@bbigbang/core 0.1.0

package/dist/services/agentWorkspaceService.js

@@ -0,0 +1,70 @@
+export class AgentWorkspaceServiceError extends Error {
+    statusCode;
+    constructor(statusCode, message) {
+        super(message);
+        this.statusCode = statusCode;
+    }
+}
+export class AgentWorkspaceService {
+    getAgentById;
+    broker;
+    constructor(params) {
+        this.getAgentById = params.getAgentById;
+        this.broker = params.broker;
+    }
+    async listWorkspace(agentId, relativePath, options = {}) {
+        const agent = this.getAgentById(agentId);
+        if (!agent)
+            throw new AgentWorkspaceServiceError(404, 'Agent not found.');
+        if (!agent.nodeId)
+            throw new AgentWorkspaceServiceError(409, 'Agent is not assigned to a remote node.');
+        if (!agent.workspacePath)
+            throw new AgentWorkspaceServiceError(409, 'Agent has no workspace configured.');
+        try {
+            return await this.broker.listDirectory(agent.nodeId, agent.workspacePath, relativePath, options);
+        }
+        catch (error) {
+            throw mapAgentWorkspaceError(error);
+        }
+    }
+    async readWorkspaceFile(agentId, relativePath) {
+        const agent = this.getAgentById(agentId);
+        if (!agent)
+            throw new AgentWorkspaceServiceError(404, 'Agent not found.');
+        if (!agent.nodeId)
+            throw new AgentWorkspaceServiceError(409, 'Agent is not assigned to a remote node.');
+        if (!agent.workspacePath)
+            throw new AgentWorkspaceServiceError(409, 'Agent has no workspace configured.');
+        try {
+            return await this.broker.readFile(agent.nodeId, agent.workspacePath, relativePath);
+        }
+        catch (error) {
+            throw mapAgentWorkspaceError(error);
+        }
+    }
+}
+export function mapAgentWorkspaceError(error) {
+    const message = String(error?.message ?? error);
+    if (message === 'Agent node is offline.' || message.startsWith('Agent node disconnected:')) {
+        return new AgentWorkspaceServiceError(409, message);
+    }
+    if (message === 'Workspace request timed out.' || message === 'Workspace stream request timed out.') {
+        return new AgentWorkspaceServiceError(504, message);
+    }
+    if (message.startsWith('not_found:')) {
+        return new AgentWorkspaceServiceError(404, message.slice('not_found:'.length));
+    }
+    if (message.startsWith('path_outside_workspace:')) {
+        return new AgentWorkspaceServiceError(400, message.slice('path_outside_workspace:'.length));
+    }
+    if (message.startsWith('binary_file:')) {
+        return new AgentWorkspaceServiceError(415, message.slice('binary_file:'.length));
+    }
+    if (message.startsWith('file_too_large:')) {
+        return new AgentWorkspaceServiceError(413, message.slice('file_too_large:'.length));
+    }
+    if (message.startsWith('not_directory:') || message.startsWith('not_file:')) {
+        return new AgentWorkspaceServiceError(400, message.slice(message.indexOf(':') + 1));
+    }
+    return new AgentWorkspaceServiceError(500, message);
+}

package/dist/services/appVersion.js

