@fgv/ts-extras 5.0.2 → 5.1.0-0

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

@@ -0,0 +1,90 @@
+// 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.
+// ============================================================================
+// AiPrompt
+// ============================================================================
+/**
+ * A structured AI prompt with system/user split for direct API calls,
+ * and a lazily-constructed combined version for copy/paste workflows.
+ * @public
+ */
+export class AiPrompt {
+    constructor(user, system) {
+        this.system = system;
+        this.user = user;
+    }
+    /** Combined single-string version (user + system joined) for copy/paste. */
+    get combined() {
+        return `${this.user}\n\n${this.system}`;
+    }
+}
+/**
+ * All valid {@link ModelSpecKey} values.
+ * @public
+ */
+export const allModelSpecKeys = ['base', 'tools', 'image'];
+/**
+ * Default context key used as fallback when resolving a {@link ModelSpec}.
+ * @public
+ */
+export const MODEL_SPEC_BASE_KEY = 'base';
+/**
+ * Resolves a {@link ModelSpec} to a concrete model string given an optional context key.
+ *
+ * @remarks
+ * Resolution rules:
+ * 1. If the spec is a string, return it directly (context is irrelevant).
+ * 2. If the spec is an object and the context key exists, recurse into that branch.
+ * 3. Otherwise, fall back to the {@link MODEL_SPEC_BASE_KEY | 'base'} key.
+ * 4. If neither context nor `'base'` exists, use the first available value.
+ *
+ * @param spec - The model specification to resolve
+ * @param context - Optional context key (e.g. `'tools'`)
+ * @returns The resolved model string
+ * @public
+ */
+export function resolveModel(spec, context) {
+    if (typeof spec === 'string') {
+        return spec;
+    }
+    // Try the requested context key first
+    if (context !== undefined && context in spec) {
+        return resolveModel(spec[context]);
+    }
+    // Fall back to 'base'
+    if (MODEL_SPEC_BASE_KEY in spec) {
+        return resolveModel(spec[MODEL_SPEC_BASE_KEY]);
+    }
+    // Last resort: first value in the record
+    const first = Object.values(spec)[0];
+    /* c8 ignore next 3 - defensive: only reachable with empty object (prevented by converter) */
+    if (first === undefined) {
+        return '';
+    }
+    return resolveModel(first);
+}
+/**
+ * Default AI assist settings (copy-paste only).
+ * @public
+ */
+export const DEFAULT_AI_ASSIST = {
+    providers: [{ provider: 'copy-paste' }]
+};
+//# sourceMappingURL=model.js.map

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

