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

package/apps/storefront/src/pages/api/apps/internal/order-forward.ts

@@ -0,0 +1,172 @@
+/**
+ * POST /api/apps/internal/order-forward — PrivateApps epic, D6 (Chunk D).
+ * Service-to-service, HMAC-authed (NOT the app-JWT bearer scheme
+ * `pages/api/apps/v1/*` uses — this is a different caller entirely: the
+ * tot-foxycart order-reconciliation unit, not an installed private app).
+ * Lives under `internal/`, a sibling of `v1/`/`admin/`, precisely so it's
+ * excluded from both `v1/routeInventory.test.ts` and
+ * `admin/routeInventory.test.ts`'s directory-scoped inventories — this is
+ * neither surface.
+ *
+ * `docs/private-apps/order-forward-contract.md` is the normative spec for the
+ * request shape + signature scheme below; this file is the HTTP transport
+ * only — `orderForwardReceiver.ts` owns the actual decision logic.
+ *
+ * Fail-closed, same posture as `pages/api/preview/reconcile.ts`'s Gitea
+ * webhook verification: missing/invalid signature -> 401, unconfigured
+ * secret -> 503. Never call the receiver on an unverified request.
+ */
+import type { APIContext } from "astro";
+import { readEnv, readD1 } from "@/lib/env";
+import { fromD1 } from "@/lib/d1/catalog.js";
+import {
+  receiveForwardedOrder,
+  type OrderForwardInput,
+} from "@/lib/apps/orders/orderForwardReceiver.js";
+import type { OrderLineItem, OrderStatus } from "@/lib/apps/orders/ordersStore.js";
+
+export const prerender = false;
+
+const SIGNATURE_HEADER = "x-order-forward-signature";
+const ORDER_STATUSES: readonly OrderStatus[] = ["created", "fulfilled", "cancelled"];
+
+function json(body: unknown, status: number): Response {
+  return new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json" } });
+}
+
+// --- HMAC verification -----------------------------------------------------
+// Same shape as `@tot/private-controlplane`'s `verifyGiteaSignature` (hex
+// HMAC-SHA256 over the raw body, verified via `crypto.subtle.verify` so a
+// short/malformed signature can't be timed) — kept local rather than shared
+// since that package's scheme is Gitea's, not this contract's; this is the
+// one caller of it today.
+const textEncoder = new TextEncoder();
+
+function hexToBytes(hex: string): Uint8Array | null {
+  if (hex.length === 0 || hex.length % 2 !== 0 || /[^0-9a-fA-F]/.test(hex)) return null;
+  const out = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < out.length; i++) out[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+  return out;
+}
+
+async function verifyOrderForwardSignature(
+  secret: string,
+  rawBody: string,
+  signatureHex: string | null,
+): Promise<boolean> {
+  if (!signatureHex) return false;
+  const sig = hexToBytes(signatureHex.trim());
+  if (!sig) return false;
+  const key = await crypto.subtle.importKey(
+    "raw",
+    textEncoder.encode(secret) as unknown as BufferSource,
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["verify"],
+  );
+  return crypto.subtle.verify(
+    "HMAC",
+    key,
+    sig as unknown as BufferSource,
+    textEncoder.encode(rawBody) as unknown as BufferSource,
+  );
+}
+
+// --- Payload validation ------------------------------------------------------
+interface OrderForwardBody {
+  tenantId?: unknown;
+  externalOrderId?: unknown;
+  env?: unknown;
+  status?: unknown;
+  currency?: unknown;
+  total?: unknown;
+  subtotal?: unknown;
+  lineItems?: unknown;
+  rawCustomerId?: unknown;
+  createdAt?: unknown;
+}
+
+function parseLineItems(value: unknown): OrderLineItem[] | string {
+  if (!Array.isArray(value) || value.length === 0) return "lineItems must be a non-empty array";
+  const items: OrderLineItem[] = [];
+  for (const raw of value as unknown[]) {
+    if (raw === null || typeof raw !== "object") return "each lineItem must be an object";
+    const item = raw as Record<string, unknown>;
+    if (typeof item.sku !== "string" || !item.sku.trim()) return "each lineItem.sku is required";
+    if (typeof item.quantity !== "number") return "each lineItem.quantity must be a number";
+    if (item.handle !== undefined && typeof item.handle !== "string") return "lineItem.handle must be a string";
+    if (item.lineTotal !== undefined && typeof item.lineTotal !== "number") {
+      return "lineItem.lineTotal must be a number";
+    }
+    items.push({
+      sku: item.sku,
+      quantity: item.quantity,
+      ...(item.handle !== undefined ? { handle: item.handle as string } : {}),
+      ...(item.lineTotal !== undefined ? { lineTotal: item.lineTotal as number } : {}),
+    });
+  }
+  return items;
+}
+
+/** Validate + narrow the request body into `OrderForwardInput`, or a 400 message. */
+function parseOrderForwardInput(body: OrderForwardBody): OrderForwardInput | string {
+  if (typeof body.tenantId !== "string" || !body.tenantId.trim()) return "tenantId is required";
+  if (typeof body.externalOrderId !== "string" || !body.externalOrderId.trim()) {
+    return "externalOrderId is required";
+  }
+  if (typeof body.env !== "string" || !body.env.trim()) return "env is required";
+  if (typeof body.status !== "string" || !ORDER_STATUSES.includes(body.status as OrderStatus)) {
+    return `status must be one of ${ORDER_STATUSES.join(", ")}`;
+  }
+  if (typeof body.currency !== "string" || !body.currency.trim()) return "currency is required";
+  if (typeof body.total !== "number") return "total must be a number";
+  if (body.subtotal !== undefined && typeof body.subtotal !== "number") return "subtotal must be a number";
+  const lineItems = parseLineItems(body.lineItems);
+  if (typeof lineItems === "string") return lineItems;
+  if (body.rawCustomerId !== undefined && typeof body.rawCustomerId !== "string") {
+    return "rawCustomerId must be a string";
+  }
+  if (body.createdAt !== undefined && typeof body.createdAt !== "string") return "createdAt must be a string";
+
+  return {
+    tenantId: body.tenantId,
+    externalOrderId: body.externalOrderId,
+    env: body.env,
+    status: body.status as OrderStatus,
+    currency: body.currency,
+    total: body.total,
+    subtotal: body.subtotal as number | undefined,
+    lineItems,
+    rawCustomerId: body.rawCustomerId as string | undefined,
+    createdAt: body.createdAt as string | undefined,
+  };
+}
+
+export async function POST(context: APIContext): Promise<Response> {
+  const signature = context.request.headers.get(SIGNATURE_HEADER);
+  if (!signature) return json({ error: "Missing signature" }, 401);
+
+  const secret = await readEnv("FOXY_ORDER_FORWARD_SECRET");
+  if (!secret) return json({ error: "order-forward secret not configured" }, 503);
+
+  // Raw body: the HMAC is computed over the exact bytes, same as the Gitea scheme.
+  const rawBody = await context.request.text();
+  const valid = await verifyOrderForwardSignature(secret, rawBody, signature);
+  if (!valid) return json({ error: "Invalid signature" }, 401);
+
+  let body: OrderForwardBody;
+  try {
+    body = JSON.parse(rawBody) as OrderForwardBody;
+  } catch {
+    return json({ error: "invalid JSON body" }, 400);
+  }
+
+  const input = parseOrderForwardInput(body);
+  if (typeof input === "string") return json({ error: input }, 400);
+
+  const d1 = await readD1("STOREFRONT_APPS_DB");
+  if (!d1) return json({ error: "orders store not configured" }, 503);
+
+  const result = await receiveForwardedOrder(fromD1(d1), input);
+  return json({ ok: true, status: result.order.status, emitted: result.emitted }, 200);
+}

