@t3b/hub-guard 0.5.0 → 0.6.0

package/README.md

@@ -182,16 +182,58 @@ if (!guard.allows(r.session, "deliveries", "write")) return guard.refusePage(req
 3. **Show only what may be used** — build the menu from `pageAccess(session, key)` and switch off buttons on a
    Read-only page.
 
+## Activity: your change log on the Hub's page (0.6.0, WORKFLOWS §16)
+
+The Hub's Settings → Activity lists every change made in the Hub and in every app. Nothing is copied to the Hub: when
+the page opens, the Hub asks your app for its lines with its own pass, and your app answers from its own log.
+
+1. **Name the door** in the manifest and in the health answer (the Hub reads the manifest again by itself when the
+   health answer names a door it does not hold):
+
+```ts
+// manifest: { ..., activity: "/api/hub/activity" }   health: healthResponse(req, check, { ...cfg, activity: "/api/hub/activity" })
+```
+
+2. **Answer it** from your own log - only the lines that are someone changing something (settings, people and
+   access, money, writes to Shopify or a carrier), worded in English like the Hub:
+
+```ts
+// src/app/api/hub/activity/route.ts
+import { activityResponse } from "@t3b/hub-guard";
+export async function GET(req: Request) {
+  return activityResponse(req, async (q) => {
+    // q: { from, to, limit, before: { at, id } | null, person (Hub id) | null, store (Hub key) | null }
+    // newest first by `at`, then your id highest first; only lines after `before` in that order; at most q.limit
+    const rows = await readMyLog(q);
+    return {
+      lines: rows.map((r) => ({ id: String(r.id), at: r.at, person: r.hubPersonId, what: r.what, detail: r.detail, store: r.store, place: r.branch })),
+      count: await countMyLog(q), // the lines in these dates, person and store, all pages together
+    };
+  }, cfg);
+}
+```
+
+   - `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").
+   - `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.
+
 ## 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` and what you add) never need a session — they carry their own locks (the Hub's pass, a cron secret).
+- 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`: 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`: 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.
 
 ## Changes
 
+- **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.
 - **0.5.0** (D-062, A-509): the session's idle limit is 180 minutes (was 15); the Hub counts the 15-minute check as activity, so the person's Hub session stays alive while they work in the module.
 - **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.

package/dist/hub-client.d.ts

@@ -69,7 +69,7 @@ export type HubCallCheck = {
 export declare function verifyHubCall(req: Request, opts: {
     moduleId: string;
     keys: JWTVerifyGetKey;
-    use: "manifest" | "health";
+    use: "manifest" | "health" | "activity";
     now?: Date;
     environment?: string;
 }): Promise<HubCallCheck>;
@@ -92,7 +92,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[]): Promise<{
+export declare function healthAnswer(check: () => Promise<Connection[]> | Connection[], pages?: PageDef[], activity?: string): Promise<{
     status: number;
     body: {
         ok: boolean;
@@ -100,9 +100,60 @@ export declare function healthAnswer(check: () => Promise<Connection[]> | Connec
         connections: Connection[];
         checked_at: string;
         pages?: string;
+        activity?: 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;
 }): Promise<Response>;
+/** One change, worded by the app for the Hub's Activity page (English, like the Hub). */
+export type ActivityLine = {
+    /** the app's own row id; with `at` it fixes the order and the page boundary */
+    id: string;
+    /** when, ISO 8601 in UTC at the app's full precision (up to microseconds), e.g. "2026-10-03T15:49:49.600123Z" */
+    at: string;
+    /** the Hub person who made the change (their Hub id), or null */
+    person: string | null;
+    /** who, when no Hub person did it - "International Orders, on its own" */
+    actor?: string | null;
+    what: string;
+    detail?: string | null;
+    /** the Hub's store key the change belongs to, if one ("kw") */
+    store?: string | null;
+    /** a finer place inside the store, if one (a branch: "Mall 360") */
+    place?: string | null;
+};
+/**
+ * What the Hub asks for. Answer the lines newest first - by `at`, then by your own id, highest first - and only
+ * those after `before` in that order (compare `at` at the precision you answered it with). At most `limit`.
+ */
+export type ActivityQuery = {
+    from: Date;
+    to: Date;
+    limit: number;
+    before: {
+        at: string;
+        id: string;
+    } | null;
+    /** only changes made by this Hub person */
+    person: string | null;
+    /** only changes for this Hub store key; a module serving one store answers nothing for another */
+    store: string | null;
+};
+export declare const ACTIVITY_AT_RE: RegExp;
+export declare const ACTIVITY_ID_RE: RegExp;
+export declare const ACTIVITY_MAX_LIMIT = 201;
+/** The Hub's question, from the request's address; null when anything is out of shape (never a wider read). */
+export declare function readActivityQuery(url: URL): ActivityQuery | null;
+/** A line as the Hub accepts it: anything out of shape is dropped, long words are cut. */
+export declare function cleanActivityLine(raw: unknown): ActivityLine | null;
+/**
+ * §16: the module's change log, only to the Hub's pass for "activity"; anyone else gets 401 and nothing. `read`
+ * answers the lines for the question (see ActivityQuery) and how many lines the dates, person and store hold in all.
+ */
+export declare function activityResponse(req: Request, read: (q: ActivityQuery) => Promise<{
+    lines: ActivityLine[];
+    count: number;
+}>, cfg: Omit<AnswerConfig, "token">): Promise<Response>;

package/dist/hub-client.js

@@ -124,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, pages) {
+export async function healthAnswer(check, pages, activity) {
     let connections;
     try {
         connections = await check();
@@ -142,6 +142,8 @@ export async function healthAnswer(check, pages) {
             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) } : {}),
+            // §16: the app's Activity door; when it differs from the one the Hub holds, the Hub reads the manifest again
+            ...(activity ? { activity } : {}),
         },
     };
 }
