@hasna/hooks 0.9.4 → 0.9.5

package/README.md

@@ -181,6 +181,17 @@ export HASNA_HOOKS_API_KEY_REF=<vault-key-name>   # resolved through the vault a
 secrets exec <vault-key-name> --as HASNA_HOOKS_API_KEY -- hooks serve
 ```
 
+The owner-only `~/.hasna/hooks/config/credentials` file also accepts a reference:
+
+```dotenv
+HASNA_HOOKS_API_URL=https://registry.example.com
+HASNA_HOOKS_API_KEY_REF=your-team/hooks/live/api-key
+```
+
+Keep this file at mode `0400` or `0600`, and configure Secrets through its normal independent credential resolver. Hooks resolves the selected reference through the Secrets SDK for each registry request and each server publish-key check. References retain their existing precedence: a locked Keychain remains a refusal ahead of a file reference, and a missing reference never falls through to a stale literal key. A file cannot contain both a literal key and a reference.
+
+`hooks list` displays catalog metadata and does not prove that the remote registry is reachable. Use `hooks sync --dry-run` to exercise registry reads without changing installed hooks. SDK consumers use `createHooksClient()`; callers working directly with transport metadata must await `resolveHooksRequestAuthority()` before sending a request. The server uses `resolveHooksServePublishKeyAsync()` for references.
+
 **Cloudflare provisioning.** `hooks cf deploy` creates the D1 database and R2 bucket via the Cloudflare API, then prints the exact wrangler commands for the worker upload (the worker needs the workerd target, which only wrangler can bundle):
 
 ```bash
@@ -193,8 +204,8 @@ The worker (`src/cf/worker.ts`) implements the same API routes against D1 + R2,
 
 ## Storage
 
-Hooks stores data locally by default in `~/.hasna/hooks/` and uses SQLite
-directly for hook event history. The package owns its database schema and
+When local mode is explicitly selected, Hooks stores data in `~/.hasna/hooks/`
+and uses SQLite for hook event history. The package owns its database schema and
 migrations; it does not depend on the deprecated shared runtime or its CLI.
 The repo includes its own PostgreSQL migration definitions for the optional
 `hooks storage push|pull|sync` commands. Use the `hooks log` commands to inspect

package/bin/hooks-mcp.js

@@ -1418,14 +1418,14 @@ var init_redact = __esm(() => {
   ];
 });
 
-// ../../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 as closeSync2, fstatSync, openSync as openSync2, readFileSync as readFileSync7 } 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 readFileSync22 } 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 as isAbsolute2, join as join9 } from "path";
+import { isAbsolute as isAbsolute2, join as join22 } from "path";
+import { createRequire } from "module";
 function envToken(name) {
   return name.toUpperCase().replace(/-/g, "_");
 }
