@salamandradevs/core 0.1.4 → 0.2.0

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"}

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"}