@ghostlytools/sdk 1.10.0 → 1.10.2
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/core.js +2 -2
- package/dist/{fakes-BTB2ugB3.js → fakes-Bj5HAJFV.js} +2 -2
- package/dist/{fakes-BTB2ugB3.js.map → fakes-Bj5HAJFV.js.map} +1 -1
- package/dist/fakes.js +1 -1
- package/dist/index.js +2 -2
- package/dist/index.js.map +1 -1
- package/dist/{keet-identity-key-a4pR0QSm.js → keet-identity-key-BgbqG2dL.js} +2 -2
- package/dist/{keet-identity-key-a4pR0QSm.js.map → keet-identity-key-BgbqG2dL.js.map} +1 -1
- package/dist/{src-BZy4lDju.js → src-DHR2fUGx.js} +2383 -1662
- package/dist/src-DHR2fUGx.js.map +1 -0
- package/dist/testing.js +3 -3
- package/dist/types/browser/src/proofs/contract.d.ts +18 -2
- package/dist/types/core/src/callSignal.d.ts +16 -0
- package/dist/types/core/src/datalink.d.ts +37 -0
- package/dist/types/core/src/engineErrors.d.ts +1 -0
- package/dist/types/core/src/ghostlink.d.ts +16 -1
- package/dist/types/core/src/groupCommunity.d.ts +33 -2
- package/dist/types/core/src/groupSession.d.ts +53 -3
- package/dist/types/core/src/identityProofs.d.ts +8 -0
- package/dist/types/core/src/link.d.ts +43 -4
- package/dist/types/core/src/pairedTransports.d.ts +8 -0
- package/dist/types/core/src/pairedWake.d.ts +2 -1
- package/dist/types/core/src/relay.d.ts +54 -7
- package/dist/types/core/src/transport.d.ts +5 -2
- package/dist/types/core/src/videoMetadata.d.ts +3 -1
- package/dist/types/core/src/webPush.d.ts +15 -6
- package/dist/{verify-Bcd7K4q-.js → verify-aVAh4GtV.js} +2 -2
- package/dist/{verify-Bcd7K4q-.js.map → verify-aVAh4GtV.js.map} +1 -1
- package/package.json +1 -1
- package/dist/src-BZy4lDju.js.map +0 -1
package/dist/testing.js
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import { Bu as newIdentityBinding, Lu as identityStatement, Nu as emptyIdentityLedger, ia as isBitcoinAddress, ju as IdentityExchange, jw as createIdentity, ka as decodeBolt11, xu as IDENTITY_MAX_EVIDENCE } from "./src-DHR2fUGx.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-aVAh4GtV.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-Bj5HAJFV.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;
|
|
@@ -36,6 +36,17 @@ export interface IdentityFetchResponse {
|
|
|
36
36
|
bytes: Uint8Array;
|
|
37
37
|
}
|
|
38
38
|
export type IdentityFetch = (url: string, options?: IdentityFetchOptions) => Promise<IdentityFetchResponse>;
|
|
39
|
+
/**
|
|
40
|
+
* How a provider says a line it works out when it runs (a step naming the person's domain, a progress line) in the
|
|
41
|
+
* app's language: `key` names the line within the provider, `english` is the line itself with `{{name}}` for each of
|
|
42
|
+
* `values`. The UI reads a built-in provider's line under `identities.providers.<provider id>.<key>`, with `english`
|
|
43
|
+
* when its language has none; a provider written outside the app (a plugin) always gets its `english` back, filled in.
|
|
44
|
+
* Its fixed words (`label`, `summary`, a signer's `description`…) need no call: the UI reads them by the same rule,
|
|
45
|
+
* under their own path (`subject.help`, `signers.<signer id>.label`, `signers.<signer id>.fields.<name>.help`).
|
|
46
|
+
*/
|
|
47
|
+
export type ProviderSay = (key: string, english: string, values?: Readonly<Record<string, string | number>>) => string;
|
|
48
|
+
/** `english` with its `{{name}}`s filled in: what `ProviderSay` returns where no app language is at hand (the CLI, tests). */
|
|
49
|
+
export declare const englishSay: ProviderSay;
|
|
39
50
|
export interface VerifyContext {
|
|
40
51
|
/** Seconds. Use this, never `Date.now()`, so tests and re-checks agree on time. */
|
|
41
52
|
now: number;
|
|
@@ -64,6 +75,7 @@ export interface SubjectSpec {
|
|
|
64
75
|
*/
|
|
65
76
|
preview?(subject: string, options: {
|
|
66
77
|
signal: AbortSignal;
|
|
78
|
+
say?: ProviderSay;
|
|
67
79
|
}): Promise<SubjectPreview>;
|
|
68
80
|
}
|
|
69
81
|
export interface SubjectPreview {
|
|
@@ -112,6 +124,8 @@ export interface SignerContext {
|
|
|
112
124
|
onProgress(message: string): void;
|
|
113
125
|
/** The signer waits for an approval elsewhere (`null`: it no longer does). The UI renders it; see `ApprovalRequest`. */
|
|
114
126
|
onApproval?(request: ApprovalRequest | null): void;
|
|
127
|
+
/** Says the signer's progress lines and approval words in the app's language; `englishSay` when absent. */
|
|
128
|
+
say?: ProviderSay;
|
|
115
129
|
}
|
|
116
130
|
export interface SignerSession<E> {
|
|
117
131
|
/** The identity the signer controls, canonical (as `subject.normalize` returns it). */
|
|
@@ -154,7 +168,8 @@ export interface InAppSigner<E> extends SignerBase {
|
|
|
154
168
|
/** The person runs a tool (ssh-keygen, gpg, a Bitcoin wallet) on the statement and pastes the output back. */
|
|
155
169
|
export interface ExternalToolSigner<E> extends SignerBase {
|
|
156
170
|
kind: "external-tool";
|
|
157
|
-
|
|
171
|
+
/** `say`: the steps in the app's language (`englishSay` when absent). */
|
|
172
|
+
instructions(statement: IdentityStatement, say?: ProviderSay): SignerInstructions;
|
|
158
173
|
/** What was pasted, as evidence. Throw a message the person can act on ("That is not an SSH signature"). */
|
|
159
174
|
parse(pasted: string, statement: IdentityStatement): E | Promise<E>;
|
|
160
175
|
}
|
|
@@ -166,7 +181,8 @@ export interface RedirectSigner<E> extends SignerBase {
|
|
|
166
181
|
/** The person publishes something the verifier fetches (a DNS TXT record, a /.well-known file). */
|
|
167
182
|
export interface PublishSigner<E> extends SignerBase {
|
|
168
183
|
kind: "publish";
|
|
169
|
-
|
|
184
|
+
/** `say`: the steps in the app's language (`englishSay` when absent). */
|
|
185
|
+
instructions(statement: IdentityStatement, say?: ProviderSay): SignerInstructions;
|
|
170
186
|
/** Usually small or empty: the verifier looks the record up itself. */
|
|
171
187
|
evidence(statement: IdentityStatement): E | Promise<E>;
|
|
172
188
|
}
|
|
@@ -170,12 +170,28 @@ export declare function extractParamsFromSdp(sdp: string, { maxCandidates, loopb
|
|
|
170
170
|
}): Partial<CallSignal>;
|
|
171
171
|
/** Offers, answers and hang-ups older (or further in the future) than this are ignored. */
|
|
172
172
|
export declare const CALL_SIGNAL_MAX_AGE_MS = 120000;
|
|
173
|
+
/**
|
|
174
|
+
* A call that comes this soon after the contact's last missed one does not ring, when that one barely rang
|
|
175
|
+
* (`BURST_RING_MS`): a bot looping call and hang-up does that (1,375 calls a minute), no person does. It is kept as a
|
|
176
|
+
* missed call, and the wait starts over with it, so a burst rings once and a call placed after a pause rings again.
|
|
177
|
+
* A person's call that rang a while, then was cancelled or rang out, holds nothing back: calling again at once (voice to
|
|
178
|
+
* video, a slip of the finger) rings. The apps (`useWebRTC`) and the headless CLI's call manager both keep it.
|
|
179
|
+
*/
|
|
180
|
+
export declare const QUICK_REDIAL_MS = 2000;
|
|
181
|
+
/** A missed call that rang shorter than this was not a person's (`QUICK_REDIAL_MS`). */
|
|
182
|
+
export declare const BURST_RING_MS = 1000;
|
|
173
183
|
/**
|
|
174
184
|
* A signal dated further ahead of this clock than this is not taken, however it was heard. A receiver acts on a signal
|
|
175
185
|
* only when its `ts` is later than the last one it acted on: taken, a signal dated a day ahead would be that last one,
|
|
176
186
|
* and every offer, answer and hang-up its sender made afterwards would be dropped as older, until the app started again.
|
|
177
187
|
*/
|
|
178
188
|
export declare const CALL_SIGNAL_FUTURE_MS: number;
|
|
189
|
+
/**
|
|
190
|
+
* Whether a contact's candidate address may go into this device's remote description: an IPv4 or IPv6 literal, or the
|
|
191
|
+
* `<uuid>.local` name a browser gives its host candidate. Any other name would have this side's ICE agent look it up in
|
|
192
|
+
* DNS, a request the contact chose, whatever the relay policy says.
|
|
193
|
+
*/
|
|
194
|
+
export declare function isCandidateAddress(address: string): boolean;
|
|
179
195
|
/**
|
|
180
196
|
* Validates an untrusted `_call` signal (from the Pkarr record or a `call`
|
|
181
197
|
* frame). Every value that ends up in the rebuilt SDP is checked against an
|
|
@@ -14,6 +14,12 @@ export interface DataLinkOptions {
|
|
|
14
14
|
createPeerConnection: () => RTCPeerConnection;
|
|
15
15
|
/** Publishes (or clears, with null) my `_rtc` record. */
|
|
16
16
|
publishSignal: (signal: string | null) => void;
|
|
17
|
+
/**
|
|
18
|
+
* Whether a signal of this side went out in this attempt: a relay (or the authenticated channel) took it. An answer
|
|
19
|
+
* the relays' budget held back the whole attempt never reached the offerer, so its failing says nothing of the
|
|
20
|
+
* network (agents#1637). Left out: every signal counts as out.
|
|
21
|
+
*/
|
|
22
|
+
signalOut?: () => boolean;
|
|
17
23
|
/** Signaling in progress (or over): look fast for the peer's signal. `offer`: for the answer to this side's offer. */
|
|
18
24
|
setFastPoll: (fast: boolean, offer?: boolean) => void;
|
|
19
25
|
onOpen: (channel: FrameChannel) => void;
|
|
@@ -97,6 +103,17 @@ export declare const REANSWERS = 2;
|
|
|
97
103
|
* backoff (meshSignals, PR #1363). Offers through members cost no relay request; over the relays four is still a few.
|
|
98
104
|
*/
|
|
99
105
|
export declare const ANSWER_REFUSED_REDIALS = 4;
|
|
106
|
+
/**
|
|
107
|
+
* An answer to this side's offer that comes this long or more after the offer reached the relays was read late (the
|
|
108
|
+
* relays' request budget held the read back, a restart's first minute), and an attempt that ends after this side made
|
|
109
|
+
* its answer again (`REANSWERS`) this long after it took an offer that still stands answered one the offerer has not
|
|
110
|
+
* read yet. Neither says anything about direct connections (`DirectEvidence`): the answering side's ICE gives up about
|
|
111
|
+
* 30 s after its answer with no reply, so the answer that went in late found nobody there, and the offerer gives up on
|
|
112
|
+
* the attempt and offers again. Taken for a network that lets nothing through, a group's edge went native on both
|
|
113
|
+
* sides, and past the native slots members stayed unreachable for the rest of a restart lab (agents#971, 2026-11-03):
|
|
114
|
+
* of 38 answers read 60 s or more after their offer, 13 connected nothing; of 78 read within 20 s, none failed.
|
|
115
|
+
*/
|
|
116
|
+
export declare const LATE_ANSWER_MS = 20000;
|
|
100
117
|
export declare class DataLink {
|
|
101
118
|
private readonly options;
|
|
102
119
|
state: DataLinkState;
|
|
@@ -104,6 +121,10 @@ export declare class DataLink {
|
|
|
104
121
|
/** Each connection's listeners, and its data channel's (`wrapDataChannel`), dropped once it is closed. */
|
|
105
122
|
private readonly ends;
|
|
106
123
|
private myOfferTs;
|
|
124
|
+
/** When this side's offer reached the relays, as far as this link knows (`signalWentOut`). */
|
|
125
|
+
private myOfferOutAt;
|
|
126
|
+
/** The answer to this side's offer came `LATE_ANSWER_MS` or more after the offer went out. */
|
|
127
|
+
private answerCameLate;
|
|
107
128
|
/**
|
|
108
129
|
* An offer or answer of this side's that went without a public candidate came to nothing (both descriptions were
|
|
109
130
|
* exchanged, and no path connected): the next one waits for its STUN servers as long as it takes
|
|
@@ -152,6 +173,22 @@ export declare class DataLink {
|
|
|
152
173
|
* does not show the answer yet: the one it was given counts, as DTLS already checked the peer against it.
|
|
153
174
|
*/
|
|
154
175
|
get fingerprints(): [string, string] | null;
|
|
176
|
+
/**
|
|
177
|
+
* The answer this side's offer is connecting on came `LATE_ANSWER_MS` or more after the offer went out: if it connects
|
|
178
|
+
* nothing, that says nothing about direct connections, and the link offers again (`GhostLink`'s stall of a group link).
|
|
179
|
+
*/
|
|
180
|
+
get answerLate(): boolean;
|
|
181
|
+
/**
|
|
182
|
+
* This side answered, and no answer of its went out in this attempt (`signalOut`: the relays' budget held every one
|
|
183
|
+
* back): the offerer never had one to try (agents#1637). The answering side's twin of `answerLate`.
|
|
184
|
+
*/
|
|
185
|
+
private get answerNotOut();
|
|
186
|
+
/**
|
|
187
|
+
* This attempt, if it ends now without opening, says nothing about direct connections: the answer to this side's offer
|
|
188
|
+
* was read late (`answerLate`), or this side's answer never went out (`answerNotOut`). An answer made again and still
|
|
189
|
+
* unread `LATE_ANSWER_MS` on (`failed`) is the same case, seen from the offer that still stands.
|
|
190
|
+
*/
|
|
191
|
+
private get saysNothing();
|
|
155
192
|
/** The peer connection this link holds now (null when idle): a later one is another attempt. */
|
|
156
193
|
get connection(): RTCPeerConnection | null;
|
|
157
194
|
close(): void;
|
|
@@ -71,6 +71,7 @@ export declare const ENGINE_ERRORS: {
|
|
|
71
71
|
readonly fedimintAlreadyJoined: "You already joined this federation";
|
|
72
72
|
readonly fedimintConnecting: "Wait for the federation to connect";
|
|
73
73
|
readonly fedimintNotEnough: "Not enough in this federation";
|
|
74
|
+
readonly fedimintRedeemUnheard: "Could not hear from the federation about these notes: if they don't show in your balance soon, paste them again";
|
|
74
75
|
readonly fedimintRealOnTestnet: "This federation holds real bitcoin: it belongs in a Mainnet Fedimint wallet";
|
|
75
76
|
readonly fedimintTestOnMainnet: "This federation is on {chain}, a test network: it belongs in a Testnet Fedimint wallet";
|
|
76
77
|
readonly walletAway: "{wallet} can't be used here. Use it on {device}.";
|
|
@@ -209,6 +209,11 @@ export declare const PAIRED_FRAME_TOO_LARGE = "Message too long once encoded. Sh
|
|
|
209
209
|
* as the frame drops one that does not fit.
|
|
210
210
|
*/
|
|
211
211
|
export declare function pairedMessageFits(ts: number, m: string, reply?: WireReply, forwarded?: number, card?: StatusCard): boolean;
|
|
212
|
+
/**
|
|
213
|
+
* The `paired-edit` frame of this edit fits a session, as `pairedMessageFits` says of a text's: an edit within 16 KiB
|
|
214
|
+
* can pass it the same way, and the contact's session ends on it each time it is said again.
|
|
215
|
+
*/
|
|
216
|
+
export declare function pairedEditFits(edit: WireEdit): boolean;
|
|
212
217
|
/**
|
|
213
218
|
* The transport a chat is set to reach and is not on yet (WISP 100, "A chosen transport not reached yet"): waited for,
|
|
214
219
|
* never failed. `by`: whose choice names it (absent: a policy alone, such as Fallback off, limits the chat to it).
|
|
@@ -292,6 +297,11 @@ export interface GhostLinkEvents {
|
|
|
292
297
|
* forgotten here, and the owner forgets what it kept of it.
|
|
293
298
|
*/
|
|
294
299
|
onPacketTransportsGone?(): void;
|
|
300
|
+
/**
|
|
301
|
+
* With `packetTransports`: the member's packet carries no `_tr` where the last one read did (`true`), or one again
|
|
302
|
+
* (`false`). News only: what it said before is kept, and on a device link only a signed value counts.
|
|
303
|
+
*/
|
|
304
|
+
onPacketTransportsUnsaid?(unsaid: boolean): void;
|
|
295
305
|
onPairingState?(state: PairingState): void;
|
|
296
306
|
/** How far a first pairing got (`pairingProgress` option): every change, up to `live`. */
|
|
297
307
|
onPairingProgress?(progress: PairingProgress): void;
|
|
@@ -402,7 +412,8 @@ export interface GhostLinkEvents {
|
|
|
402
412
|
onAnswersRefused?(): void;
|
|
403
413
|
/**
|
|
404
414
|
* A group link's WebRTC offer of this side's was answered and nothing connected `RACE_ANSWERED_MS` later: there is no
|
|
405
|
-
* direct path, as a chat's race takes it (`scheduleRace`). Said once per offer; the attempt itself goes on.
|
|
415
|
+
* direct path, as a chat's race takes it (`scheduleRace`). Said once per offer; the attempt itself goes on. Not for an
|
|
416
|
+
* answer read late (`LATE_ANSWER_MS`): the link gives that attempt up and offers again.
|
|
406
417
|
*/
|
|
407
418
|
onRtcStalled?(): void;
|
|
408
419
|
/** The contact's packet came between two reads of its record: its clock against this one (`LinkSessionEvents.onPeerClock`). */
|
|
@@ -589,6 +600,8 @@ export interface GhostLinkOptions {
|
|
|
589
600
|
avatar?: string;
|
|
590
601
|
lastSeenTimestamp?: number;
|
|
591
602
|
pollIntervals?: PollIntervals;
|
|
603
|
+
/** A contact that left a live session is read no slower than the idle pace this long (a CLI daemon's, `DAEMON_WATCH_PEER_IDLE_MS`). */
|
|
604
|
+
watchPeerIdleMs?: number;
|
|
592
605
|
/**
|
|
593
606
|
* The transport this chat was live on when the app last ran (it quit, or crashed, with the session up). The contact is
|
|
594
607
|
* probably still there, holding a session that is dead now: that transport is dialled first, and a native one is
|
|
@@ -890,6 +903,8 @@ export declare class GhostLink {
|
|
|
890
903
|
private noteSignalSigner;
|
|
891
904
|
/** A signal ready to go: on the live session during a switch to WebRTC, in this side's packet otherwise. */
|
|
892
905
|
private signalOut;
|
|
906
|
+
/** A WebRTC signal of this attempt went over the authenticated channel (a migration), not the relays. */
|
|
907
|
+
private rtcViaChannel;
|
|
893
908
|
/** This app is going away (`depart`): no more dials. */
|
|
894
909
|
private leaving;
|
|
895
910
|
/** `resume` still to act on: the first dial after the start goes to it, and a native one is knocked on. */
|
|
@@ -329,10 +329,15 @@ export interface CommunityState {
|
|
|
329
329
|
/** My next sequence number under the commit `seqH` (full hash). */
|
|
330
330
|
seq: number;
|
|
331
331
|
seqH: string;
|
|
332
|
-
/**
|
|
332
|
+
/**
|
|
333
|
+
* Sender → `e:h16` → highest seen and the window below it. `gap`: the lowest number missing below it, how many syncs
|
|
334
|
+
* asked for it and when the last did (`haveOf`); `floor`: what is missing at or below it is given up.
|
|
335
|
+
*/
|
|
333
336
|
seen: Record<string, Record<string, {
|
|
334
337
|
high: number;
|
|
335
338
|
window: number[];
|
|
339
|
+
gap?: [number, number, number];
|
|
340
|
+
floor?: number;
|
|
336
341
|
}>>;
|
|
337
342
|
nicks: Record<string, string>;
|
|
338
343
|
/** Recent frames from everyone (mine included), oldest first. */
|
|
@@ -353,6 +358,12 @@ export interface CommunityState {
|
|
|
353
358
|
* Absent in older states.
|
|
354
359
|
*/
|
|
355
360
|
alone?: string[];
|
|
361
|
+
/**
|
|
362
|
+
* My texts saved here (counter, frame in `store`) whose message row may not be stored or whose frame may not have gone
|
|
363
|
+
* yet, as `e:h16:n`, oldest first: an app killed in between stores and says them when it opens again (`resume`), so the
|
|
364
|
+
* number is never given to another text. Absent in older states.
|
|
365
|
+
*/
|
|
366
|
+
unsaid?: string[];
|
|
356
367
|
/** Leave requests waiting for a member to commit them. */
|
|
357
368
|
pendingLeaves: {
|
|
358
369
|
s: string;
|
|
@@ -864,9 +875,21 @@ export declare class CommunitySession {
|
|
|
864
875
|
/**
|
|
865
876
|
* Saves, then says my frame on every edge. One no edge took (none is up: I just joined, or my app just opened) is
|
|
866
877
|
* remembered until a member it was written for is handed it: I may be behind on the chain without knowing, and the
|
|
867
|
-
* first member I reach may be one let in since, who cannot read it but can carry it (`receiveSync`).
|
|
878
|
+
* first member I reach may be one let in since, who cannot read it but can carry it (`receiveSync`). `saved`: the
|
|
879
|
+
* caller marked it unheard and saved it (`sendText`).
|
|
868
880
|
*/
|
|
869
881
|
private say;
|
|
882
|
+
/** My frame in `unheard`, before it is said: the frames of mine the store no longer holds leave it. */
|
|
883
|
+
private markUnheard;
|
|
884
|
+
/**
|
|
885
|
+
* Stores and says what an app killed mid-send left `unsaid`: its counter and frame were saved, its row or its sending
|
|
886
|
+
* may not have happened. A row stored already is not stored twice (the app's store takes one row per id), a frame
|
|
887
|
+
* that went already is taken by the members as one they hold. The engine calls this on each tick; a send does first.
|
|
888
|
+
*/
|
|
889
|
+
resume(): Promise<void>;
|
|
890
|
+
private sayUnsaid;
|
|
891
|
+
/** The row of one of my own texts, as `sendText` stored it, opened from its frame; none for anything else, or one deleted for everyone. */
|
|
892
|
+
private ownRow;
|
|
870
893
|
/**
|
|
871
894
|
* Message `id` was deleted for everyone (WISP 400 § Delete for everyone), by its author or here: its frame goes from
|
|
872
895
|
* the store, so no catch-up hands it to a member who was away (they get the removal, which stays). A frame said again
|
|
@@ -934,6 +957,14 @@ export declare class CommunitySession {
|
|
|
934
957
|
*/
|
|
935
958
|
private ownFrame;
|
|
936
959
|
private isDuplicate;
|
|
960
|
+
/**
|
|
961
|
+
* What a sync says I have of a sender under a commit: below the lowest number missing, not the highest seen. A live
|
|
962
|
+
* frame raises the highest above that sender's frames still coming in a catch-up answer, and when the rest of the
|
|
963
|
+
* answer never came (my app closed or my edge dropped, or the hub's app closed), every later sync said I had them:
|
|
964
|
+
* they were lost for good (2026-10-18). A gap asked for by `GAP_ASKS` syncs at least `GAP_ASK_MS` apart that none
|
|
965
|
+
* filled (the stores rolled past it, a leaver's frames) is given up: each answer hands what is stored above it again.
|
|
966
|
+
*/
|
|
967
|
+
private haveOf;
|
|
937
968
|
private markSeen;
|
|
938
969
|
private park;
|
|
939
970
|
/** Something is missing here: the current epoch's secret, or the epoch of frames waiting. */
|
|
@@ -317,6 +317,12 @@ export interface GroupState {
|
|
|
317
317
|
* (`resealBehind`): I may have been behind on the chain without knowing. Absent in older states.
|
|
318
318
|
*/
|
|
319
319
|
alone?: string[];
|
|
320
|
+
/**
|
|
321
|
+
* My texts saved here (counter, frame in `sent`) whose message row may not be stored or whose frame may not have gone
|
|
322
|
+
* yet, as `e:n`, oldest first: an app killed in between stores and says them when it opens again (`resume`), so the
|
|
323
|
+
* number is never given to another text. Absent in older states.
|
|
324
|
+
*/
|
|
325
|
+
unsaid?: string[];
|
|
320
326
|
/** Epoch → the admin's mark (`GroupCommitFrame.left`) on the commit of that epoch that took out a member who left. Absent in older states. */
|
|
321
327
|
leftMarks?: Record<string, string>;
|
|
322
328
|
}
|
|
@@ -531,6 +537,13 @@ export declare class GroupSession {
|
|
|
531
537
|
get top(): GroupCommit;
|
|
532
538
|
get roster(): Roster;
|
|
533
539
|
get admin(): string | undefined;
|
|
540
|
+
/**
|
|
541
|
+
* The roster in the order its members were last admitted, the creator first (WISP 902 § Transports, the edge a
|
|
542
|
+
* member keeps): every member holding the same chain reads the same order, and a member reads everyone admitted
|
|
543
|
+
* before it from its welcome. Kept for the current top commit.
|
|
544
|
+
*/
|
|
545
|
+
get admissionOrder(): string[];
|
|
546
|
+
private admissionCache?;
|
|
534
547
|
get isAdmin(): boolean;
|
|
535
548
|
get status(): GroupStatus;
|
|
536
549
|
/** Members other than me, in the current roster. */
|
|
@@ -635,6 +648,8 @@ export declare class GroupSession {
|
|
|
635
648
|
private kept;
|
|
636
649
|
private trimRelay;
|
|
637
650
|
private pruneSecrets;
|
|
651
|
+
/** Someone out of the roster is named by no record of theirs, mine as the admin's: let in again, theirs start over. */
|
|
652
|
+
private pruneNames;
|
|
638
653
|
/**
|
|
639
654
|
* Leaves: my secrets go now; the admin removes me from the roster when it hears. `pick`: whom an admin with other
|
|
640
655
|
* members hands the role to first, in the same turn. The role can reach me while my leave is under way (a hand-over
|
|
@@ -671,6 +686,24 @@ export declare class GroupSession {
|
|
|
671
686
|
} | {
|
|
672
687
|
error: string;
|
|
673
688
|
}>;
|
|
689
|
+
/**
|
|
690
|
+
* Stores and says what an app killed mid-send left `unsaid`: its counter and frame were saved, its row or its sending
|
|
691
|
+
* may not have happened. A row stored already is not stored twice (the app's store takes one row per id), a frame
|
|
692
|
+
* that went already is taken by the members as one they hold. The engine calls this on each tick; a send does first.
|
|
693
|
+
*/
|
|
694
|
+
resume(): Promise<void>;
|
|
695
|
+
private sayUnsaid;
|
|
696
|
+
/** The row of one of my own frames, as `sendText` stored it, opened from the frame. */
|
|
697
|
+
private ownRow;
|
|
698
|
+
/**
|
|
699
|
+
* The highest number of mine, per epoch, among the rows the app stored (`GroupIncomingMessage.seq` of my own): my
|
|
700
|
+
* counter goes above them, so a row left by an older app killed mid-send never shares its id with a new text.
|
|
701
|
+
*/
|
|
702
|
+
ownRows(rows: Iterable<{
|
|
703
|
+
epoch: number;
|
|
704
|
+
seq: number;
|
|
705
|
+
}>): void;
|
|
706
|
+
private readonly rowHigh;
|
|
674
707
|
/** My next sequence number in `epoch`: the running counter in the current one, past every frame of mine I keep in an older one. */
|
|
675
708
|
private nextSeq;
|
|
676
709
|
/** A text sealed and signed as my frame `n` of `epoch`, with its boxes; `o`: where it was first said (`resealBehind`). */
|
|
@@ -678,7 +711,7 @@ export declare class GroupSession {
|
|
|
678
711
|
/** Into my bounded log, for members who missed it. */
|
|
679
712
|
private logOwn;
|
|
680
713
|
/**
|
|
681
|
-
* Saves, then sends my frame to every other member of its epoch still in the group. One no edge took (none was up:
|
|
714
|
+
* Saves, then sends my frame to every other member of its epoch still in the group (`saved`: the caller saved it). One no edge took (none was up:
|
|
682
715
|
* my app just opened) is remembered (`alone`): I may be behind on the chain without knowing, and members let in
|
|
683
716
|
* meanwhile could never open it (`resealBehind`).
|
|
684
717
|
*/
|
|
@@ -767,12 +800,24 @@ export declare class GroupSession {
|
|
|
767
800
|
/**
|
|
768
801
|
* A frame from an authenticated member over the pairwise edge. Anything malformed or unauthorized is dropped.
|
|
769
802
|
* Resolves to what it took that a hub passes on to its other edges (WISP 902 · Group Mesh § Hubs): each message,
|
|
770
|
-
* edit, commit (without the secret sealed for me), metadata statement and signed
|
|
771
|
-
* flood among hubs stops at every member that already has it
|
|
803
|
+
* edit, commit (without the secret sealed for me: `handOnTo` seals it for each member), metadata statement and signed
|
|
804
|
+
* leave, the first time only, so a flood among hubs stops at every member that already has it; a commit once more when
|
|
805
|
+
* its secret comes after it (`handOnAgain`). Only what its author still in the roster signed.
|
|
772
806
|
*/
|
|
773
807
|
handle(from: string, raw: unknown): Promise<GroupEdgeFrame[]>;
|
|
774
808
|
/** Taken for the first time: a hub passes it on (see `handle`). */
|
|
775
809
|
private took;
|
|
810
|
+
/**
|
|
811
|
+
* The secret of my top epoch came after its commit, which I handed on without it: the commit goes on once more, now
|
|
812
|
+
* with it (`handOnTo`), to the members who took it from me and asked me in vain. Once per epoch, as a secret is taken once.
|
|
813
|
+
*/
|
|
814
|
+
private handOnAgain;
|
|
815
|
+
/**
|
|
816
|
+
* A frame I took, as a hub passes it on to `to` (WISP 902 · Group Mesh § Hubs): a commit with its epoch's secret sealed
|
|
817
|
+
* for `to` when `to` is in that roster and I hold the secret, as a sync answer has it, so a member need not ask for it;
|
|
818
|
+
* anything else as it is.
|
|
819
|
+
*/
|
|
820
|
+
handOnTo(to: string, frame: GroupEdgeFrame): GroupEdgeFrame;
|
|
776
821
|
/**
|
|
777
822
|
* My leave, signed, for hubs to carry to the admin (see `GroupByeFrame`). Made while I am still a member: `leave`
|
|
778
823
|
* forgets everything but my key.
|
|
@@ -849,6 +894,11 @@ export declare class GroupSession {
|
|
|
849
894
|
private openReply;
|
|
850
895
|
private isDuplicate;
|
|
851
896
|
private markSeen;
|
|
897
|
+
/**
|
|
898
|
+
* The same for every sender, as the chain moves: `markSeen` prunes only the sender that writes, and a member who left
|
|
899
|
+
* never writes again. Each sync carries what is left here (`have`, `miss`), on every edge.
|
|
900
|
+
*/
|
|
901
|
+
private pruneSeen;
|
|
852
902
|
private park;
|
|
853
903
|
/** Whoever sent something I cannot read yet is ahead of me, or holds a secret I lack: ask, but not in a loop. */
|
|
854
904
|
private ask;
|
|
@@ -207,6 +207,12 @@ export declare class IdentityCheckUnavailable extends Error {
|
|
|
207
207
|
}
|
|
208
208
|
/** What the contact is told when the check failed with an IdentityCheckUnavailable. */
|
|
209
209
|
export declare const IDENTITY_CHECK_UNAVAILABLE = "Your contact's app could not check it. Try again later.";
|
|
210
|
+
/**
|
|
211
|
+
* Why a share of mine was not accepted, as this app may say it under my identity: one of the refusals above or my own
|
|
212
|
+
* app's line; else nothing past "not verified". Any other words came from the contact (a ledger kept before this check)
|
|
213
|
+
* and would read as this app's own notice.
|
|
214
|
+
*/
|
|
215
|
+
export declare const identityRefusal: (error: unknown) => string | undefined;
|
|
210
216
|
/**
|
|
211
217
|
* The `idp-*` exchange of one conversation. Frames (all JSON, additive, over the paired channel,
|
|
212
218
|
* only when both offers carry `identity-proof/1`):
|
|
@@ -222,6 +228,8 @@ export declare class IdentityExchange {
|
|
|
222
228
|
private options;
|
|
223
229
|
private peerProviders;
|
|
224
230
|
private requested;
|
|
231
|
+
/** The nonces of the presentations in their provider's check now. */
|
|
232
|
+
private checking;
|
|
225
233
|
constructor(options: IdentityExchangeOptions);
|
|
226
234
|
private now;
|
|
227
235
|
/** The ledger with one more step on the chat's timeline, in milliseconds (a test's clock, in seconds, when given). */
|
|
@@ -50,6 +50,14 @@ export declare const OFFER_LOOK_MS = 90000;
|
|
|
50
50
|
* matrix's chat stayed "On DHT · retrying live" for 45 s (E2E full, 2026-10-30).
|
|
51
51
|
*/
|
|
52
52
|
export declare const SIGNAL_OUT_READS = 3;
|
|
53
|
+
/**
|
|
54
|
+
* The first fast reads once the contact's offer is due now (`expectPeer(…, true)`: the chat just left DHT only, on
|
|
55
|
+
* both sides) are signaling too, as many as after an answer, until one finds a new signal of the contact's. As plain
|
|
56
|
+
* reads, an extension whose relay minute was spent read its contact once as it came back from DHT only, and the next
|
|
57
|
+
* read waited 41 s: the offer out since then was never read, and the matrix's chat stayed "On DHT · retrying live" for
|
|
58
|
+
* 45 s (E2E full, 2026-11-05).
|
|
59
|
+
*/
|
|
60
|
+
export declare const SIGNAL_DUE_READS = 3;
|
|
53
61
|
/**
|
|
54
62
|
* How long a link looks fast when its peer, or the peer's offer, is due any moment. The peer that
|
|
55
63
|
* dials does so as soon as it sees the other one here, and its offer lands in its packet a moment
|
|
@@ -62,6 +70,17 @@ export declare const EXPECT_PEER_MS = 30000;
|
|
|
62
70
|
* or the session dropped): an app that restarts is back within this, and its dial or offer is seen in seconds.
|
|
63
71
|
*/
|
|
64
72
|
export declare const WATCH_PEER_MS: number;
|
|
73
|
+
/**
|
|
74
|
+
* A CLI daemon (a bot) reads a contact that went away from a live session at the idle pace, not its background one, from
|
|
75
|
+
* the end of `WATCH_PEER_MS` until this long after it left (`LinkSession.watchPeer`). A phone that put the app to sleep is
|
|
76
|
+
* often back after more than 2 minutes, and where WebRTC is all there is between them its offer waits for the daemon's
|
|
77
|
+
* read: every 30 s past 2 minutes, a web app at phone size was live again 18.3 s after 5 minutes asleep (the lab,
|
|
78
|
+
* 2026-11-01). Cost, a contact away the whole 5 minutes: from 2 to 5 minutes, a read every 10 s and not every 30 s, 12
|
|
79
|
+
* more. A key's reads take turns between the two default relays (`readOrder` in relay.ts), 6 more on each: at 12 such
|
|
80
|
+
* absences an hour, 72 more an hour on a relay, 4% of the 1,800 this client allows itself there (`REQUESTS_PER_MINUTE`).
|
|
81
|
+
* At the active pace for the whole 5 minutes instead, 39 more an absence: 13%.
|
|
82
|
+
*/
|
|
83
|
+
export declare const DAEMON_WATCH_PEER_IDLE_MS: number;
|
|
65
84
|
/**
|
|
66
85
|
* The longest a link reads fast for a data link whose connection went `disconnected` (`setDataLinkStalled`): a little
|
|
67
86
|
* past the 12 s such a connection is given (`DISCONNECT_GRACE_MS`), by when it is back or the session is gone.
|
|
@@ -159,6 +178,8 @@ export interface LinkSessionEvents {
|
|
|
159
178
|
onPeerTransports?(value: string): void;
|
|
160
179
|
/** The peer's packet has said no `_tr` for `TRANSPORTS_GONE_MS`: the peer publishes none (any more). Once per such stretch. */
|
|
161
180
|
onPeerTransportsGone?(): void;
|
|
181
|
+
/** The peer's packet that advertises carries no `_tr` (`true`) where the last read did, or carries one again (`false`). */
|
|
182
|
+
onPeerTransportsUnsaid?(unsaid: boolean): void;
|
|
162
183
|
onStatus?(status: LinkStatus): void;
|
|
163
184
|
/** A poll started, or finished with the next one due in `nextInMs`. */
|
|
164
185
|
onPoll?(poll: {
|
|
@@ -238,6 +259,10 @@ export declare class LinkSession {
|
|
|
238
259
|
private lastCallSignalIn;
|
|
239
260
|
/** The `_rtc` signal the last packet that went out carried. */
|
|
240
261
|
private rtcSignalOut;
|
|
262
|
+
/** Counts the signals taken back (`setRtcSignal(null)`): each ends an attempt. */
|
|
263
|
+
private rtcAttempt;
|
|
264
|
+
/** A publish that went out carried a signal of this attempt (since the last take-back). */
|
|
265
|
+
private rtcAttemptOut;
|
|
241
266
|
private lastRtcSignalIn;
|
|
242
267
|
/** The `_rtc` signal the peer's packet carried as last read (null: none), whether or not it was new. */
|
|
243
268
|
private peerRtcSignal;
|
|
@@ -247,6 +272,8 @@ export declare class LinkSession {
|
|
|
247
272
|
/** When a read first found the peer's packet advertising with no `_tr` (0: the last packet that said carried one). */
|
|
248
273
|
private transportsAbsentSince;
|
|
249
274
|
private transportsGone;
|
|
275
|
+
/** The peer's packet carried a `_tr` and the last read found none (`onPeerTransportsUnsaid`). */
|
|
276
|
+
private transportsUnsaid;
|
|
250
277
|
private running;
|
|
251
278
|
/** Stopped without a last packet (`stop(false)`): nothing more goes out. */
|
|
252
279
|
private silent;
|
|
@@ -275,6 +302,8 @@ export declare class LinkSession {
|
|
|
275
302
|
private fastStepsAfter;
|
|
276
303
|
/** Fast reads still signaling since this side's last new offer or answer went out (`SIGNAL_OUT_READS`). */
|
|
277
304
|
private signalReadsLeft;
|
|
305
|
+
/** Fast reads still signaling while the contact's offer is due (`SIGNAL_DUE_READS`). */
|
|
306
|
+
private dueSignalReadsLeft;
|
|
278
307
|
/** When the last `expectPeer` window ends (or ended): the pace slows down from there step by step. */
|
|
279
308
|
private expectUntil;
|
|
280
309
|
/**
|
|
@@ -287,6 +316,8 @@ export declare class LinkSession {
|
|
|
287
316
|
private watchUntil;
|
|
288
317
|
/** The time of the peer's packet read last when it went away (`watchPeer`): a newer one that advertises says it is back. */
|
|
289
318
|
private watchFrom;
|
|
319
|
+
/** Until when a contact that went away is read at the idle pace once `watchUntil` passed (`watchPeer`'s `idleMs`). */
|
|
320
|
+
private lingerUntil;
|
|
290
321
|
/** Until when the reads of a contact that went away are its first ones (`DEPARTED_READ_MS`). */
|
|
291
322
|
private departedUntil;
|
|
292
323
|
private publishRetryTimer;
|
|
@@ -318,6 +349,11 @@ export declare class LinkSession {
|
|
|
318
349
|
private peerPacketAt;
|
|
319
350
|
constructor(options: LinkSessionOptions);
|
|
320
351
|
get peerPresence(): PeerPresence;
|
|
352
|
+
/**
|
|
353
|
+
* The relays took a WebRTC signal of this attempt: its answer, or an earlier one of it. Not an earlier attempt's still
|
|
354
|
+
* in the packet out: its take-back, a background write, is the first the relays' budget holds back.
|
|
355
|
+
*/
|
|
356
|
+
get rtcSignalPublished(): boolean;
|
|
321
357
|
/** The `_rtc` signal the peer's packet carries, as last read: null when it carries none. */
|
|
322
358
|
get peerSignal(): string | null;
|
|
323
359
|
start(): void;
|
|
@@ -346,14 +382,17 @@ export declare class LinkSession {
|
|
|
346
382
|
setFastPoll(fast: boolean, offer?: boolean): void;
|
|
347
383
|
/**
|
|
348
384
|
* The peer, or its offer, is due any moment: poll fast for `EXPECT_PEER_MS` (never cutting a longer fast window short),
|
|
349
|
-
* then slow down step by step (`nextInterval`) rather than at once.
|
|
385
|
+
* then slow down step by step (`nextInterval`) rather than at once. `signal`: its offer is due now (it may be out
|
|
386
|
+
* already): a read goes at once, even inside a window already looking fast, and the first reads that look for it are
|
|
387
|
+
* signaling (`SIGNAL_DUE_READS`).
|
|
350
388
|
*/
|
|
351
|
-
expectPeer(awaited?: boolean): void;
|
|
389
|
+
expectPeer(awaited?: boolean, signal?: boolean): void;
|
|
352
390
|
/**
|
|
353
391
|
* The contact just left a live session, and is likely coming back (an app restarting): fast for `EXPECT_PEER_MS`,
|
|
354
|
-
* then the active pace until `WATCH_PEER_MS` passed, whatever the chat's pace would be.
|
|
392
|
+
* then the active pace until `WATCH_PEER_MS` passed, whatever the chat's pace would be. `idleMs` (a daemon's,
|
|
393
|
+
* `DAEMON_WATCH_PEER_IDLE_MS`): then no slower than the idle pace until that long after now.
|
|
355
394
|
*/
|
|
356
|
-
watchPeer(): void;
|
|
395
|
+
watchPeer(idleMs?: number): void;
|
|
357
396
|
/**
|
|
358
397
|
* Nothing a read finds can be acted on for a while (a dial waiting out its backoff, whose end has a look of its own):
|
|
359
398
|
* the windows that look fast for the contact (`expectPeer`, `watchPeer`) end, and the link reads at its pace from the
|
|
@@ -59,6 +59,14 @@ export declare const RELAY_URL: RegExp;
|
|
|
59
59
|
export declare const RELAY_WITH_SECRETS: RegExp;
|
|
60
60
|
/** A relay URL a descriptor may name: `RELAY_URL`, with nothing but the server's address in it. */
|
|
61
61
|
export declare const relayUrl: (value: unknown) => value is string;
|
|
62
|
+
/**
|
|
63
|
+
* Whether an Iroh endpoint may dial a contact through the relay its descriptor names (none: a direct address alone).
|
|
64
|
+
* The contact chose that relay and this device opens it on its own, again on each redial, so it is held to what a held
|
|
65
|
+
* item's address is (`isHoldUrl`): https at a public name or a public address, never this machine or its network.
|
|
66
|
+
* One of the endpoint's own relays (`own`: the person's settings, a private network's or a test's) is dialled as well,
|
|
67
|
+
* in either spelling: this device opens it anyway.
|
|
68
|
+
*/
|
|
69
|
+
export declare function dialableIrohRelay(relay: unknown, own: readonly string[]): boolean;
|
|
62
70
|
/**
|
|
63
71
|
* A contact's native descriptors as it tells them on a session (`paired-policy`, `paired-adapters`) or as this app
|
|
64
72
|
* kept them: only what the adapters dial, each field in the shape its adapter makes. The keys are 64 hex characters,
|
|
@@ -12,7 +12,8 @@ import { type PushRequest, type PushTarget, type VapidKeys } from "./webPush.js"
|
|
|
12
12
|
* of a few bytes to the endpoint: `{"wake":1,"k":"<token>"}`. It says nothing about the message: the contact's
|
|
13
13
|
* app shows "New message", opens on a tap, connects and fetches the message itself. The token is the contact's
|
|
14
14
|
* own name for this chat, different for every contact, so its app knows which chat (and whether it is muted)
|
|
15
|
-
* without the push service learning anything:
|
|
15
|
+
* without the push service learning anything: every wake-up is padded to one size (`PUSH_PAD_BYTES`), so it sees that
|
|
16
|
+
* a push happened, and when; only the time to live and a call's repeats set a call or a device handoff apart.
|
|
16
17
|
*
|
|
17
18
|
* It needs `wake/1` in `paired-capabilities` on both sides. The VAPID key pair belongs to that one subscription,
|
|
18
19
|
* so sharing its private half lets a contact post to that subscription and nothing else. Rotating it (a new
|