artifacty 0.4.0 → 0.6.0

package/README.md

@@ -27,37 +27,43 @@ artifacty --help
 Run it without a global install:
 
 ```bash
-npx artifacty@latest serve
+npx artifacty@latest serve --foreground
 ```
 
-Start the local dashboard:
+Start the local dashboard in the background:
 
 ```bash
 artifacty serve
 ```
 
-Open the URL printed by the server. Artifacty prefers `http://127.0.0.1:8787`; if that default port is busy and no explicit port was configured, it starts on the next available local port and records the actual URL for CLI and MCP responses.
+Open the `url` printed in the JSON response. Artifacty prefers `http://127.0.0.1:8787`; if that default port is busy and no explicit port was configured, it starts on the next available local port and records the actual URL for CLI and MCP responses.
 
-Run it in the background and return to your prompt:
+Manage the background server:
 
 ```bash
-artifacty start
 artifacty status
 artifacty stop
 ```
 
-`artifacty serve --detach` is equivalent to `artifacty start`. Logs are written under `~/.artifacty/logs/`.
+`artifacty start` and `artifacty serve --detach` use the same lifecycle path as `artifacty serve`. Logs are written under `~/.artifacty/logs/`.
 These lifecycle commands use Node's detached process support and work on macOS, Linux, and Windows. `artifacty stop` uses Windows `taskkill` on Windows and process-group signals on macOS/Linux.
 
+For foreground debugging, keep the process attached:
+
+```bash
+artifacty serve --foreground
+npm start
+```
+
 Generate an API token at startup when you want to protect HTTP API and browser write routes:
 
 ```bash
 artifacty serve --generate-token
 artifacty serve --host 0.0.0.0 --share-mode lan --generate-token
-npm start -- --generate-token
+artifacty serve --foreground --generate-token
 ```
 
-The server prints the generated token plus `/new?token=...` and `/import?token=...` URLs. For scripts or background services that need a stable token, generate one first:
+Background `serve` returns the generated token and ready-to-open `/new?token=...` and `/import?token=...` URLs in JSON. Foreground `serve` prints the same values to stderr. For scripts or long-running services that need a stable token, generate one first:
 
 ```bash
 artifacty token
@@ -216,11 +222,11 @@ artifacty integrity
 
 ## API Example
 
-Start a protected server in another terminal, or generate a reusable shell token first:
+Start a protected server with a reusable shell token:
 
 ```bash
-artifacty serve --generate-token
 export ARTIFACTY_API_TOKEN="$(artifacty token --raw)"
+artifacty serve --api-token "$ARTIFACTY_API_TOKEN"
 ```
 
 ```bash
@@ -285,9 +291,11 @@ Schema and storage:
 ## Security Model
 
 - The HTTP server binds to `127.0.0.1` by default.
-- If `ARTIFACTY_API_TOKEN` is set, HTTP API routes require `Authorization: Bearer <token>` or `x-artifacty-token`.
+- If `ARTIFACTY_API_TOKEN` is set, HTTP API routes require `Authorization: Bearer <token>` or `x-artifacty-token`; scripts should prefer headers over `?token=...` URLs.
+- API token checks use timing-safe digest comparison.
 - Binding outside localhost requires both `ARTIFACTY_SHARE_MODE=lan` or `team` and `ARTIFACTY_API_TOKEN`.
 - Non-local sharing is intended for trusted LAN or VPN sessions. Prefer a specific interface IP over `0.0.0.0`, keep React rendering disabled, and see [docs/network-sharing.md](docs/network-sharing.md).
+- Non-local binding prints a startup warning because Artifacty does not terminate TLS.
 - Artifact content is scanned for common API keys and private keys before storage. Use `--allow-secrets` or `ARTIFACTY_ALLOW_SECRETS=true` only for intentional exceptions.
 - Creates, updates, reads, imports, archives, and restores write audit events to SQLite.
 - CodeMirror editor/viewer and renderer assets are served from local npm dependencies through a package allowlist, not from a public CDN. JavaScript asset routes answer `Origin: null` requests with `Access-Control-Allow-Origin: null` so sandboxed renderer iframes can import local ESM without `allow-same-origin`.
