@oscharko-dev/keiko-security 0.2.0

package/dist/secret-vault.js

@@ -0,0 +1,271 @@
+// Local secret vault — encrypted-at-rest, multi-entry storage for local runtime credentials
+// (Issue #1320, Epic #1319).
+//
+// This is the generalised sibling of the single-value Figma PAT vault (figmaTokenStore.ts) and the
+// MemoriaViva memory vault (ADR-0035): all three seal their secrets at rest with the shared
+// AES-256-GCM secretbox primitive and resolve a 32-byte key with the same env -> OS-keychain ->
+// keyfile precedence. The difference here is cardinality: a model gateway can carry several provider
+// credentials, so this store keeps a sealed map of `reference -> sealed(secret)` rather than one
+// sealed value. References are opaque, NON-SECRET identifiers held alongside the sealed material; the
+// plaintext secret NEVER touches disk, an error message, a log line, or a return value other than
+// get().
+//
+// Key precedence (resolveLocalVaultKey), namespaced per domain so it never collides with another
+// vault's key:
+//   1. <envVarName>     — base64 of exactly 32 bytes. Explicit operator override; key lives outside
+//                         the vault directory entirely (strongest tier).
+//   2. macOS Keychain   — generic password under <keychainService>. The OS protects the key.
+//   3. Keyfile          — <vaultDir>/<keyfileName>, mode 0600. Weakest tier (key next to store).
+//
+// Replay across vaults is prevented by key separation, not by the AAD: every vault resolves a
+// DISTINCT key (distinct env var, keychain service, and keyfile), so a ciphertext sealed for one
+// vault fails GCM authentication when opened with another vault's key regardless of the shared AAD.
+import { execFileSync } from "node:child_process";
+import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, renameSync, rmSync, unlinkSync, writeFileSync, } from "node:fs";
+import { randomBytes } from "node:crypto";
+import { userInfo } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { isSealed, openString, sealString } from "./secretbox.js";
+const KEY_BYTES = 32;
+const STORE_VERSION = 1;
+export const NO_LOCAL_VAULT_KEYCHAIN = () => undefined;
+function decodeKeyOrThrow(raw) {
+    const decoded = Buffer.from(raw, "base64");
+    if (decoded.length !== KEY_BYTES) {
+        // Secret-free message: never echo the (possibly partial) key material.
+        throw new Error("secret vault key must be base64 of exactly 32 bytes");
+    }
+    return decoded;
+}
+function keyFromEnv(env, envVarName) {
+    const raw = env[envVarName];
+    if (raw === undefined || raw.length === 0)
+        return undefined;
+    return decodeKeyOrThrow(raw);
+}
+function ensureDirHardened(dir) {
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+    if (process.platform === "win32")
+        return;
+    try {
+        chmodSync(dir, 0o700);
+    }
+    catch {
+        // Best-effort: a parent-owned directory we cannot chmod beats a hard failure.
+    }
+}
+function chmodIfPresent(path, mode) {
+    if (process.platform === "win32")
+        return;
+    try {
+        chmodSync(path, mode);
+    }
+    catch {
+        // Best-effort hardening.
+    }
+}
+function defaultKeychainCommandRunner(args) {
+    return execFileSync("security", args, { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+}
+// Builds the default keychain-backed key access for a service. Exported with an injectable runner so
+// the reader/generate branches are deterministically testable without the real login keychain.
+export function createKeychainVaultKeyAccess(keychainService, runCommand = defaultKeychainCommandRunner) {
+    return () => {
+        if (process.platform !== "darwin")
+            return undefined;
+        const account = userInfo().username;
+        try {
+            const found = runCommand([
+                "find-generic-password",
+                "-s",
+                keychainService,
+                "-a",
+                account,
+                "-w",
+            ]).trim();
+            return decodeKeyOrThrow(found);
+        }
+        catch {
+            return generateKeychainKey(keychainService, account, runCommand);
+        }
+    };
+}
+function generateKeychainKey(keychainService, account, runCommand) {
+    const key = randomBytes(KEY_BYTES);
+    try {
+        runCommand([
+            "add-generic-password",
+            "-s",
+            keychainService,
+            "-a",
+            account,
+            "-w",
+            key.toString("base64"),
+        ]);
+        return key;
+    }
+    catch {
+        return undefined;
+    }
+}
+function keyFromKeyfile(vaultDir, keyfileName) {
+    const keyfile = resolve(vaultDir, keyfileName);
+    // Refuse to read or write the key through a symlinked path segment so a hostile symlink cannot
+    // redirect key material outside the hardened vault directory.
+    assertNoSymlinkedPathSegments(keyfile);
+    ensureDirHardened(dirname(keyfile));
+    assertNoSymlinkedPathSegments(keyfile);
+    if (existsSync(keyfile)) {
+        return decodeKeyOrThrow(readFileSync(keyfile, "utf8").trim());
+    }
+    const key = randomBytes(KEY_BYTES);
+    writeFileSync(keyfile, key.toString("base64"), { mode: 0o600 });
+    chmodIfPresent(keyfile, 0o600);
+    return key;
+}
+export function resolveLocalVaultKey(options) {
+    const fromEnv = keyFromEnv(options.env, options.envVarName);
+    if (fromEnv !== undefined)
+        return { key: fromEnv, source: "env" };
+    const keychainAccess = options.keychainAccess ?? createKeychainVaultKeyAccess(options.keychainService);
+    const fromKeychain = keychainAccess();
+    if (fromKeychain !== undefined)
+        return { key: fromKeychain, source: "keychain" };
+    return { key: keyFromKeyfile(options.vaultDir, options.keyfileName), source: "keyfile" };
+}
+function assertNoSymlinkedPathSegments(resolvedPath) {
+    let current = resolvedPath;
+    while (current !== dirname(current)) {
+        if (isSymlink(current)) {
+            throw new Error("refusing to write secret vault through a symlinked path");
+        }
+        current = dirname(current);
+    }
+}
+function isSymlink(path) {
+    try {
+        return lstatSync(path).isSymbolicLink();
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return false;
+        }
+        throw error;
+    }
+}
+function isStoreFile(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const record = value;
+    if (record.version !== STORE_VERSION)
+        return false;
+    const entries = record.entries;
+    if (typeof entries !== "object" || entries === null || Array.isArray(entries))
+        return false;
+    return Object.values(entries).every((entry) => typeof entry === "string");
+}
+function readStore(storePath) {
+    const resolvedPath = resolve(storePath);
+    assertNoSymlinkedPathSegments(resolvedPath);
+    if (!existsSync(resolvedPath))
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(resolvedPath, "utf8"));
+    }
+    catch {
+        // A non-JSON store is treated as empty so a corrupt index never crashes resolution; the entries
+        // it would have held simply resolve to undefined and surface as an honest "missing credential".
+        return {};
+    }
+    return isStoreFile(parsed) ? { ...parsed.entries } : {};
+}
+// Lists the references held in a sealed store WITHOUT resolving a vault key — a pure read over the
+// non-secret index. Used by callers that must reconcile config references against vaulted secrets
+// (e.g. preserve-existing persistence and `keiko repair`) without triggering key generation or
+// decryption. Returns an empty array for a missing or corrupt store.
+export function readLocalVaultReferences(storePath) {
+    return Object.keys(readStore(storePath));
+}
+// Atomic, crash-safe write: a fresh temp file in the same directory is written with 0600 and renamed
+// over the target so a reader never observes a partially written store. Mirrors savePrivateJson.
+function writeStore(storePath, entries) {
+    const resolvedPath = resolve(storePath);
+    const dir = dirname(resolvedPath);
+    // Check both before and after directory creation (mirrors private-json.ts): the first guards an
+    // already-symlinked path, the second narrows the window where a parent could be swapped between
+    // dir creation and the atomic rename. The atomic temp-then-rename below remains the real guarantee.
+    assertNoSymlinkedPathSegments(resolvedPath);
+    ensureDirHardened(dir);
+    assertNoSymlinkedPathSegments(resolvedPath);
+    const payload = { version: STORE_VERSION, entries };
+    const tempPath = join(dir, `.secret-vault.${String(process.pid)}.${randomBytes(8).toString("hex")}.tmp`);
+    try {
+        writeFileSync(tempPath, `${JSON.stringify(payload, null, 2)}\n`, {
+            encoding: "utf8",
+            flag: "wx",
+            mode: 0o600,
+        });
+        chmodIfPresent(tempPath, 0o600);
+        renameSync(tempPath, resolvedPath);
+        chmodIfPresent(resolvedPath, 0o600);
+    }
+    finally {
+        if (existsSync(tempPath)) {
+            try {
+                unlinkSync(tempPath);
+            }
+            catch {
+                // Best-effort cleanup only.
+            }
+        }
+    }
+}
+export function createLocalSecretVault(deps) {
+    const { key, storePath } = deps;
+    const resolvedStorePath = resolve(storePath);
+    const get = (reference) => {
+        const envelope = readStore(resolvedStorePath)[reference];
+        if (envelope === undefined || !isSealed(envelope))
+            return undefined;
+        return openString(key, envelope);
+    };
+    const set = (reference, secret) => {
+        const entries = readStore(resolvedStorePath);
+        entries[reference] = sealString(key, secret);
+        writeStore(resolvedStorePath, entries);
+    };
+    const replaceAll = (next) => {
+        const entries = {};
+        for (const [reference, secret] of next) {
+            entries[reference] = sealString(key, secret);
+        }
+        if (Object.keys(entries).length === 0) {
+            assertNoSymlinkedPathSegments(resolvedStorePath);
+            rmSync(resolvedStorePath, { force: true });
+            return;
+        }
+        writeStore(resolvedStorePath, entries);
+    };
+    const remove = (reference) => {
+        const entries = readStore(resolvedStorePath);
+        if (!(reference in entries))
+            return;
+        const next = {};
+        for (const [storedRef, sealed] of Object.entries(entries)) {
+            if (storedRef !== reference) {
+                next[storedRef] = sealed;
+            }
+        }
+        if (Object.keys(next).length === 0) {
+            assertNoSymlinkedPathSegments(resolvedStorePath);
+            rmSync(resolvedStorePath, { force: true });
+            return;
+        }
+        writeStore(resolvedStorePath, next);
+    };
+    const has = (reference) => reference in readStore(resolvedStorePath);
+    const list = () => Object.keys(readStore(resolvedStorePath));
+    return { get, set, replaceAll, delete: remove, has, list };
+}

