@terminal3/t3n-sdk 4.19.0 → 4.20.0

package/dist/index.d.ts

@@ -3898,6 +3898,116 @@ interface ConfigValidationResult {
     errors: string[];
 }
 
+/**
+ * Operator-signed trust-manifest distribution.
+ *
+ * The SDK's attestation check (see `TrustAnchor`) needs a trusted source
+ * for the expected cluster identity — the set of node peer IDs and the
+ * allow-listed RTMR3 image measurements. Without a trusted source, every
+ * caller has to hand-pin those values or fall back to
+ * `{ unsafe_trust_server: true }`, which disables verification entirely.
+ *
+ * A trust manifest is a small JSON document published by the cluster
+ * operator to a public URL (a GCS bucket) and signed with the operator's
+ * secp256k1 key. Its public half is baked into the SDK per environment
+ * (`OPERATOR_PUBLIC_KEYS`). `fetchTrustedManifest(env)` fetches the
+ * manifest, verifies the signature against the pinned operator key, and
+ * returns a {@link TrustAnchor} that plugs straight into
+ * `T3nClientConfig.trustAnchor`.
+ *
+ * Trust model: the operator key is the root of trust. A network attacker
+ * can serve any bytes at the manifest URL, but cannot forge a signature
+ * for a manifest naming their own node identities/measurements without
+ * the operator's private key. The manifest only ever *narrows* trust to
+ * the real cluster — it never widens what the on-quote RTMR3 pinning and
+ * peer-id set-equality already enforce inside the WASM verifier.
+ */
+
+/**
+ * The signed payload an operator publishes. `signature` covers every
+ * other field (see {@link canonicalManifestBytes}); it is excluded from
+ * its own signing input.
+ */
+interface SignedTrustManifest {
+    /** Environment the manifest describes (e.g. `"production"`). */
+    cluster: string;
+    /** Monotonic manifest version; lets a client reject a rolled-back manifest. */
+    version: number;
+    /** Base58 peer IDs of the expected cluster nodes. */
+    peer_ids: string[];
+    /** Base64-encoded 48-byte RTMR3 measurements of the expected image(s). */
+    rtmr3_allowlist: string[];
+    /** RFC 3339 timestamp the manifest was signed. */
+    signed_at: string;
+    /** Hex secp256k1 signature (compact 64-byte r‖s) over the canonical payload. */
+    signature: string;
+}
+/** The payload fields the signature covers — the manifest minus `signature`. */
+type TrustManifestPayload = Omit<SignedTrustManifest, "signature">;
+/**
+ * Verify a manifest's signature against an operator public key (hex
+ * compressed secp256k1). Returns `true` iff the signature is valid for
+ * the manifest's canonical payload. Never throws on a bad signature —
+ * malformed inputs (non-hex key/signature) return `false`.
+ */
+declare function verifyManifestSignature(manifest: SignedTrustManifest, operatorPublicKeyHex: string): boolean;
+/** Project a verified manifest onto the `TrustAnchor` the client pins. */
+declare function manifestToTrustAnchor(manifest: SignedTrustManifest): TrustAnchor;
+/** Options for {@link fetchTrustedManifest}. */
+interface FetchTrustedManifestOptions {
+    /**
+     * Override the node base URL the manifest is fetched from (defaults to
+     * the environment's `NODE_URLS` entry). Use for a private-cloud cluster
+     * on a custom host — the manifest is served at `<baseUrl>/api/trust-manifest`.
+     */
+    baseUrl?: string;
+    /**
+     * Override the full manifest URL outright (takes precedence over
+     * `baseUrl`). Primarily for tests and non-standard deployments.
+     */
+    manifestUrl?: string;
+    /**
+     * Override the operator public key (hex compressed secp256k1). Defaults
+     * to the SDK-pinned key for the environment. Primarily for tests.
+     */
+    operatorPublicKeyHex?: string;
+    /**
+     * Reject any manifest whose `version` is below this floor, even when its
+     * signature is valid. Pass this when the application persists the last
+     * accepted version across restarts — it closes the rollback window the
+     * in-process high-water mark cannot cover (a fresh process trusts the
+     * first manifest it sees).
+     */
+    minVersion?: number;
+}
+/** Reset the per-environment rollback floor. Useful in tests. */
+declare function clearManifestVersionFloor(): void;
+/**
+ * Fetch and verify the operator-signed trust manifest for an environment,
+ * returning a {@link TrustAnchor} ready to pass as
+ * `T3nClientConfig.trustAnchor`.
+ *
+ * Throws if the environment has no pinned operator key (the manifest
+ * infrastructure is not provisioned for it yet), if the manifest cannot
+ * be fetched or is malformed, if the signature does not verify against
+ * the pinned operator key, or if the manifest's `version` is below the
+ * rollback floor (see {@link FetchTrustedManifestOptions.minVersion}).
+ * It never returns an unverified anchor.
+ *
+ * Deliberately uncached (unlike the ML-KEM `keyCache`): the manifest is
+ * re-published on deploys and this function is expected to run once per
+ * application startup, not per handshake. Fetch it once, keep the
+ * returned anchor for the process lifetime, and re-fetch only when a
+ * handshake starts failing verification (a sign the cluster rolled).
+ *
+ * The manifest is served by the node itself at `/api/trust-manifest`
+ * (there is no external bucket) — same origin as the node the anchor
+ * describes. That co-location does not weaken the trust: authenticity is
+ * the operator signature verified against the SDK-pinned key, and the
+ * monotonic version floor rejects replays of an old signed manifest.
+ */
+declare function fetchTrustedManifest(env: Environment, opts?: FetchTrustedManifestOptions): Promise<TrustAnchor>;
+
 /**
  * Configuration validation for T3n SDK
  */
