@everystack/auth 0.2.5 → 0.3.0

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

@@ -32,6 +32,7 @@ CREATE OR REPLACE FUNCTION auth.hash_password(p_password TEXT)
 RETURNS TEXT
 LANGUAGE plpgsql
 SECURITY DEFINER
+SET search_path = auth, public, pg_temp
 AS $$
 BEGIN
   RETURN crypt(p_password, gen_salt('bf', 10));
@@ -43,6 +44,7 @@ CREATE OR REPLACE FUNCTION auth.verify_password(p_password TEXT, p_hash TEXT)
 RETURNS BOOLEAN
 LANGUAGE plpgsql
 SECURITY DEFINER
+SET search_path = auth, public, pg_temp
 AS $$
 DECLARE
   v_normalized TEXT;
@@ -59,6 +61,7 @@ CREATE OR REPLACE FUNCTION auth.sign_jwt(p_payload JSONB)
 RETURNS TEXT
 LANGUAGE plpgsql
 SECURITY DEFINER
+SET search_path = auth, public, pg_temp
 AS $$
 DECLARE
   v_header TEXT;
@@ -102,6 +105,7 @@ CREATE OR REPLACE FUNCTION auth.verify_jwt(p_token TEXT)
 RETURNS JSONB
 LANGUAGE plpgsql
 SECURITY DEFINER
+SET search_path = auth, public, pg_temp
 AS $$
 DECLARE
   v_parts TEXT[];
@@ -499,6 +503,118 @@ $$;
 
 REVOKE EXECUTE ON FUNCTION auth.verify_one_time_token FROM PUBLIC;`;
 
+// =============================================================================
+// TOKEN-GATED ACTION WRAPPERS
+//
+// These are the anon-safe entry points for the password-reset and email-confirm
+// flows. They are SECURITY DEFINER (they update auth.users — a locked table), but the
+// CALLER must already hold a valid one-time token, so they are credential-gated the
+// same way auth.sign_in is password-gated: there is nothing to abuse without the token.
+// The token-MINTING function (auth.create_one_time_token) is never granted to anon and
+// runs only on the privileged worker path. These wrappers touch ONLY auth.users — auth
+// columns. Public profile data lives in its own table and is never mixed in here.
+// =============================================================================
+
+const CONFIRM_EMAIL = `\
+CREATE OR REPLACE FUNCTION auth.confirm_email(p_token TEXT)
+RETURNS JSONB
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = auth, public, pg_temp
+AS $$
+DECLARE
+  v_result JSONB;
+  v_user_id UUID;
+BEGIN
+  -- Raises on an invalid/expired/consumed token (fails closed). One-time use.
+  v_result := auth.verify_one_time_token(p_token, 'confirmation');
+  v_user_id := (v_result->>'userId')::uuid;
+
+  UPDATE auth.users
+  SET email_confirmed_at = now(), updated_at = now()
+  WHERE id = v_user_id;
+
+  RETURN jsonb_build_object('confirmed', true, 'userId', v_user_id);
+END;
+$$;
+
+REVOKE EXECUTE ON FUNCTION auth.confirm_email FROM PUBLIC;`;
+
+const RESET_PASSWORD = `\
+CREATE OR REPLACE FUNCTION auth.reset_password(p_token TEXT, p_new_password TEXT)
+RETURNS JSONB
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = auth, public, pg_temp
+AS $$
+DECLARE
+  v_result JSONB;
+  v_user_id UUID;
+BEGIN
+  -- Raises on an invalid/expired/consumed token (fails closed). One-time use.
+  v_result := auth.verify_one_time_token(p_token, 'recovery');
+  v_user_id := (v_result->>'userId')::uuid;
+
+  UPDATE auth.users
+  SET encrypted_password = auth.hash_password(p_new_password), updated_at = now()
+  WHERE id = v_user_id;
+
+  -- A password reset invalidates every existing session — force re-login everywhere.
+  PERFORM auth.revoke_refresh_tokens(v_user_id);
+
+  RETURN jsonb_build_object('reset', true, 'userId', v_user_id);
+END;
+$$;
+
+REVOKE EXECUTE ON FUNCTION auth.reset_password FROM PUBLIC;`;
+
+// auth.change_password — the authenticated self-service password change. Not token-gated
+// but credential-gated: the caller must be authenticated (auth.uid() from the verified
+// JWT) AND prove the current password before the new one is set. SECURITY DEFINER because
+// verifying the current password requires reading encrypted_password, which authenticated
+// must never be granted. Granted to authenticated (not anon); called via withRole.
+const CHANGE_PASSWORD = `\
+CREATE OR REPLACE FUNCTION auth.change_password(p_current_password TEXT, p_new_password TEXT)
+RETURNS JSONB
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = auth, public, pg_temp
+AS $$
+DECLARE
+  v_user_id UUID;
+  v_hash TEXT;
+BEGIN
+  -- The caller is authenticated; their verified subject claim identifies them.
+  -- Read the claim inline so this wrapper has no dependency on the accessor functions.
+  v_user_id := (nullif(current_setting('request.jwt.claims', true), '')::jsonb->>'sub')::uuid;
+  IF v_user_id IS NULL THEN
+    RAISE EXCEPTION 'not_authenticated' USING ERRCODE = 'P0001';
+  END IF;
+
+  SELECT encrypted_password INTO v_hash FROM auth.users
+  WHERE id = v_user_id AND deleted_at IS NULL;
+  IF NOT FOUND OR v_hash IS NULL THEN
+    RAISE EXCEPTION 'invalid_credentials' USING ERRCODE = 'P0001';
+  END IF;
+
+  -- Verify the current password before changing it (the gate).
+  IF NOT auth.verify_password(p_current_password, v_hash) THEN
+    RAISE EXCEPTION 'invalid_credentials' USING ERRCODE = 'P0001';
+  END IF;
+
+  UPDATE auth.users
+  SET encrypted_password = auth.hash_password(p_new_password), updated_at = now()
+  WHERE id = v_user_id;
+
+  -- A password change invalidates every existing session — force re-login everywhere.
+  PERFORM auth.revoke_refresh_tokens(v_user_id);
+
+  RETURN jsonb_build_object('changed', true, 'userId', v_user_id);
+END;
+$$;
+
+REVOKE EXECUTE ON FUNCTION auth.change_password FROM PUBLIC;`;
+
 // =============================================================================
 // DEFAULT AUTH FUNCTIONS (work against default auth.users schema)
 // =============================================================================
@@ -811,6 +927,76 @@ $$;
 
 REVOKE EXECUTE ON FUNCTION auth.oauth_sign_in_jwt FROM PUBLIC;`;
 
