@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.
Files changed (234) hide show
  1. package/.claude-plugin/marketplace.json +15 -0
  2. package/README.md +107 -0
  3. package/dist/cli.d.ts +2 -0
  4. package/dist/cli.js +564 -0
  5. package/dist/daemon/account-page-assets.d.ts +4 -0
  6. package/dist/daemon/account-page-assets.js +160 -0
  7. package/dist/daemon/account-page.d.ts +14 -0
  8. package/dist/daemon/account-page.js +104 -0
  9. package/dist/daemon/address.d.ts +10 -0
  10. package/dist/daemon/address.js +34 -0
  11. package/dist/daemon/away.d.ts +31 -0
  12. package/dist/daemon/away.js +65 -0
  13. package/dist/daemon/channel-store.d.ts +112 -0
  14. package/dist/daemon/channel-store.js +284 -0
  15. package/dist/daemon/channels.d.ts +46 -0
  16. package/dist/daemon/channels.js +1049 -0
  17. package/dist/daemon/contacts.d.ts +26 -0
  18. package/dist/daemon/contacts.js +74 -0
  19. package/dist/daemon/engine.d.ts +80 -0
  20. package/dist/daemon/engine.js +2882 -0
  21. package/dist/daemon/errors.d.ts +5 -0
  22. package/dist/daemon/errors.js +16 -0
  23. package/dist/daemon/governance.d.ts +66 -0
  24. package/dist/daemon/governance.js +514 -0
  25. package/dist/daemon/guards.d.ts +36 -0
  26. package/dist/daemon/guards.js +140 -0
  27. package/dist/daemon/issuer-client.d.ts +56 -0
  28. package/dist/daemon/issuer-client.js +143 -0
  29. package/dist/daemon/link.d.ts +30 -0
  30. package/dist/daemon/link.js +191 -0
  31. package/dist/daemon/log.d.ts +1 -0
  32. package/dist/daemon/log.js +4 -0
  33. package/dist/daemon/main.d.ts +1 -0
  34. package/dist/daemon/main.js +511 -0
  35. package/dist/daemon/paths.d.ts +6 -0
  36. package/dist/daemon/paths.js +21 -0
  37. package/dist/daemon/pii.d.ts +24 -0
  38. package/dist/daemon/pii.js +146 -0
  39. package/dist/daemon/policy-cadence.d.ts +33 -0
  40. package/dist/daemon/policy-cadence.js +59 -0
  41. package/dist/daemon/policy-proposals.d.ts +41 -0
  42. package/dist/daemon/policy-proposals.js +83 -0
  43. package/dist/daemon/policy-store.d.ts +47 -0
  44. package/dist/daemon/policy-store.js +144 -0
  45. package/dist/daemon/presented.d.ts +36 -0
  46. package/dist/daemon/presented.js +94 -0
  47. package/dist/daemon/rate-limit.d.ts +17 -0
  48. package/dist/daemon/rate-limit.js +44 -0
  49. package/dist/daemon/reach.d.ts +63 -0
  50. package/dist/daemon/reach.js +207 -0
  51. package/dist/daemon/screening.d.ts +97 -0
  52. package/dist/daemon/screening.js +362 -0
  53. package/dist/daemon/settings.d.ts +125 -0
  54. package/dist/daemon/settings.js +73 -0
  55. package/dist/daemon/signal-rules.d.ts +55 -0
  56. package/dist/daemon/signal-rules.js +127 -0
  57. package/dist/daemon/signal-store.d.ts +53 -0
  58. package/dist/daemon/signal-store.js +114 -0
  59. package/dist/daemon/store.d.ts +188 -0
  60. package/dist/daemon/store.js +474 -0
  61. package/dist/daemon/tiers.d.ts +14 -0
  62. package/dist/daemon/tiers.js +9 -0
  63. package/dist/daemon/wallet.d.ts +73 -0
  64. package/dist/daemon/wallet.js +428 -0
  65. package/dist/daemon/who-label.d.ts +3 -0
  66. package/dist/daemon/who-label.js +11 -0
  67. package/dist/guidance.d.ts +39 -0
  68. package/dist/guidance.js +98 -0
  69. package/dist/hermes-bridge.d.ts +26 -0
  70. package/dist/hermes-bridge.js +180 -0
  71. package/dist/install-mcp.d.ts +6 -0
  72. package/dist/install-mcp.js +77 -0
  73. package/dist/ipc/client.d.ts +18 -0
  74. package/dist/ipc/client.js +107 -0
  75. package/dist/ipc/operations.d.ts +30 -0
  76. package/dist/ipc/operations.js +835 -0
  77. package/dist/ipc/protocol.d.ts +21 -0
  78. package/dist/ipc/protocol.js +1 -0
  79. package/dist/issuer-list-sign.d.ts +12 -0
  80. package/dist/issuer-list-sign.js +43 -0
  81. package/dist/local-operations.d.ts +2 -0
  82. package/dist/local-operations.js +73 -0
  83. package/dist/mcp-tools.d.ts +14 -0
  84. package/dist/mcp-tools.js +45 -0
  85. package/dist/mcp.d.ts +2 -0
  86. package/dist/mcp.js +155 -0
  87. package/dist/protocol/aead.d.ts +4 -0
  88. package/dist/protocol/aead.js +35 -0
  89. package/dist/protocol/cbor.d.ts +40 -0
  90. package/dist/protocol/cbor.js +106 -0
  91. package/dist/protocol/chain.d.ts +44 -0
  92. package/dist/protocol/chain.js +126 -0
  93. package/dist/protocol/channel.d.ts +153 -0
  94. package/dist/protocol/channel.js +298 -0
  95. package/dist/protocol/encode.d.ts +6 -0
  96. package/dist/protocol/encode.js +21 -0
  97. package/dist/protocol/identity.d.ts +27 -0
  98. package/dist/protocol/identity.js +94 -0
  99. package/dist/protocol/issuer-list.d.ts +56 -0
  100. package/dist/protocol/issuer-list.js +193 -0
  101. package/dist/protocol/issuer-roots.d.ts +6 -0
  102. package/dist/protocol/issuer-roots.js +10 -0
  103. package/dist/protocol/key-agreement.d.ts +20 -0
  104. package/dist/protocol/key-agreement.js +88 -0
  105. package/dist/protocol/merkle.d.ts +16 -0
  106. package/dist/protocol/merkle.js +166 -0
  107. package/dist/protocol/ml-dsa.d.ts +28 -0
  108. package/dist/protocol/ml-dsa.js +58 -0
  109. package/dist/protocol/ml-kem.d.ts +14 -0
  110. package/dist/protocol/ml-kem.js +57 -0
  111. package/dist/protocol/pq-errors.d.ts +9 -0
  112. package/dist/protocol/pq-errors.js +23 -0
  113. package/dist/protocol/pq-warnings.d.ts +1 -0
  114. package/dist/protocol/pq-warnings.js +18 -0
  115. package/dist/protocol/presented-signals.d.ts +17 -0
  116. package/dist/protocol/presented-signals.js +92 -0
  117. package/dist/protocol/salt.d.ts +5 -0
  118. package/dist/protocol/salt.js +47 -0
  119. package/dist/protocol/seal.d.ts +58 -0
  120. package/dist/protocol/seal.js +220 -0
  121. package/dist/protocol/signal.d.ts +54 -0
  122. package/dist/protocol/signal.js +266 -0
  123. package/dist/protocol/status.d.ts +41 -0
  124. package/dist/protocol/status.js +64 -0
  125. package/dist/protocol/structures.d.ts +359 -0
  126. package/dist/protocol/structures.js +296 -0
  127. package/dist/protocol/transcript.d.ts +61 -0
  128. package/dist/protocol/transcript.js +319 -0
  129. package/dist/protocol/wire.d.ts +212 -0
  130. package/dist/protocol/wire.js +161 -0
  131. package/dist/require-node.d.ts +1 -0
  132. package/dist/require-node.js +10 -0
  133. package/dist/screener/affordance.d.ts +1 -0
  134. package/dist/screener/affordance.js +2 -0
  135. package/dist/screener/classifier-selfcheck.d.ts +29 -0
  136. package/dist/screener/classifier-selfcheck.js +56 -0
  137. package/dist/screener/exfil.d.ts +11 -0
  138. package/dist/screener/exfil.js +45 -0
  139. package/dist/screener/gitleaks-rules.d.ts +9 -0
  140. package/dist/screener/gitleaks-rules.js +226 -0
  141. package/dist/screener/inbound.d.ts +25 -0
  142. package/dist/screener/inbound.js +102 -0
  143. package/dist/screener/injection-classifier-onnx.d.ts +20 -0
  144. package/dist/screener/injection-classifier-onnx.js +89 -0
  145. package/dist/screener/injection-classifier-wasm.d.ts +2 -0
  146. package/dist/screener/injection-classifier-wasm.js +97 -0
  147. package/dist/screener/injection-patterns.d.ts +8 -0
  148. package/dist/screener/injection-patterns.js +48 -0
  149. package/dist/screener/injection-windows.d.ts +9 -0
  150. package/dist/screener/injection-windows.js +37 -0
  151. package/dist/screener/language.d.ts +15 -0
  152. package/dist/screener/language.js +71 -0
  153. package/dist/screener/linear-regex.d.ts +8 -0
  154. package/dist/screener/linear-regex.js +27 -0
  155. package/dist/screener/model-installer.d.ts +14 -0
  156. package/dist/screener/model-installer.js +61 -0
  157. package/dist/screener/outbound.d.ts +19 -0
  158. package/dist/screener/outbound.js +62 -0
  159. package/dist/screener/sanitize.d.ts +44 -0
  160. package/dist/screener/sanitize.js +361 -0
  161. package/dist/screener/scan-variants.d.ts +5 -0
  162. package/dist/screener/scan-variants.js +146 -0
  163. package/dist/screener/screener-model-manifest.d.ts +16 -0
  164. package/dist/screener/screener-model-manifest.js +20 -0
  165. package/dist/screener/screener-state.d.ts +29 -0
  166. package/dist/screener/screener-state.js +119 -0
  167. package/dist/screener/secrets.d.ts +18 -0
  168. package/dist/screener/secrets.js +84 -0
  169. package/dist/screener/worker.d.ts +6 -0
  170. package/dist/screener/worker.js +83 -0
  171. package/dist/setup.d.ts +9 -0
  172. package/dist/setup.js +252 -0
  173. package/dist/shipped-issuer-list.d.ts +1 -0
  174. package/dist/shipped-issuer-list.js +3 -0
  175. package/dist/signals-text.d.ts +46 -0
  176. package/dist/signals-text.js +81 -0
  177. package/dist/verify-seal.d.ts +9 -0
  178. package/dist/verify-seal.js +30 -0
  179. package/hermes/plugin/__init__.py +1040 -0
  180. package/hermes/plugin/plugin.yaml +30 -0
  181. package/hermes/skills/cello-bridge-setup/SKILL.md +38 -0
  182. package/hermes/skills/cello-policy/SKILL.md +44 -0
  183. package/package.json +48 -16
  184. package/plugins/cello/.claude-plugin/plugin.json +19 -0
  185. package/plugins/cello/.mcp.json +7 -0
  186. package/plugins/cello/skills/cello/SKILL.md +117 -0
  187. package/dist/arg-parse.d.ts +0 -19
  188. package/dist/arg-parse.d.ts.map +0 -1
  189. package/dist/arg-parse.js +0 -29
  190. package/dist/arg-parse.js.map +0 -1
  191. package/dist/bin/cello.d.ts +0 -15
  192. package/dist/bin/cello.d.ts.map +0 -1
  193. package/dist/bin/cello.js +0 -110
  194. package/dist/bin/cello.js.map +0 -1
  195. package/dist/cli-args.d.ts +0 -62
  196. package/dist/cli-args.d.ts.map +0 -1
  197. package/dist/cli-args.js +0 -129
  198. package/dist/cli-args.js.map +0 -1
  199. package/dist/commands.d.ts +0 -196
  200. package/dist/commands.d.ts.map +0 -1
  201. package/dist/commands.js +0 -1544
  202. package/dist/commands.js.map +0 -1
  203. package/dist/hermes/assets.d.ts +0 -41
  204. package/dist/hermes/assets.d.ts.map +0 -1
  205. package/dist/hermes/assets.js +0 -2281
  206. package/dist/hermes/assets.js.map +0 -1
  207. package/dist/hermes/install-hermes.d.ts +0 -50
  208. package/dist/hermes/install-hermes.d.ts.map +0 -1
  209. package/dist/hermes/install-hermes.js +0 -232
  210. package/dist/hermes/install-hermes.js.map +0 -1
  211. package/dist/json-out.d.ts +0 -41
  212. package/dist/json-out.d.ts.map +0 -1
  213. package/dist/json-out.js +0 -59
  214. package/dist/json-out.js.map +0 -1
  215. package/dist/node-runtime-guard-init.d.ts +0 -6
  216. package/dist/node-runtime-guard-init.d.ts.map +0 -1
  217. package/dist/node-runtime-guard-init.js +0 -7
  218. package/dist/node-runtime-guard-init.js.map +0 -1
  219. package/dist/node-runtime-guard.d.ts +0 -48
  220. package/dist/node-runtime-guard.d.ts.map +0 -1
  221. package/dist/node-runtime-guard.js +0 -79
  222. package/dist/node-runtime-guard.js.map +0 -1
  223. package/dist/parity-commands.d.ts +0 -427
  224. package/dist/parity-commands.d.ts.map +0 -1
  225. package/dist/parity-commands.js +0 -953
  226. package/dist/parity-commands.js.map +0 -1
  227. package/dist/registry.d.ts +0 -120
  228. package/dist/registry.d.ts.map +0 -1
  229. package/dist/registry.js +0 -2169
  230. package/dist/registry.js.map +0 -1
  231. package/dist/screener-commands.d.ts +0 -85
  232. package/dist/screener-commands.d.ts.map +0 -1
  233. package/dist/screener-commands.js +0 -313
  234. package/dist/screener-commands.js.map +0 -1
