@ghostlytools/sdk 0.0.0-stage → 1.2.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (145) hide show
  1. package/README.md +13 -2
  2. package/dist/app.js +72 -0
  3. package/dist/app.js.map +1 -0
  4. package/dist/core.js +207 -0
  5. package/dist/core.js.map +1 -0
  6. package/dist/fakes-JOzOFxn3.js +536 -0
  7. package/dist/fakes-JOzOFxn3.js.map +1 -0
  8. package/dist/fakes.js +2 -0
  9. package/dist/index.js +179 -0
  10. package/dist/index.js.map +1 -0
  11. package/dist/keet-identity-key-BLli1rE4.js +76483 -0
  12. package/dist/keet-identity-key-BLli1rE4.js.map +1 -0
  13. package/dist/src-BqHTnRWH.js +31296 -0
  14. package/dist/src-BqHTnRWH.js.map +1 -0
  15. package/dist/testing.js +330 -0
  16. package/dist/testing.js.map +1 -0
  17. package/dist/types/browser/src/engine/paymentAdapters/providers/contractSuite.d.ts +41 -0
  18. package/dist/types/browser/src/engine/paymentAdapters/providers/lightning.d.ts +103 -0
  19. package/dist/types/browser/src/engine/paymentAdapters/providers/onchain.d.ts +88 -0
  20. package/dist/types/browser/src/engine/paymentAdapters/providers/testing.d.ts +89 -0
  21. package/dist/types/browser/src/engine/paymentAdapters/providers/types.d.ts +151 -0
  22. package/dist/types/browser/src/plugins/bundled.d.ts +8 -0
  23. package/dist/types/browser/src/plugins/registry.d.ts +57 -0
  24. package/dist/types/browser/src/proofs/contract.d.ts +262 -0
  25. package/dist/types/browser/src/proofs/contractSuite.d.ts +27 -0
  26. package/dist/types/browser/src/proofs/testing.d.ts +36 -0
  27. package/dist/types/browser/src/proofs/verify.d.ts +23 -0
  28. package/dist/types/browser/src/shared/mints.d.ts +50 -0
  29. package/dist/types/core/src/appBundle.d.ts +173 -0
  30. package/dist/types/core/src/appStatements.d.ts +142 -0
  31. package/dist/types/core/src/appStore.d.ts +133 -0
  32. package/dist/types/core/src/appUpdates.d.ts +88 -0
  33. package/dist/types/core/src/atprotoIdentity.d.ts +49 -0
  34. package/dist/types/core/src/atprotoRepo.d.ts +101 -0
  35. package/dist/types/core/src/avatar.d.ts +19 -0
  36. package/dist/types/core/src/bip322.d.ts +57 -0
  37. package/dist/types/core/src/bitcoinAddress.d.ts +5 -0
  38. package/dist/types/core/src/bitcoinMessage.d.ts +15 -0
  39. package/dist/types/core/src/bitcoinScript.d.ts +69 -0
  40. package/dist/types/core/src/bolt11.d.ts +30 -0
  41. package/dist/types/core/src/bytes.d.ts +11 -0
  42. package/dist/types/core/src/callSignal.d.ts +232 -0
  43. package/dist/types/core/src/canonicalJson.d.ts +22 -0
  44. package/dist/types/core/src/capsRecord.d.ts +234 -0
  45. package/dist/types/core/src/catchUp.d.ts +45 -0
  46. package/dist/types/core/src/chatFiles.d.ts +271 -0
  47. package/dist/types/core/src/clockWatch.d.ts +72 -0
  48. package/dist/types/core/src/communityRendezvous.d.ts +113 -0
  49. package/dist/types/core/src/crypto.d.ts +10 -0
  50. package/dist/types/core/src/datalink.d.ts +187 -0
  51. package/dist/types/core/src/deviceInvite.d.ts +51 -0
  52. package/dist/types/core/src/deviceLink.d.ts +70 -0
  53. package/dist/types/core/src/dhtDelivery.d.ts +407 -0
  54. package/dist/types/core/src/dhtFiles.d.ts +46 -0
  55. package/dist/types/core/src/did.d.ts +134 -0
  56. package/dist/types/core/src/didDht.d.ts +155 -0
  57. package/dist/types/core/src/directPath.d.ts +63 -0
  58. package/dist/types/core/src/dns.d.ts +41 -0
  59. package/dist/types/core/src/domainProofs.d.ts +88 -0
  60. package/dist/types/core/src/engineErrors.d.ts +91 -0
  61. package/dist/types/core/src/enroll.d.ts +98 -0
  62. package/dist/types/core/src/files.d.ts +73 -0
  63. package/dist/types/core/src/forwards.d.ts +12 -0
  64. package/dist/types/core/src/frames.d.ts +211 -0
  65. package/dist/types/core/src/ghostlink.d.ts +1532 -0
  66. package/dist/types/core/src/groupCommits.d.ts +103 -0
  67. package/dist/types/core/src/groupCommunity.d.ts +720 -0
  68. package/dist/types/core/src/groupCrypto.d.ts +60 -0
  69. package/dist/types/core/src/groupEdits.d.ts +67 -0
  70. package/dist/types/core/src/groupEntry.d.ts +61 -0
  71. package/dist/types/core/src/groupFiles.d.ts +106 -0
  72. package/dist/types/core/src/groupHubs.d.ts +61 -0
  73. package/dist/types/core/src/groupMentions.d.ts +27 -0
  74. package/dist/types/core/src/groupMeta.d.ts +162 -0
  75. package/dist/types/core/src/groupSession.d.ts +728 -0
  76. package/dist/types/core/src/groupSignals.d.ts +167 -0
  77. package/dist/types/core/src/groupTyping.d.ts +56 -0
  78. package/dist/types/core/src/groupWake.d.ts +68 -0
  79. package/dist/types/core/src/handoff.d.ts +255 -0
  80. package/dist/types/core/src/http.d.ts +125 -0
  81. package/dist/types/core/src/identity.d.ts +17 -0
  82. package/dist/types/core/src/identityProofs.d.ts +243 -0
  83. package/dist/types/core/src/identityTimeline.d.ts +72 -0
  84. package/dist/types/core/src/image.d.ts +33 -0
  85. package/dist/types/core/src/index.d.ts +100 -0
  86. package/dist/types/core/src/invite.d.ts +128 -0
  87. package/dist/types/core/src/link.d.ts +353 -0
  88. package/dist/types/core/src/linkPreview.d.ts +60 -0
  89. package/dist/types/core/src/linkTrace.d.ts +12 -0
  90. package/dist/types/core/src/lnurl.d.ts +99 -0
  91. package/dist/types/core/src/messageTime.d.ts +28 -0
  92. package/dist/types/core/src/miniApp.d.ts +146 -0
  93. package/dist/types/core/src/pairedApps.d.ts +151 -0
  94. package/dist/types/core/src/pairedCalls.d.ts +59 -0
  95. package/dist/types/core/src/pairedCapabilities.d.ts +101 -0
  96. package/dist/types/core/src/pairedEdits.d.ts +83 -0
  97. package/dist/types/core/src/pairedFiles.d.ts +30 -0
  98. package/dist/types/core/src/pairedHttp.d.ts +15 -0
  99. package/dist/types/core/src/pairedSession.d.ts +163 -0
  100. package/dist/types/core/src/pairedSignal.d.ts +17 -0
  101. package/dist/types/core/src/pairedTransports.d.ts +76 -0
  102. package/dist/types/core/src/pairedTyping.d.ts +130 -0
  103. package/dist/types/core/src/pairedWake.d.ts +109 -0
  104. package/dist/types/core/src/pairingProgress.d.ts +107 -0
  105. package/dist/types/core/src/paymentIntent.d.ts +111 -0
  106. package/dist/types/core/src/paymentUri.d.ts +34 -0
  107. package/dist/types/core/src/payments.d.ts +97 -0
  108. package/dist/types/core/src/peerProofs.d.ts +98 -0
  109. package/dist/types/core/src/pins.d.ts +73 -0
  110. package/dist/types/core/src/pkarr.d.ts +48 -0
  111. package/dist/types/core/src/pkdns.d.ts +35 -0
  112. package/dist/types/core/src/pubkyProofs.d.ts +25 -0
  113. package/dist/types/core/src/pubkyRing.d.ts +21 -0
  114. package/dist/types/core/src/reactions.d.ts +108 -0
  115. package/dist/types/core/src/records.d.ts +89 -0
  116. package/dist/types/core/src/relay.d.ts +459 -0
  117. package/dist/types/core/src/relayBreaker.d.ts +99 -0
  118. package/dist/types/core/src/replies.d.ts +41 -0
  119. package/dist/types/core/src/services.d.ts +35 -0
  120. package/dist/types/core/src/setUpdate.d.ts +53 -0
  121. package/dist/types/core/src/signal.d.ts +53 -0
  122. package/dist/types/core/src/signer.d.ts +13 -0
  123. package/dist/types/core/src/sparkAddress.d.ts +37 -0
  124. package/dist/types/core/src/sshsig.d.ts +74 -0
  125. package/dist/types/core/src/statusCards.d.ts +253 -0
  126. package/dist/types/core/src/storeForward.d.ts +144 -0
  127. package/dist/types/core/src/text.d.ts +20 -0
  128. package/dist/types/core/src/transport.d.ts +158 -0
  129. package/dist/types/core/src/transportSwitch.d.ts +160 -0
  130. package/dist/types/core/src/turnRead.d.ts +145 -0
  131. package/dist/types/core/src/turnRecord.d.ts +165 -0
  132. package/dist/types/core/src/version.d.ts +9 -0
  133. package/dist/types/core/src/video.d.ts +44 -0
  134. package/dist/types/core/src/voice.d.ts +88 -0
  135. package/dist/types/core/src/webPush.d.ts +58 -0
  136. package/dist/types/sdk/src/app.d.ts +23 -0
  137. package/dist/types/sdk/src/core.d.ts +7 -0
  138. package/dist/types/sdk/src/fakes.d.ts +6 -0
  139. package/dist/types/sdk/src/index.d.ts +26 -0
  140. package/dist/types/sdk/src/testing.d.ts +7 -0
  141. package/dist/types-DvtCy3WB.js +99 -0
  142. package/dist/types-DvtCy3WB.js.map +1 -0
  143. package/dist/verify-RjMx7eW6.js +106 -0
  144. package/dist/verify-RjMx7eW6.js.map +1 -0
  145. package/package.json +70 -4
