@sema-agent/core 7.48.0 → 7.49.1

package/dist/core/compliance.d.ts

@@ -29,6 +29,9 @@ export declare const BUILTIN_COMPLIANCE_DENIES: Record<ComplianceProfile, readon
  * resolver FAULT (deny every managed capability), never as a partially-applied profile.
  */
 export declare function resolveComplianceDenies(posture: CompliancePosture): ReadonlySet<ComplianceCapability>;
+/** One deny list member's refusal under the closed capability set, labelled with the list that carried it, or
+ *  `undefined` when it is a member. */
+export declare function complianceCapabilityProblem(cap: unknown, owner: string): string | undefined;
 /** The core web-fetch tool face's canonical mounted name (`createWebFetchTool` in tools/web.ts). */
 export declare const WEB_FETCH_TOOL_NAME = "WebFetch";
 /**

package/dist/core/compliance.js

@@ -16,14 +16,19 @@ export function resolveComplianceDenies(posture) {
     }
     const denies = new Set(BUILTIN_COMPLIANCE_DENIES[posture.profile]);
     for (const cap of posture.additionalDenies ?? []) {
-        if (!COMPLIANCE_CAPABILITIES.includes(cap)) {
-            throw codedError("config.compliance_posture", `compliance posture additionalDenies contains "${String(cap)}", not a member of the closed capability set ` +
-                `(${COMPLIANCE_CAPABILITIES.join(", ")}) — a misspelled deny must never silently not-enforce.`);
-        }
+        const problem = complianceCapabilityProblem(cap, "compliance posture additionalDenies");
+        if (problem !== undefined)
+            throw codedError("config.compliance_posture", problem);
         denies.add(cap);
     }
     return denies;
 }
+export function complianceCapabilityProblem(cap, owner) {
+    if (COMPLIANCE_CAPABILITIES.some((member) => member === cap))
+        return undefined;
+    return (`${owner} contains "${String(cap)}", not a member of the closed capability set ` +
+        `(${COMPLIANCE_CAPABILITIES.join(", ")}) — a misspelled deny must never silently not-enforce.`);
+}
 export const WEB_FETCH_TOOL_NAME = "WebFetch";
 export function complianceCallDenial(denies, toolName) {
     if (denies.has("web_fetch") && toolName === WEB_FETCH_TOOL_NAME) {

package/dist/core/credential-vocabulary.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Where a text holds a credential — answered by ONE table, {@link CREDENTIAL_VOCABULARY}, and the three views read
+ * off it:
+ *  - refuse-write ({@link refuseWriteView}): the rows that carry a `strict` form, in table order. A hit fail-closed
+ *    rejects a durable write, so a strict form is narrow (vendor-distinctive prefix, long body, word boundary): a
+ *    wrongly refused ordinary note is that face's head risk.
+ *  - egress ({@link egressPassGroups}): every row's wide `match`, in table order, grouped into passes. A hit replaces
+ *    the value in text that is persisted and forwarded, so a wide form is broad: a missed credential is that face's
+ *    head risk and over-redaction is cheap.
+ *  - env names ({@link envNameView}): the exact credential names, the credential words by position, the
+ *    connection-string name shape and the token-prefix value predicate a spawned child's environment is judged by.
+ *  - record keys ({@link recordKeyView}): the same credential words, read as the name of a member of a structured record
+ *    (a header name, a config member) rather than of an environment variable.
+ *
+ * A family's strict and wide forms live on the SAME row, and every text the strict form matches the wide form matches
+ * too (machine-judged over the fixture file by `scripts/verify-credential-vocabulary.mjs`): the two faces may differ in
+ * floors, never in vocabulary. Detection is shared; each layer renders its own marker.
+ *
+ * Zero imports by design: this module is the detection definition and moves into its own package as written.
+ */
+/** How sure a detection is. */
+export type RedactionConfidence = "high" | "medium" | "low";
+/** Which rule table a finding names as its minter. A closed set: a report's entries can only have been written by
+ *  the engine's own tables, so "this finding says X" is an engine statement. */
+export type RedactionSource = "arg-summary" | "untrusted-egress" | "secret-env";
+/** One value family: "this run of characters is itself a credential". */
+export interface ValueFamilyRow {
+    /** Stable family name, `^[a-z0-9-]+$`; a finding's `family`. The refuse-write label is this id spelled with `_`. */
+    readonly id: string;
+    /** The finding `kind` this family reports (the coarse class a consumer groups by). */
+    readonly kind: string;
+    readonly source: RedactionSource;
+    readonly confidence: RedactionConfidence;
+    /** The wide form (egress), global. A capture group 1, when the form has one, is a label kept verbatim ahead of the
+     *  marker (`AccountKey=`, `api_key=`). */
+    readonly match: RegExp;
+    /** The strict form (refuse-write), never global. Present = this family refuses a durable write; absent = it does
+     *  not (refusing is the tightening, so it is written, never implied). */
+    readonly strict?: RegExp;
+    /** The egress pass this wide form runs in. Rows naming the same pass sit next to each other and join as ONE
+     *  alternation, so a token is taken at its leftmost start whichever of them it is (a nested shape is never cut by
+     *  an earlier family's pass). Absent = a pass of its own. */
+    readonly pass?: string;
+}
+/** Where a credential word counts in a name (env names are upper-cased words joined by `_`):
+ *  - `leading` — at the start of the name or right after `_`;
+ *  - `plural` — the word plus `S`, in the leading position;
+ *  - `counted-plural` — a plural, unless a count word (`MAX_TOKENS`) stands right in front of it;
+ *  - `separated` — only right after `_` (the shell's own `PWD` is none; a record has no such variable, so the record-key
+ *    view reads it as `leading`);
+ *  - `embedded` — anywhere (`AUTHTOKEN`, `MYSECRET`).
+ *  In every position the word must end the name or be followed by `_` or a digit (`KEYBOARD` is no word). */
+export type CredentialWordPosition = "leading" | "plural" | "counted-plural" | "separated" | "embedded";
+/** One credential word: "a name holding this word names a credential". */
+export interface CredentialWordRow {
+    readonly word: string;
+    readonly position: CredentialWordPosition;
+    /** Further words that name the same credential as a record key only, read in this row's position by the record-key
+     *  view alone (`AUTH` → the `Authorization` header). The env-name view never reads them: a variable named
+     *  `AUTHORIZATION` is not withheld by its name. */
+    readonly recordKeys?: readonly string[];
+}
+/** The URL userinfo rendering every renderer follows: keep the username (an auditor can tell whose account leaked
+ *  and revoke it) and replace the password, or replace the whole userinfo. */
+export interface VocabularyPolicy {
+    readonly urlUserinfo: "keep-username" | "whole";
+}
+export interface CredentialVocabulary {
+    /** Value families, in egress pass order. */
+    readonly values: readonly ValueFamilyRow[];
+    readonly words: readonly CredentialWordRow[];
+    /** The words that turn a following counted plural into a number. */
+    readonly countWords: readonly string[];
+    /** A connection string named as such (`DB_CONN_STR`, `CONNECTION_STRINGS`), case-insensitive. */
+    readonly connectionStringName: RegExp;
+    /** Credential env names, each also judged under the `INPUT_` prefix (a GitHub Actions input). */
+    readonly exactEnvNames: readonly string[];
+    /** Credential-shaped names that hold no credential: exact names, never a shape. */
+    readonly nonSecretExactNames: readonly string[];
+    /** The one name shape that holds no credential whatever words it carries: git's `GIT_CONFIG_KEY_<n…>` names a
+     *  configuration key (its value sits in `GIT_CONFIG_VALUE_<n>`). Read by every name view, beside the exact names. */
+    readonly nonSecretNameShape: RegExp;
+    /** A leading vendor prefix that spells a credential word without being one (`AUTH0_`): dropped from a name before the
+     *  credential words are looked for, in every name view alike. */
+    readonly nonCredentialPrefix: RegExp;
+    /** A value (or a password-less URL user) opening with a known token prefix. */
+    readonly tokenPrefix: RegExp;
+    readonly policy: VocabularyPolicy;
+}
+/**
+ * The URI scheme, bounded so it cannot backtrack: RFC 3986's scheme production plus `_`, at most 64 characters. An
+ * unbounded `\w+` made every `://` pattern quadratic in the longest unbroken word run (one long base64 paste cost
+ * seconds of synchronous CPU); the bound makes it linear and redacts no less on any URL.
+ */
+export declare const URI_SCHEME_SOURCE: string;
+export declare const CREDENTIAL_VOCABULARY: CredentialVocabulary;
+/** The refuse-write label of a family: its id spelled with `_` (surfaced in the refusal; never the matched value). */
+export declare const refuseLabel: (id: string) => string;
+/** One refuse-write form: the family's label and its strict form. */
+export interface RefuseWriteForm {
+    readonly label: string;
+    readonly re: RegExp;
+}
+/** The refuse-write view: every row carrying a strict form, in table order (the first hit names the label). */
+export declare function refuseWriteView(vocabulary: CredentialVocabulary): readonly RefuseWriteForm[];
+/** The egress view: the rows in table order, each run of adjacent rows naming the same `pass` as one group. */
+export declare function egressPassGroups(vocabulary: CredentialVocabulary): ReadonlyArray<readonly ValueFamilyRow[]>;
+/** The env-name view: what {@link CREDENTIAL_VOCABULARY} says about variable names and token-prefixed values. */
+export interface EnvNameView {
+    /** Upper-cased, `-` read as `_`; each name also under `INPUT_`. */
+    readonly exactNames: ReadonlySet<string>;
+    readonly nonSecretExactNames: ReadonlySet<string>;
+    readonly nonSecretNameShape: RegExp;
+    readonly nonCredentialPrefix: RegExp;
+    /** A credential word in its position, case-insensitive. */
+    readonly credentialWord: RegExp;
+    readonly connectionStringName: RegExp;
+    /** The counted plurals as a regex source (a plural no count word touches). */
+    readonly countedPlural: string;
+    readonly tokenPrefix: RegExp;
+}
+export declare function envNameView(vocabulary: CredentialVocabulary): EnvNameView;
+/** `camelCase` / `PascalCase` read as `_`-separated words, `OAuth` and `NextAuth` kept whole. */
+export declare function splitCamelCase(name: string): string;
+/** The record-key view: what {@link CREDENTIAL_VOCABULARY} says about the names of a structured record's members (an HTTP
+ *  header, a config or detail member) — the credential words of the env-name view, each row's `recordKeys` spellings
+ *  besides, and a `separated` word standing alone (`pwd`, `pass`: a record has no shell variable of that name). The names
+ *  the vocabulary declares non-secret stay non-secret here too: one fact, one reading in every view. */
+export interface RecordKeyView {
+    /** A credential word in its position, case-insensitive. Applied to a key with `-` read as `_`, as written and
+     *  camel-split ({@link isSensitiveRecordKey}). */
+    readonly credentialWord: RegExp;
+    readonly nonSecretExactNames: ReadonlySet<string>;
+    readonly nonSecretNameShape: RegExp;
+    readonly nonCredentialPrefix: RegExp;
+}
+export declare function recordKeyView(vocabulary: CredentialVocabulary): RecordKeyView;
+/** Does `key`, the name of a record's member (`Proxy-Authorization`, `pwd`, `X_API_KEY`, `clientSecret`), name a credential?
+ *  Case does not matter, `-` and `_` are one. `view` is the vocabulary's record-key view unless a caller holds another. */
+export declare function isSensitiveRecordKey(key: string, view?: RecordKeyView): boolean;

