@augurworks/augur 0.15.1

package/src/tenant-host.mjs

@@ -0,0 +1,144 @@
+// Which workspace a hostname names.
+//
+// `B-resolver-dynamic`. A deployment that serves several workspaces tells them apart by
+// the first label of the Host header — `acme.example.com` is the workspace `acme`. This
+// module is the parsing and the refusing; `resolveTenant()` in src/_worker.js is the one
+// place that calls it, and turning the label into a Durable Object stub is that function's
+// last line.
+//
+// It is a separate module for two reasons. The worker does not need two more module-scope
+// tables in it, and the RESERVED list has a second reader coming: the control plane
+// generates workspace names (`voracious-eel-294`, never user-chosen), and a generator that
+// emits `admin` and a resolver that refuses it are the same list disagreeing. One list,
+// imported twice, is the only arrangement where they cannot drift.
+//
+// EVERYTHING HERE IS A PURE FUNCTION OF A STRING. No env, no fetch, no clock — the
+// resolver runs before any config is read, on every request, and it has to be impossible
+// for it to be the thing that is slow or the thing that fails.
+
+/**
+ * A hostname label a workspace may never be, whatever a generator emits and whatever
+ * already exists.
+ *
+ * These fall into three groups and each is here for its own reason:
+ *
+ *   · INFRASTRUCTURE — `www`, `mail`, `ns1`, `mx`, `cdn`. A DNS record that has to be able
+ *     to exist on this domain. A workspace holding one of these names is a workspace that
+ *     cannot be routed around later without taking somebody's site away.
+ *   · THE OPERATOR'S OWN SURFACE — `admin`, `status`, `billing`, `support`, `login`,
+ *     `auth`. These read as the operator speaking. A stranger's workspace answering on
+ *     `login.<domain>` is a phishing page with a real certificate, served by us.
+ *   · MAILBOXES THAT MUST STAY ANSWERABLE — `postmaster`, `hostmaster`, `webmaster`,
+ *     `abuse`, `security`. Certificate authorities and abuse reporters use these; they are
+ *     addresses before they are hostnames, and losing control of one loses a channel.
+ *
+ * A frozen ARRAY rather than a Set, deliberately: `Object.freeze(new Set())` does not stop
+ * `.add()`, so a frozen Set is a table that looks immutable and is not. The list is short
+ * and the check runs once per request.
+ */
+export const RESERVED_LABELS = Object.freeze([
+  // infrastructure
+  "www", "mail", "smtp", "imap", "pop", "mx", "ns", "ns1", "ns2", "ns3", "ftp", "sftp",
+  "cdn", "static", "assets", "img", "images", "media", "files", "edge", "origin", "proxy",
+  "vpn", "dns", "autodiscover", "autoconfig", "localhost", "local", "example", "invalid",
+  // the operator's own surface
+  "admin", "administrator", "root", "system", "internal", "control", "cp", "panel",
+  "dashboard", "account", "accounts", "billing", "invoice", "invoices", "pay", "payments",
+  "login", "signin", "signup", "register", "auth", "oauth", "sso", "id", "identity",
+  "api", "app", "apps", "console", "manage", "portal", "my", "me",
+  "status", "support", "help", "docs", "doc", "documentation", "blog", "news", "about",
+  "contact", "legal", "privacy", "terms", "press", "careers", "jobs", "shop", "store",
+  "download", "downloads", "community", "forum", "wiki",
+  "augur", "engine", "site", "web", "hosted", "cloud", "platform",
+  // environments, which are the names an operator reaches for in a hurry
+  "test", "testing", "staging", "stage", "dev", "develop", "development", "demo",
+  "preview", "sandbox", "beta", "alpha", "canary", "next", "old", "new", "tmp", "temp",
+  // mailboxes that have to stay answerable
+  "postmaster", "hostmaster", "webmaster", "abuse", "security", "noreply", "no-reply",
+  "info", "hi", "hello", "sales", "marketing",
+]);
+
+/**
+ * The shape a workspace label may have: a DNS label, lowercase, no leading or trailing
+ * hyphen, at most 63 characters. Anchored at both ends, so a dot anywhere fails and a
+ * deeper hostname can never be read as a workspace name.
+ */
+export const TENANT_LABEL_RE = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
+
+/**
+ * A Host header, reduced to the hostname a comparison can be made against.
+ *
+ * Three normalizations, each of which is a real request somebody sends:
+ *   · a PORT — `acme.example.com:8787`, which every local run produces;
+ *   · CASE — the header is case-insensitive and proxies do not agree on which one to send;
+ *   · a TRAILING DOT — `acme.example.com.` is the fully-qualified form and is legal.
+ *
+ * A bracketed IPv6 literal is left alone: it has no labels to take, and the suffix test
+ * below will not match it.
+ */
+export function normalizeHost(hostHeader) {
+  let h = String(hostHeader == null ? "" : hostHeader).trim().toLowerCase();
+  if (!h) return "";
+  if (h.startsWith("[")) return h.split("]")[0] + "]";     // [::1]:8787 -> [::1]
+  h = h.split(":")[0];
+  while (h.endsWith(".")) h = h.slice(0, -1);
+  return h;
+}
+
+/**
+ * The workspace this hostname names, or null.
+ *
+ * `suffix` is LITERAL and is compared with endsWith, which is the whole trick. A dotted
+ * suffix (`.example.com`) puts workspaces on `<name>.example.com` and needs a wildcard
+ * certificate; a hyphenated one (`-team.example.com`) keeps every workspace on a
+ * first-level hostname, which a universal certificate already covers. Both are one string
+ * in this function, and neither is special-cased.
+ *
+ * Returns null — never a guess — for: no suffix configured, a host that does not carry it,
+ * the apex itself, a label of the wrong shape, a deeper hostname, and a reserved name.
+ * The caller refuses the request; it does not fall back to a default workspace, because a
+ * default on a multi-workspace deployment is somebody else's workspace.
+ */
+export function tenantLabelFromHost(hostHeader, suffix, extra = NO_EXTRA) {
+  const s = String(suffix == null ? "" : suffix).trim().toLowerCase();
+  if (!s) return null;
+  const host = normalizeHost(hostHeader);
+  if (!host || host.length <= s.length || !host.endsWith(s)) return null;
+  const label = host.slice(0, -s.length);
+  if (!TENANT_LABEL_RE.test(label)) return null;
+  if (isReservedLabel(label, extra)) return null;
+  return label;
+}
+
+/**
+ * Whether a label is one the resolver must never resolve. Case-folded; nothing else.
+ * `extra` is the DEPLOYMENT's own reserved list (see parseReservedLabels) and reserves
+ * exactly like the engine's: the literal resolver answers nobody for it.
+ */
+export function isReservedLabel(label, extra = NO_EXTRA) {
+  const l = String(label == null ? "" : label).trim().toLowerCase();
+  return l !== "" && (RESERVED_LABELS.includes(l) || (extra.length > 0 && extra.includes(l)));
+}
+
+const NO_EXTRA = Object.freeze([]);
+
+/**
+ * The deployment's own reserved labels, from one env string (`RESERVED_LABELS_EXTRA`).
+ *
+ * The frozen list above names what is dangerous on ANY deployment. A deployment also has
+ * names of its own that must never become somebody's first label — the fallback origin it
+ * pointed a certificate product at, an address it intends to alias by operator grant — and
+ * those belong in its config, not in a public engine. Comma or whitespace separated,
+ * case-folded, and anything that is not a legal label is DROPPED rather than widened: a
+ * typo here must not reserve more than it says. Pure string work, like everything in this
+ * file; the caller reads the env, this never does.
+ */
+export function parseReservedLabels(raw) {
+  const s = String(raw == null ? "" : raw).trim().toLowerCase();
+  if (!s) return NO_EXTRA;
+  const out = [];
+  for (const part of s.split(/[\s,]+/)) {
+    if (part && TENANT_LABEL_RE.test(part) && !out.includes(part)) out.push(part);
+  }
+  return Object.freeze(out);
+}

