Change Opensecret API

Change the OpenSecret API

Treat OpenSecret, released SDKs, and affected Maple paths as one versioned protocol. Preserve existing public behavior unless the task deliberately changes it.

Read the monorepo-root AGENTS.md and services/opensecret/AGENTS.md. Backend source paths below are relative to services/opensecret/; run backend commands there through its pinned Nix shell. Consumer paths in the coordination section are relative to the monorepo root.

Normative rules in this skill govern new or changed code; they do not certify untouched paths. Re-confirm current behavior from source and tests. If an unrelated path conflicts with a rule, keep that observation task-local and do not broaden the change without user approval.

Trace the live contract

Derive the route from current router assembly in src/main.rs and its module in src/web/; do not maintain a copied endpoint table. Trace one request through:

1. method, path, middleware order, and established auth context;
2. decryption and typed or extensible request validation;
3. authorization, storage, provider, and usage side effects;
4. status, headers, body or SSE projection, and error mapping;
5. focused tests, released SDK support, and pinned Maple consumers.

Use router assembly as the authority for outer authentication and the route module as the authority for inner session/decryption middleware. Use src/web/openai.rs for OpenAI-shaped inference routes and src/web/responses/ for Responses, conversations, tools, persistence, and events.

For Transport V2, also trace src/transport_v2/gateway.rs and src/transport_v2/session.rs from the mounted routes in src/main.rs. V1 and V2 transport coexist; establish which path the actual SDK invokes. Transport V2 and Router V2 are separate mechanisms, so a transport version does not establish the selected inference router.

Preserve transport and identity boundaries

• OpenAI-shaped describes the decrypted payload, not a plaintext wire API. Protected routes require the OpenSecret attestation/session protocol and a route-appropriate auth context.
• A session protects transport; it does not establish user identity, project membership, or storage-key ownership. Bodyless protected routes still validate and touch the session.
• JWT and API-key contexts are distinct. Preserve the auth method through authorization, persistence eligibility, quota, and usage attribution.
• Hold the session lease for the complete response body or stream. Successful protected responses and ordinary stream events remain encrypted according to the established client protocol.
• Validate provider-free input before writes. Pinned clients may recover from selected session or auth failures by retrying, so a side-effecting change needs explicit idempotency or proof that validation precedes the effect.

Inspect src/web/attestation_routes.rs, src/web/encryption_middleware.rs, session state in src/main.rs, src/web/openai_auth.rs, and src/jwt.rs when the change reaches those boundaries. Do not duplicate their policy inside a handler.

Derive errors from the response type actually returned by the route. Handlers returning ApiError use its mapping in src/main.rs; route-local error types may intentionally differ. For a new or intentionally revised contract, use stable HTTP semantics and sanitized public bodies. Once a changed stream has started, use its typed encrypted error event rather than introducing an unauthenticated plaintext data frame.