@tokenoftrust/storefront-runner 2.0.2 → 2.0.4

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

@@ -1,116 +0,0 @@
-/**
- * Composition root + shared helpers for the `/api/apps/admin/*` routes —
- * builds an `AppRegistryService` over the
- * `STOREFRONT_APPS_DB` `Queryable` binding and a `D1CredentialStore`, the same
- * construction `api/apps/oauth/token.ts` uses, and mirrors
- * `../grants/route.ts`'s `getService()` + no-store `json()` + 503-when-
- * unconfigured pattern. Kept out of the pure service module so that stays
- * transport-free and unit-testable against a fake `Queryable`.
- */
-import {
-  AppRegistryService,
-  RegistryError,
-  type AppInstall,
-  type RegistryErrorCode,
-} from "./registryService.js";
-import { D1CredentialStore } from "./credentials.js";
-import { DEFAULT_APP_GATEWAY_KID, APP_GATEWAY_KID_ENV } from "./gatewayKeys.js";
-import { fromD1 } from "../d1/catalog.js";
-import { readD1, readEnv } from "../env.js";
-import { MANAGE_ROLES, type AdminAuthResult } from "./adminSession.js";
-import { ManagedAnalyticsApiV1Facade } from "./managedAnalyticsService.js";
-
-/**
- * No-store JSON response — install/rotate bodies carry a one-time client
- * secret and must never be edge- or browser-cached.
- */
-export function json(body: unknown, status = 200): Response {
-  return new Response(JSON.stringify(body), {
-    status,
-    headers: { "content-type": "application/json", "cache-control": "no-store" },
-  });
-}
-
-/**
- * Build an `AppRegistryService` over the real `STOREFRONT_APPS_DB` D1
- * binding, or return a 503 Response when that binding isn't configured in
- * this runtime. Never leaks binding/secret detail in the response body.
- */
-export async function getRegistryService(): Promise<AppRegistryService | Response> {
-  const d1 = await readD1("STOREFRONT_APPS_DB");
-  if (!d1) return json({ error: "app registry not configured" }, 503);
-  const db = fromD1(d1);
-  const activeKid = (await readEnv(APP_GATEWAY_KID_ENV)) ?? DEFAULT_APP_GATEWAY_KID;
-  const credentials = new D1CredentialStore(db, activeKid);
-  return new AppRegistryService(db, credentials);
-}
-
-/** Build the managed-analytics v1 service over the same tenant control-plane D1. */
-export async function getManagedAnalyticsService(): Promise<ManagedAnalyticsApiV1Facade | Response> {
-  const d1 = await readD1("STOREFRONT_APPS_DB");
-  if (!d1) return json({ error: "app registry not configured" }, 503);
-  return new ManagedAnalyticsApiV1Facade(fromD1(d1));
-}
-
-/** HTTP status per `RegistryError` code — the one shared fail-closed mapping. */
-const STATUS_BY_REGISTRY_CODE: Record<RegistryErrorCode, number> = {
-  scope_denied: 400,
-  not_found: 404,
-  already_installed: 409,
-  invalid_state: 409,
-  invalid_webhook_endpoint: 400,
-  invalid_widget_placement: 400,
-  unknown_version: 404,
-  invalid_version_facets: 400,
-};
-
-/** Map a `RegistryError` to its HTTP status. Never echoes internals — code + message only. */
-export function registryErrorResponse(err: RegistryError): Response {
-  const body: Record<string, unknown> = { error: err.message, code: err.code };
-  if (err.denials) body.denials = err.denials;
-  return json(body, STATUS_BY_REGISTRY_CODE[err.code]);
-}
-
-/** Parse `{ installId }` from a JSON body — shared by every installId-bearing admin route. */
-export function parseInstallId(body: unknown): string | null {
-  if (!body || typeof body !== "object") return null;
-  const installId = (body as { installId?: unknown }).installId;
-  return typeof installId === "string" && installId.trim() ? installId.trim() : null;
-}
-
-/**
- * Resolve `installId` and verify it belongs to `tenantId` — every mutating
- * admin route (update/suspend/resume/uninstall/rotate) MUST call this BEFORE
- * invoking a service method, since those methods take a bare `installId` with
- * no tenant check of their own. A foreign-tenant
- * `installId` is reported IDENTICALLY to a truly-missing one — 404, same
- * body shape as `RegistryError("not_found")` — so there is no cross-tenant
- * existence oracle.
- */
-export async function requireOwnedInstall(
-  registry: AppRegistryService,
-  installId: string,
-  tenantId: string,
-): Promise<AppInstall | Response> {
-  const install = await registry.get(installId);
-  if (!install || install.tenantId !== tenantId) {
-    return json({ error: "App install not found.", code: "not_found" }, 404);
-  }
-  return install;
-}
-
-/**
- * Gate a mutating admin route on the resolved auth's role — call AFTER
- * `resolveOperatorSession` for every write route (suspend/resume/uninstall/
- * update/rotate/replay). A console session's `role` must be in
- * `MANAGE_ROLES`: a `developer` is read-only and gets a 403 here. The
- * host-bound/Bearer path (`resolveAdminSession`) carries no `role` at all —
- * it is already manage-capable (gated by `ADMIN_CAPABILITIES`/the dedicated
- * secret) — so an `undefined` role is exempt, not denied.
- */
-export function requireManageRole(auth: Extract<AdminAuthResult, { ok: true }>): Response | null {
-  if (auth.role !== undefined && !MANAGE_ROLES.has(auth.role)) {
-    return json({ error: "not authorized to manage apps for this tenant" }, 403);
-  }
-  return null;
-}

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

