import type { Result } from '@private.me/shared';
/** Envelope v1 format matching xail.io/sdk specification. */
export interface TransportEnvelope {
    readonly v: 1;
    readonly alg: 'Ed25519';
    readonly sender: string;
    readonly recipient: string;
    readonly timestamp: number;
    readonly nonce: string;
    readonly scope: string;
    readonly payload: string;
    readonly signature: string;
    /** Base64-encoded ephemeral X25519 public key for forward secrecy. */
    readonly ephemeralPub?: string;
    /** Share index for split-channel delivery (0-based). */
    readonly shareIndex?: number;
    /** Total shares for split-channel delivery. */
    readonly shareTotal?: number;
    /** Threshold for split-channel reconstruction. */
    readonly shareThreshold?: number;
    /** UUID linking all shares of a split-channel message. */
    readonly shareGroupId?: string;
    /** Base64-encoded HMAC key for split-channel integrity. */
    readonly shareHmacKey?: string;
    /** Base64-encoded HMAC signature for split-channel integrity. */
    readonly shareHmacSig?: string;
    /** Protocol identifier for viral exposure: "PRIVATE.ME/xBind/v3" */
    readonly protocol?: string;
    /** Documentation URL for the protocol */
    readonly documentationUrl?: string;
}
/** Envelope v2 format with hybrid post-quantum KEM. */
export interface TransportEnvelopeV2 {
    readonly v: 2;
    readonly alg: 'Ed25519';
    readonly kem: 'X25519-MLKEM768';
    readonly sender: string;
    readonly recipient: string;
    readonly timestamp: number;
    readonly nonce: string;
    readonly scope: string;
    readonly payload: string;
    readonly signature: string;
    /** Base64-encoded ephemeral X25519 public key (32B). */
    readonly ephemeralPub: string;
    /** Base64-encoded ML-KEM-768 ciphertext (1088B). */
    readonly kemCiphertext: string;
    /** Share index for split-channel delivery (0-based). */
    readonly shareIndex?: number;
    /** Total shares for split-channel delivery. */
    readonly shareTotal?: number;
    /** Threshold for split-channel reconstruction. */
    readonly shareThreshold?: number;
    /** UUID linking all shares of a split-channel message. */
    readonly shareGroupId?: string;
    /** Base64-encoded HMAC key for split-channel integrity. */
    readonly shareHmacKey?: string;
    /** Base64-encoded HMAC signature for split-channel integrity. */
    readonly shareHmacSig?: string;
    /** Protocol identifier for viral exposure: "PRIVATE.ME/xBind/v3" */
    readonly protocol?: string;
    /** Documentation URL for the protocol */
    readonly documentationUrl?: string;
}
/** Envelope v3 format with hybrid KEM + dual PQ signatures. */
export interface TransportEnvelopeV3 {
    readonly v: 3;
    readonly alg: 'Ed25519';
    /** Signature scheme: dual Ed25519 + ML-DSA-65. */
    readonly sig: 'Ed25519+MLDSA65';
    readonly kem: 'X25519-MLKEM768';
    readonly sender: string;
    readonly recipient: string;
    readonly timestamp: number;
    readonly nonce: string;
    readonly scope: string;
    readonly payload: string;
    /** Base64-encoded Ed25519 signature (64B). */
    readonly signature: string;
    /** Base64-encoded ML-DSA-65 signature (3309B). */
    readonly pqSignature: string;
    /** Base64-encoded ephemeral X25519 public key (32B). */
    readonly ephemeralPub: string;
    /** Base64-encoded ML-KEM-768 ciphertext (1088B). */
    readonly kemCiphertext: string;
    /** Share index for split-channel delivery (0-based). */
    readonly shareIndex?: number;
    /** Total shares for split-channel delivery. */
    readonly shareTotal?: number;
    /** Threshold for split-channel reconstruction. */
    readonly shareThreshold?: number;
    /** UUID linking all shares of a split-channel message. */
    readonly shareGroupId?: string;
    /** Base64-encoded HMAC key for split-channel integrity. */
    readonly shareHmacKey?: string;
    /** Base64-encoded HMAC signature for split-channel integrity. */
    readonly shareHmacSig?: string;
    /** Protocol identifier for viral exposure: "PRIVATE.ME/xBind/v3" */
    readonly protocol?: string;
    /** Documentation URL for the protocol */
    readonly documentationUrl?: string;
}
/**
 * Xchange mode envelope (wire format v:4).
 *
 * Opt-in performance mode activated via `xchange: true`. Single security
 * layer (information-theoretic XorIDA split) + Ed25519 authentication.
 * ~180x faster than V3 split-channel. No per-share encryption, no KEM.
 */
