ankusa-sdk 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 817a62bfe2b9d6f6f4dc513d32cb6a4e4091de4e79bd37ef9b5432a44eca6a60
-  data.tar.gz: 74ac90d9dccf5b681519f6870221bcddc11a96d015d945cffc68200606e2c808
+  metadata.gz: 3dbf23058e4a0799746070c44c18c750554e2298a2ae1dbe149d25bc9f9f4b22
+  data.tar.gz: 3aeaae91dbb2d4530678e9da87a365aafc5df73ab684047066aefae45b802ce6
 SHA512:
-  metadata.gz: ca0aa04bed9460cc20cc1db4b262ff711c65762b284b60486bdcf49825800e03e4173ca319553eaa3ab21f4151aa68fce7a5350e861bb3626d29e48028c02b91
-  data.tar.gz: 290a4cd6343778e9236772c3394877302ce97180c751c80a80420127698bfede89a859c413ea919280870bf57f355f6019628740cf4427c76ad2a39e70e1457b
+  metadata.gz: 78397c0e96fc065f7a4d30d0bcf533b07d86dec71d9c185d55fdd415f0ee5b1373e83e9af43bcc70ddb89b5a71d48970bfd38954e5cc2afce0ddcf0e06a0fd90
+  data.tar.gz: 0d0cc364cd091f83daa7425bd1df37e7a41b1cadaefc00b00776a193dbef97a3d5ea527f15ba80a01a5f97bca77a37d7c6c5162bca9849f8cbd247ad1135a3b9

data/CHANGELOG.md

