@fgv/ts-extras 5.1.0-15 → 5.1.0-17

package/dist/packlets/ai-assist/streamingAdapters/openaiResponses.js

@@ -0,0 +1,163 @@
+// Copyright (c) 2026 Erik Fortune
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in all
+// copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+var __await = (this && this.__await) || function (v) { return this instanceof __await ? (this.v = v, this) : new __await(v); }
+var __asyncValues = (this && this.__asyncValues) || function (o) {
+    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
+    var m = o[Symbol.asyncIterator], i;
+    return m ? m.call(o) : (o = typeof __values === "function" ? __values(o) : o[Symbol.iterator](), i = {}, verb("next"), verb("throw"), verb("return"), i[Symbol.asyncIterator] = function () { return this; }, i);
+    function verb(n) { i[n] = o[n] && function (v) { return new Promise(function (resolve, reject) { v = o[n](v), settle(resolve, reject, v.done, v.value); }); }; }
+    function settle(resolve, reject, d, v) { Promise.resolve(v).then(function(v) { resolve({ value: v, done: d }); }, reject); }
+};
+var __asyncGenerator = (this && this.__asyncGenerator) || function (thisArg, _arguments, generator) {
+    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
+    var g = generator.apply(thisArg, _arguments || []), i, q = [];
+    return i = Object.create((typeof AsyncIterator === "function" ? AsyncIterator : Object).prototype), verb("next"), verb("throw"), verb("return", awaitReturn), i[Symbol.asyncIterator] = function () { return this; }, i;
+    function awaitReturn(f) { return function (v) { return Promise.resolve(v).then(f, reject); }; }
+    function verb(n, f) { if (g[n]) { i[n] = function (v) { return new Promise(function (a, b) { q.push([n, v, a, b]) > 1 || resume(n, v); }); }; if (f) i[n] = f(i[n]); } }
+    function resume(n, v) { try { step(g[n](v)); } catch (e) { settle(q[0][3], e); } }
+    function step(r) { r.value instanceof __await ? Promise.resolve(r.value.v).then(fulfill, reject) : settle(q[0][2], r); }
+    function fulfill(value) { resume("next", value); }
+    function reject(value) { resume("throw", value); }
+    function settle(f, v) { if (f(v), q.shift(), q.length) resume(q[0][0], q[0][1]); }
+};
+/**
+ * Streaming adapter for the OpenAI / xAI Responses API. This is the format
+ * used when server-side tools (e.g. web_search) are requested — Chat
+ * Completions doesn't support tool progress events, but the Responses API
+ * does.
+ *
+ * @packageDocumentation
+ */
+import { succeed, Validators } from '@fgv/ts-utils';
+import { buildMessages, buildOpenAiResponsesUserContent } from '../chatRequestBuilders';
+import { parseSseEventJson, readSseEvents } from '../sseParser';
+import { toResponsesApiTools } from '../toolFormats';
+import { openSseConnection, validateEventPayload } from './common';
+const responsesDeltaPayload = Validators.object({
+    delta: Validators.string
+});
+const responsesCompletedPayload = Validators.object({
+    response: Validators.object({ status: Validators.string.optional() }, { options: { optionalFields: ['status'] } })
+});
+const responsesErrorInner = Validators.object({ message: Validators.string.optional() }, { options: { optionalFields: ['message'] } });
+const responsesErrorPayload = Validators.object({
+    error: responsesErrorInner.optional(),
+    message: Validators.string.optional()
+}, { options: { optionalFields: ['error', 'message'] } });
+// ============================================================================
+// Stream translator
+// ============================================================================
+/**
+ * Translates an OpenAI Responses API SSE stream into unified events.
+ *
+ * @internal
+ */
+function translateOpenAiResponsesStream(response) {
+    return __asyncGenerator(this, arguments, function* translateOpenAiResponsesStream_1() {
+        var _a, e_1, _b, _c;
+        var _d, _e, _f;
+        let fullText = '';
+        let truncated = false;
+        let completed = false;
+        try {
+            /* c8 ignore next - body is non-null at this point per openSseConnection */
+            if (!response.body)
+                return yield __await(void 0);
+            try {
+                for (var _g = true, _h = __asyncValues(readSseEvents(response.body)), _j; _j = yield __await(_h.next()), _a = _j.done, !_a; _g = true) {
+                    _c = _j.value;
+                    _g = false;
+                    const message = _c;
+                    const eventName = message.event;
+                    if (eventName === 'response.output_text.delta') {
+                        const payload = validateEventPayload(parseSseEventJson(message.data), responsesDeltaPayload);
+                        const delta = payload === null || payload === void 0 ? void 0 : payload.delta;
+                        if (typeof delta === 'string' && delta.length > 0) {
+                            fullText += delta;
+                            yield yield __await({ type: 'text-delta', delta });
+                        }
+                    }
+                    else if (eventName === 'response.web_search_call.in_progress') {
+                        yield yield __await({ type: 'tool-event', toolType: 'web_search', phase: 'started' });
+                    }
+                    else if (eventName === 'response.web_search_call.completed') {
+                        yield yield __await({ type: 'tool-event', toolType: 'web_search', phase: 'completed' });
+                    }
+                    else if (eventName === 'response.completed') {
+                        const payload = validateEventPayload(parseSseEventJson(message.data), responsesCompletedPayload);
+                        truncated = (payload === null || payload === void 0 ? void 0 : payload.response.status) === 'incomplete';
+                        completed = true;
+                    }
+                    else if (eventName === 'response.failed' || eventName === 'error') {
+                        const payload = validateEventPayload(parseSseEventJson(message.data), responsesErrorPayload);
+                        const errMsg = (_f = (_e = (_d = payload === null || payload === void 0 ? void 0 : payload.error) === null || _d === void 0 ? void 0 : _d.message) !== null && _e !== void 0 ? _e : payload === null || payload === void 0 ? void 0 : payload.message) !== null && _f !== void 0 ? _f : 'Responses API stream failed';
+                        yield yield __await({ type: 'error', message: errMsg });
+                        return yield __await(void 0);
+                    }
+                }
+            }
+            catch (e_1_1) { e_1 = { error: e_1_1 }; }
+            finally {
+                try {
+                    if (!_g && !_a && (_b = _h.return)) yield __await(_b.call(_h));
+                }
+                finally { if (e_1) throw e_1.error; }
+            }
+        }
+        catch (err) {
+            yield yield __await({ type: 'error', message: err instanceof Error ? err.message : String(err) });
+            return yield __await(void 0);
+        }
+        if (completed) {
+            yield yield __await({ type: 'done', truncated, fullText });
+        }
+        else {
+            yield yield __await({ type: 'error', message: 'Responses API stream ended without a completed event' });
+        }
+    });
+}
+// ============================================================================
+// Per-format request caller
+// ============================================================================
+/**
+ * Issues a streaming Responses API request (with tools) and returns the
+ * unified-event iterable on success.
+ *
+ * @internal
+ */
+export async function callOpenAiResponsesStream(config, prompt, tools, messagesBefore, temperature, logger, signal) {
+    const url = `${config.baseUrl}/responses`;
+    const input = buildMessages(prompt.system, buildOpenAiResponsesUserContent(prompt), {
+        head: messagesBefore
+    });
+    const body = {
+        model: config.model,
+        input,
+        tools: toResponsesApiTools(tools),
+        temperature,
+        stream: true
+    };
+    const headers = { Authorization: `Bearer ${config.apiKey}` };
+    /* c8 ignore next 1 - optional logger */
+    logger === null || logger === void 0 ? void 0 : logger.info(`OpenAI Responses streaming: model=${config.model}, tools=${tools.map((t) => t.type).join(',')}`);
+    const conn = await openSseConnection(url, headers, body, logger, signal);
+    return conn.onSuccess((response) => succeed(translateOpenAiResponsesStream(response)));
+}
+//# sourceMappingURL=openaiResponses.js.map

