@hasna/hooks 0.9.0 → 0.9.1

package/dist/lib/db-writer.d.ts

@@ -1,8 +1,37 @@
 /**
  * Shared hook DB writer — single write path for all observability hooks.
  * Never throws: errors are written to stderr only.
+ *
+ * GATED (hasna/apps#1720 fail-closed ruling, W6 2026-09-11). This used to be
+ * the one ungated path to ~/.hasna/hooks/hooks.db: every `hooks run`, every
+ * MCP run tool and four bundled hook runtimes called it, and it created the
+ * store on first write with no credential decision at all — a silent local
+ * default. It now writes ONLY when the environment selects the on-box store
+ * through the explicit opt-in (HASNA_HOOKS_LOCAL=1 / HOOKS_LOCAL=1, answered
+ * from the env dictionary alone — no Keychain or disk read on the per-event
+ * hot path). On the hosted route (a process-wide refusal installed by the CLI
+ * gate / MCP startup, or any authority variable set in the env) and in an
+ * unconfigured environment it prints ONE stderr line naming the opt-in and
+ * writes nothing: the hosted registry has no event route to port to.
+ */
+import type { HookEventRow } from "../db/schema.js";
+import type { HooksLocalOptInEnv } from "./resolver-types.js";
+/** Where a hook event may land: the on-box store, or nowhere (with the reason). */
+export type HookEventSink = {
+    kind: "local";
+} | {
+    kind: "refused";
+    reason: string;
+};
+/**
+ * Decide the event sink from the env dictionary and the process-wide store
+ * refusal ONLY — never the resolver, so agents' per-event `hooks run` and the
+ * bundled hook children never pay a `security` spawn here (the CLI gate
+ * already decided the route for the parent process).
  */
-import type { HookEventRow } from "../db/schema";
+export declare function resolveHookEventSink(env?: HooksLocalOptInEnv): HookEventSink;
+/** Reset the once-per-process sink refusal notice. Test seam only. */
+export declare function __resetHookEventSinkNotice(): void;
 export type HookEventInput = Omit<HookEventRow, "id" | "timestamp"> & {
     timestamp?: string;
 };

package/dist/lib/local-opt-in.d.ts

@@ -22,6 +22,32 @@ export declare function hooksAuthorityEnvKeys(): string[];
 export declare function hasHooksEnvAuthorityIntent(env?: HooksLocalOptInEnv): boolean;
 /** True when this environment should be served by the on-box bundled store. */
 export declare function selectsHooksLocalStore(env?: HooksLocalOptInEnv): boolean;
+/** The credential tiers every fail-closed line names, in chain order. Never a value. */
+export declare const HOOKS_CREDENTIAL_TIERS = "the Keychain item hasna.credentials.hooks.api-key, ~/.hasna/hooks/config/credentials, or HASNA_HOOKS_API_KEY";
+/** The opt-in every refusal names, canonical spelling first. */
+export declare const HOOKS_LOCAL_OPT_IN_HINT = "HASNA_HOOKS_LOCAL=1 (alias HOOKS_LOCAL=1)";
+/**
+ * The ONE line an unconfigured client surface prints before exiting non-zero
+ * (hasna/apps#1720 ruling, W6 target state): the stable code, the tiers
+ * consulted, the opt-in, and the refusal — no credential value, no local
+ * default. The CLI gate, the MCP server and the SDK all print this spelling.
+ */
+export declare function hooksFailClosedLine(detail?: string): string;
+/**
+ * The refusal every local-only verb / tool returns on the HOSTED route: the
+ * on-box SQLite store is a different dataset from the registry authority the
+ * run is routed to, so it is never opened — not even to answer an empty
+ * result. Installed process-wide through `refuseLocalStore()` in
+ * `src/db/index.ts`. Mirrors todos' `REMOTE_COMMAND_UNSUPPORTED`.
+ */
+export declare function hooksHostedRouteLocalStoreRefusal(authority: string): string;
+/**
+ * The line the hook-event writer prints (once per process) when it has no
+ * sink: the hosted registry has no event route, so without the explicit
+ * local opt-in there is nowhere to record the event — and it is NOT written
+ * to a silently created hooks.db.
+ */
+export declare function hooksEventSinkRefusal(): string;
 /**
  * The environment as the resolver should see it: every authority/credential
  * variable that is DECLARED BUT BLANK removed.

package/dist/lib/sync.d.ts

@@ -92,7 +92,8 @@ export interface PinnedHookInstall {
     sha256: string;
     source: string;
     source_ref: string;
-    artifact: ArtifactResponse;
+    /** The registry artifact for remote pins; null for bundled-registry pins. */
+    artifact: ArtifactResponse | null;
     scriptPath: string;
 }
 /**
@@ -107,4 +108,19 @@ export interface PinnedHookInstall {
  * are first-class, never rejected as "not the latest".
  */
 export declare function fetchPinnedHook(name: string, version: string, apiUrl: string, apiKey: string): Promise<PinnedHookInstall>;
