alpha-gate 0.1.0

package/src/core/version.ts

@@ -0,0 +1,113 @@
+// §22 self-update version logic. Pure: the manifest is passed in (the fetch lives in
+// services/self-update). The manifest is untrusted input from an upstream URL, so isUpdateAvailable
+// is defensive — it never throws and defaults to "no update" on anything malformed.
+//
+// Two manifest shapes are accepted so the check works against the npm registry OR a static file:
+//   - npm's registry `/latest` endpoint returns the published package.json: { version, homepage,
+//     alphaGate? }. The upgrade signals (breaking / min-supported / notes) ride in a custom
+//     `alphaGate` field, which npm preserves in the version manifest.
+//   - the legacy static release.json: { latest, min_supported, notes_url, breaking }.
+
+/** The upstream release manifest — either npm's `/latest` response or a static release.json. */
+export interface UpdateManifest {
+  /** Static release.json: the latest version string. */
+  latest?: string;
+  /** npm registry `/latest`: the published version. */
+  version?: string;
+  min_supported?: string;
+  notes_url?: string;
+  breaking?: boolean;
+  /** npm package.json `homepage` — a notes-URL fallback for the npm channel. */
+  homepage?: string;
+  /** Upgrade signals carried through npm (a custom package.json field npm preserves). */
+  alphaGate?: {
+    minSupported?: string;
+    breaking?: boolean;
+    notesUrl?: string;
+  };
+}
+
+export interface UpdateStatus {
+  available: boolean;
+  breaking: boolean;
+  belowMinSupported: boolean;
+  latest: string | null;
+  notesUrl: string | null;
+}
+
+interface ParsedVersion {
+  core: number[];
+  prerelease: string | null;
+}
+
+function parse(version: string): ParsedVersion {
+  const cleaned = version.trim().replace(/^v/i, "");
+  const dash = cleaned.indexOf("-");
+  const core = dash === -1 ? cleaned : cleaned.slice(0, dash);
+  const prerelease = dash === -1 ? null : cleaned.slice(dash + 1);
+  const segments = core.split(".").map((part) => {
+    const n = Number.parseInt(part, 10);
+    return Number.isFinite(n) ? n : 0;
+  });
+  return { core: segments, prerelease };
+}
+
+/** Returns <0, 0, or >0 (semver-ish; numeric segments, missing treated as 0, prerelease < release). */
+export function compareVersion(a: string, b: string): number {
+  const pa = parse(a);
+  const pb = parse(b);
+
+  const length = Math.max(pa.core.length, pb.core.length);
+  for (let i = 0; i < length; i++) {
+    const diff = (pa.core[i] ?? 0) - (pb.core[i] ?? 0);
+    if (diff !== 0) return diff < 0 ? -1 : 1;
+  }
+
+  // Equal core: a release outranks a prerelease of the same core; otherwise compare the tags.
+  if (pa.prerelease === pb.prerelease) return 0;
+  if (pa.prerelease === null) return 1;
+  if (pb.prerelease === null) return -1;
+  if (pa.prerelease < pb.prerelease) return -1;
+  if (pa.prerelease > pb.prerelease) return 1;
+  return 0;
+}
+
+export function isUpdateAvailable(toolVersion: string, manifest: UpdateManifest): UpdateStatus {
+  const noUpdate: UpdateStatus = {
+    available: false,
+    breaking: false,
+    belowMinSupported: false,
+    latest: null,
+    notesUrl: null,
+  };
+
+  if (typeof manifest !== "object" || manifest === null) return noUpdate;
+  // The latest version: release.json's `latest`, else npm's `version`.
+  const latestRaw = manifest.latest ?? manifest.version;
+  if (typeof latestRaw !== "string" || latestRaw.length === 0) return noUpdate;
+  const latest = latestRaw;
+
+  const ag = manifest.alphaGate;
+  const minSupported =
+    typeof manifest.min_supported === "string"
+      ? manifest.min_supported
+      : typeof ag?.minSupported === "string"
+        ? ag.minSupported
+        : null;
+  const notesUrl =
+    typeof manifest.notes_url === "string"
+      ? manifest.notes_url
+      : typeof ag?.notesUrl === "string"
+        ? ag.notesUrl
+        : typeof manifest.homepage === "string"
+          ? manifest.homepage
+          : null;
+
+  return {
+    available: compareVersion(latest, toolVersion) > 0,
+    breaking: manifest.breaking === true || ag?.breaking === true,
+    belowMinSupported: minSupported !== null && compareVersion(toolVersion, minSupported) < 0,
+    latest,
+    notesUrl,
+  };
+}