+// =============================================================================
+// SESSION WRAPPERS — the anon-safe login/signup entry points for a least-priv API
+//
+// Each is credential-gated (sign_in raises on a bad password; sign_up raises on a dup
+// email), so the caller proves the credential before anything is minted. They verify or
+// create the user AND issue the refresh token internally (as the definer/owner), so the
+// raw minters — issue_refresh_token, sign_jwt — never need a grant to anon and stay
+// REVOKE'd. They return only the caller's OWN identity plus the refresh token; the ACCESS
+// JWT is minted by the handler in JS (so app-level enrichClaims, e.g. the `aud` claim,
+// is preserved). They touch only auth.users; the public profile is created by a trigger.
+// =============================================================================
+
+const SIGN_IN_SESSION = `\
+CREATE OR REPLACE FUNCTION auth.sign_in_session(
+  p_email TEXT,
+  p_password TEXT,
+  p_ip_address TEXT DEFAULT NULL,
+  p_user_agent TEXT DEFAULT NULL,
+  p_device_id UUID DEFAULT NULL
+)
+RETURNS JSONB
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = auth, public, pg_temp
+AS $$
+DECLARE
+  v_user JSONB;
+  v_refresh JSONB;
+BEGIN
+  -- Raises invalid_credentials (timing-safe) on a bad email/password — fails closed.
+  v_user := auth.sign_in(p_email, p_password);
+  v_refresh := auth.issue_refresh_token(
+    (v_user->>'sub')::uuid, NULL, p_ip_address, p_user_agent, p_device_id
+  );
+  RETURN v_user || jsonb_build_object('refresh_token', v_refresh->>'token');
+END;
+$$;
+
+REVOKE EXECUTE ON FUNCTION auth.sign_in_session FROM PUBLIC;`;
+
+const SIGN_UP_SESSION = `\
+CREATE OR REPLACE FUNCTION auth.sign_up_session(
+  p_email TEXT,
+  p_password TEXT,
+  p_user_meta_data JSONB DEFAULT '{}',
+  p_ip_address TEXT DEFAULT NULL,
+  p_user_agent TEXT DEFAULT NULL,
+  p_device_id UUID DEFAULT NULL
+)
+RETURNS JSONB
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = auth, public, pg_temp
+AS $$
+DECLARE
+  v_user JSONB;
+  v_refresh JSONB;
+BEGIN
+  -- Raises email_exists on a duplicate. Creates auth.users only; the caller creates
+  -- the public profile as the authenticated user (invoker INSERT under RLS).
+  v_user := auth.sign_up(p_email, p_password, p_user_meta_data);
+  v_refresh := auth.issue_refresh_token(
+    (v_user->>'sub')::uuid, NULL, p_ip_address, p_user_agent, p_device_id
+  );
+  RETURN v_user || jsonb_build_object('refresh_token', v_refresh->>'token');
+END;
+$$;
+
+REVOKE EXECUTE ON FUNCTION auth.sign_up_session FROM PUBLIC;`;
+
 // =============================================================================
 // COMPOSABLE GENERATORS
 // =============================================================================
