@smthrs/sync 0.0.0-stage → 1.0.0-rc.3

package/src/WorkspaceShare.ts

@@ -0,0 +1,292 @@
+/**
+ * Workspace share capabilities: the credential a sync connection presents to
+ * read the workspace's non-branch runs.
+ *
+ * The scheme extends the branch share shape rather than inventing a parallel
+ * one: a claim set and an HMAC-SHA-256 signature over its length-prefixed
+ * canonical encoding, verified with a constant-time comparison. Two things
+ * are added. A `kid` names the signing key inside the claims, so keys rotate
+ * without invalidating capabilities minted under a retired key that is still
+ * in the verification keyring. And the canonical encoding starts with a
+ * scheme label, so a workspace capability can never verify as a branch
+ * capability even if one secret is misconfigured into both authorities.
+ *
+ * Secrets enter through {@link Key} as `Redacted` values — a keyring never
+ * holds a plain string — and {@link layerConfig} provisions the keyring from
+ * configuration without any secret appearing in code.
+ *
+ * @since 0.1.0
+ */
+
+import * as Clock from "effect/Clock"
+import * as Config from "effect/Config"
+import * as Context from "effect/Context"
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+import * as Schema from "effect/Schema"
+import { Access } from "./BranchProtocol.ts"
+import * as Admission from "./internal/Admission.ts"
+import * as shareSigner from "./internal/ShareSigner.ts"
+import type { SyncError } from "./SyncError.ts"
+
+/**
+ * Schema for the claims a workspace capability carries.
+ *
+ * `kid` names the key that signed the claims and is itself signed, so a
+ * verifier both selects the right key and refuses a capability whose key
+ * name was swapped after minting.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export class WorkspaceClaims extends Schema.Class<WorkspaceClaims>("@smthrs/sync/WorkspaceShare/WorkspaceClaims")({
+  kid: Schema.NonEmptyString,
+  capabilityId: Schema.NonEmptyString,
+  access: Access,
+  issuedAtMs: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)),
+  expiresAtMs: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0))
+}) {}
+
+/**
+ * Schema for a signed, expiring, workspace-scoped capability.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export class WorkspaceCapability extends Schema.Class<WorkspaceCapability>(
+  "@smthrs/sync/WorkspaceShare/WorkspaceCapability"
+)({
+  claims: WorkspaceClaims,
+  signature: Schema.String
+}) {}
+
+/**
+ * The access one authorization request needs.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface AuthorizeRequest {
+  readonly access: Access
+}
+
+/**
+ * What a freshly minted workspace capability grants.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export const MintRequest = Schema.Struct({
+  capabilityId: Schema.NonEmptyString,
+  access: Access,
+  ttlMs: Schema.Int.check(Schema.isGreaterThan(0))
+})
+
+/**
+ * What a freshly minted workspace capability grants.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type MintRequest = typeof MintRequest.Type
+
+/**
+ * Workspace share capability operations.
+ *
+ * `mint` fails with a `SyncError` when the Web Crypto signing operation
+ * rejects; `verify` fails with a `SyncError` when signing rejects or the
+ * capability is refused.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Service {
+  readonly mint: (request: MintRequest) => Effect.Effect<WorkspaceCapability, SyncError>
+  readonly verify: (
+    capability: WorkspaceCapability,
+    request: AuthorizeRequest
+  ) => Effect.Effect<WorkspaceClaims, SyncError>
+}
+
+/**
+ * The workspace share-capability authority.
+ *
+ * @category services
+ * @since 0.1.0
+ */
+export class WorkspaceShare extends Context.Service<WorkspaceShare, Service>()("@smthrs/sync/WorkspaceShare") {}
+
+const denied = shareSigner.unauthorized
+
+/**
+ * Constructs a workspace share authority that mints nothing and trusts
+ * nothing.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const makeNoop = (overrides: Partial<Service> = {}): Service =>
+  WorkspaceShare.of({
+    // Both operations FAIL. `mint` used to die, and this is the authority the
+    // shipped CLI gateway wires, so a consumer handling `SyncError` on that
+    // composition got a crash where the type promised a refusal.
+    mint: () => Effect.fail(denied("Workspace sharing is unavailable")),
+    verify: () => Effect.fail(denied("Workspace sharing is unavailable")),
+    ...overrides
+  })
+
+/**
+ * Provides a workspace share authority that refuses every capability.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const layerNoop: Layer.Layer<WorkspaceShare> = Layer.succeed(WorkspaceShare, makeNoop())
+
+/**
+ * One named signing key. The secret is `Redacted` so a keyring never renders
+ * it into logs or inspection output.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Key = shareSigner.Key
+
+/**
+ * A keyring: the key that signs new capabilities plus every key still
+ * accepted for verification. Rotation adds a new active key and keeps the
+ * retired one in `keys` until its outstanding capabilities expire.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Keyring = shareSigner.Keyring
+
+/**
+ * Domain separation: the label leads the signed encoding, so a workspace
+ * signature can never be replayed as any other scheme's signature under a
+ * shared secret.
+ */
+const schemeLabel = "@smthrs/sync/WorkspaceShare/v1"
+
+const canonical = (claims: WorkspaceClaims): string =>
+  shareSigner.lengthPrefixed([
+    schemeLabel,
+    claims.kid,
+    claims.capabilityId,
+    claims.access,
+    String(claims.issuedAtMs),
+    String(claims.expiresAtMs)
+  ])
+
+/**
+ * The claim fields, copied out of the capability the caller owns.
+ *
+ * `Schema.Class` instances are not frozen, and `verify` awaits Web Crypto
+ * between signing the claims and authorizing them, so the checks must read a
+ * snapshot rather than an object the caller can still mutate.
+ */
+const snapshot = (claims: WorkspaceClaims): WorkspaceClaims =>
+  new WorkspaceClaims({
+    kid: claims.kid,
+    capabilityId: claims.capabilityId,
+    access: claims.access,
+    issuedAtMs: claims.issuedAtMs,
+    expiresAtMs: claims.expiresAtMs
+  })
+
+/**
+ * Constructs the HMAC-SHA-256 workspace share authority over a keyring.
+ *
+ * Every key is imported up front, so a misconfigured keyring — an unknown
+ * active kid, a duplicate kid, or a key Web Crypto refuses — fails at
+ * construction rather than at the first request.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const makeHmac = (keyring: Keyring): Effect.Effect<Service, SyncError> =>
+  Effect.map(
+    shareSigner.importKeyring(keyring, "workspace"),
+    (ring) => {
+      const mint = Effect.fn("WorkspaceShare.mint")(function*(request: MintRequest) {
+        // Decoded, not read: the declared parameter type admits an empty
+        // capability id and a `ttlMs` of 0 or NaN that the schema forbids, and
+        // reading them straight into `new WorkspaceClaims` turned a caller's
+        // bad argument into a defect out of an operation whose type promises a
+        // `SyncError`.
+        const admitted = yield* Admission.decode(MintRequest, request, "invalid_request")
+        yield* Effect.annotateCurrentSpan({ access: admitted.access })
+        const issuedAtMs = yield* Clock.currentTimeMillis
+        const claims = new WorkspaceClaims({
+          kid: ring.activeKid,
+          capabilityId: admitted.capabilityId,
+          access: admitted.access,
+          issuedAtMs,
+          expiresAtMs: issuedAtMs + admitted.ttlMs
+        })
+        return new WorkspaceCapability({
+          claims,
+          signature: yield* shareSigner.signHmac(ring.active, canonical(claims))
+        })
+      })
+
+      const verify = Effect.fn("WorkspaceShare.verify")(function*(
+        capability: WorkspaceCapability,
+        request: AuthorizeRequest
+      ) {
+        yield* Effect.annotateCurrentSpan({ access: request.access })
+        // Everything authorized below is read from these locals, never from the
+        // caller's objects, which may change while Web Crypto is awaited.
+        const claims = snapshot(capability.claims)
+        const signature = capability.signature
+        const key = ring.verification.get(claims.kid)
+        if (key === undefined) {
+          return yield* Effect.fail(denied("The workspace capability names an unknown signing key"))
+        }
+        yield* shareSigner.verifyClaims({
+          key,
+          canonical: canonical(claims),
+          signature,
+          expiresAtMs: claims.expiresAtMs,
+          granted: claims.access,
+          requested: request.access,
+          subject: "The workspace capability"
+        })
+        return claims
+      })
+
+      return WorkspaceShare.of({ mint, verify })
+    }
+  )
+
+/**
+ * Provides the HMAC-SHA-256 workspace share authority over a keyring.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const layerHmac = (keyring: Keyring): Layer.Layer<WorkspaceShare, SyncError> =>
+  Layer.effect(WorkspaceShare, makeHmac(keyring))
+
+/**
+ * Provides the workspace share authority from configuration: the secret from
+ * `SMITHERS_SYNC_SECRET` (read as `Redacted`, never logged) and the key name
+ * from `SMITHERS_SYNC_KEY_ID`, defaulting to `primary`. Rotation beyond one
+ * configured key uses {@link layerHmac} with an explicit keyring.
+ *
+ * There is deliberately no default secret: a deployment that configures
+ * neither name fails to construct the authority, and the read path stays
+ * closed.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const layerConfig: Layer.Layer<WorkspaceShare, SyncError | Config.ConfigError> = Layer.effect(
+  WorkspaceShare,
+  Effect.gen(function*() {
+    const secret = yield* Config.Redacted("SMITHERS_SYNC_SECRET")
+    const kid = yield* Config.String("SMITHERS_SYNC_KEY_ID").pipe(Config.withDefault("primary"))
+    return yield* makeHmac({ activeKid: kid, keys: [{ kid, secret }] })
+  })
+)

package/src/index.ts

@@ -0,0 +1,107 @@
+/**
+ * Read-only journal synchronization services for flows.
+ *
+ * @since 0.1.0
+ */
+
+/**
+ * @category errors
+ * @since 0.1.0
+ */
+export * as SyncError from "./SyncError.ts"
+
+/**
+ * @category protocol
+ * @since 0.1.0
+ */
+export * as SyncProtocol from "./SyncProtocol.ts"
+
+/**
+ * @category protocol
+ * @since 0.1.0
+ */
+export * as BranchProtocol from "./BranchProtocol.ts"
+
+/**
+ * @category projections
+ * @since 0.1.0
+ */
+export * as BranchProjection from "./BranchProjection.ts"
+
+/**
+ * @category rpc
+ * @since 0.1.0
+ */
+export * as SyncRpcs from "./SyncRpcs.ts"
+
+/**
+ * @category rpc
+ * @since 0.1.0
+ */
+export * as BranchRpcs from "./BranchRpcs.ts"
+
+/**
+ * @category services
+ * @since 0.1.0
+ */
+export * as RunCatalog from "./RunCatalog.ts"
+
+/**
+ * @category services
+ * @since 0.1.0
+ */
+export * as SyncServer from "./SyncServer.ts"
+
+/**
+ * @category services
+ * @since 0.1.0
+ */
+export * as SyncClient from "./SyncClient.ts"
+
+/**
+ * @category services
+ * @since 0.1.0
+ */
+export * as BranchShare from "./BranchShare.ts"
+
+/**
+ * @category services
+ * @since 0.1.0
+ */
+export * as WorkspaceShare from "./WorkspaceShare.ts"
+
+/**
+ * @category services
+ * @since 0.1.0
+ */
+export * as SyncPrincipal from "./SyncPrincipal.ts"
+
+/**
+ * @category rpc
+ * @since 0.1.0
+ */
+export * as SyncAuth from "./SyncAuth.ts"
+
+/**
+ * @category services
+ * @since 0.1.0
+ */
+export * as BranchPresence from "./BranchPresence.ts"
+
+/**
+ * @category services
+ * @since 0.1.0
+ */
+export * as BranchCommands from "./BranchCommands.ts"
+
+/**
+ * @category services
+ * @since 0.1.0
+ */
+export * as BranchServer from "./BranchServer.ts"
+
+/**
+ * @category services
+ * @since 0.1.0
+ */
+export * as BranchIds from "./BranchIds.ts"

