@sanctuary-framework/mcp-server 0.5.0 → 0.5.2

package/dist/index.d.cts

@@ -58,6 +58,9 @@ interface SanctuaryConfig {
 }
 /**
  * Load configuration from file, falling back to defaults.
+ *
+ * Precedence (highest wins): CLI flags > env vars > config file > defaults
+ * This matches the standard config precedence pattern used by most tools.
  */
 declare function loadConfig(configPath?: string): Promise<SanctuaryConfig>;
 
@@ -1993,8 +1996,11 @@ declare class DashboardApprovalChannel implements ApprovalChannel {
     private baseline;
     private auditLog;
     private dashboardHTML;
+    private loginHTML;
     private authToken;
     private useTLS;
+    /** Session TTL: longer for localhost, shorter for remote */
+    private sessionTTLMs;
     /** SEC-012: Short-lived session store. Sessions replace URL query tokens. */
     private sessions;
     private sessionCleanupTimer;
@@ -2034,6 +2040,15 @@ declare class DashboardApprovalChannel implements ApprovalChannel {
      * Returns true if auth passes, false if blocked (response already sent).
      */
     private checkAuth;
+    /**
+     * Check if a request is authenticated WITHOUT sending a response.
+     * Used to decide between login page vs dashboard for GET /.
+     */
+    private isAuthenticated;
+    /**
+     * Parse a specific cookie value from the request.
+     */
+    private parseCookie;
     /**
      * Create a short-lived session by exchanging the long-lived auth token
      * (provided in the Authorization header) for a session ID.
@@ -2071,6 +2086,7 @@ declare class DashboardApprovalChannel implements ApprovalChannel {
      * normal checkAuth flow.
      */
     private handleSessionExchange;
+    private serveLoginPage;
     private serveDashboard;
     private handleSSE;
     private handleStatus;
@@ -2117,6 +2133,15 @@ declare class DashboardApprovalChannel implements ApprovalChannel {
      * Broadcast current protection status to connected dashboards.
      */
     broadcastProtectionStatus(data: Record<string, unknown>): void;
+    /**
+     * Create a pre-authenticated URL for the dashboard.
+     * Used by the sanctuary_dashboard_open tool and at startup.
+     */
+    createSessionUrl(): string;
+    /**
+     * Get the base URL for the dashboard.
+     */
+    getBaseUrl(): string;
     /** Get the number of pending requests */
     get pendingCount(): number;
     /** Get the number of connected SSE clients */

package/dist/index.d.ts

@@ -58,6 +58,9 @@ interface SanctuaryConfig {
 }
 /**
  * Load configuration from file, falling back to defaults.
+ *
+ * Precedence (highest wins): CLI flags > env vars > config file > defaults
+ * This matches the standard config precedence pattern used by most tools.
  */
 declare function loadConfig(configPath?: string): Promise<SanctuaryConfig>;
 
@@ -1993,8 +1996,11 @@ declare class DashboardApprovalChannel implements ApprovalChannel {
     private baseline;
     private auditLog;
     private dashboardHTML;
+    private loginHTML;
     private authToken;
     private useTLS;
+    /** Session TTL: longer for localhost, shorter for remote */
+    private sessionTTLMs;
     /** SEC-012: Short-lived session store. Sessions replace URL query tokens. */
     private sessions;
     private sessionCleanupTimer;
@@ -2034,6 +2040,15 @@ declare class DashboardApprovalChannel implements ApprovalChannel {
      * Returns true if auth passes, false if blocked (response already sent).
      */
     private checkAuth;
+    /**
+     * Check if a request is authenticated WITHOUT sending a response.
+     * Used to decide between login page vs dashboard for GET /.
+     */
+    private isAuthenticated;
+    /**
+     * Parse a specific cookie value from the request.
+     */
+    private parseCookie;
     /**
      * Create a short-lived session by exchanging the long-lived auth token
      * (provided in the Authorization header) for a session ID.
@@ -2071,6 +2086,7 @@ declare class DashboardApprovalChannel implements ApprovalChannel {
      * normal checkAuth flow.
      */
     private handleSessionExchange;
+    private serveLoginPage;
     private serveDashboard;
     private handleSSE;
     private handleStatus;
@@ -2117,6 +2133,15 @@ declare class DashboardApprovalChannel implements ApprovalChannel {
      * Broadcast current protection status to connected dashboards.
      */
     broadcastProtectionStatus(data: Record<string, unknown>): void;
+    /**
+     * Create a pre-authenticated URL for the dashboard.
+     * Used by the sanctuary_dashboard_open tool and at startup.
+     */
+    createSessionUrl(): string;
+    /**
+     * Get the base URL for the dashboard.
+     */
+    getBaseUrl(): string;
     /** Get the number of pending requests */
     get pendingCount(): number;
     /** Get the number of connected SSE clients */

package/dist/index.js

@@ -254,7 +254,18 @@ function defaultConfig() {
   };
 }
 async function loadConfig(configPath) {
-  const config = defaultConfig();
+  let config = defaultConfig();
+  const storagePath = process.env.SANCTUARY_STORAGE_PATH ?? config.storage_path;
+  const path = configPath ?? join(storagePath, "sanctuary.json");
+  try {
+    const raw = await readFile(path, "utf-8");
+    const fileConfig = JSON.parse(raw);
+    config = deepMerge(config, fileConfig);
+  } catch (err) {
+    if (err instanceof Error && err.message.includes("unimplemented features")) {
+      throw err;
+    }
+  }
   if (process.env.SANCTUARY_STORAGE_PATH) {
     config.storage_path = process.env.SANCTUARY_STORAGE_PATH;
   }
@@ -267,6 +278,9 @@ async function loadConfig(configPath) {
   if (process.env.SANCTUARY_DASHBOARD_ENABLED === "true") {
     config.dashboard.enabled = true;
   }
+  if (process.env.SANCTUARY_DASHBOARD_ENABLED === "false") {
+    config.dashboard.enabled = false;
+  }
   if (process.env.SANCTUARY_DASHBOARD_PORT) {
     config.dashboard.port = parseInt(process.env.SANCTUARY_DASHBOARD_PORT, 10);
   }
@@ -285,6 +299,9 @@ async function loadConfig(configPath) {
   if (process.env.SANCTUARY_WEBHOOK_ENABLED === "true") {
     config.webhook.enabled = true;
   }
+  if (process.env.SANCTUARY_WEBHOOK_ENABLED === "false") {
+    config.webhook.enabled = false;
+  }
   if (process.env.SANCTUARY_WEBHOOK_URL) {
     config.webhook.url = process.env.SANCTUARY_WEBHOOK_URL;
   }
@@ -297,19 +314,9 @@ async function loadConfig(configPath) {
   if (process.env.SANCTUARY_WEBHOOK_CALLBACK_HOST) {
     config.webhook.callback_host = process.env.SANCTUARY_WEBHOOK_CALLBACK_HOST;
   }
-  const path = configPath ?? join(config.storage_path, "sanctuary.json");
-  try {
-    const raw = await readFile(path, "utf-8");
-    const fileConfig = JSON.parse(raw);
-    const merged = deepMerge(config, fileConfig);
-    validateConfig(merged);
-    return merged;
-  } catch (err) {
-    if (err instanceof Error && err.message.includes("unimplemented features")) {
-      throw err;
-    }
-    return config;
-  }
+  config.version = PKG_VERSION;
+  validateConfig(config);
+  return config;
 }
 async function saveConfig(config, configPath) {
   const path = join(config.storage_path, "sanctuary.json");
@@ -4048,6 +4055,181 @@ var AutoApproveChannel = class {
 };
 
 // src/principal-policy/dashboard-html.ts
+function generateLoginHTML(options) {
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Sanctuary \u2014 Login</title>
+<link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;600&display=swap" rel="stylesheet">
+<style>
+  :root {
+    --bg: #0d1117;
+    --surface: #161b22;
+    --border: #30363d;
+    --text-primary: #e6edf3;
+    --text-secondary: #8b949e;
+    --green: #3fb950;
+    --red: #f85149;
+    --blue: #58a6ff;
+    --mono: 'JetBrains Mono', 'Fira Code', 'Consolas', monospace;
+    --sans: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+    --radius: 6px;
+  }
+  * { box-sizing: border-box; margin: 0; padding: 0; }
+  html, body { width: 100%; height: 100%; }
+  body {
+    font-family: var(--sans);
+    background: var(--bg);
+    color: var(--text-primary);
+    display: flex;
+    align-items: center;
+    justify-content: center;
+  }
+  .login-container {
+    width: 100%;
+    max-width: 400px;
+    padding: 40px 32px;
+    background: var(--surface);
+    border: 1px solid var(--border);
+    border-radius: 12px;
+  }
+  .login-logo {
+    text-align: center;
+    font-size: 20px;
+    font-weight: 700;
+    letter-spacing: -0.5px;
+    margin-bottom: 8px;
+  }
+  .login-logo span { color: var(--blue); }
+  .login-version {
+    text-align: center;
+    font-size: 11px;
+    color: var(--text-secondary);
+    font-family: var(--mono);
+    margin-bottom: 32px;
+  }
+  .login-label {
+    display: block;
+    font-size: 13px;
+    font-weight: 600;
+    color: var(--text-secondary);
+    margin-bottom: 8px;
+  }
+  .login-input {
+    width: 100%;
+    padding: 10px 14px;
+    background: var(--bg);
+    border: 1px solid var(--border);
+    border-radius: var(--radius);
+    color: var(--text-primary);
+    font-family: var(--mono);
+    font-size: 14px;
+    outline: none;
+    transition: border-color 0.15s;
+  }
+  .login-input:focus { border-color: var(--blue); }
+  .login-input::placeholder { color: var(--text-secondary); opacity: 0.5; }
+  .login-btn {
+    width: 100%;
+    margin-top: 20px;
+    padding: 10px;
+    background: var(--blue);
+    color: var(--bg);
+    border: none;
+    border-radius: var(--radius);
+    font-size: 14px;
+    font-weight: 600;
+    cursor: pointer;
+    transition: opacity 0.15s;
+    font-family: var(--sans);
+  }
+  .login-btn:hover { opacity: 0.9; }
+  .login-btn:disabled { opacity: 0.5; cursor: not-allowed; }
+  .login-error {
+    margin-top: 16px;
+    padding: 10px 14px;
+    background: rgba(248, 81, 73, 0.1);
+    border: 1px solid var(--red);
+    border-radius: var(--radius);
+    font-size: 12px;
+    color: var(--red);
+    display: none;
+  }
+  .login-hint {
+    margin-top: 24px;
+    padding-top: 16px;
+    border-top: 1px solid var(--border);
+    font-size: 11px;
+    color: var(--text-secondary);
+    line-height: 1.5;
+  }
+  .login-hint code {
+    font-family: var(--mono);
+    background: var(--bg);
+    padding: 1px 4px;
+    border-radius: 3px;
+    font-size: 10px;
+  }
+</style>
+</head>
+<body>
+<div class="login-container">
+  <div class="login-logo"><span>&#9670;</span> SANCTUARY</div>
+  <div class="login-version">Principal Dashboard v${options.serverVersion}</div>
+  <form id="loginForm" onsubmit="return handleLogin(event)">
+    <label class="login-label" for="tokenInput">Dashboard Auth Token</label>
+    <input class="login-input" type="password" id="tokenInput"
+           placeholder="Enter your auth token" autocomplete="off" autofocus required>
+    <button class="login-btn" type="submit" id="loginBtn">Open Dashboard</button>
+  </form>
+  <div class="login-error" id="loginError"></div>
+  <div class="login-hint">
+    Your token is set via <code>SANCTUARY_DASHBOARD_AUTH_TOKEN</code> environment variable,
+    or check your server's startup output.
+  </div>
+</div>
+<script>
+async function handleLogin(e) {
+  e.preventDefault();
+  var btn = document.getElementById('loginBtn');
+  var errEl = document.getElementById('loginError');
+  var token = document.getElementById('tokenInput').value.trim();
+  if (!token) return false;
+  btn.disabled = true;
+  btn.textContent = 'Authenticating...';
+  errEl.style.display = 'none';
+  try {
+    var resp = await fetch('/auth/session', {
+      method: 'POST',
+      headers: { 'Authorization': 'Bearer ' + token }
+    });
+    if (!resp.ok) {
+      var data = await resp.json().catch(function() { return {}; });
+      throw new Error(data.error || 'Authentication failed');
+    }
+    var result = await resp.json();
+    // Store token in sessionStorage for auto-renewal inside the dashboard
+    try { sessionStorage.setItem('sanctuary_token', token); } catch(_) {}
+    // Set session cookie
+    var maxAge = result.expires_in_seconds || 300;
+    document.cookie = 'sanctuary_session=' + result.session_id +
+      '; path=/; SameSite=Strict; max-age=' + maxAge;
+    // Reload to enter the dashboard
+    window.location.reload();
+  } catch (err) {
+    errEl.textContent = err.message || 'Authentication failed. Check your token.';
+    errEl.style.display = 'block';
+    btn.disabled = false;
+    btn.textContent = 'Open Dashboard';
+  }
+  return false;
+}
+</script>
+</body>
+</html>`;
+}
 function generateDashboardHTML(options) {
   return `<!DOCTYPE html>
 <html lang="en">
@@ -4917,7 +5099,9 @@ function generateDashboardHTML(options) {
   // \u2500\u2500 Configuration \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
 
   const TIMEOUT_SECONDS = ${options.timeoutSeconds};
-  const AUTH_TOKEN = ${options.authToken ? JSON.stringify(options.authToken) : "null"};
+  // AUTH_TOKEN: embedded token (for direct session access) or from sessionStorage (login page flow)
+  const EMBEDDED_TOKEN = ${options.authToken ? JSON.stringify(options.authToken) : "null"};
+  const AUTH_TOKEN = EMBEDDED_TOKEN || (function() { try { return sessionStorage.getItem('sanctuary_token'); } catch(_) { return null; } })();
   const MAX_ACTIVITY_ITEMS = 100;
   const MAX_THREAT_ITEMS = 20;
 
@@ -4932,6 +5116,7 @@ function generateDashboardHTML(options) {
   const activityItems = [];
   const threatItems = [];
   let sovereigntyScore = 85;
+  let sessionRenewalTimer = null;
 
   // \u2500\u2500 Auth Helpers (SEC-012) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
 
@@ -4947,6 +5132,11 @@ function generateDashboardHTML(options) {
     return url + sep + 'session=' + SESSION_ID;
   }
 
+  function setCookie(sessionId, maxAge) {
+    document.cookie = 'sanctuary_session=' + sessionId +
+      '; path=/; SameSite=Strict; max-age=' + maxAge;
+  }
+
   async function exchangeSession() {
     if (!AUTH_TOKEN) return;
     try {
@@ -4954,14 +5144,35 @@ function generateDashboardHTML(options) {
       if (resp.ok) {
         const data = await resp.json();
         SESSION_ID = data.session_id;
-        const refreshMs = (data.expires_in_seconds || 300) * 800;
-        setTimeout(() => { exchangeSession(); reconnectSSE(); }, refreshMs);
+        var ttl = data.expires_in_seconds || 300;
+        // Update cookie with new session
+        setCookie(SESSION_ID, ttl);
+        // Schedule renewal at 80% of TTL
+        if (sessionRenewalTimer) clearTimeout(sessionRenewalTimer);
+        sessionRenewalTimer = setTimeout(function() {
+          exchangeSession().then(function() { reconnectSSE(); });
+        }, ttl * 800);
+      } else if (resp.status === 401) {
+        // Token invalid or expired \u2014 show non-destructive re-login overlay
+        showSessionExpired();
       }
     } catch (e) {
-      // Retry on next connect
+      // Network error \u2014 retry in 30s
+      if (sessionRenewalTimer) clearTimeout(sessionRenewalTimer);
+      sessionRenewalTimer = setTimeout(function() {
+        exchangeSession().then(function() { reconnectSSE(); });
+      }, 30000);
     }
   }
 
+  function showSessionExpired() {
+    // Clear stored token
+    try { sessionStorage.removeItem('sanctuary_token'); } catch(_) {}
+    // Redirect to login page
+    document.cookie = 'sanctuary_session=; path=/; max-age=0';
+    window.location.reload();
+  }
+
   // \u2500\u2500 UI Utilities \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
 
   function esc(s) {
@@ -5434,7 +5645,8 @@ function generateDashboardHTML(options) {
 }
 
 // src/principal-policy/dashboard.ts
-var SESSION_TTL_MS = 5 * 60 * 1e3;
+var SESSION_TTL_REMOTE_MS = 5 * 60 * 1e3;
+var SESSION_TTL_LOCAL_MS = 24 * 60 * 60 * 1e3;
 var MAX_SESSIONS = 1e3;
 var RATE_LIMIT_WINDOW_MS = 6e4;
 var RATE_LIMIT_GENERAL = 120;
@@ -5449,8 +5661,11 @@ var DashboardApprovalChannel = class {
   baseline = null;
   auditLog = null;
   dashboardHTML;
+  loginHTML;
   authToken;
   useTLS;
+  /** Session TTL: longer for localhost, shorter for remote */
+  sessionTTLMs;
   /** SEC-012: Short-lived session store. Sessions replace URL query tokens. */
   sessions = /* @__PURE__ */ new Map();
   sessionCleanupTimer = null;
@@ -5460,11 +5675,14 @@ var DashboardApprovalChannel = class {
     this.config = config;
     this.authToken = config.auth_token;
     this.useTLS = !!(config.tls?.cert_path && config.tls?.key_path);
+    const isLocalhost = config.host === "127.0.0.1" || config.host === "localhost" || config.host === "::1";
+    this.sessionTTLMs = isLocalhost ? SESSION_TTL_LOCAL_MS : SESSION_TTL_REMOTE_MS;
     this.dashboardHTML = generateDashboardHTML({
       timeoutSeconds: config.timeout_seconds,
       serverVersion: SANCTUARY_VERSION,
       authToken: this.authToken
     });
+    this.loginHTML = generateLoginHTML({ serverVersion: SANCTUARY_VERSION });
     this.sessionCleanupTimer = setInterval(() => this.cleanupSessions(), 6e4);
   }
   /**
@@ -5494,25 +5712,26 @@ var DashboardApprovalChannel = class {
       const protocol = this.useTLS ? "https" : "http";
       const baseUrl = `${protocol}://${this.config.host}:${this.config.port}`;
       this.httpServer.listen(this.config.port, this.config.host, () => {
-        if (this.authToken) {
-          const hint = this.authToken.slice(0, 4) + "..." + this.authToken.slice(-4);
-          process.stderr.write(
-            `
+        process.stderr.write(
+          `
   Sanctuary Principal Dashboard: ${baseUrl}
 `
-          );
+        );
+        if (this.authToken) {
+          const sessionUrl = this.createSessionUrl();
           process.stderr.write(
-            `  Auth required (token: ${hint}). Use Authorization: Bearer <TOKEN> header.
-
+            `  Quick open: ${sessionUrl}
 `
           );
-        } else {
+          const hint = this.authToken.slice(0, 4) + "..." + this.authToken.slice(-4);
           process.stderr.write(
-            `
-  Sanctuary Principal Dashboard: ${baseUrl}
+            `  Auth token: ${hint}
 
 `
           );
+        } else {
+          process.stderr.write(`
+`);
         }
         resolve();
       });
@@ -5616,10 +5835,47 @@ var DashboardApprovalChannel = class {
     if (sessionId && this.validateSession(sessionId)) {
       return true;
     }
+    const cookieSession = this.parseCookie(req, "sanctuary_session");
+    if (cookieSession && this.validateSession(cookieSession)) {
+      return true;
+    }
     res.writeHead(401, { "Content-Type": "application/json" });
     res.end(JSON.stringify({ error: "Unauthorized \u2014 use Authorization: Bearer header or a valid session" }));
     return false;
   }
+  /**
+   * Check if a request is authenticated WITHOUT sending a response.
+   * Used to decide between login page vs dashboard for GET /.
+   */
+  isAuthenticated(req, url) {
+    if (!this.authToken) return true;
+    const authHeader = req.headers.authorization;
+    if (authHeader) {
+      const parts = authHeader.split(" ");
+      if (parts.length === 2 && parts[0] === "Bearer" && parts[1] === this.authToken) {
+        return true;
+      }
+    }
+    const sessionId = url.searchParams.get("session");
+    if (sessionId && this.validateSession(sessionId)) return true;
+    const cookieSession = this.parseCookie(req, "sanctuary_session");
+    if (cookieSession && this.validateSession(cookieSession)) return true;
+    return false;
+  }
+  /**
+   * Parse a specific cookie value from the request.
+   */
+  parseCookie(req, name) {
+    const header = req.headers.cookie;
+    if (!header) return null;
+    for (const part of header.split(";")) {
+      const [key, ...rest] = part.split("=");
+      if (key?.trim() === name) {
+        return rest.join("=").trim();
+      }
+    }
+    return null;
+  }
   // ── Session Management (SEC-012) ──────────────────────────────────
   /**
    * Create a short-lived session by exchanging the long-lived auth token
@@ -5640,7 +5896,7 @@ var DashboardApprovalChannel = class {
     this.sessions.set(id, {
       id,
       created_at: now,
-      expires_at: now + SESSION_TTL_MS
+      expires_at: now + this.sessionTTLMs
     });
     return id;
   }
@@ -5739,13 +5995,26 @@ var DashboardApprovalChannel = class {
       res.end();
       return;
     }
-    if (!this.checkAuth(req, url, res)) return;
-    if (!this.checkRateLimit(req, res, "general")) return;
-    try {
-      if (method === "POST" && url.pathname === "/auth/session") {
+    if (method === "POST" && url.pathname === "/auth/session") {
+      if (!this.checkRateLimit(req, res, "general")) return;
+      try {
         this.handleSessionExchange(req, res);
+      } catch {
+        res.writeHead(500, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "Internal server error" }));
+      }
+      return;
+    }
+    if (method === "GET" && url.pathname === "/" && this.authToken) {
+      if (!this.isAuthenticated(req, url)) {
+        if (!this.checkRateLimit(req, res, "general")) return;
+        this.serveLoginPage(res);
         return;
       }
+    }
+    if (!this.checkAuth(req, url, res)) return;
+    if (!this.checkRateLimit(req, res, "general")) return;
+    try {
       if (method === "GET" && url.pathname === "/") {
         this.serveDashboard(res);
       } else if (method === "GET" && url.pathname === "/events") {
@@ -5802,12 +6071,23 @@ var DashboardApprovalChannel = class {
       return;
     }
     const sessionId = this.createSession();
-    res.writeHead(200, { "Content-Type": "application/json" });
+    const ttlSeconds = Math.floor(this.sessionTTLMs / 1e3);
+    res.writeHead(200, {
+      "Content-Type": "application/json",
+      "Set-Cookie": `sanctuary_session=${sessionId}; Path=/; SameSite=Strict; Max-Age=${ttlSeconds}`
+    });
     res.end(JSON.stringify({
       session_id: sessionId,
-      expires_in_seconds: SESSION_TTL_MS / 1e3
+      expires_in_seconds: ttlSeconds
     }));
   }
+  serveLoginPage(res) {
+    res.writeHead(200, {
+      "Content-Type": "text/html; charset=utf-8",
+      "Cache-Control": "no-cache, no-store"
+    });
+    res.end(this.loginHTML);
+  }
   serveDashboard(res) {
     res.writeHead(200, {
       "Content-Type": "text/html; charset=utf-8",
@@ -5983,6 +6263,22 @@ data: ${JSON.stringify(data)}
   broadcastProtectionStatus(data) {
     this.broadcastSSE("protection-status", data);
   }
+  /**
+   * Create a pre-authenticated URL for the dashboard.
+   * Used by the sanctuary_dashboard_open tool and at startup.
+   */
+  createSessionUrl() {
+    const sessionId = this.createSession();
+    const protocol = this.useTLS ? "https" : "http";
+    return `${protocol}://${this.config.host}:${this.config.port}/?session=${sessionId}`;
+  }
+  /**
+   * Get the base URL for the dashboard.
+   */
+  getBaseUrl() {
+    const protocol = this.useTLS ? "https" : "http";
+    return `${protocol}://${this.config.host}:${this.config.port}`;
+  }
   /** Get the number of pending requests */
   get pendingCount() {
     return this.pending.size;
@@ -11852,6 +12148,32 @@ async function createSanctuaryServer(options) {
   } : void 0;
   const gate = new ApprovalGate(policy, baseline, approvalChannel, auditLog, injectionDetector, onInjectionAlert);
   const policyTools = createPrincipalPolicyTools(policy, baseline, auditLog);
+  const dashboardTools = [];
+  if (dashboard) {
+    dashboardTools.push({
+      name: "sanctuary/dashboard_open",
+      description: "Generate a one-click URL to open the Principal Dashboard in a browser. Returns a pre-authenticated link \u2014 no manual token entry needed.",
+      inputSchema: {
+        type: "object",
+        properties: {}
+      },
+      handler: async () => {
+        const url = dashboard.createSessionUrl();
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({
+                dashboard_url: url,
+                base_url: dashboard.getBaseUrl(),
+                note: "Click the dashboard_url to open the Principal Dashboard. The session is pre-authenticated."
+              }, null, 2)
+            }
+          ]
+        };
+      }
+    });
+  }
   let allTools = [
     ...l1Tools,
     ...l2Tools,
@@ -11865,6 +12187,7 @@ async function createSanctuaryServer(options) {
     ...auditTools,
     ...contextGateTools,
     ...hardeningTools,
+    ...dashboardTools,
     manifestTool
   ];
   allTools = allTools.map((tool) => ({