@wardby/cli 0.5.3 → 0.7.0

package/dist/core/schedule-start.d.ts

@@ -0,0 +1,12 @@
+import type { PrismaClient } from "#prisma";
+import { type ScheduleState } from "./cron.js";
+/**
+ * The `lastScheduledAt` to write with a schedule change: the database's
+ * clock when the change starts the schedule (see startsSchedule), nothing
+ * otherwise. The database's clock, not this process's, because the CLI and
+ * import can run on an operator's machine: a clock running ahead there would
+ * record a start after a window the scheduler has yet to fire, and skip it.
+ */
+export declare function scheduleStartFields(db: Pick<PrismaClient, "$queryRaw">, before: ScheduleState | null, after: ScheduleState): Promise<{
+    lastScheduledAt: Date;
+} | Record<string, never>>;

package/dist/core/schedule-start.js

@@ -0,0 +1,14 @@
+import { startsSchedule } from "./cron.js";
+/**
+ * The `lastScheduledAt` to write with a schedule change: the database's
+ * clock when the change starts the schedule (see startsSchedule), nothing
+ * otherwise. The database's clock, not this process's, because the CLI and
+ * import can run on an operator's machine: a clock running ahead there would
+ * record a start after a window the scheduler has yet to fire, and skip it.
+ */
+export async function scheduleStartFields(db, before, after) {
+    if (!startsSchedule(before, after))
+        return {};
+    const [{ now }] = await db.$queryRaw `SELECT now() AS now`;
+    return { lastScheduledAt: now };
+}

package/dist/core/secret-broker-config.d.ts

@@ -0,0 +1,39 @@
+import { z } from "zod";
+export declare const MIN_BROKERED_VALUE_LENGTH = 6;
+export declare const SecretBrokerConfigSchema: z.ZodObject<{
+    hosts: z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+    pathPrefixes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    placement: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"header">;
+        name: z.ZodString;
+        format: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"query">;
+        name: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"body">;
+        field: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"aws-sigv4">;
+        region: z.ZodString;
+        service: z.ZodString;
+    }, z.core.$strict>], "kind">;
+}, z.core.$strict>;
+export type SecretBrokerConfig = z.infer<typeof SecretBrokerConfigSchema>;
+export type SecretBrokerPlacement = SecretBrokerConfig["placement"];
+export declare function parseSecretBrokerConfig(input: unknown): SecretBrokerConfig;
+/**
+ * A fingerprint of one broker config (sha256 hex of its parsed JSON): an unbroker
+ * link carries the hash of the config it was minted for, so it can't remove a
+ * config that has changed since.
+ */
+export declare function brokerConfigHash(config: SecretBrokerConfig): string;
+export declare const SECRET_BROKER_CHANGED = "secret_broker_changed: brokering changed since this link was created; request a new link";
+export type SigV4Credentials = {
+    accessKeyId: string;
+    secretAccessKey: string;
+    sessionToken?: string;
+};
+export declare function parseSigV4Value(value: string): SigV4Credentials;
+/** Throws unless `value` can be brokered under `config` (and later scrubbed from responses). */
+export declare function assertBrokerableValue(config: SecretBrokerConfig, value: string): void;

package/dist/core/secret-broker-config.js

