@hasna/recordings 0.3.13 → 0.4.0

package/dist/storage.js

@@ -244,6 +244,9 @@ var DEFAULT_CONFIG = {
   db_path: "",
   audio_dir: "",
   max_recording_seconds: 1800,
+  s3_bucket: "",
+  s3_prefix: "",
+  s3_region: "",
   config_warnings: []
 };
 function loadConfig(configPath) {
@@ -270,6 +273,9 @@ function loadConfig(configPath) {
   if (process.env.RECORDINGS_API_KEY) {
     config.openai_api_key = process.env.RECORDINGS_API_KEY;
   }
+  if (process.env.RECORDINGS_OPENAI_API_KEY) {
+    config.openai_api_key = process.env.RECORDINGS_OPENAI_API_KEY;
+  }
   if (process.env.RECORDINGS_ENHANCEMENT_KEY) {
     config.enhancement_api_key = process.env.RECORDINGS_ENHANCEMENT_KEY;
   }
@@ -313,14 +319,26 @@ function loadConfig(configPath) {
   if (process.env.RECORDINGS_AUDIO_DIR) {
     config.audio_dir = process.env.RECORDINGS_AUDIO_DIR;
   }
+  if (process.env.HASNA_RECORDINGS_S3_BUCKET) {
+    config.s3_bucket = process.env.HASNA_RECORDINGS_S3_BUCKET;
+  } else if (process.env.RECORDINGS_S3_BUCKET) {
+    config.s3_bucket = process.env.RECORDINGS_S3_BUCKET;
+  }
+  if (process.env.HASNA_RECORDINGS_S3_PREFIX) {
+    config.s3_prefix = process.env.HASNA_RECORDINGS_S3_PREFIX;
+  } else if (process.env.RECORDINGS_S3_PREFIX) {
+    config.s3_prefix = process.env.RECORDINGS_S3_PREFIX;
+  }
+  if (process.env.RECORDINGS_S3_REGION) {
+    config.s3_region = process.env.RECORDINGS_S3_REGION;
+  } else if (process.env.AWS_REGION) {
+    config.s3_region = process.env.AWS_REGION;
+  }
   if (process.env.RECORDINGS_MAX_SECONDS) {
     config.max_recording_seconds = parseInt(process.env.RECORDINGS_MAX_SECONDS, 10);
   }
-  if (!config.openai_api_key) {
-    config.openai_api_key = loadSecretKey("OPENAI_API_KEY");
-  }
   if (!config.enhancement_api_key) {
-    config.enhancement_api_key = config.openai_api_key || loadSecretKey("OPENAI_API_KEY");
+    config.enhancement_api_key = config.openai_api_key;
   }
   if (!explicitTranscriberModel) {
     config.transcriber_model = config.enhancement_model;
@@ -500,51 +518,6 @@ function mergeDirectoryContents(sourceDir, targetDir) {
     }
   }
 }
-function loadSecretKey(keyName) {
-  const secretsPath = join2(getHomeDir(), ".secrets");
-  if (!existsSync(secretsPath))
-    return "";
-  for (const candidate of listSecretFiles(secretsPath)) {
-    try {
-      const content = readFileSync(candidate, "utf-8");
-      const match = content.match(new RegExp(`export\\s+${keyName}\\s*=\\s*"([^"]+)"`));
-      const doubleQuotedValue = match?.[1];
-      if (doubleQuotedValue !== undefined)
-        return doubleQuotedValue;
-      const match2 = content.match(new RegExp(`export\\s+${keyName}\\s*=\\s*'([^']+)'`));
-      const singleQuotedValue = match2?.[1];
-      if (singleQuotedValue !== undefined)
-        return singleQuotedValue;
-      const match3 = content.match(new RegExp(`${keyName}\\s*=\\s*(.+)`));
-      const unquotedValue = match3?.[1];
-      if (unquotedValue !== undefined)
-        return unquotedValue.trim().replace(/^["']|["']$/g, "");
-    } catch {}
-  }
-  return "";
-}
-function listSecretFiles(path) {
-  try {
-    const stats = statSync(path);
-    if (stats.isFile())
-      return [path];
-    if (!stats.isDirectory())
-      return [];
-    return readdirSync(path).sort().flatMap((entry) => {
-      const child = join2(path, entry);
-      try {
-        const childStats = statSync(child);
-        if (childStats.isDirectory())
-          return listSecretFiles(child);
-        if (childStats.isFile() && child.endsWith(".env"))
-          return [child];
-      } catch {}
-      return [];
-    });
-  } catch {
-    return [];
-  }
-}
 function getHomeDir() {
   return process.env["HOME"] || process.env["USERPROFILE"] || homedir2();
 }
@@ -641,6 +614,11 @@ var MIGRATIONS = [
   `,
   `
   ALTER TABLE agents ADD COLUMN active_project_id TEXT REFERENCES projects(id) ON DELETE SET NULL;
+  `,
+  `
+  ALTER TABLE recordings ADD COLUMN audio_object_key TEXT;
+  ALTER TABLE recordings ADD COLUMN audio_sha256 TEXT;
+  ALTER TABLE recordings ADD COLUMN audio_bytes INTEGER;
   `
 ];
 var CURRENT_MIGRATION_LEVEL = MIGRATIONS.length - 1;
@@ -696,6 +674,9 @@ function repairSchemaDrift(db) {
   ensureColumn(db, "recordings", "task_list_id", "TEXT");
   ensureColumn(db, "recordings", "machine_id", "TEXT");
   ensureColumn(db, "recordings", "metadata", "TEXT DEFAULT '{}'");
+  ensureColumn(db, "recordings", "audio_object_key", "TEXT");
+  ensureColumn(db, "recordings", "audio_sha256", "TEXT");
+  ensureColumn(db, "recordings", "audio_bytes", "INTEGER");
   ensureColumn(db, "agents", "active_project_id", "TEXT REFERENCES projects(id) ON DELETE SET NULL");
 }
 function ensureColumn(db, table, column, definition) {
@@ -771,6 +752,9 @@ function parseRow(row) {
   return {
     id: row["id"],
     audio_path: row["audio_path"] || null,
+    audio_object_key: row["audio_object_key"] || null,
+    audio_sha256: row["audio_sha256"] || null,
+    audio_bytes: Number(row["audio_bytes"] ?? 0) || null,
     raw_text: row["raw_text"],
     processed_text: row["processed_text"] || null,
     processing_mode: row["processing_mode"] || "raw",
@@ -802,9 +786,9 @@ function createRecording(input, db, idempotencyKey) {
     }
     const tagsJson = JSON.stringify(input.tags || []);
     const metadataJson = JSON.stringify(input.metadata || {});
-    const insertResult = d.query(`INSERT INTO recordings (id, audio_path, raw_text, processed_text, processing_mode, model_used, enhancement_model, duration_ms, language, tags, agent_id, project_id, session_id, goal, role, task_list_id, machine_id, metadata)
-     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-     ON CONFLICT(id) DO NOTHING`).run(id, input.audio_path || null, input.raw_text, input.processed_text || null, input.processing_mode || "raw", input.model_used || "gpt-4o-transcribe", input.enhancement_model || null, input.duration_ms || 0, input.language || null, tagsJson, input.agent_id || null, input.project_id || null, input.session_id || null, input.goal || null, input.role || null, input.task_list_id || null, input.machine_id || null, metadataJson);
+    const insertResult = d.query(`INSERT INTO recordings (id, audio_path, audio_object_key, audio_sha256, audio_bytes, raw_text, processed_text, processing_mode, model_used, enhancement_model, duration_ms, language, tags, agent_id, project_id, session_id, goal, role, task_list_id, machine_id, metadata)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+     ON CONFLICT(id) DO NOTHING`).run(id, input.audio_path || null, input.audio_object_key || null, input.audio_sha256 || null, input.audio_bytes || null, input.raw_text, input.processed_text || null, input.processing_mode || "raw", input.model_used || "gpt-4o-transcribe", input.enhancement_model || null, input.duration_ms || 0, input.language || null, tagsJson, input.agent_id || null, input.project_id || null, input.session_id || null, input.goal || null, input.role || null, input.task_list_id || null, input.machine_id || null, metadataJson);
     if (insertResult.changes === 0) {
       const existing = getRecording(id, d);
       if (existing?.id === id)
@@ -821,6 +805,13 @@ function createRecording(input, db, idempotencyKey) {
   });
   return create();
 }
+function updateRecordingAudio(id, audioObjectKey, audioSha256, audioBytes, db) {
+  const d = db || getDatabase();
+  const result = d.query(`UPDATE recordings SET audio_object_key = ?, audio_sha256 = ?, audio_bytes = ? WHERE id = ?`).run(audioObjectKey, audioSha256, audioBytes, id);
+  if (result.changes === 0)
+    return null;
+  return getRecording(id, d);
+}
 function getRecording(id, db) {
   const d = db || getDatabase();
   let row = d.query("SELECT * FROM recordings WHERE id = ?").get(id);
@@ -1022,7 +1013,7 @@ function setAgentFocus(idOrName, projectId, db) {
 // package.json
 var package_default = {
   name: "@hasna/recordings",
-  version: "0.3.13",
+  version: "0.4.0",
   type: "module",
   description: "Speech-to-text recording tool with MCP and CLI \u2014 records, transcribes, and optionally enhances text using AI",
   repository: {
@@ -1056,10 +1047,10 @@ var package_default = {
   scripts: {
     clean: "rm -rf dist",
     build: "bun run clean && bun run build:cli && bun run build:mcp && bun run build:serve && bun run build:lib && tsc --emitDeclarationOnly --outDir dist",
-    "build:cli": "bun build src/cli/index.ts --target=bun --outfile=dist/cli/index.js --external=commander --external=chalk --external=openai",
-    "build:mcp": "bun build src/mcp/index.ts --target=bun --outfile=dist/mcp/index.js --external=@modelcontextprotocol/sdk --external=openai",
-    "build:serve": "bun build src/server/index.ts --target=bun --outfile=dist/server/index.js --external=@modelcontextprotocol/sdk --external=@hasna/contracts --external=openai --external=pg",
-    "build:lib": "bun build src/index.ts src/storage.ts src/sdk/index.ts --target=bun --outdir=dist --external=openai",
+    "build:cli": "bun build src/cli/index.ts --target=bun --outfile=dist/cli/index.js --external=commander --external=chalk --external=openai --external=@aws-sdk/client-s3",
+    "build:mcp": "bun build src/mcp/index.ts --target=bun --outfile=dist/mcp/index.js --external=@modelcontextprotocol/sdk --external=openai --external=@aws-sdk/client-s3",
+    "build:serve": "bun build src/server/index.ts --target=bun --outfile=dist/server/index.js --external=@modelcontextprotocol/sdk --external=@hasna/contracts --external=openai --external=pg --external=@aws-sdk/client-s3",
+    "build:lib": "bun build src/index.ts src/storage.ts src/sdk/index.ts --target=bun --outdir=dist --external=openai --external=@aws-sdk/client-s3",
     "build:native-fs-guard": "/bin/bash scripts/build_native_fs_guard.sh",
     "generate:sdk": "bun run scripts/generate-sdk.ts",
     migrate: "bun run scripts/migrate.ts",
@@ -1069,7 +1060,7 @@ var package_default = {
     "verify:ci-suite": "bun scripts/ci-linux-suite.ts --check",
     "verify:ci-suite:run": "bun scripts/ci-linux-suite.ts --verify-run",
     "verify:ci-native": "bun scripts/ci-native-build.ts",
-    "test:gated": 'bun scripts/ci-linux-suite.ts --check && RECORDINGS_TEST_TIMEOUT_MS="${RECORDINGS_TEST_TIMEOUT_MS:-120000}" bun test --timeout "$RECORDINGS_TEST_TIMEOUT_MS" $(bun scripts/ci-linux-suite.ts --gated)',
+    "test:gated": 'bun scripts/ci-linux-suite.ts --check && RECORDINGS_TEST_TIMEOUT_MS="${RECORDINGS_TEST_TIMEOUT_MS:-120000}" bun test --timeout "${RECORDINGS_TEST_TIMEOUT_MS:-120000}" $(bun scripts/ci-linux-suite.ts --gated)',
     "test:vacuity-battery": 'bun scripts/vacuity-manifest-gen.ts > "${TMPDIR:-/tmp}/vacuity-corrupt-sites.tsv" && bun scripts/vacuity-mutation-battery.ts "${TMPDIR:-/tmp}/vacuity-corrupt-sites.tsv"',
     "test:vacuity-battery:source": "bun scripts/vacuity-mutation-battery.ts scripts/vacuity-manifests/source-side.tsv",
     "test:vacuity-battery:chain": "bun scripts/vacuity-mutation-battery.ts scripts/vacuity-manifests/install-chain.tsv",
@@ -1106,7 +1097,8 @@ var package_default = {
     "LICENSE"
   ],
   dependencies: {
-    "@hasna/contracts": "0.14.1",
+    "@aws-sdk/client-s3": "^3.1007.0",
+    "@hasna/contracts": "1.0.2",
     "@hasna/events": "0.1.11",
     "@modelcontextprotocol/sdk": "^1.12.1",
     chalk: "^5.4.1",
@@ -1116,7 +1108,7 @@ var package_default = {
     zod: "^3.24.2"
   },
   devDependencies: {
-    "@types/bun": "^1.2.5",
+    "@types/bun": "1.3.14",
     "@types/pg": "^8.11.11",
     "node-api-headers": "1.9.0",
     typescript: "^5.8.2"
@@ -1140,8 +1132,12 @@ function saveFeedback(input) {
 
 // ../contracts/dist/client/transport.js
 import { isIP } from "net";
-import { readFileSync as readFileSync2, statSync as statSync2 } from "fs";
-import { join as join3 } from "path";
+import { spawnSync as spawnSync2 } from "child_process";
+import { closeSync, fstatSync, openSync, readFileSync as readFileSync2 } from "fs";
+import { O_NOFOLLOW, O_NONBLOCK, O_RDONLY } from "constants";
+import { createRequire } from "module";
+import { hostname as osHostname } from "os";
+import { isAbsolute as isAbsolute2, join as join3 } from "path";
 function envToken(name) {
   return name.toUpperCase().replace(/-/g, "_");
 }
@@ -1156,6 +1152,9 @@ function credentialOverrideEnvKey(name) {
   return `HASNA_${envToken(name)}_API_KEY_OVERRIDE`;
 }
 var CREDENTIAL_PROFILE_ENV_KEY = "HASNA_PROFILE";
+function credentialPointerEnvKey(name) {
+  return `HASNA_${envToken(name)}_API_KEY_REF`;
+}
 
 class CredentialResolutionError extends Error {
   appName;
@@ -1167,34 +1166,70 @@ class CredentialResolutionError extends Error {
     this.attempted = attempted;
   }
 }
-var HASNA_STATE_DIR = ".hasna";
-var FLEET_CREDENTIAL_DIR = "cloud";
-var CONFIG_DIR = ".config";
-var CONFIG_NAMESPACE = "hasna";
+
+class CredentialFileUnsafeError extends Error {
+  path;
+  constructor(path, reason) {
+    super(`Refusing unsafe credential/config file ${path}: ${reason}.`);
+    this.name = "CredentialFileUnsafeError";
+    this.path = path;
+  }
+}
+var HASNA_HOME_ENV_KEY = "HASNA_HOME";
+var HASNA_CONFIG_HOME_ENV_KEY = "HASNA_CONFIG_HOME";
+var KEYCHAIN_STATION_ENV_KEY = "HASNA_STATION";
+var HASNA_HOME_DIR = ".hasna";
+var CONFIG_SUBDIR = "config";
+var CREDENTIALS_FILE = "credentials";
+var KEYCHAIN_SECURITY_BIN = "/usr/bin/security";
+var KEYCHAIN_SERVICE_PREFIX = "hasna.credentials";
+var KEYCHAIN_ITEM_NOT_FOUND_STATUS = 44;
+var KEYCHAIN_SPAWN_TIMEOUT_MS = 1e4;
 var MAX_CREDENTIAL_FILE_BYTES = 64 * 1024;
 var SAFE_APP_SLUG = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/;
 var SAFE_PROFILE = /^[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?$/;
 var ILLEGAL_IN_HEADER_VALUE = /[^\t\x20-\x7e]/;
+var VAULT_POINTER_SHAPE = /^[a-z0-9][a-z0-9-]*(?:\/[a-z0-9][a-z0-9-_.]*){2,}$/;
 function homeDir(env) {
   const home = env.HOME?.trim();
   return home ? home : null;
 }
-function credentialDiskSources(name, env) {
-  return profileDiskSources(name, env, null);
+function absoluteOverride(env, key) {
+  const value = env[key]?.trim();
+  return value && isAbsolute2(value) ? value : null;
 }
-function profileDiskSources(name, env, profile) {
+function hasnaHomeDir(env) {
+  const override = absoluteOverride(env, HASNA_HOME_ENV_KEY);
+  if (override)
+    return override;
   const home = homeDir(env);
-  if (!home || !SAFE_APP_SLUG.test(name))
+  return home ? join3(home, HASNA_HOME_DIR) : null;
+}
+function appConfigDir(name, env) {
+  const configRoot = absoluteOverride(env, HASNA_CONFIG_HOME_ENV_KEY);
+  if (configRoot)
+    return join3(configRoot, name);
+  const root = hasnaHomeDir(env);
+  return root ? join3(root, name, CONFIG_SUBDIR) : null;
+}
+function credentialDiskSourceList(name, env, profile = null) {
+  if (!SAFE_APP_SLUG.test(name))
     return [];
-  const stem = profile ? `${name}.${profile}` : name;
-  const configStem = profile ? `${name}-${profile}` : name;
-  return [
-    join3(home, HASNA_STATE_DIR, FLEET_CREDENTIAL_DIR, `${stem}.env`),
-    join3(home, CONFIG_DIR, CONFIG_NAMESPACE, `${configStem}-cloud.env`)
-  ];
+  const directory = appConfigDir(name, env);
+  if (!directory)
+    return [];
+  const file = profile ? `${CREDENTIALS_FILE}-${profile}` : CREDENTIALS_FILE;
+  return [{ path: join3(directory, file), tier: "disk" }];
+}
+function credentialDiskSources(name, env) {
+  return credentialDiskSourceList(name, env, null).map((s) => s.path);
+}
+function profileDiskSources(name, env, profile) {
+  return credentialDiskSourceList(name, env, profile).map((s) => s.path);
 }
 function parseEnvFile(text) {
   const values = new Map;
+  const unusable = new Set;
   for (const rawLine of text.split(/\r?\n/)) {
     const line = rawLine.trim();
     if (line.length === 0 || line.startsWith("#"))
@@ -1209,38 +1244,81 @@ function parseEnvFile(text) {
     let value = withoutExport.slice(equals + 1).trim();
     const quote = value[0];
     if (quote === '"' || quote === "'") {
-      if (value.length < 2 || !value.endsWith(quote))
+      if (value.length < 2 || !value.endsWith(quote)) {
+        unusable.add(key);
         continue;
+      }
       value = value.slice(1, -1);
     }
-    if (value.length === 0)
+    if (value.trim().length === 0) {
+      unusable.add(key);
       continue;
+    }
+    if (values.has(key) && values.get(key) !== value)
+      unusable.add(key);
     values.set(key, value);
   }
-  return values;
+  return { values, unusable };
+}
+function configFileModeAllowed(mode) {
+  const permissions = mode & 4095;
+  return permissions === 256 || permissions === 384;
+}
+function configFileReadsCoherent(before, after) {
+  return before.dev === after.dev && before.ino === after.ino && before.size === after.size && before.mtimeMs === after.mtimeMs && before.ctimeMs === after.ctimeMs;
 }
 function readAppConfigFile(path) {
-  let text;
+  const unsafe = (reason) => {
+    throw new CredentialFileUnsafeError(path, reason);
+  };
+  let fd = -1;
   try {
-    const stats = statSync2(path);
-    if (!stats.isFile() || stats.size > MAX_CREDENTIAL_FILE_BYTES)
+    fd = openSync(path, O_RDONLY | O_NOFOLLOW | O_NONBLOCK);
+  } catch (error) {
+    const code = error.code;
+    if (code === "ENOENT" || code === "ENOTDIR")
       return null;
-    text = readFileSync2(path, "utf8");
-  } catch {
-    return null;
+    if (code === "ELOOP")
+      unsafe("the path is a symlink");
+    unsafe(`the path could not be opened (${code ?? "unknown error"})`);
+  }
+  try {
+    const before = fstatSync(fd);
+    if (!before.isFile())
+      unsafe("the path is not a regular file");
+    if (!configFileModeAllowed(before.mode)) {
+      unsafe(`permission mode ${(before.mode & 4095).toString(8).padStart(4, "0")} is not owner-only 0400 or 0600`);
+    }
+    const uid = process.getuid?.() ?? process.geteuid?.();
+    if (uid !== undefined && before.uid !== uid)
+      unsafe("the file is not owned by the current user");
+    if (before.size > MAX_CREDENTIAL_FILE_BYTES)
+      unsafe("the file exceeds the size limit");
+    const bytes = readFileSync2(fd);
+    const after = fstatSync(fd);
+    if (!configFileReadsCoherent(before, after)) {
+      unsafe("the file changed while being read");
+    }
+    return parseEnvFile(bytes.toString("utf8"));
+  } finally {
+    if (fd !== -1)
+      closeSync(fd);
   }
-  return parseEnvFile(text);
 }
 function readCredentialFile(path, apiKeyKeys) {
-  const values = readAppConfigFile(path);
-  if (!values)
+  const parsed = readAppConfigFile(path);
+  if (!parsed)
     return null;
   for (const key of apiKeyKeys) {
-    const value = values.get(key)?.trim();
-    if (value)
-      return value;
+    if (parsed.unusable.has(key)) {
+      throw new CredentialFileUnsafeError(path, `${key} is declared but blank or malformed`);
+    }
   }
-  return null;
+  const values = apiKeyKeys.map((key) => parsed.values.get(key)?.trim()).filter((value) => Boolean(value));
+  if (new Set(values).size > 1) {
+    throw new CredentialFileUnsafeError(path, "credential aliases disagree");
+  }
+  return values[0] ?? null;
 }
 var CREDENTIAL_SHAPED_KEY = /(?:^|_)(?:API_KEY|KEY|TOKEN|SECRET|PASSWORD|PASSWD|CREDENTIAL|AUTH)(?:_|$)/;
 function appConfigDiskValue(name, env, keys) {
@@ -1248,11 +1326,19 @@ function appConfigDiskValue(name, env, keys) {
   if (wanted.length === 0)
     return null;
   for (const path of credentialDiskSources(name, env)) {
-    const values = readAppConfigFile(path);
-    if (!values)
+    const parsed = readAppConfigFile(path);
+    if (!parsed)
       continue;
+    if (wanted.some((key) => parsed.unusable.has(key))) {
+      return { key: wanted.find((key) => parsed.unusable.has(key)), value: "", path, unusable: true };
+    }
+    const values = wanted.map((key) => parsed.values.get(key)?.trim()).filter((value) => Boolean(value));
+    if (new Set(values).size > 1)
+      throw new CredentialFileUnsafeError(path, "configuration aliases disagree");
     for (const key of wanted) {
-      const value = values.get(key)?.trim();
+      if (parsed.unusable.has(key))
+        return { key, value: "", path, unusable: true };
+      const value = parsed.values.get(key)?.trim();
       if (value)
         return { key, value, path };
     }
@@ -1260,20 +1346,21 @@ function appConfigDiskValue(name, env, keys) {
   return null;
 }
 function assertUsableCredential(appName, source, value) {
+  if (VAULT_POINTER_SHAPE.test(value)) {
+    throw new CredentialResolutionError(appName, `The credential from ${source} looks like a secrets-vault pointer (a path-shaped reference like ` + `'namespace/app/live/api_key'). A vault path is NEVER accepted as a literal API key. ` + `Use ${credentialPointerEnvKey(appName)} to resolve the key through the vault, or provide the actual key value.`, [source]);
+  }
   if (!ILLEGAL_IN_HEADER_VALUE.test(value))
     return;
   throw new CredentialResolutionError(appName, `The credential from ${source} contains characters that cannot be sent in an HTTP header ` + `(a control character or non-ASCII byte). A file written with CR-only line endings is the usual ` + `cause. Rewrite that credential file with one LF-terminated KEY=value line. ` + `The value is not shown here, and is deliberately never logged.`, [source]);
 }
 var INSPECT_CUSTOM = Symbol.for("nodejs.util.inspect.custom");
 var CREDENTIAL_SEAL = Symbol.for("hasna:contracts:sealedCredential");
-var CALLER_SUPPLIED_CREDENTIAL_PROVIDER_SOURCE = "caller-supplied CredentialProvider";
 function sealCredential(fields) {
   const { apiKey } = fields;
   const visible = {
     tier: fields.tier,
     source: fields.source,
     deliberate: fields.deliberate,
-    deprecated: fields.deprecated,
     diskCandidates: Object.freeze([...fields.diskCandidates]),
     warning: fields.warning
   };
@@ -1284,6 +1371,14 @@ function sealCredential(fields) {
     writable: false,
     configurable: false
   });
+  if (fields.pointerVaultKey !== undefined) {
+    Object.defineProperty(sealed, "pointerVaultKey", {
+      value: fields.pointerVaultKey,
+      enumerable: false,
+      writable: false,
+      configurable: false
+    });
+  }
   Object.defineProperty(sealed, INSPECT_CUSTOM, {
     value: () => ({ ...visible, apiKey: "[redacted]" }),
     enumerable: false,
@@ -1298,88 +1393,142 @@ function sealCredential(fields) {
   });
   return Object.freeze(sealed);
 }
-function isSealedCredential(credential) {
-  return credential[CREDENTIAL_SEAL] === true;
-}
-function explicitCredential(appName, apiKey) {
-  const source = "explicit apiKey option";
-  assertUsableCredential(appName, source, apiKey);
-  return sealCredential({
-    apiKey,
-    tier: "argument",
-    source,
-    deliberate: true,
-    deprecated: false,
-    diskCandidates: [],
-    warning: null
-  });
-}
-function validateAndSealResolvedCredential(appName, credential) {
-  const apiKey = credential.apiKey;
-  assertUsableCredential(appName, CALLER_SUPPLIED_CREDENTIAL_PROVIDER_SOURCE, apiKey);
-  if (!isSealedCredential(credential)) {
-    return sealCredential({
-      apiKey,
-      tier: "argument",
-      source: CALLER_SUPPLIED_CREDENTIAL_PROVIDER_SOURCE,
-      deliberate: true,
-      deprecated: false,
-      diskCandidates: [],
-      warning: null
-    });
-  }
-  return sealCredential({
-    apiKey,
-    tier: credential.tier,
-    source: credential.source,
-    deliberate: credential.deliberate,
-    deprecated: credential.deprecated,
-    diskCandidates: credential.diskCandidates,
-    warning: credential.warning
-  });
-}
 function firstEnvValue(env, keys) {
   for (const key of keys) {
+    if (!Object.prototype.hasOwnProperty.call(env, key))
+      continue;
     const value = env[key]?.trim();
     if (value)
       return { key, value };
   }
   return null;
 }
-var DEPRECATION_REGISTRY = Symbol.for("hasna:contracts:credentialDeprecationNotices");
-function deprecationNotified() {
-  const host = globalThis;
-  const existing = host[DEPRECATION_REGISTRY];
-  if (existing instanceof Set)
-    return existing;
-  const created = new Set;
-  host[DEPRECATION_REGISTRY] = created;
-  return created;
+var AMBIENT_ENVIRONMENT = Symbol.for("hasna:contracts:ambientClientEnvironment");
+function isAmbientEnvironment(env) {
+  return env === process.env || env[AMBIENT_ENVIRONMENT] === true;
+}
+function defaultKeychainRunner(argv) {
+  const result = spawnSync2(KEYCHAIN_SECURITY_BIN, [...argv], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+    timeout: KEYCHAIN_SPAWN_TIMEOUT_MS
+  });
+  return {
+    status: result.status,
+    stdout: result.stdout ?? "",
+    stderr: result.error ? result.error.message : result.stderr ?? ""
+  };
+}
+function keychainTierEnabled(env, options) {
+  if ((options.platform ?? process.platform) !== "darwin")
+    return false;
+  if (options.enabled !== undefined)
+    return options.enabled;
+  return options.run !== undefined || isAmbientEnvironment(env);
+}
+function keychainAccount(env, options) {
+  const station = env[KEYCHAIN_STATION_ENV_KEY]?.trim();
+  if (station)
+    return station;
+  const host = (options.hostname ?? osHostname)().split(".")[0]?.trim() ?? "";
+  if (host)
+    return host;
+  const user = env.USER?.trim();
+  return user || null;
+}
+function keychainFailureHint(text) {
+  const line = text.split(/\r?\n/).find((entry) => entry.trim().length > 0)?.trim() ?? "";
+  const clean = line.replace(/[\u0000-\u001f\u007f]/g, "").slice(0, 200);
+  return clean ? `: ${clean}` : "";
+}
+function readKeychainItem(name, env, kind, options) {
+  if (!SAFE_APP_SLUG.test(name) || !keychainTierEnabled(env, options))
+    return null;
+  const account = keychainAccount(env, options);
+  if (!account)
+    return null;
+  const service = `${KEYCHAIN_SERVICE_PREFIX}.${name}.${kind}`;
+  const source = `keychain:${service}@${account}`;
+  const run = options.run ?? defaultKeychainRunner;
+  let result;
+  try {
+    result = run(["find-generic-password", "-a", account, "-s", service, "-w"]);
+  } catch (error) {
+    const reason = keychainFailureHint(error instanceof Error ? error.message : String(error));
+    throw new CredentialResolutionError(name, `The Keychain lookup for ${source} could not run${reason}. A Keychain failure is never resolved ` + `around: fix the keychain, or delete the item to fall through to the credential on disk.`, [source]);
+  }
+  if (result.status === KEYCHAIN_ITEM_NOT_FOUND_STATUS)
+    return null;
+  if (result.status !== 0) {
+    throw new CredentialResolutionError(name, `The Keychain lookup for ${source} failed (security exited ` + `${result.status ?? "without a status"}${keychainFailureHint(result.stderr)}). A Keychain item that ` + `exists but cannot be read is never resolved around: unlock the keychain, run from a session that ` + `may use it, or delete the item to fall through to the credential on disk.`, [source]);
+  }
+  const value = result.stdout.trim();
+  if (!value) {
+    throw new CredentialResolutionError(name, `${source} exists but holds an empty value; a declared item never falls through to another ` + `identity. Store a value in it or delete the item.`, [source]);
+  }
+  return { value, source };
+}
+function keychainConfigValue(name, env, options = {}) {
+  return readKeychainItem(name, env, "api-url", options);
 }
-function defaultDeprecationSink(message) {
-  if (typeof process !== "undefined" && process.stderr) {
-    process.stderr.write(`${message}
-`);
+function snapshotClientEnvironment(name, env) {
+  const keys = clientTransportEnvKeys(name);
+  const ambient = isAmbientEnvironment(env);
+  const snapshot = Object.create(null);
+  for (const key of [
+    ...keys.apiUrlKeys,
+    ...keys.apiKeyKeys,
+    credentialOverrideEnvKey(name),
+    credentialPointerEnvKey(name),
+    CREDENTIAL_PROFILE_ENV_KEY,
+    "HOME",
+    HASNA_HOME_ENV_KEY,
+    HASNA_CONFIG_HOME_ENV_KEY,
+    KEYCHAIN_STATION_ENV_KEY,
+    "USER"
+  ]) {
+    const descriptor = Object.getOwnPropertyDescriptor(env, key);
+    if (!descriptor)
+      continue;
+    if (!("value" in descriptor)) {
+      throw new CredentialResolutionError(name, `${key} is accessor-backed; client configuration requires own data properties.`, [key]);
+    }
+    if (descriptor.value !== undefined && typeof descriptor.value !== "string") {
+      throw new CredentialResolutionError(name, `${key} must be a string data property.`, [key]);
+    }
+    snapshot[key] = descriptor.value;
+  }
+  if (ambient) {
+    Object.defineProperty(snapshot, AMBIENT_ENVIRONMENT, {
+      value: true,
+      enumerable: false,
+      writable: false,
+      configurable: false
+    });
   }
+  return Object.freeze(snapshot);
 }
 function resolveCredential(name, env, options = {}) {
+  env = snapshotClientEnvironment(name, env);
   const { apiKeyKeys } = clientTransportEnvKeys(name);
   const diskPaths = credentialDiskSources(name, env);
-  const explicitKey = options.apiKey?.trim();
-  if (explicitKey) {
+  if (options.apiKey !== undefined) {
+    const explicitKey = options.apiKey.trim();
+    if (!explicitKey) {
+      throw new CredentialResolutionError(name, "The explicit apiKey argument is blank; an explicit credential never falls through to another identity.", ["explicit apiKey argument"]);
+    }
     assertUsableCredential(name, "the explicit apiKey argument", explicitKey);
     return sealCredential({
       apiKey: explicitKey,
       tier: "argument",
       source: "explicit apiKey argument",
       deliberate: true,
-      deprecated: false,
       diskCandidates: diskPaths,
       warning: null
     });
   }
   const overrideKeyName = credentialOverrideEnvKey(name);
-  const overrideRaw = env[overrideKeyName];
+  const overrideRaw = Object.prototype.hasOwnProperty.call(env, overrideKeyName) ? env[overrideKeyName] : undefined;
   if (overrideRaw !== undefined) {
     const override = overrideRaw.trim();
     if (!override) {
@@ -1391,12 +1540,38 @@ function resolveCredential(name, env, options = {}) {
       tier: "override",
       source: overrideKeyName,
       deliberate: true,
-      deprecated: false,
       diskCandidates: diskPaths,
       warning: null
     });
   }
-  const profile = options.profile?.trim() || env[CREDENTIAL_PROFILE_ENV_KEY]?.trim();
+  const pointerKeyName = credentialPointerEnvKey(name);
+  const pointerRaw = Object.prototype.hasOwnProperty.call(env, pointerKeyName) ? env[pointerKeyName] : undefined;
+  if (pointerRaw !== undefined) {
+    const pointer = pointerRaw.trim();
+    if (!pointer) {
+      throw new CredentialResolutionError(name, `${pointerKeyName} is set but empty. It is a deliberate vault pointer, so it is not resolved around: ` + `either give it a vault item key or unset it to fall back to the credential on disk.`, [pointerKeyName]);
+    }
+    if (!VAULT_POINTER_SHAPE.test(pointer)) {
+      throw new CredentialResolutionError(name, `${pointerKeyName} must name a vault ITEM KEY (a path-shaped reference like ` + `'namespace/app/live/api_key'), not a credential value. A pointer that carries a literal is refused.`, [pointerKeyName]);
+    }
+    return sealCredential({
+      apiKey: "",
+      pointerVaultKey: pointer,
+      tier: "pointer",
+      source: pointerKeyName,
+      deliberate: true,
+      diskCandidates: diskPaths,
+      warning: null
+    });
+  }
+  if (options.profile !== undefined && !options.profile.trim()) {
+    throw new CredentialResolutionError(name, "The explicit profile argument is blank; an explicit identity selection never falls through.", ["explicit profile argument"]);
+  }
+  const profileRaw = Object.prototype.hasOwnProperty.call(env, CREDENTIAL_PROFILE_ENV_KEY) ? env[CREDENTIAL_PROFILE_ENV_KEY] : undefined;
+  if (profileRaw !== undefined && !profileRaw.trim()) {
+    throw new CredentialResolutionError(name, `${CREDENTIAL_PROFILE_ENV_KEY} is set but blank.`, [CREDENTIAL_PROFILE_ENV_KEY]);
+  }
+  const profile = options.profile?.trim() || profileRaw?.trim();
   if (profile) {
     const profileSource = options.profile?.trim() ? "explicit profile argument" : CREDENTIAL_PROFILE_ENV_KEY;
     if (!SAFE_PROFILE.test(profile)) {
@@ -1412,7 +1587,6 @@ function resolveCredential(name, env, options = {}) {
           tier: "profile",
           source: path,
           deliberate: true,
-          deprecated: false,
           diskCandidates: paths,
           warning: null
         });
@@ -1420,51 +1594,67 @@ function resolveCredential(name, env, options = {}) {
     }
     throw new CredentialResolutionError(name, `Profile '${profile}' (from ${profileSource}) has no ${apiKeyKeys[0]} for '${name}'. ` + `Looked in: ${paths.join(", ") || "<no HOME in this environment>"}. ` + `A profile names WHICH identity to use, so it is never resolved around \u2014 ` + `create the profile's credential file or unset ${CREDENTIAL_PROFILE_ENV_KEY}.`, paths);
   }
-  const diskHits = diskPaths.map((path) => ({ path, value: readCredentialFile(path, apiKeyKeys) })).filter((hit) => hit.value !== null);
+  const definedEnvEntries = apiKeyKeys.filter((key) => Object.prototype.hasOwnProperty.call(env, key) && env[key] !== undefined).map((key) => ({ key, value: String(env[key]).trim() }));
+  const blankEnv = definedEnvEntries.find((entry) => entry.value.length === 0);
+  if (blankEnv) {
+    throw new CredentialResolutionError(name, `${blankEnv.key} is set but blank; a declared credential never falls through to another alias or identity.`, [blankEnv.key]);
+  }
+  if (definedEnvEntries.length > 1 && new Set(definedEnvEntries.map((entry) => entry.value)).size > 1) {
+    throw new CredentialResolutionError(name, `${definedEnvEntries.map((entry) => entry.key).join(" and ")} disagree; credential aliases must be identical or only one may be set.`, definedEnvEntries.map((entry) => entry.key));
+  }
+  const envHit = firstEnvValue(env, apiKeyKeys);
+  const keychainHit = readKeychainItem(name, env, "api-key", options.keychain ?? {});
+  if (keychainHit) {
+    assertUsableCredential(name, keychainHit.source, keychainHit.value);
+    const warning = envHit && envHit.value !== keychainHit.value ? `Credential sources disagree for '${name}': ${keychainHit.source} and ${envHit.key} hold ` + `different keys. ${keychainHit.source} wins, because the Keychain is re-read on every call while ` + `an environment variable is a snapshot. Reconcile them \u2014 a rotation that updated only one leaves ` + `the other to fail 401 wherever it is loaded first.` : null;
+    return sealCredential({
+      apiKey: keychainHit.value,
+      tier: "keychain",
+      source: keychainHit.source,
+      deliberate: false,
+      diskCandidates: diskPaths,
+      warning
+    });
+  }
+  const diskSourceList = credentialDiskSourceList(name, env, null);
+  const diskHits = diskSourceList.map((src) => ({ src, value: readCredentialFile(src.path, apiKeyKeys) })).filter((hit) => hit.value !== null);
   if (diskHits.length > 0) {
     const winner = diskHits[0];
-    assertUsableCredential(name, winner.path, winner.value);
+    assertUsableCredential(name, winner.src.path, winner.value);
     const divergentSources = [
-      ...diskHits.slice(1).filter((hit) => hit.value !== winner.value).map((hit) => hit.path),
-      ...(() => {
-        const legacyHit = firstEnvValue(env, apiKeyKeys);
-        return legacyHit && legacyHit.value !== winner.value ? [legacyHit.key] : [];
-      })()
+      ...diskHits.slice(1).filter((hit) => hit.value !== winner.value).map((hit) => hit.src.path),
+      ...envHit && envHit.value !== winner.value ? [envHit.key] : []
     ];
-    const warning = divergentSources.length > 0 ? `Credential sources disagree for '${name}': ${winner.path} and ` + `${divergentSources.join(", ")} hold different keys. ${winner.path} wins, because a file on ` + `disk is re-read on every call while an environment variable is a snapshot. Reconcile them \u2014 ` + `a rotation that updated only one leaves the other to fail 401 wherever it is loaded first.` : null;
+    const warning = divergentSources.length > 0 ? `Credential sources disagree for '${name}': ${winner.src.path} and ` + `${divergentSources.join(", ")} hold different keys. ${winner.src.path} wins, because a file on ` + `disk is re-read on every call while an environment variable is a snapshot. Reconcile them \u2014 ` + `a rotation that updated only one leaves the other to fail 401 wherever it is loaded first.` : null;
     return sealCredential({
       apiKey: winner.value,
-      tier: "disk",
-      source: winner.path,
+      tier: winner.src.tier,
+      source: winner.src.path,
       deliberate: false,
-      deprecated: false,
       diskCandidates: diskPaths,
       warning
     });
   }
-  const legacy = firstEnvValue(env, apiKeyKeys);
-  if (legacy) {
-    assertUsableCredential(name, legacy.key, legacy.value);
-    const where = diskPaths.length > 0 ? `Put the current key in ${diskPaths[0]} \u2014 it is re-read on every call, so rotations take effect immediately.` : `This environment has no HOME, so no credential file could be consulted at all; the disk tier is ` + `unavailable here and this process will keep using the environment snapshot.`;
-    const message = `[${name}] DEPRECATED: the API key came from ${legacy.key} in this process's environment. ` + `Environment variables are a snapshot taken when this process started, so a shell that started ` + `before a key rotation keeps using the old key until it exits. ${where}`;
-    const sink = options.onDeprecation ?? defaultDeprecationSink;
-    const notified = deprecationNotified();
-    if (!notified.has(name)) {
-      notified.add(name);
-      sink(message);
-    }
+  if (envHit) {
+    assertUsableCredential(name, envHit.key, envHit.value);
     return sealCredential({
-      apiKey: legacy.value,
-      tier: "legacy-env",
-      source: legacy.key,
+      apiKey: envHit.value,
+      tier: "env",
+      source: envHit.key,
       deliberate: false,
-      deprecated: true,
       diskCandidates: diskPaths,
-      warning: message
+      warning: null
     });
   }
   return null;
 }
+var SECRETS_PACKAGE_SPECIFIER = "@hasna/" + "secrets";
+var requireSecretsSdk = createRequire(import.meta.url);
+var DEFAULT_FLEET_GATEWAY_ORIGIN = "https://api.hasna.com";
+var DEFAULT_AUTHORITY_SOURCE = "default";
+function defaultFleetGatewayBaseUrl(name) {
+  return `${DEFAULT_FLEET_GATEWAY_ORIGIN}/${validateAppSlug(name)}`;
+}
 var ASCII_CONTROL_PATTERN = /[\u0000-\u001f\u007f]/;
 var DNS_LABEL_PATTERN = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/;
 function isValidDnsDomain(value) {
@@ -1473,21 +1663,11 @@ function isValidDnsDomain(value) {
   }
   return value.split(".").every((label) => label.length <= 63 && !label.startsWith("xn--") && DNS_LABEL_PATTERN.test(label));
 }
-function firstEnv(env, keys, options = {}) {
-  for (const key of keys) {
-    const raw = env[key];
-    const value = raw?.trim();
-    if (value)
-      return { key, value: options.preserveRaw ? raw : value };
-  }
-  return null;
-}
-function firstEnvDefinedKey(env, keys) {
-  for (const key of keys) {
-    if (env[key] !== undefined)
-      return key;
+function validateAppSlug(name) {
+  if (name.length > 63 || !DNS_LABEL_PATTERN.test(name)) {
+    throw new Error("App name must be one lowercase DNS label.");
   }
-  return null;
+  return name;
 }
 function rawAuthority(value) {
   const match = /^[a-z][a-z0-9+.-]*:\/\//i.exec(value);
@@ -1590,140 +1770,102 @@ function toV1BaseUrl(apiUrl) {
   url.pathname = `${path}/v1`;
   return url.toString().replace(/\/+$/, "");
 }
-function resolveClientTransport(name, env = process.env, options = {}) {
+class ClientTransportConfigurationError extends Error {
+  appName;
+  sources;
+  constructor(appName, message, sources = []) {
+    super(message);
+    this.name = "ClientTransportConfigurationError";
+    this.appName = appName;
+    this.sources = Object.freeze([...sources]);
+  }
+}
+function resolveClientTransportSnapshot(name, env = process.env, options = {}) {
+  env = snapshotClientEnvironment(name, env);
   const keys = clientTransportEnvKeys(name);
-  const envUrlHit = firstEnv(env, keys.apiUrlKeys, { preserveRaw: true });
-  const explicitLocalKey = envUrlHit ? null : firstEnvDefinedKey(env, keys.apiUrlKeys);
-  const diskUrlHit = envUrlHit || explicitLocalKey ? null : appConfigDiskValue(name, env, keys.apiUrlKeys);
-  const urlHit = envUrlHit ?? (diskUrlHit ? { key: diskUrlHit.path, value: diskUrlHit.value } : null);
-  const keyHit = firstEnv(env, keys.apiKeyKeys);
-  const warnings = [];
-  if (!urlHit) {
-    if (explicitLocalKey) {
-      const overriddenPointer = appConfigDiskValue(name, env, keys.apiUrlKeys);
-      if (overriddenPointer) {
-        warnings.push(`${explicitLocalKey} is defined but blank, which selects the local store. ` + `The server URL in ${overriddenPointer.path} was NOT selected: an explicit blank wins over a disk pointer.`);
-      }
-      return {
-        transport: "sqlite",
-        transportSource: explicitLocalKey,
-        baseUrl: null,
-        apiUrlSource: null,
-        apiKeyPresent: Boolean(keyHit),
-        apiKeySource: keyHit ? keyHit.key : null,
-        apiKeyTier: null,
-        misconfigured: false,
-        warning: warnings.length > 0 ? warnings.join(" ") : null
-      };
-    }
-    return {
-      transport: "sqlite",
-      transportSource: "default",
-      baseUrl: null,
-      apiUrlSource: null,
-      apiKeyPresent: Boolean(keyHit),
-      apiKeySource: keyHit ? keyHit.key : null,
-      apiKeyTier: null,
-      misconfigured: false,
-      warning: null
-    };
+  const definedUrlEntries = keys.apiUrlKeys.filter((key) => Object.prototype.hasOwnProperty.call(env, key) && env[key] !== undefined).map((key) => ({ key, raw: String(env[key]) }));
+  const blankUrl = definedUrlEntries.find((entry) => entry.raw.trim().length === 0);
+  if (blankUrl) {
+    throw new ClientTransportConfigurationError(name, `${blankUrl.key} is set but blank; public clients require an explicit HTTPS API URL and never select local storage.`, [blankUrl.key]);
+  }
+  const controlledUrl = definedUrlEntries.find((entry) => ASCII_CONTROL_PATTERN.test(entry.raw));
+  if (controlledUrl) {
+    throw new ClientTransportConfigurationError(name, `${controlledUrl.key} contains ASCII control characters.`, [controlledUrl.key]);
+  }
+  const usableUrlEntries = definedUrlEntries.map((entry) => ({ key: entry.key, value: entry.raw.trim() }));
+  if (usableUrlEntries.length > 1 && new Set(usableUrlEntries.map((entry) => entry.value)).size > 1) {
+    throw new ClientTransportConfigurationError(name, `${usableUrlEntries.map((entry) => entry.key).join(" and ")} disagree; client authority aliases must be identical or only one may be set.`, usableUrlEntries.map((entry) => entry.key));
+  }
+  const envUrlHit = usableUrlEntries[0] ?? null;
+  const keychainUrlHit = keychainConfigValue(name, env, options.credentials?.keychain);
+  const diskConfigUrlHit = appConfigDiskValue(name, env, keys.apiUrlKeys);
+  if (diskConfigUrlHit?.unusable) {
+    throw new ClientTransportConfigurationError(name, `${diskConfigUrlHit.key} in ${diskConfigUrlHit.path} is declared but blank or malformed; public clients require a valid HTTPS service authority.`, [diskConfigUrlHit.path]);
+  }
+  const urlCandidates = [
+    ...envUrlHit ? [envUrlHit] : [],
+    ...keychainUrlHit ? [{ key: keychainUrlHit.source, value: keychainUrlHit.value }] : [],
+    ...diskConfigUrlHit ? [{ key: diskConfigUrlHit.path, value: diskConfigUrlHit.value.trim() }] : []
+  ];
+  const configuredUrl = urlCandidates[0] ?? null;
+  const divergentUrls = urlCandidates.filter((candidate) => candidate.value !== configuredUrl?.value);
+  if (configuredUrl && divergentUrls.length > 0) {
+    throw new ClientTransportConfigurationError(name, `${configuredUrl.key} and ${divergentUrls.map((candidate) => candidate.key).join(" and ")} select different service authorities; refusing to send a credential written for one authority to the other.`, urlCandidates.map((candidate) => candidate.key));
   }
-  if (diskUrlHit) {
-    warnings.push(`No ${keys.apiUrlKeys[0]} in the environment; the server URL in ${diskUrlHit.path} was used, so this client connects to the server. ` + `Unset the pointer or remove the file to stay on the local store.`);
+  const warnings = [];
+  if (configuredUrl && !envUrlHit) {
+    warnings.push(`No ${keys.apiUrlKeys[0]} in the environment; the server URL in ${configuredUrl.key} was used, so this client connects to the server. ` + `Keep that entry aligned with the intended service authority.`);
   }
   const credential = resolveCredential(name, env, options.credentials);
   if (!credential) {
     const diskHint = credentialDiskSourcesForMessage(name, env);
-    warnings.push(`${urlHit.key} selects the HTTP server for '${name}', but no API key could be resolved; ` + `refusing to route and leaving the local sqlite store selected. ` + `Looked for a credential file at ${diskHint}, then for ${keys.apiKeyKeys[0]} in the environment.`);
-    return {
-      transport: "sqlite",
-      transportSource: urlHit.key,
-      baseUrl: null,
-      apiUrlSource: urlHit.key,
-      apiKeyPresent: false,
-      apiKeySource: null,
-      apiKeyTier: null,
-      misconfigured: true,
-      warning: warnings.join(" ")
-    };
+    const lead = configuredUrl ? `${configuredUrl.key} selects the HTTP server for '${name}', but no API key could be resolved` : `${keys.apiUrlKeys[0]} is not set and no API key could be resolved for '${name}'; a credential is required before the default fleet gateway authority applies`;
+    warnings.push(`${lead}; refusing to create an unauthenticated client \u2014 public clients never fall back to SQLite or another local store. ` + `Looked in the Keychain (macOS only), then for a credential file at ${diskHint}, then for ${keys.apiKeyKeys[0]} in the environment.`);
+    throw new ClientTransportConfigurationError(name, warnings.join(" "), [configuredUrl?.key ?? keys.apiUrlKeys[0]]);
   }
   if (credential.warning)
     warnings.push(credential.warning);
+  let urlHit;
+  if (configuredUrl) {
+    urlHit = configuredUrl;
+  } else {
+    try {
+      urlHit = { key: DEFAULT_AUTHORITY_SOURCE, value: defaultFleetGatewayBaseUrl(name) };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new ClientTransportConfigurationError(name, `No ${keys.apiUrlKeys[0]} is configured and the default fleet gateway authority cannot be composed for '${name}': ${message}`, [keys.apiUrlKeys[0]]);
+    }
+  }
   const apiUrlSource = urlHit.key;
   let baseUrl;
   try {
     baseUrl = toV1BaseUrl(urlHit.value);
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
-    warnings.push(`Invalid API URL from ${apiUrlSource}: ${message}. Using local store.`);
-    return {
-      transport: "sqlite",
+    throw new ClientTransportConfigurationError(name, `Invalid API URL from ${apiUrlSource}: ${message}`, [apiUrlSource]);
+  }
+  return {
+    resolution: {
+      transport: "http",
       transportSource: urlHit.key,
-      baseUrl: null,
-      apiUrlSource: urlHit.key,
+      baseUrl,
+      apiUrlSource,
       apiKeyPresent: true,
       apiKeySource: credential.source,
       apiKeyTier: credential.tier,
-      misconfigured: true,
-      warning: warnings.join(" ")
-    };
-  }
-  return {
-    transport: "http",
-    transportSource: urlHit.key,
-    baseUrl,
-    apiUrlSource,
-    apiKeyPresent: true,
-    apiKeySource: credential.source,
-    apiKeyTier: credential.tier,
-    misconfigured: false,
-    warning: warnings.length > 0 ? warnings.join(" ") : null
+      misconfigured: false,
+      warning: warnings.length > 0 ? warnings.join(" ") : null
+    },
+    credential
   };
 }
+function resolveClientTransport(name, env = process.env, options = {}) {
+  return resolveClientTransportSnapshot(name, env, options).resolution;
+}
 function credentialDiskSourcesForMessage(name, env) {
   const paths = credentialDiskSources(name, env);
-  return paths.length > 0 ? paths.join(" or ") : "<no HOME set in this environment, so no credential file was consulted>";
-}
-
-class HasnaHttpError extends Error {
-  status;
-  method;
-  path;
-  body;
-  credentialSource;
-  credentialTier;
-  constructor(method, path, status, body, credential) {
-    const guidance = credential ? `. ${credential.guidance}` : "";
-    super(`Hasna cloud request failed: ${method} ${path} -> ${status}${guidance}`);
-    this.name = "HasnaHttpError";
-    this.status = status;
-    this.method = method;
-    this.path = path;
-    this.body = body;
-    this.credentialSource = credential?.source ?? null;
-    this.credentialTier = credential?.tier ?? null;
-  }
-}
-function currentCredential(name, apiKey) {
-  if (typeof apiKey === "function") {
-    return validateAndSealResolvedCredential(name, apiKey());
-  }
-  return explicitCredential(name, apiKey);
-}
-function authFailureGuidance(credential) {
-  const origin = `The API key for this request came from ${credential.source}`;
-  if (credential.deliberate) {
-    const remedy = credential.source === CALLER_SUPPLIED_CREDENTIAL_PROVIDER_SOURCE ? `Fix that provider so it returns the current key, or replace it with resolveCredential() ` + `so diagnostics can name the original source.` : `Rotate that key, or unset the override to use the credential on disk.`;
-    return `${origin} \u2014 a credential you selected deliberately. It was NOT substituted with any other key: ` + `falling back here would authenticate as a different principal than the one you named, which is ` + `exactly the failure an override exists to prevent. ${remedy}`;
-  }
-  if (credential.deprecated) {
-    const target = credential.diskCandidates[0];
-    const remedy = target ? `Write the CURRENT key to ${target} \u2014 that file is re-read on every call, so rotations take ` + `effect immediately and in every shell. Do not simply unset ${credential.source}: nothing was ` + `found on disk, so that would leave this client with no credential at all.` : `This environment has no HOME, so no credential file could be consulted; the disk tier is ` + `unavailable here and there is nothing to fall back to. Set HOME, or supply the key explicitly.`;
-    return `${origin}, a variable in this process's environment \u2014 which is a snapshot taken when the process ` + `started. A STALE SHELL is the most common cause of this error: this shell exported the key before ` + `it was rotated, and will keep sending the old one until it exits. ${remedy}`;
-  }
-  return `${origin}, which was re-read from disk on this very call \u2014 so a stale shell is NOT the cause here. ` + `The stored credential is genuinely being rejected: rotate it, or re-run the fleet key distribution ` + `so this machine gets the current key.`;
+  return paths.length > 0 ? paths.join(" or ") : "<no HOME or HASNA_HOME set in this environment, so no credential file was consulted>";
 }
-var DEFAULT_RETRY_STATUSES = [408, 425, 429, 500, 502, 503, 504];
 var IDEMPOTENT_METHODS = new Set(["GET", "HEAD", "PUT", "DELETE", "OPTIONS"]);
 var AUTHORITY_OVERRIDE_HEADERS = new Set([
   "host",
@@ -1732,215 +1874,32 @@ var AUTHORITY_OVERRIDE_HEADERS = new Set([
   "x-forwarded-host",
   "x-original-host"
 ]);
-function assertNoAuthorityOverrideHeaders(headers, source) {
-  if (!headers)
-    return;
-  const forbidden = Object.keys(headers).find((name) => AUTHORITY_OVERRIDE_HEADERS.has(name.trim().toLowerCase()));
-  if (forbidden) {
-    throw new Error(`Authenticated ${source} headers must not set authority header '${forbidden}'.`);
-  }
+
+// ../contracts/dist/client/storage.js
+import { isIP as isIP2 } from "net";
+import { spawnSync as spawnSync3 } from "child_process";
+import { closeSync as closeSync2, fstatSync as fstatSync2, openSync as openSync2, readFileSync as readFileSync3 } from "fs";
+import { O_NOFOLLOW as O_NOFOLLOW2, O_NONBLOCK as O_NONBLOCK2, O_RDONLY as O_RDONLY2 } from "constants";
+import { createRequire as createRequire2 } from "module";
+import { hostname as osHostname2 } from "os";
+import { isAbsolute as isAbsolute3, join as join4 } from "path";
+function envToken2(name) {
+  return name.toUpperCase().replace(/-/g, "_");
 }
-function appendQuery(path, query) {
-  if (!query)
-    return path;
-  const params = query instanceof URLSearchParams ? query : new URLSearchParams;
-  if (!(query instanceof URLSearchParams)) {
-    for (const [key, value] of Object.entries(query)) {
-      if (value === null || value === undefined)
-        continue;
-      if (Array.isArray(value)) {
-        for (const v of value)
-          params.append(key, String(v));
-      } else {
-        params.append(key, String(value));
-      }
-    }
-  }
-  const qs = params.toString();
-  if (!qs)
-    return path;
-  return `${path}${path.includes("?") ? "&" : "?"}${qs}`;
-}
-var defaultSleep = (ms) => new Promise((resolve3) => setTimeout(resolve3, ms));
-function createHasnaHttpTransport(options) {
-  const fetchImpl = options.fetchImpl ?? ((input, init) => fetch(input, init));
-  const base = toV1BaseUrl(options.baseUrl);
-  const timeoutMs = options.timeoutMs ?? 30000;
-  const sleep = options.sleepImpl ?? defaultSleep;
-  const defaultRetry = options.retry;
-  function resolveRetry(callRetry) {
-    const chosen = callRetry !== undefined ? callRetry : defaultRetry;
-    if (chosen === false)
-      return null;
-    const r = chosen ?? {};
-    return {
-      retries: r.retries ?? 2,
-      baseDelayMs: r.baseDelayMs ?? 200,
-      maxDelayMs: r.maxDelayMs ?? 2000,
-      retryStatuses: r.retryStatuses ?? [...DEFAULT_RETRY_STATUSES]
-    };
-  }
-  async function once(method, rel, url, body, opts, credential) {
-    assertNoAuthorityOverrideHeaders(options.headers, "transport");
-    assertNoAuthorityOverrideHeaders(opts.headers, "request");
-    const headers = {
-      "x-api-key": credential.apiKey,
-      Authorization: `Bearer ${credential.apiKey}`,
-      Accept: "application/json",
-      ...options.headers ?? {},
-      ...opts.headers ?? {}
-    };
-    if (opts.idempotencyKey)
-      headers["Idempotency-Key"] = opts.idempotencyKey;
-    const init = {
-      method,
-      headers,
-      redirect: "manual"
-    };
-    if (body !== undefined) {
-      headers["Content-Type"] = "application/json";
-      init.body = JSON.stringify(body);
-    }
-    const controller = new AbortController;
-    const onAbort = () => controller.abort();
-    if (opts.signal) {
-      if (opts.signal.aborted)
-        controller.abort();
-      else
-        opts.signal.addEventListener("abort", onAbort, { once: true });
-    }
-    const timer = setTimeout(() => controller.abort(), opts.timeoutMs ?? timeoutMs);
-    init.signal = controller.signal;
-    let response;
-    try {
-      response = await fetchImpl(url, init);
-    } catch (error) {
-      const err = error instanceof Error ? error : new Error(String(error));
-      if (opts.signal?.aborted)
-        return { ok: false, retryable: false, error: err };
-      return { ok: false, retryable: true, error: err };
-    } finally {
-      clearTimeout(timer);
-      if (opts.signal)
-        opts.signal.removeEventListener("abort", onAbort);
-    }
-    const text = await response.text();
-    let parsed = undefined;
-    if (text.length > 0) {
-      try {
-        parsed = JSON.parse(text);
-      } catch {
-        parsed = text;
-      }
-    }
-    if (!response.ok) {
-      if (response.status >= 300 && response.status < 400) {
-        return {
-          ok: false,
-          retryable: false,
-          error: new HasnaHttpError(method, rel, response.status, parsed)
-        };
-      }
-      if (response.status === 401 || response.status === 403) {
-        return {
-          ok: false,
-          retryable: false,
-          error: new HasnaHttpError(method, rel, response.status, parsed, {
-            source: credential.source,
-            tier: credential.tier,
-            guidance: authFailureGuidance(credential)
-          })
-        };
-      }
-      const retry = resolveRetry(opts.retry);
-      const retryable = retry ? retry.retryStatuses.includes(response.status) : false;
-      return { ok: false, retryable, error: new HasnaHttpError(method, rel, response.status, parsed) };
-    }
-    return { ok: true, value: parsed };
-  }
-  async function request(method, path, body, opts = {}) {
-    const upper = method.toUpperCase();
-    const rel = appendQuery(path.startsWith("/") ? path : `/${path}`, opts.query);
-    const url = `${base}${rel}`;
-    const retry = resolveRetry(opts.retry);
-    const methodRetryable = IDEMPOTENT_METHODS.has(upper) || Boolean(opts.idempotencyKey);
-    const maxAttempts = retry && methodRetryable ? retry.retries + 1 : 1;
-    const credential = currentCredential(options.name, options.apiKey);
-    let last = null;
-    for (let attempt = 1;attempt <= maxAttempts; attempt++) {
-      const result = await once(upper, rel, url, body, opts, credential);
-      if (result.ok)
-        return result.value;
-      last = result;
-      const canRetry = retry !== null && methodRetryable && result.retryable && attempt < maxAttempts;
-      if (!canRetry)
-        break;
-      const backoff = Math.min(retry.maxDelayMs, retry.baseDelayMs * 2 ** (attempt - 1));
-      const jitter = Math.floor(Math.random() * (backoff / 2 + 1));
-      await sleep(backoff + jitter);
-    }
-    throw last.error;
-  }
-  return {
-    baseUrl: base,
-    request,
-    get: (path, opts) => request("GET", path, undefined, opts),
-    post: (path, body, opts) => request("POST", path, body, opts),
-    put: (path, body, opts) => request("PUT", path, body, opts),
-    patch: (path, body, opts) => request("PATCH", path, body, opts),
-    del: (path, body, opts) => request("DELETE", path, body, opts)
-  };
-}
-function createClientTransport(name, env = process.env, overrides) {
-  const credentialOptions = overrides?.credentials;
-  const resolution = resolveClientTransport(name, env, { ...credentialOptions ? { credentials: credentialOptions } : {} });
-  if (resolution.misconfigured) {
-    throw new Error(resolution.warning ?? `Client for '${name}' is misconfigured for the API client.`);
-  }
-  if (resolution.transport === "sqlite" || !resolution.baseUrl) {
-    return { transport: "sqlite", client: null, resolution };
-  }
-  const credentialProvider = () => {
-    const resolved = resolveCredential(name, env, credentialOptions);
-    if (!resolved) {
-      throw new Error(`Client for '${name}' resolved to the http transport but no API key is available any more. ` + `Looked at ${credentialDiskSourcesForMessage(name, env)}, then the environment. ` + `A credential file that was removed after this client was built is the usual cause.`);
-    }
-    return resolved;
-  };
-  return {
-    transport: "http",
-    client: createHasnaHttpTransport({
-      name,
-      baseUrl: resolution.baseUrl,
-      apiKey: credentialProvider,
-      ...overrides?.fetchImpl ? { fetchImpl: overrides.fetchImpl } : {},
-      ...overrides?.headers ? { headers: overrides.headers } : {},
-      ...overrides?.timeoutMs ? { timeoutMs: overrides.timeoutMs } : {},
-      ...overrides?.retry !== undefined ? { retry: overrides.retry } : {},
-      ...overrides?.sleepImpl ? { sleepImpl: overrides.sleepImpl } : {}
-    }),
-    resolution
-  };
-}
-
-// ../contracts/dist/client/storage.js
-import { isIP as isIP2 } from "net";
-import { readFileSync as readFileSync3, statSync as statSync3 } from "fs";
-import { join as join4 } from "path";
-function envToken2(name) {
-  return name.toUpperCase().replace(/-/g, "_");
-}
-function clientTransportEnvKeys2(name) {
-  const envSegment = envToken2(name);
-  return {
-    apiUrlKeys: [`HASNA_${envSegment}_API_URL`, `${envSegment}_API_URL`],
-    apiKeyKeys: [`HASNA_${envSegment}_API_KEY`, `${envSegment}_API_KEY`]
-  };
+function clientTransportEnvKeys2(name) {
+  const envSegment = envToken2(name);
+  return {
+    apiUrlKeys: [`HASNA_${envSegment}_API_URL`, `${envSegment}_API_URL`],
+    apiKeyKeys: [`HASNA_${envSegment}_API_KEY`, `${envSegment}_API_KEY`]
+  };
 }
 function credentialOverrideEnvKey2(name) {
   return `HASNA_${envToken2(name)}_API_KEY_OVERRIDE`;
 }
 var CREDENTIAL_PROFILE_ENV_KEY2 = "HASNA_PROFILE";
+function credentialPointerEnvKey2(name) {
+  return `HASNA_${envToken2(name)}_API_KEY_REF`;
+}
 
 class CredentialResolutionError2 extends Error {
   appName;
@@ -1952,34 +1911,70 @@ class CredentialResolutionError2 extends Error {
     this.attempted = attempted;
   }
 }
-var HASNA_STATE_DIR2 = ".hasna";
-var FLEET_CREDENTIAL_DIR2 = "cloud";
-var CONFIG_DIR2 = ".config";
-var CONFIG_NAMESPACE2 = "hasna";
+
+class CredentialFileUnsafeError2 extends Error {
+  path;
+  constructor(path, reason) {
+    super(`Refusing unsafe credential/config file ${path}: ${reason}.`);
+    this.name = "CredentialFileUnsafeError";
+    this.path = path;
+  }
+}
+var HASNA_HOME_ENV_KEY2 = "HASNA_HOME";
+var HASNA_CONFIG_HOME_ENV_KEY2 = "HASNA_CONFIG_HOME";
+var KEYCHAIN_STATION_ENV_KEY2 = "HASNA_STATION";
+var HASNA_HOME_DIR2 = ".hasna";
+var CONFIG_SUBDIR2 = "config";
+var CREDENTIALS_FILE2 = "credentials";
+var KEYCHAIN_SECURITY_BIN2 = "/usr/bin/security";
+var KEYCHAIN_SERVICE_PREFIX2 = "hasna.credentials";
+var KEYCHAIN_ITEM_NOT_FOUND_STATUS2 = 44;
+var KEYCHAIN_SPAWN_TIMEOUT_MS2 = 1e4;
 var MAX_CREDENTIAL_FILE_BYTES2 = 64 * 1024;
 var SAFE_APP_SLUG2 = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/;
 var SAFE_PROFILE2 = /^[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?$/;
 var ILLEGAL_IN_HEADER_VALUE2 = /[^\t\x20-\x7e]/;
+var VAULT_POINTER_SHAPE2 = /^[a-z0-9][a-z0-9-]*(?:\/[a-z0-9][a-z0-9-_.]*){2,}$/;
 function homeDir2(env) {
   const home = env.HOME?.trim();
   return home ? home : null;
 }
-function credentialDiskSources2(name, env) {
-  return profileDiskSources2(name, env, null);
+function absoluteOverride2(env, key) {
+  const value = env[key]?.trim();
+  return value && isAbsolute3(value) ? value : null;
 }
-function profileDiskSources2(name, env, profile) {
+function hasnaHomeDir2(env) {
+  const override = absoluteOverride2(env, HASNA_HOME_ENV_KEY2);
+  if (override)
+    return override;
   const home = homeDir2(env);
-  if (!home || !SAFE_APP_SLUG2.test(name))
+  return home ? join4(home, HASNA_HOME_DIR2) : null;
+}
+function appConfigDir2(name, env) {
+  const configRoot = absoluteOverride2(env, HASNA_CONFIG_HOME_ENV_KEY2);
+  if (configRoot)
+    return join4(configRoot, name);
+  const root = hasnaHomeDir2(env);
+  return root ? join4(root, name, CONFIG_SUBDIR2) : null;
+}
+function credentialDiskSourceList2(name, env, profile = null) {
+  if (!SAFE_APP_SLUG2.test(name))
     return [];
-  const stem = profile ? `${name}.${profile}` : name;
-  const configStem = profile ? `${name}-${profile}` : name;
-  return [
-    join4(home, HASNA_STATE_DIR2, FLEET_CREDENTIAL_DIR2, `${stem}.env`),
-    join4(home, CONFIG_DIR2, CONFIG_NAMESPACE2, `${configStem}-cloud.env`)
-  ];
+  const directory = appConfigDir2(name, env);
+  if (!directory)
+    return [];
+  const file = profile ? `${CREDENTIALS_FILE2}-${profile}` : CREDENTIALS_FILE2;
+  return [{ path: join4(directory, file), tier: "disk" }];
+}
+function credentialDiskSources2(name, env) {
+  return credentialDiskSourceList2(name, env, null).map((s) => s.path);
+}
+function profileDiskSources2(name, env, profile) {
+  return credentialDiskSourceList2(name, env, profile).map((s) => s.path);
 }
 function parseEnvFile2(text) {
   const values = new Map;
+  const unusable = new Set;
   for (const rawLine of text.split(/\r?\n/)) {
     const line = rawLine.trim();
     if (line.length === 0 || line.startsWith("#"))
@@ -1994,38 +1989,81 @@ function parseEnvFile2(text) {
     let value = withoutExport.slice(equals + 1).trim();
     const quote = value[0];
     if (quote === '"' || quote === "'") {
-      if (value.length < 2 || !value.endsWith(quote))
+      if (value.length < 2 || !value.endsWith(quote)) {
+        unusable.add(key);
         continue;
+      }
       value = value.slice(1, -1);
     }
-    if (value.length === 0)
+    if (value.trim().length === 0) {
+      unusable.add(key);
       continue;
+    }
+    if (values.has(key) && values.get(key) !== value)
+      unusable.add(key);
     values.set(key, value);
   }
-  return values;
+  return { values, unusable };
+}
+function configFileModeAllowed2(mode) {
+  const permissions = mode & 4095;
+  return permissions === 256 || permissions === 384;
+}
+function configFileReadsCoherent2(before, after) {
+  return before.dev === after.dev && before.ino === after.ino && before.size === after.size && before.mtimeMs === after.mtimeMs && before.ctimeMs === after.ctimeMs;
 }
 function readAppConfigFile2(path) {
-  let text;
+  const unsafe = (reason) => {
+    throw new CredentialFileUnsafeError2(path, reason);
+  };
+  let fd = -1;
   try {
-    const stats = statSync3(path);
-    if (!stats.isFile() || stats.size > MAX_CREDENTIAL_FILE_BYTES2)
+    fd = openSync2(path, O_RDONLY2 | O_NOFOLLOW2 | O_NONBLOCK2);
+  } catch (error) {
+    const code = error.code;
+    if (code === "ENOENT" || code === "ENOTDIR")
       return null;
-    text = readFileSync3(path, "utf8");
-  } catch {
-    return null;
+    if (code === "ELOOP")
+      unsafe("the path is a symlink");
+    unsafe(`the path could not be opened (${code ?? "unknown error"})`);
+  }
+  try {
+    const before = fstatSync2(fd);
+    if (!before.isFile())
+      unsafe("the path is not a regular file");
+    if (!configFileModeAllowed2(before.mode)) {
+      unsafe(`permission mode ${(before.mode & 4095).toString(8).padStart(4, "0")} is not owner-only 0400 or 0600`);
+    }
+    const uid = process.getuid?.() ?? process.geteuid?.();
+    if (uid !== undefined && before.uid !== uid)
+      unsafe("the file is not owned by the current user");
+    if (before.size > MAX_CREDENTIAL_FILE_BYTES2)
+      unsafe("the file exceeds the size limit");
+    const bytes = readFileSync3(fd);
+    const after = fstatSync2(fd);
+    if (!configFileReadsCoherent2(before, after)) {
+      unsafe("the file changed while being read");
+    }
+    return parseEnvFile2(bytes.toString("utf8"));
+  } finally {
+    if (fd !== -1)
+      closeSync2(fd);
   }
-  return parseEnvFile2(text);
 }
 function readCredentialFile2(path, apiKeyKeys) {
-  const values = readAppConfigFile2(path);
-  if (!values)
+  const parsed = readAppConfigFile2(path);
+  if (!parsed)
     return null;
   for (const key of apiKeyKeys) {
-    const value = values.get(key)?.trim();
-    if (value)
-      return value;
+    if (parsed.unusable.has(key)) {
+      throw new CredentialFileUnsafeError2(path, `${key} is declared but blank or malformed`);
+    }
   }
-  return null;
+  const values = apiKeyKeys.map((key) => parsed.values.get(key)?.trim()).filter((value) => Boolean(value));
+  if (new Set(values).size > 1) {
+    throw new CredentialFileUnsafeError2(path, "credential aliases disagree");
+  }
+  return values[0] ?? null;
 }
 var CREDENTIAL_SHAPED_KEY2 = /(?:^|_)(?:API_KEY|KEY|TOKEN|SECRET|PASSWORD|PASSWD|CREDENTIAL|AUTH)(?:_|$)/;
 function appConfigDiskValue2(name, env, keys) {
@@ -2033,11 +2071,19 @@ function appConfigDiskValue2(name, env, keys) {
   if (wanted.length === 0)
     return null;
   for (const path of credentialDiskSources2(name, env)) {
-    const values = readAppConfigFile2(path);
-    if (!values)
+    const parsed = readAppConfigFile2(path);
+    if (!parsed)
       continue;
+    if (wanted.some((key) => parsed.unusable.has(key))) {
+      return { key: wanted.find((key) => parsed.unusable.has(key)), value: "", path, unusable: true };
+    }
+    const values = wanted.map((key) => parsed.values.get(key)?.trim()).filter((value) => Boolean(value));
+    if (new Set(values).size > 1)
+      throw new CredentialFileUnsafeError2(path, "configuration aliases disagree");
     for (const key of wanted) {
-      const value = values.get(key)?.trim();
+      if (parsed.unusable.has(key))
+        return { key, value: "", path, unusable: true };
+      const value = parsed.values.get(key)?.trim();
       if (value)
         return { key, value, path };
     }
@@ -2045,20 +2091,22 @@ function appConfigDiskValue2(name, env, keys) {
   return null;
 }
 function assertUsableCredential2(appName, source, value) {
+  if (VAULT_POINTER_SHAPE2.test(value)) {
+    throw new CredentialResolutionError2(appName, `The credential from ${source} looks like a secrets-vault pointer (a path-shaped reference like ` + `'namespace/app/live/api_key'). A vault path is NEVER accepted as a literal API key. ` + `Use ${credentialPointerEnvKey2(appName)} to resolve the key through the vault, or provide the actual key value.`, [source]);
+  }
   if (!ILLEGAL_IN_HEADER_VALUE2.test(value))
     return;
   throw new CredentialResolutionError2(appName, `The credential from ${source} contains characters that cannot be sent in an HTTP header ` + `(a control character or non-ASCII byte). A file written with CR-only line endings is the usual ` + `cause. Rewrite that credential file with one LF-terminated KEY=value line. ` + `The value is not shown here, and is deliberately never logged.`, [source]);
 }
 var INSPECT_CUSTOM2 = Symbol.for("nodejs.util.inspect.custom");
 var CREDENTIAL_SEAL2 = Symbol.for("hasna:contracts:sealedCredential");
-var CALLER_SUPPLIED_CREDENTIAL_PROVIDER_SOURCE2 = "caller-supplied CredentialProvider";
+var CALLER_SUPPLIED_CREDENTIAL_PROVIDER_SOURCE = "caller-supplied CredentialProvider";
 function sealCredential2(fields) {
   const { apiKey } = fields;
   const visible = {
     tier: fields.tier,
     source: fields.source,
     deliberate: fields.deliberate,
-    deprecated: fields.deprecated,
     diskCandidates: Object.freeze([...fields.diskCandidates]),
     warning: fields.warning
   };
@@ -2069,6 +2117,14 @@ function sealCredential2(fields) {
     writable: false,
     configurable: false
   });
+  if (fields.pointerVaultKey !== undefined) {
+    Object.defineProperty(sealed, "pointerVaultKey", {
+      value: fields.pointerVaultKey,
+      enumerable: false,
+      writable: false,
+      configurable: false
+    });
+  }
   Object.defineProperty(sealed, INSPECT_CUSTOM2, {
     value: () => ({ ...visible, apiKey: "[redacted]" }),
     enumerable: false,
@@ -2083,10 +2139,10 @@ function sealCredential2(fields) {
   });
   return Object.freeze(sealed);
 }
-function isSealedCredential2(credential) {
+function isSealedCredential(credential) {
   return credential[CREDENTIAL_SEAL2] === true;
 }
-function explicitCredential2(appName, apiKey) {
+function explicitCredential(appName, apiKey) {
   const source = "explicit apiKey option";
   assertUsableCredential2(appName, source, apiKey);
   return sealCredential2({
@@ -2094,21 +2150,19 @@ function explicitCredential2(appName, apiKey) {
     tier: "argument",
     source,
     deliberate: true,
-    deprecated: false,
     diskCandidates: [],
     warning: null
   });
 }
-function validateAndSealResolvedCredential2(appName, credential) {
+function validateAndSealResolvedCredential(appName, credential) {
   const apiKey = credential.apiKey;
-  assertUsableCredential2(appName, CALLER_SUPPLIED_CREDENTIAL_PROVIDER_SOURCE2, apiKey);
-  if (!isSealedCredential2(credential)) {
+  assertUsableCredential2(appName, CALLER_SUPPLIED_CREDENTIAL_PROVIDER_SOURCE, apiKey);
+  if (!isSealedCredential(credential)) {
     return sealCredential2({
       apiKey,
       tier: "argument",
-      source: CALLER_SUPPLIED_CREDENTIAL_PROVIDER_SOURCE2,
+      source: CALLER_SUPPLIED_CREDENTIAL_PROVIDER_SOURCE,
       deliberate: true,
-      deprecated: false,
       diskCandidates: [],
       warning: null
     });
@@ -2118,53 +2172,147 @@ function validateAndSealResolvedCredential2(appName, credential) {
     tier: credential.tier,
     source: credential.source,
     deliberate: credential.deliberate,
-    deprecated: credential.deprecated,
     diskCandidates: credential.diskCandidates,
-    warning: credential.warning
+    warning: credential.warning,
+    ...credential.pointerVaultKey !== undefined ? { pointerVaultKey: credential.pointerVaultKey } : {}
   });
 }
 function firstEnvValue2(env, keys) {
   for (const key of keys) {
+    if (!Object.prototype.hasOwnProperty.call(env, key))
+      continue;
     const value = env[key]?.trim();
     if (value)
       return { key, value };
   }
   return null;
 }
-var DEPRECATION_REGISTRY2 = Symbol.for("hasna:contracts:credentialDeprecationNotices");
-function deprecationNotified2() {
-  const host = globalThis;
-  const existing = host[DEPRECATION_REGISTRY2];
-  if (existing instanceof Set)
-    return existing;
-  const created = new Set;
-  host[DEPRECATION_REGISTRY2] = created;
-  return created;
+var AMBIENT_ENVIRONMENT2 = Symbol.for("hasna:contracts:ambientClientEnvironment");
+function isAmbientEnvironment2(env) {
+  return env === process.env || env[AMBIENT_ENVIRONMENT2] === true;
+}
+function defaultKeychainRunner2(argv) {
+  const result = spawnSync3(KEYCHAIN_SECURITY_BIN2, [...argv], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+    timeout: KEYCHAIN_SPAWN_TIMEOUT_MS2
+  });
+  return {
+    status: result.status,
+    stdout: result.stdout ?? "",
+    stderr: result.error ? result.error.message : result.stderr ?? ""
+  };
+}
+function keychainTierEnabled2(env, options) {
+  if ((options.platform ?? process.platform) !== "darwin")
+    return false;
+  if (options.enabled !== undefined)
+    return options.enabled;
+  return options.run !== undefined || isAmbientEnvironment2(env);
+}
+function keychainAccount2(env, options) {
+  const station = env[KEYCHAIN_STATION_ENV_KEY2]?.trim();
+  if (station)
+    return station;
+  const host = (options.hostname ?? osHostname2)().split(".")[0]?.trim() ?? "";
+  if (host)
+    return host;
+  const user = env.USER?.trim();
+  return user || null;
+}
+function keychainFailureHint2(text) {
+  const line = text.split(/\r?\n/).find((entry) => entry.trim().length > 0)?.trim() ?? "";
+  const clean = line.replace(/[\u0000-\u001f\u007f]/g, "").slice(0, 200);
+  return clean ? `: ${clean}` : "";
+}
+function readKeychainItem2(name, env, kind, options) {
+  if (!SAFE_APP_SLUG2.test(name) || !keychainTierEnabled2(env, options))
+    return null;
+  const account = keychainAccount2(env, options);
+  if (!account)
+    return null;
+  const service = `${KEYCHAIN_SERVICE_PREFIX2}.${name}.${kind}`;
+  const source = `keychain:${service}@${account}`;
+  const run = options.run ?? defaultKeychainRunner2;
+  let result;
+  try {
+    result = run(["find-generic-password", "-a", account, "-s", service, "-w"]);
+  } catch (error) {
+    const reason = keychainFailureHint2(error instanceof Error ? error.message : String(error));
+    throw new CredentialResolutionError2(name, `The Keychain lookup for ${source} could not run${reason}. A Keychain failure is never resolved ` + `around: fix the keychain, or delete the item to fall through to the credential on disk.`, [source]);
+  }
+  if (result.status === KEYCHAIN_ITEM_NOT_FOUND_STATUS2)
+    return null;
+  if (result.status !== 0) {
+    throw new CredentialResolutionError2(name, `The Keychain lookup for ${source} failed (security exited ` + `${result.status ?? "without a status"}${keychainFailureHint2(result.stderr)}). A Keychain item that ` + `exists but cannot be read is never resolved around: unlock the keychain, run from a session that ` + `may use it, or delete the item to fall through to the credential on disk.`, [source]);
+  }
+  const value = result.stdout.trim();
+  if (!value) {
+    throw new CredentialResolutionError2(name, `${source} exists but holds an empty value; a declared item never falls through to another ` + `identity. Store a value in it or delete the item.`, [source]);
+  }
+  return { value, source };
+}
+function keychainConfigValue2(name, env, options = {}) {
+  return readKeychainItem2(name, env, "api-url", options);
 }
-function defaultDeprecationSink2(message) {
-  if (typeof process !== "undefined" && process.stderr) {
-    process.stderr.write(`${message}
-`);
+function snapshotClientEnvironment2(name, env) {
+  const keys = clientTransportEnvKeys2(name);
+  const ambient = isAmbientEnvironment2(env);
+  const snapshot = Object.create(null);
+  for (const key of [
+    ...keys.apiUrlKeys,
+    ...keys.apiKeyKeys,
+    credentialOverrideEnvKey2(name),
+    credentialPointerEnvKey2(name),
+    CREDENTIAL_PROFILE_ENV_KEY2,
+    "HOME",
+    HASNA_HOME_ENV_KEY2,
+    HASNA_CONFIG_HOME_ENV_KEY2,
+    KEYCHAIN_STATION_ENV_KEY2,
+    "USER"
+  ]) {
+    const descriptor = Object.getOwnPropertyDescriptor(env, key);
+    if (!descriptor)
+      continue;
+    if (!("value" in descriptor)) {
+      throw new CredentialResolutionError2(name, `${key} is accessor-backed; client configuration requires own data properties.`, [key]);
+    }
+    if (descriptor.value !== undefined && typeof descriptor.value !== "string") {
+      throw new CredentialResolutionError2(name, `${key} must be a string data property.`, [key]);
+    }
+    snapshot[key] = descriptor.value;
   }
+  if (ambient) {
+    Object.defineProperty(snapshot, AMBIENT_ENVIRONMENT2, {
+      value: true,
+      enumerable: false,
+      writable: false,
+      configurable: false
+    });
+  }
+  return Object.freeze(snapshot);
 }
 function resolveCredential2(name, env, options = {}) {
+  env = snapshotClientEnvironment2(name, env);
   const { apiKeyKeys } = clientTransportEnvKeys2(name);
   const diskPaths = credentialDiskSources2(name, env);
-  const explicitKey = options.apiKey?.trim();
-  if (explicitKey) {
+  if (options.apiKey !== undefined) {
+    const explicitKey = options.apiKey.trim();
+    if (!explicitKey) {
+      throw new CredentialResolutionError2(name, "The explicit apiKey argument is blank; an explicit credential never falls through to another identity.", ["explicit apiKey argument"]);
+    }
     assertUsableCredential2(name, "the explicit apiKey argument", explicitKey);
     return sealCredential2({
       apiKey: explicitKey,
       tier: "argument",
       source: "explicit apiKey argument",
       deliberate: true,
-      deprecated: false,
       diskCandidates: diskPaths,
       warning: null
     });
   }
   const overrideKeyName = credentialOverrideEnvKey2(name);
-  const overrideRaw = env[overrideKeyName];
+  const overrideRaw = Object.prototype.hasOwnProperty.call(env, overrideKeyName) ? env[overrideKeyName] : undefined;
   if (overrideRaw !== undefined) {
     const override = overrideRaw.trim();
     if (!override) {
@@ -2176,12 +2324,38 @@ function resolveCredential2(name, env, options = {}) {
       tier: "override",
       source: overrideKeyName,
       deliberate: true,
-      deprecated: false,
       diskCandidates: diskPaths,
       warning: null
     });
   }
-  const profile = options.profile?.trim() || env[CREDENTIAL_PROFILE_ENV_KEY2]?.trim();
+  const pointerKeyName = credentialPointerEnvKey2(name);
+  const pointerRaw = Object.prototype.hasOwnProperty.call(env, pointerKeyName) ? env[pointerKeyName] : undefined;
+  if (pointerRaw !== undefined) {
+    const pointer = pointerRaw.trim();
+    if (!pointer) {
+      throw new CredentialResolutionError2(name, `${pointerKeyName} is set but empty. It is a deliberate vault pointer, so it is not resolved around: ` + `either give it a vault item key or unset it to fall back to the credential on disk.`, [pointerKeyName]);
+    }
+    if (!VAULT_POINTER_SHAPE2.test(pointer)) {
+      throw new CredentialResolutionError2(name, `${pointerKeyName} must name a vault ITEM KEY (a path-shaped reference like ` + `'namespace/app/live/api_key'), not a credential value. A pointer that carries a literal is refused.`, [pointerKeyName]);
+    }
+    return sealCredential2({
+      apiKey: "",
+      pointerVaultKey: pointer,
+      tier: "pointer",
+      source: pointerKeyName,
+      deliberate: true,
+      diskCandidates: diskPaths,
+      warning: null
+    });
+  }
+  if (options.profile !== undefined && !options.profile.trim()) {
+    throw new CredentialResolutionError2(name, "The explicit profile argument is blank; an explicit identity selection never falls through.", ["explicit profile argument"]);
+  }
+  const profileRaw = Object.prototype.hasOwnProperty.call(env, CREDENTIAL_PROFILE_ENV_KEY2) ? env[CREDENTIAL_PROFILE_ENV_KEY2] : undefined;
+  if (profileRaw !== undefined && !profileRaw.trim()) {
+    throw new CredentialResolutionError2(name, `${CREDENTIAL_PROFILE_ENV_KEY2} is set but blank.`, [CREDENTIAL_PROFILE_ENV_KEY2]);
+  }
+  const profile = options.profile?.trim() || profileRaw?.trim();
   if (profile) {
     const profileSource = options.profile?.trim() ? "explicit profile argument" : CREDENTIAL_PROFILE_ENV_KEY2;
     if (!SAFE_PROFILE2.test(profile)) {
@@ -2197,7 +2371,6 @@ function resolveCredential2(name, env, options = {}) {
           tier: "profile",
           source: path,
           deliberate: true,
-          deprecated: false,
           diskCandidates: paths,
           warning: null
         });
@@ -2205,51 +2378,105 @@ function resolveCredential2(name, env, options = {}) {
     }
     throw new CredentialResolutionError2(name, `Profile '${profile}' (from ${profileSource}) has no ${apiKeyKeys[0]} for '${name}'. ` + `Looked in: ${paths.join(", ") || "<no HOME in this environment>"}. ` + `A profile names WHICH identity to use, so it is never resolved around \u2014 ` + `create the profile's credential file or unset ${CREDENTIAL_PROFILE_ENV_KEY2}.`, paths);
   }
-  const diskHits = diskPaths.map((path) => ({ path, value: readCredentialFile2(path, apiKeyKeys) })).filter((hit) => hit.value !== null);
+  const definedEnvEntries = apiKeyKeys.filter((key) => Object.prototype.hasOwnProperty.call(env, key) && env[key] !== undefined).map((key) => ({ key, value: String(env[key]).trim() }));
+  const blankEnv = definedEnvEntries.find((entry) => entry.value.length === 0);
+  if (blankEnv) {
+    throw new CredentialResolutionError2(name, `${blankEnv.key} is set but blank; a declared credential never falls through to another alias or identity.`, [blankEnv.key]);
+  }
+  if (definedEnvEntries.length > 1 && new Set(definedEnvEntries.map((entry) => entry.value)).size > 1) {
+    throw new CredentialResolutionError2(name, `${definedEnvEntries.map((entry) => entry.key).join(" and ")} disagree; credential aliases must be identical or only one may be set.`, definedEnvEntries.map((entry) => entry.key));
+  }
+  const envHit = firstEnvValue2(env, apiKeyKeys);
+  const keychainHit = readKeychainItem2(name, env, "api-key", options.keychain ?? {});
+  if (keychainHit) {
+    assertUsableCredential2(name, keychainHit.source, keychainHit.value);
+    const warning = envHit && envHit.value !== keychainHit.value ? `Credential sources disagree for '${name}': ${keychainHit.source} and ${envHit.key} hold ` + `different keys. ${keychainHit.source} wins, because the Keychain is re-read on every call while ` + `an environment variable is a snapshot. Reconcile them \u2014 a rotation that updated only one leaves ` + `the other to fail 401 wherever it is loaded first.` : null;
+    return sealCredential2({
+      apiKey: keychainHit.value,
+      tier: "keychain",
+      source: keychainHit.source,
+      deliberate: false,
+      diskCandidates: diskPaths,
+      warning
+    });
+  }
+  const diskSourceList = credentialDiskSourceList2(name, env, null);
+  const diskHits = diskSourceList.map((src) => ({ src, value: readCredentialFile2(src.path, apiKeyKeys) })).filter((hit) => hit.value !== null);
   if (diskHits.length > 0) {
     const winner = diskHits[0];
-    assertUsableCredential2(name, winner.path, winner.value);
+    assertUsableCredential2(name, winner.src.path, winner.value);
     const divergentSources = [
-      ...diskHits.slice(1).filter((hit) => hit.value !== winner.value).map((hit) => hit.path),
-      ...(() => {
-        const legacyHit = firstEnvValue2(env, apiKeyKeys);
-        return legacyHit && legacyHit.value !== winner.value ? [legacyHit.key] : [];
-      })()
+      ...diskHits.slice(1).filter((hit) => hit.value !== winner.value).map((hit) => hit.src.path),
+      ...envHit && envHit.value !== winner.value ? [envHit.key] : []
     ];
-    const warning = divergentSources.length > 0 ? `Credential sources disagree for '${name}': ${winner.path} and ` + `${divergentSources.join(", ")} hold different keys. ${winner.path} wins, because a file on ` + `disk is re-read on every call while an environment variable is a snapshot. Reconcile them \u2014 ` + `a rotation that updated only one leaves the other to fail 401 wherever it is loaded first.` : null;
+    const warning = divergentSources.length > 0 ? `Credential sources disagree for '${name}': ${winner.src.path} and ` + `${divergentSources.join(", ")} hold different keys. ${winner.src.path} wins, because a file on ` + `disk is re-read on every call while an environment variable is a snapshot. Reconcile them \u2014 ` + `a rotation that updated only one leaves the other to fail 401 wherever it is loaded first.` : null;
     return sealCredential2({
       apiKey: winner.value,
-      tier: "disk",
-      source: winner.path,
+      tier: winner.src.tier,
+      source: winner.src.path,
       deliberate: false,
-      deprecated: false,
       diskCandidates: diskPaths,
       warning
     });
   }
-  const legacy = firstEnvValue2(env, apiKeyKeys);
-  if (legacy) {
-    assertUsableCredential2(name, legacy.key, legacy.value);
-    const where = diskPaths.length > 0 ? `Put the current key in ${diskPaths[0]} \u2014 it is re-read on every call, so rotations take effect immediately.` : `This environment has no HOME, so no credential file could be consulted at all; the disk tier is ` + `unavailable here and this process will keep using the environment snapshot.`;
-    const message = `[${name}] DEPRECATED: the API key came from ${legacy.key} in this process's environment. ` + `Environment variables are a snapshot taken when this process started, so a shell that started ` + `before a key rotation keeps using the old key until it exits. ${where}`;
-    const sink = options.onDeprecation ?? defaultDeprecationSink2;
-    const notified = deprecationNotified2();
-    if (!notified.has(name)) {
-      notified.add(name);
-      sink(message);
-    }
+  if (envHit) {
+    assertUsableCredential2(name, envHit.key, envHit.value);
     return sealCredential2({
-      apiKey: legacy.value,
-      tier: "legacy-env",
-      source: legacy.key,
+      apiKey: envHit.value,
+      tier: "env",
+      source: envHit.key,
       deliberate: false,
-      deprecated: true,
       diskCandidates: diskPaths,
-      warning: message
+      warning: null
     });
   }
   return null;
 }
+var SECRETS_PACKAGE_SPECIFIER2 = "@hasna/" + "secrets";
+var requireSecretsSdk2 = createRequire2(import.meta.url);
+async function completePointerCredential(name, pointerResolution, env = process.env) {
+  const vaultKey = pointerResolution.pointerVaultKey;
+  const pointerEnvKey = pointerResolution.source;
+  if (!vaultKey) {
+    throw new CredentialResolutionError2(name, `Pointer resolution from ${pointerEnvKey} carries no vault item key; this is a defect in the resolver.`, [pointerEnvKey]);
+  }
+  let secretsSdk;
+  try {
+    secretsSdk = requireSecretsSdk2(SECRETS_PACKAGE_SPECIFIER2);
+  } catch {
+    throw new CredentialResolutionError2(name, `${pointerEnvKey} names vault item '${vaultKey}', but the secrets SDK (@hasna/secrets) is not installed ` + `in this process. A vault pointer is TERMINAL: install @hasna/secrets to resolve it, or unset ${pointerEnvKey}.`, [pointerEnvKey]);
+  }
+  let client;
+  try {
+    client = secretsSdk.createSecretsClientFromEnv(env);
+  } catch {
+    throw new CredentialResolutionError2(name, `${pointerEnvKey} names vault item '${vaultKey}', but the secrets client could not be configured from this ` + `environment (the secrets service URL and key env are missing or invalid). A vault pointer is TERMINAL and ` + `never falls through to a literal or disk credential.`, [pointerEnvKey]);
+  }
+  let secret;
+  try {
+    secret = await client.getSecret({ key: vaultKey });
+  } catch {
+    throw new CredentialResolutionError2(name, `${pointerEnvKey} names vault item '${vaultKey}', but the vault could not be reached or the item is ` + `unavailable. A vault pointer is TERMINAL and never falls through to a literal or disk credential.`, [pointerEnvKey]);
+  }
+  const value = secret.value;
+  if (!value) {
+    throw new CredentialResolutionError2(name, `${pointerEnvKey} resolved vault item '${vaultKey}', but it holds no value. A vault pointer is TERMINAL.`, [pointerEnvKey]);
+  }
+  assertUsableCredential2(name, `${pointerEnvKey} -> vault:${vaultKey}`, value);
+  return sealCredential2({
+    apiKey: value,
+    tier: "pointer",
+    source: `${pointerEnvKey} -> vault:${vaultKey}`,
+    deliberate: true,
+    diskCandidates: pointerResolution.diskCandidates,
+    warning: null
+  });
+}
+var DEFAULT_FLEET_GATEWAY_ORIGIN2 = "https://api.hasna.com";
+var DEFAULT_AUTHORITY_SOURCE2 = "default";
+function defaultFleetGatewayBaseUrl2(name) {
+  return `${DEFAULT_FLEET_GATEWAY_ORIGIN2}/${validateAppSlug2(name)}`;
+}
 var ASCII_CONTROL_PATTERN2 = /[\u0000-\u001f\u007f]/;
 var DNS_LABEL_PATTERN2 = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/;
 function isValidDnsDomain2(value) {
@@ -2258,21 +2485,11 @@ function isValidDnsDomain2(value) {
   }
   return value.split(".").every((label) => label.length <= 63 && !label.startsWith("xn--") && DNS_LABEL_PATTERN2.test(label));
 }
-function firstEnv2(env, keys, options = {}) {
-  for (const key of keys) {
-    const raw = env[key];
-    const value = raw?.trim();
-    if (value)
-      return { key, value: options.preserveRaw ? raw : value };
+function validateAppSlug2(name) {
+  if (name.length > 63 || !DNS_LABEL_PATTERN2.test(name)) {
+    throw new Error("App name must be one lowercase DNS label.");
   }
-  return null;
-}
-function firstEnvDefinedKey2(env, keys) {
-  for (const key of keys) {
-    if (env[key] !== undefined)
-      return key;
-  }
-  return null;
+  return name;
 }
 function rawAuthority2(value) {
   const match = /^[a-z][a-z0-9+.-]*:\/\//i.exec(value);
@@ -2375,106 +2592,104 @@ function toV1BaseUrl2(apiUrl) {
   url.pathname = `${path}/v1`;
   return url.toString().replace(/\/+$/, "");
 }
-function resolveClientTransport2(name, env = process.env, options = {}) {
+class ClientTransportConfigurationError2 extends Error {
+  appName;
+  sources;
+  constructor(appName, message, sources = []) {
+    super(message);
+    this.name = "ClientTransportConfigurationError";
+    this.appName = appName;
+    this.sources = Object.freeze([...sources]);
+  }
+}
+function resolveClientTransportSnapshot2(name, env = process.env, options = {}) {
+  env = snapshotClientEnvironment2(name, env);
   const keys = clientTransportEnvKeys2(name);
-  const envUrlHit = firstEnv2(env, keys.apiUrlKeys, { preserveRaw: true });
-  const explicitLocalKey = envUrlHit ? null : firstEnvDefinedKey2(env, keys.apiUrlKeys);
-  const diskUrlHit = envUrlHit || explicitLocalKey ? null : appConfigDiskValue2(name, env, keys.apiUrlKeys);
-  const urlHit = envUrlHit ?? (diskUrlHit ? { key: diskUrlHit.path, value: diskUrlHit.value } : null);
-  const keyHit = firstEnv2(env, keys.apiKeyKeys);
-  const warnings = [];
-  if (!urlHit) {
-    if (explicitLocalKey) {
-      const overriddenPointer = appConfigDiskValue2(name, env, keys.apiUrlKeys);
-      if (overriddenPointer) {
-        warnings.push(`${explicitLocalKey} is defined but blank, which selects the local store. ` + `The server URL in ${overriddenPointer.path} was NOT selected: an explicit blank wins over a disk pointer.`);
-      }
-      return {
-        transport: "sqlite",
-        transportSource: explicitLocalKey,
-        baseUrl: null,
-        apiUrlSource: null,
-        apiKeyPresent: Boolean(keyHit),
-        apiKeySource: keyHit ? keyHit.key : null,
-        apiKeyTier: null,
-        misconfigured: false,
-        warning: warnings.length > 0 ? warnings.join(" ") : null
-      };
-    }
-    return {
-      transport: "sqlite",
-      transportSource: "default",
-      baseUrl: null,
-      apiUrlSource: null,
-      apiKeyPresent: Boolean(keyHit),
-      apiKeySource: keyHit ? keyHit.key : null,
-      apiKeyTier: null,
-      misconfigured: false,
-      warning: null
-    };
+  const definedUrlEntries = keys.apiUrlKeys.filter((key) => Object.prototype.hasOwnProperty.call(env, key) && env[key] !== undefined).map((key) => ({ key, raw: String(env[key]) }));
+  const blankUrl = definedUrlEntries.find((entry) => entry.raw.trim().length === 0);
+  if (blankUrl) {
+    throw new ClientTransportConfigurationError2(name, `${blankUrl.key} is set but blank; public clients require an explicit HTTPS API URL and never select local storage.`, [blankUrl.key]);
+  }
+  const controlledUrl = definedUrlEntries.find((entry) => ASCII_CONTROL_PATTERN2.test(entry.raw));
+  if (controlledUrl) {
+    throw new ClientTransportConfigurationError2(name, `${controlledUrl.key} contains ASCII control characters.`, [controlledUrl.key]);
+  }
+  const usableUrlEntries = definedUrlEntries.map((entry) => ({ key: entry.key, value: entry.raw.trim() }));
+  if (usableUrlEntries.length > 1 && new Set(usableUrlEntries.map((entry) => entry.value)).size > 1) {
+    throw new ClientTransportConfigurationError2(name, `${usableUrlEntries.map((entry) => entry.key).join(" and ")} disagree; client authority aliases must be identical or only one may be set.`, usableUrlEntries.map((entry) => entry.key));
+  }
+  const envUrlHit = usableUrlEntries[0] ?? null;
+  const keychainUrlHit = keychainConfigValue2(name, env, options.credentials?.keychain);
+  const diskConfigUrlHit = appConfigDiskValue2(name, env, keys.apiUrlKeys);
+  if (diskConfigUrlHit?.unusable) {
+    throw new ClientTransportConfigurationError2(name, `${diskConfigUrlHit.key} in ${diskConfigUrlHit.path} is declared but blank or malformed; public clients require a valid HTTPS service authority.`, [diskConfigUrlHit.path]);
+  }
+  const urlCandidates = [
+    ...envUrlHit ? [envUrlHit] : [],
+    ...keychainUrlHit ? [{ key: keychainUrlHit.source, value: keychainUrlHit.value }] : [],
+    ...diskConfigUrlHit ? [{ key: diskConfigUrlHit.path, value: diskConfigUrlHit.value.trim() }] : []
+  ];
+  const configuredUrl = urlCandidates[0] ?? null;
+  const divergentUrls = urlCandidates.filter((candidate) => candidate.value !== configuredUrl?.value);
+  if (configuredUrl && divergentUrls.length > 0) {
+    throw new ClientTransportConfigurationError2(name, `${configuredUrl.key} and ${divergentUrls.map((candidate) => candidate.key).join(" and ")} select different service authorities; refusing to send a credential written for one authority to the other.`, urlCandidates.map((candidate) => candidate.key));
   }
-  if (diskUrlHit) {
-    warnings.push(`No ${keys.apiUrlKeys[0]} in the environment; the server URL in ${diskUrlHit.path} was used, so this client connects to the server. ` + `Unset the pointer or remove the file to stay on the local store.`);
+  const warnings = [];
+  if (configuredUrl && !envUrlHit) {
+    warnings.push(`No ${keys.apiUrlKeys[0]} in the environment; the server URL in ${configuredUrl.key} was used, so this client connects to the server. ` + `Keep that entry aligned with the intended service authority.`);
   }
   const credential = resolveCredential2(name, env, options.credentials);
   if (!credential) {
     const diskHint = credentialDiskSourcesForMessage2(name, env);
-    warnings.push(`${urlHit.key} selects the HTTP server for '${name}', but no API key could be resolved; ` + `refusing to route and leaving the local sqlite store selected. ` + `Looked for a credential file at ${diskHint}, then for ${keys.apiKeyKeys[0]} in the environment.`);
-    return {
-      transport: "sqlite",
-      transportSource: urlHit.key,
-      baseUrl: null,
-      apiUrlSource: urlHit.key,
-      apiKeyPresent: false,
-      apiKeySource: null,
-      apiKeyTier: null,
-      misconfigured: true,
-      warning: warnings.join(" ")
-    };
+    const lead = configuredUrl ? `${configuredUrl.key} selects the HTTP server for '${name}', but no API key could be resolved` : `${keys.apiUrlKeys[0]} is not set and no API key could be resolved for '${name}'; a credential is required before the default fleet gateway authority applies`;
+    warnings.push(`${lead}; refusing to create an unauthenticated client \u2014 public clients never fall back to SQLite or another local store. ` + `Looked in the Keychain (macOS only), then for a credential file at ${diskHint}, then for ${keys.apiKeyKeys[0]} in the environment.`);
+    throw new ClientTransportConfigurationError2(name, warnings.join(" "), [configuredUrl?.key ?? keys.apiUrlKeys[0]]);
   }
   if (credential.warning)
     warnings.push(credential.warning);
+  let urlHit;
+  if (configuredUrl) {
+    urlHit = configuredUrl;
+  } else {
+    try {
+      urlHit = { key: DEFAULT_AUTHORITY_SOURCE2, value: defaultFleetGatewayBaseUrl2(name) };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new ClientTransportConfigurationError2(name, `No ${keys.apiUrlKeys[0]} is configured and the default fleet gateway authority cannot be composed for '${name}': ${message}`, [keys.apiUrlKeys[0]]);
+    }
+  }
   const apiUrlSource = urlHit.key;
   let baseUrl;
   try {
     baseUrl = toV1BaseUrl2(urlHit.value);
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
-    warnings.push(`Invalid API URL from ${apiUrlSource}: ${message}. Using local store.`);
-    return {
-      transport: "sqlite",
+    throw new ClientTransportConfigurationError2(name, `Invalid API URL from ${apiUrlSource}: ${message}`, [apiUrlSource]);
+  }
+  return {
+    resolution: {
+      transport: "http",
       transportSource: urlHit.key,
-      baseUrl: null,
-      apiUrlSource: urlHit.key,
+      baseUrl,
+      apiUrlSource,
       apiKeyPresent: true,
       apiKeySource: credential.source,
       apiKeyTier: credential.tier,
-      misconfigured: true,
-      warning: warnings.join(" ")
-    };
-  }
-  return {
-    transport: "http",
-    transportSource: urlHit.key,
-    baseUrl,
-    apiUrlSource,
-    apiKeyPresent: true,
-    apiKeySource: credential.source,
-    apiKeyTier: credential.tier,
-    misconfigured: false,
-    warning: warnings.length > 0 ? warnings.join(" ") : null
+      misconfigured: false,
+      warning: warnings.length > 0 ? warnings.join(" ") : null
+    },
+    credential
   };
 }
 function credentialDiskSourcesForMessage2(name, env) {
   const paths = credentialDiskSources2(name, env);
-  return paths.length > 0 ? paths.join(" or ") : "<no HOME set in this environment, so no credential file was consulted>";
+  return paths.length > 0 ? paths.join(" or ") : "<no HOME or HASNA_HOME set in this environment, so no credential file was consulted>";
 }
 
-class HasnaHttpError2 extends Error {
+class HasnaHttpError extends Error {
   status;
   method;
   path;
-  body;
   credentialSource;
   credentialTier;
   constructor(method, path, status, body, credential) {
@@ -2484,31 +2699,46 @@ class HasnaHttpError2 extends Error {
     this.status = status;
     this.method = method;
     this.path = path;
-    this.body = body;
+    Object.defineProperty(this, "body", {
+      value: body,
+      enumerable: status !== 401 && status !== 403,
+      writable: false,
+      configurable: false
+    });
     this.credentialSource = credential?.source ?? null;
     this.credentialTier = credential?.tier ?? null;
   }
 }
-function currentCredential2(name, apiKey) {
+function currentCredential(name, apiKey) {
   if (typeof apiKey === "function") {
-    return validateAndSealResolvedCredential2(name, apiKey());
+    return validateAndSealResolvedCredential(name, apiKey());
+  }
+  return explicitCredential(name, apiKey);
+}
+async function resolveRequestCredential(name, apiKey, env = process.env) {
+  const resolved = currentCredential(name, apiKey);
+  if (resolved.tier === "pointer") {
+    return completePointerCredential(name, resolved, env);
   }
-  return explicitCredential2(name, apiKey);
+  return resolved;
 }
-function authFailureGuidance2(credential) {
+function authFailureGuidance(credential) {
   const origin = `The API key for this request came from ${credential.source}`;
   if (credential.deliberate) {
-    const remedy = credential.source === CALLER_SUPPLIED_CREDENTIAL_PROVIDER_SOURCE2 ? `Fix that provider so it returns the current key, or replace it with resolveCredential() ` + `so diagnostics can name the original source.` : `Rotate that key, or unset the override to use the credential on disk.`;
+    const remedy = credential.source === CALLER_SUPPLIED_CREDENTIAL_PROVIDER_SOURCE ? `Fix that provider so it returns the current key, or replace it with resolveCredential() ` + `so diagnostics can name the original source.` : `Rotate that key, or unset the override to use the credential on disk.`;
     return `${origin} \u2014 a credential you selected deliberately. It was NOT substituted with any other key: ` + `falling back here would authenticate as a different principal than the one you named, which is ` + `exactly the failure an override exists to prevent. ${remedy}`;
   }
-  if (credential.deprecated) {
+  if (credential.tier === "env") {
     const target = credential.diskCandidates[0];
-    const remedy = target ? `Write the CURRENT key to ${target} \u2014 that file is re-read on every call, so rotations take ` + `effect immediately and in every shell. Do not simply unset ${credential.source}: nothing was ` + `found on disk, so that would leave this client with no credential at all.` : `This environment has no HOME, so no credential file could be consulted; the disk tier is ` + `unavailable here and there is nothing to fall back to. Set HOME, or supply the key explicitly.`;
-    return `${origin}, a variable in this process's environment \u2014 which is a snapshot taken when the process ` + `started. A STALE SHELL is the most common cause of this error: this shell exported the key before ` + `it was rotated, and will keep sending the old one until it exits. ${remedy}`;
+    const remedy = target ? `Store the CURRENT key in the Keychain or write it to ${target} \u2014 both are re-read on every call, so ` + `rotations take effect immediately and in every shell. Do not simply unset ${credential.source}: ` + `nothing was found in the Keychain or on disk, so that would leave this client with no credential at all.` : `This environment has no HOME or HASNA_HOME, so no credential file could be consulted; the disk tier is ` + `unavailable here and there is nothing to fall back to. Set HOME, or supply the key explicitly.`;
+    return `${origin}, a variable in this process's environment. If a wrapper injected it for this one process, the ` + `wrapper re-reads its store on every invocation and the stored key itself is being rejected \u2014 rotate it. ` + `If this SHELL exported it, the export is a snapshot taken when the shell started: a STALE SHELL that ` + `exported the key before it was rotated keeps sending the old one until it exits. ${remedy}`;
+  }
+  if (credential.tier === "keychain") {
+    return `${origin}, which was re-read from the Keychain on this very call \u2014 so a stale shell is NOT the cause ` + `here. The stored item is genuinely being rejected: update it with the current key, or re-run the fleet ` + `key distribution so this machine gets the current key.`;
   }
   return `${origin}, which was re-read from disk on this very call \u2014 so a stale shell is NOT the cause here. ` + `The stored credential is genuinely being rejected: rotate it, or re-run the fleet key distribution ` + `so this machine gets the current key.`;
 }
-var DEFAULT_RETRY_STATUSES2 = [408, 425, 429, 500, 502, 503, 504];
+var DEFAULT_RETRY_STATUSES = [408, 425, 429, 500, 502, 503, 504];
 var IDEMPOTENT_METHODS2 = new Set(["GET", "HEAD", "PUT", "DELETE", "OPTIONS"]);
 var AUTHORITY_OVERRIDE_HEADERS2 = new Set([
   "host",
@@ -2517,7 +2747,7 @@ var AUTHORITY_OVERRIDE_HEADERS2 = new Set([
   "x-forwarded-host",
   "x-original-host"
 ]);
-function assertNoAuthorityOverrideHeaders2(headers, source) {
+function assertNoAuthorityOverrideHeaders(headers, source) {
   if (!headers)
     return;
   const forbidden = Object.keys(headers).find((name) => AUTHORITY_OVERRIDE_HEADERS2.has(name.trim().toLowerCase()));
@@ -2525,7 +2755,7 @@ function assertNoAuthorityOverrideHeaders2(headers, source) {
     throw new Error(`Authenticated ${source} headers must not set authority header '${forbidden}'.`);
   }
 }
-function appendQuery2(path, query) {
+function appendQuery(path, query) {
   if (!query)
     return path;
   const params = query instanceof URLSearchParams ? query : new URLSearchParams;
@@ -2546,12 +2776,12 @@ function appendQuery2(path, query) {
     return path;
   return `${path}${path.includes("?") ? "&" : "?"}${qs}`;
 }
-var defaultSleep2 = (ms) => new Promise((resolve3) => setTimeout(resolve3, ms));
-function createHasnaHttpTransport2(options) {
+var defaultSleep = (ms) => new Promise((resolve3) => setTimeout(resolve3, ms));
+function createHasnaHttpTransportInternal(options, requestBindingProvider) {
   const fetchImpl = options.fetchImpl ?? ((input, init) => fetch(input, init));
   const base = toV1BaseUrl2(options.baseUrl);
   const timeoutMs = options.timeoutMs ?? 30000;
-  const sleep = options.sleepImpl ?? defaultSleep2;
+  const sleep = options.sleepImpl ?? defaultSleep;
   const defaultRetry = options.retry;
   function resolveRetry(callRetry) {
     const chosen = callRetry !== undefined ? callRetry : defaultRetry;
@@ -2562,12 +2792,12 @@ function createHasnaHttpTransport2(options) {
       retries: r.retries ?? 2,
       baseDelayMs: r.baseDelayMs ?? 200,
       maxDelayMs: r.maxDelayMs ?? 2000,
-      retryStatuses: r.retryStatuses ?? [...DEFAULT_RETRY_STATUSES2]
+      retryStatuses: r.retryStatuses ?? [...DEFAULT_RETRY_STATUSES]
     };
   }
   async function once(method, rel, url, body, opts, credential) {
-    assertNoAuthorityOverrideHeaders2(options.headers, "transport");
-    assertNoAuthorityOverrideHeaders2(opts.headers, "request");
+    assertNoAuthorityOverrideHeaders(options.headers, "transport");
+    assertNoAuthorityOverrideHeaders(opts.headers, "request");
     const headers = {
       "x-api-key": credential.apiKey,
       Authorization: `Bearer ${credential.apiKey}`,
@@ -2609,13 +2839,20 @@ function createHasnaHttpTransport2(options) {
       if (opts.signal)
         opts.signal.removeEventListener("abort", onAbort);
     }
-    const text = await response.text();
+    const authenticationFailure = response.status === 401 || response.status === 403;
     let parsed = undefined;
-    if (text.length > 0) {
+    if (authenticationFailure) {
       try {
-        parsed = JSON.parse(text);
-      } catch {
-        parsed = text;
+        await response.body?.cancel();
+      } catch {}
+    } else {
+      const text = await response.text();
+      if (text.length > 0) {
+        try {
+          parsed = JSON.parse(text);
+        } catch {
+          parsed = text;
+        }
       }
     }
     if (!response.ok) {
@@ -2623,34 +2860,38 @@ function createHasnaHttpTransport2(options) {
         return {
           ok: false,
           retryable: false,
-          error: new HasnaHttpError2(method, rel, response.status, parsed)
+          error: new HasnaHttpError(method, rel, response.status, parsed)
         };
       }
-      if (response.status === 401 || response.status === 403) {
+      if (authenticationFailure) {
         return {
           ok: false,
           retryable: false,
-          error: new HasnaHttpError2(method, rel, response.status, parsed, {
+          error: new HasnaHttpError(method, rel, response.status, undefined, {
             source: credential.source,
             tier: credential.tier,
-            guidance: authFailureGuidance2(credential)
+            guidance: authFailureGuidance(credential)
           })
         };
       }
       const retry = resolveRetry(opts.retry);
       const retryable = retry ? retry.retryStatuses.includes(response.status) : false;
-      return { ok: false, retryable, error: new HasnaHttpError2(method, rel, response.status, parsed) };
+      return { ok: false, retryable, error: new HasnaHttpError(method, rel, response.status, parsed) };
     }
     return { ok: true, value: parsed };
   }
   async function request(method, path, body, opts = {}) {
     const upper = method.toUpperCase();
-    const rel = appendQuery2(path.startsWith("/") ? path : `/${path}`, opts.query);
-    const url = `${base}${rel}`;
+    const rel = appendQuery(path.startsWith("/") ? path : `/${path}`, opts.query);
     const retry = resolveRetry(opts.retry);
     const methodRetryable = IDEMPOTENT_METHODS2.has(upper) || Boolean(opts.idempotencyKey);
     const maxAttempts = retry && methodRetryable ? retry.retries + 1 : 1;
-    const credential = currentCredential2(options.name, options.apiKey);
+    const binding = requestBindingProvider ? await requestBindingProvider() : {
+      baseUrl: base,
+      credential: await resolveRequestCredential(options.name, options.apiKey)
+    };
+    const url = `${binding.baseUrl}${rel}`;
+    const credential = binding.credential;
     let last = null;
     for (let attempt = 1;attempt <= maxAttempts; attempt++) {
       const result = await once(upper, rel, url, body, opts, credential);
@@ -2676,34 +2917,43 @@ function createHasnaHttpTransport2(options) {
     del: (path, body, opts) => request("DELETE", path, body, opts)
   };
 }
-function createClientTransport2(name, env = process.env, overrides) {
+function createClientTransport(name, env = process.env, overrides) {
   const credentialOptions = overrides?.credentials;
-  const resolution = resolveClientTransport2(name, env, { ...credentialOptions ? { credentials: credentialOptions } : {} });
-  if (resolution.misconfigured) {
-    throw new Error(resolution.warning ?? `Client for '${name}' is misconfigured for the API client.`);
-  }
-  if (resolution.transport === "sqlite" || !resolution.baseUrl) {
-    return { transport: "sqlite", client: null, resolution };
-  }
-  const credentialProvider = () => {
-    const resolved = resolveCredential2(name, env, credentialOptions);
-    if (!resolved) {
-      throw new Error(`Client for '${name}' resolved to the http transport but no API key is available any more. ` + `Looked at ${credentialDiskSourcesForMessage2(name, env)}, then the environment. ` + `A credential file that was removed after this client was built is the usual cause.`);
-    }
-    return resolved;
+  const snapshotOptions = { ...credentialOptions ? { credentials: credentialOptions } : {} };
+  const resolution = resolveClientTransportSnapshot2(name, env, snapshotOptions).resolution;
+  const sameBinding = (left, right) => left.resolution.baseUrl === right.resolution.baseUrl && left.credential.apiKey === right.credential.apiKey && left.credential.pointerVaultKey === right.credential.pointerVaultKey && left.credential.source === right.credential.source && left.credential.tier === right.credential.tier;
+  const unstableConfiguration = () => new ClientTransportConfigurationError2(name, "The configured service authority or credential changed while a request was being prepared; no authenticated request was sent.");
+  const requestBindingProvider = async () => {
+    const first = resolveClientTransportSnapshot2(name, env, snapshotOptions);
+    const reviewed = resolveClientTransportSnapshot2(name, env, snapshotOptions);
+    if (!sameBinding(first, reviewed))
+      throw unstableConfiguration();
+    if (reviewed.resolution.baseUrl !== resolution.baseUrl) {
+      throw new ClientTransportConfigurationError2(name, "The configured service authority changed; rebuild the client before sending credentials.");
+    }
+    const credential = await resolveRequestCredential(name, () => reviewed.credential, env);
+    const immediatelyBeforeDispatch = resolveClientTransportSnapshot2(name, env, snapshotOptions);
+    if (!sameBinding(reviewed, immediatelyBeforeDispatch))
+      throw unstableConfiguration();
+    if (immediatelyBeforeDispatch.resolution.baseUrl !== resolution.baseUrl) {
+      throw new ClientTransportConfigurationError2(name, "The configured service authority changed; rebuild the client before sending credentials.");
+    }
+    return { baseUrl: immediatelyBeforeDispatch.resolution.baseUrl, credential };
   };
   return {
     transport: "http",
-    client: createHasnaHttpTransport2({
+    client: createHasnaHttpTransportInternal({
       name,
       baseUrl: resolution.baseUrl,
-      apiKey: credentialProvider,
+      apiKey: () => {
+        throw new Error("The authenticated request binding provider was not invoked.");
+      },
       ...overrides?.fetchImpl ? { fetchImpl: overrides.fetchImpl } : {},
       ...overrides?.headers ? { headers: overrides.headers } : {},
       ...overrides?.timeoutMs ? { timeoutMs: overrides.timeoutMs } : {},
       ...overrides?.retry !== undefined ? { retry: overrides.retry } : {},
       ...overrides?.sleepImpl ? { sleepImpl: overrides.sleepImpl } : {}
-    }),
+    }, requestBindingProvider),
     resolution
   };
 }
@@ -2807,41 +3057,68 @@ function createHasnaStorageClient(name, transport) {
   };
 }
 function resolveStorageClient(name, env = process.env, overrides) {
-  const wired = createClientTransport2(name, env, overrides);
-  if (wired.transport === "http") {
-    return { transport: "http", client: createHasnaStorageClient(name, wired.client) };
-  }
-  return { transport: "sqlite", client: null };
+  const wired = createClientTransport(name, env, overrides);
+  return { transport: "http", client: createHasnaStorageClient(name, wired.client) };
 }
 
-// src/http/client.ts
-function envToken3(name) {
-  return name.toUpperCase().replace(/-/g, "_");
-}
-function envKeys(name) {
-  const token = envToken3(name);
-  return {
-    storeKeys: [`HASNA_${token}_CLIENT_STORE`, `${token}_CLIENT_STORE`],
-    apiUrlKeys: [`HASNA_${token}_API_URL`],
-    apiKeyKeys: [`HASNA_${token}_API_KEY`]
-  };
+// src/lib/local-opt-in.ts
+var RECORDINGS_LOCAL_OPT_IN_ENV_KEYS = [
+  "HASNA_RECORDINGS_LOCAL",
+  "RECORDINGS_LOCAL"
+];
+function isRecordingsLocalOptIn(env = process.env) {
+  return RECORDINGS_LOCAL_OPT_IN_ENV_KEYS.some((key) => (env[key] ?? "").trim() !== "");
 }
-function normalizeClientStore(value) {
-  const normalized = value.trim().toLowerCase();
-  if (normalized === "sqlite")
-    return "sqlite";
-  if (normalized === "http" || normalized === "https")
-    return "http";
-  throw new Error(`Unknown client store: ${value}. Use sqlite or http.`);
+var RECORDINGS_CARVED_LEGACY_ENV_KEYS = [
+  "RECORDINGS_API_URL",
+  "RECORDINGS_API_KEY"
+];
+function recordingsAuthorityEnvKeys() {
+  const keys = clientTransportEnvKeys("recordings");
+  return [
+    ...keys.apiUrlKeys,
+    ...keys.apiKeyKeys,
+    credentialOverrideEnvKey("recordings"),
+    credentialPointerEnvKey("recordings"),
+    CREDENTIAL_PROFILE_ENV_KEY
+  ].filter((key) => !RECORDINGS_CARVED_LEGACY_ENV_KEYS.includes(key));
+}
+function hasRecordingsEnvAuthorityIntent(env = process.env) {
+  return recordingsAuthorityEnvKeys().some((key) => (env[key] ?? "").trim() !== "");
+}
+function selectsRecordingsLocalStore(env = process.env) {
+  return !hasRecordingsEnvAuthorityIntent(env) && isRecordingsLocalOptIn(env);
+}
+function recordingsResolverEnv(env) {
+  const carved = RECORDINGS_CARVED_LEGACY_ENV_KEYS.filter((key) => (key in env));
+  const blanks = recordingsAuthorityEnvKeys().filter((key) => (key in env) && (env[key] ?? "").trim() === "");
+  const removed = new Set([...carved, ...blanks]);
+  if (removed.size === 0)
+    return env;
+  const next = { ...env };
+  for (const key of removed)
+    delete next[key];
+  return next;
+}
+var CONTRACTS_AMBIENT_ENVIRONMENT = Symbol.for("hasna:contracts:ambientClientEnvironment");
+function isAmbientRecordingsEnv(env) {
+  if (typeof process !== "undefined" && env === process.env) {
+    return true;
+  }
+  return env[CONTRACTS_AMBIENT_ENVIRONMENT] === true;
 }
-function firstEnv3(env, keys) {
-  for (const key of keys) {
-    const value = env[key]?.trim();
-    if (value)
-      return { key, value };
+function recordingsResolverInputs(env, credentials = {}) {
+  const normalised = recordingsResolverEnv(env);
+  if (normalised === env)
+    return { env: normalised, credentials };
+  const keychain = { ...credentials.keychain };
+  if (keychain.enabled === undefined && keychain.run === undefined) {
+    keychain.enabled = isAmbientRecordingsEnv(env);
   }
-  return null;
+  return { env: normalised, credentials: { ...credentials, keychain } };
 }
+
+// src/http/client.ts
 function toV1BaseUrl3(apiUrl) {
   const url = new URL(apiUrl);
   if (url.protocol !== "http:" && url.protocol !== "https:") {
@@ -2855,69 +3132,8 @@ function toV1BaseUrl3(apiUrl) {
   url.hash = "";
   return url.toString().replace(/\/+$/, "");
 }
-function resolveTransport(name, env = process.env) {
-  const keys = envKeys(name);
-  const storeHit = firstEnv3(env, keys.storeKeys);
-  const urlHit = firstEnv3(env, keys.apiUrlKeys);
-  const keyHit = firstEnv3(env, keys.apiKeyKeys);
-  let requested = "sqlite";
-  let modeSource = "default";
-  if (storeHit) {
-    requested = normalizeClientStore(storeHit.value);
-    modeSource = storeHit.key;
-  } else if (urlHit && keyHit) {
-    requested = "http";
-    modeSource = "auto:api-url+api-key";
-  } else if (urlHit || keyHit) {
-    const missing = urlHit ? keys.apiKeyKeys[0] : keys.apiUrlKeys[0];
-    const present = urlHit ? keys.apiUrlKeys[0] : keys.apiKeyKeys[0];
-    return {
-      transport: "sqlite",
-      requested,
-      modeSource,
-      baseUrl: null,
-      apiKeyPresent: Boolean(keyHit),
-      misconfigured: true,
-      warning: `${present} is set but ${missing} is not: the hosted API is only ` + `selected when BOTH are present. Set ${missing}, or unset ${present} to ` + `use the on-box store.`
-    };
-  }
-  if (requested === "sqlite") {
-    return { transport: "sqlite", requested, modeSource, baseUrl: null, apiKeyPresent: Boolean(keyHit), misconfigured: false, warning: null };
-  }
-  if (!urlHit) {
-    return {
-      transport: "sqlite",
-      requested,
-      modeSource,
-      baseUrl: null,
-      apiKeyPresent: Boolean(keyHit),
-      misconfigured: true,
-      warning: `${modeSource}=http but no API URL is set (${keys.apiUrlKeys[0]}). Refusing to route to the API.`
-    };
-  }
-  if (!keyHit) {
-    return {
-      transport: "sqlite",
-      requested,
-      modeSource,
-      baseUrl: null,
-      apiKeyPresent: false,
-      misconfigured: true,
-      warning: `${modeSource}=http but no API key is set (${keys.apiKeyKeys[0]}). Refusing to route to the API.`
-    };
-  }
-  const rawUrl = urlHit.value;
-  let baseUrl;
-  try {
-    baseUrl = toV1BaseUrl3(rawUrl);
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    return { transport: "sqlite", requested, modeSource, baseUrl: null, apiKeyPresent: true, misconfigured: true, warning: `Invalid API URL: ${message}.` };
-  }
-  return { transport: "http", requested, modeSource, baseUrl, apiKeyPresent: true, misconfigured: false, warning: null };
-}
 
-class HasnaHttpError3 extends Error {
+class HasnaHttpError2 extends Error {
   status;
   method;
   path;
@@ -2931,7 +3147,7 @@ class HasnaHttpError3 extends Error {
     this.body = body;
   }
 }
-function appendQuery3(path, query) {
+function appendQuery2(path, query) {
   if (!query)
     return path;
   const params = new URLSearchParams;
@@ -2949,12 +3165,12 @@ function appendQuery3(path, query) {
 }
 var RETRY_STATUSES = new Set([408, 425, 429, 500, 502, 503, 504]);
 var IDEMPOTENT = new Set(["GET", "HEAD", "PUT", "DELETE", "OPTIONS"]);
-var defaultSleep3 = (ms) => new Promise((r) => setTimeout(r, ms));
+var defaultSleep2 = (ms) => new Promise((r) => setTimeout(r, ms));
 function createHttpTransport(options) {
   const fetchImpl = options.fetchImpl ?? ((input, init) => fetch(input, init));
   const base = options.baseUrl.replace(/\/+$/, "");
   const timeoutMs = options.timeoutMs ?? 30000;
-  const sleep = options.sleepImpl ?? defaultSleep3;
+  const sleep = options.sleepImpl ?? defaultSleep2;
   async function once(method, rel, url, body, opts) {
     const headers = {
       "x-api-key": options.apiKey,
@@ -3002,13 +3218,13 @@ function createHttpTransport(options) {
       }
     }
     if (!response.ok) {
-      return { ok: false, retryable: RETRY_STATUSES.has(response.status), error: new HasnaHttpError3(method, rel, response.status, parsed) };
+      return { ok: false, retryable: RETRY_STATUSES.has(response.status), error: new HasnaHttpError2(method, rel, response.status, parsed) };
     }
     return { ok: true, value: parsed };
   }
   async function request(method, path, body, opts = {}) {
     const upper = method.toUpperCase();
-    const rel = appendQuery3(path.startsWith("/") ? path : `/${path}`, opts.query);
+    const rel = appendQuery2(path.startsWith("/") ? path : `/${path}`, opts.query);
     const url = `${base}${rel}`;
     const methodRetryable = IDEMPOTENT.has(upper) || Boolean(opts.idempotencyKey);
     const maxRetries = opts.retries ?? 2;
@@ -3073,7 +3289,7 @@ function createStorageClient(name, transport) {
       try {
         return await transport.get(ep(resource, id));
       } catch (error) {
-        if (error instanceof HasnaHttpError3 && error.status === 404)
+        if (error instanceof HasnaHttpError2 && error.status === 404)
           return null;
         throw error;
       }
@@ -3089,46 +3305,278 @@ function createStorageClient(name, transport) {
       try {
         await transport.del(ep(resource, id));
       } catch (error) {
-        if (error instanceof HasnaHttpError3 && error.status === 404)
+        if (error instanceof HasnaHttpError2 && error.status === 404)
           return;
         throw error;
       }
     }
   };
 }
-function resolveStoreClient(name, env = process.env) {
-  const resolution = resolveTransport(name, env);
-  if (resolution.misconfigured) {
-    const wired2 = createClientTransport(name, env);
-    if (wired2.transport === "http") {
-      return {
-        transport: "http",
-        client: createHasnaStorageClient(name, wired2.client),
-        resolution: {
-          transport: "http",
-          requested: "http",
-          modeSource: resolution.modeSource === "default" ? "auto:api-url+seam-credential" : resolution.modeSource,
-          baseUrl: wired2.resolution.baseUrl,
-          apiKeyPresent: true,
-          misconfigured: false,
-          warning: null
-        }
-      };
+function throwRecordingsAuthorityFailure(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  const name = error instanceof Error ? error.name : "";
+  if (name === "CredentialResolutionError" || name === "CredentialFileUnsafeError") {
+    throw new Error(`REMOTE_API_CREDENTIAL_INVALID: ${message} There is no local fallback: ` + "local SQLite is opt-in only (HASNA_RECORDINGS_LOCAL=1) and is disabled by default \u2014 failing closed", { cause: error });
+  }
+  if (/no API key could be resolved/.test(message)) {
+    if (/is not set and no API key could be resolved/.test(message)) {
+      throw new Error("REMOTE_API_CONFIG_MISSING: no Recordings credential resolved from the Keychain item " + `hasna.credentials.recordings.api-key, ~/.hasna/recordings/config/credentials, or HASNA_RECORDINGS_API_KEY. ${message} ` + "There is no local fallback: local SQLite is opt-in only (HASNA_RECORDINGS_LOCAL=1, alias RECORDINGS_LOCAL=1) " + "and is disabled by default \u2014 failing closed instead of serving the local store", { cause: error });
+    }
+    throw new Error("REMOTE_API_KEY_MISSING: remote Recordings storage requires HASNA_RECORDINGS_API_KEY, the Keychain item " + `hasna.credentials.recordings.api-key, or ~/.hasna/recordings/config/credentials. ${message} ` + "There is no local fallback: local SQLite is opt-in only (HASNA_RECORDINGS_LOCAL=1) and is disabled by default \u2014 failing closed", { cause: error });
+  }
+  throw new Error(`REMOTE_API_URL_INVALID: ${message} local SQLite fallback is disabled`, { cause: error });
+}
+function toRecordsAuthority(resolution) {
+  return {
+    transport: resolution.transport,
+    transportSource: resolution.transportSource,
+    baseUrl: resolution.baseUrl,
+    apiUrlSource: resolution.apiUrlSource,
+    apiKeyPresent: resolution.apiKeyPresent,
+    apiKeySource: resolution.apiKeySource,
+    apiKeyTier: resolution.apiKeyTier,
+    misconfigured: resolution.misconfigured,
+    warning: resolution.warning
+  };
+}
+function resolveRecordingsTransport(env = process.env, options = {}) {
+  if (selectsRecordingsLocalStore(env)) {
+    return { transport: "sqlite", selected: false, source: "local-opt-in", authority: null };
+  }
+  const resolverInputs = recordingsResolverInputs(env, options.credentials);
+  let resolution;
+  try {
+    resolution = resolveClientTransport("recordings", resolverInputs.env, {
+      credentials: resolverInputs.credentials
+    });
+  } catch (error) {
+    throwRecordingsAuthorityFailure(error);
+  }
+  return {
+    transport: "http",
+    selected: true,
+    source: `${resolution.apiKeySource ?? resolution.apiKeyTier}+${resolution.apiUrlSource ?? "default"}`,
+    authority: toRecordsAuthority(resolution)
+  };
+}
+function getRecordingsTransportStatus(env = process.env, options = {}) {
+  let resolution;
+  try {
+    resolution = resolveRecordingsTransport(env, options);
+  } catch (error) {
+    const issue = error instanceof Error ? error.message : String(error);
+    const envKeys = clientTransportEnvKeys("recordings");
+    const declared = (keys) => keys.some((key) => (env[key] ?? "").trim() !== "");
+    return {
+      selected: true,
+      ok: false,
+      transport: "invalid",
+      api_url_configured: declared(envKeys.apiUrlKeys),
+      api_key_configured: declared(envKeys.apiKeyKeys),
+      api_url_source: null,
+      api_key_source: null,
+      api_key_tier: null,
+      v1_base_url: null,
+      issues: [issue],
+      local_fallback: false
+    };
+  }
+  if (!resolution.selected) {
+    return {
+      selected: false,
+      ok: true,
+      transport: resolution.transport,
+      api_url_configured: false,
+      api_key_configured: false,
+      api_url_source: null,
+      api_key_source: null,
+      api_key_tier: null,
+      v1_base_url: null,
+      issues: [],
+      local_fallback: false
+    };
+  }
+  const authority = resolution.authority;
+  return {
+    selected: true,
+    ok: true,
+    transport: resolution.transport,
+    api_url_configured: authority.apiUrlSource !== null && authority.apiUrlSource !== "default",
+    api_key_configured: authority.apiKeyPresent,
+    api_url_source: authority.apiUrlSource,
+    api_key_source: authority.apiKeySource,
+    api_key_tier: authority.apiKeyTier,
+    v1_base_url: authority.baseUrl,
+    issues: [],
+    local_fallback: false
+  };
+}
+function resolveRecordingsCloudClient(env = process.env, options = {}) {
+  if (selectsRecordingsLocalStore(env))
+    return null;
+  const resolverInputs = recordingsResolverInputs(env, options.credentials);
+  let resolved;
+  try {
+    resolved = resolveStorageClient("recordings", resolverInputs.env, {
+      fetchImpl: (input, init) => globalThis.fetch(input, { ...init, redirect: "manual" }),
+      credentials: resolverInputs.credentials
+    });
+  } catch (error) {
+    throwRecordingsAuthorityFailure(error);
+  }
+  const client = resolved.client;
+  return client;
+}
+
+// src/store.ts
+import { createHash as createHash2, randomUUID as randomUUID2 } from "crypto";
+
+// src/lib/audio-artifact-storage.ts
+import { GetObjectCommand, PutObjectCommand, S3Client as AwsS3Client } from "@aws-sdk/client-s3";
+import { createHash } from "crypto";
+import { readFile } from "fs/promises";
+import { extname } from "path";
+var SHA256_HEX = /^[0-9a-f]{64}$/;
+var DEFAULT_S3_PREFIX = "recordings";
+var AUDIO_CONTENT_TYPES = {
+  wav: "audio/wav",
+  mp3: "audio/mpeg",
+  m4a: "audio/mp4",
+  aac: "audio/aac",
+  webm: "audio/webm",
+  ogg: "audio/ogg",
+  flac: "audio/flac"
+};
+function contentTypeForExtension(extension) {
+  return AUDIO_CONTENT_TYPES[extension.toLowerCase()] ?? "application/octet-stream";
+}
+
+class AudioArtifactStorage {
+  bucket;
+  prefix;
+  s3;
+  constructor(options = {}) {
+    this.bucket = options.bucket;
+    this.prefix = (options.prefix || DEFAULT_S3_PREFIX).replace(/^\/+|\/+$/g, "");
+    this.s3 = this.bucket ? options.client ?? new AwsS3Client({ region: options.region || process.env.AWS_REGION || "us-east-1" }) : undefined;
+  }
+  get usesS3() {
+    return Boolean(this.bucket);
+  }
+  objectKeyFor(recordingId, sha256, extension) {
+    assertSha256(sha256);
+    const safeExtension = extension.toLowerCase().match(/^[a-z0-9]+/)?.[0] || "bin";
+    return `${this.prefix}/${recordingId}/${sha256}.${safeExtension}`;
+  }
+  async uploadAudio(recordingId, audioPath) {
+    if (!this.bucket || !this.s3)
+      return null;
+    const bytes = await readFileBytes(audioPath);
+    if (!bytes)
+      return null;
+    const sha256 = sha256Hex(bytes);
+    const extension = extensionOf(audioPath);
+    const key = this.objectKeyFor(recordingId, sha256, extension);
+    await this.s3.send(new PutObjectCommand({
+      Bucket: this.bucket,
+      Key: key,
+      Body: bytes,
+      ContentType: contentTypeForExtension(extension)
+    }));
+    return { objectKey: key, sha256, bytes: bytes.byteLength };
+  }
+  async readAudio(objectKey) {
+    if (!this.bucket || !this.s3)
+      return null;
+    try {
+      const response = await this.s3.send(new GetObjectCommand({ Bucket: this.bucket, Key: objectKey }));
+      return await bodyToBytes(response.Body);
+    } catch {
+      return null;
+    }
+  }
+}
+function resolveAudioArtifactStorage(env = process.env, client) {
+  const bucket = env.HASNA_RECORDINGS_S3_BUCKET || env.RECORDINGS_S3_BUCKET || undefined;
+  const prefix = env.HASNA_RECORDINGS_S3_PREFIX || env.RECORDINGS_S3_PREFIX || undefined;
+  const region = env.RECORDINGS_S3_REGION || env.AWS_REGION || undefined;
+  return new AudioArtifactStorage({ bucket, prefix, region, client });
+}
+async function uploadAudioAtCreation(recordingId, audioPath, storage = resolveAudioArtifactStorage()) {
+  if (!audioPath)
+    return null;
+  if (!storage.usesS3)
+    return null;
+  try {
+    const uploaded = await storage.uploadAudio(recordingId, audioPath);
+    if (!uploaded)
+      return null;
+    console.warn(`recordings: uploaded audio for ${recordingId} to ${uploaded.objectKey}`);
+    return uploaded;
+  } catch (error) {
+    console.warn(`recordings: audio upload failed for ${recordingId} (${String(error instanceof Error ? error.message : error)}); keeping local audio_path only`);
+    return null;
+  }
+}
+function assertSha256(value) {
+  if (!SHA256_HEX.test(value)) {
+    throw new Error("audio digest must be a lowercase hex sha-256; refusing to build a storage key from it");
+  }
+}
+function sha256Hex(bytes) {
+  const hash = createHash("sha256");
+  hash.update(bytes);
+  return hash.digest("hex");
+}
+async function readFileBytes(path) {
+  try {
+    return new Uint8Array(await readFile(path));
+  } catch {
+    return null;
+  }
+}
+function extensionOf(path) {
+  const extension = extname(path).replace(/^\./, "").toLowerCase();
+  return extension || "bin";
+}
+async function bodyToBytes(body) {
+  if (!body)
+    return new Uint8Array(0);
+  if (body instanceof Uint8Array)
+    return body;
+  if (typeof body.transformToByteArray === "function") {
+    return new Uint8Array(await body.transformToByteArray());
+  }
+  if (typeof body.getReader === "function") {
+    const reader = body.getReader();
+    const chunks2 = [];
+    for (;; ) {
+      const { value, done } = await reader.read();
+      if (done)
+        break;
+      if (value)
+        chunks2.push(value);
     }
-    throw new Error(resolution.warning ?? `Client for '${name}' is misconfigured for the /v1 API.`);
+    return concat(chunks2);
   }
-  if (resolution.transport === "sqlite" || !resolution.baseUrl) {
-    return { transport: "sqlite", client: null, resolution };
+  const chunks = [];
+  for await (const chunk of body) {
+    chunks.push(typeof chunk === "string" ? new TextEncoder().encode(chunk) : chunk);
   }
-  const wired = createClientTransport(name, env);
-  if (wired.transport !== "http") {
-    throw new Error(`Client for '${name}' resolved to the /v1 API without an API key.`);
+  return concat(chunks);
+}
+function concat(chunks) {
+  const total = chunks.reduce((sum, chunk) => sum + chunk.byteLength, 0);
+  const merged = new Uint8Array(new ArrayBuffer(total));
+  let offset = 0;
+  for (const chunk of chunks) {
+    merged.set(chunk, offset);
+    offset += chunk.byteLength;
   }
-  return { transport: "http", client: createHasnaStorageClient(name, wired.client), resolution };
+  return merged;
 }
 
 // src/store.ts
-import { createHash, randomUUID as randomUUID2 } from "crypto";
 var APP = "recordings";
 function listQuery(filter) {
   if (!filter)
@@ -3159,7 +3607,15 @@ var localStore = {
   mode: "sqlite",
   baseUrl: null,
   async createRecording(input, idempotencyKey) {
-    return withLocalStoreReaderLease(() => createRecording(input, undefined, idempotencyKey));
+    return withLocalStoreReaderLease(async () => {
+      const recording = createRecording(input, undefined, idempotencyKey);
+      if (!recording.audio_path)
+        return recording;
+      const uploaded = await uploadAudioAtCreation(recording.id, recording.audio_path, localArtifactStorageFor());
+      if (!uploaded)
+        return recording;
+      return updateRecordingAudio(recording.id, uploaded.objectKey, uploaded.sha256, uploaded.bytes) ?? recording;
+    });
   },
   async getRecording(id) {
     return withLocalStoreReaderLease(() => getRecording(id));
@@ -3353,7 +3809,7 @@ function apiStore(client) {
   };
 }
 function recordingPageFingerprint(items) {
-  const hash = createHash("sha256");
+  const hash = createHash2("sha256");
   const ids = items.map((item) => String(item.id ?? "")).sort();
   for (const id of ids) {
     hash.update(String(id.length));
@@ -3364,12 +3820,16 @@ function recordingPageFingerprint(items) {
   return `${items.length}:${hash.digest("hex")}`;
 }
 var cached = null;
-function getStore(env = process.env) {
-  if (env === process.env && cached)
+var localArtifactStorageOverride;
+function localArtifactStorageFor() {
+  return localArtifactStorageOverride ?? resolveAudioArtifactStorage();
+}
+function getStore(env = process.env, options = {}) {
+  if (env === process.env && cached && options.credentials === undefined)
     return cached;
-  const resolved = resolveStoreClient(APP, env);
-  const store = resolved.transport === "http" ? apiStore(resolved.client) : localStore;
-  if (env === process.env)
+  const client = resolveRecordingsCloudClient(env, options);
+  const store = client ? apiStore(client) : localStore;
+  if (env === process.env && options.credentials === undefined)
     cached = store;
   return store;
 }
@@ -3406,12 +3866,15 @@ class EnhancementError extends Error {
 }
 export {
   toV1BaseUrl3 as toV1BaseUrl,
-  resolveTransport,
-  resolveStorageClient,
+  resolveRecordingsTransport,
+  resolveRecordingsCloudClient,
+  isRecordingsLocalOptIn,
   getStore,
+  getRecordingsTransportStatus,
   createStorageClient,
   createHttpTransport,
   __resetStore,
-  HasnaHttpError3 as HasnaHttpError,
+  RECORDINGS_LOCAL_OPT_IN_ENV_KEYS,
+  HasnaHttpError2 as HasnaHttpError,
   APP
 };