@terminal3/t3n-sdk 1.3.2 → 2.3.0

package/dist/index.d.ts

@@ -325,6 +325,281 @@ type AuthInput = EthAuthInput | OidcAuthInput;
 declare function createEthAuthInput(address: string): EthAuthInput;
 declare function createOidcAuthInput(credentials: OidcCredentials): OidcAuthInput;
 
+/**
+ * Error classes for T3n SDK
+ */
+/**
+ * Base error class for T3n SDK errors
+ */
+declare class T3nError extends Error {
+    readonly code?: string | undefined;
+    constructor(message: string, code?: string | undefined);
+}
+/**
+ * Error thrown when session is in invalid state for operation
+ */
+declare class SessionStateError extends T3nError {
+    readonly currentState: string;
+    constructor(message: string, currentState: string);
+}
+/**
+ * Error thrown during authentication process
+ */
+declare class AuthenticationError extends T3nError {
+    readonly authMethod?: string | undefined;
+    constructor(message: string, authMethod?: string | undefined);
+}
+/**
+ * Error thrown during handshake process
+ */
+declare class HandshakeError extends T3nError {
+    constructor(message: string);
+}
+/**
+ * Error thrown during RPC communication.
+ *
+ * `message` is the human-readable error (preferring the server's
+ * `error.data.detail` when present, with the request id appended in
+ * `[<id>]` form so a UI that only surfaces `.message` still gives an
+ * operator something to grep). The structured fields below preserve
+ * the same info for callers that want to render or log them
+ * separately — e.g. a toast that shows `detail` but surfaces
+ * `requestId` in a "copy for support" affordance.
+ */
+declare class RpcError extends T3nError {
+    readonly rpcMethod?: string | undefined;
+    readonly httpStatus?: number | undefined;
+    /** Server-attached detail (JSON-RPC `error.data.detail`). User-facing kinds
+     *  carry the specific reason here; internal kinds omit it. */
+    readonly detail?: string | undefined;
+    /** Per-request correlation id (JSON-RPC `error.data.request_id`). */
+    readonly requestId?: string | undefined;
+    constructor(message: string, rpcMethod?: string | undefined, httpStatus?: number | undefined, 
+    /** Server-attached detail (JSON-RPC `error.data.detail`). User-facing kinds
+     *  carry the specific reason here; internal kinds omit it. */
+    detail?: string | undefined, 
+    /** Per-request correlation id (JSON-RPC `error.data.request_id`). */
+    requestId?: string | undefined);
+}
+/**
+ * Error thrown when WASM operations fail
+ */
+declare class WasmError extends T3nError {
+    readonly operation?: string | undefined;
+    readonly payload?: unknown | undefined;
+    constructor(message: string, operation?: string | undefined, payload?: unknown | undefined);
+}
+/**
+ * Decode WASM error message from comma-separated byte array format
+ * WASM errors often come as "83,101,114,100,101..." which represents ASCII bytes
+ *
+ * @param errorMessage - The error message string that may contain comma-separated bytes
+ * @returns Decoded error message if it was encoded, otherwise original message
+ */
+declare function decodeWasmErrorMessage(errorMessage: string): string;
+/**
+ * Extract and decode error from WASM ComponentError
+ *
+ * @param error - The error object from WASM
+ * @returns Decoded error message
+ */
+declare function extractWasmError(error: unknown): string;
+
+/**
+ * MAT-1374 — wire types for the explicit `otp-request` /
+ * `otp-verify` / slim `user-upsert` exports on `tee:user/contracts`
+ * (`tee:user@2.0.0`).
+ *
+ * Pre-2.0.0 the user contract dispatched OTP request and OTP verify
+ * implicitly from the input shape of a single `user-upsert` call.
+ * 2.0.0 splits that surface into three explicit functions; the
+ * shapes here mirror the Rust types in
+ * `node/tee_contracts/user/src/otp_types.rs` and
+ * `node/tee_contracts/user/src/upsert_types.rs`.
+ *
+ * Keep the two in sync — bytes flow directly from the contract
+ * through the JSON-RPC envelope into the SDK wrappers
+ * (`T3nClient.otpRequest`, `T3nClient.otpVerify`,
+ * `T3nClient.submitUserInput`).
+ */
+
+/**
+ * OTP delivery channel. Matches the `OtpContactChannel` Rust enum
+ * with `serde(rename_all = "snake_case")`.
+ */
+type OtpChannel = "email" | "sms";
+/**
+ * Discriminated OTP contact target. Mirrors the Rust `OtpRequest` enum
+ * (`email_channel` / `sms_channel` on the wire). Exactly one branch is
+ * set — no parallel optional email + phone with a separate channel tag.
+ *
+ * The legacy `keys.generic_api.otp_channel` body shadow was removed
+ * in 2.0.0 — the contract rejects calls carrying it with a
+ * `legacy_field` error.
+ */
+type OtpRequestInput = {
+    emailChannel: {
+        emailAddress: string;
+    };
+} | {
+    smsChannel: {
+        phoneNumber: string;
+    };
+};
+/**
+ * Response returned by `otp-request`. Mirrors `OtpResponse` in
+ * `otp_types.rs`.
+ *
+ * - `contact` echoes the OTP destination so clients that race
+ *   multiple channels can correlate replies.
+ * - `expiresAtSec` is the Unix-second TTL the host minted for the
+ *   pending OTP. Absent in `skip_otp` test environments.
+ * - `status` is `"otp_pending"` on the happy path. `"otp_failed"`
+ *   only appears on retry without a fresh request — usually you
+ *   shouldn't see it on `otp-request`.
+ * - `txHash` is the host-enriched ledger ref for the OTP-pending
+ *   write (the contract leaves it `null`; the host injects).
+ * - `isNewProfile` is `true` on a fresh DID's first OTP request —
+ *   read this to detect "did the user just register".
+ */
+interface OtpRequestResult {
+    contact: string;
+    channel: OtpChannel;
+    expiresAtSec?: number;
+    status?: string;
+    txHash?: string;
+    isNewProfile?: boolean;
+}
+/**
+ * Input to `T3nClient.otpVerify`. `otpCode` is mandatory; `request`
+ * repeats the same discriminated contact shape as {@link OtpRequestInput}.
+ */
+interface OtpVerifyInput {
+    otpCode: string;
+    request: OtpRequestInput;
+}
+/**
+ * Suggestion surfaced when the bind-target contact already belongs
+ * to another DID. The contract refuses to silently steal the
+ * authenticator; the caller must resolve the merge (typically via
+ * `merge-profiles`) before re-attempting verify.
+ */
+interface OtpMergeSuggestion {
+    existingDid: string;
+    currentDid: string;
+    email?: string;
+    phone?: string;
+    channel: OtpChannel;
+}
+/**
+ * Response returned by `otp-verify`. Mirrors
+ * `OtpVerifyResponse` in `otp_types.rs`.
+ *
+ * - `email` is populated on `channel = "email"` success;
+ *   `phone` on `channel = "sms"` success. Mutually exclusive on
+ *   the happy path.
+ * - `status` carries `"otp_failed"` / `"otp_expired"` on retry; the
+ *   happy path leaves it `undefined`.
+ * - `mergeSuggestion` is set when the contact-to-bind is already
+ *   owned by another DID. Wire it into your merge UX.
+ */
+interface OtpVerifyResult {
+    txHash?: string;
+    did: string;
+    channel: OtpChannel;
+    email?: string;
+    phone?: string;
+    status?: string;
+    mergeSuggestion?: OtpMergeSuggestion;
+    isNewProfile?: boolean;
+}
+/**
+ * Level-1 user-input fields accepted by the slim `user-upsert`.
+ * The Rust contract validates these via `validate_profile`; the
+ * shape is intentionally open so callers can add provider-specific
+ * fields on top of the canonical six.
+ */
+interface UserInputProfile {
+    firstName?: string;
+    lastName?: string;
+    email_address?: string;
+    phone_number?: string;
+    birthdate?: string;
+    nationality?: string;
+    [key: string]: unknown;
+}
+/**
+ * Input to `T3nClient.submitUserInput`. Maps onto the slim
+ * `user-upsert` request shape: `{ profile, organisation_did?,
+ * attestations?, keys? }`.
+ */
+interface SubmitUserInputArgs {
+    profile: UserInputProfile;
+    organisationDid?: string;
+    attestations?: unknown;
+    keys?: Record<string, unknown>;
+    /**
+     * KYC webhook orphan-attestation flow. When set, the contract
+     * skips the email-not-verified gate and only records the
+     * attestation if the DID has no profile yet (T3-TS-026 §13).
+     * Most callers should leave this `undefined`.
+     */
+    requireExistingUser?: boolean;
+}
+/**
+ * Response shape returned by the slim `user-upsert`. Carries the
+ * post-merge tx hash plus the L1 merge diagnostics
+ * (`refusedFields`, `mergeSuggestion`) the pre-2.0.0 omnibus
+ * `UpsertResponse` already surfaced.
+ */
+interface SubmitUserInputResult {
+    txHash?: string;
+    refusedFields?: string[];
+    mergeSuggestion?: OtpMergeSuggestion;
+    userFound?: boolean;
+}
+/**
+ * Discriminator for {@link UserUpsertError}. Mirrors the
+ * `UserUpsertError` Rust enum and its `<code>:<detail>` wire
+ * format (see `upsert_types.rs::UserUpsertError::code`). Branch
+ * with a `switch` over `kind`.
+ *
+ * - `EmailNotVerified` — the slim `user-upsert` was called against
+ *   a DID that has no verified email and no proving authenticator.
+ *   Run `otpRequest` + `otpVerify` first (or accept an
+ *   OIDC/Email-authed session).
+ * - `LegacyField` — caller passed a pre-2.0.0 dispatch field
+ *   (`otp_code` to a non-verify export, or
+ *   `keys.generic_api.otp_channel` anywhere). Migrate the call
+ *   site to the new explicit functions.
+ * - `UserNotFound` — `requireExistingUser` was set but no profile
+ *   exists for the DID. The attestation is recorded for audit;
+ *   no profile created.
+ */
+type UserUpsertErrorKind = "EmailNotVerified" | "LegacyField" | "UserNotFound";
+/**
+ * Typed wrapper for the `<code>:<detail>` errors the slim
+ * `user-upsert` and the OTP entry points emit. `kind` is the
+ * structured discriminator the SDK derives from the error code
+ * prefix; `code` and `detail` retain the wire components for
+ * fall-through logging.
+ *
+ * Throw site: `T3nClient.submitUserInput` (and friends) when the
+ * contract returns a string error matching the
+ * `<code>:<detail>` shape.
+ */
+declare class UserUpsertError extends T3nError {
+    readonly kind: UserUpsertErrorKind | "Unknown";
+    readonly detail: string;
+    constructor(code: string, detail: string);
+    /**
+     * Try to parse a contract error string into a `UserUpsertError`.
+     * Returns `null` if `raw` doesn't match the `<code>:<detail>`
+     * shape — caller falls back to a generic error.
+     */
+    static fromWire(raw: string): UserUpsertError | null;
+}
+
 /**
  * Public types export for T3n SDK
  */
