@tribe-nest/forge 2.1.0 → 3.2.0

package/src/server/_tests/platformEvents.spec.ts

@@ -0,0 +1,315 @@
+// The app side of platform event delivery: signature verification, the response
+// contract, and the derived idempotency key.
+//
+// The platform's half is tested against a real database in
+// apps/backend/src/services/admin/app/_tests/appEvents.spec.ts. What can only be
+// tested here is what an APP does with a delivery — and every one of these is a
+// quiet failure if it is wrong: a verifier that accepts anything is an open
+// endpoint, a route that answers 200 too early loses the event for good, and a
+// key that differs between attempts reintroduces the duplicate write the whole
+// design exists to prevent.
+
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { handlePlatformEvent, verifyPlatformEvent, SIGNATURE_TOLERANCE_SECONDS } from "../platform";
+
+const SECRET = "test-signing-secret";
+const API = "https://api.test";
+
+async function hmacHex(secret: string, body: string): Promise<string> {
+  const enc = new TextEncoder();
+  const key = await crypto.subtle.importKey("raw", enc.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, [
+    "sign",
+  ]);
+  const sig = await crypto.subtle.sign("HMAC", key, enc.encode(body));
+  return Array.from(new Uint8Array(sig))
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+}
+
+const eventBody = (over: Record<string, unknown> = {}) =>
+  JSON.stringify({
+    event: "order.paid",
+    eventId: "evt-1",
+    appId: "app-1",
+    profileId: "prof-1",
+    occurredAt: new Date().toISOString(),
+    data: { orderId: "o-1", total: 10 },
+    ...over,
+  });
+
+async function signedRequest(
+  body: string,
+  opts: { scheme?: "v1" | "v2" | "none"; timestamp?: number; secret?: string } = {},
+): Promise<Request> {
+  const secret = opts.secret ?? SECRET;
+  const headers: Record<string, string> = { "content-type": "application/json" };
+  const scheme = opts.scheme ?? "v2";
+  if (scheme === "v1") {
+    headers["x-tribenest-signature"] = await hmacHex(secret, body);
+  } else if (scheme === "v2") {
+    const t = opts.timestamp ?? Math.floor(Date.now() / 1000);
+    headers["x-tribenest-signature-v2"] = `t=${t},v1=${await hmacHex(secret, `${t}.${body}`)}`;
+  }
+  return new Request("https://app.test/api/tn-events", { method: "POST", headers, body });
+}
+
+afterEach(() => vi.restoreAllMocks());
+
+describe("verifyPlatformEvent", () => {
+  it("accepts a correctly timestamped signature", async () => {
+    const body = eventBody();
+    const event = await verifyPlatformEvent(await signedRequest(body), SECRET);
+    expect(event.eventId).toBe("evt-1");
+    expect(event.event).toBe("order.paid");
+  });
+
+  // Deployed apps bundle their own Forge; they must keep receiving events while
+  // the fleet moves onto the timestamped scheme.
+  it("still accepts the body-only signature deployed apps were built against", async () => {
+    const body = eventBody();
+    const event = await verifyPlatformEvent(await signedRequest(body, { scheme: "v1" }), SECRET);
+    expect(event.eventId).toBe("evt-1");
+  });
+
+  it("SECURITY: refuses an unsigned body", async () => {
+    await expect(verifyPlatformEvent(await signedRequest(eventBody(), { scheme: "none" }), SECRET)).rejects.toThrow(
+      /missing/i,
+    );
+  });
+
+  it("SECURITY: refuses a signature made with a different secret", async () => {
+    const req = await signedRequest(eventBody(), { secret: "someone-elses-secret" });
+    await expect(verifyPlatformEvent(req, SECRET)).rejects.toThrow(/did not verify/i);
+  });
+
+  it("SECURITY: refuses a body altered after signing", async () => {
+    const body = eventBody();
+    const signed = await signedRequest(body);
+    const tampered = new Request(signed.url, {
+      method: "POST",
+      headers: signed.headers,
+      body: eventBody({ data: { orderId: "o-1", total: 999999 } }),
+    });
+    await expect(verifyPlatformEvent(tampered, SECRET)).rejects.toThrow(/did not verify/i);
+  });
+
+  // The reason the timestamp is in the signature at all: without it, one captured
+  // delivery could be pushed at the app for as long as the key lived.
+  it("SECURITY: refuses a correctly signed delivery that is too old to be current", async () => {
+    const stale = Math.floor(Date.now() / 1000) - (SIGNATURE_TOLERANCE_SECONDS + 60);
+    const req = await signedRequest(eventBody(), { timestamp: stale });
+    await expect(verifyPlatformEvent(req, SECRET)).rejects.toThrow(/time window/i);
+  });
+
+  it("SECURITY: refuses a timestamp from the future by the same margin", async () => {
+    const ahead = Math.floor(Date.now() / 1000) + (SIGNATURE_TOLERANCE_SECONDS + 60);
+    const req = await signedRequest(eventBody(), { timestamp: ahead });
+    await expect(verifyPlatformEvent(req, SECRET)).rejects.toThrow(/time window/i);
+  });
+
+  it("refuses a malformed signature header rather than trying to interpret it", async () => {
+    const req = new Request("https://app.test/api/tn-events", {
+      method: "POST",
+      headers: { "x-tribenest-signature-v2": "garbage" },
+      body: eventBody(),
+    });
+    await expect(verifyPlatformEvent(req, SECRET)).rejects.toThrow(/malformed/i);
+  });
+});
+
+describe("handlePlatformEvent", () => {
+  const opts = (handlers: Parameters<typeof handlePlatformEvent>[1]["handlers"], extra = {}) => ({
+    secret: SECRET,
+    apiUrl: API,
+    token: "tnp_test",
+    handlers,
+    ...extra,
+  });
+
+  it("runs the handler for the event and answers 200", async () => {
+    const seen: string[] = [];
+    const res = await handlePlatformEvent(
+      await signedRequest(eventBody()),
+      opts({ "order.paid": async (e) => void seen.push(e.data.orderId) }),
+    );
+    expect(res.status).toBe(200);
+    expect(seen).toEqual(["o-1"]);
+  });
+
+  it("SECURITY: never runs a handler for a delivery that did not verify", async () => {
+    const handler = vi.fn();
+    const res = await handlePlatformEvent(
+      await signedRequest(eventBody(), { secret: "wrong" }),
+      opts({ "order.paid": handler }),
+    );
+    expect(res.status).toBe(401);
+    expect(handler).not.toHaveBeenCalled();
+  });
+
+  // The event is finished from the platform's side once it sees a 200. Answering
+  // 200 for an event nothing handles is right; a 500 would retry it five times
+  // and then sit in the failed list forever.
+  it("acknowledges an event it has no handler for, instead of failing forever", async () => {
+    const res = await handlePlatformEvent(await signedRequest(eventBody()), opts({}));
+    expect(res.status).toBe(200);
+    expect(await res.json()).toMatchObject({ ignored: "order.paid" });
+  });
+
+  // The whole reason this route is platform-owned: a 200 must mean the work is
+  // done, so the response cannot go out until the handler's promise settles.
+  it("REGRESSION: does not answer until the handler has actually finished", async () => {
+    let finished = false;
+    const res = await handlePlatformEvent(
+      await signedRequest(eventBody()),
+      opts({
+        "order.paid": async () => {
+          await new Promise((r) => setTimeout(r, 50));
+          finished = true;
+        },
+      }),
+    );
+    expect(finished).toBe(true);
+    expect(res.status).toBe(200);
+  });
+
+  it("answers 500 when the handler throws, so the platform retries", async () => {
+    const res = await handlePlatformEvent(
+      await signedRequest(eventBody()),
+      opts({
+        "order.paid": async () => {
+          throw new Error("downstream is down");
+        },
+      }),
+    );
+    expect(res.status).toBe(500);
+    expect(await res.json()).toMatchObject({ error: "downstream is down", eventId: "evt-1" });
+  });
+
+  // An overrun is otherwise indistinguishable from the platform timing out, and
+  // the fix (move it to a job) is not guessable from a dropped connection.
+  it("names the fix when a handler runs past its budget", async () => {
+    const res = await handlePlatformEvent(
+      await signedRequest(eventBody()),
+      opts({ "order.paid": () => new Promise<void>(() => {}) }, { budgetMs: 20 }),
+    );
+    expect(res.status).toBe(500);
+    expect((await res.json()).error).toMatch(/enqueueAppJob/);
+  });
+});
+
+// The property that makes a retried handler safe. Asserted on the header the
+// platform actually receives, because that is what the idempotency store keys on.
+describe("idempotency inside a handler", () => {
+  const runWithFetch = async (handler: Parameters<typeof handlePlatformEvent>[1]["handlers"]) => {
+    const calls: Array<{ url: string; key: string | null; body: string }> = [];
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async (url: string, init: RequestInit) => {
+        const headers = new Headers(init.headers as HeadersInit);
+        calls.push({ url, key: headers.get("idempotency-key"), body: String(init.body) });
+        return new Response(JSON.stringify({ result: { ok: true } }), { status: 200 });
+      }),
+    );
+    try {
+      await handlePlatformEvent(await signedRequest(eventBody()), {
+        secret: SECRET,
+        apiUrl: API,
+        token: "tnp_test",
+        handlers: handler,
+      });
+    } finally {
+      vi.unstubAllGlobals();
+    }
+    return calls;
+  };
+
+  it("sends an idempotency key the app never had to think about", async () => {
+    const calls = await runWithFetch({
+      "order.paid": async (_e, ctx) => {
+        await ctx.platform.run("blog.post.create", { title: "T" });
+      },
+    });
+    expect(calls).toHaveLength(1);
+    // Carries the event id so a human reading the audit trail can see where the
+    // write came from.
+    expect(calls[0].key).toMatch(/^evt_evt-1_[0-9a-f]{32}$/);
+  });
+
+  it("REGRESSION: the same write on a redelivery produces the SAME key", async () => {
+    const write = {
+      "order.paid": async (_e: unknown, ctx: { platform: { run: (...a: never[]) => Promise<unknown> } }) => {
+        await (ctx.platform.run as (a: string, b: unknown) => Promise<unknown>)("blog.post.create", {
+          title: "T",
+          tags: ["a", "b"],
+        });
+      },
+    } as unknown as Parameters<typeof handlePlatformEvent>[1]["handlers"];
+
+    const first = await runWithFetch(write);
+    const second = await runWithFetch(write);
+    expect(first[0].key).toBe(second[0].key);
+  });
+
+  // A call counter would have done this too — until a handler looped or branched
+  // differently on the retry, and then every key after the first would shift.
+  it("is not affected by the ORDER the writes happen in", async () => {
+    const forwards = await runWithFetch({
+      "order.paid": async (_e, ctx) => {
+        await ctx.platform.run("blog.post.create", { title: "A" });
+        await ctx.platform.run("blog.post.create", { title: "B" });
+      },
+    });
+    const backwards = await runWithFetch({
+      "order.paid": async (_e, ctx) => {
+        await ctx.platform.run("blog.post.create", { title: "B" });
+        await ctx.platform.run("blog.post.create", { title: "A" });
+      },
+    });
+    expect(new Set(forwards.map((c) => c.key))).toEqual(new Set(backwards.map((c) => c.key)));
+  });
+
+  it("keys on the input, so two different writes are not collapsed into one", async () => {
+    const calls = await runWithFetch({
+      "order.paid": async (_e, ctx) => {
+        await ctx.platform.run("blog.post.create", { title: "A" });
+        await ctx.platform.run("blog.post.create", { title: "B" });
+      },
+    });
+    expect(calls[0].key).not.toBe(calls[1].key);
+  });
+
+  it("keys on the action, so the same input to two actions is not collapsed", async () => {
+    const calls = await runWithFetch({
+      "order.paid": async (_e, ctx) => {
+        await ctx.platform.run("blog.post.create", { title: "A" });
+        await ctx.platform.run("blog.post.update", { title: "A" });
+      },
+    });
+    expect(calls[0].key).not.toBe(calls[1].key);
+  });
+
+  // Key order is not stable, so an unsorted stringify would hash the same write
+  // two different ways and silently allow the duplicate.
+  it("REGRESSION: object key order in the input does not change the key", async () => {
+    const a = await runWithFetch({
+      "order.paid": async (_e, ctx) => {
+        await ctx.platform.run("blog.post.create", { title: "T", content: "C" });
+      },
+    });
+    const b = await runWithFetch({
+      "order.paid": async (_e, ctx) => {
+        await ctx.platform.run("blog.post.create", { content: "C", title: "T" } as never);
+      },
+    });
+    expect(a[0].key).toBe(b[0].key);
+  });
+
+  it("lets an app override the key when it genuinely needs the same write twice", async () => {
+    const calls = await runWithFetch({
+      "order.paid": async (_e, ctx) => {
+        await ctx.platform.run("blog.post.create", { title: "T" }, { idempotencyKey: "mine-1" });
+      },
+    });
+    expect(calls[0].key).toBe("mine-1");
+  });
+});

