@kehto/shell 0.2.0 → 0.5.0

package/README.md

@@ -2,6 +2,10 @@
 
 Browser adapter over @kehto/runtime — ShellBridge, domain proxies, keys-forwarder.
 
+> **Alpha status:** Kehto is an early runtime implementation for a draft NIP-5D
+> protocol. NUB contracts, `supports()` behavior, and shell capabilities are not
+> final; treat this package as current implementation guidance.
+
 ## Install
 
 ```bash
@@ -14,11 +18,11 @@ pnpm add @kehto/shell
 
 The primary entry point is `createShellBridge()` — it owns the postMessage listener, AUTH handshake, manifest verification, and every dispatch back into the runtime engine.
 
-Canonical v1.2 behaviors this package enforces:
+Current draft behaviors this package enforces:
 
 - The shell does not inject a host-provided nostr object into napplets — NIP-5D explicitly forbids napplet-visible signing. Napplets call `relay.publish` / `relay.publishEncrypted` and the shell mediates the signing flow internally (NIP-44 default, NIP-04 opt-in for encrypted envelopes).
 - `shell.supports(capability)` uses the `perm:<permission>` namespace for sandbox permissions, not the v1.1 bare capability list.
-- Five optional per-domain proxies — `createIdentityProxy`, `createThemeProxy`, `createKeysProxy`, `createMediaProxy`, `createNotifyProxy` — can be composed between napplet and runtime to intercept or augment traffic per NUB. They are NOT wired by default (the runtime already owns 8-domain dispatch); they exist as host-app composition seams.
+- Five optional per-domain proxies — `createIdentityProxy`, `createThemeProxy`, `createKeysProxy`, `createMediaProxy`, `createNotifyProxy` — can be composed between napplet and runtime to intercept or augment traffic per NUB. They are NOT wired by default (Kehto's runtime already owns dispatch for the currently supported domains); they exist as host-app composition seams.
 - The keys-forwarder pumps host keydown events into `keys.forward` envelopes for napplets that hold the `keys:forward` capability.
 
 ## Quick Start
@@ -43,24 +47,24 @@ bridge.runtime.registerService(
 ## Public API
 
 ### Bridge factory
-- [`createShellBridge`](../../docs/api/functions/_kehto_shell.createShellBridge.html) — primary entry point; returns a `ShellBridge` (exposed `runtime`, `shell.ready`, lifecycle hooks)
+- `createShellBridge` — primary entry point; returns a `ShellBridge` (exposed `runtime`, `shell.ready`, lifecycle hooks)
 - `ShellBridge` — interface type for the returned bridge
 
 ### Hooks adapter
-- [`adaptHooks`](../../docs/api/functions/_kehto_shell.adaptHooks.html) — convert a `ShellAdapter` + `BrowserDeps` into the canonical `RuntimeAdapter` hook bag consumed by `@kehto/runtime`
+- `adaptHooks` — convert a `ShellAdapter` + `BrowserDeps` into the canonical `RuntimeAdapter` hook bag consumed by `@kehto/runtime`
 
 ### Shell init
-- [`buildShellCapabilities`](../../docs/api/functions/_kehto_shell.buildShellCapabilities.html) — construct the `ShellCapabilities` payload emitted during the `shell.ready` / `shell.init` handshake
+- `buildShellCapabilities` — construct the current draft `ShellCapabilities` payload emitted during the `shell.ready` / `shell.init` handshake
 
 ### Domain proxies (NIP-5D composition seams)
-- [`createIdentityProxy`](../../docs/api/functions/_kehto_shell.createIdentityProxy.html) — intercept `identity.getProfile/getFollows/...` traffic
-- [`createThemeProxy`](../../docs/api/functions/_kehto_shell.createThemeProxy.html) — intercept `theme.get/theme.changed`
-- [`createKeysProxy`](../../docs/api/functions/_kehto_shell.createKeysProxy.html) — intercept `keys.bind/unbind/bindings`
-- [`createMediaProxy`](../../docs/api/functions/_kehto_shell.createMediaProxy.html) — intercept `media.*` playback control
-- [`createNotifyProxy`](../../docs/api/functions/_kehto_shell.createNotifyProxy.html) — intercept `notify.send/list/read/dismiss`
+- `createIdentityProxy` — intercept `identity.getProfile/getFollows/...` traffic
+- `createThemeProxy` — intercept `theme.get/theme.changed`
+- `createKeysProxy` — intercept `keys.bind/unbind/bindings`
+- `createMediaProxy` — intercept `media.*` playback control
+- `createNotifyProxy` — intercept `notify.send/list/read/dismiss`
 
 ### Keys forwarder
-- [`createKeysForwarder`](../../docs/api/functions/_kehto_shell.createKeysForwarder.html) — host-keydown pump into `keys.forward` envelopes; auto-attached by `createShellBridge`, also exported for hosts that manage their own forwarder instance
+- `createKeysForwarder` — host-keydown pump into `keys.forward` envelopes; auto-attached by `createShellBridge`, also exported for hosts that manage their own forwarder instance
 
 ### Session / origin registry
 - `sessionRegistry` — canonical windowId ↔ verified-napplet registry singleton
@@ -88,13 +92,14 @@ Exported for host-app integration: `ShellAdapter`, `ShellCapabilities`, `RelayPo
 
 ### Compat re-exports (DRIFT-CORE-06)
 
