@iann29/rastro 0.10.8 → 0.11.0

package/docs/upgrading.md

@@ -1,5 +1,80 @@
 # Upgrading Amage Rastro
 
+## Meta Lead Ads (0.11.0)
+
+Additive: new tables only, and a host that does not opt in changes nothing (no
+env var, re-export or handler, and its manifest advertises nothing new). Lead
+reads widen `channel` from `"whatsapp"` to `"whatsapp" | "form"` and may carry
+the origins `lead_form` and `lead_form_organic`; a host that switches on
+`channel` or on origins handles the new values. A host that brings Meta instant
+forms into its CRM, in one deploy:
+
+1. Declares two more optional env bindings and passes them to the component:
+
+   ```ts
+   const app = defineApp({
+     env: {
+       // ...the Meta bindings of 0.10.0
+       RASTRO_FEDERATION_ISSUER: v.optional(v.string()),
+       RASTRO_FEDERATION_AUDIENCE: v.optional(v.string()),
+     },
+   });
+   app.use(rastro, {
+     env: {
+       // ...
+       RASTRO_FEDERATION_ISSUER: app.env.RASTRO_FEDERATION_ISSUER,
+       RASTRO_FEDERATION_AUDIENCE: app.env.RASTRO_FEDERATION_AUDIENCE,
+     },
+   });
+   ```
+
+   Set `RASTRO_FEDERATION_AUDIENCE` on the deployment to the host's functions
+   URL (the `applicationID` its `auth.config.ts` names). The issuer defaults to
+   the production dashboard; a host paired with another dashboard (a DEV control
+   plane) sets `RASTRO_FEDERATION_ISSUER` to that dashboard's issuer, the one
+   its `auth.config.ts` trusts. Without the audience the leadgen route answers
+   503 and `linkPage` refuses with `FEDERATION_NOT_CONFIGURED`; with an issuer
+   other than the dashboard's, the dashboard routes no lead to the host.
+
+2. Registers its form lead handler, an internal mutation validated by
+   `formLeadPayloadValidator`, once:
+   `rastro.setFormLeadHandler(ctx, { handle: await createFunctionHandle(internal.crm.formLeadArrived) })`.
+   This is the opt-in: from here on each Meta connect and `listMetaAdAccounts`
+   also reads the owner's Facebook Pages and keeps each Page's token sealed, and
+   the owners already connected have theirs read right away. A host that never
+   registers it makes no Pages read and keeps no Page token: registering the
+   handler is what makes Pages appear in Formulários, and until then the screen
+   says the host is not ready (`metaLinkedPages` answers `handlerReady: false`).
+3. Passes `metaLeads: true` to `exposeFederatedAnalyticsApi` (with
+   `metaAds: true`: `metaLeads` alone throws at setup) and re-exports
+   `metaPages`, `metaForms`, `metaFormRules`, `simulateMetaFormRules`,
+   `metaFormsReport`, `metaLinkedPages`, `linkMetaPage`, `unlinkMetaPage`,
+   `refreshMetaForms`, `setMetaFormRules` and `returnMetaFormLead`.
+4. Asks the dashboard operator to add the connection's deployment origin
+   (`https://<name>.convex.cloud`, the functions URL) to the control plane's
+   `RASTRO_META_LEADS_DEPLOYMENT_ORIGINS`, and, when the host's site URL is a
+   custom domain, that origin to `RASTRO_FEDERATION_ALLOWED_DEPLOYMENT_ORIGINS`.
+   Until then the dashboard forwards no webhook to the host, and leads arrive
+   only through the 15-minute reconciliation.
+5. Deploys and uses **Verificar novamente** in the dashboard's Conexões.
+
+`metaLinkedPages` answers
+`{ pages, leadgenReady, issuer, audience, handlerReady }`; the dashboard routes
+a Page to the host only when `leadgenReady` is true, `issuer` is its own and
+`audience` is the host's deployment URL. Forwarding needs the component mounted
+with `httpPrefix: "/rastro/"`, the path the dashboard posts to. `metaPages` and
+`metaForms` give a Page's `lastError` as a code (`META_PAGE_ERROR_CODES`), and
+`metaPages` adds `handlerReady`. `leadsDaily` takes `origin: "paid"` for every
+lead an ad bought (`ctwa_ad` and `lead_form`) with their spend, and every host
+serving `leads` advertises `leadsPaid` to say so.
+
+See [Meta ads, Lead Ads](meta-ads.md#lead-ads-instant-forms).
+
+## Sent means Meta received it (0.10.9)
+
+Install `@iann29/rastro@0.10.9` and deploy the host. No schema, env or export
+change.
+
 ## The spend sync finishes its ranges (0.10.8)
 
 Install `@iann29/rastro@0.10.8` and deploy the host. No schema, env or export

package/llms.txt

@@ -37,6 +37,7 @@ Do not infer federation availability from this website, a dist-tag, or a source
 - A host on 0.5.0 re-exports `listTrackedLinks`, `createTrackedLink`, `updateTrackedLink` and `deleteTrackedLink` from that module and reverifies, which advertises the optional `trackedLinks` capability; listing needs a reader, the other three need `analytics:configure`. A host that skips it keeps working without the capability.
 - A host on 0.8.0 that records leads from its server re-exports `leadsReport`, `listLeads` and `leadJourney` and passes `leads: true` to `exposeFederatedAnalyticsApi`, which advertises the opt-in `leads` capability for any reader; without the option the three refuse and nothing is advertised.
 - A host on 0.10.0 also re-exports `leadsDaily` under `leads`. One that links Meta ad accounts or a pixel passes `metaAds: true` and re-exports `metaStatus` and `metaConversions`, which advertises the opt-in `metaAds` capability for any reader; without the option those two refuse with `FEDERATION_INVALID_SCOPE`. With `metaAds: true` the host also exports the dashboard's own Meta setup (`metaConnection`, `metaEventMap`, `metaUnlinkPreview`, and the `analytics:configure` writes `connectMeta`, `refreshMetaAccounts`, `setMetaPixel`, `disconnectMeta`, `linkMetaAdAccount`, `unlinkMetaAdAccount`, `removeMetaPixel`, `setMetaEventMap`, `syncMetaNow`) plus the internal `authorizeMetaAction`; see docs/upgrading.md for the 0.10.0 steps.
+- A host whose CRM takes Meta instant-form leads (Lead Ads, unreleased after 0.10.9) passes `metaLeads: true` beside `metaAds: true` (alone it throws at setup), passes `RASTRO_FEDERATION_ISSUER` and `RASTRO_FEDERATION_AUDIENCE` to the component in `app.use`, registers a form lead handler with `setFormLeadHandler`, re-exports `metaPages`, `metaForms`, `metaFormRules`, `simulateMetaFormRules`, `metaFormsReport`, `metaLinkedPages`, `linkMetaPage`, `unlinkMetaPage`, `refreshMetaForms`, `setMetaFormRules` and `returnMetaFormLead`, and asks the dashboard operator to list its deployment origin in `RASTRO_META_LEADS_DEPLOYMENT_ORIGINS`; a form lead's personal answers are never stored or logged by the component. See docs/upgrading.md.
 - Expose only the manifest, connection status, site summaries, reports, journeys, conversions, affiliates, funnels, goals, web vitals, coverage, tracked links, and the configure functions listed in the manifest; the configure functions run only when the token and the local grant both carry `analytics:configure`. A public link's token carries `analytics:public` alone and reaches only the manifest, connection status, site summaries, a redacted overview, redacted live visitors, and coverage, and only when the local grant lists `analytics:public`.
 - Use the functions URL as JWT audience and the HTTP-actions URL for tracker ingestion.
 - Rehearse on an explicit development target. Production changes require fresh operator consent.

package/package.json

@@ -6,7 +6,7 @@
   "bugs": {
     "url": "https://github.com/amageweb/amage-rastro/issues"
   },
-  "version": "0.10.8",
+  "version": "0.11.0",
   "license": "Apache-2.0",
   "publishConfig": {
     "access": "public"

package/src/component/_generated/api.ts

@@ -22,6 +22,10 @@ import type * as guards from "../guards.js";
 import type * as http from "../http.js";
 import type * as identity from "../identity.js";
 import type * as ingest from "../ingest.js";
+import type * as leadAdsValidators from "../leadAdsValidators.js";
+import type * as leadFormRules from "../leadFormRules.js";
+import type * as leadFormStore from "../leadFormStore.js";
+import type * as leadgenToken from "../leadgenToken.js";
 import type * as leads from "../leads.js";
 import type * as live from "../live.js";
 import type * as localTime from "../localTime.js";
@@ -29,6 +33,7 @@ import type * as meta from "../meta.js";
 import type * as metaCapi from "../metaCapi.js";
 import type * as metaFake from "../metaFake.js";
 import type * as metaGraph from "../metaGraph.js";
+import type * as metaLeads from "../metaLeads.js";
 import type * as metaSync from "../metaSync.js";
 import type * as origin from "../origin.js";
 import type * as people from "../people.js";
@@ -69,6 +74,10 @@ const fullApi: ApiFromModules<{
   http: typeof http;
   identity: typeof identity;
   ingest: typeof ingest;
+  leadAdsValidators: typeof leadAdsValidators;
+  leadFormRules: typeof leadFormRules;
+  leadFormStore: typeof leadFormStore;
+  leadgenToken: typeof leadgenToken;
   leads: typeof leads;
   live: typeof live;
   localTime: typeof localTime;
@@ -76,6 +85,7 @@ const fullApi: ApiFromModules<{
   metaCapi: typeof metaCapi;
   metaFake: typeof metaFake;
   metaGraph: typeof metaGraph;
+  metaLeads: typeof metaLeads;
   metaSync: typeof metaSync;
   origin: typeof origin;
   people: typeof people;

package/src/component/_generated/component.ts

@@ -281,9 +281,36 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             revenueCents: number | null;
             type: "created" | "qualified" | "won" | "lost" | "open";
           }>;
+          form?: {
+            answers: Array<{
+              label: string;
+              questionKey: string;
+              values: Array<string>;
+            }>;
+            decision: { column: string | null } | { discard: string };
+            leadgenId: string;
+            origin: {
+              adId: string | null;
+              adName: string | null;
+              adsetId: string | null;
+              adsetName: string | null;
+              campaignId: string | null;
+              campaignName: string | null;
+              formId: string;
+              formName: string | null;
+              isOrganic: boolean;
+              pageId: string;
+              pageName: string | null;
+              platform: string | null;
+            };
+            receivedAt: number;
+            returned: { at: number; reason: string } | null;
+            ruleIndex: number | null;
+            rulePath: Array<number>;
+          } | null;
           lead: {
             adId: string | null;
-            channel: "whatsapp";
+            channel: "whatsapp" | "form";
             entryPoint: string | null;
             firstAt: number;
             hasVisitor: boolean;
@@ -313,7 +340,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
         },
         Array<{
           adId: string | null;
-          channel: "whatsapp";
+          channel: "whatsapp" | "form";
           entryPoint: string | null;
           firstAt: number;
           hasVisitor: boolean;
@@ -339,7 +366,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             sourceUrl?: string;
             title?: string;
           };
-          channel: "whatsapp";
+          channel: "whatsapp" | "form";
           column?: string;
           entryPoint?: string;
           label?: string;
@@ -501,23 +528,6 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
         },
         Name
       >;
-      connectWithCode: FunctionReference<
-        "action",
-        "internal",
-        { code: string; ownerKey: string; redirectUri: string },
-        {
-          adAccounts: Array<{
-            adAccountId: string;
-            currency: string;
-            name: string;
-            timezone: string;
-          }>;
-          businessName: string | null;
-          connectionId: string;
-          pixels: Array<{ name: string; pixelId: string }>;
-        },
-        Name
-      >;
       connection: FunctionReference<
         "query",
         "internal",
@@ -550,6 +560,23 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
         Array<string>,
         Name
       >;
+      connectWithCode: FunctionReference<
+        "action",
+        "internal",
+        { code: string; ownerKey: string; redirectUri: string },
+        {
+          adAccounts: Array<{
+            adAccountId: string;
+            currency: string;
+            name: string;
+            timezone: string;
+          }>;
+          businessName: string | null;
+          connectionId: string;
+          pixels: Array<{ name: string; pixelId: string }>;
+        },
+        Name
+      >;
       conversions: FunctionReference<
         "query",
         "internal",
@@ -698,6 +725,248 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
         Name
       >;
     };
+    metaLeads: {
+      formRules: FunctionReference<
+        "query",
+        "internal",
+        { formId: string; now?: number; ownerKey?: string; siteId: string },
+        {
+          configured: boolean;
+          entryColumn: string | null;
+          firstContact: {
+            brakes?: {
+              businessHoursOnly: boolean;
+              maxPerHour: number;
+              waitMinutes: number;
+            };
+            mode: "lead_starts" | "one_click" | "automatic";
+            text?: string;
+          };
+          formId: string;
+          own?: boolean;
+          rules: Array<{
+            answers: Array<string>;
+            monthCount: number | null;
+            questionKey: string;
+            to: { column: string } | { discard: string };
+          }>;
+          siteId: string;
+          updatedAt: number | null;
+          whatsappButtonConfirmed: boolean;
+        },
+        Name
+      >;
+      forms: FunctionReference<
+        "query",
+        "internal",
+        { now?: number; ownerKey?: string; siteId: string },
+        Array<{
+          forms: Array<{
+            createdTime: number | null;
+            daily: Array<number> | null;
+            formId: string;
+            lastLeadAt: number | null;
+            leads30d: number | null;
+            name: string;
+            questions: Array<{
+              key: string;
+              label: string;
+              options?: Array<{ key: string; value: string }>;
+              type: string;
+            }>;
+            rules: {
+              configured: boolean;
+              count: number;
+              entryColumn: string | null;
+              own?: boolean;
+            };
+            status: string;
+            syncedAt: number;
+            whatsappButton: boolean | null;
+            whatsappButtonConfirmed: boolean;
+          }>;
+          handlerReady: boolean;
+          lastError:
+            | "META_TOKEN_INVALID"
+            | "META_PERMISSION_MISSING"
+            | "HANDLER_MISSING"
+            | "HANDLER_FAILED"
+            | "HANDLER_GAVE_UP"
+            | "SECRETS_KEY_MISSING"
+            | "META_TRUNCATED"
+            | "META_RATE_LIMITED"
+            | "META_UNAVAILABLE"
+            | "RUN_TIMEOUT"
+            | null;
+          lastLeadAt: number | null;
+          lastReconcileAt: number | null;
+          leadsAllowed: boolean;
+          own?: boolean;
+          pageId: string;
+          pageName: string;
+          subscribedAt: number | null;
+        }>,
+        Name
+      >;
+      formsReport: FunctionReference<
+        "query",
+        "internal",
+        { from: number; siteIds: Array<string>; to: number },
+        {
+          forms: Array<{
+            columns: Array<{ column: string; leads: number }>;
+            discarded: Array<{ leads: number; reason: string }>;
+            entry: number;
+            formId: string;
+            leads: number;
+            name: string | null;
+            pageId: string;
+            qualified: number;
+            returned: number;
+            revenueCents: number;
+            siteId: string;
+            won: number;
+          }>;
+          partial: boolean;
+        },
+        Name
+      >;
+      linkedPages: FunctionReference<
+        "query",
+        "internal",
+        { siteIds: Array<string> },
+        {
+          audience: string | null;
+          handlerReady: boolean;
+          issuer: string;
+          leadgenReady: boolean;
+          pages: Array<{ pageId: string; siteId: string }>;
+        },
+        Name
+      >;
+      linkPage: FunctionReference<
+        "action",
+        "internal",
+        {
+          backfillDays?: number;
+          onlyOwn?: boolean;
+          ownerKey: string;
+          pageId: string;
+          siteId: string;
+        },
+        { forms: number; linked: boolean },
+        Name
+      >;
+      pages: FunctionReference<
+        "query",
+        "internal",
+        { ownerKey: string },
+        Array<{
+          handlerReady: boolean;
+          lastError:
+            | "META_TOKEN_INVALID"
+            | "META_PERMISSION_MISSING"
+            | "HANDLER_MISSING"
+            | "HANDLER_FAILED"
+            | "HANDLER_GAVE_UP"
+            | "SECRETS_KEY_MISSING"
+            | "META_TRUNCATED"
+            | "META_RATE_LIMITED"
+            | "META_UNAVAILABLE"
+            | "RUN_TIMEOUT"
+            | null;
+          leadsAllowed: boolean;
+          linkedOutsideScope?: boolean;
+          linkedSiteId: string | null;
+          name: string;
+          own: boolean | null;
+          pageId: string;
+          subscribedAt: number | null;
+          tasks: Array<string>;
+        }>,
+        Name
+      >;
+      refreshForms: FunctionReference<
+        "action",
+        "internal",
+        { pageId?: string; siteId: string },
+        { forms: number; pages: number },
+        Name
+      >;
+      returnFormLead: FunctionReference<
+        "mutation",
+        "internal",
+        { leadId: string; ownerKey?: string; siteId: string },
+        { returned: boolean },
+        Name
+      >;
+      setFormLeadHandler: FunctionReference<
+        "mutation",
+        "internal",
+        { handle: string | null },
+        null,
+        Name
+      >;
+      setFormRules: FunctionReference<
+        "mutation",
+        "internal",
+        {
+          entryColumn: string | null;
+          firstContact: {
+            brakes?: {
+              businessHoursOnly: boolean;
+              maxPerHour: number;
+              waitMinutes: number;
+            };
+            mode: "lead_starts" | "one_click" | "automatic";
+            text?: string;
+          };
+          formId: string;
+          onlyOwn?: boolean;
+          ownerKey?: string;
+          rules: Array<{
+            answers: Array<string>;
+            questionKey: string;
+            to: { column: string } | { discard: string };
+          }>;
+          siteId: string;
+          whatsappButtonConfirmed?: boolean;
+        },
+        null,
+        Name
+      >;
+      simulateFormRules: FunctionReference<
+        "query",
+        "internal",
+        {
+          entryColumn: string | null;
+          formId: string;
+          now: number;
+          rules: Array<{
+            answers: Array<string>;
+            questionKey: string;
+            to: { column: string } | { discard: string };
+          }>;
+          siteId: string;
+        },
+        {
+          columns: Array<{ column: string; leads: number }>;
+          discarded: Array<{ leads: number; reason: string }>;
+          entry: number;
+          partial: boolean;
+          rules: Array<number>;
+          total: number;
+        },
+        Name
+      >;
+      unlinkPage: FunctionReference<
+        "action",
+        "internal",
+        { ownerKey?: string; pageId: string; siteId: string },
+        { unlinked: boolean },
+        Name
+      >;
+    };
     people: {
       backfillSearch: FunctionReference<
         "mutation",

package/src/component/_generated/server.ts

@@ -40,6 +40,8 @@ type Env = {
   readonly CONVEX_CLOUD_URL: string;
   readonly CONVEX_SITE_URL: string;
   readonly RASTRO_CLIENT_RATE_LIMIT: "off" | undefined;
+  readonly RASTRO_FEDERATION_AUDIENCE: string | undefined;
+  readonly RASTRO_FEDERATION_ISSUER: string | undefined;
   readonly RASTRO_GEOIP_DAILY_LIMIT: string | undefined;
   readonly RASTRO_GEOIP_PROVIDER: "ipinfo" | "ipwhois" | undefined;
   readonly RASTRO_GEOIP_TOKEN: string | undefined;

package/src/component/constants.ts

@@ -118,3 +118,36 @@ export const MAX_SITE_MAP_ROUTES_PER_DAY = 200;
 export const ROUTE_TRANSITION_SLOTS = 24;
 export const MAX_SITE_MAP_ROWS = 8_000;
 export const SITE_MAP_OTHER_ROUTE = "(other)";
+
+/**
+ * `leads.daily`'s `origin` for every paid origin together (`ctwa_ad` and
+ * `lead_form`), with the spend that bought them (decision D4). A host on a
+ * release before it counts nothing under this key, so a dashboard asks for it
+ * only where the host serves Lead Ads, the only hosts with `lead_form` leads.
+ */
+export const PAID_LEADS_ORIGIN = "paid";
+
+/**
+ * The token a control plane signs to hand one Meta lead notification to a
+ * host (`POST <host site>/rastro/meta/leadgen`, contract §12.3/§12.4). The
+ * control plane signs it and the host's leadgen route verifies it, so both
+ * read these names from here. Same issuer, keys and audience as a federation
+ * connection token, but no `rastro_permissions`: it can never be replayed as a
+ * read token, and the route requires the purpose claim, which no connection
+ * token carries. The Page and lead claims must equal the request body's.
+ */
+export const META_LEADGEN_TOKEN = Object.freeze({
+  purpose: "meta_leadgen",
+  subject: "rastro:meta-webhook",
+  /** What the control plane signs; the host refuses a longer-lived token. */
+  lifetimeSeconds: 120,
+  maxLifetimeSeconds: 600,
+  claims: Object.freeze({
+    purpose: "rastro_purpose",
+    connectionId: "rastro_connection_id",
+    organizationId: "rastro_organization_id",
+    version: "rastro_connection_version",
+    pageId: "rastro_page_id",
+    leadgenId: "rastro_leadgen_id",
+  } as const),
+} as const);

package/src/component/convex.config.ts

@@ -21,5 +21,12 @@ export default defineComponent("rastroAnalytics", {
     // both, only a pasted token connects.
     RASTRO_META_APP_ID: v.optional(v.string()),
     RASTRO_META_APP_SECRET: v.optional(v.string()),
+    // The Rastro dashboard's federation issuer and this host's audience, the
+    // same values the host trusts in its auth.config.ts. The Lead Ads route
+    // (`/meta/leadgen`, http.ts) checks the control plane's forwarding token
+    // against them. The issuer defaults to the production dashboard; without
+    // the audience (the host's functions URL) it refuses every forward.
+    RASTRO_FEDERATION_ISSUER: v.optional(v.string()),
+    RASTRO_FEDERATION_AUDIENCE: v.optional(v.string()),
   },
 });

package/src/component/errors.ts

@@ -14,7 +14,9 @@ export type RastroErrorCode =
   | "SECRETS_KEY_MISSING"
   | "META_TOKEN_INVALID"
   | "META_LOGIN_UNAVAILABLE"
-  | "META_UNAVAILABLE";
+  | "META_UNAVAILABLE"
+  | "META_PERMISSION_MISSING"
+  | "FEDERATION_NOT_CONFIGURED";
 
 export function fail(
   code: RastroErrorCode,

package/src/component/http.ts

@@ -19,6 +19,11 @@ import {
   resolveGeoIp,
 } from "./geo.js";
 import { isPlainRecord } from "./guards.js";
+import {
+  LeadgenTokenError,
+  leadgenTrust,
+  verifyLeadgenToken,
+} from "./leadgenToken.js";
 import { alignClock, sanitizeEvent } from "./sanitize.js";
 import { deriveClientKey, deriveVisitorKey, randomSecret } from "./identity.js";
 import { isTrackedLinkSlug, trackedLinkLocation } from "./trackedLinks.js";
@@ -348,6 +353,76 @@ http.route({
   }),
 });
 
+// Lead Ads: the control plane forwards Meta's `leadgen` webhook here, one
+// lead at a time, with a short-lived token from the federation issuer bound
+// to the Page and the lead (leadgenToken.ts). Only ids travel: the lead is
+// read from Meta with the Page's own token, then handed to the host.
+const MAX_LEADGEN_BODY = 4_096;
+http.route({
+  path: "/meta/leadgen",
+  method: "POST",
+  handler: httpAction(async (ctx, request) => {
+    // The same trust `metaLinkedPages` reports to the control plane
+    // (`leadgenReady`, `issuer`), so it never routes a Page here that this
+    // route would refuse.
+    const { issuer, audience } = leadgenTrust(env);
+    if (!audience) {
+      return json({ error: { code: "FEDERATION_NOT_CONFIGURED" } }, 503);
+    }
+    let pageId: string;
+    let leadgenId: string;
+    try {
+      const bytes = await readLimitedBody(request, MAX_LEADGEN_BODY);
+      const body: unknown = JSON.parse(new TextDecoder().decode(bytes));
+      if (!isPlainRecord(body)) throw new Error("body");
+      if (
+        typeof body.pageId !== "string" ||
+        typeof body.leadgenId !== "string" ||
+        !/^\d{1,32}$/u.test(body.pageId) ||
+        !/^\d{1,32}$/u.test(body.leadgenId)
+      ) {
+        throw new Error("ids");
+      }
+      pageId = body.pageId;
+      leadgenId = body.leadgenId;
+    } catch {
+      return json({ error: { code: "INVALID_BODY" } }, 400);
+    }
+    const authorization = request.headers.get("authorization") ?? "";
+    const token = /^Bearer\s+(\S+)$/iu.exec(authorization)?.[1];
+    if (!token) return json({ error: { code: "UNAUTHENTICATED" } }, 401);
+    try {
+      await verifyLeadgenToken(token, { issuer, audience, pageId, leadgenId });
+    } catch (error) {
+      if (error instanceof LeadgenTokenError) {
+        console.warn(
+          `[rastro] refused a leadgen forward for Page ${pageId}: ${error.reason}`,
+        );
+        // The issuer's keys could not be read: not the token's fault, and the
+        // control plane retries a 503 (a 401 is final for the forward).
+        if (error.transient) {
+          return json({ error: { code: "ISSUER_UNREACHABLE" } }, 503);
+        }
+        return json({ error: { code: "UNAUTHENTICATED" } }, 401);
+      }
+      throw error;
+    }
+    const { scheduled } = await ctx.runMutation(
+      internal.metaLeads.scheduleLeadgen,
+      { pageId, leadgenId },
+    );
+    // A Page this host does not link is not an error for the forwarder:
+    // retrying would change nothing.
+    return json(
+      {
+        accepted: scheduled,
+        ...(scheduled ? {} : { reason: "PAGE_NOT_LINKED" }),
+      },
+      scheduled ? 202 : 200,
+    );
+  }),
+});
+
 http.route({
   path: "/health",
   method: "GET",