Accounts

What it is

This is the module that turns the app into a product other people sign up to. Every account that signs up gets a Chatfuel bot of its own, and can create more — all of them made by this app's server with your master token, inside one workspace of their own that they never learn is one of many. Colleagues arrive by invite and join the inviter's workspace instead of getting one of their own.

Sign-in is Supabase Auth — email and password — on your Supabase project, whose data and keys are yours. The Chatfuel token never leaves the server; what reaches it is the proxy, which has become a gate.

Installed as

Opt-in because it needs credentials the wizard cannot invent: a Supabase project. --yes installs every other ready module and skips this one with a line saying so; name it explicitly to get it.

It is also hidden, which in the manifest means exactly one thing: no rail item and no /auth route. It contributes a host integration instead — the shell wraps itself in the module's Gate, puts the module's item in the user menu, and hands it the routes below. What it changes is who may reach everything else.

The migration is one file and it is the whole schema — every table and every cf_* RPC, idempotent and re-runnable. The supabase/ directory exists in your app only when this module is selected, and every other module's SQL lands in it after this one in name order. There is nothing to seed: a workspace appears when somebody signs up.

Routes and views

Eight routes, and none of them is /auth. The shell knows these first path segments are the module's and never treats them as module ids.

team is the only one in IN_SHELL_ROUTES, and it is opened from the avatar menu rather than from the rail — and only for an owner or an admin. It is one page: members and invites in a single table with a Bots column that opens each person's access and a Reset password link action in the row menu, a Bots table (new, rename, delete), Invite people, and a danger zone holding leave and transfer ownership.

Everything here is written app-relative, because only the shell knows where the app is mounted. The two links that have to be absolute are the two that get mailed — an invite and a recovery link — and the runtime hands those the mount point. A returnTo is app-relative too, is rejected if it names another origin, and never bounces back into an auth screen.

The model

One workspace per account is a database constraint, not a convention: cf_tenants.created_by is unique, which is also what makes sign-up safe from two tabs. At most one owner is a partial unique index on (tenant_id) where role = 'owner'. A bot is a row in cf_bots whose bot_id is unique and null for the seconds between the row existing and Chatfuel answering with a bot; the gate never counts such a row.

Reaching every bot and administering the team are the same pair of roles today and are kept as two separate rules, in the SQL and in lib/roles.ts, because they are different questions. Owners and admins hold no grant rows at all — their access comes from the role, and listing it would read as something revocable. Every RPC that acts on a person — change role, remove, issue a recovery link — refuses a target who is not strictly below the caller, because an admin who could demote a peer could then reset that peer's password.

Every customer's bot comes out of one Chatfuel workspace. CHATFUEL_WORKSPACE_ID names it, the wizard asked which one, and its plan pays for all of them. Adding a bot is two steps: the caller reserves a row with cf_new_bot, as themselves, so the database decides whether they may; then the server creates the bot in Chatfuel with the master token and names it to the row with cf_bot_created, a function granted to service_role and nobody else. If either half fails the other is undone. Plain createBot is not a fallback: it puts each bot in a throwaway workspace with a limit of one and nobody's plan behind it. A deployment without CHATFUEL_WORKSPACE_ID refuses to provision at all.

Two ceilings sit inside cf_new_bot, before Chatfuel is ever asked, and this page is where their numbers live:

Both are one-line SQL functions in your own database. The two variables are read once, by the wizard run that installs the module, and substituted into the migration; they are never written into .env and the app never reads them. Afterwards the only thing that changes a cap is re-running its create or replace with another number in the SQL editor. Past either one the database answers PT429, which the proxy hands on as 429 BotLimitReached. Neither is sized against the Chatfuel plan: when the workspace's own botsLimit runs out, sign-ups and New bot alike answer 409 WorkspaceFull, and raising the caps past the plan only moves the refusal to Chatfuel.

A delete is fenced twice, and both fences answer 409 LastBotInWorkspace with one sentence. A workspace may not delete the bot it can still open — nothing openable is the state provisioning exists to end, and the app answers it by asking for another bot on your plan — and nobody may delete the last bot in CHATFUEL_WORKSPACE_ID, because Chatfuel deletes a workspace when its last bot goes and that would take sign-up away from everybody.

Two trust boundaries do the work, and they answer different questions:

