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

package/apps/storefront/src/pages/api/apps/admin/install.ts

@@ -0,0 +1,100 @@
+/**
+ * POST /api/apps/admin/install — install a private app for the resolved
+ * operator tenant + a caller-chosen env (PrivateApps epic, D2 Chunk C).
+ * Session-authed (see `@/lib/apps/adminSession`) — NOT the app JWT (D3's data
+ * surface). `tenantId` comes only from the resolved session, never the body.
+ *
+ * The response's `credential.secret` is the ONE time the plaintext client
+ * secret is ever surfaced — never logged, never returned again (see
+ * `registryService.ts`'s `InstallResult` doc).
+ */
+import type { APIContext } from "astro";
+import { resolveAdminSession } from "@/lib/apps/adminSession.js";
+import { getRegistryService, registryErrorResponse, json } from "@/lib/apps/adminService.js";
+import { RegistryError, type InstallInput } from "@/lib/apps/registryService.js";
+import { emitWebhookEvent } from "@/lib/webhooks/emit.js";
+
+export const prerender = false;
+
+interface InstallBody {
+  appId?: unknown;
+  appVersion?: unknown;
+  env?: unknown;
+  scopes?: unknown;
+  manifest?: unknown;
+  webhookEndpoint?: unknown;
+  widgetPlacements?: unknown;
+}
+
+/** Validate + narrow the request body into `InstallInput`, or a 400 message. */
+function parseInstallInput(body: InstallBody): InstallInput | string {
+  if (typeof body.appId !== "string" || !body.appId.trim()) return "appId is required";
+  if (typeof body.appVersion !== "string" || !body.appVersion.trim()) return "appVersion is required";
+  if (typeof body.env !== "string" || !body.env.trim()) return "env is required";
+  if (!Array.isArray(body.scopes) || body.scopes.some((s) => typeof s !== "string")) {
+    return "scopes must be a string[]";
+  }
+  if (body.manifest === null || typeof body.manifest !== "object" || Array.isArray(body.manifest)) {
+    return "manifest is required and must be an object";
+  }
+  if (
+    body.webhookEndpoint !== undefined &&
+    body.webhookEndpoint !== null &&
+    typeof body.webhookEndpoint !== "string"
+  ) {
+    return "webhookEndpoint, when given, must be a string or null";
+  }
+  if (body.widgetPlacements !== undefined && !Array.isArray(body.widgetPlacements)) {
+    return "widgetPlacements, when given, must be an array";
+  }
+  return {
+    appId: body.appId,
+    appVersion: body.appVersion,
+    env: body.env,
+    scopes: body.scopes as string[],
+    manifest: body.manifest,
+    webhookEndpoint: (body.webhookEndpoint as string | null | undefined) ?? undefined,
+    widgetPlacements: body.widgetPlacements as unknown[] | undefined,
+  };
+}
+
+export async function POST(context: APIContext): Promise<Response> {
+  const auth = await resolveAdminSession(context);
+  if (!auth.ok) return json({ error: auth.message }, auth.status);
+
+  let body: InstallBody;
+  try {
+    body = (await context.request.json()) as InstallBody;
+  } catch {
+    return json({ error: "invalid JSON body" }, 400);
+  }
+
+  const input = parseInstallInput(body);
+  if (typeof input === "string") return json({ error: input }, 400);
+
+  const registry = await getRegistryService();
+  if (registry instanceof Response) return registry;
+
+  try {
+    const result = await registry.install(input, { tenantId: auth.tenantId, actor: auth.actor });
+    try {
+      // Best-effort: a webhook-plumbing hiccup must never turn a successful
+      // install into a failed response — see emit.ts's header.
+      await emitWebhookEvent("app.installed", auth.tenantId, {}, { installId: result.install.installId });
+    } catch (cause) {
+      console.warn(
+        "[diag:webhooks:emit]",
+        JSON.stringify({
+          topic: "app.installed",
+          tenantId: auth.tenantId,
+          installId: result.install.installId,
+          error: cause instanceof Error ? cause.message : String(cause),
+        }),
+      );
+    }
+    return json(result, 201);
+  } catch (err) {
+    if (err instanceof RegistryError) return registryErrorResponse(err);
+    throw err;
+  }
+}

package/apps/storefront/src/pages/api/apps/admin/list.ts