@@ -0,0 +1,61 @@
1
+ import { type ChainFault } from "./chain.ts";
2
+ import { type SealFault, type SealRecord, type SealRecordOnWire } from "./seal.ts";
3
+ import { type WireSigned } from "./wire.ts";
4
+ export declare const TRANSCRIPT_FORMAT = "cello-transcript";
5
+ export interface TranscriptOnWire {
6
+ format: typeof TRANSCRIPT_FORMAT;
7
+ seal: SealRecordOnWire;
8
+ entries: {
9
+ entry: WireSigned;
10
+ ack: WireSigned;
11
+ }[];
12
+ salt: string;
13
+ revealed: {
14
+ position: number;
15
+ body: string;
16
+ }[];
17
+ }
18
+ export type TranscriptFault = SealFault | ChainFault | "malformed_transcript" | "truncated_chain" | "entries_beyond_seal" | "root_mismatch" | "seal_predates_entries" | "closed_without_close_entries" | "delivery_ack_off_chain" | "bad_salt" | "reveal_out_of_range" | "duplicate_reveal" | "body_does_not_match";
19
+ export type TranscriptCheck = {
20
+ ok: true;
21
+ record: SealRecord;
22
+ report: Record<string, unknown>;
23
+ } | {
24
+ ok: false;
25
+ fault: TranscriptFault;
26
+ message: string;
27
+ };
28
+ export interface ReadBody {
29
+ text: string;
30
+ signal: string | null;
31
+ estMinutes: number | null;
32
+ hasRandomValue: boolean;
33
+ }
34
+ export declare function readBody(bytes: Uint8Array): ReadBody | null;
35
+ export declare function checkTranscript(raw: unknown, sealKeyId: Uint8Array): Promise<TranscriptCheck>;
36
+ export interface HeldEntry {
37
+ position: number;
38
+ entry: WireSigned;
39
+ ack: WireSigned | null;
40
+ body: Uint8Array | null;
41
+ }
42
+ export interface TranscriptRequest {
43
+ session: string;
44
+ sealCommand: string;
45
+ entries: readonly HeldEntry[];
46
+ seals: readonly unknown[];
47
+ salt: Uint8Array | null;
48
+ reveal: string | undefined;
49
+ all: boolean;
50
+ sealId: string | undefined;
51
+ }
52
+ export type TranscriptExport = {
53
+ ok: true;
54
+ file: TranscriptOnWire;
55
+ summary: Record<string, unknown>;
56
+ } | {
57
+ ok: false;
58
+ fault: string;
59
+ message: string;
60
+ };
61
+ export declare function buildTranscript(request: TranscriptRequest): Promise<TranscriptExport>;
@@ -0,0 +1,319 @@
1
+ // A provable transcript: a seal, the signed chain it covers, and the plaintext of the positions one party chose to show.
2
+ // Anyone can check one with public keys only. It shows what was passed, never that it's true or agreed.
3
+ // Bodies travel as their exact bytes, because the signed hash is over those bytes and JSON can't be re-encoded safely.
4
+ import { ChainVerifier, witnessed } from "./chain.js";
5
+ import { equalBytes, toHex } from "./encode.js";
6
+ import { SESSION_SALT_BYTES, saltedContentHash } from "./salt.js";
7
+ import { checkSealRecord, decodeSealRecord, describeSeal, refusedPositions, readableTime, sealId, sealSummary } from "./seal.js";
8
+ import { EntryKind, readBodyBytes, structureHash } from "./structures.js";
9
+ import { fromB64, readInt, readObjectField, signedAck, signedEntry, toB64 } from "./wire.js";
10
+ export const TRANSCRIPT_FORMAT = "cello-transcript";
11
+ const CHAIN_FAULT_MESSAGES = {
12
+ wrong_session: "An entry belongs to a different session from the one this seal covers",
13
+ entry_wrong_server: "An entry's author named a different server to witness it",
14
+ not_participant: "An entry's author isn't one of this session's two parties",
15
+ bad_entry_signature: "An entry wasn't signed by its author",
16
+ entry_after_close: "An author's entry comes after that author had closed",
17
+ entry_expired: "An entry was witnessed after its author's send window had passed, which a server must refuse",
18
+ ack_time_backwards: "An entry's witnessed time is earlier than the entry before it",
19
+ bad_author_seq: "An author's entries are out of sequence, so one is missing or repeated",
20
+ bad_author_chain: "An entry doesn't follow its author's previous entry",
21
+ read_beyond_tip: "An entry claims to have read further than the chain had reached",
22
+ bad_read_root: "An entry names a history other than this one as what its author had read",
23
+ bad_position: "An entry is out of place in the order",
24
+ ack_wrong_server: "An entry's ack is from a different server from the one this seal names",
25
+ ack_wrong_session: "An entry's ack is for a different session",
26
+ ack_wrong_entry: "An entry isn't the one its ack witnessed, so it has been changed or given a different author",
27
+ ack_wrong_root: "An entry's ack names a different history",
28
+ bad_ack_signature: "An entry's ack wasn't signed by the server",
29
+ };
30
+ function fail(fault, message) {
31
+ return { ok: false, fault, message };
32
+ }
33
+ // A field nobody checks has no place in a file people read as proof, such as a claimed author next to a body.
34
+ function onlyKeys(value, allowed, name) {
35
+ const extra = Object.keys(value).find((key) => !allowed.includes(key));
36
+ if (extra !== undefined)
37
+ throw new RangeError(`${name} has a field nothing checks: ${extra}`);
38
+ }
39
+ function readList(value, name) {
40
+ if (!Array.isArray(value))
41
+ throw new RangeError(`${name} isn't a list`);
42
+ return value;
43
+ }
44
+ function decodeTranscript(raw) {
45
+ const value = readObjectField(raw, "transcript");
46
+ if (value["format"] !== TRANSCRIPT_FORMAT)
47
+ throw new RangeError(`this isn't a ${TRANSCRIPT_FORMAT} file`);
48
+ onlyKeys(value, ["format", "seal", "entries", "salt", "revealed"], "the file");
49
+ return {
50
+ seal: value["seal"],
51
+ items: readList(value["entries"], "entries").map((item, i) => {
52
+ const fields = readObjectField(item, `entries[${i}]`);
53
+ onlyKeys(fields, ["entry", "ack"], `entries[${i}]`);
54
+ const entry = signedEntry.decode(fields["entry"], `entries[${i}].entry`);
55
+ const ack = signedAck.decode(fields["ack"], `entries[${i}].ack`);
56
+ return witnessed(entry, ack);
57
+ }),
58
+ salt: fromB64(value["salt"], "salt"),
59
+ revealed: readList(value["revealed"], "revealed").map((item, i) => {
60
+ const fields = readObjectField(item, `revealed[${i}]`);
61
+ onlyKeys(fields, ["position", "body"], `revealed[${i}]`);
62
+ return { position: readInt(fields["position"], `revealed[${i}].position`), body: fromB64(fields["body"], `revealed[${i}].body`) };
63
+ }),
64
+ };
65
+ }
66
+ const RANDOM_VALUE_BYTES = 16;
67
+ // Null for anything that isn't exactly what a CELLO client writes.
68
+ export function readBody(bytes) {
69
+ const body = readBodyBytes(bytes);
70
+ if (!body)
71
+ return null;
72
+ return { text: body.text, signal: body.signal, estMinutes: body.est_minutes, hasRandomValue: body.n.length >= RANDOM_VALUE_BYTES };
73
+ }
74
+ // "1-3, 5", so a statement stays readable however long the conversation.
75
+ function listPositions(positions) {
76
+ const parts = [];
77
+ let i = 0;
78
+ while (i < positions.length) {
79
+ let last = i;
80
+ while (positions[last + 1] === positions[last] + 1)
81
+ last++;
82
+ parts.push(last === i ? `${positions[i]}` : `${positions[i]}-${positions[last]}`);
83
+ i = last + 1;
84
+ }
85
+ return parts.join(", ");
86
+ }
87
+ function describeMessage(item, body, record) {
88
+ const cert = record.certificate.fields;
89
+ const closing = item.fields.kind === EntryKind.close;
90
+ const read = readBody(body);
91
+ const words = !read
92
+ ? { unreadable: true, body_base64url: toB64(body) }
93
+ // A client never shows a close's text to its agent, so text here wasn't passed in the usual way, and it's marked.
94
+ : closing
95
+ ? (read.text ? { text_on_a_close: read.text } : {})
96
+ : { text: read.text, signal: read.signal, ...(read.estMinutes !== null ? { est_minutes: read.estMinutes } : {}) };
97
+ return {
98
+ position: item.ack.position,
99
+ author: equalBytes(item.fields.authorId, cert.sealerId) ? "sealer" : "counterparty",
100
+ author_id: toHex(item.fields.authorId),
101
+ kind: closing ? "close" : "message",
102
+ ...words,
103
+ author_had_read_through: item.fields.readPosition,
104
+ witnessed_at: readableTime(item.ack.time),
105
+ basis: refusedPositions(record).includes(item.ack.position) ? "refused_by_counterparty" : item.ack.position <= cert.receivedThrough ? "counterparty_signature" : "sender_signature_and_server",
106
+ };
107
+ }
108
+ // What this file shows and doesn't, for a person to read. Neutral on agreement and truth, always.
109
+ function describeTranscript(record, items, revealed, hidden) {
110
+ const cert = record.certificate.fields;
111
+ const m = cert.receivedThrough;
112
+ const authorOf = (position) => items[position - 1].fields.authorId;
113
+ const refused = refusedPositions(record);
114
+ const bound = revealed.filter((p) => p <= m && !refused.includes(p));
115
+ const beyond = revealed.filter((p) => p > m);
116
+ const fromSealer = beyond.filter((p) => equalBytes(authorOf(p), cert.sealerId));
117
+ const fromCounterparty = beyond.filter((p) => !equalBytes(authorOf(p), cert.sealerId));
118
+ const more = cert.tip - cert.throughPosition;
119
+ const missing = [
120
+ ...(hidden.length > 0 ? [`Positions ${listPositions(hidden)} are hidden. Their signed hashes are in the chain, so they exist and can't be altered unseen, but this file doesn't show what they said.`] : []),
121
+ ...(more > 0 ? [`The server says ${more} more position${more === 1 ? "" : "s"} came after what this seal covers, and this file shows nothing of them.`] : []),
122
+ ...(cert.closed === 1 ? [] : ["The server says the session hadn't closed when this was sealed, so more may have followed."]),
123
+ ];
124
+ // The seal's own statement says it shows nothing of what was said, which isn't so for this file.
125
+ const seal = Object.fromEntries(Object.entries(describeSeal(record)).filter(([key]) => key !== "contents"));
126
+ return {
127
+ meaning: "These are messages that were passed between these two keys. This says nothing about whether they're true, or whether either party agreed.",
128
+ bound_by_the_counterparty_signature: bound.length > 0
129
+ ? `Positions ${listPositions(bound)}: each body matches its signed entry, and the counterparty's own signature says its machine stored and decrypted everything through position ${m}, in this order, except anything listed as refused. That rests on its key, not on the server. Received means stored and decrypted, not read.`
130
+ : "No revealed position is covered by the counterparty's signature.",
131
+ rests_on_the_sender_and_the_server: [
132
+ ...(fromCounterparty.length > 0 ? [`Positions ${listPositions(fromCounterparty)}: the counterparty's signature on the entry stands behind the words. Their place in the order rests on the server.`] : []),
133
+ ...(fromSealer.length > 0 ? [`Positions ${listPositions(fromSealer)}: only the signature of the person who made this file and the server's word stand behind these. Nothing shows the counterparty ever received them.`] : []),
134
+ ...(beyond.length === 0 ? ["No revealed position rests on these alone. The times shown still rest on the server."] : ["The times shown rest on the server."]),
135
+ ].join(" "),
136
+ refused_by_the_counterparty: refused.length > 0
137
+ ? `Positions ${listPositions(refused)}: the counterparty signed that the text it got isn't what the author signed. A body shown here may match the signed hash, and nothing shows the counterparty ever held it.`
138
+ : "The counterparty's signature refuses no position.",
139
+ who_chose: `This file comes from one party, the sealer ${toHex(cert.sealerId)}, who chose what to reveal. The other party may hold its own copy.`,
140
+ hidden: missing.length > 0
141
+ ? `${missing.join(" ")} What isn't shown may change the meaning: "Bob offers $1M" can be followed by a hidden "Bob withdraws".`
142
+ : "Nothing is hidden: every position in this session is revealed.",
143
+ how_bodies_were_checked: "Each revealed body was hashed with the session salt and matched against its author's signed entry. Nothing signs the salt itself, and it needs nothing to: finding another salt or body that gives the same hash would mean breaking SHA-256.",
144
+ ciphertext: "This file holds no ciphertext or key, so each entry's signed ciphertext hash isn't checked here. It's carried unchanged, because the entry's signature covers it. Only a recipient's machine can check it. It does that before signing a delivery ack, which is why the counterparty's signature means more than the sender's.",
145
+ seal,
146
+ };
147
+ }
148
+ async function findTranscript(decoded, record) {
149
+ const cert = record.certificate.fields;
150
+ const n = cert.throughPosition;
151
+ const { items, salt } = decoded;
152
+ if (items.length < n)
153
+ return fail("truncated_chain", `This seal covers ${n} positions, and the file holds only ${items.length}`);
154
+ if (items.length > n)
155
+ return fail("entries_beyond_seal", `This seal covers ${n} positions, and the file holds ${items.length}, so some of them no seal stands behind`);
156
+ const verifier = new ChainVerifier({ sessionId: cert.sessionId, server: record.server, participants: [record.sealer, record.counterparty] });
157
+ for (const item of items) {
158
+ const fault = await verifier.check(item);
159
+ if (fault)
160
+ return fail(fault, `${CHAIN_FAULT_MESSAGES[fault]}: at place ${verifier.position + 1} in the file`);
161
+ }
162
+ if (!equalBytes(verifier.root, cert.root))
163
+ return fail("root_mismatch", "This chain's root isn't the one the seal covers, so the seal is for a different history");
164
+ if (cert.time < verifier.lastAckTime)
165
+ return fail("seal_predates_entries", "This seal is dated before the messages it covers");
166
+ // Past N, the close entries aren't in this file. Where the file reaches the tip, closed can be checked for free.
167
+ const bothClosed = verifier.hasClosed(cert.sealerId) && verifier.hasClosed(cert.counterpartyId);
168
+ if ((cert.closed === 1 && cert.tip === n && !bothClosed) || (cert.closed === 0 && bothClosed)) {
169
+ return fail("closed_without_close_entries", `This seal says closed=${cert.closed}, and the entries say otherwise`);
170
+ }
171
+ const ack = record.deliveryAck?.fields;
172
+ if (ack && ack.throughPosition <= n) {
173
+ const onChain = equalBytes(verifier.rootAt(ack.throughPosition), ack.root) && equalBytes(structureHash(items[ack.throughPosition - 1].bytes), ack.entryHash);
174
+ if (!onChain)
175
+ return fail("delivery_ack_off_chain", `What the counterparty signed at position ${ack.throughPosition} isn't this chain`);
176
+ }
177
+ // HMAC pads a short key with zeros, so only this exact length stops two different salts acting as one.
178
+ if (salt.length !== SESSION_SALT_BYTES)
179
+ return fail("bad_salt", `A session salt is ${SESSION_SALT_BYTES} bytes, and this one is ${salt.length}`);
180
+ const bodies = new Map();
181
+ for (const { position, body } of decoded.revealed) {
182
+ if (position < 1 || position > n)
183
+ return fail("reveal_out_of_range", `Position ${position} is revealed, and this seal covers 1 to ${n}`);
184
+ if (bodies.has(position))
185
+ return fail("duplicate_reveal", `Position ${position} is revealed twice`);
186
+ if (!equalBytes(saltedContentHash(salt, body), items[position - 1].fields.contentHash)) {
187
+ return fail("body_does_not_match", `The body given for position ${position} isn't what its author signed`);
188
+ }
189
+ bodies.set(position, body);
190
+ }
191
+ const revealed = [...bodies.keys()].sort((a, b) => a - b);
192
+ const hidden = items.map((item) => item.ack.position).filter((position) => !bodies.has(position));
193
+ return {
194
+ ok: true,
195
+ record,
196
+ report: {
197
+ ...sealSummary(record),
198
+ revealed_positions: revealed,
199
+ hidden_positions: hidden,
200
+ messages: revealed.map((position) => describeMessage(items[position - 1], bodies.get(position), record)),
201
+ statement: describeTranscript(record, items, revealed, hidden),
202
+ },
203
+ };
204
+ }
205
+ // Never throws on a bad file: every bad input is a named fault.
206
+ export async function checkTranscript(raw, sealKeyId) {
207
+ let decoded;
208
+ try {
209
+ decoded = decodeTranscript(raw);
210
+ }
211
+ catch (err) {
212
+ return fail("malformed_transcript", `This file isn't a readable transcript: ${err instanceof Error ? err.message : String(err)}`);
213
+ }
214
+ const seal = await checkSealRecord(decoded.seal, sealKeyId);
215
+ if (!seal.ok)
216
+ return seal;
217
+ return findTranscript(decoded, seal.record);
218
+ }
219
+ // Ranges, so a typed 1-99999999999 is refused for being beyond the seal rather than expanded first.
220
+ function parsePositions(text) {
221
+ if (!/^\d+(-\d+)?(,\d+(-\d+)?)*$/.test(text))
222
+ return null;
223
+ const ranges = text.split(",").map((part) => {
224
+ const [first, last] = part.split("-").map(Number);
225
+ return [first, last ?? first];
226
+ });
227
+ return ranges.every(([first, last]) => Number.isSafeInteger(last) && first >= 1 && first <= last) ? ranges : null;
228
+ }
229
+ function chooseSeal(seals, wanted) {
230
+ if (wanted !== undefined)
231
+ return seals.find((seal) => toHex(sealId(decodeSealRecord(seal).certificate.bytes)) === wanted.toLowerCase());
232
+ // Sorting one seal compares nothing, so this reads every one, and a corrupt one can't slip through unnoticed.
233
+ for (const seal of seals)
234
+ decodeSealRecord(seal);
235
+ const reach = (seal) => {
236
+ const cert = decodeSealRecord(seal).certificate.fields;
237
+ return [cert.throughPosition, cert.receivedThrough, cert.time];
238
+ };
239
+ // The furthest one, then the one the counterparty has confirmed most of, then the newest.
240
+ return [...seals].sort((a, b) => {
241
+ const [x, y] = [reach(a), reach(b)];
242
+ return (y[0] - x[0]) || (y[1] - x[1]) || (y[2] - x[2]);
243
+ })[0];
244
+ }
245
+ // Builds the file and checks it as a stranger would, so nobody is handed a file that fails in front of its reader.
246
+ export async function buildTranscript(request) {
247
+ const refuse = (fault, message) => ({ ok: false, fault, message });
248
+ const { reveal, all, entries, session, sealCommand, salt } = request;
249
+ if (all && reveal !== undefined)
250
+ return refuse("bad_argument", "Choose either reveal or all, not both");
251
+ if (!all && reveal === undefined)
252
+ return refuse("no_reveal_chosen", "Nothing is revealed by default. Name the positions to show with reveal, such as 1,3,5-7, or show everything with all");
253
+ const ranges = reveal === undefined ? null : parsePositions(reveal);
254
+ if (reveal !== undefined && !ranges)
255
+ return refuse("bad_argument", `reveal must be positions such as 1,3,5-7, and "${reveal}" isn't`);
256
+ let seal;
257
+ try {
258
+ seal = chooseSeal(request.seals, request.sealId);
259
+ }
260
+ catch (err) {
261
+ return refuse("stored_seal_unreadable", `A seal this agent holds for this session can't be read: ${err instanceof Error ? err.message : String(err)}`);
262
+ }
263
+ if (request.sealId !== undefined && !seal)
264
+ return refuse("unknown_seal", "This agent holds no seal with that id for this session");
265
+ const held = entries.at(-1)?.position ?? 0;
266
+ const seek = `Run: ${sealCommand}`;
267
+ if (!seal)
268
+ return refuse("no_seal_covers", `This agent holds no seal for session ${session}, and a transcript needs one. ${seek}`);
269
+ const n = decodeSealRecord(seal).certificate.fields.throughPosition;
270
+ const highest = ranges ? Math.max(...ranges.map(([, last]) => last)) : request.sealId === undefined ? held : n;
271
+ if (highest > n)
272
+ return refuse("no_seal_covers", `The seal covers positions 1 to ${n}, and this needs position ${highest}. ${seek}`);
273
+ const covered = entries.filter((row) => row.position <= n);
274
+ if (covered.length !== n || covered.some((row, i) => row.position !== i + 1 || !row.ack))
275
+ return refuse("record_incomplete", `This agent's record doesn't hold every position from 1 to ${n}, so it can't be exported`);
276
+ if (!salt)
277
+ return refuse("salt_missing", "This agent's record doesn't hold the session's salt, so no message can be shown to match its hash");
278
+ const shown = new Set();
279
+ for (const [first, last] of ranges ?? [[1, n]])
280
+ for (let p = first; p <= last; p++)
281
+ shown.add(p);
282
+ const notKept = covered.filter((row) => row.body === null).map((row) => row.position);
283
+ const askedNotKept = ranges ? notKept.filter((p) => shown.has(p)) : [];
284
+ if (askedNotKept.length > 0)
285
+ return refuse("body_not_kept", `Positions ${listPositions(askedNotKept)} arrived past this conversation's byte limit, so their words were never kept and can't be shown. Nothing was written.`);
286
+ // The salt goes in the file, and it's the same one for the whole session. Only each body's random value still protects a hidden one.
287
+ // Words not kept can't be checked for one. They're the sender's own, sent past a limit, and nobody here read them.
288
+ const guessable = covered.filter((row) => row.body !== null && !shown.has(row.position) && !readBody(row.body)?.hasRandomValue).map((row) => row.position);
289
+ if (guessable.length > 0) {
290
+ return refuse("hidden_body_guessable", `Positions ${listPositions(guessable)} have no random value in them, because the other party's software didn't add one. With the salt in this file, anyone could test guesses about what they say. Nothing was written. Reveal those positions too if you're content to show them.`);
291
+ }
292
+ const file = {
293
+ format: TRANSCRIPT_FORMAT,
294
+ seal,
295
+ entries: covered.map((row) => ({ entry: row.entry, ack: row.ack })),
296
+ salt: toB64(salt),
297
+ revealed: covered.flatMap((row) => (row.body !== null && shown.has(row.position) ? [{ position: row.position, body: toB64(row.body) }] : [])),
298
+ };
299
+ const cert = decodeSealRecord(seal).certificate.fields;
300
+ const check = await checkTranscript(file, cert.sealKeyId);
301
+ if (!check.ok)
302
+ return refuse("export_failed_own_check", `This agent's record doesn't pass the check a reader would run, so nothing was written. ${check.fault}: ${check.message}`);
303
+ const revealedPositions = file.revealed.map((row) => row.position);
304
+ return {
305
+ ok: true,
306
+ file,
307
+ summary: {
308
+ session_id: toHex(cert.sessionId),
309
+ seal_id: toHex(sealId(decodeSealRecord(seal).certificate.bytes)),
310
+ seal_key: toHex(cert.sealKeyId),
311
+ witnessed_through: n,
312
+ received_through: cert.receivedThrough,
313
+ revealed_positions: revealedPositions,
314
+ hidden_positions: check.report["hidden_positions"],
315
+ not_kept_positions: notKept,
316
+ warning: `This file holds the plaintext of positions ${listPositions(revealedPositions)}. Anyone you give it to can read them. It also holds the session's salt.`,
317
+ },
318
+ };
319
+ }
@@ -0,0 +1,212 @@
1
+ import type { DualSignature, PublicIdentity } from "./identity.ts";
2
+ import { type Structure } from "./structures.ts";
3
+ export declare const PROTOCOL_VERSION = 1;
4
+ export declare const MAX_CIPHERTEXT_BYTES = 1100000;
5
+ export declare const MAX_FRAME_BYTES = 2000000;
6
+ export declare const LONG_CIPHERTEXT_BYTES = 8000;
7
+ export declare const ERROR_CODES: readonly ["bad_request", "unsupported_version", "not_authenticated", "bad_signature", "agent_already_connected", "unknown_agent", "unknown_session", "not_participant", "wrong_session_state", "offer_expired", "session_conflict", "session_closed", "not_current", "entry_expired", "bad_chain", "bad_read_position", "bad_ciphertext", "too_large", "nothing_to_seal", "seal_beyond_tip", "seal_root_mismatch", "seal_log_inconsistent", "unknown_channel", "channel_conflict", "not_a_member", "not_allowed_to_post", "generation_stale", "post_conflict", "replayed_post", "over_quota", "ejected", "bad_roster", "rate_limited", "federation_closed", "too_many_pending", "visitor_budget_spent", "agent_suspended", "agent_retired", "agent_unavailable", "conversation_stopped", "status_not_allowed", "status_stale", "signal_required", "signal_malformed", "signal_unknown_format", "signal_expiry_too_long", "signal_forged", "signal_wrong_subject", "signal_expired", "signal_not_email", "signal_not_from_issuer", "issuer_unknown", "issuer_list_not_configured", "issuer_list_expired", "issuer_list_invalid", "internal_error"];
8
+ export type ErrorCode = (typeof ERROR_CODES)[number];
9
+ export declare class WireError extends Error {
10
+ readonly code: ErrorCode;
11
+ constructor(code: ErrorCode, message: string);
12
+ }
13
+ export declare function toB64(bytes: Uint8Array): string;
14
+ export declare function fromB64(value: unknown, name: string): Uint8Array;
15
+ export declare function readInt(value: unknown, name: string): number;
16
+ export declare function readString(value: unknown, name: string): string;
17
+ type FieldKind = "bytes" | "int";
18
+ export interface Codec<T> {
19
+ encode(value: T): Record<string, string | number>;
20
+ decode(value: unknown, name?: string): T;
21
+ }
22
+ export declare function codec<T>(shape: Record<keyof T & string, FieldKind>): Codec<T>;
23
+ export declare const identityCodec: Codec<PublicIdentity>;
24
+ export declare const signatureCodec: Codec<DualSignature>;
25
+ export interface Signed<T> {
26
+ fields: T;
27
+ signature: DualSignature;
28
+ bytes: Uint8Array;
29
+ }
30
+ export interface WireSigned {
31
+ bytes: string;
32
+ signature: Record<string, string | number>;
33
+ }
34
+ export declare function readStructure<T>(structure: Structure<T>, bytes: Uint8Array, name: string): T;
35
+ export declare function signedCodec<T>(structure: Structure<T>): {
36
+ encode(value: {
37
+ fields: T;
38
+ signature: DualSignature;
39
+ bytes?: Uint8Array;
40
+ }): WireSigned;
41
+ decode(value: unknown, name?: string): Signed<T>;
42
+ };
43
+ export interface WitnessedOnWire {
44
+ entry: WireSigned;
45
+ ack: WireSigned;
46
+ ciphertext: string | null;
47
+ }
48
+ export declare const signedEntry: {
49
+ encode(value: {
50
+ fields: import("./structures.ts").EntryFields;
51
+ signature: DualSignature;
52
+ bytes?: Uint8Array;
53
+ }): WireSigned;
54
+ decode(value: unknown, name?: string): Signed<import("./structures.ts").EntryFields>;
55
+ };
56
+ export declare const signedAck: {
57
+ encode(value: {
58
+ fields: import("./structures.ts").AckFields;
59
+ signature: DualSignature;
60
+ bytes?: Uint8Array;
61
+ }): WireSigned;
62
+ decode(value: unknown, name?: string): Signed<import("./structures.ts").AckFields>;
63
+ };
64
+ export declare const signedDeliveryAck: {
65
+ encode(value: {
66
+ fields: import("./structures.ts").DeliveryAckFields;
67
+ signature: DualSignature;
68
+ bytes?: Uint8Array;
69
+ }): WireSigned;
70
+ decode(value: unknown, name?: string): Signed<import("./structures.ts").DeliveryAckFields>;
71
+ };
72
+ export declare const signedOffer: {
73
+ encode(value: {
74
+ fields: import("./structures.ts").OfferFields;
75
+ signature: DualSignature;
76
+ bytes?: Uint8Array;
77
+ }): WireSigned;
78
+ decode(value: unknown, name?: string): Signed<import("./structures.ts").OfferFields>;
79
+ };
80
+ export declare const signedAccept: {
81
+ encode(value: {
82
+ fields: import("./structures.ts").AcceptFields;
83
+ signature: DualSignature;
84
+ bytes?: Uint8Array;
85
+ }): WireSigned;
86
+ decode(value: unknown, name?: string): Signed<import("./structures.ts").AcceptFields>;
87
+ };
88
+ export declare const signedConfirm: {
89
+ encode(value: {
90
+ fields: import("./structures.ts").ConfirmFields;
91
+ signature: DualSignature;
92
+ bytes?: Uint8Array;
93
+ }): WireSigned;
94
+ decode(value: unknown, name?: string): Signed<import("./structures.ts").ConfirmFields>;
95
+ };
96
+ export declare const signedRefuse: {
97
+ encode(value: {
98
+ fields: import("./structures.ts").RefuseFields;
99
+ signature: DualSignature;
100
+ bytes?: Uint8Array;
101
+ }): WireSigned;
102
+ decode(value: unknown, name?: string): Signed<import("./structures.ts").RefuseFields>;
103
+ };
104
+ export declare const signedGreeting: {
105
+ encode(value: {
106
+ fields: import("./structures.ts").GreetingFields;
107
+ signature: DualSignature;
108
+ bytes?: Uint8Array;
109
+ }): WireSigned;
110
+ decode(value: unknown, name?: string): Signed<import("./structures.ts").GreetingFields>;
111
+ };
112
+ export declare const signedAssignment: {
113
+ encode(value: {
114
+ fields: import("./structures.ts").AssignmentFields;
115
+ signature: DualSignature;
116
+ bytes?: Uint8Array;
117
+ }): WireSigned;
118
+ decode(value: unknown, name?: string): Signed<import("./structures.ts").AssignmentFields>;
119
+ };
120
+ export declare const signedSealRequest: {
121
+ encode(value: {
122
+ fields: import("./structures.ts").SealRequestFields;
123
+ signature: DualSignature;
124
+ bytes?: Uint8Array;
125
+ }): WireSigned;
126
+ decode(value: unknown, name?: string): Signed<import("./structures.ts").SealRequestFields>;
127
+ };
128
+ export declare const signedSealCertificate: {
129
+ encode(value: {
130
+ fields: import("./structures.ts").SealCertificateFields;
131
+ signature: DualSignature;
132
+ bytes?: Uint8Array;
133
+ }): WireSigned;
134
+ decode(value: unknown, name?: string): Signed<import("./structures.ts").SealCertificateFields>;
135
+ };
136
+ export declare const signedSealLogHead: {
137
+ encode(value: {
138
+ fields: import("./structures.ts").SealLogHeadFields;
139
+ signature: DualSignature;
140
+ bytes?: Uint8Array;
141
+ }): WireSigned;
142
+ decode(value: unknown, name?: string): Signed<import("./structures.ts").SealLogHeadFields>;
143
+ };
144
+ export declare const signedStatusStatement: {
145
+ encode(value: {
146
+ fields: import("./structures.ts").StatusStatementFields;
147
+ signature: DualSignature;
148
+ bytes?: Uint8Array;
149
+ }): WireSigned;
150
+ decode(value: unknown, name?: string): Signed<import("./structures.ts").StatusStatementFields>;
151
+ };
152
+ export declare const signedStatusWitness: {
153
+ encode(value: {
154
+ fields: import("./structures.ts").StatusWitnessFields;
155
+ signature: DualSignature;
156
+ bytes?: Uint8Array;
157
+ }): WireSigned;
158
+ decode(value: unknown, name?: string): Signed<import("./structures.ts").StatusWitnessFields>;
159
+ };
160
+ export declare const signedEncryptionKey: {
161
+ encode(value: {
162
+ fields: import("./structures.ts").EncryptionKeyFields;
163
+ signature: DualSignature;
164
+ bytes?: Uint8Array;
165
+ }): WireSigned;
166
+ decode(value: unknown, name?: string): Signed<import("./structures.ts").EncryptionKeyFields>;
167
+ };
168
+ export declare const MAX_GREETING_BYTES = 400100;
169
+ export interface SessionOnWire {
170
+ offer: WireSigned;
171
+ accept: WireSigned | null;
172
+ confirm: WireSigned | null;
173
+ assignment: WireSigned | null;
174
+ refusal: WireSigned | null;
175
+ greeting: WireSigned | null;
176
+ callerIdentity: Record<string, string | number>;
177
+ calleeIdentity: Record<string, string | number>;
178
+ state: SessionState;
179
+ tip: number;
180
+ stopped: boolean;
181
+ }
182
+ export type SessionState = "offered" | "accepted" | "active" | "closed";
183
+ export type PushKind = "session" | "entry" | "delivery" | "channel" | "status";
184
+ export interface RequestFrame {
185
+ v: number;
186
+ id: number;
187
+ method: string;
188
+ params: unknown;
189
+ }
190
+ export type ResponseFrame = {
191
+ v: number;
192
+ id: number;
193
+ ok: true;
194
+ result: unknown;
195
+ } | {
196
+ v: number;
197
+ id: number;
198
+ ok: false;
199
+ error: {
200
+ code: ErrorCode;
201
+ message: string;
202
+ tip?: number;
203
+ };
204
+ };
205
+ export interface PushFrame {
206
+ v: number;
207
+ push: PushKind;
208
+ agent: string;
209
+ data: unknown;
210
+ }
211
+ export declare function readObjectField(value: unknown, name: string): Record<string, unknown>;
212
+ export {};