@t3b/hub-guard 0.8.0 → 0.10.0

package/README.md

@@ -269,16 +269,58 @@ const lines = guard.appMenu(session);
 - A session opened before 0.8.0 (or by an older Hub) has no list: the button then holds the Hub line only.
 - `appMenu(session, { hubUrl, moduleId })` is the same without a Guard; `readApps(raw)` reads a list defensively.
 
+## Memos: the bell and the window (0.10.0, WORKFLOWS §22)
+
+HR holds the memos; the Hub carries them. Your app shows a bell on its top bar and one page, `/memos`, that every
+signed-in person has (no page tick - a person's own memos are theirs). Nothing is kept in your app: the page asks the
+Hub (your Vercel ID, the person from your own session), the Hub asks HR with its signed pass and passes the answer back.
+
+```ts
+// the bell, in your top bar (the number comes with the pass and every 15-minute check)
+const bell = guard.memoBell(session, "ar"); // { count: 2, href: "/memos", label: "التعاميم: 2 تعاميم بانتظارك" }
+
+// GET /memos (and /memos?id=<memo>) - the list, and one memo opened (HR marks it read)
+const data = await guard.memoData(session, { memoId: url.searchParams.get("id"), lang: "ar" });
+const html = memoFragment(data, { lang: "ar", basePath: "/memos", backHref: "/" }); // put it inside your own shell
+
+// POST /memos/:id/accept and POST /memos/:id/reply (form field `text`) - then 303 back to /memos?id=<memo>
+const r = await guard.memoAct(session, "accept", id, { lang: "ar" });
+const r2 = await guard.memoAct(session, "reply", id, { text, lang: "ar" });
+```
+
+- Texts in Arabic and English (`MEMO_TEXTS`); pick the language your app speaks (the till Arabic, International
+  Orders English). Latin digits; times on Kuwait's clock (`memoWhen`).
+- `memoFragment` escapes every word HR sent and draws with the design system's classes; or draw your own page from
+  `data` (`MemoView`). `readMemo` / `readMemos` cut HR's words to shape.
+- The Hub silent → `{ ok: false, reason: "hr_silent" }` with the text to show; the bell keeps its last number.
+- A session from a Hub before §22 carries no number: the bell shows nothing.
+- **HR's own door** (the module that holds the memos): `verifyMemosCall(req, rawBody, { moduleId, keys })` checks the
+  Hub's pass - person, app and action named, bound to the exact bytes - and `memosRefusal(reason)` answers a refusal;
+  name the door in the manifest as `memos` and in `healthResponse(..., { memos })`.
+
 ## 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.10.0** (WORKFLOWS §22, D-088): memos - the pass's and the 15-minute check's `memos` (the waiting number) is kept in
+  the session (`session.memos`, `readMemoCount`); `guard.memoBell`, `guard.memoData`, `guard.memoAct`, `memoFragment`,
+  `MEMO_TEXTS` (Arabic and English), `memosCall`; for the module that holds the memos `verifyMemosCall`, `memosRefusal`
+  and `healthResponse(..., { memos })`; a manifest page may be `everyone: true` (Hub §22.7) and `pagesFingerprint` adds
+  that word only for such a page. **The Hub must be on its §22 release before an app takes 0.10.0.** Nothing else
+  changes; a module on 0.9.0 keeps working (its sessions simply carry no number).
+- **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

@@ -1,5 +1,6 @@
 import type { JWTVerifyGetKey } from "jose";
 import { type AppMenuItem } from "./apps.js";
+import { type MemoActResult, type MemoBell, type MemoData, type MemoLang } from "./memos.js";
 import { type TokenProvider } from "./identity.js";
 import { type ModuleSession } from "./session.js";
 export type GuardConfig = {
@@ -27,6 +28,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 +65,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.
@@ -69,6 +76,18 @@ export declare class Guard {
     refusePage(req: Request, what?: string): Response;
     /** §18 (0.8.0): the Apps button's lines for this session - the Hub first, then every app this person may open. */
     appMenu(session: ModuleSession): AppMenuItem[];
+    /** §22.4 (0.10.0): the bell for the top bar - the waiting number and the window's address. */
+    memoBell(session: ModuleSession, lang?: MemoLang, basePath?: string): MemoBell;
+    /** §22.4 (0.10.0): the memo window's data for this session - the list, and one memo open (marked read) when `memoId` is given. */
+    memoData(session: ModuleSession, opts?: {
+        memoId?: string | null;
+        lang?: MemoLang;
+    }): Promise<MemoData>;
+    /** §22.4 (0.10.0): accept or reply, for this session's person only; answers what the page should do next. */
+    memoAct(session: ModuleSession, action: "accept" | "reply", memoId: string, opts?: {
+        text?: string;
+        lang?: MemoLang;
+    }): Promise<MemoActResult>;
     /** Signs out of the module only (the Hub session is untouched). */
     signOut(): Response;
 }

package/dist/guard.js

@@ -1,9 +1,10 @@
 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 { memoAct, memoBell, memoData } from "./memos.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,8 +60,16 @@ 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 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, memos: v.claims.memos };
         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);
@@ -97,12 +106,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) - §22.2: and the bell's number
             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 } : {}), ...(r2.memos === undefined ? {} : { memos: r2.memos }) };
         }