@@ -6,6 +6,53 @@ this project follows [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-10-28
+
+### Added
+
+- `Message#traceparent` and `Message#tracestate`: the hook's W3C trace context
+  from the message, verbatim (`nil` when none); a non-string value is
+  `invalid_field`.
+
+- `verification` on parsed headers, decoded messages and received deliveries:
+  how Ankusa verified the hook at ingest (`{status, flagged}`, `null` from a
+  node older than the field).
+- `Ankusa.parse_claim_ref` and `ClaimCheckClient#redeem` accept signed,
+  expiring v2 refs
+  (`urn:ankusa:claim:v2:<tenant>:<claim_id>:<exp_unix>:<signature>`): the
+  parsed `path` carries `?exp=&sig=` and `redeem` requests it as is. The
+  gateway's `400 bad_signature` and `410 ref_expired` are a
+  `ClaimRejectedError`. The SDK never checks the signature or the expiry.
+- `Ankusa.receive_delivery(headers, body, secrets: [], allow_unsigned: false,
+  tolerance_seconds: 300, now: nil)`, the receiver-side decision on one
+  HTTP-sink delivery. The sink signs every delivery unless configured
+  `allow_unsigned: true`, so a receiver is closed by default: with `secrets`
+  the delivery must verify (as `verify_signature`); with none and no
+  `allow_unsigned: true` it raises `InvalidSignatureError` (`invalid_secret`).
+  The signature is judged before the hook id. Returns a `ReceivedDelivery`
+  (`headers`, `verified`).
+- `scope` on `AdminRejectedError` and `RoutesRejectedError`: the scope a `403
+  forbidden` says the credential lacks (control planes require a credential
+  since Ankusa 0.6).
+- `Admin#list_audit(**params)`: `GET /v1/audit`, the audit trail (newest first,
+  paged by `cursor`/`limit`, filtered by `since`, `until`, `actor`, `action`,
+  `tenant`).
+- **Delivery metadata (CON-4).** `HookHeaders#received_at` (when the edge accepted the hook, unix milliseconds, from `x-ankusa-received-at`) and `HookHeaders#body_sha256` (the lowercase hex SHA-256 of the body sent, from `x-ankusa-body-sha256`): nil when the header is absent, empty or malformed, never an error.
+
+- **Wire-format evolution path (CON-2).** `Ankusa.decode_message` accepts every
+  `v` from `Ankusa::MIN_SUPPORTED_VERSION` to `Ankusa::MAX_SUPPORTED_VERSION`
+  (1 and 2) into the one `Message`, with `v` as the wire said it: a `v: 2`
+  message is a `v: 1` message plus additive fields, so the keys it does not know
+  are ignored. `Message#instance` and `Message#region`: the name of the Ankusa
+  instance that published the message and the region it is configured with (nil
+  when null or absent). `Ankusa.decode_lifecycle` and `Ankusa::LifecycleEvent`
+  decode the CloudEvents lifecycle events of the instance's lifecycle sinks.
+
+- `Message#trusted?`, `HookHeaders#trusted?` and `Verification#trusted?`: true
+  only when the node verified the hook at ingest (status `"ok"`) and did not
+  flag it. A flagged, `"failed"` or `"skipped"` hook and one with no
+  `verification` are untrusted.
+
 ## [0.5.0] - 2026-10-14
 
 ### Added
@@ -74,6 +121,7 @@ this project follows [Semantic Versioning](https://semver.org/).
   family, which carries `.status` and `.body` instead), so a consumer needs
   exactly one bit to route a failure to dead-letter or retry.
 
-[Unreleased]: https://github.com/jamescarr/ankusa/compare/sdk-ruby-v0.5.0...HEAD
+[Unreleased]: https://github.com/jamescarr/ankusa/compare/sdk-ruby-v0.6.0...HEAD
+[0.6.0]: https://github.com/jamescarr/ankusa/compare/sdk-ruby-v0.5.0...sdk-ruby-v0.6.0
 [0.5.0]: https://github.com/jamescarr/ankusa/compare/sdk-ruby-v0.3.0...sdk-ruby-v0.5.0
 [0.3.0]: https://github.com/jamescarr/ankusa/releases/tag/sdk-ruby-v0.3.0

data/README.md

@@ -26,14 +26,6 @@ then, in code:
 require "ankusa/sdk"
 ```
 
-Before the first RubyGems release, depend on it as a path gem the same way the
-Elixir packages in this monorepo depend on `ankusa` core before their first Hex
-release:
-
-```ruby
-gem "ankusa-sdk", path: "packages/sdk-ruby"
-```
-
 Everything the SDK exposes lives under `Ankusa::`.
 
 ## Claim-check client
@@ -156,8 +148,54 @@ pass several during a rotation. `tolerance_seconds:` (default 300) bounds the
 `webhook-timestamp` window. Failures are `Ankusa::InvalidSignatureError` with
 `code` and `field`, never retryable.
 
+### Receiving a delivery (signed by default)
+
+Ankusa's HTTP sink signs every delivery unless it is configured
+`allow_unsigned: true`, so a receiver is closed by default.
+`Ankusa.receive_delivery` is the one call that decides: with the sink's
+`secrets:` it verifies as above; with none, and no `allow_unsigned: true`, it
+refuses every delivery (`Ankusa::InvalidSignatureError`, code
+`invalid_secret`) — otherwise any host that can reach your URL could inject
+hooks. A configured secret is never weakened by `allow_unsigned:`. The
+signature is judged before the hook id, so a delivery that fails it is a `401`
+even when it also lacks `x-ankusa-id` (`Ankusa::MissingHookIdError`, `400`).
+
+```ruby
+begin
+  received = Ankusa.receive_delivery(header_map(env), body, secrets: [ENV.fetch("ANKUSA_WHSEC")])
+  # received.headers is the HookHeaders; received.verified is false only for an
+  # unsigned delivery `allow_unsigned: true` let through.
+rescue Ankusa::InvalidSignatureError => e
+  return [401, {"content-type" => "application/json"},
+    [JSON.generate(error: "invalid_signature", code: e.code)]]
+rescue Ankusa::MissingHookIdError
+  return [400, {"content-type" => "application/json"},
+    [JSON.generate(error: "missing x-ankusa-id")]]
+end
+```
+
+`hook.verification` (also on `Ankusa.parse_headers` and `Ankusa.decode_message`
+results) says how the *node* verified the hook at ingest, `nil` from a node
+older than the field. `hook.verification&.flagged == true` means the node
+accepted a failed check (`on_verify_failure: accept_flag`) — treat it as
+unverified. `hook.trusted?` (on messages and parsed headers) is that decision
+in one call: true only for status `"ok"` with `flagged` false, so a flagged,
+`"failed"` or `"skipped"` hook, or one from a node older than the field, is
+untrusted.
+
 ## Consuming queue messages
 
+The message's `v` is the wire format's major version: `Ankusa.decode_message`
+accepts every `v` from `Ankusa::MIN_SUPPORTED_VERSION` to
+`Ankusa::MAX_SUPPORTED_VERSION` (1 and 2) into the one `Message`, with `v` as
+the wire said it. A `v: 2` message is a `v: 1` message plus additive fields, so
+a consumer reads it the same way; any other `v` is `unsupported_version`
+(permanent: dead-letter it). `message.instance` and `message.region` are the
+Ankusa instance that published the message and the region it is configured with
+(nil for none). A message from the instance's lifecycle sinks carries a
+CloudEvents event as its body: `Ankusa.decode_lifecycle(body)` returns an
+`Ankusa::LifecycleEvent`.
+
 Every message sink — RabbitMQ, Kafka, NATS, Redis — delivers one JSON message
 per hook (the HTTP sink sends the original body plus `x-ankusa-*` headers
 instead):
@@ -254,8 +292,9 @@ unfollowed redirect, a non-JSON success body, or unreachable; retryable).
 ## Admin client
 
 The operator API on `admin.port` (default 4002): health, Prometheus metrics, the
-redacted config, the DLQ, replay jobs, and the quarantine list — the
-`operations`, `dlq`, `replays`, and `quarantine` tags of `admin.v1.yaml`.
+redacted config, the DLQ, the audit trail, replay jobs, and the quarantine
+list — the `operations`, `dlq`, `audit`, `replays`, and `quarantine` tags of
+`admin.v1.yaml`.
 
 ```ruby
 require "ankusa/sdk"
@@ -265,6 +304,7 @@ admin = Ankusa::AdminClient.new(ENV.fetch("ADMIN_URL", "http://localhost:4002"))
 admin.health                          # {"status" => "ok", "instance" => ..., "roles" => [...]}
 admin.list_dead_letters({"limit" => 10})  # {"total" => ..., "entries" => [...]}
 admin.list_quarantined
+admin.list_audit({"tenant" => "acme", "limit" => 50})  # {"entries" => [...], "next_cursor" => ...}
 
 job = admin.create_replay({"kind" => "dlq", "source_id" => "stripe", "rate" => 500})
 admin.get_replay(job["id"])
@@ -275,10 +315,12 @@ admin.update_replay(job["id"], {"state" => "paused"})   # resume, pause or cance
 `create_replay` is idempotent for retries: a second POST of the same filter
 while the job is `running`/`paused` returns the existing job (`200`) instead of
 starting another (`202`). `list_replays` returns `{"replays" => [...]}` exactly
-as the API sends it.
+as the API sends it. `list_audit` returns the audit trail newest first,
+`{"entries" => [...], "next_cursor" => ...}`, paged by `cursor`/`limit` and
+filtered by `since`, `until`, `actor`, `action` and `tenant`.
 
 Methods: `health`, `metrics` (Prometheus text), `config`, `list_dead_letters`,
-`create_replay`, `get_replay`, `list_replays`, `update_replay`,
+`list_audit`, `create_replay`, `get_replay`, `list_replays`, `update_replay`,
 `list_quarantined`. Failures are `AdminError` subclasses: `RoleNotEnabledError`
 (409 `role_not_enabled`, carrying `role`), `AdminRejectedError` (any other 4xx —
 a missing replay is a 404 with `code` `replay_not_found`), and

data/lib/ankusa/admin.rb

@@ -34,14 +34,16 @@ module Ankusa
   # The listener rejected the request (any other 4xx).
   #
   # `status` is the HTTP status; `code` is the body's `error` field
-  # (`invalid_filter`, ...).
+  # (`invalid_filter`, ...). `scope` is the scope a 403 forbidden says the
+  # credential lacks, nil when absent or not a 403.
   class AdminRejectedError < AdminError
-    attr_reader :status, :code
+    attr_reader :status, :code, :scope
 
-    def initialize(message, status:, code:)
+    def initialize(message, status:, code:, scope: nil)
       super(message)
       @status = status
       @code = code
+      @scope = scope
     end
   end
 
@@ -81,6 +83,15 @@ module Ankusa
       json(request("GET", "/v1/dlq", query: params))
     end
 
+    # GET /v1/audit -> a page of the audit trail, newest first.
+    #
+    # `params` may carry `cursor`, `limit`, `since`, `until`, `actor`,
+    # `action` and `tenant`; absent keys are omitted from the query string
+    # rather than sent as `=`.
+    def list_audit(params = nil)
+      json(request("GET", "/v1/audit", query: params))
+    end
+
     # POST /v1/replays -> the created Replay, as a Hash.
     #
     # `spec` is the replay spec: `{"kind" => "dlq", ...}`,
@@ -153,10 +164,12 @@ module Ankusa
       end
 
       if status >= 400 && status < 500
+        scope = body.is_a?(Hash) ? body["scope"] : nil
         raise AdminRejectedError.new(
           "admin listener rejected the request (#{status}): #{body.inspect}",
           status: status,
-          code: code
+          code: code,
+          scope: scope
         )
       end
 

data/lib/ankusa/claim_check.rb

@@ -58,24 +58,31 @@ module Ankusa
   # Mirrors `#/components/schemas/Ref` in priv/openapi/claim_check.v1.yaml --
   # keep the two in sync. A ref is one string:
   #   urn:ankusa:claim:v1:<tenant>:<claim_id>
+  #   urn:ankusa:claim:v2:<tenant>:<claim_id>:<exp_unix>:<signature>
+  # <exp_unix> is a decimal of 1-12 digits with no leading zero and <signature>
+  # 43 unpadded base64url characters. The gateway checks the signature; the
+  # SDK only carries it.
   #
   # \A...\z, never ^...$: Ruby's ^ and $ are line anchors, so a ref ending in a
   # newline would otherwise parse.
   CLAIM_REF_PATTERN = /\Aurn:ankusa:claim:v1:([A-Za-z0-9_-]{1,64}):([0-7][0-9A-HJKMNP-TV-Z]{25})\z/
+  CLAIM_REF_V2_PATTERN =
+    /\Aurn:ankusa:claim:v2:([A-Za-z0-9_-]{1,64}):([0-7][0-9A-HJKMNP-TV-Z]{25}):([1-9][0-9]{0,11}):([A-Za-z0-9_-]{43})\z/
 
   SHA256_PATTERN = /\A[0-9a-f]{64}\z/
 
   # Parses a claim-check ref (the `claim` field of a queue message) into the
-  # tenant id, claim id, and GET /v1/claims/{tenant_id}/{claim_id} path. Raises
-  # `InvalidClaimRefError` -- never worth retrying -- if `ref` isn't a
-  # well-formed ref.
+  # tenant id, claim id, and GET /v1/claims/{tenant_id}/{claim_id} path (with
+  # ?exp=&sig= for a v2 ref). Raises `InvalidClaimRefError` -- never worth
+  # retrying -- if `ref` isn't a well-formed ref.
   def self.parse_claim_ref(ref)
-    match = ref.is_a?(String) ? CLAIM_REF_PATTERN.match(ref) : nil
+    match = ref.is_a?(String) ? (CLAIM_REF_V2_PATTERN.match(ref) || CLAIM_REF_PATTERN.match(ref)) : nil
     raise InvalidClaimRefError, "invalid claim-check ref: #{ref}" if match.nil?
 
-    tenant_id = match[1]
-    claim_id = match[2]
-    ParsedClaimRef.new(tenant_id: tenant_id, claim_id: claim_id, path: "/v1/claims/#{tenant_id}/#{claim_id}")
+    tenant_id, claim_id, exp, sig = match.captures
+    path = "/v1/claims/#{tenant_id}/#{claim_id}"
+    path += "?exp=#{exp}&sig=#{sig}" if sig
+    ParsedClaimRef.new(tenant_id: tenant_id, claim_id: claim_id, path: path)
   end
 
   # Redeem claim-check refs against a deployment's claim-check gateway.

data/lib/ankusa/lifecycle.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Ankusa
+  # One decoded lifecycle event: the CloudEvents 1.0 (structured mode) event an
+  # Ankusa instance publishes when a source or a route is created, updated or
+  # deleted, when a tenant is erased, or when the instance is restored from a
+  # backup. It arrives as the body of a queue message from the instance's
+  # lifecycle sinks (content type `application/cloudevents+json`, `source_id`
+  # `ankusa:lifecycle`): decode the message with `Ankusa.decode_message`,
+  # redeem its body, and hand the bytes to `Ankusa.decode_lifecycle`.
+  #
+  # Delivery is at least once and in commit order. `id` is derived from the
+  # change, so the same event always has the same id, and `revision` (per
+  # `subject`) lets a consumer ignore a stale update. `sequence` is the
+  # instance's audit sequence number, the decimal string it is on the wire.
+  # `data` is the entity as the admin API shows it, secrets redacted (nil when
+  # the event carries none). An optional field the event omitted or said `null`
+  # is nil.
+  LifecycleEvent = Data.define(
+    :specversion, :id, :source, :type, :subject, :time, :datacontenttype, :data, :revision,
+    :actor, :instance, :sequence, :replayid, :traceparent, :tracestate
+  )
+
+  LIFECYCLE_REQUIRED_FIELDS = %w[id source type subject time].freeze
+  LIFECYCLE_DECIMAL = /\A[0-9]+\z/
+  private_constant :LIFECYCLE_REQUIRED_FIELDS, :LIFECYCLE_DECIMAL
+
+  # Decodes one lifecycle event (the JSON of the CloudEvent) into a
+  # `LifecycleEvent`. The checks run in a fixed order and the first failure
+  # wins, raising `InvalidMessageError` (never retryable): `invalid_json`,
+  # `not_an_object`, `unsupported_version` (`specversion` is not "1.0") or
+  # `invalid_field` with the offending `field`. Keys and event types this SDK
+  # does not know are ignored, so a consumer keeps working when a newer node
+  # announces more.
+  def self.decode_lifecycle(data)
+    parsed =
+      begin
+        JSON.parse(data)
+      rescue JSON::ParserError
+        raise InvalidMessageError.new("event is not JSON", code: "invalid_json")
+      end
+
+    unless parsed.is_a?(Hash)
+      raise InvalidMessageError.new("event is not a JSON object", code: "not_an_object")
+    end
+
+    unless parsed["specversion"] == "1.0"
+      raise InvalidMessageError.new("unsupported specversion", code: "unsupported_version")
+    end
+
+    LIFECYCLE_REQUIRED_FIELDS.each do |field|
+      value = parsed[field]
+      lifecycle_invalid_field(field) unless value.is_a?(String) && !value.empty?
+    end
+
+    datacontenttype = lifecycle_optional_string(parsed, "datacontenttype")
+
+    body = parsed["data"]
+    lifecycle_invalid_field("data") unless body.nil? || body.is_a?(Hash)
+
+    revision = parsed["revision"]
+    lifecycle_invalid_field("revision") unless revision.nil? || lifecycle_revision?(revision)
+
+    actor = lifecycle_optional_string(parsed, "actor")
+    instance = lifecycle_optional_string(parsed, "instance")
+
+    sequence = parsed["sequence"]
+    lifecycle_invalid_field("sequence") unless sequence.nil? || lifecycle_decimal?(sequence)
+
+    LifecycleEvent.new(
+      specversion: "1.0",
+      id: parsed["id"],
+      source: parsed["source"],
+      type: parsed["type"],
+      subject: parsed["subject"],
+      time: parsed["time"],
+      datacontenttype: datacontenttype,
+      data: body,
+      revision: revision,
+      actor: actor,
+      instance: instance,
+      sequence: sequence,
+      replayid: lifecycle_optional_string(parsed, "replayid"),
+      traceparent: lifecycle_optional_string(parsed, "traceparent"),
+      tracestate: lifecycle_optional_string(parsed, "tracestate")
+    )
+  end
+
+  def self.lifecycle_optional_string(parsed, field)
+    value = parsed[field]
+    lifecycle_invalid_field(field) unless value.nil? || value.is_a?(String)
+    value
+  end
+  private_class_method :lifecycle_optional_string
+
+  def self.lifecycle_revision?(value)
+    value.is_a?(Integer) && value >= 1
+  end
+  private_class_method :lifecycle_revision?
+
+  def self.lifecycle_decimal?(value)
+    value.is_a?(String) && LIFECYCLE_DECIMAL.match?(value)
+  end
+  private_class_method :lifecycle_decimal?
+
+  def self.lifecycle_invalid_field(field)
+    raise InvalidMessageError.new("invalid or missing field: #{field}", code: "invalid_field", field: field)
+  end
+  private_class_method :lifecycle_invalid_field
+end

data/lib/ankusa/message.rb

@@ -47,17 +47,32 @@ module Ankusa
   end
   private_constant :IdempotencyKey
 
-  # One decoded v1 queue message. `body` holds the inline bytes (or nil for the
+  # The message versions `Ankusa.decode_message` understands, both ends
+  # inclusive. `v` is the wire format's major version: a `v: 2` message is a
+  # `v: 1` message plus additive fields, decoded exactly like it (the keys this
+  # decoder does not know are ignored) into the one `Message` type, with `v` as
+  # the wire said it. Raising `MAX_SUPPORTED_VERSION` is the whole change an
+  # SDK needs for a producer that starts writing the next additive version.
+  MIN_SUPPORTED_VERSION = 1
+  MAX_SUPPORTED_VERSION = 2
+
+  # One decoded queue message; `v` is the wire's. `body` holds the inline bytes (or nil for the
   # claim form, where the bytes are fetched with `Ankusa::ClaimCheckClient`);
   # `claim` holds the ref string in that case. `headers` is the forwarded
-  # provider request headers, `{}` when the message carried none.
+  # provider request headers, `{}` when the message carried none. `traceparent`
+  # and `tracestate` are the hook's W3C trace context, verbatim (nil when the
+  # message carries none): continue the trace from them. `instance` and `region`
+  # are the name of the Ankusa instance that published the message and the
+  # region it is configured with (nil when the message says null or predates
+  # the fields).
   #
   # `idempotency_key` is the one value a consumer should dedupe on, as
   # `Message#idempotency_key` (the field is nil only for a message from a node
   # that predates it); see `Ankusa.decode_message` for the decode rules.
   Message = Data.define(
     :v, :id, :source_id, :tenant_id, :received_at, :content_type, :size,
-    :body, :claim, :sha256, :dedupe_key, :replay_id, :idempotency_key, :headers
+    :body, :claim, :sha256, :dedupe_key, :replay_id, :idempotency_key, :headers, :verification,
+    :traceparent, :tracestate, :instance, :region
   ) do
     # `Data.define` made `idempotency_key` the reader of the decoded field; keep
     # that value reachable here and let the helper below take over the name.
@@ -80,14 +95,24 @@ module Ankusa
         dedupe_key: dedupe_key, id: id, replay_id: replay_id, include_replay: include_replay
       )
     end
