@aotter/mantle 0.2.0-alpha.6 → 0.2.0-alpha.8

package/docs/examples/commerce.md

@@ -1,254 +0,0 @@
----
-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

@@ -1,238 +0,0 @@
----
-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