credkeep 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wren Automation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,47 @@
+# credkeep
+
+Keep the credentials an automation signs in with. Sealed at rest, shared through AWS SSM, every use audited, expiries watched.
+
+No browser, no UI. The tool that signs in (a browser agent, a worker) reads from it. The tool that mints tokens writes to it.
+
+```sh
+npm install credkeep
+```
+
+## What is in it
+
+| Piece | What it does |
+| --- | --- |
+| `fileCredentials(path, cipher)` | Logins by site name (`github`, `google@ops`). A 0600 JSON file, sealed with AES-256-GCM. |
+| `keychainKey({ service })` | The seal key, kept in the macOS Keychain. Made on first use. |
+| `envCredentials(env, { prefix })` | The same logins read from env, for containers. Read-only. |
+| `pushCredentials` / `pullCredentials` | Move logins between a laptop and the shared store. Passkeys and recovery codes stay on the machine. |
+| `ssmEnvStore(ssm, "/app/config")` | Named values (API keys, tokens), one SSM SecureString each. |
+| `put(name, value, { expiresAt })` + `expiring(list, ms)` | Record when a token stops working. List what lapses soon, without decrypting anything. |
+| `fileAudit(path)` | Where each secret went, one hash-chained line per use. `verifyChain` finds any edit. |
+| `canaryStore(store)` | Reading a tripwire credential records it, tells a person, and throws. |
+| `totp(seed)` | The current code from a TOTP seed. `findTotpSecret(pageText)` finds the seed on an enrollment page. |
+| `newPassword()` | 24 characters, every class, no look-alikes. |
+
+## Example
+
+```ts
+import { SSMClient } from "@aws-sdk/client-ssm";
+import { aesGcmCipher, expiring, fileCredentials, keychainKey, ssmEnvStore, totp } from "credkeep";
+
+const logins = fileCredentials("~/.myapp/credentials.json", aesGcmCipher(keychainKey({ service: "myapp" })));
+const github = await logins.get("github");
+const code = github?.totpSecret ? totp(github.totpSecret) : null;
+
+const keys = ssmEnvStore(new SSMClient({}), "/myapp/config");
+await keys.put("NPM_TOKEN", token, { expiresAt: "2026-12-21T00:00:00Z" });
+const soon = expiring(await keys.list(), 14 * 86_400_000);
+```
+
+## Rules it keeps
+
+- Values never go into argv, logs or error messages. `list` returns names only.
+- A sealed file opened without its key fails loudly. It never fails as a parse error.
+- Each app has its own Keychain item, SSM path and env prefix, so two apps never share a secret by accident.
+
+MIT

package/dist/audit.d.ts

@@ -0,0 +1,23 @@
+export interface SecretUse {
+    at: string;
+    /** The credential's store name (`google`, `google@will`). */
+    credential: string;
+    field: "password" | "previousPassword" | "secret";
+    /** The site the session is on. */
+    site: string;
+    /** The page, without its query (tokens ride in queries). */
+    url: string;
+    /** Who used it: `login`, a flow name. */
+    by: string;
+    allowed: boolean;
+}
+export interface SecretAudit {
+    record(use: SecretUse): Promise<void>;
+    /** Newest last. */
+    recent(n?: number): Promise<SecretUse[]>;
+}
+/** JSON lines, owner-only, appended and hash-chained (chain.ts): `verifyChain` finds any edit. */
+export declare function fileAudit(path: string): SecretAudit;
+export declare function memoryAudit(): SecretAudit & {
+    uses: SecretUse[];
+};

package/dist/audit.js

@@ -0,0 +1,29 @@
+/**
+ * Where secrets went. Every use, allowed or refused, is a line: which
+ * credential, which field, which site, which page, by whom. Values are
+ * never written here.
+ */
+import { chainedFile } from "./chain.js";
+/** JSON lines, owner-only, appended and hash-chained (chain.ts): `verifyChain` finds any edit. */
+export function fileAudit(path) {
+    const file = chainedFile(path);
+    return {
+        async record(use) {
+            await file.append(use);
+        },
+        recent: (n = 50) => file.recent(n),
+    };
+}
+export function memoryAudit() {
+    const uses = [];
+    return {
+        uses,
+        async record(u) {
+            uses.push(u);
+        },
+        async recent(n = 50) {
+            return uses.slice(-n);
+        },
+    };
+}
+//# sourceMappingURL=audit.js.map

