@cello-protocol/cli 0.0.306 → 0.0.307
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/.claude-plugin/marketplace.json +15 -0
- package/README.md +107 -0
- package/dist/cli.d.ts +2 -0
- package/dist/cli.js +564 -0
- package/dist/daemon/account-page-assets.d.ts +4 -0
- package/dist/daemon/account-page-assets.js +160 -0
- package/dist/daemon/account-page.d.ts +14 -0
- package/dist/daemon/account-page.js +104 -0
- package/dist/daemon/address.d.ts +10 -0
- package/dist/daemon/address.js +34 -0
- package/dist/daemon/away.d.ts +31 -0
- package/dist/daemon/away.js +65 -0
- package/dist/daemon/channel-store.d.ts +112 -0
- package/dist/daemon/channel-store.js +284 -0
- package/dist/daemon/channels.d.ts +46 -0
- package/dist/daemon/channels.js +1049 -0
- package/dist/daemon/contacts.d.ts +26 -0
- package/dist/daemon/contacts.js +74 -0
- package/dist/daemon/engine.d.ts +80 -0
- package/dist/daemon/engine.js +2882 -0
- package/dist/daemon/errors.d.ts +5 -0
- package/dist/daemon/errors.js +16 -0
- package/dist/daemon/governance.d.ts +66 -0
- package/dist/daemon/governance.js +514 -0
- package/dist/daemon/guards.d.ts +36 -0
- package/dist/daemon/guards.js +140 -0
- package/dist/daemon/issuer-client.d.ts +56 -0
- package/dist/daemon/issuer-client.js +143 -0
- package/dist/daemon/link.d.ts +30 -0
- package/dist/daemon/link.js +191 -0
- package/dist/daemon/log.d.ts +1 -0
- package/dist/daemon/log.js +4 -0
- package/dist/daemon/main.d.ts +1 -0
- package/dist/daemon/main.js +511 -0
- package/dist/daemon/paths.d.ts +6 -0
- package/dist/daemon/paths.js +21 -0
- package/dist/daemon/pii.d.ts +24 -0
- package/dist/daemon/pii.js +146 -0
- package/dist/daemon/policy-cadence.d.ts +33 -0
- package/dist/daemon/policy-cadence.js +59 -0
- package/dist/daemon/policy-proposals.d.ts +41 -0
- package/dist/daemon/policy-proposals.js +83 -0
- package/dist/daemon/policy-store.d.ts +47 -0
- package/dist/daemon/policy-store.js +144 -0
- package/dist/daemon/presented.d.ts +36 -0
- package/dist/daemon/presented.js +94 -0
- package/dist/daemon/rate-limit.d.ts +17 -0
- package/dist/daemon/rate-limit.js +44 -0
- package/dist/daemon/reach.d.ts +63 -0
- package/dist/daemon/reach.js +207 -0
- package/dist/daemon/screening.d.ts +97 -0
- package/dist/daemon/screening.js +362 -0
- package/dist/daemon/settings.d.ts +125 -0
- package/dist/daemon/settings.js +73 -0
- package/dist/daemon/signal-rules.d.ts +55 -0
- package/dist/daemon/signal-rules.js +127 -0
- package/dist/daemon/signal-store.d.ts +53 -0
- package/dist/daemon/signal-store.js +114 -0
- package/dist/daemon/store.d.ts +188 -0
- package/dist/daemon/store.js +474 -0
- package/dist/daemon/tiers.d.ts +14 -0
- package/dist/daemon/tiers.js +9 -0
- package/dist/daemon/wallet.d.ts +73 -0
- package/dist/daemon/wallet.js +428 -0
- package/dist/daemon/who-label.d.ts +3 -0
- package/dist/daemon/who-label.js +11 -0
- package/dist/guidance.d.ts +39 -0
- package/dist/guidance.js +98 -0
- package/dist/hermes-bridge.d.ts +26 -0
- package/dist/hermes-bridge.js +180 -0
- package/dist/install-mcp.d.ts +6 -0
- package/dist/install-mcp.js +77 -0
- package/dist/ipc/client.d.ts +18 -0
- package/dist/ipc/client.js +107 -0
- package/dist/ipc/operations.d.ts +30 -0
- package/dist/ipc/operations.js +835 -0
- package/dist/ipc/protocol.d.ts +21 -0
- package/dist/ipc/protocol.js +1 -0
- package/dist/issuer-list-sign.d.ts +12 -0
- package/dist/issuer-list-sign.js +43 -0
- package/dist/local-operations.d.ts +2 -0
- package/dist/local-operations.js +73 -0
- package/dist/mcp-tools.d.ts +14 -0
- package/dist/mcp-tools.js +45 -0
- package/dist/mcp.d.ts +2 -0
- package/dist/mcp.js +155 -0
- package/dist/protocol/aead.d.ts +4 -0
- package/dist/protocol/aead.js +35 -0
- package/dist/protocol/cbor.d.ts +40 -0
- package/dist/protocol/cbor.js +106 -0
- package/dist/protocol/chain.d.ts +44 -0
- package/dist/protocol/chain.js +126 -0
- package/dist/protocol/channel.d.ts +153 -0
- package/dist/protocol/channel.js +298 -0
- package/dist/protocol/encode.d.ts +6 -0
- package/dist/protocol/encode.js +21 -0
- package/dist/protocol/identity.d.ts +27 -0
- package/dist/protocol/identity.js +94 -0
- package/dist/protocol/issuer-list.d.ts +56 -0
- package/dist/protocol/issuer-list.js +193 -0
- package/dist/protocol/issuer-roots.d.ts +6 -0
- package/dist/protocol/issuer-roots.js +10 -0
- package/dist/protocol/key-agreement.d.ts +20 -0
- package/dist/protocol/key-agreement.js +88 -0
- package/dist/protocol/merkle.d.ts +16 -0
- package/dist/protocol/merkle.js +166 -0
- package/dist/protocol/ml-dsa.d.ts +28 -0
- package/dist/protocol/ml-dsa.js +58 -0
- package/dist/protocol/ml-kem.d.ts +14 -0
- package/dist/protocol/ml-kem.js +57 -0
- package/dist/protocol/pq-errors.d.ts +9 -0
- package/dist/protocol/pq-errors.js +23 -0
- package/dist/protocol/pq-warnings.d.ts +1 -0
- package/dist/protocol/pq-warnings.js +18 -0
- package/dist/protocol/presented-signals.d.ts +17 -0
- package/dist/protocol/presented-signals.js +92 -0
- package/dist/protocol/salt.d.ts +5 -0
- package/dist/protocol/salt.js +47 -0
- package/dist/protocol/seal.d.ts +58 -0
- package/dist/protocol/seal.js +220 -0
- package/dist/protocol/signal.d.ts +54 -0
- package/dist/protocol/signal.js +266 -0
- package/dist/protocol/status.d.ts +41 -0
- package/dist/protocol/status.js +64 -0
- package/dist/protocol/structures.d.ts +359 -0
- package/dist/protocol/structures.js +296 -0
- package/dist/protocol/transcript.d.ts +61 -0
- package/dist/protocol/transcript.js +319 -0
- package/dist/protocol/wire.d.ts +212 -0
- package/dist/protocol/wire.js +161 -0
- package/dist/require-node.d.ts +1 -0
- package/dist/require-node.js +10 -0
- package/dist/screener/affordance.d.ts +1 -0
- package/dist/screener/affordance.js +2 -0
- package/dist/screener/classifier-selfcheck.d.ts +29 -0
- package/dist/screener/classifier-selfcheck.js +56 -0
- package/dist/screener/exfil.d.ts +11 -0
- package/dist/screener/exfil.js +45 -0
- package/dist/screener/gitleaks-rules.d.ts +9 -0
- package/dist/screener/gitleaks-rules.js +226 -0
- package/dist/screener/inbound.d.ts +25 -0
- package/dist/screener/inbound.js +102 -0
- package/dist/screener/injection-classifier-onnx.d.ts +20 -0
- package/dist/screener/injection-classifier-onnx.js +89 -0
- package/dist/screener/injection-classifier-wasm.d.ts +2 -0
- package/dist/screener/injection-classifier-wasm.js +97 -0
- package/dist/screener/injection-patterns.d.ts +8 -0
- package/dist/screener/injection-patterns.js +48 -0
- package/dist/screener/injection-windows.d.ts +9 -0
- package/dist/screener/injection-windows.js +37 -0
- package/dist/screener/language.d.ts +15 -0
- package/dist/screener/language.js +71 -0
- package/dist/screener/linear-regex.d.ts +8 -0
- package/dist/screener/linear-regex.js +27 -0
- package/dist/screener/model-installer.d.ts +14 -0
- package/dist/screener/model-installer.js +61 -0
- package/dist/screener/outbound.d.ts +19 -0
- package/dist/screener/outbound.js +62 -0
- package/dist/screener/sanitize.d.ts +44 -0
- package/dist/screener/sanitize.js +361 -0
- package/dist/screener/scan-variants.d.ts +5 -0
- package/dist/screener/scan-variants.js +146 -0
- package/dist/screener/screener-model-manifest.d.ts +16 -0
- package/dist/screener/screener-model-manifest.js +20 -0
- package/dist/screener/screener-state.d.ts +29 -0
- package/dist/screener/screener-state.js +119 -0
- package/dist/screener/secrets.d.ts +18 -0
- package/dist/screener/secrets.js +84 -0
- package/dist/screener/worker.d.ts +6 -0
- package/dist/screener/worker.js +83 -0
- package/dist/setup.d.ts +9 -0
- package/dist/setup.js +252 -0
- package/dist/shipped-issuer-list.d.ts +1 -0
- package/dist/shipped-issuer-list.js +3 -0
- package/dist/signals-text.d.ts +46 -0
- package/dist/signals-text.js +81 -0
- package/dist/verify-seal.d.ts +9 -0
- package/dist/verify-seal.js +30 -0
- package/hermes/plugin/__init__.py +1040 -0
- package/hermes/plugin/plugin.yaml +30 -0
- package/hermes/skills/cello-bridge-setup/SKILL.md +38 -0
- package/hermes/skills/cello-policy/SKILL.md +44 -0
- package/package.json +48 -16
- package/plugins/cello/.claude-plugin/plugin.json +19 -0
- package/plugins/cello/.mcp.json +7 -0
- package/plugins/cello/skills/cello/SKILL.md +117 -0
- package/dist/arg-parse.d.ts +0 -19
- package/dist/arg-parse.d.ts.map +0 -1
- package/dist/arg-parse.js +0 -29
- package/dist/arg-parse.js.map +0 -1
- package/dist/bin/cello.d.ts +0 -15
- package/dist/bin/cello.d.ts.map +0 -1
- package/dist/bin/cello.js +0 -110
- package/dist/bin/cello.js.map +0 -1
- package/dist/cli-args.d.ts +0 -62
- package/dist/cli-args.d.ts.map +0 -1
- package/dist/cli-args.js +0 -129
- package/dist/cli-args.js.map +0 -1
- package/dist/commands.d.ts +0 -196
- package/dist/commands.d.ts.map +0 -1
- package/dist/commands.js +0 -1544
- package/dist/commands.js.map +0 -1
- package/dist/hermes/assets.d.ts +0 -41
- package/dist/hermes/assets.d.ts.map +0 -1
- package/dist/hermes/assets.js +0 -2281
- package/dist/hermes/assets.js.map +0 -1
- package/dist/hermes/install-hermes.d.ts +0 -50
- package/dist/hermes/install-hermes.d.ts.map +0 -1
- package/dist/hermes/install-hermes.js +0 -232
- package/dist/hermes/install-hermes.js.map +0 -1
- package/dist/json-out.d.ts +0 -41
- package/dist/json-out.d.ts.map +0 -1
- package/dist/json-out.js +0 -59
- package/dist/json-out.js.map +0 -1
- package/dist/node-runtime-guard-init.d.ts +0 -6
- package/dist/node-runtime-guard-init.d.ts.map +0 -1
- package/dist/node-runtime-guard-init.js +0 -7
- package/dist/node-runtime-guard-init.js.map +0 -1
- package/dist/node-runtime-guard.d.ts +0 -48
- package/dist/node-runtime-guard.d.ts.map +0 -1
- package/dist/node-runtime-guard.js +0 -79
- package/dist/node-runtime-guard.js.map +0 -1
- package/dist/parity-commands.d.ts +0 -427
- package/dist/parity-commands.d.ts.map +0 -1
- package/dist/parity-commands.js +0 -953
- package/dist/parity-commands.js.map +0 -1
- package/dist/registry.d.ts +0 -120
- package/dist/registry.d.ts.map +0 -1
- package/dist/registry.js +0 -2169
- package/dist/registry.js.map +0 -1
- package/dist/screener-commands.d.ts +0 -85
- package/dist/screener-commands.d.ts.map +0 -1
- package/dist/screener-commands.js +0 -313
- package/dist/screener-commands.js.map +0 -1
|
@@ -0,0 +1,220 @@
|
|
|
1
|
+
// A seal record, and the check anyone can run on one: public keys only, with no server, daemon or database.
|
|
2
|
+
// The reader supplies the seal key's id. A record checked only against a key it carries proves nothing,
|
|
3
|
+
// because anyone can make a key and sign whatever they like with it.
|
|
4
|
+
import { ZERO_HASH, equalBytes, toHex } from "./encode.js";
|
|
5
|
+
import { identityId, verifySignature } from "./identity.js";
|
|
6
|
+
import { verifyConsistency, verifyInclusion } from "./merkle.js";
|
|
7
|
+
import { readRefusedList, sealKeyBindingBytes, structureHash, } from "./structures.js";
|
|
8
|
+
import { WireError, fromB64, identityCodec, readInt, readObjectField, signatureCodec, signedAccept, signedDeliveryAck, signedOffer, signedSealCertificate, signedSealLogHead, signedSealRequest, toB64 } from "./wire.js";
|
|
9
|
+
export const SEAL_RECORD_FORMAT = "cello-seal";
|
|
10
|
+
function readHashes(value, name) {
|
|
11
|
+
if (!Array.isArray(value))
|
|
12
|
+
throw new RangeError(`${name} isn't a list`);
|
|
13
|
+
return value.map((hash, i) => fromB64(hash, `${name}[${i}]`));
|
|
14
|
+
}
|
|
15
|
+
export function encodeHashes(hashes) {
|
|
16
|
+
return hashes.map(toB64);
|
|
17
|
+
}
|
|
18
|
+
// Throws on anything malformed. checkSealRecord turns that into a named fault.
|
|
19
|
+
export function decodeSealRecord(raw) {
|
|
20
|
+
const value = readObjectField(raw, "record");
|
|
21
|
+
if (value["format"] !== SEAL_RECORD_FORMAT)
|
|
22
|
+
throw new RangeError(`this isn't a ${SEAL_RECORD_FORMAT} record`);
|
|
23
|
+
const log = readObjectField(value["log"], "log");
|
|
24
|
+
return {
|
|
25
|
+
certificate: signedSealCertificate.decode(value["certificate"], "certificate"),
|
|
26
|
+
request: signedSealRequest.decode(value["request"], "request"),
|
|
27
|
+
offer: signedOffer.decode(value["offer"], "offer"),
|
|
28
|
+
accept: signedAccept.decode(value["accept"], "accept"),
|
|
29
|
+
deliveryAck: value["deliveryAck"] === null ? null : signedDeliveryAck.decode(value["deliveryAck"], "deliveryAck"),
|
|
30
|
+
deliveryProof: readHashes(value["deliveryProof"], "deliveryProof"),
|
|
31
|
+
sealer: identityCodec.decode(value["sealer"], "sealer"),
|
|
32
|
+
counterparty: identityCodec.decode(value["counterparty"], "counterparty"),
|
|
33
|
+
sealKey: identityCodec.decode(value["sealKey"], "sealKey"),
|
|
34
|
+
server: identityCodec.decode(value["server"], "server"),
|
|
35
|
+
sealKeyBinding: signatureCodec.decode(value["sealKeyBinding"], "sealKeyBinding"),
|
|
36
|
+
log: { index: readInt(log["index"], "log.index"), head: signedSealLogHead.decode(log["head"], "log.head"), path: readHashes(log["path"], "log.path") },
|
|
37
|
+
};
|
|
38
|
+
}
|
|
39
|
+
// A seal's id is its place in the seal log: the hash of what the seal key signed.
|
|
40
|
+
export function sealId(certificateBytes) {
|
|
41
|
+
return structureHash(certificateBytes);
|
|
42
|
+
}
|
|
43
|
+
const FAULT_MESSAGES = {
|
|
44
|
+
malformed_record: "This file isn't a readable seal record",
|
|
45
|
+
unknown_format: "This record is in a format this reader doesn't know. That says nothing about whether it's genuine, so use a newer reader",
|
|
46
|
+
wrong_seal_key: "This record's seal key isn't the one you named, so it says nothing about that server",
|
|
47
|
+
bad_seal_key_binding: "The server's identity doesn't vouch for this seal key",
|
|
48
|
+
bad_seal_signature: "The certificate has been changed, or wasn't signed by this seal key",
|
|
49
|
+
wrong_sealer_keys: "The sealer's keys in this record don't match the certificate",
|
|
50
|
+
bad_seal_request: "The sealer didn't sign the request behind this certificate",
|
|
51
|
+
seal_request_mismatch: "The certificate differs from what the sealer asked to have sealed",
|
|
52
|
+
wrong_counterparty_keys: "The counterparty's keys in this record don't match the certificate",
|
|
53
|
+
no_session_agreement: "The named counterparty's signed accept of this session isn't in this record, so nothing shows they ever joined it",
|
|
54
|
+
impossible_positions: "The certificate's positions can't be true together",
|
|
55
|
+
delivery_ack_mismatch: "The number received doesn't match the counterparty's signed delivery ack",
|
|
56
|
+
bad_delivery_ack_signature: "The counterparty didn't sign this delivery ack",
|
|
57
|
+
delivery_proof_failed: "What the counterparty signed isn't a part of the same history as the sealed root",
|
|
58
|
+
bad_log_head_signature: "The seal log's state wasn't signed by this seal key",
|
|
59
|
+
log_proof_failed: "This seal isn't in the seal log state it claims",
|
|
60
|
+
};
|
|
61
|
+
function fail(fault, detail) {
|
|
62
|
+
return { ok: false, fault, message: detail ? `${FAULT_MESSAGES[fault]}: ${detail}` : FAULT_MESSAGES[fault] };
|
|
63
|
+
}
|
|
64
|
+
async function findFault(record, sealKeyId) {
|
|
65
|
+
const cert = record.certificate.fields;
|
|
66
|
+
const actualKeyId = identityId(record.sealKey);
|
|
67
|
+
if (!equalBytes(actualKeyId, sealKeyId) || !equalBytes(cert.sealKeyId, sealKeyId))
|
|
68
|
+
return fail("wrong_seal_key", `it carries ${toHex(actualKeyId)}`);
|
|
69
|
+
if (!equalBytes(identityId(record.server), cert.serverId))
|
|
70
|
+
return fail("bad_seal_key_binding");
|
|
71
|
+
if (!(await verifySignature(record.server, "cello-seal-key-binding", sealKeyBindingBytes({ serverId: cert.serverId, sealKeyId }), record.sealKeyBinding)))
|
|
72
|
+
return fail("bad_seal_key_binding");
|
|
73
|
+
if (!(await verifySignature(record.sealKey, "cello-seal-certificate", record.certificate.bytes, record.certificate.signature)))
|
|
74
|
+
return fail("bad_seal_signature");
|
|
75
|
+
if (!equalBytes(identityId(record.sealer), cert.sealerId))
|
|
76
|
+
return fail("wrong_sealer_keys");
|
|
77
|
+
const request = record.request.fields;
|
|
78
|
+
const requestBytes = record.request.bytes;
|
|
79
|
+
if (!(await verifySignature(record.sealer, "cello-seal-request", requestBytes, record.request.signature)))
|
|
80
|
+
return fail("bad_seal_request");
|
|
81
|
+
const asked = equalBytes(structureHash(requestBytes), cert.requestHash)
|
|
82
|
+
&& equalBytes(request.sealerId, cert.sealerId)
|
|
83
|
+
&& equalBytes(request.counterpartyId, cert.counterpartyId)
|
|
84
|
+
&& equalBytes(request.sessionId, cert.sessionId)
|
|
85
|
+
&& equalBytes(request.serverId, cert.serverId)
|
|
86
|
+
&& equalBytes(request.root, cert.root)
|
|
87
|
+
&& request.throughPosition === cert.throughPosition;
|
|
88
|
+
if (!asked)
|
|
89
|
+
return fail("seal_request_mismatch");
|
|
90
|
+
if (!equalBytes(identityId(record.counterparty), cert.counterpartyId))
|
|
91
|
+
return fail("wrong_counterparty_keys");
|
|
92
|
+
if (equalBytes(cert.sealerId, cert.counterpartyId))
|
|
93
|
+
return fail("impossible_positions", "the sealer and the counterparty are the same");
|
|
94
|
+
const agreementFault = await findAgreementFault(record);
|
|
95
|
+
if (agreementFault)
|
|
96
|
+
return agreementFault;
|
|
97
|
+
const positionsPossible = cert.throughPosition >= 1 && cert.tip >= cert.throughPosition && cert.receivedThrough <= cert.throughPosition;
|
|
98
|
+
if (!positionsPossible)
|
|
99
|
+
return fail("impossible_positions");
|
|
100
|
+
const deliveryFault = await findDeliveryFault(record);
|
|
101
|
+
if (deliveryFault)
|
|
102
|
+
return deliveryFault;
|
|
103
|
+
const head = record.log.head;
|
|
104
|
+
if (!equalBytes(head.fields.sealKeyId, sealKeyId) || !(await verifySignature(record.sealKey, "cello-seal-log-head", head.bytes, head.signature)))
|
|
105
|
+
return fail("bad_log_head_signature");
|
|
106
|
+
if (!verifyInclusion(sealId(record.certificate.bytes), record.log.index, head.fields.size, head.fields.root, record.log.path))
|
|
107
|
+
return fail("log_proof_failed");
|
|
108
|
+
return null;
|
|
109
|
+
}
|
|
110
|
+
// The two parties' own signatures on how this session began, so a counterparty named in a seal is one who took part.
|
|
111
|
+
async function findAgreementFault(record) {
|
|
112
|
+
const cert = record.certificate.fields;
|
|
113
|
+
const offer = record.offer.fields;
|
|
114
|
+
const sealerCalled = equalBytes(offer.callerId, cert.sealerId) && equalBytes(offer.calleeId, cert.counterpartyId);
|
|
115
|
+
const sealerAnswered = equalBytes(offer.callerId, cert.counterpartyId) && equalBytes(offer.calleeId, cert.sealerId);
|
|
116
|
+
if ((!sealerCalled && !sealerAnswered) || !equalBytes(offer.sessionId, cert.sessionId) || !equalBytes(offer.serverId, cert.serverId))
|
|
117
|
+
return fail("no_session_agreement", "the offer is for another session or other parties");
|
|
118
|
+
if (!equalBytes(record.accept.fields.offerHash, structureHash(record.offer.bytes)))
|
|
119
|
+
return fail("no_session_agreement", "the accept answers a different offer");
|
|
120
|
+
const [caller, callee] = sealerCalled ? [record.sealer, record.counterparty] : [record.counterparty, record.sealer];
|
|
121
|
+
if (!(await verifySignature(caller, "cello-session-offer", record.offer.bytes, record.offer.signature)))
|
|
122
|
+
return fail("no_session_agreement", "the caller didn't sign the offer");
|
|
123
|
+
if (!(await verifySignature(callee, "cello-session-accept", record.accept.bytes, record.accept.signature)))
|
|
124
|
+
return fail("no_session_agreement", "the callee didn't sign the accept");
|
|
125
|
+
return null;
|
|
126
|
+
}
|
|
127
|
+
// M counts delivery acks only, and the check runs on the counterparty's own signature, never the server's word.
|
|
128
|
+
async function findDeliveryFault(record) {
|
|
129
|
+
const cert = record.certificate.fields;
|
|
130
|
+
const signed = record.deliveryAck;
|
|
131
|
+
if (!signed) {
|
|
132
|
+
if (cert.receivedThrough !== 0 || !equalBytes(cert.deliveryAckHash, ZERO_HASH))
|
|
133
|
+
return fail("delivery_ack_mismatch", "there's no delivery ack behind this number");
|
|
134
|
+
return record.deliveryProof.length === 0 ? null : fail("delivery_proof_failed");
|
|
135
|
+
}
|
|
136
|
+
const ack = signed.fields;
|
|
137
|
+
const { bytes } = signed;
|
|
138
|
+
if (!equalBytes(structureHash(bytes), cert.deliveryAckHash))
|
|
139
|
+
return fail("delivery_ack_mismatch", "the certificate names a different ack");
|
|
140
|
+
if (!equalBytes(ack.readerId, cert.counterpartyId) || !equalBytes(ack.sessionId, cert.sessionId) || !equalBytes(ack.serverId, cert.serverId))
|
|
141
|
+
return fail("delivery_ack_mismatch", "this ack isn't the counterparty's, for this session");
|
|
142
|
+
if (Math.min(ack.throughPosition, cert.throughPosition) !== cert.receivedThrough || cert.receivedThrough < 1) {
|
|
143
|
+
return fail("delivery_ack_mismatch", `the certificate says ${cert.receivedThrough}, and the counterparty signed through ${ack.throughPosition}`);
|
|
144
|
+
}
|
|
145
|
+
if (!(await verifySignature(record.counterparty, "cello-delivery-ack", bytes, signed.signature)))
|
|
146
|
+
return fail("bad_delivery_ack_signature");
|
|
147
|
+
const linked = ack.throughPosition <= cert.throughPosition
|
|
148
|
+
? verifyConsistency(ack.throughPosition, cert.throughPosition, ack.root, cert.root, record.deliveryProof)
|
|
149
|
+
: verifyConsistency(cert.throughPosition, ack.throughPosition, cert.root, ack.root, record.deliveryProof);
|
|
150
|
+
return linked ? null : fail("delivery_proof_failed");
|
|
151
|
+
}
|
|
152
|
+
// What the counterparty signed that it refused, within what this seal covers.
|
|
153
|
+
export function refusedPositions(record) {
|
|
154
|
+
if (!record.deliveryAck)
|
|
155
|
+
return [];
|
|
156
|
+
return readRefusedList(record.deliveryAck.fields.refused).filter((position) => position <= record.certificate.fields.throughPosition);
|
|
157
|
+
}
|
|
158
|
+
// Never throws on a bad record: every bad input is a named fault.
|
|
159
|
+
export async function checkSealRecord(raw, sealKeyId) {
|
|
160
|
+
let record;
|
|
161
|
+
try {
|
|
162
|
+
record = decodeSealRecord(raw);
|
|
163
|
+
identityId(record.sealKey);
|
|
164
|
+
identityId(record.server);
|
|
165
|
+
identityId(record.sealer);
|
|
166
|
+
identityId(record.counterparty);
|
|
167
|
+
}
|
|
168
|
+
catch (err) {
|
|
169
|
+
if (err instanceof WireError && err.code === "unsupported_version")
|
|
170
|
+
return fail("unknown_format", err.message);
|
|
171
|
+
return fail("malformed_record", err instanceof Error ? err.message : String(err));
|
|
172
|
+
}
|
|
173
|
+
return (await findFault(record, sealKeyId)) ?? { ok: true, record };
|
|
174
|
+
}
|
|
175
|
+
// What the seal does and doesn't show, for a person to read. Neutral on agreement, always.
|
|
176
|
+
export function describeSeal(record) {
|
|
177
|
+
const cert = record.certificate.fields;
|
|
178
|
+
const n = cert.throughPosition;
|
|
179
|
+
const m = cert.receivedThrough;
|
|
180
|
+
const beyond = cert.tip - n;
|
|
181
|
+
const refused = refusedPositions(record);
|
|
182
|
+
return {
|
|
183
|
+
meaning: "A seal attests that this conversation took place. It says nothing about whether the parties agreed.",
|
|
184
|
+
proven_without_trusting_the_server: m > 0
|
|
185
|
+
? `Positions 1 to ${m}: the counterparty's own signature says its machine stored and decrypted these, in this order. That rests on its key, not on the server. Received means stored and decrypted, not read.${refused.length > 0 ? ` Except positions ${refused.join(", ")}: the counterparty signed that their text wasn't what their author signed, so it holds no such words.` : ""}`
|
|
186
|
+
: "Nothing: the counterparty has signed no delivery ack for any of this.",
|
|
187
|
+
rests_on_the_server: `${m < n
|
|
188
|
+
? `Positions ${m + 1} to ${n}: only the sealer and the server say these were witnessed in this order. The counterparty hasn't confirmed receiving them. `
|
|
189
|
+
: "Every position is covered by the counterparty's signature. "}Also the time, how many positions the session had, and whether it had closed: no counterparty signature stands behind those.`,
|
|
190
|
+
how_much_this_covers: `${beyond > 0 ? `This is a partial seal. The server says the session had ${cert.tip} positions when sealed, and this covers ${n}, so ${beyond} more exist that it doesn't cover.` : `The server says the session had ${n} positions when sealed, and this covers all of them.`} ${cert.closed === 1 ? "The server says the session had closed on both sides." : "The server says the session hadn't closed, so more may have followed."}`,
|
|
191
|
+
who_signed: "Check that session_id is the conversation you mean, and that counterparty_id is who you expect. The same two parties can have other sessions. The signature behind the received number is that key's, and an id is all it proves.",
|
|
192
|
+
seal_log: "This seal is in its server's own log. Nobody outside witnesses that log yet, so its operator could rewrite it.",
|
|
193
|
+
contents: "This record holds hashes and signatures only. It doesn't show what was said.",
|
|
194
|
+
};
|
|
195
|
+
}
|
|
196
|
+
// A time inside a signed record comes from outside, and a number too large for a date shouldn't crash the reader.
|
|
197
|
+
export function readableTime(time) {
|
|
198
|
+
const date = new Date(time);
|
|
199
|
+
return Number.isNaN(date.getTime()) ? null : date.toISOString();
|
|
200
|
+
}
|
|
201
|
+
export function sealSummary(record) {
|
|
202
|
+
const cert = record.certificate.fields;
|
|
203
|
+
return {
|
|
204
|
+
seal_id: toHex(sealId(record.certificate.bytes)),
|
|
205
|
+
seal_key: toHex(cert.sealKeyId),
|
|
206
|
+
session_id: toHex(cert.sessionId),
|
|
207
|
+
sealer_id: toHex(cert.sealerId),
|
|
208
|
+
counterparty_id: toHex(cert.counterpartyId),
|
|
209
|
+
root: toHex(cert.root),
|
|
210
|
+
witnessed_through: cert.throughPosition,
|
|
211
|
+
received_through: cert.receivedThrough,
|
|
212
|
+
refused_by_counterparty: refusedPositions(record),
|
|
213
|
+
tip_when_sealed: cert.tip,
|
|
214
|
+
partial: cert.throughPosition < cert.tip,
|
|
215
|
+
session_closed: cert.closed === 1,
|
|
216
|
+
sealed_at: readableTime(cert.time),
|
|
217
|
+
log_index: record.log.index,
|
|
218
|
+
log_size: record.log.head.fields.size,
|
|
219
|
+
};
|
|
220
|
+
}
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
import { type DualSignature, type PublicIdentity, type Signer } from "./identity.ts";
|
|
2
|
+
export declare const TRUST_SIGNAL_DOMAIN = "cello-signal-v1";
|
|
3
|
+
export declare const SIGNED_SIGNAL_DOMAIN = "cello-signed-signal-v1";
|
|
4
|
+
export declare const MAX_SIGNAL_LIFETIME_SECONDS: number;
|
|
5
|
+
export declare const MAX_SIGNAL_BYTES = 65536;
|
|
6
|
+
export declare const SIGNAL_ID_BYTES = 16;
|
|
7
|
+
export declare class ExpiryTooLong extends RangeError {
|
|
8
|
+
}
|
|
9
|
+
export type SignalSubjectKind = "account" | "agent";
|
|
10
|
+
export type SignalIssuerKind = "issuer" | "agent";
|
|
11
|
+
export interface TrustSignalEnvelope {
|
|
12
|
+
subject_kind: SignalSubjectKind;
|
|
13
|
+
subject: string;
|
|
14
|
+
issuer_kind: SignalIssuerKind;
|
|
15
|
+
issuer_pubkey: string;
|
|
16
|
+
type: string;
|
|
17
|
+
schema_version: number;
|
|
18
|
+
payload: Uint8Array;
|
|
19
|
+
issued_at: number;
|
|
20
|
+
same_operator: boolean;
|
|
21
|
+
expires_at: number | null;
|
|
22
|
+
supersedes_hash: Uint8Array | null;
|
|
23
|
+
issuer_address: string;
|
|
24
|
+
signal_id: Uint8Array;
|
|
25
|
+
}
|
|
26
|
+
export declare const CO_OWNERSHIP_NOTE = "[endorsed by an agent with the same owner \u2014 does not count toward endorsement minimums]";
|
|
27
|
+
export declare function encodeTrustSignalEnvelope(envelope: TrustSignalEnvelope): Uint8Array;
|
|
28
|
+
export declare function hashTrustSignalEnvelope(envelope: TrustSignalEnvelope): Uint8Array;
|
|
29
|
+
export declare function verifyTrustSignalHash(envelope: TrustSignalEnvelope, expected: Uint8Array): boolean;
|
|
30
|
+
export declare function decodeTrustSignalEnvelope(bytes: Uint8Array): TrustSignalEnvelope;
|
|
31
|
+
export declare function issuerPubkeyField(pub: PublicIdentity): string;
|
|
32
|
+
export declare function issuerKeys(envelope: TrustSignalEnvelope): PublicIdentity;
|
|
33
|
+
export declare function signSignal(envelope: TrustSignalEnvelope, signer: Signer): Promise<Uint8Array>;
|
|
34
|
+
export interface SignedSignal {
|
|
35
|
+
envelope: TrustSignalEnvelope;
|
|
36
|
+
envelopeBytes: Uint8Array;
|
|
37
|
+
signature: DualSignature;
|
|
38
|
+
hash: Uint8Array;
|
|
39
|
+
}
|
|
40
|
+
export declare function readSignedSignal(file: Uint8Array): SignedSignal;
|
|
41
|
+
export type SignalFault = "malformed" | "unknown_format" | "expiry_too_long" | "forged" | "wrong_subject" | "expired";
|
|
42
|
+
export type SignalCheck = {
|
|
43
|
+
ok: true;
|
|
44
|
+
signal: SignedSignal;
|
|
45
|
+
issuerId: Uint8Array;
|
|
46
|
+
} | {
|
|
47
|
+
ok: false;
|
|
48
|
+
fault: SignalFault;
|
|
49
|
+
message: string;
|
|
50
|
+
};
|
|
51
|
+
export declare function checkSignal(file: Uint8Array, expected: {
|
|
52
|
+
subject: string;
|
|
53
|
+
now: number;
|
|
54
|
+
}): Promise<SignalCheck>;
|
|
@@ -0,0 +1,266 @@
|
|
|
1
|
+
// The trust signal: a fixed-order CBOR array the issuer signs, hashed for its name, with both signatures outside the hash.
|
|
2
|
+
// Field order is the wire format. The field set is closed, and optional fields are explicit nulls in fixed slots.
|
|
3
|
+
// status, class and verified_at stay out because they change after minting. No floats: times are integer seconds.
|
|
4
|
+
import { sha256 } from "@noble/hashes/sha2.js";
|
|
5
|
+
import { encodeCbor, decodeCbor } from "./cbor.js";
|
|
6
|
+
import { ED25519_PUBLIC_KEY_BYTES, ED25519_SIGNATURE_BYTES, identityId, verifySignature } from "./identity.js";
|
|
7
|
+
import { ML_DSA_PUBLIC_KEY_BYTES, ML_DSA_SIGNATURE_BYTES } from "./ml-dsa.js";
|
|
8
|
+
import { equalBytes, toHex } from "./encode.js";
|
|
9
|
+
import { UnknownFormat, assertFlat } from "./structures.js";
|
|
10
|
+
export const TRUST_SIGNAL_DOMAIN = "cello-signal-v1";
|
|
11
|
+
export const SIGNED_SIGNAL_DOMAIN = "cello-signed-signal-v1";
|
|
12
|
+
// Each issuer picks per signal: a date at most this far from issue, or null for permanent. Fixed seconds, so every implementation draws the line in one place.
|
|
13
|
+
export const MAX_SIGNAL_LIFETIME_SECONDS = 365 * 86_400;
|
|
14
|
+
// Read before decoding, so a hostile length costs nothing. A public signal's own smaller cap belongs to the server.
|
|
15
|
+
export const MAX_SIGNAL_BYTES = 65_536;
|
|
16
|
+
export const SIGNAL_ID_BYTES = 16;
|
|
17
|
+
const ENVELOPE_ARITY = 14;
|
|
18
|
+
const SIGNED_ARITY = 4;
|
|
19
|
+
export class ExpiryTooLong extends RangeError {
|
|
20
|
+
}
|
|
21
|
+
export const CO_OWNERSHIP_NOTE = "[endorsed by an agent with the same owner — does not count toward endorsement minimums]";
|
|
22
|
+
const PREIMAGE_FIELDS = [
|
|
23
|
+
"subject_kind",
|
|
24
|
+
"subject",
|
|
25
|
+
"issuer_kind",
|
|
26
|
+
"issuer_pubkey",
|
|
27
|
+
"type",
|
|
28
|
+
"schema_version",
|
|
29
|
+
"payload",
|
|
30
|
+
"issued_at",
|
|
31
|
+
"expires_at",
|
|
32
|
+
"supersedes_hash",
|
|
33
|
+
"same_operator",
|
|
34
|
+
"issuer_address",
|
|
35
|
+
"signal_id",
|
|
36
|
+
];
|
|
37
|
+
const MAX_EPOCH_SECONDS = 100_000_000_000; // ~year 5138
|
|
38
|
+
const CBOR_UINT32_MAX = 0xffff_ffff;
|
|
39
|
+
const ISSUER_PUBKEY_HEX_LENGTH = 2 * (ED25519_PUBLIC_KEY_BYTES + ML_DSA_PUBLIC_KEY_BYTES);
|
|
40
|
+
const SIGNAL_HASH_BYTES = 32;
|
|
41
|
+
const SUPERSEDES_HASH_BYTES = 32;
|
|
42
|
+
function asCborInteger(value) {
|
|
43
|
+
return value > CBOR_UINT32_MAX ? BigInt(value) : value;
|
|
44
|
+
}
|
|
45
|
+
function requireHashableInteger(name, value, max, hint) {
|
|
46
|
+
if (typeof value !== "number" || !Number.isFinite(value)) {
|
|
47
|
+
throw new Error(`trust-signal envelope: ${name} must be a finite integer, got ${String(value)}`);
|
|
48
|
+
}
|
|
49
|
+
if (!Number.isInteger(value)) {
|
|
50
|
+
throw new Error(`trust-signal envelope: ${name} must be an integer — no floating point is hashable across implementations, got ${value}`);
|
|
51
|
+
}
|
|
52
|
+
if (value < 0) {
|
|
53
|
+
throw new Error(`trust-signal envelope: ${name} must not be negative, got ${value}`);
|
|
54
|
+
}
|
|
55
|
+
if (value > Number.MAX_SAFE_INTEGER) {
|
|
56
|
+
throw new Error(`trust-signal envelope: ${name} exceeds Number.MAX_SAFE_INTEGER (${value}) — it cannot be hashed exactly`);
|
|
57
|
+
}
|
|
58
|
+
if (value >= max) {
|
|
59
|
+
throw new Error(`trust-signal envelope: ${name} is out of range (${value}) — ${hint}`);
|
|
60
|
+
}
|
|
61
|
+
return asCborInteger(value);
|
|
62
|
+
}
|
|
63
|
+
const requireEpochSeconds = (name, value) => requireHashableInteger(name, value, MAX_EPOCH_SECONDS, "this looks like a millisecond timestamp; the contract is epoch SECONDS");
|
|
64
|
+
function requireNfcString(name, value) {
|
|
65
|
+
if (typeof value !== "string" || value.length === 0) {
|
|
66
|
+
throw new Error(`trust-signal envelope: ${name} must be a non-empty string, got ${String(value)}`);
|
|
67
|
+
}
|
|
68
|
+
if (value.normalize("NFC") !== value) {
|
|
69
|
+
throw new Error(`trust-signal envelope: ${name} must be Unicode NFC-normalized — the same logical string hashes ` +
|
|
70
|
+
`differently in NFD ("é" is c3a9 in NFC, 65cc81 in NFD), so a non-NFC value would produce a ` +
|
|
71
|
+
`signal no other implementation can reproduce. Normalize it before minting.`);
|
|
72
|
+
}
|
|
73
|
+
return value;
|
|
74
|
+
}
|
|
75
|
+
function toPreimage(envelope) {
|
|
76
|
+
if (envelope === null || typeof envelope !== "object") {
|
|
77
|
+
throw new Error(`trust-signal envelope: expected an object, got ${String(envelope)}`);
|
|
78
|
+
}
|
|
79
|
+
const known = new Set(PREIMAGE_FIELDS);
|
|
80
|
+
for (const key of Object.keys(envelope)) {
|
|
81
|
+
if (!known.has(key)) {
|
|
82
|
+
throw new Error(`trust-signal envelope: unknown envelope field "${key}". The preimage is a CLOSED set (spec §4) — ` +
|
|
83
|
+
`an unhashed field riding inside a verified signal is unauthenticated data. ` +
|
|
84
|
+
`Note status/class/verified_at are deliberately NOT hashed (they are mutable after minting) ` +
|
|
85
|
+
`and do not belong on this object.`);
|
|
86
|
+
}
|
|
87
|
+
}
|
|
88
|
+
for (const field of PREIMAGE_FIELDS) {
|
|
89
|
+
if (!(field in envelope)) {
|
|
90
|
+
throw new Error(`trust-signal envelope: missing mandatory field "${field}" (the preimage is a closed set — spec §4)`);
|
|
91
|
+
}
|
|
92
|
+
}
|
|
93
|
+
const { subject_kind, subject, issuer_kind, issuer_pubkey, type, schema_version, payload, expires_at, supersedes_hash, issuer_address, signal_id } = envelope;
|
|
94
|
+
if (subject_kind !== "account" && subject_kind !== "agent") {
|
|
95
|
+
throw new Error(`trust-signal envelope: subject_kind must be "account" or "agent", got ${String(subject_kind)}`);
|
|
96
|
+
}
|
|
97
|
+
if (issuer_kind !== "issuer" && issuer_kind !== "agent") {
|
|
98
|
+
throw new Error(`trust-signal envelope: issuer_kind must be "issuer" or "agent", got ${String(issuer_kind)}`);
|
|
99
|
+
}
|
|
100
|
+
requireNfcString("subject", subject);
|
|
101
|
+
if (!/^[0-9a-f]{64}$/.test(subject)) {
|
|
102
|
+
throw new Error(`trust-signal envelope: subject must be the agent's key, 64 lowercase hex characters, got "${subject}"`);
|
|
103
|
+
}
|
|
104
|
+
requireNfcString("issuer_address", issuer_address);
|
|
105
|
+
if (!(signal_id instanceof Uint8Array) || signal_id.length !== SIGNAL_ID_BYTES) {
|
|
106
|
+
throw new Error(`trust-signal envelope: signal_id must be exactly ${SIGNAL_ID_BYTES} raw bytes`);
|
|
107
|
+
}
|
|
108
|
+
requireNfcString("type", type);
|
|
109
|
+
requireNfcString("issuer_pubkey", issuer_pubkey);
|
|
110
|
+
if (!/^[0-9a-f]+$/.test(issuer_pubkey) || issuer_pubkey.length !== ISSUER_PUBKEY_HEX_LENGTH) {
|
|
111
|
+
throw new Error(`trust-signal envelope: issuer_pubkey must be both public keys in LOWERCASE hex, ${ISSUER_PUBKEY_HEX_LENGTH} characters. ` +
|
|
112
|
+
`Hex has a case, and "AABB" and "aabb" are the same key but different preimage bytes — which would ` +
|
|
113
|
+
`mint two different hashes for one signal.`);
|
|
114
|
+
}
|
|
115
|
+
const schemaVersion = requireHashableInteger("schema_version", schema_version, CBOR_UINT32_MAX + 1, "a schema version is a small counter, not an identifier");
|
|
116
|
+
if (!(payload instanceof Uint8Array)) {
|
|
117
|
+
throw new Error(`trust-signal envelope: payload must be raw bytes (Uint8Array), got ${payload === null ? "null" : typeof payload}. ` +
|
|
118
|
+
`An object payload would be map-encoded, and CBOR maps are not deterministic under this encoder — ` +
|
|
119
|
+
`serialize the payload yourself and pass the bytes.`);
|
|
120
|
+
}
|
|
121
|
+
const issuedAt = requireEpochSeconds("issued_at", envelope.issued_at);
|
|
122
|
+
const expiresAt = expires_at === null ? null : requireEpochSeconds("expires_at", expires_at);
|
|
123
|
+
if (expires_at !== null) {
|
|
124
|
+
if (expires_at <= envelope.issued_at)
|
|
125
|
+
throw new RangeError(`trust-signal envelope: expires_at (${expires_at}) must be after issued_at (${envelope.issued_at})`);
|
|
126
|
+
if (expires_at - envelope.issued_at > MAX_SIGNAL_LIFETIME_SECONDS)
|
|
127
|
+
throw new ExpiryTooLong("a signal's expiry can be at most one year from issue, or none at all");
|
|
128
|
+
}
|
|
129
|
+
if (supersedes_hash !== null) {
|
|
130
|
+
if (!(supersedes_hash instanceof Uint8Array)) {
|
|
131
|
+
throw new Error(`trust-signal envelope: supersedes_hash must be 32 raw bytes or null, got ${typeof supersedes_hash}`);
|
|
132
|
+
}
|
|
133
|
+
if (supersedes_hash.length !== SUPERSEDES_HASH_BYTES) {
|
|
134
|
+
throw new Error(`trust-signal envelope: supersedes_hash must be exactly ${SUPERSEDES_HASH_BYTES} bytes, got ${supersedes_hash.length}`);
|
|
135
|
+
}
|
|
136
|
+
}
|
|
137
|
+
return [
|
|
138
|
+
TRUST_SIGNAL_DOMAIN,
|
|
139
|
+
subject_kind,
|
|
140
|
+
subject,
|
|
141
|
+
issuer_kind,
|
|
142
|
+
issuer_pubkey,
|
|
143
|
+
type,
|
|
144
|
+
schemaVersion,
|
|
145
|
+
payload,
|
|
146
|
+
issuedAt,
|
|
147
|
+
expiresAt,
|
|
148
|
+
supersedes_hash,
|
|
149
|
+
envelope.same_operator === true,
|
|
150
|
+
issuer_address,
|
|
151
|
+
signal_id,
|
|
152
|
+
];
|
|
153
|
+
}
|
|
154
|
+
export function encodeTrustSignalEnvelope(envelope) {
|
|
155
|
+
return new Uint8Array(encodeCbor(toPreimage(envelope)));
|
|
156
|
+
}
|
|
157
|
+
export function hashTrustSignalEnvelope(envelope) {
|
|
158
|
+
return sha256(encodeTrustSignalEnvelope(envelope));
|
|
159
|
+
}
|
|
160
|
+
export function verifyTrustSignalHash(envelope, expected) {
|
|
161
|
+
if (!(expected instanceof Uint8Array) || expected.length !== SIGNAL_HASH_BYTES)
|
|
162
|
+
return false;
|
|
163
|
+
const actual = hashTrustSignalEnvelope(envelope);
|
|
164
|
+
let diff = 0;
|
|
165
|
+
for (let i = 0; i < actual.length; i++)
|
|
166
|
+
diff |= actual[i] ^ expected[i];
|
|
167
|
+
return diff === 0;
|
|
168
|
+
}
|
|
169
|
+
export function decodeTrustSignalEnvelope(bytes) {
|
|
170
|
+
if (bytes.length > MAX_SIGNAL_BYTES)
|
|
171
|
+
throw new RangeError(`trust-signal envelope can't be over ${MAX_SIGNAL_BYTES} bytes`);
|
|
172
|
+
assertFlat(bytes, ENVELOPE_ARITY, { booleans: true });
|
|
173
|
+
const arr = decodeCbor(bytes);
|
|
174
|
+
const [domain, subject_kind, subject, issuer_kind, issuer_pubkey, type, schema_version, payload, issued_at, expires_at, supersedes_hash, same_operator, issuer_address, signal_id] = arr;
|
|
175
|
+
if (domain !== TRUST_SIGNAL_DOMAIN) {
|
|
176
|
+
throw new UnknownFormat(`trust-signal envelope domain tag is '${String(domain)}', expected '${TRUST_SIGNAL_DOMAIN}' — not a trust-signal envelope`);
|
|
177
|
+
}
|
|
178
|
+
const asBytes = (v, field) => {
|
|
179
|
+
if (v instanceof Uint8Array)
|
|
180
|
+
return new Uint8Array(v);
|
|
181
|
+
throw new Error(`trust-signal envelope: ${field} must be raw bytes, got ${v === null ? "null" : typeof v}`);
|
|
182
|
+
};
|
|
183
|
+
const env = {
|
|
184
|
+
subject_kind: subject_kind,
|
|
185
|
+
subject: subject,
|
|
186
|
+
issuer_kind: issuer_kind,
|
|
187
|
+
issuer_pubkey: issuer_pubkey,
|
|
188
|
+
type: type,
|
|
189
|
+
schema_version: Number(schema_version),
|
|
190
|
+
payload: asBytes(payload, "payload"),
|
|
191
|
+
issued_at: Number(issued_at),
|
|
192
|
+
expires_at: expires_at === null || expires_at === undefined ? null : Number(expires_at),
|
|
193
|
+
supersedes_hash: supersedes_hash === null || supersedes_hash === undefined ? null : asBytes(supersedes_hash, "supersedes_hash"),
|
|
194
|
+
same_operator: same_operator === true,
|
|
195
|
+
issuer_address: issuer_address,
|
|
196
|
+
signal_id: asBytes(signal_id, "signal_id"),
|
|
197
|
+
};
|
|
198
|
+
const reencoded = encodeTrustSignalEnvelope(env);
|
|
199
|
+
if (reencoded.length !== bytes.length) {
|
|
200
|
+
throw new Error("trust-signal envelope bytes are not canonical — re-encoding does not reproduce the input");
|
|
201
|
+
}
|
|
202
|
+
for (let i = 0; i < reencoded.length; i++) {
|
|
203
|
+
if (reencoded[i] !== bytes[i]) {
|
|
204
|
+
throw new Error("trust-signal envelope bytes are not canonical — re-encoding does not reproduce the input");
|
|
205
|
+
}
|
|
206
|
+
}
|
|
207
|
+
return env;
|
|
208
|
+
}
|
|
209
|
+
export function issuerPubkeyField(pub) {
|
|
210
|
+
return toHex(pub.ed) + toHex(pub.pq);
|
|
211
|
+
}
|
|
212
|
+
export function issuerKeys(envelope) {
|
|
213
|
+
const all = Buffer.from(envelope.issuer_pubkey, "hex");
|
|
214
|
+
return { ed: new Uint8Array(all.subarray(0, ED25519_PUBLIC_KEY_BYTES)), pq: new Uint8Array(all.subarray(ED25519_PUBLIC_KEY_BYTES)) };
|
|
215
|
+
}
|
|
216
|
+
// The file a signal travels as. The envelope stays bytes in a slot, so signature and hash cover it exactly as received.
|
|
217
|
+
export async function signSignal(envelope, signer) {
|
|
218
|
+
if (envelope.issuer_pubkey !== issuerPubkeyField(signer.publicIdentity))
|
|
219
|
+
throw new Error("this signer's keys aren't the ones the signal names as its issuer");
|
|
220
|
+
const bytes = encodeTrustSignalEnvelope(envelope);
|
|
221
|
+
const signature = await signer.sign("cello-signal", bytes);
|
|
222
|
+
const file = new Uint8Array(encodeCbor([SIGNED_SIGNAL_DOMAIN, bytes, signature.ed, signature.pq]));
|
|
223
|
+
if (file.length > MAX_SIGNAL_BYTES)
|
|
224
|
+
throw new RangeError(`a signal can't be over ${MAX_SIGNAL_BYTES} bytes`);
|
|
225
|
+
return file;
|
|
226
|
+
}
|
|
227
|
+
export function readSignedSignal(file) {
|
|
228
|
+
if (file.length > MAX_SIGNAL_BYTES)
|
|
229
|
+
throw new RangeError(`a signal can't be over ${MAX_SIGNAL_BYTES} bytes`);
|
|
230
|
+
assertFlat(file, SIGNED_ARITY);
|
|
231
|
+
const [domain, envelopeBytes, ed, pq] = decodeCbor(file);
|
|
232
|
+
if (domain !== SIGNED_SIGNAL_DOMAIN)
|
|
233
|
+
throw new UnknownFormat(`this is ${typeof domain === "string" ? domain.slice(0, 64) : "unnamed"}, and ${SIGNED_SIGNAL_DOMAIN} was expected`);
|
|
234
|
+
if (!(envelopeBytes instanceof Uint8Array) || !(ed instanceof Uint8Array) || !(pq instanceof Uint8Array) || ed.length !== ED25519_SIGNATURE_BYTES || pq.length !== ML_DSA_SIGNATURE_BYTES) {
|
|
235
|
+
throw new RangeError("a signal needs an envelope and both issuer signatures");
|
|
236
|
+
}
|
|
237
|
+
const held = new Uint8Array(envelopeBytes);
|
|
238
|
+
const envelope = decodeTrustSignalEnvelope(held);
|
|
239
|
+
const reencoded = new Uint8Array(encodeCbor([SIGNED_SIGNAL_DOMAIN, held, new Uint8Array(ed), new Uint8Array(pq)]));
|
|
240
|
+
if (!equalBytes(reencoded, file))
|
|
241
|
+
throw new RangeError("this signal's bytes aren't canonical");
|
|
242
|
+
return { envelope, envelopeBytes: held, signature: { ed: new Uint8Array(ed), pq: new Uint8Array(pq) }, hash: sha256(held) };
|
|
243
|
+
}
|
|
244
|
+
// For daemon, server and reader alike. Whether the issuer counts is a separate question: see issuer-list.ts.
|
|
245
|
+
export async function checkSignal(file, expected) {
|
|
246
|
+
let signal;
|
|
247
|
+
try {
|
|
248
|
+
signal = readSignedSignal(file);
|
|
249
|
+
}
|
|
250
|
+
catch (err) {
|
|
251
|
+
const message = err instanceof Error ? err.message : String(err);
|
|
252
|
+
if (err instanceof UnknownFormat)
|
|
253
|
+
return { ok: false, fault: "unknown_format", message };
|
|
254
|
+
if (err instanceof ExpiryTooLong)
|
|
255
|
+
return { ok: false, fault: "expiry_too_long", message };
|
|
256
|
+
return { ok: false, fault: "malformed", message };
|
|
257
|
+
}
|
|
258
|
+
const keys = issuerKeys(signal.envelope);
|
|
259
|
+
if (!(await verifySignature(keys, "cello-signal", signal.envelopeBytes, signal.signature)))
|
|
260
|
+
return { ok: false, fault: "forged", message: "the issuer's signatures don't verify over this signal" };
|
|
261
|
+
if (signal.envelope.subject !== expected.subject)
|
|
262
|
+
return { ok: false, fault: "wrong_subject", message: `this signal names ${signal.envelope.subject}, not ${expected.subject}` };
|
|
263
|
+
if (signal.envelope.expires_at !== null && signal.envelope.expires_at <= expected.now)
|
|
264
|
+
return { ok: false, fault: "expired", message: `this signal expired at ${signal.envelope.expires_at}` };
|
|
265
|
+
return { ok: true, signal, issuerId: identityId(keys) };
|
|
266
|
+
}
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
import { type PublicIdentity } from "./identity.ts";
|
|
2
|
+
import { AgentStatus, StatusIssuer, StatusReason, type StatusStatementFields } from "./structures.ts";
|
|
3
|
+
import { type WireSigned } from "./wire.ts";
|
|
4
|
+
export declare const STATUS_DOMAIN = "cello-agent-status";
|
|
5
|
+
export declare const STATUS_WITNESS_DOMAIN = "cello-agent-status-witness";
|
|
6
|
+
export declare const STATUS_MAX_FUTURE_MS: number;
|
|
7
|
+
export type StatusName = keyof typeof AgentStatus;
|
|
8
|
+
export type ReasonName = keyof typeof StatusReason;
|
|
9
|
+
export type IssuerName = keyof typeof StatusIssuer;
|
|
10
|
+
export declare const statusName: (value: number) => StatusName;
|
|
11
|
+
export declare const reasonName: (value: number) => ReasonName;
|
|
12
|
+
export declare const issuerName: (value: number) => IssuerName;
|
|
13
|
+
export interface StatusRecordOnWire {
|
|
14
|
+
statement: WireSigned;
|
|
15
|
+
issuerKeys: Record<string, string | number>;
|
|
16
|
+
witness: WireSigned;
|
|
17
|
+
}
|
|
18
|
+
export type StatusFault = "agent_retired" | "status_not_allowed" | "status_stale";
|
|
19
|
+
export declare function statusChangeFault(current: {
|
|
20
|
+
status: number;
|
|
21
|
+
issuedAt: number;
|
|
22
|
+
} | undefined, next: StatusStatementFields, now: number): {
|
|
23
|
+
fault: StatusFault;
|
|
24
|
+
message: string;
|
|
25
|
+
} | null;
|
|
26
|
+
export interface StatusLogLine {
|
|
27
|
+
seq: number;
|
|
28
|
+
status: StatusName;
|
|
29
|
+
reason: ReasonName;
|
|
30
|
+
issuer: IssuerName;
|
|
31
|
+
issuer_id: string;
|
|
32
|
+
issued_at: string;
|
|
33
|
+
witnessed_at: string;
|
|
34
|
+
}
|
|
35
|
+
export declare function checkStatusLog(records: readonly StatusRecordOnWire[], agentId: Uint8Array, server: PublicIdentity): Promise<{
|
|
36
|
+
ok: true;
|
|
37
|
+
log: StatusLogLine[];
|
|
38
|
+
} | {
|
|
39
|
+
ok: false;
|
|
40
|
+
message: string;
|
|
41
|
+
}>;
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
// An agent's status: the rules for changing it, and the check a later reader runs on its log.
|
|
2
|
+
import { ZERO_HASH, equalBytes } from "./encode.js";
|
|
3
|
+
import { identityId, verifySignature } from "./identity.js";
|
|
4
|
+
import { AgentStatus, StatusIssuer, StatusReason, structureHash } from "./structures.js";
|
|
5
|
+
import { identityCodec, signedStatusStatement, signedStatusWitness } from "./wire.js";
|
|
6
|
+
export const STATUS_DOMAIN = "cello-agent-status";
|
|
7
|
+
export const STATUS_WITNESS_DOMAIN = "cello-agent-status-witness";
|
|
8
|
+
// A statement dated further ahead than this could block every later one, so it's refused.
|
|
9
|
+
export const STATUS_MAX_FUTURE_MS = 5 * 60 * 1000;
|
|
10
|
+
function nameOf(table, value) {
|
|
11
|
+
const found = Object.entries(table).find(([, v]) => v === value);
|
|
12
|
+
if (!found)
|
|
13
|
+
throw new RangeError(`unknown value ${value}`);
|
|
14
|
+
return found[0];
|
|
15
|
+
}
|
|
16
|
+
export const statusName = (value) => nameOf(AgentStatus, value);
|
|
17
|
+
export const reasonName = (value) => nameOf(StatusReason, value);
|
|
18
|
+
export const issuerName = (value) => nameOf(StatusIssuer, value);
|
|
19
|
+
// Retired is final. An agent's own keys can stop it but never restart it, or a thief holding them could undo a suspension.
|
|
20
|
+
export function statusChangeFault(current, next, now) {
|
|
21
|
+
if (current?.status === AgentStatus.retired)
|
|
22
|
+
return { fault: "agent_retired", message: "this agent is retired, and that can't be changed" };
|
|
23
|
+
if (next.status === AgentStatus.active && next.issuer === StatusIssuer.agent)
|
|
24
|
+
return { fault: "status_not_allowed", message: "an agent's own keys can't lift a suspension, because a thief holds them too" };
|
|
25
|
+
if (next.issuedAt > now + STATUS_MAX_FUTURE_MS)
|
|
26
|
+
return { fault: "status_stale", message: "this statement is dated in the future" };
|
|
27
|
+
if (current && next.issuedAt <= current.issuedAt)
|
|
28
|
+
return { fault: "status_stale", message: "this statement is older than the one already in force" };
|
|
29
|
+
return null;
|
|
30
|
+
}
|
|
31
|
+
// Checks every signature and link, using only public keys. It can't show a server hasn't left off the newest records.
|
|
32
|
+
export async function checkStatusLog(records, agentId, server) {
|
|
33
|
+
const serverId = identityId(server);
|
|
34
|
+
const log = [];
|
|
35
|
+
let prev = ZERO_HASH;
|
|
36
|
+
for (const [i, raw] of records.entries()) {
|
|
37
|
+
const seq = i + 1;
|
|
38
|
+
const fail = (message) => ({ ok: false, message: `record ${seq}: ${message}` });
|
|
39
|
+
const statement = signedStatusStatement.decode(raw.statement, "statement");
|
|
40
|
+
const witness = signedStatusWitness.decode(raw.witness, "witness");
|
|
41
|
+
const keys = identityCodec.decode(raw.issuerKeys, "issuerKeys");
|
|
42
|
+
const f = statement.fields;
|
|
43
|
+
const { bytes } = statement;
|
|
44
|
+
if (!equalBytes(f.agentId, agentId) || !equalBytes(witness.fields.agentId, agentId))
|
|
45
|
+
return fail("it's about another agent");
|
|
46
|
+
if (!equalBytes(identityId(keys), f.issuerId))
|
|
47
|
+
return fail("the keys carried aren't the issuer's");
|
|
48
|
+
if (f.issuer === StatusIssuer.agent && !equalBytes(f.issuerId, agentId))
|
|
49
|
+
return fail("it says the agent signed it, and names other keys");
|
|
50
|
+
if (f.issuer === StatusIssuer.server && !equalBytes(f.issuerId, serverId))
|
|
51
|
+
return fail("it says this server signed it, and names other keys");
|
|
52
|
+
if (!(await verifySignature(keys, STATUS_DOMAIN, bytes, statement.signature)))
|
|
53
|
+
return fail("the statement's signature doesn't verify");
|
|
54
|
+
const w = witness.fields;
|
|
55
|
+
if (!equalBytes(w.serverId, serverId) || w.seq !== seq || !equalBytes(w.prevHash, prev) || !equalBytes(w.statementHash, structureHash(bytes)))
|
|
56
|
+
return fail("the log's links don't hold");
|
|
57
|
+
const witnessBytes = witness.bytes;
|
|
58
|
+
if (!(await verifySignature(server, STATUS_WITNESS_DOMAIN, witnessBytes, witness.signature)))
|
|
59
|
+
return fail("the server's signature doesn't verify");
|
|
60
|
+
prev = structureHash(witnessBytes);
|
|
61
|
+
log.push({ seq, status: statusName(f.status), reason: reasonName(f.reason), issuer: issuerName(f.issuer), issuer_id: Buffer.from(f.issuerId).toString("hex"), issued_at: new Date(f.issuedAt).toISOString(), witnessed_at: new Date(w.time).toISOString() });
|
|
62
|
+
}
|
|
63
|
+
return { ok: true, log };
|
|
64
|
+
}
|