@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.
- package/CHANGELOG.md +461 -0
- package/bin/verify-evidence-bundle.mjs +96 -0
- package/dist/client/btpsAgent.d.ts +10 -1
- package/dist/client/btpsAgent.js +116 -18
- package/dist/client/btpsClient.d.ts +53 -7
- package/dist/client/btpsClient.js +265 -147
- package/dist/client/index.d.ts +1 -1
- package/dist/client/index.js +3 -1
- package/dist/client/libs/schema.js +78 -13
- package/dist/client/libs/timeouts.d.ts +6 -0
- package/dist/client/libs/timeouts.js +2 -1
- package/dist/client/types/index.d.ts +54 -2
- package/dist/core/authentication/BtpsAuthentication.d.ts +43 -1
- package/dist/core/authentication/BtpsAuthentication.js +152 -36
- package/dist/core/authentication/refreshSuccessor.js +47 -0
- package/dist/core/authentication/storage/InMemoryTokenStore.d.ts +17 -1
- package/dist/core/authentication/storage/InMemoryTokenStore.js +16 -4
- package/dist/core/authentication/types.d.ts +82 -0
- package/dist/core/crypto/contentKey.d.ts +34 -0
- package/dist/core/crypto/contentKey.js +64 -0
- package/dist/core/crypto/decryptVerify.d.ts +7 -1
- package/dist/core/crypto/decryptVerify.js +23 -5
- package/dist/core/crypto/decrypter-interface.d.ts +6 -0
- package/dist/core/crypto/index.d.ts +12 -0
- package/dist/core/crypto/index.js +7 -1
- package/dist/core/crypto/keyResolver.d.ts +48 -0
- package/dist/core/crypto/keyResolver.js +46 -0
- package/dist/core/crypto/pem-decrypter.d.ts +2 -0
- package/dist/core/crypto/pem-decrypter.js +13 -8
- package/dist/core/crypto/signEncrypt.d.ts +4 -1
- package/dist/core/crypto/signEncrypt.js +20 -5
- package/dist/core/crypto/types.d.ts +8 -1
- package/dist/core/delegation/BtpsDelegator.d.ts +4 -0
- package/dist/core/delegation/BtpsDelegator.js +3 -2
- package/dist/core/delegation/verifyTransporterSignature.d.ts +104 -0
- package/dist/core/delegation/verifyTransporterSignature.js +224 -0
- package/dist/core/error/constant.d.ts +39 -0
- package/dist/core/error/constant.js +55 -0
- package/dist/core/server/constants/btps-protocol.d.ts +21 -5
- package/dist/core/server/constants/btps-protocol.js +46 -8
- package/dist/core/server/constants/index.d.ts +7 -3
- package/dist/core/server/constants/index.js +19 -4
- package/dist/core/server/constants/limits.d.ts +18 -0
- package/dist/core/server/constants/limits.js +19 -1
- package/dist/core/server/constants/permissions.d.ts +38 -0
- package/dist/core/server/constants/permissions.js +38 -0
- package/dist/core/server/schemas/artifacts/agentSchema.js +2 -1
- package/dist/core/server/schemas/artifacts/artifacts.js +7 -1
- package/dist/core/server/schemas/artifacts/controlSchema.js +1 -1
- package/dist/core/server/schemas/artifacts/identityLookupSchema.js +10 -1
- package/dist/core/server/schemas/artifacts/transporterSchema.js +99 -12
- package/dist/core/server/schemas/bounded.js +2 -2
- package/dist/core/server/schemas/btpsDocsSchema.d.ts +36009 -1083
- package/dist/core/server/schemas/btpsDocsSchema.js +305 -42
- package/dist/core/server/schemas/helpers.d.ts +10090 -0
- package/dist/core/server/schemas/helpers.js +76 -12
- package/dist/core/server/schemas/keyChainSchema.js +53 -0
- package/dist/core/server/schemas/responseSchema.js +52 -9
- package/dist/core/server/schemas/schema.js +3 -1
- package/dist/core/server/schemas/trustValues.d.ts +105 -0
- package/dist/core/server/schemas/trustValues.js +117 -0
- package/dist/core/server/types.d.ts +104 -6
- package/dist/core/storage/AbstractIdentityStore.d.ts +9 -0
- package/dist/core/storage/JsonIdentityStore.d.ts +3 -0
- package/dist/core/storage/JsonIdentityStore.js +3 -0
- package/dist/core/storage/types.d.ts +2 -0
- package/dist/core/trust/agreements.d.ts +107 -0
- package/dist/core/trust/agreements.js +116 -0
- package/dist/core/trust/evidence.d.ts +220 -0
- package/dist/core/trust/evidence.js +334 -0
- package/dist/core/trust/index.d.ts +10 -0
- package/dist/core/trust/index.js +14 -1
- package/dist/core/trust/keyRotation.d.ts +148 -0
- package/dist/core/trust/keyRotation.js +267 -0
- package/dist/core/trust/permissions.d.ts +114 -0
- package/dist/core/trust/permissions.js +115 -0
- package/dist/core/trust/shaping.d.ts +42 -0
- package/dist/core/trust/shaping.js +47 -0
- package/dist/core/trust/storage/AbstractTrustStore.d.ts +2 -1
- package/dist/core/trust/storage/JsonTrustStore.d.ts +3 -2
- package/dist/core/trust/timestamps.d.ts +49 -0
- package/dist/core/trust/timestamps.js +78 -0
- package/dist/core/trust/trustUtils.d.ts +13 -2
- package/dist/core/trust/trustUtils.js +28 -3
- package/dist/core/trust/types.d.ts +312 -2
- package/dist/core/trust/verification.d.ts +52 -0
- package/dist/core/trust/verification.js +55 -0
- package/dist/server/btpsServer.d.ts +79 -5
- package/dist/server/btpsServer.js +297 -145
- package/dist/server/index.d.ts +3 -0
- package/dist/server/index.js +17 -1
- package/dist/server/libs/agreementOrderCheck.d.ts +29 -0
- package/dist/server/libs/agreementOrderCheck.js +29 -0
- package/dist/server/libs/artifactTimeWindow.d.ts +2 -2
- package/dist/server/libs/artifactTimeWindow.js +2 -1
- package/dist/server/libs/detailsRequestLimit.d.ts +27 -0
- package/dist/server/libs/detailsRequestLimit.js +28 -0
- package/dist/server/libs/detailsResponseCheck.d.ts +27 -0
- package/dist/server/libs/detailsResponseCheck.js +27 -0
- package/dist/server/libs/eventChainCheck.d.ts +31 -0
- package/dist/server/libs/eventChainCheck.js +39 -0
- package/dist/server/libs/inFlightLimit.d.ts +10 -0
- package/dist/server/libs/inFlightLimit.js +7 -1
- package/dist/server/libs/index.d.ts +5 -0
- package/dist/server/libs/index.js +10 -0
- package/dist/server/libs/keyChains.d.ts +14 -0
- package/dist/server/libs/keyChains.js +17 -0
- package/dist/server/libs/wrapForAgent.d.ts +20 -0
- package/dist/server/libs/wrapForAgent.js +36 -0
- package/dist/server/types.d.ts +103 -9
- 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
|
}
|