@spfn/core 0.3.0-beta.32 → 0.3.0-beta.33

package/dist/server/index.js

@@ -487,22 +487,33 @@ function createBoundedWriter(stream, maxQueue, onClose) {
 var registryLogger = logger.child("@spfn/core:sse");
 var SUBSCRIPTION_GRANTED = "subscription.granted";
 var SUBSCRIPTION_REVOKED = "subscription.revoked";
+var KEY_REVOKED = "key revoked";
 function createConnectionRegistry() {
   const bySubject = /* @__PURE__ */ new Map();
+  const byKey = /* @__PURE__ */ new Map();
   const pendingBySubject = /* @__PURE__ */ new Map();
-  const beginAdmission = (subject, signal) => {
+  const pendingByKey = /* @__PURE__ */ new Map();
+  const beginAdmission = (subject, keyId, signal) => {
     const changes = [];
     addToSet(pendingBySubject, subject, changes);
-    const end = endOnce(signal, () => removeFromSet(pendingBySubject, subject, changes));
+    addToOptionalSet(pendingByKey, keyId, changes);
+    const end = endOnce(signal, () => {
+      removeFromSet(pendingBySubject, subject, changes);
+      removeFromOptionalSet(pendingByKey, keyId, changes);
+    });
     return {
       cancel: end,
       open: (connection) => {
         if (!end()) {
-          return false;
+          return "aborted during admission";
+        }
+        if (changes.some((change2) => change2.kind === "close")) {
+          return KEY_REVOKED;
         }
         applyRecorded(connection, changes);
         addToSet(bySubject, subject, connection);
-        return true;
+        addToOptionalSet(byKey, connection.keyId, connection);
+        return null;
       }
     };
   };
@@ -522,15 +533,25 @@ function createConnectionRegistry() {
       });
     }
   };
