A host-owned resource for inbound webhook keys, provider selection and pause.
Sources use opaque keys through AshHooks.Custody. The host owns the data
layer, policies and migrations. Source and ledger resources must have the
same tenancy and non-nullable scope attributes. Provider aliases select
modules from a compile-time allowlist. Each ledger declaration's source_record
must name a source whose ledger is that declaring resource.
The extension injects the following attributes for host migrations:
- The declaration-name attribute (
:sourceby default) is a required atom. Each locally declared scope attribute is required.:provideris a required atom constrained to the allowlist's aliases. :secret_refand:previous_secret_refare nullable opaque reference strings.:secret_kindand:previous_secret_kindare nullable terms.:public_keyand:public_key_kindare nullable terms for pinned sender verification material outside custody. Its kind must be one ofAshHooks.Custody.PublicKey's closed asymmetric kinds, and the material must decode under that kind before creation or registration.:pausedis a required boolean defaulting to false.:secret_created_at,:secret_first_used_at,:previous_secret_created_at,:previous_secret_first_used_atand:previous_secret_retired_atare nullable microsecond UTC datetimes.
Without a host primary key, the extension adds a writable UUID :id with a
generated default. The :unique_source identity comprises the declaration-name
attribute and scope attributes, under the resource's tenancy. Host attributes
with injected names must match their type, constraints and nullability.
Lifecycle functions are system writes using authorize?: false. Authorize
callers before invoking them and restrict direct access to injected machine
actions. Generated disclosures are returned once and must be delivered to
the sender securely. They are never stored on the source.
Injected machine actions are :roll_secret, :schedule_previous_retirement,
:expire_previous_secret, :register_public_key, :pause, :unpause,
:mark_current_secret_used, :mark_previous_secret_used, :set_custody_keys
and :read_custody_owner. Secret-bearing arguments are sensitive. Direct
kind input is refused on host create and update actions. Direct reference
input is always refused; use create_source/3 to issue and attach
references through the key registry.
Summary
Functions
Adopts pre-cutover nil-alias receipts for this source resource's ledger.
name must select a declaration fed by this resource, and alias must be
in its allowlist. expected_provider: can pin the old declaration's module.
Each claim atomically stamps its alias and commits before handling.
Options: :tenant, positive :limit (default 100), :expected_provider.
Returns {:ok, %{driven: count, remaining: count}}. Remaining includes live
pre-cutover claims; repeat until it reaches zero. Refuses enclosing transactions
before reading with {:error, :inside_transaction}. Terminal nil-alias rows
remain unchanged. Returns {:error, :invalid_limit} for a nonpositive or
noninteger limit, {:error, :source_mismatch} when the declaration does not
use this source resource, and {:error, :provider_mismatch} for an unknown
alias or a mismatched :expected_provider. Correct the arguments before retrying.
Creates a source with material: and kind:, generate: {:standard_webhooks, :v1}, or a pinned public_key: and kind:. Optional previous: material
requires previous_retires_at:; previous_kind: defaults to the current kind.
Returns {:ok, source} or {:ok, source, disclosure} for generation.
Issuing refuses enclosing transactions. Direct reference input is refused.
Options include :tenant, :action and the application clock :now.
Removes the previous key and retires its custody reference for disposal. Options: :tenant, :now.
Sweeps dated previous keys whose deadlines have ended. Returns {:ok, count}. Options: :tenant, :now.
Pauses new requests; authenticated receipts remain recoverable. Option: :tenant.
Pins a sender's public verification key outside custody. The required
:kind is one of AshHooks.Custody.PublicKey's asymmetric kinds. Invalid
kinds or undecodable keys return KeyKindMismatch before writing.
Option: :tenant.
Generates a replacement current key of the same kind, leaving the previous
key and its retirement time unchanged. Returns the one-time disclosure.
Only the symmetric standard v1 kind may be generated; sender-issued kinds
return :kind_not_allowed before issuance. The replaced current key stops
verifying immediately. Only the separate previous key keeps working until
its own deadline. Options: :tenant and :now. Refuses enclosing transactions.
Rolls the current custody key with sender-issued material: and kind:,
or generate: {:standard_webhooks, :v1}. Generation returns a one-time
whsec_ disclosure. Other generation kinds return :kind_not_allowed
before issuance. Options: :tenant, :now, and :overlap_seconds.
An active overlap refuses another roll. Expire the previous key first or
wait for its deadline. Issuing refuses an enclosing transaction.
Sets a previous key's retirement time, fenced on its reference. Options: :tenant, :now.
Resumes new requests. Option: :tenant.
Functions
@spec adopt_provider_alias(module(), atom(), atom(), keyword()) :: {:ok, %{driven: non_neg_integer(), remaining: non_neg_integer()}} | {:error, term()}
Adopts pre-cutover nil-alias receipts for this source resource's ledger.
name must select a declaration fed by this resource, and alias must be
in its allowlist. expected_provider: can pin the old declaration's module.
Each claim atomically stamps its alias and commits before handling.
Options: :tenant, positive :limit (default 100), :expected_provider.
Returns {:ok, %{driven: count, remaining: count}}. Remaining includes live
pre-cutover claims; repeat until it reaches zero. Refuses enclosing transactions
before reading with {:error, :inside_transaction}. Terminal nil-alias rows
remain unchanged. Returns {:error, :invalid_limit} for a nonpositive or
noninteger limit, {:error, :source_mismatch} when the declaration does not
use this source resource, and {:error, :provider_mismatch} for an unknown
alias or a mismatched :expected_provider. Correct the arguments before retrying.
@spec create_source(module(), map(), keyword()) :: {:ok, struct()} | {:ok, struct(), term()} | {:error, term()}
Creates a source with material: and kind:, generate: {:standard_webhooks, :v1}, or a pinned public_key: and kind:. Optional previous: material
requires previous_retires_at:; previous_kind: defaults to the current kind.
Returns {:ok, source} or {:ok, source, disclosure} for generation.
Issuing refuses enclosing transactions. Direct reference input is refused.
Options include :tenant, :action and the application clock :now.
Removes the previous key and retires its custody reference for disposal. Options: :tenant, :now.
@spec expire_previous_secrets(module(), keyword()) :: {:ok, non_neg_integer()} | {:error, term()}
Sweeps dated previous keys whose deadlines have ended. Returns {:ok, count}. Options: :tenant, :now.
Pauses new requests; authenticated receipts remain recoverable. Option: :tenant.
Pins a sender's public verification key outside custody. The required
:kind is one of AshHooks.Custody.PublicKey's asymmetric kinds. Invalid
kinds or undecodable keys return KeyKindMismatch before writing.
Option: :tenant.
Generates a replacement current key of the same kind, leaving the previous
key and its retirement time unchanged. Returns the one-time disclosure.
Only the symmetric standard v1 kind may be generated; sender-issued kinds
return :kind_not_allowed before issuance. The replaced current key stops
verifying immediately. Only the separate previous key keeps working until
its own deadline. Options: :tenant and :now. Refuses enclosing transactions.
@spec roll_secret(struct(), keyword()) :: {:ok, struct()} | {:ok, struct(), term()} | {:error, term()}
Rolls the current custody key with sender-issued material: and kind:,
or generate: {:standard_webhooks, :v1}. Generation returns a one-time
whsec_ disclosure. Other generation kinds return :kind_not_allowed
before issuance. Options: :tenant, :now, and :overlap_seconds.
An active overlap refuses another roll. Expire the previous key first or
wait for its deadline. Issuing refuses an enclosing transaction.
@spec schedule_previous_retirement(struct(), term(), keyword()) :: {:ok, struct()} | {:error, term()}
Sets a previous key's retirement time, fenced on its reference. Options: :tenant, :now.
Resumes new requests. Option: :tenant.