credvault 0.3.0

package/dist/credentials.js

@@ -0,0 +1,314 @@
+/**
+ * What it takes to sign in to a site, by site name (`github`, or
+ * `google@ops` for a second account). Stored outside any repo or journal:
+ * a sealed 0600 JSON file on a laptop, env entries in a container. Read at
+ * the moment a login needs it, never carried on a plan or in a memo.
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname } from "node:path";
+import { z } from "zod";
+import { isSealed, plainCipher } from "./cipher.js";
+const expandHome = (p) => (p.startsWith("~/") ? `${homedir()}${p.slice(1)}` : p);
+export const credentialSchema = z
+    .object({
+    username: z.string().min(1),
+    /** Absent when the account has none: it signs in through a provider (`via`). */
+    password: z.string().min(1).optional(),
+    /** The password before the last rotation: tried once when the site rejects the current one. */
+    previousPassword: z.string().min(1).optional(),
+    /** Base32 TOTP seed (the site's "manual entry key", spaces and dashes allowed); never a 6-digit code. */
+    totpSecret: z
+        .string()
+        .transform((s) => s.replace(/[\s=-]/g, "").toUpperCase())
+        .pipe(z
+        .string()
+        .regex(/^[A-Z2-7]{16,}$/, "totpSecret must be the base32 seed (16+ letters/digits), not a 6-digit code"))
+        .optional(),
+    /** One-time recovery codes the site handed out; used, then dropped. */
+    recoveryCodes: z.array(z.string().min(1)).default([]),
+    /** Where the site sends email codes; defaults to `username` when that is an address. */
+    codesInbox: z.string().email().optional(),
+    /** Passkeys enrolled by us (the virtual authenticator's export); loaded into the site's browser session. */
+    passkeys: z
+        .array(z.object({
+        rpId: z.string(),
+        credentialId: z.string(),
+        privateKey: z.string(),
+        userHandle: z.string().optional(),
+        signCount: z.number(),
+        isResidentCredential: z.boolean(),
+    }))
+        .default([]),
+    /** Sign in through this identity provider's button (`google`) instead of a password; the provider's own credential does the work. */
+    via: z.string().min(1).optional(),
+    /**
+     * A tripwire, not an account: nothing legitimate ever reads it. A `get`
+     * of a canary is an alarm (see canary.ts), and its password belongs on
+     * no host.
+     */
+    canary: z.boolean().optional(),
+    /** Where the sign-in page is, when the caller knows no login page of its own for the site. */
+    url: z.string().url().optional(),
+    /** When the account was made; a minted credential without it is a signup still owed. */
+    madeAt: z.string().datetime().optional(),
+})
+    .refine((c) => c.password || c.via, { message: "a credential has a password or a via provider" });
+const fileSchema = z.object({ sites: z.record(z.string(), credentialSchema) });
+/**
+ * `{ "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 function fileCredentials(path, cipher = plainCipher) {
+    const file = expandHome(path);
+    // Opened and parsed once per version of the file: a `list` + `get` per name is one read, and
+    // a file another process rewrote (its mtime or size moved) is read again. A stat per call.
+    let cached = null;
+    const read = () => {
+        if (!existsSync(file)) {
+            cached = null;
+            return { sites: {} };
+        }
+        const st = statSync(file);
+        const stamp = `${st.mtimeMs}:${st.size}`;
+        if (cached?.stamp === stamp)
+            return cached.data;
+        const raw = readFileSync(file, "utf8");
+        const data = fileSchema.parse(JSON.parse(isSealed(raw) ? cipher.open(raw) : raw));
+        cached = { stamp, data };
+        return data;
+    };
+    return {
+        async get(site) {
+            return read().sites[site] ?? null;
+        },
+        async put(site, cred) {
+            const data = { sites: { ...read().sites, [site]: credentialSchema.parse(cred) } };
+            mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
+            const tmp = `${file}.tmp`;
+            writeFileSync(tmp, cipher.seal(JSON.stringify(data, null, 2)), { mode: 0o600 });
+            renameSync(tmp, file);
+            cached = null;
+        },
+        async list() {
+            return Object.keys(read().sites);
+        },
+    };
+}
+export function memoryCredentials(init = {}) {
+    const sites = new Map(Object.entries(init).map(([k, v]) => [k, credentialSchema.parse(v)]));
+    return {
+        async get(site) {
+            return sites.get(site) ?? null;
+        },
+        async put(site, cred) {
+            sites.set(site, credentialSchema.parse(cred));
+        },
+        async list() {
+            return [...sites.keys()];
+        },
+    };
+}
+const DEFAULT_PREFIX = "CRED_";
+/** `CRED_<SITE>_<FIELD>`: the env name a credential field travels under. */
+export function credentialEnvName(site, field, o = {}) {
+    return `${o.prefix ?? DEFAULT_PREFIX}${envSiteName(site)}_${field}`;
+}
+/** `google@ops` → `GOOGLE__OPS`, `google-admin` → `GOOGLE_ADMIN`: the account keeps its own mark so `list` can read it back. */
+const envSiteName = (site) => site
+    .replace(/@/g, "__")
+    .replace(/[^a-zA-Z0-9_]+/g, "_")
+    .toUpperCase();
+const USERNAME = "_USERNAME";
+const siteFromEnvName = (s) => s.toLowerCase().replace(/__/g, "@").replace(/_/g, "-");
+/** Fields that travel as plain strings, and the list fields that travel as JSON. */
+const STRING_FIELDS = [
+    ["USERNAME", "username"],
+    ["PASSWORD", "password"],
+    ["PREVIOUS_PASSWORD", "previousPassword"],
+    ["TOTP_SECRET", "totpSecret"],
+    ["VIA", "via"],
+    ["CODES_INBOX", "codesInbox"],
+    ["URL", "url"],
+    ["MADE_AT", "madeAt"],
+];
+const JSON_FIELDS = [
+    ["RECOVERY_CODES", "recoveryCodes"],
+    ["PASSKEYS", "passkeys"],
+];
+/** Every env field a credential can use: what a push clears when the credential no longer has it. */
+export const CREDENTIAL_ENV_FIELDS = [...STRING_FIELDS, ...JSON_FIELDS].map(([f]) => f);
+/**
+ * A credential as env entries, every field of it: the strings as they are,
+ * recovery codes and passkeys as JSON. Empty fields are left out. A
+ * canary's entries are never asked for (see `pushCredentials`).
+ */
+export function credentialEnv(site, cred, o = {}) {
+    const fields = [
+        ...STRING_FIELDS.map(([f, k]) => [f, cred[k]]),
+        ...JSON_FIELDS.map(([f, k]) => [
+            f,
+            cred[k].length ? JSON.stringify(cred[k]) : undefined,
+        ]),
+    ];
+    return fields
+        .filter((f) => Boolean(f[1]))
+        .map(([field, value]) => ({ name: credentialEnvName(site, field, o), value }));
+}
+/**
+ * `CRED_<SITE>_<FIELD>`: the container form, where a Secret becomes env,
+ * and the shape a pull reads back. Read-only.
+ */
+export function envCredentials(env = process.env, o = {}) {
+    const prefix = o.prefix ?? DEFAULT_PREFIX;
+    const key = (site, field) => credentialEnvName(site, field, o);
+    return {
+        async get(site) {
+            const username = env[key(site, "USERNAME")];
+            if (!username || !(env[key(site, "PASSWORD")] || env[key(site, "VIA")]))
+                return null;
+            const out = {};
+            for (const [f, k] of STRING_FIELDS) {
+                const v = env[key(site, f)];
+                if (v)
+                    out[k] = v;
+            }
+            for (const [f, k] of JSON_FIELDS) {
+                const v = env[key(site, f)];
+                if (!v)
+                    continue;
+                try {
+                    out[k] = JSON.parse(v);
+                }
+                catch {
+                    throw new Error(`credentials for ${site}: ${key(site, f)} is not JSON`);
+                }
+            }
+            return credentialSchema.parse(out);
+        },
+        async put(site) {
+            throw new Error(`credentials for ${site}: env store is read-only; set ${key(site, "*")}`);
+        },
+        async list() {
+            return Object.keys(env)
+                .map((k) => k.startsWith(prefix) && k.endsWith(USERNAME)
+                ? k.slice(prefix.length, -USERNAME.length)
+                : undefined)
+                .filter((s) => Boolean(s))
+                .map(siteFromEnvName);
+        },
+    };
+}
+/**
+ * This machine's credentials into the env store, every site or the named
+ * ones, every field (passkeys and recovery codes as JSON). Canaries never
+ * travel: a tripwire belongs to one machine. Answers what was pushed, never
+ * a value.
+ */
+export async function pushCredentials(local, store, sites, o = {}) {
+    const chosen = sites?.length ? sites : await local.list();
+    const out = [];
+    const there = store.list && store.remove ? new Set((await store.list()).map((e) => e.name)) : null;
+    for (const site of chosen) {
+        const cred = await local.get(site);
+        if (!cred)
+            throw new Error(`no credential stored here for ${site}`);
+        if (cred.canary)
+            continue;
+        const entries = credentialEnv(site, cred, o);
+        for (const e of entries)
+            await store.put(e.name, e.value);
+        if (there && store.remove) {
+            const kept = new Set(entries.map((e) => e.name));
+            for (const f of CREDENTIAL_ENV_FIELDS) {
+                const name = credentialEnvName(site, f, o);
+                if (there.has(name) && !kept.has(name))
+                    await store.remove(name);
+            }
+        }
+        out.push({ site, names: entries.map((e) => e.name) });
+    }
+    return out;
+}
+/**
+ * The env store's credentials into this machine's file, the other way: a
+ * new laptop, or a box's file for a passkey site. A site already here is
+ * kept unless `overwrite`, and even then passkeys here are never dropped:
+ * the shared ones join them. Answers what was written and what was kept.
+ */
+export async function pullCredentials(store, local, sites, o = {}) {
+    const env = Object.fromEntries((await store.all()).map((e) => [e.name, e.value]));
+    const remote = envCredentials(env, o);
+    const chosen = sites?.length ? sites : await remote.list();
+    const written = [];
+    const kept = [];
+    for (const site of chosen) {
+        const cred = await remote.get(site);
+        if (!cred)
+            throw new Error(`no credential in the shared store for ${site}: push it first`);
+        const here = await local.get(site);
+        if (here && !o.overwrite) {
+            kept.push(site);
+            continue;
+        }
+        const shared = new Set(cred.passkeys.map((p) => p.credentialId));
+        await local.put(site, {
+            ...cred,
+            // A store pushed before codes travelled has none: the ones here stay.
+            recoveryCodes: cred.recoveryCodes.length ? cred.recoveryCodes : (here?.recoveryCodes ?? []),
+            passkeys: [
+                ...cred.passkeys,
+                ...(here?.passkeys ?? []).filter((p) => !shared.has(p.credentialId)),
+            ],
+        });
+        written.push(site);
+    }
+    return { written, kept };
+}
+/** First store that has the site wins; writes go to `write`, which defaults to the last store. */
+export function layeredCredentials(stores, write = stores.at(-1)) {
+    const first = write;
+    if (!first)
+        throw new Error("layeredCredentials needs at least one store");
+    return {
+        async get(site) {
+            for (const s of stores) {
+                const c = await s.get(site);
+                if (c)
+                    return c;
+            }
+            return null;
+        },
+        put: (site, cred) => first.put(site, cred),
+        async list() {
+            const all = await Promise.all(stores.map((s) => s.list()));
+            return [...new Set(all.flat())];
+        },
+    };
+}
+/**
+ * `local`, with every write copied to the shared env store: the file on this
+ * machine becomes a cache, and a lost machine loses nothing. The local write
+ * lands first; a failed copy goes to `onMirrorError` (default: throw), and
+ * `pushCredentials` for that site repairs it. Canaries stay local.
+ */
+export function mirroredCredentials(local, store, o = {}) {
+    const naming = o.prefix ? { prefix: o.prefix } : {};
+    return {
+        get: (site) => local.get(site),
+        list: () => local.list(),
+        async put(site, cred) {
+            await local.put(site, cred);
+            try {
+                await pushCredentials(local, store, [site], naming);
+            }
+            catch (err) {
+                if (!o.onMirrorError)
+                    throw err;
+                o.onMirrorError(site, err);
+            }
+        },
+    };
+}
+//# sourceMappingURL=credentials.js.map

