@lowdefy/docs-content 6.0.0 → 7.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +1 -0
- package/content/actions/downloadcsv.md +1 -1
- package/content/actions/emailotpsend.md +58 -0
- package/content/actions/emailotpverify.md +79 -0
- package/content/actions/getlocalstorage.md +43 -0
- package/content/actions/link.md +47 -1
- package/content/actions/login.md +25 -5
- package/content/actions/logout.md +7 -5
- package/content/actions/magiclinkverify.md +117 -0
- package/content/actions/pdfmake.md +2 -2
- package/content/actions/posthogalias.md +29 -0
- package/content/actions/posthogcapture.md +49 -0
- package/content/actions/posthogcapturepageleave.md +38 -0
- package/content/actions/posthogfeatureflag.md +50 -0
- package/content/actions/posthoggroup.md +37 -0
- package/content/actions/posthogidentify.md +54 -0
- package/content/actions/posthoginit.md +96 -0
- package/content/actions/posthogoptin.md +29 -0
- package/content/actions/posthogoptout.md +29 -0
- package/content/actions/posthogpageview.md +37 -0
- package/content/actions/posthogreloadfeatureflags.md +47 -0
- package/content/actions/posthogreset.md +28 -0
- package/content/actions/posthogsetpersonproperties.md +36 -0
- package/content/actions/removelocalstorage.md +28 -0
- package/content/actions/resetvalidation.md +5 -3
- package/content/actions/setdarkmode.md +3 -3
- package/content/actions/setglobal.md +2 -0
- package/content/actions/setlocale.md +1 -1
- package/content/actions/setlocalstorage.md +34 -0
- package/content/actions/setstate.md +2 -0
- package/content/actions/validate.md +7 -4
- package/content/adapter-reference/mongodbauthadapter.md +46 -0
- package/content/agents/agent-endpoint-tools.md +24 -0
- package/content/agents/agent-properties.md +13 -3
- package/content/agents/agent-server-hooks.md +1 -1
- package/content/agents/agentchat.md +41 -4
- package/content/agents/agentconversations.md +42 -8
- package/content/agents/agents-introduction.md +107 -0
- package/content/callback-reference/auth0logoutcallback.md +54 -0
- package/content/concepts/ai-agent-docs.md +455 -106
- package/content/concepts/blocks.md +150 -0
- package/content/concepts/connections-and-requests.md +402 -0
- package/content/concepts/custom-html.md +42 -0
- package/content/concepts/custom-styling.md +50 -5
- package/content/concepts/dynamic-page-content.md +309 -0
- package/content/concepts/events-and-actions.md +185 -2
- package/content/concepts/four-primitives.md +31 -0
- package/content/concepts/html-attributes.md +293 -0
- package/content/concepts/i18n.md +12 -3
- package/content/concepts/keyboard-shortcuts.md +2 -2
- package/content/concepts/layout-overview.md +1 -1
- package/content/concepts/logger.md +99 -0
- package/content/concepts/lowdefy-api.md +1319 -0
- package/content/concepts/lowdefy-schema.md +144 -3
- package/content/concepts/menus.md +8 -7
- package/content/concepts/module-authoring.md +76 -5
- package/content/concepts/modules.md +3 -1
- package/content/concepts/notifications.md +180 -0
- package/content/concepts/operators.md +7 -0
- package/content/concepts/page-and-app-state.md +252 -0
- package/content/concepts/page-paths.md +209 -0
- package/content/concepts/theming.md +582 -0
- package/content/connections/aigateway.md +375 -0
- package/content/connections/anthropic.md +169 -2
- package/content/connections/awss3.md +178 -2
- package/content/connections/axioshttp.md +181 -0
- package/content/connections/google.md +169 -2
- package/content/connections/mongodb.md +1014 -3
- package/content/connections/openai-connection.md +169 -2
- package/content/connections/sendgridmail.md +3 -0
- package/content/connections/smtp.md +16 -0
- package/content/connections/treg.md +329 -0
- package/content/container-blocks/affix.md +47 -7
- package/content/container-blocks/alert.md +76 -24
- package/content/container-blocks/badge.md +100 -24
- package/content/container-blocks/box.md +9 -9
- package/content/container-blocks/card.md +132 -27
- package/content/container-blocks/carousel.md +60 -7
- package/content/container-blocks/collapse.md +153 -9
- package/content/container-blocks/configprovider.md +35 -13
- package/content/container-blocks/confirmmodal.md +69 -23
- package/content/container-blocks/content.md +62 -98
- package/content/container-blocks/descriptions.md +45 -4
- package/content/container-blocks/drawer.md +139 -28
- package/content/container-blocks/dropdownmenu.md +119 -31
- package/content/container-blocks/flex.md +40 -62
- package/content/container-blocks/footer.md +15 -11
- package/content/container-blocks/googlemapsheatmap.md +1 -1
- package/content/container-blocks/googlemapsscript.md +2 -2
- package/content/container-blocks/header.md +71 -36
- package/content/container-blocks/label.md +34 -7
- package/content/container-blocks/layout.md +52 -34
- package/content/container-blocks/masonry.md +17 -71
- package/content/container-blocks/mobilemenu.md +131 -88
- package/content/container-blocks/modal.md +161 -26
- package/content/container-blocks/pageheadermenu.md +138 -31
- package/content/container-blocks/pagesidebarlayout.md +230 -27
- package/content/container-blocks/pagesidermenu.md +153 -43
- package/content/container-blocks/popover.md +34 -31
- package/content/container-blocks/result.md +32 -21
- package/content/container-blocks/sider.md +85 -122
- package/content/container-blocks/span.md +7 -7
- package/content/container-blocks/spinner.md +3 -3
- package/content/container-blocks/splitter.md +150 -68
- package/content/container-blocks/tabs.md +64 -12
- package/content/container-blocks/tooltip.md +22 -46
- package/content/container-blocks/watermark.md +22 -4
- package/content/controls/parallel_for.md +21 -2
- package/content/controls/reject.md +26 -3
- package/content/controls/return.md +17 -1
- package/content/controls/throw.md +30 -2
- package/content/controls/try.md +24 -2
- package/content/controls/while.md +46 -0
- package/content/deployment/deployment-environments.md +146 -0
- package/content/deployment/docker.md +23 -7
- package/content/deployment/node-server.md +4 -0
- package/content/deployment/vercel.md +25 -19
- package/content/display-blocks/aggrid.md +33 -16
- package/content/display-blocks/anchor.md +16 -15
- package/content/display-blocks/avatar.md +57 -37
- package/content/display-blocks/breadcrumb.md +70 -21
- package/content/display-blocks/button.md +93 -19
- package/content/display-blocks/calendar.md +12 -0
- package/content/display-blocks/clickablehtml.md +239 -0
- package/content/display-blocks/dangeroushtml.md +1 -1
- package/content/display-blocks/difflist.md +1 -1
- package/content/display-blocks/difftimeline.md +1 -1
- package/content/display-blocks/divider.md +64 -3
- package/content/display-blocks/dropdownbutton.md +81 -30
- package/content/display-blocks/echart.md +35 -1
- package/content/display-blocks/eventlog.md +363 -0
- package/content/display-blocks/floatbutton.md +129 -42
- package/content/display-blocks/html.md +61 -1
- package/content/display-blocks/icon.md +250 -67
- package/content/display-blocks/img.md +2 -2
- package/content/display-blocks/menu.md +146 -73
- package/content/display-blocks/message.md +38 -124
- package/content/display-blocks/notification.md +94 -222
- package/content/display-blocks/paragraph.md +59 -9
- package/content/display-blocks/pollingtimer.md +263 -0
- package/content/display-blocks/progress.md +96 -17
- package/content/display-blocks/qrcode.md +19 -4
- package/content/display-blocks/s3download.md +1 -1
- package/content/display-blocks/search.md +19 -9
- package/content/display-blocks/skeletonbutton.md +1 -0
- package/content/display-blocks/skeletoninput.md +1 -0
- package/content/display-blocks/statistic.md +75 -17
- package/content/display-blocks/steps.md +58 -25
- package/content/display-blocks/table.md +2527 -0
- package/content/display-blocks/tablelight.md +621 -0
- package/content/display-blocks/tag.md +102 -17
- package/content/display-blocks/title.md +50 -11
- package/content/display-blocks/tour.md +33 -23
- package/content/input-blocks/autocomplete.md +81 -9
- package/content/input-blocks/buttonselector.md +45 -8
- package/content/input-blocks/captcha.md +40 -0
- package/content/input-blocks/checkboxselector.md +97 -7
- package/content/input-blocks/checkboxswitch.md +33 -3
- package/content/input-blocks/colorselector.md +63 -14
- package/content/input-blocks/daterangeselector.md +165 -45
- package/content/input-blocks/dateselector.md +139 -41
- package/content/input-blocks/datetimeselector.md +158 -49
- package/content/input-blocks/inputgallery.md +3 -3
- package/content/input-blocks/intentinput.md +207 -0
- package/content/input-blocks/monthselector.md +120 -52
- package/content/input-blocks/multipleselector.md +150 -39
- package/content/input-blocks/numberinput.md +98 -12
- package/content/input-blocks/pagination.md +70 -14
- package/content/input-blocks/paragraphinput.md +51 -37
- package/content/input-blocks/passwordinput.md +60 -6
- package/content/input-blocks/phonenumberinput.md +59 -26
- package/content/input-blocks/placesautocomplete.md +319 -0
- package/content/input-blocks/radioselector.md +83 -7
- package/content/input-blocks/ratingslider.md +57 -26
- package/content/input-blocks/s3uploadbutton.md +24 -24
- package/content/input-blocks/s3uploaddragger.md +3 -3
- package/content/input-blocks/s3uploadphoto.md +5 -5
- package/content/input-blocks/segmentedselector.md +72 -32
- package/content/input-blocks/selector.md +109 -21
- package/content/input-blocks/switch.md +65 -17
- package/content/input-blocks/tableinput.md +445 -0
- package/content/input-blocks/tagmultipleselector.md +114 -0
- package/content/input-blocks/tagselector.md +114 -0
- package/content/input-blocks/textarea.md +32 -3
- package/content/input-blocks/textinput.md +70 -29
- package/content/input-blocks/tiptapinput.md +1 -1
- package/content/input-blocks/tiptapmentioninput.md +2 -2
- package/content/input-blocks/titleinput.md +39 -12
- package/content/input-blocks/treeinput.md +49 -25
- package/content/input-blocks/treemultipleselector.md +127 -10
- package/content/input-blocks/treeselector.md +97 -9
- package/content/input-blocks/upload.md +64 -15
- package/content/input-blocks/uploaddragger.md +17 -1
- package/content/input-blocks/uploadphoto.md +18 -1
- package/content/input-blocks/weekselector.md +120 -55
- package/content/learn/introduction.md +27 -0
- package/content/learn/quickstart.md +53 -0
- package/content/learn/showcase.md +8 -0
- package/content/list-blocks/controlledlist.md +24 -15
- package/content/list-blocks/list.md +11 -11
- package/content/list-blocks/masonrylist.md +7 -34
- package/content/migration/auth-upgrade.md +337 -0
- package/content/migration/upgrade-guide.md +1 -0
- package/content/migration/v3-to-v4.md +417 -0
- package/content/migration/v6-to-v7.md +620 -0
- package/content/operators/_agent.md +155 -0
- package/content/operators/_app.md +2 -1
- package/content/operators/_array.md +122 -1
- package/content/operators/_build.md +1 -0
- package/content/operators/_credential.md +57 -0
- package/content/operators/_cron.md +292 -0
- package/content/operators/_date.md +2 -0
- package/content/operators/_error.md +196 -0
- package/content/operators/_get.md +6 -6
- package/content/operators/_hmac.md +78 -0
- package/content/operators/_js.md +2 -1
- package/content/operators/_location.md +1 -1
- package/content/operators/_media.md +13 -0
- package/content/operators/_module.md +56 -2
- package/content/operators/_operator.md +17 -3
- package/content/operators/_path_params.md +82 -0
- package/content/operators/_ref.md +258 -0
- package/content/operators/_request.md +1 -1
- package/content/operators/_request_details.md +6 -0
- package/content/operators/_type.md +14 -3
- package/content/operators/_url_query.md +2 -0
- package/content/operators/_user.md +3 -3
- package/content/plugins/plugins-actions.md +10 -0
- package/content/plugins/plugins-connections.md +25 -0
- package/content/plugins/plugins-dev.md +66 -0
- package/content/plugins/plugins-icon-sets.md +267 -0
- package/content/plugins/plugins-introduction.md +27 -1
- package/content/plugins/plugins.md +19 -0
- package/content/plugins/posthog.md +359 -0
- package/content/provider-reference/auth-js-providers.md +107 -0
- package/content/provider-reference/openidconnectprovider.md +44 -0
- package/content/recipes/recipes.md +16 -0
- package/content/reference/actions-reference.md +31 -0
- package/content/reference/blocks-reference.md +35 -0
- package/content/reference/cli.md +403 -0
- package/content/reference/connections-reference.md +23 -0
- package/content/reference/operators-reference.md +47 -0
- package/content/reference/reference.md +16 -0
- package/content/reference/schema-reference.md +12 -0
- package/content/testing/config-tests.md +677 -0
- package/content/testing/e2e-configuration.md +31 -1
- package/content/testing/e2e-getting-started.md +1 -1
- package/content/testing/e2e-introduction.md +1 -1
- package/content/testing/e2e-writing-tests.md +12 -1
- package/content/testing/explore-pull-request.md +136 -0
- package/content/testing/journey-data-sets.md +326 -0
- package/content/tutorial/tutorial-actions-operators.md +2 -2
- package/content/tutorial/tutorial-add-blocks.md +2 -2
- package/content/tutorial/tutorial-create-page.md +48 -2
- package/content/tutorial/tutorial-display-data-page.md +3 -3
- package/content/tutorial/tutorial-requests-api.md +155 -0
- package/content/tutorial/tutorial-requests-sql.md +153 -0
- package/content/tutorial/tutorial-start.md +66 -1
- package/content/user-authentication/auth-configuration.md +267 -0
- package/content/user-authentication/auth-providers.md +24 -0
- package/content/user-authentication/auth-steps.md +141 -0
- package/content/user-authentication/login-and-logout.md +160 -8
- package/content/user-authentication/mcp-oauth.md +424 -0
- package/content/user-authentication/organizations.md +246 -0
- package/content/user-authentication/protected-pages-apis.md +97 -0
- package/content/user-authentication/roles.md +49 -0
- package/content/user-authentication/two-factor.md +229 -0
- package/content/user-authentication/user-object.md +58 -0
- package/content/user-authentication/users-introduction.md +8 -0
- package/content/websockets/websocket-publish.md +105 -0
- package/content/websockets/websocket-subscriptions.md +136 -0
- package/content/websockets/websockets-introduction.md +101 -0
- package/hazards.json +56 -0
- package/index.json +3472 -14
- package/package.json +10 -1
- package/scripts/extractAgentDocs.js +41 -30
- package/scripts/hashDocSources.js +38 -0
- package/scripts/isRedirectPage.js +26 -0
- package/scripts/recordSourceHashes.js +97 -0
- package/scripts/resolvePageSections.js +42 -0
- package/scripts/sectionKind.js +27 -0
- package/content/concepts/cli.md +0 -223
- package/content/other/introduction.md +0 -39
- package/content/other/next-auth-providers.md +0 -3
- /package/content/{other → actions}/updatesession.md +0 -0
|
@@ -0,0 +1,246 @@
|
|
|
1
|
+
# Organizations & Multi-Tenancy
|
|
2
|
+
|
|
3
|
+
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.
|
|
4
|
+
|
|
5
|
+
The single knob that decides how organizations behave is `auth.organizations.policy`.
|
|
6
|
+
|
|
7
|
+
## Two policies: `pinned` and `tenant`
|
|
8
|
+
|
|
9
|
+
```yaml
|
|
10
|
+
auth:
|
|
11
|
+
organizations:
|
|
12
|
+
policy: pinned # or "tenant"
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
**`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.
|
|
16
|
+
|
|
17
|
+
**`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.
|
|
18
|
+
|
|
19
|
+
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.
|
|
20
|
+
|
|
21
|
+
## The `organizations` keys
|
|
22
|
+
|
|
23
|
+
| Key | Type | Applies to | Default | Meaning |
|
|
24
|
+
| --- | ---- | ---------- | ------- | ------- |
|
|
25
|
+
| `policy` | `pinned` \| `tenant` | both | `pinned` | The organization model, above. |
|
|
26
|
+
| `org` | string | **pinned only** | `default` | The slug the deployment pins as the active organization. Under `pinned` the slug **is** the organization's id. |
|
|
27
|
+
| `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. |
|
|
28
|
+
| `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). |
|
|
29
|
+
| `invitationExpiresIn` | integer (seconds, min 60) | both | `172800` (48h) | How long an invitation stays acceptable. Re-sending an invitation refreshes its expiry. |
|
|
30
|
+
| `membershipLimit` | integer (min 1) | both | `1000000` (effectively open) | The most members one organization may have. Once an organization has this many, accepting an invitation and adding a member are refused (a 403). Set it to cap organization size, for example per tenant. It is also the default page size of `ListMembers` when no `limit` is given. |
|
|
31
|
+
|
|
32
|
+
The build cross-checks these, and the errors are worth knowing before you hit them:
|
|
33
|
+
|
|
34
|
+
- **`org` is required under `pinned`** and **rejected under `tenant`** — under `tenant` there is no single organization to pin; organizations are created per user.
|
|
35
|
+
- **`create` is rejected under `pinned`** — the active organization is ensured at startup, so there is nothing to create on demand.
|
|
36
|
+
- **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.
|
|
37
|
+
|
|
38
|
+
Defaults line up with intent: `pinned` defaults to a closed, invite-only internal app; `tenant` defaults to self-serve SaaS (`signup: open`, `create: auto`).
|
|
39
|
+
|
|
40
|
+
### The organization `create: auto` mints
|
|
41
|
+
|
|
42
|
+
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.
|
|
43
|
+
|
|
44
|
+
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):
|
|
45
|
+
|
|
46
|
+
```js
|
|
47
|
+
db['user-organizations'].createIndex({ slug: 1 }, { unique: true })
|
|
48
|
+
db['user-members'].createIndex({ user_id: 1, organization_id: 1 }, { unique: true })
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
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.
|
|
52
|
+
|
|
53
|
+
### Invitations for existing members
|
|
54
|
+
|
|
55
|
+
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.
|
|
56
|
+
|
|
57
|
+
## The `owner` / `admin` / `member` tier vs app roles
|
|
58
|
+
|
|
59
|
+
A membership carries **two** independent role authorities, and keeping them apart is the whole point:
|
|
60
|
+
|
|
61
|
+
- **`_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.**
|
|
62
|
+
- **`_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.
|
|
63
|
+
|
|
64
|
+
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.
|
|
65
|
+
|
|
66
|
+
## Bootstrapping the first administrator
|
|
67
|
+
|
|
68
|
+
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).
|
|
69
|
+
|
|
70
|
+
## The tenant wall
|
|
71
|
+
|
|
72
|
+
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*.
|
|
73
|
+
|
|
74
|
+
### Declaring scope on a connection
|
|
75
|
+
|
|
76
|
+
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:
|
|
77
|
+
|
|
78
|
+
```yaml
|
|
79
|
+
connections:
|
|
80
|
+
# Scoped by default under tenant policy — nothing to declare.
|
|
81
|
+
- id: app_data
|
|
82
|
+
type: MongoDBCollection
|
|
83
|
+
properties:
|
|
84
|
+
databaseUri:
|
|
85
|
+
_secret: MONGODB_URI
|
|
86
|
+
collection: records
|
|
87
|
+
|
|
88
|
+
# Data deliberately shared across organizations (reference data,
|
|
89
|
+
# a global catalogue) — opt out of scoping explicitly.
|
|
90
|
+
- id: countries
|
|
91
|
+
type: MongoDBCollection
|
|
92
|
+
tenant: shared
|
|
93
|
+
properties:
|
|
94
|
+
databaseUri:
|
|
95
|
+
_secret: MONGODB_URI
|
|
96
|
+
collection: countries
|
|
97
|
+
|
|
98
|
+
# Scope on a field other than the default organization_id.
|
|
99
|
+
- id: legacy_records
|
|
100
|
+
type: MongoDBCollection
|
|
101
|
+
tenant:
|
|
102
|
+
field: tenant_id
|
|
103
|
+
properties:
|
|
104
|
+
databaseUri:
|
|
105
|
+
_secret: MONGODB_URI
|
|
106
|
+
collection: legacy
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
`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.
|
|
110
|
+
|
|
111
|
+
**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.
|
|
112
|
+
|
|
113
|
+
**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`: inserted and replacement documents must carry it, upserts must author it (`$set` / `$setOnInsert`, or an equality match in the filter), and updates may not null, unset, rename or otherwise overwrite it with a value the wall can not verify. 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.
|
|
114
|
+
|
|
115
|
+
**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. Return the documents and write them with `MongoDBInsertMany` or `MongoDBBulkWrite`, which check every row. A target named by an operator, or in another database, is not checked at build time.
|
|
116
|
+
|
|
117
|
+
**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.
|
|
118
|
+
|
|
119
|
+
### Exceptions at the point of use
|
|
120
|
+
|
|
121
|
+
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:
|
|
122
|
+
|
|
123
|
+
| Surface | Allowed values | Meaning |
|
|
124
|
+
| ------- | -------------- | ------- |
|
|
125
|
+
| Request | `none` | Read rows of every organization. The request may only read (see below). |
|
|
126
|
+
| Request | `authored` | The request authors its own tenant clause (audited at runtime). |
|
|
127
|
+
| Websocket | `none` | Watch rows of every organization. `authored` is not allowed — change streams are always scoped mechanically. |
|
|
128
|
+
|
|
129
|
+
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.
|
|
130
|
+
|
|
131
|
+
```yaml
|
|
132
|
+
# A $search aggregation on a scoped connection: author the org filter
|
|
133
|
+
# inside the stage and declare it.
|
|
134
|
+
id: search_records
|
|
135
|
+
type: MongoDBAggregation
|
|
136
|
+
connectionId: app_data
|
|
137
|
+
tenant: authored
|
|
138
|
+
properties:
|
|
139
|
+
pipeline:
|
|
140
|
+
- $search:
|
|
141
|
+
compound:
|
|
142
|
+
filter:
|
|
143
|
+
- equals:
|
|
144
|
+
path: organization_id
|
|
145
|
+
value:
|
|
146
|
+
_user: organization_id
|
|
147
|
+
must:
|
|
148
|
+
- text:
|
|
149
|
+
query:
|
|
150
|
+
_payload: q
|
|
151
|
+
path: title
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
### `tenant: none` only reads
|
|
155
|
+
|
|
156
|
+
`tenant: none` lifts the filter, so a request can read rows of every organization: enumerate the organizations to fan out over, or count across tenants. It never writes. A request or step with `tenant: none` whose type writes (`MongoDBInsertOne`, `MongoDBUpdateMany`, `MongoDBBulkWrite`, the table and enrichment writes, and the rest) fails the build on a scoped connection, and the same write is refused at runtime. An aggregation under `tenant: none` may not contain `$out` or `$merge`, since they write its output into a collection.
|
|
157
|
+
|
|
158
|
+
To write, do the work as one organization: call an endpoint with a `CallApi` step that names the `organization` (see [Background work in one organization](#background-work-in-one-organization)). Its requests run with the wall on, so every write is filtered and stamped with that organization.
|
|
159
|
+
|
|
160
|
+
**Rollups across organizations** — group walled rows by organization and save the totals, typically from a scheduled endpoint — read with `tenant: none`, then save each organization's totals as that organization:
|
|
161
|
+
|
|
162
|
+
```yaml
|
|
163
|
+
# The scheduled endpoint: one read across organizations, one call per organization.
|
|
164
|
+
routine:
|
|
165
|
+
- id: rollup
|
|
166
|
+
type: MongoDBAggregation
|
|
167
|
+
connectionId: orders
|
|
168
|
+
tenant: none
|
|
169
|
+
properties:
|
|
170
|
+
pipeline:
|
|
171
|
+
- $group:
|
|
172
|
+
_id:
|
|
173
|
+
organization_id: $organization_id
|
|
174
|
+
month:
|
|
175
|
+
$dateToString:
|
|
176
|
+
format: '%Y-%m'
|
|
177
|
+
date: $created_at
|
|
178
|
+
total:
|
|
179
|
+
$sum: $amount
|
|
180
|
+
- $group:
|
|
181
|
+
_id: $_id.organization_id
|
|
182
|
+
totals:
|
|
183
|
+
$push:
|
|
184
|
+
month: $_id.month
|
|
185
|
+
total: $total
|
|
186
|
+
- :for: organization
|
|
187
|
+
:in:
|
|
188
|
+
_step: rollup
|
|
189
|
+
:do:
|
|
190
|
+
- id: save
|
|
191
|
+
type: CallApi
|
|
192
|
+
properties:
|
|
193
|
+
endpointId: save_monthly_totals
|
|
194
|
+
organization:
|
|
195
|
+
_item: organization._id
|
|
196
|
+
payload:
|
|
197
|
+
totals:
|
|
198
|
+
_item: organization.totals
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
```yaml
|
|
202
|
+
# save_monthly_totals: runs bound to one organization, so the scoped
|
|
203
|
+
# monthly_totals connection filters and stamps every write with it.
|
|
204
|
+
routine:
|
|
205
|
+
- id: save_totals
|
|
206
|
+
type: MongoDBBulkWrite
|
|
207
|
+
connectionId: monthly_totals
|
|
208
|
+
properties:
|
|
209
|
+
operations:
|
|
210
|
+
_array.map:
|
|
211
|
+
- _payload: totals
|
|
212
|
+
- _function:
|
|
213
|
+
replaceOne:
|
|
214
|
+
filter:
|
|
215
|
+
month:
|
|
216
|
+
__args: 0.month
|
|
217
|
+
replacement:
|
|
218
|
+
__args: 0
|
|
219
|
+
upsert: true
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
Each organization reads its own totals through the scoped `monthly_totals` connection.
|
|
223
|
+
|
|
224
|
+
### Background work in one organization
|
|
225
|
+
|
|
226
|
+
A scheduled run, an auth hook or a verified webhook has no caller, so it has no organization, and a walled request in it fails closed. To do one organization's work from such a run, call the endpoint that does it with a `CallApi` step that names the `organization`, and optionally a stand-in `caller`:
|
|
227
|
+
|
|
228
|
+
```yaml
|
|
229
|
+
- id: sweep
|
|
230
|
+
type: CallApi
|
|
231
|
+
properties:
|
|
232
|
+
endpointId: send_reminders
|
|
233
|
+
organization:
|
|
234
|
+
_item: organization_id
|
|
235
|
+
caller:
|
|
236
|
+
id: reminders
|
|
237
|
+
name: Reminders
|
|
238
|
+
```
|
|
239
|
+
|
|
240
|
+
The called endpoint runs bound to that organization: its walled requests are filtered and stamped with it, with the wall on, and `_user` is `{ id, name, organization_id, system: true }` (or null without `caller`), so routines that stamp writes with the caller run unchanged. This is how a caller-less run writes: `tenant: none` only reads. Only a trusted system run may bind; a signed-in caller can not name another organization. See [Running in One Organization](/lowdefy-api#running-in-one-organization).
|
|
241
|
+
|
|
242
|
+
### Why the wall lives on the connection
|
|
243
|
+
|
|
244
|
+
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.
|
|
245
|
+
|
|
246
|
+
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.
|
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
# Protected Pages and APIs
|
|
2
|
+
|
|
3
|
+
By default, all pages and APIs in a Lowdefy app are public. API endpoints, agents and websockets a [module](/module-authoring) ships are the exception: when the app has auth configured, they need a signed-in caller unless the module's manifest or an app `public` rule makes them 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.
|
|
4
|
+
|
|
5
|
+
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.
|
|
6
|
+
|
|
7
|
+
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.
|
|
8
|
+
|
|
9
|
+
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.
|
|
10
|
+
|
|
11
|
+
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.
|
|
12
|
+
|
|
13
|
+
## Examples
|
|
14
|
+
|
|
15
|
+
###### List specific public pages and APIs:
|
|
16
|
+
```yaml
|
|
17
|
+
lowdefy: 6.1.0
|
|
18
|
+
auth:
|
|
19
|
+
pages:
|
|
20
|
+
protected: true
|
|
21
|
+
public:
|
|
22
|
+
- '404'
|
|
23
|
+
- login
|
|
24
|
+
- public-page
|
|
25
|
+
api:
|
|
26
|
+
protected: true
|
|
27
|
+
public:
|
|
28
|
+
- health_check
|
|
29
|
+
- get_public_content
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
###### List specific protected pages and APIs:
|
|
33
|
+
```yaml
|
|
34
|
+
lowdefy: 6.1.0
|
|
35
|
+
auth:
|
|
36
|
+
pages:
|
|
37
|
+
public: true
|
|
38
|
+
protected:
|
|
39
|
+
- admin
|
|
40
|
+
- users
|
|
41
|
+
api:
|
|
42
|
+
public: true
|
|
43
|
+
protected:
|
|
44
|
+
- update_user_settings
|
|
45
|
+
- admin_dashboard_api
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
###### Mixed configuration:
|
|
49
|
+
```yaml
|
|
50
|
+
lowdefy: 6.1.0
|
|
51
|
+
auth:
|
|
52
|
+
# Protect specific pages while keeping most public
|
|
53
|
+
pages:
|
|
54
|
+
public: true
|
|
55
|
+
protected:
|
|
56
|
+
- dashboard
|
|
57
|
+
- profile
|
|
58
|
+
- settings
|
|
59
|
+
|
|
60
|
+
# Protect all API endpoints
|
|
61
|
+
api:
|
|
62
|
+
protected: true
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
## Wildcard Patterns
|
|
66
|
+
|
|
67
|
+
Page and API access rules support glob patterns using `*` and `**` wildcards. This is useful for granting access to all pages from a [module](/modules):
|
|
68
|
+
|
|
69
|
+
- `team-users/*` — matches all pages in the `team-users` module
|
|
70
|
+
- `team-*/*` — matches all pages in modules with IDs starting with `team-`
|
|
71
|
+
- `*/settings` — matches the `settings` page in any module
|
|
72
|
+
- `**` — matches all pages
|
|
73
|
+
|
|
74
|
+
Exact page IDs still work: `home`, `team-users/users-list`.
|
|
75
|
+
|
|
76
|
+
###### Wildcard pattern example:
|
|
77
|
+
```yaml
|
|
78
|
+
lowdefy: 6.1.0
|
|
79
|
+
auth:
|
|
80
|
+
pages:
|
|
81
|
+
protected: true
|
|
82
|
+
public:
|
|
83
|
+
- home
|
|
84
|
+
- login
|
|
85
|
+
roles:
|
|
86
|
+
admin:
|
|
87
|
+
- team-users/*
|
|
88
|
+
- admin/*
|
|
89
|
+
user:
|
|
90
|
+
- notifications/*
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
## Important Notes
|
|
94
|
+
|
|
95
|
+
- Pages and APIs are configured separately - protecting pages does not automatically protect APIs
|
|
96
|
+
- Protected resources require users to be authenticated before access is granted
|
|
97
|
+
- Role-based access control can be layered on top of protection for finer-grained permissions
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
# Roles
|
|
2
|
+
|
|
3
|
+
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.
|
|
4
|
+
|
|
5
|
+
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.
|
|
6
|
+
|
|
7
|
+
Declare the role names your app uses in `auth.roles` (id, optional label and description) so tooling can list them:
|
|
8
|
+
|
|
9
|
+
```yaml
|
|
10
|
+
lowdefy: 6.1.0
|
|
11
|
+
auth:
|
|
12
|
+
roles:
|
|
13
|
+
- id: user-admin
|
|
14
|
+
label: User Administrator
|
|
15
|
+
- id: sales
|
|
16
|
+
- id: reports
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
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).
|
|
20
|
+
|
|
21
|
+
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.
|
|
22
|
+
|
|
23
|
+
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.
|
|
24
|
+
|
|
25
|
+
###### Protect pages and API endpoints using roles:
|
|
26
|
+
```yaml
|
|
27
|
+
lowdefy: 6.1.0
|
|
28
|
+
auth:
|
|
29
|
+
pages:
|
|
30
|
+
public: true
|
|
31
|
+
roles:
|
|
32
|
+
user-admin:
|
|
33
|
+
- users
|
|
34
|
+
- new-user
|
|
35
|
+
- edit-user
|
|
36
|
+
sales:
|
|
37
|
+
- customers
|
|
38
|
+
- new-customer
|
|
39
|
+
- edit-customer
|
|
40
|
+
reports:
|
|
41
|
+
- sales-report
|
|
42
|
+
- operations-report
|
|
43
|
+
api:
|
|
44
|
+
protected: true
|
|
45
|
+
roles:
|
|
46
|
+
user-admin:
|
|
47
|
+
- create-user
|
|
48
|
+
- update-user
|
|
49
|
+
````
|
|
@@ -0,0 +1,229 @@
|
|
|
1
|
+
# Two-Factor Authentication
|
|
2
|
+
|
|
3
|
+
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.
|
|
4
|
+
|
|
5
|
+
## Enabling it
|
|
6
|
+
|
|
7
|
+
```yaml
|
|
8
|
+
auth:
|
|
9
|
+
twoFactor:
|
|
10
|
+
enabled: true
|
|
11
|
+
authPages:
|
|
12
|
+
twoFactor: /two-factor-challenge
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
`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.
|
|
16
|
+
|
|
17
|
+
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.
|
|
18
|
+
|
|
19
|
+
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.
|
|
20
|
+
|
|
21
|
+
## Which sign-in methods are challenged
|
|
22
|
+
|
|
23
|
+
| Sign-in method | Challenged |
|
|
24
|
+
| ------------------------------ | ----------------------------------- |
|
|
25
|
+
| Email + password | Yes |
|
|
26
|
+
| Phone number + password | Yes |
|
|
27
|
+
| Magic link | Yes — always, no toggle |
|
|
28
|
+
| SMS code (`PhoneNumberVerify`) | Yes — always, no toggle |
|
|
29
|
+
| OAuth provider | Yes, unless the provider is trusted |
|
|
30
|
+
| Passkey (`PasskeySignIn`) | No — deliberately |
|
|
31
|
+
|
|
32
|
+
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.
|
|
33
|
+
|
|
34
|
+
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.
|
|
35
|
+
|
|
36
|
+
### The engine routes the challenge
|
|
37
|
+
|
|
38
|
+
[`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.
|
|
39
|
+
|
|
40
|
+
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.
|
|
41
|
+
|
|
42
|
+
### A challenge page routes nothing
|
|
43
|
+
|
|
44
|
+
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.
|
|
45
|
+
|
|
46
|
+
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.
|
|
47
|
+
|
|
48
|
+
`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.
|
|
49
|
+
|
|
50
|
+
### Trusting a device
|
|
51
|
+
|
|
52
|
+
`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.
|
|
53
|
+
|
|
54
|
+
## Trusting an OAuth provider
|
|
55
|
+
|
|
56
|
+
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:
|
|
57
|
+
|
|
58
|
+
```yaml
|
|
59
|
+
auth:
|
|
60
|
+
providers:
|
|
61
|
+
- id: corp-idp
|
|
62
|
+
type: GenericOAuth
|
|
63
|
+
twoFactorTrusted: true
|
|
64
|
+
properties: ...
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
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.
|
|
68
|
+
|
|
69
|
+
**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.
|
|
70
|
+
|
|
71
|
+
`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.
|
|
72
|
+
|
|
73
|
+
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.
|
|
74
|
+
|
|
75
|
+
## Known limitation: TOTP codes are replayable within their window
|
|
76
|
+
|
|
77
|
+
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.
|
|
78
|
+
|
|
79
|
+
This violates the standards:
|
|
80
|
+
|
|
81
|
+
- 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."
|
|
82
|
+
- OWASP ASVS 5.0 §6.5.1 (L2), which requires the same single-use property.
|
|
83
|
+
|
|
84
|
+
**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.
|
|
85
|
+
|
|
86
|
+
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.
|
|
87
|
+
|
|
88
|
+
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.
|
|
89
|
+
|
|
90
|
+
If you are enabling multi-factor authentication to satisfy an auditor, know about this before the auditor tells you.
|
|
91
|
+
|
|
92
|
+
## Concurrent enrolment and the unique index
|
|
93
|
+
|
|
94
|
+
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).
|
|
95
|
+
|
|
96
|
+
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`:
|
|
97
|
+
|
|
98
|
+
```js
|
|
99
|
+
db['user-two-factors'].createIndex({ user_id: 1 }, { unique: true });
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
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.
|
|
103
|
+
|
|
104
|
+
## Requiring two-factor enrolment
|
|
105
|
+
|
|
106
|
+
`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.
|
|
107
|
+
|
|
108
|
+
```yaml
|
|
109
|
+
auth:
|
|
110
|
+
twoFactor:
|
|
111
|
+
enabled: true
|
|
112
|
+
required: true
|
|
113
|
+
authPages:
|
|
114
|
+
twoFactor: /two-factor-challenge
|
|
115
|
+
twoFactorEnrol: /two-factor-enrol
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
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.
|
|
119
|
+
|
|
120
|
+
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".
|
|
121
|
+
|
|
122
|
+
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.
|
|
123
|
+
|
|
124
|
+
`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.
|
|
125
|
+
|
|
126
|
+
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.
|
|
127
|
+
|
|
128
|
+
## What `required` guarantees — and what it does not
|
|
129
|
+
|
|
130
|
+
> `required` guarantees that every member has enrolled a factor. It does NOT guarantee that every session presented one.
|
|
131
|
+
|
|
132
|
+
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.
|
|
133
|
+
|
|
134
|
+
This is an accepted cost, for three reasons:
|
|
135
|
+
|
|
136
|
+
- 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.
|
|
137
|
+
- 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.
|
|
138
|
+
- 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.
|
|
139
|
+
|
|
140
|
+
## Two-factor with a trusted OAuth provider
|
|
141
|
+
|
|
142
|
+
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.
|
|
143
|
+
|
|
144
|
+
The cost, stated plainly: a deployment whose **only** sign-in path is a trusted provider gets enrolment with no challenge ever attached to it.
|
|
145
|
+
|
|
146
|
+
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.
|
|
147
|
+
|
|
148
|
+
## Two-factor for passwordless users
|
|
149
|
+
|
|
150
|
+
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.
|
|
151
|
+
|
|
152
|
+
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.
|
|
153
|
+
|
|
154
|
+
## The enrolment page
|
|
155
|
+
|
|
156
|
+
`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.
|
|
157
|
+
|
|
158
|
+
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.
|
|
159
|
+
|
|
160
|
+
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.
|
|
161
|
+
|
|
162
|
+
## Recovering a user who has lost their factor
|
|
163
|
+
|
|
164
|
+
When a member loses their authenticator or has a security key stolen, an administrator restores their access with two org-scoped steps:
|
|
165
|
+
|
|
166
|
+
| Step | Properties | Permission |
|
|
167
|
+
| ----------------------------------------------- | --------------------- | ----------------------------- |
|
|
168
|
+
| `ResetUserTwoFactor` | `userId` | `user: ['reset-two-factor']` |
|
|
169
|
+
| `RevokeUserPasskeys` | `userId`, `passkeyId?`| `user: ['revoke-passkeys']` |
|
|
170
|
+
|
|
171
|
+
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.
|
|
172
|
+
|
|
173
|
+
Three things this routine must not miss:
|
|
174
|
+
|
|
175
|
+
**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:
|
|
176
|
+
|
|
177
|
+
```yaml
|
|
178
|
+
id: admin-recover-user-two-factor
|
|
179
|
+
type: Api
|
|
180
|
+
routine:
|
|
181
|
+
- id: reset_two_factor
|
|
182
|
+
type: ResetUserTwoFactor
|
|
183
|
+
properties:
|
|
184
|
+
userId:
|
|
185
|
+
_payload: userId
|
|
186
|
+
- id: revoke_passkeys
|
|
187
|
+
type: RevokeUserPasskeys
|
|
188
|
+
properties:
|
|
189
|
+
userId:
|
|
190
|
+
_payload: userId
|
|
191
|
+
- id: revoke_sessions
|
|
192
|
+
type: RevokeUserSessions
|
|
193
|
+
properties:
|
|
194
|
+
userId:
|
|
195
|
+
_payload: userId
|
|
196
|
+
- ':return':
|
|
197
|
+
_step: revoke_sessions
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
**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.
|
|
201
|
+
|
|
202
|
+
**`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.
|
|
203
|
+
|
|
204
|
+
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.
|
|
205
|
+
|
|
206
|
+
## Before you turn `required` on
|
|
207
|
+
|
|
208
|
+
**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.
|
|
209
|
+
|
|
210
|
+
**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.
|
|
211
|
+
|
|
212
|
+
**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:
|
|
213
|
+
|
|
214
|
+
1. Delete the target's row from the `user-two-factors` collection.
|
|
215
|
+
2. Set `twoFactorEnabled` to `false` on their row in the `users` collection.
|
|
216
|
+
|
|
217
|
+
That administrator can then sign in and recover the others through the app.
|
|
218
|
+
|
|
219
|
+
## Required index
|
|
220
|
+
|
|
221
|
+
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:
|
|
222
|
+
|
|
223
|
+
```js
|
|
224
|
+
db['user-passkeys'].createIndex({ user_id: 1 });
|
|
225
|
+
```
|
|
226
|
+
|
|
227
|
+
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 }`.)
|
|
228
|
+
|
|
229
|
+
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.
|