@hasna/recordings 0.3.8 → 0.3.9

package/dist/cli/index.js

@@ -903,7 +903,7 @@ import chalk from "chalk";
 import { spawnSync as spawnSync7 } from "child_process";
 import {
   existsSync as existsSync8,
-  readFileSync as readFileSync4,
+  readFileSync as readFileSync5,
   readdirSync as readdirSync2
 } from "fs";
 import { dirname as dirname5, join as pathJoin } from "path";
@@ -1928,7 +1928,7 @@ function setAgentFocus(idOrName, projectId, db) {
 // package.json
 var package_default = {
   name: "@hasna/recordings",
-  version: "0.3.8",
+  version: "0.3.9",
   type: "module",
   description: "Speech-to-text recording tool with MCP and CLI \u2014 records, transcribes, and optionally enhances text using AI",
   repository: {
@@ -2012,7 +2012,7 @@ var package_default = {
     "LICENSE"
   ],
   dependencies: {
-    "@hasna/contracts": "0.13.3",
+    "@hasna/contracts": "0.13.4",
     "@hasna/events": "0.1.11",
     "@modelcontextprotocol/sdk": "^1.12.1",
     chalk: "^5.4.1",
@@ -2044,27 +2044,207 @@ function saveFeedback(input) {
   db.query("INSERT INTO feedback (message, email, category, version) VALUES (?, ?, ?, ?)").run(input.message, input.email ?? null, input.category ?? "general", input.version ?? VERSION);
 }
 
-// src/http/client.ts
+// ../contracts/dist/client/transport.js
+import { isIP } from "net";
+import { readFileSync as readFileSync2, statSync as statSync2 } from "fs";
+import { join as join4 } from "path";
 function envToken(name) {
   return name.toUpperCase().replace(/-/g, "_");
 }
-function envKeys(name) {
-  const token = envToken(name);
+function clientTransportEnvKeys(name) {
+  const envSegment = envToken(name);
   return {
-    storeKeys: [`HASNA_${token}_CLIENT_STORE`, `${token}_CLIENT_STORE`],
-    apiUrlKeys: [`HASNA_${token}_API_URL`],
-    apiKeyKeys: [`HASNA_${token}_API_KEY`]
+    apiUrlKeys: [`HASNA_${envSegment}_API_URL`, `${envSegment}_API_URL`],
+    apiKeyKeys: [`HASNA_${envSegment}_API_KEY`, `${envSegment}_API_KEY`]
   };
 }
-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.`);
+function credentialOverrideEnvKey(name) {
+  return `HASNA_${envToken(name)}_API_KEY_OVERRIDE`;
+}
+var CREDENTIAL_PROFILE_ENV_KEY = "HASNA_PROFILE";
+
+class CredentialResolutionError extends Error {
+  appName;
+  attempted;
+  constructor(appName, message, attempted) {
+    super(message);
+    this.name = "CredentialResolutionError";
+    this.appName = appName;
+    this.attempted = attempted;
+  }
+}
+var HASNA_STATE_DIR = ".hasna";
+var FLEET_CREDENTIAL_DIR = "cloud";
+var CONFIG_DIR = ".config";
+var CONFIG_NAMESPACE = "hasna";
+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]/;
+function homeDir(env) {
+  const home = env.HOME?.trim();
+  return home ? home : null;
+}
+function credentialDiskSources(name, env) {
+  return profileDiskSources(name, env, null);
+}
+function profileDiskSources(name, env, profile) {
+  const home = homeDir(env);
+  if (!home || !SAFE_APP_SLUG.test(name))
+    return [];
+  const stem = profile ? `${name}.${profile}` : name;
+  const configStem = profile ? `${name}-${profile}` : name;
+  return [
+    join4(home, HASNA_STATE_DIR, FLEET_CREDENTIAL_DIR, `${stem}.env`),
+    join4(home, CONFIG_DIR, CONFIG_NAMESPACE, `${configStem}-cloud.env`)
+  ];
+}
+function parseEnvFile(text) {
+  const values = new Map;
+  for (const rawLine of text.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (line.length === 0 || line.startsWith("#"))
+      continue;
+    const withoutExport = line.startsWith("export ") ? line.slice("export ".length).trim() : line;
+    const equals = withoutExport.indexOf("=");
+    if (equals <= 0)
+      continue;
+    const key = withoutExport.slice(0, equals).trim();
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key))
+      continue;
+    let value = withoutExport.slice(equals + 1).trim();
+    const quote = value[0];
+    if (quote === '"' || quote === "'") {
+      if (value.length < 2 || !value.endsWith(quote))
+        continue;
+      value = value.slice(1, -1);
+    }
+    if (value.length === 0)
+      continue;
+    values.set(key, value);
+  }
+  return values;
+}
+function readAppConfigFile(path) {
+  let text;
+  try {
+    const stats = statSync2(path);
+    if (!stats.isFile() || stats.size > MAX_CREDENTIAL_FILE_BYTES)
+      return null;
+    text = readFileSync2(path, "utf8");
+  } catch {
+    return null;
+  }
+  return parseEnvFile(text);
 }
-function firstEnv(env, keys) {
+function readCredentialFile(path, apiKeyKeys) {
+  const values = readAppConfigFile(path);
+  if (!values)
+    return null;
+  for (const key of apiKeyKeys) {
+    const value = values.get(key)?.trim();
+    if (value)
+      return value;
+  }
+  return null;
+}
+var CREDENTIAL_SHAPED_KEY = /(?:^|_)(?:API_KEY|KEY|TOKEN|SECRET|PASSWORD|PASSWD|CREDENTIAL|AUTH)(?:_|$)/;
+function appConfigDiskValue(name, env, keys) {
+  const wanted = keys.filter((key) => !CREDENTIAL_SHAPED_KEY.test(key));
+  if (wanted.length === 0)
+    return null;
+  for (const path of credentialDiskSources(name, env)) {
+    const values = readAppConfigFile(path);
+    if (!values)
+      continue;
+    for (const key of wanted) {
+      const value = values.get(key)?.trim();
+      if (value)
+        return { key, value, path };
+    }
+  }
+  return null;
+}
+function assertUsableCredential(appName, source, value) {
+  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
+  };
+  const sealed = { ...visible };
+  Object.defineProperty(sealed, "apiKey", {
+    value: apiKey,
+    enumerable: false,
+    writable: false,
+    configurable: false
+  });
+  Object.defineProperty(sealed, INSPECT_CUSTOM, {
+    value: () => ({ ...visible, apiKey: "[redacted]" }),
+    enumerable: false,
+    writable: false,
+    configurable: false
+  });
+  Object.defineProperty(sealed, CREDENTIAL_SEAL, {
+    value: true,
+    enumerable: false,
+    writable: false,
+    configurable: false
+  });
+  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) {
     const value = env[key]?.trim();
     if (value)
@@ -2072,79 +2252,343 @@ function firstEnv(env, keys) {
   }
   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;
+}
+function defaultDeprecationSink(message) {
+  if (typeof process !== "undefined" && process.stderr) {
+    process.stderr.write(`${message}
+`);
+  }
+}
+function resolveCredential(name, env, options = {}) {
+  const { apiKeyKeys } = clientTransportEnvKeys(name);
+  const diskPaths = credentialDiskSources(name, env);
+  const explicitKey = options.apiKey?.trim();
+  if (explicitKey) {
+    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];
+  if (overrideRaw !== undefined) {
+    const override = overrideRaw.trim();
+    if (!override) {
+      throw new CredentialResolutionError(name, `${overrideKeyName} is set but empty. It is a deliberate override, so it is not resolved around: ` + `either give it a real key or unset it to fall back to the credential on disk.`, [overrideKeyName]);
+    }
+    assertUsableCredential(name, overrideKeyName, override);
+    return sealCredential({
+      apiKey: override,
+      tier: "override",
+      source: overrideKeyName,
+      deliberate: true,
+      deprecated: false,
+      diskCandidates: diskPaths,
+      warning: null
+    });
+  }
+  const profile = options.profile?.trim() || env[CREDENTIAL_PROFILE_ENV_KEY]?.trim();
+  if (profile) {
+    const profileSource = options.profile?.trim() ? "explicit profile argument" : CREDENTIAL_PROFILE_ENV_KEY;
+    if (!SAFE_PROFILE.test(profile)) {
+      throw new CredentialResolutionError(name, `Profile name from ${profileSource} is not usable in a path. ` + `Use letters, digits, dot, dash, or underscore.`, [profileSource]);
+    }
+    const paths = profileDiskSources(name, env, profile);
+    for (const path of paths) {
+      const value = readCredentialFile(path, apiKeyKeys);
+      if (value) {
+        assertUsableCredential(name, path, value);
+        return sealCredential({
+          apiKey: value,
+          tier: "profile",
+          source: path,
+          deliberate: true,
+          deprecated: false,
+          diskCandidates: paths,
+          warning: null
+        });
+      }
+    }
+    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);
+  if (diskHits.length > 0) {
+    const winner = diskHits[0];
+    assertUsableCredential(name, winner.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] : [];
+      })()
+    ];
+    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;
+    return sealCredential({
+      apiKey: winner.value,
+      tier: "disk",
+      source: winner.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);
+    }
+    return sealCredential({
+      apiKey: legacy.value,
+      tier: "legacy-env",
+      source: legacy.key,
+      deliberate: false,
+      deprecated: true,
+      diskCandidates: diskPaths,
+      warning: message
+    });
+  }
+  return null;
+}
+var ASCII_CONTROL_PATTERN = /[\u0000-\u001f\u007f]/;
+var DNS_LABEL_PATTERN = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/;
+function isValidDnsDomain(value) {
+  if (value.length === 0 || value.length > 253 || ASCII_CONTROL_PATTERN.test(value) || /[^\x00-\x7f]/.test(value)) {
+    return false;
+  }
+  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;
+  }
+  return null;
+}
+function rawAuthority(value) {
+  const match = /^[a-z][a-z0-9+.-]*:\/\//i.exec(value);
+  if (!match)
+    throw new Error("API URL must be absolute.");
+  const afterScheme = value.slice(match[0].length);
+  const boundary = afterScheme.search(/[/?#]/);
+  const authority = boundary === -1 ? afterScheme : afterScheme.slice(0, boundary);
+  if (!authority)
+    throw new Error("API URL must include a hostname.");
+  return authority;
+}
+function assertCanonicalPort(port) {
+  if (!/^[0-9]+$/.test(port) || port.length > 1 && port.startsWith("0")) {
+    throw new Error("API URL authority must contain a canonical port between 1 and 65535.");
+  }
+  const numericPort = Number(port);
+  if (!Number.isSafeInteger(numericPort) || numericPort < 1 || numericPort > 65535) {
+    throw new Error("API URL authority must contain a canonical port between 1 and 65535.");
+  }
+}
+function canonicalAuthorityHostname(authority) {
+  let rawHostname;
+  if (authority.startsWith("[")) {
+    const closingBracket = authority.indexOf("]");
+    if (closingBracket === -1) {
+      throw new Error("API URL authority must contain a canonical hostname.");
+    }
+    rawHostname = authority.slice(0, closingBracket + 1);
+    const portSuffix = authority.slice(closingBracket + 1);
+    if (portSuffix) {
+      if (!portSuffix.startsWith(":")) {
+        throw new Error("API URL authority must contain a canonical hostname and port.");
+      }
+      assertCanonicalPort(portSuffix.slice(1));
+    }
+    if (isIP(rawHostname.slice(1, -1)) !== 6) {
+      throw new Error("API URL authority must contain a canonical IPv6 literal.");
+    }
+  } else {
+    const firstColon = authority.indexOf(":");
+    const lastColon = authority.lastIndexOf(":");
+    if (firstColon !== lastColon) {
+      throw new Error("IPv6 API URL authorities must use brackets.");
+    }
+    if (lastColon !== -1) {
+      const port = authority.slice(lastColon + 1);
+      assertCanonicalPort(port);
+      rawHostname = authority.slice(0, lastColon);
+    } else {
+      rawHostname = authority;
+    }
+    const ipVersion = isIP(rawHostname);
+    const numericAddressParts = rawHostname.split(".");
+    const looksLikeNonCanonicalIpv4 = numericAddressParts.every((part) => /^(?:0x[0-9a-f]+|[0-9]+)$/i.test(part));
+    if (ipVersion !== 4 && looksLikeNonCanonicalIpv4 || ipVersion !== 4 && !isValidDnsDomain(rawHostname.toLowerCase())) {
+      throw new Error("API URL authority must contain a canonical ASCII hostname.");
+    }
+  }
+  return rawHostname.toLowerCase();
+}
+function isDeliberateLoopbackHttpAuthority(authority) {
+  return /^(?:localhost|127\.0\.0\.1|\[::1\])(?::[0-9]+)?$/i.test(authority);
+}
 function toV1BaseUrl(apiUrl) {
-  const url = new URL(apiUrl);
+  if (ASCII_CONTROL_PATTERN.test(apiUrl)) {
+    throw new Error("API URL must not contain ASCII control characters.");
+  }
+  const input = apiUrl.trim();
+  const authority = rawAuthority(input);
+  if (authority.includes("@") || authority.includes("\\") || authority.includes("%") || /[^\x00-\x7f]/.test(authority)) {
+    throw new Error("API URL authority must be canonical ASCII without credentials.");
+  }
+  const canonicalHostname = canonicalAuthorityHostname(authority);
+  const url = new URL(input);
   if (url.protocol !== "http:" && url.protocol !== "https:") {
     throw new Error("API URL must use http or https.");
   }
+  if (url.username || url.password) {
+    throw new Error("API URL must not include credentials.");
+  }
+  if (!url.hostname || url.hostname.endsWith(".")) {
+    throw new Error("API URL must include a canonical hostname.");
+  }
+  if (url.hostname.toLowerCase() !== canonicalHostname) {
+    throw new Error("API URL authority must not rely on parser hostname normalization.");
+  }
+  if (url.hostname.split(".").some((label) => label.toLowerCase().startsWith("xn--"))) {
+    throw new Error("API URL must not use IDN or punycode hostnames.");
+  }
+  if (url.protocol === "http:" && !isDeliberateLoopbackHttpAuthority(authority)) {
+    throw new Error("API URL may use http only for an exact loopback authority.");
+  }
+  if (url.search || url.hash) {
+    throw new Error("API URL must not include a query string or fragment.");
+  }
   let path = url.pathname.replace(/\/+$/, "");
   if (path.endsWith("/v1"))
     path = path.slice(0, -"/v1".length);
   url.pathname = `${path}/v1`;
-  url.search = "";
-  url.hash = "";
   return url.toString().replace(/\/+$/, "");
 }
-function resolveTransport(name, env = process.env) {
-  const keys = envKeys(name);
-  const storeHit = firstEnv(env, keys.storeKeys);
-  const urlHit = firstEnv(env, keys.apiUrlKeys);
+function resolveClientTransport(name, env = process.env, options = {}) {
+  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);
-  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 };
-  }
+  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",
-      requested,
-      modeSource,
+      transportSource: "default",
       baseUrl: null,
+      apiUrlSource: null,
       apiKeyPresent: Boolean(keyHit),
-      misconfigured: true,
-      warning: `${modeSource}=http but no API URL is set (${keys.apiUrlKeys[0]}). Refusing to route to the API.`
+      apiKeySource: keyHit ? keyHit.key : null,
+      apiKeyTier: null,
+      misconfigured: false,
+      warning: null
     };
   }
-  if (!keyHit) {
+  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 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",
-      requested,
-      modeSource,
+      transportSource: urlHit.key,
       baseUrl: null,
+      apiUrlSource: urlHit.key,
       apiKeyPresent: false,
+      apiKeySource: null,
+      apiKeyTier: null,
       misconfigured: true,
-      warning: `${modeSource}=http but no API key is set (${keys.apiKeyKeys[0]}). Refusing to route to the API.`
+      warning: warnings.join(" ")
     };
   }
-  const rawUrl = urlHit.value;
+  if (credential.warning)
+    warnings.push(credential.warning);
+  const apiUrlSource = urlHit.key;
   let baseUrl;
   try {
-    baseUrl = toV1BaseUrl(rawUrl);
+    baseUrl = toV1BaseUrl(urlHit.value);
   } 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}.` };
+    warnings.push(`Invalid API URL from ${apiUrlSource}: ${message}. Using local store.`);
+    return {
+      transport: "sqlite",
+      transportSource: urlHit.key,
+      baseUrl: null,
+      apiUrlSource: urlHit.key,
+      apiKeyPresent: true,
+      apiKeySource: credential.source,
+      apiKeyTier: credential.tier,
+      misconfigured: true,
+      warning: warnings.join(" ")
+    };
   }
-  return { transport: "http", requested, modeSource, baseUrl, apiKeyPresent: true, misconfigured: false, warning: null };
+  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
+  };
+}
+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 {
@@ -2152,49 +2596,113 @@ class HasnaHttpError extends Error {
   method;
   path;
   body;
-  constructor(method, path, status, body) {
-    super(`Hasna request failed: ${method} ${path} -> ${status}`);
+  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.`;
+}
+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",
+  ":authority",
+  "forwarded",
+  "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}'.`);
   }
 }
 function appendQuery(path, query) {
   if (!query)
     return path;
-  const params = new 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 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();
-  return qs ? `${path}${path.includes("?") ? "&" : "?"}${qs}` : path;
+  if (!qs)
+    return path;
+  return `${path}${path.includes("?") ? "&" : "?"}${qs}`;
 }
-var RETRY_STATUSES = new Set([408, 425, 429, 500, 502, 503, 504]);
-var IDEMPOTENT = new Set(["GET", "HEAD", "PUT", "DELETE", "OPTIONS"]);
-var defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
-function createHttpTransport(options) {
+var defaultSleep = (ms) => new Promise((resolve3) => setTimeout(resolve3, ms));
+function createHasnaHttpTransport(options) {
   const fetchImpl = options.fetchImpl ?? ((input, init) => fetch(input, init));
-  const base = options.baseUrl.replace(/\/+$/, "");
+  const base = toV1BaseUrl(options.baseUrl);
   const timeoutMs = options.timeoutMs ?? 30000;
   const sleep = options.sleepImpl ?? defaultSleep;
-  async function once(method, rel, url, body, opts) {
+  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": options.apiKey,
-      Authorization: `Bearer ${options.apiKey}`,
+      "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 };
+    const init = {
+      method,
+      headers,
+      redirect: "manual"
+    };
     if (body !== undefined) {
       headers["Content-Type"] = "application/json";
       init.body = JSON.stringify(body);
@@ -2232,7 +2740,27 @@ function createHttpTransport(options) {
       }
     }
     if (!response.ok) {
-      return { ok: false, retryable: RETRY_STATUSES.has(response.status), error: new HasnaHttpError(method, rel, response.status, parsed) };
+      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 };
   }
@@ -2240,24 +2768,23 @@ function createHttpTransport(options) {
     const upper = method.toUpperCase();
     const rel = appendQuery(path.startsWith("/") ? path : `/${path}`, opts.query);
     const url = `${base}${rel}`;
-    const methodRetryable = IDEMPOTENT.has(upper) || Boolean(opts.idempotencyKey);
-    const maxRetries = opts.retries ?? 2;
-    const maxAttempts = methodRetryable ? maxRetries + 1 : 1;
+    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);
+      const result = await once(upper, rel, url, body, opts, credential);
       if (result.ok)
         return result.value;
       last = result;
-      const canRetry = methodRetryable && result.retryable && attempt < maxAttempts;
+      const canRetry = retry !== null && methodRetryable && result.retryable && attempt < maxAttempts;
       if (!canRetry)
         break;
-      const backoff = Math.min(2000, 200 * 2 ** (attempt - 1));
+      const backoff = Math.min(retry.maxDelayMs, retry.baseDelayMs * 2 ** (attempt - 1));
       const jitter = Math.floor(Math.random() * (backoff / 2 + 1));
       await sleep(backoff + jitter);
     }
-    if (last === null)
-      throw new Error(`Request to ${rel} completed without a result`);
     throw last.error;
   }
   return {
@@ -2265,81 +2792,289 @@ function createHttpTransport(options) {
     request,
     get: (path, opts) => request("GET", path, undefined, opts),
     post: (path, body, opts) => request("POST", path, body, opts),
-    patch: (path, body, opts) => request("PATCH", 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
+var MAX_CREDENTIAL_FILE_BYTES2 = 64 * 1024;
+var INSPECT_CUSTOM2 = Symbol.for("nodejs.util.inspect.custom");
+var CREDENTIAL_SEAL2 = Symbol.for("hasna:contracts:sealedCredential");
+var DEPRECATION_REGISTRY2 = Symbol.for("hasna:contracts:credentialDeprecationNotices");
+var IDEMPOTENT_METHODS2 = new Set(["GET", "HEAD", "PUT", "DELETE", "OPTIONS"]);
+var AUTHORITY_OVERRIDE_HEADERS2 = new Set([
+  "host",
+  ":authority",
+  "forwarded",
+  "x-forwarded-host",
+  "x-original-host"
+]);
+function resourcePath(resource) {
+  const trimmed = resource.replace(/^\/+|\/+$/g, "");
+  if (!trimmed)
+    throw new Error("resource must be a non-empty path segment");
+  return `/${trimmed}`;
+}
+function entityPath(resource, id) {
+  if (id === undefined || id === null || `${id}`.length === 0) {
+    throw new Error("id must be a non-empty string");
+  }
+  return `${resourcePath(resource)}/${encodeURIComponent(String(id))}`;
+}
 function newIdempotencyKey() {
   const g = globalThis;
   if (g.crypto?.randomUUID)
     return g.crypto.randomUUID();
   return `idmp_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 12)}`;
 }
-function extractItems(raw, extraKeys = []) {
+function extractItems(raw) {
   if (Array.isArray(raw))
     return raw;
   if (raw && typeof raw === "object") {
     const obj = raw;
-    for (const key of [...extraKeys, "items", "data", "results", "rows", "records"]) {
+    for (const key of ["items", "data", "results", "rows", "records"]) {
       if (Array.isArray(obj[key]))
         return obj[key];
     }
   }
   return [];
 }
-function createStorageClient(name, transport) {
-  const rp = (r) => `/${r.replace(/^\/+|\/+$/g, "")}`;
-  const ep = (r, id) => `${rp(r)}/${encodeURIComponent(String(id))}`;
+function extractTotal(raw) {
+  if (raw && typeof raw === "object") {
+    const obj = raw;
+    for (const key of ["total", "count", "totalCount", "total_count"]) {
+      if (typeof obj[key] === "number")
+        return obj[key];
+    }
+  }
+  return null;
+}
+function extractCursor(raw) {
+  if (raw && typeof raw === "object") {
+    const obj = raw;
+    for (const key of ["cursor", "nextCursor", "next_cursor", "next"]) {
+      if (typeof obj[key] === "string")
+        return obj[key];
+    }
+  }
+  return null;
+}
+function isNotFoundHttpError(error) {
+  return typeof error === "object" && error !== null && error.name === "HasnaHttpError" && error.status === 404;
+}
+function createHasnaStorageClient(name, transport) {
   return {
     name,
     baseUrl: transport.baseUrl,
     transport,
-    async list(resource, query) {
-      const raw = await transport.get(rp(resource), { query });
-      return { items: extractItems(raw, [resource]), raw };
+    async list(resource, options = {}) {
+      const raw = await transport.get(resourcePath(resource), options);
+      return {
+        items: extractItems(raw),
+        total: extractTotal(raw),
+        cursor: extractCursor(raw),
+        raw
+      };
     },
-    async get(resource, id) {
+    async get(resource, id, options = {}) {
       try {
-        return await transport.get(ep(resource, id));
+        return await transport.get(entityPath(resource, id), options);
       } catch (error) {
-        if (error instanceof HasnaHttpError && error.status === 404)
+        if (isNotFoundHttpError(error))
           return null;
         throw error;
       }
     },
-    async create(resource, body, idempotencyKey) {
-      return transport.post(rp(resource), body, { idempotencyKey: idempotencyKey ?? newIdempotencyKey() });
+    async create(resource, body, options = {}) {
+      const { idempotencyKey, ...rest } = options;
+      return transport.post(resourcePath(resource), body, {
+        ...rest,
+        idempotencyKey: idempotencyKey ?? newIdempotencyKey()
+      });
     },
-    async update(resource, id, patch, method = "PATCH") {
+    async update(resource, id, patch, options = {}) {
+      const { method = "PATCH", idempotencyKey, ...rest } = options;
       const call = method === "PUT" ? transport.put : transport.patch;
-      return call(ep(resource, id), patch);
+      return call(entityPath(resource, id), patch, { ...rest, ...idempotencyKey ? { idempotencyKey } : {} });
     },
-    async delete(resource, id) {
+    async delete(resource, id, options = {}) {
       try {
-        await transport.del(ep(resource, id));
+        await transport.del(entityPath(resource, id), undefined, options);
       } catch (error) {
-        if (error instanceof HasnaHttpError && error.status === 404)
+        if (isNotFoundHttpError(error))
           return;
         throw error;
       }
     }
   };
 }
-function resolveStorageClient(name, env = process.env, fetchImpl) {
+
+// src/http/client.ts
+function envToken2(name) {
+  return name.toUpperCase().replace(/-/g, "_");
+}
+function envKeys(name) {
+  const token = envToken2(name);
+  return {
+    storeKeys: [`HASNA_${token}_CLIENT_STORE`, `${token}_CLIENT_STORE`],
+    apiUrlKeys: [`HASNA_${token}_API_URL`],
+    apiKeyKeys: [`HASNA_${token}_API_KEY`]
+  };
+}
+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.`);
+}
+function firstEnv2(env, keys) {
+  for (const key of keys) {
+    const value = env[key]?.trim();
+    if (value)
+      return { key, value };
+  }
+  return null;
+}
+function toV1BaseUrl2(apiUrl) {
+  const url = new URL(apiUrl);
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new Error("API URL must use http or https.");
+  }
+  let path = url.pathname.replace(/\/+$/, "");
+  if (path.endsWith("/v1"))
+    path = path.slice(0, -"/v1".length);
+  url.pathname = `${path}/v1`;
+  url.search = "";
+  url.hash = "";
+  return url.toString().replace(/\/+$/, "");
+}
+function resolveTransport(name, env = process.env) {
+  const keys = envKeys(name);
+  const storeHit = firstEnv2(env, keys.storeKeys);
+  const urlHit = firstEnv2(env, keys.apiUrlKeys);
+  const keyHit = firstEnv2(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 = toV1BaseUrl2(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 };
+}
+var RETRY_STATUSES = new Set([408, 425, 429, 500, 502, 503, 504]);
+var IDEMPOTENT = new Set(["GET", "HEAD", "PUT", "DELETE", "OPTIONS"]);
+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
+        }
+      };
+    }
     throw new Error(resolution.warning ?? `Client for '${name}' is misconfigured for the /v1 API.`);
   }
   if (resolution.transport === "sqlite" || !resolution.baseUrl) {
     return { transport: "sqlite", client: null, resolution };
   }
-  const keys = envKeys(name);
-  const apiKey = firstEnv(env, keys.apiKeyKeys)?.value;
-  if (!apiKey)
+  const wired = createClientTransport(name, env);
+  if (wired.transport !== "http") {
     throw new Error(`Client for '${name}' resolved to the /v1 API without an API key.`);
-  const transport = createHttpTransport({ name, baseUrl: resolution.baseUrl, apiKey, ...fetchImpl ? { fetchImpl } : {} });
-  return { transport: "http", client: createStorageClient(name, transport), resolution };
+  }
+  return { transport: "http", client: createHasnaStorageClient(name, wired.client), resolution };
 }
 
 // src/store.ts
@@ -2422,6 +3157,22 @@ var localStore = {
     await withLocalStoreReaderLease(() => saveFeedback(input));
   }
 };
+async function listResource(client, resource, query) {
+  const raw = await client.transport.get(`/${resource}`, query ? { query } : undefined);
+  return { items: extractEnvelopeItems(raw, resource), raw };
+}
+function extractEnvelopeItems(raw, resource) {
+  if (Array.isArray(raw))
+    return raw;
+  if (raw && typeof raw === "object") {
+    const obj = raw;
+    for (const key of [resource, "items", "data", "results", "rows", "records"]) {
+      if (Array.isArray(obj[key]))
+        return obj[key];
+    }
+  }
+  return [];
+}
 function apiStore(client) {
   return {
     mode: "http",
@@ -2429,7 +3180,7 @@ function apiStore(client) {
     async createRecording(input, idempotencyKey) {
       const keyCandidate = idempotencyKey === undefined && (input.id === undefined || input.id === null) ? randomUUID5() : idempotencyKey;
       const identity = recordingCreateIdentity(input, keyCandidate, { bindIdempotencyKeyToId: false });
-      const res = await client.create("recordings", identity.input, identity.idempotencyKey);
+      const res = await client.create("recordings", identity.input, { idempotencyKey: identity.idempotencyKey });
       return unwrap(res, "recording");
     },
     async getRecording(id) {
@@ -2437,7 +3188,7 @@ function apiStore(client) {
       return res ? unwrap(res, "recording") : null;
     },
     async listRecordings(filter) {
-      const { items } = await client.list("recordings", listQuery(filter));
+      const { items } = await listResource(client, "recordings", listQuery(filter));
       return items;
     },
     async countRecordings(filter) {
@@ -2448,7 +3199,7 @@ function apiStore(client) {
       const seenPageKeys = new Set;
       while (pageRequests < maxPageRequests) {
         pageRequests += 1;
-        const { items, raw } = await client.list("recordings", {
+        const { items, raw } = await listResource(client, "recordings", {
           ...listQuery(filter),
           limit: pageLimit,
           offset
@@ -2471,7 +3222,7 @@ function apiStore(client) {
       throw new Error(`Recordings API exceeded ${maxPageRequests} pages while counting legacy results`);
     },
     async searchRecordings(query, filter) {
-      const { items } = await client.list("recordings", listQuery({ ...filter ?? {}, search: query }));
+      const { items } = await listResource(client, "recordings", listQuery({ ...filter ?? {}, search: query }));
       return items;
     },
     async deleteRecording(id) {
@@ -2503,7 +3254,7 @@ function apiStore(client) {
       return res ? unwrap(res, "agent") : null;
     },
     async listAgents() {
-      const { items } = await client.list("agents");
+      const { items } = await listResource(client, "agents");
       return items;
     },
     async heartbeatAgent(idOrName) {
@@ -2543,7 +3294,7 @@ function apiStore(client) {
       return res ? unwrap(res, "project") : null;
     },
     async listProjects() {
-      const { items } = await client.list("projects");
+      const { items } = await listResource(client, "projects");
       return items;
     },
     async saveFeedback(input) {
@@ -2591,7 +3342,7 @@ var cached = null;
 function getStore(env = process.env) {
   if (env === process.env && cached)
     return cached;
-  const resolved = resolveStorageClient(APP, env);
+  const resolved = resolveStoreClient(APP, env);
   const store = resolved.transport === "http" ? apiStore(resolved.client) : localStore;
   if (env === process.env)
     cached = store;
@@ -2600,7 +3351,7 @@ function getStore(env = process.env) {
 
 // src/lib/recorder.ts
 import { spawn as spawn2 } from "child_process";
-import { join as join4 } from "path";
+import { join as join5 } from "path";
 import { existsSync as existsSync3 } from "fs";
 
 // src/types/index.ts
@@ -2651,7 +3402,7 @@ function startRecording(config) {
   }
   const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
   const filename = `recording-${timestamp}.${config.audio_format}`;
-  const filepath = join4(config.audio_dir, filename);
+  const filepath = join5(config.audio_dir, filename);
   const args = buildRecordArgs(filepath, config);
   const [command, ...commandArgs] = args;
   if (command === undefined) {
@@ -2723,7 +3474,7 @@ function buildRecordArgs(filepath, config) {
 async function recordDuration(seconds, config) {
   const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
   const filename = `recording-${timestamp}.${config.audio_format}`;
-  const filepath = join4(config.audio_dir, filename);
+  const filepath = join5(config.audio_dir, filename);
   const args = [
     "rec",
     "-r",
@@ -2896,8 +3647,8 @@ ${trimmed}`;
 
 // src/lib/capture-probe.ts
 import { spawnSync as spawnSync2 } from "child_process";
-import { existsSync as existsSync4, readFileSync as readFileSync2, rmSync as rmSync2 } from "fs";
-import { join as join5 } from "path";
+import { existsSync as existsSync4, readFileSync as readFileSync3, rmSync as rmSync2 } from "fs";
+import { join as join6 } from "path";
 import { tmpdir } from "os";
 
 // src/lib/macos-bundle.ts
@@ -2913,7 +3664,7 @@ var WAVE_FORMAT_PCM = 1;
 var WAVE_FORMAT_EXTENSIBLE = 65534;
 var SUBFORMAT_OFFSET_IN_EXTENSION = 8;
 function readWavPeak(filepath) {
-  const buf = readFileSync2(filepath);
+  const buf = readFileSync3(filepath);
   if (buf.length < RIFF_HEADER_BYTES) {
     throw new Error(`not a RIFF file (${buf.length} bytes): ${filepath}`);
   }
@@ -2988,7 +3739,7 @@ function probeMicrophoneCapture(config, options = {}) {
     peak: 0,
     silent: null
   };
-  const filepath = join5(tmpdir(), `recordings-capture-probe-${process.pid}-${Date.now()}.wav`);
+  const filepath = join6(tmpdir(), `recordings-capture-probe-${process.pid}-${Date.now()}.wav`);
   try {
     const result = spawnSync2(executable, [
       "-q",
@@ -3160,7 +3911,7 @@ function microphoneGrantInstruction(options) {
     steps.push(`AMBIGUOUS: ${candidates.length} HasnaRecordings.app bundles exist (${candidates.join(", ")}). ` + "A TCC grant is bound to the bundle's code signature, so granting one does not grant the " + "other, and the toggle in Settings does not say which is which. Remove the bundles you are " + "not running before granting, or the grant may attach to the wrong one.");
   }
   steps.push(`At the keyboard on the machine itself (not over SSH), launch ${bundlePath} and start a ` + "recording once. macOS shows the consent sheet titled " + `"\u201CRecordings\u201D would like to access the microphone" \u2014 click Allow.`);
-  steps.push("If no sheet appears, open System Settings \u2192 Privacy & Security \u2192 Microphone " + "and switch ON the row named \u201CRecordings\u201D. " + `That row is bundle ${RECORDINGS_BUNDLE_IDENTIFIER} at ${bundlePath}; the binary that ` + `receives the grant is ${join5(bundlePath, "Contents", "MacOS", "Recordings")}.`);
+  steps.push("If no sheet appears, open System Settings \u2192 Privacy & Security \u2192 Microphone " + "and switch ON the row named \u201CRecordings\u201D. " + `That row is bundle ${RECORDINGS_BUNDLE_IDENTIFIER} at ${bundlePath}; the binary that ` + `receives the grant is ${join6(bundlePath, "Contents", "MacOS", "Recordings")}.`);
   if (options.requestState === "never_requested") {
     steps.push("Note: the app has never requested microphone access on this machine (no TCC entry exists), " + "so the Microphone list will NOT contain a \u201CRecordings\u201D row until the app asks once. " + "Do the launch-and-record step first; the Settings toggle only exists afterwards.");
   } else if (options.requestState === "unknown") {
@@ -3693,12 +4444,12 @@ ${block}` : block;
 
 // src/cli/macos-permissions.ts
 import { spawnSync as spawnSync3 } from "child_process";
-import { existsSync as existsSync6, mkdtempSync, rmSync as rmSync3, statSync as statSync2, writeFileSync as writeFileSync2 } from "fs";
+import { existsSync as existsSync6, mkdtempSync, rmSync as rmSync3, statSync as statSync3, writeFileSync as writeFileSync2 } from "fs";
 import { tmpdir as tmpdir2 } from "os";
-import { join as join6 } from "path";
+import { join as join7 } from "path";
 var defaultPermissionHelperRunner = (executable, arguments_, options) => spawnSync3(executable, arguments_, options);
 function runMacOSPermissionRequest(appPath, runner = defaultPermissionHelperRunner) {
-  const executable = join6(appPath, "Contents", "MacOS", "Recordings");
+  const executable = join7(appPath, "Contents", "MacOS", "Recordings");
   const result = runner(executable, ["--request-permissions", "--open-permission-settings"], { stdio: "inherit" });
   return {
     exitCode: result.error ? 1 : result.status ?? 1,
@@ -3709,8 +4460,8 @@ var CODESIGN_REQUIREMENT_SATISFIED_STATUS = 0;
 var CODESIGN_REQUIREMENT_UNSATISFIED_STATUS = 3;
 function tccDatabasePaths(home) {
   return [
-    join6(home, "Library", "Application Support", "com.apple.TCC", "TCC.db"),
-    join6("/", "Library", "Application Support", "com.apple.TCC", "TCC.db")
+    join7(home, "Library", "Application Support", "com.apple.TCC", "TCC.db"),
+    join7("/", "Library", "Application Support", "com.apple.TCC", "TCC.db")
   ];
 }
 function tccAuthValueLabel(value) {
@@ -3737,8 +4488,8 @@ function verifyStoredRequirementWithCodesign(csreqHex, appPath, runner = default
     return "unverifiable";
   let scratchDirectory = null;
   try {
-    scratchDirectory = mkdtempSync(join6(tmpdir2(), "recordings-tcc-csreq-"));
-    const requirementPath = join6(scratchDirectory, "tcc-requirement.bin");
+    scratchDirectory = mkdtempSync(join7(tmpdir2(), "recordings-tcc-csreq-"));
+    const requirementPath = join7(scratchDirectory, "tcc-requirement.bin");
     writeFileSync2(requirementPath, Buffer.from(normalized, "hex"));
     const result = runner(requirementPath, appPath);
     if (result.error)
@@ -3758,7 +4509,7 @@ function verifyStoredRequirementWithCodesign(csreqHex, appPath, runner = default
 var defaultTccPermissionProbe = {
   databasePresence: (dbPath) => {
     try {
-      statSync2(dbPath);
+      statSync3(dbPath);
       return "present";
     } catch (error) {
       return error.code === "ENOENT" ? "absent" : "indeterminate";
@@ -3797,8 +4548,8 @@ function describeStoredRequirementWithCsreq(csreqHex, runner = (requirementPath)
   }
   let scratchDirectory = null;
   try {
-    scratchDirectory = mkdtempSync(join6(tmpdir2(), "recordings-tcc-decode-"));
-    const requirementPath = join6(scratchDirectory, "tcc-requirement.bin");
+    scratchDirectory = mkdtempSync(join7(tmpdir2(), "recordings-tcc-decode-"));
+    const requirementPath = join7(scratchDirectory, "tcc-requirement.bin");
     writeFileSync2(requirementPath, Buffer.from(normalized, "hex"));
     const result = runner(requirementPath);
     if (result.error || result.status !== 0)
@@ -4200,7 +4951,7 @@ function writeUseFnKey(enabled) {
 }
 
 // src/cli/trigger-probe.ts
-import { closeSync, openSync, readSync, statSync as statSync3 } from "fs";
+import { closeSync, openSync, readSync, statSync as statSync4 } from "fs";
 var FN_BLOCKING_ACCESSIBILITY_STATES = [
   "denied",
   "stale_allowed_for_previous_app_build"
@@ -4319,7 +5070,7 @@ function readAppLogTail(logPath, maxBytes = APP_LOG_TAIL_BYTES) {
     return null;
   let handle = null;
   try {
-    const size = statSync3(logPath).size;
+    const size = statSync4(logPath).size;
     if (size === 0)
       return null;
     const length = Math.min(size, maxBytes);
@@ -4439,7 +5190,7 @@ function currentMachineId(env = process.env, hostName = hostname()) {
 }
 
 // src/lib/bun-runtime.ts
-import { accessSync, constants as fsConstants, realpathSync as realpathSync3, statSync as statSync4 } from "fs";
+import { accessSync, constants as fsConstants, realpathSync as realpathSync3, statSync as statSync5 } from "fs";
 import { isAbsolute as isAbsolute2 } from "path";
 import { randomBytes } from "crypto";
 import { spawnSync as spawnSync5 } from "child_process";
@@ -4461,7 +5212,7 @@ function validateBunExecutable(candidate) {
   let executable;
   try {
     executable = realpathSync3(candidate);
-    if (!statSync4(executable).isFile())
+    if (!statSync5(executable).isFile())
       return { reason: "resolved path is not a regular file" };
     accessSync(executable, fsConstants.X_OK);
   } catch {
@@ -4541,11 +5292,11 @@ import {
   fsyncSync,
   mkdtempSync as mkdtempSync2,
   openSync as openSync2,
-  readFileSync as readFileSync3,
+  readFileSync as readFileSync4,
   rmSync as rmSync4,
   writeFileSync as writeFileSync3
 } from "fs";
-import { isAbsolute as isAbsolute3, join as join7 } from "path";
+import { isAbsolute as isAbsolute3, join as join8 } from "path";
 var LOWER_SHA256 = /^[a-f0-9]{64}$/;
 var LOWER_SOURCE_SHA = /^[a-f0-9]{40}$/;
 var RELEASE_VERSION = /^[0-9]+\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z.-]+)?$/;
@@ -4618,7 +5369,7 @@ function prepareReleaseInstallInputs(input) {
   if (!isAbsolute3(snapshotRoot)) {
     throw new Error("release snapshot root must be absolute");
   }
-  const snapshotDirectory = mkdtempSync2(join7(snapshotRoot, "recordings-release-install."));
+  const snapshotDirectory = mkdtempSync2(join8(snapshotRoot, "recordings-release-install."));
   let cleaned = false;
   const cleanup = () => {
     if (cleaned)
@@ -4630,9 +5381,9 @@ function prepareReleaseInstallInputs(input) {
     rmSync4(snapshotDirectory, { recursive: true, force: true });
   };
   try {
-    const manifestSnapshot = join7(snapshotDirectory, `${input.manifestSha256}.manifest.json`);
+    const manifestSnapshot = join8(snapshotDirectory, `${input.manifestSha256}.manifest.json`);
     const envelopeDigest = createHash2("sha256").update(envelopeBytes).digest("hex");
-    const envelopeSnapshot = join7(snapshotDirectory, `${envelopeDigest}.envelope.json`);
+    const envelopeSnapshot = join8(snapshotDirectory, `${envelopeDigest}.envelope.json`);
     writeSnapshot(manifestSnapshot, manifestBytes);
     writeSnapshot(envelopeSnapshot, envelopeBytes);
     chmodSync2(snapshotDirectory, 320);
@@ -4653,7 +5404,7 @@ function readBoundedRegularFile(path, label, maximum) {
     if (!metadata.isFile() || metadata.size < 1 || metadata.size > maximum) {
       throw new Error(`${label} must be a non-empty bounded regular file`);
     }
-    return readFileSync3(descriptor);
+    return readFileSync4(descriptor);
   } finally {
     closeSync2(descriptor);
   }
@@ -4744,8 +5495,8 @@ function writeSnapshot(path, bytes) {
 }
 
 // src/cli/desktop-snapshot.ts
-import { chmodSync as chmodSync3, mkdirSync as mkdirSync4, mkdtempSync as mkdtempSync3, renameSync as renameSync2, rmSync as rmSync5, statSync as statSync5 } from "fs";
-import { dirname as dirname4, join as join8, resolve as resolve3 } from "path";
+import { chmodSync as chmodSync3, mkdirSync as mkdirSync4, mkdtempSync as mkdtempSync3, renameSync as renameSync2, rmSync as rmSync5, statSync as statSync6 } from "fs";
+import { dirname as dirname4, join as join9, resolve as resolve3 } from "path";
 import { spawnSync as spawnSync6 } from "child_process";
 var SCREEN_CAPTURE_EXECUTABLE = "/usr/sbin/screencapture";
 var DEFAULT_DESKTOP_SNAPSHOT = "desktop-snapshot.png";
@@ -4767,9 +5518,9 @@ function exportDesktopSnapshot(output = DEFAULT_DESKTOP_SNAPSHOT, dependencies =
   const destination = resolve3(dependencies.cwd ?? process.cwd(), output);
   const destinationDirectory = dirname4(destination);
   mkdirSync4(destinationDirectory, { recursive: true });
-  const stagingDirectory = mkdtempSync3(join8(destinationDirectory, ".recordings-desktop-"));
+  const stagingDirectory = mkdtempSync3(join9(destinationDirectory, ".recordings-desktop-"));
   chmodSync3(stagingDirectory, 448);
-  const stagingPath = join8(stagingDirectory, "snapshot.png");
+  const stagingPath = join9(stagingDirectory, "snapshot.png");
   try {
     const capture = dependencies.capture ?? runScreenCapture;
     const result = capture(SCREEN_CAPTURE_EXECUTABLE, [
@@ -4789,7 +5540,7 @@ function exportDesktopSnapshot(output = DEFAULT_DESKTOP_SNAPSHOT, dependencies =
     }
     let size = 0;
     try {
-      const snapshot = statSync5(stagingPath);
+      const snapshot = statSync6(stagingPath);
       if (snapshot.isFile())
         size = snapshot.size;
     } catch {}
@@ -5238,10 +5989,10 @@ program.command("projects").description("List registered projects").option("-n,
 });
 program.command("init").description("Initialize .recordings/ in current directory").action(() => {
   const { mkdirSync: mkdirSync5, writeFileSync: writeFileSync4, existsSync: existsSync9 } = __require("fs");
-  const { join: join9 } = __require("path");
-  const dir = join9(process.cwd(), ".recordings");
-  const audioDir = join9(dir, "audio");
-  const configFile = join9(dir, "config.json");
+  const { join: join10 } = __require("path");
+  const dir = join10(process.cwd(), ".recordings");
+  const audioDir = join10(dir, "audio");
+  const configFile = join10(dir, "config.json");
   mkdirSync5(audioDir, { recursive: true });
   if (!existsSync9(configFile)) {
     const defaultConf = {
@@ -6261,7 +7012,7 @@ async function readSaveTextInput(text, opts) {
   }
   let rawText;
   if (opts.textFile !== undefined) {
-    rawText = readFileSync4(opts.textFile, "utf8");
+    rawText = readFileSync5(opts.textFile, "utf8");
   } else if (opts.stdin) {
     rawText = await Bun.stdin.text();
   } else {
@@ -6475,7 +7226,7 @@ function relativeHint(value) {
   return `${Math.floor(hours / 24)}d ago`;
 }
 program.command("mcp").description("Install recordings MCP server into Claude Code, Codex, or Gemini").option("--claude", "Install into Claude Code (via `claude mcp add`)").option("--codex", "Install into Codex (~/.codex/config.toml)").option("--gemini", "Install into Gemini (~/.gemini/settings.json)").option("--all", "Install into all supported agents").option("--uninstall", "Remove recordings MCP from config").action(async (opts) => {
-  const { readFileSync: readFileSync5, writeFileSync: writeFileSync4, existsSync: fileExists } = __require("fs");
+  const { readFileSync: readFileSync6, writeFileSync: writeFileSync4, existsSync: fileExists } = __require("fs");
   const { join: pathJoin2 } = __require("path");
   const { homedir: getHome } = __require("os");
   const { execSync } = __require("child_process");
@@ -6508,7 +7259,7 @@ program.command("mcp").description("Install recordings MCP server into Claude Co
       if (target === "codex") {
         const configPath = pathJoin2(home, ".codex", "config.toml");
         if (fileExists(configPath)) {
-          const content = readFileSync5(configPath, "utf-8");
+          const content = readFileSync6(configPath, "utf-8");
           if (opts.uninstall) {
             const { content: next, removed } = removeCodexServerBlock(content, "recordings");
             writeFileSync4(configPath, next, "utf-8");
@@ -6526,7 +7277,7 @@ program.command("mcp").description("Install recordings MCP server into Claude Co
         const configPath = pathJoin2(home, ".gemini", "settings.json");
         let config = {};
         if (fileExists(configPath)) {
-          config = JSON.parse(readFileSync5(configPath, "utf-8"));
+          config = JSON.parse(readFileSync6(configPath, "utf-8"));
         }
         const servers = config["mcpServers"] || {};
         if (opts.uninstall) {
@@ -6714,7 +7465,7 @@ function findPackageRoot() {
     const packagePath = pathJoin(current, "package.json");
     if (existsSync8(packagePath)) {
       try {
-        const pkg = JSON.parse(readFileSync4(packagePath, "utf8"));
+        const pkg = JSON.parse(readFileSync5(packagePath, "utf8"));
         if (pkg.name === "@hasna/recordings") {
           return current;
         }