@@ -300,5 +308,6 @@ Schema and storage:
 - CSV artifacts render as an escaped, bounded table; `/raw` preserves the original text.
 - Image and video artifacts store base64 media inline, render safe previews, and decode bytes through `/raw`.
 - Artifact content should still be treated as untrusted; use the raw view when handing content back to an agent.
+- npm releases are published with GitHub Actions OIDC Trusted Publishing after lint, test, and smoke checks pass.
 
-See [docs/release-checklist.md](docs/release-checklist.md) before publishing or running a shared instance.
+See [SECURITY.md](SECURITY.md), [docs/threat-model.md](docs/threat-model.md), and [docs/release-checklist.md](docs/release-checklist.md) before publishing or running a shared instance.

package/SECURITY.md

@@ -0,0 +1,49 @@
+# Security Policy
+
+## Supported Versions
+
+Artifacty is pre-1.0. Security fixes are provided for the latest published
+minor release. Upgrade to the latest `artifacty` version before reporting a
+suspected issue.
+
+## Reporting a Vulnerability
+
+Use GitHub private vulnerability reporting if it is enabled for this repository.
+If private reporting is unavailable, open a GitHub issue with a minimal summary
+and avoid including exploit details, secrets, private artifacts, or sensitive
+network information.
+
+Please include:
+
+- Artifacty version and install method.
+- Node.js version and operating system.
+- Whether the HTTP server was localhost-only, LAN/team mode, or behind a proxy.
+- Whether `ARTIFACTY_API_TOKEN` and `ARTIFACTY_ENABLE_REACT_RENDERER` were set.
+- Reproduction steps using non-sensitive sample content.
+
+## Security Model
+
+Artifacty is local-first. The default HTTP server binds to `127.0.0.1`; binding
+outside loopback requires `ARTIFACTY_SHARE_MODE=lan|team` and an API token.
+
+The project treats artifact content as untrusted:
+
+- HTML, SVG, Mermaid, and React rendering use sandboxed frames and scoped CSP.
+- React execution is disabled unless `ARTIFACTY_ENABLE_REACT_RENDERER=true`.
+- Mutating browser routes reject non-local `Origin` headers.
+- API token checks use constant-time digest comparison.
+- Artifact content is scanned for common API keys and private keys before
+  storage unless explicitly allowed.
+
+Artifacty does not provide TLS termination, remote OAuth, multi-user access
+control, or a hosted sync service. Do not expose the server directly to the
+public internet.
+
+## Supply Chain
+
+npm releases are published through GitHub Actions using npm Trusted Publishing
+OIDC. The release workflow runs lint, tests, and smoke checks on supported Node
+versions before publishing.
+
+See [docs/threat-model.md](docs/threat-model.md) and
+[docs/network-sharing.md](docs/network-sharing.md) for operational guidance.

package/docs/integrations.md

@@ -13,22 +13,23 @@ The dashboard prefers `http://127.0.0.1:8787`. If that port is busy and no expli
 Use a generated startup token when running a protected foreground server:
 
 ```bash
-node src/cli.js serve --generate-token
-node src/cli.js serve --host 0.0.0.0 --share-mode lan --generate-token
+node src/cli.js serve --foreground --generate-token
+node src/cli.js serve --foreground --host 0.0.0.0 --share-mode lan --generate-token
 npm start -- --generate-token
 ```
 
-The generated token is printed with ready-to-open create and import URLs.
+Foreground runs print the generated token with ready-to-open create and import URLs. Background runs return the same values in JSON.
 
 For prompt-friendly local background runs, use the lifecycle commands:
 
 ```bash
+node src/cli.js serve --port 8787
 node src/cli.js start --port 8787
 node src/cli.js status
 node src/cli.js stop
 ```
 