-Retained for v1.1 migration consumers; new integrations should use canonical NIP-5D envelope types from `@napplet/core`. Slated for removal once upstream restores those exports.
+Retained for migration consumers; new integrations should use current NIP-5D envelope types from `@napplet/core`. Slated for removal once upstream restores those exports.
 
 Re-exported from `@kehto/runtime`: the v1.1 bus-kind enum, auth event kind, shell bridge URI constant, protocol version string, the full capability list, destructive-kind set, and the replay window seconds constant. Re-exported types cover the v1.1 capability union and bus-kind numeric union. See the typedoc API reference below for the exact identifier list.
 
 ## API Reference
 
-Full API reference: [docs/api/@kehto/shell/](../../docs/api/modules/_kehto_shell.html) (generated via `pnpm docs:api`).
+Full package docs: [`docs/packages/shell.md`](../../docs/packages/shell.md).
+Generated API module: `docs/api/modules/_kehto_shell.html` (run `pnpm docs:api`).
 
 ## License
 

package/dist/index.d.ts

@@ -1,45 +1,9 @@
-import { Capability, ServiceRegistry, RuntimeConfigOverrides, ConsentRequest, Runtime, RuntimeAdapter } from '@kehto/runtime';
-export { ALL_CAPABILITIES, AclChecker, Capability, ConsentRequest, EnforceConfig, EnforceResult, IdentityResolver, NubEnforceConfig, NubMessage, ServiceDescriptor, ServiceHandler, ServiceRegistry, createEnforceGate, createNubEnforceGate, formatDenialReason } from '@kehto/runtime';
+import { Capability, NappletClass, ServiceRegistry, RuntimeConfigOverrides, ConsentRequest, Runtime, SessionEntry, PendingUpdate, RuntimeAdapter } from '@kehto/runtime';
+export { ALL_CAPABILITIES, AclChecker, Capability, ConsentRequest, EnforceConfig, EnforceResult, IdentityResolver, NappKeyEntry, NappletClass, NubEnforceConfig, NubMessage, PendingUpdate, ServiceDescriptor, ServiceHandler, ServiceRegistry, SessionEntry, createEnforceGate, createNubEnforceGate, formatDenialReason } from '@kehto/runtime';
 import { NappletMessage, NostrEvent, NostrFilter } from '@napplet/core';
 export { NappletMessage, NostrEvent, NostrFilter, TOPICS, TopicKey, TopicValue } from '@napplet/core';
-import { Theme } from '@napplet/nub-theme';
+import { Theme } from '@napplet/nub/theme/types';
 