+
+    # Whether the node verified this message's hook at ingest and nothing flags
+    # it (see `Verification#trusted?`). A message with no `verification` (a node
+    # older than the field) is untrusted.
+    def trusted?
+      verification&.trusted? == true
+    end
   end
 
   # The optional string-keyed fields that may be a string, null, or absent.
   # Checked in this order, so the first offending key is the one reported.
-  MESSAGE_STRING_FIELDS = %w[tenant_id content_type dedupe_key replay_id idempotency_key].freeze
+  MESSAGE_STRING_FIELDS = %w[
+    tenant_id content_type dedupe_key replay_id idempotency_key traceparent tracestate instance region
+  ].freeze
   private_constant :MESSAGE_STRING_FIELDS
 
-  # Decodes one v1 queue message (the JSON body a sink or broker delivers) into
+  # Decodes one queue message of any supported `v` (`MIN_SUPPORTED_VERSION` to
+  # `MAX_SUPPORTED_VERSION`; the JSON body a sink or broker delivers) into
   # a `Message`, applying every rule in "Consuming queue messages" of the SDK
   # README in order; the first failure wins.
   #
@@ -107,7 +132,7 @@ module Ankusa
     end
 
     version = parsed["v"]
-    unless version.is_a?(Integer) && version == 1
+    unless version.is_a?(Integer) && version.between?(MIN_SUPPORTED_VERSION, MAX_SUPPORTED_VERSION)
       raise InvalidMessageError.new("unsupported message version: #{version.inspect}", code: "unsupported_version")
     end
 