package/dist/packlets/ai-assist/streamingAdapters/proxy.js

@@ -0,0 +1,157 @@
+// Copyright (c) 2026 Erik Fortune
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in all
+// copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+var __await = (this && this.__await) || function (v) { return this instanceof __await ? (this.v = v, this) : new __await(v); }
+var __asyncValues = (this && this.__asyncValues) || function (o) {
+    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
+    var m = o[Symbol.asyncIterator], i;
+    return m ? m.call(o) : (o = typeof __values === "function" ? __values(o) : o[Symbol.iterator](), i = {}, verb("next"), verb("throw"), verb("return"), i[Symbol.asyncIterator] = function () { return this; }, i);
+    function verb(n) { i[n] = o[n] && function (v) { return new Promise(function (resolve, reject) { v = o[n](v), settle(resolve, reject, v.done, v.value); }); }; }
+    function settle(resolve, reject, d, v) { Promise.resolve(v).then(function(v) { resolve({ value: v, done: d }); }, reject); }
+};
+var __asyncGenerator = (this && this.__asyncGenerator) || function (thisArg, _arguments, generator) {
+    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
+    var g = generator.apply(thisArg, _arguments || []), i, q = [];
+    return i = Object.create((typeof AsyncIterator === "function" ? AsyncIterator : Object).prototype), verb("next"), verb("throw"), verb("return", awaitReturn), i[Symbol.asyncIterator] = function () { return this; }, i;
+    function awaitReturn(f) { return function (v) { return Promise.resolve(v).then(f, reject); }; }
+    function verb(n, f) { if (g[n]) { i[n] = function (v) { return new Promise(function (a, b) { q.push([n, v, a, b]) > 1 || resume(n, v); }); }; if (f) i[n] = f(i[n]); } }
+    function resume(n, v) { try { step(g[n](v)); } catch (e) { settle(q[0][3], e); } }
+    function step(r) { r.value instanceof __await ? Promise.resolve(r.value.v).then(fulfill, reject) : settle(q[0][2], r); }
+    function fulfill(value) { resume("next", value); }
+    function reject(value) { resume("throw", value); }
+    function settle(f, v) { if (f(v), q.shift(), q.length) resume(q[0][0], q[0][1]); }
+};
+/**
+ * Streaming adapter for a caller-provided proxy server. Unlike the
+ * provider-specific adapters, the proxy speaks our own unified vocabulary
+ * directly: each `data:` line is a JSON-serialized {@link AiAssist.IAiStreamEvent},
+ * so this adapter only validates the event-type discriminator and forwards.
+ *
+ * @packageDocumentation
+ */
+import { succeed, Validators } from '@fgv/ts-utils';
+import { parseSseEventJson, readSseEvents } from '../sseParser';
+import { openSseConnection, validateEventPayload } from './common';
+const proxyEventTypes = ['text-delta', 'tool-event', 'done', 'error'];
+const proxyEventEnvelope = Validators.object({
+    type: Validators.enumeratedValue(proxyEventTypes)
+});
+// ============================================================================
+// Stream translator
+// ============================================================================
+/**
+ * Translates a proxied SSE stream back into {@link AiAssist.IAiStreamEvent} objects.
+ * Validation is limited to the type discriminator; the proxy is contractually
+ * required to emit shape-correct unified events.
+ *
+ * @internal
+ */
+function translateProxyStream(response) {
+    return __asyncGenerator(this, arguments, function* translateProxyStream_1() {
+        var _a, e_1, _b, _c;
+        try {
+            /* c8 ignore next - body is non-null at this point per openSseConnection */
+            if (!response.body)
+                return yield __await(void 0);
+            try {
+                for (var _d = true, _e = __asyncValues(readSseEvents(response.body)), _f; _f = yield __await(_e.next()), _a = _f.done, !_a; _d = true) {
+                    _c = _f.value;
+                    _d = false;
+                    const message = _c;
+                    const json = parseSseEventJson(message.data);
+                    if (json === undefined) {
+                        continue;
+                    }
+                    const envelope = validateEventPayload(json, proxyEventEnvelope);
+                    if (!envelope) {
+                        continue;
+                    }
+                    const event = json;
+                    yield yield __await(event);
+                    if (envelope.type === 'done' || envelope.type === 'error') {
+                        return yield __await(void 0);
+                    }
+                }
+            }
+            catch (e_1_1) { e_1 = { error: e_1_1 }; }
+            finally {
+                try {
+                    if (!_d && !_a && (_b = _e.return)) yield __await(_b.call(_e));
+                }
+                finally { if (e_1) throw e_1.error; }
+            }
+        }
+        catch (err) {
+            yield yield __await({ type: 'error', message: err instanceof Error ? err.message : String(err) });
+        }
+    });
+}
+// ============================================================================
+// Public entry point
+// ============================================================================
+/**
+ * Calls the streaming chat endpoint on a proxy server instead of calling
+ * the provider directly from the browser.
+ *
+ * @remarks
+ * Proxy contract:
+ * - Endpoint: `POST ${proxyUrl}/api/ai/completion-stream`
+ * - Request body: same JSON as `/api/ai/completion` plus `"stream": true`
+ * - Response: `Content-Type: text/event-stream`; body is the unified
+ *   {@link AiAssist.IAiStreamEvent} JSON-serialized one event per SSE `data:` line
+ *   (no `event:` line needed since the type discriminator is in the JSON).
+ * - Error response (when the proxy can't even start): JSON `{error: string}`
+ *   with a non-2xx status, surfaced as `proxy: ${error}`.
+ *
+ * The proxy server is responsible for opening the upstream SSE connection,
+ * translating provider-native events to the unified vocabulary, and
+ * forwarding events as they arrive (no buffering). The library does not
+ * ship a proxy implementation.
+ *
+ * @public
+ */
+export async function callProxiedCompletionStream(proxyUrl, params) {
+    const { descriptor, apiKey, prompt, messagesBefore, temperature, modelOverride, logger, tools, signal } = params;
+    const promptBody = { system: prompt.system, user: prompt.user };
+    if (prompt.attachments.length > 0) {
+        promptBody.attachments = prompt.attachments;
+    }
+    const body = {
+        providerId: descriptor.id,
+        apiKey,
+        prompt: promptBody,
+        temperature: temperature !== null && temperature !== void 0 ? temperature : 0.7,
+        stream: true
+    };
+    if (messagesBefore && messagesBefore.length > 0) {
+        body.messagesBefore = messagesBefore;
+    }
+    if (modelOverride !== undefined) {
+        body.modelOverride = modelOverride;
+    }
+    if (tools && tools.length > 0) {
+        body.tools = tools;
+    }
+    /* c8 ignore next 1 - optional logger */
+    logger === null || logger === void 0 ? void 0 : logger.info(`AI streaming proxy request: provider=${descriptor.id}, proxy=${proxyUrl}`);
+    const url = `${proxyUrl}/api/ai/completion-stream`;
+    const conn = await openSseConnection(url, {}, body, logger, signal);
+    return conn.onSuccess((response) => succeed(translateProxyStream(response)));
+}
+//# sourceMappingURL=proxy.js.map

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