package/apps/storefront/src/pages/api/apps/oauth/token.ts

@@ -0,0 +1,87 @@
+/**
+ * `POST /api/apps/oauth/token` — the Storefront App Gateway's OAuth2
+ * client-credentials grant (PrivateApps epic, D2 Chunk B; feature-brief.md §3
+ * "Scoped credentials"). A private app exchanges its `(client_id,
+ * client_secret)` for a short-lived RS256 bearer JWT it then presents to the
+ * D3 scoped APIs. Standard RFC 6749 §4.4 form-encoded request/response — any
+ * language's off-the-shelf OAuth2 client works unmodified (feature-brief.md's
+ * "never a ToT SDK requirement").
+ *
+ * `tenant` and `env` are NEVER taken from the request body: `tenant` is this
+ * host's resolved `appDomain` (`context.locals.tenant`, set by
+ * `src/middleware` from the request Host) and `env` is this deploy's own
+ * `NODE_ENV` — both bound server-side so a leaked credential can't be
+ * replayed against a different tenant or environment than the one it was
+ * issued for. This endpoint's absence from `contract/openapi.yaml` (the D1
+ * data-API file) is intentional — see that file's `securitySchemes.appJwt`
+ * note.
+ */
+import type { APIContext } from "astro";
+import { AppRegistryService } from "@/lib/apps/registryService.js";
+import { D1CredentialStore } from "@/lib/apps/credentials.js";
+import { AppTokenIssuer, TokenError, type TokenErrorCode } from "@/lib/apps/tokenIssuer.js";
+import { DEFAULT_APP_GATEWAY_KID, APP_GATEWAY_KID_ENV } from "@/lib/apps/gatewayKeys.js";
+import { fromD1 } from "@/lib/d1/catalog.js";
+import { readD1, readEnv } from "@/lib/env";
+
+export const prerender = false;
+
+/** No-store JSON responder — a token (or its error) must never be edge-cached. */
+function json(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "content-type": "application/json", "cache-control": "no-store" },
+  });
+}
+
+const STATUS_BY_CODE: Record<TokenErrorCode, number> = {
+  invalid_client: 401,
+  invalid_grant: 403,
+  temporarily_unavailable: 503,
+};
+
+export async function POST(context: APIContext): Promise<Response> {
+  const contentType = context.request.headers.get("content-type") ?? "";
+  if (!contentType.includes("application/x-www-form-urlencoded")) {
+    return json({ error: "invalid_request", error_description: "expected application/x-www-form-urlencoded" }, 400);
+  }
+
+  const form = new URLSearchParams(await context.request.text());
+  if (form.get("grant_type") !== "client_credentials") {
+    return json({ error: "unsupported_grant_type" }, 400);
+  }
+  const clientId = form.get("client_id");
+  const clientSecret = form.get("client_secret");
+  if (!clientId || !clientSecret) {
+    return json({ error: "invalid_request", error_description: "client_id and client_secret are required" }, 400);
+  }
+
+  const d1 = await readD1("STOREFRONT_APPS_DB");
+  if (!d1) return json({ error: "temporarily_unavailable" }, 503);
+  const db = fromD1(d1);
+
+  const activeKid = (await readEnv(APP_GATEWAY_KID_ENV)) ?? DEFAULT_APP_GATEWAY_KID;
+  const credentials = new D1CredentialStore(db, activeKid);
+  const registry = new AppRegistryService(db, credentials);
+  const issuer = new AppTokenIssuer(registry, credentials);
+
+  try {
+    const token = await issuer.issueToken({
+      clientId,
+      secret: clientSecret,
+      tenant: context.locals.tenant.appDomain,
+      env: (await readEnv("NODE_ENV")) ?? "development",
+    });
+    return json({
+      access_token: token.accessToken,
+      token_type: token.tokenType,
+      expires_in: token.expiresIn,
+      scope: token.scope,
+    });
+  } catch (err) {
+    if (err instanceof TokenError) {
+      return json({ error: err.code }, STATUS_BY_CODE[err.code]);
+    }
+    throw err;
+  }
+}

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

