@salamandradevs/core 0.1.3 → 0.2.0

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

@@ -0,0 +1,66 @@
+import { z } from 'zod';
+/**
+ * Supported signing-key provider identifiers; grows as new providers are added.
+ *
+ * @group Keys
+ * @category Key Providers
+ */
+export declare const signingKeyProviderSchema: z.ZodEnum<{
+    jose: "jose";
+    openbao: "openbao";
+}>;
+/**
+ * Signing-key provider selector resolved from the environment.
+ *
+ * - Provider: Active signing-key provider; read from `SIGNING_KEY_PROVIDER`.
+ *
+ * @remarks
+ * `provider` is marked `.meta({ env })`, so `loadEnvVariables` resolves it from
+ * `SIGNING_KEY_PROVIDER`; the active provider is chosen at runtime, never baked into the
+ * configuration file.
+ * @group Keys
+ * @category Key Providers
+ */
+export declare const signingKeyProviderSelectorSchema: z.ZodObject<{
+    provider: z.ZodEnum<{
+        jose: "jose";
+        openbao: "openbao";
+    }>;
+}, z.core.$strict>;
+/**
+ * Provider-neutral signing lifecycle schema.
+ *
+ * - Algorithm: JOSE algorithm supported by this key set.
+ * - Jose: Jose provider configuration, present when the deployment may select `jose`.
+ * - Openbao: OpenBao provider configuration, present when the deployment may select
+ *   `openbao`.
+ *
+ * @remarks
+ * Each provider block is optional so a deployment configures only the providers it uses;
+ * the active one is chosen at runtime by `SIGNING_KEY_PROVIDER` and must have its block
+ * present. Composed into each service's own `serviceConfigSchema` and validated there; core
+ * never reads a configuration file.
+ * @group Keys
+ * @category Key Providers
+ */
+export declare const signingKeysConfigSchema: z.ZodObject<{
+    algorithm: z.ZodLiteral<"ES256">;
+    jose: z.ZodOptional<z.ZodObject<{
+        keyNamePrefix: z.ZodString;
+        storage: z.ZodObject<{
+            filePath: z.ZodString;
+            passphrase: z.ZodString;
+        }, z.core.$strict>;
+    }, z.core.$strict>>;
+    openbao: z.ZodOptional<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>>;
+}, z.core.$strict>;
+//# sourceMappingURL=schema.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/keys/config/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB;;;EAA8B,CAAC;AAEpE;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,gCAAgC;;;;;kBAIlC,CAAC;AAEZ;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;kBAMzB,CAAC"}

package/types/keys/config/types.d.ts

@@ -0,0 +1,8 @@
+import type { z } from 'zod';
+import type { signingKeyProviderSchema } from './schema.js';
+import type { signingKeysConfigSchema } from './schema.js';
+/** Durable signing lifecycle and per-provider configuration. */
+export type SigningKeysConfig = z.infer<typeof signingKeysConfigSchema>;
+/** Signing-key provider selected at runtime by `SIGNING_KEY_PROVIDER`. */
+export type SigningKeyProvider = z.infer<typeof signingKeyProviderSchema>;
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/keys/config/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAE3D,gEAAgE;AAChE,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAExE,0EAA0E;AAC1E,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC"}

package/types/keys/contracts.d.ts

