@terminal3/t3n-sdk 3.3.0 → 3.4.0

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

@@ -1,388 +0,0 @@
-/**
- * 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_FUNCTIONS_PER_CREDENTIAL = 16;
-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;
-/**
- * Canonical sorted list of the payroll v2 function surface. One source
- * of truth for callers building a full-cycle credential — pass this
- * (or a sorted subset) as `functions` to {@link buildDelegationCredential}.
- */
-export declare const PAYROLL_FUNCTIONS_V1: readonly ["compute-payroll", "execute-disbursement", "finalize-audit", "submit-escalations", "validate-credentials"];
-/** 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;
-    /**
-     * Functions this credential authorises. Sorted ascending, deduped,
-     * each entry non-empty lowercase ASCII, 1..=16 entries.
-     */
-    functions: 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>;
-    /**
-     * Per-employee disbursement flag threshold, in cents. Mirrors
-     * `PayrollRunRequest::individual_disbursement_threshold_cents` on the Rust
-     * side. When absent the Rust contract applies its own default (SGD 15,000;
-     * `DEFAULT_INDIVIDUAL_THRESHOLD_CENTS`). When present, the value is
-     * included in the wire shape and participates in the request hash.
-     */
-    individual_disbursement_threshold_cents?: bigint;
-}
-/** Default for `individual_disbursement_threshold_cents` — SGD 15,000. */
-export declare const DEFAULT_INDIVIDUAL_THRESHOLD_CENTS = 1500000n;
-/** Delegated invocation: the agent acts on behalf of a user. */
-export interface PayrollInvocationDelegated {
-    envelope: DelegationEnvelope;
-    request: PayrollRunRequest;
-}
-/**
- * Direct invocation: the agent acts on its own behalf. No delegation
- * envelope is included. The principal DID is resolved by the service layer
- * from `DynamicContext.authenticated_did`; authorisation falls through to
- * `OrgContractGrants[org || "tee:payroll"]` for the agent's own DID.
- *
- * Wire shape is `{ request }` — no `envelope` field and no
- * `authenticated_did` field. The contract's entry-point handler injects
- * `authenticated_did` from `GenericInput.context` before calling `verify`.
- */
-export interface PayrollInvocationDirect {
-    request: PayrollRunRequest;
-}
-/**
- * Union of the two invocation variants. The serde-untagged enum on the
- * contract side disambiguates by presence of `envelope` — delegated calls
- * carry `{ envelope, request }`, direct calls carry `{ request }` only.
- */
-export type PayrollInvocation = PayrollInvocationDelegated | PayrollInvocationDirect;
-/** 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;
-    /**
-     * Functions this credential authorises. Must be non-empty, sorted
-     * ascending, deduped — the same invariants enforced by
-     * {@link validateCredentialBody}.
-     */
-    functions: 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 DelegationCustodialClient}.
- */
-export interface DelegationCustodialClientOpts {
-    /**
-     * Explicit semver string for the delegation contract (e.g. `"1.0.0"`).
-     * When omitted the client resolves `"latest"` via
-     * `GET /api/contracts/current?name=tee:delegation/contracts` (one
-     * request per client instance, cached in `getScriptVersion`).
-     */
-    scriptVersion?: string;
-}
-/**
- * Result returned by {@link DelegationCustodialClient.signCustodial}.
- */
-export interface SignCustodialResult {
-    /** RFC 8785 JCS bytes of the credential, exactly as signed by the node. */
-    credentialJcs: Uint8Array;
-    /** 65-byte EIP-191 signature over `credentialJcs` produced by the TEE. */
-    userSig: Uint8Array;
-}
-/**
- * Wraps the `tee:delegation/contracts::sign` function for OIDC users
- * (or any user whose private key is held by the TEE rather than the
- * browser).
- *
- * ETH-EOA users who hold their own key should call
- * {@link signCredential} directly — no network round-trip required.
- *
- * The client must be constructed with an authenticated {@link T3nClient}
- * instance and the node's base URL; `signCustodial` sends the credential
- * body to the TEE and returns the signed bytes.
- *
- * Reference: `node/tests/harness/src/payroll_seed.rs` (the
- * `tee:delegation.sign` invocation at line 550).
- */
-export declare class DelegationCustodialClient {
-    private readonly t3n;
-    private readonly baseUrl;
-    private readonly opts;
-    constructor(t3n: import("./t3n-client").T3nClient, baseUrl: string, opts?: DelegationCustodialClientOpts);
-    /**
-     * Request the TEE to sign a delegation credential on behalf of the
-     * authenticated user.
-     *
-     * The `body` is sent as-is as the `input.body` field of the
-     * `tee:delegation/contracts::sign` action.  Use
-     * {@link buildDelegationCredential} + the wire-shape projection to
-     * produce the correct representation — binary fields (`agent_pubkey`,
-     * `vc_id`) must be base64url-no-pad strings, and `not_before_secs` /
-     * `not_after_secs` must be decimal strings.
-     *
-     * Returns `{ credentialJcs, userSig }` — both as `Uint8Array` — ready
-     * to be passed into {@link buildPayrollInvocation}.
-     */
-    signCustodial(body: Record<string, unknown>): Promise<SignCustodialResult>;
-}
-/** Options for {@link revokeDelegation}. */
-export interface RevokeDelegationOpts {
-    /** Credential body to revoke. Already-encoded base64url-no-pad JCS bytes. */
-    credentialJcsB64u: string;
-    /**
-     * Omit (or pass `undefined`) to revoke the whole credential. Pass an
-     * array of function names to revoke a subset; the array must obey the
-     * same sort + dedupe invariants the credential's `functions` field
-     * enforces, and each entry must already appear in the credential's
-     * `functions` list (a revocation can only narrow the set, never grow
-     * it).
-     */
-    revokedFunctions?: string[];
-    /** Authenticated {@link T3nClient} for the credential's `user_did`. */
-    client: import("./t3n-client").T3nClient;
-    /**
-     * Override the resolved delegation contract version. Defaults to
-     * whatever `GET /api/contracts/current?name=tee:delegation/contracts`
-     * returns at call time.
-     */
-    scriptVersion?: string;
-    /** Override the node base URL used for `"latest"` resolution. */
-    baseUrl?: string;
-}
-/** Result of a successful {@link revokeDelegation} call. */
-export interface RevokeDelegationResult {
-    /** Credential id (base64url-no-pad, no padding). */
-    vcId: string;
-    /**
-     * Mirrors the persisted revocation state after merging: `null` means
-     * whole-credential, a sorted array means per-function. The contract
-     * may return a larger set than `opts.revokedFunctions` when an
-     * earlier per-function revocation existed for the same credential.
-     */
-    revokedFunctions: string[] | null;
-}
-/**
- * Wraps the `tee:delegation/contracts::revoke` entrypoint. Only the
- * credential's `user_did` may call this — the contract reads the
- * authenticated DID from session context and rejects any other caller
- * with `NotCredentialHolder`.
- *
- * Merge semantics are handled server-side: whole-credential revocations
- * are sticky, and per-function revocations accumulate as a sorted +
- * deduped union across calls. The returned `revokedFunctions` reflects
- * the persisted state after merging, not just this call's input.
- */
-export declare function revokeDelegation(opts: RevokeDelegationOpts): Promise<RevokeDelegationResult>;
-/** 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 delegated {@link PayrollInvocationDelegated} (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)`.
- *
- * When `request.individual_disbursement_threshold_cents` is undefined this
- * function fills in {@link DEFAULT_INDIVIDUAL_THRESHOLD_CENTS} before
- * hashing so the SDK's hash matches the Rust contract's hash (the contract
- * applies the same default via `#[serde(default)]`).
- */
-export declare function buildPayrollInvocation(opts: BuildPayrollInvocationOpts): PayrollInvocationDelegated;
-/** Options for {@link buildPayrollDirectInvocation}. */
-export interface BuildPayrollDirectInvocationOpts {
-    request: PayrollRunRequest;
-}
-/**
- * Assemble a direct {@link PayrollInvocationDirect} — no delegation
- * envelope. The caller supplies only the request body; the contract
- * entry-point resolves the principal DID from
- * `DynamicContext.authenticated_did` at runtime.
- *
- * Callers in direct mode must hold a grant in
- * `OrgContractGrants[org || "tee:payroll"]` under their own DID.
- *
- * When `request.individual_disbursement_threshold_cents` is undefined this
- * function fills in {@link DEFAULT_INDIVIDUAL_THRESHOLD_CENTS} so the wire
- * shape matches the Rust contract's `#[serde(default)]` canonicalisation.
- */
-export declare function buildPayrollDirectInvocation(opts: BuildPayrollDirectInvocationOpts): PayrollInvocationDirect;
-export {};

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

