@sanoma-ai/connector-better-auth 0.2.4 → 0.2.6

package/README.md

@@ -35,7 +35,7 @@ It has no credential. Better Auth signs its cookies with a key the app derives f
 
 ### The schema
 
-The tables (`user`, `session`, `account`, `verification`) are in the schema `better_auth` on the company's database (`SANOMA_DATABASE_URL`), beside the runtime's own, in queries that name the schema (no `search_path`, which the URL's own `options` could change). The login runs Better Auth's migrations when the app starts, before it serves the site: once per database in a process, under a Postgres advisory lock, so several processes starting at once do not race. A second start changes nothing.
+The tables (`user`, `session`, `account`, `verification`, and `rate_limit`, the rate limit's counts; snake_case columns, as the runtime's own tables) are in the schema `better_auth` on the company's database (`SANOMA_DATABASE_URL`), beside the runtime's own, in queries that name the schema (no `search_path`, which the URL's own `options` could change), reached through the pool the app gives the login (`LoginContext.database`: the app's one pool on Node, the request's own on a Worker, with one Better Auth instance per pool and nothing else kept across requests). The worker makes them at its start, as it makes the runtime's own tables: `prepareBetterAuth`, the connector's `prepare`, applies the migrations the package ships (its `drizzle/` folder, generated from the tables' declaration, recorded in the journal table `drizzle.__drizzle_migrations_better_auth`) on the database's direct URL under the runtime's preparation lock, so two workers starting at once do not race, and a second run changes nothing; the `sanoma` bin's worker runs `prepareBetterAuthStaff` the same way for the staff sign-in's schema, which no config names. The app never migrates: a login whose first request finds a database the worker has not prepared yet, or has prepared for an older version, waits a minute for a worker starting beside the app, then refuses, saying so (start the worker first, or with it). The worker trusts the journal, as it does for the runtime's own tables: to reset a login, drop its schema and its journal table together (`DROP SCHEMA better_auth CASCADE; DROP TABLE drizzle.__drizzle_migrations_better_auth;`), and the next worker makes both again. A schema a release before this one made (on Better Auth's own migrations, whose columns are named otherwise) has no journal: the worker refuses it, naming the drop, and its users sign in again. Nothing of the session is cached in the cookie: every request reads its session row, so a revoked session is gone at once.
 
 ### The routes
 
@@ -58,7 +58,7 @@ const response = await fetch("/auth/better-auth/sign-in/email", {
 if (response.ok) window.location.reload(); // the app reads the new session cookie
 ```
 
-The session is one cookie, `better-auth.session_token` (`__Secure-better-auth.session_token`, and `Secure`, when the site is served over https): HttpOnly, SameSite=Lax, for the site's host only (no `Domain`), for seven days from sign-in. A request for a host that is not the site's is answered 421. Sign-in and sign-up are rate limited per visitor address (three tries in ten seconds), which the app gives the login in its own header, never from `X-Forwarded-For`. A site never imports `better-auth`: its pages only post to these routes.
+The session is one cookie, `better-auth.session_token` (`__Secure-better-auth.session_token`, and `Secure`, when the site is served over https): HttpOnly, SameSite=Lax, for the site's host only (no `Domain`), for seven days from sign-in. A request for a host that is not the site's is answered 421. Sign-in and sign-up are rate limited per visitor address (three tries in ten seconds), which the app gives the login in its own header, never from `X-Forwarded-For`; the counts are rows in the schema's `rateLimit` table, so the limit holds across processes and requests. A site never imports `better-auth`: its pages only post to these routes.
 
 ### An email code
 
@@ -100,16 +100,16 @@ Each `callbackURL` (and `errorCallbackURL`, where an error goes as `?error=<code
 
 ## The staff sign-in
 
-`betterAuthStaffLogin` is the app's sign-in for the company's own people on a host, which the `sanoma` bin uses off this machine (`staffLogin(betterAuthStaffLogin, { github })` from `@sanoma-ai/app`). Unlike the visitor login, nobody signs up: a code is sent, and an account made, only for an email the people file declares (anyone else gets the same answer, and nothing is stored or sent), or a GitHub login it declares. Its tables are in the schema `better_auth_staff`, migrated under the advisory lock `sanoma.login.better-auth.better_auth_staff`; its cookie is `sanoma.session_token`, for seven days, on whatever host the app answers on. Its ways in, under `/auth/better-auth/`:
+`betterAuthStaffLogin` is the app's sign-in for the company's own people on a host, which the `sanoma` bin uses off this machine (`staffLogin(betterAuthStaffLogin, { github })` from `@sanoma-ai/app`). Unlike the visitor login, nobody signs up: a code is sent, and an account made, only for an email the people file declares (anyone else gets the same answer, and nothing is stored or sent), or a GitHub login it declares. Its tables are in the schema `better_auth_staff`, which the worker makes beside `better_auth` ([the schema](#the-schema)); its cookie is `sanoma.session_token`, for seven days, on whatever host the app answers on. Its ways in, under `/auth/better-auth/`:
 
 - an email code (`/email-otp/send-verification-otp`, `/sign-in/email-otp`), with a sender;
 - GitHub (`/sign-in/social`, back at `/callback/github`), with the company's GitHub App's client, matched by the verified email GitHub gives, else the login (GitHub's `/user` for the sign-in's own token, which is then dropped; the App needs the account permission "Email addresses: read", or a private email ends in Better Auth's `?error=email_not_found`); a GitHub account the files declare by neither is refused as `?error=not_declared` (or, when its unverified email is a row's, Better Auth's `account_not_linked`), with no row left, as is a new GitHub account under a login a row already carries, since GitHub frees a renamed login; declare people by email where you can;
 - an invite (`/magic-link/verify`), a one-use magic link valid 24 hours that the app mints server-side (`invite`), a new one replacing the person's last; Better Auth's own `/sign-in/magic-link` is not served.
 
-Every other Better Auth route is a 404, a POST whose `Origin` is not the request's own host is a 403, and a `callbackURL`, `errorCallbackURL` or `newUserCallbackURL` that is not a path on the request's host is a 400. Invites are minted one at a time. Each sign-in is told to the app (`signin.recorded` in the ledger, with how).
+Every other Better Auth route is a 404, a POST whose `Origin` is not the request's own host is a 403, and a `callbackURL`, `errorCallbackURL` or `newUserCallbackURL` that is not a path on the request's host is a 400. Invites for one email are minted one at a time, whichever process asks (a lock on the database). Each sign-in is told to the app (`signin.recorded` in the ledger, with how).
 
 ### Later
 
-Password reset for visitors, more social providers (Google), and the rate limit kept in the database for several processes.
+Password reset for visitors, and more social providers (Google).
 
 The logo the app shows is Better Auth's mark, from the [Better Auth repository](https://github.com/better-auth/better-auth) (`demo/nextjs/components/logo.tsx`), in black or white. It is there only to identify the service.