package/dist/audit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.js","sourceRoot":"","sources":["../src/audit.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAsBzC,kGAAkG;AAClG,MAAM,UAAU,SAAS,CAAC,IAAY;IACpC,MAAM,IAAI,GAAG,WAAW,CAAY,IAAI,CAAC,CAAC;IAC1C,OAAO;QACL,KAAK,CAAC,MAAM,CAAC,GAAG;YACd,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACzB,CAAC;QACD,MAAM,EAAE,CAAC,CAAC,GAAG,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;KACnC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,WAAW;IACzB,MAAM,IAAI,GAAgB,EAAE,CAAC;IAC7B,OAAO;QACL,IAAI;QACJ,KAAK,CAAC,MAAM,CAAC,CAAC;YACZ,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACf,CAAC;QACD,KAAK,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE;YACjB,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QACxB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/canary.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Canaries: credentials that exist only to be tripped. A real-looking
+ * credential under a name a thief or a confused model would reach for
+ * (`stripe`), with a random password nobody knows. Nothing legitimate asks
+ * for it, so a `get` of it IS the incident: it is written to the audit
+ * ledger, a person is told, and the read is refused.
+ */
+import type { SecretAudit } from "./audit.js";
+import type { Credential, CredentialInput, CredentialStore } from "./credentials.js";
+export declare class CanaryTripped extends Error {
+    readonly credential: string;
+    constructor(credential: string);
+}
+export interface CanaryOptions {
+    audit?: SecretAudit | undefined;
+    /** Tell a person; absent = the ledger line only. */
+    notify?: ((title: string, body: string) => Promise<unknown>) | undefined;
+    /** Who is reading, for the ledger (`login`, `explore`, a flow). */
+    by?: string;
+}
+/** A credential that looks like an account and is not. Pick a username a thief would believe. */
+export declare function canaryCredential(username: string): CredentialInput;
+/**
+ * The store with the wire armed: `get` of a canary records, notifies and
+ * throws `CanaryTripped`; `list` and `put` pass through, so the operator
+ * can still see and manage it by name.
+ */
+export declare function canaryStore(inner: CredentialStore, o?: CanaryOptions): CredentialStore;
+/** True when this credential must never be typed anywhere. */
+export declare const isCanary: (cred: Pick<Credential, "canary"> | null | undefined) => boolean;

package/dist/canary.js

@@ -0,0 +1,44 @@
+import { newPassword } from "./passwords.js";
+export class CanaryTripped extends Error {
+    credential;
+    constructor(credential) {
+        super(`credential ${credential} is a canary: nothing should read it`);
+        this.credential = credential;
+        this.name = "CanaryTripped";
+    }
+}
+/** A credential that looks like an account and is not. Pick a username a thief would believe. */
+export function canaryCredential(username) {
+    return { username, password: newPassword(20), canary: true };
+}
+/**
+ * The store with the wire armed: `get` of a canary records, notifies and
+ * throws `CanaryTripped`; `list` and `put` pass through, so the operator
+ * can still see and manage it by name.
+ */
+export function canaryStore(inner, o = {}) {
+    return {
+        ...inner,
+        async get(site) {
+            const cred = await inner.get(site);
+            if (!cred?.canary)
+                return cred;
+            await o.audit?.record({
+                at: new Date().toISOString(),
+                credential: site,
+                field: "password",
+                site,
+                url: "",
+                by: `${o.by ?? "get"} (canary)`,
+                allowed: false,
+            });
+            await o
+                .notify?.(`canary tripped: ${site}`, `something read the ${site} credential. Nothing legitimate does; check the audit ledger.`)
+                .catch(() => undefined);
+            throw new CanaryTripped(site);
+        },
+    };
+}
+/** True when this credential must never be typed anywhere. */
+export const isCanary = (cred) => cred?.canary === true;
+//# sourceMappingURL=canary.js.map

