alpha-gate 0.1.0

package/src/routes/admin/theme.ts

@@ -0,0 +1,34 @@
+import { deleteCookie, setCookie } from "hono/cookie";
+import type { AdminContext } from "./admin-context";
+import { field, returnTo } from "./form";
+import { requireUser } from "./middleware";
+
+// The theme toggle (sidebar foot): light / system / dark. A plain form POST that works with JS
+// disabled — the choice lives in a `theme` cookie the GET pages read (and a pre-paint script
+// applies on chrome-less pages). "system" clears the cookie: following the OS is the default,
+// not a stored value. A UI preference, not a domain mutation — deliberately NOT audited.
+
+const YEAR_SECONDS = 60 * 60 * 24 * 365;
+
+export async function setTheme(c: AdminContext): Promise<Response> {
+  if (requireUser(c) === null) return c.text("Forbidden", 403);
+  const body = await c.req.parseBody();
+  const value = field(body, "value");
+  if (value !== "light" && value !== "dark" && value !== "system") {
+    return c.text("Bad request", 400);
+  }
+
+  const secure = new URL(c.req.url).protocol === "https:";
+  if (value === "system") {
+    deleteCookie(c, "theme", { path: "/" });
+  } else {
+    // Not HttpOnly on purpose: the pre-paint script reads it. It holds nothing sensitive.
+    setCookie(c, "theme", value, {
+      path: "/",
+      sameSite: "Lax",
+      maxAge: YEAR_SECONDS,
+      secure,
+    });
+  }
+  return c.redirect(returnTo(body) ?? "/admin", 303);
+}

package/src/routes/admin/upload.tsx

