manza 1.0.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 435c347d3d7f45503a976c5be7c7b185f4c86968d6557e93ec736557e2ca3fec
-  data.tar.gz: 5f13cc5d2633f528ffbe43521e6e64ae2070415e6b47d34afbe51a583ca57cac
+  metadata.gz: 460a7caba9195a45a73b84bbadbd1fdc3476ad4fdf8244e0d554fd451b493b28
+  data.tar.gz: ecabf7b8a26eeb01ff6405821305ad54e9192674f77982df77f3b53437aefeaa
 SHA512:
-  metadata.gz: 4b5efbf767a72be8822fd86ef8596146410910730a6a575f711aea9da6fb77bf7184ebcd283b4c0671fa3b155ee8d770bb237774bc11e18951c2c547008d91c2
-  data.tar.gz: ed1f8c2a4233014da1447bdb6ca30ca1e6139c49b8ac325a7ce77c08f162ed92e808f78c77ac7738e3e77f75cd86ea6f1041f5ddb3cf7a9b83a84277c89c58fd
+  metadata.gz: b17cb8c504555b47d2c26322880a22c9187396617a1fcfdbda5a4d176e6e4671e5ca4164d528454ba69008ec11841658a42c262a9619219a07b9605dba0e23fc
+  data.tar.gz: c69b5d6f786843c19f815a8eb1b201653b833d90fe4128796f30b7eee81f46df59096df33d0b9c6d04e08e7f00d595b3d837c7bb3677d856ab3e2243ff45509d

data/CHANGELOG.md

@@ -7,6 +7,99 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+### Added
+
+- `manza.payments` (`Manza::Resources::Payments`): `create`, `get`,
+  `authorize` and `decline` on the API's canonical paths, `POST
+  /api/payments`, `GET /api/payments/:id`, `POST /api/payments/:id/authorize`
+  and `POST /api/payments/:id/decline`. The API renamed transfer drafts to
+  payments; request and response bodies are unchanged, and so is the
+  `Manza::TransferAuthorization` signature input.
+
+### Deprecated
+
+- `manza.transfer_drafts` and `Manza::Resources::TransferDrafts`. Both keep
+  working for all of 1.x: the accessor returns `manza.payments` and the
+  constant names the same class, so the old name now calls `/api/payments`
+  too. They warn only when Ruby's deprecation warnings are on
+  (`Warning[:deprecated] = true` or `ruby -W:deprecated`). The server keeps
+  `/api/transfer_drafts` as a permanent alias.
+
+### Changed (cassettes)
+
+The nine payment cassettes moved from `transfer_drafts/` to `payments/`
+and match a new URI. An SDK that replays `cassettes-v1.3.0` sends:
+
+| Cassette | Request |
+|---|---|
+| `payments/create` | `POST https://ma.manza.dev/api/payments` |
+| `payments/create_duplicate` | `POST https://ma.manza.dev/api/payments` |
+| `payments/get` | `GET https://ma.manza.dev/api/payments/fixture-transfer-draft-id` |
+| `payments/get_refused` | `GET https://ma.manza.dev/api/payments/fixture-refused-draft-id` |
+| `payments/authorize` | `POST https://ma.manza.dev/api/payments/fixture-authorizable-draft-id/authorize` |
+| `payments/authorize_bad_signature` | `POST https://ma.manza.dev/api/payments/fixture-bad-signature-draft-id/authorize` |
+| `payments/authorize_same_key` | `POST https://ma.manza.dev/api/payments/fixture-authorizable-draft-id/authorize` |
+| `payments/authorize_new_payee` | `POST https://ma.manza.dev/api/payments/fixture-new-payee-draft-id/authorize` |
+| `payments/decline` | `POST https://ma.manza.dev/api/payments/fixture-declinable-draft-id/decline` |
+
+Each was `/api/transfer_drafts…` with the same rest of the path, under
+`transfer_drafts/<name>`. The fixture placeholders keep their names
+(`fixture-transfer-draft-id`, …). Every other cassette was re-recorded with
+the same method, URI and request body as in `cassettes-v1.2.0`, and every
+response keeps its status and the same JSON keys.
+
+## [1.2.0]
+
+1.1.0 was never published: its changes (the webhook verifier and the
+example) ship here.
+
+### Added
+
+- `manza.transfer_authorizer.get` (`GET /api/transfer_authorizer`): the
+  enrolled authorizer's `status`, `suspension_reason`, limits,
+  `daily_authorized_total`, `secret_expires_at` and `webhook_endpoint_id`.
+  Raises `Manza::NotFoundError` when none is enrolled.
+- Documented the new pass-through fields: a draft's `authorization` carries
+  `refusal_reason` (status `refused` when it went to the approvers at
+  create time), bank accounts carry `trusted`, and the challenge webhook's
+  `payment.payee_trusted` says whether the payee was trusted already.
+- `examples/transfer_authorizer/`: `preflight.rb` checks every setup step
+  and prints the fix; `create_transfer.rb` prints the authorization status
+  and refusal reason in words; the authorizer logs a new payee, declines it
+  with `ALLOW_NEW_PAYEES=false`, and retries 409 `authorization_busy`.
+- README: setup step 6 is "Approve transfers to new payees" (or trust each
+  payee), step 7 the preflight.
+- Cassettes re-recorded against `ma.manza.dev`, with new ones for
+  `transfer_authorizer/get`, a refused draft, a new-payee authorize and the
+  payee trusted afterwards.
+- `Manza::Webhook` verifies incoming webhook deliveries: `verify?` (boolean),
+  `construct_event` (returns the parsed event, raises `Manza::ArgumentError`)
+  and `sign`. Reads `X-Manza-*` headers in any case, the Rack `HTTP_X_MANZA_*`
+  form and the legacy `X-Zazu-*` names; checks the timestamp within 5 minutes
+  (`tolerance: nil` skips it, for local replay only). The spec carries a fixed test vector every SDK
+  reuses.
+- `examples/transfer_authorizer/`: a runnable two-key transfer authorizer
+  (Rack app plus a creator script and a JSON ledger). Not shipped in the gem.
+- README: "Setup, step by step" for machine-authorized transfers.
+
+### Changed (cassettes)
+
+Two existing cassettes match a different request body. An SDK that replays
+`cassettes-v1.2.0` sends these exact bodies:
+
+- `transfer_drafts/create`: `amount` `"10.00"`, the staging per-transfer
+  limit (the old `"150.00"` exceeds it and was refused), and a new `internal_notes`
+  `"[zazu-ruby-fixture] create spec - do not approve"`. The response's
+  `authorization` is a `pending` challenge.
+- `beneficiaries/create`: `company_name` `"Manza Fixture Beneficiary spec"`
+  (staging now accepts only unaccented letters, digits and spaces).
+
+Responses are scrubbed further: account `balance` and transaction
+`account_balance_after` read the synthetic decimal `"1000.0"`, and the
+authorizer's `daily_authorized_total` reads `"0.0"`, in every cassette.
+
+## [1.0.0]
+
 The SDK is renamed from Zazu to Manza and released as `manza` 1.0.0.
 The API surface is otherwise unchanged.
 
