atoo-studio 0.0.1 → 0.0.2

package/dist/src/agents/registry.d.ts

@@ -0,0 +1,72 @@
+import type WebSocket from 'ws';
+import type { Agent, AgentFactory, AgentSessionInfo, AgentInitOptions, AgentDescriptor, HistoricalSession, LinkedIssueInfo } from './types.js';
+import type { SessionEvent } from '../events/types.js';
+interface BrowserState {
+    linkedIssue?: LinkedIssueInfo;
+    viewMode?: string;
+    showVerbose?: boolean;
+    title?: string;
+    metaName?: string;
+    metaDescription?: string;
+    tags?: string[];
+}
+declare class AgentRegistry {
+    private factories;
+    private agents;
+    registerFactory(factory: AgentFactory): void;
+    createAgent(agentType: string, sessionId: string, options: AgentInitOptions): Promise<Agent>;
+    getAgent(sessionId: string): Agent | undefined;
+    destroyAgent(sessionId: string): Promise<void>;
+    setSessionFocused(sessionId: string): void;
+    setSessionBlurred(sessionId: string): void;
+    setBrowserState(sessionId: string, state: Partial<BrowserState>): void;
+    getBrowserState(sessionId: string): BrowserState | undefined;
+    listAgents(): (AgentSessionInfo & {
+        browserState?: BrowserState;
+    })[];
+    addBrowserClient(sessionId: string, ws: WebSocket): void;
+    removeBrowserClient(sessionId: string, ws: WebSocket): void;
+    getAvailableAgents(): AgentDescriptor[];
+    getHistoricalSessions(cwd?: string): Promise<HistoricalSession[]>;
+    /**
+     * Collect all session JSONL file paths for a project directory,
+     * deduplicated across all registered agent factories.
+     * Resolves related paths (main project + all worktrees, current and historical)
+     * so that searching from any worktree or the main project returns the full history.
+     */
+    getSessionFilesForProject(cwd: string): Promise<string[]>;
+    resumeAgent(sessionUuid: string, options?: {
+        cwd?: string;
+        skipPermissions?: boolean;
+        agentType?: string;
+    }): Promise<Agent>;
+    /**
+     * Create a new chain link from an existing session.
+     * Carries forward user messages + last N events, generates a chain-linked UUID.
+     * The new session can search previous chain links via CurrentSessionChain.
+     */
+    chainAgent(sessionUuid: string, options?: {
+        cwd?: string;
+        skipPermissions?: boolean;
+        agentType?: string;
+    }): Promise<Agent>;
+    /**
+     * Create a chain link from in-memory events (for active agents).
+     * Bypasses the FS scanner — events come directly from the live agent.
+     */
+    chainFromEvents(events: SessionEvent[], parentSessionId: string, options?: {
+        cwd?: string;
+        skipPermissions?: boolean;
+        agentType?: string;
+    }): Promise<Agent>;
+    /**
+     * Convert a fork JSONL (always written in Claude format by forkToResumable)
+     * to the target agent's native format if cross-family.
+     * Returns the UUID to use for resume (same UUID, but file now in target format).
+     */
+    convertForkForAgent(forkUuid: string, sourceAgentType: string, targetAgentType: string, cwd: string): Promise<string>;
+    private broadcastToClients;
+    private broadcastRawToClients;
+}
+export declare const agentRegistry: AgentRegistry;
+export {};

package/dist/src/agents/registry.js

