@t3b/hub-guard 0.1.0

package/README.md

@@ -0,0 +1,123 @@
+# @t3b/hub-guard
+
+The lock every The3Beez module installs. A module **opens only by a ticket from the Hub** and
+refuses everything else with a plain "Open this from The3Beez" page (WORKFLOWS 2.2–2.4, 8.7).
+It holds no secret of the Hub — only the Hub's public key and the module's own key.
+
+**Runs anywhere:** Web Crypto only (no `node:crypto`, no `Buffer`), so it works in Node 20+ and in
+edge runtimes — including Next.js 14 middleware, which runs only on the edge. A test fails if a
+shipped file ever imports a Node-only module.
+
+## Install
+
+```bash
+npm install @t3b/hub-guard
+```
+
+Environment (values live in the module's Vercel, names only here):
+
+| Name | What |
+|---|---|
+| `T3B_MODULE_KEY` | the key the Hub made for this module (Settings → Modules → Make key), shown once |
+| `T3B_HUB_PUBLIC_KEY` | the Hub's public key (Settings → Modules → Copy) |
+| `T3B_HUB_PUBLIC_KEY_PREVIOUS` | only during a rotation: the previous public key, for one hour |
+| `T3B_HUB_URL` | `https://t3b-hub.com` (or the Hub's test address) |
+| `T3B_CF_ACCESS_TEAM`, `T3B_CF_ACCESS_AUD` | Cloudflare Access proof, once the module host is behind it |
+
+## Next.js — three files
+
+```ts
+// src/lib/guard.ts
+import { Guard, guardConfigFromEnv } from "@t3b/hub-guard";
+export const guard = new Guard({
+  ...guardConfigFromEnv(process.env, "currencies"),
+  openPaths: ["/api/hub/webhooks", /^\/api\/cron\//], // machine doors with their own locks
+});
+```
+
+```ts
+// src/middleware.ts (or src/proxy.ts on Next 16)
+import { NextResponse, type NextRequest } from "next/server";
+import { guard } from "@/lib/guard";
+export async function middleware(req: NextRequest) {
+  const r = await guard.check(req);
+  if (!r.allow) return r.response;
+  const res = NextResponse.next();
+  if (r.setCookie) res.headers.append("set-cookie", r.setCookie);
+  return res;
+}
+export const config = { matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"] };
+```
+
+```ts
+// src/app/hub/enter/route.ts
+import { guard } from "@/lib/guard";
+export const GET = (req: Request) => guard.enter(req);
+```
+
+## The two answers the Hub reads
+
+```ts
+// src/app/api/hub/manifest/route.ts
+import { signedManifest } from "@t3b/hub-guard";
+export async function GET() {
+  const { body, headers } = await signedManifest(
+    { id: "currencies", name: { ar: "العملات", en: "Currencies" }, sidebar: { order: 40, icon: "currency" },
+      roles: ["owner", "manager"], scopes: ["read_products", "write_products"],
+      webhooks: [{ topic: "products/create", path: "/api/hub/webhooks" }], carrier_services: [], settings: [],
+      health: "/api/hub/health" },
+    process.env.T3B_MODULE_KEY ?? "",
+  );
+  return new Response(body, { headers });
+}
+```
+
+```ts
+// src/app/api/hub/health/route.ts — one line per connection the module has; the Hub shows each as a chip
+import { healthAnswer } from "@t3b/hub-guard";
+export async function GET() {
+  const { status, body } = await healthAnswer(async () => [
+    { name: "rates source", ok: await ratesReachable(), reason: null },
+    { name: "database", ok: await dbReachable() },
+  ]);
+  return Response.json(body, { status });
+}
+```
+
+## Shopify's events (through the Hub)
+
+The module never holds the Shopify app secret. Shopify sends events to the Hub; the Hub checks
+them and passes the exact body to each module that declared the topic in its manifest and is on
+for that store, signed with the module's key. Answer 2xx once the event is taken; any other answer
+makes the Hub (and Shopify behind it) try again later.
+
+```ts
+// src/app/api/hub/webhooks/route.ts  (an open path - its lock is the signature)
+import { verifyRelay } from "@t3b/hub-guard";
+export async function POST(req: Request) {
+  const body = new Uint8Array(await req.arrayBuffer());      // the exact bytes - parse only after the check
+  const v = await verifyRelay(req.headers, body, process.env.T3B_MODULE_KEY ?? "");
+  if (!v.ok) return new Response(null, { status: 401 });
+  if (await alreadyTaken(v.webhookId)) return new Response(null, { status: 200 }); // a repeat
+  await handle(v.topic, v.store, JSON.parse(new TextDecoder().decode(body)));
+  return new Response(null, { status: 200 });
+}
+```
+
+## Talking to the Hub
+
+```ts
+import { tokenBroker, audit } from "@t3b/hub-guard";
+const cfg = { hubUrl: process.env.T3B_HUB_URL!, moduleKey: process.env.T3B_MODULE_KEY! };
+const broker = tokenBroker(cfg);
+const t = await broker.get("kw");           // { ok, token: { accessToken, expiresAt, scopes } }, cached until an hour before expiry
+await audit(cfg, { action: "shopify.write", target: "kw", detail: { what: "product 123 price" } });
+```
+
+## What it enforces
+
+- `/hub/enter?ticket=…`: EdDSA ticket signed by the Hub, for this module, 60 seconds, single use → sets the module session (HttpOnly, Secure, SameSite=Strict) and sends to the page.
+- Every other request: no session → 403 (HTML for browsers, JSON for APIs), on **every host** the module answers on. Idle 15 minutes, absolute 8 hours. Every 15 minutes the Hub is asked whether the person's session still stands (sign-everyone-out, removal, lockout, grant changes). 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 (HMAC, cron secret, Shopify webhook HMAC).
+- Cloudflare Access proof checked first when the team and audience are set.
+- `verifyRelay`: the Hub's signature over timestamp, event id, topic, store and the exact body, with this module's key; refused when older or newer than 5 minutes.

package/dist/cf-access.d.ts

@@ -0,0 +1,12 @@
+export declare function checkCloudflareAccess(headers: Headers, cfg: {
+    team?: string;
+    audience?: string;
+}): Promise<{
+    mode: "off";
+    ok: true;
+} | {
+    mode: "enforced";
+    ok: boolean;
+    email?: string;
+    reason?: string;
+}>;

package/dist/cf-access.js

@@ -0,0 +1,25 @@
+import { createRemoteJWKSet, jwtVerify } from "jose";
+// Layer 1 (HUB-LOGIN-AND-SECURITY §2): Cloudflare Access puts a signed proof on every request
+// that passed it (`Cf-Access-Jwt-Assertion`). When the module is told its team and audience, a
+// request without a valid proof is refused before anything else - that is what locks the origin.
+const jwksCache = new Map();
+export async function checkCloudflareAccess(headers, cfg) {
+    if (!cfg.team || !cfg.audience)
+        return { mode: "off", ok: true };
+    const token = headers.get("cf-access-jwt-assertion");
+    if (!token)
+        return { mode: "enforced", ok: false, reason: "no Cloudflare proof" };
+    const issuer = `https://${cfg.team}.cloudflareaccess.com`;
+    let jwks = jwksCache.get(issuer);
+    if (!jwks) {
+        jwks = createRemoteJWKSet(new URL(`${issuer}/cdn-cgi/access/certs`));
+        jwksCache.set(issuer, jwks);
+    }
+    try {
+        const { payload } = await jwtVerify(token, jwks, { issuer, audience: cfg.audience });
+        return { mode: "enforced", ok: true, email: typeof payload.email === "string" ? payload.email : undefined };
+    }
+    catch (e) {
+        return { mode: "enforced", ok: false, reason: e instanceof Error ? e.message : "invalid proof" };
+    }
+}

package/dist/guard.d.ts

@@ -0,0 +1,47 @@
+import { type ModuleSession } from "./session.js";
+export type GuardConfig = {
+    /** this module's id - the ticket's audience */
+    moduleId: string;
+    /** the Hub's public key(s): the current one and, for an hour after a rotation, the previous one */
+    hubPublicKeys: string[];
+    /** the module key made in the Hub (Settings → Modules → Make key) */
+    moduleKey: string;
+    hubUrl: string;
+    /** the refusal page's link back */
+    hubHomeUrl?: string;
+    /** paths that are machine doors with their own locks (webhooks, crons, health, manifest, the enter route) - never a session */
+    openPaths?: (string | RegExp)[];
+    cloudflare?: {
+        team?: string;
+        audience?: string;
+    };
+    absoluteMs?: number;
+    fetchImpl?: typeof fetch;
+    now?: () => Date;
+};
+export type CheckResult = {
+    allow: true;
+    session: ModuleSession;
+    setCookie?: string;
+} | {
+    allow: false;
+    response: Response;
+};
+export declare class Guard {
+    private readonly cfg;
+    private readonly jti;
+    /** the session-cookie key, derived from the module key (same value as before the Web Crypto move) */
+    private readonly secretP;
+    constructor(cfg: GuardConfig);
+    private now;
+    private hubClient;
+    isOpenPath(pathname: string): boolean;
+    /** The refusal (board 11): a plain page for browsers, JSON for API routes. */
+    refuse(req: Request, reason: string, status?: number): Response;
+    /** /hub/enter?ticket=… : verify, open the module session, send to the page (303). */
+    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>;
+    /** Signs out of the module only (the Hub session is untouched). */
+    signOut(): Response;
+}

package/dist/guard.js

@@ -0,0 +1,90 @@
+import { checkCloudflareAccess } from "./cf-access.js";
+import { sessionCheck } from "./hub-client.js";
+import { clearCookieHeader, cookieHeader, cookieValue, readSession, signSession, RECHECK_MS, SESSION_COOKIE } from "./session.js";
+import { JtiMemory, verifyTicket } from "./ticket.js";
+import { hmacSha256, toHex } from "./webcrypto.js";
+export class Guard {
+    cfg;
+    jti = new JtiMemory();
+    /** the session-cookie key, derived from the module key (same value as before the Web Crypto move) */
+    secretP;
+    constructor(cfg) {
+        this.cfg = cfg;
+        if (!cfg.moduleId || !cfg.moduleKey || !cfg.hubUrl || !cfg.hubPublicKeys?.length)
+            throw new Error("hub-guard: moduleId, moduleKey, hubUrl and hubPublicKeys are required");
+        this.secretP = hmacSha256(cfg.moduleKey, "t3b-hub-guard/session/v1").then(toHex);
+    }
+    now() {
+        return this.cfg.now ? this.cfg.now() : new Date();
+    }
+    hubClient() {
+        return { hubUrl: this.cfg.hubUrl, moduleKey: this.cfg.moduleKey, fetchImpl: this.cfg.fetchImpl };
+    }
+    isOpenPath(pathname) {
+        const defaults = ["/hub/enter", "/api/hub/manifest", "/api/hub/health"];
+        return [...defaults, ...(this.cfg.openPaths ?? [])].some((p) => (typeof p === "string" ? pathname === p || pathname.startsWith(p.endsWith("/") ? p : `${p}/`) : p.test(pathname)));
+    }
+    /** The refusal (board 11): a plain page for browsers, JSON for API routes. */
+    refuse(req, reason, status = 403) {
+        const accept = req.headers.get("accept") ?? "";
+        const home = this.cfg.hubHomeUrl ?? this.cfg.hubUrl;
+        if (!accept.includes("text/html")) {
+            return new Response(JSON.stringify({ error: "open_from_hub", reason }), { status, headers: { "Content-Type": "application/json", "Cache-Control": "no-store", "Set-Cookie": clearCookieHeader() } });
+        }
+        const html = `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Open this from The3Beez</title><style>body{margin:0;font-family:system-ui,-apple-system,sans-serif;background:#F6F5F3;color:#231F20;display:flex;align-items:center;justify-content:center;min-height:100vh}.card{background:#fff;border:1px solid #E7E5E2;border-radius:12px;padding:40px;max-width:440px;text-align:center}h1{font-size:22px;margin:0 0 12px}p{color:#6B6866;line-height:1.5;margin:0 0 24px}a{display:inline-block;background:#231F20;color:#fff;text-decoration:none;padding:14px 26px;border-radius:12px;font-size:13px;letter-spacing:.08em;text-transform:uppercase;font-weight:600}</style></head><body><div class="card"><h1>Open this from The3Beez</h1><p>This app opens only from the Hub. ${escapeHtml(reason)}</p><a href="${escapeAttr(home)}">Go to the Hub</a></div></body></html>`;
+        return new Response(html, { status, headers: { "Content-Type": "text/html; charset=utf-8", "Cache-Control": "no-store", "Set-Cookie": clearCookieHeader() } });
+    }
+    /** /hub/enter?ticket=… : verify, open the module session, send to the page (303). */
+    async enter(req) {
+        const url = new URL(req.url);
+        const cf = await checkCloudflareAccess(req.headers, this.cfg.cloudflare ?? {});
+        if (!cf.ok)
+            return this.refuse(req, "The Cloudflare check did not pass.");
+        const ticket = url.searchParams.get("ticket") ?? "";
+        const v = await verifyTicket(ticket, { publicKeys: this.cfg.hubPublicKeys, audience: this.cfg.moduleId, now: this.now(), jti: this.jti });
+        if (!v.ok) {
+            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." };
+            return this.refuse(req, words[v.reason] ?? "No valid ticket.");
+        }
+        const now = this.now().getTime();
+        const session = { personId: v.claims.sub, name: v.claims.name, role: v.claims.role, stores: v.claims.stores, sv: v.claims.sv, iat: now, lastSeen: now, checkedAt: now };
+        const target = new URL(v.claims.path, url.origin);
+        return new Response(null, { status: 303, headers: { Location: target.pathname + target.search, "Set-Cookie": cookieHeader(await signSession(session, await this.secretP), { secure: url.protocol === "https:", maxAgeS: Math.floor((this.cfg.absoluteMs ?? 8 * 3_600_000) / 1000) }), "Cache-Control": "no-store" } });
+    }
+    /** Every other request: open path → allow; else the session must stand, be fresh, and pass the 15-minute Hub check. */
+    async check(req) {
+        const url = new URL(req.url);
+        if (this.isOpenPath(url.pathname))
+            return { allow: true, session: { personId: "", name: "", role: "", stores: [], sv: 0, iat: 0, lastSeen: 0, checkedAt: 0 } };
+        const cf = await checkCloudflareAccess(req.headers, this.cfg.cloudflare ?? {});
+        if (!cf.ok)
+            return { allow: false, response: this.refuse(req, "The Cloudflare check did not pass.") };
+        const nowMs = this.now().getTime();
+        const secret = await this.secretP;
+        const r = await readSession(cookieValue(req.headers.get("cookie"), SESSION_COOKIE), secret, nowMs, { absoluteMs: this.cfg.absoluteMs });
+        if (!r.ok) {
+            const words = { missing: "", bad: "", idle: "You were signed out after 15 minutes without activity.", expired: "Your session reached its 8-hour limit." };
+            return { allow: false, response: this.refuse(req, words[r.reason] ?? "") };
+        }
+        let s = r.session;
+        if (nowMs - s.checkedAt >= RECHECK_MS) {
+            const verdict = await sessionCheck(this.hubClient(), s.personId, s.sv);
+            if (verdict === "refused")
+                return { allow: false, response: this.refuse(req, "The Hub ended this session (signed out everywhere, or access changed).") };
+            if (verdict === "ok")
+                s = { ...s, checkedAt: nowMs };
+        }
+        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) }) };
+    }
+    /** 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() } });
+    }
+}
+function escapeHtml(s) {
+    return s.replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
+}
+function escapeAttr(s) {
+    return escapeHtml(s);
+}

package/dist/hub-client.d.ts

@@ -0,0 +1,53 @@
+export type HubClientConfig = {
+    hubUrl: string;
+    moduleKey: string;
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+};
+/** 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">;
+export type BrokerToken = {
+    accessToken: string;
+    expiresAt: Date;
+    scopes: string[];
+};
+/** 7.3: the store's token from the Hub, cached until an hour before it expires. */
+export declare function tokenBroker(cfg: HubClientConfig): {
+    get(store: string, now?: Date): Promise<{
+        ok: true;
+        token: BrokerToken;
+    } | {
+        ok: false;
+        status: number;
+        error: string;
+        message: string;
+    }>;
+    forget(store: string): void;
+};
+/** C-7: one audit line per consequential act (a Shopify write above all). Never throws. */
+export declare function audit(cfg: HubClientConfig, line: {
+    action: string;
+    target?: string;
+    detail?: Record<string, unknown>;
+}): Promise<boolean>;
+/** C-5: the manifest body signed with the module key - the exact bytes sent are the bytes signed. */
+export declare function signedManifest(manifest: Record<string, unknown>, moduleKey: string): Promise<{
+    body: string;
+    headers: Record<string, string>;
+}>;
+export type Connection = {
+    name: string;
+    ok: boolean;
+    reason?: string | null;
+    store?: string | null;
+};
+/** 8.4 / 7.6: the health answer. `ok` is false when any connection is red; the Hub shows each connection as its own chip. */
+export declare function healthAnswer(check: () => Promise<Connection[]> | Connection[]): Promise<{
+    status: number;
+    body: {
+        ok: boolean;
+        reason: string | null;
+        connections: Connection[];
+        checked_at: string;
+    };
+}>;

