@openlup/platform 0.16.0 → 0.17.0

package/dist/http/webhookSignature.js

@@ -0,0 +1,86 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+/** Hard cap on raw webhook body bytes — the payment provider events are well under 256 KiB. */
+export const MAX_WEBHOOK_BODY_BYTES = 1_048_576;
+/** Thrown by readRawBody when the streamed body exceeds MAX_WEBHOOK_BODY_BYTES. */
+export class WebhookBodyTooLargeError extends Error {
+    constructor() {
+        super("Webhook body exceeds maximum size");
+        this.name = "WebhookBodyTooLargeError";
+    }
+}
+/**
+ * Reads the exact raw request body bytes for provider webhook signature
+ * verification.
+ *
+ * `@vercel/node` (v3, the builder for `/api` functions in this Vite project)
+ * auto-parses `application/json` request bodies into `req.body` and IGNORES the
+ * `export const config = { api: { bodyParser: false } }` opt-out — that opt-out
+ * is a Next.js Pages Router convention, not a vanilla `@vercel/node` one
+ * (verified empirically against the hidden-preview deploy: a JSON payload posted
+ * with `Content-Type: application/json` arrives parsed, the same bytes posted as
+ * `text/plain` arrive raw). Re-serializing the parsed object with
+ * `JSON.stringify` does NOT reproduce the provider's exact bytes — the payment provider signs
+ * pretty-printed JSON, so a compacted re-serialization breaks HMAC verification.
+ *
+ * Reading the underlying request stream FIRST — before touching `req.body`,
+ * whose getter triggers the parse that consumes the stream — preserves the exact
+ * bytes when the platform parses lazily. When `req` is not a stream (unit tests
+ * pass a plain `{ body }` object) or the stream yields nothing (already
+ * consumed), we fall back to `req.body`.
+ */
+export async function readRawBody(req) {
+    if (isAsyncIterable(req)) {
+        const chunks = [];
+        let total = 0;
+        for await (const chunk of req) {
+            const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            total += buf.byteLength;
+            // Enforce the cap mid-stream so an oversized body is rejected before it is
+            // fully buffered into memory, not after.
+            if (total > MAX_WEBHOOK_BODY_BYTES)
+                throw new WebhookBodyTooLargeError();
+            chunks.push(buf);
+        }
+        if (chunks.length > 0)
+            return Buffer.concat(chunks).toString("utf8");
+    }
+    if (typeof req.body === "string")
+        return capBody(req.body);
+    if (Buffer.isBuffer(req.body))
+        return capBody(req.body.toString("utf8"));
+    if (req.body && typeof req.body === "object")
+        return capBody(JSON.stringify(req.body));
+    return "";
+}
+function capBody(body) {
+    if (Buffer.byteLength(body, "utf8") > MAX_WEBHOOK_BODY_BYTES) {
+        throw new WebhookBodyTooLargeError();
+    }
+    return body;
+}
+function isAsyncIterable(value) {
+    return (value != null &&
+        typeof value[Symbol.asyncIterator] ===
+            "function");
+}
+export function verifyHmacSignature(input) {
+    if (!input.signatureHeader || !input.secret)
+        return false;
+    return timingSafeStringEqual(input.signatureHeader, hmac(input.rawBody, input.secret));
+}
+function hmac(value, secret) {
+    return createHmac("sha256", secret).update(value).digest("hex");
+}
+/**
+ * Constant-time comparison of two shared-secret strings.
+ *
+ * Exported because it is not payment-specific: any route holding a shared token has to compare it
+ * the same way, and a second hand-rolled copy of a security primitive is how one of them quietly
+ * stops being constant-time. The length check comes first because `timingSafeEqual` THROWS on a
+ * length mismatch rather than returning false, and the length of a shared token is not the secret.
+ */
+export function timingSafeStringEqual(left, right) {
+    const leftBuffer = Buffer.from(left);
+    const rightBuffer = Buffer.from(right);
+    return leftBuffer.length === rightBuffer.length && timingSafeEqual(leftBuffer, rightBuffer);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openlup/platform",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "private": false,
   "description": "Runnable server substrate: Node HTTP runtime, BFF dispatch, scheduler, storage, data gateways and bundle composition; development preview.",
   "license": "Apache-2.0",
@@ -31,7 +31,7 @@
     "api:update": "npm run build && node --experimental-strip-types ./scripts/api-contract.ts --update"
   },
   "peerDependencies": {
-    "@openlup/core": "0.16.0",
+    "@openlup/core": "0.17.0",
     "pg": "^8.22.0",
     "@aws-sdk/client-s3": "^3.1144.0",
     "@types/pg": "^8.20.0"
@@ -105,6 +105,16 @@
       "types": "./dist/identity/contracts/index.d.ts",
       "import": "./dist/identity/contracts/index.js",
       "default": "./dist/identity/contracts/index.js"
+    },
+    "./communications": {
+      "types": "./dist/communications/index.d.ts",
+      "import": "./dist/communications/index.js",
+      "default": "./dist/communications/index.js"
+    },
+    "./communications/contracts": {
+      "types": "./dist/communications/contracts/index.d.ts",
+      "import": "./dist/communications/contracts/index.js",
+      "default": "./dist/communications/contracts/index.js"
     }
   },
   "repository": {

package/release-gates.json

@@ -11,7 +11,8 @@
       "compatibilityPolicy": "internal-candidate",
       "packageSmokeEvidence": [
         "test/packageBoundary.test.ts",
-        "test/http/runtime.test.ts"
+        "test/http/runtime.test.ts",
+        "test/http/webhookSignature.test.ts"
       ],
       "entrypoint": "dist/http/index.d.ts",
       "snapshot": "api/http.api.md"
@@ -125,19 +126,51 @@
       ],
       "entrypoint": "dist/identity/contracts/index.d.ts",
       "snapshot": "api/identity-contracts.api.md"
