@devchitchat/chat 0.0.0

package/src/core/uploads.js

@@ -0,0 +1,107 @@
+/**
+ * Pure functions for upload validation.
+ * No I/O — trivially testable.
+ */
+
+// Magic byte signatures → MIME type
+const MAGIC = [
+  // Images
+  { bytes: [0xff, 0xd8, 0xff],                              mime: 'image/jpeg' },
+  { bytes: [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a], mime: 'image/png' },
+  { bytes: [0x00, 0x00, 0x01, 0x00],                         mime: 'image/x-icon' },
+  { bytes: [0x47, 0x49, 0x46, 0x38],                         mime: 'image/gif' },
+  { bytes: [0x52, 0x49, 0x46, 0x46],                         mime: 'image/webp', offset: 0, extra: { offset: 8, bytes: [0x57, 0x45, 0x42, 0x50] } },
+  // PDF
+  { bytes: [0x25, 0x50, 0x44, 0x46],                         mime: 'application/pdf' },
+  // ZIP (also docx, xlsx, etc. — we only allow plain zip)
+  { bytes: [0x50, 0x4b, 0x03, 0x04],                         mime: 'application/zip' },
+  { bytes: [0x50, 0x4b, 0x05, 0x06],                         mime: 'application/zip' },
+  // GZip
+  { bytes: [0x1f, 0x8b],                                     mime: 'application/gzip' },
+  // MP3
+  { bytes: [0x49, 0x44, 0x33],                               mime: 'audio/mpeg' },
+  { bytes: [0xff, 0xfb],                                     mime: 'audio/mpeg' },
+  { bytes: [0xff, 0xf3],                                     mime: 'audio/mpeg' },
+  { bytes: [0xff, 0xf2],                                     mime: 'audio/mpeg' },
+  // OGG
+  { bytes: [0x4f, 0x67, 0x67, 0x53],                         mime: 'audio/ogg' },
+  // WAV
+  { bytes: [0x52, 0x49, 0x46, 0x46],                         mime: 'audio/wav', extra: { offset: 8, bytes: [0x57, 0x41, 0x56, 0x45] } },
+  // MP4
+  { bytes: [0x66, 0x74, 0x79, 0x70], offset: 4,              mime: 'video/mp4' },
+  // WebM
+  { bytes: [0x1a, 0x45, 0xdf, 0xa3],                         mime: 'video/webm' },
+]
+
+// Plain-text extensions we serve as text/plain (no magic check needed)
+const TEXT_EXTENSIONS = new Set([
+  'txt', 'md', 'markdown', 'json', 'csv', 'js', 'ts', 'jsx', 'tsx',
+  'html', 'css', 'yaml', 'yml', 'toml', 'sh', 'bash', 'py', 'rb',
+  'go', 'rs', 'java', 'c', 'cpp', 'h', 'xml', 'svg',
+])
+
+// MIME types that browsers / OSes can execute — force Content-Disposition: attachment
+const FORCED_DOWNLOAD_MIMES = new Set([
+  'application/javascript',
+  'application/x-sh',
+  'application/octet-stream',
+  'application/x-executable',
+  'application/x-msdownload',
+  'application/x-msdos-program',
+  'text/html',
+  'application/xhtml+xml',
+])
+
+/**
+ * Detect MIME type from the first bytes of a file buffer.
+ * Returns the MIME string on success, or throws an Error with code 'UNSUPPORTED_TYPE'.
+ *
+ * @param {Uint8Array|Buffer} buf   First N bytes (at least 16 recommended)
+ * @param {string} filename         Original filename (used for text fallback)
+ * @returns {string}                Detected MIME type
+ */
+export function validateMimeType(buf, filename = '') {
+  // 1. Try text extension fallback first so .md, .json, etc. always work
+  const ext = filename.split('.').pop()?.toLowerCase() ?? ''
+  if (TEXT_EXTENSIONS.has(ext)) {
+    // Quick sanity: must not start with binary-looking bytes
+    const isBinary = Array.from(buf.slice(0, 8)).some(b => b < 0x09 && b !== 0x00)
+    if (!isBinary) return 'text/plain'
+  }
+
+  // 2. Try SVG (XML text)
+  if (ext === 'svg') {
+    return 'image/svg+xml'
+  }
+
+  // 3. Magic byte scan
+  for (const sig of MAGIC) {
+    const start = sig.offset ?? 0
+    const slice = buf.slice(start, start + sig.bytes.length)
+    const match = sig.bytes.every((b, i) => slice[i] === b)
+    if (!match) continue
+
+    // Optional extra check (e.g., WEBP vs WAV both start with RIFF)
+    if (sig.extra) {
+      const extra = buf.slice(sig.extra.offset, sig.extra.offset + sig.extra.bytes.length)
+      if (!sig.extra.bytes.every((b, i) => extra[i] === b)) continue
+    }
+
+    return sig.mime
+  }
+
+  const err = new Error(`Unsupported file type: ${filename}`)
+  err.code = 'UNSUPPORTED_TYPE'
+  throw err
+}
+
+/**
+ * Returns true if the MIME type should be served with Content-Disposition: attachment
+ * to prevent execution in the browser.
+ *
+ * @param {string} mime
+ * @returns {boolean}
+ */
+export function isForcedDownload(mime) {
+  return FORCED_DOWNLOAD_MIMES.has(mime)
+}

