@monster-orange/den 0.4.20 → 0.4.21

package/CHANGELOG.md

@@ -4,6 +4,102 @@ All notable changes to Den are documented here. Each release lists the
 config and manifest changes a distribution must make to move to it under
 **Migrations**.
 
+## [0.4.21] - 2026-11-09
+
+### Added
+
+- **Every developer connects GitHub from the browser (D17).** A company
+  makes its own Den repo, every developer runs their own instance, and
+  everyone opens the same edge URL (such as `https://den.local.<zone>`,
+  whose DNS says 127.0.0.1). Before, they all got the signed-out page with
+  no way in from the browser: behind Docker Desktop, OrbStack or a TCP
+  passthrough the edge sees a gateway's address, so Den couldn't tell a
+  browser on its own machine; the one-time link needed a terminal, pairing
+  needed Settings, and Sign in with GitHub needed an owner already linked.
+  Now, while an instance has no owner, the signed-out page leads with
+  **Connect your GitHub account**:
+  - **This is my computer** (for a member of `web.allowed_github_org`):
+    a top-level round trip through `http://localhost:<port>/attest`, which
+    only a browser on this machine reaches, back to the edge page with a
+    short-lived, single-use code bound to that edge hostname and signed
+    with `web.secret` (in the URL fragment, never logged; only to this
+    Den's own edge hostnames). The GitHub sign-in that follows makes a
+    member of the org the owner and signs the browser in. The proof alone
+    never makes a session (any program on the machine can reach
+    localhost), so the GitHub approval is always the person's.
+  - **Sign in as @login** (`web.owner_github`): that login claims it from
+    any browser, such as a laptop reaching a devbox.
+  - Anyone else is refused with the reason (not a member; a member but not
+    on this computer; not that login; a private membership the GitHub App
+    can't read, naming the fix). With neither set, the page names both
+    settings and offers no claim.
+- **`create --github-org <org>`** writes `web.allowed_github_org` into the
+  team config; without the flag it uses the GitHub owner of the repo the
+  new folder is in, else writes a commented line and says to set it
+  (`create --json`: `githubOrg`, null when unknown).
+- **`web up`, `web restart` and `service install` record
+  `web.owner_github`** in `config/local/user.yml` from `gh api user` when
+  `gh` is signed in, no owner is linked and it isn't set, and print it.
+  When `gh` isn't signed in, they and `doctor` say so, with the fix
+  (`gh auth login`, or set `web.owner_github`).
+- **doctor** shows who may claim the instance (`web:owner` in
+  `doctor --json`), and fails when there is no owner, neither setting, and
+  the edge is reachable from other machines.
+- **`web.login_link_ttl` (D16)**: how long a sign-in link lasts, 5 minutes
+  unless set (it was 60 s, and expired while people switched windows);
+  30s to 60m. `web login` shows the time left while it waits.
+
+### Fixed
+
+- doctor no longer shows `usage (invalid config) ✗ unavailable: no selector
+  for this kind` on every fresh install (D9). Usage sources are all read at
+  once, so the row names them (`claude-code (implicit)`), as any strategy
+  kind with no selector of its own now does; never a failure. The state
+  column lines up past 20 characters.
+- **Every page was broken for a distribution whose name has a hyphen**
+  (`acme-den`), since 0.4.20 at least. `header.js` put the
+  `__DEN_CLI__` placeholder inside a variable name, so the served file
+  read `let _acme-denConfig`, a syntax error: no page mounted anything,
+  the signed-out page included ("Error / local"), and Settings showed an
+  error. A new check fills every served page and script with hyphenated,
+  digit-bearing and short names and parses each one, and no placeholder
+  may touch a name's letters.
+- `/attest` reached through the edge shows its own "only on the computer
+  this Den runs on" page, not the generic signed-out one.
+- doctor, when `web.owner_github` isn't set but `gh` is signed in, says to
+  run `web restart` to record it (not that gh isn't signed in).
+
+### Changed
+
+- The sign-in smoke runs against a remote browser with `DEN_PW_WS` (a
+  Playwright run-server): WebKit from Playwright's Linux image when the
+  shell can't start a GUI app (CONTRIBUTING.md).
+- The GitHub code on the sign-in page has its copy button right beside it,
+  on its line (as every command on that page), at any width.
+- Tests put a stub `launchctl` first on PATH, as for gh and the agent
+  CLIs: no test can reach this machine's real launchd.
+- Pages, `--version`, doctor and the server agent's name say the brand's
+  name (`brand.name` in the org config: "Sign in to Acme Den"), not the CLI
+  name upper-cased ("Acme-den") (D11). A `brand.name` with characters that
+  could break a page (quotes, `&`, `<`) falls back to the old title.
+- `product.cli` in den.yml must be lower-case letters, digits and `-`,
+  starting with a letter (as `product.name`). `product.config`,
+  `manifest`, `services_dir` and `workspaces_dir` may use letters, digits,
+  `.`, `_`, `-` and `/` only: the pages carry these names, and a quote or
+  `$` would break their scripts. A value outside that is refused at start,
+  naming the key.
+- The page behind a `web login` link that asks for its code is a plain
+  sign-in page: no shell frame and no request id, the code field focused.
+
+### Migrations
+
+- A `product.cli` or product path outside the characters above now stops
+  the CLI and server with a message naming the key: rename it.
+- To let your team connect GitHub from the browser, set
+  `web.allowed_github_org: <your GitHub org>` in the team config (or run
+  `web up` with `gh` signed in, for `web.owner_github`). The GitHub App
+  needs the org's Members (read) permission to see private memberships.
+
 ## [0.4.20] - 2026-11-09
 
 ### Added

package/README.md

@@ -10,8 +10,8 @@
 </p>
 
 <picture>
-  <source media="(prefers-color-scheme: dark)" srcset="docs/images/0.4.20/hero-dark.png">
-  <img src="docs/images/0.4.20/hero-light.png" width="100%" alt="Den's Graph page: the demo workspace's services grouped by application, all healthy, with the status chip and the left rail">
+  <source media="(prefers-color-scheme: dark)" srcset="docs/images/0.4.21/hero-dark.png">
+  <img src="docs/images/0.4.21/hero-light.png" width="100%" alt="Den's Graph page: the demo workspace's services grouped by application, all healthy, with the status chip and the left rail">
 </picture>
 
 ## Set up by your agent
@@ -39,7 +39,7 @@ It doesn't replace your tools. Your repos, Docker, your test runners, your secre
 yours. Den connects them and turns on good practice from the start.
 
 <p align="center">
-  <img src="docs/images/0.4.20/up.gif" width="100%" alt="make up in the Graph page: every stack down, then demo-api, demo-web and demo-notes come up in dependency order until the status chip reads All 3 healthy">
+  <img src="docs/images/0.4.21/up.gif" width="100%" alt="make up in the Graph page: every stack down, then demo-api, demo-web and demo-notes come up in dependency order until the status chip reads All 3 healthy">
 </p>
 
 ## How it helps
@@ -69,10 +69,10 @@ yours. Den connects them and turns on good practice from the start.
   lives in your own repo.
 
 <p align="center">
-  <img src="docs/images/0.4.20/agents.png" width="49%" alt="The Agents tab: the demo workspace's sessions on the left, and one open in a terminal pane on the right, running demo-api's test and then the service">
-  <img src="docs/images/0.4.20/workspaces.png" width="49%" alt="The Workspaces page: the demo workspace's repos with their health, mode and Start, Stop, Restart and Logs actions">
-  <img src="docs/images/0.4.20/status-drawer.png" width="49%" alt="The status drawer: nothing needs attention, and every service in the demo workspace, by application, with its latency">
-  <img src="docs/images/0.4.20/edge.png" width="49%" alt="The Edge page: the edge container up, its ports and TLS, and every route it serves, Den's own and each stack's, with its upstream">
+  <img src="docs/images/0.4.21/agents.png" width="49%" alt="The Agents tab: the demo workspace's sessions on the left, and one open in a terminal pane on the right, running demo-api's test and then the service">
+  <img src="docs/images/0.4.21/workspaces.png" width="49%" alt="The Workspaces page: the demo workspace's repos with their health, mode and Start, Stop, Restart and Logs actions">
+  <img src="docs/images/0.4.21/status-drawer.png" width="49%" alt="The status drawer: nothing needs attention, and every service in the demo workspace, by application, with its latency">
+  <img src="docs/images/0.4.21/edge.png" width="49%" alt="The Edge page: the edge container up, its ports and TLS, and every route it serves, Den's own and each stack's, with its upstream">
 </p>
 
 ## Get started

package/docs/distributions.md

@@ -1004,15 +1004,21 @@ brand:
     - "  └───────────┘"
 ```
 
-| Field     | Used for                                                                     |
-| --------- | ---------------------------------------------------------------------------- |
-| `name`    | Web page `<title>`s, the banner fallback, the web route on the edge (`acme`) |
-| `tagline` | The line under the banner                                                    |
-| `banner`  | The CLI and web server startup banner                                        |
+| Field     | Used for                                                                                                                                                                 |
+| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `name`    | The name people see: page titles and copy ("Sign in to Acme Den"), `--version`, doctor, the server agent's name, the banner fallback, the web route on the edge (`acme`) |
+| `tagline` | The line under the banner                                                                                                                                                |
+| `banner`  | The CLI and web server startup banner                                                                                                                                    |
 
 Runtime names (env vars, files, directories) always come from `den.yml`,
 never from the brand.
 
+`brand.name` is used in pages and messages only when it is letters, digits,
+spaces, `.`, `_` and `-` (up to 40, starting with a letter or digit), so
+it can't break a page. Anything else (a quote, `&`, `<`) falls back to the
+product name with its first letter upper-cased ("Acme-den"); the page
+`<title>` still shows it.
+
 ## Plugins
 
 A plugin adds to Den without changing it: a theme, a page in the web UI, and
@@ -1613,7 +1619,10 @@ user, and the CLI does that for you:
 
 - **The link** is `http://localhost:<port>/auth?c=<code>`, with `&next=<path>`
   for where to land (`web login --next /settings`). The code works once,
-  within 60 seconds, and only this server's secret makes one. It is printed
+  within `web.login_link_ttl` (5 minutes unless set; 30s to 60m, as `90s`,
+  `5m` or `1h`, in `config/local/user.yml` or the team config), and only
+  this server's secret makes one. `web login` shows the time left while it
+  waits, on a terminal. It is printed
   only on the one line you asked for (`web login`, or `web up` when it
   couldn't open the browser), never logged. Through the edge or a LAN name,
   the cookie belongs to that name: `web login --host acme.acme.localhost`
@@ -1853,7 +1862,8 @@ the account's id and login, never a token, and no other account gets in.
   last seen; "This device" on yours), each with **Revoke**, which ends its session at once (its
   open terminals included). **Pair a device** makes a one-time link and a
   QR code for an edge hostname you pick (`web login --host <name>` in the
-  browser): scan it on the other device within 60 seconds.
+  browser): scan it on the other device before it expires
+  (`web.login_link_ttl`; the page counts down).
 - **`web.github_client_id`** is the GitHub App's client id (public; no
   secret). The default is Den's own App, **Monster Orange Den**
   (`Iv23liKL12gnN6WvRV5b`), so Sign in with GitHub works out of the box. A
@@ -1868,6 +1878,61 @@ the account's id and login, never a token, and no other account gets in.
   it never prints the token. `GET /api/web/owner` reports it as
   `tokenExpiry: true`.
 
+### A company's Den: every developer connects GitHub from the browser
+
+The common shape: a company makes its own Den repo (`create`), pushes it to
+its GitHub org, and every developer clones it and runs their own instance
+on their own machine. Everyone opens the same URL (an edge name such as
+`https://den.local.<your zone>`, whose DNS says 127.0.0.1) and connects
+their GitHub account there, with no terminal and nothing to explain.
+
+```yaml
+# config/<name>.yml (the team's, committed): who may claim an instance
+web:
+  allowed_github_org: acme
+```
+
+- **`create` writes it**: `--github-org <org>`, else the GitHub owner of the
+  repo the new folder is in. Neither: a commented line and a next step.
+- **`web.owner_github`** (`config/local/user.yml`, per machine) is the
+  GitHub login of whoever runs this instance. `web up`, `web restart` and
+  `service install` record it from `gh` (`gh api user`) when `gh` is signed
+  in, no owner is linked and it isn't set, and print it. Only the login is
+  kept. This is the path most people take: org memberships are private
+  by default. When `gh` isn't signed in, `web up` and `doctor` say so,
+  with the fix (`gh auth login`, then `web restart`; or set
+  `web.owner_github` yourself).
+- **The signed-out page leads with Connect your GitHub account** while the
+  instance has no owner and one of the two is set. Who may claim it:
+  - **A member of `allowed_github_org`, on this computer.** **This is my
+    computer** navigates to `http://localhost:<port>/attest` and straight
+    back: only a browser on the machine Den runs on reaches it there. It
+    returns with a short-lived (2 minutes), single-use code, signed with
+    `web.secret`, bound to the edge hostname, in the URL fragment (never
+    sent to a server or logged), and only to one of this Den's own edge
+    hostnames. The page then starts Sign in with GitHub with it; when
+    GitHub says the account is a member of the org, it becomes the owner
+    and the browser is signed in. This exists because Docker Desktop,
+    OrbStack and a TCP passthrough show the edge a gateway's address, so
+    Den can't tell a browser on its own machine from another one.
+  - **`owner_github`'s login, from any browser** (a devbox you reach from a
+    laptop).
+  - **Anyone else is refused, with the reason**: not a member of the org;
+    a member, but not on this computer; not the login `owner_github` names.
+    The proof alone never signs a browser in: any program on the machine
+    can reach localhost, so the GitHub approval is always the person's.
+- **Membership.** Den asks GitHub with the sign-in's own token: the
+  account's own membership (`GET /user/memberships/orgs/<org>`, which needs
+  the App to have the org's Members (read) permission), then the public
+  member list. A private membership the App can't read is refused, saying
+  so: make the membership public, give the App that permission, or set
+  `web.owner_github`.
+- **Neither set**: the page names both settings and offers no claim.
+  `doctor` shows who may claim the instance, and fails (✗) when neither is
+  set and the edge is reachable from other machines.
+- Once claimed, it is an ordinary owner: Sign in with GitHub from any
+  browser, as above.
+
 ### The GitHub App (once, by whoever ships the Den)
 
 Den's default App is Monster Orange Den. A distribution that wants its own

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monster-orange/den",
-  "version": "0.4.20",
+  "version": "0.4.21",
   "description": "Den: a local multi-repo dev orchestrator, HTTPS edge and E2E harness",
   "type": "module",
   "bin": {

package/src/shared/attest-code.ts

@@ -0,0 +1,125 @@
+/**
+ * "This is my computer" (D17, fix A): how a browser on the machine Den runs
+ * on proves it, when the edge can't tell (Docker Desktop, OrbStack or a TCP
+ * passthrough hand the edge a gateway's address, so edgeClient says
+ * `unattested`).
+ *
+ * The signed-out edge page navigates the top level to
+ * `http://localhost:<port>/attest?return=<its own edge URL>`. Only a browser
+ * on this machine reaches this server there: a browser elsewhere reaches
+ * nothing, or its own machine's Den, whose web.secret doesn't verify here.
+ * The server answers 303 to the edge URL with the code in the fragment
+ * (`#den-attest=<code>`: never sent to a server, never in a log), and the
+ * page starts Sign in with GitHub with it.
+ *
+ * The proof alone never makes a session. Any program running as this OS
+ * user (an agent with a shell, too) can reach localhost, so a session from
+ * it would let an agent approve its own changes. It only lets a GitHub
+ * sign-in claim a Den that has no owner, for a member of
+ * web.allowed_github_org (github-routes.ts decideFlow): the person still
+ * approves on github.com.
+ *
+ *  - `a1.<nonce>.<expiry>.<mac>`, the mac HMAC-SHA256(web.secret, context +
+ *    the rest + the edge host it is for), its context its own: never a
+ *    login or a claim code. A code minted for one host fails on another.
+ *  - Valid for ATTEST_CODE_TTL_MS (2 minutes): the page uses it at once.
+ *  - Single use: its nonce is spent when the sign-in starts (ClaimNonces,
+ *    a file, so a restart can't revive one).
+ *  - `return` must be one of this server's own edge hosts (attestReturn).
+ */
+import { createHmac, randomBytes, timingSafeEqual } from "crypto";
+
+export const ATTEST_CODE_TTL_MS = 2 * 60_000;
+const SKEW_MS = 5_000;
+const CONTEXT = "den-attest-v1:";
+/** Where the spent attest nonces are kept (ClaimNonces' format). */
+export const ATTEST_NONCES_FILE = "attest-nonces.json";
+
+function mac(secret: Buffer, body: string, host: string): Buffer {
+  return createHmac("sha256", secret)
+    .update(`${CONTEXT}${body}\n${host.toLowerCase()}`)
+    .digest();
+}
+
+/** A fresh attest code for `host` (the edge hostname, no port). */
+export function mintAttestCode(
+  secret: Buffer,
+  host: string,
+  now: number = Date.now(),
+): string {
+  const nonce = randomBytes(16).toString("base64url");
+  const body = `a1.${nonce}.${(now + ATTEST_CODE_TTL_MS).toString(36)}`;
+  return `${body}.${mac(secret, body, host).toString("base64url")}`;
+}
+
+export type AttestCodeCheck =
+  | { ok: true; nonce: string; expiresAt: number }
+  | { ok: false; reason: "malformed" | "bad_mac" | "expired" };
+
+/**
+ * Whether `code` is an attest code this secret minted for `host`, still in
+ * its time. Constant-time mac. Single use is the caller's.
+ */
+export function checkAttestCode(
+  code: string,
+  secret: Buffer,
+  host: string,
+  now: number = Date.now(),
+): AttestCodeCheck {
+  const m =
+    /^(a1\.([A-Za-z0-9_-]{22})\.([0-9a-z]{1,11}))\.([A-Za-z0-9_-]{43})$/.exec(
+      code,
+    );
+  if (!m) return { ok: false, reason: "malformed" };
+  const given = Buffer.from(m[4], "base64url");
+  const want = mac(secret, m[1], host);
+  if (given.length !== want.length || !timingSafeEqual(given, want))
+    return { ok: false, reason: "bad_mac" };
+  const expiresAt = parseInt(m[3], 36);
+  if (
+    !Number.isFinite(expiresAt) ||
+    now >= expiresAt ||
+    expiresAt - now > ATTEST_CODE_TTL_MS + SKEW_MS
+  )
+    return { ok: false, reason: "expired" };
+  return { ok: true, nonce: m[2], expiresAt };
+}
+
+/**
+ * `/attest`'s `return`, checked: an http(s) URL whose host is one of
+ * `edgeHosts` (this server's own edge hostnames), no credentials in it.
+ * Its origin and same-origin path, or null for anything else.
+ */
+export function attestReturn(
+  raw: string | null | undefined,
+  edgeHosts: readonly string[],
+): { origin: string; host: string; next: string } | null {
+  if (!raw) return null;
+  let u: URL;
+  try {
+    u = new URL(raw);
+  } catch {
+    return null;
+  }
+  if (u.protocol !== "https:" && u.protocol !== "http:") return null;
+  if (u.username || u.password) return null;
+  const host = u.hostname.toLowerCase();
+  if (!edgeHosts.map((h) => h.toLowerCase()).includes(host)) return null;
+  const next = `${u.pathname}${u.search}`;
+  return {
+    origin: u.origin,
+    host,
+    next: next.startsWith("/auth") ? "/" : next,
+  };
+}
+
+/** The fragment key the code rides in back to the edge page. */
+export const ATTEST_FRAGMENT = "den-attest";
+
+/** Where /attest sends the browser: the edge page, the code in the fragment. */
+export function attestRedirect(
+  ret: { origin: string; next: string },
+  code: string,
+): string {
+  return `${ret.origin}${ret.next}#${ATTEST_FRAGMENT}=${encodeURIComponent(code)}`;
+}

package/src/shared/claim-code.ts

@@ -108,10 +108,14 @@ export function claimRefusalForAgent(env: NodeJS.ProcessEnv): string | null {
 
 /** The used claim nonces, kept until they expire (a file, 0600). */
 export class ClaimNonces {
-  constructor(private readonly stateDir: string) {}
+  constructor(
+    private readonly stateDir: string,
+    /** The file's name (D17: the attest codes keep their own). */
+    private readonly fileName: string = CLAIM_NONCES_FILE,
+  ) {}
 
   private file(): string {
-    return path.join(this.stateDir, CLAIM_NONCES_FILE);
+    return path.join(this.stateDir, this.fileName);
   }
 
   /** The used nonces; null when the file is there but won't parse (fail closed). */

package/src/{ui/server/edge-exposure.ts → shared/edge/exposure.ts}

@@ -15,7 +15,13 @@
  */
 import { execFile } from "child_process";
 import { promises as dns } from "dns";
-import { isLoopbackAddress } from "./request-guard.js";
+import * as net from "net";
+
+/** A loopback IP (127/8, ::1, or either IPv4-mapped); request-guard.ts has the same. */
+function isLoopbackAddress(addr: string): boolean {
+  const a = addr.toLowerCase().replace(/^::ffff:/, "");
+  return a === "::1" || (net.isIPv4(a) && a.startsWith("127."));
+}
 
 /**
  * The warning, by `web.edge_unattested` (SEC-2a): with `signin` (the

package/src/shared/github-app.ts

@@ -41,6 +41,8 @@ export interface GithubEndpoints {
   deviceCode: string;
   accessToken: string;
   user: string;
+  /** The REST API's base (D17: an org's membership), no trailing slash. */
+  api: string;
   /** A test's fake GitHub is in use (GITHUB_TEST_BASE_ENV). */
   fake: boolean;
 }
@@ -68,12 +70,14 @@ export function githubEndpoints(
       deviceCode: `${fake}/login/device/code`,
       accessToken: `${fake}/login/oauth/access_token`,
       user: `${fake}/user`,
+      api: fake,
       fake: true,
     };
   return {
     deviceCode: "https://github.com/login/device/code",
     accessToken: "https://github.com/login/oauth/access_token",
     user: "https://api.github.com/user",
+    api: "https://api.github.com",
     fake: false,
   };
 }

package/src/shared/github-device.ts

@@ -56,11 +56,27 @@ export interface GithubIdentity {
   login: string;
 }
 
-/** The three calls, swappable in a unit test. */
+/**
+ * Whether a login is a member of an org (D17), as far as its own token can
+ * tell: `member`, `not_member`, or `unreadable` (the membership is private
+ * and this token may not read it: the app lacks the org's Members
+ * permission, or isn't installed there).
+ */
+export type OrgMembership = "member" | "not_member" | "unreadable";
+
+/** The calls, swappable in a unit test. */
 export interface GithubDeviceClient {
   start(clientId: string): Promise<DeviceCode>;
   poll(clientId: string, deviceCode: string): Promise<PollResult>;
   user(token: string): Promise<GithubIdentity>;
+  /**
+   * D17: is `login` (the token's own account) a member of `org`? First its
+   * own membership (`GET /user/memberships/orgs/<org>`, which a GitHub App
+   * reads with the org's Members permission), then the public list (`GET
+   * /orgs/<org>/members/<login>`: 204 for a public member). A network
+   * failure throws.
+   */
+  orgMember(token: string, org: string, login: string): Promise<OrgMembership>;
 }
 
 const TIMEOUT_MS = 15_000;
@@ -218,6 +234,27 @@ export function githubDeviceClient(
         throw new Error(`GitHub's /user answered ${r.status}`);
       return { id: j.id, login: j.login };
     },
+    async orgMember(token, org, login) {
+      const headers = {
+        accept: "application/vnd.github+json",
+        authorization: `Bearer ${token}`,
+        "x-github-api-version": "2022-11-28",
+      };
+      const own = await request(
+        `${ep.api}/user/memberships/orgs/${encodeURIComponent(org)}`,
+        { method: "GET", headers },
+      );
+      if (own.status === 200)
+        return parse(own.body).state === "active" ? "member" : "not_member";
+      const pub = await request(
+        `${ep.api}/orgs/${encodeURIComponent(org)}/members/${encodeURIComponent(login)}`,
+        { method: "GET", headers },
+      );
+      if (pub.status === 204) return "member";
+      // A 404 for its own membership means none; a 403 means this token
+      // may not read it, so a private membership can't be told apart.
+      return own.status === 404 ? "not_member" : "unreadable";
+    },
   };
 }
 