@@ -1,214 +0,0 @@
-/**
- * Operator-session resolution for the Private Apps admin API
- * (`/api/apps/admin/*`). Mirrors
- * `../grants/session.ts`'s owner-session resolution — same two paths, same
- * fail-closed shape — but resolves `{ tenantId, actor }` instead of `{ owner }`:
- *
- *   - `tenantId` is the `AppInstall.tenantId` scope. It MUST equal the
- *     host-resolved `appDomain` the OAuth token issuer checks installs
- *     against (`tokenIssuer.ts` compares `install.tenantId` to the caller's
- *     `context.locals.tenant.appDomain`) — so an app installed through this
- *     admin API is later discoverable by the SAME tenant identity a minted
- *     token is scoped to.
- *   - `actor` is an OPAQUE id for the audit log (`app_audit_log.actor` —
- *     "never email/PII", see `../d1/schema.ts`). A signed-in viewer's verified
- *     email is one-way hashed (`sha256Hex`, the same primitive `credentials.ts`
- *     uses for secrets) so distinct operators still produce distinct, stable
- *     audit actors without the trail ever holding an email address.
- *
- * Two resolution paths, tried in order:
- *   1. SIGNED-IN TENANT OPERATOR (primary). `context.locals.viewer` (set by
- *      the login-gate middleware from the `tot_session` cookie) plus
- *      `context.locals.tenant`. Admitted only for an owner/admin capability
- *      on the resolved tenant — a lower-capability viewer is a resolved
- *      session with insufficient authority, so this fails closed with 403
- *      rather than silently falling through to path 2.
- *   2. BEARER OPERATOR SECRET (fallback, headless console). Gated by a
- *      DEDICATED `APPS_ADMIN_SECRET` only — unlike grants' session, this does
- *      NOT fall back to the shared `PREVIEW_RECONCILE_SECRET`, since that
- *      secret must not double as a cross-tenant app-registry master key
- *      Unconfigured `APPS_ADMIN_SECRET`
- *      means this path is unavailable — fails closed rather than trusting
- *      another deployment's secret. The tenant is resolved server-side from
- *      `APPS_ADMIN_TENANT` env or the `X-Tot-Tenant` header (honoured only
- *      for an already-authenticated caller) — never from the request body.
- *      There is no per-caller identity on this path, so `actor` is the fixed
- *      literal below.
- *
- * Routes depend only on the `{ ok, tenantId, actor }` result. `authorizeAdmin`
- * is the pure core of path 2 (unit-testable, no I/O).
- *
- * Console admin session. The two paths above are host-bound:
- * they resolve exactly one tenant (`context.locals.tenant`). The
- * `/api/apps/admin/*` surface is also reachable from the multi-tenant vendor
- * console, where a signed-in viewer may hold memberships on several vendors —
- * so `resolveConsoleAdminSession` mirrors `../grants/team-members.ts`'s
- * pattern instead: `readViewerSession` (the FULL session, all `tenants[]`)
- * plus an explicit `requestedTenant` from the request, admitted via
- * `viewerCanAccess`/`membershipFor` (deny-by-default, staff-selection-aware).
- * Its `role` is the caller's resolved membership role
- * (`developer`|`appAdmin`|`appOwner`) so routes can gate mutations against
- * `MANAGE_ROLES` — a `developer` is read-only. `resolveOperatorSession` is
- * the single entry point routes call: it tries the console path first and
- * only falls back to `resolveAdminSession` (path 1/2 above) when there is NO
- * console session at all (401) — a console session that exists but lacks
- * access to `requestedTenant` fails closed with its own 403, the same
- * no-fall-through discipline path 1 already uses for an insufficient
- * capability.
- */
-import type { APIContext } from "astro";
-import { sha256Hex } from "@tot/public-runtime";
-import { readEnv } from "@/lib/env";
-import { readViewerSession } from "@/lib/auth/route.js";
-import { viewerCanAccess, membershipFor } from "@/lib/dashboard/tenantSelection.js";
-import {
-  authorizeBearerOperator,
-  resolveHostBoundSession,
-  type SessionFailure,
-} from "@/lib/auth/operatorSession.js";
-
-/** Capabilities that make a signed-in viewer an app-registry operator for their tenant. */
-const ADMIN_CAPABILITIES: ReadonlySet<string> = new Set(["owner", "admin"]);
-
-/** Console membership roles authorized to mutate installs — a `developer` is read-only. */
-export const MANAGE_ROLES: ReadonlySet<string> = new Set(["appOwner", "appAdmin"]);
-
-/** Opaque `actor` stamped for the shared Bearer fallback — no per-caller identity to hash. */
-const BEARER_ACTOR = "bearer-operator";
-
-/** How many hex chars of the email digest to keep — enough entropy to distinguish operators. */
-const ACTOR_HASH_LENGTH = 32;
-
-/** Pure inputs to the Bearer-fallback authorization decision (env + request, no I/O). */
-export interface AdminAuthInput {
-  /** The request `Authorization` header, if any. */
-  authHeader: string | null;
-  /** The configured operator gate secret (or undefined if unconfigured). */
-  gateSecret: string | undefined;
-  /** Server-configured tenant for this deployment (APPS_ADMIN_TENANT), if any. */
-  configuredTenant: string | undefined;
-  /** `X-Tot-Tenant` header — honoured only once the caller is authenticated. */
-  requestedTenant: string | null;
-}
-
-export type AdminAuthResult =
-  | { ok: true; tenantId: string; actor: string; role?: string }
-  | SessionFailure;
-
-/** The one authorized-success shape both host-bound and Bearer admin paths return. */
-type AdminAuthOk = Extract<AdminAuthResult, { ok: true }>;
-
-/**
- * Decide the authenticated tenant from env + request, with NO I/O —
- * unit-testable. Fail-closed: unconfigured gate → 503, bad/absent Bearer →
- * 401, no resolvable tenant → 400. A thin adapter over the shared
- * Bearer-operator core that maps its resolved `principal` to this surface's
- * `tenantId` and stamps the fixed `BEARER_ACTOR` (no per-caller identity here).
- */
-export function authorizeAdmin(input: AdminAuthInput): AdminAuthResult {
-  const res = authorizeBearerOperator({
-    authHeader: input.authHeader,
-    gateSecret: input.gateSecret,
-    configuredPrincipal: input.configuredTenant,
-    requestedPrincipal: input.requestedTenant,
-    unconfiguredMessage: "apps admin operator secret not configured",
-    unresolvedMessage: "tenant unresolved (set APPS_ADMIN_TENANT or X-Tot-Tenant)",
-  });
-  return res.ok
-    ? { ok: true, tenantId: res.principal, actor: BEARER_ACTOR }
-    : res;
-}
-
-/** One-way, stable pseudonym for an audit `actor` — never the email itself. */
-async function actorFromEmail(email: string): Promise<string> {
-  return `viewer:${(await sha256Hex(email)).slice(0, ACTOR_HASH_LENGTH)}`;
-}
-
-/**
- * Resolve the authenticated `{ tenantId, actor }` for a Private Apps admin
- * request from the runtime env + the incoming request. Never reads `tenantId`
- * from the body.
- */
-export async function resolveAdminSession(context: APIContext): Promise<AdminAuthResult> {
-  return resolveHostBoundSession<AdminAuthOk>(context, {
-    capabilities: ADMIN_CAPABILITIES,
-    // A resolved-but-insufficient viewer fails closed with 403 and does NOT
-    // fall through to the Bearer gate — an authenticated-but-under-privileged
-    // caller must not be silently admitted by a secret it also presents.
-    onInsufficientCapability: {
-      mode: "failClosed",
-      failure: {
-        ok: false,
-        status: 403,
-        message: "not authorized to manage apps for this tenant",
-      },
-    },
-    // Path 1: the tenant IS the resolved host's appDomain — never the body.
-    resolveViewer: async (viewer, tenantId) => ({
-      ok: true,
-      tenantId,
-      actor: await actorFromEmail(viewer.email),
-    }),
-    // Path 2 (fallback): the headless-console Bearer operator secret. Dedicated
-    // secret only — no fallback to another deployment's secret.
-    resolveBearer: async (ctx) => {
-      const gateSecret = await readEnv("APPS_ADMIN_SECRET");
-      const configuredTenant = await readEnv("APPS_ADMIN_TENANT");
-      return authorizeAdmin({
-        authHeader: ctx.request.headers.get("authorization"),
-        gateSecret,
-        configuredTenant,
-        requestedTenant: ctx.request.headers.get("x-tot-tenant"),
-      });
-    },
-  });
-}
-
-/**
- * Resolve a signed-in console viewer's admin session for `requestedTenant`
- * (the `?tenant=` query param every admin route now reads) — the multi-tenant
- * counterpart to `resolveAdminSession`'s host-bound path 1, mirroring
- * `../grants/team-members.ts`'s `readViewerSession` + `viewerCanAccess`
- * pattern instead of the single-tenant `locals.tenant`/`locals.viewer` gate.
- * Fail-closed: no session → 401 (the signal `resolveOperatorSession` uses to
- * fall back to the host-bound/Bearer path); a session with no membership or
- * live staff admission for `requestedTenant` → 403 (does NOT fall back — an
- * authenticated-but-denied caller is not the "no console session" case).
- * `role` is the caller's resolved membership role for routes to gate
- * mutations against `MANAGE_ROLES`.
- */
-export async function resolveConsoleAdminSession(
-  context: APIContext,
-  requestedTenant: string | null,
-): Promise<AdminAuthResult> {
-  const session = await readViewerSession(context);
-  if (!session) return { ok: false, status: 401, message: "not signed in" };
-
-  const tenantId = (requestedTenant ?? "").trim();
-  const staff = { selection: session.staffSelection, nowSeconds: Math.floor(Date.now() / 1000) };
-  if (!viewerCanAccess(session.tenants, tenantId, staff)) {
-    return {
-      ok: false,
-      status: 403,
-      message: "not authorized to manage apps for this tenant",
-    };
-  }
-  const role = membershipFor(session.tenants, tenantId, staff)?.role ?? "developer";
-  return { ok: true, tenantId, actor: await actorFromEmail(session.email), role };
-}
-
-/**
- * The single entry point admin routes call: try the signed-in console
- * viewer's session first, and only fall back to the host-bound/Bearer path
- * (`resolveAdminSession`) when there is no console session at all (401) — see
- * {@link resolveConsoleAdminSession}'s doc for why a denied console session
- * (403) does not fall through.
- */
-export async function resolveOperatorSession(
-  context: APIContext,
-  requestedTenant: string | null,
-): Promise<AdminAuthResult> {
-  const consoleAuth = await resolveConsoleAdminSession(context, requestedTenant);
-  if (consoleAuth.ok || consoleAuth.status !== 401) return consoleAuth;
-  return resolveAdminSession(context);
-}

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

