@terminal3/t3n-sdk 4.2.0 → 4.3.0

package/dist/index.d.ts

@@ -1263,6 +1263,7 @@ declare class HttpTransport implements Transport {
  * mockTransport.mockResponse("auth.handshake", { result: "..." });
  *
  * const client = new T3nClient({
+ *   trustAnchor: { unsafe_trust_server: true },
  *   transport: mockTransport,
  *   wasmComponent: mockWasm,
  * });
@@ -1317,6 +1318,112 @@ declare class MockTransport implements Transport {
     send(request: JsonRpcRequest, headers: Record<string, string>): Promise<JsonRpcResponse>;
 }
 
+/**
+ * TDX quote verifier backed by the Rust `signature` crate compiled to
+ * WASM. Full cryptographic verification: ECDSA P-256 attestation-key
+ * signature, PCK certificate chain walk to Intel's root CA, and
+ * report_data + RTMR comparison.
+ *
+ * The WASM bytes are inlined as base64 (see quote_verifier_bytes.ts)
+ * so the SDK works without bundler WASM plugins and without runtime
+ * asset URL resolution.
+ */
+interface QuoteVerifyResult {
+    valid: boolean;
+    error?: string;
+    rtmr3?: string;
+    report_data?: string;
+}
+interface PeerQuoteResult {
+    peer_id: string;
+    valid: boolean;
+    error?: string;
+    rtmr3?: string;
+}
+interface DkgVerifyResult {
+    valid: boolean;
+    results: PeerQuoteResult[];
+    valid_count: number;
+    expected_count: number;
+    error?: string;
+}
+/**
+ * Client-pinned anchor the DKG attestation bundle is verified against.
+ *
+ * Without it, "the server proved it runs in a TEE" only means "*some*
+ * TDX box somewhere" — any attacker with their own TDX cloud VM can
+ * forge a complete, cryptographically-valid bundle for their own key
+ * (SP-003). The anchor is the independent ground truth that closes it:
+ * the bundle must describe *our* cluster (`expected_peer_ids`) running
+ * *our* image (`rtmr3_allowlist`).
+ */
+interface TrustAnchor {
+    /**
+     * Base58 peer IDs the client expects in the cluster. The bundle's
+     * `peer_ids` must equal this set exactly (order-insensitive) — a MITM
+     * cannot substitute its own single-node participant set.
+     */
+    expected_peer_ids: string[];
+    /**
+     * Base64-encoded 48-byte RTMR3 measurements of the expected node
+     * image. Every quote's RTMR3 must be a member. **Must be non-empty.**
+     * An array (not a singleton) so a rolling deploy's two in-flight
+     * image measurements both verify.
+     */
+    rtmr3_allowlist: string[];
+}
+/**
+ * Escape hatch for local dev / tests against a node whose attestation
+ * can't be anchored (e.g. a mock signer that publishes no bundle).
+ *
+ * The name is deliberately alarming so it stands out in code review and
+ * grep — it is the *only* way to skip DKG attestation verification on
+ * the handshake path.
+ */
+interface UnsafeTrustServer {
+    unsafe_trust_server: true;
+}
+type TrustAnchorOrUnsafe = TrustAnchor | UnsafeTrustServer;
+/** Narrow a {@link TrustAnchorOrUnsafe} to the explicit opt-out arm. */
+declare function isUnsafeTrustServer(anchor: TrustAnchorOrUnsafe): anchor is UnsafeTrustServer;
+/**
+ * Verify a single TDX attestation quote with full cryptographic verification.
+ *
+ * @param quoteB64 - Base64-encoded raw TDX v4 quote
+ * @param attestationMsgB64 - Base64-encoded attestation message
+ *   (for DKG: encaps_key || sorted_peer_id_bytes)
+ * @param expectedRtmr3B64 - Optional base64-encoded 48-byte RTMR3
+ * @returns Verification result with extracted measurements
+ */
+declare function verifyTdxQuote(quoteB64: string, attestationMsgB64: string, expectedRtmr3B64?: string): Promise<QuoteVerifyResult>;
+/**
+ * Verify a full DKG attestation bundle against a client-pinned
+ * {@link TrustAnchor}: multiple TDX quotes from all participating
+ * nodes, plus the binding between the quotes and the ML-KEM
+ * encapsulation key. Checks:
+ *   1. `expected_peer_ids` / `rtmr3_allowlist` are both non-empty
+ *   2. the bundle's `peer_ids` equal the pinned set exactly
+ *   3. attestationMsg starts with encapsKey (server can't swap the key)
+ *   4. every quote's ECDSA signature chains to Intel's SGX root CA
+ *   5. every quote's report_data == keccak512(attestationMsg)
+ *   6. every quote's RTMR3 is a member of `rtmr3_allowlist`
+ *
+ * The anchor is **required**: there is no unauthenticated mode. Callers
+ * that genuinely want to trust the server must not call this at all —
+ * see `unsafe_trust_server` on the client config, which branches around
+ * the whole verify path.
+ *
+ * @param encapsKeyB64 - Base64-encoded ML-KEM encapsulation key
+ *   (from `/status.encaps_key`)
+ * @param attestationMsgB64 - Base64-encoded raw attestation message
+ *   (from `/status.dkg_attestation.attestation_msg`)
+ * @param peerIds - Base58 peer IDs as reported by the bundle
+ * @param quotes - Map of peer_id → base64-encoded TDX quote
+ * @param anchor - Client-pinned expected peer IDs + RTMR3 allowlist
+ * @returns Per-peer verification results and overall validity
+ */
+declare function verifyDkgAttestation(encapsKeyB64: string, attestationMsgB64: string, peerIds: string[], quotes: Record<string, string>, anchor: TrustAnchor): Promise<DkgVerifyResult>;
+
 /**
  * Configuration types for T3n Client
  */
@@ -1346,6 +1453,20 @@ interface T3nClientConfig {
     logger?: Logger;
     /** Optional guest-to-host request handlers - provides custom behavior for WASM requests */
     handlers?: GuestToHostHandlers;
+    /**
+     * **Required.** Client-pinned trust anchor the node's DKG attestation
+     * is verified against before the handshake trusts its ML-KEM key
+     * (SP-003). Either a {@link TrustAnchor} (`expected_peer_ids` +
+     * `rtmr3_allowlist`) or the explicit `{ unsafe_trust_server: true }`
+     * opt-out for local dev / mock-signer nodes.
+     *
+     * Without this, a network attacker with their own TDX VM can hand the
+     * SDK a forged-but-valid attestation for a key it controls and read
+     * every session. It is a required field precisely so no caller can
+     * omit it by accident — bypassing verification must be a visible,
+     * grep-able choice.
+     */
+    trustAnchor: TrustAnchorOrUnsafe;
 }
 
 /**
@@ -2398,8 +2519,9 @@ declare function metamask_get_address(): Promise<string>;
 declare function eth_get_address(privateKey: string): string;
 /**
  * Create an MlKemPublicKey handler that lazily fetches the root public key
- * from `${baseUrl}/status` on first invocation and caches the encoded
- * response for subsequent calls.
+ * from `${baseUrl}/status` on first invocation, verifies it against the
+ * DKG attestation trust anchor (SP-003), and caches the encoded response
+ * for subsequent calls.
  *
  * @param baseUrl - **Required**. The node URL whose `/status` endpoint should
  *                  serve the ML-KEM public key. Must be the same URL the
@@ -2411,8 +2533,12 @@ declare function eth_get_address(privateKey: string): string;
  *                  hit the wrong node. Three downstream consumers (demo.ts,
  *                  t3-apps dev wallet hooks, t3n-mcp session manager) all
  *                  hit this trap before we tightened the type.
+ * @param trustAnchor - **Required**. Client-pinned expected peer IDs +
+ *                  RTMR3 allowlist the DKG bundle is verified against, or
+ *                  `{ unsafe_trust_server: true }` to skip verification.
+ *                  The key is only cached/returned once verification passes.
  */
-declare function createMlKemPublicKeyHandler(baseUrl: string): GuestToHostHandler;
+declare function createMlKemPublicKeyHandler(baseUrl: string, trustAnchor: TrustAnchorOrUnsafe): GuestToHostHandler;
 /**
  * Create Random handler backed by crypto.getRandomValues
  * Note: The Rust Vec<u8> type serializes as an array of bytes, not a base64 string
@@ -2423,8 +2549,11 @@ declare function createRandomHandler(): GuestToHostHandler;
  *
  * @param baseUrl - **Required**. Forwarded to `createMlKemPublicKeyHandler`
  *                  so the lazy /status fetch hits the right node.
+ * @param trustAnchor - **Required**. Forwarded to the ML-KEM handler so the
+ *                  fetched key is verified against the DKG attestation
+ *                  (SP-003) before the handshake trusts it.
  */
-declare function createDefaultHandlers(baseUrl: string): GuestToHostHandlers;
+declare function createDefaultHandlers(baseUrl: string, trustAnchor: TrustAnchorOrUnsafe): GuestToHostHandlers;
 
 /**
  * Payroll request shapes + shared encoding utilities.
@@ -2650,6 +2779,17 @@ interface OrgDataClientOptions extends ExecuteOrgDataActionOptions {
      * header (e.g. the staging Cloud Armor bypass token).
      */
     headers?: Record<string, string>;
+    /**
+     * **Required.** Trust anchor for the internal `T3nClient`'s DKG
+     * attestation check (SP-003). Mirrors `T3nClientConfig.trustAnchor`:
+     * either a pinned {@link TrustAnchor} or the explicit
+     * `{ unsafe_trust_server: true }` opt-out. Required (no silent default)
+     * so bypassing verification is always a visible, grep-able choice —
+     * an authenticated ETH-key caller is still MITM-able on the ML-KEM key.
+     * Signed trust-anchor manifests are not published yet, so most callers
+     * pass `{ unsafe_trust_server: true }` today.
+     */
+    trustAnchor: TrustAnchorOrUnsafe;
 }
 /**
  * Client for session-authenticated org-data contract execution.
@@ -2666,7 +2806,7 @@ declare class OrgDataClient {
     private readonly userDid;
     private readonly opts;
     private clientPromise;
-    constructor(baseUrl: string, ethSecret: Uint8Array, userDid: string, opts?: OrgDataClientOptions);
+    constructor(baseUrl: string, ethSecret: Uint8Array, userDid: string, opts: OrgDataClientOptions);
     private getAuthenticatedClient;
     private initialiseClient;
     private call;
@@ -2991,65 +3131,6 @@ interface ConfigValidationResult {
     errors: string[];
 }
 
-/**
- * TDX quote verifier backed by the Rust `signature` crate compiled to
- * WASM. Full cryptographic verification: ECDSA P-256 attestation-key
- * signature, PCK certificate chain walk to Intel's root CA, and
- * report_data + RTMR comparison.
- *
- * The WASM bytes are inlined as base64 (see quote_verifier_bytes.ts)
- * so the SDK works without bundler WASM plugins and without runtime
- * asset URL resolution.
- */
-interface QuoteVerifyResult {
-    valid: boolean;
-    error?: string;
-    rtmr3?: string;
-    report_data?: string;
-}
-interface PeerQuoteResult {
-    peer_id: string;
-    valid: boolean;
-    error?: string;
-    rtmr3?: string;
-}
-interface DkgVerifyResult {
-    valid: boolean;
-    results: PeerQuoteResult[];
-    valid_count: number;
-    expected_count: number;
-    error?: string;
-}
-/**
- * Verify a single TDX attestation quote with full cryptographic verification.
- *
- * @param quoteB64 - Base64-encoded raw TDX v4 quote
- * @param attestationMsgB64 - Base64-encoded attestation message
- *   (for DKG: encaps_key || sorted_peer_id_bytes)
- * @param expectedRtmr3B64 - Optional base64-encoded 48-byte RTMR3
- * @returns Verification result with extracted measurements
- */
-declare function verifyTdxQuote(quoteB64: string, attestationMsgB64: string, expectedRtmr3B64?: string): Promise<QuoteVerifyResult>;
-/**
- * Verify a full DKG attestation bundle: multiple TDX quotes from all
- * participating nodes, plus the binding between the quotes and the
- * ML-KEM encapsulation key. Checks:
- *   1. attestationMsg starts with encapsKey (server can't swap the key)
- *   2. Every quote's ECDSA signature chains to Intel's SGX root CA
- *   3. Every quote's report_data == keccak512(attestationMsg)
- *   4. Optional RTMR3 pinning per quote
- *
- * @param encapsKeyB64 - Base64-encoded ML-KEM encapsulation key
- *   (from `/status.encaps_key`)
- * @param attestationMsgB64 - Base64-encoded raw attestation message
- *   (from `/status.dkg_attestation.attestation_msg`)
- * @param peerIds - Sorted array of base58 peer IDs
- * @param quotes - Map of peer_id → base64-encoded TDX quote
- * @param expectedRtmr3B64 - Optional base64-encoded 48-byte RTMR3
- * @returns Per-peer verification results and overall validity
- */
-declare function verifyDkgAttestation(encapsKeyB64: string, attestationMsgB64: string, peerIds: string[], quotes: Record<string, string>, expectedRtmr3B64?: string): Promise<DkgVerifyResult>;
-
 /**
  * Configuration validation for T3n SDK
  */