@@ -0,0 +1,26 @@
+/**
+ * GET /api/apps/admin/list — list the app installs for the resolved operator
+ * tenant (PrivateApps epic, D2 Chunk C; D8 console-session auth added). The
+ * `?tenant=` query param (read by console callers with several memberships,
+ * mirroring `../../grants/team-members.ts`) is only ever a CANDIDATE into
+ * `resolveOperatorSession` — the tenant actually used below is `auth.tenantId`
+ * from the resolved session, never the raw param, so a caller can only ever
+ * see their own tenant's installs. Read-only: any membership role admits.
+ */
+import type { APIContext } from "astro";
+import { resolveOperatorSession } from "@/lib/apps/adminSession.js";
+import { getRegistryService, json } from "@/lib/apps/adminService.js";
+
+export const prerender = false;
+
+export async function GET(context: APIContext): Promise<Response> {
+  const requestedTenant = new URL(context.request.url).searchParams.get("tenant");
+  const auth = await resolveOperatorSession(context, requestedTenant);
+  if (!auth.ok) return json({ error: auth.message }, auth.status);
+
+  const registry = await getRegistryService();
+  if (registry instanceof Response) return registry;
+
+  const installs = await registry.listByTenant(auth.tenantId);
+  return json({ installs });
+}

package/apps/storefront/src/pages/api/apps/admin/resume.ts

@@ -0,0 +1,56 @@
+/**
+ * POST /api/apps/admin/resume — resume a suspended install back to active
+ * (PrivateApps epic, D2 Chunk C; D8 console-session auth added).
+ *
+ * `registryService.resume()` takes a bare `installId` with no tenant check of
+ * its own (Chunk A assumption #1) — so this route resolves the install via
+ * `requireOwnedInstall` BEFORE calling it, rejecting a foreign-tenant
+ * `installId` with the SAME 404 a truly-missing one gets (no cross-tenant
+ * existence oracle). Mutating: `requireManageRole` gates a console
+ * `developer` role out — the host-bound/Bearer path is exempt (no `role`).
+ */
+import type { APIContext } from "astro";
+import { resolveOperatorSession } from "@/lib/apps/adminSession.js";
+import {
+  getRegistryService,
+  registryErrorResponse,
+  requireOwnedInstall,
+  requireManageRole,
+  parseInstallId,
+  json,
+} from "@/lib/apps/adminService.js";
+import { RegistryError } from "@/lib/apps/registryService.js";
+
+export const prerender = false;
+
+export async function POST(context: APIContext): Promise<Response> {
+  const requestedTenant = new URL(context.request.url).searchParams.get("tenant");
+  const auth = await resolveOperatorSession(context, requestedTenant);
+  if (!auth.ok) return json({ error: auth.message }, auth.status);
+  const manageDenied = requireManageRole(auth);
+  if (manageDenied) return manageDenied;
+
+  let body: unknown;
+  try {
+    body = await context.request.json();
+  } catch {
+    return json({ error: "invalid JSON body" }, 400);
+  }
+
+  const installId = parseInstallId(body);
+  if (!installId) return json({ error: "installId is required" }, 400);
+
+  const registry = await getRegistryService();
+  if (registry instanceof Response) return registry;
+
+  const owned = await requireOwnedInstall(registry, installId, auth.tenantId);
+  if (owned instanceof Response) return owned;
+
+  try {
+    const install = await registry.resume(installId, auth.actor);
+    return json({ install });
+  } catch (err) {
+    if (err instanceof RegistryError) return registryErrorResponse(err);
+    throw err;
+  }
+}

package/apps/storefront/src/pages/api/apps/admin/suspend.ts