-`serve --detach` uses the same detached-process path as `start`. It writes `server.pid`, `server.json`, and logs under `ARTIFACTY_HOME` (default `~/.artifacty`). Prefer `start --api-token "$(node src/cli.js token --raw)"` when a background server needs API protection, because generated startup tokens are only visible in the server log.
+`serve`, `serve --detach`, and `start` use the same detached-process path. They write `server.pid`, `server.json`, and logs under `ARTIFACTY_HOME` (default `~/.artifacty`). `serve --generate-token` and `start --generate-token` generate the API token in the parent CLI process and return it in JSON along with ready-to-open create/import URLs. Use `serve --foreground` when you want attached logs for debugging.
 
 The lifecycle commands are intended to be cross-platform:
 
@@ -105,7 +106,7 @@ Generate a token for protected HTTP routes:
 node src/cli.js token
 node src/cli.js serve --generate-token
 npm start -- --generate-token
-ARTIFACTY_API_TOKEN="$(node src/cli.js token --raw)" node src/cli.js serve
+ARTIFACTY_API_TOKEN="$(node src/cli.js token --raw)" node src/cli.js serve --foreground
 ```
 
 ## Claude Code
@@ -308,7 +309,7 @@ node src/cli.js service install
 
 The generated service runs `src/server.js` with explicit `--host` and `--home` arguments. It includes `--port` only when you configure a port, which keeps the default port fallback available. Load or unload it manually with the `launchctl` commands returned by `service install`.
 
-For background services, prefer a stable `ARTIFACTY_API_TOKEN` in the service environment. `serve --generate-token` is intended for foreground runs where the operator can read the generated token from startup output.
+For background services, prefer a stable `ARTIFACTY_API_TOKEN` in the service environment. `serve --generate-token` is intended for temporary interactive sessions; the parent CLI returns the generated token in JSON.
 
 ## Backup and Audit
 

package/docs/network-sharing.md

@@ -30,6 +30,8 @@ The generated token protects HTTP API routes and browser write forms. Prefer the
 
 Artifacty does not terminate TLS. Do not expose it directly on the public internet. If a shared instance must cross an untrusted network, put it behind a TLS reverse proxy or a private VPN.
 
+When Artifacty binds outside loopback, startup output includes a warning that the server is reachable beyond the local machine and that TLS is not provided by Artifacty. Background `serve` returns this warning in JSON; foreground `serve` and `src/server.js` also write it to stderr.
+
 ## Browser Write Behavior
 
 Remote browsers can read shared pages, but write actions are intentionally conservative. Mutating browser routes reject non-local `Origin` headers to reduce CSRF risk. For LAN sharing, prefer API or MCP writes with an explicit token header.
@@ -39,3 +41,5 @@ Do not relax the origin check just to make remote browser writes easier. A futur
 ## Renderer Guidance
 
 Artifact content is untrusted. HTML, SVG, Mermaid, and React artifacts are rendered with sandboxing and CSP controls, but shared viewing still means content reaches another user's browser. Keep `ARTIFACTY_ENABLE_REACT_RENDERER` disabled for LAN sessions unless every viewer trusts the artifact source.
+
+See [threat-model.md](threat-model.md) for the full trust-boundary summary.

package/docs/release-checklist.md

@@ -8,7 +8,7 @@ Use this checklist before publishing or distributing Artifacty.
 npm run release:check
 ```
 
-This runs syntax checks, the full Node test suite, and a local smoke test that starts the HTTP server with token auth enabled, creates an artifact, verifies secret blocking, reads audit logs, writes a backup, and checks MCP tool discovery.
+This runs syntax checks, the full Node test suite, and a local smoke test that starts the HTTP server with token auth enabled, creates an artifact, verifies secret blocking, reads audit logs, writes a backup, and checks MCP tool/resource/prompt discovery.
 
 ## Packaging
 
@@ -23,7 +23,11 @@ This runs syntax checks, the full Node test suite, and a local smoke test that s
 
 - Keep the default HTTP bind address at `127.0.0.1`.
 - Require `ARTIFACTY_API_TOKEN` and `ARTIFACTY_SHARE_MODE=lan` or `team` before binding to `0.0.0.0`.
+- Confirm non-loopback startup output includes the LAN/team warning.
+- Confirm `artifacty serve` starts a managed background server and returns prompt-friendly JSON; use `artifacty serve --foreground` for attached log checks.
+- Prefer `x-artifacty-token` or `Authorization: Bearer <token>` over query tokens in scripts.
 - Review secret-scan bypasses. `--allow-secrets` and `ARTIFACTY_ALLOW_SECRETS=true` should be deliberate and temporary.
