Implement local agent JWT authentication for adapters

Add HS256 JWT-based authentication for local adapters (claude_local, codex_local)
so agents authenticate automatically without manual API key configuration. The
server mints short-lived JWTs per heartbeat run and injects them as PAPERCLIP_API_KEY.
The auth middleware verifies JWTs alongside existing static API keys.

Includes: CLI onboard/doctor JWT secret management, env command for deployment,
config path resolution from ancestor directories, dotenv loading on server startup,
event payload secret redaction, multi-status issue filtering, and adapter transcript
parsing for thinking/user message kinds.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

cli/src/checks/agent-jwt-secret-check.ts

@@ -0,0 +1,40 @@
+import {
+  ensureAgentJwtSecret,
+  readAgentJwtSecretFromEnv,
+  readAgentJwtSecretFromEnvFile,
+  resolveAgentJwtEnvFile,
+} from "../config/env.js";
+import type { CheckResult } from "./index.js";
+
+export function agentJwtSecretCheck(): CheckResult {
+  if (readAgentJwtSecretFromEnv()) {
+    return {
+      name: "Agent JWT secret",
+      status: "pass",
+      message: "PAPERCLIP_AGENT_JWT_SECRET is set in environment",
+    };
+  }
+
+  const envPath = resolveAgentJwtEnvFile();
+  const fileSecret = readAgentJwtSecretFromEnvFile(envPath);
+
+  if (fileSecret) {
+    return {
+      name: "Agent JWT secret",
+      status: "warn",
+      message: `PAPERCLIP_AGENT_JWT_SECRET is present in ${envPath} but not loaded into environment`,
+      repairHint: `Set the value from ${envPath} in your shell before starting the Paperclip server`,
+    };
+  }
+
+  return {
+    name: "Agent JWT secret",
+    status: "fail",
+    message: `PAPERCLIP_AGENT_JWT_SECRET missing from environment and ${envPath}`,
+    canRepair: true,
+    repair: () => {
+      ensureAgentJwtSecret();
+    },
+    repairHint: `Run with --repair to create ${envPath} containing PAPERCLIP_AGENT_JWT_SECRET`,
+  };
+}

cli/src/checks/index.ts

@@ -7,6 +7,7 @@ export interface CheckResult {
   repairHint?: string;
 }
 
+export { agentJwtSecretCheck } from "./agent-jwt-secret-check.js";
 export { configCheck } from "./config-check.js";
 export { databaseCheck } from "./database-check.js";
 export { llmCheck } from "./llm-check.js";

cli/src/commands/doctor.ts

@@ -1,8 +1,9 @@
 import * as p from "@clack/prompts";
 import pc from "picocolors";
 import type { PaperclipConfig } from "../config/schema.js";