package/src/cron.ts

@@ -0,0 +1,37 @@
+import { prune } from "./db/access-log";
+import { buildDeps, type Deps } from "./deps";
+import type { Env } from "./env";
+import { isoDaysAgo } from "./lib/clock";
+import { anchorAudit } from "./services/anchor";
+import { checkSelfUpdate } from "./services/self-update";
+
+// §16/§22 — the daily scheduled job. Only the admin Worker acts; the app Worker shares the cron
+// config but no-ops. Deps is injectable so tests drive it with a mocked fetch / recording email.
+
+const LOG_RETENTION_DAYS = 90;
+
+export async function runScheduled(env: Env, deps: Deps = buildDeps(env)): Promise<void> {
+  if (env.ROLE !== "admin") return; // the app Worker no-ops the shared cron
+
+  const ownerEmail = env.EMAIL_FROM.length > 0 ? env.EMAIL_FROM : null;
+
+  // Each step runs independently — a failure in one (e.g. a transient email/manifest error) must not
+  // skip the others (notably the audit anchor and the retention prune).
+  await safely("self-update", () =>
+    checkSelfUpdate(deps, {
+      toolVersion: env.TOOL_VERSION,
+      manifestUrl: env.UPDATE_MANIFEST_URL,
+      ownerEmail,
+    }),
+  );
+  await safely("audit-anchor", () => anchorAudit(deps, { now: deps.clock(), ownerEmail }));
+  await safely("prune", () => prune(deps.db, isoDaysAgo(LOG_RETENTION_DAYS)));
+}
+
+async function safely(step: string, fn: () => Promise<unknown>): Promise<void> {
+  try {
+    await fn();
+  } catch (error) {
+    console.error(`cron step "${step}" failed`, error);
+  }
+}

package/src/db/access-log.ts

