@kernlize/core 0.10.0 → 0.12.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,19 +1,19 @@
1
1
  import { Observable, Subscription } from 'rxjs';
2
2
  import { EventStore } from 'applesauce-core';
3
3
  import { RelayPool, RelayPoolOptions } from 'applesauce-relay';
4
- import { AccountManager, IAccount } from 'applesauce-accounts';
4
+ import { AccountManager, IAccount, BaseAccount, SerializedAccount } from 'applesauce-accounts';
5
5
  import { RelayPoolHooks, RelayPoolLike, ShellBridge, ShellEnvironment, AuthHooks, ShellAdapter, OriginRegistry, NappletMessageDecision, CapabilityHooks, NappletRevocation, UnroutedMessageInfo } from '@kehto/shell';
6
- import { Capability, RelayPlanningServiceHandler, ConsentRequest, Signer, FirewallEvent, 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 { ConfigSettingsContext, ConfigServiceOptions, IntentCatalogEntry, RelayPoolServiceOptions, DmRelayPool, IdentityServiceOptions, DmAdapter, Uploader, CommonServiceOptions, ThemeService, DmService, ResourceFetchInit, IntentResolver, IntentDispatchParams } from '@kehto/services';
17
17
  import { AddressPointerLoader } from 'applesauce-loaders/loaders';
18
18
  import { CacheRequest } from 'applesauce-loaders';
19
19
  import { FirewallStateContainer, RateLimit } from '@kehto/rate-limit/legacy';
@@ -23,9 +23,196 @@ export { CryptoFallbackReport, CryptoScope, createFallbackSubtle, installCryptoF
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. */
@@ -159,6 +346,79 @@ declare function toProfileCard(pubkey: string, event: NostrEvent | undefined): P
159
346
  */
160
347
  declare function createProfiles(options: ProfilesOptions): Profiles;
161
348
 
349
+ /** A person, and where whoever shared them said their data is kept. */
350
+ interface PersonPointer {
351
+ /** The identity, as 64 lowercase hex characters. */
352
+ readonly pubkey: string;
353
+ /** Servers named alongside the identity; empty when none were. */
354
+ readonly relays: readonly string[];
355
+ }
356
+ /**
357
+ * The longest the hinted servers are waited for before a lookup goes on
358
+ * without them. An outer bound only: it ends as soon as they have all answered.
359
+ *
360
+ * @example
361
+ * ```ts
362
+ * createPeople({ store, pool, timeoutMs: PERSON_HINT_TIMEOUT_MS });
363
+ * ```
364
+ */
365
+ declare const PERSON_HINT_TIMEOUT_MS = 8000;
366
+ /**
367
+ * Read an identity out of what someone typed, pasted or was sent.
368
+ *
369
+ * Every NIP-19 form of a person is one: 64 hex characters, an `npub`, or an
370
+ * `nprofile`, with or without a `nostr:` prefix and in any case. An
371
+ * `nprofile` carries the servers its data is on, which come back as `relays`.
372
+ *
373
+ * @param input - The text.
374
+ * @returns The person, or `undefined` when the text is none of those.
375
+ * @example
376
+ * ```ts
377
+ * parsePerson('npub1…'); // { pubkey: '3bf0…', relays: [] }
378
+ * parsePerson('nostr:nprofile1…'); // { pubkey: '3bf0…', relays: ['wss://relay.example'] }
379
+ * parsePerson('hello'); // undefined
380
+ * ```
381
+ */
382
+ declare function parsePerson(input: string): PersonPointer | undefined;
383
+ /** Options for {@link createPeople}. */
384
+ interface PeopleOptions {
385
+ /** The shell's event store; what the hinted servers hold is put here, where every lookup reads first. */
386
+ readonly store: EventStore;
387
+ readonly pool: ApplesaucePool;
388
+ /** Outer bound on waiting for the hinted servers; {@link PERSON_HINT_TIMEOUT_MS} by default. */
389
+ readonly timeoutMs?: number;
390
+ }
391
+ /** Finds people from any form of their identity. */
392
+ interface People {
393
+ /** Read an identity; `undefined` when the text is not one. Asks nobody. */
394
+ parse(input: string): PersonPointer | undefined;
395
+ /**
396
+ * Read an identity and, when it names servers, fetch the person's profile,
397
+ * server list and message inboxes from them first, so whatever looks the
398
+ * person up next finds them.
399
+ *
400
+ * @throws `invalid:person` when the text is not an identity.
401
+ */
402
+ locate(input: string): Promise<string>;
403
+ }
404
+ /**
405
+ * Create the shell's way of finding a person from what was typed or sent.
406
+ *
407
+ * The servers an `nprofile` names are asked once per person and set of
408
+ * servers, and what they hold is added to the shell's event store. A server
409
+ * that fails or says nothing costs nothing: the lookup goes on with the
410
+ * shell's own servers, as it would have without the hint.
411
+ *
412
+ * @param options - The event store, the pool and the outer bound.
413
+ * @returns The finder.
414
+ * @example
415
+ * ```ts
416
+ * const people = createPeople({ store: eventStore, pool });
417
+ * const pubkey = await people.locate('nprofile1…');
418
+ * ```
419
+ */
420
+ declare function createPeople(options: PeopleOptions): People;
421
+
162
422
  /**
163
423
  * Servers that carry NIP-66 monitors' reports: the ones nostr.watch's own
164
424
  * client reads. Its history server is left out: its certificate does not
@@ -452,96 +712,6 @@ declare function mailboxTags(mailboxes: Mailboxes, previous?: NostrEvent$1): str
452
712
  */
453
713
  declare function createAccountMailboxes(options: AccountMailboxesOptions): AccountMailboxes;
454
714
 
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
- /**
458
- * How the shell's own pool redials a relay that refused the connection.
459
- *
460
- * applesauce-relay 7.1 redials refused connections three times by default,
461
- * pausing one, two and three seconds, and a publish waits for every relay it
462
- * was sent to, so one dead relay in a tier held a publish for about six
463
- * seconds. One redial after a second keeps the case it exists for: a busy
464
- * public relay answers a websocket upgrade with 502 or 503 for a moment and
465
- * accepts the next one (D-025, D-037). Subscriptions keep applesauce's
466
- * default, because a live subscription should come back after a drop.
467
- *
468
- * @example
469
- * ```ts
470
- * const pool = new RelayPool(SHELL_RELAY_OPTIONS);
471
- * ```
472
- */
473
- declare const SHELL_RELAY_OPTIONS: RelayPoolOptions;
474
- /** A subscription that delivers events once each and signals the end of stored events. */
475
- interface EoseSubscription {
476
- unsubscribe(): void;
477
- }
478
- /**
479
- * Subscribe through the pool's raw `req` so the end of stored events is
480
- * observable: `EOSE` is reported once, after every relay has answered or
481
- * failed, and events are deduplicated by id because `req` does not.
482
- * applesauce's `subscription()` deduplicates but hides `EOSE`, which kehto's
483
- * relay service relies on to answer `relay.subscribe`.
484
- *
485
- * @param pool - The shared applesauce pool.
486
- * @param relays - Relay URLs to ask.
487
- * @param filters - Filters for the request.
488
- * @param callback - Receives each new event once, then `'EOSE'`.
489
- * @returns A handle that closes the subscription.
490
- * @example
491
- * ```ts
492
- * const sub = subscribeWithEose(pool, ['wss://relay.example'], [{ kinds: [1] }], (item) => {
493
- * if (item !== 'EOSE') console.log(item.id);
494
- * });
495
- * sub.unsubscribe();
496
- * ```
497
- */
498
- declare function subscribeWithEose(pool: Pick<ApplesaucePool, 'req'>, relays: string[], filters: NostrFilter[], callback: (item: NostrEvent | 'EOSE') => void): EoseSubscription;
499
- /**
500
- * Adapt the shared applesauce `RelayPool` to kehto's `RelayPoolLike`.
501
- *
502
- * @param pool - The one pool the shell owns (D-002).
503
- * @returns An object kehto's `RelayPoolHooks.getRelayPool` can return.
504
- * @example
505
- * ```ts
506
- * const like = createRelayPoolLike(pool);
507
- * like.subscription(['wss://relay.example'], [{ kinds: [1] }]).subscribe((item) => {});
508
- * ```
509
- */
510
- declare function createRelayPoolLike(pool: ApplesaucePool): RelayPoolLike;
511
- /**
512
- * Choose the relay tier for a set of filters.
513
- *
514
- * Profiles, follow lists and relay lists come from the discovery tier; applet
515
- * manifests from the apps tier; everything else goes to the user's outbox
516
- * relays plus the super tier. A filter without kinds cannot be classified and
517
- * takes the general path.
518
- *
519
- * @param tiers - The current tier configuration.
520
- * @param filters - Filters about to be sent.
521
- * @returns Relay URLs, deduplicated.
522
- * @example
523
- * ```ts
524
- * selectRelayTier(tiers, [{ kinds: [0], authors: [pubkey] }]); // discovery, then outbox and super
525
- * ```
526
- */
527
- declare function selectRelayTier(tiers: RelayTiers, filters: readonly NostrFilter[]): string[];
528
- /**
529
- * Build kehto's `RelayPoolHooks` over the shared applesauce pool.
530
- *
531
- * Scoped relays (one relay per window, the NIP-29 pattern) are kept minimal:
532
- * one open subscription per window, replaced on reopen, and events delivered
533
- * to the window's bound port as `relay.event` envelopes.
534
- *
535
- * @param pool - The shared applesauce pool.
536
- * @param tiers - Relay tiers used for `selectRelayTier`.
537
- * @returns Hooks for `ShellAdapter.relayPool`.
538
- * @example
539
- * ```ts
540
- * const adapter: ShellAdapter = { relayPool: createRelayPoolHooks(pool, tiers), ... };
541
- * ```
542
- */
543
- declare function createRelayPoolHooks(pool: ApplesaucePool, tiers: RelayTiers): RelayPoolHooks;
544
-
545
715
  /**
546
716
  * File servers to use when the account has not published its own list: public
547
717
  * Blossom servers that answered an upload preflight when this was chosen.
@@ -1090,6 +1260,8 @@ interface GrantRecord {
1090
1260
  readonly identity: AppletIdentity;
1091
1261
  readonly domains: readonly string[];
1092
1262
  readonly capabilities: readonly Capability[];
1263
+ /** Domains allowed or baseline that are not in force, because the applet can read messages (D-046). */
1264
+ readonly withheld: readonly string[];
1093
1265
  readonly blocked: boolean;
1094
1266
  readonly stateQuotaBytes: number;
1095
1267
  }
@@ -1119,8 +1291,11 @@ interface ConsentLine {
1119
1291
  /** A write described as what it changes, not as JSON. */
1120
1292
  interface ConsentSummary {
1121
1293
  readonly title: string;
1122
- /** `destructive` replaces or erases part of the record; `public` puts something where anyone can fetch it; both are asked about. */
1123
- readonly severity: 'routine' | 'destructive' | 'public';
1294
+ /**
1295
+ * `destructive` replaces or erases part of the record; `public` puts something where anyone can fetch it;
1296
+ * `direct` connects the person to someone else, who learns their network address. All three are asked about.
1297
+ */
1298
+ readonly severity: 'routine' | 'destructive' | 'public' | 'direct';
1124
1299
  readonly lines: readonly ConsentLine[];
1125
1300
  readonly applet: AppletIdentity;
1126
1301
  /** The raw event, for an "advanced" disclosure. */
@@ -1263,6 +1438,37 @@ interface KernlOptions {
1263
1438
  readonly intervalMs: number;
1264
1439
  readonly attempts: number;
1265
1440
  };
1441
+ /** Where applets' remote tools are looked for, and which tool families the host vouches for (D-041). */
1442
+ readonly remoteTools?: RemoteToolsSettings;
1443
+ /** How applets connect people directly: the relays that introduce them and the ICE servers that help (D-042). */
1444
+ readonly directConnections?: DirectConnectionsSettings;
1445
+ }
1446
+ /** A STUN or TURN server, as `RTCPeerConnection` takes it. Its credentials stay in the shell. */
1447
+ interface DirectIceServer {
1448
+ readonly urls: readonly string[];
1449
+ readonly username?: string;
1450
+ readonly credential?: string;
1451
+ }
1452
+ /** The host's settings for direct connections between people. */
1453
+ interface DirectConnectionsSettings {
1454
+ /** Relays people in a room find each other through; the general (`super`) tier by default. */
1455
+ readonly relays?: readonly string[];
1456
+ /** STUN and TURN servers; none by default, so only people who can reach each other's devices connect. */
1457
+ readonly iceServers?: readonly DirectIceServer[];
1458
+ /** Makes a peer connection; the browser's `RTCPeerConnection` by default. Without either, the `webrtc` domain is not offered. */
1459
+ readonly createPeer?: (configuration: RTCConfiguration) => RTCPeerConnection;
1460
+ }
1461
+ /** The person's settings for meeting people and calling remote tools, kept on this device, and the search for tool families. */
1462
+ interface KernlMultiplayer extends MultiplayerSettings {
1463
+ /** Find tool families from an announcement reference, a schema hash or a website, over the servers in use (D-043). */
1464
+ discover(input: string): Promise<readonly ToolFamilyCandidate[]>;
1465
+ }
1466
+ /** The host's settings for remote tools. */
1467
+ interface RemoteToolsSettings {
1468
+ /** Relays a tool server is looked for on when the applet names none; the general (`super`) tier by default. */
1469
+ readonly relays?: readonly string[];
1470
+ /** Tool families pinned to verified schemas, for applets that ask by family; none by default. */
1471
+ readonly registry?: readonly CvmRegistryFamily[];
1266
1472
  }
1267
1473
  /** The applet store's catalogue. */
1268
1474
  interface AppletCatalog {
@@ -1304,10 +1510,14 @@ interface Kernl {
1304
1510
  readonly catalog: AppletCatalog;
1305
1511
  /** People's names and pictures, loaded from their profiles on demand. */
1306
1512
  readonly profiles: Profiles;
1513
+ /** Finds a person from hex, `npub` or `nprofile`, asking the servers an `nprofile` names. */
1514
+ readonly people: People;
1307
1515
  /** The signed-in account's published inbox and outbox (NIP-65); the `outbox` tier follows its outboxes. */
1308
1516
  readonly mailboxes: AccountMailboxes;
1309
1517
  /** Where the account's uploads go (BUD-03, kind 10063); the defaults while it has no list. */
1310
1518
  readonly files: AccountFileServers;
1519
+ /** The person's servers, helpers and trusted tool families for meeting people and calling remote tools (D-043). */
1520
+ readonly multiplayer: KernlMultiplayer;
1311
1521
  /** Monitored servers (NIP-66) for completing and suggesting; idle until `start()`. */
1312
1522
  readonly directory: RelayDirectory;
1313
1523
  readonly intents: Intents;
@@ -1714,6 +1924,83 @@ declare function createReplaceableLoader(store: EventStore, pool: ApplesaucePool
1714
1924
  */
1715
1925
  declare function createIdentityProviders(store: EventStore, pool: ApplesaucePool, tiers: RelayTiers, options?: IdentityProviderOptions): IdentityProviders;
1716
1926
 
1927
+ /**
1928
+ * The domain that lets an applet read and write the person's private messages.
1929
+ *
1930
+ * @example
1931
+ * ```ts
1932
+ * grants.get(identity)?.domains.includes(MESSAGES_DOMAIN); // the applet is sealed
1933
+ * ```
1934
+ */
1935
+ declare const MESSAGES_DOMAIN = "dm";
1936
+ /**
1937
+ * Every domain an applet may hold together with messages. None of them can
1938
+ * carry what the applet read to anywhere but the person's own screen and
1939
+ * this device: the handshake, messages themselves, which identity is signed
1940
+ * in, the theme, the applet's own storage and settings, notifications,
1941
+ * keyboard shortcuts, and being handed a request by another applet.
1942
+ *
1943
+ * It is an allowlist, so a domain kehto adds later is withheld until it is
1944
+ * put here on purpose (D-046).
1945
+ *
1946
+ * @example
1947
+ * ```ts
1948
+ * MESSAGE_COMPANION_DOMAINS.includes('upload'); // false
1949
+ * ```
1950
+ */
1951
+ declare const MESSAGE_COMPANION_DOMAINS: readonly string[];
1952
+ /**
1953
+ * Whether an applet's grants seal it: it holds messages, so it holds nothing
1954
+ * that could send them on.
1955
+ *
1956
+ * @param granted - The domains the person allowed.
1957
+ * @returns True when messages are among them.
1958
+ * @example
1959
+ * ```ts
1960
+ * sealsApplet(['dm', 'relay']); // true
1961
+ * ```
1962
+ */
1963
+ declare function sealsApplet(granted: readonly string[]): boolean;
1964
+ /**
1965
+ * The domains actually in force for an applet: the baseline plus what the
1966
+ * person allowed, cut down to {@link MESSAGE_COMPANION_DOMAINS} when the
1967
+ * applet holds messages.
1968
+ *
1969
+ * @param granted - The domains the person allowed.
1970
+ * @param baseline - Domains every applet holds; {@link BASELINE_DOMAINS} by default.
1971
+ * @returns The domains in force, baseline first.
1972
+ * @example
1973
+ * ```ts
1974
+ * domainsInForce(['relay']); // ['shell', 'inc', 'theme', 'storage', 'relay']
1975
+ * domainsInForce(['dm', 'relay', 'upload']); // ['shell', 'theme', 'storage', 'dm']
1976
+ * ```
1977
+ */
1978
+ declare function domainsInForce(granted: readonly string[], baseline?: readonly string[]): readonly string[];
1979
+ /**
1980
+ * The domains an applet would hold but for messages: allowed by the person
1981
+ * or part of the baseline, and not in force while it can read messages.
1982
+ *
1983
+ * @param granted - The domains the person allowed.
1984
+ * @param baseline - Domains every applet holds; {@link BASELINE_DOMAINS} by default.
1985
+ * @returns The withheld domains; empty for an applet without messages.
1986
+ * @example
1987
+ * ```ts
1988
+ * withheldDomains(['dm', 'relay']); // ['inc', 'relay']
1989
+ * ```
1990
+ */
1991
+ declare function withheldDomains(granted: readonly string[], baseline?: readonly string[]): readonly string[];
1992
+ /**
1993
+ * The kehto capabilities an applet's grants come to, after the seal.
1994
+ *
1995
+ * @param granted - The domains the person allowed.
1996
+ * @returns The capabilities to write into the runtime ACL.
1997
+ * @example
1998
+ * ```ts
1999
+ * capabilitiesInForce(['dm', 'intent', 'relay']); // dm, baseline and 'intent:read'; no relay, no 'intent:write'
2000
+ * ```
2001
+ */
2002
+ declare function capabilitiesInForce(granted: readonly string[]): readonly Capability[];
2003
+
1717
2004
  /**
1718
2005
  * Account types whose serialised form carries a raw secret. `PrivateKeyAccount`
1719
2006
  * serialises the key itself and `SeedWordsAccount` the mnemonic. Neither may be
@@ -1767,6 +2054,53 @@ declare class KernlAccountManager extends AccountManager {
1767
2054
  */
1768
2055
  declare function createKernlAccounts(storage: StorageLike): AccountManager;
1769
2056
 
2057
+ /**
2058
+ * The type of an identity that is never written down.
2059
+ *
2060
+ * @example
2061
+ * ```ts
2062
+ * account.type === THROWAWAY_IDENTITY_TYPE; // true for createThrowawayIdentity()
2063
+ * ```
2064
+ */
2065
+ declare const THROWAWAY_IDENTITY_TYPE = "throwaway";
2066
+ /**
2067
+ * An identity for trying the shell: a fresh key held by its signer in memory
2068
+ * and nowhere else. It signs like any other, so the live store, applets and
2069
+ * consent all behave as they will for a kept identity. It refuses to be
2070
+ * serialised, so the account manager's persistence skips it and a reload
2071
+ * starts without it (D-044).
2072
+ *
2073
+ * @example
2074
+ * ```ts
2075
+ * const identity = createThrowawayIdentity();
2076
+ * await kernl.login(identity);
2077
+ * ```
2078
+ */
2079
+ declare class ThrowawayIdentity extends BaseAccount<PrivateKeySigner, never, {
2080
+ name: string;
2081
+ }> {
2082
+ static readonly type = "throwaway";
2083
+ /**
2084
+ * Refuse to be written down.
2085
+ *
2086
+ * @throws `denied:plaintext-key-persistence`, always.
2087
+ */
2088
+ toJSON(): SerializedAccount<never, {
2089
+ name: string;
2090
+ }>;
2091
+ }
2092
+ /**
2093
+ * Make an identity that lasts until the page goes away.
2094
+ *
2095
+ * @param name - What the shell calls it until a profile says otherwise.
2096
+ * @returns The identity, ready for `kernl.login`.
2097
+ * @example
2098
+ * ```ts
2099
+ * await kernl.login(createThrowawayIdentity('Just looking'));
2100
+ * ```
2101
+ */
2102
+ declare function createThrowawayIdentity(name?: string): ThrowawayIdentity;
2103
+
1770
2104
  /**
1771
2105
  * Decode what a user typed or clicked into the event to fetch.
1772
2106
  *
@@ -2341,7 +2675,9 @@ interface KernlGrants extends Grants {
2341
2675
  * no entry holds nothing. kernl grants the baseline domains plus what the user
2342
2676
  * allowed, and revokes whatever the applet's entry holds beyond that, which
2343
2677
  * covers a domain the user took back and an entry kept from an earlier
2344
- * posture. The per-identity record is persisted at `kernl:grants:v1`; the ACL
2678
+ * posture. An applet that holds messages is sealed: only the domains that
2679
+ * cannot send what it read anywhere stay in force, and the rest are reported
2680
+ * as `withheld` (D-046). The per-identity record is persisted at `kernl:grants:v1`; the ACL
2345
2681
  * itself is persisted by kehto. Blocking an applet blocks it in the ACL and empties its
2346
2682
  * environment through {@link createEnvironmentResolver}.
2347
2683
  *
@@ -2361,7 +2697,8 @@ declare function createGrants(options: GrantsOptions): KernlGrants;
2361
2697
  * Each applet sees the baseline domains plus the domains the user allowed,
2362
2698
  * intersected with what the shell offers live. kehto intersects again with
2363
2699
  * its own availability set, so this hook can only narrow. A blocked applet
2364
- * sees only `shell`, enough to finish the handshake and nothing more.
2700
+ * sees only `shell`, enough to finish the handshake and nothing more. An
2701
+ * applet that holds messages sees only the domains that may go with them.
2365
2702
  *
2366
2703
  * @param grants - The grants surface the hook reads.
2367
2704
  * @returns The hook, ready for `adapter.capabilities.resolveEnvironment`.
@@ -2950,6 +3287,8 @@ declare function createBlossomUploader(options: BlossomUploaderOptions): Uploade
2950
3287
  interface CommonActionsOptions {
2951
3288
  readonly store: EventStore;
2952
3289
  readonly profiles: Pick<Profiles, 'settled'>;
3290
+ /** Reads a person from any form of their identity, asking the servers it names first; `invalid:person` otherwise. */
3291
+ readonly locate: (input: string) => Promise<string>;
2953
3292
  /** The signed-in account's key, or none. */
2954
3293
  readonly pubkey: () => string | undefined;
2955
3294
  /** The account's signer, or none for a read-only session. */
@@ -2984,6 +3323,7 @@ interface KernlNetwork {
2984
3323
  readonly eventCache: ConnectedEventCache;
2985
3324
  readonly replaceableLoader: AddressPointerLoader;
2986
3325
  readonly profiles: Profiles;
3326
+ readonly people: People;
2987
3327
  readonly directory: RelayDirectory;
2988
3328
  readonly mailboxes: AccountMailboxes;
2989
3329
  readonly files: AccountFileServers;
@@ -3031,7 +3371,227 @@ declare function createKernlNetwork(options: Pick<KernlOptions, 'eventCache'>, p
3031
3371
  * createKernlServices({ ..., common: commonActionsFor(parts, network, consent) });
3032
3372
  * ```
3033
3373
  */
3034
- declare function commonActionsFor(parts: Omit<KernlNetworkParts, 'destroyed$'>, network: Pick<KernlNetwork, 'profiles' | 'replaceableLoader' | 'signer'>, consent: SigningConsent): CommonServiceOptions;
3374
+ declare function commonActionsFor(parts: Omit<KernlNetworkParts, 'destroyed$'>, network: Pick<KernlNetwork, 'profiles' | 'people' | 'replaceableLoader' | 'signer'>, consent: SigningConsent): CommonServiceOptions;
3375
+
3376
+ /** A key per applet window that belongs to no account. */
3377
+ interface WindowIdentities {
3378
+ /** The window's signer, made the first time the window needs one. */
3379
+ signer(windowId: string): PrivateKeySigner;
3380
+ /** Wipe the window's key. The next use makes a new one. */
3381
+ release(windowId: string): void;
3382
+ }
3383
+ /**
3384
+ * Keys for the work a window does under its own name rather than the account's:
3385
+ * calling remote tools and reaching other people directly. Each window gets a
3386
+ * fresh key, so a server or a peer cannot link two applets, or one applet to
3387
+ * the account. The key lives in an applesauce signer, is never stored, and is
3388
+ * overwritten with zeros when the window ends (D-041).
3389
+ *
3390
+ * @returns The window identities.
3391
+ * @example
3392
+ * ```ts
3393
+ * const identities = createWindowIdentities();
3394
+ * const pubkey = await identities.signer('w1').getPublicKey();
3395
+ * identities.release('w1');
3396
+ * ```
3397
+ */
3398
+ declare function createWindowIdentities(): WindowIdentities;
3399
+
3400
+ /** What the remote tools service needs from the shell. */
3401
+ interface RemoteToolsOptions {
3402
+ readonly pool: ApplesaucePool;
3403
+ /** Where a tool server is looked for when the applet names no relay for it; read when a window first calls one. */
3404
+ readonly relays: () => readonly string[];
3405
+ readonly identities: WindowIdentities;
3406
+ /** Tool families the host and the person vouch for, pinned to verified schemas; read when a window first calls one. */
3407
+ readonly registry?: () => readonly CvmRegistryFamily[];
3408
+ }
3409
+ /**
3410
+ * The host's tool families and the person's together. The person's family
3411
+ * takes the place of the host's with the same label and provider, so what
3412
+ * they chose is what an applet asking by that label reaches (D-043).
3413
+ *
3414
+ * @param host - Families from `KernlOptions.remoteTools.registry`.
3415
+ * @param own - Families the person trusts.
3416
+ * @returns The families the tool service offers.
3417
+ * @example
3418
+ * ```ts
3419
+ * mergeFamilies(options.remoteTools?.registry ?? [], kernl.multiplayer.state().families);
3420
+ * ```
3421
+ */
3422
+ declare function mergeFamilies(host: readonly CvmRegistryFamily[], own: readonly CvmRegistryFamily[]): CvmRegistryFamily[];
3423
+ /**
3424
+ * kehto's tool transport over the shell's one pool. A request is published to
3425
+ * every relay and succeeds when any accepts it (D-028).
3426
+ *
3427
+ * @param pool - The shared applesauce pool.
3428
+ * @returns The relay surface `createNostrCvmTransport` takes.
3429
+ * @example
3430
+ * ```ts
3431
+ * createNostrCvmTransport({ pool: createCvmRelayPool(pool), defaultRelays });
3432
+ * ```
3433
+ */
3434
+ declare function createCvmRelayPool(pool: ApplesaucePool): CvmRelayPool;
3435
+ /**
3436
+ * The `cvm` service: applets call tools on remote servers through the shell.
3437
+ *
3438
+ * Each window gets a kehto tool service of its own, with a transport that
3439
+ * calls as that window's key (D-041). Two applets that use the same server
3440
+ * neither share a client key nor receive each other's server events, and no
3441
+ * call is made as the account. When the window ends, its transport closes and
3442
+ * its key is wiped.
3443
+ *
3444
+ * @param options - Pool, default relays, window identities and an optional registry.
3445
+ * @returns The service handler to register as `cvm`.
3446
+ * @example
3447
+ * ```ts
3448
+ * registry.cvm = createRemoteToolsService({ pool, relays: () => tiers.get().super, identities });
3449
+ * ```
3450
+ */
3451
+ declare function createRemoteToolsService(options: RemoteToolsOptions): ServiceHandler;
3452
+
3453
+ /** What the direct connections service needs from the shell. */
3454
+ interface DirectConnectionsOptions {
3455
+ readonly pool: ApplesaucePool;
3456
+ /** Where people in a room find each other; read when a window first opens a session. */
3457
+ readonly relays: () => readonly string[];
3458
+ readonly identities: WindowIdentities;
3459
+ /** STUN and TURN servers that help connections through; read when a window first opens a session. */
3460
+ readonly iceServers: () => readonly DirectIceServer[];
3461
+ /** Makes a peer connection; the page's `RTCPeerConnection` by default. */
3462
+ readonly createPeer?: (configuration: RTCConfiguration) => RTCPeerConnection;
3463
+ /** The verified applet a window runs, or undefined. */
3464
+ readonly appletOf: (windowId: string) => Pick<AppletSummary, 'identity' | 'publisher' | 'manifest'> | undefined;
3465
+ /** Whether the person granted this window's applet direct connections, and has not blocked it. */
3466
+ readonly isGranted: (windowId: string) => boolean;
3467
+ /** Put the summary to the person; resolve true only on yes. */
3468
+ readonly ask: (summary: ConsentSummary) => Promise<boolean>;
3469
+ }
3470
+ /**
3471
+ * The stable address rooms are kept apart by: the publisher, the manifest
3472
+ * kind and the applet's name, the same for every version. Paja derives the
3473
+ * same string, so one applet meets the same rooms in either shell when both
3474
+ * introduce people through the same servers.
3475
+ *
3476
+ * @param summary - The verified applet.
3477
+ * @returns `<publisher>:<kind>:<name>`.
3478
+ * @example
3479
+ * ```ts
3480
+ * directNamespace(summary); // 'ab12…:35129:chess'
3481
+ * ```
3482
+ */
3483
+ declare function directNamespace(summary: Pick<AppletSummary, 'publisher' | 'manifest'>): string;
3484
+ /**
3485
+ * The consent prompt for one direct session: who it reaches, what they learn
3486
+ * about the person, what the shell cannot see, and which servers introduce
3487
+ * the two sides. A direct connection hands the other side the person's
3488
+ * network address, and what passes over it is out of the shell's sight, so
3489
+ * the prompt says both plainly.
3490
+ *
3491
+ * @param requirements - What kehto's WebRTC service planned for the session.
3492
+ * @param applet - The applet asking.
3493
+ * @returns The summary the host renders.
3494
+ * @example
3495
+ * ```ts
3496
+ * describeDirectConnection(requirements, identity).title; // 'Connect directly to other people'
3497
+ * ```
3498
+ */
3499
+ declare function describeDirectConnection(requirements: readonly PermissionRequirement[], applet: AppletIdentity): ConsentSummary;
3500
+ /**
3501
+ * The `webrtc` service: applets open direct sessions with other people.
3502
+ *
3503
+ * Each window gets kehto's WebRTC service over {@link createDirectSignaling},
3504
+ * signing under the window's own key. kehto opens a session only through the
3505
+ * runtime's approval step, which kernl supplies here instead of kehto's
3506
+ * permission authority: the window's applet must hold the `webrtc` grant, the
3507
+ * person is asked once per session, and the session's work stops when the
3508
+ * window ends, its grant changes or the person says no (D-042). Upstream
3509
+ * gap: kehto's ACL has no capability for `webrtc`, so the grant is checked
3510
+ * here, not by the ACL.
3511
+ *
3512
+ * @param options - Pool, relays, identities, ICE servers, peer factory and the grant and consent hooks.
3513
+ * @returns The service handler to register as `webrtc`.
3514
+ * @example
3515
+ * ```ts
3516
+ * registry.webrtc = createDirectConnectionsService({ pool, relays, identities, iceServers: [], createPeer, appletOf, isGranted, ask });
3517
+ * ```
3518
+ */
3519
+ declare function createDirectConnectionsService(options: DirectConnectionsOptions): ServiceHandler;
3520
+
3521
+ /**
3522
+ * The signaling format, shared with Paja so one applet meets the same rooms in
3523
+ * either shell when both introduce people through the same servers.
3524
+ *
3525
+ * @example
3526
+ * ```ts
3527
+ * JSON.parse(signal.content).v === DIRECT_SIGNALING_PROFILE; // a hello carries the format it speaks
3528
+ * ```
3529
+ */
3530
+ declare const DIRECT_SIGNALING_PROFILE = "soy-rtc/1";
3531
+ /**
3532
+ * The event kind signals travel in.
3533
+ *
3534
+ * @example
3535
+ * ```ts
3536
+ * const filter = { kinds: [DIRECT_SIGNAL_KIND], '#d': [wire] };
3537
+ * ```
3538
+ */
3539
+ declare const DIRECT_SIGNAL_KIND = 25050;
3540
+ /**
3541
+ * The largest JSON payload one message may carry, in bytes.
3542
+ *
3543
+ * @example
3544
+ * ```ts
3545
+ * new TextEncoder().encode(JSON.stringify(payload)).length <= DIRECT_MAX_PAYLOAD_BYTES; // else the send is refused
3546
+ * ```
3547
+ */
3548
+ declare const DIRECT_MAX_PAYLOAD_BYTES = 16384;
3549
+ /** The window's own signer: a key that belongs to no account. */
3550
+ interface SignalSigner {
3551
+ getPublicKey(): Promise<string>;
3552
+ signEvent(template: EventTemplate): Promise<NostrEvent>;
3553
+ readonly nip44: {
3554
+ encrypt(pubkey: string, plaintext: string): Promise<string>;
3555
+ decrypt(pubkey: string, ciphertext: string): Promise<string>;
3556
+ };
3557
+ }
3558
+ /** Where signals are published and read. */
3559
+ interface SignalRelay {
3560
+ subscribe(relays: readonly string[], filters: NostrFilter[], onEvent: (event: NostrEvent) => void): {
3561
+ close(): void;
3562
+ };
3563
+ publish(relays: readonly string[], event: NostrEvent): Promise<void>;
3564
+ }
3565
+ /** What one window's direct connections run on. */
3566
+ interface DirectSignalingOptions {
3567
+ readonly signer: SignalSigner;
3568
+ /** The applet's stable address; rooms of different applets never meet. */
3569
+ readonly namespace: string;
3570
+ readonly relays: readonly string[];
3571
+ readonly relay: SignalRelay;
3572
+ /** STUN and TURN addresses the host configured, approved with the session. */
3573
+ readonly iceEndpoints: readonly string[];
3574
+ readonly createPeer: () => RTCPeerConnection;
3575
+ }
3576
+ /**
3577
+ * kehto's WebRTC hooks for one window, speaking the `soy-rtc/1` signaling
3578
+ * format over the shell's pool.
3579
+ *
3580
+ * Signals are signed by the window's own key and carry the session's room
3581
+ * address, never the account. Offers and answers are encrypted to the one
3582
+ * peer they are for. Application data goes only through the data channel;
3583
+ * delivery is reliable and ordered, and a peer that asks for otherwise is
3584
+ * left out. A message is at most 16 KiB of JSON; at most four sessions per
3585
+ * window and eight peers per session (D-042).
3586
+ *
3587
+ * @param options - The window's signer and namespace, the relays, and the peer factory.
3588
+ * @returns Options for kehto's `createWebrtcService`.
3589
+ * @example
3590
+ * ```ts
3591
+ * createWebrtcService(createDirectSignaling({ signer, namespace, relays, relay, iceEndpoints: [], createPeer }));
3592
+ * ```
3593
+ */
3594
+ declare function createDirectSignaling(options: DirectSignalingOptions): WebrtcServiceOptions;
3035
3595
 
3036
3596
  /**
3037
3597
  * Whether a host-supplied theme has the colours NAP-THEME requires.
@@ -3074,6 +3634,8 @@ interface KernlServiceDeps {
3074
3634
  readonly uploader?: Uploader;
3075
3635
  /** Names conversation participants for applets; without it they are listed by key alone. */
3076
3636
  readonly profiles?: Pick<Profiles, 'settled'>;
3637
+ /** Reads the people an applet names in any form of their identity; without it only hex is taken. */
3638
+ readonly people?: Pick<People, 'locate'>;
3077
3639
  readonly theme?: Theme;
3078
3640
  /** Maps a live window to its verified identity, or null. */
3079
3641
  readonly resolveIdentity: (windowId: string) => {
@@ -3082,6 +3644,18 @@ interface KernlServiceDeps {
3082
3644
  } | null;
3083
3645
  /** Identity lookups; defaults to the applesauce-backed providers. */
3084
3646
  readonly identity?: IdentityProviders;
3647
+ /** Keys for the work a window does under its own name; a fresh set by default (D-041). */
3648
+ readonly identities?: WindowIdentities;
3649
+ /** Where remote tools are looked for and which families the host vouches for. */
3650
+ readonly remoteTools?: RemoteToolsSettings | undefined;
3651
+ /** Direct connections; without them the `webrtc` domain is not offered (D-042). */
3652
+ readonly directConnections?: DirectConnectionsDeps | undefined;
3653
+ /** The person's own choices, which come before the host's (D-043). */
3654
+ readonly multiplayer?: Pick<MultiplayerSettings, 'state'>;
3655
+ }
3656
+ /** What the `webrtc` service needs beyond the pool and the window identities. */
3657
+ interface DirectConnectionsDeps extends Pick<DirectConnectionsOptions, 'createPeer' | 'appletOf' | 'isGranted' | 'ask'> {
3658
+ readonly settings: Omit<DirectConnectionsSettings, 'createPeer'>;
3085
3659
  }
3086
3660
  /** The registered services plus the handles the shell keeps calling. */
3087
3661
  interface KernlServices {
@@ -3105,11 +3679,12 @@ declare function resourceInitFor(deps: Pick<KernlServiceDeps, 'resolveIdentity'>
3105
3679
  /**
3106
3680
  * Register kehto's reference services over the shell's applesauce layer.
3107
3681
  *
3108
- * `relay`, `identity`, `theme`, `notify`, `link`, `resource`, `dm` and `outbox`
3109
- * are wired; every network path goes through the one pool, every resource
3110
- * fetch through the bridge registry's SSRF policy, links open only over
3111
- * `https:` and `mailto:`, notifications surface through the host, and outbox
3112
- * publishes pass the consent gate before they are signed.
3682
+ * `relay`, `identity`, `theme`, `notify`, `link`, `resource`, `dm`, `outbox`
3683
+ * and `cvm` are wired; every network path goes through the one pool, every
3684
+ * resource fetch through the bridge registry's SSRF policy, links open only
3685
+ * over `https:` and `mailto:`, notifications surface through the host, outbox
3686
+ * publishes pass the consent gate before they are signed, and remote tools are
3687
+ * called under each window's own key.
3113
3688
  *
3114
3689
  * @param deps - Pool, tiers, store, auth, consent gate, host, registries and identity resolver.
3115
3690
  * @returns The service registry and the theme and dm handles.
@@ -3190,7 +3765,9 @@ interface LifecycleContext {
3190
3765
  * A window keeps the environment it was started with, and `shell.init` is not
3191
3766
  * sent again, so a window whose grant no longer covers a domain it was started
3192
3767
  * with would go on advertising it. Granting more never stops a window; the
3193
- * applet sees the new domain the next time it opens.
3768
+ * applet sees the new domain the next time it opens. The one grant that
3769
+ * narrows is messages: it withholds every domain that could send them on, so
3770
+ * a window started with one of those stops (D-046).
3194
3771
  *
3195
3772
  * @param plan - The running window's plan; its environment is what it was started with.
3196
3773
  * @param record - The grant record that just changed.
@@ -3270,6 +3847,24 @@ declare function toSession(account: IAccount, card?: ProfileCard): Session;
3270
3847
  */
3271
3848
  declare function createKernl(options: KernlOptions): Kernl;
3272
3849
 
3850
+ /**
3851
+ * Let an applet name the people it writes to in any form of their identity.
3852
+ *
3853
+ * Every recipient of a send is read with `people.locate`, so hex, `npub` and
3854
+ * `nprofile` all work and the servers an `nprofile` names are asked for the
3855
+ * person's inboxes before the message is sealed. The backends still see hex.
3856
+ *
3857
+ * @param adapter - The messaging adapter to wrap.
3858
+ * @param people - The shell's finder.
3859
+ * @returns The adapter, with recipients read on the way in.
3860
+ * @throws `invalid:recipient` from `send` when a recipient is not an identity.
3861
+ * @example
3862
+ * ```ts
3863
+ * createDmService({ adapter: locateRecipients(messaging.composite(), kernl.people) });
3864
+ * ```
3865
+ */
3866
+ declare function locateRecipients(adapter: DmAdapter, people: Pick<People, 'locate'>): DmAdapter;
3867
+
3273
3868
  /** What the store filters by. Every part is optional; an empty query lists everything. */
3274
3869
  interface CatalogQuery {
3275
3870
  /** Free text, matched loosely against title, topics, roles, description and publisher. */
@@ -3477,4 +4072,4 @@ declare const PACKAGE_NAME = "@kernlize/core";
3477
4072
  */
3478
4073
  declare const KERNL_FRAME_POLICY_META: string;
3479
4074
 
3480
- 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, 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, SHELL_RELAY_OPTIONS, type SealedGroupStoreOptions, type SealedRatchetStorageOptions, type Session, type SettingsPrompt, 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, commonActionsFor, createAccountFileServers, createAccountMailboxes, createAppletConfig, createAppletLifecycle, createAppletRelayBackend, createAppletRelayService, createAuthHooks, createBlossomUploader, createCommonActions, 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, grantNarrowingReason, 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 };
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 };