@@ -0,0 +1,142 @@
+/**
+ * `POST /api/apps/v1/attribution` — the D6 app-owned attribution write
+ * (PrivateApps epic; `docs/private-apps/contract/openapi.yaml`'s
+ * `writeAttribution`). Requires scope `attribution:write`.
+ *
+ * Real idempotency, unlike D4's replay endpoint: the `Idempotency-Key`
+ * header is required, and a reused key with a DIFFERENT request body is
+ * rejected with 409 (`idempotency.ts`'s `checkIdempotency`, backed by the
+ * `idempotency_keys` table). The body is validated strictly — the contract
+ * is `additionalProperties: false`, so an unknown field 400s rather than
+ * being silently ignored. `orderId` ownership and the `attributionId`
+ * repeat-write rule are enforced in `attributionService.ts`.
+ */
+import type { APIContext } from "astro";
+import { authorizeAppRequest } from "@/lib/apps/apiAuth.js";
+import { json, withRequestId } from "@/lib/apps/apiRoute.js";
+import { checkIdempotency, computeBodyHash, recordIdempotency } from "@/lib/apps/orders/idempotency.js";
+import { AppAttributionService, AttributionError } from "@/lib/apps/orders/attributionService.js";
+import { fromD1 } from "@/lib/d1/catalog.js";
+import { readD1 } from "@/lib/env";
+
+export const prerender = false;
+
+const COMMISSION_KEYS = new Set(["amount", "currency"]);
+const BODY_KEYS = new Set(["attributionId", "orderId", "campaign", "referralCode", "customerHash", "commission"]);
+
+interface AttributionBody {
+  attributionId?: unknown;
+  orderId?: unknown;
+  campaign?: unknown;
+  referralCode?: unknown;
+  customerHash?: unknown;
+  commission?: unknown;
+}
+
+interface ParsedAttributionBody {
+  attributionId: string;
+  orderId: string;
+  campaign?: string;
+  referralCode?: string;
+  customerHash?: string;
+  commission?: { amount?: number; currency?: string };
+}
+
+/** Validate + narrow the request body, or return a 400 message. Rejects unknown fields (contract: additionalProperties: false). */
+function parseAttributionBody(body: AttributionBody): ParsedAttributionBody | string {
+  for (const key of Object.keys(body)) {
+    if (!BODY_KEYS.has(key)) return `unknown field: ${key}`;
+  }
+  if (typeof body.attributionId !== "string" || !body.attributionId.trim()) return "attributionId is required";
+  if (typeof body.orderId !== "string" || !body.orderId.trim()) return "orderId is required";
+  if (body.campaign !== undefined && typeof body.campaign !== "string") return "campaign, when given, must be a string";
+  if (body.referralCode !== undefined && typeof body.referralCode !== "string") {
+    return "referralCode, when given, must be a string";
+  }
+  if (body.customerHash !== undefined && typeof body.customerHash !== "string") {
+    return "customerHash, when given, must be a string";
+  }
+
+  let commission: { amount?: number; currency?: string } | undefined;
+  if (body.commission !== undefined) {
+    if (body.commission === null || typeof body.commission !== "object" || Array.isArray(body.commission)) {
+      return "commission, when given, must be an object";
+    }
+    const c = body.commission as Record<string, unknown>;
+    for (const key of Object.keys(c)) {
+      if (!COMMISSION_KEYS.has(key)) return `unknown field: commission.${key}`;
+    }
+    if (c.amount !== undefined && typeof c.amount !== "number") return "commission.amount, when given, must be a number";
+    if (c.currency !== undefined && typeof c.currency !== "string") return "commission.currency, when given, must be a string";
+    commission = { ...(c.amount !== undefined ? { amount: c.amount as number } : {}), ...(c.currency !== undefined ? { currency: c.currency as string } : {}) };
+  }
+
+  return {
+    attributionId: body.attributionId,
+    orderId: body.orderId,
+    ...(body.campaign !== undefined ? { campaign: body.campaign as string } : {}),
+    ...(body.referralCode !== undefined ? { referralCode: body.referralCode as string } : {}),
+    ...(body.customerHash !== undefined ? { customerHash: body.customerHash as string } : {}),
+    ...(commission !== undefined ? { commission } : {}),
+  };
+}
+
+export async function POST(context: APIContext): Promise<Response> {
+  const auth = await authorizeAppRequest(context, "attribution:write");
+  if (!auth.ok) return withRequestId(auth.response, context);
+
+  const idempotencyKey = context.request.headers.get("idempotency-key");
+  if (!idempotencyKey) {
+    return withRequestId(json({ error: "Idempotency-Key header is required", code: "bad_request" }, 400), context);
+  }
+
+  let rawBody: AttributionBody;
+  try {
+    rawBody = (await context.request.json()) as AttributionBody;
+  } catch {
+    return withRequestId(json({ error: "invalid JSON body", code: "bad_request" }, 400), context);
+  }
+
+  const parsed = parseAttributionBody(rawBody);
+  if (typeof parsed === "string") {
+    return withRequestId(json({ error: parsed, code: "bad_request" }, 400), context);
+  }
+
+  const d1 = await readD1("STOREFRONT_APPS_DB");
+  if (!d1) return withRequestId(json({ error: "attribution store not configured", code: "unconfigured" }, 503), context);
+  const db = fromD1(d1);
+
+  const bodyHash = await computeBodyHash(rawBody);
+  const idem = await checkIdempotency(db, auth.install.installId, idempotencyKey, bodyHash);
+  if (idem.status === "conflict") {
+    return withRequestId(json({ error: "Idempotency-Key reused with a different request body", code: "idempotency_conflict" }, 409), context);
+  }
+  if (idem.status === "replay") {
+    return withRequestId(json(idem.responseBody, 201), context);
+  }
+
+  const service = new AppAttributionService(db);
+  let record;
+  try {
+    record = await service.record({
+      installId: auth.install.installId,
+      tenantId: auth.install.tenantId,
+      attributionId: parsed.attributionId,
+      orderId: parsed.orderId,
+      campaign: parsed.campaign,
+      referralCode: parsed.referralCode,
+      commission: parsed.commission,
+      customerHash: parsed.customerHash,
+    });
+  } catch (err) {
+    if (err instanceof AttributionError) {
+      const status =
+        err.code === "attribution_forbidden" ? 403 : err.code === "attribution_conflict" ? 409 : 400;
+      return withRequestId(json({ error: err.message, code: err.code }, status), context);
+    }
+    throw err;
+  }
+
+  await recordIdempotency(db, auth.install.installId, idempotencyKey, bodyHash, record);
+  return withRequestId(json(record, 201), context);
+}

