@everystack/auth 0.4.0 → 0.4.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/auth",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "JWT authentication handlers, password hashing, and React auth context",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",
@@ -91,7 +91,7 @@
   },
   "dependencies": {
     "bcryptjs": "3.0.3",
-    "@everystack/model": "0.4.0"
+    "@everystack/model": "0.4.12"
   },
   "peerDependencies": {
     "@everystack/api": ">=0.1.0",
@@ -120,7 +120,7 @@
     "postgres": "3.4.9",
     "ts-jest": "29.4.9",
     "typescript": "5.9.3",
-    "@everystack/api": "0.2.10"
+    "@everystack/api": "0.4.0"
   },
   "scripts": {
     "test": "jest",

package/src/models/functions.ts

@@ -0,0 +1,965 @@
+/**
+ * The auth package's SECURITY DEFINER functions, as DECLARED derived objects.
+ *
+ * WHY THIS FILE EXISTS. These same functions have always shipped, but on `defineModule`'s
+ * deprecated `functions` thunk — and exactly ONE command in the toolchain reads that thunk:
+ * `db:generate --init`, the greenfield generator (cli/migration-compile.ts, step 3). Every other
+ * lane, `db:reconcile` included, reads `module.derived`, which was empty. So an app that adopted
+ * brownfield — pull, sync, plan, apply, reconcile — installed NONE of these, and every gate
+ * reported clean, because a reconciler can only compare what was declared and nothing was.
+ * All seven auth models declare `writtenBy: 'functions'` (ENABLE-not-FORCE RLS on the reasoning
+ * that owner functions mediate their writes), so the declared posture and the live database
+ * disagreed about who mediates auth writes. Reported by a consumer, 2026-08-04.
+ *
+ * WHY defineFunction AND NOT defineSql. The escape hatch would have taken the whole blob in one
+ * descriptor and one content hash — but `defineSql` objects are deliberately SKIPPED by the
+ * search_path gates (model/src/derived.ts:526-534). Routing 24 SECURITY DEFINER functions through
+ * the one hatch that exempts them from the pinned-search_path check is the wrong trade for the
+ * auth package specifically. Declared as functions, each one is hashed, ordered, gate-checked,
+ * and — the part that matters most here — the compiler emits
+ * `REVOKE ALL ON FUNCTION … FROM PUBLIC` for EVERY function unconditionally
+ * (cli/derived-compile.ts:72). The defect that shipped in 0.4.0, seven functions left
+ * PUBLIC-executable because nobody remembered their REVOKE, becomes structurally impossible.
+ *
+ * HOW THESE WERE PRODUCED. Not transcribed by hand. The legacy `generateAuthSQL()` was applied to
+ * a scratch database and each descriptor was DERIVED from what PostgreSQL actually recorded —
+ * `pg_get_function_arguments`, `pg_get_function_result`, `prosrc`, `prosecdef`, `proconfig`,
+ * `provolatile`, and the ACL. Deriving beats transcribing when the cost of a mistyped argument
+ * type is a security bug. The derivation is then PROVEN, not trusted: the equivalence test in
+ * @everystack/cli builds one database from the thunk and one from these descriptors and compares
+ * the resulting catalogs function by function.
+ *
+ * Two derivation traps worth naming, both caught before this file was written:
+ *   - the ACL always contains the function OWNER, so a naive read emits an ability granting
+ *     EXECUTE to whatever role happened to build the scratch database;
+ *   - `array_to_string(proconfig, ',')` is ambiguous with the commas INSIDE
+ *     `search_path=auth, public, pg_temp`, silently truncating the pin to its first schema.
+ *
+ * The bodies are byte-identical to what the thunk produced. Edit `sql.ts` and re-derive; do not
+ * hand-patch a body here.
+ */
+
+import { defineFunction, arg, can, sql } from '@everystack/model';
+
+export const changePasswordFn = defineFunction('auth.change_password', {
+  args: [arg('p_current_password', 'text'), arg('p_new_password', 'text')],
+  returns: 'jsonb',
+  language: 'plpgsql',
+  security: 'definer',
+  searchPath: ['auth', 'public', 'pg_temp'],
+  abilities: [can('execute', { role: 'authenticated' })],
+  body: sql`
+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;
+`,
+});
+
+export const cleanupRefreshTokensFn = defineFunction('auth.cleanup_refresh_tokens', {
+  args: [arg('p_consumed_retention', 'interval', { default: sql`'7 days'::interval` })],
+  returns: 'integer',
+  language: 'plpgsql',
+  security: 'definer',
+  searchPath: ['auth', 'public', 'pg_temp'],
+  body: sql`
+DECLARE
+  v_count INTEGER;
+BEGIN
+  DELETE FROM auth.refresh_tokens
+  WHERE expires_at < now()
+     OR (status = 'consumed' AND created_at < now() - p_consumed_retention);
+
+  GET DIAGNOSTICS v_count = ROW_COUNT;
+  RETURN v_count;
+END;
+`,
+});
+
+export const confirmEmailFn = defineFunction('auth.confirm_email', {
+  args: [arg('p_token', 'text')],
+  returns: 'jsonb',
+  language: 'plpgsql',
+  security: 'definer',
+  searchPath: ['auth', 'public', 'pg_temp'],
+  abilities: [can('execute', { role: 'anon' })],
+  body: sql`
+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;
+`,
+});
+
+export const createOneTimeTokenFn = defineFunction('auth.create_one_time_token', {
+  args: [arg('p_user_id', 'uuid'), arg('p_token_type', 'text'), arg('p_relates_to', 'text')],
+  returns: 'text',
+  language: 'plpgsql',
+  security: 'definer',
+  searchPath: ['auth', 'public', 'pg_temp'],
+  body: sql`
+DECLARE
+  v_raw_token TEXT;
+  v_token_hash TEXT;
+BEGIN
+  -- Delete any existing token of this type for this user
+  DELETE FROM auth.one_time_tokens
+  WHERE user_id = p_user_id AND token_type = p_token_type;
+
+  -- Generate 32 random bytes, base64url encoded
+  v_raw_token := rtrim(translate(
+    encode(gen_random_bytes(32), 'base64'),
+    '+/=', '-_ '
+  ));
+
+  v_token_hash := encode(digest(v_raw_token, 'sha256'), 'hex');
+
+  INSERT INTO auth.one_time_tokens (user_id, token_type, token_hash, relates_to)
+  VALUES (p_user_id, p_token_type, v_token_hash, p_relates_to);
+
+  RETURN v_raw_token;
+END;
+`,
+});
+
+export const hashPasswordFn = defineFunction('auth.hash_password', {
+  args: [arg('p_password', 'text')],
+  returns: 'text',
+  language: 'plpgsql',
+  security: 'definer',
+  searchPath: ['auth', 'public', 'pg_temp'],
+  body: sql`
+BEGIN
+  RETURN crypt(p_password, gen_salt('bf', 10));
+END;
+`,
+});
+
+export const issueRefreshTokenFn = defineFunction('auth.issue_refresh_token', {
+  args: [arg('p_user_id', 'uuid'), arg('p_family_id', 'uuid', { default: sql`NULL::uuid` }), arg('p_ip_address', 'text', { default: sql`NULL::text` }), arg('p_user_agent', 'text', { default: sql`NULL::text` }), arg('p_device_id', 'uuid', { default: sql`NULL::uuid` }), arg('p_repository_id', 'uuid', { default: sql`NULL::uuid` }), arg('p_ttl', 'interval', { default: sql`'30 days'::interval` })],
+  returns: 'jsonb',
+  language: 'plpgsql',
+  security: 'definer',
+  searchPath: ['auth', 'public', 'pg_temp'],
+  body: sql`
+DECLARE
+  v_raw_token TEXT;
+  v_token_hash TEXT;
+  v_family_id UUID;
+  v_expires_at TIMESTAMPTZ;
+  v_family_count INTEGER;
+  v_oldest_family UUID;
+BEGIN
+  -- Clean up expired tokens for this user (scoped by repository)
+  DELETE FROM auth.refresh_tokens
+  WHERE user_id = p_user_id
+    AND repository_id IS NOT DISTINCT FROM p_repository_id
+    AND expires_at < now();
+
+  -- Enforce per-user family ceiling (only for new families)
+  IF p_family_id IS NULL THEN
+    SELECT count(DISTINCT family_id) INTO v_family_count
+    FROM auth.refresh_tokens
+    WHERE user_id = p_user_id
+      AND repository_id IS NOT DISTINCT FROM p_repository_id
+      AND status = 'active';
+
+    IF v_family_count >= 10 THEN
+      -- Revoke the oldest family
+      SELECT family_id INTO v_oldest_family
+      FROM auth.refresh_tokens
+      WHERE user_id = p_user_id
+        AND repository_id IS NOT DISTINCT FROM p_repository_id
+        AND status = 'active'
+      GROUP BY family_id
+      ORDER BY MIN(created_at) ASC
+      LIMIT 1;
+
+      DELETE FROM auth.refresh_tokens
+      WHERE user_id = p_user_id AND family_id = v_oldest_family;
+    END IF;
+  END IF;
+
+  -- Generate 32 random bytes, base64url encoded
+  v_raw_token := rtrim(translate(
+    encode(gen_random_bytes(32), 'base64'),
+    '+/=', '-_ '
+  ));
+
+  -- Store SHA-256 hash, not the raw token
+  v_token_hash := encode(digest(v_raw_token, 'sha256'), 'hex');
+  v_family_id := COALESCE(p_family_id, gen_random_uuid());
+  v_expires_at := now() + p_ttl;
+
+  INSERT INTO auth.refresh_tokens (
+    repository_id, user_id, token_hash, family_id, status,
+    ip_address, user_agent, device_id, expires_at
+  )
+  VALUES (
+    p_repository_id, p_user_id, v_token_hash, v_family_id, 'active',
+    p_ip_address, p_user_agent, p_device_id, v_expires_at
+  );
+
+  RETURN jsonb_build_object(
+    'token', v_raw_token,
+    'familyId', v_family_id,
+    'expiresAt', v_expires_at
+  );
+END;
+`,
+});
+
+export const jwtFn = defineFunction('auth.jwt', {
+  returns: 'jsonb',
+  language: 'sql',
+  volatility: 'stable',
+  abilities: [can('execute', { role: 'admin' }), can('execute', { role: 'anon' }), can('execute', { role: 'authenticated' })],
+  body: sql`
+  SELECT COALESCE(
+    nullif(current_setting('request.jwt.claims', true), '')::jsonb,
+    '{}'::jsonb
+  );
+`,
+});
+
+export const oauthSignInFn = defineFunction('auth.oauth_sign_in', {
+  args: [arg('p_provider', 'text'), arg('p_provider_id', 'text'), arg('p_email', 'text'), arg('p_identity_data', 'jsonb', { default: sql`'{}'::jsonb` })],
+  returns: 'jsonb',
+  language: 'plpgsql',
+  security: 'definer',
+  searchPath: ['auth', 'public', 'pg_temp'],
+  body: sql`
+DECLARE
+  v_identity RECORD;
+  v_user RECORD;
+  v_providers JSONB;
+BEGIN
+  -- Look up existing identity
+  SELECT * INTO v_identity FROM auth.identities
+  WHERE provider = p_provider AND provider_id = p_provider_id;
+
+  IF FOUND THEN
+    -- Existing user, update identity data and sign in
+    SELECT * INTO v_user FROM auth.users WHERE id = v_identity.user_id AND deleted_at IS NULL;
+    IF NOT FOUND THEN
+      RAISE EXCEPTION 'user_disabled' USING ERRCODE = 'P0004';
+    END IF;
+
+    UPDATE auth.identities
+    SET identity_data = p_identity_data, last_sign_in_at = now(), updated_at = now()
+    WHERE id = v_identity.id;
+
+    UPDATE auth.users SET last_sign_in_at = now(), updated_at = now()
+    WHERE id = v_user.id;
+
+    RETURN jsonb_build_object(
+      'sub', v_user.id,
+      'email', v_user.email,
+      'role', v_user.role,
+      'isNewUser', false
+    );
+  END IF;
+
+  -- Check if a user with this email already exists (link account)
+  SELECT * INTO v_user FROM auth.users
+  WHERE email = lower(trim(p_email)) AND deleted_at IS NULL;
+
+  IF FOUND THEN
+    -- Link the new provider to existing user
+    v_providers := COALESCE(v_user.raw_app_meta_data->'providers', '[]'::jsonb);
+    IF NOT v_providers ? p_provider THEN
+      v_providers := v_providers || to_jsonb(p_provider);
+    END IF;
+
+    UPDATE auth.users
+    SET raw_app_meta_data = COALESCE(raw_app_meta_data, '{}'::jsonb)
+        || jsonb_build_object('providers', v_providers),
+        last_sign_in_at = now(),
+        updated_at = now()
+    WHERE id = v_user.id;
+
+    INSERT INTO auth.identities (user_id, provider, provider_id, identity_data, email)
+    VALUES (v_user.id, p_provider, p_provider_id, p_identity_data, lower(trim(p_email)));
+
+    RETURN jsonb_build_object(
+      'sub', v_user.id,
+      'email', v_user.email,
+      'role', v_user.role,
+      'isNewUser', false
+    );
+  END IF;
+
+  -- New user: create auth.users + auth.identities
+  INSERT INTO auth.users (
+    email, role, aud, raw_user_meta_data, raw_app_meta_data,
+    email_confirmed_at, last_sign_in_at
+  )
+  VALUES (
+    lower(trim(p_email)), 'authenticated', 'authenticated',
+    p_identity_data,
+    jsonb_build_object('provider', p_provider, 'providers', jsonb_build_array(p_provider)),
+    now(), now()
+  )
+  RETURNING * INTO v_user;
+
+  INSERT INTO auth.identities (user_id, provider, provider_id, identity_data, email)
+  VALUES (v_user.id, p_provider, p_provider_id, p_identity_data, v_user.email);
+
+  RETURN jsonb_build_object(
+    'sub', v_user.id,
+    'email', v_user.email,
+    'role', v_user.role,
+    'isNewUser', true
+  );
+END;
+`,
+});
+
+export const oauthSignInJwtFn = defineFunction('auth.oauth_sign_in_jwt', {
+  args: [arg('p_provider', 'text'), arg('p_provider_id', 'text'), arg('p_email', 'text'), arg('p_identity_data', 'jsonb', { default: sql`'{}'::jsonb` })],
+  returns: 'jsonb',
+  language: 'plpgsql',
+  security: 'definer',
+  searchPath: ['auth', 'public', 'pg_temp'],
+  body: sql`
+DECLARE
+  v_payload JSONB;
+  v_claims JSONB;
+  v_token TEXT;
+  v_refresh JSONB;
+BEGIN
+  v_payload := auth.oauth_sign_in(p_provider, p_provider_id, p_email, p_identity_data);
+
+  v_claims := v_payload || jsonb_build_object(
+    'iat', extract(epoch FROM now())::bigint,
+    'exp', (extract(epoch FROM now()) + 3600)::bigint
+  );
+  v_token := auth.sign_jwt(v_claims);
+
+  v_refresh := auth.issue_refresh_token((v_payload->>'sub')::uuid);
+
+  RETURN jsonb_build_object(
+    'access_token', v_token,
+    'refresh_token', v_refresh->>'token',
+    'user', v_payload
+  );
+END;
+`,
+});
+
+export const resetPasswordFn = defineFunction('auth.reset_password', {
+  args: [arg('p_token', 'text'), arg('p_new_password', 'text')],
+  returns: 'jsonb',
+  language: 'plpgsql',
+  security: 'definer',
+  searchPath: ['auth', 'public', 'pg_temp'],
+  abilities: [can('execute', { role: 'anon' })],
+  body: sql`
+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;
+`,
+});
+
+export const revokeRefreshTokensFn = defineFunction('auth.revoke_refresh_tokens', {
+  args: [arg('p_user_id', 'uuid'), arg('p_family_id', 'uuid', { default: sql`NULL::uuid` }), arg('p_repository_id', 'uuid', { default: sql`NULL::uuid` })],
+  returns: 'integer',
+  language: 'plpgsql',
+  security: 'definer',
+  searchPath: ['auth', 'public', 'pg_temp'],
+  body: sql`
+DECLARE
+  v_count INTEGER;
+BEGIN
+  IF p_family_id IS NOT NULL THEN
+    DELETE FROM auth.refresh_tokens
+    WHERE user_id = p_user_id AND family_id = p_family_id;
+  ELSIF p_repository_id IS NOT NULL THEN
+    DELETE FROM auth.refresh_tokens
+    WHERE user_id = p_user_id AND repository_id = p_repository_id;
+  ELSE
+    DELETE FROM auth.refresh_tokens
+    WHERE user_id = p_user_id;
+  END IF;
+
+  GET DIAGNOSTICS v_count = ROW_COUNT;
+  RETURN v_count;
+END;
+`,
+});
+
+export const roleFn = defineFunction('auth.role', {
+  returns: 'text',
+  language: 'sql',
+  volatility: 'stable',
+  abilities: [can('execute', { role: 'admin' }), can('execute', { role: 'anon' }), can('execute', { role: 'authenticated' })],
+  body: sql`
+  SELECT COALESCE(
+    nullif(current_setting('request.jwt.claims', true), '')::jsonb ->> 'role',
+    'anon'
+  );
+`,
+});
+
+export const signInFn = defineFunction('auth.sign_in', {
+  args: [arg('p_email', 'text'), arg('p_password', 'text')],
+  returns: 'jsonb',
+  language: 'plpgsql',
+  security: 'definer',
+  searchPath: ['auth', 'public', 'pg_temp'],
+  body: sql`
+DECLARE
+  v_user RECORD;
+  v_valid BOOLEAN;
+BEGIN
+  SELECT * INTO v_user FROM auth.users
+  WHERE email = lower(trim(p_email)) AND deleted_at IS NULL;
+
+  IF NOT FOUND THEN
+    -- Timing-safe: still run bcrypt to prevent user enumeration
+    PERFORM auth.verify_password(p_password,
+      '$2a$10$abcdefghijklmnopqrstuuABCDEFGHIJKLMNOPQRSTUVWXYZ012345');
+    RAISE EXCEPTION 'invalid_credentials' USING ERRCODE = 'P0001';
+  END IF;
+
+  -- Check banned
+  IF v_user.banned_until IS NOT NULL AND v_user.banned_until > now() THEN
+    RAISE EXCEPTION 'user_banned' USING ERRCODE = 'P0006';
+  END IF;
+
+  v_valid := auth.verify_password(p_password, v_user.encrypted_password);
+  IF NOT v_valid THEN
+    RAISE EXCEPTION 'invalid_credentials' USING ERRCODE = 'P0001';
+  END IF;
+
+  -- Update last sign in
+  UPDATE auth.users SET last_sign_in_at = now(), updated_at = now()
+  WHERE id = v_user.id;
+
+  RETURN jsonb_build_object(
+    'sub', v_user.id,
+    'email', v_user.email,
+    'role', v_user.role
+  );
+END;
+`,
+});
+
+export const signInJwtFn = defineFunction('auth.sign_in_jwt', {
+  args: [arg('p_email', 'text'), arg('p_password', 'text')],
+  returns: 'jsonb',
+  language: 'plpgsql',
+  security: 'definer',
+  searchPath: ['auth', 'public', 'pg_temp'],
+  body: sql`
+DECLARE
+  v_payload JSONB;
+  v_claims JSONB;
+  v_token TEXT;
+  v_refresh JSONB;
+BEGIN
+  v_payload := auth.sign_in(p_email, p_password);
+
+  v_claims := v_payload || jsonb_build_object(
+    'iat', extract(epoch FROM now())::bigint,
+    'exp', (extract(epoch FROM now()) + 3600)::bigint
+  );
+  v_token := auth.sign_jwt(v_claims);
+
+  v_refresh := auth.issue_refresh_token((v_payload->>'sub')::uuid);
+
+  RETURN jsonb_build_object(
+    'access_token', v_token,
+    'refresh_token', v_refresh->>'token',
+    'user', v_payload
+  );
+END;
+`,
+});
+
+export const signInSessionFn = defineFunction('auth.sign_in_session', {
+  args: [arg('p_email', 'text'), arg('p_password', 'text'), arg('p_ip_address', 'text', { default: sql`NULL::text` }), arg('p_user_agent', 'text', { default: sql`NULL::text` }), arg('p_device_id', 'uuid', { default: sql`NULL::uuid` })],
+  returns: 'jsonb',
+  language: 'plpgsql',
+  security: 'definer',
+  searchPath: ['auth', 'public', 'pg_temp'],
+  abilities: [can('execute', { role: 'anon' })],
+  body: sql`
+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;
+`,
+});
+
+export const signJwtFn = defineFunction('auth.sign_jwt', {
+  args: [arg('p_payload', 'jsonb')],
+  returns: 'text',
+  language: 'plpgsql',
+  security: 'definer',
+  searchPath: ['auth', 'public', 'pg_temp'],
+  body: sql`
+DECLARE
+  v_header TEXT;
+  v_payload TEXT;
+  v_signing_input TEXT;
+  v_signature TEXT;
+  v_secret TEXT;
+BEGIN
+  v_secret := current_setting('app.jwt_secret', true);
+  IF v_secret IS NULL OR v_secret = '' THEN
+    RAISE EXCEPTION 'app.jwt_secret not set'
+      USING HINT = 'Call SET LOCAL app.jwt_secret before auth.sign_jwt';
+  END IF;
+
+  -- Base64url encode header (replace strips MIME newlines from encode())
+  v_header := rtrim(translate(
+    replace(encode(convert_to('{"alg":"HS256","typ":"JWT"}', 'utf8'), 'base64'), E'\\n', ''),
+    '+/=', '-_ '
+  ));
+
+  -- Base64url encode payload
+  v_payload := rtrim(translate(
+    replace(encode(convert_to(p_payload::text, 'utf8'), 'base64'), E'\\n', ''),
+    '+/=', '-_ '
+  ));
+
+  v_signing_input := v_header || '.' || v_payload;
+
+  -- HMAC-SHA256 signature via pgcrypto
+  v_signature := rtrim(translate(
+    replace(encode(hmac(v_signing_input, v_secret, 'sha256'), 'base64'), E'\\n', ''),
+    '+/=', '-_ '
+  ));
+
+  RETURN v_signing_input || '.' || v_signature;
+END;
+`,
+});
+
+export const signUpFn = defineFunction('auth.sign_up', {
+  args: [arg('p_email', 'text'), arg('p_password', 'text'), arg('p_user_meta_data', 'jsonb', { default: sql`'{}'::jsonb` })],
+  returns: 'jsonb',
+  language: 'plpgsql',
+  security: 'definer',
+  searchPath: ['auth', 'public', 'pg_temp'],
+  body: sql`
+DECLARE
+  v_user RECORD;
+  v_encrypted TEXT;
+BEGIN
+  -- Check if email already exists
+  SELECT id INTO v_user FROM auth.users
+  WHERE email = lower(trim(p_email)) AND deleted_at IS NULL;
+
+  IF FOUND THEN
+    RAISE EXCEPTION 'email_exists' USING ERRCODE = 'P0001';
+  END IF;
+
+  v_encrypted := auth.hash_password(p_password);
+
+  INSERT INTO auth.users (
+    email, encrypted_password, role, aud,
+    raw_user_meta_data, raw_app_meta_data
+  )
+  VALUES (
+    lower(trim(p_email)), v_encrypted, 'authenticated', 'authenticated',
+    p_user_meta_data, jsonb_build_object('provider', 'email', 'providers', jsonb_build_array('email'))
+  )
+  RETURNING * INTO v_user;
+
+  -- Create email identity
+  INSERT INTO auth.identities (user_id, provider, provider_id, identity_data, email)
+  VALUES (v_user.id, 'email', v_user.id::text, p_user_meta_data, v_user.email);
+
+  RETURN jsonb_build_object(
+    'sub', v_user.id,
+    'email', v_user.email,
+    'role', v_user.role
+  );
+END;
+`,
+});
+
+export const signUpJwtFn = defineFunction('auth.sign_up_jwt', {
+  args: [arg('p_email', 'text'), arg('p_password', 'text'), arg('p_user_meta_data', 'jsonb', { default: sql`'{}'::jsonb` })],
+  returns: 'jsonb',
+  language: 'plpgsql',
+  security: 'definer',
+  searchPath: ['auth', 'public', 'pg_temp'],
+  body: sql`
+DECLARE
+  v_payload JSONB;
+  v_claims JSONB;
+  v_token TEXT;
+  v_refresh JSONB;
+BEGIN
+  v_payload := auth.sign_up(p_email, p_password, p_user_meta_data);
+
+  v_claims := v_payload || jsonb_build_object(
+    'iat', extract(epoch FROM now())::bigint,
+    'exp', (extract(epoch FROM now()) + 3600)::bigint
+  );
+  v_token := auth.sign_jwt(v_claims);
+
+  v_refresh := auth.issue_refresh_token((v_payload->>'sub')::uuid);
+
+  RETURN jsonb_build_object(
+    'access_token', v_token,
+    'refresh_token', v_refresh->>'token',
+    'user', v_payload
+  );
+END;
+`,
+});
+
+export const signUpSessionFn = defineFunction('auth.sign_up_session', {
+  args: [arg('p_email', 'text'), arg('p_password', 'text'), arg('p_user_meta_data', 'jsonb', { default: sql`'{}'::jsonb` }), arg('p_ip_address', 'text', { default: sql`NULL::text` }), arg('p_user_agent', 'text', { default: sql`NULL::text` }), arg('p_device_id', 'uuid', { default: sql`NULL::uuid` })],
+  returns: 'jsonb',
+  language: 'plpgsql',
+  security: 'definer',
+  searchPath: ['auth', 'public', 'pg_temp'],
+  abilities: [can('execute', { role: 'anon' })],
+  body: sql`
+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;
+`,
+});
+
+export const uidFn = defineFunction('auth.uid', {
+  returns: 'uuid',
+  language: 'sql',
+  volatility: 'stable',
+  abilities: [can('execute', { role: 'admin' }), can('execute', { role: 'anon' }), can('execute', { role: 'authenticated' })],
+  body: sql`
+  SELECT COALESCE(
+    (nullif(current_setting('request.jwt.claims', true), '')::jsonb ->> 'sub')::uuid,
+    NULL
+  );
+`,
+});
+
+export const validateRefreshTokenFn = defineFunction('auth.validate_refresh_token', {
+  args: [arg('p_token', 'text'), arg('p_device_id', 'uuid', { default: sql`NULL::uuid` }), arg('p_ip_address', 'text', { default: sql`NULL::text` }), arg('p_user_agent', 'text', { default: sql`NULL::text` }), arg('p_ttl', 'interval', { default: sql`'30 days'::interval` })],
+  returns: 'jsonb',
+  language: 'plpgsql',
+  security: 'definer',
+  searchPath: ['auth', 'public', 'pg_temp'],
+  abilities: [can('execute', { role: 'anon' })],
+  body: sql`
+DECLARE
+  v_token_hash TEXT;
+  v_row RECORD;
+  v_user_deleted TIMESTAMPTZ;
+  v_new_token JSONB;
+BEGIN
+  -- 1. Hash the input token
+  v_token_hash := encode(digest(p_token, 'sha256'), 'hex');
+
+  -- 2. Look up with row lock (prevents concurrent refresh races)
+  SELECT id, user_id, family_id, status, expires_at, device_id, repository_id
+  INTO v_row
+  FROM auth.refresh_tokens
+  WHERE token_hash = v_token_hash
+  FOR UPDATE;
+
+  IF NOT FOUND THEN
+    RAISE EXCEPTION 'invalid_token' USING ERRCODE = 'P0001';
+  END IF;
+
+  -- 3. Consumed token reuse = theft detected -> revoke entire family
+  --    Return error as JSONB instead of RAISE because PostgreSQL rolls back
+  --    the DELETE when an exception propagates. Returning normally lets the
+  --    family deletion commit. The caller checks for result.error.
+  IF v_row.status = 'consumed' THEN
+    DELETE FROM auth.refresh_tokens WHERE family_id = v_row.family_id;
+    RETURN jsonb_build_object('error', 'token_reused');
+  END IF;
+
+  -- 4. Check expiry
+  IF v_row.expires_at < now() THEN
+    DELETE FROM auth.refresh_tokens WHERE id = v_row.id;
+    RAISE EXCEPTION 'token_expired' USING ERRCODE = 'P0003';
+  END IF;
+
+  -- 5. Check user is not deleted
+  SELECT deleted_at INTO v_user_deleted
+  FROM auth.users
+  WHERE id = v_row.user_id;
+
+  IF v_user_deleted IS NOT NULL THEN
+    DELETE FROM auth.refresh_tokens WHERE user_id = v_row.user_id;
+    RAISE EXCEPTION 'user_disabled' USING ERRCODE = 'P0004';
+  END IF;
+
+  -- 6. Device binding: if token was issued to a specific device, verify it
+  IF v_row.device_id IS NOT NULL AND p_device_id IS NOT NULL
+     AND v_row.device_id IS DISTINCT FROM p_device_id THEN
+    DELETE FROM auth.refresh_tokens WHERE family_id = v_row.family_id;
+    RAISE EXCEPTION 'device_mismatch' USING ERRCODE = 'P0005';
+  END IF;
+
+  -- 7. Rotate: mark consumed, issue new token in same family
+  UPDATE auth.refresh_tokens
+  SET status = 'consumed'
+  WHERE id = v_row.id;
+
+  -- Inherit repository_id from the original token
+  v_new_token := auth.issue_refresh_token(
+    v_row.user_id,
+    v_row.family_id,
+    p_ip_address,
+    p_user_agent,
+    v_row.device_id,
+    v_row.repository_id,
+    p_ttl
+  );
+
+  RETURN v_new_token || jsonb_build_object('userId', v_row.user_id);
+END;
+`,
+});
+
+export const verifyJwtFn = defineFunction('auth.verify_jwt', {
+  args: [arg('p_token', 'text')],
+  returns: 'jsonb',
+  language: 'plpgsql',
+  security: 'definer',
+  searchPath: ['auth', 'public', 'pg_temp'],
+  body: sql`
+DECLARE
+  v_parts TEXT[];
+  v_signing_input TEXT;
+  v_expected_sig TEXT;
+  v_payload_json JSONB;
+  v_exp BIGINT;
+  v_secret TEXT;
+BEGIN
+  v_secret := current_setting('app.jwt_secret', true);
+  IF v_secret IS NULL OR v_secret = '' THEN
+    RAISE EXCEPTION 'app.jwt_secret not set'
+      USING HINT = 'Call SET LOCAL app.jwt_secret before auth.verify_jwt';
+  END IF;
+
+  v_parts := string_to_array(p_token, '.');
+  IF array_length(v_parts, 1) != 3 THEN
+    RETURN NULL;
+  END IF;
+
+  v_signing_input := v_parts[1] || '.' || v_parts[2];
+
+  -- Recompute expected signature (replace strips MIME newlines)
+  v_expected_sig := rtrim(translate(
+    replace(encode(hmac(v_signing_input, v_secret, 'sha256'), 'base64'), E'\\n', ''),
+    '+/=', '-_ '
+  ));
+
+  IF v_parts[3] != v_expected_sig THEN
+    RETURN NULL;
+  END IF;
+
+  -- Decode payload: base64url -> base64 -> bytes -> text -> jsonb
+  v_payload_json := convert_from(
+    decode(
+      translate(v_parts[2], '-_', '+/') ||
+      repeat('=', (4 - length(v_parts[2]) % 4) % 4),
+      'base64'
+    ),
+    'utf8'
+  )::jsonb;
+
+  -- Check expiration
+  v_exp := (v_payload_json->>'exp')::bigint;
+  IF v_exp IS NOT NULL AND v_exp < extract(epoch FROM now())::bigint THEN
+    RETURN NULL;
+  END IF;
+
+  RETURN v_payload_json;
+END;
+`,
+});
+
+export const verifyOneTimeTokenFn = defineFunction('auth.verify_one_time_token', {
+  args: [arg('p_token', 'text'), arg('p_token_type', 'text')],
+  returns: 'jsonb',
+  language: 'plpgsql',
+  security: 'definer',
+  searchPath: ['auth', 'public', 'pg_temp'],
+  body: sql`
+DECLARE
+  v_token_hash TEXT;
+  v_row RECORD;
+BEGIN
+  v_token_hash := encode(digest(p_token, 'sha256'), 'hex');
+
+  SELECT user_id, relates_to INTO v_row
+  FROM auth.one_time_tokens
+  WHERE token_hash = v_token_hash
+    AND token_type = p_token_type
+  FOR UPDATE;
+
+  IF NOT FOUND THEN
+    RAISE EXCEPTION 'invalid_token' USING ERRCODE = 'P0001';
+  END IF;
+
+  -- Delete the token (one-time use)
+  DELETE FROM auth.one_time_tokens
+  WHERE token_hash = v_token_hash AND token_type = p_token_type;
+
+  RETURN jsonb_build_object(
+    'userId', v_row.user_id,
+    'relatesTo', v_row.relates_to
+  );
+END;
+`,
+});
+
+export const verifyPasswordFn = defineFunction('auth.verify_password', {
+  args: [arg('p_password', 'text'), arg('p_hash', 'text')],
+  returns: 'boolean',
+  language: 'plpgsql',
+  security: 'definer',
+  searchPath: ['auth', 'public', 'pg_temp'],
+  body: sql`
+DECLARE
+  v_normalized TEXT;
+BEGIN
+  -- pgcrypto crypt() only supports $2a$ prefix; bcryptjs produces $2b$.
+  -- $2a$ and $2b$ are byte-identical algorithms — normalize prefix for compat.
+  v_normalized := regexp_replace(p_hash, '^\\$2[by]\\$', '$2a$');
+  RETURN crypt(p_password, v_normalized) = v_normalized;
+END;
+`,
+});
+
+
+// ---------------------------------------------------------------------------
+// The option groups — `generateAuthSQL`'s six switches, as descriptor sets.
+//
+// A thunk could branch at call time; a descriptor array cannot. Rather than make `authModule`
+// a function (which would break every consumer doing `import { authModule }`), the default
+// module stays a static export and `defineAuthModule(opts)` is the parameterized door.
+// ---------------------------------------------------------------------------
+
+/** Password hashing + JWT sign/verify. The internals every other function calls. Always on. */
+export const coreFunctions = [hashPasswordFn, verifyPasswordFn, signJwtFn, verifyJwtFn];
+
+/** The refresh-token family (RFC 6819 rotation). Always on. */
+export const refreshTokenFunctions = [
+  issueRefreshTokenFn, validateRefreshTokenFn, revokeRefreshTokensFn, cleanupRefreshTokensFn,
+];
+
+/** `auth.uid()` / `auth.role()` / `auth.jwt()` — called FROM RLS policies, so granted to the
+ *  request roles rather than left to the owner. Default on. */
+export const accessorFunctions = [uidFn, roleFn, jwtFn];
+
+/** One-time token mint/verify. Default on. */
+export const oneTimeTokenFunctions = [createOneTimeTokenFn, verifyOneTimeTokenFn];
+
+/** Token-gated account actions. Default on. */
+export const tokenActionFunctions = [confirmEmailFn, resetPasswordFn, changePasswordFn];
+
+/** The anon-safe session wrappers — the only sign-in surface anon may execute. Default on. */
+export const sessionWrapperFunctions = [signInSessionFn, signUpSessionFn];
+
+/** The raw sign_in/sign_up/oauth minters. Default on; never granted to anon. */
+export const defaultAuthFunctions = [signUpFn, signInFn, oauthSignInFn];
+
+/** JWT convenience wrappers. Default OFF, matching `generateAuthSQL`. */
+export const jwtWrapperFunctions = [signInJwtFn, signUpJwtFn, oauthSignInJwtFn];
+
+/** Mirrors {@link AuthSQLOptions} in sql.ts — same defaults, same meanings. */
+export interface AuthFunctionOptions {
+  accessors?: boolean;
+  oneTimeTokens?: boolean;
+  tokenActions?: boolean;
+  sessionWrappers?: boolean;
+  defaultAuthFunctions?: boolean;
+  jwtWrappers?: boolean;
+}
+
+/**
+ * The declared function set for a given option shape. Same selection `generateAuthSQL(opts)`
+ * makes, so the two lanes stay comparable object-for-object — which is what the equivalence
+ * test asserts.
+ */
+export function authFunctions(opts: AuthFunctionOptions = {}) {
+  return [
+    ...coreFunctions,
+    ...refreshTokenFunctions,
+    ...(opts.accessors !== false ? accessorFunctions : []),
+    ...(opts.oneTimeTokens !== false ? oneTimeTokenFunctions : []),
+    ...(opts.tokenActions !== false ? tokenActionFunctions : []),
+    ...(opts.sessionWrappers !== false ? sessionWrapperFunctions : []),
+    ...(opts.defaultAuthFunctions !== false ? defaultAuthFunctions : []),
+    ...(opts.jwtWrappers === true ? jwtWrapperFunctions : []),
+  ];
+}

package/src/models/index.ts

@@ -17,7 +17,7 @@ export { MfaFactor } from './mfa-factor';
 export { MfaChallenge } from './mfa-challenge';
 export { OneTimeToken } from './one-time-token';
 
-import { defineModule } from '@everystack/model';
+import { defineModule, type Module } from '@everystack/model';
 import { User } from './user';
 import { Identity } from './identity';
 import { RefreshToken } from './refresh-token';
@@ -25,19 +25,41 @@ import { Device } from './device';
 import { MfaFactor } from './mfa-factor';
 import { MfaChallenge } from './mfa-challenge';
 import { OneTimeToken } from './one-time-token';
-import { generateAuthSQL } from '../sql';
+import { authFunctions, type AuthFunctionOptions } from './functions';
+
+export * from './functions';
 
 /** 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.
+ * The auth Module for a given option shape — the package's complete DB slice: the seven tables
+ * (schema + authz), the `pgcrypto` extension its functions need, and the SECURITY DEFINER
+ * functions as DECLARED derived objects.
+ *
+ * THE FUNCTIONS MOVED FROM `functions` TO `derived`, AND THAT IS THE WHOLE POINT. The `functions`
+ * thunk is read by exactly one command — `db:generate --init` — so an app that adopted brownfield
+ * installed none of them and every gate reported clean, because a reconciler can only compare
+ * what was declared. Declared as `derived`, they are what `db:reconcile` deploys and audits, they
+ * are content-hashed and dependency-ordered, and the compiler revokes PUBLIC on every one of them
+ * unconditionally.
+ *
+ * A function is not expressible as a Model, so this is not the Models growing a new power — it is
+ * the package declaring its own compute layer through the vocabulary that already existed for it.
+ */
+export function defineAuthModule(opts: AuthFunctionOptions = {}): Module {
+  return defineModule({
+    models: authModels,
+    extensions: ['pgcrypto'],
+    derived: authFunctions(opts),
+  });
+}
+
+/**
+ * The auth Module with default options — what an app composes when it wants auth as shipped.
+ *
+ * Deliberately still a VALUE, not a function call. Consumers write `modules = [appModule,
+ * authModule]`; making it `authModule()` would break every one of them for the benefit of the
+ * minority who need to change the option set, and those have {@link defineAuthModule}.
  */
-export const authModule = defineModule({
-  models: authModels,
-  extensions: ['pgcrypto'],
-  functions: generateAuthSQL,
-});
+export const authModule = defineAuthModule();

package/src/sql.ts

@@ -37,7 +37,8 @@ AS $$
 BEGIN
   RETURN crypt(p_password, gen_salt('bf', 10));
 END;
-$$;`;
+$$;
+REVOKE EXECUTE ON FUNCTION auth.hash_password FROM PUBLIC;`;
 
 const VERIFY_PASSWORD = `\
 CREATE OR REPLACE FUNCTION auth.verify_password(p_password TEXT, p_hash TEXT)
@@ -54,7 +55,8 @@ BEGIN
   v_normalized := regexp_replace(p_hash, '^\\$2[by]\\$', '$2a$');
   RETURN crypt(p_password, v_normalized) = v_normalized;
 END;
-$$;`;
+$$;
+REVOKE EXECUTE ON FUNCTION auth.verify_password FROM PUBLIC;`;
 
 const SIGN_JWT = `\
 CREATE OR REPLACE FUNCTION auth.sign_jwt(p_payload JSONB)
@@ -98,7 +100,8 @@ BEGIN
 
   RETURN v_signing_input || '.' || v_signature;
 END;
-$$;`;
+$$;
+REVOKE EXECUTE ON FUNCTION auth.sign_jwt FROM PUBLIC;`;
 
 const VERIFY_JWT = `\
 CREATE OR REPLACE FUNCTION auth.verify_jwt(p_token TEXT)
@@ -156,7 +159,8 @@ BEGIN
 
   RETURN v_payload_json;
 END;
-$$;`;
+$$;
+REVOKE EXECUTE ON FUNCTION auth.verify_jwt FROM PUBLIC;`;
 
 // =============================================================================
 // REFRESH TOKEN FUNCTIONS (RFC 6819)
@@ -391,6 +395,11 @@ REVOKE EXECUTE ON FUNCTION auth.cleanup_refresh_tokens FROM PUBLIC;`;
 // SUPABASE-COMPATIBLE ACCESSOR FUNCTIONS
 // =============================================================================
 
+// The three accessors are SECURITY INVOKER and are called FROM RLS POLICY EXPRESSIONS, which
+// evaluate as the querying role. So PUBLIC comes off — no blanket grant — and the everystack
+// role chain is granted back explicitly. A bare `REVOKE ... FROM PUBLIC` with no grant-back
+// would break every policy that calls them, which is exactly why they must not be lumped in
+// with the internal SECDEF helpers below.
 const AUTH_UID = `\
 CREATE OR REPLACE FUNCTION auth.uid()
 RETURNS uuid
@@ -400,7 +409,9 @@ AS $$
     (nullif(current_setting('request.jwt.claims', true), '')::jsonb ->> 'sub')::uuid,
     NULL
   );
-$$;`;
+$$;
+REVOKE EXECUTE ON FUNCTION auth.uid FROM PUBLIC;
+GRANT EXECUTE ON FUNCTION auth.uid() TO anon, authenticated, admin;`;
 
 const AUTH_ROLE = `\
 CREATE OR REPLACE FUNCTION auth.role()
@@ -411,7 +422,9 @@ AS $$
     nullif(current_setting('request.jwt.claims', true), '')::jsonb ->> 'role',
     'anon'
   );
-$$;`;
+$$;
+REVOKE EXECUTE ON FUNCTION auth.role FROM PUBLIC;
+GRANT EXECUTE ON FUNCTION auth.role() TO anon, authenticated, admin;`;
 
 const AUTH_JWT = `\
 CREATE OR REPLACE FUNCTION auth.jwt()
@@ -422,7 +435,9 @@ AS $$
     nullif(current_setting('request.jwt.claims', true), '')::jsonb,
     '{}'::jsonb
   );
-$$;`;
+$$;
+REVOKE EXECUTE ON FUNCTION auth.jwt FROM PUBLIC;
+GRANT EXECUTE ON FUNCTION auth.jwt() TO anon, authenticated, admin;`;
 
 // =============================================================================
 // ONE-TIME TOKEN FUNCTIONS