@lowdefy/docs-content 0.0.0-experimental-20260928120643 → 6.1.0

package/content/user-authentication/mcp-oauth.md

@@ -1,292 +0,0 @@
-# MCP Server & OAuth
-
-A Lowdefy app can expose its API endpoints as tools to an MCP client — Claude, ChatGPT, an IDE assistant — over the Model Context Protocol. When those tools touch anything but public data, the client has to prove who is calling, and Lowdefy handles that by turning the app itself into an **OAuth 2.1 authorization server**: the assistant runs a normal browser authorization, the user signs in, chooses the organization to work in, and grants consent, and the app mints an access token the assistant sends on every tool call.
-
-This page is about the *authenticated* MCP surface. Exposing tools to an app's own agents, and the `mcp` array on an agent (the app acting as an MCP *client*), are covered in [MCP tools for agents](/agent-mcp-tools) and the [`Mcp` connection](/Mcp). Here the app is the *server*, and the caller is an outside assistant.
-
-## One resource, one address
-
-There is a single MCP resource for the whole deployment, served at `/api/mcp`. The organization a call acts in is **not** part of the address — it is chosen once during authorization and carried inside the access token as a claim. Every assistant connects to the same URL; two users, or one user in two organizations, are told apart by their tokens, never by the path.
-
-This is the Linear model — one link, the workspace is a property of the authorization rather than the address — and it is deliberate. An earlier design keyed the resource per organization (`/api/mcp/{organization_id}`); that put the organization in the URL, the RFC 8707 `resource` parameter, and the token audience, and needed a per-organization resource row kept in sync. The single resource deletes all of that: one address to paste, one audience, and the organization rides the token.
-
-| Route | Purpose |
-| ----- | ------- |
-| `POST /api/mcp` | The MCP resource — streamable HTTP transport. Tools are listed and called here, per request, authorized against the bearer token. |
-| `GET /.well-known/oauth-protected-resource/api/mcp` | RFC 9728 protected-resource metadata: the resource URI, the authorization server, and the scopes it supports. Public and constant per deployment. |
-| `GET /.well-known/oauth-authorization-server/api/auth` | RFC 8414 authorization-server metadata, re-exposed at the path a client derives from the issuer. |
-| `/api/auth/*` | The authorization server itself — authorize, token, registration, and the OAuth endpoints the consent and picker pages call. |
-
-The `/.well-known` documents derive their URIs from the pinned canonical URL (`BETTER_AUTH_URL`, else the current environment's `url`), never from a request `Host` header, so they are the same for every caller. They mount **only when `auth.oauthProvider` is configured** — an app that is not an authorization server has nothing to discover, and its MCP tools are all public (see the rule below).
-
-## Turning the app into an authorization server
-
-Add `auth.oauthProvider`. It names the two pages the browser authorization flow hands control to, and whether unknown clients may register themselves:
-
-```yaml
-auth:
-  oauthProvider:
-    consentPage: /oauth-consent
-    postLoginPage: /oauth-select-organization
-    dynamicClientRegistration: false
-```
-
-- **`consentPage`** *(required)* — the Lowdefy page id of your consent screen. The authorization flow redirects the signed-in user here to approve or deny the client. The engine builds the redirect as `${origin}${basePath}${consentPage}`, joined with no separator, so **the leading slash is required**.
-- **`postLoginPage`** — the page where a signed-in user chooses which organization the authorization acts in. It is shown after login and before consent. It is **required under `organizations.policy: tenant`** (the build fails without it) and is skipped under `pinned`, where there is only ever one organization to act in.
-- **`dynamicClientRegistration`** — allow unregistered MCP clients to self-register per RFC 7591. Off by default; pre-registered clients are the primary path. Turn it on for public assistants you cannot pre-register.
-
-Both page ids are validated at build time the same way: the page must exist, and it must not be public-listed in a way that would let it render without a session — the flow only ever reaches them for a signed-in user.
-
-## Exposing tools, and their scopes
-
-The app-level `mcp` block declares the server's identity and which API endpoints are tools:
-
-```yaml
-mcp:
-  name: acme
-  version: '1.0.0'
-  title: Acme
-  websiteUrl: https://acme.example.com
-  instructions: Search for a customer before creating an invoice for them.
-  icons:
-    - src: https://acme.example.com/icon-512.png
-      mimeType: image/png
-      sizes: ['512x512']
-  endpoints:
-    - id: search-customers
-      scope: mcp:read
-    - id: create-invoice
-      scope: mcp:write
-```
-
-`name`, `version`, `title`, `websiteUrl` and `icons` are the server branding a client shows the user in the `initialize` handshake. Each `endpoints` entry needs an `id` and a `scope`.
-
-`instructions` is an optional string sent in the `initialize` result. Clients such as Claude Code place it in the model's system prompt, so use it for a short note on how the tools fit together or when to reach for them. Clients may truncate long instructions, so keep it to a few lines. When it is not set, the server sends no instructions.
-
-**`scope` is a closed vocabulary — `mcp:read` or `mcp:write`, and nothing else.** Apps cannot mint their own scopes. `mcp:write` implies `mcp:read` at runtime, so a token granted write can call both. Tag a tool that only reads with `mcp:read` and one that mutates with `mcp:write`; the consent screen then lets a user grant an assistant read-only access to the whole surface if they choose.
-
-Three rules the build enforces on every tool:
-
-- **Only `Api` endpoints can be tools.** An `InternalApi` endpoint is not reachable as one — it has no external caller by design.
-- **Every tool needs a `description` and a `payloadSchema`.** The description is what the assistant reads to decide when to call the tool; the `payloadSchema` becomes the tool's input schema. A tool with neither is not a usable tool, so the build refuses it.
-- **The `mcp.agents` key is gone.** MCP agent tools are not supported; remove it if you are upgrading.
-
-## A tool is gated twice
-
-When a call arrives at `/api/mcp`, a tool is listed and callable only when **both** hold:
-
-1. the caller's **role outcome** allows the endpoint — the same `auth.api` / `auth.api.roles` gate every API call passes; and
-2. the **token's granted scope** covers the tool's tag.
-
-The 401 challenge is decided once, at the route boundary, before the MCP transport runs. Past that boundary the transport answers over HTTP 200, so a role or scope shortfall never surfaces as a `403` or an `insufficient_scope` error to the assistant — the tool is simply not offered. This is intentional: the tool surface does not disclose the existence of tools the caller may not use.
-
-## The rule that catches everyone: keep MCP endpoints out of `auth.api.public`
-
-> **Never list an MCP endpoint id in `auth.api.public`.**
-
-One public tool suppresses the 401 challenge for the *whole* route. The build sets `mcp.json`'s `hasPublicTool` flag when any exposed endpoint is public, and the `/api/mcp` route then serves an anonymous caller a `200` with the public tools instead of a `401` with the `WWW-Authenticate` challenge. A freshly added assistant reports "connected, 1 tool" and **never runs the OAuth flow** — only a *stale* token would take the challenge branch. Every protected tool then sits behind a door the client was never told to knock on.
-
-So a protected app keeps its `auth.api` gates and leaves every `mcp.endpoints` id out of the public list:
-
-```yaml
-auth:
-  api:
-    protected: true
-    # Keep MCP endpoint ids OUT of this list. A single public tool
-    # flips mcp.json hasPublicTool, and /api/mcp then serves anonymous
-    # callers a 200 with that tool instead of the 401 challenge.
-    public:
-      - webhooks/stripe   # a webhook receiver, not an MCP tool
-```
-
-The build has a matching guard from the other direction: a protected or role-gated MCP endpoint **requires** `auth.oauthProvider`. Without the authorization server there is no way to authenticate the caller, so the build fails rather than shipping an unreachable tool — make the endpoint public (accepting the trade above) or configure `oauthProvider`.
-
-## The authorization flow, end to end
-
-1. The assistant reads `/.well-known/oauth-protected-resource/api/mcp`, finds the authorization server, and (if it is not pre-registered and `dynamicClientRegistration` is on) registers itself.
-2. It opens a browser to the authorization endpoint. The user signs in through your normal sign-in page.
-3. **Under `tenant`,** the flow redirects to `postLoginPage`. The user picks the organization to work in; the page sets it active and continues the authorization. **Under `pinned`,** this step is skipped.
-4. The flow redirects to `consentPage`. The user approves the client and the requested scopes — or, if they have already consented for this client in this organization, consent is skipped.
-5. The app mints an access token whose **`organization_id` claim is the chosen organization** (the consent `referenceId`), and the assistant sends it as a `Bearer` token on every `/api/mcp` call.
-
-Consent is recorded per **(client, user, organization)**. Re-authorizing into an organization the user has already consented for skips the consent screen; a first authorization into a *different* organization asks for consent again, for that organization.
-
-### How a token becomes a caller
-
-On every `/api/mcp` request the token is verified in-process against the authorization server's own signing keys: the issuer and audience must match the resource, and the token must carry both a `sub` (the user) and an `organization_id` claim. The claim is not trusted on its own — the **consent row for `(client, user, organization)` must still exist**. That liveness read on every call is what makes switching and disconnecting take effect *immediately*: revoke the grant and the next call is refused at once, not at the token's expiry.
-
-The caller is then resolved as a member of that organization, exactly as a session caller is — same membership wall, same role source, same `_user` shape — with one extra field: **`_user.auth_method` is `'mcp'`**, so a routine can tell an assistant apart from a browser without any app-side plumbing.
-
-```yaml
-# In an endpoint routine, branch on how the caller arrived:
-- id: set_channel
-  type: SetState
-  params:
-    channel:
-      _if:
-        test:
-          _eq:
-            - _user: auth_method
-            - mcp
-        then: mcp
-        else: ui
-```
-
-A token that cannot be verified (for example, an opaque token minted because the client omitted the RFC 8707 `resource` parameter), one whose grant has been revoked, or one whose user is no longer a member of the token's organization (removed, left, or the user deleted), gets a `401` with a `WWW-Authenticate` challenge that tells the client what to do — reconnect and re-run the authorization, including the organization choice. The authorization server also refuses to refresh a grant whose user is no longer a member of its organization (`invalid_grant`), so a client holding a refresh token falls back to the full authorization instead of refreshing into another refused token.
-
-## Building the consent and picker pages
-
-Both pages are ordinary Lowdefy pages that read the authorization request from the URL query, show the user what is being asked, and finish the flow with client actions. Four actions do the work:
-
-| Action | What it does |
-| ------ | ------------ |
-| `ListOrganizations` | Returns the caller's organization memberships — the rows the picker renders. |
-| `SetActiveOrganization` | Sets the caller's active organization. The picker calls it for the chosen organization. |
-| `OAuthContinue` | Continues the authorization after the organization is chosen (`POST /api/auth/oauth2/continue`). Returns `{ url }` to redirect to. |
-| `OAuthConsent` | Approves (`accept: true`) or denies (`accept: false`) the client. Returns `{ url }` to redirect to. |
-
-### The organization picker (`postLoginPage`)
-
-On mount the page calls `ListOrganizations` and stores the rows in state; a `ListSelector` renders them, and its click handler sets the chosen organization active and continues:
-
-```yaml
-id: select_org_rows
-type: ListSelector
-properties:
-  selectable: false
-  hoverable: true
-  data:
-    _state: organizations
-events:
-  onClick:
-    - id: set_active_organization
-      type: SetActiveOrganization
-      skip:
-        _eq:
-          - _event: item.id
-          - _user: organization_id
-      params:
-        organizationId:
-          _event: item.id
-    - id: continue_authorization
-      type: OAuthContinue
-      messages:
-        error: false
-    - id: continue_redirect
-      type: Link
-      params:
-        url:
-          _actions: continue_authorization.response.url
-```
-
-`SetActiveOrganization` is skipped when the chosen organization is already the active one, so re-picking the current organization is a no-op that still continues the flow.
-
-### The consent screen (`consentPage`)
-
-Reads the request from the query, shows the client and scopes, and finishes on the user's decision:
-
-```yaml
-id: consent_allow
-type: Button
-properties:
-  title: Allow access
-events:
-  onClick:
-    - id: consent_allow_action
-      type: OAuthConsent
-      messages:
-        error: false
-      params:
-        accept: true
-    - id: consent_allow_redirect
-      type: Link
-      params:
-        url:
-          _actions: consent_allow_action.response.url
-```
-
-The deny button is identical with `params: { accept: false }`. Read `_url_query: client_id` and `_url_query: scope` to render what the client is asking for, and `_url_query: resource` to confirm the audience. Fetch the client's own metadata (name, logo) from `/api/auth/oauth2/public-client?client_id=...` to show a human-readable client name rather than an opaque id.
-
-## Switching organization from the assistant
-
-An assistant connected to one organization switches by *disconnecting* — the client then re-runs the authorization and the user picks a different organization. Expose a tool that revokes the calling grant with the `RevokeMcpGrant` step:
-
-```yaml
-id: switch-organization
-type: Api
-description: >
-  Disconnect this assistant from the organization it is connected to so
-  the user can connect it to another one. Use ONLY when the user asks to
-  work in a different organization. After it succeeds the connection is
-  gone: tell the user to reconnect in their assistant — the browser will
-  ask which organization to connect to.
-payloadSchema:
-  type: object
-  additionalProperties: false
-  properties: {}
-routine:
-  - id: revoke_grant
-    type: RevokeMcpGrant
-  - ':return':
-      disconnected: true
-      organization_id:
-        _step: revoke_grant.organizationId
-      message: >-
-        Disconnected. Ask the user to reconnect in their assistant.
-```
-
-[`RevokeMcpGrant`](/auth-steps) reads the calling token's `(client, user, organization)` from the request context, deletes that one consent row, and revokes its refresh tokens. It is **caller-scoped**: it touches only the grant the call arrived on, so another assistant the same person connected, or this assistant's grant in another organization, is untouched. It refuses to run for any caller that did not arrive over MCP — there is no grant behind a browser session for it to revoke.
-
-Expose it as an `mcp:read` tool. The next tool call the assistant makes gets a `401`, the client re-runs OAuth, and the user lands back on the organization picker.
-
-## Disconnecting assistants from the app
-
-The mirror control belongs in your app's UI: a person removing every assistant connected to their active organization. It deletes the caller's consent rows for that organization and revokes the matching refresh tokens — the same two writes `RevokeMcpGrant` makes, scoped to the active organization instead of one client:
-
-```yaml
-id: disconnect-assistants
-type: Api
-description: Disconnect every assistant connected to the caller's active organization.
-payloadSchema:
-  type: object
-  additionalProperties: false
-  properties: {}
-routine:
-  - id: revoke_refresh_tokens
-    type: MongoDBUpdateMany
-    connectionId: oauth-refresh-tokens
-    properties:
-      filter:
-        user_id:
-          _user: id
-        reference_id:
-          _user: organization_id
-        revoked: null
-      update:
-        $set:
-          revoked:
-            _date: now
-  - id: delete_consents
-    type: MongoDBDeleteMany
-    connectionId: oauth-consents
-    properties:
-      filter:
-        user_id:
-          _user: id
-        reference_id:
-          _user: organization_id
-  - ':return':
-      disconnected:
-        _step: delete_consents.deletedCount
-```
-
-Because the `/api/mcp` route reads the live consent row on every call, every affected assistant is refused on its next call, not at token expiry.
-
-## Summary
-
-- The app is an OAuth 2.1 authorization server; enable it with `auth.oauthProvider`.
-- There is one MCP resource at `/api/mcp`. The organization is a token claim, not a URL segment.
-- Tag each tool `mcp:read` or `mcp:write`; a tool is gated by both role and scope.
-- **Never list an MCP endpoint id in `auth.api.public`** — one public tool suppresses the challenge for the whole route.
-- Consent is per `(client, user, organization)` and read live on every call, so `RevokeMcpGrant` and disconnecting take effect immediately.
-- `_user.auth_method` is `'mcp'` for assistant callers.

package/content/user-authentication/organizations.md

@@ -1,221 +0,0 @@
-# Organizations & Multi-Tenancy
-
-Every Lowdefy app has organizations — always, even a single-team internal tool. A signed-in caller is a **member** of an organization, and it is the membership, not the user record, that carries the caller's app roles and per-organization attributes. This is the unit the whole auth system is built on: `_user.roles` is the active membership's roles, and the [tenant wall](#the-tenant-wall) scopes data to the active organization.
-
-The single knob that decides how organizations behave is `auth.organizations.policy`.
-
-## Two policies: `pinned` and `tenant`
-
-```yaml
-auth:
-  organizations:
-    policy: pinned   # or "tenant"
-```
-
-**`pinned`** *(the default)* — one organization for the whole deployment, ensured at startup. This is the shape for an internal app or a single-customer install: there is one workspace, everyone is a member of it, and the active organization is never switched. The organization plugin's per-organization routes (create, switch, self-service org management) are disabled.
-
-**`tenant`** — organizations are created per user, and a caller can belong to several and switch between them. This is the shape for a multi-tenant SaaS: each customer is an organization, members are invited into it, and `SetActiveOrganization` moves the caller between the workspaces they belong to.
-
-An app that sets nothing gets `pinned` with one auto-seeded organization, invite-only. The policy is not something you can leave to a default and change later without thought — it changes what `_user.organization_id` means, whether the tenant wall is active, and whether the MCP flow needs an [organization picker](/mcp-oauth). Choose it up front.
-
-## The `organizations` keys
-
-| Key | Type | Applies to | Default | Meaning |
-| --- | ---- | ---------- | ------- | ------- |
-| `policy` | `pinned` \| `tenant` | both | `pinned` | The organization model, above. |
-| `org` | string | **pinned only** | `default` | The slug the deployment pins as the active organization. Under `pinned` the slug **is** the organization's id. |
-| `signup` | `invite-only` \| `open` | both | `pinned` → `invite-only`, `tenant` → `open` | Whether uninvited sign-ups are admitted. `invite-only` refuses a sign-up with no invitation; `open` admits everyone. |
-| `create` | `auto` \| `operator` | **tenant only** | `tenant` → `auto` | How a tenant organization comes into being: `auto` mints one for a user at first session; `operator` leaves creation to your own config (the `CreateOrganization` step). |
-| `invitationExpiresIn` | integer (seconds, min 60) | both | `172800` (48h) | How long an invitation stays acceptable. Re-sending an invitation refreshes its expiry. |
-
-The build cross-checks these, and the errors are worth knowing before you hit them:
-
-- **`org` is required under `pinned`** and **rejected under `tenant`** — under `tenant` there is no single organization to pin; organizations are created per user.
-- **`create` is rejected under `pinned`** — the active organization is ensured at startup, so there is nothing to create on demand.
-- **Renaming `org` strands the existing membership.** The startup ensure is by slug, so changing `org` mints a *fresh* organization rather than renaming the old one, and every existing `member` row still points at the old id. Treat the pinned slug as permanent.
-
-Defaults line up with intent: `pinned` defaults to a closed, invite-only internal app; `tenant` defaults to self-serve SaaS (`signup: open`, `create: auto`).
-
-### The organization `create: auto` mints
-
-Under `tenant` with `create: auto`, the first session of a user who has no membership and no pending invitation mints the user's own organization, with the user as its `owner`, slugged `org-<userId>`. A user who later leaves their last organization gets a fresh one at their next session (`org-<userId>-2`, then `-3` and on). An organization the user was ever a member of is never handed back to them, even after every member has left it, so its data and pending invitations stay with it.
-
-The mint is safe when the same user signs in from two tabs at once or submits twice: exactly one organization and one `owner` membership are written. It relies on two unique indexes in the auth database, which the server creates at startup (and checks again before it mints):
-
-```js
-db['user-organizations'].createIndex({ slug: 1 }, { unique: true })
-db['user-members'].createIndex({ user_id: 1, organization_id: 1 }, { unique: true })
-```
-
-An equivalent unique index you created yourself, under any name, is accepted. If the auth database user may not create indexes, or the collections already hold duplicate rows, the server logs an error naming the index, and a sign-in that needs a new organization is refused with status 503 and the code `ORGANIZATION_SETUP_UNAVAILABLE` (existing members sign in as usual). The server tries again at most every 30 seconds while such sign-ins arrive, so removing the duplicates or creating the indexes by hand recovers without a restart.
-
-### Invitations for existing members
-
-An invitation is how someone joins an organization, never how a membership changes. Accepting an invitation into an organization you already belong to (you joined another way after it was sent) succeeds and marks the invitation accepted, but leaves your membership exactly as it is: the invitation's role, app roles and attributes are not applied, and no second membership is written. If your session had no active organization, the accepted organization becomes active. To change an existing membership, use the [auth steps](/auth-steps) (`UpdateMemberOrgRole`, `UpdateMemberRoles`, `UpdateMemberAttributes`), which check the caller's authority at the time of the change.
-
-## The `owner` / `admin` / `member` tier vs app roles
-
-A membership carries **two** independent role authorities, and keeping them apart is the whole point:
-
-- **`_user.org_roles`** — the organization tier: `owner`, `admin`, or `member`. This is BetterAuth's administrative fact about the membership, and it is what the [auth-step authority floor](/auth-steps) checks. **No page or API gate reads it.**
-- **`_user.roles`** — the app's own role strings, from the membership's `appRoles`. These are what [`auth.pages.roles` and `auth.api.roles`](/roles) match, and the only thing they match.
-
-So an app that wants a page for organization administrators does **not** gate it on the `admin` tier — it gates on one of its own app roles, and lets the write authority answer the administration question separately, at the step. See [Roles](/roles) for page and API gating, and [Auth Steps](/auth-steps) for the administration model.
-
-## Bootstrapping the first administrator
-
-Nothing grants organization authority implicitly — not even to the first user. On a fresh `pinned` + `invite-only` deployment that is a closed loop: nobody can invite (inviting needs authority nobody holds) and nobody can sign up (the gate admits only members and pending invitees). Breaking the loop is a single invitation document inserted by hand into the `user-invitations` collection, seeded with the `owner` tier. The full recipe — the exact document, why the key must be `_id`, why the role must be `owner`, and how to deliver the accept link — is in the [Auth Upgrade guide](/auth-upgrade#bootstrapping-the-first-administrator).
-
-## The tenant wall
-
-Under `policy: tenant`, data must not leak across organizations. The **tenant wall** enforces that mechanically: a scoping-capable connection is filtered to the caller's active organization on every read and stamped with it on every write, without the request author writing a single filter clause. The wall is declared **on the connection**; requests, steps and websockets only declare *exceptions*.
-
-### Declaring scope on a connection
-
-Under `tenant`, a connection whose type implements the scoping contract (MongoDB does) is **scoped by default** — silence means scoped. You only ever declare the two exceptions:
-
-```yaml
-connections:
-  # Scoped by default under tenant policy — nothing to declare.
-  - id: app_data
-    type: MongoDBCollection
-    properties:
-      databaseUri:
-        _secret: MONGODB_URI
-      collection: records
-
-  # Data deliberately shared across organizations (reference data,
-  # a global catalogue) — opt out of scoping explicitly.
-  - id: countries
-    type: MongoDBCollection
-    tenant: shared
-    properties:
-      databaseUri:
-        _secret: MONGODB_URI
-      collection: countries
-
-  # Scope on a field other than the default organization_id.
-  - id: legacy_records
-    type: MongoDBCollection
-    tenant:
-      field: tenant_id
-    properties:
-      databaseUri:
-        _secret: MONGODB_URI
-      collection: legacy
-```
-
-`tenant` on a connection is either the string `shared` or `{ field: <name> }` (a non-empty name with no dots). The default scoping field is `organization_id`. There is deliberately **no `tenant: true`** — under `tenant` policy a capable connection is already scoped, so `true` would only restate the default; the build rejects it.
-
-**A shared connection's change log must not write into a walled collection.** A `tenant: shared` connection's writes belong to no organization, so its `changeLog` records carry no `organization_id`. In a collection a scoped connection reads, those records would be invisible to every walled read and would make the tenant preflight refuse to serve the app, so the build rejects a shared connection whose `changeLog.collection` is the collection of a scoped connection in the same database. Give shared connections their own change-log collection.
-
-**A shared connection over a walled collection has its writes checked.** When a `tenant: shared` connection names the same collection, in the same database, as a scoped connection, the build marks it, and every row it inserts, replaces, upserts or updates must keep a non-empty `organization_id` — the same check a [`tenant: none` write](#writing-with-tenant-none) gets. Its reads stay unscoped, which is what `shared` is for. A collection name resolved at runtime (`_secret`, `_payload`) can not be compared at build time, so such a connection is not marked.
-
-**A shared connection's aggregation may not `$out` or `$merge` into a walled collection.** The rows an aggregation writes are not checked, so the build rejects a request or step on a `tenant: shared` connection whose literal pipeline writes, with `$out` or `$merge`, into a collection a scoped connection reads in the same database. Write the rows with a checked request instead (see the rollup example below). A target named by an operator, or in another database, is not checked at build time.
-
-**Under `tenant` policy every connection type must declare its capability.** A connection whose type does not declare tenant support (`connectionMetas.tenant`) fails the build — no connection is ever *silently* unscoped. Connection plugins declare this in their `types.js`; you do not set it.
-
-### Exceptions at the point of use
-
-The wall scopes mechanically, but a few operations need an explicit opt-out or opt-in, declared on the request, step or websocket — never on the connection:
-
-| Surface | Allowed values | Meaning |
-| ------- | -------------- | ------- |
-| Request | `none` | Opt this request out of scoping entirely. |
-| Request | `authored` | The request authors its own tenant clause (audited at runtime). |
-| Websocket | `none` | Opt out. `authored` is not allowed — change streams are always scoped mechanically. |
-
-An aggregation stage the wall cannot scope mechanically — `$search`, `$searchMeta`, `$vectorSearch`, `$geoNear`, `$graphLookup` — must declare `tenant: authored` and author the organization clause *inside the stage*. The runtime audits that clause against the caller's active organization; it does not trust the declaration alone.
-
-```yaml
-# A $search aggregation on a scoped connection: author the org filter
-# inside the stage and declare it.
-id: search_records
-type: MongoDBAggregation
-connectionId: app_data
-tenant: authored
-properties:
-  pipeline:
-    - $search:
-        compound:
-          filter:
-            - equals:
-                path: organization_id
-                value:
-                  _user: organization_id
-          must:
-            - text:
-                query:
-                  _payload: q
-                path: title
-```
-
-### Writing with `tenant: none`
-
-`tenant: none` lifts the filter and the stamp, not the rule that every row in a walled collection belongs to an organization. A row without `organization_id` is invisible to every walled read, and the tenant preflight refuses to serve the app while one exists, so a `tenant: none` write on a scoped connection is checked instead of stamped:
-
-- Inserted and replacement documents must carry a non-empty `organization_id`, and upserts must author it (`$set` / `$setOnInsert`, or an equality match in the filter).
-- Updates may not null, unset, rename or otherwise overwrite it with a value the wall can not verify.
-- An aggregation may not contain `$out` or `$merge`: the rows they write can not be checked. Return the documents and write them with `MongoDBInsertMany` or `MongoDBBulkWrite`, which check every row (see the example below).
-
-**Change logs.** On a connection with a `changeLog`, the change-log record of a `tenant: none` write carries the `organization_id` of the rows it records, so the log collection can itself be read through a scoped connection. A single-document write takes it from the row it inserted, updated (the row as the update left it) or deleted; a write that matched no row writes no record. A multi-document write must be held to one organization before it runs:
-
-| Request | Allowed on a change-logged connection when |
-| ------- | ------------------------------------------ |
-| `MongoDBInsertMany`, `MongoDBInsertManyConsecutiveIds` | every document carries the same `organization_id` |
-| `MongoDBUpdateMany` | the filter matches `organization_id` by equality (`{ organization_id: <id> }` or `{ $eq: <id> }`) and the update does not write it |
-| `MongoDBDeleteMany` | the filter matches `organization_id` by equality |
-
-Anything else is refused before it writes, with an error naming the fix — usually running the write once per organization. Connections without a `changeLog` are not affected. (A [shared connection](#declaring-scope-on-a-connection) writes no organization into its change-log records; its change log can not point into a walled collection.)
-
-**Rollups across organizations** — group walled rows by organization and save the totals, typically from a scheduled endpoint — read with `tenant: none` and write the rows with a checked request instead of `$merge`:
-
-```yaml
-routine:
-  - id: rollup
-    type: MongoDBAggregation
-    connectionId: orders
-    tenant: none
-    properties:
-      pipeline:
-        - $group:
-            _id:
-              organization_id: $organization_id
-              month:
-                $dateToString:
-                  format: '%Y-%m'
-                  date: $created_at
-            total:
-              $sum: $amount
-        - $project:
-            _id: 0
-            organization_id: $_id.organization_id
-            month: $_id.month
-            total: 1
-  - id: save_rollup
-    type: MongoDBBulkWrite
-    connectionId: monthly_totals
-    tenant: none
-    properties:
-      operations:
-        _array.map:
-          - _step: rollup
-          - _function:
-              replaceOne:
-                filter:
-                  organization_id:
-                    __args: 0.organization_id
-                  month:
-                    __args: 0.month
-                replacement:
-                  __args: 0
-                upsert: true
-```
-
-Every replacement carries the `organization_id` the group produced, so the bulk write passes the check, and each organization reads its own totals through the scoped `monthly_totals` connection.
-
-### Why the wall lives on the connection
-
-Putting scope on the connection, and only exceptions at the point of use, means the default is safe: a developer who forgets to think about tenancy gets a scoped read and a stamped write, not a leak. The dangerous states — sharing across organizations, opting a request out, authoring a raw clause — are the ones that have to be typed out, reviewed in a diff, and (for `authored`) audited at runtime. This inverts the usual footgun where the safe path is the verbose one.
-
-Under `policy: pinned` the wall is inert — there is one organization, so scoping to it is a no-op — but declaring `tenant` on connections does no harm, which lets one config serve both a pinned install and a tenant deployment.

package/content/user-authentication/protected-pages-apis.md

@@ -1,97 +0,0 @@
-# Protected Pages and APIs
-
-By default, all pages and APIs in a Lowdefy app are public. Protected pages and APIs are resources that can only be accessed by a logged in user. If a user that is not logged in tries to access a protected page or API, they will receive an authentication error. For pages, the user will be redirected to the 404 page, and pages that a user is not allowed to see will be filtered from the app menus. For APIs, an "API Endpoint does not exist" error will be thrown.
-
-The config can either be set to protect all pages/APIs, except for a list of public ones, or vice-versa, all are public except for a list of protected ones.
-
-Protected and public pages and APIs can be configured in the `auth.pages` and `auth.api` sections of the Lowdefy configuration. Here the fields `protected` and `public` can be set to true, or a list of page/API IDs. You cannot set `protected` or `public` to `false`, and both can't be an array or `true` at the same time.
-
-When protecting all pages in the app, you will need to set at least one page as public to allow users to log in to the app.
-
-The 404 page (used to indicate that a requested page cannot be found) is always a public page. A default 404 page will be created if you do not specify one, but if you create a page with pageId `'404'` then that page will be the 404 page.
-
-## Examples
-
-###### List specific public pages and APIs:
-```yaml
-lowdefy: 6.0.0
-auth:
-  pages:
-    protected: true
-    public:
-      - '404'
-      - login
-      - public-page
-  api:
-    protected: true
-    public:
-      - health_check
-      - get_public_content
-```
-
-###### List specific protected pages and APIs:
-```yaml
-lowdefy: 6.0.0
-auth:
-  pages:
-    public: true
-    protected:
-      - admin
-      - users
-  api:
-    public: true
-    protected:
-      - update_user_settings
-      - admin_dashboard_api
-```
-
-###### Mixed configuration:
-```yaml
-lowdefy: 6.0.0
-auth:
-  # Protect specific pages while keeping most public
-  pages:
-    public: true
-    protected:
-      - dashboard
-      - profile
-      - settings
-
-  # Protect all API endpoints
-  api:
-    protected: true
-```
-
-## Wildcard Patterns
-
-Page and API access rules support glob patterns using `*` and `**` wildcards. This is useful for granting access to all pages from a [module](/modules):
-
-- `team-users/*` — matches all pages in the `team-users` module
-- `team-*/*` — matches all pages in modules with IDs starting with `team-`
-- `*/settings` — matches the `settings` page in any module
-- `**` — matches all pages
-
-Exact page IDs still work: `home`, `team-users/users-list`.
-
-###### Wildcard pattern example:
-```yaml
-lowdefy: 6.0.0
-auth:
-  pages:
-    protected: true
-    public:
-      - home
-      - login
-    roles:
-      admin:
-        - team-users/*
-        - admin/*
-      user:
-        - notifications/*
-```
-
-## Important Notes
-
-- Pages and APIs are configured separately - protecting pages does not automatically protect APIs
-- Protected resources require users to be authenticated before access is granted
-- Role-based access control can be layered on top of protection for finer-grained permissions

package/content/user-authentication/roles.md

@@ -1,49 +0,0 @@
-# Roles
-
-Roles can be used to limit user access to certain pages and API endpoints. Only users with a role linked to the page will be able to see that page, and the page will be filtered from menus if the user does not have the role.
-
-Roles are read from the `roles` field on the [user object](/user-object) — an array of role-name strings. These are the caller's **app roles**, resolved from their membership in the active organization (`member.appRoles`), not from a provider claim. A member is granted app roles through an [invitation](/auth-steps) (`InviteMember`) or an auth step (`UpdateMemberRoles`), so the same person can hold different roles in two organizations they belong to.
-
-Declare the role names your app uses in `auth.roles` (id, optional label and description) so tooling can list them:
-
-```yaml
-lowdefy: 6.0.0
-auth:
-  roles:
-    - id: user-admin
-      label: User Administrator
-    - id: sales
-    - id: reports
-```
-
-Do **not** gate on `_user.org_roles` (the `owner`/`admin`/`member` organization tier) — no page or API gate reads it. It is an administrative fact used by the [auth-step authority floor](/auth-steps), separate from app roles. See [Organizations & Multi-Tenancy](/organizations#the-owner-admin-member-tier-vs-app-roles).
-
-The pages that are protected by roles are configured in the `auth.pages.roles` section in the Lowdefy configuration. This should be an object, where the keys are the role names, and the values are an array of pageIds that are protected by that role.
-
-Similarly, the API endpoints that are protected by roles are configured in the `auth.api.roles` section in the Lowdefy configuration, where the keys are the role names, and the values are an array of endpointsIds that are protected by that role.
-
-###### Protect pages and API endpoints using roles:
-```yaml
-lowdefy: 6.0.0
-auth:
-  pages:
-    public: true
-    roles:
-      user-admin:
-        - users
-        - new-user
-        - edit-user
-      sales:
-        - customers
-        - new-customer
-        - edit-customer
-      reports:
-        - sales-report
-        - operations-report
-    api:
-      protected: true
-      roles:
-        user-admin:
-          - create-user
-          - update-user
-````