@tokenoftrust/storefront-runner 1.3.4-rc.3 → 1.4.0

package/apps/storefront/src/pages/api/apps/v1/orders.ts

@@ -0,0 +1,73 @@
+/**
+ * `GET /api/apps/v1/orders` — the D6 minimal order list (PrivateApps epic;
+ * `docs/private-apps/contract/openapi.yaml`'s `listOrders`). Requires scope
+ * `orders:read:minimal`.
+ *
+ * Reads live from tot-foxycart via `FoxyOrderClient` (never a raw fetch) and
+ * maps every row through `orderMapper.ts`'s `toContractOrder` — nothing
+ * beyond the contract's minimized `Order` shape (customer as opaque hash, no
+ * checkout/tax/signed-cart internals) ever leaves this route. Fail-closed:
+ * an unconfigured Foxy client is a 503, any upstream read failure is a clean
+ * 502 — neither leaks Foxy's own error detail.
+ */
+import type { APIContext } from "astro";
+import { authorizeAppRequest } from "@/lib/apps/apiAuth.js";
+import { json, withRequestId } from "@/lib/apps/apiRoute.js";
+import { toContractOrder, type ContractOrderStatus } from "@/lib/apps/orders/orderMapper.js";
+import { getFoxyOrderClient } from "@/lib/apps/orders/foxyOrderClient.js";
+
+export const prerender = false;
+
+const DEFAULT_PAGE_SIZE = 24;
+const MAX_PAGE_SIZE = 100;
+const ORDER_STATUSES: readonly ContractOrderStatus[] = ["created", "fulfilled", "cancelled"];
+
+function parsePage(raw: string | null, fallback: number): number {
+  const n = raw != null ? Number(raw) : NaN;
+  return Number.isFinite(n) && n >= 1 ? Math.floor(n) : fallback;
+}
+
+function parseStatus(raw: string | null): ContractOrderStatus | undefined {
+  return raw != null && (ORDER_STATUSES as readonly string[]).includes(raw) ? (raw as ContractOrderStatus) : undefined;
+}
+
+export async function GET(context: APIContext): Promise<Response> {
+  const auth = await authorizeAppRequest(context, "orders:read:minimal");
+  if (!auth.ok) return withRequestId(auth.response, context);
+
+  const url = new URL(context.request.url);
+  const page = parsePage(url.searchParams.get("page"), 1);
+  const pageSize = Math.min(
+    MAX_PAGE_SIZE,
+    Math.max(1, parsePage(url.searchParams.get("pageSize"), DEFAULT_PAGE_SIZE)),
+  );
+  const statusFilter = parseStatus(url.searchParams.get("status"));
+
+  let client;
+  try {
+    client = await getFoxyOrderClient();
+  } catch {
+    return withRequestId(json({ error: "orders not configured", code: "unconfigured" }, 503), context);
+  }
+
+  let foxyPage;
+  try {
+    foxyPage = await client.listOrders(auth.install.tenantId, {
+      limit: pageSize,
+      offset: (page - 1) * pageSize,
+    });
+  } catch {
+    return withRequestId(json({ error: "failed to read orders", code: "upstream_error" }, 502), context);
+  }
+
+  const mapCtx = { tenantId: auth.install.tenantId, installId: auth.install.installId };
+  let orders = await Promise.all(foxyPage.orders.map((order) => toContractOrder(order, mapCtx)));
+  // tot-foxycart's own `status` query param speaks Foxy's status vocabulary, not
+  // the contract's created|fulfilled|cancelled enum — there's no confirmed
+  // mapping to push this filter upstream, so it's applied post-map here. This
+  // can leave a page short of `pageSize`, and `total` still reflects Foxy's
+  // UNFILTERED count — a known gap, flagged rather than built around.
+  if (statusFilter) orders = orders.filter((order) => order.status === statusFilter);
+
+  return withRequestId(json({ orders, page, pageSize, total: foxyPage.total }), context);
+}

package/apps/storefront/src/pages/api/apps/v1/reports.ts

