kubricate/dist/dts/secret/SecretManager.d.ts

A TypeScript framework for building reusable, type-safe Kubernetes infrastructure — without the YAML mess.

import type { Pipe, Tuples, Unions } from 'hotscript';
import type { BaseConnector, BaseLogger, BaseProvider, PreparedEffect, SecretValue } from '@kubricate/core';
import type { AnyKey, FallbackIfNever } from '../types.js';
export interface SecretManagerEffect {
    name: string;
    value: SecretValue;
    effects: PreparedEffect[];
}
type ExtractWithDefault<Input extends AnyKey, Default extends AnyKey> = Pipe<Input, [Unions.ToTuple, Tuples.At<1>]> extends undefined ? Input : Default;
/**
 * SecretOptions defines the structure of a secret entry in the SecretManager.
 * It includes the name of the secret, the connector to use for loading it,
 * and the provider to use for resolving it.
 */
export interface SecretOptions<NewSecret extends string = string, Connector extends AnyKey = AnyKey, Provider extends AnyKey = AnyKey> {
    /**
     * Name of the secret to be added.
     * This name must be unique within the SecretManager instance.
     */
    name: NewSecret;
    /**
     * Connector instance to use for loading the secret.
     * If not provided, the default connector will be used.
     */
    connector?: Connector;
    /**
     * Key of a registered provider instance.
     * If not provided, the default provider will be used.
     */
    provider?: Provider;
}
/**
 * SecretManager is a type-safe registry for managing secret providers and their secrets.
 *
 * - Register provider definitions (with type-safe config).
 * - Register named provider instances based on those definitions.
 * - Add secrets referencing the registered providers.
 */
export declare class SecretManager<
/**
 * Connector instances that have been registered.
 */
ConnectorInstances extends Record<string, string> = {}, 
/**
 * Instances of providers that have been registered.
 * Keys are provider names, values are typically unique string identifiers.
 */
ProviderInstances extends Record<string, BaseProvider> = {}, 
/**
 * Secret entries added to the registry.
 * Keys are secret names, values are their associated string identifiers.
 */
SecretEntries extends Record<string, {
    provider: keyof ProviderInstances;
}> = {}, 
/**
 * Default provider to use if no specific provider is specified.
 */
