@12-apps/auth

Authentication as a plug-in: Auth.js wiring, the e-mail + password flow, the screens and whole pages that flow needs, a mountable backend surface, and the three tables it all runs on — with no host's vocabulary anywhere in it.

Same shape as @12-apps/report-builder, deliberately. If you have adopted that one, you already know this one's layout.

An entry point marks a distinct peer, never merely a module. Every peer is optional, so a backend that never renders a page installs no react.

. is the light half, and that is enforced. It value-imports nothing — no @auth/core, no react, no hono — so a background job that expires stale tokens can import { hashToken } from '@12-apps/auth' and load only that. The Auth.js runtime lives in ./server for the same reason report-builder keeps createReportBuilder there. src/__tests__/light-root.test.ts walks the root's import graph and fails if that ever stops being true.

The tables are the package's

prisma/auth.prisma owns auth_credentials, auth_tokens and auth_platform_settings, with migrations beside them.

pnpm --filter @12-apps/auth prisma:sync        # copy the partial into your schema
pnpm --filter @12-apps/auth prisma:sync:check  # CI: fail if the copy drifted

The partial is copied, never symlinked: npm pack drops symlinked entries, turbo prune dangles a link whose owner is not a declared dependency, and Prisma lstats a migration directory — so a symlinked one is silently skipped, which is a green deploy that applied no schema.

Every user reference is an opaque user_id with no foreign key into any host table. These migrations therefore apply in a repo whose users live under another name, in another database, or do not exist yet.

What stays yours

One thing, because it is the one thing a package cannot know: who your users are. EmailIdentityDelegate is three methods — findByEmail, findById, upsert — over your own user table. Everything else is here.

Alongside that, the choices that are genuinely a product's:

• the words — every copy pack is required, never defaulted (PT_BR_* ships as one for each surface);
• the branding — a slot on the pages, completely opaque to this package;
• the providers — a node you render, because an OAuth button carries a callback URL, a consent gate and a redirect this package cannot own;
• the mail vendor — you name the environment VARIABLES; which service, which key and which from-address are yours. The resolution between them is not: createEnvAuthMailer owns the sink / vendor / refuse tree, because every branch of it is a correctness property rather than a preference.

Config, and only config. The origin host's whole wiring is now:

export const authMailer = createEnvAuthMailer({
  env: { provider: "NOTIFICATIONS_EMAIL_PROVIDER", apiKey: "RESEND_API_KEY",
         from: "NOTIFICATIONS_EMAIL_FROM", sinkFile: "AUTH_EMAIL_LOG_FILE",
         origin: ["APP_PUBLIC_URL", "AUTH_URL"] },
  drivers: EMAIL_DRIVERS,
  log: createFeatureLogger("auth-email"),
});

export const { GET, POST, PUT } = mountEmailAuth({
  path: "/api/auth/email",
  credentials, messages: PT_BR_MESSAGES, resolveUserId, onSignedUp,
});

Security model

• consumeToken must be a conditional write (UPDATE … WHERE consumed_at IS NULL) reporting whether it affected a row. That return value is the single-use guarantee.
• Sign-up and password-reset answers are identical whether or not the address exists, and whether or not the mail left. That is why the mailer resolves rather than throws.
• A deployment with no mail provider refuses loudly instead of falling back to logging: a reset link in a log aggregator is a credential in a log aggregator.
• requireEmailVerification changes the sign-up contract, not just its security — see ADOPTING.md.
• createInProcessRateLimiter() returns an InProcessRateLimiter: the AuthRateLimiter port (check(key)) plus retryAfterMs(key), the milliseconds until a key at its limit gets a fresh window (0 when it is not limited, its window expired, or it was never seen). Read-only, on the injected now. A host answering 429 turns it into Retry-After with Math.ceil(ms / 1000). The port itself is unchanged, so a shared-store limiter owes nothing new.

Conventions

• Every surface is a create* factory taking one config object.
• Nothing here reads an environment variable.
• The database client is duck-typed (AuthDb, AuthSettingsDb); this package never resolves a generated Prisma client.
• Developer-facing text is English; the shipped copy packs are pt-BR.

Full wiring, endpoint list and the decisions that are not obvious: ADOPTING.md. Journeys and harness notes: E2E.md.

Stable login-session binding

A verified session exposes optional loginSessionId, a random per-login nonce. It is minted on genuine sign-in (and encodeSessionToken), retained through ordinary Auth.js JWT renewal, and replaced on the next login. It is useful for binding an OAuth consent request to one cookie-authenticated login: account ids are too broad, while encrypted cookie bytes and Auth.js iat/jti change during normal refresh. Always read it from the verified server session, never from a client request field. Legacy cookies without the claim remain authenticated but have no binding until a fresh sign-in; session reads never invent one.