@@ -41,6 +134,16 @@ one-time deprecation warning per variable.
 - Fixture and staging env vars for recording are `MANZA_FIXTURE_*` and
   `MANZA_STAGING_*`, with no fallback. Rename them in your `.env`.
 
+## [0.3.1]
+
+Final release under the old `zazu-ruby` name, published from the
+`zazu-legacy` branch.
+
+### Deprecated
+
+- `require "zazu"` prints a deprecation warning, and the gem shows a
+  post-install message pointing to `gem "manza"`.
+
 ## [0.3.0]
 
 ### Added

data/README.md

@@ -82,20 +82,23 @@ manza.checkout_sessions.get("cs_...")
 manza.beneficiaries.list
 manza.beneficiaries.create(beneficiary_type: "business", company_name: "Acme Supplies", email: "ap@acme.com")
 manza.beneficiaries.list_external_accounts("01a0...")
-manza.beneficiaries.get_external_account("01a0...", "01a1...")
+manza.beneficiaries.get_external_account("01a0...", "01a1...")  # "trusted": true once a trusted payee
 manza.beneficiaries.create_external_account("01a0...", account_number: "007780...", name: "Main account")
 
 manza.payee_trust_requests.create(external_account_ids: ["01a1..."])
 manza.payee_trust_requests.get("01a2...")
 
