@aotter/mantle 0.1.4 → 0.2.0-alpha.1

package/docs/examples/commerce.md

@@ -0,0 +1,254 @@
+---
+description: A published product catalog and guest orders written by SQL Procedures, with an optimistic-lock staff review. No stock authority, payments or handler code.
+---
+# Commerce catalog and orders
+
+[Examples hub](./README.md) · Stock authority, re-pricing on the server and a verified payment callback are [Commerce inventory](./commerce-inventory.md).
+
+Staff publish products, the public lists them, guests place orders, and staff
+mark orders fulfilled or cancelled. Every Procedure is SQL. The example does
+not reserve stock or talk to a payment provider.
+
+## Problem
+
+Staff publish products with a price. A guest places an order with customer
+fields, an order number, a currency, a total and line items. Staff see
+submitted orders and record fulfillment or cancellation. Two staff members must
+not overwrite each other's review.
+
+## Manifest
+
+```yaml
+apiVersion: cms.mantle.aotter.net/v2
+kind: Schema
+metadata: { name: products }
+spec:
+  title: Products
+  lifecycle: publishing
+  uniqueIndexes: [[slug]]
+  schema:
+    type: object
+    additionalProperties: false
+    required: [slug, title, priceMinor, currency]
+    properties:
+      slug: { type: string, maxLength: 120, pattern: "^[a-z0-9-]+$" }
+      title: { type: string, minLength: 1, maxLength: 160 }
+      summary: { type: string, maxLength: 500 }
+      priceMinor: { type: integer, minimum: 0, x-mcp-hint: money-minor }
+      currency: { type: string, pattern: "^[A-Z]{3}$" }
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: Schema
+metadata: { name: orders }
+spec:
+  title: Orders
+  description: Guest orders, written only by the declared Procedures.
+  lifecycle: operational
+  uniqueIndexes: [[orderNumber]]
+  indexes: [[orderStatus]]
+  searchableFields: [orderNumber, customerName, customerEmail]
+  schema:
+    type: object
+    additionalProperties: false
+    required: [orderNumber, orderStatus, currency, totalMinor, customerName, customerEmail, shippingAddress, items]
+    properties:
+      orderNumber: { type: string, minLength: 1, maxLength: 40 }
+      orderStatus: { type: string, enum: [submitted, fulfilled, cancelled] }
+      currency: { type: string, pattern: "^[A-Z]{3}$" }
+      totalMinor: { type: integer, minimum: 0, x-mcp-hint: money-minor }
+      customerName: { type: string, minLength: 1, maxLength: 120 }
+      customerEmail: { type: string, format: email }
+      shippingAddress: { type: string, minLength: 1, maxLength: 500 }
+      items:
+        type: array
+        minItems: 1
+        maxItems: 20
+        items:
+          type: object
+          additionalProperties: false
+          required: [productSlug, title, quantity, unitPriceMinor, lineTotalMinor]
+          properties:
+            productSlug: { type: string, maxLength: 120, pattern: "^[a-z0-9-]+$" }
+            title: { type: string }
+            quantity: { type: integer, minimum: 1, maximum: 99 }
+            unitPriceMinor: { type: integer, minimum: 0 }
+            lineTotalMinor: { type: integer, minimum: 0 }
+      trackingNumber: { type: string, maxLength: 120 }
+      cancelReason: { type: string, maxLength: 500 }
+---
+# A public View over a publishing Schema sees published rows only; the SQL does not repeat it.
+apiVersion: cms.mantle.aotter.net/v2
+kind: View
+metadata: { name: public-products }
+spec:
+  title: Public products
+  surface: public
+  sql: |
+    SELECT id, slug, title, summary, priceMinor, currency, updated_at
+    FROM products
+    ORDER BY slug LIMIT 100
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: View
+metadata: { name: submitted-orders }
+spec:
+  title: Submitted orders
+  surface: staff
+  requires: { auth: { all: [{ ctx.staff: [owner, editor] }] } }
+  sql: |
+    SELECT id, version, orderNumber, customerName, customerEmail, shippingAddress, totalMinor, currency, created_at
+    FROM orders
+    WHERE orderStatus = 'submitted'
+    ORDER BY created_at LIMIT 100
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: Procedure
+metadata: { name: place-order }
+spec:
+  title: Place order
+  description: Record a guest order as submitted.
+  input:
+    type: object
+    additionalProperties: false
+    required: [orderNumber, currency, totalMinor, customerName, customerEmail, shippingAddress, items]
+    properties:
+      orderNumber: { type: string, minLength: 1, maxLength: 40 }
+      currency: { type: string, pattern: "^[A-Z]{3}$" }
+      totalMinor: { type: integer, minimum: 0, x-mcp-hint: money-minor }
+      customerName: { type: string, minLength: 1, maxLength: 120 }
+      customerEmail: { type: string, format: email }
+      shippingAddress: { type: string, minLength: 1, maxLength: 500 }
+      items:
+        type: array
+        minItems: 1
+        maxItems: 20
+        items:
+          type: object
+          additionalProperties: false
+          required: [productSlug, title, quantity, unitPriceMinor, lineTotalMinor]
+          properties:
+            productSlug: { type: string, maxLength: 120, pattern: "^[a-z0-9-]+$" }
+            title: { type: string }
+            quantity: { type: integer, minimum: 1, maximum: 99 }
+            unitPriceMinor: { type: integer, minimum: 0 }
+            lineTotalMinor: { type: integer, minimum: 0 }
+  output: { type: object }
+  handler:
+    sql: |
+      INSERT INTO orders (orderNumber, orderStatus, currency, totalMinor, customerName, customerEmail, shippingAddress, items)
+      VALUES (input.orderNumber, 'submitted', input.currency, input.totalMinor, input.customerName,
+              input.customerEmail, input.shippingAddress, input.items)
+      RETURNING id, orderNumber AS "orderNumber"
+---
+# The version predicate is the optimistic lock: a stale expectedVersion matches no row, which is a CONFLICT.
+apiVersion: cms.mantle.aotter.net/v2
+kind: Procedure
+metadata: { name: review-order }
+spec:
+  title: Review order
+  description: Mark a submitted order fulfilled or cancelled, with the version the reviewer saw.
+  requires: { auth: { all: [{ ctx.staff: [owner, editor] }] } }
+  input:
+    type: object
+    additionalProperties: false
+    required: [id, expectedVersion, orderStatus]
+    properties:
+      id: { type: string }
+      expectedVersion: { type: integer, minimum: 1 }
+      orderStatus: { type: string, enum: [fulfilled, cancelled] }
+      trackingNumber: { type: string, maxLength: 120 }
+      cancelReason: { type: string, maxLength: 500 }
+  output: { type: object }
+  handler:
+    sql: |
+      UPDATE orders
+      SET orderStatus = input.orderStatus,
+          trackingNumber = COALESCE(input.trackingNumber, trackingNumber),
+          cancelReason = COALESCE(input.cancelReason, cancelReason)
+      WHERE id = input.id AND version = input.expectedVersion AND orderStatus = 'submitted'
+      RETURNING id, version, orderStatus AS "orderStatus"
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: Trigger
+metadata: { name: place-order-http }
+spec:
+  source: { kind: http, method: POST, path: /api/commerce/orders }
+  target: { procedure: place-order }
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: Trigger
+metadata: { name: place-order-mcp }
+spec:
+  source: { kind: mcp, surface: public }
+  target: { procedure: place-order }
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: Trigger
+metadata: { name: review-order-mcp }
+spec:
+  source: { kind: mcp, surface: staff }
+  target: { procedure: review-order }
+```
+
+Points worth noticing:
+
+- **`products` is `publishing`.** Staff create drafts and publish through
+  Admin's API (`POST /admin/api/entries`, then
+  `POST /admin/api/entries/{id}/publish`). SQL cannot set `status`, so
+  publishing is never a Procedure's `UPDATE`.
+- **The order status on create is a literal.** `place-order` writes
+  `'submitted'` itself, so no caller can insert a fulfilled order.
+- **`review-order` is a locked row op.** `WHERE id = … AND version = …` pins
+  one row, and a row op that writes nothing is `CONFLICT`. Its `target`
+  (`orders`, `id`, `expectedVersion`) is inferred from that `WHERE`.
+  `COALESCE` keeps a field the caller left out. The extra
+  `orderStatus = 'submitted'` means a reviewed order cannot be reviewed again.
+- **Line titles, unit prices and the total are what the caller sent.** This
+  example does not re-price or reserve stock.
+
+## Handlers
+
+None.
+
+## Try it
+
+```sh
+curl -sS 'http://127.0.0.1:8787/api/views/public-products?limit=20'
+
+curl -sS -X POST http://127.0.0.1:8787/api/commerce/orders \
+  -H 'content-type: application/json' \
+  -d '{"orderNumber":"MNT-20261001-1","currency":"TWD","totalMinor":2400,"customerName":"Ada","customerEmail":"ada@example.test","shippingAddress":"1 Shell Lane","items":[{"productSlug":"notebook","title":"Notebook","quantity":2,"unitPriceMinor":1200,"lineTotalMinor":2400}]}'
+```
+
+A duplicate `orderNumber` is HTTP 409 `CONFLICT`. Staff, on `/mcp/staff`,
+call `submitted_orders` and then:
+
+```json
+{
+  "jsonrpc": "2.0", "id": 2, "method": "tools/call",
+  "params": { "name": "review_order", "arguments": { "id": "<order id>", "expectedVersion": 1, "orderStatus": "fulfilled", "trackingNumber": "TEST-1" } }
+}
+```
+
+A second reviewer replaying `expectedVersion: 1` gets `CONFLICT`. A
+contributor gets `AUTH_DENIED`.
+
+| MCP surface | Tool | From |
+|---|---|---|
+| `/mcp` | `public_products` | the public View |
+| `/mcp` | `place_order` | the `place-order-mcp` Trigger |
+| `/mcp/staff` | `submitted_orders` | the staff View |
+| `/mcp/staff` | `review_order` | the `review-order-mcp` Trigger |
+
+## What this leaves out
+
+- **Stock authority.** Two orders for the last unit both succeed. See
+  [Commerce inventory](./commerce-inventory.md).
+- **Re-pricing.** The total is whatever the caller sent.
+- **Payments.** `submitted` is not `pending_payment`, and there is no provider
+  callback.
+
+## Source
+
+- [Schema](../handbook/reference/schema.md), [View](../handbook/reference/view.md) and [Procedure](../handbook/reference/procedure.md) references
+- [Lifecycle and locales](../handbook/concepts/lifecycle-and-locales.md): `publishing` and `operational`

