@t3b/hub-guard 0.6.0 → 0.8.0

package/README.md

@@ -216,21 +216,76 @@ export async function GET(req: Request) {
    - `at`: ISO 8601 in UTC at your database's full precision (Postgres: `to_char(at at time zone 'UTC',
      'YYYY-MM-DD"T"HH24:MI:SS.US"Z"')`), and compare `before.at` at that same precision - a coarser time skips lines.
    - `person`: the Hub person's id (the pass gave it to you); `actor` instead, for a line no person made
-     ("International Orders, on its own").
+     ("International Orders, on its own"). An app that records people by name reads the Hub's `person_name`
+     from the address to filter (`q.person` is the id).
    - `store`: the Hub's store key; a module serving one store answers nothing when asked for another.
    - The Hub drops a line out of shape (`cleanActivityLine`) and cuts long words: `what` 200, `detail` 400,
      `actor`/`place` 60 characters. It waits 5 seconds; an app that does not answer is named on the page.
 
+## Packing station: pack for the Hub's station (0.7.0, WORKFLOWS §17)
+
+The packer scans an invoice at the Packing app; the Hub has already checked that station's key, then asks every app
+that names a station door, with its own 60-second pass for `station`. Your app answers whether the order is its own and
+what to scan; on the last scan the Hub sends the scans and your app packs exactly as its own station does.
+
+1. **Name the door** in the manifest and in the health answer (`station: "/api/hub/station"`, and
+   `healthResponse(req, check, { ...cfg, station: "/api/hub/station" })`).
+2. **Answer it** - the Hub's pass first, then your own rules:
+
+```ts
+// GET  ?code=<digits from the invoice QR>  ->  { mine:false } | { mine:true, ok:true, order } | { mine:true, ok:false, reason, reason_ar }
+// POST { orderId, scans:[...] }             ->  { ok:true, name } | { ok:false, reason, reason_ar, missing, extra }
+import { verifyStationCall, stationRefusal, stationJson } from "@t3b/hub-guard";
+export async function POST(req: Request) {
+  const raw = new Uint8Array(await req.arrayBuffer());          // the pass covers these exact bytes
+  const v = await verifyStationCall(req, raw, cfg);              // GET: verifyStationCall(req, null, cfg)
+  if (!v.ok) return stationRefusal(v.reason);
+  const body = JSON.parse(new TextDecoder().decode(raw));
+  // ... check every scan again against the order as Shopify has it now, then fulfil; record it under v.station.name
+  return stationJson({ ok: true, name: "#KW1100" });
+}
+```
+
+   - `order.kind`: `"kuwait"` (local delivery - the screen shows the Kuwait flag) or `"international"` (the globe),
+     with `country` `{ code, ar, en }`.
+   - `items[]`: `title` (Arabic), `title_en`, `sku`, `qty`, `barcode`, `image` (Shopify's CDN only), `offer`
+     (`{ title, qty }` from `lineItemGroup` when the line came from a bundle).
+   - `mine:true, ok:false` puts the order aside: say why in the words the manager needs (`reason`, `reason_ar`).
+   - Answer 200 for every case once the pass is good; the Hub waits 5 seconds and treats anything else as no answer.
+
+## Apps button: move between apps (0.8.0, WORKFLOWS §18)
+
+The Hub's pass and its 15-minute check carry the apps this person may open. Show them in ONE button, **Apps
+(التطبيقات)**, in the same place in your top bar, in place of a "Back to the Hub" link:
+
+```ts
+const lines = guard.appMenu(session);
+// [{ id: "hub", nameEn: "The Hub", nameAr: "الـHub", href: "https://t3b-hub.com/home", current: false },
+//  { id: "delivery", nameEn: "Delivery", nameAr: "التوصيل", href: "https://t3b-hub.com/go/delivery", current: true }, ...]
+```
+
+- Each line is a plain link (`href`); the Hub mints the next app's pass and goes straight on. Mark the `current` line,
+  never link it to itself.
+- 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.
+
 ## 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.
 - 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`: the Hub's pass, for this module, for this purpose, from this environment's Hub; a relay also for these exact bytes and at most 5 minutes old; a call at most 60 seconds old.