@@ -0,0 +1,57 @@
+/**
+ * POST /api/apps/admin/suspend — suspend an active install: immediately
+ * disables its API tokens, webhook delivery, and widget placements
+ * (PrivateApps epic, D2 Chunk C; D8 console-session auth added).
+ *
+ * `registryService.suspend()` takes a bare `installId` with no tenant check
+ * of its own (Chunk A assumption #1) — so this route resolves the install via
+ * `requireOwnedInstall` BEFORE calling it, rejecting a foreign-tenant
+ * `installId` with the SAME 404 a truly-missing one gets (no cross-tenant
+ * existence oracle). Mutating: `requireManageRole` gates a console
+ * `developer` role out — the host-bound/Bearer path is exempt (no `role`).
+ */
+import type { APIContext } from "astro";
+import { resolveOperatorSession } from "@/lib/apps/adminSession.js";
+import {
+  getRegistryService,
+  registryErrorResponse,
+  requireOwnedInstall,
+  requireManageRole,
+  parseInstallId,
+  json,
+} from "@/lib/apps/adminService.js";
+import { RegistryError } from "@/lib/apps/registryService.js";
+
+export const prerender = false;
+
+export async function POST(context: APIContext): Promise<Response> {
+  const requestedTenant = new URL(context.request.url).searchParams.get("tenant");
+  const auth = await resolveOperatorSession(context, requestedTenant);
+  if (!auth.ok) return json({ error: auth.message }, auth.status);
+  const manageDenied = requireManageRole(auth);
+  if (manageDenied) return manageDenied;
+
+  let body: unknown;
+  try {
+    body = await context.request.json();
+  } catch {
+    return json({ error: "invalid JSON body" }, 400);
+  }
+
+  const installId = parseInstallId(body);
+  if (!installId) return json({ error: "installId is required" }, 400);
+
+  const registry = await getRegistryService();
+  if (registry instanceof Response) return registry;
+
+  const owned = await requireOwnedInstall(registry, installId, auth.tenantId);
+  if (owned instanceof Response) return owned;
+
+  try {
+    const install = await registry.suspend(installId, auth.actor);
+    return json({ install });
+  } catch (err) {
+    if (err instanceof RegistryError) return registryErrorResponse(err);
+    throw err;
+  }
+}

package/apps/storefront/src/pages/api/apps/admin/uninstall.ts

@@ -0,0 +1,74 @@
+/**
+ * POST /api/apps/admin/uninstall — uninstall an app: revokes credentials and
+ * clears placements, but retains the install row + audit trail (PrivateApps
+ * epic, D2 Chunk C; D8 console-session auth added).
+ *
+ * `registryService.uninstall()` takes a bare `installId` with no tenant check
+ * of its own (Chunk A assumption #1) — so this route resolves the install via
+ * `requireOwnedInstall` BEFORE calling it, rejecting a foreign-tenant
+ * `installId` with the SAME 404 a truly-missing one gets (no cross-tenant
+ * existence oracle). Mutating: `requireManageRole` gates a console
+ * `developer` role out — the host-bound/Bearer path is exempt (no `role`).
+ */
+import type { APIContext } from "astro";
+import { resolveOperatorSession } from "@/lib/apps/adminSession.js";
+import {
+  getRegistryService,
+  registryErrorResponse,
+  requireOwnedInstall,
+  requireManageRole,
+  parseInstallId,
+  json,
+} from "@/lib/apps/adminService.js";
+import { RegistryError } from "@/lib/apps/registryService.js";
+import { emitWebhookEvent } from "@/lib/webhooks/emit.js";
+
+export const prerender = false;
+
+export async function POST(context: APIContext): Promise<Response> {
+  const requestedTenant = new URL(context.request.url).searchParams.get("tenant");
+  const auth = await resolveOperatorSession(context, requestedTenant);
+  if (!auth.ok) return json({ error: auth.message }, auth.status);
+  const manageDenied = requireManageRole(auth);
+  if (manageDenied) return manageDenied;
+
+  let body: unknown;
+  try {
+    body = await context.request.json();
+  } catch {
+    return json({ error: "invalid JSON body" }, 400);
+  }
+
+  const installId = parseInstallId(body);
+  if (!installId) return json({ error: "installId is required" }, 400);
+
+  const registry = await getRegistryService();
+  if (registry instanceof Response) return registry;
+
+  const owned = await requireOwnedInstall(registry, installId, auth.tenantId);
+  if (owned instanceof Response) return owned;
+
+  try {
+    const install = await registry.uninstall(installId, auth.actor);
+    try {
+      // Best-effort, and deliberately AFTER uninstall has already flipped the
+      // install to "uninstalled" — this is the final farewell delivery; see
+      // emit.ts / deliveryEngine.ts's matching status exemption for it.
+      await emitWebhookEvent("app.uninstalled", auth.tenantId, {}, { installId });
+    } catch (cause) {
+      console.warn(
+        "[diag:webhooks:emit]",
+        JSON.stringify({
+          topic: "app.uninstalled",
+          tenantId: auth.tenantId,
+          installId,
+          error: cause instanceof Error ? cause.message : String(cause),
+        }),
+      );
+    }
+    return json({ install });
+  } catch (err) {
+    if (err instanceof RegistryError) return registryErrorResponse(err);
+    throw err;
+  }
+}

package/apps/storefront/src/pages/api/apps/admin/update.ts