-/**
- * Registry entry mapping a napplet's pubkey to its runtime metadata.
- * Created after a successful NIP-42 AUTH handshake or NIP-5D origin registration.
- * @example
- * ```ts
- * const entry: SessionEntry = {
- *   pubkey: 'abc123...', windowId: 'win-1', origin: '*',
- *   type: 'chat', dTag: '3chat', aggregateHash: 'deadbeef',
- *   registeredAt: Date.now(), instanceId: 'guid-123',
- *   identitySource: 'auth',
- * };
- * ```
- */
-interface SessionEntry {
-    /**
-     * @deprecated NIP-5D: AUTH keypair no longer exists. Empty string for NIP-5D sessions.
-     * Kept for backward compatibility during legacy support period.
-     */
-    pubkey: string;
-    windowId: string;
-    origin: string;
-    type: string;
-    dTag: string;
-    aggregateHash: string;
-    registeredAt: number;
-    /** Persistent GUID for this iframe instance, assigned by the runtime. Survives page reloads. */
-    instanceId: string;
-    /**
-     * How session identity was established.
-     * 'source' = NIP-5D (identity registered at iframe creation via originRegistry).
-     * 'auth' = legacy AUTH handshake (pubkey is the derived keypair pubkey).
-     */
-    identitySource: 'auth' | 'source';
-}
-/** @deprecated Use SessionEntry. Will be removed in v0.9.0. */
-type NappKeyEntry = SessionEntry;
 /**
  * ACL entry controlling what a napplet pubkey is permitted to do.
  * @example
@@ -198,8 +162,9 @@ interface AclCheckEvent {
     message?: NappletMessage | unknown[];
 }
 /**
- * Static capability set injected into napplet iframes at creation time.
- * Used by `window.napplet.shell.supports()` for synchronous capability queries.
+ * Static capability set sent to napplet iframes through the shell.ready /
+ * shell.init handshake. Used by hosted `window.napplet.shell.supports()` for
+ * synchronous capability queries after the shim consumes shell.init.
  *
  * Per canonical NIP-5D (specs/NIP-5D.md lines 81-94), supports() distinguishes
  * two namespaces:
@@ -216,9 +181,9 @@ interface AclCheckEvent {
  */
 interface ShellCapabilities {
     /**
-     * NUB domain prefixes the shell handles. Canonical 8-domain set from @napplet/nub-*:
-     * relay, identity, storage, ifc, theme, keys, media, notify. `relay` is conditional
-     * on the RelayPoolHooks being provided.
+     * NUB domain prefixes the shell handles. Kehto's hosted playground set is:
+     * relay, identity, storage, ifc, theme, keys, media, notify, config,
+     * resource, connect, class. `relay` is conditional on RelayPoolHooks.
      *
      * Entries are bare domain names — `'relay'`, `'identity'`, etc. They MUST NOT
      * carry the `perm:` prefix; that prefix is reserved for the `sandbox` array.
@@ -272,12 +237,18 @@ interface ShellAdapter {
     onHashMismatch?: (dTag: string, claimed: string, computed: string) => void;
     /**
      * Called at iframe creation for NIP-5D napplets.
-     * Returns identity metadata for originRegistry.register().
-     * Return null for non-NIP-5D (legacy) iframes.
+     * Returns identity metadata for originRegistry.register(), INCLUDING the
+     * class posture (CLASS-01, breaking v1.7). Returning `class: null` selects
+     * the permissive default (D2). Returning null overall means "not NIP-5D /
+     * skip registration" (unchanged semantics from v1.6).
+     *
+     * BREAKING v1.7: previously `{ dTag, aggregateHash } | null`; now requires
+     * `class` in the non-null branch. See .changeset/class-01-breaking-hook.md.
      */
     onNip5dIframeCreate?: (windowId: string) => {
         dTag: string;
         aggregateHash: string;
+        class: NappletClass;
     } | null;
     /**
      * Optional service extensions. Each key is a service name (e.g., 'audio',
@@ -305,17 +276,144 @@ interface ShellAdapter {
 }
 
 /**
- * shell-bridge.ts — Browser adapter over @kehto/runtime.
+ * connect-store.ts — NUB-CONNECT grant registry keyed on (dTag, aggregateHash).
+ *
+ * Mirrors acl-store.ts pattern: module-level singleton, localStorage persistence,
+ * composite-key Map. Grants are per-napplet-build: changing the aggregateHash
+ * (a rebuild) invalidates prior grants (CONNECT-06) — the composite key makes
+ * this structural, not policy-driven.
  *
- * Thin shell that converts browser MessageEvents into windowId-based
- * NIP-5D envelope messages for the runtime engine. All protocol logic
- * (NUB dispatch, ACL enforcement, subscription lifecycle, signer proxying)
- * lives in @kehto/runtime.
+ * Default policy is RESTRICTIVE (opposite of aclStore): unknown (dTag, hash, origin)
+ * combinations return `false` from check() — napplets must be explicitly granted
+ * origins via grant(). This is the NUB-CONNECT security invariant.
  *
- * The only browser-specific concern here is extracting the source Window
- * from a MessageEvent, mapping it to a windowId via originRegistry, and
- * routing shell.ready/shell.init handshake locally.
+ * @see packages/shell/src/types/internal-connect.ts for the wire types.
+ * @see docs/policies/SHELL-CONNECT-POLICY.md (Plan 39-05) for the full policy.
+ */
+/**
+ * Public interface for the NUB-CONNECT grant store singleton.
+ *
+ * All methods are keyed on (dTag, aggregateHash). A rebuild with a new
+ * aggregateHash is a distinct identity — CONNECT-06 hash-upgrade semantics
+ * are structurally guaranteed: check(dTag, newHash, origin) returns false
+ * because newHash has no entry in the store.
+ */
+interface ConnectStore {
+    /**
+     * Check whether an origin has been granted for a specific (dTag, aggregateHash).
+     *
+     * Returns false for unknown (dTag, aggregateHash) pairs — RESTRICTIVE default.
+     * Returns false for unknown origins even if the (dTag, hash) pair exists.
+     *
+     * @param dTag - The napplet's dTag identifier
+     * @param aggregateHash - The napplet's build aggregate hash
+     * @param origin - The origin to check (e.g., 'https://relay.example.com')
+     * @returns true if origin is in the grant set; false otherwise
+     */
+    check(dTag: string, aggregateHash: string, origin: string): boolean;
+    /**
+     * Get all granted origins for a (dTag, aggregateHash) pair.
+     *
+     * Returns an empty array for unknown (dTag, aggregateHash) pairs.
+     *
+     * @param dTag - The napplet's dTag identifier
+     * @param aggregateHash - The napplet's build aggregate hash
+     * @returns Readonly array of granted origin strings; empty if not granted
+     */
+    getOrigins(dTag: string, aggregateHash: string): readonly string[];
+    /**
+     * Grant a set of origins to a (dTag, aggregateHash) pair.
+     *
+     * Deduplicates and sorts origins for idempotent CSP header output (Plan 39-03).
+     * Replaces any existing grant for the same (dTag, aggregateHash) pair.
+     * Persists to localStorage automatically.
+     *
+     * @param dTag - The napplet's dTag identifier
+     * @param aggregateHash - The napplet's build aggregate hash
+     * @param origins - Origins to grant (e.g., ['https://relay.example.com', 'wss://relay2.example.com'])
+     */
+    grant(dTag: string, aggregateHash: string, origins: readonly string[]): void;
+    /**
+     * Revoke all granted origins for a (dTag, aggregateHash) pair.
+     *
+     * After revocation, check() returns false and getOrigins() returns [].
+     * Persists to localStorage automatically.
+     *
+     * @param dTag - The napplet's dTag identifier
+     * @param aggregateHash - The napplet's build aggregate hash
+     */
+    revoke(dTag: string, aggregateHash: string): void;
+    /**
+     * Get all current grants across all (dTag, aggregateHash) pairs.
+     *
+     * Used by the Vite CSP plugin (Plan 39-03) to build the connect-src
+     * header for each napplet on dev-server startup.
+     *
+     * @returns Readonly array of all grants
+     */
+    getAllGrants(): ReadonlyArray<{
+        dTag: string;
+        aggregateHash: string;
+        origins: readonly string[];
+    }>;
+    /**
+     * Persist the current store state to localStorage under 'napplet:connect'.
+     *
+     * Tolerates unavailable localStorage (e.g., SSR, private browsing with
+     * storage disabled). Called automatically by grant() and revoke().
+     */
+    persist(): void;
+    /**
+     * Load the store state from localStorage.
+     *
+     * Validates shape before populating; clears store on corrupt data.
+     * Should be called once on shell startup before handling any napplet messages.
+     */
+    load(): void;
+    /**
+     * Clear all grants and remove the localStorage entry.
+     *
+     * Best-effort localStorage removal (tolerates unavailability).
+     */
+    clear(): void;
+}
+/**
+ * NUB-CONNECT grant store singleton.
+ *
+ * Module-level instance — import and use directly. Persists under localStorage
+ * key 'napplet:connect'. Call `connectStore.load()` on shell startup to restore
+ * persisted grants from a previous session.
+ *
+ * @example
+ * ```ts
+ * import { connectStore } from '@kehto/shell';
+ *
+ * // On shell startup:
+ * connectStore.load();
+ *
+ * // On consent approval:
+ * connectStore.grant(dTag, aggregateHash, ['https://relay.example.com']);
+ *
+ * // In Vite CSP plugin (Plan 39-03):
+ * const origins = connectStore.getOrigins(dTag, aggregateHash);
+ * ```
+ */
+declare const connectStore: ConnectStore;
+/**
+ * Compose the canonical `<dTag>:<aggregateHash>` composite key used by the
+ * connect-store. Exported for consumers that need to key their own maps by
+ * the same identity (e.g., Vite CSP plugin — Plan 39-03).
+ *
+ * @param dTag - The napplet's dTag identifier
+ * @param aggregateHash - The napplet's build aggregate hash
+ * @returns Composite key string in `<dTag>:<aggregateHash>` format
+ *
+ * @example
+ * ```ts
+ * const key = connectGrantKey('chat', 'abc123'); // 'chat:abc123'
+ * ```
  */
+declare function connectGrantKey(dTag: string, aggregateHash: string): string;
 
 /**
  * Shell-side message bridge that handles NIP-5D communication with napplet iframes.
@@ -354,17 +452,19 @@ interface ShellBridge {
      */
     handleMessage(event: MessageEvent): void;
     /**
-     * Inject a shell-originated event into subscription delivery.
+     * Inject a shell-originated event into subscription delivery. Under NIP-5D,
+     * shell-originated events are forwarded to napplets as ifc.event envelope
+     * messages. The runtime's injectEvent() handles the per-session routing.
      *
-     * Under NIP-5D, shell-originated events are forwarded to napplets as
-     * ifc.event envelope messages. The runtime's injectEvent() handles
-     * the per-session routing.
+     * v1.10 hard-removed the v1.8 soft-rename compatibility branch for the
+     * old `auth:identity-changed` topic. Use the canonical `identity:changed`
+     * topic for identity-change pushes.
      *
-     * @param topic - The event topic tag value (e.g., 'auth:identity-changed')
+     * @param topic - The event topic tag value. Forwarded exactly once.
      * @param payload - The event content
      * @example
      * ```ts
-     * bridge.injectEvent('auth:identity-changed', { pubkey: userPubkey });
+     * bridge.injectEvent('identity:changed', { pubkey: userPubkey });
      * ```
      */
     injectEvent(topic: string, payload: unknown): void;
@@ -417,12 +517,36 @@ interface ShellBridge {
      * ```
      */
     publishTheme(theme: Theme): void;
+    /**
+     * Publish the current shell-user identity to every loaded napplet.
+     *
+     * Posts an `identity.changed` envelope (shell → napplet push) with the
+     * current user pubkey. An empty pubkey means no signer/user identity is
+     * currently connected. This is distinct from NIP-5D napplet session identity,
+     * which remains source-bound at iframe creation.
+     *
+     * @param pubkey - Current user's hex pubkey, or empty string when signed out.
+     */
+    publishIdentityChanged(pubkey: string): void;
     /**
      * Access the underlying runtime instance for advanced use cases.
      * Provides direct access to the runtime's sessionRegistry, aclState,
      * and manifestCache.
      */
     readonly runtime: Runtime;
+    /**
+     * Access the NUB-CONNECT grant store. Per-napplet connect grants are
+     * keyed on (dTag, aggregateHash) and persisted under localStorage key
+     * 'napplet:connect'. Public API surface for the Vite CSP middleware
+     * (Plan 39-03) and the consent flow (Plan 39-04).
+     *
+     * Default policy is RESTRICTIVE: check() returns false for any origin
+     * not explicitly granted. Call load() on shell startup to restore
+     * persisted grants from a previous session.
+     *
+     * @see SHELL-CONNECT-POLICY.md for the full policy.
+     */
+    readonly connectStore: ConnectStore;
 }
 /**
  * Create a ShellBridge instance with dependency injection via hooks.
@@ -451,13 +575,6 @@ interface ShellBridge {
  */
 declare function createShellBridge(hooks: ShellAdapter): ShellBridge;
 
-/**
- * Origin Registry — Window reference to windowId mapping.
- *
- * Used by the ShellBridge to validate that postMessage senders are known
- * napplet iframes. event.source (a Window reference) is the only unforgeable
- * origin — never trust event.origin from the message payload.
- */
 /**
  * Bidirectional registry mapping Window references to windowId strings.
  * Optionally stores NIP-5D identity metadata (dTag and aggregateHash) per window.
@@ -592,16 +709,6 @@ declare const manifestCache: {
     clear(): void;
 };
 
-/**
- * ACL Store — composite-keyed capability registry for napplet identity.
- *
- * ACL entries are keyed by dTag:aggregateHash — a 2-segment composite key
- * that ties permissions to a specific napplet build (NIP-5D format).
- * Old 3-segment keys (pubkey:dTag:hash) are automatically migrated via migrateAclState().
- *
- * Default policy is PERMISSIVE: unknown identities have all capabilities granted.
- */
-
 /**
  * ACL store — manages capability grants, revocations, and blocks for napp identities.
  * Persists to localStorage and uses a permissive default policy (all capabilities granted).
@@ -806,25 +913,6 @@ declare const audioManager: {
  * verified pubkey here. Both mappings are kept in sync.
  */
 
-/**
- * A pending napplet update — raised when a napplet reconnects with a different aggregateHash.
- * @example
- * ```ts
- * const update: PendingUpdate = {
- *   windowId: 'win-1', pubkey: 'abc...', dTag: '3chat',
- *   oldHash: 'aaa', newHash: 'bbb',
- *   resolve: (action) => { if (action === 'accept') { // apply } },
- * };
- * ```
- */
-interface PendingUpdate {
-    windowId: string;
-    pubkey: string;
-    dTag: string;
-    oldHash: string;
-    newHash: string;
-    resolve: (action: 'accept' | 'block') => void;
-}
 /**
  * Bidirectional registry mapping windowIds to verified napplet pubkeys.
  * Maintained by ShellBridge after successful AUTH handshakes.
@@ -1024,25 +1112,13 @@ interface BrowserDeps {
  */
 declare function adaptHooks(shellHooks: ShellAdapter, deps: BrowserDeps): RuntimeAdapter;
 
-/**
- * shell-init.ts — Shell initialization utilities.
- *
- * Provides buildShellCapabilities() — derives the shell's static NUB capability
- * set from the ShellAdapter configuration, used in the shell.ready / shell.init
- * handshake so napplets can query shell.supports() synchronously.
- *
- * Canonical NIP-5D forbids the shell from injecting a NIP-07 proxy object on
- * the napplet iframe's global scope (specs/NIP-5D.md line 44 + Security §6).
- * This module therefore does NOT expose any signing proxy to napplet code.
- * Signing/encryption is mediated by the shell through relay.publish and
- * relay.publishEncrypted — never via a napplet-visible API surface.
- */
-
 /**
  * Build the shell's static capability set from adapter configuration.
  *
- * NUB capabilities = canonical 8-domain list from @napplet/nub-*:
- *   relay (gated on hooks.relayPool), identity, storage, ifc, theme, keys, media, notify.
+ * NUB capabilities = Kehto-hosted domain list from @napplet/nub subpaths,
+ * plus relay (gated on hooks.relayPool):
+ *   relay (gated on hooks.relayPool), identity, storage, ifc, theme,
+ *   keys, media, notify, config, resource, connect, class.
  *
  * Sandbox permissions are left empty by default — host apps may extend after
  * construction. Sandbox entries returned here (and any host-app extensions)
@@ -1056,7 +1132,7 @@ declare function adaptHooks(shellHooks: ShellAdapter, deps: BrowserDeps): Runtim
  * @example
  * ```ts
  * const caps = buildShellCapabilities(hooks);
- * // caps.nubs => ['relay','identity','storage','ifc','theme','keys','media','notify']
+ * // caps.nubs => ['relay','identity','storage','ifc','theme','keys','media','notify','config','resource','connect','class','cvm']
  * //              (relay present when hooks.relayPool is provided; bare names only)
  * // caps.sandbox => []   // host app may extend with 'perm:popups', etc.
  * ```
@@ -1346,7 +1422,7 @@ declare function createKeysProxy(deps: KeysProxyDeps): KeysProxy;
 /**
  * media-proxy.ts — Shell-side per-domain proxy for media.* envelopes.
  *
- * Establishes the shell-side composition seam for `@napplet/nub-media`
+ * Establishes the shell-side composition seam for `@napplet/nub/media`
  * session-control envelopes. Shape mirrors identity-proxy (Plan 12-11):
  *
  *   - `dispatch(windowId, envelope)` routes napplet→shell media requests
@@ -1434,7 +1510,7 @@ declare function createMediaProxy(deps: MediaProxyDeps): MediaProxy;
 /**
  * notify-proxy.ts — Shell-side per-domain proxy for notify.* envelopes.
  *
- * Establishes the shell-side composition seam for `@napplet/nub-notify`
+ * Establishes the shell-side composition seam for `@napplet/nub/notify`
  * notification envelopes. Shape mirrors identity-proxy (Plan 12-11):
  *
  *   - `dispatch(windowId, envelope)` routes napplet→shell notify requests
@@ -1524,7 +1600,7 @@ declare function createNotifyProxy(deps: NotifyProxyDeps): NotifyProxy;
  * to registered napplets as `keys.forward` envelopes (Plan 12-11, NUB-05
  * shell-side half).
  *
- * Per `@napplet/nub-keys`, `keys.forward` is fire-and-forget (no result
+ * Per `@napplet/nub/keys`, `keys.forward` is fire-and-forget (no result
  * envelope, no correlation id). Field names follow the nub convention:
  * `{ ctrl, alt, shift, meta }` — NOT the DOM-style `ctrlKey`/etc.
  *
@@ -1614,4 +1690,147 @@ interface KeysForwarder {
  */
 declare function createKeysForwarder(deps: KeysForwarderDeps): KeysForwarder;
 
-export { type AclCheckEvent, type AclEntry, type AudioSource, type AuthHooks, type BrowserDeps, type ConfigHooks, type CryptoHooks, type DmHooks, type HotkeyHooks, type IdentityProxy, type IdentityProxyDeps, type KeysForwarder, type KeysForwarderDeps, type KeysForwarderOriginRegistry, type KeysForwarderSessionRegistry, type KeysProxy, type KeysProxyDeps, type ManifestCacheEntry, type MediaProxy, type MediaProxyDeps, type NappKeyEntry, type NotifyProxy, type NotifyProxyDeps, type PendingUpdate, type ProxyOriginRegistry, type RelayConfigHooks, type RelayPoolHooks, type RelayPoolLike, type SessionEntry, type ShellAdapter, type ShellBridge, type ShellCapabilities, type ThemeProxy, type ThemeProxyDeps, type WindowManagerHooks, type WorkerRelayHooks, type WorkerRelayLike, adaptHooks, audioManager, buildShellCapabilities, createIdentityProxy, createKeysForwarder, createKeysProxy, createMediaProxy, createNotifyProxy, createShellBridge, createThemeProxy, manifestCache, nappKeyRegistry, originRegistry, sessionRegistry };
+/**
+ * @file internal-connect.ts
+ *
+ * Kehto-internal shell-side connect-store + consent-flow types. Per
+ * PROJECT.md Decision #31, this is NOT a staging-ground duplicate of upstream
+ * `@napplet/nub/connect`: upstream exports a napplet-side accessor interface
+ * (`NappletConnect = { granted, origins }`) plus the shared
+ * `normalizeConnectOrigin` pure validator. Kehto's types here describe the
+ * shell's grant-store records (`ConnectGrant`, `ConnectGrantKey`,
+ * `ConsentResult`), used by the connect-store singleton and the Vite CSP
+ * plugin's consent flow.
+ *
+ * The two surfaces are complementary: upstream's accessor type ships at the
+ * napplet boundary; kehto's grant-store types live shell-side. No retirement
+ * planned. For canonical origin validation (kehto has no local impl;
+ * Decision #32), consume `@napplet/nub/connect`'s `normalizeConnectOrigin`
+ * directly.
+ *
+ * Downstream consumers (Phase 39 `connect-store.ts`, Vite CSP middleware,
+ * consent flow UI) import from this module.
+ */
+/**
+ * Grant key composed from the napplet's dTag and build aggregateHash. A hash
+ * upgrade invalidates prior grants (CONNECT-06).
+ */
+interface ConnectGrantKey {
+    dTag: string;
+    aggregateHash: string;
+}
+/**
+ * A persisted connect grant. Stored in the shell connect-store singleton,
+ * surfaced as the CSP `connect-src` origin list for the corresponding napplet.
+ */
+interface ConnectGrant {
+    /** Composite key `"<dTag>:<aggregateHash>"` under which this grant is stored. */
+    key: string;
+    /** The set of origins (WebSocket and HTTPS) the napplet is granted to connect to. */
+    origins: readonly string[];
+    /** Epoch millis when the grant was approved by the user. */
+    grantedAt: number;
+}
+/**
+ * Consent flow outcome. `'dismiss'` resolves to deny (MUST NOT default to allow).
+ * `'timeout'` also resolves to deny.
+ */
+type ConsentResult = 'approve' | 'deny' | 'dismiss' | 'timeout';
+/**
+ * Inbound consent request from a napplet requesting connect access to one or
+ * more origins.
+ */
+interface ConnectConsentRequest {
+    dTag: string;
+    aggregateHash: string;
+    /** Origins the napplet is asking to be granted access to. */
+    requestedOrigins: readonly string[];
+}
+
+/**
+ * @file internal-resource.ts
+ *
+ * Kehto-internal shell-side resource wire types. Per PROJECT.md Decision #31,
+ * this is NOT a staging-ground duplicate of upstream `@napplet/nub/resource`:
+ * Phase 44 audit confirmed the two surfaces diverge substantively — different
+ * field names (kehto's `requestId` vs upstream `id`; kehto's `bodyBase64` vs
+ * upstream `blob` + `mime`), different message-type names
+ * (`ResourceBytesRequest` vs `ResourceBytesMessage`), and disjoint error
+ * vocabularies (kehto: 5 codes `{denied, canceled, network-error, invalid-url,
+ * class-forbidden}`; upstream: 8 codes `{not-found, blocked-by-policy,
+ * timeout, too-large, unsupported-scheme, decode-failed, network-error,
+ * quota-exceeded}`).
+ *
+ * Future migration to upstream's surface is its own phase. For now this file
+ * owns the wire shapes kehto's `resource-service.ts` and resource-demo napplet
+ * already implement.
+ *
+ * Canonical 4-message protocol (RESOURCE-03):
+ *   Inbound:  resource.bytes, resource.cancel
+ *   Outbound: resource.bytes.result, resource.bytes.error
+ */
+/**
+ * Unique id for correlating a `resource.bytes` request to its later result /
+ * error / cancel envelope.
+ */
+type ResourceRequestId = string;
+/**
+ * Inbound: napplet requests bytes from an origin. Shell consults
+ * getConnectGrants(dTag, aggregateHash) before proxying; ungranted origins
+ * receive a `denied` error (RESOURCE-01 H-03 prevention).
+ */
+interface ResourceBytesRequest {
+    type: 'resource.bytes';
+    requestId: ResourceRequestId;
+    url: string;
+    /** Optional subset of fetch init (method, headers). Body bytes are shell-proxy-internal. */
+    init?: {
+        method?: string;
+        headers?: Readonly<Record<string, string>>;
+    };
+}
+/**
+ * Inbound: napplet cancels a previously-issued bytes request. Shell correlates
+ * to the in-flight request by requestId and emits a `resource.bytes.error`
+ * with `code: 'canceled'`.
+ */
+interface ResourceCancelRequest {
+    type: 'resource.cancel';
+    requestId: ResourceRequestId;
+}
+/**
+ * Outbound: successful fetch result.
+ */
+interface ResourceBytesResult {
+    type: 'resource.bytes.result';
+    requestId: ResourceRequestId;
+    status: number;
+    headers: Readonly<Record<string, string>>;
+    /** Raw response bytes, base64-encoded for the postMessage wire. */
+    bodyBase64: string;
+}
+/**
+ * Canonical typed-error codes for RESOURCE-03 cancel correlation + H-03
+ * ungranted-origin refusal.
+ */
+type ResourceErrorCode = 'denied' | 'canceled' | 'network-error' | 'invalid-url' | 'class-forbidden';
+/**
+ * Outbound: error result — used for both grant-refusal (RESOURCE-01) and
+ * cancel-correlation (RESOURCE-03) cases.
+ */
+interface ResourceBytesError {
+    type: 'resource.bytes.error';
+    requestId: ResourceRequestId;
+    code: ResourceErrorCode;
+    message: string;
+}
+/**
+ * Union of all inbound resource wire messages (napplet -> shell).
+ */
+type ResourceInbound = ResourceBytesRequest | ResourceCancelRequest;
+/**
+ * Union of all outbound resource wire messages (shell -> napplet).
+ */
+type ResourceOutbound = ResourceBytesResult | ResourceBytesError;
+
+export { type AclCheckEvent, type AclEntry, type AudioSource, type AuthHooks, type BrowserDeps, type ConfigHooks, type ConnectConsentRequest, type ConnectGrant, type ConnectGrantKey, type ConnectStore, type ConsentResult, type CryptoHooks, type DmHooks, type HotkeyHooks, type IdentityProxy, type IdentityProxyDeps, type KeysForwarder, type KeysForwarderDeps, type KeysForwarderOriginRegistry, type KeysForwarderSessionRegistry, type KeysProxy, type KeysProxyDeps, type ManifestCacheEntry, type MediaProxy, type MediaProxyDeps, type NotifyProxy, type NotifyProxyDeps, type ProxyOriginRegistry, type RelayConfigHooks, type RelayPoolHooks, type RelayPoolLike, type ResourceBytesError, type ResourceBytesRequest, type ResourceBytesResult, type ResourceCancelRequest, type ResourceErrorCode, type ResourceInbound, type ResourceOutbound, type ResourceRequestId, type ShellAdapter, type ShellBridge, type ShellCapabilities, type ThemeProxy, type ThemeProxyDeps, type WindowManagerHooks, type WorkerRelayHooks, type WorkerRelayLike, adaptHooks, audioManager, buildShellCapabilities, connectGrantKey, connectStore, createIdentityProxy, createKeysForwarder, createKeysProxy, createMediaProxy, createNotifyProxy, createShellBridge, createThemeProxy, manifestCache, nappKeyRegistry, originRegistry, sessionRegistry };