@kehto/paja 0.6.3 → 0.9.0

package/dist/index.d.ts

@@ -1,20 +1,47 @@
-import { P as PajaRawOptions, b as PajaHostConfig } from './server-qAXYczds.js';
-export { D as DEFAULT_PAJA_AGGREGATE_HASH, c as DEFAULT_PAJA_DTAG, d as DEFAULT_PAJA_HOST, e as DEFAULT_PAJA_PORT, f as DEFAULT_PAJA_RUNTIME_WAIT_MS, g as DEFAULT_PAJA_WINDOW_ID, h as DEFAULT_READY_TIMEOUT_MS, J as JsonPrimitive, i as JsonRecord, j as JsonValue, k as PAJA_SIMULATION_DOMAINS, l as PajaCapabilityDomain, a as PajaCommand, m as PajaHmrStrategy, n as PajaOptions, o as PajaOptionsError, p as PajaPointerRuntimeConfig, q as PajaServer, r as PajaServerOptions, t as PajaSimulation, u as PajaSimulationError, v as PajaSimulationRawOptions, x as PajaTargetMode, R as ReadinessError, y as ReadinessFetch, W as WaitForTargetUrlOptions, z as createPajaHostConfig, A as createPajaRuntimeHostConfig, B as formatPajaUrl, C as normalizePajaOptions, E as normalizePajaSimulation, s as startPajaServer, F as summarizePajaSimulation, w as waitForTargetUrl } from './server-qAXYczds.js';
+import { P as PajaRawOptions, b as PajaHostConfig } from './server-efRTBcMR.js';
+export { D as DEFAULT_PAJA_AGGREGATE_HASH, c as DEFAULT_PAJA_DTAG, d as DEFAULT_PAJA_HOST, e as DEFAULT_PAJA_PORT, f as DEFAULT_PAJA_RUNTIME_WAIT_MS, g as DEFAULT_PAJA_WINDOW_ID, h as DEFAULT_READY_TIMEOUT_MS, J as JsonPrimitive, i as JsonRecord, j as JsonValue, k as PAJA_SIMULATION_DOMAINS, l as PajaCapabilityDomain, a as PajaCommand, m as PajaHmrStrategy, n as PajaOptions, o as PajaOptionsError, p as PajaPointerRuntimeConfig, q as PajaServer, r as PajaServerOptions, t as PajaSimulation, u as PajaSimulationError, v as PajaSimulationRawOptions, x as PajaTargetMode, R as ReadinessError, y as ReadinessFetch, W as WaitForTargetUrlOptions, z as createPajaHostConfig, A as createPajaRuntimeHostConfig, B as formatPajaUrl, C as normalizePajaOptions, E as normalizePajaSimulation, s as startPajaServer, F as summarizePajaSimulation, w as waitForTargetUrl } from './server-efRTBcMR.js';
 import { NostrEvent } from 'nostr-tools';
 import { Filter } from 'nostr-tools/filter';
 import { ResolvedNapplet } from '@kehto/nip/5d';
 import { ShellCapabilities } from '@kehto/shell';
+import { IntentCatalogEntry, IntentTargetController, IntentRetentionParams, IntentRetainedDelivery } from '@kehto/services';
 
+/**
+ * Load a JSON Paja config file from disk.
+ *
+ * @param configPath - Path to a JSON config file.
+ * @returns Raw options parsed from the config file.
+ */
 declare function loadPajaConfigFile(configPath: string): PajaRawOptions;
+/**
+ * Resolve raw options by merging an optional config file with explicit values.
+ *
+ * @param raw - CLI/config options, optionally including `configPath`.
+ * @returns Raw options with config-file defaults applied.
+ */
 declare function resolvePajaRawOptions(raw: PajaRawOptions): PajaRawOptions;
+/**
+ * Merge two raw Paja option objects, with override values taking precedence.
+ *
+ * @param base - Base options, usually from a config file.
+ * @param override - Explicit options, usually from CLI args.
+ * @returns Merged raw options.
+ */
 declare function mergePajaRawOptions(base: PajaRawOptions, override: PajaRawOptions): PajaRawOptions;
 