@@ -135,6 +160,8 @@ module Ankusa
     valid_sha256 = sha256.nil? || (sha256.is_a?(String) && SHA256_PATTERN.match?(sha256))
     invalid_field("sha256") unless valid_sha256
 
+    verification = decode_verification(parsed["verification"])
+
     body_base64 = parsed["body_base64"]
     claim = parsed["claim"]
 
@@ -172,7 +199,7 @@ module Ankusa
     end
 
     Message.new(
-      v: 1,
+      v: version,
       id: id,
       source_id: source_id,
       tenant_id: tenant_id,
@@ -185,10 +212,32 @@ module Ankusa
       dedupe_key: parsed["dedupe_key"],
       replay_id: parsed["replay_id"],
       idempotency_key: parsed["idempotency_key"],
-      headers: headers
+      headers: headers,
+      verification: verification,
+      traceparent: parsed["traceparent"],
+      tracestate: parsed["tracestate"],
+      instance: parsed["instance"],
+      region: parsed["region"]
     )
   end
 
+  # Absent or explicit `null` is `nil` (a node that predates the field).
+  # Anything else must be `{status: <non-empty string>, flagged: <boolean>}`;
+  # the status value itself is never validated, so unknown statuses pass
+  # through untouched.
+  def self.decode_verification(value)
+    return nil if value.nil?
+    invalid_field("verification") unless value.is_a?(Hash)
+
+    status = value["status"]
+    flagged = value["flagged"]
+    valid = status.is_a?(String) && !status.empty? && [true, false].include?(flagged)
+    invalid_field("verification") unless valid
+
+    Verification.new(status: status, flagged: flagged)
+  end
+  private_class_method :decode_verification
+
   def self.invalid_field(field)
     raise InvalidMessageError.new("invalid message field: #{field}", code: "invalid_field", field: field)
   end

