@we8/auth

The embedded admin sign-in for a @we8/cms site: Better Auth over the site's own D1, email and password, mounted at /api/auth/*. The first account created becomes the owner and public sign-up closes behind it; every account after that is created by the owner. Password reset goes through the CMS's email seam.

The CMS core has no auth of its own. It knows which capabilities each role holds, and it asks a registered provider who a request is. This package is that provider, and installing it is the answer for anyone who does not already run an identity provider.

Five roles, and the CMS's ROLE_CAPABILITIES is the one place that says what each reaches: owner and full-admin hold everything, content-admin holds the editorial site and its inbox, product-admin holds the catalogue and its assets, and member is an editor, exactly as in 0.3. Only the owner may assign or remove owner and full-admin, so a full-admin runs the site without being able to mint a peer and lock the owner out.

Requirements

• A @we8/cms worker on Cloudflare Workers, with nodejs_compat enabled.
• The same D1 database the CMS uses, bound as DB.
• The secret BETTER_AUTH_SECRET. Sign-in is refused without it, rather than validating a session the worker could not have signed. AUTH_URL is optional and defaults to SITE_URL.
• Its migrations applied: we8-cloudflare migrate applies the CMS sequence and then this package's, or point wrangler at node_modules/@we8/auth/migrations yourself. 0.4 adds 0002_auth_roles.sql, an index and nothing else.
• Runtime dependencies, bundled at deploy: better-auth and drizzle-orm, with @we8/cms, hono, and zod as peers. Node 20 or newer for the tooling around it.

Use it

import cms, { registerAdminAuth } from '@we8/cms';
import { embeddedAdminAuth } from '@we8/auth';

registerAdminAuth(embeddedAdminAuth);

export default cms;

That is the whole integration. npm create we8 writes it for you.

openssl rand -hex 32                          # the value
npx wrangler secret put BETTER_AUTH_SECRET    # for the deployment
npm run db:migrate                            # the tables

Then create the owner, once:

curl -X POST https://your-site.example/api/auth/sign-up/email \
  -H 'Content-Type: application/json' \
  -d '{"email":"[email protected]","password":"a-long-enough-password","name":"You"}'

With the admin portal bundled, opening / offers the same thing as a form. GET /api/v1/auth/mode reports whether that first account can still be created.

What it adds to the API

• POST /api/auth/*: sign-up, sign-in, sign-out, session, and password reset, Better Auth's own routes at its own prefix.
• /api/v1/admin/users: the site's users, behind the users capability. List, create (optionally in a named role), change a role, delete. A site always keeps at least one account that can manage users, nobody changes or deletes their own account here, and only the owner assigns or removes owner and full-admin.

Both are gated by the CMS's own admin rules, so a role without the capability is refused by exactly the rule that refuses it everywhere else, and no API key ever reaches either.

Leaving it out

Nothing forces this package on a site. @we8/cms without any registered provider serves its whole public API and refuses every /api/v1/admin/* request with a message naming what to do about it, so an unconfigured deploy is locked rather than open. If your admin sits behind an identity provider you already run, register a provider of your own instead: resolve(request, env) returning { userId, role } is the required half of the interface.

Upgrading a site that had auth inside the CMS

The tables are the same ones, and this package's migration is written to find them already there: it creates nothing, drops nothing, and fails at nothing. Install this package, add the registration line to your worker, run npm run db:migrate, and everyone signs in exactly as before.

More

• @we8/cms: the CMS this signs into.
• create-we8: scaffolds a project with all of it composed.
• GET /api/v1/openapi.json on any install: the public contract, live and keyless.