assinafy 1.8.1 → 1.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: de868e0ed87ada5a4456c4a811a1aa8057a6c482b344944661a0a4670ab86057
-  data.tar.gz: cef6d34ac264a694a194ca46ec35810836d0660001fcea5d351a1bbfff1dc638
+  metadata.gz: 6c202496157dd16d5ae51e1e6416ca30ab0d6ec3665ffa6dead88219214c82b8
+  data.tar.gz: 9c07ecf32a3c9e9e94d964d56f6f38dc8c670d2cc011059d4c14409e79972b9e
 SHA512:
-  metadata.gz: 24fff2f9be29fbcf69788f6f217f541c9d68ba22c10ec6dbb2f557e2c9c3d827fe57004294d6c8af7cc1c38dd6e8ca2ff12bb826995a97ea7a111eae8589dac4
-  data.tar.gz: 6e7ffbaa337b9480c118bd1d5ef2d3423bba3622e333a5b6c11b20ed594df78cc03772e7243ff2ca919f272aab8efdf439db3bb06d3f9180553c8388e7f0753b
+  metadata.gz: 4bd51928265eb56100d62653932be2145442efb23e4708007070a027aeaff0e96678014c4d2a5b39ca2a9dcb37c6a13e5caf3b16798e28b6ad2ad535ef937068
+  data.tar.gz: 7c1c6a6f07f0794b685b414195161f9832c74e9e196adff5f8713b26b44d7b94c188651184144af0b7393ad8bfea97d601a0e350c7165d2a4709356bcda0743a

data/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 All notable changes to the `assinafy` Ruby gem are documented here.
 
+## 1.9.0
+
+- `OAuthResource#refresh`, and `#token` with the `refresh_token` grant, raise `Assinafy::Error` instead of
+  returning a success whose `refresh_token` is missing, blank, or the one sent. The token sent may already be
+  retired, so handle the error like `invalid_grant`.
+- `OAuthResource` posts `/oauth/token` and `/oauth/revoke` bodies as `application/x-www-form-urlencoded`, as
+  RFC 6749 and RFC 7009 define them. The API accepts this and JSON alike; no caller change is needed.
+- Every `ApiError`, not only `OAuthError`, carries the `WWW-Authenticate` challenge in
+  `context[:www_authenticate]`, including one raised for an error status inside a `2xx` envelope, so a `403` for
+  a missing OAuth scope can be told apart from one for another workspace or role.
+- `DocumentResource#verify` documents the nullable `agreement_code` field, the agreement code printed on the
+  document certificate. `spec/fixtures/api_contract.json` tracks the current contract.
+- `scripts/check_api_contract.rb` requires TLS 1.2 or newer.
+- The OAuth guides cover refresh-token rotation (every refresh returns a new refresh token valid for 30 days and
+  retires the old one): storing the new tokens and rebuilding the client, never resending a refresh token after
+  an ambiguous failure, and revoking the refresh token currently stored on disconnect. They also cover checking
+  `state` and `iss` against the values stored for each authorization attempt (the sandbox has its own issuer)
+  and finding the connected workspace through `GET /accounts`.
+
 ## 1.8.1
 
 - The SDK's own HTTPS client now requires TLS 1.2 or newer; TLS 1.0 and 1.1 are refused. Caller-supplied clients are unchanged.

data/README.en.md

@@ -154,7 +154,7 @@ The flow is authorization-code with **mandatory PKCE**; the authorization server
 | `email` | Include the user's email and verification status in the claims |
 | `offline_access` | Be issued a refresh token |
 
-**1. Redirect the user.** Store the verifier and state in the session first.
+**1. Redirect the user.** Store the verifier, the state, and the expected issuer in the session first.
 
 ```ruby
 verifier = Assinafy::OAuth.generate_code_verifier
@@ -162,6 +162,7 @@ state    = Assinafy::OAuth.generate_state
 
 session[:assinafy_code_verifier] = verifier
 session[:assinafy_state]         = state
+session[:assinafy_issuer]        = Assinafy::OAuth::AUTHORIZATION_SERVER # issuer of the server this attempt uses
 
 redirect_to Assinafy::OAuth.authorization_url(
   client_id:     ENV.fetch('ASSINAFY_CLIENT_ID'),
@@ -173,11 +174,20 @@ redirect_to Assinafy::OAuth.authorization_url(
 ```
 
 The `code_challenge` is derived from the verifier; the verifier itself never appears in the URL.
+`Assinafy::OAuth::AUTHORIZATION_SERVER` is the production issuer. The sandbox has its own: pass
+`authorization_endpoint: 'https://auth-sandbox.assinafy.com.br/oauth/authorize'` and store
+`https://auth-sandbox.assinafy.com.br` instead.
 
-**2. Exchange the code.** Compare `state` before exchanging — that is the CSRF check.
+**2. Exchange the code.** Check `state` and `iss` against the values stored for this attempt before anything
+else, including on an `error=` return — that is the CSRF check, and it rejects responses that are not yours. The
+code is single-use and expires 60 seconds after approval: exchange it at once, and never retry.
 
 ```ruby
-raise 'state mismatch' unless params[:state] == session.delete(:assinafy_state)
+unless params[:state] == session.delete(:assinafy_state) &&
+       params[:iss] == session.delete(:assinafy_issuer)
+  raise 'authorization response is not ours'
+end
+raise "authorization not granted: #{params[:error]}" if params[:error] # access_denied, invalid_scope, ...
 
 tokens = Assinafy::Client.new.oauth.exchange_code(
   code:          params.fetch(:code),
@@ -189,34 +199,63 @@ tokens = Assinafy::Client.new.oauth.exchange_code(
 #      'refresh_token' => ..., 'scope' => 'documents:read documents:write' }
 ```
 