data/lib/ankusa/routes.rb

@@ -37,18 +37,20 @@ module Ankusa
   # The listener rejected the request (400 or any other non-404 4xx).
   #
   # `code` is the body's `error` field (`invalid_route`, `duplicate_route`,
-  # `too_many_routes`, ...); `field`, `message`, `conflicting_id` and
-  # `max_routes` are carried through when the body supplies them.
+  # `too_many_routes`, ...); `field`, `message`, `conflicting_id`,
+  # `max_routes` and `scope` are carried through when the body supplies them.
+  # `scope` is the scope a 403 forbidden says the credential lacks.
   class RoutesRejectedError < RoutesError
-    attr_reader :status, :code, :field, :conflicting_id, :max_routes
+    attr_reader :status, :code, :field, :conflicting_id, :max_routes, :scope
 
-    def initialize(message, status:, code:, field: nil, conflicting_id: nil, max_routes: nil)
+    def initialize(message, status:, code:, field: nil, conflicting_id: nil, max_routes: nil, scope: nil)
       super(message)
       @status = status
       @code = code
       @field = field
       @conflicting_id = conflicting_id
       @max_routes = max_routes
+      @scope = scope
     end
   end
 
@@ -149,7 +151,8 @@ module Ankusa
           code: field(body, "error"),
           field: field(body, "field"),
           conflicting_id: field(body, "conflicting_id"),
