@frockbot/cloudflare 0.0.0 → 0.7.292

package/src/native-auth.ts

@@ -0,0 +1,1006 @@
+import {
+  isProtocolValue,
+  type AuthStartCommand,
+  type ClientHello,
+} from "@frockbot/core/protocol-schemas";
+import {
+  clientCompatibilityResponse,
+  CLIENT_HELLO_HEADER,
+  UPDATE_APP_MESSAGE,
+} from "./client-compatibility.js";
+import {
+  returnPageV1,
+  type ReturnPageBrandV1,
+} from "@frockbot/app/return-page";
+import {
+  AUTH_NO_STORE_HEADERS_V1,
+  signInFailedV1 as error,
+  signInRedirectV1 as redirect,
+} from "@frockbot/app/auth/shared";
+import type { AccountAdmissionDecisionV1 } from "@frockbot/app/admin/shared";
+import {
+  admissionRefusedResponse,
+  admissionUnavailableResponse,
+} from "./account-admission.js";
+import {
+  nativeReturnSchemeV1,
+  type AuthIdentityV1,
+  type AuthPackageIdentityV1,
+  type BrandV1,
+} from "@frockbot/core/contracts";
+import type {
+  NativeSessionOperation,
+  NativeSessionRecord,
+} from "./native-sessions.js";
+
+/**
+ * Each signed app's return page under `/native/return/`: Android's verified
+ * App Link, and the page each Apple build's browser return hands over on its
+ * own scheme. `macos-dev` and `ios-dev` are the FrockBot Dev builds, separate
+ * apps installed beside the released ones, which a deployment serves only
+ * when its profile names them.
+ */
+export type NativeReturnPlatformV1 =
+  "android" | "macos" | "macos-dev" | "ios" | "ios-dev";
+const NATIVE_RETURN_PLATFORMS: readonly NativeReturnPlatformV1[] = [
+  "android",
+  "macos",
+  "macos-dev",
+  "ios",
+  "ios-dev",
+];
+
+/**
+ * Where a signed app receives its sign-in: a path on the deployment's own
+ * origin. No deployment is named here — the origin is the one the Worker was
+ * given, so a second deployment's App Links are its own
+ * ([ADR 0028](../../../docs/adr/0028-open-deployment.md)).
+ */
+export function nativeReturnUriV1(
+  origin: string,
+  platform: NativeReturnPlatformV1,
+): string {
+  return `${new URL(origin).origin}/native/return/${platform}`;
+}
+/**
+ * Where a development build of the app receives its sign-in. A custom scheme,
+ * the brand's development one, because a plain-HTTP loopback origin can never
+ * be an App Link; only a Worker running with `ALLOW_DEVELOPMENT_AUTH` ever
+ * lists it.
+ */
+export function nativeDevelopmentReturnUriV1(
+  brand: Pick<BrandV1, "nativeScheme">,
+): string {
+  return `${nativeReturnSchemeV1(brand, "development")}://native/return/android`;
+}
+/**
+ * Which build each Apple return page hands over to, on the brand's scheme
+ * (`nativeReturnSchemeV1`). A Universal Link only reaches the app from
+ * Safari, and only on a user's own click; Chrome and Firefox never dispatch
+ * one, and Google's completion redirect is not a click — on an iPhone as on a
+ * Mac. The return page hands the same code and state to the app's scheme,
+ * which every browser can open. The code is useless without the PKCE verifier
+ * the app never shares.
+ *
+ * The development builds (`bun run update:desktop` on a Mac, a
+ * `FROCKBOT_IOS_DEV` build on an iPhone) are each a separate app beside the
+ * released one, with its own bundle identifier, so their sign-in comes back
+ * through their own `-dev` page and scheme: handed to the released scheme,
+ * the released app would take the code, or the system would open the wrong
+ * copy. Not in the Apple association, so Safari never offers it to the
+ * released app as a Universal Link either. Android needs no scheme.
+ */
+const NATIVE_RETURN_BUILDS: Record<
+  Exclude<NativeReturnPlatformV1, "android">,
+  "released" | "development"
+> = {
+  macos: "released",
+  "macos-dev": "development",
+  ios: "released",
+  "ios-dev": "development",
+};
+/** The returns the Apple association claims: the released apps' own. */
+const APPLE_ASSOCIATED_RETURNS = ["macos", "ios"] as const;
+const PREFIX = "frockbot-native.";
+const encoder = new TextEncoder();
+const NO_STORE = AUTH_NO_STORE_HEADERS_V1;
+
+/**
+ * Deployment policy, never a client-selected target or a per-Bot grant: the
+ * returns the profile's `nativeAuth` names, comma-separated. Nothing is
+ * implied — a FrockBot Dev return is served only where it is named — and a
+ * flag with an unknown name, a space or a repeat serves none.
+ */
+export function nativeReturnUris(
+  flag: string | undefined,
+  origin: string,
+): readonly string[] {
+  const named = flag?.split(",") ?? [];
+  const valid =
+    new Set(named).size === named.length &&
+    named.every((name) =>
+      (NATIVE_RETURN_PLATFORMS as readonly string[]).includes(name),
+    );
+  return valid
+    ? NATIVE_RETURN_PLATFORMS.filter((platform) =>
+        named.includes(platform),
+      ).map((platform) => nativeReturnUriV1(origin, platform))
+    : [];
+}
+
+/** What the consent page calls the app a return belongs to. */
+function nativeAppName(
+  platform: NativeReturnPlatformV1,
+  product: string,
+): string {
+  switch (platform) {
+    case "android":
+      return `the ${product} app on this Android device`;
+    case "macos":
+      return `the ${product} app on this Mac`;
+    case "macos-dev":
+      return `${product} Dev on this Mac`;
+    case "ios":
+      return `the ${product} app on this iPhone`;
+    case "ios-dev":
+      return `${product} Dev on this iPhone`;
+  }
+}
+
+/**
+ * The signed apps a deployment's association files name: the profile's
+ * `nativeApps`, carried as the `NATIVE_APPS` var.
+ */
+export interface NativeAppsV1 {
+  android: readonly {
+    packageName: string;
+    sha256CertFingerprints: readonly string[];
+  }[];
+  apple: readonly string[];
+}
+
+const ANDROID_PACKAGE_V1 = /^[A-Za-z][A-Za-z0-9_]*(\.[A-Za-z][A-Za-z0-9_]*)+$/;
+const CERT_FINGERPRINT_V1 = /^[0-9A-F]{2}(:[0-9A-F]{2}){31}$/;
+const APPLE_APP_ID_V1 = /^[A-Z0-9]{10}\.[A-Za-z0-9.-]+$/;
+
+/**
+ * The `NATIVE_APPS` var, decoded. Deployment policy like `nativeAuth`: a value
+ * that is absent or malformed names no app, so the deployment claims no link
+ * rather than a guessed one.
+ */
+export function nativeAppsV1(flag: string | undefined): NativeAppsV1 {
+  const none: NativeAppsV1 = { android: [], apple: [] };
+  try {
+    const value: unknown = JSON.parse(flag ?? "null");
+    if (!isRecord(value) || !hasOnly(value, ["android", "apple"])) return none;
+    const android = value.android ?? [];
+    const apple = value.apple ?? [];
+    const valid =
+      Array.isArray(android) &&
+      android.every(
+        (app) =>
+          isRecord(app) &&
+          hasOnly(app, ["packageName", "sha256CertFingerprints"]) &&
+          typeof app.packageName === "string" &&
+          ANDROID_PACKAGE_V1.test(app.packageName) &&
+          Array.isArray(app.sha256CertFingerprints) &&
+          app.sha256CertFingerprints.length > 0 &&
+          app.sha256CertFingerprints.every(
+            (print) =>
+              typeof print === "string" && CERT_FINGERPRINT_V1.test(print),
+          ),
+      ) &&
+      Array.isArray(apple) &&
+      apple.every((id) => typeof id === "string" && APPLE_APP_ID_V1.test(id));
+    return valid ? ({ android, apple } as NativeAppsV1) : none;
+  } catch {
+    return none;
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+function hasOnly(
+  value: Record<string, unknown>,
+  keys: readonly string[],
+): boolean {
+  return Object.keys(value).every((key) => keys.includes(key));
+}
+
+/** The request origin with a fully qualified (trailing-dot) host normalised. */
+export function requestOrigin(url: URL): string {
+  const host = url.hostname.endsWith(".")
+    ? url.hostname.slice(0, -1)
+    : url.hostname;
+  return `${url.protocol}//${host}${url.port ? `:${url.port}` : ""}`;
+}
+
+// A supported app upgrade reuses a session, whatever version and protocol it
+// moved to: the protocol is compatibility, and the gate refuses one it no longer
+// serves. Catalogs stay bound.
+function sameClient(a: ClientHello, b: ClientHello): boolean {
+  const shape = (h: ClientHello) =>
+    JSON.stringify({
+      schemaVersion: h.schemaVersion,
+      catalogs: h.catalogs.map((c) => `${c.id}:${c.digest}`).sort(),
+    });
+  return shape(a) === shape(b);
+}
+
+export function isNativeAuthPath(path: string): boolean {
+  return (
+    path.startsWith("/api/auth/native/") ||
+    path.startsWith("/native/") ||
+    path === "/.well-known/assetlinks.json" ||
+    path === "/.well-known/apple-app-site-association"
+  );
+}
+
+interface StartClaims {
+  kind: "start";
+  start: AuthStartCommand;
+  hello: ClientHello;
+  expires: number;
+}
+/**
+ * A pending authorization bound to the User it is for. `consent` is what the
+ * consent page's button posts, and only that post turns it into the
+ * `exchange` code the app redeems. The two are signed alike and are never
+ * each other: `verify` reads only the kind it was asked for.
+ */
+interface ExchangeClaims {
+  kind: "consent" | "exchange";
+  start: AuthStartCommand;
+  hello: ClientHello;
+  expires: number;
+  userId: string;
+}
+interface SessionClaims {
+  kind: "session";
+  userId: string;
+  sessionId: string;
+  hello: ClientHello;
+  expires: number;
+}
+interface SettingsClaims {
+  kind: "settings";
+  userId: string;
+  hello: ClientHello;
+  home: "models" | "connections";
+  expires: number;
+}
+type Claims = StartClaims | ExchangeClaims | SessionClaims | SettingsClaims;
+
+export interface NativeAuthOptions {
+  secret: string;
+  auth: AuthPackageIdentityV1;
+  // Only associated, signed targets belong here. No request can add an entry.
+  returnUris: readonly string[];
+  /** The signed apps the association files name. */
+  nativeApps: NativeAppsV1;
+  /** What the pages show of the product. */
+  brand: ReturnPageBrandV1;
+  /**
+   * The beta-access authority, asked after a bearer passes its read-only
+   * session check, or before a session is issued. Reads never provision a User.
+   * `null` means the identity no longer exists; a throw means the authority
+   * could not answer.
+   * Never asked for `developmentUserId`, which only a development stack sets.
+   */
+  admit(userId: string): Promise<AccountAdmissionDecisionV1 | null>;
+  session(
+    userId: string,
+    operation: NativeSessionOperation,
+  ): Promise<NativeSessionRecord | null>;
+  now?: () => number;
+  /**
+   * The deployment's own origin — every sign-in redirect, return URI and the
+   * origin check on `/native/*` is built from it. The Worker reads it from
+   * `BETTER_AUTH_URL`, which is what a development stack already points at its
+   * own host.
+   */
+  origin: string;
+  /**
+   * The development sign-in door: with this set, `/native/authorize` issues
+   * the code for this User when the browser holds no session, in place of
+   * Google. Set only from `ALLOW_DEVELOPMENT_AUTH`, which production refuses.
+   */
+  developmentUserId?: string;
+}
+
+export interface NativeAuth {
+  route(request: Request): Promise<Response | undefined>;
+  /**
+   * `admission` is the authority's answer for this bearer, so the gateway
+   * does not ask twice; it is absent for the development identity.
+   */
+  authenticate(request: Request): Promise<
+    | {
+        session: AuthIdentityV1 | null;
+        refusal?: Response;
+        admission?: AccountAdmissionDecisionV1;
+      }
+    | undefined
+  >;
+}
+
+function base64(bytes: Uint8Array): string {
+  return btoa(String.fromCharCode(...bytes))
+    .replaceAll("+", "-")
+    .replaceAll("/", "_")
+    .replace(/=+$/, "");
+}
+function unbase64(text: string): Uint8Array<ArrayBuffer> {
+  return Uint8Array.from(
+    atob(text.replaceAll("-", "+").replaceAll("_", "/")),
+    (c) => c.charCodeAt(0),
+  );
+}
+export async function readNativeJsonBody(
+  request: Request,
+  maximumBytes = 8192,
+): Promise<unknown> {
+  const text = await readLimitedText(request, maximumBytes);
+  let depth = 0,
+    quoted = false,
+    escaped = false;
+  for (const character of text) {
+    if (quoted) {
+      if (escaped) escaped = false;
+      else if (character === "\\") escaped = true;
+      else if (character === '"') quoted = false;
+    } else if (character === '"') quoted = true;
+    else if (character === "{" || character === "[") {
+      if (++depth > 16) throw new Error("Input nesting limit");
+    } else if (character === "}" || character === "]") depth--;
+  }
+  return JSON.parse(text);
+}
+
+async function readLimitedText(
+  request: Request,
+  maximumBytes: number,
+): Promise<string> {
+  const reader = request.body?.getReader();
+  if (!reader) throw new Error("Missing input");
+  let size = 0;
+  const chunks: Uint8Array[] = [];
+  while (true) {
+    const next = await reader.read();
+    if (next.done) break;
+    size += next.value.length;
+    if (size > maximumBytes) {
+      await reader.cancel();
+      throw new Error("Too much input");
+    }
+    chunks.push(next.value);
+  }
+  const data = new Uint8Array(size);
+  let offset = 0;
+  for (const chunk of chunks) {
+    data.set(chunk, offset);
+    offset += chunk.length;
+  }
+  return new TextDecoder().decode(data);
+}
+
+export function createNativeAuth(options: NativeAuthOptions): NativeAuth {
+  // Normalised, so a configured origin with a trailing slash or a default port
+  // still matches the request origin the `/native/*` check compares it against.
+  const origin = new URL(options.origin).origin;
+  const product = options.brand.productName;
+  const now = options.now ?? Date.now;
+  const key = () =>
+    crypto.subtle.importKey(
+      "raw",
+      encoder.encode(`frockbot-native-v1:${options.secret}`),
+      { name: "HMAC", hash: "SHA-256" },
+      false,
+      ["sign", "verify"],
+    );
+  async function sign(claims: Claims): Promise<string> {
+    const payload = base64(encoder.encode(JSON.stringify(claims)));
+    const signature = await crypto.subtle.sign(
+      "HMAC",
+      await key(),
+      encoder.encode(payload),
+    );
+    return `${payload}.${base64(new Uint8Array(signature))}`;
+  }
+  async function verify(token: string, kind: Claims["kind"]): Promise<Claims> {
+    if (token.length > 4096) throw new Error("Invalid token");
+    const parts = token.split(".");
+    if (
+      parts.length !== 2 ||
+      !/^[A-Za-z0-9_-]+$/.test(parts[0]!) ||
+      !/^[A-Za-z0-9_-]+$/.test(parts[1]!)
+    )
+      throw new Error("Invalid token");
+    if (
+      !(await crypto.subtle.verify(
+        "HMAC",
+        await key(),
+        unbase64(parts[1]!),
+        encoder.encode(parts[0]!),
+      ))
+    )
+      throw new Error("Invalid signature");
+    const value: unknown = JSON.parse(
+      new TextDecoder().decode(unbase64(parts[0]!)),
+    );
+    if (!value || typeof value !== "object" || Array.isArray(value))
+      throw new Error("Invalid claims");
+    const v = value as Record<string, unknown>;
+    if (
+      v.kind !== kind ||
+      typeof v.expires !== "number" ||
+      !Number.isSafeInteger(v.expires) ||
+      v.expires <= now() ||
+      !isProtocolValue("ClientHello", v.hello)
+    )
+      throw new Error("Expired sign-in");
+    if (kind === "settings") {
+      if (
+        !isProtocolValue("Identifier", v.userId) ||
+        (v.home !== "models" && v.home !== "connections")
+      )
+        throw new Error("Invalid settings destination");
+      return {
+        kind,
+        userId: v.userId,
+        home: v.home,
+        hello: v.hello,
+        expires: v.expires,
+      };
+    }
+    if (kind !== "session") {
+      if (
+        !isProtocolValue("AuthStartCommand", v.start) ||
+        !options.returnUris.includes(v.start.returnUri)
+      )
+        throw new Error("Invalid return link");
+      if (kind === "start")
+        return { kind, start: v.start, hello: v.hello, expires: v.expires };
+      if (!isProtocolValue("Identifier", v.userId))
+        throw new Error("Invalid User");
+      return {
+        kind,
+        start: v.start,
+        hello: v.hello,
+        expires: v.expires,
+        userId: v.userId,
+      };
+    }
+    if (
+      !isProtocolValue("Identifier", v.userId) ||
+      !isProtocolValue("Identifier", v.sessionId)
+    )
+      throw new Error("Invalid session");
+    return {
+      kind,
+      userId: v.userId,
+      sessionId: v.sessionId,
+      hello: v.hello,
+      expires: v.expires,
+    };
+  }
+  function hello(request: Request): ClientHello {
+    const value: unknown = JSON.parse(
+      request.headers.get(CLIENT_HELLO_HEADER) ?? "null",
+    );
+    if (!isProtocolValue("ClientHello", value))
+      throw new Error(UPDATE_APP_MESSAGE);
+    return value;
+  }
+  async function browserIdentity(
+    request: Request,
+  ): Promise<AuthIdentityV1 | null> {
+    // Browser cookies only: this endpoint cannot be used to launder another bearer.
+    const headers = new Headers();
+    const cookie = request.headers.get("cookie");
+    if (cookie) headers.set("cookie", cookie);
+    return options.auth.getSession(headers);
+  }
+  function operation(
+    claims: SessionClaims,
+    action: NativeSessionOperation["action"],
+  ): NativeSessionOperation {
+    return {
+      schemaVersion: 1,
+      userId: claims.userId,
+      sessionId: claims.sessionId,
+      hello: claims.hello,
+      expiresAt: claims.expires,
+      action,
+    };
+  }
+  async function admitBeforeUser(
+    userId: string,
+  ): Promise<AccountAdmissionDecisionV1 | "development" | Response | null> {
+    if (
+      options.developmentUserId !== undefined &&
+      userId === options.developmentUserId
+    ) {
+      return "development";
+    }
+    let decision: AccountAdmissionDecisionV1 | null;
+    try {
+      decision = await options.admit(userId);
+    } catch {
+      return admissionUnavailableResponse();
+    }
+    if (decision && !decision.admitted) {
+      return admissionRefusedResponse(decision.reason, false);
+    }
+    return decision;
+  }
+  /** The code for `userId`, sent to the return the app started with. */
+  async function handBack(
+    claims: StartClaims | ExchangeClaims,
+    userId: string,
+    status: 302 | 303,
+  ): Promise<Response> {
+    const code = await sign({
+      kind: "exchange",
+      start: claims.start,
+      hello: claims.hello,
+      expires: claims.expires,
+      userId,
+    });
+    const destination = new URL(claims.start.returnUri);
+    destination.searchParams.set("code", code);
+    destination.searchParams.set("state", claims.start.state);
+    return new Response(null, {
+      status,
+      headers: { ...NO_STORE, location: destination.toString() },
+    });
+  }
+  /**
+   * The press that lets this browser's User sign the app in. The consent it
+   * posts is bound to that User and to this authorization's state, challenge
+   * and return, and expires with it; the page cannot be framed.
+   */
+  async function consentPage(
+    claims: StartClaims,
+    session: AuthIdentityV1,
+  ): Promise<Response> {
+    const consent = await sign({
+      kind: "consent",
+      start: claims.start,
+      hello: claims.hello,
+      expires: claims.expires,
+      userId: session.user.id,
+    });
+    const platform = NATIVE_RETURN_PLATFORMS.find(
+      (candidate) =>
+        nativeReturnUriV1(origin, candidate) === claims.start.returnUri,
+    );
+    const destination = new URL(claims.start.returnUri);
+    return returnPageV1({
+      brand: options.brand,
+      title: `Sign in to ${product}`,
+      heading: `Sign in to ${platform ? nativeAppName(platform, product) : `the ${product} development build on this device`}?`,
+      lead: session.user.email
+        ? `You’ll be signed in as ${session.user.email}.`
+        : "You’ll be signed in with the account this browser uses.",
+      form: {
+        label: "Sign in",
+        action: `${origin}/native/authorize`,
+        fields: { consent },
+        // The development scheme is the one return off this origin.
+        ...(destination.origin === origin
+          ? {}
+          : { redirects: [destination.protocol] }),
+      },
+      footnote:
+        "Only continue if you just started signing in from the app. If you didn’t, close this page: nothing is signed in until you press Sign in.",
+    });
+  }
+  return {
+    async authenticate(request) {
+      const bearer = request.headers.get("authorization");
+      if (!bearer?.startsWith(`Bearer ${PREFIX}`)) return undefined;
+      const refusal = clientCompatibilityResponse(
+        request,
+        new URL(`${origin}/api/native/session`),
+      );
+      if (refusal) return { session: null, refusal };
+      let claims: Claims;
+      try {
+        claims = await verify(bearer.slice(7 + PREFIX.length), "session");
+        if (claims.kind !== "session") return { session: null };
+        // The app recovers a rejected session through sign-in; 426 asks for an update.
+        if (!sameClient(hello(request), claims.hello)) return { session: null };
+      } catch {
+        return { session: null };
+      }
+      let record: NativeSessionRecord | null;
+      try {
+        record = await options.session(
+          claims.userId,
+          operation(claims, "read"),
+        );
+      } catch {
+        return { session: null };
+      }
+      if (!record) return { session: null };
+      const admitted = await admitBeforeUser(claims.userId);
+      if (admitted instanceof Response) {
+        return { session: null, refusal: admitted };
+      }
+      if (admitted === null) return { session: null };
+      try {
+        // The email, not just the id: admission and the admin check read it,
+        // so a native session that omitted it made a listed admin ordinary on
+        // the phone while the same account was an admin in a browser.
+        const profile = await options.auth.profile?.(record.userId);
+        return {
+          session: {
+            user: {
+              id: record.userId,
+              ...(profile?.email ? { email: profile.email } : {}),
+              ...(profile?.emailVerified ? { emailVerified: true } : {}),
+            },
+          },
+          ...(admitted === "development" ? {} : { admission: admitted }),
+        };
+      } catch {
+        return { session: null };
+      }
+    },
+    async route(request) {
+      const url = new URL(request.url);
+      if (!isNativeAuthPath(url.pathname)) return undefined;
+      // The signed application's callback origin is not configurable by input.
+      // Google's asset-links fetcher asks for the fully qualified host
+      // ("bot.frockbot.com."); that trailing dot names the same origin.
+      if (requestOrigin(url) !== origin) return error(403);
+      const association =
+        url.pathname === "/.well-known/assetlinks.json" ||
+        url.pathname === "/.well-known/apple-app-site-association";
+      if (association && request.method === "HEAD") {
+        const full = await this.route(new Request(request.url));
+        return new Response(null, {
+          status: full?.status ?? 404,
+          headers: full?.headers,
+        });
+      }
+      try {
+        if (
+          url.pathname === "/.well-known/assetlinks.json" &&
+          request.method === "GET"
+        ) {
+          if (options.nativeApps.android.length === 0) return error(404);
+          return Response.json(
+            options.nativeApps.android.map((app) => ({
+              relation: ["delegate_permission/common.handle_all_urls"],
+              target: {
+                namespace: "android_app",
+                package_name: app.packageName,
+                sha256_cert_fingerprints: app.sha256CertFingerprints,
+              },
+            })),
+            { headers: { "cache-control": "public, max-age=300" } },
+          );
+        }
+        if (
+          url.pathname === "/.well-known/apple-app-site-association" &&
+          request.method === "GET"
+        ) {
+          // Only the Apple returns this deployment serves: a path it answers
+          // 404 for is never offered to an app as a verified link.
+          const components = APPLE_ASSOCIATED_RETURNS.filter((platform) =>
+            options.returnUris.includes(nativeReturnUriV1(origin, platform)),
+          ).map((platform) => ({ "/": `/native/return/${platform}` }));
+          if (components.length === 0 || options.nativeApps.apple.length === 0)
+            return error(404);
+          return Response.json(
+            {
+              applinks: {
+                details: [
+                  {
+                    appIDs: options.nativeApps.apple,
+                    components,
+                  },
+                ],
+              },
+            },
+            { headers: { "cache-control": "public, max-age=300" } },
+          );
+        }
+        // This signed link grants no browser session and no Connection. It only
+        // carries a short-lived navigation intent to the same authenticated User.
+        if (
+          url.pathname === "/api/auth/native/settings" &&
+          request.method === "POST"
+        ) {
+          const principal = await this.authenticate(request);
+          if (principal?.refusal) return principal.refusal;
+          if (!principal?.session) return error(401);
+          const command = await readNativeJsonBody(request);
+          if (!isProtocolValue("SettingsHandoffCommand", command))
+            return error();
+          const expires = now() + 300_000;
+          const token = await sign({
+            kind: "settings",
+            userId: principal.session.user.id,
+            home: command.home,
+            hello: hello(request),
+            expires,
+          });
+          return Response.json(
+            {
+              schemaVersion: 1,
+              authorizationUrl: `${origin}/native/settings?request=${token}`,
+              expiresAt: new Date(expires).toISOString(),
+            },
+            { headers: NO_STORE },
+          );
+        }
+        if (url.pathname === "/native/settings" && request.method === "GET") {
+          if ([...url.searchParams.keys()].join() !== "request") return error();
+          const token = url.searchParams.get("request") ?? "";
+          const claims = await verify(token, "settings");
+          if (claims.kind !== "settings") return error();
+          const session = await browserIdentity(request);
+          if (!session)
+            return options.auth.startSignIn(
+              request,
+              `${origin}/native/settings?request=${token}`,
+            );
+          if (session.user.id !== claims.userId)
+            return new Response(
+              `This browser is signed in to a different ${product} account. Switch accounts in the browser, then return to the app and try again.`,
+              {
+                status: 403,
+                headers: {
+                  ...NO_STORE,
+                  "content-type": "text/plain; charset=utf-8",
+                },
+              },
+            );
+          return redirect(
+            `${origin}/?settings=${claims.home}${claims.home === "models" ? "#user-model-providers" : ""}`,
+          );
+        }
+        if (
+          url.pathname === "/api/auth/native/start" &&
+          request.method === "POST"
+        ) {
+          const invalid = clientCompatibilityResponse(request, url);
+          if (invalid) return invalid;
+          const start = await readNativeJsonBody(request);
+          if (
+            !isProtocolValue("AuthStartCommand", start) ||
+            !options.returnUris.includes(start.returnUri)
+          )
+            return error();
+          const expires = now() + 300_000;
+          const token = await sign({
+            kind: "start",
+            start,
+            hello: hello(request),
+            expires,
+          });
+          return Response.json(
+            {
+              schemaVersion: 1,
+              authorizationUrl: `${origin}/native/authorize?request=${token}`,
+              expiresAt: new Date(expires).toISOString(),
+            },
+            { headers: NO_STORE },
+          );
+        }
+        // A code is issued only from the consent page's press. Anyone can
+        // call the start with their own PKCE values and open this URL in the
+        // person's browser — an app that claims `frockbot://` can — so a
+        // browser that is already signed in must not hand that app a code by
+        // itself. `/native/complete` shows the same page after a fresh
+        // sign-in: it is a GET any page can open, so it cannot tell a sign-in
+        // that just happened from a browser that was signed in already.
+        if (
+          ["/native/authorize", "/native/complete"].includes(url.pathname) &&
+          request.method === "GET"
+        ) {
+          if ([...url.searchParams.keys()].join() !== "request") return error();
+          const token = url.searchParams.get("request") ?? "";
+          const claims = await verify(token, "start");
+          if (claims.kind !== "start") return error();
+          const session = await browserIdentity(request);
+          if (session) return consentPage(claims, session);
+          // The development door signs in a scripted app with no browser to
+          // press in, on a stack production refuses.
+          if (options.developmentUserId !== undefined)
+            return handBack(claims, options.developmentUserId, 302);
+          if (url.pathname === "/native/complete") return error(401);
+          return options.auth.startSignIn(
+            request,
+            `${origin}/native/complete?request=${token}`,
+          );
+        }
+        if (url.pathname === "/native/authorize" && request.method === "POST") {
+          // The press must come from the consent page itself. The signed
+          // consent below is what a cross-site form cannot have; this refuses
+          // one before any identity is asked.
+          const site = request.headers.get("sec-fetch-site");
+          const from = request.headers.get("origin");
+          if (
+            (site === null && from === null) ||
+            (site !== null && site !== "same-origin") ||
+            (from !== null && from !== origin)
+          )
+            return error(403);
+          const form = new URLSearchParams(
+            await readLimitedText(request, 8192),
+          );
+          if ([...form.keys()].join() !== "consent") return error();
+          const claims = await verify(form.get("consent") ?? "", "consent");
+          if (claims.kind !== "consent") return error();
+          const session = await browserIdentity(request);
+          if (!session) return error(401);
+          if (session.user.id !== claims.userId) return error(403);
+          return handBack(claims, claims.userId, 303);
+        }
+        if (
+          url.pathname === "/api/auth/native/exchange" &&
+          request.method === "POST"
+        ) {
+          const invalid = clientCompatibilityResponse(request, url);
+          if (invalid) return invalid;
+          const command = await readNativeJsonBody(request);
+          if (!isProtocolValue("AuthExchangeCommand", command)) return error();
+          const claims = await verify(command.code, "exchange");
+          if (claims.kind !== "exchange") return error();
+          const digest = base64(
+            new Uint8Array(
+              await crypto.subtle.digest(
+                "SHA-256",
+                encoder.encode(command.codeVerifier),
+              ),
+            ),
+          );
+          if (
+            digest !== claims.start.codeChallenge ||
+            command.state !== claims.start.state ||
+            command.returnUri !== claims.start.returnUri ||
+            JSON.stringify(hello(request)) !== JSON.stringify(claims.hello)
+          )
+            return error();
+          const session: SessionClaims = {
+            kind: "session",
+            userId: claims.userId,
+            sessionId: claims.start.commandId,
+            hello: claims.hello,
+            expires: now() + 7 * 86400_000,
+          };
+          await options.session(
+            session.userId,
+            operation(session, "check-issue"),
+          );
+          const admitted = await admitBeforeUser(session.userId);
+          if (admitted instanceof Response) return admitted;
+          if (admitted === null) return error(401);
+          // Admission is committed before the bearer is returned. Replaying the
+          // same authorization, including a repeated callback, cannot issue twice.
+          const issued = await options.session(
+            session.userId,
+            operation(session, "issue"),
+          );
+          if (
+            !issued ||
+            issued.revoked ||
+            issued.userId !== session.userId ||
+            issued.sessionId !== session.sessionId ||
+            issued.expiresAt !== session.expires ||
+            JSON.stringify(issued.hello) !== JSON.stringify(session.hello)
+          )
+            return error();
+          return Response.json(
+            {
+              schemaVersion: 1,
+              userId: session.userId,
+              sessionId: session.sessionId,
+              expiresAt: new Date(session.expires).toISOString(),
+              sessionToken: PREFIX + (await sign(session)),
+            },
+            { headers: NO_STORE },
+          );
+        }
+        if (
+          url.pathname === "/api/auth/native/revoke" &&
+          request.method === "POST"
+        ) {
+          // This route is also called without the gateway's compatibility gate.
+          const invalid = clientCompatibilityResponse(request, url);
+          if (invalid) return invalid;
+          const bearer = request.headers.get("authorization") ?? "";
+          if (!bearer.startsWith(`Bearer ${PREFIX}`)) return error(401);
+          const claims = await verify(
+            bearer.slice(7 + PREFIX.length),
+            "session",
+          );
+          if (claims.kind !== "session") return error(401);
+          const command = await readNativeJsonBody(request);
+          if (
+            !isProtocolValue("SessionRevokeCommand", command) ||
+            command.sessionId !== claims.sessionId
+          )
+            return error();
+          // A 401 lets the app discard the unusable session and finish signing out.
+          if (!sameClient(hello(request), claims.hello))
+            return error(401, "Please sign in again.");
+          // Signing out narrows authority even while access is paused. The
+          // session owner revokes existing records without provisioning a User.
+          await options.session(claims.userId, operation(claims, "revoke"));
+          return Response.json(
+            { schemaVersion: 1, status: "signed-out" },
+            { headers: NO_STORE },
+          );
+        }
+        if (
+          options.returnUris.includes(url.origin + url.pathname) &&
+          request.method === "GET"
+        ) {
+          const page = url.origin + url.pathname;
+          const platform = NATIVE_RETURN_PLATFORMS.find(
+            (candidate) => nativeReturnUriV1(origin, candidate) === page,
+          );
+          if (platform)
+            return nativeReturnPage(platform, origin, options.brand);
+        }
+        return error(404);
+      } catch {
+        return error();
+      }
+    },
+  };
+}
+
+/**
+ * The page Google's completion lands on in the user's browser. On a Mac or an
+ * iPhone it carries the code and state across to the app on its custom
+ * scheme, forwarding only those two query parameters and never reflecting
+ * them into markup. On Android the verified App Link has already opened the
+ * app; this page is what remains in the browser, and what a user sees if it
+ * did not.
+ */
+function nativeReturnPage(
+  platform: NativeReturnPlatformV1,
+  origin: string,
+  brand: ReturnPageBrandV1,
+): Response {
+  const product = brand.productName;
+  const returnUri = new URL(nativeReturnUriV1(origin, platform));
+  const target =
+    platform === "android"
+      ? undefined
+      : `${nativeReturnSchemeV1(brand, NATIVE_RETURN_BUILDS[platform])}://${returnUri.host}${returnUri.pathname}`;
+  return returnPageV1({
+    brand,
+    title: `Return to ${product}`,
+    heading: `Return to ${product} to finish signing in`,
+    lead: target
+      ? `Your browser is handing you over to the ${product} app. Once it opens, you can close this tab.`
+      : `Head back to the ${product} app to finish signing in. You can close this page.`,
+    footnote: `If ${product} did not open, check that the latest app is installed and try signing in again.`,
+    ...(target === undefined
+      ? {}
+      : {
+          status: `Opening ${product}`,
+          action: { label: `Open ${product}`, href: target, id: "open" },
+          script: `(function () {
+  var incoming = new URLSearchParams(location.search);
+  var forwarded = new URLSearchParams();
+  ["code", "state"].forEach(function (key) {
+    var value = incoming.get(key);
+    if (value !== null) forwarded.set(key, value);
+  });
+  var href = ${JSON.stringify(target)} + (forwarded.toString() ? "?" + forwarded.toString() : "");
+  document.getElementById("open").setAttribute("href", href);
+  location.replace(href);
+})();`,
+        }),
+  });
+}