@@ -4384,5 +4494,5 @@ declare function tenantDidHex(tenantDid: string): string;
 declare function validateTail(tail: string): string;
 declare function canonicalTenantName(tenantDid: string, tail: string): string;
 
-export { AGENT_CARDS_SCOPE, 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, SessionUsageReportClient, T3nClient, T3nError, TERMINAL_KYC_STATUSES, TOKEN_DECIMALS, TenantClient, TenantContractsNamespace, TenantMapsNamespace, TenantNamespace, TenantSdkValidationError, TenantTokenNamespace, UnsupportedTenantSdkOperationError, UserUpsertError, WasmError, WireEncodingError, 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, createUsageReportClientFromSession, createWorkloadAuthInput, decodeWasmErrorMessage, deriveAgentCardEntryId, eth_get_address, extractWasmError, fetchDkgAttestation, fetchMlKemPublicKey, formatTokens, generateRandomString, generateUUID, getEnvironment, getEnvironmentName, getGlobalLogLevel, getLogger, getNodeUrl, getScriptVersion, isAgentCardResponse, isDataGetResponse, isDataListResponse, isMutationResponse, isObject, isOrgAdminStatus, isOrgContractGrants, isOrgPolicyMeta, isOrgPolicyView, isOrgUsageReport, isOrgWriters, isRoleAssignmentsResponse, isRoleGetResponse, isUnsafeTrustServer, loadConfig, loadWasmComponent, maskKeyMaterial, mergeAgentAuthEntries, mergeDiscoverDids, metamask_get_address, metamask_sign, parseAgentAuthGet, parseAgentAuthPolicy, parseContractResponse, redactSecrets, redactSecretsFromJson, requestToWire, setEnvironment, setGlobalLogLevel, setNodeUrl, stringToBytes, tenantDidHex, toAgentAuthUpdateWire, toBaseUnits, validateConfig, validateTail, verifyDkgAttestation, verifyTdxQuote };
-export type { AdmitForOrgOptions, AgentAuthEntry, AgentAuthMergeResult, AgentAuthPolicy, AgentAuthScriptGrant, AgentAuthUpdateInput, AgentCardRefInput, AgentCardResponse, AgentCardSetInput, AssignRolesInput, AuthInput, BalanceRow, ChargeReason, ClientAuth, ClientHandshake, ConfigValidationResult, ContractExecuteInput, ContractKind, ContractPublishInput, ContractRegisterResult, ContractResponseSchema, ContractSetDescriptorInput, CreatePolicyInput, DataGetInput, DataGetResponse, DataListInput, DataListResponse, DelegationGrantKind, DelegationGrantRef, DeleteDataInput, DeleteGrantsInput, DeleteScopeInput, Did, Direction, DkgAttestation, DkgVerifyResult, EmailOtpAuthInput, EmailOtpCredentials, Environment, EthAuthInput, ExecuteBusinessContractOptions, ExecuteOrgDataActionOptions, GetUsageOptions, GrantCheckParams, GrantCheckResult, GranteeInput, GrantsGetInput, GuestToHostHandler, GuestToHostHandlers, HandshakeResult, JsonRpcRequest, JsonRpcResponse, KycPollCadence, KycPollOptions, KycStatus, KycStatusKind, ListContractsParams, ListContractsResult, ListContractsScope, ListedContract, Logger, MapCreateInput, MapLifecycleStatus, MapResponse, MapUpdateInput, MapVisibility, MutationResponse, OidcAuthInput, OidcCredentials, OrgAdminStatus, OrgContractGrants, OrgDataActionWire, OrgDataClientOptions, OrgPolicyMeta, OrgPolicyView, OrgUsageReport, OrgUsageReportInput, OrgWriters, OtpChannel, OtpMergeSuggestion, OtpRequestInput, OtpRequestResult, OtpVerifyInput, OtpVerifyResult, PayrollRunRequest, PeerQuoteResult, PolicyGetInput, PurgeOrgInput, QuoteVerifyResult, ReaderSet, RemoveMemberGrantsInput, RoleAssignments, RoleAssignmentsResponse, RoleDefinition, RoleGetResponse, RoleGrant, RoleIdInput, SdkConfig, SessionCrypto, SessionId, SetGrantsInput, SetRoleInput, SetWritersInput, StringEncoding, SubmitUserInputArgs, SubmitUserInputResult, T3nClientConfig, TenantAdmitProjection, TenantAdmitStatus, TenantBaseClient, TenantClientConfig, TenantContractExecuteInput, TenantContractPublishInput, TenantContractSetDescriptorInput, TenantExecutionSession, TenantMapCreateInput, TenantMapUpdatePatch, TenantMeResponse, TenantSdkEnvironment, TenantSelfAdmitResult, TenantStatus, TenantTargetOptions, TokenTxKind, Transport, TrustAnchor, TrustAnchorOrUnsafe, UnassignRolesInput, UnsafeTrustServer, UpdateMetaInput, UsageEntry, UsagePage, UsageReportSignature, UserGrant, UserInputProfile, UserUpsertErrorKind, WasmComponent, WasmNextResult, WireBlock, WorkloadAuthInput, WriteDataInput, WriterSet, WritersGetInput };
+export { AGENT_CARDS_SCOPE, 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, SessionUsageReportClient, T3nClient, T3nError, TERMINAL_KYC_STATUSES, TOKEN_DECIMALS, TenantClient, TenantContractsNamespace, TenantMapsNamespace, TenantNamespace, TenantSdkValidationError, TenantTokenNamespace, UnsupportedTenantSdkOperationError, UserUpsertError, WasmError, WireEncodingError, Z_PAYROLL_AUDIT_READ_FUNCTIONS, Z_PAYROLL_RUN_FUNCTIONS, _b64uEncode, assertShape, b64uDecodeStrict, b64uEncodeBytes, bytesToString, canonicalTenantName, clearKeyCache, clearManifestVersionFloor, compactDidFromBytes, createDefaultHandlers, createEmailOtpAuthInput, createEthAuthInput, createLogger, createMlKemPublicKeyHandler, createOidcAuthInput, createOrgDataClientFromSession, createRandomHandler, createUsageReportClientFromSession, createWorkloadAuthInput, decodeWasmErrorMessage, deriveAgentCardEntryId, eth_get_address, extractWasmError, fetchDkgAttestation, fetchMlKemPublicKey, fetchTrustedManifest, formatTokens, generateRandomString, generateUUID, getEnvironment, getEnvironmentName, getGlobalLogLevel, getLogger, getNodeUrl, getScriptVersion, isAgentCardResponse, isDataGetResponse, isDataListResponse, isMutationResponse, isObject, isOrgAdminStatus, isOrgContractGrants, isOrgPolicyMeta, isOrgPolicyView, isOrgUsageReport, isOrgWriters, isRoleAssignmentsResponse, isRoleGetResponse, isUnsafeTrustServer, loadConfig, loadWasmComponent, manifestToTrustAnchor, maskKeyMaterial, mergeAgentAuthEntries, mergeDiscoverDids, metamask_get_address, metamask_sign, parseAgentAuthGet, parseAgentAuthPolicy, parseContractResponse, redactSecrets, redactSecretsFromJson, requestToWire, setEnvironment, setGlobalLogLevel, setNodeUrl, stringToBytes, tenantDidHex, toAgentAuthUpdateWire, toBaseUnits, validateConfig, validateTail, verifyDkgAttestation, verifyManifestSignature, verifyTdxQuote };
+export type { AdmitForOrgOptions, AgentAuthEntry, AgentAuthMergeResult, AgentAuthPolicy, AgentAuthScriptGrant, AgentAuthUpdateInput, AgentCardRefInput, AgentCardResponse, AgentCardSetInput, AssignRolesInput, AuthInput, BalanceRow, ChargeReason, ClientAuth, ClientHandshake, ConfigValidationResult, ContractExecuteInput, ContractKind, ContractPublishInput, ContractRegisterResult, ContractResponseSchema, ContractSetDescriptorInput, CreatePolicyInput, DataGetInput, DataGetResponse, DataListInput, DataListResponse, DelegationGrantKind, DelegationGrantRef, DeleteDataInput, DeleteGrantsInput, DeleteScopeInput, Did, Direction, DkgAttestation, DkgVerifyResult, EmailOtpAuthInput, EmailOtpCredentials, Environment, EthAuthInput, ExecuteBusinessContractOptions, ExecuteOrgDataActionOptions, FetchTrustedManifestOptions, GetUsageOptions, GrantCheckParams, GrantCheckResult, GranteeInput, GrantsGetInput, GuestToHostHandler, GuestToHostHandlers, HandshakeResult, JsonRpcRequest, JsonRpcResponse, KycPollCadence, KycPollOptions, KycStatus, KycStatusKind, ListContractsParams, ListContractsResult, ListContractsScope, ListedContract, Logger, MapCreateInput, MapLifecycleStatus, MapResponse, MapUpdateInput, MapVisibility, MutationResponse, OidcAuthInput, OidcCredentials, OrgAdminStatus, OrgContractGrants, OrgDataActionWire, OrgDataClientOptions, OrgPolicyMeta, OrgPolicyView, OrgUsageReport, OrgUsageReportInput, OrgWriters, OtpChannel, OtpMergeSuggestion, OtpRequestInput, OtpRequestResult, OtpVerifyInput, OtpVerifyResult, PayrollRunRequest, PeerQuoteResult, PolicyGetInput, PurgeOrgInput, QuoteVerifyResult, ReaderSet, RemoveMemberGrantsInput, RoleAssignments, RoleAssignmentsResponse, RoleDefinition, RoleGetResponse, RoleGrant, RoleIdInput, SdkConfig, SessionCrypto, SessionId, SetGrantsInput, SetRoleInput, SetWritersInput, SignedTrustManifest, StringEncoding, SubmitUserInputArgs, SubmitUserInputResult, T3nClientConfig, TenantAdmitProjection, TenantAdmitStatus, TenantBaseClient, TenantClientConfig, TenantContractExecuteInput, TenantContractPublishInput, TenantContractSetDescriptorInput, TenantExecutionSession, TenantMapCreateInput, TenantMapUpdatePatch, TenantMeResponse, TenantSdkEnvironment, TenantSelfAdmitResult, TenantStatus, TenantTargetOptions, TokenTxKind, Transport, TrustAnchor, TrustAnchorOrUnsafe, TrustManifestPayload, UnassignRolesInput, UnsafeTrustServer, UpdateMetaInput, UsageEntry, UsagePage, UsageReportSignature, UserGrant, UserInputProfile, UserUpsertErrorKind, WasmComponent, WasmNextResult, WireBlock, WorkloadAuthInput, WriteDataInput, WriterSet, WritersGetInput };