EventLogSessionAuth
Signs and verifies event-log session authentication payloads.
Remote peers use this challenge-response flow to prove that they control a session signing key before sending session traffic. The signed payload includes the remote id, a short-lived challenge, the event-log public key, and the signing public key in a stable byte format.
Constants
AuthPayloadContext
Defines the domain-separation string embedded in canonical session authentication payloads.
When to use
Use when you need the domain-separation string used to build canonical event-log session authentication payloads.
Signature
declare const AuthPayloadContext: "eventlog-auth-v1"Ed25519PublicKeyLength
Defines the required byte length for raw Ed25519 public keys used in session authentication.
When to use
Use when implementing session-auth serialization or validation that must reject public keys with a non-canonical raw byte length.
Signature
declare const Ed25519PublicKeyLength: 32Ed25519SignatureLength
Defines the required byte length for Ed25519 signatures used in session authentication.
When to use
Use when implementing session-auth verification that must reject signatures with a non-canonical byte length before cryptographic checking.
Signature
declare const Ed25519SignatureLength: 64SessionAuthChallengeLength
Defines the number of random bytes generated for a session authentication challenge.
When to use
Use when you need the challenge size for event-log session authentication.
Signature
declare const SessionAuthChallengeLength: 32SessionAuthChallengeTimeToLiveMillis
Defines the time-to-live, in milliseconds, for a pending session authentication challenge.
When to use
Use when you need the timeout for pending event-log session authentication challenges.
Signature
declare const SessionAuthChallengeTimeToLiveMillis: 30000Constructors
makeSessionAuthChallenge
Generates a random session authentication challenge using globalThis.crypto.
Signature
declare const makeSessionAuthChallenge: Effect.Effect<Uint8Array<ArrayBuffer>, EventLogSessionAuthError>Encoding
decodeSessionAuthPayload
Decodes a canonical session authentication payload.
Details
The decoder validates the context field, UTF-8 fields, signing public key length, and rejects truncated or trailing bytes.
Signature
declare const decodeSessionAuthPayload: (...args: [payload: Uint8Array<ArrayBufferLike>]) => Effect<SessionAuthPayload, EventLogSessionAuthError, never>encodeSessionAuthPayload
Encodes a session authentication payload into the canonical byte format.
Details
The canonical payload format uses ordered big-endian length-prefixed fields:
- context (fixed: eventlog-auth-v1)
- remoteId
- challenge bytes
- publicKey
- signingPublicKey bytes
Signature
declare const encodeSessionAuthPayload: (...args: [payload: SessionAuthPayload]) => Effect<Uint8Array<ArrayBuffer>, EventLogSessionAuthError, never>Errors
EventLogSessionAuthError
Error raised while encoding, decoding, signing, verifying, or generating session authentication challenges.
Signature
declare class EventLogSessionAuthError extends YieldableError<this> & { readonly _tag: "EventLogSessionAuthError";} & Readonly<{ readonly cause?: unknown; readonly message: string; readonly reason: "InvalidPayload" | "InvalidContext" | "InvalidAlgorithm" | "InvalidSigningPublicKeyLength" | "InvalidSignatureLength" | "InvalidSigningPrivateKey" | "CryptoUnavailable" | "CryptoFailure";}> { constructor(args: { readonly cause?: unknown; readonly message: string; readonly reason: "InvalidPayload" | "InvalidContext" | "InvalidAlgorithm" | "InvalidSigningPublicKeyLength" | "InvalidSignatureLength" | "InvalidSigningPrivateKey" | "CryptoUnavailable" | "CryptoFailure"; });}Models
SessionAuthPayload interface
Payload fields that are canonicalized and signed during session authentication.
Signature
interface SessionAuthPayload { readonly challenge: Uint8Array; readonly publicKey: string; readonly remoteId: string | Uint8Array<ArrayBufferLike>; readonly signingPublicKey: Uint8Array;}Signing
signSessionAuthPayload
Encodes a session authentication payload in canonical form and signs it with an Ed25519 private key.
Signature
declare function signSessionAuthPayload(options: SessionAuthPayload & { readonly signingPrivateKey: Uint8Array;}): Effect<Uint8Array<ArrayBuffer>, EventLogSessionAuthError, never>signSessionAuthPayloadBytes
Creates a canonical session authentication signature with an Ed25519 private key.
Details
The private key must be PKCS#8-encoded bytes importable by SubtleCrypto.
Signature
declare const signSessionAuthPayloadBytes: (...args: [options: { readonly payload: Uint8Array; readonly signingPrivateKey: Uint8Array;}]) => Effect<Uint8Array<ArrayBuffer>, EventLogSessionAuthError, never>Verification
verifySessionAuthenticateRequest
Verifies an authentication request by requiring the Ed25519 algorithm and
checking the signature over the canonical session authentication payload.
Signature
declare const verifySessionAuthenticateRequest: (...args: [options: { readonly algorithm: string; readonly challenge: Uint8Array; readonly publicKey: string; readonly remoteId: string | Uint8Array<ArrayBufferLike>; readonly signature: Uint8Array; readonly signingPublicKey: Uint8Array;}]) => Effect<boolean, EventLogSessionAuthError, never>verifySessionAuthPayload
Encodes a session authentication payload in canonical form and verifies its Ed25519 signature.
Signature
declare function verifySessionAuthPayload(options: SessionAuthPayload & { readonly signature: Uint8Array;}): Effect<boolean, EventLogSessionAuthError, never>verifySessionAuthPayloadBytes
Verifies an Ed25519 signature for canonical session authentication payload bytes.
Details
The payload, signing public key, and signature lengths are validated before
calling SubtleCrypto.verify.
Signature
declare const verifySessionAuthPayloadBytes: (...args: [options: { readonly payload: Uint8Array; readonly signature: Uint8Array; readonly signingPublicKey: Uint8Array;}]) => Effect<boolean, EventLogSessionAuthError, never>