@everystack/auth 0.1.0 → 0.2.0

package/src/schema.ts

@@ -1,20 +1,29 @@
 /**
- * Auth schema — everyschema auth.* tables
+ * Auth schema — default tables for everystack auth.
  *
  * Tables:
- *   sessions    — Unified STI sessions (auth/work/agent/ws domains)
- *   identities  — Abstraction layer between users and credentials
- *   credentials — How identities prove who they are (passkey, oauth, challenge, etc.)
- *   devices     — Device attestation with trust scores
+ *   users           — Supabase-compatible user table (batteries included, replaceable)
+ *   identities      — OAuth provider links (Supabase-compatible)
+ *   refreshTokens   — RFC 6819 family-based token rotation with reuse detection
+ *   devices         — Device registry (persistent ID, push tokens) + attestation
+ *   mfaFactors      — TOTP + WebAuthn multi-factor authentication
+ *   mfaChallenges   — Ephemeral MFA challenge state
+ *   oneTimeTokens   — Email confirmation, password reset, magic links
  *
- * @see everyschema — canonical schema definitions
+ * 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.
  */
 
 import {
   pgSchema,
+  boolean,
   text,
   timestamp,
   uuid,
+  varchar,
   integer,
   index,
   uniqueIndex,
@@ -26,159 +35,121 @@ const authSchema = pgSchema('auth');
 export { authSchema };
 
 // =============================================================================
-// SESSIONS (unified STI)
+// USERS
 // =============================================================================
 
 /**
- * Unified sessions table
- *
- * domain='auth' data: { biometricAt, attestationAt, authorizedBy, authorizedAt,
- *   revokedBy, revokedReason, challenge, challengeExpiresAt, browserName,
- *   browserOs, location, locationHint, familyId }
- *
- * domain='work' data: { goals, taskIds, summary, outcome }
+ * Default user table. Supabase-compatible column names for zero-friction migration.
  *
- * domain='agent' data: { agentType, scopes, context, currentTask,
- *   lockedResources, transport, toolCallCount, errorCount }
- *
- * domain='ws' data: { connectionId, channels }
+ * 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 sessions = authSchema.table(
-  'sessions',
+export const users = authSchema.table(
+  'users',
   {
     id: uuid('id').primaryKey().defaultRandom(),
-
-    // STI discriminator
-    domain: text('domain').notNull(), // 'auth' | 'work' | 'agent' | 'ws'
-    type: text('type'), // auth sub-types: 'device' | 'web' | 'refresh' (NULL for work/agent/ws)
-
-    // Actor
-    userId: uuid('user_id'),
-    agentId: text('agent_id'),
-
-    // Context
-    repositoryId: uuid('repository_id'),
-    deviceId: uuid('device_id'),
-
-    // Auth: session token
-    tokenHash: text('token_hash').unique(),
-
-    // Status (shared across domains, different values per domain)
-    status: text('status').notNull().default('active'),
-
-    // Auth: lifecycle timestamps
-    expiresAt: timestamp('expires_at', { withTimezone: true }),
-    lastUsedAt: timestamp('last_used_at', { withTimezone: true }),
-    revokedAt: timestamp('revoked_at', { withTimezone: true }),
-
-    // Auth: security context
-    ipAddress: text('ip_address'),
-    userAgent: text('user_agent'),
-
-    // Work/agent: lifecycle
-    startedAt: timestamp('started_at', { withTimezone: true }),
-    endedAt: timestamp('ended_at', { withTimezone: true }),
-
-    // Agent: counters
-    toolCallCount: integer('tool_call_count'),
-    errorCount: integer('error_count'),
-
-    // Domain-specific data
-    data: jsonb('data'),
-
-    // Timestamps
+    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) => ({
-    domainIdx: index('sessions_domain_idx').on(table.domain),
-    domainUserIdx: index('sessions_domain_user_idx').on(table.domain, table.userId),
-    domainAgentStatusIdx: index('sessions_domain_agent_status_idx').on(table.domain, table.agentId, table.status),
-    typeIdx: index('sessions_type_idx').on(table.type),
-    userIdx: index('sessions_user_idx').on(table.userId),
-    deviceIdx: index('sessions_device_idx').on(table.deviceId),
-    tokenIdx: uniqueIndex('sessions_token_idx').on(table.tokenHash),
-    statusIdx: index('sessions_status_idx').on(table.status),
-    expiresIdx: index('sessions_expires_idx').on(table.expiresAt),
-    repoIdx: index('sessions_repo_idx').on(table.repositoryId),
-    createdIdx: index('sessions_created_idx').on(table.createdAt),
+    emailIdx: uniqueIndex('users_email_idx').on(table.email),
+    instanceIdx: index('users_instance_id_idx').on(table.instanceId),
   })
 );
 
 // =============================================================================
-// IDENTITIES (WHO can be granted permissions)
+// IDENTITIES
 // =============================================================================
 
 /**
- * Abstraction layer between users and credentials. Separates WHO (identity)
- * from HOW they prove it (credentials).
+ * OAuth provider links. Supabase-compatible.
  *
- * type='user': linked to auth.users via userId
- * type='external': email addresses, phone numbers, external services
+ * 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(),
-    type: text('type').notNull(), // user | agent | service | aws_account | organization | external
-    userId: uuid('user_id'),
-    externalId: text('external_id'),
-    name: text('name').notNull(),
-    metadata: jsonb('metadata'),
-
-    // Spam protection for external identities
-    reputationScore: integer('reputation_score').default(0),
-    blockedAt: timestamp('blocked_at', { withTimezone: true }),
-    blockReason: text('block_reason'),
-
+    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) => ({
-    typeIdx: index('identities_type_idx').on(table.type),
+    providerUniqueIdx: uniqueIndex('identities_provider_id_provider_idx').on(
+      table.providerId,
+      table.provider
+    ),
     userIdx: index('identities_user_idx').on(table.userId),
-    externalIdx: index('identities_external_idx').on(table.type, table.externalId),
-    blockedIdx: index('identities_blocked_idx').on(table.blockedAt),
   })
 );
 
 // =============================================================================
-// CREDENTIALS (HOW identities prove who they are)
+// REFRESH TOKENS
 // =============================================================================
 
 /**
- * Links to auth.identities, not directly to users.
+ * 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
  *
- * Type-specific fields:
- * - passkey/ssh_key: publicKey, fingerprint
- * - password: secretHash (bcrypt/argon2/scram)
- * - api_key: credentialId (key prefix), secretHash (argon2)
- * - oauth: credentialId (providerUid), name (provider), metadata ({email})
- * - challenge: credentialId (nonce), expiresAt (5min), revokedAt (consumed)
+ * PostgreSQL path uses SECURITY DEFINER functions with SELECT FOR UPDATE
+ * for full atomicity. JS path uses consumed-token reuse detection as mitigation.
  */
-export const credentials = authSchema.table(
-  'credentials',
+export const refreshTokens = authSchema.table(
+  'refresh_tokens',
   {
     id: uuid('id').primaryKey().defaultRandom(),
-    type: text('type').notNull(), // passkey | ssh_key | password | api_key | oauth | challenge
-    identityId: uuid('identity_id').notNull(),
-    credentialId: text('credential_id'),
-    name: text('name'),
-    publicKey: text('public_key'),
-    secretHash: text('secret_hash'),
+    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(),
-    expiresAt: timestamp('expires_at', { withTimezone: true }),
-    lastUsedAt: timestamp('last_used_at', { withTimezone: true }),
-    revokedAt: timestamp('revoked_at', { withTimezone: true }),
-    revokedBy: uuid('revoked_by'),
-    metadata: jsonb('metadata'),
   },
   (table) => ({
-    typeIdx: index('credentials_type_idx').on(table.type),
-    identityIdx: index('credentials_identity_idx').on(table.identityId),
-    credentialIdIdx: uniqueIndex('credentials_credential_id_idx').on(table.type, table.credentialId),
-    expiresIdx: index('credentials_expires_idx').on(table.expiresAt),
-    activeIdx: index('credentials_active_idx')
-      .on(table.identityId)
-      .where(sql`${table.revokedAt} IS NULL`),
+    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'`),
   })
 );
 
@@ -187,38 +158,159 @@ export const credentials = authSchema.table(
 // =============================================================================
 
 /**
- * Device attestation with trust scores and revocation.
+ * 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
  *
- * Maps from everystack security_devices:
- *   keyId → keyId, publicKey → publicKey, counter → attestationCount,
- *   attestedAt → registeredAt, lastAssertionAt → lastSeenAt
+ * 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(),
-    userId: uuid('user_id').notNull(),
+    repositoryId: uuid('repository_id'),
+    userId: uuid('user_id').references(() => users.id, { onDelete: 'set null' }),
     deviceId: text('device_id').notNull().unique(),
-    platform: text('platform').notNull(),
-    attestationType: text('attestation_type').notNull(),
-    keyId: text('key_id'),
-    publicKey: text('public_key'),
-    attestationData: jsonb('attestation_data'),
+    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'),
-    lastAttestation: timestamp('last_attestation', { withTimezone: true }),
-    attestationCount: integer('attestation_count').notNull().default(0),
+    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),
+  })
+);