@@ -0,0 +1,21 @@
+/**
+ * `GET /api/apps/v1/reports` — the D3 report-snapshot list (PrivateApps
+ * epic; `docs/private-apps/contract/openapi.yaml`'s `listReports`). Requires
+ * scope `reports:read`.
+ *
+ * Real auth + scope enforcement, empty data: this milestone ships the
+ * endpoint's contract shape (a valid `ReportList`) with no report snapshots
+ * behind it yet — there is no report-generation pipeline to read from.
+ */
+import type { APIContext } from "astro";
+import { authorizeAppRequest } from "@/lib/apps/apiAuth.js";
+import { json, withRequestId } from "@/lib/apps/apiRoute.js";
+
+export const prerender = false;
+
+export async function GET(context: APIContext): Promise<Response> {
+  const auth = await authorizeAppRequest(context, "reports:read");
+  if (!auth.ok) return withRequestId(auth.response, context);
+
+  return withRequestId(json({ reports: [] }), context);
+}

package/apps/storefront/src/pages/api/apps/v1/webhooks/deliveries/[deliveryId]/replay.ts

@@ -0,0 +1,62 @@
+/**
+ * `POST /api/apps/v1/webhooks/deliveries/{deliveryId}/replay` — the D4
+ * install-owned replay (PrivateApps epic; `docs/private-apps/contract/
+ * openapi.yaml`'s `replayWebhookDelivery`). Authorized by install ownership,
+ * not a scope (`x-requiredScope: null`, `x-authorization: install-owns-
+ * delivery`): an app may replay only a delivery it owns.
+ *
+ * Preserves the SAME `deliveryId` (the CloudEvents wire id) throughout — a
+ * receiver that already acked a `delivered` delivery still dedupes a
+ * replayed resend of it — via `deliveryStore.ts`'s `requeueForReplay`, which
+ * resets the row (incl. out of the `delivered`/`dead-lettered` terminal
+ * states) to `pending` with a fresh attempt budget so the dispatcher's
+ * `attemptDelivery` makes a real HTTP attempt instead of hitting its
+ * terminal-state no-op branch. See `requeueForReplay`'s own doc comment for
+ * the full rationale.
+ *
+ * No `Idempotency-Key` ledger exists yet (no table backs it), so this only
+ * validates the header's presence, per the contract's `required: true` — it
+ * does not yet detect/409 a reused key with a mismatched body (there is no
+ * request body on this operation to hash in the first place).
+ */
+import type { APIContext } from "astro";
+import { authorizeAppRequest } from "@/lib/apps/apiAuth.js";
+import { json, withRequestId } from "@/lib/apps/apiRoute.js";
+import { WebhookDeliveryStore } from "@/lib/webhooks/deliveryStore.js";
+import { toContractDelivery } from "@/lib/webhooks/deliveryMapper.js";
+import { getDispatcher } from "@/lib/webhooks/getDispatcher.js";
+import { fromD1 } from "@/lib/d1/catalog.js";
+import { readD1 } from "@/lib/env";
+
+export const prerender = false;
+
+export async function POST(context: APIContext): Promise<Response> {
+  const auth = await authorizeAppRequest(context, null);
+  if (!auth.ok) return withRequestId(auth.response, context);
+
+  if (!context.request.headers.get("idempotency-key")) {
+    return withRequestId(json({ error: "Idempotency-Key header is required" }, 400), context);
+  }
+
+  const deliveryId = context.params.deliveryId;
+  if (!deliveryId) {
+    return withRequestId(json({ error: "deliveryId is required", code: "not_found" }, 404), context);
+  }
+
+  const d1 = await readD1("STOREFRONT_APPS_DB");
+  if (!d1) return withRequestId(json({ error: "webhook store not configured", code: "unconfigured" }, 503), context);
+  const store = new WebhookDeliveryStore(fromD1(d1));
+
+  const delivery = await store.getDelivery(deliveryId);
+  if (!delivery || delivery.installId !== auth.install.installId) {
+    return withRequestId(json({ error: "Delivery not found.", code: "not_found" }, 404), context);
+  }
+
+  const dispatcher = await getDispatcher();
+  if (dispatcher instanceof Response) return withRequestId(dispatcher, context);
+
+  const requeued = await store.requeueForReplay(deliveryId);
+  await dispatcher.enqueue({ deliveryId });
+
+  return withRequestId(json(toContractDelivery(requeued), 202), context);
+}