@@ -0,0 +1,113 @@
1
+ import { type Identity } from "./identity.js";
2
+ import type { GhostRecord } from "./pkarr.js";
3
+ /**
4
+ * Where the members of a `group-community/1` group find each other (WISP 903 · Group Community §
5
+ * Topology): a **beacon** listing the current hubs, and a **lobby** per hub where a member asks
6
+ * that hub for an edge. Both are Pkarr records under identities every member derives from the
7
+ * group's rendezvous secret, sealed with a key from the same secret: relays see a key and an
8
+ * opaque value. Several members write the same record, so a writer reads, merges and publishes.
9
+ */
10
+ export declare const COMMUNITY_TOPOLOGY: {
11
+ /** Hubs listed in the beacon, at most. */
12
+ readonly maxHubs: 8;
13
+ /** Hubs wanted before a member settles for being a member. */
14
+ readonly minHubs: 2;
15
+ /** Members one hub keeps edges with. */
16
+ readonly hubCapacity: 48;
17
+ /** Hubs a member connects to: one; if it goes, the member asks another and a sync fills the gap. */
18
+ readonly hubsPerMember: 1;
19
+ /** A hub republishes its beacon entry this often… */
20
+ readonly beaconEveryMs: 30000;
21
+ /** …and an entry older than this is stale. */
22
+ readonly beaconFreshMs: 90000;
23
+ /** Lobby entries: at most this many, fresh this long. */
24
+ readonly lobbyEntries: 6;
25
+ readonly lobbyFreshMs: number;
26
+ };
27
+ /** A hub as the beacon lists it: when it last said so (`ts`), since when it is a hub, and how many members it holds. */
28
+ export interface Hub {
29
+ key: string;
30
+ ts: number;
31
+ load: number;
32
+ since?: number;
33
+ }
34
+ export interface LobbyEntry {
35
+ key: string;
36
+ ts: number;
37
+ }
38
+ /** The beacon's Pkarr identity and sealing key, for a group. */
39
+ export declare function beaconKeys(rvB64: string, groupId: string): {
40
+ identity: Identity;
41
+ key: Uint8Array;
42
+ aad: Uint8Array;
43
+ };
44
+ /** A hub's lobby: its Pkarr identity and sealing key. */
45
+ export declare function lobbyKeys(rvB64: string, groupId: string, hubKey: string): {
46
+ identity: Identity;
47
+ key: Uint8Array;
48
+ aad: Uint8Array;
49
+ };
50
+ /**
51
+ * The hubs that take turns at the door (WISP 903 § Admission): those that said so lately and have
52
+ * been hubs for a minute, so that every hub, having read the beacon at least once since, agrees on
53
+ * the same set. Only when there is none (a group's first minute), the one that has been a hub longest. And when none said so lately, a hub asking (`me`)
54
+ * that sees no other fresh hub in the beacon is the door alone, listed or not: its own entry may not have reached the
55
+ * relays yet (a new group's first hub, whose write the relays' budget holds back), and there is nobody to agree with.
56
+ */
57
+ export declare function doorHubs(hubs: Hub[], now?: number, me?: string): string[];
58
+ /**
59
+ * The newest message frame a hub holds (WISP 903 · Group Community § Head): who sent it, in which epoch (number and
60
+ * first 16 hex of its commit hash), its sequence and time. Hubs publish it beside the hub list, so a member's other
61
+ * profile on the same device can tell something new was said without being online (WISP 04 § Checking other profiles).
62
+ */
63
+ export interface CommunityHead {
64
+ s: string;
65
+ e: number;
66
+ h: string;
67
+ n: number;
68
+ ts: number;
69
+ }
70
+ /** A frame can be a head: a member key, and numbers that fit. */
71
+ export declare function validHead(head: CommunityHead | null | undefined): head is CommunityHead;
72
+ /** The newer of two heads, by time; a head from more than a minute ahead of now is not taken. */
73
+ export declare function newerHead(a: CommunityHead | null, b: CommunityHead | null, now?: number): CommunityHead | null;
74
+ export declare function beaconRecords(keys: {
75
+ key: Uint8Array;
76
+ aad: Uint8Array;
77
+ }, hubs: Hub[], head?: CommunityHead | null): GhostRecord[];
78
+ /** The head a beacon packet carries, if a hub of this revision wrote it last (an older hub's publication drops it). */
79
+ export declare function readBeaconHead(keys: {
80
+ key: Uint8Array;
81
+ aad: Uint8Array;
82
+ }, records: GhostRecord[]): CommunityHead | null;
83
+ export declare function readBeacon(keys: {
84
+ key: Uint8Array;
85
+ aad: Uint8Array;
86
+ }, records: GhostRecord[]): Hub[];
87
+ export declare function lobbyRecords(keys: {
88
+ key: Uint8Array;
89
+ aad: Uint8Array;
90
+ }, entries: LobbyEntry[]): GhostRecord[];
91
+ export declare function readLobby(keys: {
92
+ key: Uint8Array;
93
+ aad: Uint8Array;
94
+ }, records: GhostRecord[]): LobbyEntry[];
95
+ /**
96
+ * The beacon to publish: my entry (or none, `mine` null, when I step down) with the other fresh
97
+ * hubs, newest first, at most `maxHubs`. A hub not in the roster any more is dropped.
98
+ */
99
+ export declare function mergeBeacon(existing: Hub[], me: string, mine: Hub | null, now?: number, isMember?: (key: string) => boolean): Hub[];
100
+ /** The lobby to publish: my request refreshed, others' still fresh, newest last. */
101
+ export declare function mergeLobby(existing: LobbyEntry[], mine: LobbyEntry, now?: number): LobbyEntry[];
102
+ /** Fresh hubs of a beacon, as a member sees them. */
103
+ export declare function freshHubs(hubs: Hub[], now?: number): Hub[];
104
+ /** Rendezvous hashing: how strongly a hub is responsible for someone (a knock, a member). Highest first. */
105
+ export declare function hubRank(subject: string, hubKey: string): string;
106
+ export declare function rankHubs(subject: string, hubs: string[]): string[];
107
+ /**
108
+ * The hubs a member asks for edges: the least loaded fresh ones with room, ties broken by rank
109
+ * for this member (so members spread out), at most `hubsPerMember`.
110
+ */
111
+ export declare function pickHubs(me: string, hubs: Hub[], now?: number, avoid?: ReadonlySet<string>): string[];
112
+ /** Should this member be a hub? Too few fresh hubs, or all full, and room in the beacon. */
113
+ export declare function shouldBeHub(me: string, hubs: Hub[], now?: number): boolean;
@@ -0,0 +1,10 @@
1
+ export declare function generateEncryptionKey(): Uint8Array;
2
+ /**
3
+ * NaCl secretbox (XSalsa20-Poly1305). Wire format matches the Rust
4
+ * implementation in `apps/desktop/src/crypto.rs`: base64(nonce || box).
5
+ */
6
+ export declare function encrypt(plaintext: string, key: Uint8Array): string;
7
+ /** The length of what `encrypt` returns for a plaintext of this many UTF-8 bytes: base64 of nonce, box and 16-byte tag. */
8
+ export declare function sealedLength(plaintextBytes: number): number;
9
+ export declare function decrypt(encoded: string, key: Uint8Array): string;
10
+ export declare function tryDecrypt(encoded: string, key: Uint8Array): string | null;
@@ -0,0 +1,187 @@
1
+ import { type DirectEvidence } from "./directPath.js";
2
+ import { type FrameChannel } from "./frames.js";
3
+ import { type SignalSight } from "./signal.js";
4
+ /**
5
+ * The WebRTC data link of one link: a single RTCPeerConnection carrying the
6
+ * negotiated `ghostly/1` DataChannel. Offer and answer travel through the
7
+ * `_rtc` record; once the channel is open Pkarr is out of the picture and all
8
+ * application traffic flows peer to peer (or through TURN, if ICE needs it).
9
+ */
10
+ export type DataLinkState = "idle" | "offering" | "answering" | "connecting" | "open";
11
+ export interface DataLinkOptions {
12
+ myPubKeyZ32: string;
13
+ peerPubKeyZ32: string;
14
+ createPeerConnection: () => RTCPeerConnection;
15
+ /** Publishes (or clears, with null) my `_rtc` record. */
16
+ publishSignal: (signal: string | null) => void;
17
+ /** Signaling in progress (or over): look fast for the peer's signal. `offer`: for the answer to this side's offer. */
18
+ setFastPoll: (fast: boolean, offer?: boolean) => void;
19
+ onOpen: (channel: FrameChannel) => void;
20
+ onClose: () => void;
21
+ onState?: (state: DataLinkState) => void;
22
+ /**
23
+ * How long an attempt (offer or answer out, channel not yet open) may take before it is given up, so the
24
+ * next one can start, asked as each one starts. Default `CONNECT_TIMEOUT_MS`; a first pairing, whose contact
25
+ * is right there reading its invite, uses a short one until it is over.
26
+ */
27
+ attemptTimeoutMs?: () => number | undefined;
28
+ /**
29
+ * The open connection went `disconnected` (true: ICE consent checks unanswered, the contact may be gone or its app
30
+ * restarted; the connection is given `DISCONNECT_GRACE_MS`), or came back from it (false).
31
+ */
32
+ onDisconnected?: (disconnected: boolean) => void;
33
+ /**
34
+ * Whether the peer's packet, as last read, still carries its offer of that time (`RtcSignal.ts`). An answer to it
35
+ * that did not connect is then made again (`REANSWERS`); without this, never.
36
+ */
37
+ offerStanding?: (offerTs: number) => boolean;
38
+ /**
39
+ * This side's attempt was given up because the answerer answered its offer again (its connection for the answer
40
+ * applied here is gone), or because its answer could not be applied (`ANSWER_REFUSED_REDIALS`): the answerer is
41
+ * there, so the caller may dial again now rather than at its next look.
42
+ */
43
+ onAnswerReplaced?: () => void;
44
+ /**
45
+ * This side's answers were refused more times in a row than it offers again at once for (`ANSWER_REFUSED_REDIALS`):
46
+ * the WebRTC of this device takes none now (libdatachannel's race, on a loaded core), and the next offer would wait
47
+ * the caller's backoff, minutes after a few failures. Nothing about the network: the answerer was there each time.
48
+ */
49
+ onAnswersRefused?: () => void;
50
+ /**
51
+ * What an attempt said about direct connections from this device (`directPath.ts`): it opened (and, later, closed);
52
+ * it did not connect and this device had no public candidate for it, or a public port per STUN server; or this
53
+ * side's offer was answered and no path connected.
54
+ */
55
+ onDirect?: (evidence: DirectEvidence) => void;
56
+ }
57
+ /**
58
+ * An attempt ended from outside (another transport went live first) that had both descriptions for this long and no
59
+ * connection says what one that failed does: a path that exists connects within a second or two.
60
+ */
61
+ export declare const STALLED_EVIDENCE_MS = 5000;
62
+ export declare const CONNECT_TIMEOUT_MS = 90000;
63
+ /**
64
+ * An offer with its host candidates waits this long at most for a server reflexive one (STUN answered), not
65
+ * `ICE_GATHERING_TIMEOUT_MS`. Where the STUN servers answer, they do in some 50 ms (0.44 s an offer took here, with the
66
+ * settle); where they do not, every offer of a first pairing waited the full 5 s, twice when the inviter offered too
67
+ * (One's e2e runs: 13 offers of 89 at 5 s, 9 more at 1.3-3 s, 2026-10-05). An offer without one still connects to most
68
+ * contacts (their checks learn this side's address from its own); behind a restricted NAT on the contact's side it may
69
+ * not, and the next offer of the chat then waits as long as it takes (`fullGather`).
70
+ */
71
+ export declare const OFFER_HOST_GATHER_MS = 2000;
72
+ /** The data link keeps collecting this long after the candidate it waited for came (a call keeps 400 ms). */
73
+ export declare const DATA_SETTLE_MS = 150;
74
+ /**
75
+ * A connection with no candidate at all by then has stalled: Chromium, rarely and under load, gathers none, and an
76
+ * offer or answer without one can never connect. It is made again in its place, up to `GATHER_ATTEMPTS` in all.
77
+ */
78
+ export declare const GATHER_STALL_MS = 3000;
79
+ export declare const GATHER_ATTEMPTS = 3;
80
+ /**
81
+ * An answer whose connection failed, while the peer still offers (`offerStanding`), is made again for the same offer,
82
+ * up to this many times. The offerer's connection waits for an answer for its whole attempt (`CONNECT_TIMEOUT_MS`), and
83
+ * its read of the answer may be held back by its relays' budget; the answerer's ICE gives up after about 30 s of no
84
+ * reply. Going idle then left the link with an offer this side had answered once and would not answer again, until the
85
+ * offerer's attempt ran out: a community's edge was live again 110 s after a member restarted (2026-09-30).
86
+ */
87
+ export declare const REANSWERS = 2;
88
+ /**
89
+ * An answer to this side's offer that could not be applied, its connection failing as it was (libdatachannel 0.24.5,
90
+ * in node-datachannel 0.33.4: the answerer's DTLS handshake can end inside setRemoteDescription, before the answer's
91
+ * fingerprint is in, and the connection closes), is followed by a new offer at once, up to this many times until a
92
+ * connection opens. The answerer is there; it was the dial after it that waited: its backoff, 40 s, then its next
93
+ * look (a member let in to a group reached one of its members 72 s after its welcome on CI, 2026-10-06). Two were
94
+ * not enough: on CI the race refused an answer again right after two others, and the edge waited 160 s for its
95
+ * backoff (meshSignals, PR #1363). Offers through members cost no relay request; over the relays four is still a few.
96
+ */
97
+ export declare const ANSWER_REFUSED_REDIALS = 4;
98
+ export declare class DataLink {
99
+ private readonly options;
100
+ state: DataLinkState;
101
+ private pc;
102
+ private myOfferTs;
103
+ /**
104
+ * An offer of this side's that went without a public candidate came to nothing (it was answered, and no path
105
+ * connected): the next one waits for its STUN servers as long as it takes (`ICE_GATHERING_TIMEOUT_MS`).
106
+ */
107
+ private fullGather;
108
+ /** The offer out has no public candidate (as it went: the connection's description gains any that come later). */
109
+ private offerLacksPublic;
110
+ private lastSignalTs;
111
+ /** The peer's description as this connection was given it: Chrome shows it as `remoteDescription` only once applied. */
112
+ private remoteSdp;
113
+ /** When the connection had both descriptions (`connecting`). */
114
+ private connectingSince;
115
+ private connectTimer;
116
+ private disconnectTimer;
117
+ /** The offer this side answered in the current attempt, when it took it (this clock), and how many times it answered it again. */
118
+ private answered;
119
+ /** Answers refused since a connection last opened, each followed by a new offer at once (`ANSWER_REFUSED_REDIALS`). */
120
+ private refusedAnswers;
121
+ /** The last answer dropped as not for this side's offer (`answer-dropped`): each is said once. */
122
+ private droppedAnswerTs;
123
+ constructor(options: DataLinkOptions);
124
+ /** Offers a connection to the peer. Resolves once the offer is published. */
125
+ /**
126
+ * Makes an offer and publishes it. `gate`: gathered ahead, while the caller still finds out whether the peer is there
127
+ * (a joiner reading the inviter's record): the link stays idle meanwhile, and the offer goes once the gate says yes.
128
+ * On no, the connection is dropped, nothing having been said, and `"held"` is the answer.
129
+ */
130
+ connect(gate?: Promise<boolean>): Promise<"held" | void>;
131
+ /**
132
+ * Feeds a decrypted `_rtc` value from the peer's packet. `sight`: how this device saw it come (`SignalSight`): the
133
+ * peer's record did not carry it at a read the network answered, or it came on a live session just now.
134
+ *
135
+ * The peer's `ts` orders its signals (a later one replaces an earlier one, and an answer names the offer it is for).
136
+ * It is not what says a signal is recent when this device saw it come: two clocks a few minutes apart are common, and
137
+ * every signal of such a peer was dropped here, without a word. An answer is for the offer it names, which this side
138
+ * made in this attempt, so it has no age to check. An offer is as old as the time since the read that did not have it
139
+ * (`offerIsFresh`); only one the first read finds is judged by its own time, as nothing else dates it.
140
+ *
141
+ * A signal dated more than `RTC_SIGNAL_FUTURE_MS` ahead of this clock is not taken at all: taken, its time would
142
+ * be the latest this link knows of the peer, and every signal the peer makes after it would read as older.
143
+ */
144
+ handleSignal(json: string, sight?: SignalSight): Promise<void>;
145
+ /**
146
+ * On a quick path the channel opens before setRemoteDescription resolves (see `handleSignal`), when the connection
147
+ * does not show the answer yet: the one it was given counts, as DTLS already checked the peer against it.
148
+ */
149
+ get fingerprints(): [string, string] | null;
150
+ close(): void;
151
+ /** This side's offer went with no public candidate, was answered, and came to nothing: the next offer gathers for as long as it takes. */
152
+ private noteNoPublic;
153
+ /**
154
+ * What this attempt says about direct connections if it ends now without opening: nothing unless both descriptions
155
+ * were exchanged (this side's offer answered, or its answer out). Then, what this device gathered: no public
156
+ * candidate, a public port per STUN server, or (for the side that offered) candidates that read as reachable.
157
+ */
158
+ private directEvidence;
159
+ /**
160
+ * The attempt on this connection failed (it timed out, ICE failed or closed, its channel closed). An answer the
161
+ * offerer may not have read yet is made again for the same offer while it still stands (`REANSWERS`); anything
162
+ * else goes back to idle.
163
+ */
164
+ private failed;
165
+ /** The answer to this side's offer did not go in (`ANSWER_REFUSED_REDIALS`): the attempt ends, and the caller may offer again now. */
166
+ private answerRefused;
167
+ private answer;
168
+ /**
169
+ * Makes the connection (`describe` sets its description) and waits for its candidates. One that found none by
170
+ * `GATHER_STALL_MS` is replaced by a new one, up to `GATHER_ATTEMPTS` in all; when none finds any, the link goes back
171
+ * to idle at once rather than hold, for its whole timeout, an attempt that cannot connect. Null when the link moved
172
+ * on meanwhile (closed, or another signal took over) or gave up.
173
+ */
174
+ private gathered;
175
+ private createConnection;
176
+ /** The attempt on `pc` gives up this long from now (`CONNECT_TIMEOUT_MS`) unless it opens. */
177
+ private startAttemptTimer;
178
+ /**
179
+ * This side's offer or answer reached the relays only now (their budget, or an outage, held it back): the attempt
180
+ * counts from here, so the other side has as long to read it as if it had gone out at once.
181
+ */
182
+ signalWentOut(): void;
183
+ private clearTimers;
184
+ private teardown;
185
+ private reset;
186
+ private setState;
187
+ }
@@ -0,0 +1,51 @@
1
+ import { type LinkParams } from "./invite.js";
2
+ /** 4 fields of 32 bytes, the flags and the expiry. */
3
+ export declare const DEVICE_INVITE_BYTES = 133;
4
+ /** Bit 0 of the flags: the code adds a device to the inviter's own profile. The only kind there is. */
5
+ export declare const DEVICE_INVITE_OWN_DEVICE = 1;
6
+ /** How long a code is good for (WISP 06: the inviter enforces the 10 minutes). */
7
+ export declare const DEVICE_INVITE_LIFETIME_S = 600;
8
+ /** A device invite, as both sides hold it. Keys and seeds are the forms the link parameters use. */
9
+ export interface DeviceInvite {
10
+ /** The joiner's one-time rendezvous seed, base64url. */
11
+ joinerSeedB64: string;
12
+ /** The one-time key that seals the session's rendezvous records, base64url. */
13
+ linkKeyB64: string;
14
+ /** The inviter's one-time rendezvous key, z-base-32. */
15
+ inviterRendezvousZ32: string;
16
+ /** The inviter's device signing key (Ed25519 public key, 32 bytes). */
17
+ inviterKey: Uint8Array;
18
+ flags: number;
19
+ /** UNIX seconds. */
20
+ expires: number;
21
+ }
22
+ /** Why a device code was refused. `chat`: it is a chat invite. `expired`: past its time. The others as for a chat invite (WISP 801). */
23
+ export type DeviceInviteRefusal = "typo" | "update" | "not-ghostly" | "damaged" | "chat" | "expired";
24
+ export type DeviceInviteReading = {
25
+ ok: true;
26
+ invite: DeviceInvite;
27
+ } | {
28
+ ok: false;
29
+ reason: DeviceInviteRefusal;
30
+ detail?: string;
31
+ };
32
+ /** The `ghostly1z…` code of a device invite. */
33
+ export declare function encodeDeviceInvite(invite: DeviceInvite): string;
34
+ /**
35
+ * Reads a device code, pasted or scanned (bare, in capitals from a QR code, or after a `#`). `now` is in UNIX
36
+ * seconds: a code past its expiry is refused here already, though only the inviter's word counts.
37
+ */
38
+ export declare function readDeviceInvite(input: string, now?: number): DeviceInviteReading;
39
+ /** What the inviter keeps of a code it made: the invite, and its own end of the one-time link. Never written anywhere. */
40
+ export interface DeviceInviteSide {
41
+ invite: DeviceInvite;
42
+ code: string;
43
+ /** The inviter's end: its one-time rendezvous seed, the joiner's rendezvous key, the link key. */
44
+ params: LinkParams;
45
+ }
46
+ /** A new device code for the device with this signing key, good until `now + DEVICE_INVITE_LIFETIME_S`. */
47
+ export declare function createDeviceInvite(inviterKey: Uint8Array, now?: number): DeviceInviteSide;
48
+ /** The joiner's end of the one-time link a device invite names. */
49
+ export declare function deviceInviteJoinerParams(invite: DeviceInvite): LinkParams;
50
+ /** The joiner's one-time rendezvous key: what the inviter's end of the link waits for. */
51
+ export declare const deviceInviteJoinerKeyZ32: (invite: DeviceInvite) => string;
@@ -0,0 +1,70 @@
1
+ import type { LinkParams } from "./invite.js";
2
+ import type { PairingCredentials } from "./pairedSession.js";
3
+ import type { Signer } from "./signer.js";
4
+ /**
5
+ * A new device-set secret `D`: 32 random bytes (WISP 06 § Terms). The first `D` of a profile is not random, it comes
6
+ * from the DID key's seed (`firstDeviceSetSecret`); every later one, made when a device is removed, is.
7
+ */
8
+ export declare const newDeviceSetSecret: () => Uint8Array;
9
+ /** The secret of the link between two devices of the set that holds `D`. The same whichever key is given first. */
10
+ export declare function deviceLinkSecret(d: Uint8Array, keyA: Uint8Array, keyB: Uint8Array): Uint8Array;
11
+ /** One side's rendezvous seed on a link: the identity its packets of that link are published under. */
12
+ export declare function deviceLinkRendezvousSeed(linkSecret: Uint8Array, signingKey: Uint8Array): Uint8Array;
13
+ /** The key that seals the link's discovery records. */
14
+ export declare function deviceLinkSealKey(linkSecret: Uint8Array): Uint8Array;
15
+ /**
16
+ * The link from the device with `ownKey` to the one with `peerKey`, as a paired link's parameters: this side's
17
+ * rendezvous seed, the other side's rendezvous key, and the shared sealing key.
18
+ */
19
+ export declare function deviceLinkParams(d: Uint8Array, ownKey: Uint8Array, peerKey: Uint8Array): LinkParams;
20
+ /** A device signing key as a session names a participation key (z-base-32). */
21
+ export declare const deviceKeyZ32: (signingKey: Uint8Array) => string;
22
+ /** A `_tr` value signed by this device: `{"t":…,"d":…,"s":"<signature>"}`. `from`/`to`: the link's two rendezvous keys, this side's first. */
23
+ export declare function signDeviceTransports(value: string, signer: Signer, from: string, to: string): Promise<string>;
24
+ /** The unsigned `_tr` value of one signed by `signingKey`, or null for anything else (unsigned, another key, another link). */
25
+ export declare function verifyDeviceTransports(value: string, from: string, to: string, signingKey: Uint8Array): string | null;
26
+ /**
27
+ * The `_tr` value of a signed one, unchecked, or null for anything that is not one: for an enrollment's inviter only,
28
+ * which has no key to check it against until a joiner authenticated (`GhostLink`, trust on first use). Where to dial,
29
+ * and nothing more: the session there still authenticates.
30
+ */
31
+ export declare function unsignedDeviceTransports(value: string): string | null;
32
+ /** What a paired link needs to be a device link: its derived parameters and its pinned, signer-backed pairing. */
33
+ export interface DeviceLinkPairing {
34
+ params: LinkParams;
35
+ pairing: {
36
+ credentials: PairingCredentials;
37
+ pinPeer: (key: string) => Promise<void>;
38
+ trustOnFirstUse: false;
39
+ };
40
+ }
41
+ /**
42
+ * The link from this device (its signer) to the device with `peerKey`, ready for a `GhostLink`. The other device's
43
+ * signing key is pinned before anything is said, as the turn record names it: there is nothing to trust on first
44
+ * use, and no other key is ever saved in its place. Signals in the link's packets must be signed by that key too.
45
+ */
46
+ export declare function deviceLinkPairing(d: Uint8Array, signer: Signer, peerKey: Uint8Array): DeviceLinkPairing;
47
+ export declare const DEVICES_CAPABILITY = "devices/1";
48
+ export declare const HANDOFF_CAPABILITY = "handoff/1";
49
+ export declare const ENROLL_CAPABILITY = "enroll/1";
50
+ export type DeviceCapability = typeof DEVICES_CAPABILITY | typeof HANDOFF_CAPABILITY | typeof ENROLL_CAPABILITY;
51
+ export declare const DEVICE_CAPABILITIES: readonly DeviceCapability[];
52
+ /** The capability a frame of this type travels under, or null when it is no device frame. */
53
+ export declare function deviceFrameCapability(type: unknown): DeviceCapability | null;
54
+ /** A frame between two devices: `t` names it, the rest is its body. */
55
+ export interface DeviceFrame {
56
+ t: string;
57
+ [field: string]: unknown;
58
+ }
59
+ export declare const DEVICE_PING_FRAME = "device-ping";
60
+ export declare const DEVICE_ECHO_FRAME = "device-echo";
61
+ /** `{"t":"device-ping","n":"<16 random bytes, base64url>"}`: asks the other device to say the nonce back. */
62
+ export declare function devicePingFrame(nonce?: Uint8Array): DeviceFrame & {
63
+ n: string;
64
+ };
65
+ /** The echo of a ping, or null when the frame is not a well-formed ping. */
66
+ export declare function deviceEchoFrame(ping: DeviceFrame): (DeviceFrame & {
67
+ n: string;
68
+ }) | null;
69
+ /** The nonce an echo says back, or null when the frame is not a well-formed echo. */
70
+ export declare function deviceEchoNonce(frame: DeviceFrame): string | null;