@noodleseed/agent-kit 0.21.0 → 0.22.0

package/skills/claude-code/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/claude-code/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/claude-code/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. |

package/skills/codex/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: noodle-seed
 description: Use when building, validating, testing, deploying, or operating a local or hosted Noodle Seed MCP server or app authored in TypeScript with the noodle CLI.
-version: 0.21.0
+version: 0.22.0
 hash: cd25535e1d6dbf4f
 ---
 

package/skills/codex/examples/customer-auth/README.md

@@ -0,0 +1,237 @@
+# Customer Auth - NoodleSeed.com Firebase customer identity
+
+This curated example owns the customer/end-user authentication with Firebase bridge capability slot. It is
+the NoodleSeed.com dogfood app for proving that a SaaS app can protect an MCP endpoint with its own customer
+identity provider while still using the generic Noodle Seed authoring API.
+
+It also owns the embedded-assistant showcase: the same authenticated MCP surface can be dropped into the
+SaaS web application as a fully customer-branded assistant with independent light and dark themes. The
+assistant loads the active deployment's instructions and model-visible tools rather than installing a stale
+second skill bundle. Interactive MCP Apps widgets continue to render in supported external hosts; the
+initial embedded surface renders text and native tool confirmations.
+
+The public developer entrypoint is [`src/server.ts`](src/server.ts). It declares `customerAuth.firebase(...)` with
+the NoodleSeed.com Firebase project and Firebase Web App public config. It exposes a deliberately small MCP
+surface for org discovery:
+
+- `list_my_organizations` lists the NoodleSeed.com organizations the signed-in customer belongs to (no
+  arguments — the org set comes from the verified customer session).
+- `list_org_apps` lists apps for one of those organizations through the dev app API.
+
+The two tools chain: `list_my_organizations` surfaces the `org_id`s the customer can act on, and
+`list_org_apps` takes one of those `org_id`s. There is no NoodleSeed-specific SDK helper. The downstream API
+is an ordinary authored HTTP connector.
+
+During MCP OAuth login, Noodle Cloud hosts the Firebase bridge page at
+`https://cloud.noodleseed.dev/oauth/customer/firebase/authorize`. The customer app does not add an
+authorization route. The SaaS operator only configures Firebase Auth to allow the Noodle Cloud origin, and
+Noodle Cloud signs the customer in with Firebase before posting the Firebase ID token back to its own bridge
+callback.
+
+## How delegated customer credentials are used
+
+The example has two declarations that work together:
+
+```ts
+auth: customerAuth.firebase({
+  projectId: variable('FIREBASE_PROJECT_ID'),
+  apiKey: variable('FIREBASE_WEB_API_KEY'),
+  authDomain: variable('FIREBASE_AUTH_DOMAIN'),
+  user: {
+    id: 'sub',
+    email: 'email',
+    name: 'name',
+    tenant: 'firebase.tenant',
+    orgs: 'claims.orgs',
+    roles: 'claims.roles',
+  },
+}),
+```
+
+That protects the MCP endpoint with the SaaS customer's Firebase identity. The connector then opts into
+delegated customer credentials:
+
+```ts
+auth: {
+  kind: 'delegatedSessionCookie',
+  provider: 'firebase',
+  sessionUrl: `${noodleseedApiOrigin}/api/auth/session`,
+  tokenField: 'idToken',
+},
+```
+
+Tool code calls the connector normally:
+
+```ts
+fulfil({ input, connectors }) {
+  const apps = connectors.app_api.listOrgApps({
+    org_id: input.org_id,
+    skip: input.skip,
+    limit: input.limit,
+  });
+
+  return { result: apps.result };
+}
+```
+
+At runtime, Noodle Seed verifies the Firebase customer during MCP OAuth, stores that customer's delegated
+Firebase refresh token in the credential broker, and refreshes a short-lived Firebase ID token only when a
+connector-backed tool calls the NoodleSeed.com API. For this app API, the broker exchanges that ID token at
+the existing Next.js `/api/auth/session` route and sends the resulting session cookie to the API. The MCP
+access token remains a Noodle-issued resource-bound token and is never sent to the downstream API.
+
+## Delegated downstream auth for your own API (token exchange)
+
+The Firebase path above only works for Firebase-session downstreams. When the downstream is **your own
+API** with its own token issuance, use `delegatedTokenExchange` instead
+([ADR 0152](../../docs/decisions/0152-delegated-token-exchange-connector-auth.md)): the platform signs a
+short-lived, JWKS-verifiable assertion of the signed-in user and exchanges it (RFC 8693) at a token
+endpoint you implement, which mints your own user-scoped token — so your API enforces its own per-user
+authorization on every call. It works for identities from `customerAuth.bridge(...)` and from embedded
+assistant sessions, with no per-user OAuth enrollment.
+
+```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'],
+},
+```
+
+Your endpoint authenticates the broker's client credential, verifies the `subject_token` JWT against the
+platform issuer JWKS (claims include the verified `sub`, `email`, `name`, declared session `claims`,
+`tenant`, and `deployment`), mints a short-lived user-scoped token, and returns the standard
+`{ access_token, token_type, expires_in }` response. The exact wire contract and a copyable endpoint
+implementation live in [docs/spec/connectors.md](../../docs/spec/connectors.md) and the Agent Kit
+authoring-workflow reference ("Delegated downstream auth"). `noodle auth doctor` reports each declared
+exchange endpoint.
+
+## Validate
+
+```bash
+noodle auth doctor examples/customer-auth/src/server.ts
+noodle validate examples/customer-auth/src/server.ts
+```
+
+## Run locally
+
+```bash
+noodle dev examples/customer-auth/src/server.ts --app noodleseed-customer-auth
+```
+
+## Configuration
+
+The embedded assistant uses a customer-supplied OpenAI Chat Completions-compatible endpoint. Configure its
+managed values at the Noodle deployment environment; none of these values belongs in the customer web
+application environment, and the API key never reaches the browser:
+
+```bash
+noodle variables set ASSISTANT_MODEL_BASE_URL https://model.example.com/v1 --scope env
+noodle variables set ASSISTANT_MODEL your-model --scope env
+noodle secrets set ASSISTANT_MODEL_API_KEY --scope env
+noodle variables set FIREBASE_PROJECT_ID your-firebase-project --scope env
+noodle variables set FIREBASE_WEB_API_KEY your-firebase-web-api-key --scope env
+noodle variables set FIREBASE_AUTH_DOMAIN your-firebase-project.firebaseapp.com --scope env
+noodle check --target embedded-assistant src/server.ts
+```
+
+Assistant origins are exact and HTTPS-only. A local embedding application must serve itself over HTTPS and
+declare an origin such as `https://localhost:3000`; `noodle dev` does not provide TLS for that separate web
+application.
+
+Create the backend credential after deployment. The CLI writes it to a mode-0600 file and never prints the
+secret:
+
+```bash
+noodle assistant clients create --name web --org noodleseed --app customer-auth --env prod
+```
+
+Only the Noodle service URL, assistant client ID, and assistant client secret belong in the authenticated
+customer backend. The model URL, model name, and model API key remain managed by the Noodle deployment.
+
+The customer's authenticated backend calls `createAssistantSession(...)` from
+`@noodleseed/assistant/server`, passing the already-verified user and browser origin. The browser then uses
+the returned short-lived session through the Web Component or React wrapper:
+
+```bash
+pnpm add @noodleseed/assistant
+```
+
+```tsx
+import { NoodleAssistant } from '@noodleseed/assistant/react';
+
+<NoodleAssistant
+  sessionEndpoint="/api/noodle-assistant/session"
+  theme="auto"
+  onSessionExpired={() => console.info('Assistant session renewed')}
+/>;
+```
+
+`theme="auto"` follows the SaaS application. The server-level `branding` block is inherited by both MCP App
+widgets and the assistant; documented `--ns-assistant-*` semantic CSS variables remain the final integration
+escape hatch. There is no second assistant branding declaration.
+The end-user UI contains only customer branding.
+Text streams progressively. Expired turns re-exchange through the authenticated backend and retry once;
+consent-bound tool confirmations never replay automatically.
+
+The Firebase project ID is required because Firebase ID tokens use the project ID as the token audience and
+issuer suffix. The runtime verifies `aud` against the project ID and `iss` against
+`https://securetoken.google.com/<projectId>`.
+
+The Firebase Web API key and auth domain are public Firebase browser configuration. They let the Noodle
+Cloud-hosted bridge initialize Firebase Auth for this customer project; they are not server secrets. Keep
+them out of source with `variable(...)`, restrict the Firebase key to the expected browser origins and APIs,
+and use `secret(...)` only for credentials that must never reach a browser.
+
+The `noodleseed_app_api` connector currently points at the NoodleSeed.com dev app surface:
+
+```text
+https://dev.noodleseed.com
+```
+
+When the customer app moves from `dev.noodleseed.com` to `app.noodleseed.com`, update the connector's
+`noodleseedApiOrigin` constant to the production API origin that serves the same paths.
+
+The connector uses delegated Firebase customer credentials. During the customer OAuth bridge, Noodle Seed
+verifies the Firebase ID token, stores the Firebase refresh token through the credential broker, and refreshes
+a Firebase ID token when the connector calls the NoodleSeed.com app API. The broker then exchanges that ID
+token for the app's existing Next.js session cookie. There is no shared `NOODLESEED_APP_API_TOKEN` for this
+example.
+
+Firebase Auth must list `cloud.noodleseed.dev` as an authorized domain before browser sign-in works in
+production.
+
+## Deploy customer-protected to Noodle Seed Cloud
+
+```bash
+noodle deploy examples/customer-auth/src/server.ts \
+  --org noodleseed \
+  --app customer-auth \
+  --env prod \
+  --access customers
+```
+
+Endpoint:
+
+```text
+https://cloud.noodleseed.dev/o/noodleseed/customer-auth/mcp
+```
+
+## MCP Primitives
+
+- Tool `list_my_organizations`: calls `GET /api/organizations` and returns the organizations the signed-in
+  customer is a member of. Takes no arguments; the org set is scoped by the verified customer session.
+- Tool `list_org_apps`: calls `GET /api/organizations/{org_id}/apps` for one organization `org_id`.
+
+## Auth boundary
+
+Firebase ID-token verification is handled by Noodle Seed's generic Firebase bridge adapter during OAuth
+issuance. The MCP client receives a Noodle-issued, resource-bound access token marked as a Firebase customer
+identity; raw Firebase tokens and inbound MCP bearer tokens are never forwarded to tools, connectors,
+widgets, or downstream systems.
+
+The connector-backed tools use the credential broker to turn the signed-in Firebase customer session into the
+same session-cookie credential that the existing NoodleSeed.com Next.js API already expects. The inbound MCP
+bearer token is never used as an app API credential.

