@btps/sdk 1.1.3 → 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.
Files changed (111) hide show
  1. package/CHANGELOG.md +461 -0
  2. package/bin/verify-evidence-bundle.mjs +96 -0
  3. package/dist/client/btpsAgent.d.ts +10 -1
  4. package/dist/client/btpsAgent.js +116 -18
  5. package/dist/client/btpsClient.d.ts +53 -7
  6. package/dist/client/btpsClient.js +265 -147
  7. package/dist/client/index.d.ts +1 -1
  8. package/dist/client/index.js +3 -1
  9. package/dist/client/libs/schema.js +78 -13
  10. package/dist/client/libs/timeouts.d.ts +6 -0
  11. package/dist/client/libs/timeouts.js +2 -1
  12. package/dist/client/types/index.d.ts +54 -2
  13. package/dist/core/authentication/BtpsAuthentication.d.ts +43 -1
  14. package/dist/core/authentication/BtpsAuthentication.js +152 -36
  15. package/dist/core/authentication/refreshSuccessor.js +47 -0
  16. package/dist/core/authentication/storage/InMemoryTokenStore.d.ts +17 -1
  17. package/dist/core/authentication/storage/InMemoryTokenStore.js +16 -4
  18. package/dist/core/authentication/types.d.ts +82 -0
  19. package/dist/core/crypto/contentKey.d.ts +34 -0
  20. package/dist/core/crypto/contentKey.js +64 -0
  21. package/dist/core/crypto/decryptVerify.d.ts +7 -1
  22. package/dist/core/crypto/decryptVerify.js +23 -5
  23. package/dist/core/crypto/decrypter-interface.d.ts +6 -0
  24. package/dist/core/crypto/index.d.ts +12 -0
  25. package/dist/core/crypto/index.js +7 -1
  26. package/dist/core/crypto/keyResolver.d.ts +48 -0
  27. package/dist/core/crypto/keyResolver.js +46 -0
  28. package/dist/core/crypto/pem-decrypter.d.ts +2 -0
  29. package/dist/core/crypto/pem-decrypter.js +13 -8
  30. package/dist/core/crypto/signEncrypt.d.ts +4 -1
  31. package/dist/core/crypto/signEncrypt.js +20 -5
  32. package/dist/core/crypto/types.d.ts +8 -1
  33. package/dist/core/delegation/BtpsDelegator.d.ts +4 -0
  34. package/dist/core/delegation/BtpsDelegator.js +3 -2
  35. package/dist/core/delegation/verifyTransporterSignature.d.ts +104 -0
  36. package/dist/core/delegation/verifyTransporterSignature.js +224 -0
  37. package/dist/core/error/constant.d.ts +39 -0
  38. package/dist/core/error/constant.js +55 -0
  39. package/dist/core/server/constants/btps-protocol.d.ts +21 -5
  40. package/dist/core/server/constants/btps-protocol.js +46 -8
  41. package/dist/core/server/constants/index.d.ts +7 -3
  42. package/dist/core/server/constants/index.js +19 -4
  43. package/dist/core/server/constants/limits.d.ts +18 -0
  44. package/dist/core/server/constants/limits.js +19 -1
  45. package/dist/core/server/constants/permissions.d.ts +38 -0
  46. package/dist/core/server/constants/permissions.js +38 -0
  47. package/dist/core/server/schemas/artifacts/agentSchema.js +2 -1
  48. package/dist/core/server/schemas/artifacts/artifacts.js +7 -1
  49. package/dist/core/server/schemas/artifacts/controlSchema.js +1 -1
  50. package/dist/core/server/schemas/artifacts/identityLookupSchema.js +10 -1
  51. package/dist/core/server/schemas/artifacts/transporterSchema.js +99 -12
  52. package/dist/core/server/schemas/bounded.js +2 -2
  53. package/dist/core/server/schemas/btpsDocsSchema.d.ts +36009 -1083
  54. package/dist/core/server/schemas/btpsDocsSchema.js +305 -42
  55. package/dist/core/server/schemas/helpers.d.ts +10090 -0
  56. package/dist/core/server/schemas/helpers.js +76 -12
  57. package/dist/core/server/schemas/keyChainSchema.js +53 -0
  58. package/dist/core/server/schemas/responseSchema.js +52 -9
  59. package/dist/core/server/schemas/schema.js +3 -1
  60. package/dist/core/server/schemas/trustValues.d.ts +105 -0
  61. package/dist/core/server/schemas/trustValues.js +117 -0
  62. package/dist/core/server/types.d.ts +104 -6
  63. package/dist/core/storage/AbstractIdentityStore.d.ts +9 -0
  64. package/dist/core/storage/JsonIdentityStore.d.ts +3 -0
  65. package/dist/core/storage/JsonIdentityStore.js +3 -0
  66. package/dist/core/storage/types.d.ts +2 -0
  67. package/dist/core/trust/agreements.d.ts +107 -0
  68. package/dist/core/trust/agreements.js +116 -0
  69. package/dist/core/trust/evidence.d.ts +220 -0
  70. package/dist/core/trust/evidence.js +334 -0
  71. package/dist/core/trust/index.d.ts +10 -0
  72. package/dist/core/trust/index.js +14 -1
  73. package/dist/core/trust/keyRotation.d.ts +148 -0
  74. package/dist/core/trust/keyRotation.js +267 -0
  75. package/dist/core/trust/permissions.d.ts +114 -0
  76. package/dist/core/trust/permissions.js +115 -0
  77. package/dist/core/trust/shaping.d.ts +42 -0
  78. package/dist/core/trust/shaping.js +47 -0
  79. package/dist/core/trust/storage/AbstractTrustStore.d.ts +2 -1
  80. package/dist/core/trust/storage/JsonTrustStore.d.ts +3 -2
  81. package/dist/core/trust/timestamps.d.ts +49 -0
  82. package/dist/core/trust/timestamps.js +78 -0
  83. package/dist/core/trust/trustUtils.d.ts +13 -2
  84. package/dist/core/trust/trustUtils.js +28 -3
  85. package/dist/core/trust/types.d.ts +312 -2
  86. package/dist/core/trust/verification.d.ts +52 -0
  87. package/dist/core/trust/verification.js +55 -0
  88. package/dist/server/btpsServer.d.ts +79 -5
  89. package/dist/server/btpsServer.js +297 -145
  90. package/dist/server/index.d.ts +3 -0
  91. package/dist/server/index.js +17 -1
  92. package/dist/server/libs/agreementOrderCheck.d.ts +29 -0
  93. package/dist/server/libs/agreementOrderCheck.js +29 -0
  94. package/dist/server/libs/artifactTimeWindow.d.ts +2 -2
  95. package/dist/server/libs/artifactTimeWindow.js +2 -1
  96. package/dist/server/libs/detailsRequestLimit.d.ts +27 -0
  97. package/dist/server/libs/detailsRequestLimit.js +28 -0
  98. package/dist/server/libs/detailsResponseCheck.d.ts +27 -0
  99. package/dist/server/libs/detailsResponseCheck.js +27 -0
  100. package/dist/server/libs/eventChainCheck.d.ts +31 -0
  101. package/dist/server/libs/eventChainCheck.js +39 -0
  102. package/dist/server/libs/inFlightLimit.d.ts +10 -0
  103. package/dist/server/libs/inFlightLimit.js +7 -1
  104. package/dist/server/libs/index.d.ts +5 -0
  105. package/dist/server/libs/index.js +10 -0
  106. package/dist/server/libs/keyChains.d.ts +14 -0
  107. package/dist/server/libs/keyChains.js +17 -0
  108. package/dist/server/libs/wrapForAgent.d.ts +20 -0
  109. package/dist/server/libs/wrapForAgent.js +36 -0
  110. package/dist/server/types.d.ts +103 -9
  111. package/package.json +12 -3
