@everystack/auth 0.2.5 → 0.3.0

package/README.md

@@ -247,4 +247,8 @@ Part of [everystack](https://github.com/scalable-technology/everystack) — a se
 
 ## License
 
-MIT
+[AGPL-3.0-only](https://www.gnu.org/licenses/agpl-3.0.html) © Scalable Technology, Inc.
+
+A commercial license is available for organizations that cannot or do not wish to
+comply with the AGPL-3.0 terms. For commercial licensing, contact
+licensing@scalable.technology.

package/package.json

@@ -1,8 +1,18 @@
 {
   "name": "@everystack/auth",
-  "version": "0.2.5",
+  "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>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/scalable-technology/everystack.git",
+    "directory": "packages/auth"
+  },
+  "homepage": "https://github.com/scalable-technology/everystack#readme",
+  "bugs": {
+    "url": "https://github.com/scalable-technology/everystack/issues"
+  },
   "publishConfig": {
     "access": "public"
   },
@@ -27,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"
@@ -75,13 +89,9 @@
       "default": "./src/testing.ts"
     }
   },
-  "scripts": {
-    "test": "jest",
-    "build": "tsc --build",
-    "lint": "tsc --noEmit"
-  },
   "dependencies": {
-    "bcryptjs": "3.0.3"
+    "bcryptjs": "3.0.3",
+    "@everystack/model": "0.3.3"
   },
   "peerDependencies": {
     "@everystack/api": ">=0.1.0",
@@ -101,7 +111,6 @@
     }
   },
   "devDependencies": {
-    "@everystack/api": "workspace:*",
     "@types/bcryptjs": "3.0.0",
     "@types/jest": "29.5.14",
     "@types/node": "22.19.18",
@@ -110,6 +119,12 @@
     "jest": "29.7.0",
     "postgres": "3.4.9",
     "ts-jest": "29.4.9",
-    "typescript": "5.9.3"
+    "typescript": "5.9.3",
+    "@everystack/api": "0.2.9"
+  },
+  "scripts": {
+    "test": "jest",
+    "build": "tsc --build",
+    "lint": "tsc --noEmit"
   }
-}
+}

package/src/index.ts

@@ -147,10 +147,22 @@ export interface AuthOptions {
   /** One-time token operations for email confirmation and password recovery.
    *  Required for confirmEmail, forgotPassword, and resetPassword handlers. */
   tokens?: TokenOperations;
-  /** Called after successful signup when tokens are configured. App sends confirmation email. */
+  /** Called after successful signup when tokens are configured. App sends confirmation email.
+   *  Receives a token MINTED IN THE API — owner-only, so this breaks under least-privilege.
+   *  Postgres least-priv path uses `onConfirmationRequested` instead (mint on the worker). */
   onConfirmationRequired?: (user: { id: string; email: string }, token: string) => Promise<void>;
-  /** Called on forgot-password — app sends recovery email. */
+  /** Called on forgot-password with a token MINTED IN THE API (owner-only — breaks under
+   *  least-privilege). Postgres least-priv path uses `onRecoveryRequested` instead. */
   onRecoveryRequired?: (user: { id: string; email: string }, token: string) => Promise<void>;
+  /** Least-privilege confirmation: called after signup with only the new user's identity.
+   *  The API does NOT mint a token — the app enqueues a job; the privileged worker mints the
+   *  one-time token and sends the email. Takes precedence over onConfirmationRequired. */
+  onConfirmationRequested?: (user: { id: string; email: string }) => Promise<void>;
+  /** Least-privilege recovery: called on forgot-password with ONLY the email. The API does
+   *  not read the user table or mint a token — it enqueues a job; the privileged worker
+   *  looks up the user, mints the recovery token, and sends the email. Always responds the
+   *  same to the client (no user enumeration). Takes precedence over onRecoveryRequired. */
+  onRecoveryRequested?: (email: string) => Promise<void>;
   /** Called after email confirmed via one-time token — app updates user record. */
   onEmailConfirmed?: (userId: string) => Promise<void>;
 }
@@ -209,6 +221,11 @@ function assertSafeCookieConfig(cookies: CookieConfig | undefined): void {
 /**
  * Add mode-independent email confirmation and password management handlers.
  * Called after base handlers are created (works with both node and postgres modes).
+ *
+ * Uses `??=` so a handler already provided by the base (e.g. the least-privilege
+ * postgres confirmEmail/resetPassword that run via SECDEF wrappers under withRole)
+ * is NOT overwritten by the generic owner-connection version. Node mode provides
+ * none of these, so it gets the generic implementations.
  */
 function addEmailPasswordFlows(
   handlers: AuthHandlers,
@@ -217,7 +234,7 @@ function addEmailPasswordFlows(
   options?: AuthOptions,
 ): void {
   if (options?.tokens) {
-    handlers.confirmEmail = async (request: Request): Promise<Response> => {
+    handlers.confirmEmail ??= async (request: Request): Promise<Response> => {
       const csrfError = csrfCheck(request, options?.cookies);
       if (csrfError) return csrfError;
 
@@ -244,7 +261,7 @@ function addEmailPasswordFlows(
       }
     };
 
-    handlers.forgotPassword = async (request: Request): Promise<Response> => {
+    handlers.forgotPassword ??= async (request: Request): Promise<Response> => {
       const csrfError = csrfCheck(request, options?.cookies);
       if (csrfError) return csrfError;
 
@@ -279,7 +296,7 @@ function addEmailPasswordFlows(
       return Response.json({ sent: true });
     };
 
-    handlers.resetPassword = async (request: Request): Promise<Response> => {
+    handlers.resetPassword ??= async (request: Request): Promise<Response> => {
       const csrfError = csrfCheck(request, options?.cookies);
       if (csrfError) return csrfError;
 
@@ -313,7 +330,7 @@ function addEmailPasswordFlows(
     };
   }
 
-  handlers.changePassword = async (request: Request): Promise<Response> => {
+  handlers.changePassword ??= async (request: Request): Promise<Response> => {
     const csrfError = csrfCheck(request, options?.cookies);
     if (csrfError) return csrfError;
 

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'] }),
+  ],
+});