@securecoms/agent-bridge 0.34.0 → 0.36.0

package/dist/grants/mcp-section.d.ts

@@ -0,0 +1,94 @@
+/**
+ * MCP client Phase 1, Task 14 (spec §12.2, §13a; M-D ruling and its remainder at 3c203f8bb): the signed `mcp` section.
+ *
+ *   "mcp": { "servers": { "<server_id>": {
+ *     "vendor": "<catalog key>", "url": "<canonical https URL>",
+ *     "auth": { "mode": "oauth", "issuer": "<https URL>", "client": "securecoms_cimd" }
+ *           | { "mode": "oauth", "issuer": "<https URL>", "client": "customer", "client_id": "<string>" }
+ *           | { "mode": "key" },
+ *     "tools": { "<tool>": { "sha256": "<hex64>", "class": "read" } } } },
+ *     "removed"?: [ "<server_id>", ... ] | "*" }
+ *
+ * `removed` (C-NEW-1 architect ruling, 2026-10-30): the owner's explicit, per-save removal. Absence of a server from
+ * `servers` NEVER deletes its credential; only a server named here (or `"*"`, remove-all) does. Optional; absent is `[]`.
+ * An array holds 1 to 8 distinct valid, non-reserved server ids, none of them also a key of `servers`; `"*"` is valid
+ * only with `servers` empty. Anything else makes the section malformed (non-deleting).
+ *
+ * EXACT keys everywhere and NO PATH anywhere (M-D): the host derives every credential path from the server id, so a
+ * `token_file`, `key_file` or `client_secret_file` key (or any other key) makes the section malformed. The client-kind
+ * key is `client`, with the #1315 §3.1 names; `securecoms_installed` (a Google desktop client) is not an MCP client and
+ * is refused. A bad section returns null; the CALLER keeps the rest of the manifest (T-15), which departs on purpose from
+ * the all-or-nothing rule of the other sections.
+ *
+ * Pure. Comparison with the bridge's catalog copy (vendor present, url equals `readOnlyUrl`, issuer equals the row) is a
+ * per-server verdict (`mcpServerAcceptable`), never a section parse failure: spec §6.5 lists those as server `refused`.
+ */
+import type { McpCatalog, McpCatalogRow } from "./mcp-catalog.js";
+export declare const MCP_MAX_SERVERS = 8;
+export declare const MCP_MAX_TOOLS_PER_SERVER = 64;
+export declare const MCP_MAX_SIGNED_TOOLS = 160;
+/** C-NEW-1: at most this many server ids in one signed `removed` list. */
+export declare const MCP_MAX_REMOVED = 8;
+/** OQ-5 ruling: the SecureComs Client ID Metadata Document. A `securecoms_cimd` client's client_id is this URL, derived on the host. */
+export declare const SECURECOMS_CIMD_CLIENT_ID = "https://app.securecoms.ai/oauth/securecoms-agent-client.json";
+export declare const MCP_SERVER_ID: RegExp;
+export declare const MCP_TOOL_NAME: RegExp;
+/**
+ * PR-B1 audit M-1: names a JS object treats specially. A signed `__proto__` would set the map's prototype instead of a
+ * key; `constructor` and `prototype` would collide with inherited members. Refused as tool names and server ids (the
+ * section is malformed), and every map is built with no prototype as well.
+ */
+export declare const MCP_RESERVED_NAMES: ReadonlySet<string>;
+export type McpClientKind = "securecoms_cimd" | "customer";
+export type SignedMcpAuth = {
+    readonly mode: "oauth";
+    readonly issuer: string;
+    readonly client: "securecoms_cimd";
+} | {
+    readonly mode: "oauth";
+    readonly issuer: string;
+    readonly client: "customer";
+    readonly client_id: string;
+} | {
+    readonly mode: "key";
+};
+export interface SignedMcpTool {
+    readonly sha256: string;
+    readonly class: "read";
+}
+export interface SignedMcpServer {
+    readonly vendor: string;
+    readonly url: string;
+    readonly auth: SignedMcpAuth;
+    readonly tools: Readonly<Record<string, SignedMcpTool>>;
+}
+/** The signed removal: server ids the owner removed in this save, or `"*"` (remove-all). `[]` when the key is absent. */
+export type SignedMcpRemoved = readonly string[] | "*";
+export interface SignedMcp {
+    readonly servers: Readonly<Record<string, SignedMcpServer>>;
+    /** C-NEW-1: the ONLY source of a credential deletion on top `ok`. Never inferred from absence. */
+    readonly removed: SignedMcpRemoved;
+}
+/** The exact key sets per auth shape. Anything else, path keys included, is refused (M-D). */
+export declare const MCP_AUTH_KEYS: Readonly<{
+    oauth_securecoms_cimd: readonly string[];
+    oauth_customer: readonly string[];
+    key: readonly string[];
+}>;
+/** The signed `mcp` value, or null when it is not exactly the §13a shape (the section is then `malformed`, non-deleting). */
+export declare function parseMcp(v: unknown): SignedMcp | null;
+/**
+ * Per-server catalog verdict: the vendor is in the bridge's catalog, the signed url is the row's read-only URL exactly,
+ * and (oauth) the signed issuer is the row's issuer (audit r1 C-1). The row on success, else null (server `refused`).
+ */
+export declare function mcpServerCatalogRow(s: SignedMcpServer, catalog: McpCatalog): McpCatalogRow | null;
+/** `mcp:<server_id>/<tool>` split, or null for any other shape. */
+export declare function parseMcpGrant(name: string): {
+    serverId: string;
+    tool: string;
+} | null;
+/**
+ * Spec §12.2 code ceiling for one owner_dm grant string: the server and tool are signed in the `mcp` section, the
+ * server passes the catalog verdict, and the tool is on the catalog row's read list. team_room accepts none (caller).
+ */
+export declare function mcpGrantWithinCeiling(name: string, mcp: SignedMcp | null, catalog: McpCatalog): boolean;