@@ -0,0 +1,52 @@
+import type { CryptoKey } from 'jose';
+import type { PublicJwk, SigningKeyHandle } from './types.js';
+/**
+ * Owner of a key set that signs with it and lists its public keys.
+ *
+ * @remarks
+ * {@link JoseKeysProvider} and {@link OpenBaoKeysProvider} are the shipped implementations,
+ * each over the key set it owns. A consumer that only issues signatures depends on this
+ * role, never on {@link IVerificationKeyProvider} or {@link IKeysProvider}.
+ * @group Keys
+ * @category Key Providers
+ */
+export interface ISigningKeyProvider {
+    /** Loads durable state and ensures that an active key exists. */
+    initialize(): Promise<void>;
+    /** Returns a signer bound to the active key. */
+    getCurrentSigner(): Promise<SigningKeyHandle>;
+    /** Lists public keys eligible for JWKS publication. */
+    listPublicKeys(): Promise<readonly PublicJwk[]>;
+}
+/**
+ * Source of public keys that verify signatures, looked up by key identifier.
+ *
+ * @remarks
+ * {@link JoseKeysProvider} and {@link OpenBaoKeysProvider} implement it over the key set they
+ * own, next to {@link ISigningKeyProvider}; {@link JwksVerificationKeyProvider} implements it
+ * over a remote JWKS.
+ * @group Keys
+ * @category Key Providers
+ */
+export interface IVerificationKeyProvider {
+    /**
+     * Resolves an eligible public verification key by exact key identifier.
+     *
+     * @param kid - Key identifier carried with the signature.
+     * @returns The public key, or null when no eligible key has that identifier.
+     */
+    getPublicKey(kid: string): Promise<CryptoKey | null>;
+}
+/**
+ * Owner of a key set, which signs with it and verifies against it.
+ *
+ * @remarks
+ * Adds no members: it names the class the composition root builds once, which then hands
+ * each consumer only {@link ISigningKeyProvider} or {@link IVerificationKeyProvider}.
+ * {@link JoseKeysProvider} and {@link OpenBaoKeysProvider} are the shipped implementations.
+ * @group Keys
+ * @category Key Providers
+ */
+export interface IKeysProvider extends ISigningKeyProvider, IVerificationKeyProvider {
+}
+//# sourceMappingURL=contracts.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.d.ts","sourceRoot":"","sources":["../../src/keys/contracts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,MAAM,CAAC;AAEtC,OAAO,KAAK,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAE9D;;;;;;;;;GASG;AACH,MAAM,WAAW,mBAAmB;IAClC,iEAAiE;IACjE,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAE5B,gDAAgD;IAChD,gBAAgB,IAAI,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAE9C,uDAAuD;IACvD,cAAc,IAAI,OAAO,CAAC,SAAS,SAAS,EAAE,CAAC,CAAC;CACjD;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,wBAAwB;IACvC;;;;;OAKG;IACH,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;CACtD;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,aAAc,SAAQ,mBAAmB,EAAE,wBAAwB;CAAG"}

package/types/keys/factory.d.ts

@@ -0,0 +1,22 @@
+import type { IKeysProvider } from './contracts.js';
+import type { SigningKeysConfig } from './config/types.js';
+/**
+ * Selects and constructs the keys provider named by `SIGNING_KEY_PROVIDER`.
+ *
+ * @remarks
+ * Construction only: each provider resolves its own environment as it is constructed but
+ * performs no input or output, so all network and file work is deferred to `initialize()`.
+ * The `switch` is the single extension point; a new provider is a new enum member, a new
+ * `case`, and its own configuration block, with no change to the bootstrap step or the
+ * services that consume the provider. Returns the owner of the key set as
+ * {@link IKeysProvider}; the composition root hands each consumer only the role it uses.
+ * @group Keys
+ * @category Key Providers
+ * @param config - Signing lifecycle and per-provider configuration.
+ * @returns The keys provider named by `SIGNING_KEY_PROVIDER`, ready for `initialize()`.
+ * @throws {CustomError} ENV_VAR_ERROR when `SIGNING_KEY_PROVIDER` is missing or not a
+ *   recognized provider, or (for OpenBao) when the provider's own variables are missing.
+ * @throws {CustomError} CONFIG_ERROR when the selected provider has no configuration block.
+ */
+export declare function createKeysProvider(config: SigningKeysConfig): IKeysProvider;
+//# sourceMappingURL=factory.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../src/keys/factory.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEpD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAE3D;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,iBAAiB,GAAG,aAAa,CAiD3E"}

package/types/keys/index.d.ts

@@ -0,0 +1,10 @@
+export * from './config/index.js';
+export * from './contracts.js';
+export * from './factory.js';
+export * from './jose/index.js';
+export * from './jwks/index.js';
+export * from './openbao/index.js';
+export * from './schema.js';
+export * from './types.js';
+export * from './validation.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/keys/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC"}