@@ -0,0 +1,88 @@
+// Copyright (c) 2026 Erik Fortune
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in all
+// copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+/**
+ * Streaming chat completion client. Public façade over the per-format
+ * adapters under `streamingAdapters/`: provider dispatch and pre-flight
+ * validation live here; format-specific request/translation logic and the
+ * typed event-payload validators live with each adapter.
+ *
+ * @packageDocumentation
+ */
+import { fail } from '@fgv/ts-utils';
+import { resolveModel } from './model';
+import { callAnthropicStream } from './streamingAdapters/anthropic';
+import { callGeminiStream } from './streamingAdapters/gemini';
+import { callOpenAiChatStream } from './streamingAdapters/openaiChat';
+import { callOpenAiResponsesStream } from './streamingAdapters/openaiResponses';
+export { callProxiedCompletionStream } from './streamingAdapters/proxy';
+/**
+ * Calls the appropriate streaming chat completion API for a given provider.
+ *
+ * @remarks
+ * Pre-flight rejection: when `descriptor.streamingCorsRestricted === true`
+ * and the call isn't being routed through a proxy, this returns
+ * `Result.fail` before fetch is invoked. Callers should route through
+ * {@link AiAssist.callProxiedCompletionStream} or surface the failure to the user.
+ *
+ * Connection-time failures (auth, network, non-2xx) surface as the outer
+ * `Result.fail`. Once iteration begins, errors mid-stream surface as a
+ * terminal error event ({@link AiAssist.IAiStreamError}) followed by the iterable
+ * ending. The final successful event is {@link AiAssist.IAiStreamDone}.
+ *
+ * @param params - Request parameters including descriptor, API key, prompt, and optional tools
+ * @returns A streaming iterable of unified events, or a Result.fail
+ * @public
+ */
+export async function callProviderCompletionStream(params) {
+    const { descriptor, apiKey, prompt, messagesBefore, temperature = 0.7, modelOverride, logger, tools, signal } = params;
+    if (!descriptor.baseUrl) {
+        return fail(`provider "${descriptor.id}" has no API endpoint configured`);
+    }
+    if (descriptor.streamingCorsRestricted) {
+        return fail(`provider "${descriptor.id}" requires a proxy for streaming; none is configured`);
+    }
+    if (prompt.attachments.length > 0 && !descriptor.acceptsImageInput) {
+        return fail(`provider "${descriptor.id}" does not accept image input`);
+    }
+    const hasTools = tools !== undefined && tools.length > 0;
+    const modelContext = hasTools ? 'tools' : undefined;
+    const config = {
+        baseUrl: descriptor.baseUrl,
+        apiKey,
+        model: resolveModel(modelOverride !== null && modelOverride !== void 0 ? modelOverride : descriptor.defaultModel, modelContext)
+    };
+    switch (descriptor.apiFormat) {
+        case 'openai':
+            if (hasTools) {
+                return callOpenAiResponsesStream(config, prompt, tools, messagesBefore, temperature, logger, signal);
+            }
+            return callOpenAiChatStream(config, prompt, messagesBefore, temperature, logger, signal);
+        case 'anthropic':
+            return callAnthropicStream(config, prompt, messagesBefore, temperature, tools, logger, signal);
+        case 'gemini':
+            return callGeminiStream(config, prompt, messagesBefore, temperature, tools, logger, signal);
+        /* c8 ignore next 4 - defensive coding: exhaustive switch guaranteed by TypeScript */
+        default: {
+            const _exhaustive = descriptor.apiFormat;
+            return fail(`unsupported API format: ${String(_exhaustive)}`);
+        }
+    }
+}
+//# sourceMappingURL=streamingClient.js.map

