@terminal3/t3n-sdk 4.37.0 → 4.38.0

package/dist/index.d.ts

@@ -1850,6 +1850,112 @@ interface GrantCheckResult {
     satisfied: DelegationGrantRef[];
     missing: DelegationGrantRef[];
 }
+/** Response for the `whoami` operation: who the key resolves to, and where. */
+interface WhoamiResult {
+    /** The DID the relayed api key resolves to. */
+    did: string;
+    /**
+     * The org DIDs the agent itself belongs to (its own agent-keyed membership),
+     * or `[]` when it belongs to none. Each is a valid `org_did` for
+     * `contracts.list` scope `"org"`, so this is the seed for browsing the agent's
+     * own orgs.
+     */
+    organisations: string[];
+    /**
+     * The agent's owning / managing DID — usually the org that created it. `null`
+     * for a missing record (agents created without a hosted card or agent URI have
+     * no registry record), a record with no owner link, or a malformed record
+     * (decode failure is logged at `WARN`, never a silent authority downgrade); a
+     * snapshot read failure is surfaced as an error, not reported as `null`. The
+     * owner link is mutable and may have changed since creation, so treat this as
+     * best-effort, not an authority.
+     */
+    owner: string | null;
+}
+/** Params for the `describe.contract` operation. */
+interface DescribeContractParams {
+    /**
+     * Registry name: `tee:<name>/contracts` (core) or `z:<tid>:<tail>` (tenant).
+     * The bare core form `contracts.list` presents (`tee:<name>` / `y:<name>`) is
+     * also accepted — the node maps it onto the `/contracts` registry key — so a
+     * `ListedContract.name` feeds straight in.
+     */
+    contract: string;
+    /** Explicit version; omitted resolves the current registered version. */
+    version?: string;
+}
+/** Params for the `describe.function` operation. */
+interface DescribeFunctionParams {
+    /**
+     * Registry name: `tee:<name>/contracts` (core) or `z:<tid>:<tail>` (tenant).
+     * The bare core form `contracts.list` presents (`tee:<name>` / `y:<name>`) is
+     * also accepted — the node maps it onto the `/contracts` registry key.
+     */
+    contract: string;
+    /** The single function to project from the contract's descriptor. */
+    function: string;
+    /** Explicit version; omitted resolves the current registered version. */
+    version?: string;
+}
+/**
+ * One function's descriptor entry — the `describe.function` result and the
+ * element type of a {@link ContractDescriptorDocument}'s `functions` array.
+ *
+ * Left open-ended: the descriptor document's full schema (argument schema,
+ * wire projection, auth requirements) is owned by the contract descriptor
+ * registry and served verbatim by the node. The named fields are the ones the
+ * node's descriptor path always presents.
+ */
+interface FunctionDescriptorEntry {
+    /** Contract function name (e.g. `compute-payroll`). */
+    name: string;
+    summary?: string;
+    /** Whether the function mutates state. */
+    mutates?: boolean;
+    [key: string]: unknown;
+}
+/**
+ * The node's descriptor document for a contract — the `descriptor` field of a
+ * {@link DescribeContractResult}. Open-ended for the same reason as
+ * {@link FunctionDescriptorEntry}: the node returns the registry's descriptor
+ * document verbatim.
+ */
+interface ContractDescriptorDocument {
+    name?: string;
+    version?: string;
+    summary?: string;
+    tags?: string[];
+    functions?: FunctionDescriptorEntry[];
+    [key: string]: unknown;
+}
+/**
+ * Result of the `describe.contract` operation. The node wraps the descriptor
+ * document with the resolved dispatch `version`, so an authorised describe hands
+ * back the exact `scriptVersion` an {@link invoke} call needs alongside the
+ * schema. Returned only on the authorised path; a gate miss or unknown contract
+ * yields the uniform non-disclosive error, never this wrapper.
+ */
+interface DescribeContractResult {
+    /** The canonical registry name, echoed from the request. */
+    contract: string;
+    /** The resolved dispatch version — pass as `scriptVersion` to `invoke`. */
+    version: string;
+    /** The contract's full descriptor document. */
+    descriptor: ContractDescriptorDocument;
+}
+/**
+ * Result of the `describe.function` operation: the resolved dispatch `version`
+ * paired with the single projected function entry. Same authorised-path-only
+ * guarantee as {@link DescribeContractResult}.
+ */
+interface DescribeFunctionResult {
+    /** The canonical registry name, echoed from the request. */
+    contract: string;
+    /** The resolved dispatch version — pass as `scriptVersion` to `invoke`. */
+    version: string;
+    /** The single projected function's descriptor entry. */
+    descriptor: FunctionDescriptorEntry;
+}
 
 /**
  * T3n Client - Main SDK class
@@ -2993,7 +3099,21 @@ declare function createDefaultHandlers(baseUrl: string, trustAnchor: TrustAnchor
  * component loader, or any handshake/session machinery — `invoke` is
  * a single fetch, nothing else.
  *
- * ### HTTPS guard (CodeRabbit T2)
+ * ### Keyed discovery transports
+ * Alongside `invoke` (which acts), this module exports the keyed **discovery**
+ * reads — {@link discoverWhoami}, {@link discoverListContracts},
+ * {@link discoverCheckDelegation}, {@link discoverDescribeContract},
+ * {@link discoverDescribeFunction}. They are the api-key counterpart of the
+ * session `T3nClient.listContracts` / `checkDelegation` reads: each POSTs a
+ * `{ method, params }` envelope to the node's `POST /api/discover` with the
+ * same `X-T3N-Api-Key` header, HTTPS guard, timeout, and key-safe error
+ * hygiene as `invoke`, and returns the node's raw JSON result. The session
+ * `T3nClient` methods are untouched — these live beside `invoke`, off the
+ * session client, so the relay reads never open a session. Every transport
+ * shares the {@link postKeyed} core, so there is one implementation of the
+ * secure-transport + secret-hygiene rules below, not two.
+ *
+ * ### HTTPS guard
  * 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
@@ -3001,7 +3121,7 @@ declare function createDefaultHandlers(baseUrl: string, trustAnchor: TrustAnchor
  * 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)
+ * ### Error hygiene
  * 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
@@ -3060,7 +3180,7 @@ interface InvokeOptions {
  *
  * 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
+ * underlying network error's message: 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.
@@ -3084,6 +3204,71 @@ declare class InvokeError extends T3nError {
  *   that is not valid JSON
  */
 declare function invoke<T = unknown>(opts: InvokeOptions, schema?: ContractResponseSchema<T>): Promise<T>;
