sentinelayer-cli 0.46.3 → 0.46.5

package/README.md

@@ -46,6 +46,22 @@ sl watch run-events --run-id <run-id>
 
 Windows PowerShell note: `sl` is a built-in alias for `Set-Location`. Use `sentinelayer-cli` (or short alias `slc`) instead.
 
+### Human sign-in and agent identity
+
+`sl auth login --skip-browser-open` prints the approval URL before waiting;
+in JSON mode the URL goes to stderr. A server outage during `auth status` is
+unavailable validation, not logout. Do not delete credential encryption keys
+or log out to repair a keyring/file-permission error.
+
+An admitted agent receives its own AIdenID email, Ed25519-backed passport and
+room-scoped credential after human approval. Its email and cryptographic
+identity remain visible on reconnect; email alone never grants access.
+An interrupted claim or missing credential can be recovered with the retained
+agent key. For a stale active credential, repeat the original join with
+`--recover-admission`, the same `--goal`, `--scope` and `--ttl`.
+Recovery requires API support, preserves the original expiry, and cannot revive
+revoked, stopped or expired permissions. It is not TTL renewal.
+
 ## MCP Live Entry Points And Incident Response
 
 Live MCP entry points:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sentinelayer-cli",
-  "version": "0.46.3",
+  "version": "0.46.5",
   "description": "Scaffold Sentinelayer spec/prompt/guide artifacts with secure browser auth and token bootstrap.",
   "type": "module",
   "scripts": {

package/src/auth/gate.js

@@ -5,6 +5,7 @@ import fs from "node:fs";
 import path from "node:path";
 import pc from "picocolors";
 import { resolveActiveAuthSession } from "./service.js";
+import { readStoredSessionMetadata } from "./session-store.js";
 import { resolveAgentAdmissionTarget } from "../session/admission-auth.js";
 import { authLoginHint } from "../ui/command-hints.js";
 import { isAuthenticated } from "./credential-destinations.js";
@@ -378,7 +379,9 @@ export async function checkAuthGate(args) {
         resolveError = "session_invalid";
       }
     } else {
-      resolveError = "no_session";
+      // A keyring/decryption failure leaves the metadata intact. That is not
+      // absence, and recommending logout would destroy recoverable sign-in.
+      resolveError = (await readStoredSessionMetadata()) ? "session_token_missing" : "no_session";
     }
   } catch (error) {
     resolveError = error instanceof Error ? `session_read_error: ${error.message}` : "session_read_error";
@@ -405,15 +408,19 @@ export function printAuthRequired(failureReason = null) {
   if (reason === "session_expired") {
     console.error("  Your stored session has expired. Log in again:");
   } else if (reason === "session_token_missing") {
-    console.error("  Your session metadata is present but the token is missing");
-    console.error("  (likely a keyring read failure or mismatched storage).");
+    console.error("  Your session metadata is present but its credential cannot be read.");
+    console.error("  Check the current user/home, keyring, encryption key and file permissions.");
+    console.error("  Your stored credentials were not cleared; repair storage before signing in again.");
     console.error("");
-    console.error("  " + pc.yellow("Fix:") + " log out to clear the stale metadata, then log in:");
-    console.error("    " + pc.cyan("sentinelayer-cli auth logout"));
+    process.exitCode = 1;
+    return;
   } else if (reason && reason.startsWith("session_read_error")) {
     console.error("  Session read failed: " + pc.yellow(reason.replace(/^session_read_error:\s*/, "")));
-    console.error("  Log out and back in to reset local state:");
-    console.error("    " + pc.cyan("sentinelayer-cli auth logout"));
+    console.error("  Check the current user/home and credential-file permissions.");
+    console.error("  Your stored credentials were not cleared; do not log out to repair a read error.");
+    console.error("");
+    process.exitCode = 1;
+    return;
   } else {
     console.error("  Log in to SentinelLayer to use CLI commands:");
   }

package/src/auth/service.js

@@ -7,6 +7,7 @@ import open from "open";
 import { loadConfig } from "../config/service.js";
 import { scopedAdmissionAuth } from "./admission-scope.js";
 import {
+  CredentialDestinationRefused,
   DEFAULT_API_URL,
   assertTrustedApiUrl,
   credentialFor,
@@ -453,6 +454,7 @@ async function rotateStoredApiTokenIfNeeded({
       tokenPrefix: issued.token_prefix || null,
       tokenExpiresAt: issued.expires_at || null,
       user: session.user,
+      aidenid: session.aidenid,
     },
     { homeDir }
   );
@@ -490,7 +492,8 @@ async function rotateStoredApiTokenIfNeeded({
  *   tokenTtlDays?: number,
  *   ide?: string,
  *   cliVersion?: string,
- *   homeDir?: string
+ *   homeDir?: string,
+ *   onAuthorize?: (details: { authorizeUrl: string, browserOpened: boolean }) => void | Promise<void>
  * }} [options]
  * @returns {Promise<{
  *   apiUrl: string,
@@ -521,6 +524,7 @@ export async function loginAndPersistSession({
   ide = DEFAULT_IDE_NAME,
   cliVersion = "",
   homeDir,
+  onAuthorize = () => {},
 } = {}) {
   const apiUrl = await resolveApiUrl({ cwd, env, explicitApiUrl, homeDir });
   // The token this flow issues is the user's, so the API that issues it must be the configured
@@ -548,6 +552,10 @@ export async function loginAndPersistSession({
     }
   }
 
+  // Headless hosts must receive the URL before approval polling can complete.
+  // The command renders this on stderr in JSON mode, keeping stdout parseable.
+  await onAuthorize({ authorizeUrl, browserOpened });
+
   const approval = await pollCliAuthSession({
     apiUrl,
     sessionId: String(session.session_id || "").trim(),
@@ -768,7 +776,8 @@ export async function resolveActiveAuthSession({
  *   homeDir?: string
  * }} [options]
  * @returns {Promise<{
- *   authenticated: boolean,
+ *   authenticated: boolean | null,
+ *   validation: "none" | "not_checked" | "verified" | "rejected" | "unavailable" | "storage_unavailable",
  *   apiUrl: string,
  *   source: string | null,
  *   storage: string | null,
@@ -805,20 +814,25 @@ export async function getAuthStatus({
   });
 
   if (!session) {
+    // Encrypted metadata can survive a missing/unreadable key or keyring.
+    // Distinguish recoverable storage from actual absence without creating a
+    // replacement key, validating remotely, or claiming authentication.
+    const stored = await readStoredSessionMetadata({ homeDir });
     return {
-      authenticated: false,
+      authenticated: stored ? null : false,
+      validation: stored ? "storage_unavailable" : "none",
       apiUrl: await resolveApiUrl({ cwd, env, explicitApiUrl, homeDir }),
-      source: null,
-      storage: null,
-      user: null,
-      aidenid: null,
+      source: stored ? "storage_unknown" : null,
+      storage: stored?.storage || null,
+      user: stored ? normalizeUser(stored.user || {}) : null,
+      aidenid: stored?.aidenid || null,
       remoteUser: null,
       remoteError: null,
       rotated: false,
-      tokenExpiresAt: null,
-      tokenPrefix: null,
-      tokenId: null,
-      filePath: null,
+      tokenExpiresAt: stored?.tokenExpiresAt || null,
+      tokenPrefix: stored?.tokenPrefix || null,
+      tokenId: stored?.tokenId || null,
+      filePath: stored?.filePath || null,
     };
   }
 
@@ -829,12 +843,12 @@ export async function getAuthStatus({
       remoteUser = normalizeUser(await fetchCurrentUser({ apiUrl: session.apiUrl, credential: session.credential }));
     } catch (error) {
       remoteError =
-        error instanceof SentinelayerApiError
+        error instanceof SentinelayerApiError || error instanceof CredentialDestinationRefused
           ? {
               code: error.code,
               message: error.message,
-              status: error.status,
-              requestId: error.requestId,
+              status: error instanceof CredentialDestinationRefused ? 403 : error.status,
+              requestId: error.requestId || null,
             }
           : {
               code: "UNKNOWN",
@@ -845,8 +859,13 @@ export async function getAuthStatus({
     }
   }
 
+  const validationUnavailable = remoteError && (
+    [408, 425, 429, 499].includes(remoteError.status) || remoteError.status >= 500
+  );
   return {
-    authenticated: !remoteError,
+    // Unknown remote health is neither a successful validation nor a logout.
+    authenticated: validationUnavailable ? null : !remoteError,
+    validation: validationUnavailable ? "unavailable" : remoteError ? "rejected" : checkRemote ? "verified" : "not_checked",
     apiUrl: session.apiUrl,
     source: session.source,
     storage: session.storage,

package/src/auth/session-store.js

@@ -135,60 +135,68 @@ function resolveLegacyCredentialsKeyPath({ homeDir } = {}) {
   return path.join(resolvedHome, ".sentinelayer", "credentials.key");
 }
 
-async function loadOrCreateFileKey({ homeDir } = {}) {
-  const keyPath = resolveCredentialsKeyPath({ homeDir });
-  const legacyKeyPath = resolveLegacyCredentialsKeyPath({ homeDir });
-  try {
-    const raw = await fsp.readFile(keyPath, "utf-8");
-    const key = Buffer.from(String(raw || "").trim(), "base64");
-    if (key.length === 32) {
-      return key;
-    }
-  } catch (error) {
-    if (!(error && typeof error === "object" && error.code === "ENOENT")) {
+async function readFileKeyAt(keyPath) {
+  // Exclusive-create fallback filesystems may expose a partially written key.
+  // Retry that bounded race, but never replace an invalid or unreadable key.
+  for (let attempt = 0; ; attempt += 1) {
+    let raw;
+    try {
+      raw = await fsp.readFile(keyPath, "utf-8");
+    } catch (error) {
+      if (error?.code === "ENOENT") return null;
       throw error;
     }
-  }
-
-  try {
-    const legacyRaw = await fsp.readFile(legacyKeyPath, "utf-8");
-    const legacyKey = Buffer.from(String(legacyRaw || "").trim(), "base64");
-    if (legacyKey.length === 32) {
-      await fsp.mkdir(path.dirname(keyPath), { recursive: true, mode: 0o700 });
-      await fsp.writeFile(keyPath, legacyKey.toString("base64"), { encoding: "utf-8", mode: 0o600 });
-      try {
-        await fsp.chmod(keyPath, 0o600);
-      } catch {
-        // Windows does not reliably support POSIX chmod semantics.
-      }
-      let verified = false;
-      try {
-        const verifyRaw = await fsp.readFile(keyPath, "utf-8");
-        const verifyKey = Buffer.from(String(verifyRaw || "").trim(), "base64");
-        verified = verifyKey.length === 32 && verifyKey.equals(legacyKey);
-      } catch {
-        verified = false;
-      }
-      if (verified) {
-        await fsp.rm(legacyKeyPath, { force: true });
-      }
-      return legacyKey;
-    }
-  } catch (error) {
-    if (!(error && typeof error === "object" && error.code === "ENOENT")) {
+    const encoded = String(raw || "").trim();
+    const key = Buffer.from(encoded, "base64");
+    if (key.length === 32 && key.toString("base64") === encoded) return key;
+    if (attempt >= 5) {
+      const error = new Error("Stored credential encryption key is invalid; it was not replaced.");
+      error.code = "CREDENTIALS_KEY_INVALID";
       throw error;
     }
+    await delayMilliseconds(20);
   }
+}
+
+async function readFileKey({ homeDir } = {}) {
+  return (await readFileKeyAt(resolveCredentialsKeyPath({ homeDir }))) ||
+    (await readFileKeyAt(resolveLegacyCredentialsKeyPath({ homeDir })));
+}
 
-  const key = crypto.randomBytes(32);
+async function loadOrCreateFileKey({ homeDir } = {}) {
+  const keyPath = resolveCredentialsKeyPath({ homeDir });
+  const existing = await readFileKeyAt(keyPath);
+  if (existing) return existing;
+  const legacyKey = await readFileKeyAt(resolveLegacyCredentialsKeyPath({ homeDir }));
+  const key = legacyKey || crypto.randomBytes(32);
+  const encoded = key.toString("base64");
   await fsp.mkdir(path.dirname(keyPath), { recursive: true, mode: 0o700 });
-  await fsp.writeFile(keyPath, key.toString("base64"), { encoding: "utf-8", mode: 0o600 });
+  const tmpPath = `${keyPath}.${process.pid}.${crypto.randomUUID()}.tmp`;
   try {
-    await fsp.chmod(keyPath, 0o600);
-  } catch {
-    // Windows does not reliably support POSIX chmod semantics.
+    await fsp.writeFile(tmpPath, encoded, { encoding: "utf-8", mode: 0o600, flag: "wx" });
+    await syncFile(tmpPath);
+    try {
+      // Publish complete bytes once. Every concurrent writer then uses the winner.
+      await fsp.link(tmpPath, keyPath);
+    } catch (error) {
+      if (error?.code !== "EEXIST") {
+        if (!["ENOTSUP", "ENOSYS", "EXDEV", "EPERM"].includes(error?.code)) throw error;
+        try {
+          await fsp.writeFile(keyPath, encoded, { encoding: "utf-8", mode: 0o600, flag: "wx" });
+        } catch (fallbackError) {
+          if (fallbackError?.code !== "EEXIST") throw fallbackError;
+        }
+      }
+    }
+    const persisted = await readFileKeyAt(keyPath);
+    if (!persisted) throw new Error("Credential encryption key could not be persisted.");
+    await syncFile(keyPath);
+    await syncDirectory(path.dirname(keyPath));
+    // Keep the legacy key: deleting it can race a read-only legacy reader.
+    return persisted;
+  } finally {
+    await fsp.rm(tmpPath, { force: true }).catch(() => {});
   }
-  return key;
 }
 
 function encryptToken(token, key) {
@@ -540,7 +548,11 @@ async function tryDecryptFileToken({ metadata, homeDir }) {
     return null;
   }
   try {
-    const key = await loadOrCreateFileKey({ homeDir });
+    const key = await readFileKey({ homeDir });
+    if (!key) {
+      emitSessionWarning("FILE_CREDENTIAL_UNAVAILABLE", { reason: "key_missing", source: "file-encrypted" });
+      return null;
+    }
     const token = decryptToken(
       {
         tokenEncrypted: metadata.tokenEncrypted,
@@ -550,7 +562,13 @@ async function tryDecryptFileToken({ metadata, homeDir }) {
       key
     );
     return token || null;
-  } catch {
+  } catch (error) {
+    emitSessionWarning("FILE_CREDENTIAL_UNAVAILABLE", {
+      reason: error?.code === "EACCES" || error?.code === "EPERM"
+        ? "key_unreadable"
+        : error?.code === "CREDENTIALS_KEY_INVALID" ? "key_invalid" : "decryption_failed",
+      source: "file-encrypted",
+    });
     return null;
   }
 }
@@ -722,6 +740,7 @@ export async function readStoredSessionMetadata({ homeDir } = {}) {
  *   tokenPrefix?: string | null,
  *   tokenExpiresAt?: string | null,
  *   user?: Record<string, unknown>
+ *   aidenid?: Record<string, unknown> | null
  * }} [session]
  * @param {{ homeDir?: string }} [options]
  * @returns {Promise<{
@@ -754,6 +773,7 @@ export async function writeStoredSession(
     tokenPrefix = null,
     tokenExpiresAt = null,
     user = {},
+    aidenid = null,
   } = {},
   { homeDir } = {}
 ) {
@@ -778,6 +798,7 @@ export async function writeStoredSession(
     tokenPrefix,
     tokenExpiresAt,
     user: normalizeUser(user),
+    aidenid,
     createdAt: existingMetadata?.createdAt || updatedAt,
     updatedAt,
   });

package/src/commands/auth.js

@@ -133,6 +133,14 @@ export function registerAuthCommand(program) {
           tokenLabel: options.tokenLabel,
           tokenTtlDays,
           cliVersion: CLI_VERSION,
+          onAuthorize: ({ authorizeUrl }) => {
+            // A spawned opener does not prove a browser exists on a headless host.
+            if (!authorizeUrl) return;
+            const safeUrl = String(authorizeUrl).replace(/[\u0000-\u001f\u007f-\u009f]/g, "").slice(0, 4096);
+            const line = `Open this URL to approve sign-in:\n${safeUrl}\n`;
+            if (shouldEmitJson(options, command)) process.stderr.write(line);
+            else console.log(line.trimEnd());
+          },
         });
       } catch (error) {
         throw new Error(formatApiError(error));
@@ -159,10 +167,6 @@ export function registerAuthCommand(program) {
       if (result.filePath) {
         console.log(pc.gray(`Session metadata: ${result.filePath}`));
       }
-      if (!result.browserOpened && result.authorizeUrl) {
-        console.log(pc.yellow("Open this URL to approve sign-in:"));
-        console.log(result.authorizeUrl);
-      }
     });
 
   auth
@@ -199,6 +203,13 @@ export function registerAuthCommand(program) {
 
       console.log(pc.bold("Authentication status"));
       console.log(pc.gray(`API: ${status.apiUrl}`));
+      if (status.validation === "storage_unavailable") {
+        console.log(pc.yellow("Stored sign-in metadata exists, but its credential cannot be read. Authentication is unknown."));
+        if (status.filePath) console.log(pc.gray(`Session metadata: ${status.filePath}`));
+        console.log(pc.gray("Check the current user/home, keyring availability, encryption key and file permissions."));
+        console.log(pc.gray("Credentials were not cleared. Repair storage instead of logging out or signing in again for this error."));
+        return;
+      }
       if (!status.source) {
         console.log(pc.yellow("No active session token found."));
         printAuthHint();
@@ -254,6 +265,15 @@ export function registerAuthCommand(program) {
             }`
           )
         );
+        if (status.validation === "unavailable") {
+          console.log(pc.yellow("Remote validation is temporarily unavailable; your existing credentials were not cleared."));
+          console.log(pc.gray("Retry auth status when the API is reachable. Do not sign in again solely for this validation error."));
+          return;
+        }
+        if (["CREDENTIAL_DESTINATION_REFUSED", "CREDENTIAL_PATH_REFUSED"].includes(status.remoteError.code)) {
+          console.log(pc.yellow("Credential destination was refused. Check the configured API; signing in again does not change this boundary."));
+          return;
+        }
       } else {
         console.log(pc.yellow("Remote validation was skipped (`--offline`)."));
       }