@aimarket/agent 0.1.0

package/README.md

@@ -0,0 +1,59 @@
+# @aimarket/agent
+
+AI Market Protocol v2 consumer SDK for **TypeScript** — Electron, Node.js servers, and web apps.
+
+Discover, pay for, and invoke AI capabilities from the decentralized marketplace, with production cryptography:
+
+- **Ed25519** (`ed25519:<base64>`) for canonical hub / invoke signatures
+- **EIP-712** (`keccak256` + secp256k1, `eip712:0x<r><s><v>`) for on-chain channel debits
+
+Part of the [AIMarket SDKs](https://github.com/alexar76/aimarket-sdks) (Dart · TypeScript · Rust) — all three ship the same version and the same model shapes, enforced by an ecosystem parity guard in CI.
+
+## Install
+
+```bash
+# Today — build from source (the SDK lives in typescript/):
+git clone https://github.com/alexar76/aimarket-sdks
+cd aimarket-sdks/typescript && npm install && npm run build
+# …then reference it via `npm link` or a `file:` dependency.
+
+# Once published: npm install @aimarket/agent   (npm registry — not live yet)
+```
+
+## Quick start
+
+```ts
+import { AimarketAgent } from '@aimarket/agent';
+
+const agent = new AimarketAgent({
+  hubUrl: 'https://hub.aicom.io',
+  walletKey: loadYourWalletKey(),
+});
+
+// Discover capabilities for an intent — returns a ranked PlanStep[].
+const plan = await agent.discover({
+  intent: 'ATS scoring rules for fintech roles',
+  budget: 1.0,
+  limit: 5,
+});
+
+// Open a $5 channel (good for ~50 calls), then invoke the best match.
+const channel = await agent.openChannel(5.0);
+const result = await agent.invoke({
+  capabilityId: plan[0].capability.capability_id,
+  input: { target_role: 'Senior PM', industry: 'fintech' },
+  channelId: channel.channel_id,
+});
+
+console.log('Output:', result.output, '· cost $', result.price_usd, '· TEE', result.tee_verified);
+await agent.closeChannel(channel.channel_id);
+```
+
+## Links
+
+- Ecosystem & live demos: <https://alexar76.github.io/aicom/>
+- Protocol spec & schemas: <https://github.com/alexar76/aimarket-protocol>
+
+## License
+
+MIT

package/dist/agent.d.ts

@@ -0,0 +1,90 @@
+/**
+ * AI Market Protocol v2 Consumer Agent (TypeScript).
+ *
+ * Implements the 5-phase consumer cycle:
+ *   1. Discovery  — fetch well-known + search
+ *   2. Channel    — open pre-funded payment channel
+ *   3. Invoke     — call capability with payment header
+ *   4. Settle     — close channel, get refund
+ *   5. Verify     — TEE attestation check
+ *
+ * Target: Electron desktop apps, Node.js servers, web apps.
+ */
+import { type BillOfMaterials, type Channel, type InvokeResult, type PlanStep, type Settlement, type TeeAttestation, type TeeReceipt } from './models';
+/** Configuration for [AimarketAgent] behavior. */
+export interface AimarketAgentConfig {
+    hubUrl: string;
+    walletKey: string;
+    affiliate: string;
+    timeoutMs: number;
+    maxRetries: number;
+    trustedCodeHashes?: Record<string, string>;
+    verifyTee: boolean;
+}
+export interface AimarketAgentOptions {
+    hubUrl: string;
+    walletKey: string;
+    affiliate?: string;
+    trustedCodeHashes?: Record<string, string>;
+    timeoutMs?: number;
+    maxRetries?: number;
+    verifyTee?: boolean;
+    /** Injectable fetch for tests. */
+    fetch?: typeof fetch;
+}
+export declare class AimarketAgent {
+    private readonly config;
+    private readonly signer;
+    private readonly teeVerifier;
+    private readonly fetchFn;
+    private readonly channelCache;
+    private wellKnownCache;
+    constructor(opts: AimarketAgentOptions);
+    private retryWithBackoff;
+    private fetchWithTimeout;
+    wellKnown(): Promise<string>;
+    discover(opts: {
+        intent: string;
+        budget?: number;
+        limit?: number;
+        category?: string;
+    }): Promise<PlanStep[]>;
+    discoverProduct(productId: string): Promise<PlanStep[]>;
+    openChannel(depositUsd: number, token?: string, chain?: string): Promise<Channel>;
+    getChannelBalance(channelId: string): Promise<number>;
+    invoke(opts: {
+        capabilityId: string;
+        input: Record<string, unknown>;
+        channelId: string;
+        productId?: string;
+        sourceHub?: string;
+        verifyTee?: boolean;
+        /**
+         * TEE attestation for the target capability, obtained out-of-band (e.g.
+         * from the hub manifest or a prior invocation's `tee_attestation`). When
+         * supplied and TEE verification is enabled, it is verified BEFORE any input
+         * is transmitted; an invalid attestation aborts the call so sensitive input
+         * never reaches an unverified enclave.
+         */
+        attestation?: TeeAttestation;
+    }): Promise<InvokeResult>;
+    private invokeOnce;
+    invokeBatch(opts: {
+        capabilityIds: string[];
+        inputs: Array<Record<string, unknown>>;
+        channelId: string;
+        sourceHub?: string;
+    }): Promise<InvokeResult[]>;
+    closeChannel(channelId: string): Promise<Settlement>;
+    verifyTeeAttestation(attestation: TeeAttestation, capabilityId: string): boolean;
+    verifyTeeReceipt(receipt: TeeReceipt, sentInput: string, receivedOutput: string): boolean;
+    trustCodeHash(capabilityId: string, codeHash: string): void;
+    fetchTrustedHashes(): Promise<number>;
+    runOnce(opts: {
+        intent: string;
+        input: Record<string, unknown>;
+        depositUsd?: number;
+        category?: string;
+    }): Promise<BillOfMaterials>;
+    dispose(): void;
+}

package/dist/agent.js

@@ -0,0 +1,302 @@
+/**
+ * AI Market Protocol v2 Consumer Agent (TypeScript).
+ *
+ * Implements the 5-phase consumer cycle:
+ *   1. Discovery  — fetch well-known + search
+ *   2. Channel    — open pre-funded payment channel
+ *   3. Invoke     — call capability with payment header
+ *   4. Settle     — close channel, get refund
+ *   5. Verify     — TEE attestation check
+ *
+ * Target: Electron desktop apps, Node.js servers, web apps.
+ */
+import { AimarketException, AimarketNetworkException, AimarketPaymentException, AimarketSafetyException, } from './errors';
+import { channelBalanceRatio, channelIsExpired, } from './models';
+import { MarketSigner } from './signer';
+import { TeeVerifier } from './tee';
+class CachedChannel {
+    channel;
+    cachedAt;
+    constructor(channel, cachedAt) {
+        this.channel = channel;
+        this.cachedAt = cachedAt;
+    }
+    get hasSufficientBalance() {
+        return channelBalanceRatio(this.channel) > 0.5;
+    }
+    get isNotExpired() {
+        return !channelIsExpired(this.channel);
+    }
+    get isReusable() {
+        return this.isNotExpired && this.hasSufficientBalance;
+    }
+}
+export class AimarketAgent {
+    config;
+    signer;
+    teeVerifier;
+    fetchFn;
+    channelCache = new Map();
+    wellKnownCache = null;
+    constructor(opts) {
+        this.config = {
+            hubUrl: opts.hubUrl.replace(/\/$/, ''),
+            walletKey: opts.walletKey,
+            affiliate: opts.affiliate ?? 'aimarket-sdk-ts',
+            timeoutMs: opts.timeoutMs ?? 30_000,
+            maxRetries: opts.maxRetries ?? 3,
+            trustedCodeHashes: opts.trustedCodeHashes,
+            verifyTee: opts.verifyTee ?? true,
+        };
+        this.signer = new MarketSigner(this.config.walletKey);
+        this.teeVerifier = new TeeVerifier({
+            signer: this.signer,
+            trustedCodeHashes: this.config.trustedCodeHashes,
+        });
+        this.fetchFn = opts.fetch ?? fetch;
+    }
+    async retryWithBackoff(operation) {
+        let lastError = new AimarketNetworkException(`Request failed after ${this.config.maxRetries} retries`);
+        for (let attempt = 0; attempt <= this.config.maxRetries; attempt++) {
+            try {
+                return await operation();
+            }
+            catch (e) {
+                if (e instanceof AimarketNetworkException) {
+                    lastError = e;
+                }
+                else if (e instanceof Error && e.name === 'AbortError') {
+                    lastError = new AimarketNetworkException(`Request timed out: ${e.message}`);
+                }
+                else if (e instanceof TypeError ||
+                    (e instanceof Error && e.message.includes('fetch'))) {
+                    lastError = new AimarketNetworkException(`Network error: ${e.message}`);
+                }
+                else {
+                    throw e;
+                }
+            }
+            if (attempt < this.config.maxRetries) {
+                await new Promise((resolve) => setTimeout(resolve, 1000 * 2 ** attempt));
+            }
+        }
+        throw lastError;
+    }
+    async fetchWithTimeout(input, init) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.config.timeoutMs);
+        try {
+            return await this.fetchFn(input, { ...init, signal: controller.signal });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    // ── Phase 1: Discovery ────────────────────────────────────────
+    async wellKnown() {
+        if (this.wellKnownCache)
+            return this.wellKnownCache;
+        const resp = await this.fetchWithTimeout(`${this.config.hubUrl}/.well-known/ai-market.json`);
+        if (!resp.ok) {
+            throw new AimarketException(`Failed to fetch well-known: ${resp.status}`);
+        }
+        this.wellKnownCache = await resp.text();
+        return this.wellKnownCache;
+    }
+    async discover(opts) {
+        const params = new URLSearchParams({
+            intent: opts.intent,
+            limit: String(opts.limit ?? 5),
+        });
+        if (opts.budget !== undefined)
+            params.set('budget_usd', String(opts.budget));
+        if (opts.category)
+            params.set('category', opts.category);
+        const resp = await this.fetchWithTimeout(`${this.config.hubUrl}/ai-market/v2/search?${params}`, { headers: { 'X-AIMarket-Affiliate': this.config.affiliate } });
+        if (!resp.ok) {
+            throw new AimarketException(`Discovery failed: ${resp.status} ${await resp.text()}`);
+        }
+        const data = await resp.json();
+        return data.results;
+    }
+    async discoverProduct(productId) {
+        return this.discover({ intent: `product:${productId}` });
+    }
+    // ── Phase 2: Channel Open ─────────────────────────────────────
+    async openChannel(depositUsd, token = 'USDT', chain = 'base') {
+        const cacheKey = `${depositUsd}:${token}:${chain}`;
+        const cached = this.channelCache.get(cacheKey);
+        if (cached?.isReusable) {
+            return cached.channel;
+        }
+        if (cached) {
+            this.channelCache.delete(cacheKey);
+        }
+        const resp = await this.fetchWithTimeout(`${this.config.hubUrl}/ai-market/v2/channel/open`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'X-AIMarket-Affiliate': this.config.affiliate,
+            },
+            body: JSON.stringify({ deposit_usd: depositUsd, token, chain }),
+        });
+        if (resp.status === 404) {
+            throw new AimarketException('Payment channels not available on this hub');
+        }
+        if (resp.status !== 200 && resp.status !== 201) {
+            throw new AimarketException(`Channel open failed: ${resp.status} ${await resp.text()}`);
+        }
+        // The hub wraps the channel in a `{ channel: {...} }` envelope (matching the
+        // Python agent + live hub); unwrap it, tolerating a bare object for forward-compat.
+        const raw = await resp.json();
+        const channel = raw && raw.channel ? raw.channel : raw;
+        this.channelCache.set(cacheKey, new CachedChannel(channel, new Date()));
+        return channel;
+    }
+    async getChannelBalance(channelId) {
+        const resp = await this.fetchWithTimeout(`${this.config.hubUrl}/ai-market/v2/channel/${channelId}`, { headers: { 'X-AIMarket-Affiliate': this.config.affiliate } });
+        if (!resp.ok) {
+            throw new AimarketException(`Failed to get channel balance: ${resp.status}`);
+        }
+        const data = (await resp.json());
+        return data.balance_usd ?? 0;
+    }
+    // ── Phase 3: Invoke ───────────────────────────────────────────
+    async invoke(opts) {
+        return this.retryWithBackoff(() => this.invokeOnce(opts));
+    }
+    async invokeOnce(opts) {
+        const verifyTee = opts.verifyTee ?? true;
+        if (verifyTee && this.config.verifyTee && opts.attestation) {
+            // Phase 5 pre-check: verify the enclave attestation BEFORE sending input,
+            // so user data never reaches a capability whose code hash / signature
+            // can't be trusted. Fail closed — a bad attestation aborts the call.
+            const verdict = this.teeVerifier.verifyAttestationDetailed(opts.attestation, opts.capabilityId);
+            if (!verdict.isValid) {
+                throw new AimarketSafetyException(`TEE attestation verification failed for ${opts.capabilityId}: ` +
+                    verdict.failures.join('; '));
+            }
+        }
+        const headers = this.signer.signedHeaders({
+            channelId: opts.channelId,
+            capabilityId: opts.capabilityId,
+            affiliate: this.config.affiliate,
+        });
+        headers['Content-Type'] = 'application/json';
+        const body = {
+            capability_id: opts.capabilityId,
+            input: opts.input,
+        };
+        if (opts.productId)
+            body.product_id = opts.productId;
+        if (opts.sourceHub)
+            body.source_hub = opts.sourceHub;
+        const startMs = performance.now();
+        const resp = await this.fetchWithTimeout(`${this.config.hubUrl}/ai-market/v2/invoke`, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify(body),
+        });
+        const latencyMs = performance.now() - startMs;
+        if (resp.status === 403) {
+            const data = (await resp.json());
+            throw new AimarketSafetyException(data.reason ?? 'Blocked by safety gate');
+        }
+        if (resp.status === 402) {
+            throw new AimarketPaymentException('Channel depleted or expired — open a new channel');
+        }
+        if (!resp.ok) {
+            return {
+                success: false,
+                price_usd: 0,
+                latency_ms: latencyMs,
+                safety_blocked: false,
+                tee_verified: false,
+                error: `HTTP ${resp.status}: ${await resp.text()}`,
+            };
+        }
+        return resp.json();
+    }
+    async invokeBatch(opts) {
+        if (opts.capabilityIds.length !== opts.inputs.length) {
+            throw new Error('capabilityIds and inputs must have the same length');
+        }
+        return Promise.all(opts.capabilityIds.map((capabilityId, i) => this.invoke({
+            capabilityId,
+            input: opts.inputs[i],
+            channelId: opts.channelId,
+            sourceHub: opts.sourceHub,
+        })));
+    }
+    // ── Phase 4: Settle ───────────────────────────────────────────
+    async closeChannel(channelId) {
+        for (const [key, cached] of this.channelCache) {
+            if (cached.channel.channel_id === channelId) {
+                this.channelCache.delete(key);
+                break;
+            }
+        }
+        const resp = await this.fetchWithTimeout(`${this.config.hubUrl}/ai-market/v2/channel/close`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'X-AIMarket-Affiliate': this.config.affiliate,
+            },
+            body: JSON.stringify({ channel_id: channelId }),
+        });
+        if (resp.status === 404) {
+            throw new AimarketException(`Channel not found: ${channelId}`);
+        }
+        if (!resp.ok) {
+            throw new AimarketException(`Settlement failed: ${resp.status} ${await resp.text()}`);
+        }
+        return resp.json();
+    }
+    // ── Phase 5: Verify ───────────────────────────────────────────
+    verifyTeeAttestation(attestation, capabilityId) {
+        return this.teeVerifier.verifyAttestation(attestation, capabilityId);
+    }
+    verifyTeeReceipt(receipt, sentInput, receivedOutput) {
+        return this.teeVerifier.verifyReceipt(receipt, sentInput, receivedOutput);
+    }
+    trustCodeHash(capabilityId, codeHash) {
+        this.teeVerifier.trustCodeHash(capabilityId, codeHash);
+    }
+    async fetchTrustedHashes() {
+        return this.teeVerifier.fetchTrustedHashes(this.config.hubUrl, this.fetchFn);
+    }
+    // ── Full cycle ────────────────────────────────────────────────
+    async runOnce(opts) {
+        const depositUsd = opts.depositUsd ?? 5.0;
+        const plan = await this.discover({
+            intent: opts.intent,
+            budget: depositUsd,
+            category: opts.category,
+        });
+        if (plan.length === 0) {
+            throw new AimarketException(`No capabilities found for: ${opts.intent}`);
+        }
+        const channel = await this.openChannel(depositUsd);
+        const step = plan[0];
+        const result = await this.invoke({
+            capabilityId: step.capability.capability_id,
+            input: opts.input,
+            channelId: channel.channel_id,
+            productId: step.capability.product_id,
+            sourceHub: step.capability.source_hub,
+        });
+        const settlement = await this.closeChannel(channel.channel_id);
+        return {
+            task: opts.intent,
+            plan,
+            results: [result],
+            settlement,
+            total_spent_usd: result.price_usd,
+            protocol_version: 'v2',
+        };
+    }
+    dispose() {
+        this.channelCache.clear();
+        this.wellKnownCache = null;
+    }
+}

