@ghostlytools/sdk 0.0.0-stage → 1.2.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (145) hide show
  1. package/README.md +13 -2
  2. package/dist/app.js +67 -0
  3. package/dist/app.js.map +1 -0
  4. package/dist/core.js +207 -0
  5. package/dist/core.js.map +1 -0
  6. package/dist/fakes-CBIuqo5e.js +536 -0
  7. package/dist/fakes-CBIuqo5e.js.map +1 -0
  8. package/dist/fakes.js +2 -0
  9. package/dist/index.js +179 -0
  10. package/dist/index.js.map +1 -0
  11. package/dist/keet-identity-key-BylxCPl4.js +76483 -0
  12. package/dist/keet-identity-key-BylxCPl4.js.map +1 -0
  13. package/dist/src-DCeLPsi-.js +31056 -0
  14. package/dist/src-DCeLPsi-.js.map +1 -0
  15. package/dist/testing.js +330 -0
  16. package/dist/testing.js.map +1 -0
  17. package/dist/types/browser/src/engine/paymentAdapters/providers/contractSuite.d.ts +41 -0
  18. package/dist/types/browser/src/engine/paymentAdapters/providers/lightning.d.ts +103 -0
  19. package/dist/types/browser/src/engine/paymentAdapters/providers/onchain.d.ts +88 -0
  20. package/dist/types/browser/src/engine/paymentAdapters/providers/testing.d.ts +89 -0
  21. package/dist/types/browser/src/engine/paymentAdapters/providers/types.d.ts +151 -0
  22. package/dist/types/browser/src/plugins/bundled.d.ts +8 -0
  23. package/dist/types/browser/src/plugins/registry.d.ts +57 -0
  24. package/dist/types/browser/src/proofs/contract.d.ts +262 -0
  25. package/dist/types/browser/src/proofs/contractSuite.d.ts +27 -0
  26. package/dist/types/browser/src/proofs/testing.d.ts +36 -0
  27. package/dist/types/browser/src/proofs/verify.d.ts +23 -0
  28. package/dist/types/browser/src/shared/mints.d.ts +50 -0
  29. package/dist/types/core/src/appBundle.d.ts +173 -0
  30. package/dist/types/core/src/appStatements.d.ts +142 -0
  31. package/dist/types/core/src/appStore.d.ts +133 -0
  32. package/dist/types/core/src/appUpdates.d.ts +88 -0
  33. package/dist/types/core/src/atprotoIdentity.d.ts +49 -0
  34. package/dist/types/core/src/atprotoRepo.d.ts +101 -0
  35. package/dist/types/core/src/avatar.d.ts +19 -0
  36. package/dist/types/core/src/bip322.d.ts +57 -0
  37. package/dist/types/core/src/bitcoinAddress.d.ts +5 -0
  38. package/dist/types/core/src/bitcoinMessage.d.ts +15 -0
  39. package/dist/types/core/src/bitcoinScript.d.ts +69 -0
  40. package/dist/types/core/src/bolt11.d.ts +30 -0
  41. package/dist/types/core/src/bytes.d.ts +11 -0
  42. package/dist/types/core/src/callSignal.d.ts +232 -0
  43. package/dist/types/core/src/canonicalJson.d.ts +22 -0
  44. package/dist/types/core/src/capsRecord.d.ts +234 -0
  45. package/dist/types/core/src/catchUp.d.ts +45 -0
  46. package/dist/types/core/src/chatFiles.d.ts +271 -0
  47. package/dist/types/core/src/clockWatch.d.ts +72 -0
  48. package/dist/types/core/src/communityRendezvous.d.ts +113 -0
  49. package/dist/types/core/src/crypto.d.ts +10 -0
  50. package/dist/types/core/src/datalink.d.ts +187 -0
  51. package/dist/types/core/src/deviceInvite.d.ts +51 -0
  52. package/dist/types/core/src/deviceLink.d.ts +70 -0
  53. package/dist/types/core/src/dhtDelivery.d.ts +403 -0
  54. package/dist/types/core/src/dhtFiles.d.ts +46 -0
  55. package/dist/types/core/src/did.d.ts +134 -0
  56. package/dist/types/core/src/didDht.d.ts +155 -0
  57. package/dist/types/core/src/directPath.d.ts +63 -0
  58. package/dist/types/core/src/dns.d.ts +41 -0
  59. package/dist/types/core/src/domainProofs.d.ts +88 -0
  60. package/dist/types/core/src/engineErrors.d.ts +90 -0
  61. package/dist/types/core/src/enroll.d.ts +98 -0
  62. package/dist/types/core/src/files.d.ts +73 -0
  63. package/dist/types/core/src/forwards.d.ts +12 -0
  64. package/dist/types/core/src/frames.d.ts +211 -0
  65. package/dist/types/core/src/ghostlink.d.ts +1510 -0
  66. package/dist/types/core/src/groupCommits.d.ts +103 -0
  67. package/dist/types/core/src/groupCommunity.d.ts +714 -0
  68. package/dist/types/core/src/groupCrypto.d.ts +60 -0
  69. package/dist/types/core/src/groupEdits.d.ts +67 -0
  70. package/dist/types/core/src/groupEntry.d.ts +61 -0
  71. package/dist/types/core/src/groupFiles.d.ts +106 -0
  72. package/dist/types/core/src/groupHubs.d.ts +61 -0
  73. package/dist/types/core/src/groupMentions.d.ts +27 -0
  74. package/dist/types/core/src/groupMeta.d.ts +162 -0
  75. package/dist/types/core/src/groupSession.d.ts +710 -0
  76. package/dist/types/core/src/groupSignals.d.ts +167 -0
  77. package/dist/types/core/src/groupTyping.d.ts +56 -0
  78. package/dist/types/core/src/groupWake.d.ts +68 -0
  79. package/dist/types/core/src/handoff.d.ts +255 -0
  80. package/dist/types/core/src/http.d.ts +125 -0
  81. package/dist/types/core/src/identity.d.ts +17 -0
  82. package/dist/types/core/src/identityProofs.d.ts +243 -0
  83. package/dist/types/core/src/identityTimeline.d.ts +72 -0
  84. package/dist/types/core/src/image.d.ts +33 -0
  85. package/dist/types/core/src/index.d.ts +100 -0
  86. package/dist/types/core/src/invite.d.ts +128 -0
  87. package/dist/types/core/src/link.d.ts +353 -0
  88. package/dist/types/core/src/linkPreview.d.ts +60 -0
  89. package/dist/types/core/src/linkTrace.d.ts +12 -0
  90. package/dist/types/core/src/lnurl.d.ts +99 -0
  91. package/dist/types/core/src/messageTime.d.ts +28 -0
  92. package/dist/types/core/src/miniApp.d.ts +141 -0
  93. package/dist/types/core/src/pairedApps.d.ts +151 -0
  94. package/dist/types/core/src/pairedCalls.d.ts +59 -0
  95. package/dist/types/core/src/pairedCapabilities.d.ts +101 -0
  96. package/dist/types/core/src/pairedEdits.d.ts +83 -0
  97. package/dist/types/core/src/pairedFiles.d.ts +30 -0
  98. package/dist/types/core/src/pairedHttp.d.ts +15 -0
  99. package/dist/types/core/src/pairedSession.d.ts +163 -0
  100. package/dist/types/core/src/pairedSignal.d.ts +17 -0
  101. package/dist/types/core/src/pairedTransports.d.ts +76 -0
  102. package/dist/types/core/src/pairedTyping.d.ts +130 -0
  103. package/dist/types/core/src/pairedWake.d.ts +109 -0
  104. package/dist/types/core/src/pairingProgress.d.ts +107 -0
  105. package/dist/types/core/src/paymentIntent.d.ts +111 -0
  106. package/dist/types/core/src/paymentUri.d.ts +34 -0
  107. package/dist/types/core/src/payments.d.ts +97 -0
  108. package/dist/types/core/src/peerProofs.d.ts +98 -0
  109. package/dist/types/core/src/pins.d.ts +73 -0
  110. package/dist/types/core/src/pkarr.d.ts +48 -0
  111. package/dist/types/core/src/pkdns.d.ts +35 -0
  112. package/dist/types/core/src/pubkyProofs.d.ts +25 -0
  113. package/dist/types/core/src/pubkyRing.d.ts +21 -0
  114. package/dist/types/core/src/reactions.d.ts +108 -0
  115. package/dist/types/core/src/records.d.ts +89 -0
  116. package/dist/types/core/src/relay.d.ts +437 -0
  117. package/dist/types/core/src/relayBreaker.d.ts +99 -0
  118. package/dist/types/core/src/replies.d.ts +41 -0
  119. package/dist/types/core/src/services.d.ts +35 -0
  120. package/dist/types/core/src/setUpdate.d.ts +53 -0
  121. package/dist/types/core/src/signal.d.ts +53 -0
  122. package/dist/types/core/src/signer.d.ts +13 -0
  123. package/dist/types/core/src/sparkAddress.d.ts +37 -0
  124. package/dist/types/core/src/sshsig.d.ts +74 -0
  125. package/dist/types/core/src/statusCards.d.ts +253 -0
  126. package/dist/types/core/src/storeForward.d.ts +144 -0
  127. package/dist/types/core/src/text.d.ts +20 -0
  128. package/dist/types/core/src/transport.d.ts +151 -0
  129. package/dist/types/core/src/transportSwitch.d.ts +160 -0
  130. package/dist/types/core/src/turnRead.d.ts +145 -0
  131. package/dist/types/core/src/turnRecord.d.ts +165 -0
  132. package/dist/types/core/src/version.d.ts +9 -0
  133. package/dist/types/core/src/video.d.ts +44 -0
  134. package/dist/types/core/src/voice.d.ts +88 -0
  135. package/dist/types/core/src/webPush.d.ts +58 -0
  136. package/dist/types/sdk/src/app.d.ts +23 -0
  137. package/dist/types/sdk/src/core.d.ts +7 -0
  138. package/dist/types/sdk/src/fakes.d.ts +6 -0
  139. package/dist/types/sdk/src/index.d.ts +26 -0
  140. package/dist/types/sdk/src/testing.d.ts +7 -0
  141. package/dist/types-DvtCy3WB.js +99 -0
  142. package/dist/types-DvtCy3WB.js.map +1 -0
  143. package/dist/verify-DBGw6wYt.js +106 -0
  144. package/dist/verify-DBGw6wYt.js.map +1 -0
  145. package/package.json +70 -4