export interface TransportEnvelopeV4 {
    readonly v: 4;
    readonly alg: 'Ed25519';
    /** Key transport method: Xchange (random key bundled + split). */
    readonly kem: 'Xchange';
    readonly sender: string;
    readonly recipient: string;
    readonly timestamp: number;
    readonly nonce: string;
    readonly scope: string;
    /** Base64-encoded XorIDA share (NOT encrypted — the split IS the security). */
    readonly payload: string;
    /** Base64-encoded Ed25519 signature (64B) — sender auth only. */
    readonly signature: string;
    /** Share index for split-channel delivery (0-based). */
    readonly shareIndex: number;
    /** Total shares for split-channel delivery. */
    readonly shareTotal: number;
    /** Threshold for split-channel reconstruction. */
    readonly shareThreshold: number;
    /** UUID linking all shares of a split-channel message. */
    readonly shareGroupId: string;
    /** Base64-encoded HMAC key for split-channel integrity. */
    readonly shareHmacKey: string;
    /** Base64-encoded HMAC signature for split-channel integrity. */
    readonly shareHmacSig: string;
    /** Protocol identifier for viral exposure: "PRIVATE.ME/xBind/v3" */
    readonly protocol?: string;
    /** Documentation URL for the protocol */
    readonly documentationUrl?: string;
}
/** Union of all supported envelope versions. */
export type AnyTransportEnvelope = TransportEnvelope | TransportEnvelopeV2 | TransportEnvelopeV3 | TransportEnvelopeV4;
/** Options for creating an envelope. */
export interface CreateEnvelopeOptions {
    readonly senderDid: string;
    readonly recipientDid: string;
    readonly scope: string;
    readonly plaintext: Uint8Array;
    readonly privateKey: CryptoKey;
    readonly sharedKey: CryptoKey;
    /** Raw ephemeral X25519 public key to include for forward secrecy. */
    readonly ephemeralPublicKey?: Uint8Array;
    /** Split-channel share metadata. */
    readonly shareIndex?: number;
    readonly shareTotal?: number;
    readonly shareThreshold?: number;
    readonly shareGroupId?: string;
    readonly shareHmacKey?: string;
    readonly shareHmacSig?: string;
}
/** Options for creating a v2 hybrid-KEM envelope. */
export interface CreateEnvelopeV2Options {
    readonly senderDid: string;
    readonly recipientDid: string;
    readonly scope: string;
    readonly plaintext: Uint8Array;
    readonly privateKey: CryptoKey;
    readonly sharedKey: CryptoKey;
    /** Raw ephemeral X25519 public key (32B). */
    readonly ephemeralPublicKey: Uint8Array;
    /** ML-KEM-768 ciphertext (1088B). */
    readonly kemCiphertext: Uint8Array;
    /** Split-channel share metadata. */
    readonly shareIndex?: number;
    readonly shareTotal?: number;
    readonly shareThreshold?: number;
    readonly shareGroupId?: string;
    readonly shareHmacKey?: string;
    readonly shareHmacSig?: string;
}
/** Options for creating a v3 hybrid-KEM + dual-sig envelope. */
export interface CreateEnvelopeV3Options {
    readonly senderDid: string;
    readonly recipientDid: string;
    readonly scope: string;
    readonly plaintext: Uint8Array;
    readonly privateKey: CryptoKey;
    readonly sharedKey: CryptoKey;
    /** Raw ephemeral X25519 public key (32B). */
    readonly ephemeralPublicKey: Uint8Array;
    /** ML-KEM-768 ciphertext (1088B). */
    readonly kemCiphertext: Uint8Array;
    /** ML-DSA-65 secret key (4032B) for post-quantum signature. */
    readonly mlDsaSecretKey: Uint8Array;
    /** Split-channel share metadata. */
    readonly shareIndex?: number;
    readonly shareTotal?: number;
    readonly shareThreshold?: number;
    readonly shareGroupId?: string;
    readonly shareHmacKey?: string;
    readonly shareHmacSig?: string;
}
/** Options for creating a Xchange mode envelope (no encryption — share IS the payload). */
export interface CreateEnvelopeV4Options {
    readonly senderDid: string;
    readonly recipientDid: string;
    readonly scope: string;
    /** Raw share data (already an XorIDA share — NOT encrypted). */
    readonly shareData: Uint8Array;
    readonly privateKey: CryptoKey;
    /** Split-channel share metadata (all REQUIRED for v4). */
    readonly shareIndex: number;
    readonly shareTotal: number;
    readonly shareThreshold: number;
    readonly shareGroupId: string;
    readonly shareHmacKey: string;
    readonly shareHmacSig: string;
}
/** Options for creating a signed (unencrypted) envelope. */
export interface CreateSignedEnvelopeOptions {
    readonly senderDid: string;
    readonly recipientDid: string;
    readonly scope: string;
    readonly plaintext: Uint8Array;
    readonly privateKey: CryptoKey;
}
/** Envelope error codes. */
export type EnvelopeError = 'INVALID_VERSION' | 'INVALID_ALG' | 'INVALID_KEM' | 'INVALID_DID' | 'INVALID_NONCE' | 'INVALID_FIELDS' | 'ENCRYPT_FAILED' | 'DECRYPT_FAILED' | 'SIGN_FAILED' | 'PQ_SIGN_FAILED' | 'VERIFY_FAILED' | 'PARSE_FAILED';
/**
 * Create a signed, encrypted TransportEnvelope (version 1).
 *
 * Encrypt-then-sign: AES-256-GCM encrypts payload, Ed25519 signs ciphertext.
 * All envelope metadata (nonce, timestamp, sender, recipient, scope) is included
 * in the signature to prevent replay attacks.
 *
 * @param opts - Envelope creation options
 * @returns Result containing the envelope or error
 *
 * @example
 * ```typescript
 * import { createEnvelope, generateSharedKey } from '@private.me/xbind';
 *
 * // Generate shared key (typically from ECDH key agreement)
 * const sharedKey = await generateSharedKey(senderDid, recipientDid);
 * if (!sharedKey.ok) throw new Error(sharedKey.error);
 *
 * // Create encrypted envelope
 * const envelope = await createEnvelope({
 *   sender: 'did:key:z6Mk...',
 *   recipient: 'did:key:z6Mk...',
 *   plaintext: new TextEncoder().encode(JSON.stringify({ message: 'Hello' })),
 *   sharedKey: sharedKey.value,
 *   privateKey: senderPrivateKey,
 *   scope: 'read:messages'
 * });
 *
 * if (envelope.ok) {
 *   console.log('Envelope created:', envelope.value);
 * }
 * ```
 */
