@btps/sdk 1.2.0-rc.1 → 1.2.0-rc.3
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 +108 -0
- package/dist/client/index.d.ts +1 -0
- package/dist/client/index.js +7 -1
- package/dist/core/crypto/decryptVerify.js +6 -2
- package/dist/core/crypto/types.d.ts +3 -0
- package/dist/core/server/constants/btps-protocol.js +4 -2
- package/dist/core/server/constants/currency.d.ts +6 -0
- package/dist/core/server/constants/currency.js +27 -2
- package/dist/core/server/constants/limits.d.ts +25 -0
- package/dist/core/server/constants/limits.js +27 -0
- package/dist/core/server/constants/permissions.d.ts +1 -1
- package/dist/core/server/schemas/artifacts/transporterSchema.js +16 -9
- package/dist/core/server/schemas/boundView.d.ts +9 -0
- package/dist/core/server/schemas/boundView.js +28 -0
- package/dist/core/server/schemas/boundViewBindings.d.ts +40 -0
- package/dist/core/server/schemas/boundViewBindings.js +128 -0
- package/dist/core/server/schemas/boundViewChecks.d.ts +49 -0
- package/dist/core/server/schemas/boundViewChecks.js +344 -0
- package/dist/core/server/schemas/boundViewSchema.d.ts +1637 -0
- package/dist/core/server/schemas/boundViewSchema.js +186 -0
- package/dist/core/server/schemas/btpsDocsSchema.d.ts +37094 -8000
- package/dist/core/server/schemas/btpsDocsSchema.js +62 -44
- package/dist/core/server/schemas/helpers.d.ts +11604 -2312
- package/dist/core/trust/types.d.ts +11 -1
- package/dist/server/btpsServer.d.ts +11 -1
- package/dist/server/btpsServer.js +45 -5
- package/dist/server/index.d.ts +1 -0
- package/dist/server/index.js +9 -1
- package/dist/server/types.d.ts +31 -26
- package/package.json +14 -1
package/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,114 @@ All notable changes to `@btps/sdk` and the BTPS protocol it implements. The
|
|
|
4
4
|
format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
|
|
5
5
|
versions follow [Semantic Versioning](https://semver.org/).
|
|
6
6
|
|
|
7
|
+
## [1.2.0-rc.3] — 2026-11-15 (beta, release candidate)
|
|
8
|
+
|
|
9
|
+
BoundView: a document's own look, signed with it, every fact drawn from its
|
|
10
|
+
signed data. It replaces rc.1's templates. Everything in rc.2 and rc.1 below
|
|
11
|
+
still holds, except where this section changes it.
|
|
12
|
+
|
|
13
|
+
### Added
|
|
14
|
+
|
|
15
|
+
- **BoundView.** A document may carry its BoundView in
|
|
16
|
+
`boundView` (`BTPBoundView`), `1.2.0` only: a canvas captured from the
|
|
17
|
+
sender's own preview, signed with the document, so the receiver sees what
|
|
18
|
+
the sender saw. Text that shows a fact binds a signed field and is drawn from
|
|
19
|
+
it, never carried as text; fonts travel as glyph outlines and images as
|
|
20
|
+
pixels, so nothing is fetched and no font or image file is parsed. A
|
|
21
|
+
receiver checks a BoundView wherever the document is opened (`checkBoundView`): a
|
|
22
|
+
BoundView that breaks its schema or a limit, or binds a missing field, is refused
|
|
23
|
+
with the document; one that hides, shrinks or leaves out a key fact is not
|
|
24
|
+
shown, and the receiver shows its own view of the data. `decryptVerify`
|
|
25
|
+
returns whether an opened document's BoundView may be shown (`boundView`,
|
|
26
|
+
`BTPBoundViewResult`), and a server hands its transporter handlers the same,
|
|
27
|
+
once an artifact's signature and trust are checked. `checkBoundView` and
|
|
28
|
+
`writtenValue` are exported from `@btps/sdk/server` and `@btps/sdk/client`.
|
|
29
|
+
Images inflate with fflate, a new dependency (MIT, no dependencies of its
|
|
30
|
+
own), stopping once past their stated length. Specified on the new
|
|
31
|
+
BoundView pages, with golden vectors for the schema in
|
|
32
|
+
`documents-1.2.vectors.json` and for the checks in `boundview.vectors.json`.
|
|
33
|
+
A BoundView is optional: without one, a receiver shows its own view of the
|
|
34
|
+
data.
|
|
35
|
+
- **`@btps/boundview`, a new package.** `snapshotBoundView` captures a
|
|
36
|
+
platform's own HTML preview as a BoundView in the browser: every fact found
|
|
37
|
+
by its value, fonts read as glyph outlines, images as pixels, an SVG logo as
|
|
38
|
+
outlines when they draw as the browser drew it. It throws
|
|
39
|
+
`BoundViewSnapshotError` with what a receiver would refuse or not show.
|
|
40
|
+
`renderBoundView` draws a received one with resvg compiled to WebAssembly,
|
|
41
|
+
handed only checked values, and gives a PNG, the same bytes everywhere
|
|
42
|
+
(`boundview-pictures.vectors.json`), or null when a check fails. It bundles
|
|
43
|
+
open-licence glyph outlines for label fallbacks and typed signatures.
|
|
44
|
+
- **`@btps/sdk/boundview`.** A BoundView's schema, bindings and checks alone,
|
|
45
|
+
for a browser or app without the rest of the SDK.
|
|
46
|
+
- **Totals, line roles and the recipient.** An invoice or receipt may carry
|
|
47
|
+
`subtotalAmount` and `taxAmount`, and name what each line-item column holds
|
|
48
|
+
(`lineItems.roles`, `BTPLineRole`); an invoice, receipt, letter or agreement
|
|
49
|
+
may name its `recipient`. `1.2.0` only.
|
|
50
|
+
- **A letter's signatory.** A letter or an agreement may carry `signatory`
|
|
51
|
+
(`BTPSignatory`), `1.2.0` only: a name, a title, and a visual signature,
|
|
52
|
+
typed (drawn in the open-licence script font Caveat) or drawn as integer
|
|
53
|
+
strokes on a 1,000 by 300 canvas, never markup. Such a signature is
|
|
54
|
+
decoration and proves no agreement.
|
|
55
|
+
|
|
56
|
+
### Changed
|
|
57
|
+
|
|
58
|
+
- **`template` is `1.1.0` only.** A `1.1.0` invoice or receipt's `template`
|
|
59
|
+
is read as 1.1 reads it, `{ name, data }` with free data, and nothing is
|
|
60
|
+
drawn from it. A `1.2.0` artifact with one is refused: "template is 1.1.0
|
|
61
|
+
only; in 1.2.0 a document's look is its boundView". A document with a
|
|
62
|
+
`template` and nothing from 1.2 is still sent as `1.1.0`; once a platform
|
|
63
|
+
adds anything from 1.2 to it, its own SDK refuses it until `template` is
|
|
64
|
+
removed. See Migrating from 1.1 to 1.2, Dropping `template`.
|
|
65
|
+
|
|
66
|
+
### Removed
|
|
67
|
+
|
|
68
|
+
- **Templates by reference, and template formats 1 and 2** (rc.1). A `1.2.0`
|
|
69
|
+
template's named data fields (`version`, `sha256`, `source`, `logo`), a
|
|
70
|
+
letter's or payslip's template, and a letter template's signature values
|
|
71
|
+
(`template.data.values`, `BTPTemplateValues`) are gone: a document's look is
|
|
72
|
+
its BoundView, and a letter's sign-off its `signatory`. Removed with them:
|
|
73
|
+
the Templates page, `schemas/btps-template.schema.json` and
|
|
74
|
+
`templates.vectors.json`.
|
|
75
|
+
|
|
76
|
+
## [1.2.0-rc.2] — 2026-11-11 (beta, release candidate)
|
|
77
|
+
|
|
78
|
+
What eBill found running 1.2.0-rc.1. Everything in rc.1 below still holds.
|
|
79
|
+
|
|
80
|
+
### Added
|
|
81
|
+
|
|
82
|
+
- **A signer's own signature on its acceptance.** An agreement statement may
|
|
83
|
+
carry `visualSignature`, typed (`{ type: 'typed', text }`) or drawn
|
|
84
|
+
(`{ type: 'drawn', strokes }`), with a letter signature's limits, on an
|
|
85
|
+
`accepted` statement only. It is inside the statement, so the statement's
|
|
86
|
+
signature covers it and the evidence bundle keeps it. It is optional in the
|
|
87
|
+
protocol; a platform may require one. A 1.2.0-rc.1 receiver refuses a
|
|
88
|
+
statement that carries one.
|
|
89
|
+
- The server option `entityTypeOf`: whether one of the platform's own
|
|
90
|
+
addresses is a person or an organisation, so the server can tell what a
|
|
91
|
+
person's trust request owes (see Changed).
|
|
92
|
+
|
|
93
|
+
### Changed
|
|
94
|
+
|
|
95
|
+
- A `1.2.0` trust request carries `permissions`. One without them is refused
|
|
96
|
+
on arrival; a request for everything is a `1.1.0` one, which every server
|
|
97
|
+
still takes.
|
|
98
|
+
- A person asking an organisation for details gives nothing in return. An
|
|
99
|
+
organisation's request still gives what it asks for to anyone, and a
|
|
100
|
+
person's to another person. Only the receiver's own server knows what the
|
|
101
|
+
receiver is, so a person's request is now checked there, against
|
|
102
|
+
`entityTypeOf`, instead of by the schema; without the option, every receiver
|
|
103
|
+
is held to be a person, as before.
|
|
104
|
+
|
|
105
|
+
### Fixed
|
|
106
|
+
|
|
107
|
+
- A refusal of a trust's permissions reaches the sender as itself:
|
|
108
|
+
`BTP_ERROR_PERMISSION_REQUIRED` for a grant that withholds a required name,
|
|
109
|
+
`BTP_ERROR_PERMISSION` for a name not granted or not asked for,
|
|
110
|
+
`BTP_ERROR_DOCUMENT_TYPE_MISMATCH` and `BTP_ERROR_DETAILS_NOT_HELD`. Each
|
|
111
|
+
read `BTP_ERROR_TRUST_NOT_ALLOWED` on the wire, so a platform could not tell
|
|
112
|
+
its user what to fix. Refusals about a trust's state still read "not
|
|
113
|
+
allowed", so a stranger learns nothing of it.
|
|
114
|
+
|
|
7
115
|
## [1.2.0-rc.1] — 2026-11-08 (beta, release candidate)
|
|
8
116
|
|
|
9
117
|
What's new, with a guide for each feature: [What's new in 1.2](https://www.openbtps.org/docs/next/whats-new/1-2).
|
package/dist/client/index.d.ts
CHANGED
|
@@ -9,4 +9,5 @@ export { BtpsAgent } from './btpsAgent.js';
|
|
|
9
9
|
export { BtpsClient } from './btpsClient.js';
|
|
10
10
|
export { BtpsTransporter } from './btpsTransporter.js';
|
|
11
11
|
export * from './constants/index.js';
|
|
12
|
+
export { checkBoundView, writtenValue, type BTPBoundViewResult, } from '../core/server/schemas/boundViewChecks.js';
|
|
12
13
|
export { MIN_CONNECT_TIMEOUT_MS, DEFAULT_CONNECT_TIMEOUT_MS, MIN_REPLY_TIMEOUT_MS, DEFAULT_REPLY_TIMEOUT_MS, KEY_CHAIN_REPLY_TIMEOUT_MS, } from './libs/timeouts.js';
|
package/dist/client/index.js
CHANGED
|
@@ -10,6 +10,10 @@ import { BtpsAgent } from "./btpsAgent.js";
|
|
|
10
10
|
import { BtpsClient } from "./btpsClient.js";
|
|
11
11
|
import { BtpsTransporter } from "./btpsTransporter.js";
|
|
12
12
|
export * from "./constants/index.js";
|
|
13
|
+
import {
|
|
14
|
+
checkBoundView,
|
|
15
|
+
writtenValue
|
|
16
|
+
} from "../core/server/schemas/boundViewChecks.js";
|
|
13
17
|
import {
|
|
14
18
|
MIN_CONNECT_TIMEOUT_MS,
|
|
15
19
|
DEFAULT_CONNECT_TIMEOUT_MS,
|
|
@@ -25,5 +29,7 @@ export {
|
|
|
25
29
|
DEFAULT_REPLY_TIMEOUT_MS,
|
|
26
30
|
KEY_CHAIN_REPLY_TIMEOUT_MS,
|
|
27
31
|
MIN_CONNECT_TIMEOUT_MS,
|
|
28
|
-
MIN_REPLY_TIMEOUT_MS
|
|
32
|
+
MIN_REPLY_TIMEOUT_MS,
|
|
33
|
+
checkBoundView,
|
|
34
|
+
writtenValue
|
|
29
35
|
};
|
|
@@ -13,6 +13,7 @@ import {
|
|
|
13
13
|
BTP_ERROR_VALIDATION
|
|
14
14
|
} from "../error/constant.js";
|
|
15
15
|
import { decryptedDocumentProblem } from "../server/schemas/helpers.js";
|
|
16
|
+
import { boundViewResultOf } from "../server/schemas/boundViewChecks.js";
|
|
16
17
|
import { verifierRefusal } from "../trust/verification.js";
|
|
17
18
|
import isEmpty from "lodash/isEmpty.js";
|
|
18
19
|
const genDecryptError = (error) => ({
|
|
@@ -53,9 +54,12 @@ const genDecryptError = (error) => ({
|
|
|
53
54
|
...restEncryptedPayload,
|
|
54
55
|
signature
|
|
55
56
|
};
|
|
56
|
-
|
|
57
|
+
decryptedData && (decryptedPayload.document = decryptedData), delegation && (decryptedPayload.delegation = delegation);
|
|
58
|
+
const boundView = restEncryptedPayload.type === "BTPS_DOC" ? boundViewResultOf(decryptedData) : void 0;
|
|
59
|
+
return {
|
|
57
60
|
payload: decryptedPayload,
|
|
58
|
-
error: void 0
|
|
61
|
+
error: void 0,
|
|
62
|
+
...boundView && { boundView }
|
|
59
63
|
};
|
|
60
64
|
};
|
|
61
65
|
export {
|
|
@@ -8,6 +8,7 @@ import { BTPErrorException } from '../error/index.js';
|
|
|
8
8
|
import { BTPAgentArtifact, BTPArtifact, BTPDelegation, BTPDocType, BTPServerResponse, BTPShaped, BTPTransporterArtifact } from '../server/types.js';
|
|
9
9
|
import type { Signer } from './signer-interface.js';
|
|
10
10
|
import type { Decrypter } from './decrypter-interface.js';
|
|
11
|
+
import type { BTPBoundViewResult } from '../server/schemas/boundViewChecks.js';
|
|
11
12
|
export type EncryptionMode = 'none' | 'standardEncrypt' | '2faEncrypt';
|
|
12
13
|
export type EncryptionAlgorithmType = 'aes-256-gcm';
|
|
13
14
|
export type BTPEncryption = {
|
|
@@ -54,6 +55,8 @@ export interface BTPCryptoResponse<T = BTPDocType> {
|
|
|
54
55
|
error?: BTPErrorException;
|
|
55
56
|
/** Since 1.2: a trust request sent as its 1.1 receiver allows, and what it left out */
|
|
56
57
|
shaped?: BTPShaped;
|
|
58
|
+
/** Since 1.2: whether the opened document's BoundView may be shown, when it carries one */
|
|
59
|
+
boundView?: BTPBoundViewResult;
|
|
57
60
|
}
|
|
58
61
|
export interface VerifyEncryptedPayload<T = unknown | string> {
|
|
59
62
|
document?: T;
|
|
@@ -37,8 +37,10 @@ const BTP_PROTOCOL_VERSION = "1.2.0", MIN_SUPPORTED_VERSION = "1.1.0", MAX_SUPPO
|
|
|
37
37
|
(artifact) => documentOf(artifact)?.type === "agreement",
|
|
38
38
|
|
|
39
39
|
(artifact) => {
|
|
40
|
-
const document = documentOf(artifact);
|
|
41
|
-
return
|
|
40
|
+
const document = documentOf(artifact), lineItems = document?.lineItems;
|
|
41
|
+
return document !== void 0 && (["boundView", "recipient", "signatory", "subtotalAmount", "taxAmount"].some(
|
|
42
|
+
(field) => document[field] !== void 0
|
|
43
|
+
) || typeof lineItems == "object" && lineItems !== null && "roles" in lineItems);
|
|
42
44
|
},
|
|
43
45
|
|
|
44
46
|
(artifact) => Object.keys(PERMISSION_ENVELOPE_FIELDS).some((field) => artifact[field] !== void 0),
|
|
@@ -5,3 +5,9 @@
|
|
|
5
5
|
* https://www.apache.org/licenses/LICENSE-2.0
|
|
6
6
|
*/
|
|
7
7
|
export declare const CURRENCY_CODES: readonly ["AED", "AFN", "ALL", "AMD", "ANG", "AOA", "ARS", "AUD", "AWG", "AZN", "BAM", "BBD", "BDT", "BGN", "BHD", "BIF", "BMD", "BND", "BOB", "BRL", "BSD", "BTN", "BWP", "BYN", "BZD", "CAD", "CDF", "CHF", "CLP", "CNY", "COP", "CRC", "CUP", "CVE", "CZK", "DJF", "DKK", "DOP", "DZD", "EGP", "ERN", "ETB", "EUR", "FJD", "FKP", "FOK", "GBP", "GEL", "GGP", "GHS", "GIP", "GMD", "GNF", "GTQ", "GYD", "HKD", "HNL", "HRK", "HTG", "HUF", "IDR", "ILS", "IMP", "INR", "IQD", "IRR", "ISK", "JEP", "JMD", "JOD", "JPY", "KES", "KGS", "KHR", "KID", "KMF", "KRW", "KWD", "KYD", "KZT", "LAK", "LBP", "LKR", "LRD", "LSL", "LYD", "MAD", "MDL", "MGA", "MKD", "MMK", "MNT", "MOP", "MRU", "MUR", "MVR", "MWK", "MXN", "MYR", "MZN", "NAD", "NGN", "NIO", "NOK", "NPR", "NZD", "OMR", "PAB", "PEN", "PGK", "PHP", "PKR", "PLN", "PYG", "QAR", "RON", "RSD", "RUB", "RWF", "SAR", "SBD", "SCR", "SDG", "SEK", "SGD", "SHP", "SLL", "SOS", "SRD", "SSP", "STN", "SYP", "SZL", "THB", "TJS", "TMT", "TND", "TOP", "TRY", "TTD", "TVD", "TWD", "TZS", "UAH", "UGX", "USD", "UYU", "UZS", "VES", "VND", "VUV", "WST", "XAF", "XCD", "XOF", "XPF", "YER", "ZAR", "ZMW", "ZWL"];
|
|
8
|
+
/**
|
|
9
|
+
* The decimal places ISO 4217 gives each currency whose minor unit is not two
|
|
10
|
+
* hundredths. Every other code has 2. Fixed here rather than read from a
|
|
11
|
+
* runtime's Intl data, so every receiver writes an amount the same way.
|
|
12
|
+
*/
|
|
13
|
+
export declare const CURRENCY_DECIMALS: Partial<Record<(typeof CURRENCY_CODES)[number], number>>;
|
|
@@ -326,7 +326,32 @@ const CURRENCY_CODES = [
|
|
|
326
326
|
|
|
327
327
|
"ZWL"
|
|
328
328
|
|
|
329
|
-
]
|
|
329
|
+
], CURRENCY_DECIMALS = {
|
|
330
|
+
BIF: 0,
|
|
331
|
+
CLP: 0,
|
|
332
|
+
DJF: 0,
|
|
333
|
+
GNF: 0,
|
|
334
|
+
ISK: 0,
|
|
335
|
+
JPY: 0,
|
|
336
|
+
KMF: 0,
|
|
337
|
+
KRW: 0,
|
|
338
|
+
PYG: 0,
|
|
339
|
+
RWF: 0,
|
|
340
|
+
UGX: 0,
|
|
341
|
+
VND: 0,
|
|
342
|
+
VUV: 0,
|
|
343
|
+
XAF: 0,
|
|
344
|
+
XOF: 0,
|
|
345
|
+
XPF: 0,
|
|
346
|
+
BHD: 3,
|
|
347
|
+
IQD: 3,
|
|
348
|
+
JOD: 3,
|
|
349
|
+
KWD: 3,
|
|
350
|
+
LYD: 3,
|
|
351
|
+
OMR: 3,
|
|
352
|
+
TND: 3
|
|
353
|
+
};
|
|
330
354
|
export {
|
|
331
|
-
CURRENCY_CODES
|
|
355
|
+
CURRENCY_CODES,
|
|
356
|
+
CURRENCY_DECIMALS
|
|
332
357
|
};
|
|
@@ -86,5 +86,30 @@ export declare const BTPS_FIELD_LIMITS: {
|
|
|
86
86
|
readonly width: 1000;
|
|
87
87
|
readonly height: 300;
|
|
88
88
|
};
|
|
89
|
+
readonly recipientName: 200;
|
|
90
|
+
readonly boundView: {
|
|
91
|
+
readonly json: number;
|
|
92
|
+
readonly pageWidth: 2000;
|
|
93
|
+
readonly pageHeight: 20000;
|
|
94
|
+
readonly breaks: 100;
|
|
95
|
+
readonly elements: 2000;
|
|
96
|
+
readonly textElements: 1000;
|
|
97
|
+
readonly position: 20000;
|
|
98
|
+
readonly label: 500;
|
|
99
|
+
readonly path: 20000;
|
|
100
|
+
readonly paths: 100000;
|
|
101
|
+
readonly stops: 8;
|
|
102
|
+
readonly fonts: 4;
|
|
103
|
+
readonly glyphs: 256;
|
|
104
|
+
readonly glyphPath: 4000;
|
|
105
|
+
readonly kerning: 4096;
|
|
106
|
+
readonly fallback: 4;
|
|
107
|
+
readonly images: 8;
|
|
108
|
+
readonly imageSide: 1024;
|
|
109
|
+
readonly imagePixels: 262144;
|
|
110
|
+
readonly imageData: number;
|
|
111
|
+
readonly affix: 8;
|
|
112
|
+
readonly groups: 32;
|
|
113
|
+
};
|
|
89
114
|
readonly detailNumber: 64;
|
|
90
115
|
};
|
|
@@ -86,6 +86,33 @@ const BTPS_FIELD_LIMITS = {
|
|
|
86
86
|
|
|
87
87
|
signature: { text: 100, strokes: 32, strokePoints: 512, points: 2048, width: 1e3, height: 300 },
|
|
88
88
|
|
|
89
|
+
recipientName: 200,
|
|
90
|
+
|
|
91
|
+
boundView: {
|
|
92
|
+
json: 393216,
|
|
93
|
+
pageWidth: 2e3,
|
|
94
|
+
pageHeight: 2e4,
|
|
95
|
+
breaks: 100,
|
|
96
|
+
elements: 2e3,
|
|
97
|
+
textElements: 1e3,
|
|
98
|
+
position: 2e4,
|
|
99
|
+
label: 500,
|
|
100
|
+
path: 2e4,
|
|
101
|
+
paths: 1e5,
|
|
102
|
+
stops: 8,
|
|
103
|
+
fonts: 4,
|
|
104
|
+
glyphs: 256,
|
|
105
|
+
glyphPath: 4e3,
|
|
106
|
+
kerning: 4096,
|
|
107
|
+
fallback: 4,
|
|
108
|
+
images: 8,
|
|
109
|
+
imageSide: 1024,
|
|
110
|
+
imagePixels: 262144,
|
|
111
|
+
imageData: 262144,
|
|
112
|
+
affix: 8,
|
|
113
|
+
groups: 32
|
|
114
|
+
},
|
|
115
|
+
|
|
89
116
|
detailNumber: 64
|
|
90
117
|
};
|
|
91
118
|
export {
|
|
@@ -13,7 +13,7 @@ export declare const DOCUMENT_TYPES: readonly ["invoice", "receipt", "payslip",
|
|
|
13
13
|
export declare const DETAIL_TYPES: readonly ["legalName", "profile", "email", "phone", "address", "taxNo", "dob", "registrationNumber"];
|
|
14
14
|
/** Since 1.2: what owns a BTPS address. */
|
|
15
15
|
export declare const ENTITY_TYPES: readonly ["person", "organisation"];
|
|
16
|
-
export declare const SEND_PERMISSIONS: ("send:
|
|
16
|
+
export declare const SEND_PERMISSIONS: ("send:invoice" | "send:receipt" | "send:payslip" | "send:letter" | "send:agreement")[];
|
|
17
17
|
export declare const DETAIL_PERMISSIONS: ("detail:legalName" | "detail:profile" | "detail:email" | "detail:phone" | "detail:address" | "detail:taxNo" | "detail:dob" | "detail:registrationNumber")[];
|
|
18
18
|
/** Since 1.2: details refresh: a notice that details changed, a request for some, and its answer. */
|
|
19
19
|
export declare const DETAILS_ARTIFACT_TYPES: readonly ["DETAILS_CHANGED", "DETAILS_REQ", "DETAILS_RES"];
|
|
@@ -60,6 +60,13 @@ const BtpSyncOfSchema = z.object({ id: z.string().min(1), sha256: sha256Hex }).s
|
|
|
60
60
|
documentType: z.enum(DOCUMENT_TYPES).optional(),
|
|
61
61
|
details: namesFrom(DETAIL_PERMISSIONS, 1).optional()
|
|
62
62
|
});
|
|
63
|
+
function detailsOwed(permissions, entityType, given = []) {
|
|
64
|
+
const identities = Object.values(IDENTITY_DETAIL);
|
|
65
|
+
return permissions.filter(({ name }) => name.startsWith("detail:")).map(({ name }) => ({
|
|
66
|
+
asked: name,
|
|
67
|
+
owed: identities.includes(name) ? IDENTITY_DETAIL[entityType] : name
|
|
68
|
+
})).filter(({ owed }) => !given.includes(owed));
|
|
69
|
+
}
|
|
63
70
|
function permissionEnvelopeProblems(data) {
|
|
64
71
|
const problems = [];
|
|
65
72
|
for (const [field, types] of Object.entries(PERMISSION_ENVELOPE_FIELDS))
|
|
@@ -74,15 +81,14 @@ function permissionEnvelopeProblems(data) {
|
|
|
74
81
|
const twice = names && duplicateOf(names);
|
|
75
82
|
twice && problems.push([field, `${twice} appears more than once`]);
|
|
76
83
|
}
|
|
84
|
+
data.type === "TRUST_REQ" && !isVersionBelow(data.version, "1.2.0") && !data.permissions && problems.push([
|
|
85
|
+
"permissions",
|
|
86
|
+
"a 1.2.0 TRUST_REQ asks for permissions; a request for everything is a 1.1.0 one"
|
|
87
|
+
]);
|
|
77
88
|
const { entityType } = data, other = entityType && IDENTITY_DETAIL[entityType === "person" ? "organisation" : "person"];
|
|
78
|
-
if (data.permissions && !entityType && problems.push(["entityType", "entityType comes with permissions"]), data.granted && !entityType && problems.push(["entityType", "entityType comes with granted"]), data.permissions && entityType)
|
|
79
|
-
const
|
|
80
|
-
|
|
81
|
-
if (!name.startsWith("detail:")) continue;
|
|
82
|
-
const gives = identities.includes(name) ? IDENTITY_DETAIL[entityType] : name;
|
|
83
|
-
given.includes(gives) || problems.push(["given", `asks for ${name} without giving ${gives}`]);
|
|
84
|
-
}
|
|
85
|
-
}
|
|
89
|
+
if (data.permissions && !entityType && problems.push(["entityType", "entityType comes with permissions"]), data.granted && !entityType && problems.push(["entityType", "entityType comes with granted"]), data.permissions && entityType === "organisation")
|
|
90
|
+
for (const { asked, owed } of detailsOwed(data.permissions, entityType, data.given))
|
|
91
|
+
problems.push(["given", `asks for ${asked} without giving ${owed}`]);
|
|
86
92
|
if (other && data.given?.includes(other) && problems.push(["given", `a ${entityType} never gives ${other}`]), other && data.granted?.includes(other) && problems.push(["granted", `a ${entityType} never grants ${other}`]), DETAILS_ARTIFACT_TYPES.includes(data.type) && data.details === void 0 && problems.push(["details", `a ${data.type} names the details it is about`]), data.type === "DETAILS_RES" && data.encryption === null && problems.push(["encryption", "a DETAILS_RES is always encrypted to the requester"]), data.encryption === null) {
|
|
87
93
|
const document = documentRecord(data.document);
|
|
88
94
|
data.type === "TRUST_REQ" && document?.own !== void 0 && problems.push(["document", "a request with its own values is encrypted"]), data.type === "TRUST_REQ" && document?.verification !== void 0 && problems.push(["document", "a request with a verification is encrypted"]), data.type === "TRUST_RES" && document?.details !== void 0 && problems.push(["document", "a response with details is encrypted"]), data.type === "TRUST_RES" && data.granted && document?.decision !== "accepted" && problems.push(["granted", "only an accepted answer carries granted"]);
|
|
@@ -136,5 +142,6 @@ export {
|
|
|
136
142
|
BtpTransporterArtifactBaseSchema,
|
|
137
143
|
BtpTransporterArtifactSchema,
|
|
138
144
|
BtpTrustPermissionsSchema,
|
|
139
|
-
BtpTrustRecordPermissionsSchema
|
|
145
|
+
BtpTrustRecordPermissionsSchema,
|
|
146
|
+
detailsOwed
|
|
140
147
|
};
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @license
|
|
3
|
+
* Copyright (c) 2025 Bhupendra Tamang
|
|
4
|
+
* Licensed under the Apache License, Version 2.0
|
|
5
|
+
* https://www.apache.org/licenses/LICENSE-2.0
|
|
6
|
+
*/
|
|
7
|
+
export { BtpBoundViewSchema, isPathData, type BTPBoundView, type BTPBoundViewElement, type BTPBoundViewFont, } from './boundViewSchema.js';
|
|
8
|
+
export { boundValue, bindingProblem, type BoundValue } from './boundViewBindings.js';
|
|
9
|
+
export { checkBoundView, boundViewResultOf, writtenValue, CONTRAST_WORK_LIMIT, type BTPBoundViewResult, type BTPBoundViewProblem, type BTPBoundViewCheck, } from './boundViewChecks.js';
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @license
|
|
3
|
+
* Copyright (c) 2025 Bhupendra Tamang
|
|
4
|
+
* Licensed under the Apache License, Version 2.0
|
|
5
|
+
* https://www.apache.org/licenses/LICENSE-2.0
|
|
6
|
+
*/
|
|
7
|
+
|
|
8
|
+
import {
|
|
9
|
+
BtpBoundViewSchema,
|
|
10
|
+
isPathData
|
|
11
|
+
} from "./boundViewSchema.js";
|
|
12
|
+
import { boundValue, bindingProblem } from "./boundViewBindings.js";
|
|
13
|
+
import {
|
|
14
|
+
checkBoundView,
|
|
15
|
+
boundViewResultOf,
|
|
16
|
+
writtenValue,
|
|
17
|
+
CONTRAST_WORK_LIMIT
|
|
18
|
+
} from "./boundViewChecks.js";
|
|
19
|
+
export {
|
|
20
|
+
BtpBoundViewSchema,
|
|
21
|
+
CONTRAST_WORK_LIMIT,
|
|
22
|
+
bindingProblem,
|
|
23
|
+
boundValue,
|
|
24
|
+
boundViewResultOf,
|
|
25
|
+
checkBoundView,
|
|
26
|
+
isPathData,
|
|
27
|
+
writtenValue
|
|
28
|
+
};
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @license
|
|
3
|
+
* Copyright (c) 2025 Bhupendra Tamang
|
|
4
|
+
* Licensed under the Apache License, Version 2.0
|
|
5
|
+
* https://www.apache.org/licenses/LICENSE-2.0
|
|
6
|
+
*/
|
|
7
|
+
export type BoundKind = 'text' | 'money' | 'date' | 'percent';
|
|
8
|
+
/** A bound field's value: text, a date, whole basis points, or an amount in minor units of its currency. */
|
|
9
|
+
export type BoundValue = {
|
|
10
|
+
kind: 'text';
|
|
11
|
+
text: string;
|
|
12
|
+
} | {
|
|
13
|
+
kind: 'date';
|
|
14
|
+
date: string;
|
|
15
|
+
} | {
|
|
16
|
+
kind: 'percent';
|
|
17
|
+
basisPoints: number;
|
|
18
|
+
} | {
|
|
19
|
+
kind: 'money';
|
|
20
|
+
amount: number;
|
|
21
|
+
currency: string;
|
|
22
|
+
};
|
|
23
|
+
type Doc = Record<string, unknown>;
|
|
24
|
+
/** What `field` names in `document`, or undefined when a BoundView may not bind it or the document lacks it. */
|
|
25
|
+
export declare const boundValue: (document: Doc, field: string) => BoundValue | undefined;
|
|
26
|
+
type Bind = {
|
|
27
|
+
field: string;
|
|
28
|
+
format?: {
|
|
29
|
+
money?: unknown;
|
|
30
|
+
date?: unknown;
|
|
31
|
+
percent?: unknown;
|
|
32
|
+
groups?: {
|
|
33
|
+
sizes: number[];
|
|
34
|
+
};
|
|
35
|
+
};
|
|
36
|
+
range?: [number, number];
|
|
37
|
+
};
|
|
38
|
+
/** Why a binding cannot be drawn from `document`, or undefined when it can. */
|
|
39
|
+
export declare const bindingProblem: (document: Doc, bind: Bind) => string | undefined;
|
|
40
|
+
export {};
|
|
@@ -0,0 +1,128 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @license
|
|
3
|
+
* Copyright (c) 2025 Bhupendra Tamang
|
|
4
|
+
* Licensed under the Apache License, Version 2.0
|
|
5
|
+
* https://www.apache.org/licenses/LICENSE-2.0
|
|
6
|
+
*/
|
|
7
|
+
|
|
8
|
+
const ISSUER = [
|
|
9
|
+
["id", "text"],
|
|
10
|
+
["title", "text"],
|
|
11
|
+
["issuedAt", "date"],
|
|
12
|
+
["issuer.name", "text"],
|
|
13
|
+
["issuer.email", "text"],
|
|
14
|
+
["issuer.phone", "text"],
|
|
15
|
+
["issuer.address", "text"],
|
|
16
|
+
["issuer.identifiers.*", "text"]
|
|
17
|
+
], BILL = [
|
|
18
|
+
...ISSUER,
|
|
19
|
+
["totalAmount", "money"],
|
|
20
|
+
["subtotalAmount", "money"],
|
|
21
|
+
["taxAmount", "money"],
|
|
22
|
+
["discount.amount", "money"],
|
|
23
|
+
["discount.percent", "percent"],
|
|
24
|
+
["recipient.name", "text"],
|
|
25
|
+
["description", "text"],
|
|
26
|
+
["lineItems.rows.#.*", "cell"]
|
|
27
|
+
], LETTER = [
|
|
28
|
+
...ISSUER,
|
|
29
|
+
["body.content", "text"],
|
|
30
|
+
["recipient.name", "text"],
|
|
31
|
+
["signatory.name", "text"],
|
|
32
|
+
["signatory.title", "text"]
|
|
33
|
+
], PATTERNS = {
|
|
34
|
+
invoice: [...BILL, ["dueAt", "date"]],
|
|
35
|
+
receipt: [
|
|
36
|
+
...BILL,
|
|
37
|
+
["payment.amount", "money"],
|
|
38
|
+
["payment.paidAt", "date"],
|
|
39
|
+
["payment.method", "text"],
|
|
40
|
+
["payment.reference", "text"]
|
|
41
|
+
],
|
|
42
|
+
payslip: [
|
|
43
|
+
...ISSUER,
|
|
44
|
+
["payDate", "date"],
|
|
45
|
+
["payPeriod.start", "date"],
|
|
46
|
+
["payPeriod.end", "date"],
|
|
47
|
+
["payRate.asAt", "date"],
|
|
48
|
+
["employee.name", "text"],
|
|
49
|
+
["employee.employeeId", "text"],
|
|
50
|
+
["payRate.amount", "money"],
|
|
51
|
+
["gross", "money"],
|
|
52
|
+
["net", "money"],
|
|
53
|
+
["taxWithheld", "money"],
|
|
54
|
+
["yearToDate.*", "money"],
|
|
55
|
+
...["description", "category", "rate", "rateUnit", "quantity"].map(
|
|
56
|
+
(key) => [`earnings.#.${key}`, "text"]
|
|
57
|
+
),
|
|
58
|
+
["earnings.#.amount", "money"],
|
|
59
|
+
["deductions.#.description", "text"],
|
|
60
|
+
["deductions.#.category", "text"],
|
|
61
|
+
["deductions.#.payee.name", "text"],
|
|
62
|
+
["deductions.#.amount", "money"],
|
|
63
|
+
["contributions.#.category", "text"],
|
|
64
|
+
["contributions.#.fund.name", "text"],
|
|
65
|
+
["contributions.#.amount", "money"],
|
|
66
|
+
...["description", "category", "unit", "balance", "accrued", "taken"].map(
|
|
67
|
+
(key) => [`leave.#.${key}`, "text"]
|
|
68
|
+
)
|
|
69
|
+
],
|
|
70
|
+
letter: LETTER,
|
|
71
|
+
agreement: [...LETTER, ["acceptance.by", "date"]]
|
|
72
|
+
}, isRecord = (value) => typeof value == "object" && value !== null && !Array.isArray(value), walk = (document, pattern, field) => {
|
|
73
|
+
const want = pattern.split("."), have = field.split(".");
|
|
74
|
+
let at = document;
|
|
75
|
+
for (let i = 0; i < want.length; i++) {
|
|
76
|
+
const segment = want[i];
|
|
77
|
+
if (segment === "*") {
|
|
78
|
+
const key = have.slice(i).join(".");
|
|
79
|
+
return isRecord(at) && key !== "" && Object.hasOwn(at, key) ? at[key] : void 0;
|
|
80
|
+
}
|
|
81
|
+
const part = have[i];
|
|
82
|
+
if (part === void 0) return;
|
|
83
|
+
if (segment === "#") {
|
|
84
|
+
if (!Array.isArray(at) || !/^(0|[1-9]\d*)$/.test(part)) return;
|
|
85
|
+
at = at[Number(part)];
|
|
86
|
+
} else {
|
|
87
|
+
if (segment !== part || !isRecord(at) || !Object.hasOwn(at, part)) return;
|
|
88
|
+
at = at[part];
|
|
89
|
+
}
|
|
90
|
+
}
|
|
91
|
+
return have.length === want.length ? at : void 0;
|
|
92
|
+
}, currencyOf = (document) => {
|
|
93
|
+
const total = document.totalAmount;
|
|
94
|
+
return isRecord(total) && typeof total.currency == "string" ? total.currency : void 0;
|
|
95
|
+
}, boundValue = (document, field) => {
|
|
96
|
+
const type = typeof document.type == "string" ? document.type : "";
|
|
97
|
+
for (const [pattern, kind] of PATTERNS[type] ?? []) {
|
|
98
|
+
const value = walk(document, pattern, field);
|
|
99
|
+
if (value !== void 0) {
|
|
100
|
+
if (kind === "cell" || kind === "money" && typeof value == "number") {
|
|
101
|
+
const currency = currencyOf(document);
|
|
102
|
+
return typeof value == "number" && currency !== void 0 ? { kind: "money", amount: value, currency } : typeof value == "string" ? { kind: "text", text: value } : void 0;
|
|
103
|
+
}
|
|
104
|
+
return kind === "money" ? isRecord(value) && typeof value.amount == "number" && typeof value.currency == "string" ? { kind: "money", amount: value.amount, currency: value.currency } : void 0 : kind === "percent" ? typeof value == "number" ? { kind: "percent", basisPoints: value } : void 0 : kind === "date" ? typeof value == "string" ? { kind: "date", date: value } : void 0 : isRecord(value) && typeof value.content == "string" ? { kind: "text", text: value.content } : typeof value == "string" ? { kind: "text", text: value } : void 0;
|
|
105
|
+
}
|
|
106
|
+
}
|
|
107
|
+
}, bindingProblem = (document, bind) => {
|
|
108
|
+
const value = boundValue(document, bind.field);
|
|
109
|
+
if (value === void 0) return `binds ${bind.field}, which a BoundView may not bind or the document does not carry`;
|
|
110
|
+
const format = bind.format ?? {};
|
|
111
|
+
if (value.kind === "money" && format.money === void 0) return "a money field is written with a money format";
|
|
112
|
+
if (value.kind === "date" && format.date === void 0) return "a date field is written with a date format";
|
|
113
|
+
if (value.kind === "percent" && format.percent === void 0) return "a percent is written with a percent format";
|
|
114
|
+
if (value.kind === "text") {
|
|
115
|
+
if (format.money !== void 0 || format.date !== void 0 || format.percent !== void 0)
|
|
116
|
+
return "text is written as it is, or in groups";
|
|
117
|
+
if (format.groups !== void 0) {
|
|
118
|
+
const length = [...value.text.replace(/ /g, "")].length;
|
|
119
|
+
if (format.groups.sizes.reduce((total, part) => total + part, 0) !== length) return "a groups format's sizes add up to the value's length";
|
|
120
|
+
}
|
|
121
|
+
if (bind.range !== void 0 && bind.range[1] > [...value.text].length)
|
|
122
|
+
return "a range lies inside the value's characters";
|
|
123
|
+
}
|
|
124
|
+
};
|
|
125
|
+
export {
|
|
126
|
+
bindingProblem,
|
|
127
|
+
boundValue
|
|
128
|
+
};
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @license
|
|
3
|
+
* Copyright (c) 2025 Bhupendra Tamang
|
|
4
|
+
* Licensed under the Apache License, Version 2.0
|
|
5
|
+
* https://www.apache.org/licenses/LICENSE-2.0
|
|
6
|
+
*/
|
|
7
|
+
import { type BTPBoundView, type BTPBoundViewElement } from './boundViewSchema.js';
|
|
8
|
+
import { type BoundValue } from './boundViewBindings.js';
|
|
9
|
+
type Doc = Record<string, unknown>;
|
|
10
|
+
type TextElement = Extract<BTPBoundViewElement, {
|
|
11
|
+
type: 'text';
|
|
12
|
+
}>;
|
|
13
|
+
export type BTPBoundViewCheck = 'wellFormed' | 'keyFacts' | 'shownInFull' | 'notHidden';
|
|
14
|
+
export type BTPBoundViewProblem = {
|
|
15
|
+
check: BTPBoundViewCheck;
|
|
16
|
+
message: string;
|
|
17
|
+
/** The element the problem is on, by its index in `elements`. */
|
|
18
|
+
element?: number;
|
|
19
|
+
/** The key fact the problem is about. */
|
|
20
|
+
field?: string;
|
|
21
|
+
};
|
|
22
|
+
/** Whether a BoundView may be shown, and why not when it may not. */
|
|
23
|
+
export type BTPBoundViewResult = {
|
|
24
|
+
show: true;
|
|
25
|
+
} | {
|
|
26
|
+
show: false;
|
|
27
|
+
problems: BTPBoundViewProblem[];
|
|
28
|
+
};
|
|
29
|
+
/** A bound value as the receiver draws it, by its binding's format and range (Bindings and formats). */
|
|
30
|
+
export declare const writtenValue: (value: BoundValue, bind: TextElement["bind"]) => string;
|
|
31
|
+
/**
|
|
32
|
+
* The most edge and point tests the contrast check makes on one BoundView. A
|
|
33
|
+
* BoundView that would need more fails the check: a receiver is never made to
|
|
34
|
+
* work without end on a crafted one.
|
|
35
|
+
*/
|
|
36
|
+
export declare const CONTRAST_WORK_LIMIT = 20000000;
|
|
37
|
+
/**
|
|
38
|
+
* The checks on a well-formed BoundView, against the signed document it
|
|
39
|
+
* belongs to: every key fact shown, every bound value shown in full, and
|
|
40
|
+
* nothing bound hidden. Run wherever the document is opened, before it is shown.
|
|
41
|
+
*/
|
|
42
|
+
export declare const checkBoundView: (document: Doc, view: BTPBoundView) => BTPBoundViewResult;
|
|
43
|
+
/**
|
|
44
|
+
* Whether an opened document's BoundView may be shown, or undefined when it
|
|
45
|
+
* carries none. A document is checked against its schema before it is opened;
|
|
46
|
+
* one that was not, and whose BoundView is not well formed, is never shown.
|
|
47
|
+
*/
|
|
48
|
+
export declare const boundViewResultOf: (document: unknown) => BTPBoundViewResult | undefined;
|
|
49
|
+
export {};
|