@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,50 @@
|
|
|
1
|
+
import type { WalletNetwork } from "../../../core/src/index.js";
|
|
2
|
+
/**
|
|
3
|
+
* Mints a new wallet starts with, so nobody has to know what a mint is before
|
|
4
|
+
* receiving sats. The first one that answers is where Lightning invoices are
|
|
5
|
+
* created; ecash from any of them is accepted from contacts.
|
|
6
|
+
*
|
|
7
|
+
* A mint is a custodian: it holds the sats. This list is a product decision,
|
|
8
|
+
* to be reviewed regularly. It was picked on 2026-09-18 from the community
|
|
9
|
+
* auditor (https://audit.8333.space): mints with thousands of audited swaps,
|
|
10
|
+
* the highest success rates and an OK state at the time.
|
|
11
|
+
*/
|
|
12
|
+
export declare const DEFAULT_MINTS: string[];
|
|
13
|
+
/** Public test mint: worthless sats, invoices settle by themselves. */
|
|
14
|
+
export declare const TEST_MINT = "https://testnut.cashu.space";
|
|
15
|
+
/**
|
|
16
|
+
* Mints whose sats are worth nothing: never counted as money, never mixed with real sats.
|
|
17
|
+
* Mutinynet's mint (cashu.mutinynet.com) would belong here, but on 2026-09-22 it answered with a
|
|
18
|
+
* duplicated Access-Control-Allow-Origin header that every browser and WebView rejects.
|
|
19
|
+
*/
|
|
20
|
+
export declare const TEST_MINTS: readonly string[];
|
|
21
|
+
export declare const isTestMint: (url: string) => boolean;
|
|
22
|
+
/** A mint on this very machine (a local test server): whatever it issues is not money anyone else holds. */
|
|
23
|
+
export declare function isLocalMint(url: string): boolean;
|
|
24
|
+
/**
|
|
25
|
+
* Mints whose sats are worth nothing: the public test mints and mints on this machine. They belong to
|
|
26
|
+
* the Testnet mode, and their ecash never settles a request for real sats. Only the public test mints
|
|
27
|
+
* are ever added by themselves (a contact must not make this app contact a port on this machine).
|
|
28
|
+
*/
|
|
29
|
+
export declare const isWorthlessMint: (url: string) => boolean;
|
|
30
|
+
/**
|
|
31
|
+
* A mint whose word "this invoice is paid" proves nobody paid it. The public test mint runs a fake Lightning backend
|
|
32
|
+
* that marks every invoice paid by itself, and a mint on this machine is a test server that may do the same. Its
|
|
33
|
+
* invoices are still shown to be paid, but the wallet mints one only once a payer says it paid it (see `held` on
|
|
34
|
+
* StoredQuote); asking it for test coins on purpose is `CashuWallet.testCoins`.
|
|
35
|
+
*/
|
|
36
|
+
export declare const paysItsOwnInvoices: (url: string) => boolean;
|
|
37
|
+
export declare function declareTestMints(urls: readonly string[]): void;
|
|
38
|
+
/**
|
|
39
|
+
* Whether a Testnet wallet may pay a Bitcoin (`lnbc`) invoice through this mint. Test mints issue `lnbc` invoices,
|
|
40
|
+
* but so does a real node: only a mint known to fake its Lightning moves nothing real when it pays one. That is the
|
|
41
|
+
* public test mint, or a mint on this machine the operator declared a test server; never any other mint on this
|
|
42
|
+
* machine, which may be a self-hosted mint with real sats behind it.
|
|
43
|
+
*/
|
|
44
|
+
export declare const fakesLightning: (url: string) => boolean;
|
|
45
|
+
/** Refused before any mint is asked: see `fakesLightning`. */
|
|
46
|
+
export declare const BITCOIN_INVOICE_ON_TESTNET = "This is a Bitcoin invoice (real money): test sats pay one only through the public test mint. Nothing was sent.";
|
|
47
|
+
/** Real money, or test networks: each wallet has its own (see WalletNetwork in @ghostly/core). */
|
|
48
|
+
export type WalletMode = WalletNetwork;
|
|
49
|
+
/** The network a Cashu mint's ecash belongs to: test mints and mints on this machine are Testnet. */
|
|
50
|
+
export declare const mintNetwork: (url: string) => WalletNetwork;
|
|
@@ -0,0 +1,173 @@
|
|
|
1
|
+
import { type AppSignature } from "./appStatements.js";
|
|
2
|
+
import type { Signer } from "./signer.js";
|
|
3
|
+
export declare const APP_BUNDLE_MAGIC = "GHOSTLYAPP1";
|
|
4
|
+
export declare const APP_BUNDLE_LIMITS: {
|
|
5
|
+
/** The whole bundle, phase 1. */
|
|
6
|
+
readonly bundleBytes: number;
|
|
7
|
+
readonly files: 64;
|
|
8
|
+
readonly manifestBytes: number;
|
|
9
|
+
/** A path, in bytes (paths are ASCII). */
|
|
10
|
+
readonly pathBytes: 128;
|
|
11
|
+
readonly iconBytes: number;
|
|
12
|
+
/** The icon's width and height, in pixels: a client decodes it whole to draw it, whatever its bytes. */
|
|
13
|
+
readonly iconEdge: 1024;
|
|
14
|
+
readonly screenshots: 8;
|
|
15
|
+
/** Lengths in Unicode code points. */
|
|
16
|
+
readonly title: 40;
|
|
17
|
+
readonly tagline: 80;
|
|
18
|
+
readonly description: 2000;
|
|
19
|
+
readonly releaseNotes: 500;
|
|
20
|
+
readonly version: 64;
|
|
21
|
+
readonly license: 128;
|
|
22
|
+
/** An https URL, in characters. */
|
|
23
|
+
readonly url: 512;
|
|
24
|
+
readonly sources: 8;
|
|
25
|
+
};
|
|
26
|
+
export declare const APP_ICON_PATH = "icon.png";
|
|
27
|
+
export declare const APP_SCREENSHOTS_DIR = "screenshots/";
|
|
28
|
+
/**
|
|
29
|
+
* The permissions of phase 1 (WISP 1200 · Permissions). `internet`: the app reaches HTTPS and WSS servers of its
|
|
30
|
+
* choosing (the client runs it in its network runner); without it, an app has no network.
|
|
31
|
+
*/
|
|
32
|
+
export declare const APP_PERMISSIONS: readonly ["chat", "internet", "name"];
|
|
33
|
+
export type AppPermission = typeof APP_PERMISSIONS[number];
|
|
34
|
+
/**
|
|
35
|
+
* The clients a writer may name in `runtime.clients` (WISP 1200 · Manifest). A reader also accepts a client name it does
|
|
36
|
+
* not know (`APP_CLIENT_NAME`), since `runtime` is advisory and a later client (Android, say) must not make every older
|
|
37
|
+
* reader refuse the bundle.
|
|
38
|
+
*/
|
|
39
|
+
export declare const APP_CLIENTS: readonly ["web", "desktop", "extension"];
|
|
40
|
+
/** A client name a reader accepts in `runtime.clients`, a later client's included. */
|
|
41
|
+
export declare const APP_CLIENT_NAME: RegExp;
|
|
42
|
+
/**
|
|
43
|
+
* Where an app shows (WISP 1200 · Manifest, `view`). `chat`, the default when the manifest has none: inside a 1:1 chat
|
|
44
|
+
* only, beside it on a wide screen. `full`: full screen, alone or from a chat, never beside one.
|
|
45
|
+
*/
|
|
46
|
+
export declare const APP_VIEWS: readonly ["chat", "full"];
|
|
47
|
+
export type AppViewMode = typeof APP_VIEWS[number];
|
|
48
|
+
/** The view of a manifest: `chat` when it names none. */
|
|
49
|
+
export declare const appViewOf: (manifest: {
|
|
50
|
+
view?: AppViewMode;
|
|
51
|
+
}) => AppViewMode;
|
|
52
|
+
export type AppClient = typeof APP_CLIENTS[number];
|
|
53
|
+
export interface AppFileEntry {
|
|
54
|
+
path: string;
|
|
55
|
+
size: number;
|
|
56
|
+
sha256: string;
|
|
57
|
+
}
|
|
58
|
+
export interface AppManifest {
|
|
59
|
+
ghostlyApp: 1;
|
|
60
|
+
publisher: string;
|
|
61
|
+
name: string;
|
|
62
|
+
version: string;
|
|
63
|
+
sequence: number;
|
|
64
|
+
kind: "mini-app";
|
|
65
|
+
title: string;
|
|
66
|
+
tagline: string;
|
|
67
|
+
description?: string;
|
|
68
|
+
entry: string;
|
|
69
|
+
permissions: AppPermission[];
|
|
70
|
+
/** Absent: `chat` (`appViewOf`). */
|
|
71
|
+
view?: AppViewMode;
|
|
72
|
+
/** Advisory: a writer names only `APP_CLIENTS`; a reader may hold a later client's name. */
|
|
73
|
+
runtime: {
|
|
74
|
+
host: string;
|
|
75
|
+
clients: string[];
|
|
76
|
+
};
|
|
77
|
+
license: string;
|
|
78
|
+
sources?: string[];
|
|
79
|
+
proofs?: never[];
|
|
80
|
+
homepage?: string;
|
|
81
|
+
support?: string;
|
|
82
|
+
releaseNotes?: string;
|
|
83
|
+
files: AppFileEntry[];
|
|
84
|
+
}
|
|
85
|
+
/**
|
|
86
|
+
* How `checkAppManifest` treats a key it does not know. A reader (`readAppBundle`, the client) ignores it, at the top of
|
|
87
|
+
* the manifest and in `runtime`, so a later publisher can add an optional key without every older client refusing the
|
|
88
|
+
* app; the publisher's signature and the digest still cover the manifest's bytes as they are. A writer
|
|
89
|
+
* (`buildAppBundle`, the CLI) passes `strict` and refuses it, so a misspelt key is caught before anything is signed.
|
|
90
|
+
* Required keys, their types and bounds, `price` and `recovery`, and a file's exact `{path, size, sha256}` (which lay
|
|
91
|
+
* out the bundle's bytes) hold in both.
|
|
92
|
+
*/
|
|
93
|
+
export interface AppManifestOptions {
|
|
94
|
+
strict?: boolean;
|
|
95
|
+
}
|
|
96
|
+
/**
|
|
97
|
+
* Keys refused in every mode and at any level, wherever a reader ignores unknown keys: kept and passed on, they would
|
|
98
|
+
* name an object's prototype the moment anything spreads or assigns a manifest or a listing.
|
|
99
|
+
*/
|
|
100
|
+
export declare const APP_FORBIDDEN_KEYS: readonly string[];
|
|
101
|
+
/**
|
|
102
|
+
* The path of an `APP_FORBIDDEN_KEYS` key anywhere in a parsed JSON value (`later.0.__proto__`), the values of ignored
|
|
103
|
+
* keys included, or undefined: WISP 1200 refuses them at any level. `JSON.parse` makes `__proto__` an own key, so
|
|
104
|
+
* `Object.keys` sees it. A stack, not recursion: a `listing.json` is read with `JSON.parse` alone, at any depth.
|
|
105
|
+
*/
|
|
106
|
+
export declare function findAppForbiddenKey(value: unknown): string | undefined;
|
|
107
|
+
export type AppBundleRefusal = "too-large" | "magic" | "truncated" | "trailing-bytes" | "manifest-too-large" | "not-json" | "not-canonical" | "unsupported-format" | "unknown-key" | "reserved-key" | "missing-key" | "bad-field" | "proofs-unsupported" | "too-many-files" | "bad-path" | "path-collision" | "files-unsorted" | "bad-entry" | "too-many-screenshots" | "bad-icon" | "bad-signature-statement" | "signature-key" | "bad-signature" | "file-hash";
|
|
108
|
+
export type AppManifestCheck = {
|
|
109
|
+
ok: true;
|
|
110
|
+
manifest: AppManifest;
|
|
111
|
+
} | {
|
|
112
|
+
ok: false;
|
|
113
|
+
reason: AppBundleRefusal;
|
|
114
|
+
detail?: string;
|
|
115
|
+
};
|
|
116
|
+
/**
|
|
117
|
+
* An https URL as WISP 1200 takes one anywhere: at most 512 characters, no user or password, and on jsDelivr only
|
|
118
|
+
* `https://cdn.jsdelivr.net/gh/<owner>/<repo>@<40-hex commit>/...`, since a branch, a tag, a range or `latest` is
|
|
119
|
+
* served from a copy that moves.
|
|
120
|
+
*/
|
|
121
|
+
export declare function isAppUrl(value: unknown): value is string;
|
|
122
|
+
/**
|
|
123
|
+
* An SPDX license expression, read lightly: identifiers (`MIT`, `GPL-3.0-or-later`, `LicenseRef-x`, `Apache-2.0+`)
|
|
124
|
+
* joined by `AND` and `OR`, `WITH` an exception, and parentheses; or `proprietary`.
|
|
125
|
+
*/
|
|
126
|
+
export declare function isAppLicense(value: unknown): value is string;
|
|
127
|
+
/** A path of a bundle: relative, `/`-separated, `[A-Za-z0-9._-]` per segment, no `.` or `..`, at most 128 bytes. */
|
|
128
|
+
export declare function isAppPath(value: unknown): value is string;
|
|
129
|
+
/**
|
|
130
|
+
* Checks a parsed manifest against every rule and bound of WISP 1200 that the manifest alone decides. An unknown key is
|
|
131
|
+
* ignored unless `strict` (`AppManifestOptions`).
|
|
132
|
+
*/
|
|
133
|
+
export declare function checkAppManifest(value: unknown, options?: AppManifestOptions): AppManifestCheck;
|
|
134
|
+
/** The digest of a version: SHA-256 of its canonical manifest bytes, base64url. */
|
|
135
|
+
export declare function appDigest(manifestBytes: Uint8Array): string;
|
|
136
|
+
export interface AppBundle {
|
|
137
|
+
manifest: AppManifest;
|
|
138
|
+
/** The manifest's canonical bytes, as in the bundle. */
|
|
139
|
+
manifestBytes: Uint8Array;
|
|
140
|
+
digest: string;
|
|
141
|
+
signature: AppSignature;
|
|
142
|
+
/** Every file's bytes, by path, in the manifest's order (views into the bundle's bytes). */
|
|
143
|
+
files: Map<string, Uint8Array>;
|
|
144
|
+
}
|
|
145
|
+
export type AppBundleReading = {
|
|
146
|
+
ok: true;
|
|
147
|
+
bundle: AppBundle;
|
|
148
|
+
} | {
|
|
149
|
+
ok: false;
|
|
150
|
+
reason: AppBundleRefusal;
|
|
151
|
+
detail?: string;
|
|
152
|
+
};
|
|
153
|
+
/** Reads and checks a bundle (the order of the checks is part of the format: see above). */
|
|
154
|
+
export declare function readAppBundle(bytes: Uint8Array): AppBundleReading;
|
|
155
|
+
/** Puts a bundle's parts together, checking nothing: for builders, and for tests that need a broken bundle. */
|
|
156
|
+
export declare function assembleAppBundle(manifestBytes: Uint8Array, statementBytes: Uint8Array, files: Uint8Array[]): Uint8Array;
|
|
157
|
+
/** What a publisher writes: every manifest field but `publisher` and `files`, which the bundle's contents decide. */
|
|
158
|
+
export type AppManifestDraft = Omit<AppManifest, "publisher" | "files" | "ghostlyApp"> & {
|
|
159
|
+
ghostlyApp?: 1;
|
|
160
|
+
};
|
|
161
|
+
/**
|
|
162
|
+
* Builds and signs a bundle: lists the files (sorted, with sizes and hashes), signs the canonical manifest with the
|
|
163
|
+
* publisher's key under `ghostly-app/1`, and reads the result back, so it throws rather than return a bundle a client
|
|
164
|
+
* would refuse.
|
|
165
|
+
*/
|
|
166
|
+
export declare function buildAppBundle(draft: AppManifestDraft, files: {
|
|
167
|
+
path: string;
|
|
168
|
+
bytes: Uint8Array;
|
|
169
|
+
}[], signer: Signer): Promise<{
|
|
170
|
+
bytes: Uint8Array;
|
|
171
|
+
digest: string;
|
|
172
|
+
manifest: AppManifest;
|
|
173
|
+
}>;
|
|
@@ -0,0 +1,142 @@
|
|
|
1
|
+
import { type CanonicalJsonRefusal, type JsonValue } from "./canonicalJson.js";
|
|
2
|
+
import type { Signer } from "./signer.js";
|
|
3
|
+
/** The prefixes of phase 1. The others of the WISP (reports, reviews, licences, rotation, publisher proofs) come later. */
|
|
4
|
+
export declare const APP_PREFIXES: {
|
|
5
|
+
readonly app: "ghostly-app/1";
|
|
6
|
+
readonly store: "ghostly-store/1";
|
|
7
|
+
readonly revoke: "ghostly-revoke/1";
|
|
8
|
+
};
|
|
9
|
+
export type AppPrefix = typeof APP_PREFIXES[keyof typeof APP_PREFIXES];
|
|
10
|
+
export declare const APP_STATEMENT_LIMITS: {
|
|
11
|
+
/** A signature statement's canonical bytes: 52 + 86 characters of values and the keys around them. */
|
|
12
|
+
readonly signatureBytes: 1024;
|
|
13
|
+
/** Digests named by one revocation. */
|
|
14
|
+
readonly revokeDigests: 64;
|
|
15
|
+
/** A revocation's reason, in characters. */
|
|
16
|
+
readonly reason: 200;
|
|
17
|
+
/** Revocations in one `ghostly-revoke.json`. */
|
|
18
|
+
readonly revocations: 4096;
|
|
19
|
+
};
|
|
20
|
+
/** A z-base32 Ed25519 public key: 52 characters that decode to 32 bytes and encode back to the same text. */
|
|
21
|
+
export declare function isAppKey(value: unknown): value is string;
|
|
22
|
+
/** A SHA-256 in base64url without padding: 43 characters that decode to 32 bytes and encode back to the same text. */
|
|
23
|
+
export declare function isAppHash(value: unknown): value is string;
|
|
24
|
+
/** An app reference, `<publisher key>/<name>`. */
|
|
25
|
+
export declare const APP_NAME: RegExp;
|
|
26
|
+
export declare function isAppRef(value: unknown): value is string;
|
|
27
|
+
export declare function appRef(publisher: string, name: string): string;
|
|
28
|
+
/** The publisher key of a reference. */
|
|
29
|
+
export declare function appRefPublisher(ref: string): string;
|
|
30
|
+
/**
|
|
31
|
+
* The publisher fingerprint people see: the first 16 z-base32 characters of the key (80 bits), in four groups.
|
|
32
|
+
*/
|
|
33
|
+
export declare function appFingerprint(key: string): string;
|
|
34
|
+
/** The bytes a signature covers: the prefix, a zero byte, then the SHA-256 of the object's canonical bytes. */
|
|
35
|
+
export declare function appSignedBytes(prefix: AppPrefix, canonical: Uint8Array): Uint8Array;
|
|
36
|
+
export interface AppSignature {
|
|
37
|
+
alg: "ed25519";
|
|
38
|
+
key: string;
|
|
39
|
+
sig: string;
|
|
40
|
+
}
|
|
41
|
+
/** Signs an object under a prefix: its canonical bytes and the signature statement. */
|
|
42
|
+
export declare function signAppObject(prefix: AppPrefix, value: unknown, signer: Signer): Promise<{
|
|
43
|
+
bytes: Uint8Array;
|
|
44
|
+
signature: AppSignature;
|
|
45
|
+
}>;
|
|
46
|
+
export type AppSignatureRefusal = "bad-signature-statement" | "signature-key" | "bad-signature";
|
|
47
|
+
/** Checks the shape of a signature statement: exactly `alg`, `key` and `sig`, a 64-byte signature. */
|
|
48
|
+
export declare function isAppSignature(value: unknown): value is AppSignature;
|
|
49
|
+
/** Reads a signature statement from its bytes, which must be canonical. */
|
|
50
|
+
export declare function readAppSignature(bytes: Uint8Array): {
|
|
51
|
+
ok: true;
|
|
52
|
+
signature: AppSignature;
|
|
53
|
+
} | {
|
|
54
|
+
ok: false;
|
|
55
|
+
reason: "bad-signature-statement";
|
|
56
|
+
detail?: string;
|
|
57
|
+
};
|
|
58
|
+
/**
|
|
59
|
+
* Verifies a signature over an object's canonical bytes under a prefix, made by `key`: `signature-key` when the
|
|
60
|
+
* statement names another key, `bad-signature` when it does not verify.
|
|
61
|
+
*/
|
|
62
|
+
export declare function verifyAppSignature(prefix: AppPrefix, canonical: Uint8Array, signature: AppSignature, key: string): {
|
|
63
|
+
ok: true;
|
|
64
|
+
} | {
|
|
65
|
+
ok: false;
|
|
66
|
+
reason: AppSignatureRefusal;
|
|
67
|
+
};
|
|
68
|
+
/** Verifies a signed object given as bytes: they must be canonical, then the signature as above. */
|
|
69
|
+
export declare function verifyAppStatementBytes(prefix: AppPrefix, bytes: Uint8Array, signature: AppSignature, key: string): {
|
|
70
|
+
ok: true;
|
|
71
|
+
value: JsonValue;
|
|
72
|
+
} | {
|
|
73
|
+
ok: false;
|
|
74
|
+
reason: CanonicalJsonRefusal | AppSignatureRefusal;
|
|
75
|
+
};
|
|
76
|
+
/** A publisher's revocation: the listed digests of its app, or every version up to `upTo` (inclusive). */
|
|
77
|
+
export type AppRevokeStatement = {
|
|
78
|
+
ghostlyRevoke: 1;
|
|
79
|
+
app: string;
|
|
80
|
+
digests: string[];
|
|
81
|
+
reason?: string;
|
|
82
|
+
} | {
|
|
83
|
+
ghostlyRevoke: 1;
|
|
84
|
+
app: string;
|
|
85
|
+
upTo: number;
|
|
86
|
+
reason?: string;
|
|
87
|
+
};
|
|
88
|
+
export interface SignedAppRevocation {
|
|
89
|
+
statement: AppRevokeStatement;
|
|
90
|
+
signature: AppSignature;
|
|
91
|
+
}
|
|
92
|
+
export type AppRevocationRefusal = "bad-revocation" | AppSignatureRefusal;
|
|
93
|
+
/** Checks a revocation statement's shape; the reason it is refused, or null. */
|
|
94
|
+
export declare function checkAppRevokeStatement(value: unknown): string | null;
|
|
95
|
+
/** Signs a revocation with the publisher's key. */
|
|
96
|
+
export declare function signAppRevocation(statement: AppRevokeStatement, signer: Signer): Promise<SignedAppRevocation>;
|
|
97
|
+
/**
|
|
98
|
+
* The revocations a reader has already checked, by `appRevocationId`: a store index copies its `revoked` again in every
|
|
99
|
+
* version, so a reader that holds this checks each revocation's signature once. The reader bounds what it holds.
|
|
100
|
+
*/
|
|
101
|
+
export interface AppRevocationsChecked {
|
|
102
|
+
has(id: string): boolean;
|
|
103
|
+
add(id: string): void;
|
|
104
|
+
}
|
|
105
|
+
/** What a checked revocation is kept by: the SHA-256 of its canonical bytes (statement and signature), base64url. */
|
|
106
|
+
export declare function appRevocationId(revocation: SignedAppRevocation): string;
|
|
107
|
+
type AppRevocationRead = {
|
|
108
|
+
ok: true;
|
|
109
|
+
revocation: SignedAppRevocation;
|
|
110
|
+
} | {
|
|
111
|
+
ok: false;
|
|
112
|
+
reason: AppRevocationRefusal;
|
|
113
|
+
detail?: string;
|
|
114
|
+
};
|
|
115
|
+
/**
|
|
116
|
+
* Reads one signed revocation (a parsed value, from `ghostly-revoke.json` or a store index's `revoked`): its shape, then
|
|
117
|
+
* the signature under `ghostly-revoke/1` by the publisher its `app` names. One that `checked` holds verified before, so
|
|
118
|
+
* its signature is not checked again; one that verifies now is added to it.
|
|
119
|
+
*/
|
|
120
|
+
export declare function readAppRevocation(value: unknown, checked?: AppRevocationsChecked): AppRevocationRead;
|
|
121
|
+
/** The first half of `readAppRevocation`: the shape of a signed revocation, with no signature checked. */
|
|
122
|
+
export declare function readAppRevocationShape(value: unknown): AppRevocationRead;
|
|
123
|
+
/** The second half: the signature of a revocation of the right shape, unless `checked` holds it. */
|
|
124
|
+
export declare function verifyAppRevocation(revocation: SignedAppRevocation, checked?: AppRevocationsChecked): {
|
|
125
|
+
ok: true;
|
|
126
|
+
} | {
|
|
127
|
+
ok: false;
|
|
128
|
+
reason: AppSignatureRefusal;
|
|
129
|
+
};
|
|
130
|
+
/**
|
|
131
|
+
* Reads `ghostly-revoke.json`: canonical bytes holding a list of signed revocations. One that does not verify refuses the
|
|
132
|
+
* file, as a store index's `revoked` does.
|
|
133
|
+
*/
|
|
134
|
+
export declare function readAppRevocations(bytes: Uint8Array): {
|
|
135
|
+
ok: true;
|
|
136
|
+
revocations: SignedAppRevocation[];
|
|
137
|
+
} | {
|
|
138
|
+
ok: false;
|
|
139
|
+
reason: CanonicalJsonRefusal | AppRevocationRefusal;
|
|
140
|
+
detail?: string;
|
|
141
|
+
};
|
|
142
|
+
export {};
|
|
@@ -0,0 +1,133 @@
|
|
|
1
|
+
import { type AppRevocationsChecked, type AppSignature, type SignedAppRevocation } from "./appStatements.js";
|
|
2
|
+
import type { Signer } from "./signer.js";
|
|
3
|
+
export declare const APP_STORE_LIMITS: {
|
|
4
|
+
/** The index's bytes, uncompressed. */
|
|
5
|
+
readonly indexBytes: number;
|
|
6
|
+
/** How far ahead `expires` may be. */
|
|
7
|
+
readonly expiresAheadS: number;
|
|
8
|
+
readonly name: 40;
|
|
9
|
+
readonly description: 2000;
|
|
10
|
+
readonly title: 40;
|
|
11
|
+
readonly tagline: 80;
|
|
12
|
+
/** `category`, `developer`, `submitter`. */
|
|
13
|
+
readonly label: 40;
|
|
14
|
+
readonly reason: 200;
|
|
15
|
+
readonly urls: 4;
|
|
16
|
+
readonly apps: 4096;
|
|
17
|
+
readonly removed: 4096;
|
|
18
|
+
readonly revoked: 4096;
|
|
19
|
+
};
|
|
20
|
+
export declare const APP_STORE_KINDS: readonly ["curated", "indexed"];
|
|
21
|
+
export type AppStoreKind = typeof APP_STORE_KINDS[number];
|
|
22
|
+
export interface AppListing {
|
|
23
|
+
ref: string;
|
|
24
|
+
sequence: number;
|
|
25
|
+
digest: string;
|
|
26
|
+
urls: string[];
|
|
27
|
+
title: string;
|
|
28
|
+
tagline: string;
|
|
29
|
+
category?: string;
|
|
30
|
+
developer?: string;
|
|
31
|
+
submitter?: string;
|
|
32
|
+
repo?: string;
|
|
33
|
+
support?: string;
|
|
34
|
+
}
|
|
35
|
+
export interface AppRemoval {
|
|
36
|
+
ref: string;
|
|
37
|
+
digest: string;
|
|
38
|
+
reason: string;
|
|
39
|
+
at: number;
|
|
40
|
+
}
|
|
41
|
+
export interface AppStoreIndex {
|
|
42
|
+
ghostlyStore: 1;
|
|
43
|
+
key: string;
|
|
44
|
+
name: string;
|
|
45
|
+
description?: string;
|
|
46
|
+
kind: AppStoreKind;
|
|
47
|
+
sequence: number;
|
|
48
|
+
expires: number;
|
|
49
|
+
apps: AppListing[];
|
|
50
|
+
removed: AppRemoval[];
|
|
51
|
+
revoked: SignedAppRevocation[];
|
|
52
|
+
}
|
|
53
|
+
export type AppStoreRefusal = "too-large" | "not-json" | "not-canonical" | "unsupported-format" | "unknown-key" | "missing-key" | "bad-field" | "duplicate-app" | "bad-signature-statement" | "signature-key" | "bad-signature" | "store-key" | "expires-too-far" | "bad-revocation";
|
|
54
|
+
type Check = {
|
|
55
|
+
ok: true;
|
|
56
|
+
} | {
|
|
57
|
+
ok: false;
|
|
58
|
+
reason: AppStoreRefusal;
|
|
59
|
+
detail?: string;
|
|
60
|
+
};
|
|
61
|
+
/**
|
|
62
|
+
* How a check treats a key it does not know. A reader (`readAppStore`, the client) ignores it, so a later format can
|
|
63
|
+
* add an optional key without a client refusing the whole signed index; the signature still covers the bytes as they
|
|
64
|
+
* are, unknown keys included. A writer (`signAppStore`, the CLI, a store's check of a `listing.json` through
|
|
65
|
+
* `readAppListing`) passes `strict` and refuses it, so a misspelt key is caught before anything is signed. Required
|
|
66
|
+
* keys, their types and their bounds hold in both, and `APP_FORBIDDEN_KEYS` are refused in both, at any level.
|
|
67
|
+
*/
|
|
68
|
+
export interface AppFormatOptions {
|
|
69
|
+
strict?: boolean;
|
|
70
|
+
}
|
|
71
|
+
/** Checks one entry of `apps`, which is also the whole of a `listing.json`. An unknown key is ignored unless `strict`. */
|
|
72
|
+
export declare function checkAppListing(value: unknown, options?: AppFormatOptions): Check;
|
|
73
|
+
/**
|
|
74
|
+
* Reads a `listing.json`: JSON holding exactly one listing (written by hand in release 1.2, so not required canonical).
|
|
75
|
+
* A store reads it, as a writer: strict by default, so a misspelt key is refused before the owner signs the index (the
|
|
76
|
+
* client never reads a `listing.json`, only the signed index). `{ strict: false }` reads it as a client reads an index
|
|
77
|
+
* entry, ignoring a later key.
|
|
78
|
+
*/
|
|
79
|
+
export declare function readAppListing(text: string, options?: AppFormatOptions): {
|
|
80
|
+
ok: true;
|
|
81
|
+
listing: AppListing;
|
|
82
|
+
} | {
|
|
83
|
+
ok: false;
|
|
84
|
+
reason: AppStoreRefusal;
|
|
85
|
+
detail?: string;
|
|
86
|
+
};
|
|
87
|
+
/**
|
|
88
|
+
* Checks an index's fields and bounds, and every revocation it carries (one that does not verify refuses the index:
|
|
89
|
+
* the store copied it, so a broken one is the store's fault). The signature and `expires` are `readAppStore`'s. An
|
|
90
|
+
* unknown key of the index, a listing or a removal is ignored unless `strict`; a revocation is its publisher's signed
|
|
91
|
+
* statement and keeps its exact keys.
|
|
92
|
+
*/
|
|
93
|
+
export declare function checkAppStoreIndex(value: unknown, options?: AppFormatOptions): Check;
|
|
94
|
+
export interface AppStoreReading {
|
|
95
|
+
index: AppStoreIndex;
|
|
96
|
+
/** SHA-256 of the index's bytes, base64url: what the update rule compares at one `sequence`. */
|
|
97
|
+
digest: string;
|
|
98
|
+
/** Past `expires`: it still installs, and the Apps page says when the store was last updated. */
|
|
99
|
+
expired: boolean;
|
|
100
|
+
}
|
|
101
|
+
export type AppStoreRead = {
|
|
102
|
+
ok: true;
|
|
103
|
+
store: AppStoreReading;
|
|
104
|
+
} | {
|
|
105
|
+
ok: false;
|
|
106
|
+
reason: AppStoreRefusal;
|
|
107
|
+
detail?: string;
|
|
108
|
+
};
|
|
109
|
+
/**
|
|
110
|
+
* Reads `ghostly-store.json` with its `ghostly-store.sig`, in this order: size, JSON, canonical bytes, fields and the
|
|
111
|
+
* shape of each revocation, the signature statement, the key the reader holds for this store (when it holds one), the
|
|
112
|
+
* signature, the signature of each revocation, then `expires` against `now` (seconds): more than 90 days ahead is
|
|
113
|
+
* refused, past is `expired`. The index's own signature comes before its revocations': an index nobody signed costs
|
|
114
|
+
* its reader one signature check, whatever it carries. A key it does not know is ignored (a later store's optional
|
|
115
|
+
* field) and stays in the bytes the signature covers.
|
|
116
|
+
*/
|
|
117
|
+
export declare function readAppStore(indexBytes: Uint8Array, sigBytes: Uint8Array, now: number, heldKey?: string): AppStoreRead;
|
|
118
|
+
/**
|
|
119
|
+
* `readAppStore` in steps, for a reader that shares its thread (a page): it stops after each listing, removal and
|
|
120
|
+
* revocation, and after each revocation's signature check, so the caller can let the thread go between two `next()`
|
|
121
|
+
* and an index of 4096 revocations never holds it for seconds. With `checked`, a revocation it holds is not checked again.
|
|
122
|
+
*/
|
|
123
|
+
export declare function readAppStoreSteps(indexBytes: Uint8Array, sigBytes: Uint8Array, now: number, heldKey?: string, checked?: AppRevocationsChecked): Generator<void, AppStoreRead>;
|
|
124
|
+
/**
|
|
125
|
+
* Signs an index with the store key: its canonical bytes and the `ghostly-store.sig` bytes. Throws on a bad index, and
|
|
126
|
+
* on a key this format does not define: a writer is strict, so a misspelt key is never signed.
|
|
127
|
+
*/
|
|
128
|
+
export declare function signAppStore(index: AppStoreIndex, signer: Signer): Promise<{
|
|
129
|
+
indexBytes: Uint8Array;
|
|
130
|
+
sigBytes: Uint8Array;
|
|
131
|
+
signature: AppSignature;
|
|
132
|
+
}>;
|
|
133
|
+
export {};
|
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
import { type SignedAppRevocation } from "./appStatements.js";
|
|
2
|
+
import type { AppRemoval, AppStoreKind } from "./appStore.js";
|
|
3
|
+
/** A version of an app, as the client holds it or a checked bundle shows it. */
|
|
4
|
+
export interface AppVersion {
|
|
5
|
+
ref: string;
|
|
6
|
+
sequence: number;
|
|
7
|
+
digest: string;
|
|
8
|
+
}
|
|
9
|
+
/**
|
|
10
|
+
* What a valid package means next to the installed one:
|
|
11
|
+
* - `update`: the same app with a higher `sequence`, from anywhere;
|
|
12
|
+
* - `same`: the version installed;
|
|
13
|
+
* - `rollback`: a lower `sequence`, never installed over a higher one;
|
|
14
|
+
* - `equivocation`: the same `sequence` with another digest; the client keeps what it runs, refuses the other and marks
|
|
15
|
+
* the app ("Two different versions 7 exist");
|
|
16
|
+
* - `other-app`: another reference (another publisher key or another name), never an update of this one.
|
|
17
|
+
*/
|
|
18
|
+
export type AppUpdateDecision = "update" | "same" | "rollback" | "equivocation" | "other-app";
|
|
19
|
+
export declare function appUpdateDecision(installed: AppVersion, candidate: AppVersion): AppUpdateDecision;
|
|
20
|
+
/** The permissions an update adds: when there is any, the update waits for the person, who sees only these. */
|
|
21
|
+
export declare function addedAppPermissions(granted: readonly string[], requested: readonly string[]): string[];
|
|
22
|
+
/**
|
|
23
|
+
* What to do with a newer package: install it (the permissions it keeps or drops apply by themselves) or ask about the
|
|
24
|
+
* permissions it adds. Anything but `update` from `appUpdateDecision` is not installed.
|
|
25
|
+
*/
|
|
26
|
+
export type AppUpdatePlan = {
|
|
27
|
+
action: "install";
|
|
28
|
+
} | {
|
|
29
|
+
action: "ask";
|
|
30
|
+
added: string[];
|
|
31
|
+
} | {
|
|
32
|
+
action: "refuse";
|
|
33
|
+
decision: Exclude<AppUpdateDecision, "update">;
|
|
34
|
+
};
|
|
35
|
+
export declare function planAppUpdate(installed: AppVersion & {
|
|
36
|
+
permissions: readonly string[];
|
|
37
|
+
}, candidate: AppVersion & {
|
|
38
|
+
permissions: readonly string[];
|
|
39
|
+
}): AppUpdatePlan;
|
|
40
|
+
/**
|
|
41
|
+
* The revocation that stops a version, or null: one signed by the app's own publisher (a reader verified it) that names
|
|
42
|
+
* its digest, or reaches its `sequence` with `upTo`.
|
|
43
|
+
*/
|
|
44
|
+
export declare function appRevocationFor(version: AppVersion, revocations: readonly SignedAppRevocation[]): SignedAppRevocation | null;
|
|
45
|
+
/** A store the person added, as the run check needs it. */
|
|
46
|
+
export interface AppStoreView {
|
|
47
|
+
key: string;
|
|
48
|
+
name: string;
|
|
49
|
+
kind: AppStoreKind;
|
|
50
|
+
removed: readonly AppRemoval[];
|
|
51
|
+
revoked: readonly SignedAppRevocation[];
|
|
52
|
+
}
|
|
53
|
+
/**
|
|
54
|
+
* The check before Install is enabled, at every update check and before a run:
|
|
55
|
+
* - `revoked`: its publisher revoked it; it stops, with no "Run anyway";
|
|
56
|
+
* - `removed`: a store the person added removed this digest; it stops and the person decides (Remove, Keep it stopped,
|
|
57
|
+
* or, behind Details, Run anyway);
|
|
58
|
+
* - `ok`.
|
|
59
|
+
* Revocations come from the app's sources and from every store's `revoked`; a store the person did not add has no say.
|
|
60
|
+
*/
|
|
61
|
+
export type AppRunCheck = {
|
|
62
|
+
status: "ok";
|
|
63
|
+
} | {
|
|
64
|
+
status: "revoked";
|
|
65
|
+
revocation: SignedAppRevocation;
|
|
66
|
+
} | {
|
|
67
|
+
status: "removed";
|
|
68
|
+
by: {
|
|
69
|
+
store: string;
|
|
70
|
+
name: string;
|
|
71
|
+
reason: string;
|
|
72
|
+
at: number;
|
|
73
|
+
}[];
|
|
74
|
+
};
|
|
75
|
+
export declare function checkAppBeforeRun(version: AppVersion, stores: readonly AppStoreView[], revocations?: readonly SignedAppRevocation[]): AppRunCheck;
|
|
76
|
+
/** A store index as the client holds it. */
|
|
77
|
+
export interface AppStoreVersion {
|
|
78
|
+
key: string;
|
|
79
|
+
sequence: number;
|
|
80
|
+
digest: string;
|
|
81
|
+
}
|
|
82
|
+
/**
|
|
83
|
+
* What a newly read index means next to the one held: `new` (none held), `update`, `same`, `rollback` (a lower
|
|
84
|
+
* `sequence`, refused), `equivocation` (the same `sequence`, other bytes: refused, the held one kept) or `other-key`
|
|
85
|
+
* (another store: a store is its key).
|
|
86
|
+
*/
|
|
87
|
+
export type AppStoreDecision = "new" | "update" | "same" | "rollback" | "equivocation" | "other-key";
|
|
88
|
+
export declare function appStoreDecision(held: AppStoreVersion | null, read: AppStoreVersion): AppStoreDecision;
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
import { type AtprotoPublicKey, type CborValue } from "./atprotoRepo.js";
|
|
2
|
+
import type { IdentityStatement } from "./identityProofs.js";
|
|
3
|
+
/**
|
|
4
|
+
* AT Protocol identity, the pure half (no network): handle and DID syntax, what a DID document says
|
|
5
|
+
* (the signing key, the PDS, the handle it claims), and the Ghostly proof record. Specs:
|
|
6
|
+
* https://atproto.com/specs/handle, https://atproto.com/specs/did, https://atproto.com/specs/record-key.
|
|
7
|
+
*/
|
|
8
|
+
/** The Ghostly proof record's collection (NSID under ghostly.tools). Lexicon: docs/lexicons/tools.ghostly.proof.json. */
|
|
9
|
+
export declare const ATPROTO_PROOF_COLLECTION = "tools.ghostly.proof";
|
|
10
|
+
/**
|
|
11
|
+
* What the OAuth sign-in asks for. `atproto` is required by every server; the granular repo scope lets
|
|
12
|
+
* Ghostly create and delete records of its own collection only: no posts, no DMs, no profile edits.
|
|
13
|
+
* Servers that predate granular permissions only know `transition:generic` (full access to the account's
|
|
14
|
+
* repository); Ghostly asks for it only when the person picks that option, after being told.
|
|
15
|
+
*/
|
|
16
|
+
export declare const ATPROTO_PROOF_SCOPE = "atproto repo:tools.ghostly.proof?action=create&action=delete";
|
|
17
|
+
export declare const ATPROTO_FULL_SCOPE = "atproto transition:generic";
|
|
18
|
+
/** Every scope the client metadata declares (a request may only use declared scopes). */
|
|
19
|
+
export declare const ATPROTO_DECLARED_SCOPE = "atproto repo:tools.ghostly.proof?action=create&action=delete transition:generic";
|
|
20
|
+
/** A handle as people type it ("@Alice.bsky.social", "alice.bsky.social") → canonical, or null. */
|
|
21
|
+
export declare function normalizeAtprotoHandle(input: string): string | null;
|
|
22
|
+
export type AtprotoDidMethod = "plc" | "web";
|
|
23
|
+
export declare function atprotoDidMethod(did: string): AtprotoDidMethod | null;
|
|
24
|
+
export declare const isAtprotoDid: (did: string) => boolean;
|
|
25
|
+
/** "did:plc:ab12cd…wxyz": the method, the first six and the last four characters. */
|
|
26
|
+
export declare function shortAtprotoDid(did: string): string;
|
|
27
|
+
/** The record key of a proof: its proof key (z-base-32, already a valid record key), so removal finds it. */
|
|
28
|
+
export declare function atprotoProofRkey(proofKey: string): string;
|
|
29
|
+
export interface AtprotoDidDocument {
|
|
30
|
+
did: string;
|
|
31
|
+
/** The repository signing key (`#atproto`). */
|
|
32
|
+
key: AtprotoPublicKey;
|
|
33
|
+
/** The PDS (`#atproto_pds`), as an https origin. */
|
|
34
|
+
pds: string;
|
|
35
|
+
/** The handle the document claims (first valid `at://`), normalized. Not verified: resolve it back. */
|
|
36
|
+
handle?: string;
|
|
37
|
+
}
|
|
38
|
+
/** A DID document (JSON already parsed) for `did`, strictly enough for atproto. Throws a message people can read. */
|
|
39
|
+
export declare function parseAtprotoDidDocument(doc: unknown, did: string): AtprotoDidDocument;
|
|
40
|
+
/** The record Ghostly writes: the statement, exactly, and when. */
|
|
41
|
+
export declare function atprotoProofRecord(statement: IdentityStatement, createdAt: Date): {
|
|
42
|
+
$type: string;
|
|
43
|
+
statement: string;
|
|
44
|
+
createdAt: string;
|
|
45
|
+
};
|
|
46
|
+
/** Checks a record read from a repository against the statement it must carry. */
|
|
47
|
+
export declare function checkAtprotoProofRecord(value: {
|
|
48
|
+
[key: string]: CborValue;
|
|
49
|
+
}, statement: IdentityStatement): void;
|