The second one is the isolation boundary, because behind it there is a single Chatfuel account holding every customer's bot. The fence is exact for anything that names a bot — botID in the variables, the root bot(id:) field, every WebSocket subscribe frame — and answers 403 BotNotAllowed without the request ever reaching Chatfuel. Reads that reach for the account (currentUser beyond the fields that name the bot or resource they answer about, and botsV2) are refused with 403 AccountScopeBlocked, precisely because they would hand one customer the list of all the others. An operation that names a flow, a contact or a conversation instead of a bot is fenced by what the proxy has watched being handed out (403 ResourceNotAllowed) — that fence and its modes are on the auth gate. An empty set is still ok: true: signed in, no workspace yet — the state the provisioning route exists to leave.

Sign-up, and who may

Sign-up is the form every SaaS has, and what makes this one different is what follows it: the account gets a workspace, and the server creates a Chatfuel bot for it under your master token, on your plan. Who may open an account is the Supabase project's own Allow new users to sign up toggle, and the wizard asks about it once, on a project it creates:

On a project you brought, the wizard writes none of the three, and a later run on any project leaves them alone — a closed sign-up stays closed. Under open nothing proves an address exists, let alone that the person typing it owns it, and the first account through the door owns the workspace; the server says so on its startup line when sign-ups are open, and again when confirmation is off. To restrict which accounts get a workspace rather than whether anyone may sign up, put a check inside cf_claim_workspace in a migration of your own.

Password recovery

Forgot password cannot deliver mail until you configure SMTP on the project. Until then an owner or admin issues a link from the Team row menu, and the link never appears on their screen: POST /chatfuel/auth/recovery-link answers { "delivered": "server-log" } and writes the URL to the server log as one greppable RECOVERY-LINK line. That link is the account it names until it is used, and a log is read by more people than the route admits, so the write is opt-in: without AUTH_RECOVERY_LINK_LOG=true the route mints nothing and answers 501 RecoveryLinkNotEnabled, which the Team page shows as "Password reset links are not enabled on this deployment". The link is built from PUBLIC_URL and nothing in the request; without it the route answers 409 ProxyPublicUrlMissing.

Who may be named is the database's decision, not the route's. cf_recovery_authorize runs as the caller and requires three things: the target is a member of the caller's workspace, ranks strictly below them, and belongs to no other workspace on this deployment — a link resets an account, not a membership, so a target who also stands elsewhere would carry this workspace's admin into one they were never admitted to. Every issue leaves a row in cf_recovery_events, readable by the workspace's admins and by the person it names, because a log is not a record of who asked.

Configuration

The wizard fills all but the workspace pick from a Supabase personal access token, which it uses once, keeps in memory, and writes nowhere. CHATFUEL_BOT_CAP and CHATFUEL_BOT_TOTAL_CAP are read by that same run and go into the SQL, not into .env. What each variable is and which side reads it is on environment variables.

The migration also creates two tables other parts of the deployment lean on: cf_admin_attempts, the wrong-password counter the admin panel's door shares across instances, and cf_resource_owner, the resource fence's shared memory.

Permissions

The manifest declares no Chatfuel permissions at all. This module asks nothing of the Chatfuel token — it decides who may use the one the deployment already holds.

What stands in their place is two lists. Inside a workspace, the cf_* RPCs are the whole surface: cf_profiles is the one table with a direct grant (select and update, self only), and tenants, members, bots, grants and invites are reachable by function or not at all; the one RPC the anon key may call is cf_invite_preview, which answers a masked address and needs the token itself. On the way out, the gate's answer to cf_my_bot_ids decides every request.

Limits

Saved views and preferences are lost under this module. currentUser.userStorageItem is storage against the Chatfuel account, so allowing it would hand every customer the same list — the proxy answers AccountScopeBlocked. Inbox views and canned responses, Deals' and Contacts' saved views, Knowledge base preferences and Bookings' preferences all degrade to "nothing saved yet". A per-account version would live in Supabase, not in Chatfuel.

Removal is a real lock-out. Somebody removed from a workspace loses it; signing up again gives them a new, empty bot rather than the one they were removed from. That is the difference the bot boundary makes, and it is worth saying out loud before an admin clicks Remove.

Sign-in is email and password only. OAuth and magic link are not wired; the adapter and a footer slot on the sign-in screen are where they would go. There is no second factor and no admin approval step.

The workspace has no settings. It is named after the account that created it and is not editable in the app: one less write path.