@ghostlytools/sdk 1.10.3 → 1.10.5

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-Dbw01Dk9.js → fakes-BNNNkQqY.js} +2 -2
  3. package/dist/{fakes-Dbw01Dk9.js.map → fakes-BNNNkQqY.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-BT3p-YEj.js → keet-identity-key-DJbA1oSW.js} +2 -2
  8. package/dist/{keet-identity-key-BT3p-YEj.js.map → keet-identity-key-DJbA1oSW.js.map} +1 -1
  9. package/dist/{src-CCGK1Q_h.js → src-C2bAufMs.js} +738 -155
  10. package/dist/src-C2bAufMs.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/capsRecord.d.ts +19 -6
  14. package/dist/types/core/src/dhtDelivery.d.ts +47 -0
  15. package/dist/types/core/src/frames.d.ts +6 -0
  16. package/dist/types/core/src/ghostlink.d.ts +5 -0
  17. package/dist/types/core/src/groupCommunity.d.ts +23 -2
  18. package/dist/types/core/src/groupSession.d.ts +20 -1
  19. package/dist/types/core/src/http.d.ts +1 -0
  20. package/dist/types/core/src/identityProofs.d.ts +15 -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-DXMSqZzR.js → verify-CpIce6Bt.js} +3 -2
  27. package/dist/verify-CpIce6Bt.js.map +1 -0
  28. package/package.json +1 -1
  29. package/dist/src-CCGK1Q_h.js.map +0 -1
  30. package/dist/verify-DXMSqZzR.js.map +0 -1
package/dist/testing.js CHANGED
@@ -1,7 +1,7 @@
1
- import { Mw as createIdentity, Pu as emptyIdentityLedger, Ru as identityStatement, Vu as newIdentityBinding, ia as isBitcoinAddress, ju as IdentityExchange, ka as decodeBolt11, xu as IDENTITY_MAX_EVIDENCE } from "./src-CCGK1Q_h.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-C2bAufMs.js";
2
2
  import { l as providerDescriptorProblems, o as isNothingSpentError } from "./types-DvtCy3WB.js";
3
- import { i as verifyIdentity, r as descriptorProblems } from "./verify-DXMSqZzR.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-Dbw01Dk9.js";
3
+ import { i as verifyIdentity, r as descriptorProblems } from "./verify-CpIce6Bt.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-BNNNkQqY.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;
@@ -3,7 +3,7 @@ import type { LinkParams } from "./invite.js";
3
3
  import type { PairingCredentials } from "./pairedSession.js";
4
4
  import { type TransportDescriptors } from "./pairedTransports.js";
5
5
  import { type GhostRecord, type SignedPacket } from "./pkarr.js";
6
- import { type PkarrTransport } from "./transport.js";
6
+ import { type PkarrRequestOptions, type PkarrTransport } from "./transport.js";
7
7
  /**
8
8
  * The layer-0 capability record of a chat (WISP 03, revision 0.2): what each side accepts on the DHT
9
9
  * (`dht-text/1`, `hold/1`), what its layer 1 would carry, the minimum to dial its native transports
@@ -180,9 +180,12 @@ export declare class CapsExchange {
180
180
  private running;
181
181
  private lastRead;
182
182
  private readTimer;
183
+ private readBackground;
183
184
  /** The newest revision of the contact's record an envelope named, and the reads made again since for it. */
184
185
  private named;
185
186
  private retries;
187
+ /** A revision named since the last new record read started the read-again chain: the next ones named are only background reads. */
188
+ private chased;
186
189
  private retryTimer;
187
190
  /** What the last publication of this run carried. */
188
191
  private lastOut?;
