@monster-orange/den 0.4.4 → 0.4.5

package/CHANGELOG.md

@@ -4,6 +4,175 @@ 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.5] - 2026-11-07
+
+Sign in with GitHub as the owner, from your other devices; approve a
+computer with a code; see that you're signed in (SEC-2a). Save the admin
+password without editing YAML (LK-4). Dev-metrics stay on this machine
+unless you opt in.
+
+### Added
+
+- **Sign in with GitHub.** A Den has one owner, a GitHub account:
+  `<cli> web owner link` runs GitHub's device flow in the terminal (a code
+  to enter at https://github.com/login/device) and stores only
+  `github:<id>` and the login (`web-owner.json`, 0600), never the token.
+  `web owner show` and `web owner unlink` too. The signed-out page then
+  has **Sign in with GitHub**: the server runs the flow, and the owner's
+  approval sets the same never-expiring session a one-time link does;
+  any other account sees "@<login> isn't allowed on this Den". At most
+  three sign-ins wait at once. Before an owner is linked the page says to
+  run `web owner link`. See docs/distributions.md, "Signing in with GitHub".
+- **Settings › Access.** The owner (link and unlink: shell-grade, so a
+  signed-in browser and never an agent's token), the
+  linked devices (browser, how it signed in, the client address the edge
+  vouched for, first and last seen) each with **Revoke**, which ends that
+  session at once, and **Pair a device**: a one-time link and its QR code
+  for an edge hostname you pick.
+- **`web.github_client_id`**: the GitHub App's client id (public). The
+  default is Den's own App, "Monster Orange Den" (`Iv23liKL12gnN6WvRV5b`);
+  a distribution sets its own App's id here, and an empty value turns Sign
+  in with GitHub off (the page then offers only the code and the link).
+  The App needs "Enable Device Flow" ticked and "Expire user authorization
+  tokens" off (docs/distributions.md, "The GitHub App").
+- **Expiring GitHub tokens are noticed.** If the App hands out expiring
+  tokens (`expires_in` or `refresh_token` in the answer), sign-in still
+  completes, and Den says once to switch off token expiry in the App's
+  settings (never with the token). `GET /api/web/owner` reports it as
+  `tokenExpiry`. Den never asks for `offline_access`.
+- **Approve this computer with a code.** The signed-out page shows a
+  six-character code (`XXX-XXX`, about 30 bits; the page polls with its own
+  128-bit id) and the command that approves it on the machine Den runs on:
+  `<cli> web approve <code>` (any case, dash optional; `--list` shows what
+  waits). The page signs itself in when it's approved, onto the page it
+  asked for. From a machine with SSH access the page gives the one-liner
+  (`ssh <host> '<cli> web approve <code>'`) and, for a host name, an Open
+  Terminal link. Codes expire after 10 minutes, are single-use, at most
+  five wait at once (the oldest drops) and are kept in memory only;
+  approvals are rate-limited and audited with who approved. The device is
+  labelled "approved with a code".
+- **Settings › Access › Waiting devices**: the computers waiting with a
+  code (browser and OS, address, when), each with **Approve** and **Deny**.
+- **`web.machine_name`** (Settings › Access › Machine name, in user.yml):
+  the name the signed-out page gives this machine. Default: the short
+  hostname. It's never taken from the browser's Host; the ssh one-liner's
+  target is the Host the browser used (without the port).
+- **The signed-out page says where to act.** "Sign in to <product>", which
+  machine Den runs on and why it asks (once per computer), Sign in with
+  GitHub (only with a client id), Approve this computer, and the one-time
+  link under "Other ways". Every command it prints names the machine it
+  runs on, has a copy button, and is `<cli>` when that's on PATH and this
+  distribution's, else the absolute path of its bin. English, Japanese and
+  Spanish.
+- **See that you're signed in.** A chip at the foot of the rail says
+  "Local", "Signed in · this device" or "@<login>" and opens Settings ›
+  Access. The first page after a sign-in says "This device is signed in
+  to <product> on <machine>", once. Linked devices lists every session
+  (GitHub, a code, a one-time link) with how it signed in, when, from
+  where, last seen and Revoke, and marks the one you're using as "This
+  device".
+- **Save the admin password without editing YAML (LK-4).** When a secrets
+  backend that keeps secrets (1Password, Doppler) is available and no
+  `secrets.refs.sudo` is set, the admin password prompt (shown when a
+  command is about to run sudo, LK-0) still offers "Save to <backend>".
+  Saving creates the item (1Password: "<Product> admin password" in your
+  default vault; Doppler: `<PREFIX>_LOCAL_ADMIN_PWD`) and writes
+  `secrets.refs.sudo` to your `config/local/user.yml`, so the password
+  survives restarts. A ref in the distribution's config still wins. The
+  vault status says so as `canSave`. A save error no longer carries the
+  backend's command line.
+- **`edge.proxy_protocol.trusted_ips`** (empty by default): the front
+  proxies (a TCP passthrough in front of the edge) whose PROXY protocol
+  every entrypoint accepts, so Den sees the real client through them.
+- **`web.edge_unattested: local | signin`** (default `signin`, read only
+  from `config/local/user.yml`): whether an edge client Den can't place
+  signs in. `local` keeps 0.4.4's (and 0.4.3's) behaviour.
+
+### Changed
+
+- **Dev-metrics are local unless you opt in.** Den sent its dev-metrics
+  whenever a DSN was present (in the env or a synced
+  `dev-metrics.config`). Sending now needs `metrics: { share: true }` in
+  `config/local/user.yml` (the boolean only); a DSN alone never sends. The
+  local `events.jsonl` is unchanged, and `CI=true` and
+  `DEV_METRICS_DISABLED=1` still stop sending.
+- **`<cli> web login` waits.** It prints the link and an 8-character code,
+  and blocks until the link is used ("Signed in: <browser> (<address>) at
+  <time>") or expires ("Expired: nobody used the link", exit 1). The link
+  asks for the code before it signs in; a wrong code is refused (five burn
+  the link, and wrong codes are rate-limited) and the link stays
+  single-use. `--no-wait` prints the link alone, as before, and asks for no
+  code; with no server running it behaves like `--no-wait` and says so.
+- **Edge visitors Den can't place sign in.** A client the edge reports
+  with no `X-Forwarded-For`, or with a Docker/VM gateway or bridge address
+  (what a TCP passthrough or Docker Desktop and OrbStack hand it), now sees
+  the signed-out page with Sign in with GitHub, unless
+  `web.edge_unattested: local`. Loopback and this machine's own addresses,
+  as the edge reports them, stay local, and localhost straight to the
+  server's port never signs in.
+- **The client is the right-most `X-Forwarded-For` entry**, the one the
+  edge appended (0.4.4 and earlier read the left-most, which a client could
+  write).
+- **The edge believes forwarded headers only from its own networks.** Den
+  renders `forwardedHeaders.trustedIPs` (loopback and the Docker ranges)
+  on every entrypoint, never `forwardedHeaders.insecure`. An `edge.args`
+  entry that sets `forwardedHeaders` or `proxyProtocol` is dropped with a
+  notice from `edge up`.
+- **"Your edge is reachable from other machines"** now reads "A browser it
+  can't place as this one signs in first (Sign in with GitHub, or a
+  pairing link)." (with `web.edge_unattested: local`, that anyone it can't
+  place can use terminals).
+- **`edge up` says when the running edge's command differs** from the one
+  it renders, and why, before recreating it.
+
+### Fixed
+
+- **The workspace commands run in is named: "CLI default".** Local Dev's
+  workspace list marked it with a bare accent dot and no label, and
+  picking a workspace in the top bar never moved the dot (by design: that
+  picks the view), so it looked broken. It now says "CLI default", with
+  a tooltip: CLI commands run there when you don't name a workspace, and
+  the top bar only changes what pages show. The top bar's Workspace menu
+  tags it "CLI default" (was "focus") and offers "Make <ws> the CLI
+  default"; the Workspaces pane's badge reads "active · CLI default" and
+  its button "Make CLI default". Nothing behaves differently.
+
+- **A browser signs in on a plain-http LAN bind** (`DEN_BIND_HOST` with
+  `web.allow_plain_http_remote`). A `web login --origin http://<LAN IP>:<port>`
+  link got 403 `origin_rejected`: the browser sends a plain-http origin that
+  isn't localhost no `Sec-Fetch-*` headers, and a navigation sends no
+  Origin. The sign-in GETs (`/auth` and the GitHub sign-in poll), which
+  carry their own one-time credential, now pass with neither header. Either
+  header, when present, is still checked, and every other GET that runs
+  something still needs this server's page or a bearer.
+- **`web up` with `DEN_BIND_HOST` on one address is ready when it serves.**
+  Its readiness probe (and `web sessions`/`web logout`'s calls) asked
+  127.0.0.1, so a server bound to a LAN IP or `::1` printed "did not become
+  ready" and exited non-zero. They ask the bound address now (loopback for
+  0.0.0.0 and `::`), with a Host the allowlist accepts and the CLI's
+  bearer: a LAN address answers an unsigned probe 401 `signin_required`.
+  `web up` names the bound address (`http://<LAN IP>:<port>`), not
+  localhost, which a LAN-only bind doesn't answer.
+
+### Migrations
+
+- **One edge recreate.** The edge's command changes (forwarded-header
+  trust), so the first `<cli> edge up` (or `stack up`) after upgrading
+  recreates it once, and says so: "<org>-edge's settings changed
+  (forwarded-header trust): recreating it once." Routes drop only while it
+  restarts.
+- **Edge visitors now see Sign in with GitHub** where 0.4.4 let a client
+  it couldn't place in. Link an owner (`<cli> web owner link`), approve
+  the computer with its code (`<cli> web approve <code>`) or pair with
+  `<cli> web login --host <name>`;
+  or set `web.edge_unattested: local` in `config/local/user.yml` to keep
+  0.4.4's behaviour on that machine.
+- **Scripts that run `<cli> web login` and read its output** should pass
+  `--no-wait`: it now waits for the link to be used.
+- **Remove `forwardedHeaders.*` and `proxyProtocol.*` from `edge.args`.**
+  They are ignored now; use `edge.proxy_protocol.trusted_ips` for a front
+  proxy.
+
 ## [0.4.4] - 2026-11-07
 
 The admin password is for sudo, and nothing else (LK-0). An agent's

