@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,111 @@
1
+ /** Local wallet contract. Capability support is never authorization to spend. */
2
+ export type PaymentMethod = "cashu" | "arkade" | "usdt" | "bark" | "bitcoin" | "fedimint" | "spark";
3
+ export type PaymentNetwork = "bitcoin" | "signet" | "testnet" | "mutinynet" | "regtest" | "cashu-test" | "ethereum" | "sepolia" | "evm-local";
4
+ /**
5
+ * Real money, or test coins: what every wallet is, whatever chain it runs on. A payment never crosses from one
6
+ * to the other: a test wallet never settles a request for real money, nor the reverse.
7
+ */
8
+ export type WalletNetwork = "mainnet" | "testnet";
9
+ export declare const WALLET_NETWORKS: readonly WalletNetwork[];
10
+ /** Bitcoin and Ethereum carry real money; every other chain of a payment target is a test network. */
11
+ export declare const walletNetworkOf: (network: PaymentNetwork | string) => WalletNetwork;
12
+ export declare const isWalletNetwork: (value: unknown) => value is WalletNetwork;
13
+ /**
14
+ * The `provider` of an on-chain target. Anyone can pay a Bitcoin address from any wallet, so the payee
15
+ * names no service; which wallet pays is the payer's own choice (its active on-chain source).
16
+ */
17
+ export declare const ONCHAIN_PROVIDER = "onchain";
18
+ export type IntentState = "pending" | "submitted" | "settled" | "failed" | "unknown" | "cancelled";
19
+ export interface PaymentTarget {
20
+ method: PaymentMethod;
21
+ network: PaymentNetwork;
22
+ provider: string;
23
+ asset: "BTC" | "USDT" | "TEST-USDT";
24
+ unit: "sat" | "token-base";
25
+ chainId?: number;
26
+ token?: string;
27
+ decimals?: number;
28
+ issuedAt?: number;
29
+ address: string;
30
+ expiresAt: number;
31
+ }
32
+ export interface PaymentReview extends PaymentTarget {
33
+ id: string;
34
+ requestId?: string;
35
+ linkId?: string;
36
+ payee: string;
37
+ /** What the payment is for, as the payer wrote it (at most 140 characters). */
38
+ memo?: string;
39
+ amount: number;
40
+ fee: number;
41
+ feeCap: number;
42
+ createdAt: number;
43
+ /** When it was approved (claimed for spending): how old an attempt whose outcome is unknown is, across a reload. */
44
+ submittedAt?: number;
45
+ state: IntentState;
46
+ txid?: string;
47
+ error?: string;
48
+ /** A refused Cashu send whose ecash came back: what came back, and the fee the mint kept for taking it in. */
49
+ returned?: {
50
+ amount: number;
51
+ fee: number;
52
+ };
53
+ evm?: {
54
+ from: string;
55
+ nonce: number;
56
+ gasLimit: string;
57
+ maxFeePerGas: string;
58
+ maxPriorityFeePerGas: string;
59
+ confirmations: number;
60
+ };
61
+ /**
62
+ * Parked (WISP 06 § Forced takeover): an attempt that holds signed bytes or a signed transaction, found unfinished by
63
+ * a copy of the profile started from older state (a forced takeover, a restored backup). It is never broadcast again
64
+ * nor reconciled by broadcast: it waits for the person.
65
+ */
66
+ parked?: true;
67
+ }
68
+ export interface PaymentAdapter<Prepared = unknown> {
69
+ method: PaymentMethod;
70
+ prepare(target: PaymentTarget, amount: number, feeCap: number): Promise<{
71
+ fee: number;
72
+ prepared: Prepared;
73
+ evm?: PaymentReview["evm"];
74
+ }>;
75
+ execute(review: PaymentReview, prepared: Prepared, persist?: () => Promise<void>): Promise<PaymentExecution>;
76
+ reconcile(review: PaymentReview, prepared: Prepared, persist?: () => Promise<void>): Promise<PaymentExecution>;
77
+ /** A review cancelled before approval: give back what `prepare` reserved (locked coins). Nothing was spent. */
78
+ release?(review: PaymentReview, prepared: Prepared): Promise<void>;
79
+ }
80
+ export interface PaymentExecution {
81
+ txid?: string;
82
+ settled: boolean;
83
+ pending?: boolean;
84
+ failed?: boolean;
85
+ error?: string;
86
+ }
87
+ /** Only use before signing/broadcasting, when no spend could have happened. */
88
+ export declare class PaymentPreflightError extends Error {
89
+ }
90
+ export declare const ETHEREUM_USDT = "0xdAC17F958D2ee523a2206206994597C13D831ec7";
91
+ /** Each chain's public RPC, which needs no key: the token wallet's defaults, and the `provider` its requests name. */
92
+ export declare const USDT_PUBLIC_RPC: {
93
+ readonly ethereum: "https://ethereum.publicnode.com";
94
+ readonly sepolia: "https://ethereum-sepolia-rpc.publicnode.com";
95
+ };
96
+ /** Test networks for the token wallet and their chain IDs. Their tokens are worthless and not issued by Tether. */
97
+ export declare const EVM_TEST_CHAINS: {
98
+ readonly sepolia: 11155111;
99
+ readonly "evm-local": 31337;
100
+ };
101
+ /** Aave's Sepolia test USDT (6 decimals): anyone can mint it from Aave's faucet, so a test needs only Sepolia ETH. */
102
+ export declare const SEPOLIA_TEST_USDT = "0xaA8E23Fb1079EA71e0a56F48a2aA51851D8433D0";
103
+ /** Aave's public test-token faucet on Sepolia: `mint(token, to, amount)`, open to anyone who pays the gas. */
104
+ export declare const SEPOLIA_TEST_USDT_FAUCET = "0xC959483DBa39aa9E78757139af0e9a2EDEb3f42D";
105
+ /** What one "Get test USDT" asks for: 1,000 TEST-USDT (6 decimals). */
106
+ export declare const TEST_USDT_FAUCET_AMOUNT = 1000000000;
107
+ export declare function parsePaymentAmount(value: string, decimals: number): number;
108
+ export declare function formatPaymentAmount(value: number | string, decimals?: number): string;
109
+ export declare function assertTokenUnits(amount: number): void;
110
+ export declare function assertWholeSats(amount: number): void;
111
+ export declare function validatePaymentTarget(value: unknown, now?: number): PaymentTarget;
@@ -0,0 +1,34 @@
1
+ /**
2
+ * Payment URIs for a wallet that is not Ghostly: what a QR code shows and what a `lightning:` or
3
+ * `bitcoin:` link opens. Building them is all this does; whether the payment arrives is watched by the
4
+ * payee's own source, never assumed from the link having been opened.
5
+ *
6
+ * - `lightning:<invoice>` ([BOLT 11](https://github.com/lightning/bolts/blob/master/11-payment-encoding.md)).
7
+ * - `bitcoin:<address>?amount=<btc>&lightning=<invoice>` ([BIP 21](https://github.com/bitcoin/bips/blob/master/bip-0021.mediawiki)),
8
+ * with the `lightning` parameter of the unified QR convention when an invoice exists too.
9
+ * - `bitcoin:?ark=<address>&amount=<btc>` for an Ark address, the BIP 21 form Ark wallets read.
10
+ */
11
+ export type PaymentUriInput = {
12
+ kind: "lightning";
13
+ invoice: string;
14
+ } | {
15
+ kind: "bitcoin";
16
+ address: string;
17
+ amountSat?: number;
18
+ label?: string;
19
+ message?: string;
20
+ lightning?: string;
21
+ } | {
22
+ kind: "ark";
23
+ address: string;
24
+ amountSat?: number;
25
+ };
26
+ /** Whole sats as the decimal BTC amount BIP 21 wants (`21` → `0.00000021`), never in exponent form. */
27
+ export declare function satsToBtc(sats: number): string;
28
+ /** The URI to open in another wallet. Throws on an input that cannot be one. */
29
+ export declare function paymentUri(input: PaymentUriInput): string;
30
+ /**
31
+ * What to put in the QR code: a `lightning:` URI in upper case, so the code uses the smaller alphanumeric
32
+ * mode every Lightning wallet reads; anything with characters outside that mode as it is.
33
+ */
34
+ export declare function qrText(uri: string): string;
@@ -0,0 +1,97 @@
1
+ import type { WireEndpoint } from "./frames.js";
2
+ /**
3
+ * Payments between two linked peers. Ghostly does not move money itself: it
4
+ * carries payment requests, in-band payments such as ecash tokens, and
5
+ * receipts over the data link, and a platform wallet executes them.
6
+ *
7
+ * Vocabulary and identifiers follow Pubky's Paykit so that publishing the same
8
+ * endpoints through Paykit later is a change of transport, not of model:
9
+ * an endpoint is an identifier plus a payload, an amount is decimal text plus
10
+ * an asset.
11
+ */
12
+ export declare const ENDPOINT: {
13
+ /** Payload: a BOLT11 invoice. */
14
+ readonly bolt11: "btc-lightning-bolt11";
15
+ /**
16
+ * Payload in a request: JSON `{ "mints": ["https://…"] }`, the mints the
17
+ * payee accepts ecash from. Payload in a payment: a `cashuB…` token.
18
+ */
19
+ readonly cashu: "cashu";
20
+ readonly arkade: "btc-arkade/1";
21
+ /** Second's Ark (Bark). Payload in a request: a payment target; in a payment: a receipt hint. */
22
+ readonly bark: "btc-bark/1";
23
+ readonly usdt: "usdt-erc20/1";
24
+ /** On-chain Bitcoin. Payload in a request: a payment target (a fresh address); in a payment: a receipt hint `{ txid }`. */
25
+ readonly bitcoin: "btc-onchain/1";
26
+ /**
27
+ * Fedimint ecash. Payload in a request: JSON `{ "federations": ["<federation id>", …] }`, the federations the
28
+ * payee has joined and takes ecash from. Payload in a payment: the notes themselves (out-of-band notes, a
29
+ * bearer string only the federation that issued them redeems).
30
+ */
31
+ readonly fedimint: "fedimint-ecash/1";
32
+ /**
33
+ * Spark, wallet to wallet. Payload in a request: a payment target whose address is a Spark invoice made for
34
+ * that request; in a payment: a receipt hint `{ id }` (the payer's transfer id).
35
+ */
36
+ readonly spark: "btc-spark/1";
37
+ };
38
+ export interface PaymentAmount {
39
+ /** Decimal text; whole numbers for `sat`. */
40
+ value: string;
41
+ asset: string;
42
+ }
43
+ export interface PaymentRequest {
44
+ id: string;
45
+ timestamp: number;
46
+ amount: PaymentAmount;
47
+ memo?: string;
48
+ endpoints: WireEndpoint[];
49
+ /** The ask this request answers, when the contact asked to pay (see {@link PaymentAsk}). */
50
+ ask?: string;
51
+ /** Real money or test coins: only a wallet of this network pays it. Absent from older apps. */
52
+ network?: "mainnet" | "testnet";
53
+ }
54
+ /**
55
+ * "I want to pay you this much this way": sent by a payer who has no address to pay to (Ark, USDT).
56
+ * The payee's app answers with an ordinary payment request carrying `ask`, which the payer
57
+ * then reviews and approves like any other.
58
+ */
59
+ export interface PaymentAsk {
60
+ id: string;
61
+ timestamp: number;
62
+ amount: PaymentAmount;
63
+ method: "arkade" | "usdt" | "bark" | "bitcoin" | "fedimint" | "spark";
64
+ memo?: string;
65
+ /** The network the payer pays from. Absent from older apps. */
66
+ network?: "mainnet" | "testnet";
67
+ }
68
+ export interface Payment {
69
+ id: string;
70
+ timestamp: number;
71
+ requestId?: string;
72
+ amount: PaymentAmount;
73
+ memo?: string;
74
+ endpoint: WireEndpoint;
75
+ }
76
+ export interface PaymentResult {
77
+ /** Id of the payment or request this is about. */
78
+ id: string;
79
+ ok: boolean;
80
+ /** Amount credited when it differs from the amount sent. */
81
+ credited?: string;
82
+ error?: string;
83
+ /**
84
+ * On a request (`ok` false): its payee closed it for good, and a payment made to it now is lost. Only the payee of a
85
+ * request says it; the payer stops offering to pay it.
86
+ */
87
+ closed?: boolean;
88
+ }
89
+ export declare function cashuRequestPayload(mints: string[]): string;
90
+ /** Mints named by a `cashu` endpoint of a request. Anything malformed yields none. */
91
+ export declare function parseCashuRequestPayload(payload: string): string[];
92
+ /** A Fedimint federation id: 32 bytes, lowercase hex. */
93
+ export declare const isFederationId: (value: unknown) => value is string;
94
+ export declare function fedimintRequestPayload(federations: string[]): string;
95
+ /** Federations named by a `fedimint-ecash/1` endpoint of a request. Anything malformed yields none. */
96
+ export declare function parseFedimintRequestPayload(payload: string): string[];
97
+ export declare function findEndpoint(endpoints: WireEndpoint[], identifier: string): string | undefined;
@@ -0,0 +1,98 @@
1
+ import { type RingEvidence } from './pubkyRing.js';
2
+ export type ProofAdapter = 'nostr' | 'pubky-import' | 'keet-import' | 'pubky-ring' | 'pubky-storage';
3
+ export declare const PROOF_ADAPTERS: ProofAdapter[];
4
+ export declare const proofCapability: (adapter: ProofAdapter) => string;
5
+ export declare const isProofAdapter: (value: unknown) => value is ProofAdapter;
6
+ export interface ProofScope {
7
+ subject: string;
8
+ audience: string;
9
+ context: string;
10
+ session: string;
11
+ }
12
+ export interface ProofChallenge extends ProofScope {
13
+ adapter: ProofAdapter;
14
+ externalKey: string;
15
+ nonce: string;
16
+ issuedAt: number;
17
+ expiresAt: number;
18
+ }
19
+ export interface NostrProofEvent {
20
+ id: string;
21
+ pubkey: string;
22
+ created_at: number;
23
+ kind: number;
24
+ tags: string[][];
25
+ content: string;
26
+ sig: string;
27
+ }
28
+ export interface ImportedProof {
29
+ id: string;
30
+ scheme: 'pubky-import/1' | 'keet-import/1';
31
+ signature: string;
32
+ }
33
+ export interface StorageProof {
34
+ scheme: 'pubky-storage/1';
35
+ id: string;
36
+ folder: string;
37
+ }
38
+ export type StorageProofReader = (key: string, path: string) => Promise<string>;
39
+ export type ProofEvidence = NostrProofEvent | ImportedProof | RingEvidence | StorageProof;
40
+ export declare const STORAGE_LIFETIME = 600;
41
+ export declare const STORAGE_ROOT = "/pub/ghostly.app/proofs/";
42
+ export declare function storageProof(c: ProofChallenge, folder: string): Promise<StorageProof>;
43
+ export declare function storageProofPath(e: StorageProof): `/pub/${string}`;
44
+ export declare function storageProofBody(c: ProofChallenge, e: StorageProof): string;
45
+ export interface ProofRecord {
46
+ challenge: ProofChallenge;
47
+ event: ProofEvidence;
48
+ verifiedAt: number;
49
+ status: 'pending' | 'accepted' | 'withdrawal-pending' | 'withdrawn';
50
+ }
51
+ export interface ProofLedger {
52
+ incoming: ProofChallenge[];
53
+ outgoing: ProofChallenge[];
54
+ local: ProofRecord[];
55
+ remote: ProofRecord[];
56
+ }
57
+ export declare const emptyProofLedger: () => ProofLedger;
58
+ export interface ProofStorage {
59
+ read(): ProofLedger;
60
+ /** Atomic, durable read-transform-write, preserving other conversation fields. */
61
+ update(change: (ledger: ProofLedger) => ProofLedger): Promise<void>;
62
+ }
63
+ export declare const PROOF_CAPABILITY = "proof-nostr/1";
64
+ export declare function proofHash(text: string): Promise<string>;
65
+ export declare function proofStatement(c: ProofChallenge): string;
66
+ export declare function nostrProofTemplate(c: ProofChallenge): {
67
+ kind: number;
68
+ created_at: number;
69
+ tags: string[][];
70
+ content: string;
71
+ };
72
+ export declare function verifyNostrProof(event: NostrProofEvent, c: ProofChallenge): Promise<void>;
73
+ export declare function validExternalKey(adapter: ProofAdapter, value: string): boolean;
74
+ export declare function importedProof(c: ProofChallenge, signature: Uint8Array): Promise<ImportedProof>;
75
+ export declare function verifyPeerProof(event: ProofEvidence, c: ProofChallenge, readStorage?: StorageProofReader): Promise<void>;
76
+ /** Optional application protocol. All calls require an authenticated, pinned paired channel.
77
+ * A bad external proof never replaces participation authentication or disconnects ordinary chat. */
78
+ export declare class PeerProofs {
79
+ private options;
80
+ private waiting;
81
+ constructor(options: {
82
+ scope(): ProofScope;
83
+ send(frame: object): void;
84
+ storage: ProofStorage;
85
+ supports?(adapter: ProofAdapter): boolean;
86
+ now?: () => number;
87
+ readStorage?: StorageProofReader;
88
+ onError?(error: string): void;
89
+ });
90
+ private now;
91
+ private scope;
92
+ prepare(externalKey: string, adapter?: ProofAdapter): Promise<ProofChallenge>;
93
+ submit(c: ProofChallenge, event: ProofEvidence): Promise<void>;
94
+ withdraw(adapter?: ProofAdapter): Promise<void>;
95
+ resendWithdrawals(): void;
96
+ receive(frame: Record<string, unknown>): Promise<void>;
97
+ stop(): void;
98
+ }
@@ -0,0 +1,73 @@
1
+ /**
2
+ * A pinned message (WISP 400 § Pinned message): one per chat, shown in a bar at the top. Whoever pins says which
3
+ * message (the id both sides know it by, as a reply names it) and a number: the clock in milliseconds, past the pin
4
+ * it replaces. An empty id unpins. The highest number wins, whatever order the frames arrive in, so the last pin wins
5
+ * on every side and a late frame changes nothing. A number further ahead of the receiver's clock than
6
+ * `PIN_CLOCK_SKEW_MS` is refused: clocks drift, but a number past that is the sender's choice, and one near the
7
+ * largest safe integer would leave nobody a higher number to pin or unpin with.
8
+ *
9
+ * A 1:1 chat says it on the live session once both sides list `pin/1` in `paired-capabilities`, and the contact
10
+ * confirms the number it took:
11
+ *
12
+ * {"t":"paired-pin","id":"<message id>","n":1790000000000}
13
+ * {"t":"paired-pinned","n":1790000000000}
14
+ *
15
+ * A private group signs it and passes it over the edges (`group-pin`); a community seals it to the group as an
16
+ * application frame (`pin`). Older apps drop all of these: a `t` they do not know.
17
+ */
18
+ export declare const PIN_FRAME = "paired-pin";
19
+ export declare const PINNED_FRAME = "paired-pinned";
20
+ /** A pin in a private group, signed by the member who pinned, passed on by every member that takes it. */
21
+ export declare const GROUP_PIN_FRAME = "group-pin";
22
+ /** A pin in a community, as an application frame sealed to the group. */
23
+ export declare const COMMUNITY_PIN_FRAME = "pin";
24
+ /**
25
+ * How far ahead of this device's clock a pin's number may be. What a session and a call allow a contact's clock
26
+ * (`RTC_SIGNAL_FUTURE_MS`, `CALL_SIGNAL_FUTURE_MS`): a contact whose clock runs seven minutes ahead pairs, chats and
27
+ * calls, and its pins were dropped, each said again every 30 seconds and never taken.
28
+ */
29
+ export declare const PIN_CLOCK_SKEW_MS: number;
30
+ export declare const PIN_LIMITS: {
31
+ /** Pin frames a receiver takes per window on one chat; the rest are dropped unconfirmed and come again. */
32
+ readonly receive: 10;
33
+ readonly windowMs: 10000;
34
+ /** A pin said on the live session and not confirmed is said again after this long. */
35
+ readonly resendMs: 30000;
36
+ };
37
+ /** A pin as it goes on the wire: the message's id ("" unpins) and the pinner's number. */
38
+ export interface WirePin {
39
+ id: string;
40
+ n: number;
41
+ }
42
+ /**
43
+ * Who may pin in a group. The one place the rule lives (WISP 400 § Pinned message): in a private group any member,
44
+ * in a community only its admin.
45
+ */
46
+ export declare function mayPin(kind: "mesh" | "community", member: string, admin: string | undefined): boolean;
47
+ /**
48
+ * Whether a pin's number holds at `now`: a positive safe integer no further ahead of the clock than
49
+ * `PIN_CLOCK_SKEW_MS`. A kept pin whose number does not hold (taken before receivers checked it) counts as none.
50
+ */
51
+ export declare function pinNumberHolds(n: unknown, now?: number): n is number;
52
+ /**
53
+ * The number for a new pin: the clock, or one past the pin shown now, whichever is higher. Past a shown pin whose
54
+ * number does not hold, the clock: a receiver would refuse one past it.
55
+ */
56
+ export declare function nextPinNumber(current?: number, now?: number): number;
57
+ /**
58
+ * Whether `pin` replaces the chat's pin now: a higher number wins; two pins with the same number (two sides at the
59
+ * same millisecond) are settled by the id, so every side ends on the same one. A shown pin whose number does not hold
60
+ * is replaced by any pin.
61
+ */
62
+ export declare function pinIsNewer(current: WirePin | undefined, pin: WirePin, now?: number): boolean;
63
+ /**
64
+ * A pin as a receiver takes it at `now`, or null: an id of a chat's shape or "" (unpinned), and a number that holds
65
+ * (`pinNumberHolds`). One refused is not confirmed: its sender says it again, and it is taken once the clocks agree.
66
+ */
67
+ export declare function readPin(raw: unknown, now?: number): WirePin | null;
68
+ export declare function pinFrame(pin: WirePin): string;
69
+ export declare function pinnedFrame(n: number): string;
70
+ /** The pin a `paired-pin` frame says, or null when it is malformed. */
71
+ export declare function parsePinFrame(frame: Record<string, unknown>): WirePin | null;
72
+ /** The number a `paired-pinned` frame confirms, or null when it is malformed. */
73
+ export declare function parsePinnedFrame(frame: Record<string, unknown>): number | null;
@@ -0,0 +1,48 @@
1
+ import { type Identity } from "./identity.js";
2
+ /** Mainline DHT (BEP44) caps the value of a mutable item at 1000 bytes. */
3
+ export declare const MAX_DNS_PACKET_BYTES = 1000;
4
+ /** The largest relay payload: a 64-byte signature, an 8-byte timestamp and the largest DNS packet (1072 bytes). */
5
+ export declare const RELAY_PAYLOAD_MAX_BYTES: number;
6
+ /** A label relative to the publisher's key, e.g. `_msgs`. */
7
+ export interface GhostRecord {
8
+ label: string;
9
+ value: string;
10
+ ttl?: number;
11
+ }
12
+ export interface SignedPacket {
13
+ pubKeyZ32: string;
14
+ /** Microseconds since the UNIX epoch; doubles as the BEP44 sequence number. */
15
+ timestampMicros: bigint;
16
+ records: GhostRecord[];
17
+ }
18
+ export declare class PacketTooLargeError extends Error {
19
+ readonly size: number;
20
+ constructor(size: number);
21
+ }
22
+ /** Size of the encoded DNS packet these records would produce. */
23
+ export declare function measureRecords(pubKeyZ32: string, records: GhostRecord[]): number;
24
+ /**
25
+ * Builds the payload Pkarr relays accept on `PUT /<z32 public key>`:
26
+ * `<64 bytes signature><8 bytes big-endian timestamp (µs)><encoded DNS packet>`
27
+ */
28
+ export declare function createRelayPayload(identity: Identity, records: GhostRecord[], timestampMicros?: bigint): Uint8Array;
29
+ /**
30
+ * Signs a DNS packet exactly as given (its own names and flags) into a relay payload. `seq` is the
31
+ * BEP44 sequence number: Ghostly's records use microseconds, a did:dht document seconds.
32
+ */
33
+ export declare function signRelayPayload(identity: Identity, dnsPacket: Uint8Array, seq: bigint): Uint8Array;
34
+ /** Checks a relay payload's size and signature. Returns its sequence number and DNS packet, not decoded. */
35
+ export declare function openRelayPayload(pubKeyZ32: string, payload: Uint8Array): {
36
+ seq: bigint;
37
+ dnsPacket: Uint8Array;
38
+ };
39
+ /** Verifies and decodes a relay payload. Throws if the signature does not match. */
40
+ export declare function parseRelayPayload(pubKeyZ32: string, payload: Uint8Array): SignedPacket;
41
+ /** How far ahead of this clock a packet's time may be and still count as now: clocks drift, not by this much. */
42
+ export declare const PKARR_FUTURE_SKEW_MS: number;
43
+ /**
44
+ * The newer of two signed packets of one key. A packet dated further ahead than `PKARR_FUTURE_SKEW_MS` never wins over
45
+ * one dated now or before: whoever could sign it once (a key several people hold, a clock far off) must not keep every
46
+ * later packet from being taken. Between two of the same kind, the later time wins; on a tie, `known` stays.
47
+ */
48
+ export declare function newerPacket(known: SignedPacket | null | undefined, packet: SignedPacket | null | undefined, now?: number): SignedPacket | null;
@@ -0,0 +1,35 @@
1
+ export interface SvcbRecord {
2
+ /** The owner name, lowercase, without a trailing dot (a Pkarr packet's names end in its key). */
3
+ name: string;
4
+ priority: number;
5
+ /** The target name, lowercase; "" is "." (the owner itself). */
6
+ target: string;
7
+ /** SvcParams by key, raw. */
8
+ params: Map<number, Uint8Array>;
9
+ }
10
+ /** Every SVCB and HTTPS record of a DNS packet, in packet order. Throws on a malformed one. */
11
+ export declare function decodeSvcbRecords(dnsPacket: Uint8Array): SvcbRecord[];
12
+ /** The homeserver a Pubky key's packet names: the z-base-32 key its `_pubky` record points at, or undefined. */
13
+ export declare function pubkyHomeserverOf(dnsPacket: Uint8Array, userZ32: string): string | undefined;
14
+ /** Where a homeserver answers browsers: a public host name and, when its record says so, a port. */
15
+ export interface HomeserverEndpoint {
16
+ host: string;
17
+ port?: number;
18
+ }
19
+ /**
20
+ * The homeserver's web endpoint from its own packet: of the HTTPS/SVCB records at its root, the lowest priority one
21
+ * whose target is a public ICANN host name (not ".", not another Pkarr key, not a name that only works on private
22
+ * networks, which would point a contact's app inward), with its port parameter. Undefined when there is none.
23
+ */
24
+ export declare function homeserverWebEndpoint(dnsPacket: Uint8Array, homeserverZ32: string): HomeserverEndpoint | undefined;
25
+ /**
26
+ * A DNS packet of SVCB/HTTPS records, the way Pkarr stores them (names with the key appended, targets
27
+ * uncompressed). For tests and test services: Ghostly itself never publishes these.
28
+ */
29
+ export declare function encodeSvcbPacket(records: {
30
+ name: string;
31
+ priority: number;
32
+ target: string;
33
+ port?: number;
34
+ type?: 64 | 65;
35
+ }[]): Uint8Array;
@@ -0,0 +1,25 @@
1
+ import type { IdentityStatement } from "./identityProofs.js";
2
+ /**
3
+ * A Pubky identity proof, by publication (WISP 302, docs/wisps/302-pubky.md). Neither Pubky Ring nor Pubky
4
+ * Passport signs arbitrary text: they approve standard Pubky auth requests. So Ghostly asks, through one of them,
5
+ * for write access to ONE fresh folder of the key's homeserver, `/pub/ghostly.app/proofs/<folder>/`, and writes the
6
+ * identity statement there (the #80 statement: the Pubky key authorizes this profile's per-proof key). A contact's
7
+ * app reads the file back, finding the homeserver through the key's own signed PKDNS records (pkdns.ts), never
8
+ * through a host or URL from the proof. The folder is random, so the path says nothing about the profile.
9
+ */
10
+ export declare const PUBKY_PROOF_ROOT = "/pub/ghostly.app/proofs/";
11
+ /** The file is the statement, a few hundred bytes: anything larger is not ours. */
12
+ export declare const PUBKY_PROOF_MAX_BYTES = 1024;
13
+ /** A canonical Pubky key: 52 characters of z-base-32 that decode to 32 bytes and back. */
14
+ export declare function isPubkyKey(value: unknown): value is string;
15
+ /** The z-base-32 key for what a person typed or pasted: the bare key, `pubky<key>`, `pk:<key>` or `pubky://<key>`. */
16
+ export declare function normalizePubkyKey(input: string): string;
17
+ export declare const isPubkyProofFolder: (value: unknown) => value is string;
18
+ /** A fresh folder name: 32 random bytes, hex. One per proof, so two proofs never share a path. */
19
+ export declare const newPubkyProofFolder: () => string;
20
+ /** The only capability Ghostly ever asks for: write access to one proof folder. */
21
+ export declare function pubkyProofCapability(folder: string): `/pub/${string}/:w`;
22
+ /** Where the statement goes: in its folder, named by the statement id. */
23
+ export declare function pubkyProofPath(folder: string, statementId: string): `/pub/${string}`;
24
+ /** The file's exact contents: the statement's one line, nothing added. The verifier compares bytes. */
25
+ export declare const pubkyProofFile: (statement: IdentityStatement) => string;
@@ -0,0 +1,21 @@
1
+ export declare const RING_LIFETIME = 600;
2
+ export interface RingEvidence {
3
+ id: string;
4
+ scheme: 'pubky-ring/1';
5
+ authorization: string;
6
+ signature: string;
7
+ }
8
+ export interface RingClaims {
9
+ iss: string;
10
+ cnf: string;
11
+ aud: 'ghostly-peer-proof/1';
12
+ challenge: string;
13
+ iat: number;
14
+ exp: number;
15
+ }
16
+ export declare function ringClaims(statement: string, issuer: string, delegate: string, issuedAt: number, expiresAt: number): RingClaims;
17
+ export declare function ringAuthorization(claims: RingClaims, seed: Uint8Array): string;
18
+ export declare function verifyRingAuthorization(authorization: string, statement: string, issuer: string, issuedAt: number, expiresAt: number): RingClaims;
19
+ export declare function validRingKey(key: string): boolean;
20
+ export declare function ringEvidence(authorization: string, statement: string, delegatedSeed: Uint8Array): RingEvidence;
21
+ export declare function verifyRingEvidence(e: RingEvidence, statement: string, issuer: string, issuedAt: number, expiresAt: number): void;
@@ -0,0 +1,108 @@
1
+ /**
2
+ * Reactions to messages (WISP 400 § Reactions): one emoji per person per message, like WhatsApp. Whoever reacts says
3
+ * which message (the id both sides know it by, as a reply names it), the emoji, and a number of its own that only
4
+ * grows; an empty emoji takes the reaction back. For each person and message the highest number wins, whatever order
5
+ * the frames arrive in, so a new reaction replaces the old one and a late frame changes nothing.
6
+ *
7
+ * A 1:1 chat says it on the live session once both sides list `react/1` in `paired-capabilities`, and the contact
8
+ * confirms each number it took:
9
+ *
10
+ * {"t":"paired-reaction","id":"<message id>","e":"❤️","n":1790000000000}
11
+ * {"t":"paired-reacted","n":1790000000000}
12
+ *
13
+ * Off the live session they ride on the DHT envelopes (WISP 403 § Reactions). Groups carry them in their own frames
14
+ * (WISP 902 § Reactions). Older apps drop all of these: a `t` they do not know, or a trailing element they skip.
15
+ */
16
+ export declare const REACTION_FRAME = "paired-reaction";
17
+ export declare const REACTED_FRAME = "paired-reacted";
18
+ /** A reaction in a private group, over the edge from the member who reacts (WISP 902 group mesh § Reactions). */
19
+ export declare const GROUP_REACTION_FRAME = "group-react";
20
+ /** A reaction in a community, as an application frame sealed to the group (WISP 903 group community § Reactions). */
21
+ export declare const COMMUNITY_REACTION_FRAME = "reaction";
22
+ /** The quick bar, in order: what most reactions are. Any other emoji comes from the picker. */
23
+ export declare const QUICK_REACTIONS: readonly ["👍", "❤️", "😂", "😮", "😢", "🙏"];
24
+ export declare const REACTION_LIMITS: {
25
+ /** UTF-8 bytes of one emoji: a family or a subdivision flag fits, a run of emoji does not. */
26
+ readonly emojiBytes: 32;
27
+ /**
28
+ * Reaction frames a receiver takes per window on one chat; the rest are dropped unconfirmed and come again. In a
29
+ * group nothing comes again (a community's catch-up hands a frame once), so there the rest wait for the next window.
30
+ */
31
+ readonly receive: 30;
32
+ /** Group members' reactions past a window, kept per group until it has room: as many as a community's store hands back. */
33
+ readonly held: 256;
34
+ /** Reactions a sender says per window on one chat; the newest of each message waits for room. */
35
+ readonly send: 20;
36
+ readonly windowMs: 10000;
37
+ /**
38
+ * A reaction to a message not here yet waits this long for it, at most `buffer` of them per sender in each chat: a
39
+ * member back in a busy group hears every member's latest reactions as their edges open, before the catch-up (over a
40
+ * minute for a full log) brings what they name.
41
+ */
42
+ readonly bufferMs: 300000;
43
+ readonly buffer: 64;
44
+ /** Reactions of this side not confirmed yet, per chat: the oldest is dropped past it. */
45
+ readonly pending: 32;
46
+ /** Reactions one DHT envelope carries at most, room allowing. */
47
+ readonly dht: 8;
48
+ };
49
+ /** One reaction as it goes on the wire: the message's id, the emoji ("" takes it back) and the reactor's number. */
50
+ export interface WireReaction {
51
+ id: string;
52
+ e: string;
53
+ n: number;
54
+ }
55
+ /**
56
+ * The emoji a reaction may carry, in one form (so the same emoji from two apps is one chip), or null when it is not
57
+ * one: exactly one grapheme, made of emoji code points only, with a pictograph in it, at most
58
+ * `REACTION_LIMITS.emojiBytes`. A single pictograph drawn as text by default gets the emoji selector (❤ → ❤️); one
59
+ * drawn as emoji by default loses a redundant one (👍️ → 👍). Sequences keep their selectors as sent.
60
+ */
61
+ export declare function reactionEmoji(raw: unknown): string | null;
62
+ /** A reactor's number: valid on the wire (a positive safe integer). */
63
+ export declare function validReactionNumber(n: unknown): n is number;
64
+ /**
65
+ * The number for this side's next reaction in a chat: the clock in milliseconds, or one past the last, whichever is
66
+ * higher. It only grows, even when the clock goes back.
67
+ */
68
+ export declare function nextReactionNumber(last?: number, now?: number): number;
69
+ /** Whether a reaction numbered `n` replaces what a person's reaction to that message is now. */
70
+ export declare function reactionIsNewer(current: {
71
+ n: number;
72
+ } | undefined, n: number): boolean;
73
+ /**
74
+ * A reaction as a receiver takes it, or null: a message id of a chat's shape (as a reply names it), an emoji that
75
+ * holds or "" (taken back), and a valid number. Anything else says nothing and is not confirmed.
76
+ */
77
+ export declare function readReaction(raw: unknown): WireReaction | null;
78
+ /** Only the wire fields, in a fixed order. */
79
+ export declare const wireReaction: (r: WireReaction) => WireReaction;
80
+ export declare function reactionFrame(r: WireReaction): string;
81
+ export declare function reactedFrame(n: number): string;
82
+ /** The reaction a `paired-reaction` frame says, or null when it is malformed. */
83
+ export declare function parseReactionFrame(frame: Record<string, unknown>): WireReaction | null;
84
+ /** The number a `paired-reacted` frame confirms, or null when it is malformed. */
85
+ export declare function parseReactedFrame(frame: Record<string, unknown>): number | null;
86
+ /**
87
+ * A DHT envelope's reactions (its thirteenth element): `[[id, emoji, n], …]`. What does not hold is skipped, never the
88
+ * envelope; at most `REACTION_LIMITS.dht` are read.
89
+ */
90
+ export declare function readDhtReactions(raw: unknown): WireReaction[];
91
+ /**
92
+ * This side's reactions not confirmed yet, after one more: the newest per message (a new one replaces a pending one
93
+ * for the same message), in the order of their numbers, the oldest dropped past `REACTION_LIMITS.pending`.
94
+ */
95
+ export declare function queueReaction(pending: readonly WireReaction[], reaction: WireReaction): WireReaction[];
96
+ /** A sliding window of `limit` events per `windowMs`: a sender's pace and a receiver's limit. */
97
+ export declare class ReactionWindow {
98
+ private readonly limit;
99
+ private readonly windowMs;
100
+ private readonly now;
101
+ private recent;
102
+ constructor(limit: number, windowMs?: number, now?: () => number);
103
+ /** Counts one now; false (and not counted) when the window is full. */
104
+ take(): boolean;
105
+ /** Milliseconds until the window has room again; 0 when it has room now. */
106
+ wait(): number;
107
+ reset(): void;
108
+ }