+        // 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.
@@ -125,6 +150,18 @@ export class Guard {
     appMenu(session) {
         return appMenu(session, { hubUrl: this.cfg.hubUrl, moduleId: this.cfg.moduleId });
     }
+    /** §22.4 (0.10.0): the bell for the top bar - the waiting number and the window's address. */
+    memoBell(session, lang = "en", basePath = "/memos") {
+        return memoBell(session, lang, basePath);
+    }
+    /** §22.4 (0.10.0): the memo window's data for this session - the list, and one memo open (marked read) when `memoId` is given. */
+    memoData(session, opts = {}) {
+        return memoData(this.hubClient(), session, opts);
+    }
+    /** §22.4 (0.10.0): accept or reply, for this session's person only; answers what the page should do next. */
+    memoAct(session, action, memoId, opts = {}) {
+        return memoAct(this.hubClient(), session, action, memoId, opts);
+    }
     /** 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() } });

package/dist/hub-client.d.ts

@@ -19,7 +19,25 @@ export declare function sessionCheckPages(cfg: HubClientConfig, personId: string
     verdict: "ok" | "refused" | "unknown";
     pages?: Pages;
     apps?: HubApp[];
+    stores?: string[];
+    memos?: number;
 }>;
+/** §22.3 (0.10.0): the memo window's one call to the Hub - list, open, accept, reply - for the session's person. */
+export declare function memosCall(cfg: HubClientConfig, action: "list" | "open" | "accept" | "reply", body: {
+    personId: string;
+    memoId?: string;
+    text?: string;
+    lang?: "ar" | "en";
+}): Promise<{
+    status: number;
+    json: Record<string, unknown> | null;
+}>;
+/**
+ * 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;
@@ -74,7 +92,7 @@ export type HubCallCheck = {
 export declare function verifyHubCall(req: Request, opts: {
     moduleId: string;
     keys: JWTVerifyGetKey;
-    use: "manifest" | "health" | "activity";
+    use: "manifest" | "health" | "activity" | "memos";
     now?: Date;
     environment?: string;
 }): Promise<HubCallCheck>;
@@ -97,7 +115,7 @@ 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[], pages?: PageDef[], activity?: string, station?: string): Promise<{
+export declare function healthAnswer(check: () => Promise<Connection[]> | Connection[], pages?: PageDef[], activity?: string, station?: string, memos?: string): Promise<{
     status: number;
     body: {
         ok: boolean;
@@ -107,6 +125,7 @@ export declare function healthAnswer(check: () => Promise<Connection[]> | Connec
         pages?: string;
         activity?: string;
         station?: string;
+        memos?: string;
     };
 }>;
 /** 8b.4: the health answer, in full, only to the Hub; anyone else gets 401 and nothing. */
@@ -114,6 +133,7 @@ export declare function healthResponse(req: Request, check: () => Promise<Connec
     pages?: PageDef[];
     activity?: string;
     station?: string;
+    memos?: string;
 }): Promise<Response>;
 /** One change, worded by the app for the Hub's Activity page (English, like the Hub). */
 export type ActivityLine = {

package/dist/hub-client.js

@@ -1,6 +1,7 @@
 import { jwtVerify } from "jose";
 import { readApps } from "./apps.js";
 import { pagesFingerprint, readPages } from "./pages.js";
+import { readMemoCount } from "./ticket.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) {
@@ -50,8 +51,31 @@ 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)) } : {}),
+        // §22.2 (0.10.0): the person's waiting memos, for the bell (absent from a Hub before §22)
+        ...(typeof r.json.memos === "number" ? { memos: readMemoCount(r.json.memos) } : {}),
     };
 }