@@ -0,0 +1,337 @@
+import { v4 as uuidv4 } from 'uuid';
+import { store } from '../state/store.js';
+import { db } from '../state/db.js';
+import { buildChainSession } from './lib/chain-builder.js';
+import { fsSessionScanner } from './lib/claude/fs-sessions.js';
+class AgentRegistry {
+    factories = new Map();
+    agents = new Map();
+    registerFactory(factory) {
+        this.factories.set(factory.agentType, factory);
+        console.log(`[agent-registry] Registered factory: ${factory.agentType}`);
+    }
+    async createAgent(agentType, sessionId, options) {
+        const factory = this.factories.get(agentType);
+        if (!factory) {
+            throw new Error(`Unknown agent type: ${agentType}`);
+        }
+        const agent = factory.create(sessionId);
+        const entry = {
+            agent,
+            agentType,
+            browserClients: new Set(),
+            contextInProgress: false,
+            browserState: {},
+        };
+        this.agents.set(sessionId, entry);
+        // Wire up event forwarding
+        agent.on('message', (msg) => {
+            this.broadcastToClients(sessionId, msg);
+        });
+        // Forward agent status to the global store for WebSocket broadcasting.
+        // Each agent adapter owns its activity status (open/active/attention).
+        agent.on('status', (status) => {
+            if (status === 'exited')
+                return; // handled by destroyAgent
+            store.setAgentStatus(sessionId, status);
+        });
+        agent.on('context_in_progress', (inProgress) => {
+            const e = this.agents.get(sessionId);
+            if (e)
+                e.contextInProgress = inProgress;
+            this.broadcastRawToClients(sessionId, { type: 'context_in_progress', inProgress });
+        });
+        agent.on('exit', () => {
+            console.log(`[agent-registry] Agent exited: ${sessionId}`);
+        });
+        agent.on('error', (err) => {
+            console.error(`[agent-registry] Agent error for ${sessionId}:`, err.message);
+        });
+        // Initialize the agent
+        await agent.initialize(options);
+        console.log(`[agent-registry] Agent created: ${sessionId} (type: ${agentType})`);
+        return agent;
+    }
+    getAgent(sessionId) {
+        return this.agents.get(sessionId)?.agent;
+    }
+    async destroyAgent(sessionId) {
+        const entry = this.agents.get(sessionId);
+        if (!entry)
+            return;
+        // Remove all event listeners BEFORE destroying to prevent
+        // late status broadcasts from reviving the session in the UI
+        entry.agent.removeAllListeners();
+        // Close all browser WS connections
+        for (const ws of entry.browserClients) {
+            try {
+                ws.close();
+            }
+            catch { }
+        }
+        entry.browserClients.clear();
+        await entry.agent.destroy();
+        this.agents.delete(sessionId);
+        // Clean up status from the global store and broadcast removal
+        store.removeAgentStatus(sessionId);
+        console.log(`[agent-registry] Agent destroyed: ${sessionId}`);
+    }
+    setSessionFocused(sessionId) {
+        this.agents.get(sessionId)?.agent.onFocused();
+    }
+    setSessionBlurred(sessionId) {
+        this.agents.get(sessionId)?.agent.onBlurred();
+    }
+    setBrowserState(sessionId, state) {
+        const entry = this.agents.get(sessionId);
+        if (entry)
+            Object.assign(entry.browserState, state);
+    }
+    getBrowserState(sessionId) {
+        return this.agents.get(sessionId)?.browserState;
+    }
+    listAgents() {
+        const infos = [];
+        for (const entry of this.agents.values()) {
+            const info = entry.agent.getInfo();
+            if (entry.browserState.linkedIssue)
+                info.linkedIssue = entry.browserState.linkedIssue;
+            infos.push({ ...info, browserState: entry.browserState });
+        }
+        return infos;
+    }
+    addBrowserClient(sessionId, ws) {
+        const entry = this.agents.get(sessionId);
+        if (!entry)
+            return;
+        entry.browserClients.add(ws);
+        // Send current context_in_progress state so late-joining browsers get it
+        if (entry.contextInProgress) {
+            ws.send(JSON.stringify({ type: 'context_in_progress', inProgress: true }));
+        }
+    }
+    removeBrowserClient(sessionId, ws) {
+        const entry = this.agents.get(sessionId);
+        if (!entry)
+            return;
+        entry.browserClients.delete(ws);
+    }
+    getAvailableAgents() {
+        const descriptors = [];
+        for (const factory of this.factories.values()) {
+            descriptors.push(factory.getDescriptor());
+        }
+        return descriptors;
+    }
+    async getHistoricalSessions(cwd) {
+        const allSessions = [];
+        for (const factory of this.factories.values()) {
+            const sessions = await factory.getHistoricalSessions();
+            allSessions.push(...sessions);
+        }
+        // Deduplicate by session ID — when same UUID exists across factories, keep the most recent
+        const bestById = new Map();
+        for (const s of allSessions) {
+            const existing = bestById.get(s.id);
+            if (!existing || new Date(s.lastModified).getTime() > new Date(existing.lastModified).getTime()) {
+                bestById.set(s.id, s);
+            }
+        }
+        let unique = Array.from(bestById.values());
+        // Filter by project path (includes main project + all worktree paths)
+        if (cwd) {
+            const relatedPaths = new Set(db.getAllRelatedProjectPaths(cwd));
+            unique = unique.filter(s => relatedPaths.has(s.directory));
+        }
+        // Sort by date descending (most recent first)
+        unique.sort((a, b) => new Date(b.lastModified).getTime() - new Date(a.lastModified).getTime());
+        return unique;
+    }
+    /**
+     * Collect all session JSONL file paths for a project directory,
+     * deduplicated across all registered agent factories.
+     * Resolves related paths (main project + all worktrees, current and historical)
+     * so that searching from any worktree or the main project returns the full history.
+     */
+    async getSessionFilesForProject(cwd) {
+        // Resolve all related project paths (main + worktrees, current and historical)
+        const relatedPaths = db.getAllRelatedProjectPaths(cwd);
+        const seen = new Set();
+        const allFiles = [];
+        for (const factory of this.factories.values()) {
+            const files = await factory.getSessionFilesForProject(relatedPaths);
+            for (const f of files) {
+                if (!seen.has(f)) {
+                    seen.add(f);
+                    allFiles.push(f);
+                }
+            }
+        }
+        return allFiles;
+    }
+    async resumeAgent(sessionUuid, options = {}) {
+        // Find the factory that owns this session
+        let sourceFactory = null;
+        for (const factory of this.factories.values()) {
+            if (await factory.ownsSession(sessionUuid)) {
+                sourceFactory = factory;
+                break;
+            }
+        }
+        if (!sourceFactory) {
+            throw new Error(`No agent implementation recognizes session ${sessionUuid}`);
+        }
+        // Determine target factory (requested agentType or same as source)
+        const targetAgentType = options.agentType || sourceFactory.agentType;
+        const targetFactory = this.factories.get(targetAgentType);
+        if (!targetFactory) {
+            throw new Error(`Unknown agent type: ${targetAgentType}`);
+        }
+        let resumeUuid = sessionUuid;
+        let isChainContinuation = false;
+        // Cross-family resume: create a chain link instead of reusing the same UUID.
+        // This keeps each session file unambiguously one agent family and preserves
+        // the parent→child link via the session ID schema.
+        if (sourceFactory.agentFamily !== targetFactory.agentFamily) {
+            const events = await sourceFactory.readSessionEvents(sessionUuid);
+            if (!events.length) {
+                throw new Error(`No events found in session ${sessionUuid} for cross-family conversion`);
+            }
+            const cwd = options.cwd || '.';
+            const { buildLinkedUuid } = await import('./lib/session-id-utils.js');
+            const chainUuid = buildLinkedUuid(sessionUuid, 'chain');
+            targetFactory.writeSessionForResume(events, chainUuid, cwd);
+            resumeUuid = chainUuid;
+            isChainContinuation = true;
+        }
+        const sessionId = `agent_${uuidv4()}`;
+        return this.createAgent(targetFactory.agentType, sessionId, {
+            cwd: options.cwd,
+            skipPermissions: options.skipPermissions,
+            resumeSessionUuid: resumeUuid,
+            isChainContinuation,
+        });
+    }
+    /**
+     * Create a new chain link from an existing session.
+     * Carries forward user messages + last N events, generates a chain-linked UUID.
+     * The new session can search previous chain links via CurrentSessionChain.
+     */
+    async chainAgent(sessionUuid, options = {}) {
+        // Find the factory that owns the source session.
+        // Invalidate caches first since we may be chaining from a still-running session
+        // whose JSONL has grown since the last scan.
+        fsSessionScanner.invalidate();
+        let sourceFactory = null;
+        for (const factory of this.factories.values()) {
+            if (await factory.ownsSession(sessionUuid)) {
+                sourceFactory = factory;
+                break;
+            }
+        }
+        if (!sourceFactory) {
+            throw new Error(`No agent implementation recognizes session ${sessionUuid}`);
+        }
+        // Read events from the source session (file is up-to-date since CLIs write incrementally)
+        const events = await sourceFactory.readSessionEvents(sessionUuid);
+        if (!events.length) {
+            throw new Error(`No events found in session ${sessionUuid} for chain creation`);
+        }
+        // Determine target factory
+        const targetAgentType = options.agentType || sourceFactory.agentType;
+        const targetFactory = this.factories.get(targetAgentType);
+        if (!targetFactory) {
+            throw new Error(`Unknown agent type: ${targetAgentType}`);
+        }
+        const cwd = options.cwd || '.';
+        // Build chain events + UUID (does not write to disk)
+        const chain = buildChainSession(events, sessionUuid);
+        if (!chain) {
+            throw new Error(`Session has no conversation content to chain — try sending a message first`);
+        }
+        // Write in the target agent's native format
+        targetFactory.writeSessionForResume(chain.events, chain.uuid, cwd);
+        const sessionId = `agent_${uuidv4()}`;
+        return this.createAgent(targetFactory.agentType, sessionId, {
+            cwd: options.cwd,
+            skipPermissions: options.skipPermissions,
+            resumeSessionUuid: chain.uuid,
+            isChainContinuation: true,
+        });
+    }
+    /**
+     * Create a chain link from in-memory events (for active agents).
+     * Bypasses the FS scanner — events come directly from the live agent.
+     */
+    async chainFromEvents(events, parentSessionId, options = {}) {
+        if (!events.length) {
+            throw new Error('No events provided for chain creation');
+        }
+        // Determine target factory
+        const targetAgentType = options.agentType || 'claude-code-terminal-chatro';
+        const targetFactory = this.factories.get(targetAgentType);
+        if (!targetFactory) {
+            throw new Error(`Unknown agent type: ${targetAgentType}`);
+        }
+        const cwd = options.cwd || '.';
+        // Build chain events + UUID (does not write to disk)
+        const chain = buildChainSession(events, parentSessionId);
+        if (!chain) {
+            throw new Error('Session has no conversation content to chain — try sending a message first');
+        }
+        // Write in the target agent's native format
+        targetFactory.writeSessionForResume(chain.events, chain.uuid, cwd);
+        const sessionId = `agent_${uuidv4()}`;
+        return this.createAgent(targetFactory.agentType, sessionId, {
+            cwd: options.cwd,
+            skipPermissions: options.skipPermissions,
+            resumeSessionUuid: chain.uuid,
+            isChainContinuation: true,
+        });
+    }
+    /**
+     * Convert a fork JSONL (always written in Claude format by forkToResumable)
+     * to the target agent's native format if cross-family.
+     * Returns the UUID to use for resume (same UUID, but file now in target format).
+     */
+    async convertForkForAgent(forkUuid, sourceAgentType, targetAgentType, cwd) {
+        const sourceFactory = this.factories.get(sourceAgentType);
+        const targetFactory = this.factories.get(targetAgentType);
+        if (!sourceFactory || !targetFactory)
+            return forkUuid;
+        if (sourceFactory.agentFamily === targetFactory.agentFamily)
+            return forkUuid;
+        // Fork was written as Claude JSONL — read via a Claude factory
+        const claudeFactory = [...this.factories.values()].find(f => f.agentFamily === 'claude');
+        if (!claudeFactory)
+            return forkUuid;
+        const events = await claudeFactory.readSessionEvents(forkUuid);
+        if (!events.length)
+            return forkUuid;
+        targetFactory.writeSessionForResume(events, forkUuid, cwd);
+        return forkUuid;
+    }
+    broadcastToClients(sessionId, message) {
+        const entry = this.agents.get(sessionId);
+        if (!entry)
+            return;
+        const data = JSON.stringify(message);
+        for (const ws of entry.browserClients) {
+            if (ws.readyState === 1) {
+                ws.send(data);
+            }
+        }
+    }
+    broadcastRawToClients(sessionId, message) {
+        const entry = this.agents.get(sessionId);
+        if (!entry)
+            return;
+        const data = JSON.stringify(message);
+        for (const ws of entry.browserClients) {
+            if (ws.readyState === 1) {
+                ws.send(data);
+            }
+        }
+    }
+}
+export const agentRegistry = new AgentRegistry();