package/src/tenant-quotas.mjs

@@ -0,0 +1,140 @@
+// What one workspace is allowed, as one row it carries with it.
+//
+// `B-quota-schema`. Four enforcement points are coming — asset uploads, board writes,
+// realtime rooms, signup invites — and the failure mode if they each carry their own
+// number is not that a limit is wrong. It is that nobody can say what the limit IS: raising
+// a plan means finding four constants in three files, and the one that gets missed refuses
+// a customer who has paid.
+//
+// So the quotas are SEEDED INTO THE WORKSPACE at provisioning and read from there. A
+// workspace's limits then travel with its data, survive an engine deploy, and can be raised
+// for one customer without a code change — which is what a support request actually looks
+// like.
+//
+// ⚠️ THE NUMBERS BELOW ARE A STARTING POSITION, NOT A PRICE. The plan item defines the
+// SHAPE and says the values are the operator's call. Each one has its reasoning written
+// beside it so changing it is an argument with a stated position rather than a guess at
+// what the last person meant. TWO of them are not guesses. `editorSeatLimit`: the free tier
+// is one editor because the paywall is the SECOND editor, which is the whole business model
+// and not a tuning knob. And `rtMonthlyDoMinutes` was MEASURED — a real room, instrumented
+// from the inside, driven by two real browser tabs; the note beside it says what the
+// measurement was and what it cost.
+
+/**
+ * R2's free tier is 10 GB for the WHOLE ACCOUNT, not per workspace. A per-workspace cap
+ * that ignores that is a cap that never fires until the account bill does.
+ */
+const ACCOUNT_R2_FREE_BYTES = 10 * 1024 * 1024 * 1024;
+
+/**
+ * How many free workspaces the account's free storage is meant to hold. THIS is the number
+ * to turn: it is the one with a meaning ("free workspaces we can carry before storage
+ * costs money"), and the byte cap falls out of it.
+ */
+const FREE_WORKSPACES_PER_ACCOUNT = 40;
+
+/**
+ * A working month in minutes — 22 days of 8 hours. The realtime cap below is written in
+ * board time rather than in a bare number because "how long boards may be live" is a
+ * sentence somebody can check against their own week, and 10560 is not.
+ */
+const WORKING_MINUTES_PER_MONTH = 22 * 8 * 60;
+
+/**
+ * The quota shape. Every field is a number, and every enforcement point reads its ceiling
+ * from here rather than declaring one.
+ *
+ * `null` is not used and must not be: an absent ceiling written as null reads as "no limit"
+ * at one call site and "not configured, refuse" at another. Unlimited is a very large
+ * number, so every comparison has the same meaning everywhere.
+ */
+export const QUOTA_FIELDS = Object.freeze([
+  "editorSeatLimit",
+  "storageBytesCap",
+  "assetUploadDailyBytes",
+  "boardWritesPerMinute",
+  "rtConcurrentRooms",
+  "rtMonthlyDoMinutes",
+]);
+
+export const PLANS = Object.freeze({
+  free: Object.freeze({
+    // ONE editor. Not a tuning knob — the paywall is the second editor, and everything
+    // else on this list is a cost ceiling rather than a product boundary. Viewers and
+    // commenters are not seats: a workspace nobody can show anything to is not a workspace.
+    editorSeatLimit: 1,
+    // The account's free storage divided by how many free workspaces it is meant to carry.
+    // A published design system with a few dozen prototypes is tens of megabytes, so this
+    // is generous for what it is for and firm about what it is not (an image host).
+    storageBytesCap: Math.floor(ACCOUNT_R2_FREE_BYTES / FREE_WORKSPACES_PER_ACCOUNT),
+    // Per DAY, and it is deliberately a fraction of the total cap: the thing this stops is
+    // a script filling a workspace overnight, which the total cap alone would allow right
+    // up to the moment it is full.
+    assetUploadDailyBytes: 50 * 1024 * 1024,
+    // A canvas board writes on a debounce, not per keystroke, so a person costs a handful
+    // a minute. This is loose enough that nobody drawing hits it and tight enough that a
+    // loop does.
+    boardWritesPerMinute: 300,
+    // Concurrent multiplayer rooms. This used to say a room "stays awake while somebody is
+    // in it, which is the realtime bill in one sentence", and the measurement below refutes
+    // that: a room with people in it and nobody touching it is hibernated and costs nothing.
+    // What this stops is a workspace holding hundreds of rooms open at once, which the
+    // monthly cap alone would allow right up to the moment it is spent.
+    rtConcurrentRooms: 5,
+    // Minutes those rooms may stay awake in a month. ONE BOARD LIVE EVERY WORKING HOUR OF
+    // THE MONTH — which one editor cannot reach, and that is the point: this is a runaway
+    // stop, not a ration.
+    //
+    // It is set from a measurement, not chosen. test/rt-cost/ instruments a real room from
+    // the inside and test/rt-cost/results/ is the recording; a room was driven both by a
+    // replay of the client's own cadence and by two browser tabs running the real client.
+    // An hour of editing keeps the room awake 32.7 minutes with one person in it and 54.7 with
+    // two — the same object either way, so a second person is nearly free and a cap on room
+    // minutes is a cap on how long boards are LIVE, never on head count. A heavy month for
+    // one editor is therefore around 1300 awake minutes, and the 1000 that stood here would
+    // have cut that person off.
+    //
+    // ⚠️ AWAKE IS NOT BILLED, AND THE GAP IS TWO ORDERS OF MAGNITUDE. Duration is charged
+    // while the object is running or idle-but-unable-to-hibernate, and a room whose sockets
+    // all went through the hibernation API is eligible in every gap between messages. The
+    // same recording puts the object's actual handler occupancy under one per cent of its
+    // awake time, so this cap corresponds to at most a couple of minutes of charged
+    // duration — a fairness limit long before it is a cost one. On the deployed runtime the
+    // object was never evicted at all across 150 seconds of silence, so residency there is
+    // nearer "a socket is open" than "somebody is working", and it still costs nothing.
+    //
+    // Two cases are deliberately NOT averaged into the number above. An idle tab costs
+    // NOTHING: five minutes, two tabs, 52 keepalives, zero events reached the object,
+    // because the runtime answers them from the auto-response pair without waking it. And
+    // the tail after the last person leaves is one flush of about 11ms, plus one already-
+    // armed alarm that fires later into an empty room and returns.
+    rtMonthlyDoMinutes: WORKING_MINUTES_PER_MONTH,
+  }),
+  paid: Object.freeze({
+    // The only difference that is a PRODUCT difference. The rest are raised because a
+    // paying workspace's costs are covered, not because the free tier was mean.
+    editorSeatLimit: 100,
+    storageBytesCap: 20 * 1024 * 1024 * 1024,
+    assetUploadDailyBytes: 2 * 1024 * 1024 * 1024,
+    boardWritesPerMinute: 3000,
+    rtConcurrentRooms: 100,
+    // Ten boards live every working hour of the month, at the measured cost of a room with
+    // more than one person on it. Ten because that is what a hundred seats spread over
+    // shared boards looks like when the whole team is working, and because the measurement
+    // says the ceiling costs about a thousand minutes of charged duration a month — inside
+    // the account's included allowance on its own.
+    rtMonthlyDoMinutes: 10 * WORKING_MINUTES_PER_MONTH,
+  }),
+});
+
+export const DEFAULT_PLAN = "free";
+
+/**
+ * The quota values a plan implies, as a flat name→number map including `plan` itself.
+ * An unknown plan name resolves to the free tier rather than to no limits: a typo in a
+ * billing webhook must not be how somebody gets an unlimited workspace.
+ */
+export function quotasForPlan(plan, plans = PLANS) {
+  const name = plans[plan] ? plan : DEFAULT_PLAN;
+  return Object.freeze({ plan: name, ...plans[name] });
+}