+/** §22.3 (0.10.0): the memo window's one call to the Hub - list, open, accept, reply - for the session's person. */
+export async function memosCall(cfg, action, body) {
+    return post(cfg, `/api/hub/memos/${action}`, body);
+}
+/**
+ * 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();
@@ -132,7 +156,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, pages, activity, station) {
+export async function healthAnswer(check, pages, activity, station, memos) {
     let connections;
     try {
         connections = await check();
@@ -154,6 +178,8 @@ export async function healthAnswer(check, pages, activity, station) {
             ...(activity ? { activity } : {}),
             // §17: the app's packing-station door; when it differs from the one the Hub holds, the Hub reads the manifest again
             ...(station ? { station } : {}),
+            // §22.3 (0.10.0): the memos door of the app that holds the memos (HR); likewise
+            ...(memos ? { memos } : {}),
         },
     };
 }
@@ -162,7 +188,7 @@ 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, cfg.pages, cfg.activity, cfg.station);
+    const a = await healthAnswer(check, cfg.pages, cfg.activity, cfg.station, cfg.memos);
     return jsonResponse(a.status, a.body);
 }
 export const ACTIVITY_AT_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,6})?Z$/;

package/dist/index.d.ts

@@ -1,9 +1,10 @@
 export { Guard, openingPage, type GuardConfig, type CheckResult } from "./guard.js";
 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 { verifyTicket, JtiMemory, readMemoCount, TICKET_ISSUER, TICKET_TTL_S, TICKET_ALG, type TicketClaims, type VerifyResult } from "./ticket.js";
+export { memoBell, memoData, memoAct, memoFragment, memoText, memoWhen, readMemo, readMemos, verifyMemosCall, memosRefusal, MEMO_TEXTS, MEMO_ID_RE, REPLY_MAX, type MemoLang, type MemoTextKey, type MemoView, type MemoReply, type MemoBell, type MemoData, type MemoActResult, type MemoFragmentOptions, type MemosCallCheck, } from "./memos.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, memosCall, 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

@@ -1,9 +1,10 @@
 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 { verifyTicket, JtiMemory, readMemoCount, TICKET_ISSUER, TICKET_TTL_S, TICKET_ALG } from "./ticket.js";
+export { memoBell, memoData, memoAct, memoFragment, memoText, memoWhen, readMemo, readMemos, verifyMemosCall, memosRefusal, MEMO_TEXTS, MEMO_ID_RE, REPLY_MAX, } from "./memos.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, memosCall, 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/memos.d.ts

@@ -0,0 +1,172 @@
+import { type JWTVerifyGetKey } from "jose";
+import { type HubClientConfig } from "./hub-client.js";
+export type MemoLang = "ar" | "en";
+export declare const MEMO_ID_RE: RegExp;
+export declare const REPLY_MAX = 2000;
+/** Every word on the window, in both languages (the owner's rule: Arabic and English everywhere). */
+export declare const MEMO_TEXTS: {
+    readonly en: {
+        readonly title: "Memos";
+        readonly bell: "Memos";
+        readonly waiting: "memos waiting";
+        readonly empty: "No memos.";
+        readonly from: "From";
+        readonly sent: "Sent";
+        readonly state_new: "New";
+        readonly state_read: "Read";
+        readonly state_accepted: "Accepted";
+        readonly state_withdrawn: "Withdrawn";
+        readonly accept: "I have read and accept";
+        readonly accepted_on: "Accepted";
+        readonly accept_note: "One press, recorded with the time and this app.";
+        readonly replies: "Your replies";
+        readonly replies_note: "Only the people ticked for Replies read them.";
+        readonly reply: "Reply";
+        readonly reply_placeholder: "Write a reply…";
+        readonly send_reply: "Send reply";
+        readonly answer: "Answer";
+        readonly open: "Open";
+        readonly back: "Back to the list";
+        readonly hr_silent: "HR did not answer. The bell keeps its last number - try again in a minute.";
+        readonly not_yours: "That memo is not yours.";
+        readonly too_long: "A reply is 1 to 2,000 characters.";
+        readonly new_answer: "New answer";
+    };
+    readonly ar: {
+        readonly title: "التعاميم";
+        readonly bell: "التعاميم";
+        readonly waiting: "تعاميم بانتظارك";
+        readonly empty: "لا توجد تعاميم.";
+        readonly from: "من";
+        readonly sent: "أُرسل";
+        readonly state_new: "جديد";
+        readonly state_read: "مقروء";
+        readonly state_accepted: "تمت الموافقة";
+        readonly state_withdrawn: "مسحوب";
+        readonly accept: "قرأت وأوافق";
+        readonly accepted_on: "تمت الموافقة";
+        readonly accept_note: "ضغطة واحدة، تُسجَّل مع الوقت واسم هذا التطبيق.";
+        readonly replies: "ردودك";
+        readonly replies_note: "يقرأها فقط من لديهم صلاحية الردود.";
+        readonly reply: "رد";
+        readonly reply_placeholder: "اكتب رداً…";
+        readonly send_reply: "إرسال الرد";
+        readonly answer: "الرد";
+        readonly open: "فتح";
+        readonly back: "عودة إلى القائمة";
+        readonly hr_silent: "لم يرد نظام الموارد البشرية. يبقى الجرس على آخر رقم - حاول بعد دقيقة.";
+        readonly not_yours: "هذا التعميم ليس لك.";
+        readonly too_long: "الرد من حرف واحد إلى 2,000 حرف.";
+        readonly new_answer: "رد جديد";
+    };
+};
+export type MemoTextKey = keyof (typeof MEMO_TEXTS)["en"];
+export declare function memoText(lang: MemoLang, key: MemoTextKey): string;
+export type MemoReply = {
+    id: string;
+    text: string;
+    at: string;
+    answer: {
+        text: string;
+        at: string;
+        by: string;
+    } | null;
+};
+export type MemoView = {
+    id: string;
+    title: string;
+    text: string | null;
+    from: string;
+    sent_at: string;
+    state: "new" | "read" | "accepted" | "withdrawn";
+    read_at: string | null;
+    accepted_at: string | null;
+    replies: MemoReply[];
+    unseen_answer: boolean;
+};
+export declare function readMemo(raw: unknown): MemoView | null;
+export declare function readMemos(raw: unknown): MemoView[];
+export type MemoBell = {
+    count: number;
+    href: string;
+    label: string;
+};
+/** The bell for the top bar: the waiting number from the pass or the last check, and the window's address. */
+export declare function memoBell(session: {
+    memos?: number;
+}, lang?: MemoLang, basePath?: string): MemoBell;
+export type MemoData = {
+    ok: true;
+    memos: MemoView[];
+    open: MemoView | null;
+    waiting: number | null;
+} | {
+    ok: false;
+    reason: "hr_silent" | "refused" | "not_yours";
+    message: string;
+};
+/** The person's list, and one memo opened (HR marks it read). Only for the session's person - the app never passes another id. */
+export declare function memoData(cfg: HubClientConfig, session: {
+    personId: string;
+    memos?: number;
+}, opts?: {
+    memoId?: string | null;
+    lang?: MemoLang;
+}): Promise<MemoData>;
+export type MemoActResult = {
+    ok: true;
+    memo: MemoView | null;
+    waiting: number | null;
+} | {
+    ok: false;
+    reason: "bad_request" | "hr_silent" | "refused";
+    message: string;
+};
+/** Accept, or reply: for the session's person only. The caller then shows the memo again (a 303 to its address). */
+export declare function memoAct(cfg: HubClientConfig, session: {
+    personId: string;
+}, action: "accept" | "reply", memoId: string, opts?: {
+    text?: string;
+    lang?: MemoLang;
+}): Promise<MemoActResult>;
+/** A time as the window shows it: Kuwait's clock, Latin digits, `2026-10-12 10:30`. */
+export declare function memoWhen(iso: string): string;
+export type MemoFragmentOptions = {
+    lang?: MemoLang;
+    /** the window's address on this app (links and forms) */
+    basePath?: string;
+    /** a link back to the app's own page */
+    backHref?: string | null;
+    /** a message to show on top (an error from `memoAct`) */
+    notice?: string | null;
+};
+/**
+ * The window as HTML the app puts inside its own shell: the list on the start side, the open memo (or the list only)
+ * with the accept button, the person's replies and the reply box. Every HR word is escaped. Forms: POST
+ * `<basePath>/<id>/accept` and `<basePath>/<id>/reply` (field `text`); a list line links `<basePath>?id=<id>`.
+ */
+export declare function memoFragment(data: MemoData, opts?: MemoFragmentOptions): string;
+export type MemosCallCheck = {
+    ok: true;
+    person: string;
+    app: string;
+    action: "list" | "open" | "accept" | "reply" | "delivered";
+} | {
+    ok: false;
+    reason: "missing" | "bad_signature" | "expired" | "wrong_module" | "wrong_use" | "wrong_environment" | "body_changed";
+};
+/**
+ * Is this the Hub asking the memos door? `body` is the request's raw bytes (read with `await req.arrayBuffer()` before
+ * parsing - the pass covers the exact bytes). The pass names the person, the app the person is in and the action; the
+ * body carries the same and the action's fields.
+ */
+export declare function verifyMemosCall(req: Request, body: Uint8Array | string, opts: {
+    moduleId: string;
+    keys: JWTVerifyGetKey;
+    now?: Date;
+    environment?: string;
+}): Promise<MemosCallCheck>;
+/** The refusal HR's memos door answers with: 401 and only the reason word. */
+export declare function memosRefusal(reason: Extract<MemosCallCheck, {
+    ok: false;
+}>["reason"]): Response;