@@ -0,0 +1,145 @@
+// 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.
+/**
+ * Centralized provider registry — single source of truth for all AI provider metadata.
+ * @packageDocumentation
+ */
+import { fail, succeed } from '@fgv/ts-utils';
+// ============================================================================
+// Built-in providers
+// ============================================================================
+/**
+ * All known AI provider descriptors. Copy-paste first, then alphabetical.
+ * @internal
+ */
+const BUILTIN_PROVIDERS = [
+    {
+        id: 'copy-paste',
+        label: 'Copy / Paste',
+        buttonLabel: 'AI Assist | Copy',
+        needsSecret: false,
+        apiFormat: 'openai',
+        baseUrl: '',
+        defaultModel: '',
+        supportedTools: [],
+        corsRestricted: false
+    },
+    {
+        id: 'anthropic',
+        label: 'Anthropic Claude',
+        buttonLabel: 'AI Assist | Claude',
+        needsSecret: true,
+        apiFormat: 'anthropic',
+        baseUrl: 'https://api.anthropic.com/v1',
+        defaultModel: 'claude-sonnet-4-5-20250929',
+        supportedTools: ['web_search'],
+        corsRestricted: false
+    },
+    {
+        id: 'google-gemini',
+        label: 'Google Gemini',
+        buttonLabel: 'AI Assist | Gemini',
+        needsSecret: true,
+        apiFormat: 'gemini',
+        baseUrl: 'https://generativelanguage.googleapis.com/v1beta',
+        defaultModel: 'gemini-2.5-flash',
+        supportedTools: ['web_search'],
+        corsRestricted: false
+    },
+    {
+        id: 'groq',
+        label: 'Groq',
+        buttonLabel: 'AI Assist | Groq',
+        needsSecret: true,
+        apiFormat: 'openai',
+        baseUrl: 'https://api.groq.com/openai/v1',
+        defaultModel: 'llama-3.3-70b-versatile',
+        supportedTools: [],
+        corsRestricted: false
+    },
+    {
+        id: 'mistral',
+        label: 'Mistral',
+        buttonLabel: 'AI Assist | Mistral',
+        needsSecret: true,
+        apiFormat: 'openai',
+        baseUrl: 'https://api.mistral.ai/v1',
+        defaultModel: 'mistral-large-latest',
+        supportedTools: [],
+        corsRestricted: false
+    },
+    {
+        id: 'openai',
+        label: 'OpenAI',
+        buttonLabel: 'AI Assist | OpenAI',
+        needsSecret: true,
+        apiFormat: 'openai',
+        baseUrl: 'https://api.openai.com/v1',
+        defaultModel: 'gpt-4o',
+        supportedTools: ['web_search'],
+        corsRestricted: false
+    },
+    {
+        id: 'xai-grok',
+        label: 'xAI Grok',
+        buttonLabel: 'AI Assist | Grok',
+        needsSecret: true,
+        apiFormat: 'openai',
+        baseUrl: 'https://api.x.ai/v1',
+        defaultModel: { base: 'grok-4-1-fast', tools: 'grok-4-1-fast-reasoning' },
+        supportedTools: ['web_search'],
+        corsRestricted: true
+    }
+];
+/**
+ * Index for O(1) lookup by id.
+ * @internal
+ */
+const PROVIDER_BY_ID = new Map(BUILTIN_PROVIDERS.map((d) => [d.id, d]));
+// ============================================================================
+// Public API
+// ============================================================================
+/**
+ * All valid provider ID values, in the same order as the registry.
+ * @public
+ */
+export const allProviderIds = BUILTIN_PROVIDERS.map((d) => d.id);
+/**
+ * Get all known provider descriptors. Copy-paste first, then alphabetical.
+ * @returns All built-in provider descriptors
+ * @public
+ */
+export function getProviderDescriptors() {
+    return BUILTIN_PROVIDERS;
+}
+/**
+ * Get a provider descriptor by id.
+ * @param id - The provider identifier
+ * @returns The descriptor, or a failure if the provider is unknown
+ * @public
+ */
+export function getProviderDescriptor(id) {
+    const descriptor = PROVIDER_BY_ID.get(id);
+    if (!descriptor) {
+        return fail(`unknown AI provider: ${id}`);
+    }
+    return succeed(descriptor);
+}
+//# sourceMappingURL=registry.js.map

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

