@thevinci/web 1.0.0

package/server/lib/scheduled-tasks/runtime.test.js

@@ -0,0 +1,100 @@
+import { describe, expect, it } from 'vitest';
+import { computeNextRunAt, formatScheduledSessionTitle, parseScheduledCommandPrompt } from './runtime.js';
+
+describe('scheduled-tasks runtime helpers', () => {
+  it('computes next daily run in timezone', () => {
+    const nowUtc = Date.UTC(2025, 0, 1, 8, 0, 0);
+    const next = computeNextRunAt({
+      enabled: true,
+      schedule: {
+        kind: 'daily',
+        times: ['09:30'],
+        timezone: 'UTC',
+      },
+    }, nowUtc);
+
+    expect(next).toBe(Date.UTC(2025, 0, 1, 9, 30, 0));
+  });
+
+  it('computes weekly next run using weekdays', () => {
+    // Monday 2025-01-06 10:00:00 UTC
+    const nowUtc = Date.UTC(2025, 0, 6, 10, 0, 0);
+    const next = computeNextRunAt({
+      enabled: true,
+      schedule: {
+        kind: 'weekly',
+        times: ['09:00'],
+        weekdays: [1, 3],
+        timezone: 'UTC',
+      },
+    }, nowUtc);
+
+    // Wednesday 2025-01-08 09:00:00 UTC
+    expect(next).toBe(Date.UTC(2025, 0, 8, 9, 0, 0));
+  });
+
+  it('picks nearest time from multiple daily times', () => {
+    const nowUtc = Date.UTC(2025, 0, 1, 9, 20, 0);
+    const next = computeNextRunAt({
+      enabled: true,
+      schedule: {
+        kind: 'daily',
+        times: ['09:15', '09:45', '18:00'],
+        timezone: 'UTC',
+      },
+    }, nowUtc);
+
+    expect(next).toBe(Date.UTC(2025, 0, 1, 9, 45, 0));
+  });
+
+  it('computes one-time next run for future date', () => {
+    const nowUtc = Date.UTC(2026, 3, 15, 10, 0, 0);
+    const next = computeNextRunAt({
+      enabled: true,
+      schedule: {
+        kind: 'once',
+        date: '2026-04-16',
+        time: '13:30',
+        timezone: 'UTC',
+      },
+    }, nowUtc);
+
+    expect(next).toBe(Date.UTC(2026, 3, 16, 13, 30, 0));
+  });
+
+  it('returns null for past one-time schedule', () => {
+    const nowUtc = Date.UTC(2026, 3, 16, 14, 0, 0);
+    const next = computeNextRunAt({
+      enabled: true,
+      schedule: {
+        kind: 'once',
+        date: '2026-04-16',
+        time: '13:30',
+        timezone: 'UTC',
+      },
+    }, nowUtc);
+
+    expect(next).toBeNull();
+  });
+
+  it('formats session title with timestamp suffix', () => {
+    const title = formatScheduledSessionTitle({
+      name: 'Morning Sync',
+      schedule: { timezone: 'UTC' },
+    }, Date.UTC(2025, 2, 10, 7, 5, 0));
+
+    expect(title).toBe('Morning Sync 2025-03-10 07:05');
+  });
+
+  it('parses slash command prompt for scheduled command mode', () => {
+    expect(parseScheduledCommandPrompt('/review src/components')).toEqual({
+      command: 'review',
+      arguments: 'src/components',
+    });
+  });
+
+  it('returns null when prompt is not a slash command', () => {
+    expect(parseScheduledCommandPrompt('Summarize open issues')).toBeNull();
+    expect(parseScheduledCommandPrompt('/')).toBeNull();
+  });
+});

package/server/lib/security/request-security.js