-**3. Act as the user.**
+**3. Act as the user.** The token works only in the workspace the user picked; store its id next to the tokens.
 
 ```ruby
-user_client = Assinafy::Client.new(
-  token:      tokens.fetch('access_token'),
-  account_id: ENV.fetch('ASSINAFY_ACCOUNT_ID')
-)
+access_token = tokens.fetch('access_token')
+workspace_id = Assinafy::Client.new(token: access_token).accounts.list[:data].first.fetch('id')
 
+user_client = Assinafy::Client.new(token: access_token, account_id: workspace_id)
 user_client.documents.list
 user_client.oauth.userinfo  # => { 'sub' => ..., 'name' => ..., 'email' => ... }
 ```
 
-**Refresh and revoke.**
+**Refresh and revoke.** `connection` below is your stored record for this user: tokens, expiry, workspace id.
 
 ```ruby
-client.oauth.refresh(refresh_token: stored_refresh_token, client_id: client_id)
+tokens = Assinafy::Client.new.oauth.refresh(
+  refresh_token: connection.refresh_token,
+  client_id:     ENV.fetch('ASSINAFY_CLIENT_ID')
+)
 
-client.oauth.revoke(
-  token: stored_refresh_token, client_id: client_id, token_type_hint: 'refresh_token'
+# The refresh token just sent is retired: store the new tokens before anything else.
+connection.update!(
+  refresh_token: tokens.fetch('refresh_token'),
+  access_token:  tokens.fetch('access_token'),
+  expires_at:    Time.now + tokens.fetch('expires_in')
 )
+user_client = Assinafy::Client.new(token: connection.access_token, account_id: connection.workspace_id)
 ```
 
-A refresh token exists only when `offline_access` was requested *and* consented. Revoking a refresh token also
-invalidates the access tokens issued from it. Every revoke outcome returns `200` — including an unknown or
-already-revoked token — so the endpoint cannot be used to probe whether a token exists.
+When a user disconnects, revoke the refresh token in storage **now** — the latest one — then delete the stored
+tokens:
 
-> The SDK does **not** refresh automatically. Persist `expires_in`, refresh before expiry, and treat
-> `invalid_grant` as a signal to restart the authorization flow.
+```ruby
+Assinafy::Client.new.oauth.revoke(
+  token:           connection.reload.refresh_token,
+  client_id:       ENV.fetch('ASSINAFY_CLIENT_ID'),
+  token_type_hint: 'refresh_token'
+)
+connection.destroy!
+```
+
+A refresh token exists only when `offline_access` was requested *and* consented. Revoking a refresh token also
+invalidates the access tokens issued from it. Every revoke outcome returns `200` — including an unknown,
+already-revoked, or rotated token — so the endpoint cannot be used to probe whether a token exists, and revoking
+a stale copy can look successful while the connection stays active.
+
+> The SDK does **not** refresh automatically. Persist `expires_in` and refresh before expiry. Every refresh
+> returns a **new** refresh token, valid for another 30 days, and retires the old one, so a connection only
+> expires after 30 days without a refresh. Reusing a retired refresh token ends the whole connection: store the
+> new tokens before using them, and refresh one at a time per connection. `refresh` raises `Assinafy::Error`
+> rather than return a success without a new refresh token; handle it like `invalid_grant`.
+>
+> The SDK sends each token request once. If a refresh fails without a clear answer — a timeout, a reset
+> connection, a `5xx` — the server may have rotated the token without the response reaching you. Re-read the
+> stored refresh token: if it is still the one you sent, **never send it again**; ask the user to connect again.
+> Carry on only if another worker has since stored a different one. Only a failure that provably happened before
+> the request was sent — DNS resolution, a refused connection, a failed TLS handshake — is safe to retry. On an
+> API `401`, refresh once; if that fails, or on `invalid_grant`, ask the user to connect again.
 
 **Discovery**, instead of hardcoding endpoints:
 
@@ -241,6 +280,10 @@ rescue Assinafy::OAuthError => e
   e.context[:www_authenticate] # on a 403, names the missing scope
 ```
 
+Any resource, not only these routes, puts that challenge in `context[:www_authenticate]`. Treat it as a prompt to
+reconnect with that scope added, not as a retry; a `403` without it means another workspace, the user's role, or
+an area OAuth tokens never reach.
+
 ### Accounts
 
 ```ruby
@@ -760,11 +803,11 @@ result[:signer_ids] # => ['<sid-1>', '<sid-2>']
 The SDK raises one of:
 
 - `Assinafy::ValidationError` — caller-side input invalid (missing IDs, bad email, etc.).
-- `Assinafy::ApiError` — the API returned a non-2xx status. Includes `status_code` and `response_data`.
+- `Assinafy::ApiError` — the API returned a non-2xx status. Includes `status_code` and `response_data`; on a
+  `403`, `context[:www_authenticate]` names the scope an OAuth token is missing.
 - `Assinafy::OAuthError` — an OAuth endpoint failed. Subclasses `ApiError`, and adds `error` and
-  `error_description` from the flat RFC 6749 body; on a `403`, `context[:www_authenticate]` names the missing
-  scope.
-- `Assinafy::NetworkError` — Faraday connection error or timeout.
+  `error_description` from the flat RFC 6749 body.
+- `Assinafy::NetworkError` — Faraday connection error, timeout, or TLS failure.
 - `Assinafy::Error` — base class; other unexpected errors get wrapped here with the operation label.
 
 All inherit a `#context` Hash with debugging metadata.

data/README.md

@@ -411,8 +411,9 @@ credenciais ou superfícies administrativas — independentemente do escopo.
 verificador = Assinafy::OAuth.generate_code_verifier
 state       = Assinafy::OAuth.generate_state
 
-session[:assinafy_code_verifier] = verificador   # guarde os dois na sessão
+session[:assinafy_code_verifier] = verificador   # guarde os três na sessão
 session[:assinafy_state]         = state
