@hasna/switcher 0.1.3 → 0.1.4

package/README.md

@@ -4,7 +4,7 @@ title: "Switcher"
 type: "package-documentation"
 owner: "codex-fixer"
 created_at: "2026-09-05T12:50:21.698672Z"
-updated_at: "2026-09-06T15:23:09.568156+00:00"
+updated_at: "2026-09-07T06:18:32.384233+00:00"
 status: "active"
 source_task: "01a07181-ca8d-70c1-99a2-b276dc5770f3"
 ---
@@ -69,18 +69,27 @@ An interactive terminal can choose or search the catalog when `--model` is omitt
 
 When no remote API configuration is present, each CLI invocation starts an authenticated loopback API on an allocated port, stores SQLite data in `~/.hasna/switcher`, and closes its own listener on completion. Its random operator key remains in memory. Use `HASNA_SWITCHER_HOME` to choose another owner-only home, `HASNA_SWITCHER_SQLITE_PATH` for an explicit database, or `HASNA_SWITCHER_DATABASE_URL` for PostgreSQL. API and SDK data access remains HTTP.
 
-If either remote API variable is configured, both `HASNA_SWITCHER_API_URL` and `HASNA_SWITCHER_API_KEY` are required. An unreachable or misconfigured remote API fails; it never selects a local database instead. The SDK always requires an explicitly configured API.
+Remote API configuration is resolved through Contracts, including canonical credential stores and the default gateway URL. Invalid, unavailable or unauthorized remote services fail without opening local SQLite.
 
 The registry contains DeepSeek, OpenRouter, Anthropic, OpenAI, xAI, Ollama, LM Studio, Groq, Cerebras, Mistral, Together AI, Fireworks, Moonshot/Kimi, DashScope, Z.AI, MiniMax, SiliconFlow, and generic protocol entries. `switcher providers presets ID` exposes documented routes, aliases and limitations; this is not a claim that every combination has passed live tests. Remaining adapters and acceptance gates are tracked in [TODOS.md](TODOS.md).
 
+## Canonical API configuration
+
+The CLI, `clientFromEnv()` SDK helper and standalone MCP client resolve Switcher API URL/key through `@hasna/contracts/client`, following the same shared convention as Conversations. A key alone selects `https://api.hasna.com/switcher`; `HASNA_SWITCHER_API_URL` selects a self-hosted endpoint. The `SWITCHER_API_URL` and `SWITCHER_API_KEY` aliases are supported. Deliberate overrides/profile selections take precedence; otherwise the resolver reads macOS Keychain, canonical disk configuration and then environment. A live client rereads credentials before each request and refuses an authority change until rebuilt.
+
+The canonical file is `~/.hasna/switcher/config/credentials` (owner-only mode 0600), using assignments named `HASNA_SWITCHER_API_URL` and `HASNA_SWITCHER_API_KEY`. Provision actual values through your approved secret manager. macOS Keychain uses service `hasna.credentials.switcher.api-key` and optional `api-url`, with account `HASNA_STATION` or the short hostname. Provider keys remain in the provider's vault or secure store; this file authenticates the Switcher API only.
+
+`HASNA_HOME` replaces `~/.hasna`; `HASNA_CONFIG_HOME` places credentials at `<root>/switcher/credentials` and `<root>/secrets/credentials`. These shared overrides must be absolute and nonblank. `HASNA_PROFILE` selects `credentials-<profile>`; API authority stays in the common credentials file. `HASNA_SWITCHER_HOME` changes Switcher's local database, bindings and launch state only, and does not relocate shared credentials. `HOME` is respected by both paths.
+
+Configured but missing, unsafe, conflicting or inaccessible remote credentials fail before local data is opened. Only complete absence of Switcher remote configuration retains the user-authorized automatic local API. The owned local API uses a random in-memory key. Server-side authentication remains configured separately through `HASNA_SWITCHER_API_KEY` on `switcher-serve`.
+
 ## Credential bindings
 
-Bind an existing vault key once, then launch without an external wrapper. Use your vault's URL and the installed `secrets` CLI. On macOS, `--vault-account` selects the operator's `hasna.credentials.secrets.api-key` Keychain item. Without that option, inject `HASNA_SECRETS_API_KEY` for each process.
+Bind an existing vault key once, then launch without an external wrapper. New bindings use the installed `secrets` CLI and resolve its operator key and API URL through `@hasna/contracts/client`. A configured Keychain item or canonical `~/.hasna/secrets/config/credentials` supplies the operator without shell exports. The default Secrets API URL is `https://api.hasna.com/secrets`; `--vault-url` can select a custom vault but must agree with any configured Secrets authority.
 
 ```sh
 switcher credentials bind deepseek \
-  --vault-key providers/deepseek/live/api_key --vault-url https://vault.example \
-  --vault-account my-station
+  --vault-key providers/deepseek/live/api_key
 switcher credentials check deepseek
 switcher launch claude --provider deepseek --model deepseek-v4-pro
 ```
@@ -91,7 +100,7 @@ For provider keys already stored in macOS Keychain, use `--keychain-service SERV
 
 `credentials list` displays bindings; `credentials remove PRESET_OR_REFERENCE` removes only the locator. Replacement requires explicit removal. Custom credential references require `--origin URL` (repeatable); preset bindings authorize their documented origins by default. `credentials check` reports availability, length and hash, not successful provider authentication. Provider credentials needed by a remote API's catalog discovery must still be configured on that server independently.
 
-On Linux, use a vault binding without `--vault-account` and have your approved secret manager inject `HASNA_SECRETS_API_KEY` into each Switcher process. The binding records the vault URL and key locator; it stores no credential value. Alternatively, let the authenticated `secrets` CLI inject a provider credential for one command:
+Explicit `--vault-account ACCOUNT` pins one macOS Keychain account and requires `--vault-url`; it never falls back when that account is missing or locked. `--vault-operator env` preserves the per-process `HASNA_SECRETS_API_KEY` mode and also requires `--vault-url`. Existing bindings keep their original operator mode. To adopt canonical resolution for an old binding, explicitly remove and rebind its same provider key reference. A Secrets operator cannot bootstrap itself through `HASNA_SECRETS_API_KEY_REF`; use a literal operator from its canonical store or explicit override. On Linux the shared resolver reads the owner-only canonical credentials file or process environment. The binding stores only the locator and optional vault authority. Alternatively, let the authenticated `secrets` CLI inject a provider credential for one command:
 
 ```sh
 secrets exec providers/deepseek/live/api_key --as DEEPSEEK_API_KEY -- \

package/dist/cli/index.js

@@ -499,7 +499,7 @@ function canonicalPolicyJSON(value) {
 }
 
 // src/domain.ts
-var VERSION = "0.1.3";
+var VERSION = "0.1.4";
 var harnessSchema = z3.enum(["claude", "codex", "grok", "opencode", "opencode2", "pi", "omp", "dsh", "cline", "hermes", "prime-agent", "gemini", "aider", "kilo"]);
 var protocolSchema = z3.enum(["anthropic-messages", "openai-responses", "openai-chat", "gemini-generate-content"]);
 var idSchema = z3.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,79}$/);
@@ -1033,7 +1033,7 @@ async function boundedJson(response, maxBytes = MAX_BYTES) {
 }
 
 // src/sdk.ts
