alpha-gate 0.1.0

package/src/core/no-build.ts

@@ -0,0 +1,160 @@
+import { resolve } from "./resolver";
+import type { Build, BuildStreamLink, Client, ResolverResult, UserStreamLink } from "./types";
+
+// §11 — servability and the no-build state, sharing the §8 resolver so the confirmation preview and
+// runtime resolution can never disagree (a bug here would silently strand users). Pure over plain
+// data; the installed-build numbers come from the access log (the impure source is the caller's).
+
+/** The relational slice the §11 computations operate on. */
+export interface World {
+  clients: readonly Client[];
+  builds: readonly Build[];
+  buildStreams: readonly BuildStreamLink[];
+  userStreams: readonly UserStreamLink[];
+}
+
+/** A proposed admin mutation whose blast radius §11 wants computed before it is applied. */
+export type AdminAction =
+  | { type: "withdraw-build"; buildId: number }
+  | { type: "restore-build"; buildId: number }
+  | { type: "remove-build-from-stream"; buildId: number; streamId: number }
+  | { type: "unassign-user-stream"; clientId: number; streamId: number }
+  | { type: "pin-client"; clientId: number; buildId: number }
+  | { type: "unpin-client"; clientId: number }
+  | { type: "delete-stream"; streamId: number };
+
+export type NoBuildState = "servable" | "empty" | "stranded";
+
+/** The /appcast notion of servable: the resolver yields a target. Sparkle enforces no-downgrade itself. */
+export function isServableResult(result: ResolverResult): boolean {
+  return result.kind === "target";
+}
+
+export function resolveForClient(world: World, client: Client): ResolverResult {
+  const clientStreamIds = world.userStreams
+    .filter((link) => link.clientId === client.id)
+    .map((link) => link.streamId);
+  return resolve({
+    client,
+    builds: world.builds,
+    buildStreams: world.buildStreams,
+    clientStreamIds,
+  });
+}
+
+/**
+ * The §13 admin-surface notion, which accounts for no-downgrade using the client's last-reported
+ * installed build (or null if unknown):
+ * - `servable`  — the resolver yields a target the client can actually be on (≥ installed).
+ * - `stranded`  — the client is on a withdrawn build and the resolver can't move them higher (§11).
+ * - `empty`     — no usable build otherwise (no streams/builds, or pinned to a withdrawn build).
+ */
+export function noBuildState(
+  world: World,
+  client: Client,
+  installedBuildNumber: number | null,
+): NoBuildState {
+  const result = resolveForClient(world, client);
+  const target = result.kind === "target" ? result.build : null;
+
+  const servable =
+    target !== null &&
+    (installedBuildNumber === null || target.buildNumber >= installedBuildNumber);
+  if (servable) return "servable";
+
+  // §11 files "pinned to a now-withdrawn build" under EMPTY — the pin is the cause, so classify as
+  // empty regardless of the installed build. Must precede the stranded (stream no-downgrade) check.
+  if (client.pinnedBuildId !== null) {
+    const pinned = world.builds.find((build) => build.id === client.pinnedBuildId);
+    if (pinned === undefined || pinned.status !== "available") return "empty";
+  }
+
+  const onWithdrawnBuild =
+    installedBuildNumber !== null &&
+    world.builds.some(
+      (build) => build.buildNumber === installedBuildNumber && build.status === "withdrawn",
+    );
+  return onWithdrawnBuild ? "stranded" : "empty";
+}
+
+/**
+ * The emails of clients who are servable now but would fall into the no-build state if the batch of
+ * `actions` were applied together. §11: such actions are confirmed, not blocked — the §13 #3 bulk
+ * withdraw shows the union of everyone the whole selection would strand, so the operator confirms
+ * once for the lot (single actions pass a one-element batch).
+ */
+export function computeAffectedUsersForActions(
+  world: World,
+  actions: readonly AdminAction[],
+  installed: ReadonlyMap<number, number> = new Map(),
+): string[] {
+  const after = applyActions(world, actions);
+  const affected: string[] = [];
+
+  for (const client of world.clients) {
+    const installedBuildNumber = installed.get(client.id) ?? null;
+    if (noBuildState(world, client, installedBuildNumber) !== "servable") continue;
+
+    const clientAfter = after.clients.find((candidate) => candidate.id === client.id) ?? client;
+    if (noBuildState(after, clientAfter, installedBuildNumber) !== "servable") {
+      affected.push(client.email);
+    }
+  }
+  return affected;
+}
+
+/** Fold a sequence of actions into the world (the bulk operations apply several at once). */
+function applyActions(world: World, actions: readonly AdminAction[]): World {
+  return actions.reduce(applyAction, world);
+}
+
+/** Pure transform: a new World with `action` applied. */
+function applyAction(world: World, action: AdminAction): World {
+  switch (action.type) {
+    case "withdraw-build":
+      return { ...world, builds: withBuildStatus(world.builds, action.buildId, "withdrawn") };
+    case "restore-build":
+      return { ...world, builds: withBuildStatus(world.builds, action.buildId, "available") };
+    case "remove-build-from-stream":
+      return {
+        ...world,
+        buildStreams: world.buildStreams.filter(
+          (link) => !(link.buildId === action.buildId && link.streamId === action.streamId),
+        ),
+      };
+    case "unassign-user-stream":
+      return {
+        ...world,
+        userStreams: world.userStreams.filter(
+          (link) => !(link.clientId === action.clientId && link.streamId === action.streamId),
+        ),
+      };
+    case "pin-client":
+      return { ...world, clients: withPin(world.clients, action.clientId, action.buildId) };
+    case "unpin-client":
+      return { ...world, clients: withPin(world.clients, action.clientId, null) };
+    case "delete-stream":
+      // The channel and all its assignments/links vanish: builds leave it, users are unassigned.
+      return {
+        ...world,
+        buildStreams: world.buildStreams.filter((link) => link.streamId !== action.streamId),
+        userStreams: world.userStreams.filter((link) => link.streamId !== action.streamId),
+      };
+  }
+}
+
+function withBuildStatus(
+  builds: readonly Build[],
+  buildId: number,
+  status: Build["status"],
+): Build[] {
+  return builds.map((build) => (build.id === buildId ? { ...build, status } : build));
+}
+
+function withPin(
+  clients: readonly Client[],
+  clientId: number,
+  pinnedBuildId: number | null,
+): Client[] {
+  return clients.map((client) => (client.id === clientId ? { ...client, pinnedBuildId } : client));
+}