@@ -0,0 +1,103 @@
+/**
+ * POST /api/apps/admin/update — patch an existing install's version, scopes,
+ * manifest snapshot, or webhook endpoint (PrivateApps epic, D2 Chunk C; D8
+ * console-session auth added).
+ *
+ * `registryService.update()` takes a bare `installId` with no tenant check of
+ * its own (Chunk A assumption #1) — so this route resolves the install via
+ * `requireOwnedInstall` BEFORE calling it, rejecting a foreign-tenant
+ * `installId` with the SAME 404 a truly-missing one gets (no cross-tenant
+ * existence oracle). Mutating: `requireManageRole` gates a console
+ * `developer` role out — the host-bound/Bearer path is exempt (no `role`).
+ */
+import type { APIContext } from "astro";
+import { resolveOperatorSession } from "@/lib/apps/adminSession.js";
+import {
+  getRegistryService,
+  registryErrorResponse,
+  requireOwnedInstall,
+  requireManageRole,
+  parseInstallId,
+  json,
+} from "@/lib/apps/adminService.js";
+import { RegistryError, type AppInstallPatch } from "@/lib/apps/registryService.js";
+
+export const prerender = false;
+
+interface UpdateBody {
+  installId?: unknown;
+  appVersion?: unknown;
+  scopes?: unknown;
+  manifest?: unknown;
+  webhookEndpoint?: unknown;
+  widgetPlacements?: unknown;
+}
+
+/** Validate + narrow the given fields into `AppInstallPatch`, or a 400 message. */
+function parsePatch(body: UpdateBody): AppInstallPatch | string {
+  const patch: AppInstallPatch = {};
+  if (body.appVersion !== undefined) {
+    if (typeof body.appVersion !== "string" || !body.appVersion.trim()) {
+      return "appVersion, when given, must be a non-empty string";
+    }
+    patch.appVersion = body.appVersion;
+  }
+  if (body.scopes !== undefined) {
+    if (!Array.isArray(body.scopes) || body.scopes.some((s) => typeof s !== "string")) {
+      return "scopes, when given, must be a string[]";
+    }
+    patch.scopes = body.scopes as string[];
+  }
+  if (body.manifest !== undefined) {
+    if (body.manifest === null || typeof body.manifest !== "object" || Array.isArray(body.manifest)) {
+      return "manifest, when given, must be an object";
+    }
+    patch.manifest = body.manifest;
+  }
+  if (body.webhookEndpoint !== undefined) {
+    if (body.webhookEndpoint !== null && typeof body.webhookEndpoint !== "string") {
+      return "webhookEndpoint, when given, must be a string or null";
+    }
+    patch.webhookEndpoint = body.webhookEndpoint as string | null;
+  }
+  if (body.widgetPlacements !== undefined) {
+    if (!Array.isArray(body.widgetPlacements)) return "widgetPlacements, when given, must be an array";
+    patch.widgetPlacements = body.widgetPlacements;
+  }
+  return patch;
+}
+
+export async function POST(context: APIContext): Promise<Response> {
+  const requestedTenant = new URL(context.request.url).searchParams.get("tenant");
+  const auth = await resolveOperatorSession(context, requestedTenant);
+  if (!auth.ok) return json({ error: auth.message }, auth.status);
+  const manageDenied = requireManageRole(auth);
+  if (manageDenied) return manageDenied;
+
+  let body: UpdateBody;
+  try {
+    body = (await context.request.json()) as UpdateBody;
+  } catch {
+    return json({ error: "invalid JSON body" }, 400);
+  }
+
+  const installId = parseInstallId(body);
+  if (!installId) return json({ error: "installId is required" }, 400);
+
+  const patch = parsePatch(body);
+  if (typeof patch === "string") return json({ error: patch }, 400);
+
+  const registry = await getRegistryService();
+  if (registry instanceof Response) return registry;
+
+  const owned = await requireOwnedInstall(registry, installId, auth.tenantId);
+  if (owned instanceof Response) return owned;
+
+  try {
+    const install = await registry.update(installId, patch, auth.actor);
+    return json({ install });
+  } catch (err) {
+    if (err instanceof RegistryError) return registryErrorResponse(err);
+    throw err;
+  }
+}

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