package/dist/canary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canary.js","sourceRoot":"","sources":["../src/canary.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAE7C,MAAM,OAAO,aAAc,SAAQ,KAAK;IACjB;IAArB,YAAqB,UAAkB;QACrC,KAAK,CAAC,cAAc,UAAU,sCAAsC,CAAC,CAAC;QADnD,eAAU,GAAV,UAAU,CAAQ;QAErC,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;IAC9B,CAAC;CACF;AAUD,iGAAiG;AACjG,MAAM,UAAU,gBAAgB,CAAC,QAAgB;IAC/C,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,WAAW,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;AAC/D,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,KAAsB,EAAE,IAAmB,EAAE;IACvE,OAAO;QACL,GAAG,KAAK;QACR,KAAK,CAAC,GAAG,CAAC,IAAI;YACZ,MAAM,IAAI,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YACnC,IAAI,CAAC,IAAI,EAAE,MAAM;gBAAE,OAAO,IAAI,CAAC;YAC/B,MAAM,CAAC,CAAC,KAAK,EAAE,MAAM,CAAC;gBACpB,EAAE,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;gBAC5B,UAAU,EAAE,IAAI;gBAChB,KAAK,EAAE,UAAU;gBACjB,IAAI;gBACJ,GAAG,EAAE,EAAE;gBACP,EAAE,EAAE,GAAG,CAAC,CAAC,EAAE,IAAI,KAAK,WAAW;gBAC/B,OAAO,EAAE,KAAK;aACf,CAAC,CAAC;YACH,MAAM,CAAC;iBACJ,MAAM,EAAE,CACP,mBAAmB,IAAI,EAAE,EACzB,sBAAsB,IAAI,+DAA+D,CAC1F;iBACA,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;YAC1B,MAAM,IAAI,aAAa,CAAC,IAAI,CAAC,CAAC;QAChC,CAAC;KACF,CAAC;AACJ,CAAC;AAED,8DAA8D;AAC9D,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,IAAmD,EAAW,EAAE,CACvF,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC"}

package/dist/chain.d.ts

@@ -0,0 +1,26 @@
+export interface Chained {
+    prev: string;
+    hash: string;
+}
+/** Hash of one row: `prev`, then the row's fields in key order, so the value is stable however it was built. */
+export declare function rowHash(prev: string, row: object): string;
+export interface ChainedFile<T extends object> {
+    /** Appends the row with its chain fields; one writer per process (appends are serialized here). */
+    append(row: T): Promise<T & Chained>;
+    /** Newest last; the chain fields come along. */
+    recent(n?: number): Promise<(T & Chained)[]>;
+}
+/**
+ * The whole file checked: `brokenAt` is the first row (0-based) whose hash
+ * or prev does not fit. Rows written before chaining (no `hash`) may only
+ * lead the file; they are counted in `unchained`, never verified.
+ */
+export interface Verification {
+    rows: number;
+    unchained: number;
+    ok: boolean;
+    brokenAt: number | null;
+}
+export declare function chainedFile<T extends object>(path: string): ChainedFile<T>;
+/** Walk every row from the start. */
+export declare function verifyChain(path: string): Promise<Verification>;

package/dist/chain.js

