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

package/apps/storefront/src/lib/apps/tokenIssuer.ts

@@ -0,0 +1,121 @@
+/**
+ * OAuth2 client-credentials token issuer — the Storefront App Gateway's
+ * `POST /oauth/token` grant (PrivateApps epic, D2 Chunk B). Mints the
+ * short-lived RS256 JWT a private app presents as a bearer token to the D3
+ * scoped APIs.
+ *
+ * `tenant` and `env` are supplied by the CALLER (the route, from
+ * host-resolved context — never from the request body) and checked against
+ * the install's own `tenantId`/`env`: a credential minted for one
+ * tenant/env can't be replayed against another, even if the secret leaked.
+ *
+ * Fails closed on every rejected path; `TokenError.code` uses the RFC 6749
+ * §5.2 / §4.1.2.1 error vocabulary so the route can pass it straight through
+ * as the OAuth2 `error` field. `invalid_client` deliberately covers "unknown
+ * client_id", "wrong secret", AND "tenant/env mismatch" identically — none of
+ * those should be distinguishable to a caller (no enumeration oracle).
+ */
+import { SignJWT } from "jose";
+import type { AppRegistryService } from "./registryService.js";
+import {
+  loadGatewaySigningConfig,
+  GatewayKeyError,
+  APP_GATEWAY_ALG,
+  APP_TOKEN_TTL_SECONDS,
+  type GatewayKeyOverrides,
+} from "./gatewayKeys.js";
+
+export type TokenErrorCode = "invalid_client" | "invalid_grant" | "temporarily_unavailable";
+
+export class TokenError extends Error {
+  constructor(
+    message: string,
+    readonly code: TokenErrorCode,
+  ) {
+    super(message);
+    this.name = "TokenError";
+  }
+}
+
+/** The narrow secret-verification seam `AppTokenIssuer` depends on (`D1CredentialStore` satisfies it). */
+export interface SecretVerifier {
+  verifySecret(clientId: string, presentedSecret: string): Promise<string | null>;
+}
+
+export interface IssueTokenRequest {
+  clientId: string;
+  secret: string;
+  /** This request's host-resolved tenant (never client-supplied). */
+  tenant: string;
+  /** This deploy's own env tier (never client-supplied). */
+  env: string;
+}
+
+export interface IssuedToken {
+  accessToken: string;
+  tokenType: "Bearer";
+  expiresIn: number;
+  scope: string;
+}
+
+export class AppTokenIssuer {
+  constructor(
+    private readonly registry: AppRegistryService,
+    private readonly credentials: SecretVerifier,
+    private readonly keyOverrides: GatewayKeyOverrides = {},
+    private readonly now: () => number = () => Math.floor(Date.now() / 1000),
+  ) {}
+
+  async issueToken(req: IssueTokenRequest): Promise<IssuedToken> {
+    const installId = await this.credentials.verifySecret(req.clientId, req.secret);
+    if (!installId) {
+      throw new TokenError("invalid client_id or client_secret", "invalid_client");
+    }
+
+    const install = await this.registry.get(installId);
+    // An install row can't outlive its credential row (uninstall clears both),
+    // but never let a lookup miss here leak any more detail than a bad secret.
+    if (!install || install.tenantId !== req.tenant || install.env !== req.env) {
+      throw new TokenError("invalid client_id or client_secret", "invalid_client");
+    }
+    if (install.status !== "active") {
+      throw new TokenError(`install is ${install.status}; token issuance refused`, "invalid_grant");
+    }
+
+    let signing;
+    try {
+      signing = await loadGatewaySigningConfig(this.keyOverrides);
+    } catch (cause) {
+      if (cause instanceof GatewayKeyError) {
+        throw new TokenError(cause.message, "temporarily_unavailable");
+      }
+      throw cause;
+    }
+
+    const nowSeconds = this.now();
+    const accessToken = await new SignJWT({
+      tenant: install.tenantId,
+      env: install.env,
+      scopes: install.scopes,
+      // Discriminates this bearer token from a widget launch token (D5 Chunk
+      // B) so the two can never be replayed for each other even though both
+      // are RS256 JWTs signed by the same gateway key — see tokenVerifier.ts.
+      token_use: "access",
+    })
+      .setProtectedHeader({ alg: APP_GATEWAY_ALG, kid: signing.kid, typ: "JWT" })
+      .setIssuer(signing.issuer)
+      .setSubject(install.installId)
+      .setAudience(install.tenantId)
+      .setJti(crypto.randomUUID())
+      .setIssuedAt(nowSeconds)
+      .setExpirationTime(nowSeconds + APP_TOKEN_TTL_SECONDS)
+      .sign(signing.key);
+
+    return {
+      accessToken,
+      tokenType: "Bearer",
+      expiresIn: APP_TOKEN_TTL_SECONDS,
+      scope: install.scopes.join(" "),
+    };
+  }
+}