+session[:assinafy_issuer]        = Assinafy::OAuth::AUTHORIZATION_SERVER # emissor do servidor usado nesta tentativa
 
 redirect_to Assinafy::OAuth.authorization_url(
   client_id:     ENV.fetch('ASSINAFY_CLIENT_ID'),
@@ -424,11 +425,18 @@ redirect_to Assinafy::OAuth.authorization_url(
 ```
 
 O `code_challenge` é derivado do verificador (`S256`) — o verificador em si nunca vai para a URL.
+`Assinafy::OAuth::AUTHORIZATION_SERVER` é o emissor de produção. O sandbox tem o seu: passe
+`authorization_endpoint: 'https://auth-sandbox.assinafy.com.br/oauth/authorize'` e guarde
+`https://auth-sandbox.assinafy.com.br`.
 
 ### Passo 2 — trocar o código por tokens
 
 ```ruby
-raise 'state divergente' unless params[:state] == session.delete(:assinafy_state)
+unless params[:state] == session.delete(:assinafy_state) &&
+       params[:iss] == session.delete(:assinafy_issuer)
+  raise 'resposta de autorização inválida'
+end
+raise "autorização não concedida: #{params[:error]}" if params[:error] # access_denied, invalid_scope, ...
 
 tokens = Assinafy::Client.new.oauth.exchange_code(
   code:          params.fetch(:code),
@@ -443,41 +451,74 @@ tokens['refresh_token']  # => presente apenas com offline_access
 tokens['scope']          # => "documents:read documents:write"
 ```
 
-Compare o `state` **antes** de trocar o código — é a proteção contra CSRF.
+Confira `state` e `iss` contra os valores guardados nesta tentativa **antes de qualquer outra
+coisa**, inclusive num retorno com `error=` — é a proteção contra CSRF e contra respostas que não
+são suas. O código vale uma vez e expira 60
+segundos depois da aprovação: troque-o na hora, sem repetir.
 
 ### Passo 3 — agir como o usuário
 
 ```ruby
-usuario = Assinafy::Client.new(
-  token:      tokens.fetch('access_token'),
-  account_id: ENV.fetch('ASSINAFY_ACCOUNT_ID')
-)
+access_token = tokens.fetch('access_token')
+
+# O token só vale na workspace que o usuário escolheu; guarde o id junto dos tokens.
+workspace_id = Assinafy::Client.new(token: access_token).accounts.list[:data].first.fetch('id')
 
+usuario = Assinafy::Client.new(token: access_token, account_id: workspace_id)
 usuario.documents.list
 usuario.oauth.userinfo  # => { 'sub' => ..., 'name' => ..., 'email' => ... }
 ```
 
 ### Renovar e revogar
 
+`conexao` abaixo é o registro que você guarda para o usuário: tokens, validade e id da workspace.
+
 ```ruby
-novos = client.oauth.refresh(
-  refresh_token: refresh_token_guardado,
+novos = Assinafy::Client.new.oauth.refresh(
+  refresh_token: conexao.refresh_token,
   client_id:     ENV.fetch('ASSINAFY_CLIENT_ID')
 )
 
-client.oauth.revoke(
-  token:           refresh_token_guardado,
+# O refresh token enviado foi aposentado: guarde os tokens novos antes de qualquer outra coisa.
+conexao.update!(
+  refresh_token: novos.fetch('refresh_token'),
+  access_token:  novos.fetch('access_token'),
+  expires_at:    Time.now + novos.fetch('expires_in')
+)
+usuario = Assinafy::Client.new(token: conexao.access_token, account_id: conexao.workspace_id)
+```
+
+Quando o usuário desconectar, revogue o refresh token guardado **agora** — o mais recente — e só
+depois apague os tokens:
+
+```ruby
+Assinafy::Client.new.oauth.revoke(
+  token:           conexao.reload.refresh_token,
   client_id:       ENV.fetch('ASSINAFY_CLIENT_ID'),
   token_type_hint: 'refresh_token'
 )
+conexao.destroy!
 ```
 
 Sem `offline_access` não há refresh token: quando o access token expirar, mande o usuário pelo
 fluxo de autorização de novo. Revogar um refresh token invalida também os access tokens emitidos
-a partir dele.
-
-> O SDK **não renova o token automaticamente**. Guarde `expires_in`, renove antes de expirar, e
-> trate `invalid_grant` reiniciando o fluxo de autorização.
+a partir dele. A revogação responde `200` inclusive para um token já aposentado, então revogar uma
+cópia antiga parece dar certo enquanto a conexão continua ativa.
+
+> O SDK **não renova o token automaticamente**. Guarde `expires_in` e renove antes de expirar.
+> Cada renovação devolve um refresh token **novo**, válido por mais 30 dias, e aposenta o
+> anterior: a conexão só expira se passar 30 dias sem renovar. Reutilizar um refresh token
+> aposentado encerra a conexão inteira, então guarde os tokens novos antes de usá-los e faça uma
+> renovação por vez por conexão. `refresh` levanta `Assinafy::Error` em vez de devolver um
+> sucesso sem refresh token novo; trate como `invalid_grant`.
+>
+> O SDK envia cada pedido de token uma única vez. Se a renovação falhar sem resposta clara —
+> timeout, conexão interrompida, `5xx` —, o servidor pode ter trocado o token sem que a resposta
+> chegasse. Releia o refresh token guardado: se ainda for o que você enviou, **nunca o reenvie**;
+> peça ao usuário para conectar de novo. Siga em frente só se outro processo já tiver guardado um
+> token diferente. Só é seguro repetir uma falha que comprovadamente aconteceu antes do envio:
+> DNS, conexão recusada, handshake TLS. Num `401` da API, renove uma vez; se falhar, ou em
+> `invalid_grant`, peça ao usuário para conectar de novo.
 
 ### Descoberta
 
@@ -507,7 +548,10 @@ rescue Assinafy::OAuthError => e
 end
 ```
 
-Num `403`, `e.context[:www_authenticate]` traz o desafio que **nomeia o escopo faltante**.
+Num `403` de qualquer recurso, `e.context[:www_authenticate]` traz o desafio que **nomeia o escopo
+faltante**: peça ao usuário para conectar de novo incluindo esse escopo, sem repetir a chamada. Um
+`403` sem esse desafio indica outra workspace, o papel do usuário ou uma área que tokens OAuth não
+alcançam.
 
 ---
 
@@ -786,8 +830,9 @@ cadeia de certificação.
 | Sandbox | `https://sandbox.assinafy.com.br/v1` |
 
 O sandbox é gratuito e espelha a produção 1 para 1 — mesmas rotas, mesmos contratos, incluindo
-OAuth 2.1 e certificado digital. Troque apenas a `base_url` para testar a integração de ponta a
-ponta antes de ir para produção.
+OAuth 2.1 e certificado digital. Troque apenas a `base_url` — e, no OAuth, o servidor de
+autorização (`https://auth-sandbox.assinafy.com.br`) — para testar a integração de ponta a ponta
+antes de ir para produção.
 
 ---
 

data/docs/API_REFERENCE.md

@@ -1,7 +1,7 @@
 # Assinafy Ruby SDK API Reference
 
-> Contract source: Assinafy API v1 OpenAPI 3.0.0, retrieved 2026-08-26 from
-> `https://api.assinafy.com.br/v1/docs/openapi.json` (67 paths, 89 operations, 39 schemas).
+> Contract source: Assinafy API v1 OpenAPI 3.0.0, retrieved 2026-09-25 from
+> `https://api.assinafy.com.br/v1/docs/openapi.json` (71 paths, 93 operations, 39 schemas).
 > `scripts/check_api_contract.rb` validates contract compatibility weekly.
 
 This is the SDK-facing contract reference. Paths below are wire paths; Ruby methods return the unwrapped
@@ -21,12 +21,15 @@ Required parameters and object properties are marked with `*`.
   `client.oauth` covers the token lifecycle. A token is scoped to one workspace and carries only the scopes the
   user approved, and it never reaches billing, account lifecycle, credential management, or admin surfaces
   regardless of scope. A missing scope answers `403` with a `WWW-Authenticate` challenge naming it, which the
-  SDK exposes as `OAuthError#context[:www_authenticate]`. Store the `code_verifier` and `state` per user session,
-  compare `state` on the callback before exchanging the code, and keep refresh tokens out of logs.
+  SDK exposes as `ApiError#context[:www_authenticate]` on every resource: reconnect with that scope added rather
+  than retrying. Store the `code_verifier`, `state`, and expected issuer with each authorization attempt — the
+  issuer of the authorization server it uses: `https://auth.assinafy.com.br` in production,
+  `https://auth-sandbox.assinafy.com.br` in the sandbox. Check `state` and `iss` against those stored values on
+  the callback before anything else, including an `error=` return, and keep refresh tokens out of logs.
 - Signer-facing operations use the one-time `signer-access-code` query parameter where shown. Never log, commit,
   or place API keys, bearer tokens, signer codes, or real recipient addresses in examples or fixtures.
-- HTTP connections use Ruby/Faraday TLS verification and the host system trust store; the SDK does not pin the
-  upstream TLS certificate.
+- HTTP connections require TLS 1.2 or newer and use Ruby/Faraday TLS verification and the host system trust store;
+  the SDK does not pin the upstream TLS certificate.
 - `DocumentResource#verify` reports Assinafy upstream verification data. It does not independently validate a PDF
   signature, certificate chain, OCSP/CRL status, or legal validity. The API artifact name `certificated` is not an
   additional local guarantee.
@@ -103,8 +106,8 @@ Required parameters and object properties are marked with `*`.
 | GET | `/v1/documents/{documentSignatureHash}/verify` | `DocumentResource#verify` | Public | path `documentSignatureHash*`: string | None | `200` `application/json` [`Envelope`](#envelope) plus object { `data`: [`DocumentVerification`](#documentverification) } |
 | GET | `/v1/field-types` | `FieldResource#types` | Bearer token or `X-Api-Key` | None | None | `200` `application/json` [`Envelope`](#envelope) plus object { `data`: Array<[`FieldType`](#fieldtype)> } |
 | POST | `/v1/login` | `AuthResource#login` | Public | None | required; `application/json` object { `email*`: string (email); `password*`: string (password) } | `200` `application/json` [`Envelope`](#envelope) plus object { `data`: [`AuthSession`](#authsession) } |
-| POST | `/v1/oauth/token` | `OAuthResource#token`, `#exchange_code`, `#refresh` | Public (client authenticates with `client_id` in the body) | None | required; `application/json` object { `grant_type*`: string enum `authorization_code`, `refresh_token`; `client_id*`: string; `code`: string; `redirect_uri`: string (uri); `code_verifier`: string; `refresh_token`: string; `client_secret`: string; `resource`: string (uri) } | `200` `application/json` **flat** object { `access_token`: string; `token_type`: string; `expires_in`: integer; `refresh_token`: string (nullable); `scope`: string; `id_token`: string (nullable) } — not enveloped |
-| POST | `/v1/oauth/revoke` | `OAuthResource#revoke` | Public (client authenticates with `client_id` in the body) | None | required; `application/json` object { `token*`: string; `client_id*`: string; `token_type_hint`: string enum `access_token`, `refresh_token`; `client_secret`: string } | `200` empty body — every token outcome reports success |
+| POST | `/v1/oauth/token` | `OAuthResource#token`, `#exchange_code`, `#refresh` | Public (client authenticates with `client_id` in the body) | None | required; `application/x-www-form-urlencoded` (RFC 6749; the contract lists `application/json`) object { `grant_type*`: string enum `authorization_code`, `refresh_token`; `client_id*`: string; `code`: string; `redirect_uri`: string (uri); `code_verifier`: string; `refresh_token`: string; `client_secret`: string; `resource`: string (uri) } | `200` `application/json` **flat** object { `access_token`: string; `token_type`: string; `expires_in`: integer; `refresh_token`: string (nullable); `scope`: string; `id_token`: string (nullable) } — not enveloped |
+| POST | `/v1/oauth/revoke` | `OAuthResource#revoke` | Public (client authenticates with `client_id` in the body) | None | required; `application/x-www-form-urlencoded` (RFC 7009; the contract lists `application/json`) object { `token*`: string; `client_id*`: string; `token_type_hint`: string enum `access_token`, `refresh_token`; `client_secret`: string } | `200` empty body — every token outcome reports success |
 | GET | `/v1/oauth/userinfo` | `OAuthResource#userinfo` | Bearer token or `X-Api-Key`; requires the `openid` scope | None | None | `200` `application/json` **flat** object { `sub`: string; `name`: string (nullable); `email`: string (email, nullable); `email_verified`: boolean (nullable) } — not enveloped |
 | GET | `/v1/public/documents/{documentId}` | `DocumentResource#public_info` | Public | path `documentId*`: string | None | `200` `application/json` [`Envelope`](#envelope) plus object { `data`: [`Document`](#document) } |
 | PUT | `/v1/public/documents/{documentId}/send-token` | `DocumentResource#send_token` | Public | path `documentId*`: string | optional; `application/json` object { `email`: string (email) } | `200` `application/json` [`Envelope`](#envelope) |
@@ -167,7 +170,8 @@ raise `Assinafy::ApiError`:
 - `message` uses the API's `message`, `error`, or `name` value.
 - `response_data` preserves the parsed response body.
 - `error_name` and `error_code` expose framework `name` and `code` values when present.
-- `context` contains `status_code` and `response_data` for structured logging or support diagnostics.
+- `context` contains `status_code` and `response_data` for structured logging or support diagnostics, plus
+  `www_authenticate` when the response carries that header.
 
 Transport, timeout, and TLS failures raise `Assinafy::NetworkError`; caller-side validation failures raise
 `Assinafy::ValidationError` before a request is sent.
@@ -228,10 +232,28 @@ that `base_url` carries.
 
 ### Token refresh
 
-The SDK does not refresh access tokens automatically. Persist `expires_in` alongside the token,
-call `OAuthResource#refresh` before expiry, and treat `invalid_grant` as a signal to restart the
-authorization flow. A refresh token is issued only when `offline_access` was both requested and
-consented.
+The SDK does not refresh access tokens automatically. Persist `expires_in` alongside the token and
+call `OAuthResource#refresh` before expiry. A refresh token is issued only when `offline_access` was
+both requested and consented.
+
+Every refresh returns a new refresh token, valid for another 30 days, and retires the one sent, so a
+connection only expires after 30 days without a refresh. Reusing a retired refresh token ends the
+whole connection. Store the new refresh and access tokens before using either, rebuild the client with
+the new access token, and run one refresh at a time per connection. `OAuthResource#refresh`, and
+`#token` with the `refresh_token` grant, raise `Assinafy::Error` rather than return a success whose
+`refresh_token` is missing, blank, or the one sent; handle that like `invalid_grant`.
+
+The SDK never retries token requests; do not add middleware that does. After an ambiguous failure — a
+timeout, a reset connection, a `5xx` — the server may have rotated the token without the response
+arriving. Re-read the stored refresh token: if it is still the one you sent, never send it again; ask
+the user to connect again. Proceed only if another worker has since stored a different one. Only a
+failure that provably happened before the request was sent (DNS resolution, a refused connection, a
+failed TLS handshake) is safe to retry. On an API `401`, refresh once; if that fails, or on
+`invalid_grant`, ask the user to connect again.
+
+When a user disconnects, revoke the refresh token in storage at that moment with `OAuthResource#revoke`,
+then delete the stored tokens. Revoking a rotated token also answers `200`, so revoking a stale copy can
+look successful while the connection stays active.
 
 ### Digital-certificate signing
 
@@ -530,6 +552,7 @@ The verification result for a document looked up by signature hash. When not ver
 | --- | --- | --- | --- | --- |
 | `hash` | string | No | No | — |
 | `id` | string | No | Yes | — |
+| `agreement_code` | string | No | Yes | Agreement code printed on the document certificate. |
 | `status` | string | No | Yes | — |
 | `page_count` | string | No | Yes | — |
 | `signer_count` | string | No | Yes | — |

data/lib/assinafy/client.rb

@@ -241,6 +241,10 @@ module Assinafy
     # Expose the underlying Faraday connection (for advanced use cases,
     # such as adding middleware or inspecting headers in tests).
     #
+    # OAuth token requests share this connection: never add middleware that
+    # retries `POST /oauth/token`. A retried refresh resends a refresh token the
+    # first attempt may already have retired, which ends the user's connection.
+    #
     # @return [Faraday::Connection]
     #
     # @example Inspect the auth header the SDK sends

data/lib/assinafy/oauth.rb

@@ -15,11 +15,13 @@ module Assinafy
   # helpers exist so an integration never hand-rolls the S256 transform.
   #
   # @example Full authorization-code flow with PKCE
-  #   # 1. Before redirecting, mint and store a verifier for this user session.
+  #   # 1. Before redirecting, mint and store a verifier and state for this
+  #   #    attempt, with the issuer of the authorization server it uses.
   #   verifier = Assinafy::OAuth.generate_code_verifier
   #   state    = Assinafy::OAuth.generate_state
   #   session[:assinafy_code_verifier] = verifier
   #   session[:assinafy_state]         = state
+  #   session[:assinafy_issuer]        = Assinafy::OAuth::AUTHORIZATION_SERVER
   #
   #   # 2. Send the user to the authorization server.
   #   redirect_to Assinafy::OAuth.authorization_url(
@@ -34,13 +36,17 @@ module Assinafy
   #   #     &scope=documents%3Aread+documents%3Awrite+offline_access&state=...
   #   #     &code_challenge=...&code_challenge_method=S256"
   #
-  #   # 3. On the callback, compare `state`, then exchange the code
-  #   #    (see Resources::OAuthResource#exchange_code).
+  #   # 3. On the callback, before anything else (an `error=` return
+  #   #    included), check `state` and `iss` against the values stored for
+  #   #    this attempt; stop if either differs. Then exchange the code (see
+  #   #    Resources::OAuthResource#exchange_code).
   #
   # @see https://api.assinafy.com.br/v1/docs
   module OAuth
-    # Authorization server that owns the browser-facing flow. Published by
-    # `GET /.well-known/oauth-protected-resource` as `authorization_servers[0]`.
+    # Production authorization server, which owns the browser-facing flow.
+    # Published by `GET /.well-known/oauth-protected-resource` as
+    # `authorization_servers[0]`, and the `iss` its callbacks carry. The
+    # sandbox publishes its own, `https://auth-sandbox.assinafy.com.br`.
     AUTHORIZATION_SERVER = 'https://auth.assinafy.com.br'
 
     # RFC 8414 discovery document for {AUTHORIZATION_SERVER}.
@@ -151,7 +157,8 @@ module Assinafy
       # @param resource       [String, nil] RFC 8707 resource indicator; when sent
       #   here it must also be sent to the token endpoint, and must be the
       #   `resource` published by `/.well-known/oauth-protected-resource`
-      # @param authorization_endpoint [String] override for a non-default server
+      # @param authorization_endpoint [String] override for a non-default
+      #   server; store that server's issuer for the callback's `iss` check
       # @param extra_params   [Hash] additional query parameters, merged last
       # @return [String] the absolute URL to redirect to
       # @raise [ValidationError] on a missing client_id/redirect_uri, an invalid

data/lib/assinafy/resources/base_resource.rb

@@ -177,6 +177,17 @@ module Assinafy
         end
       end
 
+      # RFC 6749 §4.1.3/§6 and RFC 7009 §2.1 define token and revocation
+      # requests as form posts. The connection's JSON and multipart middleware
+      # leave a pre-encoded String body alone.
+      def http_post_form(path, form, workspace_auth: true)
+        @connection.post(path) do |request|
+          prepare_request(request, {}, workspace_auth: workspace_auth)
+          request.headers['Content-Type'] = 'application/x-www-form-urlencoded'
+          request.body = URI.encode_www_form(form)
+        end
+      end
+
       def http_put(path, body = nil, params = {}, workspace_auth: true)
         @connection.put(path) do |request|
           prepare_request(request, params, workspace_auth: workspace_auth)
@@ -204,7 +215,7 @@ module Assinafy
       end
 
       def call(label)
-        Utils.handle_assinafy_response(request(label) { yield }.body)
+        unwrap(request(label) { yield })
       end
 
       def call_optional(label)
@@ -223,7 +234,7 @@ module Assinafy
       def call_binary(label)
         response = request(label) { yield }
         body = response.body
-        body = Utils.handle_assinafy_response(body) if body.is_a?(Hash)
+        body = unwrap(response) if body.is_a?(Hash)
         content_type = response.headers&.[]('content-type').to_s.downcase
 
         if body.is_a?(String) && !body.empty? && !textual_content_type?(content_type)
@@ -235,7 +246,7 @@ module Assinafy
 
       def call_array(label)
         response = request(label) { yield }
-        body = Utils.handle_assinafy_response(response.body)
+        body = unwrap(response)
         return body if body.is_a?(Array)
 
         raise unexpected_response(label, 'an Array data payload', response, body)
@@ -243,7 +254,7 @@ module Assinafy
 
       def call_list(label)
         response = request(label) { yield }
-        body     = Utils.handle_assinafy_response(response.body)
+        body     = unwrap(response)
         # @type var result: Assinafy::list_result
         result   = { data: extract_list_data(body, label, response) }
         meta     = parse_pagination_meta(response.headers)
@@ -268,10 +279,30 @@ module Assinafy
         raise Assinafy::Error.new("#{label}: #{e.message}", { cause: e.class.name })
       end
 
+      # On a `403` the `WWW-Authenticate` challenge names the scope an OAuth
+      # token is missing, which tells "reconnect with more scope" apart from
+      # "wrong workspace or role", so it travels with the error.
       def check_status!(response, _label)
         return if (200..299).cover?(response.status)
 
-        raise ApiError.from_response(response.status, response.body)
+        raise with_challenge(error_class.from_response(response.status, response.body), response)
+      end
+
+      # A 2xx envelope can still carry an error status, with the same challenge.
+      def unwrap(response)
+        Utils.handle_assinafy_response(response.body)
+      rescue ApiError => e
+        raise with_challenge(e, response)
+      end
+
+      def with_challenge(error, response)
+        challenge = response.headers&.[]('www-authenticate')
+        error.context[:www_authenticate] = challenge if challenge
+        error
+      end
+
+      def error_class
+        ApiError
       end
 
       def extract_list_data(body, label, response)

data/lib/assinafy/resources/document_resource.rb

@@ -573,6 +573,7 @@ module Assinafy
       #   {
       #     'hash' => 'FE32EDDADE7CBDDCBB934E7402047450B0E59C02',
       #     'id' => '63ddb172402799bfc991d10d',
+      #     'agreement_code' => '550E8400-E29B-41D4-A716-446655440000', # printed on the certificate
       #     'status' => 'certificated',
       #     'page_count' => '1',
       #     'signer_count' => '1',
@@ -582,8 +583,8 @@ module Assinafy
       #     'is_valid' => true,
       #     'message' => ''
       #   }
-      #   # Not verified: { 'hash' => 'INVALIDHASHEXAMPLE', 'id' => nil, 'status' => nil,
-      #   #   'is_valid' => false, 'message' => 'Document not signed or not found.', ... }
+      #   # Not verified: { 'hash' => 'INVALIDHASHEXAMPLE', 'id' => nil, 'agreement_code' => nil,
+      #   #   'status' => nil, 'is_valid' => false, 'message' => 'Document not signed or not found.', ... }
       def verify(hash)
         h = require_id(hash, 'Signature hash')
 

data/lib/assinafy/resources/oauth_resource.rb

@@ -18,15 +18,19 @@ module Assinafy
     #    `{status, data, message}`. These methods return the body as-is.
     # 2. **No workspace credentials.** `/oauth/token` and `/oauth/revoke` are
     #    unauthenticated routes that identify the client through `client_id` in
-    #    the body, so the SDK strips `X-Api-Key`/`Authorization` from them.
+    #    the body, so the SDK strips `X-Api-Key`/`Authorization` from them and
+    #    posts that body form-encoded, as RFC 6749 and RFC 7009 define it.
     # 3. **OAuth-shaped errors.** A failure raises {Assinafy::OAuthError}, which
     #    carries `error` and `error_description` separately.
     #
     # An OAuth access token never reaches billing, account lifecycle, credential
     # management or admin surfaces, whatever scopes it holds. A request missing
     # a scope answers `403` with `WWW-Authenticate: Bearer
-    # error="insufficient_scope"` naming it; the SDK puts that header in
-    # {Assinafy::Error#context} under `:www_authenticate`.
+    # error="insufficient_scope"` naming it; on every resource, the SDK puts
+    # that header in {Assinafy::Error#context} under `:www_authenticate`. Treat
+    # it as a prompt to reconnect with that scope added, not as a retry; a `403`
+    # without it means another workspace, the user's role, or an area OAuth
+    # tokens never reach.
     #
     # @example End-to-end: exchange a callback code, then act as the user
     #   tokens = Assinafy::Client.new.oauth.exchange_code(
@@ -35,11 +39,13 @@ module Assinafy
     #     code_verifier: session.delete(:assinafy_code_verifier),
     #     redirect_uri:  'https://app.example.com/oauth/callback'
     #   )
+    #   access_token = tokens.fetch('access_token')
     #
-    #   user_client = Assinafy::Client.new(
-    #     token:      tokens.fetch('access_token'),
-    #     account_id: ENV.fetch('ASSINAFY_ACCOUNT_ID')
-    #   )
+    #   # The token works only in the workspace the user picked; store its id
+    #   # next to the tokens.
+    #   workspace_id = Assinafy::Client.new(token: access_token).accounts.list[:data].first.fetch('id')
+    #
+    #   user_client = Assinafy::Client.new(token: access_token, account_id: workspace_id)
     #   user_client.documents.list
     #
     # @see Assinafy::OAuth
@@ -59,11 +65,14 @@ module Assinafy
       # Exchange an authorization code for tokens (RFC 6749 §4.1.3 + PKCE).
       #
       # Call this on your OAuth callback, after checking that the returned
-      # `state` matches the one you stored. `code_verifier` must be the exact
-      # value whose challenge was sent to
-      # {Assinafy::OAuth.authorization_url} — the SDK validates its grammar
-      # locally, because the server reports a malformed verifier as
-      # `invalid_grant`, indistinguishable from an expired code.
+      # `state` and `iss` match the values you stored for this authorization
+      # attempt (`iss` is the issuer of the authorization server it used,
+      # {Assinafy::OAuth::AUTHORIZATION_SERVER} in production). The code is
+      # single-use and expires 60 seconds after approval: exchange it at once,
+      # and never retry. `code_verifier` must be the exact value whose
+      # challenge was sent to {Assinafy::OAuth.authorization_url} — the SDK
+      # validates its grammar locally, because the server reports a malformed
+      # verifier as `invalid_grant`, indistinguishable from an expired code.
       #
       # @param code          [String] the `code` query parameter from the callback
       # @param client_id     [String] the registered client identifier
@@ -89,14 +98,13 @@ module Assinafy
       #     redirect_uri:  'https://app.example.com/oauth/callback'
       #   )
       #
-      #   # Request body sent by the SDK (no X-Api-Key/Authorization header):
-      #   #   {
-      #   #     "grant_type":    "authorization_code",
-      #   #     "client_id":     "client-id",
-      #   #     "code":          "authorization-code-from-callback",
-      #   #     "code_verifier": "<43-128 unreserved characters>",
-      #   #     "redirect_uri":  "https://app.example.com/oauth/callback"
-      #   #   }
+      #   # Request body sent by the SDK, application/x-www-form-urlencoded
+      #   # (no X-Api-Key/Authorization header):
+      #   #   grant_type=authorization_code
+      #   #   client_id=client-id
+      #   #   code=authorization-code-from-callback
+      #   #   code_verifier=<43-128 unreserved characters>
+      #   #   redirect_uri=https://app.example.com/oauth/callback
       #   #
       #   # Response (flat, NOT enveloped):
       #   # {
@@ -126,22 +134,45 @@ module Assinafy
       # consented. Without one, send the user through the authorization flow
       # again once the access token expires.
       #
-      # @param refresh_token [String] issued alongside a previous access token
+      # Every refresh returns a new refresh token, valid for another 30 days,
+      # and retires the one sent, so a connection ends only after 30 days
+      # without a refresh. Reusing a retired refresh token ends the whole
+      # connection. Store the new refresh and access tokens before using
+      # either, and run one refresh at a time per connection.
+      #
+      # The SDK sends this request once and never retries it. After an
+      # ambiguous failure (a timeout, a reset connection, a 5xx) the server may
+      # have rotated the token without the response arriving: re-read the
+      # stored token, and if it is still the one sent, never send it again —
+      # ask the user to connect again. Proceed only if another worker has since
+      # stored a different one. Only a failure that provably happened before
+      # sending (DNS, a refused connection, a failed TLS handshake) is safe to
+      # retry.
+      #
+      # @param refresh_token [String] the most recently issued refresh token
       # @param client_id     [String] the registered client identifier
       # @param client_secret [String, nil] confidential clients only
-      # @param resource      [String, nil] RFC 8707 resource indicator
-      # @return [Hash{String=>Object}] the flat token response
+      # @param resource      [String, nil] RFC 8707 resource indicator; may repeat
+      #   the value sent when authorizing, never change it (`invalid_target`)
+      # @return [Hash{String=>Object}] the flat token response, always with a
+      #   new `refresh_token`
       # @raise [Assinafy::OAuthError] `invalid_grant` when the refresh token is
-      #   unknown, revoked, or its authorization no longer includes `offline_access`
+      #   unknown, already used, expired, or revoked, or the user approved the
+      #   app again with different permissions: the connection is over, so ask
+      #   the user to connect again instead of retrying
+      # @raise [Assinafy::Error] when a success carries no new refresh token
+      #   (missing, blank, or the one sent): the one sent may already be
+      #   retired, so handle it like `invalid_grant`
       #
       # @see POST /oauth/token
       #
       # @example Request and response
       #   client.oauth.refresh(refresh_token: stored_refresh_token, client_id: 'client-id')
       #
-      #   # Request body sent by the SDK:
-      #   #   { "grant_type": "refresh_token", "client_id": "client-id",
-      #   #     "refresh_token": "refresh-token-placeholder" }
+      #   # Request body sent by the SDK, application/x-www-form-urlencoded:
+      #   #   grant_type=refresh_token
+      #   #   client_id=client-id
+      #   #   refresh_token=refresh-token-placeholder
       #   #
       #   # Response (flat, NOT enveloped):
       #   # {
@@ -164,13 +195,17 @@ module Assinafy
       # Call the token endpoint directly.
       #
       # {#exchange_code} and {#refresh} cover both supported grants; reach for
-      # this only to send a parameter they do not model.
+      # this only to send a parameter they do not model. The `refresh_token`
+      # grant gets the same rotation check, and the same retry rules, as
+      # {#refresh}.
       #
       # @param grant_type [String] `"authorization_code"` or `"refresh_token"`
       # @param client_id  [String] the registered client identifier
       # @param params     [Hash] additional body parameters; nil values are dropped
       # @return [Hash{String=>Object}] the flat token response
       # @raise [Assinafy::OAuthError] on any non-2xx response
+      # @raise [Assinafy::Error] when a `refresh_token` grant succeeds without a
+      #   new refresh token
       # @raise [Assinafy::ValidationError] on an unsupported `grant_type`
       #
       # @see POST /oauth/token
@@ -180,21 +215,26 @@ module Assinafy
           raise ValidationError.new("Grant type must be one of: #{GRANT_TYPES.join(', ')}", { grant_type: grant_type })
         end
 
-        body = body_params(params.merge(grant_type: grant, client_id: require_string(client_id, 'Client ID')))
+        body  = body_params(params.merge(grant_type: grant, client_id: require_string(client_id, 'Client ID')))
+        label = 'Failed to exchange OAuth token'
 
         @logger.info("Requesting OAuth token (#{grant})")
-        call('Failed to exchange OAuth token') do
-          http_post('oauth/token', body, {}, workspace_auth: false)
-        end
+        response = request(label) { http_post_form('oauth/token', body, workspace_auth: false) }
+        tokens   = unwrap(response)
+        return tokens if grant != 'refresh_token' || rotated?(tokens, body['refresh_token'])
+
+        raise unexpected_response(label, 'a new refresh token', response, tokens)
       end
 
       # Revoke an access or refresh token (RFC 7009).
       #
-      # Revoking a refresh token also invalidates the access tokens issued from
-      # it. Every token outcome answers `200` — including a token that is
-      # unknown, already revoked, or malformed — so the endpoint cannot be used
-      # to probe whether a token exists. Only failed client authentication
-      # raises.
+      # Call it when a user disconnects, with the refresh token in storage at
+      # that moment, then delete the stored tokens. Revoking a refresh token
+      # also invalidates the access tokens issued from it. Every token outcome
+      # answers `200` — including a token that is unknown, already revoked or
+      # rotated, or malformed — so the endpoint cannot be used to probe whether
+      # a token exists, and revoking a stale copy can look successful while the
+      # connection stays active. Only failed client authentication raises.
       #
       # @param token           [String] the access or refresh token to revoke
       # @param client_id       [String] the registered client identifier
@@ -212,9 +252,11 @@ module Assinafy
       #     token_type_hint: 'refresh_token'
       #   )
       #
-      #   # Request body sent by the SDK (no X-Api-Key/Authorization header):
-      #   #   { "token": "refresh-token-placeholder", "client_id": "client-id",
-      #   #     "token_type_hint": "refresh_token" }
+      #   # Request body sent by the SDK, application/x-www-form-urlencoded
+      #   # (no X-Api-Key/Authorization header):
+      #   #   token=refresh-token-placeholder
+      #   #   client_id=client-id
+      #   #   token_type_hint=refresh_token
       #   #
       #   # Response: HTTP 200, empty body
       #   # => nil
@@ -235,7 +277,7 @@ module Assinafy
 
         @logger.info('Revoking OAuth token')
         call_void('Failed to revoke OAuth token') do
-          http_post('oauth/revoke', body, {}, workspace_auth: false)
+          http_post_form('oauth/revoke', body, workspace_auth: false)
         end
       end
 
@@ -355,15 +397,17 @@ module Assinafy
 
       # OAuth routes report failures as RFC 6749 error objects rather than this
       # API's envelope, so they raise {OAuthError} (an {ApiError}, so existing
-      # `rescue Assinafy::ApiError` handlers keep working). The
-      # `WWW-Authenticate` challenge is carried along because on a 403 it names
-      # the scope that was missing.
-      def check_status!(response, _label)
-        return if (200..299).cover?(response.status)
+      # `rescue Assinafy::ApiError` handlers keep working).
+      def error_class
+        OAuthError
+      end
 
-        error = OAuthError.from_response(response.status, response.body)
-        error.context[:www_authenticate] = response.headers&.[]('www-authenticate')
-        raise error
+      # A refresh retires the refresh token it sends. A success without a
+      # different one leaves nothing to refresh with next time, and sending the
+      # retired one again ends the whole connection.
+      def rotated?(tokens, sent)
+        replacement = tokens['refresh_token'] if tokens.is_a?(Hash)
+        replacement.is_a?(String) && !replacement.strip.empty? && replacement != sent
       end
     end
   end

data/lib/assinafy/version.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 module Assinafy
-  VERSION = '1.8.1'
+  VERSION = '1.9.0'
   USER_AGENT = "Assinafy-Ruby-SDK/v#{VERSION}".freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: assinafy
 version: !ruby/object:Gem::Version
-  version: 1.8.1
+  version: 1.9.0
 platform: ruby
 authors:
 - Assinafy SDK Contributors