@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.
- package/README.md +13 -2
- package/dist/app.js +72 -0
- package/dist/app.js.map +1 -0
- package/dist/core.js +207 -0
- package/dist/core.js.map +1 -0
- package/dist/fakes-JOzOFxn3.js +536 -0
- package/dist/fakes-JOzOFxn3.js.map +1 -0
- package/dist/fakes.js +2 -0
- package/dist/index.js +179 -0
- package/dist/index.js.map +1 -0
- package/dist/keet-identity-key-BLli1rE4.js +76483 -0
- package/dist/keet-identity-key-BLli1rE4.js.map +1 -0
- package/dist/src-BqHTnRWH.js +31296 -0
- package/dist/src-BqHTnRWH.js.map +1 -0
- package/dist/testing.js +330 -0
- package/dist/testing.js.map +1 -0
- package/dist/types/browser/src/engine/paymentAdapters/providers/contractSuite.d.ts +41 -0
- package/dist/types/browser/src/engine/paymentAdapters/providers/lightning.d.ts +103 -0
- package/dist/types/browser/src/engine/paymentAdapters/providers/onchain.d.ts +88 -0
- package/dist/types/browser/src/engine/paymentAdapters/providers/testing.d.ts +89 -0
- package/dist/types/browser/src/engine/paymentAdapters/providers/types.d.ts +151 -0
- package/dist/types/browser/src/plugins/bundled.d.ts +8 -0
- package/dist/types/browser/src/plugins/registry.d.ts +57 -0
- package/dist/types/browser/src/proofs/contract.d.ts +262 -0
- package/dist/types/browser/src/proofs/contractSuite.d.ts +27 -0
- package/dist/types/browser/src/proofs/testing.d.ts +36 -0
- package/dist/types/browser/src/proofs/verify.d.ts +23 -0
- package/dist/types/browser/src/shared/mints.d.ts +50 -0
- package/dist/types/core/src/appBundle.d.ts +173 -0
- package/dist/types/core/src/appStatements.d.ts +142 -0
- package/dist/types/core/src/appStore.d.ts +133 -0
- package/dist/types/core/src/appUpdates.d.ts +88 -0
- package/dist/types/core/src/atprotoIdentity.d.ts +49 -0
- package/dist/types/core/src/atprotoRepo.d.ts +101 -0
- package/dist/types/core/src/avatar.d.ts +19 -0
- package/dist/types/core/src/bip322.d.ts +57 -0
- package/dist/types/core/src/bitcoinAddress.d.ts +5 -0
- package/dist/types/core/src/bitcoinMessage.d.ts +15 -0
- package/dist/types/core/src/bitcoinScript.d.ts +69 -0
- package/dist/types/core/src/bolt11.d.ts +30 -0
- package/dist/types/core/src/bytes.d.ts +11 -0
- package/dist/types/core/src/callSignal.d.ts +232 -0
- package/dist/types/core/src/canonicalJson.d.ts +22 -0
- package/dist/types/core/src/capsRecord.d.ts +234 -0
- package/dist/types/core/src/catchUp.d.ts +45 -0
- package/dist/types/core/src/chatFiles.d.ts +271 -0
- package/dist/types/core/src/clockWatch.d.ts +72 -0
- package/dist/types/core/src/communityRendezvous.d.ts +113 -0
- package/dist/types/core/src/crypto.d.ts +10 -0
- package/dist/types/core/src/datalink.d.ts +187 -0
- package/dist/types/core/src/deviceInvite.d.ts +51 -0
- package/dist/types/core/src/deviceLink.d.ts +70 -0
- package/dist/types/core/src/dhtDelivery.d.ts +407 -0
- package/dist/types/core/src/dhtFiles.d.ts +46 -0
- package/dist/types/core/src/did.d.ts +134 -0
- package/dist/types/core/src/didDht.d.ts +155 -0
- package/dist/types/core/src/directPath.d.ts +63 -0
- package/dist/types/core/src/dns.d.ts +41 -0
- package/dist/types/core/src/domainProofs.d.ts +88 -0
- package/dist/types/core/src/engineErrors.d.ts +91 -0
- package/dist/types/core/src/enroll.d.ts +98 -0
- package/dist/types/core/src/files.d.ts +73 -0
- package/dist/types/core/src/forwards.d.ts +12 -0
- package/dist/types/core/src/frames.d.ts +211 -0
- package/dist/types/core/src/ghostlink.d.ts +1532 -0
- package/dist/types/core/src/groupCommits.d.ts +103 -0
- package/dist/types/core/src/groupCommunity.d.ts +720 -0
- package/dist/types/core/src/groupCrypto.d.ts +60 -0
- package/dist/types/core/src/groupEdits.d.ts +67 -0
- package/dist/types/core/src/groupEntry.d.ts +61 -0
- package/dist/types/core/src/groupFiles.d.ts +106 -0
- package/dist/types/core/src/groupHubs.d.ts +61 -0
- package/dist/types/core/src/groupMentions.d.ts +27 -0
- package/dist/types/core/src/groupMeta.d.ts +162 -0
- package/dist/types/core/src/groupSession.d.ts +728 -0
- package/dist/types/core/src/groupSignals.d.ts +167 -0
- package/dist/types/core/src/groupTyping.d.ts +56 -0
- package/dist/types/core/src/groupWake.d.ts +68 -0
- package/dist/types/core/src/handoff.d.ts +255 -0
- package/dist/types/core/src/http.d.ts +125 -0
- package/dist/types/core/src/identity.d.ts +17 -0
- package/dist/types/core/src/identityProofs.d.ts +243 -0
- package/dist/types/core/src/identityTimeline.d.ts +72 -0
- package/dist/types/core/src/image.d.ts +33 -0
- package/dist/types/core/src/index.d.ts +100 -0
- package/dist/types/core/src/invite.d.ts +128 -0
- package/dist/types/core/src/link.d.ts +353 -0
- package/dist/types/core/src/linkPreview.d.ts +60 -0
- package/dist/types/core/src/linkTrace.d.ts +12 -0
- package/dist/types/core/src/lnurl.d.ts +99 -0
- package/dist/types/core/src/messageTime.d.ts +28 -0
- package/dist/types/core/src/miniApp.d.ts +146 -0
- package/dist/types/core/src/pairedApps.d.ts +151 -0
- package/dist/types/core/src/pairedCalls.d.ts +59 -0
- package/dist/types/core/src/pairedCapabilities.d.ts +101 -0
- package/dist/types/core/src/pairedEdits.d.ts +83 -0
- package/dist/types/core/src/pairedFiles.d.ts +30 -0
- package/dist/types/core/src/pairedHttp.d.ts +15 -0
- package/dist/types/core/src/pairedSession.d.ts +163 -0
- package/dist/types/core/src/pairedSignal.d.ts +17 -0
- package/dist/types/core/src/pairedTransports.d.ts +76 -0
- package/dist/types/core/src/pairedTyping.d.ts +130 -0
- package/dist/types/core/src/pairedWake.d.ts +109 -0
- package/dist/types/core/src/pairingProgress.d.ts +107 -0
- package/dist/types/core/src/paymentIntent.d.ts +111 -0
- package/dist/types/core/src/paymentUri.d.ts +34 -0
- package/dist/types/core/src/payments.d.ts +97 -0
- package/dist/types/core/src/peerProofs.d.ts +98 -0
- package/dist/types/core/src/pins.d.ts +73 -0
- package/dist/types/core/src/pkarr.d.ts +48 -0
- package/dist/types/core/src/pkdns.d.ts +35 -0
- package/dist/types/core/src/pubkyProofs.d.ts +25 -0
- package/dist/types/core/src/pubkyRing.d.ts +21 -0
- package/dist/types/core/src/reactions.d.ts +108 -0
- package/dist/types/core/src/records.d.ts +89 -0
- package/dist/types/core/src/relay.d.ts +459 -0
- package/dist/types/core/src/relayBreaker.d.ts +99 -0
- package/dist/types/core/src/replies.d.ts +41 -0
- package/dist/types/core/src/services.d.ts +35 -0
- package/dist/types/core/src/setUpdate.d.ts +53 -0
- package/dist/types/core/src/signal.d.ts +53 -0
- package/dist/types/core/src/signer.d.ts +13 -0
- package/dist/types/core/src/sparkAddress.d.ts +37 -0
- package/dist/types/core/src/sshsig.d.ts +74 -0
- package/dist/types/core/src/statusCards.d.ts +253 -0
- package/dist/types/core/src/storeForward.d.ts +144 -0
- package/dist/types/core/src/text.d.ts +20 -0
- package/dist/types/core/src/transport.d.ts +158 -0
- package/dist/types/core/src/transportSwitch.d.ts +160 -0
- package/dist/types/core/src/turnRead.d.ts +145 -0
- package/dist/types/core/src/turnRecord.d.ts +165 -0
- package/dist/types/core/src/version.d.ts +9 -0
- package/dist/types/core/src/video.d.ts +44 -0
- package/dist/types/core/src/voice.d.ts +88 -0
- package/dist/types/core/src/webPush.d.ts +58 -0
- package/dist/types/sdk/src/app.d.ts +23 -0
- package/dist/types/sdk/src/core.d.ts +7 -0
- package/dist/types/sdk/src/fakes.d.ts +6 -0
- package/dist/types/sdk/src/index.d.ts +26 -0
- package/dist/types/sdk/src/testing.d.ts +7 -0
- package/dist/types-DvtCy3WB.js +99 -0
- package/dist/types-DvtCy3WB.js.map +1 -0
- package/dist/verify-RjMx7eW6.js +106 -0
- package/dist/verify-RjMx7eW6.js.map +1 -0
- package/package.json +70 -4
|
@@ -0,0 +1,155 @@
|
|
|
1
|
+
import { type NsRecord, type TxtRecord } from "./dns.js";
|
|
2
|
+
import type { Identity } from "./identity.js";
|
|
3
|
+
/**
|
|
4
|
+
* did:dht (the DIF method, https://github.com/decentralized-identity/did-dht/blob/main/spec/spec.md): a W3C DID document written as DNS records into the
|
|
5
|
+
* Pkarr packet of an Ed25519 key, the BEP44 mutable item Ghostly already publishes chats under. This
|
|
6
|
+
* module maps a document to that packet and back (strictly: a malformed packet is an error, never a
|
|
7
|
+
* guess) and resolves a did:dht through Pkarr relays. WISP 310-did-dht describes Ghostly's use.
|
|
8
|
+
*/
|
|
9
|
+
export declare const DID_DHT_PREFIX = "did:dht:";
|
|
10
|
+
/** The TTL the spec recommends: Mainline's default record lifetime. */
|
|
11
|
+
export declare const DID_DHT_TTL = 7200;
|
|
12
|
+
/** The spec version this module writes and the only one it reads (`v=0`). */
|
|
13
|
+
export declare const DID_DHT_VERSION = "0";
|
|
14
|
+
/** A relay answer: 64 bytes of signature, 8 of sequence number, then at most 1000 of DNS packet. */
|
|
15
|
+
export declare const DID_DHT_MAX_PAYLOAD: number;
|
|
16
|
+
export interface DidDhtJwk {
|
|
17
|
+
kty: "OKP" | "EC";
|
|
18
|
+
crv: "Ed25519" | "secp256k1" | "P-256" | "X25519";
|
|
19
|
+
x: string;
|
|
20
|
+
y?: string;
|
|
21
|
+
alg: string;
|
|
22
|
+
kid: string;
|
|
23
|
+
}
|
|
24
|
+
export interface DidDhtVerificationMethod {
|
|
25
|
+
id: string;
|
|
26
|
+
type: "JsonWebKey";
|
|
27
|
+
controller: string;
|
|
28
|
+
publicKeyJwk: DidDhtJwk;
|
|
29
|
+
}
|
|
30
|
+
export interface DidDhtService {
|
|
31
|
+
id: string;
|
|
32
|
+
type: string;
|
|
33
|
+
serviceEndpoint: string[];
|
|
34
|
+
/** Registered extra properties (the spec's registry): which keys sign and encrypt for it. */
|
|
35
|
+
sig?: string | string[];
|
|
36
|
+
enc?: string | string[];
|
|
37
|
+
}
|
|
38
|
+
/** A did:dht document in W3C DID Core JSON: no `@context`, every reference fully qualified. */
|
|
39
|
+
export interface DidDhtDocument {
|
|
40
|
+
id: string;
|
|
41
|
+
controller?: string | string[];
|
|
42
|
+
alsoKnownAs?: string[];
|
|
43
|
+
verificationMethod: DidDhtVerificationMethod[];
|
|
44
|
+
authentication?: string[];
|
|
45
|
+
assertionMethod?: string[];
|
|
46
|
+
keyAgreement?: string[];
|
|
47
|
+
capabilityInvocation?: string[];
|
|
48
|
+
capabilityDelegation?: string[];
|
|
49
|
+
service?: DidDhtService[];
|
|
50
|
+
}
|
|
51
|
+
/** Why a did:dht could not be read: the message is meant for a person. */
|
|
52
|
+
export declare class DidDhtError extends Error {
|
|
53
|
+
readonly code: "invalid-did" | "not-found" | "invalid-signature" | "malformed" | "unreachable";
|
|
54
|
+
constructor(message: string, code: "invalid-did" | "not-found" | "invalid-signature" | "malformed" | "unreachable");
|
|
55
|
+
}
|
|
56
|
+
/** `did:dht:<z-base-32 of the Ed25519 public key>`. */
|
|
57
|
+
export declare function didDhtFromPublicKey(publicKey: Uint8Array): string;
|
|
58
|
+
/** The identity key of a did:dht. Only the exact DID: no path, query or fragment, canonical z-base-32. */
|
|
59
|
+
export declare function didDhtKey(did: string): {
|
|
60
|
+
z32: string;
|
|
61
|
+
publicKey: Uint8Array;
|
|
62
|
+
};
|
|
63
|
+
/**
|
|
64
|
+
* The document of an identity key alone, as the spec's Create step makes it: the key as `#0`, with the
|
|
65
|
+
* four relationships it requires (authentication, assertion, capability invocation and delegation).
|
|
66
|
+
* `alsoKnownAs` adds other identifiers of the same subject (URIs), which the document makes public.
|
|
67
|
+
*/
|
|
68
|
+
export declare function didDhtDocument(publicKey: Uint8Array, options?: {
|
|
69
|
+
alsoKnownAs?: string[];
|
|
70
|
+
}): DidDhtDocument;
|
|
71
|
+
/** RFC 7638 thumbprint: SHA-256 of the required members in lexicographic order. */
|
|
72
|
+
export declare function jwkThumbprint(jwk: Pick<DidDhtJwk, "kty" | "crv" | "x" | "y">): string;
|
|
73
|
+
export interface DidDhtPacketOptions {
|
|
74
|
+
/** Type indexing (`_typ._did.`), integers from the spec's registry. */
|
|
75
|
+
types?: number[];
|
|
76
|
+
/** Authoritative gateways, as NS records of the root name. */
|
|
77
|
+
gateways?: string[];
|
|
78
|
+
/**
|
|
79
|
+
* Other records of the same key. A key has exactly one packet: whatever else it publishes goes in
|
|
80
|
+
* with the document, and the whole must fit the 1000 bytes.
|
|
81
|
+
*/
|
|
82
|
+
extra?: TxtRecord[];
|
|
83
|
+
}
|
|
84
|
+
/**
|
|
85
|
+
* The DNS records of a document, in the spec's layout (names `_did.<ID>.` and `_kN._did.`). The root
|
|
86
|
+
* record comes after the records it names, gateways last: the order @web5/dids writes, and the only one
|
|
87
|
+
* it reads correctly (it resolves `vm`/`auth` references in packet order). Order-free readers don't mind.
|
|
88
|
+
*/
|
|
89
|
+
export declare function didDhtRecords(document: DidDhtDocument, options?: DidDhtPacketOptions): (TxtRecord | NsRecord)[];
|
|
90
|
+
/** The compressed, authoritative DNS packet of a document. Throws `PacketTooLargeError` past 1000 bytes. */
|
|
91
|
+
export declare function encodeDidDhtPacket(document: DidDhtDocument, options?: DidDhtPacketOptions): Uint8Array;
|
|
92
|
+
/**
|
|
93
|
+
* The packet that ends a DID: its root record alone, reading `deactivated`. Resolvers then answer with
|
|
94
|
+
* `deactivated: true` and a document holding the id alone, until the record leaves the DHT.
|
|
95
|
+
*/
|
|
96
|
+
export declare function encodeDidDhtDeactivated(publicKey: Uint8Array): Uint8Array;
|
|
97
|
+
/**
|
|
98
|
+
* The relay payload of a document: its packet, signed by the identity key. `seq` is the BEP44 sequence
|
|
99
|
+
* number, which did:dht defines as the UNIX time in seconds (Ghostly's chat records use microseconds).
|
|
100
|
+
*/
|
|
101
|
+
export declare function signDidDhtPacket(identity: Identity, dnsPacket: Uint8Array, seq: number): Uint8Array;
|
|
102
|
+
export interface DecodedDidDht {
|
|
103
|
+
document: DidDhtDocument;
|
|
104
|
+
/** The root record says `deactivated`: the document holds the id alone. */
|
|
105
|
+
deactivated: boolean;
|
|
106
|
+
/** Type indexing integers (`_typ._did.`), when present. */
|
|
107
|
+
types?: number[];
|
|
108
|
+
}
|
|
109
|
+
/**
|
|
110
|
+
* The document in a did:dht DNS packet. Other records of the key (anything not ending in `_did`) are
|
|
111
|
+
* ignored, and so are did:dht records this version does not know (`_prv`, future ones); everything it
|
|
112
|
+
* does know must be well formed and consistent, or the packet is refused.
|
|
113
|
+
*/
|
|
114
|
+
export declare function decodeDidDhtPacket(did: string, dnsPacket: Uint8Array): DecodedDidDht;
|
|
115
|
+
export interface DidDhtFetchResponse {
|
|
116
|
+
status: number;
|
|
117
|
+
bytes: Uint8Array;
|
|
118
|
+
}
|
|
119
|
+
/** A bounded GET (the identity proofs' `ctx.fetch` is one). */
|
|
120
|
+
export type DidDhtFetch = (url: string, options?: {
|
|
121
|
+
maxBytes?: number;
|
|
122
|
+
signal?: AbortSignal;
|
|
123
|
+
redirect?: "error";
|
|
124
|
+
}) => Promise<DidDhtFetchResponse>;
|
|
125
|
+
export interface ResolveDidDhtOptions {
|
|
126
|
+
fetch: DidDhtFetch;
|
|
127
|
+
/** Pkarr relays (or did:dht gateways, which answer the same GET) to ask in turn. Default: `DEFAULT_RELAYS`. */
|
|
128
|
+
relays?: string[];
|
|
129
|
+
signal?: AbortSignal;
|
|
130
|
+
}
|
|
131
|
+
export interface DidDhtMetadata {
|
|
132
|
+
/** The BEP44 sequence number. */
|
|
133
|
+
versionId: string;
|
|
134
|
+
/** When it was published, from the sequence number. */
|
|
135
|
+
updated: string;
|
|
136
|
+
deactivated?: true;
|
|
137
|
+
types?: number[];
|
|
138
|
+
}
|
|
139
|
+
export interface DidDhtResolution {
|
|
140
|
+
document: DidDhtDocument;
|
|
141
|
+
metadata: DidDhtMetadata;
|
|
142
|
+
/** The relay that answered. */
|
|
143
|
+
relay: string;
|
|
144
|
+
}
|
|
145
|
+
/** A packet opened and decoded: the signature is the identity key's, the document well formed. */
|
|
146
|
+
export declare function openDidDhtPayload(did: string, payload: Uint8Array): DecodedDidDht & {
|
|
147
|
+
seq: bigint;
|
|
148
|
+
};
|
|
149
|
+
/**
|
|
150
|
+
* Resolves a did:dht through Pkarr relays: one GET per relay, in turn, the next only when one has
|
|
151
|
+
* nothing, fails or serves a packet that does not check out. The answer is bounded to a BEP44 item,
|
|
152
|
+
* its signature checked against the DID's key and its records parsed strictly. A deactivated DID
|
|
153
|
+
* resolves (`metadata.deactivated`); everything else that goes wrong throws a `DidDhtError`.
|
|
154
|
+
*/
|
|
155
|
+
export declare function resolveDidDht(did: string, options: ResolveDidDhtOptions): Promise<DidDhtResolution>;
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Whether this device's own WebRTC attempts say that direct connections do not get through its network: a VPN that
|
|
3
|
+
* takes every packet through its tunnel, a firewall that drops UDP, a carrier's NAT. The app cannot see a VPN; it can
|
|
4
|
+
* see that its attempts keep failing the same way, and say so where people look at the connection (the chat's
|
|
5
|
+
* connection panel, Settings → Network). Chats still go live through a relayed transport, or carry short texts on the
|
|
6
|
+
* DHT.
|
|
7
|
+
*
|
|
8
|
+
* What an attempt says (`DataLink` tells, per attempt):
|
|
9
|
+
* - `open`: a WebRTC connection opened (`closed`: that one ended). Direct connections work here, whatever failed before.
|
|
10
|
+
* - `no-public`: the attempt did not connect, and this device had gathered no public candidate for it (none at all, or
|
|
11
|
+
* host addresses only: no STUN server answered). Its own evidence: nothing of the contact's is in it.
|
|
12
|
+
* - `symmetric`: it did not connect, and this device's public address was a different port for each STUN server it
|
|
13
|
+
* asked (`symmetricNat`): its network maps every destination apart, so a contact cannot reach the port it was told.
|
|
14
|
+
* Its own evidence too.
|
|
15
|
+
* - `no-path`: this device's offer was answered, it had public candidates that read as reachable, and no pair
|
|
16
|
+
* connected. The contact may be the one behind the network that blocks; several contacts are this device.
|
|
17
|
+
*
|
|
18
|
+
* The rule, on purpose slow to say yes: no WebRTC connection open now and none opened since, and either
|
|
19
|
+
* `DIRECT_OWN_ATTEMPTS` attempts with this device's own evidence, or attempts that failed with `DIRECT_PEERS`
|
|
20
|
+
* different contacts (a contact who is also a member of a group counts under each key, so two is not enough). One
|
|
21
|
+
* failed dial never shows anything. It clears by itself: on the first connection that opens, when the network changes
|
|
22
|
+
* (`reset`), and once the evidence is older than `DIRECT_EVIDENCE_MS` (a network that changed without the app hearing
|
|
23
|
+
* of it).
|
|
24
|
+
*/
|
|
25
|
+
export type DirectEvidence = "open" | "closed" | "no-public" | "symmetric" | "no-path";
|
|
26
|
+
/** Evidence older than this says nothing about the network now. */
|
|
27
|
+
export declare const DIRECT_EVIDENCE_MS: number;
|
|
28
|
+
/** Attempts with this device's own evidence (`no-public`, `symmetric`) that it takes. */
|
|
29
|
+
export declare const DIRECT_OWN_ATTEMPTS = 2;
|
|
30
|
+
/** Different contacts the attempts must have failed with, whatever their kind. */
|
|
31
|
+
export declare const DIRECT_PEERS = 3;
|
|
32
|
+
export interface DirectFailure {
|
|
33
|
+
peer: string;
|
|
34
|
+
kind: "no-public" | "symmetric" | "no-path";
|
|
35
|
+
at: number;
|
|
36
|
+
}
|
|
37
|
+
/**
|
|
38
|
+
* Whether a local description shows a NAT that maps each destination apart: the app asks several STUN servers from one
|
|
39
|
+
* socket, and a NAT that keeps one mapping answers with one address and port (the browser lists it once). Three ports
|
|
40
|
+
* on one address, not two: a device on two interfaces behind one router (Wi-Fi and a cable) has two.
|
|
41
|
+
*/
|
|
42
|
+
export declare function symmetricNat(sdp: string | undefined | null): boolean;
|
|
43
|
+
/** The rule alone: whether `failures` (every one after the last `open`) say direct connections are blocked at `now`. */
|
|
44
|
+
export declare function directBlocked(failures: readonly DirectFailure[], now: number): boolean;
|
|
45
|
+
export declare class DirectPathWatch {
|
|
46
|
+
private readonly onChange;
|
|
47
|
+
private readonly now;
|
|
48
|
+
private failures;
|
|
49
|
+
/** Contacts a WebRTC connection is open with now. */
|
|
50
|
+
private readonly open;
|
|
51
|
+
private was;
|
|
52
|
+
private timer;
|
|
53
|
+
/** `onChange`: `blocked` changed (evidence came, a connection opened, the network changed, the evidence aged out). */
|
|
54
|
+
constructor(onChange?: (blocked: boolean) => void, now?: () => number);
|
|
55
|
+
/** One WebRTC attempt with `peer` ended this way (or its open connection closed). */
|
|
56
|
+
note(peer: string, evidence: DirectEvidence): void;
|
|
57
|
+
/** The network changed: what failed on the old one says nothing about this one. */
|
|
58
|
+
reset(): void;
|
|
59
|
+
get blocked(): boolean;
|
|
60
|
+
/** Stops the timer that lets the evidence age out. */
|
|
61
|
+
close(): void;
|
|
62
|
+
private settle;
|
|
63
|
+
}
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Minimal DNS wire codec for Pkarr packets. Ghostly publishes TXT records (and,
|
|
3
|
+
* for a did:dht document that names its gateways, NS). Decoding skips every
|
|
4
|
+
* other record type and understands name compression, which the Rust client
|
|
5
|
+
* (simple-dns) emits. `decodeDnsAnswers` hands out any record type raw, for
|
|
6
|
+
* readers of other people's records (Pubky's `_pubky` and homeserver records, pkdns.ts).
|
|
7
|
+
*/
|
|
8
|
+
export interface TxtRecord {
|
|
9
|
+
/** Fully qualified name, e.g. `_msgs.<z32 public key>` */
|
|
10
|
+
name: string;
|
|
11
|
+
value: string;
|
|
12
|
+
ttl: number;
|
|
13
|
+
}
|
|
14
|
+
/** A name server record: `host` is the server's name. */
|
|
15
|
+
export interface NsRecord {
|
|
16
|
+
type: "NS";
|
|
17
|
+
name: string;
|
|
18
|
+
host: string;
|
|
19
|
+
ttl: number;
|
|
20
|
+
}
|
|
21
|
+
/** `authoritative` sets the AA flag, which a did:dht packet must carry. */
|
|
22
|
+
export declare function encodeTxtPacket(records: (TxtRecord | NsRecord)[], options?: {
|
|
23
|
+
authoritative?: boolean;
|
|
24
|
+
}): Uint8Array;
|
|
25
|
+
/** A name at `start` (compressed or not), and where the bytes after it begin. Labels are joined with ".", no trailing dot. */
|
|
26
|
+
export declare function readDnsName(data: Uint8Array, start: number): {
|
|
27
|
+
name: string;
|
|
28
|
+
next: number;
|
|
29
|
+
};
|
|
30
|
+
export declare function decodeTxtPacket(data: Uint8Array): TxtRecord[];
|
|
31
|
+
/** One answer record, undecoded: its rdata starts at `offset` in the packet (names in it may point anywhere before). */
|
|
32
|
+
export interface RawDnsAnswer {
|
|
33
|
+
name: string;
|
|
34
|
+
type: number;
|
|
35
|
+
ttl: number;
|
|
36
|
+
/** Where the rdata starts in the packet. */
|
|
37
|
+
offset: number;
|
|
38
|
+
length: number;
|
|
39
|
+
}
|
|
40
|
+
/** Every answer record of a packet, of any type. Names are decompressed; the rdata is left to the caller. */
|
|
41
|
+
export declare function decodeDnsAnswers(data: Uint8Array): RawDnsAnswer[];
|
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Domain identity proofs (draft WISP 304, docs/wisps/304-domain.md), the pure half.
|
|
3
|
+
*
|
|
4
|
+
* Under WISP 300 a proof authorizes a fresh Ed25519 *proof key* that only this
|
|
5
|
+
* profile holds, through a statement the external identity vouches for. A
|
|
6
|
+
* domain vouches by publishing: a DNS TXT record at `_ghostly.<domain>` or a
|
|
7
|
+
* `/.well-known/ghostly.json` file names the proof key **and the statement id**
|
|
8
|
+
* (SHA-256 of the statement), so the record commits to the exact binding —
|
|
9
|
+
* subject, key, dates and nonce — not just to a key. Sharing with a contact is
|
|
10
|
+
* then the contract's per-contact presentation, signed by the proof key.
|
|
11
|
+
*
|
|
12
|
+
* People who already run NIP-05 can use `/.well-known/nostr.json` instead: its
|
|
13
|
+
* root name `_` must be the very Nostr key that signed the statement.
|
|
14
|
+
*
|
|
15
|
+
* The record names no participation key and no contact. Fetching, DNS over
|
|
16
|
+
* HTTPS and caching live in `@ghostly/browser/proofs/domain`.
|
|
17
|
+
*/
|
|
18
|
+
export type DomainMethod = 'dns' | 'https' | 'nip05';
|
|
19
|
+
/** What a record says: this Ghostly proof key, for this statement. */
|
|
20
|
+
export interface DomainRecord {
|
|
21
|
+
key: string;
|
|
22
|
+
proof: string;
|
|
23
|
+
}
|
|
24
|
+
export declare const DOMAIN_METHODS: readonly DomainMethod[];
|
|
25
|
+
export declare const DNS_LABEL = "_ghostly";
|
|
26
|
+
export declare const WELL_KNOWN_PATH = "/.well-known/ghostly.json";
|
|
27
|
+
export declare const NIP05_PATH = "/.well-known/nostr.json?name=_";
|
|
28
|
+
/** Everything read from a domain is bounded; these match the fetch limits. */
|
|
29
|
+
export declare const DOMAIN_FILE_MAX_BYTES: number;
|
|
30
|
+
export declare const DOMAIN_TXT_MAX_BYTES = 1024;
|
|
31
|
+
export declare const DOMAIN_MAX_RECORDS = 8;
|
|
32
|
+
/**
|
|
33
|
+
* Normalizes what a person typed ("Example.COM.", "https://example.com/") into
|
|
34
|
+
* a lowercase ASCII host name, or throws with a message fit for the UI.
|
|
35
|
+
* Internationalized names become punycode (xn--), the form DNS carries.
|
|
36
|
+
*/
|
|
37
|
+
export declare function normalizeDomain(input: string): string;
|
|
38
|
+
export declare const dnsProofName: (domain: string) => string;
|
|
39
|
+
export declare const wellKnownUrl: (domain: string, method?: "https" | "nip05") => string;
|
|
40
|
+
export declare function validDomainRecord(r: DomainRecord): boolean;
|
|
41
|
+
/** The TXT record value, in the `tag=value; …` style people know from DKIM. */
|
|
42
|
+
export declare function domainTxtRecord(r: DomainRecord): string;
|
|
43
|
+
/** Parses one TXT string. Undefined for anything that is not ours or not exactly
|
|
44
|
+
* well-formed; unknown extra tags are ignored for forward compatibility. */
|
|
45
|
+
export declare function parseDomainTxt(value: string): DomainRecord | undefined;
|
|
46
|
+
/** All records among the TXT strings of `_ghostly.<domain>`; other strings are skipped. */
|
|
47
|
+
export declare function recordsFromTxt(values: string[]): DomainRecord[];
|
|
48
|
+
/** The body of `/.well-known/ghostly.json`. */
|
|
49
|
+
export declare function domainWellKnownFile(records: DomainRecord[]): string;
|
|
50
|
+
/** Records from `ghostly.json`. Throws on a malformed file; [] when it names none. */
|
|
51
|
+
export declare function recordsFromWellKnown(text: string): DomainRecord[];
|
|
52
|
+
/** NIP-05: only the root name `_` speaks for the domain itself. Undefined when absent. */
|
|
53
|
+
export declare function nip05RootKey(text: string): string | undefined;
|
|
54
|
+
export declare const recordsName: (records: DomainRecord[], r: DomainRecord) => boolean;
|
|
55
|
+
export declare const DNS_TYPE: {
|
|
56
|
+
readonly A: 1;
|
|
57
|
+
readonly CNAME: 5;
|
|
58
|
+
readonly TXT: 16;
|
|
59
|
+
readonly AAAA: 28;
|
|
60
|
+
};
|
|
61
|
+
export type DnsType = keyof typeof DNS_TYPE;
|
|
62
|
+
export interface DnsAnswer {
|
|
63
|
+
name: string;
|
|
64
|
+
type: number;
|
|
65
|
+
ttl: number;
|
|
66
|
+
data: Uint8Array;
|
|
67
|
+
}
|
|
68
|
+
export interface DnsResponse {
|
|
69
|
+
/** 0 = NOERROR, 3 = NXDOMAIN; anything else is a failed lookup. */
|
|
70
|
+
rcode: number;
|
|
71
|
+
/** The resolver reports it validated the answer with DNSSEC. */
|
|
72
|
+
authenticated: boolean;
|
|
73
|
+
answers: DnsAnswer[];
|
|
74
|
+
}
|
|
75
|
+
/** A recursive query for one name and type. ID 0, as RFC 8484 recommends for caching;
|
|
76
|
+
* the AD bit asks the resolver to report DNSSEC validation (RFC 6840 §5.7). */
|
|
77
|
+
export declare function encodeDnsQuery(name: string, type: DnsType): Uint8Array;
|
|
78
|
+
/**
|
|
79
|
+
* Decodes a resolver's answer to `encodeDnsQuery(name, type)`. Refuses a reply
|
|
80
|
+
* to another question or a truncated one, and keeps only records of the asked
|
|
81
|
+
* type owned by the name or by the CNAME chain the answer itself follows.
|
|
82
|
+
*/
|
|
83
|
+
export declare function decodeDnsResponse(data: Uint8Array, name: string, type: DnsType): DnsResponse;
|
|
84
|
+
/** The TXT character-strings of one record, joined as RFC 7208 §3.3 does. */
|
|
85
|
+
export declare function txtValue(rdata: Uint8Array): string;
|
|
86
|
+
/** False for loopback, private, link-local, shared (CGNAT), multicast, reserved
|
|
87
|
+
* and unspecified addresses, including IPv4 embedded in IPv6. */
|
|
88
|
+
export declare function isPublicAddress(address: Uint8Array): boolean;
|
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The engine's known errors: a stable code each, and its English text with the values in it. The engine throws
|
|
3
|
+
* `engineError(code, values)`; the text is the one it always wrote, so the CLI and every log keep printing the same.
|
|
4
|
+
* The app's pages get only the text (it crosses the engine's RPC and is kept on payments and operations as a string),
|
|
5
|
+
* and `parseEngineError` finds the code and the values back in it, to say it in the app's language. A text that is
|
|
6
|
+
* none of these (a mint's own words, a provider's) stays as it is.
|
|
7
|
+
*
|
|
8
|
+
* `{name}` in a template is a value: a host or domain (no spaces), a network ("Mainnet" or "Testnet"), a chain's name,
|
|
9
|
+
* an ecash unit ("usd"), or an amount (digits, with the separators of whatever locale wrote it).
|
|
10
|
+
*/
|
|
11
|
+
export declare const ENGINE_ERRORS: {
|
|
12
|
+
readonly mintUnreachable: "Could not reach {host}. Check the address: it should be a Cashu mint.";
|
|
13
|
+
readonly lnurlUnreachable: "Could not reach {host}. It may be down, or not allow web apps to read it (CORS).";
|
|
14
|
+
readonly hostUnreachable: "Could not reach {host}";
|
|
15
|
+
readonly networkUnreachable: "Could not reach the network";
|
|
16
|
+
readonly hostTimedOut: "{host} did not answer in time";
|
|
17
|
+
readonly networkTimedOut: "The network did not answer in time";
|
|
18
|
+
readonly testMintOnMainnet: "This is a test mint, and its sats are worth nothing: add it to a Testnet Cashu wallet";
|
|
19
|
+
readonly realMintOnTestnet: "This mint holds real sats: add it to a Mainnet Cashu wallet";
|
|
20
|
+
readonly mintHoldsSats: "Move your sats out of this mint before removing it";
|
|
21
|
+
readonly lastMint: "This is the last mint of your {network} Cashu wallet: remove the wallet to remove it";
|
|
22
|
+
readonly invalidMintUrl: "That is not a valid mint URL";
|
|
23
|
+
readonly mintNotHttps: "Mints must use https";
|
|
24
|
+
readonly notEnoughSats: "Not enough sats in your wallet";
|
|
25
|
+
readonly noSharedMint: "You share no mint with this contact";
|
|
26
|
+
readonly ecashAlreadySpent: "This ecash was already spent somewhere else";
|
|
27
|
+
readonly ecashBeingReceived: "This ecash is already being received";
|
|
28
|
+
readonly ecashOtherUnit: "This ecash is in {unit}: only sat ecash can be redeemed here";
|
|
29
|
+
readonly reviewedEcashSpent: "The ecash for this payment was already spent somewhere else. Nothing was sent, and your balance now shows what the mint still holds.";
|
|
30
|
+
readonly reviewedSatsGone: "The sats this payment was reviewed with went to another payment. Nothing was sent: review it again.";
|
|
31
|
+
readonly lightningFeeTooHigh: "The Lightning fee ({fee} sats) is too high";
|
|
32
|
+
readonly invoiceExpired: "That invoice has expired";
|
|
33
|
+
readonly lnurlExactly: "{domain} asks for exactly {amount} sats";
|
|
34
|
+
readonly lnurlRange: "{domain} takes between {min} and {max} sats";
|
|
35
|
+
readonly feeAboveLimit: "The fee exceeds your limit";
|
|
36
|
+
readonly cashuFeeAboveLimit: "Cashu fee exceeds your limit";
|
|
37
|
+
readonly invalidMaxFee: "Invalid maximum fee";
|
|
38
|
+
readonly methodUnavailable: "This payment method is unavailable";
|
|
39
|
+
readonly unknownPaymentIntent: "Unknown payment intent";
|
|
40
|
+
readonly paymentExpired: "Payment request expired or has an invalid expiry";
|
|
41
|
+
readonly requestHasPayment: "This request already has a payment. Reconcile it before trying again.";
|
|
42
|
+
readonly requestPaymentInFlight: "This request already has a payment; reconcile it instead";
|
|
43
|
+
readonly requestNotAwaiting: "This request is no longer awaiting payment. Check its status before spending.";
|
|
44
|
+
readonly reconnectBeforeApprove: "Reconnect the data link before approving. Your review was saved.";
|
|
45
|
+
readonly cannotSubmitAgain: "This payment cannot be submitted again. Reconcile its existing transaction.";
|
|
46
|
+
readonly alreadySubmitted: "This payment was already submitted or could not be saved";
|
|
47
|
+
readonly sentAfterReview: "A payment from this wallet was sent after this review was made. Create a new review";
|
|
48
|
+
readonly cannotCancelSubmitted: "A submitted payment cannot be cancelled; reconcile it instead";
|
|
49
|
+
readonly outcomeUnknown: "Outcome unknown. Check the existing payment; do not send another.";
|
|
50
|
+
readonly notYetConfirmed: "Not yet confirmed. No second payment was sent.";
|
|
51
|
+
readonly couldNotVerify: "Could not verify this payment yet. No second payment was sent.";
|
|
52
|
+
readonly paymentTakenBack: "This payment was taken back. The sats are in your wallet.";
|
|
53
|
+
readonly parkedSigned: "Needs your decision: this payment was signed before this copy of your profile took over. It is never sent again from here. Check it before you pay again.";
|
|
54
|
+
readonly contactAway: "Your contact is offline. Nothing was sent: pay once the chat is live.";
|
|
55
|
+
readonly realMoneyUnconfirmed: "This pays with real money: confirm it with Send real money first. Nothing was sent.";
|
|
56
|
+
readonly mainnetPaymentOnTestnet: "This is a Mainnet payment (real money): a Testnet wallet never pays it. Use a Mainnet wallet.";
|
|
57
|
+
readonly testnetPaymentOnMainnet: "This is a Testnet payment (test coins): a Mainnet wallet never pays it. Use a Testnet wallet.";
|
|
58
|
+
readonly usdtRpcUnavailable: "USDT RPC unavailable";
|
|
59
|
+
readonly usdtNotEnoughTokens: "Insufficient token balance";
|
|
60
|
+
readonly usdtNotEnoughGas: "Insufficient ETH for gas";
|
|
61
|
+
readonly usdtGasAboveLimit: "Estimated maximum gas exceeds your limit";
|
|
62
|
+
readonly usdtNeedsSepoliaGas: "This needs a little Sepolia ETH for gas first";
|
|
63
|
+
readonly fedimintNotInvite: "That is not a Fedimint invite code: it starts with fed1";
|
|
64
|
+
readonly fedimintAlreadyJoined: "You already joined this federation";
|
|
65
|
+
readonly fedimintConnecting: "Wait for the federation to connect";
|
|
66
|
+
readonly fedimintNotEnough: "Not enough in this federation";
|
|
67
|
+
readonly fedimintRealOnTestnet: "This federation holds real bitcoin: it belongs in a Mainnet Fedimint wallet";
|
|
68
|
+
readonly fedimintTestOnMainnet: "This federation is on {chain}, a test network: it belongs in a Testnet Fedimint wallet";
|
|
69
|
+
readonly walletAway: "{wallet} can't be used here. Use it on {device}.";
|
|
70
|
+
readonly walletAwayUnnamed: "{wallet} can't be used here: its home is another device.";
|
|
71
|
+
readonly groupTurnUnconfirmed: "Can't check which device is active, so the group was not changed. Try again in a moment.";
|
|
72
|
+
};
|
|
73
|
+
export type EngineErrorCode = keyof typeof ENGINE_ERRORS;
|
|
74
|
+
export type EngineErrorValues = Record<string, string | number>;
|
|
75
|
+
/**
|
|
76
|
+
* An error the engine knows: `engineCode` travels with it inside the engine, the text everywhere. Not `code`: the
|
|
77
|
+
* CLI reads a `code` as its own exit code, and Node's errors carry one of theirs.
|
|
78
|
+
*/
|
|
79
|
+
export declare class EngineError extends Error {
|
|
80
|
+
readonly engineCode: EngineErrorCode;
|
|
81
|
+
readonly values: EngineErrorValues;
|
|
82
|
+
constructor(engineCode: EngineErrorCode, values?: EngineErrorValues);
|
|
83
|
+
}
|
|
84
|
+
/** The English text of `code` with its values in it, exactly as the engine writes it. */
|
|
85
|
+
export declare function engineText(code: EngineErrorCode, values?: EngineErrorValues): string;
|
|
86
|
+
export declare const engineError: (code: EngineErrorCode, values?: EngineErrorValues) => EngineError;
|
|
87
|
+
/** The code and values of a text the engine wrote, or null for any other text (it is then shown as it is). */
|
|
88
|
+
export declare function parseEngineError(text: string): {
|
|
89
|
+
code: EngineErrorCode;
|
|
90
|
+
values: Record<string, string>;
|
|
91
|
+
} | null;
|
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
import type { DeviceFrame } from "./deviceLink.js";
|
|
2
|
+
import type { Signer } from "./signer.js";
|
|
3
|
+
export declare const ENROLL_HELLO = "enroll-hello";
|
|
4
|
+
export declare const ENROLL_PROOF = "enroll-proof";
|
|
5
|
+
export declare const ENROLL_GRANT = "enroll-grant";
|
|
6
|
+
export declare const ENROLL_DONE = "enroll-done";
|
|
7
|
+
export declare const ENROLL_CANCEL = "enroll-cancel";
|
|
8
|
+
/** What kind of client a device is (WISP 06 § Terms). Anything else a hello says is read as `web`. */
|
|
9
|
+
export declare const DEVICE_KINDS: readonly ["web", "desktop", "extension"];
|
|
10
|
+
export type DeviceKind = (typeof DEVICE_KINDS)[number];
|
|
11
|
+
/** Why a side ended the session. */
|
|
12
|
+
export declare const ENROLL_CANCEL_REASONS: readonly ["digits", "used", "expired", "cancelled", "full", "failed"];
|
|
13
|
+
export type EnrollCancelReason = (typeof ENROLL_CANCEL_REASONS)[number];
|
|
14
|
+
/** The bytes both devices sign: the session, then A's key, then B's. */
|
|
15
|
+
export declare function enrollMessage(transcriptHash: string, inviterKey: Uint8Array, joinerKey: Uint8Array): Uint8Array;
|
|
16
|
+
/**
|
|
17
|
+
* The six digits both screens show: the first 32 bits of `SHA-256("ghostly-enroll-digits" || transcriptHash ||
|
|
18
|
+
* A's key || B's key)`, big-endian, as a decimal number modulo 1,000,000, with leading zeros. The transcript hash goes
|
|
19
|
+
* in as its 32 bytes. Not 20 bits: modulo a million those make the values under 48,576 twice as likely as the rest,
|
|
20
|
+
* which 32 bits bring down to one part in about 4,295 (WISP 06 § Adding a device).
|
|
21
|
+
*/
|
|
22
|
+
export declare function enrollDigits(transcriptHash: string, inviterKey: Uint8Array, joinerKey: Uint8Array): string;
|
|
23
|
+
/** "482913" as people read it: "482 913". */
|
|
24
|
+
export declare const formatEnrollDigits: (digits: string) => string;
|
|
25
|
+
/** What a hello says of the device that joins. */
|
|
26
|
+
export interface EnrollHello {
|
|
27
|
+
key: Uint8Array;
|
|
28
|
+
/** As the device set holds it: at most 16 bytes of UTF-8. */
|
|
29
|
+
name: string;
|
|
30
|
+
kind: DeviceKind;
|
|
31
|
+
app: string;
|
|
32
|
+
}
|
|
33
|
+
/** `enroll-hello`, signed by the joiner over the tuple. */
|
|
34
|
+
export declare function enrollHelloFrame(transcriptHash: string, inviterKey: Uint8Array, joiner: Signer, about: {
|
|
35
|
+
name: string;
|
|
36
|
+
kind: DeviceKind;
|
|
37
|
+
app: string;
|
|
38
|
+
}): Promise<DeviceFrame>;
|
|
39
|
+
/**
|
|
40
|
+
* A hello, checked: its key must be the one the session authenticated (`sessionKey`), and its signature must be that
|
|
41
|
+
* key's over this session's tuple. Null for anything else.
|
|
42
|
+
*/
|
|
43
|
+
export declare function readEnrollHello(frame: DeviceFrame, transcriptHash: string, inviterKey: Uint8Array, sessionKey: Uint8Array): EnrollHello | null;
|
|
44
|
+
/** `enroll-proof`: the inviter's signature over the same tuple. */
|
|
45
|
+
export declare function enrollProofFrame(transcriptHash: string, inviter: Signer, joinerKey: Uint8Array): Promise<DeviceFrame>;
|
|
46
|
+
/** Whether a proof is the inviter's: checked against the key in the code, never against what the session says. */
|
|
47
|
+
export declare function verifyEnrollProof(frame: DeviceFrame, transcriptHash: string, inviterKey: Uint8Array, joinerKey: Uint8Array): boolean;
|
|
48
|
+
/** One slot of a granted device set: the key and its name, or null where nobody holds the slot. */
|
|
49
|
+
export type EnrollSlot = {
|
|
50
|
+
key: Uint8Array;
|
|
51
|
+
name: string;
|
|
52
|
+
} | null;
|
|
53
|
+
/**
|
|
54
|
+
* The person's network settings, as the active device has them (`devices/network.ts` keeps the same copy): a new
|
|
55
|
+
* standby reaches the other devices through the person's relays, Iroh relays and ICE servers, and asks nothing of
|
|
56
|
+
* anyone with the network off. Absent fields are the app's defaults. This build's own field of the grant (`net`).
|
|
57
|
+
*/
|
|
58
|
+
export interface EnrollNetwork {
|
|
59
|
+
off?: boolean;
|
|
60
|
+
relays?: string[];
|
|
61
|
+
readRelays?: boolean;
|
|
62
|
+
irohRelays?: string[];
|
|
63
|
+
/** The relay a browser reaches the HyperDHT through (a new standby web app's device links offer HyperDHT through it). */
|
|
64
|
+
hyperdhtRelay?: string;
|
|
65
|
+
iceServers?: {
|
|
66
|
+
urls: string;
|
|
67
|
+
username?: string;
|
|
68
|
+
credential?: string;
|
|
69
|
+
}[];
|
|
70
|
+
}
|
|
71
|
+
/** What `enroll-grant` gives the new device. */
|
|
72
|
+
export interface EnrollGrant {
|
|
73
|
+
/** The device-set secret, 32 bytes. */
|
|
74
|
+
d: Uint8Array;
|
|
75
|
+
/** By slot, so a slot keeps its index: four entries at most, null where nobody holds it. */
|
|
76
|
+
set: EnrollSlot[];
|
|
77
|
+
turn: number;
|
|
78
|
+
rev: number;
|
|
79
|
+
/** The person's network settings (`net`); absent from a grant that carries none. */
|
|
80
|
+
network?: EnrollNetwork;
|
|
81
|
+
}
|
|
82
|
+
/**
|
|
83
|
+
* `enroll-grant`. The WISP writes the set as `[[key, name], ...]`; slots keep their index (after a removal the slots
|
|
84
|
+
* held need not be the first), so an unheld slot is `null` in its place, and trailing unheld slots are left out.
|
|
85
|
+
*/
|
|
86
|
+
export declare function enrollGrantFrame(grant: EnrollGrant): DeviceFrame;
|
|
87
|
+
/**
|
|
88
|
+
* A grant, checked for the joiner with `joinerKey`: a 32-byte `D`, a set of at most four slots that lists the joiner
|
|
89
|
+
* once and the inviter once, and a turn and `rev` an ordinary record can have. Null for anything else.
|
|
90
|
+
*/
|
|
91
|
+
export declare function readEnrollGrant(frame: DeviceFrame, inviterKey: Uint8Array, joinerKey: Uint8Array): (EnrollGrant & {
|
|
92
|
+
ownSlot: number;
|
|
93
|
+
inviterSlot: number;
|
|
94
|
+
}) | null;
|
|
95
|
+
export declare const enrollDoneFrame: () => DeviceFrame;
|
|
96
|
+
export declare const enrollCancelFrame: (why: EnrollCancelReason) => DeviceFrame;
|
|
97
|
+
/** The reason a cancel gives, or null when the frame is no cancel. An unknown reason is `failed`. */
|
|
98
|
+
export declare function enrollCancelReason(frame: DeviceFrame): EnrollCancelReason | null;
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
import { type ChunkFrame, type FileFrame, type FrameChannel, type ResetFrame } from "./frames.js";
|
|
2
|
+
import type { WireReply } from "./replies.js";
|
|
3
|
+
import type { ImageMeta } from "./image.js";
|
|
4
|
+
import { type VideoMeta } from "./video.js";
|
|
5
|
+
import { type VoiceMeta } from "./voice.js";
|
|
6
|
+
/**
|
|
7
|
+
* Files over the data link. A `file` frame announces name, size and type, the
|
|
8
|
+
* bytes follow as chunks, and the receiver only keeps the file if exactly the
|
|
9
|
+
* announced number of bytes arrived. Nothing touches Pkarr: files go peer to
|
|
10
|
+
* peer or not at all.
|
|
11
|
+
*/
|
|
12
|
+
export interface FileInfo {
|
|
13
|
+
/** Chosen by the sender. */
|
|
14
|
+
id: string;
|
|
15
|
+
name: string;
|
|
16
|
+
size: number;
|
|
17
|
+
mime: string;
|
|
18
|
+
timestamp: number;
|
|
19
|
+
/** A voice message: its length and the shape of its sound (files/2 and held items only). */
|
|
20
|
+
voice?: VoiceMeta;
|
|
21
|
+
/** A video: its length, size and a small first frame (optional; old apps ignore it). */
|
|
22
|
+
video?: VideoMeta;
|
|
23
|
+
/** A picture: its size as it is shown, so its box is laid out before it arrives (optional; old apps ignore it). */
|
|
24
|
+
image?: ImageMeta;
|
|
25
|
+
/** The message this file answers (`r`, WISP 401 § Replies): files/2, files/3 and held items; older apps ignore it. */
|
|
26
|
+
reply?: WireReply;
|
|
27
|
+
/** How many times it has been forwarded (`fw`, WISP 401 § Forwards): files/2, files/3 and held items; older apps ignore it. */
|
|
28
|
+
forwarded?: number;
|
|
29
|
+
}
|
|
30
|
+
/** Where a platform puts incoming bytes: memory, IndexedDB, disk. */
|
|
31
|
+
export interface FileSink {
|
|
32
|
+
write(chunk: Uint8Array): void | Promise<void>;
|
|
33
|
+
close(digest?: string): void | Promise<void>;
|
|
34
|
+
abort(): void;
|
|
35
|
+
}
|
|
36
|
+
export interface FileTransferEvents {
|
|
37
|
+
/** Return a sink to accept the file, null to refuse it, or the reason for refusing it. */
|
|
38
|
+
onIncoming(file: FileInfo): FileSink | string | null;
|
|
39
|
+
onProgress?(fileId: string, transferred: number, direction: "in" | "out"): void;
|
|
40
|
+
onComplete?(fileId: string, direction: "in" | "out"): void;
|
|
41
|
+
onFailed?(fileId: string, reason: string, direction: "in" | "out"): void;
|
|
42
|
+
}
|
|
43
|
+
/** A file name is display text and a download suggestion, never a path. */
|
|
44
|
+
export declare function sanitizeFileName(name: string): string;
|
|
45
|
+
export declare function sanitizeMime(mime: string): string;
|
|
46
|
+
/** A size for people: B, KB, MB, GB, TB (powers of 1024), one decimal from KB up. */
|
|
47
|
+
export declare function formatFileSize(bytes: number): string;
|
|
48
|
+
/** Raster images a UI may show inline. SVG is left out on purpose: it can carry scripts. */
|
|
49
|
+
export declare const PREVIEWABLE_IMAGE: RegExp;
|
|
50
|
+
/**
|
|
51
|
+
* The type received bytes are served with. The peer picks the announced type,
|
|
52
|
+
* and a blob: URL typed text/html or image/svg+xml would run in the app's
|
|
53
|
+
* origin, so anything but a previewable image or playable audio or video is opaque bytes.
|
|
54
|
+
* Audio and video keep their type because WebKit will not play what is typed as bytes.
|
|
55
|
+
*/
|
|
56
|
+
export declare function safeBlobType(mime: string): string;
|
|
57
|
+
export declare class FileTransfers {
|
|
58
|
+
private readonly channel;
|
|
59
|
+
private readonly events;
|
|
60
|
+
private nextStreamId;
|
|
61
|
+
private readonly incoming;
|
|
62
|
+
private readonly outgoing;
|
|
63
|
+
constructor(channel: FrameChannel, events: FileTransferEvents);
|
|
64
|
+
/** Streams a file to the peer. Resolves once every byte is handed to the channel. */
|
|
65
|
+
send(file: FileInfo, source: AsyncIterable<Uint8Array>): Promise<void>;
|
|
66
|
+
handleFile(frame: FileFrame): void;
|
|
67
|
+
handleChunk(chunk: ChunkFrame): void;
|
|
68
|
+
handleReset(frame: ResetFrame): void;
|
|
69
|
+
/** The link went away: nothing in flight can finish. */
|
|
70
|
+
closeAll(): void;
|
|
71
|
+
private armIdleTimer;
|
|
72
|
+
private failIncoming;
|
|
73
|
+
}
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
export declare const FORWARD_LIMITS: {
|
|
2
|
+
/** The count stops here: a message forwarded more often still says it was forwarded many times. */
|
|
3
|
+
readonly max: 255;
|
|
4
|
+
/** From this many hops on, the reader says "Forwarded many times". */
|
|
5
|
+
readonly many: 5;
|
|
6
|
+
};
|
|
7
|
+
/** A hop count as a receiver takes it: a whole number from 1 to `FORWARD_LIMITS.max`. Anything else is not forwarded. */
|
|
8
|
+
export declare function readForwarded(raw: unknown): number | undefined;
|
|
9
|
+
/** The count a message carries once forwarded again: one more hop than it had (none for a message never forwarded). */
|
|
10
|
+
export declare function forwardedAgain(hops?: number): number;
|
|
11
|
+
/** Whether a message has come far enough to be called "Forwarded many times". */
|
|
12
|
+
export declare function forwardedMany(hops?: number): boolean;
|