@oma3/omatrust 0.1.0-alpha.10 → 0.1.0-alpha.11

package/dist/{subject-ownership-CXvzEjpH.d.ts → subject-ownership-B7cFlm8c.d.ts}

@@ -169,10 +169,23 @@ type SubmitDelegatedAttestationParams = {
     signature: Hex | string;
     attester?: Hex;
 };
+type RelayMetadata = {
+    blockNumber?: number;
+    chain?: string;
+    success?: boolean;
+    [key: string]: unknown;
+};
+type RelayErrorDetails = {
+    httpStatus: number;
+    code?: string;
+    error?: string;
+    payload?: Record<string, unknown>;
+};
 type SubmitDelegatedAttestationResult = {
     uid: Hex;
     txHash?: Hex;
     status: "submitted" | "confirmed";
+    relay?: RelayMetadata;
 };
 type GetAttestationParams = {
     uid: Hex;
@@ -181,7 +194,7 @@ type GetAttestationParams = {
     schema?: SchemaField[] | string;
 };
 type ListAttestationsParams = {
-    did: Did;
+    subjectDid: Did;
     provider: unknown;
     easContractAddress: Hex;
     schemas?: Hex[];
@@ -227,14 +240,111 @@ type CallControllerWitnessResult = {
 type VerifyProofParams = {
     proof: ProofWrapper;
     provider?: unknown;
-    expectedSubject?: Did;
-    expectedController?: Did;
+    expectedSubjectDid?: Did;
+    expectedControllerDid?: Did;
 };
 type VerifyProofResult = {
     valid: boolean;
     proofType: ProofType;
     reason?: string;
 };
+type RequestControllerWitnessParams = {
+    /** Subject DID (e.g., did:web:example.com) */
+    subjectDid: Did;
+    /** Controller DID (e.g., did:pkh:eip155:66238:0xabc...) */
+    controllerDid: Did;
+    /** Override the default controller witness API URL. If omitted, uses the OMATrust production endpoint. */
+    gatewayUrl?: string;
+    /** Optional chain ID — defaults to the API's active chain if omitted */
+    chainId?: number;
+    /** Request timeout in milliseconds (default: 15000) */
+    timeoutMs?: number;
+};
+type RequestControllerWitnessResult = {
+    success: boolean;
+    uid: string | null;
+    txHash: string;
+    blockNumber: number;
+    observedAt: number;
+    method: string;
+};
+type W3CKeyPurpose = "authentication" | "assertionMethod" | "keyAgreement";
+type GetControllerAuthorizationParams = {
+    /**
+     * Controller identifier. Can be:
+     * - An EVM wallet address (Hex) for did:pkh controllers
+     * - A did:pkh DID string
+     * - A did:jwk DID string
+     */
+    controllerDid: string;
+    /** Subject DID the controller claims to control */
+    subjectDid: Did;
+    /** ethers v6 Provider for on-chain reads */
+    provider: unknown;
+    /** CAIP-2 chain identifier. Defaults to "eip155:6623" (OMAChain). */
+    chain?: string;
+    /** EAS contract address. If omitted, resolved from trust anchors. */
+    easContractAddress?: Hex;
+    /** How far back to scan for controller witnesses. Defaults to 0 (full history). */
+    fromBlock?: number;
+    /** DNS resolution function for did:web live check */
+    resolveTxt?: (host: string) => Promise<string[][]>;
+    /** DID document fetcher for did:web live check */
+    fetchDidDocument?: (domain: string) => Promise<Record<string, unknown>>;
+    /**
+     * W3C DID verification relationship purposes to require.
+     * Key bindings are only considered valid if their keyPurpose includes all requested purposes.
+     * Defaults to ["authentication", "assertionMethod"].
+     */
+    purpose?: W3CKeyPurpose[];
+};
+type ControllerWitnessEvidence = {
+    /** Attestation UID */
+    uid: Hex;
+    /** Timestamp when the controller witness was issued (unix seconds) */
+    issuedAt: bigint;
+    /** EAS-level attester address (typically the OMA3 server wallet) */
+    attester: string;
+    /** Verification method used by the witness service */
+    method?: "dns" | "did-document" | "manual" | "other";
+};
+type ControllerAuthorizationResult = {
+    /** Whether the controller has any authorization for this subject */
+    authorized: boolean;
+    /**
+     * Earliest timestamp of durable authorization evidence, usually the first
+     * Controller Witness. Null when authorization is only currently verified
+     * by live DNS/did.json.
+     */
+    anchoredFrom: bigint | null;
+    /**
+     * End of the authorization window. Set when a relevant key binding revocation
+     * closes the window. Null if the window is still open.
+     */
+    until: bigint | null;
+    /** Whether live DNS/did.json or contract ownership currently confirms control */
+    currentlyVerified: boolean;
+    /** Verification method for live check */
+    liveMethod: "dns" | "did-document" | "contract-ownership" | null;
+    /** Controller witness attestations found (oldest first) */
+    controllerWitnesses: ControllerWitnessEvidence[];
+    /** Key binding attestation UID if one exists */
+    keyBindingUid: Hex | null;
+    /**
+     * Whether the key binding's keyPurpose matched the requested purposes.
+     * - "matched": key binding exists and its purposes satisfy the request
+     * - "unknown": key binding exists but has no keyPurpose field
+     * - "mismatch": key binding exists but does not satisfy the requested purposes
+     * - "not-required": no key binding exists or no purpose filter was applied
+     */
+    keyPurposeStatus: "matched" | "unknown" | "mismatch" | "not-required";
+    /**
+     * Whether the key binding includes a verified transfer proof.
+     * Only relevant for did:pkh subjects where the controller is authorized
+     * via a key binding backed by a deterministic native transfer.
+     */
+    transferProofVerified?: boolean;
+};
 
 declare function submitAttestation(params: SubmitAttestationParams): Promise<SubmitAttestationResult>;
 
@@ -295,6 +405,96 @@ declare function formatSchemaUid(schemaUid: string): Hex;
 
 declare function callControllerWitness(params: CallControllerWitnessParams): Promise<CallControllerWitnessResult>;
 
+/**
+ * Request a controller witness attestation from the OMATrust backend.
+ *
+ * This is the recommended function for requesting controller witnesses.
+ * It makes a single API call with the subject and controller DIDs.
+ * The backend handles evidence discovery, attestation submission, and
+ * write quota deduction.
+ *
+ * Requires an authenticated session (cookie-based for web clients).
+ * Future versions will support x402 and OAuth DCR 2.0 for agents.
+ *
+ * @deprecated callControllerWitness — use requestControllerWitness instead.
+ * callControllerWitness uses the legacy multi-call pattern and will be
+ * removed in a future SDK version.
+ */
+declare function requestControllerWitness(params: RequestControllerWitnessParams): Promise<RequestControllerWitnessResult>;
+
+/**
+ * Contract Ownership — shared primitives for discovering contract owners
+ * and verifying transfer proofs.
+ *
+ * Used by:
+ * - subject-ownership.ts (full ownership verification flow)
+ * - attester-authorization.ts (authorization checks for did:pkh subjects)
+ */
+
+/**
+ * Minimal provider interface for contract ownership reads.
+ * Compatible with ethers v6 providers — consumers can pass their provider directly.
+ */
+interface ContractOwnershipProvider {
+    call(transaction: {
+        to: string;
+        data: string;
+    }): Promise<string>;
+    getCode(address: string): Promise<string>;
+    getStorage(address: string, slot: string): Promise<string>;
+    getTransaction(hash: string): Promise<{
+        from?: string | null;
+        to?: string | null;
+        value?: bigint | string | number | null;
+        blockNumber?: number | null;
+    } | null>;
+}
+declare const EIP1967_ADMIN_SLOT: "0xb53127684a568b3173ae13b9f8a6016e243e63b6e8ee1178d6a717850b5d6103";
+declare const OWNERSHIP_PATTERNS: readonly [{
+    readonly method: "owner";
+    readonly signature: "function owner() view returns (address)";
+}, {
+    readonly method: "admin";
+    readonly signature: "function admin() view returns (address)";
+}, {
+    readonly method: "getOwner";
+    readonly signature: "function getOwner() view returns (address)";
+}];
+/**
+ * Read a single address-returning function from a contract.
+ * Returns the checksummed address or null if the call fails or returns zero.
+ */
+declare function readOwnerFromContract(provider: ContractOwnershipProvider, contractAddress: string, signature: string, method: string): Promise<string | null>;
+/**
+ * Discover the controlling wallet address of a contract.
+ *
+ * Tries, in order:
+ * 1. `owner()` — OpenZeppelin Ownable
+ * 2. `admin()` — common admin pattern
+ * 3. `getOwner()` — alternative naming
+ * 4. EIP-1967 admin storage slot
+ *
+ * Returns the checksummed owner address, or null if not discoverable.
+ */
+declare function discoverContractOwner(provider: ContractOwnershipProvider, contractAddress: string): Promise<string | null>;
+/**
+ * Discover the controlling wallet and return it as a did:pkh DID.
+ * Convenience wrapper over discoverContractOwner for DID-based flows.
+ */
+declare function discoverControllingWalletDid(provider: ContractOwnershipProvider, contractAddress: string, chainId: number): Promise<Did | null>;
+/**
+ * Verify a transfer proof transaction.
+ *
+ * Checks:
+ * - Transaction exists and has from/to
+ * - Recipient matches the expected attester address
+ * - Transfer amount matches the deterministic proof amount for the subject-attester pair
+ *
+ * Does NOT verify the sender is the current contract owner — that's a separate
+ * concern (the sender may have been the owner at the time of transfer but not now).
+ */
+declare function verifyTransferProof(provider: ContractOwnershipProvider, txHash: Hex, subjectDid: Did, attesterAddress: string, chainId: number): Promise<boolean>;
+
 declare function getSupportedChainIds(): number[];
 declare function isChainSupported(chainId: number): boolean;
 declare function getChainConstants(chainId: number, purpose: ProofPurpose): ChainConstants;
@@ -336,18 +536,65 @@ declare function createX402OfferProof(offer: Record<string, unknown>): X402Offer
 
 declare function createEvidencePointerProof(url: string): EvidencePointerProof;
 
-declare function parseDnsTxtRecord(record: string): {
+interface VerifyDnsTxtControllerDidOptions {
+    resolveTxt?: (host: string) => Promise<string[][]>;
+    recordPrefix?: string;
+}
+
+interface DnsTxtRecordResult {
     version?: string;
+    /**
+     * @deprecated Use `controllers` instead. This field only returns the first
+     * controller value and will be removed in a future release.
+     */
     controller?: Did;
-    [key: string]: string | undefined;
-};
+    /**
+     * All controller DIDs found in the record.
+     * A DNS TXT record may contain multiple controller= entries.
+     */
+    controllers: Did[];
+}
+declare function parseDnsTxtRecord(record: string): DnsTxtRecordResult;
 declare function buildDnsTxtRecord(controllerDid: Did): string;
 
+/**
+ * DID Document Fetching — shared utility
+ *
+ * Fetches did:web DID documents from the well-known endpoint.
+ * Used by identity/resolve-key and reputation/proof/did-json.
+ */
+/**
+ * Fetch a DID document for a did:web domain.
+ *
+ * Resolves `https://<domain>/.well-known/did.json` and returns the parsed JSON.
+ *
+ * @param domain - The domain to fetch the DID document from
+ * @returns The parsed DID document
+ * @throws OmaTrustError with code NETWORK_ERROR if fetch fails
+ */
 declare function fetchDidDocument(domain: string): Promise<Record<string, unknown>>;
+
 interface VerifyDidJsonControllerDidOptions {
     fetchDidDocument?: (domain: string) => Promise<Record<string, unknown>>;
 }
-declare function extractAddressesFromDidDocument(didDocument: Record<string, unknown>): string[];
+/**
+ * Extract EVM addresses from a DID document's verification methods.
+ * Looks at blockchainAccountId and publicKeyHex fields.
+ */
+declare function extractEvmAddressesFromDidDocument(didDocument: Record<string, unknown>): string[];
+/**
+ * Extract public JWKs from a DID document's verification methods.
+ */
+declare function extractJwksFromDidDocument(didDocument: Record<string, unknown>): Array<Record<string, unknown>>;
+/**
+ * Verify that a controller DID is present in a DID document.
+ *
+ * Matching strategies:
+ * - did:pkh (EVM): extract address and compare against blockchainAccountId / publicKeyHex
+ *   in verification methods. Chain ID is ignored (same address across all EVM chains).
+ * - did:jwk: decode the JWK from the DID and compare against publicKeyJwk fields
+ *   in verification methods.
+ */
 declare function verifyDidDocumentControllerDid(didDocument: Record<string, unknown>, expectedControllerDid: Did): {
     valid: boolean;
     reason?: string;
@@ -379,11 +626,6 @@ declare function verifyEip712Signature(typedData: {
     signer?: string;
 };
 
-interface VerifyDnsTxtControllerDidOptions {
-    resolveTxt?: (host: string) => Promise<string[][]>;
-    recordPrefix?: string;
-}
-
 type SubjectOwnershipVerificationMethod = "dns" | "did-document" | "wallet" | "contract" | "minting-wallet" | "transfer";
 interface SubjectOwnershipVerificationResult {
     valid: boolean;
@@ -394,19 +636,7 @@ interface SubjectOwnershipVerificationResult {
     connectedWalletDid: Did;
     controllingWalletDid?: Did;
 }
-interface EvmOwnershipProvider {
-    call(transaction: {
-        to: string;
-        data: string;
-    }): Promise<string>;
-    getCode(address: string): Promise<string>;
-    getStorage(address: string, slot: string): Promise<string>;
-    getTransaction(hash: string): Promise<{
-        from?: string | null;
-        to?: string | null;
-        value?: bigint | string | number | null;
-        blockNumber?: number | null;
-    } | null>;
+interface EvmOwnershipProvider extends ContractOwnershipProvider {
     getTransactionReceipt(hash: string): Promise<{
         blockNumber: number;
     } | null>;
@@ -431,4 +661,4 @@ declare function verifyDidWebOwnership(params: VerifyDidWebOwnershipParams): Pro
 declare function verifyDidPkhOwnership(params: VerifyDidPkhOwnershipParams): Promise<SubjectOwnershipVerificationResult>;
 declare function verifySubjectOwnership(params: VerifySubjectOwnershipParams): Promise<SubjectOwnershipVerificationResult>;
 
-export { createEvidencePointerProof as $, type AttestationQueryResult as A, type BuildDelegatedTypedDataFromEncodedParams as B, type CallControllerWitnessParams as C, type Did as D, type EvidencePointerProof as E, type VerifyProofParams as F, type GetAttestationParams as G, type Hex as H, type VerifyProofResult as I, type VerifySubjectOwnershipParams as J, type X402ReceiptProof as K, type ListAttestationsParams as L, buildDelegatedAttestationTypedData as M, buildDelegatedTypedDataFromEncoded as N, buildDnsTxtRecord as O, type PopEip712Proof as P, buildEip712Domain as Q, type RevokeAttestationParams as R, type SchemaField as S, type TxEncodedValueProof as T, calculateAverageUserReviewRating as U, type VerifyAttestationParams as V, calculateTransferAmount as W, type X402OfferProof as X, calculateTransferAmountFromAddresses as Y, callControllerWitness as Z, constructSeed as _, type AttestationValidationError as a, createPopEip712Proof as a0, createPopJwsProof as a1, createTxEncodedValueProof as a2, createTxInteractionProof as a3, createX402OfferProof as a4, createX402ReceiptProof as a5, decodeAttestationData as a6, deduplicateReviews as a7, encodeAttestationData as a8, extractAddressesFromDidDocument as a9, validateAttestationData as aA, verifyAttestation as aB, verifyDidDocumentControllerDid as aC, verifyDidJsonControllerDid as aD, verifyDidPkhOwnership as aE, verifyDidWebOwnership as aF, verifyEip712Signature as aG, verifyProof as aH, verifySchemaExists as aI, verifySubjectOwnership as aJ, extractExpirationTime as aa, fetchDidDocument as ab, formatSchemaUid as ac, formatTransferAmount as ad, getAttestation as ae, getAttestationsByAttester as af, getAttestationsForDid as ag, getChainConstants as ah, getExplorerAddressUrl as ai, getExplorerTxUrl as aj, getLatestAttestations as ak, getMajorVersion as al, getOmaTrustProofEip712Types as am, getSchemaDetails as an, getSupportedChainIds as ao, hashSeed as ap, isChainSupported as aq, listAttestations as ar, normalizeSchema as as, parseDnsTxtRecord as at, prepareDelegatedAttestation as au, revokeAttestation as av, schemaToString as aw, splitSignature as ax, submitAttestation as ay, submitDelegatedAttestation as az, type CallControllerWitnessResult as b, type ChainConstants as c, type CreatePopEip712ProofParams as d, type CreatePopJwsProofParams as e, type EvmOwnershipProvider as f, type GetAttestationsByAttesterParams as g, type GetLatestAttestationsParams as h, type PopJwsProof as i, type PrepareDelegatedAttestationParams as j, type PrepareDelegatedAttestationResult as k, type ProofPurpose as l, type ProofType as m, type ProofWrapper as n, type RevokeAttestationResult as o, type SubjectOwnershipVerificationMethod as p, type SubjectOwnershipVerificationResult as q, type SubmitAttestationParams as r, type SubmitAttestationResult as s, type SubmitDelegatedAttestationParams as t, type SubmitDelegatedAttestationResult as u, type TxInteractionProof as v, type VerifyAttestationResult as w, type VerifyDidJsonControllerDidOptions as x, type VerifyDidPkhOwnershipParams as y, type VerifyDidWebOwnershipParams as z };
+export { buildDelegatedAttestationTypedData as $, type AttestationQueryResult as A, type BuildDelegatedTypedDataFromEncodedParams as B, type CallControllerWitnessParams as C, type Did as D, type EvidencePointerProof as E, type SubmitAttestationResult as F, type GetAttestationParams as G, type Hex as H, type SubmitDelegatedAttestationParams as I, type SubmitDelegatedAttestationResult as J, type TxInteractionProof as K, type ListAttestationsParams as L, type VerifyAttestationResult as M, type VerifyDidJsonControllerDidOptions as N, type VerifyDidPkhOwnershipParams as O, type PopEip712Proof as P, type VerifyDidWebOwnershipParams as Q, type RelayErrorDetails as R, type SchemaField as S, type TxEncodedValueProof as T, type VerifyProofParams as U, type VerifyAttestationParams as V, type VerifyProofResult as W, type VerifySubjectOwnershipParams as X, type W3CKeyPurpose as Y, type X402OfferProof as Z, type X402ReceiptProof as _, type AttestationValidationError as a, readOwnerFromContract as a$, buildDelegatedTypedDataFromEncoded as a0, buildDnsTxtRecord as a1, buildEip712Domain as a2, calculateAverageUserReviewRating as a3, calculateTransferAmount as a4, calculateTransferAmountFromAddresses as a5, callControllerWitness as a6, constructSeed as a7, createEvidencePointerProof as a8, createPopEip712Proof as a9, isChainSupported as aA, listAttestations as aB, normalizeSchema as aC, parseDnsTxtRecord as aD, prepareDelegatedAttestation as aE, requestControllerWitness as aF, revokeAttestation as aG, schemaToString as aH, splitSignature as aI, submitAttestation as aJ, submitDelegatedAttestation as aK, validateAttestationData as aL, verifyAttestation as aM, verifyDidDocumentControllerDid as aN, verifyDidJsonControllerDid as aO, verifyDidPkhOwnership as aP, verifyDidWebOwnership as aQ, verifyEip712Signature as aR, verifyProof as aS, verifySchemaExists as aT, verifySubjectOwnership as aU, type VerifyDnsTxtControllerDidOptions as aV, type ContractOwnershipProvider as aW, EIP1967_ADMIN_SLOT as aX, OWNERSHIP_PATTERNS as aY, discoverContractOwner as aZ, discoverControllingWalletDid as a_, createPopJwsProof as aa, createTxEncodedValueProof as ab, createTxInteractionProof as ac, createX402OfferProof as ad, createX402ReceiptProof as ae, decodeAttestationData as af, deduplicateReviews as ag, encodeAttestationData as ah, extractEvmAddressesFromDidDocument as ai, extractExpirationTime as aj, extractJwksFromDidDocument as ak, fetchDidDocument as al, formatSchemaUid as am, formatTransferAmount as an, getAttestation as ao, getAttestationsByAttester as ap, getAttestationsForDid as aq, getChainConstants as ar, getExplorerAddressUrl as as, getExplorerTxUrl as at, getLatestAttestations as au, getMajorVersion as av, getOmaTrustProofEip712Types as aw, getSchemaDetails as ax, getSupportedChainIds as ay, hashSeed as az, type CallControllerWitnessResult as b, verifyTransferProof as b0, type ChainConstants as c, type ControllerAuthorizationResult as d, type ControllerWitnessEvidence as e, type CreatePopEip712ProofParams as f, type CreatePopJwsProofParams as g, type DnsTxtRecordResult as h, type EvmOwnershipProvider as i, type GetAttestationsByAttesterParams as j, type GetControllerAuthorizationParams as k, type GetLatestAttestationsParams as l, type PopJwsProof as m, type PrepareDelegatedAttestationParams as n, type PrepareDelegatedAttestationResult as o, type ProofPurpose as p, type ProofType as q, type ProofWrapper as r, type RelayMetadata as s, type RequestControllerWitnessParams as t, type RequestControllerWitnessResult as u, type RevokeAttestationParams as v, type RevokeAttestationResult as w, type SubjectOwnershipVerificationMethod as x, type SubjectOwnershipVerificationResult as y, type SubmitAttestationParams as z };

package/dist/types-dpYxRq8N.d.cts

@@ -0,0 +1,281 @@
+/**
+ * JWK and did:jwk Helpers — Phase 2
+ *
+ * Provides conversion between public JWKs and did:jwk DIDs,
+ * deterministic JWK comparison, and public JWK validation.
+ *
+ * did:jwk is the preferred durable DID representation for JWS/JWK public key
+ * material. It is immutable (the DID IS the key) and should be used as the
+ * controllerDid for authorization checks.
+ *
+ * Uses the `jose` library for base64url encoding/decoding and JWK thumbprints.
+ */
+/** Minimal public JWK structure */
+interface PublicJwk {
+    kty: string;
+    [key: string]: unknown;
+}
+/** Result of JWK validation */
+interface JwkValidationResult {
+    valid: boolean;
+    error?: string;
+}
+/**
+ * Validate that a JWK object is a well-formed public key.
+ *
+ * Requirements:
+ * - Must be a non-null object
+ * - Must have a valid `kty` (EC, OKP, RSA)
+ * - Must have required public key fields for its key type
+ * - Must NOT contain private key material (d, p, q, dp, dq, qi, oth)
+ */
+declare function validatePublicJwk(jwk: unknown): JwkValidationResult;
+/**
+ * Convert a public JWK to a did:jwk DID.
+ *
+ * Uses deterministic (sorted-key) JSON serialization and base64url encoding.
+ * Rejects JWKs containing private key material.
+ *
+ * @param jwk - A public JWK object
+ * @returns The did:jwk DID string
+ * @throws OmaTrustError if the JWK is invalid or contains private key material
+ */
+declare function jwkToDidJwk(jwk: unknown): string;
+/**
+ * Convert a did:jwk DID back to a public JWK object.
+ *
+ * Validates the DID structure, decodes the base64url payload,
+ * parses JSON, and validates the resulting JWK.
+ *
+ * @param didJwk - A did:jwk DID string
+ * @returns The decoded public JWK object
+ * @throws OmaTrustError if the DID is malformed or contains private key material
+ */
+declare function didJwkToJwk(didJwk: string): PublicJwk;
+/**
+ * Compare two public JWKs for equality.
+ *
+ * Compares only the public key material fields (kty, crv, x, y, n, e, etc.).
+ * Ignores property order, metadata fields (kid, use, alg, key_ops, ext),
+ * and rejects/strips private key fields before comparison.
+ *
+ * @param a - First public JWK
+ * @param b - Second public JWK
+ * @returns true if both JWKs represent the same public key
+ * @throws OmaTrustError if either JWK contains private key material
+ */
+declare function publicJwkEquals(a: unknown, b: unknown): boolean;
+/**
+ * Compute an RFC 7638 JWK Thumbprint for a public JWK.
+ *
+ * Returns the base64url-encoded SHA-256 thumbprint. This is a compact,
+ * deterministic fingerprint of the public key material.
+ *
+ * Used in OMATrust DNS TXT records as: `jkt=S256:<thumbprint>`
+ *
+ * @param jwk - A public JWK object
+ * @param digestAlgorithm - Hash algorithm (default: "sha256")
+ * @returns base64url-encoded thumbprint string
+ * @throws OmaTrustError if the JWK is invalid or contains private key material
+ */
+declare function computeJwkThumbprint(jwk: unknown, digestAlgorithm?: "sha256" | "sha384" | "sha512"): Promise<string>;
+/**
+ * Format a JWK thumbprint as an OMATrust DNS TXT `jkt` value.
+ *
+ * Format: `jkt=S256:<base64url-thumbprint>`
+ *
+ * @param jwk - A public JWK object
+ * @returns Formatted jkt string for DNS TXT records
+ */
+declare function formatJktValue(jwk: unknown): Promise<string>;
+
+/**
+ * DID URL Key Resolution — Phase 3
+ *
+ * Resolves DID URL key references (e.g. did:web:api.example.com#key-1) to
+ * public key material and derives durable did:jwk controller DIDs.
+ *
+ * DID URLs are mutable key references. This module resolves them to the
+ * actual public key material they currently point to, then converts that
+ * material into an immutable did:jwk for use as a controller DID.
+ */
+
+/** Result of resolving a DID URL to public key material */
+interface ResolvedPublicKey {
+    /** The original DID URL */
+    didUrl: string;
+    /** The base DID (without fragment) */
+    did: string;
+    /** The fragment identifier */
+    fragment: string | null;
+    /** The resolved public JWK */
+    publicKeyJwk: PublicJwk;
+    /** The verification method ID that matched */
+    verificationMethodId: string;
+}
+/** Result of resolving a DID URL to a durable controller DID */
+interface ResolvedControllerDid extends ResolvedPublicKey {
+    /** The durable did:jwk derived from the resolved public key */
+    controllerDid: string;
+}
+/** Options for DID URL key resolution */
+interface ResolveKeyOptions {
+    /**
+     * Custom DID document fetcher. If not provided, uses the shared
+     * fetchDidDocument which fetches from `/.well-known/did.json`.
+     */
+    fetchDidDocument?: (domain: string) => Promise<Record<string, unknown>>;
+}
+/**
+ * Resolve a DID URL to public key material.
+ *
+ * Currently supports:
+ * - did:web with fragment (e.g. did:web:api.example.com#key-1)
+ *
+ * Resolution steps:
+ * 1. Parse the DID URL
+ * 2. Resolve the base DID (fetch DID document)
+ * 3. Find the matching verification method
+ * 4. Extract and validate publicKeyJwk
+ *
+ * This function only obtains key material. It does not make authorization
+ * decisions or check Controller Witness / Key Binding records.
+ *
+ * @param didUrl - A DID URL string (e.g. "did:web:api.example.com#key-1")
+ * @param options - Optional configuration (custom fetcher, etc.)
+ * @returns Resolved public key information
+ * @throws OmaTrustError if resolution fails
+ */
+declare function resolveDidUrlToPublicKey(didUrl: string, options?: ResolveKeyOptions): Promise<ResolvedPublicKey>;
+/**
+ * Resolve a DID URL to a durable controller DID.
+ *
+ * This wraps resolveDidUrlToPublicKey and adds the did:jwk conversion step.
+ * The returned controllerDid is the durable DID that callers should pass
+ * to getControllerAuthorization.
+ *
+ * @param didUrl - A DID URL string (e.g. "did:web:api.example.com#key-1")
+ * @param options - Optional configuration (custom fetcher, etc.)
+ * @returns Resolved public key plus derived did:jwk controller DID
+ * @throws OmaTrustError if resolution fails
+ */
+declare function resolveDidUrlToControllerDid(didUrl: string, options?: ResolveKeyOptions): Promise<ResolvedControllerDid>;
+
+/**
+ * Identity Types — Phase 4
+ *
+ * Types for JWS verification results and authorization metadata.
+ * These define the contract between signature verification and
+ * downstream authorization checks via getControllerAuthorization.
+ */
+
+/** Source of the public key used for JWS signature verification */
+type PublicKeySource = "embedded-jwk" | "kid-resolution";
+/**
+ * Structured result of JWS signature verification.
+ *
+ * This result is NOT an authorization result. It does not determine whether
+ * the signing key was authorized to act for the service identified by resourceUrl.
+ *
+ * It provides enough information for callers to perform downstream authorization
+ * checks via getControllerAuthorization:
+ * - publicKeyDid (did:jwk) is the durable controller DID
+ * - resourceUrl identifies the service subject
+ * - issuedAt enables authorization-window checks for receipts
+ */
+interface JwsVerificationResult {
+    /** Whether the JWS signature is cryptographically valid */
+    valid: boolean;
+    /** Decoded JWS protected header */
+    header: Record<string, unknown>;
+    /** Decoded JWS payload */
+    payload: Record<string, unknown>;
+    /** kid from the JWS header (a key reference, NOT a controller DID) */
+    kid: string | null;
+    /** The public JWK used for signature verification */
+    publicKeyJwk: PublicJwk;
+    /** How the public key was obtained */
+    publicKeySource: PublicKeySource;
+    /**
+     * The durable did:jwk derived from the public key.
+     * This is the controller DID for downstream authorization checks.
+     * Pass this as controllerDid to getControllerAuthorization.
+     */
+    publicKeyDid: string;
+    /** Error details when valid is false */
+    error?: JwsVerificationError;
+}
+/** Error details for failed JWS verification */
+interface JwsVerificationError {
+    code: string;
+    message: string;
+}
+/**
+ * Failed JWS verification result.
+ * Returned when parsing, decoding, or signature verification fails.
+ */
+interface JwsVerificationFailure {
+    valid: false;
+    error: JwsVerificationError;
+    header?: Record<string, unknown>;
+    payload?: Record<string, unknown>;
+    kid?: string | null;
+    publicKeyJwk?: PublicJwk;
+    publicKeySource?: PublicKeySource;
+    publicKeyDid?: string;
+}
+/**
+ * Authorization metadata extracted from a verified JWS artifact.
+ *
+ * This is the information a caller needs to perform an authorization check
+ * after JWS signature verification succeeds.
+ *
+ * Usage:
+ * 1. Verify JWS → get JwsVerificationResult
+ * 2. Extract AuthorizationMetadata from the result
+ * 3. Call getControllerAuthorization({ subjectDid, controllerDid, purpose })
+ * 4. Evaluate the returned authorization window against policy
+ */
+interface AuthorizationMetadata {
+    /**
+     * The durable controller DID (did:jwk) derived from the verified public key.
+     * Pass this as controllerDid to getControllerAuthorization.
+     */
+    controllerDid: string;
+    /**
+     * The subject DID derived from resourceUrl.
+     * For x402 artifacts, this is typically did:web:<domain-from-resourceUrl>.
+     * Pass this as subjectDid to getControllerAuthorization.
+     */
+    subjectDid: string | null;
+    /**
+     * The resourceUrl from the signed payload.
+     * Identifies the service/resource the artifact is associated with.
+     */
+    resourceUrl: string | null;
+    /**
+     * The issuedAt timestamp from the signed payload (receipts).
+     * Used for authorization-window checks — was the controller authorized at this time?
+     */
+    issuedAt: string | null;
+    /**
+     * The kid from the JWS header (mutable key reference).
+     * Useful for key-pinning lookups but NOT a controller DID.
+     */
+    kid: string | null;
+    /** The public JWK used for signature verification */
+    publicKeyJwk: PublicJwk;
+}
+/**
+ * Extract authorization metadata from a successful JWS verification result.
+ *
+ * Derives the subject DID from resourceUrl when possible (assumes did:web
+ * for HTTPS URLs). Returns null for subjectDid if resourceUrl is missing
+ * or cannot be parsed.
+ *
+ * @param result - A successful JwsVerificationResult (valid === true)
+ * @returns Authorization metadata for downstream getControllerAuthorization calls
+ */
+declare function extractAuthorizationMetadata(result: JwsVerificationResult): AuthorizationMetadata;
+
+export { type AuthorizationMetadata as A, type JwkValidationResult as J, type PublicJwk as P, type ResolveKeyOptions as R, type JwsVerificationError as a, type JwsVerificationFailure as b, type JwsVerificationResult as c, type PublicKeySource as d, type ResolvedControllerDid as e, type ResolvedPublicKey as f, computeJwkThumbprint as g, didJwkToJwk as h, extractAuthorizationMetadata as i, formatJktValue as j, jwkToDidJwk as k, resolveDidUrlToPublicKey as l, publicJwkEquals as p, resolveDidUrlToControllerDid as r, validatePublicJwk as v };