@everystack/auth 0.2.6 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/auth",
-  "version": "0.2.6",
+  "version": "0.3.0",
   "description": "JWT authentication handlers, password hashing, and React auth context",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",
@@ -37,6 +37,10 @@
       "types": "./src/schema.ts",
       "default": "./src/schema.ts"
     },
+    "./models": {
+      "types": "./src/models/index.ts",
+      "default": "./src/models/index.ts"
+    },
     "./sql": {
       "types": "./src/sql.ts",
       "default": "./src/sql.ts"
@@ -86,7 +90,8 @@
     }
   },
   "dependencies": {
-    "bcryptjs": "3.0.3"
+    "bcryptjs": "3.0.3",
+    "@everystack/model": "0.3.3"
   },
   "peerDependencies": {
     "@everystack/api": ">=0.1.0",

package/src/models/device.ts

@@ -0,0 +1,51 @@
+/**
+ * auth.devices — unified device registry + attestation. Auth owns the registry fields
+ * (persistent deviceId, push token, platform/metadata); @everystack/security consumes
+ * the attestation fields (keyId, publicKey, trustScore …). Written on the privileged
+ * device/attestation paths, so `writtenBy: 'functions'` (ENABLE-not-FORCE); admin
+ * manages; private.
+ */
+
+import { defineModel, field, can, index } from '@everystack/model';
+import { User } from './user';
+
+export const Device = defineModel('devices', {
+  schema: 'auth',
+  writtenBy: 'functions',
+  private: true,
+  fields: {
+    id: field.uuid().primaryKey().defaultRandom(),
+    repositoryId: field.uuid().nullable(),
+    userId: field.uuid().references(() => User, { onDelete: 'set null' }),
+    deviceId: field.text().notNull().unique(),
+    platform: field.text().notNull(), // 'ios' | 'android' | 'web'
+    pushToken: field.text().nullable(),
+    name: field.text().nullable(),
+    model: field.text().nullable(),
+    osVersion: field.text().nullable(),
+    appVersion: field.text().nullable(),
+    userAgent: field.text().nullable(),
+
+    // Attestation (consumed by @everystack/security)
+    attestationType: field.text().nullable(),
+    keyId: field.text().nullable(),
+    publicKey: field.text().nullable(),
+    attestationData: field.jsonb().nullable(),
+    trustScore: field.integer().notNull().default(100),
+    attestationCount: field.integer().notNull().default(0),
+    lastAttestation: field.timestamptz().nullable(),
+
+    // Lifecycle
+    registeredAt: field.timestamptz().defaultNow().notNull(),
+    lastSeenAt: field.timestamptz().defaultNow().notNull(),
+    revokedAt: field.timestamptz().nullable(),
+    revokedReason: field.text().nullable(),
+  },
+  constraints: [
+    index('repositoryId'),
+    index('userId'),
+    index('repositoryId', 'userId'),
+    index('platform'),
+  ],
+  abilities: [can('manage', { role: 'admin' })],
+});

package/src/models/identity.ts

@@ -0,0 +1,32 @@
+/**
+ * auth.identities — OAuth provider links (Supabase-compatible). One row per
+ * (provider, provider_id). Written only by the SECDEF auth functions (oauth_sign_in,
+ * sign_up), so `writtenBy: 'functions'` (ENABLE-not-FORCE); admin manages; private.
+ *
+ * Schema + authz derive from this Model; `../schema` materializes the runtime table.
+ */
+
+import { defineModel, field, can, index } from '@everystack/model';
+import { User } from './user';
+
+export const Identity = defineModel('identities', {
+  schema: 'auth',
+  writtenBy: 'functions',
+  private: true,
+  fields: {
+    id: field.uuid().primaryKey().defaultRandom(),
+    userId: field.uuid().notNull().references(() => User, { onDelete: 'cascade' }),
+    provider: field.text().notNull(),
+    providerId: field.text().notNull(),
+    identityData: field.jsonb().nullable(),
+    email: field.text().nullable(),
+    lastSignInAt: field.timestamptz().nullable(),
+    createdAt: field.timestamptz().defaultNow().notNull(),
+    updatedAt: field.timestamptz().defaultNow().notNull(),
+  },
+  constraints: [
+    index('providerId', 'provider').unique(),
+    index('userId'),
+  ],
+  abilities: [can('manage', { role: 'admin' })],
+});

package/src/models/index.ts

@@ -0,0 +1,43 @@
+/**
+ * Auth's package-owned models. A consuming app composes these into its own model list
+ * so `db:generate` emits the auth schema + authz alongside the app's tables:
+ * `models = [...appModels, ...authModels]`.
+ *
+ * All seven are `schema: 'auth'`, `writtenBy: 'functions'` (SECDEF-managed →
+ * ENABLE-not-FORCE), and `private` (reached through the auth handlers, never the generic
+ * API). The SECURITY DEFINER functions that write them stay package-owned SQL (sql.ts) —
+ * not Model-expressible; the Model declares the table authz, the package ships the functions.
+ */
+
+export { User } from './user';
+export { Identity } from './identity';
+export { RefreshToken } from './refresh-token';
+export { Device } from './device';
+export { MfaFactor } from './mfa-factor';
+export { MfaChallenge } from './mfa-challenge';
+export { OneTimeToken } from './one-time-token';
+
+import { defineModule } from '@everystack/model';
+import { User } from './user';
+import { Identity } from './identity';
+import { RefreshToken } from './refresh-token';
+import { Device } from './device';
+import { MfaFactor } from './mfa-factor';
+import { MfaChallenge } from './mfa-challenge';
+import { OneTimeToken } from './one-time-token';
+import { generateAuthSQL } from '../sql';
+
+/** All auth-owned models, for the app to spread into its db:generate model list. */
+export const authModels = [User, Identity, RefreshToken, Device, MfaFactor, MfaChallenge, OneTimeToken];
+
+/**
+ * The auth Module — the package's complete DB slice: the seven tables (schema + authz), the
+ * `pgcrypto` extension its functions need, and the SECURITY DEFINER functions themselves
+ * (`generateAuthSQL` — hashing, JWT, refresh tokens, one-time tokens, session/token wrappers,
+ * the default sign_in/sign_up). The app composes this so `db:generate` emits auth end to end.
+ */
+export const authModule = defineModule({
+  models: authModels,
+  extensions: ['pgcrypto'],
+  functions: generateAuthSQL,
+});

package/src/models/mfa-challenge.ts

@@ -0,0 +1,25 @@
+/**
+ * auth.mfa_challenges — ephemeral MFA challenge state, verified within a timeout window.
+ * Written on the privileged MFA path (SECDEF), so `writtenBy: 'functions'`
+ * (ENABLE-not-FORCE); admin manages; private.
+ */
+
+import { defineModel, field, can, index } from '@everystack/model';
+import { MfaFactor } from './mfa-factor';
+
+export const MfaChallenge = defineModel('mfa_challenges', {
+  schema: 'auth',
+  writtenBy: 'functions',
+  private: true,
+  fields: {
+    id: field.uuid().primaryKey().defaultRandom(),
+    factorId: field.uuid().notNull().references(() => MfaFactor, { onDelete: 'cascade' }),
+    ipAddress: field.text().nullable(),
+    otpCode: field.text().nullable(),
+    webAuthnSessionData: field.jsonb().nullable(),
+    verifiedAt: field.timestamptz().nullable(),
+    createdAt: field.timestamptz().defaultNow().notNull(),
+  },
+  constraints: [index('factorId')],
+  abilities: [can('manage', { role: 'admin' })],
+});

package/src/models/mfa-factor.ts

@@ -0,0 +1,33 @@
+/**
+ * auth.mfa_factors — TOTP + WebAuthn factors. Enrolled 'unverified', become 'verified'
+ * after a challenge. Written on the privileged MFA path (SECDEF), so
+ * `writtenBy: 'functions'` (ENABLE-not-FORCE); admin manages; private.
+ */
+
+import { defineModel, field, can, index, sql } from '@everystack/model';
+import { User } from './user';
+
+export const MfaFactor = defineModel('mfa_factors', {
+  schema: 'auth',
+  writtenBy: 'functions',
+  private: true,
+  fields: {
+    id: field.uuid().primaryKey().defaultRandom(),
+    userId: field.uuid().notNull().references(() => User, { onDelete: 'cascade' }),
+    friendlyName: field.text().nullable(),
+    factorType: field.text().notNull(), // 'totp' | 'webauthn'
+    status: field.text().notNull().default('unverified'), // 'unverified' | 'verified'
+    secret: field.text().nullable(), // encrypted TOTP secret
+    webAuthnCredential: field.jsonb().nullable(),
+    phone: field.text().nullable(),
+    lastChallengedAt: field.timestamptz().nullable(),
+    createdAt: field.timestamptz().defaultNow().notNull(),
+    updatedAt: field.timestamptz().defaultNow().notNull(),
+  },
+  constraints: [
+    index('userId'),
+    // Partial index: a user's verified factors (predicate in deparser normal form).
+    index('userId').where(sql`status = 'verified'::text`),
+  ],
+  abilities: [can('manage', { role: 'admin' })],
+});

package/src/models/one-time-token.ts

@@ -0,0 +1,30 @@
+/**
+ * auth.one_time_tokens — email confirmation, password reset, magic links. One row per
+ * (user_id, token_type) — a new token of the same type replaces the previous. Stored as
+ * SHA-256 hashes. Minted/verified only by SECDEF functions (create/verify_one_time_token),
+ * so `writtenBy: 'functions'` (ENABLE-not-FORCE); admin manages; private.
+ */
+
+import { defineModel, field, can, index } from '@everystack/model';
+import { User } from './user';
+
+export const OneTimeToken = defineModel('one_time_tokens', {
+  schema: 'auth',
+  writtenBy: 'functions',
+  private: true,
+  fields: {
+    id: field.uuid().primaryKey().defaultRandom(),
+    userId: field.uuid().notNull().references(() => User, { onDelete: 'cascade' }),
+    tokenType: field.text().notNull(),
+    tokenHash: field.text().notNull(),
+    relatesTo: field.text().notNull(), // email or phone
+    createdAt: field.timestamptz().defaultNow().notNull(),
+    updatedAt: field.timestamptz().defaultNow().notNull(),
+  },
+  constraints: [
+    index('userId', 'tokenType').unique(),
+    index('tokenHash'),
+    index('relatesTo'),
+  ],
+  abilities: [can('manage', { role: 'admin' })],
+});

package/src/models/refresh-token.ts

@@ -0,0 +1,39 @@
+/**
+ * auth.refresh_tokens — RFC 6819 family-based rotation with reuse detection. Only
+ * SHA-256 hashes are stored. Every operation goes through a SECDEF function
+ * (issue/validate/revoke/cleanup_refresh_tokens) running as owner, so
+ * `writtenBy: 'functions'` (ENABLE-not-FORCE). 0015 revoked the direct authenticated
+ * grant: admin manages, the functions do the rest.
+ */
+
+import { defineModel, field, can, index, sql } from '@everystack/model';
+import { User } from './user';
+
+export const RefreshToken = defineModel('refresh_tokens', {
+  schema: 'auth',
+  writtenBy: 'functions',
+  private: true,
+  fields: {
+    id: field.uuid().primaryKey().defaultRandom(),
+    repositoryId: field.uuid().nullable(),
+    userId: field.uuid().notNull().references(() => User, { onDelete: 'cascade' }),
+    tokenHash: field.text().notNull().unique(),
+    familyId: field.uuid().notNull().defaultRandom(),
+    status: field.text().notNull().default('active'), // 'active' | 'consumed'
+    ipAddress: field.text().nullable(),
+    userAgent: field.text().nullable(),
+    deviceId: field.uuid().nullable(),
+    expiresAt: field.timestamptz().notNull(),
+    createdAt: field.timestamptz().defaultNow().notNull(),
+  },
+  constraints: [
+    index('userId'),
+    index('repositoryId'),
+    index('repositoryId', 'userId'),
+    index('familyId'),
+    index('expiresAt'),
+    // Partial index: the active token of a family (predicate in deparser normal form).
+    index('familyId').where(sql`status = 'active'::text`),
+  ],
+  abilities: [can('manage', { role: 'admin' })],
+});

package/src/models/user.ts

@@ -0,0 +1,59 @@
+/**
+ * auth.users — the default user table (Supabase-compatible column names for
+ * zero-friction migration).
+ *
+ * The v3 Model that owns this table's schema AND its authorization. The drizzle
+ * runtime table (`../schema`) derives from it via `toDrizzleTable`, and `db:generate`
+ * reads it to emit the DDL + RLS + grants — the package, not the consuming app, owns
+ * auth.users end to end.
+ *
+ * Authz shape (matches the live 0014 migration):
+ *  - `writtenBy: 'functions'` — every write goes through the SECURITY DEFINER auth
+ *    functions (sign_up / sign_in / reset_password …), which run as the table owner.
+ *    The owner must keep its bypass (read encrypted_password, insert users), so RLS is
+ *    ENABLE-not-FORCE. `db:doctor` additionally asserts those functions exist with a
+ *    pinned search_path.
+ *  - `can('manage', { role: 'admin' })` — admin (operator) gets CRUD + the `users_admin`
+ *    policy.
+ *  - `can('read', { owner: 'id', columns: ['id', 'email', 'role'] })` — column-scoped:
+ *    `authenticated` may read only id/email/role of its OWN row (the refresh path mints
+ *    the next access token from them), never the password hash. Compiles to a column
+ *    grant + the `users_select_self` policy, not a table grant.
+ *  - `private: true` — reached through the auth handlers, never the generic data API.
+ *
+ * Apps that need a different user model replace the postgres functions (the stable API);
+ * the schema is the batteries-included default.
+ */
+
+import { defineModel, field, can, index } from '@everystack/model';
+
+export const User = defineModel('users', {
+  schema: 'auth',
+  writtenBy: 'functions',
+  private: true,
+  fields: {
+    id: field.uuid().primaryKey().defaultRandom(),
+    instanceId: field.uuid().nullable(), // Supabase compat
+    aud: field.varchar(255).default('authenticated'),
+    role: field.varchar(255).default('authenticated'),
+    email: field.varchar(255).unique(),
+    encryptedPassword: field.varchar(255).nullable(),
+    emailConfirmedAt: field.timestamptz().nullable(),
+    phone: field.varchar(255).nullable(),
+    phoneConfirmedAt: field.timestamptz().nullable(),
+    rawAppMetaData: field.jsonb().nullable(),
+    rawUserMetaData: field.jsonb().nullable(),
+    lastSignInAt: field.timestamptz().nullable(),
+    bannedUntil: field.timestamptz().nullable(),
+    deletedAt: field.timestamptz().nullable(),
+    isAnonymous: field.boolean().notNull().default(false),
+    createdAt: field.timestamptz().defaultNow().notNull(),
+    updatedAt: field.timestamptz().defaultNow().notNull(),
+  },
+  constraints: [index('instanceId')],
+  abilities: [
+    can('manage', { role: 'admin' }),
+    // Self-read, column-scoped: id/email/role of your own row, never the hash.
+    can('read', { owner: 'id', columns: ['id', 'email', 'role'] }),
+  ],
+});

package/src/schema.ts

@@ -1,5 +1,9 @@
 /**
- * Auth schema — default tables for everystack auth.
+ * Auth schema — the default tables for everystack auth, as drizzle-orm runtime tables.
+ *
+ * DERIVED from the package-owned Models (`./models`) — each Model is the single source
+ * of its table's columns, schema, indexes, and authz; this just materializes the
+ * drizzle-orm runtime objects the auth handlers query. Edit the Models, not this file.
  *
  * Tables:
  *   users           — Supabase-compatible user table (batteries included, replaceable)
@@ -12,305 +16,30 @@
  *
  * The default schema works out of the box. Apps that need a different user model
  * replace the postgres functions (sign_in, sign_up, oauth_sign_in) — the function
- * signatures are the stable API, not the schema.
- *
- * Column names match Supabase for zero-friction migration.
+ * signatures are the stable API, not the schema. Column names match Supabase for
+ * zero-friction migration.
  */
 
+import { pgSchema } from 'drizzle-orm/pg-core';
+import { toDrizzleTable } from '@everystack/model/drizzle';
 import {
-  pgSchema,
-  boolean,
-  text,
-  timestamp,
-  uuid,
-  varchar,
-  integer,
-  index,
-  uniqueIndex,
-  jsonb,
-} from 'drizzle-orm/pg-core';
-import { sql } from 'drizzle-orm';
-
+  User,
+  Identity,
+  RefreshToken,
+  Device,
+  MfaFactor,
+  MfaChallenge,
+  OneTimeToken,
+} from './models/index';
+
+/** The `auth` Postgres schema namespace. Kept for consumers that build against it directly. */
 const authSchema = pgSchema('auth');
 export { authSchema };
 