package/README.md

@@ -10,8 +10,8 @@
 </p>
 
 <picture>
-  <source media="(prefers-color-scheme: dark)" srcset="docs/images/0.4.4/hero-dark.png">
-  <img src="docs/images/0.4.4/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.5/hero-dark.png">
+  <img src="docs/images/0.4.5/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>
 
 ## What Den is
@@ -24,7 +24,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.4/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.5/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
@@ -46,17 +46,18 @@ yours. Den connects them and turns on good practice from the start.
   and audit trail as a person, under a token of its own. Agents can read and investigate, and acting is opt-in.
   Starting an agent never asks for your admin password: Den asks for it only when a command it runs needs sudo.
 - **Safe on localhost, signed in beyond it.** On localhost there is nothing to sign in to. Reached through the
-  edge or your network, every page and call needs a sign-in, and there is no password: `acme web login` prints a
-  one-time link.
+  edge from another machine, or over your network, every page and call needs a sign-in, and there is no password:
+  Sign in with GitHub as the Den's owner, approve the computer with a code (`acme web approve <code>`), or open a
+  one-time link from `acme web login`.
 - **Opinionated, not locked in.** Good defaults are switched on, and almost everything can be switched off. The
   safety guards stay on. Den never needs our accounts, secrets or certificates. Everything specific to you
   lives in your own repo.
 
 <p align="center">