@@ -515,86 +790,6 @@ interface T3nClientConfig {
     handlers?: GuestToHostHandlers;
 }
 
-/**
- * Error classes for T3n SDK
- */
-/**
- * Base error class for T3n SDK errors
- */
-declare class T3nError extends Error {
-    readonly code?: string | undefined;
-    constructor(message: string, code?: string | undefined);
-}
-/**
- * Error thrown when session is in invalid state for operation
- */
-declare class SessionStateError extends T3nError {
-    readonly currentState: string;
-    constructor(message: string, currentState: string);
-}
-/**
- * Error thrown during authentication process
- */
-declare class AuthenticationError extends T3nError {
-    readonly authMethod?: string | undefined;
-    constructor(message: string, authMethod?: string | undefined);
-}
-/**
- * Error thrown during handshake process
- */
-declare class HandshakeError extends T3nError {
-    constructor(message: string);
-}
-/**
- * Error thrown during RPC communication.
- *
- * `message` is the human-readable error (preferring the server's
- * `error.data.detail` when present, with the request id appended in
- * `[<id>]` form so a UI that only surfaces `.message` still gives an
- * operator something to grep). The structured fields below preserve
- * the same info for callers that want to render or log them
- * separately — e.g. a toast that shows `detail` but surfaces
- * `requestId` in a "copy for support" affordance.
- */
-declare class RpcError extends T3nError {
-    readonly rpcMethod?: string | undefined;
-    readonly httpStatus?: number | undefined;
-    /** Server-attached detail (JSON-RPC `error.data.detail`). User-facing kinds
-     *  carry the specific reason here; internal kinds omit it. */
-    readonly detail?: string | undefined;
-    /** Per-request correlation id (JSON-RPC `error.data.request_id`). */
-    readonly requestId?: string | undefined;
-    constructor(message: string, rpcMethod?: string | undefined, httpStatus?: number | undefined, 
-    /** Server-attached detail (JSON-RPC `error.data.detail`). User-facing kinds
-     *  carry the specific reason here; internal kinds omit it. */
-    detail?: string | undefined, 
-    /** Per-request correlation id (JSON-RPC `error.data.request_id`). */
-    requestId?: string | undefined);
-}
-/**
- * Error thrown when WASM operations fail
- */
-declare class WasmError extends T3nError {
-    readonly operation?: string | undefined;
-    readonly payload?: unknown | undefined;
-    constructor(message: string, operation?: string | undefined, payload?: unknown | undefined);
-}
-/**
- * Decode WASM error message from comma-separated byte array format
- * WASM errors often come as "83,101,114,100,101..." which represents ASCII bytes
- *
- * @param errorMessage - The error message string that may contain comma-separated bytes
- * @returns Decoded error message if it was encoded, otherwise original message
- */
-declare function decodeWasmErrorMessage(errorMessage: string): string;
-/**
- * Extract and decode error from WASM ComponentError
- *
- * @param error - The error object from WASM
- * @returns Decoded error message
- */
-declare function extractWasmError(error: unknown): string;
-
 /**
  * Contract response decoding for {@link T3nClient.execute}.
  *
@@ -1030,6 +1225,116 @@ declare class T3nClient {
      *   row exists yet), or if the response shape is unexpected.
      */
     kycStatus(providerId?: string): Promise<KycStatus>;