package/dist/secretbox.d.ts

@@ -0,0 +1,6 @@
+export declare function sealString(key: Buffer, plaintext: string): string;
+export declare function openString(key: Buffer, envelope: string): string;
+export declare function sealBytes(key: Buffer, buf: Buffer): Buffer;
+export declare function openBytes(key: Buffer, envelope: Buffer): Buffer;
+export declare function isSealed(value: string): boolean;
+//# sourceMappingURL=secretbox.d.ts.map

package/dist/secretbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secretbox.d.ts","sourceRoot":"","sources":["../src/secretbox.ts"],"names":[],"mappings":"AA2CA,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAKjE;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAgBhE;AAED,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAI1D;AAED,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAS/D;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAE/C"}

package/dist/secretbox.js

@@ -0,0 +1,80 @@
+// AES-256-GCM authenticated encryption primitive — the leaf crypto boundary for at-rest secrecy.
+// Two envelope formats share one key and one AAD so a value sealed by either path is bound to this
+// domain and cannot be replayed into another:
+//
+//   string envelope:  "kv1.<base64url(nonce12)>.<base64url(ciphertext||tag16)>"
+//   binary envelope:  0x01 || nonce12 || ciphertext || tag16   (one Buffer, no separators)
+//
+// GCM gives confidentiality AND integrity: open() recomputes the 16-byte auth tag and throws on
+// any mismatch, so a tampered ciphertext or a wrong key both fail loudly (never silent corruption).
+// The nonce is a fresh 12 random bytes per call — the GCM-safe size, and random-per-call keeps us
+// far from the birthday bound for the local single-DB write volume in scope. AAD pins every
+// envelope to "keiko-memory-v1" so a ciphertext lifted from another keiko surface won't open here.
+import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
+import { SecretboxError } from "./errors/secretbox.js";
+const STRING_PREFIX = "kv1.";
+const BINARY_VERSION = 0x01;
+const NONCE_BYTES = 12;
+const TAG_BYTES = 16;
+const ALGORITHM = "aes-256-gcm";
+const AAD = Buffer.from("keiko-memory-v1");
+function encrypt(key, nonce, plaintext) {
+    const cipher = createCipheriv(ALGORITHM, key, nonce, { authTagLength: TAG_BYTES });
+    cipher.setAAD(AAD);
+    const ct = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+    return { ct, tag: cipher.getAuthTag() };
+}
+// All decrypt failures funnel through here as a single SecretboxError class — Node throws a generic
+// Error on auth-tag mismatch, which we normalise so callers branch on the type, not the message.
+function decrypt(key, nonce, ct, tag) {
+    const decipher = createDecipheriv(ALGORITHM, key, nonce, { authTagLength: TAG_BYTES });
+    decipher.setAAD(AAD);
+    decipher.setAuthTag(tag);
+    try {
+        return Buffer.concat([decipher.update(ct), decipher.final()]);
+    }
+    catch {
+        throw new SecretboxError("secretbox: authentication failed (wrong key or tampered data)");
+    }
+}
+export function sealString(key, plaintext) {
+    const nonce = randomBytes(NONCE_BYTES);
+    const { ct, tag } = encrypt(key, nonce, Buffer.from(plaintext, "utf8"));
+    const body = Buffer.concat([ct, tag]);
+    return `${STRING_PREFIX}${nonce.toString("base64url")}.${body.toString("base64url")}`;
+}
+export function openString(key, envelope) {
+    if (!isSealed(envelope)) {
+        throw new SecretboxError("secretbox: envelope is missing the kv1 prefix");
+    }
+    const parts = envelope.split(".");
+    if (parts.length !== 3) {
+        throw new SecretboxError("secretbox: envelope must have three parts");
+    }
+    const nonce = Buffer.from(parts[1] ?? "", "base64url");
+    const body = Buffer.from(parts[2] ?? "", "base64url");
+    if (nonce.length !== NONCE_BYTES || body.length < TAG_BYTES) {
+        throw new SecretboxError("secretbox: envelope nonce or body length is invalid");
+    }
+    const ct = body.subarray(0, body.length - TAG_BYTES);
+    const tag = body.subarray(body.length - TAG_BYTES);
+    return decrypt(key, nonce, ct, tag).toString("utf8");
+}
+export function sealBytes(key, buf) {
+    const nonce = randomBytes(NONCE_BYTES);
+    const { ct, tag } = encrypt(key, nonce, buf);
+    return Buffer.concat([Buffer.from([BINARY_VERSION]), nonce, ct, tag]);
+}
+export function openBytes(key, envelope) {
+    const minLength = 1 + NONCE_BYTES + TAG_BYTES;
+    if (envelope.length < minLength || envelope[0] !== BINARY_VERSION) {
+        throw new SecretboxError("secretbox: binary envelope is malformed or has an unknown version");
+    }
+    const nonce = envelope.subarray(1, 1 + NONCE_BYTES);
+    const ct = envelope.subarray(1 + NONCE_BYTES, envelope.length - TAG_BYTES);
+    const tag = envelope.subarray(envelope.length - TAG_BYTES);
+    return decrypt(key, nonce, ct, tag);
+}
+export function isSealed(value) {
+    return value.startsWith(STRING_PREFIX);
+}

