@signsealer/sdk 1.16.0 → 1.22.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +149 -0
- package/README.md +356 -0
- package/dist/cjs/index.cjs +478 -1
- package/dist/cjs/index.cjs.map +1 -1
- package/dist/cjs/react.cjs +330 -0
- package/dist/cjs/react.cjs.map +1 -0
- package/dist/esm/index.d.ts +545 -2
- package/dist/esm/index.d.ts.map +1 -1
- package/dist/esm/index.js +471 -0
- package/dist/esm/index.js.map +1 -1
- package/dist/esm/react.d.ts +153 -0
- package/dist/esm/react.d.ts.map +1 -0
- package/dist/esm/react.js +321 -0
- package/dist/esm/react.js.map +1 -0
- package/package.json +19 -2
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,154 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 1.22.0
|
|
4
|
+
|
|
5
|
+
Nothing that worked before changes.
|
|
6
|
+
|
|
7
|
+
### Added
|
|
8
|
+
|
|
9
|
+
- `blank` on a template question (`Ask`, 00699): the answer fills the blank
|
|
10
|
+
of the same name in a written template's text, `{{plate}}` for `plate`.
|
|
11
|
+
A send may leave that blank out of `values`; the first signer answers it,
|
|
12
|
+
and their signature writes it into the text before it is fingerprinted.
|
|
13
|
+
- `recipient` on `Ask` (00685): the one signer a question is for, by their
|
|
14
|
+
`sign_order`. The engine already kept it; `POST /v1/templates` now does too.
|
|
15
|
+
|
|
16
|
+
## 1.21.0
|
|
17
|
+
|
|
18
|
+
Nothing that worked before changes.
|
|
19
|
+
|
|
20
|
+
### Added
|
|
21
|
+
|
|
22
|
+
- A partner's platform may text its businesses' signers itself (00692).
|
|
23
|
+
The partner decides on its dashboard: SignSealer texts them (as before,
|
|
24
|
+
and every partner's starting point), the partner does, or each business
|
|
25
|
+
chooses. For documents sent through the partner's app with a business's
|
|
26
|
+
access token, when the answer is the partner or nobody, SignSealer sends
|
|
27
|
+
no texts: no link, no reminder, no confirmation. Email and webhooks are
|
|
28
|
+
unchanged, and a one-time code a signer asks for is still sent.
|
|
29
|
+
- `setTextingSender(sender, clientId?)`: `PUT /v1/texting/sender`, the
|
|
30
|
+
business's choice where the partner leaves it to each business. With
|
|
31
|
+
the partner's own access token, `clientId` is left out. Type
|
|
32
|
+
`TextingSenderChoice`.
|
|
33
|
+
- `texting.sender` on `account()`: who texts the signers of what this key
|
|
34
|
+
sends. Type `TextingSender`.
|
|
35
|
+
- A partner client made from the partner form may now ask a business for
|
|
36
|
+
`signing:workflows` and `signing:webhooks` as well as `signing:read` and
|
|
37
|
+
`signing:write`.
|
|
38
|
+
|
|
39
|
+
## 1.20.0
|
|
40
|
+
|
|
41
|
+
Nothing that worked before changes.
|
|
42
|
+
|
|
43
|
+
### Added
|
|
44
|
+
|
|
45
|
+
- "Connect with SignSealer" for a partner's server (00090, 00207):
|
|
46
|
+
`SignSealerOAuth`, made with your OAuth client's `clientId` and
|
|
47
|
+
`clientSecret`.
|
|
48
|
+
- `createPkce()` makes a verifier and its S256 challenge, and
|
|
49
|
+
`pkceChallenge()` works out the challenge for a verifier, in WebCrypto
|
|
50
|
+
(Node 18 through `node:crypto`, every edge runtime).
|
|
51
|
+
- `authorizeUrl({ redirectUri, scopes, state, codeChallenge })` is where to
|
|
52
|
+
send the business's browser; `callback(query, state)` reads the answer,
|
|
53
|
+
checks `state` and gives the code.
|
|
54
|
+
- `exchangeCode({ code, redirectUri, codeVerifier })` and
|
|
55
|
+
`refresh(refreshToken)` post to `/oauth/token` as a form, the client by
|
|
56
|
+
HTTP Basic. The answer is the endpoint's, with `expires_at` (absolute)
|
|
57
|
+
and `scopes` (what the business actually gave) added. The access token
|
|
58
|
+
is an API key: `new SignSealer({ apiKey: tokens.access_token })`.
|
|
59
|
+
- **Neither is ever sent twice.** A refresh token or a code presented
|
|
60
|
+
again is treated as stolen and ends the connection, so these two calls
|
|
61
|
+
do not retry the way every other call in this package does. Serialise
|
|
62
|
+
refreshes per grant, and store the new refresh token before using the
|
|
63
|
+
access token.
|
|
64
|
+
- `SignSealerOAuthError`, a `SignSealerError` whose `error` and
|
|
65
|
+
`errorDescription` are RFC 6749's. `reconnect` is true for
|
|
66
|
+
`invalid_grant` (send the business through `authorizeUrl` again);
|
|
67
|
+
`transient` for the network, a `429` or a `5xx`, after which a
|
|
68
|
+
refresh token's state is unknown. `retryable` is always false.
|
|
69
|
+
- Types `OAuthOptions`, `OAuthScope`, `OAuthTokens` and `Pkce`.
|
|
70
|
+
|
|
71
|
+
## 1.19.0
|
|
72
|
+
|
|
73
|
+
Nothing that worked before changes.
|
|
74
|
+
|
|
75
|
+
### Added
|
|
76
|
+
|
|
77
|
+
- `documentFromPdf()` (00685): a document from a PDF and the places to sign
|
|
78
|
+
it, in one call. The file is read, sanitised and drawn as a dashboard
|
|
79
|
+
upload is, kept as a one-time template, and the document prepared as a
|
|
80
|
+
draft. Each box belongs to one `recipient`, the `sign_order` you give that
|
|
81
|
+
signer on `send()`. Boxes are given in `fields` or found from text tags in
|
|
82
|
+
the file's words (`{{signature:1}}`, `{{date:1}}`, `{{initials:2}}`,
|
|
83
|
+
`{{text:1:Label}}`, `{{checkbox:2:Label}}`). Types `PdfBox` and
|
|
84
|
+
`DocumentFromPdf`.
|
|
85
|
+
- `ensureWebhook()` (00685): makes sure an endpoint is registered for an
|
|
86
|
+
address. It is idempotent by the address itself, so calling it on every
|
|
87
|
+
start-up never makes a second endpoint. Type `EnsuredWebhook`.
|
|
88
|
+
|
|
89
|
+
## 1.18.0
|
|
90
|
+
|
|
91
|
+
Nothing that worked before changes: every addition is new, and the main entry
|
|
92
|
+
still has no dependencies.
|
|
93
|
+
|
|
94
|
+
### Added
|
|
95
|
+
|
|
96
|
+
- Trusted application signing (00684). A business's own application signs
|
|
97
|
+
its people's approvals with a key the business registered, and SignSealer
|
|
98
|
+
records the signature as authenticated by that application -- assurance
|
|
99
|
+
`external_application` -- never as an identity it checked.
|
|
100
|
+
- `signingApplications()`, `addSigningApplication()`,
|
|
101
|
+
`addSigningApplicationKey()`, `revokeSigningApplicationKey()`,
|
|
102
|
+
`disableSigningApplication()`, needing the new `signing:applications`
|
|
103
|
+
scope.
|
|
104
|
+
- `addSignatureReference()`: a saved signature handed over server to
|
|
105
|
+
server as a single-use, short-lived reference bound to the application
|
|
106
|
+
and the person. `signWithApproval()`, `signingTransaction()` and
|
|
107
|
+
`signingTransactionByApproval()`, needing the new `signing:assert` scope.
|
|
108
|
+
- `createApproval()` signs one approval with the application's private key
|
|
109
|
+
(ES256 or EdDSA, in WebCrypto) and `sha256Hex()` hashes a signature or a
|
|
110
|
+
text the way the API does.
|
|
111
|
+
- `application` on a signer given to `send()`, binding the line to the
|
|
112
|
+
application and the person; `application_bound` on the `SignerLink`,
|
|
113
|
+
whose `token` and `url` are then null.
|
|
114
|
+
- Types: `SigningApplication`, `SigningApplicationKey`,
|
|
115
|
+
`SignatureReference`, `SigningTransaction`, `ApprovalSignature`,
|
|
116
|
+
`ApprovalInput`.
|
|
117
|
+
- `@signsealer/sdk/react`, a new entry: `SignaturePad`, a React component
|
|
118
|
+
to draw (finger, stylus or mouse), type (in a signature face) or pick a
|
|
119
|
+
saved signature, clear and redraw, preview it, and apply it on an explicit
|
|
120
|
+
approval or cancel, with busy and error states, keyboard access and a
|
|
121
|
+
layout that fits a phone. React 18 or later is an optional peer
|
|
122
|
+
dependency of this entry only; nothing else imports React. Its state
|
|
123
|
+
(`padReducer`, `readiness`) and drawing helpers (`strokesToPng`,
|
|
124
|
+
`typedToPng`) are exported too.
|
|
125
|
+
|
|
126
|
+
## 1.17.0
|
|
127
|
+
|
|
128
|
+
### Added
|
|
129
|
+
|
|
130
|
+
- On each `Workflow` from `workflows()`, what a form's website link (its
|
|
131
|
+
public address) holds since 00654: `email_check`, a visitor confirming the
|
|
132
|
+
email they typed with a code before they sign (free, and not the one-time
|
|
133
|
+
passcodes setting); the link's limits `stop_after_signed`, `closes_on` and
|
|
134
|
+
`once_within_days`, which a start through the API or a tablet is neither
|
|
135
|
+
stopped by nor counted toward; `closed`, why the link takes no more
|
|
136
|
+
signatures, or null; and `needs_attention`, the first check of its
|
|
137
|
+
pre-flight a live link fails, with `stops_visitors` saying whether visitors
|
|
138
|
+
are turned away by it or sign as before.
|
|
139
|
+
- `"address"` among the kinds of a workflow's question: asked on the public
|
|
140
|
+
form as street, city, state or region and ZIP or postal code, and written
|
|
141
|
+
into the document as one line.
|
|
142
|
+
- `party_documents` on each `Workflow` (00670): on a form where everybody in
|
|
143
|
+
a booking's party signs, `"one"` document the whole party signs, or
|
|
144
|
+
`"each"` person a document of their own, with their own name in it and
|
|
145
|
+
each counted as a signing. The person who booked adds the others exactly
|
|
146
|
+
as before (`addParty`); with `"each"`, every link they get back is to that
|
|
147
|
+
person's own document.
|
|
148
|
+
- A start's `persons` is read from `fields` as well as `values` (00670), so
|
|
149
|
+
a caller that fills in `asked_fields` and adds `persons` beside them starts
|
|
150
|
+
a party.
|
|
151
|
+
|
|
3
152
|
## 1.16.0
|
|
4
153
|
|
|
5
154
|
### Added
|
package/README.md
CHANGED
|
@@ -268,6 +268,131 @@ await signing.sign(token, "drawn", dataUri, {
|
|
|
268
268
|
});
|
|
269
269
|
```
|
|
270
270
|
|
|
271
|
+
## Signing from inside your own application
|
|
272
|
+
|
|
273
|
+
When your application already signs its people in -- a field-service app, a
|
|
274
|
+
back office -- they can sign SignSealer documents without leaving it
|
|
275
|
+
(1.18.0). Your application vouches for the person; SignSealer checks your
|
|
276
|
+
application's signed approval and records the signature as **authenticated
|
|
277
|
+
by your application**, never as an identity SignSealer verified.
|
|
278
|
+
|
|
279
|
+
**Once**, with a key carrying `signing:applications`:
|
|
280
|
+
|
|
281
|
+
```ts
|
|
282
|
+
const admin = new SignSealer({ apiKey: process.env.SIGNSEALER_ADMIN_KEY });
|
|
283
|
+
const app = await admin.addSigningApplication("Field inspections");
|
|
284
|
+
// Your private key stays with you: register only its public half.
|
|
285
|
+
await admin.addSigningApplicationKey(app.id, { public_jwk: publicJwk }); // EC P-256 or Ed25519
|
|
286
|
+
```
|
|
287
|
+
|
|
288
|
+
**Each document**, on your server, with a key carrying `signing:assert` and
|
|
289
|
+
`signing:send`: bind the line to the person when you send it.
|
|
290
|
+
|
|
291
|
+
```ts
|
|
292
|
+
const { links } = await client.send(documentId, [{
|
|
293
|
+
email: "dana@example.com", full_name: "Dana Reyes", delivery: "embedded",
|
|
294
|
+
application: { id: app.id, subject: "emp_1042" }, // your id for the person
|
|
295
|
+
}]);
|
|
296
|
+
```
|
|
297
|
+
|
|
298
|
+
**In the browser**, show the document and the pad. It talks to nobody: what
|
|
299
|
+
the person approved goes to your server.
|
|
300
|
+
|
|
301
|
+
```tsx
|
|
302
|
+
import { SignaturePad } from "@signsealer/sdk/react";
|
|
303
|
+
|
|
304
|
+
<SignaturePad
|
|
305
|
+
signerName="Dana Reyes"
|
|
306
|
+
statement={link.intent_text}
|
|
307
|
+
savedSignatures={[{ id: "mine", label: "My saved signature", image: profile.signature_data }]}
|
|
308
|
+
onApply={(signature) => fetch("/api/sign", { method: "POST", body: JSON.stringify({ documentId, signature }) })
|
|
309
|
+
.then((r) => { if (!r.ok) throw new Error("That did not sign. Try again."); })}
|
|
310
|
+
onCancel={() => router.back()}
|
|
311
|
+
/>
|
|
312
|
+
```
|
|
313
|
+
|
|
314
|
+
Draw (finger, stylus or mouse), type (in a signature face: load the web fonts
|
|
315
|
+
you want and pass `fonts`), or pick a saved one; clear and redraw; a preview;
|
|
316
|
+
an explicit approve, and cancel. A promise from `onApply` holds it busy, and a
|
|
317
|
+
rejection is shown and can be approved again. React 18 or later is an
|
|
318
|
+
optional peer of this entry only: the main entry still imports nothing.
|
|
319
|
+
|
|
320
|
+
**On your server**, sign the approval and send it at once:
|
|
321
|
+
|
|
322
|
+
```ts
|
|
323
|
+
import { createApproval } from "@signsealer/sdk";
|
|
324
|
+
|
|
325
|
+
// A saved signature goes over server to server, never as a public URL.
|
|
326
|
+
const ref = signature.method === "saved"
|
|
327
|
+
? await client.addSignatureReference({ application_id: app.id, subject: "emp_1042", image: profile.signature_data })
|
|
328
|
+
: null;
|
|
329
|
+
|
|
330
|
+
const doc = await client.document(documentId); // the text the person was shown
|
|
331
|
+
const { assertion } = await createApproval({
|
|
332
|
+
privateKey, kid, // a CryptoKey or private JWK; the kid you registered
|
|
333
|
+
approval: {
|
|
334
|
+
applicationId: app.id, tenantId: (await client.account()).tenant_id,
|
|
335
|
+
documentId, documentSha256: doc.body_sha256_hex!,
|
|
336
|
+
person: { subject: "emp_1042", name: "Dana Reyes" },
|
|
337
|
+
auth: { methods: ["pwd", "otp"], level: "aal2", at: session.authenticatedAt },
|
|
338
|
+
approvedAt: new Date(),
|
|
339
|
+
signature: ref ? { method: "saved", sha256: ref.sha256 }
|
|
340
|
+
: signature.method === "typed" ? { method: "typed", text: signature.text }
|
|
341
|
+
: { method: "drawn", image: signature.image },
|
|
342
|
+
ip: request.ip, device: request.headers["user-agent"], // recorded as supplied by you
|
|
343
|
+
},
|
|
344
|
+
});
|
|
345
|
+
const signed = await client.signWithApproval({
|
|
346
|
+
assertion,
|
|
347
|
+
signature: ref ? { method: "saved", reference: ref.reference }
|
|
348
|
+
: signature.method === "typed" ? { method: "typed", text: signature.text }
|
|
349
|
+
: { method: "drawn", image: signature.image },
|
|
350
|
+
});
|
|
351
|
+
// signed.document_status === "completed" once everybody has signed
|
|
352
|
+
```
|
|
353
|
+
|
|
354
|
+
An approval lives two minutes (five at most), is bound to this business, to
|
|
355
|
+
the person's line and to the document's exact text: if the text changes
|
|
356
|
+
after the person approved -- another signer's signature writes in the date --
|
|
357
|
+
it is refused with 409 `document_changed`, and they approve again. Its `jti`
|
|
358
|
+
is spent once: the same approval sent again answers with the signing it made,
|
|
359
|
+
and another approval carrying it is refused with 409 `assertion_replayed`.
|
|
360
|
+
A refusal of the approval itself is 403 `assertion_rejected`, saying why.
|
|
361
|
+
`signingTransaction(id)` and `signingTransactionByApproval(appId, jti)` read
|
|
362
|
+
a signing back. No password, cookie or session token of yours ever crosses
|
|
363
|
+
over. Other languages: the REST flow is in `docs/APPLICATION_SIGNING.md`.
|
|
364
|
+
|
|
365
|
+
## A document from a PDF, for each of its recipients
|
|
366
|
+
|
|
367
|
+
When the document is a PDF you already have, with places for more than one
|
|
368
|
+
person to sign (1.19.0), create it in one call and send it:
|
|
369
|
+
|
|
370
|
+
```ts
|
|
371
|
+
const doc = await client.documentFromPdf({
|
|
372
|
+
title: "Service authorization — 12 Elm St",
|
|
373
|
+
pdf: fileBytes, // or its base64
|
|
374
|
+
text_tags: true, // {{signature:1}}, {{date:1}}, {{text:1:Job number}} in the file's words
|
|
375
|
+
fields: [ // and/or boxes given outright, in fractions of the page
|
|
376
|
+
{ kind: "signature", recipient: 2, page: 2, x: 0.1, y: 0.75, w: 0.3, h: 0.05 },
|
|
377
|
+
],
|
|
378
|
+
external_ref: "job-4471",
|
|
379
|
+
});
|
|
380
|
+
await client.send(doc.document_id, [
|
|
381
|
+
{ email: "casey@example.com", full_name: "Casey Customer", sign_order: 1, delivery: "embedded" },
|
|
382
|
+
{ email: "terry@example.com", full_name: "Terry Tech", sign_order: 2, delivery: "embedded" },
|
|
383
|
+
]);
|
|
384
|
+
```
|
|
385
|
+
|
|
386
|
+
Each box is its recipient's alone: the signer whose `sign_order` is its
|
|
387
|
+
number. A `signature` box is filled with their signature, and a `date` box
|
|
388
|
+
with the day they sign; the others are asked on their signing page. A send
|
|
389
|
+
that leaves a recipient with no signer is refused. Write text tags in white,
|
|
390
|
+
each as one run of text, so they do not show under the box.
|
|
391
|
+
|
|
392
|
+
Register your webhook on start-up with `ensureWebhook({ url, events })`. It
|
|
393
|
+
finds the endpoint for that address, or makes it once, and returns the
|
|
394
|
+
`secret` only the first time.
|
|
395
|
+
|
|
271
396
|
## Verifying a webhook
|
|
272
397
|
|
|
273
398
|
Every delivery carries three headers, and the body is signed as the exact bytes
|
|
@@ -448,6 +573,237 @@ changed since it was issued. That is reported and never corrected — a
|
|
|
448
573
|
verification service that quietly re-derived could not answer the one question
|
|
449
574
|
it exists for.
|
|
450
575
|
|
|
576
|
+
## Connecting a business with one click (OAuth)
|
|
577
|
+
|
|
578
|
+
When your product acts for *other* businesses' SignSealer accounts, they
|
|
579
|
+
connect it on SignSealer's consent screen rather than pasting you a key
|
|
580
|
+
(1.20.0). `SignSealerOAuth` is the partner's half: authorization code with
|
|
581
|
+
PKCE (S256, which SignSealer requires of every client), on your server,
|
|
582
|
+
with your OAuth client's id and secret. What comes back is an API key for
|
|
583
|
+
that one business, limited to what it agreed to.
|
|
584
|
+
|
|
585
|
+
**Send the business to SignSealer.** Make a PKCE pair and a `state` for each
|
|
586
|
+
attempt, keep both on your server, and redirect:
|
|
587
|
+
|
|
588
|
+
```ts
|
|
589
|
+
import { SignSealerOAuth, createPkce } from "@signsealer/sdk";
|
|
590
|
+
|
|
591
|
+
const oauth = new SignSealerOAuth({
|
|
592
|
+
clientId: process.env.SIGNSEALER_CLIENT_ID!, // ss_client_…
|
|
593
|
+
clientSecret: process.env.SIGNSEALER_CLIENT_SECRET!, // ss_secret_…, server only
|
|
594
|
+
});
|
|
595
|
+
const REDIRECT = "https://pos.example.com/oauth/signsealer"; // exactly as registered
|
|
596
|
+
|
|
597
|
+
app.get("/connect/signsealer", async (req, res) => {
|
|
598
|
+
const { verifier, challenge } = await createPkce();
|
|
599
|
+
const state = crypto.randomUUID();
|
|
600
|
+
await attempts.put(state, { verifier, tenantId: req.user.tenantId }, { ttlSeconds: 1800 });
|
|
601
|
+
res.redirect(oauth.authorizeUrl({
|
|
602
|
+
redirectUri: REDIRECT,
|
|
603
|
+
scopes: ["signing:read", "signing:write", "signing:workflows", "signing:webhooks"],
|
|
604
|
+
state,
|
|
605
|
+
codeChallenge: challenge,
|
|
606
|
+
}));
|
|
607
|
+
});
|
|
608
|
+
```
|
|
609
|
+
|
|
610
|
+
Keep the attempt for half an hour, not a minute: a business with no
|
|
611
|
+
SignSealer account can make one on the way, name its business and agree to
|
|
612
|
+
the terms, and SignSealer brings it back to the consent screen afterwards.
|
|
613
|
+
|
|
614
|
+
**The callback.** `callback` checks the `state` and gives you the code, or
|
|
615
|
+
throws the consent screen's error (`access_denied` when they pressed Not now).
|
|
616
|
+
Exchange the code at once: it lives sixty seconds and is good once.
|
|
617
|
+
|
|
618
|
+
```ts
|
|
619
|
+
import { SignSealer, SignSealerOAuthError } from "@signsealer/sdk";
|
|
620
|
+
|
|
621
|
+
app.get("/oauth/signsealer", async (req, res) => {
|
|
622
|
+
const attempt = await attempts.take(String(req.query.state ?? "")); // read once, then deleted
|
|
623
|
+
if (!attempt) return res.status(400).send("That connection has expired. Start again.");
|
|
624
|
+
try {
|
|
625
|
+
const { code } = oauth.callback(req.url, req.query.state as string);
|
|
626
|
+
const tokens = await oauth.exchangeCode({ code, redirectUri: REDIRECT, codeVerifier: attempt.verifier });
|
|
627
|
+
const account = await new SignSealer({ apiKey: tokens.access_token }).account();
|
|
628
|
+
await db.signsealer.upsert({
|
|
629
|
+
tenantId: attempt.tenantId,
|
|
630
|
+
businessId: account.tenant_id,
|
|
631
|
+
accessToken: seal(tokens.access_token), // encrypted at rest, never logged
|
|
632
|
+
refreshToken: seal(tokens.refresh_token!),
|
|
633
|
+
expiresAt: tokens.expires_at,
|
|
634
|
+
scopes: tokens.scopes, // what they gave, which can be less than you asked
|
|
635
|
+
needsReconnect: false,
|
|
636
|
+
});
|
|
637
|
+
res.redirect("/settings/signing?connected=1");
|
|
638
|
+
} catch (e) {
|
|
639
|
+
if (e instanceof SignSealerOAuthError) return res.redirect(`/settings/signing?error=${e.error}`);
|
|
640
|
+
throw e;
|
|
641
|
+
}
|
|
642
|
+
});
|
|
643
|
+
```
|
|
644
|
+
|
|
645
|
+
`tokens.scopes` is what the business actually granted. A grant never holds
|
|
646
|
+
more than the person who made it may do themselves, so check it before
|
|
647
|
+
offering a feature that needs a scope you asked for.
|
|
648
|
+
|
|
649
|
+
**Refresh, one at a time.** An access token lives an hour; refresh it a
|
|
650
|
+
little before `expires_at`. **The SDK never retries a refresh, and neither
|
|
651
|
+
should you.** Each refresh token is good once: the answer carries the next
|
|
652
|
+
one, and presenting a spent one revokes the whole connection, every token
|
|
653
|
+
under it, and the business has to connect again. So serialise refreshes per
|
|
654
|
+
business, and store the new refresh token before using the new access token,
|
|
655
|
+
inside the same lock:
|
|
656
|
+
|
|
657
|
+
```ts
|
|
658
|
+
async function clientFor(tenantId: string): Promise<SignSealer> {
|
|
659
|
+
return db.transaction(async (tx) => {
|
|
660
|
+
const row = await tx.signsealer.forUpdate(tenantId); // the lock: one refresh per grant
|
|
661
|
+
if (row.needsReconnect) throw new NeedsReconnect(tenantId);
|
|
662
|
+
if (Date.parse(row.expiresAt) - Date.now() > 5 * 60_000) {
|
|
663
|
+
return new SignSealer({ apiKey: unseal(row.accessToken) });
|
|
664
|
+
}
|
|
665
|
+
try {
|
|
666
|
+
const t = await oauth.refresh(unseal(row.refreshToken));
|
|
667
|
+
await tx.signsealer.update(tenantId, { // stored before it is used
|
|
668
|
+
accessToken: seal(t.access_token), refreshToken: seal(t.refresh_token!),
|
|
669
|
+
expiresAt: t.expires_at, scopes: t.scopes,
|
|
670
|
+
});
|
|
671
|
+
return new SignSealer({ apiKey: t.access_token });
|
|
672
|
+
} catch (e) {
|
|
673
|
+
if (e instanceof SignSealerOAuthError && e.reconnect) {
|
|
674
|
+
await tx.signsealer.update(tenantId, { needsReconnect: true });
|
|
675
|
+
throw new NeedsReconnect(tenantId);
|
|
676
|
+
}
|
|
677
|
+
throw e; // e.transient: see below. Never a loop.
|
|
678
|
+
}
|
|
679
|
+
});
|
|
680
|
+
}
|
|
681
|
+
```
|
|
682
|
+
|
|
683
|
+
`SignSealerOAuthError` carries RFC 6749's `error` and `errorDescription`, and
|
|
684
|
+
two flags that decide what happens next:
|
|
685
|
+
|
|
686
|
+
- **`reconnect`**: `invalid_grant`. The business disconnected you, the person
|
|
687
|
+
who connected you left or can no longer give what you hold, or a token was
|
|
688
|
+
used twice. Ask the business to connect again.
|
|
689
|
+
- **`transient`**: the network, a `429` or a `5xx`. The connection may well
|
|
690
|
+
be fine, but **whether the refresh token was spent is unknown**: if the
|
|
691
|
+
request arrived and the answer was lost, it is spent and its successor went
|
|
692
|
+
with the answer. Sending it once more, later and under the same lock,
|
|
693
|
+
either works or ends the connection, which losing the successor had
|
|
694
|
+
already made certain. That is a decision for your code to make knowingly,
|
|
695
|
+
not a retry loop.
|
|
696
|
+
|
|
697
|
+
`invalid_client` is neither: your client id or secret was refused, which is
|
|
698
|
+
your configuration and affects every business at once. `retryable` is
|
|
699
|
+
`false` on every OAuth error.
|
|
700
|
+
|
|
701
|
+
**A `401` from the API means reconnect.** A business can end the connection at
|
|
702
|
+
any moment, and its tokens stop working that minute, not at the end of the
|
|
703
|
+
hour. Refreshing ahead of `expires_at` means an unexpired token answered `401`
|
|
704
|
+
has been revoked:
|
|
705
|
+
|
|
706
|
+
```ts
|
|
707
|
+
try {
|
|
708
|
+
await (await clientFor(tenantId)).send(documentId, signers);
|
|
709
|
+
} catch (e) {
|
|
710
|
+
if (e instanceof SignSealerError && e.status === 401) {
|
|
711
|
+
await db.signsealer.update(tenantId, { needsReconnect: true }); // show "Reconnect SignSealer"
|
|
712
|
+
} else throw e;
|
|
713
|
+
}
|
|
714
|
+
```
|
|
715
|
+
|
|
716
|
+
The [OAuth reference](https://signsealer.com/docs/authentication) has the
|
|
717
|
+
endpoints themselves.
|
|
718
|
+
|
|
719
|
+
## Onboarding a business
|
|
720
|
+
|
|
721
|
+
What to ask for, and what a business needs in place before signing works
|
|
722
|
+
inside your product.
|
|
723
|
+
|
|
724
|
+
**Scopes.** Ask for the fewest that do the job; a consent screen that asks
|
|
725
|
+
for everything is one people decline. For e-signing and waivers:
|
|
726
|
+
|
|
727
|
+
| Scope | Why you need it |
|
|
728
|
+
| --- | --- |
|
|
729
|
+
| `signing:read` | `account()` (including `frame_origins`), documents, signers, PDFs and certificates, the list of workflows |
|
|
730
|
+
| `signing:write` | prepare and `send()` documents, `embedLink()`, remind, void. If your client was registered with its parts, `signing:send` and `signing:links` are the minimum |
|
|
731
|
+
| `signing:workflows` | `startWorkflow()`: a waiver from one of the business's forms |
|
|
732
|
+
| `signing:webhooks` | `ensureWebhook()` on the business, to hear `signing.completed` rather than poll |
|
|
733
|
+
|
|
734
|
+
Add `signing:subjects` only if you sync reservations and their packets
|
|
735
|
+
(`upsertReservation`, `startPacket`), and `signing:templates` only if you
|
|
736
|
+
make templates or use `documentFromPdf()`. Your client can ask only for the
|
|
737
|
+
scopes SignSealer registered it with, and anything else comes back as
|
|
738
|
+
`error=invalid_scope`. A client made from the partner form is registered with
|
|
739
|
+
`signing:read`, `signing:write`, `signing:workflows` and `signing:webhooks`
|
|
740
|
+
(1.21.0); write to partners@signsealer.com for the others. The person pressing Connect must be able to manage API keys on that
|
|
741
|
+
business (an owner or admin, unless given it), and a scope they could not
|
|
742
|
+
use themselves is left out of the grant.
|
|
743
|
+
|
|
744
|
+
**Where the signing page can be framed.** An embedded signing page
|
|
745
|
+
(`delivery: "embedded"`, then `embedLink()`) shows only inside a site the
|
|
746
|
+
business has proven is its own; anywhere else the browser leaves the frame
|
|
747
|
+
empty. `frame_origins` on `account()` and on each `embedLink()` lists them:
|
|
748
|
+
|
|
749
|
+
```ts
|
|
750
|
+
const { frame_origins } = await client.account();
|
|
751
|
+
// ["https://pos.example.com", "https://dockside.example", "https://*.dockside.example"]
|
|
752
|
+
```
|
|
753
|
+
|
|
754
|
+
There are three ways onto that list:
|
|
755
|
+
|
|
756
|
+
- **Your app, once connected.** The host of each of your redirect addresses
|
|
757
|
+
is added for every business that connects you, exactly that host and no
|
|
758
|
+
other. Register a redirect on the host your product frames the page on and
|
|
759
|
+
embedded signing there works with nothing for the business to do.
|
|
760
|
+
- **A company sign-in domain** the business proves in the dashboard under
|
|
761
|
+
[Settings → Single sign-on](https://app.signsealer.com/settings/sso): that
|
|
762
|
+
domain and every host under it, which is how a page on its own main site
|
|
763
|
+
qualifies.
|
|
764
|
+
- **A signing domain** it verifies under
|
|
765
|
+
[Settings → Your own domains](https://app.signsealer.com/settings#domains)
|
|
766
|
+
(with white label): that host and the hosts under it.
|
|
767
|
+
|
|
768
|
+
Check `frame_origins` before showing a frame, and open the link in a new tab
|
|
769
|
+
when the page's site is not on it. The owner-facing steps are in the help
|
|
770
|
+
pages, not here: [Signing inside your product](https://signsealer.com/docs/embedding),
|
|
771
|
+
[Branding and your own domains](https://signsealer.com/docs/branding), and
|
|
772
|
+
[Teams, roles and sign-in](https://signsealer.com/docs/teams) for who may
|
|
773
|
+
connect an app and where a business sees and ends it (Integrations →
|
|
774
|
+
Connected apps).
|
|
775
|
+
|
|
776
|
+
**Who texts the signers.** SignSealer texts a signer the link and one
|
|
777
|
+
reminder where it holds their consent. Your platform may do that instead
|
|
778
|
+
(1.21.0): on your partner dashboard choose SignSealer, your platform, or each
|
|
779
|
+
business. For documents sent with a business's access token, when the answer
|
|
780
|
+
is your platform or nobody, SignSealer sends those signers no texts at all,
|
|
781
|
+
reminders included; email goes as before, and the webhooks are how you hear
|
|
782
|
+
what to text. A one-time code a signer asks for is always sent by SignSealer.
|
|
783
|
+
|
|
784
|
+
```ts
|
|
785
|
+
const { texting } = await client.account();
|
|
786
|
+
texting?.sender; // "partner": text the links yourself; "signsealer": we do; "none": nobody does
|
|
787
|
+
|
|
788
|
+
// Where your dashboard leaves it to each business, record its answer with its token:
|
|
789
|
+
await client.setTextingSender("partner");
|
|
790
|
+
```
|
|
791
|
+
|
|
792
|
+
When `texting.sender` is `partner`, the business needs no texting number of
|
|
793
|
+
its own for these documents, so do not show it `textingNumberInvitation`.
|
|
794
|
+
|
|
795
|
+
**A business with no account yet.** It can make one from the consent screen
|
|
796
|
+
itself, as above, and the emailed link brings it back to your consent screen
|
|
797
|
+
even when it is opened on another device. To send one to SignSealer first, with the business counted
|
|
798
|
+
as yours, use your signup link:
|
|
799
|
+
|
|
800
|
+
```ts
|
|
801
|
+
import { SignSealerPartner } from "@signsealer/sdk";
|
|
802
|
+
|
|
803
|
+
SignSealerPartner.signupUrl("deckpos");
|
|
804
|
+
// "https://app.signsealer.com/signup?partner=deckpos"
|
|
805
|
+
```
|
|
806
|
+
|
|
451
807
|
## For partners: what you have earned
|
|
452
808
|
|
|
453
809
|
A platform SignSealer has enrolled as a partner shares in the revenue of every
|