/**
 * Enbox Connect Protocol
 *
 * A capability delegation protocol for DWN access. Enables apps to request
 * scoped permission grants from a wallet (provider), receiving a delegate DID
 * with the granted permissions.
 *
 * Two transport modes:
 * - Local (`dwn://connect`): same-device, direct HTTP against the local DWN
 * - Remote (`enbox://connect`): cross-device, relay-mediated with QR/deep link
 *
 * The protocol uses JWTs for signing, JWE (XChaCha20-Poly1305) for encryption,
 * and ECDH (Ed25519 → X25519 + HKDF) for key agreement.
 */
import type { EnboxPlatformAgent } from './types/agent.js';
import type { RequireOnly } from '@enbox/common';
import type { DidDocument, PortableDid } from '@enbox/dids';
import type { DwnDataEncodedRecordsWriteMessage, DwnPermissionScope, DwnProtocolDefinition } from './types/dwn.js';
/**
 * The protocols of permissions requested, along with the definition and permission scopes for each protocol.
 */
export type ConnectPermissionRequest = {
    /**
     * The definition of the protocol the permissions are being requested for.
     * In the event that the protocol is not already installed, the wallet will install this given protocol definition.
     */
    protocolDefinition: DwnProtocolDefinition;
    /** The scope of the permissions being requested for the given protocol */
    permissionScopes: DwnPermissionScope[];
};
import { type BearerDid } from '@enbox/dids';
/**
 * Pushed to the connect server so the wallet can retrieve it later.
 * The request is encrypted (JWE) before being pushed.
 *
 * Inspired by RFC 9126 (Pushed Authorization Requests).
 */
export type ConnectPushedRequest = {
    /** The encrypted JWE containing the signed {@link EnboxConnectRequest} JWT. */
    request: string;
};
/**
 * Returned by the connect server after a {@link ConnectPushedRequest}.
 * Contains a URI the wallet uses to fetch the encrypted request,
 * and the TTL before it expires.
 */
export type ConnectPushedResponse = {
    /** URI where the wallet can fetch the encrypted auth request. */
    request_uri: string;
    /** Seconds until the request expires. */
    expires_in: number;
};
/**
 * A connect request from an app to a wallet, asking for DWN permissions.
 *
 * The app creates this, signs it as a JWT, encrypts it as a JWE, and pushes
 * it to the connect server. The wallet retrieves, decrypts, verifies, and
 * displays it in a consent UI.
 */
export type EnboxConnectRequest = {
    /** Ephemeral DID (did:jwk) used for ECDH key agreement and request signing. */
    clientDid: string;
    /** Human-readable name of the requesting application, shown in the consent UI. */
    appName: string;
    /** DWN protocols and permission scopes being requested. */
    permissionRequests: ConnectPermissionRequest[];
    /** Anti-replay nonce (random base64url). */
    nonce: string;
    /** State correlator for matching request to response (random base64url). */
    state: string;
    /** URL where the wallet should POST the encrypted response. */
    callbackUrl: string;
    /** Response mode — always `direct_post` (wallet POSTs response to callbackUrl). */
    responseMode: 'direct_post';
    /** Supported DID methods for the connected identity. */
    supportedDidMethods: string[];
};
/**
 * A connect response from a wallet, granting DWN permissions.
 *
 * The wallet creates this after user consent, signs it as a JWT with the
 * delegate DID, encrypts it via ECDH, and POSTs it to the connect server.
 * The app retrieves, decrypts (using ECDH + optional PIN), and verifies it.
 */
export type EnboxConnectResponse = {
    /** The wallet owner's real DID that authorised the delegation. */
    providerDid: string;
    /** The newly created delegate DID identifier. */
    delegateDid: string;
    /** Audience — must match the `clientDid` from the request. */
    aud: string;
    /** Issued-at timestamp (Unix seconds). */
    iat: number;
    /** Expiration timestamp (Unix seconds). */
    exp: number;
    /** Echo of the request nonce. */
    nonce?: string;
    /** DWN permission grant messages (serialised RecordsWrite with encoded data). */
    delegateGrants: DwnDataEncodedRecordsWriteMessage[];
    /** The delegate DID's full portable form, including private keys. */
    delegatePortableDid: PortableDid;
};
/** The connect server endpoint types. */
export type ConnectEndpoint = 'pushedAuthorizationRequest' | 'authorize' | 'callback' | 'token';
/**
 * Builds the URL for a connect server endpoint.
 *
 * @param options.baseURL - The connect server base URL (e.g. `http://localhost:3000/connect/`)
 * @param options.endpoint - The endpoint type
 * @param options.authParam - Required for `authorize` endpoint (the request ID)
 * @param options.tokenParam - Required for `token` endpoint (the state value)
 */
