/**
 * KeyProvider port — cryptographic key access for HMAC signing.
 *
 * Design intent:
 *   - The host injects a concrete KeyProvider at boot.
 *   - Agents and trace builders depend ONLY on the KeyProvider interface.
 *   - No key material ever appears in trace files — only the keyId is stored.
 *
 * Implementations provided:
 *   - EnvKeyProvider: reads keys from process.env[keyId] (hex-encoded).
 *     hasColocationRisk() = true when TRACE_DB_URL is also in env
 *     (key and DB on same host — forward secrecy concern).
 *   - ExternalKMSKeyProvider: placeholder for Vault/AWS KMS/Azure Key Vault.
 *     hasColocationRisk() = false (key material never touches the app host).
 *
 * Production notes:
 *   - EnvKeyProvider is acceptable for dev/staging.
 *   - For production audits, use ExternalKMSKeyProvider to satisfy
 *     "key not co-located with data" compliance requirements.
 *   - Both constructors throw in production-like environments when no
 *     config is provided — fail-closed, never silently degrade.
 *
 * @module ports/key-provider
 */
/**
 * Abstract key access port.
 * Implementations are injected by the host at boot time.
 */
export interface KeyProvider {
    /**
     * Retrieve the raw key bytes for `keyId`.
     * @throws Error if the key is not found or cannot be decoded.
     */
    getKey(keyId: string): Promise<Uint8Array>;
    /**
     * Returns true if the key material is co-located with the traced data
     * (e.g. both in process.env on the same host).
     *
     * A true result does NOT block operation — it is a risk signal
     * that should be surfaced in audit reports and monitoring.
     * Callers may log a warning or increment a metric.
     */
    hasColocationRisk(): boolean;
}
/**
 * KeyProvider that reads hex-encoded key bytes from process.env.
 *
 * Key format: hex string, e.g. `export TRACE_HMAC_KEY="deadbeef..."`
 * Minimum recommended key length: 32 bytes (256 bits) for HMAC-SHA-256.
 *
 * Colocation risk:
 *   hasColocationRisk() returns true when `TRACE_DB_URL` is set in the same
 *   environment, indicating that the HMAC key and the database connection
 *   string are both accessible to the same process — a forward-secrecy
 *   concern noted in audit frameworks.
 *   A warning is logged to stderr at construction time when this is detected.
 *
 * Production usage note:
 *   Acceptable for dev and staging. For production compliance requirements
 *   that mandate physical key separation, use ExternalKMSKeyProvider instead.
 */
export declare class EnvKeyProvider implements KeyProvider {
    private readonly _hasColocationRisk;
    constructor();
    getKey(keyId: string): Promise<Uint8Array>;
    hasColocationRisk(): boolean;
}
/**
 * Options for ExternalKMSKeyProvider.
 */
export interface ExternalKMSKeyProviderOptions {
    /**
     * KMS endpoint URL (e.g. Vault transit engine, AWS KMS, Azure Key Vault).
     * Required — no default to avoid silent misconfiguration.
     */
    endpoint: string;
    /**
     * Optional authentication token (injected via sealed secrets or Workload
     * Identity). When absent, the implementation is expected to use
     * environment-level ambient credentials (e.g. AWS Instance Role).
     */
    authToken?: string;
}
/**
 * Placeholder KeyProvider for external KMS (HashiCorp Vault, AWS KMS, Azure Key Vault, …).
 *
 * This implementation is a STUB — it provides the correct interface and
 * colocation risk semantics but does NOT make actual KMS calls.
 * Replace the `getKey` body with your KMS client SDK call.
 *
 * hasColocationRisk() always returns false: key material is never present
 * in the application process; it is fetched on demand from an external system.
 */
export declare class ExternalKMSKeyProvider implements KeyProvider {
    private readonly endpoint;
    private readonly authToken?;
    constructor(options: ExternalKMSKeyProviderOptions);
    /**
     * Fetch the key from the external KMS.
     *
     * STUB: Replace this with your KMS client SDK call.
     * Example (Vault transit):
     *   const res = await fetch(`${this.endpoint}/v1/transit/keys/${keyId}`, { … });
     *   return hexToUint8Array(await res.json().key_bytes);
     */
    getKey(keyId: string): Promise<Uint8Array>;
    /**
     * Always false: key material never resides in the application process.
     * The key is fetched on demand from the external KMS endpoint.
     */
    hasColocationRisk(): boolean;
}
//# sourceMappingURL=key-provider.d.ts.map