@terminal3/t3n-sdk 1.2.1 → 1.3.2

package/README.md

@@ -560,6 +560,128 @@ When upserting a profile with an email address (either for a new profile or when
 3. Guide you through the Google OAuth flow
 4. Allow you to paste the ID token back into the terminal
 
+#### KYC Walkthrough (MAT-1371)
+
+The `--kyc-walkthrough` mode drives the full MetaMask KYC L1 + L2 flow against a running Trinity node, end-to-end, without needing the actual MetaMask front-end. It is useful for:
+
+- Smoke-testing a freshly-built node (`node/bin/start-local`) before pointing the real FE at it.
+- Reproducing edge cases (rejected KYC, OTP expiry, merge suggestions) deterministically.
+- Showing internal stakeholders what the L1 + L2 flow looks like without spinning up MetaMask Snap + Veriff sandbox.
+
+**Quick start (interactive):**
+
+```bash
+pnpm demo:real-wasm --kyc-walkthrough
+```
+
+The walkthrough then prompts at each step in the order Trinity expects:
+
+1. **Handshake** + **authenticate** (existing prompts — wallet / OIDC).
+2. **Email OTP** — request + verify on `tee:user/contracts::user-upsert` (email channel).
+3. **Phone OTP** — request + verify on the same function (SMS channel via `keys.generic_api.otp_channel: "sms"` shadow). Gated by the contract on a verified email.
+4. **Level 1 user-input** — single `user-upsert` call carrying `first_name`, `last_name`, `country_of_residence`, `document_issuance_country`, `ssn`, `address`.
+5. **`create-kyc-provider-session`** ([MAT-1284](https://linear.app/terminal3/issue/MAT-1284)) — prints the Veriff `session_url`. The CLI does **not** auto-open the URL.
+6. **`kyc-status` poll** — until terminal status (`verified`, `rejected`, or `orphan`) or the timeout fires. Each snapshot is logged.
+
+**Veriff is driven manually.** The CLI prints the `session_url` and waits — open it in your browser, drive the Veriff flow to the desired terminal state (approve / reject / abandon), then come back to the terminal. The poll loop will see the contract update and surface the terminal status.
+
+##### KYC walkthrough flags
+
+| Flag | Default | Meaning |
+|---|---|---|
+| `--kyc-walkthrough` | off | Enable the walkthrough mode. Implicitly enabled by `--scenario`. |
+| `--scenario <name>` | none | One of `happy-path-l1`, `happy-path-l2`, `rejected`. See *Scenarios* below. |
+| `--auth-method <eth\|metamask\|oidc>` | interactive prompt | Skip the auth-method prompt. |
+| `--email <addr>` | interactive prompt (or `demo+kyc@example.com` in scenario mode) | Email to verify in the L1 OTP step. |
+| `--phone <e164>` | interactive prompt (or `+14155552671` in scenario mode) | Phone in E.164 format for the SMS OTP step. |
+| `--first-name <name>` | interactive prompt (or `Ada` in scenario mode) | L1 first name. |
+| `--last-name <name>` | interactive prompt (or `Lovelace` in scenario mode) | L1 last name. |
+| `--country <ISO-2>` | `US` | Convenience: applies to both `country_of_residence` and `document_issuance_country` unless overridden individually. |
+| `--country-of-residence <ISO-2>` | `--country` value | L1 residence country. |
+| `--document-issuance-country <ISO-2>` | `--country` value | L1 document issuance country. |
+| `--ssn <value>` | interactive prompt (or `123-45-6789` in scenario mode) | L1 SSN (9 digits or `XXX-XX-XXXX`). |
+| `--address <text>` | interactive prompt (or default address in scenario mode) | L1 residential address. |
+| `--kyc-provider-id <id>` | `veriff` | Provider id passed to `create-kyc-provider-session` and `kyc-status`. |
+| `--kyc-poll-fast-ms <ms>` | `2000` | Fast-cadence poll interval (T3-TS-026 §8.4). |
+| `--kyc-poll-slow-ms <ms>` | `5000` | Slow-cadence poll interval. |
+| `--kyc-poll-switch-at-ms <ms>` | `30000` | Elapsed threshold to switch from fast to slow. |
+| `--kyc-poll-timeout-ms <ms>` | `300000` | Total cap before `KycStatusTimeoutError` is raised. |
+| `--skip-create-kyc-session` | off | Stop after L1 — useful when no Veriff sandbox is configured. |
+
+##### Scenarios
+
+Pre-baked shortcuts that auto-feed answers (mock-mode OTP codes, default L1 fields) so the walkthrough runs without operator input. All scenarios still require a running Trinity node configured with the **mock OTP provider** (otherwise the deterministic OTP code algorithm doesn't match what the node actually generated).
+
+| Scenario | What it does | Veriff |
+|---|---|---|
+| `happy-path-l1` | Email OTP → phone OTP → L1 upsert. Stops before `create-kyc-provider-session`. | Not exercised. |
+| `happy-path-l2` | Full L1 + L2 flow. Asserts `kyc-status` terminates with `verified`. | **Manual**: open the printed `session_url` and drive Veriff to approval. |
+| `rejected` | Full L1 + L2 flow. Asserts `kyc-status` terminates with `rejected`. | **Manual**: open the printed `session_url` and drive Veriff to a rejection. |
+
+Examples:
+
+```bash
+# L1-only happy path — no Veriff sandbox needed
+pnpm demo:real-wasm --scenario happy-path-l1
+
+# Full L1 + L2 happy path — drive Veriff to approved manually
+pnpm demo:real-wasm --scenario happy-path-l2
+
+# Rejection scenario — drive Veriff to a rejection manually
+pnpm demo:real-wasm --scenario rejected
+
+# Custom inputs without a scenario
+pnpm demo:real-wasm --kyc-walkthrough \
+  --auth-method eth \
+  --email me@example.com \
+  --phone +14155551234 \
+  --country US \
+  --first-name Ada --last-name Lovelace
+```
+
+##### Mock-mode OTP code
+
+When the Trinity node runs against the mock OTP provider (the default for `node/bin/start-local`), the OTP code is a **deterministic** 6-digit hash of the contact value. The walkthrough always prints the calculated mock code in the OTP-pending log line, so even without a scenario you can simply enter that code at the prompt to advance.
+
+The algorithm matches `node/wasm/src/otp.rs` byte-for-byte: `String((hash * 31 + byte_i) % 1_000_000).padStart(6, "0")` over the UTF-8 bytes of the contact (email address or E.164 phone).
+
+##### Sample output (excerpt)
+
+```text
+🚦 KYC walkthrough mode enabled (MAT-1371)
+   Scenario: happy-path-l1
+
+📧 Step 5/8 — Email OTP: demo+kyc@example.com
+5️⃣ Executing action: user-upsert...
+   ✅ Action executed successfully
+📨 Email verification required
+   📬 OTP code sent to: demo+kyc@example.com
+   📡 Channel: email
+   💡 Mock mode OTP code (deterministic): 482913
+   🤖 Scenario auto-feeding OTP code: 482913
+🔄 Verifying Email OTP code...
+5️⃣ Executing action: user-upsert...
+   ✅ OTP verified successfully
+   📝 Transaction hash: tx:1:42
+
+📱 Step 6/8 — Phone OTP: +14155552671
+6️⃣ Executing action: user-upsert...
+   ...
+
+📋 KYC walkthrough summary
+   ✅ email-otp            demo+kyc@example.com
+   ✅ phone-otp            +14155552671
+   ✅ l1-upsert            tx:1:44
+   ⏭️  create-kyc-session  (scenario)
+   ⏭️  kyc-status-poll     (scenario)
+```
+
+##### Caveats
+
+- **No version bump.** The walkthrough is dev tooling — it does not introduce new `@terminal3/t3n-sdk` public-API surface, so `package.json` is not bumped.
+- **Spec alignment.** The walkthrough follows the as-built code, which differs from earlier T3-TS-026 versions on two points: `user-upsert` has no `op:` discriminator (dispatch is implicit on input shape), and the function for L2 session creation is `tee:user/contracts::create-kyc-provider-session` rather than `tee:kyc/contracts::create-session`. See [T3-TS-026 v0.6.0 changelog](../../docs/specs/T3-TS-026-kyc-frontend-integration.md) and [MAT-1374](https://linear.app/terminal3/issue/MAT-1374) for the deferred discriminator-vs-split decision.
+- **`STRICT_SCENARIO=true`** in the environment turns scenario assertion failures into a non-zero exit code (otherwise they're logged but the demo exits zero). `--scenario` always exits non-zero on a terminal-status mismatch.
+
 ## WASM Integration
 
 The SDK can work with both real T3n WASM components and mock components for testing.

package/dist/index.d.ts

@@ -655,6 +655,142 @@ declare class ContractResponseError extends T3nError {
  */
 declare function parseContractResponse<T = unknown>(raw: string, schema?: ContractResponseSchema<T>): T;
 
+/**
+ * KYC types for the `tee:user/contracts::kyc-status` short-poll
+ * function added in MAT-1202.
+ *
+ * The shape mirrors `tee_contracts/user/src/kyc_status.rs::KycStatusResponse`.
+ * Keep the two in sync — the bytes go straight from the contract
+ * through the JSON-RPC envelope into [[T3nClient.kycStatus]].
+ */
+
+/**
+ * Terminal status for a Level 2 KYC verification, plus `pending`.
+ *
+ * - `pending` — provider has not delivered a verdict yet, or the
+ *   webhook arrived but the post-action VC issuance hasn't completed.
+ * - `verified` — provider approved AND a VC has been issued. `vcIds`
+ *   carries the issued credential ids.
+ * - `rejected` — provider declined / required resubmission /
+ *   expired / the user abandoned the flow. `error` may carry a
+ *   provider-supplied reason.
+ * - `orphan` — a Veriff webhook arrived with a `vendorData` that
+ *   couldn't be matched to any user (T3-TS-024 §3.4). Should not
+ *   happen in the MetaMask flow but the contract surfaces it for
+ *   completeness.
+ */
+type KycStatusKind = "pending" | "verified" | "rejected" | "orphan";
+/**
+ * Snapshot returned by `tee:user/contracts::kyc-status`.
+ *
+ * Field names use camelCase on the SDK boundary even though the
+ * wire is snake_case — the wrapper rewrites keys at the client edge
+ * so callers don't see the JSON shape leaking through.
+ */
+interface KycStatus {
+    /** Terminal status if reached, otherwise `pending`. */
+    status: KycStatusKind;
+    /**
+     * Provider being polled. Echoed back so callers that didn't
+     * supply one see the contract's default (`"veriff"` in phase one).
+     */
+    provider: string;
+    /**
+     * Unix-millis of the latest contract-visible event:
+     * VC issuance time, attestation arrival time, session-row
+     * `started_at_ms`, or orphan-record arrival time. Best-effort —
+     * `undefined` when no source carries a usable timestamp.
+     */
+    updatedAt?: number;
+    /**
+     * VC ids appended for this provider, in append order. Empty for
+     * `pending` / `rejected` / `orphan`.
+     */
+    vcIds: string[];
+    /**
+     * Provider-supplied reason for `rejected`, when available.
+     */
+    error?: string;
+}
+/**
+ * Polling cadence for [[T3nClient.kycStatusPoll]]. Defaults match
+ * T3-TS-026 §8.4: poll fast for the first 30 seconds, then back
+ * off, and bail after 5 minutes.
+ */
+interface KycPollCadence {
+    /** Poll interval in ms while `elapsed < switchAtMs`. Default: 2000. */
+    fastMs: number;
+    /** Poll interval in ms once `elapsed >= switchAtMs`. Default: 5000. */
+    slowMs: number;
+    /** Elapsed-ms threshold to switch from fast to slow cadence. Default: 30_000. */
+    switchAtMs: number;
+    /**
+     * Maximum total time to spend polling before rejecting with
+     * [[KycStatusTimeoutError]]. Default: 300_000 (5 minutes).
+     */
+    timeoutMs: number;
+}
+/**
+ * Optional knobs for [[T3nClient.kycStatusPoll]]. Most callers won't
+ * touch any of these — the §8.4 defaults are baked in.
+ */
+interface KycPollOptions {
+    /**
+     * Cancellation signal. When aborted, the helper rejects with
+     * `signal.reason` (or a generic `AbortError` if the consumer
+     * didn't supply a reason). The currently-in-flight `kycStatus()`
+     * call also receives the signal so it can short-circuit.
+     */
+    signal?: AbortSignal;
+    /**
+     * Called with every snapshot the helper receives, including
+     * non-terminal `pending` ones. Useful for surfacing intermediate
+     * UI states (e.g. "still waiting on provider…"). Errors thrown
+     * from this callback are caught and ignored — they must not
+     * sink the poll loop.
+     */
+    onUpdate?: (status: KycStatus) => void;
+    /**
+     * Override one or more cadence fields. Anything not specified
+     * uses the §8.4 defaults from [[DEFAULT_KYC_POLL_CADENCE]].
+     */
+    cadence?: Partial<KycPollCadence>;
+    /**
+     * Provider id to poll. Defaults to the contract default
+     * (`"veriff"` in phase one). Mirrored on the wire as
+     * `input.provider_id`.
+     */
+    providerId?: string;
+}
+/**
+ * Default cadence used by [[T3nClient.kycStatusPoll]] when the caller
+ * doesn't override `cadence.*`. Matches T3-TS-026 §8.4 verbatim.
+ */
+declare const DEFAULT_KYC_POLL_CADENCE: KycPollCadence;
+/**
+ * Subset of [[KycStatusKind]] that ends a poll. `pending` is the
+ * only non-terminal value.
+ */
+declare const TERMINAL_KYC_STATUSES: ReadonlySet<KycStatusKind>;
+/**
+ * Thrown by [[T3nClient.kycStatusPoll]] when the cadence's
+ * `timeoutMs` elapses without a terminal status arriving. The
+ * `lastStatus` field is the most recent (necessarily `pending`)
+ * snapshot the helper saw, useful for surfacing "we tried for N
+ * minutes but Veriff is still working" UX.
+ */
+declare class KycStatusTimeoutError extends T3nError {
+    /** The §8.4 timeout the helper exhausted. */
+    readonly timeoutMs: number;
+    /** The last `pending` snapshot before timeout, if any. */
+    readonly lastStatus?: KycStatus | undefined;
+    constructor(
+    /** The §8.4 timeout the helper exhausted. */
+    timeoutMs: number, 
+    /** The last `pending` snapshot before timeout, if any. */
+    lastStatus?: KycStatus | undefined);
+}
+
 /**
  * T3n Client - Main SDK class
  *
@@ -668,6 +804,14 @@ declare function parseContractResponse<T = unknown>(raw: string, schema?: Contra
 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`
@@ -763,6 +907,32 @@ 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.
@@ -837,6 +1007,57 @@ declare class T3nClient {
      *   the response cannot be decoded.
      */
     removeUserWithWalletAbandonment(): Promise<unknown>;
+    /**
+     * One-shot poll of `tee:user/contracts::kyc-status`.
+     *
+     * Returns the current snapshot of the authenticated user's Level 2
+     * KYC state — see [[KycStatus]] for the four possible terminal /
+     * non-terminal values. The caller usually wants
+     * [[kycStatusPoll]] (which loops with §8.4 cadence until a
+     * terminal status arrives), but the bare snapshot is useful for
+     * pages that need to render the user's standing without waiting
+     * (e.g. account-status views, "did the user finish KYC last time
+     * they were here?" gates).
+     *
+     * Phase one default — `providerId` defaults to `"veriff"` (the
+     * contract applies the same default when the field is absent),
+     * so the most common call site is `await t3n.kycStatus()`.
+     *
+     * @param providerId optional provider id, mirrored on the wire as
+     *   `input.provider_id`. Omit for phase-one MetaMask flows.
+     * @throws if unauthenticated, if the node rejects the action
+     *   (e.g. `precondition_failed:` when no `create-kyc-provider-session`
+     *   row exists yet), or if the response shape is unexpected.
+     */
+    kycStatus(providerId?: string): Promise<KycStatus>;
+    /**
+     * Poll `kyc-status` until a terminal status arrives or the
+     * configured timeout elapses.
+     *
+     * Cadence defaults to T3-TS-026 §8.4: 2-second interval for the
+     * first 30 seconds, then 5 seconds, with a 5-minute hard cap.
+     * Override via `opts.cadence` if you need different numbers
+     * (e.g. tests that don't want to wait the full 30 seconds before
+     * the slow window kicks in). [[KycStatusTimeoutError]] is thrown
+     * if the timeout elapses without reaching a terminal state.
+     *
+     * `opts.signal` cancels the loop synchronously — the helper
+     * stops sleeping and rejects with the abort reason; an
+     * already-in-flight `kycStatus()` request is allowed to settle
+     * but its result is discarded.
+     *
+     * `opts.onUpdate` fires once per snapshot, including
+     * intermediate `pending` ones. Errors thrown from the callback
+     * are swallowed so a misbehaving UI handler can't strand the
+     * poll loop.
+     *
+     * @throws [[KycStatusTimeoutError]] when the cadence's
+     *   `timeoutMs` elapses without a terminal status.
+     * @throws the abort reason when `opts.signal` is aborted.
+     * @throws the underlying RPC error when the contract or
+     *   transport raises (e.g. session expiry mid-poll).
+     */
+    kycStatusPoll(opts?: KycPollOptions): Promise<KycStatus>;
     /**
      * The server-minted session ID once handshake has completed, or
      * `null` beforehand (pentest M-1 / MAT-983).
@@ -1202,5 +1423,5 @@ declare function clearKeyCache(): void;
  */
 declare function loadConfig(baseUrl?: string): SdkConfig;
 
-export { AuthMethod, AuthenticationError, ContractResponseError, HandshakeError, HttpTransport, LogLevel, MockTransport, NODE_URLS, RpcError, SessionStateError, SessionStatus, T3nClient, T3nError, 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, Logger, OidcAuthInput, OidcCredentials, PeerQuoteResult, QuoteVerifyResult, SdkConfig, SessionCrypto, SessionId, T3nClientConfig, Transport, WasmComponent, WasmNextResult };
+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 };