@ghostlytools/sdk 0.0.0-stage → 1.2.3

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 (145) hide show
  1. package/README.md +13 -2
  2. package/dist/app.js +67 -0
  3. package/dist/app.js.map +1 -0
  4. package/dist/core.js +207 -0
  5. package/dist/core.js.map +1 -0
  6. package/dist/fakes-CBIuqo5e.js +536 -0
  7. package/dist/fakes-CBIuqo5e.js.map +1 -0
  8. package/dist/fakes.js +2 -0
  9. package/dist/index.js +179 -0
  10. package/dist/index.js.map +1 -0
  11. package/dist/keet-identity-key-BylxCPl4.js +76483 -0
  12. package/dist/keet-identity-key-BylxCPl4.js.map +1 -0
  13. package/dist/src-DCeLPsi-.js +31056 -0
  14. package/dist/src-DCeLPsi-.js.map +1 -0
  15. package/dist/testing.js +330 -0
  16. package/dist/testing.js.map +1 -0
  17. package/dist/types/browser/src/engine/paymentAdapters/providers/contractSuite.d.ts +41 -0
  18. package/dist/types/browser/src/engine/paymentAdapters/providers/lightning.d.ts +103 -0
  19. package/dist/types/browser/src/engine/paymentAdapters/providers/onchain.d.ts +88 -0
  20. package/dist/types/browser/src/engine/paymentAdapters/providers/testing.d.ts +89 -0
  21. package/dist/types/browser/src/engine/paymentAdapters/providers/types.d.ts +151 -0
  22. package/dist/types/browser/src/plugins/bundled.d.ts +8 -0
  23. package/dist/types/browser/src/plugins/registry.d.ts +57 -0
  24. package/dist/types/browser/src/proofs/contract.d.ts +262 -0
  25. package/dist/types/browser/src/proofs/contractSuite.d.ts +27 -0
  26. package/dist/types/browser/src/proofs/testing.d.ts +36 -0
  27. package/dist/types/browser/src/proofs/verify.d.ts +23 -0
  28. package/dist/types/browser/src/shared/mints.d.ts +50 -0
  29. package/dist/types/core/src/appBundle.d.ts +173 -0
  30. package/dist/types/core/src/appStatements.d.ts +142 -0
  31. package/dist/types/core/src/appStore.d.ts +133 -0
  32. package/dist/types/core/src/appUpdates.d.ts +88 -0
  33. package/dist/types/core/src/atprotoIdentity.d.ts +49 -0
  34. package/dist/types/core/src/atprotoRepo.d.ts +101 -0
  35. package/dist/types/core/src/avatar.d.ts +19 -0
  36. package/dist/types/core/src/bip322.d.ts +57 -0
  37. package/dist/types/core/src/bitcoinAddress.d.ts +5 -0
  38. package/dist/types/core/src/bitcoinMessage.d.ts +15 -0
  39. package/dist/types/core/src/bitcoinScript.d.ts +69 -0
  40. package/dist/types/core/src/bolt11.d.ts +30 -0
  41. package/dist/types/core/src/bytes.d.ts +11 -0
  42. package/dist/types/core/src/callSignal.d.ts +232 -0
  43. package/dist/types/core/src/canonicalJson.d.ts +22 -0
  44. package/dist/types/core/src/capsRecord.d.ts +234 -0
  45. package/dist/types/core/src/catchUp.d.ts +45 -0
  46. package/dist/types/core/src/chatFiles.d.ts +271 -0
  47. package/dist/types/core/src/clockWatch.d.ts +72 -0
  48. package/dist/types/core/src/communityRendezvous.d.ts +113 -0
  49. package/dist/types/core/src/crypto.d.ts +10 -0
  50. package/dist/types/core/src/datalink.d.ts +187 -0
  51. package/dist/types/core/src/deviceInvite.d.ts +51 -0
  52. package/dist/types/core/src/deviceLink.d.ts +70 -0
  53. package/dist/types/core/src/dhtDelivery.d.ts +403 -0
  54. package/dist/types/core/src/dhtFiles.d.ts +46 -0
  55. package/dist/types/core/src/did.d.ts +134 -0
  56. package/dist/types/core/src/didDht.d.ts +155 -0
  57. package/dist/types/core/src/directPath.d.ts +63 -0
  58. package/dist/types/core/src/dns.d.ts +41 -0
  59. package/dist/types/core/src/domainProofs.d.ts +88 -0
  60. package/dist/types/core/src/engineErrors.d.ts +90 -0
  61. package/dist/types/core/src/enroll.d.ts +98 -0
  62. package/dist/types/core/src/files.d.ts +73 -0
  63. package/dist/types/core/src/forwards.d.ts +12 -0
  64. package/dist/types/core/src/frames.d.ts +211 -0
  65. package/dist/types/core/src/ghostlink.d.ts +1510 -0
  66. package/dist/types/core/src/groupCommits.d.ts +103 -0
  67. package/dist/types/core/src/groupCommunity.d.ts +714 -0
  68. package/dist/types/core/src/groupCrypto.d.ts +60 -0
  69. package/dist/types/core/src/groupEdits.d.ts +67 -0
  70. package/dist/types/core/src/groupEntry.d.ts +61 -0
  71. package/dist/types/core/src/groupFiles.d.ts +106 -0
  72. package/dist/types/core/src/groupHubs.d.ts +61 -0
  73. package/dist/types/core/src/groupMentions.d.ts +27 -0
  74. package/dist/types/core/src/groupMeta.d.ts +162 -0
  75. package/dist/types/core/src/groupSession.d.ts +710 -0
  76. package/dist/types/core/src/groupSignals.d.ts +167 -0
  77. package/dist/types/core/src/groupTyping.d.ts +56 -0
  78. package/dist/types/core/src/groupWake.d.ts +68 -0
  79. package/dist/types/core/src/handoff.d.ts +255 -0
  80. package/dist/types/core/src/http.d.ts +125 -0
  81. package/dist/types/core/src/identity.d.ts +17 -0
  82. package/dist/types/core/src/identityProofs.d.ts +243 -0
  83. package/dist/types/core/src/identityTimeline.d.ts +72 -0
  84. package/dist/types/core/src/image.d.ts +33 -0
  85. package/dist/types/core/src/index.d.ts +100 -0
  86. package/dist/types/core/src/invite.d.ts +128 -0
  87. package/dist/types/core/src/link.d.ts +353 -0
  88. package/dist/types/core/src/linkPreview.d.ts +60 -0
  89. package/dist/types/core/src/linkTrace.d.ts +12 -0
  90. package/dist/types/core/src/lnurl.d.ts +99 -0
  91. package/dist/types/core/src/messageTime.d.ts +28 -0
  92. package/dist/types/core/src/miniApp.d.ts +141 -0
  93. package/dist/types/core/src/pairedApps.d.ts +151 -0
  94. package/dist/types/core/src/pairedCalls.d.ts +59 -0
  95. package/dist/types/core/src/pairedCapabilities.d.ts +101 -0
  96. package/dist/types/core/src/pairedEdits.d.ts +83 -0
  97. package/dist/types/core/src/pairedFiles.d.ts +30 -0
  98. package/dist/types/core/src/pairedHttp.d.ts +15 -0
  99. package/dist/types/core/src/pairedSession.d.ts +163 -0
  100. package/dist/types/core/src/pairedSignal.d.ts +17 -0
  101. package/dist/types/core/src/pairedTransports.d.ts +76 -0
  102. package/dist/types/core/src/pairedTyping.d.ts +130 -0
  103. package/dist/types/core/src/pairedWake.d.ts +109 -0
  104. package/dist/types/core/src/pairingProgress.d.ts +107 -0
  105. package/dist/types/core/src/paymentIntent.d.ts +111 -0
  106. package/dist/types/core/src/paymentUri.d.ts +34 -0
  107. package/dist/types/core/src/payments.d.ts +97 -0
  108. package/dist/types/core/src/peerProofs.d.ts +98 -0
  109. package/dist/types/core/src/pins.d.ts +73 -0
  110. package/dist/types/core/src/pkarr.d.ts +48 -0
  111. package/dist/types/core/src/pkdns.d.ts +35 -0
  112. package/dist/types/core/src/pubkyProofs.d.ts +25 -0
  113. package/dist/types/core/src/pubkyRing.d.ts +21 -0
  114. package/dist/types/core/src/reactions.d.ts +108 -0
  115. package/dist/types/core/src/records.d.ts +89 -0
  116. package/dist/types/core/src/relay.d.ts +437 -0
  117. package/dist/types/core/src/relayBreaker.d.ts +99 -0
  118. package/dist/types/core/src/replies.d.ts +41 -0
  119. package/dist/types/core/src/services.d.ts +35 -0
  120. package/dist/types/core/src/setUpdate.d.ts +53 -0
  121. package/dist/types/core/src/signal.d.ts +53 -0
  122. package/dist/types/core/src/signer.d.ts +13 -0
  123. package/dist/types/core/src/sparkAddress.d.ts +37 -0
  124. package/dist/types/core/src/sshsig.d.ts +74 -0
  125. package/dist/types/core/src/statusCards.d.ts +253 -0
  126. package/dist/types/core/src/storeForward.d.ts +144 -0
  127. package/dist/types/core/src/text.d.ts +20 -0
  128. package/dist/types/core/src/transport.d.ts +151 -0
  129. package/dist/types/core/src/transportSwitch.d.ts +160 -0
  130. package/dist/types/core/src/turnRead.d.ts +145 -0
  131. package/dist/types/core/src/turnRecord.d.ts +165 -0
  132. package/dist/types/core/src/version.d.ts +9 -0
  133. package/dist/types/core/src/video.d.ts +44 -0
  134. package/dist/types/core/src/voice.d.ts +88 -0
  135. package/dist/types/core/src/webPush.d.ts +58 -0
  136. package/dist/types/sdk/src/app.d.ts +23 -0
  137. package/dist/types/sdk/src/core.d.ts +7 -0
  138. package/dist/types/sdk/src/fakes.d.ts +6 -0
  139. package/dist/types/sdk/src/index.d.ts +26 -0
  140. package/dist/types/sdk/src/testing.d.ts +7 -0
  141. package/dist/types-DvtCy3WB.js +99 -0
  142. package/dist/types-DvtCy3WB.js.map +1 -0
  143. package/dist/verify-DBGw6wYt.js +106 -0
  144. package/dist/verify-DBGw6wYt.js.map +1 -0
  145. package/package.json +70 -4