+- `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.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).
+- **0.7.0** (WORKFLOWS §17): the packing station - `verifyStationCall` checks the Hub's pass for `station` (naming the
+  station; on a pack, bound to the exact body), `stationRefusal`, `stationJson` and the answer types; `healthResponse(...,
+  { station })` names the door so the Hub reads the manifest again by itself. Nothing else changes; a module on 0.6.0 keeps
+  working.
 - **0.6.0** (WORKFLOWS §16): Activity - `activityResponse` answers the module's own change log to the Hub's pass for
   `activity` (`readActivityQuery`, `cleanActivityLine`, `ActivityLine`, `ActivityQuery`); `healthResponse(..., { activity })`
   names the door so the Hub reads the manifest again by itself. Nothing else changes; a module on 0.5.0 keeps working.

package/dist/apps.d.ts

@@ -0,0 +1,28 @@
+/** One app the person may open, as the Hub sends it. */
+export type HubApp = {
+    id: string;
+    nameEn: string;
+    nameAr: string;
+};
+/** One line of the Apps button. `current`: this is the app the person is in. */
+export type AppMenuItem = {
+    id: string;
+    nameEn: string;
+    nameAr: string;
+    href: string;
+    current: boolean;
+};
+export declare const APP_ID_RE: RegExp;
+/** A pass's or check's `apps`, read defensively: anything malformed is dropped, never widened. */
+export declare function readApps(raw: unknown): HubApp[];
+/**
+ * The Apps button's lines for this person, in order: the Hub first (its Home), then every app they may open; the app
+ * they are in is marked `current`. A session from a Hub before 0.8.0 carries no list - the button then holds the Hub
+ * only, which is the way back as before.
+ */
+export declare function appMenu(session: {
+    apps?: HubApp[];
+}, cfg: {
+    hubUrl: string;
+    moduleId: string;
+}): AppMenuItem[];

package/dist/apps.js

@@ -0,0 +1,37 @@
+// WORKFLOWS §18 (0.8.0, D-069): the Apps button. The Hub's pass and its 15-minute check carry the apps this person may
+// open (the same list as the Hub's sidebar); every app shows them in one button in its top bar, with the Hub first and
+// the current app marked. A pick goes to `<hub>/go/<app>`, where the Hub mints that app's pass and goes straight on.
+export const APP_ID_RE = /^[a-z][a-z0-9-]{1,30}$/;
+const MAX_APPS = 30;
+const MAX_NAME = 60;
+/** A pass's or check's `apps`, read defensively: anything malformed is dropped, never widened. */
+export function readApps(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    const seen = new Set();
+    for (const a of raw.slice(0, MAX_APPS)) {
+        if (!a || typeof a !== "object")
+            continue;
+        const { id, nameEn, nameAr } = a;
+        if (typeof id !== "string" || !APP_ID_RE.test(id) || seen.has(id))
+            continue;
+        const en = typeof nameEn === "string" && nameEn.trim() ? nameEn.trim().slice(0, MAX_NAME) : id;
+        const ar = typeof nameAr === "string" && nameAr.trim() ? nameAr.trim().slice(0, MAX_NAME) : en;
+        seen.add(id);
+        out.push({ id, nameEn: en, nameAr: ar });
+    }
+    return out;
+}
+/**
+ * The Apps button's lines for this person, in order: the Hub first (its Home), then every app they may open; the app
+ * they are in is marked `current`. A session from a Hub before 0.8.0 carries no list - the button then holds the Hub
+ * only, which is the way back as before.
+ */
+export function appMenu(session, cfg) {
+    const hub = cfg.hubUrl.replace(/\/$/, "");
+    return [
+        { id: "hub", nameEn: "The Hub", nameAr: "الـHub", href: `${hub}/home`, current: false },
+        ...(session.apps ?? []).map((a) => ({ id: a.id, nameEn: a.nameEn, nameAr: a.nameAr, href: `${hub}/go/${a.id}`, current: a.id === cfg.moduleId })),
+    ];
+}

package/dist/guard.d.ts

@@ -1,4 +1,5 @@
 import type { JWTVerifyGetKey } from "jose";
+import { type AppMenuItem } from "./apps.js";
 import { type TokenProvider } from "./identity.js";
 import { type ModuleSession } from "./session.js";
 export type GuardConfig = {
@@ -66,6 +67,8 @@ export declare class Guard {
     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;
+    /** §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[];
     /** Signs out of the module only (the Hub session is untouched). */
     signOut(): Response;
 }

package/dist/guard.js

@@ -1,3 +1,4 @@
+import { appMenu } from "./apps.js";
 import { checkCloudflareAccess } from "./cf-access.js";
 import { sessionCheckPages } from "./hub-client.js";
 import { pageAllowed } from "./pages.js";
@@ -59,7 +60,7 @@ 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, pages: v.claims.pages };
+        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);
         // never off this module's own address, whatever `landing` returns
         const target = landed.origin === url.origin ? landed : new URL("/", url.origin);
@@ -96,9 +97,9 @@ 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
+            // §14: a change of ticks reaches the module here, within 15 minutes - §18: and so does the Apps button's list
             if (r2.verdict === "ok")
-                s = { ...s, checkedAt: nowMs, ...(r2.pages ? { pages: r2.pages } : {}) };
+                s = { ...s, checkedAt: nowMs, ...(r2.pages ? { pages: r2.pages } : {}), ...(r2.apps ? { apps: r2.apps } : {}) };
         }
         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) }) };
@@ -120,6 +121,10 @@ 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>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" } });
     }
+    /** §18 (0.8.0): the Apps button's lines for this session - the Hub first, then every app this person may open. */
+    appMenu(session) {
+        return appMenu(session, { hubUrl: this.cfg.hubUrl, moduleId: this.cfg.moduleId });
+    }
     /** 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

@@ -1,4 +1,5 @@
 import { type JWTVerifyGetKey } from "jose";
+import { type HubApp } from "./apps.js";
 import { type PageDef, type Pages } from "./pages.js";
 import { type TokenProvider } from "./identity.js";
 export type HubClientConfig = {
@@ -10,10 +11,14 @@ 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). */
+/**
+ * §14 (0.4.0): the same check, with the person's pages as the Hub holds them now (absent from a Hub before §14);
+ * §18 (0.8.0): and the apps they may open (absent from a Hub before §18).
+ */
 export declare function sessionCheckPages(cfg: HubClientConfig, personId: string, sessionVersion: number): Promise<{
     verdict: "ok" | "refused" | "unknown";
     pages?: Pages;
+    apps?: HubApp[];
 }>;
 export type BrokerToken = {
     accessToken: string;
@@ -92,7 +97,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): Promise<{
+export declare function healthAnswer(check: () => Promise<Connection[]> | Connection[], pages?: PageDef[], activity?: string, station?: string): Promise<{
     status: number;
     body: {
         ok: boolean;
@@ -101,12 +106,14 @@ export declare function healthAnswer(check: () => Promise<Connection[]> | Connec
         checked_at: string;
         pages?: string;
         activity?: string;
+        station?: 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"> & {
     pages?: PageDef[];
     activity?: string;
+    station?: 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,4 +1,5 @@
 import { jwtVerify } from "jose";
+import { readApps } from "./apps.js";
 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.";
@@ -35,14 +36,21 @@ async function post(cfg, path, body) {
 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). */
+/**
+ * §14 (0.4.0): the same check, with the person's pages as the Hub holds them now (absent from a Hub before §14);
+ * §18 (0.8.0): and the apps they may open (absent from a Hub before §18).
+ */
 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 { verdict: "unknown" };
     if (r.json?.ok !== true)
         return { verdict: "refused" };
-    return r.json.pages === undefined ? { verdict: "ok" } : { verdict: "ok", pages: readPages(r.json.pages) };
+    return {
+        verdict: "ok",
+        ...(r.json.pages === undefined ? {} : { pages: readPages(r.json.pages) }),
+        ...(r.json.apps === undefined ? {} : { apps: readApps(r.json.apps) }),
+    };
 }
 /** 7.3: the store's token from the Hub, cached until an hour before it expires. */
 export function tokenBroker(cfg) {
@@ -124,7 +132,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) {
+export async function healthAnswer(check, pages, activity, station) {
     let connections;
     try {
         connections = await check();
@@ -144,6 +152,8 @@ export async function healthAnswer(check, pages, activity) {
             ...(pages ? { pages: await pagesFingerprint(pages) } : {}),
             // §16: the app's Activity door; when it differs from the one the Hub holds, the Hub reads the manifest again
             ...(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 } : {}),
         },
     };
 }
@@ -152,7 +162,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);
+    const a = await healthAnswer(check, cfg.pages, cfg.activity, cfg.station);
     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,10 +1,12 @@
 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 { 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";
 export { ownVercelToken, ownEnvironment, hubKeys, APP_ID_HEADER, OIDC_HEADER, type TokenProvider } from "./identity.js";
 /**
  * Reads the guard's settings from a module's environment. Nothing secret: the Hub's address

package/dist/index.js

@@ -1,10 +1,12 @@
 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 { 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";
 export { ownVercelToken, ownEnvironment, hubKeys, APP_ID_HEADER, OIDC_HEADER } from "./identity.js";
 /**
  * Reads the guard's settings from a module's environment. Nothing secret: the Hub's address

package/dist/session.d.ts

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

@@ -0,0 +1,82 @@
+import { type JWTVerifyGetKey } from "jose";
+export declare const STATION_ID_RE: RegExp;
+export declare const STATION_NAME_MAX = 60;
+export type StationCheck = {
+    ok: true;
+    station: {
+        id: string;
+        name: string;
+    };
+} | {
+    ok: false;
+    reason: "missing" | "bad_signature" | "expired" | "wrong_module" | "wrong_use" | "wrong_environment" | "body_changed";
+};
+/**
+ * Is this the Hub asking for a packing station? `body` is the request's raw bytes for a POST (read it with
+ * `await req.arrayBuffer()` before parsing - the pass covers the exact bytes) and null for a GET.
+ */
+export declare function verifyStationCall(req: Request, body: Uint8Array | string | null, opts: {
+    moduleId: string;
+    keys: JWTVerifyGetKey;
+    now?: Date;
+    environment?: string;
+}): Promise<StationCheck>;
+/** The refusal every Hub door answers with: 401 and only the reason word (the Hub turns it into the owner's words). */
+export declare function stationRefusal(reason: Extract<StationCheck, {
+    ok: false;
+}>["reason"]): Response;
+/** One line of an order to scan, as an app answers it (the Hub checks the shape again - an app's words are data). */
+export type StationItem = {
+    title: string;
+    title_en?: string | null;
+    sku?: string | null;
+    qty: number;
+    barcode: string;
+    image?: string | null;
+    offer?: {
+        title: string;
+        qty: number;
+    } | null;
+};
+/** An order the app owns and can be packed now. `kind` decides the flag (kuwait) or the globe (international). */
+export type StationOrder = {
+    id: string;
+    name: string;
+    kind: "kuwait" | "international";
+    country: {
+        code: string;
+        ar: string;
+        en: string;
+    };
+    items: StationItem[];
+};
+/** The three answers to the Hub's GET (always 200 once the pass is good). */
+export type StationAnswer = {
+    mine: false;
+} | {
+    mine: true;
+    ok: true;
+    order: StationOrder;
+} | {
+    mine: true;
+    ok: false;
+    name?: string | null;
+    reason: string;
+    reason_ar?: string | null;
+};
+/** The two answers to the Hub's POST (200 once the pass is good). */
+export type PackAnswer = {
+    ok: true;
+    name: string;
+} | {
+    ok: false;
+    reason: string;
+    reason_ar?: string | null;
+    missing?: {
+        sku: string | null;
+        title: string;
+        need: number;
+    }[];
+    extra?: string[];
+};
+export declare function stationJson(body: StationAnswer | PackAnswer): Response;

package/dist/station.js

@@ -0,0 +1,55 @@
+import { jwtVerify } from "jose";
+import { HUB_ISSUER, TYP } from "./identity.js";
+import { b64urlEncode, constantTimeEqual, sha256 } from "./webcrypto.js";
+// WORKFLOWS §17 (SPEC C-25, D-065): the packing station. A scan reaches an app only through the Hub:
+// the Hub has checked the station's key, then asks each app with a station door, with its own
+// 60-second pass for "station" naming the station. On the pack (POST) the pass also carries the
+// SHA-256 of the exact body, so a pass cannot be lifted onto another order or other scans.
+export const STATION_ID_RE = /^[A-Za-z0-9_-]{1,64}$/;
+export const STATION_NAME_MAX = 60;
+/**
+ * Is this the Hub asking for a packing station? `body` is the request's raw bytes for a POST (read it with
+ * `await req.arrayBuffer()` before parsing - the pass covers the exact bytes) and null for a GET.
+ */
+export async function verifyStationCall(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 !== "station")
+        return { ok: false, reason: "wrong_use" };
+    if (opts.environment && p.env !== opts.environment)
+        return { ok: false, reason: "wrong_environment" };
+    const id = typeof p.station_id === "string" ? p.station_id : "";
+    const name = typeof p.station_name === "string" ? p.station_name.trim() : "";
+    if (!STATION_ID_RE.test(id) || !name || name.length > STATION_NAME_MAX)
+        return { ok: false, reason: "bad_signature" };
+    if (body !== null) {
+        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, station: { id, name } };
+}
+/** The refusal every Hub door answers with: 401 and only the reason word (the Hub turns it into the owner's words). */
+export function stationRefusal(reason) {
+    return new Response(JSON.stringify({ error: "hub_only", reason }), { status: 401, headers: { "Content-Type": "application/json", "Cache-Control": "no-store" } });
+}
+export function stationJson(body) {
+    return new Response(JSON.stringify(body), { status: 200, headers: { "Content-Type": "application/json", "Cache-Control": "no-store" } });
+}

package/dist/ticket.d.ts

@@ -1,3 +1,4 @@
+import { type HubApp } from "./apps.js";
 import { type Pages } from "./pages.js";
 import { type JWTVerifyGetKey } from "jose";
 export declare const TICKET_ISSUER = "t3b-hub";
@@ -15,6 +16,8 @@ export type TicketClaims = {
     exp: number;
     /** §14 (0.4.0): the person's pages in this module; `{}` from a Hub before §14 */
     pages: Pages;
+    /** §18 (0.8.0): the apps this person may open; `[]` from a Hub before §18 */
+    apps: HubApp[];
 };
 export type VerifyResult = {
     ok: true;

package/dist/ticket.js

@@ -1,3 +1,4 @@
+import { readApps } from "./apps.js";
 import { readPages } from "./pages.js";
 import { jwtVerify } from "jose";
 import { HUB_ISSUER, TYP } from "./identity.js";
@@ -60,6 +61,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) },
+        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) },
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@t3b/hub-guard",
-  "version": "0.6.0",
+  "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.",
   "license": "UNLICENSED",
   "type": "module",