feat(cli): route custody through the hub /api/v1 (thin CLI Step 10)

[madarco]

What

Step 10 of docs/hub-api-single-path-plan.md: move custody off the internal /admin/custody wire onto the public /api/v1/custody, so the CLI, tray and web all drive custody through one client surface. This removes the CLI's last routine /admin/* client use.

Converted: hub credentials push|pull, hub secrets push, hub project push (seed), hub custody list|pull|rm, the login-time + change-detected agent-credential sync, the hub worker seed fetch, and per-box SSH-key adoption (hub adopt/hub pull, auto-adopt, recover, cloud-agent-via-hub).

The two-tier, metadata-only contract (the load-bearing part)

Custody holds agent credentials, .env files and per-box SSH private keys — the highest-value target in the API — and the /api/v1 gate is the hub API key, which on a control box travels to the tray/web/thin clients. So:

• list / PUT / DELETE authorize with the hub API key and return metadata only (path, size, sha256, mode, mtime; changed on PUT) — never a stored value.
• byte-read GET /api/v1/custody/<path> is the one route that returns bytes, so it needs a second, non-distributed credential: on the password profile (a real/exposed control box) the admin token via X-Agentbox-Admin-Token. It fails closed — missing header, wrong token, or an unset admin-token env all refuse; there is no path that degrades to API-key-only. A caller with only the API key is 401. On a plain local hub (token profile) the byte-read is authorized by the machine-local hub token itself (single trusted machine).

The decision is the pure, unit-tested custodyByteReadAuthorized (apps/hub/lib/custody-auth.ts) so the invariant survives a route refactor — apps/hub/test/custody-auth.test.ts asserts an API-key-only caller cannot read bytes, and the client test asserts the same end.

Custody is now wired on every hub (not just a control box), so /api/v1/custody serves identically local and remote; the relay's /admin/custody wire stays admin-token-gated (a plain local hub serves custody only over its token-gated /api/v1). The project seed push became transport-agnostic (SeedCustodySink): the CLI injects a /api/v1 sink; the create path keeps its /admin sink (it holds the admin token — internal registration flow, Step 11 territory).

Verified end-to-end (ground truth, not exit codes)

• Local hub (token profile): credentials push → custody list (curl-confirmed no data field) → credentials pull + custody pull --dest round-tripped byte-for-byte; store landed at ~/.agentbox/hub/custody/.
• Password-profile hub (spawned standalone): byte-read with the API key alone → 401; with a wrong admin token → 401 (fail closed); with the admin token → 200 value; list/PUT metadata only; no-auth → 401.
• Remote-shaped CLI (--url + AGENTBOX_HUB_API_KEY + AGENTBOX_RELAY_ADMIN_TOKEN): push → list → pull (byte match) → rm; and a thin client (API key, no admin token) is refused on pull.
• pnpm typecheck (cli/hub/sandbox-cloud), unit tests, and eslint all green.

Notes

• Base branch is feat/cli_api_consolidation. Step 9 (PR feat(cli): route checkpoint/prune/agent/logs through the hub /api/v1 (thin CLI Step 9) #289) is in parallel; expected overlap is control-plane.ts.
• Public docs updated in-change: apps/web/content/docs/api.mdx + the OpenAPI spec document the new verbs and the two-tier contract; the plan doc is ticked with a Notes-for-later-steps block.

https://claude.ai/code/session_0173RGmXq6CGQgxuhcvgLRkh

---

Note

High Risk
Changes authentication and transport for agent credentials, env secrets, and per-box SSH private keys, with a new fail-closed byte-read gate that must not regress to API-key-only reads.

Overview
Step 10 routes routine custody work through /api/v1/custody instead of /admin/custody: CLI hub credentials|secrets|project|custody commands, background credential sync, worker seed fetch, and SSH-key adoption now resolve targets via resolveCustodyApiTarget and CustodyClient (with delete()). CustodyClient prefers the API key on /api/v1 and falls back to admin-only /admin when no key is present so SSH pulls do not silently skip.

The hub adds GET/PUT/DELETE /api/v1/custody/{path} plus custodyByteReadAuthorized: list/put/delete stay metadata-only on the hub API key; byte-read GET on a control box requires X-Agentbox-Admin-Token (fail-closed). Custody store is wired on every hub; pushProjectSeedToCustody takes an injected SeedCustodySink (CLI uses v1; create keeps adminCustodySink).

^{Reviewed by Cursor Bugbot for commit a738c31. Configure here.}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
agentbox-web	Ready	Preview	Jul 30, 2026 3:31am

[madarco]

Addressed the Bugbot finding (admin-only custody clients silently failing) in 2e35356.

The API key is genuinely required to reach /api/v1/custody at all — the proxy gate needs it on a control box, so returning null without it is correct. The bug was that it was silent. resolveCustodyApiTarget({remoteOnly}) now distinguishes the two cases: "no control box" → silent null (the expected no-op); "control box configured but no API key" → an actionable error naming AGENTBOX_HUB_API_KEY for interactive callers, while the best-effort quiet callers degrade downstream — createCloudBoxViaHubAndAdopt still adopts the record and adoptHubBox flags sshKeysMissing (with a 'try hub pull' hint), so an SSH provider's missing key is reported, never silently dropped. Comment at the create-via-hub call site updated to say so.

[madarco]

bugbot run

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit a738c31. Configure here.}