@ghostlytools/sdk 1.7.4 → 1.8.1

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 (35) hide show
  1. package/dist/core.js +593 -2
  2. package/dist/core.js.map +1 -1
  3. package/dist/{fakes-ClE16ouz.js → fakes-Cyfc_vXC.js} +2 -2
  4. package/dist/fakes-Cyfc_vXC.js.map +1 -0
  5. package/dist/fakes.js +1 -1
  6. package/dist/index.js +2 -2
  7. package/dist/{keet-identity-key-BRKv78jp.js → keet-identity-key-uq3scTiE.js} +2 -2
  8. package/dist/{keet-identity-key-BRKv78jp.js.map → keet-identity-key-uq3scTiE.js.map} +1 -1
  9. package/dist/{src-B5uLojgn.js → src-DytzSJB6.js} +1133 -182
  10. package/dist/src-DytzSJB6.js.map +1 -0
  11. package/dist/testing.js +3 -3
  12. package/dist/types/browser/src/shared/features.d.ts +5 -0
  13. package/dist/types/browser/src/shared/mints.d.ts +6 -0
  14. package/dist/types/core/src/chatFiles.d.ts +34 -1
  15. package/dist/types/core/src/dhtDelivery.d.ts +51 -0
  16. package/dist/types/core/src/domainProofs.d.ts +3 -2
  17. package/dist/types/core/src/engineErrors.d.ts +5 -1
  18. package/dist/types/core/src/ghostlink.d.ts +18 -0
  19. package/dist/types/core/src/groupCommunity.d.ts +44 -4
  20. package/dist/types/core/src/groupSession.d.ts +19 -21
  21. package/dist/types/core/src/groupSignals.d.ts +4 -0
  22. package/dist/types/core/src/image.d.ts +2 -0
  23. package/dist/types/core/src/index.d.ts +2 -0
  24. package/dist/types/core/src/link.d.ts +13 -0
  25. package/dist/types/core/src/pairedTransports.d.ts +14 -3
  26. package/dist/types/core/src/pictureMetadata.d.ts +25 -0
  27. package/dist/types/core/src/ratchet.d.ts +201 -0
  28. package/dist/types/core/src/relay.d.ts +15 -0
  29. package/dist/types/core/src/statusCards.d.ts +5 -0
  30. package/dist/types/core/src/storeForward.d.ts +32 -11
  31. package/dist/{verify-yJe2Uqod.js → verify-BC1Eu1lE.js} +2 -2
  32. package/dist/{verify-yJe2Uqod.js.map → verify-BC1Eu1lE.js.map} +1 -1
  33. package/package.json +1 -1
  34. package/dist/fakes-ClE16ouz.js.map +0 -1
  35. package/dist/src-B5uLojgn.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, jC as createIdentity, ra as isBitcoinAddress, rd as newIdentityBinding, zu as IDENTITY_MAX_EVIDENCE } from "./src-B5uLojgn.js";
1
+ import { $u as emptyIdentityLedger, Vu as IDENTITY_MAX_EVIDENCE, Zu as IdentityExchange, ad as newIdentityBinding, ia as isBitcoinAddress, ka as decodeBolt11, nd as identityStatement, rw as createIdentity } from "./src-DytzSJB6.js";
2
2
  import { l as providerDescriptorProblems, o as isNothingSpentError } from "./types-DvtCy3WB.js";
3
- import { i as verifyIdentity, r as descriptorProblems } from "./verify-yJe2Uqod.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-ClE16ouz.js";
3
+ import { i as verifyIdentity, r as descriptorProblems } from "./verify-BC1Eu1lE.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-Cyfc_vXC.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
  /**
@@ -107,8 +107,20 @@ export declare const FILE_LIMITS: {
107
107
  readonly stallMs: 60000;
108
108
  /** A receiver makes what it stored durable, and records the point to resume from, this often. */
109
109
  readonly checkpointBytes: number;