+/**
+ * Pin an exact hook version from the BUNDLED registry (the on-box catalog).
+ * Powers `hooks install <name>@<version>` / `hooks update <name>@<version>`
+ * under the explicit local opt-in (HASNA_HOOKS_LOCAL=1) — the only route on
+ * which `resolveHooksTransport` returns `mode: "local"`; with nothing
+ * configured the CLI gate has already failed closed, and on the hosted route
+ * the remote registry answers the pin. The exact version named must be the
+ * bundled one, and the script stays at its bundled path — the pin (lock + DB
+ * record) is the trust anchor, exactly as local `hooks sync` pins the catalog.
+ * Carried from hasna/apps#1888 (its good half).
+ *
+ * A name or version the bundled registry does not carry is a DATA error with
+ * the available version named — the same shape as a remote pin miss.
+ */
+export declare function installPinnedFromBundled(name: string, version: string): Promise<PinnedHookInstall>;
 export {};

package/dist/sdk/index.d.ts

@@ -0,0 +1,103 @@
+/**
+ * `@hasna/hooks/sdk` — the hosted hooks registry client (package-surfaces
+ * rule: one package, four surfaces; this is the importable one).
+ *
+ * SELF-CONTAINED. The built bundle (`dist/sdk/index.js`, `bun build --target
+ * bun`) imports node builtins only: the `@hasna/contracts/client` credential
+ * seam is inlined at build time, and nothing here reaches `bun:sqlite` or the
+ * on-box store — the SDK has no local mode. `src/sdk/index.test.ts` pins both.
+ *
+ * FAIL CLOSED (hasna/apps#1720). `createHooksClient()` resolves the registry
+ * authority and credential through the ONE @hasna/contracts chain (env pair →
+ * Keychain item `hasna.credentials.hooks.api-key` → `~/.hasna/hooks/config/
+ * credentials`), as a strict pair, fresh per call. With nothing resolved it
+ * THROWS the `REMOTE_API_*` diagnostic naming the tiers and the opt-in; it
+ * never returns a client that answers from a local file. The explicit local
+ * opt-in (`HASNA_HOOKS_LOCAL=1`) is refused here by name: the SDK is a hosted
+ * client and the on-box store is the CLI's, opt-in only.
+ */
+import { hooksRegistryOrigin, type HooksRemoteAuthority, type HooksTransportOptions } from "../lib/transport.js";
+import type { HooksCredentialOptions, HooksLocalOptInEnv } from "../lib/resolver-types.js";
+export type { HooksRemoteAuthority, HooksCredentialOptions, HooksLocalOptInEnv };
+export { hooksRegistryOrigin };
+/** One row of `GET /api/v1/catalog` — the registry's latest version of a hook. */
+export interface HooksRegistryCatalogEntry {
+    name: string;
+    version: string;
+    sha256: string;
+    events: string[];
+    description: string;
+    source: string;
+    versions: string[];
+}
+/** One pin of `GET /api/v1/lock` — the exact version the registry wants clients on. */
+export interface HooksRegistryLockEntry {
+    version: string;
+    sha256: string;
+    source?: string;
+    versions?: string[];
+}
+export interface HooksRegistryLock {
+    hooks: Record<string, HooksRegistryLockEntry>;
+}
+/** `GET /api/v1/hooks/:name/:version` — a versioned artifact (manifest + script). */
+export interface HooksRegistryArtifact {
+    manifest: {
+        name: string;
+        version: string;
+        description?: string;
+        events: string[];
+        script: string;
+        script_kind?: "inline" | "file";
+        args?: string[];
+        timeout_ms?: number;
+    };
+    script: string;
+    /** The registry's `x-hook-sha256` header for the served row, when present. */
+    sha256: string | null;
+}
+export interface HooksClientOptions {
+    /** Injectable environment (tests). Defaults to `process.env`. */
+    env?: HooksLocalOptInEnv;
+    /** Tier-1 credential inputs and the injectable `security` runner. */
+    credentials?: HooksCredentialOptions;
+    /** Injectable fetch (tests). Defaults to the global `fetch`. */
+    fetch?: typeof fetch;
+}
+/**
+ * Resolve the hosted authority the SDK will talk to. 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 resolveHooksSdkAuthority(env?: HooksLocalOptInEnv, options?: Omit<HooksTransportOptions, "notice">): HooksRemoteAuthority;
+/**
+ * Hosted registry client. Holds the resolved credential privately and sends
+ * it only to the authority it was resolved together with (strict pair).
+ */
+export declare class HooksClient {
+    #private;
+    /** Registry origin WITHOUT `/v1` — the registry routes hang off `<origin>/api/v1`. */
+    readonly origin: string;
+    /** The resolver's `<origin>/v1` authority, for diagnostics. */
+    readonly v1BaseUrl: 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;
+    constructor(authority: HooksRemoteAuthority, options?: {
+        fetch?: typeof fetch;
+    });
+    /** Build the request URL for a registry route (exposed so callers can log WHERE without a key). */
+    urlFor(path: string): string;
+    health(): Promise<{
+        status: string;
+        name: string;
+    }>;
+    catalog(): Promise<HooksRegistryCatalogEntry[]>;
+    lock(): Promise<HooksRegistryLock>;
+    artifact(name: string, version: string): Promise<HooksRegistryArtifact>;
+    private request;
+    private getJson;
+}
+/** Resolve the hosted authority (fail closed) and return a client bound to it. */
+export declare function createHooksClient(options?: HooksClientOptions): HooksClient;