package/dist/core/credential-vocabulary.js

@@ -0,0 +1,131 @@
+export const URI_SCHEME_SOURCE = String.raw `[A-Za-z][A-Za-z0-9+.\-_]{0,63}`;
+const VENDOR_BODY = "[A-Za-z0-9_-]{8,}";
+export const CREDENTIAL_VOCABULARY = {
+    values: [
+        { id: "github-token", kind: "prefixed-token", source: "arg-summary", confidence: "high", pass: "vendor-prefixed", match: new RegExp(`(?<![A-Za-z0-9])gh[opsur][-_]${VENDOR_BODY}`, "g"), strict: /\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{36,}\b/ },
+        { id: "github-fine-grained-pat", kind: "prefixed-token", source: "arg-summary", confidence: "high", pass: "vendor-prefixed", match: new RegExp(`(?<![A-Za-z0-9])github_pat[-_]${VENDOR_BODY}`, "g"), strict: /\bgithub_pat_[A-Za-z0-9_]{60,}\b/ },
+        { id: "openai-api-key", kind: "prefixed-token", source: "arg-summary", confidence: "high", pass: "vendor-prefixed", match: new RegExp(`(?<![A-Za-z0-9])sk-${VENDOR_BODY}`, "g"), strict: /\bsk-(?:ant-(?:api03-)?|proj-)?[A-Za-z0-9_]{20,}\b/ },
+        { id: "stripe-secret-key", kind: "prefixed-token", source: "arg-summary", confidence: "high", pass: "vendor-prefixed", match: new RegExp(`(?<![A-Za-z0-9])(?:sk_|rk[-_])${VENDOR_BODY}`, "g"), strict: /\b[sr]k_(?:live|test)_[A-Za-z0-9]{24,}\b/ },
+        { id: "stripe-publishable-key", kind: "prefixed-token", source: "arg-summary", confidence: "high", pass: "vendor-prefixed", match: new RegExp(`(?<![A-Za-z0-9])pk[-_]${VENDOR_BODY}`, "g") },
+        { id: "gitlab-pat", kind: "prefixed-token", source: "arg-summary", confidence: "high", pass: "vendor-prefixed", match: /(?<![A-Za-z0-9])glpat-[A-Za-z0-9_-]{20,}/g },
+        { id: "google-api-key", kind: "prefixed-token", source: "arg-summary", confidence: "high", match: /(?<![A-Za-z0-9])AIza[A-Za-z0-9_-]{20,}/g, strict: /\bAIza[0-9A-Za-z_-]{35}\b/ },
+        { id: "slack-token", kind: "prefixed-token", source: "arg-summary", confidence: "high", match: /(?<![A-Za-z0-9])xox[baprs]-[A-Za-z0-9-]{10,}/g, strict: /\bxox[baprs]-(?:[A-Za-z0-9]+-){1,3}[A-Za-z0-9]{16,}\b/ },
+        { id: "aws-access-key-id", kind: "prefixed-token", source: "arg-summary", confidence: "high", match: /(?<![A-Za-z0-9])(?:AKIA|ASIA)[0-9A-Z]{12,}/g, strict: /\bAKIA[0-9A-Z]{16}\b/ },
+        { id: "huggingface-token", kind: "prefixed-token", source: "arg-summary", confidence: "high", match: /(?<![A-Za-z0-9])hf_[A-Za-z0-9]{20,}/g, strict: /\bhf_(?=[A-Za-z0-9]*[0-9])[A-Za-z0-9]{20,}\b/ },
+        { id: "jwt", kind: "jwt", source: "arg-summary", confidence: "high", match: /(?<![A-Za-z0-9])eyJ[A-Za-z0-9._-]{20,}/g, strict: /\beyJ[A-Za-z0-9_-]+\.eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]{16,}\b/ },
+        { id: "private-key", kind: "private-key-block", source: "arg-summary", confidence: "high", match: /-----BEGIN[ A-Z0-9]*PRIVATE KEY(?: BLOCK)?-----[\s\S]*?(?:-----END[ A-Z0-9]*PRIVATE KEY(?: BLOCK)?-----|$)/g, strict: /-----BEGIN (?:[A-Z0-9]+ )*PRIVATE KEY(?: BLOCK)?-----/ },
+        { id: "bearer-token", kind: "bearer-token", source: "arg-summary", confidence: "high", match: /(?<![A-Za-z0-9])Bearer\s+[A-Za-z0-9._~+/-]{8,}=*/gi, strict: /\bAuthorization:\s*Bearer\s+(?=[A-Za-z0-9._~+/-]*[0-9])[A-Za-z0-9._~+/-]{20,}=*/ },
+        { id: "azure-storage-account-key", kind: "prefixed-token", source: "arg-summary", confidence: "high", match: /(AccountKey=)[A-Za-z0-9+/]{40,}={0,2}/g, strict: /AccountKey=[A-Za-z0-9+/]{40,}={0,2}/ },
+        { id: "keyword-value", kind: "keyword-value", source: "arg-summary", confidence: "medium", match: /(?<![A-Za-z0-9])((?:token|secret|key|password|passwd|credential|authorization)["']?\s*[=:]\s*["']?)[^\s"';|&]{4,}/gi },
+        { id: "url-userinfo", kind: "url-credentials", source: "untrusted-egress", confidence: "medium", match: new RegExp(String.raw `(${URI_SCHEME_SOURCE}:\/\/)((?:[^/\s"'@]*@)+)`, "gi") },
+        { id: "signed-url-param", kind: "signed-url-param", source: "untrusted-egress", confidence: "high", match: /([?&#](?:sig|signature|sas|code)=)[^&\s"'#]+/gi },
+    ],
+    words: [
+        ...["TOKEN", "SECRET", "PASSWORD", "PASSWD", "PASSPHRASE", "KEY"].map((word) => ({ word, position: "leading" })),
+        { word: "AUTH", position: "leading", recordKeys: ["AUTHORIZATION"] },
+        ...["COOKIE", "PAT", "DSN", "WEBHOOK", "CREDENTIAL", "CREDENTIALS", "CREDS", "APIKEY", "ACCESSKEY", "SECRETKEY", "ACCOUNTKEY", "PRIVATEKEY", "AUTHKEY", "SSHKEY", "SIGNINGKEY", "MASTERKEY", "DEPLOYKEY", "ENCRYPTIONKEY", "PGPASSWORD", "SSHPASS"].map((word) => ({ word, position: "leading" })),
+        ...["KEY", "SECRET", "PASSWORD", "CREDENTIAL"].map((word) => ({ word, position: "plural" })),
+        { word: "TOKEN", position: "counted-plural" },
+        ...["PWD", "PASS", "JWT"].map((word) => ({ word, position: "separated" })),
+        ...["TOKEN", "SECRET", "PASSWORD", "PASSWD", "PASSPHRASE"].map((word) => ({ word, position: "embedded" })),
+    ],
+    countWords: ["MAX", "OUTPUT", "INPUT", "THINKING", "NUM", "TOTAL"],
+    connectionStringName: /CONN(ECT(ION)?)?_?STR(ING)?S?(?=$|[_0-9])/i,
+    exactEnvNames: [
+        "ANTHROPIC_API_KEY", "CLAUDE_CODE_OAUTH_TOKEN", "CLAUDE_CODE_ARTIFACTS_API_TOKEN", "CLAUDE_CODE_MEMORY_API_TOKEN",
+        "CLAUDE_CODE_SLACK_TAG_TOKEN", "ANTHROPIC_AUTH_TOKEN", "ANTHROPIC_FOUNDRY_API_KEY", "ANTHROPIC_FOUNDRY_AUTH_TOKEN",
+        "ANTHROPIC_AWS_API_KEY", "ANTHROPIC_CUSTOM_HEADERS", "AWS_SECRET_ACCESS_KEY", "AWS_SESSION_TOKEN",
+        "AWS_BEARER_TOKEN_BEDROCK", "GOOGLE_APPLICATION_CREDENTIALS", "GOOGLE_GHA_CREDS_PATH", "AZURE_CLIENT_SECRET",
+        "IDENTITY_HEADER", "MSI_SECRET", "AZURE_CLIENT_CERTIFICATE_PATH", "AZURE_CLIENT_CERTIFICATE_PASSWORD",
+        "AZURE_PASSWORD", "AZURE_FEDERATED_TOKEN_FILE", "AWS_WEB_IDENTITY_TOKEN_FILE",
+        "AWS_CONTAINER_CREDENTIALS_RELATIVE_URI", "AWS_CONTAINER_CREDENTIALS_FULL_URI",
+        "AWS_CONTAINER_AUTHORIZATION_TOKEN", "AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE", "CLOUDSDK_AUTH_ACCESS_TOKEN",
+        "GOOGLE_OAUTH_ACCESS_TOKEN", "CLAUDE_CODE_OAUTH_REFRESH_TOKEN", "HF_TOKEN", "HUGGING_FACE_HUB_TOKEN",
+        "HUGGINGFACEHUB_API_TOKEN", "NODE_AUTH_TOKEN", "NUGET_AUTH_TOKEN", "CARGO_REGISTRY_TOKEN", "TWINE_PASSWORD",
+        "TWINE_USERNAME", "PYPI_TOKEN", "PYPI_API_TOKEN", "UV_PUBLISH_TOKEN", "UV_PUBLISH_PASSWORD", "UV_PUBLISH_USERNAME",
+        "FLIT_PASSWORD", "FLIT_USERNAME", "HATCH_INDEX_AUTH", "HATCH_INDEX_USER", "GEM_HOST_API_KEY", "MATURIN_PYPI_TOKEN",
+        "MATURIN_PASSWORD", "MATURIN_USERNAME", "CONAN_LOGIN_USERNAME", "CONAN_PASSWORD", "ANACONDA_API_TOKEN",
+        "BINSTAR_API_TOKEN", "VAULT_TOKEN", "VAULT_AUTH_TOKEN", "VAULT_ROLE_ID", "VAULT_SECRET_ID", "CONSUL_HTTP_TOKEN",
+        "CONSUL_HTTP_AUTH", "NOMAD_TOKEN", "NOMAD_HTTP_AUTH", "CI_REGISTRY_USER", "CI_DEPLOY_USER", "JF_USER",
+        "FASTLANE_SESSION", "MATCH_GIT_BASIC_AUTHORIZATION", "SONAR_TOKEN", "SONARQUBE_SCANNER_PARAMS",
+        "SONAR_SCANNER_JSON_PARAMS", "SLACK_WEBHOOK_URL", "SLACK_WEBHOOK", "DISCORD_WEBHOOK", "DISCORD_WEBHOOK_URL",
+        "TEAMS_WEBHOOK_URL", "MS_TEAMS_WEBHOOK_URI", "ANTHROPIC_IDENTITY_TOKEN", "ANTHROPIC_IDENTITY_TOKEN_FILE",
+        "CLOUDSDK_AUTH_ACCESS_TOKEN_FILE", "CLOUDSDK_AUTH_AUTHORIZATION_TOKEN_FILE", "AZURE_AUTH_LOCATION",
+        "ACTIONS_ID_TOKEN_REQUEST_TOKEN", "ACTIONS_ID_TOKEN_REQUEST_URL", "ACTIONS_RUNTIME_TOKEN", "ACTIONS_RUNTIME_URL",
+        "ALL_INPUTS", "VSS_NUGET_EXTERNAL_FEED_ENDPOINTS", "ARTIFACTS_CREDENTIALPROVIDER_EXTERNAL_FEED_ENDPOINTS",
+        "VSS_NUGET_ACCESSTOKEN", "ARTIFACTS_CREDENTIALPROVIDER_ACCESSTOKEN", "COMPOSER_AUTH", "OVERRIDE_GITHUB_TOKEN",
+        "DEFAULT_WORKFLOW_TOKEN", "SSH_SIGNING_KEY",
+    ],
+    nonSecretExactNames: [
+        "PARTITION_KEY", "SORT_KEY", "RANGE_KEY", "IDEMPOTENCY_KEY", "CACHE_KEY", "ROUTING_KEY",
+        "DB_FOREIGN_KEYS", "JSON_SORT_KEYS",
+        "MAX_NEW_TOKENS", "MAX_COMPLETION_TOKENS", "AIDER_MAP_TOKENS", "AIDER_MAX_CHAT_HISTORY_TOKENS",
+        "MAX_BATCH_PREFILL_TOKENS", "MAX_WAITING_TOKENS", "MAX_TOP_N_TOKENS", "RATE_LIMIT_TOKENS",
+        "PROMPT_TOKENS", "CONTEXT_TOKENS",
+    ],
+    nonSecretNameShape: /^GIT_CONFIG_KEY_[0-9][A-Za-z0-9_]*$/,
+    nonCredentialPrefix: /^AUTH0_/i,
+    tokenPrefix: /^(?:gh[opusr]_|github_pat_|glpat-|xox[abpr]-|sk-|pk-|AKIA|eyJ|ya29\.|npm_)/,
+    policy: { urlUserinfo: "keep-username" },
+};
+export const refuseLabel = (id) => id.replaceAll("-", "_");
+export function refuseWriteView(vocabulary) {
+    return vocabulary.values.flatMap((row) => (row.strict === undefined ? [] : [{ label: refuseLabel(row.id), re: row.strict }]));
+}
+export function egressPassGroups(vocabulary) {
+    const groups = [];
+    for (const row of vocabulary.values) {
+        const last = groups[groups.length - 1];
+        if (row.pass !== undefined && last !== undefined && last[0].pass === row.pass)
+            last.push(row);
+        else
+            groups.push([row]);
+    }
+    return groups;
+}
+function credentialWordPattern(countWords, rows) {
+    const at = (position) => rows.filter((r) => r.position === position).map((r) => r.word);
+    const countedPlural = `(?<!(?:^|_)(?:${countWords.join("|")})_)(?:${at("counted-plural").join("|")})S`;
+    const [separated, embedded] = [at("separated"), at("embedded")];
+    const positions = [
+        `(^|_)(${at("leading").join("|")}|(${at("plural").join("|")})S|${countedPlural})`,
+        ...(separated.length > 0 ? [`_(${separated.join("|")})`] : []),
+        ...(embedded.length > 0 ? [`(${embedded.join("|")})`] : []),
+    ];
+    return { credentialWord: new RegExp(`(${positions.join("|")})(?=$|[_0-9])`, "i"), countedPlural };
+}
+export function envNameView(vocabulary) {
+    const { credentialWord, countedPlural } = credentialWordPattern(vocabulary.countWords, vocabulary.words);
+    return {
+        exactNames: new Set(vocabulary.exactEnvNames.flatMap((name) => [name, `INPUT_${name}`])),
+        nonSecretExactNames: new Set(vocabulary.nonSecretExactNames),
+        nonSecretNameShape: vocabulary.nonSecretNameShape,
+        nonCredentialPrefix: vocabulary.nonCredentialPrefix,
+        credentialWord,
+        connectionStringName: vocabulary.connectionStringName,
+        countedPlural,
+        tokenPrefix: vocabulary.tokenPrefix,
+    };
+}
+export function splitCamelCase(name) {
+    return ["OAuth", "NextAuth"]
+        .reduce((text, word) => text.replaceAll(word, word[0] + word.slice(1).toLowerCase()), name)
+        .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+        .replace(/([A-Z])([A-Z][a-z])/g, "$1_$2");
+}
+export function recordKeyView(vocabulary) {
+    const rows = vocabulary.words.flatMap((w) => [w.word, ...(w.recordKeys ?? [])].map((word) => ({ word, position: w.position === "separated" ? "leading" : w.position })));
+    return {
+        credentialWord: credentialWordPattern(vocabulary.countWords, rows).credentialWord,
+        nonSecretExactNames: new Set(vocabulary.nonSecretExactNames),
+        nonSecretNameShape: vocabulary.nonSecretNameShape,
+        nonCredentialPrefix: vocabulary.nonCredentialPrefix,
+    };
+}
+const RECORD_KEYS = recordKeyView(CREDENTIAL_VOCABULARY);
+export function isSensitiveRecordKey(key, view = RECORD_KEYS) {
+    if (view.nonSecretExactNames.has(key.toUpperCase()) || view.nonSecretNameShape.test(key))
+        return false;
+    const words = key.replace(view.nonCredentialPrefix, "").replace(/-/g, "_");
+    return view.credentialWord.test(words) || view.credentialWord.test(splitCamelCase(words));
+}

package/dist/core/decision-receipt.js

@@ -11,7 +11,7 @@ export const refusedOutOfContract = (message) => {
 export const isEngineRefusal = (d) => typeof d === "object" && d !== null && ENGINE_REFUSALS.has(d);
 const DECISION_REASONS = Object.freeze(["rule", "mode", "hook", "safety", "classifier", "persisted_rule", "sandbox", "org_rule", "org_unavailable", "read_only", "skill", "deployment_rule", "request_rule"]);
 const DECISION_ACTIONS = Object.keys({ allow: 0, deny: 0, ask: 0 });
-const GUARDS = Object.keys({ dangerous_delete: 0, unverifiable_delete: 0, transcript_write: 0, artifact_shared_read: 0 });
+const GUARDS = Object.keys({ dangerous_delete: 0, unverifiable_delete: 0, unverifiable_shell_text: 0, transcript_write: 0, artifact_shared_read: 0 });
 const RULE_UNREADABLE_WORDS = Object.keys({ content_deny: 0, content_ask: 0, persisted_call: 0 });
 const AUTHORED_BY_WORDS = Object.keys({ deployment: 0 });
 const memberOf = (words) => {

package/dist/core/effective-path-target.d.ts

@@ -26,12 +26,12 @@
  *
  * A target is seen three ways: its LEXICAL view (the spelling joined to the selected base, `.` / `..` folded —
  * zero IO), its CANONICAL view (the same spelling resolved by the execution environment: symlinks, aliases of the
- * tree, the disk's own case) and the HOPS of its leaf's symlink chain. {@link readPathViews} is the one producer of
+ * tree, the disk's own case) and the HOPS of its leaf's symlink chain. {@link readPath} is the one producer of
  * those views — the tool's own resolution and its deny judgment read it, and so does {@link readCallTarget}, which
  * a Runner stamp point calls once per adjudicated call and hands to every rule lane as
  * `ToolCallRequest.targetReading`. Every rule lane reads a call's target through ONE reader, {@link callTargetViewsOf}:
  * the reading's views when the call carries one, else the call's own lexical view (a bare request). The judgment over
- * those views is the deny tables' (`pathRowsReach`): any view a deny or ask row reaches is reached; an allow row admits a
+ * those views is every table's (`judgePathRows`, path-guard-rows.ts): any view a deny or ask row reaches is reached; an allow row admits a
  * call only when it admits every view of the declared reading.
  *
  * ## What it does NOT decide
@@ -46,7 +46,7 @@
  * declaration to read; the day it declares one, it reads the same selector as everything else.
  */
 import { canonicalizeTarget, type PathFamily, type PathIdentity, type Win32NamespaceRefusal } from "../tools/fs/safety.js";
-import type { TargetViews } from "../tools/fs/read-deny.js";
+import type { TargetViews } from "./path-guard-rows.js";
 import type { ExecutionEnv } from "../internal/harness-types.js";
 import type { ToolCallPathTarget } from "./tool-face.js";
 import { type ToolCallLike } from "./tool-registry.js";
@@ -75,7 +75,7 @@ export declare function pathTargetBaseOf(pt: Pick<ToolCallPathTarget, "base"> |
  * Lives HERE rather than beside the search engine because two readers need the identical cut: Glob's own
  * scope resolution and the path fences that must know which directory an absolute pattern really searches.
  */
-export declare function splitAbsoluteGlobPattern(pattern: string, family: PathFamily | undefined): {
+export declare function splitAbsoluteGlobPattern(pattern: string, tree: PathFamily | undefined): {
     baseDir: string;
     relativePattern: string;
 } | {
@@ -91,6 +91,7 @@ export declare function splitAbsoluteGlobPattern(pattern: string, family: PathFa
 export type PathTargetReading = {
     readonly kind: "path";
     readonly identity: PathIdentity;
+    readonly family: PathFamily;
 } | {
     readonly kind: "unreadable";
     readonly reason: string;
@@ -126,17 +127,34 @@ export declare function effectivePathSpellingOf(call: ToolCallLike, pt: ToolCall
 } | {
     readonly refused: Win32NamespaceRefusal;
 } | undefined;
+/**
+ * THE path prelude: ONE spelling → the identity of the path the TOOL will open it as. Every reading of a spelling passes
+ * through here — the target slot's own value, a `patternParam`'s derived base, an empty slot's base, the views of
+ * {@link readPath} — in one order: the family ({@link readingFamilyOf}), the namespace screen, the anchor step
+ * ({@link anchorSpelling} against `declaredBase` — a relative spelling with no usable base is `unreadable`), the identity.
+ * A win-form spelling on a POSIX tree is therefore an ordinary relative name under the DECLARED base — the same file the fs
+ * throat opens — and a `/x` on a win tree lands on the base's drive. Nothing is case-folded and `~` is not expanded here:
+ * a fold is a judge's, an expansion a reader's.
+ */
+export declare function placeSpelling(spelled: string, declaredBase: string | undefined, bases: ToolPathBases): PathTargetReading;
+/** The family one reading is taken in: the tree's (its root, else its cwd), or — for an address no tree places — the
+ *  spelling's own ({@link familyFor} `"own"`), so a treeless `C:\x` and a treeless `/x` are each an address in their family. */
+export declare function readingFamilyOf(bases: ToolPathBases, spelled: string): PathFamily;
 /**
  * ONE reading of a call's path slot as VIEWS. `path`: the LEXICAL view (the spelling joined to the selected base and
  * folded — a native spelling of the tree's family), the CANONICAL view when the environment answered (absent ⇒ not asked
  * or no answer: an absent view takes no part in a judgment and is never a refusal) and the HOPS of the leaf's symlink
- * chain when the environment declares one. `unreadable` / `refused` read as in {@link PathTargetReading}.
+ * chain when the environment declares one. `unread`: a view the environment was ASKED for did not answer (the canonical
+ * one, or the hops of a chain the canonical view says was followed) — the allow direction then admits nothing
+ * ({@link callTargetViewsOf}: an allow must see every view where a rule names it). `unreadable` / `refused` read as in
+ * {@link PathTargetReading}.
  */
 export type CallTargetView = {
     readonly kind: "path";
     readonly lexical: string;
     readonly canonical?: string;
     readonly hops?: readonly string[];
+    readonly unread?: true;
 } | {
     readonly kind: "unreadable";
     readonly reason: string;
@@ -159,23 +177,60 @@ export interface CallTargetReading {
 }
 /** The environment's answer the canonical view rests on — the throat's own, so the tool keeps reading the refusal it gave. */
 export type CanonicalAnswer = Awaited<ReturnType<typeof canonicalizeTarget>>;
-/** The three views of one spelling as {@link readPathViews} produces them. */
+/** The three views of one spelling as {@link readPath} produces them. */
 export interface PathViews {
     readonly lexical: PathTargetReading;
-    /** `undefined` ⇒ the environment was not asked (none supplied, or a spelling this reading cannot locate). */
+    /** `undefined` ⇒ the environment was not asked (the contract's `lexical` views, no environment, no tree, or a spelling
+     *  this reading cannot locate). */
     readonly canonical?: CanonicalAnswer;
     readonly hops: readonly string[];
+    /** The hop chain was asked for (a link was followed) and could not be read. */
+    readonly hopsUnread?: true;
 }
+/**
+ * The CONTRACT of one path reading — what the caller asks of a spelling, written at the call rather than implied by which
+ * helper it happened to call. Two intents:
+ *
+ *  · `"resolve"` ({@link readPath}): the spelling becomes a target. `views`: `"lexical"` — the placed spelling alone
+ *    ({@link placeSpelling}, zero I/O); `"canonical"` — and the execution environment's answer for where it lands (the
+ *    throat's own canonicalizer); `"chain"` — and the hops of the leaf's symlink chain wherever a link may be on the way.
+ *    The base a relative spelling needs is the reading's `base` argument (the tool's declared selection): absent ⇒ the
+ *    relative spelling is `unreadable`, never guessed; a namespace spelling the tree refuses is `refused` with its word; a
+ *    chain the environment cannot read is marked `hopsUnread`, never a refusal.
+ *  · `"validate-coordinate"` / `"validate-grant"` ({@link validatePath}): the value was HANDED to the engine as an address
+ *    (a configured home, a configuration root, a checkpoint's coordinates, a probe's grant offer) and is checked, never
+ *    repaired — no base, no tree, its own spelling its family source. A coordinate must be a string fully qualified in its
+ *    own family; a grant must also be bounded and free of control characters, already in normal form, not a family root,
+ *    free of a Win32 alias component and outside every device namespace (a repaired directory is a different directory
+ *    than the one a card would show).
+ */
+export type PathContract = {
+    readonly intent: "resolve";
+    readonly views: "lexical" | "canonical" | "chain";
+} | {
+    readonly intent: "validate-coordinate" | "validate-grant";
+};
+/** The display bound on a validated grant (a probe's read-root offer): generous next to a real `PATH_MAX`, tight enough that
+ *  the seat cannot become an unbounded prose channel onto an approval card. */
+export declare const READ_ROOT_CANDIDATE_DIR_MAX = 1024;
+/**
+ * THE validator of a path value the engine was handed ({@link PathContract} `validate-*`): the value itself when it holds
+ * under the contract, else `undefined`. Every seat that accepts a configured or recorded address reads it through here, so
+ * "is this an address" is answered once — a UNC with no share (`\\x`) is no address in any family.
+ */
+export declare function validatePath(value: unknown, contract: Extract<PathContract, {
+    readonly intent: "validate-coordinate" | "validate-grant";
+}>): string | undefined;
 /**
  * The ONE producer of a target's views: `spelled` against `base` (the base the tool's declaration selected), under the
- * tree `bases` names. Lexical through the same resolution {@link effectivePathTargetOf} reads; canonical through the
- * throat's own canonicalizer; the hops (when `opts.hops` and the canonical view answered) through the leaf's chain. The
- * tool's resolution and deny judgment read this, and so does {@link readCallTarget}; an environment that THROWS
- * propagates here (each caller holds its own posture: the tool refuses, the reading leaves the view absent).
- */
-export declare function readPathViews(env: ExecutionEnv | undefined, spelled: string, base: string | undefined, bases: ToolPathBases, signal?: AbortSignal, opts?: {
-    readonly hops?: boolean;
-}): Promise<PathViews>;
+ * tree `bases` names, as far as `contract` asks. Lexical through the one prelude ({@link placeSpelling}); canonical through
+ * the throat's own canonicalizer; the hops (when the contract asks for the chain and the canonical view answered) through
+ * the leaf's chain. The tool's resolution and deny judgment read this, and so does {@link readCallTarget}; an environment
+ * that THROWS propagates here (each caller holds its own posture: the tool refuses, the reading leaves the view absent).
+ */
+export declare function readPath(env: ExecutionEnv | undefined, spelled: string, base: string | undefined, bases: ToolPathBases, contract: Extract<PathContract, {
+    readonly intent: "resolve";
+}>, signal?: AbortSignal): Promise<PathViews>;
 /** The identity of an ABSOLUTE spelling under the tree `bases` names — the target side's one prelude (family, namespace
  *  screen, identity) for a path a judge already holds (a canonical key, a hop, a lexical view). `undefined` when the
  *  spelling is not an absolute path of that tree. */
@@ -213,7 +268,9 @@ export declare function callTargetReadingOf(req: {
  * canonical, the leaf chain's hops), else the call's own lexical view — resolved against the call's `root` / `cwd` when it
  * carries either, else against `bare` (a host's direct call of a policy: the bases it declared). `undefined` = the call
  * names no path in this reading (or a spelling the throat refuses — no rule speaks about it); an `unreadable` answer =
- * the call names a path this reading cannot locate.
+ * the call names a path this reading cannot locate — or, in the allow reading, the target's resolved location is not in
+ * hand (no reading, no canonical view, or a view that was asked for and did not answer: `unread`). An allow by path is
+ * judged on where the target resolves; its spelling alone never admits it.
  */
 export declare function callTargetViewsOf(req: ToolCallLike & {
     readonly root?: string | undefined;