@terminal3/t3n-sdk 0.6.0 → 0.8.0

package/dist/index.d.ts

@@ -278,11 +278,16 @@ declare enum AuthMethod {
     OIDC = "oidc"
 }
 /**
- * OIDC credentials interface
+ * OIDC credentials interface.
+ *
+ * The TEE generates a session-binding nonce that must be included in
+ * the Google authorization URL (`&nonce=…`). The `getIdToken` callback
+ * receives this nonce and must return the `id_token` JWT obtained
+ * from the OIDC provider with the nonce baked into its claims.
  */
 interface OidcCredentials {
     provider: string;
-    idToken: string;
+    getIdToken: (nonce: string) => Promise<string>;
 }
 /**
  * Base authentication input with method discriminator
@@ -522,9 +527,27 @@ declare class T3nClient {
      */
     handshake(): Promise<HandshakeResult>;
     /**
-     * Authenticate with the T3n node
+     * Authenticate with the T3n node.
+     *
+     * For OIDC, this runs a two-step nonce-bound flow:
+     * 1. Sends `InitOidcAuth` to server → receives session-binding nonce.
+     * 2. Calls `getIdToken(nonce)` callback so the app can include the
+     *    nonce in the Google authorization URL.
+     * 3. Sends `SubmitIdToken` with the nonce-bearing token → receives DID.
      */
     authenticate(authInput: AuthInput): Promise<Did>;
+    /**
+     * OIDC two-step authentication with session-binding nonce.
+     *
+     * Bypasses the WASM client state machine and makes two encrypted
+     * RPC calls directly:
+     * 1. `InitOidcAuth { provider }` → server generates nonce → returns
+     *    `ProvideNonce { nonce }`.
+     * 2. App calls `getIdToken(nonce)` to obtain a nonce-bound `id_token`.
+     * 3. `SubmitIdToken { id_token }` → server verifies token + nonce →
+     *    returns `Finish { did }`.
+     */
+    private authenticateOidc;
     /**
      * Execute an action on the T3n node
      */
@@ -766,6 +789,65 @@ 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
  */
@@ -789,6 +871,18 @@ declare function validateConfig(config: unknown): ConfigValidationResult;
  * or by passing `baseUrl` to `T3nClient`.
  */
 declare const NODE_URLS: Record<Environment, string>;
+/** DKG attestation bundle from the cluster. */
+interface DkgAttestation {
+    /** Sorted base58 peer IDs that participated in DKG. */
+    peer_ids: string[];
+    /** Per-node TDX quotes keyed by base58 peer ID (base64-encoded). */
+    quotes: Record<string, string>;
+    /**
+     * Base64-encoded raw attestation message: `encaps_key || sorted_peer_ids`.
+     * Each quote's `report_data` is `keccak512(attestation_msg)`.
+     */
+    attestation_msg: string;
+}
 /**
  * Set the active environment. Clears any previous URL override and the key
  * cache so the next fetch uses the new environment's default URL.
@@ -809,10 +903,30 @@ declare function setNodeUrl(url: string | null): void;
 /** Resolve the active node URL: explicit `baseUrl` > override > env default. */
 declare function getNodeUrl(baseUrl?: string): string;
 /**
- * Fetch the ML-KEM root public key from `${nodeUrl}/status`. Cached per URL.
- * The node must be in the `Ready` phase and expose `encaps_key`.
+ * Fetch the ML-KEM root public key from `${nodeUrl}/status`. Cached
+ * per URL because the key is stable for the cluster's lifetime (a
+ * new DKG means a full redeploy; callers clear the cache via
+ * `clearKeyCache()` or `setNodeUrl()` in that case).
+ *
+ * Returns only the base64-encoded key. For the DKG attestation
+ * bundle (which changes over time as peer quotes replicate via
+ * Raft), call `fetchDkgAttestation()` \u2014 that path is
+ * intentionally uncached.
  */
 declare function fetchMlKemPublicKey(baseUrl?: string): Promise<string>;
+/**
+ * Fetch the DKG attestation bundle from `${nodeUrl}/status`. Never
+ * cached \u2014 peer quotes are written to consensus KV asynchronously
+ * during cluster bootstrap, so early reads may see a subset of the
+ * expected quotes. Caching would pin an incomplete bundle and cause
+ * spurious `valid_count < expected_count` failures in
+ * `verifyDkgAttestation()` for the whole process lifetime.
+ *
+ * Returns `undefined` when the node has not yet published an
+ * attestation (e.g. still bootstrapping, or running with a mock
+ * signer where attestation is skipped by design).
+ */
+declare function fetchDkgAttestation(baseUrl?: string): Promise<DkgAttestation | undefined>;
 /** Clear the cached ML-KEM public keys. Useful in tests. */
 declare function clearKeyCache(): void;
 /**
@@ -822,5 +936,5 @@ declare function clearKeyCache(): void;
  */
 declare function loadConfig(baseUrl?: string): SdkConfig;
 
-export { AuthMethod, AuthenticationError, HandshakeError, HttpTransport, LogLevel, MockTransport, NODE_URLS, RpcError, SessionStateError, SessionStatus, T3nClient, T3nError, WasmError, bytesToString, clearKeyCache, createDefaultHandlers, createEthAuthInput, createLogger, createMlKemPublicKeyHandler, createOidcAuthInput, createRandomHandler, decodeWasmErrorMessage, eth_get_address, extractWasmError, fetchMlKemPublicKey, generateRandomString, generateUUID, getEnvironment, getEnvironmentName, getGlobalLogLevel, getLogger, getNodeUrl, getScriptVersion, loadConfig, loadWasmComponent, metamask_get_address, metamask_sign, redactSecrets, redactSecretsFromJson, setEnvironment, setGlobalLogLevel, setNodeUrl, stringToBytes, validateConfig };
-export type { AuthInput, ClientAuth, ClientHandshake, ConfigValidationResult, Did, Environment, EthAuthInput, GuestToHostHandler, GuestToHostHandlers, HandshakeResult, JsonRpcRequest, JsonRpcResponse, Logger, OidcAuthInput, OidcCredentials, SdkConfig, SessionCrypto, SessionId, T3nClientConfig, Transport, WasmComponent, WasmNextResult };
+export { AuthMethod, AuthenticationError, HandshakeError, HttpTransport, LogLevel, MockTransport, NODE_URLS, RpcError, SessionStateError, SessionStatus, T3nClient, T3nError, WasmError, bytesToString, clearKeyCache, createDefaultHandlers, createEthAuthInput, createLogger, createMlKemPublicKeyHandler, createOidcAuthInput, createRandomHandler, decodeWasmErrorMessage, eth_get_address, extractWasmError, fetchDkgAttestation, fetchMlKemPublicKey, generateRandomString, generateUUID, getEnvironment, getEnvironmentName, getGlobalLogLevel, getLogger, getNodeUrl, getScriptVersion, loadConfig, loadWasmComponent, metamask_get_address, metamask_sign, redactSecrets, redactSecretsFromJson, setEnvironment, setGlobalLogLevel, setNodeUrl, stringToBytes, validateConfig, verifyDkgAttestation, verifyTdxQuote };
+export type { AuthInput, ClientAuth, ClientHandshake, ConfigValidationResult, Did, DkgAttestation, DkgVerifyResult, Environment, EthAuthInput, GuestToHostHandler, GuestToHostHandlers, HandshakeResult, JsonRpcRequest, JsonRpcResponse, Logger, OidcAuthInput, OidcCredentials, PeerQuoteResult, QuoteVerifyResult, SdkConfig, SessionCrypto, SessionId, T3nClientConfig, Transport, WasmComponent, WasmNextResult };