declare function buildConnectUrl({ baseURL, endpoint, authParam, tokenParam, }: {
    baseURL: string;
    endpoint: ConnectEndpoint;
    authParam?: string;
    tokenParam?: string;
}): string;
/** Signs an object as a JWT using an Ed25519 DID key. */
declare function signJwt({ did, data, }: {
    did: BearerDid;
    data: Record<string, unknown>;
}): Promise<string>;
/** Verifies a JWT signature using the DID in the `kid` header. Returns the parsed payload. */
declare function verifyJwt({ jwt }: {
    jwt: string;
}): Promise<Record<string, unknown>>;
/** Encrypts the connect request JWT with a symmetric key (shared via QR code or deep link). */
declare function encryptRequest({ jwt, encryptionKey, }: {
    jwt: string;
    encryptionKey: Uint8Array;
}): Promise<string>;
/** Decrypts an encrypted connect request JWE using the symmetric key from the QR/deep link. */
declare function decryptRequest({ jwe, encryptionKey, }: {
    jwe: string;
    encryptionKey: string;
}): Promise<string>;
/** Derives a shared ECDH key for encrypting/decrypting the connect response. */
declare function deriveSharedKey(privateKeyDid: BearerDid, publicKeyDid: DidDocument): Promise<Uint8Array>;
/**
 * Encrypts the connect response JWT.
 *
 * For remote (relay-mediated) flows, `pin` is required — it is added to the
 * AAD to prevent MITM attacks via the untrusted relay.
 *
 * For local (same-device) flows, `pin` may be omitted — the ECDH encryption
 * alone is sufficient when there is no untrusted intermediary.
 */
declare function encryptResponse({ jwt, encryptionKey, delegateDidKeyId, pin, }: {
    jwt: string;
    encryptionKey: Uint8Array;
    delegateDidKeyId: string;
    pin?: string;
}): Promise<string>;
/**
 * Decrypts the connect response JWE using ECDH + optional PIN.
 *
 * @param clientDid - The ephemeral DID used at connect initiation (for ECDH).
 * @param jwe - The encrypted response JWE.
 * @param pin - The PIN entered by the user (required for remote flows, omit for local).
 */
declare function decryptResponse(clientDid: BearerDid, jwe: string, pin?: string): Promise<string>;
/** Creates an {@link EnboxConnectRequest}. */
declare function createConnectRequest(options: RequireOnly<EnboxConnectRequest, 'clientDid' | 'callbackUrl' | 'permissionRequests' | 'appName'>): Promise<EnboxConnectRequest>;
/**
 * Fetches an encrypted connect request from the authorize endpoint
 * and decrypts it using the encryption key from the QR/deep link.
 */
declare function getConnectRequest(requestUri: string, encryptionKey: string): Promise<EnboxConnectRequest>;
/** Creates an {@link EnboxConnectResponse} with timestamps. */
declare function createConnectResponse(options: RequireOnly<EnboxConnectResponse, 'providerDid' | 'delegateDid' | 'aud' | 'delegateGrants' | 'delegatePortableDid'>): Promise<EnboxConnectResponse>;
/**
 * Creates permission grants that assign the requested scopes to a delegate DID.
 */
declare function createPermissionGrants(selectedDid: string, delegateBearerDid: BearerDid, agent: EnboxPlatformAgent, scopes: DwnPermissionScope[]): Promise<DwnDataEncodedRecordsWriteMessage[]>;
/**
 * Executes the full wallet-side (provider) flow:
 * 1. Creates a delegate DID
 * 2. Installs requested protocols
 * 3. Creates permission grants
 * 4. Builds, signs, and encrypts the response
 * 5. POSTs the encrypted response to the callback URL
 *
 * @param selectedDid - The provider's DID that is granting access.
 * @param connectRequest - The decoded connect request from the app.
 * @param pin - The PIN for response encryption AAD (required for remote flows).
 * @param agent - The agent instance for DWN operations.
 */
declare function submitConnectResponse(selectedDid: string, connectRequest: EnboxConnectRequest, pin: string | undefined, agent: EnboxPlatformAgent): Promise<void>;
export declare const EnboxConnectProtocol: {
    buildConnectUrl: typeof buildConnectUrl;
    signJwt: typeof signJwt;
    verifyJwt: typeof verifyJwt;
    encryptRequest: typeof encryptRequest;
    decryptRequest: typeof decryptRequest;
    encryptResponse: typeof encryptResponse;
    decryptResponse: typeof decryptResponse;
    deriveSharedKey: typeof deriveSharedKey;
    createConnectRequest: typeof createConnectRequest;
    getConnectRequest: typeof getConnectRequest;
    createConnectResponse: typeof createConnectResponse;
    createPermissionGrants: typeof createPermissionGrants;
    submitConnectResponse: typeof submitConnectResponse;
};
export {};
//# sourceMappingURL=enbox-connect-protocol.d.ts.map