package/dist/memos.js

@@ -0,0 +1,251 @@
+import { jwtVerify } from "jose";
+import { memosCall } from "./hub-client.js";
+import { HUB_ISSUER, TYP } from "./identity.js";
+import { b64urlEncode, constantTimeEqual, sha256 } from "./webcrypto.js";
+export const MEMO_ID_RE = /^[A-Za-z0-9_-]{1,64}$/;
+export const REPLY_MAX = 2_000;
+/** Every word on the window, in both languages (the owner's rule: Arabic and English everywhere). */
+export const MEMO_TEXTS = {
+    en: {
+        title: "Memos",
+        bell: "Memos",
+        waiting: "memos waiting",
+        empty: "No memos.",
+        from: "From",
+        sent: "Sent",
+        state_new: "New",
+        state_read: "Read",
+        state_accepted: "Accepted",
+        state_withdrawn: "Withdrawn",
+        accept: "I have read and accept",
+        accepted_on: "Accepted",
+        accept_note: "One press, recorded with the time and this app.",
+        replies: "Your replies",
+        replies_note: "Only the people ticked for Replies read them.",
+        reply: "Reply",
+        reply_placeholder: "Write a reply…",
+        send_reply: "Send reply",
+        answer: "Answer",
+        open: "Open",
+        back: "Back to the list",
+        hr_silent: "HR did not answer. The bell keeps its last number - try again in a minute.",
+        not_yours: "That memo is not yours.",
+        too_long: "A reply is 1 to 2,000 characters.",
+        new_answer: "New answer",
+    },
+    ar: {
+        title: "التعاميم",
+        bell: "التعاميم",
+        waiting: "تعاميم بانتظارك",
+        empty: "لا توجد تعاميم.",
+        from: "من",
+        sent: "أُرسل",
+        state_new: "جديد",
+        state_read: "مقروء",
+        state_accepted: "تمت الموافقة",
+        state_withdrawn: "مسحوب",
+        accept: "قرأت وأوافق",
+        accepted_on: "تمت الموافقة",
+        accept_note: "ضغطة واحدة، تُسجَّل مع الوقت واسم هذا التطبيق.",
+        replies: "ردودك",
+        replies_note: "يقرأها فقط من لديهم صلاحية الردود.",
+        reply: "رد",
+        reply_placeholder: "اكتب رداً…",
+        send_reply: "إرسال الرد",
+        answer: "الرد",
+        open: "فتح",
+        back: "عودة إلى القائمة",
+        hr_silent: "لم يرد نظام الموارد البشرية. يبقى الجرس على آخر رقم - حاول بعد دقيقة.",
+        not_yours: "هذا التعميم ليس لك.",
+        too_long: "الرد من حرف واحد إلى 2,000 حرف.",
+        new_answer: "رد جديد",
+    },
+};
+export function memoText(lang, key) {
+    return MEMO_TEXTS[lang === "ar" ? "ar" : "en"][key];
+}
+const WHEN_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,6})?Z$/;
+const clip = (v, n) => (typeof v === "string" && v.trim() ? v.replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g, " ").trim().slice(0, n) : null);
+const when = (v) => (typeof v === "string" && WHEN_RE.test(v) ? v : null);
+export function readMemo(raw) {
+    const o = (raw ?? {});
+    if (typeof o.id !== "string" || !MEMO_ID_RE.test(o.id))
+        return null;
+    const title = clip(o.title, 120);
+    const from = clip(o.from, 80);
+    const sent = when(o.sent_at);
+    const state = o.state === "new" || o.state === "read" || o.state === "accepted" || o.state === "withdrawn" ? o.state : null;
+    if (!title || !from || !sent || !state)
+        return null;
+    const replies = (Array.isArray(o.replies) ? o.replies : [])
+        .slice(0, 50)
+        .flatMap((r) => {
+        const x = (r ?? {});
+        const id = typeof x.id === "string" && MEMO_ID_RE.test(x.id) ? x.id : null;
+        const text = clip(x.text, REPLY_MAX);
+        const at = when(x.at);
+        if (!id || !text || !at)
+            return [];
+        const a = (x.answer ?? null);
+        const answer = a && clip(a.text, REPLY_MAX) && when(a.at) && clip(a.by, 80) ? { text: clip(a.text, REPLY_MAX), at: when(a.at), by: clip(a.by, 80) } : null;
+        return [{ id, text, at, answer }];
+    });
+    return { id: o.id, title, text: clip(o.text, 4_000), from, sent_at: sent, state, read_at: when(o.read_at), accepted_at: when(o.accepted_at), replies, unseen_answer: o.unseen_answer === true };
+}
+export function readMemos(raw) {
+    return (Array.isArray(raw) ? raw : []).slice(0, 200).map(readMemo).filter((m) => m !== null);
+}
+/** The bell for the top bar: the waiting number from the pass or the last check, and the window's address. */
+export function memoBell(session, lang = "en", basePath = "/memos") {
+    const count = typeof session.memos === "number" && session.memos > 0 ? Math.min(Math.floor(session.memos), 9_999) : 0;
+    return { count, href: basePath, label: count > 0 ? `${memoText(lang, "bell")}: ${count} ${memoText(lang, "waiting")}` : memoText(lang, "bell") };
+}
+/** The person's list, and one memo opened (HR marks it read). Only for the session's person - the app never passes another id. */
+export async function memoData(cfg, session, opts = {}) {
+    const lang = opts.lang ?? "en";
+    const list = await memosCall(cfg, "list", { personId: session.personId, lang });
+    if (list.status === 0 || list.status >= 500 || !list.json)
+        return { ok: false, reason: "hr_silent", message: memoText(lang, "hr_silent") };
+    if (list.json.ok !== true)
+        return { ok: false, reason: "refused", message: String(list.json.message ?? memoText(lang, "hr_silent")) };
+    const memos = readMemos(list.json.memos);
+    let waiting = typeof list.json.waiting === "number" ? list.json.waiting : null;
+    let open = null;
+    const id = typeof opts.memoId === "string" && MEMO_ID_RE.test(opts.memoId) ? opts.memoId : null;
+    if (id) {
+        if (!memos.some((m) => m.id === id))
+            return { ok: false, reason: "not_yours", message: memoText(lang, "not_yours") };
+        const r = await memosCall(cfg, "open", { personId: session.personId, memoId: id, lang });
+        if (r.status === 0 || r.status >= 500 || !r.json)
+            return { ok: false, reason: "hr_silent", message: memoText(lang, "hr_silent") };
+        if (r.json.ok === true) {
+            open = readMemo(r.json.memo);
+            if (typeof r.json.waiting === "number")
+                waiting = r.json.waiting;
+        }
+    }
+    return { ok: true, memos: open ? memos.map((m) => (m.id === open.id ? open : m)) : memos, open, waiting };
+}
+/** Accept, or reply: for the session's person only. The caller then shows the memo again (a 303 to its address). */
+export async function memoAct(cfg, session, action, memoId, opts = {}) {
+    const lang = opts.lang ?? "en";
+    if (!MEMO_ID_RE.test(memoId))
+        return { ok: false, reason: "bad_request", message: memoText(lang, "not_yours") };
+    const text = action === "reply" ? (opts.text ?? "").replace(/\r\n/g, "\n").trim() : undefined;
+    if (action === "reply" && (!text || text.length > REPLY_MAX))
+        return { ok: false, reason: "bad_request", message: memoText(lang, "too_long") };
+    const r = await memosCall(cfg, action, { personId: session.personId, memoId, lang, ...(text ? { text } : {}) });
+    if (r.status === 0 || r.status >= 500 || !r.json)
+        return { ok: false, reason: "hr_silent", message: memoText(lang, "hr_silent") };
+    if (r.json.ok !== true)
+        return { ok: false, reason: "refused", message: String(r.json.message ?? memoText(lang, "hr_silent")) };
+    return { ok: true, memo: readMemo(r.json.memo), waiting: typeof r.json.waiting === "number" ? r.json.waiting : null };
+}
+// ---- the window's markup (the same page in every app, the design system's classes, inline styles for its layout) ----
+function esc(s) {
+    return s.replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
+}
+/** A time as the window shows it: Kuwait's clock, Latin digits, `2026-10-12 10:30`. */
+export function memoWhen(iso) {
+    const d = new Date(iso);
+    if (Number.isNaN(d.getTime()))
+        return iso;
+    const p = new Intl.DateTimeFormat("en-GB", { timeZone: "Asia/Kuwait", year: "numeric", month: "2-digit", day: "2-digit", hour: "2-digit", minute: "2-digit", hourCycle: "h23" }).formatToParts(d);
+    const g = (t) => p.find((x) => x.type === t)?.value ?? "";
+    return `${g("year")}-${g("month")}-${g("day")} ${g("hour")}:${g("minute")}`;
+}
+function stateBadge(m, lang) {
+    const tone = m.state === "accepted" ? "badge-success" : m.state === "new" ? "badge-warning" : m.state === "withdrawn" ? "badge-muted" : "badge-info";
+    const key = `state_${m.state}`;
+    const extra = m.unseen_answer ? ` <span class="badge badge-honey">${esc(memoText(lang, "new_answer"))}</span>` : "";
+    return `<span class="badge ${tone}">${esc(memoText(lang, key))}</span>${extra}`;
+}
+/**
+ * The window as HTML the app puts inside its own shell: the list on the start side, the open memo (or the list only)
+ * with the accept button, the person's replies and the reply box. Every HR word is escaped. Forms: POST
+ * `<basePath>/<id>/accept` and `<basePath>/<id>/reply` (field `text`); a list line links `<basePath>?id=<id>`.
+ */
+export function memoFragment(data, opts = {}) {
+    const lang = opts.lang ?? "en";
+    const t = (k) => esc(memoText(lang, k));
+    const base = opts.basePath ?? "/memos";
+    const head = `<div class="page-head"><div class="row"><div class="title"><h1>${t("title")}</h1></div>${opts.backHref ? `<div class="actions"><a class="btn btn-ghost" href="${esc(opts.backHref)}">${t("back")}</a></div>` : ""}</div></div>`;
+    const notice = opts.notice ? `<div class="alert warning" role="status" style="margin-block-end: var(--s-4)"><div class="txt">${esc(opts.notice)}</div></div>` : "";
+    if (!data.ok)
+        return `${head}${notice}<div class="alert warning" role="alert"><div class="txt">${esc(data.message)}</div></div>`;
+    if (data.memos.length === 0)
+        return `${head}${notice}<div class="card"><p class="help-2" style="margin: 0">${t("empty")}</p></div>`;
+    const list = data.memos
+        .map((m) => {
+        const current = data.open?.id === m.id;
+        return `<a href="${esc(`${base}?id=${encodeURIComponent(m.id)}`)}" ${current ? 'aria-current="true"' : ""} style="display: grid; gap: 4px; padding: var(--s-3) var(--s-4); border-block-end: 1px solid var(--line); text-decoration: none; color: inherit;${current ? " background: var(--paper-2); box-shadow: inset 3px 0 0 var(--ink);" : ""}"><span style="display: flex; align-items: center; gap: var(--s-2); font-weight: 600; font-size: var(--fs-body-sm)"><span style="flex: 1; min-inline-size: 0">${esc(m.title)}</span>${stateBadge(m, lang)}</span><span class="help-2">${esc(m.from)} · ${esc(memoWhen(m.sent_at))}</span></a>`;
+    })
+        .join("");
+    const o = data.open;
+    const opened = !o
+        ? ""
+        : `<div class="card"><div class="card-head"><h2 class="card-title">${esc(o.title)}</h2><div class="help-2" style="display: flex; gap: var(--s-3); flex-wrap: wrap"><span>${t("from")} ${esc(o.from)}</span><span>${t("sent")} ${esc(memoWhen(o.sent_at))}</span></div></div>` +
+            `<p style="white-space: pre-line; line-height: 1.7; margin: 0 0 var(--s-4)">${esc(o.text ?? "")}</p>` +
+            (o.state === "accepted"
+                ? `<div class="alert success" role="status"><div class="txt"><b>${t("accepted_on")} · ${esc(memoText(lang === "ar" ? "en" : "ar", "accept"))}</b>${o.accepted_at ? esc(memoWhen(o.accepted_at)) : ""}</div></div>`
+                : o.state === "withdrawn"
+                    ? `<div class="alert info" role="status"><div class="txt">${t("state_withdrawn")}</div></div>`
+                    : `<form method="post" action="${esc(`${base}/${encodeURIComponent(o.id)}/accept`)}" style="display: flex; gap: var(--s-3); align-items: center; flex-wrap: wrap; padding-block: var(--s-3); border-block: 1px solid var(--line)"><button type="submit" class="btn btn-primary" style="font-size: var(--fs-body); padding-block: var(--s-3)">${t("accept")} · ${esc(memoText(lang === "ar" ? "en" : "ar", "accept"))}</button><span class="help-2">${t("accept_note")}</span></form>`) +
+            `<div style="display: grid; gap: var(--s-3); margin-block-start: var(--s-4)"><div class="section-head"><h3 style="margin: 0">${t("replies")} <span class="help-2" style="font-weight: 400">· ${t("replies_note")}</span></h3></div>` +
+            o.replies
+                .map((r) => `<div style="border-inline-start: 3px solid var(--line); padding-inline-start: var(--s-3); display: grid; gap: 4px; font-size: var(--fs-body-sm)"><span class="help-2">${esc(memoWhen(r.at))}</span><span style="white-space: pre-line">${esc(r.text)}</span></div>` +
+                (r.answer ? `<div style="border-inline-start: 3px solid var(--honey, #EDA94D); margin-inline-start: var(--s-5); padding-inline-start: var(--s-3); display: grid; gap: 4px; font-size: var(--fs-body-sm)"><span class="help-2">${t("answer")} · ${esc(r.answer.by)} · ${esc(memoWhen(r.answer.at))}</span><span style="white-space: pre-line">${esc(r.answer.text)}</span></div>` : ""))
+                .join("") +
+            (o.state === "withdrawn"
+                ? ""
+                : `<form method="post" action="${esc(`${base}/${encodeURIComponent(o.id)}/reply`)}" style="display: grid; gap: var(--s-2)"><div class="field"><label class="label" for="memo-reply">${t("reply")}</label><textarea id="memo-reply" name="text" class="textarea" rows="2" maxlength="${REPLY_MAX}" required placeholder="${t("reply_placeholder")}"></textarea></div><div style="display: flex; justify-content: flex-end"><button type="submit" class="btn btn-secondary">${t("send_reply")}</button></div></form>`) +
+            `</div></div>`;
+    // side by side on a desk (the list at most 360 px wide), one under the other on a phone - a wrapping row, no media query
+    return `${head}${notice}<div style="display: flex; flex-wrap: wrap; gap: var(--s-4); align-items: flex-start"><div class="card" role="list" style="padding: 0; overflow: hidden; flex: 1 1 280px; min-inline-size: 0;${o ? " max-inline-size: 360px;" : ""}">${list}</div>${o ? opened.replace('<div class="card">', '<div class="card" style="flex: 999 1 420px; min-inline-size: 0">') : ""}</div>`;
+}
+const PERSON_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const APP_RE = /^[a-z][a-z0-9-]{1,30}$/;
+const ACTIONS = ["list", "open", "accept", "reply", "delivered"];
+/**
+ * Is this the Hub asking the memos door? `body` is the request's raw bytes (read with `await req.arrayBuffer()` before
+ * parsing - the pass covers the exact bytes). The pass names the person, the app the person is in and the action; the
+ * body carries the same and the action's fields.
+ */
+export async function verifyMemosCall(req, body, opts) {
+    const auth = req.headers.get("authorization") ?? "";
+    const token = auth.startsWith("Bearer ") ? auth.slice(7).trim() : "";
+    if (!token || token.length > 4096)
+        return { ok: false, reason: "missing" };
+    let p;
+    try {
+        ({ payload: p } = await jwtVerify(token, opts.keys, { issuer: HUB_ISSUER, audience: opts.moduleId, algorithms: ["EdDSA"], typ: TYP.call, currentDate: opts.now, clockTolerance: 5, maxTokenAge: 65 }));
+    }
+    catch (e) {
+        const code = e.code ?? "";
+        if (code === "ERR_JWT_EXPIRED")
+            return { ok: false, reason: "expired" };
+        if (code === "ERR_JWT_CLAIM_VALIDATION_FAILED" && /"aud"/.test(e.message))
+            return { ok: false, reason: "wrong_module" };
+        if (code === "ERR_JWT_CLAIM_VALIDATION_FAILED")
+            return { ok: false, reason: "expired" };
+        return { ok: false, reason: "bad_signature" };
+    }
+    if (p.use !== "memos")
+        return { ok: false, reason: "wrong_use" };
+    if (opts.environment && p.env !== opts.environment)
+        return { ok: false, reason: "wrong_environment" };
+    const person = typeof p.person === "string" && PERSON_RE.test(p.person) ? p.person : null;
+    const app = typeof p.app === "string" && APP_RE.test(p.app) ? p.app : null;
+    const action = ACTIONS.find((a) => a === p.action) ?? null;
+    if (!person || !app || !action)
+        return { ok: false, reason: "bad_signature" };
+    const want = typeof p.body_sha256 === "string" ? p.body_sha256 : "";
+    const bytes = typeof body === "string" ? new TextEncoder().encode(body) : body;
+    if (!want || !constantTimeEqual(b64urlEncode(await sha256(bytes)), want))
+        return { ok: false, reason: "body_changed" };
+    return { ok: true, person, app, action };
+}
+/** The refusal HR's memos door answers with: 401 and only the reason word. */
+export function memosRefusal(reason) {
+    return new Response(JSON.stringify({ error: "hub_only", reason }), { status: 401, headers: { "Content-Type": "application/json", "Cache-Control": "no-store" } });
+}

