@try-works/dsh-tool-mode 0.0.0-stage → 0.5.45

package/lib/mcp/credential-cli.js

@@ -0,0 +1,148 @@
+/**
+ * The HUMAN-ONLY credential CLI (SEC-01).
+ *
+ * The model-visible `model_tools credentials` surface REFUSES generation: a
+ * generated secret must never enter a model transcript. This module is the
+ * operator's terminal instead — it generates over the durable store and prints
+ * the secret EXACTLY ONCE to stdout, with the same stream discipline as the
+ * stdio bridge: stdout carries the credential and nothing else; every
+ * diagnostic goes to stderr. The secret is never logged, never persisted
+ * anywhere beyond the owner-only store document, and cannot be recovered —
+ * a lost secret is replaced by revoking and regenerating.
+ *
+ * Usage:
+ *   dsh-tool-mode-credentials generate --scheme static-token --client-id <id>
+ *   dsh-tool-mode-credentials generate --scheme oauth-resource-server --client-id <id> [--scope a,b,c]
+ *   dsh-tool-mode-credentials list [--store <path>]
+ *   dsh-tool-mode-credentials revoke --client-id <id> [--store <path>]
+ *
+ * Exit codes: 0 done; 1 the operation failed (corrupt store, duplicate id,
+ * persistence failure); 2 usage.
+ *
+ * @module @try-works/dsh-tool-mode/mcp/credential-cli
+ */
+import { createFileCredentialStore, defaultCredentialStoreFile, generateCredential, } from "./credential-store.js";
+const USAGE = [
+    'usage:',
+    '  dsh-tool-mode-credentials generate --scheme static-token --client-id <id>',
+    '  dsh-tool-mode-credentials generate --scheme oauth-resource-server --client-id <id> [--scope a,b,c]',
+    '  dsh-tool-mode-credentials list [--store <path>]',
+    '  dsh-tool-mode-credentials revoke --client-id <id> [--store <path>]',
+    'The generated secret is printed ONCE to stdout and is never echoed again;',
+    'a lost secret is replaced by revoking the client and generating a new one.',
+].join('\n');
+/** Parse `--flag value` pairs; repeated flags keep the last value. */
+function parseArgs(argv) {
+    const pairs = new Map();
+    for (let i = 0; i < argv.length; i += 1) {
+        const token = argv[i];
+        if (!token.startsWith('--'))
+            throw new Error(`unexpected argument ${JSON.stringify(token)}`);
+        const value = argv[i + 1];
+        if (value === undefined || value.startsWith('--'))
+            throw new Error(`the flag ${token} needs a value`);
+        pairs.set(token.slice(2), value);
+        i += 1;
+    }
+    return pairs;
+}
+/**
+ * Run the credential CLI.
+ * @param argv - the process arguments, without the executable.
+ * @param streams - the two streams (stdout/stderr in production).
+ * @returns the process exit code.
+ */
+export function runCredentialsCli(argv, streams) {
+    const command = argv[0];
+    let pairs;
+    try {
+        pairs = parseArgs(argv.slice(1));
+    }
+    catch (error) {
+        streams.err(error instanceof Error ? error.message : String(error));
+        streams.err(USAGE);
+        return 2;
+    }
+    const storeFile = pairs.get('store') ?? defaultCredentialStoreFile();
+    let store;
+    try {
+        store = createFileCredentialStore(storeFile);
+    }
+    catch (error) {
+        streams.err(`cannot open the credential store: ${error instanceof Error ? error.message : String(error)}`);
+        return 1;
+    }
+    if (command === 'generate') {
+        const scheme = pairs.get('scheme');
+        const clientId = pairs.get('client-id');
+        if (scheme !== 'static-token' && scheme !== 'oauth-resource-server') {
+            streams.err('generate requires --scheme static-token or --scheme oauth-resource-server');
+            streams.err(USAGE);
+            return 2;
+        }
+        if (clientId === undefined || clientId.length === 0) {
+            streams.err('generate requires --client-id');
+            streams.err(USAGE);
+            return 2;
+        }
+        const scope = pairs.get('scope') === undefined
+            ? undefined
+            : pairs.get('scope').split(',').map(name => name.trim()).filter(name => name.length > 0);
+        try {
+            const generated = generateCredential(store, {
+                clientId,
+                scheme: scheme,
+                ...scope === undefined ? {} : { scope },
+            });
+            // THE ONCE-ONLY OUTPUT. Nothing else in this process writes to stdout.
+            streams.out('Generated credential (SEC-01).');
+            streams.out(`clientId: ${generated.clientId}`);
+            streams.out(`scheme: ${generated.scheme}`);
+            streams.out(`scope: ${generated.scope.join(' ')}`);
+            streams.out(`secret: ${generated.secret}`);
+            streams.out('SHOWN ONCE: store the secret now. It is never echoed again and cannot be recovered;');
+            streams.out('a lost secret is replaced by revoking this client and generating a new credential.');
+            return 0;
+        }
+        catch (error) {
+            streams.err(`generation refused: ${error instanceof Error ? error.message : String(error)}`);
+            return 1;
+        }
+    }
+    if (command === 'list') {
+        try {
+            const entries = store.list();
+            streams.out(`${entries.length} live client credential(s):`);
+            for (const entry of entries) {
+                streams.out(`- ${entry.clientId} (${entry.scheme}, ${entry.createdAt})`);
+            }
+            return 0;
+        }
+        catch (error) {
+            streams.err(`list failed: ${error instanceof Error ? error.message : String(error)}`);
+            return 1;
+        }
+    }
+    if (command === 'revoke') {
+        const clientId = pairs.get('client-id');
+        if (clientId === undefined || clientId.length === 0) {
+            streams.err('revoke requires --client-id');
+            streams.err(USAGE);
+            return 2;
+        }
+        try {
+            const existed = store.get(clientId) !== undefined;
+            store.delete(clientId);
+            streams.out(existed ? `revoked ${clientId}` : `no credential for ${clientId}; nothing to revoke`);
+            return 0;
+        }
+        catch (error) {
+            streams.err(`revoke refused: ${error instanceof Error ? error.message : String(error)}`);
+            return 1;
+        }
+    }
+    streams.err(`unknown command ${JSON.stringify(command ?? '')}`);
+    streams.err(USAGE);
+    return 2;
+}
+//# sourceMappingURL=credential-cli.js.map