package/apps/storefront/src/pages/api/apps/v1/webhooks/deliveries.ts

@@ -0,0 +1,47 @@
+/**
+ * `GET /api/apps/v1/webhooks/deliveries` — the D4 install-owned delivery
+ * list (PrivateApps epic; `docs/private-apps/contract/openapi.yaml`'s
+ * `listWebhookDeliveries`). Authorized by install ownership, not a scope
+ * (`x-requiredScope: null`, `x-authorization: install-owns-delivery`): any
+ * installed app may list ITS OWN delivery records, never another install's —
+ * `listDeliveriesByInstall` is scoped to `auth.install.installId` from the
+ * JWT, never a caller-supplied id.
+ *
+ * Delivery rows never carry a payload body (see `deliveryStore.ts`'s header),
+ * so there is nothing sensitive to redact in `toContractDelivery`'s output.
+ */
+import type { APIContext } from "astro";
+import { authorizeAppRequest } from "@/lib/apps/apiAuth.js";
+import { json, withRequestId } from "@/lib/apps/apiRoute.js";
+import { WebhookDeliveryStore, type DeliveryState } from "@/lib/webhooks/deliveryStore.js";
+import { toContractDelivery } from "@/lib/webhooks/deliveryMapper.js";
+import { fromD1 } from "@/lib/d1/catalog.js";
+import { readD1 } from "@/lib/env";
+
+export const prerender = false;
+
+const DELIVERY_STATES: readonly DeliveryState[] = ["pending", "retrying", "delivered", "dead-lettered"];
+
+/** Absent = no filter (`undefined`); an unrecognized value is a 400, not a silent no-op. */
+function parseStateFilter(raw: string | null): DeliveryState | undefined | "invalid" {
+  if (raw === null) return undefined;
+  return (DELIVERY_STATES as readonly string[]).includes(raw) ? (raw as DeliveryState) : "invalid";
+}
+
+export async function GET(context: APIContext): Promise<Response> {
+  const auth = await authorizeAppRequest(context, null);
+  if (!auth.ok) return withRequestId(auth.response, context);
+
+  const state = parseStateFilter(new URL(context.request.url).searchParams.get("state"));
+  if (state === "invalid") {
+    return withRequestId(json({ error: "invalid state filter", code: "invalid_state_filter" }, 400), context);
+  }
+
+  const d1 = await readD1("STOREFRONT_APPS_DB");
+  if (!d1) return withRequestId(json({ error: "webhook store not configured", code: "unconfigured" }, 503), context);
+  const store = new WebhookDeliveryStore(fromD1(d1));
+
+  const deliveries = await store.listDeliveriesByInstall(auth.install.installId, { state });
+
+  return withRequestId(json({ deliveries: deliveries.map(toContractDelivery) }), context);
+}

package/apps/storefront/src/pages/api/auth/magic-exchange.ts

@@ -25,18 +25,30 @@ import {
 } from "@/lib/auth/identityToken";
 import { createSession, DEFAULT_SESSION_TTL_SECONDS } from "@/lib/auth/session";
 import { normalizeEmailHint } from "@/lib/privacy/emailHint";