package/src/core/resolver.ts

@@ -0,0 +1,60 @@
+import type { Build, BuildStreamLink, Client, ResolverResult } from "./types";
+
+// §8 — the core resolver. Pure: given a client (or null for an unknown token), the builds, the
+// build→stream links, and the client's stream assignments, decide what to serve. The single source
+// of truth behind /appcast, the /download target, and the §11 no-build preview, so the confirmation
+// preview and runtime resolution can never disagree.
+
+export interface ResolveInput {
+  /** The client for the token, or null when the token matched no row (§3/§15). */
+  client: Client | null;
+  /** Candidate builds (the resolver filters by status and stream membership). */
+  builds: readonly Build[];
+  /** build_streams rows for the candidate builds. */
+  buildStreams: readonly BuildStreamLink[];
+  /** The stream ids this client is assigned to (their user_streams rows). */
+  clientStreamIds: readonly number[];
+}
+
+export type { ResolverResult } from "./types";
+
+export function resolve(input: ResolveInput): ResolverResult {
+  const { client, builds, buildStreams, clientStreamIds } = input;
+
+  // 1. Unknown or revoked → an informational notice, never a target (§8.1, §15).
+  if (client === null) return { kind: "informational", reason: "unknown" };
+  if (client.status === "revoked") return { kind: "informational", reason: "revoked" };
+
+  // 2. A pin overrides stream resolution entirely (§8.2). If the pinned build is unavailable
+  //    (withdrawn or gone) the client is no-build — it does NOT fall back to streams (§11).
+  if (client.pinnedBuildId !== null) {
+    const pinned = builds.find((build) => build.id === client.pinnedBuildId);
+    if (pinned !== undefined && pinned.status === "available") {
+      return { kind: "target", build: pinned };
+    }
+    return { kind: "none" };
+  }
+
+  // 3. Otherwise: the highest available build_number across the client's streams (§8.3).
+  const target = highestAvailableInStreams(builds, buildStreams, clientStreamIds);
+  return target === null ? { kind: "none" } : { kind: "target", build: target };
+}
+
+function highestAvailableInStreams(
+  builds: readonly Build[],
+  buildStreams: readonly BuildStreamLink[],
+  clientStreamIds: readonly number[],
+): Build | null {
+  const clientStreams = new Set(clientStreamIds);
+  const buildIdsInClientStreams = new Set(
+    buildStreams.filter((link) => clientStreams.has(link.streamId)).map((link) => link.buildId),
+  );
+
+  let best: Build | null = null;
+  for (const build of builds) {
+    if (build.status !== "available") continue;
+    if (!buildIdsInClientStreams.has(build.id)) continue;
+    if (best === null || build.buildNumber > best.buildNumber) best = build;
+  }
+  return best;
+}