@@ -1,30 +0,0 @@
-/**
- * Session Encryption Service
- *
- * Handles encryption and decryption of data using the established WASM session.
- * Keeps cryptographic operations isolated and simple.
- */
-import { SessionCrypto } from "../wasm";
-import { Logger } from "../utils/logger";
-/**
- * Encrypts and decrypts data using an established session
- */
-export declare class SessionEncryption {
-    private sessionCrypto;
-    private logger;
-    constructor(sessionCrypto: SessionCrypto, logger: Logger);
-    /**
-     * Encrypt data using the session
-     * @param sessionState - The session state bytes (from handshake)
-     * @param data - The plaintext data to encrypt
-     * @returns Base64-encoded encrypted data
-     */
-    encrypt(sessionState: Uint8Array, data: Uint8Array): Promise<string>;
-    /**
-     * Decrypt data using the session
-     * @param sessionState - The session state bytes (from handshake)
-     * @param encryptedData - Base64-encoded encrypted data
-     * @returns Decrypted plaintext bytes
-     */
-    decrypt(sessionState: Uint8Array, encryptedData: string): Promise<Uint8Array>;
-}

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

@@ -1,73 +0,0 @@
-/**
- * Guest-to-Host Request Handlers
- *
- * These handle requests from WASM that need the host environment to perform side effects.
- * Examples: signing challenges, providing public keys, generating random bytes.
- */
-import { GuestToHostHandler, GuestToHostHandlers } from "../types";
-import { Logger } from "../utils/logger";
-/**
- * Account — MetaMask handler accepts either a plain address string or an
- * object with an `address` field (for compatibility with various wallet
- * libraries).
- */
-type EthAccount = string | {
-    address: string;
-};
-/**
- * Create an EthSign handler using MetaMask (window.ethereum)
- * @param account - MetaMask account (string address or object with address property)
- * @param logger - Optional logger instance. Defaults to a logger using the global log level (LogLevel.ERROR).
- *   Pass a custom logger to override logging behavior for this handler.
- * @param privateKey - Optional private key for signing (if provided, MetaMask is not used)
- */
-export declare function metamask_sign(account: EthAccount, logger?: Logger, privateKey?: string | undefined): GuestToHostHandler;
-/**
- * Get the current MetaMask address
- * @returns Ethereum address (lowercase, 0x prefixed)
- */
-export declare function metamask_get_address(): Promise<string>;
-/**
- * Get the address for a given private key
- * @param privateKey - Ethereum private key (0x prefixed hex string)
- * @returns Ethereum address (lowercase, 0x prefixed)
- */
-export declare function eth_get_address(privateKey: string): string;
-/**
- * Create an MlKemPublicKey handler that lazily fetches the root public key
- * from `${baseUrl}/status` on first invocation and caches the encoded
- * response for subsequent calls.
- *
- * @param baseUrl - **Required**. The node URL whose `/status` endpoint should
- *                  serve the ML-KEM public key. Must be the same URL the
- *                  T3nClient is constructed with — otherwise the handshake
- *                  encrypts to one node and sends ciphertext to another.
- *
- *                  Was optional in 0.3.x, where omitting it caused the lazy
- *                  fetch to silently fall back to `NODE_URLS[currentEnv]` and
- *                  hit the wrong node. Three downstream consumers (demo.ts,
- *                  t3-apps dev wallet hooks, t3n-mcp session manager) all
- *                  hit this trap before we tightened the type.
- */
-export declare function createMlKemPublicKeyHandler(baseUrl: string): GuestToHostHandler;
-/**
- * Create Random handler backed by crypto.getRandomValues
- * Note: The Rust Vec<u8> type serializes as an array of bytes, not a base64 string
- */
-export declare function createRandomHandler(): GuestToHostHandler;
-/**
- * Create the default handler set required by the T3n handshake.
- *
- * @param baseUrl - **Required**. Forwarded to `createMlKemPublicKeyHandler`
- *                  so the lazy /status fetch hits the right node.
- */
-export declare function createDefaultHandlers(baseUrl: string): GuestToHostHandlers;
-/**
- * Merge consumer-provided handlers with defaults (user handlers take precedence).
- *
- * @param handlers - Optional consumer overrides.
- * @param baseUrl  - **Required**. Forwarded to the default handler set so the
- *                   ML-KEM key fetch hits the right node.
- */
-export declare function mergeWithDefaultHandlers(handlers: GuestToHostHandlers | undefined, baseUrl: string): GuestToHostHandlers;
-export {};

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

@@ -1,13 +0,0 @@
-/**
- * Client exports for T3n SDK
- */
-export * from "./config";
-export * from "./transport";
-export * from "./t3n-client";
-export * from "./handlers";
-export * from "./encryption";
-export * from "./actions";
-export * from "./request-parser";
-export * from "./contract-response";
-export * from "./delegation";
-export * from "./org-data";