@btps/sdk 1.2.0-rc.1 → 1.2.0-rc.2

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.
@@ -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
@@ -28,6 +28,8 @@ export declare class BtpsServer {
28
28
  private readonly maxArtifactAgeSeconds;
29
29
  private readonly signAnswers;
30
30
  private readonly keyResolver?;
31
+ /** Since 1.2: what each of this server's identities is, as its platform says. */
32
+ private readonly entityTypeOf?;
31
33
  /** Since 1.2: how a sender's, a delegator's and an attestor's key is checked against its key chain. */
32
34
  private readonly keyChains;
33
35
  /** Since 1.2: what `on(…)` tells its listeners, apart from the artifact handlers. */
@@ -222,6 +224,13 @@ export declare class BtpsServer {
222
224
  * Core trust verification (non-negotiable)
223
225
  */
224
226
  private verifyTrust;
227
+ /**
228
+ * Since 1.2: a person's trust request that asks for details without giving its own. It is
229
+ * refused unless its receiver is an organisation, as `entityTypeOf` says: a person asking an
230
+ * organisation gives nothing in return. A receiver this server cannot say is held to be a
231
+ * person. An organisation's request is held to it by the schema, whoever receives it.
232
+ */
233
+ private detailsOwedByPerson;
225
234
  /**
226
235
  * A trust records how its artifacts are sent: 'encrypted' refuses one sent in
227
236
  * the clear, 'unencrypted' one the receiver did not agree to decrypt, and
@@ -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,7 @@ import {
57
60
  isBtpsAgentArtifact,
58
61
  isValidIdentity
59
62
  } from "../core/utils/index.js";
63
+ import { detailsOwed } from "../core/server/schemas/artifacts/transporterSchema.js";
60
64
  import { BTPErrorException, transformToBTPErrorException } from "../core/error/index.js";
61
65
  import {
62
66
  AGENT_TRANSPORTER_ACTIONS,
@@ -101,6 +105,15 @@ const lastRotationTo = (chain) => {
101
105
  Object.values(BTPS_ERROR_CONSTANTS).filter(
102
106
  (value) => typeof value == "object" && value !== null && typeof value.code == "string" && typeof value.status == "number"
103
107
  ).map((constant) => [String(constant.code), constant])
108
+ ), TOLD_AS_ITSELF = new Set(
109
+ [
110
+ BTP_ERROR_VALIDATION.code,
111
+ BTP_ERROR_PRIVACY_TYPE.code,
112
+ BTP_ERROR_PERMISSION.code,
113
+ BTP_ERROR_PERMISSION_REQUIRED.code,
114
+ BTP_ERROR_DOCUMENT_TYPE_MISMATCH.code,
115
+ BTP_ERROR_DETAILS_NOT_HELD.code
116
+ ].map(String)
104
117
  );
105
118
  class BtpsServer {
106
119
  tlsOptions;
@@ -116,6 +129,7 @@ class BtpsServer {
116
129
  maxArtifactAgeSeconds;
117
130
  signAnswers;
118
131
  keyResolver;
132
+ entityTypeOf;
119
133
  keyChains;
120
134
  events = new EventEmitter();
121
135
  answersOnSocket = new WeakMap();
@@ -125,7 +139,7 @@ class BtpsServer {
125
139
  emitter = new EventEmitter();
126
140
  handlerFn = null;
127
141
  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(
142
+ 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
143
  options.maxInFlightPerConnection
130
144
  ), this.maxConsecutiveInvalidLines = resolveMaxConsecutiveInvalidLines(
131
145
  options.maxConsecutiveInvalidLines
@@ -437,7 +451,7 @@ class BtpsServer {
437
451
  resCtx
438
452
  )) return;
439
453
  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;
454
+ 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
455
  return this.sendBtpsError(resCtx.socket, wireError, resCtx.reqId);
442
456
  }
443
457
  this.tellDetails(data), !(await this.executeMiddleware(
@@ -685,6 +699,8 @@ class BtpsServer {
685
699
  if (isTrustActive(ownTrust)) return this.verifyPrivacyType(artifact, ownTrust);
686
700
  }
687
701
  if (artifact.type === "TRUST_REQ") {
702
+ const owes = await this.detailsOwedByPerson(artifact);
703
+ if (owes) return { isTrusted: !1, error: owes };
688
704
  const { isValid, error } = validateTrustRequest(trustRecord, artifact);
689
705
  return { isTrusted: isValid, error };
690
706
  } else {
@@ -696,6 +712,22 @@ class BtpsServer {
696
712
  error: new BTPErrorException(refusal.error, { cause: refusal.problem })
697
713
  } : this.verifyPrivacyType(artifact, trustRecord);
698
714
  }
715
+ }
716
+ async detailsOwedByPerson(artifact) {
717
+ const { permissions, entityType, given } = artifact;
718
+ if (!permissions || entityType !== "person") return;
719
+ const [first] = detailsOwed(permissions, entityType, given);
720
+ if (!first) return;
721
+ let receiver;
722
+ try {
723
+ receiver = await this.entityTypeOf?.(artifact.to);
724
+ } catch {
725
+ receiver = void 0;
726
+ }
727
+ if (receiver !== "organisation")
728
+ return new BTPErrorException(BTP_ERROR_VALIDATION, {
729
+ cause: `asks for ${first.asked} without giving ${first.owed}`
730
+ });
699
731
  }
700
732
  verifyPrivacyType(artifact, trustRecord) {
701
733
  const required = trustRecord?.privacyType, sent = artifact.encryption ? "encrypted" : "unencrypted";
@@ -16,6 +16,7 @@ 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 { BTPEntityType } from '../core/server/types.js';
19
20
  export interface BtpsTlsOptions extends TlsOptions {
20
21
  cert: string;
21
22
  key: string;
@@ -70,6 +71,13 @@ export interface BtpsServerOptions {
70
71
  * lookups; a `keyResolver` with `resolveKeyChain` keeps its own cache, and must honour it.
71
72
  */
72
73
  keyChainMaxCacheSeconds?: number;
74
+ /**
75
+ * Since 1.2: whether one of this server's own identities is a person or an organisation, as
76
+ * its platform knows it; undefined when it does not say. A person asking an organisation for
77
+ * details gives nothing in return; every other request gives what it asks for. Without this
78
+ * option every receiver is held to be a person, so every request gives what it asks for.
79
+ */
80
+ entityTypeOf?: (identity: string) => BTPEntityType | undefined | Promise<BTPEntityType | undefined>;
73
81
  }
74
82
  /** Since 1.2: a details request arrived: who asked whom for which details, and when. */
75
83
  export interface BTPDetailsRequestedInfo {
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.2",
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",