package/skills/codex/examples/customer-auth/noodle.json

@@ -0,0 +1,4 @@
+{
+  "entrypoint": "src/server.ts",
+  "name": "customer-auth"
+}

package/skills/codex/examples/customer-auth/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "customer-auth",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "test": "vitest run",
+    "validate": "noodle validate",
+    "dev": "noodle dev",
+    "deploy": "noodle deploy"
+  },
+  "devDependencies": {
+    "@noodleseed/one": "latest",
+    "vitest": "latest"
+  }
+}

package/skills/codex/examples/customer-auth/src/server.ts

@@ -0,0 +1,145 @@
+import {
+  annotations,
+  connector,
+  customerAuth,
+  embeddedAssistant,
+  openAICompatible,
+  secret,
+  server,
+  tool,
+  variable,
+  z,
+} from '@noodleseed/one';
+
+const noodleseedApiOrigin = 'https://dev.noodleseed.com';
+
+const noodleseedApi = connector('noodleseed_app_api')
+  .version('1.0.0')
+  .http({
+    baseUrl: noodleseedApiOrigin,
+    allowedOrigins: [noodleseedApiOrigin],
+    auth: {
+      kind: 'delegatedSessionCookie',
+      provider: 'firebase',
+      sessionUrl: `${noodleseedApiOrigin}/api/auth/session`,
+      tokenField: 'idToken',
+    },
+    operations: {
+      list_org_apps: {
+        type: 'read',
+        method: 'GET',
+        path: '/api/organizations/${args.org_id}/apps',
+        query: ['skip', 'limit'],
+        input: z.object({
+          org_id: z.string(),
+          skip: z.number().optional(),
+          limit: z.number().optional(),
+        }),
+        output: z.object({ result: z.unknown().optional() }),
+        response: {
+          result: '${response}',
+        },
+      },
+      list_organizations: {
+        type: 'read',
+        method: 'GET',
+        path: '/api/organizations',
+        output: z.object({ organizations: z.array(z.unknown()).optional() }),
+        response: {
+          organizations: '${response.organizations}',
+        },
+      },
+    },
+  });
+
+export default server(
+  'noodleseed_customer_auth',
+  {
+    title: 'NoodleSeed.com Customer Auth',
+    version: '1.0.0',
+    branding: {
+      name: 'Noodle Seed Assistant',
+      accent: '#E85D24',
+      surface: '#FFFFFF',
+      surfaceDark: '#171310',
+      colorScheme: 'auto',
+      theme: {
+        light: { accentText: '#FFFFFF', text: '#1C1714' },
+        dark: { accent: '#FF8A4C', accentText: '#1C100A', text: '#FFF8F2' },
+      },
+    },
+    use: { app_api: noodleseedApi },
+    auth: customerAuth.firebase({
+      projectId: variable('FIREBASE_PROJECT_ID'),
+      apiKey: variable('FIREBASE_WEB_API_KEY'),
+      authDomain: variable('FIREBASE_AUTH_DOMAIN'),
+      user: {
+        id: 'sub',
+        email: 'email',
+        name: 'name',
+        tenant: 'firebase.tenant',
+        orgs: 'claims.orgs',
+        roles: 'claims.roles',
+      },
+    }),
+    instructions:
+      'Customer-authenticated demo. Firebase proves the customer identity, while read-only NoodleSeed.com API calls use broker-managed delegated Firebase customer credentials.',
+    assistant: embeddedAssistant({
+      model: openAICompatible({
+        baseUrl: variable('ASSISTANT_MODEL_BASE_URL'),
+        model: variable('ASSISTANT_MODEL'),
+        apiKey: secret('ASSISTANT_MODEL_API_KEY'),
+      }),
+      // Production origins are exact HTTPS; http://localhost:<port> is allowed for local development.
+      allowedOrigins: [
+        'https://app.noodleseed.com',
+        'https://dev.noodleseed.com',
+        'http://localhost:3000',
+      ],
+      layout: { mode: 'floating', position: 'bottom-right', panelWidth: 420 },
+      labels: {
+        welcomeHeading: 'How can I help with Noodle Seed?',
+        composerPlaceholder: 'Ask about your apps…',
+      },
+      suggestedPrompts: ['Show my organizations', 'List the apps in my organization'],
+    }),
+  },
+  [
+    tool('list_org_apps', {
+      description: 'List NoodleSeed.com apps for an organization from the dev app API.',
+      input: z.object({
+        org_id: z.string(),
+        skip: z.number().int().min(0).optional(),
+        limit: z.number().int().min(1).max(100).optional(),
+      }),
+      output: z.object({
+        result: z.unknown(),
+      }),
+      annotations: annotations.readOnly(),
+      fulfil({ input, connectors }) {
+        const apps = connectors.app_api.listOrgApps({
+          org_id: input.org_id,
+          skip: input.skip,
+          limit: input.limit,
+        });
+        return {
+          result: apps.result,
+        };
+      },
+    }),
+    tool('list_my_organizations', {
+      description: 'List the NoodleSeed.com organizations the signed-in customer belongs to.',
+      input: z.object({}),
+      output: z.object({
+        organizations: z.array(z.unknown()),
+      }),
+      annotations: annotations.readOnly(),
+      fulfil({ connectors }) {
+        const organizations = connectors.app_api.listOrganizations();
+        return {
+          organizations: organizations.organizations,
+        };
+      },
+    }),
+  ],
+);