package/src/server/index.ts

@@ -274,9 +274,26 @@ export function toPlainText(html?: string, max = 200): string | undefined {
 export {
   createPlatformClient,
   verifyPlatformEvent,
+  handlePlatformEvent,
   PlatformError,
+  HANDLER_BUDGET_MS,
+  SIGNATURE_TOLERANCE_SECONDS,
   type PlatformClient,
   type PlatformConfig,
   type PlatformAction,
   type PlatformEvent,
+  type TypedPlatformEvent,
+  type PlatformEventHandlers,
+  type HandlePlatformEventOptions,
 } from "./platform";
+
+// Generated from the platform's event catalog — the payload each event carries.
+// `npm run generate:forge-events` in apps/backend rewrites it; a spec fails if
+// the committed copy is stale.
+export {
+  PLATFORM_EVENT_PERMISSIONS,
+  PLATFORM_EVENT_NAMES,
+  type PlatformEventMap,
+  type PlatformEventName,
+  type PlatformEventData,
+} from "./platformEvents.generated";

package/src/server/jobs.ts

@@ -11,11 +11,22 @@ export interface AppJobsEnv {
     idFromName: (name: string) => unknown;
     get: (id: unknown) => AppJobsStub;
   };
+  /**
+   * Per-app job credential, injected by the platform at deploy. Authenticates
+   * this app to the shared job runtime (C8) — without it the runtime cannot
+   * tell one app's calls from another's.
+   */
+  JOBS_APP_TOKEN?: string;
 }
 
 interface AppJobsStub {
-  reconcile: (script: string, appId: string, desired: JobSchedule[], hash: string) => Promise<{ changed: boolean }>;
-  enqueue: (script: string, appId: string, name: string, payload: unknown, delayMs: number) => Promise<void>;
+  reconcile: (
+    script: string,
+    callerToken: string,
+    desired: JobSchedule[],
+    hash: string,
+  ) => Promise<{ changed: boolean }>;
+  enqueue: (script: string, callerToken: string, name: string, payload: unknown, delayMs: number) => Promise<void>;
   status: () => Promise<AppJobsStatus>;
 }
 