@@ -0,0 +1,320 @@
+import * as builds from "../../db/builds";
+import * as streams from "../../db/streams";
+import { headObject, putArchive } from "../../r2/builds-bucket";
+import { recordAudit } from "../../services/audit";
+import { ResultPage } from "../../views/admin/manage-pages";
+import { renderPage } from "../../views/layout";
+import type { AdminContext } from "./admin-context";
+import { auditFields } from "./audit-fields";
+import { field, toId } from "./form";
+import { wantsHtml } from "./negotiate";
+
+// §20 / decision 0007 — the convergence point for all publish paths. Both routes accept a service
+// token (CI) as well as a human (decision 0006 scopes service tokens to exactly here). The Worker
+// NEVER signs; it stores bytes + the supplied EdDSA signature. A wrong length would break Sparkle
+// for every client, so the register path asserts the stored object's size matches the declared one.
+
+const MAX_UPLOAD_BYTES = 90 * 1024 * 1024; // conservative ceiling under the 100 MB Workers body cap
+
+/**
+ * GET /admin/publish-info — everything a publish script needs to get a release RIGHT the first time,
+ * as JSON. Service-token allowed (decision 0006 scopes it here + the two publish routes): it's
+ * read-only and publishing-scoped, so the script can pre-check the next build number, resolve a
+ * channel name, and know the size ceiling BEFORE it spends minutes signing and uploading. This turns
+ * "full upload → 409 duplicate" into "instant local check".
+ */
+export async function publishInfo(c: AdminContext): Promise<Response> {
+  const deps = c.get("deps");
+  const all = await builds.listAll(deps.db);
+  const topBuild = all.reduce((max, b) => Math.max(max, b.buildNumber), 0);
+  const channels = (await streams.list(deps.db)).map((s) => ({ id: s.id, name: s.name }));
+  return c.json({
+    // The highest build_number in use; the next publish must exceed it.
+    topBuild,
+    nextBuildHint: topBuild + 1,
+    channels,
+    maxUploadBytes: MAX_UPLOAD_BYTES,
+  });
+}
+
+interface BuildMeta {
+  shortVersion: string;
+  buildNumber: number;
+  edSignature: string;
+  minOs: string | null;
+  critical: boolean;
+  /** Resolved channel to link on publish, or null. Set from stream_id (id) OR channel (name). */
+  streamId: number | null;
+  /** A `channel=<name>` request awaiting resolution to an id (mutually exclusive with stream_id). */
+  channelName: string | null;
+}
+
+// STRICT digits only — parseInt would quietly accept "1.2.3" as 1 and "1500abc" as 1500, minting a
+// wrong (and permanent: build_number is unique and monotonic) build number from a swapped argument.
+function intField(body: Record<string, unknown>, name: string): number | null {
+  const raw = field(body, name);
+  if (raw === null || !/^\d+$/.test(raw.trim())) return null;
+  const n = Number.parseInt(raw, 10);
+  return Number.isSafeInteger(n) ? n : null;
+}
+
+function parseBuildMeta(
+  body: Record<string, unknown>,
+): { ok: true; value: BuildMeta } | { ok: false; error: string } {
+  const shortVersion = field(body, "short_version");
+  const edSignature = field(body, "ed_signature");
+  const buildNumber = intField(body, "build_number");
+  if (shortVersion === null || edSignature === null) {
+    return { ok: false, error: "short_version and ed_signature are required" };
+  }
+  if (buildNumber === null || buildNumber <= 0) {
+    return { ok: false, error: "build_number must be a positive integer" };
+  }
+  // Channel destination two ways: stream_id (the browser select; a DB id) OR channel=<name> (the
+  // publish CLI — human-friendly, per the "never a DB row id on operator surfaces" principle). The
+  // name is resolved to an id in rejectPublish (needs the db); giving both is a conflict.
+  const streamId = toId(field(body, "stream_id"));
+  const channelName = field(body, "channel");
+  if (streamId !== null && channelName !== null) {
+    return { ok: false, error: "give either stream_id or channel, not both" };
+  }
+  return {
+    ok: true,
+    value: {
+      shortVersion,
+      buildNumber,
+      edSignature,
+      minOs: field(body, "min_os"),
+      critical: field(body, "critical") === "true",
+      streamId,
+      channelName,
+    },
+  };
+}
+
+// Content-negotiated responses (decision 0006 — both routes serve a human form AND a CI service token).
+// A browser gets a page; CI keeps the machine JSON/text contract. See ./negotiate.
+
+function fail(c: AdminContext, status: 400 | 409 | 413 | 507, message: string): Response {
+  if (!wantsHtml(c)) return c.text(message, status);
+  return c.html(
+    renderPage(
+      <ResultPage
+        title="Upload failed"
+        intent="error"
+        back={{ href: "/admin/upload", label: "← Back to upload" }}
+      >
+        <p>{message}</p>
+      </ResultPage>,
+    ),
+    status,
+  );
+}
+
+// build_number is UNIQUE (Sparkle's monotonic key). A re-upload of an existing one would hit the DB
+// constraint and surface as a bare 500; pre-check so the admin gets an actionable message instead. In
+// uploadBuild this runs BEFORE the R2 PUT, so a rejected duplicate never leaves an orphan archive.
+async function duplicateBuild(c: AdminContext, buildNumber: number): Promise<Response | null> {
+  const existing = await builds.getByBuildNumber(c.get("deps").db, buildNumber);
+  if (existing === null) return null;
+  return fail(
+    c,
+    409,
+    `Build number ${buildNumber} already exists (published as ${existing.shortVersion}). Each ` +
+      `build number is unique — to publish a corrected build, give it a higher number (a roll-forward).`,
+  );
+}
+
+/**
+ * Pre-write validation shared by both publish endpoints, run BEFORE any R2 or D1 write so a rejected
+ * publish never half-registers (the old failure mode: build row inserted, then the channel link threw
+ * a raw foreign-key 500 with the archive already stored). Also RESOLVES a channel name into
+ * `meta.streamId` in place, so the insert path only ever deals with an id.
+ */
+async function rejectPublish(
+  c: AdminContext,
+  body: Record<string, unknown>,
+  meta: BuildMeta,
+): Promise<Response | null> {
+  const deps = c.get("deps");
+
+  const duplicate = await duplicateBuild(c, meta.buildNumber);
+  if (duplicate !== null) return duplicate;
+
+  // Resolve a channel NAME → id (the publish CLI's --channel). Unknown name is a clear 400 that
+  // lists what exists, not a foreign-key 500.
+  if (meta.channelName !== null) {
+    const stream = await streams.getByName(deps.db, meta.channelName);
+    if (stream === null) {
+      const names = (await streams.list(deps.db)).map((s) => s.name);
+      return fail(
+        c,
+        400,
+        `Channel "${meta.channelName}" not found. ` +
+          (names.length > 0
+            ? `Existing channels: ${names.join(", ")}.`
+            : "No channels exist yet.") +
+          " Nothing was published.",
+      );
+    }
+    meta.streamId = stream.id;
+  }
+
+  // The selected channel must still exist (a stale form otherwise FK-500s AFTER the insert).
+  if (meta.streamId !== null && (await streams.getById(deps.db, meta.streamId)) === null) {
+    return fail(
+      c,
+      400,
+      `Channel ${meta.streamId} not found — it may have been deleted. Nothing was published; ` +
+        `pick another channel (or none) and retry.`,
+    );
+  }
+
+  // Rollback mode's whole point is a build number ABOVE the current highest (Sparkle can't
+  // downgrade); enforce the floor the form only explains.
+  if (field(body, "mode") === "rollback") {
+    const all = await builds.listAll(deps.db);
+    const top = all.reduce((max, b) => Math.max(max, b.buildNumber), 0);
+    if (meta.buildNumber <= top) {
+      return fail(
+        c,
+        400,
+        `A rollback build must exceed the current highest build number (${top}) — Sparkle never ` +
+          `offers a lower build. Rebuild the previous good code with a number above ${top}.`,
+      );
+    }
+  }
+  return null;
+}
+
+function published(
+  c: AdminContext,
+  build: { id: number; buildNumber: number; shortVersion: string },
+  streamName: string | null,
+): Response {
+  return c.html(
+    renderPage(
+      <ResultPage
+        title="Build published"
+        back={{ href: `/admin/builds/${build.id}`, label: `Open build ${build.buildNumber} →` }}
+      >
+        <p>
+          Build <strong>{build.buildNumber}</strong> ({build.shortVersion}) is now available.
+        </p>
+        {streamName !== null ? (
+          <p class="muted">
+            It's in the <strong>{streamName}</strong> channel — users assigned there are offered it
+            on their next update check (unless a higher build already serves them).
+          </p>
+        ) : (
+          <p class="callout warn">
+            It isn't in any channel yet, so <strong>no one receives it</strong> until you link a
+            channel from the <a href={`/admin/builds/${build.id}`}>build page</a>.
+          </p>
+        )}
+      </ResultPage>,
+    ),
+    201,
+  );
+}
+
+/** Full upload: streams the archive body to R2 (under the size ceiling), then registers the build. */
+export async function uploadBuild(c: AdminContext): Promise<Response> {
+  const deps = c.get("deps");
+
+  const declaredLength = Number.parseInt(c.req.header("content-length") ?? "", 10);
+  if (Number.isFinite(declaredLength) && declaredLength > MAX_UPLOAD_BYTES) {
+    return fail(c, 413, "Archive exceeds the upload ceiling; use /admin/builds/register");
+  }
+
+  const body = await c.req.parseBody();
+  const archive = body.archive;
+  if (!(archive instanceof File)) return fail(c, 400, "an archive file is required");
+  if (archive.size > MAX_UPLOAD_BYTES) {
+    return fail(c, 413, "Archive exceeds the upload ceiling; use /admin/builds/register");
+  }
+
+  const meta = parseBuildMeta(body);
+  if (!meta.ok) return fail(c, 400, meta.error);
+
+  const rejected = await rejectPublish(c, body, meta.value);
+  if (rejected !== null) return rejected;
+
+  let objectKey: string;
+  try {
+    objectKey = await putArchive(
+      deps.r2,
+      meta.value.buildNumber,
+      archive.name || "App.zip",
+      await archive.arrayBuffer(),
+    );
+  } catch (e) {
+    // A quota/write failure otherwise surfaces as a bare 500 with nothing published. Say what's
+    // wrong and the remedy (the Builds page shows the total and offers per-build archive purge).
+    console.error("[upload] R2 put failed:", e);
+    return fail(
+      c,
+      507,
+      "Storage write failed — the R2 bucket may be at the free-tier limit. Purge withdrawn builds' " +
+        "archives from the Builds page to reclaim space, then retry. Nothing was published.",
+    );
+  }
+  const build = await builds.insert(deps.db, {
+    shortVersion: meta.value.shortVersion,
+    buildNumber: meta.value.buildNumber,
+    objectKey,
+    edSignature: meta.value.edSignature,
+    length: archive.size,
+    minOs: meta.value.minOs,
+    critical: meta.value.critical,
+  });
+  const streamName =
+    meta.value.streamId === null
+      ? null
+      : ((await streams.getById(deps.db, meta.value.streamId))?.name ?? null);
+  if (meta.value.streamId !== null) await builds.linkStream(deps.db, build.id, meta.value.streamId);
+  await recordAudit(deps, auditFields(c, "build.upload", String(meta.value.buildNumber)));
+
+  if (wantsHtml(c)) return published(c, build, streamName);
+  return c.json({ ok: true, buildNumber: meta.value.buildNumber, objectKey }, 201);
+}
+
+/** Metadata-only register for an archive already PUT to R2 out of band (large builds, §20). */
+export async function registerBuild(c: AdminContext): Promise<Response> {
+  const deps = c.get("deps");
+  const body = await c.req.parseBody();
+
+  const objectKey = field(body, "object_key");
+  const size = intField(body, "size");
+  if (objectKey === null || size === null || size < 0) {
+    return fail(c, 400, "object_key and a non-negative size are required");
+  }
+  const meta = parseBuildMeta(body);
+  if (!meta.ok) return fail(c, 400, meta.error);
+
+  const rejected = await rejectPublish(c, body, meta.value);
+  if (rejected !== null) return rejected;
+
+  const head = await headObject(deps.r2, objectKey);
+  if (head === null) return fail(c, 400, "object not found in R2");
+  if (head.size !== size) return fail(c, 400, "declared size does not match the stored object");
+
+  const build = await builds.insert(deps.db, {
+    shortVersion: meta.value.shortVersion,
+    buildNumber: meta.value.buildNumber,
+    objectKey,
+    edSignature: meta.value.edSignature,
+    length: size,
+    minOs: meta.value.minOs,
+    critical: meta.value.critical,
+  });
+  const streamName =
+    meta.value.streamId === null
+      ? null
+      : ((await streams.getById(deps.db, meta.value.streamId))?.name ?? null);
+  if (meta.value.streamId !== null) await builds.linkStream(deps.db, build.id, meta.value.streamId);
+  await recordAudit(deps, auditFields(c, "build.register", String(meta.value.buildNumber)));
+
+  if (wantsHtml(c)) return published(c, build, streamName);
+  return c.json({ ok: true, buildNumber: meta.value.buildNumber }, 201);
+}

