@awiki/anp-typescript-sdk 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,790 @@
+declare class ANPError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string, cause?: Error);
+}
+declare class CryptoError extends ANPError {
+    constructor(message: string, cause?: Error);
+}
+declare class AuthenticationError extends ANPError {
+    constructor(message: string, cause?: Error);
+}
+declare class ProofError extends ANPError {
+    constructor(message: string, cause?: Error);
+}
+declare class NetworkError extends ANPError {
+    readonly statusCode?: number | undefined;
+    constructor(message: string, statusCode?: number | undefined, cause?: Error);
+}
+declare class WnsError extends ANPError {
+    constructor(message: string, code?: string, cause?: Error);
+}
+declare class HandleValidationError extends WnsError {
+    constructor(message: string);
+}
+declare class HandleResolutionError extends WnsError {
+    readonly statusCode?: number | undefined;
+    constructor(message: string, statusCode?: number | undefined, cause?: Error);
+}
+declare class HandleNotFoundError extends HandleResolutionError {
+    constructor(message: string);
+}
+declare class HandleGoneError extends HandleResolutionError {
+    constructor(message: string);
+}
+declare class HandleMovedError extends HandleResolutionError {
+    readonly redirectUrl: string;
+    constructor(message: string, redirectUrl?: string);
+}
+declare class HandleBindingError extends WnsError {
+    constructor(message: string);
+}
+declare class WbaUriParseError extends WnsError {
+    constructor(message: string);
+}
+
+type KeyType = 'secp256k1' | 'secp256r1' | 'ed25519' | 'x25519';
+type PrivateKeyInput = string | PrivateKeyMaterial;
+type PublicKeyInput = string | PublicKeyMaterial;
+interface PrivateKeyMaterial {
+    type: KeyType;
+    bytes: Uint8Array;
+}
+interface PublicKeyMaterial {
+    type: KeyType;
+    bytes: Uint8Array;
+}
+interface GeneratedKeyPairPem {
+    privateKeyPem: string;
+    publicKeyPem: string;
+}
+
+type JsonPrimitive = null | boolean | number | string;
+type JsonValue = JsonPrimitive | JsonObject | JsonValue[];
+interface JsonObject {
+    [key: string]: JsonValue;
+}
+
+declare enum DidProfile {
+    E1 = "e1",
+    K1 = "k1",
+    PlainLegacy = "plain_legacy"
+}
+declare enum AuthMode {
+    HttpSignatures = "http_signatures",
+    LegacyDidWba = "legacy_didwba",
+    Auto = "auto"
+}
+interface ProofRecord {
+    type: string;
+    created: string;
+    verificationMethod: string;
+    proofPurpose: string;
+    proofValue: string;
+    cryptosuite?: string;
+    domain?: string;
+    challenge?: string;
+}
+interface VerificationMethodRecord {
+    id: string;
+    type: string;
+    controller: string;
+    publicKeyJwk?: JsonWebKey;
+    publicKeyMultibase?: string;
+    publicKeyBase58?: string;
+}
+interface ServiceRecord {
+    id: string;
+    type: string;
+    serviceEndpoint: unknown;
+    serviceDid?: string;
+    profiles?: string[];
+    securityProfiles?: string[];
+    accepts?: string[];
+    priority?: number | string;
+    authSchemes?: string[];
+}
+interface AnpMessageServiceOptions {
+    fragment?: string;
+    serviceDid?: string;
+    profiles?: string[];
+    securityProfiles?: string[];
+    accepts?: string[];
+    priority?: number | string;
+    authSchemes?: string[];
+}
+interface DidDocument {
+    '@context': string[];
+    id: string;
+    verificationMethod: VerificationMethodRecord[];
+    authentication: Array<string | VerificationMethodRecord>;
+    assertionMethod?: Array<string | VerificationMethodRecord>;
+    keyAgreement?: Array<string | VerificationMethodRecord>;
+    service?: ServiceRecord[];
+    proof?: ProofRecord;
+}
+interface DidDocumentOptions {
+    port?: number;
+    pathSegments?: string[];
+    agentDescriptionUrl?: string;
+    services?: Array<ServiceRecord | JsonObject>;
+    proofPurpose?: string;
+    verificationMethod?: string;
+    domain?: string;
+    challenge?: string;
+    created?: string;
+    enableE2ee?: boolean;
+    didProfile?: DidProfile;
+}
+interface DidDocumentBundle {
+    didDocument: DidDocument;
+    keys: Record<string, GeneratedKeyPairPem>;
+}
+interface ParsedAuthHeader {
+    did: string;
+    nonce: string;
+    timestamp: string;
+    verificationMethod: string;
+    signature: string;
+    version: string;
+}
+interface LegacyAuthOptions {
+    nonce?: string;
+    timestamp?: string;
+}
+interface DidResolutionOptions {
+    timeoutSeconds?: number;
+    verifySsl?: boolean;
+    baseUrlOverride?: string;
+    headers?: Record<string, string>;
+}
+type DidResolver = (did: string) => DidDocument | null | undefined | Promise<DidDocument | null | undefined>;
+interface HttpSignatureOptions {
+    keyid?: string;
+    nonce?: string;
+    created?: number;
+    expires?: number;
+    coveredComponents?: string[];
+}
+interface FederatedVerificationOptions {
+    senderDidDocument?: DidDocument;
+    serviceDidDocument?: DidDocument;
+    serviceId?: string;
+    serviceEndpoint?: string;
+    verifySenderDidProof?: boolean;
+    verifyServiceDidProof?: boolean;
+    didResolutionOptions?: DidResolutionOptions;
+}
+interface SignatureMetadata {
+    label: string;
+    components: string[];
+    keyid: string;
+    nonce?: string;
+    created: number;
+    expires?: number;
+}
+interface FederatedVerificationResult {
+    senderDid: string;
+    serviceDid: string;
+    serviceId: string;
+    signatureMetadata: SignatureMetadata;
+}
+
+declare class VerificationMethod {
+    readonly id: string;
+    readonly methodType: string;
+    readonly publicKey: PublicKeyMaterial;
+    constructor(id: string, methodType: string, publicKey: PublicKeyMaterial);
+    verifySignature(content: Uint8Array, signature: string): boolean;
+    encodeSignature(signatureBytes: Uint8Array): string;
+}
+declare function createVerificationMethod(method: VerificationMethodRecord): VerificationMethod;
+declare function extractPublicKey(method: VerificationMethodRecord): PublicKeyMaterial;
+
+declare const VM_KEY_AUTH = "key-1";
+declare const VM_KEY_E2EE_SIGNING = "key-2";
+declare const VM_KEY_E2EE_AGREEMENT = "key-3";
+declare const ANP_MESSAGE_SERVICE_TYPE = "ANPMessageService";
+declare function resolveDidWbaDocument(did: string, verifyProof?: boolean, options?: DidResolutionOptions): Promise<DidDocument>;
+declare function buildAnpMessageService(didOrServiceRef: string, serviceEndpoint: string, options?: AnpMessageServiceOptions): ServiceRecord;
+declare function buildAgentMessageService(didOrServiceRef: string, serviceEndpoint: string, options?: AnpMessageServiceOptions): ServiceRecord;
+declare function buildGroupMessageService(didOrServiceRef: string, serviceEndpoint: string, options?: AnpMessageServiceOptions): ServiceRecord;
+declare function createDidWbaDocument(hostname: string, options?: DidDocumentOptions): DidDocumentBundle;
+declare function createDidWbaDocumentWithKeyBinding(hostname: string, options?: DidDocumentOptions): DidDocumentBundle;
+declare function computeJwkFingerprint(publicKeyInput: PublicKeyInput): string;
+declare function computeMultikeyFingerprint(publicKeyInput: PublicKeyInput): string;
+declare function verifyDidKeyBinding(did: string, bindingMaterial: VerificationMethodRecord | PublicKeyMaterial | string): boolean;
+declare function validateDidDocumentBinding(didDocument: DidDocument, verifyProof?: boolean): boolean;
+declare function generateAuthHeader(didDocument: DidDocument, serviceDomain: string, privateKeyInput: string, version?: string, options?: LegacyAuthOptions): string;
+declare function generateAuthJson(didDocument: DidDocument, serviceDomain: string, privateKeyInput: string, version?: string, options?: LegacyAuthOptions): string;
+declare function extractAuthHeaderParts(authHeader: string): ParsedAuthHeader;
+declare function verifyAuthHeaderSignature(authHeader: string, didDocument: DidDocument, serviceDomain: string): boolean;
+declare function verifyAuthJsonSignature(authJson: string, didDocument: DidDocument, serviceDomain: string): boolean;
+declare function findVerificationMethod(didDocument: DidDocument, verificationMethodId: string): VerificationMethodRecord | undefined;
+declare function isAuthenticationAuthorized(didDocument: DidDocument, verificationMethodId: string): boolean;
+declare function isAssertionMethodAuthorized(didDocument: DidDocument, verificationMethodId: string): boolean;
+
+declare function resolveDidDocument(did: string, verifyProof?: boolean, options?: DidResolutionOptions): Promise<DidDocument>;
+
+declare function buildContentDigest(body: Uint8Array | string): string;
+declare function verifyContentDigest(body: Uint8Array | string, contentDigest: string): boolean;
+declare function generateHttpSignatureHeaders(didDocument: DidDocument, requestUrl: string, requestMethod: string, privateKeyInput: PrivateKeyInput, headers?: Record<string, string>, body?: Uint8Array | string, options?: HttpSignatureOptions): Record<string, string>;
+declare function extractSignatureMetadata(headers: Record<string, string>): SignatureMetadata;
+declare function verifyHttpMessageSignature(didDocument: DidDocument, requestMethod: string, requestUrl: string, headers: Record<string, string>, body?: Uint8Array | string): SignatureMetadata;
+
+declare class DIDWbaAuthHeader {
+    private readonly didDocumentPath;
+    private readonly privateKeyPath;
+    private readonly authMode;
+    private didDocumentCache?;
+    private readonly tokens;
+    constructor(didDocumentPath: string, privateKeyPath: string, authMode?: AuthMode);
+    getAuthHeaders(serverUrl: string, forceNew?: boolean, method?: string, headers?: Record<string, string>, body?: Uint8Array | string): Promise<Record<string, string>>;
+    getAuthHeader(serverUrl: string, forceNew?: boolean, method?: string, headers?: Record<string, string>, body?: Uint8Array | string): Promise<Record<string, string>>;
+    updateToken(serverUrl: string, headers: Record<string, string>): string | undefined;
+    clearToken(serverUrl: string): void;
+    clearAllTokens(): void;
+    shouldRetryAfter401(responseHeaders: Record<string, string>): boolean;
+    getChallengeAuthHeaders(serverUrl: string, responseHeaders: Record<string, string>, method?: string, headers?: Record<string, string>, body?: Uint8Array | string): Promise<Record<string, string>>;
+    getChallengeAuthHeader(serverUrl: string, responseHeaders: Record<string, string>, method?: string, headers?: Record<string, string>, body?: Uint8Array | string): Promise<Record<string, string>>;
+    private loadDidDocument;
+}
+
+interface DidWbaVerifierConfig {
+    jwtPrivateKey?: string;
+    jwtPublicKey?: string;
+    jwtAlgorithm?: string;
+    accessTokenExpireMinutes?: number;
+    nonceExpirationMinutes?: number;
+    timestampExpirationMinutes?: number;
+    allowedDomains?: string[];
+    allowHttpSignatures?: boolean;
+    allowLegacyDidwba?: boolean;
+    emitAuthenticationInfoHeader?: boolean;
+    emitLegacyAuthorizationHeader?: boolean;
+    requireNonceForHttpSignatures?: boolean;
+    didResolutionOptions?: DidResolutionOptions;
+    didResolver?: DidResolver;
+    externalNonceValidator?: (did: string, nonce: string) => boolean | Promise<boolean>;
+}
+interface VerificationSuccess {
+    did: string;
+    authScheme: string;
+    responseHeaders: Record<string, string>;
+    accessToken?: string;
+    tokenType?: 'bearer';
+}
+declare class DidWbaVerifierError extends Error {
+    readonly statusCode: number;
+    readonly headers: Record<string, string>;
+    constructor(message: string, statusCode?: number, headers?: Record<string, string>);
+}
+declare class DidWbaVerifier {
+    private readonly config;
+    private readonly usedNonces;
+    constructor(config?: DidWbaVerifierConfig);
+    verifyRequest(method: string, url: string, headers: Record<string, string>, body?: Uint8Array | string | null, domain?: string): Promise<VerificationSuccess>;
+    verifyRequestWithDidDocument(method: string, url: string, headers: Record<string, string>, didDocument: DidDocument, body?: Uint8Array | string | null, domain?: string): Promise<VerificationSuccess>;
+    private verifyRequestWithOptionalDidDocument;
+    private handleHttpSignatureAuth;
+    private handleLegacyDidAuth;
+    private handleBearerAuth;
+    private createAccessToken;
+    private buildSuccessResult;
+    private verifyLegacyTimestamp;
+    private verifyHttpSignatureTimeWindow;
+    private isValidServerNonce;
+    private resolveDidDocument;
+    private validateAllowedDomain;
+    private challengeError;
+}
+
+declare function verifyFederatedHttpRequest(senderDid: string, requestMethod: string, requestUrl: string, headers: Record<string, string>, body?: Uint8Array | string, options?: FederatedVerificationOptions): Promise<FederatedVerificationResult>;
+
+declare const didDocuments: {
+    ANP_MESSAGE_SERVICE_TYPE: string;
+    buildAnpMessageService: typeof buildAnpMessageService;
+    buildAgentMessageService: typeof buildAgentMessageService;
+    buildGroupMessageService: typeof buildGroupMessageService;
+    create: typeof createDidWbaDocument;
+    createWithKeyBinding: typeof createDidWbaDocumentWithKeyBinding;
+    resolve: typeof resolveDidDocument;
+    validateBinding: typeof validateDidDocumentBinding;
+    verifyKeyBinding: typeof verifyDidKeyBinding;
+};
+declare const legacyAuth: {
+    createHeader: typeof generateAuthHeader;
+    createPayload: typeof generateAuthJson;
+    parseHeader: typeof extractAuthHeaderParts;
+    verifyHeader: typeof verifyAuthHeaderSignature;
+    verifyPayload: typeof verifyAuthJsonSignature;
+};
+declare const httpSignatures: {
+    buildContentDigest: typeof buildContentDigest;
+    verifyContentDigest: typeof verifyContentDigest;
+    createHeaders: typeof generateHttpSignatureHeaders;
+    verifyMessage: typeof verifyHttpMessageSignature;
+    parseMetadata: typeof extractSignatureMetadata;
+};
+declare const authentication: {
+    didDocuments: {
+        ANP_MESSAGE_SERVICE_TYPE: string;
+        buildAnpMessageService: typeof buildAnpMessageService;
+        buildAgentMessageService: typeof buildAgentMessageService;
+        buildGroupMessageService: typeof buildGroupMessageService;
+        create: typeof createDidWbaDocument;
+        createWithKeyBinding: typeof createDidWbaDocumentWithKeyBinding;
+        resolve: typeof resolveDidDocument;
+        validateBinding: typeof validateDidDocumentBinding;
+        verifyKeyBinding: typeof verifyDidKeyBinding;
+    };
+    legacyAuth: {
+        createHeader: typeof generateAuthHeader;
+        createPayload: typeof generateAuthJson;
+        parseHeader: typeof extractAuthHeaderParts;
+        verifyHeader: typeof verifyAuthHeaderSignature;
+        verifyPayload: typeof verifyAuthJsonSignature;
+    };
+    httpSignatures: {
+        buildContentDigest: typeof buildContentDigest;
+        verifyContentDigest: typeof verifyContentDigest;
+        createHeaders: typeof generateHttpSignatureHeaders;
+        verifyMessage: typeof verifyHttpMessageSignature;
+        parseMetadata: typeof extractSignatureMetadata;
+    };
+    federation: {
+        verifyRequest: typeof verifyFederatedHttpRequest;
+    };
+    DidAuthHeaders: typeof DIDWbaAuthHeader;
+    RequestVerifier: typeof DidWbaVerifier;
+};
+
+declare const PROOF_TYPE_SECP256K1 = "EcdsaSecp256k1Signature2019";
+declare const PROOF_TYPE_ED25519 = "Ed25519Signature2020";
+declare const PROOF_TYPE_DATA_INTEGRITY = "DataIntegrityProof";
+declare const CRYPTOSUITE_EDDSA_JCS_2022 = "eddsa-jcs-2022";
+declare const CRYPTOSUITE_DIDWBA_SECP256K1_2025 = "didwba-jcs-ecdsa-secp256k1-2025";
+interface ProofGenerationOptions {
+    proofPurpose?: string;
+    proofType?: string;
+    cryptosuite?: string;
+    created?: string;
+    domain?: string;
+    challenge?: string;
+}
+interface ProofVerificationOptions {
+    expectedPurpose?: string;
+    expectedDomain?: string;
+    expectedChallenge?: string;
+}
+interface ProofObject {
+    type: string;
+    created: string;
+    verificationMethod: string;
+    proofPurpose: string;
+    proofValue: string;
+    cryptosuite?: string;
+    domain?: string;
+    challenge?: string;
+}
+declare function generateW3cProof<T extends object>(document: T, privateKeyInput: PrivateKeyInput, verificationMethod: string, options?: ProofGenerationOptions): T & {
+    proof: ProofObject;
+};
+declare function verifyW3cProof(document: object, publicKeyInput: PublicKeyInput, options?: ProofVerificationOptions): boolean;
+declare function verifyW3cProofDetailed(document: object, publicKeyInput: PublicKeyInput, options?: ProofVerificationOptions): void;
+
+declare const IM_PROOF_DEFAULT_COMPONENTS: readonly ["@method", "@target-uri", "content-digest"];
+declare const IM_PROOF_RELATION_AUTHENTICATION: "authentication";
+declare const IM_PROOF_RELATION_ASSERTION_METHOD: "assertionMethod";
+type ImProofVerificationRelationship = typeof IM_PROOF_RELATION_AUTHENTICATION | typeof IM_PROOF_RELATION_ASSERTION_METHOD;
+interface ImProof {
+    contentDigest: string;
+    signatureInput: string;
+    signature: string;
+}
+interface ParsedImSignatureInput {
+    label: string;
+    components: string[];
+    signatureParams: string;
+    keyid: string;
+    nonce?: string;
+    created?: number;
+    expires?: number;
+}
+interface ImProofGenerationOptions {
+    label?: string;
+    components?: string[];
+    created?: number;
+    expires?: number;
+    nonce?: string;
+}
+interface ImProofVerificationResult {
+    parsedSignatureInput: ParsedImSignatureInput;
+    verificationMethod: VerificationMethodRecord;
+}
+interface ImProofVerificationTarget {
+    didDocument?: DidDocument;
+    verificationMethod?: VerificationMethodRecord;
+    verificationRelationship?: ImProofVerificationRelationship;
+}
+declare function buildImContentDigest(payload: Uint8Array | string): string;
+declare function verifyImContentDigest(payload: Uint8Array | string, contentDigest: string): boolean;
+declare function buildImSignatureInput(keyid: string, options?: ImProofGenerationOptions): string;
+declare function parseImSignatureInput(value: string): ParsedImSignatureInput;
+declare function encodeImSignature(signatureBytes: Uint8Array, label?: string): string;
+declare function decodeImSignature(signature: string): {
+    label?: string;
+    signatureBytes: Uint8Array;
+};
+declare function generateImProof(payload: Uint8Array | string, signatureBase: Uint8Array | string, privateKeyInput: PrivateKeyInput, keyid: string, options?: ImProofGenerationOptions): ImProof;
+declare function verifyImProof(proof: ImProof, payload: Uint8Array | string, signatureBase: Uint8Array | string, verificationTarget: ImProofVerificationTarget, expectedSignerDid?: string): ImProofVerificationResult;
+
+declare const imProof_IM_PROOF_DEFAULT_COMPONENTS: typeof IM_PROOF_DEFAULT_COMPONENTS;
+declare const imProof_IM_PROOF_RELATION_ASSERTION_METHOD: typeof IM_PROOF_RELATION_ASSERTION_METHOD;
+declare const imProof_IM_PROOF_RELATION_AUTHENTICATION: typeof IM_PROOF_RELATION_AUTHENTICATION;
+type imProof_ImProof = ImProof;
+type imProof_ImProofGenerationOptions = ImProofGenerationOptions;
+type imProof_ImProofVerificationRelationship = ImProofVerificationRelationship;
+type imProof_ImProofVerificationResult = ImProofVerificationResult;
+type imProof_ImProofVerificationTarget = ImProofVerificationTarget;
+type imProof_ParsedImSignatureInput = ParsedImSignatureInput;
+declare const imProof_buildImContentDigest: typeof buildImContentDigest;
+declare const imProof_buildImSignatureInput: typeof buildImSignatureInput;
+declare const imProof_decodeImSignature: typeof decodeImSignature;
+declare const imProof_encodeImSignature: typeof encodeImSignature;
+declare const imProof_generateImProof: typeof generateImProof;
+declare const imProof_parseImSignatureInput: typeof parseImSignatureInput;
+declare const imProof_verifyImContentDigest: typeof verifyImContentDigest;
+declare const imProof_verifyImProof: typeof verifyImProof;
+declare namespace imProof {
+  export { imProof_IM_PROOF_DEFAULT_COMPONENTS as IM_PROOF_DEFAULT_COMPONENTS, imProof_IM_PROOF_RELATION_ASSERTION_METHOD as IM_PROOF_RELATION_ASSERTION_METHOD, imProof_IM_PROOF_RELATION_AUTHENTICATION as IM_PROOF_RELATION_AUTHENTICATION, type imProof_ImProof as ImProof, type imProof_ImProofGenerationOptions as ImProofGenerationOptions, type imProof_ImProofVerificationRelationship as ImProofVerificationRelationship, type imProof_ImProofVerificationResult as ImProofVerificationResult, type imProof_ImProofVerificationTarget as ImProofVerificationTarget, type imProof_ParsedImSignatureInput as ParsedImSignatureInput, imProof_buildImContentDigest as buildImContentDigest, imProof_buildImSignatureInput as buildImSignatureInput, imProof_decodeImSignature as decodeImSignature, imProof_encodeImSignature as encodeImSignature, imProof_generateImProof as generateImProof, imProof_parseImSignatureInput as parseImSignatureInput, imProof_verifyImContentDigest as verifyImContentDigest, imProof_verifyImProof as verifyImProof };
+}
+
+declare const proof: {
+    create: typeof generateW3cProof;
+    verify: typeof verifyW3cProof;
+    verifyDetailed: typeof verifyW3cProofDetailed;
+    im: typeof imProof;
+};
+
+type BindingGeneration = string & {
+    readonly __bindingGeneration: unique symbol;
+};
+declare function canonicalizeBindingGeneration(value: unknown): BindingGeneration;
+declare function compareBindingGenerations(current: BindingGeneration | string, previous: BindingGeneration | string): number;
+
+declare const ANP_HANDLE_SERVICE_TYPE = "ANPHandleService";
+declare enum HandleStatus {
+    Active = "active",
+    Suspended = "suspended",
+    Revoked = "revoked"
+}
+declare enum SubjectType {
+    Person = "person",
+    Agent = "agent",
+    Group = "group",
+    Organization = "organization",
+    Service = "service",
+    Application = "application",
+    Unknown = "unknown"
+}
+interface DIDSubjectProfile {
+    type?: string;
+    subject_did: string;
+    subject_type?: SubjectType;
+    handle?: string;
+    display_name?: string;
+    description?: string;
+    avatar_uri?: string;
+    profile_uri?: string;
+    discoverability?: string;
+    labels?: Record<string, unknown>;
+    updated?: string;
+    versionId?: string;
+    ttl?: number;
+    proof?: Record<string, unknown>;
+}
+interface HandleResolutionDocument {
+    handle: string;
+    did: string;
+    status: HandleStatus;
+    binding_generation: BindingGeneration;
+    updated?: string;
+    versionId?: string;
+    ttl?: number;
+    profile?: DIDSubjectProfile;
+}
+interface HandleServiceEntry {
+    id: string;
+    type: string;
+    serviceEndpoint: string;
+}
+interface ParsedWbaUri {
+    localPart: string;
+    domain: string;
+    handle: string;
+    originalUri: string;
+}
+interface ResolveHandleOptions {
+    timeoutSeconds?: number;
+    verifySsl?: boolean;
+    baseUrlOverride?: string;
+}
+interface BindingVerificationOptions {
+    didDocument?: DidDocument;
+    resolutionOptions?: ResolveHandleOptions;
+    didResolutionOptions?: DidResolutionOptions;
+}
+interface BindingVerificationResult {
+    isValid: boolean;
+    handle: string;
+    did: string;
+    bindingGeneration?: BindingGeneration;
+    forwardVerified: boolean;
+    reverseVerified: boolean;
+    errorMessage?: string;
+}
+
+declare function validateLocalPart(localPart: string): boolean;
+declare function validateHandle(handle: string): [string, string];
+declare function normalizeHandle(handle: string): string;
+declare function parseWbaUri(uri: string): ParsedWbaUri;
+declare function buildResolutionUrl(localPart: string, domain: string): string;
+declare function buildWbaUri(localPart: string, domain: string): string;
+
+declare function resolveHandle(handle: string, options?: ResolveHandleOptions): Promise<HandleResolutionDocument>;
+declare function resolveHandleFromUri(wbaUri: string, options?: ResolveHandleOptions): Promise<HandleResolutionDocument>;
+
+declare function verifyHandleBinding(handle: string, options?: BindingVerificationOptions): Promise<BindingVerificationResult>;
+declare function buildHandleServiceEntry(did: string, localPart: string, domain: string): HandleServiceEntry;
+declare function extractHandleServiceFromDidDocument(didDocument: DidDocument): HandleServiceEntry[];
+
+declare const wns: {
+    validateLocalPart: typeof validateLocalPart;
+    validateHandle: typeof validateHandle;
+    normalizeHandle: typeof normalizeHandle;
+    parseUri: typeof parseWbaUri;
+    buildResolutionUrl: typeof buildResolutionUrl;
+    buildUri: typeof buildWbaUri;
+    resolveHandle: typeof resolveHandle;
+    resolveUri: typeof resolveHandleFromUri;
+    verifyBinding: typeof verifyHandleBinding;
+    createHandleServiceEntry: typeof buildHandleServiceEntry;
+    extractHandleServices: typeof extractHandleServiceFromDidDocument;
+    canonicalizeBindingGeneration: typeof canonicalizeBindingGeneration;
+    compareBindingGenerations: typeof compareBindingGenerations;
+};
+
+/** Public, high-level AWiki IM client types. */
+declare const AWIKI_IM_ID: unique symbol;
+/** String identifier that remains nominally distinct across IM domains. */
+type AwikiImId<Kind extends string> = string & {
+    readonly [AWIKI_IM_ID]: Kind;
+};
+/** Stable AWiki decentralized identifier. */
+type AwikiDid = AwikiImId<'did'>;
+/** Validated AWiki handle. */
+type AwikiHandle = AwikiImId<'handle'>;
+/** Stable conversation identifier. */
+type AwikiConversationId = AwikiImId<'conversation'>;
+/** Stable message identifier. */
+type AwikiMessageId = AwikiImId<'message'>;
+/** Stable attachment identifier. */
+type AwikiAttachmentId = AwikiImId<'attachment'>;
+/** Opaque pagination cursor returned by AWiki. */
+type AwikiCursor = AwikiImId<'cursor'>;
+/** Persisted identity metadata. Private keys and access tokens are excluded. */
+interface AwikiIdentity {
+    readonly handle: AwikiHandle;
+    readonly did: AwikiDid;
+    readonly registeredAt: number;
+}
+/** Request for one registration verification code. */
+interface SendRegistrationOtpRequest {
+    readonly handle: string;
+    readonly phone: string;
+}
+/** Server-issued registration challenge metadata. */
+interface SendRegistrationOtpResult {
+    readonly retryAfterSeconds: number;
+    readonly retryAt: string;
+}
+/** Complete a new identity registration from a verified phone challenge. */
+interface RegisterIdentityRequest {
+    readonly handle: string;
+    readonly phone: string;
+    readonly otp: string;
+}
+/** Existing direct-message conversation. */
+interface AwikiDirectConversation {
+    readonly kind: 'direct';
+    readonly id: AwikiConversationId;
+    readonly peerDid: AwikiDid;
+    readonly peerHandle?: AwikiHandle;
+    readonly title: string;
+    readonly lastMessageAt?: number;
+}
+/** Existing group conversation. */
+interface AwikiGroupConversation {
+    readonly kind: 'group';
+    readonly id: AwikiConversationId;
+    readonly groupDid: AwikiDid;
+    readonly title: string;
+    readonly lastMessageAt?: number;
+}
+/** Conversation visible to the registered identity. */
+type AwikiConversation = AwikiDirectConversation | AwikiGroupConversation;
+/** Direct-message destination resolved by handle or DID. */
+interface AwikiDirectTarget {
+    readonly kind: 'direct';
+    readonly peer: string;
+}
+/** Existing group destination. Group creation is outside this API. */
+interface AwikiGroupTarget {
+    readonly kind: 'group';
+    readonly group: string;
+}
+/** Destination accepted by text and attachment sends. */
+type AwikiMessageTarget = AwikiDirectTarget | AwikiGroupTarget;
+/** Attachment metadata safe to expose to an IM SDK consumer. */
+interface AwikiAttachment {
+    readonly id: AwikiAttachmentId;
+    readonly fileName: string;
+    readonly mimeType: string;
+    readonly size: number;
+    readonly sha256: string;
+}
+/** Plain text message content. */
+interface AwikiTextContent {
+    readonly kind: 'text';
+    readonly text: string;
+}
+/** Attachment message content. */
+interface AwikiAttachmentContent {
+    readonly kind: 'attachment';
+    readonly attachment: AwikiAttachment;
+    readonly caption?: string;
+}
+/** Content types supported by the first AWiki Harness integration. */
+type AwikiMessageContent = AwikiTextContent | AwikiAttachmentContent;
+/** One direct or group message. */
+interface AwikiMessage {
+    readonly id: AwikiMessageId;
+    readonly conversationId: AwikiConversationId;
+    readonly conversationKind: AwikiConversation['kind'];
+    readonly senderDid: AwikiDid;
+    readonly senderHandle?: AwikiHandle;
+    readonly sentAt: number;
+    readonly outgoing: boolean;
+    readonly content: AwikiMessageContent;
+}
+/** One immutable page from an AWiki collection. */
+interface AwikiPage<Item> {
+    readonly items: readonly Item[];
+    readonly nextCursor?: AwikiCursor;
+    readonly hasMore: boolean;
+}
+/** Common cursor request for conversation and history reads. */
+interface AwikiPageRequest {
+    readonly cursor?: AwikiCursor;
+    readonly limit?: number;
+}
+/** Request for one conversation's message history. */
+interface GetAwikiHistoryRequest extends AwikiPageRequest {
+    readonly conversationId: AwikiConversationId;
+}
+/** Send one plain text message. */
+interface SendAwikiTextRequest {
+    readonly target: AwikiMessageTarget;
+    readonly text: string;
+    readonly idempotencyKey: string;
+}
+/** Bytes and public metadata for one attachment upload. */
+interface AwikiUpload {
+    readonly fileName: string;
+    readonly mimeType: string;
+    readonly bytes: Uint8Array;
+}
+/** Upload and send one attachment message. */
+interface SendAwikiAttachmentRequest {
+    readonly target: AwikiMessageTarget;
+    readonly attachment: AwikiUpload;
+    readonly caption?: string;
+    readonly idempotencyKey: string;
+}
+/** Download request for one attachment visible to the current identity. */
+interface DownloadAwikiAttachmentRequest {
+    readonly attachmentId: AwikiAttachmentId;
+    readonly messageId: AwikiMessageId;
+}
+/** Verified attachment bytes and public metadata. */
+interface DownloadedAwikiAttachment {
+    readonly attachment: AwikiAttachment;
+    readonly bytes: Uint8Array;
+}
+/** Stable public error categories normalized from AWiki services. */
+type AwikiImErrorCode = 'not-registered' | 'already-registered' | 'invalid-request' | 'invalid-otp' | 'challenge-expired' | 'handle-unavailable' | 'not-found' | 'forbidden' | 'conflict' | 'rate-limited' | 'network' | 'remote';
+/** Options for the Node.js AWiki IM client. */
+interface AwikiImClientOptions {
+    readonly userServiceUrl: string;
+    /** Handle domain administered by the User Service; it need not equal the service URL host. */
+    readonly userServiceDomain: string;
+    readonly messageServiceUrl: string;
+    /** Public Message Service base URL advertised in the identity DID document. */
+    readonly messageServicePublicUrl: string;
+    /** Authoritative Home Message Service DID advertised in the registered DID document. */
+    readonly messageServiceDid: string;
+    /** Exact HTTPS origins permitted for DID discovery, attachment service endpoints, and objects. */
+    readonly allowedAttachmentOrigins: readonly string[];
+    /** Maximum attachment size accepted for both upload and download. */
+    readonly attachmentMaxBytes: number;
+    /** Permit HTTP loopback URLs only in an explicitly controlled test environment. */
+    readonly allowInsecureLoopbackForTesting?: boolean;
+    readonly statePath: string;
+    readonly fetch?: typeof globalThis.fetch;
+}
+/**
+ * High-level AWiki IM API. Implementations own credentials, request signing,
+ * handle resolution, pagination, idempotency, attachment transfer, and
+ * persistent identity state.
+ */
+interface AwikiImClient {
+    /** Return the persisted default identity without exposing secret material. */
+    getIdentity(): Promise<AwikiIdentity | null>;
+    /** Send one phone verification code for registration. */
+    sendRegistrationOtp(request: SendRegistrationOtpRequest): Promise<SendRegistrationOtpResult>;
+    /** Register and persist the deployment's only identity. */
+    registerIdentity(request: RegisterIdentityRequest): Promise<AwikiIdentity>;
+    /** List direct and existing group conversations. */
+    listConversations(request?: AwikiPageRequest): Promise<AwikiPage<AwikiConversation>>;
+    /** Read one conversation's paginated history. */
+    getHistory(request: GetAwikiHistoryRequest): Promise<AwikiPage<AwikiMessage>>;
+    /** Send one idempotent text message. */
+    sendText(request: SendAwikiTextRequest): Promise<AwikiMessage>;
+    /** Upload and send one idempotent attachment message. */
+    sendAttachment(request: SendAwikiAttachmentRequest): Promise<AwikiMessage>;
+    /** Download and verify one attachment before returning its bytes. */
+    downloadAttachment(request: DownloadAwikiAttachmentRequest): Promise<DownloadedAwikiAttachment>;
+    /** Stop background work and release owned resources. */
+    dispose(): Promise<void>;
+}
+
+/** Create one high-level Node.js AWiki IM client. */
+declare function createAwikiImClient(options: AwikiImClientOptions): AwikiImClient;
+
+/** A stable AWiki IM failure that does not expose credentials or private protocol fields. */
+declare class AwikiImError extends Error {
+    readonly code: AwikiImErrorCode;
+    readonly status?: number | undefined;
+    /**
+     * Create a normalized AWiki IM error.
+     *
+     * @param code Stable category for callers.
+     * @param message Public diagnostic message.
+     * @param options Optional transport status and underlying cause.
+     */
+    constructor(code: AwikiImErrorCode, message: string, status?: number | undefined, options?: {
+        cause?: unknown;
+    });
+}
+
+export { ANPError, ANP_HANDLE_SERVICE_TYPE, ANP_MESSAGE_SERVICE_TYPE, type AnpMessageServiceOptions, AuthMode, AuthenticationError, type AwikiAttachment, type AwikiAttachmentContent, type AwikiAttachmentId, type AwikiConversation, type AwikiConversationId, type AwikiCursor, type AwikiDid, type AwikiDirectConversation, type AwikiDirectTarget, type AwikiGroupConversation, type AwikiGroupTarget, type AwikiHandle, type AwikiIdentity, type AwikiImClient, type AwikiImClientOptions, AwikiImError, type AwikiImErrorCode, type AwikiImId, type AwikiMessage, type AwikiMessageContent, type AwikiMessageId, type AwikiMessageTarget, type AwikiPage, type AwikiPageRequest, type AwikiTextContent, type AwikiUpload, type BindingGeneration, type BindingVerificationOptions, type BindingVerificationResult, CRYPTOSUITE_DIDWBA_SECP256K1_2025, CRYPTOSUITE_EDDSA_JCS_2022, CryptoError, type DIDSubjectProfile, DIDWbaAuthHeader, DIDWbaAuthHeader as DidAuthHeaders, type DidDocument, type DidDocumentBundle, type DidDocumentOptions, DidProfile, type DidResolutionOptions, type DidResolver, DidWbaVerifier, type DidWbaVerifierConfig, DidWbaVerifierError, type DownloadAwikiAttachmentRequest, type DownloadedAwikiAttachment, type FederatedVerificationOptions, type FederatedVerificationResult, type GetAwikiHistoryRequest, HandleBindingError, HandleGoneError, HandleMovedError, HandleNotFoundError, type HandleResolutionDocument, HandleResolutionError, type HandleServiceEntry, HandleStatus, HandleValidationError, type HttpSignatureOptions, IM_PROOF_DEFAULT_COMPONENTS, IM_PROOF_RELATION_ASSERTION_METHOD, IM_PROOF_RELATION_AUTHENTICATION, type ImProof, type ImProofGenerationOptions, type ImProofVerificationRelationship, type ImProofVerificationResult, type ImProofVerificationTarget, type LegacyAuthOptions, NetworkError, PROOF_TYPE_DATA_INTEGRITY, PROOF_TYPE_ED25519, PROOF_TYPE_SECP256K1, type ParsedAuthHeader, type ParsedImSignatureInput, type ParsedWbaUri, ProofError, type ProofGenerationOptions, type ProofObject, type ProofRecord, type ProofVerificationOptions, type RegisterIdentityRequest, DidWbaVerifier as RequestVerifier, DidWbaVerifierError as RequestVerifierError, type ResolveHandleOptions, type SendAwikiAttachmentRequest, type SendAwikiTextRequest, type SendRegistrationOtpRequest, type SendRegistrationOtpResult, type ServiceRecord, type SignatureMetadata, SubjectType, VM_KEY_AUTH, VM_KEY_E2EE_AGREEMENT, VM_KEY_E2EE_SIGNING, VerificationMethod, type VerificationMethodRecord, type VerificationSuccess, WbaUriParseError, WnsError, authentication, buildAgentMessageService, buildAnpMessageService, buildContentDigest, buildGroupMessageService, buildHandleServiceEntry, buildImContentDigest, buildImSignatureInput, buildResolutionUrl, buildWbaUri as buildUri, buildWbaUri, canonicalizeBindingGeneration, compareBindingGenerations, computeJwkFingerprint, computeMultikeyFingerprint, createAwikiImClient, createDidWbaDocument as createDidDocument, createDidWbaDocumentWithKeyBinding as createDidDocumentWithKeyBinding, createDidWbaDocument, createDidWbaDocumentWithKeyBinding, buildHandleServiceEntry as createHandleServiceEntry, generateAuthHeader as createLegacyAuthHeader, generateAuthJson as createLegacyAuthPayload, generateW3cProof as createProof, generateHttpSignatureHeaders as createSignatureHeaders, createVerificationMethod, decodeImSignature, didDocuments, encodeImSignature, extractAuthHeaderParts, extractHandleServiceFromDidDocument, extractHandleServiceFromDidDocument as extractHandleServices, extractPublicKey, extractSignatureMetadata, findVerificationMethod, generateAuthHeader, generateAuthJson, generateHttpSignatureHeaders, generateImProof, generateW3cProof, httpSignatures, isAssertionMethodAuthorized, isAuthenticationAuthorized, legacyAuth, normalizeHandle, parseImSignatureInput, extractAuthHeaderParts as parseLegacyAuthHeader, extractSignatureMetadata as parseSignatureMetadata, parseWbaUri as parseUri, parseWbaUri, proof, resolveDidDocument, resolveDidWbaDocument, resolveHandle, resolveHandleFromUri, resolveHandleFromUri as resolveUri, validateDidDocumentBinding as validateDidBinding, validateDidDocumentBinding, validateHandle, validateLocalPart, verifyAuthHeaderSignature, verifyAuthJsonSignature, verifyHandleBinding as verifyBinding, verifyContentDigest, verifyDidKeyBinding as verifyDidBinding, verifyDidKeyBinding, verifyFederatedHttpRequest, verifyHandleBinding, verifyHttpMessageSignature, verifyImContentDigest, verifyImProof, verifyAuthHeaderSignature as verifyLegacyAuthHeader, verifyAuthJsonSignature as verifyLegacyAuthPayload, verifyW3cProof as verifyProof, verifyW3cProofDetailed as verifyProofDetailed, verifyHttpMessageSignature as verifySignatureHeaders, verifyW3cProof, verifyW3cProofDetailed, wns };