@@ -150,6 +152,84 @@ 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);
+    const a = await healthAnswer(check, cfg.pages, cfg.activity);
     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$/;
+export const ACTIVITY_ID_RE = /^[A-Za-z0-9_-]{1,64}$/;
+export const ACTIVITY_MAX_LIMIT = 201;
+const ACTIVITY_MAX_DAYS = 400;
+const HUB_PERSON_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const clip = (v, n) => (typeof v === "string" && v.trim() ? v.trim().slice(0, n) : null);
+/** The Hub's question, from the request's address; null when anything is out of shape (never a wider read). */
+export function readActivityQuery(url) {
+    const q = url.searchParams;
+    const from = Date.parse(q.get("from") ?? "");
+    const to = Date.parse(q.get("to") ?? "");
+    const limit = Number(q.get("limit") ?? "");
+    if (!Number.isFinite(from) || !Number.isFinite(to) || to < from || to - from > ACTIVITY_MAX_DAYS * 86_400_000)
+        return null;
+    if (!Number.isInteger(limit) || limit < 1 || limit > ACTIVITY_MAX_LIMIT)
+        return null;
+    const bAt = q.get("before_at");
+    const bId = q.get("before_id");
+    if ((bAt === null) !== (bId === null))
+        return null;
+    if (bAt !== null && (!ACTIVITY_AT_RE.test(bAt) || !ACTIVITY_ID_RE.test(bId ?? "")))
+        return null;
+    const person = q.get("person");
+    if (person !== null && !HUB_PERSON_RE.test(person))
+        return null;
+    const store = q.get("store");
+    if (store !== null && !/^[a-z0-9-]{1,32}$/.test(store))
+        return null;
+    return { from: new Date(from), to: new Date(to), limit, before: bAt !== null ? { at: bAt, id: bId } : null, person, store };
+}
+/** A line as the Hub accepts it: anything out of shape is dropped, long words are cut. */
+export function cleanActivityLine(raw) {
+    const o = (raw ?? {});
+    const id = typeof o.id === "number" && Number.isSafeInteger(o.id) ? String(o.id) : o.id;
+    if (typeof id !== "string" || !ACTIVITY_ID_RE.test(id))
+        return null;
+    if (typeof o.at !== "string" || !ACTIVITY_AT_RE.test(o.at) || !Number.isFinite(Date.parse(o.at)))
+        return null;
+    const what = clip(o.what, 200);
+    if (!what)
+        return null;
+    return {
+        id,
+        at: o.at,
+        person: typeof o.person === "string" && HUB_PERSON_RE.test(o.person) ? o.person : null,
+        actor: clip(o.actor, 60),
+        what,
+        detail: clip(o.detail, 400),
+        store: typeof o.store === "string" && /^[a-z0-9-]{1,32}$/.test(o.store) ? o.store : null,
+        place: clip(o.place, 60),
+    };
+}
+/**
+ * §16: the module's change log, only to the Hub's pass for "activity"; anyone else gets 401 and nothing. `read`
+ * answers the lines for the question (see ActivityQuery) and how many lines the dates, person and store hold in all.
+ */
+export async function activityResponse(req, read, cfg) {
+    const v = await verifyHubCall(req, { moduleId: cfg.moduleId, keys: cfg.keys, use: "activity", now: cfg.now, environment: cfg.environment });
+    if (!v.ok)
+        return jsonResponse(401, { error: "hub_only", reason: v.reason });
+    const q = readActivityQuery(new URL(req.url));
+    if (!q)
+        return jsonResponse(400, { error: "bad_query" });
+    let got;
+    try {
+        got = await read(q);
+    }
+    catch (e) {
+        console.error("[hub-guard] activity read failed:", e instanceof Error ? e.message : String(e));
+        return jsonResponse(500, { error: "read_failed" });
+    }
+    const lines = (Array.isArray(got?.lines) ? got.lines : [])
+        .map(cleanActivityLine)
+        .filter((l) => l !== null)
+        .slice(0, q.limit);
+    const count = Number.isSafeInteger(got?.count) && got.count >= 0 ? got.count : lines.length;
+    return jsonResponse(200, { lines, count });
+}

package/dist/index.d.ts

@@ -2,7 +2,7 @@ export { Guard, openingPage, type GuardConfig, type CheckResult } from "./guard.
 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, type HubClientConfig, type HubCallCheck, type AnswerConfig, type BrokerToken, type Connection, } from "./hub-client.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 { ownVercelToken, ownEnvironment, hubKeys, APP_ID_HEADER, OIDC_HEADER, type TokenProvider } from "./identity.js";

package/dist/index.js

@@ -2,7 +2,7 @@ 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, sessionCheckPages, tokenBroker, audit, alert, verifyHubCall, manifestResponse, healthResponse, healthAnswer, } from "./hub-client.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 { ownVercelToken, ownEnvironment, hubKeys, APP_ID_HEADER, OIDC_HEADER } from "./identity.js";

package/package.json

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