package/apps/storefront/src/pages/api/apps/v1/catalog/products/[handle].ts

@@ -0,0 +1,39 @@
+/**
+ * `GET /api/apps/v1/catalog/products/{handle}` — the D3 scoped single-product
+ * read (PrivateApps epic; `docs/private-apps/contract/openapi.yaml`'s
+ * `getCatalogProduct`). Requires scope `catalog:read`.
+ *
+ * `getProductByHandle` resolves drafts too (see its own doc comment) — this
+ * route is the caller that gates visibility: a missing handle OR a
+ * non-active product are BOTH reported as a plain 404, so an app can't use
+ * this endpoint to probe for unpublished products.
+ */
+import type { APIContext } from "astro";
+import { authorizeAppRequest } from "@/lib/apps/apiAuth.js";
+import { json, withRequestId } from "@/lib/apps/apiRoute.js";
+import { toContractProduct } from "@/lib/apps/catalogMapper.js";
+import { getProductByHandle, fromD1 } from "@/lib/d1/catalog.js";
+import { readD1 } from "@/lib/env";
+
+export const prerender = false;
+
+export async function GET(context: APIContext): Promise<Response> {
+  const auth = await authorizeAppRequest(context, "catalog:read");
+  if (!auth.ok) return withRequestId(auth.response, context);
+
+  const handle = context.params.handle;
+  if (!handle) {
+    return withRequestId(json({ error: "handle is required", code: "not_found" }, 404), context);
+  }
+
+  const d1 = await readD1("CATALOG_DB");
+  if (!d1) return withRequestId(json({ error: "catalog not configured", code: "unconfigured" }, 503), context);
+  const db = fromD1(d1);
+
+  const product = await getProductByHandle(db, handle);
+  if (!product || product.status !== "active") {
+    return withRequestId(json({ error: "Product not found.", code: "not_found" }, 404), context);
+  }
+
+  return withRequestId(json(toContractProduct(product)), context);
+}