package/dist/secrets.d.ts

@@ -0,0 +1,4 @@
+export type EnvSource = Readonly<Record<string, string | undefined>>;
+export declare function isKeikoApiKeyEnvName(name: string): boolean;
+export declare function keikoApiKeySecretValues(env: EnvSource): readonly string[];
+//# sourceMappingURL=secrets.d.ts.map

package/dist/secrets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secrets.d.ts","sourceRoot":"","sources":["../src/secrets.ts"],"names":[],"mappings":"AAYA,MAAM,MAAM,SAAS,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;AASrE,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAK1D;AAMD,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,SAAS,GAAG,SAAS,MAAM,EAAE,CAQzE"}

package/dist/secrets.js

@@ -0,0 +1,34 @@
+// Centralised secret-collection helpers used by the BFF, CLI, and evaluation entrypoints to feed
+// `createAuditRedactor` with the exact apiKey values held in the environment. Pure functions: no
+// IO, no logging, no dependency on UI/CLI/gateway shapes. Consumers compose these with their own
+// config secrets (provider apiKey values) before calling the redactor builder.
+//
+// Why these helpers exist here, not in each caller: prior to extraction the BFF and the CLI
+// evaluator carried byte-identical copies of `isKeikoApiKeyEnvName` and the env-walk that fed
+// `redactionSecrets`/`keikoApiKeySecrets` — a single behavioural drift would have left one
+// surface less protected than the other (AC #1: no API token newly exposed). Centralising the
+// detector and the collector keeps every caller scrubbing the same names.
+// Returns true iff `name` matches the conventional KEIKO env-var shape that carries a model
+// provider API key:
+//   - KEIKO_DEFAULT_API_KEY  (the fallback used when no per-model key is set)
+//   - KEIKO_MODEL_<id>_API_KEY  (per-model override; <id> is opaque to this helper)
+//
+// The match is exact prefix + exact suffix to avoid false positives (e.g. "KEIKO_API_KEY_NOTE"
+// would not match because of the missing "_MODEL_" segment).
+export function isKeikoApiKeyEnvName(name) {
+    return (name === "KEIKO_DEFAULT_API_KEY" ||
+        (name.startsWith("KEIKO_MODEL_") && name.endsWith("_API_KEY")));
+}
+// Collects the VALUES of every env entry whose name is a KEIKO API-key env var. Undefined and
+// empty values are skipped — feeding "" to the redactor would over-redact ordinary text. Names
+// are never collected, only values: redacting a name like "KEIKO_DEFAULT_API_KEY" in a log line
+// would obscure debugging output without protecting any secret.
+export function keikoApiKeySecretValues(env) {
+    const values = [];
+    for (const [name, value] of Object.entries(env)) {
+        if (value !== undefined && value.length > 0 && isKeikoApiKeyEnvName(name)) {
+            values.push(value);
+        }
+    }
+    return values;
+}

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+export declare const KEIKO_SECURITY_VERSION: "0.1.0";
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,sBAAsB,EAAG,OAAgB,CAAC"}

