Close the Pathbase auth gap: broker-family lease vs stored-session secret vs upstream token flag

[bdelanghe]

Follow-up to #112 (installed + egress verified; path share still can't run unattended). Verified against path-cli 0.16.1: path auth login is grant-code only — an 8-character one-time code from pathbase.dev/auth/cli, pasted via --code — which no unattended session can complete. No token flag, no token env var, though the API's pat_… bearer tokens exist.

"Could we use the broker workflow for this?" — the maintainer's question, answered in parts:

• Egress: no, and no need. The network allowlist is platform config, not a credential — and that lever is already pulled and verified live.
• Credential custody: yes, that's the org-consistent shape — but as a lease (the front-desk-lease shape), not the ticket-window shape. claim-ticket.yml works by keeping the credential in the workflow, so the caller never holds it. That inverts here: the upload must run inside the session, because that's where the transcript lives — so the credential must reach the session. The analogous mechanism is a Worker holding a pat_… for a dedicated org Pathbase identity as a Worker secret, leasing it to sessions with an audit log. One custody point, one revocation point (DELETE /api/v1/auth/sessions/{id}), and the workers are already on the environment allowlist.
• The honest caveat: a session has no identity proof to present — GitHub Actions has OIDC; sessions don't. Until the session-identity gap closes (the Merge gate: verify a PR's branch/commits trace to a Front Desk claim naming them #113 family), the lease's release check is only as strong as the network boundary. Worth stating in the lease's header the way claim-ticket.yml states its fail direction.

