@try-works/dsh-model-as-tool 0.1.3 → 0.4.0

package/lib/managed-workers.js

@@ -0,0 +1,249 @@
+/**
+ * The host's managed-worker registry (EXT-20, the host half).
+ *
+ * The SDK ships the mechanism — {@link ManagedExtensionWorker}, a scrubbed-environment
+ * child process speaking the bounded invoke protocol — and this module is the host-side
+ * LIFETIME discipline: ONE worker process per extension per activation GENERATION,
+ * reused across invocations, disposed the moment the generation advances (a
+ * re-activation gets a fresh process, the old one never serves another call).
+ *
+ * What stays OUT of the worker, by construction:
+ *
+ * - the grant: the host authorizes the caller BEFORE dispatch ever builds a provider,
+ *   so `providerFor` here runs only for calls that already passed authorization, and
+ *   the worker receives exactly `{implementationId, input}` — no grant, no caller
+ *   identity, no configuration secrets;
+ * - the schemas: input validation happened host-side before the call, and the returned
+ *   value is validated against the declared output schema by the same path that
+ *   validates the in-process result — the worker's payload is treated as untrusted
+ *   data exactly like an in-process provider's;
+ * - receipts and accounting: untouched — they record the call in the same code path.
+ *
+ * IDENTITY: the worker is keyed by the extension's TRUE MANIFEST ID, never by a path
+ * or a package specifier (an install path must not leak into diagnostics or collide
+ * with a package name). The SDK child also derives its implementation->model mapping
+ * from the owning package.json + the manifest beside the entry, so this registry
+ * STAGES a host-owned worker directory — package.json + the manifest + a junction to
+ * the entry's directory — when the entry's own package root does not carry them
+ * (a staged store copy extracts no manifest). The entry's REAL bytes are the ones the
+ * worker executes: the junction resolves to the verified installed copy, never a host
+ * rewrite.
+ *
+ * Every worker failure surfaces as the SDK's ManagementError vocabulary
+ * (EXTENSION_FAULT), which the dispatch path converts into a tool error; the host
+ * process is never affected.
+ *
+ * @module @try-works/dsh-model-as-tool/managed-workers
+ */
+import { ManagedExtensionWorker } from '@try-works/tool-mode-extension-sdk';
+import { existsSync, mkdirSync, readFileSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { tmpdir } from 'node:os';
+/**
+ * Create the host's managed-worker registry.
+ * @returns the registry.
+ */
+export function createManagedWorkerRegistry() {
+    const holders = new Map();
+    /**
+     * Resolve the entry the CHILD must run, staging a host-owned owning-package
+     * layout when the entry's own package root does not carry one (a staged store
+     * copy extracts no package.json/manifest, which the SDK child needs for its
+     * implementation->model mapping). The staged dir carries a package.json and the
+     * REAL manifest bytes plus a junction to the entry's directory, so the bytes the
+     * worker executes are exactly the verified installed copy's.
+     */
+    const resolveChildEntry = (binding) => {
+        // Walk up from the entry looking for the OWNING package: the nearest package.json
+        // that actually declares a toolMode.manifest. A store copy extracts neither, so a
+        // stray unrelated package.json higher up must NOT be mistaken for the owner (that
+        // would hand the child a package whose manifest it would then misread).
+        let root = dirname(binding.entryPath);
+        let owned = false;
+        for (;;) {
+            const candidate = join(root, 'package.json');
+            if (existsSync(candidate)) {
+                try {
+                    const pkg = JSON.parse(readFileSync(candidate, 'utf8'));
+                    if (typeof pkg.toolMode?.manifest === 'string') {
+                        owned = true;
+                        break;
+                    }
+                }
+                catch {
+                    // Unreadable or malformed: not an owner.
+                }
+            }
+            const parent = dirname(root);
+            if (parent === root)
+                break;
+            root = parent;
+        }
+        if (owned)
+            return { entryPath: binding.entryPath, stagedDir: undefined };
+        if (binding.manifestPath === undefined) {
+            throw new Error(`the worker for ${binding.extensionId} cannot derive the model mapping: the entry's package root carries no `
+                + 'package.json and the host holds no manifest path for it (a staged store copy). Until the SDK lands the '
+                + 'host-supplied mapping API, this binding is refused rather than run with a guessed mapping.');
+        }
+        const stagedDir = join(tmpdir(), `tmw-${binding.extensionId.replace(/[^A-Za-z0-9._-]/g, '_')}-${binding.generation}-${process.pid}`);
+        mkdirSync(join(stagedDir, 'lib'), { recursive: true });
+        writeFileSync(join(stagedDir, 'package.json'), JSON.stringify({
+            name: binding.extensionId,
+            version: '0.0.0-worker',
+            type: 'module',
+            toolMode: { manifest: './tool-mode.extension.json' },
+        }));
+        // The REAL manifest bytes, so the child's identity and mapping checks run on
+        // exactly what the host verified.
+        writeFileSync(join(stagedDir, 'tool-mode.extension.json'), readFileSync(binding.manifestPath));
+        // A junction (Windows, no elevation) or symlink to the entry's directory — the
+        // child's mapping walks UP from the staged entry and finds the staged owner.
+        symlinkSync(dirname(binding.entryPath), join(stagedDir, 'lib'), process.platform === 'win32' ? 'junction' : 'dir');
+        return { entryPath: join(stagedDir, 'lib', basename(binding.entryPath)), stagedDir };
+    };
+    const bind = async (binding) => {
+        const current = holders.get(binding.extensionId);
+        if (current !== undefined && current.generation === binding.generation) {
+            return current;
+        }
+        // EXT-20: a generation change disposes the OLD worker before any new process is
+        // created — the previous generation's process never answers this generation's call.
+        if (current !== undefined) {
+            await current.worker.dispose();
+            if (current.stagedDir !== undefined)
+                rmSync(current.stagedDir, { recursive: true, force: true });
+            holders.delete(binding.extensionId);
+        }
+        const { entryPath, stagedDir } = resolveChildEntry(binding);
+        const holder = {
+            generation: binding.generation,
+            stagedDir,
+            worker: ManagedExtensionWorker.create({
+                extensionId: binding.extensionId,
+                entryPath,
+                generation: binding.generation,
+                ...binding.envPassthrough === undefined ? {} : { envPassthrough: binding.envPassthrough },
+            }),
+        };
+        holders.set(binding.extensionId, holder);
+        return holder;
+    };
+    return {
+        async providerFor(binding) {
+            const holder = await bind(binding);
+            return {
+                async load(request) {
+                    // The HOST-VERIFIED prepared assets reach the child through the
+                    // SDK's load API (host-prepared assets ONLY — nothing else is sent,
+                    // and the child never auto-loads). An empty map reaches the child as
+                    // an empty map: the extension's own load refuses a missing group by
+                    // name rather than the host inventing a verification.
+                    await holder.worker.load(request.modelId, {
+                        assets: request.assets,
+                        signal: request.signal,
+                    });
+                },
+                async invoke(request) {
+                    // The GRANT and the schemas were already enforced host-side; the worker
+                    // receives the validated input and nothing else. No resolvePath broker is
+                    // supplied on the dispatch path: an extension tool needing a host-authorized
+                    // path is refused by the child's own denial rather than given an identity
+                    // resolver (the protocol's omitted-callback rule).
+                    return await holder.worker.invoke({
+                        implementationId: request.implementationId,
+                        input: request.input,
+                        ...request.context?.signal === undefined
+                            ? {}
+                            : { signal: request.context.signal },
+                    });
+                },
+            };
+        },
+        async adapterFor(binding) {
+            const holder = await bind(binding);
+            let disposed = false;
+            return {
+                async inspect(modelId, options) {
+                    if (disposed)
+                        throw new Error(`the managed worker for ${binding.extensionId} was disposed`);
+                    return await holder.worker.inspect(modelId, {
+                        ...options?.signal === undefined ? {} : { signal: options.signal },
+                    });
+                },
+                async load(modelId, options) {
+                    if (disposed)
+                        throw new Error(`the managed worker for ${binding.extensionId} was disposed`);
+                    // Host-prepared assets ONLY — the map the host verified; nothing else is
+                    // sent to the child, and the child never auto-loads.
+                    await holder.worker.load(modelId, {
+                        assets: options.assets,
+                        ...options.signal === undefined ? {} : { signal: options.signal },
+                    });
+                },
+                async unload(modelId, options) {
+                    if (disposed)
+                        throw new Error(`the managed worker for ${binding.extensionId} was disposed`);
+                    await holder.worker.unload(modelId, {
+                        ...options?.signal === undefined ? {} : { signal: options.signal },
+                    });
+                },
+                async invoke(request) {
+                    if (disposed) {
+                        throw new Error(`the managed worker for ${binding.extensionId} was disposed`);
+                    }
+                    return await holder.worker.invoke({
+                        implementationId: request.implementationId,
+                        input: request.input,
+                        ...request.signal === undefined ? {} : { signal: request.signal },
+                        ...request.resolvePath === undefined ? {} : { resolvePath: request.resolvePath },
+                    });
+                },
+                async dispose() {
+                    if (disposed)
+                        return;
+                    disposed = true;
+                    await holder.worker.dispose();
+                    if (holders.get(binding.extensionId) === holder)
+                        holders.delete(binding.extensionId);
+                    if (holder.stagedDir !== undefined)
+                        rmSync(holder.stagedDir, { recursive: true, force: true });
+                },
+                pid() {
+                    return holder.worker.pid;
+                },
+            };
+        },
+        async dispose(extensionId) {
+            const holder = holders.get(extensionId);
+            holders.delete(extensionId);
+            if (holder !== undefined) {
+                await holder.worker.dispose();
+                if (holder.stagedDir !== undefined)
+                    rmSync(holder.stagedDir, { recursive: true, force: true });
+            }
+        },
+        capabilities() {
+            // The verified SDK child protocol now serves inspect, load/unload and the
+            // invoke resolvePath broker.
+            return { inspect: true, load: true };
+        },
+        bindings() {
+            return [...holders.entries()].map(([extensionId, holder]) => ({
+                extensionId,
+                generation: holder.generation,
+                pid: holder.worker.pid,
+            }));
+        },
+        async disposeAll() {
+            const live = [...holders.values()];
+            holders.clear();
+            await Promise.all(live.map(holder => holder.worker.dispose()));
+            for (const holder of live) {
+                if (holder.stagedDir !== undefined)
+                    rmSync(holder.stagedDir, { recursive: true, force: true });
+            }
+        },
+    };
+}
+//# sourceMappingURL=managed-workers.js.map

package/lib/mcp/client-grant.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Per-client external grants (SEC-04, SEC-01 tails, SEC-03).
+ *
+ * Before this module, every external MCP call dispatched through the HOST'S OWN
+ * interactive grant: the surface's `execute` ran `ctx.tools.execute` under the operator's
+ * grant, with `callerKind: 'interactive'` — so an external client was the operator as far
+ * as authorization and receipts were concerned, and the round-65 review recorded exactly
+ * that as a false claim to the contrary. SEC-04 requires an ISOLATED external execution
+ * context per client instead.
+ *
+ * This module is the grant half of that isolation. It derives a grant per AUTHENTICATED
+ * client at the point where the identity is already verified — the HTTP layer, after the
+ * static-token or OAuth check — and the derived identity travels with the call as CALLER
+ * IDENTITY, never as a second dispatch path:
+ *
+ * - the DEFAULT allowed set is the live published surface (the registered contracts plus
+ *   `tool_mode_run` — never `model_tools`, which stays host-local);
+ * - a per-client override narrows that set, so two clients can hold different grants;
+ * - the grant carries the CLIENT'S OWN `grantId` (`external:<clientId>`), recording
+ *   policy and limits, so a receipt records who called rather than pretending the
+ *   operator did — and a requested tool list can never extend any of it (BASE-05).
+ *
+ * @module @try-works/dsh-model-as-tool/mcp/client-grant
+ */
+import { type GrantLimits } from '../authority.ts';
+/** The per-client grant policy an operator configures. */
+export interface ClientGrantConfig {
+    /**
+     * The default allowed-tools set every authenticated client receives.
+     *
+     * Absent means the LIVE published surface at request time — the surface is the
+     * operator's export decision, so deriving the default from it keeps one source of
+     * truth. A non-empty list narrows the default for every client.
+     */
+    readonly allowedTools?: readonly string[];
+    /** Whether the client's calls may be recorded; defaults to `receipts` (OBS-02). */
+    readonly recordingPolicy?: 'none' | 'receipts';
+    /** Resource limits; defaults are {@link DEFAULT_LIMITS}. */
+    readonly limits?: Partial<GrantLimits>;
+    /** Per-client overrides, keyed by the authenticated client identity. */
+    readonly perClient?: Readonly<Record<string, {
+        /** The client's own allowed set; absent inherits the default above. */
+        readonly allowedTools?: readonly string[];
+        readonly recordingPolicy?: 'none' | 'receipts';
+        readonly limits?: Partial<GrantLimits>;
+    }>>;
+}
+/**
+ * The authenticated caller an external request runs as (SEC-04).
+ *
+ * Pure identity plus the derived grant — nothing executable, nothing caller-supplied.
+ */
+export interface ExternalCaller {
+    /** The authenticated client identity (static-token `clientId` or OAuth subject). */
+    readonly clientId: string;
+    /** The client's OWN grant identity, recorded in receipts — never the operator's. */
+    readonly grantId: string;
+    /** The tool names this client may invoke. */
+    readonly allowedTools: readonly string[];
+    readonly recordingPolicy: 'none' | 'receipts';
+    readonly limits: GrantLimits;
+}
+/**
+ * Derive one client's grant at authentication time.
+ *
+ * The client identity is INPUT — it must already be verified by the transport; nothing
+ * here authenticates, so a caller cannot reach this function with a chosen identity.
+ * @param clientId - the authenticated client identity.
+ * @param config - the operator's per-client grant policy, or undefined for the default.
+ * @param surfaceTools - the tool names the host currently publishes.
+ * @returns the derived caller identity and grant.
+ */
+export declare function resolveClientGrant(clientId: string, config: ClientGrantConfig | undefined, surfaceTools: readonly string[]): ExternalCaller;
+//# sourceMappingURL=client-grant.d.ts.map

package/lib/mcp/client-grant.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-grant.d.ts","sourceRoot":"","sources":["../../src/mcp/client-grant.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAkB,KAAK,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAElE,0DAA0D;AAC1D,MAAM,WAAW,iBAAiB;IAChC;;;;;;OAMG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACzC,mFAAmF;IACnF,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,GAAG,UAAU,CAAA;IAC9C,4DAA4D;IAC5D,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,CAAA;IACtC,wEAAwE;IACxE,QAAQ,CAAC,SAAS,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE;QAC3C,uEAAuE;QACvE,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;QACzC,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,GAAG,UAAU,CAAA;QAC9C,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,CAAA;KACvC,CAAC,CAAC,CAAA;CACJ;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,oFAAoF;IACpF,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,oFAAoF;IACpF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,6CAA6C;IAC7C,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAA;IACxC,QAAQ,CAAC,eAAe,EAAE,MAAM,GAAG,UAAU,CAAA;IAC7C,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;CAC7B;AAOD;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,iBAAiB,GAAG,SAAS,EACrC,YAAY,EAAE,SAAS,MAAM,EAAE,GAC9B,cAAc,CAmBhB"}

package/lib/mcp/client-grant.js

@@ -0,0 +1,60 @@
+/**
+ * Per-client external grants (SEC-04, SEC-01 tails, SEC-03).
+ *
+ * Before this module, every external MCP call dispatched through the HOST'S OWN
+ * interactive grant: the surface's `execute` ran `ctx.tools.execute` under the operator's
+ * grant, with `callerKind: 'interactive'` — so an external client was the operator as far
+ * as authorization and receipts were concerned, and the round-65 review recorded exactly
+ * that as a false claim to the contrary. SEC-04 requires an ISOLATED external execution
+ * context per client instead.
+ *
+ * This module is the grant half of that isolation. It derives a grant per AUTHENTICATED
+ * client at the point where the identity is already verified — the HTTP layer, after the
+ * static-token or OAuth check — and the derived identity travels with the call as CALLER
+ * IDENTITY, never as a second dispatch path:
+ *
+ * - the DEFAULT allowed set is the live published surface (the registered contracts plus
+ *   `tool_mode_run` — never `model_tools`, which stays host-local);
+ * - a per-client override narrows that set, so two clients can hold different grants;
+ * - the grant carries the CLIENT'S OWN `grantId` (`external:<clientId>`), recording
+ *   policy and limits, so a receipt records who called rather than pretending the
+ *   operator did — and a requested tool list can never extend any of it (BASE-05).
+ *
+ * @module @try-works/dsh-model-as-tool/mcp/client-grant
+ */
+import { DEFAULT_LIMITS } from "../authority.js";
+/** Read a valid recording policy, defaulting to the observable one. */
+function recordingPolicyOf(value) {
+    return value === 'none' ? 'none' : 'receipts';
+}
+/**
+ * Derive one client's grant at authentication time.
+ *
+ * The client identity is INPUT — it must already be verified by the transport; nothing
+ * here authenticates, so a caller cannot reach this function with a chosen identity.
+ * @param clientId - the authenticated client identity.
+ * @param config - the operator's per-client grant policy, or undefined for the default.
+ * @param surfaceTools - the tool names the host currently publishes.
+ * @returns the derived caller identity and grant.
+ */
+export function resolveClientGrant(clientId, config, surfaceTools) {
+    const perClient = config?.perClient?.[clientId];
+    const requested = perClient?.allowedTools ?? config?.allowedTools ?? surfaceTools;
+    const onSurface = new Set(surfaceTools);
+    // H3: the grant is INTERSECTED with the live published surface. An override is a
+    // static list, and a typo in it must not silently grant a tool the operator never
+    // meant to name — while an override that names a tool the surface does not (yet)
+    // publish grants nothing for it rather than a phantom allowance. The DEFAULT
+    // (the surface itself) passes through the intersection unchanged.
+    const allowedTools = requested.filter(name => onSurface.has(name));
+    return {
+        clientId,
+        // The client's OWN identity: a receipt that says `external:<id>` names the caller
+        // without pretending the operator made the call.
+        grantId: `external:${clientId}`,
+        allowedTools,
+        recordingPolicy: recordingPolicyOf(perClient?.recordingPolicy ?? config?.recordingPolicy),
+        limits: { ...DEFAULT_LIMITS, ...config?.limits, ...perClient?.limits },
+    };
+}
+//# sourceMappingURL=client-grant.js.map

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

@@ -0,0 +1,38 @@
+/**
+ * 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-model-as-tool/mcp/credential-cli
+ */
+/** The two streams the CLI owns, so a test can capture them separately. */
+export interface CliStreams {
+    /** The credential output — stdout in production, never anything else. */
+    out(line: string): void;
+    /** Diagnostics and usage — stderr in production. */
+    err(line: string): void;
+}
+/**
+ * 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 declare function runCredentialsCli(argv: readonly string[], streams: CliStreams): number;
+//# sourceMappingURL=credential-cli.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"credential-cli.d.ts","sourceRoot":"","sources":["../../src/mcp/credential-cli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AASH,2EAA2E;AAC3E,MAAM,WAAW,UAAU;IACzB,yEAAyE;IACzE,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,oDAAoD;IACpD,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;CACxB;AA0BD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,EAAE,UAAU,GAAG,MAAM,CA4FtF"}

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-model-as-tool/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