@terminal3/t3n-sdk 2.1.0 → 2.3.0

package/dist/index.d.ts

@@ -1507,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
  *
@@ -1728,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, UserUpsertError, 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, OtpChannel, OtpMergeSuggestion, OtpRequestInput, OtpRequestResult, OtpVerifyInput, OtpVerifyResult, PeerQuoteResult, QuoteVerifyResult, SdkConfig, SessionCrypto, SessionId, SubmitUserInputArgs, SubmitUserInputResult, T3nClientConfig, Transport, UserInputProfile, UserUpsertErrorKind, 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 };