-manza.transfer_drafts.create(
+manza.payments.create(
   account_id: "019dde7d-...",
   beneficiary_id: "01a0...",
   amount: "2500.00",
   client_reference: "po_1042" # unique per entity; a duplicate raises Manza::ConflictError
 )
-manza.transfer_drafts.get("01a3...")
-manza.transfer_drafts.decline("01a3...", authorization_id: "01a4...", reason: "Not ours")
+manza.payments.get("01a3...")  # authorization: status, refusal_reason
+manza.payments.decline("01a3...", authorization_id: "01a4...", reason: "Not ours")
+# manza.transfer_drafts is a deprecated alias of manza.payments (same methods, /api/payments)
+
+manza.transfer_authorizer.get  # status, suspension_reason, limits, daily_authorized_total; NotFoundError: none enrolled
 
 manza.webhook_endpoints.list
 manza.webhook_endpoints.create(
@@ -110,7 +113,47 @@ manza.webhook_endpoints.disable("01a0...")
 
 ## Machine-authorized transfers
 
-A draft inside your entity's authorization envelope (trusted payee, within limits) is sent to your enrolled authorizer endpoint as a `payment.authorization_requested` webhook carrying an `authorization.id` and a one-time `nonce`. Sign the draft from **your own record** of it with the endpoint's signing secret, and authorize it with a **different API key** from the one that created it (the creating key gets 403 `same_key_forbidden`):
+A draft inside your entity's authorization envelope (trusted payee, or a new one when you allow it, within limits) is sent to your enrolled authorizer endpoint as a `payment.authorization_requested` webhook carrying an `authorization.id` and a one-time `nonce`. Your system checks it against its own ledger, signs it and authorizes it with a **different API key** from the one that created it. [`examples/transfer_authorizer/`](examples/transfer_authorizer/) runs the whole flow.
+
+### Setup, step by step
+
+1. **Feature flags.** Ask support to enable API transfers and transfer authorization (`release_api_webhook_authorization`) on your workspace.
+2. **Two API keys.** Key A creates drafts (`transfers:write`; `beneficiaries:request_trust` for step 6; `entity:read`, `accounts:read`, `webhook_endpoints:read` and `beneficiaries:read` for the preflight in step 7). Key B answers the challenges (`transfers:authorize`). The creating key is always refused with 403 `same_key_forbidden`, so keep key B and the signing secret on the system that holds your ledger. Bind key B to an IP allowlist: authorizing from a key without one is refused with 403 `unrestricted_api_key`. Bind key A to one too if you allow new payees (step 6): a draft to a new payee from a key without an allowlist goes to your approvers (`unrestricted_api_key`).
+3. **A stable public URL.** Your authorizer needs an HTTPS URL that never changes: an enrolled endpoint's URL is locked. Use a reserved ngrok domain (`ngrok http --url=your-name.ngrok.app 4599`) or a named Cloudflare tunnel (see [The authorizer tunnel](#the-authorizer-tunnel)). Never a free ngrok URL: it changes on every restart.
+4. **Create the webhook endpoint** at that URL:
+
+   ```ruby
+   manza.webhook_endpoints.create(url: "https://your-name.ngrok.app/", events: ["transfer.executed"])
+   ```
+
+5. **Enrol it in the app**: Settings → Developer → Transfer approval. Pick the endpoint, the currency and both limits, confirm with your two-factor code, and copy the signing secret: it is shown once.
+6. **Allow new payees, or trust each payee.** Turn on *Approve transfers to new payees* at enrolment (or later, same page, with your two-factor code) and set the *Limit per transfer to a new payee*. Your authorizer may then approve a transfer to bank details your workspace never trusted, up to that limit, and its signature trusts them: the webhook's `payment.payee_trusted` is `false` for such a transfer. Bank details whose trust was revoked, or that were edited after trusting, still go to your approvers. Without the option, an approver marks the beneficiary's bank account as trusted from the Beneficiaries list, or you ask them to:
+
+   ```ruby
+   manza.payee_trust_requests.create(external_account_ids: ["01a1..."])
+   ```
+
+   `trusted` on `manza.beneficiaries.get_external_account` says which it is. The API does not show whether the option is on.
+7. **Run the preflight, then the example** (from `examples/transfer_authorizer/`, after `bundle install` and filling in `.env`): `bundle exec ruby preflight.rb` checks what the API shows of steps 1–6 and prints a fix for each that fails. What it cannot see, check by hand: that key B is bound to an IP allowlist, and, for a payee not trusted yet, that *Approve transfers to new payees* is on and key A is bound to an IP allowlist too (it warns, it does not fail). Then `bundle exec rackup -p 4599` in one terminal, `bundle exec ruby create_transfer.rb` in another.
+8. **Troubleshooting**: a draft that goes to your approvers instead has an `authorization` with status `refused` and a `refusal_reason` (`create_transfer.rb` prints it in words); `manza.transfer_authorizer.get` shows a suspension and its `suspension_reason`. An authorize answered 409 `authorization_busy` (a bank-detail edit, trust or trust revocation on the same payee was in flight) is safe to retry. The reasons, and an API error's `type`, are in the [transfer authorization docs](https://ma.manza.finance/docs/api/transfer-authorization).
+
+### Verifying the webhook
+
+Pass the **raw request body**, never re-serialized JSON. `construct_event` reads `X-Manza-Signature` and `X-Manza-Timestamp` (any case, the Rack `HTTP_X_MANZA_*` form, or the legacy `X-Zazu-*` names), checks the signature in constant time and the timestamp within 5 minutes, and returns the parsed event (a Hash). It raises `Manza::ArgumentError` otherwise:
+
+```ruby
+begin
+  event = Manza::Webhook.construct_event(payload: request.body.read, headers: request.env, secret: signing_secret)
+rescue Manza::ArgumentError => e
+  return [401, {}, [e.message]]
+end
+```
+
+`Manza::Webhook.verify?(payload:, signature:, timestamp:, secret:)` returns a boolean instead. Both accept `tolerance: nil` to skip the timestamp check. Use it only to replay a captured delivery in a local tool or test, never on a live endpoint: without the check, anyone holding a captured delivery can replay it.
+
+### Signing the challenge
+
+Sign the draft from **your own record** of it with the endpoint's signing secret:
 
 ```ruby
 input = Manza::TransferAuthorization.signature_input(
@@ -125,7 +168,7 @@ input = Manza::TransferAuthorization.signature_input(
 signature = Manza::TransferAuthorization.sign(secret: signing_secret, signature_input: input)
 
 authorizer = Manza.new(api_key: ENV["MANZA_AUTHORIZER_API_KEY"])
-authorizer.transfer_drafts.authorize(draft["id"], authorization_id: webhook["data"]["authorization"]["id"], signature: signature)
+authorizer.payments.authorize(draft["id"], authorization_id: webhook["data"]["authorization"]["id"], signature: signature)
 ```
 
 A wrong signature raises `Manza::ValidationError` (`type` `invalid_signature`). Five on one challenge send the draft to your in-app approvers; five in a row suspend the authorizer.
@@ -198,13 +241,14 @@ The spec suite is VCR-backed — cassettes live in `spec/fixtures/cassettes/` an
 To re-record cassettes against staging:
 
 ```bash
-cp .env.example .env
+bin/rename-env-vars    # upgrading an existing 0.x .env: ZAZU_* → MANZA_* (backup in .env.bak)
+cp .env.example .env   # fresh setup only — overwrites an existing .env
 # fill in the keys, MANZA_FIXTURE_ACCOUNT_ID and MANZA_FIXTURE_BENEFICIARY_ID
 cloudflared tunnel --config ~/.cloudflared/zazu-sdk-authorizer.yml run zazu-sdk-authorizer   # separate terminal
 bundle exec rake fixtures:record
 ```
 
-Recording executes a real 10.00 MAD transfer on staging (the authorize cassette). The one-time staging setup (keys, authorizer enrolment, trusted payee) is listed at the top of `lib/tasks/fixtures.rake`.
+Recording executes two real 10.00 MAD transfers on staging: the authorize cassette pays the trusted payee, and authorize_new_payee pays a freshly seeded bank account (and trusts it). The one-time staging setup (keys, authorizer enrolment, trusted payee, the new-payee option) is listed at the top of `lib/tasks/fixtures.rake`; AGENTS.md → Staging fixture state keeps it in place.
 
 ### The authorizer tunnel
 
@@ -240,12 +284,26 @@ Check it end to end: with the tunnel running and nothing on port 4599, `curl -X
 
 Cassettes are scrubbed before write — bearer tokens and request IDs are rewritten to placeholders. Even if a real key is in `.env`, the committed cassette never contains it.
 
+## The SDK family
+
+| SDK | Repository | Install |
+|---|---|---|
+| Ruby (reference implementation, records the cassettes) | [getmanza/manza-ruby](https://github.com/getmanza/manza-ruby) (this repo) | `gem "manza"` |
+| TypeScript / JavaScript | [getmanza/manza-ts](https://github.com/getmanza/manza-ts) | `npm install @getmanza/sdk` |
+| Python | [getmanza/manza-python](https://github.com/getmanza/manza-python) | `pip install manza` |
+| Go | [getmanza/manza-go](https://github.com/getmanza/manza-go) | `go get github.com/getmanza/manza-go` |
+| PHP | [getmanza/manza-php](https://github.com/getmanza/manza-php) | `composer require manza/manza-php` |
+| Rust | [getmanza/manza-rust](https://github.com/getmanza/manza-rust) | `cargo add manza` |
+| Crystal | [getmanza/manza-crystal](https://github.com/getmanza/manza-crystal) | shard `manza` (`github: getmanza/manza-crystal`) |
+| Elixir | [getmanza/manza-elixir](https://github.com/getmanza/manza-elixir) | `{:manza, "~> 1.0"}` |
+| CLI | [getmanza/cli](https://github.com/getmanza/cli) | `npm install -g @getzazu/cli` or `brew install getmanza/tap/zazu` |
+
 ## Cassettes for other-language SDKs
 
 Each release of `manza-ruby` publishes the cassette directory as a tarball release asset:
 
 ```
-https://github.com/getmanza/manza-ruby/releases/download/v0.1.0/cassettes-v0.1.0.tar.gz
+https://github.com/getmanza/manza-ruby/releases/download/v1.0.0/cassettes-v1.0.0.tar.gz
 ```
 
 `manza-go`, `manza-python`, etc. pin a specific tag in their cassette fetch script and download the tarball during CI. This guarantees every SDK is tested against the same recorded API interactions, surfacing cross-SDK inconsistencies immediately.

data/lib/manza/client.rb

@@ -87,12 +87,24 @@ module Manza
       @payment_links ||= Resources::PaymentLinks.new(self)
     end
 
+    def payments
+      @payments ||= Resources::Payments.new(self)
+    end
+
     def payee_trust_requests
       @payee_trust_requests ||= Resources::PayeeTrustRequests.new(self)
     end
 
+    def transfer_authorizer
+      @transfer_authorizer ||= Resources::TransferAuthorizer.new(self)
+    end
+
+    # @deprecated Use {#payments}. Kept for all of 1.x: returns the same
+    #   resource, which calls `/api/payments`. Warns when Ruby's deprecation
+    #   warnings are on (`Warning[:deprecated] = true` or `-W:deprecated`).
     def transfer_drafts
-      @transfer_drafts ||= Resources::TransferDrafts.new(self)
+      warn("[manza] transfer_drafts is deprecated; use payments instead.", category: :deprecated, uplevel: 1)
+      payments
     end
 
     def webhook_endpoints

data/lib/manza/resources/beneficiaries.rb

@@ -4,7 +4,10 @@ module Manza
   module Resources
     # Saved transfer recipients. Each beneficiary embeds its bank
     # accounts; the one flagged `default` is used when a transfer names
-    # only the beneficiary_id. There is no update or delete via the API.
+    # only the beneficiary_id. Each bank account carries `trusted`: whether
+    # its bank details are a trusted payee, which machine-authorized
+    # transfers need (or "Approve transfers to new payees" on for details
+    # never trusted). There is no update or delete via the API.
     class Beneficiaries < Base
       # GET /api/beneficiaries
       def list(limit: MAX_PER_PAGE, cursor: nil)

data/lib/manza/resources/payments.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Manza
+  module Resources
+    # API-initiated transfers, called payments (formerly transfer drafts;
+    # `/api/transfer_drafts` stays a permanent server-side alias). Creating
+    # a draft never executes a transfer by itself. A draft inside the
+    # entity's machine-
+    # authorization envelope (trusted payee, within limits) is sent to
+    # the enrolled transfer authorizer as a `payment.authorization_requested`
+    # webhook; answer it with {#authorize} or {#decline}, using an API
+    # key other than the one that created the draft. Every other draft
+    # goes to the in-app approval flow, where a manager or legal
+    # representative approves it. Poll {#get} (status: requested →
+    # processing → completed / failed) or subscribe to the
+    # `transfer.executed` webhook to follow execution.
+    #
+    # A draft's `authorization` says which way it went: `pending` (a
+    # challenge was sent), `authorized`, `declined` (the draft is deleted),
+    # or one of two outcomes that send the draft to the in-app approvers,
+    # each with a `refusal_reason`:
+    #
+    # - `refused`: it did not qualify, at create time (no webhook is sent)
+    #   or again when the challenge was answered: `untrusted_payee`,
+    #   `unrestricted_api_key`, `over_new_payee_limit`,
+    #   `over_transfer_limit`, `over_daily_limit`, `currency_mismatch`,
+    #   `suspended` or `secret_expired`.
+    # - `expired` / `superseded` / `failed`: a challenge was sent and closed
+    #   without an authorize: `expired` (no answer within the hour),
+    #   `stale` (the draft, its payee's bank details or the endpoint changed
+    #   while it was open) or `signature_failed` (five invalid signatures).
+    #   One exception: the in-app approval that finalizes the draft while
+    #   its challenge is open supersedes it (`stale`), and the draft
+    #   executes or is scheduled; the draft's own `status` shows which.
+    #
+    # `authorization` is nil when no authorizer was enrolled.
+    #
+    # With "Approve transfers to new payees" on (enrolment, in the app),
+    # a draft to bank details the entity never trusted is challenged too,
+    # up to the new-payee limit, when the creating key has an IP
+    # allowlist; authorizing it also trusts the payee.
+    class Payments < Base
+      # POST /api/payments
+      #
+      # Required: account_id, amount, and exactly one of beneficiary_id
+      # (external transfer) or destination_account_id (own-account move).
+      # Optional: external_account_id, currency_code, payment_reference,
+      # internal_notes, client_reference (unique per entity, at most 128
+      # characters; a duplicate raises {Manza::ConflictError} whose
+      # `payment_id` names the existing draft).
+      def create(**attributes)
+        http_post("api/payments", body: attributes)
+      end
+
+      # GET /api/payments/:id
+      def get(id)
+        http_get(encode_path("api/payments", id))
+      end
+
+      # POST /api/payments/:id/authorize
+      #
+      # Executes the draft. `authorization_id` comes from the
+      # `payment.authorization_requested` webhook; build `signature` with
+      # {Manza::TransferAuthorization}. Requires the `transfers:authorize`
+      # scope on a key other than the draft's creator (otherwise 403
+      # `same_key_forbidden`), bound to an IP allowlist (otherwise 403
+      # `unrestricted_api_key`). A 409 {Manza::ConflictError} with `type`
+      # `authorization_busy` means a bank-detail edit, trust or trust
+      # revocation on the payee was in flight: retry. A blank signature
+      # raises {Manza::ArgumentError} and is never sent: the API would count
+      # it as a failed attempt. Five invalid signatures fail the challenge.
+      def authorize(id, authorization_id:, signature:)
+        raise Manza::ArgumentError, "signature cannot be blank" if signature.to_s.strip.empty?
+
+        http_post(
+          encode_path("api/payments", id, "authorize"),
+          body: { authorization_id: authorization_id, signature: signature }
+        )
+      end
+
+      # POST /api/payments/:id/decline
+      #
+      # Declines the challenge and deletes the draft. Returns the
+      # authorization (`status: "declined"`, `declined_at`, and a nil
+      # `refusal_reason`).
+      def decline(id, authorization_id:, reason: nil)
+        http_post(
+          encode_path("api/payments", id, "decline"),
+          body: { authorization_id: authorization_id, reason: reason }.compact
+        )
+      end
+    end
+  end
+end

data/lib/manza/resources/transfer_authorizer.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Manza
+  module Resources
+    # The entity's enrolled transfer authorizer, read-only. Enrolment,
+    # limits, the "Approve transfers to new payees" option and resume stay
+    # in the app behind a second factor. A singular resource: no list, no id.
+    #
+    #   manza.transfer_authorizer.get.body["status"]  # => "active"
+    class TransferAuthorizer < Base
+      # GET /api/transfer_authorizer
+      #
+      # Any key with `transfers:read`, `transfers:write` or
+      # `transfers:authorize`. Returns `status` (`active` / `suspended`),
+      # `suspension_reason` (`member`, `signature_failures`,
+      # `secret_expired`, `endpoint_disabled`; nil when active),
+      # `currency_code`, `per_transfer_limit`, `daily_limit`,
+      # `daily_authorized_total` (the last 24 hours), `secret_expires_at`,
+      # `webhook_endpoint_id` and `enrolled_at`. It does not show whether
+      # new payees are approved. Raises {Manza::NotFoundError} when no
+      # authorizer is enrolled.
+      def get
+        http_get("api/transfer_authorizer")
+      end
+    end
+  end
+end

data/lib/manza/resources/transfer_drafts.rb

@@ -2,61 +2,9 @@
 
 module Manza
   module Resources
-    # API-initiated transfers. Creating a draft never executes a
-    # transfer by itself. A draft inside the entity's machine-
-    # authorization envelope (trusted payee, within limits) is sent to
-    # the enrolled transfer authorizer as a `payment.authorization_requested`
-    # webhook; answer it with {#authorize} or {#decline}, using an API
-    # key other than the one that created the draft. Every other draft
-    # goes to the in-app approval flow, where a manager or legal
-    # representative approves it. Poll {#get} (status: requested →
-    # processing → completed / failed) or subscribe to the
-    # `transfer.executed` webhook to follow execution.
-    class TransferDrafts < Base
-      # POST /api/transfer_drafts
-      #
-      # Required: account_id, amount, and exactly one of beneficiary_id
-      # (external transfer) or destination_account_id (own-account move).
-      # Optional: external_account_id, currency_code, payment_reference,
-      # internal_notes, client_reference (unique per entity, at most 128
-      # characters; a duplicate raises {Manza::ConflictError} whose
-      # `payment_id` names the existing draft).
-      def create(**attributes)
-        http_post("api/transfer_drafts", body: attributes)
-      end
-
-      # GET /api/transfer_drafts/:id
-      def get(id)
-        http_get(encode_path("api/transfer_drafts", id))
-      end
-
-      # POST /api/transfer_drafts/:id/authorize
-      #
-      # Executes the draft. `authorization_id` comes from the
-      # `payment.authorization_requested` webhook; build `signature` with
-      # {Manza::TransferAuthorization}. Requires the `transfers:authorize`
-      # scope on a key other than the draft's creator (otherwise 403
-      # `same_key_forbidden`). A blank signature is refused locally: the
-      # API counts it as a failed attempt, and five fail the challenge.
-      def authorize(id, authorization_id:, signature:)
-        raise Manza::ArgumentError, "signature cannot be blank" if signature.to_s.strip.empty?
-
-        http_post(
-          encode_path("api/transfer_drafts", id, "authorize"),
-          body: { authorization_id: authorization_id, signature: signature }
-        )
-      end
-
-      # POST /api/transfer_drafts/:id/decline
-      #
-      # Declines the challenge and deletes the draft. Returns the
-      # authorization (`status: "declined"`).
-      def decline(id, authorization_id:, reason: nil)
-        http_post(
-          encode_path("api/transfer_drafts", id, "decline"),
-          body: { authorization_id: authorization_id, reason: reason }.compact
-        )
-      end
-    end
+    # @deprecated Use {Payments} (`manza.payments`). Kept for all of 1.x;
+    #   it is the same class and calls `/api/payments`.
+    TransferDrafts = Payments
+    deprecate_constant :TransferDrafts
   end
 end

data/lib/manza/transfer_authorization.rb

@@ -11,7 +11,7 @@ module Manza
   # from your *own* record of the transfer (not the webhook's
   # `signature_input`, which is there only to compare against), sign
   # it with the authorizer endpoint's signing secret, and pass the
-  # result to {Resources::TransferDrafts#authorize}:
+  # result to {Resources::Payments#authorize}:
   #
   #   input = Manza::TransferAuthorization.signature_input(
   #     payment_id: draft["id"], nonce: nonce, amount: draft["amount"],
@@ -20,7 +20,7 @@ module Manza
   #     client_reference: draft["client_reference"]
   #   )
   #   signature = Manza::TransferAuthorization.sign(secret: signing_secret, signature_input: input)
-  #   manza.transfer_drafts.authorize(draft["id"], authorization_id: authorization_id, signature: signature)
+  #   manza.payments.authorize(draft["id"], authorization_id: authorization_id, signature: signature)
   module TransferAuthorization
     SIGNATURE_VERSION = "manza.transfer-authorization.v1"
 

data/lib/manza/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Manza
-  VERSION = "1.0.0"
+  VERSION = "1.3.0"
 end

data/lib/manza/webhook.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require "json"
+require "openssl"
+
+module Manza
+  # Verifies incoming webhook deliveries. Pure functions — no HTTP.
+  #
+  # Every delivery carries `X-Manza-Signature` (hex HMAC-SHA256 of
+  # "<timestamp>.<raw body>" under the endpoint's signing secret) and
+  # `X-Manza-Timestamp` (Unix seconds, fresh on every attempt). The
+  # legacy `X-Zazu-*` names carry the same values.
+  #
+  # Pass the **raw request body**, never re-serialized JSON:
+  #
+  #   event = Manza::Webhook.construct_event(
+  #     payload: request.body.read, headers: request.env, secret: signing_secret
+  #   )
+  #   event["event"] # => "payment.authorization_requested"
+  module Webhook
+    DEFAULT_TOLERANCE = 300 # seconds
+
+    module_function
+
+    # Hex HMAC-SHA256 of "<timestamp>.<payload>". For tests and local tools.
+    def sign(payload:, timestamp:, secret:)
+      OpenSSL::HMAC.hexdigest("SHA256", secret, "#{timestamp}.#{payload}")
+    end
+
+    # true when the signature matches (constant time) and the timestamp is
+    # within `tolerance` seconds of `now`. `tolerance: nil` skips the
+    # timestamp check (for replaying a captured delivery). Never raises on
+    # bad input; returns false.
+    def verify?(payload:, signature:, timestamp:, secret:, tolerance: DEFAULT_TOLERANCE, now: Time.now)
+      signature_matches?(payload, signature, timestamp, secret) && timestamp_fresh?(timestamp, tolerance, now)
+    end
+
+    # Reads X-Manza-Signature / X-Manza-Timestamp from any Hash-like
+    # headers (case-insensitive, X-Zazu-* fallback, Rack HTTP_X_MANZA_*
+    # form too), verifies them, and returns the parsed JSON Hash. Raises
+    # Manza::ArgumentError when a header is missing, the signature does
+    # not match, the timestamp is outside tolerance, or the body is not
+    # a JSON object.
+    def construct_event(payload:, headers:, secret:, tolerance: DEFAULT_TOLERANCE, now: Time.now)
+      normalized = normalize_headers(headers)
+      signature = header(normalized, "signature")
+      timestamp = header(normalized, "timestamp")
+
+      raise Manza::ArgumentError, "invalid webhook signature" unless signature_matches?(payload, signature, timestamp, secret)
+      raise Manza::ArgumentError, "webhook timestamp outside tolerance" unless timestamp_fresh?(timestamp, tolerance, now)
+
+      event =
+        begin
+          JSON.parse(payload)
+        rescue JSON::ParserError
+          raise Manza::ArgumentError, "webhook payload is not JSON"
+        end
+      raise Manza::ArgumentError, "webhook payload is not a JSON object" unless event.is_a?(Hash)
+
+      event
+    end
+
+    def signature_matches?(payload, signature, timestamp, secret)
+      return false unless payload.is_a?(String) && secret.is_a?(String) && !secret.empty?
+      return false unless [signature, timestamp].all? { |v| v.is_a?(String) || v.is_a?(Integer) }
+      return false unless parse_timestamp(timestamp)
+
+      expected = sign(payload: payload, timestamp: timestamp, secret: secret)
+      return false unless expected.bytesize == signature.to_s.bytesize
+
+      OpenSSL.fixed_length_secure_compare(expected, signature.to_s)
+    end
+
+    def timestamp_fresh?(timestamp, tolerance, now)
+      return true if tolerance.nil?
+
+      seconds = parse_timestamp(timestamp)
+      !seconds.nil? && (now.to_i - seconds).abs <= tolerance
+    end
+
+    def parse_timestamp(timestamp)
+      Integer(timestamp.to_s, 10)
+    rescue ::ArgumentError, TypeError
+      nil
+    end
+
+    def normalize_headers(headers)
+      headers.to_h.transform_keys { |name| name.to_s.sub(/\AHTTP_/i, "").tr("_", "-").downcase }
+    end
+
+    def header(normalized, suffix)
+      value = normalized["x-manza-#{suffix}"] || normalized["x-zazu-#{suffix}"]
+      return value.to_s unless value.nil? || value.to_s.empty?
+
+      raise Manza::ArgumentError, "missing X-Manza-#{suffix.capitalize} header"
+    end
+
+    private_class_method :signature_matches?, :timestamp_fresh?, :parse_timestamp, :normalize_headers, :header
+  end
+end

data/lib/manza.rb

@@ -21,6 +21,7 @@ require_relative "manza/errors"
 require_relative "manza/response"
 require_relative "manza/page"
 require_relative "manza/transfer_authorization"
+require_relative "manza/webhook"
 require_relative "manza/resources/base"
 require_relative "manza/resources/accounts"
 require_relative "manza/resources/beneficiaries"
@@ -30,6 +31,8 @@ require_relative "manza/resources/entity"
 require_relative "manza/resources/invoices"
 require_relative "manza/resources/payee_trust_requests"
 require_relative "manza/resources/payment_links"
+require_relative "manza/resources/payments"
+require_relative "manza/resources/transfer_authorizer"
 require_relative "manza/resources/transfer_drafts"
 require_relative "manza/resources/webhook_endpoints"
 require_relative "manza/client"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: manza
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.3.0
 platform: ruby
 authors:
 - Manza
@@ -76,11 +76,14 @@ files:
 - lib/manza/resources/invoices.rb
 - lib/manza/resources/payee_trust_requests.rb
 - lib/manza/resources/payment_links.rb
+- lib/manza/resources/payments.rb
+- lib/manza/resources/transfer_authorizer.rb
 - lib/manza/resources/transfer_drafts.rb
 - lib/manza/resources/webhook_endpoints.rb
 - lib/manza/response.rb
 - lib/manza/transfer_authorization.rb
 - lib/manza/version.rb
+- lib/manza/webhook.rb
 homepage: https://github.com/getmanza/manza-ruby
 licenses:
 - MIT