@@ -219,17 +222,27 @@ export declare class CapsExchange {
219
222
  */
220
223
  update(): Promise<void>;
221
224
  private schedule;
222
- /** An envelope named this revision of the contact's record: read it when it is newer than the one known. */
225
+ /**
226
+ * An envelope named this revision of the contact's record: read it when it is newer than the one known. The number is
227
+ * the contact's word, not a record: read at the spacing. The first one named since the last new record read is read as
228
+ * the chat's own (not background) and starts the read-again chain over: a chat waits on it (a transport chosen, a
229
+ * descriptor), and while a link signals the relays hand a held background read the old copy. Any other is background
230
+ * upkeep until a new record is read. An envelope every 4 s naming a higher one each time made 45 reads a minute.
231
+ */
223
232
  peerRev(rev: number): void;
224
- /** Reads the contact's record now (or right after the last read, when that was a moment ago). */
225
- refresh(force?: boolean): void;
233
+ /**
234
+ * Reads the contact's record now (or right after the last read, when that was a moment ago). `background`: upkeep,
235
+ * on the background share of the relays' budget; a read asked for meanwhile that is not makes it one that is not.
236
+ */
237
+ refresh(force?: boolean, background?: boolean): void;
226
238
  /** Reads and checks the contact's record; the last good one stays when this one is refused. */
227
- read(): Promise<CapsRecord | undefined>;
239
+ read(options?: PkarrRequestOptions): Promise<CapsRecord | undefined>;
228
240
  /**
229
241
  * Read again in a moment, a few times at most, while the record known is short of what the contact has: of the
230
242
  * revision an envelope named, or of a descriptor for a native transport it lists (its endpoint was still starting)
231
243
  * that this side runs too. Its next revision, with the descriptor, is named only once, by an envelope that may
232
- * come before the record is out; without it neither side could dial the other.
244
+ * come before the record is out; without it neither side could dial the other. Started over only by a new record read,
245
+ * the first revision named after one, or this side's own endpoint coming up: the chat's reads, not background ones.
233
246
  */
234
247
  private readAgainIfBehind;
235
248
  }
