primitive-admin 1.0.62 → 1.0.64

package/dist/src/lib/web-url.js

@@ -0,0 +1,76 @@
+/**
+ * The app's web counterpart, as a normalized web origin (#2982).
+ *
+ * One environment value with two jobs on the iOS side: the emailed sign-in
+ * link points at `<webUrl>/oauth/callback`, and the same origin is what an
+ * incoming universal link is trusted from. Both jobs need an ORIGIN, not just
+ * a URL that parses:
+ *
+ *   - https except loopback, the same rule the server applies to every
+ *     redirect URI (`src/auth/redirect-uri.ts`) — an origin that cannot be
+ *     allow-listed turns every sign-in request into a 400;
+ *   - no path, query or fragment: the web client derives its callback from its
+ *     own origin plus `/oauth/callback` and has no base-path mode, and the
+ *     `apple-app-site-association` component matches that exact path;
+ *   - no credentials, which have no business in a link that goes out by email.
+ *
+ * Returns the `string | true` shape `@inquirer/prompts` expects, like
+ * `validateServerUrl`, so the same function backs the flag check, the project
+ * config's field validation and any future prompt.
+ *
+ * This is the surface that EXPLAINS a rejection. The same rule is applied
+ * silently — value or nothing — by every reader that feeds `primitive.json`
+ * without going through the CLI: `normalizeWebOrigin` in `env-resolver-core.ts`
+ * (which cannot import this file; it is copied verbatim into a package that
+ * must not depend on the CLI), its bash/python3 port in the Swift template's
+ * `resolve-primitive-config.sh`, and `PrimitiveAppState.linksBaseURL` as the
+ * app's own floor. `web-url-parity` in the project-config tests pins that the
+ * two TypeScript halves accept and normalize exactly the same values.
+ */
+const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1"]);
+/** The example every message ends with, so a rejection is actionable. */
+const SHAPE = "e.g. https://app.example.com (or http://localhost:5173 in dev)";
+/**
+ * Validates a web origin. Returns `true` when valid, otherwise the message to
+ * show the user.
+ */
+export function validateWebUrl(value) {
+    if (typeof value !== "string" || !value.trim()) {
+        return `Web URL cannot be empty — ${SHAPE}`;
+    }
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        return `Please enter an absolute URL — ${SHAPE}`;
+    }
+    if (url.protocol !== "https:" && url.protocol !== "http:") {
+        return `Web URL must be http(s) — ${SHAPE}`;
+    }
+    if (url.protocol === "http:" && !LOOPBACK_HOSTS.has(url.hostname)) {
+        return `Web URL must use https outside localhost — the server refuses a non-loopback http redirect URI (${SHAPE})`;
+    }
+    if (url.username || url.password) {
+        return `Web URL must not carry credentials — ${SHAPE}`;
+    }
+    if (url.pathname !== "/" && url.pathname !== "") {
+        return `Web URL must be an origin with no path — the web app serves its sign-in callback on its own origin (${SHAPE})`;
+    }
+    if (url.search) {
+        return `Web URL must not carry a query — ${SHAPE}`;
+    }
+    if (url.hash) {
+        return `Web URL must not carry a fragment — ${SHAPE}`;
+    }
+    return true;
+}
+/**
+ * The origin form of an already-validated web URL: lowercased host, explicit
+ * port kept, no trailing slash — so `https://app.example.com/` and
+ * `https://app.example.com` are stored, compared and joined identically.
+ */
+export function normalizeWebUrl(value) {
+    return new URL(value).origin;
+}
+//# sourceMappingURL=web-url.js.map

package/dist/src/lib/web-url.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-url.js","sourceRoot":"","sources":["../../../src/lib/web-url.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,MAAM,cAAc,GAAG,IAAI,GAAG,CAAC,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC,CAAC;AAE3D,yEAAyE;AACzE,MAAM,KAAK,GAAG,gEAAgE,CAAC;AAE/E;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,KAAa;IAC1C,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC;QAC/C,OAAO,6BAA6B,KAAK,EAAE,CAAC;IAC9C,CAAC;IACD,IAAI,GAAQ,CAAC;IACb,IAAI,CAAC;QACH,GAAG,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC;IACvB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,kCAAkC,KAAK,EAAE,CAAC;IACnD,CAAC;IACD,IAAI,GAAG,CAAC,QAAQ,KAAK,QAAQ,IAAI,GAAG,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;QAC1D,OAAO,6BAA6B,KAAK,EAAE,CAAC;IAC9C,CAAC;IACD,IAAI,GAAG,CAAC,QAAQ,KAAK,OAAO,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;QAClE,OAAO,mGAAmG,KAAK,GAAG,CAAC;IACrH,CAAC;IACD,IAAI,GAAG,CAAC,QAAQ,IAAI,GAAG,CAAC,QAAQ,EAAE,CAAC;QACjC,OAAO,wCAAwC,KAAK,EAAE,CAAC;IACzD,CAAC;IACD,IAAI,GAAG,CAAC,QAAQ,KAAK,GAAG,IAAI,GAAG,CAAC,QAAQ,KAAK,EAAE,EAAE,CAAC;QAChD,OAAO,uGAAuG,KAAK,GAAG,CAAC;IACzH,CAAC;IACD,IAAI,GAAG,CAAC,MAAM,EAAE,CAAC;QACf,OAAO,oCAAoC,KAAK,EAAE,CAAC;IACrD,CAAC;IACD,IAAI,GAAG,CAAC,IAAI,EAAE,CAAC;QACb,OAAO,uCAAuC,KAAK,EAAE,CAAC;IACxD,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,KAAa;IAC3C,OAAO,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC;AAC/B,CAAC"}

