@ghostlytools/sdk 1.10.2 → 1.10.4

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 (30) hide show
  1. package/dist/core.js +2 -2
  2. package/dist/{fakes-Bj5HAJFV.js → fakes-r4tfM7wk.js} +2 -2
  3. package/dist/{fakes-Bj5HAJFV.js.map → fakes-r4tfM7wk.js.map} +1 -1
  4. package/dist/fakes.js +1 -1
  5. package/dist/index.js +2 -2
  6. package/dist/index.js.map +1 -1
  7. package/dist/{keet-identity-key-BgbqG2dL.js → keet-identity-key-CIwy3XtG.js} +2 -2
  8. package/dist/{keet-identity-key-BgbqG2dL.js.map → keet-identity-key-CIwy3XtG.js.map} +1 -1
  9. package/dist/{src-DHR2fUGx.js → src-0lxL4lAH.js} +930 -199
  10. package/dist/src-0lxL4lAH.js.map +1 -0
  11. package/dist/testing.js +3 -3
  12. package/dist/types/browser/src/proofs/contract.d.ts +4 -1
  13. package/dist/types/core/src/chatFiles.d.ts +6 -0
  14. package/dist/types/core/src/dhtDelivery.d.ts +52 -0
  15. package/dist/types/core/src/frames.d.ts +6 -0
  16. package/dist/types/core/src/ghostlink.d.ts +4 -0
  17. package/dist/types/core/src/groupCommunity.d.ts +26 -3
  18. package/dist/types/core/src/groupSession.d.ts +46 -3
  19. package/dist/types/core/src/http.d.ts +1 -0
  20. package/dist/types/core/src/identityProofs.d.ts +17 -0
  21. package/dist/types/core/src/identityTimeline.d.ts +8 -2
  22. package/dist/types/core/src/link.d.ts +8 -0
  23. package/dist/types/core/src/relay.d.ts +46 -7
  24. package/dist/types/core/src/transport.d.ts +29 -0
  25. package/dist/types/core/src/transportSwitch.d.ts +2 -0
  26. package/dist/{verify-aVAh4GtV.js → verify-DyjsMutX.js} +3 -2
  27. package/dist/verify-DyjsMutX.js.map +1 -0
  28. package/package.json +1 -1
  29. package/dist/src-DHR2fUGx.js.map +0 -1
  30. package/dist/verify-aVAh4GtV.js.map +0 -1