package/src/internal/Admission.ts

@@ -0,0 +1,119 @@
+/** Admission of host and transport values before any progress is committed.
+ * @since 1.0.0-rc.0
+ */
+
+import * as JournalEvent from "@smthrs/journal/JournalEvent"
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+import { BranchId, branchOfRunId, CommandEvent, CommandEventPayload } from "../BranchProtocol.ts"
+import { SyncError } from "../SyncError.ts"
+import { causeCode } from "./CauseText.ts"
+
+/** Decode a boundary value while retaining a safe cause classification.
+ * @category validation
+ * @since 1.0.0-rc.0
+ */
+export const decode = <S extends Schema.Top & { readonly DecodingServices: never }>(
+  schema: S,
+  value: unknown,
+  code: "decode_failed" | "invalid_request" = "decode_failed"
+): Effect.Effect<S["Type"], SyncError> =>
+  Effect.try({
+    try: () => Schema.decodeUnknownSync(schema)(value),
+    catch: (cause) => new SyncError({ code, message: "Invalid sync envelope", cause: causeCode(cause) })
+  })
+
+const decodeEntries = Schema.decodeUnknownSync(Schema.Array(JournalEvent.Entry))
+const decodeJson = Schema.decodeUnknownSync(Schema.Struct({ payload: Schema.Json, meta: Schema.Json }))
+const decodeCommand = Schema.decodeUnknownSync(CommandEventPayload)
+const decodeBranch = Schema.decodeUnknownSync(Schema.Struct({ branchId: Schema.optional(BranchId) }))
+
+/** One admitted entry beside the command payload admission decoded from it.
+ * `command` is `undefined` for every event type other than `CommandEvent`.
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export interface Admitted {
+  readonly entry: JournalEvent.Entry
+  readonly command: CommandEventPayload | undefined
+}
+
+/** The one validation `records`, `withCommands`, and `entries` share. It keeps
+ * each command's decoded payload beside its entry rather than discarding it.
+ */
+const admit = (values: ReadonlyArray<JournalEvent.Entry>): Effect.Effect<ReadonlyArray<Admitted>, SyncError> =>
+  Effect.try({
+    // Capture getters once and detach nested payloads before any application
+    // callback can mutate the producer's next entry after admission.
+    try: () =>
+      decodeEntries(structuredClone(values)).map((entry): Admitted => {
+        decodeJson(entry)
+        if (entry.eventType !== CommandEvent) return { entry, command: undefined }
+        const command = decodeCommand(entry.payload)
+        const identity = decodeBranch(entry.payload)
+        if (identity.branchId !== undefined && identity.branchId !== branchOfRunId(entry.runId)) {
+          throw new SyncError({
+            code: "protocol_violation",
+            message: "Command belongs to another branch",
+            cause: "foreign_branch"
+          })
+        }
+        return { entry, command }
+      }),
+    catch: (cause) =>
+      cause instanceof SyncError
+        ? cause
+        : new SyncError({ code: "decode_failed", message: "Invalid sync record", cause: causeCode(cause) })
+  })
+
+const entriesOf = (admitted: ReadonlyArray<Admitted>): ReadonlyArray<JournalEvent.Entry> =>
+  admitted.map(({ entry }) => entry)
+
+/** Known branch records fail closed; unknown namespaces remain open JSON envelopes.
+ * Defaults on persisted command args/target keep their existing additive schema meaning.
+ * @category validation
+ * @since 1.0.0-rc.0
+ */
+export const records = (
+  values: ReadonlyArray<JournalEvent.Entry>
+): Effect.Effect<ReadonlyArray<JournalEvent.Entry>, SyncError> => Effect.map(admit(values), entriesOf)
+
+/** Admit an entire run batch before its caller publishes or updates a cursor,
+ * handing back each command beside the payload admission decoded, so a caller
+ * that needs a command field reads it instead of decoding the payload again.
+ * @category validation
+ * @since 1.0.0-rc.0
+ */
+export const withCommands = (
+  values: ReadonlyArray<JournalEvent.Entry>,
+  runId: JournalEvent.RunId,
+  after: number
+): Effect.Effect<ReadonlyArray<Admitted>, SyncError> =>
+  Effect.gen(function*() {
+    const admitted = yield* admit(values)
+    let previous = after
+    for (const { entry } of admitted) {
+      if (entry.runId !== runId || entry.seq <= previous) {
+        return yield* Effect.fail(
+          new SyncError({
+            code: "protocol_violation",
+            message: "Journal batch must belong to the requested run and ascend strictly above its cursor",
+            cause: entry.runId !== runId ? "foreign_run" : "non_monotonic_sequence"
+          })
+        )
+      }
+      previous = entry.seq
+    }
+    return admitted
+  })
+
+/** Admit an entire run batch before its caller publishes or updates a cursor.
+ * @category validation
+ * @since 1.0.0-rc.0
+ */
+export const entries = (
+  values: ReadonlyArray<JournalEvent.Entry>,
+  runId: JournalEvent.RunId,
+  after: number
+): Effect.Effect<ReadonlyArray<JournalEvent.Entry>, SyncError> =>
+  Effect.map(withCommands(values, runId, after), entriesOf)