-  <img src="docs/images/0.4.4/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.4/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.4/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.4/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.5/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.5/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.5/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.5/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

@@ -12,6 +12,7 @@ Den's own checkout is itself a distribution, named `den`.
 - [The bin shim](#the-bin-shim)
 - [make: den.mk](#make-denmk)
 - [Two roots](#two-roots)
+- [Dev metrics: local unless you opt in](#dev-metrics-local-unless-you-opt-in)
 - [Pinning and upgrading](#pinning-and-upgrading)
 - [Developing Den against a distribution](#developing-den-against-a-distribution)
 
@@ -379,9 +380,23 @@ a ref that is not set is **not configured**, and its feature says so
 ("not configured: set secrets.provider and secrets.refs.sudo in
 config/acme.yml") instead of running a CLI. Typing the password always
 works; only the saved password needs `refs.sudo`.
+
+**Saving writes `refs.sudo` for you** (LK-4, 0.4.5). When `secrets.provider`
+is `1password` or `doppler`, its CLI is available, and no `refs.sudo` is
+set, the admin password prompt (shown when a command is about to run sudo)
+still offers "Save to 1Password". Saving creates the item
+(1Password: a Password item "<Product> admin password", field `password`,
+in your default vault; Doppler: the key `<PREFIX>_LOCAL_ADMIN_PWD`) and
+then writes that ref to `config/local/user.yml`, because the password is
+the person's, not the distribution's. From then on it survives restarts.
+A failed save writes nothing, and its error never carries the password.
+`env` keeps nothing past the process, so it offers no save. A `refs.sudo`
+in the distribution's config always wins over the one in user.yml.
+
 `/api/sudo-password/vault-status` reports `backend`, `label`,
-`configured`, `backendAvailable`, `reason` and `hasStored` (`opAvailable`
-is a deprecated alias of `backendAvailable`, kept for one minor).
+`configured`, `canSave` (saving works with no YAML to edit),
+`backendAvailable`, `reason` and `hasStored` (`opAvailable` is a
+deprecated alias of `backendAvailable`, kept for one minor).
 
 The admin password is for sudo, and nothing else (LK-0). It is no sign-in
 and no access check: starting, stopping and resuming agents, sessions and
@@ -1209,11 +1224,13 @@ are the same directory.
 
 On localhost nothing asks you to sign in: every page, the agents and the
 terminal work as they are, and the admin password (R8) is the only prompt,
-asked only when a command Den runs needs sudo. The edge counts as local too (0.4.3): opening
-`https://acme.acme.localhost` from this machine asks for nothing.
-Signing in is for when the server is reached from another machine: the
-edge for a client the edge says is elsewhere, a LAN address, or a bind
-that isn't loopback (`DEN_BIND_HOST`).
+asked only when a command Den runs needs sudo. Through the edge, a browser
+the edge shows is on this machine asks for nothing either. Signing in is
+for everything else: the edge for a client it can't place here (0.4.5), a
+LAN address, or a bind that isn't loopback (`DEN_BIND_HOST`). From another
+device, sign in with GitHub as the Den's owner, approve the computer with
+the code its page shows, or open a one-time link (below, and
+[Signing in with GitHub](#signing-in-with-github)).
 
 There is no password. Reading `web.secret` (32 random bytes, mode 0600 in
 the state dir, made at the first `web up`) proves you are this computer's
@@ -1221,7 +1238,10 @@ user, and the CLI does that for you:
 
 ```bash
 ./bin/acme web open        # start if needed, and sign this browser in (a new tab)
-./bin/acme web login       # print a one-time sign-in link, for another browser
+./bin/acme web login       # a one-time sign-in link and its code; waits until it's used
+./bin/acme web login --no-wait  # the link alone (asks for no code), and return
+./bin/acme web approve ABC-123  # approve the computer showing this code
+./bin/acme web approve --list   # the computers waiting with a code
 ./bin/acme web sessions    # the signed-in browsers: id, created, last seen, host, user agent
 ./bin/acme web logout <id> # sign out one browser (an id prefix from `web sessions`)
 ./bin/acme web logout      # sign out every browser
@@ -1238,7 +1258,19 @@ user, and the CLI does that for you:
   among them; its URL comes from the edge config, and a name the edge
   doesn't route here is refused, saying what to add), and
   `web login --origin http://<lan name>:<port>` for any other allowed name
-  (the signed-out page there shows the exact command).
+  (the signed-out page there shows the exact command, under "Other ways").
+- **`web login` waits** (0.4.5). Besides the link it prints an
+  8-character code ("It asks for this code: ABCD-EFGH") and blocks until
+  the link is used, then says who: "Signed in: Safari on macOS
+  (100.64.0.7) at 10:42". Nobody within the minute: "Expired: nobody used
+  the link", exit 1. The link's page asks for the code before it signs in,
+  so the link alone is useless; once opened it waits 5 minutes for the
+  code. A wrong code is refused; five burn the link ("Refused: too many
+  wrong codes", exit 1), more than 20 wrong a minute (any link) are slowed,
+  and the link still works once. The CLI asks the running server through
+  its bearer and never logs the code. `--no-wait` prints the link alone and
+  returns, as before (no code); with no server running `web login` does
+  that too, and says so.
 - **The cookie** (`den_session_<port>`) is HttpOnly, SameSite=Strict and
   Path=/, and Secure when the request came over HTTPS through the edge. The
   session lives server-side (`web-sessions.json`, 0600, in the state dir)
@@ -1256,36 +1288,111 @@ user, and the CLI does that for you:
   The Host allowlist, the Origin check and the CSRF token are what stop
   another site or a rebinding DNS name. From another machine, every page
   and call needs a signed-in browser (or a bearer). A page there shows
-  "Sign in to use <name>" with the command to run; it never asks for a
+  "Sign in to <name>" and the ways to sign in (below); it never asks for a
   secret. `/api` answers 401 `signin_required`.
-- **The edge counts as local.** A request for the edge hostname from the
-  edge (an edge peer, below) is treated as loopback: no sign-in on any
-  route, the agents and the terminal included. Host, Origin, CSRF and the
-  agent-token rules still apply. Who the client is comes from the left-most
-  `X-Forwarded-For` entry the edge sends:
+- **The signed-out page says where to act.** It names the machine Den runs
+  on ("You're opening Den from another computer. Den runs on
+  **studio**, so it needs to know this is you."), then:
+  - **Sign in with GitHub**, only when a client id is set (below);
+  - **Approve this computer**: a code (`XXX-XXX`) and the command that
+    approves it, to run on that machine (`<cli> web approve <code>`), or
+    Settings › Access › Waiting devices there. The page signs itself in
+    when it's approved and goes to the page you asked for; it counts down
+    the 10 minutes, and an expired code is a click away from a new one.
+    From a computer with SSH access to it, the page gives the one-liner
+    (`ssh <host> '<cli> web approve <code>'`) and, when the host is a name,
+    an Open Terminal (`ssh://`) link;
+  - **Other ways**, collapsed: the one-time link with
+    `web login --origin`.
+
+  Every command the page prints names the machine it runs on and has a
+  copy button. It is `<cli>` when the first `<cli>` on that machine's PATH
+  is this distribution's, else the absolute path of its bin.
+
+- **The machine's name** on the page is `web.machine_name` from
+  `config/local/user.yml` (Settings › Access › Machine name), else the short
+  host name (up to the first dot). It is never taken from the browser's
+  Host. The ssh one-liner's target is the Host the browser used, without
+  the port (the machine's host name if it had none).
+- **Codes.** About 30 bits (Crockford base32: no I, L, O or U; typed in any
+  case, the dash optional); the page polls with a separate 128-bit id. A
+  code expires after 10 minutes and works once; at most five wait at once
+  (a sixth drops the oldest). They live in the server's memory only.
+  Approving is rate-limited (10 a minute) and recorded in the activity log
+  with who approved, never the code. The new session is "approved with a
+  code". **Deny** (Settings › Access, or `web deny` through the API) tells
+  the page it was refused.
+- **Seeing that you're signed in.** The chip at the foot of the rail says
+  "Local" (this machine), "Signed in · this device" (a code or a one-time
+  link) or "@<login>" (GitHub), and opens Settings › Access. The first page
+  after a sign-in says "This device is signed in to Den on <machine>",
+  once. Linked devices lists every session (GitHub, a code, a one-time
+  link): how it signed in, when, from where (the address and the browser
+  and OS), last seen, and **Revoke**; the one you're using says "This
+  device".
+- **The edge counts as local only when it shows the client is.** A
+  request for the edge hostname from the edge (an edge peer, below) is
+  treated as loopback (no sign-in on any route, the agents and the
+  terminal included) when the client the edge reports is this machine.
+  Host, Origin, CSRF and the agent-token rules still apply. Who the client
+  is comes from the right-most `X-Forwarded-For` entry, the one the edge
+  itself appended (anything left of it came from the client, and is never
+  believed):
   - loopback, or one of this machine's own interface addresses (a LAN
-    address, or a VPN's such as a Tailscale `100.x`): local;
+    address, or a VPN's such as a Tailscale `100.x`): local, no sign-in;
   - missing, or a container/VM network's address (the Docker ranges, or a
     subnet of one of this machine's Docker/OrbStack/VM bridges): Den can't
     tell (Docker Desktop and OrbStack on macOS hand the edge their
     gateway's address, and a TCP passthrough in front of the edge hides the
-    client), so local;
-  - any other address: another machine, which needs a sign-in.
-
+    client), so it signs in: `web.edge_unattested`, below;
+  - any other address: another machine, which signs in.
+
+  `web.edge_unattested: local` in `config/local/user.yml` counts a client
+  Den can't place as local again (0.4.4's behaviour). It is read only from
+  that file (a choice for that machine); the distribution config's key is
+  ignored with a warning. The default is `signin`. A request straight to
+  the server's port on localhost (loopback Host and peer) never signs in.
   With `DEN_BIND_HOST` beyond loopback (a deliberate exposure, other than
-  the Linux edge's Docker bridge address) the edge needs a sign-in as
-  before. With `forwardedHeaders.insecure` (the edge's default) Traefik
-  keeps an `X-Forwarded-For` the client sent, so this is a convenience,
-  not a boundary: whoever can reach the edge can use the terminal.
+  the Linux edge's Docker bridge address) the edge always signs in.
+
+- **The edge believes forwarded headers only from its own networks.** Den
+  renders each entrypoint with `forwardedHeaders.trustedIPs` set to
+  loopback and the Docker ranges (`127.0.0.1/32`, `::1/128`,
+  `172.16.0.0/12`, `192.168.65.0/24`), never `forwardedHeaders.insecure`,
+  so a client can't hand the edge an `X-Forwarded-For` of its own. An
+  `edge.args` entry that sets `forwardedHeaders` or `proxyProtocol` is
+  dropped, and `edge up` says so.
+- **A TCP passthrough in front of the edge** (a gateway that publishes
+  `:443` and passes TLS through) hides the client: the edge sees the
+  gateway's address. Have the gateway send the PROXY protocol, and list it
+  in `edge.proxy_protocol.trusted_ips` (empty by default; IP addresses or
+  CIDRs; `config/local/user.yml`'s list replaces the team's):
+
+  ```yaml
+  edge:
+    proxy_protocol:
+      trusted_ips: [172.18.0.5]
+  ```
+
+  Every entrypoint then takes the PROXY protocol from those addresses, and
+  the client it carries is what Den sees. Configuring the gateway is the
+  gateway's job.
+
+- **`edge up` recreates the edge when its command changed.** It compares
+  the running edge's command with the one it renders and says why ("acme-edge's
+  settings changed (forwarded-header trust): recreating it once. Routes
+  drop only while it restarts."). Upgrading to 0.4.5 does this once.
 
 - **"Your edge is reachable from other machines".** When Den can tell, at
   start, that the edge is reachable beyond this machine (an edge hostname
   that resolves to an address that isn't loopback, such as a LAN or
   Tailscale address, or the edge container publishing a port on every
   interface, from `docker inspect`), it writes "Your edge is reachable from
-  other machines; anyone who can reach it can use terminals. Auth is
-  coming." once to `web.log`, and every page shows it as a banner (dismissed
-  per browser).
+  other machines. A browser it can't place as this one signs in first
+  (Sign in with GitHub, or a pairing link)." once to `web.log`, and every
+  page shows it as a banner (dismissed per browser). With
+  `web.edge_unattested: local` it says instead that anyone it can't place
+  can use terminals, and to remove the key to have them sign in.
 - **localhost is the canonical name.** A cookie set on `localhost` isn't
   sent to `127.0.0.1`, so the links Den prints use `localhost`.
 - **Browsers.** Chromium, Firefox and Safari 16.4 or later: a sign-in link
@@ -1319,6 +1426,76 @@ logout --all` the old token is refused; the CLI reads the new one.
   421 `misdirected`, so a LAN client can't send the edge's name straight to
   the server's port.
 
+## Signing in with GitHub
+
+A Den has one owner: a GitHub account. Once it is linked, that account
+signs in from any device (a phone, another laptop, a browser through the
+edge) with **Sign in with GitHub** on the signed-out page. Den stores only
+the account's id and login, never a token, and no other account gets in.
+
+```bash
+./bin/acme web owner link    # link the owner: GitHub's device flow, in the terminal
+./bin/acme web owner         # show who it is (also: web owner show, --json)
+./bin/acme web owner unlink  # forget the owner (signed-in browsers stay signed in)
+```
+
+- **`web owner link`** prints `https://github.com/login/device` and a code.
+  Enter the code there and approve; Den asks GitHub who approved, stores
+  `owner: github:<id>` and the login in `web-owner.json` (0600, in the
+  state dir) and throws the token away. A second link is refused until
+  `web owner unlink`. Settings › Access does the same in the browser
+  (Link your GitHub account, Unlink): shell-grade actions, for a signed-in
+  browser and never an agent's token.
+- **Sign in with GitHub** on the signed-out page shows a code and
+  `github.com/login/device`. The server runs the flow, and when the owner
+  approves it sets the same never-expiring session cookie a one-time link
+  sets, and the page reloads signed in. Another account sees "@<login>
+  isn't allowed on this Den". The token is thrown away either way. At most
+  three sign-ins wait for GitHub at once; a code expires as GitHub says
+  (15 minutes). With no owner linked the page says to run
+  `web owner link`.
+- **Settings › Access** lists the linked devices (the browser, how it
+  signed in, the client address when the edge vouched for one, created and
+  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.
+- **`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
+  distribution that ships its own App sets its client id here (below);
+  `config/local/user.yml`'s wins over the team's. An empty value
+  (`github_client_id: ""`) turns Sign in with GitHub off: the page then
+  offers the code and the one-time link only.
+- **Expiring tokens.** If the App hands out expiring tokens (GitHub's
+  answer carries `expires_in` or a `refresh_token`), sign-in still
+  completes, and Den says once, in the log and on stderr, to switch off
+  token expiry in the App's settings ("Expire user authorization tokens");
+  it never prints the token. `GET /api/web/owner` reports it as
+  `tokenExpiry: true`.
+
+### The GitHub App (once, by whoever ships the Den)
+
+Den's default App is Monster Orange Den. A distribution that wants its own
+(its name on GitHub's approval page) needs a GitHub App with the device
+flow on. Create it once (organization or account › Settings › Developer settings › GitHub
+Apps › New GitHub App):
+
+1. No callback URL; untick "Request user authorization during
+   installation". Webhook off.
+2. **Enable Device Flow**: ticked. The device flow needs only the client
+   id.
+3. **Expire user authorization tokens**: off. Den never asks for
+   `offline_access`, and keeps no token either way.
+4. Account permissions: none. Den reads only `GET /user` (the id and the
+   login), which needs none. Repository permissions are only for features
+   that act on a repository (Den's default App has Issues for feedback).
+5. **Where can this GitHub App be installed**: Any account. GitHub lets only
+   members of the owning organization authorize a private App, so anyone
+   else couldn't sign in.
+6. Put the **Client ID** in `web.github_client_id`. Never generate or
+   share a client secret or a private key for Den: it never uses one.
+
 ## Running the web UI as a service (macOS)
 
 Den ships a launchd installer that runs the web UI at login and restarts it if
@@ -2129,6 +2306,26 @@ with both workspaces named. Any key of `agents:` other than `max_concurrent`
 and `persona_packs` is an agent id, and its only key is `grants`. A grant
 naming a workspace that doesn't exist stops `start`, naming the key.
 
+## Dev metrics: local unless you opt in
+
+Den records each command it runs (its name, surface, duration and exit
+code, never arguments or values) as one JSON line in
+`.dev-metrics/events.jsonl` under the distribution root. That file stays
+on the machine.
+
+Nothing is sent anywhere unless the engineer opts in, per machine:
+
+```yaml
+# config/local/user.yml (gitignored)
+metrics:
+  share: true
+```
+
+Only the boolean `true` counts. With it, and a Sentry DSN in
+`DEV_METRICS_SENTRY_DSN` (or a synced `dev-metrics.config`), each line is
+also sent, best effort. A DSN on its own never sends. `CI=true` and
+`DEV_METRICS_DISABLED=1` stop sending even when opted in.
+
 ## Pinning and upgrading
 
 `package.json` pins an exact Den version (`create` writes the version that

package/docs/reference.md

@@ -110,9 +110,14 @@ That is `examples/demo/demo-api/.den.yml`; the other demo repos are in
   workspace's checkout, with an MCP server pinned to that workspace and a
   token of its own. The web UI's Agents tab lists them and opens their
   terminals.
-- **Browser sign-in beyond loopback.** On localhost no route needs a sign-in.
-  Through the edge or on a non-loopback bind, every route needs one:
-  `<cli> web login` prints a one-time link (`web open` opens it).
+- **Browser sign-in beyond loopback.** On localhost no route needs a sign-in,
+  nor through the edge when it shows the browser is on this machine.
+  Anywhere else, every route needs one: Sign in with GitHub as the Den's
+  owner (`<cli> web owner link` links the account once), approving the
+  computer with the code its page shows (`<cli> web approve <code>`, or
+  Settings › Access › Waiting devices), or a one-time link (`<cli> web
+login`, which waits until it's used; `web open` opens it; Settings ›
+  Access pairs a device with a QR code). The rail's chip shows who you are.
 - **Web UI and CLI** over the same state.
 
 ## Strategies

package/package.json

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