package/dist/testing.js CHANGED
@@ -1,7 +1,7 @@
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";
1
+ import { Bu as identityStatement, Iu as emptyIdentityLedger, Lw as createIdentity, Nu as IdentityExchange, Su as IDENTITY_MAX_EVIDENCE, Uu as newIdentityBinding, ia as isBitcoinAddress, ka as decodeBolt11 } from "./src-0lxL4lAH.js";
2
2
  import { l as providerDescriptorProblems, o as isNothingSpentError } from "./types-DvtCy3WB.js";
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";
3
+ import { i as verifyIdentity, r as descriptorProblems } from "./verify-DyjsMutX.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-r4tfM7wk.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;
@@ -218,10 +218,13 @@ export interface IdentityProofProvider<E = unknown> {
218
218
  /**
219
219
  * When a verifier's check can go stale (the DNS record may be removed later): the contact's app offers
220
220
  * "Check again" after this many seconds and shows the last check time. Omit when the evidence is a
221
- * signature that stays valid until expiry.
221
+ * signature that stays valid until expiry. `perHour`: the most checks the app runs on its own in an hour, for a
222
+ * server that limits lookups per IP (the rest wait for later); well under that limit, so a check a person starts
223
+ * (a new contact's proof, "Check again") still gets an answer.
222
224
  */
223
225
  recheck?: {
224
226
  afterSeconds: number;
227
+ perHour?: number;
225
228
  };
226
229
  /** One sentence for people: what `verify` contacts and who learns what. "Nothing: checked on this device." */
227
230
  privacy: string;
@@ -436,6 +436,12 @@ export declare class ChatFiles {
436
436
  /** Takes an offered file. */
437
437
  accept(id: string): void;
438
438
  decline(id: string): void;
439
+ /**
440
+ * An offer taken here whose record or message the host could not store: refused, so its sender does not count it
441
+ * delivered and keeps its Retry, and forgotten, so that retry is a new offer here. Nothing of it is reported changed
442
+ * (there is nothing to write it to); what was stored of it is removed.
443
+ */
444
+ refuse(id: string, why: RefuseReason): void;
439
445
  pause(direction: "in" | "out", id: string): void;
440
446
  resume(direction: "in" | "out", id: string): void;
441
447
  cancel(direction: "in" | "out", id: string): void;
@@ -37,6 +37,13 @@ export declare const LEAVING_DHT_FAST_MS: number;
37
37
  * side's offer and its reads for the answer go over the minute on (`SIGNALING_ALLOWANCE_SHARE` in relay.ts).
38
38
  */
39
39
  export declare const LEAVING_SIGNAL_READS = 3;
40
+ /**
41
+ * How long a fresh link packet of a contact that still says DHT only after the reads it started waits before it may
42
+ * start them again (`peerLinkPacket`), doubling up to `LEAVING_PROBE_MAX_GAP_MS`. One that really left says so in
43
+ * seconds; one that stays (or anyone holding the invite) cannot keep this side reading its mailbox at the DHT pace.
44
+ */
45
+ export declare const LEAVING_PROBE_GAP_MS: number;
46
+ export declare const LEAVING_PROBE_MAX_GAP_MS: number;
40
47
  /** Only this often while layer 1 carries the chat (WISP 403, Q7): the relays' per-IP budget is shared by every chat. */
41
48
  export declare const LIVE_POLL_MS: number;
42
49
  /**
@@ -183,6 +190,11 @@ export declare class DhtDelivery {
183
190
  private urgent;
184
191
  /** Reads left that are signaling: the contact is leaving DHT only, and the live link waits on them (`expect`). */
185
192
  private signalReads;
193
+ /** The read as this side leaves DHT only, before the signaling ones (`setMode`): a plain one. */
194
+ private leavingRead;
195
+ /** Until when a fresh link packet of the contact starts no signaling reads, and the wait it was held to (`peerLinkPacket`). */
196
+ private probeAt;
197
+ private probeGap;
186
198
  private timer;
187
199
  /** The first control envelope of a start that waits (`firstControlAfterMs`). */
188
200
  private controlTimer;
@@ -201,6 +213,11 @@ export declare class DhtDelivery {
201
213
  private unsealedOut;
202
214
  /** Until when the relays' request budget holds publications back: what is due then goes at once. */
203
215
  private budgetUntil;
216
+ /**
217
+ * This side left DHT only and no envelope saying so went out yet: the contact's live link waits on it (it holds this
218
+ * side's offer until it reads that), so it goes as signaling (`PkarrRequestOptions.signal`).
219
+ */
220
+ private leavingOut;
204
221
  /**
205
222
  * Until when it held this side's last read of the contact's mailbox back: the read goes again then, not at the next
206
223
  * poll. A chat in the background reads every 30 s, and one held back while its link was redialling read the contact
@@ -208,6 +225,8 @@ export declare class DhtDelivery {
208
225
  */
209
226
  private readHeldUntil;
210
227
  private errors;
228
+ /** Texts whose last `send` went nowhere (`wentNowhereFor`), newest last. */
229
+ private wentNowhere;
211
230
  /** When the device's network last came back (`networkBack`): a read or publication started before failed for want of it. */
212
231
  private networkBackAt;
213
232
  private foreignKeySeenAt?;
@@ -264,6 +283,11 @@ export declare class DhtDelivery {
264
283
  /** The contact took this side's reactions up to number `n`. */
265
284
  reactionsTaken?(n: number): Promise<void>;
266
285
  pollMs?: number;
286
+ /**
287
+ * How often a contact that chose DHT only is read with the chat in the background, where every chat counts as open
288
+ * (a CLI daemon: `ACTIVE_DHT_POLL_MS`). Absent: at the background pace (WISP 403, poll pace).
289
+ */
290
+ peerDhtPollMs?: number;
267
291
  /**
268
292
  * A chat already paired, started again: its first control envelope goes this long after the start, not in the
269
293
  * 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.
@@ -320,9 +344,21 @@ export declare class DhtDelivery {
320
344
  private changed;
321
345
  private serialize;
322
346
  private persist;
347
+ /** The key an envelope between this side and `peer` is sealed with: the same for the same contact, so derived once. */
348
+ private sealedKeys?;
323
349
  private sealedKey;
324
350
  private signed;
325
351
  private records;
352
+ /**
353
+ * Whether an envelope to `recipient` whose plaintext is this many bytes fits the packet: its size depends on the
354
+ * length alone, so it is measured on a placeholder, with no signature, key or encryption.
355
+ */
356
+ private fits;
357
+ /**
358
+ * Whether `body` fits an envelope to `recipient`, as `envelope` would find it, without building one: the signature is
359
+ * always 86 characters of base64url.
360
+ */
361
+ private bodyFits;
326
362
  /**
327
363
  * The envelope's records. Ratcheted (`ratcheted`), its `_dr` record is the right length but not sealed yet: `seal`
328
364
  * gives its bytes, under the chat's lock, once the publication is sure to go. Measuring a packet takes no key.
@@ -350,6 +386,13 @@ export declare class DhtDelivery {
350
386
  * (`LEAVING_SIGNAL_READS` in all) are signaling (`PkarrRequestOptions.signal`).
351
387
  */
352
388
  expect(ms?: number, signal?: boolean): void;
389
+ /**
390
+ * A fresh link packet of a contact still saying DHT only (`expect`, signaling). Nothing signed says it is the contact's,
391
+ * and one that stays on DHT only (or anyone holding the invite) can put one before every read: the reads it starts are
392
+ * then held to a wait that doubles from `LEAVING_PROBE_GAP_MS` to `LEAVING_PROBE_MAX_GAP_MS`, and start over once the
393
+ * contact says it left. False when held. Its offer, signed by its pinned key, is not held (`expect` directly).
394
+ */
395
+ peerLinkPacket(ms: number): boolean;
353
396
  /**
354
397
  * Layer 1 carries the chat, or no longer does. While it does, the mailbox is read every 5 minutes, after one
355
398
  * last look as it goes live: a text the contact put on the DHT in the seconds before (after this side's last
@@ -364,6 +407,10 @@ export declare class DhtDelivery {
364
407
  /** The chat is open with the app in front: on the DHT, its mailbox is read at the signaling pace. */
365
408
  setActive(active: boolean): void;
366
409
  validate(text: string, timestamp: number, id: string, reply?: string, edit?: DhtEdit): string | null;
410
+ /**
411
+ * Measured, not built (`bodyFits`): the outbox asks it of every waiting text at each look, and a text that waits as no
412
+ * relay takes it would cost a signature and a seal each time, for an answer that does not change.
413
+ */
367
414
  private packetError;
368
415
  /** Whether a text with its hop count fits the packet and what a reader reads (`MAX_ENVELOPE_PLAINTEXT`). */
369
416
  private roomForHops;
@@ -372,6 +419,11 @@ export declare class DhtDelivery {
372
419
  * room for it: the text is what matters, and it then reads as written here.
373
420
  */
374
421
  send(text: string, timestamp: number, id: string, reply?: string, edit?: DhtEdit, forwarded?: number): Promise<string | null>;
422
+ /**
423
+ * The last `send` of this id failed with no relay holding it, and it was not out before (`PublishFailedError`): it
424
+ * never left this device, and is no longer the floor's to publish.
425
+ */
426
+ wentNowhereFor(id: string): boolean;
375
427
  /**
376
428
  * The envelope a file's offer would go in, as `send` builds a text's: the most it can say that fits the packet and
377
429
  * what a reader reads (`MAX_ENVELOPE_PLAINTEXT`). Its meta goes first (a voice note's waveform thinned if it must),
@@ -24,6 +24,12 @@ export declare const LIMITS: {
24
24
  readonly maxConcurrentRequestsPerPeer: 32;
25
25
  /** Requests a client keeps in flight; the rest wait in a queue. */
26
26
  readonly maxClientInFlight: 16;
27
+ /**
28
+ * Requests, and their bodies' bytes, a client keeps waiting for a slot: past either, a request is refused at once
29
+ * (`busy`), so whatever asks (a contact's app in a viewer) cannot make it hold unbounded memory.
30
+ */
31
+ readonly maxClientWaiting: 64;
32
+ readonly maxClientWaitingBodyBytes: number;
27
33
  readonly maxChatMessageBytes: number;
28
34
  readonly maxFileBytes: number;
29
35
  /** Files a peer may be sending us at once. */
@@ -549,6 +549,8 @@ export interface GhostLinkOptions {
549
549
  state?: DhtDeliveryState;
550
550
  save(state: DhtDeliveryState): Promise<void>;
551
551
  pollMs?: number;
552
+ /** How often a contact that chose DHT only is read with the chat in the background (a CLI daemon's, `DhtDelivery`). */
553
+ peerDhtPollMs?: number;
552
554
  /** A chat already paired, started again: its first control envelope waits this long (`DhtDelivery`). */
553
555
  firstControlAfterMs?: number;
554
556
  /** This side's capability-record revision, told in every envelope (WISP 03). */
@@ -1351,6 +1353,8 @@ export declare class GhostLink {
1351
1353
  fileAnnounceError(file: DhtFileOffer, timestamp: number, reply?: WireReply, forwarded?: number): string | null;
1352
1354
  /** What awaits its receipt on the DHT floor now, if anything does. */
1353
1355
  get dhtPendingId(): string | undefined;
1356
+ /** The last DHT send of this text went nowhere: no relay holds it, and it is off the floor (`DhtDelivery.wentNowhereFor`). */
1357
+ dhtWentNowhere(id: string): boolean;
1354
1358
  /** What went on the DHT floor under this id needs no more retries there (it went live, or was withdrawn). */
1355
1359
  settleDht(id: string): Promise<void>;
1356
1360
  /** Publishes a `_call` signal; a connected peer also gets it right away over the data link. */
@@ -53,6 +53,12 @@ export declare const COMMUNITY_LIMITS: {
53
53
  readonly window: 64;
54
54
  /** Commits known off the main branch. */
55
55
  readonly side: 512;
56
+ /**
57
+ * Of those, the branches one member's commit ends (its newest), and the commits it signed: a handful of races, and
58
+ * one full run of its admissions (`memberAdmissions`, with the leaves among them). The admin's are not counted.
59
+ */
60
+ readonly sideTips: 8;
61
+ readonly sideCommits: 64;
56
62
  /** Commits waiting for their parent. */
57
63
  readonly pendingCommits: 64;
58
64
  /** Epoch secrets waiting for their commit. */
@@ -61,6 +67,11 @@ export declare const COMMUNITY_LIMITS: {
61
67
  readonly pendingMs: 120000;
62
68
  readonly waiting: 64;
63
69
  readonly waitingBytes: number;
70
+ /**
71
+ * Of those, the ones signed by a key no commit I know names (a newcomer whose admission has not come yet, or a key
72
+ * anyone can make up): the newest only, they push out nobody else's, and they make no catch-up hurry.
73
+ */
74
+ readonly waitingStrangers: 8;
64
75
  readonly replay: 256;
65
76
  /** Commits in one welcome or chain piece. */
66
77
  readonly chainPiece: 100;
@@ -648,7 +659,8 @@ export declare class CommunitySession {
648
659
  * it was in. What one who left wrote while in the group is taken and handed on, its goodbye included, up to what the
649
660
  * member who committed the leave had heard of it then (its `group-left` mark), never past it: the leaver still holds
650
661
  * those epochs' secrets, and anything it signs later is not heard (WISP 903 § Leaving and removal). No mark here
651
- * (one not come yet, or a committer's app before it) and nothing of it is heard.
662
+ * (one not come yet, or a committer's app before it) and nothing of it is heard. A key let in only on a branch that
663
+ * lost is heard no more either, as one removed, once this member knows it lost.
652
664
  */
653
665
  private heardAfterOut;
654
666
  /** The mark of a leave on my branch, as a frame to hand on (see `heardAfterOut`). */
@@ -740,7 +752,13 @@ export declare class CommunitySession {
740
752
  private holdDroppedLeaves;
741
753
  /** The entry key is the one the main branch names; its seed comes with a `group-entry` from whoever holds it. */
742
754
  private followEntry;
743
- /** Side commits stay up to a bound, the most recent ones (a longer branch being assembled included). */
755
+ /**
756
+ * Side commits stay up to a bound, the most recent ones (a longer branch being assembled included), and a member's
757
+ * newest only: past `sideTips` of the branches it ends or `sideCommits` of its commits, its oldest branch goes, from
758
+ * the tip down, so nothing kept loses its parent. Each is weighed at every commit taken and saved with the group, so
759
+ * what one member signs off the main branch costs every member a bounded amount. What it signs last is kept, so a
760
+ * branch it grows still comes in commit by commit (one let go comes again from where it parts in a catch-up).
761
+ */
744
762
  private pruneSide;
745
763
  /**
746
764
  * Seen marks of epochs older than the window go, every sender's, once the branch I follow moves past them: as
@@ -749,6 +767,10 @@ export declare class CommunitySession {
749
767
  * within the window stay, a leaver's too: what it wrote before its leave is still taken up to its mark there.
750
768
  */
751
769
  private pruneSeen;
770
+ /**
771
+ * Those of the main branch's window always stay, the current epoch's included; side commits, however many are
772
+ * kept, only get what is left of the bound, the most recent first.
773
+ */
752
774
  private pruneSecrets;
753
775
  /** A derived epoch's secret, from its parent's, when that is held. */
754
776
  private takeDerived;
@@ -769,6 +791,7 @@ export declare class CommunitySession {
769
791
  /** Whether this device may sign commits for the group now (`CommunitySessionHooks.adminWork`). */
770
792
  get adminWork(): boolean;
771
793
  private requireAdmin;
794
+ /** `alongside`: what else the commit changes in the state, saved in the same write (only once the commit is signed). */
772
795
  private commit;
773
796
  /** What an entry session sends a joiner first. */
774
797
  inviteFrame(): CommunityInviteFrame;
@@ -967,7 +990,7 @@ export declare class CommunitySession {
967
990
  private haveOf;
968
991
  private markSeen;
969
992
  private park;
970
- /** Something is missing here: the current epoch's secret, or the epoch of frames waiting. */
993
+ /** Something is missing here: the current epoch's secret, or the epoch of a member's frames waiting. */
971
994
  get needsCatchUp(): boolean;
972
995
  /** Asks a member I have an edge to for what I lack (the engine calls it now and then while `needsCatchUp`). */
973
996
  catchUp(to: string): void;
@@ -28,6 +28,13 @@ export declare const GROUP_LIMITS: {
28
28
  /** Frames waiting for an epoch (or its secret) that has not arrived yet. */
29
29
  readonly waiting: 64;
30
30
  readonly waitingBytes: number;
31
+ /**
32
+ * Of those, and of the edits waiting, the ones signed by a key no recent commit names (a newcomer whose admission has
33
+ * not come yet, or a key anyone can make up): the newest only, they go first, and they never say I am behind.
34
+ */
35
+ readonly waitingStrangers: 8;
36
+ /** How long a frame or edit waits: then it is dropped, and a later catch-up brings it again if it was real. */
37
+ readonly waitingMs: 120000;
31
38
  /** Epoch secrets kept: past this, older epochs cannot be read or handed on. */
32
39
  readonly secrets: 32;
33
40
  /** Secrets in one `group-secrets` frame: apps from before revision 0.9 drop a frame with more. */
@@ -73,6 +80,15 @@ export declare const GROUP_LIMITS: {
73
80
  readonly saveWithinMs: 1000;
74
81
  /** New name records of one member taken in `syncWindowMs` (WISP 902 § Messages, "The name record"): one a rename. */
75
82
  readonly namesPerMember: 4;
83
+ /**
84
+ * Messages of one member taken per `messageWindowMs`, and the bytes of their frames, past a burst of twice its whole
85
+ * log (`AuthorPace`); its edits the same, counted apart. As a community's (`COMMUNITY_LIMITS.messagesPerAuthor`): each
86
+ * one taken is a row in every member's app and a frame each hub passes on. The rest are not taken now and come again
87
+ * in a catch-up.
88
+ */
89
+ readonly messagesPerAuthor: 30;
90
+ readonly messageBytesPerAuthor: number;
91
+ readonly messageWindowMs: 10000;
76
92
  };
77
93
  /** What every member should know about who can read what, in the words the apps show. */
78
94
  export declare const GROUP_READ_NOTE: string;
@@ -401,6 +417,11 @@ export interface GroupSessionHooks {
401
417
  * after one parent halt the group. Absent: true.
402
418
  */
403
419
  adminWork?(): boolean;
420
+ /**
421
+ * The hubs I count on (WISP 902 · Group Mesh § Hubs), when the group runs on them: they carry my edits on even of a
422
+ * message from before they were let in, which they cannot read. Absent or empty: a full mesh.
423
+ */
424
+ carriers?(): readonly string[];
404
425
  /**
405
426
  * Whether a fresh turn read says this device is the active one (WISP 06 § When a device checks), asked before every
406
427
  * commit: two devices that both think they are active would each commit after one parent, and the group halts. No:
@@ -452,6 +473,11 @@ export declare class GroupSession {
452
473
  private waitingBytes;
453
474
  /** Edits for an epoch, or a secret, not here yet: tried again with the frames above. In memory only. */
454
475
  private waitingEdits;
476
+ /**
477
+ * Members one of whose frames waited `waitingMs` for an epoch that never came → when it was dropped: until my chain
478
+ * moves, theirs waiting say I am behind no more (`behind`). In memory only.
479
+ */
480
+ private waitedInVain;
455
481
  private pendingCommits;
456
482
  /** When each member was last asked to catch me up, so a stream of unreadable frames is one question, not a loop. */
457
483
  private asked;
@@ -466,6 +492,9 @@ export declare class GroupSession {
466
492
  private nameSaid;
467
493
  /** New name records taken per member, a few a minute (`GROUP_LIMITS.namesPerMember`). In memory only. */
468
494
  private namesTaken;
495
+ /** Messages, and apart from them edits, taken per author (`AuthorPace`). In memory only. */
496
+ private messagePace;
497
+ private editPace;
469
498
  private queue;
470
499
  /** One metadata frame that names a commit or an epoch I do not have yet: tried again when the chain moves. */
471
500
  private pendingMeta;
@@ -640,7 +669,12 @@ export declare class GroupSession {
640
669
  private pruneRelay;
641
670
  /** Whether a kept edit is a removal (WISP 400 § Delete for everyone): its box, under its epoch's key, says `rm`. */
642
671
  private isRemovalEdit;
643
- /** 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. */
672
+ /**
673
+ * Another member's edit, kept to hand on: the latest per message. Full (in count or in bytes), the oldest of the author
674
+ * who holds the most of it goes (the one just kept's own on a tie): an author's edits of messages that are not there,
675
+ * which no keeper can tell (a hub cannot even open them), as many as it likes, push out only its own. False: one as
676
+ * new was kept, or this one went.
677
+ */
644
678
  private keepEdit;
645
679
  /** A frame of another member, kept to hand on; the oldest go once the log is full. */
646
680
  private keep;
@@ -726,7 +760,10 @@ export declare class GroupSession {
726
760
  * edits, reactions); one who read the first does not show it twice. The engine calls this on each tick.
727
761
  */
728
762
  reseal(): Promise<void>;
729
- /** Something is missing here: the current epoch's secret, a commit ahead of my chain, or the epoch of frames waiting. */
763
+ /**
764
+ * Something is missing here: the current epoch's secret, a commit ahead of my chain, or the epoch of a member's frames
765
+ * waiting, unless one of that member's waited in vain since my chain last moved (`waitedInVain`).
766
+ */
730
767
  private get behind();
731
768
  private resealBehind;
732
769
  /**
@@ -748,7 +785,8 @@ export declare class GroupSession {
748
785
  /**
749
786
  * Says an edit of one of my messages (WISP 902 § Edits): edit `v`, the whole new text and its mentions, sealed under
750
787
  * the key of the message's epoch and signed, to every member of that epoch still in the group, or to `to` alone (an
751
- * edge that just opened). Someone admitted after the message cannot open it and is not sent it. The message's
788
+ * edge that just opened). Someone admitted after the message cannot open it and is not sent it, but a hub I count on
789
+ * (`hooks.carriers`), which carries it on to the members who can. The message's
752
790
  * epoch key must still be here: past `GROUP_LIMITS.secrets` epochs a message cannot be edited.
753
791
  */
754
792
  sendEdit(messageId: string, edit: {
@@ -875,6 +913,7 @@ export declare class GroupSession {
875
913
  */
876
914
  private receiveEdit;
877
915
  private parkEdit;
916
+ private paced;
878
917
  private wholeSigned;
879
918
  /**
880
919
  * The author's name in a message (`nk`), when the author's signature over it (`ns`) holds: any copy, handed on or
@@ -900,6 +939,10 @@ export declare class GroupSession {
900
939
  */
901
940
  private pruneSeen;
902
941
  private park;
942
+ /** Not in the roster, nor in any of the last `secrets` commits: a key whose frames may be no member's. */
943
+ private stranger;
944
+ /** Frames and edits that waited `waitingMs`: dropped, and a member's noted (`waitedInVain`). */
945
+ private expireWaiting;
903
946
  /** Whoever sent something I cannot read yet is ahead of me, or holds a secret I lack: ask, but not in a loop. */
904
947
  private ask;
905
948
  /**
@@ -123,6 +123,7 @@ export declare class HttpClient {
123
123
  private nextId;
124
124
  private readonly streams;
125
125
  private readonly waiting;
126
+ private waitingBytes;
126
127
  private inFlight;
127
128
  private closed;
128
129
  constructor(channel: FrameChannel);
@@ -35,6 +35,19 @@ export declare const IDENTITY_MAX_RECEIVED = 16;
35
35
  /** `idp-*` frames a paired session reads from the contact per `IDENTITY_FRAME_WINDOW_MS`; the rest are dropped unread. */
36
36
  export declare const IDENTITY_FRAME_LIMIT = 40;
37
37
  export declare const IDENTITY_FRAME_WINDOW_MS = 60000;
38
+ /**
39
+ * A proof this side holds verified, presented again with the same evidence between the same keys, is answered from that
40
+ * check while it is younger than this (seconds): the contact chooses how often it presents, and each check costs this
41
+ * device a provider lookup (a forge's per-IP quota, a DNS query, a contact's server) and a Pkarr read. An hour keeps an
42
+ * answer as fresh as a re-share can expect; past it, and between, the daily re-check (or Check again) asks the provider.
43
+ */
44
+ export declare const IDENTITY_REUSE_CHECK_S = 3600;
45
+ /**
46
+ * Presentations a verifier checks with their provider per contact in an hour; past it the contact is told the check
47
+ * could not run. Room for every proof it may keep (`IDENTITY_MAX_RECEIVED`) and a few retries: a contact making fresh
48
+ * proofs cannot spend a forge's per-IP quota (GitHub: 60 an hour) for every chat and app on this network.
49
+ */
50
+ export declare const IDENTITY_MAX_CHECKS_PER_HOUR = 20;
38
51
  export declare const IDENTITY_PROVIDER_ID: RegExp;
39
52
  /** Printable ASCII without spaces, so the statement can be built but never needs parsing. */
40
53
  export declare const IDENTITY_SUBJECT: RegExp;
@@ -120,6 +133,8 @@ export declare function signIdentityPresentation(seed: Uint8Array, proofId: stri
120
133
  export declare function verifyIdentityPresentation(key: string, sig: string, proofId: string, scope: IdentityScope, nonce: string, issuedAt: number): boolean;
121
134
  /** Bounds a provider's result so a buggy provider cannot store or show arbitrary data. */
122
135
  export declare function boundVerifiedIdentity(v: VerifiedIdentity): VerifiedIdentity;
136
+ /** Bounds a provider's public name/picture (from a proof or `lookupDisplay`): a name with nothing visible left is dropped. */
137
+ export declare function boundIdentityDisplay(d: IdentityDisplay): IdentityDisplay;
123
138
  /** Sharer side, one per proof shared in this conversation. */
124
139
  export interface SharedIdentity {
125
140
  id: string;
@@ -230,6 +245,8 @@ export declare class IdentityExchange {
230
245
  private requested;
231
246
  /** The nonces of the presentations in their provider's check now. */
232
247
  private checking;
248
+ /** When the contact's presentations were checked with their provider (seconds), for `IDENTITY_MAX_CHECKS_PER_HOUR`. */
249
+ private checks;
233
250
  constructor(options: IdentityExchangeOptions);
234
251
  private now;
235
252
  /** The ledger with one more step on the chat's timeline, in milliseconds (a test's clock, in seconds, when given). */
@@ -8,7 +8,10 @@
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 one past the highest number that proof's kept entries on that side have. */
11
+ /**
12
+ * Unique in the chat: side, proof and one past the highest number that proof's kept entries on that side have. A
13
+ * contact's later attempt that took the entry over keeps it (see applyIdentityEvent).
14
+ */
12
15
  id: string;
13
16
  /** The proof's id (identityStatement().id). */
14
17
  proof: string;
@@ -65,7 +68,10 @@ export declare const IDENTITY_TIMELINE_MAX = 100;
65
68
  /**
66
69
  * The timeline after one step. A share already on it is updated in place, never repeated: a request sent again at
67
70
  * a reconnect, a second share of a proof the contact already verified. A new attempt after a failure or a stop is
68
- * a new entry. A stop is written once; a withdrawal later found revoked becomes a revocation in place.
71
+ * a new entry, except the contact's own not verified: those keep one entry per kind, which its next attempt takes
72
+ * over in place (its id and time stay, so no new sound and the chat does not move). The ids and the kind are the
73
+ * contact's to choose, so otherwise its requests alone could push every other entry, this side's too, out of the
74
+ * bound. A stop is written once; a withdrawal later found revoked becomes a revocation in place.
69
75
  */
70
76
  export declare function applyIdentityEvent(timeline: readonly IdentityTimelineEntry[], event: IdentityTimelineEvent, at: number): IdentityTimelineEntry[];
71
77
  /** When the contact last shared an identity here (milliseconds), for the chat list: 0 when never. */
@@ -304,6 +304,8 @@ export declare class LinkSession {
304
304
  private signalReadsLeft;
305
305
  /** Fast reads still signaling while the contact's offer is due (`SIGNAL_DUE_READS`). */
306
306
  private dueSignalReadsLeft;
307
+ /** This side just left DHT only and its presence is not out yet: the contact dials on it (`presenceDue`). */
308
+ private presenceDueOut;
307
309
  /** When the last `expectPeer` window ends (or ended): the pace slows down from there step by step. */
308
310
  private expectUntil;
309
311
  /**
@@ -398,6 +400,12 @@ export declare class LinkSession {
398
400
  * the windows that look fast for the contact (`expectPeer`, `watchPeer`) end, and the link reads at its pace from the
399
401
  * next read on. An offer of this side's out keeps its window.
400
402
  */
403
+ /**
404
+ * This side just left DHT only: the contact that dials waits on its next packet that advertises, so that one is
405
+ * signaling (`PkarrRequestOptions.signal`). As a plain write, an app that had spent its relay minute held it 55 s,
406
+ * and the contact dialled only then.
407
+ */
408
+ presenceDue(): void;
401
409
  calm(): void;
402
410
  /** The data link carries chat and services while it is up. */
403
411
  setDataLinkOpen(open: boolean): void;
@@ -91,6 +91,19 @@ export declare const SIGNALING_ALLOWANCE_SHARE: number;
91
91
  * came up was never read, and the chat came back only through the race's DHT dial, 8 s on (2026-10-07).
92
92
  */
93
93
  export declare const DEPARTED_READS = 6;
94
+ /**
95
+ * A 1:1 chat's reads of an invite this side made, while its joiner is due and has not shown (`awaited`, `AWAITING_PEER_MS`
96
+ * in link.ts), may go over a relay's minute within the chat's allowance (`SIGNALING_ALLOWANCE_SHARE`) the same way: at
97
+ * most this many of each invite's in a minute, every relay together. And while one asked in the last minute, the departed
98
+ * reads leave them half of that on each relay: the last `AWAITED_READS / 2` of the allowance's reads (`DEPARTED_READS`
99
+ * then take at most 3 on a relay of 30, against 5). Read every 2 to 4 s, they cover the seconds in which a joiner that
100
+ * opened the link at once knocks. Within the chats' allowance, they add nothing to what a relay may see in a minute
101
+ * (`WAY_BACK_SHARE`): 36 at most from the chats on a relay of 30, none past 5 on a relay of 5. An inviter pairing one joiner after
102
+ * another on relays of 30 spent the minute on both 12 s in (two pairings, about 15 requests a relay each), the departed
103
+ * reads of the contact that had just left took the allowance, and the third invite's key was read once, then not until
104
+ * the minute freed: the joiner's knock 48 s late, and join to live in 60 s, against 2.6 and 4.6 s (CLI lab, 2026-11-07).
105
+ */
106
+ export declare const AWAITED_READS = 4;
94
107
  /**
95
108
  * A group edge's requests for a member that may be back may go over a relay's minute by this fraction of it (4 on a
96
109
  * relay of 30, 8 on one of 60, none on a relay of 5): its reads of a member that went away and its packet
@@ -300,7 +313,9 @@ export declare class RelayTransport implements PkarrTransport {
300
313
  * records are written by every member, an inviter warms its contact's key with an empty packet, and this device's
301
314
  * own clock may have been set back since it last wrote. A relay and the DHT keep only the packet dated latest, so
302
315
  * one dated by this clock alone, when it is behind, was refused (409) or silently never read, until this clock
303
- * caught up with the other one: minutes, or an hour.
316
+ * caught up with the other one: minutes, or an hour. Only up to `PKARR_FUTURE_SKEW_MS` ahead of this clock
317
+ * (`withinSkew`): a packet one holder of a shared key dated further ahead must not date every later one of this
318
+ * device past it (past 64 bits, unsignable; else ahead of every reader's clock, never taken over one dated now).
304
319
  */
305
320
  private readonly seenTimestamp;
306
321
  /**
@@ -335,6 +350,10 @@ export declare class RelayTransport implements PkarrTransport {
335
350
  private readonly spentAnswerAllowance;
336
351
  /** Per contact, its departed reads past the limit in the last minute, every relay together (`DEPARTED_READS`). */
337
352
  private readonly departedOver;
353
+ /** Per invite, its awaited reads past the limit in the last minute, every relay together (`AWAITED_READS`). */
354
+ private readonly awaitedOver;
355
+ /** When an awaited invite's read last asked: the departed reads leave it room for a minute (`AWAITED_READS`). */
356
+ private awaitedAt;
338
357
  /**
339
358
  * Per key a group reads (not in the background), when a read of it last went out and when it last asked: whose turn
340
359
  * it is under the watch share (`WATCH_SHARE`) and while the groups' reads are rationed (`GROUP_RATION_WINDOW_MS`). And
@@ -387,6 +406,10 @@ export declare class RelayTransport implements PkarrTransport {
387
406
  private readonly hedgeMs;
388
407
  /** Until when each relay found slow (`SLOW_MS`) goes after the others in a read (`readOrder`). */
389
408
  private readonly slowUntil;
409
+ /** Per relay, when each of this client's requests still waiting for its answer went out (`unanswering`). */
410
+ private readonly waiting;
411
+ /** When each relay last answered a request of this client, whatever it said (`unanswering`). */
412
+ private readonly answeredAt;
390
413
  /** Keys whose last read was answered 404: their next read hedges later (`HEDGE_MISSING_MS`). */
391
414
  private readonly missing;
392
415
  private readonly listeners;
@@ -395,6 +418,14 @@ export declare class RelayTransport implements PkarrTransport {
395
418
  discovery(): DiscoveryStatus;
396
419
  /** Back online on some network: relays that failed (or rate limited this address) on the old one are asked again. */
397
420
  networkChanged(): void;
421
+ /**
422
+ * `PkarrTransport.forget`: the packets and dates this client kept under these keys go, on every relay (`written`,
423
+ * `newest`, `lastTimestamp`, `seenTimestamp`, `lastPut`). A spare invite replaced unused left them here for its two keys
424
+ * for good: an idle CLI daemon gained 8 keys an hour (343 in `written` and 690 `lastPut` entries after a day). The maps
425
+ * that bound themselves (`readAt`, `lastReadFrom`, `heldBack`, `missing`, the turns) and the catch-ups, which go once
426
+ * put, are left as they are. A later put under one of these keys goes as a key's first.
427
+ */
428
+ forget(keys: Iterable<string>): void;
398
429
  /** Called when a relay trips or recovers. */
399
430
  subscribe(listener: (change?: DiscoveryChange) => void): () => void;
400
431
  private changed;
@@ -500,13 +531,21 @@ export declare class RelayTransport implements PkarrTransport {
500
531
  */
501
532
  resolve(pubKeyZ32: string, options?: PkarrRequestOptions, keptOnFailure?: boolean): Promise<SignedPacket | null>;
502
533
  /**
503
- * The order a key's read asks the relays in: in turn per key (see `resolve`), relays found slow lately last. A relay
534
+ * The order a key's read asks the relays in: in turn per key (see `resolve`), relays found slow lately or leaving a
535
+ * request unanswered (`unanswering`) last. A relay
504
536
  * with a small share of its own (`RELAY_REQUESTS_PER_MINUTE` under `REQUESTS_PER_MINUTE`: pkarr.miguelmedeiros.dev's 5)
505
537
  * takes no turns: it comes after the others, for when they refuse, fail or are slow, unless every relay is one. In the
506
538
  * turn, it was spent in seconds and the relay after it took its turns too: pkarr.pubky.org got two reads in three and
507
539
  * pkarr.pubky.app, with twice its share, one. Its few requests are then left for writes, which go to every relay.
508
540
  */
509
541
  private readOrder;
542
+ /**
543
+ * A request of this client has waited on the relay for `HEDGE_MS` and it has answered none since: it goes after the
544
+ * others in a read (`readOrder`), at no cost of a request. A relay that took connections and never answered held a
545
+ * fresh device's first pairing at its turn: the key's last read had found nothing (`HEDGE_MISSING_MS`), so the read
546
+ * waited 6 s on it before asking the relay that had held the packet all along (8 s join to live, not 2.5 s).
547
+ */
548
+ private unanswering;
510
549
  /** One GET of a key at one relay, which `controller` drops. Never rejects: what happened is the outcome. */
511
550
  private readFromRelay;
512
551
  /**
@@ -553,7 +592,7 @@ export declare class RelayTransport implements PkarrTransport {
553
592
  * Who goes first: a chat's refused write holds back everything but chat writes; a group's refused write holds back
554
593
  * group reads and background requests, never a chat's. Background requests yield to a link that signals. A chat's
555
594
  * signaling goes over the limit by its allowance (`SIGNALING_ALLOWANCE_SHARE`), and so do a few of its reads of a
556
- * contact that just went away (`DEPARTED_READS`). `ownAllowance` false: what holds an edge's read for its answer
595
+ * contact that just went away (`DEPARTED_READS`) or of an invite awaited (`AWAITED_READS`). `ownAllowance` false: what holds an edge's read for its answer
557
596
  * without its own allowance (`ANSWER_READ_ALLOWANCE`).
558
597
  */
559
598
  private heldFor;
@@ -593,10 +632,10 @@ export declare class RelayTransport implements PkarrTransport {
593
632
  private turnAhead;
594
633
  /** A 1:1 chat's read of `key` the budget has held back for `READ_STARVED_MS` without a break. */
595
634
  private starved;
596
- /** This contact's departed reads past the limit in the last minute (`DEPARTED_READS`). */
597
- private departedReads;
598
- /** One more, the contacts with none in the last minute dropped. */
599
- private departedOverAdd;
635
+ /** This key's departed or awaited reads past the limit in the last minute (`DEPARTED_READS`, `AWAITED_READS`). */
636
+ private overReads;
637
+ /** One more, the keys with none in the last minute dropped. */
638
+ private overAdd;
600
639
  /** A chat's request of `key` asked urgently (it needs every relay), or the budget refused it on `relay` (it needs that one). */
601
640
  private chatNeed;
602
641
  /** The chats that need this relay: those a request of was refused there, and the urgent ones. */