/**
 * @module vault-auth
 * DID-based authentication for Vault Store API requests.
 *
 * Implements Ed25519 signature over canonical request representation with:
 * - Timestamp (prevents replay attacks >5min old)
 * - Nonce (prevents duplicate requests)
 * - Request body hash (ensures integrity)
 *
 * Server verifies signature + timestamp + nonce before serving vault content.
 */
import type { Result } from '@private.me/shared';
import type { AgentIdentity } from './identity.js';
/**
 * Signed vault request metadata.
 */
export interface SignedVaultRequest {
    /** Base64-encoded Ed25519 signature */
    signature: string;
    /** Request timestamp (Unix milliseconds) */
    timestamp: number;
    /** Unique nonce (UUID v4) */
    nonce: string;
}
/**
 * Sign a vault store API request with agent's DID identity.
 *
 * Creates canonical request representation:
 * ```
 * {method}\n{endpoint}\n{timestamp}\n{nonce}\n{bodyHash}
 * ```
 *
 * Server verifies:
 * 1. Signature matches DID public key
 * 2. Timestamp within ±5min (prevents replay)
 * 3. Nonce not seen before (prevents duplicate)
 * 4. Body hash matches (ensures integrity)
 *
 * @param identity - Agent identity (contains signing key)
 * @param endpoint - API endpoint (e.g., "/api/vault-store/crypto")
 * @param body - Request body (JSON-serializable)
 * @returns Signed request metadata or error
 *
 * @example
 * ```typescript
 * const sigResult = await signVaultRequest(agent.identity, '/api/vault-store/crypto', {
 *   requestedVersion: 'latest',
 *   clientVersion: '1.5.0',
 * });
 *
 * if (!sigResult.ok) {
 *   throw new Error('Failed to sign vault request');
 * }
 *
 * const { signature, timestamp, nonce } = sigResult.value;
 *
 * const response = await fetch('https://private.me/api/vault-store/crypto', {
 *   method: 'POST',
 *   headers: {
 *     'X-DID': agent.did,
 *     'X-Signature': signature,
 *     'X-Timestamp': timestamp.toString(),
 *     'X-Nonce': nonce,
 *   },
 *   body: JSON.stringify(body),
 * });
 * ```
 */
export declare function signVaultRequest(identity: AgentIdentity, endpoint: string, body: unknown): Promise<Result<SignedVaultRequest, 'SIGN_FAILED'>>;
/**
 * Verify vault request signature (server-side only).
 *
 * Validates:
 * 1. Signature matches DID public key
 * 2. Timestamp within ±5min window
 * 3. Body hash matches
 *
 * Note: Nonce verification requires server-side nonce store (not implemented here).
 *
 * @param did - Sender DID
 * @param publicKeyBytes - Ed25519 public key (32 bytes)
 * @param endpoint - API endpoint
 * @param body - Request body (JSON string)
 * @param signature - Base64-encoded signature
 * @param timestamp - Request timestamp (Unix ms)
 * @param nonce - Request nonce
 * @returns True if signature is valid
 *
 * @internal Server-side verification only
 */
export declare function verifyVaultRequest(did: string, publicKeyBytes: Uint8Array, endpoint: string, body: string, signature: string, timestamp: number, nonce: string): Promise<boolean>;
