@signsealer/sdk 1.0.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/LICENSE +21 -0
- package/README.md +310 -0
- package/dist/cjs/index.cjs +854 -0
- package/dist/cjs/index.cjs.map +1 -0
- package/dist/esm/index.d.ts +796 -0
- package/dist/esm/index.d.ts.map +1 -0
- package/dist/esm/index.js +846 -0
- package/dist/esm/index.js.map +1 -0
- package/package.json +42 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Mashdun LLC
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,310 @@
|
|
|
1
|
+
# @signsealer/sdk
|
|
2
|
+
|
|
3
|
+
The client for [SignSealer](https://signsealer.com) — signatures with the
|
|
4
|
+
evidence behind them.
|
|
5
|
+
|
|
6
|
+
**No dependencies.** `fetch` is in the runtime, and a signing SDK that drags a
|
|
7
|
+
HTTP library into somebody's build is a signing SDK that gets declined at
|
|
8
|
+
review. It runs anywhere `fetch` does: Node 18+, every edge runtime, and the
|
|
9
|
+
browser — though an API key belongs on a server.
|
|
10
|
+
|
|
11
|
+
```
|
|
12
|
+
npm install @signsealer/sdk
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
## Sending something to be signed
|
|
16
|
+
|
|
17
|
+
```ts
|
|
18
|
+
import { SignSealer } from "@signsealer/sdk";
|
|
19
|
+
|
|
20
|
+
const signsealer = new SignSealer({ apiKey: process.env.SIGNSEALER_KEY! });
|
|
21
|
+
|
|
22
|
+
const { document_id } = await signsealer.prepareDocument({
|
|
23
|
+
template_code: "rental-agreement",
|
|
24
|
+
values: { guest: "Dana Reyes", property: "River Bend Cabin" },
|
|
25
|
+
});
|
|
26
|
+
|
|
27
|
+
const { links } = await signsealer.send(document_id, [
|
|
28
|
+
{ email: "dana@example.com", full_name: "Dana Reyes" },
|
|
29
|
+
]);
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
`links` is the only time you see the tokens. They are stored as hashes, so a
|
|
33
|
+
lost link is replaced with a reminder rather than looked up.
|
|
34
|
+
|
|
35
|
+
## Three things it does that a hand-rolled client usually does not
|
|
36
|
+
|
|
37
|
+
**Retries the failures worth retrying, with an idempotency key.** Every write
|
|
38
|
+
that creates something gets one automatically, so a network blip does not
|
|
39
|
+
become a second waiver. A `422` is never retried — it will be refused the same
|
|
40
|
+
way every time, and the message says why. A `429` is retried *when the server
|
|
41
|
+
says to wait and the wait is short*: the rate-limit window is a minute, so
|
|
42
|
+
backing off by a guess of a quarter-second, a half and a second puts all three
|
|
43
|
+
attempts inside the same window and spends the next window's budget too. A
|
|
44
|
+
wait longer than `maxWaitMs` is not slept through — it comes back as
|
|
45
|
+
`error.retryAfter`, in seconds, for you to schedule rather than block on.
|
|
46
|
+
|
|
47
|
+
**Surfaces the API's own sentence.** `SignSealerError` carries `message`,
|
|
48
|
+
`hint`, `code` and `status`. The message is frequently the database's own
|
|
49
|
+
words, which are more specific than anything a client layer could write:
|
|
50
|
+
|
|
51
|
+
```ts
|
|
52
|
+
try {
|
|
53
|
+
await signsealer.prepareDocument({ template_code: "rental-agreement", values: {} });
|
|
54
|
+
} catch (e) {
|
|
55
|
+
if (e instanceof SignSealerError) {
|
|
56
|
+
console.error(e.message); // "no value for guest"
|
|
57
|
+
console.error(e.hint); // "A contract that ships with a placeholder…"
|
|
58
|
+
console.error(e.requestId); // quote this and we can find the request
|
|
59
|
+
}
|
|
60
|
+
}
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
**Keeps the request id.** Every response carries one.
|
|
64
|
+
|
|
65
|
+
**Watches the allowance for you.** On a plan with a fixed monthly allowance,
|
|
66
|
+
every send tells the client how many agreements are left, and the client keeps
|
|
67
|
+
it on `signsealer.agreementsRemaining` — `null` on a plan that bills for
|
|
68
|
+
overage, where there is nothing to count down. When the allowance is spent the
|
|
69
|
+
server answers `402`, not `429`, and `error.quotaExceeded` says so. That one is
|
|
70
|
+
never retried, by this client or any other worth using: the allowance comes
|
|
71
|
+
back when the billing period turns, and no amount of backing off will reach it.
|
|
72
|
+
Subscribe to `billing.quota_approaching` if you would rather hear about it
|
|
73
|
+
before the call that fails.
|
|
74
|
+
|
|
75
|
+
```ts
|
|
76
|
+
try {
|
|
77
|
+
await signsealer.send(documentId, signers);
|
|
78
|
+
if (signsealer.agreementsRemaining !== null && signsealer.agreementsRemaining < 5) {
|
|
79
|
+
notifyOps(`${signsealer.agreementsRemaining} agreements left this month`);
|
|
80
|
+
}
|
|
81
|
+
} catch (e) {
|
|
82
|
+
if (e instanceof SignSealerError && e.quotaExceeded) escalateToBilling(e.hint);
|
|
83
|
+
}
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
## The signer's side
|
|
87
|
+
|
|
88
|
+
`SignSealerSigning` takes **no API key**, because on those routes a signing
|
|
89
|
+
token is the whole credential. It is a separate class on purpose: a client that
|
|
90
|
+
could send a key alongside a token would be a client that widens somebody's
|
|
91
|
+
authority by accident.
|
|
92
|
+
|
|
93
|
+
```ts
|
|
94
|
+
import { SignSealerSigning } from "@signsealer/sdk";
|
|
95
|
+
|
|
96
|
+
const signing = new SignSealerSigning();
|
|
97
|
+
|
|
98
|
+
const link = await signing.link(token);
|
|
99
|
+
if (!link.ok) return show(link.reason); // written for a person to read
|
|
100
|
+
|
|
101
|
+
await signing.consent(token); // before signing, always
|
|
102
|
+
await signing.sign(token, "typed", "Dana Reyes");
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
Consent is a separate call and that is not an oversight: ESIGN requires consent
|
|
106
|
+
to electronic records to precede the transaction, and a system that records
|
|
107
|
+
both in the same instant cannot show that it did.
|
|
108
|
+
|
|
109
|
+
### When the business asks the signer for a code
|
|
110
|
+
|
|
111
|
+
A business can require a one-time code before a signature (Settings →
|
|
112
|
+
Signing). **If you do not handle this, signing simply fails for those
|
|
113
|
+
businesses** — `sign` is refused and nothing in your page would say why.
|
|
114
|
+
|
|
115
|
+
`link` tells you, and both halves are one call each:
|
|
116
|
+
|
|
117
|
+
```ts
|
|
118
|
+
const link = await signing.link(token);
|
|
119
|
+
|
|
120
|
+
if (link.verification_required) {
|
|
121
|
+
const sent = await signing.requestCode(token);
|
|
122
|
+
// sent.sent_to is masked: "d•••@example.com". Show it, do not store it.
|
|
123
|
+
|
|
124
|
+
const checked = await signing.confirmCode(token, digitsTheTyped);
|
|
125
|
+
if (!checked.ok) {
|
|
126
|
+
// An answer, not an error. `attempts_left` counts down from five.
|
|
127
|
+
return show(`That code is not right. ${checked.attempts_left} tries left.`);
|
|
128
|
+
}
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
await signing.consent(token);
|
|
132
|
+
await signing.sign(token, "typed", "Dana Reyes");
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
The code goes to the address or number the **link** went to, never one your
|
|
136
|
+
page collects — which is the whole point of it. It is not an identity check:
|
|
137
|
+
it proves control of that inbox or phone at the moment of signing, and the
|
|
138
|
+
certificate says `email_otp` or `sms_otp` rather than anything about who the
|
|
139
|
+
person is.
|
|
140
|
+
|
|
141
|
+
If you would rather not build a signing page, send the signer to
|
|
142
|
+
`https://api.signsealer.com/s/<token>` and skip all of it.
|
|
143
|
+
|
|
144
|
+
### A template that is a PDF
|
|
145
|
+
|
|
146
|
+
Some documents are a page rather than words, and those get signed where they
|
|
147
|
+
are. When the template behind a link is an uploaded PDF, `link.pages` lists its
|
|
148
|
+
pages and a field may carry a `place` — a rectangle in fractions of the page a
|
|
149
|
+
reader *sees*, origin top left, so it means the same thing at any image
|
|
150
|
+
resolution and any screen width.
|
|
151
|
+
|
|
152
|
+
```ts
|
|
153
|
+
const link = await signing.link(token);
|
|
154
|
+
|
|
155
|
+
for (const p of link.pages ?? []) {
|
|
156
|
+
const img = new Image();
|
|
157
|
+
img.src = signing.pageUrl(token, p.n); // no API key: the token is the credential
|
|
158
|
+
// …and position each field with a `place` over it, in percentages.
|
|
159
|
+
}
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
Draw the pages rather than `link.body` when there are any. A PDF template's
|
|
163
|
+
body is a sentence naming the file and its SHA-256 — it has to be, because the
|
|
164
|
+
certificate fingerprints the body and a PDF has no text to fingerprint — so
|
|
165
|
+
rendering it would show somebody a hash where their lease should be.
|
|
166
|
+
|
|
167
|
+
On the keyed side, `templatePdf(id)` says whether a template is one of these
|
|
168
|
+
and whether every page has been drawn:
|
|
169
|
+
|
|
170
|
+
```ts
|
|
171
|
+
const pdf = await client.templatePdf(templateId);
|
|
172
|
+
if (pdf.has_pdf && !pdf.ready) {
|
|
173
|
+
// page_count pages, drawn of them drawn. It cannot be published yet.
|
|
174
|
+
}
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
Uploading the file is a dashboard step, not an API call: the page pictures have
|
|
178
|
+
to be drawn by a browser, and a server does not have one — so a route that took
|
|
179
|
+
the bytes would leave a template that could never be published.
|
|
180
|
+
|
|
181
|
+
### Signing where there is no network
|
|
182
|
+
|
|
183
|
+
Pass `captured` with what the device thought the time was. The server records
|
|
184
|
+
when *it* received the event — that is the part we can attest to — and keeps
|
|
185
|
+
your claim beside it, marked as a claim, with the clock difference computed
|
|
186
|
+
rather than accepted.
|
|
187
|
+
|
|
188
|
+
```ts
|
|
189
|
+
await signing.sign(token, "drawn", dataUri, {
|
|
190
|
+
offline: true,
|
|
191
|
+
at: capturedAt.toISOString(),
|
|
192
|
+
device: "ipad-counter-2",
|
|
193
|
+
});
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
## Verifying a webhook
|
|
197
|
+
|
|
198
|
+
Every delivery carries three headers, and the body is signed as the exact bytes
|
|
199
|
+
sent — so verify **before** parsing. Parsing and re-serialising checks your own
|
|
200
|
+
formatter rather than ours, and two JSON serialisers disagree about key order
|
|
201
|
+
and unicode escapes eventually.
|
|
202
|
+
|
|
203
|
+
```ts
|
|
204
|
+
import { verifyWebhookRequest } from "@signsealer/sdk";
|
|
205
|
+
|
|
206
|
+
app.post("/hooks/signsealer",
|
|
207
|
+
express.raw({ type: "application/json" }), // the bytes, not the object
|
|
208
|
+
async (req, res) => {
|
|
209
|
+
const { ok, reason, eventId } = await verifyWebhookRequest({
|
|
210
|
+
secret: process.env.SIGNSEALER_WEBHOOK_SECRET!,
|
|
211
|
+
body: req.body.toString("utf8"),
|
|
212
|
+
headers: req.headers,
|
|
213
|
+
});
|
|
214
|
+
if (!ok) return res.status(400).send(reason);
|
|
215
|
+
|
|
216
|
+
// Deliveries are at-least-once: the same event id arrives again on a retry.
|
|
217
|
+
if (await alreadyHandled(eventId)) return res.sendStatus(200);
|
|
218
|
+
|
|
219
|
+
await act(JSON.parse(req.body.toString("utf8")));
|
|
220
|
+
res.sendStatus(200);
|
|
221
|
+
});
|
|
222
|
+
```
|
|
223
|
+
|
|
224
|
+
`verifyWebhook` is the same check without the header reading, if you have the
|
|
225
|
+
values already. Both are `async` because they use WebCrypto rather than
|
|
226
|
+
`node:crypto` — that is what keeps this package working in an edge runtime and
|
|
227
|
+
in the browser.
|
|
228
|
+
|
|
229
|
+
Three things it handles that a hand-written check usually does not:
|
|
230
|
+
|
|
231
|
+
- **The timestamp is inside the MAC**, and the five-minute window is enforced
|
|
232
|
+
in *both* directions. Accepting a delivery from the future lets somebody buy
|
|
233
|
+
an arbitrarily long replay window by choosing the timestamp.
|
|
234
|
+
- **A rotation sends two signatures.** During the grace window the header is
|
|
235
|
+
`v1=<new>,v1=<old>` so a receiver holding either secret still verifies. A
|
|
236
|
+
check written against one signature works perfectly until the first rotation
|
|
237
|
+
and then refuses every delivery.
|
|
238
|
+
- **Every part is compared, in constant time.** `===` on a hex string returns
|
|
239
|
+
as soon as it finds a difference, and how long that took says how many
|
|
240
|
+
characters were right.
|
|
241
|
+
|
|
242
|
+
### Rotating a secret, and replaying what was missed
|
|
243
|
+
|
|
244
|
+
```ts
|
|
245
|
+
const { secret } = await client.rotateWebhookSecret(endpointId);
|
|
246
|
+
// Returned once. For 24 hours deliveries are signed with both, so:
|
|
247
|
+
// store this, verify with both, then drop the old one.
|
|
248
|
+
|
|
249
|
+
const { deliveries } = await client.webhookDeliveries(endpointId);
|
|
250
|
+
await client.replayWebhookDelivery(deliveries[0].id);
|
|
251
|
+
```
|
|
252
|
+
|
|
253
|
+
A replay is a new delivery marked as repeating the original, for the afternoon
|
|
254
|
+
somebody's receiver was down. One still in the queue is refused, and so is a
|
|
255
|
+
second replay while the first is queued — a replay is not a way to send the
|
|
256
|
+
same event five times.
|
|
257
|
+
|
|
258
|
+
## Making a template
|
|
259
|
+
|
|
260
|
+
```ts
|
|
261
|
+
const { template_id } = await client.createTemplate({
|
|
262
|
+
code: "rental-agreement",
|
|
263
|
+
name: "Rental agreement",
|
|
264
|
+
kind: "contract",
|
|
265
|
+
body: "This agreement is between {{business}} and {{guest}}…",
|
|
266
|
+
variables: ["business", "guest"],
|
|
267
|
+
fields: [
|
|
268
|
+
{ key: "arrival_date", label: "Arrival", kind: "date" },
|
|
269
|
+
{ key: "vehicle_plate", label: "Vehicle plate", kind: "text", required: false },
|
|
270
|
+
],
|
|
271
|
+
});
|
|
272
|
+
```
|
|
273
|
+
|
|
274
|
+
Version 1, as a **draft**. A template is not usable until it is published, and
|
|
275
|
+
publishing is what freezes the text people will have signed — so there is no
|
|
276
|
+
`publish` method here on purpose. That is a decision somebody makes looking at
|
|
277
|
+
the words.
|
|
278
|
+
|
|
279
|
+
## Checking a certificate
|
|
280
|
+
|
|
281
|
+
No credential at all. Anybody holding the printed code can do this.
|
|
282
|
+
|
|
283
|
+
```ts
|
|
284
|
+
const result = await signing.verify("4KJ72M9PXQ3TVW8H");
|
|
285
|
+
// { certificate_found: true, still_matches_record: true, … }
|
|
286
|
+
```
|
|
287
|
+
|
|
288
|
+
`still_matches_record: false` means the record behind the certificate has
|
|
289
|
+
changed since it was issued. That is reported and never corrected — a
|
|
290
|
+
verification service that quietly re-derived could not answer the one question
|
|
291
|
+
it exists for.
|
|
292
|
+
|
|
293
|
+
## Options
|
|
294
|
+
|
|
295
|
+
```ts
|
|
296
|
+
new SignSealer({
|
|
297
|
+
apiKey: "mk_live_…",
|
|
298
|
+
baseUrl: "https://api.signsealer.com", // for a self-hosted deployment
|
|
299
|
+
maxAttempts: 3, // total, the first included
|
|
300
|
+
maxWaitMs: 5_000, // the longest Retry-After it will sit through
|
|
301
|
+
fetch: myFetch, // for tests, or a proxy
|
|
302
|
+
});
|
|
303
|
+
```
|
|
304
|
+
|
|
305
|
+
## Documentation
|
|
306
|
+
|
|
307
|
+
Full reference at [signsealer.com/docs](https://signsealer.com/docs/), and the
|
|
308
|
+
OpenAPI description at
|
|
309
|
+
[signsealer.com/openapi.json](https://signsealer.com/openapi.json) — generated
|
|
310
|
+
from the router, so it cannot drift from what the API validates.
|