package/dist/eip712.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Production EIP-712 encoding for AIMarketEscrow debit authorizations.
+ *
+ * Matches `contracts/evm/src/AIMarketEscrow.sol` and OpenZeppelin
+ * `MessageHashUtils.toTypedDataHash`.
+ */
+import { type Address, type Hex } from 'viem';
+export declare const EIP712_DOMAIN_TYPE = "EIP712Domain(string name,string version,uint256 chainId,address verifyingContract)";
+export declare const DEBIT_AUTHORIZATION_TYPES: {
+    readonly DebitAuthorization: readonly [{
+        readonly name: "channelId";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "hub";
+        readonly type: "address";
+    }, {
+        readonly name: "token";
+        readonly type: "address";
+    }, {
+        readonly name: "amount";
+        readonly type: "uint256";
+    }, {
+        readonly name: "receiptId";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "nonce";
+        readonly type: "uint256";
+    }, {
+        readonly name: "deadline";
+        readonly type: "uint256";
+    }];
+};
+export interface DebitDigestParams {
+    channelId: Hex;
+    hub: Address;
+    token: Address;
+    amount: bigint;
+    receiptId: Hex;
+    nonce: bigint;
+    deadline: bigint;
+    chainId: number;
+    verifyingContract: Address;
+}
+/** Compute the EIP-712 digest a depositor signs for `debitChannel`. */
+export declare function computeDebitDigest(params: DebitDigestParams): Hex;

