use-auth

Informational, not binding. Know a better way for the case in front of you — do it your way and say so. You are trusted with the creative work on this project.

1. 🔒 One database, and the accounts are already in it

DATABASE_URL of the auth service points at the same file as the app — on a live server, file:/opt/fractera/app/data/app.db. So users sits beside products, and the data layer :3300 lists it like any other table.

This is worth stating because the code's DEFAULT says otherwise: services/auth/lib/db/index.ts falls back to its own data/auth.db, and reading only that line leads to "two separate databases", which is false on every deployment. Check the running configuration, not the fallback.

Consequence, and it is the useful half: you do not need the auth service to READ accounts. The data layer answers /db/tables/users, and lib/db reaches it the same way it reaches products.

2. The four tables, and what each is for

🔒 These four are NOT declared in your SCHEMA (lib/db/index.ts), and that is correct. The auth service creates and migrates them. Do not add them to SCHEMA "so they are visible" — two owners of one table is how a migration silently reverts somebody's column.

🔒 DELETING ANY OF THE FOUR DESTROYS EVERY ACCOUNT ON THE SERVER, including the owner's own, and app.db is not in git — there is nothing to restore from. The same goes for dropping columns and renaming them. A "cleanup" that removes tables your SCHEMA does not mention would take these first; that is precisely why this paragraph exists.

password is a bcrypt hash and never leaves the database. The data layer strips it, along with session and provider tokens, on the way out (SECRET_COLUMNS in services/data/server.js). Do not route around that: a hash that left the database lives on in logs, in answers and in an agent's context, where it cannot be taken back. Verifying a password is the service's job and yours never.

3. What the service does that a table cannot tell you

:3001 owns everything about BECOMING logged in: the login and registration forms (they live on auth.<domain>, not in your app), the session cookie, provider sign-in, is_active enforcement. Your app never sees the moment of login — it sees a ready cookie. lib/auth/get-session.ts asks :3001/api/session and gets { userId, email, roles } or nothing.

Its admin doors, when you do need them: GET /api/admin/users (list, paged, q search) and PATCH|DELETE /api/admin/users/:id. PATCH accepts nickname, email, roles, is_active — there is no password change in the API, though the column exists.

Out of the box: registration and login by password, roles, sessions. Missing: password recovery — a person who forgets theirs cannot get back in without the owner. Google sign-in and email through Resend are prepared and need only keys in the panel. Underneath is NextAuth with some eighty other providers; wiring any of them is a request to the Fractera developers, not slot work.

3a. 🔒 Where authentication physically lives in THIS repository

Nothing about it is hidden: read these eight files and you know the whole mechanism. Without that reading the work is not hard, it is guesswork — which is why this map is here rather than a description of it.

The flow, in one pass. A visitor opens a protected address → proxy.ts checks for authjs.session-token (or __Secure-authjs.session-token behind HTTPS) → no cookie and the path is under /api/* → 401 immediately; a page instead renders and its AccessGate explains → the person follows the link to auth.<domain>/login, a page of the auth service, not of this app → the service sets the cookie on the shared parent domain → back on your page get-session.ts exchanges that cookie for roles → your door compares them with requireRoles.

🔒 Two consequences that catch people out. First: on localhost the owner at the keyboard opens the architect layer without any login (lib/auth/owner-at-machine.ts), and in local dev the bypass does the same — a screen that works for you there may refuse everyone on the domain, so say which address you tested on. The node does not answer on the computer's network IP at all. Second: the login page is a different origin, so never <Link prefetch> it — check:links refuses that, because the prefetch fails on CORS.

4. 🔒 Rules that must hold wherever roles are written

Whichever path you use — the data layer or the service — these are the rules, and they must live in exactly ONE place. Splitting them between your door and the service is how they drift apart.

• A role must exist in ALL_ROLES (lib/roles.ts). The body of a request comes from a browser; an invented role does not fail loudly, it simply opens nothing, and that is found months later.
• An account keeps at least one role. No roles is not "a guest" — a guest is the absence of an account.
• Nobody edits their own account through an admin screen: that is what stops a person removing their own architect and locking the project.
• Only an architect grants or removes architect. An administrator who could hand it out would hand it to their own second account, and the difference between the two roles would vanish the same day. Compare the CURRENT roles with the REQUESTED ones — the rule guards that one role, not every edit.
• A changed role reaches a signed-in person on their next session read, not instantly. Say so rather than promising immediacy.

roles is stored as a JSON string, so parse it in one place and hand the array around; two parsers give one account two different sets of roles on the same screen.

5. Building a screen about accounts

It is the dynamic-page model, and use-dynamic-pages carries the shape: static shell, data through /api/*, requireRoles first line of the door — proxy.ts only proves a session EXISTS, so without it any signed-in person reaches any role's data. Built example to copy: app/[lang]/(protectedLayer)/(admin)/administration/users/ with app/api/users/.

Never render password, never log a whole row, and remember sessions and accounts hold tokens that are as good as a password.

6. Before you call it done

• Three states on the deployment, not one: guest → 401, signed in with the wrong role → 403 naming the role, right role → the data.
• Fetch the page as a guest and grep the markup for account data. Nothing may be there — the shell is prerendered.
• Read your own response body once: if password, session_token or a provider token appears in it, stop and fix the door, not the page.