@cubicecho/agent-core 4.1.0 → 4.2.0

package/README.md

@@ -1165,6 +1165,24 @@ applies `resolveApiKey` afterwards, so a document naming somebody else's endpoin
 host send its own provider key there. `exportSpec(spec)` strips a bundled server's `env` and
 `headers`, and a redacted document is still a valid one.
 
+Those two fields are where the format puts a bundled server's credentials, and not the only place a
+pasted `.mcp.json` has them: an `--api-key` among the `args`, a `?token=` or a `user:pass@` in the
+`url`. `exportSpec` keeps those, since a server with its query string cut off is a different
+server, and `findSpecSecrets` says where they may be so a host can warn before it calls a file safe
+to share:
+
+```ts
+const out = exportSpec(spec);
+for (const { path, server, sign } of findSpecSecrets(out)) {
+  warn(`${server}: ${path} may hold a credential (${sign})`); // bundle.mcpServers[0].args[2] … (flag)
+}
+```
+
+A hint is a place and a reason — `SecretSign.Userinfo`, `Query`, `Flag`, `Value` or `Field` — and
+never the value. It is a guess in both directions: a credential in a positional argument with no
+telling prefix is missed, and a flag called `--keyboard` is named. A `${VAR}` is a reference, and is
+not reported.
+
 `bundle.mcpServers` is parsed only under `parseSpec(document, { bundle: true })`. A bundled server
 is a command line and an environment map, so importing one is equivalent to running a program, and
 that is a decision a host makes rather than inherits from a default.

package/dist/index.d.ts

@@ -25,7 +25,7 @@ export { preview } from './run/run-calls.ts';
 export { resetAll } from './runtime/reset.ts';
 export { createRuntime, defaultRuntime, type Runtime, type RuntimeOptions } from './runtime/runtime.ts';
 export { CAPABILITY_SNAPSHOT_VERSION, type CapabilitySnapshot, type EndpointSnapshot, exportCapabilities, importCapabilities, type ModelSnapshot, } from './runtime/snapshot.ts';
-export { AGENT_SPEC, AGENT_SPEC_VERSION, AGENT_TASKS, type AgentHook, type AgentSpec, type EndpointSpec, type ExportSpecOptions, exportSpec, type ModelSpec, type ParsedSpec, type ParseSpecOptions, type PromptPart, parseSpec, REF_FILE, REF_URL, RESOLVED_DEFAULTS, type ResolvedAgent, type ResolvedTask, type RetrySpec, resolveAgentSpec, SPEC_EVENTS, type SpecBundle, type SpecServer, type TaskSpec, type ToolsSpec, } from './spec/spec.ts';
+export { AGENT_SPEC, AGENT_SPEC_VERSION, AGENT_TASKS, type AgentHook, type AgentSpec, type EndpointSpec, type ExportSpecOptions, exportSpec, findSpecSecrets, type ModelSpec, type ParsedSpec, type ParseSpecOptions, type PromptPart, parseSpec, REF_FILE, REF_URL, RESOLVED_DEFAULTS, type ResolvedAgent, type ResolvedTask, type RetrySpec, resolveAgentSpec, type SecretHint, SecretSign, SPEC_EVENTS, type SpecBundle, type SpecServer, type TaskSpec, type ToolsSpec, } from './spec/spec.ts';
 export type { CatalogServer } from './tools/catalog.ts';
 export { type KeywordPreselection, type KeywordPreselectOptions, PRESELECT_SCHEMA, PRESELECT_SYSTEM, preselect, preselectByKeywords, preselectInput, preselection, preselectSystem, type ToolMatch, } from './tools/preselect.ts';
 export { CALL_TOOL, carryOver, catalogList, catalogPrompt, expandNames, holdsDefinitions, inCatalog, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadedTools, loadResult, orderTools, PROXY_TOOLS, proxiedCall, proxyCatalogPrompt, proxyLoadResult, requestedNames, shownCall, type ToolOrder, } from './tools/tool-loading.ts';

package/dist/index.js

@@ -25,7 +25,7 @@ export { preview } from './run/run-calls.js';
 export { resetAll } from './runtime/reset.js';
 export { createRuntime, defaultRuntime } from './runtime/runtime.js';
 export { CAPABILITY_SNAPSHOT_VERSION, exportCapabilities, importCapabilities, } from './runtime/snapshot.js';
