@terminal3/t3n-sdk 2.4.0 → 2.5.0

package/dist/src/client/delegation.d.ts

@@ -196,6 +196,63 @@ export declare function ethRecoverEip191(msg: Uint8Array, sig: Uint8Array): Uint
  * `delegation-types::verify_agent_sig` accepts as the 64-byte form.
  */
 export declare function signAgentInvocation(preimage: Uint8Array, secret: Uint8Array): Uint8Array;
+/**
+ * Options for {@link DelegationCustodialClient}.
+ */
+export 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}.
+ */
+export 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).
+ */
+export declare class DelegationCustodialClient {
+    private readonly t3n;
+    private readonly baseUrl;
+    private readonly opts;
+    constructor(t3n: import("./t3n-client").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}. */
 export interface BuildPayrollInvocationOpts {
     credentialJcs: Uint8Array;

package/dist/src/client/index.d.ts

@@ -10,3 +10,4 @@ export * from "./actions";
 export * from "./request-parser";
 export * from "./contract-response";
 export * from "./delegation";
+export * from "./org-data";

package/dist/src/client/org-data.d.ts

@@ -0,0 +1,201 @@
+/**
+ * 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.
+ */
+import type { OrgContractGrants, OrgPolicyMeta, OrgWriters, DataListResponse, DataGetResponse, MutationResponse, UserGrant } from "../types/org-data";
+/**
+ * Derive the `"eth:0x<40 lowercase hex>"` authenticator string
+ * deterministically from a 32-byte ETH secret key.
+ *
+ * Mirrors `authenticator_id_from_eth_secret` in
+ * `node/tests/harness/src/org_data_client.rs`.
+ */
+declare function authenticatorIdFromEthSecret(ethSecret: Uint8Array): string;
+/**
+ * Options accepted by {@link executeOrgDataAction}.
+ */
+export interface ExecuteOrgDataActionOptions {
+    /** Envelope TTL in seconds. Defaults to {@link DEFAULT_ENVELOPE_TTL_SECS}. */
+    ttlSecs?: number;
+}
+/**
+ * Sign and dispatch a user-authenticated org-data action.
+ *
+ * `args` MUST contain an `org_did` field matching `orgDid` — the
+ * service verifies envelope-vs-args binding before dispatching.
+ *
+ * Returns the contract's JSON response on success.
+ */
+declare function executeOrgDataAction(baseUrl: string, ethSecret: Uint8Array, userDid: string, orgDid: string, functionName: string, args: Record<string, unknown>, opts?: ExecuteOrgDataActionOptions): Promise<unknown>;
+export interface CreatePolicyInput {
+    orgDid: string;
+    initialAdminDid: string;
+    maxAdmins?: number;
+}
+export interface UpdateMetaInput {
+    orgDid: string;
+    admins: string[];
+    maxAdmins?: number;
+}
+export interface SetWritersInput {
+    orgDid: string;
+    scope: string;
+    writers: string[];
+}
+export interface SetGrantsInput {
+    orgDid: string;
+    contractId: string;
+    grants: UserGrant[];
+}
+export interface DeleteGrantsInput {
+    orgDid: string;
+    contractId: string;
+}
+export 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;
+}
+export interface DeleteDataInput {
+    orgDid: string;
+    scope: string;
+    /** Hex-encoded entry ID (32 hex chars). */
+    entryId: string;
+}
+export interface DeleteScopeInput {
+    orgDid: string;
+    scope: string;
+}
+export interface PolicyGetInput {
+    orgDid: string;
+}
+export interface WritersGetInput {
+    orgDid: string;
+    scope: string;
+}
+export interface GrantsGetInput {
+    orgDid: string;
+    contractId: string;
+}
+export interface DataListInput {
+    orgDid: string;
+    scope: string;
+    offset?: number;
+    limit?: number;
+}
+export interface DataGetInput {
+    orgDid: string;
+    scope: string;
+    /** Hex-encoded entry ID (32 hex chars). */
+    entryId: string;
+}
+/**
+ * Options used when constructing an {@link OrgDataClient}.
+ */
+export 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.
+ */
+export 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>;
+}
+export { executeOrgDataAction, authenticatorIdFromEthSecret };

package/dist/src/index.d.ts

