Custody of opaque webhook keys. Secret bytes never return to ash_hooks
after AshHooks.Custody.store/4.
Material and kinds
material is decoded cryptographic material only: raw HMAC key bytes or
an Ed25519 seed. The caller decodes whsec_, whsk_, base64, hex, and
provider encodings. Custody never parses wire prefixes or encodings.
{:standard_webhooks, :v1}: HMAC-SHA256, 24 to 64 bytes, sign and verify.{:standard_webhooks, :v1a}: Ed25519, exactly a 32-byte seed, sign and verify; its public half may be disclosed.{:sender_hmac, digest}::sha1,:sha256,:sha384, or:sha512, 1 to 16,384 decoded bytes as issued, verify only. Signing returns{:error, :not_signable}.{:legacy_hmac, :sha256}: at least one byte as issued, with no ceiling, sign and verify. Even prefix-shaped material is stored byte for byte.
Import bounds are not generation policy. Package-generated spec and legacy keys use 32 cryptographically random bytes; sender keys are never generated or admitted to an endpoint slot.
The kind is fixed at store. Every expected_kind is an assertion and must
be checked before computing. A mismatch returns {:error, :kind_mismatch}.
Verification compares the full decoded MAC in constant time and refuses
truncated MACs with {:error, :invalid_signature}.
:unavailable means custody could not answer and is retryable. Every other
error is final for that attempt. ash_hooks classifies backend errors without
exposing their terms. A callback that raises, exits or throws becomes a
contents-free AshHooks.Errors.Unknown.UnknownError, an outage rather than
a signature verdict.
References, tenant binding, and destruction
ashhooks chooses `"ahk" <> UUIDv7references, one per slot occupancy; references are never shared. Store is idempotent for the exact reference, material, kind, and tenant. Other reuse of a live reference returns the:ref_exists` error.
A reference is bound globally and atomically to the canonical tenant of
its first store or destroy. Reference uniqueness is global, never per tenant.
For another tenant, sign, verify, public-key disclosure, and fingerprint
return {:error, :unknown_ref} without computing or revealing existence.
Store returns :ref_exists for a live reference and :ref_destroyed for a
tombstoned reference. Destroy returns {:error, :tenant_mismatch} and
changes nothing, leaving the original tenant's key working.
Destroy is idempotent under the bound tenant, succeeds for a never-stored
reference, and leaves a permanent tombstone for the life of the custody
store. Every later store returns {:error, :ref_destroyed}. Store and
destroy of a reference must be linearizable: the second operation sees
the first, including a delayed store arriving after destruction. A destroy
under A then store under B, or destroy under B of an absent reference then
store under A, both refuse store with :ref_destroyed. Store under A then
destroy under B refuses destroy with :tenant_mismatch.
Canonical tenants come from canonical_tenant/3, using the owner resource's
create-path conversion. Non-multitenant owners use nil. Attribute tenancy
supports UUID, UUIDv7, integer, string, and case-insensitive string. For any
other type the host supplies custody_tenant_key: {module, function, args}.
It receives the cast value followed by args and must return the same
UTF-8 binary for values the database treats as equal. This equality
contract belongs to the host. tenant_type_supported?/2 lets resource
verifiers check coverage at compile time. Context tenancy is unsupported.
Fingerprints
For v1 and v1a, fingerprint/3 returns the first 16 bytes of
SHA-256("ash_hooks key fingerprint v1\0" <> kind_label <> "\0" <> key_bytes).
The labels are standard_webhooks.v1 and standard_webhooks.v1a.
key_bytes is the exact stored HMAC material for v1, and the Ed25519
public key derived from the seed for v1a. Custody returns the digest only;
ash_hooks formats "SHA256:" <> unpadded_base64url(digest).
Sender and legacy kinds return {:error, :no_fingerprint}. An unkeyed
fingerprint of an as-issued secret could enable offline guessing.
Display fingerprints are safe to show for securely generated keys; this
truncated, domain-separated hash does not protect weak or predictable
secrets from offline guessing. It is distinct from the correlation-only
AshHooks.Telemetry.fingerprint/1.
Custodians can run AshHooks.Custody.Conformance in their test suite against
a fresh real store to exercise these contracts.
Summary
Functions
Derives canonical custody text from a tenant and its owner resource.
Displays a custody key's fingerprint as SHA256: plus unpadded base64url.
Whether an owner's tenant type has a canonical custody representation.
Types
Callbacks
Functions
@spec canonical_tenant(term(), module(), keyword()) :: {:ok, tenant()} | {:error, :invalid_tenant | :unsupported_tenant_type}
Derives canonical custody text from a tenant and its owner resource.
Applies Ash.ToTenant.to_tenant/2, the multitenancy parse_attribute, and
Ash.Type.cast_input/3 with the tenant attribute's constraints, in that
order. UUIDs are lowercase hyphenated text, integers are decimal, strings
are exact valid UTF-8, and ci_strings are downcased. Other types require
the :custody_tenant_key MFA option described in the module contract.
Returns {:error, :invalid_tenant} for rejected inputs and invalid hook results,
or {:error, :unsupported_tenant_type} for uncovered tenant types or
unsupported tenancy declarations. Non-multitenant resources return
{:ok, nil} without interpreting the supplied tenant. Exceptions raised by
application code in Ash.ToTenant, parse_attribute, or custody_tenant_key
propagate. Inside an Ash action, such an exception rolls the action back.
@spec display_fingerprint(AshHooks.Custody.Key.t()) :: {:ok, String.t()} | {:error, struct() | :no_fingerprint}
Displays a custody key's fingerprint as SHA256: plus unpadded base64url.
v1 and v1a ask the custodian for the 16-byte digest defined in the module
contract. Sender and legacy kinds return {:error, :no_fingerprint}
without calling custody. Custody errors become classified package errors,
including AshHooks.Errors.Invalid.KeyKindMismatch for a kind mismatch.
Safe to show for securely generated keys. This hash does not protect a weak or predictable secret against offline guessing.
Whether an owner's tenant type has a canonical custody representation.
Accepts a resource module or the DSL state available to a compile-time
verifier. No tenant value or custody call is needed. Other types are
covered only with a :custody_tenant_key MFA option. This function checks
coverage; it does not install a verifier on a resource.