+import { acceptDeveloperInvite } from "@/lib/grants/developerInvites";
 
 export const prerender = false;
 
 /** Back to the landing page carrying an error (no token in the URL on failure). */
 function magicRedirect(
   context: APIContext,
-  params: { error?: string; next?: string; tenant?: string; emailHint?: string },
+  params: {
+    error?: string;
+    next?: string;
+    tenant?: string;
+    emailHint?: string;
+    /** Step-up state, distinct from `error` — see `@/lib/auth/stepUpChallenge`. */
+    reason?: "step-up-required" | "success-pending";
+    /** The RFC 9470 `requiredAcr` from the step-up obligation, when known. */
+    requiredAcr?: string;
+  },
 ): Response {
   const q = new URLSearchParams();
   if (params.error) q.set("error", params.error);
   if (params.tenant) q.set("tenant", params.tenant);
   if (params.emailHint) q.set("email_hint", params.emailHint);
+  if (params.reason) q.set("reason", params.reason);
+  if (params.requiredAcr) q.set("requiredAcr", params.requiredAcr);
   if (params.next && params.next !== "/dashboard") q.set("next", params.next);
   const qs = q.toString();
   return context.redirect(`/auth/magic${qs ? `?${qs}` : ""}`, 303);
@@ -67,6 +79,20 @@ export async function POST(context: APIContext): Promise<Response> {
   // Consume the token (single-use; burned server-side by tot20).
   const result = await client.exchangeSignInToken(token);
   if (!result.ok) {
+    // RFC 9470 step-up challenge / success-pending — same distinct-reason
+    // handling as /api/auth/verify (see there for the rationale).
+    if (result.reason === "step-up-required") {
+      return magicRedirect(context, {
+        tenant,
+        emailHint,
+        reason: "step-up-required",
+        requiredAcr: result.stepUp.requiredAcr,
+        next,
+      });
+    }
+    if (result.reason === "success-pending") {
+      return magicRedirect(context, { tenant, emailHint, reason: "success-pending", next });
+    }
     // reason ∈ invalid|expired|error (tot20's "used" normalizes to invalid).
     const error = result.reason === "expired" ? "expired" : "invalid";
     return magicRedirect(context, { error, tenant, emailHint, next });
@@ -105,10 +131,31 @@ export async function POST(context: APIContext): Promise<Response> {
       capability: "member",
       tenants: derived.tenants,
       staff: derived.staff,
+      acr: derived.acr,
+      authTime: derived.authTime,
     },
     DEFAULT_SESSION_TTL_SECONDS,
     nowSeconds,
   );
   setSessionCookie(context, id, DEFAULT_SESSION_TTL_SECONDS);
+
+  // Accept-before-sign-in (#8425): the invitee just affirmatively confirmed — the magic
+  // link is a developer invite — so advance the tot20 invite roster pending → accepted as
+  // they sign in. Best-effort: NEVER blocks the sign-in (a non-invitee magic sign-in or a
+  // tot20 hiccup is skipped/swallowed). tot20 scopes the accept to an invite this app issued.
+  try {
+    const accepted = await acceptDeveloperInvite(tenant, derived.email);
+    if (!accepted.accepted && !accepted.skipped) {
+      console.warn("auth/magic-exchange: invite accept did not record", {
+        tenant,
+        reason: accepted.reason,
+      });
+    }
+  } catch (err) {
+    console.warn("auth/magic-exchange: invite accept threw (swallowed)", {
+      error: err instanceof Error ? err.message : String(err),
+    });
+  }
+
   return context.redirect(next, 303);
 }

package/apps/storefront/src/pages/api/auth/step-up-send.ts

@@ -0,0 +1,57 @@
+/**
+ * POST /api/auth/step-up-send { identifier } — RFC 9470 step-up completion, leg 1.
+ *
+ * Called after `/api/auth/verify` (or `/api/auth/magic-exchange`) surfaces a
+ * `reason=step-up-required` (or `success-pending`) state: asks tot20 to send a
+ * one-time SMS code to the identifier bound to that challenge. Deliberately
+ * NEUTRAL — always 200 `{ ok: true }`, even when the integration is
+ * unconfigured or the transport fails, mirroring `sendFederatedCode`'s
+ * enumeration-resistance (the caller never learns whether `identifier` is
+ * valid/eligible from this response alone).
+ *
+ * JSON-first (the future step-up card is expected to call this via `fetch`),
+ * but also accepts a plain form post so a no-JS fallback stays possible.
+ */
+import type { APIContext } from "astro";
+import { getAccessClient } from "@/lib/auth/route";
+
+export const prerender = false;
+
+function json(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "content-type": "application/json", "cache-control": "no-store" },
+  });
+}
+
+async function readIdentifier(request: Request): Promise<string> {
+  const ct = request.headers.get("content-type") || "";
+  if (ct.includes("application/json")) {
+    const b = (await request.json().catch(() => ({}))) as Record<string, unknown>;
+    return typeof b.identifier === "string" ? b.identifier.trim() : "";
+  }
+  const form = await request.formData();
+  return String(form.get("identifier") ?? "").trim();
+}
+
+export async function POST(context: APIContext): Promise<Response> {
+  let identifier = "";
+  try {
+    identifier = await readIdentifier(context.request);
+  } catch {
+    // Never leak parse failures either — stay neutral.
+    return json({ ok: true });
+  }
+  if (!identifier) return json({ ok: true });
+
+  const client = await getAccessClient();
+  if (!client) {
+    // Integration not configured server-side; still neutral to the caller —
+    // this is an ops problem, not something the caller should be able to probe.
+    console.warn("auth/step-up-send: access client unconfigured");
+    return json({ ok: true });
+  }
+
+  await client.sendSmsChallenge(identifier);
+  return json({ ok: true });
+}

