@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.
- package/README.md +13 -2
- package/dist/app.js +67 -0
- package/dist/app.js.map +1 -0
- package/dist/core.js +207 -0
- package/dist/core.js.map +1 -0
- package/dist/fakes-CBIuqo5e.js +536 -0
- package/dist/fakes-CBIuqo5e.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-BylxCPl4.js +76483 -0
- package/dist/keet-identity-key-BylxCPl4.js.map +1 -0
- package/dist/src-DCeLPsi-.js +31056 -0
- package/dist/src-DCeLPsi-.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 +403 -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 +90 -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 +1510 -0
- package/dist/types/core/src/groupCommits.d.ts +103 -0
- package/dist/types/core/src/groupCommunity.d.ts +714 -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 +710 -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 +141 -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 +437 -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 +151 -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-DBGw6wYt.js +106 -0
- package/dist/verify-DBGw6wYt.js.map +1 -0
- package/package.json +70 -4
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
import type { InvoiceStatus, LightningInvoice, LightningPayResult, LightningPaymentRef, LightningPaymentStatus, LightningProvider, LightningProviderDescriptor } from "./lightning.js";
|
|
2
|
+
import type { OnchainBalance, OnchainPrepared, OnchainProvider, OnchainProviderDescriptor, OnchainSendRequest, OnchainTx, OnchainTxStatus } from "./onchain.js";
|
|
3
|
+
/**
|
|
4
|
+
* Fake providers, for unit tests and e2e: they hold regtest "sats" in memory, so they only ever show up in
|
|
5
|
+
* the Testnet mode, and only when `localStorage["ghostly-test-providers"] === "1"` (or a test passes them
|
|
6
|
+
* to the registry itself). No network, no money.
|
|
7
|
+
*
|
|
8
|
+
* `behaviour` drives the outcome of a spend:
|
|
9
|
+
* - settle: invoices are paid by themselves after `settleMs`; payments and broadcasts succeed.
|
|
10
|
+
* - refuse: a spend fails, provably before anything left (`NothingSpentError`).
|
|
11
|
+
* - hang: a spend throws an unknown error, and the lookup later says it went through (a lost answer).
|
|
12
|
+
*/
|
|
13
|
+
export type FakeBehaviour = "settle" | "refuse" | "hang";
|
|
14
|
+
export declare const TEST_PROVIDERS_FLAG = "ghostly-test-providers";
|
|
15
|
+
/** A BOLT 11 invoice on regtest with a real checksum and a blank signature: it decodes, nobody can pay it. */
|
|
16
|
+
export declare function fakeInvoice(amount: number, paymentHash: Uint8Array, memo?: string, expirySeconds?: number): string;
|
|
17
|
+
/** A valid regtest P2WPKH address of nobody's. */
|
|
18
|
+
export declare const fakeAddress: () => `bcrt1${string}`;
|
|
19
|
+
interface FakeOptions {
|
|
20
|
+
alias?: string;
|
|
21
|
+
behaviour?: FakeBehaviour;
|
|
22
|
+
balance?: number;
|
|
23
|
+
settleMs?: number;
|
|
24
|
+
token?: string;
|
|
25
|
+
}
|
|
26
|
+
export declare class FakeLightningProvider implements LightningProvider {
|
|
27
|
+
readonly options: FakeOptions;
|
|
28
|
+
readonly capabilities: {
|
|
29
|
+
receive: boolean;
|
|
30
|
+
send: boolean;
|
|
31
|
+
balance: boolean;
|
|
32
|
+
lookup: boolean;
|
|
33
|
+
};
|
|
34
|
+
readonly invoices: Map<string, {
|
|
35
|
+
invoice: LightningInvoice;
|
|
36
|
+
paid: boolean;
|
|
37
|
+
}>;
|
|
38
|
+
readonly payments: Map<string, LightningPaymentStatus>;
|
|
39
|
+
readonly paid: string[];
|
|
40
|
+
balance: number;
|
|
41
|
+
behaviour: FakeBehaviour;
|
|
42
|
+
closed: boolean;
|
|
43
|
+
private timers;
|
|
44
|
+
constructor(options?: FakeOptions);
|
|
45
|
+
info(): Promise<{
|
|
46
|
+
network: "regtest";
|
|
47
|
+
alias: string;
|
|
48
|
+
balance: number;
|
|
49
|
+
}>;
|
|
50
|
+
createInvoice(amount: number, memo?: string): Promise<LightningInvoice>;
|
|
51
|
+
/** Someone paid this invoice. */
|
|
52
|
+
markPaid(paymentHash: string): void;
|
|
53
|
+
invoiceStatus(invoice: LightningInvoice): Promise<InvoiceStatus>;
|
|
54
|
+
estimateFee(_invoice: string, amount: number): Promise<number>;
|
|
55
|
+
payInvoice(invoice: string, maxFee: number): Promise<LightningPayResult>;
|
|
56
|
+
paymentStatus(payment: LightningPaymentRef): Promise<LightningPaymentStatus>;
|
|
57
|
+
close(): Promise<void>;
|
|
58
|
+
}
|
|
59
|
+
export declare class FakeOnchainProvider implements OnchainProvider {
|
|
60
|
+
readonly options: FakeOptions;
|
|
61
|
+
readonly addresses: string[];
|
|
62
|
+
readonly broadcasts: string[];
|
|
63
|
+
readonly released: string[];
|
|
64
|
+
readonly txs: Map<string, {
|
|
65
|
+
prepared: OnchainPrepared;
|
|
66
|
+
confirmations: number;
|
|
67
|
+
}>;
|
|
68
|
+
confirmed: number;
|
|
69
|
+
behaviour: FakeBehaviour;
|
|
70
|
+
closed: boolean;
|
|
71
|
+
constructor(options?: FakeOptions);
|
|
72
|
+
info(): Promise<{
|
|
73
|
+
network: "regtest";
|
|
74
|
+
alias: string;
|
|
75
|
+
}>;
|
|
76
|
+
receiveAddress(): Promise<`bcrt1${string}`>;
|
|
77
|
+
balance(): Promise<OnchainBalance>;
|
|
78
|
+
prepareSend(request: OnchainSendRequest): Promise<OnchainPrepared>;
|
|
79
|
+
broadcast(prepared: OnchainPrepared): Promise<string>;
|
|
80
|
+
status(prepared: OnchainPrepared): Promise<OnchainTxStatus>;
|
|
81
|
+
release(prepared: OnchainPrepared): Promise<void>;
|
|
82
|
+
history(limit: number): Promise<OnchainTx[]>;
|
|
83
|
+
close(): Promise<void>;
|
|
84
|
+
}
|
|
85
|
+
export declare const fakeLightning: LightningProviderDescriptor;
|
|
86
|
+
export declare const fakeOnchain: OnchainProviderDescriptor;
|
|
87
|
+
/** Whether this browser asked for the fake providers (an e2e run sets it before the app starts). */
|
|
88
|
+
export declare function testProvidersEnabled(): boolean;
|
|
89
|
+
export {};
|
|
@@ -0,0 +1,151 @@
|
|
|
1
|
+
import type { BitcoinNetwork } from "../../../../../core/src/index.js";
|
|
2
|
+
import type { WalletMode } from "../../../shared/mints.js";
|
|
3
|
+
/**
|
|
4
|
+
* What every wallet provider (a source of Lightning or of on-chain Bitcoin) shares: where it runs, how
|
|
5
|
+
* it is configured, and the one distinction that keeps money safe. See PROVIDERS.md.
|
|
6
|
+
*/
|
|
7
|
+
/** Where Ghostly runs: the web app, the browser extension (engine in an offscreen document), the Tauri app. */
|
|
8
|
+
export type ProviderPlatform = "web" | "extension" | "desktop";
|
|
9
|
+
export declare const PROVIDER_PLATFORMS: readonly ProviderPlatform[];
|
|
10
|
+
export type ProviderKind = "lightning" | "onchain";
|
|
11
|
+
/** The chain a provider's sats live on. Only `bitcoin` is real money; the others belong to the Testnet mode. */
|
|
12
|
+
export type ProviderNetwork = BitcoinNetwork;
|
|
13
|
+
export declare const PROVIDER_NETWORKS: readonly ProviderNetwork[];
|
|
14
|
+
export declare const networkMode: (network: ProviderNetwork) => WalletMode;
|
|
15
|
+
/**
|
|
16
|
+
* One field of a provider's configuration form. The wallet card renders these; a provider that needs
|
|
17
|
+
* more registers its own form component instead (apps/ui/src/components/wallet/providers/forms.ts).
|
|
18
|
+
* `secret` fields (an NWC URI, a macaroon, a rune, an API key, a password) are sealed before they are
|
|
19
|
+
* stored, never shown again, never put in the engine state, and never logged.
|
|
20
|
+
*/
|
|
21
|
+
export interface ProviderField {
|
|
22
|
+
name: string;
|
|
23
|
+
label: string;
|
|
24
|
+
kind: "text" | "url" | "secret" | "select" | "textarea";
|
|
25
|
+
placeholder?: string;
|
|
26
|
+
help?: string;
|
|
27
|
+
optional?: boolean;
|
|
28
|
+
/** `select` only. */
|
|
29
|
+
options?: {
|
|
30
|
+
value: string;
|
|
31
|
+
label: string;
|
|
32
|
+
}[];
|
|
33
|
+
/** Pre-filled per mode, e.g. a public test server for Testnet. */
|
|
34
|
+
defaults?: Partial<Record<WalletMode, string>>;
|
|
35
|
+
/**
|
|
36
|
+
* Values offered under a `url` or `text` field (a list to pick from, anything may still be typed), each
|
|
37
|
+
* only while the other fields hold `when`: e.g. a public Esplora server per network.
|
|
38
|
+
*/
|
|
39
|
+
suggestions?: {
|
|
40
|
+
value: string;
|
|
41
|
+
label: string;
|
|
42
|
+
when?: Record<string, string>;
|
|
43
|
+
}[];
|
|
44
|
+
/**
|
|
45
|
+
* A server address that can be changed on a saved source without its secrets being typed again, and
|
|
46
|
+
* without changing whose money it is: an Esplora server of a BDK wallet (the wallet is the phrase). The
|
|
47
|
+
* source's "Change server" edits these fields only. Never mark a field that picks another account (a
|
|
48
|
+
* node's URL: another node is other money).
|
|
49
|
+
*/
|
|
50
|
+
changeable?: boolean;
|
|
51
|
+
}
|
|
52
|
+
/** What the person typed, split by the field kinds: `config` is shown back, `secrets` never is. */
|
|
53
|
+
export interface ProviderSettings {
|
|
54
|
+
config: Record<string, string>;
|
|
55
|
+
secrets: Record<string, string>;
|
|
56
|
+
}
|
|
57
|
+
/** What the engine hands a provider's factory. */
|
|
58
|
+
export interface ProviderHost {
|
|
59
|
+
platform: ProviderPlatform;
|
|
60
|
+
/** The wallet mode the source is for: its provider must be on a network of this mode. */
|
|
61
|
+
mode: WalletMode;
|
|
62
|
+
/**
|
|
63
|
+
* Reserved for the built-in Cashu mint source: the engine's own wallet. It is not part of the SDK, and
|
|
64
|
+
* no other provider should read it.
|
|
65
|
+
*/
|
|
66
|
+
cashu?: unknown;
|
|
67
|
+
/** Reserved for the built-in Fedimint source: the engine's Fedimint wallet (its joined federations). Not part of the SDK. */
|
|
68
|
+
fedimint?: unknown;
|
|
69
|
+
/** Ends when the source is replaced, the mode switches or the engine stops: abort long waits on it. */
|
|
70
|
+
signal: AbortSignal;
|
|
71
|
+
/**
|
|
72
|
+
* Desktop only: calls a command of the Tauri app (apps/desktop), for what a WebView cannot do (a pinned
|
|
73
|
+
* certificate, no CORS, a raw socket). Absent on the web and in the extension.
|
|
74
|
+
*/
|
|
75
|
+
invoke?: <T>(command: string, args: Record<string, unknown>) => Promise<T>;
|
|
76
|
+
}
|
|
77
|
+
/**
|
|
78
|
+
* A provider module's export. Registering a provider is adding its module and one line in
|
|
79
|
+
* `registry.ts`; everything else (storage, sealing, per-mode sources, the card, journals) is shared.
|
|
80
|
+
*/
|
|
81
|
+
export interface ProviderDescriptor<P> {
|
|
82
|
+
id: string;
|
|
83
|
+
label: string;
|
|
84
|
+
kind: ProviderKind;
|
|
85
|
+
/** One line under the name in the source picker: what it is and who holds the money. */
|
|
86
|
+
description: string;
|
|
87
|
+
/** Networks it can run on. A mode lists only providers with a network of that mode. */
|
|
88
|
+
networks: readonly ProviderNetwork[];
|
|
89
|
+
platforms: readonly ProviderPlatform[];
|
|
90
|
+
fields: readonly ProviderField[];
|
|
91
|
+
/** Custodial (someone else holds the sats) or still experimental: said in the picker. */
|
|
92
|
+
custodial?: boolean;
|
|
93
|
+
experimental?: boolean;
|
|
94
|
+
/** Checks the form before anything is contacted; throws a message fit for the person. */
|
|
95
|
+
validate?(settings: ProviderSettings, mode: WalletMode): void;
|
|
96
|
+
/** Connects. The engine then asks `info()` and refuses a network of the other mode. */
|
|
97
|
+
create(settings: ProviderSettings, host: ProviderHost): Promise<P>;
|
|
98
|
+
}
|
|
99
|
+
/** A provider can be offered here: it runs on this platform and on a network of this mode. */
|
|
100
|
+
export declare const offeredIn: (descriptor: {
|
|
101
|
+
platforms: readonly ProviderPlatform[];
|
|
102
|
+
networks: readonly ProviderNetwork[];
|
|
103
|
+
}, platform: ProviderPlatform, mode: WalletMode) => boolean;
|
|
104
|
+
/** What is stored with the profile and sent on the wire in journals: stable, short, lowercase. */
|
|
105
|
+
export declare const PROVIDER_ID: RegExp;
|
|
106
|
+
/**
|
|
107
|
+
* Problems with a provider descriptor, empty when it is well-formed. The registry refuses a descriptor
|
|
108
|
+
* with any; the contract suite checks the same list, so an author sees them before the app does.
|
|
109
|
+
*/
|
|
110
|
+
export declare function providerDescriptorProblems(d: ProviderDescriptor<unknown>): string[];
|
|
111
|
+
/** The serializable part of a descriptor, for the UI (a function cannot cross the extension's port). */
|
|
112
|
+
export type ProviderDescriptorView = Omit<ProviderDescriptor<unknown>, "create" | "validate">;
|
|
113
|
+
/** Only these fields reach the UI, whatever else a provider module keeps on its descriptor. */
|
|
114
|
+
export declare const describeProvider: ({ id, label, kind, description, networks, platforms, fields, custodial, experimental }: ProviderDescriptor<unknown>) => ProviderDescriptorView;
|
|
115
|
+
/**
|
|
116
|
+
* The provider proved that nothing left the wallet (refused before sending, no route found before any
|
|
117
|
+
* HTLC, a transaction that was never broadcast). Safe to try again, with this or another source.
|
|
118
|
+
*
|
|
119
|
+
* Any other error from a spend means the outcome is UNKNOWN: the payment may be in flight or done. It is
|
|
120
|
+
* recorded as such and only reconciled (asked about), never retried. When in doubt, do not throw this.
|
|
121
|
+
*/
|
|
122
|
+
export declare class NothingSpentError extends Error {
|
|
123
|
+
constructor(message: string);
|
|
124
|
+
}
|
|
125
|
+
/**
|
|
126
|
+
* The source could not be reached: no answer, a time-out, a refused connection, a server error. The
|
|
127
|
+
* engine keeps trying by itself (with backoff) and shows the source as connecting meanwhile.
|
|
128
|
+
*/
|
|
129
|
+
export declare class SourceUnreachableError extends Error {
|
|
130
|
+
constructor(message: string, cause?: unknown);
|
|
131
|
+
}
|
|
132
|
+
/**
|
|
133
|
+
* A setting of the source is wrong (a server on another network, a phrase that makes no wallet): trying
|
|
134
|
+
* again changes nothing until the setting does. The engine shows it as unavailable at once.
|
|
135
|
+
*/
|
|
136
|
+
export declare class SourceConfigError extends Error {
|
|
137
|
+
constructor(message: string, cause?: unknown);
|
|
138
|
+
}
|
|
139
|
+
/** What went wrong connecting a source, by name (a plugin bundles its own copies of these classes). */
|
|
140
|
+
export type SourceProblem = "unreachable" | "config" | "other";
|
|
141
|
+
export declare const sourceProblem: (error: unknown) => SourceProblem;
|
|
142
|
+
/**
|
|
143
|
+
* Whether an error says nothing was spent. By name, not by class: a provider built outside the app (an
|
|
144
|
+
* SDK plugin bundled with its own copy of `NothingSpentError`) must be understood the same way.
|
|
145
|
+
*/
|
|
146
|
+
export declare const isNothingSpentError: (error: unknown) => error is NothingSpentError;
|
|
147
|
+
/**
|
|
148
|
+
* An error message fit to show and store: every secret the source was given is blanked out, in case a
|
|
149
|
+
* library echoed a URI or a key back.
|
|
150
|
+
*/
|
|
151
|
+
export declare function redact(error: unknown, secrets?: Record<string, string>): string;
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
import type { GhostlyAdapterPlugin } from "./registry.js";
|
|
2
|
+
/**
|
|
3
|
+
* The adapter plugins compiled into this build. Empty unless the build lists some: `GHOSTLY_PLUGINS`
|
|
4
|
+
* names their modules (comma-separated paths from the repository root, each default-exporting a
|
|
5
|
+
* `GhostlyAdapterPlugin`), and the Vite plugin in `packages/browser/vite-plugin.ts` swaps this module
|
|
6
|
+
* for one that imports them. Release builds never set it; the e2e build carries the SDK example.
|
|
7
|
+
*/
|
|
8
|
+
export declare const BUNDLED_PLUGINS: readonly GhostlyAdapterPlugin[];
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
import type { LightningProviderDescriptor } from "../engine/paymentAdapters/providers/lightning.js";
|
|
2
|
+
import type { OnchainProviderDescriptor } from "../engine/paymentAdapters/providers/onchain.js";
|
|
3
|
+
import { type ProviderKind } from "../engine/paymentAdapters/providers/types.js";
|
|
4
|
+
import type { IdentityProofProvider } from "../proofs/contract.js";
|
|
5
|
+
/**
|
|
6
|
+
* Adapters written outside the app: wallet sources (Lightning, on-chain) and identity-proof providers
|
|
7
|
+
* that register here instead of being added to the built-in lists. A plugin is a plain object naming
|
|
8
|
+
* its adapters; the registries (`providers/registry.ts`, `proofs/registry.ts`) list what is registered
|
|
9
|
+
* after the built-ins and before the test fakes, and the same platform and mode rules apply to all.
|
|
10
|
+
*
|
|
11
|
+
* Two ways in:
|
|
12
|
+
* - at build time: `GHOSTLY_PLUGINS` lists the modules and `bundled.ts` is swapped for them;
|
|
13
|
+
* - at run time: code already running in the engine's realm calls `registerAdapters` before the
|
|
14
|
+
* pickers are shown (or after: the engine re-reads the lists when something registers).
|
|
15
|
+
*
|
|
16
|
+
* Trust: a plugin runs with the app's privileges, in the app's own JavaScript realm. There is no
|
|
17
|
+
* sandbox, no permission prompt and no store; whoever builds a plugin in, or loads one, trusts its
|
|
18
|
+
* author with everything the app can do, keys and sats included. A manifest with permissions and an
|
|
19
|
+
* isolated runtime are a later phase (docs/wisps/ADAPTER-ROADMAP.md, "Plugins, apps, catalogs").
|
|
20
|
+
*
|
|
21
|
+
* The state lives on `globalThis` under a well-known symbol, so a plugin bundled with its own copy of
|
|
22
|
+
* the SDK (a second copy of this module) still registers into the same lists the app reads.
|
|
23
|
+
*/
|
|
24
|
+
/** The generation of the adapter contracts. A plugin says which one it was written against. */
|
|
25
|
+
export declare const SDK_API = 1;
|
|
26
|
+
export declare const PLUGIN_ID: RegExp;
|
|
27
|
+
export interface GhostlyAdapterPlugin {
|
|
28
|
+
/** Stable, unique among plugins: `^[a-z][a-z0-9-]{0,63}$`. */
|
|
29
|
+
id: string;
|
|
30
|
+
/** The plugin's own version, for people. */
|
|
31
|
+
version?: string;
|
|
32
|
+
/** The contract generation it was written against: `SDK_API`. Another one is refused. */
|
|
33
|
+
sdk: number;
|
|
34
|
+
lightning?: readonly LightningProviderDescriptor[];
|
|
35
|
+
onchain?: readonly OnchainProviderDescriptor[];
|
|
36
|
+
identities?: readonly IdentityProofProvider[];
|
|
37
|
+
}
|
|
38
|
+
export type AdapterKind = ProviderKind | "identity";
|
|
39
|
+
/** Problems with a plugin, empty when it can be registered. Does not look at what is already registered. */
|
|
40
|
+
export declare function pluginProblems(plugin: GhostlyAdapterPlugin): string[];
|
|
41
|
+
/** The built-in registries say which ids are theirs. A plugin using one is refused. */
|
|
42
|
+
export declare function reserveAdapterIds(kind: AdapterKind, list: readonly string[]): void;
|
|
43
|
+
/**
|
|
44
|
+
* Registers a plugin's adapters. Throws, registering nothing, when the plugin is malformed, its id or
|
|
45
|
+
* one of its adapters' ids is taken (by a built-in or by another plugin), or its contract generation
|
|
46
|
+
* is another one. Returns the function that unregisters it.
|
|
47
|
+
*/
|
|
48
|
+
export declare function registerAdapters(plugin: GhostlyAdapterPlugin): () => void;
|
|
49
|
+
/** Called when a plugin registers or unregisters: the engine re-reads the lists. */
|
|
50
|
+
export declare function onAdaptersChanged(listener: () => void): () => void;
|
|
51
|
+
/** Every registered plugin, in registration order (bundled ones first). */
|
|
52
|
+
export declare function registeredPlugins(): readonly GhostlyAdapterPlugin[];
|
|
53
|
+
export declare function registeredLightningProviders(): readonly LightningProviderDescriptor[];
|
|
54
|
+
export declare function registeredOnchainProviders(): readonly OnchainProviderDescriptor[];
|
|
55
|
+
export declare function registeredIdentityProviders(): readonly IdentityProofProvider[];
|
|
56
|
+
/** Tests only: forget every registration, including the bundled ones. */
|
|
57
|
+
export declare function resetAdapterRegistry(): void;
|
|
@@ -0,0 +1,262 @@
|
|
|
1
|
+
import type { IdentityDisplay, IdentityStatement, VerifiedIdentity } from "../../../core/src/index.js";
|
|
2
|
+
/**
|
|
3
|
+
* The identity-proof provider contract. A provider is one way to prove control of an external
|
|
4
|
+
* identity (a Nostr key, a domain, a Bitcoin address, an SSH or PGP key, an OpenID Connect account):
|
|
5
|
+
* how the person produces evidence over the shared statement (`signers`), and how any Ghostly app
|
|
6
|
+
* checks it (`verify`). Everything else — the statement bytes, the proof key, sharing per contact,
|
|
7
|
+
* replay protection, storage, expiry, the UI — is shared. See PROOFS.md.
|
|
8
|
+
*/
|
|
9
|
+
/**
|
|
10
|
+
* Who vouches for the identity. The UI shows the difference:
|
|
11
|
+
* - self-custodied: the person holds the key (Nostr, SSH, PGP, Bitcoin, a domain they control);
|
|
12
|
+
* only they can have produced the evidence.
|
|
13
|
+
* - provider-attested: a company signs that the person logged in to an account (OpenID Connect);
|
|
14
|
+
* the evidence is only as trustworthy as that company.
|
|
15
|
+
*/
|
|
16
|
+
export type IdentityCategory = "self-custodied" | "provider-attested";
|
|
17
|
+
/** Where Ghostly runs: the web app, the browser extension (engine in an offscreen document), the Tauri app. */
|
|
18
|
+
export type IdentityPlatform = "web" | "extension" | "desktop";
|
|
19
|
+
export declare const IDENTITY_PLATFORMS: readonly IdentityPlatform[];
|
|
20
|
+
/**
|
|
21
|
+
* A bounded HTTPS GET through the engine: time-out, size cap (`maxBytes`, default 64 KiB), no credentials,
|
|
22
|
+
* no referrer, refused offline. `redirect` defaults to "error": a record that redirects does not count
|
|
23
|
+
* unless the provider says so. `text` is the body as UTF-8; `bytes` is the same body raw (binary
|
|
24
|
+
* answers such as DNS-over-HTTPS `application/dns-message`).
|
|
25
|
+
*/
|
|
26
|
+
export interface IdentityFetchOptions {
|
|
27
|
+
headers?: Record<string, string>;
|
|
28
|
+
maxBytes?: number;
|
|
29
|
+
signal?: AbortSignal;
|
|
30
|
+
redirect?: "follow" | "error";
|
|
31
|
+
}
|
|
32
|
+
export interface IdentityFetchResponse {
|
|
33
|
+
status: number;
|
|
34
|
+
contentType: string;
|
|
35
|
+
text: string;
|
|
36
|
+
bytes: Uint8Array;
|
|
37
|
+
}
|
|
38
|
+
export type IdentityFetch = (url: string, options?: IdentityFetchOptions) => Promise<IdentityFetchResponse>;
|
|
39
|
+
export interface VerifyContext {
|
|
40
|
+
/** Seconds. Use this, never `Date.now()`, so tests and re-checks agree on time. */
|
|
41
|
+
now: number;
|
|
42
|
+
signal: AbortSignal;
|
|
43
|
+
/** The only way `verify` may reach the network. Never call the global `fetch`. */
|
|
44
|
+
fetch: IdentityFetch;
|
|
45
|
+
}
|
|
46
|
+
export interface SubjectSpec {
|
|
47
|
+
/** "Public key", "Domain", "Bitcoin address", "Account". */
|
|
48
|
+
label: string;
|
|
49
|
+
placeholder?: string;
|
|
50
|
+
help?: string;
|
|
51
|
+
/** Choices instead of a text field (an OpenID Connect provider's issuer). */
|
|
52
|
+
options?: readonly {
|
|
53
|
+
value: string;
|
|
54
|
+
label: string;
|
|
55
|
+
}[];
|
|
56
|
+
/** The canonical subject for what the person typed (or a signer returned). Throw a message they can act on. */
|
|
57
|
+
normalize(input: string): string;
|
|
58
|
+
/** Short form for badges and lists ("npub1x…4f2"). Defaults to the subject. */
|
|
59
|
+
short?(subject: string): string;
|
|
60
|
+
/**
|
|
61
|
+
* What the (normalized) subject turns out to be, shown under the field before anything is signed: a DID's
|
|
62
|
+
* method, its keys and its domain. Runs in the UI on the person's input; may reach the network (the
|
|
63
|
+
* person's own identity). Throw a message they can act on.
|
|
64
|
+
*/
|
|
65
|
+
preview?(subject: string, options: {
|
|
66
|
+
signal: AbortSignal;
|
|
67
|
+
}): Promise<SubjectPreview>;
|
|
68
|
+
}
|
|
69
|
+
export interface SubjectPreview {
|
|
70
|
+
/** Short facts, in order: "Method" → "did:web", "Keys" → "#key-1 (Ed25519)". */
|
|
71
|
+
facts: readonly {
|
|
72
|
+
label: string;
|
|
73
|
+
value: string;
|
|
74
|
+
}[];
|
|
75
|
+
/** The ids of the signers that apply to this subject; every signer when omitted. */
|
|
76
|
+
signers?: readonly string[];
|
|
77
|
+
}
|
|
78
|
+
/** A field an in-app signer needs (a NIP-46 connection link). `secret` values are never stored or logged. */
|
|
79
|
+
export interface SignerField {
|
|
80
|
+
name: string;
|
|
81
|
+
label: string;
|
|
82
|
+
kind: "text" | "secret";
|
|
83
|
+
placeholder?: string;
|
|
84
|
+
help?: string;
|
|
85
|
+
optional?: boolean;
|
|
86
|
+
}
|
|
87
|
+
/**
|
|
88
|
+
* A request waiting for the person's approval elsewhere, in one of two ways (Pubky: Passport in a browser window, or
|
|
89
|
+
* Ring by scanning a QR code). The UI shows both on one screen; whichever approves first wins. Its values are secrets
|
|
90
|
+
* (the QR carries a relay key): never logged, never stored.
|
|
91
|
+
*/
|
|
92
|
+
export interface ApprovalRequest {
|
|
93
|
+
/** The primary button. `run` is called synchronously from its click, so a popup it opens keeps the user activation. */
|
|
94
|
+
open?: {
|
|
95
|
+
label: string;
|
|
96
|
+
description?: string;
|
|
97
|
+
run(): void;
|
|
98
|
+
};
|
|
99
|
+
/** A QR code for a phone app, with its caption. */
|
|
100
|
+
qr?: {
|
|
101
|
+
value: string;
|
|
102
|
+
label: string;
|
|
103
|
+
};
|
|
104
|
+
/** Short lines under the choices. */
|
|
105
|
+
notes?: readonly string[];
|
|
106
|
+
}
|
|
107
|
+
export interface SignerContext {
|
|
108
|
+
values: Record<string, string>;
|
|
109
|
+
signal: AbortSignal;
|
|
110
|
+
/** The signer asks the person to approve on a page (NIP-46 auth_url): the UI shows it as a link, never opens it itself. */
|
|
111
|
+
onAuthUrl(url: string): void;
|
|
112
|
+
onProgress(message: string): void;
|
|
113
|
+
/** The signer waits for an approval elsewhere (`null`: it no longer does). The UI renders it; see `ApprovalRequest`. */
|
|
114
|
+
onApproval?(request: ApprovalRequest | null): void;
|
|
115
|
+
}
|
|
116
|
+
export interface SignerSession<E> {
|
|
117
|
+
/** The identity the signer controls, canonical (as `subject.normalize` returns it). */
|
|
118
|
+
subject(): Promise<string>;
|
|
119
|
+
sign(statement: IdentityStatement): Promise<E>;
|
|
120
|
+
}
|
|
121
|
+
export interface InstructionStep {
|
|
122
|
+
text: string;
|
|
123
|
+
/** Shown in a copyable block (a command, a DNS record). */
|
|
124
|
+
copy?: string;
|
|
125
|
+
}
|
|
126
|
+
export interface SignerInstructions {
|
|
127
|
+
steps: readonly InstructionStep[];
|
|
128
|
+
/** external-tool: the field the output is pasted into. */
|
|
129
|
+
paste?: {
|
|
130
|
+
label: string;
|
|
131
|
+
placeholder?: string;
|
|
132
|
+
multiline?: boolean;
|
|
133
|
+
};
|
|
134
|
+
}
|
|
135
|
+
interface SignerBase {
|
|
136
|
+
/** Unique within the provider: "nip07", "nip46", "ssh-keygen". */
|
|
137
|
+
id: string;
|
|
138
|
+
label: string;
|
|
139
|
+
description?: string;
|
|
140
|
+
/** Defaults to the provider's. */
|
|
141
|
+
platforms?: readonly IdentityPlatform[];
|
|
142
|
+
/** False hides it (no NIP-07 extension in this window). Runs in the UI. */
|
|
143
|
+
available?(): boolean;
|
|
144
|
+
/** The button that starts it ("Continue on your server"). Default: "Sign with <label>" in-app, "Continue" otherwise. */
|
|
145
|
+
action?: string;
|
|
146
|
+
}
|
|
147
|
+
/** Signs inside Ghostly through something the person already uses (NIP-07, NIP-46, a wallet API). */
|
|
148
|
+
export interface InAppSigner<E> extends SignerBase {
|
|
149
|
+
kind: "in-app";
|
|
150
|
+
fields?: readonly SignerField[];
|
|
151
|
+
/** Opens the signer, runs `work`, and always cleans up (closes connections, drops keys) before resolving. */
|
|
152
|
+
run<T>(ctx: SignerContext, work: (session: SignerSession<E>) => Promise<T>): Promise<T>;
|
|
153
|
+
}
|
|
154
|
+
/** The person runs a tool (ssh-keygen, gpg, a Bitcoin wallet) on the statement and pastes the output back. */
|
|
155
|
+
export interface ExternalToolSigner<E> extends SignerBase {
|
|
156
|
+
kind: "external-tool";
|
|
157
|
+
instructions(statement: IdentityStatement): SignerInstructions;
|
|
158
|
+
/** What was pasted, as evidence. Throw a message the person can act on ("That is not an SSH signature"). */
|
|
159
|
+
parse(pasted: string, statement: IdentityStatement): E | Promise<E>;
|
|
160
|
+
}
|
|
161
|
+
/** A popup to the provider's login page (OpenID Connect); the subject comes out of `verify`. */
|
|
162
|
+
export interface RedirectSigner<E> extends SignerBase {
|
|
163
|
+
kind: "redirect";
|
|
164
|
+
start(statement: IdentityStatement, ctx: SignerContext): Promise<E>;
|
|
165
|
+
}
|
|
166
|
+
/** The person publishes something the verifier fetches (a DNS TXT record, a /.well-known file). */
|
|
167
|
+
export interface PublishSigner<E> extends SignerBase {
|
|
168
|
+
kind: "publish";
|
|
169
|
+
instructions(statement: IdentityStatement): SignerInstructions;
|
|
170
|
+
/** Usually small or empty: the verifier looks the record up itself. */
|
|
171
|
+
evidence(statement: IdentityStatement): E | Promise<E>;
|
|
172
|
+
}
|
|
173
|
+
export type IdentitySigner<E> = InAppSigner<E> | ExternalToolSigner<E> | RedirectSigner<E> | PublishSigner<E>;
|
|
174
|
+
/**
|
|
175
|
+
* A provider module's export. Registering it is adding the module under `proofs/providers/` and ONE
|
|
176
|
+
* line in `proofs/registry.ts`.
|
|
177
|
+
*/
|
|
178
|
+
export interface IdentityProofProvider<E = unknown> {
|
|
179
|
+
/** Stable: it is in the statement, on the wire and in storage. `^[a-z][a-z0-9-]{0,31}$`. */
|
|
180
|
+
id: string;
|
|
181
|
+
label: string;
|
|
182
|
+
category: IdentityCategory;
|
|
183
|
+
/**
|
|
184
|
+
* One short line for the picker card, how you make it: "Sign once with your Nostr signer". About 40
|
|
185
|
+
* characters at most; the card shows nothing else beside the name and the category.
|
|
186
|
+
*/
|
|
187
|
+
summary: string;
|
|
188
|
+
/** The details view (opened from the card, shown again above the form): what is proven and how, a sentence or two. */
|
|
189
|
+
description: string;
|
|
190
|
+
/**
|
|
191
|
+
* What the proof does NOT show, when a contact could easily assume more ("Does not prove a balance, a past
|
|
192
|
+
* payment, or that you would pay."). Shown with the description, never hidden behind a hover.
|
|
193
|
+
*/
|
|
194
|
+
limits?: string;
|
|
195
|
+
platforms: readonly IdentityPlatform[];
|
|
196
|
+
subject: SubjectSpec;
|
|
197
|
+
/** How long one proof may last. The person picks up to `maxDays` (never above 400). */
|
|
198
|
+
validity: {
|
|
199
|
+
defaultDays: number;
|
|
200
|
+
maxDays: number;
|
|
201
|
+
};
|
|
202
|
+
/**
|
|
203
|
+
* When a verifier's check can go stale (the DNS record may be removed later): the contact's app offers
|
|
204
|
+
* "Check again" after this many seconds and shows the last check time. Omit when the evidence is a
|
|
205
|
+
* signature that stays valid until expiry.
|
|
206
|
+
*/
|
|
207
|
+
recheck?: {
|
|
208
|
+
afterSeconds: number;
|
|
209
|
+
};
|
|
210
|
+
/** One sentence for people: what `verify` contacts and who learns what. "Nothing: checked on this device." */
|
|
211
|
+
privacy: string;
|
|
212
|
+
/** Mark providers whose flows are not proven against real-world tools yet. */
|
|
213
|
+
experimental?: boolean;
|
|
214
|
+
/** Listed under "Advanced" in the picker, for people who know what it is (DIDs), so it does not crowd newcomers. */
|
|
215
|
+
advanced?: boolean;
|
|
216
|
+
signers: readonly IdentitySigner<E>[];
|
|
217
|
+
/**
|
|
218
|
+
* Untrusted evidence off the wire → typed evidence. Strict: exact shape, bounded sizes, no extra keys.
|
|
219
|
+
* The serialized evidence is already capped at 16 KiB before this runs.
|
|
220
|
+
*/
|
|
221
|
+
parseEvidence(raw: unknown): E;
|
|
222
|
+
/**
|
|
223
|
+
* Checks `evidence` against exactly `statement.bytes` / `statement.text` and returns what it proves.
|
|
224
|
+
* Throws when it does not. Must:
|
|
225
|
+
* - self-custodied: return `subject === statement.binding.subject`;
|
|
226
|
+
* - provider-attested: return the attested subject and set `attester`;
|
|
227
|
+
* - reach the network only through `ctx.fetch`, and use `ctx.now` for time.
|
|
228
|
+
*/
|
|
229
|
+
verify(statement: IdentityStatement, evidence: E, ctx: VerifyContext): Promise<VerifiedIdentity>;
|
|
230
|
+
/**
|
|
231
|
+
* Optional public name/picture for a verified subject (Nostr kind-0). Called ONLY when the person asks,
|
|
232
|
+
* never automatically. Sanitize like avatars: plain-text name, bounded raster re-encoded to a data URL.
|
|
233
|
+
*/
|
|
234
|
+
lookupDisplay?(subject: string, options: {
|
|
235
|
+
signal: AbortSignal;
|
|
236
|
+
}): Promise<IdentityDisplay | undefined>;
|
|
237
|
+
/** The button that runs `lookupDisplay`. Default: "Show public profile". */
|
|
238
|
+
lookupLabel?: string;
|
|
239
|
+
/**
|
|
240
|
+
* The verified subject as a URI a public DID document may list in `alsoKnownAs` (the profile's
|
|
241
|
+
* did:dht, and only for identities the person chooses to list there). Omit when the identity has no
|
|
242
|
+
* URI of its own. No comma: did:dht separates the list with commas.
|
|
243
|
+
*/
|
|
244
|
+
publicUri?(subject: string): string | undefined;
|
|
245
|
+
/**
|
|
246
|
+
* Takes down what a signer published when the person removes the proof (an AT Protocol record, a Pubky proof file). Runs in
|
|
247
|
+
* the UI, called synchronously from the confirming click (it may open a window first). The shared Pkarr
|
|
248
|
+
* revocation is published either way; if this fails, the person may remove the proof without it.
|
|
249
|
+
*/
|
|
250
|
+
unpublish?: {
|
|
251
|
+
/** What the removal adds, for the confirmation: "Also deletes the record on your server." */
|
|
252
|
+
description: string;
|
|
253
|
+
/** `evidence` is what `parseEvidence` accepted when the proof was made (Pubky: the proof file's folder). */
|
|
254
|
+
run(proof: {
|
|
255
|
+
id: string;
|
|
256
|
+
subject: string;
|
|
257
|
+
key: string;
|
|
258
|
+
evidence: E;
|
|
259
|
+
}, ctx: SignerContext): Promise<void>;
|
|
260
|
+
};
|
|
261
|
+
}
|
|
262
|
+
export {};
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
import { type IdentityStatement } from "../../../core/src/index.js";
|
|
2
|
+
import type { IdentityFetch, IdentityProofProvider } from "./contract.js";
|
|
3
|
+
/**
|
|
4
|
+
* The identity-proof contract as tests: every provider runs these against itself, with a harness that
|
|
5
|
+
* can produce evidence for it (a test key, a stubbed network). See PROOFS.md. Provider-specific tests
|
|
6
|
+
* (real tool output, vectors, malformed inputs of its format) go next to these.
|
|
7
|
+
*
|
|
8
|
+
* describeIdentityProof("SSH", async () => ({ provider: ssh, subject, prove: s => sshSign(s, key), proveAsOther: s => sshSign(s, otherKey) }));
|
|
9
|
+
*/
|
|
10
|
+
export interface IdentityProofHarness<E> {
|
|
11
|
+
provider: IdentityProofProvider<E>;
|
|
12
|
+
/** A canonical subject this harness controls (self-custodied), or the issuer (provider-attested). */
|
|
13
|
+
subject: string;
|
|
14
|
+
/** Valid evidence for `statement`, the way the provider's signer would produce it. */
|
|
15
|
+
prove(statement: IdentityStatement): Promise<E>;
|
|
16
|
+
/** Evidence for the same statement by another key/account: a self-custodied provider must refuse it. */
|
|
17
|
+
proveAsOther?(statement: IdentityStatement): Promise<E>;
|
|
18
|
+
/** The network the verifier sees (DNS, JWKS, published keys). Defaults to one that refuses everything. */
|
|
19
|
+
fetch?: IdentityFetch;
|
|
20
|
+
/** Make proofs made so far fail a re-check (unpublish the record, revoke the key). Providers with `recheck`. */
|
|
21
|
+
revoke?(): void | Promise<void>;
|
|
22
|
+
/** Seconds; defaults to the real clock. */
|
|
23
|
+
now?: number;
|
|
24
|
+
}
|
|
25
|
+
export declare function describeIdentityProof<E>(name: string, make: () => Promise<IdentityProofHarness<E>>, { timeout }?: {
|
|
26
|
+
timeout?: number | undefined;
|
|
27
|
+
}): void;
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
import { type IdentityStatement } from "../../../core/src/index.js";
|
|
2
|
+
import type { IdentityProofProvider } from "./contract.js";
|
|
3
|
+
/**
|
|
4
|
+
* Fake identity providers, for unit tests and e2e. No network, no real accounts. They are in the
|
|
5
|
+
* registry only when `localStorage["ghostly-test-identities"] === "1"` (or a test passes them itself).
|
|
6
|
+
*
|
|
7
|
+
* - fake-key self-custodied: an Ed25519 key held by a fake in-app signer, or signed "outside" and pasted.
|
|
8
|
+
* - fake-account provider-attested: a fake issuer signs a token whose nonce is the statement id (like OIDC).
|
|
9
|
+
* - fake-record self-custodied, published: a record the verifier fetches through `ctx.fetch` (like DNS).
|
|
10
|
+
*/
|
|
11
|
+
export declare const TEST_IDENTITIES_FLAG = "ghostly-test-identities";
|
|
12
|
+
export declare const testIdentitiesEnabled: () => boolean;
|
|
13
|
+
/** The key behind the fake in-app signer. Tests may replace it. */
|
|
14
|
+
export declare const fakeKeyring: {
|
|
15
|
+
seed: Uint8Array<ArrayBufferLike> & Uint8Array<ArrayBuffer>;
|
|
16
|
+
};
|
|
17
|
+
export declare const fakeKeySubject: (seed?: Uint8Array<ArrayBufferLike> & Uint8Array<ArrayBuffer>) => string;
|
|
18
|
+
export declare const fakeKeySign: (statement: IdentityStatement, seed?: Uint8Array<ArrayBufferLike> & Uint8Array<ArrayBuffer>) => {
|
|
19
|
+
sig: string;
|
|
20
|
+
};
|
|
21
|
+
export interface FakeKeyEvidence {
|
|
22
|
+
sig: string;
|
|
23
|
+
}
|
|
24
|
+
export declare const fakeKey: IdentityProofProvider<FakeKeyEvidence>;
|
|
25
|
+
export declare const FAKE_ISSUER = "https://issuer.ghostly.test";
|
|
26
|
+
export interface FakeAccountEvidence {
|
|
27
|
+
token: string;
|
|
28
|
+
}
|
|
29
|
+
/** What the fake login page signs: iss, sub, nonce (= statement id), iat. */
|
|
30
|
+
export declare function fakeAccountToken(statement: IdentityStatement, account?: string, seed?: Uint8Array<ArrayBuffer>, iat?: number): FakeAccountEvidence;
|
|
31
|
+
export declare const fakeAccount: IdentityProofProvider<FakeAccountEvidence>;
|
|
32
|
+
/** fake-record's records: subject → published text. The verifier reads `https://records.ghostly.test/<subject>`. */
|
|
33
|
+
export declare const FAKE_RECORD_HOST = "https://records.ghostly.test/";
|
|
34
|
+
export declare const fakeRecordText: (statement: IdentityStatement) => string;
|
|
35
|
+
export declare const fakeRecord: IdentityProofProvider<Record<string, never>>;
|
|
36
|
+
export declare const FAKE_IDENTITY_PROVIDERS: readonly IdentityProofProvider[];
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
import { type IdentityStatement, type VerifiedIdentity } from "../../../core/src/index.js";
|
|
2
|
+
import type { IdentityFetch, IdentityProofProvider, IdentitySigner, VerifyContext } from "./contract.js";
|
|
3
|
+
/**
|
|
4
|
+
* The checks every proof goes through, whatever its provider: known provider, validity within the
|
|
5
|
+
* provider's limit, bounded evidence, strict parsing, the provider's own check, and the category rule
|
|
6
|
+
* (a self-custodied proof proves exactly the subject it names; an attested one says who attests it).
|
|
7
|
+
* The engine verifies a contact's proof, and the person's own proof before saving it, only through this.
|
|
8
|
+
*/
|
|
9
|
+
export declare function verifyIdentity(providers: readonly IdentityProofProvider[], statement: IdentityStatement, evidence: unknown, ctx: VerifyContext): Promise<VerifiedIdentity>;
|
|
10
|
+
/** Problems with a provider's descriptor, empty when it is well-formed. The registry and the contract suite use it. */
|
|
11
|
+
export declare function descriptorProblems(p: IdentityProofProvider): string[];
|
|
12
|
+
/** Signers of a provider that run on this platform and are available in this window. */
|
|
13
|
+
export declare function availableSigners<E>(p: IdentityProofProvider<E>, platform: IdentityProofProvider["platforms"][number]): IdentitySigner<E>[];
|
|
14
|
+
/**
|
|
15
|
+
* The engine's `ctx.fetch`: HTTPS GET only, no credentials or referrer, a time-out, a size cap,
|
|
16
|
+
* redirects refused unless asked for.
|
|
17
|
+
* `online` false refuses everything (the person turned the network off).
|
|
18
|
+
*/
|
|
19
|
+
export declare function boundedIdentityFetch(options?: {
|
|
20
|
+
online: () => boolean;
|
|
21
|
+
timeoutMs?: number;
|
|
22
|
+
fetcher?: typeof fetch;
|
|
23
|
+
}): IdentityFetch;
|