+    },
+    "./communications": {
+      "role": "capability",
+      "maturity": "experimental",
+      "compatibilityPolicy": "internal-candidate",
+      "packageSmokeEvidence": [
+        "test/packageBoundary.test.ts",
+        "test/communications/sql.test.ts",
+        "test/communications/contribution.test.ts",
+        "test/communications/transportConformance.test.ts"
+      ],
+      "entrypoint": "dist/communications/index.d.ts",
+      "snapshot": "api/communications.api.md"
+    },
+    "./communications/contracts": {
+      "role": "capability",
+      "maturity": "experimental",
+      "compatibilityPolicy": "internal-candidate",
+      "packageSmokeEvidence": [
+        "test/packageBoundary.test.ts",
+        "test/communications/contracts.test.ts"
+      ],
+      "entrypoint": "dist/communications/contracts/index.d.ts",
+      "snapshot": "api/communications-contracts.api.md"
     }
   },
   "pack": {
     "code": {
-      "maxPackedBytes": 131072,
-      "maxFiles": 240
+      "maxPackedBytes": 440320,
+      "maxFiles": 800
     },
     "docs": {
-      "maxPackedBytes": 16384,
-      "maxFiles": 12
+      "maxPackedBytes": 40960,
+      "maxFiles": 10
     },
-    "maxPackedBytes": 196608,
-    "maxUnpackedBytes": 1048576,
-    "maxFiles": 256
+    "maxPackedBytes": 522240,
+    "maxUnpackedBytes": 2088960,
+    "maxFiles": 800,
+    "baseline": {
+      "version": "0.16.0",
+      "packedBytes": 256973
+    },
+    "browserEntries": {
+      "./communications/contracts": 11776,
+      "./identity/contracts": 4800
+    }
   }
 }

package/sql/20260807190000_comms_outbox_rail.sql