package/src/internal/CauseText.ts

@@ -0,0 +1,74 @@
+/**
+ * How a host failure crosses the sync boundary: what a follower is told about
+ * it, and what it is not.
+ *
+ * `SyncError.cause` crosses the wire to a follower that may hold nothing but a
+ * branch share link, so it carries a short string rather than the host object
+ * that failed. An arbitrary `unknown` had three problems at once: it counted
+ * against no ceiling, a class instance or a cyclic value has no defined wire
+ * form, and whatever the host threw — a driver message with SQL text, a
+ * rejected credential — went out verbatim.
+ *
+ * @since 1.0.0-rc.0
+ */
+
+/**
+ * Longest cause rendering that crosses the wire. Long enough to name a failure
+ * and short enough that an error can never be the largest thing a follower
+ * receives.
+ */
+const maxCauseTextLength = 512
+
+/**
+ * Clamps one rendering to {@link maxCauseTextLength}.
+ *
+ * Every string this module produces leaves through here, and so does every
+ * other string a `SyncError` carries out of a host failure: `message` is
+ * `Schema.String` and is as unbounded as `cause` was.
+ *
+ * @category encoding
+ * @since 1.0.0-rc.0
+ */
+export const boundedText = (text: string): string =>
+  text.length <= maxCauseTextLength ? text : `${text.slice(0, maxCauseTextLength)} (truncated)`
+
+/**
+ * Renders one host failure as a bounded string.
+ *
+ * An `Error` renders as `name: message`; anything else renders as its type
+ * alone, because a non-`Error` value is arbitrary host data and its contents
+ * are not this boundary's to publish. Nothing is retained beyond the returned
+ * string, so an oversized input does not keep its subject alive.
+ *
+ * @category encoding
+ * @since 1.0.0-rc.0
+ */
+export const causeText = (cause: unknown): string =>
+  boundedText(
+    cause instanceof Error ? `${cause.name}: ${cause.message}` : Object.prototype.toString.call(cause)
+  )
+
+/**
+ * Renders one failure as its TYPE alone, with no message.
+ *
+ * The journal's message is the SQLite driver's, and it routinely carries SQL
+ * text, table and column names, and constraint identifiers. A follower may
+ * hold nothing but a branch share link, so what it learns about a storage
+ * fault is the stable code the journal enumerates, never the sentence the
+ * driver wrote. `decodeCapability` already refuses to be a parsing oracle;
+ * this is the same rule for the read and write paths.
+ *
+ * The result is bounded like {@link causeText}: a `Journal` is a host seam, so
+ * the `name` and `code` this reads are as much the host's to choose as the
+ * message it refuses to publish.
+ *
+ * @category encoding
+ * @since 1.0.0-rc.0
+ */
+export const causeCode = (cause: unknown): string => {
+  if (cause instanceof Error) {
+    const code = (cause as { readonly code?: unknown }).code
+    return boundedText(typeof code === "string" ? `${cause.name}(${code})` : cause.name)
+  }
+  return boundedText(Object.prototype.toString.call(cause))
+}

