@wolpertingerlabs/drawlatch 1.0.0-alpha.29 → 1.0.0-alpha.31

package/bin/drawlatch.js

@@ -83,6 +83,12 @@ try {
       full: { type: "boolean", default: false },
       requests: { type: "boolean", default: false },
       ttl: { type: "string", default: "300" },
+      name: { type: "string" },
+      connections: { type: "string" },
+      endpoint: { type: "string" },
+      passphrase: { type: "boolean", default: false },
+      output: { type: "string", short: "o" },
+      into: { type: "string" },
     },
     strict: false,
     allowPositionals: true,
@@ -179,7 +185,16 @@ switch (subcommand) {
       await cmdDoctor();
     }
     break;
+  case "issue-caller":
+    if (values.help) {
+      printIssueCallerHelp();
+    } else {
+      await cmdIssueCaller();
+    }
+    break;
   case "sync":
+    // Parked: kept in-tree as a high-assurance escape hatch, undocumented in
+    // the main help (superseded by `issue-caller`).
     if (values.help) {
       printSyncHelp();
     } else {
@@ -307,11 +322,13 @@ async function cmdInit() {
   }
 
   console.log(`\nSetup complete! Next steps:\n`);
-  console.log(`  1. Start the remote server:`);
+  console.log(`  1. Set the dashboard password:`);
+  console.log(`       drawlatch set-password\n`);
+  console.log(`  2. Start the remote server:`);
   console.log(`       drawlatch start\n`);
-  console.log(`  2. Add callers via key sync:`);
-  console.log(`       drawlatch sync\n`);
-  console.log(`  3. Verify your setup:`);
+  console.log(`  3. Issue a caller credential bundle (or use the dashboard Callers page):`);
+  console.log(`       drawlatch issue-caller callboard-prod -o callboard-prod.drawlatch-caller.json\n`);
+  console.log(`  4. Verify your setup:`);
   console.log(`       drawlatch doctor\n`);
 }
 
@@ -976,6 +993,133 @@ async function cmdSync() {
   process.exit(1);
 }
 
