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

package/content/user-authentication/auth-configuration.md

@@ -1,266 +0,0 @@
-# Auth Configuration
-
-The `auth` section configures user authentication. Lowdefy's auth is built on [BetterAuth](https://www.better-auth.com/): sessions are database-backed, the app owns its auth UI, and roles live on organization memberships. If you are moving from the previous NextAuth-shaped config, start with the [Auth Upgrade guide](/auth-upgrade) — several keys were renamed or removed.
-
-The `_secret` operator is evaluated over the entire `auth` section, so any value can be a secret reference.
-
-For a login method to work you must configure **at least one mechanism** (`emailAndPassword`, `magicLink`, `emailOTP`, `phoneNumber`, an OAuth `providers` entry, or an API `strategies` entry), a `secret`, and a `database`. An `auth` block with none of these fails the build.
-
-## Secret
-
-A required signing secret, given as a `_secret` reference:
-
-```yaml
-lowdefy: 6.0.0
-auth:
-  secret:
-    _secret: BETTER_AUTH_SECRET
-```
-
-Also pin the app's canonical origin — the `url` of the current environment in [`config.environments`](/lowdefy-schema), or the `BETTER_AUTH_URL` environment variable, which wins — auth builds password-reset, magic-link and verification links, and its CSRF origin allowlist, from it. With `auth.email` configured, a production server refuses to start without it. See the [migration guide](/auth-upgrade#3-pin-the-canonical-url-with-better-auth-url).
-
-## Database
-
-Sessions, users, accounts and organizations are stored through an adapter:
-
-```yaml
-lowdefy: 6.0.0
-auth:
-  database:
-    id: auth_db
-    type: MongoDBAuthAdapter
-    properties:
-      uri:
-        _secret: AUTH_DATABASE_URI
-```
-
-See the [MongoDBAuthAdapter](/MongoDBAuthAdapter) reference. Collection names follow the `user-*` convention and are fixed by the adapter.
-
-## Login mechanisms
-
-- **Email & password** — `auth.emailAndPassword` (`enabled`, `requireEmailVerification`, `minPasswordLength` (default 8), `disableSignUp`).
-- **Magic link** — `auth.magicLink` (`enabled`, `expiresIn` seconds (default 300), `disableSignUp`), which needs `auth.email` (below).
-- **Email one-time code** — `auth.emailOTP` (`enabled`, `otpLength` (default 6), `expiresIn` seconds (default 300), `allowedAttempts` (default 3), `disableSignUp` (default `false`)), which needs `auth.email` (below). The person is emailed a code and types it into the tab they started from, so the sign-in survives mail security that pre-fetches links, and works when the email is opened on another device.
-- **OAuth providers** — `auth.providers`; see [Providers](/auth-providers).
-- **Phone number** — `auth.phoneNumber` (OTP sign-in); needs a `phone.otp.send` hook to deliver the SMS.
-- **Passkeys** — `auth.passkey` (`enabled`, `rpId`, `rpName`).
-
-```yaml
-lowdefy: 6.0.0
-auth:
-  emailAndPassword:
-    enabled: true
-    requireEmailVerification: true
-```
-
-## Auth email
-
-`auth.email` references an **SMTP connection** by id — the connection owns `from`, `replyTo`, the transport and the delivery filter, and is shared by every auth email flow. There is no inline transport shape. Optionally map individual flows to your own notification templates:
-
-```yaml
-lowdefy: 6.0.0
-auth:
-  email:
-    connectionId: email   # an SMTP connection in connections[]
-    templates:            # all optional; unset → branded stock template
-      verifyEmail: verify-email-notification
-      resetPassword: reset-password-notification
-      magicLink: magic-link-notification
-      invitation: invite-notification
-      emailOTP: email-otp-notification
-```
-
-### Link and code in one email
-
-With both `magicLink` and `emailOTP` enabled, the magic-link email also carries the one-time code, so a single email serves both paths: the person clicks the button, or types the code into the tab they asked for the link from. Nothing extra is sent — the `emailOTP` template is only used for a code-only send.
-
-The `magicLink` template then has two more variables available: `otp` (the code) and `expiresIn` (the code's lifetime in seconds, from `auth.emailOTP.expiresIn`). The stock template renders them below the sign-in button; a template of your own can place them wherever it likes. With `emailOTP` off both are absent and the link email is unchanged.
-
-## Auth pages
-
-BetterAuth ships no UI — your app owns its auth pages, and `auth.authPages` points at them. All are Lowdefy page paths:
-
-| Key | Default | When required |
-| --- | ------- | ------------- |
-| `signIn` | `/login` | |
-| `signUp` | `/signup` | |
-| `error` | `/auth/error` | receives `?error=` code |
-| `forgotPassword` | `/forgot-password` | |
-| `resetPassword` | `/reset-password` | where the emailed reset link lands, with `?token=` (or `?error=INVALID_TOKEN`); the default `redirectTo` of `RequestPasswordReset` |
-| `verifyEmail` | `/verify-email` | where the emailed verification link lands; receives `?error=` code when the link is invalid or expired |
-| `twoFactor` | — | **required** when `twoFactor.enabled` |
-| `twoFactorEnrol` | — | **required** when `twoFactor.required` |
-| `acceptInvitation` | — | consumes an `?invitationId=` link |
-| `magicLink` | — | landing page for the sign-in email (opt-in; see below) |
-
-```yaml
-lowdefy: 6.0.0
-auth:
-  authPages:
-    signIn: /login
-    signUp: /signup
-    error: /auth-error
-```
-
-### The email verification page
-
-A verification email links to Better Auth's verify endpoint, which confirms the address and then redirects to `authPages.verifyEmail`. When the link is invalid or has expired, it redirects there with `?error=` set (`INVALID_TOKEN`, `TOKEN_EXPIRED`), so the page can offer to resend with the `SendVerificationEmail` action. A `callbackUrl` on the `SignUp` or `SendVerificationEmail` action sends that link somewhere else instead.
-
-### The magic link landing page
-
-`authPages.magicLink` is opt-in, and it exists for one reason: Better Auth's magic-link verify endpoint consumes the single-use token on the **first** `GET` of the URL. Corporate mail security — Microsoft Defender Safe Links, Proofpoint URL Defense, Mimecast — fetches every link in a message at delivery time, so that first `GET` is a scanner and the person clicking arrives to `INVALID_TOKEN`.
-
-Set the key and the sign-in email links to a page of your own instead, with the token and the callback destinations carried on its URL query. Fetching a Lowdefy page is harmless, so the token stays unspent until a real click runs [`MagicLinkVerify`](/MagicLinkVerify):
-
-```yaml
-lowdefy: 6.0.0
-auth:
-  magicLink:
-    enabled: true
-  authPages:
-    magicLink: /magic-link
-  pages:
-    public:
-      - magic-link
-```
-
-```yaml
-id: magic-link
-type: PageHeaderMenu
-blocks:
-  - id: content
-    type: Box
-    blocks:
-      - id: title
-        type: Title
-        properties:
-          content: Sign in
-          level: 3
-      - id: description
-        type: Paragraph
-        properties:
-          content: Click the button below to finish signing in.
-      - id: verify_button
-        type: Button
-        properties:
-          title: Sign in
-        events:
-          onClick:
-            - id: verify
-              type: MagicLinkVerify
-```
-
-The page must **not** call `MagicLinkVerify` in `onMount`, and must not auto-redirect to the verify endpoint. Scanning sandboxes that render the page and execute its JavaScript would consume the token anyway, which puts you back where you started. The protection is the click, not the page.
-
-Leave the key unset and magic-link sign-in keeps working exactly as before, linking straight at the verify endpoint.
-
-See [Two-Factor Authentication](/two-factor) for the two-factor pages, and the [MCP Server & OAuth](/mcp-oauth) page for `oauthProvider.consentPage` and `postLoginPage`.
-
-## Session
-
-Database sessions. Length is `expiresIn` (seconds, default 604800 = 7 days); `updateAge` (default 86400) is how often an active session's expiry is refreshed:
-
-```yaml
-lowdefy: 6.0.0
-auth:
-  session:
-    expiresIn: 43200 # 12 hours in seconds
-    updateAge: 3600
-```
-
-`session.cookieCache` (off by default) trades a short window of stale session reads for fewer database lookups — leave it off unless you understand the [revocation-latency trade](/two-factor#recovering-a-user-who-has-lost-their-factor).
-
-## Roles, organizations, and API strategies
-
-- **Roles** — declare app role names in `auth.roles` and gate pages/endpoints with `auth.pages.roles` / `auth.api.roles`. See [Roles](/roles).
-- **Organizations** — `auth.organizations.policy` (`pinned` or `tenant`) decides the whole multi-tenancy model. See [Organizations & Multi-Tenancy](/organizations).
-- **API strategies** — `auth.strategies` authenticates non-session callers (server-to-server) with an `apiKey` or a `jwt`:
-
-```yaml
-lowdefy: 6.0.0
-auth:
-  strategies:
-    - id: service-key
-      type: apiKey
-      roles:
-        - integrations
-      properties:
-        keys:
-          - value:
-              _secret: SERVICE_API_KEY
-```
-
-A strategy caller carries the configured `roles` and `attributes` and its `auth_method` is the strategy type. A `jwt` strategy needs exactly one of `properties.secret` or `properties.jwksUri`, and a non-empty `algorithms` allowlist (which blocks `alg: none` downgrades).
-
-## Captcha
-
-`auth.captcha` protects auth endpoints with Cloudflare Turnstile. The `siteKey` is public (a plain string, never a `_secret`); the `secretKey` is a `_secret` reference. See the [Captcha block](/Captcha) for the client side.
-
-## Rate limiting and account linking
-
-- `auth.rateLimit` — brute-force protection, on by default (`enabled`, `window` seconds, `max`). Sign-in and sign-up allow 3 attempts per 10 seconds, and password-reset and verification emails 3 per minute. Limits count per client address: the connection's address on a self-hosted server, or the address a trusted proxy forwarded when the app lists its proxies in [`config.trustedProxies`](/docker#behind-a-reverse-proxy). `X-Forwarded-For` from anyone else is ignored.
-- `auth.account.accountLinking` — link a new OAuth sign-in to an existing account by verified email. `trustedProviders` lists providers whose email claim you trust for linking. **This is unrelated to `provider.twoFactorTrusted`** — see [Two-Factor Authentication](/two-factor#trusting-an-oauth-provider).
-
-## Mock User for Testing (Dev Server Only)
-
-When developing and testing Lowdefy apps, you can bypass the login flow by configuring a mock user. This is useful for testing authenticated flows without going through OAuth login.
-
-The mock user can be configured in three ways:
-
-### CLI Flag
-
-Pass `--mock-user` to `lowdefy dev` to start the server as a mock user for that run. Supply a JSON user object to set the identity and roles, or use the bare flag for a default user with no roles:
-
-```bash
-lowdefy dev --mock-user '{"id":"test-user","email":"test@example.com","roles":["admin"]}'
-```
-
-The flag sets `LOWDEFY_DEV_USER` for the dev server process, so it takes precedence over `auth.dev.mockUser` in the config file.
-
-### Environment Variable
-
-Set the `LOWDEFY_DEV_USER` environment variable to a JSON string containing the mock user object:
-
-```bash
-LOWDEFY_DEV_USER='{"id":"test-user","email":"test@example.com","roles":["admin"]}'
-```
-
-### Config File
-
-Add the `auth.dev.mockUser` section to your `lowdefy.yaml`:
-
-###### Configure a mock user for development
-```yaml
-lowdefy: 6.0.0
-
-auth:
-  providers:
-    - id: google
-      type: Google
-      properties:
-        clientId:
-          _secret: GOOGLE_CLIENT_ID
-        clientSecret:
-          _secret: GOOGLE_CLIENT_SECRET
-  dev:
-    mockUser:
-      id: test-user
-      email: test@example.com
-      name: Test User
-      roles:
-        - admin
-```
-
-When a mock user is configured:
-- The environment variable takes precedence over the config file if both are set
-- A warning is logged at dev server startup: "Mock user active - login bypassed"
-- The mock user is injected as a pre-resolved caller — its `roles` are authoritative
-- The `_user` operator returns values from the mock user, on the server and in the browser client — the dev server serves the mock session to both
-- Protected pages are accessible based on the mock user's roles
-- The dev server's headless renderer (used by the AI-agent screenshot and state-inspection tools) renders as the mock user, so it can capture pages with roles the default user lacks
-
-> **Note:** Mock users only work with the development server (`lowdefy dev`). The production server ignores mock user configuration for security.
-
-> **Note:** `dev.mockUser` bypasses the auth engine rather than exercising it, so [auth steps](/auth-steps) (which need the running auth engine) are unavailable under a mock user.
-
-`auth.dev` needs no auth stack behind it. An `auth` block whose only key is `dev` is not an auth configuration: it demands no login method, no `secret` and no `database`, the app builds and runs signed out in production, and in the dev server the browser is the `dev.mockUser` caller. Adding any other `auth` key declares a real auth stack, and the build then requires a mechanism, a secret and (for a login method) a database as usual.

package/content/user-authentication/auth-steps.md

@@ -1,138 +0,0 @@
-# Auth Steps
-
-Auth steps are routine steps that administer users, organizations and memberships — inviting a member, updating an app role, banning a user, creating an organization. They run **inside an `Api` or `InternalApi` endpoint routine**, not as client actions, because administering *other* people's memberships is a server operation that must be authorized against the caller, name its target organization explicitly, and be visible in a diff.
-
-> A **client action** mutates the caller's *own* session and nothing else — `SetActiveOrganization`, `AcceptInvitation`, `LeaveOrganization`. Anything that reaches another person's membership is an auth **step** in a routine, which is what earns it the per-step authority floor below. See the [Auth Upgrade guide](/auth-upgrade#retired-client-actions) for the actions that became steps.
-
-```yaml
-id: invite-member
-type: Api
-routine:
-  - id: invite
-    type: InviteMember
-    properties:
-      organizationId:
-        _user: organization_id
-      email:
-        _payload: email
-      appRoles:
-        _payload: roles
-  - ':return':
-      _step: invite
-```
-
-## The authority model
-
-Every auth step declares, in its own code, the authority it requires — and the engine's **authority floor** enforces that declaration mechanically before the step runs. This is not optional decoration: a step with no declared authority is a build/runtime error, so an app can never expose a member mutation by forgetting a check. The reason the floor exists in one place is that most steps go adapter-direct or through BetterAuth's admin plugin, whose check reads a single deployment-wide `user.role` field and **cannot** answer "is the caller an administrator of *this* organization". For those steps, the floor is the only authorization that can express per-organization authority.
-
-A step declares one of three **scopes**.
-
-### `org` — authorized against the caller's membership in the target organization
-
-The common case. The floor:
-
-1. **Resolves the target organization** (see below).
-2. **Finds the caller's `member` row** in that organization and checks its role against the step's required **permissions**. The caller's authority is their membership in the *target* organization — an administrator of the team organization holds nothing in the customer organization.
-3. For steps that write the deployment-wide `user` row, additionally requires the **target user** to be a member of that organization (`targetUser`), so org authority alone can never reach a user who is not the caller's business.
-
-Permissions map to the organization tier via BetterAuth's organization access control: `owner` and `admin` are granted the member-management permissions out of the box; `member` holds none of them. A refused caller gets a `ConfigError` naming exactly what was required.
-
-### `system` — caller-less, trusted runs only
-
-A `system`-scoped step (`CreateOrganization`, `ListUsers`) has no organization to be authorized in, so a caller can never satisfy it. It runs **only** where the run itself is trusted — a caller-less system routine. Mark the step `system: true`, or run it from a system context (cron, a verified webhook, an auth hook):
-
-```yaml
-- id: create_org
-  type: CreateOrganization
-  system: true
-  properties:
-    name:
-      _payload: name
-    slug:
-      _payload: slug
-    userId:
-      _payload: ownerUserId
-```
-
-### `caller` — acts on the caller's own records
-
-A `caller`-scoped step (`RevokeMcpGrant`, `LeaveOrganization`) acts only on rows the caller owns, so it needs no organization authority — but it is meaningless without a caller, and the system has no rows of its own. It requires a real caller and refuses `system: true`.
-
-### Leaving an organization from a routine
-
-`LeaveOrganization` ends the caller's own membership of the organization named by `organizationId`. The property is required: the step has no org scope, so nothing defaults it. The organization plugin's own checks run, so a caller who is not a member there, or who is its only owner, is refused. The refusal throws with the plugin's message, which the routine catches with `:try` to branch on:
-
-```yaml
-id: leave
-type: Api
-routine:
-  - :try:
-      - id: leave
-        type: LeaveOrganization
-        properties:
-          organizationId:
-            _payload: organization_id
-    :catch:
-      - :return:
-          refused:
-            message:
-              _error: message
-  # Runs only when the leave went through.
-  - :return:
-      success: true
-```
-
-On success the step returns the member row it removed. The caller's session still names the organization they left as active, so their next request resolves unauthenticated: follow the call on the page with `SetActiveOrganization` for another organization, or with `Logout`. The `LeaveOrganization` client action leaves the session's active organization from the browser and clears it; use it when nothing else has to happen in the same request as the leave. Step and action types resolve from separate maps, so the shared name is never ambiguous.
-
-## `system: true` — the two doors to a caller-less run
-
-The floor's caller requirement passes on either of two independent doors:
-
-- a **run-level** system context (`context.system === true`) — a trusted, caller-less run such as a cron endpoint, an auth hook, or a verified webhook; or
-- a **per-step** `system: true` on a single step in an otherwise user-driven run — a waiver visible in the diff, for the one privileged operation in a member-facing routine.
-
-Either door makes the step act caller-less **as the system**, bypassing the org/permission checks. That is an explicit trust decision, not attribution — use it deliberately.
-
-## How the target organization is resolved
-
-For every `org`-scoped step the floor resolves the target organization once, and the step writes into the *same* one it authorized — they cannot drift. The rule:
-
-1. An explicit **`organizationId`** property always wins. This is what a multi-organization admin routine passes, and it is what lets a session pinned to the team organization administer the customer organization.
-2. `ListMembers` also accepts an **`organizationSlug`**, resolved to an id here.
-3. Otherwise the **pinned** organization is the default — **but under `policy: tenant` there is no pinned organization**, so an omitted `organizationId` is a runtime error naming the fix. Under `tenant`, always pass `organizationId` explicitly.
-
-## `targetUser` and `selfTargetExempt`
-
-Two refinements the floor reads from a step's declaration:
-
-- **`targetUser`** names the property holding the id of the user being acted on. Steps that write the shared `user` row declare it, so the floor can require that user to be a member of the target organization. An absent target-user property is the step's own required-property error, not the floor's.
-- **`selfTargetExempt`** lets a caller act on **their own** row without holding org authority — this is what makes `UpdateUserProfile` a self-service "save my profile" step as well as an admin one. When the named property equals the caller's own id, the org authority check is skipped.
-
-## Step reference
-
-Scope, required permission, and target for every auth step. Permissions are checked against the caller's `member.role` in the target organization; `owner`/`admin` hold them by default.
-
-| Step | Scope | Permission | Target | What it does |
-| ---- | ----- | ---------- | ------ | ------------ |
-| `InviteMember` | org | `invitation: [create]` | — | Invite a member by email; carries `appRoles`, `orgRole`, `attributes`, `contactId`, `profile`; `resend` refreshes. |
-| `CancelInvitation` | org | `invitation: [cancel]` | — | Cancel a pending invitation. |
-| `ListMembers` | org | `member: [list]` | — | List members of the organization (accepts `organizationSlug`). |
-| `RemoveMember` | org | `member: [delete]` | — | Remove a member from the organization. |
-| `UpdateMemberRoles` | org | `member: [update]` | — | Set the membership's **app roles** (`appRoles` array; empty clears). |
-| `UpdateMemberOrgRole` | org | `member: [update]` | — | Set the **org tier** (`owner`/`admin`/`member`). |
-| `UpdateMemberAttributes` | org | `member: [update]` | — | Set the membership's per-organization attributes. |
-| `UpdateOrganization` | org | `organization: [update]` | — | Update the organization row (name, slug, metadata). |
-| `UpdateUserProfile` | org | `user: [update]` | `userId` (self-exempt) | Update a member's display name/image (per-organization copy). Self-service save is exempt. |
-| `UpdateUserAttributes` | org | `user: [set-attributes]` | `userId` | Set global user attributes. |
-| `BanUser` | org | `user: [ban]` | `userId` | Ban a user. |
-| `UnbanUser` | org | `user: [ban]` | `userId` | Lift a ban. |
-| `DeleteUser` | org | `user: [delete]` | `userId` | Delete a user. |
-| `RevokeUserSessions` | org | `session: [revoke]` | `userId` | Sign a user out of all sessions. |
-| `ResetUserTwoFactor` | org | `user: [reset-two-factor]` | `userId` | Clear a user's two-factor enrolment and trust-device records. |
-| `RevokeUserPasskeys` | org | `user: [revoke-passkeys]` | `userId` | Remove a user's passkeys (`passkeyId` to target one). |
-| `CreateOrganization` | system | — | — | Create an organization (tenant provisioning). Needs `userId`, or `name`+`slug` for creator-less provisioning. |
-| `ListUsers` | system | — | — | List every user in the deployment. |
-| `LeaveOrganization` | caller | — | — | End the caller's own membership of the named organization (`organizationId`, required). [Leaving from a routine](#leaving-an-organization-from-a-routine). |
-| `RevokeMcpGrant` | caller | — | — | Revoke the calling assistant's own [MCP grant](/mcp-oauth#switching-organization-from-the-assistant). |
-
-The two role tiers a member carries — the `owner`/`admin`/`member` org tier and the app's own role strings — are explained in [Organizations & Multi-Tenancy](/organizations#the-owner-admin-member-tier-vs-app-roles). Recovering a user who lost their second factor is a worked routine on the [Two-Factor Authentication](/two-factor#recovering-a-user-who-has-lost-their-factor) page.