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

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/index.browser.js

@@ -34,6 +34,8 @@ import * as Converters from './converters';
 export { Converters };
 // Direct encryption provider
 export { DirectEncryptionProvider } from './directEncryptionProvider';
+// WebCrypto parameter table for asymmetric keypair algorithms
+export { keyPairAlgorithmParams } from './keyPairAlgorithmParams';
 // Note: NodeCryptoProvider is NOT exported in browser version
 // Use BrowserCryptoProvider from @fgv/ts-web-extras instead
 // Encrypted file helpers

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

@@ -34,6 +34,8 @@ import * as Converters from './converters';
 export { Converters };
 // Direct encryption provider
 export { DirectEncryptionProvider } from './directEncryptionProvider';
+// WebCrypto parameter table for asymmetric keypair algorithms
+export { keyPairAlgorithmParams } from './keyPairAlgorithmParams';
 // Node.js crypto provider (Node.js environment only)
 export { NodeCryptoProvider, nodeCryptoProvider } from './nodeCryptoProvider';
 // Encrypted file helpers

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

@@ -0,0 +1,47 @@
+// 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.
+/**
+ * Lookup table from {@link CryptoUtils.KeyPairAlgorithm} to the WebCrypto
+ * parameters needed to drive `crypto.subtle`. Shared between every
+ * {@link CryptoUtils.ICryptoProvider} implementation since both Node and
+ * browser providers speak the same WebCrypto API. Exposed for downstream
+ * provider implementations (e.g. browser-side providers in `@fgv/ts-web-extras`).
+ * @public
+ */
+export const keyPairAlgorithmParams = {
+    'ecdsa-p256': {
+        generateKey: { name: 'ECDSA', namedCurve: 'P-256' },
+        importPublicKey: { name: 'ECDSA', namedCurve: 'P-256' },
+        keyPairUsages: ['sign', 'verify'],
+        publicKeyUsages: ['verify']
+    },
+    'rsa-oaep-2048': {
+        generateKey: {
+            name: 'RSA-OAEP',
+            modulusLength: 2048,
+            publicExponent: new Uint8Array([0x01, 0x00, 0x01]),
+            hash: 'SHA-256'
+        },
+        importPublicKey: { name: 'RSA-OAEP', hash: 'SHA-256' },
+        keyPairUsages: ['encrypt', 'decrypt'],
+        publicKeyUsages: ['encrypt']
+    }
+};
+//# sourceMappingURL=keyPairAlgorithmParams.js.map

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

@@ -17,9 +17,9 @@
 // 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.
-import { Converters } from '@fgv/ts-utils';
+import { Converters, succeed, Validators } from '@fgv/ts-utils';
 import { base64String, encryptionAlgorithm, keyDerivationParams } from '../converters';
-import { allKeyStoreSecretTypes, KEYSTORE_FORMAT } from './model';
+import { allKeyPairAlgorithms, allKeyStoreSecretTypes, allKeyStoreSymmetricSecretTypes, KEYSTORE_FORMAT, allKeyStoreAsymmetricSecretTypes } from './model';
 // ============================================================================
 // Key Store Format Converter
 // ============================================================================
@@ -31,31 +31,123 @@ export const keystoreFormat = Converters.enumeratedValue([
     KEYSTORE_FORMAT
 ]);
 // ============================================================================
-// Secret Type Converter
+// Secret Type Converters
 // ============================================================================
 /**
- * Converter for {@link CryptoUtils.KeyStore.KeyStoreSecretType | key store secret type} discriminator.
+ * Converter for {@link CryptoUtils.KeyStore.KeyStoreSecretType | any key store secret type} discriminator.
+ * Accepts both symmetric and asymmetric type values.
  * @public
  */
 export const keystoreSecretType = Converters.enumeratedValue(allKeyStoreSecretTypes);
+/**
+ * Converter for {@link CryptoUtils.KeyStore.KeyStoreSymmetricSecretType | symmetric secret type} discriminator.
+ * Accepts only `'encryption-key'` and `'api-key'`.
+ * @public
+ */
+export const keystoreSymmetricSecretType = Converters.enumeratedValue(allKeyStoreSymmetricSecretTypes);
+/**
+ * Converter for {@link CryptoUtils.KeyStore.KeyStoreAsymmetricSecretType | asymmetric secret type} discriminator.
+ * Accepts only `'asymmetric-keypair'`.
+ * @public
+ */
+export const keystoreAsymmetricSecretType = Converters.enumeratedValue(allKeyStoreAsymmetricSecretTypes);
+// ============================================================================
+// Key Pair Algorithm Converter
+// ============================================================================
+/**
+ * Converter for {@link CryptoUtils.KeyStore.KeyPairAlgorithm | key pair algorithm}.
+ * @public
+ */
+export const keyPairAlgorithm = Converters.enumeratedValue(allKeyPairAlgorithms);
 // ============================================================================
