@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,163 @@
1
+ import { type ProofAdapter } from "./peerProofs.js";
2
+ import { HOLD_CAPABILITY } from "./storeForward.js";
3
+ import type { FrameChannel } from "./frames.js";
4
+ import { type PairedTransport, type NativeBinding } from "./pairedTransports.js";
5
+ import type { Signer } from "./signer.js";
6
+ /** Experimental, opt-in profile. Ed25519 authenticates a transcript bound to WebRTC DTLS.
7
+ * This is not a new cipher/key exchange, nor an audited WISP Final profile. */
8
+ export declare const PAIRED_PROFILE: "paired-chat/1";
9
+ export interface PairingState {
10
+ transport?: PairedTransport;
11
+ preferred?: PairedTransport;
12
+ status: "connecting" | "negotiating" | "confirm" | "waiting" | "ready" | "error";
13
+ code?: string;
14
+ error?: string;
15
+ peerKey?: string;
16
+ verified?: boolean;
17
+ peerNeedsConfirmation?: boolean;
18
+ keyMismatch?: boolean;
19
+ transitionTarget?: PairedTransport;
20
+ transitionError?: string;
21
+ }
22
+ export interface PairingCredentials {
23
+ /** This side's participation seed. Not read when `signer` is given (a device link passes an empty one). */
24
+ seedB64: string;
25
+ /**
26
+ * Signs in place of the seed (WISP 06 § Terms): a device link's participation key is the device signing key, which
27
+ * the app may hold no seed for. The session then names `signer.publicKey` as its key and signs its transcript
28
+ * through it. Absent, as in every chat and group: the seed signs, exactly as before.
29
+ */
30
+ signer?: Signer;
31
+ peerKey?: string;
32
+ requireSignedSignals?: boolean;
33
+ verifiedPeerKey?: string;
34
+ /**
35
+ * The key the invite named (a `ghostly1` code carries the inviter's): before
36
+ * anything is pinned, an answer signed by any other key is a security rejection.
37
+ */
38
+ expectedPeerKey?: string;
39
+ }
40
+ export interface PairedSessionOptions {
41
+ credentials: PairingCredentials;
42
+ rendezvousKeys: [string, string];
43
+ /** SHA-256 certificate fingerprints extracted from this exact RTCPeerConnection. */
44
+ fingerprints?: [string, string];
45
+ binding?: NativeBinding;
46
+ transports?: PairedTransport[];
47
+ allowFallback?: boolean;
48
+ proofSupport?: boolean;
49
+ /** Identity proofs (WISP 300): `identity-proof/1`. */
50
+ identitySupport?: boolean;
51
+ filesSupport?: boolean;
52
+ paymentsSupport?: boolean;
53
+ /** Ecash straight in the chat. Absent means allowed, as before ways of paying could be chosen per chat. */
54
+ cashuPaymentsSupport?: boolean;
55
+ /** Lightning invoices in the chat. Absent means allowed. */
56
+ lightningPaymentsSupport?: boolean;
57
+ arkPaymentsSupport?: boolean;
58
+ usdtPaymentsSupport?: boolean;
59
+ barkPaymentsSupport?: boolean;
60
+ transportSwitchSupport?: boolean;
61
+ /** Store-and-forward for an away contact (`hold/1`): this device accepts held items and may hold some. */
62
+ holdSupport?: boolean;
63
+ /** TOFU admission is distinct from an optional human comparison. */
64
+ trustOnFirstUse?: boolean;
65
+ /**
66
+ * How long the peer has to authenticate before the session fails: three minutes by default, room for a person to
67
+ * compare codes. A connection that holds a place no person waits on (one dialled in on a pinned chat) gets less.
68
+ */
69
+ authTimeoutMs?: number;
70
+ verifyPeer?: (key: string) => Promise<void>;
71
+ /** Atomic durable compare-and-set. Resolving means the key is pinned on disk. */
72
+ pinPeer: (key: string, signedSignals?: boolean) => Promise<void>;
73
+ onState: (state: PairingState) => void;
74
+ onReady: () => void;
75
+ onApplication: (data: string | Uint8Array) => void | Promise<void>;
76
+ onFailure: () => void;
77
+ }
78
+ /** The ways of paying a chat can allow one by one. */
79
+ /**
80
+ * `bitcoin` (on-chain), `fedimint` and `spark` are never offered in the handshake: a full offer is already at the 16
81
+ * capabilities apps before 0.5 accept. Both sides allow them only through the `paired-payments` list of the open
82
+ * session.
83
+ */
84
+ export type PaymentMethodName = "cashu" | "lightning" | "arkade" | "usdt" | "bark" | "bitcoin" | "fedimint" | "spark";
85
+ /** One frame from the peer, at most (UTF-16 units for text, bytes for binary): a bigger one breaks the protocol. */
86
+ export declare const SESSION_FRAME_MAX: number;
87
+ /**
88
+ * Frames received and not handled yet, at most: their count and their size together. Frames are handled one at a time,
89
+ * each awaited (a group frame is decrypted, checked and stored before the next), and the peer sends at the network's
90
+ * pace. A member back in a group answers a sync with a burst: a commit per epoch, its kept messages, the ones it hands
91
+ * on, edits, reactions. With a bound of 64 frames a phone handling them a few milliseconds each failed its session
92
+ * mid catch-up ("Session receive limit exceeded" then, "Session receive queue full" now, 2026-10-07). The size bound keeps the old worst case in memory
93
+ * (64 frames of 60 KiB); the count only bounds a flood of tiny frames.
94
+ */
95
+ export declare const SESSION_RECEIVE_PENDING: {
96
+ readonly frames: 1024;
97
+ readonly bytes: number;
98
+ };
99
+ export declare class PairedSession {
100
+ private channel;
101
+ private options;
102
+ state: PairingState;
103
+ /** The peer said nothing more within `authTimeoutMs`: the connection carried nothing, which proves nothing about the peer. */
104
+ authTimedOut: boolean;
105
+ /**
106
+ * The peer sent faster than this side handles, past `SESSION_RECEIVE_PENDING`: the session ends, which is no proof
107
+ * of anything wrong with the peer (a burst of catch-up on a slow device), so the chat dials again.
108
+ */
109
+ overloaded: boolean;
110
+ /** The seed's identity; null when a signer signs. */
111
+ private readonly identity;
112
+ private readonly signer?;
113
+ private readonly offer;
114
+ private readonly transport;
115
+ private preferred?;
116
+ private peer;
117
+ private transcript;
118
+ private digest;
119
+ private proofReceived;
120
+ private localReady;
121
+ private peerReady;
122
+ private stopped;
123
+ private confirming;
124
+ private admission;
125
+ private pending;
126
+ private pendingBytes;
127
+ private queue;
128
+ private timer;
129
+ constructor(channel: FrameChannel, options: PairedSessionOptions);
130
+ supports(capability: "files/2" | "payments/1" | "payments-arkade/1" | "payments-usdt/1" | "payments-bark/1" | typeof HOLD_CAPABILITY): boolean;
131
+ /**
132
+ * Both sides allow this way of paying. A peer that offers payments/1 without naming Cashu or
133
+ * Lightning predates choosing them per chat, and allows both.
134
+ */
135
+ allowsPayment(method: PaymentMethodName): boolean;
136
+ /** The peer's offer alone allows this way of paying. */
137
+ peerAllowsPayment(method: PaymentMethodName): boolean;
138
+ get peerTransportSwitchSupport(): boolean;
139
+ /** The peer's offer alone carries `hold/1`: it accepts held items from us, whatever we offered. */
140
+ get peerHoldSupport(): boolean;
141
+ get proofSession(): string;
142
+ get peerProofAdapters(): ProofAdapter[];
143
+ get peerProofSupport(): boolean;
144
+ /** Both offers carry `identity-proof/1`. */
145
+ get identitySupport(): boolean;
146
+ get peerTransports(): readonly string[];
147
+ /** The peer said in its offer that it answers pings, so its silence from the open means it stopped. */
148
+ get peerAnswersPings(): boolean;
149
+ get peerAllowsFallback(): boolean;
150
+ start(): void;
151
+ private send;
152
+ private receive;
153
+ private code;
154
+ /** A user's explicit comparison. Never called by automatic admission/reconnection. */
155
+ confirm(expectedCode: string): Promise<void>;
156
+ /** Save the authenticated key before enabling any application capability. */
157
+ private admit;
158
+ private admitOnce;
159
+ private maybeReady;
160
+ private update;
161
+ private fail;
162
+ stop(): void;
163
+ }
@@ -0,0 +1,17 @@
1
+ import type { Signer } from "./signer.js";
2
+ /** Sign the existing compact signal, including its timestamp and DTLS binding.
3
+ * Extra fields remain readable by first-increment clients during migration. */
4
+ export declare function signPairedSignal(signal: string, seed: string, from: string, to: string): string;
5
+ /** Invalid input never reaches DataLink's timestamp/glare/SDP state machine. */
6
+ export declare function verifyPairedSignal(signal: string, from: string, to: string, peerKey?: string, required?: boolean): string | null;
7
+ /** Keep at least one candidate. Drop duplicate candidate types first; if still
8
+ * necessary prefer relay/server-reflexive reachability over another host route.
9
+ * Every resulting set is signed afresh, never truncated after authentication. */
10
+ export declare function fitSignedPairedSignal(signal: string, seed: string, from: string, to: string, fits: (signed: string) => boolean): string;
11
+ /**
12
+ * `signPairedSignal` through a signer (a device link's: the app may hold no seed for a device signing key, WISP 06).
13
+ * The same frame and the same transcript; only who signs differs.
14
+ */
15
+ export declare function signPairedSignalWith(signal: string, signer: Signer, from: string, to: string): Promise<string>;
16
+ /** `fitSignedPairedSignal` through a signer: the same candidates are dropped in the same order. */
17
+ export declare function fitSignedPairedSignalWith(signal: string, signer: Signer, from: string, to: string, fits: (signed: string) => boolean): Promise<string>;
@@ -0,0 +1,76 @@
1
+ import type { FrameChannel } from "./frames.js";
2
+ export declare const TRANSPORTS: readonly ["iroh/1", "hyperdht/1", "webrtc/1"];
3
+ export type PairedTransport = typeof TRANSPORTS[number];
4
+ export type NativeTransport = Exclude<PairedTransport, "webrtc/1">;
5
+ /** Supplied only by the local adapter after its real cryptographic handshake.
6
+ * Iroh uses a TLS exporter; HyperDHT uses its Noise handshake hash. */
7
+ export interface NativeBinding {
8
+ transport: NativeTransport;
9
+ context: string;
10
+ identities: [string, string];
11
+ }
12
+ export interface BoundChannel {
13
+ channel: FrameChannel;
14
+ binding: NativeBinding;
15
+ }
16
+ export interface NativeEndpoint {
17
+ transport: NativeTransport;
18
+ descriptor: unknown;
19
+ connect(descriptor: unknown): Promise<BoundChannel>;
20
+ close(): Promise<void>;
21
+ onConnection: ((connection: BoundChannel) => void) | null;
22
+ onDescriptor: (() => void) | null;
23
+ onUnavailable?: (() => void) | null;
24
+ }
25
+ export type TransportDescriptors = Partial<Record<NativeTransport, unknown>>;
26
+ /**
27
+ * One spelling per Iroh relay. Iroh compares relay URLs as text, and its own relays are named with the trailing dot
28
+ * of a fully qualified name (`https://use1-1.relay.n0.iroh.link./`): the same server written without the dot is
29
+ * another relay to it, and an endpoint dialling a contact there opens a second connection to the server it is already
30
+ * homed on, which the server answers by setting the first one aside.
31
+ *
32
+ * So every relay URL is put in one spelling before it goes into an Iroh endpoint (the relays it homes on, a contact's
33
+ * descriptor before a dial), and which one depends on the endpoint:
34
+ * - `"dotted"`, the name with its trailing dot: what native Iroh homes on by default (the Desktop), and the form to
35
+ * compare two relays in.
36
+ * - `"plain"`, the name without it: the only one every browser opens. WebKit (Safari, the iPhone app) refuses a
37
+ * host name that ends in a dot, for `fetch` and for a WebSocket alike, so nothing a browser's Iroh is given has one.
38
+ *
39
+ * An IP address and a single-label name (a search domain may complete it) stay as written; `localhost.` loses its dot
40
+ * in both, the form the relay settings accept. What does not parse comes back untouched, for the caller's own check.
41
+ */
42
+ export type IrohRelaySpelling = "dotted" | "plain";
43
+ export declare function irohRelayUrl(value: string, spelling?: IrohRelaySpelling): string;
44
+ /** An Iroh descriptor with its relay in one spelling (`irohRelayUrl`); anything else as it is. */
45
+ export declare function irohDescriptor<T>(descriptor: T, spelling?: IrohRelaySpelling): T;
46
+ /**
47
+ * A relay server's URL, short: https, or wss for a browser's relay; plain http or ws only on this machine's loopback,
48
+ * as a test relay is (the same rule as the relay settings).
49
+ */
50
+ export declare const RELAY_URL: RegExp;
51
+ /**
52
+ * A contact's native descriptors as it tells them on a session (`paired-policy`, `paired-adapters`) or as this app
53
+ * kept them: only what the adapters dial, each field in the shape its adapter makes. The keys are 64 hex characters,
54
+ * a relay passes `RELAY_URL` (the rule its capability record is read by), an Iroh descriptor lists at most eight
55
+ * socket addresses. A descriptor that is anything else is left out, as one the contact never told; a field this app
56
+ * does not know is not kept.
57
+ */
58
+ export declare function checkedDescriptors(value: unknown): TransportDescriptors;
59
+ /**
60
+ * Relay only (WISP 100, "Relayed"): the transport reaches this contact only through a relay server, never
61
+ * directly. A descriptor says so with `relayed: true`, and an Iroh descriptor with no direct address is relayed
62
+ * too (a browser's, WISP 102). Either side being relay only makes the whole path relayed. Both sides hold both
63
+ * descriptors after the exchange, so they agree, and the rank stays symmetric.
64
+ */
65
+ export declare function relayedTransports(local: TransportDescriptors, remote: TransportDescriptors): NativeTransport[];
66
+ /** Symmetric rank sum; the fixed order breaks ties deterministically. Neither
67
+ * a remote list nor a preference can add an unavailable local adapter. A
68
+ * relayed transport ranks after every direct one: it is where a failed direct
69
+ * path goes, never ahead of one that works. */
70
+ export declare function rankTransports(local: readonly string[], remote: readonly string[], relayed?: readonly string[]): PairedTransport[];
71
+ /**
72
+ * What a chat prefers when nobody chose (Automatic): WebRTC where the app has it, else the first transport it has
73
+ * (a Linux Desktop: WebKitGTK has no WebRTC). With nothing at all, WebRTC, which the offer then leaves out.
74
+ */
75
+ export declare function automaticTransport(available: readonly PairedTransport[]): PairedTransport;
76
+ export declare function transportOrder(available: readonly PairedTransport[], preferred: PairedTransport, fallback: boolean): PairedTransport[];
@@ -0,0 +1,130 @@
1
+ /**
2
+ * The typing indicator of a 1:1 chat (WISP 401 § Typing): "your contact is writing", said on the live session only.
3
+ *
4
+ * {"t":"paired-typing","s":"start"} {"t":"paired-typing","s":"stop"}
5
+ * {"t":"paired-typing","s":"start","kind":"recording"}
6
+ * {"t":"paired-typing","s":"start","kind":"thinking","status":"Transcribing your audio…"}
7
+ *
8
+ * It needs `typing/1` in `paired-capabilities` on both sides. It is presence, not a message: never sent on the
9
+ * DHT, never stored, never counted as unread, no message id (older apps drop it). While the person keeps typing,
10
+ * `start` is said again at most every `TYPING_REFRESH_MS`; the receiver shows it until `stop`, a message from that
11
+ * contact, the end of the session, or `TYPING_TIMEOUT_MS` without a new `start` (so a dropped link never leaves it on).
12
+ * A start standing when a session ends (a transport switch, a reconnect) is said again once the next one agreed
13
+ * `typing/1`, if the person's last word is still that recent.
14
+ *
15
+ * A `start` may say what the contact is doing (`kind`: typing, recording a voice note, thinking) and, for bots, a
16
+ * short `status` line. Both are optional: an app that knows neither shows "typing…", and so does a kind it does not
17
+ * know. A `start` with a new kind or status goes at once, not at the next refresh.
18
+ */
19
+ export declare const TYPING_FRAME = "paired-typing";
20
+ /** How often a `start` is said again while the person keeps typing. */
21
+ export declare const TYPING_REFRESH_MS = 3000;
22
+ /** How long a `start` holds on the receiving side without another. Twice the refresh, so one lost frame is no gap. */
23
+ export declare const TYPING_TIMEOUT_MS = 6000;
24
+ /** At most this many typing frames count per `TYPING_RATE_WINDOW_MS`; the rest are dropped unread. */
25
+ export declare const TYPING_RATE_LIMIT = 8;
26
+ export declare const TYPING_RATE_WINDOW_MS = 10000;
27
+ /**
28
+ * The sender keeps under the reader's limit: a `start` goes only while fewer than this many frames went in the
29
+ * window, so the `stop` that follows it always has room (and a clock skew between the two sides has one frame more).
30
+ */
31
+ export declare const TYPING_SEND_LIMIT: number;
32
+ /** What the contact is doing: writing, recording a voice note, or working on an answer (a bot). */
33
+ export declare const TYPING_KINDS: readonly ["typing", "recording", "thinking"];
34
+ export type TypingKind = (typeof TYPING_KINDS)[number];
35
+ /** Longest status line kept, in characters (code points). */
36
+ export declare const TYPING_STATUS_MAX = 40;
37
+ /** A `start`'s word: the kind, and a bot's status line when it gave one. */
38
+ export interface TypingActivity {
39
+ kind: TypingKind;
40
+ status?: string;
41
+ }
42
+ export type TypingState = "start" | "stop";
43
+ export type TypingFrame = {
44
+ t: typeof TYPING_FRAME;
45
+ s: TypingState;
46
+ kind?: Exclude<TypingKind, "typing">;
47
+ status?: string;
48
+ };
49
+ /**
50
+ * A status line as it may be shown: one line (line breaks and runs of spaces become one space), no invisible or
51
+ * direction-changing characters, at most `TYPING_STATUS_MAX` characters. Undefined when nothing is left, or when it
52
+ * holds a link or markup (it is plain text, never a way to put a link on the contact's screen).
53
+ */
54
+ export declare function sanitizeTypingStatus(value: unknown): string | undefined;
55
+ /** A kind as it arrived: anything this app does not know reads as plain typing. */
56
+ export declare function typingKindOf(value: unknown): TypingKind;
57
+ /** The activity as it goes on the wire and is shown: kind checked, status sanitized. */
58
+ export declare function typingActivity(kind?: unknown, status?: unknown): TypingActivity;
59
+ export declare function typingFrame(state: TypingState, activity?: TypingActivity): TypingFrame;
60
+ /** The state a `paired-typing` frame says, or null when it is malformed (then it says nothing). */
61
+ export declare function parseTypingFrame(frame: Record<string, unknown>): TypingState | null;
62
+ /** What a `start` says the contact is doing: `typing` when it says nothing (an older app) or a kind unknown here. */
63
+ export declare function parseTypingActivity(frame: Record<string, unknown>): TypingActivity;
64
+ /**
65
+ * This side's word: when to say `start` again, and whether a `stop` is owed. One per chat; what was said is per session
66
+ * (`reset`), what the person is doing is not: a new session (a transport switch, a reconnect) says a standing start
67
+ * again (`resume`), since the contact's reader cleared it when the old session ended.
68
+ *
69
+ * The rate window is not per session: the reader's is per chat too (it is not cleared when a session ends), so a
70
+ * window that started afresh on each session could put a start past the reader's limit just after a switch.
71
+ */
72
+ export declare class TypingSender {
73
+ private readonly now;
74
+ private startedAt;
75
+ private standing;
76
+ private recent;
77
+ /** What the person is doing, and when it last said so: kept across sessions, until it stops. */
78
+ private wanted;
79
+ constructor(now?: () => number);
80
+ /**
81
+ * The person typed (or records, or thinks): the frame to send now, or null when a `start` with the same word went
82
+ * out less than a refresh ago, or the window is full (the next call tries again).
83
+ */
84
+ typing(activity?: TypingActivity): TypingFrame | null;
85
+ /**
86
+ * The person typed while nothing can be said (no session, or `typing/1` not agreed on it yet): kept, so the start
87
+ * goes once a session can carry it (`resume`).
88
+ */
89
+ want(activity?: TypingActivity): void;
90
+ /**
91
+ * A new session agreed `typing/1`: the `start` to say on it when the person was still at it, its last word less than
92
+ * `TYPING_TIMEOUT_MS` ago (as long as the contact would still have shown it). Null otherwise, when a start already
93
+ * went on this session, or when the window is full (the person's next keystroke says it).
94
+ */
95
+ resume(): TypingFrame | null;
96
+ private say;
97
+ /**
98
+ * The person stopped (cleared the text, sent it, left the chat): a `stop`, only when a `start` is standing on this
99
+ * session. Nothing is said again on the next one either way.
100
+ */
101
+ stopped(): TypingFrame | null;
102
+ /** A `start` is standing on this session. */
103
+ get active(): boolean;
104
+ /** The session ended: nothing is standing on the next one until `resume` (or the next keystroke) says it. */
105
+ reset(): void;
106
+ }
107
+ /**
108
+ * The contact's word, with its timeout and a rate limit. `onChange` hears every change, and only changes: typing on
109
+ * or off, and a new kind or status while it is on.
110
+ */
111
+ export declare class TypingReceiver {
112
+ private readonly onChange;
113
+ private readonly now;
114
+ private activity;
115
+ private timer;
116
+ private recent;
117
+ constructor(onChange: (typing: boolean, activity: TypingActivity | null) => void, now?: () => number);
118
+ /** The contact is typing now. */
119
+ get peerTyping(): boolean;
120
+ /** What the contact is doing now, or null. */
121
+ get peerActivity(): TypingActivity | null;
122
+ /**
123
+ * A `paired-typing` frame from the contact. False when it was dropped: malformed, or over the rate limit (a
124
+ * contact flooding frames gets its word held where it was until the window lets it speak again).
125
+ */
126
+ receive(frame: Record<string, unknown>): boolean;
127
+ /** A message from the contact arrived, or the session ended: it is not typing any more. */
128
+ clear(): void;
129
+ private set;
130
+ }
@@ -0,0 +1,109 @@
1
+ import { type PushRequest, type PushTarget, type VapidKeys } from "./webPush.js";
2
+ /**
3
+ * Wake-up push (WISP 401 § Wake-up push): a contact whose web app is closed can be woken by this app, with no
4
+ * server of Ghostly's. The contact's app subscribes to its browser's push service and shares, with each paired
5
+ * contact and only on the live session, where to post and how:
6
+ *
7
+ * {"t":"paired-wake","w":{"e":"https://fcm.googleapis.com/fcm/send/…","p":"<p256dh>","a":"<auth>",
8
+ * "vp":"<VAPID public>","vk":"<VAPID private>","k":"<token>"}}
9
+ * {"t":"paired-wake","w":null} (stopped: forget what I shared)
10
+ *
11
+ * When a message to that contact cannot go live (the contact's app is closed), this app posts an encrypted push
12
+ * of a few bytes to the endpoint: `{"wake":1,"k":"<token>"}`. It says nothing about the message: the contact's
13
+ * app shows "New message", opens on a tap, connects and fetches the message itself. The token is the contact's
14
+ * own name for this chat, different for every contact, so its app knows which chat (and whether it is muted)
15
+ * without the push service learning anything: it sees only that a push happened, and when.
16
+ *
17
+ * It needs `wake/1` in `paired-capabilities` on both sides. The VAPID key pair belongs to that one subscription,
18
+ * so sharing its private half lets a contact post to that subscription and nothing else. Rotating it (a new
19
+ * subscription, new tokens) is how the contact's app revokes everyone it no longer shares with.
20
+ */
21
+ export { WAKE_SESSION_CAPABILITY as WAKE_CAPABILITY } from "./pairedCapabilities.js";
22
+ export declare const WAKE_FRAME = "paired-wake";
23
+ /** At most one wake-up per contact in this long. A burst of messages is one push. */
24
+ export declare const WAKE_INTERVAL_MS: number;
25
+ /** A wake-up that has not reached the phone within this is no use: the push service may drop it. */
26
+ export declare const WAKE_TTL_SECONDS: number;
27
+ /** The VAPID subject push services ask for: who to contact about abuse. The project, never a person. */
28
+ export declare const WAKE_SUBJECT = "https://ghostly.tools";
29
+ /** What a contact shares: its push subscription, the key pair it was made with, and its token for this chat. */
30
+ export interface WakeTarget extends PushTarget {
31
+ vapid: VapidKeys;
32
+ token: string;
33
+ }
34
+ export type WakeFrame = {
35
+ t: typeof WAKE_FRAME;
36
+ w: {
37
+ e: string;
38
+ p: string;
39
+ a: string;
40
+ vp: string;
41
+ vk: string;
42
+ k: string;
43
+ } | null;
44
+ };
45
+ /** A fresh per-contact token: 16 random bytes, base64url. */
46
+ export declare function newWakeToken(): string;
47
+ export declare function wakeFrame(target: WakeTarget | null): WakeFrame;
48
+ /**
49
+ * What a `paired-wake` frame says: the contact's target, null when it stopped sharing, or undefined when the frame
50
+ * is malformed (then it says nothing, and what the contact said before stands). The endpoint must be an https
51
+ * push service on a public host name, and the key pair must be a pair.
52
+ */
53
+ export declare function parseWakeFrame(frame: Record<string, unknown>): WakeTarget | null | undefined;
54
+ /**
55
+ * What a wake-up is for: a message waits, or a call does (the caller rings until the contact's app is live, then
56
+ * calls). The receiving app picks its own words for each; the push says nothing more.
57
+ */
58
+ export type WakeKind = "message" | "call";
59
+ /** At most one call wake-up per contact in this long: a caller who tries again at once is not a new push. */
60
+ export declare const WAKE_CALL_INTERVAL_MS = 30000;
61
+ /** How long a caller waits for the woken contact's app to come live before giving up. */
62
+ export declare const WAKE_CALL_WAIT_MS = 60000;
63
+ /** A call wake-up is useless once the caller stopped waiting: the push service may drop it after this. */
64
+ export declare const WAKE_CALL_TTL_SECONDS = 60;
65
+ /** The wake-up's plaintext: the contact's token for this chat, and whether it is for a call. Nothing else. */
66
+ export declare function wakePayload(token: string, kind?: WakeKind): Uint8Array;
67
+ /**
68
+ * A wake-up as the receiving service worker reads it: the token and its kind; null for anything else. `device`: one of
69
+ * the person's own devices asks this one to open for a handoff (WISP 06 § Push and the phone, `{"wake":1,"k":…,"d":1}`).
70
+ * The flag alone proves nothing: the worker believes it only for a token it gave one of its own devices.
71
+ */
72
+ export declare function readWake(text: string | null | undefined): {
73
+ token: string;
74
+ kind: WakeKind | "device";
75
+ } | null;
76
+ /** A device wake-up is useless once the device that asked stopped waiting for its handoff. */
77
+ export declare const DEVICE_WAKE_TTL_SECONDS: number;
78
+ /**
79
+ * The request that wakes another of the person's devices for a handoff (WISP 06 § Push and the phone): sent as a
80
+ * wake-up to a contact is, with body `{"wake":1,"k":"<token>","d":1}`, where the token is the one that device gave this
81
+ * one on their device link. Throws `WebPushError` when the target cannot be used.
82
+ */
83
+ export declare function deviceWakeRequest(target: WakeTarget, now?: number): PushRequest;
84
+ /** The token a wake-up carries; null for anything else. */
85
+ export declare function readWakePayload(text: string | null | undefined): string | null;
86
+ /** The request that wakes the contact. Throws `WebPushError` when the target cannot be used. */
87
+ export declare function wakeRequest(target: WakeTarget, now?: number, kind?: WakeKind): PushRequest;
88
+ /** One wake-up per contact per `WAKE_INTERVAL_MS`. Kept in memory: a restart may send one more, never a flood. */
89
+ export declare class WakeLimiter {
90
+ private readonly interval;
91
+ private readonly last;
92
+ constructor(interval?: number);
93
+ /** Whether a wake-up to `contact` may go now; if so, it counts as sent. */
94
+ take(contact: string, now?: number): boolean;
95
+ /** The contact answered (it is live again): the next time it is away, it may be woken at once. */
96
+ reset(contact: string): void;
97
+ }
98
+ /**
99
+ * What a push relay is asked (Settings → Network → Push relay): a browser page may not post to a push service
100
+ * itself (the services answer without CORS), so it can hand the finished request to a relay the person chose,
101
+ * which posts it as it is. The relay learns what the push service learns, plus this device's address.
102
+ *
103
+ * POST <relay> {"endpoint":"https://…","headers":{"Authorization":"vapid …",…},"body":"<base64url>"}
104
+ */
105
+ export declare function relayRequest(request: PushRequest): {
106
+ endpoint: string;
107
+ headers: Record<string, string>;
108
+ body: string;
109
+ };
@@ -0,0 +1,107 @@
1
+ import type { PairedTransport } from "./pairedTransports.js";
2
+ /**
3
+ * How far a first pairing got, as one side can know it. Shared by the engine (which measures it) and
4
+ * the UI (which shows it), the way a group join's stages are (`GroupJoinStage`).
5
+ */
6
+ /** Who this side is: the one who made the invite, or the one who joined with it. */
7
+ export type PairingRole = "inviter" | "joiner";
8
+ /**
9
+ * The stages, in the order they come. `publishing`: the inviter is putting its invite on the network.
10
+ * `waiting`: the inviter waits for someone to read it. `resolving`: the joiner is looking the invite up
11
+ * (relay, then DHT). `knocking`: this side sent its offer. `answering`: this side is answering the other's
12
+ * offer. `connecting`: offer and answer met; the transport is coming up. `live`: the chat is open.
13
+ * `on-dht`: the contact is pinned over the DHT and no transport is up (yet); the chat carries text on the DHT
14
+ * while layer 1 is retried in the background (WISP 400). `failed`: only what the DHT cannot get past (`reason`:
15
+ * `key-mismatch`, `rejected`, `publish`, `offline`); the engine tries again by itself when `retryable`. On a first pairing the joiner knocks and the inviter answers; an inviter that sees a joiner
16
+ * from before that rule knocks itself after a grace, so either role can be at either.
17
+ */
18
+ export type PairingStage = "publishing" | "waiting" | "resolving" | "knocking" | "answering" | "connecting" | "live" | "on-dht" | "failed";
19
+ /**
20
+ * Why a pairing is `on-dht` (WISP 400): `no-common-transport` (the two apps share none), `transport` (every
21
+ * attempt failed), `chosen` (either side chose DHT only), `waiting` (pinned over the DHT first; still trying).
22
+ */
23
+ export type PairingOnDhtReason = "no-common-transport" | "transport" | "chosen" | "waiting";
24
+ /**
25
+ * Why an attempt failed, in a word the UI has words for. `publish`: this side could not publish
26
+ * (discovery unreachable). `timeout`: the offer was not answered in time. `transport`: offer and answer
27
+ * met but no connection came up. `rejected`: the authenticated session failed, or a signal was forged or
28
+ * unauthenticated (never retried). `key-mismatch`: the contact's key is not the one saved (never retried).
29
+ * `offline`: this side went offline. `taken`: a joiner whose inviter answers someone else, who used the same invite
30
+ * first (the inviter's envelopes are sealed to that one); it holds until an envelope of the inviter's reads again.
31
+ */
32
+ export type PairingFailureReason = "publish" | "timeout" | "transport" | "rejected" | "key-mismatch" | "offline" | "taken";
33
+ export interface PairingProgress {
34
+ role: PairingRole;
35
+ stage: PairingStage;
36
+ /** When this stage began (ms since the epoch). */
37
+ since: number;
38
+ /** When the pairing began: the invite was made, or joined (ms since the epoch). */
39
+ startedAt: number;
40
+ /** Connection attempts so far, from 1. A failed attempt is followed by the next one. */
41
+ attempt: number;
42
+ /** A short technical note (an error message, or a code), when there is one: the UI shows it behind an ⓘ, untranslated. */
43
+ detail?: string;
44
+ /** When `stage` is `failed` or `on-dht`: why, and whether the engine tries again on its own. */
45
+ reason?: PairingFailureReason | PairingOnDhtReason;
46
+ retryable?: boolean;
47
+ /** The contact's packet was seen (they are on the network); their offer or answer is what is awaited. */
48
+ peerSeen?: boolean;
49
+ /** `connecting` and `live`: the transport coming up, or in use. */
50
+ transport?: PairedTransport;
51
+ /**
52
+ * `publishing`: the relays' request budget (`REQUESTS_PER_MINUTE`) holds this side's first packet back; it goes out
53
+ * once the budget frees a request, about then (ms since the epoch).
54
+ */
55
+ relayWaitUntil?: number;
56
+ }
57
+ /**
58
+ * Keeps one side's `PairingProgress` from what the link reports, and says when it changed. Stops at
59
+ * `live`: what happens to a paired chat afterwards is its connection state, not its pairing.
60
+ */
61
+ export declare class PairingTracker {
62
+ private readonly changed;
63
+ private readonly now;
64
+ progress: PairingProgress;
65
+ private peerSeen;
66
+ /** An attempt is open from its offer until it ends (live, failed, or torn down). */
67
+ private attemptOpen;
68
+ private attempts;
69
+ /** The contact was pinned over the DHT: stream attempts that fail leave the pairing `on-dht`, not `failed`. */
70
+ private dhtPinned;
71
+ constructor(role: PairingRole, startedAt: number, changed: (progress: PairingProgress) => void, now?: () => number);
72
+ /**
73
+ * Live, or stopped by a security rejection (a key mismatch, a forged or refused session), or by an invite someone else
74
+ * took: nothing moves it after (the last one only `untaken`).
75
+ */
76
+ get done(): boolean;
77
+ /** This side's packet is on the network (its first, or the one after a publish that failed). */
78
+ published(): void;
79
+ /** This side's first packet waits for the relays' request budget, which frees one at `until`: said, still `publishing`. */
80
+ heldBack(until: number): void;
81
+ /** The contact's packet was seen: they are on the network. */
82
+ sawPeer(): void;
83
+ offerSent(): void;
84
+ offerReceived(): void;
85
+ answerSent(): void;
86
+ answerReceived(): void;
87
+ live(transport?: PairedTransport): void;
88
+ failed(reason: PairingFailureReason, retryable: boolean, detail?: string): void;
89
+ /**
90
+ * The contact was pinned over the DHT: nothing to show yet (a stream attempt is usually a moment away or under
91
+ * way), but from now on a stream that fails ends the pairing `on-dht`, not back between attempts.
92
+ */
93
+ pinnedOverDht(): void;
94
+ /**
95
+ * The contact is pinned over the DHT (its first-contact envelope verified first), or the chat is kept there:
96
+ * the pairing ends `on-dht`, and later attempts only count until one goes `live`.
97
+ */
98
+ onDht(reason: PairingOnDhtReason): void;
99
+ /** The inviter's envelope reads again after `taken` (that one was forged by someone holding the invite): still trying. */
100
+ untaken(): void;
101
+ /** The attempt ended without a word (the connection went away before the session was ready). */
102
+ reset(): void;
103
+ private attempt;
104
+ /** The stage this side is at between attempts. */
105
+ private idle;
106
+ private set;
107
+ }