@hasna/hooks 0.6.4 → 0.6.6

package/dist/lib/hook-env.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Hook child-process environment — a fixed allowlist plus a name-based deny
+ * list (P1-1 env isolation).
+ *
+ * A hook executes third-party bytes inside the agent's session. Passing the
+ * parent's process.env wholesale hands every credential the agent can reach
+ * to arbitrary code. The child gets:
+ *
+ *   1. a fixed allowlist of non-secret session variables (PATH, HOME, LANG,
+ *      TZ, SHELL, TERM, USER, PWD);
+ *   2. non-secret HOOKS_* projections of the parent's HASNA_HOOKS_* config
+ *      (data dir, DB path, lock path, config path) so in-process DB/config
+ *      resolution inside the hook still finds the store the parent configured;
+ *   3. caller-supplied extras, filtered through the same deny list.
+ *
+ * Denial is NAME-BASED by design. A value-shape test is explicitly rejected
+ * as an acceptability test: a value test would have to miss something for a
+ * credential to leak, so the deny list is the documented prefix/suffix set
+ * below. The deny list strips:
+ *
+ *   suffix:  KEY, TOKEN, SECRET, PASSWORD, PASSWD, CREDENTIAL, CREDENTIALS,
+ *            URL, URI (a URL/URI-bearing variable can embed credentials)
+ *   prefix:  HASNA_, AWS_, AZURE_, GCP_, VAULT_, GOOGLE_, OPENAI_,
+ *            ANTHROPIC_, POSTGRES_, MYSQL_, REDIS_, MONGO_, MEMENTOS_
+ *   contains: DATABASE_URL (any variant)
+ *
+ * Names that merely resemble credentials (e.g. HOOKS_DATA_DIR) survive; a
+ * path is not a credential.
+ */
+/**
+ * True when a variable NAME is credential-bearing and must never reach a
+ * hook child process. Case-insensitive.
+ */
+export declare function isDeniedEnvName(name: string): boolean;
+/**
+ * Build the sanitized environment for a hook child process.
+ *
+ * `source` is the parent's environment; `extra` is any caller-supplied env
+ * the hook may need. The deny list applies to BOTH — a caller cannot
+ * reintroduce a credential-bearing name.
+ */
+export declare function buildHookEnv(source: Record<string, string | undefined>, extra?: Record<string, string | undefined>): Record<string, string>;

package/dist/lib/manifest.d.ts