package/lib/mcp/credential-store.d.ts

@@ -0,0 +1,143 @@
+/**
+ * The operator-owned client credential store (SEC-01).
+ *
+ * SEC-01's generation clause: credentials are generated with high-entropy secrets,
+ * stored with suitable host protection (owner-only), and revocable independently per
+ * application. Before this module the OAuth client registry was in-memory only and the
+ * static-token mode accepted exactly one configured token — nothing could GENERATE a
+ * credential and nothing persisted it, so a restart lost every client and a generated
+ * secret could not exist.
+ *
+ * This store is the durable half. The security properties it now holds, each pinned
+ * by test:
+ *
+ * - one JSON document per deployment (`credentials.json`), written to a CRYPTO-RANDOM
+ *   temp name opened EXCLUSIVELY (`wx`) — a predictable temp name is a hardlink target
+ *   an attacker on the same account can pre-plant, so the name is unguessable and a
+ *   pre-existing name FAILS instead of being overwritten — then fsync'd and atomically
+ *   renamed over the document. A rename replaces a planted SYMLINK at the target rather
+ *   than following it;
+ * - Windows: an EXPLICIT owner-only DACL is applied to the temp file BEFORE the rename
+ *   (inheritance removed, the owner alone granted full control) and the store fails
+ *   closed when the ACL cannot be secured. POSIX mode 0600 alone is not sufficient on
+ *   Windows, and "the profile directory inherits it" is not a control;
+ * - MUTATIONS serialize through an in-process mutex AND an exclusive sidecar lock file,
+ *   and re-read the document inside the critical section — two concurrent writers can
+ *   no longer each persist a snapshot that silently drops the other's entry;
+ * - a CORRUPT or unreadable document makes MUTATIONS fail closed (a generation refused,
+ *   the bytes untouched) while READS deny: authentication cannot succeed on a store
+ *   the host cannot vouch for, and a generation can never overwrite a malformed
+ *   document "as if empty". A MISSING document is the only empty start;
+ * - reads are served from the FILE, fresh on every lookup, so a revocation through any
+ *   surface takes effect on the very next request;
+ * - `bySecret` matches STATIC-TOKEN credentials only: an OAuth resource-server secret
+ *   presented as a static bearer must never authenticate through this path (scheme
+ *   confusion);
+ * - the secret is compared CONSTANT-TIME (SHA-256 digests over equal-length input);
+ * - every mutation throws when it cannot persist: a generation that cannot be written
+ *   must leave nothing usable rather than an in-memory-only credential that a restart
+ *   silently forgets (fail-closed, SEC-01).
+ *
+ * @module @try-works/dsh-tool-mode/mcp/credential-store
+ */
+/** The scheme a stored credential authenticates under. */
+export type CredentialScheme = 'static-token' | 'oauth-resource-server';
+/** One persisted client credential. */
+export interface StoredClientCredential {
+    /** The client identity, recorded in receipts and grants. */
+    readonly clientId: string;
+    /** The secret: crypto-random, shown once at generation, never re-echoed. */
+    readonly secret: string;
+    /** The scheme the secret is presented under. */
+    readonly scheme: CredentialScheme;
+    /** The scope the client may be granted (OAuth); empty for static tokens. */
+    readonly scope: readonly string[];
+    /** ISO timestamp of generation. */
+    readonly createdAt: string;
+}
+/** The store a generation writes and an auth layer reads. */
+export interface ClientCredentialStore {
+    /** The file the credentials live in. */
+    readonly file: string;
+    /** Every live credential, WITHOUT a way to re-echo secrets beyond what the file holds. */
+    list(): readonly StoredClientCredential[];
+    /** One credential by client identity. */
+    get(clientId: string): StoredClientCredential | undefined;
+    /**
+     * Resolve a PRESENTED secret to its credential, in constant time.
+     *
+     * STATIC-TOKEN SCHEME ONLY: this is the static-bearer lookup, and an OAuth
+     * resource-server secret must never match here (scheme confusion). OAuth
+     * credentials authenticate through the OAuth verifier, never by raw secret.
+     */
+    bySecret(secret: string): StoredClientCredential | undefined;
+    /** Write a credential; throws when persistence fails, registering nothing usable. */
+    upsert(credential: StoredClientCredential): void;
+    /** Delete one credential; throws when the deletion cannot be persisted. */
+    delete(clientId: string): void;
+}
+/** A document that EXISTS but cannot be vouched for. Mutations refuse; reads deny. */
+export declare class CorruptCredentialStoreError extends Error {
+    constructor(message: string);
+}
+/** A generated credential for the human-only CLI and tests (SEC-01, shown once). */
+export interface GeneratedCredential {
+    readonly clientId: string;
+    readonly secret: string;
+    readonly scheme: CredentialScheme;
+    readonly scope: readonly string[];
+    readonly createdAt: string;
+}
+/**
+ * Generate a fresh client credential directly over the store (the primitive
+ * the human-only CLI and tests use — the model-visible `model_tools` surface
+ * refuses generation entirely, SEC-01: the secret must never reach a model).
+ * @param store - the durable store.
+ * @param options - clientId (≤64 chars), scheme, scope.
+ * @returns the credential with the secret exactly once.
+ */
+export declare function generateCredential(store: ClientCredentialStore, options: {
+    readonly clientId: string;
+    readonly scheme: CredentialScheme;
+    readonly scope?: readonly string[];
+}): GeneratedCredential;
+/**
+ * Derive the default credential-store file, next to the host's own state
+ * (SEC-01: owner-only home protection).
+ * @param env - the environment to read; defaults to the process environment.
+ * @returns the absolute path.
+ */
+export declare function defaultCredentialStoreFile(env?: NodeJS.ProcessEnv): string;
+/**
+ * Apply an explicit owner-only DACL to one file on Windows (icacls: inheritance
+ * removed, the current owner alone granted full control), and fail closed when
+ * the ACL cannot be secured. On POSIX the caller's 0600 mode bits are the
+ * control and this is a no-op.
+ * @param file - the file to secure, BEFORE it is published (renamed) into place.
+ */
+export declare function applyOwnerOnlyDacl(file: string): void;
+/**
+ * TEST-ONLY hooks for the store's lock machinery. Production callers pass
+ * nothing: the hooks exist so the regressions can exercise a long-lived holder
+ * and the fail-closed liveness paths without multi-second waits.
+ */
+export interface CredentialStoreTestHooks {
+    /** Sleep INSIDE the critical section, after the strict read (simulates a paused writer). */
+    readonly holdLockAfterReadMs?: number;
+    /** Override the stale-lock age threshold. */
+    readonly staleLockMs?: number;
+    /** Override how long a contender waits for the lock before failing closed. */
+    readonly lockDeadlineMs?: number;
+    /** Override the process-liveness probe. */
+    readonly isProcessAlive?: (pid: number) => boolean | undefined;
+}
+/**
+ * Create (or open) the file-backed credential store.
+ * @param file - the absolute path of the credentials document.
+ * @param hooks - TEST-ONLY lock hooks; production passes nothing.
+ * @returns the store.
+ */
+export declare function createFileCredentialStore(file: string, hooks?: CredentialStoreTestHooks): ClientCredentialStore;
+/** Remove a credential store file, for tests that need a fresh deployment. */
+export declare function removeCredentialStoreFile(file: string): void;
+//# sourceMappingURL=credential-store.d.ts.map

