@hasna/hooks 0.9.4 → 0.9.6

package/README.md

@@ -48,6 +48,33 @@ tools return compact summaries by default, while explicit flags such as
 `compact:false`, `verbose:true`, or a detail tool like `hooks_info` return full
 records.
 
+## Recoverable deletion guards
+
+```bash
+hooks safety install trash-guard --target codex
+# Or --target claude. Use --overwrite to update an existing registration.
+```
+
+This installs a bundled, synchronous safety capability without requiring a Hooks
+registry credential. Generic `hooks run`, registry commands, and custom hooks keep
+their existing authentication requirements. The Trash guard also evaluates the
+protected repository policy, so its handoff cannot silently permit deletion.
+
+The installed command pins its absolute Bun runtime and complete worker bundle.
+It verifies those bytes before execution and blocks startup failures, malformed
+input/output, changed files and deadlines. Native execution has a ten-second
+budget; its own watchdog refuses after six seconds. Updating Bun or Hooks requires
+reinstalling the registration and reviewing the new native trust definition. Unsafe
+installation paths are refused before settings are written. Codex also requires
+trust through `/hooks`; registration alone does not prove interception.
+
+Supported controls cover shell `rm` rewrites through a verified `@hasna/trash`
+guard, explicit unsupported delete commands, and whole-file `apply_patch`
+deletions. They do not intercept arbitrary filesystem syscalls, application APIs,
+or in-place edits. A missing or unauthenticated Trash client refuses the rewritten
+operation; it never falls back to raw removal. Configure hosted Trash and verify a
+disposable capture/restore before relying on recoverable deletion.
+
 ## Optional Mementos prompt context
 
 `hooks install mementos-context --target codex` registers a native prompt hook.
@@ -181,6 +208,17 @@ export HASNA_HOOKS_API_KEY_REF=<vault-key-name>   # resolved through the vault a
 secrets exec <vault-key-name> --as HASNA_HOOKS_API_KEY -- hooks serve
 ```
 
+The owner-only `~/.hasna/hooks/config/credentials` file also accepts a reference:
+
+```dotenv
+HASNA_HOOKS_API_URL=https://registry.example.com
+HASNA_HOOKS_API_KEY_REF=your-team/hooks/live/api-key
+```
+
+Keep this file at mode `0400` or `0600`, and configure Secrets through its normal independent credential resolver. Hooks resolves the selected reference through the Secrets SDK for each registry request and each server publish-key check. References retain their existing precedence: a locked Keychain remains a refusal ahead of a file reference, and a missing reference never falls through to a stale literal key. A file cannot contain both a literal key and a reference.
+
+`hooks list` displays catalog metadata and does not prove that the remote registry is reachable. Use `hooks sync --dry-run` to exercise registry reads without changing installed hooks. SDK consumers use `createHooksClient()`; callers working directly with transport metadata must await `resolveHooksRequestAuthority()` before sending a request. The server uses `resolveHooksServePublishKeyAsync()` for references.
+
 **Cloudflare provisioning.** `hooks cf deploy` creates the D1 database and R2 bucket via the Cloudflare API, then prints the exact wrangler commands for the worker upload (the worker needs the workerd target, which only wrangler can bundle):
 
 ```bash
@@ -193,8 +231,8 @@ The worker (`src/cf/worker.ts`) implements the same API routes against D1 + R2,
 
 ## Storage
 
-Hooks stores data locally by default in `~/.hasna/hooks/` and uses SQLite
-directly for hook event history. The package owns its database schema and
+When local mode is explicitly selected, Hooks stores data in `~/.hasna/hooks/`
+and uses SQLite for hook event history. The package owns its database schema and
 migrations; it does not depend on the deprecated shared runtime or its CLI.
 The repo includes its own PostgreSQL migration definitions for the optional
 `hooks storage push|pull|sync` commands. Use the `hooks log` commands to inspect