# `AshHooks.InboundSource`
[🔗](https://github.com/baselabs/ash_hooks/blob/v3.3.0/lib/ash_hooks/inbound_source.ex#L1)

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.

# `adopt_provider_alias`

```elixir
@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`

```elixir
@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`

```elixir
@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`

```elixir
@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`
*macro* 

# `pause`

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

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

# `register_public_key`

```elixir
@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`

```elixir
@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`

```elixir
@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`

```elixir
@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`

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

Resumes new requests. Option: `:tenant`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