@@ -843,6 +1029,17 @@ export function generateOneTimeTokenSQL(): string {
     .trimEnd() + '\n';
 }
 
+/**
+ * auth.confirm_email, auth.reset_password — token-gated action wrappers. The anon-safe
+ * entry points for the email-confirm and password-reset flows (the caller holds a valid
+ * one-time token; the token-minting function stays owner-only on the worker path).
+ */
+export function generateTokenActionsSQL(): string {
+  return [CONFIRM_EMAIL, '', RESET_PASSWORD, '', CHANGE_PASSWORD]
+    .join('\n')
+    .trimEnd() + '\n';
+}
+
 /** auth.sign_in, auth.sign_up, auth.oauth_sign_in (work against default schema) */
 export function generateDefaultAuthSQL(): string {
   return [SIGN_UP, '', SIGN_IN, '', OAUTH_SIGN_IN]
@@ -857,6 +1054,45 @@ export function generateJwtWrappersSQL(): string {
     .trimEnd() + '\n';
 }
 
+/**
+ * auth.sign_in_session, auth.sign_up_session — the anon-safe, credential-gated login/signup
+ * entry points for a least-privilege API. They verify/create the user and issue the refresh
+ * token internally (the raw minters stay owner-only); the handler mints the access JWT in JS
+ * so enrichClaims is preserved.
+ */
+export function generateSessionWrappersSQL(): string {
+  return [SIGN_IN_SESSION, '', SIGN_UP_SESSION]
+    .join('\n')
+    .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
 // =============================================================================
@@ -866,6 +1102,10 @@ export interface AuthSQLOptions {
   accessors?: boolean;
   /** Include one-time token functions (default: true) */
   oneTimeTokens?: boolean;
+  /** Include the token-gated action wrappers confirm_email/reset_password (default: true) */
+  tokenActions?: boolean;
+  /** Include the anon-safe session wrappers sign_in_session/sign_up_session (default: true) */
+  sessionWrappers?: boolean;
   /** Include default sign_in/sign_up/oauth_sign_in functions (default: true) */
   defaultAuthFunctions?: boolean;
   /** Include JWT convenience wrappers (default: false) */
@@ -892,6 +1132,12 @@ export function generateAuthSQL(options?: AuthSQLOptions): string {
   if (options?.oneTimeTokens !== false) {
     parts.push('', generateOneTimeTokenSQL());
   }
+  if (options?.tokenActions !== false) {
+    parts.push('', generateTokenActionsSQL());
+  }
+  if (options?.sessionWrappers !== false) {
+    parts.push('', generateSessionWrappersSQL());
+  }
   if (options?.defaultAuthFunctions !== false) {
     parts.push('', generateDefaultAuthSQL());
   }
@@ -899,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';
 }