6023b14 · 0548800 · 36207ac · dfa96fd · 316fa06 · deba080
@@ -422,6 +422,59 @@
ping for 120 seconds is dropped. The app's own 101 response headers are
not carried — a cookie an app sets on the handshake does not reach the
browser.
## Your own domain
An app can answer at a name you own — `app.example.com`, or an apex like
`example.com` — beside the hostname the forge gave it. Under **Settings →
App → Domains** an admin of the repository adds the name (or `POST
/api/v1/repos/:owner/:name/app/domains` with a `{ "host" }` body) and is
shown the two records to publish in the zone:
- a TXT record at `_forge-verify.<host>` whose value is `forge-verify=<token>`
  — the proof that whoever added the name holds it. The token is made for
  that one domain and is not a secret: it is published;
- a CNAME from `<host>` to the app's own hostname (`notes.forge.example`),
  which carries the traffic. An apex cannot carry a CNAME: use the DNS
  provider's ALIAS or ANAME record instead, or A and AAAA records with the
  address the forge is served at.
The forge checks when asked — **Check now** on the page, or `POST
…/app/domains/:host/check` — never on a timer. It looks the TXT record up;
the domain is verified when some record there is exactly the value shown.
Every check leaves one sentence a person can act on ("No TXT record at
`_forge-verify.app.example.com` yet.", "The TXT record is there but holds a
different value.", "Verified; app.example.com points at
notes.forge.example."), and when it was said. Verification is a proof of
control at one moment, like a certificate's: the first check that finds the
record verifies the domain, and a record tidied away later does not take a
live site down. Removing the domain is what stops the forge answering there.
Once verified, the forge serves the app at that host — production, at the
same port, through the same proxy, with the same grant — and production's
URL becomes `https://app.example.com`: every "Open the app" link, the app's
JSON `url`, and the `FORGE_APP_URL` its process starts with. The app itself
learns its new address at its next deploy, because a process reads its
environment once. Until a domain is verified the forge answers for itself
at that name, exactly as it does for any hostname it does not know; a name
that is nobody's proof serves nobody's app. The hostname the forge gave the
app keeps working beside the domain.
A private app's sign-in works on the new host as it does on the old: a
visitor arriving at `app.example.com` is sent to the forge, vouched for, and
sent back to `app.example.com/__forge/grant`, where the grant cookie is set
for that host. One host names one app's production; a second domain on the
same app is served too, and the oldest verified one is the URL.
Whatever fronts the forge must route the name to it. A wildcard certificate
covers `*.forge.example` and not `app.example.com`, so the proxy needs a
certificate per domain. With Caddy, `on_demand_tls` fetches one the first
time a name is asked for, and asks the forge first whether the name is
anyone's: `GET /__forge/domains/ask?domain=<host>` answers 200 for a
verified domain and 404 for anything else, so a stranger cannot make the
proxy fetch certificates for names that are not here (`docs/EXTRACT.md`
has the Caddyfile). A tunnel routes the host the way it routes the
wildcard. The forge itself speaks plain HTTP either way.
## A release does not drop a session
The forge is one process on one volume, and a release replaces it. The new
@@ -693,7 +746,7 @@
the data directory `FORGE_APP_DATA`, and the defaults become
Containers. An app runs as the forge's own user, in its own directory, and
nothing more separates it from the host than that. On the machine one
person owns this is the honest, fast answer; a sandboxed runtime is the
next layer, and the process boundary here is where it will attach. Custom
domains, TLS termination, and an approve-and-land gate are additions of
the same kind: the shapes above hold, and a new column or listener carries
each of them.
next layer, and the process boundary here is where it will attach. TLS
termination and an approve-and-land gate are additions of the same kind:
the shapes above hold, and a new column or listener carries each of them —
as one column carried a domain of the app's own.
@@ -44,7 +44,31 @@
turned off, with what each move costs and what it gives up.
   `forge.example, *.forge.example { reverse_proxy 127.0.0.1:3000 }` with a
   DNS-challenge wildcard, or the existing Cloudflare tunnel with two ingress
   rules to `http://127.0.0.1:3000`. Either way the forge sees
   `x-forwarded-proto` and answers with its canonical URL.
   `x-forwarded-proto` and answers with its canonical URL. An app's own
   domain (`docs/APPS.md`, _Your own domain_) is a name the wildcard does
   not cover, so Caddy fetches its certificate on demand — after asking the
   forge whether the name is anyone's:
   ```
   {
     on_demand_tls {
       ask http://127.0.0.1:3000/__forge/domains/ask
     }
   }
   forge.example, *.forge.example {
     reverse_proxy 127.0.0.1:3000
   }
   https:// {
     tls { on_demand }
     reverse_proxy 127.0.0.1:3000
   }
   ```
   The forge answers the ask with 200 for a verified domain and 404 for
   anything else, so nobody can make the proxy fetch certificates for names
   that are not here. With the tunnel, each domain is one more ingress rule
   to the same address.
5. **DNS cutover.** Point `forge.example` and the wildcard at the box (or
   the tunnel). The old cluster keeps serving until the switch; after it,
   the platform's forge is a copy nobody visits.
@@ -8,7 +8,7 @@
import type { App } from "../app.ts";
import { appsRuntime, type EnvStatus } from "../apps/runtime.ts";
import { grantUrl } from "../apps/proxy.ts";
import { grantUrl, originFor } from "../apps/proxy.ts";
import { scaffoldFiles } from "../apps/scaffold.ts";
import {
  isEnvName,
@@ -323,7 +323,10 @@
export async function newApp(
          {
            name: input.name,
            description,
            agents: agents.map((a) => ({ name: a.user.username, brief: a.brief })),
            agents: agents.map((a) => ({
              name: a.user.username,
              brief: a.brief,
            })),
          },
          { binary },
        );
@@ -474,9 +477,8 @@
export function openEnvUrl(
    return ok(grantUrl(runtime, { app: record, env }, path, host, who));
  }
  if (record.access === "private") return err("unauthorized");
  const base = new URL(runtime.urlFor(record, env));
  if (host !== undefined) base.hostname = host.replace(/:\d+$/, "");
  return ok(`${base.origin}${path === "/" ? "" : path}`);
  const origin = originFor(runtime, { app: record, env }, host);
  return ok(`${origin}${path === "/" ? "" : path}`);
}
/** Deploy an environment again at its current commit. */
@@ -0,0 +1,198 @@
/**
 * Domain actions: give an app a name of its own, check that the person who
 * added it holds it, and take it away. Admin over the repository, like
 * every other app setting. The check is the one thing here that leaves the
 * box — a DNS lookup — and it happens when someone asks, never on a timer.
 */
import type { App } from "../app.ts";
import { checkDomain, recordsFor, type DnsRecord } from "../apps/domains.ts";
import { appHostSuffix } from "../apps/host.ts";
import { appsRuntime, type AppsRuntime } from "../apps/runtime.ts";
import { getAppByRepo, type AppRecord } from "../core/apps.ts";
import {
  addDomain,
  getDomain,
  listDomains,
  recordCheck,
  removeDomain,
  type AddDomainError,
  type AppDomain,
} from "../core/domains.ts";
import type { Repo } from "../core/repos.ts";
import type { User } from "../core/users.ts";
import { err, ok, type Result } from "../kernel/result.ts";
import { requireRepoAdmin } from "./access.ts";
/** A domain as a page or the API shows it: the facts, and what to publish. */
export interface AppDomainView {
  readonly host: string;
  readonly verified: boolean;
  readonly verifiedAt: string | null;
  readonly checkedAt: string | null;
  readonly said: string;
  /** The proof, and where the traffic goes. */
  readonly records: DnsRecord[];
}
export type DomainError = "not_found" | "no_runtime";
/** The admin, and the app they administer. */
function admitted(
  app: App,
  actor: User | undefined,
  repo: Repo,
): Result<{ admin: User; record: AppRecord }, "not_found"> {
  const admin = requireRepoAdmin(app, actor, repo);
  if (!admin.ok) return admin;
  const record = getAppByRepo(app.db, repo.id);
  if (!record) return err("not_found");
  return ok({ admin: admin.value, record });
}
/** A domain has nowhere to point when nothing serves apps. */
function serving(app: App): Result<AppsRuntime, "no_runtime"> {
  const runtime = appsRuntime(app);
  return runtime === undefined ? err("no_runtime") : ok(runtime);
}
/** The forge's own hostname — the one name no app may take. */
function forgeHost(app: App): string {
  return app.config.url !== undefined
    ? new URL(app.config.url).hostname
    : (app.config.host ?? "localhost");
}
/** One of this app's domains, by host — never another app's. */
function ownedDomain(
  app: App,
  record: AppRecord,
  host: string,
): AppDomain | undefined {
  const domain = getDomain(app.db, host);
  return domain?.appId === record.id ? domain : undefined;
}
function view(
  runtime: AppsRuntime,
  record: AppRecord,
  domain: AppDomain,
): AppDomainView {
  return {
    host: domain.host,
    verified: domain.verifiedAt !== null,
    verifiedAt: domain.verifiedAt,
    checkedAt: domain.checkedAt,
    said: domain.said,
    records: recordsFor(
      domain.host,
      domain.token,
      runtime.hostFor(record.slug, domain.env),
    ),
  };
}
export function listAppDomains(
  app: App,
  actor: User | undefined,
  repo: Repo,
): Result<AppDomainView[], DomainError> {
  const gate = admitted(app, actor, repo);
  if (!gate.ok) return gate;
  const runtime = serving(app);
  if (!runtime.ok) return runtime;
  return ok(
    listDomains(app.db, gate.value.record.id).map((domain) =>
      view(runtime.value, gate.value.record, domain),
    ),
  );
}
/** Add a domain; the answer carries the two records to publish. */
export function addAppDomain(
  app: App,
  actor: User | undefined,
  repo: Repo,
  host: string,
): Result<AppDomainView, DomainError | AddDomainError> {
  const gate = admitted(app, actor, repo);
  if (!gate.ok) return gate;
  const runtime = serving(app);
  if (!runtime.ok) return runtime;
  const { admin, record } = gate.value;
  const added = addDomain(
    app.db,
    { host, appId: record.id, createdBy: admin.id },
    {
      forgeHost: forgeHost(app),
      appHostSuffix: appHostSuffix(
        runtime.value.options.domain.toLowerCase().replace(/:\d+$/, ""),
      ),
    },
  );
  if (!added.ok) return added;
  app.bus.append({
    kind: "app.domain.added",
    repoId: repo.id,
    actorId: admin.id,
    payload: { host: added.value.host, slug: record.slug },
  });
  return ok(view(runtime.value, record, added.value));
}
/**
 * Look the proof up now. The first check that finds it verifies the domain
 * for good and says so on the bus; every check leaves its sentence.
 */
export async function checkAppDomain(
  app: App,
  actor: User | undefined,
  repo: Repo,
  host: string,
): Promise<Result<AppDomainView, DomainError | "no_such_domain">> {
  const gate = admitted(app, actor, repo);
  if (!gate.ok) return gate;
  const runtime = serving(app);
  if (!runtime.ok) return runtime;
  const { admin, record } = gate.value;
  const domain = ownedDomain(app, record, host);
  if (domain === undefined) return err("no_such_domain");
  const found = await checkDomain(
    domain.host,
    domain.token,
    runtime.value.hostFor(record.slug, domain.env),
    runtime.value.options.dns,
  );
  const updated = recordCheck(app.db, domain.host, found) ?? domain;
  if (found.verified && domain.verifiedAt === null) {
    app.bus.append({
      kind: "app.domain.verified",
      repoId: repo.id,
      actorId: admin.id,
      payload: { host: domain.host, slug: record.slug },
    });
  }
  return ok(view(runtime.value, record, updated));
}
/** Take a domain away. The forge stops answering there at once. */
export function removeAppDomain(
  app: App,
  actor: User | undefined,
  repo: Repo,
  host: string,
): Result<void, "not_found" | "no_such_domain"> {
  const gate = admitted(app, actor, repo);
  if (!gate.ok) return gate;
  const { admin, record } = gate.value;
  const domain = ownedDomain(app, record, host);
  if (domain === undefined || !removeDomain(app.db, domain.host))
    return err("no_such_domain");
  app.bus.append({
    kind: "app.domain.removed",
    repoId: repo.id,
    actorId: admin.id,
    payload: { host: domain.host, slug: record.slug },
  });
  return ok();
}
@@ -0,0 +1,154 @@
/**
 * Proving a domain, and saying what was found. The person who adds
 * `app.example.com` publishes two records: a TXT under `_forge-verify.`
 * carrying the token the forge gave them, which proves they hold the name,
 * and a CNAME to the app's own hostname, which carries the traffic. Only
 * the TXT decides; the CNAME is reported, because a name can reach the
 * forge in more ways than one — an apex through ALIAS or A records, a
 * tunnel. Every outcome of a lookup — no record, another value, a resolver
 * that will not answer — is a sentence a person can act on, never a throw.
 */
import { resolveCname, resolveTxt } from "node:dns/promises";
export interface DnsRecord {
  readonly type: "TXT" | "CNAME" | "ALIAS";
  readonly name: string;
  readonly value: string;
  /** A word of explanation, when the record needs one. */
  readonly note?: string;
}
const VERIFY_LABEL = "_forge-verify";
export const verifyName = (host: string): string => `${VERIFY_LABEL}.${host}`;
export const verifyValue = (token: string): string => `forge-verify=${token}`;
/** A name of exactly two labels cannot carry a CNAME. */
export const isApex = (host: string): boolean => host.split(".").length === 2;
const APEX_NOTE =
  "An apex cannot carry a CNAME: use your DNS provider's ALIAS or ANAME record to point it at the app's hostname, or A and AAAA records with the address the forge is served at.";
/** The two records to publish for `host`, given the app's own hostname. */
export function recordsFor(
  host: string,
  token: string,
  appHost: string,
): DnsRecord[] {
  const proof: DnsRecord = {
    type: "TXT",
    name: verifyName(host),
    value: verifyValue(token),
  };
  return isApex(host)
    ? [proof, { type: "ALIAS", name: host, value: appHost, note: APEX_NOTE }]
    : [proof, { type: "CNAME", name: host, value: appHost }];
}
/** What a check asks of DNS — the system resolver, or a test's stand-in. */
export interface DomainResolver {
  resolveTxt(name: string): Promise<string[][]>;
  resolveCname(name: string): Promise<string[]>;
}
const systemResolver: DomainResolver = { resolveTxt, resolveCname };
/** How long a lookup may take before it is called a timeout. */
const LOOKUP_TIMEOUT_MS = 5_000;
export interface DomainCheck {
  readonly verified: boolean;
  /** One plain sentence: what was found, and what to do about it. */
  readonly said: string;
}
/**
 * Look the proof up, and — once it is there — where the name points.
 * `verified` iff some TXT record at `_forge-verify.<host>` is exactly
 * `forge-verify=<token>`.
 */
export async function checkDomain(
  host: string,
  token: string,
  appHost: string,
  resolver: DomainResolver = systemResolver,
): Promise<DomainCheck> {
  const name = verifyName(host);
  const proof = await lookup(() => resolver.resolveTxt(name));
  if (proof.kind === "none")
    return { verified: false, said: `No TXT record at ${name} yet.` };
  if (proof.kind === "failed")
    return {
      verified: false,
      said: `The DNS lookup for ${name} ${proof.why}; try again in a minute.`,
    };
  const values = proof.value.map((chunks) => chunks.join(""));
  if (!values.includes(verifyValue(token)))
    return {
      verified: false,
      said: "The TXT record is there but holds a different value.",
    };
  return {
    verified: true,
    said: `Verified; ${await pointing(host, appHost, resolver)}.`,
  };
}
/** Where the name sends traffic, as one clause of the verified sentence. */
async function pointing(
  host: string,
  appHost: string,
  resolver: DomainResolver,
): Promise<string> {
  if (isApex(host))
    return `${host} is an apex, so point it at ${appHost} with an ALIAS record or at the forge's address`;
  const cname = await lookup(() => resolver.resolveCname(host));
  if (cname.kind === "none") return `${host} has no CNAME yet`;
  if (cname.kind === "failed")
    return `where ${host} points could not be looked up`;
  const first = cname.value[0];
  if (first === undefined) return `${host} has no CNAME yet`;
  const target = canonical(first);
  return target === canonical(appHost)
    ? `${host} points at ${appHost}`
    : `${host} points at ${target}, not ${appHost}`;
}
const canonical = (name: string): string =>
  name.toLowerCase().replace(/\.$/, "");
type Lookup<T> =
  | { kind: "found"; value: T }
  | { kind: "none" }
  | { kind: "failed"; why: string };
/**
 * One lookup, with every way it can go wrong folded into a value. "No such
 * record" and "no such name" both mean nothing is published yet; anything
 * else is the resolver's trouble, named so the sentence can carry it.
 */
async function lookup<T>(run: () => Promise<T>): Promise<Lookup<T>> {
  let timer: ReturnType<typeof setTimeout> | undefined;
  const timeout = new Promise<never>((_, reject) => {
    timer = setTimeout(
      () => reject(Object.assign(new Error("timed out"), { code: "ETIMEOUT" })),
      LOOKUP_TIMEOUT_MS,
    );
  });
  try {
    return { kind: "found", value: await Promise.race([run(), timeout]) };
  } catch (error) {
    const code =
      typeof error === "object" && error !== null && "code" in error
        ? String((error as { code: unknown }).code)
        : "";
    if (code === "ENODATA" || code === "ENOTFOUND") return { kind: "none" };
    return {
      kind: "failed",
      why: code === "ETIMEOUT" ? "timed out" : `failed (${code || "error"})`,
    };
  } finally {
    clearTimeout(timer);
  }
}
@@ -17,7 +17,8 @@
import { appHostSuffix } from "./host.ts";
import { createHmac, timingSafeEqual } from "node:crypto";
import type { App } from "../app.ts";
import { getAppBySlug, type AppRecord } from "../core/apps.ts";
import { getAppById, getAppBySlug, type AppRecord } from "../core/apps.ts";
import { getVerifiedDomain } from "../core/domains.ts";
import { err, ok, type Result } from "../kernel/result.ts";
import { loadKey } from "../kernel/secret.ts";
import { previewEnv, type EnvName } from "./data.ts";
@@ -34,6 +35,15 @@
export interface AppTarget {
  readonly nested?: boolean;
}
/**
 * What a `Host` may look like before it is read as anything: a hostname of
 * letters, digits, dots and hyphens, and at most a port. Nothing here can
 * be reparsed into another host by a URL parser (`#`, `@`, `/`, `?`,
 * spaces), so every reading below agrees on which machine is meant.
 */
export const isHostPort = (host: string): boolean =>
  /^[a-z0-9](?:[a-z0-9.-]{0,252})?(?::\d{1,5})?$/i.test(host);
/**
 * Which app and environment a `Host` names, if any. Hostnames are
 * case-insensitive and may carry a port. Only one label may sit in front
@@ -43,6 +53,7 @@
export function parseAppHost(
  hostHeader: string,
  domain: string,
): { slug: string; env: EnvName; nested: boolean } | undefined {
  if (!isHostPort(hostHeader)) return undefined;
  const host = hostHeader.toLowerCase().replace(/:\d+$/, "");
  const suffix = appHostSuffix(domain.toLowerCase().replace(/:\d+$/, ""));
  if (!host.endsWith(suffix)) return undefined;
@@ -89,13 +100,54 @@
export function resolveAppHostname(
  host: string,
): AppTarget | "unknown" | undefined {
  const parsed = parseAppHost(host, domain);
  if (parsed === undefined) return undefined;
  if (parsed === undefined) return ownDomain(app, host);
  const record = getAppBySlug(app.db, parsed.slug);
  return record
    ? { app: record, env: parsed.env, nested: parsed.nested }
    : "unknown";
}
/**
 * A hostname that is no label of ours may still be an app's own domain,
 * once the person who added it has proved they hold it (core/domains.ts).
 * Until then, and for every other name, the forge answers for itself —
 * its own pages, at whatever name it is reached by — so a domain added
 * but not yet verified serves nothing of the app.
 */
function ownDomain(app: App, host: string): AppTarget | undefined {
  const domain = getVerifiedDomain(app.db, host.replace(/:\d+$/, ""));
  if (domain === undefined) return undefined;
  const record = getAppById(app.db, domain.appId);
  return record === undefined
    ? undefined
    : { app: record, env: domain.env, nested: false };
}
/**
 * The origin a visitor is sent back to: the hostname they asked for, at
 * the port they asked for it on when the name carried one; otherwise the
 * environment's own URL decides the port. An app's canonical host carries
 * the forge's, its own domain none — and only what the browser sent says
 * which the visitor is at.
 */
export function originFor(
  runtime: AppsRuntime,
  target: AppTarget,
  host?: string,
): string {
  const base = new URL(runtime.urlFor(target.app, target.env));
  // Only a bare hostname, with or without a port, is a place to send
  // anyone. A URL parser reads `evil#x--notes.apps.test` as the host `evil`
  // while the label check above read it as ours — the same string must
  // never mean two hosts, so anything else is not a host at all.
  if (host === undefined || !isHostPort(host)) return base.origin;
  const asked = URL.parse(`${base.protocol}//${host}`);
  if (asked === null) return base.origin;
  base.hostname = asked.hostname;
  if (asked.port !== "") base.port = asked.port;
  return base.origin;
}
/**
 * The grant cookie is named for the app it admits to. Two forges can set
 * grants on one hostname — this one, and a forge it hosts, for an app of
@@ -240,11 +292,10 @@
export function grantUrl(
  );
  // The cookie a grant sets belongs to one hostname. A visitor who asked
  // for a hostname inside the app's own world — an app of a forge hosted
  // here — must be granted on that hostname, not the app's canonical one,
  // here, or the app's canonical host when it has a domain of its own —
  // must be granted on that hostname, not the one production's URL names,
  // or the cookie lands where the request never goes.
  const base = new URL(runtime.urlFor(target.app, target.env));
  if (host !== undefined) base.hostname = host.replace(/:\d+$/, "");
  return `${base.origin}/__forge/grant?t=${encodeURIComponent(token)}&to=${encodeURIComponent(path)}`;
  return `${originFor(runtime, target, host)}/__forge/grant?t=${encodeURIComponent(token)}&to=${encodeURIComponent(path)}`;
}
const HOP_BY_HOP = [
@@ -43,7 +43,9 @@
import { createLog } from "../kernel/log.ts";
import type { Result } from "../kernel/result.ts";
import { holdLease, STALE_AFTER_MS } from "../runs/lease.ts";
import { appendRunLog } from "../runs/log.ts";
import { primaryDomain } from "../core/domains.ts";
import { exportTree, readFileAt } from "./checkout.ts";
import type { DomainResolver } from "./domains.ts";
import {
  appsRoot,
  ensureEnvData,
@@ -89,6 +91,11 @@
export interface RuntimeOptions {
    | undefined;
  /** How often the runtime looks for environments to put to sleep. */
  readonly sweepEveryMs?: number | undefined;
  /**
   * What a domain check asks: the system resolver unless a test hands in
   * its own, so proving `app.example.com` needs no network in a test.
   */
  readonly dns?: DomainResolver | undefined;
}
export type EnvState =
@@ -294,7 +301,19 @@
export class AppsRuntime {
    return sshCommand(this.app, login);
  }
  /**
   * Where an environment is reached. Production answers at the app's own
   * domain once one is verified — every link, the app's JSON `url` and the
   * `FORGE_APP_URL` its next process starts with all follow — and at
   * `<slug>.<domain>` until then; a preview is always at its label. A
   * domain carries no port: it reaches the forge through whatever fronts
   * it, which holds its own.
   */
  urlFor(record: AppRecord, env: EnvName): string {
    if (env === "production") {
      const own = primaryDomain(this.app.db, record.id);
      if (own !== undefined) return `${this.options.scheme}://${own.host}`;
    }
    const port =
      this.options.publicPort === undefined ||
      (this.options.scheme === "http" && this.options.publicPort === 80) ||
@@ -0,0 +1,207 @@
/**
 * An app's own domains — the rows. `app.example.com` is served by the forge
 * once the person who added it has shown they hold the name: a TXT record
 * carrying the token the row remembers. The token is published in DNS, so
 * it is not a secret; the proof is that only the zone's owner could put it
 * there. Pure data: no DNS, no authz, no events. What is published and how
 * it is checked is `apps/domains.ts`.
 */
import type { Database } from "bun:sqlite";
import type { EnvName } from "../apps/data.ts";
import { err, ok, type Result } from "../kernel/result.ts";
export interface AppDomain {
  readonly host: string;
  readonly appId: string;
  /** The environment the host reaches — production, for now. */
  readonly env: EnvName;
  /** Published in DNS as `forge-verify=<token>`, to prove control of the name. */
  readonly token: string;
  readonly createdBy: string | null;
  readonly createdAt: string;
  readonly verifiedAt: string | null;
  readonly checkedAt: string | null;
  /** What the last check said, one sentence for a person. */
  readonly said: string;
}
interface DomainRow {
  host: string;
  app_id: string;
  env: EnvName;
  token: string;
  created_by: string | null;
  created_at: string;
  verified_at: string | null;
  checked_at: string | null;
  said: string;
}
const toDomain = (r: DomainRow): AppDomain => ({
  host: r.host,
  appId: r.app_id,
  env: r.env,
  token: r.token,
  createdBy: r.created_by,
  createdAt: r.created_at,
  verifiedAt: r.verified_at,
  checkedAt: r.checked_at,
  said: r.said,
});
const now = (): string => new Date().toISOString();
/**
 * The names an app may not take: the forge's own hostname, and anything
 * that hangs off the app domain — those are the forge's to hand out
 * (`<slug>.<domain>`), and a row here would shadow them.
 */
export interface DomainRules {
  /** The forge's own hostname, lowercase. */
  readonly forgeHost: string;
  /** What app hostnames attach to (`appHostSuffix`), when apps are served. */
  readonly appHostSuffix?: string | undefined;
}
export type AddDomainError = "invalid_host" | "reserved_host" | "taken";
/** A hostname the way DNS wants it: lowercase, no trailing dot. */
export function normalizeHost(host: string): string {
  return host.trim().toLowerCase().replace(/\.$/, "");
}
const LABEL = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
/**
 * A hostname a person can own: at least two labels of letters, digits and
 * inside hyphens, and not an address. A last label of digits is an IPv4
 * literal or a name no URL can hold, and is refused either way.
 */
export function isHostname(host: string): boolean {
  if (host.length === 0 || host.length > 253) return false;
  const labels = host.split(".");
  if (labels.length < 2 || !labels.every((label) => LABEL.test(label)))
    return false;
  return !/^\d+$/.test(labels.at(-1)!);
}
function isReserved(host: string, rules: DomainRules): boolean {
  if (host === rules.forgeHost.toLowerCase()) return true;
  const suffix = rules.appHostSuffix?.toLowerCase();
  if (suffix === undefined) return false;
  // `.apps.example` and `--apps.example` both hang off `apps.example`.
  const zone = suffix.replace(/^[^a-z0-9]+/, "");
  return host === zone || host.endsWith(suffix) || host.endsWith(`.${zone}`);
}
/** 24 characters of Crockford base32 — 120 bits — for the TXT record. */
export const TOKEN_LENGTH = 24;
const TOKEN_ALPHABET = "0123456789abcdefghjkmnpqrstvwxyz";
function newToken(): string {
  const bytes = new Uint8Array(TOKEN_LENGTH);
  crypto.getRandomValues(bytes);
  let out = "";
  for (const byte of bytes) out += TOKEN_ALPHABET[byte & 31];
  return out;
}
export function addDomain(
  db: Database,
  input: { host: string; appId: string; createdBy?: string | undefined },
  rules: DomainRules,
): Result<AppDomain, AddDomainError> {
  const host = normalizeHost(input.host);
  if (!isHostname(host)) return err("invalid_host");
  if (isReserved(host, rules)) return err("reserved_host");
  if (getDomain(db, host)) return err("taken");
  try {
    db.query(
      "INSERT INTO app_domain (host, app_id, env, token, created_by, created_at) VALUES (?1, ?2, 'production', ?3, ?4, ?5)",
    ).run(host, input.appId, newToken(), input.createdBy ?? null, now());
  } catch (error) {
    // Two racing adds: the primary key settles it, the check above only
    // named it early.
    if (
      error instanceof Error &&
      /UNIQUE constraint failed/.test(error.message)
    )
      return err("taken");
    throw error;
  }
  return ok(getDomain(db, host)!);
}
export function getDomain(db: Database, host: string): AppDomain | undefined {
  const row = db
    .query<DomainRow, [string]>("SELECT * FROM app_domain WHERE host = ?1")
    .get(normalizeHost(host));
  return row ? toDomain(row) : undefined;
}
/** The row for a host that has been verified — the only kind the proxy serves. */
export function getVerifiedDomain(
  db: Database,
  host: string,
): AppDomain | undefined {
  const found = getDomain(db, host);
  return found?.verifiedAt === null ? undefined : found;
}
/** An app's domains, oldest first. */
export function listDomains(db: Database, appId: string): AppDomain[] {
  return db
    .query<
      DomainRow,
      [string]
    >("SELECT * FROM app_domain WHERE app_id = ?1 ORDER BY created_at, host")
    .all(appId)
    .map(toDomain);
}
/**
 * The domain production's URL is built from: the one verified longest ago,
 * so a second domain added later never moves links that already work.
 */
export function primaryDomain(
  db: Database,
  appId: string,
): AppDomain | undefined {
  const row = db
    .query<
      DomainRow,
      [string]
    >("SELECT * FROM app_domain WHERE app_id = ?1 AND verified_at IS NOT NULL ORDER BY verified_at, host LIMIT 1")
    .get(appId);
  return row ? toDomain(row) : undefined;
}
export function removeDomain(db: Database, host: string): boolean {
  return (
    db.query("DELETE FROM app_domain WHERE host = ?1").run(normalizeHost(host))
      .changes > 0
  );
}
/**
 * What a check found. Verification is a proof of control at one moment,
 * like a certificate's: once given it stays, so a TXT record tidied away
 * later — or a resolver that would not answer today — never takes a live
 * site down. Removing the domain is the one way to unserve it.
 */
export function recordCheck(
  db: Database,
  host: string,
  check: { verified: boolean; said: string },
): AppDomain | undefined {
  const at = now();
  db.query(
    `UPDATE app_domain
       SET checked_at = ?2,
           said = ?3,
           verified_at = CASE WHEN ?4 = 1 AND verified_at IS NULL THEN ?2 ELSE verified_at END
     WHERE host = ?1`,
  ).run(normalizeHost(host), at, check.said, check.verified ? 1 : 0);
  return getDomain(db, host);
}
@@ -25,6 +25,7 @@
export function eventAudience(kind: string): EventAudience {
  if (
    kind.startsWith("webhook.") ||
    kind.startsWith("app.env_") ||
    kind.startsWith("app.domain.") ||
    kind === "repo.settings_updated"
  )
    return "admins";
@@ -879,4 +879,23 @@
export const migrations: readonly string[] = [
  DROP TABLE look;
  ALTER TABLE look_new RENAME TO look;
  `,
  // 32 — an app's own domains. One host names one app's production; the
  // token is published in DNS to prove the name is held, so it is not a
  // secret. `verified_at` is set by the first check that finds the proof
  // and never cleared by a later one; `said` is the last check's sentence.
  `
  CREATE TABLE app_domain (
    host        TEXT PRIMARY KEY,
    app_id      TEXT NOT NULL REFERENCES app(id) ON DELETE CASCADE,
    env         TEXT NOT NULL DEFAULT 'production',
    token       TEXT NOT NULL,
    created_by  TEXT REFERENCES user(id) ON DELETE SET NULL,
    created_at  TEXT NOT NULL,
    verified_at TEXT,
    checked_at  TEXT,
    said        TEXT NOT NULL DEFAULT ''
  );
  CREATE INDEX app_domain_app ON app_domain(app_id);
  `,
];
@@ -62,6 +62,13 @@
export function eventVerb(event: ForgeEvent): string {
      ? `set ${which} in the app's environment`
      : `removed ${which} from the app's environment`;
  }
  if (kind.startsWith("app.domain.")) {
    const host = payload["host"];
    const which = typeof host === "string" ? host : "a domain";
    if (kind === "app.domain.added") return `gave the app the domain ${which}`;
    if (kind === "app.domain.verified") return `verified the domain ${which}`;
    return `removed the domain ${which}`;
  }
  return WORDS[kind] ?? "acted on this repository";
}
@@ -153,6 +153,14 @@
import {
  updateAppSettings,
  type AppSettingsInput,
} from "../actions/apps.ts";
import {
  addAppDomain,
  checkAppDomain,
  listAppDomains,
  removeAppDomain,
} from "../actions/domains.ts";
import { listDomains } from "../core/domains.ts";
import type { Database } from "bun:sqlite";
import {
  migrateMessage,
  migrateRepo,
@@ -635,8 +643,12 @@
function repoQuery(ctx: Ctx) {
  };
}
/** An app as the API returns it, with what is running when a runtime is up. */
/**
 * An app as the API returns it, with what is running when a runtime is up
 * and the domains of its own that are verified — the ones the forge serves.
 */
function appJson(
  db: Database,
  record: AppRecord,
  repo: Repo,
  runtime: AppsRuntime | undefined,
@@ -645,6 +657,9 @@
function appJson(
    ...record,
    repo: { owner: repo.ownerName, name: repo.name },
    url: runtime?.urlFor(record, "production") ?? null,
    domains: listDomains(db, record.id)
      .filter((d) => d.verifiedAt !== null)
      .map((d) => d.host),
    serving: runtime !== undefined,
    environments: runtime?.status(record) ?? [],
  };
@@ -2672,7 +2687,7 @@
export function apiRoutes(router: Router<Handler>): void {
    for (const record of records) {
      const repo = repos.get(record.repoId);
      if (!repo || !canRead(ctx.app.db, repo, ctx.auth.user)) continue;
      items.push(appJson(record, repo, runtime));
      items.push(appJson(ctx.app.db, record, repo, runtime));
    }
    return json({ items, next_cursor: null });
  });
@@ -2696,7 +2711,12 @@
export function apiRoutes(router: Router<Handler>): void {
    return json(
      {
        repo: repoJson(ctx, made.value.repo),
        app: appJson(made.value.app, made.value.repo, appsRuntime(ctx.app)),
        app: appJson(
          ctx.app.db,
          made.value.app,
          made.value.repo,
          appsRuntime(ctx.app),
        ),
        issue: made.value.issue ? withLabels(ctx, made.value.issue) : null,
      },
      201,
@@ -2785,7 +2805,9 @@
export function apiRoutes(router: Router<Handler>): void {
    if (!repo) return notFound();
    const view = appView(ctx.app, ctx.auth.user, repo);
    if (!view.ok) return notFound();
    return json(appJson(view.value.app, repo, appsRuntime(ctx.app)));
    return json(
      appJson(ctx.app.db, view.value.app, repo, appsRuntime(ctx.app)),
    );
  });
  router.add("POST", "/api/v1/repos/:owner/:name/app", async (ctx) => {
@@ -2796,7 +2818,10 @@
export function apiRoutes(router: Router<Handler>): void {
    const input = await body(ctx.request);
    const enabled = enableApp(ctx.app, ctx.auth.user, repo, appPatch(input));
    if (!enabled.ok) return respondAccess(enabled.error, 422);
    return json(appJson(enabled.value, repo, appsRuntime(ctx.app)), 201);
    return json(
      appJson(ctx.app.db, enabled.value, repo, appsRuntime(ctx.app)),
      201,
    );
  });
  router.add("PATCH", "/api/v1/repos/:owner/:name/app", async (ctx) => {
@@ -2812,7 +2837,7 @@
export function apiRoutes(router: Router<Handler>): void {
      appPatch(input),
    );
    if (!updated.ok) return respondAccess(updated.error, 422);
    return json(appJson(updated.value, repo, appsRuntime(ctx.app)));
    return json(appJson(ctx.app.db, updated.value, repo, appsRuntime(ctx.app)));
  });
  router.add("DELETE", "/api/v1/repos/:owner/:name/app", (ctx) => {
@@ -2825,6 +2850,68 @@
export function apiRoutes(router: Router<Handler>): void {
    return json({}, 200);
  });
  // The app's own domains (docs/APPS.md, "Your own domain"). Admin scope
  // and admin over the repository, like the environment below; `:host` is
  // one path segment, dots included.
  router.add("GET", "/api/v1/repos/:owner/:name/app/domains", (ctx) => {
    const denied = requireScope(ctx, "admin");
    if (denied) return denied;
    const repo = loadRepo(ctx);
    if (!repo) return notFound();
    const listed = listAppDomains(ctx.app, ctx.auth.user, repo);
    if (!listed.ok) return respondAccess(listed.error, 422);
    return json({ items: listed.value, next_cursor: null });
  });
  router.add("POST", "/api/v1/repos/:owner/:name/app/domains", async (ctx) => {
    const denied = requireScope(ctx, "admin");
    if (denied) return denied;
    const repo = loadRepo(ctx);
    if (!repo) return notFound();
    const input = await body(ctx.request);
    const added = addAppDomain(ctx.app, ctx.auth.user, repo, str(input.host));
    if (!added.ok) return respondAccess(added.error, 422);
    return json(added.value, 201);
  });
  router.add(
    "POST",
    "/api/v1/repos/:owner/:name/app/domains/:host/check",
    async (ctx) => {
      const denied = requireScope(ctx, "admin");
      if (denied) return denied;
      const repo = loadRepo(ctx);
      if (!repo) return notFound();
      const checked = await checkAppDomain(
        ctx.app,
        ctx.auth.user,
        repo,
        ctx.params.host ?? "",
      );
      if (!checked.ok) return respondAccess(checked.error, 422);
      return json(checked.value);
    },
  );
  router.add(
    "DELETE",
    "/api/v1/repos/:owner/:name/app/domains/:host",
    (ctx) => {
      const denied = requireScope(ctx, "admin");
      if (denied) return denied;
      const repo = loadRepo(ctx);
      if (!repo) return notFound();
      const removed = removeAppDomain(
        ctx.app,
        ctx.auth.user,
        repo,
        ctx.params.host ?? "",
      );
      if (!removed.ok) return respondAccess(removed.error, 422);
      return json({}, 200);
    },
  );
  // The app's environment: names in, names out, and never a value back.
  // `:var`, not `:name` — `:name` is the repository's.
  router.add("GET", "/api/v1/repos/:owner/:name/app/env", (ctx) => {
@@ -160,6 +160,9 @@
import {
} from "../web/pages/pull.ts";
import {
  appDisable,
  appDomainAdd,
  appDomainCheck,
  appDomainDelete,
  appEnvDelete,
  appEnvSet,
  appSettingsPage,
@@ -275,6 +278,7 @@
import { Router } from "./router.ts";
import { getUserById } from "../core/users.ts";
import { appsRuntime } from "../apps/runtime.ts";
import { appWebSocket, proxyApp, resolveAppHost } from "../apps/proxy.ts";
import { getVerifiedDomain } from "../core/domains.ts";
// ---- auth ----
@@ -432,6 +436,20 @@
export function buildRouter(): Router<Handler> {
  // fetches a region and not the page. Literal, above /:owner.
  router.add("GET", "/live/apps", liveAppsFragment);
  router.add("GET", "/live/on-you", liveOnYouFragment);
  // Whether a hostname is an app's verified domain — what Caddy's
  // `on_demand_tls { ask … }` asks before it fetches a certificate for a
  // name it has never seen (docs/EXTRACT.md). 200 says yes, 404 says no,
  // and nothing else is told: a hostname is not a secret, an app is.
  // Literal, above /:owner.
  router.add("GET", "/__forge/domains/ask", (ctx) => {
    const host = ctx.url.searchParams.get("domain") ?? "";
    const known =
      host !== "" && getVerifiedDomain(ctx.app.db, host) !== undefined;
    return new Response(null, {
      status: known ? 200 : 404,
      headers: { "cache-control": "no-store" },
    });
  });
  router.add("GET", "/runs/:id", runRedirect);
  router.add("GET", "/settings", accountPage);
  router.add("POST", "/settings", accountUpdate);
@@ -779,6 +797,18 @@
export function buildRouter(): Router<Handler> {
    "/:owner/:name/settings/app/env/:var/delete",
    appEnvDelete,
  );
  // `:host` is one path segment — dots and all — like `:var` above it.
  router.add("POST", "/:owner/:name/settings/app/domains", appDomainAdd);
  router.add(
    "POST",
    "/:owner/:name/settings/app/domains/:host/check",
    appDomainCheck,
  );
  router.add(
    "POST",
    "/:owner/:name/settings/app/domains/:host/delete",
    appDomainDelete,
  );
  router.add("GET", "/:owner/:name/settings/crew", crewSettingsPage);
  router.add("POST", "/:owner/:name/settings/crew", crewAdd);
  router.add(
@@ -38,7 +38,7 @@
import {
} from "../../core/repos.ts";
import type { User } from "../../core/users.ts";
import { safeBack, type Ctx } from "../../http/context.ts";
import { resolveAppHostname } from "../../apps/proxy.ts";
import { isHostPort, resolveAppHostname } from "../../apps/proxy.ts";
import {
  crumbsFor,
  loadRepo,
@@ -845,7 +845,7 @@
export function appsOpen(ctx: Ctx): Response {
  const wanted = ctx.url.searchParams.get("to") ?? "/";
  const path =
    wanted.startsWith("/") && !wanted.startsWith("//") ? wanted : "/";
  if (runtime === undefined || host === "") return notFoundPage(ctx);
  if (runtime === undefined || !isHostPort(host)) return notFoundPage(ctx);
  const target = resolveAppHostname(ctx.app, runtime.options.domain, host);
  if (target === undefined || target === "unknown") return notFoundPage(ctx);
  if (!ctx.auth.user) return signInFirst(ctx);
@@ -402,6 +402,15 @@
const DESTRUCTIVE: {
      phrase: "",
    }),
  },
  {
    pattern: /^\/([^/]+)\/([^/]+)\/settings\/app\/domains\/([^/]+)\/delete$/,
    describe: (m) => ({
      verb: "Remove domain",
      title: `Remove ${decodeURIComponent(m[3] ?? "")}?`,
      detail: `The forge stops answering there at once; links to it stop working until the name is added and verified again. ${m[1]}/${m[2]} keeps its own hostname.`,
      phrase: "",
    }),
  },
  {
    pattern: /^\/([^/]+)\/([^/]+)\/settings\/labels\/([^/]+)\/delete$/,
    describe: (m) => ({
@@ -488,7 +497,9 @@
const DESTRUCTIVE: {
      // this page never becomes a way to read a private pull's title.
      const repo = getRepo(ctx.app.db, m[1]!, m[2]!);
      const writer = repo && canWrite(ctx.app.db, repo, ctx.auth.user);
      const pull = writer ? getPull(ctx.app.db, repo.id, Number(m[3])) : undefined;
      const pull = writer
        ? getPull(ctx.app.db, repo.id, Number(m[3]))
        : undefined;
      const name = pull ? `"${pull.title}"` : `change #${m[3]}`;
      return {
        verb: "Take it back",
@@ -15,6 +15,14 @@
import {
  setAppEnvVar,
  updateAppSettings,
} from "../../actions/apps.ts";
import {
  addAppDomain,
  checkAppDomain,
  listAppDomains,
  removeAppDomain,
  type AppDomainView,
} from "../../actions/domains.ts";
import type { DnsRecord } from "../../apps/domains.ts";
import {
  listAppEnvNames,
  NAME_MAX,
@@ -76,6 +84,7 @@
import { icon } from "../icons.ts";
import { flashTo, page } from "../layout.ts";
import type { Flash } from "../flash.ts";
import {
  badge,
  btn,
  card,
  confirmAction,
@@ -442,10 +451,14 @@
function appSettingsView(
    },
  );
  if (record === undefined) return form;
  const domains = listAppDomains(ctx.app, ctx.auth.user, repo);
  return html`${form}
    <div class="mt">
      ${appEnvView(base, listAppEnvNames(ctx.app.db, record.id))}
    </div>
    <div class="mt">
      ${appDomainsView(base, domains.ok ? domains.value : undefined)}
    </div>
    <div class="mt">
      ${card(
        html`<p>
@@ -553,6 +566,117 @@
function appEnvView(base: string, names: AppEnvName[]): Html {
  );
}
/**
 * The app's own domains: each with what the last check said, the records
 * to publish while it waits, and a form for one more. The forge serves a
 * domain the moment it is verified; the app itself hears its new address
 * at its next deploy, because a process reads its URL once, at start.
 * `undefined` is a forge where nothing serves apps: a domain would have
 * nowhere to point, so the card says so and offers no form.
 */
function appDomainsView(
  base: string,
  domains: AppDomainView[] | undefined,
): Html {
  const at = (host: string) =>
    `${base}/settings/app/domains/${encodeURIComponent(host)}`;
  const rows = (domains ?? []).map(
    (d) =>
      html`<li>
        <div class="row">
          <span class="row-lead">${icon("globe")}</span>
          <span class="row-main">
            <span class="row-title"
              ><span class="mono">${d.host}</span> ${d.verified
                ? badge("live", { tone: "success" })
                : badge("waiting for DNS", { tone: "attn" })}</span
            >
            <span class="row-meta" title="${d.said}"
              >${d.said === "" ? "Not checked yet." : d.said}
              ${d.checkedAt === null
                ? null
                : html` · checked ${time(d.checkedAt)}`}</span
            >
            ${when(!d.verified, () => recordsToPublish(d.records))}
          </span>
          <span class="row-trail">
            <form method="post" action="${at(d.host)}/check">
              ${btn("Check now", { size: "sm", icon: "globe" })}
            </form>
            ${confirmAction({
              action: `${at(d.host)}/delete`,
              verb: "Remove",
              size: "sm",
            })}
          </span>
        </div>
      </li>`,
  );
  return card(
    html`<div class="card-body">
        <p class="muted small">
          Serve the app at a name of your own —
          <span class="mono">app.example.com</span>, or an apex. Add it, publish
          the two records it shows, and press Check now.
        </p>
      </div>
      ${when(
        rows.length > 0,
        () =>
          html`<ul class="list">
            ${rows}
          </ul>`,
      )}
      ${domains === undefined
        ? html`<div class="card-body">
            <p class="muted small">
              Nothing is serving apps on this forge, so a domain would have
              nowhere to point.
            </p>
          </div>`
        : html`<div class="card-body">
              <p class="muted small">
                The forge serves the app there as soon as the record is
                verified. The app itself learns its new address at its next
                deploy.
              </p>
            </div>
            <form
              class="edit-row"
              method="post"
              action="${base}/settings/app/domains"
            >
              <input
                class="input mono"
                type="text"
                name="host"
                placeholder="app.example.com"
                aria-label="Domain"
                autocomplete="off"
                spellcheck="false"
                required
              />
              ${btn("Add", { variant: "primary", size: "sm", icon: "plus" })}
            </form>`}`,
    {
      head: html`${icon("globe")}
        <h2>Domains</h2>`,
      pad: false,
    },
  );
}
/** The records as a person copies them into a zone: type, name, value. */
function recordsToPublish(records: DnsRecord[]): Html {
  const width = Math.max(...records.map((r) => r.name.length)) + 2;
  const lines = records
    .map((r) => `${r.type.padEnd(6)} ${r.name.padEnd(width)} ${r.value}`)
    .join("\n");
  const notes = records.filter((r) => r.note !== undefined);
  return html`<pre class="domain-records">${lines}</pre>
    ${notes.map((r) => html`<span class="row-meta">${r.note}</span>`)}`;
}
const appValues = (repo: Repo, record: AppRecord | undefined): AppValues => ({
  slug: record?.slug ?? slugFor(repo.name),
  access: record?.access ?? repo.visibility,
@@ -702,6 +826,94 @@
export async function appEnvDelete(ctx: Ctx): Promise<Response> {
  );
}
const APP_DOMAIN_ERRORS: Record<string, string> = {
  invalid_host:
    "A domain is a hostname: letters, digits and hyphens in at least two labels, like app.example.com.",
  reserved_host: "That name is the forge's own to hand out.",
  taken: "Another app already answers to that domain.",
  no_runtime: "Nothing is serving apps on this forge.",
};
/** What the records say, as one flash: type, name and value, in words. */
function recordsInWords(records: DnsRecord[]): string {
  return records
    .map((r) =>
      r.type === "TXT"
        ? `a TXT record at ${r.name} with the value ${r.value}`
        : r.type === "CNAME"
          ? `a CNAME from ${r.name} to ${r.value}`
          : `an ALIAS from ${r.name} to ${r.value}`,
    )
    .join(" and ");
}
// POST /:owner/:name/settings/app/domains — add one.
export async function appDomainAdd(ctx: Ctx): Promise<Response> {
  const gate = await adminForm(ctx);
  if (gate instanceof Response) return gate;
  const { repo, form } = gate;
  const added = addAppDomain(ctx.app, ctx.auth.user, repo, field(form, "host"));
  if (!added.ok && added.error === "not_found") return repoNotFound(ctx);
  return flashTo(
    ctx,
    `${repoBase(repo)}/settings/app`,
    added.ok
      ? {
          message: `${added.value.host} is added. Publish ${recordsInWords(added.value.records)}, then press Check now.`,
        }
      : {
          tone: "danger",
          message:
            APP_DOMAIN_ERRORS[added.error] ?? "That domain could not be added.",
        },
  );
}
// POST /:owner/:name/settings/app/domains/:host/check — look the proof up.
export async function appDomainCheck(ctx: Ctx): Promise<Response> {
  const gate = await adminForm(ctx);
  if (gate instanceof Response) return gate;
  const { repo } = gate;
  const checked = await checkAppDomain(
    ctx.app,
    ctx.auth.user,
    repo,
    ctx.params.host ?? "",
  );
  if (!checked.ok && checked.error === "not_found") return repoNotFound(ctx);
  return flashTo(
    ctx,
    `${repoBase(repo)}/settings/app`,
    checked.ok
      ? {
          ...(checked.value.verified ? {} : { tone: "attn" as const }),
          message: checked.value.said,
        }
      : {
          tone: "danger",
          message:
            APP_DOMAIN_ERRORS[checked.error] ?? "No domain by that name.",
        },
  );
}
// POST /:owner/:name/settings/app/domains/:host/delete
export async function appDomainDelete(ctx: Ctx): Promise<Response> {
  const gate = await adminForm(ctx);
  if (gate instanceof Response) return gate;
  const { repo } = gate;
  const host = ctx.params.host ?? "";
  const removed = removeAppDomain(ctx.app, ctx.auth.user, repo, host);
  if (!removed.ok && removed.error === "not_found") return repoNotFound(ctx);
  return flashTo(
    ctx,
    `${repoBase(repo)}/settings/app`,
    removed.ok
      ? { message: `${host} is removed. The forge no longer answers there.` }
      : { tone: "danger", message: "No domain by that name." },
  );
}
/** What a change to the environment sets in motion — when anything serves. */
function redeploying(ctx: Ctx, how: string): string {
  return appsRuntime(ctx.app) === undefined
@@ -297,6 +297,8 @@
a.origin-chip:hover { border-color: var(--border-strong); color: var(--fg); }
.backups-now { margin-top: 12px; }
.backups-error { display: flex; align-items: center; gap: 8px; color: var(--danger); }
.backups-restore { margin: 8px 0 0; padding: 8px 10px; font-size: 12px; white-space: pre-wrap; word-break: break-all; background: var(--muted); border-radius: var(--radius); }
/* The records a domain waits on: type, name, value — as a zone file reads. */
.domain-records { margin: 6px 0 2px; padding: 8px 10px; font-size: 12px; line-height: 1.6; white-space: pre; overflow-x: auto; scrollbar-width: thin; background: var(--muted); border-radius: var(--radius); }
.policy-line {
  display: flex; align-items: center; gap: 8px; flex-wrap: wrap;
  margin: 12px 0 0; font-size: 13px; color: var(--muted-fg);
@@ -0,0 +1,706 @@
/**
 * An app gets a domain of its own (docs/APPS.md, "Your own domain"): the
 * names it may take, the two records to publish, what a check says, and
 * the moment the forge starts answering there — with a private app's
 * sign-in landing on the new host. DNS is a stand-in the test controls,
 * so nothing here touches the network.
 */
import { afterAll, beforeAll, describe, expect, test } from "bun:test";
import { mkdtemp, rm } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { createApp, type App } from "../src/app.ts";
import { newApp, updateAppSettings } from "../src/actions/apps.ts";
import {
  addAppDomain,
  checkAppDomain,
  removeAppDomain,
} from "../src/actions/domains.ts";
import { createRepo } from "../src/actions/repos.ts";
import {
  checkDomain,
  recordsFor,
  type DomainResolver,
} from "../src/apps/domains.ts";
import { AppsRuntime } from "../src/apps/runtime.ts";
import { createApp as insertApp, type AppRecord } from "../src/core/apps.ts";
import { addDomain, getDomain, TOKEN_LENGTH } from "../src/core/domains.ts";
import { listEvents } from "../src/core/events.ts";
import type { Repo } from "../src/core/repos.ts";
import { listRuns, type Run } from "../src/core/runs.ts";
import { createToken } from "../src/core/tokens.ts";
import { createUser, type User } from "../src/core/users.ts";
import { serve, type Servers } from "../src/http/server.ts";
import { quietLogs } from "./helpers/globals.ts";
quietLogs();
const DOMAIN = "apps.test";
const HOST = "app.example.com";
const PROOF = `_forge-verify.${HOST}`;
/** A resolver the test writes the zone of; anything unwritten does not exist. */
class FakeDns implements DomainResolver {
  readonly txt = new Map<string, string[][]>();
  readonly cname = new Map<string, string[]>();
  resolveTxt(name: string): Promise<string[][]> {
    return this.answer(this.txt.get(name));
  }
  resolveCname(name: string): Promise<string[]> {
    return this.answer(this.cname.get(name));
  }
  private answer<T>(found: T | undefined): Promise<T> {
    return found === undefined
      ? Promise.reject(Object.assign(new Error("no data"), { code: "ENODATA" }))
      : Promise.resolve(found);
  }
}
/** A page with its whitespace collapsed, for asserting on a sentence. */
const words = (html: string): string => html.replace(/\s+/g, " ");
describe("checkDomain: every outcome is a sentence", () => {
  const dns = new FakeDns();
  const token = "abcdefghjkmnpqrstvwxyz01";
  test("nothing published, another value, the proof, and where the name points", async () => {
    expect(await checkDomain(HOST, token, "notes.apps.test", dns)).toEqual({
      verified: false,
      said: `No TXT record at ${PROOF} yet.`,
    });
    dns.txt.set(PROOF, [["forge-verify=somethingelse"]]);
    expect(await checkDomain(HOST, token, "notes.apps.test", dns)).toEqual({
      verified: false,
      said: "The TXT record is there but holds a different value.",
    });
    // The right value beside a wrong one is still the proof; a record split
    // into chunks is read whole.
    dns.txt.set(PROOF, [
      ["forge-verify=somethingelse"],
      ["forge-", `verify=${token}`],
    ]);
    expect(await checkDomain(HOST, token, "notes.apps.test", dns)).toEqual({
      verified: true,
      said: `Verified; ${HOST} has no CNAME yet.`,
    });
    dns.cname.set(HOST, ["Notes.Apps.Test."]);
    expect(await checkDomain(HOST, token, "notes.apps.test", dns)).toEqual({
      verified: true,
      said: `Verified; ${HOST} points at notes.apps.test.`,
    });
    dns.cname.set(HOST, ["elsewhere.example"]);
    expect(await checkDomain(HOST, token, "notes.apps.test", dns)).toEqual({
      verified: true,
      said: `Verified; ${HOST} points at elsewhere.example, not notes.apps.test.`,
    });
  });
  test("a resolver that will not answer is a calm sentence, never a throw", async () => {
    const broken: DomainResolver = {
      resolveTxt: () =>
        Promise.reject(
          Object.assign(new Error("servfail"), { code: "ESERVFAIL" }),
        ),
      resolveCname: () => Promise.reject(new Error("boom")),
    };
    expect(await checkDomain(HOST, token, "notes.apps.test", broken)).toEqual({
      verified: false,
      said: `The DNS lookup for ${PROOF} failed (ESERVFAIL); try again in a minute.`,
    });
    const cnameOnlyBroken: DomainResolver = {
      resolveTxt: () => Promise.resolve([[`forge-verify=${token}`]]),
      resolveCname: () => Promise.reject(new Error("boom")),
    };
    expect(
      await checkDomain(HOST, token, "notes.apps.test", cnameOnlyBroken),
    ).toEqual({
      verified: true,
      said: `Verified; where ${HOST} points could not be looked up.`,
    });
  });
  test("an apex gets an ALIAS line instead of a CNAME, and is told why", () => {
    expect(recordsFor(HOST, token, "notes.apps.test")).toEqual([
      { type: "TXT", name: PROOF, value: `forge-verify=${token}` },
      { type: "CNAME", name: HOST, value: "notes.apps.test" },
    ]);
    const apex = recordsFor("example.com", token, "notes.apps.test");
    expect(apex[1]?.type).toBe("ALIAS");
    expect(apex[1]?.value).toBe("notes.apps.test");
    expect(apex[1]?.note).toContain("cannot carry a CNAME");
  });
});
describe("an app gets its own domain", () => {
  let dataDir: string;
  let app: App;
  let servers: Servers;
  let runtime: AppsRuntime;
  let alice: User;
  let bob: User;
  let repo: Repo;
  let record: AppRecord;
  let other: AppRecord;
  let otherRepo: Repo;
  let aliceCookie = "";
  let bobCookie = "";
  let adminToken = "";
  let rwToken = "";
  let bobToken = "";
  const dns = new FakeDns();
  const viaHost = (host: string, path = "/", init: RequestInit = {}) =>
    fetch(`${servers.url}${path}`, {
      ...init,
      headers: { host, ...(init.headers as Record<string, string>) },
      redirect: "manual",
    });
  /** A browser's request to the forge itself: a cookie, and a same-origin form. */
  const web = (
    cookie: string,
    path: string,
    init: RequestInit & { form?: Record<string, string>; origin?: string } = {},
  ): Promise<Response> => {
    const headers = new Headers(init.headers);
    if (cookie !== "") headers.set("cookie", cookie);
    const method = init.form !== undefined ? "POST" : (init.method ?? "GET");
    if (init.form !== undefined)
      headers.set("origin", init.origin ?? new URL(servers.url).origin);
    return fetch(`${servers.url}${path}`, {
      ...init,
      method,
      headers,
      redirect: "manual",
      ...(init.form === undefined
        ? {}
        : { body: new URLSearchParams(init.form) }),
    });
  };
  const flashOf = (response: Response): string =>
    decodeURIComponent(response.headers.get("set-cookie") ?? "");
  const api = (
    path: string,
    init: RequestInit & { token?: string | null } = {},
  ) => {
    const headers = new Headers(init.headers);
    if (typeof init.body === "string")
      headers.set("content-type", "application/json");
    const token = init.token === undefined ? adminToken : init.token;
    if (token) headers.set("authorization", `Bearer ${token}`);
    return fetch(`${servers.url}${path}`, { ...init, headers });
  };
  const DOMAINS = "/api/v1/repos/alice/notes/app/domains";
  const signIn = async (username: string): Promise<string> => {
    const response = await fetch(`${servers.url}/signin`, {
      method: "POST",
      body: new URLSearchParams({ username, password: "a-good-passphrase" }),
      redirect: "manual",
    });
    return `${(response.headers.get("set-cookie") ?? "").split(";")[0]!}; forge_mode=dev`;
  };
  async function until<T>(read: () => T | undefined, ms = 60_000): Promise<T> {
    const deadline = Date.now() + ms;
    while (Date.now() < deadline) {
      const value = read();
      if (value !== undefined) return value;
      await Bun.sleep(100);
    }
    throw new Error("did not happen in time");
  }
  const settled = (where: (run: Run) => boolean) =>
    until(() =>
      listRuns(app.db, repo.id, { kind: "deploy", limit: 50 }).find(
        (r) => where(r) && (r.state === "ok" || r.state === "failed"),
      ),
    );
  const kinds = (prefix: string): string[] =>
    listEvents(app.db, { repoId: repo.id, limit: 100 })
      .map((e) => e.kind)
      .filter((k) => k.startsWith(prefix));
  beforeAll(async () => {
    dataDir = await mkdtemp(join(tmpdir(), "forge-domains-"));
    // The forge's own hostname is `forge.test`: the one name no app may take.
    app = createApp({ dataDir, port: 0, host: "forge.test" });
    servers = await serve(app);
    runtime = new AppsRuntime(app, {
      domain: DOMAIN,
      scheme: "http",
      publicPort: servers.port,
      forgeUrl: servers.url,
      concurrency: 1,
      dns,
    });
    await runtime.start();
    const a = await createUser(app.db, {
      username: "alice",
      email: "[email protected]",
      password: "a-good-passphrase",
      adminIfFirst: true,
    });
    if (!a.ok) throw new Error(a.error);
    alice = a.value;
    const b = await createUser(app.db, {
      username: "bob",
      email: "[email protected]",
      password: "a-good-passphrase",
    });
    if (!b.ok) throw new Error(b.error);
    bob = b.value;
    aliceCookie = await signIn("alice");
    bobCookie = await signIn("bob");
    adminToken = createToken(app.db, alice.id, "admin", "admin").token;
    rwToken = createToken(app.db, alice.id, "rw", "rw").token;
    bobToken = createToken(app.db, bob.id, "admin", "admin").token;
    const made = await newApp(app, alice, {
      name: "notes",
      description: "A place for notes",
      visibility: "public",
    });
    if (!made.ok) throw new Error(String(made.error));
    repo = made.value.repo;
    record = made.value.app;
    // A second app, a row only: enough to contest a name.
    const plain = await createRepo(app, alice, {
      name: "other",
      visibility: "public",
      description: "",
    });
    if (!plain.ok) throw new Error(String(plain.error));
    otherRepo = plain.value;
    const row = insertApp(app.db, {
      repoId: otherRepo.id,
      slug: "other",
      access: "public",
    });
    if (!row.ok) throw new Error(row.error);
    other = row.value;
    const run = await settled((r) => r.env === "production");
    expect(run.state).toBe("ok");
    expect((await viaHost(`notes.${DOMAIN}`)).status).toBe(200);
  }, 120_000);
  afterAll(async () => {
    await runtime.stop();
    servers.stop();
    app.close();
    await rm(dataDir, { recursive: true, force: true });
  });
  test("what a domain may be: a hostname someone can own, and not the forge's", () => {
    const add = (host: string) => addAppDomain(app, alice, repo, host);
    for (const bad of ["bad_host", "-x.example.com", "1.2.3.4", "example"]) {
      const refused = add(bad);
      expect(refused.ok).toBe(false);
      if (!refused.ok)
        expect(`${bad}: ${refused.error}`).toBe(`${bad}: invalid_host`);
    }
    for (const ours of ["forge.test", `x.${DOMAIN}`, `a.b.${DOMAIN}`, DOMAIN]) {
      const refused = add(ours);
      expect(refused.ok).toBe(false);
      if (!refused.ok)
        expect(`${ours}: ${refused.error}`).toBe(`${ours}: reserved_host`);
    }
    // A forge whose apps hang off a single label (`--forge.example`)
    // reserves that whole shape, and the zone beneath it.
    const single = {
      forgeHost: "forge.example",
      appHostSuffix: "--forge.example",
    };
    for (const ours of [
      "notes--forge.example",
      "forge.example",
      "a.forge.example",
    ]) {
      const refused = addDomain(
        app.db,
        { host: ours, appId: record.id },
        single,
      );
      expect(refused.ok).toBe(false);
      if (!refused.ok)
        expect(`${ours}: ${refused.error}`).toBe(`${ours}: reserved_host`);
    }
    // Nothing above left a row behind.
    expect(getDomain(app.db, "forge.example")).toBeUndefined();
  });
  test("adding a domain answers with the two records to publish", () => {
    const added = addAppDomain(app, alice, repo, ` App.Example.Com. `);
    expect(added.ok).toBe(true);
    if (!added.ok) return;
    expect(added.value.host).toBe(HOST);
    expect(added.value.verified).toBe(false);
    expect(added.value.said).toBe("");
    const token = getDomain(app.db, HOST)!.token;
    expect(token).toMatch(new RegExp(`^[0-9a-hjkmnp-tv-z]{${TOKEN_LENGTH}}$`));
    expect(added.value.records).toEqual([
      { type: "TXT", name: PROOF, value: `forge-verify=${token}` },
      { type: "CNAME", name: HOST, value: `notes.${DOMAIN}` },
    ]);
    expect(kinds("app.domain.")).toEqual(["app.domain.added"]);
    // One host, one app: the same name for another app is taken, however
    // it is spelled.
    const contested = addAppDomain(app, alice, otherRepo, "APP.example.com");
    expect(contested.ok).toBe(false);
    if (!contested.ok) expect(contested.error).toBe("taken");
    expect(other.id).not.toBe(record.id);
    // An apex is told to use an ALIAS.
    const apex = addAppDomain(app, alice, repo, "example.com");
    expect(apex.ok).toBe(true);
    if (apex.ok) expect(apex.value.records[1]?.type).toBe("ALIAS");
  });
  test("before verification the forge answers for itself at the host", async () => {
    const page = await viaHost(HOST, "/");
    expect(page.status).toBe(200);
    expect(await page.text()).not.toContain("<h1>notes</h1>");
    expect(
      (await viaHost("forge.test", `/__forge/domains/ask?domain=${HOST}`))
        .status,
    ).toBe(404);
    expect(runtime.urlFor(record, "production")).toBe(
      `http://notes.${DOMAIN}:${servers.port}`,
    );
  });
  test("a check says what it found; the proof verifies the domain", async () => {
    const first = await checkAppDomain(app, alice, repo, HOST);
    expect(first.ok).toBe(true);
    if (!first.ok) return;
    expect(first.value.verified).toBe(false);
    expect(first.value.said).toBe(`No TXT record at ${PROOF} yet.`);
    expect(first.value.checkedAt).not.toBeNull();
    dns.txt.set(PROOF, [["forge-verify=not-this-one"]]);
    const wrong = await checkAppDomain(app, alice, repo, HOST);
    expect(wrong.ok && wrong.value.said).toBe(
      "The TXT record is there but holds a different value.",
    );
    expect(kinds("app.domain.verified")).toEqual([]);
    const token = getDomain(app.db, HOST)!.token;
    dns.txt.set(PROOF, [[`forge-verify=${token}`]]);
    dns.cname.set(HOST, [`notes.${DOMAIN}`]);
    const right = await checkAppDomain(app, alice, repo, HOST);
    expect(right.ok).toBe(true);
    if (!right.ok) return;
    expect(right.value.verified).toBe(true);
    expect(right.value.verifiedAt).not.toBeNull();
    expect(right.value.said).toBe(
      `Verified; ${HOST} points at notes.${DOMAIN}.`,
    );
    expect(kinds("app.domain.verified")).toEqual(["app.domain.verified"]);
    // Verified once is verified: a later check leaves its sentence and
    // says so a second time to nobody.
    dns.txt.delete(PROOF);
    const later = await checkAppDomain(app, alice, repo, HOST);
    expect(later.ok && later.value.verified).toBe(true);
    expect(later.ok && later.value.said).toBe(`No TXT record at ${PROOF} yet.`);
    expect(kinds("app.domain.verified")).toEqual(["app.domain.verified"]);
    dns.txt.set(PROOF, [[`forge-verify=${token}`]]);
    // A host that is not this app's is nobody's to check.
    const stranger = await checkAppDomain(app, alice, otherRepo, HOST);
    expect(stranger.ok).toBe(false);
    if (!stranger.ok) expect(stranger.error).toBe("no_such_domain");
  });
  test("verified, the forge serves the app at the host and every URL follows", async () => {
    const page = await viaHost(HOST, "/");
    expect(page.status).toBe(200);
    expect(await page.text()).toContain("<h1>notes</h1>");
    // The hostname the forge gave it keeps working beside the domain.
    expect(await (await viaHost(`notes.${DOMAIN}`)).text()).toContain(
      "<h1>notes</h1>",
    );
    expect(runtime.urlFor(record, "production")).toBe(`http://${HOST}`);
    expect(runtime.urlFor(record, "pull-3")).toBe(
      `http://notes--3.${DOMAIN}:${servers.port}`,
    );
    expect(runtime.hostFor(record.slug, "production")).toBe(`notes.${DOMAIN}`);
    const json = (await (
      await api("/api/v1/repos/alice/notes/app", { token: null })
    ).json()) as { url: string; domains: string[] };
    expect(json.url).toBe(`http://${HOST}`);
    expect(json.domains).toEqual([HOST]);
    // Caddy's question: is this name anyone's?
    const ask = (domain: string) =>
      viaHost("forge.test", `/__forge/domains/ask?domain=${domain}`);
    const yes = await ask(HOST);
    expect(yes.status).toBe(200);
    expect(await yes.text()).toBe("");
    expect((await ask("APP.EXAMPLE.COM.")).status).toBe(200);
    expect((await ask("example.com")).status).toBe(404);
    expect((await ask("nope.example.com")).status).toBe(404);
    expect((await viaHost("forge.test", "/__forge/domains/ask")).status).toBe(
      404,
    );
  });
  test("a private app's sign-in lands on the new host", async () => {
    expect(updateAppSettings(app, alice, repo, { access: "private" }).ok).toBe(
      true,
    );
    // A person arriving at the domain is sent to the forge to be vouched for.
    const arrived = await viaHost(HOST, "/", {
      headers: { accept: "text/html,*/*" },
    });
    expect(arrived.status).toBe(303);
    const open = new URL(arrived.headers.get("location") ?? "");
    expect(`${open.origin}${open.pathname}`).toBe(`${servers.url}/apps/open`);
    expect(open.searchParams.get("host")).toBe(HOST);
    // A script gets the flat answer.
    expect((await viaHost(HOST, "/")).status).toBe(404);
    // Signed in, alice is sent back to the domain with a grant; following
    // it sets the cookie for that host, and the page opens.
    const vouched = await web(aliceCookie, `${open.pathname}${open.search}`);
    expect(vouched.status).toBe(302);
    const grant = new URL(vouched.headers.get("location") ?? "");
    expect(grant.origin).toBe(`http://${HOST}`);
    expect(grant.pathname).toBe("/__forge/grant");
    const granted = await viaHost(HOST, `${grant.pathname}${grant.search}`);
    expect(granted.status).toBe(303);
    const cookie = granted.headers.get("set-cookie") ?? "";
    expect(cookie).toContain("forge_grant_");
    const greeted = await viaHost(HOST, "/", {
      headers: { cookie: cookie.split(";")[0]! },
    });
    expect(greeted.status).toBe(200);
    expect(await greeted.text()).toContain("<b>alice</b>");
    // Someone at the app's own hostname is granted there, port and all,
    // not sent across to the domain.
    const canonical = await web(
      aliceCookie,
      `/apps/open?host=${encodeURIComponent(`notes.${DOMAIN}:${servers.port}`)}&to=/`,
    );
    expect(canonical.status).toBe(302);
    expect(new URL(canonical.headers.get("location") ?? "").host).toBe(
      `notes.${DOMAIN}:${servers.port}`,
    );
    // A stranger to the repository gets what a private repository gives.
    expect(
      (await web(bobCookie, `${open.pathname}${open.search}`)).status,
    ).toBe(302);
    expect(updateAppSettings(app, alice, repo, { access: "public" }).ok).toBe(
      true,
    );
  });
  test("the settings page: the card, the records, the badge, and the doors", async () => {
    const settings = "/alice/notes/settings/app";
    const page = words(await (await web(aliceCookie, settings)).text());
    expect(page).toContain("Domains");
    expect(page).toContain(HOST);
    expect(page).toContain(">live<");
    // The apex waits, and shows what to publish.
    expect(page).toContain("waiting for DNS");
    expect(page).toContain("_forge-verify.example.com");
    expect(page).toContain(
      `forge-verify=${getDomain(app.db, "example.com")!.token}`,
    );
    expect(page).toContain("ALIAS");
    expect(page).toContain(`${settings}/domains/example.com/check`);
    expect(page).toContain(
      encodeURIComponent(`${settings}/domains/example.com/delete`),
    );
    expect(page).toContain("learns its new address at its next deploy");
    // Adding from the form flashes the records.
    const added = await web(aliceCookie, `${settings}/domains`, {
      form: { host: "staging.example.com" },
    });
    expect(added.status).toBe(303);
    expect(added.headers.get("location")).toBe(settings);
    expect(flashOf(added)).toContain("staging.example.com is added");
    expect(flashOf(added)).toContain("_forge-verify.staging.example.com");
    expect(flashOf(added)).toContain(
      `CNAME from staging.example.com to notes.${DOMAIN}`,
    );
    const refused = await web(aliceCookie, `${settings}/domains`, {
      form: { host: "not a host" },
    });
    expect(flashOf(refused)).toContain("A domain is a hostname");
    // Check now says what it found.
    const checked = await web(
      aliceCookie,
      `${settings}/domains/staging.example.com/check`,
      { form: {} },
    );
    expect(checked.status).toBe(303);
    expect(flashOf(checked)).toContain(
      "No TXT record at _forge-verify.staging.example.com yet.",
    );
    expect(words(await (await web(aliceCookie, settings)).text())).toContain(
      "No TXT record at _forge-verify.staging.example.com yet.",
    );
    // The confirm page knows this door.
    const confirm = await web(
      aliceCookie,
      `/-/confirm?to=${encodeURIComponent(`${settings}/domains/staging.example.com/delete`)}`,
    );
    expect(confirm.status).toBe(200);
    expect(await confirm.text()).toContain("Remove staging.example.com?");
    // Not for a non-admin — the one 404 — and not from another origin.
    expect((await web(bobCookie, settings)).status).toBe(404);
    expect(
      (
        await web(bobCookie, `${settings}/domains`, {
          form: { host: "stolen.example.com" },
        })
      ).status,
    ).toBe(404);
    expect(
      (
        await web(bobCookie, `${settings}/domains/staging.example.com/delete`, {
          form: {},
        })
      ).status,
    ).toBe(404);
    expect(
      (
        await web(aliceCookie, `${settings}/domains`, {
          form: { host: "stolen.example.com" },
          origin: "https://evil.example",
        })
      ).status,
    ).toBe(403);
    expect(getDomain(app.db, "stolen.example.com")).toBeUndefined();
    expect(getDomain(app.db, "staging.example.com")).toBeDefined();
    const removed = await web(
      aliceCookie,
      `${settings}/domains/staging.example.com/delete`,
      { form: {} },
    );
    expect(removed.status).toBe(303);
    expect(flashOf(removed)).toContain("staging.example.com is removed");
    expect(getDomain(app.db, "staging.example.com")).toBeUndefined();
    const again = await web(
      aliceCookie,
      `${settings}/domains/staging.example.com/delete`,
      { form: {} },
    );
    expect(flashOf(again)).toContain("No domain by that name");
  });
  test("the API: admin scope and admin over the repository, like the environment", async () => {
    const listed = (await (await api(DOMAINS)).json()) as {
      items: { host: string; verified: boolean; records: unknown[] }[];
    };
    expect(listed.items.map((d) => [d.host, d.verified])).toEqual([
      [HOST, true],
      ["example.com", false],
    ]);
    expect(listed.items[0]?.records).toHaveLength(2);
    const added = await api(DOMAINS, {
      method: "POST",
      body: JSON.stringify({ host: "api.example.com" }),
    });
    expect(added.status).toBe(201);
    const item = (await added.json()) as {
      host: string;
      verified: boolean;
      records: { type: string; name: string }[];
    };
    expect(item.host).toBe("api.example.com");
    expect(item.verified).toBe(false);
    expect(item.records.map((r) => r.type)).toEqual(["TXT", "CNAME"]);
    const refusals: [string, string][] = [
      ["bad_host", "invalid_host"],
      [`x.${DOMAIN}`, "reserved_host"],
      [HOST, "taken"],
    ];
    for (const [host, error] of refusals) {
      const refused = await api(DOMAINS, {
        method: "POST",
        body: JSON.stringify({ host }),
      });
      expect(refused.status).toBe(422);
      expect(((await refused.json()) as { error: string }).error).toBe(error);
    }
    const checked = await api(`${DOMAINS}/api.example.com/check`, {
      method: "POST",
    });
    expect(checked.status).toBe(200);
    expect(((await checked.json()) as { said: string }).said).toBe(
      "No TXT record at _forge-verify.api.example.com yet.",
    );
    expect(
      (await api(`${DOMAINS}/nobody.example.com/check`, { method: "POST" }))
        .status,
    ).toBe(422);
    // The floors: scope, then admin over the repository — a stranger with
    // an admin token is not told the app has domains at all.
    expect((await api(DOMAINS, { token: rwToken })).status).toBe(403);
    expect((await api(DOMAINS, { token: null })).status).toBe(401);
    expect((await api(DOMAINS, { token: bobToken })).status).toBe(404);
    expect(
      (
        await api(DOMAINS, {
          method: "POST",
          body: JSON.stringify({ host: "stolen.example.com" }),
          token: bobToken,
        })
      ).status,
    ).toBe(404);
    expect(
      (
        await api(`${DOMAINS}/api.example.com`, {
          method: "DELETE",
          token: rwToken,
        })
      ).status,
    ).toBe(403);
    expect(getDomain(app.db, "api.example.com")).toBeDefined();
    const removed = await api(`${DOMAINS}/api.example.com`, {
      method: "DELETE",
    });
    expect(removed.status).toBe(200);
    expect(await removed.json()).toEqual({});
    expect(getDomain(app.db, "api.example.com")).toBeUndefined();
  });
  test("removal makes the host unknown again", async () => {
    const removed = removeAppDomain(app, alice, repo, HOST);
    expect(removed.ok).toBe(true);
    // Newest first: the removal, after everything the page and the API did.
    expect(kinds("app.domain.")[0]).toBe("app.domain.removed");
    expect(kinds("app.domain.removed")).toHaveLength(3);
    const page = await viaHost(HOST, "/");
    expect(page.status).toBe(200);
    expect(await page.text()).not.toContain("<h1>notes</h1>");
    expect(
      (await viaHost("forge.test", `/__forge/domains/ask?domain=${HOST}`))
        .status,
    ).toBe(404);
    expect(runtime.urlFor(record, "production")).toBe(
      `http://notes.${DOMAIN}:${servers.port}`,
    );
    // The name is free again — for anyone, with a new token.
    const oldToken = getDomain(app.db, "example.com")!.token;
    const reclaimed = addAppDomain(app, alice, otherRepo, HOST);
    expect(reclaimed.ok).toBe(true);
    expect(getDomain(app.db, HOST)!.appId).toBe(other.id);
    expect(getDomain(app.db, HOST)!.token).not.toBe(oldToken);
    expect(removeAppDomain(app, alice, repo, HOST).ok).toBe(false);
  });
});
@@ -0,0 +1,131 @@
/**
 * `/apps/open?host=` sends a signed grant to the host it names. That host
 * is read twice — once as an app label, once by a URL parser to build the
 * redirect — and the two readings must agree: `evil#x--notes.apps.test`
 * once passed the label check (no dot, last part a real slug) while the
 * parser called its host `evil`, and a valid grant left for a stranger's
 * origin. Now only a bare hostname, with at most a port, is a host at all.
 */
import { afterAll, beforeAll, describe, expect, test } from "bun:test";
import { mkdtemp, rm } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { createApp, type App } from "../src/app.ts";
import { newApp, updateAppSettings } from "../src/actions/apps.ts";
import { AppsRuntime } from "../src/apps/runtime.ts";
import { createToken } from "../src/core/tokens.ts";
import { createUser, type User } from "../src/core/users.ts";
import { serve, type Servers } from "../src/http/server.ts";
import type { Repo } from "../src/core/repos.ts";
import type { AppRecord } from "../src/core/apps.ts";
import { quietLogs } from "./helpers/globals.ts";
quietLogs();
const DOMAIN = "apps.test";
describe("/apps/open sends a grant only to a host that reads one way", () => {
  let dataDir: string;
  let app: App;
  let servers: Servers;
  let runtime: AppsRuntime;
  let alice: User;
  let repo: Repo;
  let record: AppRecord;
  let aliceCookie = "";
  const signIn = async (username: string): Promise<string> => {
    const response = await fetch(`${servers.url}/signin`, {
      method: "POST",
      body: new URLSearchParams({ username, password: "a-good-passphrase" }),
      redirect: "manual",
    });
    return `${(response.headers.get("set-cookie") ?? "").split(";")[0]!}; forge_mode=dev`;
  };
  beforeAll(async () => {
    dataDir = await mkdtemp(join(tmpdir(), "forge-open-redirect-"));
    app = createApp({ dataDir, port: 0, host: "forge.test" });
    servers = await serve(app);
    runtime = new AppsRuntime(app, {
      domain: DOMAIN,
      scheme: "http",
      publicPort: servers.port,
      forgeUrl: servers.url,
      concurrency: 1,
    });
    await runtime.start();
    const a = await createUser(app.db, {
      username: "alice",
      email: "[email protected]",
      password: "a-good-passphrase",
      adminIfFirst: true,
    });
    if (!a.ok) throw new Error(a.error);
    alice = a.value;
    aliceCookie = await signIn("alice");
    const made = await newApp(app, alice, {
      name: "notes",
      description: "A place for notes",
      visibility: "public",
    });
    if (!made.ok) throw new Error(String(made.error));
    repo = made.value.repo;
    record = made.value.app;
  }, 120_000);
  afterAll(async () => {
    await runtime.stop();
    servers.stop();
    app.close();
    await rm(dataDir, { recursive: true, force: true });
  });
  const open = (host: string) => {
    const u = new URL(`${servers.url}/apps/open`);
    u.searchParams.set("host", host);
    u.searchParams.set("to", "/");
    return fetch(u, { headers: { cookie: aliceCookie }, redirect: "manual" });
  };
  test("a plain app host, with or without a port, is granted on itself", async () => {
    const plain = await open(`notes.${DOMAIN}`);
    expect(plain.status).toBe(302);
    expect(new URL(plain.headers.get("location")!).hostname).toBe(
      `notes.${DOMAIN}`,
    );
    const ported = await open(`notes.${DOMAIN}:8443`);
    expect(ported.status).toBe(302);
    expect(new URL(ported.headers.get("location")!).host).toBe(
      `notes.${DOMAIN}:8443`,
    );
  });
  test("a host a URL parser would read as another machine is not a host", async () => {
    for (const crafted of [
      `evil#stuff--notes.${DOMAIN}`,
      `2130706433@notes--${DOMAIN}`,
      `evil.example/@notes.${DOMAIN}`,
      `notes.${DOMAIN}/x`,
      `notes.${DOMAIN}?x`,
      `notes.${DOMAIN}:80:80`,
      `-notes.${DOMAIN}`,
    ]) {
      const res = await open(crafted);
      expect([crafted, res.status]).toEqual([crafted, 404]);
      expect(res.headers.get("location")).toBeNull();
    }
  });
  test("the proxy reads such a Host the same way: not ours", async () => {
    const res = await fetch(`${servers.url}/`, {
      headers: { host: `evil#stuff--notes.${DOMAIN}` },
      redirect: "manual",
    });
    // The forge answers for itself, as for any hostname it does not know.
    expect(res.status).toBe(200);
    expect(await res.text()).toContain("<title>");
  });
});
		@@ -422,6 +422,59 @@ ping for 120 seconds is dropped. The app's own 101 response headers are
422	422	not carried — a cookie an app sets on the handshake does not reach the
423	423	browser.
424	424
	425	## Your own domain
	426
	427	An app can answer at a name you own — `app.example.com`, or an apex like
	428	`example.com` — beside the hostname the forge gave it. Under **Settings →
	429	App → Domains** an admin of the repository adds the name (or `POST
	430	/api/v1/repos/:owner/:name/app/domains` with a `{ "host" }` body) and is
	431	shown the two records to publish in the zone:
	432
	433	- a TXT record at `_forge-verify.<host>` whose value is `forge-verify=<token>`
	434	— the proof that whoever added the name holds it. The token is made for
	435	that one domain and is not a secret: it is published;
	436	- a CNAME from `<host>` to the app's own hostname (`notes.forge.example`),
	437	which carries the traffic. An apex cannot carry a CNAME: use the DNS
	438	provider's ALIAS or ANAME record instead, or A and AAAA records with the
	439	address the forge is served at.
	440
	441	The forge checks when asked — Check now on the page, or `POST
	442	…/app/domains/:host/check` — never on a timer. It looks the TXT record up;
	443	the domain is verified when some record there is exactly the value shown.
	444	Every check leaves one sentence a person can act on ("No TXT record at
	445	`_forge-verify.app.example.com` yet.", "The TXT record is there but holds a
	446	different value.", "Verified; app.example.com points at
	447	notes.forge.example."), and when it was said. Verification is a proof of
	448	control at one moment, like a certificate's: the first check that finds the
	449	record verifies the domain, and a record tidied away later does not take a
	450	live site down. Removing the domain is what stops the forge answering there.
	451
	452	Once verified, the forge serves the app at that host — production, at the
	453	same port, through the same proxy, with the same grant — and production's
	454	URL becomes `https://app.example.com`: every "Open the app" link, the app's
	455	JSON `url`, and the `FORGE_APP_URL` its process starts with. The app itself
	456	learns its new address at its next deploy, because a process reads its
	457	environment once. Until a domain is verified the forge answers for itself
	458	at that name, exactly as it does for any hostname it does not know; a name
	459	that is nobody's proof serves nobody's app. The hostname the forge gave the
	460	app keeps working beside the domain.
	461
	462	A private app's sign-in works on the new host as it does on the old: a
	463	visitor arriving at `app.example.com` is sent to the forge, vouched for, and
	464	sent back to `app.example.com/__forge/grant`, where the grant cookie is set
	465	for that host. One host names one app's production; a second domain on the
	466	same app is served too, and the oldest verified one is the URL.
	467
	468	Whatever fronts the forge must route the name to it. A wildcard certificate
	469	covers `*.forge.example` and not `app.example.com`, so the proxy needs a
	470	certificate per domain. With Caddy, `on_demand_tls` fetches one the first
	471	time a name is asked for, and asks the forge first whether the name is
	472	anyone's: `GET /__forge/domains/ask?domain=<host>` answers 200 for a
	473	verified domain and 404 for anything else, so a stranger cannot make the
	474	proxy fetch certificates for names that are not here (`docs/EXTRACT.md`
	475	has the Caddyfile). A tunnel routes the host the way it routes the
	476	wildcard. The forge itself speaks plain HTTP either way.
	477
425	478	## A release does not drop a session
426	479
427	480	The forge is one process on one volume, and a release replaces it. The new
		@@ -693,7 +746,7 @@ the data directory `FORGE_APP_DATA`, and the defaults become
693	746	Containers. An app runs as the forge's own user, in its own directory, and
694	747	nothing more separates it from the host than that. On the machine one
695	748	person owns this is the honest, fast answer; a sandboxed runtime is the
696		next layer, and the process boundary here is where it will attach. Custom
697		domains, TLS termination, and an approve-and-land gate are additions of
698		the same kind: the shapes above hold, and a new column or listener carries
699		each of them.
	749	next layer, and the process boundary here is where it will attach. TLS
	750	termination and an approve-and-land gate are additions of the same kind:
	751	the shapes above hold, and a new column or listener carries each of them —
	752	as one column carried a domain of the app's own.
		@@ -44,7 +44,31 @@ turned off, with what each move costs and what it gives up.
44	44	`forge.example, *.forge.example { reverse_proxy 127.0.0.1:3000 }` with a
45	45	DNS-challenge wildcard, or the existing Cloudflare tunnel with two ingress
46	46	rules to `http://127.0.0.1:3000`. Either way the forge sees
47		`x-forwarded-proto` and answers with its canonical URL.
	47	`x-forwarded-proto` and answers with its canonical URL. An app's own
	48	domain (`docs/APPS.md`, _Your own domain_) is a name the wildcard does
	49	not cover, so Caddy fetches its certificate on demand — after asking the
	50	forge whether the name is anyone's:
	51
	52	```
	53	{
	54	on_demand_tls {
	55	ask http://127.0.0.1:3000/__forge/domains/ask
	56	}
	57	}
	58	forge.example, *.forge.example {
	59	reverse_proxy 127.0.0.1:3000
	60	}
	61	https:// {
	62	tls { on_demand }
	63	reverse_proxy 127.0.0.1:3000
	64	}
	65	```
	66
	67	The forge answers the ask with 200 for a verified domain and 404 for
	68	anything else, so nobody can make the proxy fetch certificates for names
	69	that are not here. With the tunnel, each domain is one more ingress rule
	70	to the same address.
	71
48	72	5. DNS cutover. Point `forge.example` and the wildcard at the box (or
49	73	the tunnel). The old cluster keeps serving until the switch; after it,
50	74	the platform's forge is a copy nobody visits.
		@@ -8,7 +8,7 @@
8	8
9	9	import type { App } from "../app.ts";
10	10	import { appsRuntime, type EnvStatus } from "../apps/runtime.ts";
11		import { grantUrl } from "../apps/proxy.ts";
	11	import { grantUrl, originFor } from "../apps/proxy.ts";
12	12	import { scaffoldFiles } from "../apps/scaffold.ts";
13	13	import {
14	14	isEnvName,
		@@ -323,7 +323,10 @@ export async function newApp(
323	323	{
324	324	name: input.name,
325	325	description,
326		agents: agents.map((a) => ({ name: a.user.username, brief: a.brief })),
	326	agents: agents.map((a) => ({
	327	name: a.user.username,
	328	brief: a.brief,
	329	})),
327	330	},
328	331	{ binary },
329	332	);
		@@ -474,9 +477,8 @@ export function openEnvUrl(
474	477	return ok(grantUrl(runtime, { app: record, env }, path, host, who));
475	478	}
476	479	if (record.access === "private") return err("unauthorized");
477		const base = new URL(runtime.urlFor(record, env));
478		if (host !== undefined) base.hostname = host.replace(/:\d+$/, "");
479		return ok(`${base.origin}${path === "/" ? "" : path}`);
	480	const origin = originFor(runtime, { app: record, env }, host);
	481	return ok(`${origin}${path === "/" ? "" : path}`);
480	482	}
481	483
482	484	/** Deploy an environment again at its current commit. */
		@@ -0,0 +1,198 @@
	1	/**
	2	* Domain actions: give an app a name of its own, check that the person who
	3	* added it holds it, and take it away. Admin over the repository, like
	4	* every other app setting. The check is the one thing here that leaves the
	5	* box — a DNS lookup — and it happens when someone asks, never on a timer.
	6	*/
	7
	8	import type { App } from "../app.ts";
	9	import { checkDomain, recordsFor, type DnsRecord } from "../apps/domains.ts";
	10	import { appHostSuffix } from "../apps/host.ts";
	11	import { appsRuntime, type AppsRuntime } from "../apps/runtime.ts";
	12	import { getAppByRepo, type AppRecord } from "../core/apps.ts";
	13	import {
	14	addDomain,
	15	getDomain,
	16	listDomains,
	17	recordCheck,
	18	removeDomain,
	19	type AddDomainError,
	20	type AppDomain,
	21	} from "../core/domains.ts";
	22	import type { Repo } from "../core/repos.ts";
	23	import type { User } from "../core/users.ts";
	24	import { err, ok, type Result } from "../kernel/result.ts";
	25	import { requireRepoAdmin } from "./access.ts";
	26
	27	/** A domain as a page or the API shows it: the facts, and what to publish. */
	28	export interface AppDomainView {
	29	readonly host: string;
	30	readonly verified: boolean;
	31	readonly verifiedAt: string \| null;
	32	readonly checkedAt: string \| null;
	33	readonly said: string;
	34	/** The proof, and where the traffic goes. */
	35	readonly records: DnsRecord[];
	36	}
	37
	38	export type DomainError = "not_found" \| "no_runtime";
	39
	40	/** The admin, and the app they administer. */
	41	function admitted(
	42	app: App,
	43	actor: User \| undefined,
	44	repo: Repo,
	45	): Result<{ admin: User; record: AppRecord }, "not_found"> {
	46	const admin = requireRepoAdmin(app, actor, repo);
	47	if (!admin.ok) return admin;
	48	const record = getAppByRepo(app.db, repo.id);
	49	if (!record) return err("not_found");
	50	return ok({ admin: admin.value, record });
	51	}
	52
	53	/** A domain has nowhere to point when nothing serves apps. */
	54	function serving(app: App): Result<AppsRuntime, "no_runtime"> {
	55	const runtime = appsRuntime(app);
	56	return runtime === undefined ? err("no_runtime") : ok(runtime);
	57	}
	58
	59	/** The forge's own hostname — the one name no app may take. */
	60	function forgeHost(app: App): string {
	61	return app.config.url !== undefined
	62	? new URL(app.config.url).hostname
	63	: (app.config.host ?? "localhost");
	64	}
	65
	66	/** One of this app's domains, by host — never another app's. */
	67	function ownedDomain(
	68	app: App,
	69	record: AppRecord,
	70	host: string,
	71	): AppDomain \| undefined {
	72	const domain = getDomain(app.db, host);
	73	return domain?.appId === record.id ? domain : undefined;
	74	}
	75
	76	function view(
	77	runtime: AppsRuntime,
	78	record: AppRecord,
	79	domain: AppDomain,
	80	): AppDomainView {
	81	return {
	82	host: domain.host,
	83	verified: domain.verifiedAt !== null,
	84	verifiedAt: domain.verifiedAt,
	85	checkedAt: domain.checkedAt,
	86	said: domain.said,
	87	records: recordsFor(
	88	domain.host,
	89	domain.token,
	90	runtime.hostFor(record.slug, domain.env),
	91	),
	92	};
	93	}
	94
	95	export function listAppDomains(
	96	app: App,
	97	actor: User \| undefined,
	98	repo: Repo,
	99	): Result<AppDomainView[], DomainError> {
	100	const gate = admitted(app, actor, repo);
	101	if (!gate.ok) return gate;
	102	const runtime = serving(app);
	103	if (!runtime.ok) return runtime;
	104	return ok(
	105	listDomains(app.db, gate.value.record.id).map((domain) =>
	106	view(runtime.value, gate.value.record, domain),
	107	),
	108	);
	109	}
	110
	111	/** Add a domain; the answer carries the two records to publish. */
	112	export function addAppDomain(
	113	app: App,
	114	actor: User \| undefined,
	115	repo: Repo,
	116	host: string,
	117	): Result<AppDomainView, DomainError \| AddDomainError> {
	118	const gate = admitted(app, actor, repo);
	119	if (!gate.ok) return gate;
	120	const runtime = serving(app);
	121	if (!runtime.ok) return runtime;
	122	const { admin, record } = gate.value;
	123	const added = addDomain(
	124	app.db,
	125	{ host, appId: record.id, createdBy: admin.id },
	126	{
	127	forgeHost: forgeHost(app),
	128	appHostSuffix: appHostSuffix(
	129	runtime.value.options.domain.toLowerCase().replace(/:\d+$/, ""),
	130	),
	131	},
	132	);
	133	if (!added.ok) return added;
	134	app.bus.append({
	135	kind: "app.domain.added",
	136	repoId: repo.id,
	137	actorId: admin.id,
	138	payload: { host: added.value.host, slug: record.slug },
	139	});
	140	return ok(view(runtime.value, record, added.value));
	141	}
	142
	143	/**
	144	* Look the proof up now. The first check that finds it verifies the domain
	145	* for good and says so on the bus; every check leaves its sentence.
	146	*/
	147	export async function checkAppDomain(
	148	app: App,
	149	actor: User \| undefined,
	150	repo: Repo,
	151	host: string,
	152	): Promise<Result<AppDomainView, DomainError \| "no_such_domain">> {
	153	const gate = admitted(app, actor, repo);
	154	if (!gate.ok) return gate;
	155	const runtime = serving(app);
	156	if (!runtime.ok) return runtime;
	157	const { admin, record } = gate.value;
	158	const domain = ownedDomain(app, record, host);
	159	if (domain === undefined) return err("no_such_domain");
	160	const found = await checkDomain(
	161	domain.host,
	162	domain.token,
	163	runtime.value.hostFor(record.slug, domain.env),
	164	runtime.value.options.dns,
	165	);
	166	const updated = recordCheck(app.db, domain.host, found) ?? domain;
	167	if (found.verified && domain.verifiedAt === null) {
	168	app.bus.append({
	169	kind: "app.domain.verified",
	170	repoId: repo.id,
	171	actorId: admin.id,
	172	payload: { host: domain.host, slug: record.slug },
	173	});
	174	}
	175	return ok(view(runtime.value, record, updated));
	176	}
	177
	178	/** Take a domain away. The forge stops answering there at once. */
	179	export function removeAppDomain(
	180	app: App,
	181	actor: User \| undefined,
	182	repo: Repo,
	183	host: string,
	184	): Result<void, "not_found" \| "no_such_domain"> {
	185	const gate = admitted(app, actor, repo);
	186	if (!gate.ok) return gate;
	187	const { admin, record } = gate.value;
	188	const domain = ownedDomain(app, record, host);
	189	if (domain === undefined \|\| !removeDomain(app.db, domain.host))
	190	return err("no_such_domain");
	191	app.bus.append({
	192	kind: "app.domain.removed",
	193	repoId: repo.id,
	194	actorId: admin.id,
	195	payload: { host: domain.host, slug: record.slug },
	196	});
	197	return ok();
	198	}
		@@ -0,0 +1,154 @@
	1	/**
	2	* Proving a domain, and saying what was found. The person who adds
	3	* `app.example.com` publishes two records: a TXT under `_forge-verify.`
	4	* carrying the token the forge gave them, which proves they hold the name,
	5	* and a CNAME to the app's own hostname, which carries the traffic. Only
	6	* the TXT decides; the CNAME is reported, because a name can reach the
	7	* forge in more ways than one — an apex through ALIAS or A records, a
	8	* tunnel. Every outcome of a lookup — no record, another value, a resolver
	9	* that will not answer — is a sentence a person can act on, never a throw.
	10	*/
	11
	12	import { resolveCname, resolveTxt } from "node:dns/promises";
	13
	14	export interface DnsRecord {
	15	readonly type: "TXT" \| "CNAME" \| "ALIAS";
	16	readonly name: string;
	17	readonly value: string;
	18	/** A word of explanation, when the record needs one. */
	19	readonly note?: string;
	20	}
	21
	22	const VERIFY_LABEL = "_forge-verify";
	23
	24	export const verifyName = (host: string): string => `${VERIFY_LABEL}.${host}`;
	25	export const verifyValue = (token: string): string => `forge-verify=${token}`;
	26
	27	/** A name of exactly two labels cannot carry a CNAME. */
	28	export const isApex = (host: string): boolean => host.split(".").length === 2;
	29
	30	const APEX_NOTE =
	31	"An apex cannot carry a CNAME: use your DNS provider's ALIAS or ANAME record to point it at the app's hostname, or A and AAAA records with the address the forge is served at.";
	32
	33	/** The two records to publish for `host`, given the app's own hostname. */
	34	export function recordsFor(
	35	host: string,
	36	token: string,
	37	appHost: string,
	38	): DnsRecord[] {
	39	const proof: DnsRecord = {
	40	type: "TXT",
	41	name: verifyName(host),
	42	value: verifyValue(token),
	43	};
	44	return isApex(host)
	45	? [proof, { type: "ALIAS", name: host, value: appHost, note: APEX_NOTE }]
	46	: [proof, { type: "CNAME", name: host, value: appHost }];
	47	}
	48
	49	/** What a check asks of DNS — the system resolver, or a test's stand-in. */
	50	export interface DomainResolver {
	51	resolveTxt(name: string): Promise<string[][]>;
	52	resolveCname(name: string): Promise<string[]>;
	53	}
	54
	55	const systemResolver: DomainResolver = { resolveTxt, resolveCname };
	56
	57	/** How long a lookup may take before it is called a timeout. */
	58	const LOOKUP_TIMEOUT_MS = 5_000;
	59
	60	export interface DomainCheck {
	61	readonly verified: boolean;
	62	/** One plain sentence: what was found, and what to do about it. */
	63	readonly said: string;
	64	}
	65
	66	/**
	67	* Look the proof up, and — once it is there — where the name points.
	68	* `verified` iff some TXT record at `_forge-verify.<host>` is exactly
	69	* `forge-verify=<token>`.
	70	*/
	71	export async function checkDomain(
	72	host: string,
	73	token: string,
	74	appHost: string,
	75	resolver: DomainResolver = systemResolver,
	76	): Promise<DomainCheck> {
	77	const name = verifyName(host);
	78	const proof = await lookup(() => resolver.resolveTxt(name));
	79	if (proof.kind === "none")
	80	return { verified: false, said: `No TXT record at ${name} yet.` };
	81	if (proof.kind === "failed")
	82	return {
	83	verified: false,
	84	said: `The DNS lookup for ${name} ${proof.why}; try again in a minute.`,
	85	};
	86	const values = proof.value.map((chunks) => chunks.join(""));
	87	if (!values.includes(verifyValue(token)))
	88	return {
	89	verified: false,
	90	said: "The TXT record is there but holds a different value.",
	91	};
	92	return {
	93	verified: true,
	94	said: `Verified; ${await pointing(host, appHost, resolver)}.`,
	95	};
	96	}
	97
	98	/** Where the name sends traffic, as one clause of the verified sentence. */
	99	async function pointing(
	100	host: string,
	101	appHost: string,
	102	resolver: DomainResolver,
	103	): Promise<string> {
	104	if (isApex(host))
	105	return `${host} is an apex, so point it at ${appHost} with an ALIAS record or at the forge's address`;
	106	const cname = await lookup(() => resolver.resolveCname(host));
	107	if (cname.kind === "none") return `${host} has no CNAME yet`;
	108	if (cname.kind === "failed")
	109	return `where ${host} points could not be looked up`;
	110	const first = cname.value[0];
	111	if (first === undefined) return `${host} has no CNAME yet`;
	112	const target = canonical(first);
	113	return target === canonical(appHost)
	114	? `${host} points at ${appHost}`
	115	: `${host} points at ${target}, not ${appHost}`;
	116	}
	117
	118	const canonical = (name: string): string =>
	119	name.toLowerCase().replace(/\.$/, "");
	120
	121	type Lookup<T> =
	122	\| { kind: "found"; value: T }
	123	\| { kind: "none" }
	124	\| { kind: "failed"; why: string };
	125
	126	/**
	127	* One lookup, with every way it can go wrong folded into a value. "No such
	128	* record" and "no such name" both mean nothing is published yet; anything
	129	* else is the resolver's trouble, named so the sentence can carry it.
	130	*/
	131	async function lookup<T>(run: () => Promise<T>): Promise<Lookup<T>> {
	132	let timer: ReturnType<typeof setTimeout> \| undefined;
	133	const timeout = new Promise<never>((_, reject) => {
	134	timer = setTimeout(
	135	() => reject(Object.assign(new Error("timed out"), { code: "ETIMEOUT" })),
	136	LOOKUP_TIMEOUT_MS,
	137	);
	138	});
	139	try {
	140	return { kind: "found", value: await Promise.race([run(), timeout]) };
	141	} catch (error) {
	142	const code =
	143	typeof error === "object" && error !== null && "code" in error
	144	? String((error as { code: unknown }).code)
	145	: "";
	146	if (code === "ENODATA" \|\| code === "ENOTFOUND") return { kind: "none" };
	147	return {
	148	kind: "failed",
	149	why: code === "ETIMEOUT" ? "timed out" : `failed (${code \|\| "error"})`,
	150	};
	151	} finally {
	152	clearTimeout(timer);
	153	}
	154	}
		@@ -17,7 +17,8 @@
17	17	import { appHostSuffix } from "./host.ts";
18	18	import { createHmac, timingSafeEqual } from "node:crypto";
19	19	import type { App } from "../app.ts";
20		import { getAppBySlug, type AppRecord } from "../core/apps.ts";
	20	import { getAppById, getAppBySlug, type AppRecord } from "../core/apps.ts";
	21	import { getVerifiedDomain } from "../core/domains.ts";
21	22	import { err, ok, type Result } from "../kernel/result.ts";
22	23	import { loadKey } from "../kernel/secret.ts";
23	24	import { previewEnv, type EnvName } from "./data.ts";
		@@ -34,6 +35,15 @@ export interface AppTarget {
34	35	readonly nested?: boolean;
35	36	}
36	37
	38	/**
	39	* What a `Host` may look like before it is read as anything: a hostname of
	40	* letters, digits, dots and hyphens, and at most a port. Nothing here can
	41	* be reparsed into another host by a URL parser (`#`, `@`, `/`, `?`,
	42	* spaces), so every reading below agrees on which machine is meant.
	43	*/
	44	export const isHostPort = (host: string): boolean =>
	45	/^[a-z0-9](?:[a-z0-9.-]{0,252})?(?::\d{1,5})?$/i.test(host);
	46
37	47	/**
38	48	* Which app and environment a `Host` names, if any. Hostnames are
39	49	* case-insensitive and may carry a port. Only one label may sit in front
		@@ -43,6 +53,7 @@ export function parseAppHost(
43	53	hostHeader: string,
44	54	domain: string,
45	55	): { slug: string; env: EnvName; nested: boolean } \| undefined {
	56	if (!isHostPort(hostHeader)) return undefined;
46	57	const host = hostHeader.toLowerCase().replace(/:\d+$/, "");
47	58	const suffix = appHostSuffix(domain.toLowerCase().replace(/:\d+$/, ""));
48	59	if (!host.endsWith(suffix)) return undefined;
		@@ -89,13 +100,54 @@ export function resolveAppHostname(
89	100	host: string,
90	101	): AppTarget \| "unknown" \| undefined {
91	102	const parsed = parseAppHost(host, domain);
92		if (parsed === undefined) return undefined;
	103	if (parsed === undefined) return ownDomain(app, host);
93	104	const record = getAppBySlug(app.db, parsed.slug);
94	105	return record
95	106	? { app: record, env: parsed.env, nested: parsed.nested }
96	107	: "unknown";
97	108	}
98	109
	110	/**
	111	* A hostname that is no label of ours may still be an app's own domain,
	112	* once the person who added it has proved they hold it (core/domains.ts).
	113	* Until then, and for every other name, the forge answers for itself —
	114	* its own pages, at whatever name it is reached by — so a domain added
	115	* but not yet verified serves nothing of the app.
	116	*/
	117	function ownDomain(app: App, host: string): AppTarget \| undefined {
	118	const domain = getVerifiedDomain(app.db, host.replace(/:\d+$/, ""));
	119	if (domain === undefined) return undefined;
	120	const record = getAppById(app.db, domain.appId);
	121	return record === undefined
	122	? undefined
	123	: { app: record, env: domain.env, nested: false };
	124	}
	125
	126	/**
	127	* The origin a visitor is sent back to: the hostname they asked for, at
	128	* the port they asked for it on when the name carried one; otherwise the
	129	* environment's own URL decides the port. An app's canonical host carries
	130	* the forge's, its own domain none — and only what the browser sent says
	131	* which the visitor is at.
	132	*/
	133	export function originFor(
	134	runtime: AppsRuntime,
	135	target: AppTarget,
	136	host?: string,
	137	): string {
	138	const base = new URL(runtime.urlFor(target.app, target.env));
	139	// Only a bare hostname, with or without a port, is a place to send
	140	// anyone. A URL parser reads `evil#x--notes.apps.test` as the host `evil`
	141	// while the label check above read it as ours — the same string must
	142	// never mean two hosts, so anything else is not a host at all.
	143	if (host === undefined \|\| !isHostPort(host)) return base.origin;
	144	const asked = URL.parse(`${base.protocol}//${host}`);
	145	if (asked === null) return base.origin;
	146	base.hostname = asked.hostname;
	147	if (asked.port !== "") base.port = asked.port;
	148	return base.origin;
	149	}
	150
99	151	/**
100	152	* The grant cookie is named for the app it admits to. Two forges can set
101	153	* grants on one hostname — this one, and a forge it hosts, for an app of
		@@ -240,11 +292,10 @@ export function grantUrl(
240	292	);
241	293	// The cookie a grant sets belongs to one hostname. A visitor who asked
242	294	// for a hostname inside the app's own world — an app of a forge hosted
243		// here — must be granted on that hostname, not the app's canonical one,
	295	// here, or the app's canonical host when it has a domain of its own —
	296	// must be granted on that hostname, not the one production's URL names,
244	297	// or the cookie lands where the request never goes.
245		const base = new URL(runtime.urlFor(target.app, target.env));
246		if (host !== undefined) base.hostname = host.replace(/:\d+$/, "");
247		return `${base.origin}/__forge/grant?t=${encodeURIComponent(token)}&to=${encodeURIComponent(path)}`;
	298	return `${originFor(runtime, target, host)}/__forge/grant?t=${encodeURIComponent(token)}&to=${encodeURIComponent(path)}`;
248	299	}
249	300
250	301	const HOP_BY_HOP = [
		@@ -43,7 +43,9 @@ import { createLog } from "../kernel/log.ts";
43	43	import type { Result } from "../kernel/result.ts";
44	44	import { holdLease, STALE_AFTER_MS } from "../runs/lease.ts";
45	45	import { appendRunLog } from "../runs/log.ts";
	46	import { primaryDomain } from "../core/domains.ts";
46	47	import { exportTree, readFileAt } from "./checkout.ts";
	48	import type { DomainResolver } from "./domains.ts";
47	49	import {
48	50	appsRoot,
49	51	ensureEnvData,
		@@ -89,6 +91,11 @@ export interface RuntimeOptions {
89	91	\| undefined;
90	92	/** How often the runtime looks for environments to put to sleep. */
91	93	readonly sweepEveryMs?: number \| undefined;
	94	/**
	95	* What a domain check asks: the system resolver unless a test hands in
	96	* its own, so proving `app.example.com` needs no network in a test.
	97	*/
	98	readonly dns?: DomainResolver \| undefined;
92	99	}
93	100
94	101	export type EnvState =
		@@ -294,7 +301,19 @@ export class AppsRuntime {
294	301	return sshCommand(this.app, login);
295	302	}
296	303
	304	/**
	305	* Where an environment is reached. Production answers at the app's own
	306	* domain once one is verified — every link, the app's JSON `url` and the
	307	* `FORGE_APP_URL` its next process starts with all follow — and at
	308	* `<slug>.<domain>` until then; a preview is always at its label. A
	309	* domain carries no port: it reaches the forge through whatever fronts
	310	* it, which holds its own.
	311	*/
297	312	urlFor(record: AppRecord, env: EnvName): string {
	313	if (env === "production") {
	314	const own = primaryDomain(this.app.db, record.id);
	315	if (own !== undefined) return `${this.options.scheme}://${own.host}`;
	316	}
298	317	const port =
299	318	this.options.publicPort === undefined \|\|
300	319	(this.options.scheme === "http" && this.options.publicPort === 80) \|\|
		@@ -0,0 +1,207 @@
	1	/**
	2	* An app's own domains — the rows. `app.example.com` is served by the forge
	3	* once the person who added it has shown they hold the name: a TXT record
	4	* carrying the token the row remembers. The token is published in DNS, so
	5	* it is not a secret; the proof is that only the zone's owner could put it
	6	* there. Pure data: no DNS, no authz, no events. What is published and how
	7	* it is checked is `apps/domains.ts`.
	8	*/
	9
	10	import type { Database } from "bun:sqlite";
	11	import type { EnvName } from "../apps/data.ts";
	12	import { err, ok, type Result } from "../kernel/result.ts";
	13
	14	export interface AppDomain {
	15	readonly host: string;
	16	readonly appId: string;
	17	/** The environment the host reaches — production, for now. */
	18	readonly env: EnvName;
	19	/** Published in DNS as `forge-verify=<token>`, to prove control of the name. */
	20	readonly token: string;
	21	readonly createdBy: string \| null;
	22	readonly createdAt: string;
	23	readonly verifiedAt: string \| null;
	24	readonly checkedAt: string \| null;
	25	/** What the last check said, one sentence for a person. */
	26	readonly said: string;
	27	}
	28
	29	interface DomainRow {
	30	host: string;
	31	app_id: string;
	32	env: EnvName;
	33	token: string;
	34	created_by: string \| null;
	35	created_at: string;
	36	verified_at: string \| null;
	37	checked_at: string \| null;
	38	said: string;
	39	}
	40
	41	const toDomain = (r: DomainRow): AppDomain => ({
	42	host: r.host,
	43	appId: r.app_id,
	44	env: r.env,
	45	token: r.token,
	46	createdBy: r.created_by,
	47	createdAt: r.created_at,
	48	verifiedAt: r.verified_at,
	49	checkedAt: r.checked_at,
	50	said: r.said,
	51	});
	52
	53	const now = (): string => new Date().toISOString();
	54
	55	/**
	56	* The names an app may not take: the forge's own hostname, and anything
	57	* that hangs off the app domain — those are the forge's to hand out
	58	* (`<slug>.<domain>`), and a row here would shadow them.
	59	*/
	60	export interface DomainRules {
	61	/** The forge's own hostname, lowercase. */
	62	readonly forgeHost: string;
	63	/** What app hostnames attach to (`appHostSuffix`), when apps are served. */
	64	readonly appHostSuffix?: string \| undefined;
	65	}
	66
	67	export type AddDomainError = "invalid_host" \| "reserved_host" \| "taken";
	68
	69	/** A hostname the way DNS wants it: lowercase, no trailing dot. */
	70	export function normalizeHost(host: string): string {
	71	return host.trim().toLowerCase().replace(/\.$/, "");
	72	}
	73
	74	const LABEL = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
	75
	76	/**
	77	* A hostname a person can own: at least two labels of letters, digits and
	78	* inside hyphens, and not an address. A last label of digits is an IPv4
	79	* literal or a name no URL can hold, and is refused either way.
	80	*/
	81	export function isHostname(host: string): boolean {
	82	if (host.length === 0 \|\| host.length > 253) return false;
	83	const labels = host.split(".");
	84	if (labels.length < 2 \|\| !labels.every((label) => LABEL.test(label)))
	85	return false;
	86	return !/^\d+$/.test(labels.at(-1)!);
	87	}
	88
	89	function isReserved(host: string, rules: DomainRules): boolean {
	90	if (host === rules.forgeHost.toLowerCase()) return true;
	91	const suffix = rules.appHostSuffix?.toLowerCase();
	92	if (suffix === undefined) return false;
	93	// `.apps.example` and `--apps.example` both hang off `apps.example`.
	94	const zone = suffix.replace(/^[^a-z0-9]+/, "");
	95	return host === zone \|\| host.endsWith(suffix) \|\| host.endsWith(`.${zone}`);
	96	}
	97
	98	/** 24 characters of Crockford base32 — 120 bits — for the TXT record. */
	99	export const TOKEN_LENGTH = 24;
	100	const TOKEN_ALPHABET = "0123456789abcdefghjkmnpqrstvwxyz";
	101
	102	function newToken(): string {
	103	const bytes = new Uint8Array(TOKEN_LENGTH);
	104	crypto.getRandomValues(bytes);
	105	let out = "";
	106	for (const byte of bytes) out += TOKEN_ALPHABET[byte & 31];
	107	return out;
	108	}
	109
	110	export function addDomain(
	111	db: Database,
	112	input: { host: string; appId: string; createdBy?: string \| undefined },
	113	rules: DomainRules,
	114	): Result<AppDomain, AddDomainError> {
	115	const host = normalizeHost(input.host);
	116	if (!isHostname(host)) return err("invalid_host");
	117	if (isReserved(host, rules)) return err("reserved_host");
	118	if (getDomain(db, host)) return err("taken");
	119	try {
	120	db.query(
	121	"INSERT INTO app_domain (host, app_id, env, token, created_by, created_at) VALUES (?1, ?2, 'production', ?3, ?4, ?5)",
	122	).run(host, input.appId, newToken(), input.createdBy ?? null, now());
	123	} catch (error) {
	124	// Two racing adds: the primary key settles it, the check above only
	125	// named it early.
	126	if (
	127	error instanceof Error &&
	128	/UNIQUE constraint failed/.test(error.message)
	129	)
	130	return err("taken");
	131	throw error;
	132	}
	133	return ok(getDomain(db, host)!);
	134	}
	135
	136	export function getDomain(db: Database, host: string): AppDomain \| undefined {
	137	const row = db
	138	.query<DomainRow, [string]>("SELECT * FROM app_domain WHERE host = ?1")
	139	.get(normalizeHost(host));
	140	return row ? toDomain(row) : undefined;
	141	}
	142
	143	/** The row for a host that has been verified — the only kind the proxy serves. */
	144	export function getVerifiedDomain(
	145	db: Database,
	146	host: string,
	147	): AppDomain \| undefined {
	148	const found = getDomain(db, host);
	149	return found?.verifiedAt === null ? undefined : found;
	150	}
	151
	152	/** An app's domains, oldest first. */
	153	export function listDomains(db: Database, appId: string): AppDomain[] {
	154	return db
	155	.query<
	156	DomainRow,
	157	[string]
	158	>("SELECT * FROM app_domain WHERE app_id = ?1 ORDER BY created_at, host")
	159	.all(appId)
	160	.map(toDomain);
	161	}
	162
	163	/**
	164	* The domain production's URL is built from: the one verified longest ago,
	165	* so a second domain added later never moves links that already work.
	166	*/
	167	export function primaryDomain(
	168	db: Database,
	169	appId: string,
	170	): AppDomain \| undefined {
	171	const row = db
	172	.query<
	173	DomainRow,
	174	[string]
	175	>("SELECT * FROM app_domain WHERE app_id = ?1 AND verified_at IS NOT NULL ORDER BY verified_at, host LIMIT 1")
	176	.get(appId);
	177	return row ? toDomain(row) : undefined;
	178	}
	179
	180	export function removeDomain(db: Database, host: string): boolean {
	181	return (
	182	db.query("DELETE FROM app_domain WHERE host = ?1").run(normalizeHost(host))
	183	.changes > 0
	184	);
	185	}
	186
	187	/**
	188	* What a check found. Verification is a proof of control at one moment,
	189	* like a certificate's: once given it stays, so a TXT record tidied away
	190	* later — or a resolver that would not answer today — never takes a live
	191	* site down. Removing the domain is the one way to unserve it.
	192	*/
	193	export function recordCheck(
	194	db: Database,
	195	host: string,
	196	check: { verified: boolean; said: string },
	197	): AppDomain \| undefined {
	198	const at = now();
	199	db.query(
	200	`UPDATE app_domain
	201	SET checked_at = ?2,
	202	said = ?3,
	203	verified_at = CASE WHEN ?4 = 1 AND verified_at IS NULL THEN ?2 ELSE verified_at END
	204	WHERE host = ?1`,
	205	).run(normalizeHost(host), at, check.said, check.verified ? 1 : 0);
	206	return getDomain(db, host);
	207	}
		@@ -25,6 +25,7 @@ export function eventAudience(kind: string): EventAudience {
25	25	if (
26	26	kind.startsWith("webhook.") \|\|
27	27	kind.startsWith("app.env_") \|\|
	28	kind.startsWith("app.domain.") \|\|
28	29	kind === "repo.settings_updated"
29	30	)
30	31	return "admins";
		@@ -879,4 +879,23 @@ export const migrations: readonly string[] = [
879	879	DROP TABLE look;
880	880	ALTER TABLE look_new RENAME TO look;
881	881	`,
	882
	883	// 32 — an app's own domains. One host names one app's production; the
	884	// token is published in DNS to prove the name is held, so it is not a
	885	// secret. `verified_at` is set by the first check that finds the proof
	886	// and never cleared by a later one; `said` is the last check's sentence.
	887	`
	888	CREATE TABLE app_domain (
	889	host TEXT PRIMARY KEY,
	890	app_id TEXT NOT NULL REFERENCES app(id) ON DELETE CASCADE,
	891	env TEXT NOT NULL DEFAULT 'production',
	892	token TEXT NOT NULL,
	893	created_by TEXT REFERENCES user(id) ON DELETE SET NULL,
	894	created_at TEXT NOT NULL,
	895	verified_at TEXT,
	896	checked_at TEXT,
	897	said TEXT NOT NULL DEFAULT ''
	898	);
	899	CREATE INDEX app_domain_app ON app_domain(app_id);
	900	`,
882	901	];