+// ── issue-caller ──────────────────────────────────────────────────────────
+//
+// Mint a caller credential bundle using the same primitive as the dashboard
+// "Issue credentials" action. Two delivery modes:
+//   - default / -o file : emit the {alias}.drawlatch-caller.json bundle (the
+//     caller PRIVATE key is in the file; drawlatch keeps only the public key).
+//   - --into <keysDir>  : write the UNPACKED key files straight into a
+//     co-located callboard's keys dir (same-host convenience).
+async function cmdIssueCaller() {
+  const alias = positionals[0];
+  if (!alias) {
+    console.error("Error: caller alias is required.\n  Usage: drawlatch issue-caller <alias> [options]");
+    process.exit(1);
+  }
+
+  ensureConfigDir();
+
+  const { issueCallerBundle, issueLocalCaller, CALLER_ALIAS_REGEX } = await import(
+    join(PKG_ROOT, "dist/remote/caller-bootstrap.js")
+  );
+
+  if (!CALLER_ALIAS_REGEX.test(alias)) {
+    console.error(
+      "Error: invalid alias. Use letters, numbers, dashes or underscores (must start alphanumeric).",
+    );
+    process.exit(1);
+  }
+
+  const connections = values.connections
+    ? values.connections.split(",").map((s) => s.trim()).filter(Boolean)
+    : undefined;
+  const name = values.name;
+
+  try {
+    // ── Mode 2: write unpacked key files directly into callboard's keys dir ──
+    if (values.into) {
+      const keysDir = resolve(values.into);
+      const res = issueLocalCaller({
+        alias,
+        keysDir,
+        ...(connections ? { connections } : {}),
+        ...(name ? { name } : {}),
+      });
+      console.log(`\nIssued local caller "${res.alias}" (write-to-path).`);
+      console.log(`  Key files:   ${res.callerKeysDir}/`);
+      console.log(`  Server keys: ${join(keysDir, "server")}/`);
+      console.log(`  Fingerprint: ${res.fingerprint}`);
+      console.log(`  Connections: ${res.connections.join(", ") || "(none)"}`);
+      notifyDaemonReloadNeeded();
+      return;
+    }
+
+    // ── Mode 1: emit a bundle (file or stdout) ──────────────────────────────
+    const config = loadRemoteConfig();
+    const endpoint = values.endpoint || `http://${connectHost(config.host)}:${config.port}`;
+
+    let passphrase;
+    if (values.passphrase) {
+      let confirm;
+      if (process.stdin.isTTY) {
+        passphrase = await promptPasswordTTY("Passphrase to protect private keys: ");
+        confirm = await promptPasswordTTY("Confirm passphrase: ");
+      } else {
+        // Piped input — read both lines from one readline interface.
+        const { createInterface } = await import("node:readline");
+        const rl = createInterface({ input: process.stdin });
+        [passphrase, confirm] = await readTwoLines(rl);
+        rl.close();
+      }
+      if (!passphrase) {
+        console.error("Error: passphrase cannot be empty.");
+        process.exit(1);
+      }
+      if (passphrase !== confirm) {
+        console.error("Error: passphrases do not match.");
+        process.exit(1);
+      }
+    }
+
+    const bundle = issueCallerBundle({
+      alias,
+      endpointUrl: endpoint,
+      ...(connections ? { connections } : {}),
+      ...(name ? { name } : {}),
+      ...(passphrase ? { passphrase } : {}),
+    });
+
+    const json = JSON.stringify(bundle, null, 2) + "\n";
+
+    if (values.output) {
+      const outPath = resolve(values.output);
+      writeFileSync(outPath, json, { mode: 0o600 });
+      console.error(`\nWrote credential bundle to ${outPath}`);
+      console.error(`  Caller:      ${bundle.callerAlias}`);
+      console.error(`  Fingerprint: ${bundle.fingerprint}`);
+      console.error(`  Endpoint:    ${bundle.endpointUrl}`);
+      console.error(
+        bundle.encryption
+          ? `  Private keys: passphrase-protected (share the passphrase out-of-band).`
+          : `  Private keys: PLAINTEXT in the file — protect it (or use --passphrase).`,
+      );
+      console.error(`  This file contains the caller PRIVATE key and won't be re-issued.`);
+      notifyDaemonReloadNeeded();
+    } else {
+      // Bundle (with private keys) to stdout; notes to stderr.
+      process.stdout.write(json);
+      console.error(`\n# Caller "${bundle.callerAlias}" issued (fingerprint ${bundle.fingerprint}).`);
+      if (!bundle.encryption) {
+        console.error(`# WARNING: private keys are PLAINTEXT above. Use --passphrase or -o to a 0600 file.`);
+      }
+      notifyDaemonReloadNeeded();
+    }
+  } catch (err) {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+/** If the daemon is running, it won't authorize a freshly-issued caller until
+ *  it reloads its peer set — tell the user to restart it. (The dashboard issue
+ *  flow live-reloads peers; the offline CLI path cannot.) */
+function notifyDaemonReloadNeeded() {
+  if (readPid()) {
+    console.error(`\nNote: restart the daemon so it authorizes the new caller — drawlatch restart`);
+  }
+}
+
 async function promptInput(prompt) {
   const { createInterface } = await import("node:readline");
   return new Promise((resolve) => {
@@ -1389,7 +1533,7 @@ Commands:
   watch              Watch ingestor events in real time
   doctor             Validate setup and diagnose issues
   generate-keys      Generate Ed25519 + X25519 keypairs
-  sync               Exchange keys with a callboard instance
+  issue-caller       Issue a caller credential bundle (for a callboard instance)
   set-password       Set/change the dashboard password (alias: change-password)
 
 Options:
@@ -1542,8 +1686,8 @@ drawlatch init
 Set up the drawlatch remote server. Generates server keys, creates
 config files, and scaffolds a .env template.
 
-Callers are added separately via 'drawlatch sync' after the server
-is running.
+Callers are issued separately via 'drawlatch issue-caller' (or the dashboard
+Callers page) after the server is running.
 
 Usage: drawlatch init [options]
 
@@ -1595,6 +1739,36 @@ The server must be running (drawlatch start) before using this command.
 `);
 }
 
+function printIssueCallerHelp() {
+  console.log(`
+drawlatch issue-caller
+
+Issue a caller credential bundle that a callboard instance imports to gain a
+caller identity. drawlatch mints the keypair, keeps only the PUBLIC key, and
+hands the private key out in the bundle (shown once — re-issue to rotate).
+
+Usage: drawlatch issue-caller <alias> [options]
+
+Options:
+  --name <name>           Human-readable display name (defaults to the alias)
+  --connections <a,b,c>   Comma-separated connections to authorize
+                          (defaults to cloning the "default" caller)
+  --endpoint <url>        Endpoint URL to pin in the bundle
+                          (defaults to this server's host:port)
+  --passphrase            Prompt for a passphrase and scrypt+AES-256-GCM wrap
+                          the private keys in the bundle (for untrusted transport)
+  -o, --output <file>     Write the bundle to a file (0600) instead of stdout
+  --into <keysDir>        Same-host: write the UNPACKED key files directly into a
+                          co-located callboard's keys dir (no bundle file)
+  -h, --help              Show this help message
+
+Examples:
+  drawlatch issue-caller callboard-prod -o callboard-prod.drawlatch-caller.json
+  drawlatch issue-caller callboard-prod --passphrase -o bundle.json
+  drawlatch issue-caller callboard-local --into ~/.callboard/keys
+`);
+}
+
 function printSetPasswordHelp(cmd = "set-password") {
   console.log(`
 drawlatch ${cmd}

package/dist/remote/admin-mutations.d.ts

@@ -26,6 +26,12 @@ export interface AdminMutationDeps {
     reloadPeer: (alias: string) => void;
     /** Drop the authorized peer + active sessions for a deleted caller. */
     removePeer: (alias: string) => void;
+    /** Audit-log a sensitive admin mutation (credential issuance). Optional so
+     *  tests can omit it; the daemon wires it to the request audit log. */
+    audit?: (action: string, details?: Record<string, unknown>) => void;
+    /** Endpoint URL to pin in an issued bundle when the request omits one
+     *  (the public tunnel URL, or the daemon's own host:port). */
+    defaultEndpointUrl?: () => string;
 }
 /**
  * Mount the mutating routes onto an existing admin router.

package/dist/remote/admin-mutations.js

@@ -12,9 +12,10 @@
  *   - After any config mutation, the daemon's live-reload path runs so ingestors
  *     and routes pick up the change (replacing callboard's restart banner).
  */
+import rateLimit from 'express-rate-limit';
 import { saveRemoteConfig } from '../shared/config.js';
 import { dispatchTool } from './tool-dispatch.js';
-import { createCallerWithKeys, deleteCaller, CALLER_ALIAS_REGEX } from './caller-bootstrap.js';
+import { createCallerWithKeys, deleteCaller, issueCallerBundle, CALLER_ALIAS_REGEX, } from './caller-bootstrap.js';
 /** Translate a thrown error into an HTTP status + message. */
 function errorStatus(message) {
     if (/already exists/i.test(message))
@@ -93,6 +94,75 @@ export function mountAdminMutations(router, deps) {
             res.status(errorStatus(message)).json({ error: message });
         }
     });
+    // ── Caller credential issuance ─────────────────────────────────────────
+    //
+    // Mint (or rotate) a caller credential bundle and return it ONCE. drawlatch
+    // keeps only the public key, so the private material is unrecoverable after
+    // this response — re-issue to rotate. Rate-limited and audit-logged; the
+    // bundle never carries any connection-secret value (only connection names).
+    const issueLimiter = rateLimit({
+        windowMs: 60 * 1000,
+        max: 10,
+        standardHeaders: true,
+        legacyHeaders: false,
+        message: { error: 'Too many issuance requests. Try again in a minute.' },
+    });
+    // POST /api/admin/callers/:alias/issue  { connections?, endpointUrl?, passphrase?, name? }
+    router.post('/callers/:alias/issue', issueLimiter, (req, res) => {
+        const alias = req.params.alias;
+        if (!CALLER_ALIAS_REGEX.test(alias)) {
+            res.status(400).json({ error: 'Invalid caller alias' });
+            return;
+        }
+        const { connections, endpointUrl, passphrase, name } = (req.body ?? {});
+        if (connections !== undefined &&
+            (!Array.isArray(connections) || !connections.every((c) => typeof c === 'string'))) {
+            res.status(400).json({ error: 'connections must be an array of strings' });
+            return;
+        }
+        if (endpointUrl !== undefined && typeof endpointUrl !== 'string') {
+            res.status(400).json({ error: 'endpointUrl must be a string' });
+            return;
+        }
+        if (passphrase !== undefined && typeof passphrase !== 'string') {
+            res.status(400).json({ error: 'passphrase must be a string' });
+            return;
+        }
+        if (name !== undefined && typeof name !== 'string') {
+            res.status(400).json({ error: 'name must be a string' });
+            return;
+        }
+        const resolvedEndpoint = typeof endpointUrl === 'string' && endpointUrl.trim() !== ''
+            ? endpointUrl.trim()
+            : (deps.defaultEndpointUrl?.() ?? '');
+        const reissue = alias in deps.loadConfig().callers;
+        try {
+            const bundle = issueCallerBundle({
+                alias,
+                endpointUrl: resolvedEndpoint,
+                ...(typeof name === 'string' && { name }),
+                ...(Array.isArray(connections) && { connections }),
+                ...(typeof passphrase === 'string' && passphrase !== '' && { passphrase }),
+            });
+            // Install the fresh public key and invalidate any prior credential's
+            // active sessions (removePeer drops sessions + peer; reloadPeer re-adds
+            // the new key) so a rotation takes effect immediately.
+            deps.removePeer(alias);
+            deps.reloadPeer(alias);
+            deps.audit?.('caller_issue', {
+                caller: alias,
+                reissue,
+                passphraseWrapped: bundle.encryption !== null,
+                connections: bundle.connections,
+                fingerprint: bundle.fingerprint,
+            });
+            res.json(bundle);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            res.status(errorStatus(message)).json({ error: message });
+        }
+    });
     // DELETE /api/admin/callers/:alias
     router.delete('/callers/:alias', (req, res) => {
         try {

package/dist/remote/admin-types.d.ts

@@ -7,6 +7,7 @@
  *
  * Type-only — compiles to nothing.
  */
+export type { CallerBundleV1, BundleEncryption, CallerSource, } from '../shared/protocol/caller-bundle.js';
 export interface AdminMeta {
     version: string;
     port: number;
@@ -43,6 +44,9 @@ export interface AdminCaller {
     envKeys: string[];
     fingerprint: string | null;
     keysDirExists: boolean;
+    /** How this caller's keypair was provisioned (drives the source badge).
+     *  null for callers created before issuance existed. */
+    source: 'local-auto' | 'bundle-issued' | null;
 }
 export type ConnectionCategory = 'ai' | 'developer-tools' | 'gaming' | 'messaging' | 'productivity' | 'social-media';
 export interface AdminConnectionTemplate {

package/dist/remote/admin.js

@@ -89,6 +89,7 @@ export function createAdminRouter(deps) {
                 envKeys: Object.keys(caller.env ?? {}),
                 fingerprint,
                 keysDirExists,
+                source: caller.source ?? null,
             };
         });
         res.json(out);

package/dist/remote/caller-bootstrap.d.ts

@@ -1,21 +1,21 @@
 /**
- * Programmatic / non-interactive caller bootstrap (item E).
+ * Caller provisioning — drawlatch is the sole issuer of caller key material.
  *
- * The interactive `drawlatch sync` handshake stays the path for *remote*
- * enrollment (a caller on another machine proving identity over the network).
- * This module is for the zero-friction local case: a co-located client that
- * shares drawlatch's filesystem can provision a caller — complete with a fresh
- * keypair — without any invite-code dance.
+ * One primitive, two delivery modes (see plans/caller-credential-issuance.md):
+ *   - `issueCallerBundle()` — mint a keypair IN MEMORY, persist only the public
+ *     half, and return the credential bundle (download via the admin API, or the
+ *     `drawlatch issue-caller` CLI). The caller PRIVATE key never touches
+ *     drawlatch disk; it lives only inside the returned bundle.
+ *   - `issueLocalCaller()` — same primitive, but write the UNPACKED key files
+ *     straight into a co-located callboard's keys dir over the shared filesystem.
+ *     The same-host write IS the trust proof (replaces the old enroll-token dance).
  *
- * Two entry points:
- *   - `createCallerWithKeys()` — library function (also exposed as the
- *     password-gated `POST /api/admin/callers` admin endpoint).
- *   - `autoEnroll()` — loopback / shared-fs path: a client proves filesystem
- *     access by presenting the one-time token drawlatch writes into the config
- *     dir at startup, and gets a caller provisioned with zero interaction.
+ * `createCallerWithKeys()` (priv+pub on drawlatch disk) is retained for the
+ * password-gated `POST /api/admin/callers` create endpoint and tests.
  */
 import { type RemoteServerConfig } from '../shared/config.js';
-import type { SerializedPublicKeys } from '../shared/crypto/keys.js';
+import { type SerializedPublicKeys } from '../shared/crypto/keys.js';
+import type { CallerBundleV1 } from '../shared/protocol/caller-bundle.js';
 /** Valid caller alias: starts with a letter/number, then letters/numbers/-/_. */
 export declare const CALLER_ALIAS_REGEX: RegExp;
 export interface CreateCallerOptions {
@@ -36,36 +36,86 @@ export interface CreateCallerResult {
     connections: string[];
 }
 /**
- * Create a caller WITH a fresh keypair, registered in remote.config.json,
- * without the interactive sync handshake.
+ * Create a caller WITH a fresh keypair on drawlatch disk (priv+pub), registered
+ * in remote.config.json. Used by the dashboard "New caller" action.
  *
  * Throws on invalid alias, or if the caller (config entry or key dir) exists.
  */
 export declare function createCallerWithKeys(alias: string, opts?: CreateCallerOptions): CreateCallerResult;
+export interface IssueCallerOptions {
+    alias: string;
+    /** Human-readable display name (preserved on re-issue; defaults to alias). */
+    name?: string;
+    /** Connections to authorize. Preserved on re-issue; clones `default` for new. */
+    connections?: string[];
+    /** drawlatch endpoint this caller identity is scoped to (pinned in the bundle). */
+    endpointUrl: string;
+    /** When set, `caller.*.priv` is scrypt+AES-256-GCM wrapped in the bundle. */
+    passphrase?: string;
+    /** ISO timestamp override (tests). Defaults to now. */
+    createdAt?: string;
+}
 /**
- * Delete a caller: removes its config entry, prefixed env vars, and key dir.
- * The `default` caller cannot be deleted.
+ * Issue (or re-issue / rotate) a caller credential bundle.
+ *
+ *   1. Generate the Ed25519 + X25519 keypair IN MEMORY.
+ *   2. Register/update the caller in remote.config.json (connections, name,
+ *      source='bundle-issued').
+ *   3. Persist ONLY the public keys to keys/callers/<alias>/ (the private key
+ *      never touches drawlatch disk).
+ *   4. Assemble the v1 bundle (caller priv+pub, server pub-only, endpoint,
+ *      fingerprints, connections), optionally passphrase-wrapping the two
+ *      private PEMs.
+ *   5. Zero the derived key material from memory and return the bundle.
+ *
+ * Re-issuing an existing caller mints a FRESH keypair and overwrites the stored
+ * public key — invalidating the prior credential (the old private key can no
+ * longer authenticate). The bundle is returned once; drawlatch keeps no copy of
+ * the private material, so it is unrecoverable afterward.
  */
-export declare function deleteCaller(alias: string): void;
-/** Path of the one-time enroll token file inside the config dir. */
-export declare function getEnrollTokenPath(): string;
+export declare function issueCallerBundle(opts: IssueCallerOptions): CallerBundleV1;
+export interface IssueLocalCallerOptions {
+    /** Caller alias (default 'callboard-local'). */
+    alias?: string;
+    /** Human-readable display name. */
+    name?: string;
+    /** Connections to authorize (defaults to cloning `default`). */
+    connections?: string[];
+    /** callboard's keys dir (the directory that holds `callers/` and `server/`). */
+    keysDir: string;
+}
+export interface IssueLocalCallerResult {
+    alias: string;
+    fingerprint: string;
+    /** The caller key directory written inside callboard's keys dir. */
+    callerKeysDir: string;
+    connections: string[];
+}
 /**
- * Write a fresh one-time enroll token into the config dir (mode 0600).
+ * Issue a caller and write the UNPACKED key files straight into a co-located
+ * callboard's keys dir over the shared filesystem (same-host write is the trust
+ * proof). drawlatch keeps only the public key; callboard gets the private key on
+ * its own disk — bit-for-bit the steady state of the old pairing flow, with no
+ * token dance.
  *
- * Only a process with filesystem access to drawlatch's config dir can read it,
- * which is exactly the proof-of-co-location we want for `autoEnroll()`.
- * Called once at daemon startup; overwrites any stale token.
+ * Writes, under `<keysDir>`:
+ *   - callers/<alias>/{signing,exchange}.{key,pub}.pem  (0600 / 0644)
+ *   - server/{signing,exchange}.pub.pem                 (0644)
  */
-export declare function writeEnrollToken(): string;
+export declare function issueLocalCaller(opts: IssueLocalCallerOptions): IssueLocalCallerResult;
 /**
- * Auto-enroll a co-located caller by presenting the one-time enroll token.
+ * First-boot hook: when drawlatch is supervised by a co-located callboard (which
+ * sets DRAWLATCH_LOCAL_CALLER_KEYS_DIR to its own keys dir), auto-share a default
+ * caller into that dir — but only once (skipped if the caller already exists).
  *
- * Verifies the token proves filesystem access to the config dir, then either
- * creates a new caller with keys (if the alias is new) or returns the existing
- * one's metadata (idempotent). The token is single-use: it is rotated on every
- * successful enroll so a leaked token cannot be replayed.
+ * Replaces the retired enroll-token / `/sync/auto-enroll` path.
  */
-export declare function autoEnroll(token: string, alias: string, opts?: CreateCallerOptions): CreateCallerResult;
+export declare function maybeIssueLocalCaller(): IssueLocalCallerResult | null;
+/**
+ * Delete a caller: removes its config entry, prefixed env vars, and key dir.
+ * The `default` caller cannot be deleted.
+ */
+export declare function deleteCaller(alias: string): void;
 /** Re-exported for callers that want to introspect config without re-importing. */
 export type { RemoteServerConfig };
 //# sourceMappingURL=caller-bootstrap.d.ts.map