+/**
+ * Transport options shared by the keyed discovery reads. Mirrors the transport
+ * half of {@link InvokeOptions} (no `request`; the operation params are the
+ * second argument of each read). Same HTTPS + secret-hygiene rules as `invoke`.
+ */
+interface DiscoverOptions {
+    /**
+     * RPC base URL of the T3n node, e.g. `https://node.example.com`. Must be
+     * `https:` unless the host is a local-dev loopback — see
+     * {@link InvokeOptions.baseUrl}.
+     */
+    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.
+     */
+    apiKey: string;
+    /** Fetch timeout in ms. Defaults to 30s, matching {@link invoke}. */
+    timeoutMs?: number;
+}
+/**
+ * `whoami` — resolve the DID the relayed key maps to. The node never
+ * trusts a caller-supplied DID; this is the relay's sole DID source.
+ *
+ * @throws {InvokeError} if `baseUrl` is insecure, on a network failure/timeout,
+ *   or on a non-2xx response
+ */
+declare function discoverWhoami(opts: DiscoverOptions): Promise<WhoamiResult>;
+/**
+ * `contracts.list` — the keyed counterpart of {@link T3nClient.listContracts}.
+ * Absent `params` (`{}`) lists the curated `core` contracts; `org` / `self`
+ * scopes are discovery-grant gated server-side (R5 non-disclosive empty page).
+ *
+ * @throws {InvokeError} — see {@link discoverWhoami}
+ */
+declare function discoverListContracts(opts: DiscoverOptions, params?: ListContractsParams): Promise<ListContractsResult>;
+/**
+ * `delegation.check` — the keyed counterpart of
+ * {@link T3nClient.checkDelegation}. Returns the `agent_auth ∩ UserGrant`
+ * verdict for the acting agent (as itself, or for `params.pii_did`).
+ *
+ * @throws {InvokeError} — see {@link discoverWhoami}
+ */
+declare function discoverCheckDelegation(opts: DiscoverOptions, params: GrantCheckParams): Promise<GrantCheckResult>;
+/**
+ * `describe.contract` — the authority-gated keyed describe read. Returns
+ * `{ contract, version, descriptor }`: the resolved dispatch `version` (the
+ * `scriptVersion` an {@link invoke} call needs) alongside the contract's full
+ * descriptor document. Unlike the session/stdio public descriptor GET, the relay
+ * path is membership-gated on the contract's owning org and returns a uniform
+ * non-disclosive error for both "not found" and "not authorised"
+ * (anti-enumeration).
+ *
+ * @throws {InvokeError} — see {@link discoverWhoami}
+ */
+declare function discoverDescribeContract(opts: DiscoverOptions, params: DescribeContractParams): Promise<DescribeContractResult>;
+/**
+ * `describe.function` — the authority-gated keyed describe read for a single
+ * function. Returns `{ contract, version, descriptor }` with `descriptor` the
+ * projected function entry. Same gating as {@link discoverDescribeContract}.
+ *
+ * @throws {InvokeError} — see {@link discoverWhoami}
+ */
+declare function discoverDescribeFunction(opts: DiscoverOptions, params: DescribeFunctionParams): Promise<DescribeFunctionResult>;
 
 /**
  * Token fixed-point units (USDT-style 6 decimals).
@@ -5228,5 +5413,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, InvokeError, KycStatusTimeoutError, LogLevel, MockTransport, NODE_URLS, OrgDataClient, OtpRateLimitedError, RpcError, SessionExpiredError, SessionOrgDataClient, SessionStateError, SessionStatus, SessionUsageReportClient, T3nClient, T3nConfigError, 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, buildSecretWriteArgs, 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, isAgentEgressGetResponse, isDataGetResponse, isDataListResponse, isListAgentsResponse, isListHumanMembersResponse, isMutationResponse, isObject, isOrgAdminStatus, isOrgContractGrants, isOrgPolicyMeta, isOrgPolicyView, isOrgUsageReport, isOrgWriters, isRoleAssignmentsResponse, isRoleGetResponse, isSecretListResponse, isSecretRecord, isSecretView, 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 { ActivityCallerType, ActivityEntry, ActivityOutcome, ActivityReport, AdmitForOrgOptions, AgentAuthEntry, AgentAuthMergeResult, AgentAuthPolicy, AgentAuthScriptGrant, AgentAuthUpdateInput, AgentCardRefInput, AgentCardResponse, AgentCardSetInput, AgentEgressEntry, AgentEgressGetResponse, AgentEgressRefInput, AgentSummary, AssignRolesInput, AuthInput, BalanceRow, ChargeReason, ClientAuth, ClientHandshake, ConfigValidationResult, ContractDescriptorFacets, ContractExecuteInput, ContractKind, ContractLifecycleStatus, ContractListDetailedOptions, ContractListDetailedPage, ContractPublishInput, ContractRegisterResult, ContractResponseSchema, ContractSetDescriptorInput, CreatePolicyInput, DataGetInput, DataGetResponse, DataListInput, DataListResponse, DelegationGrantKind, DelegationGrantRef, DeleteDataInput, DeleteGrantsInput, DeleteScopeInput, DetailedContract, Did, Direction, DkgAttestation, DkgVerifyResult, EmailOtpAuthInput, EmailOtpCredentials, Environment, EthAuthInput, ExecuteBusinessContractOptions, ExecuteOrgDataActionOptions, FetchTrustedManifestOptions, GetActivityLogOptions, GetUsageOptions, GrantCheckParams, GrantCheckResult, GranteeInput, GrantsGetInput, GuestToHostHandler, GuestToHostHandlers, HandshakeResult, HumanMember, InvokeOptions, InvokeRequest, JsonRpcRequest, JsonRpcResponse, KycPollCadence, KycPollOptions, KycStatus, KycStatusKind, ListAgentsInput, ListAgentsResponse, ListContractsParams, ListContractsResult, ListContractsScope, ListHumanMembersInput, ListHumanMembersResponse, ListedContract, Logger, MapCreateInput, MapLifecycleStatus, MapResponse, MapUpdateInput, MapVisibility, MemberRole, 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, SecretKind, SecretListInput, SecretListResponse, SecretNameInput, SecretRecord, SecretSetValueInput, SecretView, SecretWriteInput, SessionCrypto, SessionId, SetAgentEgressInput, 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, TrustAnchorSource, 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, T3nConfigError, 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, buildSecretWriteArgs, bytesToString, canonicalTenantName, clearKeyCache, clearManifestVersionFloor, compactDidFromBytes, createDefaultHandlers, createEmailOtpAuthInput, createEthAuthInput, createLogger, createMlKemPublicKeyHandler, createOidcAuthInput, createOrgDataClientFromSession, createRandomHandler, createUsageReportClientFromSession, createWorkloadAuthInput, decodeWasmErrorMessage, deriveAgentCardEntryId, discoverCheckDelegation, discoverDescribeContract, discoverDescribeFunction, discoverListContracts, discoverWhoami, eth_get_address, extractWasmError, fetchDkgAttestation, fetchMlKemPublicKey, fetchTrustedManifest, formatTokens, generateRandomString, generateUUID, getEnvironment, getEnvironmentName, getGlobalLogLevel, getLogger, getNodeUrl, getScriptVersion, invoke, isAgentCardResponse, isAgentEgressGetResponse, isDataGetResponse, isDataListResponse, isListAgentsResponse, isListHumanMembersResponse, isMutationResponse, isObject, isOrgAdminStatus, isOrgContractGrants, isOrgPolicyMeta, isOrgPolicyView, isOrgUsageReport, isOrgWriters, isRoleAssignmentsResponse, isRoleGetResponse, isSecretListResponse, isSecretRecord, isSecretView, 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 { ActivityCallerType, ActivityEntry, ActivityOutcome, ActivityReport, AdmitForOrgOptions, AgentAuthEntry, AgentAuthMergeResult, AgentAuthPolicy, AgentAuthScriptGrant, AgentAuthUpdateInput, AgentCardRefInput, AgentCardResponse, AgentCardSetInput, AgentEgressEntry, AgentEgressGetResponse, AgentEgressRefInput, AgentSummary, AssignRolesInput, AuthInput, BalanceRow, ChargeReason, ClientAuth, ClientHandshake, ConfigValidationResult, ContractDescriptorDocument, ContractDescriptorFacets, ContractExecuteInput, ContractKind, ContractLifecycleStatus, ContractListDetailedOptions, ContractListDetailedPage, ContractPublishInput, ContractRegisterResult, ContractResponseSchema, ContractSetDescriptorInput, CreatePolicyInput, DataGetInput, DataGetResponse, DataListInput, DataListResponse, DelegationGrantKind, DelegationGrantRef, DeleteDataInput, DeleteGrantsInput, DeleteScopeInput, DescribeContractParams, DescribeContractResult, DescribeFunctionParams, DescribeFunctionResult, DetailedContract, Did, Direction, DiscoverOptions, DkgAttestation, DkgVerifyResult, EmailOtpAuthInput, EmailOtpCredentials, Environment, EthAuthInput, ExecuteBusinessContractOptions, ExecuteOrgDataActionOptions, FetchTrustedManifestOptions, FunctionDescriptorEntry, GetActivityLogOptions, GetUsageOptions, GrantCheckParams, GrantCheckResult, GranteeInput, GrantsGetInput, GuestToHostHandler, GuestToHostHandlers, HandshakeResult, HumanMember, InvokeOptions, InvokeRequest, JsonRpcRequest, JsonRpcResponse, KycPollCadence, KycPollOptions, KycStatus, KycStatusKind, ListAgentsInput, ListAgentsResponse, ListContractsParams, ListContractsResult, ListContractsScope, ListHumanMembersInput, ListHumanMembersResponse, ListedContract, Logger, MapCreateInput, MapLifecycleStatus, MapResponse, MapUpdateInput, MapVisibility, MemberRole, 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, SecretKind, SecretListInput, SecretListResponse, SecretNameInput, SecretRecord, SecretSetValueInput, SecretView, SecretWriteInput, SessionCrypto, SessionId, SetAgentEgressInput, 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, TrustAnchorSource, TrustManifestPayload, UnassignRolesInput, UnsafeTrustServer, UpdateMetaInput, UsageEntry, UsagePage, UsageReportSignature, UserGrant, UserInputProfile, UserUpsertErrorKind, WasmComponent, WasmNextResult, WhoamiResult, WireBlock, WorkloadAuthInput, WriteDataInput, WriterSet, WritersGetInput };