opencode: OpenCode 2 entry for the custody plugin, key substituted in place (parked reference, not for merge)

[iceteaSA]

Linked issue

Refs #75

Parked, not for merge. Per the maintainer on #75, vault custody for OpenCode belongs in the shared custody library the provider plugins use (the follow-up design is cortexkit/common-auth#5). This draft stays open as a reference for the OpenCode 2 seam. It now uses the shape the maintainer prefers: the key is substituted in place, with no listener.

What changes

The custody plugin gets an OpenCode 2 entry. The OpenCode 1 entry is untouched: its bundle builds byte-identical (sha256 42607b70…), and serve.ts changes only by export on three existing helpers.

OpenCode 2's native providers never go through the AI SDK fetch, so the V1 config hook has nothing to hook. The entry uses the session hooks instead:

• http.request: for a provider the handle manifest assigns to this plugin, the entry writes the vault key into the request's Authorization header, in place of the placeholder. OpenCode 2 then sends the request with its own client.
• experimental.ws.handshake (xai's responses route): the same, into the handshake's Authorization header.
• http.response: a 401 is reported to the vault with the record version that was actually served, and that account's cached key is dropped. A 429 or 402 puts the account on a cooldown. The response itself passes through untouched.

Why only Authorization. OpenCode 2 follows redirects itself, and a plugin can't stop it: 2.0.32 rebuilds the hook's request with HttpClientRequest.fromWeb, which drops the redirect mode. What keeps the key at the provider's origin is that the runtime's fetch strips Authorization on a cross-origin redirect, as the Fetch standard requires, and strips nothing else. Measured through the shipped opencode 2.0.32 binary (embedded Bun 1.4.2) with a plugin setting headers in http.request: on cross-origin 301, 302, 303, 307 and 308, Authorization never reached the target, while x-api-key and x-goog-api-key did. So the entry substitutes only into Authorization and refuses a placeholder anywhere else (URL, any other header) with CustodyPlacementError. The custody log row names the refused location in the sink's code grammar (x_api_key, url, or other_header), never a value. deepseek, minimax, xai and synthetic all send their key as Authorization: Bearer in OpenCode 2's drivers.

Startup check. Once per process, before the first substitution, the entry checks that the runtime still behaves this way. It starts two short-lived servers on 127.0.0.1, sends a probe Authorization through a cross-origin redirect for each of the five redirect statuses and through a WebSocket upgrade answered with a cross-origin 302, waits 150 ms after the WebSocket probe ends so a late follow is still caught, and stops both servers. If the probe header reaches the target, or the probe can't run within two seconds, every owned request is refused with CustodyRedirectUnsafeError and nothing is substituted. There's no switch to skip it. The check covers the runtime's fetch and WebSocket, not OpenCode's own transport, so each OpenCode version still needs the live run below.

Unchanged from the earlier rounds: a request for an owned provider without its placeholder is refused as a split, and a placeholder for a provider no handle covers is refused as an orphan. One process-wide registry handles reload overlap, so each request is substituted once, by the newest instance, and its response goes back to the instance that served it. bun run enroll -- --oc2 --provider <p> writes the placeholder through opencode auth import and opencode auth switch. It refuses providers whose built-in OpenCode 2 plugin calls out with the stored credential itself, and API-key placeholders for openai and xai (OpenCode 2's voice feature sends a stored key to the realtime API). OAuth placeholders carry expires 9999-12-31, so OpenCode 2 core never tries to refresh them. Install by adding the absolute path of dist/opencode2 to plugins: OpenCode 2 ignores a plugin path that is a file.

Known limits, also in docs/opencode-plugin.md:

• No in-turn retry: after a 401, 429 or 402, the failing request fails and the next request uses the next account.
• A rejected WebSocket handshake isn't reported to the vault, because the handshake hook sees no response.
• The substituted key lives in OpenCode 2's request object for that request, and later http.request and http.response hooks of other plugins can see it. A plugin in the same process is not a trust boundary, as with OpenCode 1.
• Another plugin calling ctx.generate.text on an owned model bypasses session hooks. That request reaches the provider with the placeholder and fails with its 401.
• An OAuth placeholder migrated from OpenCode 1 fails inside OpenCode 2 core before any hook runs. enroll --oc2 detects and replaces it.
• The package can't be installed in OpenCode 2 by package name: its ./server export is the serve library, and OpenCode 2 resolves <package>/server first.

How it was checked

• ./scripts/gate.sh at the head of this branch (e1834b2, on master 9276c73): passed, including the 9 real-daemon e2e arms and the workspace floor (1150, equal to master). Two arms can't run on this machine: the native key store (no dbus/gnome-keyring) and the Windows cross type-check (target not installed). The branch changes no Rust.
• Hermetic Bun suite: 318 pass, 0 fail. Every new guard has a mutation that turns its test red.
• Live run against the shipped opencode 2.0.32 binary (embedded Bun 1.4.2): isolated HOME and XDG dirs, provider stubs on 127.0.0.1, vault credentials holding fake material, outbound HTTPS blocked, plugin loaded from dist/opencode2. The full suite ran twice at ee0818b. The two placement arms and the startup check ran twice again at e1834b2. Every run agreed.
  • deepseek and synthetic: the stub received the vault material on every request and never the placeholder.
  • Cross-origin 307 from the stub: the redirect target was reached, with no Authorization header, no material and no placeholder. Same-origin 307 control: the second hop carried the material.
  • A real-looking key in place of the placeholder: refused as a split, 0 stub requests.
  • Control with the plugin removed: the stub saw the placeholder, so the zeros above are real zeros.
  • WebSocket redirects: 0 requests at the redirect target.
  • No listening socket beyond those OpenCode opens without the plugin.
  • xai over its WebSocket route: the upgrade carried the vault material in Authorization and no placeholder.
  • A placeholder in x-api-key, over HTTP and over the WebSocket handshake: refused, 0 stub requests, log row errorCode: x_api_key.
  • The startup check passed (no CustodyRedirectUnsafeError in the custody log).
  • An OAuth placeholder with far-future expiry reached the stub (no refresh). The OpenCode 1 shape (expires: 0) failed with an auth error and sent nothing.
  • A 401 on the first of two accounts: that request failed, the vault recorded the report against the served record version, and the next request used the second account.

[github-actions]

Waiting for design-approved on #75.

This PR needs a linked issue with the design-approved label before it can be reviewed or merged. Link the approved issue with Approved issue: #<issue> (or Refs #<issue>) in the description. A maintainer will apply the design-approved label on the issue, or trivial on the pull request when there is genuinely no design to agree. The issue stays open until the change ships; maintainers take care of it then.