@terminal3/t3n-sdk 2.1.0 → 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/index.d.ts

@@ -20,6 +20,8 @@ export type { KycStatus, KycStatusKind, KycPollOptions, KycPollCadence, } from "
 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@terminal3/t3n-sdk",
-  "version": "2.1.0",
+  "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": {