package/apps/storefront/src/pages/api/apps/v1/catalog/products.ts

@@ -0,0 +1,49 @@
+/**
+ * `GET /api/apps/v1/catalog/products` — the D3 scoped catalog list
+ * (PrivateApps epic; `docs/private-apps/contract/openapi.yaml`'s
+ * `listCatalogProducts`). Requires scope `catalog:read`. Reads the same D1
+ * edge replica the storefront itself reads (`../../../../../lib/d1/catalog.js`),
+ * which already scopes to `status = 'active'` — published products only —
+ * and projects each row through `catalogMapper.js` so nothing beyond the
+ * contract's `Product` shape ever leaves this route.
+ */
+import type { APIContext } from "astro";
+import { authorizeAppRequest } from "@/lib/apps/apiAuth.js";
+import { json, withRequestId } from "@/lib/apps/apiRoute.js";
+import { toContractProduct } from "@/lib/apps/catalogMapper.js";
+import { listProducts, fromD1 } from "@/lib/d1/catalog.js";
+import { readD1 } from "@/lib/env";
+
+export const prerender = false;
+
+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;
+}
+
+export async function GET(context: APIContext): Promise<Response> {
+  const auth = await authorizeAppRequest(context, "catalog:read");
+  if (!auth.ok) return withRequestId(auth.response, context);
+
+  const d1 = await readD1("CATALOG_DB");
+  if (!d1) return withRequestId(json({ error: "catalog not configured", code: "unconfigured" }, 503), context);
+  const db = fromD1(d1);
+
+  const url = new URL(context.request.url);
+  const result = await listProducts(db, {
+    collection: url.searchParams.get("collection") ?? undefined,
+    q: url.searchParams.get("q") ?? undefined,
+    page: parsePage(url.searchParams.get("page"), 1),
+    pageSize: Math.min(100, Math.max(1, parsePage(url.searchParams.get("pageSize"), 24))),
+  });
+
+  return withRequestId(
+    json({
+      products: result.products.map(toContractProduct),
+      page: result.page,
+      pageSize: result.pageSize,
+      total: result.total,
+    }),
+    context,
+  );
+}

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

