@everystack/auth 0.1.0

package/src/refresh.ts

@@ -0,0 +1,204 @@
+/**
+ * Database-backed refresh token rotation using auth.sessions.
+ *
+ * Tokens are random strings (not JWTs). Only SHA-256 hashes are stored.
+ * Each token is one-time use — on refresh, the old token is deleted and a new one created.
+ * Tokens are grouped by `familyId` (stored in data JSONB) for theft detection.
+ *
+ * Refresh tokens are stored as sessions with domain='auth', type='refresh'.
+ *
+ * Usage: Pass a `sessions` table reference to `createAuthHandlers()`.
+ * If not provided, the existing JWT-based refresh behavior is preserved.
+ */
+
+import { and, eq, lt, sql } from 'drizzle-orm';
+
+const REFRESH_TOKEN_BYTES = 32;
+const REFRESH_TOKEN_TTL_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
+
+/**
+ * Generate a cryptographically random token string.
+ * 32 random bytes encoded as base64url (URL-safe, no padding).
+ */
+export function generateToken(): string {
+  const bytes = crypto.getRandomValues(new Uint8Array(REFRESH_TOKEN_BYTES));
+  // Manual base64url: btoa() then replace URL-unsafe chars and strip padding
+  const base64 = btoa(String.fromCharCode(...bytes));
+  return base64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+/**
+ * SHA-256 hash a token for storage. Returns hex string.
+ * Uses Web Crypto API — no native dependencies.
+ */
+export async function hashToken(token: string): Promise<string> {
+  const data = new TextEncoder().encode(token);
+  const hashBuffer = await crypto.subtle.digest('SHA-256', data);
+  return Array.from(new Uint8Array(hashBuffer))
+    .map((b) => b.toString(16).padStart(2, '0'))
+    .join('');
+}
+
+/**
+ * Create a new refresh token, store its hash in the sessions table,
+ * and return the raw token to send to the client.
+ *
+ * @param db - Drizzle database instance
+ * @param table - The sessions table reference
+ * @param userId - The user ID to associate with this token
+ * @param familyId - Optional family ID (inherits on rotation, new UUID if omitted)
+ * @returns Raw token string and family ID
+ */
+export async function createRefreshToken(
+  db: any,
+  table: any,
+  userId: string,
+  familyId?: string,
+): Promise<{ token: string; familyId: string }> {
+  // Clean up expired refresh sessions for this user (prevents accumulation)
+  await db.delete(table).where(
+    and(
+      eq(table.userId, userId),
+      eq(table.domain, 'auth'),
+      eq(table.type, 'refresh'),
+      lt(table.expiresAt, new Date()),
+    ),
+  );
+
+  const token = generateToken();
+  const tokenHash = await hashToken(token);
+  const family = familyId ?? crypto.randomUUID();
+  const expiresAt = new Date(Date.now() + REFRESH_TOKEN_TTL_MS);
+
+  await db.insert(table).values({
+    domain: 'auth',
+    type: 'refresh',
+    status: 'active',
+    userId,
+    tokenHash,
+    expiresAt,
+    data: { familyId: family },
+  });
+
+  return { token, familyId: family };
+}
+
+/**
+ * Validate a refresh token and rotate it.
+ * Deletes the old token and creates a new one in the same family.
+ *
+ * @throws {TokenError} If token is invalid, expired, or already used
+ * @returns User ID, new raw token, and family ID
+ */
+export async function rotateRefreshToken(
+  db: any,
+  table: any,
+  rawToken: string,
+): Promise<{ userId: string; token: string; familyId: string }> {
+  const tokenHash = await hashToken(rawToken);
+
+  const [existing] = await db
+    .select()
+    .from(table)
+    .where(and(
+      eq(table.tokenHash, tokenHash),
+      eq(table.domain, 'auth'),
+      eq(table.type, 'refresh'),
+    ))
+    .limit(1);
+
+  if (!existing) {
+    throw new TokenError('invalid_token', 'Refresh token not found');
+  }
+
+  // Check expiry
+  if (new Date(existing.expiresAt) < new Date()) {
+    await db.delete(table).where(eq(table.id, existing.id));
+    throw new TokenError('token_expired', 'Refresh token has expired');
+  }
+
+  // Delete old token (one-time use)
+  await db.delete(table).where(eq(table.id, existing.id));
+
+  // Read familyId from data JSONB
+  const existingFamilyId = (existing.data as Record<string, unknown>)?.familyId as string | undefined;
+
+  // Issue new token in the same family
+  const result = await createRefreshToken(
+    db,
+    table,
+    existing.userId,
+    existingFamilyId,
+  );
+
+  return {
+    userId: existing.userId,
+    token: result.token,
+    familyId: result.familyId,
+  };
+}
+
+/**
+ * Revoke all refresh tokens for a user.
+ * Use on: logout everywhere, password change, account compromise.
+ */
+export async function revokeAllRefreshTokens(
+  db: any,
+  table: any,
+  userId: string,
+): Promise<void> {
+  await db.delete(table).where(
+    and(
+      eq(table.userId, userId),
+      eq(table.domain, 'auth'),
+      eq(table.type, 'refresh'),
+    ),
+  );
+}
+
+/**
+ * Revoke all refresh tokens in a specific family.
+ * Use when token reuse is detected (potential theft).
+ */
+export async function revokeTokenFamily(
+  db: any,
+  table: any,
+  familyId: string,
+): Promise<void> {
+  await db.delete(table).where(
+    and(
+      eq(table.domain, 'auth'),
+      eq(table.type, 'refresh'),
+      sql`${table.data}->>'familyId' = ${familyId}`,
+    ),
+  );
+}
+
+/**
+ * Delete all expired refresh sessions. Call periodically (e.g., daily cron).
+ */
+export async function cleanupExpiredTokens(
+  db: any,
+  table: any,
+): Promise<void> {
+  await db.delete(table).where(
+    and(
+      eq(table.domain, 'auth'),
+      eq(table.type, 'refresh'),
+      lt(table.expiresAt, new Date()),
+    ),
+  );
+}
+
+/**
+ * Error class for token operations.
+ */
+export class TokenError extends Error {
+  constructor(
+    public readonly code: 'invalid_token' | 'token_expired',
+    message: string,
+  ) {
+    super(message);
+    this.name = 'TokenError';
+  }
+}

package/src/response.ts

@@ -0,0 +1,50 @@
+/**
+ * Auth response builders that optionally set HttpOnly cookies.
+ *
+ * When `cookieOpts` is truthy, Set-Cookie headers are appended to the response
+ * for both the access token and refresh token. Error responses are never decorated.
+ */
+
+import { serializeAuthCookies, clearAuthCookies, type CookieOptions } from './cookies';
+
+export type CookieConfig = CookieOptions | boolean;
+
+/**
+ * Build a JSON auth response, optionally decorated with Set-Cookie headers.
+ *
+ * @param body - Must contain `token` and `refreshToken` fields
+ * @param status - HTTP status code
+ * @param cookieConfig - When truthy, appends Set-Cookie headers. `true` uses defaults.
+ */
+export function authResponse(
+  body: { token: string; refreshToken: string; [key: string]: unknown },
+  status: number,
+  cookieConfig?: CookieConfig,
+): Response {
+  const headers = new Headers({ 'Content-Type': 'application/json' });
+
+  if (cookieConfig) {
+    const opts = cookieConfig === true ? undefined : cookieConfig;
+    for (const cookie of serializeAuthCookies(body.token, body.refreshToken, opts)) {
+      headers.append('Set-Cookie', cookie);
+    }
+  }
+
+  return new Response(JSON.stringify(body), { status, headers });
+}
+
+/**
+ * Build a signout response that clears auth cookies.
+ */
+export function signoutResponse(cookieConfig?: CookieConfig): Response {
+  const headers = new Headers({ 'Content-Type': 'application/json' });
+
+  if (cookieConfig) {
+    const opts = cookieConfig === true ? undefined : cookieConfig;
+    for (const cookie of clearAuthCookies(opts)) {
+      headers.append('Set-Cookie', cookie);
+    }
+  }
+
+  return new Response(JSON.stringify({ success: true }), { status: 200, headers });
+}

package/src/schema.ts

@@ -0,0 +1,224 @@
+/**
+ * Auth schema — everyschema auth.* tables
+ *
+ * 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
+ *
+ * @see everyschema — canonical schema definitions
+ */
+
+import {
+  pgSchema,
+  text,
+  timestamp,
+  uuid,
+  integer,
+  index,
+  uniqueIndex,
+  jsonb,
+} from 'drizzle-orm/pg-core';
+import { sql } from 'drizzle-orm';
+
+const authSchema = pgSchema('auth');
+export { authSchema };
+
+// =============================================================================
+// SESSIONS (unified STI)
+// =============================================================================
+
+/**
+ * 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 }
+ *
+ * domain='agent' data: { agentType, scopes, context, currentTask,
+ *   lockedResources, transport, toolCallCount, errorCount }
+ *
+ * domain='ws' data: { connectionId, channels }
+ */
+export const sessions = authSchema.table(
+  'sessions',
+  {
+    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
+    createdAt: timestamp('created_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),
+  })
+);
+
+// =============================================================================
+// IDENTITIES (WHO can be granted permissions)
+// =============================================================================
+
+/**
+ * Abstraction layer between users and credentials. Separates WHO (identity)
+ * from HOW they prove it (credentials).
+ *
+ * type='user': linked to auth.users via userId
+ * type='external': email addresses, phone numbers, external services
+ */
+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'),
+
+    createdAt: timestamp('created_at', { withTimezone: true }).defaultNow().notNull(),
+  },
+  (table) => ({
+    typeIdx: index('identities_type_idx').on(table.type),
+    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)
+// =============================================================================
+
+/**
+ * Links to auth.identities, not directly to users.
+ *
+ * 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)
+ */
+export const credentials = authSchema.table(
+  'credentials',
+  {
+    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'),
+    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`),
+  })
+);
+
+// =============================================================================
+// DEVICES
+// =============================================================================
+
+/**
+ * Device attestation with trust scores and revocation.
+ *
+ * Maps from everystack security_devices:
+ *   keyId → keyId, publicKey → publicKey, counter → attestationCount,
+ *   attestedAt → registeredAt, lastAssertionAt → lastSeenAt
+ */
+export const devices = authSchema.table(
+  'devices',
+  {
+    id: uuid('id').primaryKey().defaultRandom(),
+    userId: uuid('user_id').notNull(),
+    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'),
+    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),
+    trustScore: integer('trust_score').notNull().default(100),
+    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) => ({
+    userIdx: index('devices_user_idx').on(table.userId),
+    deviceIdIdx: uniqueIndex('devices_device_id_idx').on(table.deviceId),
+    platformIdx: index('devices_platform_idx').on(table.platform),
+  })
+);