@noodleseed/agent-kit 0.54.0 → 0.55.0

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

@@ -8,6 +8,7 @@
 - Connectors
 - HTTP connector example (full server)
 - Customer OAuth for remote MCP clients
+- Auth-derived customer API endpoints
 - Per-tool authorization
 - Delegated downstream auth (call your API as the signed-in user)
 - Invocation context
@@ -109,6 +110,74 @@ For `customerAuth.oidc(...)` and `.federatedOidc(...)`, the application develope
 
 That metadata must expose HTTPS `authorization_endpoint`, `token_endpoint`, `jwks_uri`, and RFC 7591 `registration_endpoint`; advertise authorization-code and refresh-token grants, Dynamic Client Registration, PKCE with `code_challenge_methods_supported: ["S256"]`, and public clients with `token_endpoint_auth_methods_supported: ["none"]`. Implement RFC 8707 `resource`, mint access-token `aud` for the exact MCP resource URL, and publish only public signing keys in JWKS. Run `noodle auth doctor src/server.ts`; its issuer-readiness probes perform bounded read-only GET checks and never register a client. A successful `noodle deploy --access customers` reports the same readiness without turning a diagnostic failure into a failed deployment.
 
+## Auth-derived customer API endpoints
+
+Use a customer endpoint when the verified IdP selects a different API base URL for each SaaS customer. The claim contains the complete base URL; tool input and `${user}` do not select it. Declare one named policy, use that reference as the connector `baseUrl`, and map its claim path in direct OIDC or on every federated issuer:
+
+```ts
+import { connector, customerAuth, customerEndpoint, secret, server, tool, variable, z } from '@noodleseed/one';
+
+const customerApi = customerEndpoint('customer_api', {
+  allowedHttpsHostSuffixes: ['api.noodleseed.dev'],
+});
+
+const api = connector('customer_api_connector').version('1.0.0').http({
+  baseUrl: customerApi,
+  auth: {
+    kind: 'delegatedTokenExchange',
+    tokenUrl: 'https://id.noodleseed.dev/oauth/token',
+    clientId: variable('CUSTOMER_API_CLIENT_ID'),
+    clientSecret: secret('CUSTOMER_API_CLIENT_SECRET'),
+  },
+  operations: {
+    list_records: {
+      type: 'read',
+      method: 'GET',
+      path: '/records',
+      input: z.object({}),
+      output: z.object({ records: z.array(z.unknown()).max(100) }),
+    },
+  },
+});
+
+export default server(
+  'customer_records',
+  {
+    title: 'Customer records',
+    version: '1.0.0',
+    use: { api },
+    auth: customerAuth.oidc({
+      issuer: 'https://id.noodleseed.dev',
+      audience: 'https://org.cloud.noodleseed.dev/app/mcp',
+      routing: {
+        endpoints: {
+          customer_api: { claim: 'tenant.api_base_url' },
+        },
+      },
+    }),
+  },
+  [
+    tool('list_records', {
+      description: 'List records for the signed-in customer.',
+      input: z.object({}),
+      output: z.object({ records: z.array(z.unknown()).max(100) }),
+      fulfil: ({ connectors }) => {
+        const result = connectors.api.listRecords();
+        return { records: result.records };
+      },
+    }),
+  ],
+);
+```
+
+`customerEndpoint` accepts exactly one non-empty policy arm: exact HTTPS origins, or HTTPS hostname suffixes. Exact policies may authorize an explicit non-default port; suffix policies allow port 443 and match only the exact host or dot-boundary subdomains. Do not add connector `allowedOrigins` to a customer-routed connector. Its fixed credential/token endpoints are validated independently and cannot come from caller claims.
+
+Every federated issuer must repeat every endpoint key used by the app, although each issuer may choose a different claim path. Endpoint names use lowercase letters, numbers, and underscores. Resolved claims must be exact absolute HTTPS URLs of at most 2,048 UTF-8 bytes with no userinfo, query, fragment, IP literal, special-use host, or unsafe whitespace/control characters. The runtime preserves a canonical optional base path.
+
+Resolved customer URLs are private routing authority: they never enter the manifest/artifact, `${user}`, logs, model output, widgets, confirmation review, cache keys, or delegated-token-exchange assertions. Routed read operations may be used by tools, including their declared nested connector calls. Customer-routed action operations fail compilation with `customer_endpoint_action_unsupported`; routed resources, prompts, and ambient context fail with `customer_endpoint_surface_unsupported` in this release.
+
+At runtime, a missing, malformed, or disallowed claim returns the same safe `connector_route_unavailable` tool error before credential lookup or connector egress. `tools/list` remains based only on roles and scopes, so route availability neither reveals tenant topology nor changes the existing authorization filter.
+
 ## Per-tool authorization
 
 Keep endpoint authentication in `customerAuth.*(...)`, then narrow individual tools with the optional typed `authorization` rule. Every `requiredScopes` value is required; any one `allowedRoles` value is sufficient; when both lists are present, both conditions apply. Omit `authorization` for an unrestricted tool. Do not invent a policy expression language or infer authorization from tool arguments, page context, connector output, email domains, or other unverified data.