110
- /** A receiver confirms at least this often while writing. */
110
+ /**
111
+ * A receiver confirms at least this often while writing, and the file's last bytes at once. Its writes are buffered
112
+ * and done at once, so confirming whenever they were all done too was confirming nearly every chunk: 6,400 confirms for
113
+ * 100 MiB, each a native call and a progress update on both sides. A host that batches them (`batchConfirms`) does not.
114
+ */
111
115
  readonly ackEveryBytes: number;
116
+ /**
117
+ * Batched (`ChatFilesHost.batchConfirms`), bytes stored and not confirmed are confirmed this long after the first of
118
+ * them was stored, at most. What a sender has in flight may be no more than `ackEveryBytes` (a window at its floor, one
119
+ * chunk while the path is measured), and bytes waiting here for a confirm are bytes it cannot send: on a slow or
120
+ * wavering path a confirm comes about every this long, as fast as the window needs. A round trip it measures is up to
121
+ * this much longer, well inside the queue it allows (`queueMs`).
122
+ */
123
+ readonly ackWaitMs: 10;
112
124
  /** A sender reads its file this much at a time. */
113
125
  readonly readBytes: number;
114
126
  /** The session refused a data frame (its send budget was full): the sender looks again after this long. */
@@ -159,6 +171,12 @@ export interface FileTransferRecord {
159
171
  agreed?: boolean;
160
172
  }
161
173
  export declare const transferEnded: (record: FileTransferRecord) => boolean;
174
+ /**
175
+ * Whether a file sent from here arrived whole (the receiver confirmed every byte, and may be checking it): too late
176
+ * for its person to cancel. The receiver's check comes before a `pf-abort` behind it, so it would keep the file while
177
+ * the sender said it was cancelled. Not once the receiver asks about it again (`asking`), nor paused here.
178
+ */
179
+ export declare function sentWhole(record: FileTransferRecord): boolean;
162
180
  /**
163
181
  * Whether an unfinished transfer is stuck, so its person is offered to push it: "Send again" (sending) or "Ask again"
164
182
  * (receiving). `movedAt` is when its bytes last moved, `restored` that it has not moved since the app started. What
@@ -229,6 +247,12 @@ export interface ChatFilesHost {
229
247
  */
230
248
  resend?(record: FileTransferRecord, sent: number): boolean;
231
249
  now?(): number;
250
+ /**
251
+ * Receiving, a confirm goes every `FILE_LIMITS.ackEveryBytes` stored, or `FILE_LIMITS.ackWaitMs` after the first
252
+ * bytes it would confirm, not whenever the writes are all done (nearly every chunk). Not for a group's edges: on a
253
+ * shared uplink an edge's window goes down to a chunk (`FileUplink.floor`), far less than a confirm's worth.
254
+ */
255
+ batchConfirms?: boolean;
232
256
  /**
233
257
  * The uplink this chat's files share with others that leave the device by it (`FileUplink`): a group's edges, each
234
258
  * a `ChatFiles` of its own, serving one file to several members at once. Absent: the uplink is this chat's alone.
@@ -296,6 +320,13 @@ export declare class ChatFiles {
296
320
  private peerRoomValue;
297
321
  /** What the chat's files may have in flight, sized by the path. */
298
322
  private readonly pace;
323
+ /**
324
+ * What the chat's files had in flight just before the last confirm. A receiver confirms many chunks at once
325
+ * (`ackEveryBytes`), and the chunks sent for them go with that much in flight, the window: counted one by one, the
326
+ * first went with the window less a confirm, and read as a path carrying that little, it shrank the window and ended
327
+ * every trial of a larger one (a fifth of the rate on a wavering path). Confirmed chunk by chunk, it is what each sends with.
328
+ */
329
+ private refill;
299
330
  constructor(host: ChatFilesHost);
300
331
  /** The floor of this chat's window: all of `minWindowBytes`, or its share of an uplink it shares (`FileUplink`). */
301
332
  private floor;