package/types/keys/jose/index.d.ts

@@ -0,0 +1,3 @@
+export * from './jose-keys-provider.js';
+export * from './schema.js';
+//# sourceMappingURL=index.d.ts.map

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

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

package/types/keys/jose/jose-keyfile.d.ts

@@ -0,0 +1,35 @@
+import type { KeyFilePayload } from './types.js';
+/**
+ * Reads and decrypts the encrypted key file, or reports its absence.
+ *
+ * @remarks
+ * A decrypt or parse failure is reported, never swallowed: a wrong passphrase must fail
+ * loudly rather than be mistaken for an absent file, so a typo cannot discard the keys.
+ * @group Keys
+ * @category Key Providers
+ * @param filePath - Path to the encrypted key file.
+ * @param secret - Passphrase that decrypts the compact JWE.
+ * @returns Validated key-file payload, or null when no file exists.
+ * @throws {CustomError} KEYS_PROVIDER_ERROR when the file exists but cannot be read,
+ *   decrypted, or parsed into a valid key-file payload.
+ */
+export declare function readKeyFile(filePath: string, secret: string): Promise<KeyFilePayload | null>;
+/**
+ * Encrypts and writes the key file, creating it only when none already exists.
+ *
+ * @remarks
+ * The `wx` flag makes the create exclusive and `0o600` restricts it to the owner, so two
+ * processes racing on one host resolve to one winner; the loser sees the file already
+ * exists, is told so by the false return, and reads the winner's key instead of minting a
+ * second.
+ * @group Keys
+ * @category Key Providers
+ * @param filePath - Path to the encrypted key file.
+ * @param secret - Passphrase that encrypts the compact JWE.
+ * @param payload - Key-file payload to persist.
+ * @returns True when this call created the file, false when one already existed.
+ * @throws {CustomError} KEYS_PROVIDER_ERROR when encryption or the write fails for any
+ *   reason other than the file already existing.
+ */
+export declare function writeKeyFile(filePath: string, secret: string, payload: KeyFilePayload): Promise<boolean>;
+//# sourceMappingURL=jose-keyfile.d.ts.map

package/types/keys/jose/jose-keyfile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jose-keyfile.d.ts","sourceRoot":"","sources":["../../../src/keys/jose/jose-keyfile.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AASjD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,WAAW,CAC/B,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAqChC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,YAAY,CAChC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,OAAO,CAAC,CAqBlB"}

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

