@ghostlytools/sdk 1.8.1 → 1.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (34) hide show
  1. package/dist/core.js +2 -593
  2. package/dist/core.js.map +1 -1
  3. package/dist/{fakes-Cyfc_vXC.js → fakes-BTB2ugB3.js} +2 -2
  4. package/dist/{fakes-Cyfc_vXC.js.map → fakes-BTB2ugB3.js.map} +1 -1
  5. package/dist/fakes.js +1 -1
  6. package/dist/index.js +2 -2
  7. package/dist/{keet-identity-key-uq3scTiE.js → keet-identity-key-a4pR0QSm.js} +2 -2
  8. package/dist/{keet-identity-key-uq3scTiE.js.map → keet-identity-key-a4pR0QSm.js.map} +1 -1
  9. package/dist/{src-DytzSJB6.js → src-BZy4lDju.js} +2045 -164
  10. package/dist/src-BZy4lDju.js.map +1 -0
  11. package/dist/testing.js +3 -3
  12. package/dist/types/core/src/appStatements.d.ts +7 -0
  13. package/dist/types/core/src/chatFiles.d.ts +4 -1
  14. package/dist/types/core/src/communityRendezvous.d.ts +5 -1
  15. package/dist/types/core/src/contactRecords.d.ts +31 -0
  16. package/dist/types/core/src/ghostlink.d.ts +38 -2
  17. package/dist/types/core/src/groupCommunity.d.ts +84 -9
  18. package/dist/types/core/src/groupFiles.d.ts +15 -0
  19. package/dist/types/core/src/groupMeta.d.ts +3 -2
  20. package/dist/types/core/src/groupSession.d.ts +96 -11
  21. package/dist/types/core/src/http.d.ts +13 -0
  22. package/dist/types/core/src/identityProofs.d.ts +7 -3
  23. package/dist/types/core/src/index.d.ts +1 -0
  24. package/dist/types/core/src/pairedAppRanges.d.ts +17 -9
  25. package/dist/types/core/src/pairedEdits.d.ts +4 -1
  26. package/dist/types/core/src/storeForward.d.ts +2 -1
  27. package/dist/types/core/src/text.d.ts +9 -0
  28. package/dist/types/core/src/turnRecord.d.ts +2 -2
  29. package/dist/types/core/src/videoMetadata.d.ts +33 -0
  30. package/dist/{verify-BC1Eu1lE.js → verify-Bcd7K4q-.js} +3 -3
  31. package/dist/verify-Bcd7K4q-.js.map +1 -0
  32. package/package.json +1 -1
  33. package/dist/src-DytzSJB6.js.map +0 -1
  34. package/dist/verify-BC1Eu1lE.js.map +0 -1
package/dist/testing.js CHANGED
@@ -1,7 +1,7 @@
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";
1
+ import { Xu as IDENTITY_MAX_EVIDENCE, cd as emptyIdentityLedger, dd as identityStatement, ia as isBitcoinAddress, ka as decodeBolt11, md as newIdentityBinding, od as IdentityExchange, vw as createIdentity } from "./src-BZy4lDju.js";
2
2
  import { l as providerDescriptorProblems, o as isNothingSpentError } from "./types-DvtCy3WB.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";
3
+ import { i as verifyIdentity, r as descriptorProblems } from "./verify-Bcd7K4q-.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-BTB2ugB3.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;
@@ -100,6 +100,13 @@ export interface SignedAppRevocation {
100
100
  signature: AppSignature;
101
101
  }
102
102
  export type AppRevocationRefusal = "bad-revocation" | AppSignatureRefusal;
103
+ /**
104
+ * One line of an app's text, from `min` to `max` code points: a title, a tagline, a store's name, a removal's or a
105
+ * revocation's reason. It is shown alone (a heading, a window title), so it holds no control character and none of
106
+ * what `stripHidden` takes from a nickname (invisible and direction-changing characters, line and paragraph
107
+ * separators), and when it is not empty it shows something (`hasVisible`). The joiners an emoji or a script needs stay.
108
+ */
109
+ export declare const isAppLine: (v: unknown, max: number, min?: number) => v is string;
103
110
  /** Checks a revocation statement's shape; the reason it is refused, or null. */
104
111
  export declare function checkAppRevokeStatement(value: unknown): string | null;
105
112
  /** Signs a revocation with the publisher's key. */
