@salamandradevs/core 0.1.3 → 0.2.0

package/types/keys/openbao/openbao-keys-provider.d.ts

@@ -0,0 +1,175 @@
+import type { CryptoKey } from 'jose';
+import type { IKeysProvider } from '../contracts.js';
+import type { PublicJwk, SigningKeyHandle } from '../types.js';
+import type { OpenBaoSigningKeysConfig } from './types.js';
+/**
+ * Durable OpenBao-backed keys provider that signs with Transit and verifies locally.
+ *
+ * @remarks
+ * Private signing keys never enter this process. OpenBao holds the private material and
+ * performs signatures; the signing keys document records which key is active and which
+ * retired keys are still verifiable. An operator owns that document and the signing keys it
+ * names.
+ *
+ * It hands a consumer a signer bound to the active key, resolves a public key by `kid` for
+ * verification, and lists the public keys eligible for JWKS publication. Its token needs
+ * only `read` on the document path and `update` on the signing path; see
+ * `docs/en/howto/openbao/README.md` for how keys are provisioned and rotated.
+ *
+ * Operationally: every signature costs one OpenBao call, so an unreachable or sealed
+ * OpenBao stops all issuance. Verification of already-signed credentials is served from the
+ * in-process snapshot with no network call, so they survive an outage that blocks new
+ * ones.
+ * @group Keys
+ * @category Key Providers
+ */
+export declare class OpenBaoKeysProvider implements IKeysProvider {
+    private readonly config;
+    private readonly algorithm;
+    private readonly refreshCooldownSecs;
+    /** Last validated signing key state, projected for verification and JWKS reads. */
+    private snapshot;
+    /** Single-flight wrapper over refreshSnapshot; concurrent callers share one document read. */
+    private readonly synchronize;
+    /** OpenBao origin read from `BAO_ADDR`. */
+    private readonly baseUrl;
+    /** Runtime OpenBao token read from `BAO_TOKEN`. */
+    private readonly token;
+    /**
+     * @param config - Validated OpenBao key namespace and request policy configuration.
+     * @param algorithm - JOSE algorithm enforced for all signing keys.
+     * @param refreshCooldownSecs - Minimum time between two re-reads of the lifecycle
+     *   document triggered by an unknown `kid`; it bounds how often a verification miss may
+     *   synchronize the snapshot from OpenBao.
+     * @throws {CustomError} ENV_VAR_ERROR when `BAO_ADDR` or `BAO_TOKEN` is missing, blank,
+     *   or malformed.
+     */
+    constructor(config: OpenBaoSigningKeysConfig, algorithm: 'ES256', refreshCooldownSecs: number);
+    /**
+     * Loads the signing keys document and publishes the first snapshot.
+     *
+     * @group Keys
+     * @category Key Providers
+     * @returns Completed provider initialization.
+     * @throws {CustomError} KEYS_PROVIDER_ERROR when no signing keys document exists or it
+     *   violates its invariants.
+     * @throws {CustomError} EXTERNAL_API_ERROR when OpenBao is unreachable or answers
+     *   unusably.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Selects the active key and returns a signer bound to that key.
+     *
+     * @group Keys
+     * @category Key Providers
+     * @returns Provider-neutral signing capability.
+     * @throws {CustomError} KEYS_PROVIDER_ERROR when durable state has no usable active key.
+     */
+    getCurrentSigner(): Promise<SigningKeyHandle>;
+    /**
+     * Resolves one eligible public key by exact key identifier.
+     *
+     * @group Keys
+     * @category Key Providers
+     * @param kid - Key identifier carried with the signature.
+     * @returns Public verification key, or null for an unknown or expired key.
+     * @throws {CustomError} EXTERNAL_API_ERROR when a synchronize is due but OpenBao prevents
+     *   it, so an outage is never reported as an unknown key.
+     */
+    getPublicKey(kid: string): Promise<CryptoKey | null>;
+    /**
+     * Synchronizes, then lists the keys currently eligible for JWKS publication.
+     *
+     * @group Keys
+     * @category Key Providers
+     * @returns Retained public JSON Web Keys.
+     * @throws {CustomError} EXTERNAL_API_ERROR when OpenBao prevents the synchronize, so a
+     *   stale snapshot is never served as though it had succeeded.
+     */
+    listPublicKeys(): Promise<readonly PublicJwk[]>;
+    /**
+     * Returns the published snapshot, synchronizing once if none has been built yet.
+     *
+     * @returns The most recently published projection of durable signing key state.
+     * @throws {CustomError} KEYS_PROVIDER_ERROR when a synchronize completed without
+     *   publishing.
+     */
+    private currentSnapshot;
+    /**
+     * Reads the signing keys document and rebuilds the published snapshot; the work each
+     * synchronize performs.
+     *
+     * @returns Completed synchronize with a freshly published snapshot.
+     * @throws {CustomError} KEYS_PROVIDER_ERROR when no signing keys document exists.
+     */
+    private refreshSnapshot;
+    /**
+     * Signs one exact JWS signing input with a captured signing key.
+     *
+     * @param providerKeyId - Signing key name captured when the signer was selected.
+     * @param input - Exact JWS signing input bytes to sign.
+     * @returns Raw 64-byte ES256 signature.
+     * @throws {CustomError} EXTERNAL_API_ERROR when OpenBao signs with an unpublished version
+     *   or returns a signature of the wrong length.
+     */
+    private signWithTransit;
+    /**
+     * Reads and validates the signing keys document, or reports its absence.
+     *
+     * @returns Validated state, or null when no document exists.
+     * @throws {CustomError} KEYS_PROVIDER_ERROR when the document exists but is not a signing
+     *   keys document, or violates a signing key invariant.
+     */
+    private readSigningKeyState;
+    /**
+     * Projects validated state into the in-memory snapshot that serves verification and JWKS.
+     *
+     * @param state - Validated signing key state to project.
+     * @returns Completed snapshot publication.
+     * @throws {CustomError} KEYS_PROVIDER_ERROR when an entry holds a non-public JWK.
+     */
+    private publishSnapshot;
+    /**
+     * Parses a Transit sign response into the raw ES256 signature bytes.
+     *
+     * @param marshaledSignature - Raw `signature` string returned by Transit's sign endpoint.
+     * @param providerKeyId - Transit key name, named in the error when the version is
+     *   unexpected.
+     * @returns Raw 64-byte ES256 signature.
+     * @throws {CustomError} EXTERNAL_API_ERROR when Transit signed with an unpublished key
+     *   version or returned a signature of the wrong length.
+     */
+    private parseTransitSignature;
+    /**
+     * Performs one OpenBao HTTP call and converts every failure into a classified
+     * `CustomError`.
+     *
+     * @param operation - Short label naming the step, retained in the error cause.
+     * @param path - Absolute OpenBao API path, including the `/v1` prefix.
+     * @param init - Method and body for the request.
+     * @param schema - Optional response schema; the body is validated when one is supplied.
+     * @param schema.parse - Validator applied to the parsed response body.
+     * @returns The validated response body, or the raw body when no schema is supplied.
+     * @throws {CustomError} EXTERNAL_API_ERROR on any transport failure, timeout, or
+     *   non-success status.
+     */
+    private request;
+    /**
+     * Classifies one non-success OpenBao status into an actionable error.
+     *
+     * @param operation - Short label naming the step.
+     * @param path - Absolute OpenBao API path that failed.
+     * @param status - HTTP status OpenBao returned.
+     * @param raw - Parsed response body, consulted only for its sanitized error list.
+     * @returns The classified error, for the caller to throw.
+     */
+    private failure;
+    /**
+     * Narrows an unknown error to the structured cause this class attaches to its failures.
+     *
+     * @param error - Error to inspect.
+     * @returns The cause when the error came from this provider's transport, else undefined.
+     */
+    private failureCause;
+}
+//# sourceMappingURL=openbao-keys-provider.d.ts.map