@@ -0,0 +1,112 @@
+/**
+ * A brokered secret's owner-set config: where its value may be sent and how it is
+ * placed. Validated on every write; the privileged host (sandbox/secret-broker.ts)
+ * trusts it at request time.
+ */
+import { createHash } from "node:crypto";
+import { z } from "zod";
+export const MIN_BROKERED_VALUE_LENGTH = 6;
+const FORBIDDEN_HEADERS = ["host", "connection", "transfer-encoding", "content-length", "upgrade", "proxy-connection"];
+const TOKEN = /^[!#$%&'*+.^_`|~0-9A-Za-z-]{1,128}$/;
+const HOSTNAME = /^(?=.{1,253}$)(?!-)[a-z0-9-]{1,63}(?:\.(?!-)[a-z0-9-]{1,63})+$/;
+const IPV4 = /^\d{1,3}(?:\.\d{1,3}){3}$/;
+/** False for a name a resolver could read as an IPv4 address ("127.1", "0x7f.0.0.1") or with a label ending in "-". */
+function isExactHostname(h) {
+    if (!HOSTNAME.test(h) || IPV4.test(h))
+        return false;
+    const labels = h.split(".");
+    const last = labels[labels.length - 1];
+    return !/^\d+$/.test(last) && !last.startsWith("0x") && !labels.some((l) => l.endsWith("-"));
+}
+const host = z
+    .string()
+    .transform((h) => h.toLowerCase())
+    .refine(isExactHostname, "hosts must be exact hostnames (no scheme, port, wildcard, or IP)");
+const pathPrefix = z
+    .string()
+    .max(512)
+    .startsWith("/")
+    .refine(
+// eslint-disable-next-line no-control-regex
+(p) => !/[?#\\\x00-\x1f\x7f]/.test(p) && !/%2f|%5c/i.test(p), "path prefixes must not contain ?, #, a backslash, control characters, or an encoded / or \\");
+const placement = z.discriminatedUnion("kind", [
+    z
+        .object({
+        kind: z.literal("header"),
+        name: z
+            .string()
+            .regex(TOKEN, "header name must be an HTTP token")
+            .refine((n) => !FORBIDDEN_HEADERS.includes(n.toLowerCase()), "that header cannot be set"),
+        format: z
+            .string()
+            .max(256)
+            .refine((f) => f.split("{value}").length === 2, 'format must contain "{value}" exactly once')
+            .refine((f) => !/[\r\n]/.test(f), "format must not contain line breaks"),
+    })
+        .strict(),
+    z.object({ kind: z.literal("query"), name: z.string().min(1).max(128) }).strict(),
+    z.object({ kind: z.literal("body"), field: z.string().min(1).max(128) }).strict(),
+    z
+        .object({
+        kind: z.literal("aws-sigv4"),
+        region: z.string().regex(/^[a-z0-9-]{1,32}$/),
+        service: z.string().regex(/^[a-z0-9-]{1,64}$/),
+    })
+        .strict(),
+]);
+export const SecretBrokerConfigSchema = z
+    .object({
+    hosts: z.array(host).min(1).max(20),
+    pathPrefixes: z.array(pathPrefix).max(20).optional(),
+    placement,
+})
+    .strict();
+export function parseSecretBrokerConfig(input) {
+    const parsed = SecretBrokerConfigSchema.safeParse(input);
+    if (!parsed.success) {
+        throw new Error(`secret_broker_config_invalid: ${parsed.error.issues.map((i) => i.message).join("; ")}`);
+    }
+    return parsed.data;
+}
+/**
+ * A fingerprint of one broker config (sha256 hex of its parsed JSON): an unbroker
+ * link carries the hash of the config it was minted for, so it can't remove a
+ * config that has changed since.
+ */
+export function brokerConfigHash(config) {
+    return createHash("sha256")
+        .update(JSON.stringify(parseSecretBrokerConfig(config)))
+        .digest("hex");
+}
+export const SECRET_BROKER_CHANGED = "secret_broker_changed: brokering changed since this link was created; request a new link";
+const SigV4ValueSchema = z
+    .object({
+    accessKeyId: z.string().min(1).max(256),
+    secretAccessKey: z.string().min(MIN_BROKERED_VALUE_LENGTH).max(1024),
+    sessionToken: z.string().min(MIN_BROKERED_VALUE_LENGTH).max(8192).optional(),
+})
+    .strict();
+export function parseSigV4Value(value) {
+    let json;
+    try {
+        json = JSON.parse(value);
+    }
+    catch {
+        throw new Error("secret_broker_value_invalid: an AWS SigV4 secret's value must be JSON {accessKeyId, secretAccessKey, sessionToken?}");
+    }
+    const parsed = SigV4ValueSchema.safeParse(json);
+    if (!parsed.success) {
+        throw new Error("secret_broker_value_invalid: an AWS SigV4 secret's value must be JSON {accessKeyId, secretAccessKey, sessionToken?}");
+    }
+    return parsed.data;
+}
+/** Throws unless `value` can be brokered under `config` (and later scrubbed from responses). */
+export function assertBrokerableValue(config, value) {
+    if (config.placement.kind === "aws-sigv4") {
+        parseSigV4Value(value);
+        return;
+    }
+    if (value.length < MIN_BROKERED_VALUE_LENGTH) {
+        throw new Error(`secret_broker_value_invalid: a brokered value must be at least ${MIN_BROKERED_VALUE_LENGTH} characters`);
+    }
+}

package/dist/core/secret-guard.d.ts

@@ -0,0 +1,46 @@
+import type { PrismaClient } from "#prisma";
+import { buildSecretsAccessor } from "./secrets.js";
+export interface NamedSecretValues {
+    name: string;
+    values: string[];
+}
+type SecretGuardCipher = Parameters<typeof buildSecretsAccessor>[1];
+type SecretGuardDb = Parameters<typeof buildSecretsAccessor>[2] & Pick<PrismaClient, "agentSecret">;
+/** Every secret attached to the agent (readable and brokered), with every form to look for. Rejects if any read fails. */
+export declare function loadAgentSecretValues(db: SecretGuardDb, cipher: SecretGuardCipher, agentId: string): Promise<NamedSecretValues[]>;
+/** The sorted, unique names of the secrets whose value occurs anywhere in `value`. */
+export declare function secretNamesIn(value: unknown, named: readonly NamedSecretValues[]): string[];
+/** The agent-visible refusal: names the secrets, never a value. At most 1000 characters. */
+export declare function secretInValueMessage(names: readonly string[]): string;
+export declare const SECRET_CHECK_UNAVAILABLE_MESSAGE = "secret_check_unavailable: not stored. The agent's secrets could not be read to check this value; try again.";
+export declare const WITHHELD_TEXT_NOTICE = "[withheld: this text could not be checked for secret values]";
+export declare class SecretInValueError extends Error {
+    readonly code = "secret_in_value";
+    readonly secretNames: string[];
+    constructor(names: readonly string[]);
+}
+export declare class SecretCheckUnavailableError extends Error {
+    readonly code = "secret_check_unavailable";
+    constructor();
+}
+/** `text` with every value of every named secret masked. */
+export declare function maskNamedSecrets(text: string, named: readonly NamedSecretValues[]): string;
+export interface SecretWriteGuard {
+    assertNoSecrets(agentId: string, value: unknown): Promise<void>;
+}
+/** Refuses a value holding an attached secret's value; fails closed when the secrets cannot be read. */
+export declare function createSecretWriteGuard(source: {
+    load(agentId: string): Promise<NamedSecretValues[]>;
+}): SecretWriteGuard;
+export declare function createDbSecretWriteGuard(db: SecretGuardDb, cipher: SecretGuardCipher): SecretWriteGuard;
+/**
+ * Built-in tools whose arguments become text on a host, so their arguments are masked before
+ * the call. Review host: repo_publish_review (summary, body, inline comment bodies), repo_comment
+ * (body). Jira: jira_comment and jira_edit_own_comment (body), jira_update_fields (labels,
+ * components, priority, custom fields), jira_create_issue (summary, description, labels,
+ * components, custom fields, fingerprint), jira_set_property (a stored value), jira_transition
+ * (toStatus, which Jira may echo in an error). Read tools and jira_link_issues (a link type name
+ * checked against an allowlist) are left out.
+ */
+export declare const POSTING_TOOL_NAMES: ReadonlySet<string>;
+export {};

package/dist/core/secret-guard.js

@@ -0,0 +1,104 @@
+import { MIN_REDACTABLE_SECRET_LENGTH, redactExactSecretValues, withEscapedForms } from "./secret-spans.js";
+import { buildSecretsAccessor } from "./secrets.js";
+import { consoleRedactionValues } from "../sandbox/secret-broker.js";
+/** Every secret attached to the agent (readable and brokered), with every form to look for. Rejects if any read fails. */
+export async function loadAgentSecretValues(db, cipher, agentId) {
+    const rows = await db.agentSecret.findMany({ where: { agentId }, select: { boundName: true } });
+    if (rows.length === 0)
+        return [];
+    const accessor = buildSecretsAccessor(agentId, cipher, db);
+    return Promise.all(rows.map(async ({ boundName }) => {
+        const entry = await accessor.resolve(boundName);
+        return { name: boundName, values: entry ? withEscapedForms(consoleRedactionValues(entry)) : [] };
+    }));
+}
+function textOf(value) {
+    return typeof value === "string" ? value : (JSON.stringify(value) ?? "");
+}
+/** The sorted, unique names of the secrets whose value occurs anywhere in `value`. */
+export function secretNamesIn(value, named) {
+    const text = textOf(value);
+    const hits = new Set();
+    for (const { name, values } of named) {
+        if (values.some((v) => v.length >= MIN_REDACTABLE_SECRET_LENGTH && text.includes(v)))
+            hits.add(name);
+    }
+    return [...hits].sort();
+}
+const MAX_MESSAGE_LENGTH = 1000;
+function refusal(names, listed) {
+    const shown = names.slice(0, listed).map((n) => JSON.stringify(n));
+    const more = names.length - listed;
+    const list = shown.join(", ") + (more > 0 ? `, and ${more} more` : "");
+    const noun = names.length > 1 ? "secrets" : "secret";
+    const first = JSON.stringify(names[0]);
+    return `secret_in_value: not stored. The value contains the value of ${noun} ${list} attached to this agent, and secret values are never stored. Store the secret's name instead and read it when you need it: secrets.get(${first}), or fetch(url, { secrets: [${first}] }) if it is brokered.`;
+}
+/** The agent-visible refusal: names the secrets, never a value. At most 1000 characters. */
+export function secretInValueMessage(names) {
+    let listed = names.length;
+    while (listed > 1 && refusal(names, listed).length > MAX_MESSAGE_LENGTH)
+        listed--;
+    return refusal(names, listed);
+}
+export const SECRET_CHECK_UNAVAILABLE_MESSAGE = "secret_check_unavailable: not stored. The agent's secrets could not be read to check this value; try again.";
+export const WITHHELD_TEXT_NOTICE = "[withheld: this text could not be checked for secret values]";
+export class SecretInValueError extends Error {
+    code = "secret_in_value";
+    secretNames;
+    constructor(names) {
+        super(secretInValueMessage(names));
+        this.name = "SecretInValueError";
+        this.secretNames = [...names];
+    }
+}
+export class SecretCheckUnavailableError extends Error {
+    code = "secret_check_unavailable";
+    constructor() {
+        super(SECRET_CHECK_UNAVAILABLE_MESSAGE);
+        this.name = "SecretCheckUnavailableError";
+    }
+}
+/** `text` with every value of every named secret masked. */
+export function maskNamedSecrets(text, named) {
+    return redactExactSecretValues(text, named.flatMap((n) => n.values));
+}
+/** Refuses a value holding an attached secret's value; fails closed when the secrets cannot be read. */
+export function createSecretWriteGuard(source) {
+    return {
+        async assertNoSecrets(agentId, value) {
+            let named;
+            try {
+                named = await source.load(agentId);
+            }
+            catch {
+                throw new SecretCheckUnavailableError();
+            }
+            const names = secretNamesIn(value, named);
+            if (names.length > 0)
+                throw new SecretInValueError(names);
+        },
+    };
+}
+export function createDbSecretWriteGuard(db, cipher) {
+    return createSecretWriteGuard({ load: (id) => loadAgentSecretValues(db, cipher, id) });
+}
+/**
+ * Built-in tools whose arguments become text on a host, so their arguments are masked before
+ * the call. Review host: repo_publish_review (summary, body, inline comment bodies), repo_comment
+ * (body). Jira: jira_comment and jira_edit_own_comment (body), jira_update_fields (labels,
+ * components, priority, custom fields), jira_create_issue (summary, description, labels,
+ * components, custom fields, fingerprint), jira_set_property (a stored value), jira_transition
+ * (toStatus, which Jira may echo in an error). Read tools and jira_link_issues (a link type name
+ * checked against an allowlist) are left out.
+ */
+export const POSTING_TOOL_NAMES = new Set([
+    "repo_publish_review",
+    "repo_comment",
+    "jira_comment",
+    "jira_edit_own_comment",
+    "jira_update_fields",
+    "jira_create_issue",
+    "jira_set_property",
+    "jira_transition",
+]);

package/dist/core/secret-guarded-stores.d.ts

@@ -0,0 +1,12 @@
+import type { Datastore } from "../providers/datastore/types.js";
+import type { AgentMemoryStore } from "../providers/memory/types.js";
+import { type SecretWriteGuard } from "./secret-guard.js";
+/**
+ * Datastore that refuses a key or value holding an attached secret's value. Shared
+ * writes are checked against `opts.writerAgentId`; without it the writer is
+ * unknown, so the write is refused (fail closed). `writerAgentId` is stripped
+ * before the inner store sees it.
+ */
+export declare function guardDatastore(inner: Datastore, guard: SecretWriteGuard): Datastore;
+/** Agent memory that refuses a key or content holding an attached secret's value. */
+export declare function guardAgentMemory(inner: AgentMemoryStore, guard: SecretWriteGuard): AgentMemoryStore;

package/dist/core/secret-guarded-stores.js

@@ -0,0 +1,41 @@
+import { SecretCheckUnavailableError } from "./secret-guard.js";
+/**
+ * Datastore that refuses a key or value holding an attached secret's value. Shared
+ * writes are checked against `opts.writerAgentId`; without it the writer is
+ * unknown, so the write is refused (fail closed). `writerAgentId` is stripped
+ * before the inner store sees it.
+ */
+export function guardDatastore(inner, guard) {
+    return {
+        get: (agentId, key) => inner.get(agentId, key),
+        async set(agentId, key, value, opts) {
+            await guard.assertNoSecrets(agentId, [key, value]);
+            return inner.set(agentId, key, value, opts);
+        },
+        delete: (agentId, key) => inner.delete(agentId, key),
+        list: (agentId, prefix) => inner.list(agentId, prefix),
+        getShared: (datastoreId, key) => inner.getShared(datastoreId, key),
+        async setShared(datastoreId, key, value, opts) {
+            const { writerAgentId, ...rest } = opts ?? {};
+            if (!writerAgentId)
+                throw new SecretCheckUnavailableError();
+            await guard.assertNoSecrets(writerAgentId, [key, value]);
+            return inner.setShared(datastoreId, key, value, rest);
+        },
+        deleteShared: (datastoreId, key) => inner.deleteShared(datastoreId, key),
+        listShared: (datastoreId, prefix) => inner.listShared(datastoreId, prefix),
+    };
+}
+/** Agent memory that refuses a key or content holding an attached secret's value. */
+export function guardAgentMemory(inner, guard) {
+    return {
+        get: (agentId, key) => inner.get(agentId, key),
+        async set(agentId, key, content) {
+            await guard.assertNoSecrets(agentId, [key, content]);
+            return inner.set(agentId, key, content);
+        },
+        list: (agentId) => inner.list(agentId),
+        search: (agentId, query, limit) => inner.search(agentId, query, limit),
+        delete: (agentId, key) => inner.delete(agentId, key),
+    };
+}

package/dist/core/secret-spans.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The one redactor for exact secret values: every site that masks values it knows (the sandbox
+ * console bridge, the native gateway's log, the native worker's stderr, a brokered response, a
+ * coding worker's debug trace, git output) goes through these functions. It masks the union of
+ * every occurrence of every value, overlapping occurrences included, so no character of any
+ * occurrence survives however occurrences overlap (a value such as `abcabcabc` in `abc` x 5).
+ *
+ * No imports: every worker image (native sandbox, coding driver, Claude coding worker) ships this
+ * file next to its callers.
+ */
+/** Below this length a "secret" is too likely to coincidentally match ordinary log text — not worth the false-positive risk of redacting it. */
+export declare const MIN_REDACTABLE_SECRET_LENGTH = 6;
+/** The marker that stands in for each masked span, unless a site passes its own. */
+export declare const REDACTED_MARKER = "[REDACTED]";
+export interface RedactOptions {
+    /** Replaces each merged span (default REDACTED_MARKER). */
+    marker?: string;
+    /** Values shorter than this are left alone (default MIN_REDACTABLE_SECRET_LENGTH; an empty value never matches). */
+    minLength?: number;
+}
+/**
+ * Each value plus its JSON-escaped forms, deduplicated: escaped once (`JSON.stringify(v).slice(1, -1)`)
+ * and twice. A value holding a quote, a backslash, a newline or a control character appears escaped
+ * once inside JSON text (a console line, a log line), and twice when that JSON text is itself
+ * logged as a string (`console.log(JSON.stringify({ key: value }))` through the console bridge, or
+ * a logger field that already holds JSON). The one expansion every redaction list goes through.
+ */
+export declare function withEscapedForms(values: Iterable<string>): string[];
+/**
+ * The merged, sorted [start, end) spans of `text` covered by any occurrence of any value, overlapping
+ * occurrences included (the search advances by one character, not by the value's length), so a
+ * self-overlapping value is covered wherever any occurrence of it lies. Values shorter than
+ * `minLength` are ignored. Overlapping or adjacent spans merge.
+ */
+export declare function secretSpans(text: string, values: Iterable<string>, minLength?: number): Array<[number, number]>;
+/** `spans` sorted and merged, overlapping or adjacent ones joined. */
+export declare function mergeSpans(spans: ReadonlyArray<readonly [number, number]>): Array<[number, number]>;
+/** `text` with each of the merged, sorted `spans` replaced by one `marker`. */
+export declare function maskSpans(text: string, spans: ReadonlyArray<readonly [number, number]>, marker?: string): string;
+/**
+ * `text` with the union of every occurrence of each value (secretSpans) replaced by the marker;
+ * values shorter than the minimum length are left alone.
+ */
+export declare function redactExactSecretValues(text: string, values: Iterable<string>, options?: RedactOptions): string;
+/**
+ * Whether `text` equals, contains, or is contained in any of `values`, under the same minimum
+ * length as redactExactSecretValues. For a short field that is sent whole or not at all (a native
+ * gateway error's cause code), where redacting part of it would still leave part of a value.
+ */
+export declare function overlapsSecretValue(text: string, values: Iterable<string>): boolean;

package/dist/core/secret-spans.js

@@ -0,0 +1,94 @@
+/**
+ * The one redactor for exact secret values: every site that masks values it knows (the sandbox
+ * console bridge, the native gateway's log, the native worker's stderr, a brokered response, a
+ * coding worker's debug trace, git output) goes through these functions. It masks the union of
+ * every occurrence of every value, overlapping occurrences included, so no character of any
+ * occurrence survives however occurrences overlap (a value such as `abcabcabc` in `abc` x 5).
+ *
+ * No imports: every worker image (native sandbox, coding driver, Claude coding worker) ships this
+ * file next to its callers.
+ */
+/** Below this length a "secret" is too likely to coincidentally match ordinary log text — not worth the false-positive risk of redacting it. */
+export const MIN_REDACTABLE_SECRET_LENGTH = 6;
+/** The marker that stands in for each masked span, unless a site passes its own. */
+export const REDACTED_MARKER = "[REDACTED]";
+/** `text` as it appears inside a JSON string literal (JSON.stringify without the quotes). */
+const jsonEscaped = (text) => JSON.stringify(text).slice(1, -1);
+/**
+ * Each value plus its JSON-escaped forms, deduplicated: escaped once (`JSON.stringify(v).slice(1, -1)`)
+ * and twice. A value holding a quote, a backslash, a newline or a control character appears escaped
+ * once inside JSON text (a console line, a log line), and twice when that JSON text is itself
+ * logged as a string (`console.log(JSON.stringify({ key: value }))` through the console bridge, or
+ * a logger field that already holds JSON). The one expansion every redaction list goes through.
+ */
+export function withEscapedForms(values) {
+    const out = new Set();
+    for (const value of values) {
+        const once = jsonEscaped(value);
+        out.add(value);
+        out.add(once);
+        out.add(jsonEscaped(once));
+    }
+    return [...out];
+}
+/**
+ * The merged, sorted [start, end) spans of `text` covered by any occurrence of any value, overlapping
+ * occurrences included (the search advances by one character, not by the value's length), so a
+ * self-overlapping value is covered wherever any occurrence of it lies. Values shorter than
+ * `minLength` are ignored. Overlapping or adjacent spans merge.
+ */
+export function secretSpans(text, values, minLength = MIN_REDACTABLE_SECRET_LENGTH) {
+    const spans = [];
+    const shortest = Math.max(1, minLength);
+    for (const value of new Set(values)) {
+        if (value.length < shortest)
+            continue;
+        for (let at = text.indexOf(value); at >= 0; at = text.indexOf(value, at + 1))
+            spans.push([at, at + value.length]);
+    }
+    return mergeSpans(spans);
+}
+/** `spans` sorted and merged, overlapping or adjacent ones joined. */
+export function mergeSpans(spans) {
+    const sorted = spans.filter(([start, end]) => end > start).sort((a, b) => a[0] - b[0] || a[1] - b[1]);
+    const merged = [];
+    for (const [start, end] of sorted) {
+        const last = merged[merged.length - 1];
+        if (last && start <= last[1])
+            last[1] = Math.max(last[1], end);
+        else
+            merged.push([start, end]);
+    }
+    return merged;
+}
+/** `text` with each of the merged, sorted `spans` replaced by one `marker`. */
+export function maskSpans(text, spans, marker = REDACTED_MARKER) {
+    let out = "";
+    let from = 0;
+    for (const [start, end] of spans) {
+        out += `${text.slice(from, start)}${marker}`;
+        from = end;
+    }
+    return out + text.slice(from);
+}
+/**
+ * `text` with the union of every occurrence of each value (secretSpans) replaced by the marker;
+ * values shorter than the minimum length are left alone.
+ */
+export function redactExactSecretValues(text, values, options = {}) {
+    return maskSpans(text, secretSpans(text, values, options.minLength), options.marker);
+}
+/**
+ * Whether `text` equals, contains, or is contained in any of `values`, under the same minimum
+ * length as redactExactSecretValues. For a short field that is sent whole or not at all (a native
+ * gateway error's cause code), where redacting part of it would still leave part of a value.
+ */
+export function overlapsSecretValue(text, values) {
+    for (const value of values) {
+        if (value.length < MIN_REDACTABLE_SECRET_LENGTH)
+            continue;
+        if (text.includes(value) || value.includes(text))
+            return true;
+    }
+    return false;
+}

package/dist/core/secrets.d.ts

@@ -6,19 +6,52 @@
  * always resolve a name within one owner's (or, at get-time, one agent's)
  * scope, never globally.
  */
-import type { PrismaClient, Secret } from "#prisma";
+import { type PrismaClient, type Secret } from "#prisma";
 import type { SecretCipher } from "../providers/secrets/types.js";
-export type SecretMetadata = Pick<Secret, "id" | "name" | "keyId" | "ownerId" | "createdAt" | "updatedAt">;
+import { type SecretBrokerConfig } from "./secret-broker-config.js";
+export type BrokerChangeVia = "mcp" | "browser";
+export type SecretMetadata = Pick<Secret, "id" | "name" | "keyId" | "ownerId" | "createdAt" | "updatedAt"> & {
+    broker: SecretBrokerConfig | null;
+};
+export interface SecretEntry {
+    value: string;
+    broker: SecretBrokerConfig | null;
+}
 export interface SecretsAccessor {
+    /** Readable secrets only: a brokered secret throws `secret_brokered`. */
     get(name: string): Promise<string | undefined>;
+    /** Host-internal: value and broker config, brokered or not. Never exposed to tool code. */
+    resolve?(name: string): Promise<SecretEntry | undefined>;
 }
 /**
  * Encrypts and stores a secret value. Upserts on (ownerId, name) — calling
  * this again for a name the owner already has rotates its value in place
  * (same id) rather than failing on the unique constraint. The plaintext is
- * never logged or returned.
+ * never logged or returned. With `options.broker`, the config is validated
+ * against the value, saved, and audited in the same transaction.
+ */
+export declare function createSecret(name: string, value: string, ownerId: string, cipher: SecretCipher, db: PrismaClient, options?: {
+    broker?: SecretBrokerConfig;
+    via?: BrokerChangeVia;
+}): Promise<Secret>;
+/**
+ * Sets, changes, or (broker: null) removes a secret's broker config, with one audit
+ * row per actual change. `expectedBrokerHash` (brokerConfigHash of the config the
+ * caller confirmed) makes the change conditional, checked inside the transaction:
+ * if the secret is no longer brokered with exactly that config, it throws
+ * secret_broker_changed and changes nothing.
  */
-export declare function createSecret(name: string, value: string, ownerId: string, cipher: SecretCipher, db: PrismaClient): Promise<Secret>;
+export declare function setSecretBroker(db: PrismaClient, cipher: SecretCipher, input: {
+    ownerId: string;
+    name: string;
+    broker: SecretBrokerConfig | null;
+    actorId: string;
+    via: BrokerChangeVia;
+    expectedBrokerHash?: string;
+}): Promise<{
+    before: SecretBrokerConfig | null;
+    after: SecretBrokerConfig | null;
+}>;
 /** Names/metadata only — never a value or ciphertext. */
 export declare function listSecrets(ownerId: string, db: PrismaClient): Promise<SecretMetadata[]>;
 /** Attaches one of the owner's own secrets (by canonical name) to an agent,
@@ -43,6 +76,8 @@ export declare function deleteSecret(secretId: string, db: PrismaClient): Promis
  * binding written before that rule, left behind by make_owner, or on an
  * owner-less agent behaves exactly like an unattached name, so one owner's
  * secret never reaches another owner's agent (A2/S2-2, R2-1).
+ *
+ * A brokered secret's `get` throws `secret_brokered`; only the privileged host's `resolve` sees its value.
  */
 export declare function buildSecretsAccessor(agentId: string, cipher: SecretCipher, db: Pick<PrismaClient, "agentSecret"> & Partial<Pick<PrismaClient, "$queryRaw">>): SecretsAccessor;
 /**