@kubun/plugin-p2p 0.11.0 → 0.12.0

package/lib/groups/store-received-grant.js

@@ -1,4 +1,5 @@
-import { verifyToken } from '@kokuin/token';
+import { normalizeDID, verifyToken } from '@kokuin/token';
+import { MAX_CAP_TTL_SECONDS } from '@kubun/store-delegation';
 /**
  * Verify a received capability grant and, when it is addressed to this device,
  * store it as a held row so the engine's auto-attach can reuse it on later
@@ -6,8 +7,9 @@ import { verifyToken } from '@kokuin/token';
  *
  * Returns `true` when the held row was inserted or materially changed (LWW
  * upsert with a newer hlc and at least one differing content field). Returns
- * `false` when no row change occurred — verification failure, audience
- * mismatch, missing required claims, LWW lost against an existing row, or an
+ * `false` when no row change occurred — verification failure, a subject that
+ * is not the signer, audience mismatch, missing required claims, a lifetime
+ * above `MAX_CAP_TTL_SECONDS`, LWW lost against an existing row, or an
  * idempotent re-broadcast with identical content. Never throws on a forged or
  * malformed token — it is skipped like an unverifiable broadcast entry.
  *
@@ -28,16 +30,56 @@ import { verifyToken } from '@kokuin/token';
         });
         return false;
     }
-    // Only store grants addressed to this device.
-    if (payload.aud !== selfDID) {
+    // Sender-bound: `sub` is the grantor the held row is filed under, and a
+    // signature only proves `iss`. Without this any co-member could file a row
+    // attributed to another peer — including one colliding with that peer's own
+    // `jti`, which is what makes the grantor-scoped revocation lookups
+    // unanswerable.
+    //
+    // The consequence is that **sub-delegation is not supported over this path**:
+    // a re-delegated grant, whose `sub` is the original grantor and whose `iss`
+    // is the re-delegator, is dropped here. Nothing mints one today
+    // (`grantWriteCapability` signs only for `identity.id`), but `checkCapability`
+    // does verify multi-hop chains, so enforcement would accept what this refuses
+    // to store. Supporting it means carrying and verifying the parent chain at
+    // this point, not relaxing the predicate — see
+    // `docs/agents/plans/backlog/sub-delegation-over-broadcast.md`.
+    if (normalizeDID(payload.sub) !== normalizeDID(payload.iss)) {
+        logger?.warn('received grant subject is not its signer, skipping', {
+            groupID
+        });
+        return false;
+    }
+    // Only store grants addressed to this device. Both sides are folded: a
+    // `did:peer:4` audience reaches us in long form on first contact and short
+    // form thereafter, and a raw compare would silently discard our own grant.
+    if (normalizeDID(payload.aud) !== normalizeDID(selfDID)) {
         return false;
     }
-    if (payload.jti == null || payload.exp == null) {
-        logger?.warn('received grant token missing jti/exp, skipping', {
+    // `iat` joins the guard because the TTL bound below is unanswerable without
+    // it, and an unanswerable bound is the hole this check exists to close. Both
+    // producers (`grantWriteCapability`, `KubunClient.mintWriteGrant`) stamp it.
+    if (payload.jti == null || payload.exp == null || payload.iat == null) {
+        logger?.warn('received grant token missing jti/exp/iat, skipping', {
             groupID
         });
         return false;
     }
+    // A capability accepted here can be revoked, and a co-member retains that
+    // revocation only for `MAX_CAP_TTL_SECONDS` past the revocation's own `iat` —
+    // it holds no copy of the capability to read an expiry from. Accepting a
+    // longer-lived grant would let it outlive its revocation and start being
+    // honored again. Skipped like any other unusable broadcast, not thrown: the
+    // sender is not necessarily this device's resolver.
+    if (payload.exp - payload.iat > MAX_CAP_TTL_SECONDS) {
+        logger?.warn('received grant lifetime exceeds the maximum, skipping', {
+            groupID,
+            jti: payload.jti,
+            ttl: payload.exp - payload.iat,
+            max: MAX_CAP_TTL_SECONDS
+        });
+        return false;
+    }
     const resource = typeof payload.res === 'string' ? payload.res : JSON.stringify(payload.res);
     const act = typeof payload.act === 'string' ? payload.act : JSON.stringify(payload.act);
     const changed = await delegationStore.addDelegationToken({
@@ -63,40 +105,43 @@ import { verifyToken } from '@kokuin/token';
     // `delegationTokenAdded` emission so subscribers see consistent ground
     // truth from the revocation backend on the same tick.
     if (changed) {
-        const pending = await delegationStore.getPendingRevocationByJTI(payload.jti);
+        const pending = await delegationStore.getPendingRevocationByIssuer(payload.jti, payload.sub);
         if (pending != null) {
-            if (pending.revoker_did === payload.sub) {
-                // Pin the `verified_at` we send to subscribers to the same value the
-                // store writes; passing it explicitly avoids a millisecond-scale
-                // skew between the row and the emitted event under clock-tick
-                // boundaries.
-                const verifiedAt = Math.floor(Date.now() / 1000);
-                const flipped = await delegationStore.markRevocationVerified(payload.jti, {
-                    cap_exp: payload.exp,
-                    verified_at: verifiedAt
-                });
-                if (flipped && emitter != null) {
-                    await emitter.emit('delegationTokenRevoked', {
-                        jti: payload.jti,
-                        grantor: payload.sub,
-                        audience: payload.aud,
-                        revokerDID: pending.revoker_did,
-                        revokedAt: pending.revoked_iat,
-                        verifiedAt,
-                        capExp: payload.exp,
-                        groupID
-                    });
-                }
-            } else {
-                logger?.warn('pending revocation iss does not match arriving cap, dropping', {
+            // Pin the `verified_at` we send to subscribers to the same value the
+            // store writes; passing it explicitly avoids a millisecond-scale
+            // skew between the row and the emitted event under clock-tick
+            // boundaries.
+            const verifiedAt = Math.floor(Date.now() / 1000);
+            const flipped = await delegationStore.markRevocationVerified(payload.jti, payload.sub, {
+                cap_exp: payload.exp,
+                verified_at: verifiedAt
+            });
+            if (flipped && emitter != null) {
+                await emitter.emit('delegationTokenRevoked', {
                     jti: payload.jti,
-                    pendingIss: pending.revoker_did,
-                    capGrantor: payload.sub,
+                    grantor: payload.sub,
+                    audience: payload.aud,
+                    revokerDID: pending.revoker_did,
+                    revokedAt: pending.revoked_iat,
+                    verifiedAt,
+                    capExp: payload.exp,
                     groupID
                 });
-                await delegationStore.deletePendingRevocation(payload.jti);
             }
         }
+        // A `jti` names a capability only within one grantor's namespace, and it
+        // travels to the whole group — so a pending row from another author is
+        // either a forgery or a claim about a different capability. Either way this
+        // grant cannot cross-check it and it can never bind here.
+        const dropped = await delegationStore.deletePendingRevocationsFromOtherIssuers(payload.jti, payload.sub);
+        if (dropped > 0) {
+            logger?.warn('dropped pending revocations not authored by the arriving cap’s issuer', {
+                jti: payload.jti,
+                dropped,
+                capGrantor: payload.sub,
+                groupID
+            });
+        }
     }
     // Emit only when the held row was actually inserted or materially changed.
     // Idempotent re-broadcasts (LWW lost, or won with byte-identical content)

package/lib/groups/store-received-revocation.d.ts

@@ -21,26 +21,29 @@ export type StoreReceivedRevocationParams = {
      * This helper does not emit; downstream subscription wiring lives elsewhere.
      */
     emitter?: P2PEventEmitter;
