@securecoms/agent-bridge 0.26.4 → 0.26.6

package/dist/bridge-agent.d.ts

@@ -1,4 +1,5 @@
 import { MlsGroupKeyProvider } from "@agentvault/connect-sdk-ts";
+import type { HarnessReport } from "./harness-report.js";
 import type { MemoryContextResult } from "@agentvault/connect-mls-store";
 /**
  * M6 (ADR-0013 Decision H): what the sweep observed about one channel.
@@ -58,9 +59,15 @@ export type BridgeToolGrant = {
  * Tool grants (architect ruling, 2026-10-02): until channel-grant persistence
  * lands, the ONLY non-empty grant list is OWNER_DM_DEFAULT_READ_GRANTS
  * (`current_time` + `web_search`, read mode), and only on a DM whose sender is
- * the pinned structural owner (or a relayed voice turn whose speaker is). Every
+ * that DM's pinned human counterpart AND server-marked `is_agent_owner` (or a
+ * relayed voice turn whose speaker is). The pin is per channel, so the
+ * owner distinction rests on the server's flag: see authorizationFor's LIMIT
+ * note. Every
  * other audience, an unpinned or anomalous owner, and the kill switch
  * `SECURECOMS_OWNER_DM_DEFAULT_GRANTS` (anything but unset/`on`) get `[]`.
+ * PR R adds exactly one more non-empty list, ROOM_DEFAULT_READ_GRANTS
+ * (`current_time` only), for an INTERNAL room's same-org human sender; see
+ * authorizationFor.
  * SEC-06 is LIVE for these two tools: docs/security/sec-06-runtime-bounds-audit.md.
  */
 /**
@@ -71,17 +78,42 @@ export type BridgeToolGrant = {
  * and `http_request` are deliberately absent.
  */
 export declare const OWNER_DM_DEFAULT_READ_GRANTS: readonly BridgeToolGrant[];