+/**
+ * Render the browser host page for a Paja runtime config.
+ *
+ * @param config - Serializable host-page config.
+ * @returns Complete HTML document served by Paja.
+ */
 declare function renderPajaHtml(config: PajaHostConfig): string;
 
 /** Named/addressable NIP-5D napplet manifest kind (`35129`). */
 declare const PAJA_NAPPLET_MANIFEST_KIND = 35129;
 /** All NIP-5D napplet manifest kinds accepted by Paja pointers (`5129`, `15129`, `35129`). */
 declare const PAJA_NAPPLET_MANIFEST_KINDS: readonly number[];
+/** Decoded naddr/nevent pointer accepted by Paja runtime-pointer mode. */
 type PajaDecodedPointer = {
     readonly type: 'naddr';
     readonly value: string;
@@ -30,44 +57,292 @@ type PajaDecodedPointer = {
     readonly kind?: number;
     readonly relays: readonly string[];
 };
+/** Fully resolved pointer plus verified napplet artifact bytes. */
 interface PajaResolvedPointer {
+    /** Decoded pointer input. */
     readonly pointer: PajaDecodedPointer;
+    /** Manifest event resolved from relays. */
     readonly event: NostrEvent;
+    /** Ordered relay URLs queried for the pointer, with embedded hints first. */
     readonly relays: readonly string[];
+    /** Blossom server hints used for blob fetches. */
     readonly blossomServers: readonly string[];
+    /** Resolved manifest `d` tag. */
     readonly dTag: string;
+    /** Verified NIP-5A aggregate hash. */
     readonly aggregateHash: string;
+    /** Verified target `/index.html` content. */
     readonly indexHtml: string;
+    /** Parsed NIP-5D manifest. */
     readonly manifest: ResolvedNapplet['manifest'];
 }
+/** Relay-pool contract for runtime-pointer resolution. */
 interface PajaPointerRelayPool {
+    /** Query relays synchronously for matching manifest events. */
     querySync(relays: string[], filter: Filter, params?: {
         readonly maxWait?: number;
         readonly label?: string;
         readonly id?: string;
     }): Promise<NostrEvent[]>;
+    /** Subscribe until all relays reach EOSE, fail, or the shared deadline expires. */
+    subscribeManyEose?(relays: string[], filter: Filter, params: {
+        readonly maxWait?: number;
+        readonly label?: string;
+        readonly id?: string;
+        readonly onevent: (event: NostrEvent) => void;
+        readonly onclose: (reasons: string[]) => void;
+    }): {
+        close(reason?: string): void | Promise<void>;
+    };
     close?(relays: string[]): void;
     destroy?(): void;
 }
+/** Options for resolving a Paja runtime pointer. */
 interface ResolvePajaPointerOptions {
+    /** Relay pool override; defaults to a `nostr-tools` `SimplePool`. */
     readonly pool?: PajaPointerRelayPool;
+    /** Fetch override used for Blossom blob URLs. */
     readonly fetcher?: (url: string) => Promise<Response>;
+    /** Extra relay candidates appended after embedded pointer hints. */
     readonly relays?: readonly string[];
+    /** Extra Blossom server hints appended during artifact fetch. */
     readonly blossomServers?: readonly string[];
+    /** One overall deadline for relay connection, fanout, and EOSE in milliseconds. */
     readonly maxWaitMs?: number;
 }
+/**
+ * Decode a NIP-19 naddr/nevent pointer for Paja runtime-pointer mode.
+ *
+ * @param value - NIP-19 pointer string.
+ * @returns Structured pointer metadata.
+ */
 declare function decodePajaPointer(value: string): PajaDecodedPointer;
+/**
+ * Resolve a Paja runtime pointer into verified napplet HTML and manifest data.
+ *
+ * @param value - NIP-19 naddr or nevent pointer.
+ * @param options - Relay, fetch, and Blossom overrides.
+ * @returns Verified napplet artifact ready for srcdoc injection.
+ */
 declare function resolvePajaPointer(value: string, options?: ResolvePajaPointerOptions): Promise<PajaResolvedPointer>;
+/**
+ * Inject Kehto's Class-1 CSP for verified runtime-pointer srcdoc output.
+ * NIP-5D mandates the verified srcdoc and opaque sandbox, but this baseline CSP
+ * is Kehto policy rather than a protocol requirement.
+ *
+ * @param html - Verified target HTML.
+ * @param origins - Origins the resolved target may connect to.
+ * @returns HTML with a CSP meta tag inserted.
+ */
 declare function injectPajaRuntimeCsp(html: string, origins: readonly string[]): string;
 
-declare const PAJA_UPSTREAM_WEB_DOMAINS: readonly ["ble", "common", "config", "count", "cvm", "dm", "identity", "ifc", "inc", "intent", "keys", "link", "lists", "media", "notify", "outbox", "relay", "resource", "serial", "storage", "theme", "upload", "webrtc"];
+declare const PAJA_LEGACY_COMPATIBILITY_DOMAIN: string;
+/** Domain list mirrored from the upstream web runtime for parity checks. */
+declare const PAJA_UPSTREAM_WEB_DOMAINS: readonly ["ble", "common", "config", "count", "cvm", "dm", "identity", string, "inc", "intent", "keys", "link", "lists", "media", "notify", "outbox", "relay", "resource", "serial", "storage", "theme", "upload", "webrtc"];
+/** Domains required during the initial Paja handshake. */
 declare const PAJA_HANDSHAKE_DOMAINS: readonly ["shell"];
+/** Compatibility aliases for renamed upstream capability domains. */
 declare const PAJA_COMPATIBILITY_ALIASES: {
-    readonly ifc: "inc";
+    readonly [PAJA_LEGACY_COMPATIBILITY_DOMAIN]: "inc";
 };
+/** Domains Paja advertises through its simulated shell capability surface. */
 declare const PAJA_ADVERTISED_DOMAINS: readonly ["relay", "outbox", "identity", "storage", "inc", "theme", "keys", "link", "common", "lists", "serial", "ble", "webrtc", "media", "notify", "config", "resource", "cvm", "upload", "intent", "count"];
+/** Service names Paja expects the host runtime to provide. */
 declare const PAJA_REQUIRED_SERVICES: readonly ["config", "cvm", "identity", "intent", "keys", "link", "common", "lists", "serial", "ble", "webrtc", "media", "notifications", "notify", "outbox", "relay", "resource", "theme", "upload", "count"];
+/**
+ * Find advertised Paja domains missing from a shell capability snapshot.
+ *
+ * @param capabilities - Shell capability snapshot to inspect.
+ * @returns Advertised domains not present in the snapshot.
+ */
 declare function getMissingAdvertisedDomains(capabilities: ShellCapabilities): string[];
+/**
+ * Find required service names missing from a runtime service list.
+ *
+ * @param services - Runtime service names to inspect.
+ * @returns Required service names that are absent.
+ */
 declare function getMissingServices(services: readonly string[]): string[];
 
-export { PAJA_ADVERTISED_DOMAINS, PAJA_COMPATIBILITY_ALIASES, PAJA_HANDSHAKE_DOMAINS, PAJA_NAPPLET_MANIFEST_KIND, PAJA_NAPPLET_MANIFEST_KINDS, PAJA_REQUIRED_SERVICES, PAJA_UPSTREAM_WEB_DOMAINS, type PajaDecodedPointer, PajaHostConfig, type PajaPointerRelayPool, PajaRawOptions, type PajaResolvedPointer, type ResolvePajaPointerOptions, decodePajaPointer, getMissingAdvertisedDomains, getMissingServices, injectPajaRuntimeCsp, loadPajaConfigFile, mergePajaRawOptions, renderPajaHtml, resolvePajaPointer, resolvePajaRawOptions };
+/**
+ * Persistent Paja catalog of resolver-verified napplet installations.
+ *
+ * The catalog deliberately contains only serializable facts copied from a
+ * verified pointer result. Runtime frames, sessions, and controller state are
+ * owned elsewhere, so closing a tab cannot alter handler eligibility.
+ *
+ * @packageDocumentation
+ */
+
+/** Serializable verified pointer and manifest facts for one installed napplet. */
+interface InstalledNappletRecord {
+    /** Verified manifest d-tag used as the handler identity. */
+    readonly dTag: string;
+    /** Verified NIP-5A aggregate hash for the installed artifact. */
+    readonly aggregateHash: string;
+    /** Pointer identity that can later be re-resolved and verified. */
+    readonly pointer: PajaDecodedPointer;
+    /** Optional manifest title for handler selection UI. */
+    readonly title?: string;
+    /** Exact manifest convention contracts used for intent eligibility. */
+    readonly archetypes: readonly {
+        readonly slug: string;
+        readonly convention: string;
+        readonly eventKinds?: readonly number[];
+    }[];
+}
+/** Listener notified when an installed artifact is inserted or removed. */
+type InstalledNappletCatalogListener = (dTag: string) => void;
+/**
+ * Stores verified Paja installations separately from the browser runtime.
+ *
+ * @example
+ * ```ts
+ * const catalog = new InstalledNappletCatalog();
+ * catalog.install(resolvedPointer);
+ * const candidates = catalog.intentCatalog();
+ * ```
+ */
+declare class InstalledNappletCatalog {
+    private readonly records;
+    private readonly listeners;
+    /** Insert or replace a record from an already resolver-verified pointer. */
+    install(resolved: PajaResolvedPointer): InstalledNappletRecord;
+    /** Remove an artifact explicitly; frame teardown never calls this method. */
+    remove(dTag: string): boolean;
+    /** Return whether a verified installation exists for a d-tag. */
+    has(dTag: string): boolean;
+    /** Return immutable serializable installed-artifact facts. */
+    installed(): readonly InstalledNappletRecord[];
+    /** Return a verified record by d-tag. */
+    get(dTag: string): InstalledNappletRecord | undefined;
+    /**
+     * Atomically confirm that a resolved target still belongs to the exact record
+     * selected before an async operation. The record object is the catalog version
+     * token, so even a same-identity replacement cannot pass this check.
+     */
+    validateCurrent(selected: InstalledNappletRecord, target: Pick<InstalledNappletRecord, 'dTag' | 'aggregateHash'>): InstalledNappletRecord | null;
+    /** Return exact handler candidates derived only from installed manifests. */
+    intentCatalog(): IntentCatalogEntry[];
+    /** Subscribe to explicit install and artifact-removal changes. */
+    onChanged(listener: InstalledNappletCatalogListener): () => void;
+    private notify;
+}
+
+/**
+ * Browser-owned retained NAP-INTENT target lifecycle policy.
+ *
+ * Retention is intentionally independent from browser frames. The host supplies
+ * generation creation/reuse, source-bound readiness, current-generation checks,
+ * and delivery. This controller freezes responsibility before an accepted
+ * result, then starts that policy only afterward.
+ *
+ * @packageDocumentation
+ */
+
+/** Opaque current target generation controlled by the browser host. */
+interface BrowserIntentGeneration {
+    /** Host-owned stable identifier for one target generation. */
+    readonly id: string;
+}
+/** Terminal reasons exposed only to host observability and cleanup policy. */
+type BrowserIntentTerminalReason = 'open-failed' | 'ready-failed' | 'no-current-target' | 'send-failed';
+/** Browser lifecycle callbacks injected by the Paja host. */
+interface BrowserIntentControllerOptions {
+    /** Open a compatible target or reuse its current generation. */
+    openOrReuse(params: IntentRetentionParams, attempt: number): BrowserIntentGeneration | null | Promise<BrowserIntentGeneration | null>;
+    /** Await source-bound NAP-SHELL readiness for a selected generation. */
+    waitForReady(generation: BrowserIntentGeneration): void | Promise<void>;
+    /** Return true only while the generation remains the selected current target. */
+    isCurrent(generation: BrowserIntentGeneration): boolean | Promise<boolean>;
+    /** Send the retained delivery to the current ready generation exactly once. */
+    send(generation: BrowserIntentGeneration, delivery: IntentRetentionParams['delivery']): void | Promise<void>;
+    /** Maximum open/replacement attempts after acceptance. Finite values clamp to 1–10; defaults to two. */
+    maxAttempts?: number;
+    /** Observe terminal post-acceptance policy without producing another result. */
+    onTerminal?(params: IntentRetentionParams, reason: BrowserIntentTerminalReason): void;
+}
+/**
+ * Retains immutable delivery responsibility before the intent service accepts.
+ *
+ * It has no public lifecycle state: host callbacks own generation identity,
+ * readiness, reuse, and replacement. A returned task is inert until its
+ * `start()` method is invoked by the intent service after sending acceptance.
+ */
+declare class BrowserIntentController implements IntentTargetController {
+    private readonly options;
+    private readonly maxAttempts;
+    constructor(options: BrowserIntentControllerOptions);
+    retain(params: IntentRetentionParams): IntentRetainedDelivery;
+    private start;
+}
+
+/**
+ * Target dev-server CORS diagnostics.
+ *
+ * Paja loads the napplet target into a `srcdoc` iframe sandboxed without
+ * `allow-same-origin`, so the napplet document has an opaque origin and sends
+ * `Origin: null` on every subresource fetch. `<script type="module">` is always
+ * fetched in CORS mode, so a dev server that does not allow the `null` origin
+ * blocks the napplet's entry module and the iframe renders blank.
+ *
+ * These helpers probe the target with an explicit `Origin: null` request so
+ * Paja can report the cause instead of leaving an empty frame behind.
+ */
+/** Whether the target dev server will serve the sandboxed frame's subresources. */
+type PajaTargetCorsStatus = 'allowed' | 'blocked' | 'unreachable';
+/** Result of probing a target dev server for opaque-origin CORS support. */
+interface PajaTargetCorsDiagnostic {
+    /** Classification of the probe result. */
+    readonly status: PajaTargetCorsStatus;
+    /** Target URL that was probed. */
+    readonly targetUrl: string;
+    /** `access-control-allow-origin` value the target returned, when any. */
+    readonly allowOrigin: string | null;
+    /** Human-readable explanation of the classification. */
+    readonly detail: string;
+    /** Actionable remedy, present only when `status` is not `allowed`. */
+    readonly hint: string | null;
+}
+/** Remedy shown whenever the target rejects the sandboxed frame's `null` origin. */
+declare const PAJA_TARGET_CORS_HINT: string;
+/**
+ * Classify an `access-control-allow-origin` response value for an opaque origin.
+ *
+ * @param targetUrl - Target URL the header came from.
+ * @param allowOrigin - Raw `access-control-allow-origin` header value, or `null` when absent.
+ * @returns Diagnostic describing whether the sandboxed frame can load assets.
+ * @example
+ * ```ts
+ * classifyTargetCors('http://127.0.0.1:5173/', '*').status; // 'allowed'
+ * classifyTargetCors('http://127.0.0.1:5173/', null).status; // 'blocked'
+ * ```
+ */
+declare function classifyTargetCors(targetUrl: string, allowOrigin: string | null): PajaTargetCorsDiagnostic;
+/** Minimal fetch surface the probe depends on. */
+type PajaTargetCorsFetch = (input: string, init: {
+    method: string;
+    headers: Record<string, string>;
+}) => Promise<{
+    headers: {
+        get(name: string): string | null;
+    };
+}>;
+/**
+ * Probe a target dev server for opaque-origin CORS support.
+ *
+ * Sends `Origin: null` explicitly — a browser cannot forge that header, but the
+ * Paja server can, which is why the probe runs server-side.
+ *
+ * @param targetUrl - Absolute target URL served by the napplet dev server.
+ * @param fetchImpl - Fetch implementation; defaults to the global `fetch`.
+ * @returns Diagnostic describing whether the sandboxed frame can load assets.
+ * @example
+ * ```ts
+ * const diagnostic = await probeTargetCors('http://127.0.0.1:5173/');
+ * if (diagnostic.status === 'blocked') console.warn(diagnostic.hint);
+ * ```
+ */
+declare function probeTargetCors(targetUrl: string, fetchImpl?: PajaTargetCorsFetch): Promise<PajaTargetCorsDiagnostic>;
+
+export { BrowserIntentController, type BrowserIntentControllerOptions, type BrowserIntentGeneration, type BrowserIntentTerminalReason, InstalledNappletCatalog, type InstalledNappletCatalogListener, type InstalledNappletRecord, PAJA_ADVERTISED_DOMAINS, PAJA_COMPATIBILITY_ALIASES, PAJA_HANDSHAKE_DOMAINS, PAJA_NAPPLET_MANIFEST_KIND, PAJA_NAPPLET_MANIFEST_KINDS, PAJA_REQUIRED_SERVICES, PAJA_TARGET_CORS_HINT, PAJA_UPSTREAM_WEB_DOMAINS, type PajaDecodedPointer, PajaHostConfig, type PajaPointerRelayPool, PajaRawOptions, type PajaResolvedPointer, type PajaTargetCorsDiagnostic, type PajaTargetCorsFetch, type PajaTargetCorsStatus, type ResolvePajaPointerOptions, classifyTargetCors, decodePajaPointer, getMissingAdvertisedDomains, getMissingServices, injectPajaRuntimeCsp, loadPajaConfigFile, mergePajaRawOptions, probeTargetCors, renderPajaHtml, resolvePajaPointer, resolvePajaRawOptions };

package/dist/index.js

@@ -1,4 +1,5 @@
 import {
+  BrowserIntentController,
   DEFAULT_PAJA_AGGREGATE_HASH,
   DEFAULT_PAJA_DTAG,
   DEFAULT_PAJA_HOST,
@@ -6,6 +7,7 @@ import {
   DEFAULT_PAJA_RUNTIME_WAIT_MS,
   DEFAULT_PAJA_WINDOW_ID,
   DEFAULT_READY_TIMEOUT_MS,
+  InstalledNappletCatalog,
   PAJA_ADVERTISED_DOMAINS,
   PAJA_COMPATIBILITY_ALIASES,
   PAJA_HANDSHAKE_DOMAINS,
@@ -13,10 +15,12 @@ import {
   PAJA_NAPPLET_MANIFEST_KINDS,
   PAJA_REQUIRED_SERVICES,
   PAJA_SIMULATION_DOMAINS,
+  PAJA_TARGET_CORS_HINT,
   PAJA_UPSTREAM_WEB_DOMAINS,
   PajaOptionsError,
   PajaSimulationError,
   ReadinessError,
+  classifyTargetCors,
   createPajaHostConfig,
   createPajaRuntimeHostConfig,
   decodePajaPointer,
@@ -28,14 +32,16 @@ import {
   mergePajaRawOptions,
   normalizePajaOptions,
   normalizePajaSimulation,
+  probeTargetCors,
   renderPajaHtml,
   resolvePajaPointer,
   resolvePajaRawOptions,
   startPajaServer,
   summarizePajaSimulation,
   waitForTargetUrl
-} from "./chunk-ADMLM2LH.js";
+} from "./chunk-OWVINAW7.js";
 export {
+  BrowserIntentController,
   DEFAULT_PAJA_AGGREGATE_HASH,
   DEFAULT_PAJA_DTAG,
   DEFAULT_PAJA_HOST,
@@ -43,6 +49,7 @@ export {
   DEFAULT_PAJA_RUNTIME_WAIT_MS,
   DEFAULT_PAJA_WINDOW_ID,
   DEFAULT_READY_TIMEOUT_MS,
+  InstalledNappletCatalog,
   PAJA_ADVERTISED_DOMAINS,
   PAJA_COMPATIBILITY_ALIASES,
   PAJA_HANDSHAKE_DOMAINS,
@@ -50,10 +57,12 @@ export {
   PAJA_NAPPLET_MANIFEST_KINDS,
   PAJA_REQUIRED_SERVICES,
   PAJA_SIMULATION_DOMAINS,
+  PAJA_TARGET_CORS_HINT,
   PAJA_UPSTREAM_WEB_DOMAINS,
   PajaOptionsError,
   PajaSimulationError,
   ReadinessError,
+  classifyTargetCors,
   createPajaHostConfig,
   createPajaRuntimeHostConfig,
   decodePajaPointer,
@@ -65,6 +74,7 @@ export {
   mergePajaRawOptions,
   normalizePajaOptions,
   normalizePajaSimulation,
+  probeTargetCors,
   renderPajaHtml,
   resolvePajaPointer,
   resolvePajaRawOptions,