+- Review [../SECURITY.md](../SECURITY.md) and [threat-model.md](threat-model.md) when changing auth, rendering, MCP, or network-sharing behavior.
 - Treat artifact HTML and imported agent payloads as untrusted content.
 - Confirm scripted artifact iframes never include `allow-same-origin`.
 - Confirm `/assets/*` and `/vendor/npm/*` JavaScript responses return
@@ -35,6 +39,8 @@ This runs syntax checks, the full Node test suite, and a local smoke test that s
   not prove Mermaid or React rendered inside the iframe.
 - Keep `ARTIFACTY_ENABLE_REACT_RENDERER` disabled by default. Enable it only when the operator accepts arbitrary component execution risk.
 - Confirm parent app CSP does not include `unsafe-eval`; it should appear only on the React frame response CSP.
+- Confirm CodeQL, Scorecard, and Dependabot configuration changes are intentional.
+- Confirm npm publish still uses OIDC Trusted Publishing rather than a long-lived npm token.
 
 ## Operations
 

package/docs/threat-model.md

@@ -0,0 +1,128 @@
+# Threat Model
+
+Artifacty is a local artifact exchange for LLM agents. It is designed for one
+operator, one local store, and trusted local MCP clients by default.
+
+## Assets
+
+- Artifact content, including generated code, reports, screenshots, and media.
+- Artifact metadata, tags, audit records, and version history.
+- API tokens and generated startup tokens.
+- Local MCP client configuration files.
+- The Artifacty SQLite database and immutable version files.
+
+## Trust Boundaries
+
+- **HTTP browser server**: local by default, optionally reachable on LAN/team
+  networks when explicitly configured.
+- **MCP stdio server**: local process launched by an MCP client. It inherits the
+  local user account's filesystem permissions.
+- **Artifact renderers**: untrusted content is rendered inside browser sandbox
+  boundaries where practical.
+- **Storage**: Artifacty stores content under `ARTIFACTY_HOME`; anyone with
+  filesystem access to that directory can read artifacts.
+- **npm package**: published through GitHub Actions OIDC after automated checks.
+
+## Primary Threats and Controls
+
+### Accidental Network Exposure
+
+Risk: binding to `0.0.0.0` exposes Artifacty on every interface, including VPNs
+or cloud VM public interfaces.
+
+Controls:
+
+- Default host is `127.0.0.1`.
+- Non-loopback binding requires `ARTIFACTY_SHARE_MODE=lan|team`.
+- Non-loopback binding also requires `ARTIFACTY_API_TOKEN`.
+- Startup logs warn when the server binds outside loopback.
+
+Guidance: prefer a specific private interface IP over `0.0.0.0`. Do not expose
+Artifacty directly to the public internet.
+
+### Token Leakage
+
+Risk: query-string tokens can appear in browser history, shell history, logs, or
+referrers.
+
+Controls:
+
+- Scripts should use `x-artifacty-token` or `Authorization: Bearer <token>`.
+- Browser form token URLs exist only for local convenience.
+- Token comparisons use timing-safe digest comparison.
+
+Guidance: rotate tokens after sharing sessions, prefer header-based tokens for
+scripts, and use generated startup tokens only for temporary interactive shares.
+
+### Cross-Site Request Forgery
+
+Risk: a remote website could attempt to submit writes to an Artifacty server
+reachable from the user's browser.
+
+Controls:
+
+- Mutating browser routes reject non-local `Origin` headers.
+- API routes require a token when configured.
+- LAN/team mode does not relax browser-origin checks.
+
+### Untrusted Artifact Rendering
+
+Risk: HTML, SVG, Mermaid, or React content could execute code in a viewer's
+browser.
+
+Controls:
+
+- HTML artifacts render in sandboxed iframes.
+- SVG artifacts render in scriptless sandboxed iframes after viewer-side
+  sanitization.
+- Mermaid renders in a sandboxed iframe without `allow-same-origin`.
+- React is source-only unless `ARTIFACTY_ENABLE_REACT_RENDERER=true`.
+- React rendering, when enabled, runs in a separate sandboxed frame with
+  frame-scoped CSP.
+
+Guidance: keep React rendering disabled for shared sessions unless all viewers
+trust the source.
+
+### Secret Storage
+
+Risk: agents may accidentally publish API keys or private keys into artifacts.
+
+Controls:
+
+- Common API key and private key patterns are scanned before storage.
+- Writes fail unless `allowSecrets` or `ARTIFACTY_ALLOW_SECRETS=true` is set.
+- Stored scan status is recorded in version metadata.
+
+Limitations: pattern scanning is best-effort and does not prove content is free
+of sensitive data.
+
+### MCP Tool Abuse
+
+Risk: an MCP client can create, update, import, archive, restore, and read local
+artifacts through stdio.
+
+Controls:
+
+- MCP is local stdio only.
+- MCP writes go through the same secret scan and audit paths as CLI/HTTP writes.
+- MCP resources are read-only.
+
+Guidance: install Artifacty MCP only in clients and workspaces you trust.
+
+## Out of Scope
+
+- Public internet hosting without a separate TLS/auth proxy.
+- Multi-user browser write access.
+- OAuth or remote MCP authorization.
+- Per-artifact ACLs.
+- Encrypted-at-rest storage.
+- Malware analysis of arbitrary artifact content.
+
+## Security Review Checklist
+
+- Run `npm run release:check`.
+- Run `artifacty integrity` against important stores.
+- Confirm non-local sharing uses a token and trusted LAN/VPN.
+- Keep `ARTIFACTY_ENABLE_REACT_RENDERER` disabled unless required.
+- Prefer token headers over query tokens in scripts.
+- Review generated MCP configs before committing workspace files.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "artifacty",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Local artifact exchange for heterogeneous LLM agents via HTTP and MCP.",
   "type": "module",
   "keywords": [
@@ -41,9 +41,11 @@
     "docs/network-sharing.md",
     "docs/release-checklist.md",
     "docs/sarif-csv-artifact-plan.md",
+    "docs/threat-model.md",
     "scripts/smoke.sh",
     "README.md",
     "LICENSE",
+    "SECURITY.md",
     "THIRD_PARTY_NOTICES.md",
     "AGENTS.md",
     "CLAUDE.md"

package/src/cli.js

@@ -47,7 +47,10 @@ async function main() {
   }
 
   if (command === "serve") {
-    if (options.detach) {
+    if (options.detach && options.foreground) {
+      throw new Error("Use either --foreground or --detach, not both");
+    }
+    if (!options.foreground) {
       printJson(await startBackgroundServer({
         ...serverOptions(options),
         serverPath: path.join(PACKAGE_ROOT, "src", "server.js")
@@ -68,6 +71,9 @@ async function main() {
     });
     process.stderr.write(`Artifacty listening on ${server.url}\n`);
     process.stderr.write(`Store: ${server.store.home}\n`);
+    if (server.securityWarning) {
+      process.stderr.write(`${server.securityWarning}\n`);
+    }
     if (generatedToken) {
       process.stderr.write(`API token: ${generatedToken.token}\n`);
       process.stderr.write(`HTTP header: ${generatedToken.header}\n`);
@@ -311,7 +317,7 @@ function parseArgs(args) {
     }
 
     const key = arg.slice(2);
-    if (key === "raw" || key === "dry-run" || key === "trust" || key === "include-archived" || key === "allow-secrets" || key === "generate-token" || key === "detach" || key === "force") {
+    if (key === "raw" || key === "dry-run" || key === "trust" || key === "include-archived" || key === "allow-secrets" || key === "generate-token" || key === "detach" || key === "foreground" || key === "force") {
       options[toCamelCase(key)] = true;
       continue;
     }
@@ -394,10 +400,11 @@ function printHelp() {
 
 Usage:
   artifacty token [--bytes 32] [--raw]
-  artifacty serve [--host 127.0.0.1] [--port 8787] [--home ~/.artifacty] [--api-token token] [--generate-token] [--bytes 32] [--detach]
-  artifacty start [--host 127.0.0.1] [--port 8787] [--home ~/.artifacty] [--api-token token] [--timeout 5000]
+  artifacty serve [--host 127.0.0.1] [--port 8787] [--home ~/.artifacty] [--api-token token] [--generate-token] [--bytes 32] [--foreground]
+  artifacty serve --foreground [--generate-token]
+  artifacty start [--host 127.0.0.1] [--port 8787] [--home ~/.artifacty] [--api-token token] [--generate-token] [--timeout 30000]
   artifacty status [--home ~/.artifacty]
-  artifacty stop [--home ~/.artifacty] [--timeout 5000] [--force]
+  artifacty stop [--home ~/.artifacty] [--timeout 30000] [--force]
   artifacty publish --title <title> (--file <path> | --content <text>) [--format html|markdown|text|json|code|svg|mermaid|react] [--source agent] [--tag tag]
   artifacty import --agent claude|codex|gemini|copilot|cursor|auto (--file <path> | --content <text>) [--title <title>] [--format html|markdown|text|json|code|svg|mermaid|react] [--tag tag]
   artifacty install claude|codex|gemini|copilot|cursor|all [--dry-run] [--config <path>] [--server-path <path>] [--url http://127.0.0.1:8787] [--timeout 30000]

package/src/lib/background.js

@@ -4,14 +4,23 @@ import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { createStore } from "./storage.js";
 import { readServerState, serverStatePath } from "./server-state.js";
+import { exposureWarning, securityConfig } from "./security.js";
+import { generateToken } from "./token.js";
 
-const DEFAULT_READY_TIMEOUT_MS = 5000;
+const DEFAULT_READY_TIMEOUT_MS = 30000;
+const DEFAULT_HOST = "127.0.0.1";
 
 export async function startBackgroundServer(options = {}) {
   if (options.generateToken && options.apiToken) {
     throw new Error("Use either --api-token or --generate-token, not both");
   }
 
+  const generatedToken = options.generateToken ? generateToken(options) : null;
+  const serverOptions = {
+    ...options,
+    apiToken: generatedToken?.token || options.apiToken,
+    generateToken: false
+  };
   const store = createStore({ home: options.home });
   const paths = backgroundPaths(store);
   const current = await backgroundStatus({ home: store.home });
@@ -22,7 +31,7 @@ export async function startBackgroundServer(options = {}) {
   mkdirSync(paths.logDir, { recursive: true });
   mkdirSync(store.home, { recursive: true });
 
-  const child = spawnDetachedServer(options, store, paths);
+  const child = spawnDetachedServer(serverOptions, store, paths);
 
   writeFileSync(paths.pidFile, `${child.pid}\n`, "utf8");
 
@@ -39,6 +48,11 @@ export async function startBackgroundServer(options = {}) {
       pid: child.pid,
       url: ready.url,
       home: store.home,
+      auth: authResponse(generatedToken, ready.url),
+      securityWarning: exposureWarning({
+        host: serverOptions.host || process.env.ARTIFACTY_HOST || DEFAULT_HOST,
+        config: securityConfig(serverOptions)
+      }) || undefined,
       logs: {
         stdout: paths.stdoutLog,
         stderr: paths.stderrLog
@@ -58,6 +72,20 @@ export async function startBackgroundServer(options = {}) {
   }
 }
 
+function authResponse(generatedToken, url) {
+  if (!generatedToken) {
+    return null;
+  }
+  return {
+    token: generatedToken.token,
+    bytes: generatedToken.bytes,
+    header: generatedToken.header,
+    authorization: generatedToken.authorization,
+    createUrl: `${url}/new?token=${encodeURIComponent(generatedToken.token)}`,
+    importUrl: `${url}/import?token=${encodeURIComponent(generatedToken.token)}`
+  };
+}
+
 export async function stopBackgroundServer(options = {}) {
   const store = createStore({ home: options.home });
   const paths = backgroundPaths(store);
@@ -68,7 +96,7 @@ export async function stopBackgroundServer(options = {}) {
       action: "stop",
       stopped: false,
       running: status.running,
-      reason: status.pid ? "server was not started by artifacty start" : "server is not running",
+      reason: status.pid ? "server was not started by artifacty serve/start" : "server is not running",
       pid: status.pid || null,
       home: store.home
     };

package/src/lib/security.js

@@ -1,3 +1,5 @@
+import { createHash, timingSafeEqual } from "node:crypto";
+
 const TOKEN_HEADER = "x-artifacty-token";
 
 const SECRET_PATTERNS = [
@@ -31,12 +33,23 @@ export function validateServerExposure({ host, config = securityConfig() }) {
   }
 }
 
+export function exposureWarning({ host, config = securityConfig() }) {
+  if (isLoopbackHost(host)) {
+    return "";
+  }
+  return [
+    `Warning: Artifacty is listening on ${host} in ${config.shareMode} share mode.`,
+    "HTTP is not encrypted by Artifacty; use only a trusted LAN/VPN or place it behind TLS.",
+    "Prefer x-artifacty-token or Authorization headers for scripts, and keep React rendering disabled unless every viewer trusts the artifact source."
+  ].join(" ");
+}
+
 export function requireToken({ request, url, body = {}, config = securityConfig() }) {
   if (!config.apiToken) {
     return;
   }
   const provided = extractToken({ request, url, body });
-  if (provided !== config.apiToken) {
+  if (!tokensEqual(provided, config.apiToken)) {
     throw Object.assign(new Error("Artifacty API token required"), {
       code: "AUTH_REQUIRED",
       statusCode: 401
@@ -87,6 +100,15 @@ export function assertNoSecrets(input = {}, options = {}) {
   };
 }
 
+export function tokensEqual(provided, expected) {
+  const providedText = String(provided ?? "");
+  const expectedText = String(expected ?? "");
+  const providedDigest = createHash("sha256").update(providedText).digest();
+  const expectedDigest = createHash("sha256").update(expectedText).digest();
+  return timingSafeEqual(providedDigest, expectedDigest) &&
+    Buffer.byteLength(providedText) === Buffer.byteLength(expectedText);
+}
+
 export function isLoopbackHost(host) {
   const normalized = String(host || "").toLowerCase();
   return normalized === "localhost" ||

package/src/server.js

@@ -19,7 +19,7 @@ import { convertAgentArtifact } from "./lib/converters.js";
 import { createLineDiff } from "./lib/diff.js";
 import { EDITOR_CLIENT_PATH, VIEWER_CLIENT_PATH, editorClientFilePath, editorVendorPath, viewerClientFilePath } from "./lib/editor-assets.js";
 import { localeFromBodyOrUrl, localeFromUrl, localizedHref } from "./lib/i18n.js";
-import { requireToken, securityConfig, validateServerExposure } from "./lib/security.js";
+import { exposureWarning, requireToken, securityConfig, validateServerExposure } from "./lib/security.js";
 import { writeServerState } from "./lib/server-state.js";
 import { generateToken } from "./lib/token.js";
 import {
@@ -78,6 +78,7 @@ export async function startServer(options = {}) {
     requestedPort,
     port: actualPort,
     portFallback: usedPortFallback,
+    securityWarning: exposureWarning({ host, config: security }),
     close: () => new Promise((resolve, reject) => server.close((error) => (error ? reject(error) : resolve())))
   };
 }
@@ -674,12 +675,15 @@ async function runServerMain(options) {
     throw new Error("Use either --api-token or --generate-token, not both");
   }
   const generatedToken = options.generateToken ? generateToken(options) : null;
-  const { url, store } = await startServer({
+  const { url, store, securityWarning } = await startServer({
     ...options,
     apiToken: generatedToken?.token || options.apiToken
   });
   process.stderr.write(`Artifacty listening on ${url}\n`);
   process.stderr.write(`Store: ${store.home}\n`);
+  if (securityWarning) {
+    process.stderr.write(`${securityWarning}\n`);
+  }
   if (generatedToken) {
     process.stderr.write(`API token: ${generatedToken.token}\n`);
     process.stderr.write(`HTTP header: ${generatedToken.header}\n`);