@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/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, FirewallEvent, AclStateContainer, ServiceHandler, PermissionRequirement, ServiceRegistry } from '@kehto/runtime';
7
- import { CvmRegistryFamily, ConfigSettingsContext, ConfigServiceOptions, IntentCatalogEntry, RelayPoolServiceOptions, DmRelayPool, IdentityServiceOptions, DmAdapter, Uploader, CommonServiceOptions, WebrtcServiceOptions, ThemeService, DmService, ResourceFetchInit, IntentResolver, IntentDispatchParams } from '@kehto/services';
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 server's reason, which is written for developers and often names
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 servers` or `No server accepted it`.
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 servers'
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 servers'
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: NostrEvent;
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
- /** Open a link outside the shell after the link policy allowed it. */
1375
- openLink(url: string): void;
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
- /** Called after the core removed a frame because its binding was revoked. */
1379
- onRevoked(windowId: string, reason: string): void;
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
- /** Called once when a window crosses the quarantine threshold; kernl revokes it here, before the triggering envelope is dispatched. */
2408
- readonly onQuarantine?: (windowId: string, napplet: string) => void;
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. `drop` discards an envelope over its
2432
- * size cap, a burst above the per-second rate, a request over the
2433
- * focus-aware firewall's budget, a hidden window's envelope past the defer
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 firewall, then kehto's bridge.
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. The runtime firewall configured by
2460
- * `applyRuntimeFirewallRules` adds the profile's per-class rates to every
2461
- * envelope it dispatches, held ones included.
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
- * Where kernl stores the runtime firewall's configuration in the host storage.
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
- * localStorage.getItem(RUNTIME_FIREWALL_STORAGE_KEY); // the serialised kehto firewall config
3077
+ * runtimeOpClass('relay.publish'); // 'relay:publish'
3078
+ * runtimeOpClass('resource.network'); // 'resource:bytes'
3079
+ * runtimeOpClass('link.open'); // 'generic'
2479
3080
  * ```
2480
3081
  */
2481
- declare const RUNTIME_FIREWALL_STORAGE_KEY = "kernl:firewall:v1";
3082
+ declare function runtimeOpClass(operation: string): OpClass;
2482
3083
  /**
2483
- * How the guard's operation classes appear inside kehto's runtime firewall.
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 keys its observations by the sender capability a message needs
2486
- * (`relay:write`, `resource:fetch`), while the guard classifies by what the
2487
- * message does (`relay:publish`, `resource:bytes`). `null` means the class has
2488
- * no runtime counterpart: deletions share `relay:write` with other publishes,
2489
- * `control` envelopes need no capability, and `generic` becomes the per-applet
2490
- * global rate.
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
- * RUNTIME_OP_CLASSES['relay:publish']; // 'relay:write'
2495
- * RUNTIME_OP_CLASSES.control; // null
3103
+ * const rateLimiter = createRuntimeRateLimiter(() => pipeline.config);
3104
+ * const permissions: PermissionAdapter = { ...approvals, rateLimiter };
2496
3105
  * ```
2497
3106
  */
