@absolutejs/secrets 0.6.1 → 0.7.1

package/dist/broker.d.ts

@@ -0,0 +1,340 @@
+/**
+ * @absolutejs/secrets — host-side secret broker for multi-tenant Bun
+ * runtimes.
+ *
+ * Three responsibilities, kept narrow on purpose:
+ *
+ * 1. **Resolve.** A pluggable adapter fetches a secret by name. The broker
+ *    caches the answer, hands the caller back a `{ value, fingerprint }`
+ *    pair (fingerprint is a sha256 prefix safe to put in logs), and fires
+ *    an audit event for every lookup.
+ * 2. **Redact.** Walks every known cached secret out of an arbitrary string
+ *    before it leaves the host (e.g. an error message that contains the
+ *    leaked API key the host call just made). The replacement is
+ *    `[REDACTED:name]`; matches shorter than `redactionMinLength` are
+ *    skipped to avoid blanking coincidental short tokens.
+ * 3. **Rotate.** Delegates to `adapter.rotate?(name)` if the adapter
+ *    supports it, invalidates the cache entry. Caller is expected to
+ *    re-distribute to dependent surfaces.
+ *
+ * v0.0.1 ships three adapters: `inMemoryAdapter`, `envAdapter`,
+ * `compositeAdapter`. AWS Secrets Manager / Vault / Doppler / Infisical
+ * adapters ship later as siblings.
+ *
+ * The broker is bun/elysia-agnostic — same posture as router + meter.
+ */
+import { type TracerProvider } from "@absolutejs/telemetry";
+export type SecretValue = {
+    /** The plaintext secret. Treat as poison: never log, never serialize. */
+    value: string;
+    /**
+     * Short sha256-derived id (first 8 hex chars). Stable across calls for
+     * the same value; safe to print in logs and traces. Useful for "which
+     * version of the key did this request use?" diagnostics without leaking.
+     */
+    fingerprint: string;
+};
+export type SecretAdapter = {
+    /** Return the plaintext value for a name, or `null` if not stored here. */
+    fetch: (name: string) => Promise<string | null>;
+    /** Write a value. Optional — adapters may be read-only. */
+    put?: (name: string, value: string) => Promise<void>;
+    /** Delete a value. Optional. */
+    remove?: (name: string) => Promise<void>;
+    /** Rotate a value; return the NEW plaintext. Optional. */
+    rotate?: (name: string) => Promise<string>;
+    /** Enumerate names. Optional; default omitted to avoid leaking the index. */
+    list?: () => Promise<string[]>;
+};
+export type AuditEvent = {
+    event: "resolve.hit";
+    name: string;
+    fingerprint: string;
+    at: number;
+} | {
+    event: "resolve.miss";
+    name: string;
+    fingerprint?: string;
+    at: number;
+} | {
+    event: "resolve.error";
+    name: string;
+    error: string;
+    at: number;
+} | {
+    event: "rotate";
+    name: string;
+    fingerprint: string;
+    at: number;
+} | {
+    event: "invalidate";
+    name: string | null;
+    at: number;
+};
+export type AuditHook = (event: AuditEvent) => void | Promise<void>;
+export type RedactionEncoding = "plain" | "base64";
+export type SecretBrokerOptions = {
+    /** The adapter the broker delegates fetch / rotate / put to. */
+    adapter: SecretAdapter;
+    /** Audit hook fired on every resolve / rotate / invalidate. */
+    audit?: AuditHook;
+    /**
+     * How long a cached secret stays fresh, in ms. After this, the next
+     * resolve re-hits the adapter. Default 60_000 (1 minute). Set to
+     * `Infinity` to disable TTL — only `rotate` / `invalidate` evict.
+     */
+    cacheTtlMs?: number;
+    /**
+     * Per-name TTL overrides. The override wins over `cacheTtlMs`. Use
+     * a short TTL for high-blast-radius secrets (admin tokens, signing
+     * keys) so a compromised value's lifetime is bounded by the override,
+     * not the global default.
+     */
+    cacheTtlOverrides?: Record<string, number>;
+    /**
+     * Minimum length a cached value must have before `redact` will rewrite
+     * occurrences of it in arbitrary text. Default 8 — short values risk
+     * blanking out coincidental matches (e.g. a short password "abc1"
+     * appearing as a substring of unrelated text).
+     */
+    redactionMinLength?: number;
+    /**
+     * Encodings to redact alongside the plaintext value. Default `['plain']`.
+     * Add `'base64'` to also catch base64-encoded forms — useful when
+     * secrets end up inside JWTs, cookies, or any payload that base64-wraps
+     * a credential.
+     */
+    redactionEncodings?: RedactionEncoding[];
+    /** Override `Date.now` for tests. */
+    clock?: () => number;
+    /**
+     * Optional OpenTelemetry tracer provider. When set, `broker.resolve`
+     * and `broker.rotate` are wrapped in `secrets.resolve` /
+     * `secrets.rotate` spans with `abs.secret.name` +
+     * `abs.secret.fingerprint` attributes. `broker.redact` is NOT
+     * traced — it's called per log line, which would explode span
+     * volume. When omitted, all tracing is a zero-allocation noop.
+     * Added in 0.3.0.
+     */
+    tracerProvider?: TracerProvider;
+};
+/** Listener registered via {@link SecretBroker.onRotate}. */
+export type RotationListener = (event: {
+    name: string;
+    value: string;
+    fingerprint: string;
+    at: number;
+}) => void | Promise<void>;
+export type SecretBroker = {
+    /**
+     * Resolve a secret by name. Returns `null` if the adapter reports
+     * no value. Caches the answer for `cacheTtlMs`.
+     */
+    resolve: (name: string) => Promise<SecretValue | null>;
+    /**
+     * Returns the fingerprint of a value WITHOUT touching the adapter.
+     * Useful for hashing a value the caller already has — e.g. a webhook
+     * payload — to compare against an audit log.
+     */
+    fingerprint: (value: string) => string;
+    /**
+     * Replace every cached secret value found in `text` with
+     * `[REDACTED:name]`. Returns the rewritten text. Subjects shorter than
+     * `redactionMinLength` are skipped.
+     */
+    redact: (text: string) => string;
+    /**
+     * Streaming variant of {@link redact}. Returns a `TransformStream`
+     * that catches secrets even when they're split across chunks (a chunk
+     * boundary in the middle of `sk_live_abc...` would otherwise miss). The
+     * stream keeps a lookback buffer the size of the longest cached secret;
+     * once the buffer outgrows that, the safe-region prefix is emitted.
+     *
+     * Use this on `process.stdout` / `process.stderr` / a tenant log forwarder
+     * so plaintext secrets never reach the sink.
+     */
+    redactStream: () => TransformStream<string, string>;
+    /**
+     * Rotate a secret. Calls `adapter.rotate(name)`, invalidates the cache,
+     * returns the new `{ value, fingerprint }`. Throws if the adapter does
+     * not support rotation. Fires every `onRotate` listener registered for
+     * this name.
+     */
+    rotate: (name: string) => Promise<SecretValue>;
+    /**
+     * Subscribe to rotation events for a specific name. Listener fires
+     * AFTER the new value is in the cache. Returns an unsubscribe handle.
+     * Use this for long-lived connections (DB clients, AI provider SDKs)
+     * that need to swap credentials in-place when rotation lands.
+     */
+    onRotate: (name: string, listener: RotationListener) => () => void;
+    /**
+     * Invalidate one cache entry, or the whole cache when `name` is omitted.
+     */
+    invalidate: (name?: string) => void;
+    /** Tear down the broker — clears the cache; further resolves still hit the adapter. */
+    dispose: () => void;
+    /**
+     * Operator-shaped cumulative counters since `createSecretBroker()`.
+     * Scrape on a 30s interval for tier monitoring + rotation cadence.
+     * Added in 0.2.0.
+     */
+    metrics: () => SecretBrokerMetrics;
+    /**
+     * Refuse new `resolve()` / `rotate()` calls (they reject with
+     * `BrokerDrainedError`); in-flight adapter calls keep running. Use
+     * during graceful shutdown so a tenant whose process is about to
+     * stop doesn't issue a fresh fetch against the secret store mid-
+     * teardown. Symmetric with `runtime.drain()` / `queue.drain()`.
+     * Added in 0.2.0.
+     */
+    drain: () => void;
+};
+/**
+ * Returned by {@link SecretBroker.metrics}. All counters cumulative
+ * since `createSecretBroker()`; cleared by neither `dispose()` nor
+ * `drain()` (so the operator can see what happened pre-shutdown).
+ * Added in 0.2.0.
+ */
+export type SecretBrokerMetrics = {
+    /** `resolve()` calls — including cached hits, misses, and errors. */
+    resolves: number;
+    /** `resolve()` calls served from cache (no adapter hit). */
+    resolveHits: number;
+    /** `resolve()` calls that hit the adapter (cache miss OR expired). */
+    resolveMisses: number;
+    /** `resolve()` calls where the adapter threw. */
+    resolveErrors: number;
+    /** Successful `rotate()` calls. */
+    rotates: number;
+    /** `rotate()` calls where the adapter threw. */
+    rotateErrors: number;
+    /** `invalidate()` calls (per call, regardless of cache size). */
+    invalidations: number;
+    /** `redact()` calls (whether anything was rewritten or not). */
+    redactCalls: number;
+    /**
+     * Distinct (secret, encoding) pairs that triggered a replacement —
+     * NOT total occurrences. A `redact()` call that rewrites the same
+     * key three times in one string bumps this by 1. Useful for
+     * "is anything ever actually getting redacted, or are we configured
+     * for nothing."
+     */
+    redactionsApplied: number;
+    /** Subset of `redactionsApplied` for base64 encoding. */
+    redactionsBase64: number;
+};
+/**
+ * Thrown by `resolve()` / `rotate()` after `drain()` has been called.
+ * Added in 0.2.0.
+ */
+export declare class BrokerDrainedError extends Error {
+    constructor();
+}
+export type InMemoryAdapterOptions = {
+    initial?: Record<string, string>;
+    /** Override the rotation strategy. Default = random 32-char base36 string. */
+    rotate?: (name: string, previous: string | null) => string;
+};
+export declare const inMemoryAdapter: (options?: InMemoryAdapterOptions) => SecretAdapter;
+export type EnvAdapterOptions = {
+    /**
+     * If set, lookups are prefixed before reading from env. e.g.
+     * `prefix: 'ABS_SECRET_'` and `resolve('STRIPE_KEY')` reads `ABS_SECRET_STRIPE_KEY`.
+     * Default `''` (no prefix).
+     */
+    prefix?: string;
+    /** The env object to read from. Default `process.env`. */
+    env?: Record<string, string | undefined>;
+};
+export declare const envAdapter: (options?: EnvAdapterOptions) => SecretAdapter;
+/**
+ * Compose adapters: `fetch` falls through to the first non-null result;
+ * `put` / `rotate` / `remove` go to the first adapter that implements them.
+ */
+export declare const compositeAdapter: (adapters: SecretAdapter[]) => SecretAdapter;
+/** Override for tests; defaults touch disk via `node:fs/promises`. */
+export type EncryptedFileIO = {
+    readFile: (path: string) => Promise<string | undefined>;
+    writeFileAtomic: (path: string, contents: string) => Promise<void>;
+};
+export type EncryptedFileAdapterMasterKey = {
+    type: "passphrase";
+    passphrase: string;
+} | {
+    type: "raw";
+    bytes: Uint8Array;
+};
+export type EncryptedFileAdapterOptions = {
+    /** Absolute or relative path to the encrypted JSON file. */
+    path: string;
+    /**
+     * Master key. Either a `passphrase` (KDF'd via PBKDF2-SHA256 with the
+     * salt stored in the file) or `raw` 32 bytes (no KDF — pass the key
+     * directly, useful when sourced from a vendor secret manager).
+     */
+    key: EncryptedFileAdapterMasterKey;
+    /**
+     * PBKDF2 iterations when `key.type === 'passphrase'`. Default 600_000
+     * (OWASP 2025 recommendation for SHA-256). The chosen value is stored
+     * in the file so future opens use it.
+     */
+    pbkdf2Iterations?: number;
+    /** Override the rotation strategy (matches `inMemoryAdapter`). */
+    rotate?: (name: string, previous: string | null) => string;
+    /** Override file IO (tests). */
+    io?: EncryptedFileIO;
+};
+/**
+ * Durable secret adapter that stores `name → value` in an encrypted
+ * JSON file (AES-256-GCM, per-value random IV). File is safe to commit
+ * to a private repo as long as the master key is kept separately
+ * (1Password, env var, hardware key, etc.).
+ *
+ * Two master-key shapes:
+ *
+ *   - `{ type: 'passphrase', passphrase }` — PBKDF2-SHA256 from the
+ *     passphrase, salt stored in the file. OWASP 2025 default (600k
+ *     iterations); add a stronger one via `pbkdf2Iterations`.
+ *   - `{ type: 'raw', bytes }` — 32 raw bytes. No KDF. Useful when the
+ *     key comes from a vendor secret manager that already gave you
+ *     random bytes.
+ *
+ * Caches decrypted values in memory after first read (consistent with
+ * the broker's caching layer above it).
+ */
+export declare const encryptedFileAdapter: (options: EncryptedFileAdapterOptions) => SecretAdapter;
+export type RotateMasterKeyOptions = {
+    /** Path to the encrypted JSON file (must exist). */
+    path: string;
+    /** Master key the file was written with. */
+    oldKey: EncryptedFileAdapterMasterKey;
+    /** Master key to re-encrypt under. */
+    newKey: EncryptedFileAdapterMasterKey;
+    /**
+     * PBKDF2 iterations for the new passphrase (when `newKey.type ===
+     * 'passphrase'`). Default 600_000. Stored in the rewritten file.
+     */
+    newPbkdf2Iterations?: number;
+    /** Override file IO (tests). */
+    io?: EncryptedFileIO;
+};
+/**
+ * Re-encrypt the entire secrets file under a new master key. Reads
+ * every value with `oldKey`, writes them back encrypted under
+ * `newKey`. Atomic at the file layer (temp + rename); the old file
+ * remains intact if any step fails before the final write.
+ *
+ * Use cases:
+ *   - master passphrase leak: rotate to a new passphrase
+ *   - moving from passphrase to raw-bytes (or vice versa) — e.g.
+ *     graduating from "operator-typed passphrase" to "key sourced
+ *     from a vendor secret manager"
+ *   - periodic master-key rotation as a compliance hygiene measure
+ *
+ * After this returns, any process still holding the old key
+ * will fail to decrypt on next access. Rotate the consumers'
+ * master-key references at the same time you call this.
+ */
+export declare const rotateMasterKey: (options: RotateMasterKeyOptions) => Promise<void>;
+export declare const createSecretBroker: (options: SecretBrokerOptions) => SecretBroker;