mirror of
https://github.com/storytold/artcraft.git
synced 2026-11-17 07:04:36 +00:00
mcp: document the auth modules and verified provider facts
Claude-Session: https://claude.ai/code/session_01H3gfN2NCx3hBXSrZXYHUQ3
This commit is contained in:
1 parent
03bf1bd795
commit
93a99c0e42
1 file changed
+29
-5
+29
-5
@@ -212,6 +212,25 @@ Cite these; re-verify if the file references stop matching.
|
||||
- Job tokens are `jinf_…`; batch status accepts mixed prefixes (`jinf_`, `batch_g_`).
|
||||
- Error bodies: `{ success: false, error_code, error_code_str, message? }`.
|
||||
|
||||
## OAuth provider facts (verified against @cloudflare/workers-oauth-provider 0.10.3)
|
||||
|
||||
- `resource` and `authorization_servers` are derived from the request origin when
|
||||
`resourceMetadata.resource` is omitted — that is why one build serves every environment and
|
||||
why production has `workers_dev = false` (exactly one public origin).
|
||||
- CIMD needs `clientIdMetadataDocumentEnabled: true` AND `global_fetch_strictly_public` in
|
||||
`compatibility_flags`; the metadata flag is advertised only when both are present.
|
||||
- The 401 challenge the library emits: `Bearer realm="OAuth",
|
||||
resource_metadata="<origin>/.well-known/oauth-protected-resource/mcp", scope="…"`.
|
||||
- Refresh tokens rotate; the previous one stays valid until its replacement is first used.
|
||||
- Grant props are AES-GCM encrypted with token-wrapped keys; `userId` and `metadata` are not.
|
||||
- `tokenExchangeCallback` runs on code exchange and refresh and may throw `OAuthError`;
|
||||
it receives props but not the grant's creation time — hence `grantIssuedAt` in props.
|
||||
- `getOAuthApi(options, env)` gives the helpers outside a fetch handler (tests use it).
|
||||
- `CimdFetchError` from `parseAuthRequest` means the client's document could not be fetched
|
||||
or validated: render locally (we answer 502), never redirect.
|
||||
- This pool-workers release exports no `fetchMock`; stub `globalThis.fetch` in tests (tests and
|
||||
the Worker share an isolate).
|
||||
|
||||
## Client requirements that bite
|
||||
|
||||
- Unauthenticated `/mcp` → **401** with
|
||||
@@ -334,9 +353,14 @@ mcp/
|
||||
├── fake-upstream/ # separate Worker faking the allowlisted API routes; never imported by src/
|
||||
├── scripts/gen-api.mjs # fetch api.json → trim to allowlist → test/fixtures/api.json + src/upstream/schema.d.ts
|
||||
├── src/
|
||||
│ ├── index.ts # Worker entry: OAuthProvider wrapping the Hono app
|
||||
│ ├── app.ts # Hono routes
|
||||
│ ├── auth/ # provider config, Authenticator impls, consent page (Hono JSX)
|
||||
│ ├── index.ts # Worker entry: environment invariant first, then the OAuthProvider
|
||||
│ ├── runtime.ts # memoized Config + Hono app per isolate (failure memoized too)
|
||||
│ ├── oauth-env.d.ts # adds env.OAUTH_PROVIDER (OAuthHelpers) to the generated Env
|
||||
│ ├── app.ts # unprotected Hono routes: /healthz, /authorize, pages
|
||||
│ ├── auth/
|
||||
│ │ ├── oauth.ts # provider options: endpoints, scopes, TTLs, CIMD+DCR, error logging
|
||||
│ │ ├── authorize.ts # /authorize: parseAuthRequest → (Authenticator, next PR) → completeAuthorization
|
||||
│ │ └── grant-age.ts # 90-day absolute grant lifetime, enforced in tokenExchangeCallback
|
||||
│ ├── tokens/ # TokenResolver, Principal, GrantStore adapter
|
||||
│ ├── upstream/
|
||||
│ │ ├── allowlist.json # the ONLY upstream routes, with `use: auth | read`; also drives the generator
|
||||
@@ -344,10 +368,10 @@ mcp/
|
||||
│ │ ├── credential.ts # UpstreamCredential interface; session implementation (swap point 2)
|
||||
│ │ ├── client.ts # openapi-fetch client; middleware enforces allowlist, use, origin, credential
|
||||
│ │ └── schema.d.ts # GENERATED from the spec snapshot by `pnpm gen:api`; do not edit
|
||||
│ ├── mcp/ # McpServer factory, tools/, resources, prompts
|
||||
│ ├── mcp/ # handler.ts (protected route; 501 stub until the transport lands), tools/
|
||||
│ └── pages/ # landing, connections
|
||||
└── test/
|
||||
├── fixtures/api.json # GENERATED spec snapshot (trimmed); the contract tests' reference
|
||||
├── helpers/ # pure check functions so guardrail tests can prove they fire
|
||||
├── helpers/ # pure check functions for guardrail tests; oauth-client.ts = an MCP client's moves
|
||||
└── upstream/, oauth/, e2e/, *.test.ts
|
||||
```
|
||||
Reference in new issue
Block a user