@agentvault/claude-bridge 0.3.4 → 0.4.0

package/dist/approve-cli.d.ts

@@ -0,0 +1,28 @@
+export declare class ApproveArmError extends Error {
+}
+/** A drained local approval: the host operator approved arming `roomId` under
+ *  the one-time `requestId`. Both are consumed together by ArmingState.approveLocal. */
+export interface DrainedApproval {
+    requestId: string;
+    roomId: string;
+}
+/** Reject ids that could escape the approvals dir / inject into arming state
+ *  (defensive — backend sends uuid4, but these values hit the filesystem). */
+export declare function sanitizeRequestId(requestId: string): string;
+/** Reject room-ids that aren't plain tokens (marker content is read back and
+ *  compared against the pending arm request's room). */
+export declare function sanitizeRoomId(roomId: string): string;
+/** Write the local-approval marker (run on the host with data-dir access). The
+ *  marker file is NAMED by the request-id and CONTAINS the approved room-id, so
+ *  the host consent binds a specific room (the room can't be redirected by later
+ *  network input — finding F1). */
+export declare function writeApproval(dataDir: string, requestId: string, roomId: string): void;
+/** One-shot: return the pending approvals (request-id + approved room-id) and
+ *  remove their markers. A marker whose content isn't a valid room-id is drained
+ *  but skipped (returned with no room ⇒ approveLocal will fail-closed). */
+export declare function drainApprovals(dataDir: string): DrainedApproval[];
+/** If argv is the approve-arm subcommand, perform it and return true (caller should exit).
+ *  Usage: `av-bridge approve-arm <request-id> <room-id>`. Both are shown to the
+ *  operator in the bridge's arm-request log line and the web arm sheet. */
+export declare function maybeRunApproveArmSubcommand(argv: string[], dataDir: string): boolean;
+//# sourceMappingURL=approve-cli.d.ts.map

package/dist/arming.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Slice 2 Plan C — per-room arming map + pending arm-requests + one-time
+ * local approval.
+ *
+ * PURE in-memory data structure: no I/O, no WS, no fs. Later tasks wire this
+ * to the channel (T11) and the local-approval CLI (T9) and the gate (T10).
+ */
+export declare class ArmingState {
+    private armed;
+    private pending;
+    private consumed;
+    /**
+     * Replace the armed set. Use ONLY for the launch-env seed (AV_ARM_ROOM), which
+     * is itself a host-local action and is therefore allowed to arm.
+     *
+     * Do NOT use this for the backend connect `arming_snapshot`: that snapshot
+     * reflects owner *intent* (set at web-request time, before any local approval),
+     * so arming from it would let a web-session compromise arm a worker on reconnect
+     * without host access — defeating the 2-of-2 local-approval model. The channel
+     * snapshot path uses `reconcileDisarm` (disarm-only) instead.
+     */
+    applySnapshot(roomIds: string[]): void;
+    /**
+     * Disarm-only reconciliation from the backend connect snapshot. Disarms any
+     * currently-armed room whose intent is no longer armed (i.e. NOT in
+     * `intendedArmed`) — so a disarm issued while the bridge was offline still takes
+     * effect on reconnect — but NEVER arms a room. Arming stays exclusively behind a
+     * local `approve-arm`. Returns the rooms that were disarmed. In-memory arming
+     * survives a WS reconnect, so a genuinely-approved arm is unaffected here; only a
+     * full process restart (which clears this state) requires re-approval on the host.
+     */
+    reconcileDisarm(intendedArmed: string[]): string[];
+    isArmed(roomId: string): boolean;
+    /** Live disarm — flip a room off (a cooperating fail-safe). */
+    disarm(roomId: string): void;
+    /**
+     * Record a pending arm request; does NOT arm until approveLocal.
+     *
+     * The (request-id → room) binding is IMMUTABLE and ONE-SHOT: a request-id
+     * already consumed is never re-registered, and a second event that tries to
+     * point an existing request-id at a DIFFERENT room is rejected. Without this a
+     * compromised backend / WS-MITM could redirect an in-flight approval to another
+     * room after the operator saw the first one (confused-deputy, finding F1), and
+     * a lingering marker could be replayed against a re-registered id (F2).
+     */
+    registerArmRequest(roomId: string, requestId: string): void;
+    /**
+     * Approve a pending request locally (one-time). The caller MUST name the room
+     * being approved (from the host-written marker); it must match the room the
+     * request originally targeted, or the approval is rejected (fail-closed). This
+     * is what makes the host consent bind a SPECIFIC room rather than "whatever room
+     * the untrusted backend currently maps to this opaque token" (F1). Returns true
+     * only if it armed the room.
+     */
+    approveLocal(requestId: string, roomId: string): boolean;
+    armedRooms(): string[];
+}
+//# sourceMappingURL=arming.d.ts.map

package/dist/audit-report.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Slice 2 Plan B — fire-and-forget self-report of an armed-room tool decision
+ * to the backend's hash-chained audit trail (POST /api/v1/audit/entries).
+ *
+ * UNTRUSTED self-report: the bridge runs on the owner's machine, so this is a
+ * record/signal, not a guarantee. It must NEVER block or fail a turn — the POST
+ * is fired and forgotten, all errors swallowed.
+ */
+export interface ToolAuditReport {
+    apiUrl: string;
+    deviceJwt: string | null;
+    agentId: string | null;
+    roomId: string;
+    tool: string;
+    decision: "allow" | "deny";
+    reason?: string;
+}
+export declare function reportToolAudit(opts: ToolAuditReport): void;
+//# sourceMappingURL=audit-report.d.ts.map

