Skip to content
Effect V4 Docs

EventLogSessionAuth.ts

EventLogSessionAuth.ts overview

Section titled “EventLogSessionAuth.ts overview”

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.

Since v4.0.0

Exports Grouped by Category

Section titled “Exports Grouped by Category”

challenge

Section titled “challenge”

makeSessionAuthChallenge

Section titled “makeSessionAuthChallenge”

Generates a random session authentication challenge using globalThis.crypto.

Signature

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

Source

Since v4.0.0

constants

Section titled “constants”

AuthPayloadContext

Section titled “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"

Source

Since v4.0.0

Ed25519PublicKeyLength

Section titled “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

Source

Since v4.0.0

Ed25519SignatureLength

Section titled “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

Source

Since v4.0.0

SessionAuthChallengeLength

Section titled “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

Source

Since v4.0.0

SessionAuthChallengeTimeToLiveMillis

Section titled “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

Source

Since v4.0.0

encoding

Section titled “encoding”

decodeSessionAuthPayload

Section titled “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: (
  payload: Uint8Array<ArrayBufferLike>
) => Effect.Effect<SessionAuthPayload, EventLogSessionAuthError, never>

Source

Since v4.0.0

encodeSessionAuthPayload

Section titled “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: (
  payload: SessionAuthPayload
) => Effect.Effect<Uint8Array<ArrayBuffer>, EventLogSessionAuthError, never>

Source

Since v4.0.0

errors

Section titled “errors”

EventLogSessionAuthError (class)

Section titled “EventLogSessionAuthError (class)”

Error raised while encoding, decoding, signing, verifying, or generating session authentication challenges.

Signature

declare class EventLogSessionAuthError

Source

Since v4.0.0

models

Section titled “models”

SessionAuthPayload (interface)

Section titled “SessionAuthPayload (interface)”

Payload fields that are canonicalized and signed during session authentication.

Signature

export interface SessionAuthPayload {
  readonly remoteId: string | Uint8Array
  readonly challenge: Uint8Array
  readonly publicKey: string
  readonly signingPublicKey: Uint8Array
}

Source

Since v4.0.0

signing

Section titled “signing”

signSessionAuthPayload

Section titled “signSessionAuthPayload”

Encodes a session authentication payload in canonical form and signs it with an Ed25519 private key.

Signature

declare const signSessionAuthPayload: (
  options: SessionAuthPayload & { readonly signingPrivateKey: Uint8Array }
) => Effect.Effect<Uint8Array<ArrayBuffer>, EventLogSessionAuthError, never>

Source

Since v4.0.0

signSessionAuthPayloadBytes

Section titled “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: (options: {
  readonly payload: Uint8Array
  readonly signingPrivateKey: Uint8Array
}) => Effect.Effect<Uint8Array<ArrayBuffer>, EventLogSessionAuthError, never>

Source

Since v4.0.0

verification

Section titled “verification”

verifySessionAuthPayload

Section titled “verifySessionAuthPayload”

Encodes a session authentication payload in canonical form and verifies its Ed25519 signature.

Signature

declare const verifySessionAuthPayload: (
  options: SessionAuthPayload & { readonly signature: Uint8Array }
) => Effect.Effect<boolean, EventLogSessionAuthError, never>

Source

Since v4.0.0

verifySessionAuthPayloadBytes

Section titled “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: (options: {
  readonly payload: Uint8Array
  readonly signingPublicKey: Uint8Array
  readonly signature: Uint8Array
}) => Effect.Effect<boolean, EventLogSessionAuthError, never>

Source

Since v4.0.0

verifySessionAuthenticateRequest

Section titled “verifySessionAuthenticateRequest”

Verifies an authentication request by requiring the Ed25519 algorithm and checking the signature over the canonical session authentication payload.

Signature

declare const verifySessionAuthenticateRequest: (options: {
  readonly remoteId: string | Uint8Array
  readonly challenge: Uint8Array
  readonly publicKey: string
  readonly signingPublicKey: Uint8Array
  readonly signature: Uint8Array
  readonly algorithm: string
}) => Effect.Effect<boolean, EventLogSessionAuthError, never>

Source

Since v4.0.0