package/dist/src/lib/webhook-deliver.d.ts

@@ -0,0 +1,209 @@
+/**
+ * Deliver a signed preview through a webhook's real receive path (#3321).
+ *
+ * `primitive webhooks test --deliver` adds no server dispatch surface. It
+ * composes two capabilities that already exist:
+ *
+ *   1. the admin-gated preview `POST /admin/api/apps/{appId}/webhooks/{id}/test`,
+ *      which signs a payload with the same rule the receiver verifies with, and
+ *   2. the public receive endpoint `POST /app/{appId}/webhook/{webhookKey}`,
+ *      the unauthenticated path a provider posts to.
+ *
+ * So the delivery is a real delivery: the body cap, the availability check, the
+ * IP allowlist, signature verification, handshake rules, deduplication, the run
+ * row and the delivery log all run exactly as they do for a provider. Nobody
+ * gains authority they did not have — only someone who can already administer
+ * the app can obtain a signature — and nothing bypasses verification, because
+ * the signature is checked for real at the receive endpoint.
+ *
+ * ── What this module owes the caller ──────────────────────────────────────
+ *
+ * An honest report. The receive endpoint answers `{received: true}` and
+ * discloses nothing else (it must not: it is unauthenticated), so "did the
+ * function actually run?" is answered from the delivery log and the runs
+ * surface, and only positive evidence may be reported as a dispatch:
+ *
+ *   - **Correlation is one rule.** A delivery-log row NEWER than a baseline
+ *     snapshot taken before the POST, whose `dedupKey` equals the one the
+ *     preview returned. That key hashes the whole signed payload including its
+ *     timestamp prefix, so it is unique to this request rather than a
+ *     heuristic; the baseline is what keeps a replay of the same signed bytes
+ *     from being attributed here. There is no body-hash fallback: identical
+ *     bodies collide, and attributing another request's row is worse than
+ *     declining to.
+ *   - **The key names dispatched deliveries only.** The receiver writes
+ *     `dedupKey` on an `accepted` row that really dispatched and OMITS it
+ *     everywhere else — on a handshake row, a duplicate, a rejection, a 202
+ *     non-dispatch, and on the `accepted` row of a delivery whose target was
+ *     not found (`webhook-receiver.ts`, `logEvent`). That omission is what
+ *     keeps the `eventsByDedupKey` index holding exactly the deliveries that
+ *     may suppress a later one, so it is load-bearing, not incidental. The
+ *     consequence here: a delivery the receiver did not dispatch has no row
+ *     this correlator can reach, and is reported as unconfirmed — with what
+ *     the absence of the key means — rather than named from a row.
+ *   - **A run is confirmed, not assumed.** An `accepted` row names a run id
+ *     before the run finishes, and the legacy workflow branch keeps its
+ *     `accepted` row and its HTTP 200 even when the launch is skipped or
+ *     throws. So the named run is looked up on the authenticated runs surface
+ *     before dispatch is claimed.
+ *   - **Everything else is named for what it was** — a suppressed replay, a
+ *     410/403/401 refusal, each of which the receive endpoint reports for
+ *     itself — or reported as "dispatch unconfirmed", which is where a
+ *     handshake short-circuit (it can legally answer 200 `{received:true}`
+ *     before any dispatch) and a 202 non-dispatch land, since neither records
+ *     a correlatable row. Only a confirmed dispatch exits `0`.
+ */
+export type DeliverOutcome = "dispatched" | "refused" | "unconfirmed";
+export interface WebhookPreview {
+    success?: boolean;
+    payload?: unknown;
+    rawBody: string;
+    signatureHeaders: Record<string, string>;
+    verificationScheme: string;
+    timestamp?: number;
+    /** #3321 — the receive path's key; absent on a pre-upgrade server. */
+    webhookKey?: string | null;
+    /** #3321 — the owning server function, or null for a standalone webhook. */
+    functionId?: string | null;
+    /** #3321 — the correlator; null for scheme `none`. */
+    dedupKey?: string | null;
+}
+export interface WebhookEventRow {
+    eventId: string;
+    status?: string | null;
+    httpStatus?: number | null;
+    rejectionReason?: string | null;
+    dedupKey?: string | null;
+    workflowRunId?: string | null;
+    workflowRunKey?: string | null;
+    createdAt?: string | null;
+    [key: string]: unknown;
+}
+export interface EventPage {
+    items: WebhookEventRow[];
+    nextCursor?: string | null;
+}
+export interface RunPage {
+    items: any[];
+    nextCursor?: string | null;
+}
+/**
+ * The admin reads and the one admin write this flow needs.
+ *
+ * `ApiClient` satisfies it as written; the live api test implements the same
+ * five methods over the test context's authenticated client, which is what lets
+ * this module be proven end to end against a real server.
+ */
+export interface WebhookDeliverClient {
+    testWebhook(appId: string, webhookId: string, payload?: any): Promise<any>;
+    listWebhookEvents(appId: string, webhookId: string, params?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<EventPage>;
+    getWebhook(appId: string, webhookId: string): Promise<any>;
+    listFunctionRuns(appId: string, functionId: string, params?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<RunPage>;
+    listWorkflowRuns(appId: string, workflowId: string, params?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<RunPage>;
+}
+export type FetchLike = (url: string, init: any) => Promise<any>;
+export interface DeliverInput {
+    appId: string;
+    webhookId: string;
+    /** The payload to sign, passed to the preview endpoint unchanged. */
+    payload?: any;
+    /** The API base URL — the receive endpoint lives under it. */
+    serverUrl: string;
+}
+export interface DeliverDeps {
+    client: WebhookDeliverClient;
+    fetchImpl?: FetchLike;
+    sleep?: (ms: number) => Promise<void>;
+    /** Called with the side-effect notice, before anything is delivered. */
+    onBeforeDeliver?: (notice: string[]) => void;
+    /** Bounds, overridable for tests. */
+    pollAttempts?: number;
+    pollIntervalMs?: number;
+    pageCap?: number;
+    pageLimit?: number;
+    runPageCap?: number;
+    runPageLimit?: number;
+    timeoutMs?: number;
+}
+export interface DeliveryAttempt {
+    url: string;
+    /** True once the request left the CLI, whatever came back. */
+    sent: boolean;
+    status: number | null;
+    body: any;
+    duplicate: boolean;
+    /** Why no response was observed, when none was. */
+    error: string | null;
+}
+export interface RunConfirmation {
+    runId: string | null;
+    confirmed: boolean;
+    surface: "function" | "workflow" | null;
+    reason: string | null;
+}
+export interface DeliverResult {
+    outcome: DeliverOutcome;
+    /** One sentence naming what happened. */
+    headline: string;
+    /** Further lines worth printing — remediation, inspection hints. */
+    details: string[];
+    /** The side-effect announcement, printed before the delivery. */
+    notice: string[];
+    preview: WebhookPreview | null;
+    refusal: {
+        message: string;
+        code: string | null;
+    } | null;
+    delivery: DeliveryAttempt | null;
+    event: WebhookEventRow | null;
+    run: RunConfirmation | null;
+}
+/** ~5 attempts over ~4 s: the accepted row is written before execution ends. */
+export declare const DELIVER_POLL_ATTEMPTS = 5;
+export declare const DELIVER_POLL_INTERVAL_MS = 800;
+/** Cursor pages walked per attempt, so a busy log cannot outrun the poll. */
+export declare const DELIVER_PAGE_CAP = 10;
+export declare const DELIVER_PAGE_LIMIT = 25;
+/** The same bound on the runs surface, where runs start while this one waits. */
+export declare const DELIVER_RUN_PAGE_CAP = 5;
+export declare const DELIVER_RUN_PAGE_LIMIT = 50;
+/** Comfortably above the sync-function ceiling. */
+export declare const DELIVER_TIMEOUT_MS = 60000;
+/**
+ * What the user is told before a delivery happens, in the terminal rather than
+ * only in the guide: a diagnostic that mutates the app has to say so where the
+ * user is looking (criterion 4).
+ */
+export declare function deliveryNotice(scheme: string): string[];
+/**
+ * The one correlation rule: the newest row above `baselineEventId` whose
+ * `dedupKey` equals this preview's.
+ *
+ * The walk is newest-first and follows `nextCursor`, stopping at the baseline
+ * row (every row below it predates this delivery) or at `pageCap`. A null
+ * baseline means the log was empty when the snapshot was taken, so every row
+ * walked is a candidate.
+ */
+export declare function findDeliveryEvent(input: {
+    client: WebhookDeliverClient;
+    appId: string;
+    webhookId: string;
+    dedupKey: string;
+    baselineEventId: string | null;
+    pageCap?: number;
+    pageLimit?: number;
+}): Promise<WebhookEventRow | null>;
+/**
+ * Preview, deliver, correlate, confirm — the whole flow, as one result a caller
+ * renders however it likes.
+ */
+export declare function deliverWebhookTest(input: DeliverInput, deps: DeliverDeps): Promise<DeliverResult>;