package/dist/grants/owner-turn.d.ts

@@ -2,6 +2,8 @@ import type { AgentVaultEnvelope } from "@agentvault/connect-core";
 import { type OwnerGrantPin } from "./pin.js";
 export declare const OWNER_VERIFY_STATES: readonly ["ok", "bad_signature", "malformed", "unknown_algo", "no_signature", "not_owner_dm_leaves", "wrong_dm_channel", "replay", "verify_error"];
 export type OwnerVerifyFailure = Exclude<(typeof OWNER_VERIFY_STATES)[number], "ok">;
+/** Phase 0 Task 5: what the is_dm === true branch read from the DM's leaf set. */
+export type OwnerDmRelay = "none" | "signed" | "unsigned";
 export type OwnerTurnVerdict = {
     readonly kind: "unchecked";
 } | {
@@ -11,6 +13,8 @@ export type OwnerTurnVerdict = {
         readonly groupId: string;
         readonly epoch: number;
     };
+    readonly relay?: OwnerDmRelay;
+    readonly relayLeaf: boolean;
 } | {
     readonly kind: "constants_only";
     readonly replay: {
@@ -18,6 +22,7 @@ export type OwnerTurnVerdict = {
         readonly groupId: string;
         readonly epoch: number;
     };
+    readonly relay?: OwnerDmRelay;
 } | {
     readonly kind: "failed";
     readonly reason: OwnerVerifyFailure;
@@ -50,3 +55,38 @@ export declare function classifyOwnerDmLeaves(leaves: readonly {
     relayIdentityId?: string;
     isServerRelay: (identityId: string) => boolean;
 }): OwnerDmLeafClass;
+/**
+ * MCP Phase 1 Task 15 (H-3, OQ-2 ruling / ADR D): relay-free means the owner DM's local leaf set holds ONLY the pinned
+ * owner (any number of devices: leaf credentials encode identity, not device) and the agent, and both are present.
+ * A signed relay leaf, which classifyOwnerDmLeaves admits as "ok", is NOT relay-free. Fails closed on an empty tree,
+ * a non-basic leaf, or a leaf with no identity.
+ */
+export declare function ownerDmLeavesRelayFree(leaves: readonly {
+    basic: boolean;
+    identity: string | null;
+}[], ids: {
+    ownerIdentityId: string;
+    agentIdentityId: string;
+}): boolean;
+/**
+ * Phase 0 spec round 2 H-4: relayLeaf is derived from the verdict's Phase 0 `relay` field, at the one place
+ * verifyOwnerTurn builds a verified verdict. Only exactly "none" is relay-free; "signed", "unsigned", any unknown value
+ * and an absent value (classification did not run) all count as a relay (fail closed).
+ */
+export declare function relayLeafFromPhase0Relay(relay: unknown): boolean;
+/**
+ * Phase 0 Task 5 (spec §3.4): the verdict's `relay`, from the SAME leaf set and leaf class the is_dm === true branch
+ * just computed. Called only after the `foreign` return. "none" exactly when the set is relay-free (only the pinned
+ * owner, any number of devices, and the agent, both present: ownerDmLeavesRelayFree), so relayLeaf is unchanged by
+ * construction. "signed" only when a leaf really carries the manifest's signed relay identity (never from the
+ * manifest alone). Anything else (an ok class that is neither, e.g. no agent leaf) is undefined: not classified, which
+ * every reader treats as relay present.
+ */
+export declare function ownerDmRelayOf(leafClass: Exclude<OwnerDmLeafClass, "foreign">, leaves: readonly {
+    basic: boolean;
+    identity: string | null;
+}[], ids: {
+    ownerIdentityId: string;
+    agentIdentityId: string;
+    relayIdentityId?: string;
+}): OwnerDmRelay | undefined;

package/dist/grants/tool-status.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Tool status, Phase 0 (spec §3.2, §3.3, §3.5; plan Task 7): the pure core of the owner-DM last-turn record.
+ *
+ * ADVISORY ONLY. Nothing reads the record to decide a grant: it is a content-free summary of a decision
+ * authorizationFor already made, posted for the owner's agent page. Enums, booleans, one 15-minute bucket `at`,
+ * one counter, and built-in tool names from the fixed allowlist below. Never a channel id, sender id, MCP tool name,
+ * argument or message data.
+ */
+import type { GrantSource, WithheldWhy } from "./effective.js";
+import type { OwnerTurnVerdict } from "./owner-turn.js";
+/** Spec §3.2: current_time plus the seven MANIFEST_KNOWN_TOOLS.owner_dm names. Never an `mcp:` name. */
+export declare const TOOL_STATUS_ALLOWLIST: readonly ["current_time", "web_search", "web_extract", "fetch_url", "http_request", "sql_query", "weather_forecast", "currency_convert"];
+export declare const CAUSES: readonly ["owner_dm_unavailable", "manifest_switch_off", "unexpected_member_in_dm", "owner_turn_failed", "agent_state_error", "dm_channel_mismatch", "dm_not_linked", "unsigned_relay_in_dm", "manifest_not_bound", "no_runtime_consumer"];
+export type Cause = (typeof CAUSES)[number];
+export declare const SUBS: readonly ["kill_switch", "pin", "sender_not_owner", "stale"];
+export type Sub = (typeof SUBS)[number];
+export type RecordRelay = "none" | "signed" | "unsigned" | "unknown";
+/**
+ * Architect ruling M-2 (A1 §8): the operator sees owner-DM activity at most as a 15-minute UTC bucket. `at` is the
+ * bucket start, and the sender posts only just after a bucket boundary (tool-status-sender.ts).
+ */
+export declare const TOOL_STATUS_BUCKET_MS = 900000;
+/** The start of the 15-minute UTC bucket holding `ms`, as `YYYY-MM-DDTHH:MMZ`. */
+export declare function bucketStartAt(ms: number): string;
+/** The instant the bucket that starts at `at` closes. */
+export declare function bucketEndMs(at: string): number;
+export interface OwnerDmTurnRecord {
+    /**
+     * Architect ruling M-2: the start of the 15-minute UTC bucket (bridge clock) in which the tuple last changed,
+     * `YYYY-MM-DDTHH:MMZ` with a minute of 00, 15, 30 or 45 (bucketStartAt). Not in the compared tuple.
+     */
+    readonly at: string;
+    /** toolGrantCounter: the manifest counter the turn ran under, null before any manifest. */
+    readonly counter: number | null;
+    readonly source: GrantSource;
+    readonly cause?: Cause;
+    readonly sub?: Sub;
+    readonly relay: RecordRelay;
+    readonly issued: readonly string[];
+    readonly withheld: readonly {
+        readonly tool: string;
+        readonly why: WithheldWhy;
+    }[];
+    readonly mcp_issued: number;
+}
+export interface CauseInput {
+    readonly killSwitchOff: boolean;
+    readonly manifestSwitchOff: boolean;
+    readonly pinMissingOrAnomalous: boolean;
+    /** Computed only from a PRESENT roster entry (OQ-5): a TTL-expired roster is `stale`, never this. */
+    readonly senderNotOwner: boolean;
+    /** `!ownerDmFresh || freshRosterEntry(channelId) === undefined` (OQ-5). */
+    readonly stale: boolean;
+    /** Never `unchecked` (correction 9: the recorded set is the grant-pin owner, so the verdict was checked). */
+    readonly verdict: Exclude<OwnerTurnVerdict, {
+        kind: "unchecked";
+    }>;
+    readonly manifestPresent: boolean;
+    readonly signedDmChannel: string | undefined;
+    readonly channelId: string;
+    readonly boundNow: boolean;
+    readonly consumerAttached: boolean;
+}
+export interface CauseResult {
+    readonly source: GrantSource;
+    readonly cause?: Cause;
+    readonly sub?: Sub;
+}
+/**
+ * Spec §3.3, first match wins, in the order 1, 2, 3, 3a, 4, 5, 6, 6a, 7, 8, 9, 10, 11. `sub` only for
+ * owner_dm_unavailable. `cause` omitted exactly when `source === "manifest"`. Source mirrors authorizationFor.
+ * Returns null for a failed `replay` verdict (not recorded) and never throws (round 1 M-3: it runs inside the
+ * authorization path); any unexpected input is null too.
+ */
+export declare function ownerDmCause(i: CauseInput): CauseResult | null;
+/** Spec §3.5 change tuple {source, cause, sub, relay, issued, withheld, mcp_issued, counter}; `at` excluded (round 2 M-8), `sub` included (OQ-4). */
+export declare function sameTuple(a: OwnerDmTurnRecord | null | undefined, b: OwnerDmTurnRecord | null | undefined): boolean;
+/** Sorted, unique, allowlist only. Drops every `mcp:` name and any tool outside the fixed allowlist. */
+export declare function sanitizeIssued(names: readonly string[]): string[];

package/dist/http-server.d.ts

@@ -28,6 +28,7 @@ export declare function deliverSseBatch(res: Parameters<typeof writeSse>[0], bat
     requeueFront(msgs: BridgeMessage[]): void;
     harnessGrantsWithheld(): boolean;
     signedSearchProvider(): SearchProvider | undefined;
+    r3Hold(): boolean;
 }, onWriteError?: (error: unknown) => void): void;
 /**
  * Once-per-connection write-failure reporter (#335). A throwing `res.write`