@cotal-ai/auth 0.12.0 → 0.13.0

package/dist/session-ledger.d.ts

@@ -0,0 +1,224 @@
+/**
+ * The D7 SESSION production auth adapter (SPEC §13.6/§13.12): the first REAL-KV implementation
+ * of core's session seams — the {@link SessionLedger} over `session.<sessionId>` rows in the
+ * per-space auth store (`cotal_auth_<space>`, `allow_direct=false`, so every read here is
+ * leader-served by construction), and the {@link SessionRedemptionHooks} the redemption seam
+ * drives: leader-served lifecycle-gate observation, the REVISION-PINNED two-gate stage (the
+ * §13.1 fence, the same touch-CAS discipline as the D4 issuance gate: the gate write IS the
+ * fence, a moved gate makes the pinned write LOSE), deterministic per-party credential release
+ * (Ed25519 JWTs are deterministic, so the idempotent lost-response retry returns the SAME
+ * bytes with no secret stored), idempotent revocation marks, the authenticated close op, and
+ * the expiry sweep driver.
+ *
+ * Authority boundaries this module PINS (core enforces the ordering; this adapter makes it
+ * durable):
+ *  - the `issuing` create IS the one-use; a credential is authority ONLY once its row is
+ *    `active` (the connect-time session-credential arm — a named follow-up — checks the row,
+ *    and {@link retrieveServingCredential} in core already refuses non-active rows);
+ *  - the HOLDER side consumes the REAL D13 registry (SPEC §13.1): the issuance gate
+ *    `gate.<lifecycleUid>` is observed through the sealed registry, and the holder's current
+ *    process epoch is the ALIAS HEAD read (leader-served, `active`-only currency, and the
+ *    head must name the presented holder's OWN lifecycleUid — a superseded or replaced
+ *    incarnation yields no epoch);
+ *  - the SERVING side consumes the disjoint ENDPOINT gate family `epgate.<endpoint>.<instanceId>`
+ *    (SPEC §13.1: explicit prefix, never arity; the endpoint fence coordinates of §13.5/§13.7).
+ *    {@link writeEndpointGate} is the D14 endpoint-registration stand-in for provisioning and
+ *    smokes, not a public authority surface;
+ *  - the gate TOUCH preserves the value and bumps only the revision: it exists so a barrier
+ *    that moved a gate between observation and stage LOSES the race durably (§13.1: a read
+ *    is never a fence). Concurrent redemptions of the SAME lifecycle serialize on it — the
+ *    loser's grant dies (one-use, already burned), which is the fail-loud contract;
+ *  - the per-session credentials are NORMATIVE LEDGER ROWS (§13.1 closed schema, monotonic
+ *    `active → revoked`): the caller's under its holder lifecycle
+ *    (`cred.<lifecycleUid>.<sessionId>.c` — the takeover barrier enumerates and revokes it),
+ *    the serving side's under its endpoint instance
+ *    (`epcred.<endpoint>.<instanceId>.<sessionId>.s`), both with
+ *    `sourceChain: ["session.<sessionId>"]`. The IMPLEMENTATION pins the release needs (the
+ *    signing kid, its thumbprint, the party) live in `stage.session.<sessionId>.<c|s>` rows —
+ *    the `stage.` family, never under a ledger prefix a barrier enumerates (§13.1). All ids
+ *    stay DETERMINISTIC (uid/instance + sessionId + party), so a crashed redemption leaves
+ *    nothing unnameable.
+ */
+import type { KV } from "@nats-io/kv";
+import type { NatsConnection } from "@nats-io/transport-node";
+import { type CryptoKey } from "jose";
+import { type SessionLedger, type SessionRedemptionHooks, type SessionTerminalState, type EpIssuanceGate } from "@cotal-ai/core";
+import { type LifecycleRegistry, type LifecycleMappingReader } from "./lifecycle-registry.js";
+import { type AuthLedgerScanner } from "./ledger-scanner.js";
+/** The trusted per-space auth store: the KV BONDED to its space, constructed ONLY by
+ *  {@link openSessionAuthStore} (so a caller can never hand-assemble a KV with a mismatched
+ *  space, mixing space-A authority rows with space-B rails). Branded — every seam that takes a
+ *  store rejects a structural look-alike. */
+export interface SessionAuthStore {
+    kv: KV;
+    space: string;
+}
+/** Open the per-space auth store and PROVE its security-critical shape, not merely that some
+ *  bucket exists. `Kvm.open` binds lazily, so this forces the bind AND inspects the backing
+ *  stream config: the store MUST be `allow_direct=false` (every read here is an authority read
+ *  treated as leader-served by construction; a Direct-Get-capable bucket would let
+ *  release/close/connect decisions read follower-stale, §13.1), MUST carry NO age eviction
+ *  (bucket-wide OR per-message TTL — an age-evicted `session.`/gate authority key silently drops
+ *  a fence, §13.12), and MUST NOT be a mirror/sourced stream (a mirror is a follower copy). A
+ *  config-drifted bucket fails loud HERE, never at the first authority read. Returns the BRANDED
+ *  store the hooks/close/sweep seams consume. */
+export declare function openSessionAuthStore(nc: NatsConnection, space: string): Promise<SessionAuthStore>;
+/** The real-KV {@link SessionLedger}: create-only CAS for the one-use `issuing` row,
+ *  revision-pinned CAS for every transition, monotonic states enforced on the write path. */
+export declare function kvSessionLedger(kv: KV): SessionLedger;
+/** The ENDPOINT-instance issuance gate (SPEC §13.1: a DISJOINT family from the agent
+ *  `gate.<lifecycleUid>`, distinguished by explicit prefix and never token arity; carries the
+ *  endpoint fence coordinates of §13.5/§13.7). Closed schema; `frozen`/`retired` are op-bound
+ *  exactly like the agent family. */
+export interface EndpointGateRow {
+    state: "open" | "frozen" | "retired";
+    generation: number;
+    processEpoch: number;
+    registrationRevision: number;
+    nameAuthorityRevision: number;
+    /** The serving instance's CONNZ-attributable connection principal (`<owner>.<actor>`
+     *  dot-form) — the eviction target when the endpoint is taken over or a serving credential is
+     *  revoked (§13.1: eviction is BY PRINCIPAL). Recorded at endpoint registration; the serving
+     *  ledger rows (`epcred.`) copy it as their `holderPrincipal`, so the endpoint KEY identity
+     *  (`endpoint`) and the evictable principal stay disjoint. */
+    principal: string;
+    op?: {
+        opId: string;
+        kind: "activation" | "takeover" | "registration" | "retirement";
+        successor?: string;
+    };
+}
+/** The endpoint gate key `epgate.<endpoint>.<instanceId>` (an instanceId is unique ONLY within
+ *  `(space, endpoint)`, so the key is endpoint-qualified — equal instanceIds under two
+ *  endpoints never collide on the gate or the credential family, §13.1/§13.6). */
+export declare const epgateKey: (endpoint: string, instanceId: string) => string;
+/** Write an endpoint gate. This is the D14 endpoint-registration stand-in for provisioning and
+ *  smokes, NOT a production authority surface (production endpoint gates are written only by
+ *  the registration/takeover machinery with revision-pinned CAS, never an unpinned `put`). It
+ *  is deliberately NOT re-exported from the package index. */
+export declare function writeEndpointGate(kv: KV, endpoint: string, instanceId: string, gate: EndpointGateRow): Promise<void>;
+/** The durable serve-issuance gate (§13.1) over the durable endpoint families — the real-KV
+ *  implementation of core's `EpIssuanceGate` seam: core's serve mint (`mintCreds`, profile
+ *  `endpoint-serve`) fences its release on the `epgate.<endpoint>.<instanceId>` key and stages
+ *  its per-JWT row under `epcred.<endpoint>.<instanceId>.<credentialId>` — the SAME
+ *  observe/stage/commit/revoke protocol the in-memory smoke seam models, over the real KV.
+ *
+ *  NOT YET WIRED to a production mint path (fact H3): today its only caller is the session-ledger
+ *  smoke. Wiring the endpoint-family authority connection that mints serve credentials — with the
+ *  matching `epgate.>`/`epcred.>` grants, the freeze/enumerate/revoke barrier half, and
+ *  stale-credential reconnect denial — is the post-D14 daemon-composition slice; the standing
+ *  writer/barrier connections carry neither `epgate.>` nor `epcred.>` today. This module provides
+ *  the durable seam so that wiring is a composition, not a rewrite. It closes the recorded
+ *  D13/D14 durable-KEY gate (the endpoint-qualified families are normative, SPEC 13.9/13.12).
+ *
+ *  Mapping to the NORMATIVE closed row schema (§13.1): the staged row's
+ *  identity/lineage/state/exp become the CredentialLedgerRow (`lifecycleUid` is the endpoint
+ *  instance's instanceId). Its gate-coordinate fields
+ *  (generation/processEpoch/registrationRevision/nameAuthorityRevision) and the holder nkey
+ *  (`credentialKey`) are NOT persisted on the row: the closed schema refuses unknown fields,
+ *  the coordinates are pinned by the GATE key the commit CASes (one key, §13.1), and
+ *  revocation/eviction route by credentialId/holderPrincipal, never nkey. `commit` is the
+ *  pinned identical-bytes TOUCH at the observed revision — a barrier that moved the gate since
+ *  observation makes the mint LOSE, the session adapter's exact discipline.
+ *
+ *  Consumes the BRANDED {@link SessionAuthStore} ({@link openSessionAuthStore}), never a raw
+ *  `{kv, space}` pair: the space bond is constructed, not asserted, so a caller can never pair
+ *  another bucket's KV with a desired space label and fence/stage against the wrong store. */
+export declare function kvServeIssuanceGate(store: SessionAuthStore, args: {
+    endpoint: string;
+    instanceId: string;
+}): EpIssuanceGate;
+/** The adapter's signing identity for released session credentials (EdDSA/Ed25519). Determinism
+ *  is the point: Ed25519 signatures are deterministic and the payload is constructed identically
+ *  per (session, party), so the idempotent re-release returns byte-identical creds. New stages
+ *  pin `current.kid`; release resolves the PINNED kid via `resolve` (rotation-safe: a rotated
+ *  signer still reproduces the row's original bytes), returning undefined for an unknown/retired
+ *  key so a release whose signing key is gone fails loud rather than re-minting under a new key. */
+export interface SessionSigner {
+    current: {
+        kid: string;
+        key: CryptoKey;
+    };
+    resolve(kid: string): CryptoKey | undefined;
+    /** The stable public-key THUMBPRINT for a kid (RFC 7638 JWK thumbprint). Pinned in the
+     *  credential row at stage and re-checked at release, so a signer that rebinds a `kid` label
+     *  to a DIFFERENT key cannot silently re-sign a session's credential under new key material. */
+    thumbprint(kid: string): string | undefined;
+}
+export interface SessionHookDeps {
+    /** The BRANDED per-space auth store ({@link openSessionAuthStore}) — the KV bonded to its
+     *  space, so a caller cannot mix space-A authority rows with space-B rails, and the eps rails
+     *  are RE-DERIVED from the bonded space at release. */
+    store: SessionAuthStore;
+    /** The sealed D13 lifecycle registry (the SAME trusted authority; the holder-gate observe
+     *  goes through it, so the session path consumes the registry's own marker/parse discipline). */
+    registry: LifecycleRegistry;
+    /** The sealed leader-served mapping reader (the holder's current-epoch seam: the alias HEAD,
+     *  `active`-only currency, bound to the presented holder's own lifecycleUid). */
+    reader: LifecycleMappingReader;
+    signer: SessionSigner;
+    now?: () => number;
+}
+/** Build the production {@link SessionRedemptionHooks} over the branded auth store + the
+ *  sealed D13 registry/reader (both brands enforced — a hand-assembled context never
+ *  authorizes, at construction for the store/registry and at first use for the reader). */
+export declare function sessionRedemptionHooks(deps: SessionHookDeps): SessionRedemptionHooks;
+/** The authenticated presenter of a close: one of the session's two parties (their identity
+ *  established by the auth path's own context, §9/§10) or the operator. */
+export type SessionCloser = {
+    kind: "holder";
+    id: string;
+    lifecycleUid: string;
+} | {
+    kind: "serving";
+    endpoint: string;
+    instanceId: string;
+    epoch: number;
+} | {
+    kind: "operator";
+};
+/**
+ * The §13.6 authoritative close: verify party membership against the AUTHORITATIVE row (never
+ * a caller projection), transition the row terminal, and revoke BOTH credentials by name, each
+ * marked on success (the sweep's terminal-row retry backstops any failure). Idempotent for an
+ * already-terminal row (`transitioned: false`, the marks still retried).
+ */
+export declare function closeSession(store: SessionAuthStore, hooks: Pick<SessionRedemptionHooks, "ledger" | "revokeCredential">, args: {
+    sessionId: string;
+    closer: SessionCloser;
+    to?: SessionTerminalState;
+}): Promise<{
+    transitioned: boolean;
+    fullyRevoked: boolean;
+}>;
+/**
+ * The SESSION-PAIR reconciler a §13.1 lifecycle barrier injects (as
+ * `credential-ledger`'s `TakeoverDeps.reconcileSessionPair`): when a takeover or handle
+ * revocation revokes a `cred.` row whose lineage names `session.<sessionId>`, this tears down
+ * BOTH halves of that session so the SERVING half cannot outlive the barrier. It terminalizes
+ * `session.<sessionId>` as `superseded` (the barrier's own terminal reason), revokes both
+ * ledger rows (the caller `cred.` and the serving `epcred.`), and RETURNS the serving row's
+ * CONNZ-attributable holder principal so the barrier can UNION it into its verified-eviction
+ * set (SPEC 13.6: both credentials revoked WITH eviction — the row alone leaves an
+ * already-connected serving session live). Idempotent: an already-reconciled session still
+ * returns its principals (a resumed barrier must still evict); fail-closed if it cannot fully
+ * revoke both halves. The barrier only ever names a session it read from a NEVER-DELETED
+ * credential row's lineage, and session rows are never deleted either, so TRUE ABSENCE here is
+ * corruption, never "nothing to reconcile".
+ */
+export declare function reconcileSessionForTakeover(store: SessionAuthStore, hooks: Pick<SessionRedemptionHooks, "ledger" | "revokeCredential">, sessionId: string): Promise<{
+    servingPrincipals: readonly string[];
+}>;
+/** Enumerate `session.>` and run core's per-row sweep decision: expiry transitions + the
+ *  terminal-row unmarked-id revoke retry. Corruption is LOUD but LOCAL: a single malformed row
+ *  is collected and reported, never allowed to abort containment of the other valid rows (else
+ *  one poison row would block the whole bucket's expiry/revocation backstop). Returns how many
+ *  rows this pass acted on plus the keys that failed. */
+export declare function sweepSessions(store: SessionAuthStore, hooks: Pick<SessionRedemptionHooks, "ledger" | "revokeCredential">, opts: {
+    now: number;
+    marginMs?: number;
+}, scanner: AuthLedgerScanner): Promise<{
+    acted: number;
+    failed: string[];
+}>;
+//# sourceMappingURL=session-ledger.d.ts.map

package/dist/session-ledger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-ledger.d.ts","sourceRoot":"","sources":["../src/session-ledger.ts"],"names":[],"mappings":"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"}