+    /**
+     * Dispatch a one-time code to the supplied contact via the host's
+     * OTP provider. Backed by `tee:user/contracts::otp-request`.
+     *
+     * The contract persists the unverified contact in the channel's
+     * pending slot (`pending_email` / `pending_phone`) and returns
+     * `OtpRequestResult` with `status = "otp_pending"` (or `undefined`
+     * when the node is configured with `skip_otp = true`). The next
+     * step is {@link otpVerify} with the code the user typed.
+     *
+     * Behaviour notes:
+     *
+     * - Contact is a discriminated object: `emailChannel` or
+     *   `smsChannel` (mirrors Rust `OtpRequest`). The legacy
+     *   `keys.generic_api.otp_channel` body shadow is rejected by the
+     *   contract.
+     * - SMS channel is gated on a verified email. Calling with
+     *   `channel = "sms"` against a DID that hasn't completed an
+     *   email roundtrip first throws.
+     * - On a fresh DID's first call, `result.isNewProfile === true`.
+     *   Use this signal — not [[otpVerify]]'s response — for "did the
+     *   user just register" gating.
+     *
+     * @throws {RpcError} if the node rejects the action; the message
+     *   carries the contract-side detail (e.g. sequential-flow guard
+     *   when the email is missing).
+     */
+    otpRequest(input: OtpRequestInput): Promise<OtpRequestResult>;
+    /**
+     * Redeem a one-time code and bind the contact to the
+     * authenticated DID. Backed by
+     * `tee:user/contracts::otp-verify`.
+     *
+     * On success the contract promotes the pending contact back to
+     * the canonical slot, writes the AUTH_MAP / DIDS_MAP /
+     * USER_AUTHS_MAP authenticator entries, stamps
+     * `verified_contacts.{email,phone}`, and mints the ambient
+     * `t3n.personal.contact.1` ownership VC when both contacts are
+     * now verified.
+     *
+     * If the contact is already owned by a different DID the
+     * contract refuses to silently reparent the authenticator and
+     * surfaces a `mergeSuggestion` instead — the caller resolves the
+     * merge (typically via {@link mergeProfiles}) and re-attempts.
+     *
+     * On a wrong / expired code the contract returns the result with
+     * `status = "otp_failed"` or `"otp_expired"` — no exception is
+     * thrown, the error is surfaced as data so the UI can stay on
+     * the verify screen and let the user retry.
+     *
+     * @throws {RpcError} if the node rejects the action outright
+     *   (network / decode / bad input shape). Branch on
+     *   `result.status` for retryable OTP failures.
+     */
+    otpVerify(input: OtpVerifyInput): Promise<OtpVerifyResult>;
+    /**
+     * Submit Level-1 user-input fields to the slim
+     * `tee:user/contracts::user-upsert`. The contract merges the
+     * supplied profile fields, validates them, mints
+     * `t3n.user-input.kyc.1` once every Level-1 field is present, and
+     * commits the write.
+     *
+     * **Pre-condition** (MAT-1374): the DID must already have a
+     * verified email — either because {@link otpVerify} bound one or
+     * because the session carries a proving authenticator (OIDC /
+     * Email auth). Calls without proof are rejected with
+     * {@link UserUpsertError} `kind = "EmailNotVerified"`. The
+     * recommended UX is "request OTP -> verify OTP -> submit user
+     * input" (or use {@link runOtpThenUserInput} which chains all
+     * three).
+     *
+     * The KYC webhook orphan-attestation flow stays here: when
+     * `requireExistingUser` is set, the contract identifies the user
+     * by DID (vendorData) instead of email and the gate is bypassed.
+     *
+     * @throws {UserUpsertError} when the contract returns a typed
+     *   error (`email_not_verified`, `legacy_field`, `user_not_found`).
+     *   Branch on `err.kind`.
+     * @throws {RpcError} for non-typed transport / decode failures.
+     */
+    submitUserInput(input: SubmitUserInputArgs): Promise<SubmitUserInputResult>;
+    /**
+     * Convenience helper: run the explicit OTP roundtrip and submit
+     * the slim user-upsert in one call.
+     *
+     * The caller supplies a `getOtpCode(contact, channel)` callback
+     * the SDK invokes between request and verify — this is where
+     * a UI prompts the user to type the code that arrived on email
+     * / SMS. Throw from the callback to abort the flow; the helper
+     * does not retry on its own.
+     *
+     * Returns the slim `submitUserInput` result on success. Throws
+     * {@link UserUpsertError} or `RpcError` on the same conditions
+     * as the underlying wrappers.
+     *
+     * Optional, opt-in path — the recommended default is to call
+     * {@link otpRequest}, {@link otpVerify}, and
+     * {@link submitUserInput} explicitly so the application owns the
+     * flow.
+     */
+    runOtpThenUserInput(args: {
+        channel: OtpChannel;
+        emailAddress?: string;
+        phoneNumber?: string;
+        profile: SubmitUserInputArgs["profile"];
+        organisationDid?: string;
+        attestations?: unknown;
+        keys?: Record<string, unknown>;
+        getOtpCode: (contact: string, channel: OtpChannel) => Promise<string> | string;
+    }): Promise<SubmitUserInputResult>;
     /**
      * Poll `kyc-status` until a terminal status arrives or the
      * configured timeout elapses.
@@ -1202,6 +1507,211 @@ declare function createRandomHandler(): GuestToHostHandler;
  */
 declare function createDefaultHandlers(baseUrl: string): GuestToHostHandlers;
 