-    /** Optional logger — debug on verification failure or malformed payload, warn on iss/grantor mismatch. */
+    /** Optional logger — debug on verification failure or malformed payload. */
     logger?: Logger;
 };
 /**
  * Verify a received revocation token and write its row to the P2P store.
  *
- * Verified-on-arrival: when the referenced capability is already known
- * locally and the revocation's `iss` matches that capability's `grantor`,
- * the row is stored with `verified_at` populated so the hot-path
- * `isRevoked` gate fires immediately. When the capability is unknown
- * locally, the row is stored as pending (`verified_at` null) until a later
- * `delegation:share` triggers a cross-check that flips it via
- * `markRevocationVerified`. A signature-verified token whose `iss` does
- * not match a known capability's `grantor` is rejected outright — a forged
- * revocation must not pollute the local store.
+ * Verified-on-arrival: when this device already holds a capability the
+ * record's own `iss` granted under that `jti`, the row is stored with
+ * `verified_at` populated so the hot-path `isRevoked` gate fires
+ * immediately. Otherwise the row is stored as pending (`verified_at` null)
+ * until a later `delegation:share` from that same issuer triggers a
+ * cross-check that flips it via `markRevocationVerified`.
+ *
+ * Holding someone else's capability under the same `jti` is not evidence
+ * that this record is forged — a `jti` is namespaced by its grantor and any
+ * co-member can reuse one — so such a record is stored pending like any
+ * other unmatched one. It binds nothing: every enforcement read is scoped to
+ * the revoker, and `storeReceivedGrant` drops it when the issuer's own
+ * capability arrives.
  *
  * Returns `true` when the row was inserted or materially changed (LWW
  * upsert). Returns `false` on verification failure, non-revocation
- * payload, iss/grantor mismatch, or a lost/idempotent LWW upsert. Never
- * throws on a forged or malformed token — it is skipped like an
- * unverifiable broadcast entry.
+ * payload, or a lost/idempotent LWW upsert. Never throws on a forged or
+ * malformed token — it is skipped like an unverifiable broadcast entry.
  */
 export declare function storeReceivedRevocation(params: StoreReceivedRevocationParams): Promise<boolean>;