package/src/db/initDb.js

@@ -0,0 +1,225 @@
+// Pure DDL — safe to call before migrations. No writes.
+export const createSchema = (db) => {
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS users (
+      user_id TEXT PRIMARY KEY,
+      handle TEXT NOT NULL UNIQUE,
+      display_name TEXT NOT NULL,
+      roles_json TEXT NOT NULL,
+      password_hash TEXT,
+      created_at INTEGER NOT NULL
+    );
+
+    CREATE TABLE IF NOT EXISTS sessions (
+      session_id TEXT PRIMARY KEY,
+      user_id TEXT NOT NULL,
+      token_hash TEXT NOT NULL,
+      created_at INTEGER NOT NULL,
+      expires_at INTEGER NOT NULL,
+      revoked_at INTEGER,
+      last_seen_at INTEGER,
+      FOREIGN KEY(user_id) REFERENCES users(user_id)
+    );
+
+    CREATE TABLE IF NOT EXISTS invites (
+      invite_id TEXT PRIMARY KEY,
+      token_hash TEXT NOT NULL,
+      created_by_user_id TEXT NOT NULL,
+      created_at INTEGER NOT NULL,
+      expires_at INTEGER NOT NULL,
+      max_uses INTEGER NOT NULL,
+      uses INTEGER NOT NULL,
+      redeemed_by_user_id TEXT,
+      note TEXT,
+      initial_roles_json TEXT,
+      FOREIGN KEY(created_by_user_id) REFERENCES users(user_id)
+    );
+
+    CREATE TABLE IF NOT EXISTS hubs (
+      hub_id TEXT PRIMARY KEY,
+      name TEXT NOT NULL,
+      description TEXT,
+      visibility TEXT NOT NULL,
+      created_by_user_id TEXT NOT NULL,
+      created_at INTEGER NOT NULL,
+      deleted_at INTEGER,
+      FOREIGN KEY(created_by_user_id) REFERENCES users(user_id)
+    );
+
+    CREATE TABLE IF NOT EXISTS hub_members (
+      hub_id TEXT NOT NULL,
+      user_id TEXT NOT NULL,
+      joined_at INTEGER NOT NULL,
+      left_at INTEGER,
+      PRIMARY KEY (hub_id, user_id),
+      FOREIGN KEY(hub_id) REFERENCES hubs(hub_id),
+      FOREIGN KEY(user_id) REFERENCES users(user_id)
+    );
+
+    CREATE TABLE IF NOT EXISTS channels (
+      channel_id TEXT PRIMARY KEY,
+      hub_id TEXT,
+      kind TEXT NOT NULL,
+      name TEXT NOT NULL,
+      topic TEXT,
+      visibility TEXT NOT NULL,
+      sort_order INTEGER NOT NULL DEFAULT 0,
+      created_by_user_id TEXT NOT NULL,
+      created_at INTEGER NOT NULL,
+      deleted_at INTEGER,
+      FOREIGN KEY(created_by_user_id) REFERENCES users(user_id)
+    );
+
+    CREATE TABLE IF NOT EXISTS channel_members (
+      channel_id TEXT NOT NULL,
+      user_id TEXT NOT NULL,
+      role TEXT NOT NULL,
+      joined_at INTEGER NOT NULL,
+      left_at INTEGER,
+      banned_at INTEGER,
+      PRIMARY KEY (channel_id, user_id),
+      FOREIGN KEY(channel_id) REFERENCES channels(channel_id),
+      FOREIGN KEY(user_id) REFERENCES users(user_id)
+    );
+
+    CREATE TABLE IF NOT EXISTS events (
+      event_id INTEGER PRIMARY KEY AUTOINCREMENT,
+      ts INTEGER NOT NULL,
+      actor_user_id TEXT NOT NULL,
+      scope_kind TEXT NOT NULL,
+      scope_id TEXT NOT NULL,
+      type TEXT NOT NULL,
+      body_json TEXT NOT NULL,
+      trace TEXT
+    );
+
+    CREATE TABLE IF NOT EXISTS messages (
+      msg_id TEXT PRIMARY KEY,
+      channel_id TEXT NOT NULL,
+      seq INTEGER NOT NULL,
+      user_id TEXT NOT NULL,
+      ts INTEGER NOT NULL,
+      text TEXT NOT NULL,
+      client_msg_id TEXT,
+      deleted_at INTEGER,
+      priority TEXT NOT NULL DEFAULT 'normal',
+      attachments_json TEXT,
+      edited_at INTEGER,
+      FOREIGN KEY(channel_id) REFERENCES channels(channel_id),
+      FOREIGN KEY(user_id) REFERENCES users(user_id)
+    );
+
+    CREATE TABLE IF NOT EXISTS uploads (
+      upload_id        TEXT    PRIMARY KEY,
+      uploader_user_id TEXT    NOT NULL REFERENCES users(user_id),
+      channel_id       TEXT    NOT NULL REFERENCES channels(channel_id),
+      msg_id           TEXT    REFERENCES messages(msg_id),
+      original_name    TEXT    NOT NULL,
+      stored_name      TEXT    NOT NULL,
+      mime_type        TEXT    NOT NULL,
+      size_bytes       INTEGER NOT NULL,
+      created_at       INTEGER NOT NULL
+    );
+
+    CREATE TABLE IF NOT EXISTS deliveries (
+      delivery_id TEXT PRIMARY KEY,
+      user_id TEXT NOT NULL,
+      channel_id TEXT NOT NULL,
+      after_seq INTEGER NOT NULL,
+      mention_seq INTEGER NOT NULL DEFAULT 0,
+      mention_priority TEXT NOT NULL DEFAULT 'normal',
+      last_delivered_at INTEGER,
+      status TEXT NOT NULL,
+      FOREIGN KEY(user_id) REFERENCES users(user_id),
+      FOREIGN KEY(channel_id) REFERENCES channels(channel_id)
+    );
+
+    CREATE TABLE IF NOT EXISTS user_settings (
+      user_id      TEXT    NOT NULL PRIMARY KEY REFERENCES users(user_id) ON DELETE CASCADE,
+      settings_json TEXT   NOT NULL DEFAULT '{}',
+      updated_at   INTEGER NOT NULL DEFAULT 0
+    );
+
+    CREATE TABLE IF NOT EXISTS calls (
+      call_id            TEXT    NOT NULL PRIMARY KEY,
+      channel_id         TEXT    NOT NULL REFERENCES channels(channel_id),
+      created_by_user_id TEXT    NOT NULL REFERENCES users(user_id),
+      topology           TEXT    NOT NULL DEFAULT 'mesh',
+      started_at         INTEGER NOT NULL DEFAULT (unixepoch()),
+      ended_at           INTEGER
+    );
+
+    CREATE TABLE IF NOT EXISTS call_participants (
+      id        INTEGER PRIMARY KEY AUTOINCREMENT,
+      call_id   TEXT    NOT NULL REFERENCES calls(call_id),
+      user_id   TEXT    NOT NULL REFERENCES users(user_id),
+      peer_id   TEXT    NOT NULL,
+      joined_at INTEGER NOT NULL DEFAULT (unixepoch()),
+      left_at   INTEGER
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_calls_channel_active
+      ON calls (channel_id) WHERE ended_at IS NULL;
+  `)
+
+  // Add sort_order to existing databases that pre-date this column
+  try { db.exec(`ALTER TABLE channels ADD COLUMN sort_order INTEGER NOT NULL DEFAULT 0`) } catch { /* already exists */ }
+  try { db.exec(`ALTER TABLE hubs ADD COLUMN sort_order INTEGER NOT NULL DEFAULT 0`) } catch { /* already exists */ }
+  // Add mention_seq to existing deliveries tables that pre-date this column
+  try { db.exec(`ALTER TABLE deliveries ADD COLUMN mention_seq INTEGER NOT NULL DEFAULT 0`) } catch { /* already exists */ }
+  // Add mention_priority to existing deliveries tables
+  try { db.exec(`ALTER TABLE deliveries ADD COLUMN mention_priority TEXT NOT NULL DEFAULT 'normal'`) } catch { /* already exists */ }
+  // Add priority + attachments_json to existing messages tables
+  try { db.exec(`ALTER TABLE messages ADD COLUMN priority TEXT NOT NULL DEFAULT 'normal'`) } catch { /* already exists */ }
+  try { db.exec(`ALTER TABLE messages ADD COLUMN attachments_json TEXT`) } catch { /* already exists */ }
+  try { db.exec(`ALTER TABLE messages ADD COLUMN edited_at INTEGER`) } catch { /* already exists */ }
+
+  // Bot tokens — added after initial schema
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS bot_tokens (
+      token_id     TEXT PRIMARY KEY,
+      user_id      TEXT NOT NULL,
+      token_hash   TEXT NOT NULL UNIQUE,
+      label        TEXT,
+      created_at   INTEGER NOT NULL,
+      expires_at   INTEGER,
+      last_used_at INTEGER,
+      revoked_at   INTEGER,
+      FOREIGN KEY(user_id) REFERENCES users(user_id)
+    );
+  `)
+  // Add expires_at to existing bot_tokens tables that predate this column
+  try { db.exec('ALTER TABLE bot_tokens ADD COLUMN expires_at INTEGER') } catch { /* already exists */ }
+
+  try {
+    db.exec(`
+      CREATE VIRTUAL TABLE IF NOT EXISTS fts_messages USING fts5(
+        text,
+        channel_id UNINDEXED,
+        msg_id UNINDEXED,
+        seq UNINDEXED,
+        user_id UNINDEXED,
+        ts UNINDEXED
+      );
+    `)
+  } catch {
+    db.exec(`
+      CREATE TABLE IF NOT EXISTS fts_messages (
+        text TEXT NOT NULL,
+        channel_id TEXT NOT NULL,
+        msg_id TEXT NOT NULL,
+        seq INTEGER NOT NULL,
+        user_id TEXT NOT NULL,
+        ts INTEGER NOT NULL
+      );
+    `)
+  }
+}
+
+export const initDb = (db) => {
+  createSchema(db)
+
+  // Close any calls left open by a previous crash or unclean shutdown.
+  // Live call state is in-memory; on restart there are no active peers.
+  db.exec(`UPDATE calls SET ended_at = unixepoch() WHERE ended_at IS NULL`)
+}

