verifiabl-issuer 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 619853ce9733f541d03c4f5267ff59da66383941256b56970953bfec703f6600
-  data.tar.gz: 2c3b3bb84032287482bbde88fca5e85c947b6f557da73e165f4c5a593e629d44
+  metadata.gz: 369e3ae173f2115422efb4a81d7cd32b018e8cd15e291899e699d51048eeca4e
+  data.tar.gz: b058e79cd9791e2f17966455129d8df40e9869b3f550ff05906ad5bae98aea5f
 SHA512:
-  metadata.gz: a987cf173047507e67e5e693bcba5b59cbc914818261dddc1edfbeecf3cc5609a70f3db96e5da7b3a8e05f4aaf09ce6aab7acb22efe3665b622f1ab2a2a95f9f
-  data.tar.gz: 25180a6200be501ef89c6a647c0975018c14e7b34084c58ed8430e679a86f0fac38752f8c3591df56b8bda16a2084cf545f469f1ddb80eddcc23b76718dd4d36
+  metadata.gz: c2996561b125072f3d8a4fd9461d9164bf5689fc3773d3242e946d844351cb14fde3c0a39893ec50b74696b59cd6c880ce1917fedbe4a1da49d0f9642e11b22b
+  data.tar.gz: 719979e79cbc3853cc52d002d45757197d41dfc33fcd398dd1b125c25153b2c07a7e56a9558149c51c5e8c6a45c14cb9722c8a11e301695ba9fc2c7026830594

data/CHANGELOG.md

@@ -4,6 +4,41 @@ All notable changes to the Verifiabl Ruby SDK will be documented in this file.
 
 ## Unreleased
 
+## [1.1.0] - 2026-10-23
+
+### Added
+
+- `Configuration` accepts `token_store:`, a cache that worker processes
+  share, such as `Rails.cache`. The processes then use one OAuth token
+  instead of one each. The client encrypts each token with a key derived
+  from the client secret before it stores the token. When the stored token
+  is missing or due, one process fetches a new token. The other processes
+  use their current token or wait for the new token. The client does not
+  replace a token that the API rejects less than one minute after its
+  fetch. A store failure counts as a miss. `on_error` gets it as an event
+  with only `token_store:` (`:read`, `:write` or `:claim`) and `error:`.
+
+### Changed
+
+- The OAuth token request has its own 10-second limit within the request's
+  `timeout:` budget.
+- The README now links to the documentation at docs.verifiabl.io instead of
+  repeating it.
+
+## [1.0.1] - 2026-10-20
+
+### Changed
+
+- AU2 and NZ2 codes may be Symbols, such as `currency: :AUD` or
+  `type: :lump_sum`. The gem converts them to Strings before its checks, so
+  every check treats both forms alike. Amounts must still be Strings.
+
+### Fixed
+
+- An AU2 earnings line with `type: :lump_sum` (a Symbol) and no
+  `lump_sum_type` now raises `ArgumentError`, as the String form already did.
+  1.0.0 sent it without the code.
+
 ## [1.0.0] - 2026-10-19
 
 First stable release. The public API now follows Semantic Versioning.

data/README.md

@@ -1,85 +1,108 @@
-# Verifiabl Ruby SDK
+# verifiabl-issuer
 
-Official Ruby SDK for issuing Verifiabl payslip QR codes. It includes offline protocol primitives,
-cross-SDK-compatible QR generation, deterministic SVG/PNG rendering, a hardened OAuth issuer
-client, RBS signatures, and packed-gem consumer qualification.
+The Verifiabl issuer SDK for Ruby. It registers payslip records with Verifiabl and makes their QR codes.
 
-## Installation
+## Documentation
 
