alpha-gate 0.1.0

package/src/routes/admin/index.ts

@@ -0,0 +1,146 @@
+import { Hono } from "hono";
+import { buildDeps, type Deps } from "../../deps";
+import type { Env } from "../../env";
+import type { AdminEnv } from "./admin-context";
+import { saveBranding, sendTestEmail } from "./branding";
+import {
+  bulkBuilds,
+  linkBuildStream,
+  markCritical,
+  markRollbackTarget,
+  purgeArchive,
+  restoreBuild,
+  setBuildHidden,
+  unlinkBuildStream,
+  withdrawBuild,
+} from "./builds";
+import {
+  assignStream,
+  createClient,
+  pinClient,
+  reactivateClient,
+  reissueClient,
+  revokeClient,
+  setClientHidden,
+  unassignStream,
+  unpinClient,
+} from "./clients";
+import { adminAuth } from "./middleware";
+import { dismissPending, invitePending } from "./pending";
+import { assignUsersToStream, createStream, deleteStream, linkBuildsToStream } from "./streams";
+import { setTheme } from "./theme";
+import { publishInfo, registerBuild, uploadBuild } from "./upload";
+import {
+  activityView,
+  auditView,
+  buildManageView,
+  buildsView,
+  ciView,
+  dashboardView,
+  pendingView,
+  settingsView,
+  setupView,
+  streamManageView,
+  streamsView,
+  uploadView,
+  userManageView,
+  usersView,
+} from "./views";
+
+// The gated Admin Worker surface (ROLE=admin). EVERY request passes through adminAuth from one mount,
+// so no route can forget verification. Public paths (/get, /appcast, …) aren't mounted → 404. Read
+// views and mutations are added in M12+. depsFor is injectable so tests swap the Access verifier.
+export function createAdminApp(depsFor: (env: Env) => Deps = buildDeps) {
+  const app = new Hono<AdminEnv>();
+
+  app.use("*", async (c, next) => {
+    c.set("deps", depsFor(c.env));
+    await next();
+  });
+  app.use("*", adminAuth);
+
+  // Decision 0006 enforced globally, not just on mutations: a service token may reach ONLY the
+  // publish surface. Reads matter too — user pages render live invite links, so a leaked CI
+  // credential must not be able to browse the back office.
+  const serviceAllowed = new Set([
+    "/admin/builds/upload",
+    "/admin/builds/register",
+    "/admin/publish-info",
+  ]);
+  app.use("*", async (c, next) => {
+    const actor = c.get("actor");
+    if (actor.kind === "service" && !serviceAllowed.has(new URL(c.req.url).pathname)) {
+      return c.text("Forbidden — service tokens may only publish (decision 0006)", 403);
+    }
+    await next();
+  });
+
+  // The deploy output and onboarding hand out the bare admin origin — route it home instead of 404.
+  app.get("/", (c) => c.redirect("/admin", 302));
+
+  app.get("/admin", dashboardView);
+  app.get("/admin/users", usersView);
+  app.get("/admin/users/:id", userManageView);
+  app.get("/admin/builds", buildsView);
+  app.get("/admin/builds/:id", buildManageView);
+  app.get("/admin/streams", streamsView);
+  app.get("/admin/streams/:id", streamManageView);
+  app.get("/admin/pending", pendingView);
+  app.get("/admin/upload", uploadView);
+  app.get("/admin/ci", ciView);
+  app.get("/admin/setup", setupView);
+  app.get("/admin/settings", settingsView);
+  app.get("/admin/activity", activityView);
+  app.get("/admin/audit", auditView);
+
+  // Read-only publish helper (service-token allowed, decision 0006): top build + channels + caps,
+  // so a publish script pre-checks locally instead of failing after a full upload.
+  app.get("/admin/publish-info", publishInfo);
+
+  // UI preference (theme toggle) — human only, not audited (no domain change)
+  app.post("/admin/theme", setTheme);
+
+  // Channel mutations (§13). The :id/link and :id/assign batch routes serve the channel page's
+  // multi-select pickers (repeated buildId/clientId fields); both are additive and never strand.
+  app.post("/admin/streams", createStream);
+  app.post("/admin/streams/:id/delete", deleteStream);
+  app.post("/admin/streams/:id/link", linkBuildsToStream);
+  app.post("/admin/streams/:id/assign", assignUsersToStream);
+
+  // Pending access requests (§13 #10)
+  app.post("/admin/pending/:id/invite", invitePending);
+  app.post("/admin/pending/:id/dismiss", dismissPending);
+
+  // Client mutations (§10/§13)
+  app.post("/admin/clients", createClient);
+  app.post("/admin/clients/:id/revoke", revokeClient);
+  app.post("/admin/clients/:id/reactivate", reactivateClient);
+  app.post("/admin/clients/:id/reissue", reissueClient);
+  app.post("/admin/clients/:id/pin", pinClient);
+  app.post("/admin/clients/:id/unpin", unpinClient);
+  app.post("/admin/clients/:id/streams/assign", assignStream);
+  app.post("/admin/clients/:id/streams/unassign", unassignStream);
+  app.post("/admin/clients/:id/hidden", setClientHidden);
+
+  // Publish (§20) — service tokens accepted here only (decision 0006)
+  app.post("/admin/builds/upload", uploadBuild);
+  app.post("/admin/builds/register", registerBuild);
+  // Branding + invite template (§13) — human only
+  app.post("/admin/branding", saveBranding);
+  app.post("/admin/settings/test-email", sendTestEmail);
+
+  // Build mutations (§9/§10/§11). The literal /bulk is mounted before the :id forms (no collision —
+  // distinct paths — but kept adjacent to the per-build mutations it batches).
+  app.post("/admin/builds/bulk", bulkBuilds);
+  app.post("/admin/builds/:id/withdraw", withdrawBuild);
+  app.post("/admin/builds/:id/restore", restoreBuild);
+  app.post("/admin/builds/:id/critical", markCritical);
+  app.post("/admin/builds/:id/rollback", markRollbackTarget);
+  app.post("/admin/builds/:id/hidden", setBuildHidden);
+  app.post("/admin/builds/:id/purge-archive", purgeArchive);
+  app.post("/admin/builds/:id/streams/link", linkBuildStream);
+  app.post("/admin/builds/:id/streams/unlink", unlinkBuildStream);
+
+  app.notFound((c) => c.text("Not found", 404));
+  return app;
+}

