@terminal3/t3n-sdk 4.20.0 → 4.22.0

package/dist/index.d.ts

@@ -1997,12 +1997,15 @@ declare class T3nClient {
      * standard authenticated `action.execute` path. The node injects the
      * caller's DID into the contract call context, and the contract refuses
      * unless the caller is listed as an admin of `organisationDid`. A brand
-     * new secp256k1 wallet is minted in-TEE for the agent; its eth-derived
-     * DID and its raw private key are both returned. The private key is the
-     * "authentication token" the MCP sidecar uses to authenticate as this
-     * agent (the existing `PRIVATE_KEY` eth auth mode) — it is generated and
-     * returned exactly once here and is never persisted or recoverable
-     * afterwards, so the caller must capture it immediately.
+     * new secp256k1 wallet is minted in-TEE for the agent (its eth-derived
+     * DID is returned), but the raw private key never leaves the TEE.
+     * Instead the contract mints an opaque bearer API key —
+     * `t3n_key_<key_id_hex>.<secret_hex>` — and returns it plus its `keyId`
+     * (the 16-hex lookup id). The `apiKey` is the credential relayed verbatim
+     * in the `X-T3N-Api-Key` header of a stateless `POST /api/invoke` call; only
+     * its hash is stored on-ledger, so it is generated and returned exactly
+     * once here and is never persisted or recoverable afterwards — the caller
+     * must capture it immediately.
      *
      * Atomic provisioning + card hosting: the SAME transaction mints the
      * agent, writes the agent-registry record (owner binding + the org's
@@ -2027,8 +2030,8 @@ declare class T3nClient {
      *   (`did:t3n:<40-hex>`); the caller must be one of its admins
      * @param name - human-readable agent name (1..=128 bytes)
      * @param options - optional atomic registration + card hosting
-     * @returns the new agent's DID and its one-time private key, plus
-     *   `agentUri` / `cardEntryId` (the hosted PRIVATE card's entry id)
+     * @returns the new agent's DID and its one-time opaque `apiKey` + `keyId`,
+     *   plus `agentUri` / `cardEntryId` (the hosted PRIVATE card's entry id)
      *   when the atomic path ran
      * @throws if the session is not authenticated, or if the contract
      *   refuses (e.g. the caller is not an admin of `organisationDid`, the
@@ -2041,7 +2044,8 @@ declare class T3nClient {
         defaultCard?: boolean;
     }): Promise<{
         agentDid: Did;
-        privateKey: string;
+        apiKey: string;
+        keyId: string;
         agentUri?: string;
         cardEntryId?: string;
     }>;
@@ -2784,6 +2788,123 @@ declare function createRandomHandler(): GuestToHostHandler;
  */
 declare function createDefaultHandlers(baseUrl: string, trustAnchor: TrustAnchorOrUnsafe): GuestToHostHandlers;
 
+/**
+ * Stateless `api_key` agent auth.
+ *
+ * `invoke` posts once to `POST /api/invoke` — an HTTPS-only
+ * endpoint (see the HTTPS-guard note below) that authenticates an org agent
+ * by an opaque API key (`X-T3N-Api-Key: t3n_key_<...>`) and executes a
+ * `z:` contract as that agent in the SAME request. Unlike
+ * {@link T3nClient.execute}, there is **no** ML-KEM handshake, **no**
+ * `Session-Id`, and **no** session state: the node derives the acting agent
+ * DID from the relayed key per-call (`resolve_stateless_credential`
+ * driving the session contract's `api_key` action), then runs the same
+ * execute pipeline `action.execute` runs after `check_authentication`
+ * (`ActionService::execute_as_did`), and returns the contract's decoded
+ * result as a plain `Json(result)` body — NOT a JSON-RPC envelope.
+ *
+ * Because the response is the bare decoded value (no `{jsonrpc,result,id}`
+ * wrapper to unwrap), decoding reuses {@link parseContractResponse} — the
+ * exact same JSON.parse + optional-schema path {@link T3nClient.executeAndDecode}
+ * uses for the session `execute` RPC — so callers get identical typed /
+ * schema-validated decoding on either path.
+ *
+ * This module intentionally does NOT import {@link T3nClient}, the WASM
+ * component loader, or any handshake/session machinery — `invoke` is
+ * a single fetch, nothing else.
+ *
+ * ### HTTPS guard (CodeRabbit T2)
+ * The API key is a long-lived bearer credential relayed in a plain header,
+ * so `invoke` refuses to send it over an insecure transport: `baseUrl`
+ * must be `https:`, unless the host is a local-dev loopback
+ * (`localhost` / `127.0.0.1` / `[::1]`), in which case plain `http:` is
+ * allowed. The check runs before any network activity — an insecure
+ * `baseUrl` never gets as far as a `fetch` call.
+ *
+ * ### Error hygiene (CodeRabbit T3/T4/T5)
+ * Every error `invoke` throws is a fixed, generic
+ * {@link InvokeError} message — the response body text, the
+ * underlying network error's message, and the api key are never
+ * interpolated into it. This is defense in depth against a server (or a
+ * malicious intermediary) that echoes the key or other secrets back in an
+ * error body: whatever comes back over the wire on a non-2xx response is
+ * discarded, not surfaced. The timeout timer also stays armed until the
+ * response body has been fully read (or has itself timed out) — see
+ * {@link invoke}'s implementation — so a connection that delivers
+ * headers and then stalls on the body still respects `timeoutMs`.
+ */
+
+/**
+ * Wire body for `POST /api/invoke` — mirrors the server's
+ * server-side `ExecuteActionRequest`, the same shape
+ * `T3nClient`'s `execute*` wrappers build for the session `action.execute`
+ * RPC. Field names are load-bearing: the server deserialises strictly into
+ * `script_name` / `script_version` / `function_name` (see
+ * `T3nClient.executeSystemContract`'s doc comment) — `contract` / `version`
+ * / `function` produce a 400.
+ */
+interface InvokeRequest {
+    script_name: string;
+    script_version: string;
+    function_name: string;
+    /** Delegated-call target member; omitted for a self (non-delegated) call. */
+    pii_did?: string;
+    input?: unknown;
+}
+/** Options for {@link invoke}. */
+interface InvokeOptions {
+    /**
+     * RPC base URL of the T3n node, e.g. `https://node.example.com`. Must be
+     * `https:` unless the host is a local-dev loopback (`localhost` /
+     * `127.0.0.1` / `[::1]`) — see the module doc comment's HTTPS-guard note.
+     */
+    baseUrl: string;
+    /**
+     * The agent's opaque API key (`t3n_key_<...>`), relayed verbatim in the
+     * `X-T3N-Api-Key` header. Never logged and never interpolated into any
+     * error this module throws — see the module doc comment and
+     * {@link InvokeError}.
+     */
+    apiKey: string;
+    /** The wire request to execute, built to the {@link InvokeRequest} shape. */
+    request: InvokeRequest;
+    /** Fetch timeout in ms. Defaults to 30s, matching {@link HttpTransport}. */
+    timeoutMs?: number;
+}
+/**
+ * Thrown when `POST /api/invoke` fails at the transport or HTTP
+ * layer (network failure, timeout, non-2xx status). Contract-level errors
+ * the node returns as a 2xx JSON error value are NOT wrapped here — they
+ * flow through {@link parseContractResponse}'s normal return, same as the
+ * session `execute` path.
+ *
+ * The message is always one of a small set of fixed, generic strings — it
+ * NEVER contains the raw api key, the response body text, or the
+ * underlying network error's message (CodeRabbit T4/T5): a server (or a
+ * misbehaving intermediary) that echoes the key or other secrets back in
+ * an error body must not be able to leak them through this error's
+ * message.
+ */
+declare class InvokeError extends T3nError {
+    readonly status?: number | undefined;
+    constructor(message: string, status?: number | undefined);
+}
+/**
+ * Execute a `z:` contract as an org agent, authenticating with an opaque
+ * API key — one request, no handshake, no session.
+ *
+ * @param opts - baseUrl, apiKey, and the wire request to execute
+ * @param schema - optional validator applied to the decoded result (e.g. a
+ *   zod schema); anything exposing `.parse(value)` is accepted, same as
+ *   {@link T3nClient.executeAndDecode}
+ * @returns the contract's decoded result, typed as `T`
+ * @throws {InvokeError} if `baseUrl` is insecure, on a network
+ *   failure/timeout, or on a non-2xx response
+ * @throws {ContractResponseError} if the node returns a 2xx with a body
+ *   that is not valid JSON
+ */
+declare function invoke<T = unknown>(opts: InvokeOptions, schema?: ContractResponseSchema<T>): Promise<T>;
+
 /**
  * Token fixed-point units (USDT-style 6 decimals).
  *
@@ -4494,5 +4615,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, 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 };
+export { AGENT_CARDS_SCOPE, AuthMethod, AuthenticationError, BASE_UNITS_PER_TOKEN, ContractResponseError, DEFAULT_ENVIRONMENT, DEFAULT_INDIVIDUAL_THRESHOLD_CENTS, DEFAULT_KYC_POLL_CADENCE, HandshakeError, HttpTransport, InvokeError, 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, invoke, 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, InvokeOptions, InvokeRequest, 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 };