@@ -0,0 +1,32 @@
+/**
+ * `GET /api/apps/v1/health` — the D4 install delivery/telemetry health read
+ * (PrivateApps epic; `docs/private-apps/contract/openapi.yaml`'s
+ * `getInstallHealth`). Requires no scope beyond a valid token — only ever the
+ * caller's OWN install health (the `sub` claim `authorizeAppRequest` already
+ * resolved), never another install's.
+ *
+ * `WebhookDeliveryStore.getInstallHealth`'s `InstallHealth` return already IS
+ * the contract's `InstallHealth` shape 1:1, incl. `p95DeliveryMs` (a
+ * never-attempted install reads as healthy/zeroed) — no mapper needed, unlike
+ * `Delivery` below.
+ */
+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 { fromD1 } from "@/lib/d1/catalog.js";
+import { readD1 } from "@/lib/env";
+
+export const prerender = false;
+
+export async function GET(context: APIContext): Promise<Response> {
+  const auth = await authorizeAppRequest(context, null);
+  if (!auth.ok) return withRequestId(auth.response, 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 health = await store.getInstallHealth(auth.install.installId);
+  return withRequestId(json(health), context);
+}

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

@@ -0,0 +1,59 @@
+/**
+ * `GET /api/apps/v1/inventory` — the D3 inventory-availability read
+ * (PrivateApps epic; `docs/private-apps/contract/openapi.yaml`'s
+ * `listInventory`). Requires scope `inventory:read`.
+ *
+ * No new table: this projects `{sku, available, quantity?, policy?}` off the
+ * variants embedded in the existing catalog read model
+ * (`../../../lib/d1/catalog.js`'s `listAllActiveProducts`) — active products
+ * only. A variant with no `sku` is skipped; the contract's `InventoryList`
+ * item requires one, and there's nothing to key it by otherwise.
+ */
+import type { APIContext } from "astro";
+import { authorizeAppRequest } from "@/lib/apps/apiAuth.js";
+import { json, withRequestId } from "@/lib/apps/apiRoute.js";
+import { listAllActiveProducts, fromD1 } from "@/lib/d1/catalog.js";
+import { readD1 } from "@/lib/env";
+
+export const prerender = false;
+
+interface InventoryItem {
+  sku: string;
+  available: boolean;
+  quantity?: number;
+  policy?: "deny" | "continue";
+}
+
+function toInventoryItem(policy: string | undefined, quantity: number | undefined, sku: string, available: boolean): InventoryItem {
+  return {
+    sku,
+    available,
+    quantity,
+    policy: policy === "deny" || policy === "continue" ? policy : undefined,
+  };
+}
+
+export async function GET(context: APIContext): Promise<Response> {
+  const auth = await authorizeAppRequest(context, "inventory:read");
+  if (!auth.ok) return withRequestId(auth.response, context);
+
+  const d1 = await readD1("CATALOG_DB");
+  if (!d1) return withRequestId(json({ error: "catalog not configured", code: "unconfigured" }, 503), context);
+  const db = fromD1(d1);
+
+  const skuFilter = new URL(context.request.url).searchParams.get("sku");
+  const products = await listAllActiveProducts(db);
+
+  const items: InventoryItem[] = [];
+  for (const product of products) {
+    for (const variant of product.variants) {
+      if (!variant.sku) continue;
+      if (skuFilter && variant.sku !== skuFilter) continue;
+      items.push(
+        toInventoryItem(variant.inventory.policy, variant.inventory.quantity, variant.sku, variant.inventory.available),
+      );
+    }
+  }
+
+  return withRequestId(json({ items }), context);
+}

package/apps/storefront/src/pages/api/apps/v1/orders/[id].ts

@@ -0,0 +1,48 @@
+/**
+ * `GET /api/apps/v1/orders/{id}` — the D6 minimal single-order read
+ * (PrivateApps epic; `docs/private-apps/contract/openapi.yaml`'s `getOrder`).
+ * Requires scope `orders:read:minimal`.
+ *
+ * `{id}` is tot-foxycart's `externalId` — the same id `listOrders` echoes
+ * back as `Order.id`. There's no cross-tenant oracle here: the Foxy partner
+ * API key is itself tenant-scoped, so a call can only ever resolve THIS
+ * tenant's own orders — an unknown id and a different tenant's id both come
+ * back `null` from `FoxyOrderClient.getOrder` and are reported identically
+ * as 404.
+ */
+import type { APIContext } from "astro";
+import { authorizeAppRequest } from "@/lib/apps/apiAuth.js";
+import { json, withRequestId } from "@/lib/apps/apiRoute.js";
+import { toContractOrder } from "@/lib/apps/orders/orderMapper.js";
+import { getFoxyOrderClient } from "@/lib/apps/orders/foxyOrderClient.js";
+
+export const prerender = false;
+
+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 id = context.params.id;
+  if (!id) return withRequestId(json({ error: "missing order id", code: "bad_request" }, 400), context);
+
+  let client;
+  try {
+    client = await getFoxyOrderClient();
+  } catch {
+    return withRequestId(json({ error: "orders not configured", code: "unconfigured" }, 503), context);
+  }
+
+  let foxyOrder;
+  try {
+    foxyOrder = await client.getOrder(auth.install.tenantId, id);
+  } catch {
+    return withRequestId(json({ error: "failed to read order", code: "upstream_error" }, 502), context);
+  }
+  if (!foxyOrder) return withRequestId(json({ error: "order not found", code: "not_found" }, 404), context);
+
+  const order = await toContractOrder(foxyOrder, {
+    tenantId: auth.install.tenantId,
+    installId: auth.install.installId,
+  });
+  return withRequestId(json(order), context);
+}