@@ -1,91 +0,0 @@
-/**
- * The scoped-API authorization boundary — every
- * `/api/apps/v1/*` route calls `authorizeAppRequest` FIRST. Verifies the
- * app-gateway bearer JWT (`AppTokenVerifier`), resolves the calling
- * install from the registry, and enforces the single scope the route
- * requires per `docs/private-apps/contract/openapi.yaml`'s `x-requiredScope`.
- *
- * Tenant is ALWAYS the host-resolved `context.locals.tenant.appDomain` —
- * never a header or query param — the same binding `tokenIssuer.ts` and
- * `oauth/token.ts` use, so a token can't be replayed against a different
- * tenant than the one it was minted for.
- *
- * Fail-closed throughout: an unconfigured signing key, a missing/invalid/
- * expired token, and an install that's gone missing/cross-tenant/suspended/
- * uninstalled are ALL reported identically as the generic 401 the contract's
- * `Unauthorized` response documents (no detail that would let a caller
- * distinguish "wrong tenant" from "suspended" from "never existed" — the
- * same no-oracle discipline `registryService.ts`'s `mustFindRow` and
- * `tokenIssuer.ts`'s `invalid_client` already keep).
- */
-import type { APIContext } from "astro";
-import { getAppTokenVerifier, type AppTokenClaims } from "./tokenVerifier.js";
-import { getRegistryService } from "./adminService.js";
-import type { AppInstall } from "./registryService.js";
-import { json } from "./apiRoute.js";
-
-export interface AuthorizedAppRequest {
-  ok: true;
-  claims: AppTokenClaims;
-  install: AppInstall;
-}
-
-export type AuthorizeAppResult = AuthorizedAppRequest | { ok: false; response: Response };
-
-/** Generic, no-detail 401 — see the fail-closed note above. */
-function unauthorized(): Response {
-  return json({ error: "Unauthorized", code: "invalid_token" }, 401);
-}
-
-/**
- * Authorize one `/api/apps/v1/*` request. Pass the single scope id the route
- * requires (per the contract's `x-requiredScope`), or `null` for the
- * metadata endpoints that only require a valid token.
- */
-export async function authorizeAppRequest(
-  context: APIContext,
-  requiredScope: string | null,
-): Promise<AuthorizeAppResult> {
-  const tenant = context.locals.tenant.appDomain;
-
-  const verifier = await getAppTokenVerifier(tenant);
-  if (!verifier) {
-    return { ok: false, response: json({ error: "app gateway not configured", code: "unconfigured" }, 503) };
-  }
-
-  const authHeader = context.request.headers.get("authorization");
-  const token = authHeader?.startsWith("Bearer ") ? authHeader.slice("Bearer ".length).trim() : "";
-  if (!token) {
-    return { ok: false, response: unauthorized() };
-  }
-
-  let claims: AppTokenClaims;
-  try {
-    claims = await verifier.verify(token);
-  } catch {
-    return { ok: false, response: unauthorized() };
-  }
-
-  const registry = await getRegistryService();
-  if (registry instanceof Response) return { ok: false, response: registry };
-
-  const install = await registry.get(claims.sub);
-  if (!install || install.tenantId !== tenant || install.status !== "active") {
-    return { ok: false, response: unauthorized() };
-  }
-
-  // Enforce the scope against BOTH the live install grant and the token claims.
-  // install.scopes is the authoritative, real-time grant — so an operator
-  // narrowing scopes via update() takes effect immediately (not only after the
-  // ~300s token TTL), matching how install *status* is already live-checked
-  // above. Requiring it in the token too keeps a token from ever exceeding the
-  // grant it was minted with. Fail-closed: absent from either → denied.
-  if (
-    requiredScope &&
-    !(install.scopes.includes(requiredScope) && claims.scopes.includes(requiredScope))
-  ) {
-    return { ok: false, response: json({ error: "scope_denied", code: "scope_denied" }, 403) };
-  }
-
-  return { ok: true, claims, install };
-}

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