package/src/unit-core.mjs

@@ -0,0 +1,103 @@
+// src/unit-core.mjs — the pure half of drafts that land.
+//
+// A UNIT is a prototype folder, spelled as its URL prefix with a leading and a trailing
+// slash, exactly as `routing.publicPrefixes` spells it. A DRAFT is one session's live
+// working copy of a unit, addressed at `<unit>@<id>/`. Everything here is a decision over
+// plain objects: the Durable Object, the worker and the CLI all import it, and none of them
+// re-derive what a unit, a draft or a stale save is. See docs/drafts-that-land.md.
+//
+// ⚠️ NO NODE IMPORTS. The worker and the Durable Object run this too.
+
+export const ACTIVE_MS = 5 * 60_000;
+export const DRAFT_ID_RE = /^[a-z0-9]{6}$/;
+// A draft address: one or more path segments, then `@` + six chars, then the rest.
+const DRAFT_PATH_RE = /^(\/(?:[^/@][^/]*\/)+)@([a-z0-9]{6})(\/.*)?$/;
+
+/** `"checkout/flow"` → `"/checkout/flow/"`; null for anything that is not a unit path. */
+export function normUnit(s) {
+  const raw = String(s == null ? "" : s).trim().replace(/\/{2,}/g, "/");
+  const segs = raw.split("/").filter(Boolean);
+  if (!segs.length) return null;
+  for (const seg of segs) if (seg === "." || seg === ".." || seg.startsWith("@")) return null;
+  return "/" + segs.join("/") + "/";
+}
+
+export function newDraftId(random = Math.random) {
+  const alphabet = "abcdefghijklmnopqrstuvwxyz0123456789";
+  let out = "";
+  for (let i = 0; i < 6; i++) out += alphabet[Math.floor(random() * alphabet.length) % alphabet.length];
+  return out;
+}
+
+export const draftAddress = (unit, id) => `${unit}@${id}/`;
+
+export function splitDraftPath(pathname) {
+  const m = DRAFT_PATH_RE.exec(String(pathname || ""));
+  if (!m) return null;
+  return { unit: m[1], id: m[2], rest: m[3] || "/" };
+}
+
+/** The manifest's entries under `unit`, with only the fields a table carries. */
+export function unitTable(files, unit) {
+  const out = {};
+  for (const [p, f] of Object.entries(files || {})) {
+    if (!p.startsWith(unit) || !f) continue;
+    const row = { h: f.h, ct: f.ct, s: f.s };
+    if (f.by) row.by = f.by;
+    if (f.editedAt) row.editedAt = f.editedAt;
+    out[p] = row;
+  }
+  return out;
+}
+
+export function sameTable(a, b) {
+  const ka = Object.keys(a || {}), kb = Object.keys(b || {});
+  if (ka.length !== kb.length) return false;
+  return ka.every((p) => b[p] && b[p].h === a[p].h);
+}
+
+/**
+ * Apply a save's changes with per-file compare-and-set. All or nothing: one stale base
+ * refuses the whole batch, and the caller gets the current hash of every stale file.
+ */
+export function applyChanges(table, changes) {
+  const stale = [];
+  for (const c of changes || []) {
+    const cur = table[c.path];
+    const curHash = cur ? cur.h : null;
+    const base = c.baseHash == null ? null : c.baseHash;
+    if (base !== curHash) stale.push({ path: c.path, h: curHash });
+  }
+  if (stale.length) return { ok: false, table, stale };
+  const next = { ...table };
+  for (const c of changes || []) {
+    if (c.delete) delete next[c.path];
+    else next[c.path] = { h: c.h, ct: c.ct, s: c.s };
+  }
+  return { ok: true, table: next, stale: [] };
+}
+
+/** What `to` has that `from` does not: changed/added with `to`'s metadata, and removed paths. */
+export function tableDelta(from, to) {
+  const changed = [], removed = [];
+  for (const [p, f] of Object.entries(to || {})) {
+    if (!from[p] || from[p].h !== f.h) changed.push({ path: p, ...f });
+  }
+  for (const p of Object.keys(from || {})) if (!to[p]) removed.push(p);
+  changed.sort((a, b) => a.path.localeCompare(b.path));
+  removed.sort();
+  return { changed, removed };
+}
+
+/** Open drafts, each with `active` derived from its last save (or its opening). */
+export function presenceOf(drafts, nowMs) {
+  return (drafts || [])
+    .filter((d) => !d.closedAt)
+    .map((d) => {
+      const last = Date.parse(d.lastSaveAt || d.openedAt || "") || 0;
+      return {
+        id: d.id, owner: d.owner, session: d.session || "", openedAt: d.openedAt,
+        lastSaveAt: d.lastSaveAt || null, active: nowMs - last < ACTIVE_MS,
+      };
+    });
+}