package/apps/storefront/src/lib/apps/tokenVerifier.ts

@@ -0,0 +1,148 @@
+/**
+ * Offline verification of the Storefront App Gateway's own OAuth2
+ * client-credentials JWT (PrivateApps epic, D2 Chunk B) — this is what D3
+ * imports at the scoped-API boundary to authorize an app's request.
+ *
+ * Modeled directly on `../auth/identityToken.ts`'s `IdentityAssertionVerifier`
+ * (same `jwtVerify` + JWKS-by-`kid` shape, `aud`/`iss` pinning, alg allowlist),
+ * but LOCAL only: this Worker signs its own tokens, so there's no remote host
+ * to fetch a JWKS from — the public JWKS is derived in-process by
+ * `gatewayKeys.ts` from the very key that signs, via `createLocalJWKSet`.
+ */
+import {
+  jwtVerify,
+  createLocalJWKSet,
+  decodeProtectedHeader,
+  type JWTVerifyGetKey,
+} from "jose";
+import {
+  loadGatewayJwks,
+  GatewayKeyError,
+  APP_GATEWAY_ALG,
+  DEFAULT_APP_GATEWAY_ISSUER,
+  APP_GATEWAY_ISSUER_ENV,
+  type GatewayKeyOverrides,
+} from "./gatewayKeys.js";
+import { readEnv } from "@/lib/env";
+
+/** The verified app-token claims (D3's authorization input). */
+export interface AppTokenClaims {
+  iss: string;
+  sub: string; // install id
+  aud: string; // tenant
+  tenant: string;
+  env: string;
+  scopes: string[];
+  iat: number;
+  exp: number;
+  jti: string;
+}
+
+/** Normalize a jose JWT payload into typed {@link AppTokenClaims}, throwing on any missing claim. */
+function toAppTokenClaims(payload: Record<string, unknown>): AppTokenClaims {
+  // The security-critical discriminator: a widget launch token (D5 Chunk B,
+  // `token_use: "widget_launch"`) is signed by this SAME gateway key, so
+  // signature/aud/iss/exp checks alone can't tell it apart from a bearer
+  // token. Requiring `token_use === "access"` here is what stops a launch
+  // token — minted for a sandboxed iframe, short-TTL, no scopes checked —
+  // from ever being replayed as an API bearer token.
+  if (payload.token_use !== "access") {
+    throw new Error("app token has the wrong `token_use`; expected an access token");
+  }
+  const tenant = payload.tenant;
+  if (typeof tenant !== "string" || !tenant) {
+    throw new Error("app token missing `tenant` claim");
+  }
+  const env = payload.env;
+  if (typeof env !== "string" || !env) {
+    throw new Error("app token missing `env` claim");
+  }
+  const jti = payload.jti;
+  if (typeof jti !== "string" || !jti) {
+    throw new Error("app token missing `jti` claim");
+  }
+  if (!Array.isArray(payload.scopes)) {
+    throw new Error("app token missing `scopes` claim");
+  }
+  const scopes = payload.scopes.filter((s): s is string => typeof s === "string");
+
+  return {
+    iss: String(payload.iss ?? ""),
+    sub: String(payload.sub ?? ""),
+    aud: String(payload.aud ?? ""),
+    tenant,
+    env,
+    scopes,
+    iat: Number(payload.iat ?? 0),
+    exp: Number(payload.exp ?? 0),
+    jti,
+  };
+}
+
+export interface AppTokenVerifierConfig {
+  /** This request's tenant — pinned as the required `aud` (per-tenant, mirrors identityToken.ts). */
+  tenant: string;
+  issuer?: string;
+  keys: JWTVerifyGetKey;
+}
+
+/**
+ * Verifies app-gateway tokens offline against the LOCAL JWKS. One instance
+ * per tenant (its `aud` pin is fixed).
+ */
+export class AppTokenVerifier {
+  private readonly tenant: string;
+  private readonly issuer: string;
+  private readonly keys: JWTVerifyGetKey;
+
+  constructor(config: AppTokenVerifierConfig) {
+    if (!config.tenant) {
+      throw new Error("AppTokenVerifier requires a `tenant` (this request's resource)");
+    }
+    this.tenant = config.tenant;
+    this.issuer = config.issuer ?? DEFAULT_APP_GATEWAY_ISSUER;
+    this.keys = config.keys;
+  }
+
+  /**
+   * Verify a compact JWS and return typed claims. Rejects (throws) on: any
+   * `alg` other than RS256 (blocks `alg:none` and every HS*), bad signature,
+   * wrong/absent `aud`, unlisted `iss`, or expired/not-yet-valid `exp`/`iat`.
+   */
+  async verify(token: string): Promise<AppTokenClaims> {
+    const header = decodeProtectedHeader(token);
+    if (header.alg !== APP_GATEWAY_ALG) {
+      throw new Error(`unexpected JWT alg ${String(header.alg)}; only ${APP_GATEWAY_ALG} is accepted`);
+    }
+
+    const { payload } = await jwtVerify(token, this.keys, {
+      issuer: this.issuer,
+      audience: this.tenant,
+      algorithms: [APP_GATEWAY_ALG],
+    });
+
+    return toAppTokenClaims(payload as Record<string, unknown>);
+  }
+}
+
+/**
+ * Get (or build) the verifier for one tenant, from the gateway's own
+ * locally-derived JWKS. Returns `null` when the signing key isn't configured
+ * — callers (D3 routes) fail closed with 503, mirroring `getIdentityVerifier`.
+ * Not cached across calls (unlike `identityToken.ts`'s remote-fetch verifier):
+ * deriving the local JWKS is cheap (`gatewayKeys.ts` caches the export itself).
+ */
+export async function getAppTokenVerifier(
+  tenant: string,
+  overrides: GatewayKeyOverrides = {},
+): Promise<AppTokenVerifier | null> {
+  let jwks;
+  try {
+    jwks = await loadGatewayJwks(overrides);
+  } catch (cause) {
+    if (cause instanceof GatewayKeyError) return null;
+    throw cause;
+  }
+  const issuer = overrides.issuer ?? (await readEnv(APP_GATEWAY_ISSUER_ENV)) ?? DEFAULT_APP_GATEWAY_ISSUER;
+  return new AppTokenVerifier({ tenant, issuer, keys: createLocalJWKSet(jwks) });
+}

