@jini-ai/platform 0.3.0 → 0.5.0

package/dist/secrets/keyring.env.d.ts

@@ -0,0 +1,176 @@
+import { type PlatformMessages } from "../messages.js";
+import type { KeyringPort } from "./ports.js";
+/** Environment access belongs to the host; the library never reads ambient process state. */
+export interface RootKeyEnvironmentPort {
+    read(required: {
+        name: string;
+    }): string | undefined;
+}
+/** Host configuration has no implicit env name, file path, permissions, or HKDF salt. */
+export interface EnvOrFileKeyringRequired {
+    /** Live environment reader; key material is resolved and cached on first derivation. */
+    env: RootKeyEnvironmentPort;
+    /** Explicit permission to read the configured file when env material is absent. */
+    allowFileFallback: boolean;
+    /** Explicit permission to create a missing file; fallback must also be enabled. */
+    allowFileAutoGenerate: boolean;
+    /** Wire constant supplied by the host; changing it changes every derived key. */
+    hkdfSalt: string | Uint8Array;
+    /** Name of an env var containing at least 32 bytes of hex-encoded key material. */
+    envVarName: string;
+    /** Explicit path to the file fallback. No runtime-mode or home-directory policy. */
+    keyFilePath: string;
+}
+export interface EnvOrFileKeyringOptions {
+    messages?: PlatformMessages;
+    /** Root-key generation identity; defaults to "v1". */
+    keyId?: string;
+}
+/** Resolves injected env first, then explicitly permitted files; caches the root per instance.
+ * Missing source permissions throw TypeError at construction, before file access.
+ * Derivation rejects absent/invalid material; only explicit fallback plus generation writes a file.
+ * @complexity Construction is O(1); first derivation parses O(k) key characters and caches them.
+ * @example new EnvOrFileKeyring({ env, envVarName, keyFilePath, hkdfSalt, allowFileFallback: false, allowFileAutoGenerate: false })
+ */
+export declare class EnvOrFileKeyring implements KeyringPort {
+    private readonly messages;
+    private readonly env;
+    private readonly envVarName;
+    private readonly keyFilePath;
+    private readonly keyId;
+    private readonly allowFileFallback;
+    private readonly allowFileAutoGenerate;
+    private readonly hkdfSalt;
+    private cachedRootKey;
+    constructor(required: EnvOrFileKeyringRequired, optional?: EnvOrFileKeyringOptions);
+    activeKey(_required: Record<string, never>): Promise<{
+        readonly keyId: string;
+    }>;
+    deriveSigningSecret(input: {
+        workspaceId: string;
+        subscriptionId: string;
+        version: number;
+    }): Promise<Uint8Array>;
+    derive(input: {
+        workspaceId: string;
+        purpose: string;
+        info: string;
+    }): Promise<Uint8Array>;
+    private resolveRootKey;
+    private parseEnvRootKey;
+    private parseFileRootKey;
+}
+/** SHA-256 HKDF, 32 bytes, with info `${workspaceId}:${subscriptionId}:v${version}`. */
+export declare function deriveSigningSecretFromRootKey({ rootKey, input, hkdfSalt }: {
+    rootKey: Uint8Array;
+    input: {
+        workspaceId: string;
+        subscriptionId: string;
+        version: number;
+    };
+    hkdfSalt: string | Uint8Array;
+}): Uint8Array;
+/** SHA-256 HKDF, 32 bytes, with info `${purpose}:${workspaceId}:${info}`. */
+export declare function deriveFromRootKey({ rootKey, input, hkdfSalt }: {
+    rootKey: Uint8Array;
+    input: {
+        workspaceId: string;
+        purpose: string;
+        info: string;
+    };
+    hkdfSalt: string | Uint8Array;
+}): Uint8Array;
+/** Derives from a validated candidate key without reading or writing any host source. */
+export declare class FixedRootKeyKeyring implements KeyringPort {
+    private readonly rootKey;
+    private readonly keyId;
+    private readonly hkdfSalt;
+    constructor(required: {
+        hex: string;
+        hkdfSalt: string | Uint8Array;
+    }, optional?: {
+        keyId?: string;
+    });
+    activeKey(_required: Record<string, never>): Promise<{
+        readonly keyId: string;
+    }>;
+    deriveSigningSecret(input: {
+        workspaceId: string;
+        subscriptionId: string;
+        version: number;
+    }): Promise<Uint8Array>;
+    derive(input: {
+        workspaceId: string;
+        purpose: string;
+        info: string;
+    }): Promise<Uint8Array>;
+}
+export type RootKeyRejection = "empty" | "not-hex" | "odd-length" | "too-short";
+export type ParsedRootKeyHex = {
+    readonly ok: true;
+    readonly hex: string;
+} | {
+    readonly ok: false;
+    readonly reason: RootKeyRejection;
+    readonly hexDigits: number;
+};
+/** Validates trimmed hex of at least 32 bytes without disclosing rejected material. */
+export declare function parseRootKeyHex({ raw }: {
+    raw: string;
+}): ParsedRootKeyHex;
+export declare class UnusableRootKeyError extends Error {
+    readonly source: "env" | "file";
+    readonly reason: RootKeyRejection;
+    constructor(input: {
+        source: "env" | "file";
+        reason: RootKeyRejection;
+        message: string;
+    });
+}
+/** SHA-256 of decoded bytes, truncated to 12 hex digits; never a usable secret. */
+export declare function fingerprintRootKeyHex({ hex }: {
+    hex: string;
+}): string;
+export interface RootKeyStatus {
+    readonly active: boolean;
+    readonly source: "env" | "file" | "none";
+    /** Present only when usable key material exists. */
+    readonly fingerprint?: string;
+    /** A present source failed validation; this differs from an absent source. */
+    readonly invalid?: boolean;
+    readonly reason?: RootKeyRejection;
+    readonly keyFilePath: string;
+}
+export interface InspectRootKeyMaterialOptions {
+    env: RootKeyEnvironmentPort;
+    envVarName: string;
+    keyFilePath: string;
+}
+/** Fresh injected env/file status read, without caching, writes or exposing key material.
+ * @complexity O(k) time/space for k key characters; at most one file read.
+ * @example inspectRootKeyMaterial({ env, envVarName, keyFilePath })
+ */
+export declare function inspectRootKeyMaterial(options: InspectRootKeyMaterialOptions): RootKeyStatus;
+export interface RootKeyReveal extends RootKeyStatus {
+    readonly hex?: string;
+}
+/** Explicit sensitive read through host env/file sources; returns usable key material in the clear.
+ * @complexity O(k) time/space for k key characters; at most one file read and no writes.
+ * @example revealRootKeyMaterial({ env, envVarName, keyFilePath })
+ */
+export declare function revealRootKeyMaterial(options: InspectRootKeyMaterialOptions): RootKeyReveal;
+export declare class RootKeyFileAlreadyExistsError extends Error {
+    constructor({ keyFilePath }: {
+        keyFilePath: string;
+    });
+}
+export interface GeneratedFileRootKey {
+    readonly hex: string;
+    readonly fingerprint: string;
+    readonly keyFilePath: string;
+}
+/** Creates a 32-byte root key at mode 0600; throws RootKeyFileAlreadyExistsError on collisions. */
+export declare function generateFileRootKey(options: {
+    keyFilePath: string;
+}): GeneratedFileRootKey;
+//# sourceMappingURL=keyring.env.d.ts.map

