Repository navigation
Phase 3 (part 1): the credential exchange, so an admin can read gated docs without a browser - #1384
Conversation
Mints a docs-scoped session from a CLI API key, so an admin can read a gated documentation page without a browser. The three-hop browser handoff exists because proof of identity and the credential live on different hosts; a CLI call crosses nothing, so this is that handoff in one step with the mint-time gates intact. Bearer only: accepting the app cookie would make the route a cross-site POST away from minting a docs credential from an ambient session. The mint statement's role, status and deleted_at gates are redundant on this path, unlike the grant path where the grant row is up to sixty seconds old. Kept so the statement holds its own contract, and tested by running it directly, because through the route each layer hides the other (measured: removing either alone leaves every route test green). Tested: 64 tests in backend/test/docs-auth-routes.test.ts, including that an app cookie is refused, that the value does not authenticate the management API, and that both gates removed turns the right two red. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Trades the stored API key for a fifteen-minute docs-scoped session and sends only that to docs.nemar.org, as a Cookie header the gate already reads. The key never reaches the docs host or its logs. The gate does NOT accept X-Docs-Session from a client, contrary to what issue #1341 assumed; that header is what the Pages Function presents to verify. Checked against the deployed Function. Nothing in nemarOrg/docs needed a change. Several paths share one mint, because the mint sits in the strict 10/min per-address bucket and a reading session should cost one credential. There is deliberately no flag that prints the session value: a credential on stdout is one in a shell history. Bodies go to stdout and diagnostics to stderr, so redirecting yields the page. Tested: 16 tests driving the real entry point against local stand-ins for both hosts, including that no header sent to the docs host contains the API key, and that the gate's 302 is not followed and reported as a page. Both proven to fail under the corresponding mutation. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
📦 Package PreviewYour package is ready to test! bun install -g nemar-cli@PR1384Version: 🤖 Updated on each push. |
backend/src/index.ts mounts the API sub-app twice, at / and at /nemar, and Hono hands middleware the full request path. So every path rule in rateLimit.ts saw /nemar/auth/login for one of the two spellings and matched none of them. Every AUTH_PATHS entry was affected, not just the docs route whose review found it: /auth/login, /auth/code/request, /auth/keys and the device-flow routes all sat behind a strict 10/min floor that one extra path segment stepped over, landing in the 500/min ip bucket or, with a bearer, the 1000/min token bucket and the admin bypass past that. Normalized in __selectBucket, the one place that turns a path into a bucket, so a rule added later gets it for free. The data and zarr planes benefit the same way. Measured, not inferred: middleware inside the prefixed mount reports c.req.path as /nemar/auth/docs/cli-session, and both spellings reach the same handler. Tested: 10 new assertions across eight auth paths plus the zarr plane; disabling the normalization turns 10 of them red. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Correctness: - nemar admin docs exited 0 and wrote its error to stdout when unauthenticated, so `nemar admin docs x > page.md` with no credentials produced a success exit and "Error: Not authenticated" sitting in page.md where a script would read it as the page. It now reports to stderr and exits 1. Same fix for the mint-failure hint, which went through handleCommandError's console.log. - Paths are parsed before the session is minted, so a call with only malformed paths no longer spends a credential from the strict bucket. - Page fetches carry a 20s timeout; a hung docs host previously spun the spinner forever, which for a script means a command that never returns. - notFoundResponse sets no-store. routes/auth-docs.ts declares that every answer it gives may never sit in a shared cache, but its two 404s returned this response, which carried no cache header. Setting it here rather than at the call site keeps the refusal byte-identical to a genuinely unrouted 404, which is the parity that file exists to hold. - AuthMethod lists 'api_key', the third value the docs mint writes. Comments that claimed more than the code did: - The CLI's User-Agent does not land in web_sessions.user_agent; that column is written at mint time from a request the API client sets no User-Agent on. - Three things in this repo read the contract, not two. The omitted one, services/docs-auth.ts, is the most load-bearing: it interpolates DOCS_ADMIN_ROLES into both mint statements. - Three symbols were added outside the three-party contract, not two. - A statement-level test was named for a claim it cannot support; renamed to what it checks. Tests: exit code and per-stream assertions replace the stream-agnostic `combined` check that was blind to both bugs above; --no-headers, a refused mint, and the parse-before-mint path are now covered. Reverting the requireAuth fix turns the unauthenticated test red. American English in one comment. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Review round 1: all ten findings addressedTwo of them were real defects rather than polish, and one is a pre-existing security hole this PR happened to surface. The
|
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…cs' into feature/issue-1341-phase3-private-admin-source
d7bfedd
into
feature/issue-1336-epic-agent-docs
Summary
The part of phase 3 that does not depend on
nemarOrg/docsbeing private yet. AddsPOST /auth/docs/cli-sessionand thenemar admin docs <path...>command that uses it, so an admin holding only a CLI API key can retrieve a gated documentation page as Markdown.This is scope item 4 of #1341. Items 1, 2, 3 and 5 (the visibility flip, moving the runbooks in, repointing the pointers, and correcting
robots.txtand docs ADR 0002) all depend on the flip, which is blocked onDOCS_READ_TOKENexisting on this repo. They follow in a second PR.What it does
The browser handoff has three hops because a visitor's proof of identity lives on
app.nemar.organd the credential has to be set ondocs.nemar.org. A CLI crosses no host boundary: it holds a long-lived key andapi.nemar.orgis the one host that can validate it. Socli-sessionis the whole handoff in one authenticated call, with every mint-time gate intact.The separation ADR 0056 exists for is preserved: the API key authenticates exactly one request, to the API, and is traded for a fifteen-minute read-only docs-scoped value. Only that value is sent onward. The long-lived key never reaches the docs host or its logs.
A correction to the issue
#1341 says "The Pages Function already accepts
X-Docs-Sessionas a header." It does not. The deployedfunctions/_middleware.tsreads the credential from theCookieheader;X-Docs-Sessionis what the Function itself presents to/auth/docs/verify. Checked againstorigin/mainrather than assumed.That turns out better than the premise: a client setting
Cookie: __Host-nemar_docs_session=<value>enters through the same door a browser does, so nothing innemarOrg/docsneeded a change and no second accepted-credential surface was created.Design notes worth reviewing
authMiddlewarewould take either. Accepting the cookie here would put a docs credential one cross-site POST away from any signed-in browser, which is exactly whygrantchecksOriginbefore anything else. The route resolves the bearer itself so the cookie path is absent rather than discouraged.resolveBearerUserre-read them microseconds earlier in the same request. The gates are kept so the statement holds its own contract regardless of caller, and are tested by running the statement directly, because through the route each layer hides the other.Test plan
backend/test/docs-auth-routes.test.ts(was 46), real D1 via bun:sqlite with every migration, real Hono dispatch, no mocks.test/docs-fetch.unit.test.ts, drivingbun run src/index.ts admin docs ...as a subprocess against two real local HTTP servers standing in for the API and docs hosts, so the cookie header andredirect: "manual"are observed on the wire.redirect: "follow"turns the redirect test red.bun run typecheckandbun run lintclean.Part of epic #1336. Advances #1341.