Cursor rule

1---
2description: crit — proxy auth transport
3alwaysApply: false
4---
5 
6# Proxy Auth Transport Rules
7 
8 
9 
10## Rule 1: Both transport modes required
11 
12Every CLI command or browser UI action that calls a crit-web API must work in both modes:
13- **Direct** (default): Go server makes HTTP requests with bearer token
14- **Browser relay** (`proxy_auth: true`): Browser popup mediates the same API call through an authenticated session
15 
16When adding a new crit-web interaction:
171. Add the direct HTTP path in Go (share.go or relevant file)
182. Add a server endpoint that returns the payload for the popup relay (server.go)
193. Add a popup handler in `crit-web/assets/js/share_receiver/handlers.js` (note: the directory/route is named `share_receiver` / `/share-receiver` — this describes what the component *does* (receives share data), while `proxy_auth` describes *why* it's needed. Both names are correct at their level.)
204. Add the relay call in `web/app.js` gated on `proxy_auth`
21 
22## Rule 2: Relay is transport, not protocol
23 
24The popup relay must hit the **same crit-web API endpoints** with the **same payload shapes** as the direct path. No relay-specific endpoints on crit-web. The popup handlers are same-origin fetch proxies.
25 
26## Rule 3: Terminal CLI commands cannot use direct HTTP when proxy_auth is on
27 
28When `proxy_auth: true` (global config), crit-web sits behind an SSO reverse proxy. The terminal cannot complete that auth flow — only the browser can (via the `/share-receiver` popup relay).
29 
30**Terminal subcommands** that HTTP-call crit-web directly (today: `crit share`, `crit fetch`, `crit unpublish`) must call `checkProxyAuthCLIAllowed("crit <cmd>")` at the top of their `Run*` entrypoint and exit with the shared error message. Do not attempt the network call.
31 
32**Browser UI actions** (Share / Pull / Unpublish / Re-share buttons in the review page) must still work: implement both transports per Rule 1 — direct when `proxy_auth` is false, popup relay when true (`web/crit-share.js` + crit-web `share_receiver/handlers.js`).
33 
34Direct (non-proxy_auth) browser actions must go through the **local Go server**, never `fetch(shareURL + …)` cross-origin:
35 
36| Action    | Local endpoint                          |
37|-----------|-----------------------------------------|
38| Share     | `POST /api/share`                       |
39| Pull      | `POST /api/share/pull`                  |
40| Re-share  | `POST /api/share/reshare`               |
41| Unpublish | `DELETE /api/share-url`                 |
42 
43(The Go handlers attach the bearer token and talk to crit-web. Cross-origin browser fetches fail CORS on selfhosted+OAuth instances because preflight has no `Authorization`, and even with CORS fixed the browser never sends the token.)
44 
45The `share-transport` Playwright project (`test/e2e/tests/share-transport.sharetransport.spec.ts`) drives these three actions against a stub crit-web on a different origin and fails if the page issues any request to it, so a regression to cross-origin fetches is caught in CI. Extend that spec when you add a browser action that talks to crit-web.
46 
47When adding a **new** crit-web interaction, decide which surface owns it:
48- **Browser-only** (like today's share/pull/unpublish behind SSO): block the terminal path with `checkProxyAuthCLIAllowed`; add relay handler + frontend branch.
49- **Terminal-only** (rare): document that it won't work behind SSO, or don't add it.
50- **Both**: direct Go HTTP path + browser relay path; terminal path still blocked when `proxy_auth` is on unless you have a non-HTTP auth story.
51 
52Integration tests that spawn the `crit` binary must isolate config — use `runCritCmd` / `runCritCmdWithHome` with a temp `HOME`, not the developer's real `~/.crit.config.json`.
53