@fonderie/auth 1.3.0 → 1.3.2

package/brain/outcomes.md

@@ -0,0 +1,137 @@
+<!-- GENERATED — do not edit. Regenerate with: npm run docs:signatures -->
+
+# @fonderie/auth — outcomes
+
+What this package does to a running app: tables its migrations create,
+rows it seeds, routes it registers. Generated from the migration SQL and
+route tables in source — trust this file instead of reading `dist/` or
+downloading tarballs.
+
+## Database tables (after all migrations)
+
+### `fonderie_email_verifications`
+
+```sql
+token                    TEXT PRIMARY KEY
+user_id                  UUID NOT NULL REFERENCES fonderie_users(id) ON DELETE CASCADE
+expires_at               TIMESTAMPTZ NOT NULL
+created_at               TIMESTAMPTZ NOT NULL DEFAULT now()
+PRIMARY                  KEY (user_id)
+```
+
+### `fonderie_mfa_backup_codes`
+
+```sql
+id                       UUID PRIMARY KEY DEFAULT gen_random_uuid()
+user_id                  UUID NOT NULL REFERENCES fonderie_users(id) ON DELETE CASCADE
+code_hash                TEXT NOT NULL
+used_at                  TIMESTAMPTZ
+created_at               TIMESTAMPTZ NOT NULL DEFAULT now()
+```
+
+### `fonderie_mfa_challenges`
+
+```sql
+token                    TEXT PRIMARY KEY
+user_id                  UUID NOT NULL REFERENCES fonderie_users(id) ON DELETE CASCADE
+expires_at               TIMESTAMPTZ NOT NULL
+used_at                  TIMESTAMPTZ
+created_at               TIMESTAMPTZ NOT NULL DEFAULT now()
+-- INDEX idx_fonderie_mfa_challenges_expires_at (expires_at)
+```
+
+### `fonderie_password_resets`
+
+```sql
+user_id                  UUID PRIMARY KEY REFERENCES fonderie_users(id) ON DELETE CASCADE
+expires_at               TIMESTAMPTZ NOT NULL
+created_at               TIMESTAMPTZ NOT NULL DEFAULT now()
+pin                      TEXT NOT NULL UNIQUE
+-- INDEX idx_fonderie_password_resets_pin (pin)
+```
+
+### `fonderie_phone_verifications`
+
+```sql
+phone                    TEXT PRIMARY KEY
+otp                      TEXT NOT NULL
+expires_at               TIMESTAMPTZ NOT NULL
+created_at               TIMESTAMPTZ NOT NULL DEFAULT now()
+user_id                  UUID REFERENCES fonderie_users(id) ON DELETE CASCADE
+```
+
+### `fonderie_sessions`
+
+```sql
+id                       UUID PRIMARY KEY DEFAULT gen_random_uuid()
+user_id                  UUID NOT NULL REFERENCES fonderie_users(id) ON DELETE CASCADE
+token                    TEXT NOT NULL UNIQUE
+user_agent               TEXT
+ip_address               TEXT
+expires_at               TIMESTAMPTZ NOT NULL
+created_at               TIMESTAMPTZ NOT NULL DEFAULT now()
+sid                      UUID
+-- INDEX idx_fonderie_sessions_expires_at (expires_at)
+-- INDEX idx_fonderie_sessions_sid (sid)
+```
+
+### `fonderie_users`
+
+```sql
+id                       UUID PRIMARY KEY DEFAULT gen_random_uuid()
+email                    TEXT UNIQUE
+password_hash            TEXT
+first_name               TEXT
+last_name                TEXT
+phone                    TEXT
+profile_image_url        TEXT
+locale                   TEXT NOT NULL DEFAULT 'en-US'
+timezone                 TEXT NOT NULL DEFAULT 'UTC'
+provider                 TEXT
+provider_id              TEXT
+is_active                BOOLEAN NOT NULL DEFAULT true
+last_login               TIMESTAMPTZ
+preferences              JSONB NOT NULL DEFAULT '{"notifications":{"email":true
+suspended                BOOLEAN NOT NULL DEFAULT false
+whitelist                BOOLEAN NOT NULL DEFAULT false
+ip_whitelist             JSONB NOT NULL DEFAULT '[]'
+mfa_enabled              BOOLEAN NOT NULL DEFAULT false
+mfa_secret               TEXT
+email_verified_at        TIMESTAMPTZ
+deleted_at               TIMESTAMPTZ
+created_at               TIMESTAMPTZ NOT NULL DEFAULT now()
+updated_at               TIMESTAMPTZ NOT NULL DEFAULT now()
+IF                       NOT EXISTS phone_verified_at TIMESTAMPTZ
+CONSTRAINT               fonderie_users_phone_unique UNIQUE (phone)
+mfa_secret_pending       TEXT
+mfa_secret_pending_expires_at TIMESTAMPTZ
+-- INDEX idx_fonderie_users_email (email)
+```
+
+Raw SQL ships in `node_modules/@fonderie/auth/dist/migrations/sql/` — read it there if you must; never download tarballs.
+
+## HTTP routes registered
+
+| Method | Path | Middleware chain (auth / validation / handler) |
+|---|---|---|
+| POST | `/auth/email/forgot` | `ipLimit('forgot') → validate(forgotPasswordSchema) → acctLimit('forgot') → auth.forgotPassword` |
+| POST | `/auth/email/reset` | `validate(resetPasswordSchema) → auth.resetPassword` |
+| GET | `/auth/google` | `oauth.googleInit` |
+| GET | `/auth/google/callback` | `oauth.googleCallback` |
+| POST | `/auth/login` | `ipLimit('login') → validate(loginSchema) → acctLimit('login') → auth.login` |
+| POST | `/auth/logout` | `requireAuth → validate(refreshSchema) → auth.logout` |
+| POST | `/auth/mfa/backup-codes` | `requireAuth → requireEmailLogin → requireVerified → validate(mfaTokenSchema) → mfa.regenerateBackupCodes` |
+| POST | `/auth/mfa/disable` | `requireAuth → requireEmailLogin → requireVerified → validate(mfaTokenSchema) → mfa.disable` |
+| POST | `/auth/mfa/setup` | `requireAuth → requireEmailLogin → requireVerified → mfa.setup` |
+| POST | `/auth/mfa/verify` | `ipLimit('mfaVerify') → requireAnyAuth → requireEmailLogin → requireVerified → validate(mfaTokenSchema) → mfa.verify` |
+| POST | `/auth/refresh` | `validate(refreshSchema) → auth.refresh` |
+| POST | `/auth/register` | `ipLimit('register') → validate(registerSchema) → auth.register` |
+| GET | `/auth/send-verification` | `requireAuth → auth.sendVerification` |
+| POST | `/auth/verify` | `requireAuth → validate(verifySchema) → auth.verify` |
+| DELETE | `/users` | `requireAuth → verifyGate → user.deleteMe` |
+| GET | `/users` | `requireAuth → user.me` |
+| PUT | `/users/email` | `requireAuth → verifyGate → validate(updateEmailSchema) → user.updateEmail` |
+| PUT | `/users/password` | `requireAuth → validate(changePasswordSchema) → user.changePassword` |
+| PUT | `/users/phone` | `requireAuth → verifyGate → validate(updatePhoneSchema) → user.updatePhone` |
+| PUT | `/users/preferences` | `requireAuth → verifyGate → validate(updatePreferencesSchema) → user.updatePreferences` |
+| PUT | `/users/profile` | `requireAuth → verifyGate → validate(updateProfileSchema) → user.updateProfile` |