@@ -399,7 +399,10 @@ export declare class ChatFiles {
399
399
  * the windows of ten files and more at once overflowed the session's receive queue.
400
400
  */
401
401
  private startIncoming;
402
- /** The next file waiting its turn, once one ends. */
402
+ /**
403
+ * The next file waiting its turn, once one ends. The others were told they wait when they were queued: told again at
404
+ * each end, n files at once made about n²/2 frames, and their sender stored its record for each.
405
+ */
403
406
  private startNext;
404
407
  private onOffer;
405
408
  /**
@@ -103,8 +103,12 @@ export declare function readLobby(keys: {
103
103
  /**
104
104
  * The beacon to publish: my entry (or none, `mine` null, when I step down) with the other fresh
105
105
  * hubs, newest first, at most `maxHubs`. A hub not in the roster any more is dropped.
106
+ *
107
+ * Anyone holding the rendezvous secret writes this record, so what is in it does not decide what stays: my entry always
108
+ * does, then the keys I know as members (`known`) before keys I do not, and an entry dated ahead of now ranks as one of
109
+ * now. Entries stay as their hubs dated them.
106
110
  */
107
- export declare function mergeBeacon(existing: Hub[], me: string, mine: Hub | null, now?: number, isMember?: (key: string) => boolean): Hub[];
111
+ export declare function mergeBeacon(existing: Hub[], me: string, mine: Hub | null, now?: number, isMember?: (key: string) => boolean, known?: (key: string) => boolean): Hub[];
108
112
  /** The lobby to publish: my request refreshed, others' still fresh, newest last. */
109
113
  export declare function mergeLobby(existing: LobbyEntry[], mine: LobbyEntry, now?: number): LobbyEntry[];
110
114
  /** Fresh hubs of a beacon, as a member sees them. */
@@ -85,3 +85,34 @@ export declare function requestRecords(askerSeedB64: string, linkKeyZ32: string,
85
85
  * open, does not hold, or has expired by `now`. That the packet is signed by the asker key is the resolver's check.
86
86
  */
87
87
  export declare function openRequest(linkSeedB64: string, askerZ32: string, records: GhostRecord[], now: number): ContactRequest | null;
88
+ /**
89
+ * The asker's proof (WISP 8xx § Accept): in the chat a request started, the requester's app says on the live session
90
+ * that it holds the asker key the request came under. The invite a request carries is a bearer code, so whoever made
91
+ * the chat the owner joined may be someone other than the asker; until this proof comes, the request's text shows as
92
+ * not confirmed. Signed by *K* over the link key, *K*, and both sides' participation keys in that chat: the joiner's is
93
+ * new with the join, so a proof is made in the chat and for it, never before.
94
+ */
95
+ export declare const CONTACT_ASKER_FRAME = "contact-asker";
96
+ export interface ContactAskerFrame {
97
+ t: typeof CONTACT_ASKER_FRAME;
98
+ /** The link key and the asker key, z-base-32. */
99
+ l: string;
100
+ k: string;
101
+ /** Ed25519 by *K*, base64url. */
102
+ s: string;
103
+ }
104
+ /** Whose chat is whose: the inviter is the asker (it made the invite), the joiner the owner. */
105
+ export interface ContactAskerChat {
106
+ inviter: string;
107
+ joiner: string;
108
+ }
109
+ /** The requester's proof for the chat its request started. */
110
+ export declare function contactAskerFrame(askerSeedB64: string, linkKeyZ32: string, chat: ContactAskerChat): ContactAskerFrame;
111
+ /**
112
+ * Whether a proof heard in a chat is the one the owner waits for there: the link and asker keys of the request it
113
+ * accepted, signed by that asker key for this chat's two participation keys. Anything else proves nothing.
114
+ */
115
+ export declare function contactAskerHolds(frame: unknown, expected: {
116
+ link: string;
117
+ key: string;
118
+ }, chat: ContactAskerChat): boolean;
@@ -3,7 +3,7 @@ import { type DeliveryMode, type DhtDeliveryState, type DhtDeliveryView, type Dh
3
3
  import type { DhtFileAnnouncement, DhtFileOffer } from "./dhtFiles.js";
4
4
  import { type ProofAdapter, type ProofScope } from "./peerProofs.js";
5
5
  import { type IdentityScope } from "./identityProofs.js";
6
- import { type NativeEndpoint, type PairedTransport, type TransportDescriptors } from "./pairedTransports.js";
6
+ import { type NativeEndpoint, type NativeTransport, type PairedTransport, type TransportDescriptors } from "./pairedTransports.js";
7
7
  import { type LinkPreview } from "./linkPreview.js";
8
8
  import { type WireReply } from "./replies.js";
9
9
  import { type StatusCard } from "./statusCards.js";
@@ -22,6 +22,7 @@ import { type SessionCapability } from "./pairedCapabilities.js";
22
22
  import { type AppFrameEvent, type AppSendError } from "./pairedApps.js";
23
23
  import { type AppRangeTask } from "./pairedAppRanges.js";
24
24
  import { type WakeTarget } from "./pairedWake.js";
25
+ import { type ContactAskerFrame } from "./contactRecords.js";
25
26
  import { type WireReaction } from "./reactions.js";
26
27
  import { type WirePin } from "./pins.js";
27
28
  import { type TypingActivity } from "./pairedTyping.js";
@@ -367,6 +368,14 @@ export interface GhostLinkEvents {
367
368
  onPeerWake?(target: WakeTarget | null): void;
368
369
  /** Both sides offer `wake/1` on the open session (true), or no longer (false): the moment to share this side's. */
369
370
  onWakeSupport?(supported: boolean): void;
371
+ /**
372
+ * The contact said it holds the asker key of the contact request that started this chat (WISP 8xx § Accept), not
373
+ * checked yet: only the caller knows which key it waits for. With this chat's two participation keys.
374
+ */
375
+ onContactAsker?(frame: unknown, keys: {
376
+ mine: string;
377
+ peer: string;
378
+ }): void;
370
379
  /**
371
380
  * The contact's app opened, closed or sent data in one of this chat's mini-apps (`apps/1`, WISP 1200 § In a chat),
372
381
  * already checked against the receiver's limits; or, as a `close` with `offline`, the session ended while it had one
@@ -742,6 +751,8 @@ export declare class GhostLink {
742
751
  /** Edit frames the contact may send per window; the rest go unconfirmed and come again. */
743
752
  private readonly editsReceived;
744
753
  private readonly wakeReceived;
754
+ /** Said once a session by the requester's app: a few a minute at most. */
755
+ private readonly askerReceived;
745
756
  /**
746
757
  * The contact's name and picture, its word on held items, its ways of paying and its transport descriptors, each saved
747
758
  * on this side when it changes: said once a session and when changed, so a handful a minute each. Past that only the
@@ -1002,6 +1013,12 @@ export declare class GhostLink {
1002
1013
  stop(announce?: boolean): Promise<void>;
1003
1014
  /** Opens the data link if needed and resolves once it is usable. */
1004
1015
  connect(timeoutMs?: number): Promise<void>;
1016
+ /**
1017
+ * `connect` for what only needs the link (a request, a file, a payment step): on a live session it does nothing, where
1018
+ * `connect` is a retry that says this side's transport policy again, and the contact reads 10 a minute
1019
+ * (POLICY_RECEIVE_LIMIT). A shared app's every file, each file sent and each payment step used to spend one.
1020
+ */
1021
+ private open;
1005
1022
  /** Closes what a switch replaced once the contact has had time to move too. */
1006
1023
  private retire;
1007
1024
  /**
@@ -1130,6 +1147,12 @@ export declare class GhostLink {
1130
1147
  * simply be away. Two dials crossing are settled by key order (see `registerEndpoint`).
1131
1148
  */
1132
1149
  private knock;
1150
+ /**
1151
+ * This side's listener on `transport` is up again after it was let go while the contact was away (the engine's
1152
+ * `releaseGoneListeners`), and the contact is back: it is dialled once now, whichever side's turn it is, as after a
1153
+ * restart. The contact's own dials found no listener here meanwhile, and wait out their backoff (half a minute).
1154
+ */
1155
+ knockOnReturn(transport: NativeTransport): void;
1133
1156
  /** The knock under way (`knock`): its transport, its attempt, and whether it was knocked again (`knockAgain`). */
1134
1157
  private knocking;
1135
1158
  /**
@@ -1495,6 +1518,19 @@ export declare class GhostLink {
1495
1518
  * `wake/1`. False when it could not go now: the caller shares it again on the next session.
1496
1519
  */
1497
1520
  sendWake(target: WakeTarget | null): boolean;
1521
+ /**
1522
+ * This side's participation key and the pinned contact's, on a paired session that is open and ready: what the asker's
1523
+ * proof of a contact request is made for (WISP 8xx § Accept). Undefined otherwise.
1524
+ */
1525
+ get participationKeys(): {
1526
+ mine: string;
1527
+ peer: string;
1528
+ } | undefined;
1529
+ /**
1530
+ * Says on the live session that this side asked through the contact's link (WISP 8xx § Accept). No capability: an app
1531
+ * that does not know the frame drops it. False when it could not go now: the caller says it again on the next session.
1532
+ */
1533
+ sendContactAsker(frame: ContactAskerFrame): boolean;
1498
1534
  /** Both sides offer `pin/1` on the open session: a pin can be said and confirmed. */
1499
1535
  get supportsPins(): boolean;
1500
1536
  /**
@@ -1583,7 +1619,7 @@ export declare class GhostLink {
1583
1619
  sendAppRange(task: AppRangeTask, bytes: Uint8Array, size: number): Promise<void>;
1584
1620
  /** `task`'s file cannot be read: `changed` or `gone` goes in place of its bytes (nothing once it is no longer live, but its place frees). */
1585
1621
  failAppRange(task: AppRangeTask, error: "changed" | "gone"): void;
1586
- /** Whether `task` still waits for an answer on this session (`AppRanges.holds`): one that does not needs none. */
1622
+ /** Whether `task` still holds a place until it is answered (`AppRanges.holds`): one that does not needs no answer. */
1587
1623
  holdsAppRange(task: AppRangeTask): boolean;
1588
1624
  /** An `ar-*` frame from the contact, on a session that agreed `app-ranges/1`. */
1589
1625
  private receiveAppRange;
@@ -64,6 +64,8 @@ export declare const COMMUNITY_LIMITS: {
64
64
  readonly replay: 256;
65
65
  /** Commits in one welcome or chain piece. */
66
66
  readonly chainPiece: 100;
67
+ /** Admissions members other than the admin may commit in a row while the admin is away (`memberAdmissions`). */
68
+ readonly memberAdmissions: 32;
67
69
  readonly pendingLeaves: 64;
68
70
  /** Leaves whose mark (`group-left`) is kept, and the epochs one names. */
69
71
  readonly leftMarks: 64;
@@ -91,6 +93,11 @@ export declare const COMMUNITY_LIMITS: {
91
93
  readonly catchUpSlice: 16;
92
94
  /** Between two slices, when the member's app cannot say it handled one (`handled` resolves `false`). */
93
95
  readonly catchUpPauseMs: 500;
96
+ /**
97
+ * A message a member handed on with its live mark (`lv`, WISP 903 § Relaying) is live here only when the time it says
98
+ * is at most this long before my clock: the mark is that member's word, and past this it would make a catch-up ring.
99
+ */
100
+ readonly liveMarkMs: number;
94
101
  };
95
102
  /** What every member should know about who can read what, and what the link does, in the words the apps show. */
96
103
  export declare const GROUP_READ_NOTE_COMMUNITY: string;
@@ -362,7 +369,14 @@ export interface CommunityState {
362
369
  /** A few statements I held before `meta`, oldest first, for a member back from away (`keepPastGroupMeta`). Absent in older states. */
363
370
  metaPast?: GroupMeta[];
364
371
  }
365
- /** `frame`: the frame the message came in, as it is kept to hand on to a member who missed it. An app may keep it with the message it stores. */
372
+ /**
373
+ * `frame`: the frame the message came in, as it is kept to hand on to a member who missed it (without a live mark). An
374
+ * app may keep it with the message it stores.
375
+ * `live`: it came as it was written (revision 2026-11-03): straight from its author over the author's own edge, not in
376
+ * the author's answer to my sync and not one that waited for a commit or a secret; or handed on at once by the member
377
+ * at the other end of the edge, whose live mark names itself (`lv`), the time it says at most `liveMarkMs` before my
378
+ * clock. How long it took then says how far the author's clock is from mine.
379
+ */
366
380
  export interface CommunityIncomingMessage {
367
381
  id: string;
368
382
  sender: string;
@@ -376,6 +390,7 @@ export interface CommunityIncomingMessage {
376
390
  card?: StatusCard;
377
391
  file?: GroupFileMeta;
378
392
  frame?: CommunityMessageFrame;
393
+ live?: true;
379
394
  }
380
395
  /**
381
396
  * What an application sends through the group rather than as text: `frame` for everyone in the epoch (the group
@@ -415,6 +430,11 @@ export interface CommunitySessionHooks {
415
430
  * Undefined for anything else. Asked once the frame is read, before the `app` hook.
416
431
  */
417
432
  lasting?(message: CommunityIncomingApp): string | undefined;
433
+ /**
434
+ * Whether an application frame (mine or a member's) is only a hint (a `group-have`, WISP 503): relayed live like any
435
+ * frame, but never kept, so it takes no place among those a member back from away gets.
436
+ */
437
+ fleeting?(frame: Record<string, unknown>): boolean;
418
438
  /** An application frame for the group (see `sendApp`). */
419
439
  app?(message: CommunityIncomingApp): Promise<void> | void;
420
440
  /** A payload another member sealed to me (see `sendPair`). Payloads to others are carried, never opened. */
@@ -495,6 +515,10 @@ export declare class CommunitySession {
495
515
  private waiting;
496
516
  private waitingBytes;
497
517
  private asked;
518
+ /** Per member: until when what comes over its edge may be its answer to my sync (`ANSWER_WINDOW_MS`). In memory only. */
519
+ private readonly answering;
520
+ /** The message frames given to `handle` that came live here (`CommunityIncomingMessage.live`): `passOn` marks them. */
521
+ private readonly cameLive;
498
522
  /** Syncs answered per member, a few a minute (`COMMUNITY_LIMITS.syncAnswers`). In memory only. */
499
523
  private syncsAnswered;
500
524
  /** Messages taken per author, a few a second (`MessagePace`). In memory only. */
@@ -513,6 +537,8 @@ export declare class CommunitySession {
513
537
  private pendingMeta;
514
538
  /** The store's frames the app holds with their messages (`storeKey` → message id): in memory here, not in what is saved. */
515
539
  private readonly onRows;
540
+ /** The oldest epoch whose seen marks are kept, as of the last `pruneSeen`. In memory only. */
541
+ private seenFrom;
516
542
  /** `rows`: the frames the app holds with the messages it stored (`CommunityIncomingMessage.frame`). They join the store. */
517
543
  constructor(state: CommunityState, hooks: CommunitySessionHooks, rows?: readonly {
518
544
  id: string;
@@ -655,15 +681,27 @@ export declare class CommunitySession {
655
681
  private branch;
656
682
  /** How many admin changes the main branch holds up to each index. */
657
683
  private adminCounts;
658
- /** What each of two branches holds after their common parent: whether it has an admin change, and its first commit. */
684
+ /** What each of two branches holds after their common parent: whether it has an admin change, its first commit, and its hand-overs. */
659
685
  private parting;
660
686
  /**
661
- * Is branch `a` better than branch `b`? After their common parent: the one that keeps an admin
662
- * change first, however short and however far back it parts; then the longer; then, parting within
663
- * the window, the lower hash of the first commit. Both holding admin changes means the admin signed
664
- * two histories: `b` stays (a fresh one halts the group, see `receiveCommit`).
687
+ * Whether a hand-over (`h`, a `role`) went to a member whose leave of that admission I know on a branch that does not
688
+ * hold the hand-over: signed on a view from before the leave, it would leave the role with someone gone for good (a
689
+ * leave never names the admin). Not when that member signed a commit after the hand-over: it took the role while still
690
+ * in, so its leave came later, and a branch from before the hand-over must not undo what it and later admins did.
691
+ */
692
+ private handedToLeaver;
693
+ /** Whether `key` signed a commit I know that comes after `h` (on the main branch past it, or on a side branch through it). */
694
+ private signedAfter;
695
+ /**
696
+ * Is branch `a` better than branch `b`? After their common parent: first, the one that does not hand the
697
+ * role to a member who left (`handedToLeaver`); then the one that keeps an admin change, however short
698
+ * and however far back it parts; then one I can read over one whose tip lists me and whose secret I lack;
699
+ * then the longer; then, parting within the window, the lower hash of the first commit. Both holding admin changes means the admin signed two histories: `b` stays (a fresh one
700
+ * halts the group, see `receiveCommit`).
665
701
  */
666
702
  private better;
703
+ /** A commit whose roster lists me and whose secret I do not hold (yet). */
704
+ private awaitsSecret;
667
705
  /**
668
706
  * Takes in a commit (from a frame or from me): placed in the tree if it verifies against its
669
707
  * parent, a fork if the admin signed another commit after the same parent, and then the best
@@ -693,6 +731,13 @@ export declare class CommunitySession {
693
731
  private followEntry;
694
732
  /** Side commits stay up to a bound, the most recent ones (a longer branch being assembled included). */
695
733
  private pruneSide;
734
+ /**
735
+ * Seen marks of epochs older than the window go, every sender's, once the branch I follow moves past them: as
736
+ * `markSeen` drops the sender's it marks. Before, only that sender's went, so a member who left or went quiet kept
737
+ * an entry for every epoch it wrote in, and its window of numbers, for the life of the group (agents#2904). Those
738
+ * within the window stay, a leaver's too: what it wrote before its leave is still taken up to its mark there.
739
+ */
740
+ private pruneSeen;
696
741
  private pruneSecrets;
697
742
  /** A derived epoch's secret, from its parent's, when that is held. */
698
743
  private takeDerived;
@@ -725,7 +770,20 @@ export declare class CommunitySession {
725
770
  rewelcome(memberKey: string): Promise<(CommunityChainFrame | CommunityWelcomeFrame)[]>;
726
771
  /** The chain, the secrets from the admitting commit on, the rendezvous secret and the entry seed, for one newcomer. */
727
772
  private welcomeFor;
773
+ /**
774
+ * Takes a member out, and with it everyone it let in who is still in, and whom those let in in turn
775
+ * (`admittedThrough`): keys a member let in cost it nothing, and one by one they were the admin's to clear. A
776
+ * `remove` commit each, as before (an app from before follows them), one at a time, so what arrives meanwhile is
777
+ * heard, and an admission signed meanwhile by one of them is taken out too (`memberAdmissions` bounds them, as a
778
+ * removal is not the admin letting anyone in). A member already out still has those it let in cleared.
779
+ */
728
780
  remove(memberKey: string, now?: number): Promise<void>;
781
+ /**
782
+ * The members still in whose admission, on the main branch, `root` signed, or one of them did, and so on: in the
783
+ * order they were let in. An admission signed by whoever was the admin then is the admin's, not counted: removing
784
+ * a former admin does not take out everyone it let in. Never the admin nor me.
785
+ */
786
+ private admittedThrough;
729
787
  transferAdmin(memberKey: string, now?: number): Promise<void>;
730
788
  rotate(now?: number): Promise<void>;
731
789
  /** A new entry key (the old link reaches nobody), or none (`off`): a `link` commit every member follows. */
@@ -737,7 +795,11 @@ export declare class CommunitySession {
737
795
  leave(): Promise<CommunityLeaveFrame | null>;
738
796
  /** Commits the leave requests I hold whose members are still in: the engine calls this on hubs. */
739
797
  commitPendingLeaves(now?: number): Promise<number>;
740
- /** Signs and says how far I had heard a member whose leave I just committed (`group-left`). */
798
+ /**
799
+ * Signs and says how far I had heard a member whose leave I just committed (`group-left`): per epoch, up to the first
800
+ * number of my window of it I never heard, so a copy of the leaver's state cannot sign one later into the gap. A gap
801
+ * at the window's bottom (a jump past it, or a counter raised by a restore) leaves the epoch out: nothing of it then.
802
+ */
741
803
  private markLeft;
742
804
  private out;
743
805
  /**
@@ -756,7 +818,7 @@ export declare class CommunitySession {
756
818
  /**
757
819
  * An application frame to everyone in the group (a note about a payment, a request anyone may pay): sealed to
758
820
  * the epoch like text, signed, kept and caught up like text, and handed to the other members' `app` hook
759
- * instead of their history.
821
+ * instead of their history. A fleeting one (`CommunitySessionHooks.fleeting`) is only said to those up now.
760
822
  */
761
823
  sendApp(frame: Record<string, unknown>, nick?: string, now?: number): Promise<{
762
824
  id: string;
@@ -854,7 +916,16 @@ export declare class CommunitySession {
854
916
  * was new and valid, so a hub knows to relay it on.
855
917
  */
856
918
  handle(from: string, raw: unknown): Promise<boolean>;
919
+ /** After a secret came that confirms: a branch that waited for it may be the one to follow now (see `better`). */
920
+ private tookSecrets;
857
921
  private receiveLeave;
922
+ /**
923
+ * What a hub hands on of a frame it took (`handle` said it was new): as it came, without the live mark of whoever
924
+ * handed it to me, and with mine when it came live here (WISP 903 § Relaying, revision 2026-11-03). Hand it on at
925
+ * once: the mark says it is passed on as it came.
926
+ */
927
+ passOn(frame: object): object;
928
+ /** `waited`: it waited for a commit or a secret (`replayWaiting`), so it is not live. */
858
929
  private receiveMessage;
859
930
  /**
860
931
  * A frame signed with my own key that I did not send here: another copy of this profile sent it (a restored backup, a
@@ -887,7 +958,11 @@ export declare class CommunitySession {
887
958
  setPicture(picture: string | null, now?: number): Promise<void>;
888
959
  /** Renames the group: only the admin, signed under the current commit, beside the picture. */
889
960
  rename(name: string, now?: number): Promise<void>;
890
- /** Signs a body under my current commit, keeps it and sends it to everyone (hubs relay it). Inside `serialize`. */
961
+ /**
962
+ * Signs a body under my current commit, keeps it and sends it to everyone (hubs relay it). Inside `serialize`. Like a
963
+ * commit, only with admin work on and a good turn read (WISP 06 § Forced takeover): refused otherwise, or, `quiet`,
964
+ * not made. Its revision is never under the floor (WISP 06 § Raised counters).
965
+ */
891
966
  private publishMeta;
892
967
  /** A statement sealed under my current epoch, when I hold its secret. */
893
968
  private metaFrame;
@@ -21,6 +21,13 @@ export declare const GROUP_FILE_LIMITS: {
21
21
  readonly serveMoveBytes: number;
22
22
  /** How long a served transfer keeps its place while all are taken and another member asks: past it, the place is theirs. */
23
23
  readonly servePlaceMs: number;
24
+ /**
25
+ * A served transfer's pace is what it confirmed in the last `servePaceMs` (at most twice that), counted from its offer.
26
+ * While all places are taken and a member holding none asks or waits, the slowest served that long gives it its place,
27
+ * if at its pace more is left to go than it has been served and than `servePaceMs`: members on fast links do not wait
28
+ * for slow ones that asked first. Each member's transfer of a file loses its place so once per holder.
29
+ */
30
+ readonly servePaceMs: 10000;
24
31
  /** File announcements a member sends to one group in a minute. */
25
32
  readonly announcePerMinute: 8;
26
33
  /** File announcements of one member of a group fetched by themselves in `announceWindowMs`; past it, kept for a Download. */
@@ -47,6 +54,14 @@ export declare const GROUP_FILE_LIMITS: {
47
54
  */
48
55
  readonly haveFramesTaken: 20;
49
56
  readonly communityHaveEveryMs: 60000;
57
+ /**
58
+ * `group-want` frames an edge sends in `wantWindowMs`, and takes from its member, the rest dropped before anything is
59
+ * looked up: twice what it may send, as for `group-have`. A member back from away in a group of 16 asked one member
60
+ * for at most 47 in 10 seconds, its files coming as fast as the network lets them.
61
+ */
62
+ readonly wantFrames: 50;
63
+ readonly wantFramesTaken: 100;
64
+ readonly wantWindowMs: 10000;
50
65
  /**
51
66
  * How long a want waits for an offer before the next holder is asked; a transfer that does not move for as long is
52
67
  * left for the next holder too.
@@ -124,12 +124,13 @@ export declare function groupMetaNewer(a: {
124
124
  /**
125
125
  * The revision of the next statement signed under `epoch`: one past the held statement's under the same epoch, else 1.
126
126
  * Counting on from a statement of an earlier epoch would let a former admin who signed the highest safe revision leave
127
- * every later admin with a revision no member accepts.
127
+ * every later admin with a revision no member accepts. Never under `floor` (WISP 06 § Raised counters): a copy started
128
+ * from older state signs above every revision the device it replaced may have signed under the same commit.
128
129
  */
129
130
  export declare function nextGroupMetaRevision(before: {
130
131
  e: number;
131
132
  r: number;
132
- } | undefined, epoch: number): number;
133
+ } | undefined, epoch: number, floor?: number): number;
133
134
  /**
134
135
  * Statements a member keeps from before the one it holds, oldest first, so it can hand a member back from away each
135
136
  * change it missed where it was made, not only the latest (two renames read as one, 2026-10-14). A few, and their
@@ -34,7 +34,8 @@ export declare const GROUP_LIMITS: {
34
34
  readonly secretsPerFrame: 16;
35
35
  /**
36
36
  * Other members' messages kept to hand on to a member who missed them (any member catches up the others): count
37
- * and total ciphertext bytes. The oldest go first.
37
+ * and total bytes as `frameBytes` counts them. The oldest go first. The bytes hold 256 texts of `textBytes` (about
38
+ * 22 KB each as a frame), so only messages carrying boxes beside a long text give way before their count.
38
39
  */
39
40
  readonly relay: 256;
40
41
  readonly relayBytes: number;
@@ -70,6 +71,8 @@ export declare const GROUP_LIMITS: {
70
71
  readonly catchUpPauseMs: 500;
71
72
  /** A received message is in the saved state within this long (`persistSoon`): a burst of them is one save, not one each. */
72
73
  readonly saveWithinMs: 1000;
74
+ /** New name records of one member taken in `syncWindowMs` (WISP 902 § Messages, "The name record"): one a rename. */
75
+ readonly namesPerMember: 4;
73
76
  };
74
77
  /** What every member should know about who can read what, in the words the apps show. */
75
78
  export declare const GROUP_READ_NOTE: string;
@@ -175,6 +178,33 @@ export interface GroupSyncFrame {
175
178
  mt?: string;
176
179
  miss?: Record<string, Record<string, number[]>>;
177
180
  ask?: string[];
181
+ nt?: string;
182
+ }
183
+ /**
184
+ * A member's name, signed by its member key (WISP 902 § Messages, "The name record"): `v` its version, the member's
185
+ * clock when it took the name (a newer one wins), `nm` the name as its app shares it, `sig` over
186
+ * `["ghostly-group/1 name", g, k, v, nm]`. Any member keeps the latest of each and seals it again to hand it over.
187
+ * `nf`, in my own record only and never sent: the counter floor (`seqFloor`) it was signed under.
188
+ */
189
+ export interface GroupNameRecord {
190
+ v: number;
191
+ nm: string;
192
+ sig: string;
193
+ nf?: number;
194
+ }
195
+ /**
196
+ * Member `k`'s name record, `{ nm, sig }` as JSON sealed under epoch `e`'s message key with
197
+ * `["ghostly-group/1 name", g, e, k, v]` as associated data. `v` in the clear: one no newer than the one held goes
198
+ * before anything is opened. Apps from before drop the frame.
199
+ */
200
+ export interface GroupNameFrame {
201
+ t: "group-name";
202
+ g: string;
203
+ e: number;
204
+ k: string;
205
+ v: number;
206
+ nn: string;
207
+ c: string;
178
208
  }
179
209
  export interface GroupSecretsFrame {
180
210
  t: "group-secrets";
@@ -236,7 +266,7 @@ export interface GroupByeFrame {
236
266
  ts: number;
237
267
  sig: string;
238
268
  }
239
- export type GroupEdgeFrame = GroupMessageFrame | GroupEditFrame | GroupCommitFrame | GroupSyncFrame | GroupSecretsFrame | GroupLeaveFrame | GroupMetaFrame | GroupByeFrame;
269
+ export type GroupEdgeFrame = GroupMessageFrame | GroupEditFrame | GroupCommitFrame | GroupSyncFrame | GroupSecretsFrame | GroupLeaveFrame | GroupMetaFrame | GroupByeFrame | GroupNameFrame;
240
270
  export type GroupAdmissionFrame = GroupInviteFrame | GroupAcceptFrame | GroupDeclineFrame | GroupChainFrame | GroupWelcomeFrame | GroupRemovedFrame;
241
271
  export type GroupStatus = "active" | "left" | "removed" | "forked";
242
272
  export interface GroupState {
@@ -274,8 +304,10 @@ export interface GroupState {
274
304
  * `GROUP_LIMITS.provisional`. Absent in states from before they were saved.
275
305
  */
276
306
  provisional?: string[];
277
- /** Names members announced on their edges. */
307
+ /** Names members announced on their edges, in their messages or in their name records. */
278
308
  nicks: Record<string, string>;
309
+ /** The latest name record of each member in the roster, mine included, to hand over. Absent in older states. */
310
+ names?: Record<string, GroupNameRecord>;
279
311
  /** The group's metadata (its picture), as the admin last signed it and I accepted it. */
280
312
  meta?: GroupMeta;
281
313
  /** A few statements I held before `meta`, oldest first, for a member back from away (`keepPastGroupMeta`). Absent in older states. */
@@ -419,8 +451,15 @@ export declare class GroupSession {
419
451
  private asked;
420
452
  /** The signed leave of each member I last passed on, kept for an admin that was away (`byesHeld`). In memory only. */
421
453
  private byesPassed;
422
- /** Member → when the name I hold for it was said: its message's time, or the moment an edge said it (`heardName`). In memory only. */
454
+ /**
455
+ * Member → when the name I hold for it was said: its message's time, its name record's version, or the moment an edge
456
+ * said it (`heardName`). In memory only; the records held start it.
457
+ */
423
458
  private readonly nickAt;
459
+ /** The version of my name record last said to every member (`sayName`). In memory only: said again once per start. */
460
+ private nameSaid;
461
+ /** New name records taken per member, a few a minute (`GROUP_LIMITS.namesPerMember`). In memory only. */
462
+ private namesTaken;
424
463
  private queue;
425
464
  /** One metadata frame that names a commit or an epoch I do not have yet: tried again when the chain moves. */
426
465
  private pendingMeta;
@@ -498,11 +537,12 @@ export declare class GroupSession {
498
537
  get others(): string[];
499
538
  /**
500
539
  * Whether `key` could read message `messageId` (`<s>:<e>:<n>`) and still can: in the roster now, and in the roster of
501
- * its epoch or, given the message's time `ts`, in the roster of the epoch its author, behind on the chain, said it
502
- * again under (`saidAgainEpoch`): the newest after its own that comes before any `add` dated later than it. That
503
- * member read it under its first id. A holder serves a group file only to such a member (WISP 503 § Asking).
540
+ * its epoch, or of an epoch it was said again under (its author was behind, `resealBehind`): `arrived`, the one its
541
+ * copy reached this device under, or, for a message of mine, one I said it again under. That member read it under its
542
+ * first id. Decided by the epochs a frame was sealed under, never by comparing two devices' clocks. A holder serves a
543
+ * group file only to such a member (WISP 503 § Asking).
504
544
  */
505
- couldRead(key: string, messageId: string, ts?: number): boolean;
545
+ couldRead(key: string, messageId: string, arrived?: number): boolean;
506
546
  role(key: string): GroupRole | undefined;
507
547
  /** The group's picture, if it has one. */
508
548
  get picture(): string | undefined;
@@ -595,8 +635,25 @@ export declare class GroupSession {
595
635
  private kept;
596
636
  private trimRelay;
597
637
  private pruneSecrets;
598
- /** Leaves: my secrets go now; the admin removes me from the roster when it hears. */
599
- leave(): Promise<void>;
638
+ /**
639
+ * Leaves: my secrets go now; the admin removes me from the roster when it hears. `pick`: whom an admin with other
640
+ * members hands the role to first, in the same turn. The role can reach me while my leave is under way (a hand-over
641
+ * said at the same moment, agents#2890): without it the leave is refused, and the role would end with me.
642
+ */
643
+ leave(pick?: () => string | undefined): Promise<void>;
644
+ /**
645
+ * After I left (WISP 902 § Admission and departure, "A role that reaches a leave"): the next commit of my chain, by the
646
+ * admin of its tip, that keeps me in the roster. Kept, without its secret, so that my leave follows the role to whoever
647
+ * holds it now, and a role that names me goes on (`handOnAfterLeave`). True when taken. The commit that takes me out
648
+ * is the end of the leave, which the engine reads itself.
649
+ */
650
+ followAfterLeave(raw: unknown): Promise<boolean>;
651
+ /**
652
+ * After I left, a chain that names me the admin (a hand-over that crossed my leave): the role goes on to
653
+ * `pick(<the member who handed it to me>)` with a `role` commit of mine, as an admin's leave hands it. Its secret is
654
+ * sealed to the members as any commit's, and not kept: I am gone. True when it went.
655
+ */
656
+ handOnAfterLeave(pick: (by: string) => string | undefined, now?: number): Promise<boolean>;
600
657
  /** Told out of band (the admin's contact chat) that I was removed, before or instead of the commit. */
601
658
  markRemoved(): Promise<void>;
602
659
  private out;
@@ -679,6 +736,31 @@ export declare class GroupSession {
679
736
  * member it goes to, whose frames for a while may be its answer, a catch-up (never `live`).
680
737
  */
681
738
  syncFrame(ask?: readonly string[], to?: string): GroupSyncFrame;
739
+ /** Which name records I hold, of members in the roster: a sync whose tag differs is answered with them all. */
740
+ private namesTag;
741
+ /**
742
+ * My name record, signed again when the name my app shares changed since, and once after my counters were raised (WISP
743
+ * 06 § Raised counters): a copy from older state holds the record from before any rename the device it replaces made
744
+ * since, which every other member holds newer. None while my app shares no name.
745
+ */
746
+ private ownName;
747
+ /** `key`'s record sealed under my current epoch, or none. */
748
+ private nameFrameOf;
749
+ /** My name record, for an edge that just opened; none while my app shares no name. */
750
+ nameFrame(): GroupNameFrame | undefined;
751
+ /**
752
+ * On each tick: my name record to every member, once per start and again when the name my app shares changes. Past
753
+ * 16 members most have no edge with me: hubs pass it on, and whoever holds it hands it over at sync.
754
+ */
755
+ sayName(): Promise<void>;
756
+ /** Every record I hold of members in the roster but `to`, sealed under my current epoch, for a sync whose tag differs from mine. */
757
+ private namesFor;
758
+ /**
759
+ * A member's name record, from its edge or handed on: taken when it is newer than the one I hold, both the member and
760
+ * whoever handed it are in the roster, its box opens and the member's signature holds. Its name shows when it is newer
761
+ * than the last one a message or an edge said. A few new ones a minute per member; passed on the first time only.
762
+ */
763
+ private receiveName;
682
764
  /** Sequence numbers below the highest seen that never arrived, the newest `miss` of them. */
683
765
  private gaps;
684
766
  setNick(key: string, nick: string | undefined): Promise<void>;
@@ -814,7 +896,10 @@ export declare class GroupSession {
814
896
  * in the group's metadata beside the picture (WISP 902 · Group Mesh § Hubs).
815
897
  */
816
898
  setHub(key: string, role: "pin" | "exclude" | null, now?: number): Promise<void>;
817
- /** Signs a body under my current commit, keeps it and sends it to every member. Inside `serialize`. */
899
+ /**
900
+ * Signs a body under my current commit, keeps it and sends it to every member. Inside `serialize`. Like a commit, only
901
+ * with admin work on and a good turn read (WISP 06 § Forced takeover): refused otherwise, or, `quiet`, not made.
902
+ */
818
903
  private publishMeta;
819
904
  /** My statement, to a member whose sync says it holds an older one (or none); nothing to an app that says nothing. */
820
905
  private offerMeta;
@@ -30,6 +30,19 @@ export declare function sanitizeResponseHeaders(headers: HeaderList, target: Loc
30
30
  * lines becomes one header per cookie.
31
31
  */
32
32
  export declare function viewerResponseHeaders(headers: HeaderList): HeaderList;
33
+ /**
34
+ * Ghostly's connection policy for a contact's app in a viewer: its requests and forms reach only its own origin, the
35
+ * contact's service; its scripts, pictures, frames and the rest its own origin and public https sites (and inline,
36
+ * data: and blob: content), never plain http, so not a service on this machine or the local network. The same value as
37
+ * Desktop's `SERVICE_CSP` (apps/desktop/src/viewer.rs) and `OPENED_SERVICE_CSP` (`service open`,
38
+ * packages/cli/src/services.ts).
39
+ */
40
+ export declare const VIEWER_SERVICE_CSP = "default-src 'self' https: data: blob: 'unsafe-inline' 'unsafe-eval'; connect-src 'self'; form-action 'self'";
41
+ /**
42
+ * `headers` with Ghostly's policy after the contact's own, all in one `content-security-policy` joined by commas: a
43
+ * browser enforces every policy of the list, so the contact's can narrow Ghostly's but never widen it.
44
+ */
45
+ export declare function withViewerPolicy(headers: HeaderList): HeaderList;
33
46
  /**
34
47
  * Turns `http://localhost:3400/base/x` into `/x` so the client never learns or
35
48
  * follows the local address. Null when the location is not on the target origin