package/apps/storefront/src/pages/api/auth/step-up-verify.ts

@@ -0,0 +1,129 @@
+/**
+ * POST /api/auth/step-up-verify { identifier, code, next? } — RFC 9470 step-up
+ * completion, leg 2.
+ *
+ * Verifies the SMS code tot20 bound to `identifier` (sent via
+ * `/api/auth/step-up-send`). On success tot20 returns a FRESHER `id_token`
+ * (acr `tot:aal:sms`, fresh `auth_time`) that satisfies the step-up obligation
+ * a prior `/api/auth/verify` or `/api/auth/magic-exchange` surfaced. We then
+ * complete sign-in the EXACT same way those routes do: verify the assertion
+ * OFFLINE against tot's JWKS (aud pinned to `STOREFRONT_APP_DOMAIN`), derive the
+ * federated session from its claims, mint the session, set the cookie, and
+ * redirect to `next` — no bespoke session path (see `@/lib/auth/route` +
+ * `@/lib/auth/identityToken` + `@/lib/auth/session`, the same helpers
+ * `verify.ts`/`magic-exchange.ts` use).
+ *
+ * No-JS-friendly (a plain form post), matching the rest of `/api/auth/*`.
+ */
+import type { APIContext } from "astro";
+import {
+  getAccessClient,
+  getSessionStore,
+  setSessionCookie,
+  safeNext,
+  loginRedirect,
+} from "@/lib/auth/route";
+import { getFederatedVerifier, sessionFromFederatedClaims } from "@/lib/auth/identityToken";
+import { createSession, DEFAULT_SESSION_TTL_SECONDS } from "@/lib/auth/session";
+
+export const prerender = false;
+
+export async function POST(context: APIContext): Promise<Response> {
+  let identifier = "";
+  let code = "";
+  let next = "/";
+  try {
+    const form = await context.request.formData();
+    identifier = String(form.get("identifier") ?? "").trim();
+    code = String(form.get("code") ?? "").trim();
+    next = safeNext(String(form.get("next") ?? "/"));
+  } catch {
+    return loginRedirect(context, { error: "invalid", reason: "step-up-required", next });
+  }
+
+  if (!identifier || !code) {
+    return loginRedirect(context, {
+      sent: true,
+      email: identifier,
+      reason: "step-up-required",
+      error: "invalid",
+      next,
+    });
+  }
+
+  const client = await getAccessClient();
+  const store = await getSessionStore();
+  if (!client || !store) {
+    return loginRedirect(context, {
+      sent: true,
+      email: identifier,
+      reason: "step-up-required",
+      error: "unconfigured",
+      next,
+    });
+  }
+
+  const result = await client.verifySmsChallenge(identifier, code);
+  if (!result.ok) {
+    // reason ∈ invalid|expired|too_many_attempts|error — keep the step-up card up.
+    return loginRedirect(context, {
+      sent: true,
+      email: identifier,
+      reason: "step-up-required",
+      error: result.reason,
+      next,
+    });
+  }
+
+  // Prove authorization offline, identically to a normal federated verify. Fail
+  // closed — never trust the flat JSON.
+  const verifier = await getFederatedVerifier();
+  if (!verifier) {
+    console.error("auth/step-up-verify: federated verifier unconfigured (TOT_CORE_URL/STOREFRONT_APP_DOMAIN)");
+    return loginRedirect(context, {
+      sent: true,
+      email: identifier,
+      reason: "step-up-required",
+      error: "unconfigured",
+      next,
+    });
+  }
+
+  let derived;
+  try {
+    const claims = await verifier.verify(result.idToken); // enforces aud === STOREFRONT_APP_DOMAIN
+    derived = sessionFromFederatedClaims(claims);
+  } catch (err) {
+    console.error("auth/step-up-verify: id_token verification failed; failing closed", {
+      error: err instanceof Error ? err.message : String(err),
+    });
+    return loginRedirect(context, {
+      sent: true,
+      email: identifier,
+      reason: "step-up-required",
+      error: "verify_failed",
+      next,
+    });
+  }
+
+  const nowSeconds = Math.floor(Date.now() / 1000);
+  const { id } = await createSession(
+    store,
+    {
+      email: derived.email,
+      resource: derived.resource,
+      roles: [],
+      capability: "member",
+      tenants: derived.tenants,
+      staff: derived.staff,
+      // The whole point of this route: record the assurance the fresher
+      // credential established (e.g. `tot:aal:sms`) on the session.
+      acr: derived.acr,
+      authTime: derived.authTime,
+    },
+    DEFAULT_SESSION_TTL_SECONDS,
+    nowSeconds,
+  );
+  setSessionCookie(context, id, DEFAULT_SESSION_TTL_SECONDS);
+  return context.redirect(next, 303);
+}