package/dist/hub-client.js

@@ -0,0 +1,81 @@
+import { hmacSha256, toHex } from "./webcrypto.js";
+async function post(cfg, path, body) {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), cfg.timeoutMs ?? 6_000);
+    try {
+        const res = await (cfg.fetchImpl ?? fetch)(new URL(path, cfg.hubUrl).toString(), {
+            method: "POST",
+            headers: { "Content-Type": "application/json", Accept: "application/json", Authorization: `Bearer ${cfg.moduleKey}` },
+            body: JSON.stringify(body),
+            signal: ctrl.signal,
+        });
+        let json = null;
+        try {
+            json = (await res.json());
+        }
+        catch {
+            json = null;
+        }
+        return { status: res.status, json };
+    }
+    catch {
+        return { status: 0, json: null };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** 2.4: does this person's Hub session still stand? `unknown` when the Hub did not answer (the module keeps the session until the next check). */
+export async function sessionCheck(cfg, personId, sessionVersion) {
+    const r = await post(cfg, "/api/hub/session-check", { personId, sessionVersion });
+    if (r.status === 0 || r.status >= 500)
+        return "unknown";
+    return r.json?.ok === true ? "ok" : "refused";
+}
+/** 7.3: the store's token from the Hub, cached until an hour before it expires. */
+export function tokenBroker(cfg) {
+    const cache = new Map();
+    return {
+        async get(store, now = new Date()) {
+            const c = cache.get(store);
+            if (c && c.expiresAt.getTime() - now.getTime() > 3_600_000)
+                return { ok: true, token: c };
+            const r = await post(cfg, "/api/broker/token", { store });
+            if (r.status !== 200 || !r.json || typeof r.json.access_token !== "string") {
+                return { ok: false, status: r.status, error: String(r.json?.error ?? "no_answer"), message: String(r.json?.message ?? "The Hub did not answer.") };
+            }
+            const token = { accessToken: r.json.access_token, expiresAt: new Date(String(r.json.expires_at)), scopes: Array.isArray(r.json.scopes) ? r.json.scopes.map(String) : [] };
+            cache.set(store, token);
+            return { ok: true, token };
+        },
+        forget(store) {
+            cache.delete(store);
+        },
+    };
+}
+/** C-7: one audit line per consequential act (a Shopify write above all). Never throws. */
+export async function audit(cfg, line) {
+    const r = await post(cfg, "/api/hub/audit", line);
+    return r.status === 200 || r.status === 201;
+}
+/** C-5: the manifest body signed with the module key - the exact bytes sent are the bytes signed. */
+export async function signedManifest(manifest, moduleKey) {
+    const body = JSON.stringify(manifest);
+    const sig = `sha256=${toHex(await hmacSha256(moduleKey, body))}`;
+    return { body, headers: { "Content-Type": "application/json", "x-t3b-signature": sig, "Cache-Control": "no-store" } };
+}
+/** 8.4 / 7.6: the health answer. `ok` is false when any connection is red; the Hub shows each connection as its own chip. */
+export async function healthAnswer(check) {
+    let connections;
+    try {
+        connections = await check();
+    }
+    catch (e) {
+        connections = [{ name: "health check", ok: false, reason: e instanceof Error ? e.message : String(e) }];
+    }
+    const red = connections.filter((c) => !c.ok);
+    return {
+        status: 200,
+        body: { ok: red.length === 0, reason: red.length ? red.map((c) => `${c.name}: ${c.reason ?? "not ok"}`).join("; ").slice(0, 200) : null, connections, checked_at: new Date().toISOString() },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+export { Guard, type GuardConfig, type CheckResult } from "./guard.js";
+export { verifyTicket, importPublicKey, JtiMemory, TICKET_ISSUER, TICKET_TTL_S, TICKET_ALG, type TicketClaims, type VerifyResult } from "./ticket.js";
+export { readSession, signSession, cookieHeader, clearCookieHeader, cookieValue, SESSION_COOKIE, IDLE_MS, ABSOLUTE_MS, RECHECK_MS, type ModuleSession } from "./session.js";
+export { sessionCheck, tokenBroker, audit, signedManifest, healthAnswer, type HubClientConfig, type BrokerToken, type Connection } from "./hub-client.js";
+export { checkCloudflareAccess } from "./cf-access.js";
+export { verifyRelay, relaySignature, RELAY_HEADERS, RELAY_MAX_AGE_S, type RelayCheck, type RelayFields } from "./relay.js";
+/** Reads the guard's configuration from a module's environment (names only; values live in Vercel). */
+export declare function guardConfigFromEnv(env: Record<string, string | undefined>, moduleId: string): {
+    moduleId: string;
+    hubPublicKeys: string[];
+    moduleKey: string;
+    hubUrl: string;
+    hubHomeUrl: string;
+    cloudflare: {
+        team: string | undefined;
+        audience: string | undefined;
+    };
+};

package/dist/index.js

@@ -0,0 +1,18 @@
+export { Guard } from "./guard.js";
+export { verifyTicket, importPublicKey, JtiMemory, TICKET_ISSUER, TICKET_TTL_S, TICKET_ALG } from "./ticket.js";
+export { readSession, signSession, cookieHeader, clearCookieHeader, cookieValue, SESSION_COOKIE, IDLE_MS, ABSOLUTE_MS, RECHECK_MS } from "./session.js";
+export { sessionCheck, tokenBroker, audit, signedManifest, healthAnswer } from "./hub-client.js";
+export { checkCloudflareAccess } from "./cf-access.js";
+export { verifyRelay, relaySignature, RELAY_HEADERS, RELAY_MAX_AGE_S } from "./relay.js";
+/** Reads the guard's configuration from a module's environment (names only; values live in Vercel). */
+export function guardConfigFromEnv(env, moduleId) {
+    const keys = [env.T3B_HUB_PUBLIC_KEY, env.T3B_HUB_PUBLIC_KEY_PREVIOUS].filter((k) => Boolean(k));
+    return {
+        moduleId,
+        hubPublicKeys: keys,
+        moduleKey: env.T3B_MODULE_KEY ?? "",
+        hubUrl: env.T3B_HUB_URL ?? "https://t3b-hub.com",
+        hubHomeUrl: env.T3B_HUB_URL ? `${env.T3B_HUB_URL.replace(/\/$/, "")}/home` : "https://t3b-hub.com/home",
+        cloudflare: { team: env.T3B_CF_ACCESS_TEAM, audience: env.T3B_CF_ACCESS_AUD },
+    };
+}

package/dist/relay.d.ts

@@ -0,0 +1,33 @@
+export declare const RELAY_HEADERS: {
+    readonly signature: "x-t3b-relay-signature";
+    readonly timestamp: "x-t3b-relay-timestamp";
+    readonly webhookId: "x-t3b-webhook-id";
+    readonly topic: "x-t3b-topic";
+    readonly store: "x-t3b-store";
+    readonly shop: "x-t3b-shop";
+};
+/** A relayed event older than this is refused (the Hub signs every attempt afresh). */
+export declare const RELAY_MAX_AGE_S = 300;
+export type RelayFields = {
+    timestamp: number;
+    webhookId: string;
+    topic: string;
+    store: string;
+};
+/** The bytes signed: `<ts>.<webhookId>.<topic>.<store>.` followed by the body exactly as received. */
+export declare function relaySignature(moduleKey: string, f: RelayFields, body: Uint8Array | string): Promise<string>;
+export type RelayCheck = {
+    ok: true;
+    webhookId: string;
+    topic: string;
+    store: string;
+    shop: string | null;
+} | {
+    ok: false;
+    reason: "missing_header" | "stale" | "bad_signature" | "no_key";
+};
+/**
+ * Checks one relayed event. Read the body as raw bytes (`await req.arrayBuffer()`) before parsing
+ * it - the signature covers the exact bytes. Use the webhook id to ignore a repeat.
+ */
+export declare function verifyRelay(headers: Headers, body: Uint8Array | string, moduleKey: string, now?: Date): Promise<RelayCheck>;

package/dist/relay.js

@@ -0,0 +1,41 @@
+import { constantTimeEqual, hmacSha256, toHex } from "./webcrypto.js";
+// WORKFLOWS 10.4 / SPEC C-20: Shopify's events reach a module only through the Hub. The Hub
+// checks Shopify's signature and which store sent the event, then re-sends the exact body to each
+// module that asked for the topic, signed with that module's key. A module never holds the
+// Shopify app secret; it checks this signature instead.
+export const RELAY_HEADERS = {
+    signature: "x-t3b-relay-signature",
+    timestamp: "x-t3b-relay-timestamp",
+    webhookId: "x-t3b-webhook-id",
+    topic: "x-t3b-topic",
+    store: "x-t3b-store",
+    shop: "x-t3b-shop",
+};
+/** A relayed event older than this is refused (the Hub signs every attempt afresh). */
+export const RELAY_MAX_AGE_S = 300;
+/** The bytes signed: `<ts>.<webhookId>.<topic>.<store>.` followed by the body exactly as received. */
+export async function relaySignature(moduleKey, f, body) {
+    return `sha256=${toHex(await hmacSha256(moduleKey, `${f.timestamp}.${f.webhookId}.${f.topic}.${f.store}.`, body))}`;
+}
+/**
+ * Checks one relayed event. Read the body as raw bytes (`await req.arrayBuffer()`) before parsing
+ * it - the signature covers the exact bytes. Use the webhook id to ignore a repeat.
+ */
+export async function verifyRelay(headers, body, moduleKey, now = new Date()) {
+    if (!moduleKey)
+        return { ok: false, reason: "no_key" };
+    const sig = headers.get(RELAY_HEADERS.signature) ?? "";
+    const tsRaw = headers.get(RELAY_HEADERS.timestamp) ?? "";
+    const webhookId = headers.get(RELAY_HEADERS.webhookId) ?? "";
+    const topic = headers.get(RELAY_HEADERS.topic) ?? "";
+    const store = headers.get(RELAY_HEADERS.store) ?? "";
+    if (!sig || !/^\d{9,11}$/.test(tsRaw) || !webhookId || !topic || !store)
+        return { ok: false, reason: "missing_header" };
+    const timestamp = Number(tsRaw);
+    if (Math.abs(Math.floor(now.getTime() / 1000) - timestamp) > RELAY_MAX_AGE_S)
+        return { ok: false, reason: "stale" };
+    const expected = await relaySignature(moduleKey, { timestamp, webhookId, topic, store }, body);
+    if (!constantTimeEqual(sig, expected))
+        return { ok: false, reason: "bad_signature" };
+    return { ok: true, webhookId, topic, store, shop: headers.get(RELAY_HEADERS.shop) };
+}

package/dist/session.d.ts

@@ -0,0 +1,31 @@
+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;
+export type ModuleSession = {
+    personId: string;
+    name: string;
+    role: string;
+    stores: string[];
+    sv: number;
+    iat: number;
+    lastSeen: number;
+    checkedAt: number;
+};
+export declare function signSession(s: ModuleSession, secret: string): Promise<string>;
+export declare function readSession(cookie: string | undefined | null, secret: string, now?: number, opts?: {
+    absoluteMs?: number;
+}): Promise<{
+    ok: true;
+    session: ModuleSession;
+} | {
+    ok: false;
+    reason: "missing" | "bad" | "idle" | "expired";
+}>;
+export declare function cookieHeader(value: string, opts?: {
+    secure?: boolean;
+    maxAgeS?: number;
+}): string;
+export declare function clearCookieHeader(): string;
+/** Reads one cookie's value out of a Cookie header. */
+export declare function cookieValue(header: string | null | undefined, name: string): string | undefined;

package/dist/session.js

@@ -0,0 +1,60 @@
+import { b64urlDecodeText, b64urlEncode, constantTimeEqual, hmacSha256, utf8 } from "./webcrypto.js";
+// The module's own session (WORKFLOWS 2.2, 2.4): set at /hub/enter from a verified ticket,
+// carried in an HttpOnly cookie signed with a key derived from the module key, 15 minutes idle,
+// 8 hours absolute for admin surfaces (a module may set shift-long for a till), re-checked with
+// the Hub every 15 minutes.
+export const SESSION_COOKIE = "t3b_module_session";
+export const IDLE_MS = 15 * 60_000;
+export const ABSOLUTE_MS = 8 * 3_600_000;
+export const RECHECK_MS = 15 * 60_000;
+export async function signSession(s, secret) {
+    const body = b64urlEncode(utf8(JSON.stringify(s)));
+    const mac = b64urlEncode(await hmacSha256(secret, body));
+    return `${body}.${mac}`;
+}
+export async function readSession(cookie, secret, now = Date.now(), opts = {}) {
+    if (!cookie)
+        return { ok: false, reason: "missing" };
+    const [body, mac] = cookie.split(".");
+    if (!body || !mac)
+        return { ok: false, reason: "bad" };
+    const expected = b64urlEncode(await hmacSha256(secret, body));
+    if (!constantTimeEqual(mac, expected))
+        return { ok: false, reason: "bad" };
+    let s;
+    try {
+        s = JSON.parse(b64urlDecodeText(body));
+    }
+    catch {
+        return { ok: false, reason: "bad" };
+    }
+    if (typeof s.personId !== "string" || typeof s.iat !== "number" || typeof s.lastSeen !== "number")
+        return { ok: false, reason: "bad" };
+    if (now - s.iat > (opts.absoluteMs ?? ABSOLUTE_MS))
+        return { ok: false, reason: "expired" };
+    if (now - s.lastSeen > IDLE_MS)
+        return { ok: false, reason: "idle" };
+    return { ok: true, session: s };
+}
+export function cookieHeader(value, opts = {}) {
+    const parts = [`${SESSION_COOKIE}=${value}`, "Path=/", "HttpOnly", "SameSite=Strict"];
+    if (opts.secure !== false)
+        parts.push("Secure");
+    if (opts.maxAgeS !== undefined)
+        parts.push(`Max-Age=${opts.maxAgeS}`);
+    return parts.join("; ");
+}
+export function clearCookieHeader() {
+    return `${SESSION_COOKIE}=; Path=/; HttpOnly; SameSite=Strict; Secure; Max-Age=0`;
+}
+/** Reads one cookie's value out of a Cookie header. */
+export function cookieValue(header, name) {
+    if (!header)
+        return undefined;
+    for (const part of header.split(";")) {
+        const [k, ...v] = part.trim().split("=");
+        if (k === name)
+            return v.join("=");
+    }
+    return undefined;
+}

package/dist/ticket.d.ts

@@ -0,0 +1,37 @@
+export declare const TICKET_ISSUER = "t3b-hub";
+export declare const TICKET_TTL_S = 60;
+export declare const TICKET_ALG = "EdDSA";
+export type TicketClaims = {
+    sub: string;
+    jti: string;
+    role: "owner" | "manager" | "staff" | "driver";
+    stores: string[];
+    path: string;
+    name: string;
+    sv: number;
+    iat: number;
+    exp: number;
+};
+export type VerifyResult = {
+    ok: true;
+    claims: TicketClaims;
+} | {
+    ok: false;
+    reason: "expired" | "wrong_audience" | "bad_signature" | "replayed" | "malformed";
+};
+/** 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 declare class JtiMemory {
+    private readonly ttlMs;
+    private seen;
+    constructor(ttlMs?: number);
+    /** returns true when the id was already seen */
+    check(jti: string, now?: number): boolean;
+}
+/** Accepts a public key as base64 SPKI (DER) or as a PEM block. */
+export declare function importPublicKey(key: string): Promise<CryptoKey>;
+export declare function verifyTicket(ticket: string, opts: {
+    publicKeys: string[];
+    audience: string;
+    now?: Date;
+    jti?: JtiMemory;
+}): Promise<VerifyResult>;

package/dist/ticket.js

@@ -0,0 +1,73 @@
+import { importSPKI, jwtVerify } from "jose";
+// SPEC C-4: the entry ticket. EdDSA (Ed25519) JWT signed by the Hub's private key; a module holds
+// the public key(s) only. Claims: iss "t3b-hub", aud = module id, sub = person id, jti, iat,
+// exp = iat + 60 s, role, stores[], path, name, sv (the person's session version).
+export const TICKET_ISSUER = "t3b-hub";
+export const TICKET_TTL_S = 60;
+export const TICKET_ALG = "EdDSA";
+/** 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;
+    seen = new Map();
+    constructor(ttlMs = 120_000) {
+        this.ttlMs = ttlMs;
+    }
+    /** returns true when the id was already seen */
+    check(jti, now = Date.now()) {
+        for (const [k, t] of this.seen)
+            if (t < now)
+                this.seen.delete(k);
+        if (this.seen.has(jti))
+            return true;
+        this.seen.set(jti, now + this.ttlMs);
+        return false;
+    }
+}
+/** Accepts a public key as base64 SPKI (DER) or as a PEM block. */
+export async function importPublicKey(key) {
+    const trimmed = key.trim();
+    const pem = trimmed.includes("-----BEGIN") ? trimmed : `-----BEGIN PUBLIC KEY-----\n${trimmed.replace(/\s+/g, "").match(/.{1,64}/g)?.join("\n") ?? ""}\n-----END PUBLIC KEY-----`;
+    return importSPKI(pem, TICKET_ALG);
+}
+export async function verifyTicket(ticket, opts) {
+    if (typeof ticket !== "string" || ticket.split(".").length !== 3 || ticket.length > 4096)
+        return { ok: false, reason: "malformed" };
+    const now = opts.now ?? new Date();
+    let payload = null;
+    let lastReason = "bad_signature";
+    for (const k of opts.publicKeys.filter(Boolean)) {
+        try {
+            const key = await importPublicKey(k);
+            const r = await jwtVerify(ticket, key, { issuer: TICKET_ISSUER, audience: opts.audience, algorithms: [TICKET_ALG], currentDate: now, clockTolerance: 5 });
+            payload = r.payload;
+            break;
+        }
+        catch (e) {
+            const code = e.code ?? "";
+            if (code === "ERR_JWT_EXPIRED")
+                lastReason = "expired";
+            else if (code === "ERR_JWT_CLAIM_VALIDATION_FAILED" && /aud/.test(e.message))
+                lastReason = "wrong_audience";
+            else if (code === "ERR_JWT_CLAIM_VALIDATION_FAILED")
+                lastReason = "wrong_audience";
+            else
+                lastReason = lastReason === "bad_signature" ? "bad_signature" : lastReason;
+        }
+    }
+    if (!payload)
+        return { ok: false, reason: lastReason };
+    const p = payload;
+    if (typeof p.sub !== "string" || typeof p.jti !== "string" || typeof p.role !== "string" || !Array.isArray(p.stores) || typeof p.path !== "string" || typeof p.exp !== "number" || typeof p.iat !== "number") {
+        return { ok: false, reason: "malformed" };
+    }
+    if (p.exp - p.iat > TICKET_TTL_S + 5)
+        return { ok: false, reason: "malformed" };
+    if (!p.path.startsWith("/") || p.path.startsWith("//") || p.path.includes("\\"))
+        return { ok: false, reason: "malformed" };
+    if (opts.jti && opts.jti.check(p.jti, now.getTime()))
+        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 },
+    };
+}

