@sanctuary-framework/mcp-server 0.10.0 → 0.10.2

package/dist/index.d.cts

@@ -159,11 +159,29 @@ declare class AuditLog {
     private readonly maxTotalSizeBytes;
     private readonly maxEntries;
     private rotationInFlight;
+    private readonly pendingWrites;
     constructor(storage: StorageBackend, masterKey: Uint8Array, config?: AuditLogConfig);
     /**
      * Append an audit entry.
+     *
+     * The on-disk persist is async and tracked via `pendingWrites`. Long-lived
+     * callers (the main MCP server) can ignore that tracking and let writes
+     * drain naturally. Short-lived callers — the `sanctuary secrets` CLI which
+     * `process.exit()`s immediately after returning from a broker mutation —
+     * MUST await `flush()` before exiting, or in-flight writes get killed
+     * with the event loop and the entry is silently lost. That was the
+     * v0.10.0-rc.2 soak failure mode where `secrets audit` returned empty
+     * after a clean 7-verb lifecycle.
      */
     append(layer: AuditEntry["layer"], operation: string, identityId: string, details?: Record<string, unknown>, result?: "success" | "failure"): void;
+    /**
+     * Wait for every in-flight `append()` persist (and its rotation pass) to
+     * settle. Safe to call multiple times — newly-appended entries during a
+     * flush are also awaited. Re-entrant only at the granularity of "drain
+     * everything queued so far". Short-lived CLIs MUST call this before
+     * `process.exit()` to keep audit writes durable.
+     */
+    flush(): Promise<void>;
     private persistEntry;
     /**
      * Prune oldest audit entries when storage exceeds configured limits.
@@ -2853,6 +2871,24 @@ declare class DashboardApprovalChannel implements ApprovalChannel {
     private rateLimits;
     /** Whether the dashboard is running in standalone mode (no MCP server) */
     private _standaloneMode;
+    /**
+     * v0.10.2: when set, requests from loopback addresses (127.0.0.1 / ::1)
+     * are treated as authenticated without requiring a Bearer token or
+     * dashboard session cookie. Only the `startStandaloneDashboard` boot
+     * path enables this, and ONLY after the supplied passphrase successfully
+     * decrypts at least one stored identity — proving the caller already
+     * holds the primary secret that protects every piece of Sanctuary state.
+     *
+     * Rationale: the dashboard auth token is a dashboard-access credential
+     * layered on top of the master-key unlock. Once the operator has already
+     * presented the passphrase on the command line (terminal-side auth), a
+     * second login prompt in the auto-opened browser just trains users to
+     * paste secrets into web forms — the exact habit Sanctuary exists to
+     * discourage. Remote (non-loopback) callers still require the bearer
+     * token, so this is a localhost-only ergonomics unlock, not a network
+     * policy change.
+     */
+    private _autoAuthLocalhost;
     constructor(config: DashboardConfig);
     /**
      * Inject dependencies after construction.
@@ -2874,6 +2910,21 @@ declare class DashboardApprovalChannel implements ApprovalChannel {
      * Exposed via /api/status so the frontend can show an appropriate banner.
      */
     setStandaloneMode(standalone: boolean): void;
+    /**
+     * v0.10.2: enable (or disable) the loopback auto-auth fast path. See
+     * {@link _autoAuthLocalhost} for the rationale and threat model. Callers
+     * should gate this on both (a) the dashboard host being a loopback
+     * interface and (b) the master-key unlock having succeeded against
+     * on-disk state.
+     */
+    setAutoAuthLocalhost(enabled: boolean): void;
+    /**
+     * v0.10.2: is this request from a loopback interface? We treat the
+     * standard IPv4/IPv6 loopback addresses plus the IPv4-mapped IPv6 form
+     * as loopback so LAN clients never accidentally hit the unauthenticated
+     * fast path even on hosts where the HTTP server binds 0.0.0.0.
+     */
+    private isLoopbackRequest;
     /**
      * Start the HTTP(S) server for the dashboard.
      */

package/dist/index.d.ts

@@ -159,11 +159,29 @@ declare class AuditLog {
     private readonly maxTotalSizeBytes;
     private readonly maxEntries;
     private rotationInFlight;
+    private readonly pendingWrites;
     constructor(storage: StorageBackend, masterKey: Uint8Array, config?: AuditLogConfig);
     /**
      * Append an audit entry.
+     *
+     * The on-disk persist is async and tracked via `pendingWrites`. Long-lived
+     * callers (the main MCP server) can ignore that tracking and let writes
+     * drain naturally. Short-lived callers — the `sanctuary secrets` CLI which
+     * `process.exit()`s immediately after returning from a broker mutation —
+     * MUST await `flush()` before exiting, or in-flight writes get killed
+     * with the event loop and the entry is silently lost. That was the
+     * v0.10.0-rc.2 soak failure mode where `secrets audit` returned empty
+     * after a clean 7-verb lifecycle.
      */
     append(layer: AuditEntry["layer"], operation: string, identityId: string, details?: Record<string, unknown>, result?: "success" | "failure"): void;
+    /**
+     * Wait for every in-flight `append()` persist (and its rotation pass) to
+     * settle. Safe to call multiple times — newly-appended entries during a
+     * flush are also awaited. Re-entrant only at the granularity of "drain
+     * everything queued so far". Short-lived CLIs MUST call this before
+     * `process.exit()` to keep audit writes durable.
+     */
+    flush(): Promise<void>;
     private persistEntry;
     /**
      * Prune oldest audit entries when storage exceeds configured limits.
@@ -2853,6 +2871,24 @@ declare class DashboardApprovalChannel implements ApprovalChannel {
     private rateLimits;
     /** Whether the dashboard is running in standalone mode (no MCP server) */
     private _standaloneMode;
+    /**
+     * v0.10.2: when set, requests from loopback addresses (127.0.0.1 / ::1)
+     * are treated as authenticated without requiring a Bearer token or
+     * dashboard session cookie. Only the `startStandaloneDashboard` boot
+     * path enables this, and ONLY after the supplied passphrase successfully
+     * decrypts at least one stored identity — proving the caller already
+     * holds the primary secret that protects every piece of Sanctuary state.
+     *
+     * Rationale: the dashboard auth token is a dashboard-access credential
+     * layered on top of the master-key unlock. Once the operator has already
+     * presented the passphrase on the command line (terminal-side auth), a
+     * second login prompt in the auto-opened browser just trains users to
+     * paste secrets into web forms — the exact habit Sanctuary exists to
+     * discourage. Remote (non-loopback) callers still require the bearer
+     * token, so this is a localhost-only ergonomics unlock, not a network
+     * policy change.
+     */
+    private _autoAuthLocalhost;
     constructor(config: DashboardConfig);
     /**
      * Inject dependencies after construction.
@@ -2874,6 +2910,21 @@ declare class DashboardApprovalChannel implements ApprovalChannel {
      * Exposed via /api/status so the frontend can show an appropriate banner.
      */
     setStandaloneMode(standalone: boolean): void;
+    /**
+     * v0.10.2: enable (or disable) the loopback auto-auth fast path. See
+     * {@link _autoAuthLocalhost} for the rationale and threat model. Callers
+     * should gate this on both (a) the dashboard host being a loopback
+     * interface and (b) the master-key unlock having succeeded against
+     * on-disk state.
+     */
+    setAutoAuthLocalhost(enabled: boolean): void;
+    /**
+     * v0.10.2: is this request from a loopback interface? We treat the
+     * standard IPv4/IPv6 loopback addresses plus the IPv4-mapped IPv6 form
+     * as loopback so LAN clients never accidentally hit the unauthenticated
+     * fast path even on hosts where the HTTP server binds 0.0.0.0.
+     */
+    private isLoopbackRequest;
     /**
      * Start the HTTP(S) server for the dashboard.
      */

package/dist/index.js

@@ -1978,6 +1978,7 @@ var AuditLog = class {
   maxTotalSizeBytes;
   maxEntries;
   rotationInFlight = false;
+  pendingWrites = /* @__PURE__ */ new Set();
   constructor(storage, masterKey, config) {
     this.storage = storage;
     this.encryptionKey = derivePurposeKey(masterKey, "audit-log");
@@ -1986,6 +1987,15 @@ var AuditLog = class {
   }
   /**
    * Append an audit entry.
+   *
+   * The on-disk persist is async and tracked via `pendingWrites`. Long-lived
+   * callers (the main MCP server) can ignore that tracking and let writes
+   * drain naturally. Short-lived callers — the `sanctuary secrets` CLI which
+   * `process.exit()`s immediately after returning from a broker mutation —
+   * MUST await `flush()` before exiting, or in-flight writes get killed
+   * with the event loop and the entry is silently lost. That was the
+   * v0.10.0-rc.2 soak failure mode where `secrets audit` returned empty
+   * after a clean 7-verb lifecycle.
    */
   append(layer, operation, identityId, details, result = "success") {
     const entry = {
@@ -1997,8 +2007,22 @@ var AuditLog = class {
       details
     };
     this.entries.push(entry);
-    this.persistEntry(entry).catch(() => {
+    const writePromise = this.persistEntry(entry).catch(() => {
     });
+    this.pendingWrites.add(writePromise);
+    void writePromise.finally(() => this.pendingWrites.delete(writePromise));
+  }
+  /**
+   * Wait for every in-flight `append()` persist (and its rotation pass) to
+   * settle. Safe to call multiple times — newly-appended entries during a
+   * flush are also awaited. Re-entrant only at the granularity of "drain
+   * everything queued so far". Short-lived CLIs MUST call this before
+   * `process.exit()` to keep audit writes durable.
+   */
+  async flush() {
+    while (this.pendingWrites.size > 0) {
+      await Promise.allSettled([...this.pendingWrites]);
+    }
   }
   async persistEntry(entry) {
     const key = `${Date.now()}-${this.counter++}`;
@@ -2009,7 +2033,7 @@ var AuditLog = class {
       key,
       stringToBytes(JSON.stringify(encrypted))
     );
-    this.maybeRotate().catch(() => {
+    await this.maybeRotate().catch(() => {
     });
   }
   /**
@@ -8676,6 +8700,24 @@ var DashboardApprovalChannel = class {
   rateLimits = /* @__PURE__ */ new Map();
   /** Whether the dashboard is running in standalone mode (no MCP server) */
   _standaloneMode = false;
+  /**
+   * v0.10.2: when set, requests from loopback addresses (127.0.0.1 / ::1)
+   * are treated as authenticated without requiring a Bearer token or
+   * dashboard session cookie. Only the `startStandaloneDashboard` boot
+   * path enables this, and ONLY after the supplied passphrase successfully
+   * decrypts at least one stored identity — proving the caller already
+   * holds the primary secret that protects every piece of Sanctuary state.
+   *
+   * Rationale: the dashboard auth token is a dashboard-access credential
+   * layered on top of the master-key unlock. Once the operator has already
+   * presented the passphrase on the command line (terminal-side auth), a
+   * second login prompt in the auto-opened browser just trains users to
+   * paste secrets into web forms — the exact habit Sanctuary exists to
+   * discourage. Remote (non-loopback) callers still require the bearer
+   * token, so this is a localhost-only ergonomics unlock, not a network
+   * policy change.
+   */
+  _autoAuthLocalhost = false;
   constructor(config) {
     this.config = config;
     this.authToken = config.auth_token;
@@ -8711,6 +8753,26 @@ var DashboardApprovalChannel = class {
   setStandaloneMode(standalone) {
     this._standaloneMode = standalone;
   }
+  /**
+   * v0.10.2: enable (or disable) the loopback auto-auth fast path. See
+   * {@link _autoAuthLocalhost} for the rationale and threat model. Callers
+   * should gate this on both (a) the dashboard host being a loopback
+   * interface and (b) the master-key unlock having succeeded against
+   * on-disk state.
+   */
+  setAutoAuthLocalhost(enabled) {
+    this._autoAuthLocalhost = enabled;
+  }
+  /**
+   * v0.10.2: is this request from a loopback interface? We treat the
+   * standard IPv4/IPv6 loopback addresses plus the IPv4-mapped IPv6 form
+   * as loopback so LAN clients never accidentally hit the unauthenticated
+   * fast path even on hosts where the HTTP server binds 0.0.0.0.
+   */
+  isLoopbackRequest(req) {
+    const addr = this.getRemoteAddr(req);
+    return addr === "127.0.0.1" || addr === "::1" || addr === "localhost";
+  }
   /**
    * Start the HTTP(S) server for the dashboard.
    */
@@ -8860,6 +8922,9 @@ var DashboardApprovalChannel = class {
    */
   checkAuth(req, url, res) {
     if (!this.authToken) return true;
+    if (this._autoAuthLocalhost && this.isLoopbackRequest(req)) {
+      return true;
+    }
     const authHeader = req.headers.authorization;
     if (authHeader) {
       const parts = authHeader.split(" ");
@@ -8885,6 +8950,9 @@ var DashboardApprovalChannel = class {
    */
   isAuthenticated(req, url) {
     if (!this.authToken) return true;
+    if (this._autoAuthLocalhost && this.isLoopbackRequest(req)) {
+      return true;
+    }
     const authHeader = req.headers.authorization;
     if (authHeader) {
       const parts = authHeader.split(" ");