@@ -0,0 +1,168 @@
+import type { AccessEvent } from "../core/types";
+import { execute, queryAll, queryOne } from "./client";
+
+// §5/§16 — the access log: the source of truth for distribution stats (download/update counts,
+// per-user last activity, current version). `created_at` is supplied by the caller's Clock so
+// time-dependent reads (stats, the §16 prune) are deterministic in tests.
+
+export interface NewAccessEvent {
+  clientId: number | null;
+  email: string | null;
+  event: AccessEvent;
+  shortVersion?: string | null;
+  buildNumber?: number | null;
+  ip?: string | null;
+  userAgent?: string | null;
+  createdAt: string;
+}
+
+export async function insertEvent(db: D1Database, entry: NewAccessEvent): Promise<void> {
+  await execute(
+    db,
+    `INSERT INTO access_log
+       (client_id, email, event, short_version, build_number, ip, user_agent, created_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+    [
+      entry.clientId,
+      entry.email,
+      entry.event,
+      entry.shortVersion ?? null,
+      entry.buildNumber ?? null,
+      entry.ip ?? null,
+      entry.userAgent ?? null,
+      entry.createdAt,
+    ],
+  );
+}
+
+/** Per-build count of a given event (e.g. downloads or updates of a build_number). */
+export async function countByBuild(
+  db: D1Database,
+  buildNumber: number,
+  event: AccessEvent,
+): Promise<number> {
+  const row = await queryOne<{ n: number }>(
+    db,
+    "SELECT COUNT(*) AS n FROM access_log WHERE build_number = ? AND event = ?",
+    [buildNumber, event],
+  );
+  return row?.n ?? 0;
+}
+
+/** The most recent time a client produced a given event (per-user "last installed/updated/seen"). */
+export async function lastEventAt(
+  db: D1Database,
+  clientId: number,
+  event: AccessEvent,
+): Promise<string | null> {
+  const row = await queryOne<{ v: string | null }>(
+    db,
+    "SELECT MAX(created_at) AS v FROM access_log WHERE client_id = ? AND event = ?",
+    [clientId, event],
+  );
+  return row?.v ?? null;
+}
+
+/** The most recent time a client produced ANY event — the Users list's "last seen". */
+export async function lastSeenAt(db: D1Database, clientId: number): Promise<string | null> {
+  const row = await queryOne<{ v: string | null }>(
+    db,
+    "SELECT MAX(created_at) AS v FROM access_log WHERE client_id = ?",
+    [clientId],
+  );
+  return row?.v ?? null;
+}
+
+/** The build_number the client reported on its latest `check` — its current installed version. */
+export async function currentBuild(db: D1Database, clientId: number): Promise<number | null> {
+  const row = await queryOne<{ build_number: number | null }>(
+    db,
+    `SELECT build_number FROM access_log
+     WHERE client_id = ? AND event = 'check' AND build_number IS NOT NULL
+     ORDER BY created_at DESC LIMIT 1`,
+    [clientId],
+  );
+  return row?.build_number ?? null;
+}
+
+/** §16 retention prune: delete rows older than `before` (an ISO timestamp). */
+export async function prune(db: D1Database, before: string): Promise<void> {
+  await execute(db, "DELETE FROM access_log WHERE created_at < ?", [before]);
+}
+
+export interface AccessLogEntry {
+  id: number;
+  clientId: number | null;
+  email: string | null;
+  event: AccessEvent;
+  shortVersion: string | null;
+  buildNumber: number | null;
+  createdAt: string;
+}
+
+export interface ActivityFilter {
+  limit?: number;
+  email?: string | undefined;
+  event?: AccessEvent | undefined;
+  buildNumber?: number | undefined;
+}
+
+/** The most recent events, newest first — the §13 activity feed; optionally filtered. */
+export async function recent(
+  db: D1Database,
+  filter: ActivityFilter = {},
+): Promise<AccessLogEntry[]> {
+  const where: string[] = [];
+  const params: unknown[] = [];
+  if (filter.email) {
+    // Contains-match: "alice" should find alice@corner.studio (LIKE is case-insensitive for ASCII).
+    where.push("email LIKE ?");
+    params.push(`%${filter.email.replaceAll("%", "").replaceAll("_", "")}%`);
+  }
+  if (filter.event) {
+    where.push("event = ?");
+    params.push(filter.event);
+  }
+  if (filter.buildNumber !== undefined) {
+    where.push("build_number = ?");
+    params.push(filter.buildNumber);
+  }
+  const clause = where.length > 0 ? `WHERE ${where.join(" AND ")}` : "";
+
+  const rows = await queryAll<{
+    id: number;
+    client_id: number | null;
+    email: string | null;
+    event: string;
+    short_version: string | null;
+    build_number: number | null;
+    created_at: string;
+  }>(
+    db,
+    `SELECT id, client_id, email, event, short_version, build_number, created_at
+     FROM access_log ${clause} ORDER BY id DESC LIMIT ?`,
+    [...params, filter.limit ?? 100],
+  );
+  return rows.map((row) => ({
+    id: row.id,
+    clientId: row.client_id,
+    email: row.email,
+    event: row.event as AccessEvent,
+    shortVersion: row.short_version,
+    buildNumber: row.build_number,
+    createdAt: row.created_at,
+  }));
+}
+
+/** The most recent event time for a build (any event) — the §13 builds-list "last activity". */
+export async function lastActivityForBuild(
+  db: D1Database,
+  buildNumber: number,
+): Promise<string | null> {
+  const row = await queryOne<{ v: string | null }>(
+    db,
+    "SELECT MAX(created_at) AS v FROM access_log WHERE build_number = ?",
+    [buildNumber],
+  );
+  return row?.v ?? null;
+}

package/src/db/access-requests.ts

@@ -0,0 +1,90 @@
+import { execute, queryAll, queryOne } from "./client";
+
+// §13 #10 — pending access requests submitted from the public /access page.
+
+export interface AccessRequest {
+  id: number;
+  email: string;
+  ip: string | null;
+  userAgent: string | null;
+  status: string;
+  createdAt: string;
+}
+
+interface Row {
+  id: number;
+  email: string;
+  ip: string | null;
+  user_agent: string | null;
+  status: string;
+  created_at: string;
+}
+
+function toRequest(row: Row): AccessRequest {
+  return {
+    id: row.id,
+    email: row.email,
+    ip: row.ip,
+    userAgent: row.user_agent,
+    status: row.status,
+    createdAt: row.created_at,
+  };
+}
+
+export interface NewAccessRequest {
+  email: string;
+  ip: string | null;
+  userAgent: string | null;
+  createdAt: string;
+}
+
+export async function insert(db: D1Database, entry: NewAccessRequest): Promise<void> {
+  await execute(
+    db,
+    "INSERT INTO access_requests (email, ip, user_agent, created_at) VALUES (?, ?, ?, ?)",
+    [entry.email, entry.ip, entry.userAgent, entry.createdAt],
+  );
+}
+
+export async function listByStatus(db: D1Database, status = "pending"): Promise<AccessRequest[]> {
+  const rows = await queryAll<Row>(
+    db,
+    "SELECT * FROM access_requests WHERE status = ? ORDER BY id DESC",
+    [status],
+  );
+  return rows.map(toRequest);
+}
+
+export async function getById(db: D1Database, id: number): Promise<AccessRequest | null> {
+  const row = await queryOne<Row>(db, "SELECT * FROM access_requests WHERE id = ?", [id]);
+  return row ? toRequest(row) : null;
+}
+
+export async function setStatus(db: D1Database, id: number, status: string): Promise<void> {
+  await execute(db, "UPDATE access_requests SET status = ? WHERE id = ?", [status, id]);
+}
+
+/**
+ * Resolves EVERY still-pending request for an email at once. Testers re-submit the public form when
+ * no confirmation arrives (copy-paste mode sends none), so duplicates are the norm — handling only
+ * the clicked row would leave stale siblings whose Invite button silently rotates a just-sent token.
+ */
+export async function setStatusByEmail(
+  db: D1Database,
+  email: string,
+  status: string,
+): Promise<void> {
+  await execute(
+    db,
+    "UPDATE access_requests SET status = ? WHERE email = ? AND status = 'pending'",
+    [status, email],
+  );
+}
+
+export async function countPending(db: D1Database): Promise<number> {
+  const row = await queryOne<{ n: number }>(
+    db,
+    "SELECT COUNT(*) AS n FROM access_requests WHERE status = 'pending'",
+  );
+  return row?.n ?? 0;
+}

package/src/db/admin-audit.ts

@@ -0,0 +1,101 @@
+import type { AuditRow } from "../core/audit-chain";
+import { executeWithChanges, queryAll, queryOne } from "./client";
+
+// §16 — admin_audit persistence. Storage only: the hash is computed in core/audit-chain and passed in.
+// appendIfHead is a conditional insert guarded on the chain head being unchanged, so two concurrent
+// writers can't fork the chain (the loser inserts 0 rows and retries — see services/audit.ts).
+
+interface AuditDbRow {
+  id: number;
+  actor_email: string;
+  action: string;
+  target: string | null;
+  detail: string | null;
+  ip: string | null;
+  ray_id: string | null;
+  prev_hash: string | null;
+  hash: string;
+  created_at: string;
+}
+
+function toAuditRow(row: AuditDbRow): AuditRow {
+  return {
+    actorEmail: row.actor_email,
+    action: row.action,
+    target: row.target,
+    detail: row.detail,
+    ip: row.ip,
+    rayId: row.ray_id,
+    prevHash: row.prev_hash,
+    hash: row.hash,
+    createdAt: row.created_at,
+  };
+}
+
+export async function getHead(db: D1Database): Promise<AuditRow | null> {
+  const row = await queryOne<AuditDbRow>(db, "SELECT * FROM admin_audit ORDER BY id DESC LIMIT 1");
+  return row ? toAuditRow(row) : null;
+}
+
+export async function listInOrder(db: D1Database): Promise<AuditRow[]> {
+  const rows = await queryAll<AuditDbRow>(db, "SELECT * FROM admin_audit ORDER BY id");
+  return rows.map(toAuditRow);
+}
+
+export interface AuditFilter {
+  actor?: string | undefined;
+  action?: string | undefined;
+  limit?: number;
+}
+
+/** Newest-first, optionally filtered by actor/action — for the §13 #15 audit page. */
+export async function listForDisplay(
+  db: D1Database,
+  filter: AuditFilter = {},
+): Promise<AuditRow[]> {
+  const where: string[] = [];
+  const params: unknown[] = [];
+  if (filter.actor) {
+    // Contains-match: a partial address is the natural filter input (LIKE is ASCII case-insensitive).
+    where.push("actor_email LIKE ?");
+    params.push(`%${filter.actor.replaceAll("%", "").replaceAll("_", "")}%`);
+  }
+  if (filter.action) {
+    where.push("action = ?");
+    params.push(filter.action);
+  }
+  const clause = where.length > 0 ? `WHERE ${where.join(" AND ")}` : "";
+  const rows = await queryAll<AuditDbRow>(
+    db,
+    `SELECT * FROM admin_audit ${clause} ORDER BY id DESC LIMIT ?`,
+    [...params, filter.limit ?? 200],
+  );
+  return rows.map(toAuditRow);
+}
+
+/** Inserts only if the current head hash still equals expectedHeadHash. Returns whether it inserted. */
+export async function appendIfHead(
+  db: D1Database,
+  row: AuditRow,
+  expectedHeadHash: string | null,
+): Promise<boolean> {
+  const changes = await executeWithChanges(
+    db,
+    `INSERT INTO admin_audit (actor_email, action, target, detail, ip, ray_id, prev_hash, hash, created_at)
+     SELECT ?, ?, ?, ?, ?, ?, ?, ?, ?
+     WHERE COALESCE((SELECT hash FROM admin_audit ORDER BY id DESC LIMIT 1), '') = ?`,
+    [
+      row.actorEmail,
+      row.action,
+      row.target,
+      row.detail,
+      row.ip,
+      row.rayId,
+      row.prevHash,
+      row.hash,
+      row.createdAt,
+      expectedHeadHash ?? "",
+    ],
+  );
+  return changes > 0;
+}

package/src/db/builds.ts

@@ -0,0 +1,169 @@
+import type { Build, BuildStatus, BuildStreamLink } from "../core/types";
+import { execute, queryAll, queryOne } from "./client";
+
+// Raw prepared statements for `builds` and the `build_streams` join. Maps the INTEGER `critical`
+// flag to boolean and the snake_case columns to the Build domain shape.
+
+interface BuildRow {
+  id: number;
+  short_version: string;
+  build_number: number;
+  object_key: string;
+  ed_signature: string;
+  length: number;
+  min_os: string | null;
+  critical: number;
+  rollback_target: number;
+  status: string;
+  hidden: number;
+  dmg_object_key: string | null;
+  dmg_length: number | null;
+  purged_at: string | null;
+  created_at: string;
+}
+
+function toBuild(row: BuildRow): Build {
+  return {
+    id: row.id,
+    shortVersion: row.short_version,
+    buildNumber: row.build_number,
+    objectKey: row.object_key,
+    edSignature: row.ed_signature,
+    length: row.length,
+    minOs: row.min_os,
+    critical: row.critical !== 0,
+    rollbackTarget: row.rollback_target !== 0,
+    status: row.status as BuildStatus,
+    hidden: row.hidden !== 0,
+    dmgObjectKey: row.dmg_object_key,
+    dmgLength: row.dmg_length,
+    purgedAt: row.purged_at,
+    createdAt: row.created_at,
+  };
+}
+
+export interface NewBuild {
+  shortVersion: string;
+  buildNumber: number;
+  objectKey: string;
+  edSignature: string;
+  length: number;
+  minOs?: string | null;
+  critical?: boolean;
+  dmgObjectKey?: string | null;
+  dmgLength?: number | null;
+}
+
+export async function getById(db: D1Database, id: number): Promise<Build | null> {
+  const row = await queryOne<BuildRow>(db, "SELECT * FROM builds WHERE id = ?", [id]);
+  return row ? toBuild(row) : null;
+}
+
+export async function getByBuildNumber(db: D1Database, buildNumber: number): Promise<Build | null> {
+  const row = await queryOne<BuildRow>(db, "SELECT * FROM builds WHERE build_number = ?", [
+    buildNumber,
+  ]);
+  return row ? toBuild(row) : null;
+}
+
+export async function listAll(db: D1Database): Promise<Build[]> {
+  const rows = await queryAll<BuildRow>(db, "SELECT * FROM builds ORDER BY build_number");
+  return rows.map(toBuild);
+}
+
+export async function listAvailable(db: D1Database): Promise<Build[]> {
+  const rows = await queryAll<BuildRow>(
+    db,
+    "SELECT * FROM builds WHERE status = 'available' ORDER BY build_number",
+  );
+  return rows.map(toBuild);
+}
+
+export async function insert(db: D1Database, input: NewBuild): Promise<Build> {
+  const row = await queryOne<BuildRow>(
+    db,
+    `INSERT INTO builds
+       (short_version, build_number, object_key, ed_signature, length, min_os, critical, dmg_object_key, dmg_length)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+     RETURNING *`,
+    [
+      input.shortVersion,
+      input.buildNumber,
+      input.objectKey,
+      input.edSignature,
+      input.length,
+      input.minOs ?? null,
+      input.critical ? 1 : 0,
+      input.dmgObjectKey ?? null,
+      input.dmgLength ?? null,
+    ],
+  );
+  if (row === null) throw new Error("INSERT builds returned no row");
+  return toBuild(row);
+}
+
+export async function setStatus(db: D1Database, id: number, status: BuildStatus): Promise<void> {
+  await execute(db, "UPDATE builds SET status = ? WHERE id = ?", [status, id]);
+}
+
+/** Admin-list visibility (declutter only; does not affect resolution/serving). */
+export async function setHidden(db: D1Database, id: number, hidden: boolean): Promise<void> {
+  await execute(db, "UPDATE builds SET hidden = ? WHERE id = ?", [hidden ? 1 : 0, id]);
+}
+
+export async function setCritical(db: D1Database, id: number, critical: boolean): Promise<void> {
+  await execute(db, "UPDATE builds SET critical = ? WHERE id = ?", [critical ? 1 : 0, id]);
+}
+
+export async function setRollbackTarget(
+  db: D1Database,
+  id: number,
+  rollbackTarget: boolean,
+): Promise<void> {
+  await execute(db, "UPDATE builds SET rollback_target = ? WHERE id = ?", [
+    rollbackTarget ? 1 : 0,
+    id,
+  ]);
+}
+
+export async function linkStream(db: D1Database, buildId: number, streamId: number): Promise<void> {
+  await execute(db, "INSERT OR IGNORE INTO build_streams (build_id, stream_id) VALUES (?, ?)", [
+    buildId,
+    streamId,
+  ]);
+}
+
+export async function unlinkStream(
+  db: D1Database,
+  buildId: number,
+  streamId: number,
+): Promise<void> {
+  await execute(db, "DELETE FROM build_streams WHERE build_id = ? AND stream_id = ?", [
+    buildId,
+    streamId,
+  ]);
+}
+
+/** Stamp a build's archive as purged (bytes deleted from R2; the row is kept). `at` is the clock. */
+export async function markPurged(db: D1Database, id: number, at: string): Promise<void> {
+  await execute(db, "UPDATE builds SET purged_at = ? WHERE id = ?", [at, id]);
+}
+
+/** The sum of all stored archive bytes (zip + optional DMG) — the Builds page's bucket-total line. */
+export async function totalArchiveBytes(db: D1Database): Promise<number> {
+  const row = await queryOne<{ total: number | null }>(
+    db,
+    "SELECT COALESCE(SUM(length), 0) + COALESCE(SUM(dmg_length), 0) AS total" +
+      " FROM builds WHERE purged_at IS NULL",
+  );
+  return row?.total ?? 0;
+}
+
+/** All build→stream links (the resolver/no-build World input). */
+export async function listBuildStreams(db: D1Database): Promise<BuildStreamLink[]> {
+  const rows = await queryAll<{ build_id: number; stream_id: number }>(
+    db,
+    "SELECT build_id, stream_id FROM build_streams",
+  );
+  return rows.map((row) => ({ buildId: row.build_id, streamId: row.stream_id }));
+}