@hasna/hooks 0.14.0 → 0.15.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (38) hide show
  1. package/README.md +31 -11
  2. package/bin/hooks/stop-review.js +17 -9
  3. package/bin/hooks-mcp.js +741 -311
  4. package/bin/index.js +1673 -634
  5. package/bin/native-safety-entry.js +2 -2
  6. package/bin/native-safety-worker.cjs +36 -34
  7. package/bin/release-manifest.json +297 -0
  8. package/bin/serve.js +577 -151
  9. package/dist/index.js +1813 -1178
  10. package/dist/lib/codex-safety-check.d.ts +1 -1
  11. package/dist/lib/error-events.d.ts +59 -0
  12. package/dist/lib/install-record.d.ts +136 -0
  13. package/dist/lib/manifest.d.ts +6 -0
  14. package/dist/lib/release-manifest.d.ts +162 -0
  15. package/dist/lib/store.d.ts +25 -2
  16. package/dist/openapi.d.ts +147 -0
  17. package/dist/registry-auth.d.ts +6 -1
  18. package/dist/registry-http.d.ts +2 -1
  19. package/dist/sdk/generated.d.ts +26 -0
  20. package/dist/sdk/index.js +14 -0
  21. package/hooks/codewith-native-common.ts +190 -6
  22. package/hooks/hook-signed-link-guard/README.md +46 -0
  23. package/hooks/hook-signed-link-guard/src/classify.ts +7 -3
  24. package/hooks/hook-signed-link-guard/src/jq.ts +205 -34
  25. package/hooks/hook-stop-review/README.md +5 -2
  26. package/hooks/hook-stop-review/src/jev.ts +9 -4
  27. package/hooks/hook-stop-review/src/policy.ts +7 -3
  28. package/hooks/hook-stop-review/src/runtime.ts +5 -4
  29. package/hooks/hook-trash-guard/README.md +9 -4
  30. package/hooks/hook-trash-guard/src/hook.ts +127 -10
  31. package/hooks/hook-workspace-repos-guard/src/hook.ts +27 -12
  32. package/hooks/pre-bash/README.md +47 -1
  33. package/hooks/pre-bash/src/hook.ts +168 -12
  34. package/hooks/shell-words.ts +40 -2
  35. package/package.json +3 -2
  36. package/scripts/build-release-manifest.ts +27 -0
  37. package/scripts/validate-package.ts +5 -1
  38. package/scripts/validate-release-manifest.ts +67 -0
@@ -2,7 +2,7 @@ import { type NativeSafetyName } from "./native-safety.js";
2
2
  import { verifyNativeSafetyCommand } from "../native-safety.js";
3
3
  /** Exact `codex --version` outputs whose app-server protocol was measured
4
4
  * against the real native binary. Anything else refuses as native_unsupported. */
5
- export declare const SUPPORTED_CODEX_SAFETY_VERSIONS: readonly ["codex-cli 0.153.0", "codex-cli 0.154.0", "codex-cli 0.154.0-alpha.6.1", "codex-cli 0.155.0", "codex-cli 0.155.1", "codex-cli 0.156.1", "codex-cli 0.157.0", "codex-cli 0.157.1", "codex-cli 0.158.0", "codex-cli 0.159.0", "codex-cli 0.159.2", "codex-cli 0.159.3", "codex-cli 0.160.0", "codex-cli 0.160.1", "codex-cli 0.161.0", "codex-cli 0.162.0", "codex-cli 0.162.1", "codex-cli 0.163.0"];
5
+ export declare const SUPPORTED_CODEX_SAFETY_VERSIONS: readonly ["codex-cli 0.153.0", "codex-cli 0.154.0", "codex-cli 0.154.0-alpha.6.1", "codex-cli 0.155.0", "codex-cli 0.155.1", "codex-cli 0.156.1", "codex-cli 0.157.0", "codex-cli 0.157.1", "codex-cli 0.158.0", "codex-cli 0.159.0", "codex-cli 0.159.2", "codex-cli 0.159.3", "codex-cli 0.160.0", "codex-cli 0.160.1", "codex-cli 0.161.0", "codex-cli 0.162.0", "codex-cli 0.162.1", "codex-cli 0.163.0", "codex-cli 0.169.0", "codex-cli 0.170.0"];
6
6
  /** Hard sanity bound on the native Codex executable, which is read whole into
7
7
  * memory for the header check and SHA-256 pin. Not a platform contract: the
8
8
  * measured 0.162.1 binaries are 246.6 MB (darwin-arm64) to 294.4 MB (linux-x64). */
