@kernlize/core 0.8.0 → 0.11.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
@@ -1,31 +1,218 @@
1
1
  import { Observable, Subscription } from 'rxjs';
2
2
  import { EventStore } from 'applesauce-core';
3
- import { RelayPool } from 'applesauce-relay';
3
+ import { RelayPool, RelayPoolOptions } from 'applesauce-relay';
4
4
  import { AccountManager, IAccount } from 'applesauce-accounts';
5
5
  import { RelayPoolHooks, RelayPoolLike, ShellBridge, ShellEnvironment, AuthHooks, ShellAdapter, OriginRegistry, NappletMessageDecision, CapabilityHooks, NappletRevocation, UnroutedMessageInfo } from '@kehto/shell';
6
- import { Capability, ConsentRequest, Signer, FirewallPersistence, FirewallEvent, FirewallStateContainer, AclStateContainer, ServiceRegistry, ServiceHandler } from '@kehto/runtime';
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';
8
+ import { NostrFilter, NostrEvent, EventTemplate, NappletMessage } from '@napplet/core';
7
9
  import { NappletManifest, NappletArtifactCache, ResolvedNapplet } from '@kehto/nip/5d';
8
- import { NostrEvent, NostrFilter, EventTemplate, NappletMessage } from '@napplet/core';
9
10
  import { WindowVisibility, GuardConfig, GuardProfile, GuardEvent, MitigationDescription, GuardDisposition, OpClass } from '@kernlize/guard';
10
11
  import { MessagingRegistry, MessagingBackend, ReplyPrompt, ReplyAnswer, MessagingRegistryOptions, ProviderAvailability } from '@kernlize/messaging';
11
12
  import { BridgeRegistry, TorrentBackend, BridgeRegistryOptions, HttpBridgeOptions, HandoffOpener, ResourceResolveInit } from '@kernlize/bridges';
12
13
  import { EventCacheOpener, ConnectedEventCache } from './cache/index.js';
13
14
  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';
14
- import { ISigner } from 'applesauce-signers';
15
+ import { ISigner, PrivateKeySigner } from 'applesauce-signers';
15
16
  import { NostrEvent as NostrEvent$1, Filter } from 'applesauce-core/helpers';
16
- import { IntentCatalogEntry, RelayPoolServiceOptions, DmRelayPool, IdentityServiceOptions, DmAdapter, Uploader, ThemeService, DmService, ResourceFetchInit, IntentResolver, IntentDispatchParams } from '@kehto/services';
17
17
  import { AddressPointerLoader } from 'applesauce-loaders/loaders';
18
18
  import { CacheRequest } from 'applesauce-loaders';
19
- import { RateLimit } from '@kehto/firewall';
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';
23
23
  import { GenericKeyValueStore, NostrNetworkInterface } from '@internet-privacy/marmot-ts';
24
24
  import { StorageAdapter } from 'nostr-double-ratchet';
25
25
  import { SignedEvent, BlobDescriptor } from 'blossom-client-sdk';
26
+ import { CvmRelayPool } from '@kehto/services/cvm-nostr-transport';
26
27
  import { Theme } from '@napplet/nap/theme/types';
27
28
  import 'applesauce-core/event-store';
28
29
 