@@ -0,0 +1,59 @@
+/**
+ * POST /api/apps/admin/webhooks/deliveries/{deliveryId}/replay — the
+ * ops/support replay (PrivateApps epic, D4 Chunk E; D8 console-session auth
+ * added). Operator session only; `tenantId` comes from `auth.tenantId`
+ * (`resolveOperatorSession`), never the request. A `deliveryId` whose
+ * `tenantId` doesn't match the operator's resolved tenant 404s identically to
+ * a truly-missing one — same no-cross-tenant-oracle discipline
+ * `requireOwnedInstall` keeps for install ids. `webhook_deliveries` already
+ * carries its own `tenantId` (set at creation, mirroring the owning
+ * install's), so this checks that column directly rather than round-tripping
+ * through the registry. Mutating (re-enqueues a delivery): `requireManageRole`
+ * gates a console `developer` role out — the host-bound/Bearer path is
+ * exempt (no `role`).
+ *
+ * Not part of the app-facing `openapi.yaml` contract (same as the rest of
+ * `admin/*`) — no `Idempotency-Key` requirement; an authenticated operator
+ * retriggering a replay isn't the untrusted-client-retry case that header
+ * guards against.
+ *
+ * Same `requeueForReplay` + same-`deliveryId` re-enqueue as the app-facing
+ * replay — see that route's doc comment for the full rationale.
+ */
+import type { APIContext } from "astro";
+import { resolveOperatorSession } from "@/lib/apps/adminSession.js";
+import { json, requireManageRole } from "@/lib/apps/adminService.js";
+import { WebhookDeliveryStore } from "@/lib/webhooks/deliveryStore.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 requestedTenant = new URL(context.request.url).searchParams.get("tenant");
+  const auth = await resolveOperatorSession(context, requestedTenant);
+  if (!auth.ok) return json({ error: auth.message }, auth.status);
+  const manageDenied = requireManageRole(auth);
+  if (manageDenied) return manageDenied;
+
+  const deliveryId = context.params.deliveryId;
+  if (!deliveryId) return json({ error: "Delivery not found.", code: "not_found" }, 404);
+
+  const d1 = await readD1("STOREFRONT_APPS_DB");
+  if (!d1) return json({ error: "webhook store not configured" }, 503);
+  const store = new WebhookDeliveryStore(fromD1(d1));
+
+  const delivery = await store.getDelivery(deliveryId);
+  if (!delivery || delivery.tenantId !== auth.tenantId) {
+    return json({ error: "Delivery not found.", code: "not_found" }, 404);
+  }
+
+  const dispatcher = await getDispatcher();
+  if (dispatcher instanceof Response) return dispatcher;
+
+  const requeued = await store.requeueForReplay(deliveryId);
+  await dispatcher.enqueue({ deliveryId });
+
+  return json({ delivery: requeued }, 202);
+}

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

@@ -0,0 +1,51 @@
+/**
+ * GET /api/apps/admin/webhooks/deliveries — the ops/support tenant-wide
+ * delivery view (PrivateApps epic, D4 Chunk E; D8 console-session auth
+ * added). `tenantId` used below comes only from the resolved operator
+ * session (`auth.tenantId`), never a raw query param — mirrors
+ * `admin/list.ts`'s tenant scoping; the same `?tenant=` param is read only as
+ * a CANDIDATE for `resolveOperatorSession` to admit against. Unlike the
+ * app-facing `/api/apps/v1/webhooks/deliveries` (one install's own
+ * deliveries), this surfaces every install's deliveries for the operator's
+ * tenant via the additive `listDeliveriesByTenant` store method. Read-only:
+ * any membership role admits.
+ *
+ * Not part of the app-facing `openapi.yaml` contract (same as the rest of
+ * `admin/*`) — returns the internal `WebhookDelivery` shape as-is (installId
+ * included; useful for support triage), no `toContractDelivery` narrowing.
+ */
+import type { APIContext } from "astro";
+import { resolveOperatorSession } from "@/lib/apps/adminSession.js";
+import { json } from "@/lib/apps/adminService.js";
+import { WebhookDeliveryStore, type DeliveryState } from "@/lib/webhooks/deliveryStore.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 params = new URL(context.request.url).searchParams;
+  const auth = await resolveOperatorSession(context, params.get("tenant"));
+  if (!auth.ok) return json({ error: auth.message }, auth.status);
+
+  const state = parseStateFilter(params.get("state"));
+  if (state === "invalid") {
+    return json({ error: "invalid state filter", code: "invalid_state_filter" }, 400);
+  }
+
+  const d1 = await readD1("STOREFRONT_APPS_DB");
+  if (!d1) return json({ error: "webhook store not configured" }, 503);
+  const store = new WebhookDeliveryStore(fromD1(d1));
+
+  const deliveries = await store.listDeliveriesByTenant(auth.tenantId, { state });
+
+  return json({ deliveries });
+}