@saluzi/saluzi-edu 0.3.1 → 0.3.2

package/dist/guide/guide-data.json

@@ -5920,6 +5920,14 @@
       "defaultValue": "0.0.0.0",
       "description": "RCS 监听地址"
     },
+    {
+      "name": "RCS_ONE_WORKER_DIR",
+      "category": "other"
+    },
+    {
+      "name": "RCS_ONE_WORKER_NAME",
+      "category": "other"
+    },
     {
       "name": "RCS_PORT",
       "category": "runtime",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saluzi/saluzi-edu",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Saluzi CLI - interactive AI coding assistant in the terminal",
   "license": "MIT",
   "type": "module",

package/packages/remote-control-server/src/__tests__/otp-route.test.ts

@@ -0,0 +1,130 @@
+import { describe, test, expect, beforeEach, mock } from 'bun:test'
+import { createMockConfig } from './helpers/mock-config'
+
+// Mutable config mock — tests flip `singleUser` to exercise the
+// single-user-only gate on GET /otp/:code.
+const configState = createMockConfig()
+mock.module('../config', () => ({
+  config: configState,
+  getBaseUrl: () => configState.baseUrl,
+}))
+
+import { Hono } from 'hono'
+import type { MiddlewareHandler } from 'hono/types'
+import { randomUUID } from 'node:crypto'
+import { tmpdir } from 'node:os'
+import { resolve } from 'node:path'
+import { initDatabase, resetDbSingleton, getDb } from '../db/sqlite'
+import { registerRoutes } from '../registerRoutes'
+import { _resetWebLoginCodes, issueWebLoginCode } from '../services/web-login'
+import { createUserDirectly } from './helpers/fixtures'
+
+/**
+ * GET /otp/:code — one-time browser login for `slz rcs one`:
+ * - valid code (single-user mode) → session cookies for the single admin
+ *   + redirect to the stored target path; the minted token authenticates
+ *     against /web/auth/me
+ * - codes are single-use — a second hit redirects to /login
+ * - unknown/expired codes redirect to /login (manual login still works)
+ * - full mode (singleUser=false) → 404 — the route is one-only
+ */
+
+// Dummy serveStatic — passes through so API routes handle everything.
+const serveStatic: (opts: Record<string, unknown>) => MiddlewareHandler =
+  () => async (_c, next) => {
+    await next()
+  }
+
+// Dummy upgradeWebSocket
+const upgradeWebSocket = (() => {
+  return () =>
+    async (_c: import('hono').Context, next: import('hono').Next) => {
+      await next()
+    }
+}) as unknown as import('hono/ws').UpgradeWebSocket<unknown>
+
+function createApp(): Hono {
+  const app = new Hono()
+  registerRoutes(app, serveStatic, upgradeWebSocket)
+  return app
+}
+
+function setupTestDb(): ReturnType<typeof getDb> {
+  try {
+    resetDbSingleton()
+  } catch {
+    // ignore
+  }
+  const uniquePath = resolve(
+    tmpdir(),
+    `rcs-otp-${randomUUID().replace(/-/g, '').slice(0, 8)}.db`,
+  )
+  return initDatabase(uniquePath)
+}
+
+describe('GET /otp/:code', () => {
+  let app: Hono
+
+  beforeEach(() => {
+    setupTestDb()
+    _resetWebLoginCodes()
+    configState.singleUser = true
+    app = createApp()
+  })
+
+  test('valid code sets admin session cookies and redirects to the target', async () => {
+    const db = getDb()
+    const admin = createUserDirectly(db, { username: 'admin', role: 'admin' })
+    const issued = issueWebLoginCode(admin.id, '/code/session_abc')
+
+    const res = await app.request(`/otp/${issued.code}`)
+    expect(res.status).toBe(302)
+    expect(res.headers.get('Location')).toBe('/code/session_abc')
+
+    const cookies = res.headers.getSetCookie()
+    const accessCookie = cookies.find(c => c.startsWith('rcs_access='))
+    const refreshCookie = cookies.find(c => c.startsWith('rcs_refresh='))
+    expect(accessCookie).toBeDefined()
+    expect(refreshCookie).toBeDefined()
+
+    // The minted access token must authenticate as the admin user.
+    const accessToken = accessCookie!.split(';')[0]!.slice('rcs_access='.length)
+    const me = await app.request('/web/auth/me', {
+      headers: { Cookie: `rcs_access=${accessToken}` },
+    })
+    expect(me.status).toBe(200)
+    const meBody = (await me.json()) as { userId: string; role: string }
+    expect(meBody.userId).toBe(admin.id)
+    expect(meBody.role).toBe('admin')
+  })
+
+  test('codes are single-use — a second hit falls back to /login', async () => {
+    const db = getDb()
+    const admin = createUserDirectly(db, { username: 'admin', role: 'admin' })
+    const issued = issueWebLoginCode(admin.id, '/code/')
+
+    const first = await app.request(`/otp/${issued.code}`)
+    expect(first.status).toBe(302)
+    expect(first.headers.get('Location')).toBe('/code/')
+
+    const second = await app.request(`/otp/${issued.code}`)
+    expect(second.status).toBe(302)
+    expect(second.headers.get('Location')).toBe('/login')
+  })
+
+  test('unknown code redirects to /login', async () => {
+    const res = await app.request('/otp/wlc_unknowncodeunknowncode')
+    expect(res.status).toBe(302)
+    expect(res.headers.get('Location')).toBe('/login')
+  })
+
+  test('returns 404 in full (non-single-user) mode', async () => {
+    configState.singleUser = false
+    const db = getDb()
+    const admin = createUserDirectly(db, { username: 'admin', role: 'admin' })
+    const issued = issueWebLoginCode(admin.id, '/code/')
+
+    const res = await app.request(`/otp/${issued.code}`)
+    expect(res.status).toBe(404)
+  })
+})

package/packages/remote-control-server/src/__tests__/web-login.test.ts

@@ -0,0 +1,84 @@
+import { describe, test, expect, beforeEach } from 'bun:test'
+import {
+  MAX_PENDING_CODES,
+  consumeWebLoginCode,
+  issueWebLoginCode,
+  _resetWebLoginCodes,
+} from '../services/web-login'
+
+/**
+ * One-time web login codes (`slz rcs one` browser auto-open):
+ * - single use — the first consume returns the record, the second null
+ * - 2-minute TTL — expired codes are rejected and pruned
+ * - target paths are clamped to same-origin paths (no '//host' open redirect)
+ * - the pending map is bounded
+ */
+
+describe('web-login codes', () => {
+  beforeEach(() => {
+    _resetWebLoginCodes()
+  })
+
+  test('consume returns the record exactly once (single use)', () => {
+    const issued = issueWebLoginCode('usr_abc', '/code/session_1')
+    expect(issued.code).toMatch(/^wlc_[0-9a-f]{32}$/)
+    expect(issued.targetPath).toBe('/code/session_1')
+    expect(issued.userId).toBe('usr_abc')
+
+    const consumed = consumeWebLoginCode(issued.code)
+    expect(consumed).not.toBeNull()
+    expect(consumed?.userId).toBe('usr_abc')
+    expect(consumed?.targetPath).toBe('/code/session_1')
+
+    // Second consume — already used.
+    expect(consumeWebLoginCode(issued.code)).toBeNull()
+  })
+
+  test('unknown code returns null', () => {
+    expect(
+      consumeWebLoginCode('wlc_deadbeefdeadbeefdeadbeefdeadbeef'),
+    ).toBeNull()
+  })
+
+  test('targetPath is clamped to a same-origin path', () => {
+    expect(issueWebLoginCode('usr_abc', '/code/session_1').targetPath).toBe(
+      '/code/session_1',
+    )
+    // No leading slash → root.
+    expect(issueWebLoginCode('usr_abc', 'code/session_1').targetPath).toBe('/')
+    // Protocol-relative would be an open redirect — clamp.
+    expect(issueWebLoginCode('usr_abc', '//evil.example/x').targetPath).toBe(
+      '/',
+    )
+    // Absolute URL → root.
+    expect(
+      issueWebLoginCode('usr_abc', 'https://evil.example/x').targetPath,
+    ).toBe('/')
+  })
+
+  test('expired code is rejected', () => {
+    const issued = issueWebLoginCode('usr_abc', '/code/')
+    const realNow = Date.now
+    // Jump past the 2-minute TTL.
+    Date.now = () => realNow() + 3 * 60 * 1000
+    try {
+      expect(consumeWebLoginCode(issued.code)).toBeNull()
+    } finally {
+      Date.now = realNow
+    }
+  })
+
+  test('pending map is bounded — oldest entries are evicted', () => {
+    const oldest = issueWebLoginCode('usr_abc', '/code/oldest')
+    // Fill to exactly the cap without exceeding it.
+    let last: ReturnType<typeof issueWebLoginCode> | undefined
+    for (let i = 1; i < MAX_PENDING_CODES; i++) {
+      last = issueWebLoginCode('usr_abc', `/code/fill-${i}`)
+    }
+    // One more beyond the cap — the oldest was evicted to make room…
+    issueWebLoginCode('usr_abc', '/code/overflow')
+    expect(consumeWebLoginCode(oldest.code)).toBeNull()
+    // …while recent entries stay intact.
+    expect(consumeWebLoginCode(last!.code)).not.toBeNull()
+  })
+})

package/packages/remote-control-server/src/nodeServer.ts

@@ -37,9 +37,26 @@ export interface RcsServerOptions {
   /** Single-user mode (`slz rcs one`): auto-init admin account, workers
    *  auto-owned, registration disabled, host defaults to 127.0.0.1. */
   singleUser?: boolean
+  /** Embedded mode: the server shares its process with something else that
+   *  owns the terminal and the process lifecycle (e.g. `slz rcs one` boots
+   *  an in-process REPL as the single repl worker). Skips the SIGINT/SIGTERM
+   *  handlers — they would process.exit(0) on the REPL's first Ctrl+C — and
+   *  skips the block-forever await so the caller can continue booting. */
+  embedded?: boolean
 }
 
-export async function startRcsServer(opts: RcsServerOptions): Promise<void> {
+/** Bound server coordinates, as returned by startRcsServer. */
+export interface RcsServerInfo {
+  port: number
+  /** The address the server actually bound (may be 0.0.0.0). */
+  host: string
+  /** Browser-reachable origin (0.0.0.0/:: mapped to localhost). */
+  webUiUrl: string
+}
+
+export async function startRcsServer(
+  opts: RcsServerOptions,
+): Promise<RcsServerInfo> {
   // Set env vars so config module picks them up
   process.env.RCS_API_KEYS = opts.apiKeys.join(',')
   // The config module may already be evaluated (static import above) — its
@@ -55,18 +72,6 @@ export async function startRcsServer(opts: RcsServerOptions): Promise<void> {
     config.host = opts.host
   }
   if (opts.singleUser) process.env.RCS_SINGLE_USER = 'true'
-  // The config module may already be evaluated (static import above) — its
-  // env-derived values are frozen, so opts.host/opts.port must also be
-  // applied to the live object or they would silently no-op.
-  if (opts.port) {
-    process.env.RCS_PORT = String(opts.port)
-    config.port = opts.port
-  }
-  if (opts.host) {
-    process.env.RCS_HOST = opts.host
-    config.host = opts.host
-  }
-  if (opts.singleUser) process.env.RCS_SINGLE_USER = 'true'
 
   // Effective single-user mode: the `one` argument OR RCS_SINGLE_USER=true
   // set before process start (config.singleUser already reflects the env).
@@ -93,8 +98,13 @@ export async function startRcsServer(opts: RcsServerOptions): Promise<void> {
   // Create Node.js WebSocket adapter
   const { injectWebSocket, upgradeWebSocket } = createNodeWebSocket({ app })
 
-  // Middleware
-  app.use('*', logger())
+  // Middleware. Per-request hono logger only in standalone mode — embedded
+  // mode shares the terminal with the host flow (`slz rcs one` prints a
+  // clean banner; the worker logs to its own file), so request spam would
+  // just be noise.
+  if (!opts.embedded) {
+    app.use('*', logger())
+  }
   app.use('*', async (c: Context, next: Next) => {
     const path = new URL(c.req.url).pathname
     if (path.includes('//')) {
@@ -142,11 +152,28 @@ export async function startRcsServer(opts: RcsServerOptions): Promise<void> {
     hostname: host,
   })
 
+  // Port conflicts (EADDRINUSE) surface asynchronously as an 'error' event —
+  // without a listener the process crashes with an ugly unhandled error.
+  // Embedded mode keeps running (the REPL owns the process; the bridge will
+  // talk to whatever server already owns the port); standalone exits loudly.
+  server.on('error', (err: NodeJS.ErrnoException) => {
+    console.error(`[RCS] Server error: ${err.message}`)
+    if (!opts.embedded) {
+      // eslint-disable-next-line custom-rules/no-process-exit
+      process.exit(1)
+    }
+  })
+
   // Inject WebSocket support for Node.js
   injectWebSocket(server)
 
-  // Start disconnect monitor
-  startDisconnectMonitor()
+  // Start disconnect monitor. Unref'd: the HTTP server (standalone) or the
+  // host process (embedded) owns the event loop — the interval must not
+  // keep an exited REPL's process alive.
+  const monitorTimer = startDisconnectMonitor()
+  if (monitorTimer.unref) {
+    monitorTimer.unref()
+  }
 
   console.log(
     `[RCS] Remote Control Server starting on ${host}:${port} (Node.js)`,
@@ -192,6 +219,15 @@ export async function startRcsServer(opts: RcsServerOptions): Promise<void> {
     )
   }
 
+  // Embedded mode: the caller owns the process lifecycle (e.g. `slz rcs one`
+  // boots an in-process REPL as the single repl worker). No signal handlers
+  // — they would process.exit(0) on the REPL's first Ctrl+C — and no
+  // block-forever: return the bound coordinates so the caller can wire the
+  // in-process bridge + browser to it.
+  if (opts.embedded) {
+    return { port, host, webUiUrl: `http://${webUiHost}:${port}` }
+  }
+
   // Graceful shutdown
   function gracefulShutdown(signal: string) {
     console.log(`\n[RCS] Received ${signal}, shutting down...`)
@@ -205,6 +241,7 @@ export async function startRcsServer(opts: RcsServerOptions): Promise<void> {
   process.on('SIGINT', () => gracefulShutdown('SIGINT'))
   process.on('SIGTERM', () => gracefulShutdown('SIGTERM'))
 
-  // Block forever — server keeps running
-  await new Promise(() => {})
+  // Block forever — server keeps running. The promise never resolves; it
+  // only exists so the caller's await parks and the return type holds.
+  return new Promise<RcsServerInfo>(() => {})
 }

package/packages/remote-control-server/src/registerRoutes.ts

@@ -7,6 +7,11 @@ import { fileURLToPath } from 'node:url'
 import { createAcpApp } from './routes/acp'
 import { createSessionIngressApp } from './routes/v1/session-ingress'
 import { csrfCheck } from './auth/csrf'
+import { config } from './config'
+import { getDb } from './db/sqlite'
+import { issueSessionToken } from './auth/session'
+import { buildSessionCookies } from './auth/cookie'
+import { consumeWebLoginCode } from './services/web-login'
 
 // Routes
 import v1Artifacts from './routes/v1/artifacts'
@@ -134,6 +139,38 @@ export function registerRoutes(
     app.get(`${p}/*`, ss({ root: webDir, path: 'index.html' }))
   }
 
+  // GET /otp/:code — one-time browser login for `slz rcs one`.
+  //
+  // The CLI mints a single-use code in-process right before opening the
+  // browser (services/web-login.ts). The browser hits this route, the
+  // server sets the single admin's session cookies and redirects to the
+  // stored target path — typically /code/<sessionId>, so a fresh browser
+  // lands straight in the just-created session instead of the login page.
+  // Codes are 2-minute TTL and only exist in single-user mode; full mode
+  // keeps the username/password ceremony.
+  app.get('/otp/:code', async c => {
+    if (!config.singleUser) {
+      return c.json({ error: 'Not found' }, 404)
+    }
+    const record = consumeWebLoginCode(c.req.param('code')!)
+    if (!record) {
+      // Unknown/expired/used — the manual login page still works
+      // (single-user mode hints the default credentials there).
+      return c.redirect('/login')
+    }
+    const db = getDb()
+    const { accessToken, refreshToken } = issueSessionToken(record.userId, db)
+    const secure =
+      c.req.header('X-Forwarded-Proto') === 'https' ||
+      c.req.url.startsWith('https')
+    for (const cookie of buildSessionCookies(accessToken, refreshToken, {
+      secure,
+    })) {
+      c.header('Set-Cookie', cookie, { append: true })
+    }
+    return c.redirect(record.targetPath)
+  })
+
   // Root redirect → /code/ (main dashboard entry point)
   app.get('/', c => c.redirect('/code/'))
 }

package/packages/remote-control-server/src/services/disconnect-monitor.ts

@@ -51,8 +51,8 @@ export function runDisconnectMonitorSweep(now = Date.now()) {
   }
 }
 
-export function startDisconnectMonitor() {
-  setInterval(() => {
+export function startDisconnectMonitor(): ReturnType<typeof setInterval> {
+  return setInterval(() => {
     runDisconnectMonitorSweep()
   }, 60_000) // Check every minute
 }

package/packages/remote-control-server/src/services/web-login.ts

@@ -0,0 +1,96 @@
+import { randomUUID } from 'node:crypto'
+
+/**
+ * One-time browser login codes for single-user mode (`slz rcs one`).
+ *
+ * `slz rcs one` auto-opens the Web UI straight into the freshly created
+ * session — but a fresh browser has no session cookies, so a plain deep
+ * link would bounce off the login page. Instead the CLI mints a
+ * short-lived one-time code in-process (only the server process itself
+ * can mint one), the browser hits GET /otp/<code>, and the server sets
+ * the single admin's session cookies before redirecting to the stored
+ * target path (see registerRoutes.ts).
+ *
+ * Trust model: same as the rest of single-user mode — loopback binding,
+ * the API key is the only real credential, and the code is a random
+ * 122-bit value that is single-use and expires in two minutes. Codes
+ * live in memory only: a server restart invalidates any unspent ones.
+ */
+
+export interface WebLoginCodeRecord {
+  code: string
+  userId: string
+  /** Path the browser is redirected to after login (must start with '/'). */
+  targetPath: string
+  expiresAt: number
+}
+
+const CODE_TTL_MS = 2 * 60 * 1000
+/** Upper bound so a pathological minter can't grow the map forever. */
+export const MAX_PENDING_CODES = 64
+
+const pendingCodes = new Map<string, WebLoginCodeRecord>()
+
+function pruneExpired(now = Date.now()): void {
+  for (const [code, record] of pendingCodes) {
+    if (record.expiresAt <= now) {
+      pendingCodes.delete(code)
+    }
+  }
+}
+
+/** Clamp a redirect target to a same-origin path ('/…', never '//…'). */
+function toSafeTargetPath(targetPath: string): string {
+  return targetPath.startsWith('/') && !targetPath.startsWith('//')
+    ? targetPath
+    : '/'
+}
+
+/**
+ * Mint a one-time login code for a user + redirect target.
+ * The target path is clamped to a same-origin path — protocol-relative
+ * ('//host') and absolute URLs are rejected to block open redirects.
+ */
+export function issueWebLoginCode(
+  userId: string,
+  targetPath: string,
+): WebLoginCodeRecord {
+  pruneExpired()
+  if (pendingCodes.size >= MAX_PENDING_CODES) {
+    // Drop the oldest — Map preserves insertion order.
+    const oldest = pendingCodes.keys().next().value
+    if (oldest !== undefined) {
+      pendingCodes.delete(oldest)
+    }
+  }
+  const record: WebLoginCodeRecord = {
+    code: `wlc_${randomUUID().replace(/-/g, '')}`,
+    userId,
+    targetPath: toSafeTargetPath(targetPath),
+    expiresAt: Date.now() + CODE_TTL_MS,
+  }
+  pendingCodes.set(record.code, record)
+  return record
+}
+
+/**
+ * Consume a login code (single use). Returns null when the code is
+ * unknown, already used, or expired.
+ */
+export function consumeWebLoginCode(code: string): WebLoginCodeRecord | null {
+  pruneExpired()
+  const record = pendingCodes.get(code)
+  if (!record) {
+    return null
+  }
+  pendingCodes.delete(code)
+  if (record.expiresAt <= Date.now()) {
+    return null
+  }
+  return record
+}
+
+/** Test hook — clear all pending codes. */
+export function _resetWebLoginCodes(): void {
+  pendingCodes.clear()
+}