@quickback-dev/cli 0.72.3 → 0.72.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/index.js +1 -1
- package/dist/skill/docs/configure/agents.md +156 -2
- package/dist/skill/docs/configure/tenant-databases.md +53 -7
- package/dist/skill/docs/define/areas.md +3 -1
- package/dist/skill/docs/define/fga.md +220 -23
- package/dist/skill/docs/platform/auth/plugins/aws-ses.md +25 -0
- package/dist/skill/docs/platform/webhooks/outbound.md +1 -0
- package/dist/skill/docs/ui/account/hooks.md +5 -2
- package/package.json +1 -1
- package/src/skill/docs/configure/agents.md +156 -2
- package/src/skill/docs/configure/tenant-databases.md +53 -7
- package/src/skill/docs/define/areas.md +3 -1
- package/src/skill/docs/define/fga.md +220 -23
- package/src/skill/docs/platform/auth/plugins/aws-ses.md +25 -0
- package/src/skill/docs/platform/webhooks/outbound.md +1 -0
- package/src/skill/docs/ui/account/hooks.md +5 -2
|
@@ -110,6 +110,31 @@ Missing keys fall through to the built-in defaults from the vendored plugin (`sr
|
|
|
110
110
|
|
|
111
111
|
> **Provider scope.** Overrides are only honored when `email.provider: 'aws-ses'`. The Cloudflare Email path uses the helper's own template pipeline and ignores `plugins.emailOtp.templates`.
|
|
112
112
|
|
|
113
|
+
### OTP Message Headers
|
|
114
|
+
|
|
115
|
+
Every emailOTP send — default or custom template — carries two headers:
|
|
116
|
+
|
|
117
|
+
| Header | Value | Why |
|
|
118
|
+
|--------|-------|-----|
|
|
119
|
+
| `Auto-Submitted` | `auto-generated` | [RFC 3834](https://www.rfc-editor.org/rfc/rfc3834): machine mail, so vacation responders and ticketing systems don't reply to it. |
|
|
120
|
+
| `OTP-Token` | `"<otp>"; origin="<origin of APP_URL, else ACCOUNT_URL>"` | [draft-goto-otp-token](https://www.ietf.org/archive/id/draft-goto-otp-token-01.html): the code in machine-readable, origin-bound form, so a mail client can offer it only on the site that asked for it. Omitted when the origin is not `http(s)`. |
|
|
121
|
+
|
|
122
|
+
`OTP-Token` is an individual Internet-Draft, not a standard. Gmail's "Copy code" button currently finds codes heuristically, so keep the code near the top of both the HTML and text parts as well.
|
|
123
|
+
|
|
124
|
+
A template can add, replace or drop headers by returning `headers` next to `{ subject, html, text }`. A `null` value removes a default:
|
|
125
|
+
|
|
126
|
+
```typescript
|
|
127
|
+
// quickback/email-templates/sign-in.ts — bind the code to the app the user signs in on
|
|
128
|
+
export default ({ otp, appName, appOrigin }: { otp: string; appName: string; appOrigin: string }) => ({
|
|
129
|
+
subject: `Sign in to ${appName}`,
|
|
130
|
+
html: `<p>Your code: <b>${otp}</b></p>`,
|
|
131
|
+
text: `Your code: ${otp}`,
|
|
132
|
+
headers: { 'OTP-Token': `"${otp}"; origin="${appOrigin}"` },
|
|
133
|
+
});
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
(`appOrigin` here comes from a [`resolve-email-context` hook](/ui/account/hooks), which receives `env`.) Header names the sender owns — `From`, `To`, `Cc`, `Bcc`, `Reply-To`, `Subject`, `Date`, `Message-ID`, `MIME-Version`, `Content-*`, `Resent-*`, `Return-Path`, `Received`, `DKIM-Signature` — are ignored, and so is any value that is not one line of printable ASCII. A send with headers goes out through SES `SendRawEmail` (the simple `SendEmail` action cannot set them); sends without headers are unchanged.
|
|
137
|
+
|
|
113
138
|
## Configuration
|
|
114
139
|
|
|
115
140
|
The compiler wires the plugin into `src/lib/auth.ts` automatically. The generated `getSESConfig(env)` maps environment to the vendored plugin's options:
|
|
@@ -330,6 +330,7 @@ dead letter queue) is identical across providers.
|
|
|
330
330
|
## See Also
|
|
331
331
|
|
|
332
332
|
- [Inbound Webhooks](/platform/webhooks/inbound) — Receive webhooks from external services
|
|
333
|
+
- [MCP Events](/configure/agents#mcp-events) — ChatGPT subscriptions that ride this store and queue
|
|
333
334
|
- [Queues](/platform/queues) — Background processing infrastructure
|
|
334
335
|
|
|
335
336
|
## Standard Webhooks signing
|
|
@@ -34,7 +34,7 @@ Each file has a single default export — an `async (entity, ctx) => ...` functi
|
|
|
34
34
|
| `after-admin-user-create.ts` | `databaseHooks.user.create.after` (filtered) | `User` | `void` |
|
|
35
35
|
| `before-invitation-create.ts` | `organizationHooks.beforeCreateInvitation` | `{ invitation, inviter, organization }` | `void \| { data?: Partial<Invitation> }` |
|
|
36
36
|
| `resolve-oauth-context.ts` | OAuth bearer middleware | OAuth identity + session | Partial `AppContext` tenant fields |
|
|
37
|
-
| `resolve-email-context.ts` | emailOTP `sendVerificationOTP` | `{ email, type, name }` | Extra fields merged into the email template context |
|
|
37
|
+
| `resolve-email-context.ts` | emailOTP `sendVerificationOTP` | `{ email, type, name, env }` | Extra fields merged into the email template context |
|
|
38
38
|
| `before-auth-request.ts` | `hooks.before` (every auth endpoint) | `(ctx, env, { APIError })` | `void` — throw an `APIError` to refuse |
|
|
39
39
|
| `after-auth-request.ts` | `hooks.after` (every auth endpoint) | `(ctx, env)` | `void` — failures are logged, never thrown |
|
|
40
40
|
|
|
@@ -178,7 +178,7 @@ add `quickback/hooks/resolve-email-context.ts`. The emailOTP send calls it for
|
|
|
178
178
|
each recipient and **spreads the returned object into your email templates**.
|
|
179
179
|
|
|
180
180
|
```ts title="quickback/hooks/resolve-email-context.ts"
|
|
181
|
-
export default async ({ email, type, name, db, schema, eq, and }) => {
|
|
181
|
+
export default async ({ email, type, name, env, db, schema, eq, and }) => {
|
|
182
182
|
// Is this recipient a member of any organization?
|
|
183
183
|
const [u] = await db.select({ id: schema.user.id })
|
|
184
184
|
.from(schema.user).where(eq(schema.user.email, email)).limit(1);
|
|
@@ -208,6 +208,9 @@ Notes:
|
|
|
208
208
|
fixed signature; convert a type to a [custom template](/platform/auth/plugins/aws-ses#per-type-template-overrides) to consume the extra context.
|
|
209
209
|
- `db`, `schema`, `eq`, and `and` are passed in (the same Drizzle handle Better
|
|
210
210
|
Auth uses) so you can look the recipient up without an import.
|
|
211
|
+
- `env` is the Worker's bindings, so the context can carry environment-specific
|
|
212
|
+
values — e.g. the origin a template binds its
|
|
213
|
+
[`OTP-Token` header](/platform/auth/plugins/aws-ses#otp-message-headers) to.
|
|
211
214
|
- This is **not** a Better Auth `databaseHook` — it's consumed only by the
|
|
212
215
|
emailOTP send, so it adds no signup/session latency.
|
|
213
216
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@quickback-dev/cli",
|
|
3
|
-
"version": "0.72.
|
|
3
|
+
"version": "0.72.4",
|
|
4
4
|
"description": "CLI for Quickback — define your backend in TypeScript, compile to a fully wired Cloudflare Worker (or Bun / Node) with auth, database, migrations, security, CMS, and Account UI.",
|
|
5
5
|
"author": "Kardoe Incorporated <paul@kardoe.com>",
|
|
6
6
|
"license": "MIT",
|
|
@@ -14,7 +14,7 @@ When `agents` is enabled (the default), the Worker serves:
|
|
|
14
14
|
| `GET /.well-known/oauth-authorization-server` | [RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414) authorization-server metadata. When the `oauthProvider` plugin is enabled it **delegates to Better Auth's real OAuth 2.1 surface** (`/oauth2/authorize`, `/oauth2/token`, `/oauth2/register` dynamic client registration, PKCE); otherwise it advertises only the truthful token-mint subset. |
|
|
15
15
|
| `GET /.well-known/api-catalog` | [RFC 9727](https://datatracker.ietf.org/doc/html/rfc9727) catalog linking at `/openapi.json`. Same [`openapi.publish`](/api/openapi#the-publish-gate) gate as the spec. |
|
|
16
16
|
| `GET /.well-known/mcp.json` | MCP Server Card — discoverable metadata for the MCP server below. |
|
|
17
|
-
| `POST /mcp` | Auto-generated MCP-over-HTTP server. One tool per OpenAPI operation, JWT auth forwarded through the same middleware as the REST API. |
|
|
17
|
+
| `POST /mcp` | Auto-generated MCP-over-HTTP server. One tool per OpenAPI operation, JWT auth forwarded through the same middleware as the REST API. With [`agents.mcp.events`](#mcp-events), also the event catalogue and webhook subscriptions ChatGPT's MCP Events use. |
|
|
18
18
|
| `POST <path>` + `GET /.well-known/oauth-protected-resource<path>` | One per [named MCP server](#named-mcp-servers) (`agents.mcp.servers`) — a curated tool set with its own OAuth resource URL. |
|
|
19
19
|
|
|
20
20
|
## Default behavior
|
|
@@ -260,7 +260,9 @@ export default defineConfig({
|
|
|
260
260
|
| `name` | No | Server title (`serverInfo.title`). Defaults to `<project> (<key> MCP)`; `serverInfo.name` is `<project>-<key>`. |
|
|
261
261
|
| `instructions` | No | Returned from `initialize` as the server's `instructions`. |
|
|
262
262
|
| `requireAuth` | No | Challenge anonymous callers with `401`. Defaults to `agents.mcp.requireAuth`. Setting it on any server force-enables `oauthProvider` + `bearer`, without changing the default `/mcp` challenge. |
|
|
263
|
+
| `lane` | No | `'staff'` (default) or `'attendee'`. An attendee server runs every request with no organization and no org roles, and confines OAuth tokens to its own audience. See [Attendee servers](#attendee-servers). |
|
|
263
264
|
| `publicUrl` | No | A vanity URL for the server — see [below](#public-urls-on-a-vanity-host). |
|
|
265
|
+
| `events` | No | Event names from the [`agents.mcp.events`](#mcp-events) catalogue this server lists and accepts subscriptions for. Omitted: the server serves no events. An unknown name fails the compile. |
|
|
264
266
|
|
|
265
267
|
The selection is fixed at compile time. A tool name or group the generated API doesn't have **fails the compile** with a suggestion (`unknown tool "events__selfRsvp". Did you mean "agenda_items__selfRsvp"?`), and so does a selection that ends up empty or an override for an unselected tool.
|
|
266
268
|
|
|
@@ -340,9 +342,36 @@ These fail the compile:
|
|
|
340
342
|
- a tool `ui` naming an undeclared resource
|
|
341
343
|
- a resource that no tool references
|
|
342
344
|
|
|
343
|
-
>
|
|
345
|
+
> On a staff server (the default), an access token minted for a named server is accepted anywhere this Worker accepts its own OAuth tokens, exactly like a `/mcp` token: the curated list decides what the model is offered, not what the token can reach. Every call still runs the full security pipeline. To confine a server's tokens, make it an [attendee server](#attendee-servers).
|
|
344
346
|
|
|
345
347
|
|
|
348
|
+
### Attendee servers
|
|
349
|
+
|
|
350
|
+
Set `lane: 'attendee'` on a server whose callers act only through a relationship to one record (an event's guests, a project's clients) and must never bring their organization role with them:
|
|
351
|
+
|
|
352
|
+
```ts title="quickback.config.ts"
|
|
353
|
+
agents: {
|
|
354
|
+
mcp: {
|
|
355
|
+
servers: {
|
|
356
|
+
guest: {
|
|
357
|
+
path: '/guest/mcp',
|
|
358
|
+
lane: 'attendee',
|
|
359
|
+
tools: { include: ['agenda_items__listMyAgenda', 'agenda_items__selfRsvp'] },
|
|
360
|
+
},
|
|
361
|
+
},
|
|
362
|
+
},
|
|
363
|
+
},
|
|
364
|
+
```
|
|
365
|
+
|
|
366
|
+
Two rules apply, enforced by a middleware that runs right after authentication, so after every credential lane and after the `resolve-oauth-context` hook. Nothing later can raise the lane again.
|
|
367
|
+
|
|
368
|
+
1. **No organization authority on the server.** Every request on it runs with `activeOrgId`, `activeTeamId`, `roles`, `orgRole` and `tierRoles` cleared and `userRole: 'user'`. That covers the MCP request itself and every tool it dispatches. It applies however the caller authenticated (OAuth, session bearer, JWT or API key). The context also carries `ctx.mcpLane = 'attendee'`. Scoped roles (`scope:<kind>:<role>`) are resolved per request from the path, so they are the only authority an attendee server's tools see. A staff member who is also an event guest gets exactly a guest's access there.
|
|
369
|
+
2. **OAuth tokens are confined by audience.** A token minted for the attendee server's URL (its path URL or its `publicUrl`) is refused with `401 invalid_token` everywhere else: `/api`, `/mcp` and other named servers. A token minted for any other audience is refused on the attendee server. That `401` names the server's protected-resource metadata, so a client can re-authorize for the right resource. A token whose `aud` lists both kinds keeps its staff authority on staff surfaces and is lowered on the attendee server.
|
|
370
|
+
|
|
371
|
+
Tool calls are tied to their server by the internal request object the MCP dispatcher builds, not by a header. A request from outside the Worker can't claim to be one. Instance-bound tokens ([Instance-bound OAuth tokens](/define/scopes#instance-bound-oauth-tokens)) are already confined to their instance and are left as they are.
|
|
372
|
+
|
|
373
|
+
Projects without an attendee server compile byte-identically.
|
|
374
|
+
|
|
346
375
|
### Public URLs on a vanity host
|
|
347
376
|
|
|
348
377
|
`publicUrl` serves the same server at a second URL on a host of your choosing, e.g. `https://mcp.attend.vip/guest`:
|
|
@@ -397,8 +426,133 @@ curl -X POST https://my-api.example.com/mcp \
|
|
|
397
426
|
|
|
398
427
|
The server speaks the **Streamable HTTP** MCP transport — JSON-RPC 2.0 over `POST`. A plain `GET /mcp` returns the server info document for sanity checks.
|
|
399
428
|
|
|
429
|
+
Two protocol revisions are served on the same endpoint:
|
|
430
|
+
|
|
431
|
+
| Revision | How a client negotiates |
|
|
432
|
+
|----------|-------------------------|
|
|
433
|
+
| `2026-07-28` | `server/discover` (no handshake), then `io.modelcontextprotocol/protocolVersion` in every request's `_meta`. Results carry `resultType: "complete"`, the server identity in `_meta`, and `ttlMs` / `cacheScope` on catalogue results. |
|
|
434
|
+
| `2025-03-26` | `initialize` / `notifications/initialized`. Results keep their historical shape. |
|
|
435
|
+
|
|
436
|
+
A `_meta` version outside that list is refused with JSON-RPC error `-32022` and `data.supported`. ChatGPT requires the `2026-07-28` revision for [MCP Events](#mcp-events).
|
|
437
|
+
|
|
400
438
|
The MCP route does **not** emit its own CORS headers. The Worker's existing `cors()` middleware applies uniformly, so browser-origin access is governed by the same allowlist as the rest of the API (`auth.trustedOrigins` + the deploy origin). Server-to-server clients (Claude Desktop, Cursor, MCP Inspector) connect with a Bearer token and don't need browser CORS at all. If you want a browser-based MCP client (ChatGPT, Claude.ai) to connect cross-origin, add its origin to `auth.trustedOrigins` like any other web client.
|
|
401
439
|
|
|
440
|
+
## MCP Events
|
|
441
|
+
|
|
442
|
+
ChatGPT's **MCP Events** lets a user say "watch this project for new tasks and open a draft for each one": ChatGPT subscribes through your MCP server, you POST a signed webhook to its callback when the event fires, and the chat acts on it. `agents.mcp.events` builds the catalogue and the subscription endpoints; the generated Worker does the rest.
|
|
443
|
+
|
|
444
|
+
Requires outbound webhooks — `webhooksBinding` on the database provider — because subscriptions and deliveries live in the webhooks store and ride the webhooks queue. The compile fails without it.
|
|
445
|
+
|
|
446
|
+
```ts title="quickback.config.ts"
|
|
447
|
+
import { defineConfig } from '@quickback/compiler';
|
|
448
|
+
|
|
449
|
+
export default defineConfig({
|
|
450
|
+
name: 'my-api',
|
|
451
|
+
// …
|
|
452
|
+
agents: {
|
|
453
|
+
mcp: {
|
|
454
|
+
events: {
|
|
455
|
+
// Resource events: <table>.created / .updated / .deleted from every
|
|
456
|
+
// write through the audit-wrapped db. Table jsNames, as in feature().
|
|
457
|
+
resources: ['tasks', 'comments'],
|
|
458
|
+
// Custom events your own code emits with emitMcpEvent().
|
|
459
|
+
custom: {
|
|
460
|
+
'build.finished': {
|
|
461
|
+
description: 'A build finished and its artefacts can be downloaded.',
|
|
462
|
+
filters: { project_id: { description: 'Only builds of this project.' } },
|
|
463
|
+
payloadSchema: {
|
|
464
|
+
type: 'object',
|
|
465
|
+
properties: { project_id: { type: 'string' }, build_id: { type: 'string' }, status: { type: 'string' } },
|
|
466
|
+
required: ['project_id', 'build_id', 'status'],
|
|
467
|
+
},
|
|
468
|
+
},
|
|
469
|
+
},
|
|
470
|
+
// Subscription lifetime bounds (ms). Defaults: 15 min / 24 h / 7 days.
|
|
471
|
+
ttl: { minMs: 900_000, defaultMs: 86_400_000, maxMs: 604_800_000 },
|
|
472
|
+
},
|
|
473
|
+
},
|
|
474
|
+
},
|
|
475
|
+
});
|
|
476
|
+
```
|
|
477
|
+
|
|
478
|
+
### The catalogue
|
|
479
|
+
|
|
480
|
+
`events/list` returns one definition per event with `inputSchema` (the filters a subscription may set) and `payloadSchema` (the delivered `data`). It is access-filtered like `tools/list`.
|
|
481
|
+
|
|
482
|
+
**Resource events.** Each table in `resources` gets `<table>.created`, `<table>.updated` and `<table>.deleted`:
|
|
483
|
+
|
|
484
|
+
- **Gate.** The table's `read.access`. A caller who cannot list the table does not see its events and cannot subscribe to them.
|
|
485
|
+
- **Filters.** `id` plus every foreign-key column (`projectId`, `documentId`, …). The filter values are compared as strings against the written row.
|
|
486
|
+
- **Scope.** The table must be organization- or owner-scoped; a subscription created inside organization `org_1` receives only `org_1` rows, and an owner-scoped subscription receives only the subscriber's rows. A table with neither column fails the compile.
|
|
487
|
+
- **Payload.** `{ id, operation, <scope column>, <foreign keys…> }` — a summary, never the row. The receiving agent reads the record with the table's get tool, so masking and access apply exactly as on REST. A soft delete arrives as `<table>.deleted`.
|
|
488
|
+
- **Source.** The audit-wrapped `db` chokepoint, after the write commits: CRUD routes, actions, cron, queue and email handlers all count. Inside `db.transaction()` the occurrences wait for the commit and are dropped on rollback. The write must use `.returning()` — without rows there is no id to send, so the generated CRUD routes emit and a bare `db.delete(...)` does not.
|
|
489
|
+
|
|
490
|
+
**Custom events.** Keyed by name (`<noun>.<verb>`, lowercase). Every `filters` entry becomes an optional string argument matched against the same-named field of the emitted `data`. The gate is "any authenticated caller". A custom name that equals a resource event fails the compile.
|
|
491
|
+
|
|
492
|
+
### Emitting a custom event
|
|
493
|
+
|
|
494
|
+
{/* doc-compile: skip — imports the generated lib, which only exists inside a compiled project */}
|
|
495
|
+
```ts
|
|
496
|
+
import { emitMcpEvent } from '../lib/mcp-events';
|
|
497
|
+
|
|
498
|
+
// Exactly one scope, like emitWebhookEvent: the organization the subscriber
|
|
499
|
+
// was in when they subscribed, or the owning user. An unscoped emit throws.
|
|
500
|
+
await emitMcpEvent(
|
|
501
|
+
'build.finished',
|
|
502
|
+
{ project_id: build.projectId, build_id: build.id, status: 'passed' },
|
|
503
|
+
{ organizationId: ctx.activeOrgId! },
|
|
504
|
+
env,
|
|
505
|
+
);
|
|
506
|
+
```
|
|
507
|
+
|
|
508
|
+
The name must be declared under `custom`; the data must satisfy your `payloadSchema` (the compiler does not check it at runtime). The function returns the number of subscriptions the occurrence was queued for.
|
|
509
|
+
|
|
510
|
+
### Subscription lifecycle
|
|
511
|
+
|
|
512
|
+
| Method | Behaviour |
|
|
513
|
+
|--------|-----------|
|
|
514
|
+
| `events/subscribe` | Validates the event, arguments, `delivery.url` (https, public — the same [anti-SSRF policy](/platform/webhooks/outbound#url-validation-anti-ssrf) as webhook endpoints) and `delivery.secret` (`whsec_` + 24–64 base64 bytes). Verifies the callback with a signed challenge, then stores or refreshes the subscription. Returns `{ id, refreshBefore, cursor: null, truncated: false }`. |
|
|
515
|
+
| `events/unsubscribe` | Deletes the matching subscription. Idempotent. |
|
|
516
|
+
|
|
517
|
+
- **Identity** is `(principal, callback URL, event, arguments)`; the `id` is derived from it and arguments are canonicalised, so re-subscribing refreshes instead of duplicating. The principal is the authenticated user, or the delegated principal on a `principals:` lane.
|
|
518
|
+
- **Verification** POSTs `{ "type": "verification", "challenge": "…" }` signed with the new secret and expects a `2xx` `{ "challenge": "…" }` echo. A successful verification is cached per (principal, URL) for 7 days. A failure returns JSON-RPC error `-32015` with `data.reason` (`challenge_failed`, `timeout`, `connection_refused`, `http_4xx`, `http_5xx`, `http_3xx`).
|
|
519
|
+
- **Lifetime.** `ttlMs` is clamped into `[minMs, maxMs]`; an omitted `ttlMs` gets `defaultMs`; `ttlMs: null` gets `maxMs`. `refreshBefore` is never `null` — a subscription always expires, and delivery stops when it does. ChatGPT refreshes by calling `events/subscribe` again before `refreshBefore`; the refresh re-runs the access gate, which is where revoked access is caught.
|
|
520
|
+
- **Secret rotation.** A refresh with a new secret signs the next 10 minutes of deliveries with both secrets, space-separated.
|
|
521
|
+
- **No replay.** `cursor` is always `null`; events missed while a subscription was expired are not recoverable.
|
|
522
|
+
|
|
523
|
+
Other errors: `-32602` invalid params, `-32023` unknown event or subscription (`data.kind`), `-32024` not authenticated or no active organization for an organization-scoped event, `-32026` a delivery mode other than `webhook` (`data.feature: "deliveryMode"`).
|
|
524
|
+
|
|
525
|
+
### Delivery
|
|
526
|
+
|
|
527
|
+
One event per request, signed in the [Standard Webhooks](https://www.standardwebhooks.com) format with the subscription's secret:
|
|
528
|
+
|
|
529
|
+
| Header | Value |
|
|
530
|
+
|--------|-------|
|
|
531
|
+
| `webhook-id` | The body's `eventId` (`evt_…`), stable across retries |
|
|
532
|
+
| `webhook-timestamp` | Signing time, Unix seconds — fresh per attempt |
|
|
533
|
+
| `webhook-signature` | `v1,<base64 HMAC-SHA256>`, two entries during a rotation window |
|
|
534
|
+
| `X-MCP-Subscription-Id` | The `id` from `events/subscribe` |
|
|
535
|
+
|
|
536
|
+
```json
|
|
537
|
+
{
|
|
538
|
+
"eventId": "evt_8f3c…",
|
|
539
|
+
"name": "tasks.created",
|
|
540
|
+
"timestamp": "2026-10-29T12:05:00.000Z",
|
|
541
|
+
"data": { "id": "tsk_42", "operation": "created", "organizationId": "org_1", "projectId": "prj_7" },
|
|
542
|
+
"cursor": null
|
|
543
|
+
}
|
|
544
|
+
```
|
|
545
|
+
|
|
546
|
+
Deliveries are `webhook_deliveries` rows (`endpoint_id` is the subscription id) processed by the webhooks queue consumer, with the same backoff as [outbound webhooks](/platform/webhooks/outbound#delivery-and-retry). Differences from endpoint deliveries:
|
|
547
|
+
|
|
548
|
+
- A body over 256 KiB is not sent; the delivery is marked `failed`.
|
|
549
|
+
- `410` revokes the subscription; `413` and any redirect fail the delivery without retry.
|
|
550
|
+
- The destination is re-checked against the anti-SSRF policy before every attempt, and redirects are never followed.
|
|
551
|
+
|
|
552
|
+
### Limits
|
|
553
|
+
|
|
554
|
+
Polling and streaming delivery, replay cursors, and the draft's `gap` / `terminated` control envelopes are not implemented. Access revoked mid-lifetime is enforced at the next refresh, so the subscription TTL bounds the window — shorten `ttl.maxMs` if that window matters.
|
|
555
|
+
|
|
402
556
|
## Verification
|
|
403
557
|
|
|
404
558
|
After you deploy, scan both the REST and MCP surfaces:
|
|
@@ -669,6 +669,13 @@ loaded table's firewall) and the per-lane scope refresh run against tenant
|
|
|
669
669
|
SQLite exactly as on a single Worker. A namespace request costs one RPC (the
|
|
670
670
|
forward) plus, for a session caller, one lookup read in D1.
|
|
671
671
|
|
|
672
|
+
A forwarded [share-link principal](/define/fga#landing-on-a-record-action)
|
|
673
|
+
is routed the same way, by the instance id in the path. The gate admits it
|
|
674
|
+
only for the link's own scope instance, in the object of the link's
|
|
675
|
+
organization, on a route that admits links of its object type (the landing);
|
|
676
|
+
it holds no roles and proves no lane, and `ctx.lane` is `'link'`. Anywhere
|
|
677
|
+
else under the prefix the request runs as the caller the link replaced.
|
|
678
|
+
|
|
672
679
|
A claimed table's [legacy forward](/define/areas#keeping-the-old-url-legacy)
|
|
673
680
|
(`legacy`) is not a namespace route. The edge routes its old URL
|
|
674
681
|
(`/api/v1/locations`) by **active organization**, exactly as it routed the
|
|
@@ -2175,24 +2182,63 @@ applies the same check to every operation.
|
|
|
2175
2182
|
With [`authz.fga`](/define/fga), `fga_tuples` is a table of every organization's
|
|
2176
2183
|
object. It is not in the platform D1.
|
|
2177
2184
|
|
|
2178
|
-
- `ctx.fga` (`check`, `listObjects`, `expand`, `read`, `write
|
|
2179
|
-
|
|
2180
|
-
in the
|
|
2181
|
-
|
|
2185
|
+
- `ctx.fga` (`check`, `listObjects`, `expand`, `read`, `write`, and
|
|
2186
|
+
[`share`](/define/fga#minting-from-an-action-ctxfgashare) with link
|
|
2187
|
+
sharing) exists in the actions of tenant features, for every principal the
|
|
2188
|
+
edge admitted to the object: a member whose active organization it is, a
|
|
2189
|
+
caller a [namespace](#tenant-namespaces) lane proved with no organization
|
|
2190
|
+
seat, a share-link principal. The object is the organization. A delete is
|
|
2191
|
+
visible to the next check.
|
|
2182
2192
|
- The edge hydrates no `ctx.fga`. It forwards `/fga/v1/*` to the caller's
|
|
2183
2193
|
organization object, like a tenant route (no organization: `400 TENANT_REQUIRED`).
|
|
2184
2194
|
- Tuples never cross organizations. Two organizations can hold tuples for the
|
|
2185
2195
|
same object id, and each sees only its own.
|
|
2196
|
+
- `access: { fga }` arms are allowed on tenant tables: their reads, views,
|
|
2197
|
+
writes and record actions run in the object, where the gate finds the
|
|
2198
|
+
tuples. A platform table, a partitioned feature, a room binding and
|
|
2199
|
+
`realtime.wsTicket` still cannot carry one.
|
|
2200
|
+
|
|
2201
|
+
### Share links
|
|
2202
|
+
|
|
2203
|
+
[Link subjects](/define/fga#link-subjects-linkid) work tenant-local: a link's
|
|
2204
|
+
row in `fga_share_links` and its tuple live in the organization object, next
|
|
2205
|
+
to the object they protect, and the lifecycle triggers (object delete or
|
|
2206
|
+
move, parent delete, fresh insert) run there, in the tenant migration set.
|
|
2207
|
+
The edge keeps the share router (`/share/v1/open`, `exchange`, `link`) and the
|
|
2208
|
+
`x-share-token` / `qb_share` middleware, and resolves a credential in two
|
|
2209
|
+
steps:
|
|
2210
|
+
|
|
2211
|
+
1. The token's stored hash is looked up in the compiler-owned hashed lookup
|
|
2212
|
+
`__fgaShareLink` (`tenancy.lookups` semantics: the platform D1 holds
|
|
2213
|
+
`HMAC(TENANT_LOOKUP_KEY, "__fgaShareLink\0<hash>")`, a hash of a hash;
|
|
2214
|
+
`TENANT_LOOKUP_KEY` becomes a required secret). The lookup converges
|
|
2215
|
+
after the minting object's next response, like every lookup.
|
|
2216
|
+
2. One command, `qb.shareLinkResolve`, runs in that object: the row by hash
|
|
2217
|
+
or id, live, its tuple still present, a `scope:<kind>:<role>` creator
|
|
2218
|
+
re-proven against the relationship row (one row, this organization), and
|
|
2219
|
+
the `fields` projection of the object. The `org` creator edge (Better
|
|
2220
|
+
Auth membership) is proven on the edge. A cookie carries the organization
|
|
2221
|
+
id, so a cookie request routes with no lookup.
|
|
2222
|
+
|
|
2223
|
+
The link principal is forwarded like any other; the tenant Worker applies it
|
|
2224
|
+
only on a route whose access has an `fga` arm for the link's object type and
|
|
2225
|
+
runs every other route as the caller it replaced. Inside the object the token
|
|
2226
|
+
is stored as `SHA-256(token)`: the object holds no secret, and a 256-bit
|
|
2227
|
+
random token needs no key. Signed `user:*` share tokens do not exist in this
|
|
2228
|
+
mode (`POST /fga/v1/share` on a `user:*` relation is `400`, a `GET
|
|
2229
|
+
/share/v1/<token>` with one is `404`); `user:*` tuples remain writable with
|
|
2230
|
+
`ctx.fga`. The link resource tables must be tenant tables.
|
|
2186
2231
|
|
|
2187
2232
|
These shapes are refused, because each would read or write tuples from
|
|
2188
2233
|
somewhere other than the organization object:
|
|
2189
2234
|
|
|
2190
2235
|
| Code | Cause |
|
|
2191
2236
|
|---|---|
|
|
2192
|
-
| `TENANCY_FGA_SHARING` | `authz.fga.sharing` is set
|
|
2237
|
+
| `TENANCY_FGA_SHARING` | `authz.fga.sharing` is set but the model declares no `link` subjects. Signed `user:*` tokens are verified on the edge against tuples it does not hold. Declare `type link` and list it on the shared relations. |
|
|
2193
2238
|
| `TENANCY_FGA_MEMBERSHIP` | `authz.fga.membership` is set. Those tuples are written from Better Auth hooks on the edge. Write the tuples from a tenant action instead. |
|
|
2194
|
-
| `TENANCY_FGA_ACCESS_ARM` | A table, action, room binding or `realtime.wsTicket` declares an `access: { fga }` arm. Call `ctx.fga.check(...)` in a tenant action instead. |
|
|
2239
|
+
| `TENANCY_FGA_ACCESS_ARM` | A platform table, a partitioned feature's table, a standalone action, a room binding or `realtime.wsTicket` declares an `access: { fga }` arm. Only a tenant table's reads, views, writes and record actions are gated in the organization object. Call `ctx.fga.check(...)` in a tenant action instead. |
|
|
2195
2240
|
| `TENANCY_FGA_MIXED` | A platform feature's action, or an action in a [partitioned](#partitions) feature, reads `ctx.fga`. A partition object's database holds no tuples. |
|
|
2241
|
+
| `TENANCY_LOOKUP` | `tenancy.lookups.__fgaShareLink` is declared by the project; the name is compiler-owned. |
|
|
2196
2242
|
|
|
2197
2243
|
Moving to `'durable-object'` does not copy the tuples already in the features
|
|
2198
2244
|
D1. `fga_tuples` leaves the platform schema, so the next generated D1
|
|
@@ -2257,7 +2303,7 @@ organization's object before you apply that migration.
|
|
|
2257
2303
|
| `TENANCY_TENANT_WORKER_CHANGED` | A deployed edge (per the existing `wrangler.toml`) would bind a different tenant Worker than it does now. See [Two Workers](#two-workers). |
|
|
2258
2304
|
| `TENANCY_ENVIRONMENT_WORKER` / `TENANCY_ENVIRONMENT_SHARED` / `TENANCY_ENVIRONMENT_BACKUP` | A named environment has no `tenantWorker.name`, shares a tenant Worker or backup bucket with another target, or names a tenant Worker like an edge or files Worker. A target that does not deploy as the project `name` reuses the single-target tenant Worker or bucket. A Worker takes a reserved `<name>-unselected`, `<name>-files-unselected` or `<name>-tenant-unselected` placeholder name. `backupBucketName` is missing while `tenancy.backup` is set, or set while it is not. See [Named environments](#named-environments). |
|
|
2259
2305
|
| `TENANCY_PURGE_DO` / `TENANCY_CHANGES` / `TENANCY_FGA` | `tenancy.purge`, `changes`, or a top-level `fga` block (declare it at `authz.fga`) together with `isolation: 'durable-object'`. |
|
|
2260
|
-
| `TENANCY_FGA_SHARING` / `TENANCY_FGA_MEMBERSHIP` / `TENANCY_FGA_ACCESS_ARM` / `TENANCY_FGA_MIXED` | An FGA shape that would reach tuples from outside the organization object. See [FGA](#fga). |
|
|
2306
|
+
| `TENANCY_FGA_SHARING` / `TENANCY_FGA_MEMBERSHIP` / `TENANCY_FGA_ACCESS_ARM` / `TENANCY_FGA_MIXED` | An FGA shape that would reach tuples from outside the organization object: sharing without `link` subjects, derived membership, an `fga` arm off a tenant table, `ctx.fga` off the organization object. See [FGA](#fga). |
|
|
2261
2307
|
|
|
2262
2308
|
|
|
2263
2309
|
### Fence a result job to an authorization epoch
|
|
@@ -609,7 +609,9 @@ Hydration is **per matched lane**: each lane fills `ctx.<its own exposeAs>` from
|
|
|
609
609
|
|
|
610
610
|
The gate stamps **`ctx.lane`** on every request it admits: the lane that let
|
|
611
611
|
the caller in — a relationship lane's name, `'roles'` for a `{ roles }` lane,
|
|
612
|
-
`'team'` for `{ team: true }
|
|
612
|
+
`'team'` for `{ team: true }`, `'link'` for a
|
|
613
|
+
[share link](/define/fga#landing-on-a-record-action) landing on its own
|
|
614
|
+
instance. The bulk-grant role check runs before the
|
|
613
615
|
relationship probes and short-circuits them, so an org admin who is *also* a
|
|
614
616
|
named organizer is admitted as `'roles'`, and nothing records the organizer
|
|
615
617
|
relationship. A body that needs to know ("may this admin also act as the
|