@@ -1,35 +0,0 @@
-/**
- * Response helpers shared by every `/api/apps/v1/*` route — a no-store JSON
- * responder (mirrors `../grants/route.ts` /
- * `./adminService.ts`'s pattern) plus the `tot-request-id` / `traceparent`
- * response headers `docs/private-apps/contract/openapi.yaml` documents on
- * every operation.
- */
-import type { APIContext } from "astro";
-
-/** No-store JSON response — scoped-app API bodies must never be edge/browser-cached. */
-export function json(body: unknown, status = 200): Response {
-  return new Response(JSON.stringify(body), {
-    status,
-    headers: { "content-type": "application/json", "cache-control": "no-store" },
-  });
-}
-
-/** The W3C Trace Context shape the contract's `Traceparent` parameter/header pins. */
-const TRACEPARENT_RE = /^[0-9a-f]{2}-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}$/;
-
-/**
- * Stamp a fresh `tot-request-id` on every response, and echo `traceparent`
- * back ONLY when the request sent a well-formed one — never fabricate a
- * trace context the caller didn't start. Callers apply this to BOTH success
- * and error responses (including `authorizeAppRequest`'s), so every response
- * off a `/api/apps/v1/*` route carries a request id.
- */
-export function withRequestId(res: Response, context: Pick<APIContext, "request">): Response {
-  res.headers.set("tot-request-id", crypto.randomUUID());
-  const traceparent = context.request.headers.get("traceparent");
-  if (traceparent && TRACEPARENT_RE.test(traceparent)) {
-    res.headers.set("traceparent", traceparent);
-  }
-  return res;
-}

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

