@ghostlytools/sdk 1.7.3 → 1.8.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.
Files changed (34) hide show
  1. package/dist/core.js +2 -2
  2. package/dist/{fakes-NFHnJNv8.js → fakes-DSeGiDvk.js} +2 -2
  3. package/dist/fakes-DSeGiDvk.js.map +1 -0
  4. package/dist/fakes.js +1 -1
  5. package/dist/index.js +2 -2
  6. package/dist/{keet-identity-key-740ESaV_.js → keet-identity-key-Db5KY0V1.js} +2 -2
  7. package/dist/{keet-identity-key-740ESaV_.js.map → keet-identity-key-Db5KY0V1.js.map} +1 -1
  8. package/dist/{src-Dw-9Vq6U.js → src-CfpOdLVf.js} +1435 -236
  9. package/dist/src-CfpOdLVf.js.map +1 -0
  10. package/dist/testing.js +3 -3
  11. package/dist/types/browser/src/shared/features.d.ts +5 -0
  12. package/dist/types/browser/src/shared/mints.d.ts +6 -0
  13. package/dist/types/core/src/chatFiles.d.ts +18 -1
  14. package/dist/types/core/src/dhtDelivery.d.ts +51 -0
  15. package/dist/types/core/src/domainProofs.d.ts +3 -2
  16. package/dist/types/core/src/engineErrors.d.ts +5 -1
  17. package/dist/types/core/src/ghostlink.d.ts +24 -5
  18. package/dist/types/core/src/groupCommunity.d.ts +42 -4
  19. package/dist/types/core/src/groupSession.d.ts +6 -2
  20. package/dist/types/core/src/identityProofs.d.ts +1 -0
  21. package/dist/types/core/src/identityTimeline.d.ts +1 -1
  22. package/dist/types/core/src/image.d.ts +2 -1
  23. package/dist/types/core/src/index.d.ts +1 -0
  24. package/dist/types/core/src/link.d.ts +13 -0
  25. package/dist/types/core/src/linkPreview.d.ts +8 -4
  26. package/dist/types/core/src/pairedApps.d.ts +10 -5
  27. package/dist/types/core/src/ratchet.d.ts +201 -0
  28. package/dist/types/core/src/relay.d.ts +28 -2
  29. package/dist/types/core/src/storeForward.d.ts +32 -11
  30. package/dist/{verify-chCUPRKH.js → verify-C-u4HILn.js} +2 -2
  31. package/dist/{verify-chCUPRKH.js.map → verify-C-u4HILn.js.map} +1 -1
  32. package/package.json +1 -1
  33. package/dist/fakes-NFHnJNv8.js.map +0 -1
  34. package/dist/src-Dw-9Vq6U.js.map +0 -1
package/dist/testing.js CHANGED
@@ -1,7 +1,7 @@
1
- import { Oa as decodeBolt11, Yu as IdentityExchange, Zu as emptyIdentityLedger, ed as identityStatement, kC as createIdentity, ra as isBitcoinAddress, rd as newIdentityBinding, zu as IDENTITY_MAX_EVIDENCE } from "./src-Dw-9Vq6U.js";
1
+ import { Bu as IDENTITY_MAX_EVIDENCE, Oa as decodeBolt11, QC as createIdentity, Qu as emptyIdentityLedger, Xu as IdentityExchange, id as newIdentityBinding, ra as isBitcoinAddress, td as identityStatement } from "./src-CfpOdLVf.js";
2
2
  import { l as providerDescriptorProblems, o as isNothingSpentError } from "./types-DvtCy3WB.js";
3
- import { i as verifyIdentity, r as descriptorProblems } from "./verify-chCUPRKH.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-NFHnJNv8.js";
3
+ import { i as verifyIdentity, r as descriptorProblems } from "./verify-C-u4HILn.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-DSeGiDvk.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;
@@ -13,3 +13,8 @@ export declare const APPS_ENABLED: boolean;
13
13
  * themselves are still in the bundle (the registries import them); plugins may still pass fakes to the registry.
14
14
  */
15
15
  export declare const testBuild: () => boolean;
16
+ /**
17
+ * A suite's switch in the page's storage (`localStorage["ghostly-test-…"]`), read only in a test build (`testBuild`): a
18
+ * release build reads none, so a leftover or pasted key changes nothing there. Null when unset, unreadable or released.
19
+ */
20
+ export declare const testSwitch: (key: string) => string | null;
@@ -19,6 +19,12 @@ export declare const TEST_MINT = "https://testnut.cashu.space";
19
19
  */
20
20
  export declare const TEST_MINTS: readonly string[];
21
21
  export declare const isTestMint: (url: string) => boolean;
22
+ /**
23
+ * A mint URL spelled as the wallet stores its mints: lower-case scheme and host, no default port, no trailing slash.
24
+ * Another Cashu wallet's token or request names a mint as its user typed it (`HTTPS://Mint.Example:443/`), which is
25
+ * still one of ours. Not a check: `normalizeMintUrl` is the one that refuses a mint.
26
+ */
27
+ export declare function mintUrlSpelling(url: string): string;
22
28
  /** A mint on this very machine (a local test server): whatever it issues is not money anyone else holds. */
