@terminal3/t3n-sdk 1.3.1 → 2.1.0

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

@@ -8,12 +8,21 @@ 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
  */
 export declare class T3nClient {
     private readonly config;
     private readonly transport;
+    /**
+     * Resolved node base URL. Snapshotted in the constructor so the
+     * typed contract wrappers (`kycStatus`, `getSelfEthAddress`, …)
+     * can call `getScriptVersion()` against the same host the
+     * transport talks to. Used only by the `script_version: "latest"`
+     * resolution path in {@link executeUserContract}.
+     */
+    private readonly effectiveBaseUrl;
     /**
      * Server-minted session ID, set by {@link handshake} from the
      * `Session-Id` response header (pentest M-1 / MAT-983). `null`
@@ -109,6 +118,32 @@ export declare class T3nClient {
      * @throws {ContractResponseError} when the response is not valid JSON
      */
     executeAndDecode<T = unknown>(payload: unknown, schema?: ContractResponseSchema<T>): Promise<T>;
+    /**
+     * Build the canonical `ExecuteActionRequest` shape the server
+     * expects in `node/primitives/src/action.rs::ExecuteActionRequest`
+     * (`script_name`, `script_version`, `function_name`, `input`,
+     * optional `pii_did`) and dispatch it through {@link execute}.
+     *
+     * Two pieces of glue live here that every typed user-contract
+     * wrapper would otherwise duplicate:
+     *
+     * 1. **Field naming.** The server deserialises strictly into
+     *    `script_name` / `script_version` / `function_name` —
+     *    sending `contract` / `version` / `function` produces
+     *    `Invalid action request: missing field …` 400s. Centralising
+     *    the names here means every wrapper agrees with the server.
+     * 2. **`"latest"` resolution.** `script_version` is `SemVer` on
+     *    the server, so a literal `"latest"` cannot be parsed. We
+     *    fetch the registered current version via
+     *    `GET /api/contracts/current?name=…` (cached per script name
+     *    in `getScriptVersion`) and forward the resolved
+     *    `MAJOR.MINOR.PATCH` string.
+     *
+     * Wrappers that need PII delegation can extend this helper
+     * later — current call sites are all SelfOnly so `pii_did` stays
+     * implicit.
+     */
+    private executeUserContract;
     /**
      * Return the authenticated user's Ethereum address from their
      * T3N-hosted per-user wallet, as a 0x-prefixed lowercase hex string.
@@ -206,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,8 @@ 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 { 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.1",
+  "version": "2.1.0",
   "type": "module",
   "description": "T3n TypeScript SDK - A minimal SDK that mirrors the server's RPC handler approach",
   "main": "dist/index.js",