-// =============================================================================
-// USERS
-// =============================================================================
-
-/**
- * Default user table. Supabase-compatible column names for zero-friction migration.
- *
- * Apps that need a different user model can replace this table entirely —
- * the postgres auth functions (sign_in, sign_up, oauth_sign_in) are the real API.
- * Replace the functions, keep the primitives (hash_password, sign_jwt, etc.).
- */
-export const users = authSchema.table(
-  'users',
-  {
-    id: uuid('id').primaryKey().defaultRandom(),
-    instanceId: uuid('instance_id'), // Supabase compat
-    aud: varchar('aud', { length: 255 }).default('authenticated'),
-    role: varchar('role', { length: 255 }).default('authenticated'),
-    email: varchar('email', { length: 255 }).unique(),
-    encryptedPassword: varchar('encrypted_password', { length: 255 }),
-    emailConfirmedAt: timestamp('email_confirmed_at', { withTimezone: true }),
-    phone: varchar('phone', { length: 255 }),
-    phoneConfirmedAt: timestamp('phone_confirmed_at', { withTimezone: true }),
-    rawAppMetaData: jsonb('raw_app_meta_data'),
-    rawUserMetaData: jsonb('raw_user_meta_data'),
-    lastSignInAt: timestamp('last_sign_in_at', { withTimezone: true }),
-    bannedUntil: timestamp('banned_until', { withTimezone: true }),
-    deletedAt: timestamp('deleted_at', { withTimezone: true }),
-    isAnonymous: boolean('is_anonymous').notNull().default(false),
-    createdAt: timestamp('created_at', { withTimezone: true }).defaultNow().notNull(),
-    updatedAt: timestamp('updated_at', { withTimezone: true }).defaultNow().notNull(),
-  },
-  (table) => ({
-    emailIdx: uniqueIndex('users_email_idx').on(table.email),
-    instanceIdx: index('users_instance_id_idx').on(table.instanceId),
-  })
-);
-
-// =============================================================================
-// IDENTITIES
-// =============================================================================
-
-/**
- * OAuth provider links. Supabase-compatible.
- *
- * One row per (provider, provider_id) pair. A user can have multiple identities
- * (email + google + apple). The identity_data jsonb stores provider-specific claims.
- */
-export const identities = authSchema.table(
-  'identities',
-  {
-    id: uuid('id').primaryKey().defaultRandom(),
-    userId: uuid('user_id')
-      .notNull()
-      .references(() => users.id, { onDelete: 'cascade' }),
-    provider: text('provider').notNull(),
-    providerId: text('provider_id').notNull(),
-    identityData: jsonb('identity_data'),
-    email: text('email'),
-    lastSignInAt: timestamp('last_sign_in_at', { withTimezone: true }),
-    createdAt: timestamp('created_at', { withTimezone: true }).defaultNow().notNull(),
-    updatedAt: timestamp('updated_at', { withTimezone: true }).defaultNow().notNull(),
-  },
-  (table) => ({
-    providerUniqueIdx: uniqueIndex('identities_provider_id_provider_idx').on(
-      table.providerId,
-      table.provider
-    ),
-    userIdx: index('identities_user_idx').on(table.userId),
-  })
-);
-
-// =============================================================================
-// REFRESH TOKENS
-// =============================================================================
-
-/**
- * Dedicated refresh token table.
- *
- * Security properties:
- * - Only SHA-256 hashes stored (never plaintext)
- * - familyId groups a rotation chain for theft detection
- * - status='consumed' tokens are kept; replay triggers family revocation (RFC 6819)
- * - ip_address/user_agent enable "active sessions" display
- * - device_id enables token-to-device binding
- *
- * PostgreSQL path uses SECURITY DEFINER functions with SELECT FOR UPDATE
- * for full atomicity. JS path uses consumed-token reuse detection as mitigation.
- */
-export const refreshTokens = authSchema.table(
-  'refresh_tokens',
-  {
-    id: uuid('id').primaryKey().defaultRandom(),
-    repositoryId: uuid('repository_id'),
-    userId: uuid('user_id')
-      .notNull()
-      .references(() => users.id, { onDelete: 'cascade' }),
-    tokenHash: text('token_hash').notNull().unique(),
-    familyId: uuid('family_id').notNull().defaultRandom(),
-    status: text('status').notNull().default('active'), // 'active' | 'consumed'
-    ipAddress: text('ip_address'),
-    userAgent: text('user_agent'),
-    deviceId: uuid('device_id'),
-    expiresAt: timestamp('expires_at', { withTimezone: true }).notNull(),
-    createdAt: timestamp('created_at', { withTimezone: true }).defaultNow().notNull(),
-  },
-  (table) => ({
-    tokenIdx: uniqueIndex('refresh_tokens_token_idx').on(table.tokenHash),
-    userIdx: index('refresh_tokens_user_idx').on(table.userId),
-    repoIdx: index('refresh_tokens_repo_idx').on(table.repositoryId),
-    repoUserIdx: index('refresh_tokens_repo_user_idx').on(table.repositoryId, table.userId),
-    familyIdx: index('refresh_tokens_family_idx').on(table.familyId),
-    expiresIdx: index('refresh_tokens_expires_idx').on(table.expiresAt),
-    activeFamilyIdx: index('refresh_tokens_active_family_idx')
-      .on(table.familyId)
-      .where(sql`${table.status} = 'active'`),
-  })
-);
-
-// =============================================================================
-// DEVICES
-// =============================================================================
-
-/**
- * Unified device registry + attestation.
- *
- * Auth-owned fields (device registry):
- *   deviceId    — persistent UUID from SecureStorage, survives reinstalls
- *   userId      — nullable, set when user signs in (anonymous on first launch)
- *   pushToken   — nullable, set when app enables push notifications
- *   platform    — 'ios' | 'android' | 'web'
- *   name, model, osVersion, appVersion, userAgent — device metadata
- *
- * Security-consumed fields (attestation):
- *   attestationType — 'apple_app_attest' | 'play_integrity' | null
- *   keyId, publicKey, attestationData — hardware-backed keys
- *   trustScore, attestationCount, lastAttestation — attestation state
- *   revokedAt, revokedReason — device revocation
- */
-export const devices = authSchema.table(
-  'devices',
-  {
-    id: uuid('id').primaryKey().defaultRandom(),
-    repositoryId: uuid('repository_id'),
-    userId: uuid('user_id').references(() => users.id, { onDelete: 'set null' }),
-    deviceId: text('device_id').notNull().unique(),
-    platform: text('platform').notNull(), // 'ios' | 'android' | 'web'
-    pushToken: text('push_token'),
-    name: text('name'),
-    model: text('model'),
-    osVersion: text('os_version'),
-    appVersion: text('app_version'),
-    userAgent: text('user_agent'),
-
-    // Attestation (consumed by @everystack/security)
-    attestationType: text('attestation_type'),
-    keyId: text('key_id'),
-    publicKey: text('public_key'),
-    attestationData: jsonb('attestation_data'),
-    trustScore: integer('trust_score').notNull().default(100),
-    attestationCount: integer('attestation_count').notNull().default(0),
-    lastAttestation: timestamp('last_attestation', { withTimezone: true }),
-
-    // Lifecycle
-    registeredAt: timestamp('registered_at', { withTimezone: true }).defaultNow().notNull(),
-    lastSeenAt: timestamp('last_seen_at', { withTimezone: true }).defaultNow().notNull(),
-    revokedAt: timestamp('revoked_at', { withTimezone: true }),
-    revokedReason: text('revoked_reason'),
-  },
-  (table) => ({
-    repoIdx: index('devices_repo_idx').on(table.repositoryId),
-    userIdx: index('devices_user_idx').on(table.userId),
-    repoUserIdx: index('devices_repo_user_idx').on(table.repositoryId, table.userId),
-    deviceIdIdx: uniqueIndex('devices_device_id_idx').on(table.deviceId),
-    platformIdx: index('devices_platform_idx').on(table.platform),
-  })
-);
-
-// =============================================================================
-// MFA FACTORS
-// =============================================================================
-
-/**
- * Multi-factor authentication factors. TOTP + WebAuthn.
- *
- * Users enroll factors (e.g. Google Authenticator) which start as 'unverified'.
- * After confirming a challenge, the factor becomes 'verified' and is required
- * for subsequent sign-ins.
- *
- * MFA handlers are a follow-up — this schema establishes the tables so apps
- * can implement their own MFA flows via postgres functions.
- */
-export const mfaFactors = authSchema.table(
-  'mfa_factors',
-  {
-    id: uuid('id').primaryKey().defaultRandom(),
-    userId: uuid('user_id')
-      .notNull()
-      .references(() => users.id, { onDelete: 'cascade' }),
-    friendlyName: text('friendly_name'),
-    factorType: text('factor_type').notNull(), // 'totp' | 'webauthn'
-    status: text('status').notNull().default('unverified'), // 'unverified' | 'verified'
-    secret: text('secret'), // encrypted TOTP secret
-    webAuthnCredential: jsonb('web_authn_credential'),
-    phone: text('phone'), // future: phone MFA
-    lastChallengedAt: timestamp('last_challenged_at', { withTimezone: true }),
-    createdAt: timestamp('created_at', { withTimezone: true }).defaultNow().notNull(),
-    updatedAt: timestamp('updated_at', { withTimezone: true }).defaultNow().notNull(),
-  },
-  (table) => ({
-    userIdx: index('mfa_factors_user_idx').on(table.userId),
-    userVerifiedIdx: index('mfa_factors_user_verified_idx')
-      .on(table.userId)
-      .where(sql`${table.status} = 'verified'`),
-  })
-);
-
-// =============================================================================
-// MFA CHALLENGES
-// =============================================================================
-
-/**
- * Ephemeral MFA challenge state.
- *
- * Created when a user initiates MFA verification. Verified within a timeout
- * window. Can be cleaned up periodically.
- */
-export const mfaChallenges = authSchema.table(
-  'mfa_challenges',
-  {
-    id: uuid('id').primaryKey().defaultRandom(),
-    factorId: uuid('factor_id')
-      .notNull()
-      .references(() => mfaFactors.id, { onDelete: 'cascade' }),
-    ipAddress: text('ip_address'),
-    otpCode: text('otp_code'),
-    webAuthnSessionData: jsonb('web_authn_session_data'),
-    verifiedAt: timestamp('verified_at', { withTimezone: true }),
-    createdAt: timestamp('created_at', { withTimezone: true }).defaultNow().notNull(),
-  },
-  (table) => ({
-    factorIdx: index('mfa_challenges_factor_idx').on(table.factorId),
-  })
-);
-
-// =============================================================================
-// ONE-TIME TOKENS
-// =============================================================================
-
-/**
- * One-time tokens for email confirmation, password reset, magic links.
- *
- * Each (user_id, token_type) pair is unique — creating a new token of the same
- * type replaces the previous one. Tokens are stored as SHA-256 hashes.
- *
- * Token types: confirmation, recovery, reauthentication,
- *              email_change_new, email_change_current, phone_change
- */
-export const oneTimeTokens = authSchema.table(
-  'one_time_tokens',
-  {
-    id: uuid('id').primaryKey().defaultRandom(),
-    userId: uuid('user_id')
-      .notNull()
-      .references(() => users.id, { onDelete: 'cascade' }),
-    tokenType: text('token_type').notNull(),
-    tokenHash: text('token_hash').notNull(),
-    relatesTo: text('relates_to').notNull(), // email or phone
-    createdAt: timestamp('created_at', { withTimezone: true }).defaultNow().notNull(),
-    updatedAt: timestamp('updated_at', { withTimezone: true }).defaultNow().notNull(),
-  },
-  (table) => ({
-    userTypeUniqueIdx: uniqueIndex('one_time_tokens_user_type_idx').on(
-      table.userId,
-      table.tokenType
-    ),
-    tokenHashIdx: index('one_time_tokens_token_hash_idx').on(table.tokenHash),
-    relatesToIdx: index('one_time_tokens_relates_to_idx').on(table.relatesTo),
-  })
-);
+export const users = toDrizzleTable(User);
+export const identities = toDrizzleTable(Identity);
+export const refreshTokens = toDrizzleTable(RefreshToken);
+export const devices = toDrizzleTable(Device);
+export const mfaFactors = toDrizzleTable(MfaFactor);
+export const mfaChallenges = toDrizzleTable(MfaChallenge);
+export const oneTimeTokens = toDrizzleTable(OneTimeToken);

