@btps/sdk 1.1.3 → 1.2.0-rc.1

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 +422 -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 +92 -12
  52. package/dist/core/server/schemas/bounded.js +2 -2
  53. package/dist/core/server/schemas/btpsDocsSchema.d.ts +34185 -1084
  54. package/dist/core/server/schemas/btpsDocsSchema.js +300 -42
  55. package/dist/core/server/schemas/helpers.d.ts +9580 -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 +302 -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 +70 -5
  89. package/dist/server/btpsServer.js +263 -143
  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 +95 -9
  111. package/package.json +12 -3
@@ -0,0 +1,334 @@
1
+ /**
2
+ * @license
3
+ * Copyright (c) 2025 Bhupendra Tamang
4
+ * Licensed under the Apache License, Version 2.0
5
+ * https://www.apache.org/licenses/LICENSE-2.0
6
+ */
7
+
8
+ import crypto from "crypto";
9
+ import {
10
+ getFingerprintFromPem,
11
+ signBtpPayload,
12
+ signBtpPayloadWithSigner,
13
+ verifySignature
14
+ } from "../crypto/index.js";
15
+ import { canonicalizeValue } from "../crypto/jcs.js";
16
+ import { BTPErrorException } from "../error/index.js";
17
+ import { BTP_ERROR_RESOLVE_PUBKEY, BTP_ERROR_VALIDATION } from "../error/constant.js";
18
+ import { BtpEvidenceBundleSchema } from "../server/schemas/btpsDocsSchema.js";
19
+ import { sameIdentity } from "../server/schemas/helpers.js";
20
+ import { getHostAndSelector, parseIdentity } from "../utils/index.js";
21
+ import {
22
+ onlineKeyChain,
23
+ signatureKey
24
+ } from "../delegation/verifyTransporterSignature.js";
25
+ import { checkKeyChain, keyAt, keyChainFactsOf } from "./keyRotation.js";
26
+ import {
27
+ agreementContentSha256,
28
+ agreementOrderProblem,
29
+ agreementRef,
30
+ originatorSignatureValid,
31
+ statementRecordSha256,
32
+ statementSignatureFacts
33
+ } from "./agreements.js";
34
+ import { timestampFacts } from "./timestamps.js";
35
+ const bundleKey = (keyOf, identity, selector) => {
36
+ const fingerprint = fingerprintOf(keyOf(identity, selector));
37
+ return { identity, selector, ...fingerprint && { fingerprint } };
38
+ }, fingerprintOf = (publicKey) => {
39
+ if (publicKey)
40
+ try {
41
+ return getFingerprintFromPem(publicKey);
42
+ } catch {
43
+ return;
44
+ }
45
+ }, statementKeys = (record, keyOf) => {
46
+ const { signer } = record.statement;
47
+ if (!record.delegatedArtifact) return { key: bundleKey(keyOf, signer, record.selector) };
48
+ const { delegation } = record.delegatedArtifact, fingerprint = fingerprintOf(delegation.agentPubKey);
49
+ return {
50
+ key: { identity: signer, ...fingerprint && { fingerprint } },
51
+ delegationKey: bundleKey(keyOf, delegation.signedBy, delegation.selector)
52
+ };
53
+ }, sha256Hex = (bytes) => crypto.createHash("sha256").update(bytes).digest("hex"), keysOf = (bundle) => {
54
+ const keys = bundle.keys.filter((key) => {
55
+ try {
56
+ return getFingerprintFromPem(key.publicKey) === key.fingerprint;
57
+ } catch {
58
+ return !1;
59
+ }
60
+ });
61
+ return (identity, selector) => keys.find((key) => sameIdentity(key.identity, identity) && key.selector === selector)?.publicKey;
62
+ }, arrivalSigned = (arrival) => ({
63
+ type: "btps.arrival.v1",
64
+ ...arrival
65
+ }), signArrival = async (arrival, holder) => {
66
+ const signed = arrivalSigned(arrival), signature = "signer" in holder ? await signBtpPayloadWithSigner(signed, holder.signer) : signBtpPayload(signed, holder.pemFiles);
67
+ return { ...arrival, signature };
68
+ }, inWindow = (key, time) => {
69
+ const at = Date.parse(time);
70
+ return (key.validFrom === void 0 || at >= Date.parse(key.validFrom)) && (key.validUntil === void 0 || at < Date.parse(key.validUntil)) && (key.compromisedSince === void 0 || at < Date.parse(key.compromisedSince));
71
+ }, operatorAnswerFacts = (chain, context) => {
72
+ const answer = chain.operatorAnswer;
73
+ if (!answer?.signedBy) return;
74
+ const { signature, ...signed } = answer, key = answer.selector ? context.keyOf(answer.signedBy, answer.selector) : void 0, fingerprint = fingerprintOf(key), document = answer.document, domain = parseIdentity(chain.identity)?.domainName.toLowerCase(), named = Object.entries(context.operators ?? {}).find(
75
+ ([operatorOf]) => operatorOf.toLowerCase() === domain
76
+ )?.[1];
77
+ return {
78
+ signedBy: answer.signedBy,
79
+ signatureValid: !!key && !!signature && verifySignature(signed, signature, key).isValid,
80
+ answersThisChain: document?.identity !== void 0 && sameIdentity(document.identity, chain.identity) && canonicalizeValue(document.keyChain) === canonicalizeValue(chain.records),
81
+ operatorKeyAnchored: fingerprint !== void 0 && (fingerprint === named || context.keyConfirmedOnline)
82
+ };
83
+ }, keyChainFactsFor = (chain, fingerprint, times, context) => {
84
+ const facts = keyChainFactsOf(checkKeyChain(chain.records, chain.identity), {
85
+ anchors: context.anchors
86
+ }), key = fingerprint === void 0 ? void 0 : keyAt(facts, { fingerprint }), { online } = context, anchored = online?.anchored && fingerprint !== void 0 && keyAt(online, { fingerprint }) ? online.anchored : facts.anchored, { timestamped, independent } = times, expiredAt = key?.expiredAt, operatorAnswer = operatorAnswerFacts(chain, {
87
+ operators: context.operators,
88
+ keyOf: context.keyOf,
89
+ keyConfirmedOnline: context.operatorKeyConfirmedOnline
90
+ }), answerConfirms = !!operatorAnswer && operatorAnswer.signatureValid && operatorAnswer.answersThisChain && operatorAnswer.operatorKeyAnchored;
91
+ return {
92
+ chainValid: facts.chainValid,
93
+ ...facts.problem !== void 0 && { problem: facts.problem },
94
+ keyInChain: key !== void 0,
95
+ authorityUnverified: facts.authorityUnverified && (anchored === !1 || anchored.by !== "online") && !answerConfirms,
96
+ ...operatorAnswer && { operatorAnswer },
97
+ forked: facts.forked,
98
+ ...facts.keys.length > 0 && { reachesKey: facts.keys.at(-1)?.fingerprint },
99
+ anchored,
100
+ ...key?.validUntil !== void 0 && { rotatedAt: key.validUntil },
101
+ ...key?.compromisedSince !== void 0 && expiredAt !== void 0 && key.reason !== void 0 && {
102
+ expiredImmediately: {
103
+ at: expiredAt,
104
+ compromisedSince: key.compromisedSince,
105
+ reason: key.reason
106
+ }
107
+ },
108
+ signedInWindow: key !== void 0 && inWindow(key, times.claimed),
109
+ ...timestamped !== void 0 && {
110
+ signedInWindowIndependently: key !== void 0 && inWindow(key, timestamped)
111
+ },
112
+ ...key?.compromisedSince !== void 0 && expiredAt !== void 0 && independent !== void 0 && {
113
+ disownedAfterTheFact: Date.parse(independent) < Date.parse(expiredAt) && Date.parse(independent) >= Date.parse(key.compromisedSince)
114
+ }
115
+ };
116
+ }, verifyEvidenceBundle = async (bundle, options = {}) => {
117
+ const parsed = BtpEvidenceBundleSchema.safeParse(bundle);
118
+ if (!parsed.success)
119
+ throw new BTPErrorException(BTP_ERROR_VALIDATION, {
120
+ cause: `not an evidence bundle: ${parsed.error.issues.map((issue) => issue.message).join("; ")}`
121
+ });
122
+ const { originator, agreement } = parsed.data, statements = parsed.data.statements, keyOf = keysOf(parsed.data), { by, terms, signers, signingOrder } = agreement.acceptance, ref = agreementRef(agreement, originator), termsAttached = terms.every(
123
+ (term) => agreement.attachments?.some(
124
+ ({ sha256, content }) => sha256 === term && sha256Hex(Buffer.from(content, "base64")) === term
125
+ )
126
+ ), answered = [], statementFacts = statements.map((record) => {
127
+ const { statement } = record, { agreement: named } = statement, facts = {
128
+ signer: statement.signer,
129
+ decision: statement.decision,
130
+ ...statementSignatureFacts(record, keyOf),
131
+ ...statementKeys(record, keyOf),
132
+ agreementMatches: sameIdentity(named.originator, ref.originator) && named.id === ref.id && named.contentSha256 === ref.contentSha256,
133
+ termsMatch: statement.terms.length === terms.length && statement.terms.every((t, i) => t === terms[i]),
134
+ withinDeadline: by === void 0 || Date.parse(statement.signedAt) <= Date.parse(by),
135
+ inOrder: agreementOrderProblem(
136
+ { from: statement.signer, previous: statement.previous },
137
+ { signers: signers.map(({ address }) => address), signingOrder, answered }
138
+ ) === void 0
139
+ };
140
+ return answered.push({
141
+ signer: statement.signer,
142
+ decision: statement.decision,
143
+ sha256: statementRecordSha256(record)
144
+ }), facts;
145
+ }), timestamped = await Promise.all(
146
+ statementFacts.map(async (facts, i) => {
147
+ const sha256 = answered[i]?.sha256 ?? "", token = parsed.data.timestamps?.find((t) => t.statementSha256 === sha256)?.token;
148
+ if (token === void 0) return facts;
149
+ const trustedRoots = options.trustedTimestampRoots;
150
+ return { ...facts, timestamp: await timestampFacts(token, sha256, { trustedRoots }) };
151
+ })
152
+ ), signing = [
153
+ [originator, agreement.originatorSignature.selector],
154
+ ...timestamped.flatMap((s, i) => {
155
+ const used = s.delegationKey ?? s.key, attestation = statements[i]?.delegatedArtifact?.delegation.attestation;
156
+ return [
157
+ [used.identity, used.selector, used.fingerprint],
158
+ ...attestation ? [[attestation.signedBy, attestation.selector]] : []
159
+ ];
160
+ })
161
+ ], onlineChains = /* @__PURE__ */ new Map(), confirmedOnline = async (check, [identity, selector, fingerprint]) => {
162
+ const id = identity.toLowerCase();
163
+ onlineChains.has(id) || onlineChains.set(id, await onlineKeyChain(identity, check));
164
+ const online = onlineChains.get(id), used = fingerprint ?? fingerprintOf(selector && keyOf(identity, selector));
165
+ if (used === void 0) return !1;
166
+ if (online.status === "checked")
167
+ return keyAt(online.facts, { fingerprint: used }) !== void 0;
168
+ if (online.status === "none" && selector !== void 0) {
169
+ const inDns = await signatureKey(identity, selector).catch(() => {
170
+ });
171
+ return fingerprintOf(inDns) === used;
172
+ }
173
+ return !1;
174
+ };
175
+ let confirmed = options.online !== void 0;
176
+ if (options.online)
177
+ for (const key of signing) {
178
+ const holds = await confirmedOnline(options.online, key);
179
+ confirmed &&= holds;
180
+ }
181
+ const keyChains = parsed.data.keyChains ?? [], chainOf = (identity) => keyChains.find((c) => sameIdentity(c.identity, identity)), operatorKeysOnline = new Map();
182
+ if (options.online)
183
+ for (const chain of keyChains) {
184
+ const { signedBy, selector } = chain.operatorAnswer ?? {};
185
+ if (!signedBy || !selector) continue;
186
+ const operator = (await getHostAndSelector(chain.identity).catch(() => {
187
+ }))?.operator;
188
+ operatorKeysOnline.set(
189
+ chain,
190
+ operator !== void 0 && sameIdentity(operator, signedBy) && await confirmedOnline(options.online, [signedBy, selector])
191
+ );
192
+ }
193
+ const onlineFactsOf = (identity) => {
194
+ const online = onlineChains.get(identity.toLowerCase());
195
+ return online?.status === "checked" ? online.facts : void 0;
196
+ }, chainFacts = (identity, fingerprint, times) => {
197
+ const chain = chainOf(identity);
198
+ if (chain)
199
+ return keyChainFactsFor(chain, fingerprint, times, {
200
+ anchors: options.anchors,
201
+ operators: options.operators,
202
+ online: onlineFactsOf(identity),
203
+ keyOf,
204
+ operatorKeyConfirmedOnline: operatorKeysOnline.get(chain) ?? !1
205
+ });
206
+ }, arrivals = new Map(
207
+ (parsed.data.arrivals ?? []).map((arrival) => {
208
+ const { signature, ...unsigned } = arrival, key = keyOf(arrival.receivedBy, arrival.selector), signatureValid = !!key && verifySignature(arrivalSigned(unsigned), signature, key).isValid;
209
+ return [
210
+ arrival.statementSha256,
211
+ { at: arrival.arrivedAt, receivedBy: arrival.receivedBy, signatureValid }
212
+ ];
213
+ })
214
+ ), withChains = timestamped.map((facts, i) => {
215
+ const arrival = arrivals.get(answered[i]?.sha256 ?? ""), stamp = facts.timestamp, timestampedAt = stamp?.trusted && stamp.imprintMatches && stamp.signatureValid ? stamp.time : void 0, used = facts.delegationKey ?? facts.key, keyChain = chainFacts(used.identity, used.fingerprint, {
216
+ claimed: statements[i]?.statement.signedAt ?? "",
217
+ timestamped: timestampedAt,
218
+ independent: timestampedAt ?? (arrival?.signatureValid ? arrival.at : void 0)
219
+ });
220
+ return { ...facts, ...arrival && { arrival }, ...keyChain && { keyChain } };
221
+ }), originatorValid = originatorSignatureValid(agreement, originator, keyOf), originatorKey = bundleKey(keyOf, originator, agreement.originatorSignature.selector), originatorKeyChain = chainFacts(originator, originatorKey.fingerprint, {
222
+ claimed: agreement.issuedAt
223
+ }), complete = originatorValid && termsAttached && statementFacts.length === signers.length && statementFacts.every(
224
+ (fact) => fact.decision === "accepted" && fact.signatureValid && fact.agreementMatches && fact.termsMatch && fact.withinDeadline && fact.inOrder
225
+ );
226
+ return {
227
+ contentSha256: agreementContentSha256(agreement),
228
+ originatorSignatureValid: originatorValid,
229
+ originatorKey,
230
+ ...originatorKeyChain && { originatorKeyChain },
231
+ keysConfirmedOnline: confirmed,
232
+ termsAttached,
233
+ statements: withChains,
234
+ complete
235
+ };
236
+ }, buildEvidenceBundle = (parts, keyOf) => {
237
+ const { originator, agreement, statements, keyChains, arrivals } = parts, needed = [[originator, agreement.originatorSignature.selector]];
238
+ for (const record of statements) {
239
+ if (record.selector !== void 0) {
240
+ needed.push([record.statement.signer, record.selector]);
241
+ continue;
242
+ }
243
+ const { delegation } = record.delegatedArtifact;
244
+ needed.push([delegation.signedBy, delegation.selector]), delegation.attestation && needed.push([delegation.attestation.signedBy, delegation.attestation.selector]);
245
+ }
246
+ for (const chain of keyChains ?? []) {
247
+ const answer = chain.operatorAnswer;
248
+ answer?.signedBy && answer.selector && needed.push([answer.signedBy, answer.selector]);
249
+ }
250
+ for (const arrival of arrivals ?? []) needed.push([arrival.receivedBy, arrival.selector]);
251
+ const chainKeyOf = (identity, selector) => {
252
+ const chain = keyChains?.find((c) => sameIdentity(c.identity, identity));
253
+ if (!chain) return;
254
+ const facts = keyChainFactsOf(checkKeyChain(chain.records, chain.identity), {});
255
+ return keyAt(facts, { selector })?.publicKey;
256
+ }, keys = [];
257
+ for (const [identity, selector] of needed) {
258
+ if (keys.some((key) => sameIdentity(key.identity, identity) && key.selector === selector))
259
+ continue;
260
+ const publicKey = keyOf(identity, selector) ?? chainKeyOf(identity, selector);
261
+ if (publicKey === void 0)
262
+ throw new BTPErrorException(BTP_ERROR_RESOLVE_PUBKEY, {
263
+ cause: `no key for ${identity} at ${selector}`
264
+ });
265
+ keys.push({ identity, selector, publicKey, fingerprint: getFingerprintFromPem(publicKey) });
266
+ }
267
+ return {
268
+ format: "btps-evidence/1",
269
+ originator,
270
+ agreement,
271
+ statements,
272
+ keys,
273
+ ...keyChains?.length && { keyChains },
274
+ ...arrivals?.length && { arrivals }
275
+ };
276
+ }, describeEvidenceFacts = (facts) => {
277
+ const mark = (fact) => fact ? "yes" : "NO", line = (label, value) => `${label.padEnd(27)}${value}`, keyText = ({ identity, selector, fingerprint }) => `${identity}${selector ? ` at ${selector}` : ""}, fingerprint ${fingerprint ?? "none in the bundle"}`, chainText = (c, indent) => {
278
+ const anchored = c.anchored ? `${c.anchored.by}, up to ${c.anchored.upTo}` : "NO", independently = c.signedInWindowIndependently === void 0 ? "" : `, by its timestamp ${mark(c.signedInWindowIndependently)}`;
279
+ return [
280
+ `${indent}key chain valid ${mark(c.chainValid)}${c.problem ? ` (${c.problem})` : ""}, key in it ${mark(c.keyInChain)}, forked ${c.forked ? "YES" : "no"}`,
281
+ `${indent} anchored ${anchored}${c.authorityUnverified ? ", a lost key's rotation unconfirmed" : ""}`,
282
+ ...c.operatorAnswer ? [
283
+ `${indent} operator's answer by ${c.operatorAnswer.signedBy}: signed ${mark(c.operatorAnswer.signatureValid)}, this chain ${mark(c.operatorAnswer.answersThisChain)}, its key anchored ${mark(c.operatorAnswer.operatorKeyAnchored)}`
284
+ ] : [],
285
+ `${indent} signed while the key was its ${mark(c.signedInWindow)}${independently}`,
286
+ ...c.rotatedAt ? [`${indent} rotated away ${c.rotatedAt}`] : [],
287
+ ...c.expiredImmediately ? [
288
+ `${indent} EXPIRED ${c.expiredImmediately.at} (${c.expiredImmediately.reason}), compromised since ${c.expiredImmediately.compromisedSince}`
289
+ ] : [],
290
+ ...c.disownedAfterTheFact ? [`${indent} DISOWNED after the fact: it arrived before the expiry was declared`] : []
291
+ ];
292
+ }, lines = [
293
+ line("content sha256", facts.contentSha256),
294
+ line("originator's signature", mark(facts.originatorSignatureValid)),
295
+ line("originator's key", keyText(facts.originatorKey)),
296
+ ...facts.originatorKeyChain ? chainText(facts.originatorKeyChain, "") : [],
297
+ line("terms are its attachments", mark(facts.termsAttached))
298
+ ];
299
+ return facts.statements.forEach((s, i) => {
300
+ const key = s.keyKind === "device" ? `device, delegated by ${s.delegatedBy}` : "identity", attested = s.attestedBy ? `, attested by ${s.attestedBy}` : "";
301
+ lines.push(
302
+ "",
303
+ `${i + 1}. ${s.signer}: ${s.decision} (${key}${attested})`,
304
+ ` key ${keyText(s.key)}`,
305
+ ...s.delegationKey ? [` delegation key ${keyText(s.delegationKey)}`] : [],
306
+ ` signature ${mark(s.signatureValid)}, this agreement ${mark(s.agreementMatches)}`,
307
+ ` these terms ${mark(s.termsMatch)}, by the deadline ${mark(s.withinDeadline)}, in order ${mark(s.inOrder)}`
308
+ );
309
+ const stamp = s.timestamp;
310
+ if (stamp) {
311
+ const trusted = stamp.trusted === void 0 ? "no roots given" : mark(stamp.trusted), authority = stamp.timestampingKeyUsage === void 0 ? "" : `, an authority's certificate ${mark(stamp.timestampingKeyUsage)}`;
312
+ lines.push(
313
+ ` timestamped ${stamp.time ?? "unreadable"} by ${stamp.authority ?? "unknown"}: over this statement ${mark(stamp.imprintMatches)}, signed ${mark(stamp.signatureValid)}${authority}, trusted ${trusted}`
314
+ );
315
+ }
316
+ s.arrival && lines.push(
317
+ ` arrived ${s.arrival.at}, received by ${s.arrival.receivedBy}, signed ${mark(s.arrival.signatureValid)}`
318
+ ), s.keyChain && lines.push(...chainText(s.keyChain, " "));
319
+ }), lines.push(
320
+ "",
321
+ ...facts.keysConfirmedOnline ? ["keys confirmed online: each key was its identity's, by its chain or DNS, now"] : [
322
+ "keys from the bundle, not confirmed online: complete says the bundle is",
323
+ "consistent, not that each key was its identity's when it signed"
324
+ ],
325
+ line("complete", mark(facts.complete))
326
+ ), lines.join(`
327
+ `);
328
+ };
329
+ export {
330
+ buildEvidenceBundle,
331
+ describeEvidenceFacts,
332
+ signArrival,
333
+ verifyEvidenceBundle
334
+ };
@@ -8,3 +8,13 @@ export { default as JsonTrustStore } from './storage/JsonTrustStore.js';
8
8
  export { AbstractTrustStore } from './storage/AbstractTrustStore.js';