package/dist/version.js

@@ -0,0 +1,4 @@
+// Version anchor for @oscharko-dev/keiko-security. Pinned to the package's package.json version.
+// Lets consumers assert which security primitive contract they linked against (ADR-0019 leaf-package
+// pattern, mirroring @oscharko-dev/keiko-contracts).
+export const KEIKO_SECURITY_VERSION = "0.1.0";

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@oscharko-dev/keiko-security",
+  "version": "0.2.0",
+  "type": "module",
+  "license": "Apache-2.0",
+  "description": "Internal workspace package: shared Keiko security primitives (redaction, safe error shaping, secret collection, content hashing, trust-boundary helpers). Not published independently.",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./redaction": {
+      "types": "./dist/redaction.d.ts",
+      "import": "./dist/redaction.js"
+    },
+    "./errors": {
+      "types": "./dist/errors/index.d.ts",
+      "import": "./dist/errors/index.js"
+    },
+    "./errors/gateway": {
+      "types": "./dist/errors/gateway.d.ts",
+      "import": "./dist/errors/gateway.js"
+    },
+    "./errors/audit": {
+      "types": "./dist/errors/audit.d.ts",
+      "import": "./dist/errors/audit.js"
+    },
+    "./errors/workspace": {
+      "types": "./dist/errors/workspace.d.ts",
+      "import": "./dist/errors/workspace.js"
+    },
+    "./errors/tools": {
+      "types": "./dist/errors/tools.d.ts",
+      "import": "./dist/errors/tools.js"
+    },
+    "./errors/harness": {
+      "types": "./dist/errors/harness.d.ts",
+      "import": "./dist/errors/harness.js"
+    },
+    "./errors/verification": {
+      "types": "./dist/errors/verification.d.ts",
+      "import": "./dist/errors/verification.js"
+    },
+    "./runid": {
+      "types": "./dist/runid.d.ts",
+      "import": "./dist/runid.js"
+    },
+    "./secrets": {
+      "types": "./dist/secrets.d.ts",
+      "import": "./dist/secrets.js"
+    },
+    "./hashing": {
+      "types": "./dist/hashing.d.ts",
+      "import": "./dist/hashing.js"
+    },
+    "./secret-vault": {
+      "types": "./dist/secret-vault.d.ts",
+      "import": "./dist/secret-vault.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -b tsconfig.json",
+    "typecheck": "tsc -b tsconfig.json",
+    "test": "vitest run"
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@oscharko-dev/keiko-contracts": "0.2.0"
+  }
+}