package/dist/bridge.d.ts

@@ -1,8 +1,21 @@
+import { ArmingState } from "./arming.js";
 export interface RoomMessage {
     roomId: string;
     senderName: string;
     plaintext: string;
 }
+/** Slice 2 Plan C arming events (SecureChannel re-emits these from the backend). */
+export interface ArmRequested {
+    roomId: string;
+    requestId: string;
+    workspaceLabel?: string | null;
+}
+export interface DisarmEvent {
+    roomId: string;
+}
+export interface ArmingSnapshot {
+    roomIds: string[];
+}
 /** Metadata SecureChannel attaches to a 1:1 `message` event. `roomId` is set only
  *  when the `message` actually originated in a room (handled by room_message), so
  *  its ABSENCE is how we identify a true owner↔agent 1:1 DM. */
@@ -20,8 +33,17 @@ export interface RoomChannel {
     on(ev: "message", cb: (text: string, metadata: MessageMeta) => void): unknown;
     on(ev: "room_hushed", cb: (e: RoomHushed) => void): unknown;
     on(ev: "error", cb: (err: unknown) => void): unknown;
+    on(ev: "ready", cb: () => void): unknown;
+    on(ev: "arm_requested", cb: (e: ArmRequested) => void): unknown;
+    on(ev: "disarm", cb: (e: DisarmEvent) => void): unknown;
+    on(ev: "arming_snapshot", cb: (e: ArmingSnapshot) => void): unknown;
     sendToRoom(roomId: string, text: string): Promise<void>;
     send(text: string): Promise<void>;
+    /** Optional so legacy/test fakes without arming support don't break wiring. */
+    sendWorkerHeartbeat?(h: {
+        workerCapable: boolean;
+        armedRooms: string[];
+    }): void;
 }
 /**
  * #392 cooperative quiet: tracks per-room hush windows so the native agent holds
@@ -40,6 +62,7 @@ export interface RoomSession {
      *  sending plain assistant text when the model never calls the say tool (#416). */
     push(text: string, reply?: (text: string) => Promise<void>, opts?: {
         autoReplyOnText?: boolean;
+        armed?: () => boolean;
     }): void;
 }
 /** Where a reply should go: a room (sendToRoom) or a 1:1 DM (send). */
@@ -103,10 +126,33 @@ export interface LifecycleChannel {
  */
 export declare function attachLifecycle(channel: LifecycleChannel, opts?: {
     log?: (msg: string) => void;
-    onTerminal?: (reason: string) => void;
+    onTerminal?: (reason: string, o: {
+        restart: boolean;
+    }) => void;
 }): void;
+/**
+ * Slice 2 Plan C (Task 11) — one drain of the local-approval marker dir.
+ *
+ * Local approval is the ONLY thing that actually arms a room: a marker under
+ * <dataDir>/arm-approvals/<request-id> is written by `av-bridge approve-arm`
+ * (host filesystem access required). Each drained id is matched against a
+ * pending arm request; a match arms the room and fires `onArmed`.
+ *
+ * Defensive per the T9 review advisory: a bad/locked/junk marker (or a planted
+ * subdir that makes readdir/rm throw) must NOT crash the poll loop, and a
+ * drained id that matches no pending request is logged rather than silently
+ * dropped (it usually means a mis-timed or duplicate approval).
+ */
+export declare function pollApprovalsOnce(arming: ArmingState, dataDir: string, onArmed: () => void, log?: (msg: string) => void): void;
 export declare function wireBridge(channel: RoomChannel, session: RoomSession, target: ActiveTarget, opts?: {
     roomFilter?: string;
+    armRoom?: boolean;
     log?: (msg: string) => void;
-}): void;
+    /** Slice 2 Plan C (T11): worker capability + local-approval marker dir. */
+    worker?: boolean;
+    workspaceDir?: string;
+    dataDir?: string;
+    /** Override the approval poll interval (ms) — for tests. */
+    approvalPollMs?: number;
+}): ArmingState;
 //# sourceMappingURL=bridge.d.ts.map

package/dist/config.d.ts

@@ -1,4 +1,10 @@
+export declare function hasPersistedCreds(dataDir: string): boolean;
+export declare function slugify(name: string): string;
 export type DataDirSource = "explicit" | "per-agent" | "legacy";
+export declare function resolveDataDir(env: NodeJS.ProcessEnv): {
+    dataDir: string;
+    source: DataDirSource;
+};
 export interface BridgeConfig {
     inviteToken: string;
     dataDir: string;
@@ -11,6 +17,9 @@ export interface BridgeConfig {
     worker: boolean;
     workspaceDir?: string;
     permissionMode: "auto" | "acceptEdits" | "bypassPermissions";
+    /** Slice 2: arm the pinned room (roomFilter) for worker tools on room turns.
+     *  Off by default. Valid only with worker + roomFilter + workspaceDir. */
+    armRoom: boolean;
 }
 export declare function loadConfig(env: NodeJS.ProcessEnv, argv?: string[]): BridgeConfig;
 //# sourceMappingURL=config.d.ts.map