@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.
Files changed (30) hide show
  1. package/CHANGELOG.md +108 -0
  2. package/dist/client/index.d.ts +1 -0
  3. package/dist/client/index.js +7 -1
  4. package/dist/core/crypto/decryptVerify.js +6 -2
  5. package/dist/core/crypto/types.d.ts +3 -0
  6. package/dist/core/server/constants/btps-protocol.js +4 -2
  7. package/dist/core/server/constants/currency.d.ts +6 -0
  8. package/dist/core/server/constants/currency.js +27 -2
  9. package/dist/core/server/constants/limits.d.ts +25 -0
  10. package/dist/core/server/constants/limits.js +27 -0
  11. package/dist/core/server/constants/permissions.d.ts +1 -1
  12. package/dist/core/server/schemas/artifacts/transporterSchema.js +16 -9
  13. package/dist/core/server/schemas/boundView.d.ts +9 -0
  14. package/dist/core/server/schemas/boundView.js +28 -0
  15. package/dist/core/server/schemas/boundViewBindings.d.ts +40 -0
  16. package/dist/core/server/schemas/boundViewBindings.js +128 -0
  17. package/dist/core/server/schemas/boundViewChecks.d.ts +49 -0
  18. package/dist/core/server/schemas/boundViewChecks.js +344 -0
  19. package/dist/core/server/schemas/boundViewSchema.d.ts +1637 -0
  20. package/dist/core/server/schemas/boundViewSchema.js +186 -0
  21. package/dist/core/server/schemas/btpsDocsSchema.d.ts +37094 -8000
  22. package/dist/core/server/schemas/btpsDocsSchema.js +62 -44
  23. package/dist/core/server/schemas/helpers.d.ts +11604 -2312
  24. package/dist/core/trust/types.d.ts +11 -1
  25. package/dist/server/btpsServer.d.ts +11 -1
  26. package/dist/server/btpsServer.js +45 -5
  27. package/dist/server/index.d.ts +1 -0
  28. package/dist/server/index.js +9 -1
  29. package/dist/server/types.d.ts +31 -26
  30. package/package.json +14 -1