package/dist/credentials.js.map

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

package/dist/env-store.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The one place a secret lives across machines: SSM Parameter Store, one
+ * SecureString per name under the app's path (`/myapp/config/NAME`). KMS
+ * at rest, IAM at the door, every read in CloudTrail. Values never enter
+ * argv, logs or errors.
+ */
+import { type SSMClient } from "@aws-sdk/client-ssm";
+export declare const ENV_KEY: RegExp;
+export interface EnvEntry {
+    name: string;
+    value: string;
+}
+/** What the store knows about an entry besides its value. */
+export interface EnvListing {
+    name: string;
+    /** When the value last changed. */
+    updatedAt: string | null;
+    /** When the value stops working (a token's expiry), if whoever stored it knew. */
+    expiresAt: string | null;
+}
+export interface PutOptions {
+    /** ISO time the value stops working; absent = it does not, or nobody knows. */
+    expiresAt?: string | undefined;
+}
+export interface EnvStore {
+    /** Names, change and expiry times; never values. */
+    list(): Promise<EnvListing[]>;
+    get(name: string): Promise<string | null>;
+    /** Every entry, decrypted: what a pull or a deploy reads. */
+    all(): Promise<EnvEntry[]>;
+    put(name: string, value: string, o?: PutOptions): Promise<void>;
+    remove(name: string): Promise<boolean>;
+}
+/**
+ * Entries that stop working within `withinMs` of `now` (already expired
+ * included), soonest first: what a watcher re-mints.
+ */
+export declare function expiring(entries: readonly EnvListing[], withinMs: number, now?: number): EnvListing[];
+/** SSM under `prefix`: `/prefix/NAME`. The client comes in so tests pass a fake. */
+export declare function ssmEnvStore(ssm: SSMClient, prefix: string): EnvStore;
+export declare function memoryEnvStore(initial?: Record<string, string>): EnvStore & {
+    values: Record<string, string>;
+};
+/**
+ * A local `.env` as a store: 0600, one line per name, other lines untouched.
+ * Expiry is a comment directly above the line, so a person reading the file
+ * sees it too. A put also sets `env[name]`, so this process sees the value.
+ */
+export declare function envFileStore(path: string, env?: NodeJS.ProcessEnv): EnvStore;
+/**
+ * `KEY=VALUE` lines → entries. Comments, blanks and quotes as a shell would
+ * read them; a value naming a readable file whose content is JSON (a
+ * service account) is inlined so the store holds the secret, not a path.
+ */
+export declare function parseDotenv(text: string, readFile?: (path: string) => string | null): EnvEntry[];
+/** Entries → `KEY=VALUE` lines. A multi-line value cannot live in one line: `files` takes it and the line names the path. */
+export declare function toDotenv(entries: EnvEntry[], files?: (name: string, value: string) => string): string;
+/** Entries → `export KEY='…'` lines for `eval "$(…)"`; single quotes are the one thing escaped. */
+export declare function toExports(entries: EnvEntry[]): string;
+/** Upsert `entries` into an env file's text; other lines untouched. */
+export declare function upsertDotenv(text: string, entries: EnvEntry[]): string;