@hasna/hooks 0.9.5 → 0.9.6

package/dist/sdk/index.js

@@ -1194,7 +1194,7 @@ function resolveHooksTransport(env = process.env, options = {}) {
   };
 }
 
-// src/sdk/index.ts
+// src/sdk/authority.ts
 function resolveHooksSdkAuthority(env = process.env, options = {}) {
   if (selectsHooksLocalStore(env)) {
     throw new Error("REMOTE_COMMAND_UNSUPPORTED: @hasna/hooks/sdk is a hosted registry client and has no local mode; " + `${HOOKS_LOCAL_OPT_IN_HINT} selects the on-box SQLite store, which only the \`hooks\` CLI serves. ` + `Unset it and configure a registry credential (${HOOKS_CREDENTIAL_TIERS}).`);
@@ -1205,7 +1205,174 @@ function resolveHooksSdkAuthority(env = process.env, options = {}) {
   }
   return transport.authority;
 }
+// src/sdk/generated.ts
+class ApiError extends Error {
+  status;
+  body;
+  constructor(status, message, body) {
+    super(message);
+    this.status = status;
+    this.body = body;
+    this.name = "ApiError";
+  }
+}
 
+class HooksRegistryApiClient {
+  baseUrl;
+  apiKey;
+  fetchImpl;
+  baseHeaders;
+  constructor(options) {
+    if (!options.baseUrl)
+      throw new Error("HooksRegistryApiClient requires a baseUrl.");
+    this.baseUrl = options.baseUrl.replace(/\/$/, "");
+    this.apiKey = options.apiKey;
+    this.fetchImpl = options.fetch ?? globalThis.fetch;
+    this.baseHeaders = options.headers ?? {};
+  }
+  async request(method, path, opts) {
+    const url = new URL(this.baseUrl + path);
+    if (opts.query) {
+      for (const [key, value] of Object.entries(opts.query)) {
+        if (value === undefined || value === null)
+          continue;
+        if (Array.isArray(value)) {
+          for (const item of value) {
+            if (item !== undefined && item !== null)
+              url.searchParams.append(key, String(item));
+          }
+        } else {
+          url.searchParams.set(key, String(value));
+        }
+      }
+    }
+    const headers = { Accept: "application/json", ...this.baseHeaders, ...opts.init?.headers };
+    if (this.apiKey)
+      headers["x-api-key"] = this.apiKey;
+    let payload;
+    if (opts.body !== undefined) {
+      headers["Content-Type"] = "application/json";
+      payload = JSON.stringify(opts.body);
+    }
+    const response = await this.fetchImpl(url.toString(), { ...opts.init, method, headers, body: payload });
+    const text = await response.text();
+    const data = text ? (() => {
+      try {
+        return JSON.parse(text);
+      } catch {
+        return text;
+      }
+    })() : undefined;
+    if (!response.ok) {
+      throw new ApiError(response.status, `${method} ${path} failed: ${response.status}`, data);
+    }
+    return data;
+  }
+  async getCatalog(init) {
+    return this.request("GET", `/api/v1/catalog`, {
+      body: undefined,
+      query: undefined,
+      init
+    });
+  }
+  async putHook(body, init) {
+    return this.request("PUT", `/api/v1/hooks`, {
+      body,
+      query: undefined,
+      init
+    });
+  }
+  async getHookArtifact(name, version, init) {
+    return this.request("GET", `/api/v1/hooks/${encodeURIComponent(String(name))}/${encodeURIComponent(String(version))}`, {
+      body: undefined,
+      query: undefined,
+      init
+    });
+  }
+  async getLock(init) {
+    return this.request("GET", `/api/v1/lock`, {
+      body: undefined,
+      query: undefined,
+      init
+    });
+  }
+  async getHealth(init) {
+    return this.request("GET", `/health`, {
+      body: undefined,
+      query: undefined,
+      init
+    });
+  }
+  async getOpenApi(init) {
+    return this.request("GET", `/openapi.json`, {
+      body: undefined,
+      query: undefined,
+      init
+    });
+  }
+  async getReady(init) {
+    return this.request("GET", `/ready`, {
+      body: undefined,
+      query: undefined,
+      init
+    });
+  }
+  async getVersion(init) {
+    return this.request("GET", `/version`, {
+      body: undefined,
+      query: undefined,
+      init
+    });
+  }
+}
+// src/sdk/registry-client.ts
+function bindAuthority(client, authority) {
+  for (const [key, value] of [
+    ["authorityOrigin", authority.origin],
+    ["apiKeySource", authority.apiKeySource],
+    ["apiUrlSource", authority.apiUrlSource]
+  ]) {
+    Object.defineProperty(client, key, {
+      value,
+      enumerable: true,
+      writable: false,
+      configurable: false
+    });
+  }
+  return client;
+}
+function bindAuthorityFetch(authority, baseFetch = fetch) {
+  const expectedOrigin = new URL(authority.origin).origin;
+  return async (input, init) => {
+    const resolved = await resolveHooksRequestAuthority(authority);
+    const url = new URL(String(input));
+    if (url.origin !== expectedOrigin) {
+      throw new Error(`REMOTE_API_ORIGIN_MISMATCH: hooks registry request targeted ${url.origin}, ` + `not the resolved registry origin ${expectedOrigin}; no credential was sent.`);
+    }
+    const headers = new Headers(init?.headers);
+    headers.set("x-api-key", resolved.apiKey);
+    return baseFetch(url, {
+      ...init,
+      headers,
+      redirect: "manual"
+    });
+  };
+}
+function hooksRegistryApiClientFor(authority, options = {}) {
+  const boundFetch = bindAuthorityFetch(authority, options.fetch ?? fetch);
+  const client = new HooksRegistryApiClient({
+    baseUrl: authority.origin,
+    fetch: boundFetch
+  });
+  return bindAuthority(client, authority);
+}
+function createHooksRegistryApiClient(options = {}) {
+  const authority = resolveHooksSdkAuthority(options.env ?? process.env, {
+    credentials: options.credentials
+  });
+  return hooksRegistryApiClientFor(authority, { fetch: options.fetch });
+}
+// src/sdk/index.ts
 class HooksClient {
   origin;
   v1BaseUrl;
@@ -1274,6 +1441,10 @@ function createHooksClient(options = {}) {
 export {
   resolveHooksSdkAuthority,
   hooksRegistryOrigin,
+  hooksRegistryApiClientFor,
+  createHooksRegistryApiClient,
   createHooksClient,
+  ApiError as HooksRegistryApiError,
+  HooksRegistryApiClient,
   HooksClient
 };

package/dist/sdk/registry-client.d.ts

@@ -0,0 +1,75 @@
+/**
+ * `@hasna/hooks` — resolver-backed factory for the generated registry client.
+ *
+ * The generated {@link HooksRegistryApiClient} takes an explicit
+ * `baseUrl`/`apiKey` and has no environment surface of its own. This module is
+ * the ONE adapter from that client onto the @hasna/contracts credential chain
+ * (owner ruling 2026-09-04, hasna/apps#1720) so callers never write a private
+ * copy of the chain — the same rule `HooksClient` (src/sdk/index.ts) follows.
+ *
+ * FOUR PROPERTIES THIS ADAPTER EXISTS TO KEEP, matching `HooksClient`:
+ *
+ *   1. FAIL CLOSED. `resolveHooksSdkAuthority` refuses the local opt-in by
+ *      name and throws `REMOTE_API_*` (naming every tier it consulted) when
+ *      nothing resolves. A client is never built that would answer from a
+ *      local file, and an unauthenticated client is never built at all.
+ *
+ *   2. FRESH PER REQUEST. The credential is re-resolved on every dispatch
+ *      through `resolveHooksRequestAuthority`, so a rotation or a vault
+ *      pointer resolves again for each request instead of being frozen at
+ *      construction — and a changed authority binding refuses the request
+ *      rather than sending the previous credential to the new URL.
+ *
+ *   3. NEVER FOLLOW A REDIRECT. The generated client does not set `redirect`,
+ *      which would make fetch follow a 3xx and carry `x-api-key` to another
+ *      origin. The adapter forces `redirect: "manual"` for every dispatch,
+ *      after the caller's init, so it cannot be overridden.
+ *
+ *   4. STAY ON THE RESOLVED ORIGIN. The adapter refuses any dispatch whose
+ *      URL is not exactly the resolved registry origin, so a malformed path
+ *      can never turn the credential into a cross-origin request.
+ */
+import { type HooksRemoteAuthority } from "../lib/transport.js";
+import { type HooksClientOptions } from "./authority.js";
+import { HooksRegistryApiClient } from "./generated.js";
+/** The transport's fetch shape (Bun's global fetch carries extra static props). */
+type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+/** The fields a resolver-backed client exposes for diagnostics. Never a value. */
+export interface HooksRegistryApiClientAuthority {
+    /** Registry origin WITHOUT `/v1`; the registry routes hang off `<origin>/api/v1`. */
+    readonly authorityOrigin: string;
+    /** WHERE the credential came from (env NAME, Keychain reference, file PATH). Never a value. */
+    readonly apiKeySource: string | null;
+    /** WHERE the authority came from. Never a value. */
+    readonly apiUrlSource: string | null;
+}
+/** A generated registry client bound to a resolved authority. */
+export type ResolvedHooksRegistryApiClient = HooksRegistryApiClient & HooksRegistryApiClientAuthority;
+/**
+ * Bind an already-resolved authority to a fetch implementation: every dispatch
+ * re-resolves the credential, pins the origin and refuses to follow redirects.
+ *
+ * Exported so the two guards below are directly testable — they are
+ * defense-in-depth for a dispatch path the generated client does not otherwise
+ * let you reach with a foreign URL.
+ */
+export declare function bindAuthorityFetch(authority: HooksRemoteAuthority, baseFetch?: FetchLike): FetchLike;
+/**
+ * Bind the generated client to an already-resolved authority: every dispatch
+ * re-resolves the credential, pins the origin and refuses to follow redirects.
+ *
+ * Exported for callers that hold an authority (e.g. `HooksClient`'s
+ * `#authority`) rather than an env object.
+ */
+export declare function hooksRegistryApiClientFor(authority: HooksRemoteAuthority, options?: {
+    fetch?: typeof fetch;
+}): ResolvedHooksRegistryApiClient;
+/**
+ * Resolve the hosted registry authority (fail closed) and return a generated
+ * client bound to it.
+ *
+ * Throws — never returns a local fallback — when nothing resolves, and refuses
+ * the local opt-in by name: there is no SDK surface for the on-box store.
+ */
+export declare function createHooksRegistryApiClient(options?: HooksClientOptions): ResolvedHooksRegistryApiClient;
+export {};

package/hooks/native-safety-entry.ts

@@ -0,0 +1,28 @@
+import { homedir } from "node:os";
+import { isAbsolute } from "node:path";
+import { evaluate as evaluateTrash, findTrashBinary, scanCommand } from "./hook-trash-guard/src/hook";
+import { evaluate as evaluateRepos } from "./hook-workspace-repos-guard/src/hook";
+import type { CodewithHookInput } from "./codewith-native-common";
+
+// Bundled with import.meta.main=false, so the original standalone run wrappers
+// cannot swallow exceptions or emit a second response. Only this entry runs.
+const name = process.argv[1];
+if (name !== "trash-guard" && name !== "workspace-repos-guard") throw new Error("Invalid safety capability");
+const input = JSON.parse(await Bun.stdin.text()) as CodewithHookInput;
+if (!input || Array.isArray(input) || input.hook_event_name !== "PreToolUse" || typeof input.tool_name !== "string"
+  || !input.tool_input || typeof input.tool_input !== "object" || Array.isArray(input.tool_input)
+  || typeof input.cwd !== "string" || !isAbsolute(input.cwd)) throw new Error("Invalid safety input");
+if (input.tool_name === "Bash" && typeof input.tool_input.command !== "string") throw new Error("Invalid shell input");
+if (["apply_patch", "ApplyPatch", "functions.apply_patch"].includes(input.tool_name)) {
+  if (input.tool_input.command !== undefined && input.tool_input.patch !== undefined && input.tool_input.command !== input.tool_input.patch) throw new Error("Conflicting patch aliases");
+  const patch = input.tool_input.command ?? input.tool_input.patch;
+  if (typeof patch !== "string") throw new Error("Invalid patch input");
+  input.tool_input = { ...input.tool_input, command: patch, patch };
+}
+const repos = evaluateRepos(input).output;
+const handoff = input.tool_name === "Bash" && scanCommand(input.tool_input.command as string, { home: homedir(), cwd: input.cwd }).handoffHits.length > 0;
+const verdict = repos.decision === "block"
+  ? { hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason: repos.reason } }
+  : handoff ? { hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason: "[workspace-repos-guard] Deletion under a protected repository checkout is refused." } }
+  : name === "trash-guard" ? evaluateTrash(input, { home: homedir(), cwd: input.cwd, findTrash: findTrashBinary }) : { continue: true };
+process.stdout.write(JSON.stringify({ verdict: "continue" in verdict ? null : verdict }));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/hooks",
-  "version": "0.9.5",
+  "version": "0.9.6",
   "description": "Open source hooks library for AI coding agents - Install safety, quality, and automation hooks with a single command",
   "type": "module",
   "bin": {
@@ -25,8 +25,10 @@
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "scripts": {
-    "build": "rm -rf dist bin && bun build ./src/cli/index.tsx --outdir ./bin --target bun --external pg --external ink --external react --external chalk --external conf --external @modelcontextprotocol/sdk --external zod && bun build ./src/serve.ts --outdir ./bin --target bun --external pg && bun build ./src/mcp/hooks-mcp.ts --outdir ./bin --target bun --external pg --external chalk --external conf --external @modelcontextprotocol/sdk --external zod && bun build ./src/sdk/index.ts --outdir ./dist/sdk --target bun && bun build ./src/index.ts ./src/storage.ts --outdir ./dist --target bun --external pg && bun run build:types",
+    "build": "rm -rf dist bin && bun build ./src/cli/index.tsx --outdir ./bin --target bun --external pg --external ink --external react --external chalk --external conf --external @modelcontextprotocol/sdk --external zod && bun build ./src/serve.ts --outdir ./bin --target bun --external pg && bun build ./src/mcp/hooks-mcp.ts --outdir ./bin --target bun --external pg --external chalk --external conf --external @modelcontextprotocol/sdk --external zod && bun build ./src/sdk/index.ts --outdir ./dist/sdk --target bun && bun build ./src/index.ts ./src/storage.ts --outdir ./dist --target bun --external pg && bun run build:native-safety && bun run build:types",
     "build:types": "tsc -p tsconfig.build.json",
+    "generate:sdk": "bun run scripts/generate-sdk.ts",
+    "verify:generated": "bun run scripts/verify-generated-artifacts.ts",
     "dev": "bun run ./src/cli/index.tsx",
     "test": "bun test",
     "typecheck": "tsc --noEmit",
@@ -34,7 +36,8 @@
     "prepublishOnly": "bun run validate:package",
     "postinstall": "node scripts/ensure-profiles-dir.mjs",
     "scan:artifact": "bun scripts/artifact-scan.ts",
-    "prepack": "bun run build && bun run scan:artifact"
+    "prepack": "bun run build && bun run scan:artifact",
+    "build:native-safety": "bun build ./hooks/native-safety-entry.ts --outdir ./bin --target bun --define import.meta.main=false"
   },
   "keywords": [
     "claude-code",
@@ -54,7 +57,7 @@
     "@types/react": "^18.2.0",
     "typescript": "^5",
     "bun-types": "1.3.14",
-    "@hasna/contracts": "1.2.1"
+    "@hasna/contracts": "~1.2.1"
   },
   "dependencies": {
     "@hasna/events": "^0.1.16",

package/scripts/generate-sdk.ts

@@ -0,0 +1,60 @@
+#!/usr/bin/env bun
+/**
+ * Regenerate the typed @hasna/hooks registry client from the serve OpenAPI
+ * document.
+ *
+ *   bun run generate:sdk
+ *
+ * Output: src/sdk/generated.ts — a dependency-free fetch client plus the
+ * interfaces derived from the document, produced by `@hasna/contracts`'
+ * `generateSdkFromOpenApi` (the fleet generator: apps/logs, apps/telephony
+ * and apps/todos use the same helper). Do not hand-edit the output; change
+ * `src/openapi.ts` and rerun this.
+ *
+ * THE SPEC IS THE SERVED ONE. `buildOpenApiDocument(version)` is the exact
+ * object `GET /openapi.json` returns (src/serve.ts), so the committed client
+ * and the served contract cannot describe different routes. That is what
+ * makes the `serviceSurfaces[3].generatedFrom` declaration in
+ * hasna.contract.json (`/openapi.json`) true rather than aspirational:
+ * `scripts/verify-generated-artifacts.ts` re-runs this script and
+ * byte-compares the result so the claim stays true (AGE11-00571).
+ *
+ * `@hasna/contracts` is a BUILD-TIME devDependency import; it is never a
+ * runtime dependency of the published bundle.
+ */
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { generateSdkFromOpenApi } from "@hasna/contracts/sdk";
+import { buildOpenApiDocument } from "../src/openapi.js";
+
+const appRoot = join(dirname(fileURLToPath(import.meta.url)), "..");
+
+/** The same value src/serve.ts's packageVersion() puts in the served document. */
+function packageVersion(): string {
+  const pkgPath = join(appRoot, "package.json");
+  if (!existsSync(pkgPath)) throw new Error(`generate-sdk: package.json not found at ${pkgPath}`);
+  const parsed = JSON.parse(readFileSync(pkgPath, "utf-8")) as { version?: string };
+  if (!parsed.version) throw new Error("generate-sdk: package.json carries no version");
+  return parsed.version;
+}
+
+const version = packageVersion();
+const generated = generateSdkFromOpenApi(buildOpenApiDocument(version), {
+  className: "HooksRegistryApiClient",
+  apiKeyHeader: "x-api-key",
+});
+
+const outFile = join(appRoot, "src", "sdk", "generated.ts");
+const header = [
+  `// @generated from the @hasna/hooks serve OpenAPI document (${version}) by scripts/generate-sdk.ts.`,
+  "// DO NOT EDIT. Regenerate: bun run generate:sdk",
+  "",
+  "",
+].join("\n");
+writeFileSync(outFile, header + generated.code, "utf8");
+
+console.log(
+  `generate-sdk: wrote src/sdk/generated.ts — ${generated.operations.length} operations from /openapi.json`,
+);
+for (const warning of generated.warnings) console.warn(`generate-sdk: warning: ${warning}`);

package/scripts/validate-package.ts

@@ -180,6 +180,8 @@ for (const [name, body] of [
   mkdirSync(folder, { recursive: true });
   writeFileSync(join(folder, "credentials"), body, { mode: 0o600 });
 }
+
+
 let value = "fixture-first-key", vaultStatus = 200, reads = 0;
 const keys = [];
 globalThis.fetch = async (input, init) => {
@@ -221,6 +223,37 @@ console.log("packed credential-file reference, rotation and terminal failure pas
  * Lanes: CLI help, serve /health, MCP stdio startup (initialize handshake),
  * a runtime SDK import, and one bundled-hook run with an isolated data dir.
  */
+async function validatePackedNativeSafety(packageDir: string, smokeDir: string): Promise<void> {
+  const home = join(smokeDir, "native-safety-home");
+  await mkdir(home, { mode: 0o700 });
+  const settings = join(home, ".codex", "hooks.json");
+  const env: NodeJS.ProcessEnv = { ...process.env, HOME: home, HASNA_STATION: "no-such-station", HASNA_HOOKS_CODEX_SETTINGS_PATH: settings };
+  for (const key of Object.keys(env)) if (/^(HASNA_HOOKS_|HOOKS_)/.test(key) && key !== "HASNA_HOOKS_CODEX_SETTINGS_PATH") delete env[key];
+  const cli = join(packageDir, "bin/index.js");
+  const installed = spawnSync(process.execPath, [cli, "safety", "install", "trash-guard", "--target", "codex"], { cwd: smokeDir, env, encoding: "utf8", timeout: 15_000 });
+  if (installed.status !== 0 || !JSON.parse(installed.stdout).success) throw new Error("Packed native safety registration failed");
+  if (existsSync(join(home, ".hasna", "hooks"))) throw new Error("Stateless safety registration created app state");
+  const native = JSON.parse(await readFile(settings, "utf8"));
+  const command = native.hooks.PreToolUse[0].hooks[0].command;
+  const input = (text: string) => JSON.stringify({ hook_event_name: "PreToolUse", tool_name: "Bash", cwd: home, tool_input: { command: text } });
+  const invoke = (text: string) => spawnSync("/bin/sh", ["-c", command], { cwd: home, env, input: input(text), encoding: "utf8", timeout: 9_000 });
+  const benign = invoke("pwd");
+  if (benign.status !== 0 || benign.stdout !== "" || benign.stderr !== "") throw new Error("Packed native benign verdict failed");
+  const refused = invoke(`rm -- ${join(home, "owned-fixture")}`);
+  if (refused.status !== 0 || JSON.parse(refused.stdout).hookSpecificOutput.permissionDecision !== "deny") throw new Error("Packed native missing-Trash refusal failed");
+  const probe = join(smokeDir, "native-registration.ts");
+  await writeFile(probe, `import { getRegisteredHooksForTarget } from "@hasna/hooks"; console.log(JSON.stringify(getRegisteredHooksForTarget("global", "codex")));`);
+  const listed = spawnSync(process.execPath, [probe], { cwd: smokeDir, env, encoding: "utf8", timeout: 15_000 });
+  if (listed.status !== 0 || JSON.stringify(JSON.parse(listed.stdout)) !== '["trash-guard"]') throw new Error("Packed SDK cannot recognize the compiled CLI safety registration");
+  const worker = join(packageDir, "bin/native-safety-entry.js");
+  const bytes = await readFile(worker);
+  try {
+    await writeFile(worker, Buffer.concat([bytes, Buffer.from("\n// changed fixture\n")]));
+    const changed = invoke("rm -- owned-fixture");
+    if (changed.status !== 2 || changed.stdout !== "" || !changed.stderr.includes("safety guard refused")) throw new Error("Packed native modified-bundle refusal failed");
+  } finally { await writeFile(worker, bytes); }
+}
+
 async function validateExtractedSmoke(pkg: PackageJson): Promise<void> {
   const tempRoot = join(root, "temp");
   await mkdir(tempRoot, { recursive: true });
@@ -352,6 +385,7 @@ async function validateExtractedSmoke(pkg: PackageJson): Promise<void> {
     if (typeof sdkOut.count !== "number" || sdkOut.count <= 0) throw new Error(`packed SDK import returned count ${sdkOut.count}`);
     if (sdkOut.sdk !== "fail-closed" || !sdkOut.hasClient) throw new Error(`packed ./sdk export did not fail closed with nothing configured: ${JSON.stringify(sdkOut)}`);
     await validatePackedCredentialReferences(pkg, packageDir, smokeDir);
+    await validatePackedNativeSafety(packageDir, smokeDir);
 
     // 5. One bundled-hook run from the packed artifact (isolated data dir;
     // first run self-trusts, then executes).