package/src/routes/admin/invite.ts

@@ -0,0 +1,57 @@
+import { renderInvite } from "../../core/invite-template";
+import type { Env } from "../../env";
+import { inviteUrl } from "../../lib/hosts";
+import { loadBranding, loadInviteTemplate } from "../../services/branding";
+import { emailStatus } from "../../services/email";
+import type { AdminContext } from "./admin-context";
+
+// Composing + delivering the §13 invite, shared by Add-user (clients) and Invite-request (pending).
+// A delivery failure must NEVER 500 the request: the client row is already written, and the copy-paste
+// link is the always-available fallback. So this catches the send error and reports it for the page to
+// surface, rather than letting it bubble into a bare "Internal Server Error".
+
+export interface Delivery {
+  /** True only when email is configured AND the send succeeded. */
+  sent: boolean;
+  /** The provider's error when a configured send failed (shown to the admin). */
+  error?: string;
+}
+
+/**
+ * Build the invite link, attempt email delivery, and report the outcome. Returns `delivery: undefined`
+ * in copy-paste mode (no email configured, nothing attempted) — callers then just show the link.
+ */
+export interface InviteMessage {
+  subject: string;
+  body: string;
+}
+
+export async function sendInvite(
+  c: AdminContext,
+  to: string,
+  token: string,
+): Promise<{ url: string; delivery?: Delivery | undefined; message: InviteMessage }> {
+  const deps = c.get("deps");
+  const url = inviteUrl(c.req.url, token);
+  const [branding, template] = await Promise.all([loadBranding(deps), loadInviteTemplate(deps)]);
+  const invite = renderInvite(template, { appName: branding.appName, getUrl: url, token });
+
+  // Only report a delivery status when email is actually configured; otherwise the sender is the no-op
+  // (copy-paste) and there is nothing to report. `c.env` is always present at runtime; the guard keeps
+  // this safe if a caller (or test) invokes the app without binding env.
+  const env = c.env as Env | undefined;
+  const configured = env !== undefined && emailStatus(env).mode === "active";
+  const message: InviteMessage = { subject: invite.subject, body: invite.body };
+  try {
+    await deps.email.send({ to, subject: invite.subject, body: invite.body });
+    return { url, delivery: configured ? { sent: true } : undefined, message };
+  } catch (e) {
+    // Surface the full provider error in the Worker logs (`wrangler tail`) — the page only gets .message.
+    console.error("[invite] email send to", to, "failed:", e);
+    return {
+      url,
+      delivery: { sent: false, error: e instanceof Error ? e.message : String(e) },
+      message,
+    };
+  }
+}