2498
- declare const RUNTIME_OP_CLASSES: Readonly<Record<OpClass, string | null>>;
2499
- /** One rate limit in the runtime's vocabulary. */
2500
- interface RuntimeRateRule {
2501
- readonly opClass: string;
2502
- readonly limit: RateLimit;
2503
- }
2504
- /** The rules {@link applyRuntimeFirewallRules} installs for one applet. */
2505
- interface RuntimeFirewallRules {
2506
- readonly rates: readonly RuntimeRateRule[];
2507
- readonly globalRate: RateLimit;
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
- * Translate the guard profile's per-class rates for one applet into the
2511
- * runtime firewall's `(napplet, opClass)` rate limits.
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 config - Current guard configuration.
2514
- * @param napplet - Applet identity (dTag).
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
- * runtimeFirewallRules(createGuardConfig('strict'), 'chat').rates.find((r) => r.opClass === 'relay:write');
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 runtimeFirewallRules(config: GuardConfig, napplet: string): RuntimeFirewallRules;
2522
- /** The runtime firewall's state, as far as kernl configures it. */
2523
- type RuntimeFirewallState = Pick<FirewallStateContainer, 'setRateLimit' | 'setGlobalRate' | 'setUnfocusedMultiplier' | 'setBurstGuard' | 'persist'>;
3190
+ declare function createFirewallRules(storage: StorageLike): FirewallRules;
3191
+
2524
3192
  /**
2525
- * Install the guard profile's rates for an applet in the runtime firewall.
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 runtime's firewall runs before every dispatch, including the envelopes
2528
- * kernl held for a hidden window and released later, so the profile's limits
2529
- * are pushed into it when a window mounts and again when the profile changes.
2530
- * No policy is set: kehto's `allow` policy bypasses every rate, matcher and
2531
- * burst check, and the user's choices to deny or block live in the grants
2532
- * layer, not here.
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 firewallState - The `legacyFirewall` from {@link createRuntimeFirewallHooks}.
2535
- * @param config - Current guard configuration.
2536
- * @param napplet - Applet identity (dTag).
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
- * applyRuntimeFirewallRules(hooks.legacyFirewall, guardConfig, summary.identity.dTag);
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 applyRuntimeFirewallRules(firewallState: RuntimeFirewallState, config: GuardConfig, napplet: string): void;
3214
+ declare function describeApproval(prompt: Pick<ApprovalPrompt, 'missing' | 'allowLifetimes'>, applet: FirewallApplet): FirewallSummary;
2544
3215
  /**
2545
- * Apply a profile's shell-wide limits to the runtime firewall: the unfocused
2546
- * multiplier, which the runtime applies with the focus kernl reports through
2547
- * `getFocusContext`, and the startup burst guard.
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 firewallState - The `legacyFirewall` from {@link createRuntimeFirewallHooks}.
2550
- * @param config - The guard configuration of the profile now in force.
2551
- * @returns Nothing; the firewall state is mutated and persisted.
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
- * applyRuntimeFirewallProfile(hooks.legacyFirewall, createGuardConfig('balanced'));
2555
- * hooks.legacyFirewall.getConfig().unfocusedMultiplier; // 0.5
3225
+ * answerFor(summary, 'allow-once'); // { effect: 'allow', lifetime: 'once' }
3226
+ * answerFor(summary, undefined); // { effect: 'cancel' }
2556
3227
  * ```
2557
3228
  */
2558
- declare function applyRuntimeFirewallProfile(firewallState: RuntimeFirewallState, config: GuardConfig): void;
3229
+ declare function answerFor(summary: Pick<FirewallSummary, 'choices'>, choice: FirewallChoice | undefined): ApprovalAnswer;
3230
+
2559
3231
  /**
2560
- * Turn a runtime firewall event into a guard event. The runtime's event
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
- * toGuardEvent({ windowId: 'w1', napplet: 'chat', opClass: 'state:write', decision: 'reject', action: 'block', ruleId: 'rate:opclass', reason: '…' }, 0).reason;
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 function toGuardEvent(event: FirewallEvent, at: number): GuardEvent;
2576
- /** The runtime firewall hooks kernl hands to `createShellAdapter`. */
2577
- interface RuntimeFirewallHooks {
2578
- /** The firewall the runtime evaluates; also what {@link applyRuntimeFirewallRules} configures. */
2579
- readonly legacyFirewall: FirewallStateContainer;
2580
- readonly onFirewallEvent: (event: FirewallEvent) => void;
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
- /** Options for {@link createRuntimeFirewallHooks}. */
2583
- interface RuntimeFirewallHooksOptions {
2584
- /** The host storage; the config is kept under {@link RUNTIME_FIREWALL_STORAGE_KEY}. */
2585
- readonly storage: StorageLike;
2586
- /** Receives every runtime refusal and flag as a guard event. */
2587
- readonly onEvent: (event: GuardEvent) => void;
2588
- readonly now?: () => number;
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 runtime firewall, persisted in kernl's host storage, and its event
2592
- * sink into the guard event stream. These report what the runtime itself
2593
- * refused, which is the startup burst and anything over budget when held
2594
- * envelopes are released; what kernl drops before the runtime sees it is
2595
- * reported by kernl's own guard layers.
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 - Host storage, the guard event sink and a clock.
2598
- * @returns `legacyFirewall` and `onFirewallEvent` for the `ShellAdapter`.
3376
+ * @param options - The rules and kehto's grant store.
3377
+ * @returns The firewall.
2599
3378
  * @example
2600
3379
  * ```ts
2601
- * const hooks = createRuntimeFirewallHooks({ storage: localStorage, onEvent: (event) => log.push(event) });
2602
- * const adapter: ShellAdapter = { ...rest, ...hooks };
2603
- * applyRuntimeFirewallProfile(hooks.legacyFirewall, createGuardConfig('strict'));
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 createRuntimeFirewallHooks(options: RuntimeFirewallHooksOptions): RuntimeFirewallHooks;
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 and scoped storage. No network, and not the identity: which
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, plus the downloads, sharing
3168
- * and mail bridges. With a `handoff` opener those four hand each locator to an app on
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`, `outbox`
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 dm handles.
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 runtime firewall's persistence and event sink; see `createRuntimeFirewallHooks`. */
3716
- readonly runtimeFirewall: RuntimeFirewallHooks;
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; hotkeys are
3725
- * not forwarded; there is no worker relay, the applesauce pool is the only
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; and
3730
- * every port envelope passes kernl's guard before the runtime sees it.
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 runtime firewall kernl constructed; mounting installs the applet's rates in it. */
3749
- readonly firewall: RuntimeFirewallState;
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, RUNTIME_FIREWALL_STORAGE_KEY, RUNTIME_OP_CLASSES, 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 RuntimeFirewallHooks, type RuntimeFirewallHooksOptions, type RuntimeFirewallRules, type RuntimeFirewallState, type RuntimeRateRule, SHELL_RELAY_OPTIONS, type SealedGroupStoreOptions, type SealedRatchetStorageOptions, type Session, type SettingsPrompt, type ShellAdapterDeps, type SignalRelay, type SignalSigner, type SignerMessagingOptions, type SigningConsent, type SigningConsentOptions, type SigningTemplate, type StorageLike, type SuggestOptions, type SuggestPurpose, THROWAWAY_IDENTITY_TYPE, TOOL_DISCOVERY_TIMEOUT_MS, ThrowawayIdentity, type TierMap, type ToolDiscoveryOptions, type ToolFamilyCandidate, type TopicCount, UNKNOWN_CURRENT_VERSION, type UploadDetails, type WindowIdentities, type WindowResolution, abbreviate, addressOf, applyRuntimeFirewallProfile, applyRuntimeFirewallRules, askUploadConsent, builtinAddress, capabilitiesForDomain, capabilitiesForDomains, capabilitiesInForce, catalogIdForRef, catalogRelays, commonActionsFor, createAccountFileServers, createAccountMailboxes, createAppletConfig, createAppletLifecycle, createAppletRelayBackend, createAppletRelayService, createAuthHooks, createBlossomUploader, createCommonActions, createConsentHandler, createCvmRelayPool, createDefaultBridges, createDefaultMessaging, createDirectConnectionsService, createDirectSignaling, createDmRelayPool, createEnvironmentResolver, createGrants, createGroupMessagesBackend, createGroupNetwork, createGuardPipeline, createHandlerDefaults, createIdentityProviders, createInstalledApplets, createIntentDelivery, createIntentRouter, createKernl, createKernlAccounts, createKernlIntents, createKernlNetwork, createKernlServices, createLegacyMessagesBackend, createMultiplayerSettings, createNamespacedStore, createOutboxRelayPool, createPeople, createPrivateMessagesBackend, createProfiles, createRatchetMessagesBackend, createRelayDirectory, createRelayPoolHooks, createRelayPoolLike, createRelayTiers, createRemoteToolsService, createReplaceableLoader, createRuntimeFirewallHooks, createSealedGroupStore, createSealedRatchetStorage, createShellAdapter, createSigningConsent, createThrowawayIdentity, createWindowIdentities, decodePointer, defaultFetchBlob, describeChange, describeDirectConnection, describeOutcome, describeUpload, directNamespace, discoverToolFamilies, domainsInForce, fetchManifestEvent, fileServerTags, fileServersFromEvent, fuzzyScore, grantNarrowingReason, isDestructiveKind, isReadOnlyAccount, isTheme, labelConversations, loadCatalog, locateRecipients, lookupRelaysOf, lookupReplaceable, mailboxTags, mailboxesFromEvent, mergeFamilies, messagingSigner, mountApplet, newestEntries, openDefaultArtifactCache, parseHandlerPreferences, parsePerson, planMount, popularTopics, preferenceRelays, preferenceTemplate, preferredHandlers, publishAccepted, refForCatalogId, relayUrls, resolveApplet, resolveBuiltin, resolveWindow, resourceInitFor, runtimeFirewallRules, sealsApplet, searchCatalog, selectRelayTier, signerAvailability, sizeWords, streamCatalog, subscribeWithEose, summarize, summarizePublish, toCatalogEntry, toGuardEvent, toProfileCard, toRelayUrl, toSession, validFamily, withheldDomains, wrapAccountSigner };
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 };