@ghostlytools/sdk 1.2.3 → 1.3.0
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/dist/app.js +15 -4
- package/dist/app.js.map +1 -1
- package/dist/core.js +2 -2
- package/dist/{fakes-CBIuqo5e.js → fakes-BlpK1WuW.js} +2 -2
- package/dist/{fakes-CBIuqo5e.js.map → fakes-BlpK1WuW.js.map} +1 -1
- package/dist/fakes.js +1 -1
- package/dist/index.js +2 -2
- package/dist/{keet-identity-key-BylxCPl4.js → keet-identity-key-GE5nr3zt.js} +2 -2
- package/dist/{keet-identity-key-BylxCPl4.js.map → keet-identity-key-GE5nr3zt.js.map} +1 -1
- package/dist/{src-DCeLPsi-.js → src-JQitqFJD.js} +1038 -137
- package/dist/src-JQitqFJD.js.map +1 -0
- package/dist/testing.js +3 -3
- package/dist/types/core/src/appBundle.d.ts +28 -0
- package/dist/types/core/src/chatFiles.d.ts +41 -1
- package/dist/types/core/src/datalink.d.ts +13 -7
- package/dist/types/core/src/dhtDelivery.d.ts +9 -0
- package/dist/types/core/src/engineErrors.d.ts +1 -0
- package/dist/types/core/src/frames.d.ts +5 -0
- package/dist/types/core/src/ghostlink.d.ts +83 -8
- package/dist/types/core/src/groupCommunity.d.ts +37 -1
- package/dist/types/core/src/groupFiles.d.ts +6 -2
- package/dist/types/core/src/groupSession.d.ts +57 -6
- package/dist/types/core/src/groupSignals.d.ts +2 -0
- package/dist/types/core/src/link.d.ts +15 -0
- package/dist/types/core/src/miniApp.d.ts +15 -4
- package/dist/types/core/src/pairedCapabilities.d.ts +6 -1
- package/dist/types/core/src/pkarr.d.ts +6 -0
- package/dist/types/core/src/relay.d.ts +60 -4
- package/dist/types/core/src/transport.d.ts +12 -0
- package/dist/{verify-DBGw6wYt.js → verify-afQj9kHW.js} +2 -2
- package/dist/{verify-DBGw6wYt.js.map → verify-afQj9kHW.js.map} +1 -1
- package/package.json +1 -1
- package/dist/src-DCeLPsi-.js.map +0 -1
package/dist/testing.js
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import { Bi as isBitcoinAddress, Ql as IDENTITY_MAX_EVIDENCE, da as decodeBolt11, ex as createIdentity, fu as identityStatement, hu as newIdentityBinding, lu as emptyIdentityLedger, su as IdentityExchange } from "./src-JQitqFJD.js";
|
|
2
2
|
import { l as providerDescriptorProblems, o as isNothingSpentError } from "./types-DvtCy3WB.js";
|
|
3
|
-
import { i as verifyIdentity, r as descriptorProblems } from "./verify-
|
|
4
|
-
import { _ as fakeAddress, a as fakeAccount, b as fakeOnchain, c as fakeKeySign, d as fakeRecord, f as fakeRecordText, g as TEST_PROVIDERS_FLAG, h as FakeOnchainProvider, i as TEST_IDENTITIES_FLAG, l as fakeKeySubject, m as FakeLightningProvider, n as FAKE_ISSUER, o as fakeAccountToken, p as testIdentitiesEnabled, r as FAKE_RECORD_HOST, s as fakeKey, t as FAKE_IDENTITY_PROVIDERS, u as fakeKeyring, v as fakeInvoice, x as testProvidersEnabled, y as fakeLightning } from "./fakes-
|
|
3
|
+
import { i as verifyIdentity, r as descriptorProblems } from "./verify-afQj9kHW.js";
|
|
4
|
+
import { _ as fakeAddress, a as fakeAccount, b as fakeOnchain, c as fakeKeySign, d as fakeRecord, f as fakeRecordText, g as TEST_PROVIDERS_FLAG, h as FakeOnchainProvider, i as TEST_IDENTITIES_FLAG, l as fakeKeySubject, m as FakeLightningProvider, n as FAKE_ISSUER, o as fakeAccountToken, p as testIdentitiesEnabled, r as FAKE_RECORD_HOST, s as fakeKey, t as FAKE_IDENTITY_PROVIDERS, u as fakeKeyring, v as fakeInvoice, x as testProvidersEnabled, y as fakeLightning } from "./fakes-BlpK1WuW.js";
|
|
5
5
|
import { afterEach, describe, expect, it, vi } from "vitest";
|
|
6
6
|
//#region ../browser/src/engine/paymentAdapters/providers/contractSuite.ts
|
|
7
7
|
var WAIT = 1e4;
|
|
@@ -150,8 +150,36 @@ export type AppBundleReading = {
|
|
|
150
150
|
reason: AppBundleRefusal;
|
|
151
151
|
detail?: string;
|
|
152
152
|
};
|
|
153
|
+
/**
|
|
154
|
+
* Lets the thread go for one turn: what waits (input, drawing, timers, port messages, IndexedDB answers) runs, then the
|
|
155
|
+
* caller goes on. A message to itself, queued behind the page's other tasks. Never `scheduler.yield()`: in Chromium its
|
|
156
|
+
* continuation outranks every normal task, so a paced read of 4096 revocations held the page's timers, its apps' broker
|
|
157
|
+
* ports and IndexedDB for the whole 1.8 s. Never `setTimeout(0)` but as the last resort: from the fifth nested timer on
|
|
158
|
+
* the browser waits at least 4 ms (HTML's clamp), which made that read take 60% longer than the work, and a hidden tab
|
|
159
|
+
* runs timers once a second.
|
|
160
|
+
*/
|
|
161
|
+
export declare function yieldThread(): Promise<void>;
|
|
162
|
+
/**
|
|
163
|
+
* A pause for a loop of short steps: `await pause()` after each step lets the thread go once `sliceMs` of work has
|
|
164
|
+
* run since the last time, and answers at once otherwise.
|
|
165
|
+
*/
|
|
166
|
+
export declare function pacer(sliceMs: number): () => Promise<void> | undefined;
|
|
167
|
+
/**
|
|
168
|
+
* SHA-256 of bytes that may be a whole bundle, for a client whose engine shares its page's thread: `sha256` in
|
|
169
|
+
* JavaScript takes about 12 ms per MiB on a desktop CPU, so 16 MiB in one run is a page that draws nothing and takes no
|
|
170
|
+
* input for 200 ms. With `crypto.subtle` the bytes are hashed off the thread; without it (a page not served over
|
|
171
|
+
* HTTPS), a slice at a time with a pause between slices. The bytes must not change until it answers.
|
|
172
|
+
*/
|
|
173
|
+
export declare function sha256Paced(bytes: Uint8Array): Promise<Uint8Array>;
|
|
153
174
|
/** Reads and checks a bundle (the order of the checks is part of the format: see above). */
|
|
154
175
|
export declare function readAppBundle(bytes: Uint8Array): AppBundleReading;
|
|
176
|
+
/**
|
|
177
|
+
* `readAppBundle` for a client whose engine shares its page's thread: the same checks in the same order, with the same
|
|
178
|
+
* refusals, and each file hashed by `sha256Paced`, one after the other, with the thread let go between files every
|
|
179
|
+
* `HASH_SLICE_MS` (64 files of 64 KiB, each hashed at once, held it for 50 ms). The bytes must not change until it
|
|
180
|
+
* answers.
|
|
181
|
+
*/
|
|
182
|
+
export declare function readAppBundleAsync(bytes: Uint8Array): Promise<AppBundleReading>;
|
|
155
183
|
/** Puts a bundle's parts together, checking nothing: for builders, and for tests that need a broken bundle. */
|
|
156
184
|
export declare function assembleAppBundle(manifestBytes: Uint8Array, statementBytes: Uint8Array, files: Uint8Array[]): Uint8Array;
|
|
157
185
|
/** What a publisher writes: every manifest field but `publisher` and `files`, which the bundle's contents decide. */
|
|
@@ -28,6 +28,11 @@ export declare const FILE_LIMITS: {
|
|
|
28
28
|
readonly chunkBytes: number;
|
|
29
29
|
/** Bytes a sender has sent and not seen confirmed: throughput is this per round trip. */
|
|
30
30
|
readonly windowBytes: number;
|
|
31
|
+
/**
|
|
32
|
+
* Bytes all of a chat's files have sent and not seen confirmed, together. Three files' windows at once were 3 MiB, and
|
|
33
|
+
* as base64 text past what a session's receive queue holds (`SESSION_RECEIVE_PENDING`, 3.75 MiB).
|
|
34
|
+
*/
|
|
35
|
+
readonly chatWindowBytes: number;
|
|
31
36
|
/** A receiver asks its person before taking a file larger than this. */
|
|
32
37
|
readonly askAboveBytes: number;
|
|
33
38
|
/** Files taken without asking, per contact, while stored. Past it, every file is asked about. */
|
|
@@ -134,6 +139,11 @@ export type RefuseReason = "declined" | "no-room" | "too-many" | "damaged" | "ca
|
|
|
134
139
|
export interface ChatFilesHost {
|
|
135
140
|
/** Sends a frame on the open session; false when there is none. */
|
|
136
141
|
send(frame: Record<string, unknown>): boolean;
|
|
142
|
+
/**
|
|
143
|
+
* Sends a file's bytes at `offset` in the form the open session agreed (WISP 501 § files/4): a binary message, or
|
|
144
|
+
* the `pf-data` frame; false when there is no session or it has no room. A host without it gets `pf-data` through `send`.
|
|
145
|
+
*/
|
|
146
|
+
sendData?(id: string, offset: number, data: Uint8Array): boolean;
|
|
137
147
|
/**
|
|
138
148
|
* A new offer from the contact: take it, ask the person, or refuse it. `again`: a file taken here without asking
|
|
139
149
|
* that ended (failed, or stopped by the sender) and is offered again; it counts against the same limits as a new one.
|
|
@@ -162,6 +172,21 @@ export interface ChatFilesHost {
|
|
|
162
172
|
resend?(record: FileTransferRecord, sent: number): boolean;
|
|
163
173
|
now?(): number;
|
|
164
174
|
}
|
|
175
|
+
/**
|
|
176
|
+
* files/4 (WISP 501 § files/4): a chunk as one binary message of the session, in place of the base64url text of a
|
|
177
|
+
* `pf-data` frame, which is a third more than the bytes it carries:
|
|
178
|
+
*
|
|
179
|
+
* kind 0x04 (1) | id length (1) | id (ASCII) | offset (8, big endian) | data (1 to `FILE_LIMITS.chunkBytes`)
|
|
180
|
+
*/
|
|
181
|
+
export declare const FILE_DATA_KIND = 4;
|
|
182
|
+
/** The binary message for the bytes of file `id` at `offset`. Throws on what no receiver would take. */
|
|
183
|
+
export declare function encodeFileData(id: string, offset: number, data: Uint8Array): Uint8Array;
|
|
184
|
+
/** What a binary message from the contact says, or null when it is not a well-formed file data message. `data` is a view of `message`. */
|
|
185
|
+
export declare function decodeFileData(message: Uint8Array): {
|
|
186
|
+
id: string;
|
|
187
|
+
offset: number;
|
|
188
|
+
data: Uint8Array;
|
|
189
|
+
} | null;
|
|
165
190
|
/** What a refusal means to the sender's person. */
|
|
166
191
|
export declare function refusalText(why: string, room?: number): {
|
|
167
192
|
state: TransferState;
|
|
@@ -170,6 +195,10 @@ export declare function refusalText(why: string, room?: number): {
|
|
|
170
195
|
export declare class ChatFiles {
|
|
171
196
|
private readonly host;
|
|
172
197
|
private readonly entries;
|
|
198
|
+
/** Files sending that may have bytes not confirmed yet: what `inFlight` adds up (the rest are left out as it goes). */
|
|
199
|
+
private readonly moving;
|
|
200
|
+
/** Files that stopped sending for the chat's window alone: they go on once another's bytes are confirmed. */
|
|
201
|
+
private readonly held;
|
|
173
202
|
private attached;
|
|
174
203
|
private peerRoomValue;
|
|
175
204
|
constructor(host: ChatFilesHost);
|
|
@@ -188,6 +217,7 @@ export declare class ChatFiles {
|
|
|
188
217
|
private moved;
|
|
189
218
|
private changed;
|
|
190
219
|
private send;
|
|
220
|
+
private sendData;
|
|
191
221
|
/** A session that agreed files/3 is open: say what fits here, then offer again what is not finished. */
|
|
192
222
|
attach(): void;
|
|
193
223
|
/** The session went: nothing moves until the next one. What was received is made durable. */
|
|
@@ -202,7 +232,13 @@ export declare class ChatFiles {
|
|
|
202
232
|
private armStall;
|
|
203
233
|
private source;
|
|
204
234
|
private chunkAt;
|
|
235
|
+
/** Whether this file's own window lets it send more. */
|
|
236
|
+
private fileMayPump;
|
|
205
237
|
private shouldPump;
|
|
238
|
+
/** Bytes this chat's files sent and have not seen confirmed. */
|
|
239
|
+
private inFlight;
|
|
240
|
+
/** Bytes were confirmed, or a file stopped sending: the files the chat's window held go on, before the one that freed it. */
|
|
241
|
+
private wakeHeld;
|
|
206
242
|
/**
|
|
207
243
|
* Whether the next `length` bytes go. Within the file's size they always do; past it the receiver is having parts
|
|
208
244
|
* sent again, which nothing it says bounds, so this side does.
|
|
@@ -220,7 +256,11 @@ export declare class ChatFiles {
|
|
|
220
256
|
*/
|
|
221
257
|
private discardStored;
|
|
222
258
|
private target;
|
|
223
|
-
/**
|
|
259
|
+
/**
|
|
260
|
+
* An accepted file goes when a session is open and fewer than three others arrive at once. One whose target is still
|
|
261
|
+
* being opened counts among the three: counted only once active, every file offered or queued meanwhile went too, and
|
|
262
|
+
* the windows of ten files and more at once overflowed the session's receive queue.
|
|
263
|
+
*/
|
|
224
264
|
private startIncoming;
|
|
225
265
|
/** The next file waiting its turn, once one ends. */
|
|
226
266
|
private startNext;
|
|
@@ -66,7 +66,9 @@ export declare const CONNECT_TIMEOUT_MS = 90000;
|
|
|
66
66
|
* settle); where they do not, every offer of a first pairing waited the full 5 s, twice when the inviter offered too
|
|
67
67
|
* (One's e2e runs: 13 offers of 89 at 5 s, 9 more at 1.3-3 s, 2026-10-05). An offer without one still connects to most
|
|
68
68
|
* contacts (their checks learn this side's address from its own); behind a restricted NAT on the contact's side it may
|
|
69
|
-
* not, and the next offer of the chat then waits as long as it takes (`fullGather`).
|
|
69
|
+
* not, and the next offer of the chat then waits as long as it takes (`fullGather`). An answer is bounded the same way:
|
|
70
|
+
* it waited the full 5 s, and two CLI daemons whose STUN server swallowed every request went live 10 s after the offer
|
|
71
|
+
* rather than 2 s (calls bug hunt, 2026-10-12).
|
|
70
72
|
*/
|
|
71
73
|
export declare const OFFER_HOST_GATHER_MS = 2000;
|
|
72
74
|
/** The data link keeps collecting this long after the candidate it waited for came (a call keeps 400 ms). */
|
|
@@ -101,12 +103,13 @@ export declare class DataLink {
|
|
|
101
103
|
private pc;
|
|
102
104
|
private myOfferTs;
|
|
103
105
|
/**
|
|
104
|
-
* An offer of this side's that went without a public candidate came to nothing (
|
|
105
|
-
* connected): the next one waits for its STUN servers as long as it takes
|
|
106
|
+
* An offer or answer of this side's that went without a public candidate came to nothing (both descriptions were
|
|
107
|
+
* exchanged, and no path connected): the next one waits for its STUN servers as long as it takes
|
|
108
|
+
* (`ICE_GATHERING_TIMEOUT_MS`).
|
|
106
109
|
*/
|
|
107
110
|
private fullGather;
|
|
108
|
-
/** The offer out has no public candidate (as it went: the connection's description gains any that come later). */
|
|
109
|
-
private
|
|
111
|
+
/** The offer or answer out has no public candidate (as it went: the connection's description gains any that come later). */
|
|
112
|
+
private sentLacksPublic;
|
|
110
113
|
private lastSignalTs;
|
|
111
114
|
/** The peer's description as this connection was given it: Chrome shows it as `remoteDescription` only once applied. */
|
|
112
115
|
private remoteSdp;
|
|
@@ -148,7 +151,10 @@ export declare class DataLink {
|
|
|
148
151
|
*/
|
|
149
152
|
get fingerprints(): [string, string] | null;
|
|
150
153
|
close(): void;
|
|
151
|
-
/**
|
|
154
|
+
/**
|
|
155
|
+
* This side's offer went with no public candidate and was answered, or its answer went with none, and it came to
|
|
156
|
+
* nothing: the next offer or answer gathers for as long as it takes.
|
|
157
|
+
*/
|
|
152
158
|
private noteNoPublic;
|
|
153
159
|
/**
|
|
154
160
|
* What this attempt says about direct connections if it ends now without opening: nothing unless both descriptions
|
|
@@ -159,7 +165,7 @@ export declare class DataLink {
|
|
|
159
165
|
/**
|
|
160
166
|
* The attempt on this connection failed (it timed out, ICE failed or closed, its channel closed). An answer the
|
|
161
167
|
* offerer may not have read yet is made again for the same offer while it still stands (`REANSWERS`); anything
|
|
162
|
-
* else goes back to idle.
|
|
168
|
+
* else goes back to idle. `byConnection`: the connection said so itself, rather than a timer of this link's.
|
|
163
169
|
*/
|
|
164
170
|
private failed;
|
|
165
171
|
/** The answer to this side's offer did not go in (`ANSWER_REFUSED_REDIALS`): the attempt ends, and the caller may offer again now. */
|
|
@@ -141,6 +141,10 @@ export declare const emptyDhtDeliveryState: () => DhtDeliveryState;
|
|
|
141
141
|
export declare class DhtDelivery {
|
|
142
142
|
private readonly options;
|
|
143
143
|
private state;
|
|
144
|
+
/** The state as last saved: a save that would write the same row again is skipped. */
|
|
145
|
+
private saved?;
|
|
146
|
+
/** The sequence of the last envelope signed here; the state's is the highest set aside (`SEQUENCE_BLOCK`). */
|
|
147
|
+
private sequence;
|
|
144
148
|
private mode;
|
|
145
149
|
private running;
|
|
146
150
|
private ticking;
|
|
@@ -151,6 +155,7 @@ export declare class DhtDelivery {
|
|
|
151
155
|
private fastUntil;
|
|
152
156
|
private live;
|
|
153
157
|
private active;
|
|
158
|
+
private readonly startedAt;
|
|
154
159
|
/** The next read was asked for (a refresh, a fresh packet of the contact): it is not a background one. */
|
|
155
160
|
private urgent;
|
|
156
161
|
/** Reads left that are signaling: the contact is leaving DHT only, and the live link waits on them (`expect`). */
|
|
@@ -235,6 +240,8 @@ export declare class DhtDelivery {
|
|
|
235
240
|
* 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
241
|
*/
|
|
237
242
|
firstControlAfterMs?: number;
|
|
243
|
+
/** This side made the invite, then: once no longer awaited, its mailbox is read less often while nobody uses it (`unusedInviteWait`). */
|
|
244
|
+
inviteMadeAt?: number;
|
|
238
245
|
});
|
|
239
246
|
get view(): DhtDeliveryView;
|
|
240
247
|
/**
|
|
@@ -381,6 +388,8 @@ export declare class DhtDelivery {
|
|
|
381
388
|
private publishOnTick;
|
|
382
389
|
/** How long until the next read of the contact's mailbox (WISP 403, poll pace). */
|
|
383
390
|
get pollMs(): number;
|
|
391
|
+
/** How long ago this side's invite was made, while nobody used it and it is no longer awaited (`AWAITING_PEER_MS`). */
|
|
392
|
+
private unusedInviteAge;
|
|
384
393
|
private schedule;
|
|
385
394
|
}
|
|
386
395
|
export declare const DHT_TEXT_REFUSED = "Your contact's app does not accept text over the DHT. It is sent when you are live.";
|
|
@@ -24,6 +24,7 @@ export declare const ENGINE_ERRORS: {
|
|
|
24
24
|
readonly notEnoughSats: "Not enough sats in your wallet";
|
|
25
25
|
readonly noSharedMint: "You share no mint with this contact";
|
|
26
26
|
readonly ecashAlreadySpent: "This ecash was already spent somewhere else";
|
|
27
|
+
readonly ecashBeingReceived: "This ecash is already being received";
|
|
27
28
|
readonly ecashOtherUnit: "This ecash is in {unit}: only sat ecash can be redeemed here";
|
|
28
29
|
readonly reviewedEcashSpent: "The ecash for this payment was already spent somewhere else. Nothing was sent, and your balance now shows what the mint still holds.";
|
|
29
30
|
readonly reviewedSatsGone: "The sats this payment was reviewed with went to another payment. Nothing was sent: review it again.";
|
|
@@ -202,6 +202,11 @@ export interface FrameChannel {
|
|
|
202
202
|
* WebRTC data channel does, and a sender only keeps under `LIMITS.sendHighWaterMark`.
|
|
203
203
|
*/
|
|
204
204
|
readonly sendBudget?: number;
|
|
205
|
+
/**
|
|
206
|
+
* It carries binary messages as well as text (WISP 100 § Text and binary messages): a WebRTC data channel does.
|
|
207
|
+
* Absent: text only, as the Iroh channels are, and nothing binary is offered or sent on it.
|
|
208
|
+
*/
|
|
209
|
+
readonly binary?: boolean;
|
|
205
210
|
close(): void;
|
|
206
211
|
onMessage: ((data: string | Uint8Array) => void) | null;
|
|
207
212
|
onClose: (() => void) | null;
|
|
@@ -31,14 +31,29 @@ import { type PairingProgress, type PairingRole } from "./pairingProgress.js";
|
|
|
31
31
|
export declare const DHT_PIN_GRACE_MS = 10000;
|
|
32
32
|
/** Back after a restart (`resume`), dials wait this long at most for the native endpoint that carried the chat to start. */
|
|
33
33
|
export declare const RESUME_WAIT_MS = 10000;
|
|
34
|
-
/**
|
|
35
|
-
|
|
34
|
+
/**
|
|
35
|
+
* Two dials crossing: how long the lower key's side waits for its own to connect before it takes the contact's. Two
|
|
36
|
+
* dials that both go through connect within a round trip of each other: each side's preface goes out as the other's
|
|
37
|
+
* dial reaches it. One not connected by then has stalled (a HyperDHT stream that opened and carries nothing, dialled
|
|
38
|
+
* again only 2 s later) or goes to an endpoint the contact no longer runs: waiting for it held a working connection
|
|
39
|
+
* back 0.9-1.9 s (DHT-direct lab, 5 of 20 first pairings). Taken, this side's dial is closed when it lands, and on the
|
|
40
|
+
* contact's side it never authenticates (`attachReplacement`).
|
|
41
|
+
*/
|
|
42
|
+
export declare const CROSSED_WAIT_MS = 500;
|
|
36
43
|
/**
|
|
37
44
|
* A session this side dialled this recently is one a crossing dial of the contact's may meet (both connected): the
|
|
38
45
|
* lower key keeps its own. Older, the session is one the contact has since lost (its app restarted), and its dial
|
|
39
46
|
* takes over.
|
|
40
47
|
*/
|
|
41
48
|
export declare const CROSSED_FRESH_MS = 10000;
|
|
49
|
+
/**
|
|
50
|
+
* A dial of the contact's that meets such a session waits this long for that session to answer a ping. It answers when
|
|
51
|
+
* the dials crossed (the contact holds this side's dial too); it does not when the contact's app ended since and is
|
|
52
|
+
* back: its dial then takes over. Refused outright, that dial left the contact waiting for the dead session's end, 16.6
|
|
53
|
+
* to 18.9 s (CLI daemons over HyperDHT, the contact killed 1 to 3 s after this side's knock, 5 of 5). A round trip is
|
|
54
|
+
* 7 ms on loopback and under 0.5 s over a relayed Iroh.
|
|
55
|
+
*/
|
|
56
|
+
export declare const CROSSED_PROBE_MS = 1500;
|
|
42
57
|
/** A joiner gathers its offer while it first looks for the inviter (`dialEarly`) only this soon after the join. */
|
|
43
58
|
export declare const EARLY_DIAL_JOIN_MS = 60000;
|
|
44
59
|
/** What a joiner is told when someone else used the invite first (`DhtDeliveryView.inviteTaken`). */
|
|
@@ -359,7 +374,10 @@ export interface GhostLinkEvents {
|
|
|
359
374
|
onFileProgress?(fileId: string, transferred: number, direction: "in" | "out"): void;
|
|
360
375
|
onFileComplete?(fileId: string, direction: "in" | "out"): void;
|
|
361
376
|
onFileFailed?(fileId: string, reason: string, direction: "in" | "out"): void;
|
|
362
|
-
/**
|
|
377
|
+
/**
|
|
378
|
+
* A files/3 frame (`FILE_FRAMES`), only while both sides agreed `files/3` on the open session. A file's data that came
|
|
379
|
+
* as a binary message (`files/4`) is the `pf-data` frame it stands for, its `data` the bytes themselves.
|
|
380
|
+
*/
|
|
363
381
|
onFilesFrame?(frame: Record<string, unknown>): void | Promise<void>;
|
|
364
382
|
/**
|
|
365
383
|
* files/3 can flow (a session agreed it and is open), or no longer can. Said again, open, after a live
|
|
@@ -417,6 +435,11 @@ export interface GhostLinkOptions {
|
|
|
417
435
|
servicesSupport?: boolean;
|
|
418
436
|
/** Offer `files/3` on paired sessions: files of any size, offered, resumed and checked (`chatFiles.ts`). */
|
|
419
437
|
largeFilesSupport?: boolean;
|
|
438
|
+
/**
|
|
439
|
+
* With `largeFilesSupport`, offer `files/4` on a session whose channel carries binary messages: a file's bytes as
|
|
440
|
+
* they are, not as text (WISP 501 § files/4). The owner's `onFilesFrame` then takes a `pf-data` whose `data` is bytes.
|
|
441
|
+
*/
|
|
442
|
+
binaryFilesSupport?: boolean;
|
|
420
443
|
/** Offer `typing/1` on paired sessions: say and show when either side is writing (1:1 chats, not group edges). */
|
|
421
444
|
typingSupport?: boolean;
|
|
422
445
|
/** Offer `react/1` on paired sessions: reactions to messages (1:1 chats, not group edges). */
|
|
@@ -700,10 +723,15 @@ export declare class GhostLink {
|
|
|
700
723
|
* was the app's in the background, not a restart (`resumeAfterAbsence`).
|
|
701
724
|
*/
|
|
702
725
|
private offered?;
|
|
726
|
+
/**
|
|
727
|
+
* The WebRTC offer this side's dial made last, fallback allowed or not: one made before the contact's record was read
|
|
728
|
+
* races once it is (`raceStandingOffer`).
|
|
729
|
+
*/
|
|
730
|
+
private offerMade?;
|
|
703
731
|
/** The attempt (its epoch) whose direct transports were knocked on as its offer went out (`knockEarly`), and whether that is under way. */
|
|
704
732
|
private knockedEarly;
|
|
705
733
|
private knockingEarly;
|
|
706
|
-
/** When
|
|
734
|
+
/** When this side's offer's answer was applied (`RACE_ANSWERED_MS`); 0 while the data link is not connecting on it. */
|
|
707
735
|
private answeredAt;
|
|
708
736
|
/** This side's offer is out unanswered, or answered and not connected yet: what is ranked after WebRTC may race it. */
|
|
709
737
|
private get offerOut();
|
|
@@ -1056,6 +1084,14 @@ export declare class GhostLink {
|
|
|
1056
1084
|
* it) or `RACE_RELAYED_MS` (a relayed one), those are dialled too, the offer standing meanwhile.
|
|
1057
1085
|
*/
|
|
1058
1086
|
private scheduleRace;
|
|
1087
|
+
/**
|
|
1088
|
+
* This side's offer went out before the contact's record was read (a joiner's early one, `dialEarly`): nothing was
|
|
1089
|
+
* known of what the contact runs, so it was made with no fallback and nothing raced it. Once the record says, and both
|
|
1090
|
+
* sides allow it, the offer races what both run as one made then would: answered and not connected `RACE_ANSWERED_MS`
|
|
1091
|
+
* later, the relayed ones too. Behind a VPN that drops UDP, a first pairing went live over the relayed Iroh only once
|
|
1092
|
+
* the attempt timed out and the next one raced, 32 to 66 s in (zero's VPN lab, 2026-10-13).
|
|
1093
|
+
*/
|
|
1094
|
+
private raceStandingOffer;
|
|
1059
1095
|
/**
|
|
1060
1096
|
* Back after an absence, this side answers an offer the contact made while it was away (it dials whatever its key):
|
|
1061
1097
|
* the contact looks for that answer at the pace of an offer out a while (every 8 s on the relays), and its attempt may
|
|
@@ -1101,6 +1137,16 @@ export declare class GhostLink {
|
|
|
1101
1137
|
* fast looks for the member's `_tr` end after a few (`PACKET_TRANSPORTS_FAST_ATTEMPTS`).
|
|
1102
1138
|
*/
|
|
1103
1139
|
private anythingToDial;
|
|
1140
|
+
/**
|
|
1141
|
+
* Neither side can dial the other until something changes, past a first pairing: what the contact runs is known, and
|
|
1142
|
+
* no transport both run has WebRTC on both sides or an endpoint up on both (this side's, and the one its record
|
|
1143
|
+
* describes). A chat that gave its listener up to another (`yieldEndpoint`), or whose contact did, is so. It dials
|
|
1144
|
+
* again when that changes (a listener taken back, `registerEndpoint`; the record describing one, `learnPeerTransports`),
|
|
1145
|
+
* and reads at its own pace meanwhile: looks every 20 s for a dial with nothing to try, and the contact's fast looks
|
|
1146
|
+
* for an offer that could not come, read its key 2.5x to 4x as often as the background pace, for good (bug hunt,
|
|
1147
|
+
* 2026-10-12). A first pairing keeps both: the records are what it is reading for.
|
|
1148
|
+
*/
|
|
1149
|
+
private nothingToDialEitherWay;
|
|
1104
1150
|
private clearRace;
|
|
1105
1151
|
/**
|
|
1106
1152
|
* The offer is still unanswered: the transports ranked after WebRTC that are due are dialled now, each once in this
|
|
@@ -1275,6 +1321,8 @@ export declare class GhostLink {
|
|
|
1275
1321
|
get supportsServices(): boolean;
|
|
1276
1322
|
/** Both sides offer `files/3` on the open session: files of any size, offered and resumed. */
|
|
1277
1323
|
get supportsLargeFiles(): boolean;
|
|
1324
|
+
/** Both sides offer `files/4` beside `files/3` on the open session: a file's bytes go as binary messages. */
|
|
1325
|
+
get supportsBinaryFiles(): boolean;
|
|
1278
1326
|
/** Both sides offer `typing/1` on the open session: typing can be said and shown. */
|
|
1279
1327
|
get supportsTyping(): boolean;
|
|
1280
1328
|
/** Both sides offer `react/1` on the open session: reactions can be said and confirmed here. */
|
|
@@ -1341,7 +1389,10 @@ export declare class GhostLink {
|
|
|
1341
1389
|
closeApp(app: string): void;
|
|
1342
1390
|
/**
|
|
1343
1391
|
* One data frame of an app open on both sides, on the live session only. An error when it did not go: nothing is
|
|
1344
|
-
* kept to send later.
|
|
1392
|
+
* kept to send later. While the channel already holds a quarter of what it may queue (its send budget, or the high
|
|
1393
|
+
* water mark of a WebRTC channel), the frame is refused with `too-fast`, so the chat's messages and pings never wait
|
|
1394
|
+
* behind an app's data on a link slower than it sends (WISP 1200 § In a chat). While a file goes, that quarter sits
|
|
1395
|
+
* above what files may hold (`filesWritable`): files keep the channel at their own line for the whole transfer.
|
|
1345
1396
|
*/
|
|
1346
1397
|
sendAppData(app: string, data: unknown): AppSendError | null;
|
|
1347
1398
|
/** What the contact had open is gone (`apps/1` is no longer agreed, or this link stopped): each app hears it now. */
|
|
@@ -1358,10 +1409,20 @@ export declare class GhostLink {
|
|
|
1358
1409
|
private emitFilesSession;
|
|
1359
1410
|
/** A files/3 frame to the contact, on the open session. False when files/3 cannot flow now. */
|
|
1360
1411
|
sendFilesFrame(frame: Record<string, unknown>): boolean;
|
|
1412
|
+
/**
|
|
1413
|
+
* A file's bytes to the contact, on the open session: one binary message while both sides agreed `files/4` on it,
|
|
1414
|
+
* the `pf-data` frame with them as base64url text otherwise (WISP 501 § files/4). The form is chosen for each chunk,
|
|
1415
|
+
* so a transfer follows the session it is on. False when files/3 cannot flow now, or the channel has no room.
|
|
1416
|
+
*/
|
|
1417
|
+
sendFileData(id: string, offset: number, data: Uint8Array): boolean;
|
|
1418
|
+
/** Files on a channel: when they last wrote on it, and how many wait for room. An app's data gets room above theirs. */
|
|
1419
|
+
private filesUse;
|
|
1420
|
+
private filesUsing;
|
|
1361
1421
|
/**
|
|
1362
1422
|
* Resolves once the open session can take another files/3 data frame; undefined when it can now. A channel with a send budget (native and
|
|
1363
1423
|
* iroh ones throw past 120 KiB) gives files a quarter of it, so a ping, a message or any other frame still fits
|
|
1364
|
-
* while a file goes; others keep under the high water mark, as files/2 does.
|
|
1424
|
+
* while a file goes; others keep under the high water mark, as files/2 does. An app's data gets a quarter above that
|
|
1425
|
+
* line meanwhile (`sendAppData`).
|
|
1365
1426
|
*/
|
|
1366
1427
|
filesWritable(): Promise<void> | undefined;
|
|
1367
1428
|
/** What each side offers on the open session, for showing why something is unavailable. `peer` is null until it says. */
|
|
@@ -1399,8 +1460,8 @@ export declare class GhostLink {
|
|
|
1399
1460
|
* Both sides dialled at once (two apps back after a restart, each knocking): the lower key's dial carries the chat, on
|
|
1400
1461
|
* both sides; the higher key's side takes it over as a replacement (`attachReplacement`). Here, on the lower key's
|
|
1401
1462
|
* side, the contact's connection waits: dropped once this side's own dial connects, taken if that dial fails, or has
|
|
1402
|
-
* not connected within `CROSSED_WAIT_MS` (
|
|
1403
|
-
*
|
|
1463
|
+
* not connected within `CROSSED_WAIT_MS` (it stalled, or goes to an endpoint the contact no longer runs, for as long
|
|
1464
|
+
* as it takes to give up).
|
|
1404
1465
|
*/
|
|
1405
1466
|
private crossed;
|
|
1406
1467
|
private parkCrossed;
|
|
@@ -1415,6 +1476,18 @@ export declare class GhostLink {
|
|
|
1415
1476
|
* Before the pin a held session keeps the chat, as it always did.
|
|
1416
1477
|
*/
|
|
1417
1478
|
private attachReplacement;
|
|
1479
|
+
private replaceWith;
|
|
1480
|
+
/**
|
|
1481
|
+
* The contact dialled in while this side's own fresh dial holds the chat (`CROSSED_FRESH_MS`): the dials crossed, or
|
|
1482
|
+
* the contact's app ended since that dial and is back. The held session is pinged; heard from within
|
|
1483
|
+
* `CROSSED_PROBE_MS`, the contact holds this side's dial too and its own closes. Not heard from, the contact's dial
|
|
1484
|
+
* takes over.
|
|
1485
|
+
*/
|
|
1486
|
+
private crossedProbe;
|
|
1487
|
+
/** Frames heard on the open session, counted from its start: whether the contact answered `probeCrossed`. */
|
|
1488
|
+
private framesHeard;
|
|
1489
|
+
private probeCrossed;
|
|
1490
|
+
private dropCrossedProbe;
|
|
1418
1491
|
/**
|
|
1419
1492
|
* Connections that came in on this side's native endpoints. Their address was in the capability record, which before
|
|
1420
1493
|
* the pin anyone holding a copy of the invite could read: a key other than the pinned one on such a connection proves
|
|
@@ -1423,6 +1496,8 @@ export declare class GhostLink {
|
|
|
1423
1496
|
private readonly dialedIn;
|
|
1424
1497
|
/** Connections whose session started with no key pinned nor named by the invite. */
|
|
1425
1498
|
private readonly openedUnpinned;
|
|
1499
|
+
/** The WebRTC offer under way was made or answered with no key pinned nor named by the invite (its channel opens later). */
|
|
1500
|
+
private rtcStartedUnpinned;
|
|
1426
1501
|
/**
|
|
1427
1502
|
* `migration`: the channel is a candidate that takes over from the session open now once it authenticated. With a
|
|
1428
1503
|
* `plan`, a live switch both sides agreed; without one, a replacement (`attachReplacement`): the contact dialled
|
|
@@ -59,6 +59,8 @@ export declare const COMMUNITY_LIMITS: {
|
|
|
59
59
|
/** Commits in one welcome or chain piece. */
|
|
60
60
|
readonly chainPiece: 100;
|
|
61
61
|
readonly pendingLeaves: 64;
|
|
62
|
+
/** Leaves whose mark (`group-left`) is kept, and the epochs one names. */
|
|
63
|
+
readonly leftMarks: 64;
|
|
62
64
|
/**
|
|
63
65
|
* Syncs of one member answered in `syncWindowMs`: each answer may carry the chain's tail, secrets and the whole
|
|
64
66
|
* store. A member catching up asks every five seconds at most, and every member syncs every thirty; one asking more
|
|
@@ -116,6 +118,8 @@ export declare function rosterHash(roster: Roster): string;
|
|
|
116
118
|
/** The id of a community group: from its creator and a nonce, so no other genesis can claim it. */
|
|
117
119
|
export declare function communityGroupId(creator: string, nonce: string): string;
|
|
118
120
|
export declare const leaveStatement: (g: string, s: string) => Uint8Array<ArrayBufferLike>;
|
|
121
|
+
/** What the member who committed a leave (`h`) had heard of the leaver then: `e:h16` → its highest number there. */
|
|
122
|
+
export declare const leftStatement: (g: string, h: string, hi: Record<string, number>) => Uint8Array<ArrayBufferLike>;
|
|
119
123
|
/** The secret of an epoch that adds, re-roles or re-links: from the previous one and the commit. */
|
|
120
124
|
export declare function derivedSecret(previous: Uint8Array, untaggedHash: string): Uint8Array;
|
|
121
125
|
/**
|
|
@@ -199,6 +203,18 @@ export interface CommunityLeaveFrame {
|
|
|
199
203
|
s: string;
|
|
200
204
|
ls: string;
|
|
201
205
|
}
|
|
206
|
+
/**
|
|
207
|
+
* The mark of a leave (`h`, the commit's full hash), signed by the member who committed it: how far it had heard the
|
|
208
|
+
* leaver in each epoch. What the leaver wrote past it is not taken (WISP 903 § Leaving and removal).
|
|
209
|
+
*/
|
|
210
|
+
export interface CommunityLeftFrame {
|
|
211
|
+
t: "group-left";
|
|
212
|
+
v: 2;
|
|
213
|
+
g: string;
|
|
214
|
+
h: string;
|
|
215
|
+
hi: Record<string, number>;
|
|
216
|
+
sig: string;
|
|
217
|
+
}
|
|
202
218
|
/** The seed of the link's current entry key, sealed to one member: after a `link` commit, or at a sync. */
|
|
203
219
|
export interface CommunityEntryFrame {
|
|
204
220
|
t: "group-entry";
|
|
@@ -236,7 +252,7 @@ export interface CommunityWelcomeFrame {
|
|
|
236
252
|
rv: SealedSecret;
|
|
237
253
|
entry: SealedSecret;
|
|
238
254
|
}
|
|
239
|
-
export type CommunityFrame = CommunityMessageFrame | CommunityCommitFrame | CommunitySecretFrame | CommunitySecretsFrame | CommunitySyncFrame | CommunityLeaveFrame | CommunityEntryFrame | GroupMetaFrame;
|
|
255
|
+
export type CommunityFrame = CommunityMessageFrame | CommunityCommitFrame | CommunitySecretFrame | CommunitySecretsFrame | CommunitySyncFrame | CommunityLeaveFrame | CommunityLeftFrame | CommunityEntryFrame | GroupMetaFrame;
|
|
240
256
|
export type CommunityStatus = "active" | "left" | "removed" | "forked" | "lost";
|
|
241
257
|
export interface CommunityState {
|
|
242
258
|
id: string;
|
|
@@ -286,6 +302,11 @@ export interface CommunityState {
|
|
|
286
302
|
s: string;
|
|
287
303
|
ls: string;
|
|
288
304
|
}[];
|
|
305
|
+
/** Leave commit (full hash) → its mark, as its committer signed it (`group-left`), oldest first. Absent in older states. */
|
|
306
|
+
left?: Record<string, {
|
|
307
|
+
hi: Record<string, number>;
|
|
308
|
+
sig: string;
|
|
309
|
+
}>;
|
|
289
310
|
/** The group's metadata (its picture), as the admin last signed it and I accepted it. */
|
|
290
311
|
meta?: GroupMeta;
|
|
291
312
|
}
|
|
@@ -467,6 +488,19 @@ export declare class CommunitySession {
|
|
|
467
488
|
/** When the chain took them out (the commit's time, by its signer's clock), if it did and they are not back in. */
|
|
468
489
|
outAt(key: string): number | undefined;
|
|
469
490
|
private outIndex;
|
|
491
|
+
/**
|
|
492
|
+
* Whether a frame of someone the chain took out is still heard. A member removed is heard no more, even for an epoch
|
|
493
|
+
* it was in. What one who left wrote while in the group is taken and handed on, its goodbye included, up to what the
|
|
494
|
+
* member who committed the leave had heard of it then (its `group-left` mark), never past it: the leaver still holds
|
|
495
|
+
* those epochs' secrets, and anything it signs later is not heard (WISP 903 § Leaving and removal). No mark here
|
|
496
|
+
* (one not come yet, or a committer's app before it) and nothing of it is heard.
|
|
497
|
+
*/
|
|
498
|
+
private heardAfterOut;
|
|
499
|
+
/** The mark of a leave on my branch, as a frame to hand on (see `heardAfterOut`). */
|
|
500
|
+
private leftFrame;
|
|
501
|
+
private keepLeft;
|
|
502
|
+
/** A leave's mark, from the member who committed it: kept when it is that member's, for a leave I hold. */
|
|
503
|
+
private receiveLeft;
|
|
470
504
|
/**
|
|
471
505
|
* What someone the chain took out is told when it comes back (WISP 903 § Leaving and removal): the commits from where
|
|
472
506
|
* it says it is (`sync`: its tip, or its locator) up to the one that took it out, and nothing after. Later commits
|
|
@@ -571,6 +605,8 @@ export declare class CommunitySession {
|
|
|
571
605
|
leave(): Promise<CommunityLeaveFrame | null>;
|
|
572
606
|
/** Commits the leave requests I hold whose members are still in: the engine calls this on hubs. */
|
|
573
607
|
commitPendingLeaves(now?: number): Promise<number>;
|
|
608
|
+
/** Signs and says how far I had heard a member whose leave I just committed (`group-left`). */
|
|
609
|
+
private markLeft;
|
|
574
610
|
private out;
|
|
575
611
|
/**
|
|
576
612
|
* `mentions`: places of the text that name members, sealed with it (`m`). Never everyone in a community. They
|
|
@@ -31,8 +31,12 @@ export declare const GROUP_FILE_LIMITS: {
|
|
|
31
31
|
readonly heardAhead: 256;
|
|
32
32
|
/** Message ids in one `group-have`. */
|
|
33
33
|
readonly haveIds: 32;
|
|
34
|
-
/**
|
|
35
|
-
|
|
34
|
+
/**
|
|
35
|
+
* `group-have` frames a private group's edge takes in `haveWindowMs`: what is to say is gathered for a second, then
|
|
36
|
+
* goes. A community's, from a member, goes every `communityHaveEveryMs`.
|
|
37
|
+
*/
|
|
38
|
+
readonly haveFrames: 10;
|
|
39
|
+
readonly haveWindowMs: 10000;
|
|
36
40
|
readonly communityHaveEveryMs: 60000;
|
|
37
41
|
/**
|
|
38
42
|
* How long a want waits for an offer before the next holder is asked; a transfer that does not move for as long is
|