package/src/routes/admin/middleware.ts

@@ -0,0 +1,52 @@
+import type { MiddlewareHandler } from "hono";
+import type { AdminContext, AdminEnv } from "./admin-context";
+
+// §4 — the single auth mount for every admin request. Verifies the Access JWT and fails CLOSED (403)
+// on any rejection; the verified actor is attached for downstream authorization and audit.
+//
+// Reason disclosure is careful: when NO JWT header is present, the request never passed edge Access,
+// so we reveal nothing (bare 403 — an attacker probing the origin learns only "denied"). When a JWT
+// IS present but fails verification, the caller already holds a team-issued token, so naming the
+// category (stale AUD after recreating the Access app, expired session, wrong team) turns the most-
+// cited support issue — a mystery 403 the operator debugs via the troubleshooting doc — into a
+// self-explaining page, without leaking anything a token-holder couldn't already infer.
+export const adminAuth: MiddlewareHandler<AdminEnv> = async (c, next) => {
+  const result = await c.get("deps").access.verify(c.req.raw.headers);
+  if (result.kind === "reject") {
+    const presented = c.req.raw.headers.has("Cf-Access-Jwt-Assertion");
+    if (!presented) return c.text("Forbidden", 403);
+    return c.text(rejectionHelp(result.reason), 403);
+  }
+  c.set("actor", result);
+  await next();
+};
+
+/** A short operator-facing explanation + fix for a verification failure, keyed off its reason. */
+function rejectionHelp(reason: string): string {
+  const r = reason.toLowerCase();
+  const fix =
+    "Re-run: ./deploy/deploy.sh --instance <slug> --access-team-domain <team> --access-aud <aud>";
+  if (r.includes("aud")) {
+    return `Access rejected: the token's audience doesn't match this Worker's configured AUD. This usually means the Access application was deleted and recreated (new AUD). ${fix}`;
+  }
+  if (r.includes("iss") || r.includes("team")) {
+    return `Access rejected: the token's issuer doesn't match the configured team domain — likely a renamed Zero Trust team. ${fix.replace("<aud>", "<same aud>")}`;
+  }
+  if (r.includes("exp") || r.includes("expired")) {
+    return "Access rejected: your session token expired. Reload this page to get a fresh one.";
+  }
+  if (r.includes("secret") || r.includes("unset") || r.includes("not configured")) {
+    return `Access rejected: this admin Worker has no Access secrets set, so it fails closed. ${fix}`;
+  }
+  return `Access rejected (${reason}). If the Access application was recently changed, re-wire it: ${fix}`;
+}
+
+/**
+ * Restricts a route to a human admin (email JWT), rejecting service tokens. Mutation handlers call
+ * this; only build upload/register (M15) accept a service token (decision 0006 — bounds a leaked CI
+ * credential to publishing). Returns the actor email, or null if a service token must be refused.
+ */
+export function requireUser(c: AdminContext): { email: string } | null {
+  const actor = c.get("actor");
+  return actor.kind === "user" ? { email: actor.email } : null;
+}

package/src/routes/admin/negotiate.ts

