import type { ScopeOfClaim } from '../accountability/types/base.js';
/**
 * RFC 7517 JSON Web Key, narrowed to the OKP / Ed25519 signing case
 * (RFC 8037). This resolver supports no other key type. X-curve
 * members (X25519/X448) are ECDH key-agreement keys, not signature
 * keys, and are rejected at selection time.
 */
export interface Ed25519JWK {
    /** RFC 8037: MUST be "OKP" (Octet Key Pair). */
    kty: 'OKP';
    /** RFC 8037: MUST be "Ed25519". */
    crv: 'Ed25519';
    /** base64url (no padding) of the raw 32-byte Ed25519 public key. */
    x: string;
    /** Opaque key selector. Optional in RFC 7517, but REQUIRED here for
     *  unambiguous rotation. Compared by exact, case-sensitive equality. */
    kid?: string;
    /** If present MUST be "sig". An "enc" key is rejected. */
    use?: 'sig' | string;
    /** If present MUST be "EdDSA". */
    alg?: 'EdDSA' | string;
    /** If present MUST include "verify". */
    key_ops?: string[];
}
/**
 * RFC 7517 JWK Set. The single REQUIRED member is `keys`, an array of
 * JWK objects. A resolver MUST treat a private `d` member on any JWK
 * as a misconfiguration and never use it; this type does not surface
 * `d`, and the loader strips it.
 */
export interface JWKS {
    keys: Ed25519JWK[];
}
/**
 * How a resolution finished. `ok` resolutions carry a key; every other
 * status carries no key and a verifier MUST reject.
 *
 *  - 'resolved'      : a single Ed25519 key was selected.
 *  - 'not_found'     : endpoint loaded but no candidate matched the kid.
 *  - 'ambiguous'     : more than one candidate matched (or no kid and
 *                      more than one signing key). Fail-closed.
 *  - 'malformed'     : endpoint loaded but the body / JWKS / JWK / x
 *                      was structurally invalid. Fail-closed even under
 *                      fail-open: a body that loads but is wrong is NOT
 *                      a transient-network condition.
 *  - 'unreachable'   : network error, timeout, non-200, or non-JSON
 *                      body. The ONLY status fail-open may relax.
 *  - 'unsupported'   : the locator named a method this resolver does
 *                      not handle.
 */
export type KeyResolutionStatus = 'resolved' | 'not_found' | 'ambiguous' | 'malformed' | 'unreachable' | 'unsupported';
/**
 * Result of a single resolution. When `ok` is true, `publicKeyHex` is
 * a 64-char lowercase hex Ed25519 public key consumable by
 * crypto/keys.ts verify(). When `ok` is false, `publicKeyHex` is
 * undefined and `status`/`reason` explain why; the caller MUST treat
 * this as "no key" and fail the signature check closed.
 *
 * `degraded` is true only when a fail-open policy turned an
 * 'unreachable' condition into a non-rejecting outcome. A degraded
 * result MUST NOT be read as a positive verification.
 */
export interface KeyResolution {
    ok: boolean;
    status: KeyResolutionStatus;
    /** 64-char lowercase hex Ed25519 public key, present iff ok. */
    publicKeyHex?: string;
    /** The kid that was selected (echoed back), when applicable. */
    kid?: string;
    /** Whether cache served this result, for observability. */
    cacheHit?: boolean;
    /** True iff a fail-open policy produced a non-rejecting degraded
     *  outcome from an unreachable endpoint. */
    degraded?: boolean;
    /** Human-readable, non-sensitive explanation. */
    reason?: string;
    /** Scope-of-claim for any resolution that feeds a receipt check. */
    scope_of_claim?: ScopeOfClaim;
}
/**
 * What to resolve. Exactly one of `did` or `jwksUrl` is the anchor.
 *  - `did`     : a DID or DID URL. A `#fragment` is read as the kid.
 *  - `jwksUrl` : a direct https JWKS endpoint (reference / testing).
 *  - `kid`     : explicit kid selector. When both a DID-URL fragment
 *                and an explicit `kid` are present they MUST agree, or
 *                resolution fails closed (ambiguous request).
 */
export interface KeyLocator {
    did?: string;
    jwksUrl?: string;
    kid?: string;
}
/**
 * Failure posture.
 *  - 'closed' (DEFAULT): any resolution failure yields no key; the
 *    signature check rejects. This is the only safe default.
 *  - 'open': an explicit, opt-in, documented-degraded mode. It relaxes
 *    ONLY the 'unreachable'/transient-network case into a degraded
 *    result. A malformed JWKS, an absent kid, or an unsupported key
 *    type STILL fails closed. fail-open is never "accept anything".
 */
export type FailurePolicy = 'closed' | 'open';
/**
 * Caching policy. The cache distinguishes hits from misses and never
 * promotes a cached negative/miss into a key.
 *  - `ttlMs`         : positive-result lifetime in ms.
 *  - `negativeTtlMs` : miss/negative lifetime in ms (default: short).
 *  - `maxEntries`    : bound on distinct cache keys (LRU-style evict).
 */
export interface CachePolicy {
    ttlMs: number;
    negativeTtlMs: number;
    maxEntries: number;
}
/**
 * Resolver-wide configuration.
 *  - `failurePolicy` : defaults to 'closed'.
 *  - `timeoutMs`     : fetch timeout, mirrors the did:web resolver.
 *  - `cache`         : caching policy (TTL hit/miss).
 *  - `fetchImpl`     : injectable fetch for tests; defaults to global.
 *  - `now`           : injectable clock for tests; defaults to Date.now.
 */
export interface KeyResolverConfig {
    failurePolicy?: FailurePolicy;
    timeoutMs?: number;
    cache?: Partial<CachePolicy>;
    fetchImpl?: typeof fetch;
    now?: () => number;
}
/**
 * The standardized KeyResolver interface. A resolver answers "which
 * public key does this locator assert?" and nothing more. It performs
 * no signature verification itself; the caller passes the returned
 * `publicKeyHex` to crypto/keys.ts verify().
 */
export interface KeyResolver {
    /** True iff this resolver handles the given locator's method. */
    canResolve(locator: KeyLocator): boolean;
    /** Resolve a locator to a single Ed25519 verification key. Always
     *  resolves the promise; failure is reported via the result's
     *  status/ok, never by rejecting (except for programmer errors). */
    resolve(locator: KeyLocator): Promise<KeyResolution>;
}
/** Default fetch timeout, matching the existing did:web resolver. */
export declare const DEFAULT_TIMEOUT_MS = 10000;
/** Conservative cache defaults: 5 min positive, 30 s negative. */
export declare const DEFAULT_CACHE_POLICY: CachePolicy;
//# sourceMappingURL=types.d.ts.map