package/types/keys/openbao/openbao-keys-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openbao-keys-provider.d.ts","sourceRoot":"","sources":["../../../src/keys/openbao/openbao-keys-provider.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,MAAM,CAAC;AAOtC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,KAAK,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAK/D,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AAO3D;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,mBAAoB,YAAW,aAAa;IAuBrD,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,mBAAmB;IAxBtC,mFAAmF;IACnF,OAAO,CAAC,QAAQ,CAAmC;IAEnD,8FAA8F;IAC9F,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA8C;IAE1E,2CAA2C;IAC3C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IAEjC,mDAAmD;IACnD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAE/B;;;;;;;;OAQG;gBAEgB,MAAM,EAAE,wBAAwB,EAChC,SAAS,EAAE,OAAO,EAClB,mBAAmB,EAAE,MAAM;IAU9C;;;;;;;;;;OAUG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAOjC;;;;;;;OAOG;IACG,gBAAgB,IAAI,OAAO,CAAC,gBAAgB,CAAC;IA8BnD;;;;;;;;;OASG;IACG,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC;IA+B1D;;;;;;;;OAQG;IACG,cAAc,IAAI,OAAO,CAAC,SAAS,SAAS,EAAE,CAAC;IAUrD;;;;;;OAMG;YACW,eAAe;IAiB7B;;;;;;OAMG;YACW,eAAe;IAkB7B;;;;;;;;OAQG;YACW,eAAe;IAyB7B;;;;;;OAMG;YACW,mBAAmB;IAsDjC;;;;;;OAMG;YACW,eAAe;IAwC7B;;;;;;;;;OASG;IACH,OAAO,CAAC,qBAAqB;IAqC7B;;;;;;;;;;;;OAYG;YACW,OAAO;IAoDrB;;;;;;;;OAQG;IACH,OAAO,CAAC,OAAO;IAoCf;;;;;OAKG;IACH,OAAO,CAAC,YAAY;CAWrB"}