package/skills/codex/examples/customer-auth/test/server.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it } from 'vitest';
+import app from '../src/server.js';
+
+describe('customer-auth example', () => {
+  it('exports a customer-authenticated, customer-branded embedded assistant', async () => {
+    expect(typeof app.toManifest).toBe('function');
+    const manifest = await app.toManifest();
+    expect(manifest.server.assistant).toMatchObject({
+      model: { kind: 'openai-compatible', apiKey: 'ASSISTANT_MODEL_API_KEY' },
+      layout: { mode: 'floating' },
+    });
+    expect(
+      manifest.server.assistant?.allowedOrigins.every((origin) => origin.startsWith('https://')),
+    ).toBe(true);
+    expect(manifest.server.branding).toMatchObject({
+      name: 'Noodle Seed Assistant',
+      colorScheme: 'auto',
+    });
+    expect(manifest.server.auth).toMatchObject({
+      projectId: '${env.FIREBASE_PROJECT_ID}',
+      apiKey: '${env.FIREBASE_WEB_API_KEY}',
+      authDomain: '${env.FIREBASE_AUTH_DOMAIN}',
+    });
+  });
+});

package/skills/codex/examples/hello/src/server.ts

@@ -1,4 +1,4 @@
-import { server, tool, z } from '@noodleseed/one';
+import { annotations, server, tool, z } from '@noodleseed/one';
 
 export default server(
   'hello',
@@ -22,6 +22,8 @@ export default server(
       output: z.object({
         message: z.string(),
       }),
+      // Read-only, closed-world: assistant surfaces run this without a consent prompt.
+      annotations: annotations.readOnly(),
       fulfil: ({ input }) => {
         return { message: `Hello, ${input.name}!` };
       },