package/apps/storefront/src/lib/apps/widgets/eligibility.ts

@@ -0,0 +1,18 @@
+/**
+ * Widget eligibility — PrivateApps epic, D5 (Chunk C). Mirrors
+ * `webhooks/emit.ts`'s `isEligibleTarget` discipline: an install is eligible
+ * to render its widget at `slot` only while it is LIVE — `active`, scoped for
+ * `widgets:launch`, and carrying a validated placement for that slot. This
+ * live check is what makes suspending an install actually stop it rendering
+ * on the very next page load — the D8 "suspension kills widgets"
+ * enforcement — with no separate revoke step; it's just this gate re-run on
+ * every request.
+ */
+import type { AppInstall } from "../registryService.js";
+
+/** True when `install` is currently eligible to render its widget at `slot`. */
+export function isWidgetEligible(install: AppInstall, slot: string): boolean {
+  if (install.status !== "active") return false;
+  if (!install.scopes.includes("widgets:launch")) return false;
+  return install.widgetPlacements.some((placement) => placement.placement === slot);
+}

package/apps/storefront/src/lib/apps/widgets/frameProps.ts

@@ -0,0 +1,52 @@
+/**
+ * Pure prop-building for `<AppWidgetFrame>` — PrivateApps epic, D5 (Chunk D).
+ * Split out of the `.astro` component so the query-param handoff and the
+ * sandbox attrs are unit-testable: `vitest.config.ts` deliberately does NOT
+ * render `.astro` components (Astro Container API breaks under vitest@2 +
+ * astro@7 — see that file's docstring), so render *logic* lives here and
+ * rendered output is verified on a live preview instead.
+ *
+ * Sandbox/loading/referrerpolicy come straight from `widgetFrameAttrs()` —
+ * the SAME helper `WidgetFrame.astro` calls for tenant `scripts.json`
+ * widgets — so `allow-scripts`/no-`allow-same-origin` is defined in exactly
+ * ONE place and can't drift between the two call sites.
+ */
+import { widgetFrameAttrs, type ScriptStrategy, type WidgetFrameAttrs } from "@tot/public-runtime";
+
+export interface AppWidgetFrameProps {
+  endpoint: string;
+  launchToken: string;
+  appOrigin: string;
+  installId: string;
+  title: string;
+  strategy?: ScriptStrategy;
+  height?: string;
+}
+
+export interface AppWidgetFrameAttrs extends WidgetFrameAttrs {
+  src: string;
+  title: string;
+  height: string;
+  /** Stamped directly on the `<iframe>` for the postMessage bridge's origin/install registry. */
+  dataWidgetOrigin: string;
+  dataInstallId: string;
+}
+
+/**
+ * Query-param handoff: the launch token rides as `?tot_launch=<jwt>` on the
+ * VALIDATED `endpoint` (never a merchant-supplied query string blindly
+ * concatenated — `URL` + `searchParams.set` handles an endpoint that already
+ * carries its own query string correctly, overwriting only `tot_launch`).
+ */
+export function buildAppWidgetFrameAttrs(props: AppWidgetFrameProps): AppWidgetFrameAttrs {
+  const url = new URL(props.endpoint);
+  url.searchParams.set("tot_launch", props.launchToken);
+  return {
+    ...widgetFrameAttrs(props.strategy ?? "on-idle"),
+    src: url.toString(),
+    title: props.title,
+    height: props.height ?? "auto",
+    dataWidgetOrigin: props.appOrigin,
+    dataInstallId: props.installId,
+  };
+}

