@btps/sdk 1.1.2 → 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.
- package/CHANGELOG.md +475 -0
- package/bin/verify-evidence-bundle.mjs +96 -0
- package/dist/client/btpsAgent.d.ts +10 -1
- package/dist/client/btpsAgent.js +117 -19
- package/dist/client/btpsClient.d.ts +53 -7
- package/dist/client/btpsClient.js +266 -137
- package/dist/client/btpsTransporter.js +2 -1
- package/dist/client/index.d.ts +1 -1
- package/dist/client/index.js +3 -1
- package/dist/client/libs/schema.js +92 -15
- package/dist/client/libs/timeouts.d.ts +6 -0
- package/dist/client/libs/timeouts.js +2 -1
- package/dist/client/types/index.d.ts +60 -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 +28 -3
- package/dist/core/crypto/index.js +34 -20
- 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 +41 -0
- package/dist/core/error/constant.js +60 -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 +41 -1
- package/dist/core/server/constants/limits.js +45 -2
- 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 +92 -12
- package/dist/core/server/schemas/bounded.js +41 -0
- package/dist/core/server/schemas/btpsDocsSchema.d.ts +34522 -1421
- package/dist/core/server/schemas/btpsDocsSchema.js +355 -68
- package/dist/core/server/schemas/helpers.d.ts +9580 -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 +88 -12
- package/dist/core/server/schemas/schema.js +6 -2
- 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 +302 -2
- package/dist/core/trust/verification.d.ts +52 -0
- package/dist/core/trust/verification.js +55 -0
- package/dist/server/btpsServer.d.ts +72 -6
- package/dist/server/btpsServer.js +280 -157
- 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 +95 -9
- 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';
|
package/dist/core/trust/index.js
CHANGED
|
@@ -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;
|