package/src/db/openDb.js

@@ -0,0 +1,18 @@
+import { Database } from 'bun:sqlite'
+import { mkdirSync, existsSync } from 'node:fs'
+import { dirname } from 'node:path'
+
+const ensureDir = (filePath) => {
+  const dir = dirname(filePath)
+  if (dir && dir !== '.' && !existsSync(dir)) {
+    mkdirSync(dir, { recursive: true })
+  }
+}
+
+export const openDatabase = (filePath) => {
+  ensureDir(filePath)
+  const db = new Database(filePath)
+  db.exec('PRAGMA journal_mode = WAL')
+  db.exec('PRAGMA foreign_keys = ON')
+  return db
+}

package/src/db/runMigrations.js

@@ -0,0 +1,45 @@
+import { readdirSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const MIGRATE_DIR = join(__dirname, '../../migrate')
+
+/**
+ * Apply all pending migrations to the given database.
+ * Already-applied migrations are skipped. Safe to call on every boot.
+ */
+export async function runMigrations(db, { logger } = {}) {
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS _migrations (
+      filename   TEXT    PRIMARY KEY,
+      applied_at INTEGER NOT NULL
+    )
+  `)
+
+  const files = readdirSync(MIGRATE_DIR).filter(f => f.endsWith('.js')).sort()
+  const applied = new Set(
+    db.prepare('SELECT filename FROM _migrations').all().map(r => r.filename)
+  )
+  const pending = files.filter(f => !applied.has(f))
+
+  if (pending.length === 0) return
+
+  const insertApplied = db.prepare(
+    'INSERT INTO _migrations (filename, applied_at) VALUES (?, ?)'
+  )
+
+  for (const file of pending) {
+    const { run } = await import(join(MIGRATE_DIR, file))
+    db.exec('PRAGMA foreign_keys = OFF')
+    try {
+      db.transaction(() => {
+        run(db)
+        insertApplied.run(file, Date.now())
+      })()
+    } finally {
+      db.exec('PRAGMA foreign_keys = ON')
+    }
+    logger?.info('migration.applied', { file })
+  }
+}

package/src/db/transaction.js

@@ -0,0 +1,11 @@
+export const runTransaction = (db, fn) => {
+  db.exec('BEGIN')
+  try {
+    const result = fn()
+    db.exec('COMMIT')
+    return result
+  } catch (error) {
+    db.exec('ROLLBACK')
+    throw error
+  }
+}

package/src/ports/IFileStore.js

@@ -0,0 +1,34 @@
+/**
+ * IFileStore — port for file persistence.
+ *
+ * Implemented by:
+ *   LocalFileStore    writes to data/uploads/{uploadId}/{storedName}
+ *   InMemoryFileStore stores buffers in a Map (for tests)
+ *
+ * @interface
+ */
+export class IFileStore {
+  /**
+   * Persist a file stream.
+   * @param {{ uploadId: string, storedName: string, stream: ReadableStream }} params
+   * @returns {Promise<void>}
+   */
+  // eslint-disable-next-line no-unused-vars
+  async write({ uploadId, storedName, stream }) { throw new Error('Not implemented') }
+
+  /**
+   * Open a file for reading.
+   * @param {{ uploadId: string, storedName: string }} params
+   * @returns {Promise<ReadableStream>}
+   */
+  // eslint-disable-next-line no-unused-vars
+  async read({ uploadId, storedName }) { throw new Error('Not implemented') }
+
+  /**
+   * Delete a stored file.
+   * @param {{ uploadId: string, storedName: string }} params
+   * @returns {Promise<void>}
+   */
+  // eslint-disable-next-line no-unused-vars
+  async delete({ uploadId, storedName }) { throw new Error('Not implemented') }
+}

package/src/services/AuthService.js

@@ -0,0 +1,208 @@
+import { newId } from '../util/ids.js'
+import { randomToken, hashToken, hashPassword, verifyPassword } from '../util/crypto.js'
+import { ServiceError } from '../util/errors.js'
+
+const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000
+const DEFAULT_SESSION_TTL_MS = 30 * 24 * 60 * 60 * 1000
+
+export class AuthService {
+  constructor({ authRepo, nowFn = () => Date.now(), sessionTtlMs = DEFAULT_SESSION_TTL_MS, bootstrapToken = null }) {
+    this.authRepo = authRepo
+    this.nowFn = nowFn
+    this.sessionTtlMs = sessionTtlMs
+    this.bootstrapToken = bootstrapToken
+  }
+
+  createInvite({ createdByUserId, ttlMs = DEFAULT_TTL_MS, maxUses = 1, note = null, roles = ['user'] }) {
+    this.requireAdmin(createdByUserId)
+    if (!Array.isArray(roles) || roles.length === 0) throw new ServiceError('BAD_REQUEST', 'roles must be a non-empty array')
+    const inviteToken = randomToken()
+    const inviteId = newId('invite')
+    const now = this.nowFn()
+    const expiresAt = now + ttlMs
+    this.authRepo.insertInvite({ inviteId, tokenHash: hashToken(inviteToken), createdByUserId, now, expiresAt, maxUses, note, initialRolesJson: JSON.stringify(roles) })
+    return { inviteToken, inviteId, expiresAt, maxUses, roles }
+  }
+
+  listInvites({ requestingUserId }) {
+    this.requireAdmin(requestingUserId)
+    return this.authRepo.listInvites()
+  }
+
+  revokeInvite({ inviteId, requestingUserId }) {
+    this.requireAdmin(requestingUserId)
+    this.authRepo.deleteInvite({ inviteId })
+  }
+
+  async redeemInvite({ inviteToken, profile, password }) {
+    const invite = this.authRepo.findInviteByTokenHash({ tokenHash: hashToken(inviteToken) })
+    const now = this.nowFn()
+    if (!invite) {
+      const bootstrap = await this.tryBootstrap({ inviteToken, profile, now, password })
+      if (bootstrap) return bootstrap
+      throw new ServiceError('AUTH_FAILED', 'Invite token is invalid')
+    }
+    if (invite.expires_at <= now) throw new ServiceError('AUTH_FAILED', 'Invite token has expired')
+    if (invite.uses >= invite.max_uses) throw new ServiceError('AUTH_FAILED', 'Invite token has been used')
+    const handle = profile?.handle?.trim()
+    const displayName = profile?.display_name?.trim() || handle
+    if (!handle) throw new ServiceError('BAD_REQUEST', 'Handle is required')
+    if (!password) throw new ServiceError('BAD_REQUEST', 'Password is required')
+    if (this.authRepo.isHandleTaken({ handle })) throw new ServiceError('CONFLICT', 'Handle already taken')
+    const userId = newId('u')
+    const roles = invite.initial_roles_json ? JSON.parse(invite.initial_roles_json) : this.getDefaultRoles()
+    const passwordHash = await hashPassword(password)
+    const { sessionId, sessionToken, expiresAt } = this._makeSessionParts(now)
+    this.authRepo.registerUser({
+      inviteId: invite.invite_id,
+      userId, handle, displayName,
+      rolesJson: JSON.stringify(roles),
+      passwordHash, now,
+      sessionId, sessionTokenHash: hashToken(sessionToken), sessionExpiresAt: expiresAt
+    })
+    return {
+      sessionToken,
+      user: { user_id: userId, handle, display_name: displayName, roles }
+    }
+  }
+
+  async tryBootstrap({ inviteToken, profile, now, password }) {
+    if (!this.bootstrapToken || inviteToken !== this.bootstrapToken) return null
+    if (this.authRepo.getUserCount() > 0) return null
+    const handle = profile?.handle?.trim()
+    const displayName = profile?.display_name?.trim() || handle
+    if (!handle) throw new ServiceError('BAD_REQUEST', 'Handle is required')
+    if (!password) throw new ServiceError('BAD_REQUEST', 'Password is required')
+    if (this.authRepo.isHandleTaken({ handle })) throw new ServiceError('CONFLICT', 'Handle already taken')
+    const userId = newId('u')
+    const roles = ['admin']
+    const passwordHash = await hashPassword(password)
+    const { sessionId, sessionToken, expiresAt } = this._makeSessionParts(now)
+    this.authRepo.registerBootstrapUser({
+      userId, handle, displayName,
+      rolesJson: JSON.stringify(roles),
+      passwordHash, now,
+      sessionId, sessionTokenHash: hashToken(sessionToken), sessionExpiresAt: expiresAt
+    })
+    this.bootstrapToken = null
+    return {
+      sessionToken,
+      user: { user_id: userId, handle, display_name: displayName, roles }
+    }
+  }
+
+  async signInWithPassword({ handle, password }) {
+    if (!handle || !password) throw new ServiceError('BAD_REQUEST', 'Handle and password required')
+    const row = this.authRepo.findUserByHandle({ handle })
+    if (!row || !row.password_hash) throw new ServiceError('AUTH_FAILED', 'Invalid handle or password')
+    const isValid = await verifyPassword(password, row.password_hash)
+    if (!isValid) throw new ServiceError('AUTH_FAILED', 'Invalid handle or password')
+    const now = this.nowFn()
+    const { sessionId, sessionToken, expiresAt } = this._makeSessionParts(now)
+    this.authRepo.insertSession({ sessionId, userId: row.user_id, tokenHash: hashToken(sessionToken), now, expiresAt })
+    return {
+      sessionToken,
+      user: { user_id: row.user_id, handle: row.handle, display_name: row.display_name, roles: JSON.parse(row.roles_json) }
+    }
+  }
+
+  createSession(userId) {
+    const now = this.nowFn()
+    const { sessionId, sessionToken, expiresAt } = this._makeSessionParts(now)
+    this.authRepo.insertSession({ sessionId, userId, tokenHash: hashToken(sessionToken), now, expiresAt })
+    return { sessionId, sessionToken, expiresAt }
+  }
+
+  validateSession(sessionToken) {
+    if (!sessionToken) return null
+    const now = this.nowFn()
+    const row = this.authRepo.findSessionWithUser({ tokenHash: hashToken(sessionToken) })
+    if (!row || row.revoked_at || row.expires_at <= now) return null
+    const lastSeenAt = row.last_seen_at ?? null
+    this.authRepo.touchSession({ sessionId: row.session_id, now })
+    return {
+      session_id: row.session_id,
+      last_seen_at: lastSeenAt,
+      user: { user_id: row.user_id, handle: row.handle, display_name: row.display_name, roles: JSON.parse(row.roles_json) }
+    }
+  }
+
+  revokeSession(sessionId) {
+    this.authRepo.revokeSession({ sessionId, now: this.nowFn() })
+  }
+
+  // ── User management (admin only) ───────────────────────────────────────────
+
+  listUsers({ requestingUserId }) {
+    this.requireAdmin(requestingUserId)
+    return this.authRepo.listUsers().map(row => ({
+      user_id:      row.user_id,
+      handle:       row.handle,
+      display_name: row.display_name,
+      roles:        JSON.parse(row.roles_json),
+      created_at:   row.created_at,
+    }))
+  }
+
+  setUserRoles({ targetUserId, roles, requestingUserId }) {
+    this.requireAdmin(requestingUserId)
+    if (!Array.isArray(roles)) throw new ServiceError('BAD_REQUEST', 'roles must be an array')
+    this.authRepo.updateUserRoles({ userId: targetUserId, rolesJson: JSON.stringify(roles) })
+  }
+
+  async adminSetPassword({ targetUserId, newPassword, requestingUserId }) {
+    this.requireAdmin(requestingUserId)
+    if (!newPassword || newPassword.length < 8) throw new ServiceError('BAD_REQUEST', 'Password must be at least 8 characters')
+    const passwordHash = await hashPassword(newPassword)
+    this.authRepo.updateUserPassword({ userId: targetUserId, passwordHash })
+    this.authRepo.revokeAllUserSessions({ userId: targetUserId, now: this.nowFn() })
+  }
+
+  adminUpdateDisplayName({ targetUserId, displayName, requestingUserId }) {
+    this.requireAdmin(requestingUserId)
+    const name = displayName?.trim()
+    if (!name) throw new ServiceError('BAD_REQUEST', 'Display name is required')
+    this.authRepo.updateUserDisplayName({ userId: targetUserId, displayName: name })
+  }
+
+  requireAdmin(userId) {
+    const user = this.getUser(userId)
+    if (!user || !user.roles.includes('admin')) throw new ServiceError('FORBIDDEN', 'Admin role required')
+  }
+
+  getUser(userId) {
+    const row = this.authRepo.findUserById({ userId })
+    if (!row) return null
+    return { user_id: row.user_id, handle: row.handle, display_name: row.display_name, roles: JSON.parse(row.roles_json) }
+  }
+
+  findInvite(inviteToken) {
+    return this.authRepo.findInviteByTokenHash({ tokenHash: hashToken(inviteToken) })
+  }
+
+  listUsersBasic() {
+    return this.authRepo.listUsers().map(row => ({
+      user_id:      row.user_id,
+      handle:       row.handle,
+      display_name: row.display_name,
+      roles:        JSON.parse(row.roles_json),
+    }))
+  }
+
+  getDefaultRoles() { return ['user'] }
+
+  getUserCount() {
+    return this.authRepo.getUserCount()
+  }
+
+  isHandleTaken(handle) {
+    return this.authRepo.isHandleTaken({ handle })
+  }
+
+  _makeSessionParts(now) {
+    const sessionId = newId('s')
+    const sessionToken = randomToken(32)
+    const expiresAt = now + this.sessionTtlMs
+    return { sessionId, sessionToken, expiresAt }
+  }
+}