@kehto/services 0.6.0 → 0.8.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { ServiceHandler, Signer } from '@kehto/runtime';
-import { NostrEvent, NappletMessage, NostrFilter, EventTemplate } from '@napplet/core';
+import { NostrFilter, NostrEvent, EventTemplate } from '@napplet/core';
 import { MediaMetadata, MediaAction } from '@napplet/nub/media/types';
 export { MediaAction } from '@napplet/nub/media/types';
 import { NotifySendMessage } from '@napplet/nub/notify/types';
@@ -181,53 +181,19 @@ declare function createNotificationService(options?: NotificationServiceOptions)
  *   - signer.nip04.encrypt/decrypt -> DELETED
  *   - signer.nip44.encrypt/decrypt -> DELETED (shell encrypts internally
  *                                      inside relay.publishEncrypted)
- *   - identity.decrypt -> ADDED in v1.8 as a shell-mediated decrypt request
- *                         with class gate + typed error union.
  *
- * See REQUIREMENTS.md DEPS-03 (Phase 15 changelog).
+ * Identity is strictly read-only per NAP-IDENTITY: napplets learn *about* the
+ * user but cannot act *as* the user — no signing, encryption, or decryption.
+ * (An `identity.decrypt` capability was briefly added in v1.8 and removed as a
+ * spec violation; decryption belongs to the runtime, inline over the wire.)
  *
- * Handles 10 identity.* request types from @napplet/nub/identity. getPublicKey
+ * Handles 9 identity.* request types from @napplet/nub/identity. getPublicKey
  * and getRelays return real values sourced from hooks.auth.getSigner(); the
  * remaining 7 (getProfile/getFollows/getList/getZaps/getMutes/getBlocked/
- * getBadges) are stub-level; decrypt delegates to a host-supplied bridge.
- * Host apps plug real backends via runtime.registerService('identity', realHandler).
+ * getBadges) are stub-level. Host apps plug real backends via
+ * runtime.registerService('identity', realHandler).
  */
 
-type IdentityDecryptErrorCode = 'class-forbidden' | 'signer-denied' | 'signer-unavailable' | 'decrypt-failed' | 'malformed-wrap' | 'impersonation' | 'unsupported-encryption' | 'policy-denied';
-interface Rumor {
-    id: string;
-    pubkey: string;
-    created_at: number;
-    kind: number;
-    tags: string[][];
-    content: string;
-}
-interface IdentityDecryptMessage extends NappletMessage {
-    type: 'identity.decrypt';
-    id: string;
-    event: NostrEvent;
-}
-interface IdentityDecryptResultMessage extends NappletMessage {
-    type: 'identity.decrypt.result';
-    id: string;
-    rumor: Rumor;
-    sender: string;
-}
-interface IdentityDecryptErrorMessage extends NappletMessage {
-    type: 'identity.decrypt.error';
-    id: string;
-    error: IdentityDecryptErrorCode;
-}
-interface GiftWrapDecryptResult {
-    seal: NostrEvent;
-    rumor: Rumor;
-}
-interface HostDecryptBridge {
-    nip04Decrypt(senderPubkey: string, ciphertext: string): Promise<string>;
-    nip44Decrypt(senderPubkey: string, ciphertext: string): Promise<string>;
-    unwrapGiftWrap(wrap: NostrEvent): Promise<GiftWrapDecryptResult>;
-}
-type VerifyEvent = (event: NostrEvent) => boolean | Promise<boolean>;
 /**
  * Options for creating the identity service.
  *
@@ -246,27 +212,14 @@ interface IdentityServiceOptions {
      * availability can change dynamically.
      */
     getSigner: () => Signer | null;
-    /**
-     * Return the host decrypt bridge. Called only after outer event signature
-     * verification and encryption-mode detection succeed. Null means decrypt is
-     * unavailable while the rest of the identity service remains usable.
-     */
-    getDecryptor?: () => HostDecryptBridge | null;
-    /**
-     * Verify a received event before any decrypt attempt. Host shells should
-     * wire this to their canonical Nostr event verifier; tests and old hosts
-     * default to true for backward compatibility with the 9 read-only actions.
-     */
-    verifyEvent?: VerifyEvent;
 }
 /**
  * Create an identity service that handles NIP-5D identity.* envelope messages.
  *
- * Supports all 10 identity.* request types from @napplet/nub/identity. The two
- * read-only nostr-info queries (getPublicKey, getRelays) resolve through the
+ * Supports the 9 read-only identity.* request types from @napplet/nub/identity.
+ * The two nostr-info queries (getPublicKey, getRelays) resolve through the
  * caller-supplied signer; the remaining 7 return default/empty payloads with
  * spec-correct envelope shapes so napplets always receive a result envelope.
- * identity.decrypt delegates to the host decrypt bridge.
  *
  * @param options - Identity service configuration (getSigner)
  * @returns A ServiceHandler ready for runtime.registerService('identity', handler)
@@ -1796,4 +1749,236 @@ interface RelayPoolOutboxRouterOptions {
  */
 declare function createRelayPoolOutboxRouter(options: RelayPoolOutboxRouterOptions): OutboxRouter;
 