package/dist/pages.d.ts

@@ -1,6 +1,10 @@
 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. */
+/**
+ * One page as a module lists it in its manifest. `write`: what Write allows, or null when there is nothing to change.
+ * `everyone` (0.10.0, Hub §22.7): every person has Read on it without a tick - for a page that only ever shows a
+ * person their own rows (HR's My profile); the Hub grants it by itself.
+ */
 export type PageDef = {
     key: string;
     group?: string | null;
@@ -10,6 +14,7 @@ export type PageDef = {
     };
     read: string;
     write?: string | null;
+    everyone?: boolean;
 };
 export declare const PAGE_KEY_RE: RegExp;
 /** A pass's or check's `pages`, read defensively: anything malformed is dropped, never widened. */
@@ -26,6 +31,10 @@ 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). */
+/**
+ * The fingerprint of a page list - the same one the Hub computes for the list it read (§14.5). An everyone's page adds
+ * one more word; a list without one fingerprints exactly as before 0.10.0.
+ */
 export declare function pagesFingerprint(pages: PageDef[]): Promise<string>;

package/dist/pages.js

@@ -22,11 +22,17 @@ 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";
 }
-/** The fingerprint of a page list - the same one the Hub computes for the list it read (§14.5). */
+/**
+ * The fingerprint of a page list - the same one the Hub computes for the list it read (§14.5). An everyone's page adds
+ * one more word; a list without one fingerprints exactly as before 0.10.0.
+ */
 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]));