-          max_routes: field(body, "max_routes")
+          max_routes: field(body, "max_routes"),
+          scope: field(body, "scope")
         )
       end
 

data/lib/ankusa/sdk/version.rb

@@ -2,6 +2,6 @@
 
 module Ankusa
   module SDK
-    VERSION = "0.5.0"
+    VERSION = "0.6.0"
   end
 end

data/lib/ankusa/sdk.rb

@@ -8,6 +8,7 @@ require_relative "webhook"
 require_relative "signature"
 require_relative "claim_check"
 require_relative "message"
+require_relative "lifecycle"
 require_relative "routes"
 require_relative "admin"
 require_relative "sources"

data/lib/ankusa/webhook.rb

@@ -1,6 +1,19 @@
 # frozen_string_literal: true
 
 module Ankusa
+  # How Ankusa verified the hook at ingest. `status` is `ok`, `failed` or
+  # `skipped`, but other values pass through untouched (forward-compatible).
+  # `flagged` is true when a failed check was accepted
+  # (`on_verify_failure: accept_flag`): treat the delivery as unverified.
+  Verification = Data.define(:status, :flagged) do
+    # Whether the node verified the hook and nothing flags it: true only for
+    # status "ok" with `flagged` false. A flagged hook, a "failed" or "skipped"
+    # one, and any other status are untrusted.
+    def trusted?
+      status == "ok" && flagged == false
+    end
+  end
+
   # The identity of one HTTP-sink delivery: the headers Ankusa's HTTP sink
   # attaches to every delivery.
   #