@@ -0,0 +1,403 @@
1
+ import type { LinkParams } from "./invite.js";
2
+ import type { PairingCredentials } from "./pairedSession.js";
3
+ import { type PkarrRequestOptions, type PkarrTransport } from "./transport.js";
4
+ import { type WireReaction } from "./reactions.js";
5
+ import { type DhtFileAnnouncement, type DhtFileElement, type DhtFileOffer } from "./dhtFiles.js";
6
+ export type DeliveryMode = "stream" | "dht";
7
+ export declare const DHT_TEXT_BYTES = 256;
8
+ export declare const DHT_MESSAGE_TTL: number;
9
+ /**
10
+ * How far apart two devices' clocks may be for an envelope's expiry: a reader takes one until this long after `expires`
11
+ * by its own clock. A device's clock a few minutes off is common; an envelope's lifetime is five or ten minutes, so a
12
+ * sender that far behind had every envelope expired on arrival, with nothing on screen on either side. Its `issued` is
13
+ * refused for nothing: what stops an old envelope from being taken again is its `sequence`, which the reader keeps.
14
+ */
15
+ export declare const DHT_EXPIRY_SKEW_MS: number;
16
+ /**
17
+ * How far before its own clock a sender dates an envelope (`issued`), never before the envelope's lifetime began nor
18
+ * 30 s before its text's time. Apps up to 1.0.2 refuse an envelope dated more than 30 s past their clock, so every
19
+ * envelope of a clock two minutes ahead was dropped by them: no first contact, no text, no receipt. Dated back, a
20
+ * control envelope from a clock up to two and a half minutes ahead is taken by them at once, and a text once it has
21
+ * been going out for as long as the clock is ahead.
22
+ */
23
+ export declare const DHT_ISSUED_BACK_MS: number;
24
+ /**
25
+ * …except for this long after this side leaves DHT-only while the contact is still there: its own
26
+ * switch then shows in seconds, not at the next 30 s read (both sides are blocked from a live link until
27
+ * each has seen the other leave).
28
+ */
29
+ export declare const LEAVING_DHT_FAST_MS: number;
30
+ /**
31
+ * Reads of a DHT-only contact's mailbox that go as signaling (`expect(ms, true)`) once something shows it leaving,
32
+ * for as long as it still says DHT only. What shows it (a fresh packet on its link key, its offer) can reach this side
33
+ * before the envelope saying so reaches the relays, and the first read then finds DHT only still. With the relays'
34
+ * minute spent, every read after it was held back for 42 s, and the chat stayed "On DHT · retrying live" while its
35
+ * contact had left (mx-d707d8d5, 2026-09-30). A few, not the whole window: the allowance they spend is also what this
36
+ * side's offer and its reads for the answer go over the minute on (`SIGNALING_ALLOWANCE_SHARE` in relay.ts).
37
+ */
38
+ export declare const LEAVING_SIGNAL_READS = 3;
39
+ /** Only this often while layer 1 carries the chat (WISP 403, Q7): the relays' per-IP budget is shared by every chat. */
40
+ export declare const LIVE_POLL_MS: number;
41
+ /**
42
+ * On the DHT with the chat open, the mailbox is read this often (WISP 403 proposes 4 s). The relays' per-IP budget
43
+ * (30 requests a minute per relay here, reads and publishes together) is shared with presence polling, which is at its
44
+ * fastest right then, while layer 1 is redialled; 4 s starved the publications of held items in the store-and-forward
45
+ * e2e. A text of ours awaiting its receipt still reads at 4 s, and a drop reads once, at once.
46
+ */
47
+ export declare const ACTIVE_DHT_POLL_MS = 10000;
48
+ type Message = [id: string, timestamp: number, text: string];
49
+ /**
50
+ * The twelfth element, with a text only: the text is an edit (WISP 403 § Edits), the new text of the message with this id,
51
+ * edit number `e`. The eleventh then goes as `null` when the text replies to nothing. An app from before edits would show
52
+ * the text as a message of its own: it is sent only to a contact whose capability record lists `edit/1`.
53
+ */
54
+ type DhtEdit = [id: string, e: number];
55
+ export interface DhtDeliveryState {
56
+ sequence: number;
57
+ peerSequence: number;
58
+ peerMode?: DeliveryMode;
59
+ /**
60
+ * How far the contact is in the pinned mailbox (WISP 403, revision 0.3), from its envelopes sealed to this side: it
61
+ * `can` use it; it `reads` there first (it knows this side can); it was `seen` publishing there. This side reads
62
+ * there first from `can` on and publishes there from `reads` on; from `seen` on it reads only there.
63
+ */
64
+ peerPinned?: "can" | "reads" | "seen";
65
+ /** `reply`: the id of the message the text replies to, published with it (the eleventh element). */
66
+ pending?: {
67
+ message: Message;
68
+ expires: number;
69
+ attempts: number;
70
+ next: number;
71
+ reply?: string;
72
+ edit?: DhtEdit;
73
+ forwarded?: number;
74
+ file?: DhtFileElement;
75
+ };
76
+ /**
77
+ * The receipt this side owes for the contact's last text. `next`: when it forces a publication again (absent: at
78
+ * once). `settled`: the contact's newer envelope no longer carries that text (it has a receipt, on either path, or
79
+ * gave up on it), so the receipt only rides along on envelopes that go out anyway.
80
+ */
81
+ receipt?: {
82
+ id: string;
83
+ expires: number;
84
+ attempts: number;
85
+ next?: number;
86
+ settled?: boolean;
87
+ };
88
+ confirmed?: string;
89
+ /** The highest number of the contact's reactions taken from its envelopes: said back in every envelope. */
90
+ reactionsTaken?: number;
91
+ /**
92
+ * The contact's envelope, by its hint the pinned (or expected) key's, is sealed to another key: the contact paired with
93
+ * someone else who used the same invite first. Kept until an envelope of the contact's newer than the last read opens.
94
+ */
95
+ inviteTaken?: true;
96
+ /**
97
+ * Layer 1 carried this chat with the pinned key at least once: the contact pinned this side, for good. What reads as
98
+ * "the invite was taken" from then on is not the contact's word (`sealedToAnother`).
99
+ */
100
+ wasLive?: true;
101
+ }
102
+ export interface DhtDeliveryView {
103
+ mode: DeliveryMode;
104
+ peerMode?: DeliveryMode;
105
+ authenticated: boolean;
106
+ error?: string;
107
+ pendingUntil?: number;
108
+ maxTextBytes: number;
109
+ /** The envelope last published from here, for a text's details; absent until one carried a text. */
110
+ lastPublished?: DhtPacketFacts;
111
+ /**
112
+ * When an envelope or a connection signal signed by a participation key other than the pinned one last came in
113
+ * over one of the chat's invite-derived keys. Anyone holding a copy of the invite can publish there, so it is
114
+ * ignored, never a reason to stop the chat: a passive warning only.
115
+ */
116
+ foreignKeySeenAt?: number;
117
+ /** The invite was used by someone else first (`DhtDeliveryState.inviteTaken`): this side's texts reach nobody. */
118
+ inviteTaken?: boolean;
119
+ }
120
+ /**
121
+ * What can be said about one DHT envelope without opening it: which text it carried, its sequence and times, the
122
+ * signed packet's size, the sealed record's nonce (the first 24 bytes of the record, never a key) and the address
123
+ * it was published under. All of it travels in the clear on the DHT already.
124
+ */
125
+ export interface DhtPacketFacts {
126
+ /** The text's stable id, when the envelope carried one. */
127
+ id?: string;
128
+ seq: number;
129
+ issued: number;
130
+ expires: number;
131
+ packetBytes: number;
132
+ nonce: string;
133
+ recordKey: string;
134
+ records: string[];
135
+ }
136
+ export declare const emptyDhtDeliveryState: () => DhtDeliveryState;
137
+ /** An invite is a secret capability, not an independently verified identity.
138
+ * Participation signatures bind each encrypted envelope to both invite roles.
139
+ * The same durable TOFU pin is required here and on all subsequent streams.
140
+ * No forward-secrecy or guaranteed DHT retention claim is made. */
141
+ export declare class DhtDelivery {
142
+ private readonly options;
143
+ private state;
144
+ private mode;
145
+ private running;
146
+ private ticking;
147
+ private tickAgain;
148
+ /** Until when this side, having left DHT-only, reads a contact still there at the fast pace. */
149
+ private leavingUntil;
150
+ /** Until when the mailbox is read at the fast pace for any other reason (a drop, a first contact). */
151
+ private fastUntil;
152
+ private live;
153
+ private active;
154
+ /** The next read was asked for (a refresh, a fresh packet of the contact): it is not a background one. */
155
+ private urgent;
156
+ /** Reads left that are signaling: the contact is leaving DHT only, and the live link waits on them (`expect`). */
157
+ private signalReads;
158
+ private timer;
159
+ /** The first control envelope of a start that waits (`firstControlAfterMs`). */
160
+ private controlTimer;
161
+ /** A new capability revision to name once the publication spacing allows (`announce`). */
162
+ private announceTimer;
163
+ private chain;
164
+ private lastPublish;
165
+ /** The sequence of the last envelope of the contact that was past its expiry (traced once). */
166
+ private expiredSeen;
167
+ private controlDue;
168
+ /**
169
+ * This side's envelope in the invite's mailbox is sealed with the invite key alone (published before the pin). Once the
170
+ * contact is pinned, one sealed to it replaces it as soon as the publication spacing allows (`resealDue`): another
171
+ * holder of the invite reads there that it was taken (`sealedToAnother`), instead of pinning this side on it.
172
+ */
173
+ private unsealedOut;
174
+ /** Until when the relays' request budget holds publications back: what is due then goes at once. */
175
+ private budgetUntil;
176
+ private errors;
177
+ /** When the device's network last came back (`networkBack`): a read or publication started before failed for want of it. */
178
+ private networkBackAt;
179
+ private foreignKeySeenAt?;
180
+ /** When the pinned mailbox was last looked in while the contact had not said it uses it. */
181
+ private pinnedProbeAt;
182
+ private pinnedBoxes?;
183
+ private readonly identity;
184
+ private readonly peerAddress;
185
+ private readonly key;
186
+ private readonly from;
187
+ private readonly to;
188
+ private readonly participation;
189
+ /** The capability-record revision the last envelope published here named. */
190
+ private namedRev?;
191
+ /** A reaction of this side waits to ride on an envelope, or the contact's reactions wait to be said taken. */
192
+ private reactionsDue;
193
+ constructor(options: {
194
+ params: LinkParams;
195
+ mode: DeliveryMode;
196
+ state?: DhtDeliveryState;
197
+ credentials: PairingCredentials;
198
+ transport: PkarrTransport;
199
+ save(state: DhtDeliveryState): Promise<void>;
200
+ pin(key: string): Promise<void>;
201
+ /** `file`: the text is a file's name, and this its offer (WISP 403 § Files): a bubble, not a text. */
202
+ message(message: {
203
+ id: string;
204
+ text: string;
205
+ timestamp: number;
206
+ reply?: {
207
+ i: string;
208
+ };
209
+ edit?: {
210
+ i: string;
211
+ e: number;
212
+ };
213
+ forwarded?: number;
214
+ file?: DhtFileAnnouncement;
215
+ }, packet: DhtPacketFacts): Promise<void>;
216
+ receipt(id: string): Promise<void>;
217
+ changed(view: DhtDeliveryView): void;
218
+ /** This side's capability-record revision, told in every envelope (WISP 03). */
219
+ capsRev?(): number | undefined;
220
+ /** An envelope from the contact named this revision of its capability record. */
221
+ peerCapsRev?(rev: number): void;
222
+ /** Whether the contact's capability record accepts DHT text (`dht-text/1`); absent or unknown: it does. */
223
+ peerAcceptsText?(): boolean;
224
+ /** Whether the contact's capability record takes a file's offer on the floor (`dht-file/1`); absent: it does not. */
225
+ peerAcceptsFile?(): boolean;
226
+ /** This side's reactions the contact has not confirmed, oldest first: they ride on the envelopes (WISP 403 § Reactions). */
227
+ reactions?(): readonly WireReaction[];
228
+ /** A reaction of the contact's, from an envelope, already checked. */
229
+ reaction?(reaction: WireReaction): Promise<void>;
230
+ /** The contact took this side's reactions up to number `n`. */
231
+ reactionsTaken?(n: number): Promise<void>;
232
+ pollMs?: number;
233
+ /**
234
+ * A chat already paired, started again: its first control envelope goes this long after the start, not in the
235
+ * burst of an app coming back (bug hunt r7a). A text, a receipt, a new mode or a new capability revision still go at once.
236
+ */
237
+ firstControlAfterMs?: number;
238
+ });
239
+ get view(): DhtDeliveryView;
240
+ /**
241
+ * Something signed by a participation key other than the pinned one came in over the chat's invite-derived keys (this
242
+ * mailbox, the link's signals, a connection to an endpoint whose address a copy of the invite could read): ignored,
243
+ * and said in the view as a passive warning.
244
+ */
245
+ foreignKeySeen(path: "dht" | "signal" | "stream"): void;
246
+ /**
247
+ * The mailboxes once the contact is pinned (WISP 403, revision 0.3): derived from the secret only the two
248
+ * participation keys share, so a copy of the invite can neither publish there nor overwrite the contact's texts.
249
+ */
250
+ private pinned;
251
+ private lastPublished?;
252
+ /** The sealed record's nonce is its first 24 bytes: 32 characters of base64. */
253
+ private static facts;
254
+ get comparisonCode(): string | undefined;
255
+ get peerMode(): DeliveryMode | undefined;
256
+ private changed;
257
+ private serialize;
258
+ private persist;
259
+ private sealedKey;
260
+ private signed;
261
+ private records;
262
+ start(): Promise<void>;
263
+ stop(): Promise<void>;
264
+ setMode(mode: DeliveryMode): Promise<void>;
265
+ /** Reads the contact's mailbox now: something says it may have changed its delivery method. */
266
+ refresh(): void;
267
+ /**
268
+ * The device's network came back: a read or publication error from while it was away says nothing now (No Pkarr
269
+ * relay reachable). It goes at once, and the mailbox is read now: one that still fails says so again.
270
+ */
271
+ networkBack(): void;
272
+ /**
273
+ * Reads the contact's mailbox at the signaling pace for a while (a fresh packet of a contact not pinned yet).
274
+ * `signal`: the contact is leaving DHT only (a fresh packet on its link key, or its offer), and the live link waits
275
+ * on a read to say so: the next read goes now, and it and the next ones while the contact still says DHT only
276
+ * (`LEAVING_SIGNAL_READS` in all) are signaling (`PkarrRequestOptions.signal`).
277
+ */
278
+ expect(ms?: number, signal?: boolean): void;
279
+ /**
280
+ * Layer 1 carries the chat, or no longer does. While it does, the mailbox is read every 5 minutes, after one
281
+ * last look as it goes live: a text the contact put on the DHT in the seconds before (after this side's last
282
+ * read) would otherwise wait for the next look. That look is a background request, which yields to links that
283
+ * signal, and only for a contact that wrote in this mailbox already. The moment layer 1 is lost, at once
284
+ * (WISP 403, poll pace), and then at the chat's pace.
285
+ */
286
+ setLive(live: boolean): void;
287
+ get isLive(): boolean;
288
+ /** The chat is open with the app in front: on the DHT, its mailbox is read at the signaling pace. */
289
+ setActive(active: boolean): void;
290
+ validate(text: string, timestamp: number, id: string, reply?: string, edit?: DhtEdit): string | null;
291
+ private packetError;
292
+ /** Whether a text with its hop count fits the packet and what a reader reads (`MAX_ENVELOPE_PLAINTEXT`). */
293
+ private roomForHops;
294
+ /**
295
+ * `forwarded`: a forwarded text's hop count (WISP 403 § Forwards). Like a reply's id it goes only when the packet has
296
+ * room for it: the text is what matters, and it then reads as written here.
297
+ */
298
+ send(text: string, timestamp: number, id: string, reply?: string, edit?: DhtEdit, forwarded?: number): Promise<string | null>;
299
+ /**
300
+ * The envelope a file's offer would go in, as `send` builds a text's: the most it can say that fits the packet and
301
+ * what a reader reads (`MAX_ENVELOPE_PLAINTEXT`). Its meta goes first (a voice note's waveform thinned if it must),
302
+ * then the reply's id, then the hop count; the name, size, type and id always. A string: why it cannot go.
303
+ */
304
+ private fileEnvelope;
305
+ /** Why a file's offer cannot go on the floor now (WISP 403 § Files), or null when it can. */
306
+ fileError(file: DhtFileOffer, timestamp: number, reply?: string, forwarded?: number): string | null;
307
+ /**
308
+ * Says a file's offer on the floor (WISP 403 § Files): its bubble takes its place on the contact's side, and its bytes
309
+ * follow on the live session. It takes the floor's one slot as a text does, under `dhtFileId(wireId)`, with the same
310
+ * retries and expiry; a receipt names that id. Null once it is the floor's pending envelope (a publication that
311
+ * failed is retried, as a text's is).
312
+ */
313
+ announceFile(file: DhtFileOffer, timestamp: number, reply?: string, forwarded?: number): Promise<string | null>;
314
+ /** The id of what awaits its receipt on the floor now, if anything does. */
315
+ get pendingId(): string | undefined;
316
+ /**
317
+ * This side's capability record has a new revision (WISP 03): an envelope names it now. Otherwise the contact
318
+ * learns of it with the next envelope that goes out anyway, a control one minutes away when nothing is sent,
319
+ * and dials no native transport the record newly offers until then.
320
+ */
321
+ announce(): Promise<void>;
322
+ /**
323
+ * This side has reactions the contact has not confirmed (`reactions`): the next envelope carries them, and goes
324
+ * as soon as the publication spacing allows.
325
+ */
326
+ announceReactions(): Promise<void>;
327
+ /** A stream receipt for the same stable ID also cancels DHT retransmission. */
328
+ acknowledge(id: string): Promise<void>;
329
+ private body;
330
+ /**
331
+ * The envelope with as many of this side's pending reactions as fit, oldest first: the packet's budget and what a
332
+ * reader reads (`MAX_ENVELOPE_PLAINTEXT`) both bound it. The contact confirms up to the newest it carried.
333
+ */
334
+ private fitted;
335
+ private publish;
336
+ /** The contact is pinned and this side's envelope in the invite's mailbox is still unsealed (`unsealedOut`). */
337
+ private get resealDue();
338
+ /**
339
+ * The relays' request budget held the envelope back: nothing went out, so it was no attempt (a text keeps its eight),
340
+ * and what it carried (a text, a receipt, a new mode) goes the moment the budget frees a request: the text and the
341
+ * receipt as they were before, and no publication before then (`budgetUntil`) but a forced one.
342
+ */
343
+ private heldBack;
344
+ /**
345
+ * One packet from one of the contact's mailboxes, opened and checked the way `receive` takes it: the right address,
346
+ * one sealed record, a well-formed body within its times, signed by the key it names. Null: not an envelope of the
347
+ * contact's (the pin rules are the caller's).
348
+ */
349
+ private open;
350
+ /**
351
+ * The contact's envelope is sealed to another key (`open`): it pinned someone else who used the same invite first, so
352
+ * nothing of this side's will ever be read. Said only while this side is not proven the one it pinned: no envelope
353
+ * sealed to this side read (`peerPinned`), no text confirmed, never live (`wasLive`). The hint is sealed under the
354
+ * invite's key, which any copy of it holds, so past that proof it says nothing of the contact: a passive warning,
355
+ * taken back by the contact's next envelope that opens here, or by a live session.
356
+ */
357
+ private sealedToAnother;
358
+ /**
359
+ * One packet from one of the contact's two mailboxes: `invite` (derived from the invite, which anyone holding a copy
360
+ * can write to) or `pinned`. `none`: nothing from the contact in it; `old`: the contact's, already read; `new`: taken.
361
+ */
362
+ private receive;
363
+ /**
364
+ * Reads the contact's mailbox: the pinned one first once the contact said it can use it, the invite's otherwise. The
365
+ * other is read too when the first held nothing from the contact (the contact publishes in the other one still, or a
366
+ * copy of the invite overwrote this one), or when the contact just said it can use the pinned one. Once the contact's
367
+ * envelope was seen in the pinned mailbox, the invite's is not read any more.
368
+ */
369
+ private read;
370
+ /**
371
+ * A look at this chat from another profile of the device while this one is not running (WISP 04 § Checking other
372
+ * profiles): the mailbox the chat reads first, opened and checked as `receive` does, with nothing saved, pinned or
373
+ * published. It tells only whether the contact's envelope carries a text this side has not taken yet, and that text's
374
+ * id; the words are dropped unread. `reads`: requests spent. Null `text`: nothing new, or nothing of the contact's.
375
+ */
376
+ peek(options?: PkarrRequestOptions): Promise<{
377
+ reads: number;
378
+ text: string | null;
379
+ }>;
380
+ private tick;
381
+ private publishOnTick;
382
+ /** How long until the next read of the contact's mailbox (WISP 403, poll pace). */
383
+ get pollMs(): number;
384
+ private schedule;
385
+ }
386
+ export declare const DHT_TEXT_REFUSED = "Your contact's app does not accept text over the DHT. It is sent when you are live.";
387
+ export declare const DHT_FILE_REFUSED = "Your contact's app shows a file only once it comes. It is sent when you are live.";
388
+ export declare const DHT_FILE_TOO_LARGE = "This file's name is too long to say over the DHT. It is sent when you are live.";
389
+ /**
390
+ * `DhtDelivery.peek` for a chat of a profile that is not running: built from what that profile stored, with every
391
+ * callback a no-op that refuses to save, so the look can change nothing.
392
+ */
393
+ export declare function peekDhtMailbox(options: {
394
+ params: LinkParams;
395
+ credentials: PairingCredentials;
396
+ state?: DhtDeliveryState;
397
+ transport: PkarrTransport;
398
+ background?: boolean;
399
+ }): Promise<{
400
+ reads: number;
401
+ text: string | null;
402
+ }>;
403
+ export {};
@@ -0,0 +1,46 @@
1
+ import { type ImageMeta } from "./image.js";
2
+ import { type VideoMeta } from "./video.js";
3
+ import { type VoiceMeta } from "./voice.js";
4
+ /**
5
+ * A file's bubble on the DHT floor (WISP 403 § Files): while the contact is away, a file's offer (its name, size, type,
6
+ * id and the sender's time, with its picture, voice or video size when it has one) rides an envelope like a text, so
7
+ * it takes its place among the texts written around it. Its bytes never do: they follow on the live session (files/3).
8
+ *
9
+ * Only to a contact whose capability record (WISP 03) lists this: an app from before would show the file's name as a
10
+ * text of its own.
11
+ */
12
+ export declare const DHT_FILE_CAPABILITY: "dht-file/1";
13
+ /** The id a file's offer has on the floor (22 characters, like a text's): every send of it and its receipt match. */
14
+ export declare function dhtFileId(wireId: string): string;
15
+ /** What a picture, a voice note or a video says of itself on the floor: a video's poster never rides. */
16
+ export interface DhtFileMeta {
17
+ voice?: VoiceMeta;
18
+ image?: ImageMeta;
19
+ video?: Omit<VideoMeta, "poster">;
20
+ }
21
+ /** The signed body's sixteenth element: `[wire id, size, type, meta]`. The name is the envelope's text. */
22
+ export type DhtFileElement = [wireId: string, size: number, mime: string, meta: DhtFileMeta | null];
23
+ /** A file to say on the floor, as the sender has it. */
24
+ export interface DhtFileOffer {
25
+ wireId: string;
26
+ name: string;
27
+ size: number;
28
+ mime: string;
29
+ voice?: VoiceMeta;
30
+ image?: ImageMeta;
31
+ video?: VideoMeta;
32
+ }
33
+ /** A file the contact said on the floor, checked: its bubble waits for the bytes. */
34
+ export interface DhtFileAnnouncement extends DhtFileOffer {
35
+ video?: Omit<VideoMeta, "poster">;
36
+ }
37
+ /**
38
+ * The sixteenth elements to try for a file, the most it can say first: its whole meta, a voice note's waveform thinned
39
+ * to fewer bars, no meta. The sender takes the first whose envelope fits the packet.
40
+ */
41
+ export declare function dhtFileElements(file: DhtFileOffer): DhtFileElement[];
42
+ /**
43
+ * The sixteenth element as a reader takes it, with the envelope's message (`[id, time, name]`). Null when it is not a
44
+ * file's offer, or not one that holds: the envelope's id must be the one its wire id gives, so a receipt names it.
45
+ */
46
+ export declare function readDhtFile(raw: unknown, message: [id: string, timestamp: number, text: string]): DhtFileAnnouncement | null;
@@ -0,0 +1,134 @@
1
+ /**
2
+ * Decentralized identifiers (W3C DID Core 1.0) as external identities, network-free half: DID syntax,
3
+ * the documents did:key and did:jwk carry in the identifier itself, did:web's URLs, strict parsing of a
4
+ * fetched DID document, and JWS / raw signatures by the keys it lists. Fetching did:web documents and
5
+ * did:dht records is the browser's (`packages/browser/src/proofs/did.ts`).
6
+ *
7
+ * Only keys a document lists under `authentication` or `assertionMethod` may sign for the DID: a key
8
+ * listed only for key agreement or capability delegation does not speak for it.
9
+ */
10
+ export declare class DidError extends Error {
11
+ }
12
+ export declare const DID_METHODS: readonly ["key", "jwk", "dht", "web"];
13
+ export type DidMethod = (typeof DID_METHODS)[number];
14
+ export type DidCurve = "Ed25519" | "secp256k1" | "P-256";
15
+ export type DidRelationship = "authentication" | "assertionMethod";
16
+ /** Same bound as an identity proof's subject (printable ASCII, no spaces). */
17
+ export declare const DID_MAX_LENGTH = 512;
18
+ /** A fetched did.json. */
19
+ export declare const DID_DOCUMENT_MAX_BYTES: number;
20
+ /** The statement file a did:web publishes beside its did.json. */
21
+ export declare const DID_FILE_MAX_BYTES: number;
22
+ export declare const DID_JWS_MAX_LENGTH = 4096;
23
+ /** The service type a did.json uses to vouch for a Ghostly proof. */
24
+ export declare const DID_GHOSTLY_SERVICE = "GhostlyIdentityProof";
25
+ export interface DidKey {
26
+ /** The verification method's absolute id: `<did>#<fragment>`. */
27
+ id: string;
28
+ curve: DidCurve;
29
+ /** Ed25519: 32 bytes. secp256k1 and P-256: 33 bytes, compressed. */
30
+ publicKey: Uint8Array;
31
+ /** Empty when the document lists the key but not for authentication or assertionMethod. */
32
+ relationships: DidRelationship[];
33
+ }
34
+ /** A `GhostlyIdentityProof` service: the document names a proof key and the statement id it vouches for. */
35
+ export interface DidGhostlyService {
36
+ id: string;
37
+ key: string;
38
+ proof: string;
39
+ }
40
+ /** What a DID document says, as far as Ghostly uses it. */
41
+ export interface DidDocumentView {
42
+ did: string;
43
+ keys: DidKey[];
44
+ /** Verification methods Ghostly cannot use (other curves, key agreement keys, other DIDs' ids). */
45
+ skipped: number;
46
+ services: DidGhostlyService[];
47
+ }
48
+ /** base64url without padding, strictly: decoding and encoding again gives the same text. */
49
+ export declare function strictBase64Url(value: string): Uint8Array;
50
+ export interface ParsedDid {
51
+ did: string;
52
+ method: DidMethod;
53
+ id: string;
54
+ }
55
+ /**
56
+ * The DID a person typed, checked and in canonical form, or a message they can act on. Methods other than
57
+ * the four Ghostly checks are refused with "not supported yet"; a DID URL (a `#fragment`, `?query` or
58
+ * `/path`) is refused, since it names something inside a DID rather than the DID.
59
+ */
60
+ export declare function parseDid(input: string): ParsedDid;
61
+ /** The canonical form of a DID Ghostly checks (a lowercase did:web host, a lowercase did:dht key). */
62
+ export declare const normalizeDid: (input: string) => string;
63
+ /** The host a did:web lives on (no port): the name looked up before contacting it. */
64
+ export declare const didWebHost: (did: string) => string;
65
+ /** did:web → its did.json: `/.well-known/did.json` for a bare domain, `/<path>/did.json` otherwise. */
66
+ export declare function didWebDocumentUrl(did: string): string;
67
+ /** Where a did:web publishes the statement of proof `proofId`: `ghostly/<id>.json` beside its did.json. */
68
+ export declare function didWebFileUrl(did: string, proofId: string): string;
69
+ /** The body of that file: the DID and the exact statement text. */
70
+ export declare function didWebFile(did: string, statement: string): string;
71
+ /** True when `text` is a statement file for exactly this DID and statement. */
72
+ export declare function didWebFileNames(text: string, did: string, statement: string): boolean;
73
+ /** The service entry a did.json can carry instead of the file. */
74
+ export declare function didGhostlyServiceEntry(did: string, key: string, proofId: string): Record<string, unknown>;
75
+ /** The document of a did:key or did:jwk, which needs no network. */
76
+ export declare function staticDidDocument(did: string): DidDocumentView;
77
+ /**
78
+ * A fetched or resolved DID document, strictly: it must be for exactly `did`; verification methods are
79
+ * read from `verificationMethod` and from `authentication` / `assertionMethod` (references or embedded);
80
+ * `GhostlyIdentityProof` services are kept. Keys Ghostly cannot use are counted in `skipped`.
81
+ */
82
+ export declare function parseDidDocument(did: string, raw: unknown): DidDocumentView;
83
+ /** Keys that may sign for the DID. */
84
+ export declare const signingKeys: (doc: DidDocumentView) => DidKey[];
85
+ /** JWS `alg` values Ghostly checks, and the curve each needs (RFC 8037, RFC 8812, RFC 7518, RFC 9864's Ed25519). */
86
+ export declare const DID_JWS_ALGS: Record<string, DidCurve>;
87
+ /** The `alg` a person's tool should write for a key on this curve. */
88
+ export declare const didJwsAlg: (curve: DidCurve) => "EdDSA" | "ES256" | "ES256K";
89
+ export interface DidJws {
90
+ alg: string;
91
+ curve: DidCurve;
92
+ kid?: string;
93
+ /** RFC 7797: false signs the payload as it is (detached only). */
94
+ b64: boolean;
95
+ /** The protected header and payload segments as they were, for the signing input. */
96
+ header: string;
97
+ payload: string;
98
+ signature: Uint8Array;
99
+ }
100
+ /** A compact JWS, attached or detached (`header..signature`), checked for shape only. */
101
+ export declare function parseDidJws(input: string): DidJws;
102
+ export interface DidSignatureCheck {
103
+ key: DidKey;
104
+ alg: string;
105
+ }
106
+ /**
107
+ * Which key of `doc` made this JWS over one of `messages` (the statement, and the statement with a
108
+ * trailing newline some tools add). With a `kid`, only that key is tried. Refused unless the key is
109
+ * listed for authentication or assertionMethod.
110
+ */
111
+ export declare function checkDidJws(input: string, messages: Uint8Array[], doc: DidDocumentView): DidSignatureCheck;
112
+ /**
113
+ * Which key of `doc` made this raw signature over one of `messages`: Ed25519 (64 bytes), or ECDSA with
114
+ * SHA-256 on secp256k1 or P-256 (64 bytes r‖s, or DER as OpenSSL writes it). `vm` narrows it to one key.
115
+ * Returns the signature in its canonical form (r‖s for ECDSA).
116
+ */
117
+ export declare function checkDidSignature(signature: Uint8Array, messages: Uint8Array[], doc: DidDocumentView, vm?: string): DidSignatureCheck & {
118
+ signature: Uint8Array;
119
+ };
120
+ /**
121
+ * What a person pasted as a signature: a compact JWS, or a raw signature (hex, base64 or base64url),
122
+ * optionally after the verification method id (`did:…#key-1 <signature>` or `#key-1 <signature>`).
123
+ */
124
+ export type DidSignaturePaste = {
125
+ kind: "jws";
126
+ jws: string;
127
+ } | {
128
+ kind: "raw";
129
+ vm?: string;
130
+ signature: Uint8Array;
131
+ };
132
+ export declare function parseDidSignaturePaste(pasted: string): DidSignaturePaste;
133
+ /** The statement bytes a signature may cover: exactly the statement, or with the newline `echo` adds. */
134
+ export declare const didSignedMessages: (statement: string) => Uint8Array<ArrayBufferLike>[];