@securecoms/agent-bridge 0.10.0 → 0.11.1

package/dist/bridge-agent.d.ts

@@ -574,6 +574,34 @@ export declare class BridgeAgent {
      * DEVICE never held a leaf can 403 on the signal call. That's harmless and
      * must not abort the sweep for every other channel.
      */
+    /**
+     * One best-effort device-level KeyPackage rotation attempt.
+     *
+     * `publishKeyPackage` is a cheap no-op skip unless the SERVER says the held
+     * KeyPackage is expired, so calling it every cycle costs one read and rotates at
+     * most once per TTL. The catch logs once and continues: it MUST NOT rethrow, MUST
+     * NOT abort the sweep, and MUST NOT retry inside the cycle. A KeyPackage that
+     * cannot be rotated this cycle is retried on the next interval, and the sweep's
+     * per-channel repair work is independent of it.
+     */
+    /**
+     * Tri-state: "is this device STILL serving a server-expired KeyPackage at the end
+     * of the cycle that just tried to fix it?"
+     *
+     * `false` is the only healthy value, and it requires a POSITIVE, current proof of
+     * non-expiry. `null` is unknown and reads exactly like `true` in `degraded`, so a
+     * daemon that cannot prove itself un-expired stops reporting healthy. That is the
+     * OPPOSITE direction to the rotation guard, which never rotates on unknown.
+     * Conflating the two directions recreates the lie this change removes.
+     *
+     * Initialised `null` and written only by `selfHealSweep`, so a sweep-off daemon
+     * reads `null` and therefore degraded.
+     */
+    private keypackageExpired;
+    /** Resolve the flag from the SAME two inputs the guard uses, with every unknown
+     * mapped to `null`. Never throws: a failure to measure is itself unknown. */
+    private resolveKeypackageExpired;
+    private rotateDeviceKeyPackage;
     private selfHealSweep;
     /**
      * Per-channel send-floor check. No-op on allow; throws RateLimitedError on a
@@ -617,6 +645,7 @@ export declare class BridgeAgent {
         status: "sent";
     }>;
     private sendDeps;
+    private receiveDeps;
     sendAttachment(channelId: string, filePath: string, caption?: string): Promise<{
         message_id: string;
         status: "sent";
@@ -630,8 +659,11 @@ export declare class BridgeAgent {
     /**
      * List channels in one enclave (default: the daemon's own home enclave).
      * Task 3: called per-*known* enclave by refreshChannelMeta so a
-     * cross-enclave room's is_dm gets resolved — see the scope caveat there
-     * (same-tenant only; a cross-tenant enclave 404s under the agent's bearer).
+     * cross-enclave room's is_dm gets resolved. ⚠️ The old "same-tenant only; a
+     * cross-tenant enclave 404s under the agent's bearer" caveat here is refuted
+     * — see the CROSS-TENANT LISTING note on enclavesToCover. This route admits
+     * any enclave the caller holds a live membership row in, partner tenants
+     * included.
      */
     listChannels(enclaveId?: string): Promise<Array<{
         channel_id: string;
@@ -666,12 +698,16 @@ export declare class BridgeAgent {
      * room is never listed under the home-enclave-only call, so its is_dm never
      * resolves and the @mention filter fails open for that room.
      *
-     * Each enclave is wrapped in its own try/catch (scope caveat — audit
-     * H2/tenant): list_channels_in_enclave filters on tenant_id, so a
-     * same-tenant enclave the agent has learned about resolves fine, but a
-     * cross-TENANT federated-partner enclave 404s under this agent's bearer;
-     * that enclave's channels are left unresolved (fail open) without aborting
-     * the other enclaves in the set.
+     * Each enclave is wrapped in its own try/catch so one enclave's listing
+     * failure leaves only that enclave's channels unresolved (fail open) without
+     * aborting the other enclaves in the set.
+     *
+     * ⚠️ The old scope caveat here (audit H2/tenant) said
+     * `list_channels_in_enclave` filters on tenant_id and 404s a cross-TENANT
+     * federated-partner enclave. That is refuted — see the CROSS-TENANT LISTING
+     * note on enclavesToCover. A partner enclave with a live membership row
+     * resolves like any other, so the try/catch now covers transport errors,
+     * 5xx, and genuine non-member 404s only.
      */
     private refreshChannelMeta;
     /** Cache for the server-side enclave enumeration (see enclavesToCover). */
@@ -686,12 +722,20 @@ export declare class BridgeAgent {
      * failure right after a restart would read as "never succeeded" and slip
      * through the expected-gap branch — weaker than the old abort-on-failure).
      * A failure of a member of this set is a REGRESSION and degrades health; a
-     * failure of a never-succeeded enclave (partner: tenant-scoped 404, permanent
-     * pending backend authz) is an EXPECTED gap — reported, not degrading, or
-     * every federated agent would peg degraded forever. */
+     * failure of a never-succeeded enclave is reported but does not degrade.
+     *
+     * ⚠️ The old justification for that asymmetry named a partner enclave's
+     * "tenant-scoped 404, permanent pending backend authz" as the expected gap.
+     * That premise is refuted — see the CROSS-TENANT LISTING note on
+     * enclavesToCover; a partner enclave with a live membership row lists fine.
+     * The asymmetry is kept on its remaining merit: an enclave this process has
+     * never listed may simply be one this agent holds no live membership in, and
+     * pegging health degraded forever on that is noise, not signal. */
     private readonly enclaveListEverSucceeded;
     /** Warn-once-per-failure-streak, keyed by enclave id (cleared on success):
-     * a permanently-404ing partner enclave must not log 1440 lines a day. */
+     * a persistently-failing enclave must not log 1440 lines a day. (The old
+     * wording named "a permanently-404ing partner enclave" — refuted, see the
+     * CROSS-TENANT LISTING note on enclavesToCover.) */
     private readonly enclaveListWarned;
     private static readonly ENCLAVE_ENUM_TTL_MS;
     private enclaveEnumWarned;
@@ -719,11 +763,35 @@ export declare class BridgeAgent {
      * membership changes are picked up within one TTL, which matches the sweep
      * cadence this exists to serve.
      *
-     * ⚠️ Residual gap, stated: the enumeration RETURNS cross-tenant partner
-     * enclaves, but `list_channels_in_enclave` is tenant-scoped and 404s them
-     * under this agent's bearer — so a partner enclave in this set still yields
-     * no channels. Callers must treat a per-enclave listing failure as skip-one,
-     * never abort-all. Closing that needs backend authz work, not daemon work.
+     * ── CROSS-TENANT LISTING: the canonical statement for this file ──────────
+     *
+     * ⚠️ CORRECTED 2026-08-21 (#280 spec F6). This block, and five other comments
+     * in this file, used to state that `list_channels_in_enclave` is tenant-
+     * scoped and 404s a cross-tenant partner enclave under this agent's bearer,
+     * leaving a partner enclave in this set with no channels. That has been FALSE
+     * since #187 (`d7cc685a`, 2026-07-31). Verified by opening the code:
+     *
+     *  - `list_channels_in_enclave` calls `_resolve_enclave_membership(...,
+     *    host_only=False)` (backend/app/api/v1/connect_channels.py:897-900).
+     *  - `host_only=False` OMITS the `ConnectEnclave.tenant_id == auth.tenant_id`
+     *    predicate and runs the membership query under `bypass_rls`, so the
+     *    host-owned enclave row is visible to a partner session (same file
+     *    :519-520, :531-543). The gate is membership, not tenancy.
+     *  - The channel query it then runs (same file :902-919) reads
+     *    `connect_channels` joined to `connect_channel_members`, and BOTH tables
+     *    are among the eight the schema deliberately leaves without RLS for
+     *    having no `tenant_id` column (alembic 0001_connect_initial_schema.py:
+     *    750-755, :778-780). No policy filters those rows by tenant.
+     *
+     * So a partner-tenant agent holding a live `ConnectEnclaveMember` row
+     * (`removed_at IS NULL`) gets 200 with that enclave's real channels. There is
+     * no partner-enclave listing gap left to close, and no backend authz work
+     * pending for it.
+     *
+     * What DOES still reach a per-enclave listing failure: a transport error, a
+     * 5xx, or a genuine 404 for an enclave this agent holds no live membership
+     * in. Those are real outages, so the skip-one, never-abort-all rule stands on
+     * its own merit — it just no longer has a standing partner-enclave case.
      */
     private enclavesToCover;
     /** A live roster for a channel, or undefined if missing OR expired past the TTL. */
@@ -851,6 +919,12 @@ export declare class BridgeAgent {
         rate_limited: number;
         /** Cumulative inbound rows acked-and-dropped because they were provably past-epoch undecryptable (forward-secrecy secret gone). */
         permanently_skipped: number;
+        /** SDK-6: cumulative rows ack-drained via QUARANTINE, distinct from the
+         *  same-group past-epoch permanently_skipped drain. */
+        quarantine_drained: number;
+        /** SDK-6: cumulative rows ack-drained because their group_id is RETIRED for
+         *  the channel (superseded fork-loser traffic). */
+        retired_drained: number;
         /** Track 5: cumulative artifact_share messages where download/decrypt/digest failed (fail-soft — acked, no redeliver). */
         failed_attachments: number;
         /** 2026-07-03 latency triage: delivery pings received on the WS stream.
@@ -879,6 +953,12 @@ export declare class BridgeAgent {
         /** M6: channels whose divergence verdict is definitively true. Excludes
          *  unresolvable/failed probes, which are counted as neither. */
         diverged_channels: number;
+        /** Tri-state. `false` means the last sweep PROVED the published KeyPackage is
+         *  still live. `true` means it is server-expired and the rotation did not heal
+         *  it. `null` means unknown — no sweep yet, no held kp id, or the expiry could
+         *  not be resolved. `null` folds into `degraded` exactly like `true`: healthy
+         *  requires a positive, current proof of non-expiry. */
+        keypackage_expired: boolean | null;
         /** A2 (dr-evil F3, decision D-3): the truthful roll-up — true when any
          *  channel is definitively diverged OR the observations cannot be trusted
          *  (stale/absent). Additive: `status` stays "ok" until the flip ships as
@@ -891,8 +971,9 @@ export declare class BridgeAgent {
         /** C1: enclaves whose channel listing failed on the newest sweep. Non-empty
          * means partial coverage — those enclaves' channels were NOT probed. A
          * PREVIOUSLY-SUCCEEDING (or home) entry also flips `degraded`; a
-         * never-succeeded entry (partner enclave, tenant-scoped 404) is reported
-         * here without degrading. */
+         * never-succeeded entry is reported here without degrading. (The old
+         * wording gave "partner enclave, tenant-scoped 404" as the never-succeeded
+         * case — refuted, see the CROSS-TENANT LISTING note on enclavesToCover.) */
         sweep_enclaves_failed: string[];
         /** Optional memory-adapter counters (e.g. Hermes provider); present only when the active provider exposes stats(). */
         hermes_no_session?: number;
@@ -940,9 +1021,19 @@ export declare class BridgeAgent {
         filteredRoomMessages: number;
         rateLimitedSends: number;
         permanentlySkipped: number;
+        /** SDK-6: cumulative rows ack-drained via QUARANTINE, distinct from the
+         *  same-group past-epoch permanentlySkipped drain. */
+        quarantineDrained: number;
+        /** SDK-6: cumulative rows ack-drained because their group_id is RETIRED for
+         *  the channel (superseded fork-loser traffic). */
+        retiredDrained: number;
         welcomeRequestsSent: number;
         /** Track 5: cumulative artifact_share failures (download/decrypt/digest). */
         failedAttachments: number;
+        /** SDK-6: bridge build id, so a /v1/metrics reading captured across a daemon
+         * restart can be attributed to a version — counters are process-lifetime
+         * and zero on restart (spec §5.5). */
+        build: string;
     };
     close(): Promise<void>;
 }