package/lib/groups/store-received-revocation.js

@@ -2,21 +2,24 @@ import { verifyToken } from '@kokuin/token';
 /**
  * Verify a received revocation token and write its row to the P2P store.
  *
- * Verified-on-arrival: when the referenced capability is already known
- * locally and the revocation's `iss` matches that capability's `grantor`,
- * the row is stored with `verified_at` populated so the hot-path
- * `isRevoked` gate fires immediately. When the capability is unknown
- * locally, the row is stored as pending (`verified_at` null) until a later
- * `delegation:share` triggers a cross-check that flips it via
- * `markRevocationVerified`. A signature-verified token whose `iss` does
- * not match a known capability's `grantor` is rejected outright — a forged
- * revocation must not pollute the local store.
+ * Verified-on-arrival: when this device already holds a capability the
+ * record's own `iss` granted under that `jti`, the row is stored with
+ * `verified_at` populated so the hot-path `isRevoked` gate fires
+ * immediately. Otherwise the row is stored as pending (`verified_at` null)
+ * until a later `delegation:share` from that same issuer triggers a
+ * cross-check that flips it via `markRevocationVerified`.
+ *
+ * Holding someone else's capability under the same `jti` is not evidence
+ * that this record is forged — a `jti` is namespaced by its grantor and any
+ * co-member can reuse one — so such a record is stored pending like any
+ * other unmatched one. It binds nothing: every enforcement read is scoped to
+ * the revoker, and `storeReceivedGrant` drops it when the issuer's own
+ * capability arrives.
  *
  * Returns `true` when the row was inserted or materially changed (LWW
  * upsert). Returns `false` on verification failure, non-revocation
- * payload, iss/grantor mismatch, or a lost/idempotent LWW upsert. Never
- * throws on a forged or malformed token — it is skipped like an
- * unverifiable broadcast entry.
+ * payload, or a lost/idempotent LWW upsert. Never throws on a forged or
+ * malformed token — it is skipped like an unverifiable broadcast entry.
  */ export async function storeReceivedRevocation(params) {
     const { delegationStore, token, groupID, hlc, emitter, logger } = params;
     let payload;
@@ -37,19 +40,17 @@ import { verifyToken } from '@kokuin/token';
         return false;
     }
     const { jti, iss, iat } = payload;
-    const cap = await delegationStore.getDelegationTokenByJTI(jti);
+    // Scoped to the record's own issuer. A co-member can mint a capability
+    // reusing a `jti` it saw broadcast, so asking for "the" capability named by a
+    // `jti` returns an arbitrary grantor's row — and the grantor's genuine
+    // revocation is the one with something to lose when the answer is wrong.
+    const cap = await delegationStore.getDelegationTokenByGrantorJTI({
+        jti,
+        grantor: iss
+    });
     let verifiedAt = null;
     let capExp = null;
     if (cap != null) {
-        if (cap.grantor !== iss) {
-            logger?.warn('received revocation iss does not match known capability grantor, skipping', {
-                groupID,
-                jti,
-                iss,
-                grantor: cap.grantor
-            });
-            return false;
-        }
         verifiedAt = Math.floor(Date.now() / 1000);
         capExp = cap.exp;
     }