@@ -250,7 +250,8 @@ export type BTPAgreementAnswers = {
250
250
  /**
251
251
  * Since 1.2: a signer's answer to an agreement, signed over its RFC 8785 form.
252
252
  * `previous`, in a sequential agreement, is the SHA-256 of the statement
253
- * record before it.
253
+ * record before it. `visualSignature`, on an acceptance only, is the signer's
254
+ * own signature, typed or drawn on the same 1000 by 300 canvas as a letter's.
254
255
  */
255
256
  export type BTPAgreementStatement = {
256
257
  agreement: BTPAgreementRef;
@@ -259,6 +260,15 @@ export type BTPAgreementStatement = {
259
260
  decision: 'accepted' | 'declined';
260
261
  signedAt: string;
261
262
  previous?: string;
263
+ visualSignature?: BTPVisualSignature;
264
+ };
265
+ /** Since 1.2: a signer's signature as data, never markup, which a receiver draws itself. */
266
+ export type BTPVisualSignature = {
267
+ type: 'typed';
268
+ text: string;
269
+ } | {
270
+ type: 'drawn';
271
+ strokes: number[][];
262
272
  };
263
273
  /**
264
274
  * Since 1.2: a signed statement. Signed by the signer's identity key at
@@ -6,6 +6,7 @@
6
6
  */
7
7
  import { BTPTrustRecord } from '../core/trust/index.js';
8
8
  import type { BTPAgentArtifact, BTPServerResponse, BTPStatus, BTPTransporterArtifact } from '../core/server/types.js';
9
+ import { type BTPBoundViewResult } from '../core/server/schemas/boundViewChecks.js';
9
10
  import type { BtpsServerEvents, BtpsServerOptions, ProcessedArtifact, ArtifactResCtx } from './types.js';
10
11
  import type { AbstractTrustStore } from '../core/trust/storage/AbstractTrustStore.js';
11
12
  import type { BTPIdentityRecord } from '../core/storage/types.js';
@@ -28,6 +29,8 @@ export declare class BtpsServer {
28
29
  private readonly maxArtifactAgeSeconds;
29
30
  private readonly signAnswers;
30
31
  private readonly keyResolver?;
32
+ /** Since 1.2: what each of this server's identities is, as its platform says. */
33
+ private readonly entityTypeOf?;
31
34
  /** Since 1.2: how a sender's, a delegator's and an attestor's key is checked against its key chain. */
32
35
  private readonly keyChains;
33
36
  /** Since 1.2: what `on(…)` tells its listeners, apart from the artifact handlers. */
@@ -222,6 +225,13 @@ export declare class BtpsServer {
222
225
  * Core trust verification (non-negotiable)
223
226
  */
224
227
  private verifyTrust;
228
+ /**
229
+ * Since 1.2: a person's trust request that asks for details without giving its own. It is
230
+ * refused unless its receiver is an organisation, as `entityTypeOf` says: a person asking an
231
+ * organisation gives nothing in return. A receiver this server cannot say is held to be a
232
+ * person. An organisation's request is held to it by the schema, whoever receives it.
233
+ */
234
+ private detailsOwedByPerson;
225
235
  /**
226
236
  * A trust records how its artifacts are sent: 'encrypted' refuses one sent in
227
237
  * the clear, 'unencrypted' one the receiver did not agree to decrypt, and
@@ -341,7 +351,7 @@ export declare class BtpsServer {
341
351
  onIncomingArtifact(type: 'Agent', handler: (artifact: BTPAgentArtifact & {
342
352
  respondNow: boolean;
343
353
  }, resCtx: ArtifactResCtx) => void): void;
344
- onIncomingArtifact(type: 'Transporter', handler: (artifact: BTPTransporterArtifact) => void | Promise<void>): void;
354
+ onIncomingArtifact(type: 'Transporter', handler: (artifact: BTPTransporterArtifact, boundView?: BTPBoundViewResult) => void | Promise<void>): void;
345
355
  /**
346
356
  * The server's identity and, when it is configured with a PEM key pair, its
347
357
  * public key. Never the private key: middleware is handed this server, and the
@@ -39,7 +39,10 @@ import {
39
39
  BTP_ERROR_PRIVACY_TYPE,
40
40
  BTP_ERROR_VERSION_UNSUPPORTED,
41
41
  BTP_ERROR_SYNC_NOT_ALLOWED,
42
- BTP_ERROR_PERMISSION
42
+ BTP_ERROR_PERMISSION,
43
+ BTP_ERROR_PERMISSION_REQUIRED,
44
+ BTP_ERROR_DOCUMENT_TYPE_MISMATCH,
45
+ BTP_ERROR_DETAILS_NOT_HELD
43
46
  } from "../core/error/constant.js";
44
47
  import {
45
48
  assertStrictJson,
@@ -57,6 +60,10 @@ import {
57
60
  isBtpsAgentArtifact,
58
61
  isValidIdentity
59
62
  } from "../core/utils/index.js";
63
+ import { detailsOwed } from "../core/server/schemas/artifacts/transporterSchema.js";
64
+ import {
65
+ boundViewResultOf
66
+ } from "../core/server/schemas/boundViewChecks.js";
60
67
  import { BTPErrorException, transformToBTPErrorException } from "../core/error/index.js";
61
68
  import {
62
69
  AGENT_TRANSPORTER_ACTIONS,
@@ -101,6 +108,15 @@ const lastRotationTo = (chain) => {
101
108
  Object.values(BTPS_ERROR_CONSTANTS).filter(
102
109
  (value) => typeof value == "object" && value !== null && typeof value.code == "string" && typeof value.status == "number"
103
110
  ).map((constant) => [String(constant.code), constant])
111
+ ), TOLD_AS_ITSELF = new Set(
112
+ [
113
+ BTP_ERROR_VALIDATION.code,
114
+ BTP_ERROR_PRIVACY_TYPE.code,
115
+ BTP_ERROR_PERMISSION.code,
116
+ BTP_ERROR_PERMISSION_REQUIRED.code,
117
+ BTP_ERROR_DOCUMENT_TYPE_MISMATCH.code,
118
+ BTP_ERROR_DETAILS_NOT_HELD.code
119
+ ].map(String)
104
120
  );
105
121
  class BtpsServer {
106
122
  tlsOptions;
@@ -116,6 +132,7 @@ class BtpsServer {
116
132
  maxArtifactAgeSeconds;
117
133
  signAnswers;
118
134
  keyResolver;
135
+ entityTypeOf;
119
136
  keyChains;
120
137
  events = new EventEmitter();
121
138
  answersOnSocket = new WeakMap();
@@ -125,7 +142,7 @@ class BtpsServer {
125
142
  emitter = new EventEmitter();
126
143
  handlerFn = null;
127
144
  constructor(options) {
128
- this.serverIdentity = options.serverIdentity, this.port = options.port ?? 3443, this.onError = options.onError, this.tlsOptions = options.tlsOptions, this.trustStore = options.trustStore, this.identityStore = options.identityStore, this.connectionTimeoutMs = resolveConnectionTimeoutMs(options.connectionTimeoutMs), this.maxArtifactSizeKb = resolveMaxArtifactSizeKb(options.maxArtifactSizeKb), this.maxInFlightPerConnection = resolveMaxInFlightPerConnection(
145
+ this.serverIdentity = options.serverIdentity, this.port = options.port ?? 3443, this.onError = options.onError, this.tlsOptions = options.tlsOptions, this.trustStore = options.trustStore, this.identityStore = options.identityStore, this.entityTypeOf = options.entityTypeOf, this.connectionTimeoutMs = resolveConnectionTimeoutMs(options.connectionTimeoutMs), this.maxArtifactSizeKb = resolveMaxArtifactSizeKb(options.maxArtifactSizeKb), this.maxInFlightPerConnection = resolveMaxInFlightPerConnection(
129
146
  options.maxInFlightPerConnection
130
147
  ), this.maxConsecutiveInvalidLines = resolveMaxConsecutiveInvalidLines(
131
148
  options.maxConsecutiveInvalidLines
@@ -437,7 +454,7 @@ class BtpsServer {
437
454
  resCtx
438
455
  )) return;
439
456
  if (!isTrusted) {
440
- const refusal = reqCtx.error, wireError = refusal?.code === BTP_ERROR_TRUST_EXPIRED.code ? BTP_ERROR_TRUST_EXPIRED : refusal && refusal.code === BTP_ERROR_PRIVACY_TYPE.code ? refusal : BTP_ERROR_TRUST_NOT_ALLOWED;
457
+ const refusal = reqCtx.error, wireError = refusal?.code === BTP_ERROR_TRUST_EXPIRED.code ? BTP_ERROR_TRUST_EXPIRED : refusal && TOLD_AS_ITSELF.has(String(refusal.code)) ? refusal : BTP_ERROR_TRUST_NOT_ALLOWED;
441
458
  return this.sendBtpsError(resCtx.socket, wireError, resCtx.reqId);
442
459
  }
443
460
  this.tellDetails(data), !(await this.executeMiddleware(
@@ -685,6 +702,8 @@ class BtpsServer {
685
702
  if (isTrustActive(ownTrust)) return this.verifyPrivacyType(artifact, ownTrust);
686
703
  }
687
704
  if (artifact.type === "TRUST_REQ") {
705
+ const owes = await this.detailsOwedByPerson(artifact);
706
+ if (owes) return { isTrusted: !1, error: owes };
688
707
  const { isValid, error } = validateTrustRequest(trustRecord, artifact);
689
708
  return { isTrusted: isValid, error };
690
709
  } else {
@@ -696,6 +715,22 @@ class BtpsServer {
696
715
  error: new BTPErrorException(refusal.error, { cause: refusal.problem })
697
716
  } : this.verifyPrivacyType(artifact, trustRecord);
698
717
  }
718
+ }
719
+ async detailsOwedByPerson(artifact) {
720
+ const { permissions, entityType, given } = artifact;
721
+ if (!permissions || entityType !== "person") return;
722
+ const [first] = detailsOwed(permissions, entityType, given);
723
+ if (!first) return;
724
+ let receiver;
725
+ try {
726
+ receiver = await this.entityTypeOf?.(artifact.to);
727
+ } catch {
728
+ receiver = void 0;
729
+ }
730
+ if (receiver !== "organisation")
731
+ return new BTPErrorException(BTP_ERROR_VALIDATION, {
732
+ cause: `asks for ${first.asked} without giving ${first.owed}`
733
+ });
699
734
  }
700
735
  verifyPrivacyType(artifact, trustRecord) {
701
736
  const required = trustRecord?.privacyType, sent = artifact.encryption ? "encrypted" : "unencrypted";
@@ -756,8 +791,10 @@ class BtpsServer {
756
791
  respondNow
757
792
  }), this.isResponseSent(resCtx)) return !0;
758
793
  } else {
794
+ const boundView = artifact.type === "BTPS_DOC" ? boundViewResultOf(artifact.document) : void 0;
795
+ boundView && (data = { ...data, boundView });
759
796
  const listeners = this.emitter.listeners("transporterArtifact");
760
- await Promise.all(listeners.map(async (listener) => listener(artifact)));
797
+ await Promise.all(listeners.map(async (listener) => listener(artifact, boundView)));
761
798
  }
762
799
  return await this._forwardArtifact(data), !1;
763
800
  }
@@ -935,7 +972,10 @@ class BtpsServer {
935
972
  type === "Agent" ? this.emitter.on(
936
973
  "agentArtifact",
937
974
  handler
938
- ) : this.emitter.on("transporterArtifact", handler);
975
+ ) : this.emitter.on(
976
+ "transporterArtifact",
977
+ handler
978
+ );
939
979
  }
940
980
  getServerIdentity() {
941
981
  const { identity } = this.serverIdentity;
@@ -9,6 +9,7 @@ export * from '../core/server/constants/index.js';
9
9
  export * from '../core/server/helpers/index.js';
10
10
  export { BtpsServer } from './btpsServer.js';
11
11
  export { lifecycleEventChainProblem, lifecycleEventChainReference, lifecycleEventSenderProblem, trustRequestProblem, trustResponseProblem, } from '../core/server/schemas/helpers.js';
12
+ export { checkBoundView, writtenValue, CONTRAST_WORK_LIMIT, type BTPBoundViewResult, type BTPBoundViewProblem, type BTPBoundViewCheck, } from '../core/server/schemas/boundViewChecks.js';
12
13
  export { wrapForAgent } from './libs/wrapForAgent.js';
13
14
  export { verifyTransporterSignature } from '../core/delegation/verifyTransporterSignature.js';
14
15
  export * from './types.js';
@@ -16,16 +16,24 @@ import {
16
16
  trustRequestProblem,
17
17
  trustResponseProblem
18
18
  } from "../core/server/schemas/helpers.js";
19
+ import {
20
+ checkBoundView,
21
+ writtenValue,
22
+ CONTRAST_WORK_LIMIT
23
+ } from "../core/server/schemas/boundViewChecks.js";
19
24
  import { wrapForAgent } from "./libs/wrapForAgent.js";
20
25
  import { verifyTransporterSignature } from "../core/delegation/verifyTransporterSignature.js";
21
26
  export * from "./types.js";
22
27
  export {
23
28
  BtpsServer,
29
+ CONTRAST_WORK_LIMIT,
30
+ checkBoundView,
24
31
  lifecycleEventChainProblem,
25
32
  lifecycleEventChainReference,
26
33
  lifecycleEventSenderProblem,
27
34
  trustRequestProblem,
28
35
  trustResponseProblem,
29
36
  verifyTransporterSignature,
30
- wrapForAgent
37
+ wrapForAgent,
38
+ writtenValue
31
39
  };
@@ -16,6 +16,9 @@ import type { Signer } from '../core/crypto/signer-interface.js';
16
16
  import type { BtpsKeyResolver } from '../core/crypto/keyResolver.js';
17
17
  import type { z } from 'zod';
18
18
  import type { BtpAgreementDocSchema, BtpLetterDocSchema, BtpPayslipDocSchema } from '../core/server/schemas/btpsDocsSchema.js';
19
+ import type { BTPBoundView } from '../core/server/schemas/boundViewSchema.js';
20
+ import type { BTPBoundViewResult } from '../core/server/schemas/boundViewChecks.js';
21
+ import type { BTPEntityType } from '../core/server/types.js';
19
22
  export interface BtpsTlsOptions extends TlsOptions {
20
23
  cert: string;
21
24
  key: string;
@@ -70,6 +73,13 @@ export interface BtpsServerOptions {
70
73
  * lookups; a `keyResolver` with `resolveKeyChain` keeps its own cache, and must honour it.
71
74
  */
72
75
  keyChainMaxCacheSeconds?: number;
76
+ /**
77
+ * Since 1.2: whether one of this server's own identities is a person or an organisation, as
78
+ * its platform knows it; undefined when it does not say. A person asking an organisation for
79
+ * details gives nothing in return; every other request gives what it asks for. Without this
80
+ * option every receiver is held to be a person, so every request gives what it asks for.
81
+ */
82
+ entityTypeOf?: (identity: string) => BTPEntityType | undefined | Promise<BTPEntityType | undefined>;
73
83
  }
74
84
  /** Since 1.2: a details request arrived: who asked whom for which details, and when. */
75
85
  export interface BTPDetailsRequestedInfo {
@@ -127,6 +137,10 @@ type WithRespondNow<K extends string, T> = K extends 'agent' ? {
127
137
  artifact: T;
128
138
  type: K;
129
139
  respondNow: boolean;
140
+ } : K extends 'transporter' ? {
141
+ artifact: T;
142
+ type: K;
143
+ boundView?: BTPBoundViewResult;
130
144
  } : {
131
145
  artifact: T;
132
146
  type: K;
@@ -234,8 +248,12 @@ export interface BTPInvoiceDoc {
234
248
  amount: number;
235
249
  currency: CurrencyCode;
236
250
  };
251
+ /** Since 1.2: the total before tax, and the tax, in the currency of `totalAmount` */
252
+ subtotalAmount?: BTPInvoiceDoc['totalAmount'];
253
+ taxAmount?: BTPInvoiceDoc['totalAmount'];
237
254
  lineItems: {
238
255
  columns: string[];
256
+ roles?: Record<string, BTPLineRole>;
239
257
  rows: Array<Record<string, string | number>>;
240
258
  };
241
259
  issuer?: {
@@ -245,6 +263,10 @@ export interface BTPInvoiceDoc {
245
263
  address?: string;
246
264
  identifiers?: Record<string, string>;
247
265
  };
266
+ /** Since 1.2: who the document is for, as the sender names them */
267
+ recipient?: {
268
+ name: string;
269
+ };
248
270
  paymentLink?: {
249
271
  linkText: string;
250
272
  url: string;
@@ -255,6 +277,8 @@ export interface BTPInvoiceDoc {
255
277
  attachments?: BTPAttachment[];
256
278
  references?: BTPDocReference[];
257
279
  template?: BTPTemplate;
280
+ /** Since 1.2: its BoundView, a signed canvas whose facts are drawn from these fields */
281
+ boundView?: BTPBoundView;
258
282
  metadata?: Record<string, unknown>;
259
283
  }
260
284
  /**
@@ -272,34 +296,16 @@ export type BTPDiscount = {
272
296
  } | {
273
297
  percent: number;
274
298
  };
275
- /** A template by reference. Since 1.2 its named data fields, each optional, are well formed when present. */
299
+ /** A template by name, with free data: the 1.1 form, in any version. A receiver draws nothing from it. */
276
300
  export interface BTPTemplate {
277
301
  name: string;
278
- data: {
279
- version?: string;
280
- sha256?: string;
281
- source?: string;
282
- logo?: {
283
- sha256: string;
284
- source: string;
285
- };
286
- values?: BTPTemplateValues;
287
- [key: string]: unknown;
288
- };
289
- }
290
- /**
291
- * Since 1.2: what a letter template's signature slots show, from the sender and
292
- * signed with the document. A drawn signature is integer strokes, `[x, y, x, y, …]`,
293
- * on a canvas 1000 by 300: data a receiver draws itself, never markup.
294
- */
295
- export interface BTPTemplateValues {
296
- 'signature.typed'?: string;
297
- 'signature.name'?: string;
298
- 'signature.title'?: string;
299
- 'signature.drawn'?: {
300
- strokes: number[][];
301
- };
302
+ data: Record<string, unknown>;
302
303
  }
304
+ /** Since 1.2: what a line-item column holds. */
305
+ export type BTPLineRole = 'description' | 'quantity' | 'unitPrice' | 'discount' | 'tax' | 'lineTotal';
306
+ /** Since 1.2: a letter's or an agreement's sign-off. Decoration: it proves no agreement. */
307
+ export type BTPSignatory = NonNullable<BTPLetterDoc['signatory']>;
308
+ export type { BTPBoundView, BTPBoundViewElement, BTPBoundViewFont, } from '../core/server/schemas/boundViewSchema.js';
303
309
  /** Proof of a payment: the invoice without what asks for payment, plus `payment`. */
304
310
  export interface BTPReceiptDoc extends Omit<BTPInvoiceDoc, 'type' | 'dueAt' | 'paymentLink' | 'lineItems'> {
305
311
  type: 'receipt';
@@ -319,4 +325,3 @@ export type BTPLetterDoc = z.infer<typeof BtpLetterDocSchema>;
319
325
  export type BTPAgreementDoc = z.infer<typeof BtpAgreementDocSchema>;
320
326
  /** What a `BTPS_DOC` carries. */
321
327
  export type BTPDocument = BTPInvoiceDoc | BTPReceiptDoc | BTPPayslipDoc | BTPLetterDoc | BTPAgreementDoc;
322
- export {};
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@btps/sdk",
3
- "version": "1.2.0-rc.1",
3
+ "version": "1.2.0-rc.3",
4
4
  "description": "The reference implementation of BTPS, the Billing Trust Protocol Secure: signed, encrypted, trust-first delivery of invoices and documents between organisations.",
5
5
  "keywords": [
6
6
  "btps",
@@ -63,6 +63,9 @@
63
63
  },
64
64
  "./storage": {
65
65
  "import": "./dist/core/storage/index.js"
66
+ },
67
+ "./boundview": {
68
+ "import": "./dist/core/server/schemas/boundView.js"
66
69
  }
67
70
  },
68
71
  "bin": {
@@ -94,6 +97,13 @@
94
97
  "build:strip-comments": "node build/stripComments.mjs"
95
98
  },
96
99
  "devDependencies": {
100
+ "@fontsource/arimo": "^5.3.0",
101
+ "@fontsource/caladea": "^5.3.0",
102
+ "@fontsource/carlito": "^5.3.0",
103
+ "@fontsource/caveat": "^5.3.0",
104
+ "@fontsource/cousine": "^5.3.0",
105
+ "@fontsource/tinos": "^5.3.0",
106
+ "@resvg/resvg-wasm": "2.6.2",
97
107
  "@types/lodash": "^4",
98
108
  "@types/proper-lockfile": "^4",
99
109
  "@types/split2": "^4",
@@ -114,7 +124,9 @@
114
124
  "eslint-plugin-import": "^2.29.0",
115
125
  "fast-glob": "^3.3.3",
116
126
  "nodemon": "^3.0.0",
127
+ "opentype.js": "^2.0.0",
117
128
  "ora": "^8.2.0",
129
+ "playwright-core": "^1.56.0",
118
130
  "prettier": "^3.0.0",
119
131
  "rimraf": "^6.0.1",
120
132
  "strip-comments": "^2.0.1",
@@ -128,6 +140,7 @@
128
140
  "@humanwhocodes/momoa": "^3.3.13",
129
141
  "asn1js": "^4.0.0",
130
142
  "canonicalize": "^5.1.0",
143
+ "fflate": "^0.8.3",
131
144
  "lodash": "^4.17.21",
132
145
  "pkijs": "^4.0.1",
133
146
  "proper-lockfile": "^4.1.2",