DefaultProvider extends AnyKey = never> {
    /**
     * Internal runtime storage for secret values (not type-safe).
     * Intended for use in actual secret resolution or access.
     */
    private _secrets;
    private _providers;
    private _connectors;
    private _defaultProvider;
    private _defaultConnector;
    logger?: BaseLogger;
    constructor();
    /**
     * Registers a new provider instance using a valid provider name
     *
     * @param provider - The unique name of the provider (e.g., 'Kubernetes.Secret').
     * @param instance - Configuration specific to the provider type.
     * @returns A SecretManager instance with the provider added.
     */
    addProvider<NewProviderKey extends string, NewProvider extends BaseProvider>(provider: NewProviderKey, instance: NewProvider): SecretManager<ConnectorInstances, ProviderInstances & Record<NewProviderKey, NewProvider>, SecretEntries, FallbackIfNever<DefaultProvider, NewProviderKey>>;
    /**
     * Sets the default provider for the SecretManager.
     * This provider will be used if no specific provider is specified when adding a secret.
     *
     * Providers support multiple instances, so this is a way to set a default.
     *
     * @param provider - The unique name of the provider (e.g., 'Kubernetes.Secret').
     * @returns A SecretManager instance with the provider added.
     */
    setDefaultProvider<NewDefaultProvider extends keyof ProviderInstances>(provider: NewDefaultProvider): SecretManager<ConnectorInstances, ProviderInstances, SecretEntries, NewDefaultProvider>;
    /**
     * Adds a new connector instance using a valid connector name
     *
     * @param connector - The unique name of the connector (e.g., 'EnvConnector').
     * @param instance - Configuration specific to the connector type.
     * @returns A SecretManager instance with the connector added.
     */
    addConnector<NewConnector extends string>(connector: NewConnector, instance: BaseConnector): SecretManager<ConnectorInstances & Record<NewConnector, string>, ProviderInstances, SecretEntries, DefaultProvider>;
    /**
     * Sets the default connector for the SecretManager.
     * This connector will be used if no specific connector is specified when adding a secret.
     *
     * Connectors support multiple instances, so this is a way to set a default.
     *
     * @param connector - The unique name of the connector (e.g., 'EnvConnector').
     * @returns A SecretManager instance with the connector added.
     */
    setDefaultConnector(connector: keyof ConnectorInstances): SecretManager<ConnectorInstances, ProviderInstances, SecretEntries, DefaultProvider>;
    /**
     * Adds a new secret to the registry and links it to an existing provider.
     *
     * @param optionsOrName - SecretOptions
     * @returns A new SecretManager instance with the secret added.
     */
    addSecret<NewSecret extends string, NewProvider extends keyof ProviderInstances = keyof ProviderInstances>(optionsOrName: NewSecret | SecretOptions<NewSecret, keyof ConnectorInstances, NewProvider>): SecretManager<ConnectorInstances, ProviderInstances, SecretEntries & Record<NewSecret, {
        provider: ExtractWithDefault<NewProvider, DefaultProvider>;
    }>, DefaultProvider>;
    /**
     * @interal Internal method to get the current secrets in the manager.
     * This is not intended for public use.
     *
     * @returns The current secrets in the registry.
     */
    getSecrets(): Record<string, SecretOptions<string, AnyKey, AnyKey>>;
    /**
     * @internal Internal method to prepare secrets for use.
     * This is not intended for public use.
     *
     * When a secret is added, it may not have a provider or connector set.
     * This method ensures that all secrets have a provider and connector set.
     */
    private prepareSecrets;
    /**
     * @internal Internal method to get the current providers in the manager.
     * This is not intended for public use.
     *
     * @param key - The unique name of the connector (e.g., 'EnvConnector').
     * @returns The connector instance associated with the given key.
     * @throws Error if the connector is not found.
     */
    getConnector<Config extends object = object>(key?: AnyKey): BaseConnector<Config>;
    /**
     * @internal Internal method to get the current providers in the manager.
     * This is not intended for public use.
     *
     * @param key - The unique name of the provider (e.g., 'Kubernetes.Secret').
     * @returns The provider instance associated with the given key.
     * @throws Error if the provider is not found.
     */
    getProvider<Config extends object = object>(key: AnyKey | undefined): BaseProvider<Config>;
    /**
     * @internal Internal method to build the SecretManager.
     * This is not intended for public use.
     *
     * Post processing step to ensure that all secrets is ready for use.
     */
    build(): this;
    resolveProvider(provider?: AnyKey): BaseProvider;
    resolveConnector(connector?: AnyKey): BaseConnector;
    getConnectors(): Record<string, BaseConnector<object>>;
    getProviders(): Record<string, BaseProvider<object, "env" | "volume" | "annotation" | "imagePullSecret" | "envFrom" | "plugin">>;
    getDefaultProvider(): keyof ProviderInstances | undefined;
    getDefaultConnector(): keyof ConnectorInstances | undefined;
    /**
     * @internal Internal method to get the current providers in the manager.
     * This is not intended for public use.
     *
     * Prepares secrets using registered connectors and providers.
     * This does not perform any side-effects like `kubectl`.
     *
     * @returns An array of SecretManagerEffect objects, each containing the name, value, and effects of the secret.
     * @throws Error if a connector or provider is not found for a secret.
     */
    prepare(): Promise<SecretManagerEffect[]>;
    /**
     * Resolves the registered provider instance for a given secret name.
     * This method is used during the secret injection planning phase (e.g., `useSecrets`)
     * and does not resolve or load secret values.
     *
     * @param secretName - The name of the secret to resolve.
     * @returns The BaseProvider associated with the secret.
     * @throws If the secret is not registered or has no provider.
     */
    resolveProviderFor(secretName: string): {
        providerInstance: BaseProvider;
        providerId: string;
    };
    /**
     * Resolves the actual secret value and its associated provider for a given secret name.
     * This method is used at runtime when the secret is being applied (e.g., `secret apply`).
     * It loads the value from the appropriate connector and returns both the value and the provider.
     *
     * @param secretName - The name of the secret to resolve and load.
     * @returns An object containing the resolved provider and loaded secret value.
     * @throws If the secret is not registered or its connector/provider cannot be found.
     */
    resolveSecretValueForApply(secretName: string): Promise<{
        provider: BaseProvider;
        value: SecretValue;
    }>;
}
export {};
//# sourceMappingURL=SecretManager.d.ts.map