assinafy 1.8.1 → 1.10.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: de868e0ed87ada5a4456c4a811a1aa8057a6c482b344944661a0a4670ab86057
-  data.tar.gz: cef6d34ac264a694a194ca46ec35810836d0660001fcea5d351a1bbfff1dc638
+  metadata.gz: d8a12972c20d3f42452948edca772428326d37eafaf2354286bd9d3285bb6bf2
+  data.tar.gz: ad4b481584b05d052d7f44cde2a0cc7c99873e127031c30c60662c0a95dbca40
 SHA512:
-  metadata.gz: 24fff2f9be29fbcf69788f6f217f541c9d68ba22c10ec6dbb2f557e2c9c3d827fe57004294d6c8af7cc1c38dd6e8ca2ff12bb826995a97ea7a111eae8589dac4
-  data.tar.gz: 6e7ffbaa337b9480c118bd1d5ef2d3423bba3622e333a5b6c11b20ed594df78cc03772e7243ff2ca919f272aab8efdf439db3bb06d3f9180553c8388e7f0753b
+  metadata.gz: 8990224d37bac65328f95e7bdae28c999381f33fa64f1cfe300f3fffc124e8e98ab4e8e8473802534b1155ec06fc5c8080ffffb8a809118abf8d58cc661ad6a7
+  data.tar.gz: 35be652f65fa20a29cef34f3487f4af98ac9e94d613ec51c816b24ee879ed436b4c168aaeb51f32fef81864a9b7e54824812fa713693b2e7235e424ae407f085

data/CHANGELOG.md

@@ -2,6 +2,39 @@
 
 All notable changes to the `assinafy` Ruby gem are documented here.
 
+## 1.10.1
+
+- Update the pinned Ruby setup action to support Ruby 4.0.7 in CI and release workflows.
+
+## 1.10.0
+
+- Support the RFC 8693 token-exchange grant for Assinafy-provisioned internal service clients.
+- Validate OAuth grant parameters, PKCE challenges, authorization URLs, and token response shapes.
+- Validate assignment deadlines, notification and verification method combinations, and signing steps before requests.
+- Validate template role and signer IDs, distinct role assignments, and editor field payloads before document creation.
+- Validate contact addresses, scalar payload fields, decline-reason lengths, and finite polling intervals consistently.
+- Expand the document workflow guides, OAuth integration instructions, and API schema reference.
+- Use Ruby 4.0.7 for the development and release toolchain.
+
+## 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

@@ -57,6 +57,7 @@ client = Assinafy::Client.new(
 )
 
 document = client.documents.upload({ file_path: './contract.pdf' })