@@ -0,0 +1,13 @@
+import type { AdminContext } from "./admin-context";
+
+// Content negotiation for the dual-audience admin POSTs. Build upload/register accept BOTH a human
+// admin and a CI service token (decision 0006), so a single response shape can't serve both: a browser
+// form submit should land on a real page, while a CI client must keep getting machine JSON.
+//
+// Rule: HTML only for a human actor whose request accepts text/html. So a service token (CI) always
+// gets JSON, and a human hitting the API with `Accept: application/json` still gets JSON — only an
+// actual browser form post (user JWT + `Accept: text/html`) is rendered as a page.
+export function wantsHtml(c: AdminContext): boolean {
+  if (c.get("actor").kind !== "user") return false;
+  return (c.req.header("accept") ?? "").includes("text/html");
+}

package/src/routes/admin/pending.tsx

@@ -0,0 +1,73 @@
+import { generateToken } from "../../core/tokens";
+import * as accessRequests from "../../db/access-requests";
+import * as clients from "../../db/clients";
+import { recordAudit } from "../../services/audit";
+import { InvitePage } from "../../views/admin/manage-pages";
+import { renderPage } from "../../views/layout";
+import type { AdminContext } from "./admin-context";
+import { auditFields } from "./audit-fields";
+import { doneRedirect } from "./flash";
+import { toId } from "./form";
+import { sendInvite } from "./invite";
+import { requireUser } from "./middleware";
+
+// §13 #10 — acting on a pending access request: invite (reissue an existing client by email, or
+// create a new one) and show the /get link, or dismiss. Human-only. Both resolve EVERY pending row
+// for the email, not just the clicked one — duplicates are the norm in copy-paste mode, and a stale
+// sibling's Invite button would otherwise silently rotate the token that was just sent.
+
+export async function invitePending(c: AdminContext): Promise<Response> {
+  if (requireUser(c) === null) return c.text("Forbidden", 403);
+  const deps = c.get("deps");
+  const id = toId(c.req.param("id"));
+  if (id === null) return c.text("Bad request", 400);
+  const request = await accessRequests.getById(deps.db, id);
+  if (request === null) return c.text("Not found", 404);
+
+  const token = generateToken();
+  const existing = await clients.findByEmail(deps.db, request.email);
+  const restored = existing !== null && existing.status !== "active";
+  if (existing !== null) {
+    // Re-grant to an existing client (the revoked-user re-access path, §12). Reissue the token AND
+    // re-activate — without flipping status back to "active" a revoked re-requester's new /get link is
+    // dead on arrival (every public route gates on kind === "active").
+    await clients.setToken(deps.db, existing.id, token);
+    if (restored) {
+      await clients.setStatus(deps.db, existing.id, "active");
+      await recordAudit(deps, auditFields(c, "client.reactivate", request.email));
+    }
+  } else {
+    await clients.insert(deps.db, { email: request.email, token });
+  }
+  await accessRequests.setStatusByEmail(deps.db, request.email, "handled");
+  await recordAudit(deps, auditFields(c, "request.invite", request.email));
+
+  // Delivery never throws: a failed send still returns the link (the copy-paste fallback) with a notice.
+  const { url, delivery, message } = await sendInvite(c, request.email, token);
+  return c.html(
+    renderPage(
+      <InvitePage
+        email={request.email}
+        getUrl={url}
+        delivery={delivery}
+        message={message}
+        restored={restored}
+      />,
+    ),
+  );
+}
+
+export async function dismissPending(c: AdminContext): Promise<Response> {
+  if (requireUser(c) === null) return c.text("Forbidden", 403);
+  const deps = c.get("deps");
+  const body = await c.req.parseBody();
+  const id = toId(c.req.param("id"));
+  if (id === null) return c.text("Bad request", 400);
+
+  const request = await accessRequests.getById(deps.db, id);
+  if (request === null) return c.text("Not found", 404); // no phantom audit rows for stale clicks
+
+  await accessRequests.setStatusByEmail(deps.db, request.email, "dismissed");
+  await recordAudit(deps, auditFields(c, "request.dismiss", request.email));
+  return doneRedirect(c, body, "/admin/pending", "request.dismissed", request.email);
+}