@terminal3/t3n-sdk 4.18.0 → 4.20.0

package/dist/index.d.ts

@@ -2968,6 +2968,56 @@ interface OrgContractGrants {
  * here would create maintenance churn against benign field additions.
  */
 declare function isOrgContractGrants(value: unknown): value is OrgContractGrants;
+/**
+ * One grant inside a role: a {@link UserGrant} body (without the
+ * grantee, which is bound at assignment time) plus the target contract.
+ * Mirrors the org-data `RoleGrant` wire shape.
+ */
+interface RoleGrant {
+    /** Target contract (canonical name, e.g. `"tee:z-payroll/contracts"`). */
+    contract_id: string;
+    /** WIT function names this grant confers. */
+    functions: string[];
+    /** Data scope paths this grant confers (canonicalised lowercase). */
+    scopes: string[];
+}
+/**
+ * A role: a named bundle of grants and/or composed sub-roles.
+ * Mirrors the org-data `RoleDefinition` wire shape.
+ */
+interface RoleDefinition {
+    /** Org-unique role identifier (slug; function-name grammar). */
+    role_id: string;
+    /** Human-facing label. */
+    label: string;
+    /** Composite: other role ids in the same org whose grants this role confers. */
+    includes: string[];
+    /** Grants this role confers directly. */
+    grants: RoleGrant[];
+}
+/**
+ * The roles assigned to one grantee within one org.
+ * Mirrors the org-data `RoleAssignments` wire shape.
+ */
+interface RoleAssignments {
+    /** Assigned role ids. */
+    roles: string[];
+}
+/** Response for `org-role-get`; `role` is `null` when the id is unknown. */
+interface RoleGetResponse {
+    role: RoleDefinition | null;
+}
+/** Shallow runtime guard for {@link RoleGetResponse}. */
+declare function isRoleGetResponse(value: unknown): value is RoleGetResponse;
+/** Response for `org-role-assignments-get`. */
+interface RoleAssignmentsResponse {
+    /** Echoed back so callers don't need to track which request this answers. */
+    grantee_did: string;
+    /** The grantee's assigned role ids (empty when none). */
+    roles: string[];
+}
+/** Shallow runtime guard for {@link RoleAssignmentsResponse}. */
+declare function isRoleAssignmentsResponse(value: unknown): value is RoleAssignmentsResponse;
 /** Response for `org-data-list`. */
 interface DataListResponse {
     /** Hex-encoded entry IDs for this page. */
@@ -3100,6 +3150,27 @@ interface DeleteGrantsInput {
     orgDid: string;
     contractId: string;
 }
+interface SetRoleInput {
+    orgDid: string;
+    role: RoleDefinition;
+}
+interface RoleIdInput {
+    orgDid: string;
+    roleId: string;
+}
+interface AssignRolesInput {
+    orgDid: string;
+    granteeDid: string;
+    /** Full replacement set of role ids; an empty list clears the assignment. */
+    roles: string[];
+}
+/** An (org, grantee) pair — the read/clear key for role assignments. */
+interface GranteeInput {
+    orgDid: string;
+    granteeDid: string;
+}
+/** Alias of {@link GranteeInput} — named for the `unassignRoles` call site. */
+type UnassignRolesInput = GranteeInput;
 interface WriteDataInputBase {
     orgDid: string;
     scope: string;
@@ -3289,6 +3360,21 @@ declare class OrgDataClient {
      * Delete the grant entry for a contract entirely.
      */
     deleteGrants(input: DeleteGrantsInput): Promise<MutationResponse>;
+    /** Upsert a role definition (org-admin only). */
+    setRole(input: SetRoleInput): Promise<MutationResponse>;
+    /** Delete a role definition (org-admin only). */
+    deleteRole(input: RoleIdInput): Promise<MutationResponse>;
+    /** Read one role definition (org-admin only); `role` is `null` if unknown. */
+    getRole(input: RoleIdInput): Promise<RoleGetResponse>;
+    /**
+     * Set a grantee's assigned roles (full replacement; empty list clears).
+     * Org-admin only.
+     */
+    assignRoles(input: AssignRolesInput): Promise<MutationResponse>;
+    /** Clear a grantee's role assignments (org-admin only). */
+    unassignRoles(input: UnassignRolesInput): Promise<MutationResponse>;
+    /** Read a grantee's assigned role ids (org-admin only). */
+    getRoleAssignments(input: GranteeInput): Promise<RoleAssignmentsResponse>;
     /**
      * Write a data entry to the org's scope.
      *
@@ -3436,6 +3522,21 @@ declare class SessionOrgDataClient {
     setGrants(input: SetGrantsInput): Promise<MutationResponse>;
     /** Mirrors {@link OrgDataClient.deleteGrants}. */
     deleteGrants(input: DeleteGrantsInput): Promise<MutationResponse>;
+    /** Upsert a role definition (org-admin only). */
+    setRole(input: SetRoleInput): Promise<MutationResponse>;
+    /** Delete a role definition (org-admin only). */
+    deleteRole(input: RoleIdInput): Promise<MutationResponse>;
+    /** Read one role definition (org-admin only); `role` is `null` if unknown. */
+    getRole(input: RoleIdInput): Promise<RoleGetResponse>;
+    /**
+     * Set a grantee's assigned roles (full replacement; empty list clears).
+     * Org-admin only.
+     */
+    assignRoles(input: AssignRolesInput): Promise<MutationResponse>;
+    /** Clear a grantee's role assignments (org-admin only). */
+    unassignRoles(input: UnassignRolesInput): Promise<MutationResponse>;
+    /** Read a grantee's assigned role ids (org-admin only). */
+    getRoleAssignments(input: GranteeInput): Promise<RoleAssignmentsResponse>;
     /** Mirrors {@link OrgDataClient.writeData}. */
     writeData(input: WriteDataInput): Promise<MutationResponse>;
     /** Mirrors {@link OrgDataClient.deleteData}. */
@@ -3797,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
  */
@@ -4283,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, 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, 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, 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, SdkConfig, SessionCrypto, SessionId, SetGrantsInput, SetWritersInput, StringEncoding, SubmitUserInputArgs, SubmitUserInputResult, T3nClientConfig, TenantAdmitProjection, TenantAdmitStatus, TenantBaseClient, TenantClientConfig, TenantContractExecuteInput, TenantContractPublishInput, TenantContractSetDescriptorInput, TenantExecutionSession, TenantMapCreateInput, TenantMapUpdatePatch, TenantMeResponse, TenantSdkEnvironment, TenantSelfAdmitResult, TenantStatus, TenantTargetOptions, TokenTxKind, Transport, TrustAnchor, TrustAnchorOrUnsafe, 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 };