@@ -0,0 +1,59 @@
1
+ import type { PgAdapterAsync } from "../db/remote-storage.js";
2
+ export declare const ERROR_EVENT_CLASSES: readonly ["nonzero-exit", "guard-blocked-unrunnable", "missing-script", "trust-changed", "trust-unreadable", "invalid-options", "start-failed", "timed-out"];
3
+ export declare const ERROR_EVENT_HARNESSES: readonly ["claude", "codex", "other"];
4
+ export declare const ERROR_EVENT_RETENTION_DAYS = 30;
5
+ export declare const ERROR_EVENT_RATE_PER_MINUTE = 120;
6
+ export declare const ERROR_EVENT_MAX_BYTES = 4096;
7
+ /** Additive only. Applied by `hooks migrate` beside the registry tables, never during a request. */
8
+ export declare const ERROR_EVENT_MIGRATIONS: readonly [`CREATE TABLE IF NOT EXISTS hooks_error_events (id BIGSERIAL PRIMARY KEY, key_id TEXT NOT NULL, hook TEXT NOT NULL, event TEXT NOT NULL, class TEXT NOT NULL CHECK(class IN (${string})), exit_code INTEGER, duration_ms INTEGER NOT NULL CHECK(duration_ms >= 0), station TEXT NOT NULL, harness TEXT NOT NULL CHECK(harness IN (${string})), hooks_version TEXT NOT NULL, at TIMESTAMPTZ NOT NULL, received_at TIMESTAMPTZ NOT NULL DEFAULT NOW())`, "CREATE INDEX IF NOT EXISTS idx_hooks_error_events_received ON hooks_error_events (received_at)", "CREATE INDEX IF NOT EXISTS idx_hooks_error_events_key_received ON hooks_error_events (key_id, received_at)", "CREATE INDEX IF NOT EXISTS idx_hooks_error_events_at ON hooks_error_events (at)"];
9
+ export type ErrorEventClass = typeof ERROR_EVENT_CLASSES[number];
10
+ export type ErrorEventHarness = typeof ERROR_EVENT_HARNESSES[number];
11
+ export interface ErrorEvent {
12
+ hook: string;
13
+ event: string;
14
+ class: ErrorEventClass;
15
+ exit_code: number | null;
16
+ duration_ms: number;
17
+ station: string;
18
+ harness: ErrorEventHarness;
19
+ hooks_version: string;
20
+ at: string;
21
+ }
22
+ export interface ErrorEventSummaryRow {
23
+ hour: string;
24
+ station: string;
25
+ hook: string;
26
+ event: string;
27
+ class: string;
28
+ count: number;
29
+ }
30
+ /** Exactly the nine fields, each bounded; anything else is refused before the store. */
31
+ export declare function validateErrorEvent(value: unknown, now?: number): ErrorEvent;
32
+ /** The summary window: an exact UTC instant no more than the retention period ago; default 24 hours. */
33
+ export declare function summarySince(value: string | null, now?: number): string;
34
+ export interface ErrorEventStore {
35
+ /** Appends one row unless the key already wrote the per-minute limit; false when limited. */
36
+ insert(event: ErrorEvent, keyId: string): Promise<boolean>;
37
+ /** Removes rows past the retention period; returns how many. */
38
+ prune(): Promise<number>;
39
+ summary(since: string): Promise<ErrorEventSummaryRow[]>;
40
+ }
41
+ export declare class PgErrorEventStore implements ErrorEventStore {
42
+ private readonly db;
43
+ constructor(db: PgAdapterAsync);
44
+ insert(event: ErrorEvent, keyId: string): Promise<boolean>;
45
+ prune(): Promise<number>;
46
+ summary(since: string): Promise<ErrorEventSummaryRow[]>;
47
+ }
48
+ /** Appends one event and prunes at most once an hour per process; a failed prune never drops the event. */
49
+ export declare class HostedErrorEvents {
50
+ private readonly store;
51
+ private readonly now;
52
+ private prunedAt;
53
+ constructor(store: ErrorEventStore, now?: () => number);
54
+ record(value: unknown, keyId: string): Promise<void>;
55
+ summary(since: string | null): Promise<{
56
+ since: string;
57
+ hours: ErrorEventSummaryRow[];
58
+ }>;
59
+ }
@@ -0,0 +1,136 @@
1
+ /**
2
+ * Install record — a custom hook's content and its trust, committed together.
3
+ *
4
+ * `hooks install <source>` used to write three things one after another: the
5
+ * script, `manifest.json`, then the pin in `hooks.lock`. Between those writes,
6
+ * and after any step that changed the script without the pin (a file copied in
7
+ * by hand, a patch applied in place), the trusted hook held bytes its trust did
8
+ * not name and `hooks run` refused until someone ran `hooks trust`.
9
+ *
10
+ * The install now commits ONE file by ONE rename: `.hooks-install.json` in the
11
+ * hook's own directory. It holds the manifest bytes, the script bytes, their
12
+ * sha256 and the hashes of the files it replaced. That file is the trust and
13
+ * the content at once, so there is no moment at which one names something the
14
+ * other is not.
15
+ *
16
+ * `manifest.json` and the script stay where they have always been, for people
17
+ * and for older CLIs. They are written after the commit. If the process stops
18
+ * in between, they still hold exactly the bytes the record says it replaced
19
+ * (or are missing): the next run finishes them from the record. Bytes that are
20
+ * neither the record's nor the replaced ones were changed by something other
21
+ * than the installer, and the hook refuses until `hooks install <source>`
22
+ * installs the new content or `hooks trust <name>` accepts it.
23
+ *
24
+ * A directory with no record (installed before this file existed) is governed
25
+ * by its `hooks.lock` pin exactly as before.
26
+ */
27
+ import { INSTALL_RECORD_FILE, type HookManifest } from "./manifest.js";
28
+ export { INSTALL_RECORD_FILE };
29
+ export declare const INSTALL_RECORD_SCHEMA = 1;
30
+ export interface InstallRecord {
31
+ schema: typeof INSTALL_RECORD_SCHEMA;
32
+ name: string;
33
+ version: string;
34
+ source: string;
35
+ source_ref: string | null;
36
+ installed_at: string;
37
+ script: {
38
+ path: string;
39
+ sha256: string;
40
+ content_base64: string;
41
+ };
42
+ manifest: {
43
+ sha256: string;
44
+ content_base64: string;
45
+ };
46
+ /** sha256 of the files this install replaced; null where there was none. */
47
+ replaces: {
48
+ script_sha256: string | null;
49
+ manifest_sha256: string | null;
50
+ };
51
+ }
52
+ /** A record that is present but cannot be trusted as written. */
53
+ export declare class InstallRecordError extends Error {
54
+ constructor(message: string);
55
+ }
56
+ /**
57
+ * Read a hook's install record. Returns null when the directory has none.
58
+ * Throws InstallRecordError when one is present but malformed or does not
59
+ * hash to what it claims: a damaged record is never read as "no record",
60
+ * which would hand the decision back to an older pin.
61
+ */
62
+ export declare function readInstallRecord(name: string): InstallRecord | null;
63
+ export type InstallStep = "before-commit" | "record-committed" | "script-written" | "manifest-written";
64
+ export interface CommitInstallOptions {
65
+ source: string;
66
+ sourceRef?: string | null;
67
+ /**
68
+ * The manifest file's exact bytes, when the caller already holds them
69
+ * (`hooks trust` records the file as it is). Default: the canonical
70
+ * serialization of `manifest`.
71
+ */
72
+ manifestBytes?: Buffer;
73
+ /**
74
+ * Test seam for an interrupted install: called after each durable step with
75
+ * its name; throwing stops the install exactly there.
76
+ */
77
+ onStep?: (step: InstallStep) => void;
78
+ }
79
+ export interface CommittedInstall {
80
+ dir: string;
81
+ scriptPath: string;
82
+ record: InstallRecord;
83
+ }
84
+ /**
85
+ * Install `manifest` and `scriptContent` as hook `name`: commit the record by
86
+ * one rename, then bring the visible files in line with it.
87
+ */
88
+ export declare function commitInstall(name: string, manifest: HookManifest, scriptContent: string | Buffer, scriptRelPath: string, options: CommitInstallOptions): CommittedInstall;
89
+ export type InstallState =
90
+ /** No record: the directory predates install records. The lock pin decides. */
91
+ {
92
+ state: "none";
93
+ }
94
+ /** The visible files equal the record. */
95
+ | {
96
+ state: "consistent";
97
+ record: InstallRecord;
98
+ }
99
+ /** An install stopped after its commit; the visible files are the replaced ones (or missing). */
100
+ | {
101
+ state: "unfinished";
102
+ record: InstallRecord;
103
+ files: Array<"script" | "manifest">;
104
+ }
105
+ /** A visible file holds bytes no install wrote. */
106
+ | {
107
+ state: "edited";
108
+ record: InstallRecord;
109
+ file: "script" | "manifest";
110
+ expected: string;
111
+ actual: string;
112
+ }
113
+ /** A record is present but cannot be trusted. */
114
+ | {
115
+ state: "invalid";
116
+ reason: string;
117
+ };
118
+ /** Read-only: compare a hook's visible files with its install record. */
119
+ export declare function inspectInstall(name: string): InstallState;
120
+ /**
121
+ * Finish an install that stopped after its commit. Writes only bytes the
122
+ * record already holds, and only over files that still hold what the record
123
+ * replaced; an edited file is left exactly as it is and reported.
124
+ */
125
+ export declare function finishInstall(name: string): InstallState;
126
+ /**
127
+ * Run `read` — everything a hook run takes from disk: manifest, script bytes
128
+ * and trust decision — inside a window in which the hook's install did not
129
+ * change, so the run holds one whole installed version.
130
+ *
131
+ * An unfinished install is finished first. If an install commits while `read`
132
+ * is running, its result is discarded and `read` runs again; after a few
133
+ * rounds of installs landing back to back the last result stands, and the
134
+ * trust check inside it has already refused anything it could not match.
135
+ */
136
+ export declare function withStableInstall<T>(name: string, read: () => T): T;
@@ -3,6 +3,12 @@
3
3
  */