@@ -1,39 +0,0 @@
-/**
- * Maps the internal `CatalogProduct` read model to the scoped-API contract's
- * `Product` shape (`docs/private-apps/contract/openapi.yaml`, schema
- * `Product` — `additionalProperties: false`). Drops every internal field
- * the contract doesn't declare (variants, images, metafields, source, …) so
- * an app only ever sees the minimized public catalog surface.
- */
-import type { CatalogProduct } from "@tot/public-runtime";
-
-export interface ContractProduct {
-  id: string;
-  handle: string;
-  title: string;
-  status: "active" | "draft" | "archived";
-  vendor?: string;
-  productType?: string;
-  tags?: string[];
-  priceRange: { min: number; max: number; currency: string };
-  updatedAt?: string;
-}
-
-/** Project one `CatalogProduct` into the contract's `Product` — nothing else survives. */
-export function toContractProduct(p: CatalogProduct): ContractProduct {
-  return {
-    id: p.id,
-    handle: p.handle,
-    title: p.title,
-    status: p.status,
-    vendor: p.vendor,
-    productType: p.product_type,
-    tags: p.tags,
-    priceRange: {
-      min: p.price_range.min,
-      max: p.price_range.max,
-      currency: p.price_range.currency,
-    },
-    updatedAt: p.updated_at,
-  };
-}