package/src/shared/owner-github.ts

@@ -0,0 +1,100 @@
+/**
+ * `web.owner_github` (D17): the GitHub login of the person who runs this
+ * instance, recorded in config/local/user.yml at `web up` or `service
+ * install` from `gh` when it is signed in here and no owner is linked yet.
+ * With it, that person connects their GitHub account from any browser, on
+ * any machine (a devbox they reach from a laptop), and nobody else can
+ * claim the instance from another machine (github-routes.ts decideFlow).
+ *
+ * Only the login is kept: never a token. `gh api user` runs with a short
+ * timeout; gh missing or signed out records nothing.
+ */
+import { execFileSync } from "child_process";
+import { readUserConfig, writeUserConfig } from "./den-config.js";
+import { parseGithubName } from "./web-session.js";
+import { readWebOwner } from "./web-owner.js";
+
+export interface OwnerGithubDeps {
+  /** The login `gh` is signed in as here, or null. */
+  ghLogin?: () => string | null;
+  /** Whether an owner is linked already. */
+  ownerLinked?: () => boolean;
+  read?: typeof readUserConfig;
+  write?: typeof writeUserConfig;
+}
+
+/** `gh api user`'s login, or null (gh missing, signed out, slow, odd output). */
+export function ghLogin(env: NodeJS.ProcessEnv = process.env): string | null {
+  try {
+    const out = execFileSync("gh", ["api", "user", "--jq", ".login"], {
+      env,
+      timeout: 8_000,
+      stdio: ["ignore", "pipe", "ignore"],
+      encoding: "utf-8",
+    }).trim();
+    return parseGithubName(out, "gh api user", "gh") ?? null;
+  } catch {
+    return null;
+  }
+}
+
+export type OwnerGithubResult =
+  | { state: "linked" }
+  | { state: "set"; login: string }
+  | { state: "recorded"; login: string }
+  | { state: "none" };
+
+/**
+ * Record `web.owner_github` from gh when no owner is linked and it isn't
+ * set: `recorded`. Already set: `set`. An owner linked: `linked` (nothing
+ * to do). gh can't say: `none`. Never throws.
+ */
+export function recordOwnerGithub(
+  deps: OwnerGithubDeps = {},
+): OwnerGithubResult {
+  try {
+    if ((deps.ownerLinked ?? (() => readWebOwner() !== null))())
+      return { state: "linked" };
+    const read = deps.read ?? readUserConfig;
+    const cfg = read();
+    const web = { ...((cfg as { web?: Record<string, unknown> }).web ?? {}) };
+    let set: string | undefined;
+    try {
+      set = parseGithubName(
+        web.owner_github,
+        "web.owner_github",
+        "config/local/user.yml",
+      );
+    } catch {
+      return { state: "none" }; // a value someone typed: leave it alone
+    }
+    if (set) return { state: "set", login: set };
+    const login = (deps.ghLogin ?? ghLogin)();
+    if (!login) return { state: "none" };
+    web.owner_github = login;
+    (deps.write ?? writeUserConfig)({ ...cfg, web } as typeof cfg);
+    return { state: "recorded", login };
+  } catch {
+    return { state: "none" };
+  }
+}
+
+/** The line `web up` and `service install` print, or null. */
+export function ownerGithubLine(
+  r: OwnerGithubResult,
+  cli = "den",
+): string | null {
+  if (r.state === "recorded")
+    return `GitHub owner: @${r.login} (from gh; web.owner_github in config/local/user.yml). Connect your GitHub account from any browser to sign in.`;
+  if (r.state === "none") return ghNotSignedInHint(cli);
+  return null;
+}
+
+/** No owner, no web.owner_github, and gh can't say who you are: the fix. */
+export function ghNotSignedInHint(cli = "den"): string {
+  return (
+    "GitHub owner: not known, because gh isn't signed in here. " +
+    `Run \`gh auth login\`, then \`${cli} web restart\`; or set web.owner_github: <your GitHub login> in config/local/user.yml. ` +
+    "Then you can connect your GitHub account from any browser."
+  );
+}