@t3b/hub-guard 0.2.0 → 0.4.0

package/README.md

@@ -74,6 +74,22 @@ await audit(cfg, { action: "shopify.write", target: "kw", detail: { what: "produ
 Without a Vercel ID (OIDC switched off, or a local run without `VERCEL_OIDC_TOKEN`) nothing is
 sent and the answer says why (`no_vercel_id`).
 
+## Telling the Hub something is wrong (0.3.0)
+
+An app never emails anyone itself: it tells the Hub, and the Hub emails the people chosen in
+Settings → Alerts — one email, at most one reminder a day while it lasts, one "back to normal".
+
+```ts
+import { alert } from "@t3b/hub-guard";
+const cfg = { hubUrl: process.env.T3B_HUB_URL ?? "https://t3b-hub.com" };
+await alert(cfg, { key: "rates-follow", ok: false, title: "MyFatoorah rates not followed for 30 hours", detail: "the 06:00 run failed: timeout", fix: "Nothing to do if tomorrow's run works." });
+await alert(cfg, { key: "rates-follow", ok: true });   // it is over: one "back to normal" if you were told
+```
+
+`key`: lower-case letters, digits and `._:-`, up to 80 — the app's own name for the problem.
+`title` up to 120 characters, `detail` 500, `fix` 300, `store` a store key. No secrets, tokens
+or customer data in any of them. At most 120 reports an hour per app.
+
 ## Shopify's events (through the Hub)
 
 The module never holds the Shopify app secret. Shopify sends events to the Hub; the Hub checks
@@ -131,9 +147,44 @@ import { guard } from "@/lib/guard";
 export const GET = (req: Request) => guard.enter(req);
 ```
 
+## Pages: who may read or change what (0.4.0, WORKFLOWS §14)
+
+The owner ticks **Read** or **Write** per page per person in the Hub (Settings → Staff). The Hub's pass and
+its 15-minute check carry the person's pages in this module; the guard keeps them in the session.
+
+1. **List your pages in the manifest** — one entry per page (a separate line for an action that needs its own
+   switch, e.g. clearing cash). A module that lists none opens for the owner only.
+
+```ts
+const PAGES = [
+  { key: "deliveries", group: "Daily work", name: { en: "Deliveries", ar: "التوصيلات" }, read: "orders, invoices", write: "assign drivers, WhatsApp" },
+  { key: "driver-tracking", group: "Daily work", name: { en: "Driver tracking", ar: "تتبع السائقين" }, read: "positions", write: null },
+];
+// manifest: { ..., pages: PAGES }   health: healthResponse(req, check, { ...cfg, pages: PAGES })
+```
+
+   The health answer then carries the list's fingerprint; when you add, remove or reword a page, the Hub reads
+   the manifest again by itself. New pages arrive closed for everyone but the owner.
+
+2. **Ask on the server, for every page and every action** — hiding a button is not enough:
+
+```ts
+const r = await guard.check(req);            // as before
+if (!r.allow) return r.response;
+if (!guard.allows(r.session, "deliveries", "read")) return guard.refusePage(req, "Deliveries");
+// in an action:
+if (!guard.allows(r.session, "deliveries", "write")) return guard.refusePage(req, "Deliveries");
+```
+
+   `refusePage` answers 403 ("You don't have access to …" for browsers, `{"error":"no_access"}` for APIs) and
+   keeps the session. The owner may do everything; `pageAllowed(session, key, need)` is the same check without a Guard.
+
+3. **Show only what may be used** — build the menu from `pageAccess(session, key)` and switch off buttons on a
+   Read-only page.
+
 ## 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 sends to the page.
+- `/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 15 minutes, 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.
 - Open paths (`/hub/enter`, `/api/hub/manifest`, `/api/hub/health` 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.
@@ -141,6 +192,8 @@ export const GET = (req: Request) => guard.enter(req);
 
 ## Changes
 
+- **0.4.0** (WORKFLOWS §14): page access — the pass's `pages` in the session, refreshed at every 15-minute check (`sessionCheckPages`); `guard.allows()`, `guard.refusePage()`, `pageAllowed`, `pageAccess`, `readPages`; `healthResponse(..., { pages })` sends the page list's fingerprint (`pagesFingerprint`). `enter()` answers an "Opening …" page instead of a 303 (`appName`, `landing` options; `openingPage` exported). A module on 0.3.x keeps working, but the Hub opens it for the owner only until it lists its pages.
+- **0.3.0** (WORKFLOWS 9.3): `alert()` — report a problem to the Hub, or say it is over.
 - **0.2.0** (8b): no module key and no pasted Hub public key. Hub → module: tokens signed by the Hub's key published at `/api/hub/jwks` (`verifyTicket`, `verifyRelay`, `verifyHubCall`, `manifestResponse`, `healthResponse`). Module → Hub: the app's own Vercel ID (`tokenBroker`, `audit`, `sessionCheck`). Removed: `signedManifest`, `relaySignature`, `importPublicKey`, the `moduleKey` / `hubPublicKeys` settings. `Guard` takes `sessionSecret`.
 - **0.1.1**: `enter()` answers with an absolute Location (B-016).
 - **0.1.0**: first publish, Web Crypto build.

package/dist/guard.d.ts

@@ -15,6 +15,10 @@ export type GuardConfig = {
     environment?: string;
     /** the refusal page's link back */
     hubHomeUrl?: string;
+    /** 0.4.0: the module's name on the "Opening …" page shown while the session starts */
+    appName?: string;
+    /** 0.4.0: where the pass's page lands on this module (e.g. "/" -> "/app"); default: the page itself */
+    landing?: (path: string) => string;
     /** paths that are machine doors with their own locks (webhooks, crons, health, manifest, the enter route) - never a session */
     openPaths?: (string | RegExp)[];
     cloudflare?: {
@@ -45,10 +49,25 @@ export declare class Guard {
     isOpenPath(pathname: string): boolean;
     /** The refusal (board 11): a plain page for browsers, JSON for API routes. */
     refuse(req: Request, reason: string, status?: number): Response;
-    /** /hub/enter?ticket=… : verify, open the module session, send to the page (303). */
+    /**
+     * /hub/enter?ticket=… : verify, open the module session, then a short "Opening …" page that moves on
+     * to the pass's page (0.4.0; 303 before). A browser drops a SameSite=Strict cookie set on a redirect
+     * that ends a navigation begun on another site (the Hub), so the first page after a 303 arrived
+     * without the session and was refused; an own-page step makes the next request same-site. Learnt on
+     * Delivery, 2026-09-29.
+     */
     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>;
+    /**
+     * §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.
+     */
+    allows(session: ModuleSession, pageKey: string, need: "read" | "write"): boolean;
+    /** §14: "You don't have access to this page" - 403; the session stays (other pages still open). */
+    refusePage(req: Request, what?: string): Response;
     /** Signs out of the module only (the Hub session is untouched). */
     signOut(): Response;
 }
+/** 0.4.0: the step between the Hub's pass and the module's page (see `enter`). No script: a meta refresh and a link. */
+export declare function openingPage(target: string, appName: string): string;

package/dist/guard.js

@@ -1,5 +1,6 @@
 import { checkCloudflareAccess } from "./cf-access.js";
-import { sessionCheck } from "./hub-client.js";
+import { sessionCheckPages } 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 { JtiMemory, verifyTicket } from "./ticket.js";
@@ -39,7 +40,13 @@ export class Guard {
         const html = `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Open this from The3Beez</title><style>body{margin:0;font-family:system-ui,-apple-system,sans-serif;background:#F6F5F3;color:#231F20;display:flex;align-items:center;justify-content:center;min-height:100vh}.card{background:#fff;border:1px solid #E7E5E2;border-radius:12px;padding:40px;max-width:440px;text-align:center}h1{font-size:22px;margin:0 0 12px}p{color:#6B6866;line-height:1.5;margin:0 0 24px}a{display:inline-block;background:#231F20;color:#fff;text-decoration:none;padding:14px 26px;border-radius:12px;font-size:13px;letter-spacing:.08em;text-transform:uppercase;font-weight:600}</style></head><body><div class="card"><h1>Open this from The3Beez</h1><p>This app opens only from the Hub. ${escapeHtml(reason)}</p><a href="${escapeAttr(home)}">Go to the Hub</a></div></body></html>`;
         return new Response(html, { status, headers: { "Content-Type": "text/html; charset=utf-8", "Cache-Control": "no-store", "Set-Cookie": clearCookieHeader() } });
     }
-    /** /hub/enter?ticket=… : verify, open the module session, send to the page (303). */
+    /**
+     * /hub/enter?ticket=… : verify, open the module session, then a short "Opening …" page that moves on
+     * to the pass's page (0.4.0; 303 before). A browser drops a SameSite=Strict cookie set on a redirect
+     * that ends a navigation begun on another site (the Hub), so the first page after a 303 arrived
+     * without the session and was refused; an own-page step makes the next request same-site. Learnt on
+     * Delivery, 2026-09-29.
+     */
     async enter(req) {
         const url = new URL(req.url);
         const cf = await checkCloudflareAccess(req.headers, this.cfg.cloudflare ?? {});
@@ -52,10 +59,22 @@ export class Guard {
             return this.refuse(req, words[v.reason] ?? "No valid ticket.");
         }
         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 };
-        const target = new URL(v.claims.path, url.origin);
-        // Absolute: Next.js middleware refuses a relative redirect ("Invalid URL", B-016); any client accepts this.
-        return new Response(null, { status: 303, headers: { Location: target.toString(), "Set-Cookie": cookieHeader(await signSession(session, await this.secretP), { secure: url.protocol === "https:", maxAgeS: Math.floor((this.cfg.absoluteMs ?? 8 * 3_600_000) / 1000) }), "Cache-Control": "no-store" } });
+        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 };
+        const landed = new URL(this.cfg.landing ? this.cfg.landing(v.claims.path) : v.claims.path, url.origin);
+        // never off this module's own address, whatever `landing` returns
+        const target = landed.origin === url.origin ? landed : new URL("/", url.origin);
+        const cookie = cookieHeader(await signSession(session, await this.secretP), { secure: url.protocol === "https:", maxAgeS: Math.floor((this.cfg.absoluteMs ?? 8 * 3_600_000) / 1000) });
+        return new Response(openingPage(target.toString(), this.cfg.appName ?? "the app"), {
+            status: 200,
+            headers: {
+                "Content-Type": "text/html; charset=utf-8",
+                "Cache-Control": "no-store",
+                "Set-Cookie": cookie,
+                "Content-Security-Policy": "default-src 'none'; style-src 'unsafe-inline'; base-uri 'none'; frame-ancestors 'none'; form-action 'none'",
+                "Referrer-Policy": "no-referrer",
+                "X-Content-Type-Options": "nosniff",
+            },
+        });
     }
     /** Every other request: open path → allow; else the session must stand, be fresh, and pass the 15-minute Hub check. */
     async check(req) {
@@ -74,20 +93,43 @@ export class Guard {
         }
         let s = r.session;
         if (nowMs - s.checkedAt >= RECHECK_MS) {
-            const verdict = await sessionCheck(this.hubClient(), s.personId, s.sv);
-            if (verdict === "refused")
+            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).") };
-            if (verdict === "ok")
-                s = { ...s, checkedAt: nowMs };
+            // §14: a change of ticks reaches the module here, within 15 minutes
+            if (r2.verdict === "ok")
+                s = { ...s, checkedAt: nowMs, ...(r2.pages ? { pages: r2.pages } : {}) };
         }
         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) }) };
     }
