@terminal3/t3n-sdk 2.3.0 → 2.5.0

package/dist/index.d.ts

@@ -600,6 +600,154 @@ declare class UserUpsertError extends T3nError {
     static fromWire(raw: string): UserUpsertError | null;
 }
 
+/**
+ * Org-data wire types mirroring the Rust contract shapes in
+ * `tee-contract-org-data` and `org-data-types`.
+ *
+ * Plain TypeScript interfaces (no zod) — the SDK does not use a
+ * validation library for domain types; see the existing `types/` files.
+ *
+ * Reference: `org-data-types/src/lib.rs` and
+ * `tee-contract-org-data/src/org_data.rs`.
+ */
+/**
+ * Capability grant stored under `ORG_CONTRACT_GRANTS_MAP`.
+ *
+ * Mirrors `org_data_types::UserGrant`.
+ */
+interface UserGrant {
+    /** The user this grant applies to (`did:t3n:<40-hex>`). */
+    user_did: string;
+    /** WIT function names the user may invoke (e.g. `"run-payroll"`). */
+    functions: string[];
+    /** Data scope paths the user may access (e.g. `"payroll/employees"`). */
+    scopes: string[];
+    /**
+     * Optional key-value constraints that must match the request metadata
+     * exactly for every key present in this map.
+     */
+    constraints: Record<string, string>;
+    /** Unix timestamp (secs) after which this grant is expired. `null` means never expires. */
+    expires_at_secs: number | null;
+}
+/**
+ * Policy record for an organisation's data tier.
+ *
+ * Mirrors `org_data_types::OrgPolicyMeta`.
+ */
+interface OrgPolicyMeta {
+    /** DIDs (`did:t3n:<40-hex>`) of users authorised to manage policy and read data. */
+    admins: string[];
+    /** Maximum number of admins allowed for this org. */
+    max_admins: number;
+    /** Unix timestamp (secs) when the policy was first created. */
+    created_at_secs: number;
+    /** Unix timestamp (secs) of the most recent policy update. */
+    updated_at_secs: number;
+}
+type EmploymentStatus = "Active" | "Terminated";
+/** Singapore CPF residency categories. */
+type ResidencyCategory = "Citizen" | "Pr1" | "Pr2" | "PrThreePlus" | "Foreigner";
+type AgeBand = "Under35" | "Age35To45" | "Age45To50" | "Age50To55" | "Age55To60" | "Age60To65" | "Over65";
+interface ExpenseClaim {
+    claim_id: string;
+    amount_cents: number;
+    category: string;
+    description: string;
+    per_diem_days?: number;
+}
+/**
+ * Employee data row stored under `OrgData[org || "payroll/employees" || entry_id]`.
+ *
+ * Mirrors `tee-contract-payroll::types::EmployeeRecord`.
+ */
+interface EmployeeRecord {
+    employee_id: string;
+    employment_status: EmploymentStatus;
+    is_on_probation: boolean;
+    hire_date: string;
+    termination_date?: string;
+    /** Monthly gross base salary in integer cents SGD. */
+    base_salary_cents: number;
+    unpaid_leave_days: number;
+    working_days_in_period: number;
+    overtime_hours: number;
+    hourly_rate_cents: number;
+    residency: ResidencyCategory;
+    age_band: AgeBand;
+    expense_claims: ExpenseClaim[];
+    /** Opaque reference used by the service layer for disbursement. */
+    bank_account_ref: string;
+    bank_account_changed_recently: boolean;
+}
+/**
+ * Standard response returned by all policy write and data mutation operations.
+ *
+ * Mirrors `tee-contract-org-data::org_data::MutationResponse`.
+ */
+interface MutationResponse {
+    /** `"created"`, `"updated"`, or `"deleted"`. */
+    status: string;
+    /** Hex-encoded entry ID; present on data write/delete operations. */
+    entry_id?: string;
+    /** Whether the target key existed before deletion; present on single-entry deletes. */
+    deleted?: boolean;
+    /** Number of entries removed; present on `org-data-delete-scope`. */
+    deleted_entries?: number;
+    tx_hash: string | null;
+}
+/**
+ * Response type alias for org-writers-get.
+ *
+ * The wire body is `{ writers: string[] }` where each entry is
+ * `did:t3n:<40-hex>`.
+ */
+interface OrgWriters {
+    writers: string[];
+}
+/**
+ * Response type alias for org-grants-get.
+ *
+ * The wire body echoes the `contract_id` alongside the grant list.
+ */
+interface OrgContractGrants {
+    contract_id: string;
+    grants: UserGrant[];
+}
+/** Response for `org-data-list`. */
+interface DataListResponse {
+    /** Hex-encoded entry IDs for this page. */
+    entry_ids: string[];
+    /** Offset to pass for the next page. `null` when this is the last page. */
+    next_offset: number | null;
+    /** Total number of entries in the scope (across all pages). */
+    total: number;
+}
+/** Response for `org-data-get`. */
+interface DataGetResponse {
+    entry_id: string;
+    /** Hex-encoded raw payload bytes. */
+    payload_hex: string;
+}
+/**
+ * The signed action envelope sent to `POST /api/org-data/execute`.
+ *
+ * Field order matches `node/service/src/org_data.rs::OrgDataSignedAction`
+ * and `SignableEnvelope`.  The `signature` field is the EIP-191
+ * personal_sign over the canonical JSON of the eight fields above it.
+ */
+interface OrgDataActionWire {
+    nonce: string;
+    user_did: string;
+    authenticator_id: string;
+    org_did: string;
+    contract_id: string;
+    function: string;
+    args_hash: string;
+    expires_at_secs: number;
+    signature: string;
+}
+
 /**
  * Public types export for T3n SDK
  */
