Skip to content

Phase 3 (part 1): the credential exchange, so an admin can read gated docs without a browser - #1384

Merged
neuromechanist merged 7 commits into
feature/issue-1336-epic-agent-docsfrom
feature/issue-1341-phase3-private-admin-source
Sep 14, 2026
Merged

neuromechanist merged 7 commits into
feature/issue-1336-epic-agent-docsfrom
feature/issue-1341-phase3-private-admin-source

Conversation

@neuromechanist

@neuromechanist neuromechanist commented Sep 13, 2026 •

Copy link
Copy Markdown
Contributor

Summary

The part of phase 3 that does not depend on nemarOrg/docs being private yet. Adds POST /auth/docs/cli-session and the nemar 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.txt and docs ADR 0002) all depend on the flip, which is blocked on DOCS_READ_TOKEN existing 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.org and the credential has to be set on docs.nemar.org. A CLI crosses no host boundary: it holds a long-lived key and api.nemar.org is the one host that can validate it. So cli-session is 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-Session as a header." It does not. The deployed functions/_middleware.ts reads the credential from the Cookie header; X-Docs-Session is what the Function itself presents to /auth/docs/verify. Checked against origin/main rather 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 in nemarOrg/docs needed a change and no second accepted-credential surface was created.

Design notes worth reviewing

  • Bearer only; the app cookie is refused. authMiddleware would take either. Accepting the cookie here would put a docs credential one cross-site POST away from any signed-in browser, which is exactly why grant checks Origin before anything else. The route resolves the bearer itself so the cookie path is absent rather than discouraged.
  • Fifteen minutes, not eight hours. A program's credential reaches shell histories, CI logs and agent transcripts; a person's browser session does not.
  • No flag prints the session value. A credential on stdout is a credential in a shell history, which is the class of exposure the short TTL hedges against. The command holds it in memory and prints only documentation.
  • Several paths per invocation share one mint. The mint is in the strict 10/min per-address bucket, so a page-at-a-time loop would spend the budget on credentials rather than reading.
  • The mint statement's gates are redundant here, and the comment now says so. On the grant path a grant row is up to sixty seconds old, so re-reading role and status at mint closes a real window. On this path resolveBearerUser re-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

  • 64 tests in backend/test/docs-auth-routes.test.ts (was 46), real D1 via bun:sqlite with every migration, real Hono dispatch, no mocks.
  • 16 tests in test/docs-fetch.unit.test.ts, driving bun 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 and redirect: "manual" are observed on the wire.
  • Mutation-checked rather than assumed green. Each of these was made to fail and then restored:
    • removing both role gates turns the member and demotion tests red (either one alone is absorbed by the other layer, which is measured, not claimed);
    • removing the mint statement's role gate turns exactly one statement-level test red;
    • making the route accept the app cookie turns the cookie-refusal test red;
    • sending the API key to the docs host turns the key-leak test red;
    • redirect: "follow" turns the redirect test red.
  • Full suite: 6679 pass, 215 skip, 0 fail. An earlier run of the same suite had one failure that did not reproduce; the two new files ran five times in a row clean, so it was not one of them, but it was not identified.
  • bun run typecheck and bun run lint clean.

Part of epic #1336. Advances #1341.

neuromechanist and others added 3 commits September 13, 2026 14:21
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>
@github-actions

github-actions Bot commented Sep 13, 2026 •

Copy link
Copy Markdown

📦 Package Preview

Your package is ready to test!

bun install -g nemar-cli@PR1384

Version: 0.10.4-PR1384.5374cd3
Commit: 5374cd3


🤖 Updated on each push.

neuromechanist and others added 2 commits September 13, 2026 14:49
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>
@neuromechanist

Copy link
Copy Markdown
Contributor Author

Review round 1: all ten findings addressed

Two of them were real defects rather than polish, and one is a pre-existing security hole this PR happened to surface.

The /nemar mount prefix bypassed the strict rate-limit bucket on every auth path

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.

Verified independently before acting: middleware inside the prefixed mount reports c.req.path as /nemar/auth/docs/cli-session, both spellings reach the same handler, and __selectBucket returns auth-ip/10 for the plain spelling and ip/500 for the prefixed one. With a bearer it is worse: token/1000, and an admin or owner token skips the limiter entirely via isPrivilegedToken, which is exactly the population that can mint here.

This was true of every AUTH_PATHS entry and long predates this PR: /auth/login, /auth/code/request, /auth/keys, the device-flow routes, /users/me/upload-access/request. Fixed in __selectBucket, the one place that turns a path into a bucket, so a rule added later inherits it; the data and zarr planes benefit too. Ten new assertions across eight auth paths, and disabling the normalization turns ten of them red.

I also removed the sentence in this PR that asserted the property held. It didn't, and the comment now says so.

nemar admin docs exited 0 and wrote its error to stdout

The exact failure the command's own contract promises against: nemar admin docs x > page.md with no credentials exited 0 and put "Error: Not authenticated" into page.md, where the intended caller, a script or an agent, would parse it as documentation. The shared requireAuth() and handleCommandError() both print with console.log and the former sets no exit code.

This command now reports to stderr and exits 1, with a comment explaining why it does not use the shared pair. Measured after the fix: EXIT=1, page.md is 0 bytes, message on stderr.

The test could not have caught it: it asserted on result.combined, which is stream-agnostic by construction, and never checked exitCode. Replaced with per-stream and exit-code assertions; reverting the fix now turns it red.

Also fixed

  • notFoundResponse sets no-store. This file declares that every answer it gives may never sit in a shared cache, but both of its 404s returned that shared response, which carried no cache header, so the invariant was false. Set in lib/not-found.ts rather than at the call site, which keeps the refusal byte-identical to a genuinely unrouted 404 instead of making it distinguishable by one header.
  • Paths are parsed before minting, so a call with only malformed paths no longer spends a credential from the strict bucket.
  • A 20s timeout on page fetches; a hung docs host previously spun the spinner forever.
  • AuthMethod lists api_key.
  • Four comment overclaims corrected, including two I introduced: the CLI's User-Agent does not land in web_sessions.user_agent, and three things in this repo read the contract rather than two (the omission being services/docs-auth.ts, which interpolates DOCS_ADMIN_ROLES into both mint statements and is the most load-bearing reader of any value in that file).
  • A statement-level test renamed to the claim it can actually support.
  • --no-headers, a refused mint, and the parse-before-mint path now have tests. Multi-path concatenation with no stdout delimiter is documented as deliberate: a separator on stdout would contaminate the single-page redirect, which is the common case.
  • American English in one comment.

Verification

Full suite: 6694 pass, 215 skip, 0 fail (was 6679 before these fixes). bun run typecheck and bun run lint clean.

The review also confirmed clean, with independent checks I had not done: no SSRF or open redirect in toMirrorPath across nine hostile spellings, scope separation mutation-tested from the other side, no mocks replacing business logic, and the cross-repo cookie assumption verified against the deployed Pages Function.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…cs' into feature/issue-1341-phase3-private-admin-source
@neuromechanist
neuromechanist merged commit d7bfedd into feature/issue-1336-epic-agent-docs Sep 14, 2026
12 checks passed
@neuromechanist
neuromechanist deleted the feature/issue-1341-phase3-private-admin-source branch September 14, 2026 12:27

This branch was previously deployed

1 inactive deployment
npm — 5374cd30 Deployed Sep 14, 2026 by neuromechanist via publish #2544
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant