AshHooks.InboundSource (AshHooks v3.3.0)

Copy Markdown View Source

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 (:source by default) is a required atom. Each locally declared scope attribute is required. :provider is a required atom constrained to the allowlist's aliases.
  • :secret_ref and :previous_secret_ref are nullable opaque reference strings. :secret_kind and :previous_secret_kind are nullable terms.
  • :public_key and :public_key_kind are nullable terms for pinned sender verification material outside custody. Its kind must be one of AshHooks.Custody.PublicKey's closed asymmetric kinds, and the material must decode under that kind before creation or registration. :paused is a required boolean defaulting to false.
  • :secret_created_at, :secret_first_used_at, :previous_secret_created_at, :previous_secret_first_used_at and :previous_secret_retired_at are 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

adopt_provider_alias(resource, name, alias, opts \\ [])

@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.

create_source(resource, attributes, opts \\ [])

@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.

expire_previous_secret(source, opts \\ [])

@spec expire_previous_secret(struct(), keyword()) ::
  {:ok, struct()} | {:error, term()}

Removes the previous key and retires its custody reference for disposal. Options: :tenant, :now.

expire_previous_secrets(resource, opts \\ [])

@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.

inbound_source(body)

(macro)

pause(source, opts \\ [])

@spec pause(struct(), keyword()) :: {:ok, struct()} | {:error, term()}

Pauses new requests; authenticated receipts remain recoverable. Option: :tenant.

register_public_key(source, public_key, opts \\ [])

@spec register_public_key(struct(), term(), keyword()) ::
  {:ok, struct()} | {:error, term()}

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.

reissue_secret(source, opts \\ [])

@spec reissue_secret(struct(), keyword()) ::
  {:ok, struct(), term()} | {:error, term()}

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.

roll_secret(source, opts \\ [])

@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.

schedule_previous_retirement(source, at, opts \\ [])

@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.

unpause(source, opts \\ [])

@spec unpause(struct(), keyword()) :: {:ok, struct()} | {:error, term()}

Resumes new requests. Option: :tenant.