@noodleseed/agent-kit 0.21.0 → 0.22.0

package/skills/codex/references/authoring-workflow.md

@@ -7,6 +7,7 @@
 - Repair loop
 - Connectors
 - HTTP connector example (full server)
+- Delegated downstream auth (call your API as the signed-in user)
 - Design tools for the model
 - Compute connector example
 - Tests
@@ -37,7 +38,7 @@ Declare connectors as data, not imperative code:
 
 Tools record connector calls into a flow; recording is not execution. Do not branch on runtime outputs with native `if` — use declarative `when(...)` conditions.
 
-HTTP connector auth variants: `bearer` (`{ kind: "bearer", secret: secret("API_TOKEN") }`), `apiKey` (`{ kind: "apiKey", header: "X-API-Key", secret: secret("API_KEY") }`), `clientCredentials`, `delegatedOAuth`, and `delegatedSessionCookie`. Use managed `secret(...)` / `variable(...)` refs for all values that differ by org/app/env.
+HTTP connector auth variants: `bearer` (`{ kind: "bearer", secret: secret("API_TOKEN") }`), `apiKey` (`{ kind: "apiKey", header: "X-API-Key", secret: secret("API_KEY") }`), `clientCredentials`, `delegatedOAuth`, `delegatedSessionCookie`, and `delegatedTokenExchange` (per-user calls to your own API — see "Delegated downstream auth" below). Use managed `secret(...)` / `variable(...)` refs for all values that differ by org/app/env.
 
 ## HTTP connector example (full server)
 