package/src/core/tokens.ts

@@ -0,0 +1,51 @@
+// Per-user access tokens (decision 0002). The sole credential: it travels in URLs and is hand-pasted
+// into the macOS app on first launch, so it uses an unambiguous, case-insensitive Crockford base32
+// alphabet and ≥160 bits of entropy. This module is the single source of truth for token shape.
+
+const CROCKFORD_ALPHABET = "0123456789ABCDEFGHJKMNPQRSTVWXYZ"; // 32 symbols — no I, L, O, U
+const TOKEN_BYTES = 20; // 160 bits of entropy
+const TOKEN_LENGTH = 32; // 160 bits / 5 bits-per-symbol, exact (no padding)
+
+/** A fresh, well-formed, already-normalized token. */
+export function generateToken(): string {
+  const bytes = crypto.getRandomValues(new Uint8Array(TOKEN_BYTES));
+  return encodeCrockford(bytes);
+}
+
+/**
+ * Canonical form for lookup: forgiving of case, whitespace/hyphens, and the Crockford confusables
+ * (O→0, I/L→1) so a human paste still matches. Idempotent.
+ */
+export function normalizeToken(raw: string): string {
+  return raw
+    .replace(/[\s-]+/g, "")
+    .toUpperCase()
+    .replace(/O/g, "0")
+    .replace(/[IL]/g, "1");
+}
+
+/** Defensive guard run before any DB lookup: exactly 32 chars, all in the Crockford alphabet. */
+export function isWellFormedToken(raw: string): boolean {
+  const normalized = normalizeToken(raw);
+  if (normalized.length !== TOKEN_LENGTH) return false;
+  for (const ch of normalized) {
+    if (!CROCKFORD_ALPHABET.includes(ch)) return false;
+  }
+  return true;
+}
+
+function encodeCrockford(bytes: Uint8Array): string {
+  let value = 0;
+  let bits = 0;
+  let out = "";
+  for (const byte of bytes) {
+    value = (value << 8) | byte;
+    bits += 8;
+    while (bits >= 5) {
+      bits -= 5;
+      out += CROCKFORD_ALPHABET.charAt((value >>> bits) & 31);
+    }
+  }
+  // 160 bits is a multiple of 5, so there is never a trailing remainder for our fixed size.
+  return out;
+}

package/src/core/types.ts