@@ -3459,5 +3540,5 @@ declare function tenantDidHex(tenantDid: string): string;
 declare function validateTail(tail: string): string;
 declare function canonicalTenantName(tenantDid: string, tail: string): string;
 
-export { AuthMethod, AuthenticationError, BASE_UNITS_PER_TOKEN, ContractResponseError, DEFAULT_ENVIRONMENT, DEFAULT_INDIVIDUAL_THRESHOLD_CENTS, DEFAULT_KYC_POLL_CADENCE, HandshakeError, HttpTransport, KycStatusTimeoutError, LogLevel, MockTransport, NODE_URLS, OrgDataClient, OtpRateLimitedError, RpcError, SessionExpiredError, SessionOrgDataClient, SessionStateError, SessionStatus, T3nClient, T3nError, TERMINAL_KYC_STATUSES, TOKEN_DECIMALS, TenantClient, TenantContractsNamespace, TenantMapsNamespace, TenantNamespace, TenantSdkValidationError, TenantTokenNamespace, UnsupportedTenantSdkOperationError, UserUpsertError, WasmError, Z_PAYROLL_AUDIT_READ_FUNCTIONS, Z_PAYROLL_RUN_FUNCTIONS, _b64uEncode, assertShape, b64uDecodeStrict, b64uEncodeBytes, bytesToString, canonicalTenantName, clearKeyCache, compactDidFromBytes, createDefaultHandlers, createEmailOtpAuthInput, createEthAuthInput, createLogger, createMlKemPublicKeyHandler, createOidcAuthInput, createOrgDataClientFromSession, createRandomHandler, createWorkloadAuthInput, decodeWasmErrorMessage, eth_get_address, extractWasmError, fetchDkgAttestation, fetchMlKemPublicKey, formatTokens, generateRandomString, generateUUID, getEnvironment, getEnvironmentName, getGlobalLogLevel, getLogger, getNodeUrl, getScriptVersion, isDataGetResponse, isDataListResponse, isMutationResponse, isObject, isOrgContractGrants, isOrgPolicyMeta, isOrgPolicyView, isOrgWriters, loadConfig, loadWasmComponent, maskKeyMaterial, mergeAgentAuthEntries, metamask_get_address, metamask_sign, parseAgentAuthGet, parseContractResponse, redactSecrets, redactSecretsFromJson, setEnvironment, setGlobalLogLevel, setNodeUrl, stringToBytes, tenantDidHex, toAgentAuthUpdateWire, toBaseUnits, validateConfig, validateTail, verifyDkgAttestation, verifyTdxQuote };
-export type { AdmitForOrgOptions, AgentAuthEntry, AgentAuthMergeResult, AgentAuthScriptGrant, AgentAuthUpdateInput, AuthInput, BalanceRow, ChargeReason, ClientAuth, ClientHandshake, ConfigValidationResult, ContractExecuteInput, ContractPublishInput, ContractRegisterResult, ContractResponseSchema, CreatePolicyInput, DataGetInput, DataGetResponse, DataListInput, DataListResponse, DeleteDataInput, DeleteGrantsInput, DeleteScopeInput, Did, Direction, DkgAttestation, DkgVerifyResult, EmailOtpAuthInput, EmailOtpCredentials, Environment, EthAuthInput, ExecuteBusinessContractOptions, ExecuteOrgDataActionOptions, GetUsageOptions, GrantsGetInput, GuestToHostHandler, GuestToHostHandlers, HandshakeResult, JsonRpcRequest, JsonRpcResponse, KycPollCadence, KycPollOptions, KycStatus, KycStatusKind, Logger, MapCreateInput, MapResponse, MapUpdateInput, MapVisibility, MutationResponse, OidcAuthInput, OidcCredentials, OrgContractGrants, OrgDataActionWire, OrgDataClientOptions, OrgPolicyMeta, OrgPolicyView, OrgWriters, OtpChannel, OtpMergeSuggestion, OtpRequestInput, OtpRequestResult, OtpVerifyInput, OtpVerifyResult, PayrollRunRequest, PeerQuoteResult, PolicyGetInput, QuoteVerifyResult, ReaderSet, SdkConfig, SessionCrypto, SessionId, SetGrantsInput, SetWritersInput, SubmitUserInputArgs, SubmitUserInputResult, T3nClientConfig, TenantAdmitProjection, TenantAdmitStatus, TenantBaseClient, TenantClientConfig, TenantContractExecuteInput, TenantContractPublishInput, TenantExecutionSession, TenantMapCreateInput, TenantMapUpdatePatch, TenantMeResponse, TenantSdkEnvironment, TenantSelfAdmitResult, TenantStatus, TenantTargetOptions, TokenTxKind, Transport, UpdateMetaInput, UsageEntry, UsagePage, UserGrant, UserInputProfile, UserUpsertErrorKind, WasmComponent, WasmNextResult, WorkloadAuthInput, WriteDataInput, WriterSet, WritersGetInput };
+export { AuthMethod, AuthenticationError, BASE_UNITS_PER_TOKEN, ContractResponseError, DEFAULT_ENVIRONMENT, DEFAULT_INDIVIDUAL_THRESHOLD_CENTS, DEFAULT_KYC_POLL_CADENCE, HandshakeError, HttpTransport, KycStatusTimeoutError, LogLevel, MockTransport, NODE_URLS, OrgDataClient, OtpRateLimitedError, RpcError, SessionExpiredError, SessionOrgDataClient, SessionStateError, SessionStatus, T3nClient, T3nError, TERMINAL_KYC_STATUSES, TOKEN_DECIMALS, TenantClient, TenantContractsNamespace, TenantMapsNamespace, TenantNamespace, TenantSdkValidationError, TenantTokenNamespace, UnsupportedTenantSdkOperationError, UserUpsertError, WasmError, Z_PAYROLL_AUDIT_READ_FUNCTIONS, Z_PAYROLL_RUN_FUNCTIONS, _b64uEncode, assertShape, b64uDecodeStrict, b64uEncodeBytes, bytesToString, canonicalTenantName, clearKeyCache, compactDidFromBytes, createDefaultHandlers, createEmailOtpAuthInput, createEthAuthInput, createLogger, createMlKemPublicKeyHandler, createOidcAuthInput, createOrgDataClientFromSession, createRandomHandler, createWorkloadAuthInput, decodeWasmErrorMessage, eth_get_address, extractWasmError, fetchDkgAttestation, fetchMlKemPublicKey, formatTokens, generateRandomString, generateUUID, getEnvironment, getEnvironmentName, getGlobalLogLevel, getLogger, getNodeUrl, getScriptVersion, isDataGetResponse, isDataListResponse, isMutationResponse, isObject, isOrgContractGrants, isOrgPolicyMeta, isOrgPolicyView, isOrgWriters, isUnsafeTrustServer, loadConfig, loadWasmComponent, maskKeyMaterial, mergeAgentAuthEntries, metamask_get_address, metamask_sign, parseAgentAuthGet, parseContractResponse, redactSecrets, redactSecretsFromJson, setEnvironment, setGlobalLogLevel, setNodeUrl, stringToBytes, tenantDidHex, toAgentAuthUpdateWire, toBaseUnits, validateConfig, validateTail, verifyDkgAttestation, verifyTdxQuote };
+export type { AdmitForOrgOptions, AgentAuthEntry, AgentAuthMergeResult, AgentAuthScriptGrant, AgentAuthUpdateInput, AuthInput, BalanceRow, ChargeReason, ClientAuth, ClientHandshake, ConfigValidationResult, ContractExecuteInput, ContractPublishInput, ContractRegisterResult, ContractResponseSchema, CreatePolicyInput, DataGetInput, DataGetResponse, DataListInput, DataListResponse, DeleteDataInput, DeleteGrantsInput, DeleteScopeInput, Did, Direction, DkgAttestation, DkgVerifyResult, EmailOtpAuthInput, EmailOtpCredentials, Environment, EthAuthInput, ExecuteBusinessContractOptions, ExecuteOrgDataActionOptions, GetUsageOptions, GrantsGetInput, GuestToHostHandler, GuestToHostHandlers, HandshakeResult, JsonRpcRequest, JsonRpcResponse, KycPollCadence, KycPollOptions, KycStatus, KycStatusKind, Logger, MapCreateInput, MapResponse, MapUpdateInput, MapVisibility, MutationResponse, OidcAuthInput, OidcCredentials, OrgContractGrants, OrgDataActionWire, OrgDataClientOptions, OrgPolicyMeta, OrgPolicyView, OrgWriters, OtpChannel, OtpMergeSuggestion, OtpRequestInput, OtpRequestResult, OtpVerifyInput, OtpVerifyResult, PayrollRunRequest, PeerQuoteResult, PolicyGetInput, QuoteVerifyResult, ReaderSet, SdkConfig, SessionCrypto, SessionId, SetGrantsInput, SetWritersInput, SubmitUserInputArgs, SubmitUserInputResult, T3nClientConfig, TenantAdmitProjection, TenantAdmitStatus, TenantBaseClient, TenantClientConfig, TenantContractExecuteInput, TenantContractPublishInput, TenantExecutionSession, TenantMapCreateInput, TenantMapUpdatePatch, TenantMeResponse, TenantSdkEnvironment, TenantSelfAdmitResult, TenantStatus, TenantTargetOptions, TokenTxKind, Transport, TrustAnchor, TrustAnchorOrUnsafe, UnsafeTrustServer, UpdateMetaInput, UsageEntry, UsagePage, UserGrant, UserInputProfile, UserUpsertErrorKind, WasmComponent, WasmNextResult, WorkloadAuthInput, WriteDataInput, WriterSet, WritersGetInput };