-export { type AudioServiceOptions, type AudioSource, type CacheServiceOptions, type ConfigSchemaValidation, type ConfigService, type ConfigServiceOptions, type CoordinatedRelayOptions, type GiftWrapDecryptResult, type HostCacheBridge, type HostDecryptBridge, type HostKeyEvent, type HostKeysBridge, type HostMediaBridge, type IdentityDecryptErrorCode, type IdentityDecryptErrorMessage, type IdentityDecryptMessage, type IdentityDecryptResultMessage, type IdentityServiceOptions, type KeysServiceOptions, type MediaMetadataLike, type MediaPlaybackOwner, type MediaServiceOptions, type MediaSessionCreateOptions, type MediaSessionTarget, type MediaSourceRef, type Notification, type NotificationServiceOptions, type NotifyServiceOptions, type OutboxPublishOptions, type OutboxPublishResult, type OutboxQueryOptions, type OutboxRelayPlan, type OutboxRelayPool, type OutboxResult, type OutboxRouter, type OutboxRouterSubscription, type OutboxServiceOptions, type OutboxStrategy, type OutboxSubscribeOptions, type OutboxSubscriptionSink, type OutboxTarget, type RelayListEntry, type RelayPoolOutboxRouterOptions, type RelayPoolServiceOptions, type ResourceService, type ResourceServiceOptions, type Rumor, type ThemeService, type ThemeServiceOptions, type VerifyEvent, createAudioService, createBrowserMediaBridge, createCacheService, createConfigService, createCoordinatedRelay, createIdentityService, createKeysService, createMediaService, createNotificationService, createNotifyService, createOutboxService, createRelayPoolOutboxRouter, createRelayPoolService, createResourceService, createThemeService };
+/**
+ * upload-service.ts — NAP-UPLOAD (shell-mediated file/blob upload) reference service.
+ *
+ * Shell-side handler for the NAP-UPLOAD wire protocol. It is a pure envelope
+ * router: it validates `upload.*` envelopes, delegates the actual byte transfer
+ * (server selection, rail authorization signing, the HTTP upload) to an injected
+ * {@link Uploader}, and posts the correlated result / status messages back to the
+ * napplet.
+ *
+ * The uploader is injected (options-as-bridge) so this service has no transport
+ * or Nostr dependency and is fully unit-testable. NAP-UPLOAD is deliberately
+ * abstract over the backend — the runtime decides *how* it uploads (NIP-96,
+ * Blossom, …). A concrete HTTP-backed uploader ships alongside as
+ * {@link createHttpUploader}.
+ *
+ * ──────────────────────────── Responsibilities ────────────────────────────
+ *   Inbound:  upload.upload, upload.status
+ *   Outbound: upload.upload.result, upload.status.result, upload.status.changed
+ *
+ * The service owns the `uploadId` (generated per request, scoped to the
+ * requesting napplet), tracks the latest {@link UploadStatus} per upload for
+ * `upload.status` queries, and cleans up on window teardown. The shell owns
+ * consent, policy, server selection, signing, and the HTTP upload — all behind
+ * the {@link Uploader}.
+ *
+ * @example
+ * ```ts
+ * import { createUploadService, createHttpUploader } from '@kehto/services';
+ *
+ * const uploader = createHttpUploader({ rails: { nip96: { servers } }, signEvent });
+ * runtime.registerService('upload', createUploadService({ uploader }));
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Storage rail. `nip96` (NIP-96 HTTP file storage) and `blossom` (Blossom blob
+ * storage) are the first concrete backends; the open string keeps the API
+ * stable as shells add rails (torrents, usenet, …).
+ */
+type UploadRail = 'nip96' | 'blossom' | (string & {});
+/** Lifecycle state of an upload. */
+type UploadState = 'pending' | 'uploading' | 'complete' | 'failed' | 'cancelled';
+/** Pixel dimensions of an uploaded image/video. */
+interface UploadDimensions {
+    width: number;
+    height: number;
+}
+/**
+ * A napplet's upload request. `data` crosses the postMessage boundary by
+ * structured clone — shells never require base64 encoding.
+ */
+interface UploadRequest {
+    /** Storage rail; omit to let the shell pick a configured default. */
+    rail?: UploadRail;
+    /** The bytes to upload. */
+    data: ArrayBuffer | Blob;
+    /** MIME type; inferred from `data` when omitted. */
+    mimeType?: string;
+    /** Suggested filename. */
+    filename?: string;
+    /** Alt text / description for the file event. */
+    caption?: string;
+    /** Request the server not re-encode the file (NIP-96 `no_transform`). */
+    noTransform?: boolean;
+    /** Rail-specific or shell-specific extra metadata. */
+    metadata?: Record<string, unknown>;
+}
+/** A single Nostr tag (NIP-94 / imeta entries are arrays of strings). */
+type NostrTag = string[];
+/** The result of an upload. */
+interface UploadResult {
+    /** Whether the upload succeeded (or is progressing) vs failed/cancelled. */
+    ok: boolean;
+    /** Shell-generated id, scoped to the requesting napplet. */
+    uploadId: string;
+    /** Current lifecycle state. */
+    status: UploadState;
+    /** The rail the shell used. */
+    rail: UploadRail;
+    /** Primary download URL. */
+    url?: string;
+    /** Mirrors / alternative server URLs. */
+    fallbackUrls?: string[];
+    /** Hash of the stored blob (NIP-94 `x`). */
+    sha256?: string;
+    /** Hash before server transforms (NIP-94 `ox`). */
+    originalSha256?: string;
+    /** Size in bytes. */
+    size?: number;
+    /** Stored MIME type. */
+    mimeType?: string;
+    /** Image/video dimensions when known. */
+    dimensions?: UploadDimensions;
+    /** Blurhash placeholder when known. */
+    blurhash?: string;
+    /** Ready-to-attach NIP-94 / imeta tags. */
+    nip94?: NostrTag[];
+    /** Error reason when the upload failed or was cancelled. */
+    error?: string;
+}
+/** A status snapshot for an upload, including progress counters. */
+interface UploadStatus extends UploadResult {
+    /** Bytes sent so far (while uploading). */
+    bytesSent?: number;
+    /** Total bytes to send. */
+    bytesTotal?: number;
+    /** Unix ms timestamp of this status. */
+    updatedAt: number;
+}
+/**
+ * Context handed to an {@link Uploader} for a single upload. Carries the
+ * service-owned `uploadId` and a sink for streaming progress / state changes.
+ */
+interface UploaderContext {
+    /** The service-generated upload id (authoritative; scoped to the napplet). */
+    uploadId: string;
+    /** The napplet window that requested the upload. */
+    windowId: string;
+    /**
+     * Push a status update (progress, or a transition to complete/failed). The
+     * service stamps `uploadId` and `updatedAt` before forwarding to the napplet
+     * as `upload.status.changed`, and records it as the latest tracked status.
+     */
+    onStatus(status: UploadStatus): void;
+}
+/**
+ * Abstract upload backend. Implementors own server selection, rail
+ * authorization signing (NIP-98 for NIP-96, kind 24242 for Blossom), the HTTP
+ * upload, and integrity-hash reporting. The service translates wire envelopes
+ * into these calls and back. A concrete reference implementation ships as
+ * {@link createHttpUploader}.
+ */
+interface Uploader {
+    /** Upload `request.data`, streaming progress through `ctx.onStatus`. */
+    upload(request: UploadRequest, ctx: UploaderContext): Promise<UploadResult>;
+    /** Optional: resolve the latest status for an upload the service is not tracking. */
+    status?(uploadId: string): Promise<UploadStatus | undefined>;
+    /** Optional: abort an in-flight upload (called on window teardown). */
+    cancel?(uploadId: string): void;
+}
+/** Options for {@link createUploadService}. */
+interface UploadServiceOptions {
+    /** The upload backend the shell uses. Required. */
+    uploader: Uploader;
+    /** Generate an upload id; defaults to `crypto.randomUUID()`. */
+    generateId?: () => string;
+    /** Current time in unix ms; defaults to `Date.now()`. */
+    now?: () => number;
+}
+/**
+ * Create the NAP-UPLOAD service handler.
+ *
+ * @param options - Must provide an {@link Uploader}.
+ * @returns A `ServiceHandler` ready for `runtime.registerService('upload', handler)`.
+ * @throws If `options.uploader` is missing.
+ */
+declare function createUploadService(options: UploadServiceOptions): ServiceHandler;
+
+/**
+ * http-uploader.ts — NAP-UPLOAD concrete HTTP-backed {@link Uploader}.
+ *
+ * The reference upload backend for {@link createUploadService}. Implements two
+ * storage rails over HTTP:
+ *
+ * - **NIP-96** — signs a NIP-98 (kind 27235) HTTP-auth event, POSTs the file as
+ *   `multipart/form-data`, and maps the returned NIP-94 event tags into an
+ *   {@link UploadResult}.
+ * - **Blossom** — signs a kind 24242 authorization event, PUTs the raw bytes to
+ *   `<server>/upload`, and maps the returned blob descriptor.
+ *
+ * Signing (`signEvent`) and transport (`fetch`) are injected so the uploader
+ * carries no Nostr or network dependency and is fully unit-testable. The shell
+ * holds the signing key and never exposes it to napplets — the uploader only
+ * receives a signing callback. Server URLs are shell configuration, not napplet
+ * input: a napplet may *hint* a rail, but never a server.
+ *
+ * The configured server URL is used directly as the upload endpoint (the
+ * NIP-96 `api_url` / Blossom base). Hosts that need `.well-known` discovery can
+ * resolve it before constructing the uploader.
+ *
+ * @example
+ * ```ts
+ * const uploader = createHttpUploader({
+ *   rails: { nip96: { servers: ['https://nostr.build/api/v2/nip96/upload'] } },
+ *   signEvent: (tmpl) => signer.signEvent(tmpl),
+ * });
+ * runtime.registerService('upload', createUploadService({ uploader }));
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+/** Per-rail server configuration. The first server is the primary endpoint. */
+interface RailServerConfig {
+    /** Ordered server endpoint URLs; index 0 is primary. */
+    servers: string[];
+}
+/** Storage rails this uploader can serve. */
+interface HttpUploaderRails {
+    /** NIP-96 HTTP file storage. */
+    nip96?: RailServerConfig;
+    /** Blossom blob storage. */
+    blossom?: RailServerConfig;
+}
+/** Signs an event template on the user's behalf (shell holds the key). */
+type SignEvent = (template: EventTemplate) => Promise<NostrEvent>;
+/** Options for {@link createHttpUploader}. */
+interface HttpUploaderOptions {
+    /** Configured rails + their servers. */
+    rails: HttpUploaderRails;
+    /** Rail to use when a request omits one; defaults to the first configured rail. */
+    defaultRail?: UploadRail;
+    /** Signs NIP-98 / Blossom auth events. Required. */
+    signEvent: SignEvent;
+    /** Fetch implementation; defaults to the global `fetch`. */
+    fetch?: typeof fetch;
+    /** Hex SHA-256 of the payload bytes; defaults to Web Crypto. */
+    digestSha256?: (bytes: Uint8Array) => Promise<string>;
+    /** Unix *seconds* clock for event timestamps; defaults to `Date.now()/1000`. */
+    now?: () => number;
+}
+/**
+ * Create the reference HTTP {@link Uploader} (NIP-96 + Blossom rails).
+ *
+ * @param options - Rails, server config, and the injected `signEvent`.
+ * @returns An {@link Uploader} for `createUploadService({ uploader })`.
+ * @throws If `options.signEvent` is missing.
+ */
+declare function createHttpUploader(options: HttpUploaderOptions): Uploader;
+
+export { type AudioServiceOptions, type AudioSource, type CacheServiceOptions, type ConfigSchemaValidation, type ConfigService, type ConfigServiceOptions, type CoordinatedRelayOptions, type HostCacheBridge, type HostKeyEvent, type HostKeysBridge, type HostMediaBridge, type HttpUploaderOptions, type HttpUploaderRails, type IdentityServiceOptions, type KeysServiceOptions, type MediaMetadataLike, type MediaPlaybackOwner, type MediaServiceOptions, type MediaSessionCreateOptions, type MediaSessionTarget, type MediaSourceRef, type NostrTag, type Notification, type NotificationServiceOptions, type NotifyServiceOptions, type OutboxPublishOptions, type OutboxPublishResult, type OutboxQueryOptions, type OutboxRelayPlan, type OutboxRelayPool, type OutboxResult, type OutboxRouter, type OutboxRouterSubscription, type OutboxServiceOptions, type OutboxStrategy, type OutboxSubscribeOptions, type OutboxSubscriptionSink, type OutboxTarget, type RailServerConfig, type RelayListEntry, type RelayPoolOutboxRouterOptions, type RelayPoolServiceOptions, type ResourceService, type ResourceServiceOptions, type SignEvent, type ThemeService, type ThemeServiceOptions, type UploadDimensions, type UploadRail, type UploadRequest, type UploadResult, type UploadServiceOptions, type UploadState, type UploadStatus, type Uploader, type UploaderContext, createAudioService, createBrowserMediaBridge, createCacheService, createConfigService, createCoordinatedRelay, createHttpUploader, createIdentityService, createKeysService, createMediaService, createNotificationService, createNotifyService, createOutboxService, createRelayPoolOutboxRouter, createRelayPoolService, createResourceService, createThemeService, createUploadService };