@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,60 @@
1
+ import type { LinkParams } from "./invite.js";
2
+ /**
3
+ * The cryptography of the `group-mesh/1` profile (WISP 900 / 902 group mesh).
4
+ *
5
+ * One random 32-byte **epoch secret** per membership state. It never travels in
6
+ * the clear: the committer seals it to each member of the new roster with an
7
+ * ephemeral X25519 key against the member's Ed25519 member key. From it come
8
+ * the message key of the epoch and the key of the confirmation tag that binds
9
+ * the secret to its commit. Messages are XChaCha20-Poly1305 with the epoch
10
+ * message key and the message header as associated data, and are signed by
11
+ * the sender's member key, since the message key alone is shared by everyone.
12
+ *
13
+ * This is not MLS: there is no ratchet tree, member keys are static for the
14
+ * life of the group, and the only source of post-compromise security is a
15
+ * fresh random secret that a removed member is never sent.
16
+ */
17
+ export declare const GROUP_PROFILE: "group-mesh/1";
18
+ /** The keys of one epoch, from its secret. */
19
+ export declare function epochKeys(secret: Uint8Array, groupId: string, epoch: number): {
20
+ message: Uint8Array;
21
+ confirm: Uint8Array;
22
+ };
23
+ export declare function newEpochSecret(): Uint8Array;
24
+ export interface SealedSecret {
25
+ e: string;
26
+ n: string;
27
+ c: string;
28
+ }
29
+ /** The epoch secret for one member: an ephemeral X25519 exchange against the member's Ed25519 key. */
30
+ export declare function sealSecret(recipientZ32: string, secret: Uint8Array, aad: string): SealedSecret;
31
+ /** Null when the box was not sealed to this seed with this associated data. */
32
+ export declare function openSecret(mySeed: Uint8Array, myZ32: string, sealed: SealedSecret, aad: string): Uint8Array | null;
33
+ /**
34
+ * Something for one member only, from another, inside a frame the whole group carries (`group-community/1`
35
+ * pair payloads: payments between two members relayed by hubs). The key mixes an ephemeral X25519 exchange
36
+ * against the recipient's member key with the static exchange between sender and recipient: only the
37
+ * recipient can open it, only the sender (or the recipient) can have made it, and a later leak of the
38
+ * sender's seed alone opens nothing. The associated data binds it to the frame that carries it.
39
+ */
40
+ export declare function sealPair(senderSeed: Uint8Array, senderZ32: string, recipientZ32: string, plaintext: Uint8Array, aad: string): SealedSecret;
41
+ /** Null unless `senderZ32` sealed it to this seed with this associated data. */
42
+ export declare function openPair(mySeed: Uint8Array, myZ32: string, senderZ32: string, sealed: SealedSecret, aad: string): Uint8Array | null;
43
+ /** Text under the epoch message key, bound to its header. */
44
+ export declare function encryptText(messageKey: Uint8Array, aad: string, text: string): {
45
+ n: string;
46
+ c: string;
47
+ };
48
+ export declare function decryptText(messageKey: Uint8Array, aad: string, nonceB64: string, boxB64: string): string | null;
49
+ /** Proves the committer holds the secret the commit distributes: HMAC of the commit's untagged hash. */
50
+ export declare function confirmationTag(confirmKey: Uint8Array, untaggedHashHex: string): string;
51
+ export declare function confirmationMatches(confirmKey: Uint8Array, untaggedHashHex: string, tag: string): boolean;
52
+ export declare function sha256Hex(data: Uint8Array): string;
53
+ /**
54
+ * The pairwise link two members of a group run between them, derived by both
55
+ * from the X25519 secret of their member keys and nothing else: rendezvous
56
+ * identities for each side and the symmetric key of their discovery records.
57
+ * No third party, the admin included, can compute it; a member who left keeps
58
+ * only the edges it was part of, and those are closed by the remaining side.
59
+ */
60
+ export declare function edgeParams(groupId: string, mySeed: Uint8Array, myZ32: string, peerZ32: string): LinkParams;
@@ -0,0 +1,67 @@
1
+ import { type GroupMention } from "./groupMentions.js";
2
+ import { type StatusCard } from "./statusCards.js";
3
+ /**
4
+ * Editing a sent text in a group (WISP 902 § Edits, both profiles). As in a 1:1 chat (WISP 401 § Edits), the author says
5
+ * the whole new text of one of its own messages with an edit number of its own per message, and the highest number
6
+ * wins whatever order edits arrive in. A group has no receipts: the author says an edit to every member it can, and
7
+ * again later (a private group: when an edge opens; a community: its members catch up from each other).
8
+ *
9
+ * - A private group (`group-mesh/1`) sends a `group-edit` frame of its own over each edge, sealed under the key of the
10
+ * epoch the message was sent in and signed by its author (`GroupSession.sendEdit`).
11
+ * - A community (`group-community/1`) sends an application frame through the group, sealed and signed like any payload,
12
+ * so every hub carries it and a member who was away gets it with the catch-up:
13
+ *
14
+ * { "x": { "t": "edit", "id": <message id>, "v": 3, "ts": 1790000000000, "text": "Done: 12 of 12", "m"?: [mentions], "sc"?: {card} } }
15
+ *
16
+ * `sc` is the status card of this version (WISP 405 · Status Cards); an edit with one may be numbered up to
17
+ * `STATUS_CARD_LIMITS.edits`, one without only up to `MAX_EDITS_PER_MESSAGE`.
18
+ *
19
+ * Older apps drop both: a mesh session ignores a `t` it does not know, a community app the `x` frames it does not know.
20
+ */
21
+ export declare const GROUP_EDIT_FRAME = "group-edit";
22
+ export declare const COMMUNITY_EDIT_FRAME = "edit";
23
+ /** One edit of a group message: the message's id in the group, its edit number, when it was made, the whole new text, its mentions. */
24
+ export interface GroupEdit {
25
+ id: string;
26
+ /** The edit number, 1 for the first edit (`MAX_EDITS_PER_MESSAGE` at most). */
27
+ e: number;
28
+ ts: number;
29
+ /** The whole new text. */
30
+ m: string;
31
+ /** Places of the new text that name members. */
32
+ k?: GroupMention[];
33
+ /** The status card of this version (WISP 405 · Status Cards). */
34
+ sc?: StatusCard;
35
+ }
36
+ /** An edit as a group hands it to the engine: `sender` is the member it is authenticated as. */
37
+ export interface GroupIncomingEdit extends GroupEdit {
38
+ sender: string;
39
+ }
40
+ /** The text bound of a group edit, as a message's: 16 KiB of UTF-8. */
41
+ export declare const GROUP_EDIT_TEXT_BYTES: number;
42
+ /** A private group's message id (`<sender>:<epoch>:<seq>`), split; null when it is not one. */
43
+ export declare function meshMessageRef(id: string): {
44
+ s: string;
45
+ e: number;
46
+ n: number;
47
+ } | null;
48
+ /** Whose message a community's id names (`<sender>:<epoch>:<commit>:<seq>`); null when it is not one. */
49
+ export declare function communityMessageAuthor(id: string): string | null;
50
+ /** A text an edit may carry: trimmed, not empty, within the bound. */
51
+ export declare function validEditText(text: unknown): text is string;
52
+ /** The `x` frame a community edit travels as. */
53
+ export declare function communityEditFrame(edit: GroupEdit): Record<string, unknown>;
54
+ /**
55
+ * The edit a community `x` frame says, from `sender` (whom the group authenticated it as), or null when it is not a
56
+ * valid edit of one of the sender's own messages. Mentions that do not hold are left out, never the edit; a community
57
+ * names no one as everyone.
58
+ */
59
+ export declare function parseCommunityEdit(frame: Record<string, unknown>, sender: string): GroupEdit | null;
60
+ /**
61
+ * The mentions of an edited text: the places the message named that are still there, found by their words (the text
62
+ * around them may have changed, or their order), and those `added` while editing. Where two overlap, `added` wins.
63
+ */
64
+ export declare function carryMentions(before: {
65
+ text: string;
66
+ mentions?: readonly GroupMention[];
67
+ }, after: string, added: readonly GroupMention[], everyone: boolean): GroupMention[];
@@ -0,0 +1,61 @@
1
+ import { type Identity } from "./identity.js";
2
+ import type { LinkParams } from "./invite.js";
3
+ import type { GhostRecord } from "./pkarr.js";
4
+ /**
5
+ * A group's public entry link (`group-entry/1`, WISP 902 § Entry link): one
6
+ * address the admin can hand to anyone, so people who are not their contacts
7
+ * can join, without a contact chat and without saying who they are.
8
+ *
9
+ * The link names the group and an **entry key** of the admin's, made for the
10
+ * link and nothing else. From those two, everyone holding the link derives
11
+ * the same **knock identity**: a Pkarr key whose seed is known to every
12
+ * holder, where a joiner leaves its fresh member key. The admin's app reads
13
+ * it; for every knock it opens an **entry session**, a paired link derived like
14
+ * a group edge from the entry key and the joiner's member key and pinned to
15
+ * both, and runs the ordinary admission over it (invite, accept, welcome).
16
+ * The joiner's trust anchor is the entry key the link named: whoever holds
17
+ * its seed is the admin who must admit it.
18
+ *
19
+ * A link is a bearer capability. Anyone who has it can join while it is on;
20
+ * the admin turns it off, or replaces it, and the old one stops working.
21
+ */
22
+ export declare const GROUP_ENTRY_PROFILE: "group-entry/1";
23
+ /** A knock older than this is not answered: the joiner republishes while it waits. */
24
+ export declare const KNOCK_TTL_MS: number;
25
+ /** Knocks a record keeps: joiners share one Pkarr packet, so it holds the latest few. */
26
+ export declare const MAX_KNOCKS = 6;
27
+ export interface GroupEntryLink {
28
+ /** The group id. */
29
+ g: string;
30
+ /** The admin's entry key (z-base-32 Ed25519), made for this link. */
31
+ host: string;
32
+ }
33
+ export interface Knock {
34
+ /** The joiner's member key for this group. */
35
+ key: string;
36
+ /** When the joiner last said it is waiting (ms). */
37
+ ts: number;
38
+ }
39
+ /** `group1/<group id>/<entry key>` */
40
+ export declare function encodeGroupEntryLink(link: GroupEntryLink): string;
41
+ /** Where the link opens the web app: its join route. */
42
+ export declare function groupEntryUrl(origin: string, link: GroupEntryLink): string;
43
+ /** A pasted link, a `/join/…` path or the bare code; null when it is none of them. */
44
+ export declare function decodeGroupEntryLink(input: string): GroupEntryLink | null;
45
+ /** The Pkarr identity every holder of the link can publish knocks under. */
46
+ export declare function knockIdentity(link: GroupEntryLink): Identity;
47
+ /**
48
+ * The knocks under the knock identity, sealed with a key from the link: a
49
+ * relay sees an opaque value on a key it cannot tie to the group.
50
+ */
51
+ export declare function knockRecords(link: GroupEntryLink, knocks: Knock[]): GhostRecord[];
52
+ /** Knocks that open with the link's key and are well formed; anything else is nobody. */
53
+ export declare function readKnocks(link: GroupEntryLink, records: GhostRecord[]): Knock[];
54
+ /** The knocks to publish: mine refreshed, others' still fresh, newest last, at most `MAX_KNOCKS`. */
55
+ export declare function mergeKnocks(existing: Knock[], mine: Knock, now?: number): Knock[];
56
+ /**
57
+ * The entry session between the admin's entry key and a joiner's member key:
58
+ * the same derivation as a group edge, under a salt of its own, so it can
59
+ * never be confused with an edge of the same group.
60
+ */
61
+ export declare function entryParams(link: GroupEntryLink, mySeed: Uint8Array, myZ32: string, peerZ32: string): LinkParams;
@@ -0,0 +1,106 @@
1
+ import { type ImageMeta } from "./image.js";
2
+ import { type VideoMeta } from "./video.js";
3
+ import { type VoiceMeta } from "./voice.js";
4
+ /**
5
+ * Files and voice messages in groups (WISP 503 · Group Files). A file is announced as a group message carrying its
6
+ * description; its bytes go over `files/3` between two members, from a member that holds it to one that asks for it.
7
+ * The limits below are the profile's first numbers, kept in one place so they are easy to change.
8
+ */
9
+ export declare const GROUP_FILE_LIMITS: {
10
+ /** The largest file a group takes. */
11
+ readonly maxBytes: number;
12
+ /** A file this size or smaller is fetched without asking (voice messages always are, up to `VOICE_LIMITS`). */
13
+ readonly autoBytes: number;
14
+ /** What a device keeps of a group's files it fetched without asking; past it, every file is asked about. */
15
+ readonly autoBytesPerGroup: number;
16
+ /** Bytes of group files a device serves to others in a day, when serving is on. */
17
+ readonly serveBytesPerDay: number;
18
+ /** Transfers a holder serves at once, all groups together. */
19
+ readonly serveAtOnce: 3;
20
+ /** File announcements a member sends to one group in a minute. */
21
+ readonly announcePerMinute: 8;
22
+ /** File announcements of one member of a group fetched by themselves in `announceWindowMs`; past it, kept for a Download. */
23
+ readonly announceTaken: 30;
24
+ readonly announceWindowMs: number;
25
+ /** Holders remembered per file. */
26
+ readonly holders: 8;
27
+ /**
28
+ * Message ids a `group-have` named before their message came (a member back from away hears who holds what as its
29
+ * catch-up begins), remembered with their holders for when it does.
30
+ */
31
+ readonly heardAhead: 256;
32
+ /** Message ids in one `group-have`. */
33
+ readonly haveIds: 32;
34
+ /** A private group's `group-have` goes on an edge at most this often; a community's, from a member, every `communityHaveEveryMs`. */
35
+ readonly haveEveryMs: 10000;
36
+ readonly communityHaveEveryMs: 60000;
37
+ /**
38
+ * How long a want waits for an offer before the next holder is asked; a transfer that does not move for as long is
39
+ * left for the next holder too.
40
+ */
41
+ readonly wantWaitMs: 30000;
42
+ /** A file session closes this long after its last transfer ends. */
43
+ readonly sessionIdleMs: 60000;
44
+ /** File sessions opening at once, and open at once, all groups together. */
45
+ readonly sessionsOpening: 2;
46
+ readonly sessionsOpen: 4;
47
+ /** The longest file name and type kept from a description. */
48
+ readonly nameChars: 255;
49
+ readonly mimeChars: 255;
50
+ };
51
+ /** The `paired-groups` version an app announces when it takes group files: it answers wants and takes `group-have`. */
52
+ export declare const GROUP_VERSION_FILES = 6;
53
+ /**
54
+ * The frames of WISP 503 § Getting the bytes, on an edge between two apps that announced `GROUP_VERSION_FILES`:
55
+ * `group-want {g, id}` asks a holder for the file of message `id`; `group-want-no {g, id, why}` is a holder's no;
56
+ * `group-have {g, ids}` says which files a member keeps (in a community, an application frame `{t, ids}` instead).
57
+ */
58
+ export declare const GROUP_WANT_FRAME = "group-want";
59
+ export declare const GROUP_WANT_NO_FRAME = "group-want-no";
60
+ export declare const GROUP_HAVE_FRAME = "group-have";
61
+ export type GroupWantRefusal = "gone" | "busy" | "refused";
62
+ export declare const isGroupMessageId: (value: unknown) => value is string;
63
+ /** A `group-want` of group `groupId`: the message whose file is asked for, or null. */
64
+ export declare function readGroupWant(value: unknown, groupId: string): {
65
+ id: string;
66
+ } | null;
67
+ /** A holder's `group-want-no` of group `groupId`, or null. A reason this app does not know reads as `busy`. */
68
+ export declare function readGroupWantNo(value: unknown, groupId: string): {
69
+ id: string;
70
+ why: GroupWantRefusal;
71
+ } | null;
72
+ /**
73
+ * The message ids of a `group-have`: of group `groupId` on an edge, or (no `groupId`) a community's application frame.
74
+ * At most `haveIds` message ids; a frame with more, or anything else, is null.
75
+ */
76
+ export declare function readGroupHave(value: unknown, groupId?: string): string[] | null;
77
+ /** A group file's description as the author's app puts it in the message (WISP 503 § The announcement). */
78
+ export interface GroupFileMeta {
79
+ name: string;
80
+ mime: string;
81
+ size: number;
82
+ /** SHA-256 of the file, base64url: what every receiver checks the stored bytes against. */
83
+ d: string;
84
+ voice?: VoiceMeta;
85
+ video?: VideoMeta;
86
+ image?: ImageMeta;
87
+ }
88
+ /**
89
+ * A description read from the wire, cleaned: the name made a display name (never a path), the type untrusted, the
90
+ * size within the group limit, the digest the right shape. A malformed voice, video or picture description is dropped
91
+ * on its own and the file is still a file; anything else malformed is no file at all (null), and the text shows.
92
+ */
93
+ export declare function readGroupFileMeta(value: unknown): GroupFileMeta | null;
94
+ /**
95
+ * The text an announcement carries when its author wrote no caption: what an app without group files shows instead
96
+ * of the file. English, as wire text is; an app that knows the file shows the file, not this line.
97
+ */
98
+ export declare function groupFileFallback(file: Pick<GroupFileMeta, "name" | "size" | "voice" | "video">): string;
99
+ /**
100
+ * Whether a device fetches a file by itself (WISP 503 § Automatic and asked downloads): a voice message always, any
101
+ * other file up to `autoBytes` while what it took that way from the group stays within `autoBytesPerGroup`.
102
+ */
103
+ export declare function fetchesByItself(file: Pick<GroupFileMeta, "size" | "voice">, keptAutomatically: number, limits?: {
104
+ autoBytes: number;
105
+ autoBytesPerGroup: number;
106
+ }): boolean;
@@ -0,0 +1,61 @@
1
+ import { type Hub } from "./communityRendezvous.js";
2
+ /**
3
+ * Hubs in a private (mesh) group (WISP 902 · Group Mesh § Hubs). Up to `threshold` members a group is a full mesh, as
4
+ * before. Past it, members that stay online (the Desktop app and the CLI, or members the admin pins) become **hubs**:
5
+ * they keep edges with every other hub and with the members that ask them, and pass on every frame they take. The
6
+ * other members keep edges with `hubsPerMember` hubs only. Frames are author-signed and sealed under the epoch key, and
7
+ * hubs are members, so what a hub passes on is what any member hands on in a catch-up (§ Catch-up): it can withhold a
8
+ * frame, never read more than it could already, alter or forge one.
9
+ *
10
+ * Where hubs are found is the community profile's machinery (`communityRendezvous.ts`): a sealed Pkarr **beacon**
11
+ * listing them, and a **lobby** per hub where a member asks for an edge. The community derives both from the secret its
12
+ * link carries; a private group has no such secret, so they derive from a rendezvous secret of the **current epoch**
13
+ * (`meshRendezvous`). The beacon moves with every commit, and someone removed cannot read or write the next one.
14
+ */
15
+ export declare const MESH_HUBS: {
16
+ /** Members up to which a group stays a full mesh, whatever hubs there are. */
17
+ readonly threshold: 16;
18
+ /** Hubs a member keeps edges with, when there are that many: one to spare, so losing a hub loses nothing. */
19
+ readonly hubsPerMember: 2;
20
+ /** Hubs listed at most (the beacon's own bound). */
21
+ readonly maxHubs: 8;
22
+ /** Members one hub holds before members prefer another: hubs with room first, a full one rather than none. */
23
+ readonly hubCapacity: 48;
24
+ /** Members the admin pins, and excludes, at most. */
25
+ readonly pinned: 8;
26
+ readonly excluded: 32;
27
+ };
28
+ /** The `paired-groups` version an app announces when it takes part in a mesh group's hubs (it may pass frames on). */
29
+ export declare const GROUP_VERSION_HUBS = 4;
30
+ /**
31
+ * The epoch's rendezvous secret, which `beaconKeys` and `lobbyKeys` take as the community takes its link's: HKDF-SHA-256
32
+ * of the epoch secret, salted by the group id and the epoch, under a label of its own (it can never be the message key).
33
+ */
34
+ export declare function meshRendezvous(epochSecret: Uint8Array, groupId: string, epoch: number): string;
35
+ /** What the admin says about hubs, in the group's metadata (`hubs` in the body): members pinned as hubs, and excluded. */
36
+ export interface MeshHubPolicy {
37
+ pin: string[];
38
+ no: string[];
39
+ }
40
+ export declare const NO_HUB_POLICY: MeshHubPolicy;
41
+ /** A policy as the body carries it: distinct member keys, within the bounds, none both pinned and excluded. Null when it is not one. */
42
+ export declare function parseHubPolicy(raw: unknown): MeshHubPolicy | null;
43
+ /** The policy as the body writes it: nothing when it says nothing. */
44
+ export declare function wireHubPolicy(policy: MeshHubPolicy): MeshHubPolicy | undefined;
45
+ /**
46
+ * Whether a member may be a hub: in the roster, not excluded, and either pinned by the admin or on an app that stays
47
+ * online (`staysOnline`, which only the member's own app knows; others go by what the beacon says).
48
+ */
49
+ export declare function mayBeHub(key: string, policy: MeshHubPolicy, inRoster: (key: string) => boolean, staysOnline: boolean): boolean;
50
+ /**
51
+ * The hubs of the beacon a member counts on: fresh, in the roster, not excluded, not itself. Everyone filters the same
52
+ * way, so a member the admin excluded, or someone removed, who lists itself anyway is listed for nobody.
53
+ */
54
+ export declare function meshHubs(hubs: Hub[], me: string, policy: MeshHubPolicy, inRoster: (key: string) => boolean, now?: number): Hub[];
55
+ /**
56
+ * The hubs a member keeps edges with: `hubsPerMember` of them, by rendezvous rank for this member, so the members
57
+ * spread over the hubs and a hub that goes moves only its own members. First hubs with room that republished lately,
58
+ * then full ones (a hub keeps an edge with every member, so a full one is only a busier one), then hubs that may be
59
+ * gone (their app closed; they stay listed a while), and hubs to `avoid` (they did not take me) last.
60
+ */
61
+ export declare function pickMeshHubs(me: string, hubs: Hub[], now?: number, avoid?: ReadonlySet<string>): string[];
@@ -0,0 +1,27 @@
1
+ /** A place in the text that names a member: `k` their member key ("*": everyone), `o`/`l` in Unicode code points. */
2
+ export interface GroupMention {
3
+ k: string;
4
+ o: number;
5
+ l: number;
6
+ }
7
+ /** Everyone in the group (a private group's admin only; never in a community). */
8
+ export declare const MENTION_EVERYONE = "*";
9
+ export declare const MENTION_LIMITS: {
10
+ /** Mentions in one message. A longer list is refused whole. */
11
+ readonly count: 16;
12
+ /** Code points of one mention in the text, its "@" included. */
13
+ readonly chars: 65;
14
+ };
15
+ /**
16
+ * The mentions of a message as a receiver (or the sender) takes them: at most `count` of them, each naming a
17
+ * member key (or everyone, when `everyone` allows it), at a place of the text that starts with "@" and holds no
18
+ * line break or control character, in order and not overlapping. An entry that is none of that is dropped; a list
19
+ * longer than the bound is dropped whole.
20
+ */
21
+ export declare function validMentions(raw: unknown, text: string, everyone: boolean): GroupMention[];
22
+ /** Whether a message's mentions name this member (by key, or everyone). */
23
+ export declare function mentionsMember(mentions: readonly GroupMention[] | undefined, key: string): boolean;
24
+ /** The bytes a list of mentions adds to a message, as JSON: counted against the text's bound. */
25
+ export declare function mentionsBytes(mentions: readonly GroupMention[]): number;
26
+ /** Only the wire fields, in a fixed order (what the sender seals). */
27
+ export declare const wireMentions: (mentions: readonly GroupMention[]) => GroupMention[];
@@ -0,0 +1,162 @@
1
+ import { type MeshHubPolicy } from "./groupHubs.js";
2
+ /**
3
+ * A group's metadata (WISP 902 § Metadata): what the group looks like, beside who is in it: its
4
+ * name and its picture. It is not in the membership chain, so apps that know nothing of it keep
5
+ * verifying the chain as before and drop the frame that carries it.
6
+ *
7
+ * The admin signs a **statement**: the group, a commit of the chain (`e`, `h`) the admin was the
8
+ * admin of, a revision `r`, and the SHA-256 of the **body**, the metadata itself as JSON. The body
9
+ * is the whole metadata: a field left out is unset, so `{}` removes the picture and gives the group
10
+ * back the name it had when this member got in (`groupDisplayName`). It travels in a
11
+ * `group-meta` frame, encrypted under the message key of an epoch the recipient holds (`k`), so
12
+ * someone taken out of the group cannot read what comes after, and any member can hand it on under
13
+ * a later epoch without the admin: the signature covers the body's hash, not its box.
14
+ *
15
+ * Which statement a member keeps is the rule of each profile (the signer is the current admin; a
16
+ * later commit wins, then a higher revision), in `GroupSession` and `CommunitySession`.
17
+ */
18
+ /**
19
+ * Longest picture (data URL) a group may have: less than a profile picture may be (`MAX_AVATAR_LENGTH`),
20
+ * so the frame that carries it, sealed and in base64url, stays within the 60 KiB an edge takes.
21
+ * What Ghostly makes (128×128) is a few kilobytes.
22
+ */
23
+ export declare const MAX_GROUP_PICTURE_LENGTH = 40000;
24
+ /** Longest name the admin may give a group, in characters (code points), as a nickname (`MAX_NICK_LENGTH`). */
25
+ export declare const MAX_GROUP_NAME_LENGTH = 64;
26
+ /** And in UTF-8 bytes. */
27
+ export declare const MAX_GROUP_NAME_BYTES = 256;
28
+ /** Longest body, in UTF-8 bytes: a picture and room for little else. */
29
+ export declare const MAX_GROUP_META_BODY = 42000;
30
+ /** What the body may say. Every field is optional; one left out is unset. */
31
+ export interface GroupMetaBody {
32
+ /** The group's name, as `groupName` accepts it. Left out: the name the group had when this member got in. */
33
+ name?: string;
34
+ /** The group's picture: a square JPEG data URL, as `sanitizeAvatar` accepts it. */
35
+ pic?: string;
36
+ /** Private groups: members the admin pins as hubs, and excludes (WISP 902 · Group Mesh § Hubs). Apps from before ignore it. */
37
+ hubs?: MeshHubPolicy;
38
+ }
39
+ export interface GroupMetaStatement {
40
+ g: string;
41
+ /** The commit the admin signs under: its epoch (index in the chain) and hash. */
42
+ e: number;
43
+ h: string;
44
+ /** Revision: higher wins under the same commit. */
45
+ r: number;
46
+ by: string;
47
+ ts: number;
48
+ /** SHA-256 (hex) of the body's UTF-8 bytes. */
49
+ d: string;
50
+ sig: string;
51
+ }
52
+ /** A statement with its body, as a member keeps it. */
53
+ export interface GroupMeta extends GroupMetaStatement {
54
+ /** The body, exactly as signed (JSON). */
55
+ body: string;
56
+ }
57
+ /**
58
+ * `group-meta` on an edge. `k` names the epoch whose message key seals the body: an epoch
59
+ * number in `group-mesh/1`, a commit hash in `group-community/1` (whose frames also carry `v: 2`).
60
+ */
61
+ export interface GroupMetaFrame extends GroupMetaStatement {
62
+ t: "group-meta";
63
+ v?: 2;
64
+ k: number | string;
65
+ nn: string;
66
+ c: string;
67
+ }
68
+ /**
69
+ * A group's name as the admin gives it and every member shows it: any run of whitespace (a newline,
70
+ * a tab) one space, invisible and direction-changing characters dropped, trimmed. Undefined when it
71
+ * is not a string, nothing visible is left, or it is longer than `MAX_GROUP_NAME_LENGTH` characters
72
+ * or `MAX_GROUP_NAME_BYTES` bytes: a name that does not hold is refused, never cut into another one.
73
+ */
74
+ export declare function groupName(raw: unknown): string | undefined;
75
+ /** The body for a name and a picture (or neither). Throws on a name or picture Ghostly would not show. */
76
+ export declare function encodeGroupMetaBody(body: GroupMetaBody): string;
77
+ /**
78
+ * A body as received: null when it is not JSON, too large, or its picture is not one Ghostly shows. Unknown fields
79
+ * are ignored, and so is a name that does not hold (`groupName`): the group keeps its first name, the picture shows.
80
+ */
81
+ export declare function parseGroupMetaBody(body: string): GroupMetaBody | null;
82
+ /** The admin's signature on a body under commit `h` (epoch `e`). */
83
+ export declare function signGroupMeta(fields: {
84
+ g: string;
85
+ e: number;
86
+ h: string;
87
+ r: number;
88
+ ts: number;
89
+ }, body: string, seed: Uint8Array, by: string): GroupMeta;
90
+ /** The statement's shape, from a frame or storage; null when anything is off. */
91
+ export declare function parseGroupMetaStatement(raw: unknown): GroupMetaStatement | null;
92
+ /** Whether `by` signed this statement. */
93
+ export declare function verifyGroupMetaSignature(s: GroupMetaStatement): boolean;
94
+ /** The frame that carries a statement and its body, sealed under the message key of epoch `k`. */
95
+ export declare function wrapGroupMeta(meta: GroupMeta, k: number | string, messageKey: Uint8Array, community?: boolean): GroupMetaFrame;
96
+ /** The frame's statement and its key reference, before anything is opened; null when malformed. */
97
+ export declare function parseGroupMetaFrame(raw: unknown): {
98
+ statement: GroupMetaStatement;
99
+ k: number | string;
100
+ nn: string;
101
+ c: string;
102
+ } | null;
103
+ /**
104
+ * The body of a parsed frame, with the key of its epoch `k`: it must open, hash to what was signed
105
+ * and be metadata Ghostly accepts. The signature is checked separately (`verifyGroupMetaSignature`).
106
+ */
107
+ export declare function openGroupMeta(frame: {
108
+ statement: GroupMetaStatement;
109
+ k: number | string;
110
+ nn: string;
111
+ c: string;
112
+ }, messageKey: Uint8Array): {
113
+ meta: GroupMeta;
114
+ body: GroupMetaBody;
115
+ } | null;
116
+ /** Is `a` later than `b`: signed under a later commit, or a higher revision under the same one. */
117
+ export declare function groupMetaNewer(a: {
118
+ e: number;
119
+ r: number;
120
+ }, b: {
121
+ e: number;
122
+ r: number;
123
+ } | undefined): boolean;
124
+ /**
125
+ * The revision of the next statement signed under `epoch`: one past the held statement's under the same epoch, else 1.
126
+ * Counting on from a statement of an earlier epoch would let a former admin who signed the highest safe revision leave
127
+ * every later admin with a revision no member accepts.
128
+ */
129
+ export declare function nextGroupMetaRevision(before: {
130
+ e: number;
131
+ r: number;
132
+ } | undefined, epoch: number): number;
133
+ /** What a sync frame says of the metadata a member holds (`e.r`, "" for none): old apps send nothing, and get nothing. */
134
+ export declare const groupMetaTag: (meta: {
135
+ e: number;
136
+ r: number;
137
+ } | undefined) => string;
138
+ export declare function parseGroupMetaTag(tag: unknown): {
139
+ e: number;
140
+ r: number;
141
+ } | undefined | null;
142
+ /** What a kept statement's body says, `{}` for none. */
143
+ export declare function groupMetaBody(meta: GroupMeta | undefined): GroupMetaBody;
144
+ /** The picture a kept statement's body names, if it is one Ghostly shows. */
145
+ export declare function groupMetaPicture(meta: GroupMeta | undefined): string | undefined;
146
+ /**
147
+ * The name members see: the one the admin's statement gives, else the name the group had when this member got in
148
+ * (its creation, or the invitation and welcome that let them in). That first name is also what apps from before
149
+ * names show, and what a member shows until the statement reaches them.
150
+ */
151
+ export declare function groupDisplayName(meta: GroupMeta | undefined, first: string): string;
152
+ /** What a new statement changed that members see (a line in the history); `null` for a field now unset. */
153
+ export interface GroupMetaChange {
154
+ name?: string | null;
155
+ picture?: string | null;
156
+ }
157
+ /**
158
+ * The name and picture that differ between two statements; null when neither does (hubs alone, or the same body signed
159
+ * again). With `first` (the name the group had when this member got in), a name is a change only when the name shown
160
+ * changes: a joiner's welcome already gave the name the statement then brings, and a new admin signs it again.
161
+ */
162
+ export declare function groupMetaChange(before: GroupMeta | undefined, after: GroupMeta, first?: string): GroupMetaChange | null;