9
9
  export * from './types.js';
10
10
  export * from './trustUtils.js';
11
+ export * from './permissions.js';
12
+ export * from './verification.js';
13
+ export * from './agreements.js';
14
+ export * from './evidence.js';
15
+ export * from './timestamps.js';
16
+ export * from './keyRotation.js';
17
+ export { shapeTrustRequestFor11, composeTrustRequestFor } from './shaping.js';
18
+ export * from '../server/constants/permissions.js';
19
+ export type { BTPDocumentType, BTPEntityType, BTPSendPermission, BTPDetailPermission, BTPPermissionName, BTPPermission, BTPTrustPermissions, } from '../server/types.js';
20
+ export { trustRequestProblem, trustResponseProblem } from '../server/schemas/trustValues.js';
@@ -9,7 +9,20 @@ import { default as default2 } from "./storage/JsonTrustStore.js";
9
9
  import { AbstractTrustStore } from "./storage/AbstractTrustStore.js";
10
10
  export * from "./types.js";
11
11
  export * from "./trustUtils.js";
12
+ export * from "./permissions.js";
13
+ export * from "./verification.js";
14
+ export * from "./agreements.js";
15
+ export * from "./evidence.js";
16
+ export * from "./timestamps.js";
17
+ export * from "./keyRotation.js";
18
+ import { shapeTrustRequestFor11, composeTrustRequestFor } from "./shaping.js";
19
+ export * from "../server/constants/permissions.js";
20
+ import { trustRequestProblem, trustResponseProblem } from "../server/schemas/trustValues.js";
12
21
  export {
13
22
  AbstractTrustStore,
14
- default2 as JsonTrustStore
23
+ default2 as JsonTrustStore,
24
+ composeTrustRequestFor,
25
+ shapeTrustRequestFor11,
26
+ trustRequestProblem,
27
+ trustResponseProblem
15
28
  };