package/apps/storefront/src/lib/apps/widgets/launchToken.ts

@@ -0,0 +1,84 @@
+/**
+ * Widget launch-token minting — PrivateApps epic, D5 Chunk B. Mints the
+ * short-lived RS256 JWT a platform-managed sandboxed widget iframe carries at
+ * SSR render time: Chunk D calls `mintWidgetLaunchToken` while rendering the
+ * page for each declared placement, and the resulting token is what the
+ * widget's own endpoint receives as proof it was launched by THIS platform,
+ * for THIS install, at THIS placement — never a merchant-forged or replayed
+ * value.
+ *
+ * Signed by the SAME gateway key as `../tokenIssuer.ts`'s bearer tokens (via
+ * `loadGatewaySigningConfig` — no separate key is provisioned for widgets),
+ * but carries `token_use: "widget_launch"` instead of `"access"`.
+ * `../tokenVerifier.ts` REQUIRES the latter, so this token can never be
+ * replayed as an API bearer token even though both are RS256 JWTs from the
+ * same key — that discriminator is what keeps the two token kinds separate.
+ *
+ * Per the `widgets:launch` scope contract
+ * (`docs/private-apps/contract/scopes.json`): the claim set is limited to
+ * tenant, env, slot, route, an optional product handle, and locale/theme
+ * hints — NEVER secrets or customer PII.
+ */
+import { SignJWT } from "jose";
+import type { AppInstall, WidgetPlacement } from "../registryService.js";
+import {
+  loadGatewaySigningConfig,
+  APP_GATEWAY_ALG,
+  WIDGET_LAUNCH_TOKEN_TTL_SECONDS,
+  type GatewayKeyOverrides,
+} from "../gatewayKeys.js";
+
+export interface MintWidgetLaunchTokenInput {
+  /**
+   * Only `installId`/`tenantId`/`env` are read. Narrowed from `AppInstall` to
+   * this `Pick` so Chunk D's render path — which has `placements.ts`'s
+   * `ResolvedPlacement` (installId/appOrigin/endpoint), not the full
+   * `AppInstall` — can build the minimal object itself instead of re-fetching
+   * the install; a full `AppInstall` still satisfies this shape unchanged.
+   */
+  install: Pick<AppInstall, "installId" | "tenantId" | "env">;
+  slot: WidgetPlacement;
+  route: string;
+  /** Present only when the render context is a specific product. */
+  productHandle?: string;
+  locale: string;
+  theme: string;
+}
+
+/**
+ * Mint one widget launch token, valid for {@link WIDGET_LAUNCH_TOKEN_TTL_SECONDS}.
+ * FAILS CLOSED: propagates `GatewayKeyError` when the gateway signing key is
+ * unconfigured — same guarantee `AppTokenIssuer.issueToken` relies on; there
+ * is no "render the widget anyway" fallback with an unsigned token.
+ */
+export async function mintWidgetLaunchToken(
+  input: MintWidgetLaunchTokenInput,
+  overrides: GatewayKeyOverrides = {},
+): Promise<string> {
+  const signing = await loadGatewaySigningConfig(overrides);
+  const nowSeconds = Math.floor(Date.now() / 1000);
+
+  return new SignJWT({
+    tenant: input.install.tenantId,
+    env: input.install.env,
+    slot: input.slot,
+    route: input.route,
+    ...(input.productHandle !== undefined ? { productHandle: input.productHandle } : {}),
+    locale: input.locale,
+    theme: input.theme,
+    token_use: "widget_launch",
+  })
+    .setProtectedHeader({ alg: APP_GATEWAY_ALG, kid: signing.kid, typ: "JWT" })
+    .setIssuer(signing.issuer)
+    .setSubject(input.install.installId)
+    // `aud` is the INSTALL, not the tenant: a tenant can have several installs,
+    // and binding to the tenant would let a token leaked to one install be
+    // accepted by a sibling install's (possibly laxer) verifier. Binding to
+    // installId means a verifier that only checks iss/aud already fails closed
+    // across installs.
+    .setAudience(input.install.installId)
+    .setJti(crypto.randomUUID())
+    .setIssuedAt(nowSeconds)
+    .setExpirationTime(nowSeconds + WIDGET_LAUNCH_TOKEN_TTL_SECONDS)
+    .sign(signing.key);
+}