package/dist/src/agents/types.d.ts

@@ -0,0 +1,135 @@
+import { EventEmitter } from 'events';
+import type { SessionEvent } from '../events/types.js';
+import type { WireMessage } from '../events/wire.js';
+export type AgentStatus = 'open' | 'active' | 'attention' | 'exited';
+export type AgentMode = 'terminal' | 'chat' | 'terminal+chat' | 'terminal+chatRO';
+export interface AgentDescriptor {
+    agentType: string;
+    agentFamily: string;
+    name: string;
+    mode: AgentMode;
+    iconUrl: string;
+}
+export interface AgentCapabilities {
+    canChangeMode: boolean;
+    canChangeModel: boolean;
+    hasContextUsage: boolean;
+    canFork: boolean;
+    canResume: boolean;
+    hasTerminal: boolean;
+    hasFileTracking: boolean;
+    availableModes: string[];
+    availableModels: string[];
+}
+export interface LinkedIssueInfo {
+    type: 'issue' | 'pr';
+    number: number;
+    title: string;
+    url: string;
+}
+export interface AgentSessionInfo {
+    sessionId: string;
+    agentType: string;
+    agentMode: AgentMode;
+    status: AgentStatus;
+    mode?: string;
+    model?: string;
+    cwd?: string;
+    capabilities: AgentCapabilities;
+    createdAt: number;
+    /** The CLI's own session UUID (for chain link detection in the sidebar) */
+    cliSessionId?: string;
+    /** Linked GitHub issue or PR */
+    linkedIssue?: LinkedIssueInfo;
+}
+export interface AgentInitOptions {
+    cwd?: string;
+    skipPermissions?: boolean;
+    resumeSessionUuid?: string;
+    /** When true, this is a chain continuation session — append chain system prompt */
+    isChainContinuation?: boolean;
+    /** Optional message to append to the initial greeting in the pre-created session */
+    initialMessage?: string;
+}
+export interface Agent extends EventEmitter {
+    initialize(options: AgentInitOptions): Promise<void>;
+    destroy(): Promise<void>;
+    sendMessage(text: string, attachments?: Attachment[]): void;
+    approve(requestId: string, updatedInput?: any): void;
+    deny(requestId: string): void;
+    answerQuestion(requestId: string, answers: Record<string, string>): void;
+    setMode(mode: string): void;
+    setModel(model: string): void;
+    refreshContext(): void;
+    sendKey(key: string): void;
+    onFocused(): void;
+    onBlurred(): void;
+    /**
+     * Fork this agent's events into a resumable session file.
+     * Returns the resume UUID, or null if forking isn't supported.
+     */
+    forkToResumable(afterEventUuid: string, fromEventUuid?: string, targetDir?: string): string | null;
+    getInfo(): AgentSessionInfo;
+    getMessages(): WireMessage[];
+    getEvents(): SessionEvent[];
+    getWireMessages(): WireMessage[];
+    getCliSessionId?(): string | null;
+}
+export interface HistoricalSession {
+    id: string;
+    agentType: string;
+    title: string;
+    directory: string;
+    lastModified: string;
+    eventCount: number;
+    metaName?: string;
+    tags?: string[];
+}
+export interface AgentFactory {
+    agentType: string;
+    /** Agent family identifier — factories in the same family can resume each other's sessions directly */
+    agentFamily: string;
+    create(sessionId: string): Agent;
+    getDescriptor(): AgentDescriptor;
+    getHistoricalSessions(): Promise<HistoricalSession[]>;
+    ownsSession(uuid: string): Promise<boolean>;
+    /** Return all session JSONL file paths (including subagent files) for the given project directories */
+    getSessionFilesForProject(cwds: string[]): Promise<string[]>;
+    /** Read a session's events (for cross-family conversion) */
+    readSessionEvents(uuid: string): Promise<SessionEvent[]>;
+    /** Write events in this family's native format for resuming. Returns the JSONL path. */
+    writeSessionForResume(events: SessionEvent[], targetUuid: string, directory: string): string;
+}
+export interface Attachment {
+    media_type: string;
+    data: string;
+    name?: string;
+    text?: string;
+}
+export type AgentCommand = {
+    action: 'send_message';
+    text: string;
+    attachments?: Attachment[];
+} | {
+    action: 'approve';
+    requestId: string;
+    updatedInput?: any;
+} | {
+    action: 'deny';
+    requestId: string;
+} | {
+    action: 'answer_question';
+    requestId: string;
+    answers: Record<string, string>;
+} | {
+    action: 'set_mode';
+    mode: string;
+} | {
+    action: 'set_model';
+    model: string;
+} | {
+    action: 'refresh_context';
+} | {
+    action: 'send_key';
+    key: string;
+};