4
4
  import { z } from "zod";
5
5
  export declare const HOOK_NAME_RE: RegExp;
6
+ /**
7
+ * The install record `hooks install <source>` commits in a custom hook's own
8
+ * directory (src/lib/install-record.ts). Named here because the registry
9
+ * writer below must retire it before it changes the files it describes.
10
+ */
11
+ export declare const INSTALL_RECORD_FILE = ".hooks-install.json";
6
12
  export declare const manifestSchema: z.ZodObject<{
7
13
  name: z.ZodString;
8
14
  version: z.ZodString;
@@ -0,0 +1,162 @@
1
+ /**
2
+ * Release manifest — the trust of a bundled hook travels with its release.
3
+ *
4
+ * A bundled hook's script is the package's own file, so it changes with the
5
+ * package version. Its trust used to be a separate pin in `hooks.lock`, written
6
+ * by a first run or by `hooks trust`: every release that changed a script left
7
+ * that pin naming the previous release's bytes, and `hooks run` refused until
8
+ * someone re-trusted the hook by hand on every machine.
9
+ *
10
+ * The build now writes `bin/release-manifest.json` into the package: one entry
11
+ * per bundled hook with its catalogue version, the package-relative script it
12
+ * runs and that script's sha256. A bundled hook whose bytes equal its own
13
+ * release's entry is trusted by that release. Installing a version writes the
14
+ * scripts and their trust in one step (the package manager unpacks both), and
15
+ * switching versions is the one link rename that already selects the scripts.
16
+ *
17
+ * What this does and does not protect. The check has always been change
18
+ * detection against a writer that does not also rewrite the trust record: the
19
+ * record (`hooks.lock`, mode 0644 in the data directory) is writable by the
20
+ * same user as the scripts. That is unchanged. A changed script with an
21
+ * unchanged manifest refuses. A script changed together with the manifest is
22
+ * caught where an anchor exists: `hooks release anchor` records the manifest's
23
+ * sha256 outside the package (owner-only, in the data directory) at install
24
+ * time, and from then on a manifest that differs from its anchor refuses every
25
+ * bundled hook of that package. A writer that rewrites script, manifest and
26
+ * anchor is the same writer that could rewrite `hooks.lock` before.
27
+ *
28
+ * The source layout (running `src/` directly) has no release, so nothing here
29
+ * applies there and the lock pin decides as before.
30
+ */
31
+ import { type HookMeta } from "./registry.js";
32
+ export declare const RELEASE_MANIFEST_SCHEMA = 1;
33
+ export declare const RELEASE_MANIFEST_RELATIVE_PATH = "bin/release-manifest.json";
34
+ export interface ReleaseManifestEntry {
35
+ /** The hook's own catalogue version (not the package version). */
36
+ version: string;
37
+ /** Package-relative path of the script `hooks run` executes. */
38
+ script: string;
39
+ sha256: string;
40
+ }
41
+ export interface ReleaseManifest {
42
+ schema: typeof RELEASE_MANIFEST_SCHEMA;
43
+ package: string;
44
+ /** The package version this manifest was built for. */
45
+ version: string;
46
+ hooks: Record<string, ReleaseManifestEntry>;
47
+ }
48
+ export interface LoadedRelease {
49
+ /** Realpath of the package directory the manifest describes. */
50
+ root: string;
51
+ path: string;
52
+ /** sha256 of the manifest file's bytes — what an anchor records. */
53
+ sha256: string;
54
+ manifest: ReleaseManifest;
55
+ }
56
+ /** A release manifest that is present but cannot be trusted as written. */
57
+ export declare class ReleaseManifestError extends Error {
58
+ constructor(message: string);
59
+ }
60
+ /**
61
+ * The package-relative script a bundled hook runs: the build-owned bundle when
62
+ * the catalogue names one, the hook's own `src/hook.ts` otherwise. This is the
63
+ * same choice `resolveScriptPath` makes, kept here so the build can make it
64
+ * without a data directory.
65
+ */
66
+ export declare function bundledScriptRelativePath(meta: HookMeta, packageDir: string): string | undefined;
67
+ /**
68
+ * Hash every bundled hook's script as it sits in `packageDir`.
69
+ *
70
+ * A hook whose catalogue entry names a build-owned bundle that is not there
71
+ * fails the build: a manifest that silently omitted it would be a package
72
+ * whose own hook refuses. A catalogue entry with no `hook.ts` at all (a hook
73
+ * that ships other entry points and cannot be run by `hooks run`) has nothing
74
+ * to hash and is left out.
75
+ */
76
+ export declare function buildReleaseManifest(packageDir: string, hooks?: readonly HookMeta[]): ReleaseManifest;
77
+ export declare function serializeReleaseManifest(manifest: ReleaseManifest): string;
78
+ /**
79
+ * The package directory a built module belongs to, or null when the module is
80
+ * not a built artifact of a package (the source layout, a test).
81
+ *
82
+ * Built entry points live in `<package>/bin` and `<package>/dist`; only those
83
+ * carry a release. A module under `<package>/src` is the source layout even
84
+ * when a stale `bin/release-manifest.json` from a local build sits beside it.
85
+ */
86
+ export declare function releaseRootOf(moduleDir?: string): string | null;
87
+ /** Test seam: pin the release this process sees. `undefined` restores discovery. */
88
+ export declare function setReleaseForTesting(release: LoadedRelease | null | undefined): void;
89
+ /**
90
+ * Load the release of the package at `root`. Returns null when the package has
91
+ * no manifest (a version from before this file existed). Throws
92
+ * ReleaseManifestError when a manifest is present but malformed: a broken
93
+ * manifest is never read as "no release".
94
+ */
95
+ export declare function loadReleaseAt(root: string): LoadedRelease | null;
96
+ /** The release this process runs from, or null in the source layout. */
97
+ export declare function currentRelease(): LoadedRelease | null;
98
+ export interface ReleaseAnchor {
99
+ schema: 1;
100
+ package_root: string;
101
+ package: string;
102
+ version: string;
103
+ manifest_sha256: string;
104
+ anchored_at: string;
105
+ }
106
+ export type AnchorState = {
107
+ state: "absent";
108
+ path: string;
109
+ } | {
110
+ state: "match";
111
+ path: string;
112
+ anchor: ReleaseAnchor;
113
+ } | {
114
+ state: "mismatch";
115
+ path: string;
116
+ expected: string;
117
+ actual: string;
118
+ } | {
119
+ state: "invalid";
120
+ path: string;
121
+ };
122
+ /** One anchor per installed package directory, keyed by its realpath. */
123
+ export declare function anchorPathFor(release: LoadedRelease): string;
124
+ /** Read-only comparison of a release with its anchor. Never writes. */
125
+ export declare function anchorStateOf(release: LoadedRelease): AnchorState;
126
+ /**
127
+ * Record the release's manifest sha256 outside the package, once. Run by the
128
+ * step that installs a version, straight after the package manager verified
129
+ * and unpacked it. An existing anchor is never replaced: the same manifest is
130
+ * a no-op, a different one is a refusal (the manifest changed after install).
131
+ */
132
+ export declare function writeReleaseAnchor(release: LoadedRelease): {
133
+ written: boolean;
134
+ state: AnchorState;
135
+ };
136
+ export type ReleaseTrust =
137
+ /** No release governs this hook: the source layout, or a package without a manifest. */
138
+ {
139
+ governed: false;
140
+ }
141
+ /** The bytes equal this release's entry (and its anchor, where one exists). */
142
+ | {
143
+ governed: true;
144
+ ok: true;
145
+ release: string;
146
+ expected: string;
147
+ anchored: boolean;
148
+ }
149
+ /** The release names other bytes, or the release itself cannot be trusted. */
150
+ | {
151
+ governed: true;
152
+ ok: false;
153
+ release: string;
154
+ expected: string;
155
+ reason: "content" | "anchor" | "manifest" | "unlisted";
156
+ };
157
+ /**
158
+ * Decide a bundled hook against the release it runs from. `scriptPath` is the
159
+ * resolved script; a script outside the release's own directory is not this
160
+ * release's file and is left to the lock pin.
161
+ */
162
+ export declare function releaseTrustFor(name: string, actual: string, scriptPath: string | undefined): ReleaseTrust;
@@ -5,7 +5,7 @@
5
5
  * never trusted on one surface only. The lock file is the portable pin that a
6
6
  * remote registry sync compares against.
7
7
  */
8
- import type { Database } from "bun:sqlite";
8
+ import { Database } from "bun:sqlite";
9
9
  export interface HookRecord {
10
10
  id: string;
11
11
  name: string;
@@ -30,6 +30,13 @@ export interface LockEntry {
30
30
  * pins are ordinary sync-maintained pins and follow the latest.
31
31
  */
32
32
  pinned?: boolean;
33
+ /**
34
+ * The package release (`<package>@<version>`) under which `hooks trust`
35
+ * accepted bytes that differ from that release's own manifest. Such a pin
36
+ * accepts those bytes for that release only: it is not carried to the next
37
+ * version, and a pin without it never accepts bytes a release does not name.
38
+ */
39
+ release?: string;
33
40
  }
34
41
  export interface LockFile {
35
42
  hooks: Record<string, LockEntry>;
@@ -85,6 +92,22 @@ export interface TrustCheck {
85
92
  expected: string | null;
86
93
  actual: string;
87
94
  name: string;
95
+ /**
96
+ * What decided: the package's release manifest, the hook's install record,
97
+ * a pin in hooks.lock / hooks.db, or a first run (nothing recorded yet).
98
+ */
99
+ governedBy?: "release" | "install-record" | "pin" | "first-run";
100
+ /** The release the trusted bytes belong to, where one is known. */
101
+ release?: string | null;
102
+ /** The install record's view of the hook's files (custom hooks with a record). */
103
+ state?: string;
104
+ }
105
+ export interface CheckOptions {
106
+ /**
107
+ * Decide without recording anything: no first-run pin, no verification
108
+ * timestamp. `hooks verify` reads with this; `hooks run` never sets it.
109
+ */
110
+ readOnly?: boolean;
88
111
  }
89
112
  /**
90
113
  * Check a hook script's content hash against the trusted record.
@@ -94,7 +117,7 @@ export interface TrustCheck {
94
117
  * Takes a precomputed hash so callers can verify the exact bytes they are
95
118
  * about to execute (content-based verification), instead of re-reading a path.
96
119
  */
97
- export declare function checkScriptHash(name: string, actual: string): TrustCheck;
120
+ export declare function checkScriptHash(name: string, actual: string, options?: CheckOptions): TrustCheck;
98
121
  /**
99
122
  * Verify a hook script's content hash against the trusted record, reading the
100
123
  * script from disk. Execution paths should prefer checkScriptHash with the
package/dist/openapi.d.ts CHANGED
@@ -213,6 +213,153 @@ export declare function buildOpenApiDocument(version: string): {
213
213
  };
214
214
  };
215
215
  };
216
+ readonly "/v1/events/errors": {
217
+ readonly post: {
218
+ readonly summary: "Append one failed hook run (error-only, no content); 120 per key per minute";
219
+ readonly operationId: "postErrorEvent";
220
+ readonly security: readonly [{
221
+ readonly apiKey: readonly [];
222
+ }];
223
+ readonly requestBody: {
224
+ readonly required: true;
225
+ readonly content: {
226
+ readonly "application/json": {
227
+ readonly schema: {
228
+ readonly type: "object";
229
+ readonly additionalProperties: false;
230
+ readonly required: readonly ["hook", "event", "class", "exit_code", "duration_ms", "station", "harness", "hooks_version", "at"];
231
+ readonly properties: {
232
+ readonly hook: {
233
+ readonly type: "string";
234
+ readonly pattern: "^[a-z0-9][a-z0-9_-]{0,127}$";
235
+ };
236
+ readonly event: {
237
+ readonly type: "string";
238
+ readonly pattern: "^[A-Za-z][A-Za-z0-9_]*$";
239
+ readonly maxLength: 64;
240
+ };
241
+ readonly class: {
242
+ readonly type: "string";
243
+ readonly enum: readonly ["nonzero-exit", "guard-blocked-unrunnable", "missing-script", "trust-changed", "trust-unreadable", "invalid-options", "start-failed", "timed-out"];
244
+ };
245
+ readonly exit_code: {
246
+ readonly type: readonly ["integer", "null"];
247
+ };
248
+ readonly duration_ms: {
249
+ readonly type: "integer";
250
+ readonly minimum: 0;
251
+ readonly maximum: 86400000;
252
+ };
253
+ readonly station: {
254
+ readonly type: "string";
255
+ readonly maxLength: 64;
256
+ };
257
+ readonly harness: {
258
+ readonly type: "string";
259
+ readonly enum: readonly ["claude", "codex", "other"];
260
+ };
261
+ readonly hooks_version: {
262
+ readonly type: "string";
263
+ readonly maxLength: 32;
264
+ };
265
+ readonly at: {
266
+ readonly type: "string";
267
+ readonly format: "date-time";
268
+ };
269
+ };
270
+ };
271
+ };
272
+ };
273
+ };
274
+ readonly responses: {
275
+ readonly "202": {
276
+ readonly description: "Recorded";
277
+ };
278
+ readonly "400": {
279
+ readonly description: "Unknown field or invalid value";
280
+ readonly content: {
281
+ readonly "application/json": {
282
+ readonly schema: {
283
+ readonly $ref: "#/components/schemas/HooksError";
284
+ };
285
+ };
286
+ };
287
+ };
288
+ readonly "429": {
289
+ readonly description: "More than 120 events from this key in the last minute";
290
+ readonly content: {
291
+ readonly "application/json": {
292
+ readonly schema: {
293
+ readonly $ref: "#/components/schemas/HooksError";
294
+ };
295
+ };
296
+ };
297
+ };
298
+ };
299
+ };
300
+ };
301
+ readonly "/v1/events/errors/summary": {
302
+ readonly get: {
303
+ readonly summary: "Hourly counts of failed hook runs by station, hook, event and class";
304
+ readonly operationId: "getErrorEventSummary";
305
+ readonly parameters: readonly [{
306
+ readonly name: "since";
307
+ readonly in: "query";
308
+ readonly required: false;
309
+ readonly schema: {
310
+ readonly type: "string";
311
+ readonly format: "date-time";
312
+ };
313
+ readonly description: "UTC instant within the last 30 days; default 24 hours ago";
314
+ }];
315
+ readonly security: readonly [{
316
+ readonly apiKey: readonly [];
317
+ }];
318
+ readonly responses: {
319
+ readonly "200": {
320
+ readonly description: "Counts per hour";
321
+ readonly content: {
322
+ readonly "application/json": {
323
+ readonly schema: {
324
+ readonly type: "object";
325
+ readonly properties: {
326
+ readonly since: {
327
+ readonly type: "string";
328
+ };
329
+ readonly hours: {
330
+ readonly type: "array";
331
+ readonly items: {
332
+ readonly type: "object";
333
+ readonly properties: {
334
+ readonly hour: {
335
+ readonly type: "string";
336
+ };
337
+ readonly station: {
338
+ readonly type: "string";
339
+ };
340
+ readonly hook: {
341
+ readonly type: "string";
342
+ };
343
+ readonly event: {
344
+ readonly type: "string";
345
+ };
346
+ readonly class: {
347
+ readonly type: "string";
348
+ };
349
+ readonly count: {
350
+ readonly type: "integer";
351
+ };
352
+ };
353
+ };
354
+ };
355
+ };
356
+ };
357
+ };
358
+ };
359
+ };
360
+ };
361
+ };
362
+ };
216
363
  readonly "/v1/selections/{profile}": {
217
364
  readonly get: {
218
365
  readonly summary: "Read one exact hosted selection profile";
@@ -2,4 +2,9 @@ import { type ApiKeyVerifier, type KeyStatusResolver } from "@hasna/contracts/au
2
2
  /** Reuse the shared issuer's signature, scope and lifecycle contract. */
3
3
  export declare function createRegistryVerifier(signingSecret: string, keyStatus: KeyStatusResolver): ApiKeyVerifier;
4
4
  export declare function hasRegistrySigningConfiguration(): boolean;
5
- export declare function authenticateRegistryRequest(request: Request, verifier?: ApiKeyVerifier): Promise<void>;
5
+ /**
6
+ * Verifies the signed key and returns its key id. Reads need hooks:read and writes hooks:write,
7
+ * except the append-only error event route, which every station's read key may use.
8
+ */
9
+ export declare function authenticateRegistryRequest(request: Request, verifier?: ApiKeyVerifier): Promise<string>;
10
+ export declare function isErrorEventWrite(method: string, path: string): boolean;
@@ -1,4 +1,5 @@
1
1
  import { HostedRegistry } from "./lib/hosted-registry.js";
2
+ import { HostedErrorEvents } from "./lib/error-events.js";
2
3
  export declare function registryReady(): Promise<boolean>;
3
4
  /** The canonical, authenticated hosted surface. No local catalog or disk-store fallback. */
4
- export declare function handleRegistryRequest(request: Request, key: string | undefined, registry?: HostedRegistry): Promise<Response>;
5
+ export declare function handleRegistryRequest(request: Request, key: string | undefined, registry?: HostedRegistry, errorEvents?: HostedErrorEvents): Promise<Response>;
@@ -100,6 +100,32 @@ export declare class HooksRegistryApiClient {
100
100
  getReady(init?: RequestInit): Promise<HooksHealth>;
101
101
  /** List the full hook catalog with versions and sha256 */
102
102
  getCatalog(init?: RequestInit): Promise<HooksCatalog>;
103
+ /** Append one failed hook run (error-only, no content); 120 per key per minute */
104
+ postErrorEvent(body: {
105
+ "hook": string;
106
+ "event": string;
107
+ "class": "nonzero-exit" | "guard-blocked-unrunnable" | "missing-script" | "trust-changed" | "trust-unreadable" | "invalid-options" | "start-failed" | "timed-out";
108
+ "exit_code": number;
109
+ "duration_ms": number;
110
+ "station": string;
111
+ "harness": "claude" | "codex" | "other";
112
+ "hooks_version": string;
113
+ "at": string;
114
+ }, init?: RequestInit): Promise<void>;
115
+ /** Hourly counts of failed hook runs by station, hook, event and class */
116
+ getErrorEventSummary(query?: {
117
+ "since"?: string;
118
+ }, init?: RequestInit): Promise<{
119
+ "since"?: string;
120
+ "hours"?: Array<{
121
+ "hour"?: string;
122
+ "station"?: string;
123
+ "hook"?: string;
124
+ "event"?: string;
125
+ "class"?: string;
126
+ "count"?: number;
127
+ }>;
128
+ }>;
103
129
  /** Publish an immutable executable artifact (requires the API key) */
104
130
  putHook(body: HooksPublishRequest, init?: RequestInit): Promise<HooksPublishResponse>;
105
131
  /** Fetch one hook's manifest and script */
package/dist/sdk/index.js CHANGED
@@ -1296,6 +1296,20 @@ class HooksRegistryApiClient {
1296
1296
  init
1297
1297
  });
1298
1298
  }
1299
+ async postErrorEvent(body, init) {
1300
+ return this.request("POST", `/v1/events/errors`, {
1301
+ body,
1302
+ query: undefined,
1303
+ init
1304
+ });
1305
+ }
1306
+ async getErrorEventSummary(query, init) {
1307
+ return this.request("GET", `/v1/events/errors/summary`, {
1308
+ body: undefined,
1309
+ query,
1310
+ init
1311
+ });
1312
+ }
1299
1313
  async putHook(body, init) {
1300
1314
  return this.request("PUT", `/v1/hooks`, {
1301
1315
  body,