package/brain/signatures.md

@@ -0,0 +1,139 @@
+<!-- GENERATED — do not edit. Regenerate with: npm run docs:signatures -->
+
+# @fonderie/auth — signatures
+
+## @fonderie/auth
+
+Subpath exports: `@fonderie/auth/types`, `@fonderie/auth/middleware`, `@fonderie/auth/migrations`
+
+```ts
+interface IUser {
+    id: string;
+    email: string | null;
+    firstName: string | null;
+    lastName: string | null;
+    phone: string | null;
+    profileImageUrl: string | null;
+    locale: string;
+    timezone: string;
+    isActive: boolean;
+    lastLogin: Date | null;
+    preferences: IUserPreferences;
+    suspended: boolean;
+    whitelist: boolean;
+    ipWhitelist: string[];
+    deletedAt: Date | null;
+    createdAt: Date;
+    updatedAt: Date;
+    mfaEnabled: boolean;
+    passwordHash: string | null;
+    emailVerifiedAt: Date | null;
+}
+
+interface ISession {
+    id: string;
+    token: string;
+    userId: string;
+    userAgent: string | null;
+    ipAddress: string | null;
+    expiresAt: Date;
+    createdAt: Date;
+}
+
+interface IMfaChallenge {
+    token: string;
+    userId: string;
+    expiresAt: Date;
+    usedAt: Date | null;
+}
+
+new AuthModule(store: IStoreAdapter, config: IAuthConfig, bus?: EventBus | undefined): AuthModule
+  .name: "@fonderie/auth"
+  .install(app: IFonderieApp): void
+
+interface IAuthConfig extends IAuthSecrets, IAuthRuntimeConfig {
+    secureCookies?: boolean;
+    rateLimit?: IAuthRateLimitConfig | false;
+    accessTokenDuration?: string;
+    providers: ('email' | 'phone' | 'google' | 'github')[];
+    appName?: string;
+    resolve?: (ctx: {
+        meta: Record<string, unknown>;
+    }) => Partial<IAuthRuntimeConfig>;
+}
+
+interface IAuthSecrets {
+    jwtSecret: string;
+    google?: {
+        clientId: string;
+        clientSecret: string;
+        redirectUri: string;
+    };
+}
+
+interface IAuthRuntimeConfig {
+    sessionDuration?: string;
+    verificationCooldown?: number;
+    mfa?: boolean;
+    requireVerification?: boolean;
+}
+
+const AUTH_CONFIG_KEYS: { sessionDuration: string; verificationCooldown: string; mfa: string; requireVerification: string; }
+
+const MESSAGE_KEYS: { readonly emailRegistration: "email-registration"; readonly emailVerification: "email-verification"; readonly passwordReset: "password-reset"; readonly phoneOtp: "phone-otp"; readonly mfaEnabled: "mfa-enabled"; readonly mfaDisabled: "mfa-disabled"; readonly mfaBackupCodesRegenerated: "mfa-backup-codes-regenerated"; readonly emailChanged: "email-changed"; readonly phoneChanged: "phone-changed"; }
+
+type AuthMessageKey = (typeof MESSAGE_KEYS)[keyof typeof MESSAGE_KEYS];
+
+interface IUserDTO {
+    id: string;
+    email: string;
+    firstName: string;
+    lastName: string;
+    phone: string;
+    profileImageUrl: string;
+    isActive: boolean;
+    lastLogin: string;
+    preferences: IUserPreferences;
+    isEmailVerified: boolean;
+    isPhoneVerified: boolean;
+    mfaEnabled: boolean;
+    suspended: boolean;
+    whitelist: boolean;
+    ipWhitelist: string[];
+    createdAt: string;
+    updatedAt: string;
+}
+
+function toUserDTO(user: IUser, phoneVerified?: boolean): IUserDTO
+
+function validate(schema: IRequestSchema): Middleware
+
+namespace schemas — exports: ChangePasswordInput, LoginInput, RegisterInput, ResetPasswordInput, changePasswordSchema, forgotPasswordSchema, loginSchema, mfaTokenSchema, refreshSchema, registerSchema, resetPasswordSchema, updateEmailSchema, updatePhoneSchema, updatePreferencesSchema, updateProfileSchema, verifySchema
+
+type RegisterInput = z.infer<typeof registerSchema>;
+
+type LoginInput = z.infer<typeof loginSchema>;
+
+type ResetPasswordInput = z.infer<typeof resetPasswordSchema>;
+
+type ChangePasswordInput = z.infer<typeof changePasswordSchema>;
+
+function withSession(store: IStoreAdapter, config: IAuthConfig): Middleware
+
+function requireAuth(ctx: IFonderieContext, next: () => Promise<Response>): Promise<Response>
+
+function normalizeEmail(email: string): string
+
+function normalizeEmailSafe(email: string): string | null
+
+function buildAuthIpLimiter(route: AuthLimitedRoute, store: IStoreAdapter, config: false | IAuthRateLimitConfig | undefined): Middleware | null
+
+function buildAuthAccountLimiter(route: AuthLimitedRoute, store: IStoreAdapter, config: false | IAuthRateLimitConfig | undefined): Middleware | null
+
+interface IAuthRateLimitConfig {
+    store?: IRateLimitStore;
+    rules?: Partial<Record<AuthLimitedRoute, IRateLimitRule | false>>;
+}
+
+type AuthLimitedRoute = 'login' | 'register' | 'forgot' | 'mfaVerify';
+```