package/lib/mcp/credential-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"credential-store.d.ts","sourceRoot":"","sources":["../../src/mcp/credential-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAkBH,0DAA0D;AAC1D,MAAM,MAAM,gBAAgB,GAAG,cAAc,GAAG,uBAAuB,CAAA;AAEvE,uCAAuC;AACvC,MAAM,WAAW,sBAAsB;IACrC,4DAA4D;IAC5D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,4EAA4E;IAC5E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,gDAAgD;IAChD,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAA;IACjC,4EAA4E;IAC5E,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;IACjC,mCAAmC;IACnC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAC3B;AAED,6DAA6D;AAC7D,MAAM,WAAW,qBAAqB;IACpC,wCAAwC;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,0FAA0F;IAC1F,IAAI,IAAI,SAAS,sBAAsB,EAAE,CAAA;IACzC,yCAAyC;IACzC,GAAG,CAAC,QAAQ,EAAE,MAAM,GAAG,sBAAsB,GAAG,SAAS,CAAA;IACzD;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,sBAAsB,GAAG,SAAS,CAAA;IAC5D,qFAAqF;IACrF,MAAM,CAAC,UAAU,EAAE,sBAAsB,GAAG,IAAI,CAAA;IAChD,2EAA2E;IAC3E,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;CAC/B;AAQD,sFAAsF;AACtF,qBAAa,2BAA4B,SAAQ,KAAK;gBACxC,OAAO,EAAE,MAAM;CAI5B;AAED,oFAAoF;AACpF,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAA;IACjC,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;IACjC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAC3B;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,qBAAqB,EAC5B,OAAO,EAAE;IAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GAC5G,mBAAmB,CAerB;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAKvF;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAgBrD;AA8DD;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACvC,4FAA4F;IAC5F,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAA;IACrC,6CAA6C;IAC7C,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B,8EAA8E;IAC9E,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAA;IAChC,2CAA2C;IAC3C,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,GAAG,SAAS,CAAA;CAC/D;AA0CD;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,GAAE,wBAA6B,GAAG,qBAAqB,CA6OnH;AAED,8EAA8E;AAC9E,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAG5D"}