package/dist/secrets/keyring.env.js

@@ -0,0 +1,271 @@
+import { defaultPlatformMessages } from "../messages.js";
+/** Env/file root-key adapter and uncached inspection helpers. Raw keys never enter sealed records.
+ * HKDF salts and source locations belong to the host. File generation refuses existing paths.
+ */
+import { createHash, hkdfSync, randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+const DERIVED_SECRET_LENGTH_BYTES = 32;
+const ROOT_KEY_LENGTH_BYTES = 32;
+/** Resolves injected env first, then explicitly permitted files; caches the root per instance.
+ * Missing source permissions throw TypeError at construction, before file access.
+ * Derivation rejects absent/invalid material; only explicit fallback plus generation writes a file.
+ * @complexity Construction is O(1); first derivation parses O(k) key characters and caches them.
+ * @example new EnvOrFileKeyring({ env, envVarName, keyFilePath, hkdfSalt, allowFileFallback: false, allowFileAutoGenerate: false })
+ */
+export class EnvOrFileKeyring {
+    messages;
+    env;
+    envVarName;
+    keyFilePath;
+    keyId;
+    allowFileFallback;
+    allowFileAutoGenerate;
+    hkdfSalt;
+    cachedRootKey;
+    constructor(required, optional = {}) {
+        requireHostOption(required?.envVarName, "envVarName");
+        requireHostOption(required?.keyFilePath, "keyFilePath");
+        requireHostOption(required?.hkdfSalt, "hkdfSalt");
+        if (typeof required.env?.read !== "function")
+            throw new TypeError("env.read is required");
+        if (typeof required.allowFileFallback !== "boolean")
+            throw new TypeError("allowFileFallback must be an explicit boolean");
+        if (typeof required.allowFileAutoGenerate !== "boolean")
+            throw new TypeError("allowFileAutoGenerate must be an explicit boolean");
+        this.messages = optional.messages ?? defaultPlatformMessages;
+        this.env = required.env;
+        this.hkdfSalt = required.hkdfSalt;
+        this.envVarName = required.envVarName;
+        this.keyFilePath = required.keyFilePath;
+        this.keyId = optional.keyId ?? "v1";
+        this.allowFileFallback = required.allowFileFallback;
+        this.allowFileAutoGenerate = required.allowFileAutoGenerate;
+    }
+    async activeKey(_required) {
+        return { keyId: this.keyId };
+    }
+    async deriveSigningSecret(input) {
+        return deriveSigningSecretFromRootKey({ rootKey: this.resolveRootKey(), input, hkdfSalt: this.hkdfSalt });
+    }
+    async derive(input) {
+        return deriveFromRootKey({ rootKey: this.resolveRootKey(), input, hkdfSalt: this.hkdfSalt });
+    }
+    resolveRootKey() {
+        // Validate env and file through the same parser used by inspection; a status screen and
+        // the sealer must never disagree about whether configured material is a usable root key.
+        // Buffer.from(raw, 'hex') alone can turn malformed text into empty bytes that HKDF accepts,
+        // yielding keys computable from public constants rather than a real root secret.
+        if (this.cachedRootKey)
+            return this.cachedRootKey;
+        const fromEnv = this.env.read({ name: this.envVarName });
+        if (fromEnv) {
+            this.cachedRootKey = this.parseEnvRootKey(fromEnv);
+            return this.cachedRootKey;
+        }
+        if (!this.allowFileFallback) {
+            throw new Error(`no root key: ${this.envVarName} is not set and allowFileFallback is disabled`);
+        }
+        if (existsSync(this.keyFilePath)) {
+            this.cachedRootKey = this.parseFileRootKey(readFileSync(this.keyFilePath, "utf8"));
+            return this.cachedRootKey;
+        }
+        if (!this.allowFileAutoGenerate) {
+            throw new Error(`no root key: ${this.envVarName} is not set, no key file exists at ${this.keyFilePath}, and this instance does not auto-generate one — set the env var, or call generateFileRootKey() explicitly`);
+        }
+        const generated = randomBytes(ROOT_KEY_LENGTH_BYTES);
+        mkdirSync(dirname(this.keyFilePath), { recursive: true });
+        writeFileSync(this.keyFilePath, generated.toString("hex"), { mode: 0o600 });
+        this.cachedRootKey = generated;
+        return this.cachedRootKey;
+    }
+    parseEnvRootKey(raw) {
+        // Legacy env parsing rejected malformed hex but could accept short material: only that
+        // rejection needs the warning that existing credentials may already use these bytes.
+        const parsed = parseRootKeyHex({ raw });
+        if (parsed.ok)
+            return Buffer.from(parsed.hex, "hex");
+        throw new UnusableRootKeyError({
+            source: "env",
+            reason: parsed.reason,
+            message: unusableRootKeyMessage({
+                messages: this.messages,
+                subject: this.envVarName,
+                detail: describeRootKeyRejection(parsed),
+                sealedWarningSubject: parsed.reason === "too-short" ? "this value" : undefined,
+            }),
+        });
+    }
+    parseFileRootKey(raw) {
+        // Legacy file decoding accepted arbitrary content, so every rejected file may have been
+        // used to seal data. Never rewrite or repair it here: replacing bytes orphans those rows.
+        const parsed = parseRootKeyHex({ raw });
+        if (parsed.ok)
+            return Buffer.from(parsed.hex, "hex");
+        throw new UnusableRootKeyError({
+            source: "file",
+            reason: parsed.reason,
+            message: unusableRootKeyMessage({
+                messages: this.messages,
+                subject: `the root key file at ${this.keyFilePath}`,
+                detail: describeRootKeyRejection(parsed),
+                sealedWarningSubject: "this file",
+            }),
+        });
+    }
+}
+/** SHA-256 HKDF, 32 bytes, with info `${workspaceId}:${subscriptionId}:v${version}`. */
+// Both installed and candidate keyrings use this derivation so checking a candidate tests the
+// exact secret that persisted root material would produce, not a parallel approximation.
+export function deriveSigningSecretFromRootKey({ rootKey, input, hkdfSalt }) {
+    const info = `${input.workspaceId}:${input.subscriptionId}:v${input.version}`;
+    return new Uint8Array(hkdfSync("sha256", rootKey, hkdfSalt, info, DERIVED_SECRET_LENGTH_BYTES));
+}
+/** SHA-256 HKDF, 32 bytes, with info `${purpose}:${workspaceId}:${info}`. */
+// purpose is part of HKDF info, not display metadata: it separates generic uses from signing secrets.
+export function deriveFromRootKey({ rootKey, input, hkdfSalt }) {
+    const effectiveInfo = `${input.purpose}:${input.workspaceId}:${input.info}`;
+    return new Uint8Array(hkdfSync("sha256", rootKey, hkdfSalt, effectiveInfo, DERIVED_SECRET_LENGTH_BYTES));
+}
+/** Derives from a validated candidate key without reading or writing any host source. */
+export class FixedRootKeyKeyring {
+    rootKey;
+    keyId;
+    hkdfSalt;
+    constructor(required, optional = {}) {
+        requireHostOption(required?.hkdfSalt, "hkdfSalt");
+        this.hkdfSalt = required.hkdfSalt;
+        this.keyId = optional.keyId ?? "v1";
+        const parsed = parseRootKeyHex({ raw: required.hex });
+        if (!parsed.ok)
+            throw new Error(`FixedRootKeyKeyring: not a valid root key (${parsed.reason})`);
+        this.rootKey = Buffer.from(parsed.hex, "hex");
+    }
+    async activeKey(_required) {
+        return { keyId: this.keyId };
+    }
+    async deriveSigningSecret(input) {
+        return deriveSigningSecretFromRootKey({ rootKey: this.rootKey, input, hkdfSalt: this.hkdfSalt });
+    }
+    async derive(input) {
+        return deriveFromRootKey({ rootKey: this.rootKey, input, hkdfSalt: this.hkdfSalt });
+    }
+}
+const HEX_KEY_PATTERN = /^[0-9a-f]+$/i;
+/** Validates trimmed hex of at least 32 bytes without disclosing rejected material. */
+export function parseRootKeyHex({ raw }) {
+    const hex = raw.trim();
+    if (hex.length === 0)
+        return { ok: false, reason: "empty", hexDigits: 0 };
+    if (!HEX_KEY_PATTERN.test(hex))
+        return { ok: false, reason: "not-hex", hexDigits: hex.length };
+    if (hex.length % 2 !== 0)
+        return { ok: false, reason: "odd-length", hexDigits: hex.length };
+    if (hex.length < ROOT_KEY_LENGTH_BYTES * 2)
+        return { ok: false, reason: "too-short", hexDigits: hex.length };
+    return { ok: true, hex };
+}
+const ROOT_KEY_REJECTION_DETAIL = {
+    empty: () => "it is empty",
+    "not-hex": () => 'it contains characters that are not hex digits (only 0-9 and a-f are allowed; a "0x" prefix, whitespace inside the value, or a base64 or PEM body all fail this)',
+    "odd-length": (hexDigits) => `it has an odd number of hex digits (${hexDigits}), so it does not describe whole bytes — usually a partial write or a truncated copy`,
+    "too-short": (hexDigits) => `it is ${hexDigits / 2} bytes (${hexDigits} hex digits); a root key must be at least ${ROOT_KEY_LENGTH_BYTES} bytes (${ROOT_KEY_LENGTH_BYTES * 2} hex digits) — usually a truncated copy`,
+};
+function describeRootKeyRejection(parsed) {
+    return ROOT_KEY_REJECTION_DETAIL[parsed.reason](parsed.hexDigits);
+}
+function unusableRootKeyMessage(input) {
+    const refusal = `${input.subject} is not usable as a root key: ${input.detail}. The keyring refuses to derive any key material from it rather than sealing under a shortened or empty key.`;
+    if (input.sealedWarningSubject === undefined)
+        return refusal;
+    return (`${refusal} ${(input.messages ?? defaultPlatformMessages).rootKeySealedWarning({ subject: input.sealedWarningSubject })}` +
+        `not from a real ${ROOT_KEY_LENGTH_BYTES}-byte key, so those stored credentials are not protected as intended — with empty or very short material the derived key is computable from published constants. ` +
+        `Replacing or regenerating the key will NOT restore them; it will make them unreadable. ` +
+        `Do not overwrite, delete or regenerate this key until you have decided what to do with the credentials already stored.`);
+}
+export class UnusableRootKeyError extends Error {
+    source;
+    reason;
+    constructor(input) {
+        super(input.message);
+        this.name = "UnusableRootKeyError";
+        this.source = input.source;
+        this.reason = input.reason;
+    }
+}
+/** SHA-256 of decoded bytes, truncated to 12 hex digits; never a usable secret. */
+export function fingerprintRootKeyHex({ hex }) {
+    return createHash("sha256").update(Buffer.from(hex, "hex")).digest("hex").slice(0, 12);
+}
+function readActiveRootKeyMaterial(input) {
+    const fromEnv = input.env.read({ name: input.envVarName });
+    if (fromEnv)
+        return toActiveRootKeyMaterial("env", fromEnv);
+    if (existsSync(input.keyFilePath))
+        return toActiveRootKeyMaterial("file", readFileSync(input.keyFilePath, "utf8"));
+    return { source: "none" };
+}
+function toActiveRootKeyMaterial(source, raw) {
+    const parsed = parseRootKeyHex({ raw });
+    return parsed.ok ? { source, hex: parsed.hex } : { source, invalid: true, reason: parsed.reason };
+}
+/** Fresh injected env/file status read, without caching, writes or exposing key material.
+ * @complexity O(k) time/space for k key characters; at most one file read.
+ * @example inspectRootKeyMaterial({ env, envVarName, keyFilePath })
+ */
+export function inspectRootKeyMaterial(options) {
+    const envVarName = options.envVarName;
+    const keyFilePath = options.keyFilePath;
+    const raw = readActiveRootKeyMaterial({ env: options.env, envVarName, keyFilePath });
+    if (raw.hex)
+        return { active: true, source: raw.source, fingerprint: fingerprintRootKeyHex({ hex: raw.hex }), keyFilePath };
+    return { active: false, source: raw.source, ...invalidFields(raw), keyFilePath };
+}
+function invalidFields(raw) {
+    return raw.invalid ? { invalid: true, reason: raw.reason } : {};
+}
+/** Explicit sensitive read through host env/file sources; returns usable key material in the clear.
+ * @complexity O(k) time/space for k key characters; at most one file read and no writes.
+ * @example revealRootKeyMaterial({ env, envVarName, keyFilePath })
+ */
+export function revealRootKeyMaterial(options) {
+    const envVarName = options.envVarName;
+    const keyFilePath = options.keyFilePath;
+    const raw = readActiveRootKeyMaterial({ env: options.env, envVarName, keyFilePath });
+    if (raw.hex)
+        return { active: true, source: raw.source, hex: raw.hex, fingerprint: fingerprintRootKeyHex({ hex: raw.hex }), keyFilePath };
+    return { active: false, source: raw.source, ...invalidFields(raw), keyFilePath };
+}
+export class RootKeyFileAlreadyExistsError extends Error {
+    constructor({ keyFilePath }) {
+        super(`a root key file already exists at ${keyFilePath} — generate never overwrites an existing key`);
+        this.name = "RootKeyFileAlreadyExistsError";
+    }
+}
+/** Creates a 32-byte root key at mode 0600; throws RootKeyFileAlreadyExistsError on collisions. */
+export function generateFileRootKey(options) {
+    const keyFilePath = options.keyFilePath;
+    const generated = randomBytes(ROOT_KEY_LENGTH_BYTES);
+    const hex = generated.toString("hex");
+    mkdirSync(dirname(keyFilePath), { recursive: true, mode: 0o700 });
+    try {
+        writeFileSync(keyFilePath, hex, { mode: 0o600, flag: "wx" });
+    }
+    catch (err) {
+        if (isAlreadyExistsError(err))
+            throw new RootKeyFileAlreadyExistsError({ keyFilePath });
+        throw err;
+    }
+    return { hex, fingerprint: fingerprintRootKeyHex({ hex }), keyFilePath };
+}
+function isAlreadyExistsError(err) {
+    if (typeof err !== "object" || err === null || !("code" in err))
+        return false;
+    const code = err.code;
+    return code === "EEXIST" || code === "ELOOP";
+}
+function requireHostOption(value, name) {
+    if (value === undefined || value === null)
+        throw new TypeError(`${name} is required`);
+}
+//# sourceMappingURL=keyring.env.js.map

package/dist/secrets/keyring.memory.d.ts

@@ -0,0 +1,10 @@
+import { FixedRootKeyKeyring } from "./keyring.env.js";
+/** Real HKDF over an ephemeral 32-byte key, with no environment or filesystem resolution. */
+export declare class InMemoryKeyring extends FixedRootKeyKeyring {
+    constructor(required: {
+        hkdfSalt: string | Uint8Array;
+    }, optional?: {
+        keyId?: string;
+    });
+}
+//# sourceMappingURL=keyring.memory.d.ts.map

package/dist/secrets/keyring.memory.js

@@ -0,0 +1,9 @@
+import { randomBytes } from "node:crypto";
+import { FixedRootKeyKeyring } from "./keyring.env.js";
+/** Real HKDF over an ephemeral 32-byte key, with no environment or filesystem resolution. */
+export class InMemoryKeyring extends FixedRootKeyKeyring {
+    constructor(required, optional = {}) {
+        super({ hex: randomBytes(32).toString("hex"), hkdfSalt: required.hkdfSalt }, optional);
+    }
+}
+//# sourceMappingURL=keyring.memory.js.map

package/dist/secrets/ports.d.ts

@@ -0,0 +1,33 @@
+import type { SealedSecret } from "./types.js";
+/** Generation identity only: a sealed record never carries root-key bytes. */
+export interface RootKeyHandle {
+    readonly keyId: string;
+}
+/** Swappable root-key adapter with two stable HKDF info layouts. */
+export interface KeyringPort {
+    activeKey(_required: Record<string, never>): Promise<RootKeyHandle>;
+    deriveSigningSecret(input: {
+        workspaceId: string;
+        subscriptionId: string;
+        version: number;
+    }): Promise<Uint8Array>;
+    derive(input: {
+        workspaceId: string;
+        purpose: string;
+        info: string;
+    }): Promise<Uint8Array>;
+}
+/** AAD binds new ciphertext to its context; absent open AAD supports historical records only. */
+export interface SecretSealerPort {
+    seal(input: {
+        plaintext: string;
+        key: RootKeyHandle;
+        aad: string;
+    }): Promise<SealedSecret>;
+    open(input: {
+        sealed: SealedSecret;
+    }, optional?: {
+        aad?: string;
+    }): Promise<string>;
+}
+//# sourceMappingURL=ports.d.ts.map

package/dist/secrets/ports.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ports.js.map

package/dist/secrets/secret-sealer.aesgcm.d.ts

@@ -0,0 +1,22 @@
+import type { KeyringPort, RootKeyHandle, SecretSealerPort } from "./ports.js";
+import type { SealedSecret } from "./types.js";
+export declare class AesGcmSecretSealer implements SecretSealerPort {
+    private readonly keyring;
+    constructor({ keyring }: {
+        keyring: KeyringPort;
+    });
+    /** Encrypts under the requested generation with a fresh IV; AAD must be reconstructed on open. */
+    seal(input: {
+        plaintext: string;
+        key: RootKeyHandle;
+        aad: string;
+    }): Promise<SealedSecret>;
+    /** Opens under the envelope's generation. Wrong key, tag, nonce, or AAD fails authentication. */
+    open(input: {
+        sealed: SealedSecret;
+    }, { aad }?: {
+        aad?: string;
+    }): Promise<string>;
+    private deriveAesKey;
+}
+//# sourceMappingURL=secret-sealer.aesgcm.d.ts.map

package/dist/secrets/secret-sealer.aesgcm.js

@@ -0,0 +1,64 @@
+/** AES-256-GCM with a fresh 12-byte IV and ciphertext || 16-byte tag, both base64 encoded.
+ * Uses purpose "secret-sealer.v1" and scope "secret-sealer" for HKDF domain separation.
+ * Seal requires context AAD; open accepts absent AAD solely for historical unbound records.
+ */
+import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
+const ALG = "aes-256-gcm";
+const IV_LENGTH_BYTES = 12;
+const AUTH_TAG_LENGTH_BYTES = 16;
+const SEALER_PURPOSE = "secret-sealer.v1";
+const SEALER_KEY_SCOPE = "secret-sealer";
+export class AesGcmSecretSealer {
+    // Derive one key per root generation, not per tenant. Data-layer ownership checks and context AAD
+    // must prevent ciphertext substitution between rows; the shared encryption key alone cannot.
+    // Root keys stay behind handles, and the purpose separates this HKDF domain from signing/tokens.
+    // Exercise real GCM with an in-memory keyring: a plaintext fake would miss authentication failures.
+    keyring;
+    constructor({ keyring }) { this.keyring = keyring; }
+    /** Encrypts under the requested generation with a fresh IV; AAD must be reconstructed on open. */
+    async seal(input) {
+        if (typeof input.aad !== "string")
+            throw new TypeError("AesGcmSecretSealer: aad must be a string");
+        const aesKey = await this.deriveAesKey(input.key);
+        const iv = randomBytes(IV_LENGTH_BYTES);
+        // GCM must never reuse an IV under the same key. AAD is authenticated but not stored in the
+        // envelope, so callers must reconstruct the byte-identical context when opening the record.
+        const cipher = createCipheriv(ALG, aesKey, iv);
+        cipher.setAAD(Buffer.from(input.aad, "utf8"));
+        const ciphertext = Buffer.concat([cipher.update(input.plaintext, "utf8"), cipher.final()]);
+        const authTag = cipher.getAuthTag();
+        return {
+            keyId: input.key.keyId,
+            ciphertext: Buffer.concat([ciphertext, authTag]).toString("base64"),
+            nonce: iv.toString("base64"),
+            alg: ALG,
+        };
+    }
+    /** Opens under the envelope's generation. Wrong key, tag, nonce, or AAD fails authentication. */
+    async open(input, { aad } = {}) {
+        if (input.sealed.alg !== ALG) {
+            throw new Error(`AesGcmSecretSealer cannot open alg '${input.sealed.alg}' (expected '${ALG}')`);
+        }
+        const aesKey = await this.deriveAesKey({ keyId: input.sealed.keyId });
+        // Use the stored generation, not the active one, so rotation does not strand older ciphertext.
+        // Derivation/authentication failures propagate; there is no plaintext or partial-output fallback.
+        const iv = Buffer.from(input.sealed.nonce, "base64");
+        const combined = Buffer.from(input.sealed.ciphertext, "base64");
+        if (combined.length < AUTH_TAG_LENGTH_BYTES) {
+            throw new Error("AesGcmSecretSealer: ciphertext too short to contain an auth tag");
+        }
+        const authTag = combined.subarray(combined.length - AUTH_TAG_LENGTH_BYTES);
+        const ciphertext = combined.subarray(0, combined.length - AUTH_TAG_LENGTH_BYTES);
+        const decipher = createDecipheriv(ALG, aesKey, iv);
+        if (aad !== undefined) {
+            decipher.setAAD(Buffer.from(aad, "utf8"));
+        }
+        decipher.setAuthTag(authTag);
+        const plaintext = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+        return plaintext.toString("utf8");
+    }
+    async deriveAesKey(key) {
+        return this.keyring.derive({ workspaceId: SEALER_KEY_SCOPE, purpose: SEALER_PURPOSE, info: key.keyId });
+    }
+}
+//# sourceMappingURL=secret-sealer.aesgcm.js.map

package/dist/secrets/testing.d.ts

@@ -0,0 +1,4 @@
+export { InMemoryKeyring } from "./keyring.memory.js";
+export { FixedRootKeyKeyring } from "./keyring.env.js";
+export { InMemoryVendorCredentialSetRepo } from "./credential-sets/repo.memory.js";
+//# sourceMappingURL=testing.d.ts.map

package/dist/secrets/testing.js

@@ -0,0 +1,4 @@
+export { InMemoryKeyring } from "./keyring.memory.js";
+export { FixedRootKeyKeyring } from "./keyring.env.js";
+export { InMemoryVendorCredentialSetRepo } from "./credential-sets/repo.memory.js";
+//# sourceMappingURL=testing.js.map

package/dist/secrets/types.d.ts

@@ -0,0 +1,10 @@
+/** Persisted envelope: base64 ciphertext followed by the GCM tag, plus a base64 IV. */
+export interface SealedSecret {
+    keyId: string;
+    /** Base64 of encrypted bytes followed by the 16-byte authentication tag. */
+    ciphertext: string;
+    /** Base64 of the 12-byte IV. */
+    nonce: string;
+    alg: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/secrets/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/shell.d.ts

@@ -1,12 +1,15 @@
 /**
  * @module shell
  *
- * Buffered command execution that re-enters the user's login shell. A daemon
+ * Buffered command execution through the user's selected shell. A daemon
  * process's own `PATH` frequently lacks entries a shell profile adds (a
  * version manager's shims, a package-manager-installed CLI, a Homebrew
  * prefix), so a plain `execFile` against a bare command name can fail even
  * though the same command works fine in the user's terminal. Routing through
- * `$SHELL -c "..."` re-sources that PATH before running the command.
+ * `$SHELL -c "..."` preserves the daemon's current PATH before running the
+ * command; it does not load login profiles or recover profile-only entries.
+ * The host must supply those entries in its environment when needed. A login
+ * invocation could reset PATH and hide wrapped command shims or test fakes.
  *
  * Depends on nothing else in this package; owns no process lifecycle beyond
  * the single buffered child it spawns per call.
@@ -31,10 +34,11 @@ export type BufferedCommandResult = {
  */
 export declare function execFileBuffered(command: string, args: readonly string[], opts?: ExecFileOptions): Promise<BufferedCommandResult>;
 /**
- * Run an arbitrary command re-entering the user's login shell (via
- * `$SHELL -c`) so shell-profile-only `PATH` entries are visible, then buffer
- * its output. Falls back to a direct `execFile` on Windows, where there is no
- * equivalent login-shell PATH gap.
+ * Run an arbitrary command through the user's selected shell (via
+ * `$SHELL -c`), explicitly preserving the current `process.env.PATH`, then
+ * buffer its output. The historical name is retained for compatibility;
+ * this non-login invocation does not load shell-profile-only PATH entries.
+ * Falls back to a direct `execFile` on Windows.
  *
  * @param command - The executable to run.
  * @param args - Arguments to pass to the executable.