/**
 * Read a secret by name from the boot snapshot. Identical to `serverEnv[key]`
 * but signals intent at the call site ("this is a secret"). Typed `string`
 * for the common case; cast if you declared a coerced secret.
 *
 * ```ts
 * import { getSecret } from '@voltro/env/server'
 * const key = getSecret('STRIPE_KEY')
 * ```
 */
export declare const getSecret: (key: string) => string | undefined;

/**
 * Read a secret together with its previous value during a rotation overlap.
 *
 * `current` is what everything else now sees; `previous` is present only while
 * a `rotateSecretLive` grace window is open (then `undefined` — revoked). A
 * verifier tries `current` first and falls back to `previous`, exactly like
 * session verification honoring `VOLTRO_SESSION_SECRET` + `_PREVIOUS`.
 */
export declare const getSecretWithOverlap: (key: string) => {
    readonly current: string | undefined;
    readonly previous: string | undefined;
};

/**
 * Resolve a secret LIVE through the configured backend (Vault / Doppler / http
 * / env), bypassing the boot snapshot. Use this only when you genuinely need a
 * post-boot re-read (e.g. a rotated remote secret) — the snapshot is correct
 * for ~99% of reads and avoids a per-call backend round-trip.
 */
export declare const resolveSecretLive: (key: string) => Promise<string | undefined>;

/**
 * The blessed live-rotation flow: re-resolve `key` through the configured
 * backend, install the NEW value over the boot snapshot so a running process
 * serves it immediately, and hold the OLD value for `graceMs` so work
 * created just before the rotation still verifies during cutover.
 *
 * This is the "set new → overlap → revoke" runbook made mechanical: after
 * `graceMs` the previous value is revoked automatically (pruned on read — no
 * timer, no dev/serve boot wiring), so an operator drives only the ONE call and
 * the grace duration, not a sequence of manual `.env` edits. Reads through
 * `getSecret` / `serverEnv` see the new value at once; a verifier that must
 * accept both during cutover reads `getSecretWithOverlap`.
 *
 * IMPORTANT — scope of "without a restart". This updates what CODE that reads a
 * secret PER USE sees (an outbound API key, a webhook-signing secret, a
 * field-encryption key). It does NOT re-establish a connection that captured the
 * old value at construction — a live DB pool built with the old `DB_URL`
 * password keeps that connection until it is rebuilt (still a restart, or a
 * pool-level reconnect). Rotate connection credentials with that in mind.
 *
 * The default grace is 5 minutes — long enough for in-flight requests and
 * short-TTL tokens to drain, short enough that a leaked value's window closes
 * promptly. Pass `graceMs: 0` for a hard cutover with no overlap.
 */
export declare const rotateSecretLive: (key: string, options?: {
    readonly graceMs?: number;
}) => Promise<SecretRotation>;

/** The outcome of a live rotation — what `getSecret` now returns and, while the
 *  grace window is open, the value that still verifies during cutover. */
export declare interface SecretRotation {
    readonly key: string;
    /** The freshly-resolved value now served by `getSecret` / `serverEnv`. */
    readonly current: string | undefined;
    /** The pre-rotation value, valid until `graceMs` elapses (`undefined` on a
     *  hard cutover, or when there was no prior value). */
    readonly previous: string | undefined;
    /** The overlap window, in ms, during which `previous` still verifies. */
    readonly graceMs: number;
}

/**
 * The typed server env accessor. The framework's codegen augments this
 * interface in a generated `.d.ts` so `serverEnv.MY_VAR` autocompletes to the
 * exact declared type. Without codegen it falls back to `unknown` per key —
 * still safe, just untyped.
 */
declare const SERVER_ENV_BRAND: unique symbol;

export declare interface ServerEnv {
    readonly [SERVER_ENV_BRAND]?: never;
}

/**
 * Read any server-readable env value (public or secret) by name.
 *
 * ```ts
 * import { serverEnv } from '@voltro/env/server'
 * const dsn = serverEnv.SENTRY_DSN          // typed via generated augmentation
 * ```
 *
 * Throws if read before the boot env gate ran (a wiring bug — env is only
 * available inside handlers / loaders / startup hooks, never at import time).
 */
export declare const serverEnv: ServerEnv;

export { }