@@ -0,0 +1,329 @@
+-- Public platform communications outbox rail: the queue table, the dormant-event-type
+-- allowlist, and the claim/ack protocol that drains them.
+--
+-- WHAT THIS FORWARD SHIPS, AND WHY IT IS THE FIRST ONE CARRYING FUNCTIONS.
+-- The baseline and the read-parity forward both hold `grep -c 'CREATE FUNCTION'` = 0 on
+-- purpose. This migration breaks that property deliberately, because the dispatch rail
+-- has no non-RPC surface: claim is an atomic `UPDATE ... FOR UPDATE SKIP LOCKED` that
+-- hands back a claim token and evaluates a per-aggregate ordering barrier inside the same
+-- statement. Expressing it through the gateway's query builder would mean reimplementing
+-- pessimistic locking in the application, i.e. a second and divergent rail. Four functions
+-- is the whole crossing: no privilege model, no `private` schema, no queue statistics, no
+-- pruning, no preview-matrix claim scope, and above all no enqueue -- rows are written by
+-- capabilities that own their own business logic, and none of them is authored here.
+--
+-- AUTHORED, NOT COPIED. The protocol below was written for this migration against the
+-- observable contract the platform outbox store port issues (five named RPC arguments sets,
+-- a boolean/text/integer/SETOF return shape). It is not a cut of any historical migration:
+-- the provider-specific idempotency window and the hardcoded product event-type vocabulary
+-- that the managed implementation calls into are absent, the preview-matrix claim scope is
+-- absent, row-level security and role grants are absent because this kernel creates no
+-- roles to grant to, `SECURITY DEFINER` is absent for the same reason, every constraint is
+-- named rather than left to a generated identifier, and `CREATE` is unconditional because a
+-- manifest-ordered forward runs exactly once against a known prefix -- `IF NOT EXISTS` there
+-- would hide the drift the migration ledger exists to catch. `SET search_path` is kept: it
+-- is a real injection-hardening property that does not depend on a role model.
+
+CREATE TABLE public.outbox_events (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  created_at timestamptz NOT NULL DEFAULT now(),
+  available_at timestamptz NOT NULL DEFAULT now(),
+  processed_at timestamptz,
+  aggregate_type text NOT NULL,
+  aggregate_id uuid NOT NULL,
+  event_type text NOT NULL,
+  idempotency_key text NOT NULL,
+  status text NOT NULL DEFAULT 'pending',
+  attempts integer NOT NULL DEFAULT 0,
+  payload jsonb NOT NULL,
+  error text,
+  metadata jsonb NOT NULL DEFAULT '{}'::jsonb,
+  CONSTRAINT outbox_events_aggregate_type_nonempty_check CHECK (btrim(aggregate_type) <> ''),
+  CONSTRAINT outbox_events_event_type_nonempty_check CHECK (btrim(event_type) <> ''),
+  CONSTRAINT outbox_events_idempotency_key_nonempty_check CHECK (btrim(idempotency_key) <> ''),
+  CONSTRAINT outbox_events_attempts_check CHECK (attempts >= 0),
+  CONSTRAINT outbox_events_status_check
+    CHECK (status IN ('pending', 'processing', 'processed', 'failed', 'discarded')),
+  CONSTRAINT outbox_events_event_type_idempotency_key_key UNIQUE (event_type, idempotency_key)
+);
+
+CREATE INDEX idx_outbox_events_status_available
+  ON public.outbox_events (status, available_at);
+
+CREATE INDEX idx_outbox_events_aggregate
+  ON public.outbox_events (aggregate_type, aggregate_id);
+
+-- The claim barrier below refuses to skip an older unprocessed row for the same aggregate,
+-- INCLUDING one whose event type the caller does not know about. Without a way to declare a
+-- type intentionally unconsumed, a single retired producer would stall its aggregate
+-- forever. This table is that declaration, and it ships empty: which types are dormant is
+-- operator data, not platform content.
+CREATE TABLE public.outbox_dormant_event_types (
+  event_type text PRIMARY KEY,
+  owner text NOT NULL,
+  reason text NOT NULL,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now(),
+  CONSTRAINT outbox_dormant_event_types_event_type_nonempty_check CHECK (btrim(event_type) <> ''),
+  CONSTRAINT outbox_dormant_event_types_owner_nonempty_check CHECK (btrim(owner) <> ''),
+  CONSTRAINT outbox_dormant_event_types_reason_nonempty_check CHECK (btrim(reason) <> '')
+);
+
+-- Claim a batch for one allowlist of event types.
+--
+-- Three properties make this more than a SELECT, and each is load-bearing:
+--   1. an empty allowlist is refused, never widened -- a caller that forgot its filter must
+--      not drain every event type on the instance;
+--   2. rows whose attempts already reached the ceiling are discarded before the scan, so an
+--      exhausted row cannot be re-selected on every tick;
+--   3. per aggregate, an older unprocessed row blocks the newer one. A prior of an event
+--      type the caller neither claims nor knows also blocks, unless it has been declared
+--      dormant -- ordering within an aggregate is the guarantee producers rely on.
+-- The claim token written into metadata is the authorization for every later acknowledgement:
+-- knowing the row id is not enough, which is what makes a stale ack detectable rather than
+-- destructive.
+CREATE FUNCTION public.outbox_claim_batch(
+  p_event_types text[],
+  p_known_event_types text[] DEFAULT ARRAY[]::text[],
+  p_batch_size integer DEFAULT 25,
+  p_visibility_seconds integer DEFAULT 300,
+  p_max_attempts integer DEFAULT 8
+)
+RETURNS SETOF public.outbox_events
+LANGUAGE plpgsql
+SET search_path = public, pg_catalog
+AS $$
+DECLARE
+  v_batch integer := LEAST(GREATEST(COALESCE(p_batch_size, 25), 1), 100);
+  v_visibility integer := LEAST(GREATEST(COALESCE(p_visibility_seconds, 300), 300), 3600);
+  v_max integer := LEAST(GREATEST(COALESCE(p_max_attempts, 8), 1), 20);
+  v_known text[];
+BEGIN
+  IF p_event_types IS NULL OR cardinality(p_event_types) = 0 THEN
+    RAISE EXCEPTION 'outbox_claim_allowlist_required' USING ERRCODE = '22023';
+  END IF;
+
+  -- Everything the caller can recognise: what it claims now, plus what it declares it knows
+  -- about. A prior outside this set is treated as foreign, and only the dormant table can
+  -- release it.
+  SELECT array_agg(DISTINCT event_type)
+    INTO v_known
+    FROM unnest(COALESCE(p_known_event_types, ARRAY[]::text[]) || p_event_types) AS known(event_type)
+   WHERE event_type IS NOT NULL AND btrim(event_type) <> '';
+
+  WITH exhausted AS (
+    SELECT event.id
+      FROM public.outbox_events event
+     WHERE event.event_type = ANY (p_event_types)
+       AND event.status IN ('pending', 'failed', 'processing')
+       AND event.available_at <= now()
+       AND event.attempts >= v_max
+     ORDER BY event.created_at, event.id
+     LIMIT 100
+     FOR UPDATE SKIP LOCKED
+  )
+  UPDATE public.outbox_events event
+     SET status = 'discarded',
+         error = left(COALESCE(event.error, '') || ' | max_attempts_exhausted_at_claim', 2000),
+         metadata = event.metadata || jsonb_build_object(
+           'discardReason', 'max_attempts',
+           'discardedAt', now(),
+           'finalAttempts', event.attempts)
+    FROM exhausted
+   WHERE event.id = exhausted.id;
+
+  RETURN QUERY
+  WITH candidates AS (
+    SELECT event.id
+      FROM public.outbox_events event
+     WHERE event.event_type = ANY (p_event_types)
+       AND event.available_at <= now()
+       AND event.status IN ('pending', 'failed', 'processing')
+       AND event.attempts < v_max
+       AND NOT EXISTS (
+             SELECT 1
+               FROM public.outbox_events prior
+              WHERE prior.aggregate_type = event.aggregate_type
+                AND prior.aggregate_id = event.aggregate_id
+                AND prior.status IN ('pending', 'failed', 'processing')
+                AND (prior.created_at, prior.id) < (event.created_at, event.id)
+                AND (
+                  prior.event_type = ANY (p_event_types)
+                  OR (
+                    prior.event_type <> ALL (COALESCE(v_known, ARRAY[]::text[]))
+                    AND NOT EXISTS (
+                          SELECT 1
+                            FROM public.outbox_dormant_event_types dormant
+                           WHERE dormant.event_type = prior.event_type
+                        )
+                  )
+                ))
+     ORDER BY event.created_at, event.id
+     LIMIT v_batch
+     FOR UPDATE SKIP LOCKED
+  )
+  UPDATE public.outbox_events event
+     SET status = 'processing',
+         attempts = event.attempts + 1,
+         available_at = now() + make_interval(secs => v_visibility),
+         metadata = event.metadata || jsonb_build_object(
+           'lastClaimedAt', now(),
+           'claimToken', gen_random_uuid()::text)
+    FROM candidates
+   WHERE event.id = candidates.id
+  RETURNING event.*;
+END;
+$$;
+
+-- Acknowledge success. Returns false rather than raising when the row is no longer the
+-- caller's: a lease that expired and was re-claimed elsewhere is an ordinary race, and the
+-- caller logs it instead of aborting a batch.
+CREATE FUNCTION public.outbox_mark_processed(
+  p_event_id uuid,
+  p_claim_token text,
+  p_metadata jsonb DEFAULT '{}'::jsonb
+)
+RETURNS boolean
+LANGUAGE sql
+SET search_path = public, pg_catalog
+AS $$
+  WITH updated AS (
+    UPDATE public.outbox_events
+       SET status = 'processed',
+           processed_at = now(),
+           error = NULL,
+           metadata = metadata || COALESCE(p_metadata, '{}'::jsonb)
+     WHERE id = p_event_id
+       AND status = 'processing'
+       AND metadata->>'claimToken' = p_claim_token
+     RETURNING id
+  )
+  SELECT EXISTS (SELECT 1 FROM updated);
+$$;
+
+-- Acknowledge failure. The outcome the handler asks for is a request, not a verdict: a
+-- 'retry' on a row that has already spent its attempts becomes a discard, so the ceiling is
+-- enforced in one place instead of in every caller.
+--
+-- 'snooze' means the downstream is unavailable rather than the row being bad, so the attempt
+-- taken at claim is refunded -- an outage must not consume the DLQ budget of the events it
+-- happened to touch. Retry delay is exponential with equal jitter in [d/2, d]: without the
+-- jitter every row that failed in the same tick returns in the same later tick, and the
+-- convoy reforms on each retry instead of dispersing.
+CREATE FUNCTION public.outbox_mark_failed(
+  p_event_id uuid,
+  p_claim_token text,
+  p_error text,
+  p_outcome text DEFAULT 'retry',
+  p_base_delay_seconds integer DEFAULT 60,
+  p_max_delay_seconds integer DEFAULT 3600,
+  p_max_attempts integer DEFAULT 8,
+  p_snooze_seconds integer DEFAULT 300
+)
+RETURNS text
+LANGUAGE plpgsql
+SET search_path = public, pg_catalog
+AS $$
+DECLARE
+  v_row public.outbox_events%ROWTYPE;
+  v_base integer := LEAST(GREATEST(COALESCE(p_base_delay_seconds, 60), 5), 3600);
+  v_cap integer;
+  v_max integer := LEAST(GREATEST(COALESCE(p_max_attempts, 8), 1), 20);
+  v_snooze integer := LEAST(GREATEST(COALESCE(p_snooze_seconds, 300), 60), 3600);
+  v_delay double precision;
+BEGIN
+  IF p_outcome IS NULL OR p_outcome NOT IN ('retry', 'discard', 'snooze') THEN
+    RAISE EXCEPTION 'outbox_mark_failed_invalid_outcome' USING ERRCODE = '22023';
+  END IF;
+
+  v_cap := LEAST(GREATEST(v_base, COALESCE(p_max_delay_seconds, 3600)), 86400);
+
+  SELECT *
+    INTO v_row
+    FROM public.outbox_events
+   WHERE id = p_event_id
+     AND status = 'processing'
+     AND metadata->>'claimToken' = p_claim_token
+   FOR UPDATE;
+
+  IF NOT FOUND THEN
+    RETURN 'missed';
+  END IF;
+
+  IF p_outcome = 'discard' OR (p_outcome = 'retry' AND v_row.attempts >= v_max) THEN
+    UPDATE public.outbox_events
+       SET status = 'discarded',
+           error = left(p_error, 2000),
+           metadata = metadata || jsonb_build_object(
+             'discardReason',
+             CASE WHEN p_outcome = 'discard' THEN 'permanent_error' ELSE 'max_attempts' END,
+             'discardedAt', now(),
+             'finalAttempts', v_row.attempts)
+     WHERE id = v_row.id;
+    RETURN 'discarded';
+  END IF;
+
+  IF p_outcome = 'snooze' THEN
+    UPDATE public.outbox_events
+       SET status = 'failed',
+           attempts = GREATEST(v_row.attempts - 1, 0),
+           available_at = now() + make_interval(secs => v_snooze),
+           error = left(p_error, 2000),
+           metadata = metadata || jsonb_build_object(
+             'snoozeCount', COALESCE((metadata->>'snoozeCount')::integer, 0) + 1,
+             'lastSnoozedAt', now())
+     WHERE id = v_row.id;
+    RETURN 'snoozed';
+  END IF;
+
+  v_delay := LEAST(
+               v_cap::double precision,
+               v_base::double precision * power(2, LEAST(GREATEST(v_row.attempts - 1, 0), 16))
+             ) * (0.5 + random() * 0.5);
+
+  UPDATE public.outbox_events
+     SET status = 'failed',
+         available_at = now() + make_interval(secs => v_delay),
+         error = left(p_error, 2000)
+   WHERE id = v_row.id;
+  RETURN 'failed';
+END;
+$$;
+
+-- Hand back rows the caller claimed but never ran -- a drain loop that aborts mid-batch, or
+-- one handler reporting the downstream is out. The attempt taken at claim is refunded for
+-- exactly the same reason as in 'snooze': nothing was tried, so nothing was spent. Ids and
+-- tokens are supplied as parallel arrays and must agree in length, because a mismatch means
+-- the caller lost track of which token belongs to which row and releasing the wrong pairing
+-- would silently release nothing.
+CREATE FUNCTION public.outbox_release_unprocessed(
+  p_event_ids uuid[],
+  p_claim_tokens text[],
+  p_delay_seconds integer DEFAULT 0
+)
+RETURNS integer
+LANGUAGE plpgsql
+SET search_path = public, pg_catalog
+AS $$
+DECLARE
+  v_delay integer := LEAST(GREATEST(COALESCE(p_delay_seconds, 0), 0), 3600);
+  v_count integer;
+BEGIN
+  IF p_event_ids IS NULL OR p_claim_tokens IS NULL
+     OR cardinality(p_event_ids) <> cardinality(p_claim_tokens) THEN
+    RAISE EXCEPTION 'outbox_release_invalid_input' USING ERRCODE = '22023';
+  END IF;
+
+  UPDATE public.outbox_events event
+     SET status = 'pending',
+         available_at = now() + make_interval(secs => v_delay),
+         attempts = GREATEST(event.attempts - 1, 0)
+    FROM unnest(p_event_ids, p_claim_tokens) AS released(id, token)
+   WHERE event.id = released.id
+     AND event.status = 'processing'
+     AND event.metadata->>'claimToken' = released.token;
+
+  GET DIAGNOSTICS v_count = ROW_COUNT;
+  RETURN v_count;
+END;
+$$;