@corenel/sidecar 0.11.0 → 0.13.0

package/README.md

@@ -4,8 +4,9 @@ A small local capability server for [Prompd](https://prompd.app). Run it next to
 web app and the browser can reach your machine — most usefully, your **local LLMs**
 (Ollama, LM Studio, vLLM) **without CORS**, plus your filesystem and (opt-in) shell.
 
-It runs only while the command is open, binds to loopback by default, and pairs with
-a token the app reads once.
+It runs only while the command is open, binds to loopback by default, and pairs each
+device once with a single-use code; after that the device proves its own key, and the
+person using it proves who they are (see [Identity](#identity-and-who-may-connect)).
 
 ## Use
 
@@ -15,8 +16,10 @@ In Prompd, open **Connect a sidecar** and follow the steps, or run it directly:
 npx @corenel/sidecar --allow-origin https://prompd.app
 ```
 
-It prints a pairing token; paste that into the app. The `--allow-origin` flag must
-match the site you're connecting from (the app fills it in for you).
+It prints a pairing code and the sidecar's fingerprint; paste them into the app. The
+`--allow-origin` flag must match the site you're connecting from (the app fills it in
+for you). Sign in to the app first: only the account the sidecar is signed in as
+(`corenel-sidecar login`) may connect, or with `--mode team`, members of its org.
 
 ## Options
 
@@ -26,8 +29,11 @@ match the site you're connecting from (the app fills it in for you).
 | `--port <n>` | `4858` | Port to listen on. |
 | `--root <dir>` | cwd | Root the file tools are confined to. |
 | `--allow-shell` | off | Enable the `sidecar_shell_exec` tool (RCE on your machine — opt-in). |
-| `--host <addr>` | `127.0.0.1` | Bind address. Non-loopback is reachable off-box; keep the token secret. |
+| `--host <addr>` | `127.0.0.1` | Bind address. Non-loopback is reachable off-box and needs TLS (below, `--allow-lan`, a tunnel, or `--behind-tls-proxy`); the daemon refuses to serve plain `ws://` off the machine. |
+| `--behind-tls-proxy` | off | A proxy in front terminates TLS (e.g. a container ingress): allows a non-loopback bind without a certificate of its own. |
+| `--mode team` `--org <org id>` | solo | Team mode: members of the Clerk organization may connect (`corenel-sidecar config set org <org id>`; the ID starts with `org_`, from the Clerk dashboard). Solo: only the account the daemon is signed in as. |
 | `--tls-cert <f>` `--tls-key <f>` | _(none)_ | Serve `wss://` (needed for a remote sidecar from an https page). |
+| `--name <text>` | generated | The name the app shows for this sidecar (daemon.json `name`). Without it the name is generated, `<hostname> · <first root folder>`, plus ` :<port>` off the default port, so several sidecars on one machine are told apart. The banner prints it. |
 | `--env <name>` | _(none)_ | Layer `daemon.<name>.json` over `daemon.json` (same state dir), under flags. See [Config environments](#config-environments). |
 
 ## Daemon (preview)
@@ -144,7 +150,7 @@ Manual smoke (manual/client-commanded trigger):
    to use a state dir other than the default, or `--default-model <id>` to give
    agents with no `settings.model` a fallback.
 
-4. **Pair from the app** with the printed token, then command a manual run of the
+4. **Pair from the app** with the printed code, then command a manual run of the
    agent you created. Confirm the reply streams back in the app as it's generated,
    and that a new session appears under `<state dir>/crew/<name>/sessions/<runId>/`.
 
@@ -255,8 +261,8 @@ list and what that gap means.
   10s), a refusal — never fails the run; the ask reaches the same outcome
   it would have reached without push, only later by that bounded wait.
 - **Endpoints are restricted to known push services.** The daemon POSTs to
-  a subscription's endpoint, so an open-ended URL would let anyone holding a
-  pairing token make it send requests to any host it can reach. A
+  a subscription's endpoint, so an open-ended URL would let any paired
+  device make it send requests to any host it can reach. A
   subscription is refused unless its endpoint is `https://` on the default
   port, carries no credentials, and its host is — or is a subdomain of —
   `fcm.googleapis.com` (Chrome/Chromium), `push.services.mozilla.com`
@@ -294,137 +300,107 @@ list and what that gap means.
   subscriptions. A browser re-sends its existing subscription on every
   pairing, so the id it is filed under follows an account switch.
 
-## Identity
-
-On by default. The daemon's issuer is **corenel-api**, not Clerk — the browser
-never gives the daemon its Clerk session token at all (spec amendment
-2026-09-25b). Pairing runs challenge → API assertion → assert:
-
-1. On `hello.wantsIdentity`, the daemon sends `identity-challenge` naming its
-   own `sidecarId` and a fresh, single-use nonce.
-2. The browser exchanges its Clerk token for a short-lived RS256 assertion by
-   calling corenel-api's `POST /api/v1/pairing-assertions` — the Clerk token
-   goes there and nowhere else. The assertion's claims are `aud` (this
-   daemon's `sidecarId`) and `nonce` (the one just issued), which is what
-   closes replay: a captured assertion names one daemon and one nonce that
-   daemon has already consumed, so it verifies nowhere else and never again
-   **[V]** `src/prompd/sidecar/connect.identity.test.ts` ("answers the daemon
-   challenge by fetching the Clerk token, POSTing {aud, nonce, tkh} with it,
-   and sending the returned assertion -- never the Clerk token itself"), which
-   also asserts that the Clerk token never appears in any message this
-   connection ever sends, `hello` included **[V]** same test, and
-   `packages/harness/sidecar/host.identity.test.ts` ("omits wantsIdentity from
-   hello, and never sends identityToken, when not configured") confirms
-   `hello.identityToken` is gone from the wire.
-3. The browser sends `identity-assert` with that assertion. The daemon
-   verifies it against corenel-api's own OIDC discovery/JWKS, checking `aud`,
-   `nonce`, `azp`, `cnf.tkh` (below) and the existing signature/`iss`/`exp`
-   checks **[V]** `packages/sidecar/src/identity/oidcVerifier.test.ts`
-   (`'rejects: %s'` cases `'foreign app (azp)'`, `'missing azp'`, `'wrong
-   aud'`, `'missing aud'`, `'aud array without the audience'`, `'wrong
-   nonce'`, `'missing nonce'`, `'wrong cnf.tkh'`, `'missing cnf'`,
-   `'non-object cnf'`).
-
-**Relay binding (`cnf.tkh`).** `aud` and the nonce stop a captured assertion
-being replayed, but not a LIVE relay: a malicious daemon M that holds this
-daemon's (B's) pairing token connects to B, forwards B's own challenge to a
-victim browser paired with M, and relays the victim's fresh assertion back.
-So step 2 also sends `tkh`, the unpadded base64url SHA-256 of the pairing
-token the browser presented on ITS connection; corenel-api signs it in as
-`cnf: { tkh }`, and the daemon requires it to equal the hash of the token
-presented on the connection the assertion arrives on. The victim's browser
-hashed M's token, not B's, so the relayed assertion pairs unverified
-(`pairing not bound to this connection`) **[V]**
-`packages/sidecar/src/identity/pairingRelay.e2e.test.ts` (two real SidecarServers, the real
-verifier, a test-key API minting exactly what corenel-api mints: the relay
-pairs UNVERIFIED and a direct pairing still verifies; removing the `cnf`
-comparison turns it red), `oidcVerifier.test.ts` ("binds to the
-pairing token"), `packages/harness/sidecar/identityHandshake.test.ts` ("the
-verifier is handed the hash of the pairing token THIS connection presented,
-not another"). The API only ever sees the hash, never the pairing token.
-**[D] Residual, not stopped:** an attacker who hands the victim B's pairing
-token under the attacker's OWN URL (so the victim's browser really presents
-B's token, to M, which proxies it to B) gets an assertion bound to B's token.
-The protocol cannot tell the browser that the daemon at a URL is not the one
-that printed the token; pair a token only with the daemon that printed it.
-
-The pairing token (`hello.token`) is checked FIRST; the challenge is never
-sent before it passes **[V]** `packages/harness/sidecar/identityHandshake.test.ts`
-("never sends a challenge for a bad pairing token"). A missing, late, or
-invalid assertion — or corenel-api being unreachable, or the signing key being
-absent (corenel-api then answers 503 on discovery/assertion) — always pairs
-the connection **unverified**, never refuses it **[V]**
-`identityHandshake.test.ts` ("no assertion arrives within 3000ms: pairs
-unverified, reason \"timed out\"", "a LATE identity-assert, arriving after the
-3000ms bound already answered \"timed out\", is ignored", "a throwing
-verifier pairs unverified with reason \"error\""). The whole identity leg is
-bounded at 3 000 ms from the challenge.
-
-The verified Clerk user id (never the claimed `accounts` text, which stays
-display-only) is the only thing that widens routing to a second device or
-widens push delivery to a device that never subscribed itself — see
-`docs/team-agents.md` §5.2 (at the repository root).
-
-- **Default issuer:** `https://api.corenel.ai` **[V]** `packages/sidecar/src/args.test.ts`
-  ("identity verification is on by default against the API issuer"). Point at
-  a local corenel-api with `--identity-issuer <url>`, or the `daemon.json` key
-  `identityIssuer`.
-- **https rule, with a loopback exception:** the issuer must be `https://`,
-  except a loopback host (`localhost`, `127.0.0.1`, `[::1]`), which may use
-  `http://` — for local development against a corenel-api with no TLS cert to
-  offer **[V]** `args.test.ts` ("rejects http:// on a non-loopback host",
-  "accepts %s (loopback issuer, for local development)" for
-  `http://localhost:4000`, `http://127.0.0.1:4000`, `http://[::1]:4000`); a
-  loopback-lookalike host (`http://localhost.evil.com`, etc.) is still
-  rejected **[V]** `args.test.ts` ("rejects the loopback lookalike %s").
-- **`--no-identity`** turns verification off entirely (`daemon.json`:
-  `identity: false`); every connection then pairs unverified, exactly as
-  before this feature existed.
-- **Keys over https:** the discovery document's `jwks_uri` must be `https://`
-  too — except under a loopback `http://` issuer, where an `http://`
-  `jwks_uri` on the issuer's own origin (same host and port) is accepted, so
-  a local corenel-api works end to end **[V]** `oidcVerifier.test.ts`
-  ("loopback http issuer" describe block: same-origin http verifies; another
-  host, another loopback host or another port does not; an https issuer with
-  an http `jwks_uri` still fails).
-- **Egress:** one OIDC discovery fetch (`<issuer>/.well-known/openid-configuration`)
-  plus one JWKS fetch per hour to the configured issuer, cached together; an
-  unknown `kid` triggers at most one extra refetch per 60 seconds.
-- The Clerk token never reaches the daemon at all, and the assertion itself is
-  never logged and never stored — only the resulting user id is kept, in
-  memory, for the life of the connection.
-- **[D]** The browser's worst case for the whole exchange is roughly 6 s (up to
-  3 s to fetch a fresh Clerk token, plus up to 3 s for the POST to
-  corenel-api) against the daemon's fixed 3 s bound from the challenge — a
-  slow answer pairs unverified, not refused.
+## Identity and who may connect
+
+Pairing proves two things on every connection: the DEVICE (a key the daemon
+recorded when the device enrolled with a single-use pairing code; see the
+device enrollment spec) and the PERSON (a verified identity). Both are
+required; there is no switch to turn identity off. A connection that cannot
+prove both gets the same `denied: invalid credentials` as any other bad
+credential, and nothing is served before it is authenticated.
+
+**Who may connect** follows the existing `--mode team` switch:
+
+- **Solo** (the default): only the account this daemon is signed in as
+  (`corenel-sidecar login`, or `CORENEL_TOKEN`). The daemon learns that
+  account's Clerk user id at startup from `GET <endpoint>/auth/me` with its
+  own credential, re-reads it every 15 minutes and whenever its sign-in
+  changes, and FAILS CLOSED: until it knows, no one may connect, and the
+  banner's `who may connect:` line says why. An `org` set in solo mode is
+  ignored, with a log line saying so.
+- **Team** (`--mode team`): only members of ONE Clerk organization, named by
+  its ID (`org_...`, from the Clerk dashboard; never a slug, which can be
+  renamed or taken by another org) with `corenel-sidecar config set org <org id>`
+  (daemon.json `org`, or `--org <org id>`). Team mode without a valid org ID
+  refuses to start, naming that command. Membership is checked by corenel-api
+  on every connect against Clerk's membership list for the verified user (not
+  the session's active org), cached at most 60 s; the daemon admits an
+  assertion whose `org_id` claim is its own org ID. Any role counts. A device
+  belongs to the first member who connected on it. Every open connection is re-challenged every 15 minutes
+  and closed when the same user cannot re-assert membership, so a removed
+  member is out within 15 minutes. Over the wire a member may revoke only
+  their own devices (those recorded under their verified user), and may read
+  a run's output (reports, check output, files) or watch it only for runs
+  they started;
+  the operator's local `corenel-sidecar devices revoke` keeps full power.
+
+**The exchange.** Once the device key is proven (and, for an enrollment,
+before the code is burned), the daemon sends `identity-challenge` naming its
+own `sidecarId`, a fresh single-use nonce and, in team mode, its org. The
+client obtains a one-minute RS256 assertion from corenel-api's
+`POST /api/v1/pairing-assertions` (`{ aud, nonce, jkt, org_id? }`): a browser
+with its Clerk session token, the `corenel` CLI with its `cnl_cli_` login
+token, which must carry the `pair` scope (granted only when the person
+approving `corenel login` ticks "Also let this machine connect to your
+sidecars"; without it, log in again). That token goes to corenel-api and nowhere else; it never crosses the
+daemon socket. The client answers with `identity-assert`, and the daemon
+verifies the assertion locally against corenel-api's OIDC discovery and JWKS:
+signature, `iss`, `exp`, `aud` (this daemon), `nonce` (this challenge),
+`azp` (an allowlisted origin, or `corenel-cli` for a CLI assertion) and
+`cnf.jkt`, which must be the thumbprint of the device key THIS connection
+proved. That binding stops a live relay: a daemon that forwards another
+daemon's challenge to a browser paired with it gets an assertion bound to
+that browser's key for IT, which the other daemon refuses; and a client only
+answers a challenge from the daemon that proved the key it pinned.
+The whole identity leg is bounded at 10 s from the challenge; a missing,
+late, oversized or invalid assertion is a refusal.
+
+**What the client can say.** The refusal is uniform on the wire, but the
+client knows when it had no identity to offer and says so: not signed in,
+not a member of the org, or the sign-in service could not vouch in time. The
+device is kept in those cases; only a device the daemon refused is
+forgotten.
+
+- **Default issuer:** `https://api.corenel.ai`. Point at a local corenel-api
+  with `--identity-issuer <url>` (daemon.json `identityIssuer`). It must be
+  `https://`, except a loopback host, which may use `http://`, and its
+  `jwks_uri` follows the same rule (same origin under a loopback issuer).
+- **Egress:** one discovery fetch plus one JWKS fetch per hour to the issuer,
+  cached together; an unknown `kid` refetches at most once a minute. In solo
+  mode, one `GET <endpoint>/auth/me` at startup and every 15 minutes.
+- The assertion is never logged or stored; only the verified user id is kept,
+  in memory, for the life of the connection (and recorded on the device).
 - **[D]** corenel-api only stamps `azp` for request origins in its own CORS
-  allowlist. A page served from an origin missing there pairs unverified even
-  with a valid Clerk session; local https dev against a local corenel-api
-  needs that instance's `FRONTEND_URL` set to the dev origin.
+  allowlist, so a page served from an origin missing there is refused.
 - **[D]** Both web apps call `https://api.corenel.ai/api/v1/pairing-assertions`
-  directly (`VITE_PAIRING_ASSERTION_URL` in each app's `vite.config.ts`),
-  never through a front end's own `/api` proxy: the route's pre-auth limiter is
-  per client IP, and behind a proxy every user of that front end would share
-  one address and one bucket.
-- The runbook for provisioning and rotating the signing key
-  (`corenel-pairing-signing-key`) lives in corenel-api's own
-  `docs/pairing-signing-key.md`, not in this repo.
-
-**`corenel doctor` Identity section.** Computed from the EFFECTIVE config
-(flags/file/overlay already layered), never a second guess: `identity:
-disabled` when `--no-identity`/`identity: false`; otherwise the issuer URL and
-whether it passes the https/loopback rule, a real discovery fetch (5 s
-timeout, the SAME code the verifier uses), whether the document's `issuer`
-matches, whether `jwks_uri` is accepted under the same https/loopback rule,
-how many usable RS256 keys it lists (zero is a failure), the trusted origins
-(canonical defaults + `--allow-origin`), and a warning when `--allow-lan` is
-on that a LAN-allowed page can connect but can never verify identity unless
-its origin is also in `allowOrigins`. Included in `--json`.
+  directly (`VITE_PAIRING_ASSERTION_URL`), never through a front end's own
+  `/api` proxy, whose single egress address would share one rate-limit bucket.
+- The runbook for the signing key (`corenel-pairing-signing-key`) lives in
+  corenel-api's `docs/pairing-signing-key.md`.
+
+**Before a connection authenticates** the daemon keeps its cost bounded: a
+daemon-wide limiter refuses an address after 10 failed hellos in a minute
+(keyed by IPv4 address or IPv6 /64; off with `--behind-tls-proxy`, where
+every peer is the proxy), lets one address hold at most 4 unauthenticated
+connections, and holds at most 32 daemon-wide (HTTP 429 and 503 at the
+upgrade); a plain HTTP request to the port gets
+`426`; request headers must arrive within 10 s; a frame over 64 KiB before
+the welcome closes the socket unparsed; and a hello that does not pair within
+20 s is closed.
+
+**`corenel doctor` Identity section.** Computed from the EFFECTIVE config: who
+the daemon admits (solo, or the team org; team mode without an org is a
+failure), the issuer URL and whether it passes the https/loopback rule, a
+real discovery fetch (the same code the verifier uses), whether the
+document's `issuer` matches, whether `jwks_uri` is accepted, how many usable
+RS256 keys it lists (zero is a failure), the trusted origins, and a warning
+when `--allow-lan` is on that a LAN-allowed page is refused unless its origin
+is also in `allowOrigins`. Included in `--json`.
 
 ## Security
 
-- Loopback by default; a browser connection requires both the pairing token **and** an
-  allowed Origin.
+- Loopback by default; a browser connection requires a recorded device key, a verified
+  identity this daemon admits, **and** an allowed Origin.
 - The HTTP proxy (for local LLMs) only reaches **loopback** hosts — it can't be used as
   an SSRF pivot to internal services.
 - `sidecar_shell_exec` is off unless you pass `--allow-shell`.