@@ -0,0 +1,112 @@
+import type { CryptoKey } from 'jose';
+import type { IKeysProvider } from '../contracts.js';
+import type { PublicJwk, SigningKeyHandle } from '../types.js';
+import type { JoseSigningKeysConfig } from './types.js';
+/**
+ * Node.js-native keys provider that keeps its key set in an encrypted local file.
+ *
+ * @remarks
+ * Generates its own ES256 key on first run and keeps the private material in an encrypted
+ * file keyed from the environment, then signs and verifies against that one key set. It
+ * fits a small deployment: a single host, or replicas sharing one key file, with the file
+ * on a persistent volume and the file and `JOSE_KEYFILE_PASSPHRASE` backed up separately.
+ * Compared with {@link OpenBaoKeysProvider}, it accepts that the private key lives in
+ * process memory, that replacing the key file reissues every credential it signed, and that
+ * no policy layer limits key use; OpenBao is the choice when those costs are not
+ * acceptable. It serves one active key and never rotates.
+ * @group Keys
+ * @category Key Providers
+ */
+export declare class JoseKeysProvider implements IKeysProvider {
+    private readonly config;
+    private readonly algorithm;
+    /** Built once in initialize(); no rotation means no refresh machinery. */
+    private snapshot;
+    /**
+     * @param config - Validated Jose provider configuration.
+     * @param algorithm - JOSE algorithm enforced for the generated key.
+     */
+    constructor(config: JoseSigningKeysConfig, algorithm: 'ES256');
+    /**
+     * Loads the encrypted key file and publishes the first snapshot, generating a key on
+     * first run when the file is absent.
+     *
+     * @remarks
+     * Hard reset: delete the key file and restart. An absent file re-enters the
+     * generate-on-empty path and mints a fresh key, so there is no separate reset operation.
+     * The file is read once here, so deleting it while the process runs takes effect only on
+     * the next initialize(); the running provider keeps serving the key already in memory.
+     * This is a hard reset, not a rotation: the previous kid leaves the published key set at
+     * once and every credential it signed stops verifying. A decrypt failure fails loudly and
+     * is never treated as an empty file, so a wrong passphrase cannot discard the keys.
+     * @group Keys
+     * @category Key Providers
+     * @returns Completed provider initialization.
+     * @throws {CustomError} ENV_VAR_ERROR when the passphrase env variable is unset or blank.
+     * @throws {CustomError} KEYS_PROVIDER_ERROR when the file cannot be decrypted or violates
+     *   a signing-key invariant.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Returns a signer bound to the active key.
+     *
+     * @group Keys
+     * @category Key Providers
+     * @returns Provider-neutral signing capability.
+     * @throws {CustomError} KEYS_PROVIDER_ERROR when initialize() has not completed.
+     */
+    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 key.
+     * @throws {CustomError} KEYS_PROVIDER_ERROR when initialize() has not completed.
+     */
+    getPublicKey(kid: string): Promise<CryptoKey | null>;
+    /**
+     * Lists the public keys eligible for JWKS publication.
+     *
+     * @group Keys
+     * @category Key Providers
+     * @returns Retained public JSON Web Keys.
+     * @throws {CustomError} KEYS_PROVIDER_ERROR when initialize() has not completed.
+     */
+    listPublicKeys(): Promise<readonly PublicJwk[]>;
+    /**
+     * Generates the first key and writes it, adopting an existing file when a concurrent
+     * start won the race.
+     *
+     * @param secret - Passphrase that encrypts the key file.
+     * @returns The persisted key-file payload.
+     * @throws {CustomError} KEYS_PROVIDER_ERROR when the file cannot be written or re-read.
+     */
+    private createKeyFile;
+    /**
+     * Generates one active ES256 key and the key-file payload that persists it.
+     *
+     * @returns Key-file payload with a single active key and its private material.
+     * @throws {CustomError} KEYS_PROVIDER_ERROR when the generated key is missing JWK
+     *   coordinates.
+     */
+    private generatePayload;
+    /**
+     * Validates the payload and publishes the in-process snapshot.
+     *
+     * @param payload - Key-file payload to project.
+     * @returns Completed snapshot publication.
+     * @throws {CustomError} KEYS_PROVIDER_ERROR when the state is invalid or a JWK cannot be
+     *   imported as an asymmetric key.
+     */
+    private publishSnapshot;
+    /**
+     * Returns the snapshot published by initialize().
+     *
+     * @returns The in-process projection of the signing-key state.
+     * @throws {CustomError} KEYS_PROVIDER_ERROR when initialize() has not completed.
+     */
+    private currentSnapshot;
+}
+//# sourceMappingURL=jose-keys-provider.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"jose-keys-provider.d.ts","sourceRoot":"","sources":["../../../src/keys/jose/jose-keys-provider.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,SAAS,EAAO,MAAM,MAAM,CAAC;AAK3C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,KAAK,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE/D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAIxD;;;;;;;;;;;;;;GAcG;AACH,qBAAa,gBAAiB,YAAW,aAAa;IASlD,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAT5B,0EAA0E;IAC1E,OAAO,CAAC,QAAQ,CAAmC;IAEnD;;;OAGG;gBAEgB,MAAM,EAAE,qBAAqB,EAC7B,SAAS,EAAE,OAAO;IAGrC;;;;;;;;;;;;;;;;;;OAkBG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAcjC;;;;;;;OAOG;IACH,gBAAgB,IAAI,OAAO,CAAC,gBAAgB,CAAC;IAsB7C;;;;;;;;OAQG;IACH,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC;IAIpD;;;;;;;OAOG;IACH,cAAc,IAAI,OAAO,CAAC,SAAS,SAAS,EAAE,CAAC;IAI/C;;;;;;;OAOG;YACW,aAAa;IA4B3B;;;;;;OAMG;YACW,eAAe;IAuD7B;;;;;;;OAOG;YACW,eAAe;IAsD7B;;;;;OAKG;IACH,OAAO,CAAC,eAAe;CAYxB"}

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