@@ -1455,14 +1455,14 @@ function hasnaHomeDir(env) {
   if (override)
     return override;
   const home = homeDir(env);
-  return home ? join9(home, HASNA_HOME_DIR) : null;
+  return home ? join22(home, HASNA_HOME_DIR) : null;
 }
 function appConfigDir(name, env) {
   const configRoot = absoluteOverride(env, HASNA_CONFIG_HOME_ENV_KEY);
   if (configRoot)
-    return join9(configRoot, name);
+    return join22(configRoot, name);
   const root = hasnaHomeDir(env);
-  return root ? join9(root, name, CONFIG_SUBDIR) : null;
+  return root ? join22(root, name, CONFIG_SUBDIR) : null;
 }
 function credentialDiskSourceList(name, env, profile = null) {
   if (!SAFE_APP_SLUG.test(name))
@@ -1471,7 +1471,7 @@ function credentialDiskSourceList(name, env, profile = null) {
   if (!directory)
     return [];
   const file = profile ? `${CREDENTIALS_FILE}-${profile}` : CREDENTIALS_FILE;
-  return [{ path: join9(directory, file), tier: "disk" }];
+  return [{ path: join22(directory, file), tier: "disk" }];
 }
 function credentialDiskSources(name, env) {
   return credentialDiskSourceList(name, env, null).map((s) => s.path);
@@ -1525,7 +1525,7 @@ function readAppConfigFile(path) {
   };
   let fd = -1;
   try {
-    fd = openSync2(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")
@@ -1535,7 +1535,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)) {
@@ -1546,8 +1546,8 @@ 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 = readFileSync7(fd);
-    const after = fstatSync(fd);
+    const bytes = readFileSync22(fd);
+    const after = fstatSync2(fd);
     if (!configFileReadsCoherent(before, after)) {
       unsafe("the file changed while being read");
     }
@@ -1557,20 +1557,28 @@ function readAppConfigFile(path) {
       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] };
 }
 function appConfigDiskValue(name, env, keys) {
   const wanted = keys.filter((key) => !CREDENTIAL_SHAPED_KEY.test(key));
@@ -1827,12 +1835,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,
@@ -1840,7 +1849,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);
@@ -1865,17 +1874,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,
@@ -2098,8 +2117,9 @@ function credentialDiskSourcesForMessage(name, env) {
   const paths = credentialDiskSources(name, env);
   return paths.length > 0 ? paths.join(" or ") : "<no HOME or HASNA_HOME set in this environment, so no credential file was consulted>";
 }
-var CREDENTIAL_PROFILE_ENV_KEY = "HASNA_PROFILE", CredentialResolutionError, CredentialFileUnsafeError, HASNA_HOME_ENV_KEY = "HASNA_HOME", HASNA_CONFIG_HOME_ENV_KEY = "HASNA_CONFIG_HOME", KEYCHAIN_STATION_ENV_KEY = "HASNA_STATION", HASNA_HOME_DIR = ".hasna", CONFIG_SUBDIR = "config", CREDENTIALS_FILE = "credentials", KEYCHAIN_SECURITY_BIN = "/usr/bin/security", KEYCHAIN_SERVICE_PREFIX = "hasna.credentials", KEYCHAIN_ITEM_NOT_FOUND_STATUS = 44, KEYCHAIN_SPAWN_TIMEOUT_MS = 1e4, MAX_CREDENTIAL_FILE_BYTES, SAFE_APP_SLUG, SAFE_PROFILE, ILLEGAL_IN_HEADER_VALUE, VAULT_POINTER_SHAPE, CREDENTIAL_SHAPED_KEY, INSPECT_CUSTOM, CREDENTIAL_SEAL, AMBIENT_ENVIRONMENT, SECRETS_PACKAGE_SPECIFIER, requireSecretsSdk, DEFAULT_FLEET_GATEWAY_ORIGIN = "https://api.hasna.com", DEFAULT_AUTHORITY_SOURCE = "default", ASCII_CONTROL_PATTERN, DNS_LABEL_PATTERN, ClientTransportConfigurationError, IDEMPOTENT_METHODS, AUTHORITY_OVERRIDE_HEADERS;
+var CREDENTIAL_PROFILE_ENV_KEY = "HASNA_PROFILE", MAX_PACKAGE_BYTES, CredentialResolutionError, CredentialFileUnsafeError, HASNA_HOME_ENV_KEY = "HASNA_HOME", HASNA_CONFIG_HOME_ENV_KEY = "HASNA_CONFIG_HOME", KEYCHAIN_STATION_ENV_KEY = "HASNA_STATION", HASNA_HOME_DIR = ".hasna", CONFIG_SUBDIR = "config", CREDENTIALS_FILE = "credentials", KEYCHAIN_SECURITY_BIN = "/usr/bin/security", KEYCHAIN_SERVICE_PREFIX = "hasna.credentials", KEYCHAIN_ITEM_NOT_FOUND_STATUS = 44, KEYCHAIN_SPAWN_TIMEOUT_MS = 1e4, MAX_CREDENTIAL_FILE_BYTES, SAFE_APP_SLUG, SAFE_PROFILE, ILLEGAL_IN_HEADER_VALUE, VAULT_POINTER_SHAPE, CREDENTIAL_SHAPED_KEY, INSPECT_CUSTOM, CREDENTIAL_SEAL, AMBIENT_ENVIRONMENT, requireSecretsSdk, DEFAULT_FLEET_GATEWAY_ORIGIN = "https://api.hasna.com", DEFAULT_AUTHORITY_SOURCE = "default", ASCII_CONTROL_PATTERN, DNS_LABEL_PATTERN, ClientTransportConfigurationError, IDEMPOTENT_METHODS, AUTHORITY_OVERRIDE_HEADERS;
 var init_transport = __esm(() => {
+  MAX_PACKAGE_BYTES = 1024 * 1024;
   CredentialResolutionError = class CredentialResolutionError extends Error {
     appName;
     attempted;
@@ -2127,7 +2147,6 @@ var init_transport = __esm(() => {
   INSPECT_CUSTOM = Symbol.for("nodejs.util.inspect.custom");
   CREDENTIAL_SEAL = Symbol.for("hasna:contracts:sealedCredential");
   AMBIENT_ENVIRONMENT = Symbol.for("hasna:contracts:ambientClientEnvironment");
-  SECRETS_PACKAGE_SPECIFIER = "@hasna/" + "secrets";
   requireSecretsSdk = createRequire(import.meta.url);
   ASCII_CONTROL_PATTERN = /[\u0000-\u001f\u007f]/;
   DNS_LABEL_PATTERN = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/;
@@ -2385,7 +2404,7 @@ __export(exports_run, {
 });
 import { randomBytes as randomBytes2 } from "crypto";
 import { rmSync as rmSync2, writeFileSync as writeFileSync6 } from "fs";
-import { basename as basename2, dirname as dirname6, isAbsolute as isAbsolute4, join as join10 } from "path";
+import { basename as basename2, dirname as dirname6, isAbsolute as isAbsolute4, join as join9 } from "path";
 function extensionOf(scriptPath) {
   const base = basename2(scriptPath);
   const dot = base.lastIndexOf(".");
@@ -2456,7 +2475,7 @@ async function readPipeWithDeadline(stream, deadlineMs) {
 async function executeVerifiedScript(options) {
   const scriptDir = dirname6(options.scriptPath);
   const interpreter = interpreterFor(options.name, options.scriptPath, options.content);
-  const tempPath = join10(scriptDir, `.hooks-verified-${randomBytes2(12).toString("hex")}.${interpreter.tempExt}`);
+  const tempPath = join9(scriptDir, `.hooks-verified-${randomBytes2(12).toString("hex")}.${interpreter.tempExt}`);
   let proc = null;
   let timedOut = false;
   const timeoutTimer = options.timeout ? setTimeout(() => {
@@ -2664,8 +2683,8 @@ import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z as z2 } from "zod";
 init_registry();
-import { existsSync as existsSync11, readFileSync as readFileSync8 } from "fs";
-import { join as join11, dirname as dirname7 } from "path";
+import { existsSync as existsSync11, readFileSync as readFileSync7 } from "fs";
+import { join as join10, dirname as dirname7 } from "path";
 import { fileURLToPath as fileURLToPath3 } from "url";
 
 // src/lib/installer.ts
@@ -3670,6 +3689,7 @@ function rethrowHooksAuthorityFailure(error) {
   }
   throw new Error(`REMOTE_API_URL_INVALID: ${message} local mode fallback is disabled`, { cause: error });
 }
+var authorityBindings = new WeakMap;
 function resolveHooksTransport(env = process.env, options = {}) {
   if (selectsHooksLocalStore(env)) {
     announceLocal(options.notice, "HASNA_HOOKS_LOCAL is set and nothing configures a registry authority");
@@ -3683,7 +3703,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);
@@ -3691,18 +3711,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
   };
 }
 
@@ -4154,9 +4176,9 @@ var __dirname3 = dirname7(fileURLToPath3(import.meta.url));
 var pkg = { name: "@hasna/hooks", version: "0.0.0" };
 try {
   for (const rel of ["../../package.json", "../package.json", "../../../package.json"]) {
-    const p = join11(__dirname3, rel);
+    const p = join10(__dirname3, rel);
     if (existsSync11(p)) {
-      pkg = JSON.parse(readFileSync8(p, "utf-8"));
+      pkg = JSON.parse(readFileSync7(p, "utf-8"));
       break;
     }
   }
@@ -4168,7 +4190,7 @@ async function runVerifiedHook(name, stdin, timeoutMs) {
   if (!resolved || !hookScript || !existsSync11(hookScript)) {
     throw new Error(`Hook '${name}' not found`);
   }
-  const content = readFileSync8(hookScript);
+  const content = readFileSync7(hookScript);
   const sha = sha256Of(content);
   const check = checkScriptHash(name, sha);
   if (!check.ok) {
@@ -4394,14 +4416,14 @@ function createHooksServer() {
           continue;
         }
         const hookDir = getHookPath(name);
-        if (!existsSync11(join11(hookDir, "src", "hook.ts"))) {
+        if (!existsSync11(join10(hookDir, "src", "hook.ts"))) {
           issues.push({ hook: name, issue: "Missing src/hook.ts in package", severity: "error" });
           hookHealthy = false;
         }
       }
       if (meta && settingsExist) {
         try {
-          const settings = JSON.parse(readFileSync8(settingsPath, "utf-8"));
+          const settings = JSON.parse(readFileSync7(settingsPath, "utf-8"));
           if (!hookRegisteredInSettings(settings, name, meta.event, meta.matcher)) {
             const eventName = meta.event.split(":")[0];
             issues.push({ hook: name, issue: `Not registered under correct event (${eventName})`, severity: "error" });
@@ -4438,10 +4460,10 @@ function createHooksServer() {
         return { content: [{ type: "text", text: JSON.stringify({ error: `Hook '${name}' not found` }) }] };
       }
       const hookPath = getHookPath(name);
-      const readmePath = join11(hookPath, "README.md");
+      const readmePath = join10(hookPath, "README.md");
       let readme = "";
       if (existsSync11(readmePath)) {
-        readme = readFileSync8(readmePath, "utf-8");
+        readme = readFileSync7(readmePath, "utf-8");
       }
       if (verbose) {
         return { content: [{ type: "text", text: JSON.stringify({ ...meta, readme }) }] };
@@ -4771,7 +4793,7 @@ function createHooksServer() {
     let settings = {};
     try {
       if (existsSync11(settingsPath))
-        settings = JSON.parse(readFileSync8(settingsPath, "utf-8"));
+        settings = JSON.parse(readFileSync7(settingsPath, "utf-8"));
     } catch {}
     if (!settings.hooks)
       settings.hooks = {};
@@ -4794,7 +4816,7 @@ function createHooksServer() {
     let settings = {};
     try {
       if (existsSync11(settingsPath))
-        settings = JSON.parse(readFileSync8(settingsPath, "utf-8"));
+        settings = JSON.parse(readFileSync7(settingsPath, "utf-8"));
     } catch {}
     if (settings.hooks?.__disabled) {
       settings.hooks.__disabled = settings.hooks.__disabled.filter((n) => n !== name);