-export { AGENT_SPEC, AGENT_SPEC_VERSION, AGENT_TASKS, exportSpec, parseSpec, REF_FILE, REF_URL, RESOLVED_DEFAULTS, resolveAgentSpec, SPEC_EVENTS, } from './spec/spec.js';
+export { AGENT_SPEC, AGENT_SPEC_VERSION, AGENT_TASKS, exportSpec, findSpecSecrets, parseSpec, REF_FILE, REF_URL, RESOLVED_DEFAULTS, resolveAgentSpec, SecretSign, SPEC_EVENTS, } from './spec/spec.js';
 export { PRESELECT_SCHEMA, PRESELECT_SYSTEM, preselect, preselectByKeywords, preselectInput, preselection, preselectSystem, } from './tools/preselect.js';
 export { CALL_TOOL, carryOver, catalogList, catalogPrompt, expandNames, holdsDefinitions, inCatalog, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadedTools, loadResult, orderTools, PROXY_TOOLS, proxiedCall, proxyCatalogPrompt, proxyLoadResult, requestedNames, shownCall, } from './tools/tool-loading.js';
 export { continueTurn, } from './turn/continuation.js';

package/dist/spec/spec.d.ts

@@ -359,7 +359,47 @@ export interface ExportSpecOptions {
  * The property worth keeping is that **a redacted spec is still a valid spec** — it parses, it
  * resolves, and what comes back is the same agent pointed at the same servers, needing only the
  * credentials the importing host supplies itself. So a bundled server loses its `env` and its
- * `headers` and nothing else, and nothing outside `bundle` is touched: the format has no
- * credential field at any depth, which is the reason there is nothing else to strip.
+ * `headers` and nothing else, and nothing outside `bundle` is touched: those two are the only
+ * fields the format gives a credential. A server can still carry one where the format gives it no
+ * field — an `--api-key` among its `args`, a token in its `url` — and that is kept, because
+ * cutting it would point the agent at a different server. `findSpecSecrets` says where to look.
  */
 export declare function exportSpec(spec: AgentSpec, { secrets }?: ExportSpecOptions): AgentSpec;
+/** Why `findSpecSecrets` named a place. */
+export declare const SecretSign: {
+    /** A URL with a user or a password before its host. */
+    readonly Userinfo: 'userinfo';
+    /** A URL query parameter whose name reads as a credential's. */
+    readonly Query: 'query';
+    /** The value of a command-line flag, or of a header written as `Name: value`, so named. */
+    readonly Flag: 'flag';
+    /** A value with the shape of a credential: a known key prefix, or `Bearer` and a token. */
+    readonly Value: 'value';
+    /** A key of the server itself whose name reads as a credential's. */
+    readonly Field: 'field';
+};
+/** Any one of the reasons in `SecretSign`. */
+export type SecretSign = (typeof SecretSign)[keyof typeof SecretSign];
+/** One place `findSpecSecrets` thinks a credential may be, and never the credential. */
+export interface SecretHint {
+    /** Where, in `parseSpec`'s spelling: `bundle.mcpServers[0].args[2]`. */
+    path: string;
+    /** The server's slug, or its id where it has no slug. */
+    server: string;
+    sign: SecretSign;
+}
+/**
+ * Where a document's bundled servers may still carry a credential after `exportSpec`.
+ *
+ * @param spec - A document, exported or not: `env` and `headers` are not reported either way,
+ * since `exportSpec` strips them.
+ * @returns One hint for each suspect place, in document order, each naming where and why and
+ * none holding the value. Empty for a document with no bundle.
+ *
+ * @remarks
+ * A host calls this before it offers an export as safe to share, and warns with what comes back.
+ * It reads a server's `url`, its `command` and `args`, and the names of its other keys, and is a
+ * guess both ways: a credential in a positional argument with no telling prefix is missed, and a
+ * flag called `--keyboard` is named. A `${VAR}` is a reference and is never named.
+ */
+export declare function findSpecSecrets(spec: AgentSpec): SecretHint[];

package/dist/spec/spec.js

@@ -896,8 +896,10 @@ export function resolveAgentSpec(layers) {
  * The property worth keeping is that **a redacted spec is still a valid spec** — it parses, it
  * resolves, and what comes back is the same agent pointed at the same servers, needing only the
  * credentials the importing host supplies itself. So a bundled server loses its `env` and its
- * `headers` and nothing else, and nothing outside `bundle` is touched: the format has no
- * credential field at any depth, which is the reason there is nothing else to strip.
+ * `headers` and nothing else, and nothing outside `bundle` is touched: those two are the only
+ * fields the format gives a credential. A server can still carry one where the format gives it no
+ * field — an `--api-key` among its `args`, a token in its `url` — and that is kept, because
+ * cutting it would point the agent at a different server. `findSpecSecrets` says where to look.
  */
 export function exportSpec(spec, { secrets = false } = {}) {
     if (secrets || !spec.bundle?.mcpServers) {
@@ -911,3 +913,160 @@ export function exportSpec(spec, { secrets = false } = {}) {
         },
     };
 }
+/** Why `findSpecSecrets` named a place. */
+export const SecretSign = {
+    /** A URL with a user or a password before its host. */
+    Userinfo: 'userinfo',
+    /** A URL query parameter whose name reads as a credential's. */
+    Query: 'query',
+    /** The value of a command-line flag, or of a header written as `Name: value`, so named. */
+    Flag: 'flag',
+    /** A value with the shape of a credential: a known key prefix, or `Bearer` and a token. */
+    Value: 'value',
+    /** A key of the server itself whose name reads as a credential's. */
+    Field: 'field',
+};
+/** A name that reads as a credential's: `api-key`, `TOKEN`, `Authorization`. */
+const SECRET_NAME = /key|token|secret|passw|auth|credential|bearer/i;
+/** A value shaped like a credential, whatever it is called. */
+const SECRET_VALUE = /^(sk-|pk-|rk-|ghp_|gho_|ghs_|github_pat_|glpat-|xox[abprs]-|AKIA)|\b(bearer|basic)\s+\S/i;
+/** What an absolute URL opens with. */
+const URL_SCHEME = /^[a-z][a-z0-9+.-]*:\/\//i;
+/** A header as one string, `Name: value`, as `--header` takes it. */
+const HEADER = /^([\w-]+):\s*(\S.*)$/;
+/** A flag carrying its own value, `--name=value`. */
+const FLAG_WITH_VALUE = /^(-{1,2}[^=\s]+)=(.+)$/;
+/** The keys of a server `findSpecSecrets` reads for itself, or `exportSpec` strips. */
+const SERVER_KEYS_READ = new Set(['id', 'slug', 'url', 'command', 'args', 'env', 'headers']);
+/**
+ * Whether a string is a credential written out, as against a reference to one.
+ *
+ * @param value - What a field, a flag or a parameter holds.
+ * @returns `false` for an empty string and for one holding a `${VAR}`, which names where the
+ * credential is and is not it.
+ */
+const writtenOut = (value) => value !== '' && VARIABLE.test(value) === false;
+/**
+ * Why a URL may carry a credential.
+ *
+ * @param text - A string, which need not be a URL.
+ * @returns `Userinfo`, `Query`, or `undefined` for a URL that shows neither and for a string
+ * that is not an absolute URL.
+ */
+function urlSign(text) {
+    if (URL_SCHEME.test(text) === false || URL.canParse(text) === false) {
+        return undefined;
+    }
+    const url = new URL(text);
+    if (writtenOut(url.username) || writtenOut(url.password)) {
+        return SecretSign.Userinfo;
+    }
+    for (const [name, value] of url.searchParams) {
+        if (SECRET_NAME.test(name) && writtenOut(value)) {
+            return SecretSign.Query;
+        }
+    }
+    return undefined;
+}
+/**
+ * Why one word of a command line may be a credential, read on its own.
+ *
+ * @param word - One argument.
+ * @returns A sign, or `undefined` for a word that shows none. A flag with no value of its own
+ * shows none here: `argumentSigns` reads the word after it.
+ */
+function wordSign(word) {
+    if (writtenOut(word) === false) {
+        return undefined;
+    }
+    const flag = FLAG_WITH_VALUE.exec(word);
+    if (flag?.[1] !== undefined && SECRET_NAME.test(flag[1])) {
+        return SecretSign.Flag;
+    }
+    const header = HEADER.exec(word);
+    if (header?.[1] !== undefined && SECRET_NAME.test(header[1])) {
+        return SecretSign.Flag;
+    }
+    // A flag's own value is read as a word too: `--url=https://user:pass@host`.
+    const value = flag?.[2] ?? word;
+    return SECRET_VALUE.test(value) ? SecretSign.Value : urlSign(value);
+}
+/**
+ * The words of a command line that may be credentials.
+ *
+ * @param words - The arguments in order. One that is not a string is passed over.
+ * @returns Each suspect word's index and its sign, in order, at most one sign a word.
+ *
+ * @remarks
+ * A flag named like a credential marks the word after it, unless that word is another flag.
+ */
+function argumentSigns(words) {
+    const signs = [];
+    let flagged = false;
+    for (const [index, word] of words.entries()) {
+        if (typeof word !== 'string') {
+            flagged = false;
+            continue;
+        }
+        const isFlag = word.startsWith('-');
+        const sign = flagged && isFlag === false && writtenOut(word) ? SecretSign.Flag : wordSign(word);
+        if (sign) {
+            signs.push([index, sign]);
+        }
+        flagged = isFlag && word.includes('=') === false && SECRET_NAME.test(word);
+    }
+    return signs;
+}
+/**
+ * The places one bundled server may carry a credential, outside its `env` and `headers`.
+ *
+ * @param server - The server as the document holds it.
+ * @param path - Where the server is, which each hint's path opens with.
+ * @returns The hints in the order `url`, `command`, `args`, then the server's other keys.
+ */
+function serverSecrets(server, path) {
+    const name = server.slug ?? server.id ?? '';
+    const hints = [];
+    const hint = (at, sign) => {
+        if (sign) {
+            hints.push({ path: `${path}.${at}`, server: name, sign });
+        }
+    };
+    if (typeof server.url === 'string') {
+        hint('url', urlSign(server.url));
+    }
+    if (typeof server.command === 'string') {
+        // A command written as one line is read as its words, and named once.
+        hint('command', argumentSigns(server.command.split(/\s+/))[0]?.[1]);
+    }
+    if (Array.isArray(server.args)) {
+        for (const [index, sign] of argumentSigns(server.args)) {
+            hint(`args[${index}]`, sign);
+        }
+    }
+    for (const [key, value] of Object.entries(server)) {
+        const empty = absent(value) || value === '' || (typeof value === 'string' && writtenOut(value) === false);
+        if (SERVER_KEYS_READ.has(key) === false && SECRET_NAME.test(key) && empty === false) {
+            hint(key, SecretSign.Field);
+        }
+    }
+    return hints;
+}
+/**
+ * Where a document's bundled servers may still carry a credential after `exportSpec`.
+ *
+ * @param spec - A document, exported or not: `env` and `headers` are not reported either way,
+ * since `exportSpec` strips them.
+ * @returns One hint for each suspect place, in document order, each naming where and why and
+ * none holding the value. Empty for a document with no bundle.
+ *
+ * @remarks
+ * A host calls this before it offers an export as safe to share, and warns with what comes back.
+ * It reads a server's `url`, its `command` and `args`, and the names of its other keys, and is a
+ * guess both ways: a credential in a positional argument with no telling prefix is missed, and a
+ * flag called `--keyboard` is named. A `${VAR}` is a reference and is never named.
+ */
+export function findSpecSecrets(spec) {
+    const servers = spec.bundle?.mcpServers ?? [];
+    return servers.flatMap((server, index) => serverSecrets(server, `bundle.mcpServers[${index}]`));
+}

package/llms.txt

@@ -220,6 +220,7 @@ A JSON document that defines an agent, and the rules for reading one.
 - `EndpointSpec` (type) — Where a model is reached, and how long to wait for it.
 - `ExportSpecOptions` (type) — What `exportSpec` takes besides the document.
 - `exportSpec` — A document fit to leave the host: the same agent, with the secrets of its bundled servers gone.
+- `findSpecSecrets` — Where a document's bundled servers may still carry a credential after `exportSpec`.
 - `ModelSpec` (type) — Which model answers and how, including the request fields this interface cannot spell.
 - `ParsedSpec` (type) — What `parseSpec` hands back.
 - `ParseSpecOptions` (type) — What `parseSpec` takes besides the document.
@@ -232,6 +233,8 @@ A JSON document that defines an agent, and the rules for reading one.
 - `ResolvedTask` (type) — One side task, resolved: a model, and the endpoint it is reached through.
 - `RetrySpec` (type) — What to do about a request lost before the model produced anything.
 - `resolveAgentSpec` — Layers documents into the flat object the loop takes, weakest first.
+- `SecretHint` (type) — One place `findSpecSecrets` thinks a credential may be, and never the credential.
+- `SecretSign` — Any one of the reasons in `SecretSign`.
 - `SPEC_EVENTS` — Every event a hook may be bound to: `HOOK_EVENTS`, under the name a document's reader knows.
 - `SpecBundle` (type) — What an agent carries so it can travel whole: the definitions of the servers it names.
 - `SpecServer` (type) — A bundled MCP server, validated only as far as a round trip needs and otherwise passed through.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cubicecho/agent-core",
-  "version": "4.1.0",
+  "version": "4.2.0",
   "description": "The endpoint-agnostic half of an OpenAI-compatible agent loop: tool-schema compatibility, on-demand tool loading, one-shot side tasks, run events, and a pooled client.",
   "keywords": [
     "openai",