@@ -0,0 +1,117 @@
+/**
+ * An append-only JSONL file whose rows are hash-chained: each row carries
+ * `prev` (the hash of the row before it, "" for the first) and `hash`
+ * (SHA-256 over prev + the row's own fields). Editing, dropping or
+ * reordering any row breaks every hash after it, so `verify` finds
+ * tampering; nothing here stops it. The audit ledger is built on it, and
+ * any other ledger an app keeps can be.
+ */
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { appendFile, chmod, mkdir } from "node:fs/promises";
+import { dirname } from "node:path";
+import { createInterface } from "node:readline";
+import { tailJson } from "./tail.js";
+/** Hash of one row: `prev`, then the row's fields in key order, so the value is stable however it was built. */
+export function rowHash(prev, row) {
+    const fields = row;
+    const keys = Object.keys(fields)
+        .filter((k) => k !== "prev" && k !== "hash")
+        .sort();
+    const h = createHash("sha256").update(prev);
+    for (const k of keys)
+        h.update("\0").update(k).update("=").update(JSON.stringify(fields[k]));
+    return h.digest("hex");
+}
+export function chainedFile(path) {
+    let ready = null;
+    /** The last hash; read once from the file's tail, then carried in memory. */
+    let tip = "";
+    let queue = Promise.resolve();
+    const ensure = () => (ready ??= (async () => {
+        await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+        await appendFile(path, "", { mode: 0o600 });
+        await chmod(path, 0o600);
+        const [last] = await tailJson(path, 1);
+        // A file from before chaining: the first chained row binds every old line, so nothing
+        // can be slipped in front of the chain later. Read whole once, here only.
+        tip = typeof last?.hash === "string" ? last.hash : last ? await prefixHash(path) : "";
+        return tip;
+    })());
+    return {
+        append(row) {
+            const next = queue.then(async () => {
+                await ensure();
+                const chained = { ...row, prev: tip, hash: rowHash(tip, row) };
+                await appendFile(path, `${JSON.stringify(chained)}\n`, { mode: 0o600 });
+                tip = chained.hash;
+                return chained;
+            });
+            queue = next.catch(() => undefined);
+            return next;
+        },
+        async recent(n = 50) {
+            return tailJson(path, n);
+        },
+    };
+}
+async function openLines(path) {
+    try {
+        const stream = createReadStream(path, { encoding: "utf8" });
+        await new Promise((ok, no) => stream.once("open", () => ok()).once("error", no));
+        return createInterface({ input: stream, crlfDelay: Infinity });
+    }
+    catch {
+        return null;
+    }
+}
+/** SHA-256 over the file's unchained lines, in order: what the first chained row's `prev` carries. */
+async function prefixHash(path) {
+    const lines = await openLines(path);
+    const h = createHash("sha256");
+    if (lines)
+        for await (const line of lines)
+            if (line)
+                h.update(line).update("\n");
+    return h.digest("hex");
+}
+/** Walk every row from the start. */
+export async function verifyChain(path) {
+    const lines = await openLines(path);
+    if (!lines)
+        return { rows: 0, unchained: 0, ok: true, brokenAt: null };
+    let prev = "";
+    let rows = 0;
+    let unchained = 0;
+    let brokenAt = null;
+    const prefix = createHash("sha256");
+    // Streamed line by line: a ledger is read from the end everywhere else, whole only here.
+    for await (const line of lines) {
+        if (!line)
+            continue;
+        const i = rows++;
+        if (brokenAt !== null)
+            continue;
+        let row;
+        try {
+            row = JSON.parse(line);
+        }
+        catch {
+            brokenAt = i;
+            continue;
+        }
+        if (!("hash" in row) && unchained === i) {
+            unchained++;
+            prefix.update(line).update("\n");
+            continue;
+        }
+        if (i === unchained && unchained > 0)
+            prev = prefix.digest("hex");
+        if (row.prev !== prev || row.hash !== rowHash(prev, row))
+            brokenAt = i;
+        else
+            prev = row.hash;
+    }
+    return { rows, unchained, ok: brokenAt === null, brokenAt };
+}
+//# sourceMappingURL=chain.js.map

package/dist/chain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chain.js","sourceRoot":"","sources":["../src/chain.ts"],"names":[],"mappings":"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"}

package/dist/cipher.d.ts

@@ -0,0 +1,26 @@
+export interface Cipher {
+    seal(plain: string): string;
+    open(sealed: string): string;
+}
+/**
+ * No sealing. `open` still refuses a sealed file: read as plain text it
+ * would fail as a parse error three layers away, when the cause is always
+ * that this machine seals and the caller passed no key.
+ */
+export declare const plainCipher: Cipher;
+/** Sealed text is one JSON line: {magic, iv, tag, data}, all base64. */
+export declare function aesGcmCipher(key: Buffer): Cipher;
+export declare function isSealed(text: string): boolean;
+/** The Keychain item holding the key: one per app, so two tools never share a key by accident. */
+export interface KeychainItem {
+    service: string;
+    account?: string;
+}
+/**
+ * The 32-byte key from the login Keychain; created on first use with the
+ * `security` tool trusted, so no dialog on later reads. Throws off macOS
+ * or when the Keychain says no.
+ */
+export declare function keychainKey(item: KeychainItem): Buffer;
+/** Re-store the existing key with the tool trusted (an item made before `TRUST` prompts on every read). */
+export declare function trustKeychainKey(item: KeychainItem): "retrusted" | "none";

package/dist/cipher.js