@@ -96,7 +97,76 @@ export default server('support', { title: 'Support', version: '1.0.0', use: { cr
 
 Naming: connector operation names and tool names are lowercase-with-underscores. Map with `${args.field}` for tool/operation inputs and `${response.path}` for the response — the parsed JSON body is bound directly to `${response}`, so there is **no `.body` envelope**; use bracket syntax for array indices (`${response.data[0].id}`) — a dotted numeric index like `.0.` is invalid. Declare URL query parameters with the operation-level `query: ["arg"]` array, **not** inside `request` (which builds only the JSON body). `allowedOrigins` must be literal origin URLs (the SSRF allowlist); `baseUrl` may be a `variable(...)` that differs by env.
 
-More: `auth.kind` is `bearer` | `apiKey` (needs `header`) | `clientCredentials` | `delegatedOAuth` | `delegatedSessionCookie`. For client credentials use `{ kind: "clientCredentials", tokenUrl, clientId, clientSecret, scopes? }` (RFC-6749 grant); for a non-standard partner token endpoint add `profile: "custom"` with a `custom: { requestFormat, clientIdField, clientSecretField, tokenResponsePath, expirySource }` descriptor. Do not put credential headers in operation `headers`; use connector `auth`. For per-customer downstream calls use `delegatedOAuth` or `delegatedSessionCookie` with a matching `customerAuth` server option. Use `.compute(name, { input, output, run })` for a sandboxed transform; `provides:` (instead of `use:`) exposes a connector only to compute `callOperation`; and `noodle import openapi <file>` generates a connector from an OpenAPI spec.
+More: `auth.kind` is `bearer` | `apiKey` (needs `header`) | `clientCredentials` | `delegatedOAuth` | `delegatedSessionCookie` | `delegatedTokenExchange`. For client credentials use `{ kind: "clientCredentials", tokenUrl, clientId, clientSecret, scopes? }` (RFC-6749 grant); for a non-standard partner token endpoint add `profile: "custom"` with a `custom: { requestFormat, clientIdField, clientSecretField, tokenResponsePath, expirySource }` descriptor. Do not put credential headers in operation `headers`; use connector `auth`. Use `.compute(name, { input, output, run })` for a sandboxed transform; `provides:` (instead of `use:`) exposes a connector only to compute `callOperation`; and `noodle import openapi <file>` generates a connector from an OpenAPI spec.
+
+## Delegated downstream auth (call your API as the signed-in user)
+
+Use delegated connector auth when the downstream API must enforce its own per-user authorization — a shared service credential plus a forwarded user id would bypass it. Three shapes exist; pick by who owns the downstream:
+
+- **`delegatedTokenExchange`** — your own API. The platform signs a short-lived, verifiable assertion of the signed-in user and exchanges it at a token endpoint you implement (RFC 8693). Works with `customerAuth.bridge(...)` identities and embedded-assistant sessions; no per-user OAuth enrollment.
+- **`delegatedOAuth` with `provider: "firebase" | "microsoft"`** — Noodle-managed bridge providers using stored per-user refresh tokens. Requires the matching `customerAuth` bridge; any other provider string is the compile error `unsupported_delegated_provider`.
+- **`delegatedSessionCookie`** — Firebase-managed session-cookie apps only; not a generic mechanism.
+
+### The connector (your `server.ts`)
+
+```ts
+auth: {
+  kind: 'delegatedTokenExchange',
+  tokenUrl: 'https://app.example.com/api/assistant/oauth/token', // origin must be in allowedOrigins
+  clientId: variable('EXAMPLE_DELEG_CLIENT_ID'),
+  clientSecret: secret('EXAMPLE_DELEG_CLIENT_SECRET'),
+  scopes: ['time_off'],           // optional
+  audience: 'example-api',        // optional; assertion + request audience, defaults to tokenUrl
+  authMethod: 'client_secret_basic', // default; client_secret_post supported
+}
+```
+
+Inside tools, `${user.id}` / `${user.email}` / `${user.name}` / `${user.claims.*}` stay available as verified context; the delegated credential is what makes the *downstream call itself* run as that user.
+
+### The exchange request your endpoint receives
+
+The broker POSTs `application/x-www-form-urlencoded` to `tokenUrl` with `Authorization: Basic base64(clientId:clientSecret)` (or `client_id`/`client_secret` form fields for `client_secret_post`):
+
+```
+grant_type=urn:ietf:params:oauth:grant-type:token-exchange
+subject_token=<RS256 JWT signed by the platform>
+subject_token_type=urn:ietf:params:oauth:token-type:jwt
+scope=time_off            (space-joined, when configured)
+audience=example-api      (when configured)
+```
+
+The `subject_token` claims: `iss` (platform issuer; JWKS at `{iss}/.well-known/jwks.json`), `sub` (verified user id), `aud` (your configured audience or the tokenUrl), `email`, `name`, `claims` (declared session claims), `tenant` (`org/app/env`), `deployment`, `iat`, `exp` (about 120 s), `jti`. Respond with `{ "access_token": "...", "token_type": "Bearer", "expires_in": 900 }`; the broker caches per user + connector + scopes until `expires_in` minus 300 s and presents the token downstream as `Authorization: Bearer`.
+
+### The downstream token endpoint (your backend)
+
+```ts
+// POST /api/assistant/oauth/token — Node example with jose.
+import { createRemoteJWKSet, jwtVerify } from 'jose';
+
+const PLATFORM_ISSUER = process.env.NOODLE_PLATFORM_ISSUER!; // e.g. https://cloud.noodleseed.dev
+const jwks = createRemoteJWKSet(new URL(`${PLATFORM_ISSUER}/.well-known/jwks.json`));
+
+export async function tokenEndpoint(req: Request): Promise<Response> {
+  // 1. Authenticate the broker client credential (client_secret_basic).
+  const basic = req.headers.get('authorization') ?? '';
+  const [clientId, clientSecret] = atob(basic.replace(/^Basic /, '')).split(':');
+  if (!isValidClient(clientId, clientSecret)) return new Response(null, { status: 401 });
+  // 2. Verify the platform-signed user assertion (never trust a plaintext user id).
+  const form = new URLSearchParams(await req.text());
+  const { payload } = await jwtVerify(form.get('subject_token') ?? '', jwks, {
+    issuer: PLATFORM_ISSUER,
+    audience: 'https://app.example.com/api/assistant/oauth/token', // your tokenUrl or configured audience
+  });
+  if (payload.deployment !== undefined && payload.tenant !== 'your-org/your-app/prod') {
+    return new Response(null, { status: 403 }); // optionally pin the calling deployment
+  }
+  // 3. Mint your own short-lived user-scoped token; your API enforces per-user rules from it.
+  const accessToken = await issueAccessToken(String(payload.sub), clientId, form.get('scope') ?? '');
+  return Response.json({ access_token: accessToken, token_type: "Bearer", expires_in: 900 });
+}
+```
+
+Diagnose with `noodle auth doctor` (reports each delegated token exchange endpoint and whether managed delegated providers pair with the declared `customerAuth`). Common failures: `disallowed_token_origin` (add the tokenUrl origin to `allowedOrigins`), `unsupported_delegated_provider` (custom provider strings never reach a broker; use `delegatedTokenExchange`), and `delegated token exchange requires a verified customer caller` at runtime (the surface calling the tool has no verified customer identity — check `customerAuth` and, for embeds, `createAssistantSession({ user })`).
 
 ## Design tools for the model
 

package/skills/codex/references/embedded-assistant.md

@@ -8,6 +8,7 @@
 - Access modes and customer auth
 - Create the backend client
 - Integrate the customer backend
+- Verified session context (identity and claims)
 - The session response
 - Mount the browser component
 - Toolchain requirements
@@ -113,6 +114,50 @@ Authenticate before exchange. Source `origin` from trusted server configuration
 
 `serviceUrl` is the Noodle Seed control-plane base URL: the value `noodle assistant clients create` prints, also stored as `serviceUrl` in `deployment.json`. It is NOT the deployment MCP endpoint (`url`, which ends in `/v1/mcp` and rejects session exchange). Never probe or guess endpoints with real credentials.
 
+## Verified session context (identity and claims)
+
+The embedding developer defines what authenticated session context the assistant receives. One mechanism, three hops:
+
+1. The authenticated backend passes standard identity and any verified claims at session exchange (flat scalars only):
+
+```ts
+const session = await createAssistantSession({
+  serviceUrl, clientId, clientSecret, origin,
+  user: { id: user.id, email: user.email, name: user.name },
+  claims: { displayName: user.name, accountTier: account.tier, region: account.region },
+});
+```
+
+2. The server author declares the allowlist in `server.ts` — undeclared claims are dropped at session exchange (never rejected, so backend and server deploys may skew safely):
+
+```ts
+assistant: embeddedAssistant({
+  model, allowedOrigins,
+  sessionClaims: {
+    displayName: { exposeToModel: true },
+    accountTier: { exposeToModel: true },
+    region: {}, // tools only, never in the prompt
+  },
+}),
+```
+
+3. Consumption. Tools read the verified identity and declared claims through the `user` scope:
+
+```ts
+tool("greet", {
+  description: "Greet the signed-in user.",
+  input: z.object({}),
+  annotations: annotations.readOnly(),
+  fulfil: ({ user }) => ({ message: `Hello, ${user.name}!`, tier: user.claims.accountTier }),
+});
+```
+
+Manifest expressions use `${user.name}`, `${user.email}`, `${user.subject}`, `${user.claims.<key>}`. The model receives one platform identity line automatically: standard identity (name/email) whenever present, plus only the claims marked `exposeToModel: true` — so the assistant greets the actual user and can pass identity into tool arguments. `noodle check --target embedded-assistant` lists the declared claim contract.
+
+Page `context` from the widget remains untrusted hint data; verified facts belong in `claims`, never in `context`.
+
+To make the *downstream API call itself* run as the signed-in user (your API enforces its own per-user authorization instead of trusting a forwarded id), give the connector `auth.kind: "delegatedTokenExchange"` — the platform signs a verifiable assertion of this session identity and exchanges it at a token endpoint you implement. Assistant sessions carry the identity this needs; the full contract and a copyable endpoint implementation are in `references/authoring-workflow.md` ("Delegated downstream auth").
+
 ## The session response
 
 The exchange returns the versioned Embedded Assistant v1 contract. `token`, `expiresAt`, and `endpoints.turns` / `endpoints.toolConfirmations` (absolute URLs) are always present; `configuration` is optional theming data. Forward the body unchanged; the widget posts turns to `endpoints.turns` itself. Do not rebuild, filter, or rewrite the response.
@@ -142,7 +187,7 @@ The component renders a custom element and must mount client-side. In a Next.js
 - Signed-out session exchange returns `401`.
 - The browser network/DOM/storage contains no client secret or model key.
 - The local and production origins match `allowedOrigins` character-for-character.
-- Read-only closed-world tools may auto-run; writes require confirmation.
+- Auto-run requires the full safe-read annotation (`annotations.readOnly()`: read-only, non-destructive, closed-world); unannotated or partially annotated tools always confirm. Writes require confirmation by design.
 - An expired turn re-exchanges once; confirmations never replay.
 - Wrong-origin and malformed-origin requests fail closed.
 
@@ -157,4 +202,11 @@ The component renders a custom element and must mount client-side. In a Next.js
 | Validate rejects an origin | Non-loopback HTTP origin in `allowedOrigins` | Use the exact HTTPS production origin; HTTP is only for `localhost`/`127.0.0.1` |
 | Session exchange returns 404 | `serviceUrl` points at the deployment MCP endpoint | Use the control-plane service URL printed by `noodle assistant clients create` |
 | Session exchange returns 403 `origin is not allowed` | Request origin differs from `allowedOrigins` character-for-character | Align the exact scheme/host/port on both sides and redeploy |
-| Hydration or `HTMLElement is not defined` errors | The component mounted during server rendering | Mount client-only (`"use client"` or `next/dynamic` with `ssr: false`) |
+| Hydration or `HTMLElement is not defined` errors | The component mounted during server rendering | Mount client-only (`"use client"` or `next/dynamic` with `ssr: false`) |
+| A read-only tool still asks for confirmation | Its annotations fail the safe-read rule: auto-run requires `readOnlyHint: true`, `destructiveHint: false`, AND `openWorldHint: false` (use `annotations.readOnly()`; `readOnly({ openWorld: true })` confirm-gates) | Fix the annotations; `noodle check --target embedded-assistant` lists every confirm-gated tool |
+| `${user.claims.<key>}` is empty | Claim not declared in `sessionClaims` (or key typo) — undeclared claims are dropped at exchange | Declare the key in `embeddedAssistant({ sessionClaims })` and redeploy |
+| `${user.name}` is empty | Backend did not pass `user.name` to `createAssistantSession` | Pass the verified name from the authenticated backend session |
+| The model does not know a claim you passed | Claim is tools-only | Mark it `exposeToModel: true` in `sessionClaims` |
+| Behavior does not change after `noodle deploy` | Outdated platform: before the 2026-07 fix, clients were pinned to their creation-time deployment | Update the platform; sessions now follow the tenant's active deployment |
+| A delegated connector tool fails with `delegated token exchange requires a verified customer caller` | The calling surface has no verified customer identity (or an old session minted before the platform carried the resource audience) | Verify `customerAuth` is configured and the backend passes the verified `user` to `createAssistantSession`; re-mint the session |
+| Deploy fails with `unsupported_delegated_provider` | `delegatedOAuth.provider` only supports the managed `firebase`/`microsoft` bridges | Use `auth.kind: "delegatedTokenExchange"` for your own token endpoint (see authoring-workflow.md) |

package/skills/codex/references/examples.md

@@ -14,12 +14,12 @@ Paths are relative to this skill directory. Assets (images/fonts) are omitted fr
 | `acme-discovery` | Top-of-funnel discovery→handoff: a discovery carousel, a `create_handoff` deep link, and a design-first UX spec + wireframe. | `examples/acme-discovery/src/server.ts` + `design/` |
 | `acme-tasks` | A two-way productivity app designed around its top-3 prioritized flows (capture/prioritize/complete), with a design-first flow spec + wireframe. | `examples/acme-tasks/src/server.ts` + `design/` |
 | `acme-bistro` | End-to-end ordering with a payment-only handoff; ships a gold-standard `design/` set (UX doc, wireframe with compliance audit, API contract). | `examples/acme-bistro/src/server.ts` + `design/` |
+| `customer-auth` | End-user (customer) auth via OIDC/Firebase bridge with delegated credentials. | `examples/customer-auth/src/server.ts` |
 
 ## In the repository only — `examples/<name>/` on GitHub
 
 | Example | Use when |
 | :-- | :-- |
-| `customer-auth` | End-user (customer) auth via OIDC/Firebase bridge with delegated credentials. |
 | `stateful-draft` | Durable, caller-scoped widget state handles with optimistic revisions. |
 | `perplexity` | A real SaaS API with bearer auth and a managed `secret`. |
 | `bitcoin` | API-key HTTP connector, custom auth header, and compute normalization. |