package/types/keys/openbao/schema.d.ts

@@ -0,0 +1,68 @@
+import { z } from 'zod';
+/**
+ * OpenBao key namespace, request policy, and connection schema.
+ *
+ * - TransitMount: Transit secrets-engine mount.
+ * - KvMount: KV v2 secrets-engine mount.
+ * - StatePath: KV path containing lifecycle state.
+ * - KeyNamePrefix: Prefix for provider-managed Transit keys.
+ * - RequestTimeoutMs: Deadline applied to every OpenBao HTTP request.
+ * - RefreshCooldownSecs: Minimum time between two re-reads of the lifecycle document
+ *   triggered by an unknown `kid`.
+ * - BaoAddr: OpenBao origin without embedded credentials; read from `BAO_ADDR`.
+ * - BaoToken: Runtime OpenBao token; a secret, read from `BAO_TOKEN`.
+ *
+ * @remarks
+ * `baoAddr` and `baoToken` are marked `.meta({ env })`, so `loadEnvVariables` resolves them
+ * from `BAO_ADDR` and `BAO_TOKEN` and hands the values to the provider; the configuration
+ * file holds only placeholders, so the token never appears in the config object.
+ */
+export declare const openBaoSigningKeysConfigSchema: z.ZodObject<{
+    transitMount: z.ZodString;
+    kvMount: z.ZodString;
+    statePath: z.ZodString;
+    keyNamePrefix: z.ZodString;
+    requestTimeoutMs: z.ZodDefault<z.ZodNumber>;
+    refreshCooldownSecs: z.ZodNumber;
+    baoAddr: z.ZodURL;
+    baoToken: z.ZodString;
+}, z.core.$strict>;
+/**
+ * KV v2 lifecycle-state read response schema.
+ *
+ * - Data: KV envelope carrying the stored document and its version metadata.
+ *
+ * @remarks
+ * OpenBao wraps every logical response in an envelope carrying `request_id`, `lease_id`,
+ * `lease_duration`, `renewable`, `warnings`, `wrap_info`, `auth` and `mount_type`, and the
+ * version metadata adds `created_time`, `custom_metadata`, `deletion_time` and `destroyed`.
+ * None of these response schemas may be `strict`, because those unmodelled fields are
+ * always present. Verified against OpenBao 2.7.0.
+ */
+export declare const openBaoKvReadResponseSchema: z.ZodObject<{
+    data: z.ZodObject<{
+        data: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        metadata: z.ZodObject<{
+            version: z.ZodNumber;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+/**
+ * Transit signing response schema.
+ *
+ * - Data: JWS-formatted signature returned by Transit.
+ */
+export declare const openBaoTransitSignResponseSchema: z.ZodObject<{
+    data: z.ZodObject<{
+        signature: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+/**
+ * OpenBao error response schema.
+ *
+ * - Errors: Sanitized error messages returned by OpenBao.
+ */
+export declare const openBaoErrorResponseSchema: z.ZodObject<{
+    errors: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+//# sourceMappingURL=schema.d.ts.map

package/types/keys/openbao/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/keys/openbao/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,8BAA8B;;;;;;;;;kBAchC,CAAC;AAEZ;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,2BAA2B;;;;;;;iBAKtC,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,gCAAgC;;;;iBAE3C,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,0BAA0B;;iBAA4C,CAAC"}

package/types/keys/openbao/types.d.ts

@@ -0,0 +1,52 @@
+import type { CryptoKey } from 'jose';
+import type { z } from 'zod';
+import type { PublicJwk } from '../types.js';
+import type { SigningKeyEntry, SigningKeyState } from '../types.js';
+import type { openBaoKvReadResponseSchema } from './schema.js';
+import type { openBaoSigningKeysConfigSchema } from './schema.js';
+import type { openBaoTransitSignResponseSchema } from './schema.js';
+/** OpenBao key namespace, request policy, and connection configuration. */
+export type OpenBaoSigningKeysConfig = z.infer<typeof openBaoSigningKeysConfigSchema>;
+/** KV v2 read response containing the lifecycle state document. */
+export type OpenBaoKvReadResponse = z.infer<typeof openBaoKvReadResponseSchema>;
+/** Transit response containing a JWS-formatted signature. */
+export type OpenBaoTransitSignResponse = z.infer<typeof openBaoTransitSignResponseSchema>;
+/**
+ * Structured cause attached to every OpenBao transport failure.
+ *
+ * - Operation: Short label naming the lifecycle step that failed.
+ * - Path: OpenBao API path that was requested.
+ * - Status: HTTP status returned, absent when the request never completed.
+ */
+export type OpenBaoFailureCause = Readonly<{
+    operation: string;
+    path: string;
+    status?: number;
+}>;
+/**
+ * Imported public key and lifecycle metadata retained in the local snapshot.
+ *
+ * - Key: Imported public Web Crypto verification key.
+ * - Status: Durable lifecycle status.
+ * - VerifyUntil: Retirement verification deadline, if applicable.
+ */
+export type CachedKey = Readonly<{
+    key: CryptoKey;
+    status: SigningKeyEntry['status'];
+    verifyUntil: string | null;
+}>;
+/**
+ * Atomic in-process projection of the last validated lifecycle state.
+ *
+ * - LoadedAt: Local timestamp when the snapshot was built.
+ * - State: Durable state represented by the snapshot.
+ * - Keys: Public JWK values eligible for publication.
+ * - ByKid: Imported verification keys indexed by exact key identifier.
+ */
+export type SigningKeySnapshot = Readonly<{
+    loadedAt: number;
+    state: SigningKeyState;
+    keys: readonly PublicJwk[];
+    byKid: ReadonlyMap<string, CachedKey>;
+}>;
+//# sourceMappingURL=types.d.ts.map

package/types/keys/openbao/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/keys/openbao/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,MAAM,CAAC;AACtC,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACpE,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,aAAa,CAAC;AAClE,OAAO,KAAK,EAAE,gCAAgC,EAAE,MAAM,aAAa,CAAC;AAEpE,2EAA2E;AAC3E,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,8BAA8B,CAAC,CAAC;AAEtF,mEAAmE;AACnE,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAEhF,6DAA6D;AAC7D,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gCAAgC,CAAC,CAAC;AAE1F;;;;;;GAMG;AACH,MAAM,MAAM,mBAAmB,GAAG,QAAQ,CAAC;IACzC,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC,CAAC;AAEH;;;;;;GAMG;AACH,MAAM,MAAM,SAAS,GAAG,QAAQ,CAAC;IAC/B,GAAG,EAAE,SAAS,CAAC;IACf,MAAM,EAAE,eAAe,CAAC,QAAQ,CAAC,CAAC;IAClC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B,CAAC,CAAC;AAEH;;;;;;;GAOG;AACH,MAAM,MAAM,kBAAkB,GAAG,QAAQ,CAAC;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,eAAe,CAAC;IACvB,IAAI,EAAE,SAAS,SAAS,EAAE,CAAC;IAC3B,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;CACvC,CAAC,CAAC"}

package/types/keys/schema.d.ts

@@ -0,0 +1,73 @@
+import { z } from 'zod';
+/**
+ * Public JSON Web Key material schema.
+ *
+ * - Kty: Key type.
+ * - Kid: Public key identifier.
+ * - Use: Optional intended key use.
+ * - Alg: Optional JOSE algorithm.
+ * - Crv: Optional elliptic curve name.
+ * - X: Optional elliptic-curve or RSA coordinate.
+ * - Y: Optional elliptic-curve coordinate.
+ * - N: Optional RSA modulus.
+ * - E: Optional RSA exponent.
+ *
+ * @remarks
+ * Provider-neutral: this is the public key as served to every key consumer, so it carries
+ * no provider-specific fields. Shared across every signing-key provider so each validates
+ * the lifecycle document against one definition.
+ * @group Keys
+ * @category Key Providers
+ */
+export declare const publicJwkSchema: z.ZodObject<{
+    kty: z.ZodString;
+    kid: z.ZodString;
+    use: z.ZodOptional<z.ZodString>;
+    alg: z.ZodOptional<z.ZodString>;
+    crv: z.ZodOptional<z.ZodString>;
+    x: z.ZodOptional<z.ZodString>;
+    y: z.ZodOptional<z.ZodString>;
+    n: z.ZodOptional<z.ZodString>;
+    e: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/**
+ * Durable signing-key lifecycle document schema.
+ *
+ * - CurrentKid: Identifier of the sole active key.
+ * - Keys: Complete provider-managed key lifecycle.
+ *
+ * @remarks
+ * The neutral contract every provider's durable store must satisfy. Behavioural invariants
+ * beyond this shape (exactly one active key, status-consistent timestamps) live in
+ * {@link validateSigningKeyState}.
+ * @group Keys
+ * @category Key Providers
+ */
+export declare const signingKeyStateSchema: z.ZodObject<{
+    currentKid: z.ZodNullable<z.ZodString>;
+    keys: z.ZodArray<z.ZodObject<{
+        kid: z.ZodString;
+        providerKeyId: z.ZodString;
+        status: z.ZodEnum<{
+            pending: "pending";
+            active: "active";
+            retired: "retired";
+        }>;
+        publicJwk: z.ZodObject<{
+            kty: z.ZodString;
+            kid: z.ZodString;
+            use: z.ZodOptional<z.ZodString>;
+            alg: z.ZodOptional<z.ZodString>;
+            crv: z.ZodOptional<z.ZodString>;
+            x: z.ZodOptional<z.ZodString>;
+            y: z.ZodOptional<z.ZodString>;
+            n: z.ZodOptional<z.ZodString>;
+            e: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+        activateAfter: z.ZodPipe<z.ZodString, z.ZodISODateTime>;
+        activatedAt: z.ZodNullable<z.ZodPipe<z.ZodString, z.ZodISODateTime>>;
+        retiredAt: z.ZodNullable<z.ZodPipe<z.ZodString, z.ZodISODateTime>>;
+        verifyUntil: z.ZodNullable<z.ZodPipe<z.ZodString, z.ZodISODateTime>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+//# sourceMappingURL=schema.d.ts.map

package/types/keys/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/keys/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;kBAYjB,CAAC;AAEZ;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;kBAkBvB,CAAC"}

package/types/keys/types.d.ts

@@ -0,0 +1,53 @@
+/** Public JSON Web Key material. */
+export type PublicJwk = Readonly<{
+    kty: string;
+    kid: string;
+    use?: string;
+    alg?: string;
+    crv?: string;
+    x?: string;
+    y?: string;
+    n?: string;
+    e?: string;
+}>;
+/** Signing capability bound to one provider-managed key. */
+export type SigningKeyHandle = Readonly<{
+    kid: string;
+    algorithm: 'ES256';
+    sign: (input: Uint8Array) => Promise<Uint8Array>;
+}>;
+/** Lifecycle state of a provider-managed signing key. */
+export type SigningKeyStatus = 'pending' | 'active' | 'retired';
+/**
+ * Durable metadata for one provider-managed signing key.
+ *
+ * - Kid: Public identifier carried with each signature.
+ * - ProviderKeyId: Opaque provider-owned key identifier.
+ * - Status: Current lifecycle status.
+ * - PublicJwk: Public verification key published through JWKS.
+ * - ActivateAfter: Earliest time when a pending key may become active.
+ * - ActivatedAt: Activation time, or null while pending.
+ * - RetiredAt: Retirement time, or null while active or pending.
+ * - VerifyUntil: Verification end time, or null while not retired.
+ */
+export type SigningKeyEntry = Readonly<{
+    kid: string;
+    providerKeyId: string;
+    status: SigningKeyStatus;
+    publicJwk: PublicJwk;
+    activateAfter: string;
+    activatedAt: string | null;
+    retiredAt: string | null;
+    verifyUntil: string | null;
+}>;
+/**
+ * Durable lifecycle state shared by the replicas that own one key set.
+ *
+ * - CurrentKid: Identifier of the sole active key.
+ * - Keys: Complete provider-managed key lifecycle.
+ */
+export type SigningKeyState = Readonly<{
+    currentKid: string | null;
+    keys: readonly SigningKeyEntry[];
+}>;
+//# sourceMappingURL=types.d.ts.map

package/types/keys/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/keys/types.ts"],"names":[],"mappings":"AAAA,oCAAoC;AACpC,MAAM,MAAM,SAAS,GAAG,QAAQ,CAAC;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,CAAC,CAAC,EAAE,MAAM,CAAC;CACZ,CAAC,CAAC;AAEH,4DAA4D;AAC5D,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC;IACtC,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,OAAO,CAAC;IACnB,IAAI,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;CAClD,CAAC,CAAC;AAEH,yDAAyD;AACzD,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEhE;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,eAAe,GAAG,QAAQ,CAAC;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,gBAAgB,CAAC;IACzB,SAAS,EAAE,SAAS,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B,CAAC,CAAC;AAEH;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG,QAAQ,CAAC;IACrC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,IAAI,EAAE,SAAS,eAAe,EAAE,CAAC;CAClC,CAAC,CAAC"}

package/types/keys/validation.d.ts

@@ -0,0 +1,19 @@
+import type { SigningKeyState } from './types.js';
+/**
+ * Parses the signing-key lifecycle document and enforces every invariant providers rely on.
+ *
+ * @remarks
+ * Shared by every signing-key provider so the lifecycle invariants have one definition:
+ * unique identifiers, an ES256 P-256 public JWK per entry whose `kid` matches its entry,
+ * status-consistent timestamps, exactly one active key, at most one pending key, and a
+ * `currentKid` that names the active key. Nothing downstream re-checks any of this, so a
+ * failure here is fatal on purpose.
+ * @group Keys
+ * @category Key Providers
+ * @param value - Raw lifecycle document read from a provider's durable store.
+ * @param algorithm - JOSE algorithm every published key must declare.
+ * @returns Validated signing-key state.
+ * @throws {CustomError} KEYS_PROVIDER_ERROR when any signing-key invariant fails.
+ */
+export declare function validateSigningKeyState(value: unknown, algorithm: 'ES256'): SigningKeyState;
+//# sourceMappingURL=validation.d.ts.map

package/types/keys/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/keys/validation.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAmB,eAAe,EAAE,MAAM,YAAY,CAAC;AAEnE;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,OAAO,EACd,SAAS,EAAE,OAAO,GACjB,eAAe,CA8DjB"}

package/types/runtime/context.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Trusted authenticated request identity.
+ *
+ * - ActorId: Authenticated actor attributed as the author of record mutations.
+ * - TenantId: Tenant boundary scoping every record operation.
+ *
+ * @group Utils
+ * @category Execution Context
+ */
+export type AuthenticatedContext = Readonly<{
+    actorId: string;
+    tenantId: string;
+}>;
+/**
+ * Per-request tracing metadata.
+ *
+ * - RequestId: Correlation identifier carried through logs for one request or job.
+ *
+ * @group Utils
+ * @category Execution Context
+ */
+export type RequestContext = Readonly<{
+    requestId: string;
+}>;
+/**
+ * Request-scoped execution metadata established by transport middleware.
+ *
+ * - Authenticated: Trusted identity for the current request or job.
+ * - Request: Tracing metadata for the current request or job.
+ *
+ * @remarks
+ * Bound to the async scope by {@link runWithExecutionCtx} and retrieved by
+ * {@link getExecutionCtx}, so downstream policy code such as {@link RecordsHandler} reads the
+ * caller's tenant and actor without threading them through every call.
+ * @group Utils
+ * @category Execution Context
+ */
+export type ExecutionContext = Readonly<{
+    authenticated: AuthenticatedContext;
+    request: RequestContext;
+}>;
+/**
+ * Runs one callback with the supplied execution context bound to the current async scope.
+ *
+ * @remarks
+ * The context is visible to every asynchronous operation started within `callback` and is
+ * torn down when it returns, so nested calls to {@link getExecutionCtx} resolve the same
+ * identity without explicit propagation. Transport middleware wraps request handling in
+ * this call.
+ * @group Utils
+ * @category Execution Context
+ * @param context - Execution context for the current request or job.
+ * @param callback - Work executed while the context is available.
+ * @returns The callback return value.
+ */
+export declare function runWithExecutionCtx<T>(context: ExecutionContext, callback: () => T): T;
+/**
+ * Reads the current execution context.
+ *
+ * @group Utils
+ * @category Execution Context
+ * @returns The active {@link ExecutionContext} for the current async scope.
+ * @throws {CustomError} RESOURCE_NOT_FOUND when called outside a {@link runWithExecutionCtx}
+ *   scope, so no context is bound.
+ */
+export declare function getExecutionCtx(): ExecutionContext;
+//# sourceMappingURL=context.d.ts.map

package/types/runtime/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/runtime/context.ts"],"names":[],"mappings":"AAGA;;;;;;;;GAQG;AACH,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CAAC;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC,CAAC;AAEH;;;;;;;GAOG;AACH,MAAM,MAAM,cAAc,GAAG,QAAQ,CAAC;IACpC,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC,CAAC;AAEH;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC;IACtC,aAAa,EAAE,oBAAoB,CAAC;IACpC,OAAO,EAAE,cAAc,CAAC;CACzB,CAAC,CAAC;AAMH;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,CAAC,GAAG,CAAC,CAEtF;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,IAAI,gBAAgB,CAYlD"}

package/types/runtime/index.d.ts

@@ -0,0 +1,2 @@
+export * from './context.js';
+//# sourceMappingURL=index.d.ts.map

package/types/runtime/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/runtime/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC"}

package/types/tokens/access-token-verifier.d.ts

@@ -0,0 +1,36 @@
+import type { IAccessTokenVerifier } from './contracts.js';
+import type { AccessTokenVerifyConfig } from './types.js';
+import type { BearerToken } from './types.js';
+import type { SessionGrant } from './types.js';
+import type { IVerificationKeyProvider } from '../keys/contracts.js';
+/**
+ * Verifies platform access tokens and reconstructs their session grant.
+ *
+ * @remarks
+ * Checks the protected header, resolves the public key by `kid` through the injected
+ * {@link IVerificationKeyProvider}, verifies signature, issuer, audience, and expiry with
+ * `jose`, then parses the claims with {@link accessTokenClaimsSchema}.
+ * @group Tokens
+ * @category Access Tokens
+ */
+export declare class AccessTokenVerifier implements IAccessTokenVerifier {
+    private readonly config;
+    private readonly keys;
+    /**
+     * @param config - Issuer, audience, and clock tolerance every token must satisfy.
+     * @param keys - Source of public verification keys by `kid`.
+     */
+    constructor(config: AccessTokenVerifyConfig, keys: IVerificationKeyProvider);
+    /**
+     * Verifies one bearer access token.
+     *
+     * @param credential - Bearer credential selected by the transport layer.
+     * @returns Trusted session grant read from the token claims.
+     * @throws {CustomError} AUTHENTICATION_FAILED when the token is malformed, signed by an
+     *   unknown key, expired, or carries incomplete claims.
+     * @throws {CustomError} EXTERNAL_API_ERROR or CONFIG_ERROR when the key provider fails;
+     *   propagated unchanged.
+     */
+    verify(credential: BearerToken): Promise<SessionGrant>;
+}
+//# sourceMappingURL=access-token-verifier.d.ts.map

package/types/tokens/access-token-verifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"access-token-verifier.d.ts","sourceRoot":"","sources":["../../src/tokens/access-token-verifier.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAE3D,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAC1D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAErE;;;;;;;;;GASG;AACH,qBAAa,mBAAoB,YAAW,oBAAoB;IAM5D,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,IAAI;IANvB;;;OAGG;gBAEgB,MAAM,EAAE,uBAAuB,EAC/B,IAAI,EAAE,wBAAwB;IAGjD;;;;;;;;;OASG;IACG,MAAM,CAAC,UAAU,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC;CA8C7D"}

package/types/tokens/contracts.d.ts

@@ -0,0 +1,21 @@
+import type { BearerToken, SessionGrant } from './types.js';
+/**
+ * Access-token verification boundary.
+ *
+ * @remarks
+ * {@link AccessTokenVerifier} is the shipped implementation. A consumer injects it behind
+ * this contract, so where the verification keys come from (an owned key set or a remote
+ * JWKS) is chosen at the composition root, not by the consumer.
+ * @group Tokens
+ * @category Access Tokens
+ */
+export interface IAccessTokenVerifier {
+    /**
+     * Verifies one bearer access credential.
+     *
+     * @param credential - Bearer credential selected by the route transport policy.
+     * @returns Trusted session grant reconstructed from the credential.
+     */
+    verify(credential: BearerToken): Promise<SessionGrant>;
+}
+//# sourceMappingURL=contracts.d.ts.map

package/types/tokens/contracts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.d.ts","sourceRoot":"","sources":["../../src/tokens/contracts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE5D;;;;;;;;;GASG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;;OAKG;IACH,MAAM,CAAC,UAAU,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;CACxD"}

package/types/tokens/index.d.ts

@@ -0,0 +1,5 @@
+export * from './access-token-verifier.js';
+export * from './contracts.js';
+export * from './schema.js';
+export * from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/types/tokens/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tokens/index.ts"],"names":[],"mappings":"AAAA,cAAc,4BAA4B,CAAC;AAC3C,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC"}

package/types/tokens/schema.d.ts

@@ -0,0 +1,34 @@
+import { z } from 'zod';
+/**
+ * Access-token verification policy every verifier shares with the issuer.
+ *
+ * - Issuer: Required `iss`, the issuing service's base URL.
+ * - Audience: Required `aud`.
+ * - ClockToleranceSecs: Allowed clock skew when checking `exp` and `iat`.
+ */
+export declare const accessTokenVerifyConfigSchema: z.ZodObject<{
+    issuer: z.ZodURL;
+    audience: z.ZodString;
+    clockToleranceSecs: z.ZodNumber;
+}, z.core.$strict>;
+/**
+ * Platform claims carried by every access token.
+ *
+ * - Sid: Server-side session identifier.
+ * - Sub: Authenticated subject.
+ * - ActorId: Local actor represented by the session.
+ * - TenantId: Tenant the session belongs to.
+ * - Roles: Roles granted to the session.
+ *
+ * @remarks
+ * Not strict: `jwtVerify` already checks the registered claims (`iss`, `aud`, `iat`,
+ * `exp`), and parsing strips them.
+ */
+export declare const accessTokenClaimsSchema: z.ZodObject<{
+    sid: z.ZodString;
+    sub: z.ZodString;
+    actorId: z.ZodString;
+    tenantId: z.ZodString;
+    roles: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+//# sourceMappingURL=schema.d.ts.map