package/dist/webcrypto.d.ts

@@ -0,0 +1,8 @@
+export declare function utf8(s: string): Uint8Array;
+/** HMAC-SHA256 over the parts, in order, as one message. */
+export declare function hmacSha256(secret: string, ...parts: (string | Uint8Array)[]): Promise<Uint8Array>;
+export declare function toHex(b: Uint8Array): string;
+export declare function b64urlEncode(b: Uint8Array): string;
+export declare function b64urlDecodeText(s: string): string;
+/** Compares two strings in time that does not depend on where they first differ. */
+export declare function constantTimeEqual(a: string, b: string): boolean;

package/dist/webcrypto.js

@@ -0,0 +1,66 @@
+// Web Crypto only (globalThis.crypto.subtle), so the guard runs in Node 20+, in edge runtimes
+// (Next.js middleware before Next 15.5, Vercel Edge, Cloudflare Workers) and in Deno alike.
+// Nothing here imports node:crypto or uses Buffer.
+const enc = new TextEncoder();
+const keys = new Map();
+function subtle() {
+    const s = globalThis.crypto?.subtle;
+    if (!s)
+        throw new Error("hub-guard: Web Crypto (crypto.subtle) is not available in this runtime");
+    return s;
+}
+function hmacKey(secret) {
+    let k = keys.get(secret);
+    if (!k) {
+        k = subtle().importKey("raw", enc.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+        keys.set(secret, k);
+    }
+    return k;
+}
+export function utf8(s) {
+    return enc.encode(s);
+}
+function concat(parts) {
+    const bytes = parts.map((p) => (typeof p === "string" ? enc.encode(p) : p));
+    const out = new Uint8Array(bytes.reduce((n, b) => n + b.byteLength, 0));
+    let at = 0;
+    for (const b of bytes) {
+        out.set(b, at);
+        at += b.byteLength;
+    }
+    return out;
+}
+/** HMAC-SHA256 over the parts, in order, as one message. */
+export async function hmacSha256(secret, ...parts) {
+    const sig = await subtle().sign("HMAC", await hmacKey(secret), concat(parts));
+    return new Uint8Array(sig);
+}
+export function toHex(b) {
+    let s = "";
+    for (const x of b)
+        s += x.toString(16).padStart(2, "0");
+    return s;
+}
+export function b64urlEncode(b) {
+    let bin = "";
+    for (const x of b)
+        bin += String.fromCharCode(x);
+    return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+export function b64urlDecodeText(s) {
+    const b64 = s.replace(/-/g, "+").replace(/_/g, "/");
+    const bin = atob(b64 + "=".repeat((4 - (b64.length % 4)) % 4));
+    const bytes = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        bytes[i] = bin.charCodeAt(i);
+    return new TextDecoder().decode(bytes);
+}
+/** Compares two strings in time that does not depend on where they first differ. */
+export function constantTimeEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++)
+        diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    return diff === 0;
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@t3b/hub-guard",
+  "version": "0.1.0",
+  "description": "The3Beez Hub guard: a module opens only by a Hub-signed ticket and refuses everything else. Entry route, refusal page, module session, idle rule, 15-minute re-check with the Hub, Cloudflare Access proof, broker and audit clients, signed manifest and health answers. Web Crypto only: runs in Node 20+ and in edge runtimes.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "jose": "^6.2.12"
+  },
+  "devDependencies": {
+    "typescript": "^5",
+    "vitest": "^5.0.1"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/doofliet/t3b-hub",
+    "directory": "packages/hub-guard"
+  }
+}