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
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: 32;Ed25519SignatureLength
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: 64;SessionAuthChallengeLength
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: 32;SessionAuthChallengeTimeToLiveMillis
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: 30000;Constructors
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:
1. context (fixed: eventlog-auth-v1) 2. remoteId 3. challenge bytes 4. publicKey 5. 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>;
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.