30
+ /** What the person chose for meeting people and calling remote tools on this device. */
31
+ interface MultiplayerState {
32
+ /** Servers that introduce people and find tool servers; undefined leaves the host's choice. */
33
+ readonly servers?: readonly string[];
34
+ /** Servers that help connections through; undefined leaves the host's choice. */
35
+ readonly helpers?: readonly DirectIceServer[];
36
+ /** Tool families the person trusts, pinned to verified schemas. */
37
+ readonly families: readonly CvmRegistryFamily[];
38
+ }
39
+ /** The person's settings for direct connections and remote tools. */
40
+ interface MultiplayerSettings {
41
+ readonly state$: Observable<MultiplayerState>;
42
+ state(): MultiplayerState;
43
+ /** Choose the servers, or `undefined` to go back to the host's. Throws `invalid:relay-url`. */
44
+ setServers(urls: readonly string[] | undefined): void;
45
+ /** Choose the helpers, or `undefined` to go back to the host's. Throws `invalid:helper`. */
46
+ setHelpers(helpers: readonly DirectIceServer[] | undefined): void;
47
+ /** Trust a family, replacing one with the same label and provider. Throws `invalid:family`. */
48
+ saveFamily(family: CvmRegistryFamily): void;
49
+ removeFamily(label: string, pubkey: string): void;
50
+ }
51
+ /**
52
+ * Whether a tool family is one the shell can keep: a label, a provider key and
53
+ * relays, and 1 to 64 uniquely named tools each pinned to a schema hash.
54
+ *
55
+ * @param family - A candidate family.
56
+ * @returns True when it can be saved.
57
+ * @example
58
+ * ```ts
59
+ * validFamily({ family: 'rooms', server: { pubkey, relays: ['wss://tools.example'] }, tools: [{ name: 'join', schemaHash }] }); // true
60
+ * ```
61
+ */
62
+ declare function validFamily(family: CvmRegistryFamily): boolean;
63
+ /**
64
+ * The person's own settings for meeting people and calling remote tools, kept
65
+ * on this device. They override the host's defaults: the person chooses the
66
+ * servers that introduce them, whether anything helps their connections
67
+ * through, and which tool families they trust (D-043). A stored value that
68
+ * fails validation is read as unset rather than trusted.
69
+ *
70
+ * @param storage - Where the settings are kept, under `kernl:multiplayer:v1`.
71
+ * @returns The settings.
72
+ * @example
73
+ * ```ts
74
+ * const settings = createMultiplayerSettings(localStorage);
75
+ * settings.setServers(['wss://meet.example']);
76
+ * ```
77
+ */
78
+ declare function createMultiplayerSettings(storage: StorageLike): MultiplayerSettings;
79
+
80
+ /** The slice of applesauce's `RelayPool` kernl adapts. Narrow so tests can supply a fake. */
81
+ type ApplesaucePool = Pick<RelayPool, 'req' | 'request' | 'publish'>;
82
+ /**
83
+ * How the shell's own pool redials a relay that refused the connection.
84
+ *
85
+ * applesauce-relay 7.1 redials refused connections three times by default,
86
+ * pausing one, two and three seconds, and a publish waits for every relay it
87
+ * was sent to, so one dead relay in a tier held a publish for about six
88
+ * seconds. One redial after a second keeps the case it exists for: a busy
89
+ * public relay answers a websocket upgrade with 502 or 503 for a moment and
90
+ * accepts the next one (D-025, D-037). Subscriptions keep applesauce's
91
+ * default, because a live subscription should come back after a drop.
92
+ *
93
+ * @example
94
+ * ```ts
95
+ * const pool = new RelayPool(SHELL_RELAY_OPTIONS);
96
+ * ```
97
+ */
98
+ declare const SHELL_RELAY_OPTIONS: RelayPoolOptions;
99
+ /** A subscription that delivers events once each and signals the end of stored events. */
100
+ interface EoseSubscription {
101
+ unsubscribe(): void;
102
+ }
103
+ /**
104
+ * Subscribe through the pool's raw `req` so the end of stored events is
105
+ * observable: `EOSE` is reported once, after every relay has answered or
106
+ * failed, and events are deduplicated by id because `req` does not.
107
+ * applesauce's `subscription()` deduplicates but hides `EOSE`, which kehto's
108
+ * relay service relies on to answer `relay.subscribe`.
109
+ *
110
+ * @param pool - The shared applesauce pool.
111
+ * @param relays - Relay URLs to ask.
112
+ * @param filters - Filters for the request.
113
+ * @param callback - Receives each new event once, then `'EOSE'`.
114
+ * @returns A handle that closes the subscription.
115
+ * @example
116
+ * ```ts
117
+ * const sub = subscribeWithEose(pool, ['wss://relay.example'], [{ kinds: [1] }], (item) => {
118
+ * if (item !== 'EOSE') console.log(item.id);
119
+ * });
120
+ * sub.unsubscribe();
121
+ * ```
122
+ */
123
+ declare function subscribeWithEose(pool: Pick<ApplesaucePool, 'req'>, relays: string[], filters: NostrFilter[], callback: (item: NostrEvent | 'EOSE') => void): EoseSubscription;
124
+ /**
125
+ * Adapt the shared applesauce `RelayPool` to kehto's `RelayPoolLike`.
126
+ *
127
+ * @param pool - The one pool the shell owns (D-002).
128
+ * @returns An object kehto's `RelayPoolHooks.getRelayPool` can return.
129
+ * @example
130
+ * ```ts
131
+ * const like = createRelayPoolLike(pool);
132
+ * like.subscription(['wss://relay.example'], [{ kinds: [1] }]).subscribe((item) => {});
133
+ * ```
134
+ */
135
+ declare function createRelayPoolLike(pool: ApplesaucePool): RelayPoolLike;
136
+ /**
137
+ * Choose the relay tier for a set of filters.
138
+ *
139
+ * Profiles, follow lists and relay lists come from the discovery tier; applet
140
+ * manifests from the apps tier; everything else goes to the user's outbox
141
+ * relays plus the super tier. A filter without kinds cannot be classified and
142
+ * takes the general path.
143
+ *
144
+ * @param tiers - The current tier configuration.
145
+ * @param filters - Filters about to be sent.
146
+ * @returns Relay URLs, deduplicated.
147
+ * @example
148
+ * ```ts
149
+ * selectRelayTier(tiers, [{ kinds: [0], authors: [pubkey] }]); // discovery, then outbox and super
150
+ * ```
151
+ */
152
+ declare function selectRelayTier(tiers: RelayTiers, filters: readonly NostrFilter[]): string[];
153
+ /**
154
+ * Build kehto's `RelayPoolHooks` over the shared applesauce pool.
155
+ *
156
+ * Scoped relays (one relay per window, the NIP-29 pattern) are kept minimal:
157
+ * one open subscription per window, replaced on reopen, and events delivered
158
+ * to the window's bound port as `relay.event` envelopes.
159
+ *
160
+ * @param pool - The shared applesauce pool.
161
+ * @param tiers - Relay tiers used for `selectRelayTier`.
162
+ * @returns Hooks for `ShellAdapter.relayPool`.
163
+ * @example
164
+ * ```ts
165
+ * const adapter: ShellAdapter = { relayPool: createRelayPoolHooks(pool, tiers), ... };
166
+ * ```
167
+ */
168
+ declare function createRelayPoolHooks(pool: ApplesaucePool, tiers: RelayTiers): RelayPoolHooks;
169
+
170
+ /**
171
+ * How long a search waits for the servers it asked, in milliseconds.
172
+ *
173
+ * @example
174
+ * ```ts
175
+ * discoverToolFamilies(input, { pool, relays, fetch, timeoutMs: TOOL_DISCOVERY_TIMEOUT_MS / 3 });
176
+ * ```
177
+ */
178
+ declare const TOOL_DISCOVERY_TIMEOUT_MS = 15000;
179
+ /** A family found for the person to review: the provider, its verified tools, and where it came from. */
180
+ interface ToolFamilyCandidate {
181
+ readonly family: CvmRegistryFamily;
182
+ /** The announcement the inventory was read from. */
183
+ readonly eventId: string;
184
+ /** What the person typed, then the event. */
185
+ readonly source: string;
186
+ }
187
+ /** What a search needs. */
188
+ interface ToolDiscoveryOptions {
189
+ readonly pool: Pick<ApplesaucePool, 'request'>;
190
+ /** Asked when the reference names none. */
191
+ readonly relays: readonly string[];
192
+ /** Reads a website's published address. */
193
+ readonly fetch: typeof fetch;
194
+ readonly timeoutMs?: number;
195
+ }
196
+ /**
197
+ * Find tool families from what the person typed: a reference to a server's or
198
+ * a tool list's announcement, a tool's schema hash, or a website that
199
+ * publishes its provider. Only signed announcements are read; every tool's
200
+ * hash is computed again from its schema, and an announcement whose stated
201
+ * hash differs is refused. The newest inventory of each provider is the one
202
+ * read, never an older one in its place (D-043).
203
+ *
204
+ * @param input - What the person typed.
205
+ * @param options - Pool, default relays, and the website fetcher.
206
+ * @returns One candidate per provider, for the person to name and save.
207
+ * @throws `invalid:tool-reference`, `unavailable:website`, `invalid:tool-inventory`, or `unavailable:no-tools`.
208
+ * @example
209
+ * ```ts
210
+ * const [candidate] = await discoverToolFamilies('nevent1…', { pool, relays: tiers.get().super });
211
+ * settings.saveFamily({ ...candidate.family, family: 'rooms' });
212
+ * ```
213
+ */
214
+ declare function discoverToolFamilies(input: string, options: ToolDiscoveryOptions): Promise<ToolFamilyCandidate[]>;
215
+
29
216
  /** One applet as the store lists it. Read from a signed manifest; its bytes are verified only when it is opened. */