package/dist/eip712.js

@@ -0,0 +1,41 @@
+/**
+ * Production EIP-712 encoding for AIMarketEscrow debit authorizations.
+ *
+ * Matches `contracts/evm/src/AIMarketEscrow.sol` and OpenZeppelin
+ * `MessageHashUtils.toTypedDataHash`.
+ */
+import { hashTypedData } from 'viem';
+export const EIP712_DOMAIN_TYPE = 'EIP712Domain(string name,string version,uint256 chainId,address verifyingContract)';
+export const DEBIT_AUTHORIZATION_TYPES = {
+    DebitAuthorization: [
+        { name: 'channelId', type: 'bytes32' },
+        { name: 'hub', type: 'address' },
+        { name: 'token', type: 'address' },
+        { name: 'amount', type: 'uint256' },
+        { name: 'receiptId', type: 'bytes32' },
+        { name: 'nonce', type: 'uint256' },
+        { name: 'deadline', type: 'uint256' },
+    ],
+};
+/** Compute the EIP-712 digest a depositor signs for `debitChannel`. */
+export function computeDebitDigest(params) {
+    return hashTypedData({
+        domain: {
+            name: 'AIMarketEscrow',
+            version: '1',
+            chainId: params.chainId,
+            verifyingContract: params.verifyingContract,
+        },
+        types: DEBIT_AUTHORIZATION_TYPES,
+        primaryType: 'DebitAuthorization',
+        message: {
+            channelId: params.channelId,
+            hub: params.hub,
+            token: params.token,
+            amount: params.amount,
+            receiptId: params.receiptId,
+            nonce: params.nonce,
+            deadline: params.deadline,
+        },
+    });
+}