@@ -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?;
@@ -325,9 +344,21 @@ export declare class DhtDelivery {
325
344
  private changed;
326
345
  private serialize;
327
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?;
328
349
  private sealedKey;
329
350
  private signed;
330
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;
331
362
  /**
332
363
  * The envelope's records. Ratcheted (`ratcheted`), its `_dr` record is the right length but not sealed yet: `seal`
333
364
  * gives its bytes, under the chat's lock, once the publication is sure to go. Measuring a packet takes no key.
@@ -355,6 +386,13 @@ export declare class DhtDelivery {
355
386
  * (`LEAVING_SIGNAL_READS` in all) are signaling (`PkarrRequestOptions.signal`).
356
387
  */
357
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;
358
396
  /**
359
397
  * Layer 1 carries the chat, or no longer does. While it does, the mailbox is read every 5 minutes, after one
360
398
  * last look as it goes live: a text the contact put on the DHT in the seconds before (after this side's last
@@ -369,6 +407,10 @@ export declare class DhtDelivery {
369
407
  /** The chat is open with the app in front: on the DHT, its mailbox is read at the signaling pace. */
370
408
  setActive(active: boolean): void;
371
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
+ */
372
414
  private packetError;
373
415
  /** Whether a text with its hop count fits the packet and what a reader reads (`MAX_ENVELOPE_PLAINTEXT`). */
374
416
  private roomForHops;
@@ -377,6 +419,11 @@ export declare class DhtDelivery {
377
419
  * room for it: the text is what matters, and it then reads as written here.
378
420
  */
379
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;
380
427
  /**
381
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
382
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. */
@@ -970,6 +970,9 @@ export declare class GhostLink {
970
970
  * room for the presence `peerMayHaveLeftDht` looks at, so the mailbox is read now and at the DHT pace for a while
971
971
  * here too. The offer is kept and answered, and the dial taken, once that read unblocks the stream. False when
972
972
  * something else blocks it (this side is DHT-only, the contact is not pinned, or the offer is not the contact's).
973
+ * A connection on a native endpoint (no `signal`) proves nothing yet: anyone who can dial the endpoint can open one,
974
+ * with any identities, and only the session it carries, which waits for this read, authenticates it. The reads it
975
+ * starts are held as a fresh link packet's are (`peerLinkPacket`); the connection is kept for them all the same.
973
976
  */
974
977
  private peerDialsFromDht;
975
978
  get isDataLinkOpen(): boolean;
@@ -1353,6 +1356,8 @@ export declare class GhostLink {
1353
1356
  fileAnnounceError(file: DhtFileOffer, timestamp: number, reply?: WireReply, forwarded?: number): string | null;
1354
1357
  /** What awaits its receipt on the DHT floor now, if anything does. */
1355
1358
  get dhtPendingId(): string | undefined;
1359
+ /** The last DHT send of this text went nowhere: no relay holds it, and it is off the floor (`DhtDelivery.wentNowhereFor`). */
1360
+ dhtWentNowhere(id: string): boolean;
1356
1361
  /** What went on the DHT floor under this id needs no more retries there (it went live, or was withdrawn). */
1357
1362
  settleDht(id: string): Promise<void>;
1358
1363
  /** 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;
@@ -741,7 +752,13 @@ export declare class CommunitySession {
741
752
  private holdDroppedLeaves;
742
753
  /** The entry key is the one the main branch names; its seed comes with a `group-entry` from whoever holds it. */
743
754
  private followEntry;
744
- /** 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
+ */
745
762
  private pruneSide;
746
763
  /**
747
764
  * Seen marks of epochs older than the window go, every sender's, once the branch I follow moves past them: as
@@ -750,6 +767,10 @@ export declare class CommunitySession {
750
767
  * within the window stay, a leaver's too: what it wrote before its leave is still taken up to its mark there.
751
768
  */
752
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
+ */
753
774
  private pruneSecrets;
754
775
  /** A derived epoch's secret, from its parent's, when that is held. */
755
776
  private takeDerived;
@@ -969,7 +990,7 @@ export declare class CommunitySession {
969
990
  private haveOf;
970
991
  private markSeen;
971
992
  private park;
972
- /** 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. */
973
994
  get needsCatchUp(): boolean;
974
995
  /** Asks a member I have an edge to for what I lack (the engine calls it now and then while `needsCatchUp`). */
975
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. */
@@ -466,6 +473,11 @@ export declare class GroupSession {
466
473
  private waitingBytes;
467
474
  /** Edits for an epoch, or a secret, not here yet: tried again with the frames above. In memory only. */
468
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;
469
481
  private pendingCommits;
470
482
  /** When each member was last asked to catch me up, so a stream of unreadable frames is one question, not a loop. */
471
483
  private asked;
@@ -748,7 +760,10 @@ export declare class GroupSession {
748
760
  * edits, reactions); one who read the first does not show it twice. The engine calls this on each tick.
749
761
  */
750
762
  reseal(): Promise<void>;
751
- /** 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
+ */
752
767
  private get behind();
753
768
  private resealBehind;
754
769
  /**
@@ -924,6 +939,10 @@ export declare class GroupSession {
924
939
  */
925
940
  private pruneSeen;
926
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;
927
946
  /** Whoever sent something I cannot read yet is ahead of me, or holds a secret I lack: ask, but not in a loop. */
928
947
  private ask;
929
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;
@@ -232,6 +245,8 @@ export declare class IdentityExchange {
232
245
  private requested;
233
246
  /** The nonces of the presentations in their provider's check now. */
234
247
  private checking;
248
+ /** When the contact's presentations were checked with their provider (seconds), for `IDENTITY_MAX_CHECKS_PER_HOUR`. */
249
+ private checks;
235
250
  constructor(options: IdentityExchangeOptions);
236
251
  private now;
237
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. */
@@ -55,6 +55,11 @@ export interface PkarrRequestOptions {
55
55
  * restarts publishes its offer then. A few may go over the relay's minute (`DEPARTED_READS` in relay.ts).
56
56
  */
57
57
  departed?: boolean;
58
+ /**
59
+ * A 1:1 chat's read of an invite this side made, while its joiner is due (`AWAITING_PEER_MS` in link.ts) and has not
60
+ * shown: the joiner's knock is read there. A few may go over the relay's minute (`AWAITED_READS` in relay.ts).
61
+ */
62
+ awaited?: boolean;
58
63
  /**
59
64
  * A read of a contact that was live when this app last ran, made before any read of it this run was answered
60
65
  * (`LinkSessionOptions.resumed`): the link's offer waits on it. A group edge's goes on the edges' floor
@@ -99,6 +104,25 @@ export declare class DiscoveryBudgetError extends Error {
99
104
  }
100
105
  /** Whether `error` is a request the budget held back (`DiscoveryBudgetError`), also from another copy of this module. */
101
106
  export declare function isDiscoveryBudgetError(error: unknown): error is DiscoveryBudgetError;
107
+ /**
108
+ * A publish no relay took (`RelayTransport`), saying whether one of them may hold the packet all the same. Not
109
+ * `mayBeStored` only when every relay was not asked now (its budget, its rate limit, its breaker, its network
110
+ * cooldown), answered that it did not take it (a 4xx), or could not be reached before the request went (a refused
111
+ * connection or a name that does not resolve, where the runtime says so: Node does, a browser does not), or when there
112
+ * is no relay at all. A relay that did not answer in time, dropped the connection, or answered with a server error
113
+ * may have stored it. The message is the publish's usual one.
114
+ */
115
+ export declare class PublishFailedError extends Error {
116
+ readonly mayBeStored: boolean;
117
+ readonly code = "publish-failed";
118
+ constructor(message: string, mayBeStored: boolean);
119
+ }
120
+ /**
121
+ * Whether `error` is a publish that went nowhere (`PublishFailedError` with `mayBeStored` false), also from another
122
+ * copy of this module. Anything else (a timeout, the DHT's own failure beside the relays', a Desktop's error in
123
+ * words) may have left this device.
124
+ */
125
+ export declare function publishedNowhere(error: unknown): boolean;
102
126
  /**
103
127
  * A publish Ghostly Desktop's Rust relay client held back, as it says it in words (`pkarr_network.rs`
104
128
  * `publish_failure`: "Publish held back on every relay…; retry in N ms: …"), as the `DiscoveryBudgetError` it is: every
@@ -191,4 +215,9 @@ export interface PkarrTransport {
191
215
  turnPut?(pubKeyZ32: string, payload: Uint8Array, conditions: TurnConditions): Promise<TurnSourcePut[]>;
192
216
  /** The profile has a device set: the turn's sources are made ready ahead of the first read (`TurnNetwork.turnWarm`). */
193
217
  turnWarm?(): Promise<void>;
218
+ /**
219
+ * Nothing will be put or read under these keys any more (a spare invite replaced unused): what the transport kept
220
+ * per key for them (the last packet put, its dates, each relay's last put) goes. Absent where nothing is kept.
221
+ */
222
+ forget?(keys: Iterable<string>): void;
194
223
  }
@@ -52,6 +52,8 @@ export declare class TransportSwitch {
52
52
  /** This side chose while no session was open: the next one begins with it as a choice. */
53
53
  private apart;
54
54
  private readonly policiesRead;
55
+ /** The session on which the contact's policy, the one read already, was said again and read for free (`handle`). */
56
+ private repeatRead;
55
57
  private policyHeld;
56
58
  constructor(options: {
57
59
  key: string;
@@ -1,4 +1,4 @@
1
- import { Au as IdentityCheckUnavailable, Nu as boundVerifiedIdentity } from "./src-CCGK1Q_h.js";
1
+ import { Fu as boundVerifiedIdentity, Mu as IdentityCheckUnavailable } from "./src-C2bAufMs.js";
2
2
  //#region ../browser/src/proofs/verify.ts
3
3
  var DAY = 86400;
4
4
  /**
@@ -31,6 +31,7 @@ function descriptorProblems(p) {
31
31
  const { defaultDays, maxDays } = p.validity;
32
32
  if (!(Number.isInteger(defaultDays) && Number.isInteger(maxDays) && defaultDays >= 1 && defaultDays <= maxDays && maxDays * DAY <= 3456e4)) problems.push("validity must be whole days, 1 ≤ default ≤ max ≤ 400");
33
33
  if (p.recheck && !(Number.isInteger(p.recheck.afterSeconds) && p.recheck.afterSeconds >= 60)) problems.push("recheck.afterSeconds must be at least 60");
34
+ if (p.recheck?.perHour !== void 0 && !(Number.isInteger(p.recheck.perHour) && p.recheck.perHour >= 1)) problems.push("recheck.perHour must be a whole number, at least 1");
34
35
  if (!p.signers.length) problems.push("no signers");
35
36
  const ids = p.signers.map((s) => s.id);
36
37
  if (new Set(ids).size !== ids.length) problems.push("signer ids are not unique");
@@ -103,4 +104,4 @@ function boundedIdentityFetch(options = { online: () => true }) {
103
104
  //#endregion
104
105
  export { verifyIdentity as i, boundedIdentityFetch as n, descriptorProblems as r, availableSigners as t };
105
106
 
106
- //# sourceMappingURL=verify-DXMSqZzR.js.map
107
+ //# sourceMappingURL=verify-CpIce6Bt.js.map