package/src/internal/JournalErrorCode.ts

@@ -0,0 +1,46 @@
+/**
+ * How a journal failure's stable code maps onto the sync boundary's error
+ * vocabulary.
+ *
+ * @since 1.0.0-rc.0
+ */
+
+/**
+ * The journal codes this boundary can state in its own vocabulary.
+ *
+ * Only codes whose meaning is identical on both sides are here. A journal that
+ * is shut down and a sync boundary that is closed are the same fact; an
+ * admission queue that overflowed and backpressure are the same fact; a
+ * payload the journal could not decode and one this boundary could not decode
+ * are the same fact. Everything else — a fence lost, a sequence conflict, a
+ * projection fault — is a storage-layer distinction a follower cannot act on,
+ * and inventing a sync code for it would say more than is known.
+ */
+const journalCodes: Readonly<Record<string, "backpressure" | "closed" | "decode_failed">> = {
+  decode_failed: "decode_failed",
+  journal_closed: "closed",
+  queue_overflow: "backpressure"
+}
+
+/**
+ * Projects one journal failure's stable code onto this boundary's vocabulary,
+ * or `unknown` when it has no counterpart.
+ *
+ * `SyncError.ErrorCode` already declares `closed`, `backpressure`, and
+ * `decode_failed`, so collapsing every journal failure but `compacted` into
+ * `unknown` threw away a classification the wire could already carry, and left
+ * a follower unable to tell a shut-down journal from an unexplained fault.
+ * Nothing here widens what a follower learns: `causeCode` already publishes
+ * the journal's own enumerated code, and the journal's MESSAGE stays refused
+ * on every path.
+ *
+ * @category encoding
+ * @since 1.0.0-rc.0
+ */
+export const journalErrorCode = (
+  cause: unknown
+): "backpressure" | "closed" | "decode_failed" | "unknown" => {
+  if (!(cause instanceof Error)) return "unknown"
+  const code = (cause as { readonly code?: unknown }).code
+  return typeof code === "string" ? journalCodes[code] ?? "unknown" : "unknown"
+}