@t3b/hub-guard 0.2.0 → 0.3.0

package/README.md

@@ -74,6 +74,22 @@ await audit(cfg, { action: "shopify.write", target: "kw", detail: { what: "produ
 Without a Vercel ID (OIDC switched off, or a local run without `VERCEL_OIDC_TOKEN`) nothing is
 sent and the answer says why (`no_vercel_id`).
 
+## Telling the Hub something is wrong (0.3.0)
+
+An app never emails anyone itself: it tells the Hub, and the Hub emails the people chosen in
+Settings → Alerts — one email, at most one reminder a day while it lasts, one "back to normal".
+
+```ts
+import { alert } from "@t3b/hub-guard";
+const cfg = { hubUrl: process.env.T3B_HUB_URL ?? "https://t3b-hub.com" };
+await alert(cfg, { key: "rates-follow", ok: false, title: "MyFatoorah rates not followed for 30 hours", detail: "the 06:00 run failed: timeout", fix: "Nothing to do if tomorrow's run works." });
+await alert(cfg, { key: "rates-follow", ok: true });   // it is over: one "back to normal" if you were told
+```
+
+`key`: lower-case letters, digits and `._:-`, up to 80 — the app's own name for the problem.
+`title` up to 120 characters, `detail` 500, `fix` 300, `store` a store key. No secrets, tokens
+or customer data in any of them. At most 120 reports an hour per app.
+
 ## Shopify's events (through the Hub)
 
 The module never holds the Shopify app secret. Shopify sends events to the Hub; the Hub checks
@@ -141,6 +157,7 @@ export const GET = (req: Request) => guard.enter(req);
 
 ## Changes
 
+- **0.3.0** (WORKFLOWS 9.3): `alert()` — report a problem to the Hub, or say it is over.
 - **0.2.0** (8b): no module key and no pasted Hub public key. Hub → module: tokens signed by the Hub's key published at `/api/hub/jwks` (`verifyTicket`, `verifyRelay`, `verifyHubCall`, `manifestResponse`, `healthResponse`). Module → Hub: the app's own Vercel ID (`tokenBroker`, `audit`, `sessionCheck`). Removed: `signedManifest`, `relaySignature`, `importPublicKey`, the `moduleKey` / `hubPublicKeys` settings. `Guard` takes `sessionSecret`.
 - **0.1.1**: `enter()` answers with an absolute Location (B-016).
 - **0.1.0**: first publish, Web Crypto build.

package/dist/hub-client.d.ts

@@ -33,6 +33,26 @@ export declare function audit(cfg: HubClientConfig, line: {
     target?: string;
     detail?: Record<string, unknown>;
 }): Promise<boolean>;
+/**
+ * 9.3: tell the Hub a problem started (`ok: false`, with a title) or ended (`ok: true`), under a
+ * key of the app's own ("rates-follow", "feeds"). The Hub emails under its no-flood rule; the app
+ * never emails anyone itself. Never throws.
+ */
+export declare function alert(cfg: HubClientConfig, a: {
+    key: string;
+    ok: boolean;
+    title?: string;
+    detail?: string;
+    fix?: string;
+    store?: string;
+}): Promise<{
+    ok: true;
+    state: string;
+} | {
+    ok: false;
+    status: number;
+    error: string;
+}>;
 export type HubCallCheck = {
     ok: true;
 } | {

package/dist/hub-client.js

@@ -63,6 +63,17 @@ export async function audit(cfg, line) {
     const r = await post(cfg, "/api/hub/audit", line);
     return r.status === 200 || r.status === 201;
 }
+/**
+ * 9.3: tell the Hub a problem started (`ok: false`, with a title) or ended (`ok: true`), under a
+ * key of the app's own ("rates-follow", "feeds"). The Hub emails under its no-flood rule; the app
+ * never emails anyone itself. Never throws.
+ */
+export async function alert(cfg, a) {
+    const r = await post(cfg, "/api/hub/alerts", a);
+    if (r.status === 202)
+        return { ok: true, state: String(r.json?.state ?? "") };
+    return { ok: false, status: r.status, error: String(r.json?.field ?? r.json?.error ?? "no_answer") };
+}
 /** Is this request the Hub's own, for this module and this purpose? (`Authorization: Bearer <pass>`) */
 export async function verifyHubCall(req, opts) {
     const auth = req.headers.get("authorization") ?? "";

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export { Guard, type GuardConfig, type CheckResult } from "./guard.js";
 export { verifyTicket, JtiMemory, TICKET_ISSUER, TICKET_TTL_S, TICKET_ALG, type TicketClaims, type VerifyResult } from "./ticket.js";
 export { readSession, signSession, cookieHeader, clearCookieHeader, cookieValue, SESSION_COOKIE, IDLE_MS, ABSOLUTE_MS, RECHECK_MS, type ModuleSession } from "./session.js";
-export { sessionCheck, tokenBroker, audit, verifyHubCall, manifestResponse, healthResponse, healthAnswer, type HubClientConfig, type HubCallCheck, type AnswerConfig, type BrokerToken, type Connection, } from "./hub-client.js";
+export { sessionCheck, tokenBroker, audit, alert, verifyHubCall, manifestResponse, healthResponse, healthAnswer, type HubClientConfig, type HubCallCheck, type AnswerConfig, type BrokerToken, type Connection, } from "./hub-client.js";
 export { checkCloudflareAccess } from "./cf-access.js";
 export { verifyRelay, RELAY_HEADERS, RELAY_MAX_AGE_S, type RelayCheck } from "./relay.js";
 export { ownVercelToken, ownEnvironment, hubKeys, APP_ID_HEADER, OIDC_HEADER, type TokenProvider } from "./identity.js";

package/dist/index.js

@@ -1,7 +1,7 @@
 export { Guard } from "./guard.js";
 export { verifyTicket, JtiMemory, TICKET_ISSUER, TICKET_TTL_S, TICKET_ALG } from "./ticket.js";
 export { readSession, signSession, cookieHeader, clearCookieHeader, cookieValue, SESSION_COOKIE, IDLE_MS, ABSOLUTE_MS, RECHECK_MS } from "./session.js";
-export { sessionCheck, tokenBroker, audit, verifyHubCall, manifestResponse, healthResponse, healthAnswer, } from "./hub-client.js";
+export { sessionCheck, tokenBroker, audit, alert, verifyHubCall, manifestResponse, healthResponse, healthAnswer, } from "./hub-client.js";
 export { checkCloudflareAccess } from "./cf-access.js";
 export { verifyRelay, RELAY_HEADERS, RELAY_MAX_AGE_S } from "./relay.js";
 export { ownVercelToken, ownEnvironment, hubKeys, APP_ID_HEADER, OIDC_HEADER } from "./identity.js";

package/package.json

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