import type { Result } from '@private.me/shared';
/** Error codes for checkpoint operations. */
export type CheckpointError = 'SIGN_FAILED' | 'VERIFY_FAILED' | 'INVALID_FORMAT' | 'INVALID_TIMESTAMP' | 'INVALID_SIGNATURE' | 'STALE_CACHE';
/**
 * Gateway-signed DID state checkpoint (freshness primitive).
 *
 * Checkpoints provide cryptographic proof of DID state at a specific timestamp.
 * Clients compare checkpoint rotation_sequence against local cache to detect staleness.
 *
 * Format:
 * - subject: DID being checkpointed
 * - current_public_key: Current public key (base64)
 * - revoked: Revocation status
 * - rotation_sequence: Monotonic counter from succession events
 * - timestamp: Unix milliseconds when checkpoint was created
 * - checkpoint_signature: ML-DSA-65 signature from gateway key
 */
export interface DIDStateCheckpoint {
    readonly type: 'DIDStateCheckpoint';
    readonly version: '1.0';
    readonly subject: string;
    readonly current_public_key: string;
    readonly revoked: boolean;
    readonly rotation_sequence: number;
    readonly timestamp: number;
    readonly checkpoint_signature_algorithm: 'ML-DSA-65';
    readonly checkpoint_signature: string;
}
/**
 * Local cache entry for DID state.
 * Used for staleness detection against signed checkpoints.
 */
export interface LocalDIDCache {
    readonly did: string;
    readonly publicKey: Uint8Array;
    readonly revoked: boolean;
    readonly rotationSequence: number;
    readonly cachedAt: number;
}
/**
 * Create a signed checkpoint for a DID (gateway-side operation).
 *
 * Gateway signs the DID state snapshot using its ML-DSA-65 private key.
 * Clients verify this signature using the gateway's published public key.
 *
 * @param subject - DID being checkpointed
 * @param publicKey - Current public key bytes
 * @param revoked - Current revocation status
 * @param rotationSequence - Current rotation sequence counter
 * @param gatewayPrivateKey - Gateway's ML-DSA-65 secret key (32-byte seed or 4032-byte expanded)
 * @returns Signed checkpoint or error
 *
 * @example
 * ```typescript
 * const checkpoint = await createCheckpoint(
 *   'did:key:z6Mk...',
 *   publicKeyBytes,
 *   false,
 *   5,
 *   gatewaySecretKey
 * );
 * if (checkpoint.ok) {
 *   // Send checkpoint to client for staleness detection
 *   sendToClient(checkpoint.value);
 * }
 * ```
 */
export declare function createCheckpoint(subject: string, publicKey: Uint8Array, revoked: boolean, rotationSequence: number, gatewayPrivateKey: Uint8Array): Promise<Result<DIDStateCheckpoint, CheckpointError>>;
/**
 * Verify a checkpoint signature (client-side operation).
 *
 * Clients MUST verify checkpoint signatures before trusting the state.
 * Uses gateway's published ML-DSA-65 public key to verify signature.
 *
 * @param checkpoint - Checkpoint to verify
 * @param gatewayPublicKey - Gateway's ML-DSA-65 public key (1952 bytes)
 * @returns true if signature valid, false if invalid, error if verification fails
 *
 * @example
 * ```typescript
 * const valid = await verifyCheckpoint(checkpoint, gatewayPubKey);
 * if (valid.ok && valid.value) {
 *   // Checkpoint is authentic - safe to use for staleness detection
 *   if (isCacheStale(localCache, checkpoint)) {
 *     // Refresh local cache
 *   }
 * }
 * ```
 */
export declare function verifyCheckpoint(checkpoint: DIDStateCheckpoint, gatewayPublicKey: Uint8Array): Promise<Result<boolean, CheckpointError>>;
/**
 * Detect if local cache is stale compared to gateway checkpoint.
 *
 * Cache is stale if:
 * 1. Checkpoint rotation_sequence > local rotationSequence (key rotated)
 * 2. Checkpoint revoked !== local revoked (revocation status changed)
 * 3. Checkpoint public key !== local publicKey (state drift)
 *
 * @param localCache - Local cache entry for DID
 * @param checkpoint - Verified checkpoint from gateway
 * @returns true if cache needs refresh, false if cache is current
 *
 * @example
 * ```typescript
 * if (isCacheStale(localCache, checkpoint)) {
 *   // Local cache is outdated - fetch fresh state from gateway
 *   const freshState = await registry.getEntry(did);
 * }
 * ```
 */
export declare function isCacheStale(localCache: LocalDIDCache, checkpoint: DIDStateCheckpoint): boolean;
/**
 * Encode checkpoint to JSON string for wire transport.
 *
 * @param checkpoint - Checkpoint to encode
 * @returns JSON string
 */
export declare function encodeCheckpoint(checkpoint: DIDStateCheckpoint): string;
/**
 * Decode checkpoint from JSON string.
 *
 * @param encoded - JSON string
 * @returns Parsed checkpoint or error
 */
export declare function decodeCheckpoint(encoded: string): Result<DIDStateCheckpoint, CheckpointError>;