+/**
+ * PR R (spec §7A.1a; controller ruling 2026-10-05, audit r1: current_time
+ * only). Granted only in a room classified INTERNAL from the server roster
+ * (every row, leaf rows included, in the agent owner's org), to a same-org
+ * human sender, while the roster is as fresh as the agent's MLS epoch, while
+ * a declared per-tool consumer is attached (audit C-B1), and while
+ * SECURECOMS_ROOM_DEFAULT_GRANTS is on (plan OQ-3). Frozen; the runtime intersects
+ * it with ROOM_SAFE_READ_TOOLS (turn-loop.ts).
+ */
+export declare const ROOM_DEFAULT_READ_GRANTS: readonly BridgeToolGrant[];
 /**
  * Kill switch for OWNER_DM_DEFAULT_READ_GRANTS, read once at BridgeAgent
  * construction (daemon startup). Unset or exactly `on` keeps the grants;
  * any other value (`off`, `0`, `false`, empty) sends `[]` on every turn.
  */
 export declare function ownerDmDefaultGrantsEnabled(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Kill switch for ROOM_DEFAULT_READ_GRANTS (plan OQ-3, RULED), read once at
+ * BridgeAgent construction exactly like ownerDmDefaultGrantsEnabled. Unset or
+ * exactly `on` keeps the room default; any other value sends `[]` on every
+ * room turn. It never touches the owner DM.
+ */
+export declare function roomDefaultGrantsEnabled(env?: NodeJS.ProcessEnv): boolean;
 export interface BridgeAuthorization {
     readonly version: 1;
     readonly audience: AgentAudience;
     readonly sender_membership: "active" | "unknown";
     readonly tool_grants: readonly BridgeToolGrant[];
+    /**
+     * Audit r2 R2-T1 (plan OQ-6 ruling): "owner" ONLY on authorizationFor's
+     * ownerRelayed branch: the channel's server-marked relay sent a turn whose
+     * relayed speaker is the channel's pinned owner. Set by the daemon, never
+     * copied from message text. A harness connector honours a grant on
+     * audience owner_dm or on this mark, nothing else.
+     */
+    readonly relay_speaker?: "owner";
 }
 export interface BridgeMessage {
     channel_id: string;
@@ -513,6 +545,15 @@ export declare class SendForbiddenError extends Error {
     readonly channelId: string;
     constructor(channelId: string);
 }
+/**
+ * Audit M-B1 (controller ruling 2026-10-05): a reply to a room-granted turn
+ * would be sealed at an epoch the room was not classified at, and the room is
+ * not internal there. Dropped. A SendForbiddenError, so both transports treat
+ * it as terminal (send_forbidden: the runtime acks, nothing redelivers).
+ */
+export declare class RoomClassChangedSendError extends SendForbiddenError {
+    constructor(channelId: string);
+}
 /**
  * Stranded sender (spec 2026-09-26 §7.4): the backend refused a publish with
  * 409 `mls.group_superseded`: the envelope was sealed under a group that is no
@@ -892,6 +933,21 @@ export declare class BridgeAgent {
     private readonly selfHealSweepEnabled;
     /** Read once at startup; see ownerDmDefaultGrantsEnabled. */
     private readonly ownerDmDefaultGrants;
+    /** Read once at startup; see roomDefaultGrantsEnabled. */
+    private readonly roomDefaultGrants;
+    /**
+     * Audit M-B4: DM channels whose roster was epoch-fresh at THIS ingest
+     * cycle's refresh (refreshRostersForCycle). Cleared at each cycle's start.
+     */
+    private readonly ownerDmCycleFresh;
+    /**
+     * Audit M-B1: room-granted turns, keyed by the inbound message id, with the
+     * channel, MLS group and epoch the room was classified at (review I-1: an
+     * epoch NUMBER alone repeats across channels and across a supersede). A
+     * reply to one is sealed only there, or re-classified once
+     * (publishBodyForReply). Forgotten at the runtime's ack.
+     */
+    private readonly roomGrantEpochs;
     /** Task 12: proactive sweep cadence (in addition to the once-at-boot fire). */
     private static readonly SELF_HEAL_SWEEP_INTERVAL_MS;
     /**
@@ -1505,6 +1561,25 @@ export declare class BridgeAgent {
      * there so a retry can resend the exact bytes).
      */
     private publishBody;
+    /**
+     * Audit M-B1 (controller ruling): a reply to a room-granted turn is sealed
+     * only at the epoch the room was classified at. On a move, the room is
+     * re-classified ONCE from a roster fetched at the new epoch: still internal,
+     * the reply is sealed at that epoch; anything else, it is dropped. The check
+     * throws before an envelope is built, so nothing is stored or posted.
+     *
+     * `inReplyTo` is the STORED intent's inbound id, not the send's options, so
+     * the redelivery replay (replayReplyIntents, which has no in_reply_to in its
+     * options) is checked the same as a live send.
+     */
+    private publishBodyForReply;
+    /**
+     * Re-read the room at the agent's current group and epoch; true only if it
+     * is still internal there. Review I-1: the entry must come from THIS re-read
+     * (a fail-soft refresh leaves an older entry whose epoch label can repeat
+     * across a supersede), and the group must not move around the reads.
+     */
+    private reclassifyForReply;
     private enforceBodyRateFloor;
     /** Bookkeeping after a CONFIRMED publish of `body` under `id`. */
     private afterPublish;
@@ -1943,6 +2018,19 @@ export declare class BridgeAgent {
     private enclavesToCover;
     /** A live roster for a channel, or undefined if missing OR expired past the TTL. */
     private freshRoster;
+    /** The whole cache entry when fresh, else undefined (TTL; the epoch is checked by the caller). */
+    private freshRosterEntry;
+    /** The agent's held MLS group id for a channel; null when none (fail closed). */
+    private heldGroupFor;
+    /**
+     * Review I-1 + fix round 2: the agent's held (group, epoch) for a channel.
+     * The group is read on BOTH sides of the epoch read, so the epoch provably
+     * belongs to it (a supersede in between installs a new group whose epoch
+     * counter restarts); a group that moved, or none held, is null (fail closed).
+     */
+    private heldPosition;
+    /** The agent's own MLS epoch for a channel; null when no group is held (fail closed). */
+    private heldEpochFor;
     /**
      * Resolve one channel's roster (members + display names + is-agent) from the
      * GET members endpoint into the roster cache. Called AT MOST ONCE per ingest
@@ -1951,6 +2039,15 @@ export declare class BridgeAgent {
      * attribution must NEVER block or drop a message.
      */
     private refreshChannelRoster;
+    /**
+     * S-1 (roster) + §7A.5 + audit M-B4: once per ingest cycle, per distinct
+     * channel, re-read the roster when the TTL lapsed OR the epoch moved since
+     * the fetch, then record which DMs are epoch-fresh for the rest of this
+     * cycle. Fail-soft inside refreshChannelRoster (never blocks ingest).
+     */
+    private refreshRostersForCycle;
+    /** Classify one inbound turn at the agent's CURRENT epoch for its channel. */
+    private authorizeTurn;
     /**
      * Classify the sender only from server-authenticated channel/roster data.
      * Missing or stale metadata is UNKNOWN with zero grants, never a permissive
@@ -1959,14 +2056,32 @@ export declare class BridgeAgent {
      *
      * Grants (architect ruling 2026-10-02): OWNER_DM_DEFAULT_READ_GRANTS only when
      * the kill switch is on, the channel is a DM, and EITHER
-     *   (a) audience is owner_dm AND the sender is the pinned structural owner
-     *       (`channelOwner`, never "anomalous") — a lying `is_agent_owner` flag
-     *       alone gets nothing; OR
+     *   (a) audience is owner_dm AND the sender is the channel's pinned DM
+     *       counterpart (`channelOwner`, never "anomalous"). A server-marked
+     *       `is_agent_owner` on a member who is NOT the DM's single human
+     *       counterpart gets nothing; on the counterpart it is trusted (see
+     *       LIMIT below); OR
      *   (b) the sender is this channel's server-marked relay (`is_relay`) and the
      *       relayed `speaker_identity_id` (passed by the caller only for relay
      *       turns) is that same pinned owner, whose roster row is the agent's
      *       owner. A speaker claim from any non-relay sender gets nothing.
+     * Both need the roster fetched at `heldEpoch` (the agent's current MLS
+     * epoch for the channel), or the DM marked epoch-fresh at this ingest
+     * cycle's refresh (audit M-B4).
+     * PR R: ROOM_DEFAULT_READ_GRANTS only when the room kill switch is on, a
+     * per-tool consumer is attached, the roster was fetched at `heldEpoch`
+     * (no cycle carve-out), the room is INTERNAL (roomIsCrossOrg === false
+     * over every row, leaf rows included) and the audience is team_room.
      * Everything else gets the frozen empty list.
+     *
+     *   LIMIT (harness gate review H2, 2026-10-05): "pinned structural owner"
+     *   is PER CHANNEL. resolveAndPinOwner pins the single human counterpart of
+     *   ANY DM, so in a DM with member Bob, Bob is that channel's pin. What
+     *   separates Bob from the real owner is only the server's `is_agent_owner`
+     *   flag (connect_channels.py: counterpart user == agent's creator). A
+     *   backend that sets that flag wrongly gives Bob the grants, and a harness
+     *   connector turns grants into its full toolset. Binding the owner identity
+     *   once, outside server control, is an open design follow-up.
      */
     private authorizationFor;
     /**
@@ -1985,6 +2100,13 @@ export declare class BridgeAgent {
      *                            startup: `on` = default grants enabled
      *   meta_fresh / roster_fresh whether the channel meta / roster caches were
      *                            fresh (either stale forces audience=unknown)
+     *   room_class               the room's class from the server roster (`na`
+     *                            for a DM): internal | cross_org | unknown
+     *   epoch_fresh              the roster was fetched at the agent's current
+     *                            MLS epoch for the channel
+     *   room_kill_switch         SECURECOMS_ROOM_DEFAULT_GRANTS as read at startup
+     *   per_tool_consumer        a consumer that declared per-tool grant
+     *                            enforcement is attached
      */
     private logAuthzDecision;
     /**
@@ -2298,6 +2420,31 @@ export declare class BridgeAgent {
      * ws-server.ts right after prior.cleanup() in the eviction path.
      */
     noteSessionEvicted(): void;
+    /** Harness tool gate H4: latest connector self-report (see harness-report.ts). */
+    private harness;
+    /**
+     * Record a connector's harness report (from its /v1/ws hello). WARN once
+     * each time the attached harness turns to an inactive veto: such a harness
+     * refuses every turn without a tool grant, so its rooms go quiet.
+     */
+    recordHarnessReport(report: HarnessReport): void;
+    /** Forget `report` when the connector that sent it disconnects. A report
+     *  from a newer connector (a different object) is kept. */
+    clearHarnessReport(report: HarnessReport): void;
+    /** The latest harness report, or null (GET /v1/status). */
+    harnessReport(): HarnessReport | null;
+    /**
+     * Audit C-B1: the attached /v1/ws consumer that declared per-tool grant
+     * enforcement (its hello carried "per_tool_grants" and no harness report),
+     * or null. authorizationFor issues a room grant only while one is attached
+     * (Task R2); every delivery path also strips room grants for any other
+     * consumer (consumer-grants.ts). The token is the socket's session object.
+     */
+    private perToolConsumer;
+    notePerToolConsumer(token: object): void;
+    /** Forget `token` when its socket closes; a newer consumer's token is kept. */
+    clearPerToolConsumer(token: object): void;
+    perToolConsumerAttached(): boolean;
     health(): {
         status: "ok";
         identity_id: string;
@@ -2369,6 +2516,12 @@ export declare class BridgeAgent {
          *  agent_sessions stays >=1 means two connectors are flapping the same
          *  identity (split-brain), not one stable harness. */
         evictions: number;
+        /** Harness tool gate H4: is the attached harness's tool veto active?
+         *  null when no connector is attached with a report. false means that
+         *  harness refuses every turn without a tool grant. Only this boolean is
+         *  on the unauthenticated /healthz; name and version are on the
+         *  authenticated GET /v1/status. */
+        harness_tool_veto_active: boolean | null;
         uptime_s: number;
         version: string;
         /** M6: is the self-heal sweep running at all? It is the SOLE writer of the

package/dist/consumer-grants.d.ts

@@ -0,0 +1,22 @@
+import type { BridgeMessage } from "./bridge-agent.js";
+/**
+ * The /v1/ws hello feature a consumer sends to declare per-tool grant
+ * enforcement. The runtime exports the same value (connect-agent-runtime
+ * data-plane.ts PER_TOOL_GRANTS_FEATURE); the two packages share no
+ * dependency, so ws-server.test.ts pins them equal and drives the bridge with
+ * the runtime's own hello frame.
+ */
+export declare const PER_TOOL_GRANTS_FEATURE = "per_tool_grants";
+/**
+ * `m` unchanged for a per-tool consumer; otherwise `m` with any room grant
+ * stripped to []. The owner's own turns, which a harness has always been
+ * granted for, pass unchanged: the owner's DM, and the owner-spoken relayed
+ * voice turn the daemon marks relay_speaker "owner" (audit r2 R2-T1; the SAME
+ * rule the connectors apply, Task R2a). Everything else with grants is
+ * stripped: an allowlist fails closed on any new granted audience.
+ *
+ * Never mutates `m`: the buffer and in-flight records keep the original, so a
+ * later per-tool consumer still receives it. The stripped copy keeps every
+ * other field (audience, relay_speaker) as is.
+ */
+export declare function withConsumerGrants(m: BridgeMessage, perToolConsumer: boolean): BridgeMessage;

package/dist/harness-report.d.ts

@@ -0,0 +1,14 @@
+/**
+ * A connector's self-report, carried on its `/v1/ws` hello (harness tool
+ * gate, fix round 1 H4): which harness is attached and whether its tool veto
+ * is active. Untrusted input from a loopback client: every field is closed to
+ * a known set or a bounded version token, so only booleans/versions reach
+ * /healthz, GET /v1/status and the service log.
+ */
+export interface HarnessReport {
+    readonly name: "hermes" | "openclaw" | "other";
+    readonly version: string | null;
+    /** "inactive": the harness refuses every turn without a tool grant. */
+    readonly tool_veto: "active" | "inactive" | "unknown";
+}
+export declare function parseHarnessReport(raw: unknown): HarnessReport | null;

package/dist/http-server.d.ts

@@ -16,6 +16,16 @@ export declare function writeSse(res: {
     writableEnded?: boolean;
     write: (s: string) => boolean;
 }, msgs: BridgeMessage[], onWriteError?: (error: unknown) => void): BridgeMessage[];
+/**
+ * Audit C-B1 / r2 R2-T2: deliver one SSE batch. An SSE consumer never declares
+ * per-tool enforcement, so the WRITTEN copies have room grants stripped; the
+ * unwritten tail is requeued as the ORIGINAL messages, never a stripped copy,
+ * so a later per-tool consumer still receives the grant.
+ */
+export declare function deliverSseBatch(res: Parameters<typeof writeSse>[0], batch: BridgeMessage[], agent: {
+    ackRuntimeMessages(ids: string[]): void;
+    requeueFront(msgs: BridgeMessage[]): void;
+}, onWriteError?: (error: unknown) => void): void;
 /**
  * Once-per-connection write-failure reporter (#335). A throwing `res.write`
  * means the socket is dying — teardown follows via the request's `'close'` —