package/docs/examples/guarded-api.md

@@ -0,0 +1,238 @@
+---
+description: Protect Views and Procedures with site-issued API keys, opaque scopes and a live entitlement guard, over REST and MCP.
+---
+# Guarded API access: API keys, scopes and entitlement
+
+[Examples hub](./README.md)
+
+Three access levels: anonymous, a verified credential with a scope, and a
+credential plus a live paid-state guard. Read it if other systems or agents
+call your service with keys instead of browser sessions.
+
+## Problem
+
+A service sells API access. Anyone may read the public catalog. Customers get
+API keys the service issues and stores itself; each key carries scopes such as
+`catalog:read` or `exports:read`. Some operations also need the customer's
+subscription to be paid right now, a fact that changes independently of the
+key. The same operation must be callable over REST and the public MCP surface
+with the same authorization. Mantle enforces; the service owns keys, scopes
+and billing.
+
+## Manifest
+
+```yaml
+apiVersion: cms.mantle.aotter.net/v2
+kind: Schema
+metadata: { name: catalog-items }
+spec:
+  title: Catalog items
+  lifecycle: publishing
+  uniqueIndexes: [[slug]]
+  schema:
+    type: object
+    additionalProperties: false
+    required: [slug, title, priceMinor]
+    properties:
+      slug: { type: string, maxLength: 120, pattern: "^[a-z0-9-]+$" }
+      title: { type: string, minLength: 1, maxLength: 160 }
+      priceMinor: { type: integer, minimum: 0, x-mcp-hint: money-minor }
+---
+# 1. Anonymous public read
+apiVersion: cms.mantle.aotter.net/v2
+kind: View
+metadata: { name: public-catalog }
+spec:
+  surface: public
+  description: The published catalog, for anyone.
+  sql: SELECT id, slug, title, priceMinor, updated_at FROM "catalog-items" ORDER BY title LIMIT 100
+---
+# 2. A verified credential with a scope. Views take the same `requires` as Procedures.
+apiVersion: cms.mantle.aotter.net/v2
+kind: View
+metadata: { name: partner-catalog }
+spec:
+  surface: public
+  description: The catalog with every field, for API keys with catalog:read.
+  requires: { auth: { all: [ctx.auth, { ctx.auth.scope: "catalog:read" }] } }
+  sql: SELECT id, slug, title, priceMinor, created_at, updated_at FROM "catalog-items" ORDER BY slug
+---
+# 3. A scope plus a live entitlement guard
+apiVersion: cms.mantle.aotter.net/v2
+kind: Procedure
+metadata: { name: require-active-api-access }
+spec:
+  input: { type: object }
+  output: { type: object }
+  handler: { ref: requireActiveApiAccess }
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: Procedure
+metadata: { name: download-export }
+spec:
+  title: Download export
+  description: Fetch a prepared export report; needs exports:read and active paid access.
+  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
+    required: [reportId]
+    properties:
+      reportId: { type: string }
+  handler: { ref: downloadExport }
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: Trigger
+metadata: { name: download-export-http }
+spec:
+  source: { kind: http, method: POST, path: /api/exports/download }
+  target: { procedure: download-export }
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: Trigger
+metadata: { name: download-export-mcp }
+spec:
+  source: { kind: mcp, surface: public }
+  target: { procedure: download-export }
+```
+
+The predicate vocabulary is closed and is evaluated against the `Caller` only:
+
+- `ctx.user` and `ctx.auth` both hold for any `user` caller, whatever its
+  credential (session, OAuth, API key or personal token). An anonymous or
+  system caller satisfies neither.
+- Each `ctx.auth.scope` names one opaque scope the caller must carry; repeat it
+  for several.
+- `guard.procedure` names one unguarded `ref` Procedure.
+
+The order is fixed: resolve the caller, check `requires.auth`, validate the
+input, run the guard, run the target. See the
+[authorization reference](../handbook/reference/authorization.md).
+
+## The caller resolver
+
+The service's entry resolves the caller once per request. The resolver
+`mantle generate` wrote (`createCallerResolver` from `@aotter/mantle/auth`)
+takes a `credentialResolver` for the service's own credential formats, and
+tries it before OAuth bearer tokens and sessions. The key table is the
+application's; Mantle neither creates nor reads it.
+
+```ts
+// src/apiKeys.ts
+import type { ConsumerCredentialResolution } from "@aotter/mantle/auth";
+
+interface KeyRow { readonly id: string; readonly account_id: string; readonly scopes_json: string; readonly revoked_at: string | null }
+
+export function siteApiKeys(db: D1Database) {
+  return async (request: Request): Promise<ConsumerCredentialResolution> => {
+    const raw = request.headers.get("x-api-key");
+    if (raw === null) return { kind: "not-handled" }; // a bearer token or a session may still be presented
+    const digest = [...new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(raw)))]
+      .map((b) => b.toString(16).padStart(2, "0")).join("");
+    const row = await db.prepare("SELECT id, account_id, scopes_json, revoked_at FROM site_api_keys WHERE token_sha256 = ?")
+      .bind(digest).first<KeyRow>();
+    const scopes: unknown = row ? JSON.parse(row.scopes_json) : null;
+    // a presented but unknown or revoked key is 401, never anonymous, and never falls back to a cookie
+    if (!row || row.revoked_at !== null || !Array.isArray(scopes)) return { kind: "invalid" };
+    return {
+      kind: "verified",
+      credential: {
+        credential: "api-key",
+        credentialId: row.id, // the record id, never the raw key
+        subject: `account:${row.account_id}`, // namespaced, so it never collides with a signed-in user's id
+        scopes: scopes.filter((s): s is string => typeof s === "string"),
+      },
+    };
+  };
+}
+```
+
+In `src/service.ts`, pass it to the generated resolver:
+
+```ts
+const resolver = createCallerResolver(auth, { jwtBearer: { audience: `${origin}/mcp`, scopes: ["mcp"] }, credentialResolver: siteApiKeys(env.DB) });
+```
+
+The key's caller is a `user` with that subject and its scopes. Its role is
+read like any user's, and an `account:` subject has none, so a key can never
+pass Admin's gate. Every surface already runs behind
+`withCaller(resolver, …)`, so REST, both MCP surfaces and Admin see the same
+caller. With identity `custom`, do the same inside your own `src/identity.ts`.
+
+## Handlers
+
+```ts
+// src/handlers.ts
+import { DiagnosticError, runtimeDiagnostic } from "@aotter/mantle";
+import type { MantleHandlers } from "../.mantle/generated/mantle.js";
+import type { Env } from "./service.js";
+
+export const handlers: MantleHandlers<Env> = {
+  requireActiveApiAccess: async (_input, ctx) => {
+    const account = ctx.caller.kind === "user" ? ctx.caller.subject : null;
+    const paid = account
+      ? await ctx.env.DB.prepare("SELECT 1 FROM site_api_entitlements WHERE account = ? AND state = 'paid'").bind(account).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 }),
+};
+```
+
+A guard receives the target's validated input and the same caller, reads only
+(its `ctx.store.write` and `ctx.invoke` fail), runs on every call and is never
+cached. A throw of any kind fails closed and the target never runs; only a
+`DiagnosticError` chooses the status.
+
+## Try it
+
+```sh
+curl -sS http://127.0.0.1:8787/api/views/public-catalog
+curl -sS http://127.0.0.1:8787/api/views/partner-catalog -H "x-api-key: $SITE_API_KEY"
+curl -i -X POST http://127.0.0.1:8787/api/exports/download \
+  -H 'content-type: application/json' -H "x-api-key: $SITE_API_KEY" -d '{"reportId":"report-1"}'
+```
+
+| Caller | HTTP | `error.code` |
+|---|---|---|
+| valid key, required scope, paid | 200 | — |
+| no credential, for a target that `requires` one | 401 | `UNAUTHENTICATED` |
+| a presented key that is unknown or revoked | 401 | `UNAUTHENTICATED`, before any surface runs |
+| valid key without the scope | 403 | `AUTH_DENIED` |
+| scoped key, no paid row | 402 | `ENTITLEMENT_REQUIRED` |
+
+Over MCP the same Procedure answers `download_export` with an error result
+carrying the same code. A standard MCP client authenticates with an OAuth
+bearer token from the service's authorization server; an agent holding an API
+key can send `x-api-key` instead, since `/mcp` sits behind the same resolver.
+`tools/list` shows `public_catalog`, `partner_catalog` and `download_export`.
+Listing is not enforcement: every call checks the predicates and the guard
+again.
+
+## What this leaves out
+
+Mantle does not issue or store keys, define a scope catalog, or read a payment
+provider.
+
+- **Key issuance.** Generating, hashing, showing once, rotating and revoking
+  keys is application code writing `site_api_keys`.
+- **Billing.** Whatever fills `site_api_entitlements` (a webhook, a sync, a
+  staff action) is outside the guard; the guard reads the current row.
+- **Personal tokens.** A token that acts as a signed-in user resolves to that
+  user's own subject key, with `credential: "personal-token"`, in the same
+  resolver.
+
+## Source
+
+- [Authorization](../handbook/concepts/authorization.md): `Caller`, `CallerResolver`, `withCaller`
+- [Authentication](../handbook/cloudflare/authentication.md): the generated resolver