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

package/content/user-authentication/two-factor.md

@@ -1,229 +0,0 @@
-# Two-Factor Authentication
-
-Enabling `auth.twoFactor` gives your app a second factor for sign-in: time-based one-time password (TOTP) codes from an authenticator app, plus a set of single-use backup codes for when the authenticator is unavailable. Backup codes are consumed one per use. The challenge is enforced by the engine on every sign-in method that can meet it — not left to your app config — so an enrolled user cannot walk past their second factor by choosing a different way in.
-
-## Enabling it
-
-```yaml
-auth:
-  twoFactor:
-    enabled: true
-  authPages:
-    twoFactor: /two-factor-challenge
-```
-
-`authPages.twoFactor` is required when `twoFactor.enabled` is true — the build fails without it. This is not a convenience default the build could invent: the engine navigates the user to that page itself, so a missing page would leave an enrolled user unable to sign in, with nowhere to show an error.
-
-The challenge page is public automatically, the same way the password-reset page is. By the time a user lands on it, the engine has already deleted the session the sign-in created and set a signed cookie holding the pending challenge, so there is no session to authenticate the page against — the protection lives in the cookie, not in a page role.
-
-The page should catch the `INVALID_TWO_FACTOR_COOKIE` error and redirect to sign-in. Visited directly, without the cookie, the page renders fine and the verify call throws. That is harmless, but it leaves the user looking at a code box that can never succeed.
-
-## Which sign-in methods are challenged
-
-| Sign-in method                 | Challenged                          |
-| ------------------------------ | ----------------------------------- |
-| Email + password               | Yes                                 |
-| Phone number + password        | Yes                                 |
-| Magic link                     | Yes — always, no toggle             |
-| SMS code (`PhoneNumberVerify`) | Yes — always, no toggle             |
-| OAuth provider                 | Yes, unless the provider is trusted |
-| Passkey (`PasskeySignIn`)      | No — deliberately                   |
-
-Magic link and SMS code have no toggle. A magic link is possession-of-inbox — the factor most likely to be compromised in exactly the incident two-factor authentication exists to survive. An SMS code is possession-of-SIM, and SIM-swap is the best-documented account-takeover attack of any factor on this list. Neither is a factor worth accepting on its own for an enrolled user.
-
-Passkey sign-in is not challenged, and that is correct rather than missing. A passkey is possession of the authenticator plus user verification in a single phishing-resistant ceremony, and the major identity providers accept one as satisfying multi-factor authentication outright.
-
-### The engine routes the challenge
-
-[`Login`](/Login) and `PhoneNumberVerify` navigate to `authPages.twoFactor` themselves, and they **end the event chain** when they do. A step placed after `Login` or `PhoneNumberVerify` does not run on the challenge path, so your app needs no `skip` guard for it. Your app does not route the challenge. The action response still carries `twoFactorRedirect` and `twoFactorMethods` if you want to read them.
-
-The trade this makes: an inline two-factor challenge rendered on the login page itself is no longer possible. The challenge is always a page.
-
-### A challenge page routes nothing
-
-The engine owns both ends of the challenge hop. It navigates to `authPages.twoFactor` on every sign-in path, carrying the destination the caller asked for as `?callbackUrl=`, and `TwoFactorVerify` navigates away again after a successful verify — reading that same parameter through the same ladder as the rest of sign-in. So an enrolled user who deep-linked to `/invoices/123`, was bounced to sign in and then challenged, lands back on `/invoices/123`, and your challenge page needs no routing config for it.
-
-Only app-relative, same-origin destinations are carried; anything else falls through to the home page. `basePath` needs no handling: the carried path already includes it.
-
-`TwoFactorVerify` takes the same `callbackUrl` param as [`Login`](/Login): an explicit target wins over the carried one, and `callbackUrl: false` stays put, for a challenge page that renders its own post-verify state instead.
-
-### Trusting a device
-
-`TwoFactorVerify`'s `trustDevice` param sets a cookie that short-circuits the challenge on later sign-ins from the same browser. It applies on every one of the challenged paths above, not just the one it was set from.
-
-## Trusting an OAuth provider
-
-An enterprise identity provider often enforces its own multi-factor policy. `twoFactorTrusted` on a provider entry tells the engine not to challenge sign-ins that came through it:
-
-```yaml
-auth:
-  providers:
-    - id: corp-idp
-      type: GenericOAuth
-      twoFactorTrusted: true
-      properties: ...
-```
-
-What it means: skip the engine's challenge for sign-ins through this provider, because you are asserting the IdP enforced multi-factor authentication itself.
-
-**The trust is declared, not verified.** The engine cannot confirm what the IdP actually enforced, and it checks nothing. Set this only where you control or otherwise trust the IdP's own MFA policy.
-
-`twoFactorTrusted` is **unrelated to `auth.account.accountLinking.trustedProviders`**, which trusts a provider's _email claim_ enough to link a sign-in to an existing account automatically. Trusting Google's email claim is routine; it is not a claim that every Google sign-in cleared MFA. The two lists are independent, and setting one has no effect on the other. This is the mistake the separate key exists to prevent.
-
-The escape hatch exists because without it the only advice would be "don't enable two-factor alongside an enterprise IdP", which is a functionality loss dressed up as operational advice. Entra has federated-IdP-MFA trust settings and Okta has the IdP factor: nobody double-challenges by default, and nobody silently accepts either.
-
-## Known limitation: TOTP codes are replayable within their window
-
-A TOTP code that has already been used successfully is accepted again inside its validity window — roughly 30 to 60 seconds. BetterAuth's verifier keeps no ledger of consumed codes and no last-used counter, so nothing distinguishes a second presentation of a code from the first.
-
-This violates the standards:
-
-- RFC 6238 §5.2: "The verifier MUST NOT accept the second attempt of the OTP after the successful validation has been issued for the first OTP."
-- OWASP ASVS 5.0 §6.5.1 (L2), which requires the same single-use property.
-
-**Severity is narrow.** Exploiting this needs the user's password _and_ a code inside its window — and an attacker holding both can simply sign in, with no replay involved. The real gain is the case where the legitimate user spent the code first: an attacker who has the password and observes that code can mint their own session inside the window without racing anyone for it.
-
-It is not a bypass. The second factor works; it is replayable within its own validity. Replay against the _same_ sign-in challenge already fails, because that challenge's verification record is consumed and its cookie expired. What remains is a _fresh_ challenge accepting the same code while the window is still open.
-
-Tracked upstream at [#10387](https://github.com/better-auth/better-auth/issues/10387). Lowdefy has not mitigated it locally: a `before` hook on the sign-in path has no session to work from, so recovering the user would mean reaching into the two-factor plugin's private cookie and verification internals — a bad trade for a sixty-second window that already sits behind a password.
-
-If you are enabling multi-factor authentication to satisfy an auditor, know about this before the auditor tells you.
-
-## Concurrent enrolment and the unique index
-
-Two `TwoFactorEnable` calls that run concurrently for the same user can write two rows to the two-factor collection. Sign-in may then read the unverified row, find no methods to offer, and leave the user unable to complete a challenge — a silent lockout. Tracked upstream at [#10561](https://github.com/better-auth/better-auth/issues/10561).
-
-The mitigation is a unique index on the user id in the two-factor collection (`user-two-factors`), applied by the host app. Lowdefy creates only the organization and membership indexes itself ([Organizations](/organizations)); this one is the deployment's. For MongoDB, see the `modules-mongodb` `user-account` index reference for how that module declares its auth indexes, or apply it directly — the adapter stores fields in snake_case, so the key is `user_id`:
-
-```js
-db['user-two-factors'].createIndex({ user_id: 1 }, { unique: true });
-```
-
-Be clear about what the index buys: it converts an unrecoverable silent lockout into a visible, retryable duplicate-key error. It does not fix the race.
-
-## Requiring two-factor enrolment
-
-`twoFactor.enabled` lets a member enrol a factor. `twoFactor.required` makes enrolment a floor: a member who has not enrolled cannot use the app until they do.
-
-```yaml
-auth:
-  twoFactor:
-    enabled: true
-    required: true
-  authPages:
-    twoFactor: /two-factor-challenge
-    twoFactorEnrol: /two-factor-enrol
-```
-
-A caller satisfies `required` by holding **either** a TOTP enrolment **or** a registered passkey. A passkey counts on its own: it is a phishing-resistant possession factor bound to user verification, which is exactly why Entra and Okta accept one outright. Demanding TOTP on top of a passkey is theatre — it adds no assurance and pushes the user toward the weaker of the two factors.
-
-An unenrolled caller is redirected to `authPages.twoFactorEnrol` on every page, and refused at every request, endpoint and websocket with a `TwoFactorEnrolmentRequiredError` — a **403, not a 401**. A 401 reads to the client as a dead session and bounces the user to sign-in, which is the loop the floor exists to avoid; a 403 says "you are signed in, but you are missing something".
-
-The enrolment check runs **after** the role check. Probing a page you lack the roles for still returns the opaque 404 it always did, so turning `required` on never reveals a page's existence to someone who was not authorised for it in the first place.
-
-`authPages.twoFactorEnrol` is **required when `required: true`** — the build fails without it. Every unenrolled user is redirected there, so a deployment that required enrolment without naming the page would redirect them to nowhere.
-
-Callers that carry no session pass untouched: the API strategy and the injected callers used in dev and e2e are not session-resolved members, so the enrolment floor does not apply to them.
-
-## What `required` guarantees — and what it does not
-
-> `required` guarantees that every member has enrolled a factor. It does NOT guarantee that every session presented one.
-
-Read the second sentence before you rely on the first. Here is the concrete gap. Take a user who registered a passkey and also holds a password. They sign in with the password. BetterAuth's sign-in hook opens with `if (!data?.user.twoFactorEnabled) return;`, so a passkey-only enrolment fires no challenge. The enrolment floor then computes `false || passkeyCount > 0` and reads the caller as satisfied. Nothing on this path compares the factor **presented this sign-in** against the factors the user **holds** — so a password-only sign-in clears a floor a passkey was meant to enforce.
-
-This is an accepted cost, for three reasons:
-
-- The fix is session-scoped satisfaction — comparing presented against held on every request. That is a larger feature than a per-user flag, and shipping it half-built would be worse than naming the limitation. It has a known correct answer; it is not in this release.
-- Dropping the passkey disjunct would trade a soft hole for a hard lockout: a passwordless user who enrolled only a passkey would satisfy nothing and be locked out of an app they have a perfectly good factor for.
-- The affected population **voluntarily registered a strong, phishing-resistant credential.** They are not the threat `required` defends against. `required` exists to catch members with **no second factor at all** — and every one of those is caught, because an unenrolled caller has neither a TOTP row nor a passkey and fails the floor outright.
-
-## Two-factor with a trusted OAuth provider
-
-A `twoFactorTrusted` provider's users are not challenged on that sign-in path (see **Trusting an OAuth provider**, above). Under `required`, a user who signed in that way and has not separately enrolled is unenrolled, so they are routed to `authPages.twoFactorEnrol` to enrol a TOTP their sign-in will never present.
-
-The cost, stated plainly: a deployment whose **only** sign-in path is a trusted provider gets enrolment with no challenge ever attached to it.
-
-The enrolled factor is not inert, though. It is what a password or magic-link sign-in **would** challenge, and it is what an admin reset restores. It earns its keep the moment a second sign-in path exists.
-
-## Two-factor for passwordless users
-
-The four BetterAuth two-factor endpoints that mutate a factor are password-gated: they call `shouldRequirePassword`, which demands the caller's current password unless `allowPasswordless` is set. Lowdefy sets `allowPasswordless: true`, so an OAuth or magic-link user who never set a password can still enrol TOTP.
-
-The waiver is **per user**, not per app. A caller who *does* hold a password still faces the password gate on all four endpoints — the waiver only lifts it for the users who have no password to give. There is no route difference to configure: the same enrol flow serves both.
-
-## The enrolment page
-
-`authPages.twoFactorEnrol` is the one auth page that is **not public**. On the sign-in and challenge pages the user has no session yet; here they hold a valid session and are merely missing a factor — an authorisation gap, not an identity one — so the page stays behind a session.
-
-The constraint that follows: **the enrolment page cannot call any Lowdefy request or endpoint.** An unenrolled caller is refused at every one of them with a 403, and the person on this page is unenrolled by definition. It must be self-sufficient on the client auth actions — `TwoFactorEnable`, `TwoFactorVerify` and `PasskeyRegister` — which hit `/api/auth/*` directly and are not behind the enrolment floor.
-
-Reached with no session at all, it behaves like any protected page: the user is sent to sign in with a `callbackUrl` back to the enrolment page.
-
-## Recovering a user who has lost their factor
-
-When a member loses their authenticator or has a security key stolen, an administrator restores their access with two org-scoped steps:
-
-| Step                                            | Properties            | Permission                    |
-| ----------------------------------------------- | --------------------- | ----------------------------- |
-| `ResetUserTwoFactor`                            | `userId`              | `user: ['reset-two-factor']`  |
-| `RevokeUserPasskeys`                            | `userId`, `passkeyId?`| `user: ['revoke-passkeys']`   |
-
-Both are `org`-scoped and bounded by target membership: an administrator can only reach a user who holds a member row in an organization they administer. Both permissions ship granted to `owner` and `admin`; a narrower custom role can be given member management without either of them.
-
-Three things this routine must not miss:
-
-**Pair the reset with `RevokeUserSessions`.** Clearing a factor does not end a session — an attacker who already holds one keeps it, which is precisely the incident you are recovering from. A reset without a session revocation has not recovered the account. Run all three together:
-
-```yaml
-id: admin-recover-user-two-factor
-type: Api
-routine:
-  - id: reset_two_factor
-    type: ResetUserTwoFactor
-    properties:
-      userId:
-        _payload: userId
-  - id: revoke_passkeys
-    type: RevokeUserPasskeys
-    properties:
-      userId:
-        _payload: userId
-  - id: revoke_sessions
-    type: RevokeUserSessions
-    properties:
-      userId:
-        _payload: userId
-  - ':return':
-      _step: revoke_sessions
-```
-
-**The reach is suite-wide.** `twoFactorEnabled` lives on the deployment-wide user row, and there is one enrolment per user — never one factor per organization. The membership bound governs **who** an administrator may reset, not **how far** a reset reaches: reset the user in the one organization you administer and their factor is cleared everywhere.
-
-**`ResetUserTwoFactor` also deletes the user's trust-device records.** This is load-bearing, not tidying. A device the user once ticked "trust this device" on holds a signed cookie that skips the challenge; leave the record in place and, the moment the victim re-enrols, a stolen device walks straight past the factor they just set up.
-
-One timing note on session revocation: with `session.cookieCache` enabled, a revoked session can still be honoured from its cached copy for up to the cache's `maxAge` (default 300 seconds). Lowdefy defaults `cookieCache` **off**, so a default deployment has no such window — but if you turned it on, size the exposure accordingly.
-
-## Before you turn `required` on
-
-**Enrol your administrators first — more than one of them.** Turning `required` on sends every unenrolled user, administrators included, to the enrolment page at their next request. If the only person who can run `ResetUserTwoFactor` is themselves locked out mid-enrolment, you have no in-app way back.
-
-**There is no escape hatch, by design.** No exempt identity, no environment override, no grace period. Each of those would be a permanent bypass of the floor, available to anyone who found it, so none exists.
-
-**Last-admin recovery is a database edit.** If every administrator is locked out, the only way back is to clear one administrator's factor directly in the database — the same two writes `ResetUserTwoFactor` makes:
-
-1. Delete the target's row from the `user-two-factors` collection.
-2. Set `twoFactorEnabled` to `false` on their row in the `users` collection.
-
-That administrator can then sign in and recover the others through the app.
-
-## Required index
-
-Under `required`, the engine counts a caller's passkeys on every request from anyone not yet enrolled, to decide whether they clear the floor. That read needs an index on the passkey collection:
-
-```js
-db['user-passkeys'].createIndex({ user_id: 1 });
-```
-
-This index is **platform-owned but host-applied.** The engine reads it per request for any unenrolled caller under `required`; without it, that read is a full collection scan on every such request. But Lowdefy creates only the organization and membership indexes itself — the deployment applies this one, exactly as it applies the `user-two-factors` index above. (The auth adapter stores fields in snake_case, so the key is `{ user_id: 1 }`, not the logical `{ userId: 1 }`.)
-
-An **enrolled** caller never reaches the passkey read: the floor short-circuits on `twoFactorEnabled`, which rides the session, so an enrolled member pays nothing. Once `required` has been on for a while, that is the overwhelming majority of traffic.

package/content/user-authentication/user-object.md

@@ -1,58 +0,0 @@
-# User Object
-
-The `user` object holds data about the currently signed-in **caller**, read with the [`_user`](/_user) operator on both the server and the client. It is not the provider's profile — it is a caller Lowdefy resolves from the user's row *and their membership in the active organization*, so the same person carries a different `_user` in two organizations they belong to.
-
-Its shape is **fixed**. Unlike the old provider-claim mapping, there is no `userFields` config and no set of OpenID Connect claims copied onto the session — the provider subject and extra claims are not on the user object at all. If you need a provider claim at signup, persist it with an [auth hook](/auth-upgrade#7-rewrite-callbacks-and-events-as-hooks) and read it from where you stored it.
-
-## Fields
-
-| Field | On which callers | Meaning |
-| ----- | ---------------- | ------- |
-| `id` | all | The internal user id. **This replaces the old `sub`** — it is a *different value* (the provider subject lives on the `user-accounts` collection as `accountId`). |
-| `email` | all | The user's email. |
-| `email_verified` | session | Whether the email is verified. |
-| `name`, `image` | session | Display name and avatar — the **per-organization** copies from the active membership, falling back to the deployment-global user record. |
-| `roles` | session, strategy | The app's own role strings, from the active membership's `appRoles`. **The only thing `auth.pages.roles` / `auth.api.roles` match.** |
-| `org_roles` | session | The organization tier from `member.role`: `owner`, `admin` or `member`. An administrative fact — **no gate reads it**. |
-| `attributes` | session | One merged bag: global `user.attributes` under the active `member.attributes`, per key, member wins. |
-| `organization_id` | session, mcp | The organization the caller acts in — the value the [tenant wall](/organizations#the-tenant-wall) stamps and filters on. |
-| `active_organization_id` | session | The active organization id (equal to `organization_id`). |
-| `two_factor_enrolled` | session | Whether the caller holds a factor satisfying `auth.twoFactor.required`. |
-| `auth_method` | strategy, mcp | How the caller authenticated — the strategy id, or `'mcp'` for an [assistant](/mcp-oauth). Absent on browser sessions. |
-| `profile` | session | The user record's opaque display/app-data bag. Absent (never `{}`) when the user has written no profile. |
-| `contact_id` | session | Link to the app's canonical record for this person, when one exists. |
-
-> **`_user.role` (singular) carries nothing.** Lowdefy never writes it; it sits one character from `roles`, so gating on `_user.role` is gating on a constant. Read `roles`.
-
-A caller resolved from an [API strategy](/auth-configuration) (`apiKey`, `jwt`) sits outside the membership boundary: it carries `id`, `roles`, `attributes` and `auth_method`, but no organization, `name`, `image`, `profile` or `two_factor_enrolled`. A signed-in user who holds only a pending invitation (before they accept, under `tenant`) is an *awaiting-organization* caller — known to the always-public accept page, refused everywhere else.
-
-## Examples
-
-###### Use the user's avatar in an Avatar block:
-```yaml
-id: avatar
-type: Avatar
-properties:
-  src:
-    _user: image
-```
-
-###### Stamp the creator when inserting a document:
-```yaml
-id: insert_data
-type: MongoDBInsertOne
-properties:
-  doc:
-    field:
-      _state: field
-    created_by:
-      name:
-        _user: name
-      id:
-        _user: id
-```
-
-###### Read a value out of the merged attributes bag:
-```yaml
-_user: attributes.plan
-```

package/content/websockets/websocket-publish.md

@@ -1,108 +0,0 @@
-# Publish and Actions
-
-A `Channel` websocket relays messages between clients: any subscriber can publish, and the server broadcasts to everyone subscribed — including the sender. This powers chat, presence, and collaborative features with no extra services.
-
-## A Minimal Chat
-
-```yaml
-lowdefy: 6.0.0
-
-websockets:
-  - id: team_chat
-    type: Channel
-    properties:
-      publish: true
-
-pages:
-  - id: chat
-    type: PageHeaderMenu
-    subscriptions:
-      - websocketId: team_chat
-        client:
-          maxMessages: 200
-    blocks:
-      - id: chat_input
-        type: TextInput
-        properties:
-          placeholder: Say something...
-      - id: send
-        type: Button
-        properties:
-          title: Send
-        events:
-          onClick:
-            - id: publish
-              type: Publish
-              params:
-                websocketId: team_chat
-                payload:
-                  text:
-                    _state: chat_input
-            - id: clear
-              type: SetState
-              params:
-                chat_input: ''
-      - id: messages
-        type: Html
-        properties:
-          html:
-            _array.join:
-              - _array.map:
-                  on:
-                    _websocket: team_chat.messages
-                  callback:
-                    _function:
-                      __string.concat:
-                        - '<p>'
-                        - __args: 0.text
-                        - '</p>'
-              - ''
-```
-
-Publishing requires both the channel type to support it and `properties.publish: true` on the definition — server-push channels reject publishes by default.
-
-## Actions
-
-### `Publish`
-
-Sends a payload to a channel. The action resolves when the server acknowledges the publish, and rejects if the channel does not allow publishing or the connection cannot be established:
-
-```yaml
-- id: publish
-  type: Publish
-  params:
-    websocketId: team_chat
-    payload:
-      text:
-        _state: chat_input
-```
-
-Payload values keep their types across the wire — dates arrive as dates.
-
-### `Subscribe` and `Unsubscribe`
-
-Page `subscriptions` cover most cases, but the actions give dynamic control — subscribe after an interaction, or re-subscribe with a fresh payload:
-
-```yaml
-- id: change_filter
-  type: Unsubscribe
-  params: activity_feed
-- id: resubscribe
-  type: Subscribe
-  params: activity_feed # payload re-evaluates from current state
-```
-
-`Subscribe` on an already-subscribed channel does nothing. Channels subscribed with the action are still cleaned up when the page unmounts.
-
-## Deployment
-
-### Vercel
-
-Websockets use Vercel's native WebSocket support for Node.js functions on Fluid compute — deploy the same project, no configuration. Two platform behaviors to know:
-
-- Connections close when a function reaches its `maxDuration`. The Lowdefy client reconnects and resubscribes automatically, so this is invisible to users; raise `maxDuration` to reduce reconnect frequency on websocket-heavy apps.
-- Under load, Vercel may run multiple instances of your app. Server-driven sources run per instance, so every subscriber receives every source message regardless of which instance they land on. Client publishes, however, reach subscribers connected to the same instance. For chat-style apps at multi-instance scale, a cross-instance pubsub adapter is on the roadmap.
-
-### Self-Hosted
-
-The Node.js server handles websocket upgrades directly — nothing to configure. A single server process delivers publishes to all subscribers, so `Channel` behavior is complete on one instance. Behind a reverse proxy, forward the upgrade headers and the original `Host` header (`proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_set_header Host $host;` for nginx). The server refuses a websocket upgrade from a page whose origin does not match the `Host` it receives.

package/content/websockets/websocket-subscriptions.md

@@ -1,100 +0,0 @@
-# Page Subscriptions
-
-Pages subscribe to websocket channels with the `subscriptions` key. The engine subscribes when the page mounts and unsubscribes when the user navigates away — no cleanup wiring needed.
-
-## Subscription Definition
-
-- `websocketId: string`: __Required__ - The id of a websocket defined in the top-level `websockets` array.
-- `payload: object`: Client-side operators (`_state`, `_url_query`, `_global`) evaluated at subscribe time. The server reads these values with `_payload` in the websocket `properties`.
-- `events: object`: Actions for `onMessage`, `onSubscribe` and `onError`.
-- `client.maxMessages: number`: How many messages to retain in `messages` (default 100, oldest dropped first).
-- `client.throttleRender: number`: Minimum milliseconds between renders while messages stream in (default 250, minimum 100).
-
-## Reacting to Messages
-
-The most common realtime pattern is prompting a data refresh — a source signals that something changed, and the page refetches its request:
-
-```yaml
-pages:
-  - id: orders
-    type: PageHeaderMenu
-    requests:
-      - id: get_orders
-        type: MongoDBFind
-        connectionId: mongodb
-        properties:
-          query: {}
-    subscriptions:
-      - websocketId: order_updates
-        events:
-          onMessage:
-            - id: refetch
-              type: Request
-              params: get_orders
-    blocks:
-      - id: orders_table
-        type: AgGridAlpine
-        properties:
-          rowData:
-            _request: get_orders
-```
-
-`onMessage` fires once per render batch, not once per message — on a busy channel the batch holds every message since the last flush. The batch is available on the event:
-
-```yaml
-events:
-  onMessage:
-    - id: use_batch
-      type: SetState
-      params:
-        latest_batch:
-          _event: messages # array of message payloads in this batch
-```
-
-`onSubscribe` fires when the server acknowledges the subscription (including after an automatic reconnect). `onError` fires with `_event: message` when the channel errors.
-
-## Reading Channel State with `_websocket`
-
-The `_websocket` operator reads the channel's client state anywhere on the page:
-
-```yaml
-_websocket: ticker.connected # boolean — subscription is live
-_websocket: ticker.messages # array — retained payloads, newest last
-_websocket: ticker.lastMessage # the most recent message payload
-_websocket: ticker.lastMessage.tick # dot paths into the payload
-_websocket: ticker.messageCount # total received this page visit (not capped)
-_websocket: ticker.error # last error, null when healthy
-```
-
-Unlike `_request`, there is no invocation history — a subscription is continuous. State resets when the page unmounts.
-
-## Subscription Payloads
-
-The subscription `payload` parameterizes the channel per subscriber. Client operators are evaluated when the subscription starts:
-
-```yaml
-pages:
-  - id: activity
-    type: PageHeaderMenu
-    subscriptions:
-      - websocketId: activity_feed
-        payload:
-          project_id:
-            _url_query: project_id
-```
-
-```yaml
-websockets:
-  - id: activity_feed
-    type: MongoDBChangeStream
-    connectionId: mongodb
-    properties:
-      pipeline:
-        - $match:
-            fullDocument.project_id:
-              _payload: project_id
-            fullDocument.owner_id:
-              _user: id
-```
-
-The payload is evaluated once, at subscribe time. To subscribe with new values — say a changed filter — run [`Unsubscribe` then `Subscribe`](/websocket-publish).

package/content/websockets/websockets-introduction.md

@@ -1,97 +0,0 @@
-# WebSockets
-
-Lowdefy websockets add realtime updates to your app — live dashboards, notifications, and chat — without polling and without running a separate socket service. Channels are defined at the root of your Lowdefy configuration, pages subscribe to them, and the same Lowdefy server that serves your pages pushes messages to the browser over a single WebSocket connection.
-
-Websockets work identically on a self-hosted Node.js server and on Vercel, where Fluid compute now accepts WebSocket connections natively — one deployment, no extra infrastructure, no token wiring. Authentication uses your app's existing session: the connection is authorized with the same user roles as [API endpoints](/api-endpoints).
-
-## Quick Start
-
-A channel and a page subscription — this page shows a live tick counter:
-
-```yaml
-lowdefy: 6.0.0
-
-websockets:
-  - id: ticker
-    type: Interval
-    properties:
-      ms: 1000
-
-pages:
-  - id: dashboard
-    type: PageHeaderMenu
-    subscriptions:
-      - websocketId: ticker
-    blocks:
-      - id: ticks
-        type: Html
-        properties:
-          html:
-            _string.concat:
-              - 'Ticks: '
-              - _websocket: ticker.lastMessage.tick
-```
-
-When the page loads, the client opens a websocket connection, subscribes to `ticker`, and the block re-renders as messages arrive. When the user navigates away, the subscription ends and the channel's server source stops.
-
-## How WebSockets Work
-
-1. A page with `subscriptions` mounts. The client opens one shared WebSocket connection to the Lowdefy server (lazily — apps without websockets never connect).
-2. For each subscription, the client evaluates the subscription `payload` (client-side operators like `_state`) and sends a subscribe frame.
-3. The server authorizes the subscription against the channel's `auth` config, then evaluates the websocket `properties` server-side — `_payload` reads the subscription payload and `_user` reads the subscriber's session, so a channel can be user-specific.
-4. Subscribers whose evaluated properties are identical share one running source on the server. The first subscriber starts it; the last one to leave stops it.
-5. Messages from the source are pushed to all subscribers, update the channel state read by the [`_websocket`](/websocket-subscriptions) operator, and fire the subscription's `onMessage` event.
-
-If the connection drops — a deploy, a network blip, or a serverless function reaching its time limit — the client reconnects with backoff and resubscribes automatically. Channel state on the page is preserved across reconnects.
-
-## Websocket Definition
-
-Websockets are defined in the top-level `websockets` array:
-
-- `id: string`: __Required__ - A unique identifier for the channel.
-- `type: string`: __Required__ - The websocket type. `Channel` and `Interval` ship with Lowdefy; connection plugins provide types like [`MongoDBChangeStream`](/MongoDB).
-- `connectionId: string`: The `id` of a [connection](/connections) for connection-backed types.
-- `properties: object`: Settings for the type. __Operators are evaluated server-side per subscription__ — `_secret`, `_user`, and `_payload` are available.
-
-###### A user-specific channel:
-```yaml
-websockets:
-  - id: my_feed
-    type: MongoDBChangeStream
-    connectionId: mongodb
-    properties:
-      pipeline:
-        - $match:
-            fullDocument.owner_id:
-              _user: id
-            fullDocument.category:
-              _payload: category
-```
-
-Because `properties` evaluate per subscription, two users subscribing to `my_feed` get two independent server sources — but a thousand subscribers to a channel with static properties share just one.
-
-## Core Types
-
-- `Channel` — a pure pub/sub relay. Clients publish messages with the [`Publish`](/websocket-publish) action and the server broadcasts them to all subscribers. Set `properties.publish: true` to allow publishing.
-- `Interval` — emits `{ tick, at }` every `properties.ms` milliseconds (default 1000, minimum 100). Useful for examples and testing.
-
-## Securing Channels
-
-Channel access follows the same pattern as [protected API endpoints](/api-endpoints). Configure `auth.websockets` with `public`, `protected`, and `roles` lists:
-
-```yaml
-auth:
-  websockets:
-    roles:
-      admin:
-        - admin_feed # only users with the admin role may subscribe
-    public:
-      - ticker # everyone else requires a session
-```
-
-Unauthorized subscriptions receive the same response as subscriptions to channels that do not exist.
-
-## What's Next
-
-- [Page Subscriptions](/websocket-subscriptions) — Subscribe pages to channels, handle messages with events, and read channel state with `_websocket`.
-- [Publish and Actions](/websocket-publish) — Client publishing, the `Publish`, `Subscribe` and `Unsubscribe` actions, and deployment notes.

package/hazards.json

@@ -1,44 +0,0 @@
-[
-  {
-    "id": "state-in-request-properties",
-    "appliesTo": { "kinds": ["requests"] },
-    "message": "_state in request properties is always undefined — a request is evaluated on the server with an empty state. Pass the value in the payload and read it with _payload.",
-    "see": "concepts/connections-and-requests"
-  },
-  {
-    "id": "visible-false-prunes-state",
-    "appliesTo": { "kinds": ["blocks"] },
-    "message": "visible: false removes the block and its state. Style it hidden (for example style: { display: none }) to keep the value.",
-    "see": "concepts/lowdefy-schema"
-  },
-  {
-    "id": "link-same-page-no-onmount",
-    "appliesTo": { "types": ["Link"] },
-    "message": "A Link to the page already open does not remount it, so onMount does not fire again. Trigger the reload chain from the same action list.",
-    "see": "actions/link"
-  },
-  {
-    "id": "ref-njk-renders-at-build",
-    "appliesTo": { "types": ["_ref"] },
-    "message": "A _ref to a .njk file renders at build, so _state, _request and _user are undefined inside it. Use _nunjucks over a .txt file for a template that needs runtime values.",
-    "see": "operators/_ref"
-  },
-  {
-    "id": "ref-js-imported-as-module",
-    "appliesTo": { "types": ["_ref"] },
-    "message": "A _ref to a .js file imports it as a module rather than reading it as text. Name the file .js.txt to read its source.",
-    "see": "operators/_ref"
-  },
-  {
-    "id": "tenant-wall-lookup",
-    "appliesTo": { "kinds": ["requests"], "when": "connectionTenantNotNone" },
-    "message": "This request runs over a tenant-walled connection. The wall injects { $match: { <tenant field> } } into the top-level pipeline and into every $lookup / $unionWith sub-pipeline, so a lookup into a collection with no tenant field returns [] with no error. Run the request over the shared connection and pass tenant facts in the payload instead.",
-    "see": "concepts/connections-and-requests"
-  },
-  {
-    "id": "reject-not-caught",
-    "appliesTo": { "types": [":reject"] },
-    "message": ":reject is the routine's reply, not an exception. A :catch never runs for it, :finally does, and :throw is the caught path.",
-    "see": "controls/reject"
-  }
-]