@assinafy/sdk 2.2.0 → 2.4.0

package/dist/index.mjs

@@ -32,6 +32,29 @@ var AssinafyError = class extends Error {
 var ApiError = class _ApiError extends AssinafyError {
   statusCode;
   responseData;
+  /**
+   * Parsed `WWW-Authenticate` challenge, when the response carried one.
+   *
+   * A `403` whose challenge is `{ error: 'insufficient_scope', scope: '…' }`
+   * means the OAuth token is valid but was never granted that permission:
+   * send the user through the authorization flow again asking for the scope
+   * named in `scope`. A `403` without a challenge has a different cause —
+   * another workspace, the user's role, or a surface OAuth tokens never
+   * reach — and reconnecting will not fix it.
+   *
+   * @example
+   * ```ts
+   * try {
+   *   await connected.documents.upload({ filePath: './contract.pdf' });
+   * } catch (error) {
+   *   if (error instanceof ApiError && error.challenge?.error === 'insufficient_scope') {
+   *     return reconnect(error.challenge.scope);   // 'documents:write'
+   *   }
+   *   throw error;
+   * }
+   * ```
+   */
+  challenge;
   /**
    * Create an error representing a non-success API response.
    *
@@ -77,6 +100,55 @@ var ApiError = class _ApiError extends AssinafyError {
     return new _ApiError(message, statusCode, responseData);
   }
 };
+var OAuthError = class _OAuthError extends ApiError {
+  /** RFC 6749 error code, e.g. `invalid_grant`. */
+  error;
+  /** The server's human-readable explanation, when it sent one. */
+  errorDescription;
+  /**
+   * Create an OAuth protocol error.
+   *
+   * @param error - RFC 6749 error code.
+   * @param errorDescription - Server-provided explanation, or `null`.
+   * @param statusCode - HTTP status that carried it. Authorization responses
+   * arrive as redirect query parameters rather than an HTTP response, so
+   * {@link OAuthResource.readAuthorizationCallback} reports them as `400`.
+   * @param responseData - The raw error object.
+   *
+   * @example
+   * ```ts
+   * throw new OAuthError('invalid_grant', 'Authorization code expired.', 400);
+   * ```
+   */
+  constructor(error, errorDescription = null, statusCode = 400, responseData = null) {
+    super(errorDescription ? `${error}: ${errorDescription}` : error, statusCode, responseData);
+    this.name = "OAuthError";
+    this.error = error;
+    this.errorDescription = errorDescription;
+  }
+  /**
+   * Upgrade an {@link ApiError} to an {@link OAuthError} when its body is an
+   * RFC 6749 error object; otherwise return the value untouched.
+   *
+   * @param error - Any thrown value.
+   * @returns An `OAuthError` when the body carries a non-empty string
+   * `error`, else the original value.
+   */
+  static upgrade(error) {
+    if (!(error instanceof ApiError) || error instanceof _OAuthError) return error;
+    const body = error.responseData;
+    if (body === null || typeof body !== "object") return error;
+    const code = body["error"];
+    if (typeof code !== "string" || code.length === 0) return error;
+    const description = body["error_description"];
+    return new _OAuthError(
+      code,
+      typeof description === "string" && description.length > 0 ? description : null,
+      error.statusCode,
+      body
+    );
+  }
+};
 var ValidationError = class extends AssinafyError {
   errors;
   /**
@@ -116,6 +188,43 @@ var NetworkError = class extends AssinafyError {
 
 // src/utils.ts
 import axios from "axios";
+
+// src/support/headers.ts
+function readHeader(headers, name) {
+  if (!headers) return void 0;
+  const lower = name.toLowerCase();
+  for (const [key, value] of Object.entries(headers)) {
+    if (key.toLowerCase() === lower && value != null) {
+      const first = Array.isArray(value) ? value[0] : value;
+      if (typeof first === "string" || typeof first === "number" || typeof first === "boolean") {
+        return String(first);
+      }
+      return void 0;
+    }
+  }
+  return void 0;
+}
+var CHALLENGE_PARAM = /([A-Za-z0-9_-]+)\s*=\s*(?:"([^"]*)"|([^\s,]+))/gu;
+function parseWwwAuthenticate(value) {
+  if (typeof value !== "string") return void 0;
+  const trimmed = value.trim();
+  const scheme = /^[A-Za-z0-9_-]+/u.exec(trimmed)?.[0];
+  if (!scheme) return void 0;
+  const challenge = { scheme };
+  CHALLENGE_PARAM.lastIndex = 0;
+  for (const match of trimmed.slice(scheme.length).matchAll(CHALLENGE_PARAM)) {
+    const key = match[1]?.toLowerCase();
+    const paramValue = match[2] ?? match[3];
+    if (paramValue === void 0) continue;
+    if (key === "error") challenge.error = paramValue;
+    else if (key === "error_description") challenge.error_description = paramValue;
+    else if (key === "scope") challenge.scope = paramValue;
+    else if (key === "resource_metadata") challenge.resource_metadata = paramValue;
+  }
+  return challenge;
+}
+
+// src/utils.ts
 var SAFE_LOG_NUMBER_FIELDS = /* @__PURE__ */ new Set([
   "attempt",
   "attempts",
@@ -159,7 +268,12 @@ function toSdkError(error, fallbackMessage) {
     const status = error.response?.status;
     if (status) {
       const body = decodeBinaryErrorBody(error.response?.data ?? null);
-      return ApiError.fromResponse(status, body ?? null);
+      const apiError = ApiError.fromResponse(status, body ?? null);
+      const challenge = parseWwwAuthenticate(
+        readHeader(error.response?.headers, "www-authenticate")
+      );
+      if (challenge) apiError.challenge = challenge;
+      return apiError;
     }
     const cause = sanitiseNetworkCause(error);
     return new NetworkError(`${fallbackMessage}: ${cause.message}`, { cause });
@@ -309,22 +423,6 @@ function cleanListParams(params) {
   return out;
 }
 
-// src/support/headers.ts
-function readHeader(headers, name) {
-  if (!headers) return void 0;
-  const lower = name.toLowerCase();
-  for (const [key, value] of Object.entries(headers)) {
-    if (key.toLowerCase() === lower && value != null) {
-      const first = Array.isArray(value) ? value[0] : value;
-      if (typeof first === "string" || typeof first === "number" || typeof first === "boolean") {
-        return String(first);
-      }
-      return void 0;
-    }
-  }
-  return void 0;
-}
-
 // src/support/retry.ts
 function retryDelayFromHeaders(headers) {
   const retryAfter = readHeader(headers, "retry-after");
@@ -476,7 +574,7 @@ import axios2 from "axios";
 // package.json
 var package_default = {
   name: "@assinafy/sdk",
-  version: "2.2.0",
+  version: "2.4.0",
   packageManager: "bun@1.4.0",
   description: "TypeScript SDK for Assinafy API - Digital signature platform",
   type: "commonjs",
@@ -563,6 +661,7 @@ var package_default = {
     "dist",
     "docs",
     "README.md",
+    "README.en.md",
     "CHANGELOG.md",
     "SECURITY.md",
     "LICENSE"
@@ -814,14 +913,34 @@ function toInt(value) {
 var ASSIGNMENT_METHODS = /* @__PURE__ */ new Set(["virtual", "collect"]);
 var VERIFICATION_METHODS = /* @__PURE__ */ new Set(["Email", "Whatsapp", "DigitalCertificate"]);
 var NOTIFICATION_METHODS = /* @__PURE__ */ new Set(["Email", "Whatsapp"]);
+var ALLOWED_NOTIFICATION_METHODS = {
+  Email: /* @__PURE__ */ new Set(["Email"]),
+  Whatsapp: /* @__PURE__ */ new Set(["Whatsapp"]),
+  DigitalCertificate: NOTIFICATION_METHODS
+};
 function validateAssignmentSignerOptions(signer, label = "signer") {
   if (signer.verification_method !== void 0 && (typeof signer.verification_method !== "string" || !VERIFICATION_METHODS.has(signer.verification_method))) {
     throw new ValidationError(`${label} has an invalid verification_method`);
   }
-  if (signer.notification_methods !== void 0 && (!Array.isArray(signer.notification_methods) || signer.notification_methods.some(
-    (method) => typeof method !== "string" || !NOTIFICATION_METHODS.has(method)
-  ))) {
-    throw new ValidationError(`${label} has invalid notification_methods`);
+  if (signer.notification_methods !== void 0) {
+    const methods = signer.notification_methods;
+    if (!Array.isArray(methods) || methods.some(
+      (method) => typeof method !== "string" || !NOTIFICATION_METHODS.has(method)
+    )) {
+      throw new ValidationError(`${label} has invalid notification_methods`);
+    }
+    if (methods.length !== 1) {
+      throw new ValidationError(`${label} allows exactly one notification method`);
+    }
+    const verification = signer.verification_method;
+    if (typeof verification === "string") {
+      const allowed = ALLOWED_NOTIFICATION_METHODS[verification];
+      if (allowed && !allowed.has(methods[0])) {
+        throw new ValidationError(
+          `${label} cannot pair ${verification} verification with ${String(methods[0])} notification`
+        );
+      }
+    }
   }
   if (signer.step !== void 0 && (typeof signer.step !== "number" || !Number.isSafeInteger(signer.step) || signer.step < 1)) {
     throw new ValidationError(`${label} step must be a positive safe integer`);
@@ -892,8 +1011,8 @@ function buildAssignmentEstimatePayload(payload) {
     throw new ValidationError("method must be virtual or collect");
   }
   const signers = Array.isArray(payload.signers) ? payload.signers : [];
-  if (method === "virtual" && signers.length === 0) {
-    throw new ValidationError("At least one signer is required for a virtual cost estimate");
+  if (signers.length === 0) {
+    throw new ValidationError("At least one signer is required for a cost estimate");
   }
   const entries = payload.entries === void 0 ? void 0 : normaliseAssignmentEntries(payload.entries);
   if (method === "collect" && (!entries || entries.length === 0)) {
@@ -901,7 +1020,7 @@ function buildAssignmentEstimatePayload(payload) {
   }
   return cleanParams({
     method,
-    signers: signers.length > 0 ? signers.map((signer) => normaliseEstimateSigner(signer)) : void 0,
+    signers: signers.map((signer) => normaliseEstimateSigner(signer)),
     entries
   });
 }
@@ -1282,7 +1401,8 @@ var AssignmentResource = class extends BaseResource {
    * }
    * ```
    * @throws {ValidationError} If `documentId` is missing, a `virtual` request
-   * has no signer entry, or a `collect` request has no field-placement entry.
+   * has no signer entry, or a `collect` request has no signer entry or no
+   * field-placement entry.
    * @throws {ApiError} If the API rejects the request.
    *
    * @example
@@ -2615,9 +2735,6 @@ function normaliseTemplateSigners(signers) {
       throw new ValidationError(`Template signer ${index + 1} requires id`);
     }
     validateAssignmentSignerOptions(signer, `Template signer ${index + 1}`);
-    if (signer.notification_methods !== void 0 && signer.notification_methods.length > 1) {
-      throw new ValidationError(`Template signer ${index + 1} allows one notification method`);
-    }
     const projected = { role_id: signer.role_id, id: signer.id };
     if (signer.verification_method !== void 0) {
       projected.verification_method = signer.verification_method;
@@ -4780,6 +4897,686 @@ var AuthenticationResource = class extends BaseResource {
   }
 };
 
+// src/resources/oauth.ts
+import { createHash, randomBytes, timingSafeEqual } from "crypto";
+var PROTECTED_RESOURCE_PATH = "/.well-known/oauth-protected-resource";
+var AUTHORIZATION_SERVER_PATH = "/.well-known/oauth-authorization-server";
+var CODE_VERIFIER_PATTERN = /^[A-Za-z0-9\-._~]{43,128}$/u;
+var OAuthResource = class extends BaseResource {
+  publicHttp;
+  constructor(http, defaultAccountId, logger, publicHttp) {
+    super(http, defaultAccountId, logger);
+    this.publicHttp = withoutCredentials(publicHttp ?? http);
+  }
+  /**
+   * Read this API's protected-resource metadata
+   * (`GET /.well-known/oauth-protected-resource`).
+   *
+   * Served at the API host root — not under `/v1` — and bare, without the
+   * `{ status, message, data }` envelope, as RFC 8615 requires. Use it to
+   * discover which authorization server may issue tokens for this API and
+   * which scopes it accepts.
+   *
+   * Request body: none. Authentication: none.
+   *
+   * @returns The metadata document:
+   * ```jsonc
+   * {
+   *   "resource": "https://api.assinafy.com.br",
+   *   "authorization_servers": ["https://auth.assinafy.com.br"],
+   *   "scopes_supported": [
+   *     "documents:read", "documents:write",
+   *     "templates:read", "templates:write",
+   *     "account:read", "openid", "profile", "email"
+   *   ],
+   *   "bearer_methods_supported": ["header"]
+   * }
+   * ```
+   * `offline_access` is deliberately absent: it is a request-time signal to
+   * the authorization server, not a permission this API enforces.
+   * @throws {ApiError} If the host does not publish the document.
+   *
+   * @example
+   * ```ts
+   * const metadata = await client.oauth.getProtectedResourceMetadata();
+   * console.log(metadata.authorization_servers[0]);
+   * ```
+   */
+  async getProtectedResourceMetadata() {
+    return this.call(
+      "Failed to fetch OAuth protected-resource metadata",
+      () => this.publicHttp.get(`${this.apiOrigin()}${PROTECTED_RESOURCE_PATH}`)
+    );
+  }
+  /**
+   * Read the authorization server's metadata
+   * (`GET {issuer}/.well-known/oauth-authorization-server`, RFC 8414).
+   *
+   * Every endpoint URL an OAuth client needs comes from here, so nothing has
+   * to be hardcoded. The document is served by the authorization server, a
+   * different host from this API.
+   *
+   * @param issuer - Issuer to read. Defaults to the first entry of
+   * {@link OAuthResource.getProtectedResourceMetadata}, which costs one extra
+   * request — pass the issuer to skip it.
+   * @returns The metadata document:
+   * ```jsonc
+   * {
+   *   "issuer": "https://auth.assinafy.com.br",
+   *   "authorization_endpoint": "https://auth.assinafy.com.br/oauth/authorize",
+   *   "token_endpoint": "https://api.assinafy.com.br/v1/oauth/token",
+   *   "revocation_endpoint": "https://api.assinafy.com.br/v1/oauth/revoke",
+   *   "userinfo_endpoint": "https://api.assinafy.com.br/v1/oauth/userinfo",
+   *   "jwks_uri": "https://auth.assinafy.com.br/.well-known/jwks.json",
+   *   "scopes_supported": ["documents:read", "documents:write", "templates:read",
+   *                        "templates:write", "account:read", "openid",
+   *                        "profile", "email", "offline_access"],
+   *   "response_types_supported": ["code"],
+   *   "grant_types_supported": ["authorization_code", "refresh_token"],
+   *   "code_challenge_methods_supported": ["S256"],
+   *   "token_endpoint_auth_methods_supported": ["client_secret_post", "none"],
+   *   "authorization_response_iss_parameter_supported": true,
+   *   "client_id_metadata_document_supported": true
+   * }
+   * ```
+   * @throws {ValidationError} If `issuer` is not an absolute `https://` URL,
+   * or the document's own `issuer` disagrees with where it was fetched from
+   * (RFC 8414 §3.3 — a mismatch means the document is not authoritative).
+   * @throws {ApiError} If the authorization server rejects the request.
+   *
+   * @example
+   * ```ts
+   * const as = await client.oauth.getAuthorizationServerMetadata();
+   * console.log(as.authorization_endpoint);
+   * ```
+   */
+  async getAuthorizationServerMetadata(issuer) {
+    const resolved = issuer ?? await this.defaultIssuer();
+    const base = assertHttpsUrl(resolved, "issuer").replace(/\/+$/u, "");
+    const metadata = await this.call(
+      "Failed to fetch OAuth authorization-server metadata",
+      () => this.publicHttp.get(`${base}${AUTHORIZATION_SERVER_PATH}`)
+    );
+    if (normaliseIssuer(metadata?.issuer) !== normaliseIssuer(base)) {
+      throw new ValidationError(
+        "Authorization-server metadata issuer does not match the requested issuer",
+        { expected: base, received: metadata?.issuer ?? null }
+      );
+    }
+    return metadata;
+  }
+  /**
+   * Mint a PKCE pair and a `state`, then build the consent URL to send the
+   * user's browser to (`GET {authorization_endpoint}`).
+   *
+   * Call this once per connection attempt and keep the whole returned object
+   * in the user's session: reusing a verifier or a `state` across attempts
+   * defeats both PKCE and CSRF protection. Navigate the browser to `url` with
+   * a full page load — an `fetch`/XHR cannot show a consent screen.
+   *
+   * PKCE is mandatory for confidential applications too, and Assinafy accepts
+   * only the `S256` challenge method.
+   *
+   * @param options - Authorization-request options.
+   * @param options.clientId - The application's `client_id`.
+   * @param options.redirectUri - One of the application's registered redirect
+   * URIs, matched character for character (`…/callback` and `…/callback/` are
+   * different). Must be `https://` and carry no fragment.
+   * @param options.scopes - Permissions to request, e.g.
+   * `['documents:read', 'documents:write', 'offline_access']`. Ask for the
+   * minimum: the user approves all of them or none. Add `offline_access` to
+   * receive a refresh token and `openid` to receive an `id_token`.
+   * @param options.authorizationEndpoint - Skip discovery by supplying the
+   * endpoint yourself. Defaults to the discovered
+   * `authorization_endpoint`.
+   * @param options.issuer - Issuer to discover from, and the value the
+   * callback's `iss` must equal. Defaults to the discovered issuer.
+   * @param options.resource - RFC 8707 resource indicator. Defaults to this
+   * API's origin; pass `null` to omit it. It must match the value sent to the
+   * token endpoint, or the exchange fails with `invalid_target`.
+   * @param options.state - Supply your own CSRF value instead of a generated
+   * one. Must be unique per attempt.
+   * @param options.codeVerifier - Supply your own RFC 7636 verifier (43–128
+   * characters from `A-Z a-z 0-9 - . _ ~`) instead of a generated one.
+   * @param options.nonce - OIDC nonce echoed in the `id_token`. Generated
+   * automatically when `openid` is requested; pass a string to set it or
+   * `null` to omit it.
+   * @param options.prompt - Forwarded as the OIDC `prompt` parameter, e.g.
+   * `'consent'` to force the approval screen again.
+   * @returns The request to store and redirect with:
+   * ```jsonc
+   * {
+   *   "url": "https://auth.assinafy.com.br/oauth/authorize?response_type=code&client_id=…&redirect_uri=https%3A%2F%2Fmyapp.com%2Foauth%2Fcallback&scope=documents%3Aread+offline_access&state=8Xv…&code_challenge=E9M…&code_challenge_method=S256&resource=https%3A%2F%2Fapi.assinafy.com.br",
+   *   "state": "8Xv2rQ7mJt0aLpKcWn4dZg",
+   *   "codeVerifier": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk",
+   *   "issuer": "https://auth.assinafy.com.br",
+   *   "nonce": "n-0S6_WzA2Mj"
+   * }
+   * ```
+   * @throws {ValidationError} If `clientId` is empty, `redirectUri` is not an
+   * absolute `https://` URL without a fragment, `scopes` is empty or contains
+   * a value with whitespace, or a supplied `codeVerifier`/`state` is invalid.
+   * @throws {ApiError} If discovery is needed and fails.
+   *
+   * @example
+   * ```ts
+   * const request = await client.oauth.createAuthorizationUrl({
+   *   clientId: process.env.ASSINAFY_CLIENT_ID!,
+   *   redirectUri: 'https://myapp.com/oauth/callback',
+   *   scopes: ['documents:read', 'documents:write', 'offline_access'],
+   * });
+   * session.oauth = request;
+   * response.redirect(request.url);
+   * ```
+   */
+  async createAuthorizationUrl(options) {
+    assertRecord(options, "authorization options");
+    assertNonEmptyString(options.clientId, "clientId");
+    assertRedirectUri(options.redirectUri);
+    const scope = assertScopes(options.scopes);
+    let endpoint = options.authorizationEndpoint;
+    let issuer = options.issuer;
+    if (endpoint === void 0 || issuer === void 0) {
+      const metadata = await this.getAuthorizationServerMetadata(options.issuer);
+      endpoint ??= metadata.authorization_endpoint;
+      issuer ??= metadata.issuer;
+    }
+    assertHttpsUrl(endpoint, "authorizationEndpoint");
+    assertHttpsUrl(issuer, "issuer");
+    const codeVerifier = options.codeVerifier ?? createCodeVerifier();
+    assertCodeVerifier(codeVerifier);
+    const state = options.state ?? createRandomValue(16);
+    assertNonEmptyString(state, "state");
+    const url = new URL(endpoint);
+    url.searchParams.set("response_type", "code");
+    url.searchParams.set("client_id", options.clientId);
+    url.searchParams.set("redirect_uri", options.redirectUri);
+    url.searchParams.set("scope", scope);
+    url.searchParams.set("state", state);
+    url.searchParams.set("code_challenge", codeChallengeFor(codeVerifier));
+    url.searchParams.set("code_challenge_method", "S256");
+    const { resource } = this.resourceParam(options.resource);
+    if (resource !== void 0) url.searchParams.set("resource", resource);
+    const wantsNonce = options.nonce === void 0 ? options.scopes.includes("openid") : options.nonce !== null;
+    const nonce = wantsNonce ? options.nonce ?? createRandomValue(16) : void 0;
+    if (nonce !== void 0) {
+      assertNonEmptyString(nonce, "nonce");
+      url.searchParams.set("nonce", nonce);
+    }
+    if (options.prompt !== void 0) {
+      assertNonEmptyString(options.prompt, "prompt");
+      url.searchParams.set("prompt", options.prompt);
+    }
+    this.logger.info("Built OAuth authorization URL");
+    const request = {
+      url: url.toString(),
+      state,
+      codeVerifier,
+      issuer
+    };
+    if (nonce !== void 0) request.nonce = nonce;
+    return request;
+  }
+  /**
+   * Validate the authorization response that lands on your redirect URI and
+   * return the code to exchange.
+   *
+   * Checks, in order and before anything else is trusted: `state` equals the
+   * value from {@link OAuthResource.createAuthorizationUrl} (constant-time),
+   * `iss` is present and equals the expected issuer, and only then whether
+   * the server reported an error. A declined consent arrives as
+   * `?error=access_denied`, not as a failed HTTP request.
+   *
+   * The `iss` check is strict because the authorization server advertises
+   * RFC 9207 support and always sends the parameter: a missing `iss` is
+   * treated exactly like a wrong one. Omit `expected.issuer` only if
+   * something between the browser and your handler strips query parameters.
+   *
+   * This performs no network I/O.
+   *
+   * @param params - The callback's query parameters. Accepts an Express-style
+   * `req.query` record, a `URLSearchParams`, a `URL`, a full callback URL
+   * string, or a bare `a=b&c=d` query string.
+   * @param expected - The stored {@link IOAuthAuthorizationRequest} (or any
+   * object carrying its `state` and `issuer`).
+   * @returns The validated response:
+   * ```jsonc
+   * {
+   *   "code": "def50200a1b2c3…",
+   *   "state": "8Xv2rQ7mJt0aLpKcWn4dZg",
+   *   "issuer": "https://auth.assinafy.com.br"
+   * }
+   * ```
+   * @throws {ValidationError} If `state` is missing or does not match, `iss`
+   * is absent or disagrees with the expected issuer, or a successful response
+   * carries no `code`. In every case the response is not yours — stop, do not
+   * exchange.
+   * @throws {OAuthError} If the server returned `error` (e.g.
+   * `access_denied`, `invalid_scope`, `invalid_request`,
+   * `unsupported_response_type`, `invalid_target`).
+   *
+   * @example
+   * ```ts
+   * app.get('/oauth/callback', async (req, res) => {
+   *   const stored = req.session.oauth;
+   *   const { code } = client.oauth.readAuthorizationCallback(req.query, stored);
+   *   const tokens = await client.oauth.exchangeCode({
+   *     code,
+   *     codeVerifier: stored.codeVerifier,
+   *     redirectUri: 'https://myapp.com/oauth/callback',
+   *     clientId: process.env.ASSINAFY_CLIENT_ID!,
+   *     clientSecret: process.env.ASSINAFY_CLIENT_SECRET,
+   *   });
+   * });
+   * ```
+   */
+  readAuthorizationCallback(params, expected) {
+    assertRecord(expected, "expected authorization request");
+    assertNonEmptyString(expected.state, "expected.state");
+    const query = toSearchParams(params);
+    const state = query.get("state");
+    if (state === null || !constantTimeEquals(state, expected.state)) {
+      throw new ValidationError(
+        "OAuth callback state does not match the stored authorization request"
+      );
+    }
+    const issuer = query.get("iss") ?? void 0;
+    if (expected.issuer !== void 0) {
+      if (issuer === void 0 || normaliseIssuer(issuer) !== normaliseIssuer(expected.issuer)) {
+        throw new ValidationError(
+          "OAuth callback issuer is missing or does not match the expected issuer",
+          { expected: expected.issuer, received: issuer ?? null }
+        );
+      }
+    }
+    const error = query.get("error");
+    if (error !== null && error.length > 0) {
+      throw new OAuthError(error, query.get("error_description"), 400, {
+        error,
+        error_description: query.get("error_description")
+      });
+    }
+    const code = query.get("code");
+    if (code === null || code.length === 0) {
+      throw new ValidationError("OAuth callback carries neither a code nor an error");
+    }
+    const result = { code, state };
+    if (issuer !== void 0) result.issuer = issuer;
+    return result;
+  }
+  /**
+   * Exchange an authorization code for tokens
+   * (`POST /oauth/token`, `grant_type=authorization_code`).
+   *
+   * Run this on your server: the code is single-use and expires **60 seconds**
+   * after approval, and a confidential application's secret must never reach
+   * a browser. Every value must match the authorization request exactly, or
+   * the API answers `invalid_grant`.
+   *
+   * @param options - Exchange options.
+   * @param options.code - The code from
+   * {@link OAuthResource.readAuthorizationCallback}.
+   * @param options.codeVerifier - The verifier stored alongside the request.
+   * @param options.redirectUri - The same redirect URI that was authorized.
+   * @param options.clientId - The application's `client_id`.
+   * @param options.clientSecret - The `client_secret`, for confidential
+   * applications only. Public applications omit it and rely on PKCE.
+   * @param options.resource - The same RFC 8707 resource indicator sent to
+   * the authorization endpoint. Defaults to this API's origin; pass `null` to
+   * omit it. A value disagreeing with the authorized one fails with
+   * `invalid_target`.
+   * @returns The token set — a flat object, **not** the API's usual envelope:
+   * ```jsonc
+   * {
+   *   "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…",
+   *   "token_type": "Bearer",
+   *   "expires_in": 3600,
+   *   "scope": "documents:read documents:write",
+   *   "refresh_token": "def5020088c2…",   // only with offline_access
+   *   "id_token": "eyJraWQiOiJEQlR0S0…"   // only with openid
+   * }
+   * ```
+   * Read `scope` rather than assuming every requested permission was granted.
+   * @throws {ValidationError} If an argument is missing or malformed, or a
+   * `2xx` response carries no `access_token`.
+   * @throws {OAuthError} `invalid_grant` for a spent, expired, replayed or
+   * mismatched code; `invalid_client` for a bad `client_id`/`client_secret`;
+   * `invalid_target` for a `resource` mismatch.
+   *
+   * @example
+   * ```ts
+   * const tokens = await client.oauth.exchangeCode({
+   *   code,
+   *   codeVerifier: session.oauth.codeVerifier,
+   *   redirectUri: 'https://myapp.com/oauth/callback',
+   *   clientId: process.env.ASSINAFY_CLIENT_ID!,
+   *   clientSecret: process.env.ASSINAFY_CLIENT_SECRET,
+   * });
+   * ```
+   */
+  async exchangeCode(options) {
+    assertRecord(options, "code exchange options");
+    assertNonEmptyString(options.code, "code");
+    assertCodeVerifier(options.codeVerifier);
+    assertRedirectUri(options.redirectUri);
+    return this.requestToken("Failed to exchange the OAuth authorization code", {
+      grant_type: "authorization_code",
+      code: options.code,
+      redirect_uri: options.redirectUri,
+      code_verifier: options.codeVerifier,
+      ...this.clientAuth(options),
+      ...this.resourceParam(options.resource)
+    });
+  }
+  /**
+   * Renew an access token (`POST /oauth/token`, `grant_type=refresh_token`).
+   *
+   * Access tokens last one hour; refresh tokens are available only when
+   * `offline_access` was requested and granted.
+   *
+   * **Refresh tokens rotate.** Every call returns a new one and retires the
+   * one you sent, and a replayed refresh token cannot be told apart from a
+   * stolen one — so the server ends the entire connection and the user must
+   * reconnect. Therefore: persist `refresh_token` from the response before
+   * doing anything else with it, treat a timeout as "it may have succeeded"
+   * and re-read your stored token instead of retrying blindly, and never run
+   * two refreshes concurrently for one connection.
+   *
+   * Refreshing does not extend the connection's 30-day life.
+   *
+   * @param options - Refresh options.
+   * @param options.refreshToken - The current refresh token.
+   * @param options.clientId - The application's `client_id`.
+   * @param options.clientSecret - The `client_secret`, for confidential
+   * applications only.
+   * @param options.resource - RFC 8707 resource indicator. Defaults to this
+   * API's origin; pass `null` to omit it.
+   * @returns A fresh token set, identical in shape to
+   * {@link OAuthResource.exchangeCode}:
+   * ```jsonc
+   * {
+   *   "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…",
+   *   "token_type": "Bearer",
+   *   "expires_in": 3600,
+   *   "scope": "documents:read documents:write",
+   *   "refresh_token": "def50200f1e2…"    // NEW — persist it immediately
+   * }
+   * ```
+   * @throws {ValidationError} If an argument is missing, or a `2xx` response
+   * carries no `access_token`.
+   * @throws {OAuthError} `invalid_grant` when the refresh token was already
+   * used, expired, or the user reconnected with different permissions — ask
+   * the user to reconnect. `invalid_client` for bad client credentials.
+   *
+   * @example
+   * ```ts
+   * const tokens = await client.oauth.refreshToken({
+   *   refreshToken: connection.refreshToken,
+   *   clientId: process.env.ASSINAFY_CLIENT_ID!,
+   *   clientSecret: process.env.ASSINAFY_CLIENT_SECRET,
+   * });
+   * await connection.save({ refreshToken: tokens.refresh_token });
+   * ```
+   */
+  async refreshToken(options) {
+    assertRecord(options, "refresh options");
+    assertNonEmptyString(options.refreshToken, "refreshToken");
+    return this.requestToken("Failed to refresh the OAuth access token", {
+      grant_type: "refresh_token",
+      refresh_token: options.refreshToken,
+      ...this.clientAuth(options),
+      ...this.resourceParam(options.resource)
+    });
+  }
+  /**
+   * Revoke an access or refresh token (`POST /oauth/revoke`, RFC 7009).
+   *
+   * Call this when a user disconnects your app, instead of only deleting your
+   * copy of the token. Revoking a refresh token ends the whole connection.
+   *
+   * Every token outcome answers `200` — unknown, malformed and
+   * already-revoked included — so the endpoint cannot be used to probe
+   * whether a token exists. Only failed client authentication returns `401`.
+   *
+   * @param options - Revocation options.
+   * @param options.token - The access or refresh token to revoke.
+   * @param options.clientId - The application's `client_id`.
+   * @param options.clientSecret - The `client_secret`, for confidential
+   * applications only.
+   * @param options.tokenTypeHint - Optional `access_token` or
+   * `refresh_token` hint that lets the server skip a lookup.
+   * @returns Nothing; resolves once the API acknowledges the request.
+   * Request body:
+   * ```jsonc
+   * {
+   *   "token": "def50200f1e2…",
+   *   "token_type_hint": "refresh_token",
+   *   "client_id": "cli_1a2b3c",
+   *   "client_secret": "…"
+   * }
+   * ```
+   * @throws {ValidationError} If `token` or `clientId` is missing, or
+   * `tokenTypeHint` is not one of the two documented values.
+   * @throws {OAuthError} `invalid_client` when client authentication fails.
+   *
+   * @example
+   * ```ts
+   * await client.oauth.revokeToken({
+   *   token: connection.refreshToken,
+   *   tokenTypeHint: 'refresh_token',
+   *   clientId: process.env.ASSINAFY_CLIENT_ID!,
+   *   clientSecret: process.env.ASSINAFY_CLIENT_SECRET,
+   * });
+   * ```
+   */
+  async revokeToken(options) {
+    assertRecord(options, "revocation options");
+    assertNonEmptyString(options.token, "token");
+    if (options.tokenTypeHint !== void 0 && options.tokenTypeHint !== "access_token" && options.tokenTypeHint !== "refresh_token") {
+      throw new ValidationError("tokenTypeHint must be access_token or refresh_token");
+    }
+    const body = cleanParams({
+      token: options.token,
+      token_type_hint: options.tokenTypeHint,
+      ...this.clientAuth(options)
+    });
+    try {
+      await this.callVoid(
+        "Failed to revoke the OAuth token",
+        () => this.publicHttp.post("/oauth/revoke", body)
+      );
+    } catch (error) {
+      throw OAuthError.upgrade(error);
+    }
+  }
+  /**
+   * Read the OpenID Connect claims of the user who authorized a token
+   * (`GET /oauth/userinfo`).
+   *
+   * Requires the `openid` scope; `name` additionally requires `profile` and
+   * `email`/`email_verified` require `email`. Per OIDC Core §5.3.2 the
+   * response is a flat claims object, not this API's usual envelope.
+   *
+   * @param accessToken - Token to introspect. Omit to use the credential the
+   * client was constructed with (`token` or `apiKey`).
+   * @returns The claims the granted scopes allow:
+   * ```jsonc
+   * {
+   *   "sub": "d6zqpbyog2v3xvxerwn8la94",
+   *   "name": "Maria Silva",
+   *   "email": "maria@example.com",
+   *   "email_verified": true
+   * }
+   * ```
+   * `sub` is the stable user identifier; the rest are `null` when their scope
+   * was not granted.
+   * @throws {ValidationError} If `accessToken` is supplied but empty.
+   * @throws {ApiError} `401` when the token is missing, expired or revoked;
+   * `403` when the `openid` scope was not granted — its `WWW-Authenticate`
+   * header names the scope to reconnect with.
+   *
+   * @example
+   * ```ts
+   * const who = await client.oauth.getUserInfo(tokens.access_token);
+   * console.log(who.sub, who.email);
+   * ```
+   */
+  async getUserInfo(accessToken) {
+    if (accessToken === void 0) {
+      return this.call(
+        "Failed to fetch OAuth userinfo",
+        () => this.http.get("/oauth/userinfo")
+      );
+    }
+    assertNonEmptyString(accessToken, "accessToken");
+    return this.call(
+      "Failed to fetch OAuth userinfo",
+      () => this.publicHttp.get("/oauth/userinfo", {
+        headers: { Authorization: `Bearer ${accessToken}` }
+      })
+    );
+  }
+  /** POST the token endpoint and assert the response actually carries a token. */
+  async requestToken(label, body) {
+    let tokens;
+    try {
+      tokens = await this.call(
+        label,
+        () => this.publicHttp.post("/oauth/token", cleanParams(body))
+      );
+    } catch (error) {
+      throw OAuthError.upgrade(error);
+    }
+    if (typeof tokens?.access_token !== "string" || tokens.access_token.length === 0) {
+      throw new ValidationError(`${label}: the token endpoint returned no access_token`, {
+        response: tokens
+      });
+    }
+    return tokens;
+  }
+  /** `client_secret_post` credentials, omitting the secret for public clients. */
+  clientAuth(options) {
+    assertNonEmptyString(options.clientId, "clientId");
+    if (options.clientSecret !== void 0) {
+      assertNonEmptyString(options.clientSecret, "clientSecret");
+    }
+    return { client_id: options.clientId, client_secret: options.clientSecret };
+  }
+  /**
+   * Resolve the optional RFC 8707 `resource` indicator.
+   *
+   * Defaults to the configured API origin, which is what this API publishes
+   * as its `resource`. A loopback `http://` base URL — the shape used by mock
+   * servers and the packed-consumer smoke test — has no valid resource
+   * identifier, so the parameter is simply omitted rather than rejected; an
+   * explicitly supplied value is still required to be `https`.
+   */
+  resourceParam(resource) {
+    if (resource === void 0) {
+      const origin = this.apiOrigin();
+      return origin.startsWith("https:") ? { resource: origin } : {};
+    }
+    if (resource === null) return {};
+    assertHttpsUrl(resource, "resource");
+    return { resource };
+  }
+  /** Discover which authorization server may issue tokens for this API. */
+  async defaultIssuer() {
+    const metadata = await this.getProtectedResourceMetadata();
+    const issuer = metadata?.authorization_servers?.[0];
+    if (typeof issuer !== "string" || issuer.length === 0) {
+      throw new ValidationError(
+        "Protected-resource metadata lists no authorization server",
+        { metadata }
+      );
+    }
+    return issuer;
+  }
+  /**
+   * Origin of the configured API host.
+   *
+   * The `.well-known` document and the RFC 8707 resource indicator both sit
+   * at the host root, while `baseUrl` points at `/v1`.
+   */
+  apiOrigin() {
+    const baseUrl = this.publicHttp.defaults.baseURL;
+    if (typeof baseUrl !== "string" || baseUrl.length === 0) {
+      throw new ValidationError("The client has no base URL to derive the API origin from");
+    }
+    return new URL(baseUrl).origin;
+  }
+};
+function createCodeVerifier() {
+  return randomBytes(32).toString("base64url");
+}
+function createRandomValue(bytes) {
+  return randomBytes(bytes).toString("base64url");
+}
+function codeChallengeFor(codeVerifier) {
+  return createHash("sha256").update(codeVerifier).digest("base64url");
+}
+function assertCodeVerifier(value) {
+  if (typeof value !== "string" || !CODE_VERIFIER_PATTERN.test(value)) {
+    throw new ValidationError(
+      "codeVerifier must be 43-128 characters from A-Z a-z 0-9 - . _ ~"
+    );
+  }
+}
+function assertRedirectUri(value) {
+  const uri = assertHttpsUrl(value, "redirectUri");
+  if (uri.includes("#")) {
+    throw new ValidationError("redirectUri must not contain a fragment");
+  }
+}
+function assertHttpsUrl(value, label) {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new ValidationError(`${label} must be an absolute https URL`);
+  }
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new ValidationError(`${label} must be an absolute https URL`);
+  }
+  if (url.protocol !== "https:") {
+    throw new ValidationError(`${label} must be an absolute https URL`);
+  }
+  return value;
+}
+function assertScopes(scopes) {
+  if (!Array.isArray(scopes) || scopes.length === 0) {
+    throw new ValidationError("scopes must be a non-empty array of scope strings");
+  }
+  for (const scope of scopes) {
+    if (typeof scope !== "string" || scope.trim().length === 0 || /\s/u.test(scope)) {
+      throw new ValidationError("each scope must be a non-empty string without whitespace");
+    }
+  }
+  return [...new Set(scopes)].join(" ");
+}
+function normaliseIssuer(value) {
+  return typeof value === "string" ? value.replace(/\/+$/u, "") : "";
+}
+function constantTimeEquals(left, right) {
+  const a = Buffer.from(left, "utf8");
+  const b = Buffer.from(right, "utf8");
+  return a.length === b.length && timingSafeEqual(a, b);
+}
+function toSearchParams(params) {
+  if (params instanceof URLSearchParams) return params;
+  if (params instanceof URL) return params.searchParams;
+  if (typeof params === "string") {
+    return params.includes("://") ? new URL(params).searchParams : new URLSearchParams(params.replace(/^\?/u, ""));
+  }
+  assertRecord(params, "callback parameters");
+  const search = new URLSearchParams();
+  for (const [key, value] of Object.entries(params)) {
+    const first = Array.isArray(value) ? value[0] : value;
+    if (typeof first === "string") search.set(key, first);
+  }
+  return search;
+}
+
 // src/resources/fields.ts
 var FieldsResource = class extends BaseResource {
   /**
@@ -6003,7 +6800,7 @@ function validateNotificationPreferences(preferences) {
 }
 
 // src/support/webhook-verifier.ts
-import { createHmac, timingSafeEqual } from "crypto";
+import { createHmac, timingSafeEqual as timingSafeEqual2 } from "crypto";
 var WebhookVerifier = class {
   webhookSecret;
   /**
@@ -6045,7 +6842,7 @@ var WebhookVerifier = class {
     const expected = createHmac("sha256", this.webhookSecret).update(buf).digest();
     const actual = Buffer.from(provided, "hex");
     try {
-      return timingSafeEqual(expected, actual);
+      return timingSafeEqual2(expected, actual);
     } catch {
       return false;
     }
@@ -6130,6 +6927,7 @@ var AssinafyClient = class _AssinafyClient {
   templates;
   tags;
   auth;
+  oauth;
   fields;
   signerDocuments;
   users;
@@ -6236,6 +7034,12 @@ var AssinafyClient = class _AssinafyClient {
       this.logger,
       this.publicAxiosInstance
     );
+    this.oauth = new OAuthResource(
+      this.axiosInstance,
+      void 0,
+      this.logger,
+      this.publicAxiosInstance
+    );
     this.fields = new FieldsResource(this.axiosInstance, this.defaultAccountId, this.logger);
     this.signerDocuments = new SignerDocumentsResource(
       this.publicAxiosInstance,
@@ -6672,6 +7476,8 @@ export {
   MAX_LIST_PAGE_SIZE,
   MAX_UPLOAD_BYTES,
   NetworkError,
+  OAuthError,
+  OAuthResource,
   SDK_USER_AGENT,
   SignerDocumentsResource,
   SignerResource,
@@ -6682,5 +7488,6 @@ export {
   WebhookResource,
   WebhookVerifier,
   WorkspaceResource,
-  buildAssignmentPayload
+  buildAssignmentPayload,
+  parseWwwAuthenticate
 };