-import { resolveCredential } from "@hasna/contracts/client";
+import { createClientTransport } from "@hasna/contracts/client";
 
 // src/presets.ts
 var route = (protocol, baseUrl, options = {}) => ({
@@ -1206,6 +1206,7 @@ function apiError(status, data, apiKey) {
 
 class SwitcherClient {
   options;
+  transport;
   baseUrl;
   constructor(options) {
     this.baseUrl = endpoint(options.baseUrl).replace(/\/v1$/, "");
@@ -1213,9 +1214,50 @@ class SwitcherClient {
       throw new Error("Switcher API key is required.");
     this.options = { ...options };
   }
+  static fromEnvironment(env = process.env, options = {}) {
+    const shared = createClientTransport("switcher", env, {
+      credentials: options.credentials,
+      timeoutMs: options.timeoutMs ?? 120000,
+      retry: false,
+      fetchImpl: async (input, init) => {
+        const address = String(input).replace(/\/v1\/(health|ready|version)$/, "/$1");
+        const key = new Headers(init?.headers).get("x-api-key") ?? "";
+        let response;
+        try {
+          response = await (options.fetch ?? fetch)(address, init);
+        } catch {
+          throw new SwitcherError(0, "connection_failed", "Switcher API request failed; check endpoint and service availability.");
+        }
+        if (response.status === 401 || response.status === 403) {
+          await response.body?.cancel().catch(() => {});
+          throw new SwitcherError(response.status, "api_error", `Switcher API returned HTTP ${response.status}. Check the configured credential; no alternate identity was selected.`);
+        }
+        let data;
+        try {
+          data = await boundedJson(response);
+        } catch {
+          throw new SwitcherError(response.status, "invalid_response", "Switcher API returned invalid JSON.");
+        }
+        if (!response.ok)
+          throw apiError(response.status, data, key);
+        return Response.json(data);
+      }
+    });
+    const client = new SwitcherClient({ baseUrl: shared.resolution.baseUrl, apiKey: () => {
+      throw new Error("Shared credential transport was not invoked.");
+    } });
+    client.transport = shared.client;
+    return client;
+  }
   async request(method, path, body, options = {}) {
     if (!/^\/v1\/[a-zA-Z0-9/?&=._%+-]+$/.test(path) && !["/health", "/ready", "/version"].includes(path) || path.includes(".."))
       throw new Error("Invalid API path.");
+    if (this.transport)
+      return this.transport.request(method, path.startsWith("/v1/") ? path.slice(3) : path, body, {
+        idempotencyKey: method === "GET" ? undefined : options.idempotencyKey ?? crypto.randomUUID(),
+        headers: options.version === undefined ? undefined : { "if-match": String(options.version) },
+        retry: false
+      });
     const apiKey = typeof this.options.apiKey === "function" ? this.options.apiKey() : this.options.apiKey;
     if (!apiKey || /[\r\n]/.test(apiKey))
       throw new Error("Switcher API key is required.");
@@ -1312,11 +1354,8 @@ class SwitcherClient {
     return this.request("PATCH", `/v1/runs/${encodeURIComponent(id)}`, input, { version, idempotencyKey });
   }
 }
-function clientFromEnv(env = process.env) {
-  const credential = () => resolveCredential("switcher", Object.fromEntries(Object.entries(env).filter(([name]) => name === "HASNA_SWITCHER_API_KEY")), { keychain: { enabled: false } })?.apiKey ?? "";
-  if (!env.HASNA_SWITCHER_API_URL || !credential())
-    throw new Error("Set HASNA_SWITCHER_API_URL and HASNA_SWITCHER_API_KEY; no local database fallback is available.");
-  return new SwitcherClient({ baseUrl: env.HASNA_SWITCHER_API_URL, apiKey: credential });
+function clientFromEnv(env = process.env, options = {}) {
+  return SwitcherClient.fromEnvironment(env, options);
 }
 
 // src/opencode-model-policy.ts
@@ -1388,7 +1427,7 @@ function openCodeInvocationModel(args, policy, defaultAgent) {
 
 // src/gemini-config.ts
 import { readFile, writeFile as writeFile3, lstat as lstat2, readdir as readdir2, symlink, realpath as realpath2 } from "fs/promises";
-import { join as join4, dirname as dirname3, resolve as resolve4, isAbsolute as isAbsolute3, relative as relative2, sep } from "path";
+import { join as join4, dirname as dirname3, resolve as resolve4, isAbsolute as isAbsolute4, relative as relative2, sep } from "path";
 import { homedir as homedir3 } from "os";
 import { parseTree as parseTree2, getNodeValue } from "jsonc-parser";
 
@@ -1396,7 +1435,7 @@ import { parseTree as parseTree2, getNodeValue } from "jsonc-parser";
 import { randomBytes } from "crypto";
 import { mkdir as mkdir4, lstat } from "fs/promises";
 import { homedir as homedir2 } from "os";
-import { join as join3, resolve as resolve3 } from "path";
+import { isAbsolute as isAbsolute3, join as join3, resolve as resolve3 } from "path";
 
 // src/store.ts
 var {SQL } = globalThis.Bun;
@@ -1638,7 +1677,7 @@ async function fetchCatalogPage(url, headers, deadline) {
     await waitForCatalogRetry(delay ?? 100 * 2 ** retry, deadline);
   }
 }
-async function discover(provider, env = process.env, resolveCredential2) {
+async function discover(provider, env = process.env, resolveCredential) {
   const refreshedAt = new Date().toISOString();
   if (provider.manualModels.length)
     return { models: provider.manualModels, source: "manual", refreshedAt };
@@ -1658,7 +1697,7 @@ async function discover(provider, env = process.env, resolveCredential2) {
   if (authStyle !== "none" && credentialEnv) {
     if (url.origin !== new URL(provider.baseUrl).origin && !provider.catalogCredentialEnv)
       throw new Fault(422, "catalog_credential_authority", "A different catalog origin requires an explicit catalog credential reference or catalogAuthStyle: none.");
-    const credential = resolveCredential2 ? await resolveCredential2({ ...provider, baseUrl: provider.catalogBaseUrl ?? provider.baseUrl, credentialEnv }) : env[credentialEnv];
+    const credential = resolveCredential ? await resolveCredential({ ...provider, baseUrl: provider.catalogBaseUrl ?? provider.baseUrl, credentialEnv }) : env[credentialEnv];
     if (!credential)
       throw new Fault(422, "credential_missing", "Provider credential environment variable is not available on the server.");
     if (/[\r\n]/.test(credential))
@@ -1985,7 +2024,7 @@ var openapi_default = {
   openapi: "3.0.3",
   info: {
     title: "Switcher API",
-    version: "0.1.3",
+    version: "0.1.4",
     description: "Authenticated provider/profile/catalog control plane. Launches run locally; the API never returns provider credentials."
   },
   security: [
@@ -5460,7 +5499,7 @@ var openapi_default = {
 // src/service.ts
 var snapshot = (profile, provider, catalog) => createHash3("sha256").update(JSON.stringify([profile, provider, { models: catalog.models, source: catalog.source }])).digest("hex");
 var hash = (s) => createHash3("sha256").update(s).digest();
-function createHandler(store, apiKey, providerEnv = process.env, resolveCredential2) {
+function createHandler(store, apiKey, providerEnv = process.env, resolveCredential) {
   if (!apiKey || apiKey.length < 24)
     throw new Fault(500, "auth_config", "Set HASNA_SWITCHER_API_KEY to a random token of at least 24 characters.");
   const expected = hash(`Bearer ${apiKey}`);
@@ -5542,7 +5581,7 @@ function createHandler(store, apiKey, providerEnv = process.env, resolveCredenti
       if (resource === "providers" && id2 && parts[3] === "refresh" && parts.length === 4 && request.method === "POST") {
         parse2(z4.object({}).strict(), body);
         const provider = await store.get("providers", id2);
-        refreshed = { provider, catalog: await discover(provider, providerEnv, resolveCredential2) };
+        refreshed = { provider, catalog: await discover(provider, providerEnv, resolveCredential) };
       }
       const result = await store.mutate(key, fingerprint, async (db) => {
         if ((resource === "providers" || resource === "profiles") && parts.length <= 3) {
@@ -5689,8 +5728,11 @@ async function startServer(options) {
 }
 
 // src/runtime.ts
+import { resolveCredential as resolveClientCredential, clientTransportEnvKeys, appConfigDiskValue, keychainConfigValue } from "@hasna/contracts/client";
 function switcherHome(env = process.env) {
-  return resolve3(env.HASNA_SWITCHER_HOME ?? join3(homedir2(), ".hasna", "switcher"));
+  const override = env.HASNA_HOME?.trim();
+  const root = override && isAbsolute3(override) ? override : join3(env.HOME?.trim() || homedir2(), ".hasna");
+  return resolve3(env.HASNA_SWITCHER_HOME ?? join3(root, "switcher"));
 }
 async function privateDirectory(path) {
   await mkdir4(path, { recursive: true, mode: 448 });
@@ -5700,9 +5742,12 @@ async function privateDirectory(path) {
   if (process.platform !== "win32" && ((info.mode & 63) !== 0 || info.uid !== process.getuid?.()))
     throw new Fault(500, "home_permissions", "Switcher data directory must be owned by this user and accessible only to its owner (mode 0700).");
 }
-async function openCliRuntime(env = process.env, resolveCredential2) {
+async function openCliRuntime(env = process.env, resolveCredential) {
   const providerEnv = Object.fromEntries(Object.entries(env).filter(([name]) => name.startsWith("SWITCHER_PROVIDER_")));
-  if (Object.hasOwn(env, "HASNA_SWITCHER_API_URL") || Object.hasOwn(env, "HASNA_SWITCHER_API_KEY")) {
+  const keys = clientTransportEnvKeys("switcher");
+  const credential = resolveClientCredential("switcher", env);
+  const configured = credential || keys.apiUrlKeys.some((name) => env[name] !== undefined) || keychainConfigValue("switcher", env) || appConfigDiskValue("switcher", env, keys.apiUrlKeys);
+  if (configured) {
     return { client: clientFromEnv(env), mode: "remote", providerEnv, close: async () => {} };
   }
   const home = switcherHome(env);
@@ -5714,7 +5759,7 @@ async function openCliRuntime(env = process.env, resolveCredential2) {
     databaseUrl: env.HASNA_SWITCHER_DATABASE_URL,
     sqlitePath: env.HASNA_SWITCHER_SQLITE_PATH ?? (env.HASNA_SWITCHER_DATABASE_URL ? undefined : join3(home, "switcher.db")),
     providerEnv,
-    resolveCredential: resolveCredential2
+    resolveCredential
   });
   return { client: new SwitcherClient({ baseUrl: service.url, apiKey }), mode: "local", providerEnv, close: service.close };
 }
@@ -5860,7 +5905,7 @@ function originalPaths(value, home) {
 }
 async function validateGeminiConfiguration(cwd, env = process.env) {
   const home = env.GEMINI_CLI_HOME ?? env.HOME ?? homedir3();
-  if (!isAbsolute3(home))
+  if (!isAbsolute4(home))
     throw new Error("Gemini requires an absolute native home.");
   const systemPath = env.GEMINI_CLI_SYSTEM_SETTINGS_PATH ?? (process.platform === "darwin" ? "/Library/Application Support/GeminiCli/settings.json" : process.platform === "win32" ? "C:\\ProgramData\\gemini-cli\\settings.json" : "/etc/gemini-cli/settings.json");
   const defaultsPath = env.GEMINI_CLI_SYSTEM_DEFAULTS_PATH ?? join4(dirname3(systemPath), "system-defaults.json");
@@ -5924,7 +5969,7 @@ async function snapshotContext(sourceDir, destinationDir, names) {
       if (code.some(([a, b]) => start >= a && start < b))
         continue;
       const imported = resolve4(dirname3(source), match[2]), actual = await realpath2(imported).catch(() => imported), within = relative2(root, actual);
-      if (within === ".." || within.startsWith(".." + sep) || isAbsolute3(within))
+      if (within === ".." || within.startsWith(".." + sep) || isAbsolute4(within))
         throw new Error("Gemini global context imports outside the original context directory require a supported explicit context location.");
       const target = files.get(imported) ?? join4(importsDir, `${files.size}.md`);
       await privateDirectory(importsDir);
@@ -6464,7 +6509,7 @@ function createInferenceGateway(input) {
 
 // src/codex-model-policy.ts
 import { mkdir as mkdir5, readFile as readFile2, realpath as realpath3, stat as stat3, writeFile as writeFile4 } from "fs/promises";
-import { dirname as dirname4, isAbsolute as isAbsolute4, join as join5, resolve as resolve5 } from "path";
+import { dirname as dirname4, isAbsolute as isAbsolute5, join as join5, resolve as resolve5 } from "path";
 import { execFileSync as execFileSync2 } from "child_process";
 import { createHash as createHash6 } from "crypto";
 var dict = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
@@ -6484,7 +6529,7 @@ function codexAgentsFromEffectiveConfig(config, trustedProject = true, baseDir)
     const rawConfigFile = value.config_file;
     if (rawConfigFile !== undefined && typeof rawConfigFile !== "string")
       throw new Error(`Codex agents.${name}.config_file must be a string.`);
-    const configFile = rawConfigFile === undefined ? undefined : isAbsolute4(rawConfigFile) ? rawConfigFile : baseDir ? resolve5(baseDir, rawConfigFile) : undefined;
+    const configFile = rawConfigFile === undefined ? undefined : isAbsolute5(rawConfigFile) ? rawConfigFile : baseDir ? resolve5(baseDir, rawConfigFile) : undefined;
     if (rawConfigFile !== undefined && !configFile)
       throw new Error(`Codex agents.${name}.config_file must be absolute after precedence resolution.`);
     const definition = { trusted: trustedProject, config_file: configFile };
@@ -6646,7 +6691,7 @@ async function prepareCodexModelPolicy(input) {
   const global = await readConfig(globalPath) ?? {};
   const projects = dict(global.projects) ? global.projects : {};
   const markers = global.project_root_markers ?? [".git"];
-  if (!Array.isArray(markers) || markers.some((m) => typeof m !== "string" || isAbsolute4(m) || m.includes("..")))
+  if (!Array.isArray(markers) || markers.some((m) => typeof m !== "string" || isAbsolute5(m) || m.includes("..")))
     throw new Error("Unsupported Codex project root markers.");
   const ancestorDirs = [];
   for (let dir = cwd;; dir = dirname4(dir)) {
@@ -6715,7 +6760,7 @@ async function prepareCodexModelPolicy(input) {
   return { ...result, agentConfigPaths: await writeCodexAgentOverrides(result, input.stateDir), configPaths: loaded };
 }
 async function readCodexAgentConfig(path) {
-  if (!isAbsolute4(path))
+  if (!isAbsolute5(path))
     throw new Error("Codex agent config_file must be absolute before launch.");
   const canonical = await realpath3(path);
   const info = await stat3(canonical);
@@ -6731,7 +6776,7 @@ async function readCodexAgentConfig(path) {
 
 // src/harnesses.ts
 import { access as access2, mkdir as mkdir10, readFile as readFile4, readdir as readdir4, writeFile as writeFile10, rm as rm2 } from "fs/promises";
-import { basename as basename2, dirname as dirname7, join as join11, isAbsolute as isAbsolute9, resolve as resolve8 } from "path";
+import { basename as basename2, dirname as dirname7, join as join11, isAbsolute as isAbsolute10, resolve as resolve8 } from "path";
 import { homedir as homedir6, tmpdir } from "os";
 import { createHash as createHash8, randomUUID as randomUUID4, timingSafeEqual as timingSafeEqual5 } from "crypto";
 import { execFile } from "child_process";
@@ -6741,7 +6786,7 @@ import { createConnection } from "net";
 // src/aider-config.ts
 import { readFile as readFile3, writeFile as writeFile5, lstat as lstat3, copyFile, rename, realpath as realpath4, access } from "fs/promises";
 import { constants as constants2 } from "fs";
-import { dirname as dirname5, basename, join as join6, resolve as resolve6, isAbsolute as isAbsolute5 } from "path";
+import { dirname as dirname5, basename, join as join6, resolve as resolve6, isAbsolute as isAbsolute6 } from "path";
 import { homedir as homedir4 } from "os";
 import { parseDocument as parseDocument2 } from "yaml";
 var KEY2 = "SWITCHER_HARNESS_API_KEY";
@@ -6800,7 +6845,7 @@ var startup = `yes-always gui browser upgrade install-main-branch just-check-upd
 var safeParameters = new Set(`max_tokens temperature top_p top_k min_p stop seed reasoning_effort thinking`.split(" "));
 var expandHome = (path, home) => path === "~" ? home : path.startsWith("~/") ? join6(home, path.slice(2)) : path;
 async function validateAiderConfiguration(cwd, args = [], home = process.env.HOME ?? homedir4()) {
-  if (!isAbsolute5(home))
+  if (!isAbsolute6(home))
     throw new Error("Aider requires an absolute HOME to preserve native instruction paths.");
   const parsed = aiderArguments(args), cwdRoot = await gitRoot(cwd);
   const roots = new Set([resolve6(home), ...cwdRoot ? [cwdRoot] : [], resolve6(cwd)]);
@@ -7036,7 +7081,7 @@ function validateGrokResume(args) {
 // src/cline-backend.ts
 import { mkdir as mkdir6, writeFile as writeFile6 } from "fs/promises";
 import { randomUUID as randomUUID2 } from "crypto";
-import { isAbsolute as isAbsolute6, join as join7 } from "path";
+import { isAbsolute as isAbsolute7, join as join7 } from "path";
 var ENV_BY_PROTOCOL = {
   "anthropic-messages": "ANTHROPIC_API_KEY",
   "openai-responses": "OPENAI_API_KEY",
@@ -7082,7 +7127,7 @@ async function prepareClineLaunch(input) {
     throw new Error(`Cline ${input.protocol} uses ${mapping.authStyle} authentication; use a provider with the native Cline auth contract.`);
   if (input.credential && /[\r\n]/.test(input.credential))
     throw new Error("Provider credential contains invalid header characters.");
-  if (!isAbsolute6(input.stateDir) || !isAbsolute6(input.cwd))
+  if (!isAbsolute7(input.stateDir) || !isAbsolute7(input.cwd))
     throw new Error("Launch state and working directories must be absolute.");
   const dataDir = join7(input.stateDir, "cline-data");
   const sessionDir = input.sessionDir ?? join7(dataDir, "sessions");
@@ -7164,7 +7209,7 @@ async function prepareClineLaunch(input) {
 // src/opencode2-config.ts
 import { mkdir as mkdir7, open as open2, realpath as realpath5, readdir as readdir3, stat as stat4, writeFile as writeFile7 } from "fs/promises";
 import { constants as constants3 } from "fs";
-import { dirname as dirname6, isAbsolute as isAbsolute7, join as join8, relative as relative4, resolve as resolve7 } from "path";
+import { dirname as dirname6, isAbsolute as isAbsolute8, join as join8, relative as relative4, resolve as resolve7 } from "path";
 import { homedir as homedir5 } from "os";
 import { randomUUID as randomUUID3 } from "crypto";
 import { Database as Database2 } from "bun:sqlite";
@@ -7180,7 +7225,7 @@ var maxTotalBytes2 = 8 * 1024 * 1024;
 var maxFiles2 = 256;
 var inside2 = (root, path) => {
   const rel = relative4(root, path);
-  return rel === "" || !isAbsolute7(rel) && rel !== ".." && !rel.startsWith("../");
+  return rel === "" || !isAbsolute8(rel) && rel !== ".." && !rel.startsWith("../");
 };
 var action = (value) => ({ bash: "shell", task: "subagent", write: "edit", patch: "edit" })[value] ?? value;
 function invalid2(path, field) {
@@ -7301,7 +7346,7 @@ async function checkRemoteConfiguration(dataHome) {
 }
 async function isolateOpenCode2(cwd, stateDir, providerID, env = process.env) {
   for (const name of ["HOME", "XDG_CONFIG_HOME", "XDG_DATA_HOME", "OPENCODE_CONFIG_DIR"])
-    if (env[name] && !isAbsolute7(env[name]))
+    if (env[name] && !isAbsolute8(env[name]))
       throw new Error(`OpenCode 2 requires an absolute ${name} to preserve native configuration authority.`);
   const home = resolve7(env.HOME || homedir5());
   const configRoot = resolve7(env.OPENCODE_CONFIG_DIR || join8(env.XDG_CONFIG_HOME || join8(home, ".config"), "opencode"));
@@ -7723,7 +7768,7 @@ function compileHermesModelPolicy(currentModel, roles2, baseUrl, apiMode = "chat
 // src/hermes-backend.ts
 import { createHash as createHash7, timingSafeEqual as timingSafeEqual4 } from "crypto";
 import { mkdir as mkdir9, symlink as symlink2, writeFile as writeFile9 } from "fs/promises";
-import { isAbsolute as isAbsolute8, join as join10 } from "path";
+import { isAbsolute as isAbsolute9, join as join10 } from "path";
 var hermesApiMode = {
   "anthropic-messages": "anthropic_messages",
   "openai-responses": "codex_responses",
@@ -7899,7 +7944,7 @@ function createHermesBridge(input) {
   };
 }
 async function prepareHermesLaunch(input) {
-  if (!isAbsolute8(input.stateDir) || !isAbsolute8(input.cwd))
+  if (!isAbsolute9(input.stateDir) || !isAbsolute9(input.cwd))
     throw new Error("Launch state and working directories must be absolute.");
   if (input.protocol !== "anthropic-messages" && input.protocol !== "openai-responses" && input.protocol !== "openai-chat")
     throw new Error("Hermes does not support this provider protocol.");
@@ -8849,7 +8894,7 @@ async function prepareNativeLaunch(input, providerBaseUrl = input.providerBaseUr
   if (!compatible(input.harness, input.protocol))
     throw new Error("Harness and provider protocol are incompatible.");
   validateHarnessVersion(input.harness, input.version);
-  if (!isAbsolute9(input.stateDir) || !isAbsolute9(input.cwd))
+  if (!isAbsolute10(input.stateDir) || !isAbsolute10(input.cwd))
     throw new Error("Launch state and working directories must be absolute.");
   if (!input.models.length || !input.models.some((m) => m.id === input.model))
     throw new Error("Selected model is missing from the launch catalog.");
@@ -8957,7 +9002,7 @@ async function prepareNativeLaunch(input, providerBaseUrl = input.providerBaseUr
     const api = { "anthropic-messages": "anthropic-messages", "openai-responses": "openai-responses", "openai-chat": "openai-completions" }[input.protocol];
     const home = join11(input.stateDir, "dsh-home");
     const sessionDir = input.sessionDir ?? join11(input.stateDir, "dsh-state");
-    if (!isAbsolute9(sessionDir))
+    if (!isAbsolute10(sessionDir))
       throw new Error("DSH session directory must be absolute.");
     await mkdir10(home, { recursive: true, mode: 448 });
     await mkdir10(sessionDir, { recursive: true, mode: 448 });
@@ -9218,7 +9263,7 @@ async function prepareHarnessLaunch(input) {
   validateHarnessVersion(input.harness, input.version);
   if (!compatible(input.harness, input.protocol))
     throw new Error("Harness and provider protocol are incompatible.");
-  if (!isAbsolute9(input.stateDir) || !isAbsolute9(input.cwd))
+  if (!isAbsolute10(input.stateDir) || !isAbsolute10(input.cwd))
     throw new Error("Launch state and working directories must be absolute.");
   const compiledPolicy = compileModelPolicy(input.model, input.models, input.modelPolicy);
   const nativePolicy = compileNativeModelPolicy({ harness: input.harness, mainModel: input.model, roles: compiledPolicy.roles, version: input.version });
@@ -9248,9 +9293,9 @@ async function prepareHarnessLaunch(input) {
 }
 
 // src/ori-model-policy.ts
-import { isAbsolute as isAbsolute10 } from "path";
+import { isAbsolute as isAbsolute11 } from "path";
 function prepareOriModelPolicy(target, prepared) {
-  if (!isAbsolute10(prepared.executable) || /[\0\r\n]/.test(prepared.executable))
+  if (!isAbsolute11(prepared.executable) || /[\0\r\n]/.test(prepared.executable))
     throw new Error("Ori requires an absolute verified native executable.");
   const entries = Object.entries(prepared.env);
   if (entries.some(([key]) => !/^[A-Z_][A-Z0-9_]*$/.test(key)))
@@ -10222,19 +10267,20 @@ async function ensureLaunchProfile(client, provider, harness, model3, modelPolic
 import { z as z6 } from "zod";
 import { constants as constants5 } from "fs";
 import { open as open3, readdir as readdir5, unlink, link, lstat as lstat4, access as access3, stat as stat5, realpath as realpath6, readlink } from "fs/promises";
-import { join as join13, isAbsolute as isAbsolute11, dirname as dirname8, parse as pathParts, resolve as resolvePath, sep as sep2 } from "path";
+import { join as join13, isAbsolute as isAbsolute12, dirname as dirname8, parse as pathParts, resolve as resolvePath, sep as sep2 } from "path";
 import { createHash as createHash10, randomUUID as randomUUID5 } from "crypto";
 import { execFile as execFile3, spawn as spawn2 } from "child_process";
 import { promisify as promisify3 } from "util";
-import { resolveCredential as resolveCredential2 } from "@hasna/contracts/client";
+import { resolveCredential, resolveClientTransport, toV1BaseUrl, clientTransportEnvKeys as clientTransportEnvKeys2, keychainConfigValue as keychainConfigValue2, appConfigDiskValue as appConfigDiskValue2 } from "@hasna/contracts/client";
 var execute2 = promisify3(execFile3);
 var reference = z6.string().regex(/^SWITCHER_PROVIDER_[A-Z0-9_]+$/).max(120);
 var item = z6.string().min(1).max(500).regex(/^[^\x00-\x1f\x7f]+$/);
 var vaultKey = z6.string().max(500).regex(/^[A-Za-z0-9][A-Za-z0-9_.-]*(?:\/[A-Za-z0-9][A-Za-z0-9_.-]*)*$/, "Use a vault key path, not an option or secret value");
 var keychain = z6.object({ kind: z6.literal("keychain"), service: item, account: item }).strict();
 var operator = z6.discriminatedUnion("kind", [
+  z6.object({ kind: z6.literal("contracts") }).strict(),
   z6.object({ kind: z6.literal("env") }).strict(),
-  z6.object({ kind: z6.literal("keychain"), account: item }).strict()
+  z6.object({ kind: z6.literal("keychain"), account: item.refine((value) => value.trim().length > 0 && value === value.trim(), "Vault account must be nonblank without surrounding whitespace") }).strict()
 ]);
 var origin = z6.string().transform((value) => new URL(endpoint(value)).origin);
 var credentialBindingSchema = z6.object({
@@ -10244,11 +10290,14 @@ var credentialBindingSchema = z6.object({
   source: z6.discriminatedUnion("kind", [keychain, z6.object({
     kind: z6.literal("vault"),
     key: vaultKey,
-    url: z6.string().max(2000).transform(endpoint),
-    executable: z6.string().max(4096).regex(/^[^\x00-\x1f\x7f]+$/).refine(isAbsolute11, "Secrets executable must be an absolute path"),
+    url: z6.string().max(2000).transform(endpoint).optional(),
+    executable: z6.string().max(4096).regex(/^[^\x00-\x1f\x7f]+$/).refine(isAbsolute12, "Secrets executable must be an absolute path"),
     operator
   }).strict()])
-}).strict();
+}).strict().superRefine((binding, ctx) => {
+  if (binding.source.kind === "vault" && binding.source.operator.kind !== "contracts" && !binding.source.url)
+    ctx.addIssue({ code: "custom", path: ["source", "url"], message: "An explicit env or Keychain operator binding requires a vault URL." });
+});
 var fingerprint = (binding) => createHash10("sha256").update(JSON.stringify(binding)).digest("hex");
 
 class CredentialBindings {
@@ -10489,20 +10538,49 @@ class CredentialInterrupted extends CommandInterrupted {
     super(exitCode, "Credential lookup was interrupted; no harness was started.");
   }
 }
-function vaultEnvironment(binding, env) {
+async function vaultEnvironment(binding, env, options = {}) {
   if (binding.source.kind !== "vault")
     throw new Fault(500, "credential_resolution", "Unexpected credential source.");
-  let credential;
+  const source = binding.source;
+  let credential, url = source.url;
   try {
-    credential = binding.source.operator.kind === "keychain" ? resolveCredential2("secrets", { HASNA_STATION: binding.source.operator.account }, { keychain: { enabled: true } }) : resolveCredential2("secrets", Object.fromEntries(Object.entries(env).filter(([name]) => name === "HASNA_SECRETS_API_KEY")), { keychain: { enabled: false } });
-  } catch {
-    throw new Fault(422, "vault_operator_unavailable", "The configured vault operator credential is inaccessible; no alternate account was selected.");
+    if (source.operator.kind === "contracts") {
+      const pair = () => {
+        const keys = clientTransportEnvKeys2("secrets");
+        const configuredUrl = keys.apiUrlKeys.map((name) => env[name]).find((value) => value !== undefined) ?? keychainConfigValue2("secrets", env, options.keychain)?.value ?? appConfigDiskValue2("secrets", env, keys.apiUrlKeys)?.value;
+        const resolution = resolveClientTransport("secrets", env, { credentials: options });
+        const key = resolveCredential("secrets", env, options);
+        if (key?.tier === "pointer")
+          throw new Fault(422, "vault_operator_pointer", "A Secrets operator cannot bootstrap itself through HASNA_SECRETS_API_KEY_REF. Configure its operator in Keychain, canonical config/credentials, or an explicit key override.");
+        if (!key?.apiKey || key.source !== resolution.apiKeySource || key.tier !== resolution.apiKeyTier)
+          throw new Fault(422, "vault_operator_changed", "The vault operator changed during resolution; no credential was sent. Retry after configuration is stable.");
+        const boundUrl = source.url ? toV1BaseUrl(source.url) : resolution.baseUrl;
+        if (resolution.apiUrlSource !== "default" && boundUrl !== resolution.baseUrl)
+          throw new Fault(422, "vault_operator_authority", "The binding vault URL conflicts with the canonical Secrets API URL; no credential was sent.");
+        if (configuredUrl !== undefined && toV1BaseUrl(configuredUrl) !== resolution.baseUrl)
+          throw new Fault(422, "vault_operator_changed", "The vault authority changed during resolution; no credential was sent.");
+        return { key, url: configuredUrl?.trim() ?? source.url ?? boundUrl.replace(/\/v1$/, "") };
+      };
+      const first = pair(), second = pair();
+      if (first.key.apiKey !== second.key.apiKey || first.key.source !== second.key.source || first.key.tier !== second.key.tier || first.url !== second.url)
+        throw new Fault(422, "vault_operator_changed", "The vault operator or authority changed during resolution; no credential was sent. Retry after configuration is stable.");
+      credential = second.key;
+      url = second.url;
+    } else {
+      credential = source.operator.kind === "keychain" ? resolveCredential("secrets", { HASNA_STATION: source.operator.account }, { keychain: { ...options.keychain, enabled: true } }) : resolveCredential("secrets", Object.fromEntries(Object.entries(env).filter(([name]) => name === "HASNA_SECRETS_API_KEY")), { keychain: { enabled: false } });
+    }
+  } catch (error) {
+    if (error instanceof Fault)
+      throw error;
+    const kind = error instanceof Error ? error.name : "";
+    const reason = kind === "CredentialFileUnsafeError" ? "unsafe canonical config/credentials file" : kind === "ClientTransportConfigurationError" ? "invalid or missing canonical API URL/key" : source.operator.kind === "keychain" ? "unavailable pinned Keychain account" : "credential selection refused by Contracts (Keychain, canonical file, profile, or environment)";
+    throw new Fault(422, "vault_operator_unavailable", `Cannot resolve the Secrets vault operator: ${reason}. Check the selected source in this terminal session; no alternate account was selected.`);
   }
   if (!credential?.apiKey)
-    throw new Fault(422, "vault_operator_missing", "Configure the vault operator Keychain account or inject HASNA_SECRETS_API_KEY for this process.");
-  const allowed = /^(PATH|HOME|USER|LOGNAME|SHELL|LANG|LC_[A-Z_]+|TMPDIR|TEMP|TMP|HASNA_SECRETS_HOME|HASNA_STATION)$/;
+    throw new Fault(422, "vault_operator_missing", "The selected vault operator has no credential. Use a canonical Contracts binding, restore its named Keychain account, or inject HASNA_SECRETS_API_KEY for an explicit env binding.");
+  const allowed = /^(PATH|HOME|USER|LOGNAME|SHELL|LANG|LC_[A-Z_]+|TMPDIR|TEMP|TMP|HASNA_HOME|HASNA_CONFIG_HOME|HASNA_SECRETS_HOME|HASNA_STATION)$/;
   const next = Object.fromEntries(Object.entries(env).filter(([name]) => allowed.test(name)));
-  next.HASNA_SECRETS_API_URL = binding.source.url;
+  next.HASNA_SECRETS_API_URL = url;
   next.HASNA_SECRETS_API_KEY = credential.apiKey;
   next.HASNA_SECRETS_API_KEY_OVERRIDE = credential.apiKey;
   if (binding.source.operator.kind === "keychain")
@@ -10515,7 +10593,7 @@ async function runVaultCommand(binding, args, env, delivery = {}, captureCheck =
   if (process.platform === "win32")
     throw new Fault(422, "vault_exec_unavailable", "Vault CLI bindings currently require POSIX process groups; use runtime environment injection on Windows.");
   const executable = await validateVaultExecutable(binding.source.executable);
-  const childEnv = { ...vaultEnvironment(binding, env), ...delivery };
+  const childEnv = { ...await vaultEnvironment(binding, env), ...delivery };
   return new Promise((resolveResult, reject2) => {
     const child = spawn2(executable, args, { env: childEnv, stdio: ["ignore", captureCheck ? "pipe" : "ignore", "ignore"], detached: true, shell: false });
     let failure;
@@ -10646,8 +10724,8 @@ var HELP = `switcher \u2014 launch a coding harness with a provider and its mode
                           [--ori-executable PATH] [--state-dir DIR]
                           [--timeout SECONDS] -- [native harness arguments]
   switcher runs list|get [ID]
-  switcher credentials bind PRESET --vault-key KEY --vault-url URL
-                            [--vault-cli PATH] [--vault-account ACCOUNT]
+  switcher credentials bind PRESET --vault-key KEY [--vault-url URL]
+                            [--vault-cli PATH] [--vault-account ACCOUNT | --vault-operator env]
   switcher credentials bind PRESET --keychain-service SERVICE --keychain-account ACCOUNT
   switcher credentials list|check|remove [PRESET_OR_REFERENCE]
   switcher doctor
@@ -10656,12 +10734,14 @@ HARNESS: claude, codex, grok, opencode, opencode2, pi, omp, dsh, cline, hermes,
 PROTOCOL: anthropic-messages, openai-responses, openai-chat, gemini-generate-content
 Without remote API configuration, the CLI owns a local authenticated API and
 stores data in ~/.hasna/switcher (override HASNA_SWITCHER_HOME).
-Set HASNA_SWITCHER_API_URL + HASNA_SWITCHER_API_KEY for a remote API.
+Remote API URL/key resolve through @hasna/contracts: overrides, Keychain,
+~/.hasna/switcher/config/credentials, then environment. A key alone uses the gateway.
 A configured remote API never falls back to local data.
 Provider credential references must start SWITCHER_PROVIDER_.
 Credential bindings contain references only. Custom destinations require --origin URL.
-Vault bindings use the installed secrets CLI; --vault-account reads its operator
-from macOS Keychain, otherwise HASNA_SECRETS_API_KEY must be injected per process.
+Vault bindings use the installed secrets CLI and its canonical Contracts URL/key
+by default. --vault-account pins a Keychain account; --vault-operator env requires
+per-process HASNA_SECRETS_API_KEY. Explicit operators also require --vault-url.
   --file accepts a JSON object including id; raw credentials are never accepted.
 Fireworks discovery requires --catalog-account-id (or an explicit --catalog-url).
 --json outputs machine-readable records (also the default for data commands).
@@ -10739,6 +10819,7 @@ async function main(args = process.argv.slice(2)) {
     "vault-url": { type: "string" },
     "vault-cli": { type: "string" },
     "vault-account": { type: "string" },
+    "vault-operator": { type: "string" },
     "keychain-service": { type: "string" },
     "keychain-account": { type: "string" },
     origin: { type: "string", multiple: true }
@@ -10753,7 +10834,7 @@ async function main(args = process.argv.slice(2)) {
     throw new Error("Unknown command. Run switcher --help.");
   const providerFlags = ["url", "protocol", "preset", "credential-env", "auth-style", "catalog-url", "catalog-format", "catalog-auth-style", "catalog-credential-env", "catalog-account-id", "models-path"];
   const provided = (names) => names.some((name) => values2[name] !== undefined);
-  const credentialFlags = ["vault-key", "vault-url", "vault-cli", "vault-account", "keychain-service", "keychain-account", "origin"];
+  const credentialFlags = ["vault-key", "vault-url", "vault-cli", "vault-account", "vault-operator", "keychain-service", "keychain-account", "origin"];
   const credentials = new CredentialResolver;
   if (command === "credentials") {
     const bindingFlags = [...credentialFlags, "credential-env"];
@@ -10775,16 +10856,20 @@ async function main(args = process.argv.slice(2)) {
     }
     if (action2 !== "bind" || !id2)
       throw new Fault(400, "invalid_request", "Use credentials bind PRESET, list, check PRESET_OR_REFERENCE, or remove PRESET_OR_REFERENCE.");
-    const hasVault = provided(["vault-key", "vault-url", "vault-cli", "vault-account"]);
+    const hasVault = provided(["vault-key", "vault-url", "vault-cli", "vault-account", "vault-operator"]);
     const hasKeychain = provided(["keychain-service", "keychain-account"]);
     if (hasVault === hasKeychain)
       throw new Fault(400, "conflicting_options", "Choose one credential source: vault or Keychain.");
+    if (values2["vault-operator"] !== undefined && !["contracts", "env"].includes(values2["vault-operator"]))
+      throw new Fault(400, "invalid_request", "Use --vault-operator contracts or env.");
+    if (values2["vault-account"] !== undefined && values2["vault-operator"] !== undefined)
+      throw new Fault(400, "conflicting_options", "Use either --vault-account or --vault-operator.");
     const source = hasVault ? {
       kind: "vault",
       key: values2["vault-key"],
       url: values2["vault-url"],
       executable: values2["vault-cli"] ?? Bun.which("secrets"),
-      operator: values2["vault-account"] ? { kind: "keychain", account: values2["vault-account"] } : { kind: "env" }
+      operator: values2["vault-account"] !== undefined ? { kind: "keychain", account: values2["vault-account"] } : { kind: values2["vault-operator"] ?? "contracts" }
     } : { kind: "keychain", service: values2["keychain-service"], account: values2["keychain-account"] };
     output(await credentials.bindings.bind(parse2(credentialBindingSchema, { schema: 1, ...bindingTarget(id2, values2["credential-env"], values2.origin), source })));
     return;

package/dist/credentials.d.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { type CredentialChainOptions } from "@hasna/contracts/client";
 import { CommandInterrupted, type ProviderInput } from "./domain";
 declare const keychain: z.ZodObject<{
     kind: z.ZodLiteral<"keychain">;
@@ -13,7 +14,7 @@ declare const keychain: z.ZodObject<{
     service: string;
     account: string;
 }>;
-export declare const credentialBindingSchema: z.ZodObject<{
+export declare const credentialBindingSchema: z.ZodEffects<z.ZodObject<{
     schema: z.ZodLiteral<1>;
     credentialEnv: z.ZodString;
     origins: z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">;
@@ -32,9 +33,15 @@ export declare const credentialBindingSchema: z.ZodObject<{
     }>, z.ZodObject<{
         kind: z.ZodLiteral<"vault">;
         key: z.ZodString;
-        url: z.ZodEffects<z.ZodString, string, string>;
+        url: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
         executable: z.ZodEffects<z.ZodString, string, string>;
         operator: z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
+            kind: z.ZodLiteral<"contracts">;
+        }, "strict", z.ZodTypeAny, {
+            kind: "contracts";
+        }, {
+            kind: "contracts";
+        }>, z.ZodObject<{
             kind: z.ZodLiteral<"env">;
         }, "strict", z.ZodTypeAny, {
             kind: "env";
@@ -42,7 +49,7 @@ export declare const credentialBindingSchema: z.ZodObject<{
             kind: "env";
         }>, z.ZodObject<{
             kind: z.ZodLiteral<"keychain">;
-            account: z.ZodString;
+            account: z.ZodEffects<z.ZodString, string, string>;
         }, "strict", z.ZodTypeAny, {
             kind: "keychain";
             account: string;
@@ -51,27 +58,31 @@ export declare const credentialBindingSchema: z.ZodObject<{
             account: string;
         }>]>;
     }, "strict", z.ZodTypeAny, {
-        url: string;
         key: string;
         executable: string;
         kind: "vault";
         operator: {
+            kind: "contracts";
+        } | {
             kind: "env";
         } | {
             kind: "keychain";
             account: string;
         };
+        url?: string | undefined;
     }, {
-        url: string;
         key: string;
         executable: string;
         kind: "vault";
         operator: {
+            kind: "contracts";
+        } | {
             kind: "env";
         } | {
             kind: "keychain";
             account: string;
         };
+        url?: string | undefined;
     }>]>;
 }, "strict", z.ZodTypeAny, {
     credentialEnv: string;
@@ -80,16 +91,18 @@ export declare const credentialBindingSchema: z.ZodObject<{
         service: string;
         account: string;
     } | {
-        url: string;
         key: string;
         executable: string;
         kind: "vault";
         operator: {
+            kind: "contracts";
+        } | {
             kind: "env";
         } | {
             kind: "keychain";
             account: string;
         };
+        url?: string | undefined;
     };
     schema: 1;
     origins: string[];
@@ -100,16 +113,62 @@ export declare const credentialBindingSchema: z.ZodObject<{
         service: string;
         account: string;
     } | {
-        url: string;
         key: string;
         executable: string;
         kind: "vault";
         operator: {
+            kind: "contracts";
+        } | {
             kind: "env";
         } | {
             kind: "keychain";
             account: string;
         };
+        url?: string | undefined;
+    };
+    schema: 1;
+    origins: string[];
+}>, {
+    credentialEnv: string;
+    source: {
+        kind: "keychain";
+        service: string;
+        account: string;
+    } | {
+        key: string;
+        executable: string;
+        kind: "vault";
+        operator: {
+            kind: "contracts";
+        } | {
+            kind: "env";
+        } | {
+            kind: "keychain";
+            account: string;
+        };
+        url?: string | undefined;
+    };
+    schema: 1;
+    origins: string[];
+}, {
+    credentialEnv: string;
+    source: {
+        kind: "keychain";
+        service: string;
+        account: string;
+    } | {
+        key: string;
+        executable: string;
+        kind: "vault";
+        operator: {
+            kind: "contracts";
+        } | {
+            kind: "env";
+        } | {
+            kind: "keychain";
+            account: string;
+        };
+        url?: string | undefined;
     };
     schema: 1;
     origins: string[];
@@ -130,16 +189,18 @@ export declare class CredentialBindings {
             service: string;
             account: string;
         } | {
-            url: string;
             key: string;
             executable: string;
             kind: "vault";
             operator: {
+                kind: "contracts";
+            } | {
                 kind: "env";
             } | {
                 kind: "keychain";
                 account: string;
             };
+            url?: string | undefined;
         };
         schema: 1;
         origins: string[];
@@ -173,6 +234,8 @@ export declare class CredentialResolver {
 export declare class CredentialInterrupted extends CommandInterrupted {
     constructor(exitCode: number);
 }
+/** Select an operator through the shared credential seam, then pin that choice. */
+export declare function vaultEnvironment(binding: CredentialBinding, env: NodeJS.ProcessEnv, options?: Pick<CredentialChainOptions, "keychain">): Promise<NodeJS.ProcessEnv>;
 /** Internal child mode: the key travels only through an authenticated loopback request. */
 export declare function deliverVaultCredential(): Promise<void>;
 export {};

package/dist/domain.d.ts

@@ -3,7 +3,7 @@ import { type RoutingEvent } from "./model-policy-schema";
 export { modelPolicySchema, routingEventSchema, routingEventsSchema } from "./model-policy-schema";
 export type { ModelPolicy, RoutingEvent } from "./model-policy-schema";
 export type { AuthStyle } from "./auth";
-export declare const VERSION = "0.1.3";
+export declare const VERSION = "0.1.4";
 export declare const harnessSchema: z.ZodEnum<["claude", "codex", "grok", "opencode", "opencode2", "pi", "omp", "dsh", "cline", "hermes", "prime-agent", "gemini", "aider", "kilo"]>;
 export declare const protocolSchema: z.ZodEnum<["anthropic-messages", "openai-responses", "openai-chat", "gemini-generate-content"]>;
 export declare const idSchema: z.ZodString;

package/dist/index.js

@@ -200,7 +200,7 @@ async function boundedJson(response, maxBytes = MAX_BYTES) {
 }
 
 // src/sdk.ts
-import { resolveCredential } from "@hasna/contracts/client";
+import { createClientTransport } from "@hasna/contracts/client";
 
 // src/presets.ts
 var route = (protocol, baseUrl, options = {}) => ({
@@ -361,6 +361,7 @@ function apiError(status, data, apiKey) {
 
 class SwitcherClient {
   options;
+  transport;
   baseUrl;
   constructor(options) {
     this.baseUrl = endpoint(options.baseUrl).replace(/\/v1$/, "");
@@ -368,9 +369,50 @@ class SwitcherClient {
       throw new Error("Switcher API key is required.");
     this.options = { ...options };
   }
+  static fromEnvironment(env = process.env, options = {}) {
+    const shared = createClientTransport("switcher", env, {
+      credentials: options.credentials,
+      timeoutMs: options.timeoutMs ?? 120000,
+      retry: false,
+      fetchImpl: async (input, init) => {
+        const address = String(input).replace(/\/v1\/(health|ready|version)$/, "/$1");
+        const key = new Headers(init?.headers).get("x-api-key") ?? "";
+        let response;
+        try {
+          response = await (options.fetch ?? fetch)(address, init);
+        } catch {
+          throw new SwitcherError(0, "connection_failed", "Switcher API request failed; check endpoint and service availability.");
+        }
+        if (response.status === 401 || response.status === 403) {
+          await response.body?.cancel().catch(() => {});
+          throw new SwitcherError(response.status, "api_error", `Switcher API returned HTTP ${response.status}. Check the configured credential; no alternate identity was selected.`);
+        }
+        let data;
+        try {
+          data = await boundedJson(response);
+        } catch {
+          throw new SwitcherError(response.status, "invalid_response", "Switcher API returned invalid JSON.");
+        }
+        if (!response.ok)
+          throw apiError(response.status, data, key);
+        return Response.json(data);
+      }
+    });
+    const client = new SwitcherClient({ baseUrl: shared.resolution.baseUrl, apiKey: () => {
+      throw new Error("Shared credential transport was not invoked.");
+    } });
+    client.transport = shared.client;
+    return client;
+  }
   async request(method, path, body, options = {}) {
     if (!/^\/v1\/[a-zA-Z0-9/?&=._%+-]+$/.test(path) && !["/health", "/ready", "/version"].includes(path) || path.includes(".."))
       throw new Error("Invalid API path.");
+    if (this.transport)
+      return this.transport.request(method, path.startsWith("/v1/") ? path.slice(3) : path, body, {
+        idempotencyKey: method === "GET" ? undefined : options.idempotencyKey ?? crypto.randomUUID(),
+        headers: options.version === undefined ? undefined : { "if-match": String(options.version) },
+        retry: false
+      });
     const apiKey = typeof this.options.apiKey === "function" ? this.options.apiKey() : this.options.apiKey;
     if (!apiKey || /[\r\n]/.test(apiKey))
       throw new Error("Switcher API key is required.");
@@ -467,11 +509,8 @@ class SwitcherClient {
     return this.request("PATCH", `/v1/runs/${encodeURIComponent(id)}`, input, { version, idempotencyKey });
   }
 }
-function clientFromEnv(env = process.env) {
-  const credential = () => resolveCredential("switcher", Object.fromEntries(Object.entries(env).filter(([name]) => name === "HASNA_SWITCHER_API_KEY")), { keychain: { enabled: false } })?.apiKey ?? "";
-  if (!env.HASNA_SWITCHER_API_URL || !credential())
-    throw new Error("Set HASNA_SWITCHER_API_URL and HASNA_SWITCHER_API_KEY; no local database fallback is available.");
-  return new SwitcherClient({ baseUrl: env.HASNA_SWITCHER_API_URL, apiKey: credential });
+function clientFromEnv(env = process.env, options = {}) {
+  return SwitcherClient.fromEnvironment(env, options);
 }
 export {
   providerFromPreset,

package/dist/mcp/index.js

@@ -55,7 +55,7 @@ var routingEventSchema = z.object({
 var routingEventsSchema = z.array(routingEventSchema).max(1000);
 
 // src/domain.ts
-var VERSION = "0.1.3";
+var VERSION = "0.1.4";
 var harnessSchema = z2.enum(["claude", "codex", "grok", "opencode", "opencode2", "pi", "omp", "dsh", "cline", "hermes", "prime-agent", "gemini", "aider", "kilo"]);
 var protocolSchema = z2.enum(["anthropic-messages", "openai-responses", "openai-chat", "gemini-generate-content"]);
 var idSchema = z2.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,79}$/);
@@ -199,7 +199,7 @@ async function boundedJson(response, maxBytes = MAX_BYTES) {
 }
 
 // src/sdk.ts
-import { resolveCredential } from "@hasna/contracts/client";
+import { createClientTransport } from "@hasna/contracts/client";
 
 // src/presets.ts
 var route = (protocol, baseUrl, options = {}) => ({
@@ -321,6 +321,7 @@ function apiError(status, data, apiKey) {
 
 class SwitcherClient {
   options;
+  transport;
   baseUrl;
   constructor(options) {
     this.baseUrl = endpoint(options.baseUrl).replace(/\/v1$/, "");
@@ -328,9 +329,50 @@ class SwitcherClient {
       throw new Error("Switcher API key is required.");
     this.options = { ...options };
   }
+  static fromEnvironment(env = process.env, options = {}) {
+    const shared = createClientTransport("switcher", env, {
+      credentials: options.credentials,
+      timeoutMs: options.timeoutMs ?? 120000,
+      retry: false,
+      fetchImpl: async (input, init) => {
+        const address = String(input).replace(/\/v1\/(health|ready|version)$/, "/$1");
+        const key = new Headers(init?.headers).get("x-api-key") ?? "";
+        let response;
+        try {
+          response = await (options.fetch ?? fetch)(address, init);
+        } catch {
+          throw new SwitcherError(0, "connection_failed", "Switcher API request failed; check endpoint and service availability.");
+        }
+        if (response.status === 401 || response.status === 403) {
+          await response.body?.cancel().catch(() => {});
+          throw new SwitcherError(response.status, "api_error", `Switcher API returned HTTP ${response.status}. Check the configured credential; no alternate identity was selected.`);
+        }
+        let data;
+        try {
+          data = await boundedJson(response);
+        } catch {
+          throw new SwitcherError(response.status, "invalid_response", "Switcher API returned invalid JSON.");
+        }
+        if (!response.ok)
+          throw apiError(response.status, data, key);
+        return Response.json(data);
+      }
+    });
+    const client = new SwitcherClient({ baseUrl: shared.resolution.baseUrl, apiKey: () => {
+      throw new Error("Shared credential transport was not invoked.");
+    } });
+    client.transport = shared.client;
+    return client;
+  }
   async request(method, path, body, options = {}) {
     if (!/^\/v1\/[a-zA-Z0-9/?&=._%+-]+$/.test(path) && !["/health", "/ready", "/version"].includes(path) || path.includes(".."))
       throw new Error("Invalid API path.");
+    if (this.transport)
+      return this.transport.request(method, path.startsWith("/v1/") ? path.slice(3) : path, body, {
+        idempotencyKey: method === "GET" ? undefined : options.idempotencyKey ?? crypto.randomUUID(),
+        headers: options.version === undefined ? undefined : { "if-match": String(options.version) },
+        retry: false
+      });
     const apiKey = typeof this.options.apiKey === "function" ? this.options.apiKey() : this.options.apiKey;
     if (!apiKey || /[\r\n]/.test(apiKey))
       throw new Error("Switcher API key is required.");
@@ -427,11 +469,8 @@ class SwitcherClient {
     return this.request("PATCH", `/v1/runs/${encodeURIComponent(id)}`, input, { version, idempotencyKey });
   }
 }
-function clientFromEnv(env = process.env) {
-  const credential = () => resolveCredential("switcher", Object.fromEntries(Object.entries(env).filter(([name]) => name === "HASNA_SWITCHER_API_KEY")), { keychain: { enabled: false } })?.apiKey ?? "";
-  if (!env.HASNA_SWITCHER_API_URL || !credential())
-    throw new Error("Set HASNA_SWITCHER_API_URL and HASNA_SWITCHER_API_KEY; no local database fallback is available.");
-  return new SwitcherClient({ baseUrl: env.HASNA_SWITCHER_API_URL, apiKey: credential });
+function clientFromEnv(env = process.env, options = {}) {
+  return SwitcherClient.fromEnvironment(env, options);
 }
 
 // src/mcp.ts
@@ -467,6 +506,6 @@ tool("runs_get", "Get launch metadata.", { id: z3.string() }, (p) => clientFromE
 if (process.argv.includes("--version"))
   console.log(VERSION);
 else if (process.argv.includes("--help"))
-  console.log("switcher-mcp: authenticated Switcher API tools over MCP stdio. Requires HASNA_SWITCHER_API_URL and HASNA_SWITCHER_API_KEY.");
+  console.log("switcher-mcp: authenticated Switcher API tools over MCP stdio. Resolves API URL/key through @hasna/contracts (Keychain, canonical config/credentials, or environment).");
 else
   await server.connect(new StdioServerTransport);

package/dist/sdk.d.ts

@@ -1,4 +1,5 @@
 import type { components } from "./generated/api";
+import { type CredentialChainOptions } from "@hasna/contracts/client";
 export { providerFromPreset } from "./presets";
 export type ProviderPreset = components["schemas"]["ProviderPreset"];
 export type ProviderInput = components["schemas"]["ProviderInput"];
@@ -29,10 +30,18 @@ export type ClientOptions = {
     fetch?: typeof fetch;
     timeoutMs?: number;
 };
+export type EnvironmentClientOptions = {
+    credentials?: CredentialChainOptions;
+    fetch?: typeof fetch;
+    timeoutMs?: number;
+};
 export declare class SwitcherClient {
     private readonly options;
+    private transport?;
     readonly baseUrl: string;
     constructor(options: ClientOptions);
+    /** Use Contracts' paired authority/credential resolution on every request. */
+    static fromEnvironment(env?: Record<string, string | undefined>, options?: EnvironmentClientOptions): SwitcherClient;
     request<T>(method: string, path: string, body?: unknown, options?: {
         version?: number;
         idempotencyKey?: string;
@@ -617,4 +626,4 @@ export declare class SwitcherClient {
         routingEventsDropped?: number;
     }>;
 }
-export declare function clientFromEnv(env?: Record<string, string | undefined>): SwitcherClient;
+export declare function clientFromEnv(env?: Record<string, string | undefined>, options?: EnvironmentClientOptions): SwitcherClient;

package/dist/sdk.js

@@ -200,7 +200,7 @@ async function boundedJson(response, maxBytes = MAX_BYTES) {
 }
 
 // src/sdk.ts
-import { resolveCredential } from "@hasna/contracts/client";
+import { createClientTransport } from "@hasna/contracts/client";
 
 // src/presets.ts
 var route = (protocol, baseUrl, options = {}) => ({
@@ -361,6 +361,7 @@ function apiError(status, data, apiKey) {
 
 class SwitcherClient {
   options;
+  transport;
   baseUrl;
   constructor(options) {
     this.baseUrl = endpoint(options.baseUrl).replace(/\/v1$/, "");
@@ -368,9 +369,50 @@ class SwitcherClient {
       throw new Error("Switcher API key is required.");
     this.options = { ...options };
   }
+  static fromEnvironment(env = process.env, options = {}) {
+    const shared = createClientTransport("switcher", env, {
+      credentials: options.credentials,
+      timeoutMs: options.timeoutMs ?? 120000,
+      retry: false,
+      fetchImpl: async (input, init) => {
+        const address = String(input).replace(/\/v1\/(health|ready|version)$/, "/$1");
+        const key = new Headers(init?.headers).get("x-api-key") ?? "";
+        let response;
+        try {
+          response = await (options.fetch ?? fetch)(address, init);
+        } catch {
+          throw new SwitcherError(0, "connection_failed", "Switcher API request failed; check endpoint and service availability.");
+        }
+        if (response.status === 401 || response.status === 403) {
+          await response.body?.cancel().catch(() => {});
+          throw new SwitcherError(response.status, "api_error", `Switcher API returned HTTP ${response.status}. Check the configured credential; no alternate identity was selected.`);
+        }
+        let data;
+        try {
+          data = await boundedJson(response);
+        } catch {
+          throw new SwitcherError(response.status, "invalid_response", "Switcher API returned invalid JSON.");
+        }
+        if (!response.ok)
+          throw apiError(response.status, data, key);
+        return Response.json(data);
+      }
+    });
+    const client = new SwitcherClient({ baseUrl: shared.resolution.baseUrl, apiKey: () => {
+      throw new Error("Shared credential transport was not invoked.");
+    } });
+    client.transport = shared.client;
+    return client;
+  }
   async request(method, path, body, options = {}) {
     if (!/^\/v1\/[a-zA-Z0-9/?&=._%+-]+$/.test(path) && !["/health", "/ready", "/version"].includes(path) || path.includes(".."))
       throw new Error("Invalid API path.");
+    if (this.transport)
+      return this.transport.request(method, path.startsWith("/v1/") ? path.slice(3) : path, body, {
+        idempotencyKey: method === "GET" ? undefined : options.idempotencyKey ?? crypto.randomUUID(),
+        headers: options.version === undefined ? undefined : { "if-match": String(options.version) },
+        retry: false
+      });
     const apiKey = typeof this.options.apiKey === "function" ? this.options.apiKey() : this.options.apiKey;
     if (!apiKey || /[\r\n]/.test(apiKey))
       throw new Error("Switcher API key is required.");
@@ -467,11 +509,8 @@ class SwitcherClient {
     return this.request("PATCH", `/v1/runs/${encodeURIComponent(id)}`, input, { version, idempotencyKey });
   }
 }
-function clientFromEnv(env = process.env) {
-  const credential = () => resolveCredential("switcher", Object.fromEntries(Object.entries(env).filter(([name]) => name === "HASNA_SWITCHER_API_KEY")), { keychain: { enabled: false } })?.apiKey ?? "";
-  if (!env.HASNA_SWITCHER_API_URL || !credential())
-    throw new Error("Set HASNA_SWITCHER_API_URL and HASNA_SWITCHER_API_KEY; no local database fallback is available.");
-  return new SwitcherClient({ baseUrl: env.HASNA_SWITCHER_API_URL, apiKey: credential });
+function clientFromEnv(env = process.env, options = {}) {
+  return SwitcherClient.fromEnvironment(env, options);
 }
 export {
   providerFromPreset,

package/dist/serve/index.js

@@ -62,7 +62,7 @@ function canonicalPolicyJSON(value) {
 }
 
 // src/domain.ts
-var VERSION = "0.1.3";
+var VERSION = "0.1.4";
 var harnessSchema = z2.enum(["claude", "codex", "grok", "opencode", "opencode2", "pi", "omp", "dsh", "cline", "hermes", "prime-agent", "gemini", "aider", "kilo"]);
 var protocolSchema = z2.enum(["anthropic-messages", "openai-responses", "openai-chat", "gemini-generate-content"]);
 var idSchema = z2.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,79}$/);
@@ -808,7 +808,7 @@ var openapi_default = {
   openapi: "3.0.3",
   info: {
     title: "Switcher API",
-    version: "0.1.3",
+    version: "0.1.4",
     description: "Authenticated provider/profile/catalog control plane. Launches run locally; the API never returns provider credentials."
   },
   security: [

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.0.3",
   "info": {
     "title": "Switcher API",
-    "version": "0.1.3",
+    "version": "0.1.4",
     "description": "Authenticated provider/profile/catalog control plane. Launches run locally; the API never returns provider credentials."
   },
   "security": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/switcher",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "type": "module",
   "description": "Universal provider and model switcher for coding harnesses with an API, SDK and self-hosted storage",
   "license": "Apache-2.0",