-Add the stable release to your bundle:
+- [Issuer SDK guide](https://docs.verifiabl.io/issuer-sdk?lang=ruby)
+- [API reference](https://docs.verifiabl.io/api-reference/sdks/ruby)
 
-```ruby
-gem "verifiabl-issuer", "1.0.0"
-```
+## Requirements
 
-Then run `bundle install`.
+Ruby 3.3 or newer.
 
-Bundler loads the gem through its package-name entry point:
+## Installation
 
-```ruby
-require "verifiabl-issuer"
+```sh
+gem install verifiabl-issuer
 ```
 
-That entry point is a compatibility shim and loads the canonical namespaced entry point. Applications
-that require dependencies explicitly can use this path instead:
+## Usage
+
+Create one client with the client ID and client secret from your onboarding:
 
 ```ruby
 require "verifiabl/issuer"
-```
-
-Both forms load the same `Verifiabl::Issuer` implementation; applications do not need to require
-both. Ruby 3.3 or newer is required. QR encoding uses the pure-Ruby `rqrcode_core` gem; Verifiabl
-owns canonical mask selection and badge rendering rather than depending on the gem's PNG or SVG
-exporters.
-
-## Configuration
-
-Construct and retain an issuer client explicitly:
 
-```ruby
-issuer = Verifiabl::Issuer::Client.new(
-  Verifiabl::Issuer::Configuration.new(
-    environment: :sandbox,
-    client_id: ENV.fetch("VERIFIABL_CLIENT_ID"),
-    client_secret: ENV.fetch("VERIFIABL_CLIENT_SECRET")
-  )
+configuration = Verifiabl::Issuer::Configuration.new(
+  environment: :sandbox,
+  client_id: ENV.fetch("VERIFIABL_CLIENT_ID"),
+  client_secret: ENV.fetch("VERIFIABL_CLIENT_SECRET")
 )
+issuer = Verifiabl::Issuer::Client.new(configuration)
 ```
 
-The SDK is framework-neutral: it does not load Rails or Active Support, install framework hooks, or
-configure logging. Applications own their long-lived client and place it in their normal dependency
-container; Rails applications commonly construct it in an initializer. A client is safe to share
-between threads and refreshes its OAuth cache after a process fork.
-
-Set `on_request`, `on_response`, and `on_error` on `Configuration` when request telemetry is needed.
-Events contain request metadata but never request bodies, credentials, or payslip data. Observer
-failures do not change request behavior.
+### Share tokens between processes
 
-The default timeout budget is 30 seconds across OAuth, token-lock waits, 401 refresh, retries,
-and backoff. Lock waits are bounded, and the budget is checked between operations. The built-in
-Net::HTTP transport applies the remaining budget to open, read, and write timeouts, but those are
-per-I/O inactivity timeouts, **not a hard wall-clock limit**: DNS or a response that keeps sending
-bytes can outlast the budget. A completed request that returns after the deadline raises
-`TimeoutError`; blocking custom adapters can also exceed it. The SDK does not use
-`Timeout.timeout`, which can asynchronously interrupt sockets and corrupt persistent connections.
-
-The Verifiabl reference is the idempotency key. `register_non_pii` generates and sends one
-when omitted, so it and batch registration can safely retry transport failures, 408s, 429s, and 5xx
-responses. API-managed barcode registration uses a server-generated reference and retries only 429,
-which is rejected before processing. Configure these limits when needed:
+Each client fetches an OAuth token and keeps it in memory, so each process fetches its own token.
+If you run many worker processes, for example an autoscaled job queue, set `token_store:` to a
+cache that the processes share. In a Rails application, use `Rails.cache` if Redis, Memcached or
+Solid Cache stores its data:
 
 ```ruby
 configuration = Verifiabl::Issuer::Configuration.new(
   client_id: ENV.fetch("VERIFIABL_CLIENT_ID"),
   client_secret: ENV.fetch("VERIFIABL_CLIENT_SECRET"),
-  timeout: 10,
-  max_retries: 2
+  token_store: Rails.cache
 )
-issuer = Verifiabl::Issuer::Client.new(configuration)
 ```
 
-Endpoint overrides are intended only for development. Issuer overrides require HTTPS except for
-loopback HTTP. OAuth overrides are restricted to Verifiabl auth hosts or loopback addresses.
+You can also use a different Active Support cache store, or any object with `read(key)` and
+`write(key, value, expires_in:, unless_exist: false)`. With `unless_exist: true`, `write` must
+write only if the key is absent, and return `false` if the key exists.
+
+The client encrypts each token with a key derived from the client secret before it writes the
+token. It names the entry with a keyed hash. The cache never holds a usable token or the client
+credentials.
+
+Each process uses its in-memory token. It reads the store only when that token is due for
+renewal, one minute before it expires. When the stored token is missing or due, one process
+claims the fetch and fetches a new token. The claim is an `unless_exist: true` write that lasts
+for 10 seconds, the limit of the token request. While that process fetches:
+
+- A process with a valid token continues to use it until the new token is in the store.
+- A process with no valid token polls the store for the new token. The interval starts at 0.1
+  seconds and doubles to a maximum of one second. If the claim expires, that process claims the
+  fetch.
+
+A fleet that renews together, or starts together after a quiet period, therefore fetches one
+token. When the API rejects a token, the client fetches a new token immediately. If the client
+fetched the rejected token less than one minute before, it returns the 401 instead.
+
+Limits:
+
+- A store failure costs a token fetch, not a registration. `Rails.cache` catches backend errors
+  and sends them to the Rails error reporter and logger, so `on_error` does not get them. To get
+  them in `on_error`, as an event with `token_store:` (`:read`, `:write` or `:claim`) and
+  `error:`, give the SDK a different store with an `error_handler:` that raises the exception
+  again. Do not make `Rails.cache` raise.
+- If the process that holds the claim stops during its fetch, the processes with no token wait
+  until the claim expires, at most 10 seconds.
+- The SDK cannot interrupt a store call. It checks the request's time budget after each call,
+  and store calls run while the client holds its token lock. Keep the store timeouts short. The
+  Rails Redis store default is one second.
+- The claim is best effort. If the store has no atomic `unless_exist`, such as a file store,
+  several processes can fetch. A store that is local to each process, such as a memory store,
+  shares nothing.
+- Stored expiry times are absolute. Keep worker clocks within one minute of each other.
+
+A store event has only `token_store:` and `error:`. A request failure has `method:`, `url:`,
+`path:` and `elapsed_ms:`. Check the kind of event before you read its fields. The SDK ignores
+exceptions from `on_error`, so if your handler fails on a store event, the report is lost:
+
+```ruby
+on_error = lambda do |event|
+  if event.key?(:token_store)
+    logger.warn("Verifiabl token store #{event[:token_store]} failed: #{event[:error].class}")
+  else
+    logger.error("Verifiabl #{event[:method]} #{event[:path]} failed: #{event[:error].class}")
+  end
+end
+```
+
+To prepare and register payslips and make their QR codes, follow the [issuer SDK guide](https://docs.verifiabl.io/issuer-sdk?lang=ruby).
+
+Before the first send, save each prepared `registration` and its ciphertext together. After a failure or restart, send that saved registration unchanged. It carries its reference, so the API does not register it twice. Preparing the payslip again makes a new reference. An `api_managed_registration` has no reference, so do not resend it after an ambiguous failure. See [Register again later](https://docs.verifiabl.io/issuer-sdk/retries-and-timeouts?lang=ruby#register-again-later).
 
 ## Connection reuse and custom transports
 
@@ -121,7 +144,8 @@ end
 ```
 
 The adapter receives `method:`, `url:`, `headers:`, `body:` (serialized JSON), and `timeout:`
-(remaining seconds), for both OAuth and issuer requests. Return an object with integer `status`,
+(remaining seconds), for both OAuth and issuer requests. The OAuth token request gets at most
+10 seconds. Return an object with integer `status`,
 `headers` (prefer lowercase keys), and string `body` readers. Adapters own their I/O and
 pool-acquisition timeouts, failed-connection cleanup, and must not retry non-idempotent calls.
 For a **strict total deadline**, bring an adapter that bounds DNS, pool waits, TLS, writes, headers,
@@ -130,395 +154,10 @@ cannot forcibly interrupt arbitrary blocking adapter code. Native `Timeout::Erro
 become SDK `TimeoutError`; socket/I/O failures become SDK errors. The application owns adapter
 shutdown, thread safety, and post-fork recreation.
 
-## Issue payslips
-
-For new AU/NZ v2 integrations, prepare the payslip once with its jurisdiction-specific helper. The helper selects the schema and PII formatter, validates non-PII fields with the SDK's existing rules, and encrypts locally. Choose one barcode flow for each payslip. Do not call both registration methods for the same issuance.
-
-### AU2 and NZ2 payslip profiles
-
-Use `prepare_australian_v2_payslip` for Australian records or
-`prepare_new_zealand_v2_payslip` for New Zealand records. Each selects the
-matching v2 schema and PII formatter internally. The AU2 formatter accepts
-employer name and ABN separately, then writes the ABN when present or falls
-back to the name. Structured address components collapse into one address
-display field.
-
-```ruby
-require "base64"
-
-provider_encryption_key = Base64.strict_decode64(
-  ENV.fetch("VERIFIABL_ENCRYPTION_KEY_BASE64")
-)
-prepared = Verifiabl::Issuer.prepare_australian_v2_payslip(
-  pii: {
-    employee_name: "Ana Leota",
-    employer_name: "Example Software Pty Ltd",
-    employer_abn: "12 345 678 901",
-    address: {lines: ["12 Example St"], suburb: "Sydney", state_or_territory: "NSW", postcode: "2000"}
-  },
-  payslip_non_pii: {
-    period_end: "2026-05-31", payment_date: "2026-06-04", currency: "AUD",
-    gross: "9000.00", paygw: "2250.00", net: "6750.00"
-  },
-  issued_at: Time.now.utc,
-  key: provider_encryption_key
-)
-# Persist the registration and ciphertext together before sending (binary columns).
-saved_registration = prepared.registration
-saved_ciphertext = prepared.barcode_parts(prepared.verifiabl_reference).fetch(:encrypted_pii)
-# Persist saved_registration and saved_ciphertext atomically. The registration
-# has the reference, IV and tag, but not the ciphertext.
-registration = issuer.register_non_pii(**saved_registration)
-# After a restart, resend saved_registration unchanged and render from saved_ciphertext.
-barcode = Verifiabl::Issuer.build_barcode_svg(
-  verifiabl_reference: registration.verifiabl_reference,
-  encrypted_pii: saved_ciphertext, environment: :sandbox
-)
-```
-
-For NZ, pass the `ird_number` and the printed employer and bank details in the
-NZ helper's `pii:` input. NZ2 carries the printed employee IRD number,
-employer name, account number and account name. It has no BSB or NZBN field.
-
-Both formatters always write eight positions, including empty trailing fields. AU addresses render
-as address lines followed by `suburb state postcode`; NZ addresses render as address lines, optional
-suburb, then `city postcode`. Country is implicit. The complete UTF-8 plaintext is limited to 1024
-bytes.
-
-The preparation helpers pair the AU2/NZ2 PII format with the matching v2
-non-PII schema. Their input does not accept a schema, formatted plaintext, or
-ciphertext. They do not check whether input values describe a real payslip or
-whether printed non-PII strings contain personal information. Keep employee
-PII out of non-PII fields. Advanced integrations can still select the schema
-and formatter separately with the low-level APIs. PII format and non-PII
-schema versions are independent; legacy v1 verification remains supported.
-The verifier currently interprets AU2 only for `au.payslip.v2` and NZ2 only
-for `nz.payslip.v2`. Future non-PII schemas need an explicit verifier reader
-mapping before reusing either PII format; an unknown schema falls back to raw
-PII text rather than structured fields.
-
-Every AU2 and NZ2 amount, rate and quantity is a plain decimal `String`, for example `"1234.56"`,
-`"-25.00"` or `"47.3684"`: an optional leading `-`, digits, and an optional `.` followed by digits.
-The SDK sends the string exactly as given, so `"1.50"` and `"1.5"` stay distinct. It rejects any
-other value, including an `Integer`, `Float` or `BigDecimal`, before sending. `period_start` is
-optional for AU2 and NZ2. `currency` is required and must be a current ISO 4217 currency code
-(`Verifiabl::Issuer::SUPPORTED_V2_CURRENCIES`). Fund codes and codes with no minor unit, for example
-`XAU` or `XXX`, are not accepted, because wages are paid in legal tender. The SDK also rejects unlisted fields (including
-nested fields) before transport to avoid sending accidental PII; the API validates the remaining
-payslip rules.
-
-For common fixed AU/NZ v2 fields, use the frozen discovery lists in
-`Verifiabl::Issuer::PayslipCodes`. The lists are scoped by jurisdiction and
-contain the known codes, including the earnings discriminators:
-
-```ruby
-au = Verifiabl::Issuer::PayslipCodes::Australian
-nz = Verifiabl::Issuer::PayslipCodes::NewZealand
-au::PAY_FREQUENCIES # => ["weekly", "fortnightly", "monthly", "quarterly", "four_weekly", "semi_monthly"]
-au::OTHER_ALLOWANCE_CATEGORIES.include?("home_office") # => true
-nz::LEAVE_BALANCE_UNITS # => ["hours", "days", "weeks"]
-```
-
-`EARNINGS_TYPES`, `PAID_LEAVE_TYPES` and `ALLOWANCE_TYPES` are available for
-both jurisdictions. An AU2 `lump_sum` line takes a `lump_sum_type` from
-`LUMP_SUM_TYPES`, and an `etp` line takes an `etp_type` from `ETP_TYPES` and
-an `etp_component` from `ETP_COMPONENTS`. Use their strings in your normal
-payslip hash; the lists do not restrict input or add local enum validation,
-and the API may accept a new code before this gem is updated. The gem raises
-before sending an AU2 `lump_sum` line without a `lump_sum_type`.
-Printed-text fields such as `tax_code` and `pay_cycle` are not code sets.
-
-### Self-managed barcode flow
-
-Use this flow when your application renders the barcode. This AU2 example is generated from
-the runnable
-[`examples/issuer/basic/issue_payslips_self_managed.rb`](../../examples/issuer/basic/issue_payslips_self_managed.rb)
-source.
-
-<!-- snippet:ruby.basic-issuance:start -->
-
-```ruby
-require "base64"
-require "fileutils"
-require "verifiabl/issuer"
-
-PAYSLIP = {
-  external_id: "PAY-1001",
-  pii: {
-    employee_name: "Ana Leota",
-    position: "Senior Developer",
-    department: "Engineering",
-    employer_name: "Example Software Pty Ltd",
-    employer_abn: "12 345 678 901",
-    bsb: "062-000",
-    account_number: "****5678",
-    account_name: "A Leota",
-    address: {lines: ["12 Example St"], suburb: "Sydney", state_or_territory: "NSW", postcode: "2000"}
-  },
-  non_pii: {
-    period_end: "2026-08-31",
-    payment_date: "2026-09-04",
-    currency: "AUD",
-    gross: "9000.00",
-    paygw: "2250.00",
-    net: "6750.00"
-  }
-}.freeze
-
-issuer = Verifiabl::Issuer::Client.new(
-  Verifiabl::Issuer::Configuration.new(
-    environment: :sandbox,
-    client_id: ENV.fetch("VERIFIABL_CLIENT_ID"),
-    client_secret: ENV.fetch("VERIFIABL_CLIENT_SECRET")
-  )
-)
-
-provider_encryption_key = Base64.strict_decode64(
-  ENV.fetch("VERIFIABL_ENCRYPTION_KEY_BASE64")
-)
-prepared = Verifiabl::Issuer.prepare_australian_v2_payslip(
-  pii: PAYSLIP.fetch(:pii),
-  payslip_non_pii: PAYSLIP.fetch(:non_pii),
-  issued_at: Time.now.utc,
-  key: provider_encryption_key
-)
-# Persist prepared.registration and the binary ciphertext from
-# prepared.barcode_parts(prepared.verifiabl_reference).fetch(:encrypted_pii)
-# atomically before sending. Reuse both after a process restart.
-result = issuer.register_non_pii(**prepared.registration)
-
-barcode = Verifiabl::Issuer.build_barcode_svg(
-  **prepared.barcode_parts(result.verifiabl_reference),
-  environment: :sandbox
-)
-
-output_path = File.expand_path("output/self-managed-barcode.svg", __dir__)
-FileUtils.mkdir_p(File.dirname(output_path))
-
-File.write(output_path, barcode.svg)
-puts "Registered #{result.verifiabl_reference} and wrote #{output_path}"
-```
-
-<!-- snippet:ruby.basic-issuance:end -->
-
-`register_non_pii` sends the non-PII fields and encryption metadata, but not the encrypted PII. The
-application combines the returned reference with the encrypted PII to render the SVG locally.
-
-### API-managed barcode flow
-
-Use this alternative when Verifiabl should render the barcode PNG. This NZ2 example is
-generated from the runnable
-[`examples/issuer/basic/issue_payslips_api_managed.rb`](../../examples/issuer/basic/issue_payslips_api_managed.rb)
-source.
-
-<!-- snippet:ruby.api-managed-issuance:start -->
-
-```ruby
-require "base64"
-require "fileutils"
-require "verifiabl/issuer"
-
-PAYSLIP = {
-  external_id: "PAY-1002",
-  pii: {
-    employee_name: "Ana Leota",
-    ird_number: "***-***-***",
-    position: "Senior Developer",
-    department: "Engineering",
-    employer_name: "Example Software Limited",
-    account_number: "**-****-*******-**",
-    account_name: "A Leota",
-    address: {lines: ["12 Example Street"], suburb: "Te Aro", city: "Wellington", postcode: "6011"}
-  },
-  non_pii: {
-    period_end: "2026-08-31",
-    payment_date: "2026-09-04",
-    currency: "NZD",
-    gross: "9000.00",
-    paye: "2283.96",
-    net: "6716.04"
-  }
-}.freeze
-
-issuer = Verifiabl::Issuer::Client.new(
-  Verifiabl::Issuer::Configuration.new(
-    environment: :sandbox,
-    client_id: ENV.fetch("VERIFIABL_CLIENT_ID"),
-    client_secret: ENV.fetch("VERIFIABL_CLIENT_SECRET")
-  )
-)
-
-provider_encryption_key = Base64.strict_decode64(
-  ENV.fetch("VERIFIABL_ENCRYPTION_KEY_BASE64")
-)
-prepared = Verifiabl::Issuer.prepare_new_zealand_v2_payslip(
-  pii: PAYSLIP.fetch(:pii),
-  payslip_non_pii: PAYSLIP.fetch(:non_pii),
-  issued_at: Time.now.utc,
-  key: provider_encryption_key
-)
-# API-managed registration allocates its own reference. Do not replay an
-# ambiguous failure as if prepared.verifiabl_reference were its idempotency key.
-result = issuer.register_and_build_barcode(**prepared.api_managed_registration)
-
-output_path = File.expand_path("output/api-managed-barcode.png", __dir__)
-FileUtils.mkdir_p(File.dirname(output_path))
-
-File.binwrite(output_path, Base64.strict_decode64(result.barcode.data))
-puts "Registered #{result.verifiabl_reference} and wrote #{output_path}"
-```
-
-<!-- snippet:ruby.api-managed-issuance:end -->
-
-`register_and_build_barcode` sends the encrypted PII in addition to the non-PII fields and encryption
-metadata. Verifiabl uses the ciphertext to render the returned PNG and does not retain it. Plaintext
-PII is never sent in either flow.
-
-### Retries and batches
-
-For a self-managed registration that must remain retryable across process
-restarts, persist `prepared.registration` and the binary ciphertext from
-`prepared.barcode_parts(prepared.verifiabl_reference).fetch(:encrypted_pii)`
-together before the first call. The registration includes the reference, IV and
-tag but not the ciphertext. Reuse the *same* registration for a later attempt,
-then render from the saved ciphertext and the returned reference. You can pass `verifiabl_reference:` to the preparation helper if your
-system already allocated one. Do not prepare and encrypt again for an
-idempotent replay. The API-managed request does not include this reference.
-
-For pay runs, prepare each record with the matching jurisdiction helper. Pass
-its `registration` hash to batch registration with an optional `external_id`.
-Use each prepared result's `barcode_parts` with the corresponding batch result:
-
-```ruby
-prepared = payslips.map do |payslip|
-  if payslip.fetch(:country) == "AU"
-    Verifiabl::Issuer.prepare_australian_v2_payslip(
-      pii: payslip.fetch(:pii), payslip_non_pii: payslip.fetch(:non_pii),
-      issued_at: Time.now.utc, key: provider_encryption_key
-    )
-  else
-    Verifiabl::Issuer.prepare_new_zealand_v2_payslip(
-      pii: payslip.fetch(:pii), payslip_non_pii: payslip.fetch(:non_pii),
-      issued_at: Time.now.utc, key: provider_encryption_key
-    )
-  end
-end
-# Persist each prepared reference, registration, and ciphertext before sending.
-batch = issuer.register_non_pii_batch(prepared.each_with_index.map do |item, index|
-  item.registration.merge(external_id: payslips.fetch(index).fetch(:external_id))
-end)
-batch.results.each_with_index do |item, index|
-  if %w[created duplicate].include?(item.status)
-    parts = prepared.fetch(index).barcode_parts(item.verifiabl_reference)
-    # Render this record's barcode from parts.
-  else
-    # Handle item.code; do not parse item.detail.
-  end
-end
-```
-
-The API returns `201` for the first registration and `200` for an identical replay. Reusing a
-reference with different content raises `ApiError` with code `CONFLICT`.
-
-Successful calls return immutable typed result objects under `Verifiabl::Issuer::Responses`.
-Malformed successful API responses raise `TransportError`. Issuer HTTP errors raise `ApiError` (or
-`IvReuseError` for `IV_REUSED`). Non-timeout OAuth connectivity failures and invalid or unsuccessful
-token responses raise `AuthError`. Deadline expiry raises `TimeoutError`, while issuer network
-failures raise `TransportError`. Request and error messages never include the submitted payslip body.
-
-## Offline protocol primitives
-
-Most integrations should use the v2 preparation helpers. To select the schema and formatter
-yourself, format and encrypt PII locally with `format_australian_pii` (AU2, for `au.payslip.v2`) or
-`format_new_zealand_pii` (NZ2, for `nz.payslip.v2`). The plaintext must never be logged or sent to
-Verifiabl:
-
-```ruby
-plaintext = Verifiabl::Issuer.format_australian_pii(
-  employee_name: "Ana Leota",
-  employer_abn: "53004085616",
-  address: {lines: ["12 Example St"], suburb: "Sydney", state_or_territory: "NSW", postcode: "2000"}
-)
-
-encrypted = Verifiabl::Issuer.encrypt_pii(plaintext, provider_encryption_key)
-reference = Verifiabl::Issuer.generate_verifiabl_reference
+## Support
 
-scan_url = Verifiabl::Issuer.build_scan_url(
-  verifiabl_reference: reference,
-  encrypted_pii: encrypted.encrypted_pii,
-  environment: :sandbox
-)
-
-xmp_payload = Verifiabl::Issuer.build_barcode_payload(
-  verifiabl_reference: reference,
-  encrypted_pii: encrypted.encrypted_pii
-)
-
-svg = Verifiabl::Issuer.build_barcode_svg(
-  verifiabl_reference: reference,
-  encrypted_pii: encrypted.encrypted_pii,
-  environment: :sandbox,
-  width: 480
-)
-File.write("barcode.svg", svg.svg)
-
-png = Verifiabl::Issuer.build_barcode_png(
-  verifiabl_reference: reference,
-  encrypted_pii: encrypted.encrypted_pii,
-  environment: :sandbox,
-  width: 720
-)
-File.binwrite("barcode.png", png.png)
-```
-
-The renderers use the same official vector frame, rounded finder geometry, and QR error-correction
-ladder as the Node and .NET SDKs. Vertical is the default; pass `layout: :horizontal` to put the
-QR on the left at full badge height, followed by a 7-unit white gap and the light-tinted
-"Secured by Verifiabl" panel on the right. Horizontal rendering is included in `0.4.0`.
-
-| Layout | SVG minimum/default width | PNG widths | PNG default width |
-| --- | ---: | --- | ---: |
-| `:vertical` | 480 | 480, 720, 960, 1440 | 720 |
-| `:horizontal` | 940 | 940, 1410, 1880, 2820 | 1410 |
-
-SVG widths scale continuously above the minimum. PNG frames are pre-rasterised for deterministic
-cross-SDK output and support only the listed widths. Both layouts render the QR at the same sizes
-at corresponding widths; the horizontal badge's total width includes its brand panel and gap.
-For example, `build_barcode_svg(**parts, layout: :horizontal)` returns a 940×480 SVG and
-`build_barcode_png(**parts, layout: :horizontal)` returns a 1410×720 PNG.
-
-### Badge placement
-
-Place the badge on a light background with a clear margin of at least four QR modules
-(`result.module_px` at the rendered size) on every open QR side: **left, right and bottom** for
-vertical; **left, top and bottom** for horizontal. A tenth of the QR side covers realistic records.
-The host document supplies these quiet zones; the badge supplies only the gap facing the brand
-frame. Size the QR, not the whole horizontal badge: a 22 mm QR means a horizontal badge about
-43.08 mm wide and 22 mm high.
-
-Use `max_error_correction: :q` for greater damage recovery; the default is
-`:m`, and the renderer steps down only when necessary to preserve the three-pixel module floor.
-Each result's `degraded` field (`svg.degraded` or `png.degraded` above) is true when the renderer
-steps down from the requested ceiling or the modules fall below the ideal four-pixel size.
-
-`provider_encryption_key` must be exactly 32 bytes and loaded from a KMS or secrets manager. Every
-encryption call creates a fresh AES-256-GCM IV. Ciphertext, IV, and authentication tags are exposed
-as binary Ruby strings (`Encoding::BINARY`) and can be persisted directly in binary database
-columns. The SDK encodes them only at an external boundary: base64url for issuer API requests and
-uppercase, unpadded RFC 4648 Base32 for v2 barcode and XMP output. PDF integrations should store `xmp_payload` under
-XMP namespace `https://verifiabl.io/ns/`, property `payload`. QR v2 is encoded as an explicit byte
-prefix and alphanumeric ciphertext segment. Matrix version, mask, and modules match the Node and
-.NET SDKs.
-
-## Development
-
-```sh
-bundle install
-bundle exec rake
-(cd gems/verifiabl-issuer && bundle exec gem build verifiabl-issuer.gemspec)
-bundle exec ruby script/packed_gem_check.rb
-```
+Report issues at [github.com/Verifiabl/verifiabl-ruby](https://github.com/Verifiabl/verifiabl-ruby/issues).
 
 ## License
 
-[MIT](./LICENSE)
+MIT. See [LICENSE](https://github.com/Verifiabl/verifiabl-ruby/blob/main/gems/verifiabl-issuer/LICENSE).

data/lib/verifiabl/issuer/client.rb

@@ -17,6 +17,10 @@ module Verifiabl
       RETRY_BASE_SECONDS = 0.5
       RETRY_MAX_SECONDS = 8.0
       REQUEST_ID_HEADERS = %w[x-request-id request-id x-verifiabl-request-id].freeze
+      SHARED_FETCH_POLL_SECONDS = 0.1
+      SHARED_FETCH_MAX_POLL_SECONDS = 1.0
+      REJECTED_TOKEN_MIN_AGE_SECONDS = 60
+      TOKEN_FETCH_TIMEOUT_SECONDS = 10
 
       def self.request_id(headers)
         REQUEST_ID_HEADERS.each do |name|
@@ -41,11 +45,12 @@ module Verifiabl
         @on_request = configuration.on_request
         @on_response = configuration.on_response
         @on_error = configuration.on_error
+        @shared_token_store = build_shared_token_store(configuration.token_store)
         @token_mutex = Mutex.new
         @process_id = Process.pid
       end
 
-      # Registers non-PII data under a provider-generated reference. When the
+      # Registers non-PII data under an issuer-generated reference. When the
       # caller omits one, generate it once before the request loop so every
       # automatic retry uses the same idempotency key. Callers that need to
       # retry from another process or invocation should generate, persist, and
@@ -124,11 +129,17 @@ module Verifiabl
 
       def send_with_auth(path, body, deadline)
         token = access_token(deadline)
-        response = issuer_request(path, body, token, deadline)
-        return response unless response.status == 401
+        response = issuer_request(path, body, token.value, deadline)
+        return response unless response.status == 401 && replaceable?(token)
 
-        invalidate_token(token, deadline)
-        issuer_request(path, body, access_token(deadline), deadline)
+        invalidate_token(token.value, deadline)
+        issuer_request(path, body, access_token(deadline, rejected: token.value).value, deadline)
+      end
+
+      # A token the API rejects within a minute of its fetch is not replaced:
+      # a replacement would be rejected too, once per request.
+      def replaceable?(token)
+        @clock.call - token.issued_at >= REJECTED_TOKEN_MIN_AGE_SECONDS
       end
 
       def issuer_request(path, body, token, deadline)
@@ -165,23 +176,101 @@ module Verifiabl
         {"content-type" => "application/json", "accept" => "application/json", "user-agent" => "verifiabl-issuer-ruby/#{VERSION} (ruby #{RUBY_VERSION})"}
       end
 
-      def access_token(deadline)
+      # A token the API just rejected is never reused, whichever layer still
+      # holds it: the shared store keeps it until a replacement overwrites it.
+      def access_token(deadline, rejected: nil)
         reset_token_cache_after_fork!
-        now = @clock.call
         cached = @token
-        return cached.value if cached && token_fresh?(cached, now)
+        return cached if usable_token?(cached, @clock.call, rejected)
 
         ensure_before_deadline!(deadline)
         with_token_lock(deadline) do
           ensure_before_deadline!(deadline)
-          now = @clock.call
-          return @token.value if @token && token_fresh?(@token, now)
+          return @token if usable_token?(@token, @clock.call, rejected)
+
+          @token = shared_token(rejected) || fetch_or_wait(deadline, rejected)
+          # The store owns its timeouts, like a transport adapter, so a slow
+          # store is only noticed afterwards. The token is kept either way: it
+          # was paid for, and the next request can use it.
+          ensure_before_deadline!(deadline)
+          @token
+        end
+      end
+
+      # Fresh enough to use without looking for a renewal.
+      def usable_token?(token, now, rejected)
+        token && token.value != rejected && token_fresh?(token, now)
+      end
+
+      # Due for renewal but still accepted by the API.
+      def valid_token?(token, now, rejected)
+        token && token.value != rejected && token.expires_at > now
+      end
+
+      # The store read takes time, so freshness is judged by the clock after
+      # it returns, not before.
+      def shared_token(rejected = nil)
+        token = @shared_token_store&.read(@clock.call)
+        token if usable_token?(token, @clock.call, rejected)
+      end
+
+      # Workers that share a store find its token due, or missing after a
+      # quiet period, at the same time. One claims the fetch. A worker with a
+      # valid token keeps using it. A worker with none polls the store, and
+      # claims the fetch itself if the claim expires. The poll interval
+      # doubles up to one second, so a stalled claimant costs a large fleet
+      # about one store read per worker each second.
+      def fetch_or_wait(deadline, rejected)
+        poll_seconds = SHARED_FETCH_POLL_SECONDS
+        loop do
+          fetch_deadline = token_fetch_deadline(deadline)
+          return fetch_and_share_token(fetch_deadline) if fetch_claim_mine?(deadline, fetch_deadline, rejected)
+          return @token if valid_token?(@token, @clock.call, rejected)
 
-          @token = fetch_token(now, deadline)
-          @token.value
+          ensure_before_deadline!(deadline)
+          @sleeper.call([poll_seconds, remaining_time(deadline)].min)
+          poll_seconds = [poll_seconds * 2, SHARED_FETCH_MAX_POLL_SECONDS].min
+          ensure_before_deadline!(deadline)
+          token = shared_token(rejected)
+          return token if token
         end
       end
 
+      # True when this process should fetch: there is no store, the API
+      # rejected the stored token, or no process holds the claim. The claim
+      # ends at the token request's deadline, so it covers the time the store
+      # calls take as well. A refused claim is read back: a store that
+      # swallows a backend error returns `false` for the write and `nil` for
+      # the read.
+      def fetch_claim_mine?(deadline, fetch_deadline, rejected)
+        return true if @shared_token_store.nil? || rejected
+
+        ensure_before_deadline!(deadline)
+        return false if @shared_token_store.fetch_claim_held?
+
+        ensure_before_deadline!(deadline)
+        return true unless @shared_token_store.claim_fetch(remaining_time(fetch_deadline).ceil) == false
+
+        ensure_before_deadline!(deadline)
+        !@shared_token_store.fetch_claim_held?
+      end
+
+      # The token request gets its own short limit, so a process that takes
+      # over a lapsed claim still has time to register, and a claim that
+      # outlives a fast fetch expires before the new token is due.
+      def token_fetch_deadline(deadline)
+        [deadline, @monotonic_clock.call + TOKEN_FETCH_TIMEOUT_SECONDS].min
+      end
+
+      # The clock is sampled after the store miss: a token dated from before
+      # a slow read would look older than it is.
+      def fetch_and_share_token(fetch_deadline)
+        now = @clock.call
+        token = fetch_token(now, fetch_deadline)
+        @shared_token_store&.write(token, now)
+        token
+      end
+
       def invalidate_token(rejected, deadline)
         reset_token_cache_after_fork!
         with_token_lock(deadline) { @token = nil if @token&.value == rejected }
@@ -204,11 +293,15 @@ module Verifiabl
       # permanently locked copy of the parent's mutex. A child has one thread
       # immediately after fork, so replacing this local state before locking is
       # safe and gives it an independent token cache.
+      #
+      # Each child also inherits the parent's random generator state. A fresh
+      # generator stops children from retrying in lockstep.
       def reset_token_cache_after_fork!
         return if @process_id == Process.pid
 
         @token_mutex = Mutex.new
         @token = nil
+        @random = Random.new
         @process_id = Process.pid
       end
 
@@ -217,9 +310,29 @@ module Verifiabl
         token.expires_at - now > [60, ttl / 2].min
       end
 
+      def build_shared_token_store(backend)
+        return if backend.nil?
+        raise ArgumentError, "token_store must respond to read and write" unless SharedTokenStore.valid_backend?(backend)
+        # Invalid credentials fail at the token fetch, as they do without a store.
+        return unless @client_id.is_a?(String) && @client_secret.is_a?(String)
+
+        SharedTokenStore.new(
+          backend,
+          client_secret: @client_secret.strip,
+          identity: [@token_url, @client_id.strip, @issuer_base_url, ISSUER_SCOPE],
+          on_error: @on_error
+        )
+      end
+
       def fetch_token(now, deadline)
         validate_credentials!
-        response = request(method: :post, url: @token_url, headers: json_headers, body: token_request_body, deadline: deadline)
+        response = request(
+          method: :post,
+          url: @token_url,
+          headers: json_headers,
+          body: token_request_body,
+          deadline: deadline
+        )
         parsed = parse_json(response.body)
         validate_token_response!(response, parsed)
         CachedToken.new(value: parsed["access_token"], issued_at: now, expires_at: now + parsed["expires_in"])
@@ -326,13 +439,20 @@ module Verifiabl
       end
 
       def configure_endpoints(configuration)
-        @client_id = configuration.client_id
-        @client_secret = configuration.client_secret
+        @client_id = frozen_copy(configuration.client_id)
+        @client_secret = frozen_copy(configuration.client_secret)
         origins = Payload.resolve_environment(configuration.environment)
         @token_url = normalize_token_url(configuration.token_url || origins.fetch(:token_url))
         @issuer_base_url = normalize_issuer_base_url(configuration.issuer_base_url || origins.fetch(:issuer_base_url))
       end
 
+      # The shared store's keys are derived once from these credentials, so the
+      # caller must not be able to change them afterwards: a secret swapped
+      # later would store another account's token under this account's entry.
+      def frozen_copy(value)
+        value.is_a?(String) ? value.dup.freeze : value
+      end
+
       def configure_retry_policy(configuration)
         @timeout = configuration.timeout
         @max_retries = configuration.max_retries

data/lib/verifiabl/issuer/configuration.rb

@@ -15,7 +15,8 @@ module Verifiabl
         max_retries: 2,
         on_request: nil,
         on_response: nil,
-        on_error: nil
+        on_error: nil,
+        token_store: nil
       }.freeze
       private_constant :DEFAULTS
 

data/lib/verifiabl/issuer/instrumentation.rb

@@ -28,6 +28,12 @@ module Verifiabl
         raise
       end
 
+      # Reports a failure that the SDK recovered from, such as a token store
+      # outage, so it is visible without changing request behaviour.
+      def emit_error(payload, on_error)
+        emit(:error, payload, on_error)
+      end
+
       def emit(type, payload, callback)
         event = payload.freeze
         begin

data/lib/verifiabl/issuer/non_pii_v2.rb

@@ -12,9 +12,11 @@ module Verifiabl
 
       module_function
 
-      def validate!(schema, payload)
-        check!(FIELDS.fetch(schema), payload, "payslip_non_pii")
-        check_lump_sum_types!(payload) if schema == AUSTRALIAN_PAYSLIP_V2_SCHEMA
+      # Returns the payload with Symbol codes as Strings, so later checks see what JSON encoding sends.
+      def to_wire!(schema, payload)
+        wire = convert!(FIELDS.fetch(schema), payload, "payslip_non_pii")
+        check_lump_sum_types!(wire) if schema == AUSTRALIAN_PAYSLIP_V2_SCHEMA
+        wire
       end
 
       # The API still accepts a bare lump sum from older SDKs, but a lump sum without its STP2 code
@@ -28,45 +30,48 @@ module Verifiabl
       end
       private_class_method :check_lump_sum_types!
 
-      def check!(allowed, value, path)
+      def convert!(allowed, value, path)
         case allowed
-        when Hash then check_object!(allowed, value, path)
-        when Array then check_array!(allowed.first, value, path)
-        when "decimal" then check_decimal!(value, path)
-        else check_scalar!(value, path)
+        when Hash then convert_object!(allowed, value, path)
+        when Array then convert_array!(allowed.first, value, path)
+        when "decimal" then decimal!(value, path)
+        else scalar!(value, path)
         end
       end
-      private_class_method :check!
+      private_class_method :convert!
 
-      def check_object!(allowed, value, path)
+      def convert_object!(allowed, value, path)
         raise ArgumentError, "#{path} must be an object" unless value.is_a?(Hash)
 
-        value.each do |key, child|
+        value.to_h do |key, child|
           raise ArgumentError, "#{path}.#{key} is not permitted" unless allowed.key?(key)
 
-          check!(allowed.fetch(key), child, "#{path}.#{key}")
+          [key, convert!(allowed.fetch(key), child, "#{path}.#{key}")]
         end
       end
-      private_class_method :check_object!
+      private_class_method :convert_object!
 
-      def check_array!(allowed, value, path)
+      def convert_array!(allowed, value, path)
         raise ArgumentError, "#{path} must be an array" unless value.is_a?(Array)
 
-        value.each_with_index { |child, index| check!(allowed, child, "#{path}[#{index}]") }
+        value.each_with_index.map { |child, index| convert!(allowed, child, "#{path}[#{index}]") }
       end
-      private_class_method :check_array!
+      private_class_method :convert_array!
 
-      def check_decimal!(value, path)
-        return if value.is_a?(String) && DECIMAL_PATTERN.match?(value)
+      # Amounts stay Strings only, so the SDK never guesses at a number's text.
+      def decimal!(value, path)
+        return value if value.is_a?(String) && DECIMAL_PATTERN.match?(value)
 
         raise ArgumentError, "#{path} must be a plain decimal String, for example \"1234.56\""
       end
-      private_class_method :check_decimal!
+      private_class_method :decimal!
 
-      def check_scalar!(value, path)
+      def scalar!(value, path)
         raise ArgumentError, "#{path} must be a scalar" if value.is_a?(Hash) || value.is_a?(Array)
+
+        value.is_a?(Symbol) ? value.to_s : value
       end
-      private_class_method :check_scalar!
+      private_class_method :scalar!
     end
   end
 end

data/lib/verifiabl/issuer/serialization.rb

@@ -12,7 +12,10 @@ module Verifiabl
       def registration_to_wire(schema:, issued_at:, payslip_non_pii:, encryption_metadata:)
         Validation.registration!(schema: schema, issued_at: issued_at, payslip_non_pii: payslip_non_pii, encryption_metadata: encryption_metadata)
         wire_payslip = stringify_keys(payslip_non_pii)
-        NonPiiV2.validate!(schema, wire_payslip) if [AUSTRALIAN_PAYSLIP_V2_SCHEMA, NEW_ZEALAND_PAYSLIP_V2_SCHEMA].include?(schema)
+        if [AUSTRALIAN_PAYSLIP_V2_SCHEMA, NEW_ZEALAND_PAYSLIP_V2_SCHEMA].include?(schema)
+          wire_payslip = NonPiiV2.to_wire!(schema, wire_payslip)
+          Validation.v2_currency!(wire_payslip)
+        end
         {
           "schema" => schema,
           "issued_at" => serialize_time(issued_at),

data/lib/verifiabl/issuer/shared_token_store.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+require "json"
+require "openssl"
+require "securerandom"
+
+module Verifiabl
+  module Issuer
+    # Keeps OAuth tokens in an application cache that several processes
+    # share, such as a Redis-backed cache, so a fleet of job workers reuses
+    # one token instead of each worker fetching its own.
+    #
+    # The backend sees only an opaque key and AES-256-GCM ciphertext. Both
+    # are derived from the client secret and the token's identity (token
+    # URL, client ID, audience and scope): reading the cache without the
+    # secret reveals no token, and the secret alone can already mint one.
+    #
+    # Backend failures and unreadable entries count as a miss and are
+    # reported through `on_error`, so a cache outage costs a token fetch
+    # rather than blocking registration.
+    #
+    # @api private
+    class SharedTokenStore
+      FORMAT = "v1"
+      KEY_PREFIX = "verifiabl-issuer:token:#{FORMAT}:"
+      VALUE_PREFIX = "#{FORMAT}:"
+      KEY_BYTES = 32
+      IV_BYTES = 12
+      TAG_BYTES = 16
+      BACKEND_METHODS = %i[read write].freeze
+      FETCH_CLAIM_SUFFIX = ":fetch"
+
+      def self.valid_backend?(backend)
+        BACKEND_METHODS.all? { |name| backend.respond_to?(name) }
+      end
+
+      # @param identity [Array] everything besides the secret that selects a
+      #   token: token URL, client ID, audience and scope.
+      # @param on_error [#call, nil] receives `{token_store:, error:}` when
+      #   the backend raises; the failure never changes request behaviour.
+      def initialize(backend, client_secret:, identity:, on_error: nil)
+        @backend = backend
+        @on_error = on_error
+        identity_json = JSON.generate(identity)
+        @encryption_key = derive_key(client_secret, "encryption", identity_json)
+        lookup_key = derive_key(client_secret, "lookup", identity_json)
+        @key = KEY_PREFIX + OpenSSL::HMAC.hexdigest("SHA256", lookup_key, identity_json)
+        @fetch_claim_key = @key + FETCH_CLAIM_SUFFIX
+      end
+
+      # Returns the stored token, or nil when there is none that is unexpired.
+      def read(now)
+        observe(:read) { decode(read_backend(@key), now) }
+      end
+
+      def write(token, now)
+        seconds_left = (token.expires_at - now).floor
+        return unless seconds_left.positive?
+
+        observe(:write) { @backend.write(@key, encode(token), expires_in: seconds_left) }
+      end
+
+      # Claims the next token fetch for `seconds`. Returns `false` only when a
+      # claim exists. The claim expires instead of being deleted, so it never
+      # removes a later process's claim.
+      def claim_fetch(seconds)
+        observe(:claim) { @backend.write(@fetch_claim_key, "1", expires_in: seconds, unless_exist: true) }
+      end
+
+      # True while a process holds the claim. A store that swallows a backend
+      # error answers `nil`, so an outage never makes a process wait.
+      def fetch_claim_held?
+        observe(:claim) { read_backend(@fetch_claim_key) } == "1"
+      end
+
+      private
+
+      # In a Rails request, Active Support stores answer repeat reads from a
+      # request-local cache, so a poll would see only its first miss. A fresh
+      # local cache for each read sends it to the backend.
+      def read_backend(key)
+        return @backend.read(key) unless @backend.respond_to?(:with_local_cache)
+
+        @backend.with_local_cache { @backend.read(key) }
+      end
+
+      # The backend is the application's cache, so its failures and any
+      # unreadable entry count as a miss. The report lets an operator see a
+      # store that is misconfigured or down, which would otherwise look like
+      # the store doing nothing.
+      def observe(operation)
+        yield
+      rescue => error
+        Instrumentation.emit_error({token_store: operation, error: error}, @on_error)
+        nil
+      end
+
+      def derive_key(secret, purpose, identity_json)
+        OpenSSL::KDF.hkdf(
+          secret,
+          salt: "",
+          info: "verifiabl-issuer token store #{FORMAT} #{purpose} #{identity_json}",
+          length: KEY_BYTES,
+          hash: "SHA256"
+        )
+      end
+
+      def encode(token)
+        payload = JSON.generate(
+          "access_token" => token.value,
+          "issued_at" => token.issued_at.to_f,
+          "expires_at" => token.expires_at.to_f
+        )
+        iv = SecureRandom.random_bytes(IV_BYTES)
+        cipher = start_cipher(:encrypt, iv)
+        ciphertext = cipher.update(payload) + cipher.final
+        VALUE_PREFIX + [iv + ciphertext + cipher.auth_tag].pack("m0")
+      end
+
+      def decode(value, now)
+        return unless value.is_a?(String) && value.start_with?(VALUE_PREFIX)
+
+        bytes = value.delete_prefix(VALUE_PREFIX).unpack1("m0")
+        return if bytes.bytesize <= IV_BYTES + TAG_BYTES
+
+        token_from(JSON.parse(decrypt(bytes)), now)
+      end
+
+      # The key is authenticated with the ciphertext, so an entry copied to
+      # another credential's key fails to decrypt instead of being served.
+      def decrypt(bytes)
+        cipher = start_cipher(:decrypt, bytes.byteslice(0, IV_BYTES))
+        cipher.auth_tag = bytes.byteslice(-TAG_BYTES, TAG_BYTES)
+        ciphertext = bytes.byteslice(IV_BYTES, bytes.bytesize - IV_BYTES - TAG_BYTES)
+        cipher.update(ciphertext) + cipher.final
+      end
+
+      def start_cipher(direction, iv)
+        cipher = OpenSSL::Cipher.new("aes-256-gcm").public_send(direction)
+        cipher.key = @encryption_key
+        cipher.iv = iv
+        cipher.auth_data = @key
+        cipher
+      end
+
+      def token_from(payload, now)
+        value = payload["access_token"]
+        issued_at = payload["issued_at"]
+        expires_at = payload["expires_at"]
+        return unless value.is_a?(String) && !value.empty?
+        return unless issued_at.is_a?(Numeric) && expires_at.is_a?(Numeric)
+        return unless issued_at < expires_at && Time.at(expires_at) > now
+
+        Client::CachedToken.new(value: value, issued_at: Time.at(issued_at), expires_at: Time.at(expires_at))
+      end
+    end
+  end
+end

data/lib/verifiabl/issuer/validation.rb

@@ -14,7 +14,7 @@ module Verifiabl
 
       def registration!(schema:, issued_at:, payslip_non_pii:, encryption_metadata:)
         registration_envelope!(schema:, issued_at:, encryption_metadata:)
-        validate_payslip_non_pii!(schema, payslip_non_pii)
+        validate_payslip_non_pii!(payslip_non_pii)
       end
 
       def registration_envelope!(schema:, issued_at:, encryption_metadata:)
@@ -55,20 +55,19 @@ module Verifiabl
       end
       private_class_method :validate_encryption_metadata!
 
-      def validate_payslip_non_pii!(schema, payslip_non_pii)
+      def validate_payslip_non_pii!(payslip_non_pii)
         raise ArgumentError, "payslip_non_pii must be a Hash" unless payslip_non_pii.is_a?(Hash)
         validate_iso_date!(value(payslip_non_pii, :period_start), "period_start") if key?(payslip_non_pii, :period_start)
         validate_iso_date!(value(payslip_non_pii, :period_end), "period_end") if key?(payslip_non_pii, :period_end)
-        validate_v2_currency!(payslip_non_pii) if [AUSTRALIAN_PAYSLIP_V2_SCHEMA, NEW_ZEALAND_PAYSLIP_V2_SCHEMA].include?(schema)
       end
       private_class_method :validate_payslip_non_pii!
 
-      def validate_v2_currency!(payslip_non_pii)
-        return if SUPPORTED_V2_CURRENCIES.include?(value(payslip_non_pii, :currency))
+      # Takes the wire payslip, so a Symbol code has already become a String.
+      def v2_currency!(wire_payslip)
+        return if SUPPORTED_V2_CURRENCIES.include?(wire_payslip["currency"])
 
         raise ArgumentError, "currency is required and must be a supported ISO 4217 currency code, for example AUD"
       end
-      private_class_method :validate_v2_currency!
 
       def validate_issued_at!(issued_at)
         return if issued_at.is_a?(Time)

data/lib/verifiabl/issuer/version.rb

@@ -2,6 +2,6 @@
 
 module Verifiabl
   module Issuer
-    VERSION = "1.0.0"
+    VERSION = "1.1.0"
   end
 end

data/lib/verifiabl/issuer.rb

@@ -5,6 +5,7 @@ require_relative "issuer/configuration"
 require_relative "issuer/errors"
 require_relative "issuer/validation"
 require_relative "issuer/responses"
+require_relative "issuer/shared_token_store"
 require_relative "issuer/client"
 require_relative "issuer/crypto"
 require_relative "issuer/instrumentation"

data/sig/verifiabl-issuer.rbs

@@ -89,7 +89,13 @@ module Verifiabl
       attr_reader on_response: Proc?
       attr_reader on_error: Proc?
       attr_reader environment: Symbol
-      def initialize: (?client_id: String?, ?client_secret: String?, ?environment: Symbol | String, ?issuer_base_url: String?, ?token_url: String?, ?timeout: Numeric, ?max_retries: Integer, ?on_request: Proc?, ?on_response: Proc?, ?on_error: Proc?) -> void
+      attr_reader token_store: _TokenStore?
+      def initialize: (?client_id: String?, ?client_secret: String?, ?environment: Symbol | String, ?issuer_base_url: String?, ?token_url: String?, ?timeout: Numeric, ?max_retries: Integer, ?on_request: Proc?, ?on_response: Proc?, ?on_error: Proc?, ?token_store: _TokenStore?) -> void
+    end
+
+    interface _TokenStore
+      def read: (String) -> untyped
+      def write: (String, String, expires_in: Integer, ?unless_exist: bool) -> untyped
     end
 
     interface _TransportResponse

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: verifiabl-issuer
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Verifiabl
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-19 00:00:00.000000000 Z
+date: 2026-10-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -38,6 +38,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.1'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.1'
 - !ruby/object:Gem::Dependency
   name: bigdecimal
   requirement: !ruby/object:Gem::Requirement
@@ -108,6 +122,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '4.2'
+- !ruby/object:Gem::Dependency
+  name: redis
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
 - !ruby/object:Gem::Dependency
   name: rubocop
   requirement: !ruby/object:Gem::Requirement
@@ -196,6 +224,7 @@ files:
 - lib/verifiabl/issuer/rendering_assets.rb
 - lib/verifiabl/issuer/responses.rb
 - lib/verifiabl/issuer/serialization.rb
+- lib/verifiabl/issuer/shared_token_store.rb
 - lib/verifiabl/issuer/validation.rb
 - lib/verifiabl/issuer/version.rb
 - sig/manifest.yaml