@@ -8,9 +21,15 @@ module Ankusa
   # nil when the delivery had no such header (a tenant only travels when the
   # source has one; `dedupe_key` only when the source declared a dedupe key;
   # `replay_id` only when the delivery is a replay; `idempotency_key` is
-  # missing only from a sender that predates the header).
+  # missing only from a sender that predates the header). `received_at` (when
+  # the edge accepted the hook, unix milliseconds, an Integer) and `body_sha256`
+  # (the lowercase hex SHA-256 of the body Ankusa sent) are advisory: nil when
+  # the header is absent, empty or malformed (not 1 to 15 decimal digits; not
+  # exactly 64 lowercase hex characters), never an error. `verification` is nil
+  # when `x-ankusa-verification` is absent or empty.
   HookHeaders = Data.define(
-    :id, :source, :tenant, :content_type, :dedupe_key, :replay_id, :idempotency_key
+    :id, :source, :tenant, :content_type, :dedupe_key, :replay_id, :idempotency_key,
+    :received_at, :body_sha256, :verification
   ) do
     # `Data.define` made `idempotency_key` the reader of the parsed header; keep
     # that value reachable here and let the helper below take over the name.
@@ -33,6 +52,13 @@ module Ankusa
         dedupe_key: dedupe_key, id: id, replay_id: replay_id, include_replay: include_replay
       )
     end