@@ -0,0 +1,76 @@
+// Shared domain vocabulary — plain data the pure core operates on. The db/ layer maps snake_case D1
+// rows onto these camelCase shapes; the core never sees a binding.
+
+export type ClientStatus = "active" | "revoked";
+export type BuildStatus = "available" | "withdrawn";
+export type AccessEvent = "check" | "download" | "update";
+
+export interface Client {
+  id: number;
+  email: string;
+  token: string;
+  status: ClientStatus;
+  /** Overrides stream resolution when set and the build is available (§8). */
+  pinnedBuildId: number | null;
+  label: string | null;
+  /** Admin-list visibility only (declutter); does NOT affect resolution/serving. */
+  hidden: boolean;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface Build {
+  id: number;
+  /** Human version, e.g. "1.4.0". */
+  shortVersion: string;
+  /** Machine CFBundleVersion — monotonic, the value Sparkle compares (§8). */
+  buildNumber: number;
+  /** R2 key of the EdDSA-signed .app zip (the Sparkle enclosure). */
+  objectKey: string;
+  edSignature: string;
+  /** Byte length of the signed zip (the enclosure length). */
+  length: number;
+  minOs: string | null;
+  critical: boolean;
+  /** §9/§13 operator marker: a designated rollback (roll-forward) target. Label only — see §9. */
+  rollbackTarget: boolean;
+  status: BuildStatus;
+  /** Admin-list visibility only (declutter); does NOT affect resolution/serving. */
+  hidden: boolean;
+  /** Optional first-install DMG (decision 0003); no EdDSA — notarization seals it. */
+  dmgObjectKey: string | null;
+  dmgLength: number | null;
+  /** When the R2 archive bytes were deleted to reclaim space (the row is kept). Null = present. */
+  purgedAt: string | null;
+  createdAt: string;
+}
+
+export interface Stream {
+  id: number;
+  name: string;
+}
+
+/** A build_streams row: which stream a build belongs to. */
+export interface BuildStreamLink {
+  buildId: number;
+  streamId: number;
+}
+
+/** A user_streams row: which stream a client is assigned to. */
+export interface UserStreamLink {
+  clientId: number;
+  streamId: number;
+}
+
+/**
+ * Outcome of resolving what a client should be served (§8). The single source of truth behind the
+ * appcast, the /download target, and the §11 no-build preview.
+ *
+ * `none` means "no build to serve" — the empty-vs-stranded distinction (§11) is a separate
+ * classification (core/no-build) because it needs the client's last-reported installed build, which
+ * §8 resolution never uses.
+ */
+export type ResolverResult =
+  | { kind: "target"; build: Build }
+  | { kind: "informational"; reason: "revoked" | "unknown" }
+  | { kind: "none" };

package/src/core/validation.ts

@@ -0,0 +1,60 @@
+import { type AdminAction, computeAffectedUsersForActions, type World } from "./no-build";
+
+// §11 — pre-mutation validation. Actions that would strand users are confirmed, not blocked: the
+// caller computes the affected set up front, shows it, and proceeds only on confirm. This module also
+// guards malformed params defensively, since the action is built from untrusted form/HTTP input.
+
+export type ValidationResult =
+  | { ok: false; error: string }
+  | { ok: true; needsConfirm: boolean; affectedEmails: string[] };
+
+export function validateAction(
+  world: World,
+  action: AdminAction,
+  installed?: ReadonlyMap<number, number>,
+): ValidationResult {
+  return validateActions(world, [action], installed);
+}
+
+/** Validate a batch applied together (§13 #3 bulk withdraw): one combined confirm for the selection. */
+export function validateActions(
+  world: World,
+  actions: readonly AdminAction[],
+  installed?: ReadonlyMap<number, number>,
+): ValidationResult {
+  for (const action of actions) {
+    const guardError = guardAction(action);
+    if (guardError !== null) return { ok: false, error: guardError };
+  }
+  const affectedEmails = computeAffectedUsersForActions(world, actions, installed);
+  return { ok: true, needsConfirm: affectedEmails.length > 0, affectedEmails };
+}
+
+/** Returns an error message if the action's id params are not positive integers, else null. */
+function guardAction(action: AdminAction): string | null {
+  switch (action.type) {
+    case "withdraw-build":
+    case "restore-build":
+      return isPositiveInt(action.buildId) ? null : "buildId must be a positive integer";
+    case "remove-build-from-stream":
+      return isPositiveInt(action.buildId) && isPositiveInt(action.streamId)
+        ? null
+        : "buildId and streamId must be positive integers";
+    case "unassign-user-stream":
+      return isPositiveInt(action.clientId) && isPositiveInt(action.streamId)
+        ? null
+        : "clientId and streamId must be positive integers";
+    case "pin-client":
+      return isPositiveInt(action.clientId) && isPositiveInt(action.buildId)
+        ? null
+        : "clientId and buildId must be positive integers";
+    case "unpin-client":
+      return isPositiveInt(action.clientId) ? null : "clientId must be a positive integer";
+    case "delete-stream":
+      return isPositiveInt(action.streamId) ? null : "streamId must be a positive integer";
+  }
+}
+
+function isPositiveInt(value: unknown): value is number {
+  return typeof value === "number" && Number.isInteger(value) && value > 0;
+}

package/src/core/verdict.ts

@@ -0,0 +1,195 @@
+import type { World } from "./no-build";
+import type { Build, Client } from "./types";
+
+// The display-grade answer to "what does this user's NEXT update check actually do?" — the §8
+// resolver's outcome refined with the user's last-reported installed build and the no-downgrade rule,
+// classified by CAUSE so every page can say not just "no build" but why, and what fixes it. Pure over
+// plain data (§23): the same World the runtime resolver uses, no bindings, no clock.
+
+export type Verdict =
+  /** The next check offers this build (installed is below it, or nothing installed yet). */
+  | { kind: "offered"; build: Build; via: "pin" | "channel" }
+  /** The resolver targets exactly what is installed — Sparkle reports "up to date". */
+  | { kind: "up-to-date"; build: Build; via: "pin" | "channel" }
+  /** Revoked: every check returns the reactivation notice, never a build. */
+  | { kind: "revoked" }
+  /** Active but assigned to no channel (and unpinned) — resolves to nothing, always. */
+  | { kind: "no-channel" }
+  /** Channels are assigned but none carries an available build. */
+  | { kind: "empty-channel" }
+  /** Pinned to a build that is withdrawn or gone — the pin serves nothing. */
+  | { kind: "pin-unavailable"; pinnedBuildId: number }
+  /** Pinned below the installed build — Sparkle won't downgrade, so the pin serves nothing. */
+  | { kind: "pin-below-installed"; pinned: Build; installed: number }
+  /** Installed sits above everything the channels offer — stranded under no-downgrade (§11). */
+  | { kind: "stranded"; installed: number; top: Build };
+
+/** True when the verdict means the user's feed is empty/faulted (the amber states). */
+export function isFault(verdict: Verdict): boolean {
+  return verdict.kind !== "offered" && verdict.kind !== "up-to-date" && verdict.kind !== "revoked";
+}
+
+export function verdictFor(
+  world: World,
+  client: Client,
+  installedBuildNumber: number | null,
+): Verdict {
+  if (client.status === "revoked") return { kind: "revoked" };
+
+  // A pin overrides channel resolution entirely (§8.2) — and never falls back.
+  if (client.pinnedBuildId !== null) {
+    const pinned = world.builds.find((build) => build.id === client.pinnedBuildId);
+    if (pinned === undefined || pinned.status !== "available") {
+      return { kind: "pin-unavailable", pinnedBuildId: client.pinnedBuildId };
+    }
+    if (installedBuildNumber !== null && pinned.buildNumber < installedBuildNumber) {
+      return { kind: "pin-below-installed", pinned, installed: installedBuildNumber };
+    }
+    if (installedBuildNumber !== null && pinned.buildNumber === installedBuildNumber) {
+      return { kind: "up-to-date", build: pinned, via: "pin" };
+    }
+    return { kind: "offered", build: pinned, via: "pin" };
+  }
+
+  const streamIds = new Set(
+    world.userStreams.filter((link) => link.clientId === client.id).map((link) => link.streamId),
+  );
+  if (streamIds.size === 0) return { kind: "no-channel" };
+
+  const buildIds = new Set(
+    world.buildStreams.filter((link) => streamIds.has(link.streamId)).map((link) => link.buildId),
+  );
+  let top: Build | null = null;
+  for (const build of world.builds) {
+    if (build.status !== "available" || !buildIds.has(build.id)) continue;
+    if (top === null || build.buildNumber > top.buildNumber) top = build;
+  }
+  if (top === null) return { kind: "empty-channel" };
+
+  if (installedBuildNumber === null || top.buildNumber > installedBuildNumber) {
+    return { kind: "offered", build: top, via: "channel" };
+  }
+  if (top.buildNumber === installedBuildNumber) {
+    return { kind: "up-to-date", build: top, via: "channel" };
+  }
+  return { kind: "stranded", installed: installedBuildNumber, top };
+}
+
+/** One serving-map row: what a channel offers and how its audience actually fares. */
+export interface ChannelServing {
+  streamId: number;
+  name: string;
+  /** Highest available linked build — what the channel offers (§8) — or null (serving nothing). */
+  top: Build | null;
+  /** Active users assigned to the channel (revoked users are not counted as audience). */
+  users: number;
+  /** Users whose next check will move them (verdict: offered). */
+  willUpdate: number;
+  /** Users already at the channel's head (or held at an equal pin). */
+  upToDate: number;
+  /** Users whose feed is empty while assigned here — stranded, pin faults (the amber count). */
+  faulted: number;
+  /** Users held elsewhere by a pin (their pin overrides this channel). */
+  pinned: number;
+}
+
+/**
+ * The dashboard serving map, computed from the same World as runtime resolution — one row per
+ * channel plus the audience math per user verdict. `installed` maps client id → last-reported build.
+ */
+export function channelServings(
+  world: World,
+  streams: readonly { id: number; name: string }[],
+  installed: ReadonlyMap<number, number>,
+): ChannelServing[] {
+  return streams.map((stream) => {
+    const buildIds = new Set(
+      world.buildStreams.filter((l) => l.streamId === stream.id).map((l) => l.buildId),
+    );
+    let top: Build | null = null;
+    for (const build of world.builds) {
+      if (build.status !== "available" || !buildIds.has(build.id)) continue;
+      if (top === null || build.buildNumber > top.buildNumber) top = build;
+    }
+
+    const memberIds = new Set(
+      world.userStreams.filter((l) => l.streamId === stream.id).map((l) => l.clientId),
+    );
+    let users = 0;
+    let willUpdate = 0;
+    let upToDate = 0;
+    let faulted = 0;
+    let pinned = 0;
+    for (const client of world.clients) {
+      if (!memberIds.has(client.id) || client.status !== "active") continue;
+      users++;
+      const verdict = verdictFor(world, client, installed.get(client.id) ?? null);
+      if (client.pinnedBuildId !== null) pinned++;
+      if (verdict.kind === "offered") willUpdate++;
+      else if (verdict.kind === "up-to-date") upToDate++;
+      else faulted++;
+    }
+    return {
+      streamId: stream.id,
+      name: stream.name,
+      top,
+      users,
+      willUpdate,
+      upToDate,
+      faulted,
+      pinned,
+    };
+  });
+}
+
+/** Active users assigned to NO channel and not pinned — routed nowhere; the map's "off the map" row. */
+export function offTheMap(world: World): Client[] {
+  const assigned = new Set(world.userStreams.map((link) => link.clientId));
+  return world.clients.filter(
+    (client) =>
+      client.status === "active" && !assigned.has(client.id) && client.pinnedBuildId === null,
+  );
+}
+
+const MONTHS = [
+  "Jan",
+  "Feb",
+  "Mar",
+  "Apr",
+  "May",
+  "Jun",
+  "Jul",
+  "Aug",
+  "Sep",
+  "Oct",
+  "Nov",
+  "Dec",
+] as const;
+
+/**
+ * "Jul 09 08:30" from an ISO-8601 string — the UI's one timestamp form (full ISO stays in the
+ * element's title). Pure string slicing, no Date (lib/clock owns time). Adds the year only when it
+ * differs from `nowIso`'s. Returns the input unchanged when it doesn't look like an ISO timestamp.
+ */
+export function formatWhen(iso: string, nowIso: string): string {
+  const m = /^(\d{4})-(\d{2})-(\d{2})[T ](\d{2}):(\d{2})/.exec(iso);
+  if (m === null) return iso;
+  const [, year, month, day, hh, mm] = m;
+  const monthName = MONTHS[Number(month) - 1] ?? month;
+  const sameYear = nowIso.startsWith(`${year}-`);
+  return `${monthName} ${day} ${hh}:${mm}${sameYear ? "" : ` ${year}`}`;
+}
+
+/** "84.2 MB" from bytes — exact count belongs in the title attribute. */
+export function formatBytes(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  const units = ["KB", "MB", "GB"] as const;
+  let value = bytes;
+  let unit = "B";
+  for (const next of units) {
+    if (value < 1024) break;
+    value /= 1024;
+    unit = next;
+  }
+  return `${value >= 100 ? Math.round(value) : Math.round(value * 10) / 10} ${unit}`;
+}