@hasna/hooks 0.9.3 → 0.9.5

package/dist/lib/resolver-types.d.ts

@@ -3,7 +3,7 @@
  * across its public seam, spelled locally.
  *
  * WHY THIS FILE EXISTS. `@hasna/contracts` is a BUILD-TIME dependency of this
- * package (pinned 1.0.2, inlined by `bun build --target bun`), so the emitted
+ * package (pinned in package.json, inlined by `bun build --target bun`), so the emitted
  * `dist/**/*.d.ts` must never `import ... from "@hasna/contracts/client"` —
  * a published declaration that references a package consumers do not have is
  * a broken install (hasna/apps#1782). Every public signature therefore uses

package/dist/lib/sync.d.ts

@@ -6,6 +6,7 @@
  * failure mid-sync leaves the local store untouched. Local-only hooks are
  * never deleted by a remote sync.
  */
+import { type HooksRemoteAuthority } from "./transport.js";
 import type { HooksCredentialOptions } from "./resolver-types.js";
 import { parseManifest } from "./manifest.js";
 type Env = Record<string, string | undefined>;
@@ -69,7 +70,7 @@ export interface StagedSyncArtifact {
  * written. A failure here (network, sha mismatch, malformed manifest,
  * containment violation) throws with the store untouched.
  */
-export declare function stageSyncArtifacts(apiUrl: string, apiKey: string, names: string[], remoteLock: RemoteLock): Promise<StagedSyncArtifact[]>;
+export declare function stageSyncArtifacts(apiUrl: string, apiKey: string | HooksRemoteAuthority, names: string[], remoteLock: RemoteLock): Promise<StagedSyncArtifact[]>;
 /**
  * P1-9 commit phase, ordered so a mid-commit failure cannot leave a partial
  * store that reads as trusted:
@@ -107,7 +108,7 @@ export interface PinnedHookInstall {
  * the user is fetched from the versioned registry — older-than-latest pins
  * are first-class, never rejected as "not the latest".
  */
-export declare function fetchPinnedHook(name: string, version: string, apiUrl: string, apiKey: string): Promise<PinnedHookInstall>;
+export declare function fetchPinnedHook(name: string, version: string, apiUrl: string, apiKey: string | HooksRemoteAuthority): Promise<PinnedHookInstall>;
 /**
  * Pin an exact hook version from the BUNDLED registry (the on-box catalog).
  * Powers `hooks install <name>@<version>` / `hooks update <name>@<version>`

package/dist/lib/transport.d.ts

@@ -8,7 +8,7 @@ export interface HooksRemoteAuthority {
      * client composes `/api/v1/...` routes on top of it.
      */
     origin: string;
-    /** The credential, resolved together with the authority it will be sent to. */
+    /** Literal credential, or empty for a vault reference. Requests use resolveHooksRequestAuthority(). */
     apiKey: string;
     /** WHERE the authority came from: an env key NAME, a Keychain item reference, a file PATH, or "default". */
     apiUrlSource: string | null;
@@ -63,6 +63,8 @@ export interface HooksTransportOptions {
     /** Where the one-line local-mode notice goes. Defaults to `process.stderr`. */
     notice?: HooksTransportNotice;
 }
+/** Resolve the selected credential through the shared consumer immediately before dispatch. */
+export declare function resolveHooksRequestAuthority(authority: HooksRemoteAuthority): Promise<HooksRemoteAuthority>;
 /**
  * Resolve the hooks transport. The deliberate unhosted opt-in is answered
  * first and WITHOUT consulting the resolver; otherwise `@hasna/contracts`
@@ -85,3 +87,5 @@ export declare function resolveHooksTransport(env?: HooksLocalOptInEnv, options?
  * end.
  */
 export declare function resolveHooksServePublishKey(env?: HooksLocalOptInEnv, options?: HooksTransportOptions): string | undefined;
+/** Server request boundary: references remain terminal and are never cached as a literal key. */
+export declare function resolveHooksServePublishKeyAsync(env?: HooksLocalOptInEnv, options?: HooksTransportOptions): Promise<string | undefined>;

package/dist/sdk/index.d.ts

@@ -71,8 +71,8 @@ export interface HooksClientOptions {
  */
 export declare function resolveHooksSdkAuthority(env?: HooksLocalOptInEnv, options?: Omit<HooksTransportOptions, "notice">): HooksRemoteAuthority;
 /**
- * Hosted registry client. Holds the resolved credential privately and sends
- * it only to the authority it was resolved together with (strict pair).
+ * Hosted registry client. Holds the authority binding privately and resolves
+ * its current credential for each request before dispatch to that authority.
  */
 export declare class HooksClient {
     #private;

package/dist/sdk/index.js

@@ -1,12 +1,17 @@
 // @bun
-// ../../node_modules/.bun/@hasna+contracts@1.0.2+e0db24ae03127387/node_modules/@hasna/contracts/dist/client/transport.js
+// ../contracts/dist/client/transport.js
 import { isIP } from "net";
 import { spawnSync } from "child_process";
-import { closeSync, fstatSync, openSync, readFileSync } from "fs";
-import { O_NOFOLLOW, O_NONBLOCK, O_RDONLY } from "constants";
-import { createRequire } from "module";
+import { closeSync as closeSync2, fstatSync as fstatSync2, openSync as openSync2, readFileSync as readFileSync2 } from "fs";
+import { O_NOFOLLOW as O_NOFOLLOW2, O_NONBLOCK as O_NONBLOCK2, O_RDONLY as O_RDONLY2 } from "constants";
 import { hostname as osHostname } from "os";
-import { isAbsolute, join } from "path";
+import { isAbsolute, join as join2 } from "path";
+import { createRequire } from "module";
+import { fileURLToPath as fileURLToPath2 } from "url";
+import { closeSync, fstatSync, lstatSync, openSync, readFileSync, realpathSync, statSync } from "fs";
+import { O_NOFOLLOW, O_NONBLOCK, O_RDONLY } from "constants";
+import { basename, dirname, join, relative, sep } from "path";
+import { fileURLToPath, pathToFileURL } from "url";
 function envToken(name) {
   return name.toUpperCase().replace(/-/g, "_");
 }
@@ -24,6 +29,114 @@ var CREDENTIAL_PROFILE_ENV_KEY = "HASNA_PROFILE";
 function credentialPointerEnvKey(name) {
   return `HASNA_${envToken(name)}_API_KEY_REF`;
 }
+function e(e2, n, r) {
+  throw new Error(r ? `No known conditions for "${n}" specifier in "${e2}" package` : `Missing "${n}" specifier in "${e2}" package`);
+}
+function n(n2, i, o, f) {
+  let s, u, l = r(n2, o), c = function(e2) {
+    let n3 = new Set(["default", ...e2.conditions || []]);
+    return e2.unsafe || n3.add(e2.require ? "require" : "import"), e2.unsafe || n3.add(e2.browser ? "browser" : "node"), n3;
+  }(f || {}), a = i[l];
+  if (a === undefined) {
+    let e2, n3, r, t;
+    for (t in i)
+      n3 && t.length < n3.length || (t[t.length - 1] === "/" && l.startsWith(t) ? (u = l.substring(t.length), n3 = t) : t.length > 1 && (r = t.indexOf("*", 1), ~r && (e2 = RegExp("^" + t.substring(0, r) + "(.*)" + t.substring(1 + r) + "$").exec(l), e2 && e2[1] && (u = e2[1], n3 = t))));
+    a = i[n3];
+  }
+  return a || e(n2, l), s = t(a, c), s || e(n2, l, 1), u && function(e2, n3) {
+    let r, t = 0, i2 = e2.length, o2 = /[*]/g, f2 = /[/]$/;
+    for (;t < i2; t++)
+      e2[t] = o2.test(r = e2[t]) ? r.replace(o2, n3) : f2.test(r) ? r + n3 : r;
+  }(s, u), s;
+}
+function r(e2, n2, r2) {
+  if (e2 === n2 || n2 === ".")
+    return ".";
+  let t = e2 + "/", i = t.length, o = n2.slice(0, i) === t, f = o ? n2.slice(i) : n2;
+  return f[0] === "#" ? f : o || !r2 ? f.slice(0, 2) === "./" ? f : "./" + f : f;
+}
+function t(e2, n2, r2) {
+  if (e2) {
+    if (typeof e2 == "string")
+      return r2 && r2.add(e2), [e2];
+    let i, o;
+    if (Array.isArray(e2)) {
+      for (o = r2 || new Set, i = 0;i < e2.length; i++)
+        t(e2[i], n2, o);
+      if (!r2 && o.size)
+        return [...o];
+    } else
+      for (i in e2)
+        if (n2.has(i))
+          return t(e2[i], n2, r2);
+  }
+}
+function o(e2, r2, t2) {
+  let i, o2 = e2.exports;
+  if (o2) {
+    if (typeof o2 == "string")
+      o2 = { ".": o2 };
+    else
+      for (i in o2) {
+        i[0] !== "." && (o2 = { ".": o2 });
+        break;
+      }
+    return n(e2.name, o2, r2 || ".", t2);
+  }
+}
+var PACKAGE = "@hasna/secrets";
+var MAX_PACKAGE_BYTES = 1024 * 1024;
+function entryPoint(directory) {
+  const root = realpathSync(directory);
+  const fd = openSync(join(root, "package.json"), O_RDONLY | O_NOFOLLOW | O_NONBLOCK);
+  let pkg;
+  try {
+    const stat = fstatSync(fd);
+    if (!stat.isFile() || stat.size > MAX_PACKAGE_BYTES)
+      throw new Error("Invalid Secrets package metadata");
+    pkg = JSON.parse(readFileSync(fd, "utf8"));
+  } finally {
+    closeSync(fd);
+  }
+  if (!pkg || typeof pkg !== "object" || !("name" in pkg) || pkg.name !== PACKAGE) {
+    throw new Error("Invalid Secrets package identity");
+  }
+  const target = o(pkg, ".")?.[0];
+  if (typeof target !== "string" || !target.startsWith("./"))
+    throw new Error("Missing Secrets import export");
+  const parts = target.slice(2).split("/");
+  if (/[\\%?#\0]/.test(target) || parts.some((part) => !part || part === "." || part === ".." || part === "node_modules")) {
+    throw new Error("Invalid Secrets import export");
+  }
+  const file = realpathSync(join(root, ...parts));
+  const within = relative(root, file);
+  if (!within || within === ".." || within.startsWith(`..${sep}`) || !statSync(file).isFile()) {
+    throw new Error("Secrets import export escapes its package or is not a file");
+  }
+  return pathToFileURL(file).href;
+}
+function resolveInstalledSecrets(parentUrl) {
+  let directory = dirname(fileURLToPath(parentUrl));
+  for (;; ) {
+    if (basename(directory) !== "node_modules") {
+      const candidate = join(directory, "node_modules", PACKAGE);
+      let absent = false;
+      try {
+        lstatSync(candidate);
+      } catch (error) {
+        if (error.code !== "ENOENT")
+          throw error;
+        absent = true;
+      }
+      if (!absent)
+        return entryPoint(candidate);
+    }
+    const parent = dirname(directory);
+    if (parent === directory)
+      throw new Error("Secrets SDK is not installed for this consumer");
+    directory = parent;
+  }
+}
 
 class CredentialResolutionError extends Error {
   appName;
@@ -72,14 +185,14 @@ function hasnaHomeDir(env) {
   if (override)
     return override;
   const home = homeDir(env);
-  return home ? join(home, HASNA_HOME_DIR) : null;
+  return home ? join2(home, HASNA_HOME_DIR) : null;
 }
 function appConfigDir(name, env) {
   const configRoot = absoluteOverride(env, HASNA_CONFIG_HOME_ENV_KEY);
   if (configRoot)
-    return join(configRoot, name);
+    return join2(configRoot, name);
   const root = hasnaHomeDir(env);
-  return root ? join(root, name, CONFIG_SUBDIR) : null;
+  return root ? join2(root, name, CONFIG_SUBDIR) : null;
 }
 function credentialDiskSourceList(name, env, profile = null) {
   if (!SAFE_APP_SLUG.test(name))
@@ -88,7 +201,7 @@ function credentialDiskSourceList(name, env, profile = null) {
   if (!directory)
     return [];
   const file = profile ? `${CREDENTIALS_FILE}-${profile}` : CREDENTIALS_FILE;
-  return [{ path: join(directory, file), tier: "disk" }];
+  return [{ path: join2(directory, file), tier: "disk" }];
 }
 function credentialDiskSources(name, env) {
   return credentialDiskSourceList(name, env, null).map((s) => s.path);
@@ -142,7 +255,7 @@ function readAppConfigFile(path) {
   };
   let fd = -1;
   try {
-    fd = openSync(path, O_RDONLY | O_NOFOLLOW | O_NONBLOCK);
+    fd = openSync2(path, O_RDONLY2 | O_NOFOLLOW2 | O_NONBLOCK2);
   } catch (error) {
     const code = error.code;
     if (code === "ENOENT" || code === "ENOTDIR")
@@ -152,7 +265,7 @@ function readAppConfigFile(path) {
     unsafe(`the path could not be opened (${code ?? "unknown error"})`);
   }
   try {
-    const before = fstatSync(fd);
+    const before = fstatSync2(fd);
     if (!before.isFile())
       unsafe("the path is not a regular file");
     if (!configFileModeAllowed(before.mode)) {
@@ -163,31 +276,39 @@ function readAppConfigFile(path) {
       unsafe("the file is not owned by the current user");
     if (before.size > MAX_CREDENTIAL_FILE_BYTES)
       unsafe("the file exceeds the size limit");
-    const bytes = readFileSync(fd);
-    const after = fstatSync(fd);
+    const bytes = readFileSync2(fd);
+    const after = fstatSync2(fd);
     if (!configFileReadsCoherent(before, after)) {
       unsafe("the file changed while being read");
     }
     return parseEnvFile(bytes.toString("utf8"));
   } finally {
     if (fd !== -1)
-      closeSync(fd);
+      closeSync2(fd);
   }
 }
-function readCredentialFile(path, apiKeyKeys) {
+function readCredentialFile(path, apiKeyKeys, pointerKey) {
   const parsed = readAppConfigFile(path);
   if (!parsed)
     return null;
-  for (const key of apiKeyKeys) {
+  for (const key of [...apiKeyKeys, pointerKey]) {
     if (parsed.unusable.has(key)) {
       throw new CredentialFileUnsafeError(path, `${key} is declared but blank or malformed`);
     }
   }
   const values = apiKeyKeys.map((key) => parsed.values.get(key)?.trim()).filter((value) => Boolean(value));
+  const pointer = parsed.values.get(pointerKey)?.trim();
+  if (pointer !== undefined) {
+    if (!VAULT_POINTER_SHAPE.test(pointer))
+      throw new CredentialFileUnsafeError(path, `${pointerKey} must name a vault item`);
+    if (values.length)
+      throw new CredentialFileUnsafeError(path, "a credential file cannot select both a literal key and a vault reference");
+    return { apiKey: "", pointerVaultKey: pointer };
+  }
   if (new Set(values).size > 1) {
     throw new CredentialFileUnsafeError(path, "credential aliases disagree");
   }
-  return values[0] ?? null;
+  return values[0] === undefined ? null : { apiKey: values[0] };
 }
 var CREDENTIAL_SHAPED_KEY = /(?:^|_)(?:API_KEY|KEY|TOKEN|SECRET|PASSWORD|PASSWD|CREDENTIAL|AUTH)(?:_|$)/;
 function appConfigDiskValue(name, env, keys) {
@@ -262,6 +383,18 @@ function sealCredential(fields) {
   });
   return Object.freeze(sealed);
 }
+function explicitCredential(appName, apiKey) {
+  const source = "explicit apiKey option";
+  assertUsableCredential(appName, source, apiKey);
+  return sealCredential({
+    apiKey,
+    tier: "argument",
+    source,
+    deliberate: true,
+    diskCandidates: [],
+    warning: null
+  });
+}
 function firstEnvValue(env, keys) {
   for (const key of keys) {
     if (!Object.prototype.hasOwnProperty.call(env, key))
@@ -448,12 +581,13 @@ function resolveCredential(name, env, options = {}) {
     }
     const paths = profileDiskSources(name, env, profile);
     for (const path of paths) {
-      const value = readCredentialFile(path, apiKeyKeys);
+      const value = readCredentialFile(path, apiKeyKeys, pointerKeyName);
       if (value) {
-        assertUsableCredential(name, path, value);
+        if (!value.pointerVaultKey)
+          assertUsableCredential(name, path, value.apiKey);
         return sealCredential({
-          apiKey: value,
-          tier: "profile",
+          ...value,
+          tier: value.pointerVaultKey ? "pointer" : "profile",
           source: path,
           deliberate: true,
           diskCandidates: paths,
@@ -461,7 +595,7 @@ function resolveCredential(name, env, options = {}) {
         });
       }
     }
-    throw new CredentialResolutionError(name, `Profile '${profile}' (from ${profileSource}) has no ${apiKeyKeys[0]} for '${name}'. ` + `Looked in: ${paths.join(", ") || "<no HOME in this environment>"}. ` + `A profile names WHICH identity to use, so it is never resolved around \u2014 ` + `create the profile's credential file or unset ${CREDENTIAL_PROFILE_ENV_KEY}.`, paths);
+    throw new CredentialResolutionError(name, `Profile '${profile}' (from ${profileSource}) has no ${apiKeyKeys[0]} or ${pointerKeyName} 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 definedEnvEntries = apiKeyKeys.filter((key) => Object.prototype.hasOwnProperty.call(env, key) && env[key] !== undefined).map((key) => ({ key, value: String(env[key]).trim() }));
   const blankEnv = definedEnvEntries.find((entry) => entry.value.length === 0);
@@ -486,17 +620,27 @@ function resolveCredential(name, env, options = {}) {
     });
   }
   const diskSourceList = credentialDiskSourceList(name, env, null);
-  const diskHits = diskSourceList.map((src) => ({ src, value: readCredentialFile(src.path, apiKeyKeys) })).filter((hit) => hit.value !== null);
+  const diskHits = diskSourceList.map((src) => ({ src, value: readCredentialFile(src.path, apiKeyKeys, pointerKeyName) })).filter((hit) => hit.value !== null);
   if (diskHits.length > 0) {
     const winner = diskHits[0];
-    assertUsableCredential(name, winner.src.path, winner.value);
+    if (winner.value.pointerVaultKey) {
+      return sealCredential({
+        ...winner.value,
+        tier: "pointer",
+        source: winner.src.path,
+        deliberate: false,
+        diskCandidates: diskPaths,
+        warning: null
+      });
+    }
+    assertUsableCredential(name, winner.src.path, winner.value.apiKey);
     const divergentSources = [
-      ...diskHits.slice(1).filter((hit) => hit.value !== winner.value).map((hit) => hit.src.path),
-      ...envHit && envHit.value !== winner.value ? [envHit.key] : []
+      ...diskHits.slice(1).filter((hit) => hit.value.apiKey !== winner.value.apiKey || hit.value.pointerVaultKey !== winner.value.pointerVaultKey).map((hit) => hit.src.path),
+      ...envHit && envHit.value !== winner.value.apiKey ? [envHit.key] : []
     ];
     const warning = divergentSources.length > 0 ? `Credential sources disagree for '${name}': ${winner.src.path} and ` + `${divergentSources.join(", ")} hold different keys. ${winner.src.path} wins, because a file on ` + `disk is re-read on every call while an environment variable is a snapshot. Reconcile them \u2014 ` + `a rotation that updated only one leaves the other to fail 401 wherever it is loaded first.` : null;
     return sealCredential({
-      apiKey: winner.value,
+      apiKey: winner.value.apiKey,
       tier: winner.src.tier,
       source: winner.src.path,
       deliberate: false,
@@ -517,8 +661,54 @@ function resolveCredential(name, env, options = {}) {
   }
   return null;
 }
-var SECRETS_PACKAGE_SPECIFIER = "@hasna/" + "secrets";
 var requireSecretsSdk = createRequire(import.meta.url);
+async function completePointerCredential(name, pointerResolution, env = process.env) {
+  const secretsEnv = snapshotClientEnvironment("secrets", env);
+  const vaultKey = pointerResolution.pointerVaultKey;
+  const pointerEnvKey = pointerResolution.source;
+  if (!vaultKey) {
+    throw new CredentialResolutionError(name, `Pointer resolution from ${pointerEnvKey} carries no vault item key; this is a defect in the resolver.`, [pointerEnvKey]);
+  }
+  if (name === "secrets") {
+    throw new CredentialResolutionError(name, "The Secrets bootstrap credential cannot reference the same hosted vault; configure an independent bootstrap provider.", [pointerEnvKey]);
+  }
+  let secretsSdk;
+  try {
+    const sdkUrl = resolveInstalledSecrets(import.meta.url);
+    secretsSdk = requireSecretsSdk(fileURLToPath2(sdkUrl));
+  } catch {
+    throw new CredentialResolutionError(name, `${pointerEnvKey} names vault item '${vaultKey}', but the secrets SDK (@hasna/secrets) is not installed ` + `in this process. A vault pointer is TERMINAL: install @hasna/secrets to resolve it, or unset ${pointerEnvKey}.`, [pointerEnvKey]);
+  }
+  let client;
+  try {
+    const bootstrap = resolveCredential("secrets", secretsEnv);
+    if (!bootstrap || bootstrap.tier === "pointer") {
+      throw new CredentialResolutionError("secrets", "The Secrets vault requires an independent, non-reference bootstrap credential.", bootstrap ? [bootstrap.source] : []);
+    }
+    client = secretsSdk.createSecretsClientFromEnv(secretsEnv);
+  } catch {
+    throw new CredentialResolutionError(name, `${pointerEnvKey} names vault item '${vaultKey}', but the secrets client could not be configured from this ` + `environment (the secrets service URL and key env are missing or invalid). A vault pointer is TERMINAL and ` + `never falls through to a literal or disk credential.`, [pointerEnvKey]);
+  }
+  let secret;
+  try {
+    secret = await client.getSecret({ key: vaultKey });
+  } catch {
+    throw new CredentialResolutionError(name, `${pointerEnvKey} names vault item '${vaultKey}', but the vault could not be reached or the item is ` + `unavailable. A vault pointer is TERMINAL and never falls through to a literal or disk credential.`, [pointerEnvKey]);
+  }
+  const value = secret.value;
+  if (!value) {
+    throw new CredentialResolutionError(name, `${pointerEnvKey} resolved vault item '${vaultKey}', but it holds no value. A vault pointer is TERMINAL.`, [pointerEnvKey]);
+  }
+  assertUsableCredential(name, `${pointerEnvKey} -> vault:${vaultKey}`, value);
+  return sealCredential({
+    apiKey: value,
+    tier: "pointer",
+    source: `${pointerEnvKey} -> vault:${vaultKey}`,
+    deliberate: pointerResolution.deliberate,
+    diskCandidates: pointerResolution.diskCandidates,
+    warning: null
+  });
+}
 var DEFAULT_FLEET_GATEWAY_ORIGIN = "https://api.hasna.com";
 var DEFAULT_AUTHORITY_SOURCE = "default";
 function defaultFleetGatewayBaseUrl(name) {
@@ -747,7 +937,7 @@ var AUTHORITY_OVERRIDE_HEADERS = new Set([
 // src/lib/app-home.ts
 import { existsSync } from "fs";
 import { homedir } from "os";
-import { join as join2, resolve } from "path";
+import { join as join3, resolve } from "path";
 import { homedir as pathsResolverHomedir } from "os";
 import { join as pathsResolverJoin } from "path";
 var PATHS_RESOLVER_KIND_ENV = {
@@ -816,13 +1006,13 @@ function getResolverDataRoot(env = process.env) {
   return dataDir({ app: "hooks", home: getHomeDir(env), env });
 }
 function getLegacyDataRoot(env = process.env) {
-  return join2(getHomeDir(env), ".hasna", "hooks");
+  return join3(getHomeDir(env), ".hasna", "hooks");
 }
 function adoptResolverDataRoot(resolved, env = process.env) {
   const dataOverride = env.HASNA_DATA_HOME;
   if (typeof dataOverride === "string" && dataOverride.trim().length > 0)
     return true;
-  return existsSync(join2(resolved, STORE_MARKER));
+  return existsSync(join3(resolved, STORE_MARKER));
 }
 function getExplicitDataDir(env = process.env) {
   const dir = env.HASNA_HOOKS_DATA_DIR ?? env.HOOKS_DATA_DIR;
@@ -931,6 +1121,41 @@ function rethrowHooksAuthorityFailure(error) {
   }
   throw new Error(`REMOTE_API_URL_INVALID: ${message} local mode fallback is disabled`, { cause: error });
 }
+var authorityBindings = new WeakMap;
+function sameCredential(left, right) {
+  return left === null || right === null ? left === right : left.apiKey === right.apiKey && left.pointerVaultKey === right.pointerVaultKey && left.source === right.source && left.tier === right.tier;
+}
+function changedBinding() {
+  throw new Error("REMOTE_API_CREDENTIAL_INVALID: The configured Hooks authority or credential changed while preparing a request; no request was sent.");
+}
+async function resolveHooksRequestAuthority(authority) {
+  if (authority.origin !== hooksRegistryOrigin(authority.v1BaseUrl))
+    changedBinding();
+  const binding = authorityBindings.get(authority);
+  if (!binding)
+    return { ...authority, apiKey: explicitCredential("hooks", authority.apiKey).apiKey };
+  const snapshot = () => {
+    const next = resolveHooksTransport(binding.env, binding.options);
+    if (next.mode !== "remote" || !next.authority || next.authority.v1BaseUrl !== authority.v1BaseUrl)
+      changedBinding();
+    return { authority: next.authority, binding: authorityBindings.get(next.authority) };
+  };
+  const first = snapshot();
+  const reviewed = snapshot();
+  if (!sameCredential(first.binding.credential, reviewed.binding.credential))
+    changedBinding();
+  let credential = reviewed.binding.credential;
+  try {
+    if (credential.tier === "pointer")
+      credential = await completePointerCredential("hooks", credential, binding.env);
+  } catch (error) {
+    rethrowHooksAuthorityFailure(error);
+  }
+  const final = snapshot();
+  if (!sameCredential(reviewed.binding.credential, final.binding.credential))
+    changedBinding();
+  return { ...reviewed.authority, apiKey: credential.apiKey };
+}
 function resolveHooksTransport(env = process.env, options = {}) {
   if (selectsHooksLocalStore(env)) {
     announceLocal(options.notice, "HASNA_HOOKS_LOCAL is set and nothing configures a registry authority");
@@ -944,7 +1169,7 @@ function resolveHooksTransport(env = process.env, options = {}) {
   try {
     credential = resolveCredential("hooks", resolverEnv, credentialOptions);
     resolution = resolveClientTransport("hooks", resolverEnv, {
-      credentials: credential ? { ...credentialOptions, apiKey: credential.apiKey } : credentialOptions
+      credentials: credential && credential.tier !== "pointer" ? { ...credentialOptions, apiKey: credential.apiKey } : credentialOptions
     });
   } catch (error) {
     rethrowHooksAuthorityFailure(error);
@@ -952,18 +1177,20 @@ function resolveHooksTransport(env = process.env, options = {}) {
   if (!credential) {
     throw new Error("REMOTE_API_CONFIG_MISSING: no hooks registry credential resolved; " + "local mode fallback is disabled");
   }
+  const authority = {
+    origin: hooksRegistryOrigin(resolution.baseUrl),
+    apiKey: credential.apiKey,
+    apiUrlSource: resolution.apiUrlSource,
+    apiKeySource: credential.source,
+    apiKeyTier: credential.tier,
+    v1BaseUrl: resolution.baseUrl,
+    warning: resolution.warning
+  };
+  authorityBindings.set(authority, { env, options, credential });
   return {
     mode: "remote",
     source: `${credential.source}+${resolution.apiUrlSource ?? "default"}`,
-    authority: {
-      origin: hooksRegistryOrigin(resolution.baseUrl),
-      apiKey: credential.apiKey,
-      apiUrlSource: resolution.apiUrlSource,
-      apiKeySource: credential.source,
-      apiKeyTier: credential.tier,
-      v1BaseUrl: resolution.baseUrl,
-      warning: resolution.warning
-    }
+    authority
   };
 }
 
@@ -984,14 +1211,14 @@ class HooksClient {
   v1BaseUrl;
   apiKeySource;
   apiUrlSource;
-  #apiKey;
+  #authority;
   #fetch;
   constructor(authority, options = {}) {
     this.origin = authority.origin;
     this.v1BaseUrl = authority.v1BaseUrl;
     this.apiKeySource = authority.apiKeySource;
     this.apiUrlSource = authority.apiUrlSource;
-    this.#apiKey = authority.apiKey;
+    this.#authority = authority;
     this.#fetch = options.fetch ?? fetch;
   }
   urlFor(path) {
@@ -1023,13 +1250,15 @@ class HooksClient {
     return { ...body, sha256: res.headers.get("x-hook-sha256") };
   }
   async request(path) {
-    const res = await this.#fetch(this.urlFor(path), {
-      headers: { accept: "application/json", "x-api-key": this.#apiKey },
+    const authority = await resolveHooksRequestAuthority(this.#authority);
+    const url = `${authority.origin}${path.startsWith("/") ? path : `/${path}`}`;
+    const res = await this.#fetch(url, {
+      headers: { accept: "application/json", "x-api-key": authority.apiKey },
       redirect: "manual"
     });
     if (!res.ok) {
       const code = res.status === 401 || res.status === 403 ? "REMOTE_API_CREDENTIAL_INVALID" : "REMOTE_API_HTTP_ERROR";
-      throw new Error(`${code}: hooks registry ${this.urlFor(path)} responded ${res.status}`);
+      throw new Error(`${code}: hooks registry ${url} responded ${res.status}`);
     }
     return res;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/hooks",
-  "version": "0.9.3",
+  "version": "0.9.5",
   "description": "Open source hooks library for AI coding agents - Install safety, quality, and automation hooks with a single command",
   "type": "module",
   "bin": {
@@ -54,11 +54,11 @@
     "@types/react": "^18.2.0",
     "typescript": "^5",
     "bun-types": "1.3.14",
-    "@hasna/contracts": "1.0.2"
+    "@hasna/contracts": "1.2.1"
   },
   "dependencies": {
     "@hasna/events": "^0.1.16",
-    "@hasna/secrets": "0.3.10",
+    "@hasna/secrets": "0.4.2",
     "@modelcontextprotocol/sdk": "^1.26.0",
     "chalk": "^5.3.0",
     "commander": "^12.1.0",