@hasna/hooks 0.9.4 → 0.9.6

package/bin/serve.js

@@ -174,6 +174,7 @@ var HOOKS = [
   },
   {
     name: "workspace-repos-guard",
+    timeoutSeconds: 10,
     displayName: "Workspace Repos Guard",
     description: "Blocks writes and deletes that break the protected repo-checkout structure (~/.hasna/repos/clones canonical, plus legacy ~/workspace/repos during the migration window): writes to a protected root, top-level entry creation, non-org folders, and any delete under a protected root",
     version: "0.1.0",
@@ -192,7 +193,7 @@ var HOOKS = [
     matcher: "^(Bash|apply_patch|ApplyPatch|functions\\.apply_patch)$",
     tags: ["rm", "delete", "trash", "recoverable", "guard", "safety", "bash"],
     rewritesInput: true,
-    timeoutSeconds: 5
+    timeoutSeconds: 10
   },
   {
     name: "checktests",
@@ -5358,16 +5359,21 @@ function resolveHook(name) {
 
 // src/serve.ts
 import { readFileSync as readFileSync5 } from "fs";
-import { dirname as dirname3, join as join8 } from "path";
-import { fileURLToPath as fileURLToPath2 } from "url";
+import { dirname as dirname4, join as join8 } from "path";
+import { fileURLToPath as fileURLToPath5 } from "url";
 
-// ../../node_modules/.bun/@hasna+contracts@1.0.2+e0db24ae03127387/node_modules/@hasna/contracts/dist/client/transport.js
+// ../contracts/dist/client/transport.js
 import { spawnSync } from "child_process";
-import { closeSync, fstatSync, openSync, readFileSync as readFileSync4 } 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 join7 } from "path";
+import { isAbsolute as isAbsolute2, join as join22 } from "path";
+import { createRequire } from "module";
+import { fileURLToPath as fileURLToPath2 } from "url";
+import { closeSync, fstatSync, lstatSync, openSync, readFileSync as readFileSync4, realpathSync as realpathSync2, statSync } from "fs";
+import { O_NOFOLLOW, O_NONBLOCK, O_RDONLY } from "constants";
+import { basename as basename2, dirname as dirname3, join as join7, relative, sep as sep2 } from "path";
+import { fileURLToPath as fileURLToPath3, pathToFileURL } from "url";
 function envToken(name) {
   return name.toUpperCase().replace(/-/g, "_");
 }
@@ -5385,6 +5391,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 = realpathSync2(directory);
+  const fd = openSync(join7(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(readFileSync4(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 = realpathSync2(join7(root, ...parts));
+  const within = relative(root, file);
+  if (!within || within === ".." || within.startsWith(`..${sep2}`) || !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 = dirname3(fileURLToPath3(parentUrl));
+  for (;; ) {
+    if (basename2(directory) !== "node_modules") {
+      const candidate = join7(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 = dirname3(directory);
+    if (parent === directory)
+      throw new Error("Secrets SDK is not installed for this consumer");
+    directory = parent;
+  }
+}
 
 class CredentialResolutionError extends Error {
   appName;
@@ -5433,14 +5547,14 @@ function hasnaHomeDir(env) {
   if (override)
     return override;
   const home = homeDir(env);
-  return home ? join7(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 join7(configRoot, name);
+    return join22(configRoot, name);
   const root = hasnaHomeDir(env);
-  return root ? join7(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))
@@ -5449,7 +5563,7 @@ function credentialDiskSourceList(name, env, profile = null) {
   if (!directory)
     return [];
   const file = profile ? `${CREDENTIALS_FILE}-${profile}` : CREDENTIALS_FILE;
-  return [{ path: join7(directory, file), tier: "disk" }];
+  return [{ path: join22(directory, file), tier: "disk" }];
 }
 function credentialDiskSources(name, env) {
   return credentialDiskSourceList(name, env, null).map((s) => s.path);
@@ -5503,7 +5617,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")
@@ -5513,7 +5627,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)) {
@@ -5524,31 +5638,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 = readFileSync4(fd);
-    const after = fstatSync(fd);
+    const bytes = readFileSync22(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] };
 }
 function assertUsableCredential(appName, source, value) {
   if (VAULT_POINTER_SHAPE.test(value)) {
@@ -5781,12 +5903,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,
@@ -5794,7 +5917,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);
@@ -5819,17 +5942,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,
@@ -5850,8 +5983,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 IDEMPOTENT_METHODS = new Set(["GET", "HEAD", "PUT", "DELETE", "OPTIONS"]);
 var AUTHORITY_OVERRIDE_HEADERS = new Set([
   "host",
@@ -5899,11 +6078,25 @@ function hooksResolverInputs(env, credentials = {}) {
 }
 
 // src/lib/transport.ts
-function resolveHooksServePublishKey(env = process.env, options = {}) {
+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 resolveHooksServePublishKeyAsync(env = process.env, options = {}) {
   const { env: resolverEnv, credentials } = hooksResolverInputs(env, options.credentials);
-  const tier1 = options.credentials?.apiKey;
-  const credentialOptions = tier1 !== undefined ? { ...credentials, apiKey: tier1 } : credentials;
-  return resolveCredential("hooks", resolverEnv, credentialOptions)?.apiKey;
+  const read = () => resolveCredential("hooks", resolverEnv, credentials);
+  const selected = read();
+  if (!selected || selected.tier !== "pointer")
+    return selected?.apiKey;
+  if (!sameCredential(selected, read()))
+    changedBinding();
+  const completed = await completePointerCredential("hooks", selected, env);
+  if (!sameCredential(selected, read()))
+    changedBinding();
+  return completed.apiKey;
 }
 
 // src/lib/secure-compare.ts
@@ -5912,163 +6105,364 @@ function secureEqual(a, b) {
   const ab = enc.encode(a);
   const bb = enc.encode(b);
   let diff = ab.length ^ bb.length;
-  const n = Math.max(ab.length, bb.length);
-  for (let i = 0;i < n; i++) {
+  const n2 = Math.max(ab.length, bb.length);
+  for (let i = 0;i < n2; i++) {
     diff |= (ab[i] ?? 0) ^ (bb[i] ?? 0);
   }
   return diff === 0;
 }
 
 // src/openapi.ts
-var openApiDocument = {
-  openapi: "3.1.0",
-  info: {
-    title: "Hooks Registry API",
-    version: "0.1.0",
-    description: "Local registry HTTP API for @hasna/hooks: catalog, lock, and artifact reads are open; publishing (PUT /api/v1/hooks) requires the API key (authorization: Bearer or x-api-key)."
-  },
-  servers: [{ url: "/" }],
-  paths: {
-    "/health": {
-      get: {
-        summary: "Liveness probe",
-        operationId: "getHealth",
-        responses: {
-          "200": {
-            description: "Service is alive",
-            content: {
-              "application/json": {
-                schema: { type: "object", additionalProperties: true }
+function buildOpenApiDocument(version) {
+  return {
+    openapi: "3.1.0",
+    info: {
+      title: "Hooks Registry API",
+      version,
+      description: "Local registry HTTP API for @hasna/hooks: catalog, lock, and artifact reads are open; publishing (PUT /api/v1/hooks) requires the API key (authorization: Bearer or x-api-key)."
+    },
+    servers: [{ url: "/" }],
+    paths: {
+      "/health": {
+        get: {
+          summary: "Liveness probe",
+          operationId: "getHealth",
+          responses: {
+            "200": {
+              description: "Service is alive",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/HooksHealth" }
+                }
               }
             }
           }
         }
-      }
-    },
-    "/ready": {
-      get: {
-        summary: "Readiness probe \u2014 the hooks.lock store is readable",
-        operationId: "getReady",
-        responses: {
-          "200": { description: "Lock store is readable" },
-          "503": { description: "Lock store is not readable" }
+      },
+      "/ready": {
+        get: {
+          summary: "Readiness probe \u2014 the hooks.lock store is readable",
+          operationId: "getReady",
+          responses: {
+            "200": {
+              description: "Lock store is readable",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/HooksHealth" }
+                }
+              }
+            },
+            "503": {
+              description: "Lock store is not readable",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/HooksHealth" }
+                }
+              }
+            }
+          }
         }
-      }
-    },
-    "/version": {
-      get: {
-        summary: "Package version",
-        operationId: "getVersion",
-        responses: {
-          "200": {
-            description: "The installed @hasna/hooks version",
-            content: {
-              "application/json": {
-                schema: { type: "object", properties: { version: { type: "string" } } }
+      },
+      "/version": {
+        get: {
+          summary: "Package version",
+          operationId: "getVersion",
+          responses: {
+            "200": {
+              description: "The installed @hasna/hooks version",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/HooksVersion" }
+                }
               }
             }
           }
         }
-      }
-    },
-    "/openapi.json": {
-      get: {
-        summary: "This OpenAPI document",
-        operationId: "getOpenApi",
-        responses: { "200": { description: "OpenAPI 3.1 document" } }
-      }
-    },
-    "/api/v1/catalog": {
-      get: {
-        summary: "List the full hook catalog with versions and sha256",
-        operationId: "getCatalog",
-        responses: {
-          "200": {
-            description: "Catalog entries",
-            content: {
-              "application/json": {
-                schema: {
-                  type: "object",
-                  properties: {
-                    hooks: {
-                      type: "array",
-                      items: {
-                        type: "object",
-                        properties: {
-                          name: { type: "string" },
-                          version: { type: "string" },
-                          sha256: { type: "string" },
-                          events: { type: "array", items: { type: "string" } }
-                        }
-                      }
-                    }
-                  }
+      },
+      "/openapi.json": {
+        get: {
+          summary: "This OpenAPI document",
+          operationId: "getOpenApi",
+          responses: {
+            "200": {
+              description: "OpenAPI 3.1 document",
+              content: {
+                "application/json": {
+                  schema: { type: "object", additionalProperties: true }
                 }
               }
             }
           }
         }
-      }
-    },
-    "/api/v1/lock": {
-      get: {
-        summary: "Read the published hooks.lock with per-hook versions",
-        operationId: "getLock",
-        responses: { "200": { description: "The lock file" } }
-      }
-    },
-    "/api/v1/hooks/{name}/{version}": {
-      get: {
-        summary: "Fetch one hook's manifest and script",
-        operationId: "getHookArtifact",
-        parameters: [
-          { name: "name", in: "path", required: true, schema: { type: "string" } },
-          { name: "version", in: "path", required: true, schema: { type: "string" } }
-        ],
-        responses: {
-          "200": {
-            description: "Hook artifact; x-hook-sha256 header carries the script hash"
+      },
+      "/api/v1/catalog": {
+        get: {
+          summary: "List the full hook catalog with versions and sha256",
+          operationId: "getCatalog",
+          responses: {
+            "200": {
+              description: "Catalog entries",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/HooksCatalog" }
+                }
+              }
+            }
+          }
+        }
+      },
+      "/api/v1/lock": {
+        get: {
+          summary: "Read the published hooks.lock with per-hook versions",
+          operationId: "getLock",
+          responses: {
+            "200": {
+              description: "The lock file",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/HooksLock" }
+                }
+              }
+            }
+          }
+        }
+      },
+      "/api/v1/hooks/{name}/{version}": {
+        get: {
+          summary: "Fetch one hook's manifest and script",
+          operationId: "getHookArtifact",
+          parameters: [
+            { name: "name", in: "path", required: true, schema: { type: "string" } },
+            { name: "version", in: "path", required: true, schema: { type: "string" } }
+          ],
+          responses: {
+            "200": {
+              description: "Hook artifact; x-hook-sha256 header carries the script hash",
+              headers: {
+                "x-hook-sha256": {
+                  description: "sha256 of the served script, the same value the lock pins",
+                  schema: { type: "string" }
+                }
+              },
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/HooksArtifact" }
+                }
+              }
+            },
+            "400": {
+              description: "Invalid URL encoding or semver version",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/HooksError" }
+                }
+              }
+            },
+            "404": {
+              description: "Hook not found locally",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/HooksError" }
+                }
+              }
+            }
+          }
+        }
+      },
+      "/api/v1/hooks": {
+        put: {
+          summary: "Publish/retrust a hook (requires the API key)",
+          operationId: "putHook",
+          requestBody: {
+            required: true,
+            content: {
+              "application/json": {
+                schema: { $ref: "#/components/schemas/HooksPublishRequest" }
+              }
+            }
           },
-          "400": { description: "Invalid URL encoding or semver version" },
-          "404": { description: "Hook not found locally" }
+          responses: {
+            "200": {
+              description: "Hook retrusted and pin updated",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/HooksPublishResponse" }
+                }
+              }
+            },
+            "400": {
+              description: "Invalid JSON body",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/HooksError" }
+                }
+              }
+            },
+            "401": {
+              description: "Missing or invalid API key",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/HooksError" }
+                }
+              }
+            },
+            "404": {
+              description: "Hook not found in local store",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/HooksError" }
+                }
+              }
+            },
+            "409": {
+              description: "Version mismatch with the local store",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/HooksError" }
+                }
+              }
+            }
+          },
+          security: [{ apiKey: [] }]
         }
       }
     },
-    "/api/v1/hooks": {
-      put: {
-        summary: "Publish/retrust a hook (requires the API key)",
-        operationId: "putHook",
-        requestBody: {
-          required: true,
-          content: {
-            "application/json": {
-              schema: {
-                type: "object",
-                properties: { name: { type: "string" }, version: { type: "string" } }
-              }
+    components: {
+      securitySchemes: {
+        apiKey: {
+          type: "http",
+          scheme: "bearer",
+          description: "The registry API key \u2014 resolved by the client through the @hasna/contracts chain (HASNA_HOOKS_API_KEY, the Keychain item hasna.credentials.hooks.api-key, or ~/.hasna/hooks/config/credentials); the server compares the inbound bearer/x-api-key value."
+        }
+      },
+      schemas: {
+        HooksHealth: {
+          type: "object",
+          additionalProperties: false,
+          required: ["status", "name"],
+          properties: {
+            status: { type: "string" },
+            name: { type: "string" }
+          }
+        },
+        HooksVersion: {
+          type: "object",
+          additionalProperties: false,
+          required: ["version"],
+          properties: { version: { type: "string" } }
+        },
+        HooksCatalogEntry: {
+          type: "object",
+          additionalProperties: false,
+          required: ["name", "version", "sha256", "events", "description", "source", "versions"],
+          properties: {
+            name: { type: "string" },
+            version: { type: "string" },
+            sha256: { type: "string" },
+            events: { type: "array", items: { type: "string" } },
+            description: { type: "string" },
+            source: {
+              type: "string",
+              description: "bundled | custom | custom-overrides-bundled"
+            },
+            versions: { type: "array", items: { type: "string" } }
+          }
+        },
+        HooksCatalog: {
+          type: "object",
+          additionalProperties: false,
+          required: ["hooks"],
+          properties: {
+            hooks: { type: "array", items: { $ref: "#/components/schemas/HooksCatalogEntry" } }
+          }
+        },
+        HooksLockEntry: {
+          type: "object",
+          additionalProperties: false,
+          required: ["version", "sha256", "source"],
+          properties: {
+            version: { type: "string" },
+            sha256: { type: "string" },
+            source: { type: "string" },
+            pinned: {
+              type: "boolean",
+              description: "True for an explicit install/update pin, absent for sync-maintained pins."
+            },
+            versions: { type: "array", items: { type: "string" } }
+          }
+        },
+        HooksLock: {
+          type: "object",
+          additionalProperties: false,
+          required: ["hooks"],
+          properties: {
+            hooks: {
+              type: "object",
+              additionalProperties: { $ref: "#/components/schemas/HooksLockEntry" }
             }
           }
         },
-        responses: {
-          "200": { description: "Hook retrusted and pin updated" },
-          "401": { description: "Missing or invalid API key" },
-          "404": { description: "Hook not found in local store" },
-          "409": { description: "Version mismatch with the local store" }
+        HooksManifest: {
+          type: "object",
+          additionalProperties: false,
+          required: ["name", "version", "events", "script"],
+          properties: {
+            name: { type: "string" },
+            version: { type: "string" },
+            description: { type: "string" },
+            events: { type: "array", items: { type: "string" } },
+            script: { type: "string" },
+            script_kind: { type: "string", enum: ["inline", "file"] },
+            args: { type: "array", items: { type: "string" } },
+            timeout_ms: { type: "number" }
+          }
         },
-        security: [{ apiKey: [] }]
-      }
-    }
-  },
-  components: {
-    securitySchemes: {
-      apiKey: {
-        type: "http",
-        scheme: "bearer",
-        description: "The registry API key \u2014 resolved by the client through the @hasna/contracts chain (HASNA_HOOKS_API_KEY, the Keychain item hasna.credentials.hooks.api-key, or ~/.hasna/hooks/config/credentials); the server compares the inbound bearer/x-api-key value."
+        HooksArtifact: {
+          type: "object",
+          additionalProperties: false,
+          required: ["manifest", "script"],
+          properties: {
+            manifest: { $ref: "#/components/schemas/HooksManifest" },
+            script: { type: "string" }
+          }
+        },
+        HooksError: {
+          type: "object",
+          additionalProperties: false,
+          required: ["error"],
+          properties: { error: { type: "string" } }
+        },
+        HooksPublishRequest: {
+          type: "object",
+          additionalProperties: false,
+          required: ["name"],
+          properties: {
+            name: { type: "string" },
+            version: { type: "string" }
+          }
+        },
+        HooksPublishResponse: {
+          type: "object",
+          additionalProperties: false,
+          required: ["ok", "hook"],
+          properties: {
+            ok: { type: "boolean" },
+            hook: {
+              type: "object",
+              additionalProperties: false,
+              required: ["name", "version", "sha256"],
+              properties: {
+                name: { type: "string" },
+                version: { type: "string" },
+                sha256: { type: "string" }
+              }
+            }
+          }
+        }
       }
     }
-  }
-};
+  };
+}
 
 // src/serve.ts
 var DEFAULT_SERVE_PORT = 39428;
@@ -6076,7 +6470,7 @@ var SERVE_HOST = "127.0.0.1";
 var SERVE_SERVICE_NAME = "hooks-registry";
 function packageVersion() {
   try {
-    const pkgPath = join8(dirname3(fileURLToPath2(import.meta.url)), "..", "package.json");
+    const pkgPath = join8(dirname4(fileURLToPath5(import.meta.url)), "..", "package.json");
     return JSON.parse(readFileSync5(pkgPath, "utf-8")).version || "0.0.0";
   } catch {
     return "0.0.0";
@@ -6166,7 +6560,7 @@ function handleServeRequest(req, apiKey) {
     return Promise.resolve(json({ version: packageVersion() }));
   }
   if (url.pathname === "/openapi.json" && req.method === "GET") {
-    return Promise.resolve(json(openApiDocument));
+    return Promise.resolve(json(buildOpenApiDocument(packageVersion())));
   }
   if (url.pathname === "/api/v1/catalog" && req.method === "GET") {
     return buildCatalog().then((catalog) => json({ hooks: catalog }));
@@ -6238,7 +6632,7 @@ function startServeServer(options) {
     hostname: host,
     port,
     async fetch(req) {
-      return handleServeRequest(req, resolveHooksServePublishKey());
+      return handleServeRequest(req, await resolveHooksServePublishKeyAsync());
     }
   });
   console.error(`hooks registry listening on http://${host}:${server.port} (publish requires an API key)`);