@k2b/cloud 0.42.0 → 0.44.0

package/src/api/resource-links.ts

@@ -1,6 +1,10 @@
 import { z } from "zod";
-import { getCapability } from "../_internal/registry";
+import { canonicalRoute } from "../_internal/app-path";
+import { readBoundedJson } from "../_internal/bounded-json";
+import { resolveCapabilityManifestPresentation } from "../_internal/capabilities";
+import { getCapability, listApps, listCapabilities } from "../_internal/registry";
 import {
+  CAPABILITY_MAX_RESULT_BYTES,
   CapabilitySemanticLinkSchema,
   type CloudResourceRef,
   CloudResourceRefSchema,
@@ -8,20 +12,26 @@ import {
   cloudResourceRefAppId,
   resolveCapabilityResourceReader,
 } from "../contracts/capabilities";
+import { parseCloudResourceUrl } from "../contracts/resource-clipboard";
+import { localCloudResourceUrl, matchCloudResourcePage } from "../contracts/resource-pages";
+import type { ResolvedCloudResourceUrl } from "../contracts/resource-resolution";
 import type { RequestAuthority } from "../server";
+import * as settings from "../services/settings";
+import { publicCloudOrigin } from "../shared/app-url";
 import { dispatchCapability } from "./capabilities";
 
-export const resolveCloudResourceHref = async (
+const readCloudResourceLink = async (
   params: { ref: CloudResourceRef; request: Request; authority: RequestAuthority; locale?: string },
   dependencies: { getCapability?: typeof getCapability; dispatch?: typeof dispatchCapability } = {},
-): Promise<string | null> => {
+): Promise<ResolvedCloudResourceUrl | null> => {
   const parsed = CloudResourceRefSchema.safeParse(params.ref);
   if (!parsed.success) return null;
   const ref = parsed.data;
   const appId = cloudResourceRefAppId(ref);
   const app = await (dependencies.getCapability ?? getCapability)(appId);
   if (!app || app.appId !== appId) return null;
-  const reader = resolveCapabilityResourceReader(app.manifest, ref);
+  const manifest = params.locale ? resolveCapabilityManifestPresentation(app.manifest, app.presentation, params.locale) : app.manifest;
+  const reader = resolveCapabilityResourceReader(manifest, ref);
   if (!reader) return null;
   const response = await (dependencies.dispatch ?? dispatchCapability)({
     request: params.request,
@@ -34,10 +44,77 @@ export const resolveCloudResourceHref = async (
     input: { id: ref.id },
   });
   if (!response.ok) return null;
-  const result = capabilityResultSchema(z.unknown(), { consumer: true }).safeParse(await response.json());
+  const body = await readBoundedJson(response, CAPABILITY_MAX_RESULT_BYTES, params.request.signal);
+  if (!body.ok) return null;
+  const result = capabilityResultSchema(z.unknown(), { consumer: true }).safeParse(body.data);
   if (!result.success) return null;
   const link = CapabilitySemanticLinkSchema.safeParse(
     result.data.links?.find((link) => link.rel === "open") ?? result.data.links?.find((link) => link.rel === "edit"),
   );
-  return link.success ? link.data.href : null;
+  if (!link.success) return null;
+  const type = manifest.types.find((type) => `${appId}.${type.localId}` === ref.type);
+  if (!type) return null;
+  const reference = result.data.refs?.find((entry) => entry.type === ref.type && entry.id === ref.id);
+  const icon = reference?.icon ?? type.icon;
+  return { ref, title: reference?.title ?? type.title, ...(icon ? { icon } : {}), href: link.data.href };
+};
+
+/** Resolve a known reference through its authorized reader. */
+export const resolveCloudResourceHref = async (
+  params: Parameters<typeof readCloudResourceLink>[0],
+  dependencies: Parameters<typeof readCloudResourceLink>[1] = {},
+): Promise<string | null> => (await readCloudResourceLink(params, dependencies))?.href ?? null;
+
+/** Recognize one local URL, then read the resource under the caller's authority. All failures are opaque. */
+export const resolveCloudResourceUrl = async (
+  params: { url: string; request: Request; authority: RequestAuthority; locale?: string },
+  dependencies: Parameters<typeof readCloudResourceLink>[1] & {
+    appUrl?: () => Promise<string | null | undefined>;
+    listApps?: typeof listApps;
+    listCapabilities?: typeof listCapabilities;
+  } = {},
+): Promise<ResolvedCloudResourceUrl | null> => {
+  try {
+    const configured = await (dependencies.appUrl ?? (() => settings.get<string>("app.url")))();
+    const origin = configured ? publicCloudOrigin(configured) : null;
+    const url = localCloudResourceUrl(params.url, origin);
+    if (!url) return null;
+    // Permalinks share the existing parser; fragments and incidental query parameters do not change identity.
+    let ref = parseCloudResourceUrl(`${url.pathname}`, origin ?? url.origin);
+    if (!ref && !url.pathname.startsWith("/open/")) {
+      const apps = await (dependencies.listApps ?? listApps)();
+      // Honor a more specific live owner, including apps that publish no resource pages.
+      // A root or ancestor route must not capture their links. Equal prefix claims fail closed.
+      const pathname = canonicalRoute(url.pathname);
+      const namespace = pathname.split("/");
+      const routes = apps.flatMap((app) =>
+        app.routes.flatMap((route) => {
+          const prefix = canonicalRoute(route);
+          if (!prefix.startsWith("/") || /[%\\?#\s]/.test(prefix) || prefix.split("/").some((part) => part === "." || part === ".."))
+            return [];
+          if (namespace[1] === "app" && namespace[2] && namespace[2] !== app.id) return [];
+          return prefix === "/" || pathname === prefix || pathname.startsWith(`${prefix}/`)
+            ? [{ appId: app.id, length: prefix.length }]
+            : [];
+        }),
+      );
+      const longest = routes.reduce((length, route) => Math.max(length, route.length), 0);
+      const owners = new Set(routes.filter((route) => route.length === longest).map((route) => route.appId));
+      if (owners.size !== 1) return null;
+      const catalog = await (dependencies.listCapabilities ?? listCapabilities)(apps);
+      const pages = catalog.flatMap((entry) => {
+        const app = apps.find((app) => app.id === entry.appId);
+        if (!app || !owners.has(app.id) || entry.manifest.appId !== app.id) return [];
+        return (entry.manifest.resourcePages ?? []).flatMap((page) => {
+          const ref = { type: `${app.id}.${page.type}`, id: "candidate" };
+          return resolveCapabilityResourceReader(entry.manifest, ref) ? [{ type: ref.type, path: page.path, prefixes: app.routes }] : [];
+        });
+      });
+      ref = matchCloudResourcePage(`${url.pathname}${url.search}`, pages);
+    }
+    return ref ? await readCloudResourceLink({ ...params, ref }, dependencies) : null;
+  } catch {
+    // Never include a pasted URL, resource existence, or provider error in this result.
+    return null;
+  }
 };

package/src/api/resource-resolve.ts

@@ -0,0 +1,50 @@
+import { Hono } from "hono";
+import { describeRoute, resolver } from "hono-openapi";
+import { z } from "zod";
+import { readBoundedJson } from "../_internal/bounded-json";
+import { withCapabilityRequestTimeout } from "../_internal/capability-timeout";
+import { RESOURCE_URL_MAX_LENGTH } from "../contracts/resource-pages";
+import { ResolvedCloudResourceUrlSchema } from "../contracts/resource-resolution";
+import { type AuthContext, auth, getLocale } from "../server";
+import { resolveCloudResourceUrl } from "./resource-links";
+
+const Input = z.object({ url: z.string().min(1).max(RESOURCE_URL_MAX_LENGTH) }).strict();
+const NotFound = { error: "Resource not found" } as const;
+
+export const createResourceResolveRoutes = (resolve = resolveCloudResourceUrl) =>
+  new Hono<AuthContext>().post(
+    "/resolve",
+    auth.readOnly,
+    auth.requireRole("authenticated"),
+    describeRoute({
+      tags: ["Resources"],
+      summary: "Resolve a Cloud URL through its authorized resource reader",
+      requestBody: { required: true, content: { "application/json": { schema: resolver(Input) } } },
+      responses: {
+        200: { description: "Readable resource", content: { "application/json": { schema: resolver(ResolvedCloudResourceUrlSchema) } } },
+        404: {
+          description: "Resource not found",
+          content: { "application/json": { schema: resolver(z.object({ error: z.literal(NotFound.error) })) } },
+        },
+      },
+    }),
+    async (c) => {
+      try {
+        // JSON may encode each UTF-16 unit as six bytes. Bound the envelope before parsing.
+        const body = await readBoundedJson(c.req.raw, RESOURCE_URL_MAX_LENGTH * 6 + 100, c.req.raw.signal);
+        const input = body.ok ? Input.safeParse(body.data) : null;
+        if (!input?.success) return c.json(NotFound, 404);
+        const result = await withCapabilityRequestTimeout(c, "query", () =>
+          resolve({
+            url: input.data.url,
+            request: c.req.raw,
+            authority: auth.getAuthority(c),
+            locale: getLocale(c),
+          }),
+        );
+        return result ? c.json(result, 200) : c.json(NotFound, 404);
+      } catch {
+        return c.json(NotFound, 404);
+      }
+    },
+  );

package/src/api/search/schemas.ts

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { CloudResourceRefSchema } from "../../contracts";
-import { CapabilitySearchTagManifestSchema } from "../../contracts/capabilities";
+import { CapabilitySearchTagManifestSchema, CloudResourceReferenceSchema } from "../../contracts/capabilities";
 
 const TAG_PATTERN = /^[^\s#]+$/;
 const SEARCH_BASE_URL = "https://cloud.invalid";
@@ -69,6 +69,8 @@ export const SearchItemSchema = z.object({
   ref: CloudResourceRefSchema,
   title: z.string(),
   href: SameOriginPathSchema,
+  context: CloudResourceReferenceSchema.shape.context,
+  status: CloudResourceReferenceSchema.shape.status,
   preview: z.string().optional(),
   icon: z.string().optional(),
   priority: z.number().int().min(0).max(9).optional(),

package/src/api/search.ts

@@ -139,9 +139,14 @@ export const createSearchRoutes = (dependencies: SearchRouteDependencies = {}) =
       const stream = acceptsStream(c.req.header("accept"));
       const requestId = normalizeInvocationRequestId(c.req.header("x-request-id"));
       const invocationAuthority = invocationAuthorityFromRequest(auth.getAuthority(c));
+      // One request-wide budget covers resource access, signing and provider I/O.
+      const providerDeadline = AbortSignal.timeout(PROVIDER_TIMEOUT_MS);
+      // A client that stops reading a stream ends the search too.
+      const streamCancelled = new AbortController();
+      const fanoutSignal = AbortSignal.any([c.req.raw.signal, providerDeadline, streamCancelled.signal]);
       let entries: CapabilityRegistryEntry[];
       try {
-        entries = await discoverableAppEntries(appAccessAuthority(c), await registry(), dependencies.listApps);
+        entries = await discoverableAppEntries(appAccessAuthority(c), await registry(), dependencies.listApps, { signal: fanoutSignal });
       } catch (error) {
         log.warn("Search capability registry unavailable", { error: error instanceof Error ? error.message : String(error) });
         return c.json(
@@ -227,11 +232,6 @@ export const createSearchRoutes = (dependencies: SearchRouteDependencies = {}) =
       // at GLOBAL_RESULT_LIMIT so a single app can saturate the response
       // but no more.
       const effectiveProviderLimit = active.length === 1 ? Math.min(GLOBAL_RESULT_LIMIT, query.provider_limit * 3) : query.provider_limit;
-      // The same request-wide budget covers signing and provider I/O.
-      const providerDeadline = AbortSignal.timeout(PROVIDER_TIMEOUT_MS);
-      // A client that stops reading a stream, such as the browser on the next keystroke, ends the search too.
-      const streamCancelled = new AbortController();
-      const fanoutSignal = AbortSignal.any([c.req.raw.signal, providerDeadline, streamCancelled.signal]);
       // Guard the whole issuance batch once, then reuse the prepared signer for
       // every target. This is one Postgres check per outer search request, not
       // one check per provider.
@@ -258,7 +258,7 @@ export const createSearchRoutes = (dependencies: SearchRouteDependencies = {}) =
                           signer,
                           issuer: signer.issuer,
                         },
-                        { db, groupsAdmin: signer.groupsAdmin },
+                        { db, groupsAdmin: signer.groupsAdmin, signal: fanoutSignal },
                       ),
                     fanoutSignal,
                   ),
@@ -353,6 +353,8 @@ export const createSearchRoutes = (dependencies: SearchRouteDependencies = {}) =
             ref: view.ref,
             title: view.title,
             href: open.href,
+            context: view.context,
+            status: view.status,
             preview: view.preview,
             icon: view.icon,
             priority: view.priority,

package/src/api/widgets.ts

@@ -353,6 +353,7 @@ export const createWidgetRoutes = (dependencies: WidgetRouteDependencies = {}) =
       })
       .post(
         "/widgets/v1",
+        auth.readOnly,
         bodyLimit({ maxSize: WIDGET_REQUEST_MAX_BYTES, onError: (c) => c.json({ message: "Widget request is too large" }, 400) }),
         async (c) => {
           let raw: unknown;

package/src/app-pwa/authority.ts

@@ -0,0 +1,75 @@
+import type { SQL, TransactionSQL } from "bun";
+import { accountCategory } from "../contracts/account-categories";
+import { decodeAccountCategoryEnabled } from "../services/account-category-policy";
+import { type AppPwaWebSignIn, pwaFail } from "./contracts";
+
+type User = {
+  auth_epoch: string;
+  provider: "local" | "ipa";
+  profile: "guest" | "user";
+  account_expires: Date | null;
+};
+type Family = {
+  auth_epoch: string;
+  expires_at: Date;
+  revoked_at: Date | null;
+  pwa_device_id: string | null;
+  signing_kid: string;
+  legal_pending: boolean;
+};
+
+export const databaseClock = async (tx: TransactionSQL): Promise<Date> => {
+  const [row] = await tx<{ time: Date }[]>`SELECT clock_timestamp() AS time`;
+  if (!row) return pwaFail("UNAVAILABLE", 503);
+  return row.time;
+};
+
+/** Supported on PostgreSQL 15–17. Keep the query cancellable through execution. */
+export const boundTransaction = (tx: SQL, remainingMilliseconds: number) => {
+  if (!Number.isSafeInteger(remainingMilliseconds) || remainingMilliseconds < 1) return pwaFail("UNAVAILABLE", 503);
+  const timeout = `${remainingMilliseconds}ms`;
+  return tx`SELECT set_config('statement_timeout', ${timeout}, true), set_config('lock_timeout', ${timeout}, true),
+    set_config('idle_in_transaction_session_timeout', ${timeout}, true)`;
+};
+
+/**
+ * Core order: user -> session family -> signing key. All locks survive domain writes and commit.
+ * Logout updates this family; epoch invalidation/deactivation updates this user; key revoke updates this key.
+ * Never replace this with a cached authentication callback or a preflight HTTP request.
+ */
+export const lockWebAuthority = async (tx: TransactionSQL, signIn: AppPwaWebSignIn) => {
+  const [user] = await tx<User[]>`SELECT auth_epoch, provider, profile, account_expires
+    FROM auth.users WHERE id = ${signIn.userId}::uuid FOR NO KEY UPDATE`;
+  if (!user) return pwaFail("WEB_SESSION_REQUIRED", 401);
+  const [family] = await tx<Family[]>`SELECT auth_epoch, expires_at, revoked_at, pwa_device_id, signing_kid, legal_pending
+    FROM auth.session_families WHERE sid = ${signIn.sid}::uuid AND user_id = ${signIn.userId}::uuid FOR UPDATE`;
+  if (!family) return pwaFail("WEB_SESSION_REQUIRED", 401);
+  const [key] = await tx<{ state: string }[]>`SELECT state FROM auth.signing_keys
+    WHERE kid = ${family.signing_kid} FOR SHARE`;
+  const categoryKey = `user.category.${accountCategory(user)}.enabled`;
+  // A row lock cannot serialize an absent default with the first policy INSERT.
+  // Settings has no shared category writer lock; ordinary DML conflicts with SHARE.
+  await tx`LOCK TABLE settings.entries IN SHARE MODE`;
+  const [category] = await tx<{ value: string }[]>`SELECT value FROM settings.entries WHERE key = ${categoryKey} FOR SHARE`;
+  const legal =
+    !family.legal_pending || (await tx`SELECT 1 FROM auth.legal_acceptances WHERE user_id = ${signIn.userId}::uuid LIMIT 1`).length > 0;
+  const categoryEnabled = await decodeAccountCategoryEnabled(category?.value);
+  const check = (time: Date) => {
+    if (
+      family.revoked_at ||
+      family.pwa_device_id ||
+      !key ||
+      key.state === "revoked" ||
+      String(family.auth_epoch) !== String(user.auth_epoch) ||
+      family.expires_at <= time ||
+      !legal ||
+      (user.account_expires && user.account_expires <= time) ||
+      !categoryEnabled
+    ) {
+      return pwaFail("WEB_SESSION_REQUIRED", 401);
+    }
+    return new Date(Math.min(family.expires_at.getTime(), user.account_expires?.getTime() ?? Infinity));
+  };
+  await check(await databaseClock(tx));
+  return { user, family, check };
+};

package/src/app-pwa/contracts.ts

@@ -0,0 +1,177 @@
+import type { SQL, TransactionSQL } from "bun";
+import { z } from "zod";
+import type { AppInstallable } from "../contracts/installable";
+import type { PermissionLevel } from "../server/services/access";
+
+export const APP_PWA_LIMITS = {
+  qrSeconds: 120,
+  deviceSeconds: 12 * 60 * 60,
+  visitIdleSeconds: 15 * 60,
+  visitSeconds: 60 * 60,
+} as const;
+
+export const AppPwaId = z.uuid();
+export const AppPwaSecret = z.string().regex(/^[A-Za-z0-9_-]{43}$/);
+export const AppPwaClaim = z.strictObject({ qr: z.string() });
+export const AppPwaAttempt = z.strictObject({ attemptId: AppPwaId, input: z.unknown() });
+
+export type AppPwaDeviceActor = {
+  kind: "device";
+  appId: string;
+  deviceId: string;
+  ownerUserId: string;
+};
+export type AppPwaVisitActor = Omit<AppPwaDeviceActor, "kind"> & {
+  kind: "visit";
+  visitId: string;
+  /** Validated against the application's subject schema. Domain interpretation belongs to the app. */
+  subject: unknown;
+};
+export type AppPwaActor = AppPwaDeviceActor | AppPwaVisitActor;
+export type AppPwaDeviceView = {
+  id: string;
+  name: string;
+  state: "pending" | "active" | "expired" | "revoked";
+  expiresAt: string | null;
+};
+export type AppPwaVisitView = {
+  id: string;
+  state: "pending" | "active" | "expired" | "ended" | "revoked";
+  expiresAt: string | null;
+  idleExpiresAt: string | null;
+};
+export type AppPwaWebSignIn = { userId: string; sid: string };
+export type AppPwaStaffAction = "issue-device" | "list-devices" | "device-status" | "revoke-device" | "issue-visit" | "revoke-visit";
+
+export type AppPwaVisitContext = {
+  actor: AppPwaVisitActor;
+  tx: TransactionSQL;
+  signal: AbortSignal;
+};
+export type AppPwaCommandContext = AppPwaVisitContext & {
+  /** Complete the visit atomically with the domain write and its attempt result. */
+  endVisit(): void;
+};
+export type AppPwaDeviceContext = {
+  actor: AppPwaDeviceActor;
+  tx: TransactionSQL;
+  signal: AbortSignal;
+};
+
+export type AppPwaQuery = {
+  run(context: AppPwaVisitContext, input: unknown): Promise<unknown>;
+};
+export type AppPwaCommand = {
+  parse(input: unknown): unknown;
+  run(context: AppPwaCommandContext, input: unknown): Promise<unknown>;
+};
+export type AppPwaDeviceOperation = {
+  permission: Exclude<PermissionLevel, "none">;
+  run(context: AppPwaDeviceContext, input: unknown): Promise<unknown>;
+  /** Lock the app-owned resource/junction rows that determine these grant IDs. Called again before commit. */
+  accessIds(context: AppPwaDeviceContext, input: unknown): Promise<string[]>;
+};
+
+const parse = <T>(schema: z.ZodType<T>, value: unknown): T => {
+  const result = schema.safeParse(value);
+  if (!result.success) throw new AppPwaError("INVALID_INPUT", 400);
+  return result.data;
+};
+
+/** A query never renews a visit. Use the supplied transaction even for domain reads. */
+export const appPwaQuery = <I, O>(definition: {
+  input: z.ZodType<I>;
+  output: z.ZodType<O>;
+  handler(context: AppPwaVisitContext, input: I): Promise<O>;
+}): AppPwaQuery => ({
+  run: async (context, input) => parse(definition.output, await definition.handler(context, parse(definition.input, input))),
+});
+
+/** Only a newly committed successful command renews idle time. Live retries return the stored result; terminal retries return status only. */
+export const appPwaCommand = <I, O>(definition: {
+  input: z.ZodType<I>;
+  output: z.ZodType<O>;
+  handler(context: AppPwaCommandContext, input: I): Promise<O>;
+}): AppPwaCommand => ({
+  parse: (input) => parse(definition.input, input),
+  run: async (context, input) => parse(definition.output, await definition.handler(context, parse(definition.input, input))),
+});
+
+/**
+ * A device-only local service adapter. It receives device provenance, never owner credentials.
+ * The platform intersects its explicit ceiling with current resource grants before calling it.
+ * Cross-app credential exchange is deliberately outside this adapter's contract.
+ */
+export const appPwaDeviceOperation = <I, O>(definition: {
+  input: z.ZodType<I>;
+  output: z.ZodType<O>;
+  permission: Exclude<PermissionLevel, "none">;
+  accessIds(context: AppPwaDeviceContext, input: I): Promise<string[]>;
+  handler(context: AppPwaDeviceContext, input: I): Promise<O>;
+}): AppPwaDeviceOperation => ({
+  permission: definition.permission,
+  accessIds: (context, input) => definition.accessIds(context, parse(definition.input, input)),
+  run: async (context, input) => parse(definition.output, await definition.handler(context, parse(definition.input, input))),
+});
+
+export type AppPwaCoreQuery = "address.autocomplete";
+
+export type AppPwaOptions = {
+  app: { id: string; installable: Pick<AppInstallable, "path"> };
+  /** Authoritative configured public origin, never a Host/Forwarded/request header. HTTPS is mandatory. */
+  publicOrigin: string;
+  schema: string;
+  db?: SQL;
+  /** Positive safe integer seconds; capped at 12 hours, then bounded by browser and initiating family. */
+  deviceTtlSeconds?: number;
+  subject: z.ZodType;
+  /** Explicit application budgets, covering transport, stored results, and staff pagination. */
+  budgets: { requestBytes: number; responseBytes: number; listPageSize: number; maxAccessIds: number };
+  /** Mandatory application authorization, repeated under the current web authority locks for every staff action. */
+  authorizeStaff(action: AppPwaStaffAction, signIn: AppPwaWebSignIn, tx: TransactionSQL): Promise<boolean>;
+  /** Authorize exposing this validated domain subject to a customer; lock its authority using tx.
+   * Called before issuance and again before commit, including issuance retries. */
+  authorizeVisit(signIn: AppPwaWebSignIn, subject: unknown, tx: TransactionSQL): Promise<boolean>;
+  queries?: Readonly<Record<string, AppPwaQuery>>;
+  /** Read-only platform queries available through the closed guest Core-query route. Empty by default. */
+  coreQueries?: readonly AppPwaCoreQuery[];
+  commands?: Readonly<Record<string, AppPwaCommand>>;
+  deviceOperations?: Readonly<Record<string, AppPwaDeviceOperation>>;
+  /** Missing operation declarations deny access; operation registration alone grants nothing. */
+  devicePermissions?: Readonly<Record<string, Exclude<PermissionLevel, "none">>>;
+};
+
+export type AppPwaErrorCode =
+  | "INVALID_INPUT"
+  | "INVALID_QR"
+  | "ORIGIN_REQUIRED"
+  | "JSON_REQUIRED"
+  | "CSRF_REQUIRED"
+  | "BROWSER_REQUIRED"
+  | "DUPLICATE_COOKIE"
+  | "WEB_SESSION_REQUIRED"
+  | "FORBIDDEN"
+  | "NOT_FOUND"
+  | "EXPIRED"
+  | "REVOKED"
+  | "ALREADY_CLAIMED"
+  | "ACTIVE_VISIT"
+  | "ATTEMPT_CONFLICT"
+  | "TOO_LARGE"
+  | "RATE_LIMITED"
+  | "UNAVAILABLE"
+  | `APP_${string}`;
+
+export class AppPwaError extends Error {
+  constructor(
+    readonly code: AppPwaErrorCode,
+    readonly status: 400 | 401 | 403 | 404 | 409 | 410 | 413 | 415 | 429 | 503,
+  ) {
+    super(code);
+  }
+}
+
+export const pwaFail = (code: AppPwaErrorCode, status: AppPwaError["status"]): never => {
+  throw new AppPwaError(code, status);
+};
+export const parseAppPwaInput = parse;

package/src/app-pwa/core-query-error.ts

@@ -0,0 +1,20 @@
+import type { GeoError } from "../services/geo/errors";
+
+/** Guest-safe errors from the allowlisted platform adapter, never from application handlers. */
+export class AppPwaCoreQueryError extends Error {
+  readonly code: GeoError["code"];
+  readonly status: GeoError["status"];
+  readonly details?: { scope: "person" | "cloud"; resetsAt: string };
+  constructor(error: GeoError) {
+    super(error.code);
+    this.code = error.code;
+    this.status = error.status;
+    if (
+      error.code === "GEO_BUDGET_EXHAUSTED" &&
+      (error.details.scope === "person" || error.details.scope === "cloud") &&
+      typeof error.details.resetsAt === "string"
+    ) {
+      this.details = { scope: error.details.scope, resetsAt: error.details.resetsAt };
+    }
+  }
+}

package/src/app-pwa/index.ts

@@ -0,0 +1,23 @@
+export {
+  APP_PWA_LIMITS,
+  type AppPwaActor,
+  type AppPwaCommandContext,
+  type AppPwaCoreQuery,
+  type AppPwaDeviceActor,
+  type AppPwaDeviceContext,
+  type AppPwaDeviceView,
+  AppPwaError,
+  type AppPwaErrorCode,
+  type AppPwaOptions,
+  type AppPwaStaffAction,
+  type AppPwaVisitActor,
+  type AppPwaVisitContext,
+  type AppPwaVisitView,
+  type AppPwaWebSignIn,
+  appPwaCommand,
+  appPwaDeviceOperation,
+  appPwaQuery,
+} from "./contracts";
+export { setupAppPwa } from "./schema";
+export { type AppPwaService, createAppPwaService } from "./service";
+export { createAppPwa, createAppPwaRouter } from "./transport";

package/src/app-pwa/protocol.ts

@@ -0,0 +1,27 @@
+/** Browser-safe QR protocol. Parsing never navigates or fetches the scanned URL. */
+export type AppPwaQr = { kind: "device" | "visit"; secret: string };
+const SECRET = /^[A-Za-z0-9_-]{43}$/;
+
+export const appPwaQr = (origin: string, path: string, value: AppPwaQr): string => {
+  if (!SECRET.test(value.secret)) throw new Error("Invalid App-PWA secret");
+  return `${origin}${path}#cloud-app-pwa:${value.kind}:${value.secret}`;
+};
+
+/** Exact serialized comparison rejects normalization, escapes, alternate ports, userinfo, query, and whitespace. */
+export const parseAppPwaQr = (text: string, origin: string, path: string): AppPwaQr | null => {
+  const prefix = `${origin}${path}#cloud-app-pwa:`;
+  if (text.length !== prefix.length + 7 + 43 && text.length !== prefix.length + 6 + 43) return null;
+  if (!text.startsWith(prefix)) return null;
+  const value = text.slice(prefix.length);
+  const kind = value.startsWith("device:") ? "device" : value.startsWith("visit:") ? "visit" : null;
+  if (!kind) return null;
+  const secret = value.slice(kind.length + 1);
+  return SECRET.test(secret) && text === appPwaQr(origin, path, { kind, secret }) ? { kind, secret } : null;
+};
+
+/** Drop a directly opened fragment before asynchronous work; the supported input remains the scanner. */
+export const clearAppPwaFragment = (): void => {
+  if (typeof window !== "undefined" && window.location.hash) {
+    window.history.replaceState(window.history.state, "", window.location.pathname + window.location.search);
+  }
+};

package/src/app-pwa/schema.ts

@@ -0,0 +1,59 @@
+import type { SQL } from "bun";
+import { ensureSchema } from "../services/postgres";
+import { withAppPwaTransaction } from "./transaction";
+
+export const appPwaSchemaName = (name: string): string => {
+  if (!/^[a-z_][a-z0-9_]{0,62}$/.test(name)) throw new Error("App-PWA schema must be a plain lowercase Postgres identifier");
+  return name;
+};
+
+/** Must finish successfully in application setup before listening. No best-effort migration or memory authority. */
+export const setupAppPwa = async (db: SQL, schemaName: string): Promise<void> => {
+  const schema = appPwaSchemaName(schemaName);
+  await withAppPwaTransaction(db, undefined, async (tx) => {
+    await tx`SELECT pg_advisory_xact_lock(hashtextextended(${`cloud:app-pwa:${schema}`}, 0))`;
+    await ensureSchema(tx, schema);
+    await tx
+      .unsafe(`CREATE TABLE IF NOT EXISTS ${schema}._cloud_pwa_browsers (
+      app_id text NOT NULL, credential_hash text NOT NULL, expires_at timestamptz NOT NULL,
+      device_id uuid, PRIMARY KEY (app_id, credential_hash))`)
+      .simple();
+    await tx
+      .unsafe(`CREATE TABLE IF NOT EXISTS ${schema}._cloud_pwa_devices (
+      app_id text NOT NULL, id uuid NOT NULL, request_id uuid NOT NULL, input_digest text NOT NULL,
+      owner_user_id uuid NOT NULL, initiator_sid uuid NOT NULL, auth_epoch bigint NOT NULL,
+      name text NOT NULL, secret_hash text NOT NULL, browser_hash text,
+      state text NOT NULL CHECK (state IN ('pending', 'active', 'revoked')),
+      issued_at timestamptz NOT NULL, qr_expires_at timestamptz NOT NULL,
+      activated_at timestamptz, expires_at timestamptz, active_visit_id uuid,
+      PRIMARY KEY (app_id, id), UNIQUE (app_id, owner_user_id, initiator_sid, request_id))`)
+      .simple();
+    await tx
+      .unsafe(`CREATE UNIQUE INDEX IF NOT EXISTS _cloud_pwa_device_secret ON ${schema}._cloud_pwa_devices(app_id, secret_hash)`)
+      .simple();
+    await tx
+      .unsafe(`CREATE INDEX IF NOT EXISTS _cloud_pwa_device_owner ON ${schema}._cloud_pwa_devices(app_id, owner_user_id, id)`)
+      .simple();
+    await tx
+      .unsafe(`CREATE TABLE IF NOT EXISTS ${schema}._cloud_pwa_visits (
+      app_id text NOT NULL, id uuid NOT NULL, device_id uuid NOT NULL,
+      request_id uuid NOT NULL, input_digest text NOT NULL, secret_hash text NOT NULL,
+      subject jsonb NOT NULL, browser_hash text,
+      state text NOT NULL CHECK (state IN ('pending', 'active', 'ended', 'revoked')),
+      issued_at timestamptz NOT NULL, qr_expires_at timestamptz NOT NULL,
+      activated_at timestamptz, last_used_at timestamptz, expires_at timestamptz,
+      PRIMARY KEY (app_id, id), UNIQUE (app_id, device_id, request_id),
+      FOREIGN KEY (app_id, device_id) REFERENCES ${schema}._cloud_pwa_devices(app_id, id))`)
+      .simple();
+    await tx
+      .unsafe(`CREATE UNIQUE INDEX IF NOT EXISTS _cloud_pwa_visit_secret ON ${schema}._cloud_pwa_visits(app_id, secret_hash)`)
+      .simple();
+    await tx
+      .unsafe(`CREATE TABLE IF NOT EXISTS ${schema}._cloud_pwa_attempts (
+      app_id text NOT NULL, visit_id uuid NOT NULL, attempt_id uuid NOT NULL,
+      route text NOT NULL, input_digest text NOT NULL, result jsonb NOT NULL,
+      PRIMARY KEY (app_id, visit_id, attempt_id),
+      FOREIGN KEY (app_id, visit_id) REFERENCES ${schema}._cloud_pwa_visits(app_id, id))`)
+      .simple();
+  });
+};