@@ -0,0 +1,160 @@
+// 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.
+// ============================================================================
+// Tool resolution
+// ============================================================================
+/**
+ * Resolves the effective tools for a completion call.
+ *
+ * - If per-call tools are provided, they override settings-level tools entirely.
+ * - Otherwise, settings-level enabled tools are used.
+ * - Only tools supported by the provider are included.
+ * - Returns an empty array if no tools are enabled (= no tools sent).
+ *
+ * @param descriptor - The provider descriptor (used to filter by supported tools)
+ * @param settingsTools - Tool enablement from provider settings (optional)
+ * @param perCallTools - Per-call tool override (optional)
+ * @returns The resolved list of tool configs to include in the request
+ * @public
+ */
+export function resolveEffectiveTools(descriptor, settingsTools, perCallTools) {
+    const supported = new Set(descriptor.supportedTools);
+    if (perCallTools !== undefined) {
+        return perCallTools.filter((t) => supported.has(t.type));
+    }
+    if (settingsTools === undefined) {
+        return [];
+    }
+    return settingsTools
+        .filter((e) => e.enabled && supported.has(e.type))
+        .map((e) => { var _a; return (_a = e.config) !== null && _a !== void 0 ? _a : { type: e.type }; });
+}
+// ============================================================================
+// OpenAI / xAI Responses API format
+// ============================================================================
+/**
+ * Formats a web search tool config for the xAI/OpenAI Responses API.
+ * @internal
+ */
+function webSearchToResponsesApi(config) {
+    const tool = { type: 'web_search' };
+    if (config.allowedDomains || config.blockedDomains) {
+        const filters = {};
+        if (config.allowedDomains) {
+            filters.allowed_domains = [...config.allowedDomains];
+        }
+        if (config.blockedDomains) {
+            filters.excluded_domains = [...config.blockedDomains];
+        }
+        tool.filters = filters;
+    }
+    if (config.enableImageUnderstanding) {
+        tool.enable_image_understanding = true;
+    }
+    return tool;
+}
+/**
+ * Formats tool configs for the xAI/OpenAI Responses API.
+ * @param tools - The resolved tool configs
+ * @returns Provider-native tool objects for the `tools` request field
+ * @public
+ */
+export function toResponsesApiTools(tools) {
+    return tools.map((t) => {
+        switch (t.type) {
+            case 'web_search':
+                return webSearchToResponsesApi(t);
+            /* c8 ignore next 4 - defensive coding: exhaustive switch guaranteed by TypeScript */
+            default: {
+                const _exhaustive = t.type;
+                return { type: String(_exhaustive) };
+            }
+        }
+    });
+}
+// ============================================================================
+// Anthropic Messages API format
+// ============================================================================
+/**
+ * Formats a web search tool config for the Anthropic Messages API.
+ * @internal
+ */
+function webSearchToAnthropic(config) {
+    const tool = {
+        type: 'web_search_20250305',
+        name: 'web_search'
+    };
+    if (config.maxUses !== undefined) {
+        tool.max_uses = config.maxUses;
+    }
+    if (config.allowedDomains) {
+        tool.allowed_domains = [...config.allowedDomains];
+    }
+    if (config.blockedDomains) {
+        tool.blocked_domains = [...config.blockedDomains];
+    }
+    return tool;
+}
+/**
+ * Formats tool configs for the Anthropic Messages API.
+ * @param tools - The resolved tool configs
+ * @returns Provider-native tool objects for the `tools` request field
+ * @public
+ */
+export function toAnthropicTools(tools) {
+    return tools.map((t) => {
+        switch (t.type) {
+            case 'web_search':
+                return webSearchToAnthropic(t);
+            /* c8 ignore next 4 - defensive coding: exhaustive switch guaranteed by TypeScript */
+            default: {
+                const _exhaustive = t.type;
+                return { type: String(_exhaustive) };
+            }
+        }
+    });
+}
+// ============================================================================
+// Gemini generateContent API format
+// ============================================================================
+/**
+ * Formats tool configs for the Gemini generateContent API.
+ * Gemini uses `google_search` for search grounding — no per-tool config options.
+ * @param tools - The resolved tool configs
+ * @returns Provider-native tool objects for the `tools` request field
+ * @public
+ */
+export function toGeminiTools(tools) {
+    const result = [];
+    for (const t of tools) {
+        switch (t.type) {
+            case 'web_search':
+                result.push({ google_search: {} });
+                break;
+            /* c8 ignore next 4 - defensive coding: exhaustive switch guaranteed by TypeScript */
+            default: {
+                const _exhaustive = t.type;
+                result.push({ type: String(_exhaustive) });
+            }
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=toolFormats.js.map

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

@@ -0,0 +1,48 @@
+// Copyright (c) 2024 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.
+// ============================================================================
+// Constants
+// ============================================================================
+/**
+ * Current format version for encrypted files.
+ * @public
+ */
+export const ENCRYPTED_FILE_FORMAT = 'encrypted-collection-v1';
+/**
+ * Default encryption algorithm.
+ * @public
+ */
+export const DEFAULT_ALGORITHM = 'AES-256-GCM';
+/**
+ * Key size in bytes for AES-256.
+ * @public
+ */
+export const AES_256_KEY_SIZE = 32;
+/**
+ * IV size in bytes for GCM mode.
+ * @public
+ */
+export const GCM_IV_SIZE = 12;
+/**
+ * Auth tag size in bytes for GCM mode.
+ * @public
+ */
+export const GCM_AUTH_TAG_SIZE = 16;
+//# sourceMappingURL=constants.js.map

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

@@ -0,0 +1,155 @@
+// Copyright (c) 2024 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.
+import { Converters as JsonConverters } from '@fgv/ts-json-base';
+import { Converters, fail, succeed } from '@fgv/ts-utils';
+import * as Constants from './constants';
+// ============================================================================
+// Base Converters
+// ============================================================================
+/**
+ * Converter for {@link CryptoUtils.EncryptionAlgorithm | encryption algorithm} values.
+ * @public
+ */
+export const encryptionAlgorithm = Converters.enumeratedValue([Constants.DEFAULT_ALGORITHM]);
+/**
+ * Converter for {@link CryptoUtils.EncryptedFileFormat | encrypted file format} version.
+ * @public
+ */
+export const encryptedFileFormat = Converters.enumeratedValue([
+    Constants.ENCRYPTED_FILE_FORMAT
+]);
+/**
+ * Converter for {@link CryptoUtils.EncryptedFileErrorMode | encrypted file error mode}.
+ * @public
+ */
+export const encryptedFileErrorMode = Converters.enumeratedValue(['fail', 'skip', 'warn']);
+/**
+ * Converter for {@link CryptoUtils.KeyDerivationFunction | key derivation function} type.
+ * @public
+ */
+export const keyDerivationFunction = Converters.enumeratedValue(['pbkdf2']);
+/**
+ * Converter for {@link CryptoUtils.IKeyDerivationParams | key derivation parameters}.
+ * @public
+ */
+export const keyDerivationParams = Converters.object({
+    kdf: keyDerivationFunction,
+    salt: Converters.string,
+    iterations: Converters.number
+});
+/**
+ * Converter for base64 strings (validates format).
+ * @public
+ */
+export const base64String = Converters.string.withConstraint((value) => {
+    // Basic base64 validation - check for valid characters and padding
+    const base64Regex = /^[A-Za-z0-9+/]*={0,2}$/;
+    if (!base64Regex.test(value)) {
+        return fail('Invalid base64 encoding');
+    }
+    return succeed(value);
+});
+// ============================================================================
+// Uint8Array Converter
+// ============================================================================
+/**
+ * Converter which converts a base64 string to a Uint8Array.
+ * @public
+ */
+export const uint8ArrayFromBase64 = Converters.string.map((base64) => {
+    try {
+        // Use Buffer in Node.js environment, atob in browser
+        if (typeof Buffer !== 'undefined') {
+            return succeed(Uint8Array.from(Buffer.from(base64, 'base64')));
+        }
+        /* c8 ignore start - Browser-only fallback cannot be tested in Node.js environment */
+        const binaryString = atob(base64);
+        const bytes = new Uint8Array(binaryString.length);
+        for (let i = 0; i < binaryString.length; i++) {
+            bytes[i] = binaryString.charCodeAt(i);
+        }
+        return succeed(bytes);
+    }
+    catch (e) {
+        // This catch is for browser's atob() which throws on invalid base64
+        // Node's Buffer.from() doesn't throw, it ignores invalid characters
+        const message = e instanceof Error ? e.message : String(e);
+        return fail(`Invalid base64: ${message}`);
+    }
+    /* c8 ignore stop */
+});
+// ============================================================================
+// Named Secret Converter
+// ============================================================================
+/**
+ * Converter for {@link CryptoUtils.INamedSecret | named secret} from JSON representation.
+ * Expects key as base64 string in JSON, converts to Uint8Array.
+ * @public
+ */
+export const namedSecret = Converters.object({
+    name: Converters.string,
+    key: uint8ArrayFromBase64
+});
+/**
+ * Base converter for encrypted file structure (without typed metadata).
+ */
+const baseEncryptedFileConverter = Converters.object({
+    format: encryptedFileFormat,
+    secretName: Converters.string,
+    algorithm: encryptionAlgorithm,
+    iv: base64String,
+    authTag: base64String,
+    encryptedData: base64String,
+    keyDerivation: keyDerivationParams,
+    metadata: JsonConverters.jsonValue
+}, { optionalFields: ['keyDerivation', 'metadata'] });
+/**
+ * Creates a converter for {@link CryptoUtils.IEncryptedFile | encrypted files} with optional typed metadata.
+ * @typeParam TMetadata - Type of optional unencrypted metadata
+ * @param metadataConverter - Optional converter for validating metadata field
+ * @returns A converter that validates and converts encrypted file structures
+ * @public
+ */
+export function createEncryptedFileConverter(metadataConverter) {
+    return Converters.generic((from) => {
+        // First validate base structure
+        const baseResult = baseEncryptedFileConverter.convert(from);
+        if (baseResult.isFailure()) {
+            return fail(baseResult.message);
+        }
+        const base = baseResult.value;
+        // Validate metadata with specific converter if provided and metadata exists
+        if (metadataConverter !== undefined && base.metadata !== undefined) {
+            const metaResult = metadataConverter.convert(base.metadata);
+            if (metaResult.isFailure()) {
+                return fail(`Invalid metadata: ${metaResult.message}`);
+            }
+            return succeed(Object.assign(Object.assign({}, base), { metadata: metaResult.value }));
+        }
+        // Return as-is (metadata is either undefined or untyped JsonValue)
+        return succeed(base);
+    });
+}
+/**
+ * Default converter for encrypted files without typed metadata.
+ * @public
+ */
+export const encryptedFile = createEncryptedFileConverter();
+//# sourceMappingURL=converters.js.map

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

@@ -0,0 +1,86 @@
+// 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.
+import { fail, succeed } from '@fgv/ts-utils';
+import { createEncryptedFile } from './encryptedFile';
+/**
+ * An {@link IEncryptionProvider} that uses a pre-supplied key and crypto provider.
+ *
+ * This is useful when you have the raw encryption key from an external source
+ * (e.g. a `SecretProvider` callback, password derivation, or a one-shot
+ * operation) and don't want to open a full KeyStore.
+ *
+ * Optionally bound to a specific secret name for safety: if a `boundSecretName`
+ * is provided, calls to `encryptByName` with a different name will fail.
+ *
+ * @example
+ * ```typescript
+ * const provider = DirectEncryptionProvider.create({
+ *   cryptoProvider: nodeCryptoProvider,
+ *   key: myKey,
+ *   boundSecretName: 'my-collection'
+ * }).orThrow();
+ *
+ * const encrypted = await provider.encryptByName('my-collection', jsonContent);
+ * ```
+ *
+ * @public
+ */
+export class DirectEncryptionProvider {
+    constructor(params) {
+        this._cryptoProvider = params.cryptoProvider;
+        this._key = params.key;
+        this._boundSecretName = params.boundSecretName;
+    }
+    /**
+     * Creates a new DirectEncryptionProvider.
+     * @param params - Provider configuration
+     * @returns Success with provider, or Failure if parameters are invalid
+     * @public
+     */
+    static create(params) {
+        if (params.key.length === 0) {
+            return fail('Encryption key cannot be empty');
+        }
+        return succeed(new DirectEncryptionProvider(params));
+    }
+    /**
+     * The secret name this provider is bound to, if any.
+     * @public
+     */
+    get boundSecretName() {
+        return this._boundSecretName;
+    }
+    /**
+     * {@inheritDoc IEncryptionProvider.encryptByName}
+     */
+    async encryptByName(secretName, content, metadata) {
+        if (this._boundSecretName !== undefined && secretName !== this._boundSecretName) {
+            return fail(`Secret name mismatch: requested '${secretName}' but provider is bound to '${this._boundSecretName}'`);
+        }
+        return createEncryptedFile({
+            content,
+            secretName,
+            key: this._key,
+            cryptoProvider: this._cryptoProvider,
+            metadata
+        });
+    }
+}
+//# sourceMappingURL=directEncryptionProvider.js.map