23
29
  export declare function isLocalMint(url: string): boolean;
24
30
  /**
@@ -85,6 +85,12 @@ export declare const FILE_LIMITS: {
85
85
  readonly autoAcceptBytesPerPeer: number;
86
86
  /** Offers from one contact waiting for an answer here. */
87
87
  readonly maxWaitingOffers: 16;
88
+ /**
89
+ * Files from one contact not finished here, whatever their state (asked about, taken and waiting their turn, paused,
90
+ * arriving). Only bytes were counted before: offers of 0 bytes were each taken, and 2,500 of them were 2,500
91
+ * messages and records waiting for good.
92
+ */
93
+ readonly maxUnfinishedIncoming: 256;
88
94
  /** Files one contact sends at once; accepted ones beyond wait their turn. */
89
95
  readonly maxActiveIncoming: 3;
90
96
  /** An offer nobody answered ends after this long. */
@@ -153,6 +159,12 @@ export interface FileTransferRecord {
153
159
  agreed?: boolean;
154
160
  }
155
161
  export declare const transferEnded: (record: FileTransferRecord) => boolean;
162
+ /**
163
+ * Whether a file sent from here arrived whole (the receiver confirmed every byte, and may be checking it): too late
164
+ * for its person to cancel. The receiver's check comes before a `pf-abort` behind it, so it would keep the file while
165
+ * the sender said it was cancelled. Not once the receiver asks about it again (`asking`), nor paused here.
166
+ */
167
+ export declare function sentWhole(record: FileTransferRecord): boolean;
156
168
  /**
157
169
  * Whether an unfinished transfer is stuck, so its person is offered to push it: "Send again" (sending) or "Ask again"
158
170
  * (receiving). `movedAt` is when its bytes last moved, `restored` that it has not moved since the app started. What
@@ -317,7 +329,11 @@ export declare class ChatFiles {
317
329
  attach(): void;
318
330
  /** The session went: nothing moves until the next one. What was received is made durable. */
319
331
  detach(): void;
320
- /** Offers ended by their time to live. The host calls it now and then; `attach` does too. */
332
+ /**
333
+ * Offers ended by their time to live. The host calls it now and then; `attach` does too. A file taken here and waiting
334
+ * its turn ends too once nothing of it arrived in that time: its sender never sent it. Offered again, it is taken
335
+ * again (`retakeAgreed`).
336
+ */
321
337
  sweep(): void;
322
338
  private sayRoom;
323
339
  /** A new file to send: offered now if a session is open, or on the next one. */
@@ -342,6 +358,7 @@ export declare class ChatFiles {
342
358
  private pump;
343
359
  private sendSum;
344
360
  private waitingOffers;
361
+ private unfinishedIncoming;
345
362
  private activeIncoming;
346
363
  /**
347
364
  * Removes what this side stored of an incoming file that ends here. Through its target, opened now if need be: after
@@ -1,3 +1,4 @@
1
+ import { RatchetBox, type RatchetState } from "./ratchet.js";
1
2
  import type { LinkParams } from "./invite.js";
2
3
  import type { PairingCredentials } from "./pairedSession.js";
3
4
  import { type PkarrRequestOptions, type PkarrTransport } from "./transport.js";
@@ -104,6 +105,11 @@ export interface DhtDeliveryState {
104
105
  * the chat is read as an invite nobody used (`unusedInviteWait`), counted from the join.
105
106
  */
106
107
  unanswered?: number;
108
+ /**
109
+ * A digest of the contact's last ratcheted envelope taken (WISP 4xx § The DHT floor): a reader reads more often than
110
+ * the contact publishes, and a floor key once used is gone, so the same envelope read again is known by this.
111
+ */
112
+ lastDr?: string;
107
113
  }
108
114
  export interface DhtDeliveryView {
109
115
  mode: DeliveryMode;
@@ -122,6 +128,12 @@ export interface DhtDeliveryView {
122
128
  foreignKeySeenAt?: number;
123
129
  /** The invite was used by someone else first (`DhtDeliveryState.inviteTaken`): this side's texts reach nobody. */
124
130
  inviteTaken?: boolean;
131
+ /**
132
+ * Forward secrecy of the floor (WISP 4xx): `on`, the turn passed both ways; `starting`, both apps have it and it is on
133
+ * once both have written; `unsupported`, the contact's app does not have it; `stopped`, it was on and the contact's
134
+ * app no longer says it has it (floor texts wait for the live session). Absent: this app does not run it here.
135
+ */
136
+ forwardSecrecy?: "on" | "starting" | "unsupported" | "stopped";
125
137
  }
126
138
  /**
127
139
  * What can be said about one DHT envelope without opening it: which text it carried, its sequence and times, the
@@ -162,6 +174,11 @@ export declare class DhtDelivery {
162
174
  private live;
163
175
  private active;
164
176
  private readonly startedAt;
177
+ /**
178
+ * When an envelope of the contact's newer than any before was last read here, in this run. A contact that is there
179
+ * puts a keep-alive every four minutes: none in `PRESENCE_WINDOW`, it is away (`publish`).
180
+ */
181
+ private peerNewAt;
165
182
  /** The next read was asked for (a refresh, a fresh packet of the contact): it is not a background one. */
166
183
  private urgent;
167
184
  /** Reads left that are signaling: the contact is leaving DHT only, and the live link waits on them (`expect`). */
@@ -257,8 +274,25 @@ export declare class DhtDelivery {
257
274
  * uses it, or while its inviter never answered the join (`unanswered`) (`unusedInviteWait`).
258
275
  */
259
276
  inviteMadeAt?: number;
277
+ /**
278
+ * The chat's ratchet (WISP 4xx), shared with its held items, and whether the contact's capability record lists
279
+ * `ratchet/1`. Absent: every envelope is sealed as before.
280
+ */
281
+ ratchet?: {
282
+ box: RatchetBox;
283
+ peerSupports(): boolean;
284
+ };
260
285
  });