package/src/routes/admin/views.tsx

@@ -0,0 +1,293 @@
+import { getCookie } from "hono/cookie";
+import type { AccessEvent } from "../../core/types";
+import { totalArchiveBytes } from "../../db/builds";
+import { adminToAppOrigin, inviteUrl } from "../../lib/hosts";
+import { emailStatus } from "../../services/email";
+import { CiPage } from "../../views/admin/ci-page";
+import type { Chrome } from "../../views/admin/layout";
+import {
+  BuildManagePage,
+  SettingsPage,
+  StreamManagePage,
+  UploadPage,
+  UserManagePage,
+} from "../../views/admin/manage";
+import {
+  ActivityPage,
+  AuditPage,
+  BuildsPage,
+  OverviewPage,
+  PendingPage,
+  StreamsPage,
+  UsersPage,
+} from "../../views/admin/read-pages";
+import { SetupPage } from "../../views/admin/setup-page";
+import { renderPage } from "../../views/layout";
+import type { AdminContext } from "./admin-context";
+import { flashMessage } from "./flash";
+import { toId } from "./form";
+import {
+  loadActivity,
+  loadAudit,
+  loadBuildDetail,
+  loadBuilds,
+  loadChainStatus,
+  loadChannels,
+  loadDashboard,
+  loadPending,
+  loadPendingCount,
+  loadSettings,
+  loadStreamDetail,
+  loadStreams,
+  loadUser,
+  loadUsersPage,
+  selfUpdateView,
+} from "./read-model";
+
+// §13 — the admin GET pages. Each loads its read-model and renders the matching pure view, threading
+// the shared chrome (flash notice, instance slug, pending-requests chip) and the clock's now.
+
+async function chromeFor(c: AdminContext): Promise<Chrome> {
+  const theme = getCookie(c, "theme");
+  return {
+    notice: flashMessage(c),
+    instance: c.env?.INSTANCE,
+    pending: await loadPendingCount(c.get("deps")),
+    theme: theme === "light" || theme === "dark" ? theme : undefined,
+    path: c.req.path,
+  };
+}
+
+export async function dashboardView(c: AdminContext): Promise<Response> {
+  const deps = c.get("deps");
+  return c.html(
+    renderPage(
+      <OverviewPage
+        data={await loadDashboard(deps)}
+        now={deps.clock()}
+        chrome={await chromeFor(c)}
+      />,
+    ),
+  );
+}
+
+export async function usersView(c: AdminContext): Promise<Response> {
+  const deps = c.get("deps");
+  const { users, channels } = await loadUsersPage(deps);
+  const filter = {
+    status: c.req.query("status") ?? "",
+    stream: c.req.query("stream") ?? "",
+    nobuild: c.req.query("nobuild") === "1",
+    pinned: c.req.query("pinned") === "1",
+    hidden: c.req.query("hidden") === "1", // show hidden too (default: visible only)
+  };
+  const hiddenCount = users.filter((u) => u.hidden).length;
+  let rows = users;
+  if (!filter.hidden) rows = rows.filter((u) => !u.hidden);
+  if (filter.status) rows = rows.filter((u) => u.status === filter.status);
+  if (filter.nobuild) rows = rows.filter((u) => u.noBuild !== "servable");
+  if (filter.pinned) rows = rows.filter((u) => u.pinnedBuildId !== null);
+  if (filter.stream) rows = rows.filter((u) => u.streams.includes(filter.stream));
+  return c.html(
+    renderPage(
+      <UsersPage
+        users={rows}
+        channels={channels}
+        filter={filter}
+        hiddenCount={hiddenCount}
+        now={deps.clock()}
+        chrome={await chromeFor(c)}
+      />,
+    ),
+  );
+}
+
+export async function userManageView(c: AdminContext): Promise<Response> {
+  const deps = c.get("deps");
+  const id = toId(c.req.param("id"));
+  const detail = id === null ? null : await loadUser(deps, id);
+  if (detail === null) return c.text("Not found", 404);
+  return c.html(
+    renderPage(
+      <UserManagePage
+        detail={detail}
+        inviteLink={inviteUrl(c.req.url, detail.client.token)}
+        linkDerived={adminToAppOrigin(new URL(c.req.url).origin) !== null}
+        now={deps.clock()}
+        chrome={await chromeFor(c)}
+      />,
+    ),
+  );
+}
+
+export async function buildsView(c: AdminContext): Promise<Response> {
+  const deps = c.get("deps");
+  const [builds, channels, storageBytes] = await Promise.all([
+    loadBuilds(deps),
+    loadChannels(deps),
+    totalArchiveBytes(deps.db),
+  ]);
+  const showHidden = c.req.query("hidden") === "1"; // default: visible only
+  const hiddenCount = builds.filter((b) => b.build.hidden).length;
+  const rows = showHidden ? builds : builds.filter((b) => !b.build.hidden);
+  return c.html(
+    renderPage(
+      <BuildsPage
+        builds={rows}
+        channels={channels}
+        showHidden={showHidden}
+        hiddenCount={hiddenCount}
+        storageBytes={storageBytes}
+        now={deps.clock()}
+        chrome={await chromeFor(c)}
+      />,
+    ),
+  );
+}
+
+export async function buildManageView(c: AdminContext): Promise<Response> {
+  const deps = c.get("deps");
+  const id = toId(c.req.param("id"));
+  const detail = id === null ? null : await loadBuildDetail(deps, id);
+  if (detail === null) return c.text("Not found", 404);
+  return c.html(
+    renderPage(<BuildManagePage detail={detail} now={deps.clock()} chrome={await chromeFor(c)} />),
+  );
+}
+
+export async function streamsView(c: AdminContext): Promise<Response> {
+  const deps = c.get("deps");
+  return c.html(
+    renderPage(<StreamsPage streams={await loadStreams(deps)} chrome={await chromeFor(c)} />),
+  );
+}
+
+export async function streamManageView(c: AdminContext): Promise<Response> {
+  const deps = c.get("deps");
+  const id = toId(c.req.param("id"));
+  const detail = id === null ? null : await loadStreamDetail(deps, id);
+  if (detail === null) return c.text("Not found", 404);
+  return c.html(
+    renderPage(<StreamManagePage detail={detail} now={deps.clock()} chrome={await chromeFor(c)} />),
+  );
+}
+
+export async function uploadView(c: AdminContext): Promise<Response> {
+  const deps = c.get("deps");
+  const [channels, builds] = await Promise.all([loadChannels(deps), loadBuilds(deps)]);
+  // The rollback guidance needs the floor (current highest build number) + a few recents for reference.
+  const recentBuilds = builds
+    .map((b) => ({ buildNumber: b.build.buildNumber, shortVersion: b.build.shortVersion }))
+    .sort((a, b) => b.buildNumber - a.buildNumber)
+    .slice(0, 5);
+  return c.html(
+    renderPage(
+      <UploadPage channels={channels} recentBuilds={recentBuilds} chrome={await chromeFor(c)} />,
+    ),
+  );
+}
+
+export async function ciView(c: AdminContext): Promise<Response> {
+  return c.html(
+    renderPage(<CiPage adminOrigin={new URL(c.req.url).origin} chrome={await chromeFor(c)} />),
+  );
+}
+
+export async function setupView(c: AdminContext): Promise<Response> {
+  const meta = await loadSettings(c.get("deps"));
+  const info = {
+    appName: meta.app_name || "Your App",
+    activateScheme: meta.activate_scheme || "myapp",
+    publicKey: meta.sparkle_public_key || null,
+    appOrigin: adminToAppOrigin(new URL(c.req.url).origin) ?? "<your App Worker URL>",
+  };
+  return c.html(renderPage(<SetupPage info={info} chrome={await chromeFor(c)} />));
+}
+
+export async function settingsView(c: AdminContext): Promise<Response> {
+  const deps = c.get("deps");
+  const settings = await loadSettings(deps);
+  const env = c.env;
+  const info = {
+    instance: env.INSTANCE,
+    toolVersion: env.TOOL_VERSION,
+    email: emailStatus(env),
+    accessTeam: env.ACCESS_TEAM_DOMAIN ?? null,
+    accessAud: env.ACCESS_AUD ?? null,
+    selfUpdate: selfUpdateView(settings),
+    appOrigin: adminToAppOrigin(new URL(c.req.url).origin),
+  };
+  return c.html(
+    renderPage(
+      <SettingsPage
+        settings={settings}
+        info={info}
+        now={deps.clock()}
+        chrome={await chromeFor(c)}
+      />,
+    ),
+  );
+}
+
+export async function pendingView(c: AdminContext): Promise<Response> {
+  const deps = c.get("deps");
+  return c.html(
+    renderPage(
+      <PendingPage
+        requests={await loadPending(deps)}
+        now={deps.clock()}
+        chrome={await chromeFor(c)}
+      />,
+    ),
+  );
+}
+
+export async function activityView(c: AdminContext): Promise<Response> {
+  const deps = c.get("deps");
+  const filter = {
+    email: c.req.query("email") ?? "",
+    event: c.req.query("event") ?? "",
+    build: c.req.query("build") ?? "",
+  };
+  const buildNumber = /^\d+$/.test(filter.build) ? Number.parseInt(filter.build, 10) : undefined;
+  const events = await loadActivity(deps, {
+    email: filter.email || undefined,
+    event: filter.event ? (filter.event as AccessEvent) : undefined,
+    buildNumber,
+  });
+  return c.html(
+    renderPage(
+      <ActivityPage
+        events={events}
+        filter={filter}
+        truncated={events.length >= 100}
+        now={deps.clock()}
+        chrome={await chromeFor(c)}
+      />,
+    ),
+  );
+}
+
+export async function auditView(c: AdminContext): Promise<Response> {
+  const deps = c.get("deps");
+  const filter = {
+    actor: c.req.query("actor") ?? "",
+    action: c.req.query("action") ?? "",
+  };
+  const rows = await loadAudit(deps, {
+    actor: filter.actor || undefined,
+    action: filter.action || undefined,
+  });
+  return c.html(
+    renderPage(
+      <AuditPage
+        rows={rows}
+        filter={filter}
+        chain={await loadChainStatus(deps)}
+        truncated={rows.length >= 200}
+        now={deps.clock()}
+        chrome={await chromeFor(c)}
+      />,
+    ),
+  );
+}

