@fgv/ts-extras 5.1.0-18 → 5.1.0-19

package/dist/packlets/ai-assist/apiClient.js

@@ -30,10 +30,10 @@
  * @packageDocumentation
  */
 import { isJsonObject } from '@fgv/ts-json-base';
-import { fail, succeed, Validators } from '@fgv/ts-utils';
+import { fail, mapResults, succeed, Validators } from '@fgv/ts-utils';
 import { resolveModel } from './model';
 import { buildAnthropicMessages, buildGeminiContents, buildMessages, buildOpenAiChatUserContent, buildOpenAiResponsesUserContent } from './chatRequestBuilders';
-import { DEFAULT_MODEL_CAPABILITY_CONFIG } from './registry';
+import { DEFAULT_MODEL_CAPABILITY_CONFIG, resolveImageCapability, supportsImageGeneration } from './registry';
 import { toAnthropicTools, toGeminiTools, toResponsesApiTools } from './toolFormats';
 // ============================================================================
 // Shared helpers
@@ -84,6 +84,102 @@ async function fetchJson(url, headers, body, logger, signal) {
     }
     return succeed(json);
 }
+/**
+ * Makes a multipart/form-data POST request and returns the parsed JSON, or a
+ * failure. The Content-Type header (with boundary) is set automatically by
+ * `fetch` from the `FormData` body — callers must NOT pass it explicitly.
+ * @internal
+ */
+async function fetchMultipart(url, headers, body, logger, signal) {
+    /* c8 ignore next 1 - optional logger */
+    logger === null || logger === void 0 ? void 0 : logger.detail(`AI API request: POST ${url} (multipart)`);
+    let response;
+    try {
+        response = await fetch(url, {
+            method: 'POST',
+            headers,
+            body,
+            signal
+        });
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        /* c8 ignore next 1 - optional logger */
+        logger === null || logger === void 0 ? void 0 : logger.error(`AI API request failed: ${detail}`);
+        return fail(`AI API request failed: ${detail}`);
+    }
+    if (!response.ok) {
+        const errorText = await response.text().catch(() => 'unknown error');
+        /* c8 ignore next 1 - optional logger */
+        logger === null || logger === void 0 ? void 0 : logger.error(`AI API returned ${response.status}: ${errorText}`);
+        return fail(`AI API returned ${response.status}: ${errorText}`);
+    }
+    /* c8 ignore next 1 - optional logger */
+    logger === null || logger === void 0 ? void 0 : logger.detail(`AI API response: ${response.status}`);
+    let json;
+    try {
+        json = await response.json();
+    }
+    catch (_a) {
+        /* c8 ignore next 1 - optional logger */
+        logger === null || logger === void 0 ? void 0 : logger.error('AI API returned invalid JSON response');
+        return fail('AI API returned invalid JSON response');
+    }
+    if (!isJsonObject(json)) {
+        /* c8 ignore next 1 - optional logger */
+        logger === null || logger === void 0 ? void 0 : logger.error('AI API returned non-object JSON response');
+        return fail('AI API returned non-object JSON response');
+    }
+    return succeed(json);
+}
+/**
+ * Decodes a base64-encoded image attachment into a `Blob` suitable for use as
+ * a multipart file field. On Node hands the `Buffer` straight to `Blob`
+ * (Buffer extends Uint8Array) to skip an intermediate copy; falls back to
+ * `atob` in browsers. Inputs come from `FileReader` or prior provider
+ * responses, which are trusted to be valid. Note that Node's
+ * `Buffer.from(..., 'base64')` silently strips invalid characters rather
+ * than throwing, so failures are only observable in the browser path.
+ * @internal
+ */
+function attachmentToBlob(attachment) {
+    if (typeof Buffer !== 'undefined') {
+        return succeed(new Blob([Buffer.from(attachment.base64, 'base64')], { type: attachment.mimeType }));
+    }
+    /* c8 ignore start - Browser-only fallback cannot be tested in Node.js environment */
+    try {
+        const binary = atob(attachment.base64);
+        const bytes = new Uint8Array(binary.length);
+        for (let i = 0; i < binary.length; i++) {
+            bytes[i] = binary.charCodeAt(i);
+        }
+        return succeed(new Blob([bytes], { type: attachment.mimeType }));
+    }
+    catch (e) {
+        const message = e instanceof Error ? e.message : String(e);
+        return fail(`Invalid base64: ${message}`);
+    }
+    /* c8 ignore stop */
+}
+/**
+ * Maps a MIME type to a sensible file extension for multipart filenames.
+ * @internal
+ */
+function extensionForMimeType(mimeType) {
+    switch (mimeType) {
+        case 'image/png':
+            return 'png';
+        case 'image/jpeg':
+        case 'image/jpg':
+            return 'jpg';
+        case 'image/webp':
+            return 'webp';
+        case 'image/gif':
+            return 'gif';
+        default:
+            return 'bin';
+    }
+}
 /**
  * Makes an HTTP GET request and returns the parsed JSON, or a failure.
  * @internal
@@ -457,6 +553,24 @@ const imagenPrediction = Validators.object({
 const imagenResponse = Validators.object({
     predictions: Validators.arrayOf(imagenPrediction).withConstraint((arr) => arr.length > 0)
 });
+const geminiImageInlineData = Validators.object({
+    mimeType: Validators.string,
+    data: Validators.string
+});
+const geminiImageOutPart = Validators.object({
+    text: Validators.string.optional(),
+    inlineData: geminiImageInlineData.optional()
+});
+const geminiImageOutContent = Validators.object({
+    parts: Validators.arrayOf(geminiImageOutPart).withConstraint((arr) => arr.length > 0)
+});
+const geminiImageOutCandidate = Validators.object({
+    content: geminiImageOutContent,
+    finishReason: Validators.string.optional()
+});
+const geminiImageOutResponse = Validators.object({
+    candidates: Validators.arrayOf(geminiImageOutCandidate).withConstraint((arr) => arr.length > 0)
+});
 // ---- Proxied image generation response ----
 const proxiedGeneratedImage = Validators.object({
     mimeType: Validators.string,
@@ -482,16 +596,42 @@ const proxiedListModelsResponse = Validators.object({
  * formats — the request shape is the same; the only difference is whether the
  * `size` field is honored (OpenAI: yes, xAI: ignored at the provider).
  *
+ * When `request.referenceImages` is non-empty, routes to `/images/edits`
+ * (multipart) instead of `/images/generations` (JSON). Per-model edit support
+ * is not validated here (e.g. dall-e-3 does not support edits) — the
+ * provider's 400 surfaces through the failure path.
+ *
  * @internal
  */
 async function callOpenAiImageGeneration(config, request, defaultMimeType, logger, signal) {
-    var _a, _b;
-    const url = `${config.baseUrl}/images/generations`;
+    var _a, _b, _c;
+    const opts = (_a = request.options) !== null && _a !== void 0 ? _a : {};
+    const refs = (_b = request.referenceImages) !== null && _b !== void 0 ? _b : [];
+    const headers = {
+        Authorization: `Bearer ${config.apiKey}`
+    };
+    const n = (_c = opts.count) !== null && _c !== void 0 ? _c : 1;
+    const fetched = refs.length > 0
+        ? await callOpenAiImagesEdits(config, request, headers, n, refs, logger, signal)
+        : await callOpenAiImagesGenerations(config, request, headers, n, logger, signal);
+    return fetched.onSuccess((json) => openAiImageResponse
+        .validate(json)
+        .withErrorFormat((msg) => `OpenAI images API response: ${msg}`)
+        .onSuccess((response) => succeed({
+        images: response.data.map((item) => (Object.assign({ mimeType: defaultMimeType, base64: item.b64_json }, (item.revised_prompt !== undefined ? { revisedPrompt: item.revised_prompt } : {}))))
+    })));
+}
+/**
+ * Builds and posts the JSON `/images/generations` request (no refs).
+ * @internal
+ */
+function callOpenAiImagesGenerations(config, request, headers, n, logger, signal) {
+    var _a;
     const opts = (_a = request.options) !== null && _a !== void 0 ? _a : {};
     const body = {
         model: config.model,
         prompt: request.prompt,
-        n: (_b = opts.count) !== null && _b !== void 0 ? _b : 1,
+        n,
         response_format: 'b64_json'
     };
     if (opts.size !== undefined) {
@@ -503,22 +643,86 @@ async function callOpenAiImageGeneration(config, request, defaultMimeType, logge
     if (opts.seed !== undefined) {
         body.seed = opts.seed;
     }
+    /* c8 ignore next 1 - optional logger */
+    logger === null || logger === void 0 ? void 0 : logger.info(`Image generation: model=${config.model}, n=${n}`);
+    return fetchJson(`${config.baseUrl}/images/generations`, headers, body, logger, signal);
+}
+/**
+ * Builds and posts the multipart `/images/edits` request (with refs).
+ * @internal
+ */
+async function callOpenAiImagesEdits(config, request, headers, n, refs, logger, signal) {
+    var _a;
+    const blobsResult = mapResults(refs.map((ref, i) => attachmentToBlob(ref).withErrorFormat((msg) => `reference image ${i}: ${msg}`)));
+    /* c8 ignore next 3 - decode failure unreachable via Node's Buffer.from (silently strips invalid input) */
+    if (blobsResult.isFailure()) {
+        return fail(blobsResult.message);
+    }
+    const opts = (_a = request.options) !== null && _a !== void 0 ? _a : {};
+    const form = new FormData();
+    form.append('model', config.model);
+    form.append('prompt', request.prompt);
+    form.append('n', String(n));
+    form.append('response_format', 'b64_json');
+    if (opts.size !== undefined) {
+        form.append('size', opts.size);
+    }
+    if (opts.quality !== undefined) {
+        form.append('quality', opts.quality);
+    }
+    if (opts.seed !== undefined) {
+        form.append('seed', String(opts.seed));
+    }
+    blobsResult.value.forEach((blob, i) => {
+        form.append('image[]', blob, `ref-${i}.${extensionForMimeType(refs[i].mimeType)}`);
+    });
+    /* c8 ignore next 1 - optional logger */
+    logger === null || logger === void 0 ? void 0 : logger.info(`Image edit: model=${config.model}, n=${n}, refs=${refs.length}`);
+    return fetchMultipart(`${config.baseUrl}/images/edits`, headers, form, logger, signal);
+}
+/**
+ * Calls Gemini's chat-style `:generateContent` endpoint for image output
+ * (Gemini 2.5 Flash Image / "Nano Banana"). Accepts reference images, which
+ * are passed as `inlineData` parts alongside the text prompt.
+ *
+ * @internal
+ */
+async function callGeminiImageOutGeneration(config, request, logger, signal) {
+    var _a;
+    const url = `${config.baseUrl}/models/${config.model}:generateContent`;
+    const refs = (_a = request.referenceImages) !== null && _a !== void 0 ? _a : [];
+    const parts = [{ text: request.prompt }];
+    for (const ref of refs) {
+        parts.push({ inlineData: { mimeType: ref.mimeType, data: ref.base64 } });
+    }
+    const body = {
+        contents: [{ role: 'user', parts }]
+    };
     const headers = {
-        Authorization: `Bearer ${config.apiKey}`
+        'x-goog-api-key': config.apiKey
     };
     /* c8 ignore next 1 - optional logger */
-    logger === null || logger === void 0 ? void 0 : logger.info(`Image generation: model=${config.model}, n=${body.n}`);
-    const jsonResult = await fetchJson(url, headers, body, logger, signal);
-    if (jsonResult.isFailure()) {
-        return fail(jsonResult.message);
-    }
-    return openAiImageResponse
-        .validate(jsonResult.value)
-        .withErrorFormat((msg) => `OpenAI images API response: ${msg}`)
+    logger === null || logger === void 0 ? void 0 : logger.info(`Gemini image-out: model=${config.model}, refs=${refs.length}`);
+    return (await fetchJson(url, headers, body, logger, signal)).onSuccess((json) => geminiImageOutResponse
+        .validate(json)
+        .withErrorFormat((msg) => `Gemini image API response: ${msg}`)
         .onSuccess((response) => {
-        const images = response.data.map((item) => (Object.assign({ mimeType: defaultMimeType, base64: item.b64_json }, (item.revised_prompt !== undefined ? { revisedPrompt: item.revised_prompt } : {}))));
+        const images = [];
+        for (const candidate of response.candidates) {
+            for (const part of candidate.content.parts) {
+                if (part.inlineData) {
+                    images.push({
+                        mimeType: part.inlineData.mimeType,
+                        base64: part.inlineData.data
+                    });
+                }
+            }
+        }
+        if (images.length === 0) {
+            return fail('Gemini image API response: no image parts in response');
+        }
         return succeed({ images });
-    });
+    }));
 }
 /**
  * Calls the Gemini Imagen `:predict` endpoint.
@@ -573,45 +777,61 @@ async function callImagenGeneration(config, request, logger, signal) {
 /**
  * Calls the appropriate image-generation API for a given provider.
  *
- * Routes based on `descriptor.imageApiFormat`:
+ * Resolves a {@link IAiImageModelCapability} from
+ * {@link IAiProviderDescriptor.imageGeneration} for the requested model and
+ * routes by its `format`:
  * - `'openai-images'` for OpenAI (DALL-E, gpt-image-1)
  * - `'xai-images'` for xAI Grok image models
- * - `'gemini-imagen'` for Google Imagen
+ * - `'gemini-imagen'` for Google Imagen `:predict`
+ * - `'gemini-image-out'` for Gemini chat-style image output (Nano Banana)
  *
  * Image-model selection reuses the existing `'image'` {@link ModelSpecKey}.
+ * When `request.referenceImages` is non-empty, the call is rejected up front
+ * unless the resolved capability declares `acceptsImageReferenceInput`.
  *
  * @param params - Request parameters including descriptor, API key, and prompt
  * @returns The generated images, or a failure
  * @public
  */
 export async function callProviderImageGeneration(params) {
+    var _a, _b;
     const { descriptor, apiKey, params: request, modelOverride, logger, signal } = params;
-    if (descriptor.imageApiFormat === undefined) {
+    if (!supportsImageGeneration(descriptor)) {
         return fail(`provider "${descriptor.id}" does not support image generation`);
     }
     if (!descriptor.baseUrl) {
         return fail(`provider "${descriptor.id}" has no API endpoint configured`);
     }
+    const model = resolveModel(modelOverride !== null && modelOverride !== void 0 ? modelOverride : descriptor.defaultModel, 'image');
+    const capability = resolveImageCapability(descriptor, model);
+    if (capability === undefined) {
+        return fail(`provider "${descriptor.id}" does not support image generation for model "${model}"`);
+    }
+    if (((_b = (_a = request.referenceImages) === null || _a === void 0 ? void 0 : _a.length) !== null && _b !== void 0 ? _b : 0) > 0 && !capability.acceptsImageReferenceInput) {
+        return fail(`model "${model}" does not support reference images`);
+    }
     const config = {
         baseUrl: descriptor.baseUrl,
         apiKey,
-        model: resolveModel(modelOverride !== null && modelOverride !== void 0 ? modelOverride : descriptor.defaultModel, 'image')
+        model
     };
     /* c8 ignore next 6 - optional logger diagnostic output */
     if (logger) {
-        logger.info(`AI image generation: provider=${descriptor.id}, format=${descriptor.imageApiFormat}, ` +
+        logger.info(`AI image generation: provider=${descriptor.id}, format=${capability.format}, ` +
             `model=${config.model}`);
     }
-    switch (descriptor.imageApiFormat) {
+    switch (capability.format) {
         case 'openai-images':
             return callOpenAiImageGeneration(config, request, 'image/png', logger, signal);
         case 'xai-images':
             return callOpenAiImageGeneration(config, request, 'image/jpeg', logger, signal);
         case 'gemini-imagen':
             return callImagenGeneration(config, request, logger, signal);
+        case 'gemini-image-out':
+            return callGeminiImageOutGeneration(config, request, logger, signal);
         /* c8 ignore next 4 - defensive coding: exhaustive switch guaranteed by TypeScript */
         default: {
-            const _exhaustive = descriptor.imageApiFormat;
+            const _exhaustive = capability.format;
             return fail(`unsupported image API format: ${String(_exhaustive)}`);
         }
     }
@@ -961,7 +1181,10 @@ export async function callProxiedCompletion(proxyUrl, params) {
  * - Error response body: `{error: string}` (surfaced as `proxy: ${error}`)
  *
  * The proxy server is responsible for descriptor lookup, model resolution,
- * provider dispatch, and response normalization.
+ * provider dispatch, and response normalization. When `params.referenceImages`
+ * is present, the proxy is also responsible for repackaging it into the
+ * upstream wire format (e.g. multipart/form-data for OpenAI `/images/edits`,
+ * `inlineData` parts for Gemini `:generateContent`).
  *
  * @param proxyUrl - Base URL of the proxy server (e.g. `http://localhost:3001`)
  * @param params - Same parameters as {@link callProviderImageGeneration}

package/dist/packlets/ai-assist/index.js

@@ -3,7 +3,7 @@
  * @packageDocumentation
  */
 export { AiPrompt, DEFAULT_AI_ASSIST, allModelSpecKeys, MODEL_SPEC_BASE_KEY, resolveModel, toDataUrl } from './model';
-export { allProviderIds, getProviderDescriptors, getProviderDescriptor, DEFAULT_MODEL_CAPABILITY_CONFIG } from './registry';
+export { allProviderIds, getProviderDescriptors, getProviderDescriptor, resolveImageCapability, supportsImageGeneration, DEFAULT_MODEL_CAPABILITY_CONFIG } from './registry';
 export { callProviderCompletion, callProxiedCompletion, callProviderImageGeneration, callProxiedImageGeneration, callProviderListModels, callProxiedListModels } from './apiClient';
 export { callProviderCompletionStream, callProxiedCompletionStream } from './streamingClient';
 export { aiProviderId, aiServerToolType, aiWebSearchToolConfig, aiServerToolConfig, aiToolEnablement, aiAssistProviderConfig, aiAssistSettings, modelSpecKey, modelSpec } from './converters';

package/dist/packlets/ai-assist/registry.js

@@ -63,12 +63,17 @@ const BUILTIN_PROVIDERS = [
         needsSecret: true,
         apiFormat: 'gemini',
         baseUrl: 'https://generativelanguage.googleapis.com/v1beta',
-        defaultModel: { base: 'gemini-2.5-flash', image: 'imagen-3.0-generate-002' },
+        defaultModel: { base: 'gemini-2.5-flash', image: 'gemini-2.5-flash-image' },
         supportedTools: ['web_search'],
         corsRestricted: false,
         streamingCorsRestricted: false,
         acceptsImageInput: true,
-        imageApiFormat: 'gemini-imagen'
+        imageGeneration: [
+            // imagen-* models are predict-only and do not accept reference images;
+            // everything else uses chat-style :generateContent with refs.
+            { modelPrefix: 'imagen-', format: 'gemini-imagen' },
+            { modelPrefix: '', format: 'gemini-image-out', acceptsImageReferenceInput: true }
+        ]
     },
     {
         id: 'groq',
@@ -108,7 +113,14 @@ const BUILTIN_PROVIDERS = [
         corsRestricted: false,
         streamingCorsRestricted: false,
         acceptsImageInput: true,
-        imageApiFormat: 'openai-images'
+        imageGeneration: [
+            // gpt-image-1 supports /images/edits with reference images. dall-e-3
+            // (the default image model) does not, so the catch-all rule omits
+            // acceptsImageReferenceInput; callers selecting dall-e-3 with refs hit
+            // the up-front rejection rather than a provider 400.
+            { modelPrefix: 'gpt-image-', format: 'openai-images', acceptsImageReferenceInput: true },
+            { modelPrefix: '', format: 'openai-images' }
+        ]
     },
     {
         id: 'xai-grok',
@@ -126,7 +138,7 @@ const BUILTIN_PROVIDERS = [
         corsRestricted: true,
         streamingCorsRestricted: true,
         acceptsImageInput: true,
-        imageApiFormat: 'xai-images'
+        imageGeneration: [{ modelPrefix: '', format: 'xai-images' }]
     }
 ];
 /**
@@ -163,6 +175,38 @@ export function getProviderDescriptor(id) {
     }
     return succeed(descriptor);
 }
+/**
+ * Whether a provider declares any image-generation capability at all.
+ *
+ * @param descriptor - The provider descriptor
+ * @returns `true` when {@link IAiProviderDescriptor.imageGeneration} has at
+ *   least one entry; `false` otherwise.
+ * @public
+ */
+export function supportsImageGeneration(descriptor) {
+    var _a, _b;
+    return ((_b = (_a = descriptor.imageGeneration) === null || _a === void 0 ? void 0 : _a.length) !== null && _b !== void 0 ? _b : 0) > 0;
+}
+/**
+ * Resolve the image-generation capability that applies to a given model id
+ * for a provider. Returns the entry from
+ * {@link IAiProviderDescriptor.imageGeneration} whose `modelPrefix` is the
+ * longest prefix of `modelId`. Ties are broken by first-encountered, so rule
+ * order does not matter for correctness — only for tie-breaking among rules
+ * with identical-length prefixes (an unusual case).
+ *
+ * @param descriptor - The provider descriptor
+ * @param modelId - The resolved image model id
+ * @returns The matching capability, or `undefined` when no rule matches or
+ *   the provider declares no image-generation capabilities.
+ * @public
+ */
+export function resolveImageCapability(descriptor, modelId) {
+    var _a;
+    return ((_a = descriptor.imageGeneration) !== null && _a !== void 0 ? _a : [])
+        .filter((cap) => modelId.startsWith(cap.modelPrefix))
+        .reduce((best, cap) => (best && best.modelPrefix.length >= cap.modelPrefix.length ? best : cap), undefined);
+}
 // ============================================================================
 // Default model capability config
 // ============================================================================
@@ -191,6 +235,7 @@ export const DEFAULT_MODEL_CAPABILITY_CONFIG = {
         ],
         'google-gemini': [
             { idPattern: /^imagen/, capabilities: ['image-generation'] },
+            { idPattern: /^gemini-.*-image/, capabilities: ['image-generation'] },
             { idPattern: /^gemini-/, capabilities: ['chat', 'tools', 'vision'] }
         ],
         anthropic: [{ idPattern: /^claude-/, capabilities: ['chat', 'tools', 'vision'] }],

package/dist/packlets/crypto-utils/nodeCryptoProvider.js

@@ -205,6 +205,102 @@ export class NodeCryptoProvider {
         const result = await captureAsyncResult(() => crypto.webcrypto.subtle.importKey('jwk', jwk, params.importPublicKey, true, params.publicKeyUsages));
         return result.withErrorFormat((e) => `Failed to import ${algorithm} public key from JWK: ${e}`);
     }
+    /**
+     * Wraps `plaintext` for the holder of `recipientPublicKey` using
+     * ECIES (ECDH P-256 + HKDF-SHA256 + AES-GCM-256). See
+     * {@link CryptoUtils.ICryptoProvider.wrapBytes | ICryptoProvider.wrapBytes}.
+     * @param plaintext - The bytes to wrap.
+     * @param recipientPublicKey - The recipient's ECDH P-256 public `CryptoKey`.
+     * @param options - HKDF salt and info; see {@link CryptoUtils.IWrapBytesOptions | IWrapBytesOptions}.
+     * @returns `Success` with the wrapped payload, or `Failure` with an error.
+     */
+    async wrapBytes(plaintext, recipientPublicKey, options) {
+        const recipientCheck = checkEcdhP256(recipientPublicKey, 'public', 'recipient public key');
+        if (recipientCheck.isFailure()) {
+            return fail(`wrapBytes failed: ${recipientCheck.message}`);
+        }
+        const subtle = crypto.webcrypto.subtle;
+        const result = await captureAsyncResult(async () => {
+            const ephemeral = (await subtle.generateKey({ name: 'ECDH', namedCurve: 'P-256' }, true, [
+                'deriveKey'
+            ]));
+            const hkdfBase = await subtle.deriveKey({ name: 'ECDH', public: recipientPublicKey }, ephemeral.privateKey, { name: 'HKDF' }, false, ['deriveKey']);
+            const wrapKey = await subtle.deriveKey({ name: 'HKDF', salt: options.salt, info: options.info, hash: 'SHA-256' }, hkdfBase, { name: 'AES-GCM', length: 256 }, false, ['encrypt']);
+            const nonce = crypto.randomBytes(Constants.GCM_IV_SIZE);
+            const ctBuf = await subtle.encrypt({ name: 'AES-GCM', iv: nonce }, wrapKey, plaintext);
+            const ephemeralPublicKey = await subtle.exportKey('jwk', ephemeral.publicKey);
+            return {
+                ephemeralPublicKey,
+                nonce: this.toBase64(nonce),
+                ciphertext: this.toBase64(new Uint8Array(ctBuf))
+            };
+        });
+        return result.withErrorFormat((e) => `wrapBytes failed: ${e}`);
+    }
+    /**
+     * Unwraps a payload produced by `wrapBytes` using the recipient's private
+     * key. See {@link CryptoUtils.ICryptoProvider.unwrapBytes | ICryptoProvider.unwrapBytes}.
+     * @param wrapped - The wrapped payload.
+     * @param recipientPrivateKey - The recipient's ECDH P-256 private `CryptoKey`.
+     * @param options - HKDF salt and info matching the wrap call.
+     * @returns `Success` with the original `plaintext`, or `Failure` with an error.
+     */
+    async unwrapBytes(wrapped, recipientPrivateKey, options) {
+        const recipientCheck = checkEcdhP256(recipientPrivateKey, 'private', 'recipient private key');
+        if (recipientCheck.isFailure()) {
+            return fail(`unwrapBytes failed: ${recipientCheck.message}`);
+        }
+        const nonceResult = this.fromBase64(wrapped.nonce);
+        if (nonceResult.isFailure()) {
+            return fail(`unwrapBytes failed: nonce: ${nonceResult.message}`);
+        }
+        if (nonceResult.value.length !== Constants.GCM_IV_SIZE) {
+            return fail(`unwrapBytes failed: nonce must be ${Constants.GCM_IV_SIZE} bytes (got ${nonceResult.value.length})`);
+        }
+        const ciphertextResult = this.fromBase64(wrapped.ciphertext);
+        if (ciphertextResult.isFailure()) {
+            return fail(`unwrapBytes failed: ciphertext: ${ciphertextResult.message}`);
+        }
+        if (ciphertextResult.value.length < Constants.GCM_AUTH_TAG_SIZE) {
+            return fail(`unwrapBytes failed: ciphertext must be at least ${Constants.GCM_AUTH_TAG_SIZE} bytes (got ${ciphertextResult.value.length})`);
+        }
+        const subtle = crypto.webcrypto.subtle;
+        const result = await captureAsyncResult(async () => {
+            const ephemeralPub = await subtle.importKey('jwk', wrapped.ephemeralPublicKey, { name: 'ECDH', namedCurve: 'P-256' }, false, []);
+            const hkdfBase = await subtle.deriveKey({ name: 'ECDH', public: ephemeralPub }, recipientPrivateKey, { name: 'HKDF' }, false, ['deriveKey']);
+            const wrapKey = await subtle.deriveKey({ name: 'HKDF', salt: options.salt, info: options.info, hash: 'SHA-256' }, hkdfBase, { name: 'AES-GCM', length: 256 }, false, ['decrypt']);
+            const ptBuf = await subtle.decrypt({ name: 'AES-GCM', iv: nonceResult.value }, wrapKey, ciphertextResult.value);
+            return new Uint8Array(ptBuf);
+        });
+        return result.withErrorFormat((e) => `unwrapBytes failed: ${e}`);
+    }
+}
+/**
+ * Verifies that `key` is an ECDH P-256 `CryptoKey` of the expected `keyType`
+ * (public or private). Used by the wrap/unwrap methods to surface a clean
+ * `Failure` instead of letting the WebCrypto deriveKey call throw a less
+ * informative error later in the pipeline. Key usages are intentionally not
+ * checked here: WebCrypto already produces a specific error if `deriveKey` is
+ * not in `usages`, and `deriveBits` is an equally valid alternative usage that
+ * an explicit check would have to track.
+ * @param key - The CryptoKey to validate.
+ * @param keyType - The required `key.type` ('public' for wrap, 'private' for unwrap).
+ * @param label - Human-readable role label included in the failure message.
+ * @returns `Success` with the key (unchanged) when the algorithm, curve, and
+ * type all match; otherwise `Failure` with `<label> must be ECDH P-256 (...)`.
+ */
+function checkEcdhP256(key, keyType, label) {
+    if (key.algorithm.name !== 'ECDH') {
+        return fail(`${label} must be ECDH P-256 (got algorithm '${key.algorithm.name}')`);
+    }
+    const namedCurve = key.algorithm.namedCurve;
+    if (namedCurve !== 'P-256') {
+        return fail(`${label} must be ECDH P-256 (got curve '${namedCurve}')`);
+    }
+    if (key.type !== keyType) {
+        return fail(`${label} must be a ${keyType} CryptoKey (got '${key.type}')`);
+    }
+    return succeed(key);
 }
 /**
  * Singleton instance of {@link CryptoUtils.NodeCryptoProvider}.