@terminal3/t3n-sdk 1.3.2 → 2.3.0

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

@@ -0,0 +1,216 @@
+/**
+ * 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`. */
+export declare const DELEGATION_CREDENTIAL_DOMAIN: "ot3.delegation/1";
+/** Domain tag prepended to the agent-side pre-image. */
+export declare const DELEGATION_INVOCATION_DOMAIN: "ot3.invocation/1";
+export declare const VC_ID_LEN = 16;
+export declare const NONCE_LEN = 16;
+export declare const REQUEST_HASH_LEN = 32;
+export declare const AGENT_PUBKEY_LEN = 33;
+export declare const ETH_SIG_LEN = 65;
+export declare const MAX_CONTRACT_LEN = 46;
+export declare const MAX_FUNCTION_LEN = 64;
+export declare const MAX_SCOPE_LEN = 64;
+export declare const MAX_SCOPES_PER_CREDENTIAL = 32;
+export declare const MAX_METADATA_PER_CREDENTIAL = 16;
+export declare const MAX_METADATA_KEY_LEN = 64;
+export declare const MAX_METADATA_VALUE_LEN = 256;
+/** User-to-agent delegation credential body. */
+export 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. */
+export 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. */
+export 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. */
+export interface PayrollInvocation {
+    envelope: DelegationEnvelope;
+    request: PayrollRunRequest;
+}
+/** Response from `tee:delegation.sign`. */
+export interface SignDelegationResponse {
+    credential_jcs: Uint8Array;
+    user_sig: Uint8Array;
+}
+declare function b64uEncode(input: Uint8Array): string;
+declare function b64uDecode(input: string): Uint8Array;
+/**
+ * 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.
+ */
+export declare function b64uEncodeBytes(input: Uint8Array): string;
+/**
+ * Decode a base64url-no-pad string. Strict — rejects standard-alphabet
+ * `+` / `/` and any padding `=`.
+ */
+export declare function b64uDecodeStrict(input: string): Uint8Array;
+/** @internal — preserved alias for in-tree callers. Prefer
+ *  {@link b64uEncodeBytes} / {@link b64uDecodeStrict}. */
+export declare const _b64uEncode: typeof b64uEncode;
+/** @internal — preserved alias for in-tree callers. Prefer
+ *  {@link b64uEncodeBytes} / {@link b64uDecodeStrict}. */
+export declare const _b64uDecode: typeof b64uDecode;
+/** Build a `did:t3n:<40-hex>` from raw 20 bytes. */
+export 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`).
+ */
+export declare function canonicaliseCredential(credential: DelegationCredential): Uint8Array;
+/** Canonicalise an arbitrary {@link PayrollRunRequest} to JCS bytes. */
+export declare function canonicaliseRequest(request: PayrollRunRequest): Uint8Array;
+/** SHA-256 of the canonicalised request body. */
+export 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.
+ */
+export declare function buildInvocationPreimage(vcId: Uint8Array, nonce: Uint8Array, reqHash: Uint8Array): Uint8Array;
+/** Options for {@link buildDelegationCredential}. */
+export 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.
+ */
+export 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.
+ */
+export declare function validateCredentialBody(c: DelegationCredential): void;
+/** Compute the EIP-191 "personal_sign" digest of a message. */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export declare function signAgentInvocation(preimage: Uint8Array, secret: Uint8Array): Uint8Array;
+/** Options for {@link buildPayrollInvocation}. */
+export 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)`.
+ */
+export declare function buildPayrollInvocation(opts: BuildPayrollInvocationOpts): PayrollInvocation;
+export {};

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

@@ -9,3 +9,4 @@ export * from "./encryption";
 export * from "./actions";
 export * from "./request-parser";
 export * from "./contract-response";
+export * from "./delegation";

package/dist/src/client/t3n-client.d.ts

@@ -8,6 +8,7 @@ import { T3nClientConfig } from "./config";
 import { type ContractResponseSchema } from "./contract-response";
 import { SessionId, Did, SessionStatus, AuthInput, HandshakeResult } from "../types";
 import { KycPollOptions, KycStatus } from "../types/kyc";
+import { OtpChannel, OtpRequestInput, OtpRequestResult, OtpVerifyInput, OtpVerifyResult, SubmitUserInputArgs, SubmitUserInputResult } from "../types/user";
 /**
  * Main T3n SDK Client
  */
@@ -240,6 +241,116 @@ export 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.

package/dist/src/index.d.ts

@@ -18,6 +18,10 @@ export type { SessionId, Did, OidcCredentials, AuthInput, EthAuthInput, OidcAuth
 export { SessionStatus, AuthMethod, createEthAuthInput, createOidcAuthInput, } from "./types";
 export type { KycStatus, KycStatusKind, KycPollOptions, KycPollCadence, } from "./types/kyc";
 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 { 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";
 export type { WasmComponent, ClientHandshake, ClientAuth, SessionCrypto, WasmNextResult, } from "./wasm";
 export { loadWasmComponent } from "./wasm";

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

@@ -40,3 +40,4 @@ export interface GuestToHostHandlers {
 }
 export * from "./session";
 export * from "./auth";
+export * from "./user";

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

@@ -0,0 +1,194 @@
+/**
+ * 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`).
+ */
+import { T3nError } from "../utils/errors";
+/**
+ * OTP delivery channel. Matches the `OtpContactChannel` Rust enum
+ * with `serde(rename_all = "snake_case")`.
+ */
+export 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.
+ */
+export 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".
+ */
+export 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}.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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? }`.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@terminal3/t3n-sdk",
-  "version": "1.3.2",
+  "version": "2.3.0",
   "type": "module",
   "description": "T3n TypeScript SDK - A minimal SDK that mirrors the server's RPC handler approach",
   "main": "dist/index.js",
@@ -101,6 +101,9 @@
   "dependencies": {
     "@bytecodealliance/jco": "^1.17.6",
     "@bytecodealliance/preview2-shim": "^0.17.8",
+    "@noble/curves": "^2.2.0",
+    "@noble/hashes": "^2.2.0",
+    "canonicalize": "^3.0.0",
     "ethers": "^6.16.0"
   },
   "pnpm": {