261
286
  get view(): DhtDeliveryView;
287
+ private get forwardSecrecy();
288
+ /**
289
+ * Whether an envelope to `recipient` is sealed with the ratchet: the contact is pinned and its record lists
290
+ * `ratchet/1`, or a ratcheted envelope of its was opened here, after which nothing goes plain (WISP 4xx § Downgrade).
291
+ * And the contact pinned this side too (an envelope of its sealed to this side read, or a live session had): a joiner
292
+ * pins its inviter from the invite, and its first contact sealed with the ratchet would reach an inviter that has no key
293
+ * to open it with, and so never pins it.
294
+ */
295
+ private ratcheted;
262
296
  /**
263
297
  * This side joined, and its inviter never answered (`DhtDeliveryState.unanswered`): no envelope of its newer than the
264
298
  * one that pinned it, none sealed to this side, no text confirmed, never live (as `sealedToAnother` asks too).
@@ -276,6 +310,9 @@ export declare class DhtDelivery {
276
310
  */
277
311
  private pinned;
278
312
  private lastPublished?;
313
+ /** The envelope a trace line was last said for, per step: a packet read again says nothing new (a Desktop logs every line). */
314
+ private traced;
315
+ private traceOnce;
279
316
  /** The sealed record's nonce is its first 24 bytes: 32 characters of base64. */
280
317
  private static facts;
281
318
  get comparisonCode(): string | undefined;