+/**
+ * User-to-Agent Delegation (T3-TS-030).
+ *
+ * TypeScript reference implementation of the delegation credential and
+ * envelope shapes defined in `node/tee_contracts/delegation-types`.
+ *
+ * The wire shape is byte-for-byte identical to the Rust source — pinned
+ * by the KAT fixtures under `tests/kat/`. Specifically:
+ *
+ *   - `not_before_secs` / `not_after_secs` / `batch_cap_cents` are
+ *     emitted as **JSON strings** (e.g. `"1700086400"`) so JS Number
+ *     precision never enters the canonicalisation surface.
+ *   - `nonce` (16 B), `vc_id` (16 B), `request_hash` (32 B),
+ *     `agent_pubkey` (33 B compressed secp256k1), `user_sig`,
+ *     `agent_sig` are emitted as **base64url-no-pad** strings.
+ *   - `org_did` / `user_did` are emitted as `did:t3n:<40-hex>` (the
+ *     `CompactDid` `Display` form).
+ *
+ * Canonicalisation uses the npm `canonicalize` package (RFC 8785 JCS).
+ * Cryptography uses `@noble/curves` (secp256k1) and `@noble/hashes`
+ * (sha256, keccak_256).
+ */
+/** Domain tag carried in `DelegationCredential.v`. */
+declare const DELEGATION_CREDENTIAL_DOMAIN: "ot3.delegation/1";
+/** Domain tag prepended to the agent-side pre-image. */
+declare const DELEGATION_INVOCATION_DOMAIN: "ot3.invocation/1";
+declare const VC_ID_LEN = 16;
+declare const NONCE_LEN = 16;
+declare const REQUEST_HASH_LEN = 32;
+declare const AGENT_PUBKEY_LEN = 33;
+declare const ETH_SIG_LEN = 65;
+/** User-to-agent delegation credential body. */
+interface DelegationCredential {
+    /** Domain tag, must equal {@link DELEGATION_CREDENTIAL_DOMAIN}. */
+    v: string;
+    /** `did:t3n:<40-hex>` user DID. */
+    user_did: string;
+    /** 33-byte compressed secp256k1 public key the agent uses per call. */
+    agent_pubkey: Uint8Array;
+    /** `did:t3n:<40-hex>` org DID. */
+    org_did: string;
+    /** Contract id, e.g. `"tee:payroll"`. */
+    contract: string;
+    /** Function name, e.g. `"run-payroll"`. */
+    function: string;
+    /** Org-data scopes the contract may read on this user's behalf. */
+    scopes: string[];
+    /** Flat key-value labels checked against the org grant. */
+    metadata: Record<string, string>;
+    /** Inclusive lower bound of the validity window (unix seconds). */
+    not_before_secs: bigint;
+    /** Inclusive upper bound of the validity window (unix seconds). */
+    not_after_secs: bigint;
+    /** Random 16-byte credential id. */
+    vc_id: Uint8Array;
+}
+/** Envelope wrapping a contract-specific request body. */
+interface DelegationEnvelope {
+    /** RFC 8785 JCS bytes of the credential, exactly as signed. */
+    credential_jcs: Uint8Array;
+    /** 65-byte EIP-191 signature over `credential_jcs`. */
+    user_sig: Uint8Array;
+    /** Per-call agent signature over the invocation pre-image. */
+    agent_sig: Uint8Array;
+    /** 16-byte agent-generated per-call nonce. */
+    nonce: Uint8Array;
+    /** SHA-256 of the canonical request body. */
+    request_hash: Uint8Array;
+}
+/** Payroll-specific request body wrapped by a delegation envelope. */
+interface PayrollRunRequest {
+    /** `did:t3n:<40-hex>` org id. */
+    org_id: string;
+    cycle_id: string;
+    pay_period_start: string;
+    pay_period_end: string;
+    /** Total cap on the run's net disbursement, in cents. */
+    batch_cap_cents: bigint;
+    /** `employee_id` → previous-cycle baseline net disbursement, cents (decimal string). */
+    historical_baselines: Record<string, string>;
+}
+/** Convenience wrapper paired with the matching delegation envelope. */
+interface PayrollInvocation {
+    envelope: DelegationEnvelope;
+    request: PayrollRunRequest;
+}
+/** Response from `tee:delegation.sign`. */
+interface SignDelegationResponse {
+    credential_jcs: Uint8Array;
+    user_sig: Uint8Array;
+}
+declare function b64uEncode(input: Uint8Array): string;
+/**
+ * Encode raw bytes to base64url-no-pad (RFC 4648 §5 with padding
+ * dropped). The same encoding T3-TS-030 wire-shape uses for binary
+ * fields (`agent_pubkey`, `vc_id`, `nonce`, `agent_sig`, `user_sig`,
+ * `request_hash`, `credential_jcs`).
+ *
+ * Public API since v2.2: callers building `PayrollInvocation` JSON
+ * for the wire (e.g. the t3n-mcp `runPayroll` handler) need this
+ * encoder to match the contract's deserializer.
+ */
+declare function b64uEncodeBytes(input: Uint8Array): string;
+/**
+ * Decode a base64url-no-pad string. Strict — rejects standard-alphabet
+ * `+` / `/` and any padding `=`.
+ */
+declare function b64uDecodeStrict(input: string): Uint8Array;
+/** @internal — preserved alias for in-tree callers. Prefer
+ *  {@link b64uEncodeBytes} / {@link b64uDecodeStrict}. */
+declare const _b64uEncode: typeof b64uEncode;
+/** Build a `did:t3n:<40-hex>` from raw 20 bytes. */
+declare function compactDidFromBytes(bytes: Uint8Array): string;
+/**
+ * Canonicalise a {@link DelegationCredential} to RFC 8785 JCS bytes.
+ *
+ * Output is byte-identical to the Rust `canonicalise_credential` in
+ * `delegation-types` (pinned by `tests/kat/credential.json`).
+ */
+declare function canonicaliseCredential(credential: DelegationCredential): Uint8Array;
+/** Canonicalise an arbitrary {@link PayrollRunRequest} to JCS bytes. */
+declare function canonicaliseRequest(request: PayrollRunRequest): Uint8Array;
+/** SHA-256 of the canonicalised request body. */
+declare function requestHash(request: PayrollRunRequest): Uint8Array;
+/**
+ * Build the agent-side pre-image bytes:
+ * `utf8(DELEGATION_INVOCATION_DOMAIN) || vc_id || nonce || request_hash`.
+ *
+ * SHA-256 of these bytes is what the agent's secp256k1 signature is
+ * verified against.
+ */
+declare function buildInvocationPreimage(vcId: Uint8Array, nonce: Uint8Array, reqHash: Uint8Array): Uint8Array;
+/** Options for {@link buildDelegationCredential}. */
+interface BuildDelegationCredentialOpts {
+    user_did: string;
+    agent_pubkey: Uint8Array;
+    org_did: string;
+    contract: string;
+    function: string;
+    scopes?: string[];
+    metadata?: Record<string, string>;
+    not_before_secs: bigint | number;
+    not_after_secs: bigint | number;
+    vc_id: Uint8Array;
+}
+/**
+ * Construct a {@link DelegationCredential} and validate body-level
+ * invariants (domain, lengths, validity window). Throws on the same
+ * conditions the Rust `validate_credential_body` rejects.
+ */
+declare function buildDelegationCredential(opts: BuildDelegationCredentialOpts): DelegationCredential;
+/**
+ * Body-level validation matching `delegation-types::validate_credential_body`,
+ * minus the `now`/`max_validity_secs` checks (which are caller-supplied).
+ * Throws with a message identifying the offending invariant.
+ */
+declare function validateCredentialBody(c: DelegationCredential): void;
+/** Compute the EIP-191 "personal_sign" digest of a message. */
+declare function eip191Digest(msg: Uint8Array): Uint8Array;
+/**
+ * EIP-191 sign `jcs` under `secret`, returning a 65-byte signature
+ * (`r || s || v`, with `v` in 27/28 — Ethereum convention) and the
+ * recovered 20-byte ETH address.
+ */
+declare function signCredential(jcs: Uint8Array, secret: Uint8Array): {
+    sig: Uint8Array;
+    addr: Uint8Array;
+};
+/**
+ * Recover the 20-byte ETH address that signed `msg` under EIP-191.
+ * Mirrors `delegation-types::eth_recover_eip191`.
+ *
+ * **Signature malleability — accepted by design.** This routine does
+ * not enforce low-s. EIP-2 mandates low-s for *transaction* signatures,
+ * but EIP-191 / `personal_sign` has no such requirement, and ethers.js
+ * / MetaMask / web3.js produce both shapes. Two distinct `(r, s)` and
+ * `(r, n − s)` pairs verify under the same recovered address — replay
+ * protection comes from the envelope's `request_hash` + `nonce`, not
+ * from byte-uniqueness of the signature.
+ */
+declare function ethRecoverEip191(msg: Uint8Array, sig: Uint8Array): Uint8Array;
+/**
+ * Sign the agent-side invocation pre-image. The signature is raw
+ * compact ECDSA (64 bytes) over `sha256(preimage)` — what
+ * `delegation-types::verify_agent_sig` accepts as the 64-byte form.
+ */
+declare function signAgentInvocation(preimage: Uint8Array, secret: Uint8Array): Uint8Array;
+/** Options for {@link buildPayrollInvocation}. */
+interface BuildPayrollInvocationOpts {
+    credentialJcs: Uint8Array;
+    userSig: Uint8Array;
+    /** Credential's `vc_id` — needed for the agent pre-image. */
+    vcId: Uint8Array;
+    nonce: Uint8Array;
+    request: PayrollRunRequest;
+    agentSecret: Uint8Array;
+}
+/**
+ * Assemble a complete {@link PayrollInvocation} (envelope + request)
+ * given a user-signed credential and a per-call agent secret. Computes
+ * `request_hash` from the canonical request bytes and produces an
+ * `agent_sig` over `sha256(invocation_preimage)`.
+ */
+declare function buildPayrollInvocation(opts: BuildPayrollInvocationOpts): PayrollInvocation;
+
 /**
  * Cryptographic utilities for T3n SDK
  *
@@ -1423,5 +1933,5 @@ declare function clearKeyCache(): void;
  */
 declare function loadConfig(baseUrl?: string): SdkConfig;
 