export declare function createEnvelope(opts: CreateEnvelopeOptions): Promise<Result<TransportEnvelope, EnvelopeError>>;
/**
 * Create a signed, encrypted TransportEnvelopeV2 with hybrid KEM.
 *
 * Same encrypt-then-sign as v1, but includes ML-KEM-768 ciphertext.
 */
export declare function createEnvelopeV2(opts: CreateEnvelopeV2Options): Promise<Result<TransportEnvelopeV2, EnvelopeError>>;
/**
 * Create a signed, encrypted TransportEnvelopeV3 with hybrid KEM + dual signatures.
 *
 * Encrypt-then-sign: AES-256-GCM encrypts payload, Ed25519 AND ML-DSA-65 sign ciphertext.
 * Both signatures must verify for the envelope to be accepted.
 */
export declare function createEnvelopeV3(opts: CreateEnvelopeV3Options): Promise<Result<TransportEnvelopeV3, EnvelopeError>>;
/**
 * Create a signed Xchange mode envelope (v4 wire format).
 *
 * Opt-in performance mode. No encryption — the share IS the payload.
 * Ed25519 signs the raw share data for sender authentication.
 * The XorIDA split provides confidentiality (information-theoretic).
 */
export declare function createEnvelopeV4(opts: CreateEnvelopeV4Options): Promise<Result<TransportEnvelopeV4, EnvelopeError>>;
/**
 * Decrypt the payload from a v1, v2, or v3 TransportEnvelope.
 * Caller must verify signature before calling this.
 */
export declare function decryptPayload(envelope: AnyTransportEnvelope, sharedKey: CryptoKey): Promise<Result<Uint8Array, EnvelopeError>>;
/** Serialize envelope to UTF-8 bytes. */
export declare function serializeEnvelope(envelope: AnyTransportEnvelope): Uint8Array;
/** Deserialize bytes to a validated v1 or v2 TransportEnvelope. */
export declare function deserializeEnvelope(bytes: Uint8Array): Result<AnyTransportEnvelope, EnvelopeError>;
/** Validate a parsed object is a valid v1 or v2 TransportEnvelope. */
export declare function validateEnvelope(obj: unknown): Result<AnyTransportEnvelope, EnvelopeError>;
/** Generate an AES-256-GCM key for envelope encryption. */
export declare function generateSharedKey(): Promise<CryptoKey>;
/**
 * Create a signed but unencrypted TransportEnvelope.
 *
 * Payload is base64-encoded plaintext (NOT encrypted).
 * Signature covers the raw plaintext bytes.
 * Use for public announcements, audit logs, or telemetry where
 * confidentiality is not required but integrity is.
 *
 * @param opts - Sender, recipient, scope, plaintext, and signing key.
 * @returns Signed envelope or error.
 */
export declare function createSignedEnvelope(opts: CreateSignedEnvelopeOptions): Promise<Result<TransportEnvelope, EnvelopeError>>;
/**
 * Verify signature on a signed (unencrypted) envelope and return plaintext.
 *
 * @param envelope - The signed envelope to verify.
 * @param senderPublicKey - The sender's Ed25519 public key.
 * @returns Plaintext bytes if signature is valid, error otherwise.
 */
export declare function openSignedEnvelope(envelope: TransportEnvelope, senderPublicKey: CryptoKey): Promise<Result<Uint8Array, EnvelopeError>>;