package/apps/storefront/src/lib/apps/widgets/placements.ts

@@ -0,0 +1,57 @@
+/**
+ * Widget placement resolution — PrivateApps epic, D5 (Chunk C). Turns "which
+ * apps have a live widget at this slot" into the concrete list Chunk D needs
+ * to render sandboxed iframes and mint launch tokens: reads
+ * `registry.listByTenant`, filters to the requested `env` and
+ * {@link isWidgetEligible}, then reads each eligible install's `endpoint`
+ * from its VALIDATED `widgetPlacements` field — never `install.manifest`,
+ * which is the raw unvalidated manifest snapshot. `widgetPlacements` is the
+ * one field `AppRegistryService.install`/`update` already ran through the
+ * placement-enum + `widgets:launch` scope + SSRF gate (`registryService.ts`'s
+ * `validateWidgetPlacements`), so it's the only safe source for an iframe
+ * `src`.
+ *
+ * Multiple eligible installs for the same slot all render, sorted by
+ * `createdAt` ascending (install order) rather than trusting
+ * `listByTenant`'s own ordering — that's newest-first, chosen for admin-UI
+ * listing, not widget rendering — so this stays correct even if that
+ * ordering ever changes.
+ */
+import { isWidgetEligible } from "./eligibility.js";
+import type { AppRegistryService } from "../registryService.js";
+
+/** One live widget ready to render: the app's origin, the exact endpoint to launch, and its install. */
+export interface ResolvedPlacement {
+  installId: string;
+  appOrigin: string;
+  endpoint: string;
+  title?: string;
+}
+
+/**
+ * Resolve every live widget placement for `slot` on `tenantId` within `env`.
+ * Returns `[]` (not an error) when nothing is eligible — same "empty is
+ * normal" contract as `emit.ts`'s eligible-target resolution.
+ */
+export async function resolveActivePlacements(
+  registry: Pick<AppRegistryService, "listByTenant">,
+  tenantId: string,
+  env: string,
+  slot: string,
+): Promise<ResolvedPlacement[]> {
+  const candidates = await registry.listByTenant(tenantId);
+  const eligible = candidates
+    .filter((install) => install.env === env && isWidgetEligible(install, slot))
+    .sort((a, b) => a.createdAt.localeCompare(b.createdAt) || a.installId.localeCompare(b.installId));
+
+  return eligible.map((install) => {
+    // Guaranteed to exist: isWidgetEligible already confirmed a matching placement.
+    const placement = install.widgetPlacements.find((p) => p.placement === slot)!;
+    return {
+      installId: install.installId,
+      appOrigin: new URL(placement.endpoint).origin,
+      endpoint: placement.endpoint,
+      ...(placement.title !== undefined ? { title: placement.title } : {}),
+    };
+  });
+}

package/apps/storefront/src/lib/apps/widgets/renderSlot.ts

