@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/dist/esm/index.d.ts
CHANGED
|
@@ -138,8 +138,28 @@ export interface Account {
|
|
|
138
138
|
* applied. Each step is also sent as `texting.number_updated`.
|
|
139
139
|
*/
|
|
140
140
|
application?: TextingApplication | null;
|
|
141
|
+
/**
|
|
142
|
+
* Who texts the signers of documents this key sends (1.21.0):
|
|
143
|
+
* `signsealer` for the business's own keys; for a partner's access
|
|
144
|
+
* token, the partner's answer -- `partner` (your platform texts them and
|
|
145
|
+
* SignSealer sends none), `none`, or `signsealer`.
|
|
146
|
+
*/
|
|
147
|
+
sender?: TextingSender;
|
|
141
148
|
};
|
|
142
149
|
}
|
|
150
|
+
/** Who texts a document's signers (1.21.0). */
|
|
151
|
+
export type TextingSender = "signsealer" | "partner" | "none";
|
|
152
|
+
/** A business's choice of who texts for one partner app (1.21.0), as `setTextingSender` answers it. */
|
|
153
|
+
export interface TextingSenderChoice {
|
|
154
|
+
/** The app, `ss_client_…`. */
|
|
155
|
+
client_id: string;
|
|
156
|
+
name: string;
|
|
157
|
+
mode: "business_choice";
|
|
158
|
+
/** What the business chose. */
|
|
159
|
+
choice: TextingSender;
|
|
160
|
+
/** What applies now. */
|
|
161
|
+
sender: TextingSender;
|
|
162
|
+
}
|
|
143
163
|
/** Where a business's texting-number application has got to (1.13.0), as the account and `texting.number_updated` say. */
|
|
144
164
|
export interface TextingApplication {
|
|
145
165
|
/** `applied`, `submitted`, `in_review`, `needs_changes`, `verified`, `paused`, `failed`, and the steps of bringing a number. */
|
|
@@ -355,6 +375,14 @@ export interface Ask {
|
|
|
355
375
|
block_step?: boolean | null;
|
|
356
376
|
/** Where it is answered on an uploaded PDF's page (00243), in fractions of the page. */
|
|
357
377
|
place?: Place | null;
|
|
378
|
+
/** The one signer this question is for, by their `sign_order` (00685); absent, every signer's. */
|
|
379
|
+
recipient?: number | null;
|
|
380
|
+
/**
|
|
381
|
+
* The answer fills the blank of the same name in a written template's text
|
|
382
|
+
* (00699): `{{plate}}` for `plate`. A send may leave it out of `values`;
|
|
383
|
+
* the first signer answers it and their signature writes it in.
|
|
384
|
+
*/
|
|
385
|
+
blank?: boolean | null;
|
|
358
386
|
}
|
|
359
387
|
/**
|
|
360
388
|
* A rule about an answer, exactly one of these (00373, 00375): `equals` for a
|
|
@@ -586,6 +614,8 @@ export interface SignerLink {
|
|
|
586
614
|
delivery?: "send" | "embedded";
|
|
587
615
|
/** The person who signs for the business, and answers its own questions (1.16.0, 00611). */
|
|
588
616
|
for_business?: boolean;
|
|
617
|
+
/** Signed only by an approval from the application it was bound to (1.18.0, 00684); it has no link. */
|
|
618
|
+
application_bound?: true;
|
|
589
619
|
}
|
|
590
620
|
/** Who has signed one document (00340): names and states, nothing else. */
|
|
591
621
|
export interface DocumentSigners {
|
|
@@ -771,12 +801,16 @@ export interface Workflow {
|
|
|
771
801
|
template_code?: string;
|
|
772
802
|
template_published: boolean;
|
|
773
803
|
public_slug?: string | null;
|
|
774
|
-
/**
|
|
804
|
+
/**
|
|
805
|
+
* 00541: with what each question is, when it is not words, so a signer's
|
|
806
|
+
* condition can be about it. `address` (1.17.0, 00654): asked on the public
|
|
807
|
+
* form as street, city, state or region and ZIP, and written as one line.
|
|
808
|
+
*/
|
|
775
809
|
form_fields: Array<{
|
|
776
810
|
key: string;
|
|
777
811
|
label: string;
|
|
778
812
|
required?: boolean;
|
|
779
|
-
kind?: "text" | "email" | "phone" | "checkbox" | "choice" | "number" | "date" | "birthdate" | "time" | "datetime";
|
|
813
|
+
kind?: "text" | "email" | "phone" | "address" | "checkbox" | "choice" | "number" | "date" | "birthdate" | "time" | "datetime";
|
|
780
814
|
options?: string[];
|
|
781
815
|
}>;
|
|
782
816
|
/** Every blank a person starting it is asked (00478); `sender_fields` are the boxes whoever sends it fills. */
|
|
@@ -798,8 +832,41 @@ export interface Workflow {
|
|
|
798
832
|
party_ages?: "tick" | "dob";
|
|
799
833
|
majority_age?: number;
|
|
800
834
|
minors_also_sign?: boolean;
|
|
835
|
+
/** 1.17.0 (00670): one document the party shares, or a document for each person, each its own signing. */
|
|
836
|
+
party_documents?: "one" | "each";
|
|
801
837
|
/** 00476: the zone its documents' times are written in. */
|
|
802
838
|
time_zone?: string | null;
|
|
839
|
+
/**
|
|
840
|
+
* 1.17.0 (00654): a visitor who signs from the public address confirms the
|
|
841
|
+
* email they typed with a code first. Free, and not the one-time passcodes
|
|
842
|
+
* setting. A start through the API or a tablet is not asked.
|
|
843
|
+
*/
|
|
844
|
+
email_check?: boolean;
|
|
845
|
+
/**
|
|
846
|
+
* 1.17.0 (00654): the public address's limits, which a start through the
|
|
847
|
+
* API or a tablet is neither stopped by nor counted toward: stop after so
|
|
848
|
+
* many documents started from the address are signed; stop after a day
|
|
849
|
+
* (`YYYY-MM-DD`, on the form's own calendar); and the same email within so
|
|
850
|
+
* many days is emailed its signed copy again instead of a new document.
|
|
851
|
+
* Null is no limit.
|
|
852
|
+
*/
|
|
853
|
+
stop_after_signed?: number | null;
|
|
854
|
+
closes_on?: string | null;
|
|
855
|
+
once_within_days?: number | null;
|
|
856
|
+
/** 1.17.0 (00654): why the public address takes no more signatures, in a visitor's words; null while it does. */
|
|
857
|
+
closed?: string | null;
|
|
858
|
+
/**
|
|
859
|
+
* 1.17.0 (00654): a live public address that fails a check of its
|
|
860
|
+
* pre-flight: the first such check, in words, and whether visitors are
|
|
861
|
+
* stopped by it (told the form is not ready) or sign as before, with only a
|
|
862
|
+
* change to the form waiting for the fix. Null while it passes.
|
|
863
|
+
*/
|
|
864
|
+
needs_attention?: {
|
|
865
|
+
key: string;
|
|
866
|
+
says: string;
|
|
867
|
+
fix: string | null;
|
|
868
|
+
stops_visitors: boolean;
|
|
869
|
+
} | null;
|
|
803
870
|
}
|
|
804
871
|
export interface ClientOptions {
|
|
805
872
|
/**
|
|
@@ -996,6 +1063,19 @@ export declare class SignSealer {
|
|
|
996
1063
|
* nobody was handed. If the answer is lost, ask again when you need one.
|
|
997
1064
|
*/
|
|
998
1065
|
textingNumberInvitation(prefill?: TextingNumberPrefill): Promise<TextingNumberInvitation>;
|
|
1066
|
+
/**
|
|
1067
|
+
* Who texts the signers of documents sent through a partner's app, for a
|
|
1068
|
+
* partner whose dashboard leaves it to each business (1.21.0).
|
|
1069
|
+
*
|
|
1070
|
+
* As the partner, with the business's access token, leave `clientId` out:
|
|
1071
|
+
* the choice is yours for that business. With the business's own key, name
|
|
1072
|
+
* the app by its `ss_client_…` id (the key needs `signing:webhooks`). With
|
|
1073
|
+
* `partner` or `none`, SignSealer sends no texts for those documents -- no
|
|
1074
|
+
* link, no reminder, no confirmation -- while email and webhooks go on as
|
|
1075
|
+
* before; a one-time code a signer asks for is still sent. A PUT, so a
|
|
1076
|
+
* retry after a lost answer sets the same thing again.
|
|
1077
|
+
*/
|
|
1078
|
+
setTextingSender(sender: TextingSender, clientId?: string): Promise<TextingSenderChoice>;
|
|
999
1079
|
/**
|
|
1000
1080
|
* Documents, filtered and paged.
|
|
1001
1081
|
*
|
|
@@ -1092,6 +1172,29 @@ export declare class SignSealer {
|
|
|
1092
1172
|
}, idempotencyKey?: string): Promise<{
|
|
1093
1173
|
document_id: string;
|
|
1094
1174
|
}>;
|
|
1175
|
+
/**
|
|
1176
|
+
* A document from a PDF and the places to sign it, in one call (1.19.0,
|
|
1177
|
+
* 00685): the file is read, sanitised and drawn as a dashboard upload is,
|
|
1178
|
+
* kept as a one-time template, and the document prepared as a draft.
|
|
1179
|
+
* Each box is one `recipient`'s -- the `sign_order` you give that signer
|
|
1180
|
+
* on `send()` -- given in `fields` (fractions of the page, from its
|
|
1181
|
+
* top-left) or found from text tags in the file's words with
|
|
1182
|
+
* `text_tags: true` (`{{signature:1}}`, `{{date:1}}`, `{{initials:2}}`,
|
|
1183
|
+
* `{{text:1:Job number}}`, `{{checkbox:2:Label}}`). Needs `signing:templates`
|
|
1184
|
+
* and `signing:send` on the key. `pdf` is the file's bytes or its base64.
|
|
1185
|
+
*/
|
|
1186
|
+
documentFromPdf(input: {
|
|
1187
|
+
title: string;
|
|
1188
|
+
pdf: Uint8Array | string;
|
|
1189
|
+
filename?: string;
|
|
1190
|
+
fields?: PdfBox[];
|
|
1191
|
+
text_tags?: boolean;
|
|
1192
|
+
expires_at?: string;
|
|
1193
|
+
sequential?: boolean;
|
|
1194
|
+
external_ref?: string;
|
|
1195
|
+
metadata?: Record<string, string>;
|
|
1196
|
+
return_url?: string;
|
|
1197
|
+
}, idempotencyKey?: string): Promise<DocumentFromPdf>;
|
|
1095
1198
|
/**
|
|
1096
1199
|
* Send, and take the links back once.
|
|
1097
1200
|
*
|
|
@@ -1117,6 +1220,17 @@ export declare class SignSealer {
|
|
|
1117
1220
|
* date and name on an uploaded PDF -- are theirs, and nobody else's.
|
|
1118
1221
|
*/
|
|
1119
1222
|
for_business?: boolean;
|
|
1223
|
+
/**
|
|
1224
|
+
* This line is signed by an approval from the business's own
|
|
1225
|
+
* application, as this one of its people (1.18.0, 00684): `id` is the
|
|
1226
|
+
* application's, `subject` your id for the person, as your approvals
|
|
1227
|
+
* name them in `sub`. Needs `delivery: "embedded"`. The line gets no
|
|
1228
|
+
* link: its `token` and `url` are null and `application_bound` true.
|
|
1229
|
+
*/
|
|
1230
|
+
application?: {
|
|
1231
|
+
id: string;
|
|
1232
|
+
subject: string;
|
|
1233
|
+
};
|
|
1120
1234
|
}>, idempotencyKey?: string): Promise<{
|
|
1121
1235
|
links: SignerLink[];
|
|
1122
1236
|
}>;
|
|
@@ -1244,6 +1358,18 @@ export declare class SignSealer {
|
|
|
1244
1358
|
webhooks(): Promise<{
|
|
1245
1359
|
endpoints: unknown;
|
|
1246
1360
|
}>;
|
|
1361
|
+
/**
|
|
1362
|
+
* Make sure an endpoint is registered for an address (1.19.0, 00685): the
|
|
1363
|
+
* business's endpoint for `url`, its events and label set to these, or a
|
|
1364
|
+
* new one when it has none -- so calling it on every start-up never makes
|
|
1365
|
+
* a second. `created` says which; `secret` is there only when it is new.
|
|
1366
|
+
* An endpoint the business turned off stays off (`active`, `paused`).
|
|
1367
|
+
*/
|
|
1368
|
+
ensureWebhook(input: {
|
|
1369
|
+
url: string;
|
|
1370
|
+
events?: string[];
|
|
1371
|
+
label?: string;
|
|
1372
|
+
}): Promise<EnsuredWebhook>;
|
|
1247
1373
|
addWebhook(input: {
|
|
1248
1374
|
url: string;
|
|
1249
1375
|
events?: string[];
|
|
@@ -1415,6 +1541,62 @@ export declare class SignSealer {
|
|
|
1415
1541
|
report_id: string;
|
|
1416
1542
|
device_id: string;
|
|
1417
1543
|
}>;
|
|
1544
|
+
/**
|
|
1545
|
+
* The business's own applications whose servers vouch for their people's
|
|
1546
|
+
* approvals, each with its public keys (00684). Needs `signing:applications`.
|
|
1547
|
+
*/
|
|
1548
|
+
signingApplications(): Promise<SigningApplication[]>;
|
|
1549
|
+
/** Register an application. Then register the public key it signs approvals with. */
|
|
1550
|
+
addSigningApplication(name: string, idempotencyKey?: string): Promise<SigningApplication>;
|
|
1551
|
+
/**
|
|
1552
|
+
* Register a public key, as a JWK: EC P-256 for ES256, OKP Ed25519 for
|
|
1553
|
+
* EdDSA. Only the public half; one with `d` is refused. `kid` defaults to
|
|
1554
|
+
* the key's RFC 7638 thumbprint.
|
|
1555
|
+
*/
|
|
1556
|
+
addSigningApplicationKey(applicationId: string, input: {
|
|
1557
|
+
public_jwk: {
|
|
1558
|
+
kty: "EC" | "OKP";
|
|
1559
|
+
crv: "P-256" | "Ed25519";
|
|
1560
|
+
x: string;
|
|
1561
|
+
y?: string;
|
|
1562
|
+
};
|
|
1563
|
+
kid?: string;
|
|
1564
|
+
expires_at?: string;
|
|
1565
|
+
}, idempotencyKey?: string): Promise<SigningApplication>;
|
|
1566
|
+
/** Revoke a key: every approval it signed and has not sent is refused from now on. */
|
|
1567
|
+
revokeSigningApplicationKey(applicationId: string, keyId: string, reason: string): Promise<SigningApplication>;
|
|
1568
|
+
/** Disable an application: every approval from it is refused from now on. */
|
|
1569
|
+
disableSigningApplication(applicationId: string, reason: string): Promise<SigningApplication>;
|
|
1570
|
+
/**
|
|
1571
|
+
* Hand over one person's saved signature for one signing, server to
|
|
1572
|
+
* server (00684). The reference is single-use, short-lived and bound to
|
|
1573
|
+
* the application and the person; the image is never served back.
|
|
1574
|
+
* Possession of the reference authorises nothing on its own: only an
|
|
1575
|
+
* approval from the same application naming the same person, with
|
|
1576
|
+
* `signature.sha256` equal to `sha256` here, spends it. Needs
|
|
1577
|
+
* `signing:assert`.
|
|
1578
|
+
*/
|
|
1579
|
+
addSignatureReference(input: {
|
|
1580
|
+
application_id: string;
|
|
1581
|
+
subject: string;
|
|
1582
|
+
image: string;
|
|
1583
|
+
ttl_seconds?: number;
|
|
1584
|
+
}): Promise<SignatureReference>;
|
|
1585
|
+
/**
|
|
1586
|
+
* Sign with an approval your application's server signed (`createApproval`).
|
|
1587
|
+
* Recorded as authenticated by your application, never as an identity
|
|
1588
|
+
* SignSealer checked. The same approval sent again answers with the
|
|
1589
|
+
* signing it made (`replayed: true`); retried with the same idempotency
|
|
1590
|
+
* key, the stored answer. Needs `signing:assert`.
|
|
1591
|
+
*/
|
|
1592
|
+
signWithApproval(input: {
|
|
1593
|
+
assertion: string;
|
|
1594
|
+
signature: ApprovalSignature;
|
|
1595
|
+
}, idempotencyKey?: string): Promise<SigningTransaction>;
|
|
1596
|
+
/** One signing an approval made. */
|
|
1597
|
+
signingTransaction(id: string): Promise<SigningTransaction>;
|
|
1598
|
+
/** The signing an approval made, by your application's id and the approval's `jti`: for a client that lost the answer. */
|
|
1599
|
+
signingTransactionByApproval(applicationId: string, approvalId: string): Promise<SigningTransaction>;
|
|
1418
1600
|
}
|
|
1419
1601
|
export interface SigningLink {
|
|
1420
1602
|
ok: boolean;
|
|
@@ -2180,6 +2362,184 @@ export declare class SignSealerPartner {
|
|
|
2180
2362
|
/** Every closed month, newest first. */
|
|
2181
2363
|
statements(): Promise<PartnerStatement[]>;
|
|
2182
2364
|
}
|
|
2365
|
+
/** What a partner's app may ask a business for. Your client is registered with a subset; ask for no more than that. */
|
|
2366
|
+
export type OAuthScope = "signing:read" | "signing:write" | "signing:templates" | "signing:workflows" | "signing:webhooks" | "signing:subjects" | "signing:send" | "signing:remind" | "signing:links" | "signing:void";
|
|
2367
|
+
export interface OAuthOptions {
|
|
2368
|
+
/** Your OAuth client's id, `ss_client_…`. */
|
|
2369
|
+
clientId: string;
|
|
2370
|
+
/** Its secret, `ss_secret_…`: shown once, when the client was made or a new one was made on your partner dashboard. */
|
|
2371
|
+
clientSecret: string;
|
|
2372
|
+
/** Where `/oauth/authorize` and `/oauth/token` are. Default `https://api.signsealer.com`. */
|
|
2373
|
+
baseUrl?: string;
|
|
2374
|
+
fetch?: typeof globalThis.fetch;
|
|
2375
|
+
}
|
|
2376
|
+
/** A PKCE pair (RFC 7636): keep `verifier` for the exchange, send `challenge` to authorise. */
|
|
2377
|
+
export interface Pkce {
|
|
2378
|
+
verifier: string;
|
|
2379
|
+
challenge: string;
|
|
2380
|
+
method: "S256";
|
|
2381
|
+
}
|
|
2382
|
+
/**
|
|
2383
|
+
* The token endpoint's answer, as it sends it, with two additions.
|
|
2384
|
+
*
|
|
2385
|
+
* `access_token` is an API key (`mk_live_…`): hand it to `new SignSealer({
|
|
2386
|
+
* apiKey })`. `scopes` is `scope` split, and it is what the business
|
|
2387
|
+
* actually gave, which can be less than you asked for: a grant never holds
|
|
2388
|
+
* more than the person who made it may do. `expires_at` is absolute, worked
|
|
2389
|
+
* out from the moment the request was sent, so it errs early.
|
|
2390
|
+
*/
|
|
2391
|
+
export interface OAuthTokens {
|
|
2392
|
+
access_token: string;
|
|
2393
|
+
token_type: "Bearer";
|
|
2394
|
+
/** Seconds the access token lives: an hour. */
|
|
2395
|
+
expires_in: number;
|
|
2396
|
+
/** When the access token stops working, as an ISO time. */
|
|
2397
|
+
expires_at: string;
|
|
2398
|
+
scope: string;
|
|
2399
|
+
scopes: string[];
|
|
2400
|
+
/** Good once, for thirty days. Store it before you use `access_token`. Null for a client that is given none. */
|
|
2401
|
+
refresh_token: string | null;
|
|
2402
|
+
}
|
|
2403
|
+
/**
|
|
2404
|
+
* A refusal from the OAuth endpoints, or from the consent screen's answer.
|
|
2405
|
+
*
|
|
2406
|
+
* `code` is RFC 6749's `error` and `message` its `error_description` (both
|
|
2407
|
+
* also under their RFC names). Two questions decide what to do:
|
|
2408
|
+
*
|
|
2409
|
+
* - `reconnect`: the grant is over, or the code is spent. `invalid_grant`
|
|
2410
|
+
* -- the business disconnected you, the person who connected you can no
|
|
2411
|
+
* longer give what you hold, a token or code was used twice, or it
|
|
2412
|
+
* expired. Send the business through `authorizeUrl` again; nothing else
|
|
2413
|
+
* will bring it back.
|
|
2414
|
+
* - `transient`: the network or SignSealer, not your request. The grant may
|
|
2415
|
+
* well still be good. On a refresh, **whether the token was spent is
|
|
2416
|
+
* unknown**: read `refresh()` before deciding to send it again.
|
|
2417
|
+
*
|
|
2418
|
+
* `invalid_client` is neither: your client id or secret did not
|
|
2419
|
+
* authenticate, which is your configuration, for every business at once.
|
|
2420
|
+
*
|
|
2421
|
+
* `retryable` is always false. SignSealerError's "worth trying again
|
|
2422
|
+
* unchanged" is exactly the advice that turns a lost answer into a revoked
|
|
2423
|
+
* grant here.
|
|
2424
|
+
*/
|
|
2425
|
+
export declare class SignSealerOAuthError extends SignSealerError {
|
|
2426
|
+
constructor(status: number, code: string, message: string, requestId?: string, retryAfter?: number);
|
|
2427
|
+
/** RFC 6749's name for `code`. */
|
|
2428
|
+
get error(): string;
|
|
2429
|
+
/** RFC 6749's name for `message`. */
|
|
2430
|
+
get errorDescription(): string;
|
|
2431
|
+
get retryable(): boolean;
|
|
2432
|
+
/** The grant is over or the code spent: send the business to connect again. */
|
|
2433
|
+
get reconnect(): boolean;
|
|
2434
|
+
/** The network or SignSealer failed, not the request. On a refresh, the token may or may not have been spent. */
|
|
2435
|
+
get transient(): boolean;
|
|
2436
|
+
}
|
|
2437
|
+
/**
|
|
2438
|
+
* A fresh PKCE pair, one per authorise request: 32 random bytes as a
|
|
2439
|
+
* 43-character verifier, and its S256 challenge.
|
|
2440
|
+
*
|
|
2441
|
+
* Keep the verifier on your server, against the `state` you send (a
|
|
2442
|
+
* session, or a short-lived row), and give it to `exchangeCode`. Never put
|
|
2443
|
+
* it in the authorise address: the challenge goes there, and the verifier
|
|
2444
|
+
* is what proves the code came back to the same party that asked.
|
|
2445
|
+
*/
|
|
2446
|
+
export declare function createPkce(): Promise<Pkce>;
|
|
2447
|
+
/** The S256 challenge for a verifier: base64url of its SHA-256, without padding (RFC 7636, section 4.2). */
|
|
2448
|
+
export declare function pkceChallenge(verifier: string): Promise<string>;
|
|
2449
|
+
/**
|
|
2450
|
+
* "Connect with SignSealer", for a partner's server (1.20.0).
|
|
2451
|
+
*
|
|
2452
|
+
* ```ts
|
|
2453
|
+
* const oauth = new SignSealerOAuth({ clientId, clientSecret });
|
|
2454
|
+
* const { verifier, challenge } = await createPkce();
|
|
2455
|
+
* redirect(oauth.authorizeUrl({ redirectUri, scopes: ["signing:read", "signing:write"], state, codeChallenge: challenge }));
|
|
2456
|
+
* // …and on the way back:
|
|
2457
|
+
* const { code } = oauth.callback(request.url, savedState);
|
|
2458
|
+
* const tokens = await oauth.exchangeCode({ code, redirectUri, codeVerifier: verifier });
|
|
2459
|
+
* const client = new SignSealer({ apiKey: tokens.access_token });
|
|
2460
|
+
* ```
|
|
2461
|
+
*
|
|
2462
|
+
* The client is authenticated to `/oauth/token` by HTTP Basic, which RFC
|
|
2463
|
+
* 6749 prefers and the server reads first. Every token request is sent
|
|
2464
|
+
* exactly once: see `refresh()` for why that is the whole point.
|
|
2465
|
+
*/
|
|
2466
|
+
export declare class SignSealerOAuth {
|
|
2467
|
+
#private;
|
|
2468
|
+
constructor(opts: OAuthOptions);
|
|
2469
|
+
/**
|
|
2470
|
+
* Where to send the business's browser. SignSealer signs them in (or lets
|
|
2471
|
+
* them make an account and name their business on the way), shows your
|
|
2472
|
+
* registered name and what each scope allows, and sends them back to
|
|
2473
|
+
* `redirectUri` with `code` and your `state`, or with `error`.
|
|
2474
|
+
*
|
|
2475
|
+
* `redirectUri` must be one you registered, byte for byte, and the same
|
|
2476
|
+
* string you give `exchangeCode`. `state` is yours, returned untouched:
|
|
2477
|
+
* make it unguessable, keep it with the verifier, and check it in
|
|
2478
|
+
* `callback`. Ask for the fewest scopes that do the job; a scope your
|
|
2479
|
+
* client was not registered with is refused as `invalid_scope`.
|
|
2480
|
+
*/
|
|
2481
|
+
authorizeUrl(opts: {
|
|
2482
|
+
redirectUri: string;
|
|
2483
|
+
scopes: OAuthScope[];
|
|
2484
|
+
state: string;
|
|
2485
|
+
codeChallenge: string;
|
|
2486
|
+
}): string;
|
|
2487
|
+
/**
|
|
2488
|
+
* Read the consent screen's answer from your redirect's query: the code,
|
|
2489
|
+
* once `state` matches the one you kept. A business that pressed Not now
|
|
2490
|
+
* comes back as `access_denied`, and a request the screen could not
|
|
2491
|
+
* answer as its RFC 6749 error; both are thrown as SignSealerOAuthError,
|
|
2492
|
+
* with `status` 400. A `state` that does not match is `state_mismatch`:
|
|
2493
|
+
* do not exchange that code.
|
|
2494
|
+
*/
|
|
2495
|
+
callback(query: string | URL | URLSearchParams, expectedState: string): {
|
|
2496
|
+
code: string;
|
|
2497
|
+
};
|
|
2498
|
+
/**
|
|
2499
|
+
* Exchange the code from `callback` for the business's tokens. Do it at
|
|
2500
|
+
* once: a code lives sixty seconds and is good once.
|
|
2501
|
+
*
|
|
2502
|
+
* Sent once and never again. A code presented twice is a replay, and the
|
|
2503
|
+
* server revokes the grant it made, so a retry after a lost answer would
|
|
2504
|
+
* disconnect the business it just connected. If this throws `transient`,
|
|
2505
|
+
* send the business through `authorizeUrl` again.
|
|
2506
|
+
*/
|
|
2507
|
+
exchangeCode(opts: {
|
|
2508
|
+
code: string;
|
|
2509
|
+
redirectUri: string;
|
|
2510
|
+
codeVerifier: string;
|
|
2511
|
+
}): Promise<OAuthTokens>;
|
|
2512
|
+
/**
|
|
2513
|
+
* Swap a refresh token for a new access token **and a new refresh token**.
|
|
2514
|
+
*
|
|
2515
|
+
* **THIS IS NEVER RETRIED, AND YOU MUST NOT RETRY IT EITHER WITHOUT
|
|
2516
|
+
* THINKING.** The refresh token you send is spent the moment SignSealer
|
|
2517
|
+
* reads it. Presenting a spent one is treated as theft: the whole family
|
|
2518
|
+
* is revoked -- every refresh token from that connection, the grant, and
|
|
2519
|
+
* every access token issued under it -- and the business has to connect
|
|
2520
|
+
* again. From the server's side a buggy retry and a stolen token look the
|
|
2521
|
+
* same.
|
|
2522
|
+
*
|
|
2523
|
+
* So:
|
|
2524
|
+
*
|
|
2525
|
+
* 1. **Serialise refreshes per grant.** One at a time for each business
|
|
2526
|
+
* (a row lock, an advisory lock, a queue). Two workers refreshing the
|
|
2527
|
+
* same grant at once will end it.
|
|
2528
|
+
* 2. **Store the new refresh token before you use the access token**,
|
|
2529
|
+
* atomically, while still holding the lock. A new refresh token you
|
|
2530
|
+
* lose cannot be got back.
|
|
2531
|
+
* 3. **A `transient` failure leaves the token's state unknown.** If the
|
|
2532
|
+
* request reached SignSealer and the answer was lost, the token you
|
|
2533
|
+
* hold is spent and its successor lost with the answer; if it never
|
|
2534
|
+
* arrived, it is still good. Sending it again either works or ends
|
|
2535
|
+
* the connection (`reconnect`), which losing the successor had
|
|
2536
|
+
* already made inevitable. That is your decision, made under the
|
|
2537
|
+
* lock, never a loop.
|
|
2538
|
+
* 4. **`reconnect` means reconnect.** Mark the business disconnected and
|
|
2539
|
+
* ask them to connect again; do not try the token again.
|
|
2540
|
+
*/
|
|
2541
|
+
refresh(refreshToken: string): Promise<OAuthTokens>;
|
|
2542
|
+
}
|
|
2183
2543
|
export declare const WEBHOOK_EVENT_HEADER = "signsealer-event-id";
|
|
2184
2544
|
export declare const WEBHOOK_TIMESTAMP_HEADER = "signsealer-timestamp";
|
|
2185
2545
|
export declare const WEBHOOK_SIGNATURE_HEADER = "signsealer-signature";
|
|
@@ -2292,4 +2652,187 @@ export declare function verifyWebhookRequest(opts: {
|
|
|
2292
2652
|
}): Promise<WebhookVerification & {
|
|
2293
2653
|
eventId: string | null;
|
|
2294
2654
|
}>;
|
|
2655
|
+
/** A public key an application signs approvals with. */
|
|
2656
|
+
export interface SigningApplicationKey {
|
|
2657
|
+
id: string;
|
|
2658
|
+
kid: string;
|
|
2659
|
+
alg: "ES256" | "EdDSA";
|
|
2660
|
+
public_jwk: {
|
|
2661
|
+
kty: string;
|
|
2662
|
+
crv: string;
|
|
2663
|
+
x: string;
|
|
2664
|
+
y?: string;
|
|
2665
|
+
};
|
|
2666
|
+
created_at: string;
|
|
2667
|
+
expires_at: string | null;
|
|
2668
|
+
revoked_at: string | null;
|
|
2669
|
+
revoked_reason: string | null;
|
|
2670
|
+
}
|
|
2671
|
+
/** A business's own application, registered to vouch for its people (00684). */
|
|
2672
|
+
export interface SigningApplication {
|
|
2673
|
+
id: string;
|
|
2674
|
+
name: string;
|
|
2675
|
+
created_at: string;
|
|
2676
|
+
disabled_at: string | null;
|
|
2677
|
+
disabled_reason: string | null;
|
|
2678
|
+
keys: SigningApplicationKey[];
|
|
2679
|
+
}
|
|
2680
|
+
/** A saved signature handed over for one signing: spend it within `expires_at`. */
|
|
2681
|
+
export interface SignatureReference {
|
|
2682
|
+
/** Opaque, single-use. Authorises nothing on its own. */
|
|
2683
|
+
reference: string;
|
|
2684
|
+
/** SHA-256 of the image, hex: put it in the approval's `signature.sha256`. */
|
|
2685
|
+
sha256: string;
|
|
2686
|
+
expires_at: string;
|
|
2687
|
+
}
|
|
2688
|
+
/** The signature itself, as sent beside the approval. */
|
|
2689
|
+
export type ApprovalSignature = {
|
|
2690
|
+
method: "drawn";
|
|
2691
|
+
image: string;
|
|
2692
|
+
} | {
|
|
2693
|
+
method: "typed";
|
|
2694
|
+
text: string;
|
|
2695
|
+
} | {
|
|
2696
|
+
method: "saved";
|
|
2697
|
+
reference: string;
|
|
2698
|
+
};
|
|
2699
|
+
/** What an approval signed. */
|
|
2700
|
+
export interface SigningTransaction {
|
|
2701
|
+
transaction_id: string;
|
|
2702
|
+
/** The approval's `jti`. */
|
|
2703
|
+
approval_id: string;
|
|
2704
|
+
application_id: string;
|
|
2705
|
+
document_id: string;
|
|
2706
|
+
signer_id: string;
|
|
2707
|
+
event_id: string;
|
|
2708
|
+
subject: string;
|
|
2709
|
+
status: "signed";
|
|
2710
|
+
signed_at: string;
|
|
2711
|
+
/** Where the document has got to: `completed` once everybody has signed. */
|
|
2712
|
+
document_status: string;
|
|
2713
|
+
document_sha256: string;
|
|
2714
|
+
signature_method: "drawn" | "typed" | "saved";
|
|
2715
|
+
signature_sha256: string;
|
|
2716
|
+
/** Always this: the application vouched; SignSealer did not check the person. */
|
|
2717
|
+
authentication: "external_application";
|
|
2718
|
+
/** On `signWithApproval`: true when the same approval was sent again and this is the signing it already made. */
|
|
2719
|
+
replayed?: boolean;
|
|
2720
|
+
}
|
|
2721
|
+
/** One person's approval of one exact text, as your application's server states it. */
|
|
2722
|
+
export interface ApprovalInput {
|
|
2723
|
+
/** Your application's id in SignSealer. */
|
|
2724
|
+
applicationId: string;
|
|
2725
|
+
/** The business's id: `account().tenant_id`. */
|
|
2726
|
+
tenantId: string;
|
|
2727
|
+
documentId: string;
|
|
2728
|
+
/** The document's `body_sha256_hex` as the person was shown it. */
|
|
2729
|
+
documentSha256: string;
|
|
2730
|
+
/** Optional: the line, when you have it from the send. */
|
|
2731
|
+
signerId?: string;
|
|
2732
|
+
/** Your id for the person, as the line was bound to it, and their name. */
|
|
2733
|
+
person: {
|
|
2734
|
+
subject: string;
|
|
2735
|
+
name: string;
|
|
2736
|
+
};
|
|
2737
|
+
/** How they signed in to your application: RFC 8176 methods (`pwd`, `otp`, `hwk`...), a level if you have one, and when. */
|
|
2738
|
+
auth: {
|
|
2739
|
+
methods: string[];
|
|
2740
|
+
level?: string;
|
|
2741
|
+
at: Date | number;
|
|
2742
|
+
};
|
|
2743
|
+
/** When they pressed approve. */
|
|
2744
|
+
approvedAt: Date | number;
|
|
2745
|
+
/** The signature as you will send it beside the approval: its hash goes into the approval. */
|
|
2746
|
+
signature: {
|
|
2747
|
+
method: "drawn";
|
|
2748
|
+
image: string;
|
|
2749
|
+
} | {
|
|
2750
|
+
method: "typed";
|
|
2751
|
+
text: string;
|
|
2752
|
+
} | {
|
|
2753
|
+
method: "saved";
|
|
2754
|
+
sha256: string;
|
|
2755
|
+
};
|
|
2756
|
+
/** Recorded as supplied by your application, not as anything SignSealer saw. */
|
|
2757
|
+
ip?: string;
|
|
2758
|
+
device?: string;
|
|
2759
|
+
/** `online`. `offline` is described, and refused until it is accepted. */
|
|
2760
|
+
origin?: "online" | "offline";
|
|
2761
|
+
/** The approval's id; a random one when left out. Keep it to find the signing again. */
|
|
2762
|
+
approvalId?: string;
|
|
2763
|
+
/** Seconds the approval lives, at most 300. Default 120. */
|
|
2764
|
+
ttlSeconds?: number;
|
|
2765
|
+
}
|
|
2766
|
+
/** SHA-256 of a string's UTF-8, as lowercase hex: a signature's, or a document's text. */
|
|
2767
|
+
export declare function sha256Hex(text: string): Promise<string>;
|
|
2768
|
+
/**
|
|
2769
|
+
* Sign one approval with your application's private key: a compact JWS
|
|
2770
|
+
* that `signWithApproval` sends. `privateKey` is a WebCrypto key or a
|
|
2771
|
+
* private JWK -- ECDSA P-256 (ES256) or Ed25519 (EdDSA) -- and `kid` the
|
|
2772
|
+
* name you registered its public half under.
|
|
2773
|
+
*
|
|
2774
|
+
* Make one per approval, when the person approves, and send it at once: it
|
|
2775
|
+
* lives two minutes by default and five at most, and its `jti` is spent by
|
|
2776
|
+
* the signing it makes.
|
|
2777
|
+
*/
|
|
2778
|
+
export declare function createApproval(opts: {
|
|
2779
|
+
privateKey: CryptoKey | JsonWebKey;
|
|
2780
|
+
kid: string;
|
|
2781
|
+
approval: ApprovalInput;
|
|
2782
|
+
/** For tests: the clock, in milliseconds. */
|
|
2783
|
+
now?: number;
|
|
2784
|
+
}): Promise<{
|
|
2785
|
+
assertion: string;
|
|
2786
|
+
approvalId: string;
|
|
2787
|
+
claims: Record<string, unknown>;
|
|
2788
|
+
}>;
|
|
2789
|
+
/** A box on a page of a PDF: one recipient's, in fractions of the page as a reader sees it, from its top-left. */
|
|
2790
|
+
export interface PdfBox {
|
|
2791
|
+
kind: "signature" | "initials" | "date" | "text" | "checkbox";
|
|
2792
|
+
/** The `sign_order` you give that signer on `send()`. */
|
|
2793
|
+
recipient: number;
|
|
2794
|
+
/** Defaults to `signature_1`, `date_signed_1`, `text_1_2` and so on. */
|
|
2795
|
+
key?: string;
|
|
2796
|
+
/** A `date` box labelled `Date signed` (the default) is filled with the day they sign. */
|
|
2797
|
+
label?: string;
|
|
2798
|
+
required?: boolean;
|
|
2799
|
+
page: number;
|
|
2800
|
+
x: number;
|
|
2801
|
+
y: number;
|
|
2802
|
+
w: number;
|
|
2803
|
+
h: number;
|
|
2804
|
+
}
|
|
2805
|
+
export interface DocumentFromPdf {
|
|
2806
|
+
document_id: string;
|
|
2807
|
+
template_id: string;
|
|
2808
|
+
template_code: string;
|
|
2809
|
+
pages: number;
|
|
2810
|
+
/** SHA-256 of the file as kept: sanitised, which is what is sealed. */
|
|
2811
|
+
sha256: string;
|
|
2812
|
+
/** The recipient numbers its boxes are for: give each a signer of that `sign_order`. */
|
|
2813
|
+
recipients: number[];
|
|
2814
|
+
fields: Array<Required<Omit<PdfBox, "page" | "x" | "y" | "w" | "h">> & {
|
|
2815
|
+
place: {
|
|
2816
|
+
page: number;
|
|
2817
|
+
x: number;
|
|
2818
|
+
y: number;
|
|
2819
|
+
w: number;
|
|
2820
|
+
h: number;
|
|
2821
|
+
};
|
|
2822
|
+
from: "given" | "tag";
|
|
2823
|
+
}>;
|
|
2824
|
+
/** What was taken out of the file because it could act on its own. */
|
|
2825
|
+
removed: string[];
|
|
2826
|
+
}
|
|
2827
|
+
export interface EnsuredWebhook {
|
|
2828
|
+
id: string;
|
|
2829
|
+
created: boolean;
|
|
2830
|
+
/** Only when `created`: keep it, it is not shown again. */
|
|
2831
|
+
secret: string | null;
|
|
2832
|
+
url: string;
|
|
2833
|
+
events: string[];
|
|
2834
|
+
label: string | null;
|
|
2835
|
+
active: boolean;
|
|
2836
|
+
paused: boolean;
|
|
2837
|
+
}
|
|
2295
2838
|
//# sourceMappingURL=index.d.ts.map
|