@@ -0,0 +1,115 @@
+export const createRequestSecurityRuntime = (deps) => {
+  const { readSettingsFromDiskMigrated } = deps;
+
+  const getUiSessionTokenFromRequest = (req) => {
+    const cookieHeader = req?.headers?.cookie;
+    if (!cookieHeader || typeof cookieHeader !== 'string') {
+      return null;
+    }
+    const segments = cookieHeader.split(';');
+    for (const segment of segments) {
+      const [rawName, ...rest] = segment.split('=');
+      const name = rawName?.trim();
+      if (!name) continue;
+      if (name !== 'oc_ui_session') continue;
+      const value = rest.join('=').trim();
+      try {
+        return decodeURIComponent(value || '');
+      } catch {
+        return value || null;
+      }
+    }
+    return null;
+  };
+
+  const rejectWebSocketUpgrade = (socket, statusCode, reason) => {
+    if (!socket || socket.destroyed) {
+      return;
+    }
+
+    const message = typeof reason === 'string' && reason.trim().length > 0 ? reason.trim() : 'Bad Request';
+    const body = Buffer.from(message, 'utf8');
+    const statusText = {
+      400: 'Bad Request',
+      401: 'Unauthorized',
+      403: 'Forbidden',
+      404: 'Not Found',
+      500: 'Internal Server Error',
+    }[statusCode] || 'Bad Request';
+
+    try {
+      socket.write(
+        `HTTP/1.1 ${statusCode} ${statusText}\r\n` +
+        'Connection: close\r\n' +
+        'Content-Type: text/plain; charset=utf-8\r\n' +
+        `Content-Length: ${body.length}\r\n\r\n`
+      );
+      socket.write(body);
+    } catch {
+    }
+
+    try {
+      socket.destroy();
+    } catch {
+    }
+  };
+
+  const getRequestOriginCandidates = async (req) => {
+    const origins = new Set();
+    const forwardedProto = typeof req.headers['x-forwarded-proto'] === 'string'
+      ? req.headers['x-forwarded-proto'].split(',')[0].trim().toLowerCase()
+      : '';
+    const protocol = forwardedProto || (req.socket?.encrypted ? 'https' : 'http');
+
+    const forwardedHost = typeof req.headers['x-forwarded-host'] === 'string'
+      ? req.headers['x-forwarded-host'].split(',')[0].trim()
+      : '';
+    const host = forwardedHost || (typeof req.headers.host === 'string' ? req.headers.host.trim() : '');
+
+    if (host) {
+      origins.add(`${protocol}://${host}`);
+      const [hostname, port] = host.split(':');
+      const normalizedHost = typeof hostname === 'string' ? hostname.toLowerCase() : '';
+      const portSuffix = typeof port === 'string' && port.length > 0 ? `:${port}` : '';
+      if (normalizedHost === 'localhost') {
+        origins.add(`${protocol}://127.0.0.1${portSuffix}`);
+        origins.add(`${protocol}://[::1]${portSuffix}`);
+      } else if (normalizedHost === '127.0.0.1' || normalizedHost === '[::1]') {
+        origins.add(`${protocol}://localhost${portSuffix}`);
+      }
+    }
+
+    try {
+      const settings = await readSettingsFromDiskMigrated();
+      if (typeof settings?.publicOrigin === 'string' && settings.publicOrigin.trim().length > 0) {
+        origins.add(new URL(settings.publicOrigin.trim()).origin);
+      }
+    } catch {
+    }
+
+    return origins;
+  };
+
+  const isRequestOriginAllowed = async (req) => {
+    const originHeader = typeof req.headers.origin === 'string' ? req.headers.origin.trim() : '';
+    if (!originHeader) {
+      return false;
+    }
+
+    let normalizedOrigin = '';
+    try {
+      normalizedOrigin = new URL(originHeader).origin;
+    } catch {
+      return false;
+    }
+
+    const allowedOrigins = await getRequestOriginCandidates(req);
+    return allowedOrigins.has(normalizedOrigin);
+  };
+
+  return {
+    getUiSessionTokenFromRequest,
+    rejectWebSocketUpgrade,
+    isRequestOriginAllowed,
+  };
+};

package/server/lib/session-folders/routes.js