package/dist/src/agents/types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/auth/crypto-key.d.ts

@@ -0,0 +1,6 @@
+/** Get or generate the server-side encryption key for TOTP secrets. */
+export declare function getAuthKey(): Buffer;
+/** Encrypt plaintext using AES-256-GCM with the server auth key. */
+export declare function encrypt(plaintext: string): string;
+/** Decrypt ciphertext encrypted with encrypt(). */
+export declare function decrypt(ciphertext: string): string;

package/dist/src/auth/crypto-key.js

@@ -0,0 +1,45 @@
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import crypto from 'crypto';
+const STORE_DIR = path.join(os.homedir(), '.atoo-studio');
+const AUTH_KEY_PATH = path.join(STORE_DIR, 'auth.key');
+let cachedKey = null;
+/** Get or generate the server-side encryption key for TOTP secrets. */
+export function getAuthKey() {
+    if (cachedKey)
+        return cachedKey;
+    if (!fs.existsSync(STORE_DIR)) {
+        fs.mkdirSync(STORE_DIR, { recursive: true });
+    }
+    if (fs.existsSync(AUTH_KEY_PATH)) {
+        cachedKey = Buffer.from(fs.readFileSync(AUTH_KEY_PATH, 'utf-8').trim(), 'hex');
+    }
+    else {
+        cachedKey = crypto.randomBytes(32);
+        fs.writeFileSync(AUTH_KEY_PATH, cachedKey.toString('hex'), { mode: 0o600 });
+        console.log('[auth] Generated new auth encryption key');
+    }
+    return cachedKey;
+}
+/** Encrypt plaintext using AES-256-GCM with the server auth key. */
+export function encrypt(plaintext) {
+    const key = getAuthKey();
+    const iv = crypto.randomBytes(12);
+    const cipher = crypto.createCipheriv('aes-256-gcm', key, iv);
+    const encrypted = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    // Format: iv:tag:ciphertext (all hex)
+    return `${iv.toString('hex')}:${tag.toString('hex')}:${encrypted.toString('hex')}`;
+}
+/** Decrypt ciphertext encrypted with encrypt(). */
+export function decrypt(ciphertext) {
+    const key = getAuthKey();
+    const [ivHex, tagHex, dataHex] = ciphertext.split(':');
+    const iv = Buffer.from(ivHex, 'hex');
+    const tag = Buffer.from(tagHex, 'hex');
+    const data = Buffer.from(dataHex, 'hex');
+    const decipher = crypto.createDecipheriv('aes-256-gcm', key, iv);
+    decipher.setAuthTag(tag);
+    return Buffer.concat([decipher.update(data), decipher.final()]).toString('utf8');
+}

