Sign in through a sign-in proxy, and know who did what #701

Request: none

Problem

Signing in to Simlock always means pasting a Simlock token. A team that already puts its internal tools behind a sign-in proxy (Cloudflare Access, oauth2-proxy and the like) has proved who a person is before the request reaches Simlock, yet Simlock ignores that and asks for a token anyway. The console cannot show who is signed in either.

The code that turns a credential into an identity is spread over the HTTP frontend, the daemon and the gateway, so adding a second way to sign in today means touching all three, and the next one would too.

Who it is for

An operator who runs a Simlock gateway (or a single host with HTTP on) behind the team's sign-in proxy, and the people on that team who open the console. Agents are not in this group: they keep using Simlock tokens.

Outcome

• A person the proxy has signed in opens the console and is in, with no token to paste. Their name is in the sidebar.
• Anyone can ask "who am I" over HTTP (GET /v1/identity) or the CLI (simlock whoami) and get the identity Simlock sees.
• A Simlock token keeps working everywhere it works today, behind the proxy or not.
• An identity the proxy did not sign, or signed wrongly, is refused, and the console says why.

How it works for the user

flowchart LR
  O[Open the console URL] --> P{Signed in at the proxy?}
  P -->|no| L[Proxy's own login page] --> O
  P -->|yes| I[Console asks: who am I?]
  I -->|a person| C[Console opens, name in the sidebar]
  I -->|refused, with a reason| F[Token form, with a line saying why]
  I -->|nobody| G[Token form, as today]

Before, through Cloudflare Access, signed in:

$ curl -s https://simlock.team.dev/v1/identity
{"error":{"code":"UNAUTHENTICATED","message":"Missing bearer token"}}

After:

$ curl -s https://simlock.team.dev/v1/identity
{"principal":"proxy:https://team.cloudflareaccess.com#7f3a…","name":"alice@team.dev","role":"admin","via":"proxy","signOutUrl":"https://team.cloudflareaccess.com/cdn-cgi/access/logout"}

$ simlock whoami
Principal: claude-1
Name:      claude-1
Role:      agent
Via:       socket

The operator turns it on with four keys, set together:

$ simlock config set http.proxyAuth '{"header":"cf-access-jwt-assertion","jwksUrl":"https://team.cloudflareaccess.com/cdn-cgi/access/certs","issuer":"https://team.cloudflareaccess.com","audience":"4f1c…"}'
$ simlock daemon stop && simlock daemon start

Examples

What a request through the proxy gets:

What could go wrong

• The proxy's key URL is down: people behind the proxy cannot sign in until it is back. Token sign-in still works. Likely only during a proxy outage.
• The operator copies the wrong audience or issuer: every person is refused, and the console shows the reason. Likely on first setup.
• A gateway and its workers are on different versions: the workers show as incompatible until all are upgraded, as with every release that changes the protocol.

Words used

• sign-in proxy: a service in front of Simlock that signs people in with the team's identity provider and lets only them through, e.g. Cloudflare Access, oauth2-proxy.
• JWT: a signed token the proxy adds to each request it lets through, naming the person, e.g. the Cf-Access-Jwt-Assertion header.
• key URL (JWKS URL): the address where the proxy publishes the public keys its JWTs are signed with, e.g. https://team.cloudflareaccess.com/cdn-cgi/access/certs.
• principal: the identity Simlock acts for, e.g. tok_9f2c for a token, proxy:https://team.cloudflareaccess.com#7f3a… for a person.
• strategy: one way to sign in that Simlock checks, e.g. Simlock tokens, or the proxy's JWT.

Non-goals

• Recording who did an action: Every action leaves a trace of who did it #703.
• A worker joined to a gateway refusing its own HTTP: A worker joined to a gateway does not serve its own HTTP API or console #705.
• Simlock's own login with an identity provider (built-in OIDC).
• Allow-lists, or mapping the provider's groups to roles. Who gets in is the proxy's policy.
• Trusting an unsigned identity header (X-Forwarded-Email).
• Agents signing in through the proxy. They use Simlock tokens.
• A name on leases (ownerName).
• Ending a live screen stream when the proxy's JWT expires (only event streams end).

Completion conditions

• Behind a sign-in proxy, the console opens with no token form and shows the person's name in the sidebar.
• GET /v1/identity and simlock whoami say who the caller is: a proxy person, a token, a socket session, or a gateway uplink.
• A forged, expired, wrong-issuer, wrong-audience or unverifiable proxy JWT is refused with 401 and a reason; the console shows it.
• A request signed in through the proxy that changes something and does not come from the console's own page is refused with 403.
• A Simlock token works as today, and wins when sent beside a proxy JWT.
• A follow stream (the event stream, a lease's or a lease request's events) opened by a proxy person ends when their JWT expires.
• The whole path works with a real oauth2-proxy and identity provider, in CI.

Open questions

none

Decisions

• ADR 0033 — A sign-in proxy is a second way to sign in, and auth is one module (docs(adr): 0033 a sign-in proxy is a second way to sign in, and auth is one module #704): one auth module checks every credential; strategies answer identified, not-mine or rejected; the proxy JWT rules; identity.get; the CSRF rule; the console's sign-in.

Shared values

Tasks

flowchart TD
  A["#712 Auth module"] --> B["#713 identity.get / whoami"]
  B --> C["#714 Proxy JWT sign-in"]
  C --> D["#715 CSRF rule"]
  C --> E["#716 Console through the proxy"]
  E --> F["#717 Real-proxy CI lane"]

• Auth checks live in one module, src/auth #712 Auth checks live in one module — nothing changes for a user; every credential check now lives in src/auth. Risk: a token, admin secret or join token that worked stops working.
• Ask Simlock who you are: identity.get, GET /v1/identity, simlock whoami #713 Ask Simlock who you are — GET /v1/identity and simlock whoami show the caller's identity. Risk: a wrong name or role shown.
• Sign in through a sign-in proxy's signed JWT #714 Sign in through a sign-in proxy — a person the proxy signed in reaches the HTTP API with no token. Risk: a forged JWT gets in, or a good one is refused.
• Refuse cross-site changing requests from a proxy sign-in #715 Refuse cross-site requests from a proxy sign-in — another site cannot make a signed-in browser change something. Risk: another site can make a signed-in browser release leases or drain workers.
• The console signs in through the sign-in proxy and shows who is signed in #716 The console signs in through the proxy — the console opens with no token form and shows the name. Risk: the console shows the token form behind a working proxy.
• Test sign-in against a real proxy: oauth2-proxy and Dex in CI #717 Test against a real sign-in proxy — CI runs Simlock behind oauth2-proxy and Dex. Risk: a broken lane hides a real-proxy regression (it is not a required check).

Open work in the same area:

• feat(history): the event history is a SQLite file, history.db #694, feat(history): project requests, minutes and device facts into history.db #695 (history.db, event store): change how events are stored. This feature adds no event and changes no payload. No Depends on.
• usage.get and simlock stats from the projections #631 usage.get (task:ready): reads token labels through the token store Auth checks live in one module, src/auth #712 moves. Auth checks live in one module, src/auth #712 Depends on usage.get and simlock stats from the projections #631, and moves that use with the rest.
• GET /v1/stats and the simlock stats --csv ledger #632 GET /v1/stats: adds a route in src/http/app.ts. Auth checks live in one module, src/auth #712 keeps agentAuth's name and use, so the route merges either way; whichever merges second takes the base. No Depends on.
• The folder sets the role: a gateway lives in <root>/gateway, --gateway reaches it, and the mode key is gone #708 (feature One Simlock instance per host #700): replaces mode with a folder-chosen role and simlock --gateway config set, in the same startup code, http config section and e2e harness Auth checks live in one module, src/auth #712, Sign in through a sign-in proxy's signed JWT #714 and The console signs in through the sign-in proxy and shows who is signed in #716 change. Sign in through a sign-in proxy, and know who did what #701 goes first: The folder sets the role: a gateway lives in <root>/gateway, --gateway reaches it, and the mode key is gone #708 Depends on Auth checks live in one module, src/auth #712 and Sign in through a sign-in proxy's signed JWT #714 and carries http.proxyAuth over to the gateway's folder (added to The folder sets the role: a gateway lives in <root>/gateway, --gateway reaches it, and the mode key is gone #708's body by this session).
• The event history is a SQLite file, history.db #629, Projections: request, minute and device fact rows #630, usage.get and simlock stats from the projections #631, GET /v1/stats and the simlock stats --csv ledger #632, A quarantined device says what failed #635, A waiting request says why it is not placed, on a worker #636, A waiting request says why each worker cannot take it, on a gateway #637: each bumps the protocol; a PR that merges after another bump bumps again (toolchain.md).
• A gateway sends chosen fleet events to a signed generic webhook #719, A gateway sends fleet events to Slack #720, simlock alerts test checks a destination #721 (feature Gateway sends fleet events to Slack and other webhooks #707, webhooks, task:draft): edit src/core/config.ts, src/contract/schemas.ts, the gateway's construction in src/daemon/main.ts, the operations map, and add a second outbound-HTTP port; they bump the protocol too. Sign in through a sign-in proxy, and know who did what #701 goes first: A gateway sends chosen fleet events to a signed generic webhook #719 Depends on Sign in through a sign-in proxy's signed JWT #714 (asked for on A gateway sends chosen fleet events to a signed generic webhook #719, for Gateway sends fleet events to Slack and other webhooks #707's spec session).
• Overview and Waiting: a range picker, wait p95, leases granted and three charts #633, Console Usage page #634 (console Overview and Usage pages): touch ui/ screens, not sign-in or the sidebar foot. No Depends on.
• Daemon state stores in SQLite (state.db) #624 (state.db, request:new): would move tokens.json; not started. None.
• feat(history): history.db, usage projections, simlock stats, GET /v1/stats and console figures (#623) #626 (ADR 0032): takes number 0032; this feature's ADR is 0033. None.

Written by an agent.