Module hooks 

Remote hooks: the mkit.server.hooks.v1 adapter (SPEC-SERVER §§6-8), behind the remote-hooks feature.

A deployment can run authorization, admission and outcome delivery in a separate service, such as a payment layer. This module holds the whole protocol except the transport:

• HookChannel moves one Connect unary call (POST <base>/<procedure>, application/json, Connect-Protocol-Version: 1). The native HTTPS channel (WP-3.8) and the Workers binding (WP-3.9) will implement it.
• HookSigner signs every request over its exact body bytes with the mkit-hook:v1 domain, a fresh 32-byte nonce and a validity of at most 300 s. Only a channel that reports HookChannel::isolated (a service binding, §7.3) may go unsigned, and HookClient::new refuses anything else.
• HookVerifier is the receiving side of that signature (a hook service’s §7.1 checks), free of server-runtime dependencies.
• RemoteAuthorizer, RemoteAdmission and RemoteOutcomes share one HookClient and implement the stage traits, so any subset plugs into Hooks.
• RemoteInspector implements synchronous inspection at stage 5. The pipeline owns complete inspected-set enumeration, batching and stable inspection ids.

Failure semantics

Authorize, Admit and Inspect fail closed (§8): a transport error, timeout, non-2xx status, Connect error body, non-JSON content type, body over 64 KiB, malformed JSON, absent decision/verdict or a failed §6.6 check all answer retryable unavailable and write nothing. There is no retry inside a call. A deliberate deny in a 2xx answer is a decision, sanitised per §6.2. An Outcome is acknowledged by any 2xx; every other result is a DeliveryError that kind 8 retries with backoff, signing each attempt afresh.

Credential safety

Admit bodies carry admission credentials. Requests and responses are never logged or Debug-printed (the generated messages would print values), the request body is serialised once into an exactly sized Zeroizing buffer, the credential values of the message are wiped after the call, and every failure reason is a fixed string.

Not here

The launch profile accepts synchronous fail-closed inspection only (§18). Async inspection belongs to WP-5.5c. Event belongs to WP-5.2. AuthorizeAllow.writer_view becomes AuthzFacts::caller_view, which the pipeline honours only under the authority role (§10.1). Reservation-id uniqueness is enforced per partition by the pipeline, while §6.6 asks for it per audience: uniqueness across partitions is the hook’s obligation.

Structs

HookClient

The shared client the per-role types (RemoteAuthorizer, RemoteAdmission, RemoteOutcomes) hold behind an Arc.

HookRequest

One Connect unary call, ready to send.

HookResponse

A hook’s HTTP response, whatever its status.

HookSigner

The dedicated hook signing key. It must not be a key used for mkit-write:v2, grants, receipts or administration.

HookVerifier

Verifies signed hook requests for one hook service.

KeyListError

A refused key list.

OsNonces

The operating system’s CSPRNG.

RemoteAdmission

Stage 3 over HooksService.Admit. It returns no quota charges and every allow carries the hook’s reservation id.

RemoteAuthorizer

Stage 2 over HooksService.Authorize. Any failure, and any decision that is not a deliberate allow or deny, answers retryable unavailable.

RemoteInspector

One named synchronous inspector over a shared hook client.

RemoteOutcomes

Stage 8 over HooksService.Outcome: any 2xx acknowledges, everything else leaves the outcome queued for kind 8’s backoff.

RemotePurge

Signed durable global cache-purge delivery, distinct from admission.

Verified

A request that passed every check.

VerifierKey

One key of a §7.2 key list.

Enums

ChannelError

Why a channel produced no response. Every variant means “the hook did not answer”: the adapter fails closed (SPEC-SERVER §8).

HookConfigError

A refused adapter configuration.

InspectVerdict

A validated launch-profile verdict. Quarantine rejects the push at stage 5. Quarantine is a rejection under the launch amendment.

SignerError

A signer setting the spec refuses.

VerifyError

Why a request failed verification. The text is fixed and never quotes the request.

Constants

DEFAULT_TIMEOUT

The default per-call timeout (SPEC-SERVER §8, informative).

DEFAULT_VALIDITY

The validity interval used unless configured otherwise.

DOMAIN

The literal domain separator of the hook key use.

MAX_CLOCK_LEAD_MS

How far the sender’s clock may lead the receiver’s (SPEC-SERVER §7.1).

MAX_RESPONSE_BYTES

The largest response body core accepts (SPEC-SERVER §6.6).

MAX_VALIDITY

The longest permitted validity interval.

Traits

HookChannel

A route to one hook service.

NonceSource

The source of the fresh 32-byte nonce every attempt carries.