@ghostlytools/sdk 0.0.0-stage → 1.2.3

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 +67 -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-CBIuqo5e.js +536 -0
  7. package/dist/fakes-CBIuqo5e.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-BylxCPl4.js +76483 -0
  12. package/dist/keet-identity-key-BylxCPl4.js.map +1 -0
  13. package/dist/src-DCeLPsi-.js +31056 -0
  14. package/dist/src-DCeLPsi-.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 +403 -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 +90 -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 +1510 -0
  66. package/dist/types/core/src/groupCommits.d.ts +103 -0
  67. package/dist/types/core/src/groupCommunity.d.ts +714 -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 +710 -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 +141 -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 +437 -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 +151 -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-DBGw6wYt.js +106 -0
  144. package/dist/verify-DBGw6wYt.js.map +1 -0
  145. package/package.json +70 -4
@@ -0,0 +1,144 @@
1
+ import { type Identity } from "./identity.js";
2
+ import type { LinkParams } from "./invite.js";
3
+ import { type GhostRecord, type SignedPacket } from "./pkarr.js";
4
+ /**
5
+ * Store-and-forward for an away contact (WISP 404 draft, `hold/1`).
6
+ *
7
+ * What a person sends while the contact is away is sealed into a *bundle* (signed by the sender's
8
+ * participation key, then encrypted to a key only the two of them can derive), put in the sender's
9
+ * own storage (WISP 1000), and named in a *manifest* the storage also holds. A small signed, encrypted
10
+ * *pointer* record on a per-link Pkarr key tells the contact where the manifest is (a URL that expires)
11
+ * and which of the contact's own bundles have been received. Storage and relays see ciphertext, sizes
12
+ * and timing only. Nothing here promises forward secrecy or retention beyond the bounds below.
13
+ */
14
+ export declare const HOLD_CAPABILITY: "hold/1";
15
+ export declare const HOLD_LIMITS: {
16
+ /** One bundle, ciphertext and header included: a picture, not a video. */
17
+ readonly maxBundleBytes: number;
18
+ /** All bundles held for one contact at once. */
19
+ readonly maxMailboxBytes: number;
20
+ readonly maxMailboxBundles: 64;
21
+ /** A bundle not picked up by then is dropped by its sender. The longest a presigned URL lives, too. */
22
+ readonly ttlMs: number;
23
+ readonly maxTextBytes: number;
24
+ readonly maxPaymentRequestBytes: number;
25
+ readonly maxManifestBytes: number;
26
+ /**
27
+ * How far past one lifetime from now an expiry may reach by the reader's clock: the sender's clock may be ahead, and
28
+ * a day covers any clock that is merely wrong. Nothing else about a pointer or a bundle is held against this clock.
29
+ */
30
+ readonly clockSkewMs: number;
31
+ };
32
+ /**
33
+ * How far before its own clock a sender dates its pointer and its manifest, and ends the lifetimes it gives. A reader
34
+ * refuses nothing for those dates: `rev` orders pointers and `seq` orders items, both kept by the reader. Apps up to
35
+ * 1.0.2 refuse a pointer or a manifest dated more than a minute past their clock, and an expiry more than a minute
36
+ * past one lifetime from now, each without a word: the items of a sender whose clock ran two minutes fast were never
37
+ * fetched. Dated back, a sender up to about eleven minutes ahead is read by them.
38
+ */
39
+ export declare const HOLD_DATED_BACK_MS: number;
40
+ export type HoldKind = "text" | "file" | "pay-req" | "manifest";
41
+ export interface HoldFileMeta {
42
+ name: string;
43
+ size: number;
44
+ mime: string;
45
+ }
46
+ /** One held bundle as the manifest lists it: where to get it, and what to expect. */
47
+ export type HoldManifestEntry = [seq: number, id: string, kind: Exclude<HoldKind, "manifest">, bytes: number, url: string, expires: number];
48
+ export interface HoldHeader {
49
+ v: 1;
50
+ /** Rendezvous keys, as the sender sees the link. */
51
+ from: string;
52
+ to: string;
53
+ /** Participation keys: who signed, who may open. */
54
+ author: string;
55
+ recipient: string;
56
+ mailbox: string;
57
+ seq: number;
58
+ id: string;
59
+ ts: number;
60
+ kind: HoldKind;
61
+ meta: unknown;
62
+ /** base64url SHA-256 of the body. */
63
+ digest: string;
64
+ expires: number;
65
+ }
66
+ export interface HoldPointer {
67
+ rev: number;
68
+ issued: number;
69
+ /** When the manifest URL stops working. */
70
+ expires: number;
71
+ manifestUrl: string | null;
72
+ /** Highest sequence the publisher has held for the reader. */
73
+ top: number;
74
+ /** Highest sequence the publisher received from the reader. */
75
+ ack: number;
76
+ count: number;
77
+ bytes: number;
78
+ /** Sequences of the reader's items this publisher refused (changed, oversized, not for it): at most the last 32. */
79
+ refused: number[];
80
+ }
81
+ /** Why a bundle, manifest or pointer was refused. Never a reason to trust it a little. */
82
+ export declare class HoldRefusedError extends Error {
83
+ readonly reason: "size" | "format" | "tampered" | "not-for-me" | "author" | "signature" | "digest" | "limits" | "expired";
84
+ constructor(reason: "size" | "format" | "tampered" | "not-for-me" | "author" | "signature" | "digest" | "limits" | "expired", message: string);
85
+ }
86
+ declare const newMailbox: () => string;
87
+ export { newMailbox as newHoldMailbox };
88
+ /**
89
+ * Everything derived once per link for this feature: my pointer key, the contact's pointer address and
90
+ * the key that seals bundles and pointers between the two participation keys. Needs a pinned contact.
91
+ */
92
+ export declare class HoldKeys {
93
+ readonly from: string;
94
+ readonly to: string;
95
+ readonly me: string;
96
+ readonly peer: string;
97
+ /** Publishes my pointer. */
98
+ readonly identity: Identity;
99
+ /** Where the contact publishes its pointer. */
100
+ readonly peerAddress: string;
101
+ private readonly seed;
102
+ private readonly sealKey;
103
+ constructor(params: LinkParams, participationSeedB64: string, peerKey: string);
104
+ /** Seals one item for the contact: signed with my participation key, encrypted to our shared key. */
105
+ seal(item: {
106
+ mailbox: string;
107
+ seq: number;
108
+ id: string;
109
+ ts: number;
110
+ kind: HoldKind;
111
+ meta?: unknown;
112
+ expires: number;
113
+ }, body: Uint8Array): Uint8Array;
114
+ /**
115
+ * Opens a bundle the contact sealed for me. Everything is checked before anything is returned: the
116
+ * authenticated encryption, the header's shape, that it names this link, this contact and me, the
117
+ * signature, the body digest and the limits of its kind. `loopback`: see `isHoldUrl`.
118
+ */
119
+ open(bytes: Uint8Array, expect?: {
120
+ maxBytes?: number;
121
+ mailbox?: string;
122
+ now?: number;
123
+ loopback?: boolean;
124
+ }): {
125
+ header: HoldHeader;
126
+ body: Uint8Array;
127
+ };
128
+ /** My pointer, as records to publish under `identity`. Throws when it cannot fit a packet. */
129
+ pointerRecords(pointer: HoldPointer, now?: number): GhostRecord[];
130
+ /**
131
+ * The contact's pointer out of its packet, or null when the packet is not one of its pointers. Its `issued` is the
132
+ * contact's clock and refuses nothing: an older pointer cannot take a newer one's place because of `rev`. The
133
+ * manifest's address is held to what an item's is (`isHoldUrl`): it is fetched as soon as the pointer is read.
134
+ */
135
+ readPointer(packet: SignedPacket, loopback?: boolean): HoldPointer | null;
136
+ }
137
+ /**
138
+ * A URL a bundle or manifest may be fetched from. The contact chose it and this device fetches it on its own, so it
139
+ * is HTTPS, without a user or password, at a name or a public IPv4 address: never this machine or its network.
140
+ * `loopback` adds plain HTTP to this machine, for a test against a local server; no shipped app passes it.
141
+ */
142
+ export declare function isHoldUrl(value: unknown, loopback?: boolean): value is string;
143
+ /** The entries of a manifest, checked: strictly increasing sequences, bounded sizes, fetchable URLs. */
144
+ export declare function readManifest(meta: unknown, loopback?: boolean): HoldManifestEntry[];
@@ -0,0 +1,20 @@
1
+ /**
2
+ * Display text a peer chooses: nicknames and service names. It is shown next
3
+ * to the peer's messages and in the chat header, so it must not be able to
4
+ * read as something it is not, and it must not be able to grow without bound.
5
+ */
6
+ /** Longest nickname kept from a peer. The `hello` frame has always cut here. */
7
+ export declare const MAX_NICK_LENGTH = 64;
8
+ /** `text` without its invisible and direction-changing characters, at any length: for display text with a cut of its own. */
9
+ export declare function stripHidden(text: string): string;
10
+ /** Whether `text` holds a character that shows by itself: a name of joiners, fillers or marks alone has none. */
11
+ export declare function hasVisible(text: string): boolean;
12
+ /** Undefined when nothing visible is left, so callers can fall back. */
13
+ export declare function sanitizeDisplayText(text: string, max: number): string | undefined;
14
+ /** A nickname as it arrived from a peer, ready to show. */
15
+ export declare function sanitizeNick(nick: unknown): string | undefined;
16
+ /**
17
+ * `text` without the characters of `chars` it ends with, in one pass from the end. A `/[…]+$/` replace would retry
18
+ * from every character of a run that does not reach the end.
19
+ */
20
+ export declare function trimEndOf(text: string, chars: string): string;
@@ -0,0 +1,151 @@
1
+ import type { DiscoveryStatus } from "./relayBreaker.js";
2
+ import type { Identity } from "./identity.js";
3
+ import type { GhostRecord, SignedPacket } from "./pkarr.js";
4
+ import type { TurnConditions, TurnSourceAnswer, TurnSourcePut } from "./turnRead.js";
5
+ /**
6
+ * How a Ghostly peer reaches Pkarr. Desktop talks to the Mainline DHT directly
7
+ * through the Rust client; browsers cannot open UDP sockets, so they go through
8
+ * Pkarr relays. Both end up in the same DHT and see each other's packets.
9
+ */
10
+ /**
11
+ * `background`: a request that can wait (a periodic look at a shared record, not a link's
12
+ * signaling). A transport with a request budget spends only part of it on these, so they never
13
+ * starve the links; one without ignores it.
14
+ */
15
+ /**
16
+ * `urgent`: a signal is due any moment (a link polling fast). A transport with more than one relay may
17
+ * ask a second one when the first had nothing new: relays behind one name do not all serve a fresh
18
+ * packet at the same moment.
19
+ */
20
+ /**
21
+ * `group`: a group's request (its edges' signaling, a knock, a community's shared records). A transport with a
22
+ * request budget keeps the last part of each minute for a 1:1 chat it had to hold back; one without ignores it.
23
+ */
24
+ /** What changed in how discovery goes: a relay tripped (left alone), or one answered again. */
25
+ export type DiscoveryChange = "tripped" | "recovered";
26
+ /**
27
+ * `door`: a community's records that open edges: the knock bell the door reads, a hub's lobby and the beacon it reads
28
+ * and writes, and a member's request in a hub's lobby. Background requests, but not held to the small share while a
29
+ * link signals (`BACKGROUND_WHILE_SIGNALING`): the door admitting one person opens links that signal, and the next
30
+ * person's knock would wait for them (2026-09-28). When a hub's app is killed, the edges to it dial it again and look
31
+ * fast for a while, on the hub left and on its members alike: on CLI daemons the hub left got 2 of 24 beacon writes
32
+ * through in 90 s (its entry went stale, and members it should have carried became hubs), and the members' requests
33
+ * in its lobby went out 40 s after they asked (2026-10-03).
34
+ *
35
+ * `signal`: a link's WebRTC signaling, what its contact waits for: the write of a new offer or answer, or a read for
36
+ * the answer while this side's offer is out, or the reads of a DHT-only contact's mailbox once it shows it is leaving,
37
+ * up to three while it still says DHT only (the live link waits on them). A 1:1 chat's may go a little over the relay's minute
38
+ * (`SIGNALING_ALLOWANCE_SHARE` in relay.ts).
39
+ */
40
+ export interface PkarrRequestOptions {
41
+ background?: boolean;
42
+ urgent?: boolean;
43
+ group?: boolean;
44
+ door?: boolean;
45
+ signal?: boolean;
46
+ /**
47
+ * A read for a contact that went away from a live session and has not shown itself back (`LinkSession.watchPeer`), or
48
+ * a write while a link watches for one: what that contact, back, reads first.
49
+ */
50
+ watch?: boolean;
51
+ /**
52
+ * A 1:1 chat's read of a contact that went away from a live session within `DEPARTED_READ_MS` (link.ts): an app that
53
+ * restarts publishes its offer then. A few may go over the relay's minute (`DEPARTED_READS` in relay.ts).
54
+ */
55
+ departed?: boolean;
56
+ }
57
+ /**
58
+ * `transport` with `extra` added to every request's options: a group's edges say `group` so. The optional methods
59
+ * stay optional (a caller reads `configure` as "the DHT is reached directly").
60
+ */
61
+ export declare function withRequestOptions(transport: PkarrTransport, extra: PkarrRequestOptions): PkarrTransport;
62
+ /**
63
+ * A request the transport held back to stay within a request budget, its own or a relay's rate limit: nothing went
64
+ * out, and the same request goes through once the budget frees one, in about `retryInMs`. A wait, never a failure:
65
+ * whoever publishes tries again then, and says nothing is wrong meanwhile.
66
+ */
67
+ export declare class DiscoveryBudgetError extends Error {
68
+ readonly retryInMs: number;
69
+ readonly code = "discovery-budget";
70
+ constructor(retryInMs: number, message?: string);
71
+ }
72
+ /** Whether `error` is a request the budget held back (`DiscoveryBudgetError`), also from another copy of this module. */
73
+ export declare function isDiscoveryBudgetError(error: unknown): error is DiscoveryBudgetError;
74
+ /**
75
+ * A publish Ghostly Desktop's Rust relay client held back, as it says it in words (`pkarr_network.rs`
76
+ * `publish_failure`: "Publish held back on every relay…; retry in N ms: …"), as the `DiscoveryBudgetError` it is: every
77
+ * relay held the packet back for its rate limit, or held it back beside relays left alone for failing, and nothing failed
78
+ * now. Anything else is returned as it came.
79
+ */
80
+ export declare function heldBackError(error: unknown): unknown;
81
+ /** When to try again after the budget held a request back: when it frees one, but never sooner than `min` nor later than `max`. */
82
+ export declare function budgetRetryMs(error: DiscoveryBudgetError, min: number, max: number): number;
83
+ /**
84
+ * A server's own time: the `Date` header (ms, to the second) of its answer to a request that went out at `sent` and
85
+ * came back at `received`, both by this device's clock. `source` names the server (a relay's origin), never a key.
86
+ */
87
+ export interface ServerTime {
88
+ source: string;
89
+ date: number;
90
+ sent: number;
91
+ received: number;
92
+ }
93
+ export interface PkarrTransport {
94
+ publish(identity: Identity, records: GhostRecord[], options?: PkarrRequestOptions): Promise<void>;
95
+ /**
96
+ * Puts a relay payload signed elsewhere, byte for byte (a did:dht document: its own record names and
97
+ * a sequence number in seconds). A transport without it cannot publish one.
98
+ */
99
+ publishPayload?(pubKeyZ32: string, payload: Uint8Array, options?: PkarrRequestOptions): Promise<void>;
100
+ /** Most recent packet known for this key, or null when nothing is published. */
101
+ resolve(pubKeyZ32: string, options?: PkarrRequestOptions): Promise<SignedPacket | null>;
102
+ describe(): {
103
+ protocol: string;
104
+ relays: string[];
105
+ };
106
+ /** How reads go and how each relay is doing, for the connection panel; absent where nothing is known. */
107
+ discovery?(): DiscoveryStatus;
108
+ /**
109
+ * Called when that changes in a way worth showing (a relay trips or recovers), with `"recovered"` when a relay
110
+ * answered again after failing: links then look and publish at once rather than at their pace. Returns the unsubscribe.
111
+ */
112
+ subscribe?(listener: (change?: DiscoveryChange) => void): () => void;
113
+ /** The device changed networks (back online): what was learnt about failing relays is forgotten, and links look again. */
114
+ networkChanged?(): void;
115
+ /**
116
+ * When the network last answered a read of this key (this clock), whatever it answered. A `resolve` may hand back a
117
+ * copy it kept (the budget held the read, every relay was resting, the same key was read a moment ago): a caller
118
+ * that reasons from "the record did not have this at my last read" asks this to know the read was one. Absent
119
+ * where the transport cannot say; such a caller then takes no read for one.
120
+ */
121
+ readAnsweredAt?(pubKeyZ32: string): number | undefined;
122
+ /**
123
+ * Called with each time a server gave (`ServerTime`), where the transport can read one: what `ClockWatch` holds this
124
+ * device's clock against. Returns the unsubscribe.
125
+ */
126
+ onServerTime?(listener: (time: ServerTime) => void): () => void;
127
+ /**
128
+ * Where the DHT is reached directly (Desktop): the relays from Settings, and whether reads may use them too
129
+ * (`readRelays`, "Also use Pkarr relays"). Writes go to them either way, so browser contacts see this peer's packets.
130
+ */
131
+ configure?(options: {
132
+ relays: string[];
133
+ readRelays: boolean;
134
+ }): void;
135
+ /**
136
+ * The turn record's own read (WISP 06 § Publishing and reading): every source is asked, in parallel, and each
137
+ * one's answer is handed back as it came, not verified, not cached and never taken from this client's own writes.
138
+ * Only the turn uses it; a transport without it cannot hold a profile on several devices.
139
+ */
140
+ turnRead?(pubKeyZ32: string, options?: {
141
+ timeoutMs?: number;
142
+ }): Promise<TurnSourceAnswer[]>;
143
+ /**
144
+ * The turn record's own put: the stored bytes, to each source named in `conditions`, on that source's condition
145
+ * (`cas` on the DHT, `If-Match` on a relay). Every source's answer is reported, and a refusal is never tried again
146
+ * without its condition.
147
+ */
148
+ turnPut?(pubKeyZ32: string, payload: Uint8Array, conditions: TurnConditions): Promise<TurnSourcePut[]>;
149
+ /** The profile has a device set: the turn's sources are made ready ahead of the first read (`TurnNetwork.turnWarm`). */
150
+ turnWarm?(): Promise<void>;
151
+ }
@@ -0,0 +1,160 @@
1
+ import { type PairedTransport, type TransportDescriptors } from "./pairedTransports.js";
2
+ export interface TransportPolicy {
3
+ revision: number;
4
+ intent: number;
5
+ preferred: PairedTransport;
6
+ fallback: boolean;
7
+ available: PairedTransport[];
8
+ descriptors: TransportDescriptors;
9
+ }
10
+ export interface SwitchPlan {
11
+ id: string;
12
+ local: TransportPolicy;
13
+ remote: TransportPolicy;
14
+ choices: PairedTransport[];
15
+ /**
16
+ * Nobody chose: the session is on a relayed transport and a direct one ranks first, and both sides said they move
17
+ * (`upgrade`). Quiet: no transport shown as wanted, no row when it does not connect, and tried once.
18
+ */
19
+ upgrade?: boolean;
20
+ }
21
+ export declare const allowedTransports: (policy: TransportPolicy) => ("iroh/1" | "hyperdht/1" | "webrtc/1")[];
22
+ /** Runs only inside a participation-authenticated channel. Both roles may propose;
23
+ * the lower rendezvous key coordinates a revision-checked plan, never both dials.
24
+ * The existing channel stays alive while a replacement proves its own binding. */
25
+ export declare class TransportSwitch {
26
+ private readonly options;
27
+ private context;
28
+ private revision;
29
+ private intent;
30
+ private remote;
31
+ /** The contact's policy as it last said it, kept across sessions: where the next reconnect dials first. */
32
+ private lastRemote;
33
+ private actual?;
34
+ private plan;
35
+ private timer;
36
+ private settled;
37
+ private failed;
38
+ private preparing;
39
+ /** The coordinator's dial for the pending plan has started (`dialing`): from then on a newer choice waits for it. */
40
+ private dialStarted;
41
+ /**
42
+ * The contact's `paired-policy` says `replaces`: its app reads a `paired-switch-keep` for a plan a newer choice
43
+ * replaced as that (`supersede`). An app before 1.1.5 reads it as its target missed and says the chat was kept on its
44
+ * transport; 1.1.5 reads it right but does not say so.
45
+ */
46
+ private remoteReplaces;
47
+ /** This side chose while no session was open: the next one begins with it as a choice. */
48
+ private apart;
49
+ constructor(options: {
50
+ key: string;
51
+ peerKey: string;
52
+ policy(): Omit<TransportPolicy, "revision" | "intent">;
53
+ send(frame: object): void;
54
+ peer(policy: TransportPolicy): void;
55
+ state(error?: string, target?: PairedTransport): void;
56
+ prepare(plan: SwitchPlan, dial: boolean): void;
57
+ cancel(): void;
58
+ /** A plan's target could not be reached and the session stayed on the current transport (fallback allowed it). */
59
+ kept?(target: PairedTransport, reason?: string): void;
60
+ /**
61
+ * A plan's target could not be reached, and nothing kept the chat on another transport: the chat waits for it
62
+ * (WISP 100, "A chosen transport not reached yet") rather than failing, and is told why here, not as an error.
63
+ * `reason` is known on the side that dialled. Without this callback, the failure is an error state, as before.
64
+ */
65
+ unreached?(target: PairedTransport, reason?: string): void;
66
+ /** Both sides move a session off a relayed transport to a direct one ranked first, nobody having chose (`upgrade/1`). */
67
+ upgrade?(): boolean;
68
+ timeoutMs?: number;
69
+ });
70
+ get peerPolicy(): TransportPolicy | null;
71
+ /**
72
+ * The transport a standing explicit choice names (the higher intent; the lower key on a tie), from this side's
73
+ * policy and the contact's last one, when both can use it. None when neither side chose: the rank sum decides.
74
+ * Both sides get the same answer, so whichever redials after a drop lands where the agreement would move it.
75
+ */
76
+ get chosenTarget(): PairedTransport | undefined;
77
+ private winner;
78
+ get pending(): SwitchPlan | null;
79
+ /**
80
+ * Where the policies put the chat while a session is open, and whose choice that is: the agreed target, or, when
81
+ * the two sides' transports do not overlap, the winning side's preferred. `by` is absent when nobody chose (a
82
+ * policy alone, such as Fallback off, names it). Both sides get the same answer.
83
+ */
84
+ wanted(): {
85
+ transport: PairedTransport;
86
+ by?: "you" | "contact";
87
+ } | undefined;
88
+ private local;
89
+ private signature;
90
+ private send;
91
+ /** Older apps read the policy's own fields only, and drop `replaces`. */
92
+ private announce;
93
+ /**
94
+ * A session is ready. `migrated`: it is the one a plan dialled, so that plan is done, even on a fallback choice.
95
+ * Otherwise it is a fresh session (a reconnect after a drop): a plan still pending from the old one did not happen,
96
+ * and what the old one kept or gave up on does not bind this one. Both sides agree again from their policies, so
97
+ * the chat ends on the same transport whichever side dialled.
98
+ * A plan that landed on a fallback choice (its target did not connect, a later choice did) is a target not reached,
99
+ * as when the current transport is kept: its owner waits for it and tries it again (WISP 100).
100
+ */
101
+ begin(context: string, actual: PairedTransport, migrated?: boolean): void;
102
+ /** `automatic`: no choice of this side's any more; the contact's explicit one wins, and without one the
103
+ * current transport is kept while it is allowed. */
104
+ changed(userIntent?: boolean | "automatic"): void;
105
+ /**
106
+ * This side's user chose the transport its policy now names. `again`: the one it named already. Choosing again
107
+ * what this side's standing choice names raises no intent: it would move nothing, and a raised intent could beat
108
+ * a newer choice of the contact's still on its way (the tie goes to the lower key). It still counts as a retry.
109
+ * Choosing again while the contact's choice stands is an override, and raises it.
110
+ */
111
+ chose(again?: boolean): void;
112
+ /**
113
+ * This side's user chose with no session open (WISP 100, "A choice made while not live"). Nothing to announce it on:
114
+ * the next session begins with it as a choice, so the chat moves there if that session opened elsewhere.
115
+ */
116
+ choseApart(): void;
117
+ /** This side's explicit choice is the one that stands (its intent is the higher, or wins the tie). */
118
+ get standing(): boolean;
119
+ keep(reason?: string): void;
120
+ retry(): void;
121
+ /**
122
+ * Tries the target again after it did not connect (WISP 100: retried, never given up), also when a fallback kept
123
+ * the chat on another transport. The coordinator plans again. The other side cannot: its policy goes out again under
124
+ * a new revision, which the coordinator reconciles afresh, whatever it had given up on.
125
+ */
126
+ again(): void;
127
+ stop(): void;
128
+ private clearPlan;
129
+ /** The coordinator starts dialling the pending plan (a move back to WebRTC first waits for the old session to retire). */
130
+ dialing(plan: SwitchPlan): void;
131
+ /**
132
+ * A newer choice (this side's, or the contact's policy) while a plan both sides agreed has not started its dial: a
133
+ * move back to WebRTC waits for the WebRTC session it left to retire (`SWITCH_RETIRE_MS`), and nothing has been tried
134
+ * yet. The coordinator drops that plan, so the chat does not move there only to move again; the other side is told
135
+ * with `paired-switch-keep`, and whatever the newer policies call for is planned next. A plan already dialling goes
136
+ * on: a choice made then is planned once it ended (`replanIfMoved`). So does a plan the contact's app would take
137
+ * that keep for a target missed (its policy did not say `replaces`): the newer choice is planned once it landed.
138
+ */
139
+ private supersede;
140
+ fail(error: string): void;
141
+ /**
142
+ * A choice made while a move was dialling could not cut in (WISP 100): once that move failed, it is planned at once.
143
+ * Policies that are still the failed plan's are not planned again here; the owner's retry pace does that.
144
+ */
145
+ private replanIfMoved;
146
+ /** Waiting for `target`, not failed, where the owner says why; an error state for an owner that does not. */
147
+ private unreached;
148
+ private choices;
149
+ /** Nobody chose, the session is on a relayed transport, a direct one ranks first, and both sides move (`upgrade/1`). */
150
+ private upgrading;
151
+ private isUpgrade;
152
+ /**
153
+ * Something `upgrade` depends on changed (what the contact's app offers on this session, said once it is ready): plan
154
+ * again. The session's first agreement, made before that, settled on the relay it is on; a move off it is not that.
155
+ */
156
+ reconsider(): void;
157
+ private install;
158
+ private reconcile;
159
+ handle(frame: Record<string, unknown>): boolean;
160
+ }
@@ -0,0 +1,145 @@
1
+ import { type TurnKeys, type TurnRecord, type TurnRefusal } from "./turnRecord.js";
2
+ /** One source's answer to a read: a relay, or the DHT itself. */
3
+ export interface TurnSourceAnswer {
4
+ /** The relay's address, or `dht`. */
5
+ source: string;
6
+ /** Whether it answered at all. A source that answers "no record" answered. */
7
+ answered: boolean;
8
+ /** The packets it returned, as relay payloads: one from a relay, every distinct item the nodes returned from the DHT. */
9
+ payloads: Uint8Array[];
10
+ /**
11
+ * Sequences (decimal text) the source reports holding without handing the item over: an item under the key that is
12
+ * no signed packet at all. Nobody signed that number, and the source could say anything: it is that source's put
13
+ * condition and nothing else. It never counts as seen, never closes the address and never moves a writer's place.
14
+ */
15
+ sequences?: string[];
16
+ /**
17
+ * The answer may be minutes old: a relay that does not know `?policy=NetworkOnly` was asked plainly and answered
18
+ * from its cache. Such an answer can show a newer record (that is never stale news), but never makes `mine` or
19
+ * `none`, and alone it does not make a read good.
20
+ */
21
+ stale?: boolean;
22
+ detail?: string;
23
+ }
24
+ /** What a source said to a put. `refused`: someone else wrote (301, 302 from a node; 409, 412, 428 from a relay). Read. */
25
+ export interface TurnSourcePut {
26
+ source: string;
27
+ outcome: "stored" | "refused" | "failed";
28
+ detail?: string;
29
+ }
30
+ /**
31
+ * What each source is known to hold, from the last read: its highest sequence (as decimal text), or null when it
32
+ * answered that it has no record. A put goes only to the sources named here, each with its own condition: a source
33
+ * that lags must not be compared with what another one holds. A source that did not answer the read is not put to.
34
+ */
35
+ export type TurnConditions = Record<string, string | null>;
36
+ /** The turn's own way to the network: every source read, every put conditional, no answer hidden, nothing retried. */
37
+ export interface TurnNetwork {
38
+ /** `timeoutMs`: how long each source has, where less than the usual 8 s (`TURN_RAISE_READ_TIMEOUT_MS`). */
39
+ turnRead(pubKeyZ32: string, options?: {
40
+ timeoutMs?: number;
41
+ }): Promise<TurnSourceAnswer[]>;
42
+ turnPut(pubKeyZ32: string, payload: Uint8Array, conditions: TurnConditions): Promise<TurnSourcePut[]>;
43
+ /**
44
+ * The profile has a device set: whatever a source needs before its first answer is made ready now (the Desktop's
45
+ * own DHT node for the turn, which takes seconds to join). Never called for a profile on one device.
46
+ */
47
+ turnWarm?(): Promise<void>;
48
+ }
49
+ /** `P`: a raising put is sent within this long of the start of the read it acts on. */
50
+ export declare const TURN_PUT_WINDOW_MS = 10000;
51
+ /**
52
+ * How long each source has to answer the read a raising put acts on. `P` counts from the start of that read, and a
53
+ * source may take 8 s to answer an ordinary one, which would leave 2 s to sign, store and send. With 5 s, 5 s remain.
54
+ * A source that is slower did not answer that read, and is not put to.
55
+ */
56
+ export declare const TURN_RAISE_READ_TIMEOUT_MS = 5000;
57
+ /**
58
+ * `V`: the longest a put is assumed to take from being sent to being visible at every source. Measured once
59
+ * (2026-10-02, `live_turn_visible_everywhere_after` in the Desktop's Rust, one put each way): a put through one default
60
+ * relay ended after 3.6 s and a read of every source started then showed it at the other relay and on the DHT; a
61
+ * put on the DHT ended after 2.1 s and both relays showed it to a read started then. One sample, so the assumed
62
+ * 10 s stays.
63
+ */
64
+ export declare const TURN_VISIBLE_MS = 10000;
65
+ /** `T`: how long a device that raised the turn waits, from the end of its put, before the read that may make it active. `T >= P + 2V`. */
66
+ export declare const TURN_SETTLE_MS = 30000;
67
+ /** WISP 06 § Publishing and reading, the result table. */
68
+ export type TurnResult = "mine" | "behind" | "other" | "clone" | "tombstone" | "closed" | "none" | "unreachable";
69
+ /** Who reads: what this device holds. */
70
+ export interface TurnReader {
71
+ keys: TurnKeys;
72
+ /** This device's signing key. */
73
+ ownKey: Uint8Array;
74
+ /** The packet this device stored: its own last record, or (a device that never was active) the last record it accepted. */
75
+ stored: Uint8Array | null;
76
+ /** This device's slot, where it has one and the stored packet does not say (it is not listed there yet). */
77
+ ownSlot?: number;
78
+ /** A `taking` device: the turn it takes. It yields to any other valid record at that turn, whatever the sequences. */
79
+ taking?: number;
80
+ /**
81
+ * The mark: the highest sequence this device ever saw at the address in a packet that verified under the turn key.
82
+ * A record below it is no news (`behind`): a newer record that expired does not make an older one current again.
83
+ */
84
+ seen?: bigint;
85
+ }
86
+ export interface TurnRead {
87
+ result: TurnResult;
88
+ /** A read is good when at least one source answered and the result is not `closed`. */
89
+ good: boolean;
90
+ /**
91
+ * The record the result is about: the highest valid one the sources hold (`mine`: this device's own; `behind`: the
92
+ * lower one they hold; `other`, `clone`, `tombstone`: the one that outranks this device). Absent for `none` and `unreachable`.
93
+ */
94
+ record?: TurnRecord;
95
+ /** That record's packet, to store when it is accepted. */
96
+ payload?: Uint8Array;
97
+ /** `clone`: above this device's stored sequence, or at an equal one. */
98
+ clone?: "above" | "equal";
99
+ /** `clone` at an equal sequence: whether this device's `instance` is the lower one. It then goes on and writes `rev` plus one at once. */
100
+ lower?: boolean;
101
+ /** `tombstone`: whether this device is still listed (`moving`) or not (`removed`). */
102
+ listed?: boolean;
103
+ /** `other`: the turn was taken without a release, or with one whose `from` was not the device this reader knew as active. */
104
+ forced?: boolean;
105
+ /** `other`: the record is the one this device already stored (a standby reading the active device's record again). */
106
+ known?: boolean;
107
+ /**
108
+ * The highest sequence among the answers in a packet that verified under the turn key, its record valid or not.
109
+ * 0 when there was none. What moves the device's mark; a number a source only reports never does.
110
+ */
111
+ seen: bigint;
112
+ /** Packets under the turn key that are no valid record, with the rule each breaks. Signed by the turn key, every one. */
113
+ invalid: {
114
+ source: string;
115
+ sequence: bigint;
116
+ refusal: TurnRefusal;
117
+ }[];
118
+ /** Sequences a source named for an item it did not hand over (`TurnSourceAnswer.sequences`): unsigned, so only reported. */
119
+ unsigned: {
120
+ source: string;
121
+ sequence: bigint;
122
+ }[];
123
+ /** Per source that answered: the highest raw sequence it holds, for the next put's conditions. */
124
+ conditions: TurnConditions;
125
+ }
126
+ type Kept = {
127
+ record: TurnRecord;
128
+ payload: Uint8Array;
129
+ };
130
+ /**
131
+ * Of two valid records at one sequence, the one every reader keeps: the lower `instance` (WISP 06 § Record); negative
132
+ * when that is `a`. Never a library's own rule: the `pkarr` crate prefers the larger encoded bytes, which for a sealed
133
+ * record is random. Two records with one `instance` are told apart by their bodies, then by their packets, so every
134
+ * reader still agrees.
135
+ */
136
+ export declare function keptAtEqualSequence(a: Kept, b: Kept): number;
137
+ /** The result of a read: what the answers of every source mean for this device. */
138
+ export declare function classifyTurnRead(reader: TurnReader, answers: TurnSourceAnswer[]): TurnRead;
139
+ /** A put's answers in short. `refused` anywhere means someone else wrote: read, and never put again without the condition. */
140
+ export declare function turnPutSummary(puts: TurnSourcePut[]): {
141
+ stored: number;
142
+ refused: number;
143
+ failed: number;
144
+ };
145
+ export {};