+    const text = JSON.stringify(pages.map((p) => [p.key, p.group ?? null, p.name.en, p.name.ar, p.read, p.write ?? null, ...(p.everyone ? ["everyone"] : [])]));
     return b64urlEncode(await sha256(utf8(text))).slice(0, 16);
 }

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,10 @@ 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[];
+    /** §22.2 (0.10.0): the person's waiting memos (the bell), from the pass, refreshed by every 15-minute check; absent from a Hub before §22 */
+    memos?: number;
+    /** 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/dist/ticket.d.ts

@@ -18,7 +18,11 @@ export type TicketClaims = {
     pages: Pages;
     /** §18 (0.8.0): the apps this person may open; `[]` from a Hub before §18 */
     apps: HubApp[];
+    /** §22.2 (0.10.0): the person's waiting memos (the bell); 0 from a Hub before §22 */
+    memos: number;
 };
+/** A waiting number as the Hub sends it: a whole number from 0 to 9,999; anything else is 0. */
+export declare function readMemoCount(raw: unknown): number;
 export type VerifyResult = {
     ok: true;
     claims: TicketClaims;

package/dist/ticket.js

@@ -9,6 +9,10 @@ import { HUB_ISSUER, TYP } from "./identity.js";
 export const TICKET_ISSUER = HUB_ISSUER;
 export const TICKET_TTL_S = 60;
 export const TICKET_ALG = "EdDSA";
+/** A waiting number as the Hub sends it: a whole number from 0 to 9,999; anything else is 0. */
+export function readMemoCount(raw) {
+    return typeof raw === "number" && Number.isInteger(raw) && raw >= 0 ? Math.min(raw, 9_999) : 0;
+}
 /** Seen ticket ids, kept for two minutes (C-4). One instance's memory; a replay across instances is stopped by the 60-s life. */
 export class JtiMemory {
     ttlMs;
@@ -61,6 +65,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, pages: readPages(p.pages), apps: readApps(p.apps) },
+        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), apps: readApps(p.apps), memos: readMemoCount(p.memos) },
     };
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@t3b/hub-guard",
-  "version": "0.8.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.",
+  "version": "0.10.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, the memo bell and window (0.10.0). Web Crypto only: runs in Node 20+ and in edge runtimes.",
   "license": "UNLICENSED",
   "type": "module",
   "main": "./dist/index.js",