@@ -1694,6 +1842,63 @@ declare function ethRecoverEip191(msg: Uint8Array, sig: Uint8Array): Uint8Array;
  * `delegation-types::verify_agent_sig` accepts as the 64-byte form.
  */
 declare function signAgentInvocation(preimage: Uint8Array, secret: Uint8Array): Uint8Array;
+/**
+ * Options for {@link DelegationCustodialClient}.
+ */
+interface DelegationCustodialClientOpts {
+    /**
+     * Explicit semver string for the delegation contract (e.g. `"1.0.0"`).
+     * When omitted the client resolves `"latest"` via
+     * `GET /api/contracts/current?name=tee:delegation/contracts` (one
+     * request per client instance, cached in `getScriptVersion`).
+     */
+    scriptVersion?: string;
+}
+/**
+ * Result returned by {@link DelegationCustodialClient.signCustodial}.
+ */
+interface SignCustodialResult {
+    /** RFC 8785 JCS bytes of the credential, exactly as signed by the node. */
+    credentialJcs: Uint8Array;
+    /** 65-byte EIP-191 signature over `credentialJcs` produced by the TEE. */
+    userSig: Uint8Array;
+}
+/**
+ * Wraps the `tee:delegation/contracts::sign` function for OIDC users
+ * (or any user whose private key is held by the TEE rather than the
+ * browser).
+ *
+ * ETH-EOA users who hold their own key should call
+ * {@link signCredential} directly — no network round-trip required.
+ *
+ * The client must be constructed with an authenticated {@link T3nClient}
+ * instance and the node's base URL; `signCustodial` sends the credential
+ * body to the TEE and returns the signed bytes.
+ *
+ * Reference: `node/tests/harness/src/payroll_seed.rs` (the
+ * `tee:delegation.sign` invocation at line 550).
+ */
+declare class DelegationCustodialClient {
+    private readonly t3n;
+    private readonly baseUrl;
+    private readonly opts;
+    constructor(t3n: T3nClient, baseUrl: string, opts?: DelegationCustodialClientOpts);
+    /**
+     * Request the TEE to sign a delegation credential on behalf of the
+     * authenticated user.
+     *
+     * The `body` is sent as-is as the `input.body` field of the
+     * `tee:delegation/contracts::sign` action.  Use
+     * {@link buildDelegationCredential} + the wire-shape projection to
+     * produce the correct representation — binary fields (`agent_pubkey`,
+     * `vc_id`) must be base64url-no-pad strings, and `not_before_secs` /
+     * `not_after_secs` must be decimal strings.
+     *
+     * Returns `{ credentialJcs, userSig }` — both as `Uint8Array` — ready
+     * to be passed into {@link buildPayrollInvocation}.
+     */
+    signCustodial(body: Record<string, unknown>): Promise<SignCustodialResult>;
+}
 /** Options for {@link buildPayrollInvocation}. */
 interface BuildPayrollInvocationOpts {
     credentialJcs: Uint8Array;
@@ -1712,6 +1917,190 @@ interface BuildPayrollInvocationOpts {
  */
 declare function buildPayrollInvocation(opts: BuildPayrollInvocationOpts): PayrollInvocation;
 
+/**
+ * OrgDataClient — user-signed org-data dispatch client.
+ *
+ * Implements the two-step flow that `node/service/src/org_data.rs`
+ * defines:
+ *
+ * 1. `POST /api/org-data/nonce` — fetch a single-use replay nonce.
+ * 2. `POST /api/org-data/execute` — submit a signed envelope whose
+ *    EIP-191 signature covers the canonical JSON of the eight
+ *    `SignableEnvelope` fields, in the exact field-declaration order
+ *    used by the Rust struct (see `org_data.rs` lines 104–117).
+ *
+ * The `args_hash` is `hex(sha256(JSON.stringify(args)))` — the same
+ * binding the Rust harness (`org_data_client.rs`) computes.
+ *
+ * `authenticator_id` is `"eth:0x<40 lowercase hex>"` derived
+ * deterministically from the caller's ETH secret key.
+ */
+
+/**
+ * Options accepted by {@link executeOrgDataAction}.
+ */
+interface ExecuteOrgDataActionOptions {
+    /** Envelope TTL in seconds. Defaults to {@link DEFAULT_ENVELOPE_TTL_SECS}. */
+    ttlSecs?: number;
+}
+interface CreatePolicyInput {
+    orgDid: string;
+    initialAdminDid: string;
+    maxAdmins?: number;
+}
+interface UpdateMetaInput {
+    orgDid: string;
+    admins: string[];
+    maxAdmins?: number;
+}
+interface SetWritersInput {
+    orgDid: string;
+    scope: string;
+    writers: string[];
+}
+interface SetGrantsInput {
+    orgDid: string;
+    contractId: string;
+    grants: UserGrant[];
+}
+interface DeleteGrantsInput {
+    orgDid: string;
+    contractId: string;
+}
+interface WriteDataInput {
+    orgDid: string;
+    scope: string;
+    payloadHex: string;
+    /** Explicit entry ID (32 hex chars). When present, enables idempotent upsert. */
+    entryId?: string;
+    /** Client-supplied monotonic counter for ID derivation when `entryId` is absent. */
+    clientSeqNo?: number;
+}
+interface DeleteDataInput {
+    orgDid: string;
+    scope: string;
+    /** Hex-encoded entry ID (32 hex chars). */
+    entryId: string;
+}
+interface DeleteScopeInput {
+    orgDid: string;
+    scope: string;
+}
+interface PolicyGetInput {
+    orgDid: string;
+}
+interface WritersGetInput {
+    orgDid: string;
+    scope: string;
+}
+interface GrantsGetInput {
+    orgDid: string;
+    contractId: string;
+}
+interface DataListInput {
+    orgDid: string;
+    scope: string;
+    offset?: number;
+    limit?: number;
+}
+interface DataGetInput {
+    orgDid: string;
+    scope: string;
+    /** Hex-encoded entry ID (32 hex chars). */
+    entryId: string;
+}
+/**
+ * Options used when constructing an {@link OrgDataClient}.
+ */
+interface OrgDataClientOptions {
+    /** Envelope TTL in seconds applied to every call. Default: 300. */
+    ttlSecs?: number;
+}
+/**
+ * Client for the user-authenticated org-data dispatch API.
+ *
+ * Constructed with the node's base URL, the caller's 32-byte ETH secret
+ * key, and the caller's DID (`did:t3n:<40-hex>`).  Every method
+ * transparently fetches a fresh nonce, signs the envelope with EIP-191,
+ * and posts to `/api/org-data/execute`.
+ *
+ * The signing key must be the same key registered as an authenticator
+ * (`eth:0x<addr>`) for `userDid` in the DID registry — the service
+ * verifies this binding before dispatching any contract call.
+ */
+declare class OrgDataClient {
+    private readonly baseUrl;
+    private readonly ethSecret;
+    private readonly userDid;
+    private readonly opts;
+    constructor(baseUrl: string, ethSecret: Uint8Array, userDid: string, opts?: OrgDataClientOptions);
+    private call;
+    /**
+     * Initialise the data-tier policy for an existing organisation.
+     *
+     * The calling user must be named as `initialAdminDid`.  New orgs created
+     * after the org-data contract was deployed have their policy seeded
+     * automatically by the organisation contract; call this only for orgs
+     * that pre-date the contract deployment.
+     */
+    createPolicy(input: CreatePolicyInput): Promise<MutationResponse>;
+    /**
+     * Replace the admin list and/or `max_admins` cap on an existing policy.
+     *
+     * The calling user cannot remove themselves when they are the sole
+     * remaining admin; another admin must be added first.
+     */
+    updateMeta(input: UpdateMetaInput): Promise<MutationResponse>;
+    /**
+     * Full replacement of the writer list for a data scope.
+     *
+     * Passing an empty list removes the entry (no writers allowed).
+     * Scope names are canonicalised to lowercase before storage.
+     */
+    setWriters(input: SetWritersInput): Promise<MutationResponse>;
+    /**
+     * Full replacement of the user-grant list for a contract.
+     *
+     * Passing an empty list removes the entry.
+     */
+    setGrants(input: SetGrantsInput): Promise<MutationResponse>;
+    /**
+     * Delete the grant entry for a contract entirely.
+     */
+    deleteGrants(input: DeleteGrantsInput): Promise<MutationResponse>;
+    /**
+     * Write a data entry to the org's scope.
+     *
+     * When `entryId` is supplied, the call is an idempotent upsert.
+     * When absent, `clientSeqNo` is required and the entry ID is derived
+     * via SHA-256 from `(org_did, scope, writer_did, client_seq_no)`.
+     */
+    writeData(input: WriteDataInput): Promise<MutationResponse>;
+    /** Delete a single data entry by entry ID. */
+    deleteData(input: DeleteDataInput): Promise<MutationResponse>;
+    /**
+     * Bulk-delete all entries in a scope.
+     *
+     * Requires admin access (unlike `deleteData` which requires writer access).
+     */
+    deleteScope(input: DeleteScopeInput): Promise<MutationResponse>;
+    /** Read the policy metadata for an org (admin-only). */
+    policyGet(input: PolicyGetInput): Promise<OrgPolicyMeta>;
+    /** Read the writer list for a scope (admin-only). */
+    writersGet(input: WritersGetInput): Promise<OrgWriters>;
+    /** Read the grant list for a contract (admin-only). */
+    grantsGet(input: GrantsGetInput): Promise<OrgContractGrants>;
+    /**
+     * List entry IDs for a scope (admin-only), paginated.
+     *
+     * Pass `offset` from the previous response's `next_offset` to fetch
+     * the next page.
+     */
+    dataList(input: DataListInput): Promise<DataListResponse>;
+    /** Retrieve a single data entry by entry ID (admin-only). */
+    dataGet(input: DataGetInput): Promise<DataGetResponse>;
+}
+
 /**
  * Cryptographic utilities for T3n SDK
  *
@@ -1933,5 +2322,5 @@ declare function clearKeyCache(): void;
  */
 declare function loadConfig(baseUrl?: string): SdkConfig;
 
-export { AGENT_PUBKEY_LEN, AuthMethod, AuthenticationError, ContractResponseError, DEFAULT_KYC_POLL_CADENCE, DELEGATION_CREDENTIAL_DOMAIN, DELEGATION_INVOCATION_DOMAIN, ETH_SIG_LEN, HandshakeError, HttpTransport, KycStatusTimeoutError, LogLevel, MockTransport, NODE_URLS, NONCE_LEN, REQUEST_HASH_LEN, RpcError, SessionStateError, SessionStatus, T3nClient, T3nError, TERMINAL_KYC_STATUSES, UserUpsertError, VC_ID_LEN, WasmError, _b64uEncode, b64uDecodeStrict, b64uEncodeBytes, buildDelegationCredential, buildInvocationPreimage, buildPayrollInvocation, bytesToString, canonicaliseCredential, canonicaliseRequest, clearKeyCache, compactDidFromBytes, createDefaultHandlers, createEthAuthInput, createLogger, createMlKemPublicKeyHandler, createOidcAuthInput, createRandomHandler, decodeWasmErrorMessage, eip191Digest, ethRecoverEip191, eth_get_address, extractWasmError, fetchDkgAttestation, fetchMlKemPublicKey, generateRandomString, generateUUID, getEnvironment, getEnvironmentName, getGlobalLogLevel, getLogger, getNodeUrl, getScriptVersion, loadConfig, loadWasmComponent, metamask_get_address, metamask_sign, parseContractResponse, redactSecrets, redactSecretsFromJson, requestHash, setEnvironment, setGlobalLogLevel, setNodeUrl, signAgentInvocation, signCredential, stringToBytes, validateConfig, validateCredentialBody, verifyDkgAttestation, verifyTdxQuote };
-export type { AuthInput, BuildDelegationCredentialOpts, BuildPayrollInvocationOpts, ClientAuth, ClientHandshake, ConfigValidationResult, ContractResponseSchema, DelegationCredential, DelegationEnvelope, Did, DkgAttestation, DkgVerifyResult, Environment, EthAuthInput, GuestToHostHandler, GuestToHostHandlers, HandshakeResult, JsonRpcRequest, JsonRpcResponse, KycPollCadence, KycPollOptions, KycStatus, KycStatusKind, Logger, OidcAuthInput, OidcCredentials, OtpChannel, OtpMergeSuggestion, OtpRequestInput, OtpRequestResult, OtpVerifyInput, OtpVerifyResult, PayrollInvocation, PayrollRunRequest, PeerQuoteResult, QuoteVerifyResult, SdkConfig, SessionCrypto, SessionId, SignDelegationResponse, SubmitUserInputArgs, SubmitUserInputResult, T3nClientConfig, Transport, UserInputProfile, UserUpsertErrorKind, WasmComponent, WasmNextResult };
+export { AGENT_PUBKEY_LEN, AuthMethod, AuthenticationError, ContractResponseError, 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, SessionStateError, SessionStatus, T3nClient, T3nError, TERMINAL_KYC_STATUSES, UserUpsertError, VC_ID_LEN, WasmError, _b64uEncode, b64uDecodeStrict, b64uEncodeBytes, buildDelegationCredential, buildInvocationPreimage, buildPayrollInvocation, bytesToString, canonicaliseCredential, canonicaliseRequest, clearKeyCache, compactDidFromBytes, createDefaultHandlers, createEthAuthInput, createLogger, createMlKemPublicKeyHandler, createOidcAuthInput, createRandomHandler, decodeWasmErrorMessage, eip191Digest, ethRecoverEip191, eth_get_address, extractWasmError, fetchDkgAttestation, fetchMlKemPublicKey, generateRandomString, generateUUID, getEnvironment, getEnvironmentName, getGlobalLogLevel, getLogger, getNodeUrl, getScriptVersion, 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, 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, PayrollRunRequest, PeerQuoteResult, PolicyGetInput, QuoteVerifyResult, ResidencyCategory, SdkConfig, SessionCrypto, SessionId, SetGrantsInput, SetWritersInput, SignCustodialResult, SignDelegationResponse, SubmitUserInputArgs, SubmitUserInputResult, T3nClientConfig, Transport, UpdateMetaInput, UserGrant, UserInputProfile, UserUpsertErrorKind, WasmComponent, WasmNextResult, WriteDataInput, WritersGetInput };