@@ -0,0 +1,63 @@
+const MAX_BODY_BYTES = 4 * 1024 * 1024;
+
+export const registerSessionFoldersRoutes = (app, dependencies) => {
+  const {
+    fsPromises,
+    path,
+    vinciDataDir,
+  } = dependencies;
+
+  const filePath = path.join(vinciDataDir, 'sessions-directories.json');
+
+  const ensureDir = async () => {
+    await fsPromises.mkdir(path.dirname(filePath), { recursive: true });
+  };
+
+  app.get('/api/session-folders', async (_req, res) => {
+    try {
+      const raw = await fsPromises.readFile(filePath, 'utf8').catch((error) => {
+        if (error && error.code === 'ENOENT') return null;
+        throw error;
+      });
+      if (!raw) {
+        return res.json({ version: 1, foldersMap: {}, collapsedFolderIds: [], updatedAt: 0 });
+      }
+      try {
+        const parsed = JSON.parse(raw);
+        return res.json(parsed);
+      } catch {
+        return res.json({ version: 1, foldersMap: {}, collapsedFolderIds: [], updatedAt: 0 });
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : 'Failed to read session folders';
+      return res.status(500).json({ error: message });
+    }
+  });
+
+  app.post('/api/session-folders', async (req, res) => {
+    const body = req.body;
+    if (!body || typeof body !== 'object' || Array.isArray(body)) {
+      return res.status(400).json({ error: 'Body must be an object' });
+    }
+    const serialized = JSON.stringify(body, null, 2);
+    if (Buffer.byteLength(serialized, 'utf8') > MAX_BODY_BYTES) {
+      return res.status(413).json({ error: 'Payload too large' });
+    }
+    let tmp;
+    let saved = false;
+    try {
+      await ensureDir();
+      tmp = `${filePath}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+      await fsPromises.writeFile(tmp, serialized, 'utf8');
+      await fsPromises.rename(tmp, filePath);
+      saved = true;
+      return res.json({ success: true });
+    } catch (error) {
+      if (tmp && !saved) {
+        await fsPromises.unlink(tmp).catch(() => {});
+      }
+      const message = error instanceof Error ? error.message : 'Failed to write session folders';
+      return res.status(500).json({ error: message });
+    }
+  });
+};

package/server/lib/session-folders/routes.test.js

@@ -0,0 +1,102 @@
+import { describe, expect, it, vi } from 'vitest';
+import path from 'path';
+
+import { registerSessionFoldersRoutes } from './routes.js';
+
+const createRouteRegistry = () => {
+  const routes = new Map();
+
+  return {
+    app: {
+      get(routePath, handler) {
+        routes.set(`GET ${routePath}`, handler);
+      },
+      post(routePath, handler) {
+        routes.set(`POST ${routePath}`, handler);
+      },
+    },
+    getRoute(method, routePath) {
+      return routes.get(`${method} ${routePath}`);
+    },
+  };
+};
+
+const createMockResponse = () => {
+  let statusCode = 200;
+  let body = null;
+
+  return {
+    status(code) {
+      statusCode = code;
+      return this;
+    },
+    json(payload) {
+      body = payload;
+      return this;
+    },
+    get statusCode() {
+      return statusCode;
+    },
+    get body() {
+      return body;
+    },
+  };
+};
+
+describe('session folders routes', () => {
+  it('uses unique temp files for concurrent saves', async () => {
+    const { app, getRoute } = createRouteRegistry();
+    const tempPaths = [];
+    const fsPromises = {
+      mkdir: vi.fn(async () => {}),
+      writeFile: vi.fn(async (tempPath) => {
+        tempPaths.push(tempPath);
+        await new Promise((resolve) => setTimeout(resolve, 0));
+      }),
+      rename: vi.fn(async () => {}),
+    };
+
+    registerSessionFoldersRoutes(app, {
+      fsPromises,
+      path,
+      vinciDataDir: '/tmp/vinci-test',
+    });
+
+    const handler = getRoute('POST', '/api/session-folders');
+
+    await Promise.all([
+      handler({ body: { version: 1, updatedAt: 1 } }, createMockResponse()),
+      handler({ body: { version: 1, updatedAt: 2 } }, createMockResponse()),
+    ]);
+
+    expect(tempPaths).toHaveLength(2);
+    expect(new Set(tempPaths).size).toBe(2);
+    expect(tempPaths.every((tempPath) => tempPath.includes('sessions-directories.json.tmp-'))).toBe(true);
+  });
+
+  it('removes the temp file when rename fails', async () => {
+    const { app, getRoute } = createRouteRegistry();
+    const fsPromises = {
+      mkdir: vi.fn(async () => {}),
+      writeFile: vi.fn(async () => {}),
+      rename: vi.fn(async () => {
+        throw new Error('rename failed');
+      }),
+      unlink: vi.fn(async () => {}),
+    };
+
+    registerSessionFoldersRoutes(app, {
+      fsPromises,
+      path,
+      vinciDataDir: '/tmp/vinci-test',
+    });
+
+    const handler = getRoute('POST', '/api/session-folders');
+    const response = createMockResponse();
+
+    await handler({ body: { version: 1, updatedAt: 1 } }, response);
+
+    expect(response.statusCode).toBe(500);
+    expect(fsPromises.unlink).toHaveBeenCalledWith(expect.stringContaining('sessions-directories.json.tmp-'));
+  });
+});

package/server/lib/skills-catalog/DOCUMENTATION.md

@@ -0,0 +1,178 @@
+# Skills Catalog Module Documentation
+
+## Purpose
+This module provides skill discovery, scanning, and installation capabilities for OpenCode. It supports multiple skill sources including git repositories and the ClawdHub registry, with caching and conflict resolution for skill installation.
+
+## Entrypoints and structure
+- `packages/web/server/lib/skills-catalog/`: Skills catalog module directory containing all skill-related functionality.
+  - `cache.js`: In-memory cache for scan results with TTL support.
+  - `curated-sources.js`: Predefined skill sources (Anthropic, ClawdHub).
+  - `git.js`: Git operations helpers for cloning and auth error detection.
+  - `install.js`: Skills installation from git repositories.
+  - `scan.js`: Skills scanning from git repositories.
+  - `source.js`: Source string parsing for git repositories.
+  - `clawdhub/`: ClawdHub registry integration.
+    - `index.js`: Public API exports for ClawdHub.
+    - `scan.js`: Scanning ClawdHub registry with pagination.
+    - `install.js`: Installation from ClawdHub (ZIP download).
+    - `api.js`: ClawdHub API client with rate limiting.
+
+## Public API
+
+The following functions are exported and used by the web server:
+
+### Cache (`cache.js`)
+- `getCacheKey({ normalizedRepo, subpath, identityId })`: Generate cache key for scan results.
+- `getCachedScan(key)`: Retrieve cached scan result if not expired.
+- `setCachedScan(key, value, ttlMs)`: Store scan result with TTL (default 30 minutes).
+- `clearCache()`: Clear all cached scan results.
+
+### Curated Sources (`curated-sources.js`)
+- `getCuratedSkillsSources()`: Return list of curated skill sources (Anthropic, ClawdHub).
+- `CURATED_SKILLS_SOURCES`: Constant array of predefined sources.
+
+### Source Parsing (`source.js`)
+- `parseSkillRepoSource(source, { subpath })`: Parse git repository source string into structured object with SSH/HTTPS clone URLs, normalized repo, and effective subpath. Supports SSH URLs, HTTPS URLs, and shorthand `owner/repo[/subpath]` format.
+
+### Git Repository Scanning (`scan.js`)
+- `scanSkillsRepository({ source, subpath, defaultSubpath, identity })`: Scan git repository for skills by cloning and analyzing SKILL.md files. Returns array of skill items with metadata.
+
+### Git Repository Installation (`install.js`)
+- `installSkillsFromRepository({ source, subpath, defaultSubpath, identity, scope, targetSource, workingDirectory, userSkillDir, selections, conflictPolicy, conflictDecisions })`: Install skills from git repository. Supports user/project scopes, opencode/agents targets, conflict resolution (prompt/skipAll/overwriteAll), and sparse checkout for efficiency.
+
+### ClawdHub Integration (`clawdhub/index.js`)
+- `isClawdHubSource(source)`: Check if source string refers to ClawdHub.
+- `scanClawdHub()`: Scan entire ClawdHub registry for all skills (paginated, max 20 pages).
+- `scanClawdHubPage({ cursor })`: Scan a single page of ClawdHub results with cursor-based pagination.
+- `installSkillsFromClawdHub({ scope, targetSource, workingDirectory, userSkillDir, selections, conflictPolicy, conflictDecisions })`: Install skills from ClawdHub by downloading ZIP files.
+- `fetchClawdHubSkills({ cursor })`: Fetch paginated skills list from ClawdHub API.
+- `fetchClawdHubSkillVersion(slug, version)`: Fetch specific skill version details.
+- `fetchClawdHubSkillInfo(slug)`: Fetch skill metadata without version details.
+- `downloadClawdHubSkill(slug, version)`: Download skill package as ZIP buffer.
+
+### ClawdHub Constants (`clawdhub/index.js`)
+- `CLAWDHUB_SOURCE_ID`: Source identifier for curated sources.
+- `CLAWDHUB_SOURCE_STRING`: Source string format.
+
+## Internal Helpers
+
+The following functions are internal helpers used by exported functions:
+
+### Git Helpers (`git.js`)
+- `runGit(args, options)`: Execute git command with optional SSH identity, timeout, and max buffer. Returns `{ ok, stdout, stderr, message, code, signal }`.
+- `looksLikeAuthError(message)`: Detect if error message indicates authentication failure (permission denied, publickey, etc.).
+- `assertGitAvailable()`: Check if git is available in PATH.
+
+### Skill Name Validation (used in `install.js`, `scan.js`, `clawdhub/install.js`)
+- `validateSkillName(skillName)`: Validate skill name against pattern `/^[a-z0-9][a-z0-9-]*[a-z0-9]$|^[a-z0-9]$/` (1-64 chars, lowercase alphanumeric with hyphens).
+
+### File System Helpers (`install.js`, `scan.js`, `clawdhub/install.js`)
+- `safeRm(dir)`: Safely remove directory recursively (ignores errors).
+- `ensureDir(dirPath)`: Ensure directory exists with recursive creation.
+- `copyDirectoryNoSymlinks(srcDir, dstDir)`: Copy directory contents without symlinks, with path traversal protection.
+- `normalizeUserSkillDir(userSkillDir)`: Normalize user skill directory path (handles legacy `~/.config/opencode/skill` → `~/.config/opencode/skills` migration).
+
+### Git Clone Helpers (`install.js`, `scan.js`)
+- `cloneRepo({ cloneUrl, identity, tempDir })`: Clone git repository with preferred partial clone (`--filter=blob:none`) and fallback. Uses non-interactive mode.
+
+### SKILL.md Parsing (`scan.js`)
+- `parseSkillMd(content)`: Parse YAML frontmatter from SKILL.md content. Returns `{ ok, frontmatter, warnings }`.
+
+### Path Helpers (`install.js`)
+- `toFsPath(repoDir, repoRelPosixPath)`: Convert POSIX path to filesystem path.
+- `getTargetSkillDir({ scope, targetSource, workingDirectory, userSkillDir, skillName })`: Determine target installation directory based on scope (user/project), targetSource (opencode/agents), and skill name.
+
+### ClawdHub API Helpers (`clawdhub/api.js`)
+- `rateLimitedFetch(url, options)`: Fetch with rate limiting (120 req/min limit, 100ms delay between requests, exponential backoff on 429/500 errors).
+- `mapClawdHubItem(item)`: Transform ClawdHub API response to SkillsCatalogItem format.
+
+## Response Contracts
+
+### Scan Skills Repository Response
+- `ok`: Boolean indicating success.
+- `normalizedRepo`: Normalized repo string (`owner/repo`).
+- `effectiveSubpath`: Effective subpath used for scanning (may be from source string or defaultSubpath).
+- `items`: Array of skill items with `{ repoSource, repoSubpath, skillDir, skillName, frontmatterName, description, installable, warnings }`.
+- `error`: Error object with `{ kind, message }` on failure.
+
+### Install Skills Response
+- `ok`: Boolean indicating success.
+- `installed`: Array of installed skills with `{ skillName, scope, source }`.
+- `skipped`: Array of skipped skills with `{ skillName, reason }`.
+- `error`: Error object with `{ kind, message, conflicts? }` on failure. Kinds: `authRequired`, `networkError`, `conflicts`, `invalidSource`, `unknown`.
+
+### ClawdHub Scan Response
+- `ok`: Boolean indicating success.
+- `items`: Array of skill items with ClawdHub-specific metadata in `clawdhub` property.
+- `nextCursor`: Pagination cursor for next page (only for `scanClawdHubPage`).
+- `error`: Error object with `{ kind, message }` on failure.
+
+### Parse Source Response
+- `ok`: Boolean indicating success.
+- `host`: Git host (e.g., `github.com`, `gitlab.com`).
+- `owner`: Repository owner.
+- `repo`: Repository name.
+- `cloneUrlSsh`: SSH clone URL.
+- `cloneUrlHttps`: HTTPS clone URL.
+- `effectiveSubpath`: Subpath for scanning (from source string or options).
+- `normalizedRepo`: Normalized repo string (`owner/repo`).
+- `error`: Error object with `{ kind, message }` on failure.
+
+## Notes for Contributors
+
+### Adding a New Skill Source
+1. Create a new subdirectory under `packages/web/server/lib/skills-catalog/` (e.g., `newsource/`).
+2. Implement `scan.js` with a function that returns `{ ok, items, error? }` matching the SkillsCatalogItem contract.
+3. Implement `install.js` with a function that accepts selections and returns `{ ok, installed, skipped, error? }`.
+4. Add the source to `CURATED_SKILLS_SOURCES` in `curated-sources.js` if it should appear in the default catalog.
+5. Update `packages/web/server/index.js` to import and wire up the new source.
+
+### Skill Name Validation
+- All skill names must match `/^[a-z0-9][a-z0-9-]*[a-z0-9]$|^[a-z0-9]$/` (1-64 chars).
+- Skill names are derived from directory basenames for git repos and slugs for ClawdHub.
+- Invalid names result in non-installable skills with appropriate warnings.
+
+### Git Cloning Strategy
+- Use sparse checkout to minimize clone size: `sparse-checkout init`, `sparse-checkout set`, `checkout HEAD`.
+- Preferred clone uses `--depth=1 --filter=blob:none` for partial clone with fallback to `--depth=1`.
+- Always use non-interactive mode (`GIT_TERMINAL_PROMPT=0`) to avoid hangs.
+- SSH keys are injected via `core.sshCommand` in git config.
+
+### Conflict Resolution
+- Installation checks for existing skills before downloading/cloning.
+- Three conflict policies: `prompt`, `skipAll`, `overwriteAll`.
+- Per-skill decisions override global policy via `conflictDecisions` map.
+- Conflict response includes `{ skillName, scope, source }` for each conflict.
+
+### ClawdHub Integration
+- ClawdHub API base URL: `https://clawdhub.com/api/v1`.
+- Pagination uses cursor-based approach with `MAX_PAGES=20` safety limit.
+- Rate limiting: 120 req/min with 100ms delay between requests.
+- Downloaded skills are extracted from ZIP files using `adm-zip`.
+- Always validate `SKILL.md` exists before installation.
+
+### Cache Management
+- Cache keys include `normalizedRepo`, `subpath`, and `identityId` for isolation.
+- Default TTL is 30 minutes; can be overridden via `ttlMs` parameter.
+- Cache is in-memory (not persisted across restarts).
+
+### Security Considerations
+- Path traversal protection in `copyDirectoryNoSymlinks`: resolves real paths and checks containment.
+- Symlinks are explicitly rejected to prevent escape from skill directory.
+- SSH key paths are trimmed but not escaped in `git.js` (assumes safe input from profiles).
+- Temporary directories are cleaned up in `finally` blocks.
+
+### Error Handling
+- All exported functions return `{ ok, ... }` result objects, not throw.
+- Error kinds: `authRequired`, `networkError`, `conflicts`, `invalidSource`, `unknown`.
+- Use `looksLikeAuthError` to detect SSH/HTTPS auth failures for better UX.
+- Log errors to console for debugging but return structured errors to callers.
+
+### Testing
+- Run `bun run type-check`, `bun run lint`, and `bun run build` before finalizing changes.
+- Consider edge cases: non-existent repos, private repos without auth, missing SKILL.md files, invalid skill names, conflicts, network failures.
+
+## Verification Commands
+- Type-check: `bun run type-check`
+- Lint: `bun run lint`
+- Build: `bun run build`

package/server/lib/skills-catalog/cache.js

@@ -0,0 +1,29 @@
+const DEFAULT_TTL_MS = 30 * 60 * 1000;
+
+const cache = new Map();
+
+export function getCacheKey({ normalizedRepo, subpath, identityId }) {
+  const safeRepo = String(normalizedRepo || '').trim();
+  const safeSubpath = String(subpath || '').trim();
+  const safeIdentity = String(identityId || '').trim();
+  return `${safeRepo}::${safeSubpath}::${safeIdentity}`;
+}
+
+export function getCachedScan(key) {
+  const entry = cache.get(key);
+  if (!entry) return null;
+  if (Date.now() >= entry.expiresAt) {
+    cache.delete(key);
+    return null;
+  }
+  return entry.value;
+}
+
+export function setCachedScan(key, value, ttlMs = DEFAULT_TTL_MS) {
+  const ttl = Number.isFinite(ttlMs) ? ttlMs : DEFAULT_TTL_MS;
+  cache.set(key, { expiresAt: Date.now() + ttl, value });
+}
+
+export function clearCache() {
+  cache.clear();
+}