+  const closeByKey = (keyId) => {
+    const connections = [...byKey.get(keyId) ?? []];
+    pendingByKey.get(keyId)?.forEach((changes) => changes.push({ kind: "close" }));
+    connections.forEach((connection) => connection.close(KEY_REVOKED));
+    return connections.length;
+  };
   return {
     beginAdmission,
+    closeByKey,
     remove: (connection) => {
       if (connection.subject) {
         removeFromSet(bySubject, connection.subject, connection);
       }
+      removeFromOptionalSet(byKey, connection.keyId, connection);
     },
     /** Open connections only — a pending admission is not counted. */
     count: (subject) => bySubject.get(subject)?.size ?? 0,
+    /** Open connections whose token was minted with `keyId`. */
+    countByKey: (keyId) => byKey.get(keyId)?.size ?? 0,
     pendingCount: (subject) => pendingBySubject.get(subject)?.size ?? 0,
     grant: (subject, eventName, match) => change("grant", subject, eventName, match),
     revoke: (subject, eventName, match) => change("revoke", subject, eventName, match)
@@ -558,6 +579,16 @@ function addToSet(map, key, value) {
   set.add(value);
   map.set(key, set);
 }
+function addToOptionalSet(map, key, value) {
+  if (key) {
+    addToSet(map, key, value);
+  }
+}
+function removeFromOptionalSet(map, key, value) {
+  if (key) {
+    removeFromSet(map, key, value);
+  }
+}
 function removeFromSet(map, key, value) {
   const set = map.get(key);
   set?.delete(value);
@@ -569,10 +600,11 @@ function matchesRequest(match, request) {
   return match === void 0 || Object.entries(match.query).every(([field, value]) => Object.hasOwn(request.query, field) && request.query[field] === value);
 }
 function applyRecorded(connection, changes) {
-  changes.forEach(({ kind, eventName, match }) => {
-    if (!matchesRequest(match, connection.request)) {
+  changes.forEach((change) => {
+    if (change.kind === "close" || !matchesRequest(change.match, connection.request)) {
       return;
     }
+    const { kind, eventName } = change;
     const [from, to] = kind === "grant" ? [connection.denied, connection.allowed] : [connection.allowed, connection.denied];
     if (from.delete(eventName)) {
       to.add(eventName);
@@ -602,6 +634,12 @@ function unsubscribeAll(connection) {
   connection.unsubscribes.forEach((unsubscribe) => unsubscribe());
   connection.unsubscribes.clear();
 }
+logger.child("@spfn/core:sse");
+var REGISTRIES_KEY = Symbol.for("@spfn/core:sse-key-close-registries");
+var registries = globalThis[REGISTRIES_KEY] ??= /* @__PURE__ */ new Set();
+function registerKeyCloseRegistry(registry) {
+  registries.add(registry);
+}
 
 // src/event/sse/handler.ts
 var sseLogger = logger.child("@spfn/core:sse");
@@ -634,6 +672,7 @@ function createSSEHandler(router, config = {}, tokenManager) {
   } = config;
   const registry = createConnectionRegistry();
   registerSubscriptionControls(router, registry);
+  registerKeyCloseRegistry(registry);
   const streamConfig = { router, authConfig, registry, pingInterval, maxQueue };
   const handler = async (c) => {
     const admission = await admitConnection(c, streamConfig, tokenManager);
@@ -655,7 +694,9 @@ function createSSEHandler(router, config = {}, tokenManager) {
     /** @internal Open registered connections of a subject (tests). */
     _openConnections: (subject) => registry.count(subject),
     /** @internal Connects of a subject still in admission (tests). */
-    _pendingAdmissions: (subject) => registry.pendingCount(subject)
+    _pendingAdmissions: (subject) => registry.pendingCount(subject),
+    /** @internal Open registered connections whose token was minted with a key (tests). */
+    _openConnectionsByKey: (keyId) => registry.countByKey(keyId)
   });
 }
 function registerSubscriptionControls(router, registry) {
@@ -667,17 +708,37 @@ function registerSubscriptionControls(router, registry) {
   }
 }
 async function admitConnection(c, config, tokenManager) {
-  const { router, authConfig, registry } = config;
-  const subject = await authenticateToken(c, tokenManager);
-  if (subject === false) {
+  const token = await takeToken(c, tokenManager);
+  if (token === false) {
     return c.json({ error: "Missing token parameter" }, 401);
   }
-  if (subject === null) {
-    return c.json({ error: "Invalid or expired token" }, 401);
+  if (token === null) {
+    return invalidToken(c);
   }
+  return whilePending(
+    token?.subject ? config.registry.beginAdmission(token.subject, token.keyId, c.req.raw.signal) : void 0,
+    () => checkConnection(c, config, token, tokenManager)
+  );
+}
+function invalidToken(c) {
+  return c.json({ error: "Invalid or expired token" }, 401);
+}
+async function checkConnection(c, config, token, tokenManager) {
+  if (token && tokenManager && !await tokenManager.checkKey(token)) {
+    return invalidToken(c);
+  }
+  const subject = token?.subject;
   if (subject) {
     c.set("sseSubject", subject);
   }
+  const requested = validateRequestedEvents(c, config.router);
+  if (requested instanceof Response) {
+    return requested;
+  }
+  const authorized = await authorizeConnection(c, config.router, config.authConfig, subject, requested);
+  return authorized instanceof Response ? authorized : { ...authorized, keyId: token?.keyId };
+}
+function validateRequestedEvents(c, router) {
   const requested = parseRequestedEvents(c);
   if (!requested) {
     return c.json({ error: "Missing events parameter" }, 400);
@@ -691,10 +752,7 @@ async function admitConnection(c, config, tokenManager) {
       validEvents: validEventNames
     }, 400);
   }
-  return whilePending(
-    subject ? registry.beginAdmission(subject, c.req.raw.signal) : void 0,
-    () => authorizeConnection(c, router, authConfig, subject, requested)
-  );
+  return requested;
 }
 async function whilePending(pending, check) {
   let outcome;
@@ -793,6 +851,7 @@ async function runStream(c, stream, admission, config) {
   };
   const connection = {
     subject,
+    keyId: admission.keyId,
     requested: admission.requested,
     allowed: new Set(allowed),
     denied: new Set(denied),
@@ -802,10 +861,12 @@ async function runStream(c, stream, admission, config) {
     notify: (frame, eventName) => {
       if (connectionDead) return;
       hold.send(() => writer.enqueue({ event: frame, data: JSON.stringify({ event: eventName }) }));
-    }
+    },
+    close: cleanup
   };
-  if (admission.pending?.open(connection) === false) {
-    cleanup("aborted during admission");
+  const refusal = admission.pending?.open(connection);
+  if (refusal) {
+    cleanup(refusal);
     return;
   }
   void openSubscriptions(connection, writer, hold, {
@@ -955,7 +1016,7 @@ function passesFrameFilters(eventName, eventDef, payload, ctx) {
     return false;
   }
 }
-async function authenticateToken(c, tokenManager) {
+async function takeToken(c, tokenManager) {
   if (!tokenManager) {
     return void 0;
   }
@@ -963,7 +1024,7 @@ async function authenticateToken(c, tokenManager) {
   if (!token) {
     return false;
   }
-  return await tokenManager.verify(token);
+  return tokenManager.take(token);
 }
 function parseRequestedEvents(c) {
   const eventsParam = c.req.query("events");
@@ -988,6 +1049,7 @@ var DEFAULT_SSE_STREAM_PATH = "/events/stream";
 function sseTokenPath(streamPath) {
   return streamPath.replace(/\/[^/]+$/, "/token");
 }
+var tokenLogger = logger.child("@spfn/core:sse");
 function hashToken(token) {
   return createHash("sha256").update(token).digest("hex");
 }
@@ -1050,10 +1112,12 @@ var CacheTokenStore = class {
 var SSETokenManager = class {
   store;
   ttl;
+  verifyKey;
   cleanupTimer = null;
   constructor(config) {
     this.ttl = config?.ttl ?? 3e4;
     this.store = config?.store ?? new InMemoryTokenStore();
+    this.verifyKey = config?.verifyKey;
     const cleanupInterval = config?.cleanupInterval ?? 6e4;
     this.cleanupTimer = setInterval(() => void this.store.cleanup(), cleanupInterval);
     this.cleanupTimer.unref();
@@ -1068,13 +1132,16 @@ var SSETokenManager = class {
     return this.ttl;
   }
   /**
-   * Issue a new one-time-use token for the given subject
+   * Issue a new one-time-use token for the given subject. `keyId` tags it
+   * with the device key it is minted for; an empty one leaves it untagged.
    */
-  async issue(subject) {
+  async issue(subject, options) {
     const token = randomBytes(32).toString("hex");
+    const keyId = options?.keyId || void 0;
     await this.store.set(token, {
       subject,
-      expiresAt: Date.now() + this.ttl
+      expiresAt: Date.now() + this.ttl,
+      ...keyId ? { keyId } : {}
     });
     return token;
   }
@@ -1083,11 +1150,43 @@ var SSETokenManager = class {
    * @returns subject string if valid, null if invalid/expired/already consumed
    */
   async verify(token) {
+    return (await this.consume(token))?.subject ?? null;
+  }
+  /**
+   * Consume a token and answer what it was minted with: `null` when it is
+   * unknown, expired, already consumed, or its key no longer holds
+   * (`verifyKey`). The token is gone either way. `take` + `checkKey`.
+   */
+  async consume(token) {
+    const data = await this.take(token);
+    return data && await this.checkKey(data) ? data : null;
+  }
+  /**
+   * The store half of `consume`: take the token out of the store and answer
+   * what it was minted with, `null` when it is unknown, expired or already
+   * consumed — its key is not checked yet (`checkKey`). For a caller that
+   * has to register the connection before the key check, so a revocation
+   * landing during the check reaches it.
+   */
+  async take(token) {
     const data = await this.store.consume(token);
-    if (!data || data.expiresAt <= Date.now()) {
-      return null;
+    return data && data.expiresAt > Date.now() ? data : null;
+  }
+  /**
+   * The key half of `consume`: `verifyKey` on a tagged token; an untagged
+   * one, or no verifier, holds without a call. A throw refuses and is warned
+   * without its text — it may carry what the verifier read.
+   */
+  async checkKey(data) {
+    if (!data.keyId || !this.verifyKey) {
+      return true;
+    }
+    try {
+      return await this.verifyKey(data.keyId) === true;
+    } catch {
+      tokenLogger.warn("SSE token key check threw \u2014 token refused");
+      return false;
     }
-    return data.subject;
   }
   /**
    * Cleanup timer and resources
@@ -1106,6 +1205,8 @@ var PUBLISH_TIMEOUT_MS = 5e3;
 var SUBSCRIBE_TIMEOUT_MS = 5e3;
 var WARN_THROTTLE_MS = 3e4;
 var PUBLISH_BREAKER_COOLDOWN_MS = 1e4;
+var KEY_CLOSE_RETRY_MS = PUBLISH_BREAKER_COOLDOWN_MS + 500;
+var PENDING_KEY_CLOSE_CAP = 1e3;
 function withTimeout(promise, ms, label) {
   return new Promise((resolve2, reject) => {
     const timer = setTimeout(() => {
@@ -1140,8 +1241,76 @@ var state = globalThis[STATE_KEY] ??= {
   pubSubCache: void 0,
   subscriber: void 0,
   channelPrefix: void 0,
-  wired: /* @__PURE__ */ new Map()
+  wired: /* @__PURE__ */ new Map(),
+  keyCloseDeferrals: /* @__PURE__ */ new Map()
 };
+function createKeyCloseDeferral(resend) {
+  const pending = /* @__PURE__ */ new Map();
+  let timer;
+  let flushing = false;
+  let disposed = false;
+  const arm = () => {
+    if (timer || disposed) {
+      return;
+    }
+    timer = setTimeout(() => {
+      timer = void 0;
+      void flush();
+    }, KEY_CLOSE_RETRY_MS);
+    timer.unref?.();
+  };
+  const disarm = () => {
+    clearTimeout(timer);
+    timer = void 0;
+  };
+  const flush = async () => {
+    if (flushing || pending.size === 0) {
+      return;
+    }
+    flushing = true;
+    const snapshot = [...pending.values()];
+    pending.clear();
+    for (const message of snapshot) {
+      await resend(message);
+    }
+    flushing = false;
+    if (pending.size > 0) {
+      arm();
+    } else {
+      disarm();
+    }
+  };
+  return {
+    defer: (message) => {
+      if (disposed) {
+        return;
+      }
+      pending.delete(message.keyId);
+      pending.set(message.keyId, message);
+      dropOldestPastCap(pending);
+      throttledWarn("key-close-deferred", "SSE key close deferred \u2014 re-sent when the pub/sub transport recovers", {
+        channel: CONTROL_CHANNEL,
+        pending: pending.size
+      });
+      arm();
+    },
+    flush,
+    dispose: () => {
+      disposed = true;
+      disarm();
+      pending.clear();
+    },
+    keyIds: () => [...pending.keys()]
+  };
+}
+function dropOldestPastCap(pending) {
+  const dropped = pending.size - PENDING_KEY_CLOSE_CAP;
+  if (dropped <= 0) {
+    return;
+  }
+  [...pending.keys()].slice(0, dropped).forEach((keyId) => pending.delete(keyId));
+  throttledWarn("key-close-dropped", "SSE key closes dropped \u2014 too many waiting to be re-sent", { dropped });
+}
 function resolveChannelPrefix(override) {
   return override ?? process.env.SPFN_SSE_CHANNEL_PREFIX ?? DEFAULT_CHANNEL_PREFIX;
 }
@@ -1181,7 +1350,13 @@ function createRedisPubSubCache(client, channelPrefix, onSubscriber) {
       void handler(message);
     }
   };
-  return {
+  let keyCloses;
+  const deferIfKeyClose = (name, message) => {
+    if (name === CONTROL_CHANNEL && isKeyCloseMessage(message)) {
+      keyCloses.defer(message);
+    }
+  };
+  const cache2 = {
     publish: async (name, message) => {
       const channel = channelPrefix + name;
       let serialized;
@@ -1205,6 +1380,7 @@ function createRedisPubSubCache(client, channelPrefix, onSubscriber) {
       const ready = client.status === void 0 || client.status === "ready";
       const now = Date.now();
       if (!ready || degradedUntil > 0 && now < degradedUntil) {
+        deferIfKeyClose(name, message);
         deliverLocal(channel, JSON.parse(serialized));
         return;
       }
@@ -1214,18 +1390,17 @@ function createRedisPubSubCache(client, channelPrefix, onSubscriber) {
       try {
         await withTimeout(client.publish(channel, serialized), PUBLISH_TIMEOUT_MS, "pub/sub publish");
         degradedUntil = 0;
+        void keyCloses.flush();
         if (!subscriberHealthy()) {
           throttledWarn("subscriber-down", "Subscriber connection down \u2014 same-pod local fallback", {
             channel
           });
           deliverLocal(channel, JSON.parse(serialized));
         }
-      } catch (err) {
+      } catch {
         degradedUntil = Date.now() + PUBLISH_BREAKER_COOLDOWN_MS;
-        throttledWarn("publish-failed", "Pub/sub publish failed \u2014 local delivery only", {
-          channel,
-          error: err instanceof Error ? err.message : String(err)
-        });
+        throttledWarn(`publish-failed:${channel}`, "Pub/sub publish failed \u2014 local delivery only", { channel });
+        deferIfKeyClose(name, message);
         deliverLocal(channel, JSON.parse(serialized));
       }
     },
@@ -1244,6 +1419,14 @@ function createRedisPubSubCache(client, channelPrefix, onSubscriber) {
       handlers.set(channel, handler);
     }
   };
+  keyCloses = createKeyCloseDeferral((message) => cache2.publish(CONTROL_CHANNEL, message));
+  state.keyCloseDeferrals.set(cache2, keyCloses);
+  return cache2;
+}
+var CONTROL_CHANNEL = "$control";
+function isKeyCloseMessage(message) {
+  const candidate = message;
+  return !!candidate && candidate.kind === "close" && typeof candidate.keyId === "string" && candidate.keyId !== "" && typeof candidate.origin === "string";
 }
 async function wireEventRouterCache(router, options = {}) {
   if (options.multiInstance === false) {
@@ -1341,6 +1524,8 @@ async function closeEventTransport() {
   for (const event of state.wired.values()) {
     event._resetCache?.();
   }
+  state.keyCloseDeferrals.forEach((deferral) => deferral.dispose());
+  state.keyCloseDeferrals.clear();
   state.subscriber = void 0;
   state.pubSubCache = void 0;
   state.channelPrefix = void 0;
@@ -2573,12 +2758,13 @@ async function registerSSEEndpoint(app, config) {
     const tokenPath = sseTokenPath(streamPath);
     const mwHandlers = resolveEndpointMiddlewares(config).map((mw) => mw.handler);
     const getSubject = authConfig.getSubject ?? ((c) => c.get("auth")?.userId ?? null);
+    const getKeyId = authConfig.getKeyId ?? ((c) => c.get("auth")?.keyId);
     app.on(["POST"], [tokenPath], ...mwHandlers, async (c) => {
       const subject = getSubject(c);
       if (!subject) {
         return c.json({ error: "Unable to identify subject" }, 401);
       }
-      const token = await tokenManager.issue(subject);
+      const token = await tokenManager.issue(subject, { keyId: getKeyId(c) ?? void 0 });
       return c.json({ token });
     });
     if (debug) {
@@ -3318,10 +3504,10 @@ function readPort(value) {
   return Number.isInteger(port) && port > 0 && port < 65536 ? port : void 0;
 }
 logger.child("@spfn/core:env-registry");
-function validateAllEnv(registries) {
+function validateAllEnv(registries2) {
   const errors = [];
   const warnings = [];
-  for (const registry of registries) {
+  for (const registry of registries2) {
     const result = registry.validateAll();
     errors.push(...result.errors);
     warnings.push(...result.warnings);