feat(seal): add a fetch option for key server requests

[nikos-terzo]

Description

Adds an optional fetch to SealClientOptions, used for all key server requests (/v1/fetch_key and /v1/service verification). Mirrors the fetch option of SuiHTTPTransport. Defaults to the global fetch; no behavior change otherwise.

Use case: the seal-mpc aggregator authenticates apps with an API key, which is a secret — it can't be shipped to the browser — so apps route fetch_key through their own backend, which attaches the key server-side (MystenLabs/console#428). SealClient still has to run in the browser: it's what guarantees that only the user can decrypt their data. If the backend ran it instead, the backend would see the decryption keys and could read user data.

That leaves authenticating the browser→backend leg, which is typically the app's session cookie. On a same-origin backend that just works — but when the API lives on a different origin than the app (the usual setup), cookies are only sent if the request opts in with credentials: 'include', and the SDK's fetch doesn't and can't. The cookie also can't be copied into the apiKeyName/apiKey header slot because it's HttpOnly. apiKey is also fixed at construction, so rotating credentials force rebuilding the whole client. MystenLabs/console#379 shows the workaround this forces today: a dedicated short-lived token endpoint, a custom header, and client rebuilds on every rotation.

With this option, such apps pass fetch: (url, init) => fetch(url, { ...init, credentials: 'include' }) and their existing session just rides along. This is likely a common shape for any cookie-authenticated app fronting a keyed seal-mpc aggregator.

Test plan

Client-level unit tests: SealClient built with a custom fetch must route both verifyKeyServer (/v1/service) and fetchKeysForAllIds (/v1/fetch_key) through it, never through the (stubbed) global fetch. pnpm --filter @mysten/seal vitest run test/unit/key-server.test.ts — 10/10 passing.

Also red/green-tested this in Walrus Console (MystenLabs/console#459) by patching globalThis.fetch around each decrypt equivalent to this option, since the SDK reads the global at request time.

• Green: patched fetch adds credentials: 'include' → session cookie reaches our fetch_key proxy → decrypt works.
• Red: patch removed → default same-origin credentials drop the cookie cross-origin → 401.

---

AI Assistance Notice

Please disclose the usage of AI. This is primarily to help inform reviewers of how careful they need to review PRs, and to keep track of AI usage across our team. Please fill this out accurately, and do not modify the content or heading for this section!

• This PR was primarily written by AI.
• I used AI for docs / tests, but manually wrote the source code.
• I used AI to understand the problem space / repository.
• I did not use AI for this PR.

🤖 Generated with Claude Code

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
sui-typescript-docs	Ready	Preview	Aug 10, 2026 8:59pm

[nikos-terzo]

To the reviewers, regarding the AI Assistance Notice, even though I used AI to understand the solution and write the code, I reviewed the code line by line and it is how I would have written it.

[jessiemongeon1]

Style Guide Audit

Audited 1 file(s) against the Sui Documentation Style Guide.

1 violation(s) found. All must be fixed before merge.

packages/docs/content/seal/index.mdx (1 violation(s))

1 violation(s) (1 regex, 0 claude)

• Line 66 — No Latin abbreviations
  • Current: e.g.
  • Fix: for example

---

Automated audit using the Sui Documentation Style Guide.

[jessiemongeon1]

Style Guide Audit

Audited 1 file(s) against the Sui Documentation Style Guide.

1 violation(s) found. All must be fixed before merge.

packages/docs/content/seal/index.mdx (1 violation(s))

1 violation(s) (1 regex, 0 claude)

• Line 66 — No Latin abbreviations
  • Current: e.g.
  • Fix: for example

---

Automated audit using the Sui Documentation Style Guide.