package/lib/hub/http-client.d.ts

@@ -1,42 +1,25 @@
 import { Client } from '@enkaku/client';
 import type { Identity } from '@kokuin/token';
 import type { HubProtocol } from '@kumiai/hub-protocol';
-import { type ServerDIDMismatchObserver, type ServerDIDObserver } from './did-observing-transport.js';
 export type CreateHubClientOptions = {
     /**
-     * Per-call observer fired once when the first signed response arrives. Set by
-     * the caller so observed server DIDs can be routed through TOFU capture with
-     * the hub URL bound. Factories that don't honour this opt simply skip TOFU
-     * capture for the spawned client.
+     * The hub's DID, resolved per (re)connect by the spawning caller — from the
+     * local hub row when it records one, otherwise from the hub's `/info`. Every
+     * token this client signs names it as the audience, and a hub always refuses a
+     * token that names nobody. Absent only when discovery failed: the connection
+     * is then attempted anyway and refused by the hub, which is what triggers the
+     * next discovery.
      */
-    onServerDID?: ServerDIDObserver;
-    /**
-     * Pinned `server_did` resolved from the local hub row at spawn time. When set,
-     * the underlying `DIDObservingTransport` enforces it: a non-matching first
-     * response raises `HubServerDIDMismatchError` and no message is delivered to
-     * the inner Client (hard-fail path). When unset, the wrapper falls back to
-     * TOFU capture via `onServerDID`.
-     */
-    expectedServerDID?: string;
-    /**
-     * Side-channel notifier fired when a pinned-DID mismatch is detected. Lets the
-     * caller log + evict on top of the typed error that propagates through the
-     * read loop.
-     */
-    onMismatch?: ServerDIDMismatchObserver;
+    serverID?: string;
 };
 export type CreateHubClient = (hubURL: string, opts?: CreateHubClientOptions) => Promise<Client<HubProtocol>>;
 export type CreateHTTPHubClientParams = {
     identity: Identity;
     fetch?: typeof globalThis.fetch;
-    serverID?: string;
     /**
-     * Fired once per hub client when the first signed response from the server
-     * arrives carrying `payload.iss = serverDID`. Subsequent responses do NOT
-     * re-fire this hook, even if `iss` differs. Used by `HubConnectionPool` to
-     * drive TOFU pinning into the hub manager. Per-call `onServerDID` from
-     * `CreateHubClientOptions` overrides this factory-level default.
+     * Fallback audience for every client this factory builds, for a caller that
+     * knows the hub's DID up front. Per-call `serverID` wins when set.
      */
-    onServerDID?: ServerDIDObserver;
+    serverID?: string;
 };
 export declare function createHTTPHubClient(params: CreateHTTPHubClientParams): CreateHubClient;

package/lib/hub/http-client.js

@@ -1,32 +1,15 @@
 import { Client } from '@enkaku/client';
 import { ClientTransport } from '@enkaku/http-fetch';