-// Secret Entry Converters
+// JWK Shape Validator
 // ============================================================================
 /**
- * Converter for {@link CryptoUtils.KeyStore.IKeyStoreSecretEntryJson | key store secret entry} in JSON format.
- * The `type` field is optional for backwards compatibility — missing means `'encryption-key'`.
+ * In-place shape check for a JSON Web Key. Asserts only that the input is a
+ * non-array object whose `kty` discriminator is a string; every other JWK
+ * field passes through untouched. This is intentionally **not** a true JWK
+ * validator — per-algorithm correctness (RSA `n`/`e`, EC `crv`/`x`/`y`,
+ * key-size constraints, etc.) is delegated to `crypto.subtle.importKey` at
+ * first use, which is the authoritative checker. The "shape" suffix in the
+ * name is the warning sign for readers expecting full validation.
+ * @remarks
+ * Built with `Validators.object` (in-place, non-strict) so unknown JWK fields
+ * survive the round-trip; the cast to `FieldValidators<JsonWebKey>` is required
+ * only because TypeScript's mapped type demands an entry for every key in
+ * `JsonWebKey`. At runtime the `ObjectValidator` only inspects keys present in
+ * the field-validators map.
  * @public
  */
-export const keystoreSecretEntryJson = Converters.object({
+export const jsonWebKeyShape = Validators.object({
+    kty: Validators.string
+});
+// ============================================================================
+// Symmetric Secret Entry Converter
+// ============================================================================
+/**
+ * Converter for {@link CryptoUtils.KeyStore.IKeyStoreSymmetricEntryJson | symmetric secret entry} in JSON form.
+ *
+ * @remarks
+ * Backwards compatibility with vaults written before asymmetric-keypair
+ * support: those entries may lack the `type` discriminator on the wire. To
+ * keep the model type honest (`type` is required on
+ * {@link CryptoUtils.KeyStore.IKeyStoreSymmetricEntryJson}, see its docs),
+ * we declare `type` in `optionalFields` so the inner `Converters.object` will
+ * accept input without it, then `.map()` injects the default
+ * `'encryption-key'` when missing. The output therefore always carries the
+ * discriminator and downstream code never sees the legacy missing-type form.
+ *
+ * @public
+ */
+export const keystoreSymmetricEntryJson = Converters.object({
     name: Converters.string,
-    type: keystoreSecretType,
+    type: keystoreSymmetricSecretType,
     key: base64String,
     description: Converters.string,
     createdAt: Converters.string
 }, {
+    // `type` is optional at the input layer for legacy-vault compatibility;
+    // the .map() below normalizes by injecting the default.
     optionalFields: ['type', 'description']
+}).map((entry) => {
+    var _a;
+    return succeed(Object.assign(Object.assign({}, entry), { type: (_a = entry.type) !== null && _a !== void 0 ? _a : 'encryption-key' }));
 });
 // ============================================================================
+// Asymmetric Keypair Entry Converter
+// ============================================================================
+/**
+ * Converter for {@link CryptoUtils.KeyStore.IKeyStoreAsymmetricEntryJson | asymmetric keypair entry} in JSON form.
+ * The `publicKeyJwk` field passes through {@link CryptoUtils.KeyStore.Converters.jsonWebKeyShape | jsonWebKeyShape}
+ * (shape check only — see its docs); cryptographic correctness is enforced by
+ * `crypto.subtle.importKey` at use.
+ * @public
+ */
+export const keystoreAsymmetricEntryJson = Converters.object({
+    name: Converters.string,
+    type: keystoreAsymmetricSecretType,
+    id: Converters.string,
+    algorithm: keyPairAlgorithm,
+    publicKeyJwk: jsonWebKeyShape,
+    description: Converters.string.optional(),
+    createdAt: Converters.string
+});
+// ============================================================================
+// Discriminated-Union Entry Converter
+// ============================================================================
+/**
+ * Discriminated-union converter for any {@link CryptoUtils.KeyStore.IKeyStoreEntryJson | key store entry} in JSON form.
+ * Routes by the `type` field: `'asymmetric-keypair'` is parsed by
+ * {@link CryptoUtils.KeyStore.Converters.keystoreAsymmetricEntryJson | keystoreAsymmetricEntryJson},
+ * anything else (including a missing `type` field for backwards compatibility) by
+ * {@link CryptoUtils.KeyStore.Converters.keystoreSymmetricEntryJson | keystoreSymmetricEntryJson}.
+ * @public
+ */
+export const keystoreSecretEntryJson = Converters.oneOf([
+    keystoreAsymmetricEntryJson,
+    keystoreSymmetricEntryJson
+]);
+// ============================================================================
 // Vault Contents Converter
 // ============================================================================
 /**

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

@@ -23,6 +23,7 @@
  */
 // Types and interfaces
 export * from './model';
+export * from './privateKeyStorage';
 // Converters namespace
 import * as Converters from './converters';
 export { Converters };