@@ -0,0 +1,41 @@
1
+ /**
2
+ * On the wire (`r`): `i` the original's id in this chat, `s` a line of it, `f` who wrote it. In a paired chat `f` is
3
+ * `"sender"` (the reply's author wrote the original) or `"recipient"` (the reader did); in a group, a member key.
4
+ * `b`: a button press (WISP 406 · Message Buttons), the id of the original's button this reply presses; its text is
5
+ * the button's label. An app from before buttons drops `b` and shows an ordinary reply.
6
+ */
7
+ export interface WireReply {
8
+ i: string;
9
+ s: string;
10
+ f: string;
11
+ b?: string;
12
+ }
13
+ export declare const REPLY_LIMITS: {
14
+ /** Code points of the line of the original, an ellipsis included when it was cut. */
15
+ readonly snippet: 120;
16
+ /** Characters of the original's id. */
17
+ readonly id: 128;
18
+ /** Characters of a line as it arrives, before it is cleaned: anything longer is not a line of a message. */
19
+ readonly raw: 2048;
20
+ };
21
+ /** A paired chat's message id, a payment id or a file's wire id; a group message's `sender:epoch:seq`. */
22
+ export declare const REPLY_ID: RegExp;
23
+ /** The two authors a paired chat has, from the reply author's side. */
24
+ export declare const PAIRED_REPLY_AUTHORS: readonly ["sender", "recipient"];
25
+ /**
26
+ * A line of a message to quote: plain text on one line (line breaks and runs of spaces become one space), without
27
+ * control, invisible or direction characters (WISP 400, as for names), at most `REPLY_LIMITS.snippet` code points,
28
+ * the last of them an ellipsis when it was cut.
29
+ */
30
+ export declare function replySnippet(text: string): string;
31
+ /**
32
+ * A reply as a receiver takes it: an object with an id of this chat's shape, a line (cleaned and cut again here,
33
+ * whatever the sender did) and an author `author` accepts. Anything else is no reply: the message stays, without it.
34
+ */
35
+ export declare function readReply(raw: unknown, author: (f: string) => boolean): WireReply | undefined;
36
+ /** Who may have written the original in a paired chat. */
37
+ export declare const pairedReplyAuthor: (f: string) => boolean;
38
+ /** Who may have written the original in a group: a member key (whether they are still a member is the reader's to see). */
39
+ export declare const groupReplyAuthor: (f: string) => boolean;
40
+ /** Only the wire fields, in a fixed order, the line cleaned: what the sender puts on a frame. */
41
+ export declare const wireReply: (reply: WireReply) => WireReply;
@@ -0,0 +1,35 @@
1
+ export type BuiltinServiceType = "chat" | "voice" | "video" | "http";
2
+ export interface ServiceAd {
3
+ /** Stable identifier, unique per peer. Remote peers address services by id only. */
4
+ id: string;
5
+ type: BuiltinServiceType | (string & {});
6
+ name?: string;
7
+ /** Wire protocol spoken over the data link, e.g. `ghostly-http/1`. */
8
+ proto?: string;
9
+ meta?: Record<string, string>;
10
+ }
11
+ export declare const SERVICES_VERSION = 1;
12
+ export declare const HTTP_SERVICE_PROTO = "ghostly-http/1";
13
+ export declare const MAX_SERVICES = 16;
14
+ /** What a peer that predates `_svc` offers implicitly. */
15
+ export declare const LEGACY_SERVICES: ServiceAd[];
16
+ export declare function isValidServiceId(id: string): boolean;
17
+ export declare function serviceIdFromName(name: string, taken?: Iterable<string>): string;
18
+ interface WireService {
19
+ i: string;
20
+ t: string;
21
+ n?: string;
22
+ p?: string;
23
+ m?: Record<string, string>;
24
+ }
25
+ interface WireServices {
26
+ v: number;
27
+ s: (string | WireService)[];
28
+ }
29
+ /** Compact JSON; a service whose id equals its type and has no metadata is a bare string. */
30
+ export declare function servicesToWire(services: ServiceAd[]): WireServices;
31
+ export declare function encodeServices(services: ServiceAd[]): string;
32
+ /** Parses an untrusted advertisement. Invalid entries are dropped, never thrown. */
33
+ export declare function decodeServices(json: string): ServiceAd[] | null;
34
+ export declare function servicesFromWire(wire: unknown): ServiceAd[] | null;
35
+ export {};
@@ -0,0 +1,53 @@
1
+ import type { DeviceFrame } from "./deviceLink.js";
2
+ import type { EnrollSlot } from "./enroll.js";
3
+ import type { Signer } from "./signer.js";
4
+ import { type TurnKeys, type TurnSigner, type TurnSlot } from "./turnRecord.js";
5
+ export declare const SET_UPDATE = "set-update";
6
+ export declare const SET_ACK = "set-ack";
7
+ /** What a `set-update` says. */
8
+ export interface SetUpdate {
9
+ /** The new device-set secret, 32 bytes. */
10
+ d: Uint8Array;
11
+ /** By slot: the devices that stay, each in the slot it had. */
12
+ set: EnrollSlot[];
13
+ /** The turn and `rev` of the first record the remover puts at the new address. */
14
+ turn: number;
15
+ rev: number;
16
+ /** The tombstone packet put at the old address, as a relay payload. */
17
+ tomb: Uint8Array;
18
+ /** The remover's device signing key. */
19
+ by: Uint8Array;
20
+ /** The remover's last ordinary record at the old address, as a packet (`rec`). Optional. */
21
+ rec?: Uint8Array;
22
+ }
23
+ /** The set as the frame and the signature carry it: by slot, `null` where nobody holds one, trailing ones left out. */
24
+ export declare function encodeSetSlots(set: readonly EnrollSlot[]): ([string, string] | null)[];
25
+ /** The bytes the remover signs: the old turn address, then the frame's fields, the tombstone by its digest. */
26
+ export declare function setUpdateMessage(oldAddress: Uint8Array, update: Omit<SetUpdate, "by" | "rec">): Uint8Array;
27
+ /** The signed frame. `oldAddress`: the turn address the tombstone closes. */
28
+ export declare function setUpdateFrame(oldAddress: Uint8Array, update: Omit<SetUpdate, "by">, signer: Signer): Promise<DeviceFrame>;
29
+ /** A `set-update` as it reads: its names cleaned for display (`set`), the set its signature covers as the frame wrote it (`signed`). */
30
+ export type ReadSetUpdate = SetUpdate & {
31
+ signature: Uint8Array;
32
+ signed: ([string, string] | null)[];
33
+ };
34
+ /**
35
+ * A `set-update` as it reads, with its signature, or null when it is not well formed. Its signature is not checked
36
+ * here: that needs the old turn address (`verifySetUpdate`).
37
+ */
38
+ export declare function readSetUpdate(frame: DeviceFrame): ReadSetUpdate | null;
39
+ /** Whether `by` signed this update for the turn address `oldAddress`. */
40
+ export declare function verifySetUpdate(update: SetUpdate & {
41
+ signature: Uint8Array;
42
+ signed?: ([string, string] | null)[];
43
+ }, oldAddress: Uint8Array): boolean;
44
+ export declare const setAckFrame: () => DeviceFrame;
45
+ /**
46
+ * The tombstone of a turn address (WISP 06 § Removing a device): the turn record with turn 2^32 - 1 and no active
47
+ * device, its slots the devices that stay (zero for the one removed), signed by the remover from its own slot, `rev` 0,
48
+ * no release, a random `instance`. Every tombstone has the sequence 2^52 - 1. Its packet, to be stored before it is put.
49
+ */
50
+ export declare function signTombstone(keys: TurnKeys, author: number, slots: readonly (TurnSlot | null)[], signer: TurnSigner, fixed?: {
51
+ instance?: Uint8Array;
52
+ nonce?: Uint8Array;
53
+ }): Promise<Uint8Array>;
@@ -0,0 +1,53 @@
1
+ export interface RtcSignal {
2
+ t: "o" | "a";
3
+ ts: number;
4
+ /** For answers: `ts` of the offer being answered. */
5
+ o?: number;
6
+ /** ICE ufrag */
7
+ u: string;
8
+ /** ICE pwd */
9
+ p: string;
10
+ /** DTLS SHA-256 fingerprint, hex without separators */
11
+ f: string;
12
+ /** DTLS setup role */
13
+ s: string;
14
+ /** Candidates as `<h|s|r>,<address>,<port>` (host, server reflexive, relay) */
15
+ c: string[];
16
+ }
17
+ export declare const DATA_CHANNEL_LABEL = "ghostly/1";
18
+ export declare const DATA_CHANNEL_ID = 0;
19
+ /** An offer older than this is ignored. */
20
+ export declare const RTC_SIGNAL_MAX_AGE_MS = 120000;
21
+ /** A signal dated further ahead of this clock than this is not taken: its time would outrank every later one of its sender. */
22
+ export declare const RTC_SIGNAL_FUTURE_MS: number;
23
+ /**
24
+ * How this device saw a signal come. `since`: when its read of the maker's record that did not have the signal began,
25
+ * by this clock; only a read the network answered counts, never a copy kept from before. `after`: the time of the
26
+ * maker's own packet that read found, by the maker's clock; null when that read found none of the maker's.
27
+ */
28
+ export interface SignalSight {
29
+ since: number;
30
+ after: number | null;
31
+ live?: boolean;
32
+ }
33
+ /**
34
+ * Whether an offer its maker dated `ts` is recent enough to answer.
35
+ *
36
+ * With a `sight`, two things place it in time without holding the maker's clock against this one. It was not in the
37
+ * maker's record at `since`, so it reached the record after that; and it is not dated before the maker's packet that
38
+ * was there (`after`, the same clock as `ts`), so it was not made before that packet either. An offer made earlier and
39
+ * put in the record again later fails the second. Its time is then held between `since` and now, and only this clock
40
+ * measures its age.
41
+ *
42
+ * When that read found nothing of the maker's (`after` null: a first contact), there is no packet to hold the offer
43
+ * against, and a record that looked empty a moment ago is weaker ground: the offer's own time then has to be within
44
+ * `RTC_SIGNAL_FUTURE_MS` of this clock too, which is as far as two clocks are taken to differ.
45
+ *
46
+ * Without a sight (the first read of a run found the offer) its own time is all there is to go by, and it may differ
47
+ * from this clock by the age allowed, either way.
48
+ */
49
+ export declare function offerIsFresh(ts: number, sight?: SignalSight, now?: number): boolean;
50
+ export declare function extractRtcParams(sdp: string): Pick<RtcSignal, "u" | "p" | "f" | "s" | "c">;
51
+ /** Validates an untrusted signal; anything that could inject SDP lines is rejected. */
52
+ export declare function parseRtcSignal(json: string): RtcSignal | null;
53
+ export declare function buildDataSdp(signal: RtcSignal): string;
@@ -0,0 +1,13 @@
1
+ export interface Signer {
2
+ /** The Ed25519 public key, 32 bytes. */
3
+ readonly publicKey: Uint8Array;
4
+ /** The 64-byte signature of `bytes`. */
5
+ sign(bytes: Uint8Array): Promise<Uint8Array>;
6
+ }
7
+ /** A seed held by the app, as every key of a profile is today. */
8
+ export declare function seedSigner(seed: Uint8Array): Signer;
9
+ /**
10
+ * A WebCrypto Ed25519 private key, non-extractable or not, with its raw public key. The app never sees the private
11
+ * bytes: `crypto.subtle` signs.
12
+ */
13
+ export declare function webCryptoSigner(privateKey: CryptoKey, publicKey: Uint8Array): Signer;
@@ -0,0 +1,37 @@
1
+ /**
2
+ * Spark (https://spark.money): a Bitcoin layer 2 where a transfer between two Spark wallets is instant and
3
+ * off-chain. Ghostly's Spark wallets run on Bitcoin (real sats, Breez API key) or on regtest (Breez and
4
+ * Lightspark's hosted test network, worthless sats). Spark's own testnet and signet are not offered by the
5
+ * Breez SDK, so they are not payment networks here.
6
+ */
7
+ export type SparkNetwork = "bitcoin" | "regtest";
8
+ export declare const SPARK_NETWORKS: readonly SparkNetwork[];
9
+ /**
10
+ * The `provider` of a Spark target. Spark is one network per chain (its operators are the same for every
11
+ * wallet), so any Spark wallet on the same network pays any Spark address: the payee names no service.
12
+ */
13
+ export declare const SPARK_PROVIDER = "spark";
14
+ /**
15
+ * What a Spark string is on `network`: a wallet's `address` (its identity key, the same every time) or an
16
+ * `invoice` (an address plus an amount, an expiry, a memo and a unique id, signed by the payee). Undefined
17
+ * when it is neither, or belongs to another network. Structure only: the wallet's SDK checks the rest.
18
+ */
19
+ export declare function sparkAddressKind(address: unknown, network: SparkNetwork): "address" | "invoice" | undefined;
20
+ export declare const isSparkAddress: (address: unknown, network: SparkNetwork) => boolean;
21
+ /** The Spark network a string belongs to, from its prefix alone (`spark1…` Bitcoin, `sparkrt1…` regtest). */
22
+ export declare function sparkNetworkOf(address: string): SparkNetwork | undefined;
23
+ /** What a Spark invoice asks for, read from the invoice itself (the payer's wallet checks it again). */
24
+ export interface SparkInvoiceDetails {
25
+ /** Sats asked; absent when the payer chooses. */
26
+ amount?: number;
27
+ memo?: string;
28
+ /** Milliseconds. */
29
+ expiresAt?: number;
30
+ /** An invoice for a token (not sats): Ghostly does not pay those. */
31
+ token: boolean;
32
+ }
33
+ /**
34
+ * The amount, memo and expiry a Spark invoice carries (SparkInvoiceFields: 4 sats payment, 3 tokens payment, 5 memo,
35
+ * 7 expiry time), or undefined when `invoice` is not an invoice of `network`.
36
+ */
37
+ export declare function sparkInvoiceDetails(invoice: string, network: SparkNetwork): SparkInvoiceDetails | undefined;
@@ -0,0 +1,74 @@
1
+ /** OpenSSH signatures over a Ghostly statement (`ssh-keygen -Y sign -n ghostly`),
2
+ * following PROTOCOL.sshsig. Everything here is local: parsing, the public key
3
+ * the signature names and the signature itself. Which key a person *should*
4
+ * have signed with is the caller's question (an expected fingerprint, or a
5
+ * key list published by a forge; see the browser proof provider). */
6
+ export declare const SSHSIG_NAMESPACE = "ghostly";
7
+ /** A pasted armored signature: an 8192-bit RSA key plus its signature is ~3 KB. */
8
+ export declare const SSHSIG_MAX_ARMOR = 6144;
9
+ /** A pasted `.pub` line; comments are dropped. */
10
+ export declare const SSH_PUBLIC_KEY_MAX = 4096;
11
+ export type SshKeyType = 'ssh-ed25519' | 'ecdsa-sha2-nistp256' | 'ecdsa-sha2-nistp384' | 'ecdsa-sha2-nistp521' | 'ssh-rsa' | 'sk-ssh-ed25519@openssh.com' | 'sk-ecdsa-sha2-nistp256@openssh.com';
12
+ export declare const SSH_KEY_TYPES: readonly SshKeyType[];
13
+ export interface SshPublicKey {
14
+ type: SshKeyType;
15
+ /** The wire-format key blob, which is what fingerprints and forge key lists name. */
16
+ blob: Uint8Array;
17
+ /** `SHA256:` + unpadded base64, exactly as `ssh-keygen -l` prints it. */
18
+ fingerprint: string;
19
+ /** `type base64`, the form `.pub` files and forge key lists use (no comment). */
20
+ line: string;
21
+ /** Security keys only: the FIDO application, `ssh:` unless chosen at creation. */
22
+ application?: string;
23
+ /** RSA modulus size. */
24
+ bits?: number;
25
+ }
26
+ export interface SshSignatureCheck {
27
+ key: SshPublicKey;
28
+ hashAlgorithm: 'sha256' | 'sha512';
29
+ /** Security keys only: what the authenticator asserted for this signature. */
30
+ securityKey?: {
31
+ userPresent: boolean;
32
+ userVerified: boolean;
33
+ counter: number;
34
+ };
35
+ }
36
+ export declare class SshSigError extends Error {
37
+ }
38
+ export declare function sshFingerprint(blob: Uint8Array): string;
39
+ interface ParsedKey extends SshPublicKey {
40
+ point?: Uint8Array;
41
+ rsa?: {
42
+ n: Uint8Array;
43
+ e: Uint8Array;
44
+ };
45
+ }
46
+ /** Parses one `.pub` style line (`type base64 [comment]`). */
47
+ export declare function parseSshPublicKey(line: string): SshPublicKey;
48
+ interface ParsedSignature {
49
+ key: ParsedKey;
50
+ namespace: string;
51
+ hashAlgorithm: 'sha256' | 'sha512';
52
+ signature: Uint8Array;
53
+ }
54
+ /** Unwraps `-----BEGIN SSH SIGNATURE-----` armor and the SSHSIG envelope, without verifying. */
55
+ export declare function parseSshSignature(armored: string): ParsedSignature;
56
+ /** Verifies an armored SSHSIG over `message` in `namespace` and returns the key that
57
+ * made it. Throws SshSigError for anything malformed, mismatched or unverifiable.
58
+ * Security-key signatures must assert user presence (a touch) unless explicitly
59
+ * allowed otherwise, matching OpenSSH's default for keys created without
60
+ * `no-touch-required`. */
61
+ export declare function verifySshSignature(armored: string, message: Uint8Array | string, options?: {
62
+ namespace?: string;
63
+ allowNoTouch?: boolean;
64
+ }): Promise<SshSignatureCheck>;
65
+ /** Whether two keys are the same, comparing wire blobs (comments never matter). */
66
+ export declare const sameSshKey: (a: Pick<SshPublicKey, "blob">, b: Pick<SshPublicKey, "blob">) => boolean;
67
+ /** 32-byte digest of the key blob as lowercase hex: the fingerprint's bytes, in the
68
+ * shape peer-proof external keys already use. */
69
+ export declare const sshKeyDigestHex: (key: Pick<SshPublicKey, "blob">) => string;
70
+ /** A POSIX shell one-liner that signs `statement` exactly (no trailing newline) and
71
+ * prints the armored signature. Refuses anything that would need escaping, so what
72
+ * is shown is what gets signed. */
73
+ export declare function sshSignCommand(statement: string, keyPath?: string): string;
74
+ export {};
@@ -0,0 +1,253 @@
1
+ export declare const STATUS_CARD_LIMITS: {
2
+ /** A card's JSON, as sent (UTF-8 bytes): with the fallback text it stays well inside every message bound. */
3
+ readonly bytes: number;
4
+ /** The sender's id for the card: stable across its updates. */
5
+ readonly id: 64;
6
+ readonly title: 120;
7
+ /** The current step, a list item, a run's summary. */
8
+ readonly line: 200;
9
+ readonly branch: 120;
10
+ readonly schedule: 80;
11
+ readonly cron: 64;
12
+ readonly linkLabel: 40;
13
+ readonly url: 512;
14
+ readonly items: 20;
15
+ readonly links: 4;
16
+ readonly runs: 10;
17
+ /** Any count on a card (a PR's number, lines, files; steps). */
18
+ readonly count: 1000000000;
19
+ /** How far ahead a routine's next run may be. */
20
+ readonly nextRunMs: number;
21
+ /** Edits a message with a card takes (a text takes `MAX_EDITS_PER_MESSAGE`): a bot updates a long task often. */
22
+ readonly edits: 5000;
23
+ /** Labels on a task, and a label's length in characters. */
24
+ readonly tags: 3;
25
+ readonly tag: 24;
26
+ /** Buttons on a message (WISP 406 · Message Buttons). */
27
+ readonly buttons: 6;
28
+ /** A button's id: what a press names. */
29
+ readonly buttonId: 32;
30
+ /** A button's label, in characters. */
31
+ readonly buttonLabel: 40;
32
+ /** An app card's title and version, in characters (WISP 405 § An app): the manifest's bounds. */
33
+ readonly appTitle: 40;
34
+ readonly appVersion: 32;
35
+ /** A usage card's label ("Claude") and account, in characters (WISP 405 § Usage). */
36
+ readonly usageLabel: 24;
37
+ /** A usage window's name ("5 h", "week"), in characters. */
38
+ readonly usageWindow: 16;
39
+ /** Windows beside a usage card's own, shown in its details. */
40
+ readonly usageWindows: 3;
41
+ };
42
+ /** How a button looks: `primary` is the one highlighted, `danger` warns; `neutral` when none is said. */
43
+ export declare const BUTTON_STYLES: readonly ["primary", "neutral", "danger"];
44
+ export type ButtonStyle = typeof BUTTON_STYLES[number];
45
+ export declare const TASK_STATUSES: readonly ["queued", "running", "blocked", "done", "failed", "cancelled"];
46
+ export type TaskStatus = typeof TASK_STATUSES[number];
47
+ /** A task that is still going: shown first, and counted on the chat's Tasks button. */
48
+ export declare const ACTIVE_TASK_STATUSES: readonly TaskStatus[];
49
+ export declare const ITEM_STATES: readonly ["pending", "running", "done", "failed", "skipped"];
50
+ export type ItemState = typeof ITEM_STATES[number];
51
+ export declare const ROUTINE_STATES: readonly ["active", "paused"];
52
+ export type RoutineState = typeof ROUTINE_STATES[number];
53
+ export declare const RUN_RESULTS: readonly ["ok", "failed", "skipped"];
54
+ export type RunResult = typeof RUN_RESULTS[number];
55
+ /**
56
+ * Where a task's pull request stands: `draft` (not ready for review), `open` (ready for review), `merged`, `closed`
57
+ * (closed without a merge). A reader that does not know the field shows the pull request as before.
58
+ */
59
+ export declare const PR_STATES: readonly ["draft", "open", "merged", "closed"];
60
+ export type PrState = typeof PR_STATES[number];
61
+ /** How a pull request's checks stand. */
62
+ export declare const PR_CHECKS: readonly ["passing", "failing", "pending"];
63
+ export type PrChecks = typeof PR_CHECKS[number];
64
+ export interface CardLink {
65
+ url: string;
66
+ label?: string;
67
+ }
68
+ export interface TaskItem {
69
+ text: string;
70
+ state: ItemState;
71
+ }
72
+ export interface TaskPr {
73
+ url: string;
74
+ number?: number;
75
+ additions?: number;
76
+ deletions?: number;
77
+ files?: number;
78
+ state?: PrState;
79
+ checks?: PrChecks;
80
+ }
81
+ export interface TaskCard {
82
+ kind: "task";
83
+ id: string;
84
+ title: string;
85
+ status: TaskStatus;
86
+ /** 0 to 100. */
87
+ progress?: number;
88
+ /** Steps done of `total`. */
89
+ done?: number;
90
+ total?: number;
91
+ /** What it is doing now. */
92
+ step?: string;
93
+ pr?: TaskPr;
94
+ branch?: string;
95
+ startedAt?: number;
96
+ updatedAt?: number;
97
+ items?: TaskItem[];
98
+ links?: CardLink[];
99
+ /** Up to `STATUS_CARD_LIMITS.tags` short labels (an area, a repository), shown as chips. */
100
+ tags?: string[];
101
+ /** The id of another task of the same sender in the same chat that this one is a part of. */
102
+ parent?: string;
103
+ }
104
+ export interface RoutineRun {
105
+ at: number;
106
+ result: RunResult;
107
+ summary?: string;
108
+ }
109
+ export interface RoutineCard {
110
+ kind: "routine";
111
+ id: string;
112
+ name: string;
113
+ /** When it runs, as people say it ("every day 01:00"). */
114
+ schedule: string;
115
+ cron?: string;
116
+ state: RoutineState;
117
+ lastRun?: RoutineRun;
118
+ nextRunAt?: number;
119
+ /** Recent runs, newest first. */
120
+ runs?: RoutineRun[];
121
+ links?: CardLink[];
122
+ }
123
+ /**
124
+ * A button under a bot's message (WISP 406 · Message Buttons). `once`: a press on it answers the question for that
125
+ * person, and their app offers none of the buttons again; a button without it may be pressed again.
126
+ */
127
+ export interface CardButton {
128
+ id: string;
129
+ label: string;
130
+ style?: ButtonStyle;
131
+ once?: true;
132
+ }
133
+ /**
134
+ * Buttons under a bot's message (WISP 406 · Message Buttons): unlike a task or a routine, the message's text shows
135
+ * with them, and is also what an app without buttons shows (so it should say how to answer in words). `chosen` is the
136
+ * answer the bot took, marked for everyone; `closed`: no button takes a press any more.
137
+ */
138
+ export interface ButtonsCard {
139
+ kind: "buttons";
140
+ id: string;
141
+ buttons: CardButton[];
142
+ chosen?: string;
143
+ closed?: true;
144
+ }
145
+ /**
146
+ * A mini-app the sender shared in the chat, or opened in it (WISP 405 § An app, WISP 1200 § Apps sent in a chat): what a
147
+ * contact needs to install the same app and check it. Every field is the sender's claim, unsigned; nothing is fetched to
148
+ * show it. `id` is made from `ref` (`appCardId`); `opened` only for "Ana opened Chess".
149
+ */
150
+ export interface AppCard {
151
+ kind: "app";
152
+ id: string;
153
+ ref: string;
154
+ digest: string;
155
+ sequence: number;
156
+ title: string;
157
+ version?: string;
158
+ url?: string;
159
+ opened?: true;
160
+ }
161
+ /** Another window of a usage card ("week"): how much of it is left, and when it starts again. */
162
+ export interface UsageWindow {
163
+ window: string;
164
+ left: number;
165
+ resetsAt?: number;
166
+ }
167
+ /**
168
+ * How much of a quota a bot has left (WISP 405 § Usage): "Claude, 62% left of the 5 h window, resets 18:00". `left` is
169
+ * the percent left, 0 to 100; a bot that counts can say `used` of `limit` instead, and the percent is worked out
170
+ * (`usageLeft`). `windows`: other windows of the same quota (a week), shown in the details. One per chat stands: the
171
+ * latest a sender changed. Display only, like every card.
172
+ */
173
+ export interface UsageCard {
174
+ kind: "usage";
175
+ id: string;
176
+ /** 0 to 100: how much is left, in percent. */
177
+ left?: number;
178
+ used?: number;
179
+ limit?: number;
180
+ /** What the quota is of ("Claude"). */
181
+ label?: string;
182
+ /** Which of the bot's accounts it is, short. */
183
+ account?: string;
184
+ /** The quota's window, as people say it ("5 h", "week"). */
185
+ window?: string;
186
+ /** When the window starts again: milliseconds. */
187
+ resetsAt?: number;
188
+ /** When the bot read the numbers: milliseconds. */
189
+ updatedAt?: number;
190
+ windows?: UsageWindow[];
191
+ }
192
+ export type StatusCard = TaskCard | RoutineCard | ButtonsCard | AppCard | UsageCard;
193
+ export type StatusCardKind = StatusCard["kind"];
194
+ /** A button's id: 1 to 32 of `A-Z a-z 0-9 _ . : -`, not starting with `-`. */
195
+ export declare const BUTTON_ID: RegExp;
196
+ /**
197
+ * Whether a typed answer is a button's label or id (WISP 406 · Message Buttons): ignoring case and spaces at the ends.
198
+ * Not the device's locale's case: the presser's and the author's apps must agree ("I" is not "ı" anywhere).
199
+ */
200
+ export declare const sameButtonText: (a: string, b: string) => boolean;
201
+ /**
202
+ * Two buttons a typed answer could not tell apart, or none: a label that reads as an earlier label (`label`), or a
203
+ * label that reads as another button's id (`id`), both as `sameButtonText` compares them. The labels as a reader keeps
204
+ * them (one line, cleaned). `at` is the button that clashes, `with` the one it clashes with.
205
+ */
206
+ export declare function buttonLabelClash(buttons: readonly unknown[]): {
207
+ at: number;
208
+ with: number;
209
+ kind: "label" | "id";
210
+ } | undefined;
211
+ /** An app card's id, made from its reference: the app's name, a dot, the first 16 characters of the publisher key. */
212
+ export declare function appCardId(ref: string): string;
213
+ /** One line of display text: runs of space (line breaks included) become one space, then the display rules for names. */
214
+ export declare function cardLine(value: unknown, max: number): string | undefined;
215
+ /**
216
+ * An https link a card may show: no credentials, a host, no spaces or control characters, at most
217
+ * `STATUS_CARD_LIMITS.url` characters. Returned as the parser writes it (a non-ASCII host in punycode).
218
+ */
219
+ export declare function cardUrl(value: unknown): string | undefined;
220
+ /** The host a card shows beside a link, so the reader sees where it goes before following it. */
221
+ export declare function cardLinkHost(url: string): string;
222
+ /** How much of a usage card's quota is left, 0 to 100: its own percent, else worked out from used of limit. */
223
+ export declare function usageLeft(card: Pick<UsageCard, "left" | "used" | "limit">): number;
224
+ /** The bytes a card takes on the wire: what `STATUS_CARD_LIMITS.bytes` bounds. */
225
+ export declare function statusCardBytes(card: unknown): number;
226
+ /**
227
+ * A card as a reader takes it from the wire (`sc`), or undefined when it cannot stand: not an object, past
228
+ * `STATUS_CARD_LIMITS.bytes`, a kind this app does not know, no valid id, title or name, status or state. Fields that do
229
+ * not hold are left out and lists are cut to their bound; times are kept no later than the reader's clock allows (a
230
+ * routine's next run up to a year ahead). The message is always kept: without a card it shows its text.
231
+ */
232
+ export declare function readStatusCard(raw: unknown, now?: number): StatusCard | undefined;
233
+ /**
234
+ * A card as a sender may send it, or why not: the reader's rule, but anything it would leave out or cut is refused
235
+ * here instead (an unknown status, a link that is not https, a list past its bound, a line too long), so a bot learns
236
+ * at once and nothing it said is lost on the way. Line breaks and invisible characters are cleaned, as a reader would.
237
+ */
238
+ export declare function checkStatusCard(raw: unknown, now?: number): {
239
+ card: StatusCard;
240
+ } | {
241
+ error: string;
242
+ };
243
+ /** The progress a task shows, 0 to 100: its own, else its steps done of total; undefined when it says neither. */
244
+ export declare function taskProgress(card: Pick<TaskCard, "progress" | "done" | "total">): number | undefined;
245
+ /** A time as the fallback text says it: in UTC, to the minute ("2026-09-30 01:00 UTC"). */
246
+ export declare function cardTimeUtc(ms: number): string;
247
+ /**
248
+ * The text a card's message carries: what an app without cards shows, the DHT floor carries, the chat list previews
249
+ * and search finds. Plain lines, the first naming the card, no bars or layout that would read badly elsewhere.
250
+ */
251
+ export declare function statusCardText(card: StatusCard): string;
252
+ /** Whether a message's edit number holds: a text's bound, or a card message's when the edit carries a card. */
253
+ export declare function cardEditNumber(e: unknown): e is number;