@terminal3/t3n-sdk 2.13.0 → 3.1.0

package/README.md

@@ -27,17 +27,18 @@ import {
   loadWasmComponent,
   createEthAuthInput,
   eth_get_address,
-  eth_sign,
+  metamask_sign,
 } from "@terminal3/t3n-sdk";
 
 const wasmComponent = await loadWasmComponent();
 const privateKey = process.env.T3N_DEMO_KEY!;
+const address = eth_get_address(privateKey);
 
 const client = new T3nClient({
   baseUrl: "https://t3n-node.example.com",
   wasmComponent,
   handlers: {
-    EthSign: eth_sign(privateKey),
+    EthSign: metamask_sign(address, undefined, privateKey),
   },
 });
 
@@ -55,15 +56,16 @@ import {
   T3nClient,
   createEthAuthInput,
   eth_get_address,
-  eth_sign,
+  metamask_sign,
 } from "@terminal3/t3n-sdk";
 
 const privateKey = "0x...";
+const address = eth_get_address(privateKey);
 
 const client = new T3nClient({
   wasmComponent: await loadWasmComponent(),
   handlers: {
-    EthSign: eth_sign(privateKey),
+    EthSign: metamask_sign(address, undefined, privateKey),
   },
 });
 
@@ -306,7 +308,10 @@ interface T3nClientConfig {
 ### Example with Custom Configuration
 
 ```typescript
-import { T3nClient, LogLevel } from '@terminal3/t3n-sdk';
+import { T3nClient, LogLevel, eth_get_address, metamask_sign } from '@terminal3/t3n-sdk';
+
+const privateKey = process.env.T3N_DEMO_KEY!;
+const address = eth_get_address(privateKey);
 
 const client = new T3nClient({
   baseUrl: "https://t3n-node.example.com",
@@ -318,7 +323,7 @@ const client = new T3nClient({
     'X-Custom-Header': 'custom-value'
   },
   handlers: {
-    EthSign: eth_sign(privateKey),
+    EthSign: metamask_sign(address, undefined, privateKey),
     MlKemPublicKey: ml_kem_public_key(),
     Random: random(),
   }
@@ -873,11 +878,13 @@ To use the real WASM component:
 
 ### Mock Component for Testing
 
+`loadWasmComponent()` automatically falls back to a built-in mock when the real WASM file is not present. No extra setup needed in test environments:
+
 ```typescript
-import { createMockWasmComponent } from '@terminal3/t3n-sdk';
+import { loadWasmComponent } from '@terminal3/t3n-sdk';
 
-// Use mock component for testing
-const mockComponent = createMockWasmComponent();
+// In test environments (no real WASM file present), this returns a mock automatically
+const wasmComponent = await loadWasmComponent();
 ```
 
 ### WASM Component Features

package/dist/index.d.ts

@@ -1968,6 +1968,13 @@ declare const NONCE_LEN = 16;
 declare const REQUEST_HASH_LEN = 32;
 declare const AGENT_PUBKEY_LEN = 33;
 declare const ETH_SIG_LEN = 65;
+declare const MAX_FUNCTIONS_PER_CREDENTIAL = 16;
+/**
+ * Canonical sorted list of the payroll v2 function surface. One source
+ * of truth for callers building a full-cycle credential — pass this
+ * (or a sorted subset) as `functions` to {@link buildDelegationCredential}.
+ */
+declare const PAYROLL_FUNCTIONS_V1: readonly ["compute-payroll", "execute-disbursement", "finalize-audit", "submit-escalations", "validate-credentials"];
 /** User-to-agent delegation credential body. */
 interface DelegationCredential {
     /** Domain tag, must equal {@link DELEGATION_CREDENTIAL_DOMAIN}. */
@@ -1980,8 +1987,11 @@ interface DelegationCredential {
     org_did: string;
     /** Contract id, e.g. `"tee:payroll"`. */
     contract: string;
-    /** Function name, e.g. `"run-payroll"`. */
-    function: string;
+    /**
+     * Functions this credential authorises. Sorted ascending, deduped,
+     * each entry non-empty lowercase ASCII, 1..=16 entries.
+     */
+    functions: string[];
     /** Org-data scopes the contract may read on this user's behalf. */
     scopes: string[];
     /** Flat key-value labels checked against the org grant. */
@@ -2104,7 +2114,12 @@ interface BuildDelegationCredentialOpts {
     agent_pubkey: Uint8Array;
     org_did: string;
     contract: string;
-    function: string;
+    /**
+     * Functions this credential authorises. Must be non-empty, sorted
+     * ascending, deduped — the same invariants enforced by
+     * {@link validateCredentialBody}.
+     */
+    functions: string[];
     scopes?: string[];
     metadata?: Record<string, string>;
     not_before_secs: bigint | number;
@@ -2210,6 +2225,54 @@ declare class DelegationCustodialClient {
      */
     signCustodial(body: Record<string, unknown>): Promise<SignCustodialResult>;
 }
+/** Options for {@link revokeDelegation}. */
+interface RevokeDelegationOpts {
+    /** Credential body to revoke. Already-encoded base64url-no-pad JCS bytes. */
+    credentialJcsB64u: string;
+    /**
+     * Omit (or pass `undefined`) to revoke the whole credential. Pass an
+     * array of function names to revoke a subset; the array must obey the
+     * same sort + dedupe invariants the credential's `functions` field
+     * enforces, and each entry must already appear in the credential's
+     * `functions` list (a revocation can only narrow the set, never grow
+     * it).
+     */
+    revokedFunctions?: string[];
+    /** Authenticated {@link T3nClient} for the credential's `user_did`. */
+    client: T3nClient;
+    /**
+     * Override the resolved delegation contract version. Defaults to
+     * whatever `GET /api/contracts/current?name=tee:delegation/contracts`
+     * returns at call time.
+     */
+    scriptVersion?: string;
+    /** Override the node base URL used for `"latest"` resolution. */
+    baseUrl?: string;
+}
+/** Result of a successful {@link revokeDelegation} call. */
+interface RevokeDelegationResult {
+    /** Credential id (base64url-no-pad, no padding). */
+    vcId: string;
+    /**
+     * Mirrors the persisted revocation state after merging: `null` means
+     * whole-credential, a sorted array means per-function. The contract
+     * may return a larger set than `opts.revokedFunctions` when an
+     * earlier per-function revocation existed for the same credential.
+     */
+    revokedFunctions: string[] | null;
+}
+/**
+ * Wraps the `tee:delegation/contracts::revoke` entrypoint. Only the
+ * credential's `user_did` may call this — the contract reads the
+ * authenticated DID from session context and rejects any other caller
+ * with `NotCredentialHolder`.
+ *
+ * Merge semantics are handled server-side: whole-credential revocations
+ * are sticky, and per-function revocations accumulate as a sorted +
+ * deduped union across calls. The returned `revokedFunctions` reflects
+ * the persisted state after merging, not just this call's input.
+ */
+declare function revokeDelegation(opts: RevokeDelegationOpts): Promise<RevokeDelegationResult>;
 /** Options for {@link buildPayrollInvocation}. */
 interface BuildPayrollInvocationOpts {
     credentialJcs: Uint8Array;
@@ -2769,5 +2832,5 @@ declare function clearKeyCache(): void;
  */
 declare function loadConfig(baseUrl?: string): SdkConfig;
 
-export { AGENT_PUBKEY_LEN, AuthMethod, AuthenticationError, ContractResponseError, DEFAULT_INDIVIDUAL_THRESHOLD_CENTS, DEFAULT_KYC_POLL_CADENCE, DELEGATION_CREDENTIAL_DOMAIN, DELEGATION_INVOCATION_DOMAIN, DelegationCustodialClient, ETH_SIG_LEN, HandshakeError, HttpTransport, KycStatusTimeoutError, LogLevel, MockTransport, NODE_URLS, NONCE_LEN, OrgDataClient, REQUEST_HASH_LEN, RpcError, SessionExpiredError, SessionOrgDataClient, SessionStateError, SessionStatus, T3nClient, T3nError, TERMINAL_KYC_STATUSES, UserUpsertError, VC_ID_LEN, WasmError, _b64uEncode, assertShape, b64uDecodeStrict, b64uEncodeBytes, buildDelegationCredential, buildInvocationPreimage, buildPayrollDirectInvocation, buildPayrollInvocation, bytesToString, canonicaliseCredential, canonicaliseRequest, clearKeyCache, compactDidFromBytes, createDefaultHandlers, createEthAuthInput, createLogger, createMlKemPublicKeyHandler, createOidcAuthInput, createOrgDataClientFromSession, createRandomHandler, decodeWasmErrorMessage, eip191Digest, ethRecoverEip191, eth_get_address, extractWasmError, fetchDkgAttestation, fetchMlKemPublicKey, generateRandomString, generateUUID, getEnvironment, getEnvironmentName, getGlobalLogLevel, getLogger, getNodeUrl, getScriptVersion, isDataGetResponse, isDataListResponse, isMutationResponse, isObject, isOrgContractGrants, isOrgPolicyMeta, isOrgWriters, loadConfig, loadWasmComponent, metamask_get_address, metamask_sign, parseContractResponse, redactSecrets, redactSecretsFromJson, requestHash, setEnvironment, setGlobalLogLevel, setNodeUrl, signAgentInvocation, signCredential, stringToBytes, validateConfig, validateCredentialBody, verifyDkgAttestation, verifyTdxQuote };
-export type { AgeBand, AuthInput, BuildDelegationCredentialOpts, BuildPayrollDirectInvocationOpts, BuildPayrollInvocationOpts, ClientAuth, ClientHandshake, ConfigValidationResult, ContractResponseSchema, CreatePolicyInput, DataGetInput, DataGetResponse, DataListInput, DataListResponse, DelegationCredential, DelegationCustodialClientOpts, DelegationEnvelope, DeleteDataInput, DeleteGrantsInput, DeleteScopeInput, Did, DkgAttestation, DkgVerifyResult, EmployeeRecord, EmploymentStatus, Environment, EthAuthInput, ExecuteOrgDataActionOptions, ExpenseClaim, GrantsGetInput, GuestToHostHandler, GuestToHostHandlers, HandshakeResult, JsonRpcRequest, JsonRpcResponse, KycPollCadence, KycPollOptions, KycStatus, KycStatusKind, Logger, MutationResponse, OidcAuthInput, OidcCredentials, OrgContractGrants, OrgDataActionWire, OrgDataClientOptions, OrgPolicyMeta, OrgWriters, OtpChannel, OtpMergeSuggestion, OtpRequestInput, OtpRequestResult, OtpVerifyInput, OtpVerifyResult, PayrollInvocation, PayrollInvocationDelegated, PayrollInvocationDirect, PayrollRunRequest, PeerQuoteResult, PolicyGetInput, QuoteVerifyResult, ResidencyCategory, SdkConfig, SessionCrypto, SessionId, SetGrantsInput, SetWritersInput, SignCustodialResult, SignDelegationResponse, SubmitUserInputArgs, SubmitUserInputResult, T3nClientConfig, TenantAdmitProjection, TenantAdmitStatus, Transport, UpdateMetaInput, UserGrant, UserInputProfile, UserUpsertErrorKind, WasmComponent, WasmNextResult, WriteDataInput, WritersGetInput };
+export { AGENT_PUBKEY_LEN, AuthMethod, AuthenticationError, ContractResponseError, DEFAULT_INDIVIDUAL_THRESHOLD_CENTS, DEFAULT_KYC_POLL_CADENCE, DELEGATION_CREDENTIAL_DOMAIN, DELEGATION_INVOCATION_DOMAIN, DelegationCustodialClient, ETH_SIG_LEN, HandshakeError, HttpTransport, KycStatusTimeoutError, LogLevel, MAX_FUNCTIONS_PER_CREDENTIAL, MockTransport, NODE_URLS, NONCE_LEN, OrgDataClient, PAYROLL_FUNCTIONS_V1, REQUEST_HASH_LEN, RpcError, SessionExpiredError, SessionOrgDataClient, SessionStateError, SessionStatus, T3nClient, T3nError, TERMINAL_KYC_STATUSES, UserUpsertError, VC_ID_LEN, WasmError, _b64uEncode, assertShape, b64uDecodeStrict, b64uEncodeBytes, buildDelegationCredential, buildInvocationPreimage, buildPayrollDirectInvocation, buildPayrollInvocation, bytesToString, canonicaliseCredential, canonicaliseRequest, clearKeyCache, compactDidFromBytes, createDefaultHandlers, createEthAuthInput, createLogger, createMlKemPublicKeyHandler, createOidcAuthInput, createOrgDataClientFromSession, createRandomHandler, decodeWasmErrorMessage, eip191Digest, ethRecoverEip191, eth_get_address, extractWasmError, fetchDkgAttestation, fetchMlKemPublicKey, generateRandomString, generateUUID, getEnvironment, getEnvironmentName, getGlobalLogLevel, getLogger, getNodeUrl, getScriptVersion, isDataGetResponse, isDataListResponse, isMutationResponse, isObject, isOrgContractGrants, isOrgPolicyMeta, isOrgWriters, loadConfig, loadWasmComponent, metamask_get_address, metamask_sign, parseContractResponse, redactSecrets, redactSecretsFromJson, requestHash, revokeDelegation, setEnvironment, setGlobalLogLevel, setNodeUrl, signAgentInvocation, signCredential, stringToBytes, validateConfig, validateCredentialBody, verifyDkgAttestation, verifyTdxQuote };
+export type { AgeBand, AuthInput, BalanceRow, BuildDelegationCredentialOpts, BuildPayrollDirectInvocationOpts, BuildPayrollInvocationOpts, ChargeReason, ClientAuth, ClientHandshake, ConfigValidationResult, ContractResponseSchema, CreatePolicyInput, DataGetInput, DataGetResponse, DataListInput, DataListResponse, DelegationCredential, DelegationCustodialClientOpts, DelegationEnvelope, DeleteDataInput, DeleteGrantsInput, DeleteScopeInput, Did, Direction, DkgAttestation, DkgVerifyResult, EmployeeRecord, EmploymentStatus, Environment, EthAuthInput, ExecuteOrgDataActionOptions, ExpenseClaim, GetUsageOptions, GrantsGetInput, GuestToHostHandler, GuestToHostHandlers, HandshakeResult, JsonRpcRequest, JsonRpcResponse, KycPollCadence, KycPollOptions, KycStatus, KycStatusKind, Logger, MutationResponse, OidcAuthInput, OidcCredentials, OrgContractGrants, OrgDataActionWire, OrgDataClientOptions, OrgPolicyMeta, OrgWriters, OtpChannel, OtpMergeSuggestion, OtpRequestInput, OtpRequestResult, OtpVerifyInput, OtpVerifyResult, PayrollInvocation, PayrollInvocationDelegated, PayrollInvocationDirect, PayrollRunRequest, PeerQuoteResult, PolicyGetInput, QuoteVerifyResult, ResidencyCategory, RevokeDelegationOpts, RevokeDelegationResult, SdkConfig, SessionCrypto, SessionId, SetGrantsInput, SetWritersInput, SignCustodialResult, SignDelegationResponse, SubmitUserInputArgs, SubmitUserInputResult, T3nClientConfig, TenantAdmitProjection, TenantAdmitStatus, TokenTxKind, Transport, UpdateMetaInput, UsageEntry, UsagePage, UserGrant, UserInputProfile, UserUpsertErrorKind, WasmComponent, WasmNextResult, WriteDataInput, WritersGetInput };