@@ -79,10 +90,10 @@ export interface JobSchedule {
    * interval after the deploy.
    */
   intervalMs?: number;
-   // A 5-field UTC cron expression: minute hour day-of-month month day-of-week.
-   // e.g. "0 3 * * *" = daily at 03:00 UTC; "0 0,6,12,18 * * *" = every 6 hours;
-   // "0 9 * * 1-5" = 09:00 UTC on weekdays. Provide this OR `intervalMs`. Use
-   // cron when a run must land at a specific wall-clock time; evaluation is UTC.
+  // A 5-field UTC cron expression: minute hour day-of-month month day-of-week.
+  // e.g. "0 3 * * *" = daily at 03:00 UTC; "0 0,6,12,18 * * *" = every 6 hours;
+  // "0 9 * * 1-5" = 09:00 UTC on weekdays. Provide this OR `intervalMs`. Use
+  // cron when a run must land at a specific wall-clock time; evaluation is UTC.
   cron?: string;
 }
 
@@ -135,6 +146,26 @@ export interface AppJobsConfig {
 
 const stub = (env: AppJobsEnv, appId: string): AppJobsStub => env.JOBS.get(env.JOBS.idFromName(appId));
 
+/**
+ * The per-app credential the platform injects at deploy (`JOBS_APP_TOKEN`).
+ *
+ * The job runtime authenticates the CALLER with this instead of trusting an
+ * `appId` argument (C8): every app has a binding to the shared namespace, so
+ * without it any app could address — and operate on — another app's jobs.
+ *
+ * Apps published before this existed have no token and will get a clear error
+ * rather than a silent no-op; republishing injects one.
+ */
+const callerToken = (env: AppJobsEnv): string => {
+  const token = (env as { JOBS_APP_TOKEN?: string }).JOBS_APP_TOKEN;
+  if (!token) {
+    throw new Error(
+      "TribeNest jobs: this app has no JOBS_APP_TOKEN. Republish the app to receive one (it is injected at deploy).",
+    );
+  }
+  return token;
+};
+
 // A stable fingerprint of the desired schedule set, so the DO skips reconcile
 // when nothing changed (sorted by name → order-independent).
 function scheduleHash(schedules: JobSchedule[]): string {
@@ -152,7 +183,7 @@ function scheduleHash(schedules: JobSchedule[]): string {
  * one, a removed one is pruned.
  */
 export async function reconcileAppJobs(env: AppJobsEnv, cfg: AppJobsConfig, schedules: JobSchedule[]): Promise<void> {
-  await stub(env, cfg.appId).reconcile(cfg.script ?? "", cfg.appId, schedules, scheduleHash(schedules));
+  await stub(env, cfg.appId).reconcile(cfg.script ?? "", callerToken(env), schedules, scheduleHash(schedules));
 }
 
 /**
@@ -172,7 +203,7 @@ export async function enqueueAppJob(
   payload?: unknown,
   delayMs = 0,
 ): Promise<void> {
-  await stub(env, cfg.appId).enqueue(cfg.script ?? "", cfg.appId, name, payload ?? null, delayMs);
+  await stub(env, cfg.appId).enqueue(cfg.script ?? "", callerToken(env), name, payload ?? null, delayMs);
 }
 
 /**
@@ -330,7 +361,6 @@ export async function deleteAppCollection(
   return res.json();
 }
 
-
 /**
  * Read an app's OWN collection back from a JOB handler (the read counterpart to
  * writeAppCollection), authenticated by the run's app-sync token. Reads at `app`
@@ -367,6 +397,94 @@ export async function aggregateAppCollection(
     headers: { "content-type": "application/json", "x-app-sync-token": ctx.token },
     body: JSON.stringify(input),
   });
-  if (!res.ok) throw new Error(`aggregateAppCollection ${slug} failed: ${res.status} ${await res.text().catch(() => "")}`);
+  if (!res.ok)
+    throw new Error(`aggregateAppCollection ${slug} failed: ${res.status} ${await res.text().catch(() => "")}`);
+  return res.json();
+}
+
+/**
+ * Upload a file and get back a hosted URL, in two steps.
+ *
+ * The two steps are not a formality. The bytes go to a STAGING key that does not
+ * survive: `finalizeAppUpload` moves the file to its real home, and anything
+ * never finalized is deleted within the hour. So the URL you can actually use is
+ * the one finalize returns — a staged URL will stop working, and the upload will
+ * not be counted against the profile's storage.
+ *
+ *   const up = await createAppUpload(ctx, cfg, "cover.png", bytes.byteLength)
+ *   await fetch(up.uploadUrl, { method: "PUT", headers: up.requiredHeaders, body: bytes })
+ *   const media = await finalizeAppUpload(ctx, cfg, up.uploadId)   // media.url is yours
+ *
+ * `size` is a hint so an over-quota upload fails before the transfer rather than
+ * after it; the size recorded is whatever storage reports once the bytes land.
+ * The file name decides the type, and script-capable types (html, svg) are
+ * refused.
+ */
+export async function createAppUpload(
+  ctx: JobContext,
+  cfg: AppJobsConfig,
+  fileName: string,
+  size?: number,
+): Promise<{
+  uploadId: string;
+  uploadUrl: string;
+  requiredHeaders: Record<string, string>;
+  method: "PUT";
+  expiresAt: string;
+}> {
+  const res = await fetch(`${cfg.apiUrl}/public/apps/${cfg.appId}/uploads`, {
+    method: "POST",
+    headers: { "content-type": "application/json", "x-app-sync-token": ctx.token },
+    body: JSON.stringify({ fileName, size }),
+  });
+  if (!res.ok) throw new Error(`createAppUpload failed: ${res.status} ${await res.text().catch(() => "")}`);
+  return res.json();
+}
+
+/**
+ * Complete an upload started with {@link createAppUpload} and get the media row.
+ *
+ * Safe to retry — finalizing twice returns the same media rather than storing the
+ * file twice. Takes no size: the platform reads it back from storage.
+ */
+export async function finalizeAppUpload(
+  ctx: JobContext,
+  cfg: AppJobsConfig,
+  uploadId: string,
+): Promise<{ id: string; url: string; size: string; type: string; name: string }> {
+  const res = await fetch(`${cfg.apiUrl}/public/apps/${cfg.appId}/uploads/${uploadId}/finalize`, {
+    method: "POST",
+    headers: { "content-type": "application/json", "x-app-sync-token": ctx.token },
+    body: "{}",
+  });
+  if (!res.ok) throw new Error(`finalizeAppUpload failed: ${res.status} ${await res.text().catch(() => "")}`);
+  return res.json();
+}
+
+/**
+ * Send an email as this app.
+ *
+ * The From resolves to the app's own sending identity when the owner configured
+ * one, otherwise the profile's — so mail is attributed to the creator, not to
+ * TribeNest, without the app holding any mail credentials.
+ *
+ *   await sendAppEmail(ctx, cfg, { to: user.email, subject: "Booked", html })
+ *
+ * Bounded on purpose: at most 50 recipients per call, and a daily per-app
+ * recipient budget, because the send is charged to the owner's allocation. For a
+ * campaign, use the platform's messaging tools instead — they handle consent and
+ * unsubscribes, which this deliberately does not.
+ */
+export async function sendAppEmail(
+  ctx: JobContext,
+  cfg: AppJobsConfig,
+  msg: { to: string | string[]; subject: string; html: string; replyTo?: string },
+): Promise<{ sent: number }> {
+  const res = await fetch(`${cfg.apiUrl}/public/apps/${cfg.appId}/emails`, {
+    method: "POST",
+    headers: { "content-type": "application/json", "x-app-sync-token": ctx.token },
+    body: JSON.stringify(msg),
+  });
+  if (!res.ok) throw new Error(`sendAppEmail failed: ${res.status} ${await res.text().catch(() => "")}`);
   return res.json();
 }