@@ -0,0 +1,14 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+export function readPackageVersion(packageRootFromDist) {
+    const currentDir = path.dirname(fileURLToPath(import.meta.url));
+    const packageJsonPath = path.resolve(currentDir, packageRootFromDist, 'package.json');
+    try {
+        const parsed = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+        return typeof parsed.version === 'string' && parsed.version.trim() ? parsed.version.trim() : '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}

package/dist/services/auth.js

@@ -0,0 +1,586 @@
+import { createHash, randomUUID, randomBytes } from 'node:crypto';
+import { isIP } from 'node:net';
+// Use bcryptjs for password hashing (pure JS, no native dependencies)
+import bcrypt from 'bcryptjs';
+const SALT_ROUNDS = 10;
+const SESSION_EXPIRY_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
+const INVITE_EXPIRY_MS = 24 * 60 * 60 * 1000; // 24 hours
+export const AUTH_RATE_LIMIT_MAX_FAILURES = 5;
+export const AUTH_RATE_LIMIT_WINDOW_MS = 15 * 60 * 1000;
+export const AUTH_RATE_LIMIT_LOCK_MS = 15 * 60 * 1000;
+export const AUTH_RATE_LIMIT_ERROR = 'Too many authentication attempts. Please try again later.';
+const AUTH_RATE_LIMIT_MAX_SUBJECT_LENGTH = 256;
+function mapPublicUserRow(row) {
+    return {
+        id: row.id,
+        username: row.username,
+        isAdmin: row.is_admin === 1,
+        avatarUrl: row.avatar_url?.trim() || null,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+    };
+}
+function mapUserRow(row) {
+    return {
+        ...mapPublicUserRow(row),
+        securityCodeEnabled: Boolean(row.security_code_hash?.trim()),
+    };
+}
+function normalizeNullableText(value) {
+    const trimmed = value?.trim();
+    return trimmed ? trimmed.slice(0, 255) : null;
+}
+function maskSessionIp(value) {
+    const normalized = normalizeNullableText(value);
+    if (!normalized)
+        return null;
+    const ip = normalized.split('%', 1)[0];
+    const embeddedIpv4 = ip.match(/\b(\d{1,3}(?:\.\d{1,3}){3})\b/)?.[1];
+    const ipv4 = isIP(ip) === 4 ? ip : embeddedIpv4 && isIP(embeddedIpv4) === 4 ? embeddedIpv4 : null;
+    if (ipv4) {
+        const parts = ipv4.split('.');
+        return `${parts[0]}.${parts[1]}.${parts[2]}.0/24`;
+    }
+    if (isIP(ip) === 6) {
+        const [left, right = ''] = ip.toLowerCase().split('::');
+        const leftParts = left ? left.split(':').filter(Boolean) : [];
+        const rightParts = right ? right.split(':').filter(Boolean) : [];
+        const missing = Math.max(0, 8 - leftParts.length - rightParts.length);
+        const parts = [...leftParts, ...Array(missing).fill('0'), ...rightParts].slice(0, 8);
+        const prefix = parts.slice(0, 3).map((part) => (parseInt(part || '0', 16) || 0).toString(16));
+        return `${prefix.join(':')}::/48`;
+    }
+    return 'Unknown';
+}
+function parseSessionClientInfo(info = {}) {
+    const userAgent = info.userAgent ?? '';
+    const ua = userAgent.toLowerCase();
+    let browser = 'Unknown';
+    if (ua.includes('edg/'))
+        browser = 'Edge';
+    else if (ua.includes('firefox/'))
+        browser = 'Firefox';
+    else if (ua.includes('crios/') || ua.includes('chrome/'))
+        browser = 'Chrome';
+    else if ((ua.includes('safari/') && ua.includes('mobile/')) || ua.includes('version/') && ua.includes('mobile/'))
+        browser = 'Mobile Safari';
+    else if (ua.includes('safari/'))
+        browser = 'Safari';
+    let os = 'Unknown';
+    if (ua.includes('windows nt'))
+        os = 'Windows';
+    else if (ua.includes('iphone') || ua.includes('ipad') || ua.includes('ipod'))
+        os = 'iOS';
+    else if (ua.includes('android'))
+        os = 'Android';
+    else if (ua.includes('mac os x') || ua.includes('macintosh'))
+        os = 'macOS';
+    else if (ua.includes('linux'))
+        os = 'Linux';
+    let deviceType = 'unknown';
+    if (ua.includes('bot') || ua.includes('spider') || ua.includes('crawler'))
+        deviceType = 'bot';
+    else if (ua.includes('ipad') || ua.includes('tablet'))
+        deviceType = 'tablet';
+    else if (ua.includes('mobile') || ua.includes('iphone') || (ua.includes('android') && !ua.includes('tablet')))
+        deviceType = 'mobile';
+    else if (ua.trim())
+        deviceType = 'desktop';
+    return {
+        ip: maskSessionIp(info.ip),
+        userAgentFamily: browser,
+        osFamily: os,
+        deviceType,
+    };
+}
+function userSessionMetadataColumnsExist(db) {
+    const rows = db.prepare("PRAGMA table_info('user_sessions')").all();
+    const names = new Set(rows.map((row) => row.name));
+    return (names.has('ip')
+        && names.has('user_agent_family')
+        && names.has('os_family')
+        && names.has('device_type')
+        && names.has('last_seen_ip')
+        && names.has('last_seen_user_agent_family')
+        && names.has('last_seen_os_family')
+        && names.has('last_seen_device_type'));
+}
+// Generate a secure random token
+function generateSecureToken() {
+    return randomBytes(32).toString('hex');
+}
+// Hash password using bcrypt
+export async function hashPassword(password) {
+    return bcrypt.hash(password, SALT_ROUNDS);
+}
+// Verify password
+export async function verifyPassword(password, hash) {
+    return bcrypt.compare(password, hash);
+}
+export function isValidSecurityCode(securityCode) {
+    return typeof securityCode === 'string' && /^\d{6}$/.test(securityCode);
+}
+export function hasSurroundingWhitespace(value) {
+    return value.trim() !== value;
+}
+export function getPasswordWhitespaceValidationError(password, label = 'Password') {
+    if (typeof password !== 'string' || !hasSurroundingWhitespace(password))
+        return null;
+    return `${label} cannot start or end with spaces`;
+}
+function getStoredPasswordValidationError(password) {
+    return getPasswordWhitespaceValidationError(password);
+}
+function normalizeRateLimitSubject(subject) {
+    const trimmed = subject.trim();
+    if (trimmed.length <= AUTH_RATE_LIMIT_MAX_SUBJECT_LENGTH)
+        return trimmed;
+    return `sha256:${createHash('sha256').update(trimmed).digest('hex')}`;
+}
+function normalizeRateLimitIp(ip) {
+    return ip.trim() || 'unknown';
+}
+export function pruneExpiredAuthRateLimits(db, now = Date.now()) {
+    const expiredWindowStartedBefore = now - AUTH_RATE_LIMIT_WINDOW_MS;
+    db.prepare(`DELETE FROM auth_rate_limits
+      WHERE locked_until IS NULL
+        AND window_started_at <= ?`).run(expiredWindowStartedBefore);
+    db.prepare(`DELETE FROM auth_rate_limits
+      WHERE locked_until IS NOT NULL
+        AND locked_until <= ?`).run(now);
+}
+export function checkAuthRateLimit(db, params) {
+    const now = params.now ?? Date.now();
+    const subject = normalizeRateLimitSubject(params.subject);
+    const ip = normalizeRateLimitIp(params.ip);
+    const row = db.prepare(`SELECT locked_until as lockedUntil
+       FROM auth_rate_limits
+      WHERE bucket = ? AND subject = ? AND ip = ?`).get(params.bucket, subject, ip);
+    if (!row?.lockedUntil || row.lockedUntil <= now) {
+        return { limited: false, retryAfterMs: 0, lockedUntil: null };
+    }
+    return {
+        limited: true,
+        retryAfterMs: row.lockedUntil - now,
+        lockedUntil: row.lockedUntil,
+    };
+}
+export function recordAuthFailure(db, params) {
+    const now = params.now ?? Date.now();
+    pruneExpiredAuthRateLimits(db, now);
+    const subject = normalizeRateLimitSubject(params.subject);
+    const ip = normalizeRateLimitIp(params.ip);
+    const row = db.prepare(`SELECT failure_count as failureCount,
+            window_started_at as windowStartedAt,
+            locked_until as lockedUntil
+       FROM auth_rate_limits
+      WHERE bucket = ? AND subject = ? AND ip = ?`).get(params.bucket, subject, ip);
+    if (row?.lockedUntil && row.lockedUntil > now) {
+        return {
+            limited: true,
+            retryAfterMs: row.lockedUntil - now,
+            lockedUntil: row.lockedUntil,
+        };
+    }
+    const withinWindow = row && now - row.windowStartedAt < AUTH_RATE_LIMIT_WINDOW_MS;
+    const failureCount = withinWindow ? row.failureCount + 1 : 1;
+    const windowStartedAt = withinWindow ? row.windowStartedAt : now;
+    const lockedUntil = failureCount >= AUTH_RATE_LIMIT_MAX_FAILURES
+        ? now + AUTH_RATE_LIMIT_LOCK_MS
+        : null;
+    db.prepare(`INSERT INTO auth_rate_limits (
+       bucket, subject, ip, failure_count, window_started_at, locked_until, last_failed_at
+     ) VALUES (?, ?, ?, ?, ?, ?, ?)
+     ON CONFLICT(bucket, subject, ip) DO UPDATE SET
+       failure_count = excluded.failure_count,
+       window_started_at = excluded.window_started_at,
+       locked_until = excluded.locked_until,
+       last_failed_at = excluded.last_failed_at`).run(params.bucket, subject, ip, failureCount, windowStartedAt, lockedUntil, now);
+    return { limited: false, retryAfterMs: 0, lockedUntil };
+}
+export function clearAuthFailures(db, params) {
+    const subject = normalizeRateLimitSubject(params.subject);
+    const ip = normalizeRateLimitIp(params.ip);
+    if (params.bucket) {
+        db.prepare('DELETE FROM auth_rate_limits WHERE bucket = ? AND subject = ? AND ip = ?').run(params.bucket, subject, ip);
+        return;
+    }
+    db.prepare('DELETE FROM auth_rate_limits WHERE subject = ? AND ip = ?').run(subject, ip);
+}
+export function getLoginAuthRateLimitIdentity(db, username) {
+    const row = db.prepare(`SELECT username, security_code_hash
+       FROM users
+      WHERE username = ?`).get(username);
+    if (!row)
+        return null;
+    return {
+        subject: row.username,
+        securityCodeEnabled: Boolean(row.security_code_hash?.trim()),
+    };
+}
+// Check if setup is complete (has at least one admin user)
+export function hasAdminUser(db) {
+    const row = db.prepare('SELECT COUNT(*) as count FROM users WHERE is_admin = 1').get();
+    return row.count > 0;
+}
+// Check if any users exist
+export function hasAnyUser(db) {
+    const row = db.prepare('SELECT COUNT(*) as count FROM users').get();
+    return row.count > 0;
+}
+// Create initial admin user during setup
+export async function createAdminUser(db, username, password, clientInfo) {
+    const passwordValidationError = getStoredPasswordValidationError(password);
+    if (passwordValidationError) {
+        return { success: false, error: passwordValidationError };
+    }
+    const now = Date.now();
+    const userId = randomUUID();
+    const passwordHash = await hashPassword(password);
+    try {
+        db.prepare(`INSERT INTO users (id, username, password_hash, is_admin, created_at, updated_at)
+       VALUES (?, ?, ?, 1, ?, ?)`).run(userId, username, passwordHash, now, now);
+        const user = {
+            id: userId,
+            username,
+            isAdmin: true,
+            avatarUrl: null,
+            securityCodeEnabled: false,
+            createdAt: now,
+            updatedAt: now,
+        };
+        const session = createSession(db, userId, clientInfo);
+        return { success: true, user, session };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (message.includes('UNIQUE constraint failed')) {
+            return { success: false, error: 'Username already exists' };
+        }
+        return { success: false, error: message };
+    }
+}
+// Create a new user (admin only)
+export async function createUser(db, username, password, isAdmin = false) {
+    const passwordValidationError = getStoredPasswordValidationError(password);
+    if (passwordValidationError) {
+        return { success: false, error: passwordValidationError };
+    }
+    const now = Date.now();
+    const userId = randomUUID();
+    const passwordHash = await hashPassword(password);
+    try {
+        db.prepare(`INSERT INTO users (id, username, password_hash, is_admin, created_at, updated_at)
+       VALUES (?, ?, ?, ?, ?, ?)`).run(userId, username, passwordHash, isAdmin ? 1 : 0, now, now);
+        const user = {
+            id: userId,
+            username,
+            isAdmin,
+            avatarUrl: null,
+            securityCodeEnabled: false,
+            createdAt: now,
+            updatedAt: now,
+        };
+        return { success: true, user };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (message.includes('UNIQUE constraint failed')) {
+            return { success: false, error: 'Username already exists' };
+        }
+        return { success: false, error: message };
+    }
+}
+// Create a session for a user
+export function createSession(db, userId, clientInfo) {
+    const now = Date.now();
+    const sessionId = randomUUID();
+    const token = generateSecureToken();
+    const expiresAt = now + SESSION_EXPIRY_MS;
+    const metadata = parseSessionClientInfo(clientInfo);
+    if (userSessionMetadataColumnsExist(db)) {
+        db.prepare(`INSERT INTO user_sessions (
+         id, user_id, token, created_at, expires_at, last_used_at,
+         ip, user_agent_family, os_family, device_type,
+         last_seen_ip, last_seen_user_agent_family, last_seen_os_family, last_seen_device_type
+       )
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(sessionId, userId, token, now, expiresAt, now, metadata.ip, metadata.userAgentFamily, metadata.osFamily, metadata.deviceType, metadata.ip, metadata.userAgentFamily, metadata.osFamily, metadata.deviceType);
+    }
+    else {
+        db.prepare(`INSERT INTO user_sessions (id, user_id, token, created_at, expires_at, last_used_at)
+       VALUES (?, ?, ?, ?, ?, ?)`).run(sessionId, userId, token, now, expiresAt, now);
+    }
+    return {
+        id: sessionId,
+        userId,
+        token,
+        createdAt: now,
+        expiresAt,
+        lastUsedAt: now,
+    };
+}
+// Validate session token
+export function validateSession(db, token, clientInfo) {
+    const now = Date.now();
+    const sessionRow = db.prepare(`SELECT s.id as sessionId, s.user_id as userId, s.expires_at as expiresAt
+     FROM user_sessions s
+     WHERE s.token = ?`).get(token);
+    if (!sessionRow)
+        return null;
+    // Check if session is expired
+    if (sessionRow.expiresAt && now > sessionRow.expiresAt) {
+        // Delete expired session
+        db.prepare('DELETE FROM user_sessions WHERE id = ?').run(sessionRow.sessionId);
+        return null;
+    }
+    const metadata = parseSessionClientInfo(clientInfo);
+    const hasUserAgent = Boolean(clientInfo?.userAgent?.trim());
+    if (userSessionMetadataColumnsExist(db)) {
+        db.prepare(`UPDATE user_sessions
+          SET last_used_at = ?,
+              last_seen_ip = COALESCE(?, last_seen_ip),
+              last_seen_user_agent_family = COALESCE(?, last_seen_user_agent_family),
+              last_seen_os_family = COALESCE(?, last_seen_os_family),
+              last_seen_device_type = COALESCE(?, last_seen_device_type)
+        WHERE id = ?`).run(now, metadata.ip, hasUserAgent ? metadata.userAgentFamily : null, hasUserAgent ? metadata.osFamily : null, hasUserAgent ? metadata.deviceType : null, sessionRow.sessionId);
+    }
+    else {
+        db.prepare('UPDATE user_sessions SET last_used_at = ? WHERE id = ?').run(now, sessionRow.sessionId);
+    }
+    // Get user info
+    const userRow = db.prepare(`SELECT id, username, is_admin, avatar_url, security_code_hash, created_at, updated_at
+     FROM users WHERE id = ?`).get(sessionRow.userId);
+    if (!userRow)
+        return null;
+    return mapUserRow(userRow);
+}
+// Login user
+export async function loginUser(db, username, password, securityCode, clientInfo) {
+    const userRow = db.prepare(`SELECT id, username, password_hash, is_admin, avatar_url, security_code_hash, created_at, updated_at
+     FROM users WHERE username = ?`).get(username);
+    if (!userRow) {
+        return { success: false, error: 'Invalid credentials', failureBucket: 'password' };
+    }
+    const passwordValid = await verifyPassword(password, userRow.password_hash);
+    if (!passwordValid) {
+        return { success: false, error: 'Invalid credentials', failureBucket: 'password' };
+    }
+    if (userRow.security_code_hash) {
+        if (!isValidSecurityCode(securityCode)) {
+            return { success: false, error: 'Invalid credentials', failureBucket: 'security_code' };
+        }
+        const securityCodeValid = await verifyPassword(securityCode, userRow.security_code_hash);
+        if (!securityCodeValid) {
+            return { success: false, error: 'Invalid credentials', failureBucket: 'security_code' };
+        }
+    }
+    const user = mapUserRow(userRow);
+    const session = createSession(db, userRow.id, clientInfo);
+    return { success: true, user, session };
+}
+// Logout user (delete session)
+export function logoutUser(db, token) {
+    const result = db.prepare('DELETE FROM user_sessions WHERE token = ?').run(token);
+    return result.changes > 0;
+}
+export function listUserSessions(db, params) {
+    const now = params.now ?? Date.now();
+    const hasMetadataColumns = userSessionMetadataColumnsExist(db);
+    const rows = hasMetadataColumns
+        ? db.prepare(`SELECT id, token, created_at, expires_at, last_used_at,
+              ip, user_agent_family, os_family, device_type,
+              last_seen_ip, last_seen_user_agent_family, last_seen_os_family, last_seen_device_type
+         FROM user_sessions
+        WHERE user_id = ?
+          AND (expires_at IS NULL OR expires_at > ?)
+        ORDER BY COALESCE(last_used_at, created_at) DESC`).all(params.userId, now)
+        : db.prepare(`SELECT id, token, created_at, expires_at, last_used_at
+         FROM user_sessions
+        WHERE user_id = ?
+          AND (expires_at IS NULL OR expires_at > ?)
+        ORDER BY COALESCE(last_used_at, created_at) DESC`).all(params.userId, now).map((row) => ({
+            ...row,
+            ip: null,
+            user_agent_family: null,
+            os_family: null,
+            device_type: null,
+            last_seen_ip: null,
+            last_seen_user_agent_family: null,
+            last_seen_os_family: null,
+            last_seen_device_type: null,
+        }));
+    const sessions = rows.map((row) => ({
+        id: row.id,
+        current: row.token === params.currentToken,
+        createdAt: row.created_at,
+        lastUsedAt: row.last_used_at,
+        expiresAt: row.expires_at,
+        ip: maskSessionIp(row.last_seen_ip ?? row.ip),
+        deviceType: row.last_seen_device_type ?? row.device_type ?? 'unknown',
+        browser: row.last_seen_user_agent_family ?? row.user_agent_family ?? 'Unknown',
+        os: row.last_seen_os_family ?? row.os_family ?? 'Unknown',
+    }));
+    return { activeCount: sessions.length, sessions };
+}
+export function revokeUserSession(db, params) {
+    const row = db.prepare('SELECT token FROM user_sessions WHERE id = ? AND user_id = ?').get(params.sessionId, params.userId);
+    if (!row)
+        return { ok: false, reason: 'not_found' };
+    if (row.token === params.currentToken)
+        return { ok: false, reason: 'current' };
+    db.prepare('DELETE FROM user_sessions WHERE id = ? AND user_id = ?').run(params.sessionId, params.userId);
+    return { ok: true };
+}
+export function revokeOtherUserSessions(db, userId, currentToken) {
+    const result = db.prepare('DELETE FROM user_sessions WHERE user_id = ? AND token <> ?').run(userId, currentToken);
+    return result.changes;
+}
+// Create an invite token
+export function createInviteToken(db) {
+    const now = Date.now();
+    const id = randomUUID();
+    const token = generateSecureToken();
+    const expiresAt = now + INVITE_EXPIRY_MS;
+    db.prepare(`INSERT INTO invite_tokens (id, token, used, expires_at, created_at, used_at, used_by)
+     VALUES (?, ?, 0, ?, ?, NULL, NULL)`).run(id, token, expiresAt, now);
+    return {
+        id,
+        token,
+        used: false,
+        expiresAt,
+        createdAt: now,
+        usedAt: null,
+        usedBy: null,
+    };
+}
+// Validate an invite token
+export function validateInviteToken(db, token) {
+    const now = Date.now();
+    const row = db.prepare(`SELECT id, used, expires_at FROM invite_tokens WHERE token = ?`).get(token);
+    if (!row) {
+        return { valid: false, error: 'Invalid invite token' };
+    }
+    if (row.used === 1) {
+        return { valid: false, error: 'Invite token has already been used' };
+    }
+    if (now > row.expires_at) {
+        return { valid: false, error: 'Invite token has expired' };
+    }
+    return { valid: true };
+}
+// Mark invite token as used
+export function useInviteToken(db, token, userId) {
+    const now = Date.now();
+    db.prepare(`UPDATE invite_tokens SET used = 1, used_at = ?, used_by = ? WHERE token = ?`).run(now, userId, token);
+}
+// Setup with invite token — first invite creates admin, subsequent ones create regular users
+export async function setupWithInvite(db, token, username, password, clientInfo) {
+    // Validate invite token
+    const validation = validateInviteToken(db, token);
+    if (!validation.valid) {
+        return { success: false, error: validation.error };
+    }
+    // First user becomes admin, everyone else is a regular user
+    const isFirstAdmin = !hasAdminUser(db);
+    const result = isFirstAdmin
+        ? await createAdminUser(db, username, password, clientInfo)
+        : await createUser(db, username, password, false);
+    if (!result.success) {
+        return result;
+    }
+    // Mark token as used
+    if (result.user) {
+        useInviteToken(db, token, result.user.id);
+    }
+    if (result.success && result.user && !result.session) {
+        result.session = createSession(db, result.user.id, clientInfo);
+    }
+    return result;
+}
+// Get user by ID
+export function getUserById(db, userId) {
+    const row = db.prepare(`SELECT id, username, is_admin, avatar_url, security_code_hash, created_at, updated_at
+     FROM users WHERE id = ?`).get(userId);
+    if (!row)
+        return null;
+    return mapUserRow(row);
+}
+export function updateUserProfile(db, userId, update) {
+    const now = Date.now();
+    if (Object.prototype.hasOwnProperty.call(update, 'avatarUrl')) {
+        const avatarUrl = update.avatarUrl?.trim() || null;
+        db.prepare('UPDATE users SET avatar_url = ?, updated_at = ? WHERE id = ?').run(avatarUrl, now, userId);
+    }
+    return getUserById(db, userId);
+}
+// List all users
+export function listUsers(db) {
+    const rows = db.prepare(`SELECT id, username, is_admin, avatar_url, security_code_hash, created_at, updated_at
+     FROM users ORDER BY created_at DESC`).all();
+    return rows.map(mapPublicUserRow);
+}
+export async function setUserSecurityCode(db, userId, securityCode) {
+    const now = Date.now();
+    const securityCodeHash = await hashPassword(securityCode);
+    db.prepare('UPDATE users SET security_code_hash = ?, updated_at = ? WHERE id = ?').run(securityCodeHash, now, userId);
+    return getUserById(db, userId);
+}
+export function disableUserSecurityCode(db, userId) {
+    const now = Date.now();
+    db.prepare('UPDATE users SET security_code_hash = NULL, updated_at = ? WHERE id = ?').run(now, userId);
+    return getUserById(db, userId);
+}
+export function revokeOtherSessions(db, userId, currentToken) {
+    db.prepare('DELETE FROM user_sessions WHERE user_id = ? AND token <> ?').run(userId, currentToken);
+}
+// Delete user
+export function deleteUser(db, userId) {
+    const result = db.prepare('DELETE FROM users WHERE id = ?').run(userId);
+    if (result.changes > 0) {
+        // Also delete all sessions for this user
+        db.prepare('DELETE FROM user_sessions WHERE user_id = ?').run(userId);
+        return true;
+    }
+    return false;
+}
+// Cleanup expired sessions and invite tokens
+export function cleanupExpiredTokens(db) {
+    const now = Date.now();
+    db.prepare('DELETE FROM user_sessions WHERE expires_at IS NOT NULL AND expires_at < ?').run(now);
+    db.prepare('DELETE FROM invite_tokens WHERE expires_at < ?').run(now);
+}
+// Get agent IDs the user has been granted access to
+export function getUserAgentAccess(db, userId) {
+    const rows = db
+        .prepare(`SELECT uaa.agent_id
+       FROM user_agent_access uaa
+       JOIN agents a ON a.agent_id = uaa.agent_id
+       WHERE uaa.user_id = ?
+         AND a.deleted_at IS NULL`)
+        .all(userId);
+    return rows.map((r) => r.agent_id);
+}
+// Get channel IDs the user has been granted access to
+export function getUserChannelAccess(db, userId) {
+    const rows = db
+        .prepare('SELECT channel_id FROM user_channel_access WHERE user_id = ?')
+        .all(userId);
+    return rows.map((r) => r.channel_id);
+}
+// Replace all access grants for a user atomically
+export function setUserAccess(db, userId, agentIds, channelIds) {
+    const now = Date.now();
+    const tx = db.transaction(() => {
+        db.prepare('DELETE FROM user_agent_access WHERE user_id = ?').run(userId);
+        db.prepare('DELETE FROM user_channel_access WHERE user_id = ?').run(userId);
+        const insertAgent = db.prepare('INSERT INTO user_agent_access (user_id, agent_id, granted_at) VALUES (?, ?, ?)');
+        for (const agentId of agentIds) {
+            insertAgent.run(userId, agentId, now);
+        }
+        const insertChannel = db.prepare('INSERT INTO user_channel_access (user_id, channel_id, granted_at) VALUES (?, ?, ?)');
+        for (const channelId of channelIds) {
+            insertChannel.run(userId, channelId, now);
+        }
+    });
+    tx();
+}