@@ -20,6 +20,11 @@ export type { KycStatus, KycStatusKind, KycPollOptions, KycPollCadence, } from "
 export { DEFAULT_KYC_POLL_CADENCE, TERMINAL_KYC_STATUSES, KycStatusTimeoutError, } from "./types/kyc";
 export type { OtpChannel, OtpRequestInput, OtpRequestResult, OtpVerifyInput, OtpVerifyResult, OtpMergeSuggestion, UserInputProfile, SubmitUserInputArgs, SubmitUserInputResult, UserUpsertErrorKind, } from "./types/user";
 export { UserUpsertError } from "./types/user";
+export { OrgDataClient } from "./client/org-data";
+export type { OrgDataClientOptions, CreatePolicyInput, UpdateMetaInput, SetWritersInput, SetGrantsInput, DeleteGrantsInput, WriteDataInput, DeleteDataInput, DeleteScopeInput, PolicyGetInput, WritersGetInput, GrantsGetInput, DataListInput, DataGetInput, ExecuteOrgDataActionOptions, } from "./client/org-data";
+export type { OrgDataActionWire, OrgPolicyMeta, OrgWriters, OrgContractGrants, UserGrant, EmployeeRecord, EmploymentStatus, ResidencyCategory, AgeBand, ExpenseClaim, MutationResponse, DataListResponse, DataGetResponse, } from "./types/org-data";
+export { DelegationCustodialClient } from "./client/delegation";
+export type { DelegationCustodialClientOpts, SignCustodialResult, } from "./client/delegation";
 export { DELEGATION_CREDENTIAL_DOMAIN, DELEGATION_INVOCATION_DOMAIN, VC_ID_LEN, NONCE_LEN, REQUEST_HASH_LEN, AGENT_PUBKEY_LEN, ETH_SIG_LEN, buildDelegationCredential, validateCredentialBody, canonicaliseCredential, canonicaliseRequest, requestHash, buildInvocationPreimage, eip191Digest, signCredential, ethRecoverEip191, signAgentInvocation, buildPayrollInvocation, compactDidFromBytes, b64uEncodeBytes, b64uDecodeStrict, _b64uEncode, } from "./client/delegation";
 export type { DelegationCredential, DelegationEnvelope, PayrollRunRequest, PayrollInvocation, SignDelegationResponse, BuildDelegationCredentialOpts, BuildPayrollInvocationOpts, } from "./client/delegation";
 export { metamask_sign, metamask_get_address, eth_get_address, createDefaultHandlers, createMlKemPublicKeyHandler, createRandomHandler, } from "./client/handlers";

package/dist/src/types/index.d.ts

@@ -41,3 +41,4 @@ export interface GuestToHostHandlers {
 export * from "./session";
 export * from "./auth";
 export * from "./user";
+export * from "./org-data";

package/dist/src/types/org-data.d.ts

@@ -0,0 +1,147 @@
+/**
+ * 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`.
+ */
+export 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`.
+ */
+export 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;
+}
+export type EmploymentStatus = "Active" | "Terminated";
+/** Singapore CPF residency categories. */
+export type ResidencyCategory = "Citizen" | "Pr1" | "Pr2" | "PrThreePlus" | "Foreigner";
+export type AgeBand = "Under35" | "Age35To45" | "Age45To50" | "Age50To55" | "Age55To60" | "Age60To65" | "Over65";
+export 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`.
+ */
+export 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`.
+ */
+export 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>`.
+ */
+export interface OrgWriters {
+    writers: string[];
+}
+/**
+ * Response type alias for org-grants-get.
+ *
+ * The wire body echoes the `contract_id` alongside the grant list.
+ */
+export interface OrgContractGrants {
+    contract_id: string;
+    grants: UserGrant[];
+}
+/** Response for `org-data-list`. */
+export 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`. */
+export 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.
+ */
+export 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;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@terminal3/t3n-sdk",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "type": "module",
   "description": "T3n TypeScript SDK - A minimal SDK that mirrors the server's RPC handler approach",
   "main": "dist/index.js",
@@ -30,6 +30,9 @@
     "copy-wasm": "mkdir -p dist/wasm/generated && cp -r src/wasm/generated/* dist/wasm/generated/",
     "test": "vitest run",
     "test:watch": "vitest",
+    "e2e:agent": "tsx scripts/payroll-v2-agent-e2e.ts",
+    "e2e:member": "tsx scripts/payroll-v2-e2e.ts",
+    "store-token": "tsx scripts/payroll-v2-store-token.ts",
     "test:coverage": "vitest run --coverage",
     "lint": "eslint src --ext .ts,.tsx",
     "lint:fix": "eslint src --ext .ts,.tsx --fix",