-import { DIDObservingTransport } from './did-observing-transport.js';
 export function createHTTPHubClient(params) {
     return async (hubURL, opts)=>{
-        const inner = new ClientTransport({
+        const transport = new ClientTransport({
             url: hubURL,
             fetch: params.fetch
         });
-        const observer = opts?.onServerDID ?? params.onServerDID;
-        const expectedServerDID = opts?.expectedServerDID;
-        const onMismatch = opts?.onMismatch;
-        // Wrap whenever any DID-aware behaviour is needed: TOFU capture (observer),
-        // pinned-DID enforcement (expectedServerDID), or mismatch side-channel.
-        const needsWrapper = observer != null || expectedServerDID != null || onMismatch != null;
-        const transport = needsWrapper ? new DIDObservingTransport({
-            inner,
-            // Wrapper requires an observer; supply a no-op when only enforcement
-            // is requested. The TOFU branch in the wrapper is gated by
-            // `expectedServerDID == null` regardless.
-            onServerDID: observer ?? (()=>{}),
-            expectedServerDID,
-            hubURL,
-            onMismatch
-        }) : inner;
         return new Client({
             transport,
             identity: params.identity,
-            serverID: params.serverID
+            serverID: opts?.serverID ?? params.serverID
         });
     };
 }

package/lib/hub/hub-like.d.ts

@@ -1,17 +1,26 @@
-import type { Client } from '@enkaku/client';
+import { type Client } from '@enkaku/client';
 import type { Logger } from '@kubun/logger';
-import type { HubProtocol } from '@kumiai/hub-protocol';
-import type { HubLike } from '@kumiai/hub-tunnel';
+import { type HubProtocol } from '@kumiai/hub-protocol';
+import type { HubReceiveSubscription, LogHub, MailboxHub } from '@kumiai/hub-tunnel';
 export type CreateHubLikeParams = {
     /**
      * Builds a fresh `Client<HubProtocol>` bound to one hub URL + device identity.
      * Called once on the first connect and again on every reconnect. Injected
      * rather than constructed here so the adapter is testable against a fake
-     * client without standing up HTTP.
+     * client without standing up HTTP. The signal is the adapter's own: a factory
+     * that reaches the network (hub discovery) must abandon it on dispose, or
+     * teardown waits out a request to a hub that is not answering.
      */
-    createClient: () => Client<HubProtocol> | Promise<Client<HubProtocol>>;
+    createClient: (signal: AbortSignal) => Client<HubProtocol> | Promise<Client<HubProtocol>>;
     /** Authenticated DID of this device — drains receive and stamps publishes. */
     localDID: string;
+    /**
+     * Called when the hub refused a request with `ACCESS_DENIED`, awaited before
+     * the reconnect backoff so anything it corrects is in place for the next dial.
+     * That code conflates a refused audience with a refused caller, so which one it
+     * was is the handler's to work out, not the adapter's.
+     */
+    onAccessDenied?: () => Promise<void>;
     logger?: Logger;
     ackFlushMs?: number;
     ackFlushMax?: number;
@@ -19,6 +28,48 @@ export type CreateHubLikeParams = {
     backoffMaxMs?: number;
     backoffJitter?: number;
 };
-export declare function createHubLike(params: CreateHubLikeParams): HubLike & {
+/** What a subscriber may narrow its own drain to, beyond its DID. */
+export type DeviceHubReceiveOptions = {
+    /**
+     * Deliver only frames the hub attested as sent by this DID.
+     *
+     * The narrowing happens on the fan-out, before anything is queued and long
+     * before anything is decrypted, which is what a directed session needs: MLS
+     * consumes a per-sender ratchet generation on open, so a session that opens a
+     * frame belonging to another has DESTROYED it — the session it was for waits
+     * out its idle timeout with nothing raised anywhere.
+     */
+    senderDID?: string;
+    /**
+     * Deliver only frames published to this topic.
+     *
+     * The tunnel transport already asks for this (`hub.receive(localDID, {
+     * topicID: receiveTopicID })`), and until it was honoured here the request
+     * went nowhere. It has to be applied on the fan-out for the same reason
+     * `senderDID` does: the encrypting transport decrypts a frame before the
+     * topic demux one layer in ever sees it, so a sink handed another lane's
+     * frame has consumed a ratchet generation and destroyed it.
+     */
+    topicID?: string;
+};
+/**
+ * The device hub as this package uses it: a `MailboxHub` whose `receive` also
+ * takes {@link DeviceHubReceiveOptions}. Declared because the tunnel transport
+ * takes the narrower `MailboxHub`, so a caller that needs a filtered drain has
+ * to hold this type to ask for one.
+ */
+export type DeviceHub = MailboxHub & {
+    receive: (subscriberDID: string, options?: DeviceHubReceiveOptions) => HubReceiveSubscription;
+};
+/**
+ * The reconnecting adapter itself, as its owner holds it: a hub, plus the two
+ * things only whoever built the connection can do — retry it now, and close it.
+ * Kept off {@link DeviceHub} because that is the surface a tunnel session
+ * consumes, and a session has no connection of its own to retry.
+ */
+export type ReconnectingDeviceHub = LogHub & DeviceHub & {
+    /** Try the hub now rather than when the backoff says so. */
+    retryNow: () => Promise<boolean>;
     dispose: () => Promise<void>;
 };
+export declare function createHubLike(params: CreateHubLikeParams): ReconnectingDeviceHub;