package/dist/packlets/conversion/converters.js

@@ -101,7 +101,7 @@ export const isoDateTime = new Conversion.BaseConverter((from) => {
  * If `onError` is `'failOnError'` (default), then the entire conversion fails if any element cannot
  * be converted.  If `onError` is `'ignoreErrors'`, then failing elements are silently ignored.
  * @param converter - `Converter` used to convert each item in the array
- * @param ignoreErrors - Specifies treatment of unconvertible elements
+ * @param onError - Specifies treatment of unconvertible elements
  * @beta
  */
 export function extendedArrayOf(label, converter, onError = 'failOnError') {

package/dist/packlets/crypto-utils/keystore/keyStore.js

@@ -584,49 +584,29 @@ export class KeyStore {
         if (keyResult.isFailure()) {
             return fail(`Key derivation failed: ${keyResult.message}`);
         }
-        // Build vault contents
-        const secrets = {};
-        for (const [name, entry] of this._secrets) {
-            secrets[name] = {
-                name: entry.name,
-                type: entry.type,
-                key: this._cryptoProvider.toBase64(entry.key),
-                description: entry.description,
-                createdAt: entry.createdAt
-            };
-        }
-        const vaultContents = {
-            version: KEYSTORE_FORMAT,
-            secrets
-        };
-        // Serialize and encrypt
-        const jsonResult = captureResult(() => JSON.stringify(vaultContents));
-        /* c8 ignore next 3 - error path tested but coverage intermittently missed */
-        if (jsonResult.isFailure()) {
-            return fail(`Failed to serialize vault: ${jsonResult.message}`);
+        return this._encryptVault(keyResult.value);
+    }
+    /**
+     * Saves the key store using a pre-derived key, bypassing PBKDF2 key
+     * derivation. Use this when the derived key has been stored externally
+     * (e.g., in another key store) and the original password is no longer
+     * available.
+     *
+     * The supplied key must be the same key that was (or would be) derived
+     * from the master password using the key store's PBKDF2 parameters.
+     *
+     * @param derivedKey - The pre-derived master key (32 bytes for AES-256)
+     * @returns Success with IKeyStoreFile, Failure if locked or key invalid
+     * @public
+     */
+    async saveWithKey(derivedKey) {
+        if (!this._secrets || !this._salt) {
+            return fail('Key store is locked');
         }
-        const encryptResult = await this._cryptoProvider.encrypt(jsonResult.value, keyResult.value);
-        /* c8 ignore next 3 - crypto provider errors tested but coverage intermittently missed */
-        if (encryptResult.isFailure()) {
-            return fail(`Encryption failed: ${encryptResult.message}`);
+        if (derivedKey.length !== Constants.AES_256_KEY_SIZE) {
+            return fail(`Key must be ${Constants.AES_256_KEY_SIZE} bytes, got ${derivedKey.length}`);
         }
-        const { iv, authTag, encryptedData } = encryptResult.value;
-        const keystoreFileData = {
-            format: KEYSTORE_FORMAT,
-            algorithm: Constants.DEFAULT_ALGORITHM,
-            iv: this._cryptoProvider.toBase64(iv),
-            authTag: this._cryptoProvider.toBase64(authTag),
-            encryptedData: this._cryptoProvider.toBase64(encryptedData),
-            keyDerivation: {
-                kdf: 'pbkdf2',
-                salt: this._cryptoProvider.toBase64(this._salt),
-                iterations: this._iterations
-            }
-        };
-        this._keystoreFile = keystoreFileData;
-        this._dirty = false;
-        this._isNew = false;
-        return succeed(keystoreFileData);
+        return this._encryptVault(derivedKey);
     }
     /**
      * Changes the master password.
@@ -741,8 +721,60 @@ export class KeyStore {
         });
     }
     // ============================================================================
-    // Private: Vault Decryption
+    // Private: Vault Encryption / Decryption
     // ============================================================================
+    /**
+     * Encrypts the vault with a derived key and returns the key store file.
+     * Shared by `save()` and `saveWithKey()`.
+     */
+    async _encryptVault(derivedKey) {
+        // _secrets and _salt are guaranteed non-undefined by callers
+        const secrets = this._secrets;
+        const salt = this._salt;
+        // Build vault contents
+        const secretEntries = {};
+        for (const [name, entry] of secrets) {
+            secretEntries[name] = {
+                name: entry.name,
+                type: entry.type,
+                key: this._cryptoProvider.toBase64(entry.key),
+                description: entry.description,
+                createdAt: entry.createdAt
+            };
+        }
+        const vaultContents = {
+            version: KEYSTORE_FORMAT,
+            secrets: secretEntries
+        };
+        // Serialize and encrypt
+        const jsonResult = captureResult(() => JSON.stringify(vaultContents));
+        /* c8 ignore next 3 - error path tested but coverage intermittently missed */
+        if (jsonResult.isFailure()) {
+            return fail(`Failed to serialize vault: ${jsonResult.message}`);
+        }
+        const encryptResult = await this._cryptoProvider.encrypt(jsonResult.value, derivedKey);
+        /* c8 ignore next 3 - crypto provider errors tested but coverage intermittently missed */
+        if (encryptResult.isFailure()) {
+            return fail(`Encryption failed: ${encryptResult.message}`);
+        }
+        const { iv, authTag, encryptedData } = encryptResult.value;
+        const keystoreFileData = {
+            format: KEYSTORE_FORMAT,
+            algorithm: Constants.DEFAULT_ALGORITHM,
+            iv: this._cryptoProvider.toBase64(iv),
+            authTag: this._cryptoProvider.toBase64(authTag),
+            encryptedData: this._cryptoProvider.toBase64(encryptedData),
+            keyDerivation: {
+                kdf: 'pbkdf2',
+                salt: this._cryptoProvider.toBase64(salt),
+                iterations: this._iterations
+            }
+        };
+        this._keystoreFile = keystoreFileData;
+        this._dirty = false;
+        this._isNew = false;
+        return succeed(keystoreFileData);
+    }
     /**
      * Decrypts the vault with a derived key and loads secrets into memory.
      * Shared by `unlock()` and `unlockWithKey()`.

package/dist/packlets/zip-file-tree/zipFileTreeAccessors.js

@@ -144,8 +144,8 @@ export class ZipFileTreeAccessors {
     }
     /**
      * Default function to infer the content type of a file.
-     * @param filePath - The path of the file.
-     * @param provided - Optional supplied content type.
+     * @param __filePath - The path of the file.
+     * @param __provided - Optional supplied content type.
      * @returns `Success` with the content type of the file if successful, or
      * `Failure` with an error message otherwise.
      * @remarks This default implementation always returns `Success` with `undefined`.