@tribe-nest/forge 2.2.0 → 3.2.0

package/src/server/platform.ts

@@ -16,11 +16,26 @@
  * first, then use it for the part that genuinely needs owner-level access.
  */
 
+import type {
+  PlatformEventName,
+  PlatformEventData,
+} from "./platformEvents.generated";
+
 export type PlatformConfig = {
   /** The TribeNest public API base (VITE_API_URL). */
   apiUrl: string;
   /** The app's platform token, injected as a server-only Worker binding. */
   token: string;
+  /**
+   * The event being handled, when this client is used inside an event handler.
+   *
+   * Set for you by `handlePlatformEvent` — you should not need to pass it. Its
+   * only job is to make every write idempotent without you deriving a key: the
+   * key becomes a hash of this event, the action and the input, so the same
+   * write attempted again during a redelivery returns the first result instead of
+   * acting twice. See `run()`.
+   */
+  eventId?: string;
 };
 
 export type PlatformAction = {
@@ -105,19 +120,26 @@ export function createPlatformClient(config: PlatformConfig) {
     /**
      * Run an action.
      *
-     * `idempotencyKey` is REQUIRED for anything that writes. Derive it from your
-     * own record id: event delivery is at-least-once and jobs retry, so a write
-     * without one duplicates the first time anything is redelivered. A replay
-     * returns the original result instead of acting again.
+     * INSIDE AN EVENT HANDLER you do not need an idempotency key — one is derived
+     * from the event, the action and the input, so a redelivered event cannot
+     * make the same write twice. That is the whole reason handlers can be
+     * retried safely; you get it by doing nothing.
+     *
+     * ANYWHERE ELSE a write REQUIRES `idempotencyKey`, derived from your own
+     * record id. Jobs retry, so a write without one duplicates.
+     *
+     * Pass an explicit key to override the derived one — only needed in the rare
+     * case where one handler genuinely has to make the SAME write twice.
      */
     async run<T = unknown>(
       id: string,
       input: unknown,
       opts: { idempotencyKey?: string; dryRun?: boolean } = {},
     ): Promise<T> {
+      const key = opts.idempotencyKey ?? (config.eventId ? await derivedKey(config.eventId, id, input) : undefined);
       const body = await request(`/actions/${encodeURIComponent(id)}`, {
         method: "POST",
-        headers: opts.idempotencyKey ? { "idempotency-key": opts.idempotencyKey } : {},
+        headers: key ? { "idempotency-key": key } : {},
         body: JSON.stringify({ input, ...(opts.dryRun ? { dryRun: true } : {}) }),
       });
       return body.result as T;
@@ -138,6 +160,44 @@ export function createPlatformClient(config: PlatformConfig) {
 
 export type PlatformClient = ReturnType<typeof createPlatformClient>;
 
+/**
+ * The idempotency key for a write made while handling an event.
+ *
+ * Built from the event, the action and the input — NOT from a call counter,
+ * which would shift the moment a handler looped or branched differently and
+ * stop matching on the retry. Two genuinely different writes hash differently;
+ * the same write attempted again hashes the same and is refused a second run.
+ */
+async function derivedKey(eventId: string, actionId: string, input: unknown): Promise<string> {
+  const digest = await sha256Hex(`${eventId}:${actionId}:${canonicalJson(input)}`);
+  // The column is varchar(200); a prefix is unique enough and keeps the audit
+  // trail readable, with the event id up front so a human can see where it came from.
+  return `evt_${eventId}_${digest.slice(0, 32)}`;
+}
+
+/**
+ * JSON with object keys sorted, so `{a,b}` and `{b,a}` hash alike.
+ *
+ * Key order is not stable across runs — an unsorted stringify would produce a
+ * different key for the same write and quietly reintroduce the duplicate this
+ * exists to prevent.
+ */
+function canonicalJson(value: unknown): string {
+  if (value === null || typeof value !== "object") return JSON.stringify(value) ?? "null";
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+  const entries = Object.entries(value as Record<string, unknown>)
+    .filter(([, v]) => v !== undefined)
+    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+  return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${canonicalJson(v)}`).join(",")}}`;
+}
+
+async function sha256Hex(input: string): Promise<string> {
+  const bytes = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(input));
+  return Array.from(new Uint8Array(bytes))
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+}
+
 // --------------------------------------------------------------------- events
 
 export type PlatformEvent<T = Record<string, unknown>> = {
@@ -146,10 +206,29 @@ export type PlatformEvent<T = Record<string, unknown>> = {
   eventId: string;
   appId: string;
   profileId: string;
+  /** When it HAPPENED — not when it was delivered. Stable across a redelivery. */
   occurredAt: string;
   data: T;
 };
 
+/** One named event, with its body typed from the catalog. */
+export type TypedPlatformEvent<E extends PlatformEventName = PlatformEventName> = Omit<
+  PlatformEvent,
+  "event" | "data"
+> & {
+  event: E;
+  data: PlatformEventData<E>;
+};
+
+/**
+ * How long after signing a delivery is still accepted.
+ *
+ * Without a window a delivery captured off the wire could be pushed at the app
+ * for as long as the signing key lived. Generous enough to survive clock skew
+ * and a slow retry, short enough that a captured body stops being useful.
+ */
+export const SIGNATURE_TOLERANCE_SECONDS = 300;
+
 /**
  * Verify and parse a platform event delivered to your app.
  *
@@ -173,17 +252,163 @@ export async function verifyPlatformEvent<T = Record<string, unknown>>(
   request: Request,
   secret: string,
 ): Promise<PlatformEvent<T>> {
-  const signature = request.headers.get("x-tribenest-signature");
-  if (!signature) throw new Error("Missing platform event signature.");
-
   const body = await request.text();
+
+  // Preferred: signed over a timestamp as well as the body, so a captured
+  // delivery cannot be pushed at the app days later.
+  const v2 = request.headers.get("x-tribenest-signature-v2");
+  if (v2) {
+    const parts = Object.fromEntries(
+      v2.split(",").map((p) => {
+        const i = p.indexOf("=");
+        return [p.slice(0, i).trim(), p.slice(i + 1).trim()];
+      }),
+    );
+    const timestamp = Number(parts.t);
+    if (!Number.isFinite(timestamp) || !parts.v1) {
+      throw new Error("Platform event signature is malformed.");
+    }
+    const age = Math.abs(Math.floor(Date.now() / 1000) - timestamp);
+    if (age > SIGNATURE_TOLERANCE_SECONDS) {
+      throw new Error("Platform event signature is outside the accepted time window.");
+    }
+    const expected = await hmacHex(secret, `${timestamp}.${body}`);
+    if (!timingSafeEqual(parts.v1, expected)) {
+      throw new Error("Platform event signature did not verify.");
+    }
+    return JSON.parse(body) as PlatformEvent<T>;
+  }
+
+  // Body-only signature. Still accepted so a site running an older Forge keeps
+  // receiving events through the rollout; the platform sends both headers.
+  const legacy = request.headers.get("x-tribenest-signature");
+  if (!legacy) throw new Error("Missing platform event signature.");
   const expected = await hmacHex(secret, body);
-  if (!timingSafeEqual(signature, expected)) {
+  if (!timingSafeEqual(legacy, expected)) {
     throw new Error("Platform event signature did not verify.");
   }
   return JSON.parse(body) as PlatformEvent<T>;
 }
 
+/**
+ * A map from event name to what your app does about it.
+ *
+ * `event.data` is typed from the event's name, so `handlers["order.paid"]` gets
+ * the order, its lines and the buyer without a cast.
+ */
+export type PlatformEventHandlers = {
+  [E in PlatformEventName]?: (
+    event: TypedPlatformEvent<E>,
+    ctx: { platform: PlatformClient },
+  ) => Promise<void> | void;
+};
+
+export type HandlePlatformEventOptions = {
+  secret: string;
+  handlers: PlatformEventHandlers;
+  /** For the platform client handed to your handler. */
+  apiUrl: string;
+  token?: string;
+  /**
+   * How long a handler may run before the platform's own delivery attempt times
+   * out. Overrunning is reported as an error the agent can act on rather than an
+   * opaque timeout.
+   */
+  budgetMs?: number;
+};
+
+/** Handler budget. Under the platform's own 15s delivery timeout, deliberately. */
+export const HANDLER_BUDGET_MS = 10_000;
+
+/**
+ * Verify a delivery, run the matching handler, and answer.
+ *
+ * THE RULE THIS ENFORCES: a 200 means the work is done. Your handler never
+ * writes the response — this does, and only after your handler's promise has
+ * settled. Once the platform has a 200 it will never send that event again, so
+ * answering early would lose it.
+ *
+ * Which means: do not fire a promise you don't await, and don't reach for
+ * `waitUntil`. If the work is slow, `enqueueAppJob` it and return — the job
+ * runtime has its own retries, and a 200 then honestly means "durably queued".
+ *
+ * An unknown event answers 200 and does nothing, so events you have not written
+ * a handler for are not retried forever.
+ */
+export async function handlePlatformEvent(
+  request: Request,
+  options: HandlePlatformEventOptions,
+): Promise<Response> {
+  let event: PlatformEvent;
+  try {
+    event = await verifyPlatformEvent(request, options.secret);
+  } catch (err) {
+    // An unverified body is untrusted input from the open internet. Refuse it
+    // without saying which check failed.
+    return new Response(JSON.stringify({ error: (err as Error).message }), {
+      status: 401,
+      headers: { "content-type": "application/json" },
+    });
+  }
+
+  const handler = options.handlers[event.event as PlatformEventName];
+  if (!handler) {
+    return new Response(JSON.stringify({ ok: true, ignored: event.event }), {
+      status: 200,
+      headers: { "content-type": "application/json" },
+    });
+  }
+
+  const platform = createPlatformClient({
+    apiUrl: options.apiUrl,
+    token: options.token ?? "",
+    // This is what makes every write in the handler idempotent for free.
+    eventId: event.eventId,
+  });
+
+  const budget = options.budgetMs ?? HANDLER_BUDGET_MS;
+  try {
+    await withTimeout(
+      Promise.resolve(
+        (handler as (e: PlatformEvent, c: { platform: PlatformClient }) => Promise<void> | void)(event, {
+          platform,
+        }),
+      ),
+      budget,
+      `Handler for "${event.event}" took longer than ${budget}ms. Move the slow part into ` +
+        `enqueueAppJob() and return — the platform's delivery attempt times out before this finishes.`,
+    );
+  } catch (err) {
+    // 500 so the platform retries. Writes already made carry keys derived from
+    // this same event, so the retry repeats none of them.
+    return new Response(JSON.stringify({ error: (err as Error).message, eventId: event.eventId }), {
+      status: 500,
+      headers: { "content-type": "application/json" },
+    });
+  }
+
+  return new Response(JSON.stringify({ ok: true, eventId: event.eventId }), {
+    status: 200,
+    headers: { "content-type": "application/json" },
+  });
+}
+
+function withTimeout<T>(promise: Promise<T>, ms: number, message: string): Promise<T> {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error(message)), ms);
+    promise.then(
+      (value) => {
+        clearTimeout(timer);
+        resolve(value);
+      },
+      (err) => {
+        clearTimeout(timer);
+        reject(err);
+      },
+    );
+  });
+}
+
 async function hmacHex(secret: string, body: string): Promise<string> {
   const enc = new TextEncoder();
   const key = await crypto.subtle.importKey(