@aotter/mantle 0.0.11-alpha.47 → 0.0.11-alpha.49

package/README.md

@@ -88,6 +88,8 @@ The `mantle-runtime` package never imports Cloudflare-specific types — adapter
 - Embedded docs and agent skills ship inside this npm package for
   generated-site agents:
   - `node_modules/@aotter/mantle/docs/design-atoms.md`
+  - `node_modules/@aotter/mantle/docs/api-mcp-authorization.md` (anonymous,
+    API-key, paid guard, personal-token, OAuth, REST, and MCP examples)
   - `node_modules/@aotter/mantle/docs/media-uploads.md` (Cloudflare R2 adapter recipe)
   - `node_modules/@aotter/mantle/docs/adr/`
   - `node_modules/@aotter/mantle/skills/develop/SKILL.md`
@@ -98,6 +100,7 @@ The `mantle-runtime` package never imports Cloudflare-specific types — adapter
   - `node_modules/@aotter/mantle/skills/provision/SKILL.md`
 - [Repo](https://github.com/aotter/mantle)
 - [4-atom manifest model (ADR-0001)](https://github.com/aotter/mantle/blob/develop/docs/adr/0001-four-atom-manifest-model.md)
+- [API and MCP authorization](https://github.com/aotter/mantle/blob/develop/docs/api-mcp-authorization.md)
 - [Release process](https://github.com/aotter/mantle/blob/develop/docs/release-process.md)
 - [Issues](https://github.com/aotter/mantle/issues)
 

package/docs/adapter-guide.md

@@ -66,6 +66,15 @@ The runtime is a library, not an HTTP server. A new adapter must mount equivalen
 
 Auth is not a runtime port. Per [ADR-0014](adr/0014-auth-better-auth-and-multi-tenant-mcp.md), the adapter owns Better Auth wiring and passes authenticated user/staff context into runtime dispatchers. Procedure handlers receive that data through `HandlerContext` in `packages/mantle-runtime/src/domain/model/HandlerContext.ts`.
 
+The adapter must also normalize verified credential metadata into
+`HandlerContext.auth` (`credential`, opaque `credentialId`, optional
+`clientId`, scopes). Platform-native session/OAuth verification stays in the
+adapter. A narrow adapter extension seam may let consumer code verify its own
+API-key or personal-token formats, but credential storage/issuance must not
+become a runtime port. The Cloudflare reference is
+`mount/resolveCaller.ts`; consumer usage is documented in
+[API and MCP authorization](api-mcp-authorization.md).
+
 Minimum HTTP behavior for a full adapter:
 
 - Route manifest HTTP Triggers to `runtime.invokeProcedure`.
@@ -74,6 +83,8 @@ Minimum HTTP behavior for a full adapter:
 - Serve admin SPA assets through `AssetServer`, with an SPA catchall for admin client-side routes.
 - Mount public render routes and markdown mirrors when the starter exposes public pages.
 - Translate runtime diagnostics and validation failures into stable HTTP JSON responses instead of throwing raw errors.
+- Evaluate target auth and dynamic guards through the runtime use cases; do
+  not duplicate guard logic in HTTP handlers.
 
 Minimum auth/MCP behavior:
 
@@ -82,7 +93,12 @@ Minimum auth/MCP behavior:
 - Validate `/mcp` requests with any authenticated session (D1 role check is surface-driven, not OAuth-scope-driven — claude.ai rejects colon-shaped scopes).
 - Advertise a single non-colon scope (default `["mcp"]`) in `scopes_supported`. Per-surface enforcement happens server-side in the apiHandler.
 - Build `McpAuthContext` from the validated session and pass it to `McpJsonRpcDispatcher`.
-- Build procedure `HandlerContext` with `user`, `staff`, adapter `env`, and optional `waitUntil`.
+- Build Procedure/View `HandlerContext` with `user`, live `staff`, normalized
+  `auth`, adapter `env`, and optional `waitUntil`.
+- Re-read mutable staff role for each protected REST/MCP invocation. Token or
+  consent-time role snapshots are not an authorization boundary.
+- Keep `tools/list` filtering as UX only; route every `tools/call` through the
+  same auth evaluator and guard runner used by REST.
 
 ## Static assets
 
@@ -98,11 +114,18 @@ Minimum auth/MCP behavior:
 - [ ] Mount HTTP Trigger and View REST surfaces.
 - [ ] Mount admin/public render routes and admin SPA assets.
 - [ ] Provide adapter-owned Better Auth wiring and session helpers.
+- [ ] Normalize session/OAuth and any consumer credential seam into
+      `HandlerContext.auth`; never put raw credentials in runtime context.
 - [ ] Mount `/mcp/staff` and `/mcp` via the platform's OAuth provider lib (Cloudflare adapter uses `@cloudflare/workers-oauth-provider` at top level). Enforce staff D1 role inside the apiHandler.
+- [ ] Prove one guarded target has identical REST/MCP outcomes, including
+      mutable revocation on the next call.
 - [ ] Add optional `MediaStorage` or `DeferredHookDispatcher` only when the adapter supports those features.
 - [ ] Verify the runtime package still has no platform-specific imports.
 
 ## Current non-goals
 
 - Do not add `SessionRepository`, `OAuthVerifier`, `UserRepository`, or `StaffRepository` runtime ports. Those were pre-ADR-0014 concepts and are not part of the current adapter contract.
+- Do not add API-key, personal-token, transaction, billing, or entitlement
+  repositories to Core. They are consumer state behind the adapter resolver
+  and guard Procedure.
 - Do not add a second canonical migration chain for a new adapter. The runtime owns canonical migrations; adapters execute them through `DatabaseDriver.migrations`.

package/docs/adr/0001-four-atom-manifest-model.md

@@ -294,9 +294,11 @@ forces it.
 - `spec.orderBy:`
 - `spec.limit:`
 - `spec.params:` (required query params referenced by filter values)
+- `spec.requires.{auth, guard}:` (same authorization contract as Procedure)
 
 **Procedure (v0.1)**:
 - `spec.requires.auth.all:` (closed predicate vocabulary)
+- `spec.requires.guard.procedure:` (one consumer-owned dynamic guard)
 - `spec.input:` (JSON Schema 2020-12)
 - `spec.output:` (JSON Schema 2020-12)
 - `spec.handler.{kind: ref, ref: <opaque-key>}` — author-supplied
@@ -311,14 +313,16 @@ forces it.
 - `spec.source.kind: lifecycle` — entry-writer hook (promoted to
   v0.1.0; runtime implemented by `LifecycleHookingEntryRepository`)
 - `spec.source.{schema, on, errorPolicy}` (when `kind: lifecycle`)
+- `spec.source.kind: mcp` plus `surface: public | staff` — MCP tool
+  exposure for a declared Procedure
 - `spec.target.procedure:`
 
 #### v0.1 closed enums
 
 - `x-mantle-bind: {ctx.user, ctx.staff, now}`
-- `ctx.*` predicate identity: `{user, staff}` (no `system` until a
-  use case forces it)
-- `Trigger.source.kind: {http, lifecycle}`
+- `ctx.*` predicate vocabulary: `{user, staff, auth, auth.scope}` (no
+  `system` until a use case forces it)
+- `Trigger.source.kind: {http, lifecycle, mcp}`
 - `Procedure.handler.kind: {ref, builtin}`
 - `BuiltinOp: {create, update, upsert, delete}`
 - `LifecycleHook: {before_create, after_create, before_update,

package/docs/adr/0002-closed-enums-for-bindings.md

@@ -1,6 +1,7 @@
 # ADR-0002: Closed enums for identity/time bindings
 
-**Status:** Carried over from POC v0.0.x; refreshed for v0.1.0.
+**Status:** Carried over from POC v0.0.x; refreshed for v0.1.0;
+amended 2026-07-15 for verified credentials and delegated scopes.
 
 **Date**: 2026-04-30 (POC); refreshed 2026-05-03
 
@@ -224,3 +225,38 @@ parser rejects unknown values with the structured diagnostic
 shape. Verify in code review that new manifest grammar
 additions do not quietly widen these enums; widening is a
 grammar-revise, not a code-cleanup.
+
+## Amendment — 2026-07-15: verified credentials and delegated scopes
+
+Epic #467 supplied the required grammar-revise evidence: the existing
+`ctx.user` and `ctx.staff` predicates cannot represent service API keys or
+delegated OAuth/personal-token scopes without coupling Core to a credential
+store. The closed predicate vocabulary is therefore extended by exactly two
+entries:
+
+```yaml
+requires:
+  auth:
+    all:
+      - ctx.auth
+      - { "ctx.auth.scope": "orders:read" }
+```
+
+- `ctx.auth` requires any credential that an adapter has already verified and
+  normalized into `HandlerContext.auth`.
+- `{ "ctx.auth.scope": "<opaque site-owned scope>" }` requires that one exact
+  scope. Multiple scopes are expressed by repeating the predicate under the
+  existing `all` group.
+
+The full v0.1 vocabulary is now `ctx.user`, `ctx.staff`, `ctx.auth`, and
+`ctx.auth.scope`. The latter two do not add a credential-kind expression,
+`any` group, policy array, scope catalog, or entitlement lookup. API keys may
+have no `ctx.user`; OAuth and personal tokens may supply one. Missing identity
+or credential yields `UNAUTHENTICATED` (`401`), while a verified credential
+missing a required role/scope yields `AUTH_DENIED` (`403`).
+
+Current membership, payment, ownership, or transaction state is intentionally
+not a static predicate. A target may name one ordinary Procedure through
+`requires.guard.procedure`; that Procedure performs the site-owned dynamic
+check after target input validation and before target execution. This keeps
+the predicate set closed and preserves the four-atom model.

package/docs/adr/0014-auth-better-auth-and-multi-tenant-mcp.md

@@ -458,3 +458,56 @@ The boundary is deliberately narrower than "hosted auth everywhere":
   hosted auth for `customer.com` must use an OAuth/OIDC broker flow:
   Platform authenticates and returns identity; the customer site creates
   its own local session and maps identity into local grants.
+
+## Amendment — 2026-07-15: one adapter-owned authorization pipeline
+
+Epic #467 extends the auth contract without moving auth into
+`mantle-runtime`. The original adapter-ownership rule remains authoritative:
+Better Auth is the curated Cloudflare default for identity/session/OIDC, and
+`@cloudflare/workers-oauth-provider` remains the compatibility transport for
+remote MCP. Both adapters now normalize verified callers into the same
+runtime context before invoking a target.
+
+`HandlerContext` gains an additive optional `auth` member carrying only:
+
+```ts
+{
+  credential: "session" | "oauth" | "api-key" | "personal-token";
+  credentialId: string | null;
+  clientId: string | null;
+  scopes: readonly string[];
+}
+```
+
+Raw keys/tokens and refresh tokens are forbidden in this context. `ctx.user`
+remains the authenticated subject when one exists; `ctx.staff` is a mutable
+privilege overlay and is re-read from D1 for each protected REST/MCP call.
+
+The Cloudflare adapter exposes one `ConsumerCredentialResolver` seam for a
+site to recognize and verify its own API-key or personal-token formats. It
+distinguishes `not-handled`, `invalid`, and `verified`; a recognized invalid
+credential never falls back to a cookie. Core adds no credential repository,
+table, issuance API, or runtime auth port.
+
+The curated Better Auth facade also adds the OAuth resource primitives needed
+by a generated site acting as a client or provider:
+
+- generic OAuth client `resource` is retained across authorization, code
+  exchange, and refresh;
+- OAuth provider `validAudiences` constrains minted JWT audiences;
+- `getProviderAccessToken(request, providerId)` uses the current local session
+  and returns no refresh token/account row;
+- `verifyOAuthAccessToken()` verifies issuer/JWKS, audience, time claims, and
+  scopes, rejects opaque tokens, and preserves the `401`/`403` distinction.
+
+REST and MCP transport verification remain adapter-specific. After
+normalization, both call the same runtime auth evaluator and optional guard
+Procedure. Standard remote MCP continues to use its OAuth bearer and the
+single compatibility `mcp` resource scope; manifest scopes are re-evaluated on
+every `tools/call`. MCP does not promise to accept a raw REST API key/PAT.
+
+Dynamic membership, billing, and entitlement state remains consumer-owned.
+`requires.guard.procedure` orchestrates a site handler on every invocation but
+does not introduce a Policy atom or an entitlement service. See
+[`API and MCP authorization`](../api-mcp-authorization.md) for the public API
+and end-to-end examples.

package/docs/api-mcp-authorization.md

@@ -0,0 +1,632 @@
+# API and MCP authorization
+
+Mantle gives generated sites one authorization pipeline for manifest HTTP
+Triggers, Views, Procedures, and MCP tools. Core verifies or normalizes a
+caller, evaluates the closed manifest predicates, invokes an optional dynamic
+guard Procedure, and only then reaches the target.
+
+Mantle does **not** issue or store API keys or personal tokens, define a scope
+catalog, read payment-provider state, or decide who is entitled to a product.
+Those are site-owned concerns. The Cloudflare adapter supplies a narrow
+resolver seam and the runtime supplies the common enforcement machinery.
+
+## Ownership boundary
+
+| Mantle Core SDK | Generated site / Mantle Site |
+| --- | --- |
+| Curated OAuth resource and audience options | API-key and personal-token generation, hashing, storage, rotation, and revocation |
+| JWT verification and linked-provider token facade | Scope names and grant rules |
+| `ConsumerCredentialResolver` normalization seam | Account, transaction, subscription, and entitlement tables |
+| `HandlerContext.auth`, closed predicates, and guard orchestration | Guard handlers and payment-state freshness rules |
+| Consistent REST/MCP diagnostics and reflection | CORS policy and business response fields |
+
+Authentication and entitlement are deliberately separate. A resolver answers
+“is this credential valid, and who/what does it represent?” A guard answers
+“is that currently verified caller allowed to perform this business action?”
+
+## Core contracts
+
+After the adapter verifies a caller, runtime handlers see only normalized,
+non-secret metadata:
+
+```ts
+interface HandlerContext {
+  readonly user: { readonly id: string } | null;
+  readonly staff: { readonly id: string; readonly role: StaffRole } | null;
+  readonly auth?: {
+    readonly credential: "session" | "oauth" | "api-key" | "personal-token";
+    readonly credentialId: string | null;
+    readonly clientId: string | null;
+    readonly scopes: readonly string[];
+  };
+  // env, waitUntil, and event omitted here
+}
+```
+
+Raw credentials and refresh tokens never enter this context. The manifest
+vocabulary stays closed:
+
+```yaml
+requires:
+  auth:
+    all:
+      - ctx.auth
+      - ctx.user
+      - { "ctx.auth.scope": "orders:read" }
+  guard:
+    procedure: require-active-api-access
+```
+
+- `ctx.auth` requires any verified credential.
+- `ctx.user` requires a verified user subject. Service API keys may have no
+  user.
+- each `ctx.auth.scope` entry requires that opaque, site-defined scope;
+  repeat the predicate to require multiple scopes.
+- `ctx.staff` continues to use the closed staff-role list.
+- `guard.procedure` names one ordinary, unguarded `handler.kind: ref`
+  Procedure. It is not a fifth Policy atom.
+
+The runtime order is fixed:
+
+1. verify and normalize the transport credential;
+2. evaluate static predicates before exposing input-schema details;
+3. validate/coerce target input or View params;
+4. invoke the guard with that validated value and the same context;
+5. invoke the target only after the guard succeeds.
+
+Missing/invalid credentials return `401`; a verified caller missing a required
+role or scope returns `403`; a site guard may return
+`ENTITLEMENT_REQUIRED`/`402`. Guards run on every call and are not cached.
+
+## Cloudflare consumer wiring
+
+Pass one site-owned resolver to `createCmsRef`. Return `not-handled` when the
+request is not one of the site's credential formats, `invalid` when it is a
+recognized but bad/revoked credential, and `verified` only after checking the
+authoritative site record.
+
+This example table and query are consumer code, not a Mantle migration:
+
+```ts
+import type { ConsumerCredentialResolver } from "@aotter/mantle/cloudflare";
+
+type CredentialRow = {
+  id: string;
+  kind: "api-key" | "personal-token";
+  user_id: string | null;
+  scopes_json: string;
+  revoked_at: string | null;
+};
+
+export function siteCredentialResolver(db: D1Database): ConsumerCredentialResolver {
+  return async (request) => {
+    const apiKey = request.headers.get("x-api-key");
+    const authorization = request.headers.get("authorization");
+
+    let kind: CredentialRow["kind"];
+    let raw: string;
+    if (apiKey !== null) {
+      kind = "api-key";
+      raw = apiKey;
+    } else if (authorization?.startsWith("Bearer site_pat_")) {
+      kind = "personal-token";
+      raw = authorization.slice("Bearer ".length);
+    } else {
+      // Lets configured OAuth bearer or cookie-session auth try next.
+      return { kind: "not-handled" };
+    }
+
+    const digest = await sha256(raw);
+    const row = await db
+      .prepare(
+        "SELECT id, kind, user_id, scopes_json, revoked_at " +
+          "FROM site_credentials WHERE token_sha256 = ? AND kind = ? LIMIT 1",
+      )
+      .bind(digest, kind)
+      .first<CredentialRow>();
+
+    if (!row || row.revoked_at !== null) return { kind: "invalid" };
+    const scopes = parseScopes(row.scopes_json);
+    if (!scopes) return { kind: "invalid" };
+
+    return {
+      kind: "verified",
+      credential: {
+        credential: row.kind,
+        credentialId: row.id, // opaque row id, never the raw key/token
+        userId: row.user_id,
+        scopes,
+      },
+    };
+  };
+}
+
+async function sha256(value: string): Promise<string> {
+  const bytes = await crypto.subtle.digest(
+    "SHA-256",
+    new TextEncoder().encode(value),
+  );
+  return [...new Uint8Array(bytes)]
+    .map((byte) => byte.toString(16).padStart(2, "0"))
+    .join("");
+}
+
+function parseScopes(json: string): string[] | null {
+  try {
+    const value: unknown = JSON.parse(json);
+    return Array.isArray(value) && value.every((scope) => typeof scope === "string")
+      ? value
+      : null;
+  } catch {
+    return null;
+  }
+}
+```
+
+Wire it alongside the existing Auth facade. `oauthBearer` is optional and
+enables JWT bearer verification for manifest REST routes:
+
+```ts
+import {
+  AssetsAssetServer,
+  createCmsRef,
+  createMcpApiHandler,
+  createOAuthProvider,
+  D1DatabaseDriver,
+  KvCacheBinding,
+  mountServerEndpoints,
+} from "@aotter/mantle/cloudflare";
+
+const runtimeRef = createCmsRef({
+  manifests,
+  handlers,
+  bindings: {
+    db: new D1DatabaseDriver(env.DB),
+    kv: new KvCacheBinding(env.KV),
+    assets: env.ASSETS
+      ? new AssetsAssetServer(env.ASSETS)
+      : { fetch: async () => null },
+  },
+  auth,
+  credentialResolver: siteCredentialResolver(env.DB),
+  oauthBearer: {
+    audience: "https://api.example.com",
+    // Optional server-wide floor. Manifest scopes still run per target.
+    scopes: ["api"],
+  },
+});
+
+mountServerEndpoints(app, runtimeRef);
+
+const oauthProvider = createOAuthProvider({
+  defaultHandler: {
+    fetch: (request, workerEnv, ctx) => app.fetch(request, workerEnv, ctx),
+  },
+  apiHandlers: {
+    "/mcp/staff": createMcpApiHandler({ ref: runtimeRef, surface: "staff" }),
+    "/mcp": createMcpApiHandler({ ref: runtimeRef, surface: "public" }),
+  },
+  scopesSupported: ["mcp"],
+});
+```
+
+Export or delegate to `oauthProvider` as the Worker's top-level handler so the
+OAuth provider can verify MCP bearers before dispatching to either MCP surface.
+
+Resolution precedence is site resolver, configured OAuth bearer, then cookie
+session. A recognized invalid credential never falls back to a valid cookie.
+For each verified user, the adapter re-reads the current staff role rather than
+trusting a token or consent-time snapshot.
+
+## 1. Anonymous public API
+
+Omit `requires` when the operation is intentionally anonymous:
+
+```yaml
+apiVersion: cms.mantle.aotter.net/v1
+kind: Procedure
+metadata: { name: public-status }
+spec:
+  input: { type: object }
+  output:
+    type: object
+    required: [status]
+    properties:
+      status: { type: string }
+  handler: { kind: ref, ref: publicStatus }
+---
+apiVersion: cms.mantle.aotter.net/v1
+kind: Trigger
+metadata: { name: public-status-http }
+spec:
+  source: { kind: http, method: POST, path: /api/status }
+  target: { procedure: public-status }
+```
+
+```ts
+const handlers = {
+  publicStatus: async () => ({ status: "ok" }),
+};
+```
+
+```bash
+curl -i -X POST https://site.example.com/api/status \
+  -H 'content-type: application/json' \
+  -d '{}'
+# HTTP/2 200
+```
+
+OpenAPI emits no `security` requirement and no auth responses for this
+operation. No MCP tool is created unless a separate MCP Trigger targets the
+Procedure.
+
+## 2. Public API requiring an API key
+
+The API remains publicly reachable, but its target requires a verified
+credential and the site-defined `catalog:read` scope:
+
+```yaml
+apiVersion: cms.mantle.aotter.net/v1
+kind: Procedure
+metadata: { name: read-catalog }
+spec:
+  requires:
+    auth:
+      all:
+        - ctx.auth
+        - { "ctx.auth.scope": "catalog:read" }
+  input: { type: object }
+  output: { type: object }
+  handler: { kind: ref, ref: readCatalog }
+---
+apiVersion: cms.mantle.aotter.net/v1
+kind: Trigger
+metadata: { name: read-catalog-http }
+spec:
+  source: { kind: http, method: POST, path: /api/catalog/read }
+  target: { procedure: read-catalog }
+```
+
+```ts
+import type { HandlerContext } from "@aotter/mantle/runtime";
+
+const handlers = {
+  readCatalog: async (_input: unknown, ctx: HandlerContext) => ({
+    credentialId: ctx.auth!.credentialId,
+    items: [],
+  }),
+};
+```
+
+```bash
+curl -i -X POST https://site.example.com/api/catalog/read \
+  -H 'content-type: application/json' \
+  -H "x-api-key: $SITE_API_KEY" \
+  -d '{}'
+# valid key with catalog:read -> 200
+# missing or recognized-invalid key -> 401
+# verified key without catalog:read -> 403
+```
+
+`ctx.auth` intentionally means any verified credential; there is no
+credential-kind predicate. Configure and document only the credential sources
+the site intends to accept, or put a kind-specific business rule in a guard.
+With `security.apiKey` configured during OpenAPI emission, the operation
+advertises the real header and carries `x-mantle-required-scopes`.
+
+## 3. API key plus a mutable paid/transaction guard
+
+Keep key verification in the resolver. Put current paid state in an ordinary,
+site-owned guard Procedure:
+
+```yaml
+apiVersion: cms.mantle.aotter.net/v1
+kind: Procedure
+metadata: { name: require-active-api-access }
+spec:
+  input: { type: object }
+  output: { type: object }
+  handler: { kind: ref, ref: requireActiveApiAccess }
+---
+apiVersion: cms.mantle.aotter.net/v1
+kind: Procedure
+metadata: { name: download-export }
+spec:
+  requires:
+    auth:
+      all:
+        - ctx.auth
+        - { "ctx.auth.scope": "exports:read" }
+    guard: { procedure: require-active-api-access }
+  input:
+    type: object
+    required: [reportId]
+    properties:
+      reportId: { type: string }
+  output: { type: object }
+  handler: { kind: ref, ref: downloadExport }
+---
+apiVersion: cms.mantle.aotter.net/v1
+kind: Trigger
+metadata: { name: download-export-http }
+spec:
+  source: { kind: http, method: POST, path: /api/exports/download }
+  target: { procedure: download-export }
+```
+
+```ts
+import {
+  DiagnosticError,
+  runtimeDiagnostic,
+} from "@aotter/mantle/spec";
+import type { HandlerContext } from "@aotter/mantle/runtime";
+
+const handlers = {
+  requireActiveApiAccess: async (_input: unknown, ctx: HandlerContext) => {
+    const credentialId = ctx.auth?.credentialId;
+    const paid = credentialId
+      ? await env.DB.prepare(
+          "SELECT 1 FROM site_api_entitlements " +
+            "WHERE credential_id = ? AND state = 'paid' LIMIT 1",
+        )
+          .bind(credentialId)
+          .first()
+      : null;
+
+    if (!paid) {
+      throw new DiagnosticError(
+        runtimeDiagnostic({
+          code: "ENTITLEMENT_REQUIRED",
+          severity: "error",
+          path: "site:api-entitlement",
+          message: "Active paid API access is required.",
+        }),
+      );
+    }
+    return {};
+  },
+  downloadExport: async ({ reportId }: { reportId: string }) => ({ reportId }),
+};
+```
+
+```bash
+curl -i -X POST https://site.example.com/api/exports/download \
+  -H 'content-type: application/json' \
+  -H "x-api-key: $SITE_API_KEY" \
+  -d '{"reportId":"report-1"}'
+# valid + entitled -> 200
+# invalid key -> 401
+# verified key missing exports:read -> 403
+# verified key whose current paid row is absent/revoked -> 402
+```
+
+The guard receives the already validated target input and runs for every call.
+On `402`, the target handler is not invoked. OpenAPI reflects the guard as
+`x-mantle-guard-procedure` and includes a `402` response; Mantle does not infer
+or publish the site's billing model.
+
+## 4. Personal token with user scope, shared by REST and MCP semantics
+
+This Procedure requires a user subject, a verified credential, a delegated
+scope, and current membership. Bind the same target to HTTP and public MCP:
+
+```yaml
+apiVersion: cms.mantle.aotter.net/v1
+kind: Procedure
+metadata: { name: require-active-membership }
+spec:
+  input: { type: object }
+  output: { type: object }
+  handler: { kind: ref, ref: requireActiveMembership }
+---
+apiVersion: cms.mantle.aotter.net/v1
+kind: Procedure
+metadata: { name: read-account }
+spec:
+  requires:
+    auth:
+      all:
+        - ctx.user
+        - ctx.auth
+        - { "ctx.auth.scope": "accounts:read" }
+    guard: { procedure: require-active-membership }
+  input:
+    type: object
+    required: [accountId]
+    properties:
+      accountId: { type: string }
+  output:
+    type: object
+    required: [accountId]
+    properties:
+      accountId: { type: string }
+  handler: { kind: ref, ref: readAccount }
+---
+apiVersion: cms.mantle.aotter.net/v1
+kind: Trigger
+metadata: { name: read-account-http }
+spec:
+  source: { kind: http, method: POST, path: /api/accounts/read }
+  target: { procedure: read-account }
+---
+apiVersion: cms.mantle.aotter.net/v1
+kind: Trigger
+metadata: { name: read-account-mcp }
+spec:
+  source: { kind: mcp, surface: public }
+  target: { procedure: read-account }
+```
+
+```ts
+import {
+  DiagnosticError,
+  runtimeDiagnostic,
+} from "@aotter/mantle/spec";
+import type { HandlerContext } from "@aotter/mantle/runtime";
+
+const handlers = {
+  requireActiveMembership: async (_input: unknown, ctx: HandlerContext) => {
+    const active = await env.DB.prepare(
+      "SELECT 1 FROM site_memberships " +
+        "WHERE user_id = ? AND state = 'active' LIMIT 1",
+    )
+      .bind(ctx.user!.id)
+      .first();
+    if (!active) {
+      throw new DiagnosticError(
+        runtimeDiagnostic({
+          code: "ENTITLEMENT_REQUIRED",
+          severity: "error",
+          path: `site:membership/${ctx.user!.id}`,
+          message: "Active membership is required.",
+        }),
+      );
+    }
+    return {};
+  },
+  readAccount: async ({ accountId }: { accountId: string }) => ({ accountId }),
+};
+```
+
+REST uses the site resolver's personal token:
+
+```bash
+curl -i -X POST https://site.example.com/api/accounts/read \
+  -H 'content-type: application/json' \
+  -H "authorization: Bearer $SITE_PERSONAL_TOKEN" \
+  -d '{"accountId":"acct-1"}'
+```
+
+Standard remote MCP uses the MCP server's OAuth bearer, not the raw site PAT.
+After OAuth normalization, it reaches the same target and guard:
+
+```bash
+curl -sS -X POST https://site.example.com/mcp \
+  -H 'content-type: application/json' \
+  -H "authorization: Bearer $MCP_OAUTH_ACCESS_TOKEN" \
+  -d '{
+    "jsonrpc":"2.0",
+    "id":1,
+    "method":"tools/call",
+    "params":{
+      "name":"read_account",
+      "arguments":{"accountId":"acct-1"}
+    }
+  }'
+```
+
+Expected behavior:
+
+| State | REST | MCP |
+| --- | --- | --- |
+| valid user credential, `accounts:read`, active membership | `200` target result | JSON-RPC `result` |
+| missing/invalid credential | `401` | OAuth layer rejects the request |
+| verified caller missing user or `accounts:read` | `403` | JSON-RPC error with `error.data.code = "AUTH_DENIED"` |
+| membership revoked while credential remains valid | `402` | JSON-RPC error with `error.data.code = "ENTITLEMENT_REQUIRED"` |
+| MCP bearer missing the resource-level `mcp` scope | n/a | HTTP `403` plus `WWW-Authenticate: ... insufficient_scope` |
+
+`tools/list` includes `read_account` only on the public surface selected by its
+MCP Trigger. The standard Tool schema remains standard: required scopes and
+guard metadata are described in text, while every `tools/call` re-evaluates
+the manifest predicates and guard. Staff Views are listed/callable only on the
+staff MCP surface; discovery is never the enforcement boundary.
+
+## OAuth resource primitives
+
+When one Mantle site is an OAuth client of another, request a stable RFC 8707
+resource and use standard `offline_access` when refresh is needed:
+
+```ts
+const clientAuth = createAuth({
+  // database, baseURL, secret, other methods...
+  methods: [{
+    kind: "oauth",
+    providerId: "mantle-platform",
+    clientId: env.PLATFORM_CLIENT_ID,
+    discoveryUrl: "https://platform.example.com/api/auth/.well-known/openid-configuration",
+    scopes: ["openid", "offline_access", "accounts:read"],
+    resource: "https://api.example.com",
+  }],
+});
+
+const { accessToken, accessTokenExpiresAt, scopes } =
+  await clientAuth.getProviderAccessToken(request, "mantle-platform");
+```
+
+The server-side getter is bound to the current local session request and never
+returns a refresh token or account row. On the provider:
+
+```ts
+const providerAuth = createAuth({
+  // database, baseURL, secret, methods...
+  oauthProvider: {
+    loginPage: "/sign-in",
+    consentPage: "/consent",
+    scopes: ["openid", "offline_access", "accounts:read"],
+    validAudiences: ["https://api.example.com"],
+  },
+});
+
+const verification = await providerAuth.verifyOAuthAccessToken(request, {
+  audience: "https://api.example.com",
+  scopes: ["accounts:read"],
+});
+```
+
+The verifier accepts JWT access tokens only and checks the configured issuer,
+JWKS/signature, audience, time claims, and required scopes. It returns only
+`userId`, `clientId`, `credentialId`, and scopes. Opaque tokens are rejected;
+there is no introspection fallback.
+
+## OpenAPI reflection
+
+Emit only the schemes the deployed REST mount actually accepts:
+
+```ts
+import { EmitOpenapiUseCase } from "@aotter/mantle/spec";
+
+const { document } = EmitOpenapiUseCase.run({
+  manifests,
+  title: "Site API",
+  version: "1.0.0",
+  security: {
+    sessionCookie: false,
+    oauthBearer: {
+      openIdConnectUrl:
+        "https://platform.example.com/api/auth/.well-known/openid-configuration",
+    },
+    apiKey: { in: "header", name: "X-API-Key" },
+    personalToken: { bearerFormat: "PAT" },
+  },
+});
+```
+
+Anonymous operations have no security requirement. Protected operations use
+configured scheme alternatives, OAuth scopes derive from repeated
+`ctx.auth.scope` predicates, and guard-backed targets advertise `402`. Cookie
+sessions are represented as cookies, never mislabeled as bearer tokens.
+
+## Runnable contract check
+
+The integration fixture uses mutable, consumer-owned credential and
+entitlement fakes. It proves this sequence for one Procedure over REST and MCP:
+
+```text
+grant -> REST succeeds -> MCP succeeds
+revoke entitlement while credential remains valid
+-> next REST call is 402 -> next MCP call is ENTITLEMENT_REQUIRED
+```
+
+Run the guide/contract and normalization checks from the Mantle repository:
+
+```bash
+pnpm --filter @aotter/mantle-cloudflare exec vitest run \
+  test/authorization-integration.test.ts \
+  test/resolve-caller.test.ts \
+  test/mount-http-trigger-auth.test.ts
+```
+
+`authorization-integration.test.ts` also asserts that this shipped guide still
+contains all four scenarios and the exact public API names used by the fixture.
+The package typecheck catches changes to those APIs; the integration test
+catches changes to REST/MCP enforcement and mutable guard behavior.

package/docs/auth-hosting-model.md

@@ -118,9 +118,24 @@ GitHub OAuth token is still Landing-owned unless a separate token
 handoff design is introduced.
 
 The generated site's hosted-auth client code belongs in the starter or
-a starter overlay. Core owns only the auth contract, manifest/runtime
-identity vocabulary (`ctx.user`, `ctx.staff`), and curated Better Auth
-server primitives.
+a starter overlay. Core owns only the auth contract, normalized
+manifest/runtime credential vocabulary (`ctx.user`, `ctx.staff`, `ctx.auth`),
+guard orchestration, and curated Better Auth server primitives.
+
+## API and MCP Authorization
+
+Login hosting and business API authorization are related but separate. Core
+provides a normalized verified-credential context (`ctx.auth`), closed scope
+predicates, one Cloudflare consumer credential resolver seam, and a
+Procedure-backed guard that REST and MCP both execute. A generated site owns
+API keys, personal tokens, grants, transactions, subscriptions, and the guard
+handler that checks current business state.
+
+Mantle Platform may be the identity or OAuth token authority for a hosted
+flow. That does not make token claims the generated site's live membership or
+entitlement authority. The target site's guard reads its authoritative state
+on every call. See [API and MCP authorization](api-mcp-authorization.md) for
+the exact public API and four consumer examples.
 
 ## SDK Surface Rule
 
@@ -135,5 +150,14 @@ The current first-party SSO use case justifies these optional fields on
 - `crossSubDomainCookies`
 - `cookiePrefix`
 
-All three are additive. Existing generated sites that do not pass them
-keep their previous cookie and session behavior.
+The cross-site API use case additionally justifies these curated fields and
+facades:
+
+- generic OAuth method `resource`
+- OAuth provider `validAudiences`
+- `Auth.getProviderAccessToken(request, providerId)`
+- `Auth.verifyOAuthAccessToken(tokenOrRequest, { audience, scopes })`
+
+All are additive. Existing generated sites that do not pass them keep their
+previous cookie, session, and REST behavior. These are not a raw Better Auth
+options passthrough.

package/docs/design-atoms.md

@@ -338,6 +338,12 @@ names — `page` / `show` / `cursor` — must NOT appear in
 `spec.params.properties` (the parser rejects with
 `VIEW_PARAMS_RESERVED_NAME`).
 
+Views may declare the same `requires.auth.all` predicates and optional
+`requires.guard.procedure` as Procedures. Static auth runs before parameter
+validation; the guard receives validated params and authorizes the whole
+query. It does not rewrite SQL or filter individual rows. REST and MCP View
+calls share this path.
+
 Response envelope:
 
 ```json
@@ -405,10 +411,33 @@ sdk.registerHandler("send-contact-message", sendContactMessage);
 **v0.1 `requires.auth`**: `{ all: [<predicate>] }` only. Predicates:
 - `ctx.user` — caller is any signed-in end-user
 - `ctx.staff: [<role>, ...]` — caller is staff in one of these roles
+- `ctx.auth` — caller supplied any adapter-verified credential
+- `ctx.auth.scope: <scope>` — verified credential carries the exact opaque,
+  consumer-owned scope; repeat to require multiple scopes
 
 Anything beyond this (`any:`, `owns:`, `withinMinutes:`, `contains:`,
 `requires.window`, `requires.quota`, `errors`, `retry`) is DRAFT.
 
+Both Procedures and Views may add one dynamic guard beside `auth`:
+
+```yaml
+requires:
+  auth:
+    all:
+      - ctx.auth
+      - { "ctx.auth.scope": "orders:read" }
+  guard:
+    procedure: require-active-access
+```
+
+The guard is an ordinary declared `handler.kind: ref` Procedure. It receives
+the validated target input/View params and the same `HandlerContext`; success
+permits the target. Any guard diagnostic, invalid output, missing handler, or
+throw fails closed. Guards cannot be builtin, self-referential, or guarded
+themselves. Current payments, membership, and entitlement state belongs in
+the consumer guard handler, not in a new atom or Core repository. See
+[API and MCP authorization](api-mcp-authorization.md).
+
 **v0.1.0 `handler.kind`**: `ref` (author-supplied function) or
 `builtin` (SDK-supplied CRUD shortcut). For `builtin`, declare
 `op: <create | update | upsert | delete>` and `schema: <Schema name>`
@@ -450,14 +479,14 @@ The same Procedure can have multiple Triggers — that's how it becomes
 handler logic. Each transport is one Trigger; the Procedure body is
 shared.
 
-**v0.1.0 `Trigger.source.kind`**: `http` (public endpoint) or
-`lifecycle` (entry-writer hook). For `lifecycle`, declare `schema`,
+**v0.1 `Trigger.source.kind`**: `http` (public endpoint), `mcp` (named
+tool on `surface: public | staff`), or `lifecycle` (entry-writer hook). For `lifecycle`, declare `schema`,
 `on: [<hook>, ...]` from `LifecycleHook`, and optional `errorPolicy`
 (`abort` rejects only on `before_*` hooks; `continue` is the default).
 Lifecycle hooks are wired through `LifecycleHookingEntryRepository`, so
 MCP, admin, and builtin write paths share the same hook behavior.
 
-- `mcp` / `cron` / `queue` are **DRAFT (v0.2+)** — speculative, gated by
+- `cron` / `queue` are **DRAFT (v0.2+)** — speculative, gated by
   concrete consumer demand. Same appendix § "DRAFT (v0.2+)."
 
 The state-machine "lifecycle" from the Schema atom
@@ -494,13 +523,20 @@ Mapping:
   OpenAPI Operation Object at `path` + `method`
 - The target Procedure's `input` → OpenAPI request body schema
 - The target Procedure's `output` → OpenAPI 200 response schema
-- `requires.auth.all: [{ ctx.staff: [<roles>] }]` → OpenAPI `security`
-  with role names as scopes
+- configured cookie, OAuth bearer, API-key, and personal-token schemes →
+  accurate OpenAPI `security` alternatives for auth-gated targets
+- repeated `ctx.auth.scope` predicates → OAuth scopes plus
+  `x-mantle-required-scopes`
+- `requires.guard.procedure` → `x-mantle-guard-procedure` plus a `402`
+  response
 - Error code → HTTP status mapping (below) → OpenAPI 4xx/5xx response
   shapes
 
-MCP tool definition emission is deferred to v0.2+ when
-`Trigger.source.kind: mcp` lands.
+MCP Procedure tools emit from `Trigger.source.kind: mcp`; Views emit on their
+declared surface. Catalog filtering is discovery UX only. Every `tools/call`
+re-runs static auth and the dynamic guard. Required scopes/guard behavior stay
+in the standard Tool description rather than a non-standard required-scopes
+field.
 
 ## Manifest validation — JSON Schema in, zod at runtime
 
@@ -537,6 +573,7 @@ different constraints.
 | `INPUT_VALIDATION_FAILED` | `400` | Procedure input fails zod-converted schema |
 | `UNAUTHENTICATED` | `401` | no active session (admin API: missing/expired session cookie) |
 | `AUTH_DENIED` | `403` | `requires.auth` predicate evaluated false (or admin: caller lacks required staff role) |
+| `ENTITLEMENT_REQUIRED` | `402` | consumer guard denies current payment/membership/transaction entitlement |
 | `NOT_FOUND` | `404` | resource not found — admin: approval id; runtime: View name at `/api/views/<name>` |
 | `HANDLER_NOT_REGISTERED` | `500` | `handler.ref` key not registered at boot |
 | `DISPATCHER_NOT_BUILT` | `501` | runtime feature not implemented in this SDK build |
@@ -553,10 +590,11 @@ Additional runtime codes activate as future grammar surfaces (e.g.
 
 ## RBAC — what v0.1 ships, what's DRAFT
 
-v0.1 covers the staff-RBAC half: `requires.auth.all` with `ctx.user` /
-`ctx.staff: [<roles>]` predicates as the auth gate on Procedures.
-That's enough for "staff-only", "logged-in-only", and role-gated
-Procedures.
+v0.1 auth gates use `requires.auth.all` with `ctx.user`,
+`ctx.staff: [<roles>]`, `ctx.auth`, and `ctx.auth.scope` predicates on
+Procedures and Views. This covers staff-only, logged-in-only,
+credential-protected, and delegated-scope targets. One Procedure-backed guard
+handles mutable consumer business state without widening the static grammar.
 
 **Not yet shipped** (DRAFT):
 - Row-level read visibility (private posts, friend-only audiences)
@@ -579,8 +617,10 @@ sub-specs in the DRAFT spec. See "Future grammar" appendix.
 4. **What invokes them?** → `Trigger` per source. Multiple Triggers
    can target the same Procedure (HTTP + MCP + cron, all on one
    handler).
-5. **Who's allowed?** → `Procedure.spec.requires.auth` for now.
-   Row-level and field-level rules arrive with future grammar.
+5. **Who's allowed?** → `Procedure/View.spec.requires.auth` for static
+   identity/scope; optional `requires.guard.procedure` for one live,
+   consumer-owned business check. Row-level and field-level rules remain
+   future grammar.
 
 If you find yourself wanting a 5th kind, **stop**. Sketch the same
 thing as a composition of the four; almost always it works.
@@ -751,6 +791,13 @@ Grammar lives in v0.1.0. Runtime is the
 stamping and `input ∩ Schema.properties` projection. Full shape lives
 further down.
 
+#### `Trigger.source.kind: mcp` and shared authorization
+
+An MCP Trigger binds a declared Procedure to either the public or staff MCP
+surface. Procedures/Views share `ctx.auth`/scope predicates and optional guard
+orchestration across REST and MCP. Staff role is loaded live for each protected
+call; staff Views remain absent and un-callable on public MCP.
+
 ### v0.1.x committed
 
 > The `handler.kind: builtin` and `Trigger.source.kind: lifecycle`
@@ -904,7 +951,7 @@ validator rejects with `DRAFT_KEY_USED`.
 - Filter AST extension: `contains` (array containment), `not`, `in`, `like`.
 
 #### Procedure future
-- **`requires.auth.{any | all}`** with disjunction; predicate
+- **`requires.auth.any`** with disjunction; the shipped `all` predicate
   vocabulary extends to `owns: { schema, idFrom }`, `contains: {
   schema, idFrom, field, valueFrom }`.
 - **`requires.window.{withinMinutes, column?}`** — temporal
@@ -920,8 +967,6 @@ validator rejects with `DRAFT_KEY_USED`.
   error otherwise).
 
 #### Trigger future
-- **`source.kind: mcp`** — MCP tool exposure. Same Procedure becomes
-  an LLM-callable tool by adding a Trigger.
 - **`source.kind: cron`** with `expr:` — scheduled invocation.
 - **`source.kind: queue`** — async fan-out / message-driven invocation.
 - **`source.kind: lifecycle.foo`** — DRAFT extensions to the v0.1.x
@@ -942,7 +987,8 @@ to a committed roadmap.)
   declaration when projection Triggers ship.
 
 #### Cross-cutting future
-- **Closed `ctx.*` predicate identity**: v0.1 `{ user, staff }`
+- **Closed `ctx.*` predicate identity**: v0.1 `{ user, staff, auth,
+  auth.scope }`
   extends to `{ ..., system }` when SDK-internal Trigger executor
   paths land. Multi-tenant deployments would add `{ tenant }` via
   grammar-revise round if/when that product shape is pursued. New

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aotter/mantle",
-  "version": "0.0.11-alpha.47",
+  "version": "0.0.11-alpha.49",
   "description": "Umbrella entry for @aotter/mantle. Adopters install this one package and import from subpaths: /spec, /runtime, /cloudflare, /admin-ui. Sub-packages remain individually installable on npm for tooling / alt-adapter authors. The Netlify adapter ships as a private workspace stub in v0.1 — its subpath will be added when the impl lands in v0.2.",
   "license": "Apache-2.0",
   "homepage": "https://mantle.tools/",
@@ -47,10 +47,10 @@
     "README.md"
   ],
   "dependencies": {
-    "@aotter/mantle-admin-ui": "0.0.11-alpha.47",
-    "@aotter/mantle-spec": "0.0.11-alpha.47",
-    "@aotter/mantle-runtime": "0.0.11-alpha.47",
-    "@aotter/mantle-cloudflare": "0.0.11-alpha.47"
+    "@aotter/mantle-admin-ui": "0.0.11-alpha.49",
+    "@aotter/mantle-cloudflare": "0.0.11-alpha.49",
+    "@aotter/mantle-runtime": "0.0.11-alpha.49",
+    "@aotter/mantle-spec": "0.0.11-alpha.49"
   },
   "peerDependencies": {
     "@cloudflare/workers-oauth-provider": "^0.8.0",

package/skills/extend/SKILL.md

@@ -26,6 +26,7 @@ Closed enums (`x-mantle-bind` values, `ctx.*` predicates, `Trigger.source.kind`,
 | "I want CAPTCHA / Slack notify on submit"  | + Procedure (handler.kind: ref) + Trigger (lifecycle before_/after_create) |
 | "I want a /search page filtered by tag"    | View with params: { tag } |
 | "I want a public prompt-generator / calculator / configurator page" | A consumer-side `app.get(...)` route in `src/index.ts` — see § Custom public routes |
+| "I want an API key / personal token / paid API / scoped MCP tool" | Procedure/View `requires.auth` plus optional `guard.procedure`; site-owned resolver/handler — see § API and MCP authorization |
 | "I want a /docs/<slug>/edit-history page"  | Defer — v0.1 ships `simple` lifecycle only; `editorial` is v0.1.x |
 | "I want comments"                          | v0.1: anonymous-with-email pattern (Schema + write Procedure). End-user member system is v0.2. |
 
@@ -146,6 +147,43 @@ pnpm mcp-smoke         # 12 cases against /mcp
 
 If you added a new MCP-relevant Schema, the per-collection authoring tools (`create_draft_<segment>`, `update_draft_<segment>`) auto-emit; verify with `tools/list`.
 
+## API and MCP authorization
+
+Read the shipped canonical guide before adding an authenticated public API:
+
+<https://raw.githubusercontent.com/aotter/mantle/develop/docs/api-mcp-authorization.md>
+
+Use only the closed grammar:
+
+```yaml
+requires:
+  auth:
+    all:
+      - ctx.auth
+      - { "ctx.auth.scope": "orders:read" }
+  guard:
+    procedure: require-active-access
+```
+
+- `ctx.auth` means any adapter-verified credential; it is not API-key-only.
+- Repeat `ctx.auth.scope` to require multiple site-owned scopes.
+- Use `ctx.user` as well when a user subject is required.
+- Put current payment, transaction, membership, ownership, or other business
+  state in one site-owned `handler.kind: ref` guard Procedure. It receives the
+  validated target input/params and the same `HandlerContext`.
+- Put API-key/PAT recognition, hashing, revocation, and normalization in the
+  Cloudflare `credentialResolver`. Do not add Core tables, repositories, or a
+  generic entitlement layer.
+- Bind the same Procedure to HTTP and MCP Triggers when both transports should
+  expose it. Standard remote MCP uses OAuth; it does not promise to send a raw
+  REST API key/PAT. Runtime predicates and the guard are shared after caller
+  normalization.
+
+Expected diagnostics are `UNAUTHENTICATED`/401 for no valid credential,
+`AUTH_DENIED`/403 for a verified caller missing role/scope, and
+`ENTITLEMENT_REQUIRED`/402 when a site guard denies current access. Re-run the
+guide's focused integration command after changing manifests or auth wiring.
+
 ## Custom public routes (consumer-app freedom)
 
 The starter owns its `Hono` app instance. If the user wants a public surface that doesn't fit the 4-atom model — a prompt generator, calculator, configurator, starter directory browser, small interactive widget — add a route directly in `src/index.ts`:
@@ -202,7 +240,9 @@ Production fix: iterate every published entry and call `runtime.requestPublish.e
 - Don't add a Schema-level public-read flag (`Schema.spec.expose.rest` etc) — public reads always go through Views.
 - Don't add a non-`$param` filter sentinel (`{ $env: ... }`, `{ $cookie: ... }`, `{ $now }`) — none are in v0.1.
 - Don't bypass the chokepoint by writing to D1 directly — every mutation MUST go through `runtime.entries` (lifecycle hooks fire there).
-- Don't use `Trigger.source.kind: cron / mcp / queue` — DRAFT, parser rejects.
+- Don't use `Trigger.source.kind: cron / queue` — DRAFT, parser rejects. MCP is
+  shipped; declare `source: { kind: mcp, surface: public | staff }` and bind it
+  to a declared Procedure.
 - Don't use `Procedure.spec.requires.window` / `.quota` — DRAFT.
 - Don't write a Procedure with `handler.kind: builtin` and `op: archive` on a `lifecycle: simple` Schema — boot rejects (archive is editorial-only).
 - Don't paste secrets into a manifest (`requires.auth.all` carries predicates only). Secrets go in `wrangler secret put`.