-export { AuthMethod, AuthenticationError, ContractResponseError, DEFAULT_KYC_POLL_CADENCE, HandshakeError, HttpTransport, KycStatusTimeoutError, LogLevel, MockTransport, NODE_URLS, RpcError, SessionStateError, SessionStatus, T3nClient, T3nError, TERMINAL_KYC_STATUSES, WasmError, bytesToString, clearKeyCache, createDefaultHandlers, createEthAuthInput, createLogger, createMlKemPublicKeyHandler, createOidcAuthInput, createRandomHandler, decodeWasmErrorMessage, eth_get_address, extractWasmError, fetchDkgAttestation, fetchMlKemPublicKey, generateRandomString, generateUUID, getEnvironment, getEnvironmentName, getGlobalLogLevel, getLogger, getNodeUrl, getScriptVersion, loadConfig, loadWasmComponent, metamask_get_address, metamask_sign, parseContractResponse, redactSecrets, redactSecretsFromJson, setEnvironment, setGlobalLogLevel, setNodeUrl, stringToBytes, validateConfig, verifyDkgAttestation, verifyTdxQuote };
-export type { AuthInput, ClientAuth, ClientHandshake, ConfigValidationResult, ContractResponseSchema, Did, DkgAttestation, DkgVerifyResult, Environment, EthAuthInput, GuestToHostHandler, GuestToHostHandlers, HandshakeResult, JsonRpcRequest, JsonRpcResponse, KycPollCadence, KycPollOptions, KycStatus, KycStatusKind, Logger, OidcAuthInput, OidcCredentials, PeerQuoteResult, QuoteVerifyResult, SdkConfig, SessionCrypto, SessionId, T3nClientConfig, Transport, WasmComponent, WasmNextResult };
+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 };