package/src/routes/app/access.tsx

@@ -0,0 +1,38 @@
+import * as accessRequests from "../../db/access-requests";
+import { isEmail } from "../../lib/text";
+import { loadBranding } from "../../services/branding";
+import { AccessPage, RequestReceivedPage } from "../../views/access-page";
+import { renderPage } from "../../views/layout";
+import type { AppContext } from "./app-context";
+
+// §13 — the public "request access" page (GET) and its submission (POST → a pending request the
+// admin reviews). No token required.
+
+export async function accessRoute(c: AppContext): Promise<Response> {
+  const branding = await loadBranding(c.get("deps"));
+  return c.html(renderPage(<AccessPage appName={branding.appName} accent={branding.accent} />));
+}
+
+export async function postAccessRoute(c: AppContext): Promise<Response> {
+  const deps = c.get("deps");
+  const body = await c.req.parseBody();
+  const email = typeof body.email === "string" ? body.email.trim() : "";
+  const branding = await loadBranding(deps);
+
+  if (!isEmail(email)) {
+    return c.html(
+      renderPage(<AccessPage appName={branding.appName} accent={branding.accent} />),
+      400,
+    );
+  }
+
+  await accessRequests.insert(deps.db, {
+    email,
+    ip: c.req.header("cf-connecting-ip") ?? null,
+    userAgent: c.req.header("user-agent") ?? null,
+    createdAt: deps.clock(),
+  });
+  return c.html(
+    renderPage(<RequestReceivedPage appName={branding.appName} accent={branding.accent} />),
+  );
+}

package/src/routes/app/app-context.ts

@@ -0,0 +1,8 @@
+import type { Context } from "hono";
+import type { Deps } from "../../deps";
+import type { Env } from "../../env";
+
+// The Hono realization of the Deps rule: a middleware puts Deps on the context, handlers read it via
+// c.get("deps") and never touch bindings directly. One type shared by every app-side handler.
+export type AppEnv = { Bindings: Env; Variables: { deps: Deps } };
+export type AppContext = Context<AppEnv>;