@ghostlytools/sdk 1.9.0 → 1.10.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.
- package/dist/core.js +2 -2
- package/dist/{fakes-Bx53XiDM.js → fakes-83bCOBaf.js} +2 -2
- package/dist/{fakes-Bx53XiDM.js.map → fakes-83bCOBaf.js.map} +1 -1
- package/dist/fakes.js +1 -1
- package/dist/index.js +2 -2
- package/dist/{keet-identity-key-D8ioYMkd.js → keet-identity-key-DyvuvnRO.js} +2 -2
- package/dist/{keet-identity-key-D8ioYMkd.js.map → keet-identity-key-DyvuvnRO.js.map} +1 -1
- package/dist/{src-Ch4NWeBg.js → src-CEgQHzFr.js} +3094 -1885
- package/dist/src-CEgQHzFr.js.map +1 -0
- package/dist/testing.js +3 -3
- package/dist/types/core/src/appStatements.d.ts +7 -0
- package/dist/types/core/src/callSignal.d.ts +10 -0
- package/dist/types/core/src/communityRendezvous.d.ts +5 -1
- package/dist/types/core/src/contactRecords.d.ts +31 -0
- package/dist/types/core/src/engineErrors.d.ts +1 -0
- package/dist/types/core/src/ghostlink.d.ts +40 -2
- package/dist/types/core/src/groupCommunity.d.ts +117 -11
- package/dist/types/core/src/groupFiles.d.ts +15 -0
- package/dist/types/core/src/groupMeta.d.ts +3 -2
- package/dist/types/core/src/groupSession.d.ts +142 -14
- package/dist/types/core/src/http.d.ts +13 -0
- package/dist/types/core/src/identityProofs.d.ts +7 -3
- package/dist/types/core/src/link.d.ts +16 -2
- package/dist/types/core/src/pairedAppRanges.d.ts +17 -9
- package/dist/types/core/src/pairedEdits.d.ts +4 -1
- package/dist/types/core/src/pairedTransports.d.ts +8 -0
- package/dist/types/core/src/pairedWake.d.ts +2 -1
- package/dist/types/core/src/storeForward.d.ts +2 -1
- package/dist/types/core/src/text.d.ts +9 -0
- package/dist/types/core/src/turnRecord.d.ts +2 -2
- package/dist/types/core/src/videoMetadata.d.ts +17 -0
- package/dist/types/core/src/webPush.d.ts +15 -6
- package/dist/{verify-Bi_Y5oat.js → verify-BWOWTWmV.js} +3 -3
- package/dist/verify-BWOWTWmV.js.map +1 -0
- package/package.json +1 -1
- package/dist/src-Ch4NWeBg.js.map +0 -1
- package/dist/verify-Bi_Y5oat.js.map +0 -1
package/dist/testing.js
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import { Au as IdentityExchange, Cw as createIdentity, Fu as identityStatement, Mu as emptyIdentityLedger, Ru as newIdentityBinding, bu as IDENTITY_MAX_EVIDENCE, ia as isBitcoinAddress, ka as decodeBolt11 } from "./src-CEgQHzFr.js";
|
|
2
2
|
import { l as providerDescriptorProblems, o as isNothingSpentError } from "./types-DvtCy3WB.js";
|
|
3
|
-
import { i as verifyIdentity, r as descriptorProblems } from "./verify-
|
|
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-
|
|
3
|
+
import { i as verifyIdentity, r as descriptorProblems } from "./verify-BWOWTWmV.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-83bCOBaf.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. */
|
|
@@ -170,6 +170,16 @@ export declare function extractParamsFromSdp(sdp: string, { maxCandidates, loopb
|
|
|
170
170
|
}): Partial<CallSignal>;
|
|
171
171
|
/** Offers, answers and hang-ups older (or further in the future) than this are ignored. */
|
|
172
172
|
export declare const CALL_SIGNAL_MAX_AGE_MS = 120000;
|
|
173
|
+
/**
|
|
174
|
+
* A call that comes this soon after the contact's last missed one does not ring, when that one barely rang
|
|
175
|
+
* (`BURST_RING_MS`): a bot looping call and hang-up does that (1,375 calls a minute), no person does. It is kept as a
|
|
176
|
+
* missed call, and the wait starts over with it, so a burst rings once and a call placed after a pause rings again.
|
|
177
|
+
* A person's call that rang a while, then was cancelled or rang out, holds nothing back: calling again at once (voice to
|
|
178
|
+
* video, a slip of the finger) rings. The apps (`useWebRTC`) and the headless CLI's call manager both keep it.
|
|
179
|
+
*/
|
|
180
|
+
export declare const QUICK_REDIAL_MS = 2000;
|
|
181
|
+
/** A missed call that rang shorter than this was not a person's (`QUICK_REDIAL_MS`). */
|
|
182
|
+
export declare const BURST_RING_MS = 1000;
|
|
173
183
|
/**
|
|
174
184
|
* A signal dated further ahead of this clock than this is not taken, however it was heard. A receiver acts on a signal
|
|
175
185
|
* only when its `ts` is later than the last one it acted on: taken, a signal dated a day ahead would be that last one,
|
|
@@ -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;
|
|
@@ -71,6 +71,7 @@ export declare const ENGINE_ERRORS: {
|
|
|
71
71
|
readonly fedimintAlreadyJoined: "You already joined this federation";
|
|
72
72
|
readonly fedimintConnecting: "Wait for the federation to connect";
|
|
73
73
|
readonly fedimintNotEnough: "Not enough in this federation";
|
|
74
|
+
readonly fedimintRedeemUnheard: "Could not hear from the federation about these notes: if they don't show in your balance soon, paste them again";
|
|
74
75
|
readonly fedimintRealOnTestnet: "This federation holds real bitcoin: it belongs in a Mainnet Fedimint wallet";
|
|
75
76
|
readonly fedimintTestOnMainnet: "This federation is on {chain}, a test network: it belongs in a Testnet Fedimint wallet";
|
|
76
77
|
readonly walletAway: "{wallet} can't be used here. Use it on {device}.";
|
|
@@ -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
|
|
@@ -580,6 +589,8 @@ export interface GhostLinkOptions {
|
|
|
580
589
|
avatar?: string;
|
|
581
590
|
lastSeenTimestamp?: number;
|
|
582
591
|
pollIntervals?: PollIntervals;
|
|
592
|
+
/** A contact that left a live session is read no slower than the idle pace this long (a CLI daemon's, `DAEMON_WATCH_PEER_IDLE_MS`). */
|
|
593
|
+
watchPeerIdleMs?: number;
|
|
583
594
|
/**
|
|
584
595
|
* The transport this chat was live on when the app last ran (it quit, or crashed, with the session up). The contact is
|
|
585
596
|
* probably still there, holding a session that is dead now: that transport is dialled first, and a native one is
|
|
@@ -742,6 +753,8 @@ export declare class GhostLink {
|
|
|
742
753
|
/** Edit frames the contact may send per window; the rest go unconfirmed and come again. */
|
|
743
754
|
private readonly editsReceived;
|
|
744
755
|
private readonly wakeReceived;
|
|
756
|
+
/** Said once a session by the requester's app: a few a minute at most. */
|
|
757
|
+
private readonly askerReceived;
|
|
745
758
|
/**
|
|
746
759
|
* The contact's name and picture, its word on held items, its ways of paying and its transport descriptors, each saved
|
|
747
760
|
* 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 +1015,12 @@ export declare class GhostLink {
|
|
|
1002
1015
|
stop(announce?: boolean): Promise<void>;
|
|
1003
1016
|
/** Opens the data link if needed and resolves once it is usable. */
|
|
1004
1017
|
connect(timeoutMs?: number): Promise<void>;
|
|
1018
|
+
/**
|
|
1019
|
+
* `connect` for what only needs the link (a request, a file, a payment step): on a live session it does nothing, where
|
|
1020
|
+
* `connect` is a retry that says this side's transport policy again, and the contact reads 10 a minute
|
|
1021
|
+
* (POLICY_RECEIVE_LIMIT). A shared app's every file, each file sent and each payment step used to spend one.
|
|
1022
|
+
*/
|
|
1023
|
+
private open;
|
|
1005
1024
|
/** Closes what a switch replaced once the contact has had time to move too. */
|
|
1006
1025
|
private retire;
|
|
1007
1026
|
/**
|
|
@@ -1130,6 +1149,12 @@ export declare class GhostLink {
|
|
|
1130
1149
|
* simply be away. Two dials crossing are settled by key order (see `registerEndpoint`).
|
|
1131
1150
|
*/
|
|
1132
1151
|
private knock;
|
|
1152
|
+
/**
|
|
1153
|
+
* This side's listener on `transport` is up again after it was let go while the contact was away (the engine's
|
|
1154
|
+
* `releaseGoneListeners`), and the contact is back: it is dialled once now, whichever side's turn it is, as after a
|
|
1155
|
+
* restart. The contact's own dials found no listener here meanwhile, and wait out their backoff (half a minute).
|
|
1156
|
+
*/
|
|
1157
|
+
knockOnReturn(transport: NativeTransport): void;
|
|
1133
1158
|
/** The knock under way (`knock`): its transport, its attempt, and whether it was knocked again (`knockAgain`). */
|
|
1134
1159
|
private knocking;
|
|
1135
1160
|
/**
|
|
@@ -1495,6 +1520,19 @@ export declare class GhostLink {
|
|
|
1495
1520
|
* `wake/1`. False when it could not go now: the caller shares it again on the next session.
|
|
1496
1521
|
*/
|
|
1497
1522
|
sendWake(target: WakeTarget | null): boolean;
|
|
1523
|
+
/**
|
|
1524
|
+
* This side's participation key and the pinned contact's, on a paired session that is open and ready: what the asker's
|
|
1525
|
+
* proof of a contact request is made for (WISP 8xx § Accept). Undefined otherwise.
|
|
1526
|
+
*/
|
|
1527
|
+
get participationKeys(): {
|
|
1528
|
+
mine: string;
|
|
1529
|
+
peer: string;
|
|
1530
|
+
} | undefined;
|
|
1531
|
+
/**
|
|
1532
|
+
* Says on the live session that this side asked through the contact's link (WISP 8xx § Accept). No capability: an app
|
|
1533
|
+
* that does not know the frame drops it. False when it could not go now: the caller says it again on the next session.
|
|
1534
|
+
*/
|
|
1535
|
+
sendContactAsker(frame: ContactAskerFrame): boolean;
|
|
1498
1536
|
/** Both sides offer `pin/1` on the open session: a pin can be said and confirmed. */
|
|
1499
1537
|
get supportsPins(): boolean;
|
|
1500
1538
|
/**
|
|
@@ -1583,7 +1621,7 @@ export declare class GhostLink {
|
|
|
1583
1621
|
sendAppRange(task: AppRangeTask, bytes: Uint8Array, size: number): Promise<void>;
|
|
1584
1622
|
/** `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
1623
|
failAppRange(task: AppRangeTask, error: "changed" | "gone"): void;
|
|
1586
|
-
/** Whether `task` still
|
|
1624
|
+
/** Whether `task` still holds a place until it is answered (`AppRanges.holds`): one that does not needs no answer. */
|
|
1587
1625
|
holdsAppRange(task: AppRangeTask): boolean;
|
|
1588
1626
|
/** An `ar-*` frame from the contact, on a session that agreed `app-ranges/1`. */
|
|
1589
1627
|
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;
|
|
@@ -322,10 +329,15 @@ export interface CommunityState {
|
|
|
322
329
|
/** My next sequence number under the commit `seqH` (full hash). */
|
|
323
330
|
seq: number;
|
|
324
331
|
seqH: string;
|
|
325
|
-
/**
|
|
332
|
+
/**
|
|
333
|
+
* Sender → `e:h16` → highest seen and the window below it. `gap`: the lowest number missing below it, how many syncs
|
|
334
|
+
* asked for it and when the last did (`haveOf`); `floor`: what is missing at or below it is given up.
|
|
335
|
+
*/
|
|
326
336
|
seen: Record<string, Record<string, {
|
|
327
337
|
high: number;
|
|
328
338
|
window: number[];
|
|
339
|
+
gap?: [number, number, number];
|
|
340
|
+
floor?: number;
|
|
329
341
|
}>>;
|
|
330
342
|
nicks: Record<string, string>;
|
|
331
343
|
/** Recent frames from everyone (mine included), oldest first. */
|
|
@@ -346,6 +358,12 @@ export interface CommunityState {
|
|
|
346
358
|
* Absent in older states.
|
|
347
359
|
*/
|
|
348
360
|
alone?: string[];
|
|
361
|
+
/**
|
|
362
|
+
* My texts saved here (counter, frame in `store`) whose message row may not be stored or whose frame may not have gone
|
|
363
|
+
* yet, as `e:h16:n`, oldest first: an app killed in between stores and says them when it opens again (`resume`), so the
|
|
364
|
+
* number is never given to another text. Absent in older states.
|
|
365
|
+
*/
|
|
366
|
+
unsaid?: string[];
|
|
349
367
|
/** Leave requests waiting for a member to commit them. */
|
|
350
368
|
pendingLeaves: {
|
|
351
369
|
s: string;
|
|
@@ -362,7 +380,14 @@ export interface CommunityState {
|
|
|
362
380
|
/** A few statements I held before `meta`, oldest first, for a member back from away (`keepPastGroupMeta`). Absent in older states. */
|
|
363
381
|
metaPast?: GroupMeta[];
|
|
364
382
|
}
|
|
365
|
-
/**
|
|
383
|
+
/**
|
|
384
|
+
* `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
|
|
385
|
+
* app may keep it with the message it stores.
|
|
386
|
+
* `live`: it came as it was written (revision 2026-11-03): straight from its author over the author's own edge, not in
|
|
387
|
+
* 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
|
|
388
|
+
* at the other end of the edge, whose live mark names itself (`lv`), the time it says at most `liveMarkMs` before my
|
|
389
|
+
* clock. How long it took then says how far the author's clock is from mine.
|
|
390
|
+
*/
|
|
366
391
|
export interface CommunityIncomingMessage {
|
|
367
392
|
id: string;
|
|
368
393
|
sender: string;
|
|
@@ -376,6 +401,7 @@ export interface CommunityIncomingMessage {
|
|
|
376
401
|
card?: StatusCard;
|
|
377
402
|
file?: GroupFileMeta;
|
|
378
403
|
frame?: CommunityMessageFrame;
|
|
404
|
+
live?: true;
|
|
379
405
|
}
|
|
380
406
|
/**
|
|
381
407
|
* What an application sends through the group rather than as text: `frame` for everyone in the epoch (the group
|
|
@@ -415,6 +441,11 @@ export interface CommunitySessionHooks {
|
|
|
415
441
|
* Undefined for anything else. Asked once the frame is read, before the `app` hook.
|
|
416
442
|
*/
|
|
417
443
|
lasting?(message: CommunityIncomingApp): string | undefined;
|
|
444
|
+
/**
|
|
445
|
+
* Whether an application frame (mine or a member's) is only a hint (a `group-have`, WISP 503): relayed live like any
|
|
446
|
+
* frame, but never kept, so it takes no place among those a member back from away gets.
|
|
447
|
+
*/
|
|
448
|
+
fleeting?(frame: Record<string, unknown>): boolean;
|
|
418
449
|
/** An application frame for the group (see `sendApp`). */
|
|
419
450
|
app?(message: CommunityIncomingApp): Promise<void> | void;
|
|
420
451
|
/** A payload another member sealed to me (see `sendPair`). Payloads to others are carried, never opened. */
|
|
@@ -495,6 +526,10 @@ export declare class CommunitySession {
|
|
|
495
526
|
private waiting;
|
|
496
527
|
private waitingBytes;
|
|
497
528
|
private asked;
|
|
529
|
+
/** Per member: until when what comes over its edge may be its answer to my sync (`ANSWER_WINDOW_MS`). In memory only. */
|
|
530
|
+
private readonly answering;
|
|
531
|
+
/** The message frames given to `handle` that came live here (`CommunityIncomingMessage.live`): `passOn` marks them. */
|
|
532
|
+
private readonly cameLive;
|
|
498
533
|
/** Syncs answered per member, a few a minute (`COMMUNITY_LIMITS.syncAnswers`). In memory only. */
|
|
499
534
|
private syncsAnswered;
|
|
500
535
|
/** Messages taken per author, a few a second (`MessagePace`). In memory only. */
|
|
@@ -513,6 +548,8 @@ export declare class CommunitySession {
|
|
|
513
548
|
private pendingMeta;
|
|
514
549
|
/** The store's frames the app holds with their messages (`storeKey` → message id): in memory here, not in what is saved. */
|
|
515
550
|
private readonly onRows;
|
|
551
|
+
/** The oldest epoch whose seen marks are kept, as of the last `pruneSeen`. In memory only. */
|
|
552
|
+
private seenFrom;
|
|
516
553
|
/** `rows`: the frames the app holds with the messages it stored (`CommunityIncomingMessage.frame`). They join the store. */
|
|
517
554
|
constructor(state: CommunityState, hooks: CommunitySessionHooks, rows?: readonly {
|
|
518
555
|
id: string;
|
|
@@ -655,15 +692,27 @@ export declare class CommunitySession {
|
|
|
655
692
|
private branch;
|
|
656
693
|
/** How many admin changes the main branch holds up to each index. */
|
|
657
694
|
private adminCounts;
|
|
658
|
-
/** What each of two branches holds after their common parent: whether it has an admin change,
|
|
695
|
+
/** What each of two branches holds after their common parent: whether it has an admin change, its first commit, and its hand-overs. */
|
|
659
696
|
private parting;
|
|
660
697
|
/**
|
|
661
|
-
*
|
|
662
|
-
*
|
|
663
|
-
*
|
|
664
|
-
*
|
|
698
|
+
* Whether a hand-over (`h`, a `role`) went to a member whose leave of that admission I know on a branch that does not
|
|
699
|
+
* hold the hand-over: signed on a view from before the leave, it would leave the role with someone gone for good (a
|
|
700
|
+
* leave never names the admin). Not when that member signed a commit after the hand-over: it took the role while still
|
|
701
|
+
* in, so its leave came later, and a branch from before the hand-over must not undo what it and later admins did.
|
|
702
|
+
*/
|
|
703
|
+
private handedToLeaver;
|
|
704
|
+
/** Whether `key` signed a commit I know that comes after `h` (on the main branch past it, or on a side branch through it). */
|
|
705
|
+
private signedAfter;
|
|
706
|
+
/**
|
|
707
|
+
* Is branch `a` better than branch `b`? After their common parent: first, the one that does not hand the
|
|
708
|
+
* role to a member who left (`handedToLeaver`); then the one that keeps an admin change, however short
|
|
709
|
+
* and however far back it parts; then one I can read over one whose tip lists me and whose secret I lack;
|
|
710
|
+
* 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
|
|
711
|
+
* halts the group, see `receiveCommit`).
|
|
665
712
|
*/
|
|
666
713
|
private better;
|
|
714
|
+
/** A commit whose roster lists me and whose secret I do not hold (yet). */
|
|
715
|
+
private awaitsSecret;
|
|
667
716
|
/**
|
|
668
717
|
* Takes in a commit (from a frame or from me): placed in the tree if it verifies against its
|
|
669
718
|
* parent, a fork if the admin signed another commit after the same parent, and then the best
|
|
@@ -693,6 +742,13 @@ export declare class CommunitySession {
|
|
|
693
742
|
private followEntry;
|
|
694
743
|
/** Side commits stay up to a bound, the most recent ones (a longer branch being assembled included). */
|
|
695
744
|
private pruneSide;
|
|
745
|
+
/**
|
|
746
|
+
* Seen marks of epochs older than the window go, every sender's, once the branch I follow moves past them: as
|
|
747
|
+
* `markSeen` drops the sender's it marks. Before, only that sender's went, so a member who left or went quiet kept
|
|
748
|
+
* an entry for every epoch it wrote in, and its window of numbers, for the life of the group (agents#2904). Those
|
|
749
|
+
* within the window stay, a leaver's too: what it wrote before its leave is still taken up to its mark there.
|
|
750
|
+
*/
|
|
751
|
+
private pruneSeen;
|
|
696
752
|
private pruneSecrets;
|
|
697
753
|
/** A derived epoch's secret, from its parent's, when that is held. */
|
|
698
754
|
private takeDerived;
|
|
@@ -725,7 +781,20 @@ export declare class CommunitySession {
|
|
|
725
781
|
rewelcome(memberKey: string): Promise<(CommunityChainFrame | CommunityWelcomeFrame)[]>;
|
|
726
782
|
/** The chain, the secrets from the admitting commit on, the rendezvous secret and the entry seed, for one newcomer. */
|
|
727
783
|
private welcomeFor;
|
|
784
|
+
/**
|
|
785
|
+
* Takes a member out, and with it everyone it let in who is still in, and whom those let in in turn
|
|
786
|
+
* (`admittedThrough`): keys a member let in cost it nothing, and one by one they were the admin's to clear. A
|
|
787
|
+
* `remove` commit each, as before (an app from before follows them), one at a time, so what arrives meanwhile is
|
|
788
|
+
* heard, and an admission signed meanwhile by one of them is taken out too (`memberAdmissions` bounds them, as a
|
|
789
|
+
* removal is not the admin letting anyone in). A member already out still has those it let in cleared.
|
|
790
|
+
*/
|
|
728
791
|
remove(memberKey: string, now?: number): Promise<void>;
|
|
792
|
+
/**
|
|
793
|
+
* The members still in whose admission, on the main branch, `root` signed, or one of them did, and so on: in the
|
|
794
|
+
* order they were let in. An admission signed by whoever was the admin then is the admin's, not counted: removing
|
|
795
|
+
* a former admin does not take out everyone it let in. Never the admin nor me.
|
|
796
|
+
*/
|
|
797
|
+
private admittedThrough;
|
|
729
798
|
transferAdmin(memberKey: string, now?: number): Promise<void>;
|
|
730
799
|
rotate(now?: number): Promise<void>;
|
|
731
800
|
/** A new entry key (the old link reaches nobody), or none (`off`): a `link` commit every member follows. */
|
|
@@ -737,7 +806,11 @@ export declare class CommunitySession {
|
|
|
737
806
|
leave(): Promise<CommunityLeaveFrame | null>;
|
|
738
807
|
/** Commits the leave requests I hold whose members are still in: the engine calls this on hubs. */
|
|
739
808
|
commitPendingLeaves(now?: number): Promise<number>;
|
|
740
|
-
/**
|
|
809
|
+
/**
|
|
810
|
+
* Signs and says how far I had heard a member whose leave I just committed (`group-left`): per epoch, up to the first
|
|
811
|
+
* 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
|
|
812
|
+
* at the window's bottom (a jump past it, or a counter raised by a restore) leaves the epoch out: nothing of it then.
|
|
813
|
+
*/
|
|
741
814
|
private markLeft;
|
|
742
815
|
private out;
|
|
743
816
|
/**
|
|
@@ -756,7 +829,7 @@ export declare class CommunitySession {
|
|
|
756
829
|
/**
|
|
757
830
|
* An application frame to everyone in the group (a note about a payment, a request anyone may pay): sealed to
|
|
758
831
|
* the epoch like text, signed, kept and caught up like text, and handed to the other members' `app` hook
|
|
759
|
-
* instead of their history.
|
|
832
|
+
* instead of their history. A fleeting one (`CommunitySessionHooks.fleeting`) is only said to those up now.
|
|
760
833
|
*/
|
|
761
834
|
sendApp(frame: Record<string, unknown>, nick?: string, now?: number): Promise<{
|
|
762
835
|
id: string;
|
|
@@ -802,9 +875,21 @@ export declare class CommunitySession {
|
|
|
802
875
|
/**
|
|
803
876
|
* Saves, then says my frame on every edge. One no edge took (none is up: I just joined, or my app just opened) is
|
|
804
877
|
* remembered until a member it was written for is handed it: I may be behind on the chain without knowing, and the
|
|
805
|
-
* first member I reach may be one let in since, who cannot read it but can carry it (`receiveSync`).
|
|
878
|
+
* first member I reach may be one let in since, who cannot read it but can carry it (`receiveSync`). `saved`: the
|
|
879
|
+
* caller marked it unheard and saved it (`sendText`).
|
|
806
880
|
*/
|
|
807
881
|
private say;
|
|
882
|
+
/** My frame in `unheard`, before it is said: the frames of mine the store no longer holds leave it. */
|
|
883
|
+
private markUnheard;
|
|
884
|
+
/**
|
|
885
|
+
* Stores and says what an app killed mid-send left `unsaid`: its counter and frame were saved, its row or its sending
|
|
886
|
+
* may not have happened. A row stored already is not stored twice (the app's store takes one row per id), a frame
|
|
887
|
+
* that went already is taken by the members as one they hold. The engine calls this on each tick; a send does first.
|
|
888
|
+
*/
|
|
889
|
+
resume(): Promise<void>;
|
|
890
|
+
private sayUnsaid;
|
|
891
|
+
/** The row of one of my own texts, as `sendText` stored it, opened from its frame; none for anything else, or one deleted for everyone. */
|
|
892
|
+
private ownRow;
|
|
808
893
|
/**
|
|
809
894
|
* Message `id` was deleted for everyone (WISP 400 § Delete for everyone), by its author or here: its frame goes from
|
|
810
895
|
* the store, so no catch-up hands it to a member who was away (they get the removal, which stays). A frame said again
|
|
@@ -854,7 +939,16 @@ export declare class CommunitySession {
|
|
|
854
939
|
* was new and valid, so a hub knows to relay it on.
|
|
855
940
|
*/
|
|
856
941
|
handle(from: string, raw: unknown): Promise<boolean>;
|
|
942
|
+
/** After a secret came that confirms: a branch that waited for it may be the one to follow now (see `better`). */
|
|
943
|
+
private tookSecrets;
|
|
857
944
|
private receiveLeave;
|
|
945
|
+
/**
|
|
946
|
+
* What a hub hands on of a frame it took (`handle` said it was new): as it came, without the live mark of whoever
|
|
947
|
+
* handed it to me, and with mine when it came live here (WISP 903 § Relaying, revision 2026-11-03). Hand it on at
|
|
948
|
+
* once: the mark says it is passed on as it came.
|
|
949
|
+
*/
|
|
950
|
+
passOn(frame: object): object;
|
|
951
|
+
/** `waited`: it waited for a commit or a secret (`replayWaiting`), so it is not live. */
|
|
858
952
|
private receiveMessage;
|
|
859
953
|
/**
|
|
860
954
|
* A frame signed with my own key that I did not send here: another copy of this profile sent it (a restored backup, a
|
|
@@ -863,6 +957,14 @@ export declare class CommunitySession {
|
|
|
863
957
|
*/
|
|
864
958
|
private ownFrame;
|
|
865
959
|
private isDuplicate;
|
|
960
|
+
/**
|
|
961
|
+
* What a sync says I have of a sender under a commit: below the lowest number missing, not the highest seen. A live
|
|
962
|
+
* frame raises the highest above that sender's frames still coming in a catch-up answer, and when the rest of the
|
|
963
|
+
* answer never came (my app closed or my edge dropped, or the hub's app closed), every later sync said I had them:
|
|
964
|
+
* they were lost for good (2026-10-18). A gap asked for by `GAP_ASKS` syncs at least `GAP_ASK_MS` apart that none
|
|
965
|
+
* filled (the stores rolled past it, a leaver's frames) is given up: each answer hands what is stored above it again.
|
|
966
|
+
*/
|
|
967
|
+
private haveOf;
|
|
866
968
|
private markSeen;
|
|
867
969
|
private park;
|
|
868
970
|
/** Something is missing here: the current epoch's secret, or the epoch of frames waiting. */
|
|
@@ -887,7 +989,11 @@ export declare class CommunitySession {
|
|
|
887
989
|
setPicture(picture: string | null, now?: number): Promise<void>;
|
|
888
990
|
/** Renames the group: only the admin, signed under the current commit, beside the picture. */
|
|
889
991
|
rename(name: string, now?: number): Promise<void>;
|
|
890
|
-
/**
|
|
992
|
+
/**
|
|
993
|
+
* Signs a body under my current commit, keeps it and sends it to everyone (hubs relay it). Inside `serialize`. Like a
|
|
994
|
+
* commit, only with admin work on and a good turn read (WISP 06 § Forced takeover): refused otherwise, or, `quiet`,
|
|
995
|
+
* not made. Its revision is never under the floor (WISP 06 § Raised counters).
|
|
996
|
+
*/
|
|
891
997
|
private publishMeta;
|
|
892
998
|
/** A statement sealed under my current epoch, when I hold its secret. */
|
|
893
999
|
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
|