-import { readConfig } from "../config/store.js";
+import { readConfig, resolveConfigPath } from "../config/store.js";
 import {
+  agentJwtSecretCheck,
   configCheck,
   databaseCheck,
   llmCheck,
@@ -24,6 +25,7 @@ export async function doctor(opts: {
 }): Promise<void> {
   p.intro(pc.bgCyan(pc.black(" paperclip doctor ")));
 
+  const configPath = resolveConfigPath(opts.config);
   const results: CheckResult[] = [];
 
   // 1. Config check (must pass before others)
@@ -53,24 +55,30 @@ export async function doctor(opts: {
     return;
   }
 
-  // 2. Database check
-  const dbResult = await databaseCheck(config);
+  // 2. Agent JWT check
+  const jwtResult = agentJwtSecretCheck();
+  results.push(jwtResult);
+  printResult(jwtResult);
+  await maybeRepair(jwtResult, opts);
+
+  // 3. Database check
+  const dbResult = await databaseCheck(config, configPath);
   results.push(dbResult);
   printResult(dbResult);
   await maybeRepair(dbResult, opts);
 
-  // 3. LLM check
+  // 4. LLM check
   const llmResult = await llmCheck(config);
   results.push(llmResult);
   printResult(llmResult);
 
-  // 4. Log directory check
-  const logResult = logCheck(config);
+  // 5. Log directory check
+  const logResult = logCheck(config, configPath);
   results.push(logResult);
   printResult(logResult);
   await maybeRepair(logResult, opts);
 
-  // 5. Port check
+  // 6. Port check
   const portResult = await portCheck(config);
   results.push(portResult);
   printResult(portResult);

cli/src/commands/env.ts

@@ -0,0 +1,209 @@
+import * as p from "@clack/prompts";
+import pc from "picocolors";
+import type { PaperclipConfig } from "../config/schema.js";
+import { configExists, readConfig, resolveConfigPath } from "../config/store.js";
+import {
+  readAgentJwtSecretFromEnv,
+  readAgentJwtSecretFromEnvFile,
+  resolveAgentJwtEnvFile,
+} from "../config/env.js";
+
+type EnvSource = "env" | "config" | "file" | "default" | "missing";
+
+type EnvVarRow = {
+  key: string;
+  value: string;
+  source: EnvSource;
+  required: boolean;
+  note: string;
+};
+
+const DEFAULT_AGENT_JWT_TTL_SECONDS = "172800";
+const DEFAULT_AGENT_JWT_ISSUER = "paperclip";
+const DEFAULT_AGENT_JWT_AUDIENCE = "paperclip-api";
+const DEFAULT_HEARTBEAT_SCHEDULER_INTERVAL_MS = "30000";
+
+export async function envCommand(opts: { config?: string }): Promise<void> {
+  p.intro(pc.bgCyan(pc.black(" paperclip env ")));
+
+  const configPath = resolveConfigPath(opts.config);
+  let config: PaperclipConfig | null = null;
+  let configReadError: string | null = null;
+
+  if (configExists(opts.config)) {
+    p.log.message(pc.dim(`Config file: ${configPath}`));
+    try {
+      config = readConfig(opts.config);
+    } catch (err) {
+      configReadError = err instanceof Error ? err.message : String(err);
+      p.log.message(pc.yellow(`Could not parse config: ${configReadError}`));
+    }
+  } else {
+    p.log.message(pc.dim(`Config file missing: ${configPath}`));
+  }
+
+  const rows = collectDeploymentEnvRows(config, configPath);
+  const missingRequired = rows.filter((row) => row.required && row.source === "missing");
+  const sortedRows = rows.sort((a, b) => Number(b.required) - Number(a.required) || a.key.localeCompare(b.key));
+
+  const requiredRows = sortedRows.filter((row) => row.required);
+  const optionalRows = sortedRows.filter((row) => !row.required);
+
+  const formatSection = (title: string, entries: EnvVarRow[]) => {
+    if (entries.length === 0) return;
+
+    p.log.message(pc.bold(title));
+    for (const entry of entries) {
+      const status = entry.source === "missing" ? pc.red("missing") : entry.source === "default" ? pc.yellow("default") : pc.green("set");
+      const sourceNote = {
+        env: "environment",
+        config: "config",
+        file: "file",
+        default: "default",
+        missing: "missing",
+      }[entry.source];
+      p.log.message(
+        `${pc.cyan(entry.key)} ${status.padEnd(7)} ${pc.dim(`[${sourceNote}] ${entry.note}`)}${entry.source === "missing" ? "" : ` ${pc.dim("=>")} ${pc.white(quoteShellValue(entry.value))}`}`,
+      );
+    }
+  };
+
+  formatSection("Required environment variables", requiredRows);
+  formatSection("Optional environment variables", optionalRows);
+
+  const exportRows = rows.map((row) => (row.source === "missing" ? { ...row, value: "<set-this-value>" } : row));
+  const uniqueRows = uniqueByKey(exportRows);
+  const exportBlock = uniqueRows.map((row) => `export ${row.key}=${quoteShellValue(row.value)}`).join("\n");
+
+  if (configReadError) {
+    p.log.error(`Could not load config cleanly: ${configReadError}`);
+  }
+
+  p.note(
+    exportBlock || "No values detected. Set required variables manually.",
+    "Deployment export block",
+  );
+
+  if (missingRequired.length > 0) {
+    p.log.message(
+      pc.yellow(
+        `Missing required values: ${missingRequired.map((row) => row.key).join(", ")}. Set these before deployment.`,
+      ),
+    );
+  } else {
+    p.log.message(pc.green("All required deployment variables are present."));
+  }
+  p.outro("Done");
+}
+
+function collectDeploymentEnvRows(config: PaperclipConfig | null, configPath: string): EnvVarRow[] {
+  const agentJwtEnvFile = resolveAgentJwtEnvFile();
+  const jwtEnv = readAgentJwtSecretFromEnv();
+  const jwtFile = jwtEnv ? null : readAgentJwtSecretFromEnvFile(agentJwtEnvFile);
+  const jwtSource = jwtEnv ? "env" : jwtFile ? "file" : "missing";
+
+  const dbUrl = process.env.DATABASE_URL ?? config?.database?.connectionString ?? "";
+  const databaseMode = config?.database?.mode ?? "embedded-postgres";
+  const dbUrlSource: EnvSource = process.env.DATABASE_URL ? "env" : config?.database?.connectionString ? "config" : "missing";
+
+  const heartbeatInterval = process.env.HEARTBEAT_SCHEDULER_INTERVAL_MS ?? DEFAULT_HEARTBEAT_SCHEDULER_INTERVAL_MS;
+  const heartbeatEnabled = process.env.HEARTBEAT_SCHEDULER_ENABLED ?? "true";
+
+  const rows: EnvVarRow[] = [
+    {
+      key: "PAPERCLIP_AGENT_JWT_SECRET",
+      value: jwtEnv ?? jwtFile ?? "",
+      source: jwtSource,
+      required: true,
+      note:
+        jwtSource === "missing"
+          ? "Generate during onboard or set manually (required for local adapter authentication)"
+          : jwtSource === "env"
+            ? "Set in process environment"
+            : `Set in ${agentJwtEnvFile}`,
+    },
+    {
+      key: "DATABASE_URL",
+      value: dbUrl,
+      source: dbUrlSource,
+      required: true,
+      note:
+        databaseMode === "postgres"
+          ? "Configured for postgres mode (required)"
+          : "Required for live deployment with managed PostgreSQL",
+    },
+    {
+      key: "PORT",
+      value:
+        process.env.PORT ??
+        (config?.server?.port !== undefined ? String(config.server.port) : "3100"),
+      source: process.env.PORT ? "env" : config?.server?.port !== undefined ? "config" : "default",
+      required: false,
+      note: "HTTP listen port",
+    },
+    {
+      key: "PAPERCLIP_AGENT_JWT_TTL_SECONDS",
+      value: process.env.PAPERCLIP_AGENT_JWT_TTL_SECONDS ?? DEFAULT_AGENT_JWT_TTL_SECONDS,
+      source: process.env.PAPERCLIP_AGENT_JWT_TTL_SECONDS ? "env" : "default",
+      required: false,
+      note: "JWT lifetime in seconds",
+    },
+    {
+      key: "PAPERCLIP_AGENT_JWT_ISSUER",
+      value: process.env.PAPERCLIP_AGENT_JWT_ISSUER ?? DEFAULT_AGENT_JWT_ISSUER,
+      source: process.env.PAPERCLIP_AGENT_JWT_ISSUER ? "env" : "default",
+      required: false,
+      note: "JWT issuer",
+    },
+    {
+      key: "PAPERCLIP_AGENT_JWT_AUDIENCE",
+      value: process.env.PAPERCLIP_AGENT_JWT_AUDIENCE ?? DEFAULT_AGENT_JWT_AUDIENCE,
+      source: process.env.PAPERCLIP_AGENT_JWT_AUDIENCE ? "env" : "default",
+      required: false,
+      note: "JWT audience",
+    },
+    {
+      key: "HEARTBEAT_SCHEDULER_INTERVAL_MS",
+      value: heartbeatInterval,
+      source: process.env.HEARTBEAT_SCHEDULER_INTERVAL_MS ? "env" : "default",
+      required: false,
+      note: "Heartbeat worker interval in ms",
+    },
+    {
+      key: "HEARTBEAT_SCHEDULER_ENABLED",
+      value: heartbeatEnabled,
+      source: process.env.HEARTBEAT_SCHEDULER_ENABLED ? "env" : "default",
+      required: false,
+      note: "Set to `false` to disable timer scheduling",
+    },
+  ];
+
+  const defaultConfigPath = resolveConfigPath();
+  if (process.env.PAPERCLIP_CONFIG || configPath !== defaultConfigPath) {
+    rows.push({
+      key: "PAPERCLIP_CONFIG",
+      value: process.env.PAPERCLIP_CONFIG ?? configPath,
+      source: process.env.PAPERCLIP_CONFIG ? "env" : "default",
+      required: false,
+      note: "Optional path override for config file",
+    });
+  }
+
+  return rows;
+}
+
+function uniqueByKey(rows: EnvVarRow[]): EnvVarRow[] {
+  const seen = new Set<string>();
+  const result: EnvVarRow[] = [];
+  for (const row of rows) {
+    if (seen.has(row.key)) continue;
+    seen.add(row.key);
+    result.push(row);
+  }
+  return result;
+}
+
+function quoteShellValue(value: string): string {
+  if (value === "") return "\"\"";
+  return `'${value.replaceAll("'", "'\\''")}'`;
+}

cli/src/commands/onboard.ts

@@ -1,7 +1,8 @@
 import * as p from "@clack/prompts";
 import pc from "picocolors";
-import { configExists, readConfig, writeConfig } from "../config/store.js";
+import { configExists, readConfig, resolveConfigPath, writeConfig } from "../config/store.js";
 import type { PaperclipConfig } from "../config/schema.js";
+import { ensureAgentJwtSecret, resolveAgentJwtEnvFile } from "../config/env.js";
 import { promptDatabase } from "../prompts/database.js";
 import { promptLlm } from "../prompts/llm.js";
 import { promptLogging } from "../prompts/logging.js";
@@ -12,25 +13,18 @@ export async function onboard(opts: { config?: string }): Promise<void> {
 
   // Check for existing config
   if (configExists(opts.config)) {
+    const configPath = resolveConfigPath(opts.config);
+    p.log.message(pc.dim(`${configPath} exists, updating config`));
+
     try {
       readConfig(opts.config);
     } catch (err) {
       p.log.message(
         pc.yellow(
-          `Existing config appears invalid and will be replaced if you continue.\n${err instanceof Error ? err.message : String(err)}`,
+          `Existing config appears invalid and will be updated.\n${err instanceof Error ? err.message : String(err)}`,
         ),
       );
     }
-
-    const overwrite = await p.confirm({
-      message: "A config file already exists. Overwrite it?",
-      initialValue: false,
-    });
-
-    if (p.isCancel(overwrite) || !overwrite) {
-      p.cancel("Keeping existing configuration.");
-      return;
-    }
   }
 
   // Database
@@ -104,6 +98,16 @@ export async function onboard(opts: { config?: string }): Promise<void> {
   p.log.step(pc.bold("Server"));
   const server = await promptServer();
 
+  const jwtSecret = ensureAgentJwtSecret();
+  const envFilePath = resolveAgentJwtEnvFile();
+  if (jwtSecret.created) {
+    p.log.success(`Created ${pc.cyan("PAPERCLIP_AGENT_JWT_SECRET")} in ${pc.dim(envFilePath)}`);
+  } else if (process.env.PAPERCLIP_AGENT_JWT_SECRET?.trim()) {
+    p.log.info(`Using existing ${pc.cyan("PAPERCLIP_AGENT_JWT_SECRET")} from environment`);
+  } else {
+    p.log.info(`Using existing ${pc.cyan("PAPERCLIP_AGENT_JWT_SECRET")} in ${pc.dim(envFilePath)}`);
+  }
+
   // Assemble and write config
   const config: PaperclipConfig = {
     $meta: {
@@ -125,10 +129,14 @@ export async function onboard(opts: { config?: string }): Promise<void> {
       llm ? `LLM: ${llm.provider}` : "LLM: not configured",
       `Logging: ${logging.mode} → ${logging.logDir}`,
       `Server: port ${server.port}`,
+      `Agent auth: PAPERCLIP_AGENT_JWT_SECRET configured`,
     ].join("\n"),
     "Configuration saved",
   );
 
   p.log.info(`Run ${pc.cyan("pnpm paperclip doctor")} to verify your setup.`);
+  p.log.message(
+    `Before starting Paperclip, export ${pc.cyan("PAPERCLIP_AGENT_JWT_SECRET")} from ${pc.dim(envFilePath)} (for example: ${pc.dim(`set -a; source ${envFilePath}; set +a`)})`,
+  );
   p.outro("You're all set!");
 }

cli/src/config/env.ts

@@ -0,0 +1,91 @@
+import fs from "node:fs";
+import path from "node:path";
+import { randomBytes } from "node:crypto";
+import { config as loadDotenv, parse as parseEnvFileContents } from "dotenv";
+import { resolveConfigPath } from "./store.js";
+
+const JWT_SECRET_ENV_KEY = "PAPERCLIP_AGENT_JWT_SECRET";
+function resolveEnvFilePath() {
+  return path.resolve(path.dirname(resolveConfigPath()), ".env");
+}
+
+const ENV_FILE_PATH = resolveEnvFilePath();
+const loadedEnvFiles = new Set<string>();
+
+function isNonEmpty(value: unknown): value is string {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+function parseEnvFile(contents: string) {
+  try {
+    return parseEnvFileContents(contents);
+  } catch {
+    return {};
+  }
+}
+
+function renderEnvFile(entries: Record<string, string>) {
+  const lines = [
+    "# Paperclip environment variables",
+    "# Generated by `paperclip onboard`",
+    ...Object.entries(entries).map(([key, value]) => `${key}=${value}`),
+    "",
+  ];
+  return lines.join("\n");
+}
+
+export function resolveAgentJwtEnvFile(): string {
+  return ENV_FILE_PATH;
+}
+
+export function loadAgentJwtEnvFile(filePath = ENV_FILE_PATH): void {
+  if (loadedEnvFiles.has(filePath)) return;
+
+  if (!fs.existsSync(filePath)) return;
+  loadedEnvFiles.add(filePath);
+  loadDotenv({ path: filePath, override: false, quiet: true });
+}
+
+export function readAgentJwtSecretFromEnv(): string | null {
+  loadAgentJwtEnvFile();
+  const raw = process.env[JWT_SECRET_ENV_KEY];
+  return isNonEmpty(raw) ? raw!.trim() : null;
+}
+
+export function readAgentJwtSecretFromEnvFile(filePath = ENV_FILE_PATH): string | null {
+  if (!fs.existsSync(filePath)) return null;
+
+  const raw = fs.readFileSync(filePath, "utf-8");
+  const values = parseEnvFile(raw);
+  const value = values[JWT_SECRET_ENV_KEY];
+  return isNonEmpty(value) ? value!.trim() : null;
+}
+
+export function ensureAgentJwtSecret(): { secret: string; created: boolean } {
+  const existingEnv = readAgentJwtSecretFromEnv();
+  if (existingEnv) {
+    return { secret: existingEnv, created: false };
+  }
+
+  const existingFile = readAgentJwtSecretFromEnvFile();
+  const secret = existingFile ?? randomBytes(32).toString("hex");
+  const created = !existingFile;
+
+  if (!existingFile) {
+    writeAgentJwtEnv(secret);
+  }
+
+  return { secret, created };
+}
+
+export function writeAgentJwtEnv(secret: string, filePath = ENV_FILE_PATH): void {
+  const dir = path.dirname(filePath);
+  fs.mkdirSync(dir, { recursive: true });
+
+  const current = fs.existsSync(filePath) ? parseEnvFile(fs.readFileSync(filePath, "utf-8")) : {};
+  current[JWT_SECRET_ENV_KEY] = secret;
+
+  fs.writeFileSync(filePath, renderEnvFile(current), {
+    mode: 0o600,
+  });
+}

cli/src/config/store.ts

@@ -3,11 +3,30 @@ import path from "node:path";
 import { paperclipConfigSchema, type PaperclipConfig } from "./schema.js";
 
 const DEFAULT_CONFIG_PATH = ".paperclip/config.json";
+const DEFAULT_CONFIG_BASENAME = "config.json";
+
+function findConfigFileFromAncestors(startDir: string): string | null {
+  const absoluteStartDir = path.resolve(startDir);
+  let currentDir = absoluteStartDir;
+
+  while (true) {
+    const candidate = path.resolve(currentDir, ".paperclip", DEFAULT_CONFIG_BASENAME);
+    if (fs.existsSync(candidate)) {
+      return candidate;
+    }
+
+    const nextDir = path.resolve(currentDir, "..");
+    if (nextDir === currentDir) break;
+    currentDir = nextDir;
+  }
+
+  return null;
+}
 
 export function resolveConfigPath(overridePath?: string): string {
   if (overridePath) return path.resolve(overridePath);
   if (process.env.PAPERCLIP_CONFIG) return path.resolve(process.env.PAPERCLIP_CONFIG);
-  return path.resolve(process.cwd(), DEFAULT_CONFIG_PATH);
+  return findConfigFileFromAncestors(process.cwd()) ?? path.resolve(process.cwd(), DEFAULT_CONFIG_PATH);
 }
 
 function parseJson(filePath: string): unknown {

cli/src/index.ts

@@ -2,6 +2,7 @@
 import { Command } from "commander";
 import { onboard } from "./commands/onboard.js";
 import { doctor } from "./commands/doctor.js";
+import { envCommand } from "./commands/env.js";
 import { configure } from "./commands/configure.js";
 import { heartbeatRun } from "./commands/heartbeat-run.js";
 
@@ -27,6 +28,12 @@ program
   .option("-y, --yes", "Skip repair confirmation prompts")
   .action(doctor);
 
+program
+  .command("env")
+  .description("Print environment variables for deployment")
+  .option("-c, --config <path>", "Path to config file")
+  .action(envCommand);
+
 program
   .command("configure")
   .description("Update configuration sections")