@@ -9,6 +9,13 @@ export declare const manifestSchema: z.ZodObject<{
     description: z.ZodOptional<z.ZodString>;
     events: z.ZodArray<z.ZodString, "many">;
     script: z.ZodString;
+    /**
+     * Explicit script-kind discriminator (P2-14): "inline" means the script
+     * value IS the hook body; "file" means it names a relative path. When
+     * absent, the legacy newline heuristic applies (documented fallback for
+     * older manifests — a value with a newline is inline, otherwise a path).
+     */
+    script_kind: z.ZodOptional<z.ZodEnum<["inline", "file"]>>;
     args: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     timeout_ms: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
@@ -17,6 +24,7 @@ export declare const manifestSchema: z.ZodObject<{
     name: string;
     script: string;
     description?: string | undefined;
+    script_kind?: "inline" | "file" | undefined;
     args?: string[] | undefined;
     timeout_ms?: number | undefined;
 }, {
@@ -25,6 +33,7 @@ export declare const manifestSchema: z.ZodObject<{
     name: string;
     script: string;
     description?: string | undefined;
+    script_kind?: "inline" | "file" | undefined;
     args?: string[] | undefined;
     timeout_ms?: number | undefined;
 }>;
@@ -52,10 +61,23 @@ export declare class ScriptContainmentError extends Error {
  * root, then call assertContainedReal.
  */
 export declare function assertContained(target: string, root: string, raw?: string): string;
+export declare function isInlineScript(manifest: HookManifest): boolean;
+/**
+ * Resolve a manifest's script to its RELATIVE target path under the hook
+ * directory. Shared by every install path (P2-14 / P1-2 round 2): the explicit
+ * script_kind discriminator wins; without it the legacy heuristic applies (a
+ * value containing a newline is inline content, otherwise a relative path).
+ * This is the ONE decision point — registry sync, exact-pin fetch and custom
+ * installs all call it, so a one-line inline manifest can never be mistaken
+ * for a path again.
+ */
+export declare function scriptRelFor(manifest: HookManifest): string;
 /**
  * Resolve a manifest's script to (relative path, content).
- * A script value containing a newline is inline content; anything else is a
- * relative path resolved against the manifest directory.
+ * The explicit script_kind discriminator wins (P2-14); without it the
+ * legacy heuristic applies: a script value containing a newline is inline
+ * content, anything else is a relative path resolved against the manifest
+ * directory.
  */
 export declare function resolveScript(manifest: HookManifest, manifestDir: string): {
     path: string;

package/dist/lib/redact.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Event-safe redaction for hook event rows (P1-3).
+ *
+ * tool_input / error / metadata were stored verbatim (truncated only) and
+ * returned by the MCP log tools and `hooks log`. A tool call that carries a
+ * credential (a Bash command embedding a token, a tool_input object with an
+ * api_key field, an error echoing a secret) persisted it to disk and served
+ * it back.
+ *
+ * The projection is applied:
+ *   - at WRITE time, in db-writer.writeHookEvent, so nothing sensitive is
+ *     persisted locally or pushed to the remote sync store;
+ *   - at READ time, on every MCP log response and `hooks log` output, so
+ *     rows stored by older versions (which wrote verbatim) are redacted
+ *     before they reach a reader (truncate-on-read projection; documented
+ *     retention note in CHANGELOG.md — no destructive backfill command).
+ *
+ * Two mechanisms:
+ *   1. JSON-aware: when the payload parses, values under secret-typed keys
+ *      are replaced with [REDACTED] (covers tool_input objects and metadata).
+ *   2. Shape-based: known credential shapes anywhere in the text are
+ *      replaced (covers inline tokens in command strings and error text).
+ *
+ * Redaction is intentionally conservative: these fields are internal
+ * observability data, so over-redaction costs little and under-redaction
+ * costs a leaked credential.
+ */
+export declare function redactText(value: string): string;
+export declare function redactValue(value: unknown): unknown;
+/**
+ * Project one event payload (tool_input / error / metadata text) to its
+ * event-safe form. Null passthrough, JSON-aware, always shape-scrubbed.
+ */
+export declare function redactEventPayload(text: string | null | undefined): string | null;
+/**
+ * Read projection for a full hook_events row: the fixed-field allowlist is
+ * the row schema; tool_input, error and metadata pass through
+ * redactEventPayload, everything else is returned unchanged.
+ */
+export declare function projectEventRowForRead(row: Record<string, unknown>): Record<string, unknown>;

package/dist/lib/semver.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Shared semver validation (P2-10).
+ *
+ * Every surface that accepts a hook version — manifest validation, publish,
+ * the serve and worker artifact routes — must accept and reject the SAME
+ * set. Previously the manifest accepted "1.2.3-beta" (unanchored regex)
+ * while the artifact routes demanded a bare `\d+\.\d+\.\d+` at the end of
+ * the path, so a pinned prerelease install 404'd. This is the one pattern:
+ * full semver with optional prerelease and build metadata.
+ */
+export declare const SEMVER_PATTERN: RegExp;
+/**
+ * A version segment used inside a URL path. Prerelease and build metadata
+ * can contain '+' (build metadata) which must be percent-encoded in URLs;
+ * the route regex accepts the encoded and decoded forms.
+ */
+export declare const SEMVER_PATH_SEGMENT = "[0-9A-Za-z.+_-]+";
+export declare function isValidSemver(value: string): boolean;
+export declare function semverError(value: string): string;

package/dist/lib/store.d.ts

@@ -21,6 +21,13 @@ export interface LockEntry {
     version: string;
     sha256: string;
     source: string;
+    /**
+     * True when the pin came from an explicit `hooks install/update
+     * <name>@<version>` (P2-9): an explicit older pin is preserved across
+     * syncs instead of being silently bumped to the latest. Absent/undefined
+     * pins are ordinary sync-maintained pins and follow the latest.
+     */
+    pinned?: boolean;
 }
 export interface LockFile {
     hooks: Record<string, LockEntry>;
@@ -39,6 +46,15 @@ export declare function upsertHookRecord(db: Database, record: {
     last_verified_at?: string | null;
 }): void;
 export declare function removeHookRecord(db: Database, name: string): boolean;
+/**
+ * Raised when hooks.lock is present but malformed. P1-9: a malformed lock
+ * used to degrade to {hooks:{}} — a fail-open that would let the next sync
+ * re-trust hooks as if nothing had been pinned. It now fails hard with a
+ * repair message; no execution path treats a broken lock as an empty store.
+ */
+export declare class LockFileError extends Error {
+    constructor(message: string);
+}
 export declare function readLock(): LockFile;
 export declare function writeLock(lock: LockFile): string;
 export declare function setPinnedHook(name: string, entry: LockEntry): string;

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 { parseManifest } from "./manifest.js";
 export interface SyncDiff {
     added: string[];
     updated: string[];
@@ -24,15 +25,62 @@ export interface ArtifactResponse {
         description?: string;
         events: string[];
         script: string;
+        script_kind?: "inline" | "file";
         args?: string[];
         timeout_ms?: number;
     };
     script: string;
 }
-export declare function planSync(): Promise<SyncPlan>;
+interface RemoteLock {
+    hooks: Record<string, {
+        version: string;
+        sha256: string;
+        source: string;
+        versions?: string[];
+    }>;
+}
+export declare function planSync(options?: {
+    dryRun?: boolean;
+}): Promise<SyncPlan>;
 export declare function syncHooks(options?: {
     dryRun?: boolean;
 }): Promise<SyncPlan>;
+/**
+ * One fully-validated artifact ready to be committed. Nothing has touched
+ * the store at this point: every fetch, sha check and manifest parse has
+ * already passed, so a failure inside staging leaves the store unchanged.
+ */
+export interface StagedSyncArtifact {
+    name: string;
+    version: string;
+    sha256: string;
+    source: string;
+    manifest: ReturnType<typeof parseManifest>;
+    scriptContent: string;
+    scriptRel: string;
+}
+/**
+ * P1-9 stage phase: fetch + validate ALL artifacts before anything is
+ * written. A failure here (network, sha mismatch, malformed manifest,
+ * containment violation) throws with the store untouched.
+ */
+export declare function stageSyncArtifacts(apiUrl: string, 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:
+ *
+ *   Phase A — write ALL hook files and verify their hashes. A failure here
+ *             leaves lock and DB untouched; files written without pins are
+ *             refused at run time (fail-closed trust), never silently
+ *             trusted.
+ *   Phase B — write ALL lock pins in ONE atomic write (temp + rename).
+ *   Phase C — DB records in one transaction.
+ *
+ * A failure between A and B leaves the DB untouched and the old pins in
+ * place; a failure between B and C leaves old DB records, which take
+ * precedence in checkScriptHash and refuse the new bytes until re-sync.
+ */
+export declare function commitSyncArtifacts(staged: StagedSyncArtifact[], apiUrl: string, remoteLock: RemoteLock): Promise<void>;
 export interface PinnedHookInstall {
     name: string;
     version: string;
@@ -44,11 +92,14 @@ export interface PinnedHookInstall {
 }
 /**
  * Fetch one exact hook version from the remote registry, verify its sha
- * against the remote lock, write it to the custom store, and pin it.
+ * against the remote lock (or the exact-version header for older versions),
+ * write it to the custom store, and pin it.
  * Powers `hooks install <name>@<version>` / `hooks update <name>@<version>`
  * (QA-2 finding: pinned-version install/update was unsupported).
  *
- * Requires an api_url (remote registry). The sha check is against the remote
- * lock — the exact version named by the user, never a mutable latest.
+ * Requires an api_url (remote registry). P1-4: the exact version named by
+ * 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): Promise<PinnedHookInstall>;
+export {};

package/dist/serve.d.ts

@@ -15,6 +15,7 @@ export interface CatalogEntry {
     events: string[];
     description: string;
     source: string;
+    versions: string[];
 }
 export interface ArtifactPayload {
     manifest: {
@@ -23,6 +24,7 @@ export interface ArtifactPayload {
         description?: string;
         events: string[];
         script: string;
+        script_kind?: "inline" | "file";
         args?: string[];
         timeout_ms?: number;
     };
@@ -32,5 +34,4 @@ export declare function handleServeRequest(req: Request, apiKey: string | undefi
 export declare function startServeServer(options: {
     port?: number;
     host?: string;
-    apiKey?: string;
 }): ReturnType<typeof Bun.serve>;

package/dist/storage.js

@@ -399,6 +399,60 @@ var init_db = __esm(() => {
   init_legacy_import();
 });
 
+// src/lib/redact.ts
+function redactText(value) {
+  let out = value;
+  for (const pattern of SECRET_SHAPES) {
+    out = out.replace(pattern, REDACTED);
+  }
+  return out;
+}
+function redactValue(value) {
+  if (typeof value === "string")
+    return redactText(value);
+  if (Array.isArray(value))
+    return value.map(redactValue);
+  if (value !== null && typeof value === "object") {
+    const out = {};
+    for (const [key, child] of Object.entries(value)) {
+      out[key] = SECRET_KEY_NAMES.test(key) ? REDACTED : redactValue(child);
+    }
+    return out;
+  }
+  return value;
+}
+function redactEventPayload(text) {
+  if (text === null || text === undefined)
+    return null;
+  try {
+    const parsed = JSON.parse(text);
+    return redactText(JSON.stringify(redactValue(parsed)));
+  } catch {
+    return redactText(text);
+  }
+}
+var REDACTED = "[REDACTED]", SECRET_KEY_NAMES, SECRET_SHAPES;
+var init_redact = __esm(() => {
+  SECRET_KEY_NAMES = /^(key|keys|token|tokens|secret|secrets|password|passwd|api[_-]?key|apikey|access[_-]?key|private[_-]?key|client[_-]?secret|refresh[_-]?token|authorization|auth|cookie|credential|credentials|session[_-]?id|otp|mfa[_-]?code|two[_-]?fa[_-]?code|verification[_-]?code|database_url|db_url|connection_string|dsn)$/i;
+  SECRET_SHAPES = [
+    /\bsk-(?:proj|svc|ant)-[A-Za-z0-9_-]{10,}/g,
+    /\bsk-[A-Za-z0-9]{16,}/g,
+    /\btpe_[A-Za-z0-9]{8,}/g,
+    /\b(?:rk|sk)_(?:live|test)_[A-Za-z0-9]{8,}/g,
+    /\bgithub_pat_[A-Za-z0-9_]{20,}/g,
+    /gh[pousr]_[A-Za-z0-9]{20,}/g,
+    /xox[baprs]-[A-Za-z0-9-]{20,}/g,
+    /AKIA[0-9A-Z]{16}/g,
+    /ASIA[0-9A-Z]{16}/g,
+    /eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/g,
+    /-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----/g,
+    /-----BEGIN OPENSSH PRIVATE KEY-----/g,
+    /\bBearer\s+[A-Za-z0-9._~+/=-]{6,}/g,
+    /\b[a-z][a-z0-9+.-]*:\/\/[^/\s:@]+:[^/\s@]+@/gi,
+    /\b(?:password|passwd|pwd|token|api[_-]?key|secret|access[_-]?key|client[_-]?secret|authorization|auth|credential|database_url|db_url|connection_string|dsn)\s*[:=]\s*(?:"[^"]*"|'[^']*'|[^\s,;"']{6,})/gi
+  ];
+});
+
 // src/db/storage-sync.ts
 init_db();
 
@@ -409,7 +463,7 @@ var PG_MIGRATIONS = [
     timestamp    TEXT NOT NULL,
     session_id   TEXT NOT NULL,
     hook_name    TEXT NOT NULL,
-    event_type   TEXT NOT NULL CHECK (event_type IN ('PreToolUse', 'PostToolUse', 'Stop', 'Notification', 'SessionStart', 'SessionEnd', 'UserPromptSubmit')),
+    event_type   TEXT NOT NULL CHECK (event_type IN ('PreToolUse', 'PostToolUse', 'Stop', 'Notification', 'SessionStart', 'SessionEnd', 'UserPromptSubmit', 'SubagentStart')),
     tool_name    TEXT,
     tool_input   TEXT,
     result       TEXT CHECK (result IN ('continue', 'block', NULL)),
@@ -442,7 +496,10 @@ var PG_MIGRATIONS = [
   )`,
   `ALTER TABLE hook_events DROP CONSTRAINT IF EXISTS hook_events_event_type_check`,
   `ALTER TABLE hook_events ADD CONSTRAINT hook_events_event_type_check
-    CHECK (event_type IN ('PreToolUse', 'PostToolUse', 'Stop', 'Notification', 'SessionStart', 'SessionEnd', 'UserPromptSubmit'))`
+    CHECK (event_type IN ('PreToolUse', 'PostToolUse', 'Stop', 'Notification', 'SessionStart', 'SessionEnd', 'UserPromptSubmit'))`,
+  `ALTER TABLE hook_events DROP CONSTRAINT IF EXISTS hook_events_event_type_check`,
+  `ALTER TABLE hook_events ADD CONSTRAINT hook_events_event_type_check
+    CHECK (event_type IN ('PreToolUse', 'PostToolUse', 'Stop', 'Notification', 'SessionStart', 'SessionEnd', 'UserPromptSubmit', 'SubagentStart'))`
 ];
 
 // src/db/remote-storage.ts
@@ -456,7 +513,34 @@ function normalizeParams(params) {
   return flat.map((value) => value === undefined ? null : value);
 }
 function sslConfigFor(connectionString) {
-  return connectionString.includes("sslmode=require") || connectionString.includes("ssl=true") ? { rejectUnauthorized: false } : undefined;
+  const wantsSsl = wantsSslFor(connectionString);
+  if (!wantsSsl)
+    return;
+  const insecure = process.env.HASNA_HOOKS_PG_INSECURE_TLS === "1" || process.env.HOOKS_PG_INSECURE_TLS === "1";
+  if (insecure && false) {}
+  return insecure ? { rejectUnauthorized: false } : { rejectUnauthorized: true };
+}
+function wantsSslFor(connectionString) {
+  let raw;
+  try {
+    raw = new URL(connectionString).search.replace(/^\?/, "");
+  } catch {
+    raw = connectionString;
+  }
+  try {
+    raw = decodeURIComponent(raw);
+  } catch {}
+  const paramValue = (name) => {
+    const match = raw.match(new RegExp(`(?:^|[&\\s])${name}\\s*=\\s*([^&\\s]+)`, "i"));
+    return match ? match[1].toLowerCase() : undefined;
+  };
+  const sslmode = paramValue("sslmode");
+  if (sslmode !== undefined)
+    return sslmode !== "disable" && sslmode !== "allow";
+  const ssl = paramValue("ssl");
+  if (ssl !== undefined)
+    return ssl !== "false" && ssl !== "0" && ssl !== "no";
+  return false;
 }
 
 class PgAdapterAsync {
@@ -478,6 +562,7 @@ class PgAdapterAsync {
 }
 
 // src/db/storage-sync.ts
+init_redact();
 var STORAGE_TABLES = [
   "hook_events",
   "schema_migrations",
@@ -654,9 +739,15 @@ async function pushTable(db, remote, table) {
     result.rowsRead = rows.length;
     if (rows.length === 0)
       return result;
+    const projected = table === "hook_events" ? rows.map((row) => ({
+      ...row,
+      tool_input: typeof row.tool_input === "string" ? redactEventPayload(row.tool_input) : row.tool_input,
+      error: typeof row.error === "string" ? redactEventPayload(row.error) : row.error,
+      metadata: typeof row.metadata === "string" ? redactEventPayload(row.metadata) : row.metadata
+    })) : rows;
     const remoteColumns = await getRemoteColumns(remote, table);
-    const columns = filterRemoteColumns(remoteColumns, Object.keys(rows[0]));
-    result.rowsWritten = await upsertPg(remote, table, columns, rows, remoteColumns);
+    const columns = filterRemoteColumns(remoteColumns, Object.keys(projected[0]));
+    result.rowsWritten = await upsertPg(remote, table, columns, projected, remoteColumns);
   } catch (error) {
     result.errors.push(error instanceof Error ? error.message : String(error));
   }
@@ -671,8 +762,14 @@ async function pullTable(remote, db, table) {
     result.rowsRead = rows.length;
     if (rows.length === 0)
       return result;
-    const columns = filterLocalColumns(db, table, Object.keys(rows[0]));
-    result.rowsWritten = upsertSqlite(db, table, columns, rows);
+    const projected = table === "hook_events" ? rows.map((row) => ({
+      ...row,
+      tool_input: typeof row.tool_input === "string" ? redactEventPayload(row.tool_input) : row.tool_input,
+      error: typeof row.error === "string" ? redactEventPayload(row.error) : row.error,
+      metadata: typeof row.metadata === "string" ? redactEventPayload(row.metadata) : row.metadata
+    })) : rows;
+    const columns = filterLocalColumns(db, table, Object.keys(projected[0]));
+    result.rowsWritten = upsertSqlite(db, table, columns, projected);
   } catch (error) {
     result.errors.push(error instanceof Error ? error.message : String(error));
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/hooks",
-  "version": "0.6.4",
+  "version": "0.6.6",
   "description": "Open source hooks library for AI coding agents - Install safety, quality, and automation hooks with a single command",
   "type": "module",
   "bin": {
@@ -53,7 +53,7 @@
   },
   "dependencies": {
     "@hasna/events": "^0.1.6",
-    "@hasna/secrets": "^0.2.22",
+    "@hasna/secrets": "0.3.0",
     "@modelcontextprotocol/sdk": "^1.26.0",
     "chalk": "^5.3.0",
     "commander": "^12.1.0",