@t3b/hub-guard 0.8.0 → 0.9.0

package/README.md

@@ -271,14 +271,21 @@ const lines = guard.appMenu(session);
 
 ## What it enforces
 
-- `/hub/enter?ticket=…`: an EdDSA ticket signed by the Hub's published key, for this module, from this environment's Hub, 60 seconds, single use → sets the module session (HttpOnly, Secure, SameSite=Strict) and answers a short "Opening …" page that moves on to the page (0.4.0: a SameSite=Strict cookie set on a redirect ending a navigation from another site is not sent on it). `appName` names the app on that page; `landing(path)` maps the pass's page (e.g. `"/"` → `"/app"`), never off the module's own address.
-- Every other request: no session → 403 (HTML for browsers, JSON for APIs), on **every host** the module answers on. Idle 180 minutes (0.5.0), absolute 8 hours. Every 15 minutes the Hub is asked (with the app's Vercel ID) whether the person's session still stands. A Hub blip keeps the session until the next check.
+- `/hub/enter?ticket=…`: an EdDSA ticket signed by the Hub's published key, for this module, from this environment's Hub, 60 seconds, single use - spent at the Hub, so once across all servers (0.9.0) → sets the module session (HttpOnly, Secure, SameSite=Strict) and answers a short "Opening …" page that moves on to the page (0.4.0: a SameSite=Strict cookie set on a redirect ending a navigation from another site is not sent on it). `appName` names the app on that page; `landing(path)` maps the pass's page (e.g. `"/"` → `"/app"`), never off the module's own address.
+- Every other request: no session → 403 (HTML for browsers, JSON for APIs), on **every host** the module answers on. Idle 180 minutes (0.5.0), absolute 8 hours. Every 15 minutes the Hub is asked (with the app's Vercel ID) whether the person's session still stands, and refreshes their pages, apps and stores (0.9.0). A Hub blip keeps the session until the next check; after **180 minutes** without an answer (`maxStaleMs`) the module still opens and reads, but every change waits - a POST/PUT/PATCH/DELETE answers 503 `hub_unreachable` and `allows(…, "write")` / `pageAllowed` say no (0.9.0).
 - Open paths (`/hub/enter`, `/api/hub/manifest`, `/api/hub/health`, `/api/hub/activity` and what you add) never need a session — they carry their own locks (the Hub's pass, a cron secret).
 - Cloudflare Access proof checked first when the team and audience are set.
 - `verifyRelay`, `manifestResponse`, `healthResponse`, `activityResponse`, `verifyStationCall`: the Hub's pass, for this module, for this purpose, from this environment's Hub; a relay and a station pack also for these exact bytes; a relay at most 5 minutes old; a call at most 60 seconds old.
 
 ## Changes
 
+- **0.9.0** (the Hub audit of 2026-10-04, H07-H09): (1) the 15-minute check refreshes `session.stores` - a store taken
+  away leaves the open app within 15 minutes; (2) after `maxStaleMs` (default 180 minutes, `MAX_STALE_MS`) without the
+  Hub's answer the session is `stale`: reads go on, changes are refused (503 `hub_unreachable`, `pageAllowed(…, "write")`
+  false - the owner too) until the Hub answers again; (3) every entry ticket is spent at the Hub
+  (`POST /api/hub/ticket-used`, `spendTicket`) - a ticket works once across every server; if the Hub does not confirm
+  it, the entry is refused (open the app again from the Hub). **The Hub must be on its 2026-10-05 release or later before
+  an app takes 0.9.0** (the ticket door). `sharedReplay: false` turns (3) off (tests only).
 - **0.8.0** (WORKFLOWS §18): the Apps button - the pass's and the 15-minute check's `apps` are kept in the session
   (`session.apps`), `guard.appMenu(session)` / `appMenu()` give the lines, `readApps` reads a list defensively. Nothing
   else changes; a module on 0.7.0 keeps working (its sessions simply carry no list).

package/dist/guard.d.ts

@@ -27,6 +27,10 @@ export type GuardConfig = {
         audience?: string;
     };
     absoluteMs?: number;
+    /** H08 (0.9.0): how long changes stay allowed while the Hub does not answer; default 180 minutes */
+    maxStaleMs?: number;
+    /** H09 (0.9.0): spend each ticket at the Hub (works once across all servers); default on - off only in tests */
+    sharedReplay?: boolean;
     fetchImpl?: typeof fetch;
     now?: () => Date;
 };
@@ -60,6 +64,8 @@ export declare class Guard {
     enter(req: Request): Promise<Response>;
     /** Every other request: open path → allow; else the session must stand, be fresh, and pass the 15-minute Hub check. */
     check(req: Request): Promise<CheckResult>;
+    /** H08: 503 while the Hub has been silent too long - the session stays (nothing is signed out), changes wait. */
+    pauseChanges(req: Request): Response;
     /**
      * §14: may this person read (`"read"`) or change (`"write"`) this page? The owner may do everything.
      * Ask on the server for every page and every action, then answer `refusePage` when not.

package/dist/guard.js

@@ -1,9 +1,9 @@
 import { appMenu } from "./apps.js";
 import { checkCloudflareAccess } from "./cf-access.js";
-import { sessionCheckPages } from "./hub-client.js";
+import { sessionCheckPages, spendTicket } from "./hub-client.js";
 import { pageAllowed } from "./pages.js";
 import { hubKeys } from "./identity.js";
-import { clearCookieHeader, cookieHeader, cookieValue, readSession, signSession, RECHECK_MS, SESSION_COOKIE } from "./session.js";
+import { clearCookieHeader, cookieHeader, cookieValue, readSession, signSession, MAX_STALE_MS, RECHECK_MS, SESSION_COOKIE } from "./session.js";
 import { JtiMemory, verifyTicket } from "./ticket.js";
 import { hmacSha256, toHex } from "./webcrypto.js";
 export class Guard {
@@ -59,6 +59,14 @@ export class Guard {
             const words = { expired: "The ticket has expired (it lives 60 seconds) - open the module again from the Hub.", wrong_audience: "This ticket was made for another module.", bad_signature: "This ticket was not signed by the Hub.", replayed: "This ticket was already used.", malformed: "No valid ticket.", wrong_environment: "This ticket comes from another Hub (test or live)." };
             return this.refuse(req, words[v.reason] ?? "No valid ticket.");
         }
+        // H09: this server's memory stopped a replay here; the Hub stops one on any other server
+        if (this.cfg.sharedReplay !== false) {
+            const spent = await spendTicket(this.hubClient(), v.claims.jti, v.claims.exp);
+            if (spent === "used")
+                return this.refuse(req, "This ticket was already used.");
+            if (spent === "unknown")
+                return this.refuse(req, "The Hub could not confirm this ticket - open the app again from the Hub.");
+        }
         const now = this.now().getTime();
         const session = { personId: v.claims.sub, name: v.claims.name, role: v.claims.role, stores: v.claims.stores, sv: v.claims.sv, iat: now, lastSeen: now, checkedAt: now, pages: v.claims.pages, apps: v.claims.apps };
         const landed = new URL(this.cfg.landing ? this.cfg.landing(v.claims.path) : v.claims.path, url.origin);
@@ -97,12 +105,28 @@ export class Guard {
             const r2 = await sessionCheckPages(this.hubClient(), s.personId, s.sv);
             if (r2.verdict === "refused")
                 return { allow: false, response: this.refuse(req, "The Hub ended this session (signed out everywhere, or access changed).") };
-            // §14: a change of ticks reaches the module here, within 15 minutes - §18: and so does the Apps button's list
+            // §14: a change of ticks reaches the module here, within 15 minutes - §18: and so does the Apps button's list -
+            // H07: and so does a store taken away (or given)
             if (r2.verdict === "ok")
-                s = { ...s, checkedAt: nowMs, ...(r2.pages ? { pages: r2.pages } : {}), ...(r2.apps ? { apps: r2.apps } : {}) };
+                s = { ...s, checkedAt: nowMs, ...(r2.pages ? { pages: r2.pages } : {}), ...(r2.apps ? { apps: r2.apps } : {}), ...(r2.stores ? { stores: r2.stores } : {}) };
         }
+        // H08: the Hub has not answered for longer than the limit - the module still opens and reads, changes wait
+        const stale = nowMs - s.checkedAt >= (this.cfg.maxStaleMs ?? MAX_STALE_MS);
+        if (stale && !["GET", "HEAD", "OPTIONS"].includes(req.method.toUpperCase()))
+            return { allow: false, response: this.pauseChanges(req) };
         s = { ...s, lastSeen: nowMs };
-        return { allow: true, session: s, setCookie: cookieHeader(await signSession(s, secret), { secure: url.protocol === "https:", maxAgeS: Math.floor((this.cfg.absoluteMs ?? 8 * 3_600_000) / 1000) }) };
+        const setCookie = cookieHeader(await signSession(s, secret), { secure: url.protocol === "https:", maxAgeS: Math.floor((this.cfg.absoluteMs ?? 8 * 3_600_000) / 1000) });
+        return { allow: true, session: stale ? { ...s, stale: true } : s, setCookie };
+    }
+    /** H08: 503 while the Hub has been silent too long - the session stays (nothing is signed out), changes wait. */
+    pauseChanges(req) {
+        const reason = "The Hub has not answered for a while, so changes are paused. You can still look; try again when the Hub is back.";
+        const accept = req.headers.get("accept") ?? "";
+        if (!accept.includes("text/html")) {
+            return new Response(JSON.stringify({ error: "hub_unreachable", reason }), { status: 503, headers: { "Content-Type": "application/json", "Cache-Control": "no-store", "Retry-After": "60" } });
+        }
+        const html = `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Changes paused</title></head><body style="font-family:system-ui,sans-serif;display:grid;place-items:center;min-height:100vh;margin:0"><p style="max-width:440px;text-align:center">${escapeHtml(reason)}</p></body></html>`;
+        return new Response(html, { status: 503, headers: { "Content-Type": "text/html; charset=utf-8", "Cache-Control": "no-store", "Retry-After": "60" } });
     }
     /**
      * §14: may this person read (`"read"`) or change (`"write"`) this page? The owner may do everything.

package/dist/hub-client.d.ts

@@ -19,7 +19,14 @@ export declare function sessionCheckPages(cfg: HubClientConfig, personId: string
     verdict: "ok" | "refused" | "unknown";
     pages?: Pages;
     apps?: HubApp[];
+    stores?: string[];
 }>;
+/**
+ * H09 (0.9.0): spend an entry ticket at the Hub, so it works once across every server of every module (the memory of
+ * one server is not enough on serverless). "first" = this is its first use; "used" = it was used before; "unknown" =
+ * the Hub did not say (the entry is refused - the ticket is a minute old, opening again from the Hub is cheap).
+ */
+export declare function spendTicket(cfg: HubClientConfig, jti: string, exp: number): Promise<"first" | "used" | "unknown">;
 export type BrokerToken = {
     accessToken: string;
     expiresAt: Date;

package/dist/hub-client.js

@@ -50,8 +50,25 @@ export async function sessionCheckPages(cfg, personId, sessionVersion) {
         verdict: "ok",
         ...(r.json.pages === undefined ? {} : { pages: readPages(r.json.pages) }),
         ...(r.json.apps === undefined ? {} : { apps: readApps(r.json.apps) }),
+        // H07 (0.9.0): the person's stores here as the Hub holds them now (absent from a Hub before 0.9.0)
+        ...(Array.isArray(r.json.stores) ? { stores: r.json.stores.filter((s) => typeof s === "string" && /^[a-z]{2}$/.test(s)) } : {}),
     };
 }
+/**
+ * H09 (0.9.0): spend an entry ticket at the Hub, so it works once across every server of every module (the memory of
+ * one server is not enough on serverless). "first" = this is its first use; "used" = it was used before; "unknown" =
+ * the Hub did not say (the entry is refused - the ticket is a minute old, opening again from the Hub is cheap).
+ */
+export async function spendTicket(cfg, jti, exp) {
+    const r = await post(cfg, "/api/hub/ticket-used", { jti, exp });
+    if (r.status !== 200 || !r.json)
+        return "unknown";
+    if (r.json.first === true)
+        return "first";
+    if (r.json.first === false)
+        return "used";
+    return "unknown";
+}
 /** 7.3: the store's token from the Hub, cached until an hour before it expires. */
 export function tokenBroker(cfg) {
     const cache = new Map();

package/dist/index.d.ts

@@ -2,8 +2,8 @@ export { Guard, openingPage, type GuardConfig, type CheckResult } from "./guard.
 export { appMenu, readApps, APP_ID_RE, type AppMenuItem, type HubApp } from "./apps.js";
 export { pageAllowed, pageAccess, pagesFingerprint, readPages, PAGE_KEY_RE, type PageAccess, type PageDef, type Pages } from "./pages.js";
 export { verifyTicket, JtiMemory, TICKET_ISSUER, TICKET_TTL_S, TICKET_ALG, type TicketClaims, type VerifyResult } from "./ticket.js";
-export { readSession, signSession, cookieHeader, clearCookieHeader, cookieValue, SESSION_COOKIE, IDLE_MS, ABSOLUTE_MS, RECHECK_MS, type ModuleSession } from "./session.js";
-export { sessionCheck, sessionCheckPages, tokenBroker, audit, alert, verifyHubCall, manifestResponse, healthResponse, healthAnswer, activityResponse, readActivityQuery, cleanActivityLine, ACTIVITY_AT_RE, ACTIVITY_ID_RE, ACTIVITY_MAX_LIMIT, type ActivityLine, type ActivityQuery, type HubClientConfig, type HubCallCheck, type AnswerConfig, type BrokerToken, type Connection, } from "./hub-client.js";
+export { readSession, signSession, cookieHeader, clearCookieHeader, cookieValue, SESSION_COOKIE, IDLE_MS, ABSOLUTE_MS, RECHECK_MS, MAX_STALE_MS, type ModuleSession } from "./session.js";
+export { sessionCheck, sessionCheckPages, spendTicket, tokenBroker, audit, alert, verifyHubCall, manifestResponse, healthResponse, healthAnswer, activityResponse, readActivityQuery, cleanActivityLine, ACTIVITY_AT_RE, ACTIVITY_ID_RE, ACTIVITY_MAX_LIMIT, type ActivityLine, type ActivityQuery, type HubClientConfig, type HubCallCheck, type AnswerConfig, type BrokerToken, type Connection, } from "./hub-client.js";
 export { checkCloudflareAccess } from "./cf-access.js";
 export { verifyRelay, RELAY_HEADERS, RELAY_MAX_AGE_S, type RelayCheck } from "./relay.js";
 export { verifyStationCall, stationRefusal, stationJson, STATION_ID_RE, STATION_NAME_MAX, type StationCheck, type StationAnswer, type StationOrder, type StationItem, type PackAnswer, } from "./station.js";

package/dist/index.js

@@ -2,8 +2,8 @@ export { Guard, openingPage } from "./guard.js";
 export { appMenu, readApps, APP_ID_RE } from "./apps.js";
 export { pageAllowed, pageAccess, pagesFingerprint, readPages, PAGE_KEY_RE } from "./pages.js";
 export { verifyTicket, JtiMemory, TICKET_ISSUER, TICKET_TTL_S, TICKET_ALG } from "./ticket.js";
-export { readSession, signSession, cookieHeader, clearCookieHeader, cookieValue, SESSION_COOKIE, IDLE_MS, ABSOLUTE_MS, RECHECK_MS } from "./session.js";
-export { sessionCheck, sessionCheckPages, tokenBroker, audit, alert, verifyHubCall, manifestResponse, healthResponse, healthAnswer, activityResponse, readActivityQuery, cleanActivityLine, ACTIVITY_AT_RE, ACTIVITY_ID_RE, ACTIVITY_MAX_LIMIT, } from "./hub-client.js";
+export { readSession, signSession, cookieHeader, clearCookieHeader, cookieValue, SESSION_COOKIE, IDLE_MS, ABSOLUTE_MS, RECHECK_MS, MAX_STALE_MS } from "./session.js";
+export { sessionCheck, sessionCheckPages, spendTicket, tokenBroker, audit, alert, verifyHubCall, manifestResponse, healthResponse, healthAnswer, activityResponse, readActivityQuery, cleanActivityLine, ACTIVITY_AT_RE, ACTIVITY_ID_RE, ACTIVITY_MAX_LIMIT, } from "./hub-client.js";
 export { checkCloudflareAccess } from "./cf-access.js";
 export { verifyRelay, RELAY_HEADERS, RELAY_MAX_AGE_S } from "./relay.js";
 export { verifyStationCall, stationRefusal, stationJson, STATION_ID_RE, STATION_NAME_MAX, } from "./station.js";

package/dist/pages.d.ts

@@ -26,6 +26,7 @@ export declare function pageAccess(session: {
 export declare function pageAllowed(session: {
     role: string;
     pages?: Pages;
+    stale?: boolean;
 }, key: string, need: "read" | "write"): boolean;
 /** The fingerprint of a page list - the same one the Hub computes for the list it read (§14.5). */
 export declare function pagesFingerprint(pages: PageDef[]): Promise<string>;

package/dist/pages.js

@@ -22,6 +22,9 @@ export function pageAccess(session, key) {
  * change (`"write"`) this page? Ask it on the server - hiding a button is not enough (§14.3).
  */
 export function pageAllowed(session, key, need) {
+    // H08 (0.9.0): while the Hub has not answered for 180 minutes nobody changes anything - the owner included
+    if (need === "write" && session.stale)
+        return false;
     const a = pageAccess(session, key);
     return need === "read" ? a === "r" || a === "w" : a === "w";
 }

package/dist/session.d.ts

@@ -4,6 +4,12 @@ export declare const SESSION_COOKIE = "t3b_module_session";
 export declare const IDLE_MS: number;
 export declare const ABSOLUTE_MS: number;
 export declare const RECHECK_MS: number;
+/**
+ * H08 (0.9.0): how long a module keeps allowing changes while the Hub does not answer its check - the same 180 minutes
+ * as the idle rule. Past it the module still opens and reads, but every change waits until the Hub answers again (a
+ * person the owner removed during an outage cannot keep changing things for the session's whole 8 hours).
+ */
+export declare const MAX_STALE_MS: number;
 export type ModuleSession = {
     personId: string;
     name: string;
@@ -17,6 +23,8 @@ export type ModuleSession = {
     pages?: Pages;
     /** §18 (0.8.0): the apps this person may open (the Apps button), from the pass, refreshed by every 15-minute check */
     apps?: HubApp[];
+    /** H08 (0.9.0): set by `check` (never stored) when the Hub has not answered for MAX_STALE_MS - no changes */
+    stale?: boolean;
 };
 export declare function signSession(s: ModuleSession, secret: string): Promise<string>;
 export declare function readSession(cookie: string | undefined | null, secret: string, now?: number, opts?: {

package/dist/session.js

@@ -7,8 +7,16 @@ export const SESSION_COOKIE = "t3b_module_session";
 export const IDLE_MS = 180 * 60_000;
 export const ABSOLUTE_MS = 8 * 3_600_000;
 export const RECHECK_MS = 15 * 60_000;
+/**
+ * H08 (0.9.0): how long a module keeps allowing changes while the Hub does not answer its check - the same 180 minutes
+ * as the idle rule. Past it the module still opens and reads, but every change waits until the Hub answers again (a
+ * person the owner removed during an outage cannot keep changing things for the session's whole 8 hours).
+ */
+export const MAX_STALE_MS = 180 * 60_000;
 export async function signSession(s, secret) {
-    const body = b64urlEncode(utf8(JSON.stringify(s)));
+    const { stale: _stale, ...kept } = s; // computed on every request, never carried in the cookie
+    void _stale;
+    const body = b64urlEncode(utf8(JSON.stringify(kept)));
     const mac = b64urlEncode(await hmacSha256(secret, body));
     return `${body}.${mac}`;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@t3b/hub-guard",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "The3Beez Hub guard: a module opens only by a Hub-signed ticket and refuses everything else. No key from the Hub: towards the Hub the app shows its own Vercel ID; from the Hub it accepts only what is signed by the key the Hub publishes. Entry route, refusal page, module session, idle rule, 15-minute re-check, Cloudflare Access proof, broker and audit clients, manifest and health answers for the Hub only. Web Crypto only: runs in Node 20+ and in edge runtimes.",
   "license": "UNLICENSED",
   "type": "module",