+    /**
+     * §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.
+     */
+    allows(session, pageKey, need) {
+        return pageAllowed(session, pageKey, need);
+    }
+    /** §14: "You don't have access to this page" - 403; the session stays (other pages still open). */
+    refusePage(req, what = "this page") {
+        const accept = req.headers.get("accept") ?? "";
+        if (!accept.includes("text/html")) {
+            return new Response(JSON.stringify({ error: "no_access", page: what }), { status: 403, headers: { "Content-Type": "application/json", "Cache-Control": "no-store" } });
+        }
+        const home = this.cfg.hubHomeUrl ?? this.cfg.hubUrl;
+        const html = `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>No access</title><style>body{margin:0;font-family:system-ui,-apple-system,sans-serif;background:#F6F5F3;color:#231F20;display:flex;align-items:center;justify-content:center;min-height:100vh}.card{background:#fff;border:1px solid #E7E5E2;border-radius:12px;padding:40px;max-width:440px;text-align:center}h1{font-size:22px;margin:0 0 12px}p{color:#6B6866;line-height:1.5;margin:0 0 24px}a{display:inline-block;background:#231F20;color:#fff;text-decoration:none;padding:14px 26px;border-radius:12px;font-size:13px;letter-spacing:.08em;text-transform:uppercase;font-weight:600}</style></head><body><div class="card"><h1>You don't have access to ${escapeHtml(what)}</h1><p>The owner gives access in the Hub: Settings → Staff.</p><a href="${escapeAttr(home)}">Go to the Hub</a></div></body></html>`;
+        return new Response(html, { status: 403, headers: { "Content-Type": "text/html; charset=utf-8", "Cache-Control": "no-store" } });
+    }
     /** Signs out of the module only (the Hub session is untouched). */
     signOut() {
         return new Response(null, { status: 303, headers: { Location: this.cfg.hubHomeUrl ?? this.cfg.hubUrl, "Set-Cookie": clearCookieHeader() } });
     }
 }