@@ -0,0 +1,148 @@
1
+ /**
2
+ * @license
3
+ * Copyright (c) 2025 Bhupendra Tamang
4
+ * Licensed under the Apache License, Version 2.0
5
+ * https://www.apache.org/licenses/LICENSE-2.0
6
+ */
7
+ import type { PemKeys } from '../crypto/types.js';
8
+ import type { Signer } from '../crypto/signer-interface.js';
9
+ import type { BTPError } from '../error/types.js';
10
+ import type { BTPKeyChainDns, BTPKeyChainFacts, BTPKeyChainKey, BTPKeyChainRecord, BTPKeyExpiry, BTPKeyExpiryReason } from './types.js';
11
+ /** Who signs a record: a key pair held here, or a Signer holding the key elsewhere (a KMS). */
12
+ export type BTPKeyHolder = {
13
+ pemFiles: PemKeys;
14
+ } | {
15
+ signer: Signer;
16
+ };
17
+ /** Since 1.2: what the next record names as `prev`: the SHA-256 of this record's signed object, lowercase hex. */
18
+ export declare const keyChainRecordHash: (record: BTPKeyChainRecord) => string;
19
+ /**
20
+ * Since 1.2: the identity's key `from` hands over to `to`. Both sign, so a key
21
+ * whose holder did not agree can never be named. A rotation with immediate
22
+ * expiry (the old key is compromised or lost) may go without `from`'s
23
+ * signature; then `from.publicKey` (SPKI PEM) names the lost key, and the
24
+ * record counts only where an anchor confirms its authority.
25
+ */
26
+ export declare const signKeyRotation: (rotation: {
27
+ identity: string;
28
+ from: {
29
+ selector: string;
30
+ publicKey?: string;
31
+ };
32
+ to: {
33
+ selector: string;
34
+ };
35
+ at: string;
36
+ prev: string | null;
37
+ } & ({
38
+ expiry?: "planned";
39
+ } | {
40
+ expiry: "immediate";
41
+ compromisedSince: string;
42
+ reason: BTPKeyExpiryReason;
43
+ }), keys: {
44
+ from?: BTPKeyHolder;
45
+ to: BTPKeyHolder;
46
+ }) => Promise<BTPKeyChainRecord>;
47
+ /**
48
+ * Since 1.2: a key the identity already rotated away from turns out to have
49
+ * been compromised. The identity's current key signs it; nothing rotates.
50
+ */
51
+ export declare const signKeyExpiry: (expiry: Omit<BTPKeyExpiry, "type">, current: BTPKeyHolder) => Promise<BTPKeyChainRecord>;
52
+ /** Since 1.2: a record of a checked chain, with its place in the list and its hash. */
53
+ export type BTPKeyChainNode = {
54
+ record: BTPKeyChainRecord;
55
+ index: number;
56
+ hash: string;
57
+ };
58
+ /** One path from the chain's first record to a last one, with the keys it leaves. */
59
+ export type BTPKeyChainPath = {
60
+ nodes: BTPKeyChainNode[];
61
+ keys: BTPKeyChainKey[];
62
+ lost: boolean;
63
+ };
64
+ /**
65
+ * Since 1.2: a key chain checked once: its shape, every record's signatures,
66
+ * and the chain rules, along every path. The facts for any anchor follow from
67
+ * it (`keyChainFactsOf`) without checking a signature again, so a verifier
68
+ * that sees the same chain often keeps this.
69
+ */
70
+ export type BTPCheckedKeyChain = {
71
+ problem: string;
72
+ } | {
73
+ problem?: undefined;
74
+ records: BTPKeyChainRecord[];
75
+ paths: BTPKeyChainPath[];
76
+ };
77
+ export declare const checkKeyChain: (records: unknown[], identity: string) => BTPCheckedKeyChain;
78
+ /**
79
+ * Since 1.2: the facts about an identity's key chain, refusing nothing.
80
+ *
81
+ * - `anchors`: fingerprints the reader kept, each the identity's key when the
82
+ * reader saw it. One anchors itself and the records leading to it, never a
83
+ * record after it, which a thief holding that key could have signed.
84
+ * - `online`: whether the chain came in the operator's signed answer, and
85
+ * what DNS says of the identity (BTPKeyChainDns). It anchors the whole chain
86
+ * when the chain's last key is a key DNS publishes for the identity, or,
87
+ * for a host-only identity, on the operator's answer alone. A rotation
88
+ * without the old key's signature (a lost key) is confirmed only so: every
89
+ * later record is signed by the key it named.
90
+ */
91
+ export declare const verifyKeyChain: (records: unknown[], options: {
92
+ identity: string;
93
+ anchors?: string[];
94
+ online?: {
95
+ fromOperator: boolean;
96
+ dns: BTPKeyChainDns;
97
+ };
98
+ }) => BTPKeyChainFacts;
99
+ /** Since 1.2: `verifyKeyChain`'s facts, from a chain already checked (`checkKeyChain`). */
100
+ export declare const keyChainFactsOf: (checked: BTPCheckedKeyChain, options: {
101
+ anchors?: string[];
102
+ online?: {
103
+ fromOperator: boolean;
104
+ dns: BTPKeyChainDns;
105
+ };
106
+ }) => BTPKeyChainFacts;
107
+ /**
108
+ * Since 1.2: why a verifier online refuses an identity's key chain, or
109
+ * undefined. It came in the operator's signed answer (`fromOperator`), and
110
+ * `dns` is what DNS says of the identity. A chain that forks, or does not end
111
+ * at a key DNS publishes for an identity that publishes one, is refused, and
112
+ * so is a record dated more than `maxSkewSeconds` (default 300, the server's
113
+ * maxArtifactAgeSeconds) past `now`.
114
+ */
115
+ export declare const keyChainProblem: (records: unknown[], options: {
116
+ identity: string;
117
+ fromOperator: boolean;
118
+ dns: BTPKeyChainDns;
119
+ now?: number;
120
+ maxSkewSeconds?: number;
121
+ }) => string | undefined;
122
+ /** Since 1.2: `keyChainProblem`, for a chain already checked (`checkKeyChain`). */
123
+ export declare const keyChainProblemOf: (checked: BTPCheckedKeyChain, options: {
124
+ fromOperator: boolean;
125
+ dns: BTPKeyChainDns;
126
+ now?: number;
127
+ maxSkewSeconds?: number;
128
+ }) => string | undefined;
129
+ /**
130
+ * Since 1.2: a key of a verified chain and its window: by fingerprint when
131
+ * given (the same key may be published under a later selector), else by the
132
+ * selector the chain names it under.
133
+ */
134
+ export declare const keyAt: (facts: BTPKeyChainFacts, ref: {
135
+ selector?: string;
136
+ fingerprint?: string;
137
+ }) => BTPKeyChainKey | undefined;
138
+ /**
139
+ * Since 1.2: why a live artifact signed by this key of a verified chain is
140
+ * refused now, or undefined. Expired (a rotation with immediate expiry, or an
141
+ * expiry record): `BTP_ERROR_KEY_REVOKED`, whatever the artifact's own time
142
+ * says. Rotated away as planned more than `retiredKeyGraceSeconds` ago:
143
+ * `BTP_ERROR_KEY_RETIRED`. The current key, and a key within its grace, pass.
144
+ */
145
+ export declare const keyChainSignerProblem: (key: BTPKeyChainKey, options: {
146
+ now?: number;
147
+ retiredKeyGraceSeconds: number;
148
+ }) => BTPError | undefined;