@byok-sdk/server 0.10.1 → 0.11.0

package/dist/auth.d.ts

@@ -70,18 +70,22 @@ export interface DeviceRecord {
     deviceName: string;
     /** Ed25519 public key, base64url-encoded (JWK `x` form — see {@link verifyEd25519Signature}). */
     devicePublicKey: string;
-    revoked: boolean;
 }
-/** Everything `POST /byok/pair` knows at registration time; `revoked` is the registry's own to set. */
-export type DeviceRegistration = Omit<DeviceRecord, 'revoked'>;
+/**
+ * Everything `POST /byok/pair` knows at registration time — which is the whole
+ * row. Revocation DELETES the registration (§6.3), so there is no lifecycle
+ * flag for the registry to own on top of what pairing supplies.
+ */
+export type DeviceRegistration = DeviceRecord;
 export declare class DeviceRegistry {
     /** Keyed by {@link DeviceRegistry.key} — `(tenantId, deviceId)`. */
     private readonly devices;
     /**
      * Secondary index over the SAME record objects, for the two pre-tenant
-     * endpoints only (see {@link resolveByDeviceId}). Holding the same object
-     * reference means a revocation applied through the composite key is
-     * immediately visible here too — there is no second copy to keep in sync.
+     * endpoints only (see {@link resolveByDeviceId}). It holds the same record
+     * objects rather than copies, and {@link revoke} removes the entry here in
+     * the same call that removes the composite-key one — a stale entry left
+     * behind would be a deleted device that can still get a token.
      */
     private readonly byDeviceId;
     private static key;
@@ -95,13 +99,26 @@ export declare class DeviceRegistry {
     get(tenantId: TenantId, deviceId: string): DeviceRecord | undefined;
     /**
      * Revoke a device (public API via `createByokServer(...).devices.revoke`).
-     * Its next `/byok/challenge`, `/byok/token`, WSS connect, or authed HTTP
-     * call gets a 401; the daemon's only recourse is to re-run `/byok/pair`
-     * (docs/protocol.md §6.3). A tenant can only revoke its own devices: a
-     * (tenantId, deviceId) pair it does not own resolves to nothing and this is
-     * a no-op.
+     * Revocation DELETES the registration (docs/protocol.md §6.3): afterwards
+     * the device id is byte-for-byte one that was never registered — absent
+     * from {@link list}, resolving to nothing on the pre-tenant
+     * `/byok/challenge` and `/byok/token` paths, and a 401 on every authed
+     * surface. The daemon's only recourse is to re-run `/byok/pair`.
+     *
+     * There is deliberately no retained `revoked` row: a flag every read path
+     * has to remember to exclude is a second way to represent "not a
+     * principal", and the first read path that forgets it is a live credential.
+     *
+     * A tenant can only revoke its own devices: a (tenantId, deviceId) pair it
+     * does not own resolves to nothing, deletes nothing, and is silently
+     * indistinguishable from revoking one that never existed.
+     *
+     * Returns whether a row was actually removed — the composition in
+     * `index.ts` uses it to delete the device-scoped state that only existed to
+     * serve that row (nonces, presence, dedup), so a no-op revoke touches
+     * nothing at all.
      */
-    revoke(tenantId: TenantId, deviceId: string): void;
+    revoke(tenantId: TenantId, deviceId: string): boolean;
     /** Every known device row, across tenants — the in-process read model behind `ByokServer.machines.list()`. */
     list(): DeviceRecord[];
     /**
@@ -133,6 +150,13 @@ export declare class NonceStore {
     issue(deviceId: string): string;
     /** `true` iff `nonce` exists, belongs to `deviceId`, is unexpired, and hasn't been consumed yet. Does not mutate. */
     validate(deviceId: string, nonce: string): boolean;
+    /**
+     * Drop every nonce outstanding for `deviceId` — called when the device's
+     * registration is deleted (§6.3 revocation). An unspent challenge is state
+     * that only existed to serve a row the directory can no longer name, so it
+     * goes with the row rather than sitting until its TTL sweeps it.
+     */
+    deleteForDevice(deviceId: string): void;
     /** Mark `nonce` consumed so a replay of the same (deviceId, nonce, signature) is rejected. */
     markUsed(nonce: string): void;
 }
@@ -175,9 +199,10 @@ export interface AuthenticatedDevice {
  * S1 shape: the token's `(tenantId, deviceId)` are LOOKUP KEYS into the
  * registry, and the row that comes back is the authority. A token for a
  * device that no longer exists, one whose tenant does not own that device,
- * one whose product disagrees with the row, one whose row belongs to a
- * different product than this instance serves, and one for a revoked device
- * all fail identically here and are indistinguishable to the caller — there
+ * one whose product disagrees with the row, and one whose row belongs to a
+ * different product than this instance serves all fail identically here and
+ * are indistinguishable to the caller — a revoked device is exactly the first
+ * of those, since revocation deleted its row (§6.3) — there
  * is deliberately no "which of those was it" signal to hand back, so no route
  * can turn a 401 into a cross-tenant (or cross-product) existence oracle.
  *

package/dist/hub.d.ts

@@ -333,6 +333,26 @@ export declare class ConnectionHub {
      * here (see the M1-2 report's contract-gap notes).
      */
     handleDisconnect(deviceId: string, ws: WebSocket): void;
+    /**
+     * Drop every piece of hub state keyed by `deviceId` — called when the
+     * device's registration is DELETED (§6.3 revocation, composed in
+     * `index.ts`). Presence, its undelivered outbox, its inbound-dedup ring,
+     * any held long-poll, and its rate-limit episode suppression only ever
+     * existed to serve a row the directory can no longer name; leaving them
+     * would keep a deleted device visible as live state and would let a
+     * re-paired device inherit the dead one's dedup window and seq cursor.
+     *
+     * What the device DID is not revocation's business and is untouched here:
+     * task records (`taskStore`), egress and content receipts, and projection
+     * facts are history, not credentials.
+     *
+     * A live socket is closed rather than left attached — a still-open WS whose
+     * next envelope would re-create the presence entry we just deleted is a
+     * half-applied revocation. The close is detached first so `handleDisconnect`
+     * sees no connection state and skips its disconnect bookkeeping: the device
+     * is not going dark, it is gone.
+     */
+    forgetDevice(deviceId: string): void;
     /**
      * Resolve immediately if there are already-relevant events past `cursor`;
      * otherwise hold for up to `holdMs` and resolve with an empty result if

package/dist/index.d.ts

@@ -86,8 +86,12 @@ export interface ByokServer {
     };
     /**
      * Device revocation (§6.3) — server-side only, no wire message. Revoking a
-     * device makes its next `/byok/challenge`, `/byok/token`, WSS connect, or
-     * authed HTTP call get a 401; its only recourse is to re-run `/byok/pair`.
+     * device DELETES its registration, so its next `/byok/challenge`,
+     * `/byok/token`, WSS connect, or authed HTTP call gets a 401 — the same
+     * answer as for a device id that was never registered — and its only
+     * recourse is to re-run `/byok/pair`. The device-scoped state the row
+     * owned (outstanding challenge nonces, presence, inbound dedup) is deleted
+     * with it; what the device DID (tasks, receipts) is history and survives.
      *
      * S1: tenant-first, and a tenant can only revoke a device it owns — a
      * `(tenantId, deviceId)` pair belonging to someone else resolves to

package/dist/index.js

@@ -41,9 +41,10 @@ var DeviceRegistry = class _DeviceRegistry {
   devices = /* @__PURE__ */ new Map();
   /**
    * Secondary index over the SAME record objects, for the two pre-tenant
-   * endpoints only (see {@link resolveByDeviceId}). Holding the same object
-   * reference means a revocation applied through the composite key is
-   * immediately visible here too — there is no second copy to keep in sync.
+   * endpoints only (see {@link resolveByDeviceId}). It holds the same record
+   * objects rather than copies, and {@link revoke} removes the entry here in
+   * the same call that removes the composite-key one — a stale entry left
+   * behind would be a deleted device that can still get a token.
    */
   byDeviceId = /* @__PURE__ */ new Map();
   static key(tenantId, deviceId) {
@@ -55,7 +56,7 @@ var DeviceRegistry = class _DeviceRegistry {
    * — which is the whole point of S1.
    */
   register(device) {
-    const record = { ...device, revoked: false };
+    const record = { ...device };
     this.devices.set(_DeviceRegistry.key(record.tenantId, record.deviceId), record);
     this.byDeviceId.set(record.deviceId, record);
   }
@@ -65,15 +66,31 @@ var DeviceRegistry = class _DeviceRegistry {
   }
   /**
    * Revoke a device (public API via `createByokServer(...).devices.revoke`).
-   * Its next `/byok/challenge`, `/byok/token`, WSS connect, or authed HTTP
-   * call gets a 401; the daemon's only recourse is to re-run `/byok/pair`
-   * (docs/protocol.md §6.3). A tenant can only revoke its own devices: a
-   * (tenantId, deviceId) pair it does not own resolves to nothing and this is
-   * a no-op.
+   * Revocation DELETES the registration (docs/protocol.md §6.3): afterwards
+   * the device id is byte-for-byte one that was never registered — absent
+   * from {@link list}, resolving to nothing on the pre-tenant
+   * `/byok/challenge` and `/byok/token` paths, and a 401 on every authed
+   * surface. The daemon's only recourse is to re-run `/byok/pair`.
+   *
+   * There is deliberately no retained `revoked` row: a flag every read path
+   * has to remember to exclude is a second way to represent "not a
+   * principal", and the first read path that forgets it is a live credential.
+   *
+   * A tenant can only revoke its own devices: a (tenantId, deviceId) pair it
+   * does not own resolves to nothing, deletes nothing, and is silently
+   * indistinguishable from revoking one that never existed.
+   *
+   * Returns whether a row was actually removed — the composition in
+   * `index.ts` uses it to delete the device-scoped state that only existed to
+   * serve that row (nonces, presence, dedup), so a no-op revoke touches
+   * nothing at all.
    */
   revoke(tenantId, deviceId) {
     const record = this.get(tenantId, deviceId);
-    if (record) record.revoked = true;
+    if (!record) return false;
+    this.devices.delete(_DeviceRegistry.key(tenantId, deviceId));
+    if (this.byDeviceId.get(deviceId) === record) this.byDeviceId.delete(deviceId);
+    return true;
   }
   /** Every known device row, across tenants — the in-process read model behind `ByokServer.machines.list()`. */
   list() {
@@ -131,6 +148,17 @@ var NonceStore = class {
     if (Date.now() > record.expiresAt) return false;
     return true;
   }
+  /**
+   * Drop every nonce outstanding for `deviceId` — called when the device's
+   * registration is deleted (§6.3 revocation). An unspent challenge is state
+   * that only existed to serve a row the directory can no longer name, so it
+   * goes with the row rather than sitting until its TTL sweeps it.
+   */
+  deleteForDevice(deviceId) {
+    for (const [nonce, record] of this.nonces) {
+      if (record.deviceId === deviceId) this.nonces.delete(nonce);
+    }
+  }
   /** Mark `nonce` consumed so a replay of the same (deviceId, nonce, signature) is rejected. */
   markUsed(nonce) {
     const record = this.nonces.get(nonce);
@@ -162,7 +190,7 @@ async function authenticateBearer(header, deps) {
   const claims = await deps.tokenSigner.verify(token);
   if (!claims) return void 0;
   const device = deps.devices.get(claims.tenantId, claims.deviceId);
-  if (!device || device.revoked) return void 0;
+  if (!device) return void 0;
   if (device.productId !== claims.productId) return void 0;
   if (device.productId !== deps.productId) return void 0;
   return { deviceId: device.deviceId, tenantId: device.tenantId, productId: device.productId };
@@ -702,6 +730,34 @@ var ConnectionHub = class {
     this.serverEvents.push({ kind: "device.disconnected", deviceId, at: conn.lastSeen });
     this.settleLongPollWaiter(deviceId);
   }
+  /**
+   * Drop every piece of hub state keyed by `deviceId` — called when the
+   * device's registration is DELETED (§6.3 revocation, composed in
+   * `index.ts`). Presence, its undelivered outbox, its inbound-dedup ring,
+   * any held long-poll, and its rate-limit episode suppression only ever
+   * existed to serve a row the directory can no longer name; leaving them
+   * would keep a deleted device visible as live state and would let a
+   * re-paired device inherit the dead one's dedup window and seq cursor.
+   *
+   * What the device DID is not revocation's business and is untouched here:
+   * task records (`taskStore`), egress and content receipts, and projection
+   * facts are history, not credentials.
+   *
+   * A live socket is closed rather than left attached — a still-open WS whose
+   * next envelope would re-create the presence entry we just deleted is a
+   * half-applied revocation. The close is detached first so `handleDisconnect`
+   * sees no connection state and skips its disconnect bookkeeping: the device
+   * is not going dark, it is gone.
+   */
+  forgetDevice(deviceId) {
+    const conn = this.connections.get(deviceId);
+    this.connections.delete(deviceId);
+    this.outboxes.delete(deviceId);
+    this.dedupRings.delete(deviceId);
+    this.rateLimitEventEmittedFor.delete(deviceId);
+    this.settleLongPollWaiter(deviceId);
+    conn?.ws?.close(1e3, "device revoked");
+  }
   // ---------------------------------------------------------------------
   // long-poll fallback (§8) — GET /byok/events, called from http.ts
   // ---------------------------------------------------------------------
@@ -1889,7 +1945,7 @@ var ConnectionHub = class {
     const desired = this.agentHomeProjectionRequests.get(key);
     if (desired === void 0) return void 0;
     const device = this.devices.resolveByDeviceId(deviceId);
-    if (device === void 0 || device.revoked) return void 0;
+    if (device === void 0) return void 0;
     return AgentHomeProjectionReadbackSchema.parse({
       tenantId: device.tenantId,
       deviceId,
@@ -1917,7 +1973,7 @@ var ConnectionHub = class {
       return existing;
     }
     const device = this.devices.resolveByDeviceId(deviceId);
-    if (device === void 0 || device.revoked) {
+    if (device === void 0) {
       throw new AgentHomeProjectionCompletionError("not_found", "Agent-home projection device was not found");
     }
     const readback = AgentHomeProjectionReadbackSchema.parse({
@@ -2359,7 +2415,7 @@ function buildHonoApp(deps) {
     if (!parsed.success) return c.json({ error: "deviceId is required" }, 400);
     const { deviceId } = parsed.data;
     const device = deps.devices.resolveByDeviceId(deviceId);
-    if (!device || device.revoked) {
+    if (!device) {
       return c.json({ error: "unknown or revoked device" }, 401);
     }
     const nonce = deps.nonces.issue(deviceId);
@@ -2371,7 +2427,7 @@ function buildHonoApp(deps) {
     if (!parsed.success) return c.json({ error: "deviceId, nonce, and signature are required" }, 400);
     const { deviceId, nonce, signature } = parsed.data;
     const device = deps.devices.resolveByDeviceId(deviceId);
-    if (!device || device.revoked) {
+    if (!device) {
       return c.json({ error: "unknown or revoked device" }, 401);
     }
     if (!deps.nonces.validate(deviceId, nonce)) {
@@ -3270,7 +3326,11 @@ function createByokServer(opts) {
       subscribe: () => hub.subscribeServerEvents()
     },
     devices: {
-      revoke: (tenantId, deviceId) => devices.revoke(tenantId, deviceId)
+      revoke: (tenantId, deviceId) => {
+        if (!devices.revoke(tenantId, deviceId)) return;
+        nonces.deleteForDevice(deviceId);
+        hub.forgetDevice(deviceId);
+      }
     },
     stop() {
       hub.stopLeaseReaper();