package/src/sql.ts

@@ -1066,6 +1066,33 @@ export function generateSessionWrappersSQL(): string {
     .trimEnd() + '\n';
 }
 
+/**
+ * The role grants the generated functions need to be reachable — schema USAGE plus EXECUTE on
+ * the anon-/authenticated-callable entry points. Kept SEPARATE from the function generators
+ * (which stay role-agnostic and REVOKE EXECUTE FROM PUBLIC) so the package's complete migration
+ * is self-sufficient — `db:generate --init` produces a WORKING auth, not one a consumer must
+ * hand-grant. The raw minters (sign_in, issue_refresh_token, …) are deliberately NOT here: only
+ * the credential-/token-gated wrappers are exposed. Grants the everystack role chain
+ * (anon/authenticated/admin, created by db:provision); emitted after the functions exist.
+ *
+ * `opts` mirrors {@link generateAuthSQL} so only grants for included functions are emitted.
+ */
+export function generateAuthGrantsSQL(opts: AuthSQLOptions = {}): string {
+  const lines = ['GRANT USAGE ON SCHEMA auth TO anon, authenticated, admin;'];
+  // validate_refresh_token is always generated (the refresh path) and anon-callable.
+  lines.push('GRANT EXECUTE ON FUNCTION auth.validate_refresh_token(text, uuid, text, text, interval) TO anon;');
+  if (opts.tokenActions !== false) {
+    lines.push('GRANT EXECUTE ON FUNCTION auth.confirm_email(text) TO anon;');
+    lines.push('GRANT EXECUTE ON FUNCTION auth.reset_password(text, text) TO anon;');
+    lines.push('GRANT EXECUTE ON FUNCTION auth.change_password(text, text) TO authenticated;');
+  }
+  if (opts.sessionWrappers !== false) {
+    lines.push('GRANT EXECUTE ON FUNCTION auth.sign_in_session(text, text, text, text, uuid) TO anon;');
+    lines.push('GRANT EXECUTE ON FUNCTION auth.sign_up_session(text, text, jsonb, text, text, uuid) TO anon;');
+  }
+  return lines.join('\n') + '\n';
+}
+
 // =============================================================================
 // MAIN ENTRY POINT
 // =============================================================================
@@ -1118,5 +1145,10 @@ export function generateAuthSQL(options?: AuthSQLOptions): string {
     parts.push('', generateJwtWrappersSQL());
   }
 
+  // The role grants come LAST — every GRANT EXECUTE target now exists. This is what makes the
+  // generated migration self-sufficient: the functions are reachable by the app role chain
+  // without a hand-written grant migration.
+  parts.push('', generateAuthGrantsSQL(options));
+
   return parts.join('\n').trimEnd() + '\n';
 }