@kehto/nip 0.1.0 → 0.4.0

package/README.md

@@ -1,37 +1,73 @@
 # @kehto/nip
 
-A tree-shakable bundle of unique Nostr NIP utilities for napplet runtimes. Each
-NIP lives at its own subpath so consumers import only what they use; the package
-is `sideEffects: false`, so bundlers drop any NIP that isn't referenced.
+A tree-shakable bundle of **unique** Nostr NIP utilities for napplet runtimes —
+the NIPs that `nostr-tools` does *not* ship but that relay-aware runtimes
+commonly need. Each NIP lives in its own folder at its own subpath, so consumers
+import only what they use; the package is `sideEffects: false`, so bundlers drop
+any NIP that isn't referenced.
 
 ## NIPs
 
 | Subpath | NIP | What it provides |
 |---------|-----|------------------|
-| `@kehto/nip/66` | NIP-66 | kind-30166 relay-discovery aggregator (`createNip66Aggregator`) |
+| [`@kehto/nip/5a`](./src/5a/README.md) | NIP-5A | aggregate hash compute/verify over `path` tags (`computeAggregateHash`, `verifyAggregate`) |
+| [`@kehto/nip/5d`](./src/5d/README.md) | NIP-5D | content-addressed napplet manifest resolution — parse, verify sig + aggregate + Blossom blobs (`resolveNapplet`) with optional Cache Storage artifact caching |
+| [`@kehto/nip/51`](./src/51/README.md) | NIP-51 | lists & sets parser — mute/bookmarks/relay-sets/emoji-sets/… (`parseList`) |
+| [`@kehto/nip/65`](./src/65/README.md) | NIP-65 | relay-list (kind 10002) parsing + outbox/inbox resolution (`createNip65Registry`) |
+| [`@kehto/nip/66`](./src/66/README.md) | NIP-66 | kind-30166 relay-discovery aggregator (`createNip66Aggregator`) |
+| [`@kehto/nip/89`](./src/89/README.md) | NIP-89 | app-handler discovery (kind 31989/31990) (`parseHandlerInformation`) |
 
+Each subpath has its own README with full API docs and examples (linked above).
 More unique NIPs are added as their own subpath (`@kehto/nip/<n>`) over time.
 