@@ -380,6 +411,8 @@ export declare class ChatFiles {
380
411
  /** An agreed file that ended here, offered again: taken again from the start. */
381
412
  private retake;
382
413
  private onData;
414
+ /** `pf-got` for what is stored and not confirmed yet. */
415
+ private confirm;
383
416
  /** What was stored is durable, and a restart resumes from there. */
384
417
  private checkpoint;
385
418
  private checkpointNow;
@@ -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. */
@@ -1124,6 +1130,16 @@ export declare class GhostLink {
1124
1130
  * simply be away. Two dials crossing are settled by key order (see `registerEndpoint`).
1125
1131
  */
1126
1132
  private knock;
1133
+ /** The knock under way (`knock`): its transport, its attempt, and whether it was knocked again (`knockAgain`). */
1134
+ private knocking;
1135
+ /**
1136
+ * The endpoint of a knock still under way is back on its relay (`NativeEndpoint.onRelayBack`): it is knocked again, once,
1137
+ * beside the first, and the first live wins. An Android phone back from Doze knocked at once through an Iroh whose relay
1138
+ * was gone; Iroh found it again only seconds later (its reconnect backoff, up to 16 s), and what the knock sent meanwhile
1139
+ * went nowhere: QUIC sends it again seconds on, and the dial is given 20 s. Live again 4.4 s and 9.8 s after the
1140
+ * return (away 5 and 15 minutes), and once not over Iroh at all (the emulator with a CLI bot, 2026-11-01).
1141
+ */
1142
+ private knockAgain;
1127
1143
  canReleaseEndpoint(transport: PairedTransport): boolean;
1128
1144
  releaseEndpoint(transport: PairedTransport): Promise<void>;
1129
1145
  /** When the chat was last in use on its session: the contact's last frame of use, or the session's start. */
@@ -1272,6 +1288,8 @@ export declare class GhostLink {
1272
1288
  private attemptEnded;
1273
1289
  /** The last attempt to go live that did not (WISP 100, "Why a chat is not live"); none while live. */
1274
1290
  get liveAttempt(): LiveAttempt | undefined;
1291
+ /** Automatic dials since the link was last live or its wait started over (`wake`), the one under way included. */
1292
+ get dialAttempts(): number;
1275
1293
  /**
1276
1294
  * Which side dials this chat to go live: the lower rendezvous key, or the joiner of a first pairing (WISP 100). The
1277
1295
  * other side answers, so what it can tell of a failed attempt is only what reached it.
@@ -173,13 +173,22 @@ export declare function verifyCommunityCommit(raw: unknown, parent: CommunityCom
173
173
  * handed: a `leave` in it is not held to the admission it ends, since a chain from before 2026-10-10 may hold a
174
174
  * member's second leave under the one statement there was, and no newcomer could enter that group again.
175
175
  */
176
- export declare function verifyCommunityChain(raw: unknown, groupId?: string): {
176
+ export declare function verifyCommunityChain(raw: unknown, groupId?: string): VerifiedChain | {
177
+ error: string;
178
+ };
179
+ /**
180
+ * `verifyCommunityChain` for a client whose engine shares its page's thread: the same checks, letting the thread go every
181
+ * `CHAIN_SLICE_MS` of them. One commit's signature takes ~2.6 ms in JavaScript on a desktop CPU, several times that on a
182
+ * phone, so a history near `COMMUNITY_LIMITS.chain` checked at once was an app that drew nothing for 5 s and more.
183
+ */
184
+ export declare function verifyCommunityChainPaced(raw: unknown, groupId?: string): Promise<VerifiedChain | {
185
+ error: string;
186
+ }>;
187
+ type VerifiedChain = {
177
188
  chain: CommunityCommit[];
178
189
  roster: Roster;
179
190
  entry: string;
180
191
  rosters: Roster[];
181
- } | {
182
- error: string;
183
192
  };
184
193
  export interface CommunityMessageFrame {
185
194
  t: "group-msg";
@@ -526,6 +535,16 @@ export declare class CommunitySession {
526
535
  } | {
527
536
  error: string;
528
537
  };
538
+ /** `join`, its chain checked a slice at a time (`verifyCommunityChainPaced`): what an app sharing its page's thread calls. */
539
+ static joinPaced(link: {
540
+ g: string;
541
+ host: string;
542
+ }, pieces: unknown[], welcome: unknown, seedB64: string, now?: number): Promise<{
543
+ state: CommunityState;
544
+ } | {
545
+ error: string;
546
+ }>;
547
+ private static joinVerified;
529
548
  get id(): string;
530
549
  /** The name the admin gave the group, else the one it had when I got in (WISP 903 § Metadata). */
531
550
  get name(): string;
@@ -547,11 +566,31 @@ export declare class CommunitySession {
547
566
  get canSend(): boolean;
548
567
  /** The entry key of the group's link, or "" when it is off. */
549
568
  get entryKey(): string;
569
+ /**
570
+ * The entry key of the link my admission that lost was let in by (the one its branch named), where I ask again: a
571
+ * link replaced since keeps me out as it does anyone. `entryKey` once that admission is no longer held.
572
+ */
573
+ get lostEntryKey(): string;
550
574
  role(key: string): GroupRole | undefined;
551
575
  /** The group's picture, if it has one. */
552
576
  get picture(): string | undefined;
553
- /** Members of any epoch in the window: whom a frame may come from. */
577
+ /**
578
+ * Members of any epoch in the window: whom a frame may come from. A side commit's roster counts only while its branch
579
+ * could still win (`mayWin`): one let in only on a branch that lost is not in the roster anyone sees, and the main
580
+ * branch past where they part, a later link among it, is not its business (`lostAt`).
581
+ */
554
582
  isRecentMember(key: string): boolean;
583
+ /**
584
+ * The side commits whose branch could still win: it does not drop an admin change the main branch holds (one that
585
+ * does never wins, see `better`), and it parts within the window. Kept until the tip or the side moves.
586
+ */
587
+ private mayWin;
588
+ private winning;
589
+ /**
590
+ * 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
591
+ * the commit that makes it lose (the latest over its branches). Undefined for anyone else.
592
+ */
593
+ private lostAt;
555
594
  /**
556
595
  * Whether `key` could read message `messageId` (`<s>:<e>:<h>:<n>`) and still can: a member of the roster it was sealed
557
596
  * for, and of the roster now. A holder serves a group file only to such a member (WISP 503 § Asking).
@@ -879,3 +918,4 @@ export declare class CommunitySession {
879
918
  private fork;
880
919
  }
881
920
  export declare function signCommunity(commit: Omit<CommunityCommit, "sig">, seed: Uint8Array): CommunityCommit;
921
+ export {};
@@ -431,16 +431,10 @@ export declare class GroupSession {
431
431
  /** Set while a save of what received messages changed is due (`persistSoon`). */
432
432
  private saveTimer;
433
433
  /**
434
- * The frames of members who left that each member was handed (`frameKey`), so an app that does not take them (from
435
- * before revision 2026-10-13, and never marks them seen) is not handed them again at every sync. In memory only.
434
+ * The removals of authors out of the roster that each member was handed (`editKey`), so an app that does not take
435
+ * them is not handed them again at every sync. In memory only.
436
436
  */
437
437
  private leaversHanded;
438
- /**
439
- * The frames a commit took out of the logs (`pruneRelay`), newest last, and whether the app holds them with its
440
- * messages: a removal's `left` mark can come after its commit, and what the leaver wrote is then kept again
441
- * (`unprune`). In memory only: started again, the app's rows bring theirs back.
442
- */
443
- private pruned;
444
438
  /** Syncs answered per member, a few a minute (`GROUP_LIMITS.syncAnswers`). In memory only. */
445
439
  private syncsAnswered;
446
440
  /**
@@ -454,6 +448,8 @@ export declare class GroupSession {
454
448
  * message written just now. Each frame of the answer keeps it open: it goes a slice at a time. In memory only.
455
449
  */
456
450
  private readonly answering;
451
+ /** Per member ahead of me: the epoch its last sync said, up to which its answer to mine brings the chain. In memory only. */
452
+ private readonly syncedEpoch;
457
453
  /** Catch-up answers still going out, a slice at a time (`handOut`). */
458
454
  private readonly answers;
459
455
  /**
@@ -555,8 +551,9 @@ export declare class GroupSession {
555
551
  private serialize;
556
552
  private persist;
557
553
  /**
558
- * A save within `GROUP_LIMITS.saveWithinMs`, for what a received message changes (what was seen, what is kept to hand
559
- * on): the state holds the whole hand-on log, and a member back in a busy group wrote all of it once per message.
554
+ * A save within `GROUP_LIMITS.saveWithinMs`, for what a received message, commit or secret changes (what was seen,
555
+ * what is kept to hand on, the chain): the state holds the whole hand-on log and chain, and a member back in a busy
556
+ * group wrote all of it once per message, and once per commit.
560
557
  * The message itself is stored before (`hooks.message`). An app killed before the save takes those frames again when
561
558
  * it syncs: its store has the messages already, and the state then catches up.
562
559
  */
@@ -586,15 +583,10 @@ export declare class GroupSession {
586
583
  /** A fresh secret without a membership change: whoever holds the old one and is not a member learns nothing new. */
587
584
  rotate(now?: number): Promise<void>;
588
585
  private commit;
589
- /**
590
- * Someone removed is not handed on any more, whatever they sent while in the roster; one who left still is, for the
591
- * epochs before its leave (WISP 902 § Catch-up).
592
- */
586
+ /** Someone removed or gone is not handed on any more, whatever they sent while in the roster (WISP 902 § Catch-up). */
593
587
  private pruneRelay;
594
588
  /** Whether a kept edit is a removal (WISP 400 § Delete for everyone): its box, under its epoch's key, says `rm`. */
595
589
  private isRemovalEdit;
596
- /** The frames `pruneRelay` dropped that are handed on again now (a removal's `left` mark came after it), back in their logs. */
597
- private unprune;
598
590
  /** 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. */
599
591
  private keepEdit;
600
592
  /** A frame of another member, kept to hand on; the oldest go once the log is full. */
@@ -742,8 +734,8 @@ export declare class GroupSession {
742
734
  private commitUnlessTurnUnconfirmed;
743
735
  /**
744
736
  * A message, from its author's edge or handed on by another member. Handed on, it is taken only while both are in
745
- * the roster (someone removed is neither heard from nor handed on, #300), or from a member in it when its author left
746
- * after it (`handsOn`), and its boxes only with the author's `xs`.
737
+ * the roster (someone removed or gone is neither heard from nor handed on, #300, `handsOn`), and its boxes only with
738
+ * the author's `xs`.
747
739
  */
748
740
  private receiveMessage;
749
741
  /**
@@ -778,12 +770,18 @@ export declare class GroupSession {
778
770
  private park;
779
771
  /** Whoever sent something I cannot read yet is ahead of me, or holds a secret I lack: ask, but not in a loop. */
780
772
  private ask;
773
+ /**
774
+ * Whether my sync to `from` (the one my edge opened with) still waits for its answer, which has the chain from the
775
+ * epoch it said: asking again on reading its newer sync, or a commit of that answer, had each commit I missed sent
776
+ * twice, each with a secret sealed again (200 missed went as 400 frames, 1,456 when answers go a slice at a time).
777
+ */
778
+ private awaitsAnswer;
781
779
  private replayWaiting;
782
780
  private receiveCommit;
783
781
  /**
784
- * Whether a frame of `author` under `epoch` is taken from another member, kept and handed on: while its author is in
785
- * the roster, or when it left (its removal marked `left`, and it is not back in) and the frame is from before that,
786
- * and from after any removal of it before that was not a leave: let back in, it is not handed on for those epochs.
782
+ * Whether a frame of `author` is taken from another member, kept and handed on: only while its author is in the
783
+ * roster. One who left, as one removed, keeps its seed and the secrets of its epochs, and a copy of its state signs
784
+ * frames for them after the leave, dated as it likes: whether the admin marked its removal `left` changes nothing.
787
785
  */
788
786
  private handsOn;
789
787
  /** Keeps the admin's mark on a commit that took out a member who left (`GroupCommitFrame.left`) when it holds; true when new. */
@@ -74,6 +74,8 @@ export interface CarriedHooks {
74
74
  taken: number;
75
75
  sure: boolean;
76
76
  };
77
+ /** Whether `carry` would hand a packet to any link now (none: every member that could pass it on is away). */
78
+ canCarry?(): boolean;
77
79
  /** The edge's own data link is open: it carries everything, and nothing is handed to anyone. */
78
80
  open(): boolean;
79
81
  /** A carried packet of the member's is here and no read is under way: look now. */
@@ -115,6 +117,8 @@ export declare class CarriedTransport implements PkarrTransport {
115
117
  private seen;
116
118
  /** A read under way: resolved when a carried packet comes meanwhile. */
117
119
  private waiting;
120
+ /** The records of a publish refused before they were signed, while nobody could carry them: signed when one can (`latest`). */
121
+ private unsigned;
118
122
  /** The packet the relays have not got yet. */
119
123
  private pending;
120
124
  /** How many carried packets of the member's came: a deferral that ends with none more says no member reaches it. */
@@ -34,6 +34,8 @@ export declare function previewable(size: ImageMeta | undefined): boolean;
34
34
  export declare function isImageMime(mime: string): boolean;
35
35
  /** A peer's `image` description, or undefined when it is not one. It never refuses the file. */
36
36
  export declare function parseImageMeta(value: unknown, mime?: string): ImageMeta | undefined;
37
+ /** The EXIF orientation in an APP1 segment's TIFF block (1 when it says none). */
38
+ export declare function exifOrientation(b: Uint8Array, tiff: number, end: number): number;
37
39
  /**
38
40
  * A picture's size as it is shown, read from its first bytes (PNG, JPEG, GIF, WebP), or undefined when they do not
39
41
  * say. Only the header is read: a JPEG whose frame header, or a GIF whose first frame, sits past
@@ -34,6 +34,7 @@ export * from "./chatFiles.js";
34
34
  export * from "./voice.js";
35
35
  export * from "./video.js";
36
36
  export * from "./image.js";
37
+ export * from "./pictureMetadata.js";
37
38
  export * from "./linkPreview.js";
38
39
  export * from "./messageTime.js";
39
40
  export * from "./payments.js";
@@ -61,6 +62,7 @@ export * from "./capsRecord.js";
61
62
  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
63
  export { DHT_FILE_CAPABILITY, dhtFileId, dhtFileElements, readDhtFile, type DhtFileAnnouncement, type DhtFileElement, type DhtFileMeta, type DhtFileOffer } from "./dhtFiles.js";
63
64
  export * from "./storeForward.js";
65
+ export * from "./ratchet.js";
64
66
  export * from "./paymentIntent.js";
65
67
  export * from "./bitcoinAddress.js";
66
68
  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`).
@@ -21,6 +21,8 @@ export interface NativeEndpoint {
21
21
  onConnection: ((connection: BoundChannel) => void) | null;
22
22
  onDescriptor: (() => void) | null;
23
23
  onUnavailable?: (() => void) | null;
24
+ /** The endpoint is connected to its relay again after it lost it (the native Iroh's home relay; nothing else says it). */
25
+ onRelayBack?: (() => void) | null;
24
26
  }
25
27
  export type TransportDescriptors = Partial<Record<NativeTransport, unknown>>;
26
28
  /**
@@ -31,8 +33,9 @@ export type TransportDescriptors = Partial<Record<NativeTransport, unknown>>;
31
33
  *
32
34
  * So every relay URL is put in one spelling before it goes into an Iroh endpoint (the relays it homes on, a contact's
33
35
  * descriptor before a dial), and which one depends on the endpoint:
34
- * - `"dotted"`, the name with its trailing dot: what native Iroh homes on by default (the Desktop), and the form to
35
- * compare two relays in.
36
+ * - `"dotted"`, n0's relays with their trailing dot: what native Iroh homes on by default (the Desktop), and the form
37
+ * to compare two relays in. Any other relay keeps its plain name here too: a relay behind a proxy (a Cloudflare
38
+ * tunnel) is found by its Host header, and the proxy answers the dotted name with 404.
36
39
  * - `"plain"`, the name without it: the only one every browser opens. WebKit (Safari, the iPhone app) refuses a
37
40
  * host name that ends in a dot, for `fetch` and for a WebSocket alike, so nothing a browser's Iroh is given has one.
38
41
  *
@@ -48,10 +51,18 @@ export declare function irohDescriptor<T>(descriptor: T, spelling?: IrohRelaySpe
48
51
  * as a test relay is (the same rule as the relay settings).
49
52
  */
50
53
  export declare const RELAY_URL: RegExp;
54
+ /**
55
+ * A relay URL with more than its server's address in it: a login, a query or a fragment, which no relay setting takes
56
+ * (irohWeb.ts `irohRelayProblem`, hyperdhtRelay.ts `hyperdhtRelayProblem`). An older app named its HyperDHT relay as
57
+ * set, with them; such a descriptor is not dialed or kept, and the rest of what the contact told still is.
58
+ */
59
+ export declare const RELAY_WITH_SECRETS: RegExp;
60
+ /** A relay URL a descriptor may name: `RELAY_URL`, with nothing but the server's address in it. */
61
+ export declare const relayUrl: (value: unknown) => value is string;
51
62
  /**
52
63
  * A contact's native descriptors as it tells them on a session (`paired-policy`, `paired-adapters`) or as this app
53
64
  * kept them: only what the adapters dial, each field in the shape its adapter makes. The keys are 64 hex characters,
54
- * a relay passes `RELAY_URL` (the rule its capability record is read by), an Iroh descriptor lists at most eight
65
+ * a relay passes `relayUrl` (the rule its capability record is read by), an Iroh descriptor lists at most eight
55
66
  * socket addresses. A descriptor that is anything else is left out, as one the contact never told; a field this app
56
67
  * does not know is not kept.
57
68
  */
@@ -0,0 +1,25 @@
1
+ export declare const PICTURE_METADATA_LIMITS: {
2
+ /** The largest picture read whole to remove its metadata: past this it is refused. */
3
+ readonly maxBytes: number;
4
+ /** Bytes read first to tell a picture from another file. */
5
+ readonly headBytes: 64;
6
+ };
7
+ /** Why a picture is refused: its metadata could not be removed, so it does not go at all. */
8
+ export declare const NO_PICTURE_METADATA = "This picture cannot be sent: Ghostly could not remove the details saved in it, like where it was taken";
9
+ /**
10
+ * A picture's bytes without its metadata, as parts to put in a Blob; undefined when the file is not a picture this
11
+ * strips (by its bytes and its type), so it goes as it is. Throws `NO_PICTURE_METADATA` when it is one but its
12
+ * metadata cannot be removed.
13
+ */
14
+ export declare function stripPictureMetadata(bytes: Uint8Array, mime: string): Uint8Array[] | undefined;
15
+ /**
16
+ * Whether a file is a picture whose metadata goes before it is sent, by its first `PICTURE_METADATA_LIMITS.headBytes`
17
+ * bytes or by its type: then it is read whole and stripped (`stripPictureMetadata`), else it goes as it is.
18
+ */
19
+ export declare function isStrippedPicture(head: Uint8Array, mime: string): boolean;
20
+ /**
21
+ * `source` as it is sent: without its metadata when it is a picture (`stripPictureMetadata`), or undefined when it is
22
+ * not one and goes as it is. Only its first bytes are read for any other file. Throws `NO_PICTURE_METADATA` for a
23
+ * picture that cannot be stripped or is past `PICTURE_METADATA_LIMITS.maxBytes`; an error reading `source` as it is.
24
+ */
25
+ export declare function withoutPictureMetadata(source: Blob, mime: string): Promise<Blob | undefined>;