package/apps/storefront/src/pages/api/auth/verify.ts

@@ -83,6 +83,25 @@ export async function POST(context: APIContext): Promise<Response> {
 
   const result = await client.verifyFederatedCode(email, code);
   if (!result.ok) {
+    // RFC 9470 step-up challenge: tot20 needs a fresher credential (e.g. SMS)
+    // before it will complete sign-in. Surface a distinct `reason` (not a plain
+    // `error`) so the login page can offer the step-up completion card instead
+    // of "invalid code". The `requiredAcr` lets it know which credential to ask for.
+    if (result.reason === "step-up-required") {
+      return loginRedirect(context, {
+        sent: true,
+        email,
+        reason: "step-up-required",
+        requiredAcr: result.stepUp.requiredAcr,
+        next,
+      });
+    }
+    // Identity is bound (e.g. from an invite flow); sign-in awaits step-up
+    // completion. Distinct from step-up-required: no fresh challenge to answer
+    // yet, just a "come back after step-up" state.
+    if (result.reason === "success-pending") {
+      return loginRedirect(context, { sent: true, email, reason: "success-pending", next });
+    }
     // Show the code step again with the specific reason (invalid/expired/too_many_attempts).
     return loginRedirect(context, { sent: true, email, error: result.reason, next });
   }
@@ -126,6 +145,10 @@ export async function POST(context: APIContext): Promise<Response> {
       capability: "member",
       tenants: derived.tenants,
       staff: derived.staff,
+      // Record the assurance the assertion carried, if any (e.g. a token already
+      // satisfying a step-up would arrive with `acr: 'tot:aal:sms'`).
+      acr: derived.acr,
+      authTime: derived.authTime,
     },
     DEFAULT_SESSION_TTL_SECONDS,
     nowSeconds,