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

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

@@ -0,0 +1,160 @@
+"use strict";
+// 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]); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.callProxiedCompletionStream = callProxiedCompletionStream;
+/**
+ * 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
+ */
+const ts_utils_1 = require("@fgv/ts-utils");
+const sseParser_1 = require("../sseParser");
+const common_1 = require("./common");
+const proxyEventTypes = ['text-delta', 'tool-event', 'done', 'error'];
+const proxyEventEnvelope = ts_utils_1.Validators.object({
+    type: ts_utils_1.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((0, sseParser_1.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 = (0, sseParser_1.parseSseEventJson)(message.data);
+                    if (json === undefined) {
+                        continue;
+                    }
+                    const envelope = (0, common_1.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
+ */
+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 (0, common_1.openSseConnection)(url, {}, body, logger, signal);
+    return conn.onSuccess((response) => (0, ts_utils_1.succeed)(translateProxyStream(response)));
+}
+//# sourceMappingURL=proxy.js.map

package/lib/packlets/ai-assist/streamingClient.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 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 { Result } from '@fgv/ts-utils';
+import { type IAiStreamEvent } from './model';
+import { type IProviderCompletionStreamParams } from './streamingAdapters/common';
+export { callProxiedCompletionStream } from './streamingAdapters/proxy';
+export type { IProviderCompletionStreamParams } from './streamingAdapters/common';
+/**
+ * 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 declare function callProviderCompletionStream(params: IProviderCompletionStreamParams): Promise<Result<AsyncIterable<IAiStreamEvent>>>;
+//# sourceMappingURL=streamingClient.d.ts.map

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

@@ -0,0 +1,93 @@
+"use strict";
+// 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.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.callProxiedCompletionStream = void 0;
+exports.callProviderCompletionStream = callProviderCompletionStream;
+/**
+ * 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
+ */
+const ts_utils_1 = require("@fgv/ts-utils");
+const model_1 = require("./model");
+const anthropic_1 = require("./streamingAdapters/anthropic");
+const gemini_1 = require("./streamingAdapters/gemini");
+const openaiChat_1 = require("./streamingAdapters/openaiChat");
+const openaiResponses_1 = require("./streamingAdapters/openaiResponses");
+var proxy_1 = require("./streamingAdapters/proxy");
+Object.defineProperty(exports, "callProxiedCompletionStream", { enumerable: true, get: function () { return proxy_1.callProxiedCompletionStream; } });
+/**
+ * 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
+ */
+async function callProviderCompletionStream(params) {
+    const { descriptor, apiKey, prompt, messagesBefore, temperature = 0.7, modelOverride, logger, tools, signal } = params;
+    if (!descriptor.baseUrl) {
+        return (0, ts_utils_1.fail)(`provider "${descriptor.id}" has no API endpoint configured`);
+    }
+    if (descriptor.streamingCorsRestricted) {
+        return (0, ts_utils_1.fail)(`provider "${descriptor.id}" requires a proxy for streaming; none is configured`);
+    }
+    if (prompt.attachments.length > 0 && !descriptor.acceptsImageInput) {
+        return (0, ts_utils_1.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: (0, model_1.resolveModel)(modelOverride !== null && modelOverride !== void 0 ? modelOverride : descriptor.defaultModel, modelContext)
+    };
+    switch (descriptor.apiFormat) {
+        case 'openai':
+            if (hasTools) {
+                return (0, openaiResponses_1.callOpenAiResponsesStream)(config, prompt, tools, messagesBefore, temperature, logger, signal);
+            }
+            return (0, openaiChat_1.callOpenAiChatStream)(config, prompt, messagesBefore, temperature, logger, signal);
+        case 'anthropic':
+            return (0, anthropic_1.callAnthropicStream)(config, prompt, messagesBefore, temperature, tools, logger, signal);
+        case 'gemini':
+            return (0, gemini_1.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 (0, ts_utils_1.fail)(`unsupported API format: ${String(_exhaustive)}`);
+        }
+    }
+}
+//# sourceMappingURL=streamingClient.js.map

package/lib/packlets/conversion/converters.d.ts

@@ -30,7 +30,7 @@ export declare const isoDateTime: Converter<DateTime, unknown>;
  * 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 declare function extendedArrayOf<T, TC = undefined>(label: string, converter: Converter<T, TC>, onError?: Conversion.OnError): Converter<ExtendedArray<T>, TC>;

package/lib/packlets/conversion/converters.js

@@ -111,7 +111,7 @@ exports.isoDateTime = new ts_utils_1.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
  */
 function extendedArrayOf(label, converter, onError = 'failOnError') {

package/lib/packlets/crypto-utils/index.browser.d.ts

@@ -10,5 +10,6 @@ export { KeyStore };
 import * as Converters from './converters';
 export { Converters };
 export { DirectEncryptionProvider, IDirectEncryptionProviderParams } from './directEncryptionProvider';
+export { IKeyPairAlgorithmParams, keyPairAlgorithmParams } from './keyPairAlgorithmParams';
 export { createEncryptedFile, decryptFile, fromBase64, ICreateEncryptedFileParams, toBase64, tryDecryptFile } from './encryptedFile';
 //# sourceMappingURL=index.browser.d.ts.map

package/lib/packlets/crypto-utils/index.browser.js

@@ -55,7 +55,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.tryDecryptFile = exports.toBase64 = exports.fromBase64 = exports.decryptFile = exports.createEncryptedFile = exports.DirectEncryptionProvider = exports.Converters = exports.KeyStore = exports.GCM_IV_SIZE = exports.GCM_AUTH_TAG_SIZE = exports.ENCRYPTED_FILE_FORMAT = exports.DEFAULT_ALGORITHM = exports.AES_256_KEY_SIZE = void 0;
+exports.tryDecryptFile = exports.toBase64 = exports.fromBase64 = exports.decryptFile = exports.createEncryptedFile = exports.keyPairAlgorithmParams = exports.DirectEncryptionProvider = exports.Converters = exports.KeyStore = exports.GCM_IV_SIZE = exports.GCM_AUTH_TAG_SIZE = exports.ENCRYPTED_FILE_FORMAT = exports.DEFAULT_ALGORITHM = exports.AES_256_KEY_SIZE = void 0;
 /**
  * Crypto utilities for encrypted file handling and key management (browser version).
  * Note: For browser crypto provider, use \@fgv/ts-web-extras.
@@ -79,6 +79,9 @@ exports.Converters = Converters;
 // Direct encryption provider
 var directEncryptionProvider_1 = require("./directEncryptionProvider");
 Object.defineProperty(exports, "DirectEncryptionProvider", { enumerable: true, get: function () { return directEncryptionProvider_1.DirectEncryptionProvider; } });
+// WebCrypto parameter table for asymmetric keypair algorithms
+var keyPairAlgorithmParams_1 = require("./keyPairAlgorithmParams");
+Object.defineProperty(exports, "keyPairAlgorithmParams", { enumerable: true, get: function () { return keyPairAlgorithmParams_1.keyPairAlgorithmParams; } });
 // Note: NodeCryptoProvider is NOT exported in browser version
 // Use BrowserCryptoProvider from @fgv/ts-web-extras instead
 // Encrypted file helpers

package/lib/packlets/crypto-utils/index.d.ts

@@ -10,6 +10,7 @@ export { KeyStore };
 import * as Converters from './converters';
 export { Converters };
 export { DirectEncryptionProvider, IDirectEncryptionProviderParams } from './directEncryptionProvider';
+export { IKeyPairAlgorithmParams, keyPairAlgorithmParams } from './keyPairAlgorithmParams';
 export { NodeCryptoProvider, nodeCryptoProvider } from './nodeCryptoProvider';
 export { createEncryptedFile, decryptFile, fromBase64, ICreateEncryptedFileParams, toBase64, tryDecryptFile } from './encryptedFile';
 //# sourceMappingURL=index.d.ts.map

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

@@ -55,7 +55,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.tryDecryptFile = exports.toBase64 = exports.fromBase64 = exports.decryptFile = exports.createEncryptedFile = exports.nodeCryptoProvider = exports.NodeCryptoProvider = exports.DirectEncryptionProvider = exports.Converters = exports.KeyStore = exports.Constants = void 0;
+exports.tryDecryptFile = exports.toBase64 = exports.fromBase64 = exports.decryptFile = exports.createEncryptedFile = exports.nodeCryptoProvider = exports.NodeCryptoProvider = exports.keyPairAlgorithmParams = exports.DirectEncryptionProvider = exports.Converters = exports.KeyStore = exports.Constants = void 0;
 /**
  * Crypto utilities for encrypted file handling and key management.
  * @packageDocumentation
@@ -74,6 +74,9 @@ exports.Converters = Converters;
 // Direct encryption provider
 var directEncryptionProvider_1 = require("./directEncryptionProvider");
 Object.defineProperty(exports, "DirectEncryptionProvider", { enumerable: true, get: function () { return directEncryptionProvider_1.DirectEncryptionProvider; } });
+// WebCrypto parameter table for asymmetric keypair algorithms
+var keyPairAlgorithmParams_1 = require("./keyPairAlgorithmParams");
+Object.defineProperty(exports, "keyPairAlgorithmParams", { enumerable: true, get: function () { return keyPairAlgorithmParams_1.keyPairAlgorithmParams; } });
 // Node.js crypto provider (Node.js environment only)
 var nodeCryptoProvider_1 = require("./nodeCryptoProvider");
 Object.defineProperty(exports, "NodeCryptoProvider", { enumerable: true, get: function () { return nodeCryptoProvider_1.NodeCryptoProvider; } });

package/lib/packlets/crypto-utils/keyPairAlgorithmParams.d.ts

@@ -0,0 +1,39 @@
+import { KeyPairAlgorithm } from './model';
+/**
+ * WebCrypto parameters for a single {@link CryptoUtils.KeyPairAlgorithm}.
+ * Implementations of {@link CryptoUtils.ICryptoProvider} use this table to
+ * translate the small public algorithm enum into the WebCrypto algorithm
+ * objects and key-usage arrays expected by `crypto.subtle`.
+ * @public
+ */
+export interface IKeyPairAlgorithmParams {
+    /**
+     * Algorithm parameters for `crypto.subtle.generateKey`. Always an asymmetric
+     * variant — these algorithms produce a `CryptoKeyPair`, not a single key.
+     */
+    readonly generateKey: RsaHashedKeyGenParams | EcKeyGenParams;
+    /**
+     * Algorithm parameters for `crypto.subtle.importKey('jwk', ...)` when
+     * importing the public half of a keypair.
+     */
+    readonly importPublicKey: RsaHashedImportParams | EcKeyImportParams;
+    /**
+     * Default key usages for the generated `CryptoKeyPair`. Both halves receive
+     * the usages WebCrypto considers valid for their role; the platform filters.
+     */
+    readonly keyPairUsages: ReadonlyArray<KeyUsage>;
+    /**
+     * Key usages applied when re-importing only the public key.
+     */
+    readonly publicKeyUsages: ReadonlyArray<KeyUsage>;
+}
+/**
+ * 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 declare const keyPairAlgorithmParams: Readonly<Record<KeyPairAlgorithm, IKeyPairAlgorithmParams>>;
+//# sourceMappingURL=keyPairAlgorithmParams.d.ts.map

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

@@ -0,0 +1,50 @@
+"use strict";
+// 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.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.keyPairAlgorithmParams = void 0;
+/**
+ * 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
+ */
+exports.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/lib/packlets/crypto-utils/keystore/converters.d.ts

@@ -1,21 +1,83 @@
-import { Converter } from '@fgv/ts-utils';
-import { IKeyStoreFile, IKeyStoreSecretEntryJson, IKeyStoreVaultContents, KeyStoreFormat, KeyStoreSecretType } from './model';
+import { Converter, Validator } from '@fgv/ts-utils';
+import { IKeyStoreAsymmetricEntryJson, IKeyStoreEntryJson, IKeyStoreFile, IKeyStoreSymmetricEntryJson, IKeyStoreVaultContents, KeyPairAlgorithm, KeyStoreAsymmetricSecretType, KeyStoreFormat, KeyStoreSecretType, KeyStoreSymmetricSecretType } from './model';
 /**
  * Converter for {@link CryptoUtils.KeyStore.KeyStoreFormat | key store format} version.
  * @public
  */
 export declare const keystoreFormat: Converter<KeyStoreFormat>;
 /**
- * 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 declare const keystoreSecretType: Converter<KeyStoreSecretType>;
 /**
- * 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'`.
+ * Converter for {@link CryptoUtils.KeyStore.KeyStoreSymmetricSecretType | symmetric secret type} discriminator.
+ * Accepts only `'encryption-key'` and `'api-key'`.
  * @public
  */
-export declare const keystoreSecretEntryJson: Converter<IKeyStoreSecretEntryJson>;
+export declare const keystoreSymmetricSecretType: Converter<KeyStoreSymmetricSecretType>;
+/**
+ * Converter for {@link CryptoUtils.KeyStore.KeyStoreAsymmetricSecretType | asymmetric secret type} discriminator.
+ * Accepts only `'asymmetric-keypair'`.
+ * @public
+ */
+export declare const keystoreAsymmetricSecretType: Converter<KeyStoreAsymmetricSecretType>;
+/**
+ * Converter for {@link CryptoUtils.KeyStore.KeyPairAlgorithm | key pair algorithm}.
+ * @public
+ */
+export declare const keyPairAlgorithm: Converter<KeyPairAlgorithm>;
+/**
+ * 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 declare const jsonWebKeyShape: Validator<JsonWebKey>;
+/**
+ * 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 declare const keystoreSymmetricEntryJson: Converter<IKeyStoreSymmetricEntryJson>;
+/**
+ * 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 declare const keystoreAsymmetricEntryJson: Converter<IKeyStoreAsymmetricEntryJson>;
+/**
+ * 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 declare const keystoreSecretEntryJson: Converter<IKeyStoreEntryJson>;
 /**
  * Converter for {@link CryptoUtils.KeyStore.IKeyStoreVaultContents | key store vault contents} (decrypted state).
  * @public