@@ -0,0 +1,111 @@
+/**
+ * Widget slot render composition — PrivateApps epic, D5 (Chunk D). The one
+ * call a page/layout makes to turn "render slot X for this request" into the
+ * concrete, launch-token-bearing list `AppWidgetFrame` needs: resolves live
+ * placements (`placements.ts`), mints each one a launch token
+ * (`launchToken.ts`), and — via `sink` — reports which endpoints rendered so
+ * the middleware can extend the response CSP's `frame-src`
+ * (`@tot/public-runtime`'s `appWidgetCspAdditions`).
+ *
+ * `launchToken.ts` wants `install.tenantId`/`env`/`installId`; a
+ * `ResolvedPlacement` only carries `installId` (see its own docstring for
+ * why endpoint/origin must come from the validated placement, not a raw
+ * install fetch). tenantId and env are already this call's OWN parameters,
+ * so the minimal `install` object is built here rather than re-fetching —
+ * no second registry round-trip per placement.
+ *
+ * The storefront's content-serving env (`CustomizationEnv`, `"live"|"test"`)
+ * and the app-install env (`docs/private-apps/contract/openapi.yaml`'s
+ * `development|test|sandbox|production` enum) are DIFFERENT vocabularies —
+ * an install's env is the operator's own choice at `app.install` time,
+ * orthogonal to content publishing. `"live"` maps to the env an operator
+ * would use once they trust the app in front of real shoppers:
+ * `"production"`; `"test"` maps 1:1 (same word, same "not the real site"
+ * intent in both vocabularies).
+ */
+import type { AppRegistryService, WidgetPlacement } from "../registryService.js";
+import { resolveActivePlacements, type ResolvedPlacement } from "./placements.js";
+import { mintWidgetLaunchToken } from "./launchToken.js";
+
+export type CustomizationEnv = "live" | "test";
+
+/** Map the storefront's content-serving env to the app-install env vocabulary. */
+export function appInstallEnv(customizationEnv: CustomizationEnv): string {
+  return customizationEnv === "live" ? "production" : "test";
+}
+
+/** One live widget, ready for `AppWidgetFrame`: its placement plus a minted launch token. */
+export interface RenderedWidgetSlot extends ResolvedPlacement {
+  launchToken: string;
+}
+
+export interface RenderWidgetSlotInput {
+  /**
+   * `getRegistryService()`'s return type — a `Response` means the app
+   * registry isn't configured in this runtime (missing `STOREFRONT_APPS_DB`
+   * binding). That must never break the page it would have decorated, so it
+   * resolves to no widgets rather than propagating the error.
+   */
+  registry: Pick<AppRegistryService, "listByTenant"> | Response;
+  tenantId: string;
+  customizationEnv: CustomizationEnv;
+  slot: WidgetPlacement;
+  route: string;
+  /** Present only when the render context is a specific product (product.aside). */
+  productHandle?: string;
+  locale: string;
+  theme: string;
+}
+
+/**
+ * Resolve + mint every live widget for `slot` on this request. Returns `[]`
+ * and NEVER throws — when nothing is eligible, the registry isn't configured,
+ * OR resolution/minting fails (e.g. the private-apps tables aren't provisioned
+ * in this env, or the signing key is unset). A private-apps failure must never
+ * break the storefront page it would only have decorated.
+ * When `sink` is given, every rendered placement is also pushed onto it —
+ * pass `Astro.locals.activeWidgetPlacements` so the middleware can read the
+ * full per-request set back out after `next()` for the CSP `frame-src`.
+ */
+export async function renderWidgetSlot(
+  input: RenderWidgetSlotInput,
+  sink?: Pick<ResolvedPlacement, "endpoint">[],
+): Promise<RenderedWidgetSlot[]> {
+  if (input.registry instanceof Response) return [];
+
+  try {
+    const env = appInstallEnv(input.customizationEnv);
+    const placements = await resolveActivePlacements(input.registry, input.tenantId, env, input.slot);
+
+    const rendered = await Promise.all(
+      placements.map(async (placement) => ({
+        ...placement,
+        launchToken: await mintWidgetLaunchToken({
+          install: { installId: placement.installId, tenantId: input.tenantId, env },
+          slot: input.slot,
+          route: input.route,
+          ...(input.productHandle !== undefined ? { productHandle: input.productHandle } : {}),
+          locale: input.locale,
+          theme: input.theme,
+        }),
+      })),
+    );
+
+    sink?.push(...rendered);
+    return rendered;
+  } catch (cause) {
+    // NEVER break the host page (which is every page — Layout's global.footer
+    // slot). A registry/query/mint failure — e.g. the private-apps tables
+    // aren't provisioned in this env, or the app-gateway signing key is unset —
+    // resolves to NO widgets, not a 500. This is the choke point that honors
+    // this module's documented never-throws contract for all slot hosts.
+    console.warn(
+      "[diag:widgets:render] slot resolution failed — rendering no widgets",
+      JSON.stringify({
+        slot: input.slot,
+        reason: cause instanceof Error ? cause.message : String(cause),
+      }),
+    );
+    return [];
+  }
+}