@@ -0,0 +1,91 @@
+import { z } from 'zod';
+/**
+ * Jose key-file storage schema.
+ *
+ * - FilePath: Path to the encrypted key file; must be listed in `.gitignore`.
+ * - Passphrase: Encrypted key-file passphrase; a secret, read from `JOSE_KEYFILE_PASSPHRASE`.
+ *
+ * @remarks
+ * `passphrase` is marked `.meta({ env })`, so `loadEnvVariables` resolves it from
+ * `JOSE_KEYFILE_PASSPHRASE`; the configuration file holds only a placeholder.
+ */
+export declare const joseStorageConfigSchema: z.ZodObject<{
+    filePath: z.ZodString;
+    passphrase: z.ZodString;
+}, z.core.$strict>;
+/**
+ * Jose provider configuration and local-storage schema.
+ *
+ * - KeyNamePrefix: Prefix for the generated `kid` and provider key identifier.
+ * - Storage: Encrypted key-file location and passphrase source.
+ *
+ * @remarks
+ * Self-contained so the provider directory owns its whole storage story without the factory
+ * ever handling a file path or a secret.
+ */
+export declare const joseSigningKeysConfigSchema: z.ZodObject<{
+    keyNamePrefix: z.ZodString;
+    storage: z.ZodObject<{
+        filePath: z.ZodString;
+        passphrase: z.ZodString;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+/**
+ * EC P-256 private JWK persisted in the encrypted key file.
+ *
+ * - Kty: Key type, always `EC`.
+ * - Crv: Curve, always `P-256`.
+ * - X: Public x coordinate.
+ * - Y: Public y coordinate.
+ * - D: Private scalar; the secret half, which is why the file is encrypted at rest.
+ */
+export declare const privateJwkSchema: z.ZodObject<{
+    kty: z.ZodLiteral<"EC">;
+    crv: z.ZodLiteral<"P-256">;
+    x: z.ZodString;
+    y: z.ZodString;
+    d: z.ZodString;
+}, z.core.$strict>;
+/**
+ * Decrypted key-file payload.
+ *
+ * - State: Signing-key lifecycle document shared with every provider.
+ * - PrivateJwks: Private signing material indexed by `kid`.
+ */
+export declare const keyFilePayloadSchema: z.ZodObject<{
+    state: 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>;
+    privateJwks: z.ZodRecord<z.ZodString, z.ZodObject<{
+        kty: z.ZodLiteral<"EC">;
+        crv: z.ZodLiteral<"P-256">;
+        x: z.ZodString;
+        y: z.ZodString;
+        d: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+//# sourceMappingURL=schema.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/keys/jose/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;;;;;;;GASG;AACH,eAAO,MAAM,uBAAuB;;;kBAQzB,CAAC;AAEZ;;;;;;;;;GASG;AACH,eAAO,MAAM,2BAA2B;;;;;;kBAK7B,CAAC;AAEZ;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB;;;;;;kBAQlB,CAAC;AAEZ;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAKtB,CAAC"}

package/types/keys/jose/types.d.ts

@@ -0,0 +1,35 @@
+import type { CryptoKey } from 'jose';
+import type { z } from 'zod';
+import type { PublicJwk } from '../types.js';
+import type { SigningKeyState } from '../types.js';
+import type { joseSigningKeysConfigSchema } from './schema.js';
+import type { keyFilePayloadSchema } from './schema.js';
+import type { privateJwkSchema } from './schema.js';
+/** Validated Jose provider configuration and local-storage policy. */
+export type JoseSigningKeysConfig = z.infer<typeof joseSigningKeysConfigSchema>;
+/** Decrypted key-file payload persisted by the Jose provider. */
+export type KeyFilePayload = z.infer<typeof keyFilePayloadSchema>;
+/** EC P-256 private JWK persisted in the encrypted key file. */
+export type PrivateJwk = z.infer<typeof privateJwkSchema>;
+/**
+ * In-process projection of the Jose provider's signing-key state.
+ *
+ * - State: Validated lifecycle document the snapshot was built from.
+ * - Keys: Public JWK values eligible for JWKS publication.
+ * - ByKid: Imported public verification keys indexed by exact key identifier.
+ * - ActiveSigner: Active key identifier and its imported private signing key.
+ *
+ * @remarks
+ * Named to match the OpenBao provider's equivalent projection. Built once in `initialize`
+ * and never refreshed, because the Jose provider serves one active key and never rotates.
+ */
+export type SigningKeySnapshot = Readonly<{
+    state: SigningKeyState;
+    keys: readonly PublicJwk[];
+    byKid: ReadonlyMap<string, CryptoKey>;
+    activeSigner: Readonly<{
+        kid: string;
+        privateKey: CryptoKey;
+    }>;
+}>;
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/keys/jose/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,MAAM,aAAa,CAAC;AACnD,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEpD,sEAAsE;AACtE,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAEhF,iEAAiE;AACjE,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE,gEAAgE;AAChE,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,kBAAkB,GAAG,QAAQ,CAAC;IACxC,KAAK,EAAE,eAAe,CAAC;IACvB,IAAI,EAAE,SAAS,SAAS,EAAE,CAAC;IAC3B,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IACtC,YAAY,EAAE,QAAQ,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,SAAS,CAAA;KAAE,CAAC,CAAC;CAChE,CAAC,CAAC"}

package/types/keys/jwks/index.d.ts

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

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

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

package/types/keys/jwks/jwks-verification-key-provider.d.ts

@@ -0,0 +1,27 @@
+import type { CryptoKey } from 'jose';
+import type { IVerificationKeyProvider } from '../contracts.js';
+/**
+ * Verification keys read from a remote JWKS, such as auth's published key set.
+ *
+ * @remarks
+ * Delegates fetching and caching to `jose`'s remote key set, which refetches on an unknown
+ * `kid` after its cooldown. A `kid` the set does not hold resolves to null; a key set that
+ * cannot be fetched or parsed is an infrastructure fault.
+ * @group Keys
+ * @category Key Providers
+ */
+export declare class JwksVerificationKeyProvider implements IVerificationKeyProvider {
+    private readonly jwks;
+    /** @param jwksUrl - Absolute URL of the JWKS document. */
+    constructor(jwksUrl: string);
+    /**
+     * Resolves an ES256 public key from the remote key set.
+     *
+     * @param kid - Key identifier carried with the signature.
+     * @returns The public key, or null when the key set has no key with that identifier.
+     * @throws {CustomError} EXTERNAL_API_ERROR when the key set cannot be fetched or is
+     *   invalid.
+     */
+    getPublicKey(kid: string): Promise<CryptoKey | null>;
+}
+//# sourceMappingURL=jwks-verification-key-provider.d.ts.map

package/types/keys/jwks/jwks-verification-key-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jwks-verification-key-provider.d.ts","sourceRoot":"","sources":["../../../src/keys/jwks/jwks-verification-key-provider.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,MAAM,CAAC;AAEtC,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,iBAAiB,CAAC;AAEhE;;;;;;;;;GASG;AACH,qBAAa,2BAA4B,YAAW,wBAAwB;IAC1E,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAwC;IAE7D,0DAA0D;gBAC9C,OAAO,EAAE,MAAM;IAI3B;;;;;;;OAOG;IACG,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC;CAe3D"}

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

@@ -0,0 +1,3 @@
+export * from './openbao-keys-provider.js';
+export * from './schema.js';
+//# sourceMappingURL=index.d.ts.map

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

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