@secrefs/node 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,581 @@
+import { SecretsManagerClient } from '@aws-sdk/client-secrets-manager';
+import vaultFactory from 'node-vault';
+
+/**
+ * The provider contract every SecRefs backend (AWS, Vault, local, or a
+ * custom one you bring yourself) implements. Providers never log, print,
+ * or persist the values they return - that discipline is enforced by the
+ * resolver and CLI layers above them, which only ever handle secret values
+ * long enough to hand them to `process.env` or a spawned child process.
+ */
+interface SecretFetchRequest {
+    /** The provider-specific secret path/id, as written after `sec://<provider>/`. */
+    path: string;
+    /** Optional dot-notation field to extract from a JSON secret payload. */
+    field?: string;
+}
+interface ProviderHealth {
+    provider: string;
+    ok: boolean;
+    /** Human-readable diagnostic. Never contains secret material. */
+    message?: string;
+}
+interface ISecretProvider {
+    readonly name: string;
+    /** Fetch and resolve a single secret reference to its final string value. */
+    fetchOne(request: SecretFetchRequest): Promise<string>;
+    /**
+     * Fetch multiple secret references. Implementations may batch/dedupe
+     * against the backend where possible; the default behavior (provided by
+     * {@link BaseSecretProvider}) is concurrent individual fetches via
+     * `Promise.allSettled`, surfacing the first failure with full context.
+     */
+    fetchBatch(requests: SecretFetchRequest[]): Promise<string[]>;
+    /**
+     * Lightweight reachability/auth probe used by `secrefs check`. Must never
+     * throw for expected failure modes (bad credentials, unreachable host) -
+     * those are reported via the returned {@link ProviderHealth}.
+     */
+    healthCheck(): Promise<ProviderHealth>;
+}
+declare class SecretFetchError extends Error {
+    readonly provider: string;
+    readonly path: string;
+    constructor(provider: string, path: string, cause: unknown);
+}
+declare abstract class BaseSecretProvider implements ISecretProvider {
+    abstract readonly name: string;
+    abstract fetchOne(request: SecretFetchRequest): Promise<string>;
+    fetchBatch(requests: SecretFetchRequest[]): Promise<string[]>;
+    abstract healthCheck(): Promise<ProviderHealth>;
+}
+/**
+ * Extracts a (possibly dot-nested) field from a JSON-encoded secret. If no
+ * field is requested, the raw string is returned unchanged. Throws a plain
+ * `Error` (never leaking the secret value itself) when the payload isn't
+ * valid JSON or the field path doesn't resolve to a value.
+ */
+declare function extractField(raw: string, field: string | undefined, context: {
+    provider: string;
+    path: string;
+}): string;
+
+type ProviderRegistry = Record<string, ISecretProvider>;
+interface ExpandOptions {
+    providers: ProviderRegistry;
+    /**
+     * When true (default), a value that starts with `sec://` but fails to
+     * parse throws immediately. When false, such values are left untouched.
+     * This only affects syntactically malformed references - unknown
+     * providers and provider-side fetch failures always surface as errors,
+     * aggregated in a {@link SecRefsResolutionError}.
+     */
+    strict?: boolean;
+}
+interface ResolutionFailure {
+    /** The env var / map key the reference was assigned to. */
+    key: string;
+    /** The original `sec://` string. */
+    ref: string;
+    message: string;
+}
+declare class SecRefsResolutionError extends Error {
+    readonly errors: ResolutionFailure[];
+    constructor(errors: ResolutionFailure[]);
+}
+interface CheckResult {
+    key: string;
+    ref: string;
+    provider: string;
+    ok: boolean;
+    /** Present only when ok is false. Never contains the secret value. */
+    message?: string;
+}
+/**
+ * Expands every `sec://` value in a plain key/value map, resolving all
+ * references concurrently via `Promise.allSettled`. Non-reference values
+ * pass through untouched. Never writes anything to disk - the caller
+ * decides what to do with the returned map (assign to `process.env`,
+ * template into a string, etc).
+ *
+ * Throws {@link SecRefsResolutionError} aggregating every failed
+ * reference if any fail to resolve.
+ */
+declare function expandKeyValueMap(input: Record<string, string | undefined>, options: ExpandOptions): Promise<Record<string, string>>;
+/**
+ * Expands `sec://` values found in `process.env`, mutating it in place.
+ * Returns the list of env var names that were rewritten.
+ */
+declare function expandProcessEnv(options: ExpandOptions): Promise<string[]>;
+/**
+ * Dry-run validation: resolves every `sec://` reference found in `input`
+ * but reports only ok/failure per reference - the secret values themselves
+ * are never returned or logged. Used by `secrefs check`.
+ */
+declare function checkReferences(input: Record<string, string | undefined>, options: ExpandOptions): Promise<CheckResult[]>;
+
+/**
+ * URI parser for SecRefs' `sec://` reference format:
+ *
+ *   sec://<provider-alias>/<secret-path-or-id>[#<json-field>]
+ *
+ *   sec://aws/prod/db#password
+ *   sec://vault/secret/data/stripe#key
+ *   sec://local/mock-db#password
+ *
+ * The provider alias is a bare identifier (letters/digits/`-`/`_`), the path
+ * is opaque to this parser (providers interpret it however their backend
+ * needs), and the optional `#field` fragment supports dot-notation for
+ * traversing nested JSON secrets (e.g. `#nested.value`).
+ */
+interface ParsedSecretRef {
+    /** The original, unmodified reference string. */
+    raw: string;
+    /** Lowercased provider alias, e.g. "aws", "vault", "local". */
+    provider: string;
+    /** The secret path/id as understood by the provider. */
+    path: string;
+    /** Optional dot-notation field to extract from a JSON secret. */
+    field?: string;
+}
+declare class SecRefParseError extends Error {
+    readonly raw: string;
+    readonly reason: string;
+    constructor(raw: string, reason: string);
+}
+/** True if `value` is a string that looks like a `sec://` reference at all. */
+declare function isSecretRef(value: unknown): value is string;
+/**
+ * Parses a `sec://` reference string. Throws {@link SecRefParseError} if the
+ * value isn't a string, doesn't start with `sec://`, or doesn't match the
+ * full `<provider>/<path>[#field]` shape.
+ */
+declare function parseSecretRef(raw: unknown): ParsedSecretRef;
+/** Best-effort parse that returns `null` instead of throwing. */
+declare function tryParseSecretRef(raw: unknown): ParsedSecretRef | null;
+
+/**
+ * dotenv treats `#` as a start-of-comment marker even mid-value (unless
+ * the value is quoted), which silently truncates the `#field` fragment
+ * off an unquoted `sec://provider/path#field` reference - the exact
+ * format SecRefs itself uses. Rather than require every `sec://` value in
+ * `.env` to be quoted (an easy thing to forget, with no error if you do),
+ * this re-scans the raw file for unquoted `sec://` assignments and
+ * restores the value dotenv would otherwise clip.
+ *
+ * Note: because of this, an unquoted `sec://` value can't have a
+ * trailing inline comment on the same line - put comments on their own
+ * line instead. Quoted values (`KEY="sec://...#field"`) are unaffected
+ * and already handled correctly by dotenv itself.
+ */
+declare function recoverTruncatedSecRefs(rawText: string, parsed: Record<string, string>): Record<string, string>;
+/** Parses a `.env` file's contents, correctly preserving `sec://...#field` fragments. */
+declare function parseEnvFileText(rawText: string): Record<string, string>;
+
+/**
+ * A cache that expires, used by every provider that fetches over the
+ * network.
+ *
+ * The default TTL is **zero** — every read re-fetches. That's deliberate
+ * and it's the whole point of the product: a `sec://` reference is a
+ * stable name for a value that changes underneath it. A consumer holding
+ * the reference is supposed to see a rotated secret without being
+ * redeployed, and a cache with no expiry silently breaks exactly that.
+ * Before this existed, a long-running process fetched once and held the
+ * old value until restart.
+ *
+ * A non-zero TTL is a real tradeoff, not a mistake: every expansion is a
+ * network round trip, so a busy caller may want to trade a bounded window
+ * of staleness for latency and API-rate-limit headroom. `ttlMs: 30_000`
+ * means "a rotation reaches me within 30 seconds" — usually fine, and it
+ * should be a decision someone made rather than a default they inherited.
+ */
+interface TtlCacheOptions {
+    /** Milliseconds an entry stays fresh. `0` (default) disables caching
+     * entirely - every `fetch` call goes to the source. */
+    ttlMs?: number;
+    /** Injected in tests so expiry doesn't require real waiting. */
+    now?: () => number;
+}
+declare class TtlCache<T> {
+    /** Settled values, only populated when a TTL is configured. */
+    private readonly entries;
+    /** Requests currently in flight, tracked separately from `entries`
+     * because coalescing and caching are different things: sharing an
+     * unsettled request holds no value past the moment it resolves, so it
+     * stays correct even with caching fully disabled. */
+    private readonly inFlight;
+    private readonly ttlMs;
+    private readonly now;
+    constructor(options?: TtlCacheOptions);
+    /**
+     * Returns the cached value for `key` if it's still fresh, otherwise
+     * calls `load` and caches that. In-flight promises are shared, so N
+     * concurrent expansions of the same reference make one request rather
+     * than N even when the TTL is zero - that's request coalescing, not
+     * caching, and it doesn't hold a value past its use.
+     *
+     * A rejected load is evicted rather than remembered, so a transient
+     * failure doesn't become a sticky one.
+     */
+    fetch(key: string, load: () => Promise<T>): Promise<T>;
+    /** Drops everything - used when a credential changes underneath the
+     * cache and anything fetched with the old one is suspect. */
+    clear(): void;
+}
+
+/**
+ * Thin HTTP client for a running control plane's credential-broker
+ * endpoint (docs/control-plane-design.md §7). This is the piece §10
+ * flagged as the missing link: every provider that supports
+ * control-plane-sourced credentials (AwsSecretsManagerProvider,
+ * BitwardenProvider - see their `controlPlane` constructor option)
+ * constructs one of these instead of only ever reading ambient env vars.
+ *
+ * Deliberately just an HTTP wrapper with no retry/backoff/circuit-
+ * breaking logic - a mint failure surfaces as a normal rejected promise,
+ * same as any other provider fetch failure, and the caller's existing
+ * error handling (resolver.ts's Promise.allSettled aggregation) already
+ * does the right thing with that.
+ */
+interface MintedAwsCredentials {
+    accessKeyId: string;
+    secretAccessKey: string;
+    sessionToken: string;
+    /** ISO-8601 expiration timestamp. */
+    expiration: string;
+}
+interface MintedBitwardenCredentials {
+    accessToken: string;
+    organizationId?: string;
+    /** Explicitly not a TTL promise - see apps/control-plane/src/providers/bitwarden.ts. */
+    note: string;
+}
+type MintCredentialResponse = {
+    provider: "aws";
+    credentials: MintedAwsCredentials;
+} | {
+    provider: "bitwarden";
+    credentials: MintedBitwardenCredentials;
+};
+/** What a provider's `controlPlane` constructor option needs - shared
+ * shape between `AwsSecretsManagerProvider` and `BitwardenProvider` (and
+ * any future control-plane-aware provider). */
+interface ControlPlaneCredentialSource {
+    /** Base URL of a running control plane, e.g. from $SECREFS_CONTROL_PLANE_URL. */
+    baseUrl: string;
+    /** Bootstrap token or a verified OIDC token, e.g. from $SECREFS_CONTROL_PLANE_TOKEN. */
+    token: string;
+    /** Which `VaultConnection` alias this provider instance represents -
+     * this is what the control plane's RBAC grants are actually scoped
+     * against, not the `sec://` alias this provider happens to be
+     * registered under (though in practice they're usually the same
+     * string). */
+    alias: string;
+    /** Injected for testing - defaults to a real `ControlPlaneClient`. */
+    client?: ControlPlaneClient;
+}
+interface ControlPlaneClientOptions {
+    /** Base URL of a running control plane, e.g. from $SECREFS_CONTROL_PLANE_URL. */
+    baseUrl: string;
+    /** Bootstrap token or a verified OIDC token, e.g. from $SECREFS_CONTROL_PLANE_TOKEN. */
+    token: string;
+    /** Injected for testing - defaults to the global `fetch`. */
+    fetchImpl?: typeof fetch;
+}
+/** Thrown for a well-formed error response from the control plane (401,
+ * 403, 502, ...) - `status` and `message` come straight from its `{ error }`
+ * body, so a denial reason (e.g. "no grant authorizes path...") reaches
+ * the caller verbatim rather than as an opaque HTTP failure. */
+declare class ControlPlaneRequestError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+declare class ControlPlaneClient {
+    private readonly baseUrl;
+    private readonly token;
+    private readonly fetchImpl;
+    constructor(options: ControlPlaneClientOptions);
+    /** Authenticates, authorizes, and resolves a credential for `alias`/`path`
+     * - see the control plane's `POST /v1/credentials/mint`. Throws
+     * `ControlPlaneRequestError` for any non-2xx response. */
+    mintCredential(alias: string, path: string): Promise<MintCredentialResponse>;
+}
+
+interface AwsProviderOptions {
+    region?: string;
+    /** Inject a pre-configured client (primarily for testing) - also wins
+     * over `controlPlane` if both are set, since a test that supplies an
+     * explicit client wants full control regardless of the mode. */
+    client?: SecretsManagerClient;
+    /**
+     * Sources per-request AWS credentials from a running control plane
+     * (docs/control-plane-design.md §7/§10) instead of the ambient default
+     * credential chain. Every `fetchOne` call mints a fresh, request-scoped
+     * credential via `sts:AssumeRole` on the control plane's side - see
+     * `apps/control-plane/src/providers/awsSts.ts`. Mutually exclusive
+     * with ambient auth in spirit (not enforced - `client` still wins if
+     * both are given, for testing).
+     */
+    controlPlane?: ControlPlaneCredentialSource;
+    /**
+     * How long a fetched secret value may be reused, in milliseconds.
+     * Defaults to 0 - every expansion re-fetches, so a rotated secret
+     * reaches a long-running consumer without a redeploy. Raise it to
+     * trade a bounded window of staleness for fewer round trips. See
+     * ../ttlCache.ts.
+     */
+    cacheTtlMs?: number;
+}
+/**
+ * AWS Secrets Manager provider. Two credential-sourcing modes:
+ *
+ * - **Ambient (default)**: the AWS SDK v3 default credential provider
+ *   chain - environment variables, shared config/credentials files,
+ *   ECS/EC2 instance metadata, or an assumed IAM role. No credentials
+ *   ever need to live in SecRefs configuration itself. One client is
+ *   built lazily and reused for the provider's lifetime.
+ * - **Control-plane-sourced** (`controlPlane` option): a fresh,
+ *   request-scoped credential is minted per `fetchOne` call via the
+ *   control plane's `/v1/credentials/mint`, so a distinct
+ *   `SecretsManagerClient` is constructed per path rather than reused -
+ *   each one only ever has the narrow scope that one mint granted.
+ *
+ * Raw secret values fetched per-path are cached in memory for the lifetime
+ * of the provider instance either way, so multiple `#field` references
+ * against the same secret only cost one API call (and, in control-plane
+ * mode, one mint).
+ */
+declare class AwsSecretsManagerProvider extends BaseSecretProvider {
+    readonly name = "aws";
+    private readonly explicitClient?;
+    private readonly region?;
+    private readonly controlPlane?;
+    private readonly controlPlaneClient?;
+    private ambientClient;
+    private readonly rawCache;
+    constructor(options?: AwsProviderOptions);
+    /** Resolves the `SecretsManagerClient` to use for one `path` - lazily
+     * built and reused in ambient mode, freshly minted per call in
+     * control-plane mode. `explicitClient` (test injection) always wins. */
+    private clientFor;
+    private buildClientFromMintedCredentials;
+    private getRaw;
+    fetchOne(request: SecretFetchRequest): Promise<string>;
+    healthCheck(): Promise<ProviderHealth>;
+}
+
+interface VaultProviderOptions {
+    /** Defaults to $VAULT_ADDR. */
+    endpoint?: string;
+    /** Defaults to $VAULT_TOKEN. */
+    token?: string;
+    /** Inject a pre-configured client (primarily for testing). */
+    client?: ReturnType<typeof vaultFactory>;
+    /** How long a fetched secret may be reused, in ms. Defaults to 0 -
+     * every expansion re-fetches, so rotation reaches a long-running
+     * consumer without a redeploy. See ../ttlCache.ts. */
+    cacheTtlMs?: number;
+}
+/**
+ * HashiCorp Vault provider supporting both KV v1 and KV v2 secrets engines.
+ * Auth is ambient via `VAULT_ADDR`/`VAULT_TOKEN` - point `path` at whatever
+ * the Vault HTTP API itself expects (KV v2 mounts include a literal `data/`
+ * segment, e.g. `secret/data/stripe`; KV v1 mounts do not).
+ *
+ * The client is constructed lazily on first use so that simply having a
+ * `VaultProvider` in your provider registry doesn't require Vault to be
+ * configured if you never actually reference `sec://vault/...`.
+ */
+declare class VaultProvider extends BaseSecretProvider {
+    readonly name = "vault";
+    private readonly explicitClient?;
+    private readonly endpoint?;
+    private readonly token?;
+    private client;
+    private readonly dataCache;
+    constructor(options?: VaultProviderOptions);
+    private getClient;
+    private getData;
+    fetchOne(request: SecretFetchRequest): Promise<string>;
+    healthCheck(): Promise<ProviderHealth>;
+}
+
+interface LocalProviderOptions {
+    /** Overrides the file path. Defaults to $SECREFS_LOCAL_FILE or ./.secrefs.local.json */
+    filePath?: string;
+    /** Keep the parsed file in memory instead of re-reading per fetch.
+     * Off by default so edits take effect immediately. */
+    cacheFile?: boolean;
+}
+/**
+ * Reads secrets from a gitignored, developer-local JSON file. Intended for
+ * local development only - never point this at anything checked into
+ * version control. Each top-level key is a secret path; its value is either
+ * a plain string (returned as-is when no `#field` is requested) or an
+ * object (JSON-stringified, then field-extracted as needed).
+ *
+ * Example `.secrefs.local.json`:
+ * ```json
+ * { "mock-db": { "password": "hunter2", "user": "postgres" } }
+ * ```
+ */
+declare class LocalProvider extends BaseSecretProvider {
+    readonly name = "local";
+    private readonly filePath;
+    /** Re-read on every fetch. The file is local and tiny, and caching
+     * it meant editing it mid-session silently did nothing. */
+    private cache;
+    private readonly cacheFile;
+    constructor(options?: LocalProviderOptions);
+    private load;
+    fetchOne(request: SecretFetchRequest): Promise<string>;
+    healthCheck(): Promise<ProviderHealth>;
+}
+
+/** The subset of `@bitwarden/sdk-napi`'s `BitwardenClient` this provider
+ * calls - kept narrow so tests can inject a plain mock object instead of
+ * a real client, the same pattern `VaultProvider`/`AwsSecretsManagerProvider`
+ * use for their own SDK clients. */
+interface BitwardenClientLike {
+    auth(): {
+        loginAccessToken(accessToken: string, stateFile?: string): Promise<void>;
+    };
+    secrets(): {
+        get(id: string): Promise<{
+            value: string;
+        }>;
+        list(organizationId: string): Promise<{
+            data: {
+                id: string;
+                key: string;
+            }[];
+        }>;
+    };
+}
+interface BitwardenProviderOptions {
+    /** Defaults to $BWS_ACCESS_TOKEN. Ignored if `controlPlane` is set. */
+    accessToken?: string;
+    /** Required only to resolve a `path` given as a secret *name* rather
+     * than its UUID (see class docs). Defaults to $BWS_ORGANIZATION_ID.
+     * Ignored if `controlPlane` is set - the control plane's distributed
+     * credential supplies this instead. */
+    organizationId?: string;
+    /** Self-hosted instance override. Defaults to $BWS_API_URL. */
+    apiUrl?: string;
+    /** Self-hosted instance override. Defaults to $BWS_IDENTITY_URL. */
+    identityUrl?: string;
+    /**
+     * Opt-in path to an encrypted session-state file the SDK can reuse
+     * across calls to reduce auth rate-limiting (Bitwarden's own docs
+     * describe this file's contents as fully encrypted, not plaintext
+     * secret material). Omitted by default - this provider re-authenticates
+     * in memory each time it's constructed and writes nothing to disk
+     * unless a caller opts in.
+     */
+    stateFile?: string;
+    /**
+     * Sources the access token/organizationId from a running control plane
+     * (docs/control-plane-design.md §7/§10, and §8 for why Bitwarden's
+     * distribution here isn't the same as AWS's per-request minting -
+     * see apps/control-plane/src/providers/bitwarden.ts). Every `fetchOne`
+     * call still requests a distribution for its specific `path`, so the
+     * control plane's RBAC `Grant.path_pattern` is enforced per secret even
+     * though the underlying Bitwarden token itself isn't scoped that
+     * narrowly - "SDK-side enforcement" as documented on the control-plane
+     * side.
+     */
+    controlPlane?: ControlPlaneCredentialSource;
+    /** Inject a pre-configured client (primarily for testing). */
+    client?: BitwardenClientLike;
+}
+/**
+ * Bitwarden **Secrets Manager** provider (not the password vault - see
+ * https://bitwarden.com/help/secrets-manager-overview/). Two structural
+ * differences from `AwsSecretsManagerProvider`/`VaultProvider` worth
+ * knowing before using this:
+ *
+ * 1. **Secrets are end-to-end encrypted.** There is no plain authenticated
+ *    REST call to fetch a value - the official SDK derives a decryption
+ *    key from the access token during login and decrypts client-side.
+ *    That's why this provider depends on `@bitwarden/sdk-napi` (a beta
+ *    Node-API binding maintained by Bitwarden) rather than a bare `fetch`.
+ * 2. **Bitwarden addresses secrets by UUID, with no path hierarchy** the
+ *    way AWS/Vault secret names have. `path` may be that UUID directly, or
+ *    - if `organizationId` is configured (ambient mode) or supplied by the
+ *    control plane (control-plane mode) - a human-readable secret *name*
+ *    (Bitwarden's "key" field), resolved via one cached `secrets().list()`
+ *    call. With neither, only UUID paths work.
+ */
+declare class BitwardenProvider extends BaseSecretProvider {
+    readonly name = "bitwarden";
+    private readonly explicitClient?;
+    private readonly ambientAccessToken?;
+    private readonly ambientOrganizationId?;
+    private readonly apiUrl?;
+    private readonly identityUrl?;
+    private readonly stateFile?;
+    private readonly controlPlane?;
+    private readonly controlPlaneClient?;
+    private client;
+    private loggedInAccessToken;
+    private loggedIn;
+    private organizationId;
+    /** Secret name -> id, populated by one `list()` call the first time a
+     * non-UUID path is requested. Invalidated if `organizationId` ever
+     * changes (control-plane mode, defensively - static in practice). */
+    private nameToId;
+    constructor(options?: BitwardenProviderOptions);
+    private getClient;
+    private loginWith;
+    /** Ensures a session exists for `path`. Ambient mode logs in once
+     * (memoized) with the ambient token; control-plane mode requests a
+     * distribution for this specific `path` every call - see the
+     * `controlPlane` option's docs for why that RBAC check has to be
+     * per-path even though the token it returns doesn't vary. */
+    private ensureLoggedInFor;
+    /** Assumes `ensureLoggedInFor(path)` has already run for this exact
+     * `path` - callers always do that first, so `this.organizationId` is
+     * already whatever this path's session resolved to. */
+    private resolveSecretId;
+    fetchOne(request: SecretFetchRequest): Promise<string>;
+    healthCheck(): Promise<ProviderHealth>;
+}
+
+/** Builds the default provider registry: aws, vault, local, bitwarden. */
+declare function createDefaultProviders(): ProviderRegistry;
+interface SecRefsOptions {
+    providers?: ProviderRegistry;
+    strict?: boolean;
+}
+/**
+ * The primary library entry point. Instantiate your own (with a custom
+ * provider registry) or use the default `secRefs` singleton below.
+ */
+declare class SecRefs {
+    readonly providers: ProviderRegistry;
+    readonly strict: boolean;
+    constructor(options?: SecRefsOptions);
+    private get expandOptions();
+    /**
+     * Expands every `sec://` value found in `process.env`, mutating it in
+     * place. Returns the list of env var names that were rewritten.
+     */
+    init(): Promise<string[]>;
+    /**
+     * Expands `sec://` values in an arbitrary key/value map (e.g. a parsed
+     * `.env` file) without touching `process.env`.
+     */
+    expandEnv(env: Record<string, string | undefined>): Promise<Record<string, string>>;
+    /** Expands a single string if it's a `sec://` reference; otherwise returns it unchanged. */
+    expandString(value: string): Promise<string>;
+    /**
+     * Dry-run validation of every `sec://` reference in `env` (defaults to
+     * `process.env`). Never returns plaintext secret values.
+     */
+    check(env?: Record<string, string | undefined>): Promise<Awaited<ReturnType<typeof checkReferences>>>;
+}
+/** Convenience singleton mirroring `secRefs.init()` / `secRefs.expandEnv()` / `secRefs.expandString()`. */
+declare const secRefs: SecRefs;
+
+export { type AwsProviderOptions, AwsSecretsManagerProvider, BaseSecretProvider, type BitwardenClientLike, BitwardenProvider, type BitwardenProviderOptions, type CheckResult, ControlPlaneClient, type ControlPlaneClientOptions, type ControlPlaneCredentialSource, ControlPlaneRequestError, type ExpandOptions, type ISecretProvider, LocalProvider, type LocalProviderOptions, type MintCredentialResponse, type MintedAwsCredentials, type MintedBitwardenCredentials, type ParsedSecretRef, type ProviderHealth, type ProviderRegistry, type ResolutionFailure, SecRefParseError, SecRefs, type SecRefsOptions, SecRefsResolutionError, SecretFetchError, type SecretFetchRequest, TtlCache, type TtlCacheOptions, VaultProvider, type VaultProviderOptions, checkReferences, createDefaultProviders, expandKeyValueMap, expandProcessEnv, extractField, isSecretRef, parseEnvFileText, parseSecretRef, recoverTruncatedSecRefs, secRefs, tryParseSecretRef };