@kernlize/core 0.12.0 → 0.14.0
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 +1 -1
- package/dist/{chunk-E7SNLTN2.js → chunk-ALAK4MW6.js} +8 -1
- package/dist/chunk-ALAK4MW6.js.map +1 -0
- package/dist/index.d.ts +1368 -133
- package/dist/index.js +3563 -487
- package/dist/index.js.map +1 -1
- package/dist/wm/index.d.ts +7 -0
- package/dist/wm/index.js +1 -1
- package/package.json +4 -3
- package/dist/chunk-E7SNLTN2.js.map +0 -1
package/dist/index.d.ts
CHANGED
|
@@ -2,21 +2,21 @@ import { Observable, Subscription } from 'rxjs';
|
|
|
2
2
|
import { EventStore } from 'applesauce-core';
|
|
3
3
|
import { RelayPool, RelayPoolOptions } from 'applesauce-relay';
|
|
4
4
|
import { AccountManager, IAccount, BaseAccount, SerializedAccount } from 'applesauce-accounts';
|
|
5
|
-
import { RelayPoolHooks, RelayPoolLike, ShellBridge, ShellEnvironment, AuthHooks, ShellAdapter, OriginRegistry, NappletMessageDecision, CapabilityHooks, NappletRevocation, UnroutedMessageInfo } from '@kehto/shell';
|
|
6
|
-
import { Capability, RelayPlanningServiceHandler, ConsentRequest, Signer,
|
|
7
|
-
import {
|
|
5
|
+
import { RelayPoolHooks, RelayPoolLike, ShellBridge, ShellEnvironment, AuthHooks, NappletNamespacePreludeOptions, ShellAdapter, OriginRegistry, NappletMessageDecision, CapabilityHooks, NappletRevocation, UnroutedMessageInfo } from '@kehto/shell';
|
|
6
|
+
import { ServiceHandler, Capability, RelayPlanningServiceHandler, ConsentRequest, Signer, TemporalPolicy, PermissionRateEvent, ApprovalAnswer, ApprovalPrompt, PermissionAdapter, Runtime, RuntimePermissions, AclStateContainer, PermissionRequirement as PermissionRequirement$1, ServiceRegistry } from '@kehto/runtime';
|
|
7
|
+
import { PermissionRules, PermissionRuleAction, PermissionRequest, PermissionRequirement, PermissionPrincipal } from '@kehto/firewall';
|
|
8
|
+
import { CvmRegistryFamily, ConfigSettingsContext, ConfigServiceOptions, IntentCatalogEntry, RelayPoolServiceOptions, DmRelayPool, IdentityServiceOptions, DmAdapter, Uploader, CommonServiceOptions, WebrtcServiceOptions, ThemeService, DmService, OutboxRouter, ResourceFetchInit, ResourceServiceError, IntentResolver, IntentDispatchParams } from '@kehto/services';
|
|
8
9
|
import { NostrFilter, NostrEvent, EventTemplate, NappletMessage } from '@napplet/core';
|
|
9
10
|
import { NappletManifest, NappletArtifactCache, ResolvedNapplet } from '@kehto/nip/5d';
|
|
10
11
|
import { WindowVisibility, GuardConfig, GuardProfile, GuardEvent, MitigationDescription, GuardDisposition, OpClass } from '@kernlize/guard';
|
|
11
12
|
import { MessagingRegistry, MessagingBackend, ReplyPrompt, ReplyAnswer, MessagingRegistryOptions, ProviderAvailability } from '@kernlize/messaging';
|
|
12
|
-
import { BridgeRegistry, TorrentBackend, BridgeRegistryOptions, HttpBridgeOptions, HandoffOpener, ResourceResolveInit } from '@kernlize/bridges';
|
|
13
|
+
import { ClientEndpoint, EndpointNote, ClientProbe, TorrentClient, NzbClient, SoulseekClient, PageScheme, ClientFetch, BridgeRegistry, TorrentBackend, BridgeRegistryOptions, HttpBridgeOptions, HandoffOpener, BlossomBridgeOptions, ResourceResolveInit } from '@kernlize/bridges';
|
|
13
14
|
import { EventCacheOpener, ConnectedEventCache } from './cache/index.js';
|
|
14
15
|
export { AttachEventCacheOptions, AttachedEventCache, CacheRecoveryEvent, EventCache, EventCacheAdapter, EventRecords, FilenameStorage, IndexedDbCacheOptions, LockManagerLike, OpenEventCacheOptions, SqlStatement, SqlValue, SqliteDriver, SqliteFiles, SqliteOpfsOptions, attachEventCache, connectEventCache, createEventCache, createIndexedDbCacheAdapter, createMemoryCacheAdapter, createSqliteOpfsCacheAdapter, defaultWebCacheAdapters, fromEventDatabase, isCorruptionError, openEventCache } from './cache/index.js';
|
|
15
16
|
import { ISigner, PrivateKeySigner } from 'applesauce-signers';
|
|
16
17
|
import { NostrEvent as NostrEvent$1, Filter } from 'applesauce-core/helpers';
|
|
17
18
|
import { AddressPointerLoader } from 'applesauce-loaders/loaders';
|
|
18
19
|
import { CacheRequest } from 'applesauce-loaders';
|
|
19
|
-
import { FirewallStateContainer, RateLimit } from '@kehto/rate-limit/legacy';
|
|
20
20
|
export { LayoutStrategy, Rect, WindowPlacement, WindowState } from '@kehto/wm';
|
|
21
21
|
export { LayoutChoice, LayoutEntry, LayoutOptions, LayoutRegistry, ManagedWindow, MasterStackOptions, VisibilityTarget, WindowManager, WindowManagerOptions, WindowManagerState, WindowSize, createColumnsLayout, createDefaultLayouts, createDwindleLayout, createLayoutRegistry, createMasterStackLayout, createWindowManager, floatingLayout } from './wm/index.js';
|
|
22
22
|
export { CryptoFallbackReport, CryptoScope, createFallbackSubtle, installCryptoFallback, randomUuidFallback, renderRandomUuidFallbackScript } from './crypto/index.js';
|
|
@@ -77,6 +77,75 @@ declare function validFamily(family: CvmRegistryFamily): boolean;
|
|
|
77
77
|
*/
|
|
78
78
|
declare function createMultiplayerSettings(storage: StorageLike): MultiplayerSettings;
|
|
79
79
|
|
|
80
|
+
/** Which way a message went, from the applet's side. */
|
|
81
|
+
type AppletMessageDirection = 'from-applet' | 'to-applet';
|
|
82
|
+
/**
|
|
83
|
+
* One message between an applet and the shell. `via` is the channel: `window` for a window-level
|
|
84
|
+
* message (NIP-5D allows one, `napplet.hello`), `port` for everything on the bound port.
|
|
85
|
+
*/
|
|
86
|
+
interface AppletMessage {
|
|
87
|
+
readonly windowId: string;
|
|
88
|
+
readonly direction: AppletMessageDirection;
|
|
89
|
+
readonly via: 'window' | 'port';
|
|
90
|
+
/** The envelope's `type`, or `unknown` for anything that is not an envelope. */
|
|
91
|
+
readonly type: string;
|
|
92
|
+
/** What failed, when the envelope reports a failure; see {@link appletMessageFailure}. */
|
|
93
|
+
readonly error?: string;
|
|
94
|
+
/** The message itself. It can hold private messages, signed events and stored values: keep it in memory only. */
|
|
95
|
+
readonly message: unknown;
|
|
96
|
+
readonly at: number;
|
|
97
|
+
}
|
|
98
|
+
/**
|
|
99
|
+
* What an envelope says failed: its `error` string, or for a `*.error` envelope its `message`,
|
|
100
|
+
* its `reason` or its type. kehto's runtime answers a failed request with a `*.result` carrying
|
|
101
|
+
* `error`, so this covers its replies; kehto's own devtools read envelopes the same way.
|
|
102
|
+
*
|
|
103
|
+
* @param message - Any message an applet sent or received.
|
|
104
|
+
* @returns The failure, or `undefined` when the message reports none.
|
|
105
|
+
* @example
|
|
106
|
+
* ```ts
|
|
107
|
+
* appletMessageFailure({ type: 'inc.channel.open.result', id: '1', error: 'target denied' }); // 'target denied'
|
|
108
|
+
* appletMessageFailure({ type: 'storage.get.result', id: '2', value: 'x' }); // undefined
|
|
109
|
+
* ```
|
|
110
|
+
*/
|
|
111
|
+
declare function appletMessageFailure(message: unknown): string | undefined;
|
|
112
|
+
/**
|
|
113
|
+
* Describe one message for {@link AppletMessage} reporting, timestamped now.
|
|
114
|
+
*
|
|
115
|
+
* @param windowId - The applet's window.
|
|
116
|
+
* @param direction - Which way it went.
|
|
117
|
+
* @param via - The channel it went over.
|
|
118
|
+
* @param message - The message itself.
|
|
119
|
+
* @returns The report.
|
|
120
|
+
* @example
|
|
121
|
+
* ```ts
|
|
122
|
+
* describeAppletMessage('applet-1', 'to-applet', 'port', { type: 'shell.init', id: '1' }).type; // 'shell.init'
|
|
123
|
+
* ```
|
|
124
|
+
*/
|
|
125
|
+
declare function describeAppletMessage(windowId: string, direction: AppletMessageDirection, via: AppletMessage['via'], message: unknown): AppletMessage;
|
|
126
|
+
/** The shell's side of {@link AppletMessage} reporting. */
|
|
127
|
+
interface AppletTraffic {
|
|
128
|
+
readonly traffic$: Observable<AppletMessage>;
|
|
129
|
+
/** Report a message an applet sent. */
|
|
130
|
+
fromApplet(windowId: string, via: AppletMessage['via'], message: unknown): void;
|
|
131
|
+
/** Stop reporting; idempotent. */
|
|
132
|
+
close(): void;
|
|
133
|
+
}
|
|
134
|
+
/**
|
|
135
|
+
* Report what this shell's applets send and receive, for the windows `owns` accepts. Window ids
|
|
136
|
+
* are counted per shell, so two shells on one page can both have an `applet-1` and would each hear
|
|
137
|
+
* the other's; a host runs one shell per page.
|
|
138
|
+
*
|
|
139
|
+
* @param owns - Whether a window belongs to this shell.
|
|
140
|
+
* @returns The stream and the hooks that feed it.
|
|
141
|
+
* @example
|
|
142
|
+
* ```ts
|
|
143
|
+
* const traffic = createAppletTraffic((windowId) => handles.has(windowId));
|
|
144
|
+
* traffic.traffic$.subscribe((message) => log.push(message));
|
|
145
|
+
* ```
|
|
146
|
+
*/
|
|
147
|
+
declare function createAppletTraffic(owns: (windowId: string) => boolean): AppletTraffic;
|
|
148
|
+
|
|
80
149
|
/** The slice of applesauce's `RelayPool` kernl adapts. Narrow so tests can supply a fake. */
|
|
81
150
|
type ApplesaucePool = Pick<RelayPool, 'req' | 'request' | 'publish'>;
|
|
82
151
|
/**
|
|
@@ -213,6 +282,240 @@ interface ToolDiscoveryOptions {
|
|
|
213
282
|
*/
|
|
214
283
|
declare function discoverToolFamilies(input: string, options: ToolDiscoveryOptions): Promise<ToolFamilyCandidate[]>;
|
|
215
284
|
|
|
285
|
+
/** How a secrets provider keeps what it is given, so the shell can say so truthfully. */
|
|
286
|
+
interface SecretsDescription {
|
|
287
|
+
/** What the provider is, in a few plain words: "this browser", "the system keychain". */
|
|
288
|
+
readonly label: string;
|
|
289
|
+
/**
|
|
290
|
+
* `plain`: kept as typed, readable by anything that can read the shell's storage.
|
|
291
|
+
* `protected`: kept by something that guards it, such as a keychain, an extension or a service that asks before it answers.
|
|
292
|
+
* `session`: kept in memory only, gone when the shell closes.
|
|
293
|
+
*/
|
|
294
|
+
readonly keeps: 'plain' | 'protected' | 'session';
|
|
295
|
+
}
|
|
296
|
+
/**
|
|
297
|
+
* Where the shell keeps what must not be shown again: the passwords and keys of the
|
|
298
|
+
* services it signs in to for the person. It is one small contract so a host can put
|
|
299
|
+
* its own keeper behind it: a browser extension, a service running on the device, the
|
|
300
|
+
* platform's keychain in a native shell.
|
|
301
|
+
*
|
|
302
|
+
* Names are the shell's own, such as `download:transmission:password`; a provider keeps
|
|
303
|
+
* them apart from anything else it holds and never interprets them. Every method may
|
|
304
|
+
* reject with `unavailable:secrets` (the keeper cannot be reached) or `denied:secrets`
|
|
305
|
+
* (it, or the person, said no); a caller treats both as "not available now", never as
|
|
306
|
+
* "there is no secret". Identity keys are not kept here: they live in signers (SOUL opinion 1).
|
|
307
|
+
*/
|
|
308
|
+
interface SecretsProvider {
|
|
309
|
+
readonly description: SecretsDescription;
|
|
310
|
+
/** The secret under a name, or undefined when there is none. */
|
|
311
|
+
get(name: string): Promise<string | undefined>;
|
|
312
|
+
/** Keep a secret under a name, replacing any that was there. */
|
|
313
|
+
set(name: string, value: string): Promise<void>;
|
|
314
|
+
/** Forget the secret under a name; forgetting one that is not there succeeds. */
|
|
315
|
+
delete(name: string): Promise<void>;
|
|
316
|
+
}
|
|
317
|
+
/**
|
|
318
|
+
* The default provider: secrets kept in the host's storage, as typed. It protects nothing
|
|
319
|
+
* beyond what the storage itself does, and says so (`keeps: 'plain'`); a host that can do
|
|
320
|
+
* better passes its own provider as `KernlOptions.secrets`.
|
|
321
|
+
*
|
|
322
|
+
* @param storage - The host's storage; each secret is one key under `kernl:secrets:v1:`.
|
|
323
|
+
* @returns A provider over that storage; `set` rejects `unavailable:secrets` when the storage refuses the write.
|
|
324
|
+
* @example
|
|
325
|
+
* ```ts
|
|
326
|
+
* const secrets = createStorageSecrets(localStorage);
|
|
327
|
+
* await secrets.set('download:sabnzbd:apiKey', 'k1');
|
|
328
|
+
* await secrets.get('download:sabnzbd:apiKey'); // 'k1'
|
|
329
|
+
* ```
|
|
330
|
+
*/
|
|
331
|
+
declare function createStorageSecrets(storage: StorageLike): SecretsProvider;
|
|
332
|
+
/**
|
|
333
|
+
* A provider that keeps secrets in memory only, for a host that wants nothing written
|
|
334
|
+
* down and for a shell that is tried without leaving a trace.
|
|
335
|
+
*
|
|
336
|
+
* @returns A provider whose secrets end with it.
|
|
337
|
+
* @example
|
|
338
|
+
* ```ts
|
|
339
|
+
* const kernl = createKernl({ host, secrets: createMemorySecrets() });
|
|
340
|
+
* ```
|
|
341
|
+
*/
|
|
342
|
+
declare function createMemorySecrets(): SecretsProvider;
|
|
343
|
+
|
|
344
|
+
/**
|
|
345
|
+
* The shapes the person's download connections take (D-053). A person may set up any number
|
|
346
|
+
* of connections, several of the same program among them; kernl routes each applet's work to
|
|
347
|
+
* one. These types are the contract between the settings store, the three services and the
|
|
348
|
+
* settings form.
|
|
349
|
+
*/
|
|
350
|
+
/** A program kernl can drive for the person, by the name it is known by. */
|
|
351
|
+
type DownloadProgram = 'transmission' | 'utorrent' | 'nzbget' | 'sabnzbd' | 'slskd';
|
|
352
|
+
/** The NAP domains the programs serve. */
|
|
353
|
+
type DownloadDomain = 'torrent' | 'nzb' | 'soulseek';
|
|
354
|
+
/** The domains where kernl, not the applet, picks the connection new work goes to. */
|
|
355
|
+
type RoutedDomain = Extract<DownloadDomain, 'torrent' | 'soulseek'>;
|
|
356
|
+
/** The client contract each domain's programs speak. */
|
|
357
|
+
type ClientFor<D extends DownloadDomain> = D extends 'torrent' ? TorrentClient : D extends 'nzb' ? NzbClient : SoulseekClient;
|
|
358
|
+
/** What the person types for a connection: its address and its sign-in. */
|
|
359
|
+
type DownloadSignIn = ClientEndpoint;
|
|
360
|
+
/** One connection to one program, as settings keep it. It never holds a secret, only whether one is kept. */
|
|
361
|
+
interface DownloadConnection {
|
|
362
|
+
/** Shell-issued and random; stable for the connection's life, whatever is edited. Never shown and never sent to an applet. */
|
|
363
|
+
readonly id: string;
|
|
364
|
+
readonly program: DownloadProgram;
|
|
365
|
+
/** The person's name for it, 1 to 60 characters; the program's name, numbered when taken, until they change it. */
|
|
366
|
+
readonly label: string;
|
|
367
|
+
readonly url: string;
|
|
368
|
+
readonly username?: string;
|
|
369
|
+
readonly hasPassword: boolean;
|
|
370
|
+
readonly hasApiKey: boolean;
|
|
371
|
+
/**
|
|
372
|
+
* Changes whenever the address changes. Services key what they hand applets by it, so a handle
|
|
373
|
+
* issued for jobs at the old address can never reach a different server's job with the same id.
|
|
374
|
+
*/
|
|
375
|
+
readonly routingKey: string;
|
|
376
|
+
}
|
|
377
|
+
/** What the person set up on this device. */
|
|
378
|
+
interface DownloadClientsState {
|
|
379
|
+
/** Every connection, in the order it was added. */
|
|
380
|
+
readonly connections: readonly DownloadConnection[];
|
|
381
|
+
/** Which connection new torrents and new searches go to, by connection id. The first of a kind until the person chooses. */
|
|
382
|
+
readonly defaults: Readonly<Partial<Record<RoutedDomain, string>>>;
|
|
383
|
+
/** Connections whose kept sign-in the secrets provider would not hand over, or no longer has, by id; they serve nobody until signed in to again. */
|
|
384
|
+
readonly locked: readonly string[];
|
|
385
|
+
}
|
|
386
|
+
/** A connection with the live client that speaks to it. */
|
|
387
|
+
interface RoutedClient<T> {
|
|
388
|
+
readonly connection: DownloadConnection;
|
|
389
|
+
readonly client: T;
|
|
390
|
+
}
|
|
391
|
+
/**
|
|
392
|
+
* How a service reaches one domain's connections. It is read on every call, so a connection the
|
|
393
|
+
* person edits or removes is seen at once: a record keeps a connection id and resolves it each time.
|
|
394
|
+
*/
|
|
395
|
+
interface ConnectionRouting<T> {
|
|
396
|
+
/** Every connection that can serve now (set up and not locked), in the order added. */
|
|
397
|
+
all(): readonly RoutedClient<T>[];
|
|
398
|
+
/** One connection by id; undefined when it was removed or is locked. */
|
|
399
|
+
byId(id: string): RoutedClient<T> | undefined;
|
|
400
|
+
/** Where new work goes: the person's default for the domain, else the first that can serve. Undefined when none can. */
|
|
401
|
+
preferred(): RoutedClient<T> | undefined;
|
|
402
|
+
}
|
|
403
|
+
/** A sign-in that was checked and answered. */
|
|
404
|
+
interface CheckedConnection {
|
|
405
|
+
/** The sign-in as it should be saved: the address with its scheme worked out, and what was typed. */
|
|
406
|
+
readonly signIn: DownloadSignIn;
|
|
407
|
+
/** What the person should know about the address, such as that it is not encrypted. */
|
|
408
|
+
readonly notes: readonly EndpointNote[];
|
|
409
|
+
readonly probe: ClientProbe;
|
|
410
|
+
}
|
|
411
|
+
/** A change to an existing connection; what is left out stays as it is. */
|
|
412
|
+
interface ConnectionChange {
|
|
413
|
+
readonly label?: string;
|
|
414
|
+
/** A secret left empty is the kept one for the same address, and is forgotten for a new one. */
|
|
415
|
+
readonly signIn?: DownloadSignIn;
|
|
416
|
+
}
|
|
417
|
+
/** The person's download connections, and the routing the services read. */
|
|
418
|
+
interface DownloadClients {
|
|
419
|
+
readonly state$: Observable<DownloadClientsState>;
|
|
420
|
+
state(): DownloadClientsState;
|
|
421
|
+
/** Settles once the kept sign-ins have been asked for from the secrets provider; connections serve from then on. */
|
|
422
|
+
readonly ready: Promise<void>;
|
|
423
|
+
/**
|
|
424
|
+
* Work out the address's scheme when none was typed, check it against how kernl is served, and
|
|
425
|
+
* ask the program whether it is there. Saves nothing. With `existing`, a password or key left
|
|
426
|
+
* empty is that connection's kept one, but only for the address it was kept for. Rejects with
|
|
427
|
+
* the reason a person can be told: `invalid:…`, `denied:credentials`, `unavailable:…`.
|
|
428
|
+
*/
|
|
429
|
+
check(program: DownloadProgram, typed: DownloadSignIn, existing?: string): Promise<CheckedConnection>;
|
|
430
|
+
/**
|
|
431
|
+
* Keep a new connection. Its label defaults to the program's name, numbered when taken. Rejects
|
|
432
|
+
* `invalid:…` when the address, label or sign-in cannot be used from this page, and with the
|
|
433
|
+
* secrets provider's reason when it will not keep a secret; nothing is saved then.
|
|
434
|
+
*/
|
|
435
|
+
add(program: DownloadProgram, signIn: DownloadSignIn, label?: string): Promise<DownloadConnection>;
|
|
436
|
+
/** Change a connection's label or sign-in. A new address gives it a new `routingKey`. Rejects `invalid:connection` for an unknown id. */
|
|
437
|
+
update(id: string, change: ConnectionChange): Promise<DownloadConnection>;
|
|
438
|
+
/** Forget a connection and its kept secrets. Removing a domain's default makes the next of its kind the default. */
|
|
439
|
+
remove(id: string): Promise<void>;
|
|
440
|
+
/** Choose where new work for a domain goes. Throws `invalid:connection` when the id is not a connection serving that domain. */
|
|
441
|
+
chooseDefault(domain: RoutedDomain, id: string): void;
|
|
442
|
+
/** The routing one domain's service reads. */
|
|
443
|
+
routing<D extends DownloadDomain>(domain: D): ConnectionRouting<ClientFor<D>>;
|
|
444
|
+
}
|
|
445
|
+
|
|
446
|
+
/** What a program is for, and what it asks for before it answers. */
|
|
447
|
+
interface DownloadProgramInfo {
|
|
448
|
+
/** The NAP domain the program serves. */
|
|
449
|
+
readonly domain: DownloadDomain;
|
|
450
|
+
/** The program's own name, as its makers write it. */
|
|
451
|
+
readonly name: string;
|
|
452
|
+
/** Which sign-in fields the program takes. */
|
|
453
|
+
readonly signIn: readonly ('username' | 'password' | 'apiKey')[];
|
|
454
|
+
/** An address the program answers at when it runs on this device with its usual settings. */
|
|
455
|
+
readonly example: string;
|
|
456
|
+
}
|
|
457
|
+
/**
|
|
458
|
+
* Every program kernl can drive, with the domain it serves and the sign-in it takes.
|
|
459
|
+
*
|
|
460
|
+
* @example
|
|
461
|
+
* ```ts
|
|
462
|
+
* DOWNLOAD_PROGRAMS.sabnzbd.signIn; // ['apiKey']
|
|
463
|
+
* DOWNLOAD_PROGRAMS.transmission.domain; // 'torrent'
|
|
464
|
+
* ```
|
|
465
|
+
*/
|
|
466
|
+
declare const DOWNLOAD_PROGRAMS: Readonly<Record<DownloadProgram, DownloadProgramInfo>>;
|
|
467
|
+
|
|
468
|
+
/** Options for {@link createDownloadClients}. */
|
|
469
|
+
interface DownloadClientsOptions {
|
|
470
|
+
readonly storage: StorageLike;
|
|
471
|
+
/** Where passwords and keys are kept; the host's storage, as typed, by default. */
|
|
472
|
+
readonly secrets?: SecretsProvider;
|
|
473
|
+
/** How the page running kernl was loaded; read from `location` by default, `http` where there is none. */
|
|
474
|
+
readonly pageScheme?: () => PageScheme;
|
|
475
|
+
/** `fetch` for every program; the global one by default. */
|
|
476
|
+
readonly fetch?: ClientFetch;
|
|
477
|
+
}
|
|
478
|
+
/**
|
|
479
|
+
* How the page running the shell was loaded, from `location`. Where there is no page, as in a
|
|
480
|
+
* host outside a browser, nothing restricts which addresses can be called, which is `http`'s rule.
|
|
481
|
+
*
|
|
482
|
+
* @returns `https` for a page loaded over it, otherwise `http`.
|
|
483
|
+
* @example
|
|
484
|
+
* ```ts
|
|
485
|
+
* currentPageScheme(); // 'https' on https://kernl.run/app/
|
|
486
|
+
* ```
|
|
487
|
+
*/
|
|
488
|
+
declare function currentPageScheme(): PageScheme;
|
|
489
|
+
/**
|
|
490
|
+
* The person's download connections, and the routing the `torrent`, `nzb` and `soulseek`
|
|
491
|
+
* services read (D-050, D-053). A person may set up any number of connections, several of the
|
|
492
|
+
* same program among them; each has a random id and a label of their own.
|
|
493
|
+
*
|
|
494
|
+
* Addresses, usernames and labels are kept on this device at `kernl:download-programs:v1`.
|
|
495
|
+
* Passwords and keys are not: they go to the secrets provider under
|
|
496
|
+
* `download:<connection id>:password` and `…:apiKey`, and are held in memory only for the
|
|
497
|
+
* clients that sign in with them, so nothing that reads settings, the settings form included,
|
|
498
|
+
* is ever handed one (D-052). A connection serves nobody until the provider has answered for
|
|
499
|
+
* its kept sign-in, and none whose sign-in the provider will not hand over (it is `locked`).
|
|
500
|
+
*
|
|
501
|
+
* An address is checked against how kernl itself is served before it is kept or used: a page
|
|
502
|
+
* loaded over `https` may call a plain `http` address only on this device, so anything else is
|
|
503
|
+
* refused as `invalid:mixed-content`. An address typed without a scheme has it worked out by
|
|
504
|
+
* asking the program, `https` first. What comes back out of storage is checked again and
|
|
505
|
+
* dropped when it no longer passes.
|
|
506
|
+
*
|
|
507
|
+
* @param options - Storage, and optionally the secrets provider, how the page was loaded and the `fetch` to use.
|
|
508
|
+
* @returns The settings and the routing built from them.
|
|
509
|
+
* @example
|
|
510
|
+
* ```ts
|
|
511
|
+
* const programs = createDownloadClients({ storage: localStorage });
|
|
512
|
+
* const { signIn } = await programs.check('transmission', { url: 'localhost:9091', username: 'me', password: 'secret' });
|
|
513
|
+
* const home = await programs.add('transmission', signIn, 'Home');
|
|
514
|
+
* await programs.routing('torrent').byId(home.id)?.client.list();
|
|
515
|
+
* ```
|
|
516
|
+
*/
|
|
517
|
+
declare function createDownloadClients(options: DownloadClientsOptions): DownloadClients;
|
|
518
|
+
|
|
216
519
|
/** One applet as the store lists it. Read from a signed manifest; its bytes are verified only when it is opened. */
|
|
217
520
|
interface CatalogEntry {
|
|
218
521
|
/** kehto's publisher- and kind-safe identity; the same id the intent catalogue uses. */
|
|
@@ -594,15 +897,15 @@ declare function relayUrls(urls: Iterable<string>): string[];
|
|
|
594
897
|
declare function summarizePublish(responses: readonly PublishAnswer[]): PublishOutcome;
|
|
595
898
|
/**
|
|
596
899
|
* Say what came of a publish in words for the person. The sentence never
|
|
597
|
-
* repeats a
|
|
900
|
+
* repeats a relay's reason, which is written for developers and often names
|
|
598
901
|
* the protocol.
|
|
599
902
|
*
|
|
600
903
|
* @param outcome - The result of {@link summarizePublish}.
|
|
601
|
-
* @returns A sentence such as `Saved to 2 of 3
|
|
904
|
+
* @returns A sentence such as `Saved to 2 of 3 relays` or `No relay accepted it`.
|
|
602
905
|
* @example
|
|
603
906
|
* ```ts
|
|
604
907
|
* describeOutcome({ accepted: ['wss://a/'], refused: [{ url: 'wss://b/', reason: 'blocked' }], ok: true });
|
|
605
|
-
* // 'Saved to 1 of 2
|
|
908
|
+
* // 'Saved to 1 of 2 relays'
|
|
606
909
|
* ```
|
|
607
910
|
*/
|
|
608
911
|
declare function describeOutcome(outcome: PublishOutcome): string;
|
|
@@ -707,7 +1010,7 @@ declare function mailboxTags(mailboxes: Mailboxes, previous?: NostrEvent$1): str
|
|
|
707
1010
|
* const mailboxes = createAccountMailboxes({ store, pool, pubkey$, lookupRelays: () => tiers.get().discovery, signer });
|
|
708
1011
|
* mailboxes.state$.subscribe((state) => render(state));
|
|
709
1012
|
* const outcome = await mailboxes.save({ inboxes: ['wss://in.example'], outboxes: ['wss://out.example'] });
|
|
710
|
-
* describeOutcome(outcome); // 'Saved to 3 of 4
|
|
1013
|
+
* describeOutcome(outcome); // 'Saved to 3 of 4 relays'
|
|
711
1014
|
* ```
|
|
712
1015
|
*/
|
|
713
1016
|
declare function createAccountMailboxes(options: AccountMailboxesOptions): AccountMailboxes;
|
|
@@ -1150,6 +1453,52 @@ interface InstalledApplets {
|
|
|
1150
1453
|
*/
|
|
1151
1454
|
declare function createInstalledApplets(storage: StorageLike, now?: () => number): InstalledApplets;
|
|
1152
1455
|
|
|
1456
|
+
/** A key press, as the page's `KeyboardEvent` names its parts. */
|
|
1457
|
+
interface ShortcutKey {
|
|
1458
|
+
readonly key: string;
|
|
1459
|
+
readonly code: string;
|
|
1460
|
+
readonly ctrlKey: boolean;
|
|
1461
|
+
readonly altKey: boolean;
|
|
1462
|
+
readonly shiftKey: boolean;
|
|
1463
|
+
readonly metaKey: boolean;
|
|
1464
|
+
}
|
|
1465
|
+
/** The host's settings for applets' keyboard shortcuts. */
|
|
1466
|
+
interface ShortcutSettings {
|
|
1467
|
+
/** Chords the shell keeps for itself, such as `'Alt+/'`; an applet asking for one is answered without a binding. */
|
|
1468
|
+
readonly reserved?: readonly string[];
|
|
1469
|
+
/** Where key presses outside applets are heard; the page's `document` by default, and nowhere when there is none. */
|
|
1470
|
+
readonly target?: EventTarget;
|
|
1471
|
+
}
|
|
1472
|
+
/** Options for {@link createShortcutsService}. */
|
|
1473
|
+
interface ShortcutsOptions extends ShortcutSettings {
|
|
1474
|
+
/** Whether a window is the focused one, as the shell's window manager reports it. */
|
|
1475
|
+
readonly isFocused: (windowId: string) => boolean;
|
|
1476
|
+
}
|
|
1477
|
+
/** The `keys` service, with the listener it must give back. */
|
|
1478
|
+
type ShortcutsService = ServiceHandler & {
|
|
1479
|
+
destroy(): void;
|
|
1480
|
+
};
|
|
1481
|
+
/**
|
|
1482
|
+
* The `keys` domain (D-054): kehto's reference service, which binds the key an
|
|
1483
|
+
* applet asks for, tells it which keys it holds and runs its action when the
|
|
1484
|
+
* key is pressed outside every applet, behind three rules of kernl's. A key
|
|
1485
|
+
* pressed on the shell's own page reaches applets only when the shell did not
|
|
1486
|
+
* use it: not one it handled, and not one typed into a field or pressed on a
|
|
1487
|
+
* button. The action runs in the focused window only, where kehto would run it
|
|
1488
|
+
* in every window that bound the key, so two windows of one applet do not both
|
|
1489
|
+
* act. And a key that ran an action does nothing else on the page. A key
|
|
1490
|
+
* pressed inside an applet never comes through here: the frame knows its own
|
|
1491
|
+
* bindings and runs the action itself.
|
|
1492
|
+
*
|
|
1493
|
+
* @param options - Reserved chords, where keys are heard and the focus source.
|
|
1494
|
+
* @returns The service for the registry; call `destroy()` to stop listening.
|
|
1495
|
+
* @example
|
|
1496
|
+
* ```ts
|
|
1497
|
+
* registry.keys = createShortcutsService({ reserved: ['Alt+/'], isFocused: (windowId) => wm.isFocused(windowId) });
|
|
1498
|
+
* ```
|
|
1499
|
+
*/
|
|
1500
|
+
declare function createShortcutsService(options: ShortcutsOptions): ShortcutsService;
|
|
1501
|
+
|
|
1153
1502
|
/** The two values an applet's grants are keyed on. Both come from verification, never from the applet. */
|
|
1154
1503
|
interface AppletIdentity {
|
|
1155
1504
|
readonly dTag: string;
|
|
@@ -1232,6 +1581,23 @@ interface MountPlan {
|
|
|
1232
1581
|
readonly missingRequired: readonly string[];
|
|
1233
1582
|
}
|
|
1234
1583
|
/** Lifecycle of one mounted applet. */
|
|
1584
|
+
/** A guard limit an applet crossed and was quarantined for. */
|
|
1585
|
+
interface AppletStopLimit {
|
|
1586
|
+
/** `flood`: too many messages inside the quarantine window. `hidden-resource`: too many web fetches while hidden. */
|
|
1587
|
+
readonly cause: 'flood' | 'hidden-resource';
|
|
1588
|
+
/** The limit itself, from the profile in force when the applet was stopped. */
|
|
1589
|
+
readonly count: number;
|
|
1590
|
+
/** The span `count` is measured over, in milliseconds; absent for `hidden-resource`. */
|
|
1591
|
+
readonly windowMs?: number;
|
|
1592
|
+
readonly profile: GuardProfile;
|
|
1593
|
+
}
|
|
1594
|
+
/** What is known about why an applet was stopped, beyond its reason code. */
|
|
1595
|
+
interface AppletStopDetails {
|
|
1596
|
+
/** kehto's own diagnostic line, for a reason kehto observed. Never carries a message payload. */
|
|
1597
|
+
readonly detail?: string;
|
|
1598
|
+
/** The guard limit crossed, for a quarantine. */
|
|
1599
|
+
readonly limit?: AppletStopLimit;
|
|
1600
|
+
}
|
|
1235
1601
|
type AppletStatus = 'mounting' | 'running' | 'revoked' | 'closed';
|
|
1236
1602
|
/** The structural subset of an iframe element `mountApplet` needs. Lets the core stay DOM-free in tests. */
|
|
1237
1603
|
interface FrameLike {
|
|
@@ -1298,10 +1664,101 @@ interface ConsentSummary {
|
|
|
1298
1664
|
readonly severity: 'routine' | 'destructive' | 'public' | 'direct';
|
|
1299
1665
|
readonly lines: readonly ConsentLine[];
|
|
1300
1666
|
readonly applet: AppletIdentity;
|
|
1301
|
-
/** The raw event, for an "advanced" disclosure. */
|
|
1302
|
-
readonly event
|
|
1667
|
+
/** The raw event, for an "advanced" disclosure; absent when what is asked about is not an event. */
|
|
1668
|
+
readonly event?: NostrEvent;
|
|
1303
1669
|
}
|
|
1304
1670
|
/** What the host must answer. */
|
|
1671
|
+
/** An answer the person can give to a firewall question. `allow-session` lasts while the applet stays open. */
|
|
1672
|
+
type FirewallChoice = 'allow-once' | 'allow-session' | 'allow-always' | 'deny';
|
|
1673
|
+
/** The applet a firewall question or stored answer is about. */
|
|
1674
|
+
interface FirewallApplet {
|
|
1675
|
+
readonly title: string;
|
|
1676
|
+
/** The applet across its versions; firewall rules are keyed by it. */
|
|
1677
|
+
readonly catalogId: string;
|
|
1678
|
+
/** The exact code that asked; stored answers are tied to it. */
|
|
1679
|
+
readonly identity: AppletIdentity;
|
|
1680
|
+
}
|
|
1681
|
+
/** One thing an applet asked for, named by identifiers the host words. */
|
|
1682
|
+
interface FirewallRequest {
|
|
1683
|
+
/** `access` is the use of a whole domain; `resource` one named thing; `network` one server. */
|
|
1684
|
+
readonly kind: 'access' | 'resource' | 'network';
|
|
1685
|
+
readonly domain: string;
|
|
1686
|
+
/** The request, such as `link.open`; `access` for a whole domain. */
|
|
1687
|
+
readonly operation: string;
|
|
1688
|
+
/** What exactly: the link, the server's origin, or the domain. */
|
|
1689
|
+
readonly target: string;
|
|
1690
|
+
}
|
|
1691
|
+
/** What a firewall question shows. It carries no copy; the host words it. */
|
|
1692
|
+
interface FirewallSummary {
|
|
1693
|
+
/** `link` opens something outside the shell; `access` is an applet starting with a domain; `request` is anything else. */
|
|
1694
|
+
readonly kind: 'link' | 'access' | 'request';
|
|
1695
|
+
readonly applet: FirewallApplet;
|
|
1696
|
+
readonly requests: readonly FirewallRequest[];
|
|
1697
|
+
/** The answers open to the person, most generous last but for `deny`, which is always last. */
|
|
1698
|
+
readonly choices: readonly FirewallChoice[];
|
|
1699
|
+
}
|
|
1700
|
+
/** A firewall question waiting for the person. */
|
|
1701
|
+
interface FirewallPrompt {
|
|
1702
|
+
readonly summary: FirewallSummary;
|
|
1703
|
+
/** Aborts when the request is withdrawn: the applet closed, or the question went unanswered too long. */
|
|
1704
|
+
readonly signal: {
|
|
1705
|
+
readonly aborted: boolean;
|
|
1706
|
+
addEventListener(type: 'abort', listener: () => void, options?: {
|
|
1707
|
+
once?: boolean;
|
|
1708
|
+
}): void;
|
|
1709
|
+
removeEventListener(type: 'abort', listener: () => void): void;
|
|
1710
|
+
};
|
|
1711
|
+
/** Answer with one of `summary.choices`; `undefined` dismisses without storing anything. */
|
|
1712
|
+
resolve(choice: FirewallChoice | undefined): void;
|
|
1713
|
+
}
|
|
1714
|
+
/** An answer in force: one the person gave, or one a rule gave for a running applet. */
|
|
1715
|
+
interface FirewallDecision {
|
|
1716
|
+
readonly id: string;
|
|
1717
|
+
/** The applet's catalogue id and the exact code the answer is tied to. */
|
|
1718
|
+
readonly catalogId: string;
|
|
1719
|
+
readonly hash: string;
|
|
1720
|
+
readonly request: FirewallRequest;
|
|
1721
|
+
readonly effect: 'allow' | 'deny';
|
|
1722
|
+
/** `session` ends when the applet's window does; `always` is kept across visits. */
|
|
1723
|
+
readonly lifetime: 'session' | 'always';
|
|
1724
|
+
/** True when a rule gave the answer, not the person. */
|
|
1725
|
+
readonly byRule: boolean;
|
|
1726
|
+
}
|
|
1727
|
+
/** Which firewall rule to change: everything, one domain or one request, for every applet or for one. */
|
|
1728
|
+
interface FirewallRuleTarget {
|
|
1729
|
+
/** The applet's catalogue id, as in `summary.manifest.catalogId`; every applet when absent. */
|
|
1730
|
+
readonly applet?: string;
|
|
1731
|
+
/** A whole domain, such as `relay`. */
|
|
1732
|
+
readonly domain?: string;
|
|
1733
|
+
/** One kind of request, such as `link.open`. */
|
|
1734
|
+
readonly operation?: string;
|
|
1735
|
+
}
|
|
1736
|
+
/**
|
|
1737
|
+
* The firewall: what happens to a request no stored answer covers, and the answers in force (D-056).
|
|
1738
|
+
* Grants decide which domains an applet holds; the firewall decides, inside those, what goes ahead
|
|
1739
|
+
* without asking, what asks, and what is refused.
|
|
1740
|
+
*/
|
|
1741
|
+
interface Firewall {
|
|
1742
|
+
/** The rules in force. A shell starts with everything allowed and links asking. */
|
|
1743
|
+
rules(): PermissionRules;
|
|
1744
|
+
readonly rules$: Observable<PermissionRules>;
|
|
1745
|
+
/**
|
|
1746
|
+
* Set one rule, or remove it with `undefined`. An applet running under an answer the new rules
|
|
1747
|
+
* no longer give is stopped. Throws `invalid:rule` for a malformed target.
|
|
1748
|
+
*/
|
|
1749
|
+
setRule(target: FirewallRuleTarget, action: PermissionRuleAction | undefined): void;
|
|
1750
|
+
restoreDefaults(): void;
|
|
1751
|
+
/** False when the stored answers could not be read: every applet is refused until `forgetAll()` clears them. */
|
|
1752
|
+
readonly available: boolean;
|
|
1753
|
+
/** Answers in force, the person's and the rules'. */
|
|
1754
|
+
decisions(): readonly FirewallDecision[];
|
|
1755
|
+
/** Emits whenever an answer is given, used up or taken back. */
|
|
1756
|
+
readonly decisions$: Observable<readonly FirewallDecision[]>;
|
|
1757
|
+
/** Take one answer back; an applet running under it is stopped. False when the stored copy could not be removed. */
|
|
1758
|
+
forget(id: string): boolean;
|
|
1759
|
+
/** Take every answer back and stop every applet. False when the stored copy could not be removed. */
|
|
1760
|
+
forgetAll(): boolean;
|
|
1761
|
+
}
|
|
1305
1762
|
interface ConsentPrompt {
|
|
1306
1763
|
readonly summary: ConsentSummary;
|
|
1307
1764
|
resolve(allowed: boolean): void;
|
|
@@ -1371,12 +1828,21 @@ interface KernlHost {
|
|
|
1371
1828
|
readonly windowId?: string;
|
|
1372
1829
|
readonly tone: 'info' | 'warning';
|
|
1373
1830
|
}): void;
|
|
1374
|
-
/**
|
|
1375
|
-
|
|
1831
|
+
/**
|
|
1832
|
+
* Open a link outside the shell. `approved` is set when the firewall already let this exact link
|
|
1833
|
+
* through, by asking the person or by a rule they set, so the host should not ask again.
|
|
1834
|
+
*/
|
|
1835
|
+
openLink(url: string, options?: {
|
|
1836
|
+
readonly approved?: boolean;
|
|
1837
|
+
}): void;
|
|
1376
1838
|
/** Current visibility for a window, when the core needs it synchronously. */
|
|
1377
1839
|
getVisibility(windowId: string): WindowVisibility;
|
|
1378
|
-
/**
|
|
1379
|
-
|
|
1840
|
+
/**
|
|
1841
|
+
* Called after the core removed a frame because its binding was revoked. `reason` is a stable
|
|
1842
|
+
* code: one of kehto's revocation reasons, or kernl's own (`quarantine`, `host`, `grant-narrowed`,
|
|
1843
|
+
* `blocked`, `firewall`). `details` carries what else is known about the stop.
|
|
1844
|
+
*/
|
|
1845
|
+
onRevoked(windowId: string, reason: string, details?: AppletStopDetails): void;
|
|
1380
1846
|
/**
|
|
1381
1847
|
* Ask the user which applet should take a request. Resolve `undefined` on
|
|
1382
1848
|
* dismiss. Without it, requests with several handlers and no default are refused.
|
|
@@ -1392,8 +1858,18 @@ interface KernlHost {
|
|
|
1392
1858
|
* provider the user's order picked is used.
|
|
1393
1859
|
*/
|
|
1394
1860
|
chooseReply?(prompt: ReplyPrompt): Promise<ReplyAnswer | undefined>;
|
|
1861
|
+
/**
|
|
1862
|
+
* Put a firewall question to the person: a request a rule says to ask about, such as opening a link.
|
|
1863
|
+
* Close the prompt when `signal` aborts. Without it, such a request is refused (D-056).
|
|
1864
|
+
*/
|
|
1865
|
+
presentApproval?(prompt: FirewallPrompt): void;
|
|
1395
1866
|
/** Verify an artifact blob. Defaults to `fetch` over the manifest's servers. */
|
|
1396
1867
|
fetchBlob?(sha256: string, servers: readonly string[]): Promise<Uint8Array>;
|
|
1868
|
+
/**
|
|
1869
|
+
* Take a key pressed inside an applet that the applet has no shortcut for. Without it the
|
|
1870
|
+
* shell's own shortcuts do nothing while an applet has focus (D-054).
|
|
1871
|
+
*/
|
|
1872
|
+
onShortcut?(key: ShortcutKey): void;
|
|
1397
1873
|
now?(): number;
|
|
1398
1874
|
}
|
|
1399
1875
|
/**
|
|
@@ -1442,6 +1918,25 @@ interface KernlOptions {
|
|
|
1442
1918
|
readonly remoteTools?: RemoteToolsSettings;
|
|
1443
1919
|
/** How applets connect people directly: the relays that introduce them and the ICE servers that help (D-042). */
|
|
1444
1920
|
readonly directConnections?: DirectConnectionsSettings;
|
|
1921
|
+
/** How the shell reaches the person's download programs, and whether their domains are offered (D-050). */
|
|
1922
|
+
readonly downloads?: DownloadsOptions;
|
|
1923
|
+
/** Where the shell keeps passwords and keys of services it signs in to; the host's storage, as typed, by default (D-052). */
|
|
1924
|
+
readonly secrets?: SecretsProvider;
|
|
1925
|
+
/** The chords the shell keeps from applets' keyboard shortcuts, and where key presses are heard (D-054). */
|
|
1926
|
+
readonly shortcuts?: ShortcutSettings;
|
|
1927
|
+
}
|
|
1928
|
+
/** The host's settings for the `torrent`, `nzb` and `soulseek` domains. */
|
|
1929
|
+
interface DownloadsOptions {
|
|
1930
|
+
/** How the page running the shell was loaded; read from `location` by default, `http` where there is none. */
|
|
1931
|
+
readonly pageScheme?: () => PageScheme;
|
|
1932
|
+
/** `fetch` for every download program; the global one by default. */
|
|
1933
|
+
readonly fetch?: ClientFetch;
|
|
1934
|
+
/**
|
|
1935
|
+
* Whether the three domains are offered to applets. By default they are offered exactly when
|
|
1936
|
+
* the installed `@kehto/shell` can bind a domain it does not build in; a host whose own
|
|
1937
|
+
* prelude binds them says `true`.
|
|
1938
|
+
*/
|
|
1939
|
+
readonly offer?: boolean;
|
|
1445
1940
|
}
|
|
1446
1941
|
/** A STUN or TURN server, as `RTCPeerConnection` takes it. Its credentials stay in the shell. */
|
|
1447
1942
|
interface DirectIceServer {
|
|
@@ -1503,6 +1998,11 @@ interface Kernl {
|
|
|
1503
1998
|
readonly pool: RelayPool;
|
|
1504
1999
|
readonly bridge: ShellBridge;
|
|
1505
2000
|
readonly guard: GuardFacade;
|
|
2001
|
+
/**
|
|
2002
|
+
* Every message between this shell's applets and itself, both ways, on the window and on the
|
|
2003
|
+
* port. Envelopes can hold private messages and signed events: a host keeps them in memory only.
|
|
2004
|
+
*/
|
|
2005
|
+
readonly traffic$: Observable<AppletMessage>;
|
|
1506
2006
|
readonly grants: Grants;
|
|
1507
2007
|
readonly relays: RelayTiers;
|
|
1508
2008
|
readonly messaging: MessagingRegistry;
|
|
@@ -1518,9 +2018,15 @@ interface Kernl {
|
|
|
1518
2018
|
readonly files: AccountFileServers;
|
|
1519
2019
|
/** The person's servers, helpers and trusted tool families for meeting people and calling remote tools (D-043). */
|
|
1520
2020
|
readonly multiplayer: KernlMultiplayer;
|
|
2021
|
+
/** The download programs the person set up on this device, and the check an address goes through before it is kept (D-050). */
|
|
2022
|
+
readonly downloads: DownloadClients;
|
|
2023
|
+
/** How the shell's secrets are kept, so a settings screen can say so (D-052). */
|
|
2024
|
+
readonly secrets: SecretsDescription;
|
|
1521
2025
|
/** Monitored servers (NIP-66) for completing and suggesting; idle until `start()`. */
|
|
1522
2026
|
readonly directory: RelayDirectory;
|
|
1523
2027
|
readonly intents: Intents;
|
|
2028
|
+
/** The rules for what applets may ask for without the person being asked, and the answers in force. */
|
|
2029
|
+
readonly firewall: Firewall;
|
|
1524
2030
|
readonly session$: Observable<Session | null>;
|
|
1525
2031
|
readonly session: Session | null;
|
|
1526
2032
|
login(account: IAccount): Promise<Session>;
|
|
@@ -2304,6 +2810,66 @@ declare function builtinAddress(id: string): string;
|
|
|
2304
2810
|
*/
|
|
2305
2811
|
declare function resolveBuiltin(builtins: readonly BuiltinApplet[], id: string): Promise<ResolvedApplet>;
|
|
2306
2812
|
|
|
2813
|
+
/**
|
|
2814
|
+
* One operation of a domain, as the applet calls it and as it travels: the request type,
|
|
2815
|
+
* the wire fields its arguments fill in order, and the field of the result it resolves with.
|
|
2816
|
+
*
|
|
2817
|
+
* The shape is `NappletBindingMethod` from kehto/web#413, declared here until a released
|
|
2818
|
+
* `@kehto/shell` exports it.
|
|
2819
|
+
*/
|
|
2820
|
+
interface DomainBindingMethod {
|
|
2821
|
+
readonly type: string;
|
|
2822
|
+
readonly params: readonly string[];
|
|
2823
|
+
readonly reply: boolean;
|
|
2824
|
+
readonly result?: string;
|
|
2825
|
+
}
|
|
2826
|
+
/** What `window.napplet.<domain>` offers an applet: its operations and the messages the shell may push. */
|
|
2827
|
+
interface DomainBinding {
|
|
2828
|
+
readonly methods: Readonly<Record<string, DomainBindingMethod>>;
|
|
2829
|
+
readonly events?: readonly string[];
|
|
2830
|
+
readonly handlers?: Readonly<Record<string, readonly string[]>>;
|
|
2831
|
+
}
|
|
2832
|
+
/** Prelude options with the `bindings` kehto/web#413 adds; an older `@kehto/shell` ignores the field. */
|
|
2833
|
+
type BoundPreludeOptions = NappletNamespacePreludeOptions & {
|
|
2834
|
+
readonly bindings?: Readonly<Record<string, DomainBinding>>;
|
|
2835
|
+
};
|
|
2836
|
+
/**
|
|
2837
|
+
* The applet-side bindings for the three download domains, one row per operation of
|
|
2838
|
+
* NAP-TORRENT, NAP-NZB and NAP-SOULSEEK's wire tables. The shell hands them to kehto's
|
|
2839
|
+
* namespace prelude, which turns each row into a method over the applet's private port.
|
|
2840
|
+
*
|
|
2841
|
+
* @example
|
|
2842
|
+
* ```ts
|
|
2843
|
+
* DOWNLOAD_BINDINGS.torrent?.methods.add; // { type: 'torrent.add', params: ['request'], reply: true, result: 'ack' }
|
|
2844
|
+
* Object.keys(DOWNLOAD_BINDINGS); // ['torrent', 'nzb', 'soulseek']
|
|
2845
|
+
* ```
|
|
2846
|
+
*/
|
|
2847
|
+
declare const DOWNLOAD_BINDINGS: Readonly<Record<string, DomainBinding>>;
|
|
2848
|
+
/**
|
|
2849
|
+
* Whether the installed `@kehto/shell` can give an applet a domain it does not build in.
|
|
2850
|
+
*
|
|
2851
|
+
* An applet reaches the shell only through the port kehto's prelude keeps to itself, so a
|
|
2852
|
+
* domain kehto does not know is an empty object inside the applet unless the prelude is
|
|
2853
|
+
* given its binding table (kehto/web#413). kernl offers the download domains only when
|
|
2854
|
+
* this is true: a domain an applet can see but not call would be a promise the shell
|
|
2855
|
+
* cannot keep.
|
|
2856
|
+
*
|
|
2857
|
+
* @param render - The prelude renderer; kehto's by default.
|
|
2858
|
+
* @returns True when a binding passed to the prelude reaches its output.
|
|
2859
|
+
* @example
|
|
2860
|
+
* ```ts
|
|
2861
|
+
* supportsDomainBindings(); // false on @kehto/shell 0.35, true once it renders bindings
|
|
2862
|
+
* ```
|
|
2863
|
+
*/
|
|
2864
|
+
declare function supportsDomainBindings(render?: (options: NappletNamespacePreludeOptions) => string): boolean;
|
|
2865
|
+
|
|
2866
|
+
/** Domains kernl serves that kehto's shell does not list, as one applet is to see them. */
|
|
2867
|
+
interface PlannedExtensions {
|
|
2868
|
+
/** The extension domains in force for this applet, already narrowed by its grants. */
|
|
2869
|
+
readonly domains: readonly string[];
|
|
2870
|
+
/** What each one offers inside the applet. */
|
|
2871
|
+
readonly bindings: Readonly<Record<string, DomainBinding>>;
|
|
2872
|
+
}
|
|
2307
2873
|
/** Inputs for {@link planMount}. */
|
|
2308
2874
|
interface PlanMountOptions {
|
|
2309
2875
|
readonly summary: AppletSummary;
|
|
@@ -2313,18 +2879,38 @@ interface PlanMountOptions {
|
|
|
2313
2879
|
readonly adapter: ShellAdapter;
|
|
2314
2880
|
readonly guardProfile: GuardProfile;
|
|
2315
2881
|
readonly windowId: string;
|
|
2882
|
+
/** Domains beyond kehto's own to add to the applet's environment and bind in its namespace. */
|
|
2883
|
+
readonly extensions?: PlannedExtensions;
|
|
2884
|
+
/** The domains the firewall admitted the applet with; the environment is narrowed to them. Everything the grants leave when absent. */
|
|
2885
|
+
readonly domains?: readonly string[];
|
|
2316
2886
|
}
|
|
2887
|
+
/**
|
|
2888
|
+
* The environment an applet is offered before the firewall admits it: kehto's
|
|
2889
|
+
* live domains narrowed by the host's `capabilities.resolveEnvironment`,
|
|
2890
|
+
* which in kernl is the grants layer.
|
|
2891
|
+
*
|
|
2892
|
+
* @param adapter - The shell adapter.
|
|
2893
|
+
* @param summary - The verified applet.
|
|
2894
|
+
* @returns The environment the grants leave the applet.
|
|
2895
|
+
* @example
|
|
2896
|
+
* ```ts
|
|
2897
|
+
* resolveAppletEnvironment(adapter, summary).capabilities.domains; // ['shell', 'identity', 'theme', …]
|
|
2898
|
+
* ```
|
|
2899
|
+
*/
|
|
2900
|
+
declare function resolveAppletEnvironment(adapter: ShellAdapter, summary: Pick<AppletSummary, 'identity'>): ShellEnvironment;
|
|
2317
2901
|
/**
|
|
2318
2902
|
* Build everything `mountApplet` needs, without touching the DOM.
|
|
2319
2903
|
*
|
|
2320
2904
|
* The environment is kehto's `resolveShellEnvironment`, so it is the live
|
|
2321
2905
|
* domains narrowed by the host's `capabilities.resolveEnvironment` (kernl's
|
|
2322
|
-
* grants). The CSP is the guard's zero-network profile, inserted first in
|
|
2906
|
+
* grants), and then by `domains` when the firewall admitted fewer. The CSP is the guard's zero-network profile, inserted first in
|
|
2323
2907
|
* `<head>` by `prepareNappletSrcdoc` with kehto's nested-context lock enabled
|
|
2324
2908
|
* (`experimental.nestedContextLock`): the policy gains kehto's Trusted Types
|
|
2325
2909
|
* directives and the mandatory namespace prelude installs kehto's creation
|
|
2326
2910
|
* lock. kernl's insertion lock follows the prelude. Markup that declares a
|
|
2327
2911
|
* nested frame is refused by kehto's scan before any of that (D-014).
|
|
2912
|
+
* `extensions` adds the domains kernl serves beyond kehto's list, with the
|
|
2913
|
+
* bindings kehto's prelude turns into `window.napplet.<domain>` (D-050).
|
|
2328
2914
|
* `missingRequired` lists what the applet asked for and will not get, so the
|
|
2329
2915
|
* host can warn before mounting.
|
|
2330
2916
|
*
|
|
@@ -2361,12 +2947,12 @@ interface MountDeps {
|
|
|
2361
2947
|
readonly originRegistry: Pick<OriginRegistry, 'register' | 'setEnvironment' | 'unregister'>;
|
|
2362
2948
|
readonly guard: MountGuardHooks;
|
|
2363
2949
|
/** Called after the frame was removed because the bridge revoked the binding. */
|
|
2364
|
-
readonly onRevoked?: (windowId: string, reason: string) => void;
|
|
2950
|
+
readonly onRevoked?: (windowId: string, reason: string, details?: AppletStopDetails) => void;
|
|
2365
2951
|
}
|
|
2366
2952
|
/** An {@link AppletHandle} with the entry point the bridge's revocation hook calls. */
|
|
2367
2953
|
interface MountedApplet extends AppletHandle {
|
|
2368
2954
|
/** Mark the applet revoked and remove its frame. Idempotent with `close`. */
|
|
2369
|
-
revoked(reason: string): void;
|
|
2955
|
+
revoked(reason: string, details?: AppletStopDetails): void;
|
|
2370
2956
|
}
|
|
2371
2957
|
/**
|
|
2372
2958
|
* Put a planned applet into a frame, in the NIP-5D order the shell depends on:
|
|
@@ -2404,8 +2990,11 @@ interface GuardPipelineOptions {
|
|
|
2404
2990
|
readonly now?: () => number;
|
|
2405
2991
|
/** Receives every guard event from every layer. */
|
|
2406
2992
|
readonly onEvent?: (event: GuardEvent) => void;
|
|
2407
|
-
/**
|
|
2408
|
-
|
|
2993
|
+
/**
|
|
2994
|
+
* Called once when a window crosses the quarantine threshold; kernl revokes it here, before the
|
|
2995
|
+
* triggering envelope is dispatched. `reason` is the guard's: `flood:quarantine` or `flood:hidden-resource`.
|
|
2996
|
+
*/
|
|
2997
|
+
readonly onQuarantine?: (windowId: string, napplet: string, reason: string) => void;
|
|
2409
2998
|
/** Visibility for a window the pipeline has not been told about yet. */
|
|
2410
2999
|
readonly getVisibility?: (windowId: string) => WindowVisibility;
|
|
2411
3000
|
/** Called when a window becomes visible; kernl releases the port envelopes kehto held for it here. */
|
|
@@ -2428,9 +3017,11 @@ interface GuardPipeline {
|
|
|
2428
3017
|
* Decide one envelope that arrived over a bound port, for kehto's
|
|
2429
3018
|
* `filterNappletMessage`. `defer` holds every non-control envelope from a
|
|
2430
3019
|
* window that is not visible (reason `hidden:<class>`) until it is visible
|
|
2431
|
-
* again, up to `deferQueue` envelopes
|
|
2432
|
-
*
|
|
2433
|
-
*
|
|
3020
|
+
* again, up to `deferQueue` envelopes, and a shortcut registration from a
|
|
3021
|
+
* window in its first second until that second is over (D-054). `drop` discards an envelope over its
|
|
3022
|
+
* size cap, a forwarded key that is a held key's repeat or comes from a
|
|
3023
|
+
* window that is not focused (D-054), a burst above the per-second rate, a request over the
|
|
3024
|
+
* focus-aware rate limiter's budget, a hidden window's envelope past the defer
|
|
2434
3025
|
* queue, and the envelope that triggers a quarantine. Control envelopes are
|
|
2435
3026
|
* dispatched unless the window is quarantined.
|
|
2436
3027
|
*/
|
|
@@ -2447,7 +3038,7 @@ interface GuardPipeline {
|
|
|
2447
3038
|
}
|
|
2448
3039
|
/**
|
|
2449
3040
|
* Compose the guard: ingress flood control, then the visibility gate, then the
|
|
2450
|
-
* focus-aware
|
|
3041
|
+
* focus-aware rate limiter, then kehto's bridge.
|
|
2451
3042
|
*
|
|
2452
3043
|
* What is enforced where (D-020): kehto binds NAP traffic to a `MessagePort`
|
|
2453
3044
|
* the bridge owns. Window-level messages, of which only `napplet.hello` is
|
|
@@ -2456,9 +3047,9 @@ interface GuardPipeline {
|
|
|
2456
3047
|
* kehto follows: dispatch, hold until `releaseDeferred`, or drop. Hidden
|
|
2457
3048
|
* windows' envelopes are held and `onRelease` is called when the window is
|
|
2458
3049
|
* visible again. Quarantine revokes the window inside the filter, and kehto
|
|
2459
|
-
* discards what it held.
|
|
2460
|
-
*
|
|
2461
|
-
*
|
|
3050
|
+
* discards what it held. kehto's runtime then charges what it
|
|
3051
|
+
* carries out against the same budgets (`createRuntimeRateLimiter`), held
|
|
3052
|
+
* envelopes included, and puts each request to the firewall.
|
|
2462
3053
|
*
|
|
2463
3054
|
* @param options - Configuration, clock, event sink and quarantine callback.
|
|
2464
3055
|
* @returns The pipeline.
|
|
@@ -2471,139 +3062,327 @@ interface GuardPipeline {
|
|
|
2471
3062
|
declare function createGuardPipeline(options: GuardPipelineOptions): GuardPipeline;
|
|
2472
3063
|
|
|
2473
3064
|
/**
|
|
2474
|
-
*
|
|
3065
|
+
* The guard's operation class for a request as kehto's runtime names it.
|
|
3066
|
+
*
|
|
3067
|
+
* The runtime charges an operation by the name its service gave it, which for
|
|
3068
|
+
* the requests an applet sends is the envelope's type (`relay.publish`,
|
|
3069
|
+
* `storage.set`), so the guard's own classification applies. It does not say
|
|
3070
|
+
* what kind of post a publish carries, so deletions share the `relay:publish`
|
|
3071
|
+
* budget here; kernl's own rate limiter, in front, keeps their separate one.
|
|
2475
3072
|
*
|
|
3073
|
+
* @param operation - The operation name from a runtime observation.
|
|
3074
|
+
* @returns The class whose budget the operation spends.
|
|
2476
3075
|
* @example
|
|
2477
3076
|
* ```ts
|
|
2478
|
-
*
|
|
3077
|
+
* runtimeOpClass('relay.publish'); // 'relay:publish'
|
|
3078
|
+
* runtimeOpClass('resource.network'); // 'resource:bytes'
|
|
3079
|
+
* runtimeOpClass('link.open'); // 'generic'
|
|
2479
3080
|
* ```
|
|
2480
3081
|
*/
|
|
2481
|
-
declare
|
|
3082
|
+
declare function runtimeOpClass(operation: string): OpClass;
|
|
2482
3083
|
/**
|
|
2483
|
-
*
|
|
3084
|
+
* The rate limiter kernl hands to kehto's runtime: the guard profile's budget
|
|
3085
|
+
* for each operation class.
|
|
2484
3086
|
*
|
|
2485
|
-
* The runtime
|
|
2486
|
-
*
|
|
2487
|
-
*
|
|
2488
|
-
*
|
|
2489
|
-
*
|
|
2490
|
-
*
|
|
3087
|
+
* The runtime charges what it is about to carry out, after kernl's own guard
|
|
3088
|
+
* let the envelope through: each request a service puts to the firewall, and
|
|
3089
|
+
* the storage, settings and applet-to-applet traffic the runtime serves
|
|
3090
|
+
* itself. That includes the envelopes kernl held for a hidden window and
|
|
3091
|
+
* released later, which meet the budget at the focus the window has then.
|
|
3092
|
+
* The configuration is read on every charge, so a profile change applies at
|
|
3093
|
+
* once and counters carry over. Where kehto only observes, because a protocol
|
|
3094
|
+
* has no way to refuse, a spent budget flags and never blocks. There is no
|
|
3095
|
+
* startup burst here: kernl's ingress guard counts every second of a window's
|
|
3096
|
+
* life, and the runtime's count of a first second starts when the window was
|
|
3097
|
+
* planned, not when it ran.
|
|
2491
3098
|
*
|
|
3099
|
+
* @param config - The guard configuration in force, read on every charge.
|
|
3100
|
+
* @returns The limiter for `permissions.rateLimiter`.
|
|
2492
3101
|
* @example
|
|
2493
3102
|
* ```ts
|
|
2494
|
-
*
|
|
2495
|
-
*
|
|
3103
|
+
* const rateLimiter = createRuntimeRateLimiter(() => pipeline.config);
|
|
3104
|
+
* const permissions: PermissionAdapter = { ...approvals, rateLimiter };
|
|
2496
3105
|
* ```
|
|
2497
3106
|
*/
|
|
2498
|
-
declare
|
|
2499
|
-
/**
|
|
2500
|
-
|
|
2501
|
-
|
|
2502
|
-
|
|
2503
|
-
|
|
2504
|
-
|
|
2505
|
-
|
|
2506
|
-
|
|
2507
|
-
|
|
3107
|
+
declare function createRuntimeRateLimiter(config: () => GuardConfig): TemporalPolicy;
|
|
3108
|
+
/**
|
|
3109
|
+
* Turn a runtime budget event into a guard event. The runtime's event names
|
|
3110
|
+
* the window and the operation and carries nothing the applet sent. Reasons
|
|
3111
|
+
* follow the guard's vocabulary: a spent class budget is `rate:<class>`, and a
|
|
3112
|
+
* question the firewall did not put to the person because the applet asked
|
|
3113
|
+
* too often is `flood:prompts`.
|
|
3114
|
+
*
|
|
3115
|
+
* @param event - What the runtime reported through `permissions.onRateLimit`.
|
|
3116
|
+
* @param napplet - The applet the window runs, as the shell resolved it.
|
|
3117
|
+
* @param at - When it happened.
|
|
3118
|
+
* @returns The guard event.
|
|
3119
|
+
* @example
|
|
3120
|
+
* ```ts
|
|
3121
|
+
* toGuardEvent({ windowId: 'w1', operation: 'storage.set', action: 'block', reason: 'rate-exceeded' }, 'chat', 0).reason;
|
|
3122
|
+
* // 'rate:storage:write'
|
|
3123
|
+
* ```
|
|
3124
|
+
*/
|
|
3125
|
+
declare function toGuardEvent(event: PermissionRateEvent, napplet: string, at: number): GuardEvent;
|
|
3126
|
+
|
|
3127
|
+
/**
|
|
3128
|
+
* Where the person's firewall rules are kept in the host storage.
|
|
3129
|
+
*
|
|
3130
|
+
* @example
|
|
3131
|
+
* ```ts
|
|
3132
|
+
* localStorage.getItem(FIREWALL_RULES_STORAGE_KEY); // kehto's serialised rules, once the person changed one
|
|
3133
|
+
* ```
|
|
3134
|
+
*/
|
|
3135
|
+
declare const FIREWALL_RULES_STORAGE_KEY = "kernl:firewall-rules:v1";
|
|
3136
|
+
/**
|
|
3137
|
+
* The rules a shell starts with: everything the person granted is allowed
|
|
3138
|
+
* without asking, and opening a link outside the shell asks every time.
|
|
3139
|
+
*
|
|
3140
|
+
* The grants layer already decided which domains an applet holds, so asking
|
|
3141
|
+
* again for each of them would bury the one question that matters under a
|
|
3142
|
+
* wall of prompts. A link leaves the shell, which no grant describes, so it is
|
|
3143
|
+
* the one request that always asks (D-056).
|
|
3144
|
+
*
|
|
3145
|
+
* @returns Fresh rules; change them with kehto's `setPermissionRule`.
|
|
3146
|
+
* @example
|
|
3147
|
+
* ```ts
|
|
3148
|
+
* const rules = defaultFirewallRules();
|
|
3149
|
+
* rules.default; // 'allow'
|
|
3150
|
+
* rules.operations['link.open']; // 'ask'
|
|
3151
|
+
* ```
|
|
3152
|
+
*/
|
|
3153
|
+
declare function defaultFirewallRules(): PermissionRules;
|
|
3154
|
+
/** The person's firewall rules, kept across visits. */
|
|
3155
|
+
interface FirewallRules {
|
|
3156
|
+
/** The rules in force. */
|
|
3157
|
+
current(): PermissionRules;
|
|
3158
|
+
readonly rules$: Observable<PermissionRules>;
|
|
3159
|
+
/**
|
|
3160
|
+
* Set one rule, or remove it with `undefined` so the next wider rule applies.
|
|
3161
|
+
* Throws `invalid:rule` for a target kehto refuses.
|
|
3162
|
+
*/
|
|
3163
|
+
set(target: FirewallRuleTarget, action: PermissionRuleAction | undefined): void;
|
|
3164
|
+
/** Go back to {@link defaultFirewallRules}. */
|
|
3165
|
+
restoreDefaults(): void;
|
|
3166
|
+
/** What the rules say about a request no stored answer covers; kehto's `defaultDecision`. */
|
|
3167
|
+
decide(request: Pick<PermissionRequest, 'principal'>, missing: readonly PermissionRequirement[]): PermissionRuleAction;
|
|
3168
|
+
/** Whether the rules allow one requirement for one applet without asking. */
|
|
3169
|
+
allows(principal: PermissionPrincipal, requirement: PermissionRequirement): boolean;
|
|
2508
3170
|
}
|
|
2509
3171
|
/**
|
|
2510
|
-
*
|
|
2511
|
-
*
|
|
3172
|
+
* The firewall's rules over the host storage.
|
|
3173
|
+
*
|
|
3174
|
+
* A request no stored answer covers is decided by the most specific rule kehto
|
|
3175
|
+
* finds: the applet's rule for that request, for its domain, the applet's
|
|
3176
|
+
* default, then the same three for every applet. Any `deny` among a request's
|
|
3177
|
+
* requirements refuses it, any `ask` asks, and it is allowed without asking
|
|
3178
|
+
* only when every requirement is. Rules are keyed by an applet's catalogue id,
|
|
3179
|
+
* so they survive a new version; stored answers stay tied to the exact code.
|
|
2512
3180
|
*
|
|
2513
|
-
* @param
|
|
2514
|
-
* @
|
|
2515
|
-
* @returns Runtime rate rules and the global fallback rate.
|
|
3181
|
+
* @param storage - The host storage; rules live under {@link FIREWALL_RULES_STORAGE_KEY}.
|
|
3182
|
+
* @returns The rules.
|
|
2516
3183
|
* @example
|
|
2517
3184
|
* ```ts
|
|
2518
|
-
*
|
|
3185
|
+
* const rules = createFirewallRules(localStorage);
|
|
3186
|
+
* rules.set({ domain: 'relay' }, 'ask');
|
|
3187
|
+
* rules.set({ applet: summary.manifest.catalogId, operation: 'link.open' }, 'allow');
|
|
2519
3188
|
* ```
|
|
2520
3189
|
*/
|
|
2521
|
-
declare function
|
|
2522
|
-
|
|
2523
|
-
type RuntimeFirewallState = Pick<FirewallStateContainer, 'setRateLimit' | 'setGlobalRate' | 'setUnfocusedMultiplier' | 'setBurstGuard' | 'persist'>;
|
|
3190
|
+
declare function createFirewallRules(storage: StorageLike): FirewallRules;
|
|
3191
|
+
|
|
2524
3192
|
/**
|
|
2525
|
-
*
|
|
3193
|
+
* Turn kehto's approval prompt into what the host shows: who is asking, what
|
|
3194
|
+
* for, and which answers are open.
|
|
2526
3195
|
*
|
|
2527
|
-
* The
|
|
2528
|
-
*
|
|
2529
|
-
*
|
|
2530
|
-
*
|
|
2531
|
-
*
|
|
2532
|
-
*
|
|
3196
|
+
* The summary carries no copy. Domains and requests are named by their
|
|
3197
|
+
* identifiers and the host words them, as it already words grants. A link is
|
|
3198
|
+
* answered for that one opening only, whatever lifetimes kehto offers, because
|
|
3199
|
+
* the shell asks about every link (D-056). Anything else offers each lifetime
|
|
3200
|
+
* kehto allows: once, while the applet stays open, and always when answers
|
|
3201
|
+
* can be stored. An applet starting up is never offered `once`, because kehto
|
|
3202
|
+
* admits a start for the whole run.
|
|
2533
3203
|
*
|
|
2534
|
-
* @param
|
|
2535
|
-
* @param
|
|
2536
|
-
* @
|
|
2537
|
-
* @returns Nothing; the firewall state is mutated and persisted.
|
|
3204
|
+
* @param prompt - What kehto's approval coordinator asks.
|
|
3205
|
+
* @param applet - The applet the request came from, as the shell knows it.
|
|
3206
|
+
* @returns The summary for `KernlHost.presentApproval`.
|
|
2538
3207
|
* @example
|
|
2539
3208
|
* ```ts
|
|
2540
|
-
*
|
|
3209
|
+
* const summary = describeApproval(prompt, { title: 'Notes', catalogId, identity });
|
|
3210
|
+
* summary.kind; // 'link'
|
|
3211
|
+
* summary.choices; // ['allow-once', 'deny']
|
|
2541
3212
|
* ```
|
|
2542
3213
|
*/
|
|
2543
|
-
declare function
|
|
3214
|
+
declare function describeApproval(prompt: Pick<ApprovalPrompt, 'missing' | 'allowLifetimes'>, applet: FirewallApplet): FirewallSummary;
|
|
2544
3215
|
/**
|
|
2545
|
-
*
|
|
2546
|
-
*
|
|
2547
|
-
*
|
|
3216
|
+
* The answer kehto gets for the choice the person made. Dismissing the prompt,
|
|
3217
|
+
* or naming a choice it did not offer, cancels the request without storing
|
|
3218
|
+
* anything, so the applet may ask again.
|
|
2548
3219
|
*
|
|
2549
|
-
* @param
|
|
2550
|
-
* @param
|
|
2551
|
-
* @returns
|
|
3220
|
+
* @param summary - The summary the host was shown.
|
|
3221
|
+
* @param choice - What the person chose, or `undefined` when they dismissed it.
|
|
3222
|
+
* @returns kehto's approval answer.
|
|
2552
3223
|
* @example
|
|
2553
3224
|
* ```ts
|
|
2554
|
-
*
|
|
2555
|
-
*
|
|
3225
|
+
* answerFor(summary, 'allow-once'); // { effect: 'allow', lifetime: 'once' }
|
|
3226
|
+
* answerFor(summary, undefined); // { effect: 'cancel' }
|
|
2556
3227
|
* ```
|
|
2557
3228
|
*/
|
|
2558
|
-
declare function
|
|
3229
|
+
declare function answerFor(summary: Pick<FirewallSummary, 'choices'>, choice: FirewallChoice | undefined): ApprovalAnswer;
|
|
3230
|
+
|
|
2559
3231
|
/**
|
|
2560
|
-
*
|
|
2561
|
-
* carries the applet's message; the guard event never does, so nothing the
|
|
2562
|
-
* applet sent reaches the guard log. Reasons follow the guard's vocabulary:
|
|
2563
|
-
* a rate is `rate:<class>`, the startup burst is `flood:startup`, anything
|
|
2564
|
-
* else is `runtime:<ruleId>`.
|
|
3232
|
+
* Where the answers the person asked the firewall to keep are stored.
|
|
2565
3233
|
*
|
|
2566
|
-
* @param event - What the runtime firewall reported.
|
|
2567
|
-
* @param at - When it happened.
|
|
2568
|
-
* @returns The guard event.
|
|
2569
3234
|
* @example
|
|
2570
3235
|
* ```ts
|
|
2571
|
-
*
|
|
2572
|
-
* // 'rate:storage:write'
|
|
3236
|
+
* localStorage.getItem(FIREWALL_DECISIONS_STORAGE_KEY); // kehto's serialised grants; only `allow-always` answers are in it
|
|
2573
3237
|
* ```
|
|
2574
3238
|
*/
|
|
2575
|
-
declare
|
|
2576
|
-
/**
|
|
2577
|
-
|
|
2578
|
-
|
|
2579
|
-
|
|
2580
|
-
|
|
3239
|
+
declare const FIREWALL_DECISIONS_STORAGE_KEY = "kernl:firewall-decisions:v1";
|
|
3240
|
+
/**
|
|
3241
|
+
* How long a firewall question may wait for the person, queue time included.
|
|
3242
|
+
* kehto's own default is a minute, which takes a question away from someone
|
|
3243
|
+
* who looked elsewhere; kernl only gives up on one nobody is coming back to.
|
|
3244
|
+
*
|
|
3245
|
+
* @example
|
|
3246
|
+
* ```ts
|
|
3247
|
+
* FIREWALL_PROMPT_TIMEOUT_MS; // 600000
|
|
3248
|
+
* ```
|
|
3249
|
+
*/
|
|
3250
|
+
declare const FIREWALL_PROMPT_TIMEOUT_MS: number;
|
|
3251
|
+
/**
|
|
3252
|
+
* The identity kehto's firewall knows an applet by: its catalogue id, which
|
|
3253
|
+
* rules follow across versions, and the hash of the exact code, which stored
|
|
3254
|
+
* answers are tied to. Both come from the verified manifest, never from
|
|
3255
|
+
* anything the applet sent.
|
|
3256
|
+
*
|
|
3257
|
+
* @param summary - A summary this shell verified.
|
|
3258
|
+
* @returns The principal to register with the applet's session.
|
|
3259
|
+
* @example
|
|
3260
|
+
* ```ts
|
|
3261
|
+
* permissionPrincipalFor(summary); // { kind: 'verified', manifestKey: 'nip5d:35129:…:notes', artifactHash: '…' }
|
|
3262
|
+
* ```
|
|
3263
|
+
*/
|
|
3264
|
+
declare function permissionPrincipalFor(summary: Pick<AppletSummary, 'identity' | 'manifest'>): PermissionPrincipal;
|
|
3265
|
+
/** Options for {@link createFirewallPermissions}. */
|
|
3266
|
+
interface FirewallPermissionsOptions {
|
|
3267
|
+
readonly host: Pick<KernlHost, 'storage' | 'presentApproval' | 'notify' | 'now'>;
|
|
3268
|
+
readonly rules: Pick<FirewallRules, 'decide'>;
|
|
3269
|
+
/** The applet a principal belongs to, from what this shell planned; `undefined` for one it does not know. */
|
|
3270
|
+
readonly appletOf: (principal: PermissionPrincipal) => FirewallApplet | undefined;
|
|
3271
|
+
/** Budgets for what the runtime carries out; see `createRuntimeRateLimiter`. */
|
|
3272
|
+
readonly rateLimiter: TemporalPolicy;
|
|
3273
|
+
/** Receives every spent budget, the question budget included. */
|
|
3274
|
+
readonly onRateLimit: (event: PermissionRateEvent) => void;
|
|
2581
3275
|
}
|
|
2582
|
-
/**
|
|
2583
|
-
|
|
2584
|
-
|
|
2585
|
-
|
|
2586
|
-
|
|
2587
|
-
|
|
2588
|
-
|
|
3276
|
+
/**
|
|
3277
|
+
* kehto's approval adapter for kernl: the firewall's host side.
|
|
3278
|
+
*
|
|
3279
|
+
* A request no stored answer covers goes to the rules first. What they allow
|
|
3280
|
+
* goes ahead, what they deny is refused, and what they say to ask about is
|
|
3281
|
+
* put to the person through `host.presentApproval`; a host without one has
|
|
3282
|
+
* such a request refused, never allowed. A question for an applet this shell
|
|
3283
|
+
* did not plan is cancelled. "Always" answers are kept under
|
|
3284
|
+
* {@link FIREWALL_DECISIONS_STORAGE_KEY}; a failed write is told to the person
|
|
3285
|
+
* and grants nothing. An applet that asks too often has its questions dropped
|
|
3286
|
+
* by kehto's suggested budget, twelve a minute.
|
|
3287
|
+
*
|
|
3288
|
+
* @param options - Host, rules, the applet lookup and the runtime's rate limiter.
|
|
3289
|
+
* @returns The adapter for `ShellAdapter.permissions`.
|
|
3290
|
+
* @example
|
|
3291
|
+
* ```ts
|
|
3292
|
+
* const permissions = createFirewallPermissions({ host, rules, appletOf, rateLimiter, onRateLimit });
|
|
3293
|
+
* const adapter: ShellAdapter = { ...rest, permissions };
|
|
3294
|
+
* ```
|
|
3295
|
+
*/
|
|
3296
|
+
declare function createFirewallPermissions(options: FirewallPermissionsOptions): PermissionAdapter;
|
|
3297
|
+
|
|
3298
|
+
/**
|
|
3299
|
+
* How many planned windows may wait to be mounted. A host that plans and never
|
|
3300
|
+
* mounts would otherwise leave a session behind for each; past this, the
|
|
3301
|
+
* oldest plan is dropped and mounting it fails with `denied:admission-expired`.
|
|
3302
|
+
*
|
|
3303
|
+
* @example
|
|
3304
|
+
* ```ts
|
|
3305
|
+
* MAX_UNMOUNTED_PLANS; // 16
|
|
3306
|
+
* ```
|
|
3307
|
+
*/
|
|
3308
|
+
declare const MAX_UNMOUNTED_PLANS = 16;
|
|
3309
|
+
/** What admission needs from kehto's runtime. */
|
|
3310
|
+
type AdmissionRuntime = Pick<Runtime, 'sessionRegistry' | 'permissions' | 'destroyWindow'>;
|
|
3311
|
+
/** The firewall's say over which applets start, and with which domains. */
|
|
3312
|
+
interface AppletAdmissions {
|
|
3313
|
+
/**
|
|
3314
|
+
* Put an applet's start to the firewall, before any of its code runs.
|
|
3315
|
+
* Resolves the domains it starts with; `shell` is always among them when offered.
|
|
3316
|
+
* Throws `denied:firewall` when a domain the applet requires was refused,
|
|
3317
|
+
* and `unavailable:firewall` when the firewall could not decide.
|
|
3318
|
+
*/
|
|
3319
|
+
admit(windowId: string, summary: AppletSummary, environment: ShellEnvironment): Promise<readonly string[]>;
|
|
3320
|
+
/** Whether the window's admission still stands: nothing it was admitted under was taken back. */
|
|
3321
|
+
isCurrent(windowId: string): boolean;
|
|
3322
|
+
/** The window was mounted, so it no longer counts as waiting. */
|
|
3323
|
+
mounted(windowId: string): void;
|
|
3324
|
+
/** Forget a window and end the session admission opened for it. */
|
|
3325
|
+
discard(windowId: string): void;
|
|
3326
|
+
/** Call `listener` whenever an answer is taken back; returns the unsubscribe. */
|
|
3327
|
+
onInvalidated(listener: () => void): () => void;
|
|
3328
|
+
/** Discard every window still waiting to be mounted. */
|
|
3329
|
+
close(): void;
|
|
3330
|
+
}
|
|
3331
|
+
/**
|
|
3332
|
+
* Admit applets through kehto's firewall before they run.
|
|
3333
|
+
*
|
|
3334
|
+
* kehto dispatches nothing for a window whose session holds no admission, so
|
|
3335
|
+
* kernl opens the session itself when it plans the window, under the verified
|
|
3336
|
+
* principal, and asks the firewall for every domain the grants layer left the
|
|
3337
|
+
* applet. Domains the applet requires are decided together and refuse the
|
|
3338
|
+
* start when refused; each other domain is decided on its own and is simply
|
|
3339
|
+
* left out when refused. With kernl's shipped rules none of this asks the
|
|
3340
|
+
* person anything. `shell` is the read-only control plane and is not a
|
|
3341
|
+
* permission, as in kehto's own launcher.
|
|
3342
|
+
*
|
|
3343
|
+
* @param runtime - kehto's runtime, with `permissions` configured.
|
|
3344
|
+
* @param now - Clock for the session's registration time.
|
|
3345
|
+
* @returns The admissions.
|
|
3346
|
+
* @example
|
|
3347
|
+
* ```ts
|
|
3348
|
+
* const admissions = createAppletAdmissions(bridge.runtime, Date.now);
|
|
3349
|
+
* const domains = await admissions.admit('applet-1', summary, environment);
|
|
3350
|
+
* if (admissions.isCurrent('applet-1')) frame.srcdoc = srcdoc;
|
|
3351
|
+
* ```
|
|
3352
|
+
*/
|
|
3353
|
+
declare function createAppletAdmissions(runtime: AdmissionRuntime, now: () => number): AppletAdmissions;
|
|
3354
|
+
|
|
3355
|
+
/** Options for {@link createFirewall}. */
|
|
3356
|
+
interface FirewallOptions {
|
|
3357
|
+
readonly rules: FirewallRules;
|
|
3358
|
+
/** kehto's grant store, from `bridge.runtime.permissions`. */
|
|
3359
|
+
readonly permissions: RuntimePermissions;
|
|
3360
|
+
}
|
|
3361
|
+
/** The firewall surface plus the hook the shell calls when the person answered a question. */
|
|
3362
|
+
interface KernlFirewall extends Firewall {
|
|
3363
|
+
/** Tell `decisions$` the answers may have changed. */
|
|
3364
|
+
touch(): void;
|
|
3365
|
+
close(): void;
|
|
2589
3366
|
}
|
|
2590
3367
|
/**
|
|
2591
|
-
* The
|
|
2592
|
-
*
|
|
2593
|
-
*
|
|
2594
|
-
*
|
|
2595
|
-
*
|
|
3368
|
+
* The firewall as the host sees it: the rules, and the answers in force.
|
|
3369
|
+
*
|
|
3370
|
+
* Changing a rule takes back every answer the rules gave that they no longer
|
|
3371
|
+
* give, as kehto requires of a host, so a tightened rule applies to applets
|
|
3372
|
+
* already running: kehto ends the work those answers covered and kernl stops
|
|
3373
|
+
* the window (see `createAppletLifecycle`). Answers the person gave stay until
|
|
3374
|
+
* they take them back.
|
|
2596
3375
|
*
|
|
2597
|
-
* @param options -
|
|
2598
|
-
* @returns
|
|
3376
|
+
* @param options - The rules and kehto's grant store.
|
|
3377
|
+
* @returns The firewall.
|
|
2599
3378
|
* @example
|
|
2600
3379
|
* ```ts
|
|
2601
|
-
* const
|
|
2602
|
-
*
|
|
2603
|
-
*
|
|
3380
|
+
* const firewall = createFirewall({ rules, permissions: bridge.runtime.permissions });
|
|
3381
|
+
* firewall.setRule({ domain: 'relay' }, 'ask');
|
|
3382
|
+
* firewall.decisions().filter((decision) => !decision.byRule);
|
|
2604
3383
|
* ```
|
|
2605
3384
|
*/
|
|
2606
|
-
declare function
|
|
3385
|
+
declare function createFirewall(options: FirewallOptions): KernlFirewall;
|
|
2607
3386
|
|
|
2608
3387
|
/**
|
|
2609
3388
|
* Which kehto capabilities a NAP domain needs, following `resolveCapabilitiesNap`.
|
|
@@ -2619,7 +3398,8 @@ declare function createRuntimeFirewallHooks(options: RuntimeFirewallHooksOptions
|
|
|
2619
3398
|
declare const DOMAIN_CAPABILITIES: Readonly<Record<string, readonly Capability[]>>;
|
|
2620
3399
|
/**
|
|
2621
3400
|
* Domains every applet gets without asking: the handshake, in-shell messaging,
|
|
2622
|
-
* the theme
|
|
3401
|
+
* the theme, scoped storage and keyboard shortcuts, which act only in the
|
|
3402
|
+
* applet's own focused window (D-054). No network, and not the identity: which
|
|
2623
3403
|
* account is signed in is the user's to reveal, so an applet learns it only
|
|
2624
3404
|
* after the user grants "your account" (SOUL opinion 2).
|
|
2625
3405
|
*
|
|
@@ -3162,10 +3942,13 @@ interface DefaultBridgesOptions extends BridgeRegistryOptions {
|
|
|
3162
3942
|
* hand-off for downloads from peers; the other bridges still hand off (D-017).
|
|
3163
3943
|
*/
|
|
3164
3944
|
readonly torrent?: TorrentBackend;
|
|
3945
|
+
/** The servers to look for a `blossom:` blob on for each requester, after the reference's own hints (D-055). */
|
|
3946
|
+
readonly blossomServers?: BlossomBridgeOptions['serversFor'];
|
|
3165
3947
|
}
|
|
3166
3948
|
/**
|
|
3167
|
-
* The shell's bridge registry: the web bridge, complete,
|
|
3168
|
-
*
|
|
3949
|
+
* The shell's bridge registry: the web bridge, complete, the Blossom bridge, which
|
|
3950
|
+
* fetches through the same web policy and verifies every blob's hash (D-055), plus
|
|
3951
|
+
* the downloads, sharing and mail bridges. With a `handoff` opener those four hand each locator to an app on
|
|
3169
3952
|
* the user's device; without one they report `unavailable` (D-010). A `torrent` backend
|
|
3170
3953
|
* replaces the hand-off for magnet links, so they download inside kernl (D-017).
|
|
3171
3954
|
*
|
|
@@ -3174,6 +3957,7 @@ interface DefaultBridgesOptions extends BridgeRegistryOptions {
|
|
|
3174
3957
|
* @example
|
|
3175
3958
|
* ```ts
|
|
3176
3959
|
* createDefaultBridges().forScheme('magnet')?.availability(); // { available: false, reason: 'no-backend' }
|
|
3960
|
+
* createDefaultBridges({ blossomServers: (requester) => serversOf(requester) }).forScheme('blossom')?.id; // 'blossom'
|
|
3177
3961
|
* const bridges = createDefaultBridges({ handoff: (uri) => host.openLink(uri) });
|
|
3178
3962
|
* bridges.forScheme('magnet')?.availability(); // { available: true, handoff: true }
|
|
3179
3963
|
* const inKernl = createDefaultBridges({ handoff, torrent: createWebTorrentBackend({ client }) });
|
|
@@ -3220,7 +4004,7 @@ type MultiServerUpload = (servers: readonly string[], blob: Blob, options: {
|
|
|
3220
4004
|
interface BlossomUploaderOptions {
|
|
3221
4005
|
/** The servers this upload goes to, in order. */
|
|
3222
4006
|
readonly servers: () => Promise<readonly string[]>;
|
|
3223
|
-
readonly signer: () => Pick<ISigner, 'signEvent'> | undefined;
|
|
4007
|
+
readonly signer: () => Pick<ISigner, 'signEvent' | 'getPublicKey'> | undefined;
|
|
3224
4008
|
/** Asks the person; resolves true only when they allow it. Called once per upload, before anything is signed or sent. */
|
|
3225
4009
|
readonly ask: (windowId: string, details: UploadDetails) => Promise<boolean>;
|
|
3226
4010
|
/** The transfer; hzrd149's `Actions.multiServerUpload` by default. */
|
|
@@ -3450,6 +4234,86 @@ declare function createCvmRelayPool(pool: ApplesaucePool): CvmRelayPool;
|
|
|
3450
4234
|
*/
|
|
3451
4235
|
declare function createRemoteToolsService(options: RemoteToolsOptions): ServiceHandler;
|
|
3452
4236
|
|
|
4237
|
+
/**
|
|
4238
|
+
* How long after a forwarded key the same key counts as its repeat. A held key
|
|
4239
|
+
* first repeats after the system's delay, at most about half a second, and then
|
|
4240
|
+
* many times a second.
|
|
4241
|
+
*
|
|
4242
|
+
* @example
|
|
4243
|
+
* ```ts
|
|
4244
|
+
* KEY_REPEAT_WINDOW_MS; // 600
|
|
4245
|
+
* ```
|
|
4246
|
+
*/
|
|
4247
|
+
declare const KEY_REPEAT_WINDOW_MS = 600;
|
|
4248
|
+
/** Decides which `keys.forward` envelopes never reach the guard or the runtime. */
|
|
4249
|
+
interface ForwardedKeys {
|
|
4250
|
+
/**
|
|
4251
|
+
* Whether an envelope is a forwarded key to discard: one from a window that
|
|
4252
|
+
* is not the focused one, or the repeat of the key that window forwarded last.
|
|
4253
|
+
*/
|
|
4254
|
+
drops(windowId: string, message: unknown, focused: boolean, at: number): boolean;
|
|
4255
|
+
/** Forget a window's last key. */
|
|
4256
|
+
forget(windowId: string): void;
|
|
4257
|
+
}
|
|
4258
|
+
/**
|
|
4259
|
+
* The filter in front of the guard for keys an applet forwards (D-054).
|
|
4260
|
+
*
|
|
4261
|
+
* The frame forwards every key it has no binding for, repeats included, so a
|
|
4262
|
+
* held key arrives faster than any budget; counted like other traffic it would
|
|
4263
|
+
* use up the applet's allowance and then quarantine it for the person's own
|
|
4264
|
+
* typing. A repeat is discarded here, uncounted: the shell's shortcuts act on
|
|
4265
|
+
* the press. So is a key from a window that is not focused, which the person
|
|
4266
|
+
* cannot have typed there.
|
|
4267
|
+
*
|
|
4268
|
+
* @returns The filter.
|
|
4269
|
+
* @example
|
|
4270
|
+
* ```ts
|
|
4271
|
+
* const forwarded = createForwardedKeys();
|
|
4272
|
+
* forwarded.drops('w1', { type: 'keys.forward', key: 'a', code: 'KeyA' }, true, 0); // false: the press
|
|
4273
|
+
* forwarded.drops('w1', { type: 'keys.forward', key: 'a', code: 'KeyA' }, true, 500); // true: its repeat
|
|
4274
|
+
* ```
|
|
4275
|
+
*/
|
|
4276
|
+
declare function createForwardedKeys(): ForwardedKeys;
|
|
4277
|
+
|
|
4278
|
+
/** Options for {@link createKeymapHold}. */
|
|
4279
|
+
interface KeymapHoldOptions {
|
|
4280
|
+
/** How long the runtime's startup burst guard watches a new window, in milliseconds. */
|
|
4281
|
+
readonly startupMs: () => number;
|
|
4282
|
+
/** Called once a window's startup window has passed, to hand on what was held for it. */
|
|
4283
|
+
readonly release: (windowId: string) => void;
|
|
4284
|
+
}
|
|
4285
|
+
/** Holds an applet's shortcut registrations until the runtime will take them. */
|
|
4286
|
+
interface KeymapHold {
|
|
4287
|
+
/**
|
|
4288
|
+
* Note an envelope from a window and say whether to hold it: a shortcut
|
|
4289
|
+
* registration from a window whose startup window has not passed.
|
|
4290
|
+
*/
|
|
4291
|
+
holds(windowId: string, message: unknown, at: number): boolean;
|
|
4292
|
+
/** Whether registrations are being held for a window right now. */
|
|
4293
|
+
holding(windowId: string): boolean;
|
|
4294
|
+
/** Forget a window and stop waiting for it. */
|
|
4295
|
+
forget(windowId: string): void;
|
|
4296
|
+
}
|
|
4297
|
+
/**
|
|
4298
|
+
* The wait in front of the runtime for an applet's keymap (D-054).
|
|
4299
|
+
*
|
|
4300
|
+
* An applet registers its shortcuts as it starts, a dozen or more at once,
|
|
4301
|
+
* which is exactly when the runtime's startup burst guard lets fewest
|
|
4302
|
+
* envelopes through and answers none of the ones it refuses. Registrations
|
|
4303
|
+
* that arrive in a window's startup window are held, in order, and handed on
|
|
4304
|
+
* together when it has passed, where they meet the ordinary rates. Everything
|
|
4305
|
+
* registered later goes straight through.
|
|
4306
|
+
*
|
|
4307
|
+
* @param options - The length of the startup window and what to do when it has passed.
|
|
4308
|
+
* @returns The hold.
|
|
4309
|
+
* @example
|
|
4310
|
+
* ```ts
|
|
4311
|
+
* const hold = createKeymapHold({ startupMs: () => 1000, release: (windowId) => bridge.releaseDeferred(windowId) });
|
|
4312
|
+
* hold.holds('w1', { type: 'keys.registerAction' }, Date.now()); // true: held until the window's first second is over
|
|
4313
|
+
* ```
|
|
4314
|
+
*/
|
|
4315
|
+
declare function createKeymapHold(options: KeymapHoldOptions): KeymapHold;
|
|
4316
|
+
|
|
3453
4317
|
/** What the direct connections service needs from the shell. */
|
|
3454
4318
|
interface DirectConnectionsOptions {
|
|
3455
4319
|
readonly pool: ApplesaucePool;
|
|
@@ -3496,7 +4360,7 @@ declare function directNamespace(summary: Pick<AppletSummary, 'publisher' | 'man
|
|
|
3496
4360
|
* describeDirectConnection(requirements, identity).title; // 'Connect directly to other people'
|
|
3497
4361
|
* ```
|
|
3498
4362
|
*/
|
|
3499
|
-
declare function describeDirectConnection(requirements: readonly PermissionRequirement[], applet: AppletIdentity): ConsentSummary;
|
|
4363
|
+
declare function describeDirectConnection(requirements: readonly PermissionRequirement$1[], applet: AppletIdentity): ConsentSummary;
|
|
3500
4364
|
/**
|
|
3501
4365
|
* The `webrtc` service: applets open direct sessions with other people.
|
|
3502
4366
|
*
|
|
@@ -3652,6 +4516,8 @@ interface KernlServiceDeps {
|
|
|
3652
4516
|
readonly directConnections?: DirectConnectionsDeps | undefined;
|
|
3653
4517
|
/** The person's own choices, which come before the host's (D-043). */
|
|
3654
4518
|
readonly multiplayer?: Pick<MultiplayerSettings, 'state'>;
|
|
4519
|
+
/** Reserved chords, the key listener's target and the focus source for the `keys` domain (D-054). */
|
|
4520
|
+
readonly shortcuts: ShortcutsOptions;
|
|
3655
4521
|
}
|
|
3656
4522
|
/** What the `webrtc` service needs beyond the pool and the window identities. */
|
|
3657
4523
|
interface DirectConnectionsDeps extends Pick<DirectConnectionsOptions, 'createPeer' | 'appletOf' | 'isGranted' | 'ask'> {
|
|
@@ -3662,7 +4528,61 @@ interface KernlServices {
|
|
|
3662
4528
|
readonly registry: ServiceRegistry;
|
|
3663
4529
|
readonly theme: ThemeService;
|
|
3664
4530
|
readonly dm: DmService;
|
|
4531
|
+
/** The `keys` service; `destroy()` gives back its key listener. */
|
|
4532
|
+
readonly keys: ShortcutsService;
|
|
3665
4533
|
}
|
|
4534
|
+
/**
|
|
4535
|
+
* kehto's outbox router fails a publish unless every one of the author's
|
|
4536
|
+
* write relays accepted it. On an open network one server refusing or being
|
|
4537
|
+
* down is ordinary, so kernl reports success when any relay accepted, and
|
|
4538
|
+
* keeps the per-relay results so the caller sees how many did (D-028).
|
|
4539
|
+
* Upstream gap: the router has no acceptance policy option.
|
|
4540
|
+
*
|
|
4541
|
+
* @param router - kehto's outbox router.
|
|
4542
|
+
* @returns The same router with partial acceptance treated as success.
|
|
4543
|
+
* @example
|
|
4544
|
+
* ```ts
|
|
4545
|
+
* createOutboxService({ router: acceptAnyRelay(createRelayPoolOutboxRouter(options)) });
|
|
4546
|
+
* ```
|
|
4547
|
+
*/
|
|
4548
|
+
declare function acceptAnyRelay(router: OutboxRouter): OutboxRouter;
|
|
4549
|
+
/**
|
|
4550
|
+
* The relays the shell itself may reach for an applet, as bare origins: the
|
|
4551
|
+
* form kehto's firewall takes a network destination in.
|
|
4552
|
+
*
|
|
4553
|
+
* kehto's messaging and social services have each request's relays approved
|
|
4554
|
+
* before they run it. In kernl the applet never chooses them: a provider finds
|
|
4555
|
+
* the recipient's inboxes and a post goes to the tier for its kind, so the
|
|
4556
|
+
* plan is every relay in the shell's tiers, which is the widest set either can
|
|
4557
|
+
* reach. A relay whose address is not a bare `ws:` or `wss:` origin is left out.
|
|
4558
|
+
*
|
|
4559
|
+
* @param tiers - The shell's relay tiers.
|
|
4560
|
+
* @returns Distinct relay origins.
|
|
4561
|
+
* @example
|
|
4562
|
+
* ```ts
|
|
4563
|
+
* shellRelayOrigins(tiers); // ['wss://relay.example', …]
|
|
4564
|
+
* ```
|
|
4565
|
+
*/
|
|
4566
|
+
declare function shellRelayOrigins(tiers: Pick<RelayTiers, 'get'>): readonly string[];
|
|
4567
|
+
/**
|
|
4568
|
+
* Have the firewall approve the server a download contacts before it is
|
|
4569
|
+
* contacted. kehto's resource service passes `authorizeNetwork` when the
|
|
4570
|
+
* firewall is on; a web address is put to it by origin, and anything else
|
|
4571
|
+
* (a magnet link, a file-server address) is resolved by its bridge, which
|
|
4572
|
+
* names its own servers. Upstream gap: the bridge registry follows a redirect
|
|
4573
|
+
* itself under its own address policy, so only the first origin is put to the
|
|
4574
|
+
* firewall.
|
|
4575
|
+
*
|
|
4576
|
+
* @param url - The address the applet asked for.
|
|
4577
|
+
* @param init - What kehto's resource service passed.
|
|
4578
|
+
* @param run - Resolves the address under the signal it is given.
|
|
4579
|
+
* @returns What `run` resolved.
|
|
4580
|
+
* @example
|
|
4581
|
+
* ```ts
|
|
4582
|
+
* createResourceService({ fetch: (url, init) => fetchThroughFirewall(url, init, (signal) => resolve(url, { signal })) });
|
|
4583
|
+
* ```
|
|
4584
|
+
*/
|
|
4585
|
+
declare function fetchThroughFirewall<T>(url: string, init: Pick<ResourceFetchInit, 'signal' | 'authorizeNetwork'>, run: (signal: AbortSignal) => Promise<T>): Promise<T>;
|
|
3666
4586
|
/**
|
|
3667
4587
|
* Translate the resource service's fetch init into the bridge resolver's,
|
|
3668
4588
|
* naming the applet that asked so the bridge consent hook can see it.
|
|
@@ -3676,18 +4596,34 @@ interface KernlServices {
|
|
|
3676
4596
|
* ```
|
|
3677
4597
|
*/
|
|
3678
4598
|
declare function resourceInitFor(deps: Pick<KernlServiceDeps, 'resolveIdentity'>, init: ResourceFetchInit): ResourceResolveInit;
|
|
4599
|
+
/**
|
|
4600
|
+
* The NAP-RESOURCE error a bridge failure becomes. The bridges reject with
|
|
4601
|
+
* prefixed reasons; kehto's resource service reports any error that is not a
|
|
4602
|
+
* `ResourceServiceError` as `network-error`, so without this an applet could
|
|
4603
|
+
* not tell a missing blob or an unsupported scheme from a dead network (D-055).
|
|
4604
|
+
*
|
|
4605
|
+
* @param error - What the bridge registry rejected with.
|
|
4606
|
+
* @returns The error to throw to the resource service, carrying the bridge's reason as its message.
|
|
4607
|
+
* @example
|
|
4608
|
+
* ```ts
|
|
4609
|
+
* resourceErrorFor(new Error('unavailable:not-found')).code; // 'not-found'
|
|
4610
|
+
* resourceErrorFor(new Error('unavailable:network Failed to fetch')).code; // 'network-error'
|
|
4611
|
+
* ```
|
|
4612
|
+
*/
|
|
4613
|
+
declare function resourceErrorFor(error: unknown): ResourceServiceError;
|
|
3679
4614
|
/**
|
|
3680
4615
|
* Register kehto's reference services over the shell's applesauce layer.
|
|
3681
4616
|
*
|
|
3682
|
-
* `relay`, `identity`, `theme`, `notify`, `link`, `resource`, `dm`,
|
|
3683
|
-
* and `cvm` are wired; every network path goes through the one pool, every
|
|
4617
|
+
* `relay`, `identity`, `theme`, `keys`, `notify`, `link`, `resource`, `dm`,
|
|
4618
|
+
* `outbox` and `cvm` are wired; every network path goes through the one pool, every
|
|
3684
4619
|
* resource fetch through the bridge registry's SSRF policy, links open only
|
|
3685
4620
|
* over `https:` and `mailto:`, notifications surface through the host, outbox
|
|
3686
4621
|
* publishes pass the consent gate before they are signed, and remote tools are
|
|
3687
|
-
* called under each window's own key.
|
|
4622
|
+
* called under each window's own key. An applet's shortcut runs in the focused
|
|
4623
|
+
* window only.
|
|
3688
4624
|
*
|
|
3689
4625
|
* @param deps - Pool, tiers, store, auth, consent gate, host, registries and identity resolver.
|
|
3690
|
-
* @returns The service registry and the theme and
|
|
4626
|
+
* @returns The service registry and the theme, dm and keys handles.
|
|
3691
4627
|
* @example
|
|
3692
4628
|
* ```ts
|
|
3693
4629
|
* const services = createKernlServices(deps);
|
|
@@ -3712,22 +4648,28 @@ interface ShellAdapterDeps {
|
|
|
3712
4648
|
readonly getFocusContext: (windowId: string) => {
|
|
3713
4649
|
focused: boolean;
|
|
3714
4650
|
};
|
|
3715
|
-
/** The
|
|
3716
|
-
readonly
|
|
4651
|
+
/** The firewall's host side: rules, questions, stored answers and the runtime's rate limiter; see `createFirewallPermissions`. */
|
|
4652
|
+
readonly permissions: PermissionAdapter;
|
|
3717
4653
|
readonly onUnroutedMessage?: (info: UnroutedMessageInfo) => void;
|
|
4654
|
+
/** Hears every envelope on a bound port before the guard decides it; observe-only. */
|
|
4655
|
+
readonly onNappletMessage?: NonNullable<ShellAdapter['onNappletMessage']>;
|
|
4656
|
+
/** Takes a key an applet had no shortcut for, so the shell's own shortcuts work while an applet has focus (D-054). */
|
|
4657
|
+
readonly onShortcut?: (key: ShortcutKey) => void;
|
|
3718
4658
|
}
|
|
3719
4659
|
/**
|
|
3720
4660
|
* Build kehto's `ShellAdapter` from kernl's parts.
|
|
3721
4661
|
*
|
|
3722
4662
|
* Choices kehto left open, decided here: windows are created by the host,
|
|
3723
4663
|
* which opens an intent's target for it, not by applets (`createWindow`
|
|
3724
|
-
* returns null); the `intent` domain is offered, served by kernl's router;
|
|
3725
|
-
*
|
|
4664
|
+
* returns null); the `intent` domain is offered, served by kernl's router; a key an
|
|
4665
|
+
* applet had no shortcut for goes to the host's `onShortcut`; there is no worker relay, the applesauce pool is the only
|
|
3726
4666
|
* event source; every signature made for an applet window passes the consent
|
|
3727
4667
|
* gate; update behaviour is `banner`; event signatures are verified by
|
|
3728
4668
|
* applesauce; every applet's environment is narrowed by the grants layer; the
|
|
3729
|
-
* ACL is restrictive, so an applet holds only what the grants layer wrote
|
|
3730
|
-
*
|
|
4669
|
+
* ACL is restrictive, so an applet holds only what the grants layer wrote, and
|
|
4670
|
+
* under `permissions` that is a ceiling no firewall answer can exceed; every
|
|
4671
|
+
* request is decided by the firewall; and every port envelope passes kernl's
|
|
4672
|
+
* guard before the runtime sees it.
|
|
3731
4673
|
*
|
|
3732
4674
|
* @param deps - Pool, tiers, accounts, services and the shell's hooks.
|
|
3733
4675
|
* @returns The adapter for `createShellBridge`.
|
|
@@ -3745,8 +4687,10 @@ interface LifecycleContext {
|
|
|
3745
4687
|
readonly adapter: ShellAdapter;
|
|
3746
4688
|
readonly bridge: ShellBridge;
|
|
3747
4689
|
readonly pipeline: GuardPipeline;
|
|
3748
|
-
/** The
|
|
3749
|
-
readonly
|
|
4690
|
+
/** The firewall's say over which applets start; planning asks it and mounting checks the answer still stands. */
|
|
4691
|
+
readonly admissions: AppletAdmissions;
|
|
4692
|
+
/** Tells the firewall which applet a window id's questions are about. */
|
|
4693
|
+
readonly remember: (summary: AppletSummary) => void;
|
|
3750
4694
|
readonly grants: KernlGrants;
|
|
3751
4695
|
/** Every planned applet is installed, so others can hand it work. */
|
|
3752
4696
|
readonly installed: InstalledApplets;
|
|
@@ -3758,6 +4702,8 @@ interface LifecycleContext {
|
|
|
3758
4702
|
readonly fetchBlob: (sha256: string, servers: readonly string[]) => Promise<Uint8Array>;
|
|
3759
4703
|
/** Applets the host ships with itself. */
|
|
3760
4704
|
readonly builtins: readonly BuiltinApplet[];
|
|
4705
|
+
/** Domains kernl serves beyond kehto's list, and their bindings; `domains` here is everything offered, before grants. */
|
|
4706
|
+
readonly extensions?: PlannedExtensions;
|
|
3761
4707
|
}
|
|
3762
4708
|
/**
|
|
3763
4709
|
* Why a grant change stops a running window, or nothing when it does not.
|
|
@@ -3799,7 +4745,7 @@ type AppletLifecycle = Pick<Kernl, 'resolve' | 'install' | 'plan' | 'mount' | 'a
|
|
|
3799
4745
|
declare function resolveWindow(handles: ReadonlyMap<string, MountedApplet>, event: MessageEvent): WindowResolution | null;
|
|
3800
4746
|
/**
|
|
3801
4747
|
* The applet lifecycle: `resolve` fetches and verifies (or loads an applet the host ships), `plan` narrows the
|
|
3802
|
-
* environment under the user's grants and installs the applet, `mount` performs the NIP-5D mount order
|
|
4748
|
+
* environment under the user's grants, puts the start to the firewall and installs the applet, `mount` performs the NIP-5D mount order
|
|
3803
4749
|
* and `handleWindowMessage` runs the guard in front of the bridge.
|
|
3804
4750
|
*
|
|
3805
4751
|
* @param context - The composed shell's parts.
|
|
@@ -3864,6 +4810,23 @@ declare function createKernl(options: KernlOptions): Kernl;
|
|
|
3864
4810
|
* ```
|
|
3865
4811
|
*/
|
|
3866
4812
|
declare function locateRecipients(adapter: DmAdapter, people: Pick<People, 'locate'>): DmAdapter;
|
|
4813
|
+
/**
|
|
4814
|
+
* Read the recipients of a send before kehto's service sees them.
|
|
4815
|
+
*
|
|
4816
|
+
* Under the firewall kehto has every recipient approved before a message is
|
|
4817
|
+
* sent, and takes them as hex keys only, so an `npub` or `nprofile` would be
|
|
4818
|
+
* refused before {@link locateRecipients} could read it. This reads them
|
|
4819
|
+
* first; every other request passes straight through.
|
|
4820
|
+
*
|
|
4821
|
+
* @param service - kehto's `dm` service.
|
|
4822
|
+
* @param people - The shell's finder.
|
|
4823
|
+
* @returns The service, with a send's recipients read on the way in.
|
|
4824
|
+
* @example
|
|
4825
|
+
* ```ts
|
|
4826
|
+
* registry.dm = locateSendRecipients(createDmService({ adapter }), kernl.people);
|
|
4827
|
+
* ```
|
|
4828
|
+
*/
|
|
4829
|
+
declare function locateSendRecipients(service: DmService, people: Pick<People, 'locate'>): DmService;
|
|
3867
4830
|
|
|
3868
4831
|
/** What the store filters by. Every part is optional; an empty query lists everything. */
|
|
3869
4832
|
interface CatalogQuery {
|
|
@@ -4052,6 +5015,278 @@ interface KernlIntents {
|
|
|
4052
5015
|
*/
|
|
4053
5016
|
declare function createKernlIntents(deps: KernlIntentDeps): KernlIntents;
|
|
4054
5017
|
|
|
5018
|
+
/** One line of what the person is shown before a download service acts for an applet. */
|
|
5019
|
+
interface DownloadQuestionLine {
|
|
5020
|
+
readonly label: string;
|
|
5021
|
+
readonly value: string;
|
|
5022
|
+
}
|
|
5023
|
+
/**
|
|
5024
|
+
* What a download service puts to the person before it acts for an applet. Words only:
|
|
5025
|
+
* no address, path, credential or raw backend id belongs in a line.
|
|
5026
|
+
*/
|
|
5027
|
+
interface DownloadQuestion {
|
|
5028
|
+
/** Which decision this is, so the host can word and rank it. */
|
|
5029
|
+
readonly kind: 'add' | 'session' | 'delete';
|
|
5030
|
+
readonly title: string;
|
|
5031
|
+
readonly lines: readonly DownloadQuestionLine[];
|
|
5032
|
+
}
|
|
5033
|
+
/** What every download service needs from the shell. */
|
|
5034
|
+
interface DownloadServiceDeps {
|
|
5035
|
+
/** The verified applet a window runs, or undefined when the window is not a live applet. */
|
|
5036
|
+
readonly appletOf: (windowId: string) => AppletIdentity | undefined;
|
|
5037
|
+
/**
|
|
5038
|
+
* The key what a window's applet starts is kept under: its catalogue id, the same across
|
|
5039
|
+
* versions and never shared by another publisher's applet with the same name. Undefined when
|
|
5040
|
+
* the window is not a live applet.
|
|
5041
|
+
*/
|
|
5042
|
+
readonly ownerOf: (windowId: string) => string | undefined;
|
|
5043
|
+
/** Put a question to the person in the name of a window's applet; resolves true only on yes. */
|
|
5044
|
+
readonly ask: (windowId: string, question: DownloadQuestion) => Promise<boolean>;
|
|
5045
|
+
/** Where records that must outlive a window are kept; keys are written under the `kernl` namespace. */
|
|
5046
|
+
readonly storage: StorageLike;
|
|
5047
|
+
/** Milliseconds since the epoch; `Date.now` by default. */
|
|
5048
|
+
readonly now?: () => number;
|
|
5049
|
+
}
|
|
5050
|
+
/**
|
|
5051
|
+
* A download service: the handler kehto dispatches to, plus `dispose`, which stops every
|
|
5052
|
+
* timer and forgets every window when the shell is torn down.
|
|
5053
|
+
*/
|
|
5054
|
+
interface DownloadService {
|
|
5055
|
+
readonly handler: ServiceHandler;
|
|
5056
|
+
dispose(): void;
|
|
5057
|
+
}
|
|
5058
|
+
|
|
5059
|
+
/** What the torrent service needs from the shell. */
|
|
5060
|
+
interface TorrentServiceOptions extends DownloadServiceDeps {
|
|
5061
|
+
/** The person's torrent connections, read on every request: new torrents go to one, and each job stays on its own. */
|
|
5062
|
+
readonly connections: ConnectionRouting<TorrentClient>;
|
|
5063
|
+
/** How often jobs with a live window are refreshed and pushed; 2000 ms by default. */
|
|
5064
|
+
readonly pollMs?: number;
|
|
5065
|
+
}
|
|
5066
|
+
/**
|
|
5067
|
+
* The `torrent` service: applets download through the torrent program the person
|
|
5068
|
+
* already runs. kernl reaches that program over its own API and cannot read its files,
|
|
5069
|
+
* so everything that would hand an applet file contents answers `unsupported`, and the
|
|
5070
|
+
* program, not kernl, decides where files go.
|
|
5071
|
+
*
|
|
5072
|
+
* A job is one applet's hold on one torrent. The person is asked before every add and
|
|
5073
|
+
* before any deletion. A session job is paused in the program when its window ends; a
|
|
5074
|
+
* persistent job is kept in storage and found again by a later window of the same
|
|
5075
|
+
* applet. kernl never removes a torrent, or its data, that it was not asked to. Every
|
|
5076
|
+
* call to the program runs one after another, so a removal always wins over the
|
|
5077
|
+
* changes queued behind it, and one timer tells live windows what changed.
|
|
5078
|
+
*
|
|
5079
|
+
* The person may set up several torrent programs (D-053). A new torrent goes to the one a
|
|
5080
|
+
* job already holds it on, else to the person's default, and the question names it; every
|
|
5081
|
+
* later call for the job goes to that connection alone, and a job whose connection was
|
|
5082
|
+
* removed or is locked answers `source-unavailable` and can still be removed.
|
|
5083
|
+
*
|
|
5084
|
+
* @param options - The shell's hooks, the person's torrent connections and the refresh interval.
|
|
5085
|
+
* @returns The handler to register as `torrent`, and `dispose`.
|
|
5086
|
+
* @example
|
|
5087
|
+
* ```ts
|
|
5088
|
+
* const torrents = createTorrentService({ appletOf, ownerOf, ask, storage: localStorage, connections: programs.routing('torrent') });
|
|
5089
|
+
* registry.torrent = torrents.handler;
|
|
5090
|
+
* ```
|
|
5091
|
+
*/
|
|
5092
|
+
declare function createTorrentService(options: TorrentServiceOptions): DownloadService;
|
|
5093
|
+
|
|
5094
|
+
/** One downloader the person set up. */
|
|
5095
|
+
interface NzbDownloader {
|
|
5096
|
+
/**
|
|
5097
|
+
* What handles are issued against; never sent to an applet. The shell passes the connection's
|
|
5098
|
+
* routing key, which changes with its address, so a handle issued for one server's job never
|
|
5099
|
+
* reaches another server's job with the same id.
|
|
5100
|
+
*/
|
|
5101
|
+
readonly key: string;
|
|
5102
|
+
/** What the person calls it. */
|
|
5103
|
+
readonly label: string;
|
|
5104
|
+
readonly client: NzbClient;
|
|
5105
|
+
}
|
|
5106
|
+
/** What the NZB service needs from the shell. */
|
|
5107
|
+
interface NzbServiceOptions extends DownloadServiceDeps {
|
|
5108
|
+
/** The downloaders the person set up, read on every request. */
|
|
5109
|
+
readonly downloaders: () => readonly NzbDownloader[];
|
|
5110
|
+
/** Fetches an NZB for a `url` source under the shell's own fetch policy; without it only `bytes` is offered. */
|
|
5111
|
+
readonly fetchDocument?: (url: string, signal: AbortSignal) => Promise<Uint8Array>;
|
|
5112
|
+
}
|
|
5113
|
+
|
|
5114
|
+
/** What the shell reads from an NZB document before handing it on. */
|
|
5115
|
+
interface NzbDocument {
|
|
5116
|
+
/** How many files the document lists. */
|
|
5117
|
+
readonly files: number;
|
|
5118
|
+
/** The document's own title, tidied for display, or a plain stand-in. */
|
|
5119
|
+
readonly name: string;
|
|
5120
|
+
}
|
|
5121
|
+
/**
|
|
5122
|
+
* Validates one NZB document without handing it to an XML library: the shell runs
|
|
5123
|
+
* where there is no `DOMParser`, and a strict scanner cannot be talked into loading
|
|
5124
|
+
* a DTD or expanding an entity (NAP-NZB, Submission). Accepted is well-formed XML
|
|
5125
|
+
* within the shell's bounds whose root is `nzb` in the NZB namespace and which lists
|
|
5126
|
+
* at least one file with a segment. An external doctype is read past and never
|
|
5127
|
+
* fetched; an internal subset, any declaration, any entity beyond XML's five and any
|
|
5128
|
+
* processing instruction are refused.
|
|
5129
|
+
*
|
|
5130
|
+
* @param bytes - The document as it will be handed to the downloader.
|
|
5131
|
+
* @returns The number of files listed and a display name from the document's own title.
|
|
5132
|
+
* @throws `invalid:nzb` followed by plain words for what was wrong.
|
|
5133
|
+
* @example
|
|
5134
|
+
* ```ts
|
|
5135
|
+
* readNzbDocument(bytes); // { files: 2, name: 'Holiday film (2019)' }
|
|
5136
|
+
* ```
|
|
5137
|
+
*/
|
|
5138
|
+
declare function readNzbDocument(bytes: Uint8Array): NzbDocument;
|
|
5139
|
+
|
|
5140
|
+
/**
|
|
5141
|
+
* The `nzb` service (NAP-NZB): applets hand NZB documents to the downloaders the
|
|
5142
|
+
* person already runs, and watch and steer the jobs they started.
|
|
5143
|
+
*
|
|
5144
|
+
* kernl is a remote control here. It never reads what a downloader saved, so `files`
|
|
5145
|
+
* and `read` are `unsupported` and every job says `canReadFiles: false`. The person is
|
|
5146
|
+
* asked before every add and before every delete. An applet sees only its own jobs,
|
|
5147
|
+
* under handles that mean nothing to anyone else. `add` and `control` are carried out
|
|
5148
|
+
* once per operation key, on a record that survives a reload. The runtime checks the
|
|
5149
|
+
* domain grant before a message gets here, so the handler does not check it again; it
|
|
5150
|
+
* declares every inbound type because `nzb` is not one of kehto's built-in domains.
|
|
5151
|
+
*
|
|
5152
|
+
* @param options - The downloaders, the optional fetcher, and the shell's applet, consent, storage and clock hooks.
|
|
5153
|
+
* @returns The handler to register as `nzb`, and `dispose`.
|
|
5154
|
+
* @example
|
|
5155
|
+
* ```ts
|
|
5156
|
+
* const nzb = createNzbService({ downloaders: () => [{ key: 'nzbget', label: 'Home', client }], appletOf, ownerOf, ask, storage: localStorage });
|
|
5157
|
+
* registry.nzb = nzb.handler;
|
|
5158
|
+
* ```
|
|
5159
|
+
*/
|
|
5160
|
+
declare function createNzbService(options: NzbServiceOptions): DownloadService;
|
|
5161
|
+
|
|
5162
|
+
/** The runtime limits `soulseek.info` reports; fixed for the service's life. */
|
|
5163
|
+
interface SoulseekLimits {
|
|
5164
|
+
readonly maxQueries: number;
|
|
5165
|
+
readonly maxTransfers: number;
|
|
5166
|
+
readonly maxResults: number;
|
|
5167
|
+
readonly maxPageSize: number;
|
|
5168
|
+
readonly maxReadBytes: number;
|
|
5169
|
+
readonly maxTextBytes: number;
|
|
5170
|
+
readonly queryTimeoutMs: number;
|
|
5171
|
+
readonly pollIntervalMs: number;
|
|
5172
|
+
}
|
|
5173
|
+
|
|
5174
|
+
/** What the `soulseek` service needs from the shell. */
|
|
5175
|
+
interface SoulseekServiceOptions extends DownloadServiceDeps {
|
|
5176
|
+
/** The person's Soulseek connections, read on every request: new searches go to the default, and what they find stays on it. */
|
|
5177
|
+
readonly connections: ConnectionRouting<SoulseekClient>;
|
|
5178
|
+
/** Runtime limits; each has the default in {@link DEFAULT_SOULSEEK_LIMITS}. */
|
|
5179
|
+
readonly limits?: Partial<SoulseekLimits>;
|
|
5180
|
+
}
|
|
5181
|
+
/**
|
|
5182
|
+
* The limits a window works within unless the host says otherwise.
|
|
5183
|
+
*
|
|
5184
|
+
* @example
|
|
5185
|
+
* ```ts
|
|
5186
|
+
* createSoulseekService({ ...deps, connections: programs.routing('soulseek'), limits: { ...DEFAULT_SOULSEEK_LIMITS, maxTransfers: 4 } });
|
|
5187
|
+
* ```
|
|
5188
|
+
*/
|
|
5189
|
+
declare const DEFAULT_SOULSEEK_LIMITS: SoulseekLimits;
|
|
5190
|
+
/**
|
|
5191
|
+
* What the person is asked before a window first reaches the network through their
|
|
5192
|
+
* daemon: who learns what, that nothing is private on the way, and when it ends.
|
|
5193
|
+
*
|
|
5194
|
+
* @example
|
|
5195
|
+
* ```ts
|
|
5196
|
+
* SOULSEEK_SESSION_QUESTION.title; // 'Search, browse and fetch through your sharing program'
|
|
5197
|
+
* ```
|
|
5198
|
+
*/
|
|
5199
|
+
declare const SOULSEEK_SESSION_QUESTION: DownloadQuestion;
|
|
5200
|
+
/**
|
|
5201
|
+
* The `soulseek` service: an applet searches, browses and downloads through the
|
|
5202
|
+
* Soulseek daemon the person already runs (NAP-SOULSEEK).
|
|
5203
|
+
*
|
|
5204
|
+
* Every handle belongs to the window it was issued to; another window, even of the
|
|
5205
|
+
* same applet, cannot tell one from a handle that never existed. The person is asked
|
|
5206
|
+
* once per window before it first reaches the network. Nothing outlives the window:
|
|
5207
|
+
* closing it, or taking its grant back, stops its searches and unfinished downloads
|
|
5208
|
+
* in the daemon and leaves finished files there, untouched.
|
|
5209
|
+
*
|
|
5210
|
+
* The daemon is a separate program whose files kernl cannot reach, so `read` is
|
|
5211
|
+
* `denied`, `save` is `unsupported` and `info` reports `canSave: false`. The runtime
|
|
5212
|
+
* checks the domain grant before a message gets here; this handler does not repeat it.
|
|
5213
|
+
*
|
|
5214
|
+
* @param options - The daemon, the person's consent, the clock and the limits.
|
|
5215
|
+
* @returns The handler to register as `soulseek`, and `dispose`.
|
|
5216
|
+
* @example
|
|
5217
|
+
* ```ts
|
|
5218
|
+
* const soulseek = createSoulseekService({ connections: programs.routing('soulseek'), appletOf, ownerOf, ask, storage });
|
|
5219
|
+
* registry.soulseek = soulseek.handler;
|
|
5220
|
+
* ```
|
|
5221
|
+
*/
|
|
5222
|
+
declare function createSoulseekService(options: SoulseekServiceOptions): DownloadService;
|
|
5223
|
+
|
|
5224
|
+
/**
|
|
5225
|
+
* The domains kernl serves by driving the person's own download programs, in the order they are offered.
|
|
5226
|
+
*
|
|
5227
|
+
* @example
|
|
5228
|
+
* ```ts
|
|
5229
|
+
* DOWNLOAD_DOMAINS.includes('nzb'); // true
|
|
5230
|
+
* ```
|
|
5231
|
+
*/
|
|
5232
|
+
declare const DOWNLOAD_DOMAINS: readonly string[];
|
|
5233
|
+
/** What the download services need from the composed shell. */
|
|
5234
|
+
interface KernlDownloadsDeps {
|
|
5235
|
+
readonly host: Pick<KernlHost, 'storage' | 'presentConsent' | 'now'>;
|
|
5236
|
+
readonly options: DownloadsOptions | undefined;
|
|
5237
|
+
/** Where the programs' passwords and keys are kept. */
|
|
5238
|
+
readonly secrets: SecretsProvider;
|
|
5239
|
+
/** The verified applet a window runs, or undefined. */
|
|
5240
|
+
readonly identityOf: (windowId: string) => AppletIdentity | undefined;
|
|
5241
|
+
/** The catalogue id of the applet a window runs, which what it starts is kept under. */
|
|
5242
|
+
readonly ownerOf: (windowId: string) => string | undefined;
|
|
5243
|
+
/** Fetches an NZB an applet named by address, under the shell's own fetch policy. */
|
|
5244
|
+
readonly fetchDocument: (url: string, signal: AbortSignal) => Promise<Uint8Array>;
|
|
5245
|
+
}
|
|
5246
|
+
/** The download programs' settings, the services over them when they can be offered, and their teardown. */
|
|
5247
|
+
interface KernlDownloads {
|
|
5248
|
+
readonly programs: DownloadClients;
|
|
5249
|
+
/** The handlers to register, keyed by domain; empty when the domains cannot be offered. */
|
|
5250
|
+
readonly services: ServiceRegistry;
|
|
5251
|
+
/** What planning adds to an applet's environment; undefined when the domains cannot be offered. */
|
|
5252
|
+
readonly extensions: PlannedExtensions | undefined;
|
|
5253
|
+
dispose(): void;
|
|
5254
|
+
}
|
|
5255
|
+
/**
|
|
5256
|
+
* A download service's question as the host's consent prompt takes it. Starting something
|
|
5257
|
+
* that shows peers the address of the machine doing the transfer is `direct`; erasing files
|
|
5258
|
+
* is `destructive`; an archive download, which only the person's own servers see, is `routine`.
|
|
5259
|
+
*
|
|
5260
|
+
* @param question - What the service asks.
|
|
5261
|
+
* @param applet - The applet it asks for.
|
|
5262
|
+
* @param exposesAddress - Whether peers learn a network address from what is being started.
|
|
5263
|
+
* @returns The summary the host renders.
|
|
5264
|
+
* @example
|
|
5265
|
+
* ```ts
|
|
5266
|
+
* describeDownloadQuestion({ kind: 'delete', title: 'Delete the files', lines: [] }, identity, true).severity; // 'destructive'
|
|
5267
|
+
* ```
|
|
5268
|
+
*/
|
|
5269
|
+
declare function describeDownloadQuestion(question: DownloadQuestion, applet: AppletIdentity, exposesAddress: boolean): ConsentSummary;
|
|
5270
|
+
/**
|
|
5271
|
+
* The three download domains over the programs the person set up (D-050).
|
|
5272
|
+
*
|
|
5273
|
+
* The settings are always there, so the person can set a program up before any applet asks
|
|
5274
|
+
* for it. The services are created, and the domains offered, only when kehto's prelude can
|
|
5275
|
+
* bind a domain it does not build in (`supportsDomainBindings`), or the host says its own
|
|
5276
|
+
* does (`downloads.offer`). Every question a service has goes to the person through the
|
|
5277
|
+
* host's consent prompt, in the name of the applet that caused it; a window that is no
|
|
5278
|
+
* longer a live applet is answered no without asking.
|
|
5279
|
+
*
|
|
5280
|
+
* @param deps - Host, options, the secrets provider, the window-to-applet lookup and the NZB fetcher.
|
|
5281
|
+
* @returns Settings, handlers, the planning extension and teardown.
|
|
5282
|
+
* @example
|
|
5283
|
+
* ```ts
|
|
5284
|
+
* const downloads = createKernlDownloads({ host, options: undefined, secrets: createStorageSecrets(host.storage), identityOf, ownerOf, fetchDocument });
|
|
5285
|
+
* Object.assign(services.registry, downloads.services);
|
|
5286
|
+
* ```
|
|
5287
|
+
*/
|
|
5288
|
+
declare function createKernlDownloads(deps: KernlDownloadsDeps): KernlDownloads;
|
|
5289
|
+
|
|
4055
5290
|
/**
|
|
4056
5291
|
* The npm package name, shared by both registry builds.
|
|
4057
5292
|
*
|
|
@@ -4072,4 +5307,4 @@ declare const PACKAGE_NAME = "@kernlize/core";
|
|
|
4072
5307
|
*/
|
|
4073
5308
|
declare const KERNL_FRAME_POLICY_META: string;
|
|
4074
5309
|
|
|
4075
|
-
export { type AccountFileServers, type AccountFileServersOptions, type AccountMailboxes, type AccountMailboxesOptions, type ApplesaucePool, type AppletCatalog, type AppletConfigOptions, type AppletHandle, type AppletIdentity, type AppletLifecycle, type AppletPointer, type AppletStatus, type AppletSummary, BASELINE_DOMAINS, BLOB_TIMEOUT_MS, BUILTIN_PUBLISHER, type BlossomUploaderOptions, type BuiltinApplet, CATALOG_EMIT_MS, CATALOG_LIMIT, CATALOG_SETTLE_MS, CATALOG_TIMEOUT_MS, CONTROLLER_DENY_POLICY, CURRENT_VERSION_TIMEOUT_MS, type CatalogEntry, type CatalogQuery, type CommonActionsOptions, ConnectedEventCache, type ConsentLine, type ConsentPrompt, type ConsentSummary, DEFAULT_FILE_SERVERS, DEFAULT_MONITOR_RELAYS, DEFAULT_RELAY_TIERS, DEFAULT_SUGGESTIONS, DELIVERY_RETRY, DIRECT_MAX_PAYLOAD_BYTES, DIRECT_SIGNALING_PROFILE, DIRECT_SIGNAL_KIND, DOMAIN_CAPABILITIES, type DefaultBridgesOptions, type DefaultMessagingOptions, type DirectConnectionsDeps, type DirectConnectionsOptions, type DirectConnectionsSettings, type DirectIceServer, type DirectSignalingOptions, type DirectoryPool, type EoseSubscription, EventCacheOpener, type FileServerState, type FrameLike, type GrantRecord, type Grants, type GrantsOptions, type GroupMessagingOptions, type GuardFacade, type GuardPipeline, type GuardPipelineOptions, HANDLER_PREFERENCES_KIND, type HandlerChoice, type HandlerDefaults, type HandlerDefaultsOptions, type HandlerOption, type HandlerPreferences, type HandlerPrompt, type IdentityProfile, type IdentityProviderOptions, type IdentityProviders, type InboxRelays, type InstallableApplet, type InstalledApplet, type InstalledApplets, type InstalledContract, type IntentDeliveryOptions, type IntentRouter, type IntentRouterOptions, type Intents, KERNL_FRAME_POLICY_META, type Kernl, KernlAccountManager, type KernlGrants, type KernlHost, type KernlIntentDeps, type KernlIntents, type KernlMultiplayer, type KernlNetwork, type KernlNetworkParts, type KernlOptions, type KernlServiceDeps, type KernlServices, LINK_PROTOCOLS, type LifecycleContext, type LoadCatalogOptions, type LookupBefore, type LookupReplaceableOptions, MANIFEST_TIMING, MESSAGES_DOMAIN, MESSAGE_COMPANION_DOMAINS, MESSAGING_UNAVAILABLE_REASONS, type MailboxPool, type MailboxSigner, type MailboxState, type Mailboxes, type ManifestTiming, type MessagingBackendFactories, type MessagingEncryption, type MountDeps, type MountGuardHooks, type MountPlan, type MountedApplet, type MultiServerUpload, type MultiplayerSettings, type MultiplayerState, type NamespacedStore, type OutboxRelayPoolLike, PACKAGE_NAME, PERSON_HINT_TIMEOUT_MS, PLAINTEXT_KEY_ACCOUNT_TYPES, type People, type PeopleOptions, type PersonPointer, type PipelineDisposition, type PlanMountOptions, type PreferenceSigner, type ProfileCard, type ProfileLoader, type ProfilePointer, type Profiles, type ProfilesOptions, type PublishAnswer, type PublishOutcome, type PublishedPointer,
|
|
5310
|
+
export { type AccountFileServers, type AccountFileServersOptions, type AccountMailboxes, type AccountMailboxesOptions, type AdmissionRuntime, type ApplesaucePool, type AppletAdmissions, type AppletCatalog, type AppletConfigOptions, type AppletHandle, type AppletIdentity, type AppletLifecycle, type AppletMessage, type AppletMessageDirection, type AppletPointer, type AppletStatus, type AppletStopDetails, type AppletStopLimit, type AppletSummary, type AppletTraffic, BASELINE_DOMAINS, BLOB_TIMEOUT_MS, BUILTIN_PUBLISHER, type BlossomUploaderOptions, type BoundPreludeOptions, type BuiltinApplet, CATALOG_EMIT_MS, CATALOG_LIMIT, CATALOG_SETTLE_MS, CATALOG_TIMEOUT_MS, CONTROLLER_DENY_POLICY, CURRENT_VERSION_TIMEOUT_MS, type CatalogEntry, type CatalogQuery, type CheckedConnection, type ClientFor, type CommonActionsOptions, ConnectedEventCache, type ConnectionChange, type ConnectionRouting, type ConsentLine, type ConsentPrompt, type ConsentSummary, DEFAULT_FILE_SERVERS, DEFAULT_MONITOR_RELAYS, DEFAULT_RELAY_TIERS, DEFAULT_SOULSEEK_LIMITS, DEFAULT_SUGGESTIONS, DELIVERY_RETRY, DIRECT_MAX_PAYLOAD_BYTES, DIRECT_SIGNALING_PROFILE, DIRECT_SIGNAL_KIND, DOMAIN_CAPABILITIES, DOWNLOAD_BINDINGS, DOWNLOAD_DOMAINS, DOWNLOAD_PROGRAMS, type DefaultBridgesOptions, type DefaultMessagingOptions, type DirectConnectionsDeps, type DirectConnectionsOptions, type DirectConnectionsSettings, type DirectIceServer, type DirectSignalingOptions, type DirectoryPool, type DomainBinding, type DomainBindingMethod, type DownloadClients, type DownloadClientsOptions, type DownloadClientsState, type DownloadConnection, type DownloadDomain, type DownloadProgram, type DownloadProgramInfo, type DownloadQuestion, type DownloadQuestionLine, type DownloadService, type DownloadServiceDeps, type DownloadSignIn, type DownloadsOptions, type EoseSubscription, EventCacheOpener, FIREWALL_DECISIONS_STORAGE_KEY, FIREWALL_PROMPT_TIMEOUT_MS, FIREWALL_RULES_STORAGE_KEY, type FileServerState, type Firewall, type FirewallApplet, type FirewallChoice, type FirewallDecision, type FirewallOptions, type FirewallPermissionsOptions, type FirewallPrompt, type FirewallRequest, type FirewallRuleTarget, type FirewallRules, type FirewallSummary, type ForwardedKeys, type FrameLike, type GrantRecord, type Grants, type GrantsOptions, type GroupMessagingOptions, type GuardFacade, type GuardPipeline, type GuardPipelineOptions, HANDLER_PREFERENCES_KIND, type HandlerChoice, type HandlerDefaults, type HandlerDefaultsOptions, type HandlerOption, type HandlerPreferences, type HandlerPrompt, type IdentityProfile, type IdentityProviderOptions, type IdentityProviders, type InboxRelays, type InstallableApplet, type InstalledApplet, type InstalledApplets, type InstalledContract, type IntentDeliveryOptions, type IntentRouter, type IntentRouterOptions, type Intents, KERNL_FRAME_POLICY_META, KEY_REPEAT_WINDOW_MS, type Kernl, KernlAccountManager, type KernlDownloads, type KernlDownloadsDeps, type KernlFirewall, type KernlGrants, type KernlHost, type KernlIntentDeps, type KernlIntents, type KernlMultiplayer, type KernlNetwork, type KernlNetworkParts, type KernlOptions, type KernlServiceDeps, type KernlServices, type KeymapHold, type KeymapHoldOptions, LINK_PROTOCOLS, type LifecycleContext, type LoadCatalogOptions, type LookupBefore, type LookupReplaceableOptions, MANIFEST_TIMING, MAX_UNMOUNTED_PLANS, MESSAGES_DOMAIN, MESSAGE_COMPANION_DOMAINS, MESSAGING_UNAVAILABLE_REASONS, type MailboxPool, type MailboxSigner, type MailboxState, type Mailboxes, type ManifestTiming, type MessagingBackendFactories, type MessagingEncryption, type MountDeps, type MountGuardHooks, type MountPlan, type MountedApplet, type MultiServerUpload, type MultiplayerSettings, type MultiplayerState, type NamespacedStore, type NzbDocument, type NzbDownloader, type NzbServiceOptions, type OutboxRelayPoolLike, PACKAGE_NAME, PERSON_HINT_TIMEOUT_MS, PLAINTEXT_KEY_ACCOUNT_TYPES, type People, type PeopleOptions, type PersonPointer, type PipelineDisposition, type PlanMountOptions, type PlannedExtensions, type PreferenceSigner, type ProfileCard, type ProfileLoader, type ProfilePointer, type Profiles, type ProfilesOptions, type PublishAnswer, type PublishOutcome, type PublishedPointer, type RatchetMessagingOptions, type RelayDirectory, type RelayDirectoryOptions, type RelayListing, type RelayPermissions, type RelayTier, type RelayTiers, type RemoteToolsOptions, type RemoteToolsSettings, type ResolveAppletIdentity, type ResolveAppletOptions, type ResolvedApplet, type RoutedClient, type RoutedDomain, SHELL_RELAY_OPTIONS, SOULSEEK_SESSION_QUESTION, type SealedGroupStoreOptions, type SealedRatchetStorageOptions, type SecretsDescription, type SecretsProvider, type Session, type SettingsPrompt, type ShellAdapterDeps, type ShortcutKey, type ShortcutSettings, type ShortcutsOptions, type ShortcutsService, type SignalRelay, type SignalSigner, type SignerMessagingOptions, type SigningConsent, type SigningConsentOptions, type SigningTemplate, type SoulseekLimits, type SoulseekServiceOptions, type StorageLike, type SuggestOptions, type SuggestPurpose, THROWAWAY_IDENTITY_TYPE, TOOL_DISCOVERY_TIMEOUT_MS, ThrowawayIdentity, type TierMap, type ToolDiscoveryOptions, type ToolFamilyCandidate, type TopicCount, type TorrentServiceOptions, UNKNOWN_CURRENT_VERSION, type UploadDetails, type WindowIdentities, type WindowResolution, abbreviate, acceptAnyRelay, addressOf, answerFor, appletMessageFailure, askUploadConsent, builtinAddress, capabilitiesForDomain, capabilitiesForDomains, capabilitiesInForce, catalogIdForRef, catalogRelays, commonActionsFor, createAccountFileServers, createAccountMailboxes, createAppletAdmissions, createAppletConfig, createAppletLifecycle, createAppletRelayBackend, createAppletRelayService, createAppletTraffic, createAuthHooks, createBlossomUploader, createCommonActions, createConsentHandler, createCvmRelayPool, createDefaultBridges, createDefaultMessaging, createDirectConnectionsService, createDirectSignaling, createDmRelayPool, createDownloadClients, createEnvironmentResolver, createFirewall, createFirewallPermissions, createFirewallRules, createForwardedKeys, createGrants, createGroupMessagesBackend, createGroupNetwork, createGuardPipeline, createHandlerDefaults, createIdentityProviders, createInstalledApplets, createIntentDelivery, createIntentRouter, createKernl, createKernlAccounts, createKernlDownloads, createKernlIntents, createKernlNetwork, createKernlServices, createKeymapHold, createLegacyMessagesBackend, createMemorySecrets, createMultiplayerSettings, createNamespacedStore, createNzbService, createOutboxRelayPool, createPeople, createPrivateMessagesBackend, createProfiles, createRatchetMessagesBackend, createRelayDirectory, createRelayPoolHooks, createRelayPoolLike, createRelayTiers, createRemoteToolsService, createReplaceableLoader, createRuntimeRateLimiter, createSealedGroupStore, createSealedRatchetStorage, createShellAdapter, createShortcutsService, createSigningConsent, createSoulseekService, createStorageSecrets, createThrowawayIdentity, createTorrentService, createWindowIdentities, currentPageScheme, decodePointer, defaultFetchBlob, defaultFirewallRules, describeAppletMessage, describeApproval, describeChange, describeDirectConnection, describeDownloadQuestion, describeOutcome, describeUpload, directNamespace, discoverToolFamilies, domainsInForce, fetchManifestEvent, fetchThroughFirewall, fileServerTags, fileServersFromEvent, fuzzyScore, grantNarrowingReason, isDestructiveKind, isReadOnlyAccount, isTheme, labelConversations, loadCatalog, locateRecipients, locateSendRecipients, lookupRelaysOf, lookupReplaceable, mailboxTags, mailboxesFromEvent, mergeFamilies, messagingSigner, mountApplet, newestEntries, openDefaultArtifactCache, parseHandlerPreferences, parsePerson, permissionPrincipalFor, planMount, popularTopics, preferenceRelays, preferenceTemplate, preferredHandlers, publishAccepted, readNzbDocument, refForCatalogId, relayUrls, resolveApplet, resolveAppletEnvironment, resolveBuiltin, resolveWindow, resourceErrorFor, resourceInitFor, runtimeOpClass, sealsApplet, searchCatalog, selectRelayTier, shellRelayOrigins, signerAvailability, sizeWords, streamCatalog, subscribeWithEose, summarize, summarizePublish, supportsDomainBindings, toCatalogEntry, toGuardEvent, toProfileCard, toRelayUrl, toSession, validFamily, withheldDomains, wrapAccountSigner };
|