effect 4.1.0 → 4.1.2

package/src/encoding/SchemaBinary.ts

@@ -972,6 +972,139 @@ export function fieldId(id: number) {
 
 const FIELD_ID_ANNOTATION_KEY = "~effect/encoding/SchemaBinary/fieldId"
 
+// Marks the check that opts a number or bigint into a fixed-width encoding.
+// It lives on a check, not the AST, so later annotations and checks keep it.
+const FIXED_WIDTH_ANNOTATION_KEY = "~effect/encoding/SchemaBinary/fixedWidth"
+
+type FixedWidthKind = "i32" | "u32" | "i64" | "u64"
+
+const BIGINT_I64_MIN = BigInt("-9223372036854775808")
+const BIGINT_I64_MAX = BigInt("9223372036854775807")
+const BIGINT_U64_MAX = BigInt("18446744073709551615")
+
+/**
+ * A 32-bit signed integer written as four little-endian bytes.
+ *
+ * **When to use**
+ *
+ * Use when values regularly need more than four bytes as a varint, such as
+ * hashes or full-range ids. Small values are cheaper as `Schema.Int`.
+ *
+ * **Details**
+ *
+ * Rejects non-integers and values outside -2147483648 through 2147483647
+ * instead of truncating them. `-0` is written as `0`.
+ *
+ * **Gotchas**
+ *
+ * Switching a field between this, {@link uint32}, `Schema.Number` or
+ * `Schema.Int` changes its encoding, so it is not a compatible evolution. In
+ * default mode the other reader can decode a different value without an error,
+ * for example after a signedness swap or inside an array of structs.
+ * Fingerprint mode rejects the layout mismatch.
+ *
+ * **Example** (Declaring fixed-width integer fields)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ * import { SchemaBinary } from "effect/encoding"
+ *
+ * const Packet = Schema.Struct({
+ *   version: SchemaBinary.uint32,
+ *   offset: SchemaBinary.int32,
+ *   sequence: SchemaBinary.uint64,
+ *   timestamp: SchemaBinary.int64
+ * })
+ * ```
+ *
+ * @stability unstable
+ * @category schemas
+ * @since 4.0.0
+ */
+export const int32: Schema.Number = Schema.Number.check(
+  Schema.isInt32({ [FIXED_WIDTH_ANNOTATION_KEY]: "i32" })
+)
+
+/**
+ * A 32-bit unsigned integer written as four little-endian bytes.
+ *
+ * **Details**
+ *
+ * Rejects non-integers and values outside 0 through 4294967295 instead of
+ * wrapping them. See {@link int32} for when a fixed width pays off.
+ *
+ * @stability unstable
+ * @category schemas
+ * @since 4.0.0
+ */
+export const uint32: Schema.Number = Schema.Number.check(
+  Schema.isUint32({ [FIXED_WIDTH_ANNOTATION_KEY]: "u32" })
+)
+
+/**
+ * A 64-bit signed integer, as a `bigint`, written as eight little-endian bytes.
+ *
+ * **Details**
+ *
+ * Rejects values outside -2^63 through 2^63 - 1 instead of wrapping them. As a
+ * struct field it costs one length byte more than the payload, because the
+ * eight-byte field kind belongs to floating-point numbers.
+ *
+ * **Gotchas**
+ *
+ * Switching a field between this, {@link uint64} or `Schema.BigInt` is not a
+ * compatible evolution. All three are length-prefixed struct fields, and eight
+ * bytes can be valid for each, so a default-mode reader may decode the other
+ * form as a different value without an error. Fingerprint mode rejects the
+ * layout mismatch.
+ *
+ * @stability unstable
+ * @category schemas
+ * @since 4.0.0
+ */
+export const int64: Schema.BigInt = Schema.BigInt.check(
+  Schema.isBetweenBigInt({ minimum: BIGINT_I64_MIN, maximum: BIGINT_I64_MAX }, {
+    expected: "a 64-bit integer",
+    [FIXED_WIDTH_ANNOTATION_KEY]: "i64"
+  })
+)
+
+/**
+ * A 64-bit unsigned integer, as a `bigint`, written as eight little-endian
+ * bytes.
+ *
+ * **Details**
+ *
+ * Rejects values outside 0 through 2^64 - 1 instead of wrapping them. See
+ * {@link int64} for the struct field cost.
+ *
+ * **Gotchas**
+ *
+ * Switching a field between this, {@link int64} or `Schema.BigInt` can decode
+ * as a different value without an error in default mode; see {@link int64}.
+ *
+ * @stability unstable
+ * @category schemas
+ * @since 4.0.0
+ */
+export const uint64: Schema.BigInt = Schema.BigInt.check(
+  Schema.isBetweenBigInt({ minimum: BigInt(0), maximum: BIGINT_U64_MAX }, {
+    expected: "a 64-bit unsigned integer",
+    [FIXED_WIDTH_ANNOTATION_KEY]: "u64"
+  })
+)
+
+// The fixed width the schema opted into, from any of its checks.
+function fixedWidthKind(ast: SchemaAST.AST): FixedWidthKind | undefined {
+  const checks = ast.checks
+  if (checks === undefined) return undefined
+  for (const check of checks) {
+    const kind = check.annotations?.[FIXED_WIDTH_ANNOTATION_KEY]
+    if (kind !== undefined) return kind as FixedWidthKind
+  }
+  return undefined
+}
+
 // Bit 0 selects fingerprint mode; all other flag bits are reserved.
 const ENVELOPE = 0x20 // version nibble 2, flags 0
 const ENVELOPE_FINGERPRINT = 0x21 // version nibble 2, flag bit 0
@@ -1370,6 +1503,11 @@ class Writer {
     this.view.setBigInt64(this.start + this.len, n, true)
     this.len += 8
   }
+  u64(n: bigint) {
+    this.ensure(8)
+    this.view.setBigUint64(this.start + this.len, n, true)
+    this.len += 8
+  }
   u32le(n: number) {
     this.ensure(4)
     this.view.setUint32(this.start + this.len, n >>> 0, true)
@@ -1801,6 +1939,12 @@ class Reader {
     this.pos += 8
     return value
   }
+  u64(): bigint {
+    if (this.pos + 8 > this.end) invalid("complete value", undefined, this.options)
+    const value = (this.view ?? this.dataView()).getBigUint64(this.pos, true)
+    this.pos += 8
+    return value
+  }
   u32le(): number {
     if (this.pos + 4 > this.end) invalid("complete value", undefined, this.options)
     const value = (this.view ?? this.dataView()).getUint32(this.pos, true)
@@ -1825,6 +1969,7 @@ type LeafKind =
   | "symbol"
   | "bytes"
   | "bigint"
+  | FixedWidthKind
   | "json"
   | "duration"
   | "bigDecimal"
@@ -2007,7 +2152,12 @@ function packedSize(layout: Layout): number | undefined {
       return packedSize(layout.leaf)
     case "bool":
       return 1
+    case "i32":
+    case "u32":
+      return 4
     case "int64":
+    case "i64":
+    case "u64":
       return 8
     default:
       return undefined
@@ -2318,10 +2468,15 @@ function compileLayout(root: SchemaAST.AST): CompiledLayout {
       case "Undefined":
       case "Void":
         return leaf("undefined")
-      case "Number":
+      case "Number": {
+        const fixed = fixedWidthKind(ast)
+        if (fixed === "i32" || fixed === "u32") return leaf(fixed)
         return leaf(provesInteger(ast) ? "int" : "number")
-      case "BigInt":
-        return leaf("bigint")
+      }
+      case "BigInt": {
+        const fixed = fixedWidthKind(ast)
+        return leaf(fixed === "i64" || fixed === "u64" ? fixed : "bigint")
+      }
       case "Literal":
         return literalLayout(leaf(literalKind(ast.literal)), [ast.literal])
       case "Unknown":
@@ -2685,7 +2840,7 @@ function isExact(root: SchemaAST.AST): boolean {
   const walked = new Map<SchemaAST.AST, boolean>()
   const exact = (ast: SchemaAST.AST): boolean => {
     if (
-      ast.encoding !== undefined || ast.checks !== undefined ||
+      ast.encoding !== undefined || (ast.checks !== undefined && !isFixedWidthOnly(ast)) ||
       (ast as { readonly encodingChecks?: SchemaAST.Checks }).encodingChecks !== undefined
     ) {
       return false
@@ -2746,6 +2901,13 @@ function isExact(root: SchemaAST.AST): boolean {
   return exact(root)
 }
 
+// The binary layer enforces a fixed-width check on its own, so it is exact
+// when no other check rides along.
+function isFixedWidthOnly(ast: SchemaAST.AST): boolean {
+  return (ast._tag === "Number" || ast._tag === "BigInt") && ast.checks?.length === 1 &&
+    fixedWidthKind(ast) !== undefined
+}
+
 // A clean Exit whose success schema is exact: the binary layer fully produces
 // and validates success exits, so only failure exits need the schema pass for
 // their cause's error and defect encodings.
@@ -2784,7 +2946,11 @@ const F = {
   exit: 22,
   cause: 23,
   causeReason: 24,
-  literal: 25
+  literal: 25,
+  i32: 26,
+  u32: 27,
+  i64: 28,
+  u64: 29
 } as const
 
 // Hash the compiled layout graph, including cycle back-edge distances.
@@ -2828,6 +2994,10 @@ function layoutFingerprint(root: Layout): bigint {
       case "symbol":
       case "bytes":
       case "bigint":
+      case "i32":
+      case "u32":
+      case "i64":
+      case "u64":
       case "json":
       case "duration":
       case "bigDecimal":
@@ -2986,12 +3156,16 @@ function matchesLayout(layout: Layout, value: unknown): boolean {
       return value === undefined
     case "number":
     case "int":
+    case "i32":
+    case "u32":
       return typeof value === "number"
     case "string":
       return typeof value === "string"
     case "symbol":
       return typeof value === "symbol"
     case "bigint":
+    case "i64":
+    case "u64":
       return typeof value === "bigint"
     case "bytes":
       return value instanceof Uint8Array
@@ -3287,6 +3461,10 @@ function valueWireCode(layout: Layout, value: unknown, options: SchemaAST.ParseO
     case "int":
       if (!Number.isSafeInteger(value)) encodeFail("an integer", value, options)
       return FIELD_WIRE_VARINT
+    // The payload write validates the value.
+    case "i32":
+    case "u32":
+      return FIELD_WIRE_FIXED32
     default:
       return FIELD_WIRE_SIZED
   }
@@ -3295,8 +3473,8 @@ function valueWireCode(layout: Layout, value: unknown, options: SchemaAST.ParseO
 function encodeWirePayload(ctx: EncodeContext, layout: Layout, value: unknown, wire: number, w: Writer) {
   const kind = wire % FIELD_WIRE_FACTOR
   switch (kind) {
-    // EMPTY and FIXED32 are decoder-side skip support only; `valueWireCode`
-    // never produces them.
+    // EMPTY is decoder-side skip support only; `valueWireCode` never produces
+    // it.
     case FIELD_WIRE_FALSE:
     case FIELD_WIRE_TRUE:
       return
@@ -3306,6 +3484,9 @@ function encodeWirePayload(ctx: EncodeContext, layout: Layout, value: unknown, w
     case FIELD_WIRE_FIXED64:
       w.f64(value as number)
       return
+    case FIELD_WIRE_FIXED32:
+      encodeValue(ctx, layout, value, w)
+      return
     case FIELD_WIRE_DECIMAL: {
       const scale = Math.floor(wire / FIELD_WIRE_FACTOR)
       w.numberVarint(Math.round((value as number) * POW10[scale]))
@@ -4010,6 +4191,29 @@ function encodeValue(ctx: EncodeContext, layout: Layout, value: unknown, w: Writ
       if (typeof value !== "bigint") encodeFail("a bigint", value, ctx.options)
       w.zigzag(value)
       return
+    // `disableChecks` can bypass the range check used to select these layouts.
+    case "i32":
+      if (typeof value !== "number" || (value | 0) !== value) encodeFail("a 32-bit integer", value, ctx.options)
+      w.i32le(value)
+      return
+    case "u32":
+      if (typeof value !== "number" || value >>> 0 !== value) {
+        encodeFail("a 32-bit unsigned integer", value, ctx.options)
+      }
+      w.u32le(value)
+      return
+    case "i64":
+      if (typeof value !== "bigint" || value < BIGINT_I64_MIN || value > BIGINT_I64_MAX) {
+        encodeFail("a 64-bit integer", value, ctx.options)
+      }
+      w.i64(value)
+      return
+    case "u64":
+      if (typeof value !== "bigint" || value < BIGINT_ZERO || value > BIGINT_U64_MAX) {
+        encodeFail("a 64-bit unsigned integer", value, ctx.options)
+      }
+      w.u64(value)
+      return
     case "int64": {
       if (!matchesLayout(layout, value)) {
         encodeFail(layout.flavor === "date" ? "a Date" : "a DateTime.Utc", value, ctx.options)
@@ -4375,6 +4579,9 @@ function fieldWireMask(layout: Layout): number {
       return (1 << FIELD_WIRE_VARINT) | (1 << FIELD_WIRE_FIXED64) | (1 << FIELD_WIRE_DECIMAL)
     case "int":
       return 1 << FIELD_WIRE_VARINT
+    case "i32":
+    case "u32":
+      return 1 << FIELD_WIRE_FIXED32
     default:
       return 1 << FIELD_WIRE_SIZED
   }
@@ -4406,6 +4613,8 @@ function decodeFieldPayload(layout: Layout, wireMask: number, kind: number, r: R
     skipFieldPayload(kind, r)
     return ABSENT
   }
+  // Only the two 32-bit layouts accept this kind, so the payload needs no window.
+  if (kind === FIELD_WIRE_FIXED32) return layout._ === "u32" ? r.u32le() : r.i32le()
   if (kind !== FIELD_WIRE_SIZED) {
     const value = decodeScalarField(kind, r)
     if (layout._ === "literal" && !hasLiteral(layout, value)) {
@@ -4993,6 +5202,18 @@ function decodeValueUnchecked(layout: Layout, r: Reader): unknown {
       return r.takeCopy(r.end - r.pos)
     case "bigint":
       return r.zigzag()
+    case "i32":
+      if (r.remaining !== 4) invalid("a 32-bit integer", undefined, r.options)
+      return r.i32le()
+    case "u32":
+      if (r.remaining !== 4) invalid("a 32-bit unsigned integer", undefined, r.options)
+      return r.u32le()
+    case "i64":
+      if (r.remaining !== 8) invalid("a 64-bit integer", undefined, r.options)
+      return r.i64()
+    case "u64":
+      if (r.remaining !== 8) invalid("a 64-bit unsigned integer", undefined, r.options)
+      return r.u64()
     case "int64": {
       if (r.remaining !== 8) invalid("int64", undefined, r.options)
       const millis = Number(r.i64())

package/src/encoding/Sse.ts

@@ -667,7 +667,9 @@ export type AnyEvent = Event | Retry
  * **Details**
  *
  * It renders `Event` values as `id`, `event`, and `data` lines and renders
- * `Retry` values as `retry:` directives.
+ * `Retry` values as `retry:` directives. CR and LF are removed from `id` and
+ * `event`, and NUL is removed from `id`, so those values cannot inject fields
+ * or events.
  *
  * @stability unstable
  * @category encoding
@@ -679,10 +681,10 @@ export const encoder: Encoder = {
       case "Event": {
         let data = ""
         if (event.id !== undefined) {
-          data += `id: ${event.id}\n`
+          data += `id: ${event.id.replace(/[\r\n\0]/g, "")}\n`
         }
         if (event.event !== "message") {
-          data += `event: ${event.event}\n`
+          data += `event: ${event.event.replace(/[\r\n]/g, "")}\n`
         }
         data += `data: ${event.data.replace(/\r\n|\r|\n/g, "\ndata: ")}\n`
         return data + "\n"

package/src/encoding/index.ts

@@ -41,12 +41,24 @@ export * as Hex from "./Hex.ts"
  */
 export * as Ini from "./Ini.ts"
 
+/**
+ * @stability unstable
+ * @since 4.1.2
+ */
+export * as Json5 from "./Json5.ts"
+
 /**
  * @stability unstable
  * @since 4.0.6
  */
 export * as JsonArray from "./JsonArray.ts"
 
+/**
+ * @stability unstable
+ * @since 4.1.2
+ */
+export * as Jsonc from "./Jsonc.ts"
+
 /**
  * @stability unstable
  * @since 4.0.0

package/src/eventlog/EventLog.ts

@@ -303,6 +303,13 @@ export const layerRegistry = Layer.effect(
  * The identity is used by remote replication for authentication and by the
  * encryption service to derive signing and encryption keys.
  *
+ * **Gotchas**
+ *
+ * `publicKey` identifies the identity but is not a secret, and nothing ties it
+ * to the signing key derived from `privateKey`. A server binds the first
+ * signing key that authenticates for a `publicKey`, unless its authorization
+ * checks the presented signing key.
+ *
  * @stability unstable
  * @category services
  * @since 4.0.0

package/src/eventlog/EventLogServer.ts

@@ -12,7 +12,9 @@
 import type { NonEmptyReadonlyArray } from "../Array.ts"
 import * as Arr from "../Array.ts"
 import * as Cache from "../Cache.ts"
+import * as Clock from "../Clock.ts"
 import * as Context from "../Context.ts"
+import * as Mac from "../crypto/Mac.ts"
 import * as Data from "../Data.ts"
 import * as Duration from "../Duration.ts"
 import * as Effect from "../Effect.ts"
@@ -21,7 +23,6 @@ import * as Exit from "../Exit.ts"
 import * as Hash from "../Hash.ts"
 import * as Uuid from "../internal/uuid.ts"
 import * as Layer from "../Layer.ts"
-import * as Option from "../Option.ts"
 import * as Redacted from "../Redacted.ts"
 import type * as Rpc from "../rpc/Rpc.ts"
 import type * as RpcGroup from "../rpc/RpcGroup.ts"
@@ -76,6 +77,12 @@ export const layerAuthMiddleware: Layer.Layer<
  * chunked writes, delegates write and change handling to the supplied callbacks,
  * and frames large change payloads into chunks.
  *
+ * `Authenticate` calls `authorizeIdentity` with the claimed public key and the
+ * presented signing public key, then verifies the signature against the
+ * presented key. Only a verified key is passed to
+ * `getOrCreateSessionAuthBinding`, and a key that differs from the identity's
+ * existing binding is rejected.
+ *
  * Use the connection's `ConnectionWrites.track` in `onWrite` and
  * `ConnectionWrites.filter` in `changes` to suppress its own write echoes.
  * `compaction` sets `HelloResponse.compaction`, advertising that the server
@@ -89,7 +96,10 @@ export const layerRpcHandlers = (options: {
   readonly remoteId: RemoteId
   readonly firstSequence?: number | undefined
   readonly compaction?: boolean | undefined
-  readonly authorizeIdentity?: (publicKey: string) => Effect.Effect<void, EventLogProtocolError>
+  readonly authorizeIdentity?: (
+    publicKey: string,
+    signingPublicKey: Uint8Array<ArrayBuffer>
+  ) => Effect.Effect<void, EventLogProtocolError>
   readonly getOrCreateSessionAuthBinding: (
     publicKey: string,
     signingPublicKey: Uint8Array<ArrayBuffer>
@@ -109,11 +119,6 @@ export const layerRpcHandlers = (options: {
   Rpc.ToHandler<RpcGroup.Rpcs<typeof EventLogRemoteRpcs>> | EventLogAuthentication
 > =>
   EventLogRemoteRpcs.toLayer(Effect.gen(function*() {
-    const clientChallenges = yield* Cache.make({
-      lookup: (_clientId: number) => Effect.orDie(EventLogSessionAuth.makeSessionAuthChallenge),
-      capacity: Number.MAX_SAFE_INTEGER,
-      timeToLive: EventLogSessionAuth.SessionAuthChallengeTimeToLiveMillis
-    })
     const toFrames = makeFramer()
 
     const persistedSigningPublicKeys = yield* Cache.makeWith(
@@ -138,17 +143,31 @@ export const layerRpcHandlers = (options: {
 
     return EventLogRemoteRpcs.of({
       "EventLog.Hello": Effect.fnUntraced(function*(_, { client }) {
-        const challenge = yield* Cache.get(clientChallenges, client.id)
+        // Kept on the connection, so it is released when the client disconnects
+        // and shared by overlapping Hellos until `Authenticate` consumes it.
+        let pending = getPendingChallenge(client, yield* Clock.currentTimeMillis)
+        if (pending === undefined) {
+          const challenge = yield* Effect.orDie(EventLogSessionAuth.makeSessionAuthChallenge)
+          // Read the clock again, as generating the challenge can suspend. A
+          // concurrent Hello may have stored a challenge in the meantime.
+          const now = yield* Clock.currentTimeMillis
+          pending = getPendingChallenge(client, now) ?? {
+            challenge,
+            expiresAt: now + EventLogSessionAuth.SessionAuthChallengeTimeToLiveMillis
+          }
+          client.annotate(PendingChallenge, pending)
+        }
         return new HelloResponse({
           remoteId: options.remoteId,
-          challenge,
+          challenge: pending.challenge,
           firstSequence: options.firstSequence,
           compaction: options.compaction === true ? true : undefined
         })
       }),
       "EventLog.Authenticate": Effect.fnUntraced(function*(request, { client }) {
-        const challenge = Option.getOrNull(yield* Cache.getOption(clientChallenges, client.id))
-        if (!challenge) {
+        const pending = getPendingChallenge(client, yield* Clock.currentTimeMillis)
+        client.annotate(PendingChallenge, undefined)
+        if (pending === undefined) {
           return yield* new EventLogProtocolError({
             requestTag: "Authenticate",
             publicKey: request.publicKey,
@@ -156,35 +175,41 @@ export const layerRpcHandlers = (options: {
             message: "Session auth challenge has expired"
           })
         }
-        yield* Cache.invalidate(clientChallenges, client.id)
         if (options.authorizeIdentity) {
-          yield* options.authorizeIdentity(request.publicKey)
+          yield* options.authorizeIdentity(request.publicKey, request.signingPublicKey)
         }
-        const signingPublicKey = yield* Cache.get(
-          persistedSigningPublicKeys,
-          new SessionAuthCacheKey({
-            publicKey: request.publicKey,
-            signingPublicKey: request.signingPublicKey
-          })
-        )
         const verified = yield* EventLogSessionAuth.verifySessionAuthenticateRequest({
           remoteId: options.remoteId,
-          challenge,
+          challenge: pending.challenge,
           publicKey: request.publicKey,
-          signingPublicKey,
+          signingPublicKey: request.signingPublicKey,
           signature: request.signature,
           algorithm: request.algorithm
         }).pipe(
           Effect.catch(() => Effect.succeed(false))
         )
 
-        if (!verified) {
-          return yield* new EventLogProtocolError({
+        const verificationFailed = () =>
+          new EventLogProtocolError({
             requestTag: "Authenticate",
             publicKey: request.publicKey,
             code: "Forbidden",
             message: "Session auth signature verification failed"
           })
+        if (!verified) {
+          return yield* verificationFailed()
+        }
+        // Only a verified key reaches the binding. A key other than the
+        // identity's bound key is rejected like a bad signature.
+        const boundSigningPublicKey = yield* Cache.get(
+          persistedSigningPublicKeys,
+          new SessionAuthCacheKey({
+            publicKey: request.publicKey,
+            signingPublicKey: request.signingPublicKey
+          })
+        )
+        if (!Mac.timingSafeEqual(boundSigningPublicKey, request.signingPublicKey)) {
+          return yield* verificationFailed()
         }
 
         const authenticatedIdentities = new Set(
@@ -392,6 +417,22 @@ class ConnectionWritesState extends Context.Service<ConnectionWritesState, Conne
   "effect/eventlog/EventLogServer/ConnectionWrites"
 ) {}
 
+// The connection's unconsumed `Hello` challenge, cleared by `Authenticate`.
+const PendingChallenge = Context.Reference<
+  | {
+    readonly challenge: Uint8Array<ArrayBuffer>
+    readonly expiresAt: number
+  }
+  | undefined
+>("effect/eventlog/EventLogServer/PendingChallenge", {
+  defaultValue: () => undefined
+})
+
+const getPendingChallenge = (client: Rpc.ServerClient, now: number) => {
+  const pending = Context.get(client.annotations, PendingChallenge)
+  return pending !== undefined && pending.expiresAt > now ? pending : undefined
+}
+
 const getConnectionWrites = (client: Rpc.ServerClient): ConnectionWrites => {
   const existing = Context.getOrUndefined(client.annotations, ConnectionWritesState)
   if (existing !== undefined) return existing
@@ -411,6 +452,8 @@ export class AuthenticatedIdentities extends Context.Service<AuthenticatedIdenti
   "effect/eventlog/EventLogServer/AuthenticatedIdentities"
 ) {}
 
+// Keyed by `publicKey` alone: the cache holds each identity's bound signing
+// key, and `Authenticate` rejects any presented key that differs from it.
 class SessionAuthCacheKey extends Data.Class<{
   readonly publicKey: string
   readonly signingPublicKey: Uint8Array<ArrayBuffer>

package/src/eventlog/EventLogServerEncrypted.ts

@@ -503,6 +503,11 @@ export class Storage extends Context.Service<Storage, {
    * Lowest assigned sequence (default 0). Overestimating skips entries.
    */
   readonly firstSequence?: number | undefined
+  /**
+   * Returns the signing key bound to `publicKey`, binding `signingPublicKey`
+   * when none is bound yet. The server only passes keys whose signature it
+   * has verified, and rejects a key that differs from the returned binding.
+   */
   readonly getOrCreateSessionAuthBinding: (
     publicKey: string,
     signingPublicKey: Uint8Array<ArrayBuffer>

package/src/eventlog/EventLogServerUnencrypted.ts

@@ -165,8 +165,8 @@ export const layerRpcHandlers: Layer.Layer<
   return EventLogServer.layerRpcHandlers({
     remoteId,
     firstSequence: storage.firstSequence,
-    authorizeIdentity: (publicKey) =>
-      auth.authorizeIdentity({ publicKey }).pipe(
+    authorizeIdentity: (publicKey, signingPublicKey) =>
+      auth.authorizeIdentity({ publicKey, signingPublicKey }).pipe(
         Effect.mapError((error) =>
           new EventLogProtocolError({
             requestTag: "Authenticate",
@@ -318,6 +318,17 @@ export class EventLogServerAuthError extends Data.TaggedError("EventLogServerAut
  * Use to provide authorization checks for plaintext event-log writes, reads,
  * and identity authentication.
  *
+ * **Gotchas**
+ *
+ * An identity's `publicKey` is an identifier, not a secret. The server binds
+ * the first signing key that authenticates for an identity and rejects any
+ * other key afterwards. `authorizeIdentity` also receives the presented
+ * `signingPublicKey`, so a deployment that records each identity's signing key
+ * at provisioning time, with `EventLogSessionAuth.deriveSigningPublicKey`, can
+ * reject every other key, including on first use. The server always supplies
+ * `signingPublicKey`; it is optional only so that existing callers keep
+ * compiling, and a policy that checks it should reject when it is missing.
+ *
  * @stability unstable
  * @category services
  * @since 4.0.0
@@ -334,6 +345,7 @@ export class EventLogServerAuthorization extends Context.Service<EventLogServerA
   }) => Effect.Effect<void, EventLogServerAuthError>
   readonly authorizeIdentity: (options: {
     readonly publicKey: string
+    readonly signingPublicKey?: Uint8Array<ArrayBuffer> | undefined
   }) => Effect.Effect<void, EventLogServerAuthError>
 }>()("effect/eventlog/EventLogServerUnencrypted/EventLogServerAuthorization") {}
 
@@ -422,6 +434,11 @@ export class Storage extends Context.Service<Storage, {
    * Lowest assigned sequence (default 0). Overestimating skips entries.
    */
   readonly firstSequence?: number | undefined
+  /**
+   * Returns the signing key bound to `publicKey`, binding `signingPublicKey`
+   * when none is bound yet. The server only passes keys whose signature it
+   * has verified, and rejects a key that differs from the returned binding.
+   */
   readonly getOrCreateSessionAuthBinding: (
     publicKey: string,
     signingPublicKey: Uint8Array<ArrayBuffer>