package/dist/src/auth/middleware.d.ts

@@ -0,0 +1,18 @@
+import type { Request, Response, NextFunction } from 'express';
+import type { IncomingMessage } from 'http';
+import { type User } from '../state/db.js';
+declare global {
+    namespace Express {
+        interface Request {
+            user?: User;
+        }
+    }
+}
+/** Middleware: require a valid auth session. Attaches req.user. */
+export declare function requireAuth(req: Request, res: Response, next: NextFunction): void;
+/** Middleware: require admin role. Must be used after requireAuth. */
+export declare function requireAdmin(req: Request, res: Response, next: NextFunction): void;
+/** Parse session from WebSocket upgrade request headers. Returns user or null. */
+export declare function authenticateWsUpgrade(req: IncomingMessage): User | null;
+/** Check if auth is required (users exist). */
+export declare function isAuthEnabled(): boolean;

package/dist/src/auth/middleware.js

@@ -0,0 +1,54 @@
+import { SESSION_COOKIE_NAME } from './session.js';
+import { getSessionUser } from './session.js';
+import { db } from '../state/db.js';
+/** Middleware: require a valid auth session. Attaches req.user. */
+export function requireAuth(req, res, next) {
+    // Setup mode: if no users exist, return 503
+    if (db.getUserCount() === 0) {
+        res.status(503).json({ error: 'Setup required', setupRequired: true });
+        return;
+    }
+    const sessionId = req.cookies?.[SESSION_COOKIE_NAME];
+    if (!sessionId) {
+        res.status(401).json({ error: 'Authentication required' });
+        return;
+    }
+    const user = getSessionUser(sessionId);
+    if (!user) {
+        res.status(401).json({ error: 'Invalid or expired session' });
+        return;
+    }
+    req.user = user;
+    next();
+}
+/** Middleware: require admin role. Must be used after requireAuth. */
+export function requireAdmin(req, res, next) {
+    requireAuth(req, res, () => {
+        if (req.user?.role !== 'admin') {
+            res.status(403).json({ error: 'Admin access required' });
+            return;
+        }
+        next();
+    });
+}
+/** Parse session from WebSocket upgrade request headers. Returns user or null. */
+export function authenticateWsUpgrade(req) {
+    // If no users exist (setup mode), allow all WebSocket connections
+    if (db.getUserCount() === 0)
+        return null;
+    const cookieHeader = req.headers.cookie;
+    if (!cookieHeader)
+        return null;
+    const sessionId = parseCookieValue(cookieHeader, SESSION_COOKIE_NAME);
+    if (!sessionId)
+        return null;
+    return getSessionUser(sessionId);
+}
+/** Check if auth is required (users exist). */
+export function isAuthEnabled() {
+    return db.getUserCount() > 0;
+}
+function parseCookieValue(cookieHeader, name) {
+    const match = cookieHeader.match(new RegExp(`(?:^|;\\s*)${name}=([^;]*)`));
+    return match ? decodeURIComponent(match[1]) : null;
+}

package/dist/src/auth/password.d.ts

@@ -0,0 +1,2 @@
+export declare function hashPassword(plain: string): Promise<string>;
+export declare function verifyPassword(plain: string, hash: string): Promise<boolean>;