package/dist/errors.d.ts

@@ -0,0 +1,18 @@
+/** Base exception for AI Market Protocol errors. */
+export declare class AimarketException extends Error {
+    readonly statusCode?: number;
+    constructor(message: string, statusCode?: number);
+}
+/** Network-level error: timeout, connection refused, DNS failure, etc. */
+export declare class AimarketNetworkException extends AimarketException {
+    constructor(message: string, statusCode?: number);
+}
+/** Payment failure: depleted channel, insufficient funds, or expired credit. */
+export declare class AimarketPaymentException extends AimarketException {
+    constructor(message: string, statusCode?: number);
+}
+/** Safety gate blocked the invocation. */
+export declare class AimarketSafetyException extends AimarketException {
+    readonly reason: string;
+    constructor(reason: string);
+}

package/dist/errors.js

@@ -0,0 +1,32 @@
+/** Base exception for AI Market Protocol errors. */
+export class AimarketException extends Error {
+    statusCode;
+    constructor(message, statusCode) {
+        super(message);
+        this.name = 'AimarketException';
+        this.statusCode = statusCode;
+    }
+}
+/** Network-level error: timeout, connection refused, DNS failure, etc. */
+export class AimarketNetworkException extends AimarketException {
+    constructor(message, statusCode) {
+        super(message, statusCode);
+        this.name = 'AimarketNetworkException';
+    }
+}
+/** Payment failure: depleted channel, insufficient funds, or expired credit. */
+export class AimarketPaymentException extends AimarketException {
+    constructor(message, statusCode = 402) {
+        super(message, statusCode);
+        this.name = 'AimarketPaymentException';
+    }
+}
+/** Safety gate blocked the invocation. */
+export class AimarketSafetyException extends AimarketException {
+    reason;
+    constructor(reason) {
+        super(`Safety blocked: ${reason}`, 403);
+        this.name = 'AimarketSafetyException';
+        this.reason = reason;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export { AimarketAgent } from './agent';
+export type { AimarketAgentConfig, AimarketAgentOptions } from './agent';
+export { AimarketException, AimarketNetworkException, AimarketPaymentException, AimarketSafetyException, } from './errors';
+export type { Capability, Channel, InvokeResult, PlanStep, Settlement, BillOfMaterials, TeeAttestation, TeeReceipt, SearchResponse, } from './models';
+export { channelBalanceRatio, channelIsExpired, attestationCanonical, } from './models';
+export { MarketSigner, computeDebitDigest, DEBIT_TYPEHASH_HEADER, ESCROW_CONTRACT_NAME, ESCROW_CONTRACT_VERSION, } from './signer';
+export type { MarketSignerOptions } from './signer';
+export type { DebitAuthorizationParams, Eip712Domain, TypedData, } from './signer';
+export { TeePlatform, TeeVerifier, TrustedHashCache, teeVerificationPass, teeVerificationFail, } from './tee';
+export type { TeeVerificationResult } from './tee';

package/dist/index.js

@@ -0,0 +1,5 @@
+export { AimarketAgent } from './agent';
+export { AimarketException, AimarketNetworkException, AimarketPaymentException, AimarketSafetyException, } from './errors';
+export { channelBalanceRatio, channelIsExpired, attestationCanonical, } from './models';
+export { MarketSigner, computeDebitDigest, DEBIT_TYPEHASH_HEADER, ESCROW_CONTRACT_NAME, ESCROW_CONTRACT_VERSION, } from './signer';
+export { TeePlatform, TeeVerifier, TrustedHashCache, teeVerificationPass, teeVerificationFail, } from './tee';

package/dist/models.d.ts

@@ -0,0 +1,83 @@
+/** Data models for AI Market Protocol v2. */
+export interface Capability {
+    capability_id: string;
+    product_id: string;
+    name: string;
+    version: string;
+    description: string;
+    input_schema?: Record<string, unknown>;
+    output_schema?: Record<string, unknown>;
+    price_per_call_usd: number;
+    p50_latency_ms?: number;
+    success_rate_30d?: number;
+    source_hub: string;
+    source_hub_name?: string;
+    trust_score?: number;
+}
+export interface Channel {
+    channel_id: string;
+    deposit_usd: number;
+    balance_usd: number;
+    token: string;
+    chain: string;
+    expires_at: string;
+}
+export interface TeeAttestation {
+    platform: string;
+    enclave_id: string;
+    code_hash: string;
+    pcr_values: Record<string, string>;
+    instance_id: string;
+    region: string;
+    timestamp: string;
+    ttl_s: number;
+    signature: string;
+}
+export interface TeeReceipt {
+    receipt_id: string;
+    input_hash: string;
+    output_hash: string;
+    signature: string;
+}
+export interface InvokeResult {
+    success: boolean;
+    output?: Record<string, unknown>;
+    price_usd: number;
+    latency_ms: number;
+    safety_blocked: boolean;
+    safety_reason?: string;
+    tee_verified: boolean;
+    tee_attestation?: TeeAttestation;
+    tee_receipt?: TeeReceipt;
+    error?: string;
+}
+export interface PlanStep {
+    capability: Capability;
+    relevance_score: number;
+    rationale: string;
+}
+export interface Settlement {
+    channel_id: string;
+    total_spent_usd: number;
+    refund_usd: number;
+    invocations: number;
+}
+export interface BillOfMaterials {
+    task: string;
+    plan: PlanStep[];
+    results: InvokeResult[];
+    settlement?: Settlement;
+    total_spent_usd: number;
+    protocol_version: string;
+}
+export interface SearchResponse {
+    results: PlanStep[];
+    total: number;
+    hub: string;
+}
+/** Ratio of remaining balance to original deposit (0..1). */
+export declare function channelBalanceRatio(channel: Channel): number;
+/** Whether the channel has passed its expiry timestamp. */
+export declare function channelIsExpired(channel: Channel): boolean;
+/** Canonical string used for TEE attestation signature verification. */
+export declare function attestationCanonical(att: TeeAttestation): string;

package/dist/models.js

@@ -0,0 +1,20 @@
+/** Data models for AI Market Protocol v2. */
+/** Ratio of remaining balance to original deposit (0..1). */
+export function channelBalanceRatio(channel) {
+    if (channel.deposit_usd <= 0)
+        return 0;
+    return channel.balance_usd / channel.deposit_usd;
+}
+/** Whether the channel has passed its expiry timestamp. */
+export function channelIsExpired(channel) {
+    const ts = Date.parse(channel.expires_at);
+    if (Number.isNaN(ts))
+        return true;
+    return ts < Date.now();
+}
+/** Canonical string used for TEE attestation signature verification. */
+export function attestationCanonical(att) {
+    return (`platform:${att.platform}|enclave_id:${att.enclave_id}|code_hash:${att.code_hash}` +
+        `|pcr0:${att.pcr_values.pcr0 ?? ''}|instance:${att.instance_id}` +
+        `|region:${att.region}|timestamp:${att.timestamp}|ttl:${att.ttl_s}`);
+}

package/dist/signer.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Production Ed25519 + EIP-712 signing for AI Market Protocol v2.
+ *
+ * - Canonical hub messages: real Ed25519 (`ed25519:<base64>`)
+ * - On-chain debit auth: keccak256 EIP-712 + secp256k1 (`eip712:0x<r><s><v>`)
+ */
+import { type Address, type Hex } from 'viem';
+export interface Eip712Domain {
+    name: string;
+    version: string;
+    chainId: number;
+    verifyingContract: string;
+}
+export interface TypedData {
+    domain: Eip712Domain;
+    primaryType: string;
+    message: Record<string, string | number | bigint>;
+}
+export declare const DEBIT_TYPEHASH_HEADER = "DebitAuthorization(bytes32 channelId,address hub,address token,uint256 amount,bytes32 receiptId,uint256 nonce,uint256 deadline)";
+export declare const ESCROW_CONTRACT_NAME = "AIMarketEscrow";
+export declare const ESCROW_CONTRACT_VERSION = "1";
+export interface DebitAuthorizationParams {
+    channelId: string;
+    hub: string;
+    token: string;
+    amount: bigint;
+    receiptId: string;
+    nonce: bigint;
+    deadline: number;
+    chainId?: number;
+    verifyingContract?: string;
+}
+export interface MarketSignerOptions {
+    /** 32-byte Ed25519 seed (64-char hex) for canonical invoke signatures. */
+    ed25519SeedHex: string;
+    /** secp256k1 Ethereum private key (64-char hex) for EIP-712 debit auth. */
+    ethereumPrivateKeyHex?: string;
+}
+export declare class MarketSigner {
+    private readonly seed;
+    private readonly keyPair;
+    private readonly ethereumPrivateKeyHex?;
+    constructor(seedOrOptions: string | MarketSignerOptions, ethereumPrivateKeyHex?: string);
+    /** Ed25519 public key as base64 (hub-compatible). */
+    publicKeyBase64(): string;
+    /** Ed25519 public key as hex. */
+    publicKeyHex(): string;
+    /** Sign a canonical UTF-8 string → `ed25519:<base64>`. */
+    signCanonical(canonical: string): string;
+    /** Verify `ed25519:<base64>` with hex- or base64-encoded public key. */
+    verify(publicKey: string, signature: string, canonical: string): boolean;
+    /** Sign EIP-712 debit authorization → `eip712:0x<130 hex chars>`. */
+    signDebitAuthorization(params: DebitAuthorizationParams): string;
+    signEip712TypedData(_data: TypedData): string;
+    signedHeaders(args: {
+        channelId: string;
+        capabilityId: string;
+        affiliate: string;
+    }): Record<string, string>;
+    verifyHubSignature(hubPublicKey: string, message: string, signature: string): boolean;
+    static generateEd25519Keypair(): {
+        seedHex: string;
+        publicKeyBase64: string;
+    };
+    /** Generate a secp256k1 Ethereum wallet for channel deposits / EIP-712. */
+    static generateEthereumWallet(): {
+        privateKeyHex: Hex;
+        address: Address;
+    };
+    /** @deprecated Prefer [generateEd25519Keypair] or [generateEthereumWallet]. */
+    static generateWallet(): {
+        privateKey: string;
+        address: string;
+    };
+}
+export { computeDebitDigest } from './eip712';

package/dist/signer.js

@@ -0,0 +1,164 @@
+/**
+ * Production Ed25519 + EIP-712 signing for AI Market Protocol v2.
+ *
+ * - Canonical hub messages: real Ed25519 (`ed25519:<base64>`)
+ * - On-chain debit auth: keccak256 EIP-712 + secp256k1 (`eip712:0x<r><s><v>`)
+ */
+import nacl from 'tweetnacl';
+import naclUtil from 'tweetnacl-util';
+import { createHash } from 'crypto';
+import { secp256k1 } from '@noble/curves/secp256k1.js';
+import { hexToBytes } from 'viem';
+import { generatePrivateKey, privateKeyToAccount } from 'viem/accounts';
+import { computeDebitDigest } from './eip712';
+export const DEBIT_TYPEHASH_HEADER = 'DebitAuthorization(bytes32 channelId,address hub,address token,uint256 amount,bytes32 receiptId,uint256 nonce,uint256 deadline)';
+export const ESCROW_CONTRACT_NAME = 'AIMarketEscrow';
+export const ESCROW_CONTRACT_VERSION = '1';
+// ── Helpers ───────────────────────────────────────────────────────────────────
+function parseSeedHex(hex) {
+    const normalized = hex.replace(/^0x/i, '');
+    if (normalized.length === 64 && /^[0-9a-fA-F]+$/.test(normalized)) {
+        const bytes = new Uint8Array(32);
+        for (let i = 0; i < 32; i++) {
+            bytes[i] = parseInt(normalized.slice(i * 2, i * 2 + 2), 16);
+        }
+        return bytes;
+    }
+    // Dev fallback: hash arbitrary short strings to a 32-byte seed.
+    return createHash('sha256').update(hex, 'utf8').digest();
+}
+function parseEthPrivateKey(hex) {
+    const normalized = hex.replace(/^0x/i, '');
+    if (normalized.length !== 64 || !/^[0-9a-fA-F]+$/.test(normalized)) {
+        throw new Error('ethereumPrivateKeyHex must be a 32-byte hex string (64 chars)');
+    }
+    return `0x${normalized}`;
+}
+function decodePublicKey(publicKey) {
+    const trimmed = publicKey.trim();
+    if (/^[0-9a-fA-F]+$/.test(trimmed) && trimmed.length === 64) {
+        const bytes = new Uint8Array(32);
+        for (let i = 0; i < 32; i++) {
+            bytes[i] = parseInt(trimmed.slice(i * 2, i * 2 + 2), 16);
+        }
+        return bytes;
+    }
+    return naclUtil.decodeBase64(trimmed);
+}
+function decodeEd25519Signature(signature) {
+    const raw = signature.startsWith('ed25519:') ? signature.slice(8) : signature;
+    return naclUtil.decodeBase64(raw);
+}
+// ── Signer ──────────────────────────────────────────────────────────────────
+export class MarketSigner {
+    seed;
+    keyPair;
+    ethereumPrivateKeyHex;
+    constructor(seedOrOptions, ethereumPrivateKeyHex) {
+        const opts = typeof seedOrOptions === 'string'
+            ? { ed25519SeedHex: seedOrOptions, ethereumPrivateKeyHex }
+            : seedOrOptions;
+        this.seed = parseSeedHex(opts.ed25519SeedHex);
+        this.keyPair = nacl.sign.keyPair.fromSeed(this.seed);
+        this.ethereumPrivateKeyHex = opts.ethereumPrivateKeyHex
+            ? parseEthPrivateKey(opts.ethereumPrivateKeyHex)
+            : undefined;
+    }
+    /** Ed25519 public key as base64 (hub-compatible). */
+    publicKeyBase64() {
+        return naclUtil.encodeBase64(this.keyPair.publicKey);
+    }
+    /** Ed25519 public key as hex. */
+    publicKeyHex() {
+        return Buffer.from(this.keyPair.publicKey).toString('hex');
+    }
+    /** Sign a canonical UTF-8 string → `ed25519:<base64>`. */
+    signCanonical(canonical) {
+        const message = new TextEncoder().encode(canonical);
+        const sig = nacl.sign.detached(message, this.keyPair.secretKey);
+        return `ed25519:${naclUtil.encodeBase64(sig)}`;
+    }
+    /** Verify `ed25519:<base64>` with hex- or base64-encoded public key. */
+    verify(publicKey, signature, canonical) {
+        if (!signature.startsWith('ed25519:'))
+            return false;
+        try {
+            const message = new TextEncoder().encode(canonical);
+            const sig = decodeEd25519Signature(signature);
+            const pub = decodePublicKey(publicKey);
+            return nacl.sign.detached.verify(message, sig, pub);
+        }
+        catch {
+            return false;
+        }
+    }
+    /** Sign EIP-712 debit authorization → `eip712:0x<130 hex chars>`. */
+    signDebitAuthorization(params) {
+        const ethKey = this.ethereumPrivateKeyHex;
+        if (!ethKey) {
+            throw new Error('ethereumPrivateKeyHex is required for EIP-712 debit signing. ' +
+                'Pass it to MarketSigner constructor as second argument or via MarketSignerOptions.');
+        }
+        const digest = computeDebitDigest({
+            channelId: params.channelId,
+            hub: params.hub,
+            token: params.token,
+            amount: params.amount,
+            receiptId: params.receiptId,
+            nonce: params.nonce,
+            deadline: BigInt(params.deadline),
+            chainId: params.chainId ?? 8453,
+            verifyingContract: (params.verifyingContract ??
+                '0x0000000000000000000000000000000000000000'),
+        });
+        const digestBytes = hexToBytes(digest);
+        const privBytes = hexToBytes(ethKey);
+        const recovered = secp256k1.sign(digestBytes, privBytes, {
+            lowS: true,
+            format: 'recovered',
+        });
+        const r = Buffer.from(recovered.slice(0, 32)).toString('hex');
+        const s = Buffer.from(recovered.slice(32, 64)).toString('hex');
+        const v = recovered[64] + 27;
+        return `eip712:0x${r}${s}${v.toString(16).padStart(2, '0')}`;
+    }
+    signEip712TypedData(_data) {
+        throw new Error('signEip712TypedData removed — use signDebitAuthorization() for AIMarketEscrow');
+    }
+    signedHeaders(args) {
+        const canonical = `channel:${args.channelId}|capability:${args.capabilityId}|affiliate:${args.affiliate}`;
+        return {
+            'X-Payment-Channel': args.channelId,
+            'X-AIMarket-Affiliate': args.affiliate,
+            'X-Market-Signature': this.signCanonical(canonical),
+        };
+    }
+    verifyHubSignature(hubPublicKey, message, signature) {
+        if (signature.startsWith('eip712:'))
+            return false;
+        const canonical = signature.startsWith('ed25519:') ? message : message;
+        const sig = signature.startsWith('ed25519:') ? signature : `ed25519:${signature}`;
+        return this.verify(hubPublicKey, sig, canonical);
+    }
+    static generateEd25519Keypair() {
+        const seed = nacl.randomBytes(32);
+        const pair = nacl.sign.keyPair.fromSeed(seed);
+        return {
+            seedHex: Buffer.from(seed).toString('hex'),
+            publicKeyBase64: naclUtil.encodeBase64(pair.publicKey),
+        };
+    }
+    /** Generate a secp256k1 Ethereum wallet for channel deposits / EIP-712. */
+    static generateEthereumWallet() {
+        const privateKey = generatePrivateKey();
+        const account = privateKeyToAccount(privateKey);
+        return { privateKeyHex: privateKey, address: account.address };
+    }
+    /** @deprecated Prefer [generateEd25519Keypair] or [generateEthereumWallet]. */
+    static generateWallet() {
+        const eth = MarketSigner.generateEthereumWallet();
+        return { privateKey: eth.privateKeyHex.slice(2), address: eth.address };
+    }
+}
+// Re-export digest helper at package boundary.
+export { computeDebitDigest } from './eip712';

package/dist/tee.d.ts

@@ -0,0 +1,54 @@
+import { type TeeAttestation, type TeeReceipt } from './models';
+import { MarketSigner } from './signer';
+/** Recognized TEE platform identifiers. */
+export declare const TeePlatform: {
+    readonly awsNitro: "aws_nitro";
+    readonly intelTdx: "intel_tdx";
+    readonly amdSev: "amd_sev";
+    readonly azureCc: "azure_cc";
+    readonly all: Set<string>;
+    readonly displayNames: {
+        readonly aws_nitro: "AWS Nitro Enclaves";
+        readonly intel_tdx: "Intel TDX";
+        readonly amd_sev: "AMD SEV-SNP";
+        readonly azure_cc: "Azure Confidential Computing";
+    };
+    readonly isSupported: (platform: string) => boolean;
+};
+/** Result of a TEE attestation verification with detailed failure reasons. */
+export interface TeeVerificationResult {
+    isValid: boolean;
+    failures: string[];
+}
+export declare function teeVerificationPass(): TeeVerificationResult;
+export declare function teeVerificationFail(failures: string[]): TeeVerificationResult;
+/** Caches trusted code hashes fetched from the hub, with TTL expiry. */
+export declare class TrustedHashCache {
+    private readonly ttlMs;
+    private readonly entries;
+    constructor(ttlMs?: number);
+    get(key: string): string | undefined;
+    set(key: string, hash: string): void;
+    clear(): void;
+    get size(): number;
+}
+/** Verifies TEE attestations and receipts client-side. */
+export declare class TeeVerifier {
+    private readonly signer;
+    private readonly trustedCodeHashes;
+    private readonly hashCache;
+    private readonly enclavePublicKeys;
+    lastFetch: Date | null;
+    constructor(opts: {
+        signer: MarketSigner;
+        trustedCodeHashes?: Record<string, string>;
+        hashCache?: TrustedHashCache;
+        /** Override hub well-known enclave keys (hex or base64 public keys). */
+        enclavePublicKeys?: Record<string, string>;
+    });
+    trustCodeHash(capabilityId: string, codeHash: string): void;
+    fetchTrustedHashes(hubUrl: string, fetchFn?: typeof fetch): Promise<number>;
+    verifyAttestationDetailed(attestation: TeeAttestation, capabilityId: string): TeeVerificationResult;
+    verifyAttestation(attestation: TeeAttestation, capabilityId: string): boolean;
+    verifyReceipt(receipt: TeeReceipt, expectedInput: string, receivedOutput: string): boolean;
+}

package/dist/tee.js

@@ -0,0 +1,148 @@
+import { createHash } from 'crypto';
+import { attestationCanonical } from './models';
+/** Recognized TEE platform identifiers. */
+export const TeePlatform = {
+    awsNitro: 'aws_nitro',
+    intelTdx: 'intel_tdx',
+    amdSev: 'amd_sev',
+    azureCc: 'azure_cc',
+    all: new Set(['aws_nitro', 'intel_tdx', 'amd_sev', 'azure_cc']),
+    displayNames: {
+        aws_nitro: 'AWS Nitro Enclaves',
+        intel_tdx: 'Intel TDX',
+        amd_sev: 'AMD SEV-SNP',
+        azure_cc: 'Azure Confidential Computing',
+    },
+    isSupported(platform) {
+        return TeePlatform.all.has(platform);
+    },
+};
+export function teeVerificationPass() {
+    return { isValid: true, failures: [] };
+}
+export function teeVerificationFail(failures) {
+    return { isValid: false, failures };
+}
+/** Caches trusted code hashes fetched from the hub, with TTL expiry. */
+export class TrustedHashCache {
+    ttlMs;
+    entries = new Map();
+    constructor(ttlMs = 5 * 60 * 1000) {
+        this.ttlMs = ttlMs;
+    }
+    get(key) {
+        const entry = this.entries.get(key);
+        if (!entry)
+            return undefined;
+        if (Date.now() > entry.expiresAt) {
+            this.entries.delete(key);
+            return undefined;
+        }
+        return entry.hash;
+    }
+    set(key, hash) {
+        this.entries.set(key, { hash, expiresAt: Date.now() + this.ttlMs });
+    }
+    clear() {
+        this.entries.clear();
+    }
+    get size() {
+        return this.entries.size;
+    }
+}
+function sha256Hex(input) {
+    return createHash('sha256').update(input, 'utf8').digest('hex');
+}
+function attestationIsExpired(attestation) {
+    const ts = Date.parse(attestation.timestamp);
+    if (Number.isNaN(ts))
+        return true;
+    const ageS = (Date.now() - ts) / 1000;
+    return ageS > attestation.ttl_s;
+}
+/** Verifies TEE attestations and receipts client-side. */
+export class TeeVerifier {
+    signer;
+    trustedCodeHashes;
+    hashCache;
+    enclavePublicKeys;
+    lastFetch = null;
+    constructor(opts) {
+        this.signer = opts.signer;
+        this.trustedCodeHashes = new Map(Object.entries(opts.trustedCodeHashes ?? {}));
+        this.hashCache = opts.hashCache ?? new TrustedHashCache();
+        this.enclavePublicKeys = { ...DEFAULT_ENCLAVE_PUBLIC_KEYS, ...opts.enclavePublicKeys };
+    }
+    trustCodeHash(capabilityId, codeHash) {
+        this.trustedCodeHashes.set(capabilityId, codeHash);
+        this.hashCache.set(capabilityId, codeHash);
+    }
+    async fetchTrustedHashes(hubUrl, fetchFn = fetch) {
+        try {
+            const resp = await fetchFn(`${hubUrl.replace(/\/$/, '')}/.well-known/trusted-code-hashes.json`);
+            if (!resp.ok)
+                return -1;
+            const data = (await resp.json());
+            const hashes = data.hashes ?? [];
+            for (const entry of hashes) {
+                if (entry.capability_id && entry.code_hash) {
+                    this.hashCache.set(entry.capability_id, entry.code_hash);
+                    this.trustedCodeHashes.set(entry.capability_id, entry.code_hash);
+                }
+            }
+            this.lastFetch = new Date();
+            return hashes.length;
+        }
+        catch {
+            return -1;
+        }
+    }
+    verifyAttestationDetailed(attestation, capabilityId) {
+        const failures = [];
+        if (!TeePlatform.isSupported(attestation.platform)) {
+            failures.push(`Unsupported TEE platform: ${attestation.platform}`);
+        }
+        const ts = Date.parse(attestation.timestamp);
+        if (Number.isNaN(ts)) {
+            failures.push(`Invalid attestation timestamp: ${attestation.timestamp}`);
+        }
+        else if (attestationIsExpired(attestation)) {
+            const ageS = Math.floor((Date.now() - ts) / 1000);
+            failures.push(`Attestation expired (age: ${ageS}s, ttl: ${attestation.ttl_s}s)`);
+        }
+        if (Object.keys(attestation.pcr_values).length === 0) {
+            failures.push('PCR values are empty — attestation lacks hardware proof');
+        }
+        const expectedHash = this.hashCache.get(capabilityId) ?? this.trustedCodeHashes.get(capabilityId);
+        if (expectedHash != null && attestation.code_hash !== expectedHash) {
+            failures.push(`Code hash mismatch: expected ${expectedHash}, got ${attestation.code_hash}`);
+        }
+        const enclaveKey = this.enclavePublicKeys[attestation.platform];
+        if (!enclaveKey) {
+            failures.push(`No known enclave public key for platform: ${attestation.platform}`);
+        }
+        else if (!this.signer.verify(enclaveKey, attestation.signature, attestationCanonical(attestation))) {
+            failures.push('Enclave signature verification failed');
+        }
+        return failures.length === 0 ? teeVerificationPass() : teeVerificationFail(failures);
+    }
+    verifyAttestation(attestation, capabilityId) {
+        return this.verifyAttestationDetailed(attestation, capabilityId).isValid;
+    }
+    verifyReceipt(receipt, expectedInput, receivedOutput) {
+        const inputHash = sha256Hex(expectedInput);
+        const outputHash = sha256Hex(receivedOutput);
+        if (receipt.input_hash !== inputHash)
+            return false;
+        if (receipt.output_hash !== outputHash)
+            return false;
+        return true;
+    }
+}
+/** Simulated defaults — production hubs publish keys at `/.well-known/enclave-keys.json`. */
+const DEFAULT_ENCLAVE_PUBLIC_KEYS = {
+    aws_nitro: 'nitro_enclave_pubkey_hex',
+    intel_tdx: 'tdx_enclave_pubkey_hex',
+    amd_sev: 'sev_enclave_pubkey_hex',
+    azure_cc: 'azure_cc_pubkey_hex',
+};

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@aimarket/agent",
+  "version": "0.1.0",
+  "description": "AI Market Protocol v2 consumer SDK for TypeScript — Electron, Node.js, web apps",
+  "repository": "https://github.com/alexar76/aimarket-sdks",
+  "homepage": "https://github.com/alexar76/aimarket-sdks/tree/main/typescript",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "lint": "eslint src/",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@noble/curves": "^2.2.0",
+    "@noble/hashes": "^2.2.0",
+    "tweetnacl": "^1.0.3",
+    "tweetnacl-util": "^0.15.1",
+    "viem": "^2.52.2"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "eslint": "^8.57.0",
+    "typescript": "^5.4.0",
+    "vitest": "^1.6.0"
+  }
+}