+/** 0.4.0: the step between the Hub's pass and the module's page (see `enter`). No script: a meta refresh and a link. */
+export function openingPage(target, appName) {
+    const t = escapeAttr(target);
+    return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><meta http-equiv="refresh" content="0;url=${t}"><title>Opening ${escapeHtml(appName)}</title></head><body style="font-family:system-ui,sans-serif;display:grid;place-items:center;min-height:100vh;margin:0"><p>Opening ${escapeHtml(appName)}… <a href="${t}">Continue</a></p></body></html>`;
+}
 function escapeHtml(s) {
     return s.replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
 }

package/dist/hub-client.d.ts

@@ -1,4 +1,5 @@
 import { type JWTVerifyGetKey } from "jose";
+import { type PageDef, type Pages } from "./pages.js";
 import { type TokenProvider } from "./identity.js";
 export type HubClientConfig = {
     hubUrl: string;
@@ -9,6 +10,11 @@ export type HubClientConfig = {
 };
 /** 2.4: does this person's Hub session still stand? `unknown` when the Hub did not answer (the module keeps the session until the next check). */
 export declare function sessionCheck(cfg: HubClientConfig, personId: string, sessionVersion: number): Promise<"ok" | "refused" | "unknown">;
+/** §14 (0.4.0): the same check, with the person's pages as the Hub holds them now (absent from a Hub before §14). */
+export declare function sessionCheckPages(cfg: HubClientConfig, personId: string, sessionVersion: number): Promise<{
+    verdict: "ok" | "refused" | "unknown";
+    pages?: Pages;
+}>;
 export type BrokerToken = {
     accessToken: string;
     expiresAt: Date;
@@ -33,6 +39,26 @@ export declare function audit(cfg: HubClientConfig, line: {
     target?: string;
     detail?: Record<string, unknown>;
 }): Promise<boolean>;
+/**
+ * 9.3: tell the Hub a problem started (`ok: false`, with a title) or ended (`ok: true`), under a
+ * key of the app's own ("rates-follow", "feeds"). The Hub emails under its no-flood rule; the app
+ * never emails anyone itself. Never throws.
+ */
+export declare function alert(cfg: HubClientConfig, a: {
+    key: string;
+    ok: boolean;
+    title?: string;
+    detail?: string;
+    fix?: string;
+    store?: string;
+}): Promise<{
+    ok: true;
+    state: string;
+} | {
+    ok: false;
+    status: number;
+    error: string;
+}>;
 export type HubCallCheck = {
     ok: true;
 } | {
@@ -66,14 +92,17 @@ export type Connection = {
     store?: string | null;
 };
 /** 8.4 / 7.6: the health answer's shape. `ok` is false when any connection is red; the Hub shows each connection as its own line. */
-export declare function healthAnswer(check: () => Promise<Connection[]> | Connection[]): Promise<{
+export declare function healthAnswer(check: () => Promise<Connection[]> | Connection[], pages?: PageDef[]): Promise<{
     status: number;
     body: {
         ok: boolean;
         reason: string | null;
         connections: Connection[];
         checked_at: string;
+        pages?: string;
     };
 }>;
 /** 8b.4: the health answer, in full, only to the Hub; anyone else gets 401 and nothing. */
-export declare function healthResponse(req: Request, check: () => Promise<Connection[]> | Connection[], cfg: Omit<AnswerConfig, "token">): Promise<Response>;
+export declare function healthResponse(req: Request, check: () => Promise<Connection[]> | Connection[], cfg: Omit<AnswerConfig, "token"> & {
+    pages?: PageDef[];
+}): Promise<Response>;

package/dist/hub-client.js

@@ -1,4 +1,5 @@
 import { jwtVerify } from "jose";
+import { pagesFingerprint, readPages } from "./pages.js";
 import { APP_ID_HEADER, HUB_ISSUER, ownVercelToken, TYP, tokenFrom } from "./identity.js";
 const NO_ID = "This app has no Vercel ID to show the Hub - Vercel → the project → Settings → Security → Secure backend access (OIDC) must be on.";
 async function post(cfg, path, body) {
@@ -32,10 +33,16 @@ async function post(cfg, path, body) {
 }
 /** 2.4: does this person's Hub session still stand? `unknown` when the Hub did not answer (the module keeps the session until the next check). */
 export async function sessionCheck(cfg, personId, sessionVersion) {
+    return (await sessionCheckPages(cfg, personId, sessionVersion)).verdict;
+}
+/** §14 (0.4.0): the same check, with the person's pages as the Hub holds them now (absent from a Hub before §14). */
+export async function sessionCheckPages(cfg, personId, sessionVersion) {
     const r = await post(cfg, "/api/hub/session-check", { personId, sessionVersion });
     if (r.status === 0 || r.status >= 500)
-        return "unknown";
-    return r.json?.ok === true ? "ok" : "refused";
+        return { verdict: "unknown" };
+    if (r.json?.ok !== true)
+        return { verdict: "refused" };
+    return r.json.pages === undefined ? { verdict: "ok" } : { verdict: "ok", pages: readPages(r.json.pages) };
 }
 /** 7.3: the store's token from the Hub, cached until an hour before it expires. */
 export function tokenBroker(cfg) {
@@ -63,6 +70,17 @@ export async function audit(cfg, line) {
     const r = await post(cfg, "/api/hub/audit", line);
     return r.status === 200 || r.status === 201;
 }
+/**
+ * 9.3: tell the Hub a problem started (`ok: false`, with a title) or ended (`ok: true`), under a
+ * key of the app's own ("rates-follow", "feeds"). The Hub emails under its no-flood rule; the app
+ * never emails anyone itself. Never throws.
+ */
+export async function alert(cfg, a) {
+    const r = await post(cfg, "/api/hub/alerts", a);
+    if (r.status === 202)
+        return { ok: true, state: String(r.json?.state ?? "") };
+    return { ok: false, status: r.status, error: String(r.json?.field ?? r.json?.error ?? "no_answer") };
+}
 /** Is this request the Hub's own, for this module and this purpose? (`Authorization: Bearer <pass>`) */
 export async function verifyHubCall(req, opts) {
     const auth = req.headers.get("authorization") ?? "";
@@ -106,7 +124,7 @@ export async function manifestResponse(req, manifest, cfg) {
     return jsonResponse(200, manifest, { [APP_ID_HEADER]: own });
 }
 /** 8.4 / 7.6: the health answer's shape. `ok` is false when any connection is red; the Hub shows each connection as its own line. */
-export async function healthAnswer(check) {
+export async function healthAnswer(check, pages) {
     let connections;
     try {
         connections = await check();
@@ -117,7 +135,14 @@ export async function healthAnswer(check) {
     const red = connections.filter((c) => !c.ok);
     return {
         status: 200,
-        body: { ok: red.length === 0, reason: red.length ? red.map((c) => `${c.name}: ${c.reason ?? "not ok"}`).join("; ").slice(0, 200) : null, connections, checked_at: new Date().toISOString() },
+        body: {
+            ok: red.length === 0,
+            reason: red.length ? red.map((c) => `${c.name}: ${c.reason ?? "not ok"}`).join("; ").slice(0, 200) : null,
+            connections,
+            checked_at: new Date().toISOString(),
+            // §14.5: the page list's fingerprint - when it changes, the Hub reads the manifest again by itself
+            ...(pages ? { pages: await pagesFingerprint(pages) } : {}),
+        },
     };
 }
 /** 8b.4: the health answer, in full, only to the Hub; anyone else gets 401 and nothing. */
@@ -125,6 +150,6 @@ export async function healthResponse(req, check, cfg) {
     const v = await verifyHubCall(req, { moduleId: cfg.moduleId, keys: cfg.keys, use: "health", now: cfg.now, environment: cfg.environment });
     if (!v.ok)
         return jsonResponse(401, { error: "hub_only", reason: v.reason });
-    const a = await healthAnswer(check);
+    const a = await healthAnswer(check, cfg.pages);
     return jsonResponse(a.status, a.body);
 }

package/dist/index.d.ts

@@ -1,7 +1,8 @@
-export { Guard, type GuardConfig, type CheckResult } from "./guard.js";
+export { Guard, openingPage, type GuardConfig, type CheckResult } from "./guard.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, tokenBroker, audit, verifyHubCall, manifestResponse, healthResponse, healthAnswer, type HubClientConfig, type HubCallCheck, type AnswerConfig, type BrokerToken, type Connection, } from "./hub-client.js";
+export { sessionCheck, sessionCheckPages, tokenBroker, audit, alert, verifyHubCall, manifestResponse, healthResponse, healthAnswer, 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 { ownVercelToken, ownEnvironment, hubKeys, APP_ID_HEADER, OIDC_HEADER, type TokenProvider } from "./identity.js";

package/dist/index.js

@@ -1,7 +1,8 @@
-export { Guard } from "./guard.js";
+export { Guard, openingPage } from "./guard.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, tokenBroker, audit, verifyHubCall, manifestResponse, healthResponse, healthAnswer, } from "./hub-client.js";
+export { sessionCheck, sessionCheckPages, tokenBroker, audit, alert, verifyHubCall, manifestResponse, healthResponse, healthAnswer, } from "./hub-client.js";
 export { checkCloudflareAccess } from "./cf-access.js";
 export { verifyRelay, RELAY_HEADERS, RELAY_MAX_AGE_S } from "./relay.js";
 export { ownVercelToken, ownEnvironment, hubKeys, APP_ID_HEADER, OIDC_HEADER } from "./identity.js";

package/dist/pages.d.ts

@@ -0,0 +1,31 @@
+export type PageAccess = "r" | "w";
+export type Pages = Record<string, PageAccess>;
+/** One page as a module lists it in its manifest. `write`: what Write allows, or null when there is nothing to change. */
+export type PageDef = {
+    key: string;
+    group?: string | null;
+    name: {
+        en: string;
+        ar: string;
+    };
+    read: string;
+    write?: string | null;
+};
+export declare const PAGE_KEY_RE: RegExp;
+/** A pass's or check's `pages`, read defensively: anything malformed is dropped, never widened. */
+export declare function readPages(raw: unknown): Pages;
+/** What a person may do on one page: "w", "r" or null. The owner always "w". */
+export declare function pageAccess(session: {
+    role: string;
+    pages?: Pages;
+}, key: string): PageAccess | null;
+/**
+ * The one question a module asks on every page and every action: may this person read (`"read"`) or
+ * change (`"write"`) this page? Ask it on the server - hiding a button is not enough (§14.3).
+ */
+export declare function pageAllowed(session: {
+    role: string;
+    pages?: Pages;
+}, 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

@@ -0,0 +1,32 @@
+import { b64urlEncode, sha256, utf8 } from "./webcrypto.js";
+export const PAGE_KEY_RE = /^[a-z][a-z0-9-]{1,39}$/;
+/** A pass's or check's `pages`, read defensively: anything malformed is dropped, never widened. */
+export function readPages(raw) {
+    const out = {};
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return out;
+    for (const [k, v] of Object.entries(raw)) {
+        if (PAGE_KEY_RE.test(k) && (v === "r" || v === "w"))
+            out[k] = v;
+    }
+    return out;
+}
+/** What a person may do on one page: "w", "r" or null. The owner always "w". */
+export function pageAccess(session, key) {
+    if (session.role === "owner")
+        return "w";
+    return session.pages?.[key] ?? null;
+}
+/**
+ * The one question a module asks on every page and every action: may this person read (`"read"`) or
+ * change (`"write"`) this page? Ask it on the server - hiding a button is not enough (§14.3).
+ */
+export function pageAllowed(session, key, need) {
+    const a = pageAccess(session, key);
+    return need === "read" ? a === "r" || a === "w" : a === "w";
+}
+/** The fingerprint of a page list - the same one the Hub computes for the list it read (§14.5). */
+export async function pagesFingerprint(pages) {
+    const text = JSON.stringify(pages.map((p) => [p.key, p.group ?? null, p.name.en, p.name.ar, p.read, p.write ?? null]));
+    return b64urlEncode(await sha256(utf8(text))).slice(0, 16);
+}

package/dist/session.d.ts

@@ -1,3 +1,4 @@
+import type { Pages } from "./pages.js";
 export declare const SESSION_COOKIE = "t3b_module_session";
 export declare const IDLE_MS: number;
 export declare const ABSOLUTE_MS: number;
@@ -11,6 +12,8 @@ export type ModuleSession = {
     iat: number;
     lastSeen: number;
     checkedAt: number;
+    /** §14 (0.4.0): the person's pages here, from the pass, refreshed by every 15-minute check */
+    pages?: Pages;
 };
 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/ticket.d.ts

@@ -1,3 +1,4 @@
+import { type Pages } from "./pages.js";
 import { type JWTVerifyGetKey } from "jose";
 export declare const TICKET_ISSUER = "t3b-hub";
 export declare const TICKET_TTL_S = 60;
@@ -12,6 +13,8 @@ export type TicketClaims = {
     sv: number;
     iat: number;
     exp: number;
+    /** §14 (0.4.0): the person's pages in this module; `{}` from a Hub before §14 */
+    pages: Pages;
 };
 export type VerifyResult = {
     ok: true;

package/dist/ticket.js

@@ -1,3 +1,4 @@
+import { readPages } from "./pages.js";
 import { jwtVerify } from "jose";
 import { HUB_ISSUER, TYP } from "./identity.js";
 // SPEC C-4: the entry ticket. EdDSA (Ed25519) JWT signed by the Hub's key; since 0.2.0 (8b) the
@@ -59,6 +60,6 @@ export async function verifyTicket(ticket, opts) {
         return { ok: false, reason: "replayed" };
     return {
         ok: true,
-        claims: { sub: p.sub, jti: p.jti, role: p.role, stores: p.stores.map(String), path: p.path, name: String(p.name ?? ""), sv: Number(p.sv ?? 0), iat: p.iat, exp: p.exp },
+        claims: { sub: p.sub, jti: p.jti, role: p.role, stores: p.stores.map(String), path: p.path, name: String(p.name ?? ""), sv: Number(p.sv ?? 0), iat: p.iat, exp: p.exp, pages: readPages(p.pages) },
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@t3b/hub-guard",
-  "version": "0.2.0",
+  "version": "0.4.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",