+For browser hosts that want repeated NIP-5D loads to reuse verified artifact
+bytes, see the repo guide:
+[Implement a napplet artifact cache](https://kehto.github.io/web/docs/how-tos/implement-napplet-artifact-cache).
+
+## Selection criteria
+
+A NIP earns a place here only if it is:
+
+1. **Unique** — not already provided by `nostr-tools` (re-wrapping `nip04`,
+   `nip19`, `nip25`, `nip44`, `nip57`, … would be a no-op package).
+2. **Broadly needed** — likely required by many runtimes, not just one app.
+3. **Substantive** — handles a real common case in a widely-compatible way, with
+   no framework coupling and no module-global state.
+
 ## Usage
 
 ```ts
 // Import only the NIP you need — nothing else is bundled.
-import { createNip66Aggregator } from '@kehto/nip/66';
+import { createNip65Registry } from '@kehto/nip/65';
 
-const aggregator = createNip66Aggregator({
-  pool: myPoolAdapter,
-  bootstrap: ['wss://monitor.example.com'],
-});
-aggregator.start();
+const registry = createNip65Registry();
+registry.ingest(kind10002Event);
+const outbox = registry.resolveOutboxRelays([authorPubkey]);
 ```
 
 A convenience barrel re-export is also available at the package root
 (`@kehto/nip`), but prefer subpath imports for the smallest bundles.
 
+## Conventions
+
+Every NIP module is:
+
+- **Pure / framework-agnostic** — no Svelte/React, no DOM assumptions, no relay
+  library baked in. Relay pools, signers, and decryptors are injected via small
+  interfaces.
+- **Multi-instance safe** — stateful helpers are closure-scoped factories
+  (`create*`), never module globals, so multiple runtimes in one process never
+  alias each other.
+- **Fully documented** — all public exports carry JSDoc with `@param`,
+  `@returns`, and `@example`.
+
 ## Adding a NIP
 
-1. Add `src/<n>.ts` implementing the NIP utility (framework-agnostic, no
-   module-global state, inject relay/pool concerns via interfaces).
-2. Add `src/<n>.ts` to the `tsup` `entry` array and the `./<n>` `exports` entry
-   in `package.json`.
-3. Re-export it from `src/index.ts` for the barrel.
+1. Create `src/<n>/index.ts` implementing the NIP utility (framework-agnostic, no
+   module-global state, inject relay/pool/crypto concerns via interfaces).
+2. Add `src/<n>/index.test.ts` with unit tests and `src/<n>/README.md` with API docs.
+3. Add `src/<n>/index.ts` to the `tsup` `entry` array and a `./<n>` entry to
+   `exports` in `package.json`.
+4. Re-export it from `src/index.ts` for the barrel, and add the
+   `@kehto/nip/<n>` alias to the repo `vitest.config.ts`.
+5. Add a row to the table above.

package/dist/51/index.d.ts

@@ -0,0 +1,157 @@
+import { NostrEvent } from 'nostr-tools';
+
+/**
+ * `@kehto/nip/51` — NIP-51 list & set parsing.
+ *
+ * NIP-51 organizes user data into two families of events whose items live in
+ * tags (public) and, optionally, in NIP-44-encrypted content (private):
+ *
+ * - **Standard lists** — replaceable, kinds `10000`–`10101`. One per user per
+ *   kind (e.g. mute list, bookmarks, blocked relays, DM relays).
+ * - **Sets** — addressable / parameterized-replaceable, kinds `30000`–`30030`.
+ *   Many per user, distinguished by a `d` identifier (e.g. follow sets, relay
+ *   sets, emoji sets, curation sets).
+ *
+ * `nostr-tools` ships no NIP-51 helper. This module provides a single
+ * widely-compatible parser that turns either family into a structured
+ * {@link Nip51List}, plus item accessors and an injected-decryptor path for
+ * private items (so the package stays crypto-free and framework-agnostic).
+ */
+/** Canonical NIP-51 **standard list** kinds (replaceable, one per author). */
+declare const LIST_KINDS: Readonly<Record<number, string>>;
+/** Canonical NIP-51 **set** kinds (addressable, many per author by `d`). */
+declare const SET_KINDS: Readonly<Record<number, string>>;
+/**
+ * Item-bearing NIP-51 tag names — the tags that carry list *content* (as
+ * opposed to metadata tags like `d`, `title`, `image`, `description`).
+ */
+declare const ITEM_TAGS: readonly ["e", "p", "a", "t", "r", "word", "emoji", "relay", "g", "i", "k"];
+/** Whether `kind` is a NIP-51 standard list kind (`10000`–`10101`). */
+declare function isListKind(kind: number): boolean;
+/** Whether `kind` is a NIP-51 set kind (`30000`–`30030`). */
+declare function isSetKind(kind: number): boolean;
+/**
+ * Friendly name for a NIP-51 list/set kind (e.g. `10000` → `'mute'`,
+ * `30030` → `'emoji-sets'`), or `undefined` if `kind` is not a known NIP-51 kind.
+ */
+declare function listKindName(kind: number): string | undefined;
+/**
+ * A parsed NIP-51 list or set.
+ *
+ * `publicItems` holds the item-bearing tags verbatim. `privateItems` is
+ * populated only after {@link decryptPrivateItems} runs; until then it is
+ * `undefined` (the encrypted payload is left untouched in {@link Nip51List.encryptedContent}).
+ *
+ * @example
+ * ```ts
+ * const list = parseList(kind10000MuteEvent);
+ * list.kind;        // 10000
+ * list.type;        // 'mute'
+ * list.family;      // 'list'
+ * getTagValues(list.publicItems, 'p'); // muted pubkeys (public portion)
+ * ```
+ */
+interface Nip51List {
+    /** Event kind. */
+    kind: number;
+    /** `'list'` for standard lists (10000–10101), `'set'` for sets (30000–30030), `'unknown'` otherwise. */
+    family: 'list' | 'set' | 'unknown';
+    /** Friendly kind name from {@link listKindName}, or `undefined` for unknown kinds. */
+    type: string | undefined;
+    /** Author pubkey. */
+    pubkey: string;
+    /** Set identifier from the `d` tag (sets only; `''` for standard lists / missing). */
+    identifier: string;
+    /** Addressable coordinate `kind:pubkey:d` for sets; `undefined` for standard lists. */
+    address: string | undefined;
+    /** Optional `title` tag (sets). */
+    title: string | undefined;
+    /** Optional `image` tag (sets). */
+    image: string | undefined;
+    /** Optional `description` tag (sets). */
+    description: string | undefined;
+    /** Item-bearing tags verbatim (the public portion of the list). */
+    publicItems: string[][];
+    /** Raw NIP-44-encrypted content, if any (the private portion). */
+    encryptedContent: string | undefined;
+    /** Decrypted private item tags — `undefined` until {@link decryptPrivateItems} succeeds. */
+    privateItems: string[][] | undefined;
+}
+/**
+ * Parse a NIP-51 list or set event into a structured {@link Nip51List}.
+ *
+ * Works for any kind: known list/set kinds get a `type` and correct `family`;
+ * unknown kinds still parse (`family: 'unknown'`) so forward-compatible callers
+ * can handle new list kinds before this table is updated.
+ *
+ * Item-bearing tags (see {@link ITEM_TAGS}) become {@link Nip51List.publicItems};
+ * metadata tags (`d`, `title`, `image`, `description`, …) are lifted into named
+ * fields. The encrypted `content` is preserved verbatim in
+ * {@link Nip51List.encryptedContent} — call {@link decryptPrivateItems} with a
+ * NIP-44 decryptor to populate {@link Nip51List.privateItems}.
+ *
+ * @param event - A NIP-51 list or set event
+ * @returns The structured list/set
+ *
+ * @example
+ * ```ts
+ * import { parseList, getTagValues } from '@kehto/nip/51';
+ * const bookmarks = parseList(kind10003Event);
+ * const notes = getTagValues(bookmarks.publicItems, 'e');
+ * ```
+ */
+declare function parseList(event: NostrEvent): Nip51List;
+/**
+ * Collect the values (`tag[1]`) of every item tag with the given name.
+ *
+ * @param items - Item tags ({@link Nip51List.publicItems} or {@link Nip51List.privateItems})
+ * @param tagName - Tag name to filter on (e.g. `'p'`, `'e'`, `'a'`, `'t'`, `'word'`)
+ * @returns The second element of each matching tag (missing values skipped)
+ *
+ * @example
+ * ```ts
+ * const mutedPubkeys = getTagValues(list.publicItems, 'p');
+ * const mutedWords = getTagValues(list.publicItems, 'word');
+ * ```
+ */
+declare function getTagValues(items: ReadonlyArray<ReadonlyArray<string>>, tagName: string): string[];
+/**
+ * A NIP-44 decryptor: takes the event's `content` and the author pubkey and
+ * returns the plaintext (a JSON array of tags). Inject your signer's
+ * `nip44.decrypt` (e.g. a NIP-07 `window.nostr.nip44`, a bunker, or
+ * `nostr-tools/nip44`) so this package carries no crypto dependency.
+ *
+ * @example
+ * ```ts
+ * const decrypt: Nip44Decryptor = (content, author) =>
+ *   window.nostr!.nip44!.decrypt(author, content);
+ * ```
+ */
+type Nip44Decryptor = (content: string, authorPubkey: string) => string | Promise<string>;
+/**
+ * Decrypt the private portion of a list/set and populate
+ * {@link Nip51List.privateItems}.
+ *
+ * NIP-51 stores private items as a NIP-44-encrypted JSON array of tags in the
+ * event `content`, encrypted to the author's own key. This helper runs the
+ * injected {@link Nip44Decryptor}, parses the plaintext as `string[][]`, and
+ * returns a **new** {@link Nip51List} with `privateItems` set (the input is not
+ * mutated). Lists with no encrypted content return a copy with
+ * `privateItems: []`.
+ *
+ * Throws if the decryptor throws or the plaintext is not a JSON tag array — so
+ * callers can distinguish "no private items" from "couldn't read private items".
+ *
+ * @param list - A parsed list from {@link parseList}
+ * @param decrypt - Injected NIP-44 decryptor
+ * @returns A copy of `list` with `privateItems` populated
+ *
+ * @example
+ * ```ts
+ * const withPrivate = await decryptPrivateItems(list, (c, a) => signer.nip44.decrypt(a, c));
+ * const privatelyMuted = getTagValues(withPrivate.privateItems!, 'p');
+ * ```
+ */
+declare function decryptPrivateItems(list: Nip51List, decrypt: Nip44Decryptor): Promise<Nip51List>;
+
+export { ITEM_TAGS, LIST_KINDS, type Nip44Decryptor, type Nip51List, SET_KINDS, decryptPrivateItems, getTagValues, isListKind, isSetKind, listKindName, parseList };

package/dist/51/index.js

@@ -0,0 +1,23 @@
+import {
+  ITEM_TAGS,
+  LIST_KINDS,
+  SET_KINDS,
+  decryptPrivateItems,
+  getTagValues,
+  isListKind,
+  isSetKind,
+  listKindName,
+  parseList
+} from "../chunk-2XYRP2S6.js";
+export {
+  ITEM_TAGS,
+  LIST_KINDS,
+  SET_KINDS,
+  decryptPrivateItems,
+  getTagValues,
+  isListKind,
+  isSetKind,
+  listKindName,
+  parseList
+};
+//# sourceMappingURL=index.js.map

package/dist/5a/index.d.ts

@@ -0,0 +1,64 @@
+/**
+ * One published file: an absolute path and the lowercase-hex SHA-256 of its
+ * bytes. Parsed from a NIP-5A `["path", "<abs-path>", "<sha256>"]` tag.
+ *
+ * @example
+ * ```ts
+ * const entry: PathEntry = { path: '/index.html', sha256: '186ea5…1c99' };
+ * ```
+ */
+interface PathEntry {
+    /** Absolute path of the file (the `path` tag's second element). */
+    path: string;
+    /** Lowercase-hex SHA-256 of the file bytes (the `path` tag's third element). */
+    sha256: string;
+}
+/**
+ * Compute the NIP-5A aggregate hash over a set of {@link PathEntry} files.
+ *
+ * Lines (`"<sha256> <abs-path>\n"`) are sorted before hashing, so the result is
+ * independent of the input order.
+ *
+ * @param entries - The file path entries (any order)
+ * @returns The aggregate hash as lowercase hex
+ *
+ * @example
+ * ```ts
+ * import { computeAggregateHash } from '@kehto/nip/5a';
+ * const hex = computeAggregateHash([{ path: '/index.html', sha256: 'aa…' }]);
+ * ```
+ */
+declare function computeAggregateHash(entries: readonly PathEntry[]): string;
+/**
+ * Extract {@link PathEntry} objects from an event's tags, keeping only
+ * well-formed `["path", "<abs-path>", "<sha256>"]` tags in tag order.
+ *
+ * @param tags - The manifest event's tags
+ * @returns Parsed path entries (malformed `path` tags are skipped)
+ */
+declare function pathEntriesFromTags(tags: readonly (readonly string[])[]): PathEntry[];
+/**
+ * Read the aggregate hash declared by an event's `["x", "<hex>", "aggregate"]`
+ * tag.
+ *
+ * @param tags - The manifest event's tags
+ * @returns The declared aggregate hex, or `undefined` if no aggregate `x` tag
+ */
+declare function aggregateTagValue(tags: readonly (readonly string[])[]): string | undefined;
+/**
+ * Verify that an event's declared aggregate `x` tag equals the aggregate
+ * recomputed from its `path` tags.
+ *
+ * @param tags - The manifest event's tags
+ * @returns `true` only when an aggregate `x` tag is present and matches the
+ *   recomputed value; `false` otherwise (mismatch or missing aggregate tag)
+ *
+ * @example
+ * ```ts
+ * import { verifyAggregate } from '@kehto/nip/5a';
+ * if (!verifyAggregate(manifestEvent.tags)) throw new Error('aggregate mismatch');
+ * ```
+ */
+declare function verifyAggregate(tags: readonly (readonly string[])[]): boolean;
+
+export { type PathEntry, aggregateTagValue, computeAggregateHash, pathEntriesFromTags, verifyAggregate };

package/dist/5a/index.js

@@ -0,0 +1,13 @@
+import {
+  aggregateTagValue,
+  computeAggregateHash,
+  pathEntriesFromTags,
+  verifyAggregate
+} from "../chunk-2J3CSGKL.js";
+export {
+  aggregateTagValue,
+  computeAggregateHash,
+  pathEntriesFromTags,
+  verifyAggregate
+};
+//# sourceMappingURL=index.js.map

package/dist/5a/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/5d/index.d.ts

@@ -0,0 +1,320 @@
+import { NostrEvent } from 'nostr-tools';
+import { PathEntry } from '../5a/index.js';
+
+/** Versioned Cache Storage namespace for verified napplet artifacts. */
+declare const NAPPLET_ARTIFACT_CACHE_NAME = "kehto:napplet-artifacts:v1";
+interface NappletCacheDiagnostic {
+    type: 'cache-open-failed' | 'cache-read-failed' | 'cache-write-failed' | 'cache-delete-failed' | 'cache-prune-failed' | 'storage-estimate-unavailable';
+    message: string;
+    cause?: unknown;
+}
+interface NappletBlobIndexEntry {
+    size: number;
+    lastAccessed: number;
+    refCount: number;
+}
+interface NappletAggregateIndexEntry {
+    dTag: string;
+    aggregateHash: string;
+    key: string;
+    blobHashes: string[];
+    size: number;
+    lastAccessed: number;
+    coordinateKey?: string;
+    pinned?: boolean;
+}
+interface CachedCoordinate {
+    key: string;
+    kind: number;
+    pubkey: string;
+    dTag: string;
+    aggregateHash: string;
+    lastResolvedAt: number;
+    foregroundTtlMs: number;
+    backgroundTtlMs: number;
+}
+interface NappletArtifactCacheIndex {
+    schemaVersion: number;
+    updatedAt: number;
+    blobs: Record<string, NappletBlobIndexEntry>;
+    aggregates: Record<string, NappletAggregateIndexEntry>;
+    coordinates: Record<string, CachedCoordinate>;
+}
+interface WriteVerifiedResolutionInput {
+    event: NostrEvent;
+    manifest: NappletManifest;
+    files: ReadonlyMap<string, Uint8Array>;
+    indexHtml: string;
+    now?: number;
+}
+interface CoordinateFreshnessOptions {
+    now?: number;
+    background?: boolean;
+}
+interface NappletArtifactCache {
+    readBlob(sha256Hex: string): Promise<Uint8Array | undefined>;
+    deleteBlob(sha256Hex: string): Promise<void>;
+    writeVerifiedResolution(input: WriteVerifiedResolutionInput): Promise<void>;
+    writeCoordinate(input: {
+        kind: number;
+        pubkey: string;
+        dTag: string;
+        aggregateHash: string;
+        lastResolvedAt?: number;
+        foregroundTtlMs?: number;
+        backgroundTtlMs?: number;
+    }): Promise<void>;
+    getCoordinate(input: {
+        kind: number;
+        pubkey: string;
+        dTag: string;
+    }, options?: CoordinateFreshnessOptions): Promise<(CachedCoordinate & {
+        fresh: boolean;
+    }) | undefined>;
+    touchAggregate(dTag: string, aggregateHash: string, now?: number): Promise<void>;
+    markAggregateActive(dTag: string, aggregateHash: string): void;
+    releaseAggregateActive(dTag: string, aggregateHash: string): void;
+    prune(now?: number): Promise<void>;
+}
+interface CacheStorageNappletArtifactCacheOptions {
+    cacheStorage?: CacheStorage;
+    storage?: StorageManager;
+    cacheName?: string;
+    baseUrl?: string;
+    now?: () => number;
+    onDiagnostic?: (diagnostic: NappletCacheDiagnostic) => void;
+    unknownBudgetBytes?: number;
+    softCeilingBytes?: number;
+    hardCeilingBytes?: number;
+}
+interface OpenNappletArtifactCacheOptions extends CacheStorageNappletArtifactCacheOptions {
+    requireStorageEstimate?: boolean;
+}
+declare function coordinateKey(kind: number, pubkey: string, dTag: string): string;
+declare function isCoordinateFresh(coordinate: CachedCoordinate, options?: CoordinateFreshnessOptions): boolean;
+declare class CacheStorageNappletArtifactCache implements NappletArtifactCache {
+    private readonly cacheStorage;
+    private readonly storage?;
+    private readonly cacheName;
+    private readonly baseUrl;
+    private readonly now;
+    private readonly activeAggregates;
+    private readonly onDiagnostic?;
+    private readonly unknownBudgetBytes;
+    private readonly softCeilingBytes;
+    private readonly hardCeilingBytes;
+    private cachePromise?;
+    constructor(options?: CacheStorageNappletArtifactCacheOptions);
+    readBlob(sha256Hex: string): Promise<Uint8Array | undefined>;
+    deleteBlob(sha256Hex: string): Promise<void>;
+    writeVerifiedResolution(input: WriteVerifiedResolutionInput): Promise<void>;
+    writeCoordinate(input: {
+        kind: number;
+        pubkey: string;
+        dTag: string;
+        aggregateHash: string;
+        lastResolvedAt?: number;
+        foregroundTtlMs?: number;
+        backgroundTtlMs?: number;
+    }): Promise<void>;
+    getCoordinate(input: {
+        kind: number;
+        pubkey: string;
+        dTag: string;
+    }, options?: CoordinateFreshnessOptions): Promise<(CachedCoordinate & {
+        fresh: boolean;
+    }) | undefined>;
+    touchAggregate(dTag: string, aggregateHash: string, now?: number): Promise<void>;
+    markAggregateActive(dTag: string, aggregateHash: string): void;
+    releaseAggregateActive(dTag: string, aggregateHash: string): void;
+    prune(now?: number): Promise<void>;
+    snapshotIndex(): Promise<NappletArtifactCacheIndex>;
+    private writeVerifiedResolutionOnce;
+    private open;
+    private indexUrl;
+    private blobUrl;
+    private aggregateUrl;
+    private readIndex;
+    private writeIndex;
+    private rewriteRefCounts;
+    private budgetBytes;
+    private hardBudgetBytes;
+    private originPressureHigh;
+    private estimateStorage;
+    private diagnostic;
+}
+declare function openNappletArtifactCache(options?: OpenNappletArtifactCacheOptions): Promise<CacheStorageNappletArtifactCache | undefined>;
+
+/**
+ * `@kehto/nip/5d` — NIP-5D napplet manifest resolution.
+ *
+ * NIP-5D (`dskvr/nips` branch `nip/5d`) defines content-addressed "napplet"
+ * web applets published as Nostr events that reference their files by hash
+ * (NIP-5A `path` tags + an aggregate `x` tag). A runtime resolves a napplet by:
+ *
+ * 1. verifying the manifest event's signature,
+ * 2. recomputing the NIP-5A aggregate from its `path` tags and checking the
+ *    `["x","<hex>","aggregate"]` tag,
+ * 3. fetching each referenced blob (e.g. from Blossom) and verifying its hash,
+ * 4. assembling the verified `/index.html`.
+ *
+ * The napplet's identity is the `(dTag, aggregateHash)` tuple **computed** from
+ * these verified bytes — it is never accepted from a host or gateway.
+ */
+/** Snapshot manifest — regular event, immutable point-in-time release. */
+declare const NAPPLET_KIND_SNAPSHOT = 5129;
+/** Root manifest — replaceable event, an author's latest unnamed napplet. */
+declare const NAPPLET_KIND_ROOT = 15129;
+/** Named manifest — addressable event (carries a `d` tag identifier). */
+declare const NAPPLET_KIND_NAMED = 35129;
+/** All three NIP-5D napplet manifest kinds. */
+declare const NAPPLET_KINDS: readonly number[];
+/**
+ * Whether `kind` is one of the three NIP-5D napplet manifest kinds.
+ *
+ * @param kind - A Nostr event kind
+ * @returns `true` for `5129` / `15129` / `35129`
+ */
+declare function isNappletManifestKind(kind: number): boolean;
+/**
+ * A parsed NIP-5D napplet manifest. All fields are derived from the manifest
+ * event's tags; the aggregate is the declared `x` tag (verify it separately
+ * with {@link resolveNapplet} or `@kehto/nip/5a` `verifyAggregate`).
+ */
+interface NappletManifest {
+    /** Manifest event kind (`5129` / `15129` / `35129`). */
+    kind: number;
+    /** Author hex public key. */
+    pubkey: string;
+    /** Named-napplet `d` identifier, or `''` for root/snapshot manifests. */
+    dTag: string;
+    /** File path entries from `path` tags. */
+    paths: PathEntry[];
+    /** Declared aggregate hash from the `["x","<hex>","aggregate"]` tag. */
+    aggregateHash: string;
+    /** Blossom server URL hints from `server` tags. */
+    servers: string[];
+    /** Short NAP capability names from `requires` tags. */
+    requires: string[];
+    /**
+     * Archetype slugs this napplet fulfills, from `archetype` manifest tags; the
+     * optional `nap` is the recommended default wire protocol (the 3rd tag element).
+     */
+    archetypes: Array<{
+        slug: string;
+        nap?: string;
+    }>;
+    /** Optional human title. */
+    title?: string;
+    /** Optional human description. */
+    description?: string;
+    /** Optional upstream source URL from the `source` tag. */
+    source?: string;
+}
+/** Error codes for every napplet resolution failure path. */
+type NappletResolutionErrorCode = 'invalid-signature' | 'invalid-manifest' | 'aggregate-mismatch' | 'blob-hash-mismatch' | 'blob-unavailable' | 'missing-index';
+/**
+ * Thrown on any napplet resolution/verification failure. The `code` field
+ * identifies which guard rejected, so callers can fail closed without parsing
+ * the message.
+ */
+declare class NappletResolutionError extends Error {
+    readonly code: NappletResolutionErrorCode;
+    constructor(code: NappletResolutionErrorCode, message: string);
+}
+/**
+ * Parse a NIP-5D manifest event into a {@link NappletManifest}.
+ *
+ * Does not verify the signature, aggregate, or blobs — use {@link resolveNapplet}
+ * for full verification.
+ *
+ * @param event - A NIP-5D manifest event (`5129` / `15129` / `35129`)
+ * @returns The parsed manifest
+ * @throws {@link NappletResolutionError} `invalid-manifest` for a non-napplet
+ *   kind, missing `path` tags, or a missing aggregate `x` tag
+ */
+declare function parseNappletManifest(event: NostrEvent): NappletManifest;
+/**
+ * Verify a manifest event's Nostr signature (id + schnorr sig).
+ *
+ * @param event - A manifest event
+ * @returns `true` if the event is internally consistent and validly signed
+ */
+declare function verifyManifestSignature(event: NostrEvent): boolean;
+/**
+ * Whether `bytes` hash to the expected lowercase-hex SHA-256.
+ *
+ * @param bytes - The blob bytes
+ * @param sha256Hex - Expected lowercase-hex SHA-256
+ * @returns `true` only on an exact match
+ */
+declare function verifyBlobHash(bytes: Uint8Array, sha256Hex: string): boolean;
+/**
+ * Fetch a blob by SHA-256 from a list of Blossom servers, returning the first
+ * server's bytes whose hash matches. The returned bytes are always re-verified
+ * against `sha256Hex` — servers (and gateways) are never trusted.
+ *
+ * @param servers - Candidate Blossom server base URLs, tried in order
+ * @param sha256Hex - The blob's lowercase-hex SHA-256
+ * @param fetchBytes - Fetches raw bytes for a URL (`<server>/<sha256>`)
+ * @returns The verified blob bytes
+ * @throws {@link NappletResolutionError} `blob-unavailable` if no server serves
+ *   a hash-matching blob
+ */
+declare function fetchBlob(servers: readonly string[], sha256Hex: string, fetchBytes: (url: string) => Promise<Uint8Array>): Promise<Uint8Array>;
+/** A fully verified napplet, ready to inject via `iframe.srcdoc`. */
+interface ResolvedNapplet {
+    /** Computed `d` identifier (`''` for root/snapshot). */
+    dTag: string;
+    /** Computed (and verified) aggregate hash — the content address. */
+    aggregateHash: string;
+    /** Verified file bytes keyed by manifest path. */
+    files: Map<string, Uint8Array>;
+    /** The verified `/index.html` decoded to text. */
+    indexHtml: string;
+    /** The parsed manifest. */
+    manifest: NappletManifest;
+}
+/** Options for {@link resolveNapplet}. */
+interface ResolveNappletOptions {
+    /** The candidate manifest event (resolved from relays by the caller). */
+    event: NostrEvent;
+    /**
+     * Fetch raw blob bytes by SHA-256. Backed by Blossom (or a gateway) by the
+     * caller. The bytes are re-verified against the hash here, so the fetcher is
+     * untrusted.
+     */
+    fetchBlob: (sha256Hex: string, servers: readonly string[]) => Promise<Uint8Array>;
+    /** Decode blob bytes to text for `indexHtml` (default UTF-8). */
+    textDecode?: (bytes: Uint8Array) => string;
+    /**
+     * Optional verified artifact cache. Cache hits are still re-verified against
+     * the manifest hash before use; cache writes happen only after the signature,
+     * aggregate, and every blob hash have been verified.
+     */
+    cache?: NappletArtifactCache;
+}
+/**
+ * Resolve a napplet end-to-end from a candidate manifest event: verify the
+ * signature, parse the manifest, verify the NIP-5A aggregate, fetch and verify
+ * every blob, then assemble the verified `/index.html`.
+ *
+ * The returned `(dTag, aggregateHash)` is computed from the verified bytes and
+ * is the napplet's identity. Any failure throws a {@link NappletResolutionError}
+ * — the caller must fail closed (never render unverified bytes).
+ *
+ * @param options - {@link ResolveNappletOptions}
+ * @returns The {@link ResolvedNapplet}
+ * @throws {@link NappletResolutionError} on signature, manifest, aggregate,
+ *   blob-hash, blob-availability, or missing-index failures
+ *
+ * @example
+ * ```ts
+ * import { resolveNapplet } from '@kehto/nip/5d';
+ * const napplet = await resolveNapplet({ event, fetchBlob });
+ * iframe.srcdoc = napplet.indexHtml; // sandbox="allow-scripts", opaque origin
+ * ```
+ */
+declare function resolveNapplet(options: ResolveNappletOptions): Promise<ResolvedNapplet>;
+
+export { CacheStorageNappletArtifactCache, type CacheStorageNappletArtifactCacheOptions, type CachedCoordinate, type CoordinateFreshnessOptions, NAPPLET_ARTIFACT_CACHE_NAME, NAPPLET_KINDS, NAPPLET_KIND_NAMED, NAPPLET_KIND_ROOT, NAPPLET_KIND_SNAPSHOT, type NappletAggregateIndexEntry, type NappletArtifactCache, type NappletArtifactCacheIndex, type NappletBlobIndexEntry, type NappletCacheDiagnostic, type NappletManifest, NappletResolutionError, type NappletResolutionErrorCode, type OpenNappletArtifactCacheOptions, type ResolveNappletOptions, type ResolvedNapplet, type WriteVerifiedResolutionInput, coordinateKey, fetchBlob, isCoordinateFresh, isNappletManifestKind, openNappletArtifactCache, parseNappletManifest, resolveNapplet, verifyBlobHash, verifyManifestSignature };