+document = client.documents.wait_until_ready(document.fetch('id'))
 signer   = client.signers.create(full_name: 'Alice Silva', email: 'alice@example.com')
 
 assignment = client.assignments.create(
@@ -72,6 +73,7 @@ puts assignment['id']
 ## Configuration
 
 ```ruby
+require 'logger'
 client = Assinafy::Client.new(
   api_key:        'your-api-key',
   token:          nil,
@@ -154,7 +156,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 +164,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 +176,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 +201,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:
 
@@ -231,6 +272,11 @@ client.oauth.authorization_server_metadata['code_challenge_methods_supported']
 `authorization_server_metadata` reaches a different host, so — like `/oauth/token` and `/oauth/revoke` — the SDK
 sends it with no workspace credentials attached.
 
+**Internal service clients.** The advertised RFC 8693 token-exchange grant is restricted to
+Assinafy-provisioned confidential service clients. Marketplace apps use PKCE authorization code
+and refresh. `client.oauth.token` accepts token exchange with `client_secret`, `subject_token`,
+`subject_token_type`, and `resource`; it issues no refresh token.
+
 **Errors.** OAuth routes answer with the flat RFC 6749 object rather than this API's envelope, so the SDK raises
 `Assinafy::OAuthError` (a subclass of `Assinafy::ApiError`):
 
@@ -241,6 +287,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
@@ -300,11 +350,11 @@ client.documents.append_tags('document-id', ['tag-id-3'])
 # The deployed sandbox also accepts existing tag names in these arrays.
 client.documents.detach_tag('document-id', 'tag-id')
 
-# Template-driven creation
+# Template-driven creation (a template with one configured Signer role)
 client.documents.create_from_template(
   'template-id',
   [{ role_id: 'role', id: 'signer-id', verification_method: 'Email', notification_methods: ['Email'] }],
-  { name: 'Contract', message: 'Please sign', expires_at: '2026-12-31T23:59:00Z' }
+  { name: 'Contract', message: 'Please sign', expires_at: '2099-12-31T23:59:00Z' }
 )
 client.documents.estimate_cost_from_template(
   'template-id',
@@ -358,7 +408,7 @@ client.assignments.create(
   method:         'virtual',
   signers:        [{ id: 'signer-1', verification_method: 'Email', notification_methods: ['Email'], step: 1 }],
   message:        'Please sign',
-  expires_at:     '2026-12-31T23:59:00Z',
+  expires_at:     '2099-12-31T23:59:00Z',
   copy_receivers: ['cc-signer-id']
 )
 
@@ -374,7 +424,7 @@ client.assignments.create(
 
 client.assignments.list                                       # GET /assignments (scoped to the account)
 client.assignments.estimate_cost('document-id', signers: [{ verification_method: 'Whatsapp' }])
-client.assignments.reset_expiration('document-id', 'assignment-id', '2026-12-31T23:59:00Z')
+client.assignments.reset_expiration('document-id', 'assignment-id', '2099-12-31T23:59:00Z')
 client.assignments.reset_expiration('document-id', 'assignment-id', nil) # clears the expiry
 client.assignments.resend_notification('document-id', 'assignment-id', 'signer-id')
 client.assignments.estimate_resend_cost('document-id', 'assignment-id', 'signer-id')
@@ -393,6 +443,11 @@ client.assignments.decline('document-id', 'assignment-id', decline_reason: 'Clau
 
 > The `sign` request body is the API's camelCase body-key exception. This SDK accepts the snake_case keys (`item_id`, `field_id`, `page_id`, `value`) shown above and maps them to `itemId/fieldId/pageId/value` automatically. CamelCase input is also passed through unchanged. Assignment listing separately uses the live-required `accountId` query parameter.
 
+Use exactly one notification channel per signer: `Email` verification pairs with `Email`,
+`Whatsapp` pairs with `Whatsapp`, and `DigitalCertificate` permits either. If any signer has a
+`step`, all must have one, with contiguous steps starting at 1. A certificate signer must be alone
+in its step. Deadlines require a timezone and must be at least one hour in the future.
+
 ### Signer documents (multi-document workflows)
 
 ```ruby
@@ -416,7 +471,12 @@ client.templates.delete('template-id')
 client.templates.download_page('template-id', 'page-id')   # binary image bytes
 ```
 
-> Template endpoints (`get`/`create`/`update`/`delete`/`download_page`) are live-verified against the sandbox but are not part of the current OpenAPI document. `create` requires a source file (`multipart/form-data`); the template name defaults to the uploaded file's name.
+> Template endpoints (`get`/`create`/`update`/`delete`/`download_page`) are supported by the deployed API but are not part of the current OpenAPI document. `create` requires a source file (`multipart/form-data`); the template name defaults to the uploaded file's name.
+
+A template upload initially contains an `Editor` role. Configure at least one `Signer` role and its
+fields in the Assinafy application before generating a document. Supply one entry per role, each with
+a distinct existing signer ID; `role_id` comes from the template's `roles` array. Cost estimation
+requires `role_id` but can omit the signer ID.
 
 ### Tags
 
@@ -596,16 +656,18 @@ assignment = client.assignments.create(
   method:     'virtual',
   signers:    [signer_request],
   message:    'Please review and sign.',
-  expires_at: '2026-12-31T23:59:00Z'
+  expires_at: '2099-12-31T23:59:00Z'
 )
 # => Assignment, including signing_urls
 ```
 
-The template alternative binds a signer to a template role and creates the document and assignment together:
+For a template configured with exactly one `Signer` role, the alternative binds the existing signer
+to that role and creates the document and assignment together. Templates with more roles require
+a distinct signer entry for each role:
 
 ```ruby
 role_signer = {
-  role_id:              template.fetch('roles').first.fetch('id'),
+  role_id:              template.fetch('roles').find { |role| role['assignment_type'] == 'Signer' }.fetch('id'),
   id:                   signer.fetch('id'),
   verification_method:  'Email',
   notification_methods: ['Email']
@@ -678,7 +740,8 @@ signer is created.
 Requesting the method is fully supported. Completing the signature is not: the two-step handshake
 (`/signers/certificate/start`, `/signers/certificate/complete`) is absent from the API v1 machine contract — its
 authentication and request/response schemas are not published — so the SDK does not expose those completion
-calls rather than guess at their payloads. Contact Assinafy before enabling a digital-certificate signing flow.
+calls. Direct A1/A3 signers to Assinafy's hosted signing flow using the returned `signing_urls`;
+contact Assinafy for a published contract before integrating the handshake directly.
 Once it completes, the `pades` artifact returns the qualified signature.
 
 ### 7. Inspect, tag, download, and verify
@@ -691,7 +754,8 @@ tags = client.documents.append_tags(document_id, ['tag-id']) # => Array<Tag>
 client.documents.replace_tags(document_id, tags.map { |tag| tag.fetch('id') })
 
 original_pdf = client.documents.download(document_id, 'original')
-signed_pdf = client.documents.download(document_id, 'pades')
+signed_pdf = client.documents.download(document_id, 'certificated')
+# For documents completed with ICP-Brasil certificates: download(document_id, 'pades')
 certificate_pdf = client.documents.download(document_id, 'certificated')
 
 verification = client.documents.verify('signature-hash-from-assinafy')
@@ -744,10 +808,10 @@ result = client.upload_and_request_signatures(
   source:  { file_path: './contract.pdf' },
   signers: [
     { full_name: 'Alice Silva', email: 'alice@example.com' },
-    { full_name: 'Bob Costa',   whatsapp_phone_number: '+5548999990000' }
+    { full_name: 'Bob Costa',   email: 'bob@example.com' }
   ],
   message:    'Please sign.',
-  expires_at: '2026-12-31T23:59:00Z'
+  expires_at: '2099-12-31T23:59:00Z'
 )
 
 puts result[:document]['id']
@@ -760,11 +824,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.
@@ -798,10 +862,16 @@ ASSINAFY_API_KEY=... \
 ASSINAFY_ACCOUNT_ID=... \
 ASSINAFY_TEST_EMAIL=recipient1@example.com \
 ASSINAFY_TEST_EMAIL2=recipient2@example.com \
+ASSINAFY_TEMPLATE_ID=configured-template-id \
 ASSINAFY_BASE_URL=https://sandbox.assinafy.com.br/v1 \
 bundle exec rspec spec/integration
 ```
 
+`ASSINAFY_TEMPLATE_ID` must identify a sandbox template with a `Signer` role configured in the
+application. Without it, the positive template-generation example is skipped. Supply different test
+recipients for its roles. OAuth browser consent is tested separately with a registered app, an HTTPS
+callback, and the matching authorization server; sandbox keys are not production OAuth credentials.
+
 > These tests create and clean up real resources and, for the assignment flow, send real signature-request emails to the addresses in `ASSINAFY_TEST_EMAIL` / `ASSINAFY_TEST_EMAIL2`.
 
 ## Contributing