@@ -0,0 +1,103 @@
+/**
+ * A file at rest. AES-256-GCM with a key that lives in the macOS Keychain
+ * (made on first use, read through `security -i` so it is never on a
+ * command line). Elsewhere (Linux, a container) secrets come from env and
+ * the cipher is plain.
+ */
+import { spawnSync } from "node:child_process";
+import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
+/**
+ * No sealing. `open` still refuses a sealed file: read as plain text it
+ * would fail as a parse error three layers away, when the cause is always
+ * that this machine seals and the caller passed no key.
+ */
+export const plainCipher = {
+    seal: (p) => p,
+    open: (s) => {
+        if (isSealed(s))
+            throw new Error("the file is sealed, but it was opened with no cipher key");
+        return s;
+    },
+};
+const MAGIC = "credkeep-sealed-v1";
+/** Files sealed before the vault left autobrowse: same format, older name. Read, and resealed on the next write. */
+const MAGICS = [MAGIC, "autobrowse-sealed-v1"];
+/** Sealed text is one JSON line: {magic, iv, tag, data}, all base64. */
+export function aesGcmCipher(key) {
+    if (key.length !== 32)
+        throw new Error("cipher key must be 32 bytes");
+    return {
+        seal(plain) {
+            const iv = randomBytes(12);
+            const c = createCipheriv("aes-256-gcm", key, iv);
+            const data = Buffer.concat([c.update(plain, "utf8"), c.final()]);
+            return JSON.stringify({
+                magic: MAGIC,
+                iv: iv.toString("base64"),
+                tag: c.getAuthTag().toString("base64"),
+                data: data.toString("base64"),
+            });
+        },
+        open(sealed) {
+            const parsed = JSON.parse(sealed);
+            if (!MAGICS.includes(parsed.magic ?? "") || !parsed.iv || !parsed.tag || !parsed.data)
+                throw new Error("the file is not sealed by credkeep");
+            const d = createDecipheriv("aes-256-gcm", key, Buffer.from(parsed.iv, "base64"));
+            d.setAuthTag(Buffer.from(parsed.tag, "base64"));
+            return Buffer.concat([d.update(Buffer.from(parsed.data, "base64")), d.final()]).toString("utf8");
+        },
+    };
+}
+export function isSealed(text) {
+    const head = text.trimStart();
+    return MAGICS.some((m) => head.startsWith(`{"magic":"${m}"`));
+}
+/** Runs `security` in interactive mode so nothing secret is an argv. */
+function security(commands) {
+    const r = spawnSync("security", ["-i"], { input: `${commands}\n`, encoding: "utf8" });
+    return { status: r.status ?? 1, out: `${r.stdout}${r.stderr}` };
+}
+/** The item trusts the `security` tool itself, so reading it never raises the Keychain dialog. */
+const TRUST = "-T /usr/bin/security";
+const ACCOUNT = "credentials-key";
+const ids = (item) => `-s ${item.service} -a ${item.account ?? ACCOUNT}`;
+function store(item, hex) {
+    const added = security(`add-generic-password ${ids(item)} -w ${hex} -U ${TRUST}`);
+    if (added.status !== 0)
+        throw new Error(`keychain: could not store the key (${added.out.trim().slice(0, 120)})`);
+}
+/**
+ * The 32-byte key from the login Keychain; created on first use with the
+ * `security` tool trusted, so no dialog on later reads. Throws off macOS
+ * or when the Keychain says no.
+ */
+export function keychainKey(item) {
+    if (process.platform !== "darwin")
+        throw new Error("keychain cipher needs macOS");
+    // One `security` subprocess per item per process: the key does not change while we run.
+    const cached = keyCache.get(ids(item));
+    if (cached)
+        return cached;
+    const found = security(`find-generic-password ${ids(item)} -w`);
+    let hex = found.status === 0 ? found.out.match(/\b[0-9a-f]{64}\b/)?.[0] : undefined;
+    if (!hex) {
+        hex = randomBytes(32).toString("hex");
+        store(item, hex);
+    }
+    const key = Buffer.from(hex, "hex");
+    keyCache.set(ids(item), key);
+    return key;
+}
+const keyCache = new Map();
+/** Re-store the existing key with the tool trusted (an item made before `TRUST` prompts on every read). */
+export function trustKeychainKey(item) {
+    const found = security(`find-generic-password ${ids(item)} -w`);
+    const hex = found.out.match(/\b[0-9a-f]{64}\b/)?.[0];
+    if (found.status !== 0 || !hex)
+        return "none";
+    security(`delete-generic-password ${ids(item)}`);
+    store(item, hex);
+    keyCache.delete(ids(item));
+    return "retrusted";
+}
+//# sourceMappingURL=cipher.js.map

package/dist/cipher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cipher.js","sourceRoot":"","sources":["../src/cipher.ts"],"names":[],"mappings":"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"}