+
+    # Whether the node verified this delivery at ingest and nothing flags it
+    # (see `Verification#trusted?`). A delivery with no `x-ankusa-verification`
+    # header (a node older than the field) is untrusted.
+    def trusted?
+      verification&.trusted? == true
+    end
   end
 
   # Raised by `Ankusa.parse_headers` when `x-ankusa-id` is absent or empty.
@@ -62,7 +88,10 @@ module Ankusa
       content_type: lowered["content-type"],
       dedupe_key: presence(lowered["x-ankusa-dedupe-key"]),
       replay_id: presence(lowered["x-ankusa-replay-id"]),
-      idempotency_key: presence(lowered["x-ankusa-idempotency-key"])
+      idempotency_key: presence(lowered["x-ankusa-idempotency-key"]),
+      received_at: parse_received_at(lowered["x-ankusa-received-at"]),
+      body_sha256: parse_body_sha256(lowered["x-ankusa-body-sha256"]),
+      verification: parse_verification(lowered)
     )
   end
 
@@ -72,4 +101,65 @@ module Ankusa
     (value.nil? || value.empty?) ? nil : value
   end
   private_class_method :presence
+
+  # An Integer for 1 to 15 decimal digits and nothing else, else nil.
+  def self.parse_received_at(value)
+    value.to_i if value&.match?(/\A[0-9]{1,15}\z/)
+  end
+  private_class_method :parse_received_at
+
+  # The value when it is exactly 64 lowercase hex characters, else nil.
+  def self.parse_body_sha256(value)
+    value if value&.match?(/\A[0-9a-f]{64}\z/)
+  end
+  private_class_method :parse_body_sha256
+
+  # `nil` when `x-ankusa-verification` is absent or empty; otherwise the
+  # header's value as `status`, and `flagged` true exactly when
+  # `x-ankusa-verification-flagged` is the literal string "true".
+  def self.parse_verification(lowered)
+    status = presence(lowered["x-ankusa-verification"])
+    return nil if status.nil?
+
+    Verification.new(status: status, flagged: lowered["x-ankusa-verification-flagged"] == "true")
+  end
+  private_class_method :parse_verification
+
+  # An accepted delivery: its identity (`HookHeaders`), and whether its
+  # signature verified (`false` only for an unsigned delivery `allow_unsigned`
+  # let through).
+  ReceivedDelivery = Data.define(:headers, :verified)
+
+  # Judges one HTTP-sink delivery: is it signed, and what is its identity.
+  #
+  # Ankusa's HTTP sink signs every delivery unless it is configured
+  # `allow_unsigned: true`, so a receiver is closed by default: without the
+  # sink's `secrets` (or an explicit `allow_unsigned: true`) it refuses every
+  # delivery, because any host that can reach the receiver's URL could
+  # otherwise inject hooks. With `secrets` the delivery MUST verify
+  # (`Ankusa.verify_signature`); `allow_unsigned` does not weaken that.
+  #
+  # `body` must be the raw bytes received. Raises `InvalidSignatureError`
+  # (answer 401) when there is no valid signature -- `invalid_secret` when no
+  # secret is configured and `allow_unsigned` is not set -- and
+  # `MissingHookIdError` (400) when `x-ankusa-id` is absent. The signature is
+  # judged first.
+  def self.receive_delivery(headers, body, secrets: [], allow_unsigned: false, tolerance_seconds: 300, now: nil)
+    configured = Array(secrets)
+    verified =
+      if !configured.empty?
+        verify_signature(headers, body, configured, tolerance_seconds: tolerance_seconds, now: now)
+        true
+      elsif allow_unsigned
+        false
+      else
+        raise InvalidSignatureError.new(
+          "no secret configured: deliveries are signed, so the receiver needs the sink's secret " \
+          "(or allow_unsigned: true)",
+          code: "invalid_secret"
+        )
+      end
+
+    ReceivedDelivery.new(headers: parse_headers(headers), verified: verified)
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ankusa-sdk
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - James Carr
@@ -24,6 +24,7 @@ files:
 - lib/ankusa/claim_check.rb
 - lib/ankusa/connection.rb
 - lib/ankusa/error.rb
+- lib/ankusa/lifecycle.rb
 - lib/ankusa/message.rb
 - lib/ankusa/routes.rb
 - lib/ankusa/sdk.rb