30
217
  interface CatalogEntry {
31
218
  /** kehto's publisher- and kind-safe identity; the same id the intent catalogue uses. */
@@ -452,79 +639,6 @@ declare function mailboxTags(mailboxes: Mailboxes, previous?: NostrEvent$1): str
452
639
  */
453
640
  declare function createAccountMailboxes(options: AccountMailboxesOptions): AccountMailboxes;
454
641
 
455
- /** The slice of applesauce's `RelayPool` kernl adapts. Narrow so tests can supply a fake. */
456
- type ApplesaucePool = Pick<RelayPool, 'req' | 'request' | 'publish'>;
457
- /** A subscription that delivers events once each and signals the end of stored events. */
458
- interface EoseSubscription {
459
- unsubscribe(): void;
460
- }
461
- /**
462
- * Subscribe through the pool's raw `req` so the end of stored events is
463
- * observable: `EOSE` is reported once, after every relay has answered or
464
- * failed, and events are deduplicated by id because `req` does not.
465
- * applesauce's `subscription()` deduplicates but hides `EOSE`, which kehto's
466
- * relay service relies on to answer `relay.subscribe`.
467
- *
468
- * @param pool - The shared applesauce pool.
469
- * @param relays - Relay URLs to ask.
470
- * @param filters - Filters for the request.
471
- * @param callback - Receives each new event once, then `'EOSE'`.
472
- * @returns A handle that closes the subscription.
473
- * @example
474
- * ```ts
475
- * const sub = subscribeWithEose(pool, ['wss://relay.example'], [{ kinds: [1] }], (item) => {
476
- * if (item !== 'EOSE') console.log(item.id);
477
- * });
478
- * sub.unsubscribe();
479
- * ```
480
- */
481
- declare function subscribeWithEose(pool: Pick<ApplesaucePool, 'req'>, relays: string[], filters: NostrFilter[], callback: (item: NostrEvent | 'EOSE') => void): EoseSubscription;
482
- /**
483
- * Adapt the shared applesauce `RelayPool` to kehto's `RelayPoolLike`.
484
- *
485
- * @param pool - The one pool the shell owns (D-002).
486
- * @returns An object kehto's `RelayPoolHooks.getRelayPool` can return.
487
- * @example
488
- * ```ts
489
- * const like = createRelayPoolLike(pool);
490
- * like.subscription(['wss://relay.example'], [{ kinds: [1] }]).subscribe((item) => {});
491
- * ```
492
- */
493
- declare function createRelayPoolLike(pool: ApplesaucePool): RelayPoolLike;
494
- /**
495
- * Choose the relay tier for a set of filters.
496
- *
497
- * Profiles, follow lists and relay lists come from the discovery tier; applet
498
- * manifests from the apps tier; everything else goes to the user's outbox
499
- * relays plus the super tier. A filter without kinds cannot be classified and
500
- * takes the general path.
501
- *
502
- * @param tiers - The current tier configuration.
503
- * @param filters - Filters about to be sent.
504
- * @returns Relay URLs, deduplicated.
505
- * @example
506
- * ```ts
507
- * selectRelayTier(tiers, [{ kinds: [0], authors: [pubkey] }]); // discovery, then outbox and super
508
- * ```
509
- */
510
- declare function selectRelayTier(tiers: RelayTiers, filters: readonly NostrFilter[]): string[];
511
- /**
512
- * Build kehto's `RelayPoolHooks` over the shared applesauce pool.
513
- *
514
- * Scoped relays (one relay per window, the NIP-29 pattern) are kept minimal:
515
- * one open subscription per window, replaced on reopen, and events delivered
516
- * to the window's bound port as `relay.event` envelopes.
517
- *
518
- * @param pool - The shared applesauce pool.
519
- * @param tiers - Relay tiers used for `selectRelayTier`.
520
- * @returns Hooks for `ShellAdapter.relayPool`.
521
- * @example
522
- * ```ts
523
- * const adapter: ShellAdapter = { relayPool: createRelayPoolHooks(pool, tiers), ... };
524
- * ```
525
- */
526
- declare function createRelayPoolHooks(pool: ApplesaucePool, tiers: RelayTiers): RelayPoolHooks;
527
-
528
642
  /**
529
643
  * File servers to use when the account has not published its own list: public
530
644
  * Blossom servers that answered an upload preflight when this was chosen.
@@ -613,6 +727,42 @@ declare function fileServerTags(servers: readonly string[], previous?: NostrEven
613
727
  */
614
728
  declare function createAccountFileServers(options: AccountFileServersOptions): AccountFileServers;
615
729
 
730
+ /** What the host shows when an applet asks for its settings. */
731
+ interface SettingsPrompt {
732
+ /** The applet's title, for the heading. */
733
+ readonly title: string;
734
+ /** The section the applet asked to open, if any. */
735
+ readonly section?: string;
736
+ /** The accepted schema, the current values and the commit that validates, saves and tells the applet. */
737
+ readonly context: ConfigSettingsContext;
738
+ }
739
+ /** Options for {@link createAppletConfig}. */
740
+ interface AppletConfigOptions {
741
+ readonly storage: StorageLike;
742
+ /** The applet a window runs, as a key that stays the same across its versions, with its title; none for an unknown window. */
743
+ readonly appletOf: (windowId: string) => {
744
+ readonly key: string;
745
+ readonly title: string;
746
+ } | undefined;
747
+ /** Shows the settings form. */
748
+ readonly present: (prompt: SettingsPrompt) => void;
749
+ }
750
+ /**
751
+ * kernl's NAP-CONFIG hooks for kehto's `createConfigService`: an applet's
752
+ * settings, as the person set them in a form the shell draws from the
753
+ * applet's schema. kehto validates the schema and every value. kernl keeps
754
+ * the values per applet, not per version, so an update keeps them, and only
755
+ * the shell's form ever writes them (D-036).
756
+ *
757
+ * @param options - Storage, the window-to-applet lookup and the form.
758
+ * @returns Options for `createConfigService`.
759
+ * @example
760
+ * ```ts
761
+ * registry.config = createConfigService(createAppletConfig({ storage, appletOf, present: host.presentSettings })).handler;
762
+ * ```
763
+ */
764
+ declare function createAppletConfig(options: AppletConfigOptions): ConfigServiceOptions;
765
+
616
766
  /**
617
767
  * How many manifests the store asks each relay for.
618
768
  *
@@ -1066,8 +1216,11 @@ interface ConsentLine {
1066
1216
  /** A write described as what it changes, not as JSON. */
1067
1217
  interface ConsentSummary {
1068
1218
  readonly title: string;
1069
- /** `destructive` replaces or erases part of the record; `public` puts something where anyone can fetch it; both are asked about. */
1070
- readonly severity: 'routine' | 'destructive' | 'public';
1219
+ /**
1220
+ * `destructive` replaces or erases part of the record; `public` puts something where anyone can fetch it;
1221
+ * `direct` connects the person to someone else, who learns their network address. All three are asked about.
1222
+ */
1223
+ readonly severity: 'routine' | 'destructive' | 'public' | 'direct';
1071
1224
  readonly lines: readonly ConsentLine[];
1072
1225
  readonly applet: AppletIdentity;
1073
1226
  /** The raw event, for an "advanced" disclosure. */
@@ -1134,6 +1287,8 @@ interface KernlHost {
1134
1287
  readonly storage: StorageLike;
1135
1288
  /** Ask the user. Resolve `false` on dismiss. The core never times this out. */
1136
1289
  presentConsent(prompt: ConsentPrompt): void;
1290
+ /** Show an applet's settings form. Without it applets cannot have settings, and the `config` domain is not offered (D-036). */
1291
+ presentSettings?(prompt: SettingsPrompt): void;
1137
1292
  /** Show something the applet or the guard wants the user to know. */
1138
1293
  notify(notice: {
1139
1294
  readonly title: string;
@@ -1208,6 +1363,37 @@ interface KernlOptions {
1208
1363
  readonly intervalMs: number;
1209
1364
  readonly attempts: number;
1210
1365
  };
1366
+ /** Where applets' remote tools are looked for, and which tool families the host vouches for (D-041). */
1367
+ readonly remoteTools?: RemoteToolsSettings;
1368
+ /** How applets connect people directly: the relays that introduce them and the ICE servers that help (D-042). */
1369
+ readonly directConnections?: DirectConnectionsSettings;
1370
+ }
1371
+ /** A STUN or TURN server, as `RTCPeerConnection` takes it. Its credentials stay in the shell. */
1372
+ interface DirectIceServer {
1373
+ readonly urls: readonly string[];
1374
+ readonly username?: string;
1375
+ readonly credential?: string;
1376
+ }
1377
+ /** The host's settings for direct connections between people. */
1378
+ interface DirectConnectionsSettings {
1379
+ /** Relays people in a room find each other through; the general (`super`) tier by default. */
1380
+ readonly relays?: readonly string[];
1381
+ /** STUN and TURN servers; none by default, so only people who can reach each other's devices connect. */
1382
+ readonly iceServers?: readonly DirectIceServer[];
1383
+ /** Makes a peer connection; the browser's `RTCPeerConnection` by default. Without either, the `webrtc` domain is not offered. */
1384
+ readonly createPeer?: (configuration: RTCConfiguration) => RTCPeerConnection;
1385
+ }
1386
+ /** The person's settings for meeting people and calling remote tools, kept on this device, and the search for tool families. */
1387
+ interface KernlMultiplayer extends MultiplayerSettings {
1388
+ /** Find tool families from an announcement reference, a schema hash or a website, over the servers in use (D-043). */
1389
+ discover(input: string): Promise<readonly ToolFamilyCandidate[]>;
1390
+ }
1391
+ /** The host's settings for remote tools. */
1392
+ interface RemoteToolsSettings {
1393
+ /** Relays a tool server is looked for on when the applet names none; the general (`super`) tier by default. */
1394
+ readonly relays?: readonly string[];
1395
+ /** Tool families pinned to verified schemas, for applets that ask by family; none by default. */
1396
+ readonly registry?: readonly CvmRegistryFamily[];
1211
1397
  }
1212
1398
  /** The applet store's catalogue. */
1213
1399
  interface AppletCatalog {
@@ -1253,6 +1439,8 @@ interface Kernl {
1253
1439
  readonly mailboxes: AccountMailboxes;
1254
1440
  /** Where the account's uploads go (BUD-03, kind 10063); the defaults while it has no list. */
1255
1441
  readonly files: AccountFileServers;
1442
+ /** The person's servers, helpers and trusted tool families for meeting people and calling remote tools (D-043). */
1443
+ readonly multiplayer: KernlMultiplayer;
1256
1444
  /** Monitored servers (NIP-66) for completing and suggesting; idle until `start()`. */
1257
1445
  readonly directory: RelayDirectory;
1258
1446
  readonly intents: Intents;
@@ -1374,6 +1562,26 @@ declare function publishAccepted(pool: ApplesaucePool, relays: string[], event:
1374
1562
  * ```
1375
1563
  */
1376
1564
  declare function createAppletRelayBackend(pool: ApplesaucePool, tiers: RelayTiers): RelayPoolServiceOptions;
1565
+ /**
1566
+ * kehto's relay service over the shared pool, with publishes planned by the
1567
+ * event's kind.
1568
+ *
1569
+ * kehto plans every relay operation before it runs and then publishes only to
1570
+ * the planned relays (`publishToRelays`), but its publish plan cannot see the
1571
+ * event. kernl's plan does, so a profile update is planned onto discovery
1572
+ * relays and the user's own, and a note onto the outbox plus the super tier,
1573
+ * as before. An applet's explicit relay hint is planned as kehto plans it.
1574
+ *
1575
+ * @param pool - The shared applesauce pool.
1576
+ * @param tiers - Relay tiers used to route publishes and unhinted subscriptions.
1577
+ * @returns The `relay` service handler.
1578
+ * @example
1579
+ * ```ts
1580
+ * registry.relay = createAppletRelayService(pool, tiers);
1581
+ * registry.relay.planRelayOperation('w1', { type: 'relay.publish', id: '1', event: { kind: 0 } }).relayUrls;
1582
+ * ```
1583
+ */
1584
+ declare function createAppletRelayService(pool: ApplesaucePool, tiers: RelayTiers): RelayPlanningServiceHandler;
1377
1585
  /**
1378
1586
  * The relay pool a messaging backend reads and writes through, satisfying
1379
1587
  * kehto's `DmRelayPool` over the same shared applesauce pool.
@@ -1734,8 +1942,8 @@ type PublishedPointer = Exclude<AppletPointer, {
1734
1942
  * release can still answer. `patienceMs` runs from the first relay that
1735
1943
  * answers with nothing, so a slower relay that does hold the applet is not cut
1736
1944
  * off. `timeoutMs` bounds a round of asking when no relay answers at all; a
1737
- * lookup is at most two rounds. `retryDelayMs` is the pause before a round
1738
- * whose relays all refused at once is asked a second time.
1945
+ * lookup is at most two rounds. `retryDelayMs` is the pause before a relay
1946
+ * that refused the connection is dialled once more.
1739
1947
  */
1740
1948
  interface ManifestTiming {
1741
1949
  readonly settleMs: number;
@@ -1764,8 +1972,8 @@ declare const MANIFEST_TIMING: ManifestTiming;
1764
1972
  * relay had a bad minute. For addresses, the newest event wins, since a named
1765
1973
  * applet is an addressable event that its author replaces on every release. A
1766
1974
  * relay that is down, silent or hangs up does not fail the lookup while
1767
- * another one answers, a round whose relays all refused at once is asked a
1768
- * second time, and hints that are not relay URLs are ignored.
1975
+ * another one answers, a relay that refused the connection is dialled once
1976
+ * more, and hints that are not relay URLs are ignored.
1769
1977
  *
1770
1978
  * @param pool - The shared applesauce pool.
1771
1979
  * @param tiers - Relay tiers; `apps` is asked first, `super` as the fallback.
@@ -1773,7 +1981,8 @@ declare const MANIFEST_TIMING: ManifestTiming;
1773
1981
  * @param timing - Overrides for {@link MANIFEST_TIMING}, applied to each round.
1774
1982
  * @returns The manifest event, unverified.
1775
1983
  * @throws `unavailable:manifest` when a relay answered and none had it, or
1776
- * there was no relay to ask; `unavailable:network` when no relay answered.
1984
+ * there was no relay to ask; `unavailable:unreachable` when every relay in every
1985
+ * round failed to open a connection; `unavailable:network` when no relay answered in time.
1777
1986
  * @example
1778
1987
  * ```ts
1779
1988
  * const event = await fetchManifestEvent(pool, tiers, decodePointer('naddr1…'));
@@ -2121,13 +2330,13 @@ type RuntimeFirewallState = Pick<FirewallStateContainer, 'setRateLimit' | 'setGl
2121
2330
  * burst check, and the user's choices to deny or block live in the grants
2122
2331
  * layer, not here.
2123
2332
  *
2124
- * @param firewallState - `bridge.runtime.firewallState`.
2333
+ * @param firewallState - The `legacyFirewall` from {@link createRuntimeFirewallHooks}.
2125
2334
  * @param config - Current guard configuration.
2126
2335
  * @param napplet - Applet identity (dTag).
2127
2336
  * @returns Nothing; the firewall state is mutated and persisted.
2128
2337
  * @example
2129
2338
  * ```ts
2130
- * applyRuntimeFirewallRules(bridge.runtime.firewallState, guardConfig, summary.identity.dTag);
2339
+ * applyRuntimeFirewallRules(hooks.legacyFirewall, guardConfig, summary.identity.dTag);
2131
2340
  * ```
2132
2341
  */
2133
2342
  declare function applyRuntimeFirewallRules(firewallState: RuntimeFirewallState, config: GuardConfig, napplet: string): void;
@@ -2136,13 +2345,13 @@ declare function applyRuntimeFirewallRules(firewallState: RuntimeFirewallState,
2136
2345
  * multiplier, which the runtime applies with the focus kernl reports through
2137
2346
  * `getFocusContext`, and the startup burst guard.
2138
2347
  *
2139
- * @param firewallState - `bridge.runtime.firewallState`.
2348
+ * @param firewallState - The `legacyFirewall` from {@link createRuntimeFirewallHooks}.
2140
2349
  * @param config - The guard configuration of the profile now in force.
2141
2350
  * @returns Nothing; the firewall state is mutated and persisted.
2142
2351
  * @example
2143
2352
  * ```ts
2144
- * applyRuntimeFirewallProfile(bridge.runtime.firewallState, createGuardConfig('balanced'));
2145
- * bridge.runtime.firewallState.getConfig().unfocusedMultiplier; // 0.5
2353
+ * applyRuntimeFirewallProfile(hooks.legacyFirewall, createGuardConfig('balanced'));
2354
+ * hooks.legacyFirewall.getConfig().unfocusedMultiplier; // 0.5
2146
2355
  * ```
2147
2356
  */
2148
2357
  declare function applyRuntimeFirewallProfile(firewallState: RuntimeFirewallState, config: GuardConfig): void;
@@ -2165,7 +2374,8 @@ declare function applyRuntimeFirewallProfile(firewallState: RuntimeFirewallState
2165
2374
  declare function toGuardEvent(event: FirewallEvent, at: number): GuardEvent;
2166
2375
  /** The runtime firewall hooks kernl hands to `createShellAdapter`. */
2167
2376
  interface RuntimeFirewallHooks {
2168
- readonly firewallPersistence: FirewallPersistence;
2377
+ /** The firewall the runtime evaluates; also what {@link applyRuntimeFirewallRules} configures. */
2378
+ readonly legacyFirewall: FirewallStateContainer;
2169
2379
  readonly onFirewallEvent: (event: FirewallEvent) => void;
2170
2380
  }
2171
2381
  /** Options for {@link createRuntimeFirewallHooks}. */
@@ -2177,18 +2387,19 @@ interface RuntimeFirewallHooksOptions {
2177
2387
  readonly now?: () => number;
2178
2388
  }
2179
2389
  /**
2180
- * The runtime firewall's persistence and event sink, through kernl's host
2181
- * storage and guard event stream. These report what the runtime itself
2390
+ * The runtime firewall, persisted in kernl's host storage, and its event
2391
+ * sink into the guard event stream. These report what the runtime itself
2182
2392
  * refused, which is the startup burst and anything over budget when held
2183
2393
  * envelopes are released; what kernl drops before the runtime sees it is
2184
2394
  * reported by kernl's own guard layers.
2185
2395
  *
2186
2396
  * @param options - Host storage, the guard event sink and a clock.
2187
- * @returns `firewallPersistence` and `onFirewallEvent` for the `ShellAdapter`.
2397
+ * @returns `legacyFirewall` and `onFirewallEvent` for the `ShellAdapter`.
2188
2398
  * @example
2189
2399
  * ```ts
2190
2400
  * const hooks = createRuntimeFirewallHooks({ storage: localStorage, onEvent: (event) => log.push(event) });
2191
2401
  * const adapter: ShellAdapter = { ...rest, ...hooks };
2402
+ * applyRuntimeFirewallProfile(hooks.legacyFirewall, createGuardConfig('strict'));
2192
2403
  * ```
2193
2404
  */
2194
2405
  declare function createRuntimeFirewallHooks(options: RuntimeFirewallHooksOptions): RuntimeFirewallHooks;
@@ -2868,6 +3079,39 @@ declare function askUploadConsent(host: Pick<KernlHost, 'presentConsent'>, apple
2868
3079
  */
2869
3080
  declare function createBlossomUploader(options: BlossomUploaderOptions): Uploader;
2870
3081
 
3082
+ /** What the social actions need from the shell. */
3083
+ interface CommonActionsOptions {
3084
+ readonly store: EventStore;
3085
+ readonly profiles: Pick<Profiles, 'settled'>;
3086
+ /** The signed-in account's key, or none. */
3087
+ readonly pubkey: () => string | undefined;
3088
+ /** The account's signer, or none for a read-only session. */
3089
+ readonly signer: () => Pick<ISigner, 'signEvent'> | undefined;
3090
+ /** The shell's signing gate: destructive changes, such as a new follow list, are put to the person first. */
3091
+ readonly consent: SigningConsent;
3092
+ /** Publishes a signed event and resolves how many relays accepted it; rejects when none did (D-028). */
3093
+ readonly publish: (event: NostrEvent) => Promise<number>;
3094
+ /** Loads the account's current follow list into the store before it is changed. */
3095
+ readonly loadFollows: (pubkey: string) => Promise<void>;
3096
+ }
3097
+ /**
3098
+ * kernl's NAP-COMMON hooks for kehto's `createCommonService`: profiles and
3099
+ * follows to read, and follow, unfollow, react and report to write, all on the
3100
+ * person's behalf. Reads are public data. A follow-list change replaces part
3101
+ * of the person's public record, so it passes the shell's signing gate and is
3102
+ * shown to them as what it changes; reactions and reports are posts. Every
3103
+ * write succeeds when any relay accepts it (D-028). A read-only session
3104
+ * cannot write (D-035).
3105
+ *
3106
+ * @param options - Store, profiles, account, signer, signing gate, publisher and follow-list loader.
3107
+ * @returns Options for `createCommonService`.
3108
+ * @example
3109
+ * ```ts
3110
+ * registry.common = createCommonService(createCommonActions({ store, profiles, pubkey, signer, consent, publish, loadFollows }));
3111
+ * ```
3112
+ */
3113
+ declare function createCommonActions(options: CommonActionsOptions): CommonServiceOptions;
3114
+
2871
3115
  /** The parts of the shell that know people and servers: the event cache, the loader over it, profiles, mailboxes and the directory. */
2872
3116
  interface KernlNetwork {
2873
3117
  readonly eventCache: ConnectedEventCache;
@@ -2905,6 +3149,242 @@ interface KernlNetworkParts {
2905
3149
  * ```
2906
3150
  */
2907
3151
  declare function createKernlNetwork(options: Pick<KernlOptions, 'eventCache'>, parts: KernlNetworkParts): KernlNetwork;
3152
+ /**
3153
+ * The social actions the shell offers applets, over the composed network:
3154
+ * profiles from the profile service, the account's follow list loaded before
3155
+ * it changes, writes signed through the signing gate and published to the
3156
+ * tier for their kind (D-035).
3157
+ *
3158
+ * @param parts - The store, pool, tiers and accounts.
3159
+ * @param network - The composed network.
3160
+ * @param consent - The shell's signing gate.
3161
+ * @returns Options for kehto's `createCommonService`.
3162
+ * @example
3163
+ * ```ts
3164
+ * createKernlServices({ ..., common: commonActionsFor(parts, network, consent) });
3165
+ * ```
3166
+ */
3167
+ declare function commonActionsFor(parts: Omit<KernlNetworkParts, 'destroyed$'>, network: Pick<KernlNetwork, 'profiles' | 'replaceableLoader' | 'signer'>, consent: SigningConsent): CommonServiceOptions;
3168
+
3169
+ /** A key per applet window that belongs to no account. */
3170
+ interface WindowIdentities {
3171
+ /** The window's signer, made the first time the window needs one. */
3172
+ signer(windowId: string): PrivateKeySigner;
3173
+ /** Wipe the window's key. The next use makes a new one. */
3174
+ release(windowId: string): void;
3175
+ }
3176
+ /**
3177
+ * Keys for the work a window does under its own name rather than the account's:
3178
+ * calling remote tools and reaching other people directly. Each window gets a
3179
+ * fresh key, so a server or a peer cannot link two applets, or one applet to
3180
+ * the account. The key lives in an applesauce signer, is never stored, and is
3181
+ * overwritten with zeros when the window ends (D-041).
3182
+ *
3183
+ * @returns The window identities.
3184
+ * @example
3185
+ * ```ts
3186
+ * const identities = createWindowIdentities();
3187
+ * const pubkey = await identities.signer('w1').getPublicKey();
3188
+ * identities.release('w1');
3189
+ * ```
3190
+ */
3191
+ declare function createWindowIdentities(): WindowIdentities;
3192
+
3193
+ /** What the remote tools service needs from the shell. */
3194
+ interface RemoteToolsOptions {
3195
+ readonly pool: ApplesaucePool;
3196
+ /** Where a tool server is looked for when the applet names no relay for it; read when a window first calls one. */
3197
+ readonly relays: () => readonly string[];
3198
+ readonly identities: WindowIdentities;
3199
+ /** Tool families the host and the person vouch for, pinned to verified schemas; read when a window first calls one. */
3200
+ readonly registry?: () => readonly CvmRegistryFamily[];
3201
+ }
3202
+ /**
3203
+ * The host's tool families and the person's together. The person's family
3204
+ * takes the place of the host's with the same label and provider, so what
3205
+ * they chose is what an applet asking by that label reaches (D-043).
3206
+ *
3207
+ * @param host - Families from `KernlOptions.remoteTools.registry`.
3208
+ * @param own - Families the person trusts.
3209
+ * @returns The families the tool service offers.
3210
+ * @example
3211
+ * ```ts
3212
+ * mergeFamilies(options.remoteTools?.registry ?? [], kernl.multiplayer.state().families);
3213
+ * ```
3214
+ */
3215
+ declare function mergeFamilies(host: readonly CvmRegistryFamily[], own: readonly CvmRegistryFamily[]): CvmRegistryFamily[];
3216
+ /**
3217
+ * kehto's tool transport over the shell's one pool. A request is published to
3218
+ * every relay and succeeds when any accepts it (D-028).
3219
+ *
3220
+ * @param pool - The shared applesauce pool.
3221
+ * @returns The relay surface `createNostrCvmTransport` takes.
3222
+ * @example
3223
+ * ```ts
3224
+ * createNostrCvmTransport({ pool: createCvmRelayPool(pool), defaultRelays });
3225
+ * ```
3226
+ */
3227
+ declare function createCvmRelayPool(pool: ApplesaucePool): CvmRelayPool;
3228
+ /**
3229
+ * The `cvm` service: applets call tools on remote servers through the shell.
3230
+ *
3231
+ * Each window gets a kehto tool service of its own, with a transport that
3232
+ * calls as that window's key (D-041). Two applets that use the same server
3233
+ * neither share a client key nor receive each other's server events, and no
3234
+ * call is made as the account. When the window ends, its transport closes and
3235
+ * its key is wiped.
3236
+ *
3237
+ * @param options - Pool, default relays, window identities and an optional registry.
3238
+ * @returns The service handler to register as `cvm`.
3239
+ * @example
3240
+ * ```ts
3241
+ * registry.cvm = createRemoteToolsService({ pool, relays: () => tiers.get().super, identities });
3242
+ * ```
3243
+ */
3244
+ declare function createRemoteToolsService(options: RemoteToolsOptions): ServiceHandler;
3245
+
3246
+ /** What the direct connections service needs from the shell. */
3247
+ interface DirectConnectionsOptions {
3248
+ readonly pool: ApplesaucePool;
3249
+ /** Where people in a room find each other; read when a window first opens a session. */
3250
+ readonly relays: () => readonly string[];
3251
+ readonly identities: WindowIdentities;
3252
+ /** STUN and TURN servers that help connections through; read when a window first opens a session. */
3253
+ readonly iceServers: () => readonly DirectIceServer[];
3254
+ /** Makes a peer connection; the page's `RTCPeerConnection` by default. */
3255
+ readonly createPeer?: (configuration: RTCConfiguration) => RTCPeerConnection;
3256
+ /** The verified applet a window runs, or undefined. */
3257
+ readonly appletOf: (windowId: string) => Pick<AppletSummary, 'identity' | 'publisher' | 'manifest'> | undefined;
3258
+ /** Whether the person granted this window's applet direct connections, and has not blocked it. */
3259
+ readonly isGranted: (windowId: string) => boolean;
3260
+ /** Put the summary to the person; resolve true only on yes. */
3261
+ readonly ask: (summary: ConsentSummary) => Promise<boolean>;
3262
+ }
3263
+ /**
3264
+ * The stable address rooms are kept apart by: the publisher, the manifest
3265
+ * kind and the applet's name, the same for every version. Paja derives the
3266
+ * same string, so one applet meets the same rooms in either shell when both
3267
+ * introduce people through the same servers.
3268
+ *
3269
+ * @param summary - The verified applet.
3270
+ * @returns `<publisher>:<kind>:<name>`.
3271
+ * @example
3272
+ * ```ts
3273
+ * directNamespace(summary); // 'ab12…:35129:chess'
3274
+ * ```
3275
+ */
3276
+ declare function directNamespace(summary: Pick<AppletSummary, 'publisher' | 'manifest'>): string;
3277
+ /**
3278
+ * The consent prompt for one direct session: who it reaches, what they learn
3279
+ * about the person, what the shell cannot see, and which servers introduce
3280
+ * the two sides. A direct connection hands the other side the person's
3281
+ * network address, and what passes over it is out of the shell's sight, so
3282
+ * the prompt says both plainly.
3283
+ *
3284
+ * @param requirements - What kehto's WebRTC service planned for the session.
3285
+ * @param applet - The applet asking.
3286
+ * @returns The summary the host renders.
3287
+ * @example
3288
+ * ```ts
3289
+ * describeDirectConnection(requirements, identity).title; // 'Connect directly to other people'
3290
+ * ```
3291
+ */
3292
+ declare function describeDirectConnection(requirements: readonly PermissionRequirement[], applet: AppletIdentity): ConsentSummary;
3293
+ /**
3294
+ * The `webrtc` service: applets open direct sessions with other people.
3295
+ *
3296
+ * Each window gets kehto's WebRTC service over {@link createDirectSignaling},
3297
+ * signing under the window's own key. kehto opens a session only through the
3298
+ * runtime's approval step, which kernl supplies here instead of kehto's
3299
+ * permission authority: the window's applet must hold the `webrtc` grant, the
3300
+ * person is asked once per session, and the session's work stops when the
3301
+ * window ends, its grant changes or the person says no (D-042). Upstream
3302
+ * gap: kehto's ACL has no capability for `webrtc`, so the grant is checked
3303
+ * here, not by the ACL.
3304
+ *
3305
+ * @param options - Pool, relays, identities, ICE servers, peer factory and the grant and consent hooks.
3306
+ * @returns The service handler to register as `webrtc`.
3307
+ * @example
3308
+ * ```ts
3309
+ * registry.webrtc = createDirectConnectionsService({ pool, relays, identities, iceServers: [], createPeer, appletOf, isGranted, ask });
3310
+ * ```
3311
+ */
3312
+ declare function createDirectConnectionsService(options: DirectConnectionsOptions): ServiceHandler;
3313
+
3314
+ /**
3315
+ * The signaling format, shared with Paja so one applet meets the same rooms in
3316
+ * either shell when both introduce people through the same servers.
3317
+ *
3318
+ * @example
3319
+ * ```ts
3320
+ * JSON.parse(signal.content).v === DIRECT_SIGNALING_PROFILE; // a hello carries the format it speaks
3321
+ * ```
3322
+ */
3323
+ declare const DIRECT_SIGNALING_PROFILE = "soy-rtc/1";
3324
+ /**
3325
+ * The event kind signals travel in.
3326
+ *
3327
+ * @example
3328
+ * ```ts
3329
+ * const filter = { kinds: [DIRECT_SIGNAL_KIND], '#d': [wire] };
3330
+ * ```
3331
+ */
3332
+ declare const DIRECT_SIGNAL_KIND = 25050;
3333
+ /**
3334
+ * The largest JSON payload one message may carry, in bytes.
3335
+ *
3336
+ * @example
3337
+ * ```ts
3338
+ * new TextEncoder().encode(JSON.stringify(payload)).length <= DIRECT_MAX_PAYLOAD_BYTES; // else the send is refused
3339
+ * ```
3340
+ */
3341
+ declare const DIRECT_MAX_PAYLOAD_BYTES = 16384;
3342
+ /** The window's own signer: a key that belongs to no account. */
3343
+ interface SignalSigner {
3344
+ getPublicKey(): Promise<string>;
3345
+ signEvent(template: EventTemplate): Promise<NostrEvent>;
3346
+ readonly nip44: {
3347
+ encrypt(pubkey: string, plaintext: string): Promise<string>;
3348
+ decrypt(pubkey: string, ciphertext: string): Promise<string>;
3349
+ };
3350
+ }
3351
+ /** Where signals are published and read. */
3352
+ interface SignalRelay {
3353
+ subscribe(relays: readonly string[], filters: NostrFilter[], onEvent: (event: NostrEvent) => void): {
3354
+ close(): void;
3355
+ };
3356
+ publish(relays: readonly string[], event: NostrEvent): Promise<void>;
3357
+ }
3358
+ /** What one window's direct connections run on. */
3359
+ interface DirectSignalingOptions {
3360
+ readonly signer: SignalSigner;
3361
+ /** The applet's stable address; rooms of different applets never meet. */
3362
+ readonly namespace: string;
3363
+ readonly relays: readonly string[];
3364
+ readonly relay: SignalRelay;
3365
+ /** STUN and TURN addresses the host configured, approved with the session. */
3366
+ readonly iceEndpoints: readonly string[];
3367
+ readonly createPeer: () => RTCPeerConnection;
3368
+ }
3369
+ /**
3370
+ * kehto's WebRTC hooks for one window, speaking the `soy-rtc/1` signaling
3371
+ * format over the shell's pool.
3372
+ *
3373
+ * Signals are signed by the window's own key and carry the session's room
3374
+ * address, never the account. Offers and answers are encrypted to the one
3375
+ * peer they are for. Application data goes only through the data channel;
3376
+ * delivery is reliable and ordered, and a peer that asks for otherwise is
3377
+ * left out. A message is at most 16 KiB of JSON; at most four sessions per
3378
+ * window and eight peers per session (D-042).
3379
+ *
3380
+ * @param options - The window's signer and namespace, the relays, and the peer factory.
3381
+ * @returns Options for kehto's `createWebrtcService`.
3382
+ * @example
3383
+ * ```ts
3384
+ * createWebrtcService(createDirectSignaling({ signer, namespace, relays, relay, iceEndpoints: [], createPeer }));
3385
+ * ```
3386
+ */
3387
+ declare function createDirectSignaling(options: DirectSignalingOptions): WebrtcServiceOptions;
2908
3388
 
2909
3389
  /**
2910
3390
  * Whether a host-supplied theme has the colours NAP-THEME requires.
@@ -2939,6 +3419,10 @@ interface KernlServiceDeps {
2939
3419
  readonly host: Pick<KernlHost, 'notify' | 'openLink'>;
2940
3420
  readonly bridges: BridgeRegistry;
2941
3421
  readonly messaging: MessagingRegistry;
3422
+ /** Applet settings (NAP-CONFIG); without them the `config` domain is not offered. */
3423
+ readonly config?: ConfigServiceOptions;
3424
+ /** Social actions for applets (NAP-COMMON); without them the `common` domain is not offered. */
3425
+ readonly common?: CommonServiceOptions;
2942
3426
  /** Uploads for applets (NAP-UPLOAD); without it the `upload` domain is not offered. */
2943
3427
  readonly uploader?: Uploader;
2944
3428
  /** Names conversation participants for applets; without it they are listed by key alone. */
@@ -2951,6 +3435,18 @@ interface KernlServiceDeps {
2951
3435
  } | null;
2952
3436
  /** Identity lookups; defaults to the applesauce-backed providers. */
2953
3437
  readonly identity?: IdentityProviders;
3438
+ /** Keys for the work a window does under its own name; a fresh set by default (D-041). */
3439
+ readonly identities?: WindowIdentities;
3440
+ /** Where remote tools are looked for and which families the host vouches for. */
3441
+ readonly remoteTools?: RemoteToolsSettings | undefined;
3442
+ /** Direct connections; without them the `webrtc` domain is not offered (D-042). */
3443
+ readonly directConnections?: DirectConnectionsDeps | undefined;
3444
+ /** The person's own choices, which come before the host's (D-043). */
3445
+ readonly multiplayer?: Pick<MultiplayerSettings, 'state'>;
3446
+ }
3447
+ /** What the `webrtc` service needs beyond the pool and the window identities. */
3448
+ interface DirectConnectionsDeps extends Pick<DirectConnectionsOptions, 'createPeer' | 'appletOf' | 'isGranted' | 'ask'> {
3449
+ readonly settings: Omit<DirectConnectionsSettings, 'createPeer'>;
2954
3450
  }
2955
3451
  /** The registered services plus the handles the shell keeps calling. */
2956
3452
  interface KernlServices {
@@ -2974,11 +3470,12 @@ declare function resourceInitFor(deps: Pick<KernlServiceDeps, 'resolveIdentity'>
2974
3470
  /**
2975
3471
  * Register kehto's reference services over the shell's applesauce layer.
2976
3472
  *
2977
- * `relay`, `identity`, `theme`, `notify`, `link`, `resource`, `dm` and `outbox`
2978
- * are wired; every network path goes through the one pool, every resource
2979
- * fetch through the bridge registry's SSRF policy, links open only over
2980
- * `https:` and `mailto:`, notifications surface through the host, and outbox
2981
- * publishes pass the consent gate before they are signed.
3473
+ * `relay`, `identity`, `theme`, `notify`, `link`, `resource`, `dm`, `outbox`
3474
+ * and `cvm` are wired; every network path goes through the one pool, every
3475
+ * resource fetch through the bridge registry's SSRF policy, links open only
3476
+ * over `https:` and `mailto:`, notifications surface through the host, outbox
3477
+ * publishes pass the consent gate before they are signed, and remote tools are
3478
+ * called under each window's own key.
2982
3479
  *
2983
3480
  * @param deps - Pool, tiers, store, auth, consent gate, host, registries and identity resolver.
2984
3481
  * @returns The service registry and the theme and dm handles.
@@ -3039,6 +3536,8 @@ interface LifecycleContext {
3039
3536
  readonly adapter: ShellAdapter;
3040
3537
  readonly bridge: ShellBridge;
3041
3538
  readonly pipeline: GuardPipeline;
3539
+ /** The runtime firewall kernl constructed; mounting installs the applet's rates in it. */
3540
+ readonly firewall: RuntimeFirewallState;
3042
3541
  readonly grants: KernlGrants;
3043
3542
  /** Every planned applet is installed, so others can hand it work. */
3044
3543
  readonly installed: InstalledApplets;
@@ -3051,6 +3550,27 @@ interface LifecycleContext {
3051
3550
  /** Applets the host ships with itself. */
3052
3551
  readonly builtins: readonly BuiltinApplet[];
3053
3552
  }
3553
+ /**
3554
+ * Why a grant change stops a running window, or nothing when it does not.
3555
+ *
3556
+ * A window keeps the environment it was started with, and `shell.init` is not
3557
+ * sent again, so a window whose grant no longer covers a domain it was started
3558
+ * with would go on advertising it. Granting more never stops a window; the
3559
+ * applet sees the new domain the next time it opens.
3560
+ *
3561
+ * @param plan - The running window's plan; its environment is what it was started with.
3562
+ * @param record - The grant record that just changed.
3563
+ * @param baseline - Domains every applet holds, from `grants.baselineDomains()`.
3564
+ * @returns `blocked`, `grant-narrowed`, or `undefined` when the window may keep running.
3565
+ * @example
3566
+ * ```ts
3567
+ * grants.changes$.subscribe((record) => {
3568
+ * const reason = grantNarrowingReason(plan, record, grants.baselineDomains());
3569
+ * if (reason) handle.revoked(reason);
3570
+ * });
3571
+ * ```
3572
+ */
3573
+ declare function grantNarrowingReason(plan: MountPlan, record: GrantRecord, baseline: readonly string[]): 'blocked' | 'grant-narrowed' | undefined;
3054
3574
  /** The applet half of {@link Kernl}. */
3055
3575
  type AppletLifecycle = Pick<Kernl, 'resolve' | 'install' | 'plan' | 'mount' | 'applets' | 'handleWindowMessage'>;
3056
3576
  /**
@@ -3323,4 +3843,4 @@ declare const PACKAGE_NAME = "@kernlize/core";
3323
3843
  */
3324
3844
  declare const KERNL_FRAME_POLICY_META: string;
3325
3845
 
3326
- export { type AccountFileServers, type AccountFileServersOptions, type AccountMailboxes, type AccountMailboxesOptions, type ApplesaucePool, type AppletCatalog, 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, ConnectedEventCache, type ConsentLine, type ConsentPrompt, type ConsentSummary, DEFAULT_FILE_SERVERS, DEFAULT_MONITOR_RELAYS, DEFAULT_RELAY_TIERS, DEFAULT_SUGGESTIONS, DELIVERY_RETRY, DOMAIN_CAPABILITIES, type DefaultBridgesOptions, type DefaultMessagingOptions, 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 KernlNetwork, type KernlNetworkParts, type KernlOptions, type KernlServiceDeps, type KernlServices, LINK_PROTOCOLS, type LifecycleContext, type LoadCatalogOptions, type LookupBefore, type LookupReplaceableOptions, MANIFEST_TIMING, 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 NamespacedStore, type OutboxRelayPoolLike, PACKAGE_NAME, PLAINTEXT_KEY_ACCOUNT_TYPES, 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 ResolveAppletIdentity, type ResolveAppletOptions, type ResolvedApplet, type RuntimeFirewallHooks, type RuntimeFirewallHooksOptions, type RuntimeFirewallRules, type RuntimeFirewallState, type RuntimeRateRule, type SealedGroupStoreOptions, type SealedRatchetStorageOptions, type Session, type ShellAdapterDeps, type SignerMessagingOptions, type SigningConsent, type SigningConsentOptions, type SigningTemplate, type StorageLike, type SuggestOptions, type SuggestPurpose, type TierMap, type TopicCount, UNKNOWN_CURRENT_VERSION, type UploadDetails, type WindowResolution, abbreviate, addressOf, applyRuntimeFirewallProfile, applyRuntimeFirewallRules, askUploadConsent, builtinAddress, capabilitiesForDomain, capabilitiesForDomains, catalogIdForRef, catalogRelays, createAccountFileServers, createAccountMailboxes, createAppletLifecycle, createAppletRelayBackend, createAuthHooks, createBlossomUploader, createConsentHandler, createDefaultBridges, createDefaultMessaging, createDmRelayPool, createEnvironmentResolver, createGrants, createGroupMessagesBackend, createGroupNetwork, createGuardPipeline, createHandlerDefaults, createIdentityProviders, createInstalledApplets, createIntentDelivery, createIntentRouter, createKernl, createKernlAccounts, createKernlIntents, createKernlNetwork, createKernlServices, createLegacyMessagesBackend, createNamespacedStore, createOutboxRelayPool, createPrivateMessagesBackend, createProfiles, createRatchetMessagesBackend, createRelayDirectory, createRelayPoolHooks, createRelayPoolLike, createRelayTiers, createReplaceableLoader, createRuntimeFirewallHooks, createSealedGroupStore, createSealedRatchetStorage, createShellAdapter, createSigningConsent, decodePointer, defaultFetchBlob, describeChange, describeOutcome, describeUpload, fetchManifestEvent, fileServerTags, fileServersFromEvent, fuzzyScore, isDestructiveKind, isReadOnlyAccount, isTheme, labelConversations, loadCatalog, lookupRelaysOf, lookupReplaceable, mailboxTags, mailboxesFromEvent, messagingSigner, mountApplet, newestEntries, openDefaultArtifactCache, parseHandlerPreferences, planMount, popularTopics, preferenceRelays, preferenceTemplate, preferredHandlers, publishAccepted, refForCatalogId, relayUrls, resolveApplet, resolveBuiltin, resolveWindow, resourceInitFor, runtimeFirewallRules, searchCatalog, selectRelayTier, signerAvailability, sizeWords, streamCatalog, subscribeWithEose, summarize, summarizePublish, toCatalogEntry, toGuardEvent, toProfileCard, toRelayUrl, toSession, wrapAccountSigner };
3846
+ 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, 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, PLAINTEXT_KEY_ACCOUNT_TYPES, 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, TOOL_DISCOVERY_TIMEOUT_MS, 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, 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, createPrivateMessagesBackend, createProfiles, createRatchetMessagesBackend, createRelayDirectory, createRelayPoolHooks, createRelayPoolLike, createRelayTiers, createRemoteToolsService, createReplaceableLoader, createRuntimeFirewallHooks, createSealedGroupStore, createSealedRatchetStorage, createShellAdapter, createSigningConsent, createWindowIdentities, decodePointer, defaultFetchBlob, describeChange, describeDirectConnection, describeOutcome, describeUpload, directNamespace, discoverToolFamilies, fetchManifestEvent, fileServerTags, fileServersFromEvent, fuzzyScore, grantNarrowingReason, isDestructiveKind, isReadOnlyAccount, isTheme, labelConversations, loadCatalog, lookupRelaysOf, lookupReplaceable, mailboxTags, mailboxesFromEvent, mergeFamilies, messagingSigner, mountApplet, newestEntries, openDefaultArtifactCache, parseHandlerPreferences, planMount, popularTopics, preferenceRelays, preferenceTemplate, preferredHandlers, publishAccepted, refForCatalogId, relayUrls, resolveApplet, resolveBuiltin, resolveWindow, resourceInitFor, runtimeFirewallRules, searchCatalog, selectRelayTier, signerAvailability, sizeWords, streamCatalog, subscribeWithEose, summarize, summarizePublish, toCatalogEntry, toGuardEvent, toProfileCard, toRelayUrl, toSession, validFamily, wrapAccountSigner };