package/dist/credentials.d.ts

@@ -0,0 +1,90 @@
+import { z } from "zod";
+import { type Cipher } from "./cipher.js";
+export declare const credentialSchema: z.ZodObject<{
+    username: z.ZodString;
+    password: z.ZodOptional<z.ZodString>;
+    previousPassword: z.ZodOptional<z.ZodString>;
+    totpSecret: z.ZodOptional<z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>, z.ZodString>>;
+    recoveryCodes: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    codesInbox: z.ZodOptional<z.ZodString>;
+    passkeys: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        rpId: z.ZodString;
+        credentialId: z.ZodString;
+        privateKey: z.ZodString;
+        userHandle: z.ZodOptional<z.ZodString>;
+        signCount: z.ZodNumber;
+        isResidentCredential: z.ZodBoolean;
+    }, z.core.$strip>>>;
+    via: z.ZodOptional<z.ZodString>;
+    canary: z.ZodOptional<z.ZodBoolean>;
+    url: z.ZodOptional<z.ZodString>;
+    madeAt: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type Credential = z.infer<typeof credentialSchema>;
+export type CredentialInput = z.input<typeof credentialSchema>;
+export interface CredentialStore {
+    get(site: string): Promise<Credential | null>;
+    put(site: string, cred: CredentialInput): Promise<void>;
+    /** Site names only; never values. */
+    list(): Promise<string[]>;
+}
+/**
+ * `{ "sites": { "<site>": Credential } }` at `path`, mode 0600, written
+ * atomically, sealed with `cipher` (a plain file written earlier is still
+ * read, and sealed on the next write).
+ */
+export declare function fileCredentials(path: string, cipher?: Cipher): CredentialStore;
+export declare function memoryCredentials(init?: Record<string, CredentialInput>): CredentialStore;
+/** How credentials travel as env: `<prefix><SITE>_<FIELD>`. Each app picks its own prefix. */
+export interface EnvNaming {
+    /** Default `CRED_`. */
+    prefix?: string;
+}
+/** `CRED_<SITE>_<FIELD>`: the env name a credential field travels under. */
+export declare function credentialEnvName(site: string, field: string, o?: EnvNaming): string;
+/**
+ * A credential as env entries, for the store the box reads: username,
+ * password, TOTP seed, via provider, codes inbox. Recovery codes and
+ * passkeys stay on the machine that holds the file.
+ */
+export declare function credentialEnv(site: string, cred: Credential, o?: EnvNaming): {
+    name: string;
+    value: string;
+}[];
+/**
+ * `CRED_<SITE>_USERNAME` / `_PASSWORD` / `_TOTP_SECRET` / `_VIA` /
+ * `_CODES_INBOX`: the container form, where a Secret becomes env. Read-only.
+ */
+export declare function envCredentials(env?: NodeJS.ProcessEnv, o?: EnvNaming): CredentialStore;
+/** The shared store's side of a sync (SSM, see env-store.ts). */
+export interface CredentialEnvStore {
+    all(): Promise<{
+        name: string;
+        value: string;
+    }[]>;
+    put(name: string, value: string): Promise<void>;
+}
+/**
+ * This machine's credentials into the env store, every site or the named
+ * ones: username, password, TOTP seed, via, codes inbox. Canaries never
+ * travel (a tripwire belongs to one machine); passkeys and recovery codes
+ * cannot. Answers what was pushed, never a value.
+ */
+export declare function pushCredentials(local: CredentialStore, store: CredentialEnvStore, sites?: string[], o?: EnvNaming): Promise<{
+    site: string;
+    names: string[];
+}[]>;
+/**
+ * The env store's credentials into this machine's file, the other way: a
+ * second laptop, or a box's file for a passkey site. A site already here is
+ * kept unless `overwrite`, and even then its passkeys and recovery codes
+ * stay (env never carries them). Answers what was written and what was kept.
+ */
+export declare function pullCredentials(store: CredentialEnvStore, local: CredentialStore, sites?: string[], o?: {
+    overwrite?: boolean;
+} & EnvNaming): Promise<{
+    written: string[];
+    kept: string[];
+}>;
+/** First store that has the site wins; writes go to `write`, which defaults to the last store. */
+export declare function layeredCredentials(stores: CredentialStore[], write?: CredentialStore | undefined): CredentialStore;