package/dist/migrations/sql/001_auth.sql

@@ -0,0 +1,73 @@
+-- ── fonderie_users ───────────────────────────────────────────────
+CREATE TABLE IF NOT EXISTS fonderie_users (
+	id                UUID        PRIMARY KEY DEFAULT gen_random_uuid(),
+	email             TEXT        NOT NULL UNIQUE,
+	password_hash     TEXT,
+	first_name        TEXT,
+	last_name         TEXT,
+	phone             TEXT,
+	profile_image_url TEXT,
+	locale            TEXT        NOT NULL DEFAULT 'en-US',
+	timezone          TEXT        NOT NULL DEFAULT 'UTC',
+	provider          TEXT,
+	provider_id       TEXT,
+	is_active         BOOLEAN     NOT NULL DEFAULT true,
+	last_login        TIMESTAMPTZ,
+	preferences       JSONB       NOT NULL DEFAULT '{"notifications":{"email":true,"inApp":true,"sms":false,"push":false},"emailDigest":"immediate","dateFormat":"MM/DD/YYYY","timeFormat":"hh:mm A"}',
+	suspended         BOOLEAN     NOT NULL DEFAULT false,
+	whitelist         BOOLEAN     NOT NULL DEFAULT false,
+	ip_whitelist      JSONB       NOT NULL DEFAULT '[]',
+	mfa_enabled       BOOLEAN     NOT NULL DEFAULT false,
+	mfa_secret        TEXT,
+	email_verified_at TIMESTAMPTZ,
+	deleted_at        TIMESTAMPTZ,
+	created_at        TIMESTAMPTZ NOT NULL DEFAULT now(),
+	updated_at        TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE INDEX IF NOT EXISTS idx_fonderie_users_email ON fonderie_users (email);
+
+-- ── fonderie_email_verifications ─────────────────────────────────
+CREATE TABLE IF NOT EXISTS fonderie_email_verifications (
+	token      TEXT        PRIMARY KEY,
+	user_id    UUID        NOT NULL REFERENCES fonderie_users(id) ON DELETE CASCADE,
+	expires_at TIMESTAMPTZ NOT NULL,
+	created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+-- ── fonderie_password_resets ─────────────────────────────────────
+CREATE TABLE IF NOT EXISTS fonderie_password_resets (
+	user_id    UUID        PRIMARY KEY REFERENCES fonderie_users(id) ON DELETE CASCADE,
+	token      TEXT        NOT NULL UNIQUE,
+	expires_at TIMESTAMPTZ NOT NULL,
+	created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE INDEX IF NOT EXISTS idx_fonderie_password_resets_token ON fonderie_password_resets (token);
+
+-- ── fonderie_sessions ────────────────────────────────────────────
+CREATE TABLE IF NOT EXISTS fonderie_sessions (
+	id         UUID        PRIMARY KEY DEFAULT gen_random_uuid(),
+	user_id    UUID        NOT NULL REFERENCES fonderie_users(id) ON DELETE CASCADE,
+	token      TEXT        NOT NULL UNIQUE,
+	user_agent TEXT,
+	ip_address TEXT,
+	expires_at TIMESTAMPTZ NOT NULL,
+	created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE INDEX IF NOT EXISTS idx_fonderie_sessions_user_id    ON fonderie_sessions (user_id);
+CREATE INDEX IF NOT EXISTS idx_fonderie_sessions_token      ON fonderie_sessions (token);
+CREATE INDEX IF NOT EXISTS idx_fonderie_sessions_expires_at ON fonderie_sessions (expires_at);
+
+-- ── fonderie_mfa_challenges ──────────────────────────────────────
+CREATE TABLE IF NOT EXISTS fonderie_mfa_challenges (
+	token      TEXT        PRIMARY KEY,
+	user_id    UUID        NOT NULL REFERENCES fonderie_users(id) ON DELETE CASCADE,
+	expires_at TIMESTAMPTZ NOT NULL,
+	used_at    TIMESTAMPTZ,
+	created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE INDEX IF NOT EXISTS idx_fonderie_mfa_challenges_user_id    ON fonderie_mfa_challenges (user_id);
+CREATE INDEX IF NOT EXISTS idx_fonderie_mfa_challenges_expires_at ON fonderie_mfa_challenges (expires_at);

package/dist/migrations/sql/002_phone_auth.sql

@@ -0,0 +1,20 @@
+-- Make email nullable to support phone-only users
+ALTER TABLE fonderie_users ALTER COLUMN email DROP NOT NULL;
+
+-- Track when phone was last verified via OTP
+ALTER TABLE fonderie_users ADD COLUMN IF NOT EXISTS
+	phone_verified_at TIMESTAMPTZ;
+
+-- Unique constraint on phone (NULLs are distinct in PostgreSQL, so existing
+-- rows with NULL phone are unaffected)
+ALTER TABLE fonderie_users
+	ADD CONSTRAINT fonderie_users_phone_unique UNIQUE (phone);
+
+-- ── fonderie_phone_verifications ─────────────────────────────────
+-- One pending OTP per phone number at a time (phone is the PK)
+CREATE TABLE IF NOT EXISTS fonderie_phone_verifications (
+	phone      TEXT        PRIMARY KEY,
+	otp        TEXT        NOT NULL,
+	expires_at TIMESTAMPTZ NOT NULL,
+	created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);

package/dist/migrations/sql/003_phone_registration_name.sql

@@ -0,0 +1,4 @@
+-- No longer needed: first_name/last_name are written directly to
+-- fonderie_users on registration, so they never need to travel through
+-- the verifications table.
+SELECT 1;

package/dist/migrations/sql/004_drop_phone_verif_name_cols.sql

@@ -0,0 +1,5 @@
+-- Drop columns added speculatively in 003 — user is created immediately
+-- on registration so names never need to be carried in this table.
+ALTER TABLE fonderie_phone_verifications
+	DROP COLUMN IF EXISTS first_name,
+	DROP COLUMN IF EXISTS last_name;

package/dist/migrations/sql/005_phone_verification_user_id.sql

@@ -0,0 +1,6 @@
+-- Link phone verifications to a specific user so verify can be done by JWT alone
+ALTER TABLE fonderie_phone_verifications
+	ADD COLUMN IF NOT EXISTS user_id UUID REFERENCES fonderie_users(id) ON DELETE CASCADE;
+
+CREATE INDEX IF NOT EXISTS idx_phone_verifications_user_id
+	ON fonderie_phone_verifications (user_id);

package/dist/migrations/sql/006_drop_phone_verified_at.sql

@@ -0,0 +1 @@
+ALTER TABLE fonderie_users DROP COLUMN IF EXISTS phone_verified_at;

package/dist/migrations/sql/007_email_verif_user_id_pk.sql

@@ -0,0 +1,14 @@
+-- Swap primary key from token to user_id so concurrent users can share the
+-- same 6-digit PIN without colliding.  Deduplicate first (keep newest row per
+-- user) in case stale data exists, then promote user_id to PK.
+
+DELETE FROM fonderie_email_verifications e1
+USING fonderie_email_verifications e2
+WHERE e1.user_id = e2.user_id
+  AND e1.created_at < e2.created_at;
+
+ALTER TABLE fonderie_email_verifications
+    DROP CONSTRAINT fonderie_email_verifications_pkey;
+
+ALTER TABLE fonderie_email_verifications
+    ADD PRIMARY KEY (user_id);

package/dist/migrations/sql/008_password_reset_pin.sql

@@ -0,0 +1,4 @@
+ALTER TABLE fonderie_password_resets RENAME COLUMN token TO pin;
+
+DROP INDEX IF EXISTS idx_fonderie_password_resets_token;
+CREATE INDEX IF NOT EXISTS idx_fonderie_password_resets_pin ON fonderie_password_resets (pin);

package/dist/migrations/sql/009_password_reset_created_at.sql

@@ -0,0 +1 @@
+ALTER TABLE fonderie_password_resets ADD COLUMN IF NOT EXISTS created_at TIMESTAMPTZ NOT NULL DEFAULT now();

package/dist/migrations/sql/010_mfa_pending_secret.sql

@@ -0,0 +1,3 @@
+ALTER TABLE fonderie_users
+  ADD COLUMN IF NOT EXISTS mfa_secret_pending            TEXT,
+  ADD COLUMN IF NOT EXISTS mfa_secret_pending_expires_at TIMESTAMPTZ;

package/dist/migrations/sql/011_mfa_backup_codes.sql

@@ -0,0 +1,10 @@
+CREATE TABLE IF NOT EXISTS fonderie_mfa_backup_codes (
+    id         UUID        PRIMARY KEY DEFAULT gen_random_uuid(),
+    user_id    UUID        NOT NULL REFERENCES fonderie_users(id) ON DELETE CASCADE,
+    code_hash  TEXT        NOT NULL,
+    used_at    TIMESTAMPTZ,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE INDEX IF NOT EXISTS idx_fonderie_mfa_backup_codes_user_id
+    ON fonderie_mfa_backup_codes (user_id);

package/dist/migrations/sql/012_drop_skills.sql

@@ -0,0 +1 @@
+ALTER TABLE fonderie_users DROP COLUMN IF EXISTS skills;

package/dist/migrations/sql/013_sessions_sid.sql

@@ -0,0 +1,5 @@
+-- Session-backed access-token revocation: access tokens carry the sid of
+-- the refresh session they were issued with; withSession() rejects access
+-- tokens whose session row is gone (logout, rotation, password change).
+ALTER TABLE fonderie_sessions ADD COLUMN IF NOT EXISTS sid UUID;
+CREATE INDEX IF NOT EXISTS idx_fonderie_sessions_sid ON fonderie_sessions (sid);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fonderie/auth",
-	"version": "1.3.0",
+	"version": "1.3.2",
 	"description": "Drop-in auth for SaaS — email/password, phone OTP, Google OAuth, stateless JWT sessions, TOTP-based MFA with backup codes, and self-service password recovery.",
 	"keywords": [
 		"fonderie-js",
@@ -58,7 +58,7 @@
 		"jsonwebtoken": "^9.0.3",
 		"qrcode": "^1.5.4",
 		"zod": "^4.4.3",
-		"@fonderie/rate-limit": "^0.1.0"
+		"@fonderie/rate-limit": "^0.1.1"
 	},
 	"peerDependencies": {
 		"@fonderie/core": "^0.1.1",
@@ -88,16 +88,17 @@
 	},
 	"files": [
 		"dist",
+		"brain",
 		"LICENSE",
 		"README.md"
 	],
 	"repository": {
 		"type": "git",
-		"url": "git+https://github.com/fonderie-js/sdk.git",
+		"url": "git+https://github.com/fonderiejs/sdk.git",
 		"directory": "packages/auth"
 	},
-	"homepage": "https://github.com/fonderie-js/sdk/tree/main/packages/auth#readme",
+	"homepage": "https://github.com/fonderiejs/sdk/tree/main/packages/auth#readme",
 	"bugs": {
-		"url": "https://github.com/fonderie-js/sdk/issues"
+		"url": "https://github.com/fonderiejs/sdk/issues"
 	}
 }