@@ -286,6 +323,16 @@ export declare class DhtDelivery {
286
323
  private sealedKey;
287
324
  private signed;
288
325
  private records;
326
+ /**
327
+ * The envelope's records. Ratcheted (`ratcheted`), its `_dr` record is the right length but not sealed yet: `seal`
328
+ * gives its bytes, under the chat's lock, once the publication is sure to go. Measuring a packet takes no key.
329
+ */
330
+ private envelope;
331
+ /**
332
+ * The records to publish: a ratcheted one sealed now, its state saved first (seal, save, send), from the plaintext
333
+ * the envelope was measured with.
334
+ */
335
+ private sealed;
289
336
  start(): Promise<void>;
290
337
  stop(): Promise<void>;
291
338
  setMode(mode: DeliveryMode): Promise<void>;
@@ -389,6 +436,8 @@ export declare class DhtDelivery {
389
436
  * can write to) or `pinned`. `none`: nothing from the contact in it; `old`: the contact's, already read; `new`: taken.
390
437
  */
391
438
  private receive;
439
+ /** `ratchet`: the envelope was ratcheted; its state is saved once what it carried is stored, with its digest. */
440
+ private take;
392
441
  /**
393
442
  * Reads the contact's mailbox: the pinned one first once the contact said it can use it, the invite's otherwise. The
394
443
  * other is read too when the first held nothing from the contact (the contact publishes in the other one still, or a
@@ -427,6 +476,7 @@ export declare class DhtDelivery {
427
476
  private schedule;
428
477
  }
429
478
  export declare const DHT_TEXT_REFUSED = "Your contact's app does not accept text over the DHT. It is sent when you are live.";
479
+ export declare const DHT_RATCHET_STOPPED = "Your contact's app no longer reads protected messages over the DHT. It is sent when you are live.";
430
480
  export declare const DHT_FILE_REFUSED = "Your contact's app shows a file only once it comes. It is sent when you are live.";
431
481
  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.";
432
482
  /**
@@ -439,6 +489,7 @@ export declare function peekDhtMailbox(options: {
439
489
  state?: DhtDeliveryState;
440
490
  transport: PkarrTransport;
441
491
  background?: boolean;
492
+ ratchet?: RatchetState;
442
493
  }): Promise<{
443
494
  reads: number;
444
495
  text: string | null;
@@ -43,11 +43,12 @@ export declare function domainTxtRecord(r: DomainRecord): string;
43
43
  /** Parses one TXT string. Undefined for anything that is not ours or not exactly
44
44
  * well-formed; unknown extra tags are ignored for forward compatibility. */
45
45
  export declare function parseDomainTxt(value: string): DomainRecord | undefined;
46
- /** All records among the TXT strings of `_ghostly.<domain>`; other strings are skipped. */
46
+ /** All records among the first 32 TXT strings of `_ghostly.<domain>`; other strings are skipped. A TXT set has
47
+ * no order, so every record is kept: the one a proof needs may come in any position. */
47
48
  export declare function recordsFromTxt(values: string[]): DomainRecord[];
48
49
  /** The body of `/.well-known/ghostly.json`. */
49
50
  export declare function domainWellKnownFile(records: DomainRecord[]): string;
50
- /** Records from `ghostly.json`. Throws on a malformed file; [] when it names none. */
51
+ /** Records from the first 32 entries of `ghostly.json`. Throws on a malformed file; [] when it names none. */
51
52
  export declare function recordsFromWellKnown(text: string): DomainRecord[];
52
53
  /** NIP-05: only the root name `_` speaks for the domain itself. Undefined when absent. */
53
54
  export declare function nip05RootKey(text: string): string | undefined;
@@ -6,7 +6,8 @@
6
6
  * none of these (a mint's own words, a provider's) stays as it is.
7
7
  *
8
8
  * `{name}` in a template is a value: a host or domain (no spaces), a network ("Mainnet" or "Testnet"), a chain's name,
9
- * an ecash unit ("usd"), or an amount (digits, with the separators of whatever locale wrote it).
9
+ * an ecash unit ("usd"), an amount (digits, with the separators of whatever locale wrote it), or a server's own `{reason}`
10
+ * (one line, last in its text).
10
11
  */
11
12
  export declare const ENGINE_ERRORS: {
12
13
  readonly mintUnreachable: "Could not reach {host}. Check the address: it should be a Cashu mint.";
@@ -23,13 +24,16 @@ export declare const ENGINE_ERRORS: {
23
24
  readonly mintNotHttps: "Mints must use https";
24
25
  readonly notEnoughSats: "Not enough sats in your wallet";
25
26
  readonly notEnoughForFee: "Not enough sats in your wallet: {amount} sats leave room for the fee";
27
+ readonly mintsNoAnyAmount: "None of your mints can pay an invoice with no amount";
26
28
  readonly noSharedMint: "You share no mint with this contact";
27
29
  readonly ecashAlreadySpent: "This ecash was already spent somewhere else";
28
30
  readonly ecashBeingReceived: "This ecash is already being received";
31
+ readonly ecashFeeTakesAll: "The mint keeps all {amount} sats of this ecash as its fee to take it in: nothing was redeemed, and its sender can still take it back";
29
32
  readonly ecashOtherUnit: "This ecash is in {unit}: only sat ecash can be redeemed here";
30
33
  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.";
31
34
  readonly reviewedSatsGone: "The sats this payment was reviewed with went to another payment. Nothing was sent: review it again.";
32
35
  readonly lightningFeeTooHigh: "The Lightning fee ({fee} sats) is too high";
36
+ readonly lightningRefused: "The mint refused this Lightning payment, and no sats left your wallet: it is safe to try again. The mint said: {reason}";
33
37
  readonly invoiceExpired: "That invoice has expired";
34
38
  readonly lnurlExactly: "{domain} asks for exactly {amount} sats";
35
39
  readonly lnurlRange: "{domain} takes between {min} and {max} sats";
@@ -1,3 +1,4 @@
1
+ import type { RatchetBox } from "./ratchet.js";
1
2
  import { type DeliveryMode, type DhtDeliveryState, type DhtDeliveryView, type DhtPacketFacts } from "./dhtDelivery.js";
2
3
  import type { DhtFileAnnouncement, DhtFileOffer } from "./dhtFiles.js";
3
4
  import { type ProofAdapter, type ProofScope } from "./peerProofs.js";
@@ -540,6 +541,11 @@ export interface GhostLinkOptions {
540
541
  peerAcceptsFile?(): boolean;
541
542
  /** This side's reactions the contact has not confirmed, oldest first: they ride on the envelopes. */
542
543
  reactions?(): readonly WireReaction[];
544
+ /** The chat's ratchet (WISP 4xx) and whether the contact's record lists `ratchet/1`: the floor is sealed with it. */
545
+ ratchet?: {
546
+ box: RatchetBox;
547
+ peerSupports(): boolean;
548
+ };
543
549
  };
544
550
  rtcAvailable?: boolean;
545
551
  /** `automatic`: the chat follows the app's rule (no transport chosen for it); `preferred` is then the rule's. Absent: automatic unless `preferred` is given. */
@@ -712,6 +718,11 @@ export declare class GhostLink {
712
718
  private peerNickOverride;
713
719
  /** Group protocol versions the peer announced on this session; null until it does. */
714
720
  private peerGroupVersions;
721
+ /**
722
+ * Groups were on on this session. Off again, they stay off until the next session: each "on" runs a group edge's
723
+ * whole opening, and the peer says its versions once a session.
724
+ */
725
+ private peerGroupsWereOn;
715
726
  /** What each side announced after the handshake (`paired-capabilities`): calls, services. */
716
727
  private readonly sessionCapabilities;
717
728
  private readonly pairedCalls;
@@ -732,8 +743,9 @@ export declare class GhostLink {
732
743
  private readonly editsReceived;
733
744
  private readonly wakeReceived;
734
745
  /**
735
- * The contact's name and picture, each saved when it changes: said once a session and when changed, so a handful a
736
- * minute each. Past that only the newest waits, read once the window has room again.
746
+ * The contact's name and picture, its word on held items, its ways of paying and its transport descriptors, each saved
747
+ * on this side when it changes: said once a session and when changed, so a handful a minute each. Past that only the
748
+ * newest waits, read once the window has room again.
737
749
  */
738
750
  private readonly peerSaid;
739
751
  /** Identity-proof frames the contact may send per window; the rest are dropped before they are read. */
@@ -1266,6 +1278,8 @@ export declare class GhostLink {
1266
1278
  private attemptEnded;
1267
1279
  /** The last attempt to go live that did not (WISP 100, "Why a chat is not live"); none while live. */
1268
1280
  get liveAttempt(): LiveAttempt | undefined;
1281
+ /** Automatic dials since the link was last live or its wait started over (`wake`), the one under way included. */
1282
+ get dialAttempts(): number;
1269
1283
  /**
1270
1284
  * Which side dials this chat to go live: the lower rendezvous key, or the joiner of a first pairing (WISP 100). The
1271
1285
  * other side answers, so what it can tell of a failed attempt is only what reached it.
@@ -1569,9 +1583,12 @@ export declare class GhostLink {
1569
1583
  /**
1570
1584
  * The session ended or a new one took its place (a transport switch, a resume, a re-dial): what the contact had open
1571
1585
  * is held for `APP_RESUME_GRACE_MS` (WISP 1200 § In a chat). The next session's `open` takes each back, and the app
1572
- * hears only that open, not a close first; one not said again by then is closed with `offline`.
1586
+ * hears only that open, not a close first; one not said again by then is closed with `offline`. Each suspension
1587
+ * gives what it held its own grace: a later one's apps do not close at an earlier one's time.
1573
1588
  */
1574
1589
  private appsSuspended;
1590
+ /** A timer for the next held app's grace, as long as any is held. */
1591
+ private armAppsGrace;
1575
1592
  /** Whether files/3 was agreed on the session open now; kept to say when that changes. */
1576
1593
  private filesOpen;
1577
1594
  private emitFilesSession;
@@ -1786,9 +1803,11 @@ export declare class GhostLink {
1786
1803
  private resumeAfterAbsence;
1787
1804
  /** The answer of `epoch`, made while the app was away, has not connected since the wake: the resume dials instead. */
1788
1805
  private dropAnswerAfterWake;
1806
+ /** A name or picture the contact said, once it is one (reading it costs little; saving it is what counts). */
1807
+ private peerSaysOfItself;
1789
1808
  /**
1790
- * A name or picture the contact said, once it is one (reading it costs little; saving it is what counts): past the
1791
- * window the newest waits for room on this session, so the last word still counts.
1809
+ * Something the contact said that this side saves, read within its window: past it the newest waits for room on this
1810
+ * session (handed on unawaited then), so the last word still counts. What `read` returns when read at once is returned.
1792
1811
  */
1793
1812
  private peerSays;
1794
1813
  /** What the contact said of itself and was still waiting goes with the session: the next one says it again. */
@@ -18,8 +18,9 @@ import { type GroupMeta, type GroupMetaChange, type GroupMetaFrame } from "./gro
18
18
  * only a newcomer is sent it; `leave`, `remove` and `rotate` get a fresh secret sealed to everyone;
19
19
  * - concurrent commits are a race with a deterministic winner, not a fork: the branch that keeps the
20
20
  * admin's changes (remove, role, rotate, link) since the common parent, then the longest, then the
21
- * lowest hash of the first commit after the common parent. The admin signing changes on two
22
- * branches (after the same commit or not) is still a fork and halts the group;
21
+ * lowest hash of the first commit after the common parent. The admin of the tip signing changes on
22
+ * two branches (after the same commit or not) is still a fork and halts the group; a former admin
23
+ * doing so on a branch from before its hand-over is refused, as a stale branch;
23
24
  * - messages name the commit of their epoch, so messages under a commit that lost stay readable;
24
25
  * every member keeps recent frames from everyone and re-sends them to whoever was away.
25
26
  *
@@ -73,6 +74,15 @@ export declare const COMMUNITY_LIMITS: {
73
74
  */
74
75
  readonly syncAnswers: 16;
75
76
  readonly syncWindowMs: 60000;
77
+ /**
78
+ * Messages of one member taken per `messageWindowMs`, and the bytes of their sealed bodies, past what one catch-up
79
+ * answer holds (a whole store, and the lasting frames): anyone with the link is a member, and each message taken is a
80
+ * row in every member's app and a frame each hub passes on. The rest are not taken now and come again in a catch-up
81
+ * (`MessagePace`).
82
+ */
83
+ readonly messagesPerAuthor: 30;
84
+ readonly messageBytesPerAuthor: number;
85
+ readonly messageWindowMs: 10000;
76
86
  /**
77
87
  * Frames of one catch-up answer in a slice (`CommunitySessionHooks.handled`), two slices at most not handled yet by
78
88
  * the member's app: a member back after the store filled was handed 258 at once, and an app holds 64 waiting at most
@@ -148,7 +158,7 @@ export declare function communityRoster(previous: Roster | null, c: Pick<Communi
148
158
  /**
149
159
  * One commit against its parent (null for a genesis) and the parent's roster: shape, id, link,
150
160
  * authority, roster arithmetic, roster hash and signature. The confirmation tag is checked once
151
- * the secret is known. `before`: the commits before it on its branch, newest first; given, a `leave` is held to the
161
+ * the secret is known (a derived kind's on arrival, by a member holding the parent's: `receiveCommit`). `before`: the commits before it on its branch, newest first; given, a `leave` is held to the
152
162
  * admission it ends (`leaveStands`). A member gives it for every commit it takes in after its own admission; the chain
153
163
  * of a welcome is not held to it (`verifyCommunityChain`).
154
164
  */
@@ -478,6 +488,8 @@ export declare class CommunitySession {
478
488
  private asked;
479
489
  /** Syncs answered per member, a few a minute (`COMMUNITY_LIMITS.syncAnswers`). In memory only. */
480
490
  private syncsAnswered;
491
+ /** Messages taken per author, a few a second (`MessagePace`). In memory only. */
492
+ private messagePace;
481
493
  /** The entry seed sealed to each member, for the seed it seals (`entryFrame`): every sync answer carries it. In memory only. */
482
494
  private sealedEntries;
483
495
  /** Catch-up answers still going out, a slice at a time (`receiveSync`). */
@@ -535,11 +547,31 @@ export declare class CommunitySession {
535
547
  get canSend(): boolean;
536
548
  /** The entry key of the group's link, or "" when it is off. */
537
549
  get entryKey(): string;
550
+ /**
551
+ * The entry key of the link my admission that lost was let in by (the one its branch named), where I ask again: a
552
+ * link replaced since keeps me out as it does anyone. `entryKey` once that admission is no longer held.
553
+ */
554
+ get lostEntryKey(): string;
538
555
  role(key: string): GroupRole | undefined;
539
556
  /** The group's picture, if it has one. */
540
557
  get picture(): string | undefined;
541
- /** Members of any epoch in the window: whom a frame may come from. */
558
+ /**
559
+ * Members of any epoch in the window: whom a frame may come from. A side commit's roster counts only while its branch
560
+ * could still win (`mayWin`): one let in only on a branch that lost is not in the roster anyone sees, and the main
561
+ * branch past where they part, a later link among it, is not its business (`lostAt`).
562
+ */
542
563
  isRecentMember(key: string): boolean;
564
+ /**
565
+ * The side commits whose branch could still win: it does not drop an admin change the main branch holds (one that
566
+ * does never wins, see `better`), and it parts within the window. Kept until the tip or the side moves.
567
+ */
568
+ private mayWin;
569
+ private winning;
570
+ /**
571
+ * For a key that is no recent member, let in on a branch that lost: the main-branch index it parts from, and that of
572
+ * the commit that makes it lose (the latest over its branches). Undefined for anyone else.
573
+ */
574
+ private lostAt;
543
575
  /**
544
576
  * Whether `key` could read message `messageId` (`<s>:<e>:<h>:<n>`) and still can: a member of the roster it was sealed
545
577
  * for, and of the roster now. A holder serves a group file only to such a member (WISP 503 § Asking).
@@ -632,6 +664,12 @@ export declare class CommunitySession {
632
664
  private chooseBranch;
633
665
  private bestBranch;
634
666
  private adopt;
667
+ /**
668
+ * A leave the branch I left behind had committed, whose member the main branch still lists (an admin-only commit
669
+ * signed on a stale view won the fork): its request is held again, so the next hub commits it on top. The hub that
670
+ * committed it kept no copy and the leaver's app forgot the group, so nobody would say it again (agents#2285).
671
+ */
672
+ private holdDroppedLeaves;
635
673
  /** The entry key is the one the main branch names; its seed comes with a `group-entry` from whoever holds it. */
636
674
  private followEntry;
637
675
  /** Side commits stay up to a bound, the most recent ones (a longer branch being assembled included). */
@@ -591,6 +591,8 @@ export declare class GroupSession {
591
591
  * epochs before its leave (WISP 902 § Catch-up).
592
592
  */
593
593
  private pruneRelay;
594
+ /** Whether a kept edit is a removal (WISP 400 § Delete for everyone): its box, under its epoch's key, says `rm`. */
595
+ private isRemovalEdit;
594
596
  /** The frames `pruneRelay` dropped that are handed on again now (a removal's `left` mark came after it), back in their logs. */
595
597
  private unprune;
596
598
  /** Another member's edit, kept to hand on: the latest per message; the oldest go once the log is full. False: one as new was kept. */
@@ -747,8 +749,10 @@ export declare class GroupSession {
747
749
  /**
748
750
  * An edit of a member's own message, from its author's edge or handed on by another member: believed only while its
749
751
  * author is still in the roster (someone removed edits nothing), and the member handing it on too; for an epoch the
750
- * author and I were both members of, with the author's signature over the whole frame and a box that opens. One for
751
- * an epoch or a secret not here yet waits, as a message does. Taken, it is kept to hand on in turn.
752
+ * author and I were both members of, with the author's signature over the whole frame and a box that opens. A removal
753
+ * of an author out of the roster still stands, handed on by a member: it only takes away what the author wrote while
754
+ * in, and a member away when it was said would keep the message for good. One for an epoch or a secret not here yet
755
+ * waits, as a message does. Taken, it is kept to hand on in turn.
752
756
  */
753
757
  private receiveEdit;
754
758
  private parkEdit;
@@ -245,6 +245,7 @@ export declare class IdentityExchange {
245
245
  recheck(id: string, { revocationOnly }?: {
246
246
  revocationOnly?: boolean | undefined;
247
247
  }): Promise<ReceivedIdentity>;
248
+ private settleRecheck;
248
249
  receive(frame: Record<string, unknown>): Promise<void>;
249
250
  private onRequest;
250
251
  private onChallenge;
@@ -8,7 +8,7 @@
8
8
  export type IdentityTimelineSide = "mine" | "theirs";
9
9
  export type IdentityTimelineState = "verifying" | "verified" | "failed";
10
10
  export interface IdentityTimelineEntry {
11
- /** Unique in the chat: side, proof and how many entries that proof already had on that side. */
11
+ /** Unique in the chat: side, proof and one past the highest number that proof's kept entries on that side have. */
12
12
  id: string;
13
13
  /** The proof's id (identityStatement().id). */
14
14
  proof: string;
@@ -36,7 +36,8 @@ export declare function isImageMime(mime: string): boolean;
36
36
  export declare function parseImageMeta(value: unknown, mime?: string): ImageMeta | undefined;
37
37
  /**
38
38
  * A picture's size as it is shown, read from its first bytes (PNG, JPEG, GIF, WebP), or undefined when they do not
39
- * say. Only the header is read: a JPEG whose frame header sits past `IMAGE_LIMITS.headBytes` goes without.
39
+ * say. Only the header is read: a JPEG whose frame header, or a GIF whose first frame, sits past
40
+ * `IMAGE_LIMITS.headBytes` goes without.
40
41
  */
41
42
  export declare function imageSize(head: Uint8Array): ImageMeta | undefined;
42
43
  /**
@@ -61,6 +61,7 @@ export * from "./capsRecord.js";
61
61
  export { DhtDelivery, peekDhtMailbox, DHT_TEXT_BYTES, DHT_MESSAGE_TTL, DHT_TEXT_REFUSED, DHT_FILE_REFUSED, DHT_FILE_TOO_LARGE, LIVE_POLL_MS, ACTIVE_DHT_POLL_MS, emptyDhtDeliveryState, type DeliveryMode, type DhtDeliveryState, type DhtDeliveryView, type DhtPacketFacts } from "./dhtDelivery.js";
62
62
  export { DHT_FILE_CAPABILITY, dhtFileId, dhtFileElements, readDhtFile, type DhtFileAnnouncement, type DhtFileElement, type DhtFileMeta, type DhtFileOffer } from "./dhtFiles.js";
63
63
  export * from "./storeForward.js";
64
+ export * from "./ratchet.js";
64
65
  export * from "./paymentIntent.js";
65
66
  export * from "./bitcoinAddress.js";
66
67
  export * from "./sparkAddress.js";
@@ -90,6 +90,13 @@ export declare const UNUSED_INVITE_WAIT_MAX_MS: number;
90
90
  * hunt 1014-0136, 2026-10-14).
91
91
  */
92
92
  export declare const UNUSED_INVITE_READS_PER_MINUTE = 10;
93
+ /**
94
+ * An invite this side made that nobody used, once no longer awaited, puts its key and its mailbox out this often, not
95
+ * every `PRESENCE_HEARTBEAT`: 20 of them added about 17 relay writes a minute for as long as the app ran (bug hunt,
96
+ * 2026-10-30). Not longer: a joiner goes live sooner while it finds both still good, the packet within `PRESENCE_WINDOW`
97
+ * and the envelope unexpired. At 30 minutes the slowest of 6 joins took 235 s, against 86 s of 9 at the heartbeat's pace.
98
+ */
99
+ export declare const UNUSED_INVITE_UPKEEP_MS: number;
93
100
  /** Counts `reader` (an invite's key or mailbox) among the unused ones read over `transport` while `unused`, or no longer: how many there are. */
94
101
  export declare function countUnusedInvite(transport: PkarrTransport, reader: object, unused: boolean): number;
95
102
  /**
@@ -210,6 +217,8 @@ export interface LinkSessionOptions {
210
217
  * longer awaited, read less often while nobody is there (`unusedInviteWait`).
211
218
  */
212
219
  invite?: () => boolean;
220
+ /** Whether this is an invite this side made that nobody used yet (not one it joined): its upkeep slows too (`UNUSED_INVITE_UPKEEP_MS`). */
221
+ ownInvite?: () => boolean;
213
222
  }
214
223
  /** With `firstPublish: "after-first-poll"`, the first packet goes out by then whatever happened. */
215
224
  export declare const FIRST_PUBLISH_MAX_MS = 2000;
@@ -258,6 +267,8 @@ export declare class LinkSession {
258
267
  private readonly awaitingSince;
259
268
  /** This side's invite, nobody used yet (`LinkSessionOptions.invite`). */
260
269
  private readonly invite;
270
+ /** This side's own invite, nobody used yet (`LinkSessionOptions.ownInvite`). */
271
+ private readonly ownInvite;
261
272
  private readonly intervals;
262
273
  private fastPollUntil;
263
274
  /** An offer to a saved contact is out: from then on its fast window looks less often (`OFFER_FAST_MS`); 0 for none. */
@@ -404,6 +415,8 @@ export declare class LinkSession {
404
415
  /** How urgently this link looks right now. */
405
416
  private pace;
406
417
  private scheduleHeartbeat;
418
+ /** An unused invite of this side's, no longer awaited, whose packet went out less than `UNUSED_INVITE_UPKEEP_MS` ago. */
419
+ private upkeepWaits;
407
420
  /**
408
421
  * Coalesces publishes: at most one in flight and one queued behind it. `upkeep`: nothing new to say (the heartbeat, a
409
422
  * retry of what waits): with nothing else asked for since, the packet goes as upkeep (`publishOnce`).
@@ -27,12 +27,16 @@ export declare const LINK_PREVIEW_LIMITS: {
27
27
  /** The preview as JSON. With a text of 16 KiB the message frame stays under the 60 KiB a session takes. */
28
28
  readonly jsonChars: number;
29
29
  };
30
+ /** What a link leaves out at its end: a sentence's punctuation ("…", "»", "”" too), never a path's "/". */
31
+ export declare const LINK_TRAILING: RegExp;
32
+ /** A link up to the first `LINK_STOP`: "https://x.example/a。" opens /a, not /a%E3%80%82. */
33
+ export declare function linkStop(url: string): string;
30
34
  /**
31
- * A link ends where the sentence around it takes over: trailing punctuation ("see https://x.example/a.") and a
32
- * closing bracket or quote the link did not open ("(https://x.example/a)") are left as text. The same rule as the
33
- * message bubble's links.
35
+ * A link ends where the sentence around it takes over: trailing punctuation ("see https://x.example/a.", in any of
36
+ * the app's languages) and a closing bracket or quote the link did not open ("(https://x.example/a)") are left as
37
+ * text. The same rule as the message bubble's links.
34
38
  */
35
- export declare function linkEnd(url: string): string;
39
+ export declare function linkEnd(whole: string): string;
36
40
  /** Characters of a link worth reading: a longer one is no address anyone shares, and is left as text. */
37
41
  export declare const LINK_MAX_CHARS: number;
38
42
  /** The http(s) links of a text, in order, each ending as the bubble ends it. */
@@ -25,7 +25,7 @@ export declare const APP_RATE_LIMIT = 50;
25
25
  export declare const APP_RATE_WINDOW_MS = 1000;
26
26
  /** Data frames a sender sends per app per window: under the receiver's limit, so an `open` or `close` always fits. */
27
27
  export declare const APP_SEND_LIMIT: number;
28
- /** Distinct apps the peer may have open on one session; an `open` for one more is dropped. */
28
+ /** Distinct apps the peer may have open on one session, held ones counted; an `open` for one more is dropped. */
29
29
  export declare const APP_PEER_OPEN_MAX = 16;
30
30
  /** The longest version an `open` carries. */
31
31
  export declare const APP_VERSION_MAX = 64;
@@ -116,7 +116,10 @@ export declare class AppSessions {
116
116
  readonly open: Map<string, string>;
117
117
  private readonly now;
118
118
  private readonly peer;
119
- /** What the peer had open on a session that ended, held for `APP_RESUME_GRACE_MS` until it says so again. */
119
+ /**
120
+ * What the peer had open on a session that ended, until it says so again: each with its version and the time its
121
+ * grace ends, counted from the suspension that took it from the peer.
122
+ */
120
123
  private readonly held;
121
124
  private received;
122
125
  private sent;
@@ -141,11 +144,13 @@ export declare class AppSessions {
141
144
  /**
142
145
  * The session ended or was replaced, and another may follow at once: what the peer had open is held, not closed (no
143
146
  * event now). Nothing is sent to a held app; an `open` on the next session takes it back, a `close` closes it, and
144
- * `heldExpired` closes the rest once `APP_RESUME_GRACE_MS` has passed.
147
+ * `heldExpired` closes the rest once `graceMs` has passed since the suspension that held each.
145
148
  */
146
- sessionSuspended(): void;
149
+ sessionSuspended(graceMs?: number): void;
147
150
  /** Whether any of the peer's apps is held, waiting for its next session. */
148
151
  get holding(): boolean;
149
- /** The grace is over: each app still held is closed, with `offline`. */
152
+ /** When the next held app's grace ends; undefined when none is held. */
153
+ get heldUntil(): number | undefined;
154
+ /** Each app held whose grace is over is closed, with `offline`; the ones held later keep theirs. */
150
155
  heldExpired(): AppFrameEvent[];
151
156
  }