EventLogSessionAuth unstable

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.

16 exports Since v4.0.0 Source

Constants

AuthPayloadContext

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

Generates a random session authentication challenge from SecureRandom on the WebCrypto reference.

Signature

declare const makeSessionAuthChallenge: Effect.Effect<Uint8Array<ArrayBuffer>, EventLogSessionAuthError>

Encoding

decodeSessionAuthPayload

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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 unstable

Since v4.0.0

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

deriveSigningPublicKey

unstable

Since v4.1.1

Derives the Ed25519 signing public key an identity presents during session authentication.

When to use

Use when provisioning an identity to record its signing key, so that server authorization can reject any other key presented for the identity's publicKey.

Details

The key is derived from the identity's private key on the WebCrypto reference.

Signature

declare function deriveSigningPublicKey(identity: {
  readonly privateKey: Redacted<Uint8Array<ArrayBuffer>>;
  readonly publicKey: string;
}): Effect<Uint8Array<ArrayBuffer>>

signSessionAuthPayload

unstable

Since v4.0.0

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

unstable

Since v4.0.0

Creates a canonical session authentication signature with an Ed25519 private key.

Details

The private key must be PKCS#8-encoded Ed25519 bytes. Signing runs on Signature.layerWebCrypto with the WebCrypto reference.

Signature

declare const signSessionAuthPayloadBytes: (...args: [options: {
  readonly payload: Uint8Array;
  readonly signingPrivateKey: Uint8Array;
}]) => Effect<Uint8Array<ArrayBuffer>, EventLogSessionAuthError, never>

Verification

verifySessionAuthenticateRequest

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

Verifies an Ed25519 signature for canonical session authentication payload bytes.

Details

The payload, signing public key, and signature lengths are validated before verifying on Signature.layerWebCrypto with the WebCrypto reference.

Signature

declare const verifySessionAuthPayloadBytes: (...args: [options: {
  readonly payload: Uint8Array;
  readonly signature: Uint8Array;
  readonly signingPublicKey: Uint8Array;
}]) => Effect<boolean, EventLogSessionAuthError, never>