@@ -135,7 +204,7 @@ Role values are trusted only from the explicitly configured claim path (or the p
 
 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 verified customer OIDC identities, the built-in Firebase/Microsoft adapters, and embedded-assistant sessions; no per-user OAuth enrollment.
+- **`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). It works with verified customer OIDC identities and the built-in Firebase/Microsoft adapters; no per-user OAuth enrollment. Embedded-assistant sessions support this exchange for static connectors. Customer-routed connectors require a direct or federated MCP OIDC request and fail closed in embedded-assistant sessions because those sessions carry no IdP endpoint claim.
 - **`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.
 
@@ -144,7 +213,7 @@ Use delegated connector auth when the downstream API must enforce its own per-us
 ```ts
 auth: {
   kind: 'delegatedTokenExchange',
-  tokenUrl: 'https://app.example.com/api/assistant/oauth/token', // origin must be in allowedOrigins
+  tokenUrl: 'https://app.example.com/api/assistant/oauth/token', // fixed HTTPS; static connectors also allowlist its origin
   clientId: variable('EXAMPLE_DELEG_CLIENT_ID'),
   clientSecret: secret('EXAMPLE_DELEG_CLIENT_SECRET'),
   scopes: ['time_off'],           // optional
@@ -167,7 +236,7 @@ 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 `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`. A routed exchange adds `route: { key, fingerprint }`, never the customer URL; credential cache and single-flight keys include that route binding. Respond with `{ "access_token": "...", "token_type": "Bearer", "expires_in": 900 }`; the broker caches per user + connector + scopes + route until `expires_in` minus 300 s and presents the token downstream as `Authorization: Bearer`.
 
 ### The downstream token endpoint (your backend)
 

package/skills/codex/references/compile-errors.md

@@ -63,5 +63,13 @@ Run `noodle validate` (add `--json` for the machine-readable envelope, `--fix-pr
 | `unsupported_credential_profile` | Select a credential profile declared by the connector and accepted by the operation; use the reported suggestions instead of inventing a profile name. |
 | `credential_scope_mismatch` | Declare a connection source whose scopes include every operation-required scope, or select an external exchange provider that can mint them. |
 | `credential_audience_mismatch` | Set the connection source audience to the operation-required audience exactly, or use an external exchange provider that can mint it. |
+| `customer_endpoint_auth_required` | Protect the app with direct or federated `customerAuth` OIDC and map every reachable `customerEndpoint` key under auth routing. |
+| `customer_endpoint_mapping_required` | Add the endpoint key at the cited auth routing path; every direct/federated issuer must map every customer endpoint used by the app. |
+| `customer_endpoint_unknown_mapping` | Remove the unknown or unused auth routing key, or use that exact declared `customerEndpoint` key from a reachable connector operation. |
+| `customer_endpoint_bridge_unsupported` | Replace the Firebase/Microsoft bridge with direct or federated OIDC before using auth-derived customer connector endpoints. |
+| `customer_endpoint_action_unsupported` | Use a read operation for this customer-routed call until route-bound action confirmation support is available. |
+| `customer_endpoint_surface_unsupported` | Move the customer-routed call into a tool fulfilment; routed resources, prompts, and ambient providers are unsupported. |
+| `customer_endpoint_credential_source_unsupported` | Remove the manifest connection binding; a customer-routed connector uses its declared delegated token exchange auth or no auth. |
+| `customer_endpoint_policy_conflict` | Give every reachable declaration of this endpoint key one identical policy, or rename keys whose allowed origins differ. |
 | `unused_connector_alias` | A declared connector alias is never called; remove the unused `use` entry or wire it into a tool. |
 | `arg_mismatch` | A connector call is missing or adds arguments; match the operation signature under `expected`/`got`. |

package/skills/codex/references/sdk-surface.md

@@ -54,6 +54,7 @@ Platform helper connectors are explicit subpath imports from `@noodleseed/one/pl
 ### Other
 
 - `clientCredentials`
+- `customerEndpoint`
 - `embeddedAssistant`
 - `externalExchange`
 - `gmailConnector`

package/skills/codex/reporting-noodle-feedback/SKILL.md

@@ -3,7 +3,7 @@ name: reporting-noodle-feedback
 description: "Use when a Noodle Seed bug, misleading instruction, missing capability, or concrete product improvement should be proposed to the user."
 ---
 
-<!-- noodle-skill version:0.54.0 hash:0f404109f4845683 -->
+<!-- noodle-skill version:0.55.0 hash:0f404109f4845683 -->
 
 # reporting-noodle-feedback
 

package/skills/codex/verifying-mcp-delivery/SKILL.md

@@ -3,7 +3,7 @@ name: verifying-mcp-delivery
 description: "Use when proving a Noodle Seed MCP project works at a named compile, local, connector, App, host, deployment, or production evidence level."
 ---
 
-<!-- noodle-skill version:0.54.0 hash:6ef6ef551e26b78e -->
+<!-- noodle-skill version:0.55.0 hash:6ef6ef551e26b78e -->
 
 # verifying-mcp-delivery