<!--
This file was generated by Spark. Do not edit it by hand.
-->
# AshHooks.KeyRegistry

<a id="AshHooks-KeyRegistry"></a>

Tracks opaque webhook keys that must be destroyed, using a host Ash resource.

Use this extension on a resource backed by AshPostgres or AshSqlite, with
the same repository for writes and attribute tenancy as its custody owners.
The host owns migrations, policies and scheduling. References are globally unique
`ahk_` UUIDv7 values, and each occupies one owner slot only.

Schedule `sweep/2` beside the endpoint lifecycle sweep for every tenant.
Issued references time out after `issue_timeout` seconds (900 by default);
configure this longer than the custodian's store timeout. Committed retired
references are destroyed outside transactions using their stored canonical
`custody_tenant`, even when the owner has been deleted.

Owner existence uses the injected `read_custody_owner` action, without the
host primary read's filters, preparations or pagination. The resource's
`base_filter` still applies; a row it hides counts as gone.

Only `:ok` marks a reference destroyed. An unavailable custodian is retried
with exponential backoff capped at one hour. Other answers park the obligation
in `:destroy_failed` with a fixed classification and emit
`[:ash_hooks, :key_registry, :destroy_failed]`, with `count: 1` and metadata
`registry`, `ref`, and `reason`. Backend answers are never stored or emitted.
Raised exceptions, exits and missing custodians park only that reference as
`unclassified`; subsequent references are still swept. Unavailable results
also match the attempt count they read, preserving newer retry state.
Operators inspect `pending/2`, repair the cause, then call `rearm/3`.
`destroy_generation` fences results that were in flight before rearming.
`prune/2` removes destroyed audit rows only; custody tombstones remain in
the custodian for the life of its store.

The extension injects these actions when the host has not supplied them:

* `:read`: primary read with optional keyset pagination.
* `:issue_key`: create accepting `:ref`, `:kind`, `:owner_resource`,
  `:owner_key`, `:state`, `:custody_tenant`, `:issued_at`, `:destroy_after`,
  `:attempts`, `:next_attempt_at`, `:destroy_generation`, `:last_error`,
  `:inserted_at`, and `:updated_at`.
* `:transition_key`: update accepting `:state`, `:owner_resource`,
  `:owner_key`, `:destroy_after`, `:attempts`, `:next_attempt_at`,
  `:destroy_generation`, `:last_error`, and `:updated_at`.
* `:prune_keys`: destroy a registry row.

Host-supplied actions must preserve these contracts. Restrict direct
application access to the machine write actions. Retirement returns
`{:error, :key_not_attached}` if the registry reference is not attached;
the owner write rolls back. Repair the owner/registry inconsistency before
retrying retirement; do not bypass the registry transition.

These functions perform system operations with `authorize?: false`.
Authorize application callers before exposing them.


## key_registry
Durable key disposal and crash recovery.






### Options

<table><thead><tr><th style="text-align: left;">Name</th><th style="text-align: left;">Type</th><th style="text-align: left;">Default</th><th style="text-align: left;">Docs</th></tr></thead><tbody><tr><td style="text-align: left;"><a href="#key_registry-issue_timeout" id="key_registry-issue_timeout"><code class="inline">issue_timeout</code></a></td><td style="text-align: left;"><code class="inline">pos_integer</code></td><td style="text-align: left;"><code class="inline">900</code></td><td style="text-align: left;">Seconds before an unattached issued reference is retired. Must exceed the custodian's store timeout; defaults to 15 minutes.</td></tr></tbody></table>







<style type="text/css">.spark-required::after { content: "*"; color: red !important; }</style>