Dependency either way: the CLI must accept a provided token. That's upstream path-cli surface (env var or flag over the existing bearer scheme) — and the maintainer works at Empathic now, so it's ours to land. The stored-session-file-as-environment-secret shape is the stopgap that needs no upstream change (file location/portability unverified — observe after the first real login, don't guess).

Suggested order: (1) upstream token support, (2) broker lease holding the org pat_…, (3) hook wiring, (4) first live path share pasted on its own PR.

Runbook context: .github-private → docs/handoffs/toolpath-pathbase.md (lever 2).

[bounded-systems-front-desk]

🎫 Claimed by claude/cloud-session-dispatcher-test-rjoaj1 (cloud session) — run

Release by removing the claimed label (and unassigning) if work stops without a merged PR.

[bdelanghe]

Claimed and worked from a fresh cloud session. Step 1 is written and verified; it is not landed, and cannot be from a bounded-systems session.

The gap, confirmed on the shipped binary

Not taken from the ticket — re-measured against path 0.16.1 as installed by the hook:

$ PATHBASE_TOKEN=pat_fake_probe path auth status
Not logged in. Run `path auth login`.

Ignored entirely. cmd_auth.rs at upstream HEAD (17907af) confirms it: login takes --code or an interactive paste, nothing else, and grep -rn "PATHBASE_TOKEN\|--token" across the tree returns empty.

What's implemented

Patch is in .github-private (bounded-systems/.github-private#302) at docs/handoffs/patches/pathbase-token-env.patch, against empathic/toolpath@17907af, base commit and apply instructions in the header.

preflight_auth already resolved the username via api_me, so an env token needs no stored user object — the change is a Session type carrying a SessionSource, resolved env-first, mirroring the precedence $PATHBASE_URL already has over the default server. Touches cmd_pathbase.rs, cmd_auth.rs, derive.rs, cmd_export.rs (+326/−42 including docs and CHANGELOG).

Two design calls, both worth arguing with:

• Env var only, no --token flag. A flag leaks into ps and shell history, and every caller that needs this has a secret store.
• The credential source is stated, never silently used — an exported variable is ambient in a way a file is not. Uploads print note: authenticating with the $PATHBASE_TOKEN credential; auth status names the source and flags a shadowed credentials.json; auth logout clears the file only (there is no logging out of a variable) and says when a token is still exported. Blank is treated as unset, so PATHBASE_TOKEN="$UNSET_SECRET" falls back to stored credentials rather than sending an empty bearer and earning a confusing 401.

Verified: cargo check --all-targets clean, 363 unit tests pass (358 baseline + 5 new), clippy --all-targets silent, all five auth states smoke-tested on the built binary.

The blocker — a session-creation lever, not a code problem

add_repo refuses the upstream repo:

cross-tier adds are not supported in v1: requested "empathic/toolpath" but session already has repos from owner(s) [bounded-systems]

The anonymous git lane clones empathic/toolpath fine, so upstream is readable and patchable from any session — only pushing needs it attached as the session's initial source. Landing step 1 therefore needs a session created with empathic/toolpath as its initial source; it is a hard prerequisite, not a nicety. Same class of lever as attaching the declared working-set repos at creation (this session started with the scope warning for infra and ci-workflows, both since attached mid-session).

Two side findings

• pathbase.dev egress re-confirmed live — auth logout with a synthetic stored token got a real 401 Unauthorized back. A 401 is better proof than a 200: it is the server's own auth layer answering, so the request crossed the boundary intact. Lever 2's network precondition holds.
• Session storage is no longer unverified (lever 3 in the runbook): $TOOLPATH_CONFIG_DIR/credentials.json, default ~/.toolpath/, file 0600, parent 0700, flat JSON {url, token, user{id,username,email}} — read from source and demonstrated by feeding a synthetic file to the installed binary. Still untested: whether a real server-issued token survives being copied between machines. That one needs a real login, and guessing it into a hook is exactly what the runbook warns against.

Steps 2–4 (broker lease, hook wiring, first live path share) are untouched. Releasing the claim is a judgement call for whoever picks this up — the patch is stored where it outlives the container that produced it.

---

Generated by Claude Code

[bdelanghe]

Setup session, part 2 — the blocker from the last comment is dissolved and steps 1–3 now all have PRs.

Step 1 (upstream token support) — unblocked by the fork: bounded-systems/toolpath exists (and the standing direction is that forking into the org is the pattern for cross-owner work — same-owner add_repo succeeds where the cross-tier add refuses). feat/pathbase-token-env carries the change, tests + clippy re-verified green on the branch. One click remains: open the upstream PR from the compare view.

Step 2 (broker lease) — bounded-systems/infra#231: POST /lease/<name>, staged and inert (LEASE_KEYS ships "{}"). Bearer-possession release check stated honestly in the header per the fail-direction rule; quarantined-keys-only enforced as code (entries naming CF_*/GH_APP_*/DOLTHUB_* secrets are refused as misconfigured); every release audited with claims: null — the record says nothing was verified. 123/123 tests. The /session tier stays the upgrade path once the #113 family produces an issuer.

Step 3 (hook wiring) — #118: if PATHBASE_LEASE_URL + PATHBASE_LEASE_KEY are in the environment config, setup-toolpath.sh redeems them into credentials.json (0600). Verified end to end against a stand-in broker — and the loop closes with the stock 0.16.1 binary reporting Logged in, so the lease works today with no patched CLI anywhere. The upstream env-var change stays the better explicit-source UX, not a dependency.

Step 4 (first live path share) — blocked only on the go-live levers now, all human, in order:

1. Create the dedicated org Pathbase identity; mint its pat_…
2. wrangler secret put PATHBASE_PAT + wrangler secret put LEASE_KEY_PATHBASE
3. The lease tier's own independent /security-review (the packaged skill couldn't run in the authoring session — cwd pinning — so #231 carries a manual trust-boundary review and the staged posture; the independent run is still owed before seeding)
4. Seed LEASE_KEYS with the pathbase entry (shape in wrangler.jsonc)
5. Set the two PATHBASE_LEASE_* env vars in the environment selector

Side finding recorded in the runbook: the release-asset lane fetches 200 through the session proxy (measured) — the "no prebuilt binary" reading conflated repo scope with the asset lane, so #112's digest-pinned-binary ratchet is unblocked on the network side and needs only release CI on the fork.

---

Generated by Claude Code

[bdelanghe]

Correction to the comment above: no upstream PR — the owner's explicit call. Disregard the compare-view link; the fork (bounded-systems/toolpath, branch feat/pathbase-token-env) is the org's carrying line for the token change, and upstreaming is the owner's decision to revisit. The runbook ratchet now says the same, so no future claimant acts on the stale instruction. Nothing else in the comment changes — the lease path needs no patched CLI, and the deploy ratchet can build from the fork.

---

Generated by Claude Code

[bdelanghe]

🎫 Claim released — claude/cloud-session-dispatcher-test-rjoaj1's session is closing with its work merged, so the claim comes off rather than being held by a dead container.

State at release:

• Steps 1–3: done and merged. Token support on the fork's main (feat(path-cli): read $PATHBASE_TOKEN for non-interactive auth toolpath#1, a1b1705); broker /lease/<name> tier staged+inert on infra main (#231); hook lease wiring on .github main (session-start: redeem a Pathbase lease into credentials the stock CLI reads #118). Runbook current, including the no-upstream-PR decision.
• Step 4 (first live path share) is NOT claimable work yet — it's blocked on the five human go-live levers listed on infra#231 (Pathbase identity + pat_…, two Worker secrets, the tier's independent /security-review, seed LEASE_KEYS, set the environment vars). Once those are pulled, step 4 is a fresh claim for whichever session gets there: verify the SessionStart line says the lease redeemed, run path share, paste the URL on that session's PR.

---

Generated by Claude Code

[bdelanghe]

Lever 4 done — the tier is deployed and armed (broker version 1532a3ad, after its environment-approval gate). Probed live:

probe	result	meaning
POST /lease/zzz-not-a-lease	404 unknown lease: …	tier is serving (pre-deploy this was 401)
POST /lease/pathbase + wrong bearer	401 not 500	both Worker Secrets landed
POST /lease/constructor	404, nothing enumerated	own-property guard holds live
GET /	405	other tiers unaffected

Worth recording: a bare 401 at /lease/<name> proves nothing — before the tier existed that path fell through to the default OIDC route, which also answers 401. The two rows above are the honest discriminators. Runbook updated (.github-private#306).

Remaining on this ticket: lever 5 only — PATHBASE_LEASE_URL + PATHBASE_LEASE_KEY (secret-type) in the environment selector. Then step 4, the first live path share, is a fresh claim for whoever runs it.

Two notes on the review gate, stated plainly rather than quietly dropped: the independent /security-review never ran as its own session — two attempts misfired (one landed on bdelanghe/infra, the wrong repo; one couldn't anchor a cwd) — and the owner deployed on that basis. The two flags an external reviewer raised were answered against the code instead: LEASE_KEYS holds secret names, never material (rotation is a wrangler secret put, not a history rewrite), and unsafeLeaseEntry is a detector in the unsafePrivilegedApp mould rather than a function with a caller-side precondition — one non-test caller, running before the bearer compare. The reviewer's criticism that the name misleads anyone who hasn't met the idiom stands. The tier's own review is still owed.

Also: the identity in the registry is robert-dev, the owner's personal dev identity — a recorded deviation from the dedicated-org-identity recommendation, the owner's explicit call.

New follow-up filed as #119: Pathbase's request-grant accepts a pat_… bearer (verified live — 200, 8-char code, 600s TTL), so the tier can become a minter rather than a vault. That would keep the master credential inside the Worker and give every session its own revocable token. Ratchet, not a blocker.

---

Generated by Claude Code

[bdelanghe]

Correction — lever 5 is blocked, and my earlier instruction for it was wrong.

I wrote "PATHBASE_LEASE_KEY (secret-type) in the environment selector". There is no secret type. Anthropic's docs (/docs/en/cloud-environments) say the opposite:

"Anyone who uses the environment can read the values, and cloud environments have no dedicated secrets store, so don't add API keys or other credentials."

Environment variables are ordinary env vars readable by any command a session runs — repo scripts, dependencies, anything reaching a session through untrusted content. So the lease key's exposure set is everything that executes in any session using that environment.

That would be acceptable if the lease key were the weak, rotatable pointer the tier's header describes. It isn't yet: redeeming the lease returns the master pat_…, so a leaked lease key becomes durable full access to the Pathbase identity. The indirection buys nothing while the released artifact is as strong as the credential it protects.

So #119 is a prerequisite for lever 5, not the ratchet I filed it as. With the minter, a leaked key yields 10-minute single-use codes whose tokens are individually enumerable and revocable — pointer weaker than credential, which is what makes no-secrets-store custody defensible.

Lever 5 before #119 remains possible as a deliberate, time-boxed accepted risk on an environment nobody else uses. It should not be presented — as I did — as the last easy step. Runbook corrected in .github-private#307.

Nothing deployed changes: the tier stays armed and unused, which is the right resting state while this holds.

---

Generated by Claude Code