zpan/docs/roadmap/v2.9.md

v2.9 — External OAuth Apps

Goal

Make ZPan a self-describing OAuth resource that generic Agent controllers can discover and operate without a ZPan-specific skill, Restish profile, or upload plugin.

Product Boundary

ZPan owns:

• OAuth protected-resource and authorization-server metadata;
• dynamic OAuth client registration;
• administrator visibility of registered applications;
• user consent and workspace-bound grants;
• JWT bearer actor authentication and OAuth token exchange;
• DPoP-bound resource tokens and revocation;
• scope-aware file APIs, Arazzo workflows, and structured direct-upload instructions.

The external controller owns Agent identity, approval of application access, delegated credential injection, and tool orchestration. ZPan does not ship a fixed OAuth client.

Deliverables

Discovery and Dynamic Registration

• Publish the exact /api resource audience.
• Link /api/openapi.json from the resource response.
• Publish protected-resource and authorization-server metadata.
• Advertise and accept dynamic client registration with PKCE.
• Show dynamically registered applications and their metadata to administrators.
• Do not require application approval in the first release.

Consent and Grants

• Resolve the dynamic client name and callback at consent time.
• Bind every consent to one user, client, workspace, and explicit scope set.
• Let the user switch among accessible workspaces before approval.
• List grants with their actual registered application names.
• Revoke the selected consent plus its access and refresh token family.

External Resource Tokens

• Accept JWT bearer assertions from registered clients with JWKS.
• Mint short-lived actor tokens.
• Exchange a user subject token and actor token for the exact ZPan API audience.
• Require DPoP proofs for token exchange and resource requests.
• Include workspace and delegated actor claims in resource JWTs.
• Support JTI-based access-token revocation.

Unified OpenAPI

• Keep one OpenAPI document for browser, API, and Agent consumers.
• Publish stable operation IDs and x-zpan-auth resource-scope requirements.
• Keep administrative routes protected by their normal security declarations.
• Do not publish Restish profiles, client IDs, secrets, environment-variable bindings, or executable credential helpers.
• Publish a public OAuth resource-scope catalog with standard OAuth security declarations while keeping Agent operations bound only by x-zpan-auth, so no built-in client or credential profile is selected.

Discoverable API Workflows

• Publish an Arazzo 1.1 JSON document for prepare, re-presign, complete, and abort upload workflows.
• Advertise it from the resource URL with a typed describedby Link and from OpenAPI through externalDocs.
• Reference stable OpenAPI operation IDs so a controller can resolve required scopes and invoke protected steps through its normal OpenAPI client.
• Keep the response-provided upload descriptor authoritative for presigned storage PUTs because their absolute URLs are generated at runtime.

Self-Describing Direct Upload

createObject returns everything a generic Agent needs:

• upload and object identifiers;
• part number, byte offset, byte length, HTTP method, presigned URL, and required headers for every part;
• explicit instructions to retain each response ETag;
• complete, re-presign, and abort operation IDs, methods, and paths.

The Agent uploads bytes directly to S3-compatible storage, then completes the draft with part numbers and ETags. Re-presigning and completion reauthorize against ZPan. Presigned URLs and file bytes never need to transit the external controller.

Authorization

The grantable resource scopes cover object read/create/update/delete, share read/create/delete, quota read, storage-usage read, and task read. Purge, administration, billing, credential management, WebDAV configuration, and downloader registration remain excluded.

OAuth resolves to the same protocol-neutral principal and route policies used by the rest of ZPan. Business use cases do not branch on a particular Agent controller or client ID.

Removed Compatibility Surfaces

• fixed, system-managed OAuth client;
• OpenAPI x-cli-config profiles;
• restish-zpan command plugin and release artifact;
• repository-hosted ZPan Agent skill.

The existing zpan-cli device authorization remains only for its legacy, single-use downloader-registration bootstrap.

Delivery Order

1. Resource and authorization-server discovery.
2. Dynamic client registration and administrator visibility.
3. Workspace consent, grants, and revocation.
4. JWT bearer, token exchange, DPoP, and JWT revocation.
5. Tool-neutral OpenAPI authorization metadata.
6. Discoverable Arazzo upload workflows.
7. Self-describing single/multipart upload responses.
8. Remove fixed-client, profile, plugin, and skill surfaces.
9. Complete local gates and real FlareAuth acceptance.

Acceptance Criteria

• A controller starting only from the ZPan /api URL discovers OpenAPI, Arazzo, and OAuth metadata.
• Dynamic registration creates a client visible in administrator settings.
• The user sees an authorization request with the real application name, callback, workspace, scopes, and lifetime.
• After approval, the controller obtains a DPoP resource token for /api.
• A generic Agent creates an upload, sends all returned byte ranges, captures ETags, and completes it without ZPan-specific code.
• The same connection lists, reads, and renames the uploaded file.
• Grant or JWT revocation stops subsequent resource access.
• Lint, type checking, Node tests, Cloudflare tests, and applicable end-to-end checks pass.

Deferred

• administrator approval or rejection of newly registered applications;
• workload identity for unattended CI;
• standard Agent device authorization;
• richer per-client policy and registration lifecycle management.