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

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

@@ -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 };