package/CHANGELOG.md CHANGED
@@ -4,6 +4,467 @@ 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.2] — 2026-11-11 (beta, release candidate)
8
+
9
+ What eBill found running 1.2.0-rc.1. Everything in rc.1 below still holds.
10
+
11
+ ### Added
12
+
13
+ - **A signer's own signature on its acceptance.** An agreement statement may
14
+ carry `visualSignature`, typed (`{ type: 'typed', text }`) or drawn
15
+ (`{ type: 'drawn', strokes }`), with a letter signature's limits, on an
16
+ `accepted` statement only. It is inside the statement, so the statement's
17
+ signature covers it and the evidence bundle keeps it. It is optional in the
18
+ protocol; a platform may require one. A 1.2.0-rc.1 receiver refuses a
19
+ statement that carries one.
20
+ - The server option `entityTypeOf`: whether one of the platform's own
21
+ addresses is a person or an organisation, so the server can tell what a
22
+ person's trust request owes (see Changed).
23
+
24
+ ### Changed
25
+
26
+ - A `1.2.0` trust request carries `permissions`. One without them is refused
27
+ on arrival; a request for everything is a `1.1.0` one, which every server
28
+ still takes.
29
+ - A person asking an organisation for details gives nothing in return. An
30
+ organisation's request still gives what it asks for to anyone, and a
31
+ person's to another person. Only the receiver's own server knows what the
32
+ receiver is, so a person's request is now checked there, against
33
+ `entityTypeOf`, instead of by the schema; without the option, every receiver
34
+ is held to be a person, as before.
35
+
36
+ ### Fixed
37
+
38
+ - A refusal of a trust's permissions reaches the sender as itself:
39
+ `BTP_ERROR_PERMISSION_REQUIRED` for a grant that withholds a required name,
40
+ `BTP_ERROR_PERMISSION` for a name not granted or not asked for,
41
+ `BTP_ERROR_DOCUMENT_TYPE_MISMATCH` and `BTP_ERROR_DETAILS_NOT_HELD`. Each
42
+ read `BTP_ERROR_TRUST_NOT_ALLOWED` on the wire, so a platform could not tell
43
+ its user what to fix. Refusals about a trust's state still read "not
44
+ allowed", so a stranger learns nothing of it.
45
+
46
+ ## [1.2.0-rc.1] — 2026-11-08 (beta, release candidate)
47
+
48
+ 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).
49
+ Upgrading a 1.1 provider: [Migrating from 1.1 to 1.2](https://www.openbtps.org/docs/next/whats-new/1-2/migration).
50
+
51
+ ### Added
52
+
53
+ - **BTPS 1.2 speaks 1.1 and 1.2.** A 1.2 server takes any 1.1.x and 1.2.x
54
+ artifact. A 1.2 sender stamps an artifact `1.1.0` whenever everything in it
55
+ can be said in 1.1 (`artifactVersion`), and `1.2.0` only when it uses
56
+ something 1.2 adds, so a 1.1 and a 1.2 provider always talk. Identity
57
+ lookups and control artifacts are always `1.1.0`.
58
+ - `BtpsClient.getServerVersion()`: the version a server speaks, from its
59
+ answer to a `PING` that every 1.1 and 1.2 server answers.
60
+ - `resolveIdentity` also returns `serverVersion` when the address's host
61
+ answered: the version its server speaks, from its signed answer.
62
+ - A "created, with this id" answer, `{ id }` (`BTPCreatedResDoc`), so
63
+ `draft.create` can return the new draft's id.
64
+ - **The `withdrawn` event.** The sender of an unanswered proposal takes it
65
+ back with `withdrawn`, naming it in `inReplyTo`; a proposal sent again names
66
+ the `withdrawn` it follows in `follows`. Both travel only in `1.2.0`
67
+ artifacts; under `1.1.0` an event is read exactly as 1.1 reads it
68
+ (`processBtpDocSchema` now takes the artifact's version).
69
+ - `BTP_ERROR_EVENT_CHAIN`: the new `eventChainCheck` middleware
70
+ (`@btps/sdk/server/core`, off until added) refuses a `withdrawn` or
71
+ `follows` from the invoice's issuer, since only the payer withdraws or
72
+ proposes again. With the platform's own `getEvent` lookup, it also refuses a
73
+ `withdrawn` that does not take back the payer's own open proposal about the
74
+ same invoice, and a `follows` that names no `withdrawn` about it. It tells
75
+ the sender which rule it broke. The server checks no chain itself.
76
+ `lifecycleEventChainProblem` and `lifecycleEventSenderProblem`
77
+ (`@btps/sdk/server`) let a platform check an encrypted event the same way
78
+ once it has opened it.
79
+ - **Notes say how they are written.** An invoice's and receipt's
80
+ `description`, an event's `message`, and a trust request's or response's
81
+ `message` may be `{ format: 'text' | 'markdown', content }` (`BTPNote`); a
82
+ plain string is still taken, read as `text`. In a `1.2.0` artifact a note's
83
+ content is at most 5,000 characters.
84
+ - **Discounts.** An invoice or receipt may carry `discount`, `{ amount }` in
85
+ minor units or `{ percent }` in whole basis points (1 to 10,000), applied
86
+ before tax (`BTPDiscount`). In a `1.2.0` artifact a line's `discount` cell is
87
+ an amount of at least 0.
88
+ - **Templates by reference.** In a `1.2.0` artifact a template's named `data`
89
+ fields (`version`, `sha256`, `source`, `logo`) are well formed when present
90
+ (`BTPTemplate`), a `source` always comes with its `sha256`, and a letter or
91
+ payslip may name a template. The template file's format is specified on the
92
+ new Templates page, with a JSON Schema published with the docs
93
+ (`schemas/btps-template.schema.json`) and golden vectors
94
+ (`templates.vectors.json`). Format 1 says how an invoice or receipt looks,
95
+ never what it says: it never carries or changes a value, hides no section
96
+ with signed fields, fetches nothing and runs nothing, and its labels, terms
97
+ and footer are plain text, with no markup and no control, hidden or
98
+ direction-changing character. What those words say is the platform's
99
+ policy; the Templates page recommends refusing digit runs and web, email
100
+ and BTPS addresses, where a fake payment detail would hide. Its fingerprint is the
101
+ SHA-256 of its RFC 8785 canonical form. The SDK renders nothing.
102
+ - **Template format 2: payslips and letters.** Format 2 is format 1 for
103
+ invoices and receipts, plus a payslip template (the payslip's own sections
104
+ and labels, every one with signed fields shown) and a letter template, which
105
+ sets only the page, a letterhead placing the sender's own fields, and a
106
+ footer with a sign-off and signature slots, never the body. A letter's
107
+ template carries the slots' values in `template.data.values`
108
+ (`BTPTemplateValues`), signed with the letter, 1.2.0 only: a typed
109
+ signature, drawn in the open-licence script font Caveat, a name, a title, and
110
+ a drawn signature as integer strokes on a 1,000 by 300 canvas, never markup.
111
+ Such a signature is decoration and proves no agreement.
112
+ - Every 1.2 document rule applies under `1.2.0` only: a document valid in 1.1
113
+ reads exactly as before in a `1.1.0` artifact. The schemas 1.1 reads with are
114
+ kept beside the newest (`Btp…V1_1Schema`). A device checks what it sends
115
+ under the version it will stamp it with, so it sends whatever a 1.1 device
116
+ could; a draft or edit takes either version's shape.
117
+ - **Signed answers, and a device that requires them.** A server with
118
+ `signAnswers` signs every answer, errors included, as `serverIdentity` under
119
+ its new `selector`. A client with `requireSignedBy: { identity, selector }`
120
+ takes no answer but one signed by that signer under that selector, and
121
+ refuses any other before it looks up a key. `serverIdentity` is the
122
+ domain's operator, whose key signs identity-lookup answers too, so a
123
+ provider keeps one key pair and its app pins the operator.
124
+ - **Sync.** A device's sync is an `artifact.send` to the user's own address
125
+ that names the send it copies on its envelope, `syncOf: { id, sha256 }`
126
+ (`BtpsAgentCommandOptions.syncOf`; `syncOfArtifact` computes it). It is only
127
+ from and to the same address, only in `1.2.0` artifacts, and only inside a
128
+ device's `artifact.send`: a server refuses one sent to it directly
129
+ (`BTP_ERROR_SYNC_NOT_ALLOWED`).
130
+ - **Trust permissions on the envelope.** A `TRUST_REQ` may carry
131
+ `permissions` (one flat list of the `send:` and `detail:` names it asks
132
+ for, each `required` or not, each once, with at least one `send:`), `entityType`, `given` (the details it gives) and `change`; an
133
+ accepted `TRUST_RES` carries `granted` and the responder's `entityType`; a
134
+ `BTPS_DOC` may carry `documentType`. All are signed, readable and `1.2.0`
135
+ only. A server refuses on arrival a name that is not the protocol's, a
136
+ request that does not give what it asks for (a person's `detail:dob` and an
137
+ organisation's `detail:registrationNumber` swap between kinds), and a
138
+ readable request or answer that carries values unencrypted. The names are
139
+ exported from `@btps/sdk/trust` (`DOCUMENT_TYPES`, `SEND_PERMISSIONS`,
140
+ `DETAIL_PERMISSIONS`).
141
+ - **Trust permission values, checked when opened.** A request gives each name
142
+ in `given` its value, in the 1.1 field it has (`name` is `detail:legalName`,
143
+ and so on) or else in `own`, by name; an answer holds every granted detail's
144
+ value in `details`, by name. `decryptVerify` refuses a request or answer
145
+ whose values do not match its names, or whose values are not their names'
146
+ shapes (`{ number, country }`, a `YYYY-MM-DD` date, a profile with https
147
+ addresses), with `BTP_ERROR_VALIDATION`. `trustRequestProblem` and
148
+ `trustResponseProblem` in `@btps/sdk/trust` run the same check.
149
+ - **Trust permissions on the trust record.** A record may carry `permissions`
150
+ (`requested`, `granted`, `detailsHeld`, `detailsShared`, `pendingChange`),
151
+ which the platform writes and the server only reads; without it, a 1.1
152
+ trust. `trustPermissionsFromRequest` and `trustPermissionsFromResponse`
153
+ compute what to save. A server refuses a `TRUST_RES` whose `granted` leaves
154
+ out a required name, or that its record cannot check
155
+ (`BTP_ERROR_PERMISSION_REQUIRED`), or that grants a name never asked for
156
+ (`BTP_ERROR_PERMISSION`), and takes an answer on an accepted trust only to a
157
+ pending change (`trustGrantProblem`; `validateTrustResponse` gains an
158
+ optional `response`). `BTPDetailValues` now types each detail's value.
159
+ - **A send's document type.** Under a trust with permissions, a server refuses
160
+ a `BTPS_DOC` that names no `documentType`, or one whose `send:<type>` the
161
+ trust does not grant (`BTP_ERROR_PERMISSION`), and a readable document that
162
+ is not its `documentType` (`BTP_ERROR_DOCUMENT_TYPE_MISMATCH`, also from
163
+ `decryptVerify` once opened and from `signEncrypt` before sending). A device
164
+ sets it with `artifact.send`'s new `documentType` option. A trust without
165
+ permissions takes any type, as in 1.1 (`documentTypeProblem`). A device's
166
+ send is checked the same way by its own provider before it goes, from the
167
+ user's own record of the trust in its direction, sender to receiver.
168
+ - **Details refresh.** Three new artifact types, `DETAILS_CHANGED`,
169
+ `DETAILS_REQ` and `DETAILS_RES`, carry `details`, the `detail:` names they
170
+ are about, on the envelope, so each side of an active trust is told when the
171
+ other's details change and can fetch again only what it already holds. A
172
+ server checks the names against its own record of the trust, in either
173
+ direction (`BTP_ERROR_DETAILS_NOT_HELD`), and that a response answers a
174
+ request it knows (`isKnownArtifact`, `BTP_ERROR_PERMISSION`). Two new
175
+ middleware (`@btps/sdk/server/core`, off until added) are the platform's:
176
+ `detailsResponseCheck({ getArtifact })` refuses a response naming what its
177
+ request did not ask for (`BTP_ERROR_PERMISSION`), and
178
+ `detailsRequestLimit(allow)` a request over the provider's own limit
179
+ (`BTP_ERROR_DETAILS_RATE_LIMITED`, with `status.retryAfter`). A request
180
+ that passes every check, middleware included, is told to
181
+ `server.on('detailsRequested', …)`. `decryptVerify` refuses an opened
182
+ response whose values do not match its names (`detailsProblem`).
183
+ `JsonTrustStore` keeps no artifacts, so a server using it as is takes no
184
+ `DETAILS_RES` until the store is extended to answer from the platform's own
185
+ records. The known-failing vector list is empty.
186
+ - **Details refresh from a device.** New agent actions `details.changed`,
187
+ `details.request` and `details.respond`, with the `BtpsAgent` command option
188
+ `details` (a response also needs `relatesTo` and encryption). The device's
189
+ own provider checks the names before it sends them, as the receiver will,
190
+ from the user's own record of the trust, and tells
191
+ `server.on('detailsShared', …)` of each response that passes every check.
192
+ - **A device's trust request and answer with permissions.** New `BtpsAgent`
193
+ command options: `permissions`, `entityType`, `given` and `change` on
194
+ `trust.request`, and `granted` and `entityType` on `trust.respond`. They go
195
+ on the envelope and stamp the artifact `1.2.0`, and the agent checks the
196
+ artifact as its provider will before it goes, so a request that does not
197
+ give what it asks for is refused before it is sent.
198
+ - **Verification.** A trust request's document may carry `verification`, a
199
+ provider's signed statement of what it checked of the sender: `claims` by
200
+ the protocol's names only (`entityType` and `detail:` values in their
201
+ shapes), signed over the sender's own address so it cannot be copied. A
202
+ request carrying one is encrypted. `signVerification` makes one;
203
+ `verificationFacts` reports `{ signatureValid, expired,
204
+ verifierServesSender, verifierIsOperator }` and refuses nothing. Only one who
205
+ runs a BTPS server verifies: `verifiedBy` is the `op` of its own domain's
206
+ `_btps.host`, or `decryptVerify` refuses the request (`verifierRefusal`); a
207
+ lookup that fails is `BTP_ERROR_RESOLVE_DNS`, to try again.
208
+ Whose verifications to trust is each provider's to decide.
209
+ - **A trust request composed for its receiver's version.** Before a trust
210
+ request with permissions is signed, the agent and `signEncrypt` ask the
211
+ receiver's server its version with one `PING`. To a 1.1 server it goes as
212
+ 1.1 allows, without the permission fields and the values that stamp it
213
+ `1.2.0`, and the result says so in `shaped` (`{ sentAs, leftOut }`); with
214
+ `versionFallback: false` it is refused with the receiver's version. If the
215
+ server cannot be asked, nothing is sent. A request without permissions is
216
+ never asked about. `shapeTrustRequestFor11` and `composeTrustRequestFor`
217
+ are exported for platforms that build artifacts another way.
218
+ - **Agreements.** `agreement` is a fifth document type, `1.2.0` only: a letter
219
+ that asks its signers to accept it (`BTPAgreementDoc`). It carries a required
220
+ `acceptance` (`by`, `terms` naming its attachments, 1 to 20 `signers`,
221
+ `signingOrder` `any` or `sequential`) and `originatorSignature`, and a letter
222
+ never carries `acceptance`. `send:agreement` joins the permission names, and
223
+ letter templates draw agreements too (`kinds` `letter`, `agreement`).
224
+ - **Agreements are signed over their content.** `signAgreement` signs
225
+ `{ originator, id, contentSha256 }` (`agreementRef`, `agreementContentSha256`),
226
+ and `originatorSignatureValid` checks it. A signer's answer is a statement
227
+ record, signed with its identity key (`signStatement`) or a device key
228
+ (`signStatementOnDevice`, completed by `deviceStatementRecord` with the
229
+ delegated artifact that delivered it). `statementSignatureFacts` reports
230
+ `signatureValid`, `keyKind` and, for a device, `delegatedBy` and
231
+ `attestedBy`; `statementRecordSha256` is what the next statement names as
232
+ `previous`.
233
+ - **Agreement events.** A `BTPS_EVENT` may carry an `agreement_event`,
234
+ `1.2.0` only (`BTPAgreementEvent`): a signer's `accepted` or `declined`,
235
+ each with its statement record, and the originator's `agreement_progress`
236
+ and `agreement_complete`, carrying the records so far. The server checks an
237
+ answer's structure, signatures, trust and permissions only; its order is the
238
+ originator's platform's. The new `agreementOrderCheck` middleware
239
+ (`@btps/sdk/server/core`, off until added with the platform's own lookup)
240
+ refuses an answer out of turn in flight from its envelope, without opening
241
+ it (`BTP_ERROR_AGREEMENT_ORDER`; `agreementTurnProblem`). Once opened, the
242
+ platform checks the statement with `agreementStatementProblem`
243
+ (`agreementOrderProblem` for its `previous`). A `withdrawn` can never name
244
+ an answer.
245
+ - **The evidence bundle.** `buildEvidenceBundle` makes a `btps-evidence/1`
246
+ file (`BTPEvidenceBundle`, JSON Schema `btps-evidence.schema.json`): the
247
+ opened agreement, every statement record in order, and the key behind each
248
+ signature. `verifyEvidenceBundle` checks it offline and reports facts
249
+ (`BTPEvidenceFacts`), never a verdict; `describeEvidenceFacts` prints them,
250
+ as the new `btps-verify-evidence` command does. Providers never reuse a
251
+ selector for a different key, and publish a key rotation record for every
252
+ new key.
253
+ - **Trusted timestamps.** An evidence bundle may carry RFC 3161 tokens, each
254
+ over a statement record's SHA-256 (`timestamps`). `timestampRequest` builds
255
+ the request (only the hash leaves the provider), `timestampTokenOf` reads the
256
+ authority's reply, and `timestampFacts` reports a token's facts;
257
+ `verifyEvidenceBundle` reports each statement's, and whether its authority is
258
+ trusted given `trustedTimestampRoots` (`btps-verify-evidence
259
+ --timestamp-root`). Only a timestamp authority's certificate is trusted: its
260
+ one extended key usage is timeStamping, critical, as RFC 3161 requires
261
+ (`timestampingKeyUsage`), so a TLS server's certificate under a trusted root
262
+ is not. A timestamp never changes `complete`. New dependencies:
263
+ `pkijs` and `asn1js` (BSD-3-Clause), loaded only when a timestamp is used.
264
+ - `meta.delivery` on a sentbox result: a send's outcome by its provider's own
265
+ record, `{ status: 'pending' | 'delivered' | 'failed', code?, at }`
266
+ (`BTPDelivery`).
267
+ - **Device-key theft signals.** With a token store that has the new, optional
268
+ `isConsumed`, a refresh token used a second time, which only a copy of it can
269
+ do, revokes the device and fires `refreshTokenReused`. Without it, a second
270
+ use is refused as in 1.1, and `BtpsAuthentication` warns once.
271
+ `InMemoryTokenStore` has it. `auth.on('keyRotated', …)` tells a listener
272
+ when a device moves to a new key.
273
+ - **A grace window for a retried refresh** (`refreshGraceMs`, default 30 s,
274
+ `0` off). A device that lost a refresh's answer asks again with its old token:
275
+ inside the window it gets the same answer, the same new token included, and
276
+ nothing is revoked; after it, a second use is theft. The answer is kept
277
+ sealed under the old token (AES-256-GCM, key by HKDF-SHA256, bound to the
278
+ device and user), never in plain text, through the new, optional
279
+ `TokenStore.markSuccessor`. A store without it has no window, and
280
+ `BtpsAuthentication` warns once. `InMemoryTokenStore` has it.
281
+ - **A maximum key age** (`maxKeyAgeMs`, off by default): a refresh signed by an
282
+ older device key is refused with `BTP_ERROR_KEY_TOO_OLD`, and the device
283
+ moves to a new key with the same refresh token.
284
+ - **A device reads encrypted documents with its own key.** A query result may
285
+ carry `agentKey: { key, fingerprint, wrappedAt }`: the artifact's content key
286
+ wrapped again to the device that asked, by `wrapForAgent`
287
+ (`@btps/sdk/server`). The artifact is untouched, so its signature still
288
+ verifies. `BtpsAgent.openResult` checks the key is its own, checks who signed
289
+ the artifact as a server does on arrival (a delegation and its attestation
290
+ too), and decrypts. A `Decrypter` gains the optional `unwrapKey`, which
291
+ `PemDecrypter` has, and `decryptVerify` an optional `contentKey`.
292
+ - `verifyTransporterSignature` (`@btps/sdk/server`): who signed a transporter
293
+ artifact, checked as a server checks it on arrival. The server and
294
+ `openResult` share it.
295
+ - **One `keyResolver` option for every key lookup** (`BtpsKeyResolver`), so a
296
+ provider can cache keys; BTPS itself caches nothing. `BtpsServer`,
297
+ `BtpsClient` (and so `BtpsAgent` and `BtpsTransporter`), `BtpsDelegator`
298
+ and `signEncrypt`'s `lookup` take it, and it is asked for a key and what it
299
+ is for, `verify` or `encrypt`. Without it, every lookup is as before.
300
+ `createDefaultKeyResolver` is that lookup, to wrap.
301
+ - `yarn bench`: what a server spends on one arriving artifact, step by step.
302
+ - **A 429 can say how long to wait.** `status.retryAfter`, in a `1.2.0`
303
+ response and on a 429 only, is the whole seconds a sender should wait before
304
+ sending again. A server sends it from an error's `meta.retryAfter`, for its
305
+ own refusals and middleware's `res.sendError` alike; nothing else from
306
+ `meta` reaches the wire, and `cause` never does.
307
+ - **An answer says when it is the connection's last.** `status.closing: true`,
308
+ in a `1.2.0` response, is on every answer after which a server ends the
309
+ connection: a refusal that ends it, `QUIT`, an idle timeout. A `BtpsClient`
310
+ that reads it sends its next artifact on a new connection. Before, the end
311
+ could reach the client after the answer did, and a send written in between
312
+ went to a connection nobody read and failed with
313
+ `BTP_ERROR_CONNECTION_ENDED`. A 1.1 server's answers say nothing, so with
314
+ one the client still only lets in an end that has already arrived, as in
315
+ 1.1.
316
+ - **Key rotation records.** An identity's keys form a key chain: each
317
+ rotation is signed by the old key and the new one (`signKeyRotation`), a
318
+ rotation with immediate expiry marks a compromised or lost key, and an
319
+ expiry record (`signKeyExpiry`) marks a key the identity already left.
320
+ `verifyKeyChain` reports a chain's facts (each key's window, forks,
321
+ anchors, a lost key's authority) and `keyChainProblem` is the refusal a
322
+ verifier applies online. Fingerprints are computed from each key, never
323
+ taken from the record. A `1.2.0` identity lookup may ask for the chain
324
+ (`keyChain: true`); its answer names its identity and carries the chain,
325
+ which an identity store gives with `getKeyChain`. Nothing changes for an
326
+ identity that never rotates. See
327
+ [Key Rotation](https://www.openbtps.org/docs/next/protocol/specifications/key-rotation).
328
+ - **Keys checked against their chain on arrival.** A server asks the
329
+ sender's host for its key chain (the sender's, a delegator's, an
330
+ attestor's) and refuses a key rotated away as planned past
331
+ `retiredKeyGraceSeconds` (default a day) with `BTP_ERROR_KEY_RETIRED`, and
332
+ an expired key at once, whatever the artifact's time, with
333
+ `BTP_ERROR_KEY_REVOKED`, though DNS still has it. A chain is kept for at
334
+ most `keyChainMaxCacheSeconds` (default 300): the longest a revoked key can
335
+ still be taken. A host that cannot be reached, or speaks 1.1, leaves the
336
+ key to DNS, as in 1.1; so a provider removes an expired key's DNS record at
337
+ once. `BtpsClient.lookupKeyChain` asks a host for a chain, with the
338
+ operator's signed `answer` it came in, and a `keyResolver` may give chains
339
+ (`resolveKeyChain`), kept no longer than `keyChainMaxCacheSeconds`.
340
+ `createDefaultKeyResolver` gives them only with `from`; without it, a
341
+ server given it asks for chains itself. A host answers a chain lookup for
342
+ an identity whose keys are in DNS from its chain alone. A host serves the
343
+ chain it stores exactly as stored and never checks it: a stored fork, loop
344
+ or broken record is answered with `200` and the last rotation's new key,
345
+ never as an unknown identity, so the receiver refuses it rather than
346
+ checking the key by DNS alone.
347
+ - **Content-key side-cars.** `wrapContentKeyFor` wraps a stored artifact's
348
+ content key to a new key, checked to open the document, and
349
+ `contentKeyOpens` confirms it; the artifact is never changed, and
350
+ `decryptVerify` opens it with the side-car. A provider deletes an old
351
+ private key once every side-car opens.
352
+ - **Key chains in evidence bundles.** A bundle may keep each signing
353
+ identity's chain, with the operator's signed answer that served it
354
+ (`keyChains`), and when each statement arrived, signed by the builder then
355
+ (`arrivals`, `signArrival`); a key whose DNS record is retired is taken
356
+ from its chain. `verifyEvidenceBundle` reports each signing key against its
357
+ chain (`originatorKeyChain`, each statement's `keyChain`): its window,
358
+ `rotatedAt`, `expiredImmediately`, `authorityUnverified`, and
359
+ `disownedAfterTheFact` when an owner expired its key from before a
360
+ statement that had already arrived. The operator's answer is reported
361
+ (`operatorAnswer`) and confirms a lost key's rotation only by the operator
362
+ of the chain identity's domain: the fingerprint the reader names for that
363
+ domain (`operators`), or, online, the operator DNS names there (`op=`),
364
+ its key confirmed. Its key is otherwise the bundle's own, which a forger
365
+ could have put there. `anchors` are signing-key fingerprints a reader
366
+ kept; `online` confirms each key now, and only then is
367
+ `keysConfirmedOnline` true. `btps-verify-evidence` takes `--anchor`,
368
+ `--operator <domain>=<fingerprint>` and `--online`. None of these changes
369
+ `complete`.
370
+
371
+ ### Changed
372
+
373
+ - A client no longer keeps a copy of an artifact the socket could not send at
374
+ once. It queued one, as though the write had failed, and never sent or freed
375
+ it until the connection ended: on a long-lived connection, every artifact
376
+ past the socket's buffer, about 16 KB, stayed in memory. The socket buffers
377
+ what it cannot send at once, and nothing was ever sent twice.
378
+ `getConnectionStates().isDraining` is always `false`.
379
+ - `decryptVerify` refuses every signature that does not verify. Before, one
380
+ that failed without an error object went on to be decrypted.
381
+ - A refresh never makes a revoked or blocked device accepted again.
382
+ - `keyHistory[].firstSeen` is when the retired key came into use (when the key
383
+ before it was retired, or when the device registered). It was the time of
384
+ the key's last refresh.
385
+ - A receiver's refusal of an artifact's version reaches the sender as a
386
+ `BTP_ERROR_VERSION_UNSUPPORTED` error with `receiverVersion`, the version
387
+ the receiver speaks, beside its answer. `send` now returns both `response`
388
+ and `error` for it, where 1.1 returned the response with no error: a caller
389
+ that checks `error` first now takes that path.
390
+ - A client refuses to send an artifact stamped lower than what it uses, and an
391
+ agent artifact stamped lower than the artifact it carries.
392
+ - An answer a provider builds in a shape no answer allows reaches its sender
393
+ as a generic `btps_error` against its request's `reqId`, and the connection
394
+ stays open. It was closed without an answer, which a device saw only as
395
+ "Connection closed". The server still reports it to `onError`.
396
+ - A server whose implementor takes errors, through the `onError` option or
397
+ `onError` middleware, no longer also writes each failed artifact to
398
+ `console.error`. With neither, it writes as before.
399
+ - An identity lookup goes out as `1.2.0`, and again as `1.1.0` when a 1.1
400
+ host refuses the version. Its answer is refused unless it answers this
401
+ lookup (`reqId`), is fresh (`issuedAt` within 300 seconds), and names the
402
+ identity asked about; a 1.1 answer carries none of these. A host that does
403
+ not answer is given up on after the client's reply timeout.
404
+
405
+ ### Fixed
406
+
407
+ - A change to an active trust (`TRUST_REQ` with `change: true`) reaches its
408
+ receiver. The server refused every trust request on an active trust, a
409
+ change too, so permissions could never be added or removed later. It now
410
+ takes a change while the receiver's record of the trust is active and has
411
+ no change pending, and refuses anything else as before. The receiving
412
+ platform saves the change as `pendingChange` until its user answers.
413
+ - A refresh that races another with the same token is told to try again
414
+ (`BTP_ERROR_TEMPORARILY_UNAVAILABLE`) instead of revoking the device; a
415
+ token store records `consumedAt` on the consumed mark.
416
+ - An evidence bundle's facts name the key each signature was checked with,
417
+ and say the keys are the bundle's own, not confirmed online
418
+ (`keysConfirmedOnline: false`).
419
+ - A client acts on `status.closing` only in an answer it takes, signed as
420
+ `requireSignedBy` requires.
421
+
422
+ ### Security
423
+
424
+ - A server checks each line against the schema of the kind of artifact it is
425
+ taken for, and control and identity lookup artifacts take no other member
426
+ (also in 1.1.3).
427
+ - Every list 1.2 adds to an artifact is refused when too long before its
428
+ entries are read.
429
+ - A server with `signAnswers` signs no more answers than a connection has
430
+ lines in flight, and ends a connection after `maxConsecutiveInvalidLines`
431
+ unreadable lines in a row (default 10).
432
+ - `BtpsAuthentication` errors carry no refresh token or registration code.
433
+ - An error thrown, or passed on as caught, reaches the sender only as a BTPS
434
+ constant, else as the generic 500; a platform's own plain answer sent with
435
+ `res.sendError` goes as given.
436
+
437
+ ### Upgrading from 1.1
438
+
439
+ A 1.1 provider upgrades without changing what it sends: a 1.2 server and
440
+ client take 1.1 artifacts and talk to 1.1 providers, and a trust record
441
+ without `permissions` is a 1.1 trust, checked as 1.1 checks it. In short:
442
+
443
+ - **Answers a caller now handles:** `send`'s `error` beside the `response`
444
+ when the receiver refuses the artifact's version; `decryptVerify` refusing
445
+ every signature that does not verify; no `console.error` beside `onError`;
446
+ `getConnectionStates().isDraining` always `false`.
447
+ - **The token store** may add `isConsumed` and `markSuccessor`, and record
448
+ `consumedAt`, to revoke a device whose refresh token is used twice.
449
+ - **The trust store** has no new method; `isKnownArtifact` is also asked
450
+ about the `DETAILS_REQ` a `DETAILS_RES` answers. A record may carry
451
+ `permissions`, which the platform writes.
452
+ - **The refusals for what 1.2 adds** (`eventChainCheck`,
453
+ `detailsResponseCheck`, `agreementOrderCheck`, `detailsRequestLimit`) are
454
+ middleware the platform registers, from `@btps/sdk/server/core`.
455
+ - **Arriving keys are checked against their identity's key chain:** a key
456
+ rotated away past `retiredKeyGraceSeconds` (a day) is refused, an expired
457
+ one at once. A chain is kept for at most `keyChainMaxCacheSeconds` (300
458
+ seconds), and a `keyResolver` that gives chains keeps each no longer. A
459
+ key whose identity never rotated is checked by DNS, as in 1.1.
460
+ - **Rotating a key** is a signed record the identity store keeps
461
+ (`keyChain`, `getKeyChain`), with the provider's rules: remove an expired
462
+ key's DNS record at once, re-publish unchanged keys under a new `s=`, and
463
+ delete an old private key only once its side-cars open.
464
+
465
+ The steps, in a safe order with rollback at each, the code, and the order to
466
+ adopt each feature in: [Migrating from 1.1 to 1.2](https://www.openbtps.org/docs/next/whats-new/1-2/migration).
467
+
7
468
  ## [1.1.3] — 2026-10-30 (alpha)
8
469
 
9
470
  A patch release. Every document a compliant sender sent before is still
@@ -0,0 +1,96 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * @license
4
+ * Copyright (c) 2025 Bhupendra Tamang
5
+ * Licensed under the Apache License, Version 2.0
6
+ * https://www.apache.org/licenses/LICENSE-2.0
7
+ */
8
+
9
+ /**
10
+ * btps-verify-evidence: check a BTPS agreement's evidence bundle offline, with
11
+ * no provider and no network, and print what it shows. It reports facts,
12
+ * never a verdict. The keys are the bundle's own, not confirmed online: it
13
+ * prints each one's fingerprint for a reader to check.
14
+ *
15
+ * npx -p @btps/sdk btps-verify-evidence <bundle.json> [--json] [--timestamp-root <ca.pem>]...
16
+ * [--anchor <fingerprint>]... [--operator <domain>=<fingerprint>]... [--online <your-identity>]
17
+ *
18
+ * --json print the facts as JSON instead of text
19
+ * --timestamp-root <file> a PEM certificate whose timestamps you trust; repeat for more
20
+ * --anchor <fingerprint> since 1.2: a signing key's fingerprint you kept, as an
21
+ * identity's key when you saw it; repeat for more
22
+ * --operator <domain>=<fp> since 1.2: the fingerprint you kept of a domain's operator's
23
+ * key; only it confirms an operator's answer in the bundle for an
24
+ * identity at that domain, offline; repeat for more domains
25
+ * --online <identity> since 1.2: also confirm each key now as its identity's: a key
26
+ * of its identity's chain from its host (asked as this identity),
27
+ * anchored on DNS, or its DNS key. Only this confirms keys online
28
+ *
29
+ * Exit codes: 0 the agreement is complete, 1 it is not (see the facts),
30
+ * 2 the file could not be read or is not an evidence bundle. A timestamp, a
31
+ * key chain fact and an online check are reported and never change the exit code.
32
+ */
33
+
34
+ import fs from 'node:fs';
35
+ import { describeEvidenceFacts, verifyEvidenceBundle } from '@btps/sdk/trust';
36
+ import { createDefaultKeyResolver } from '@btps/sdk/crypto';
37
+
38
+ const USAGE =
39
+ 'usage: btps-verify-evidence <bundle.json> [--json] [--timestamp-root <ca.pem>]... [--anchor <fingerprint>]... [--operator <domain>=<fingerprint>]... [--online <your-identity>]';
40
+
41
+ const args = process.argv.slice(2);
42
+ const roots = [];
43
+ const anchors = [];
44
+ const operators = {};
45
+ let badOperator = false;
46
+ let asking;
47
+ const rest = [];
48
+ for (let i = 0; i < args.length; i++) {
49
+ if (args[i] === '--timestamp-root') roots.push(args[++i]);
50
+ else if (args[i] === '--anchor') anchors.push(args[++i]);
51
+ else if (args[i] === '--operator') {
52
+ // A fingerprint is base64 and may end in '=': split at the first '=' only.
53
+ const [domain, fingerprint] = (args[++i] ?? '').split(/=(.*)/s);
54
+ if (domain && fingerprint) operators[domain] = fingerprint;
55
+ else badOperator = true;
56
+ } else if (args[i] === '--online') asking = args[++i] ?? '';
57
+ else rest.push(args[i]);
58
+ }
59
+ const file = rest.find((arg) => !arg.startsWith('--'));
60
+ if (
61
+ !file ||
62
+ roots.includes(undefined) ||
63
+ anchors.includes(undefined) ||
64
+ badOperator ||
65
+ asking === ''
66
+ ) {
67
+ console.error(USAGE);
68
+ process.exit(2);
69
+ }
70
+
71
+ let facts;
72
+ try {
73
+ const bundle = JSON.parse(fs.readFileSync(file, 'utf8'));
74
+ const trustedTimestampRoots = roots.map((root) => fs.readFileSync(root, 'utf8'));
75
+ const resolver = asking && createDefaultKeyResolver({ from: asking });
76
+ facts = await verifyEvidenceBundle(bundle, {
77
+ ...(roots.length && { trustedTimestampRoots }),
78
+ ...(anchors.length && { anchors }),
79
+ ...(Object.keys(operators).length && { operators }),
80
+ ...(resolver && {
81
+ online: {
82
+ resolveKeyChain: (identity) => resolver.resolveKeyChain(identity),
83
+ // A bundle's signatures are past: no live grace applies, only the chain's facts.
84
+ retiredKeyGraceSeconds: 0,
85
+ },
86
+ }),
87
+ });
88
+ } catch (error) {
89
+ const cause = error?.cause ? `: ${error.cause}` : '';
90
+ console.error(`${file}: ${error?.message ?? error}${cause}`);
91
+ process.exit(2);
92
+ }
93
+ console.log(
94
+ args.includes('--json') ? JSON.stringify(facts, null, 2) : describeEvidenceFacts(facts),
95
+ );
96
+ process.exit(facts.complete ? 0 : 1);
@@ -6,7 +6,7 @@
6
6
  */
7
7
  import { BtpsClient } from './btpsClient.js';
8
8
  import type { BTPAgentOptions, BTPClientResponse, BtpsAgentCommandOptions, BtpsAgentCommandParams, BtpsAgentDoc } from './types/index.js';
9
- import type { BTPDocType, AgentAction } from '../server/index.js';
9
+ import type { BTPDocType, AgentAction, BTPQueryResultEntry } from '../server/index.js';
10
10
  import type { BTPCryptoResponse } from '../core/crypto/types.js';
11
11
  export declare class BtpsAgent extends BtpsClient {
12
12
  private agentId;
@@ -16,5 +16,14 @@ export declare class BtpsAgent extends BtpsClient {
16
16
  protected getAgentArtifact(commandParams: BtpsAgentCommandParams): Promise<BTPCryptoResponse<BTPDocType>>;
17
17
  protected buildTransportArtifact(commandParams: BtpsAgentCommandParams): Promise<BTPCryptoResponse<BTPDocType>>;
18
18
  command(actionType: AgentAction, identity: string, document?: BtpsAgentDoc, options?: BtpsAgentCommandOptions, timeoutMs?: number): Promise<BTPClientResponse>;
19
+ /**
20
+ * Since 1.2: opens an encrypted query result with this device's own key,
21
+ * through the `agentKey` its provider wrapped for it. Who signed it is checked
22
+ * as a server checks it on arrival (a delegation and its attestation too), and
23
+ * the document as any decrypted one is.
24
+ * @param entry - A query result entry with `agentKey`
25
+ * @returns The artifact with its document decrypted, or the reason it could not be opened
26
+ */
27
+ openResult(entry: BTPQueryResultEntry): Promise<BTPCryptoResponse<BTPDocType | string>>;
19
28
  destroy(soft?: boolean): void;
20
29
  }