feat(auth): add contextual OAuth workspace grants

[saltbo]

What changed

• add RFC 9396 workspace authorization details and RFC 9126 pushed authorization requests to delegated OAuth
• bind OAuth grants and tokens to explicit workspaces while keeping authentication methods separate from scopes and roles
• add a standalone consent layout with workspace selection, complete localized permission disclosure, and grant management
• make every non-public first-party OpenAPI operation declare required scopes; keep Better Auth routes generated and preserve the real device-token wire contract
• expose a Realmroot-ready Restish OAuth profile and stable upload workflows
• recover interrupted x402 capacity purchases from verified and paid-pending states without replaying payment
• update to the published zpan-cloud-sdk@2.5.2

Why

Agents need standards-based, least-privilege access to a selected ZPan workspace and must be able to discover, authorize, pay for storage capacity, upload directly to S3, share, and download without source-code or database knowledge.

Validation

• pnpm lint
• pnpm typecheck
• pnpm test — 257 files / 5,359 tests
• pnpm test:cf — 18 files / 81 tests
• pnpm build
• pnpm openapi:client:check
• go test ./... in cmd/ — 254 tests
• local Realmroot → ZPan → x402 → Wallet sandbox → Cloud fulfillment → S3 upload → share → download golden path, including byte-for-byte SHA-256 verification

Preview verification will be added in a PR comment after the Workers preview is ready.

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	zpan	caf8415	Commit Preview URL Branch Preview URL	Aug 02 2026, 05:16 PM

[codecov]

Codecov Report

❌ Patch coverage is 99.57082% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 93.58%. Comparing base (1caa4e5) to head (caf8415).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
server/auth/oauth-provider.ts	98.33%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #550      +/-   ##
==========================================
+ Coverage   93.50%   93.58%   +0.08%     
==========================================
  Files         282      284       +2     
  Lines       15753    15907     +154     
  Branches     4530     4583      +53     
==========================================
+ Hits        14730    14887     +157     
+ Misses       1023     1020       -3     

Flag	Coverage Δ
integration	85.21% <87.82%> (+0.18%)	⬆️
unit	53.49% <79.65%> (+0.45%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[saltbo]

Preview verification

Verified the final feature on the shared Cloudflare preview: https://feat-oauth-workspace-grants-zpan.saltbo.workers.dev

• Golden path: authenticated files surface renders successfully.
• Golden path: RFC 9126 PAR resolves into the standalone RFC 9396 consent layout, with the exact workspace and requested scopes rendered.
• Edge path: a missing/expired OAuth request renders the dedicated recovery state.
• API contract: capacity purchase 200/202 responses are typed status objects, 402 is a typed x402 challenge, and payment transport headers are absent from business JSON.
• Applied generated migration 0090 to the shared staging D1 before the consent verification.

Authenticated files

Consent golden path

Consent edge path

[saltbo]

Final local clean-room acceptance

Strict PASS from a fresh agent with no inherited context, using only the Realmroot skill and public runtime contracts.

• Realmroot resource/grant discovery and deep OpenAPI retrieval passed.
• Exact available + 1 byte boundary returned actionable 402 with the minimum sufficient real 512 MiB tier.
• Wallet sandbox authorized exactly once on eip155:84532; same-requestHash recovery delivered without a second payment.
• 131,072,001-byte two-part direct upload, re-presign, completion, get/list, public share and download all passed. Download size and SHA-256 matched exactly.
• Fake workspace, shares:read, objects:delete on a nonexistent ID, and sandbox wallet:read all returned 403.
• No credentials, DPoP proofs, payment signatures, or payment transport headers were printed. Temporary local artifacts were deleted.

All 13 required GitHub checks now pass, including Node and Cloudflare Workers E2E, CodeQL, Codecov project/patch, Docker, Go, and Workers build.