402mob-merchant-sdk 0.4.2 → 0.6.0

package/dist/protected-work.js

@@ -0,0 +1,187 @@
+import { protectedSchemas } from './protected-work-schemas.js';
+export * from './protected-work-types.js';
+const USDC = '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913';
+const hash = /^0x[0-9a-f]{64}$/;
+const address = /^0x(?!0{40}$)[0-9a-fA-F]{40}$/;
+const record = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+const canonical = (v) => JSON.stringify(v, (_key, item) => record(item) ? Object.fromEntries(Object.entries(item).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)) : item);
+function matches(s, v, depth = 0) {
+    if (depth > 128)
+        return false;
+    if ('const' in s && canonical(s.const) !== canonical(v))
+        return false;
+    if (s.enum && !s.enum.includes(v))
+        return false;
+    if (s.anyOf && !s.anyOf.some(c => matches(c, v, depth + 1)))
+        return false;
+    if (s.oneOf && s.oneOf.filter(c => matches(c, v, depth + 1)).length !== 1)
+        return false;
+    if (Array.isArray(s.type))
+        return s.type.some(type => matches({ ...s, type }, v, depth + 1));
+    switch (s.type) {
+        case 'null': return v === null;
+        case 'boolean': return typeof v === 'boolean';
+        case 'number':
+        case 'integer': return typeof v === 'number' && Number.isFinite(v) && (s.type !== 'integer' || Number.isSafeInteger(v)) && (s.minimum === undefined || v >= s.minimum) && (s.maximum === undefined || v <= s.maximum) && (s.exclusiveMinimum === undefined || v > s.exclusiveMinimum);
+        case 'string': return typeof v === 'string' && (s.minLength === undefined || [...v].length >= s.minLength) && (s.maxLength === undefined || [...v].length <= s.maxLength) && (!s.pattern || new RegExp(s.pattern).test(v)) && (!s.format || s.format === 'date-time' && /^\d{4}-\d\d-\d\dT/.test(v) && Number.isFinite(Date.parse(v)));
+        case 'array': return Array.isArray(v) && (s.minItems === undefined || v.length >= s.minItems) && (s.maxItems === undefined || v.length <= s.maxItems) && v.every((item, i) => { const child = s.prefixItems?.[i] ?? s.items ?? {}; return child !== false && (child === true || matches(child, item, depth + 1)); });
+        case 'object': return record(v) && (s.required ?? []).every(k => Object.hasOwn(v, k)) && Object.entries(v).every(([k, item]) => s.properties && Object.hasOwn(s.properties, k) ? matches(s.properties[k], item, depth + 1) : s.additionalProperties !== false);
+        default: return true;
+    }
+}
+export class ProtectedWorkApiError extends Error {
+    status;
+    code;
+    constructor(status, code, message) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = 'ProtectedWorkApiError';
+    }
+}
+/** HTTP transport only. No keys, merchant bearer tokens, wallet signing or transaction broadcasting. */
+export class ProtectedWorkClient {
+    origin;
+    contract;
+    verifierHash;
+    fetcher;
+    constructor(options = {}) {
+        const url = new URL(options.baseUrl ?? 'https://evidence.contact');
+        if (url.username || url.password || url.search || url.hash || url.pathname !== '/' || !(url.protocol === 'https:' || url.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname)))
+            throw new TypeError('Provide an exact HTTPS origin, or HTTP loopback for local tests.');
+        if (options.contract !== undefined && !address.test(options.contract))
+            throw new TypeError('Invalid escrow contract address.');
+        if (options.verifierHash !== undefined && !hash.test(options.verifierHash))
+            throw new TypeError('Invalid pinned verifier hash.');
+        this.origin = url.origin;
+        this.contract = options.contract?.toLowerCase();
+        this.verifierHash = options.verifierHash;
+        this.fetcher = options.fetch ?? globalThis.fetch;
+    }
+    getCapabilities() { return this.call('', 'GET', undefined, undefined, 'ProtectedWorkCapability'); }
+    prepare(input) { return this.call('/prepare', 'POST', input, 'ProtectedWorkPrepareRequest', 'ProtectedWorkPrepareResponse'); }
+    prepareFunding(input) { return this.call('/funding', 'POST', input, 'ProtectedWorkFundingRequest', 'ProtectedWorkFundingResponse'); }
+    getJob(id) { return this.job(id, '', 'GET', undefined, undefined, 'ProtectedWorkStatus'); }
+    createReadChallenge(id, input) { return this.job(id, '/challenges', 'POST', input, 'ProtectedWorkChallengeRequest', 'ProtectedWorkChallenge'); }
+    createCandidateSigning(id, input) { return this.job(id, '/candidate-signing', 'POST', input, 'ProtectedWorkCandidateRequest', 'ProtectedWorkCandidateSigning'); }
+    submitCandidate(id, input) { return this.job(id, '/submissions', 'POST', input, 'ProtectedWorkSubmissionRequest', 'ProtectedWorkSubmissionResponse'); }
+    attachReplicas(id, input) { return this.job(id, '/replicas', 'POST', input, 'ProtectedWorkReplicasRequest', 'ProtectedWorkReplicasResponse'); }
+    evaluate(id) { return this.job(id, '/evaluation', 'POST', {}, 'ProtectedWorkEvaluationRequest', 'ProtectedWorkEvaluationResponse'); }
+    readResult(id, input) { return this.job(id, '/result', 'POST', input, 'ProtectedWorkResultRequest', 'ProtectedWorkResult'); }
+    /** With no signature, requests a draft. A signed action may be relayed by a configured server. */
+    requestAction(id, input) { return this.job(id, '/actions', 'POST', input, 'ProtectedWorkActionRequest', 'ProtectedWorkActionResponse'); }
+    submitAppeal(id, input) { return this.job(id, '/appeals', 'POST', input, 'ProtectedWorkAppealRequest', 'ProtectedWorkAppealResponse'); }
+    job(id, suffix, method, input, inputSchema, outputSchema) {
+        if (!hash.test(id))
+            throw new TypeError('Protected job IDs are lowercase 32-byte hashes, not operation UUIDs.');
+        return this.call('/' + id + suffix, method, input, inputSchema, outputSchema, id);
+    }
+    invalid() { throw new ProtectedWorkApiError(200, 'invalid_response', 'Protected-work response does not match the pinned request. Preserve the job and signed transaction; do not repeat funding.'); }
+    transaction(value, allowApproval = false, amount) {
+        if (!record(value) || value.chainId !== 8453 || value.value !== '0' || typeof value.to !== 'string' || typeof value.data !== 'string' || !/^0x(?:[a-fA-F0-9]{2})+$/.test(value.data))
+            this.invalid();
+        if (allowApproval) {
+            if (value.to.toLowerCase() !== USDC || !amount || value.data.toLowerCase() !== '0x095ea7b3' + this.contract.slice(2).padStart(64, '0') + BigInt(amount).toString(16).padStart(64, '0'))
+                this.invalid();
+        }
+        else if (value.to.toLowerCase() !== this.contract)
+            this.invalid();
+    }
+    async call(suffix, method, input, inputSchema, outputSchema, id) {
+        if (suffix && (!this.contract || !this.verifierHash))
+            throw new TypeError('Pin contract and verifierHash before using protected-work methods.');
+        const body = input === undefined ? undefined : JSON.stringify(input);
+        if (body !== undefined && (new TextEncoder().encode(body).length > 65536 || inputSchema && !matches(protectedSchemas[inputSchema], JSON.parse(body))))
+            throw new TypeError('Protected-work input does not match its schema or exceeds 64 KiB.');
+        if (record(input) && record(input.terms) && input.terms.verifierHash !== undefined && input.terms.verifierHash !== this.verifierHash)
+            throw new TypeError('Funding verifier differs from the pinned verifier.');
+        const response = await this.fetcher(this.origin + '/v1/protected-work' + suffix, { method, redirect: 'error', credentials: 'omit', headers: { Accept: 'application/json', ...(body === undefined ? {} : { 'Content-Type': 'application/json' }) }, ...(body === undefined ? {} : { body }) });
+        let payload;
+        try {
+            if (!response.body)
+                throw new Error();
+            const reader = response.body.getReader(), chunks = [];
+            let size = 0;
+            try {
+                while (true) {
+                    const item = await reader.read();
+                    if (item.done)
+                        break;
+                    size += item.value.length;
+                    if (size > 65536) {
+                        await reader.cancel();
+                        throw new Error();
+                    }
+                    chunks.push(item.value);
+                }
+            }
+            finally {
+                reader.releaseLock();
+            }
+            const bytes = new Uint8Array(size);
+            let offset = 0;
+            for (const chunk of chunks) {
+                bytes.set(chunk, offset);
+                offset += chunk.length;
+            }
+            payload = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes));
+        }
+        catch {
+            throw new ProtectedWorkApiError(response.status, response.ok ? 'invalid_response' : 'http_error', 'Unreadable or oversized response; preserve recovery data.');
+        }
+        if (!response.ok)
+            throw new ProtectedWorkApiError(response.status, record(payload) && typeof payload.error === 'string' ? payload.error : 'http_error', 'Protected-work request was rejected. Inspect status/code and the existing job before retrying.');
+        if (!matches(protectedSchemas[outputSchema], payload) || !record(payload))
+            this.invalid();
+        if (id && 'jobId' in payload && payload.jobId !== id)
+            this.invalid();
+        if (record(payload.relay) && payload.relay.queued !== (payload.relay.id !== null))
+            this.invalid();
+        if (suffix === '') {
+            if (payload.protocol !== '402mob.protected-json-work.v3' || payload.network !== 'eip155:8453' || (typeof payload.asset !== 'string' || payload.asset.toLowerCase() !== USDC) || this.verifierHash && payload.verifierHash !== this.verifierHash)
+                this.invalid();
+        }
+        if (record(payload.terms) && payload.terms.verifierHash !== this.verifierHash)
+            this.invalid();
+        for (const key of ['transaction', 'submissionTransaction', 'evaluationTransaction', 'refundTransaction', 'finalizeTransaction'])
+            if (payload[key] !== undefined && payload[key] !== null)
+                this.transaction(payload[key]);
+        if (Array.isArray(payload.transactions)) {
+            const amount = record(input) && record(input.terms) ? String(input.terms.amount) : undefined;
+            payload.transactions.forEach((tx, i) => this.transaction(tx, i === 0, amount));
+        }
+        for (const key of ['signing', 'sellerSigning'])
+            if (payload[key] !== undefined && payload[key] !== null) {
+                const signing = payload[key];
+                if (!record(signing) || !record(signing.domain) || !record(signing.message))
+                    this.invalid();
+                const d = signing.domain;
+                if (d.name !== '402Mob Protected Work' || d.version !== '3' || d.chainId !== 8453 || typeof d.verifyingContract !== 'string' || d.verifyingContract.toLowerCase() !== this.contract)
+                    this.invalid();
+                if (id && signing.message.jobId !== id)
+                    this.invalid();
+                if (suffix.endsWith('/candidate-signing') && record(input) && (signing.primaryType !== 'Candidate' || signing.message.attempt !== input.attempt || signing.message.resultHash !== input.resultHash))
+                    this.invalid();
+                if (suffix.endsWith('/actions') && record(input) && signing.primaryType !== { receipt: 'Receipt', accept: 'Accept', challenge: 'Challenge' }[String(input.action)])
+                    this.invalid();
+            }
+        if (suffix.endsWith('/actions') && record(input)) {
+            const draft = input.signature === undefined && ['receipt', 'accept', 'challenge'].includes(String(input.action));
+            if (draft ? (payload.signing === null || payload.transaction !== null) : (payload.signing !== null || payload.transaction === null))
+                this.invalid();
+        }
+        if (suffix === '/prepare') {
+            if (!record(input) || !record(input.terms) || !record(payload.sellerSigning) || canonical(payload.terms) !== canonical({ ...input.terms, workHash: payload.workHash, verifierHash: this.verifierHash }) || canonical(payload.sellerSigning.message) !== canonical(payload.terms))
+                this.invalid();
+        }
+        if (suffix.endsWith('/challenges')) {
+            if (!record(input) || typeof input.wallet !== 'string' || typeof payload.expiresAt !== 'number' || payload.wallet !== input.wallet || payload.action !== 'read')
+                this.invalid();
+            const now = Math.floor(Date.now() / 1000);
+            const expected = '402Mob protected JSON work read proof\n' + canonical({ protocol: '402mob.protected-json-work.v3', origin: this.origin, contract: this.contract, chainId: 8453, jobId: id, action: 'read', wallet: input.wallet.toLowerCase(), expiresAt: payload.expiresAt });
+            if (payload.message !== expected || payload.expiresAt <= now || payload.expiresAt > now + 120)
+                this.invalid();
+        }
+        return payload;
+    }
+}

package/examples/protected-inspection-service.ts

@@ -0,0 +1,31 @@
+import {MerchantClient,type WorkerProfileInput,type FreshWorkProposalInput,type EvmAddress} from '../dist/index.js';
+
+// Source SDK 0.6.0 example. No side effects on import and no signing or payment.
+export const inspectionCapabilityId='payment-readiness-inspection';
+export const inspectionWorkerProfile:WorkerProfileInput={
+ description:'Inspect buyer-signed endpoint observations and verify claimed Base USDC test payments under the protected inspection policy.',
+ availability:'accepting',discoverable:true,
+ capabilities:[{id:inspectionCapabilityId,title:'Payment-readiness evidence inspection',description:'Classify one bounded buyer probe. Negative and unresolved findings can be valid delivery. No independent HTTP truth or general audit certification.',inputDescription:'Selected protected_inspection proposal, confirmed service-fee escrow and retained buyer-signed observation. The buyer runs and funds any endpoint test.',resultDescription:'inspection-result-v1 JSON: observation, buyerSignature and fixed classification. Passing evidence is subject to escrow review and appeal.',resultContentTypes:['application/json']}]
+};
+
+// Review real capacity and discovery consent first. Profile PUT fully replaces
+// existing capabilities; merge this declaration with any you want to preserve.
+export function advertiseInspection(merchant:MerchantClient,reviewedProfile:WorkerProfileInput){
+ return merchant.setWorkerProfile(reviewedProfile);
+}
+export function findInspectionSellers(buyer:MerchantClient){
+ return buyer.searchWorkers({capability:inspectionCapabilityId,contentType:'application/json',limit:20});
+}
+
+// Check GET /v1/protected-inspections and the deployment record first. Inputs
+// come from actual authorized demand, not from this example. Prices are chosen
+// by the seller; current pilot capacity is at most 1 USDC unsettled in total.
+export function proposeInspection(merchant:MerchantClient,input:{requestId:string;targetUrl:string;paymentRecipient:EvmAddress;deliveryDeadline:string;servicePriceUSDC:string;testBudgetUSDC:string;testBudgetAtomic:string}){
+ const proposal:FreshWorkProposalInput={capability:inspectionCapabilityId,deliverable:'Verify the buyer-signed observation and any claimed Base USDC test transfer; return the fixed classification.',priceUSDC:input.servicePriceUSDC,deliveryDeadline:input.deliveryDeadline,testPurchaseBudgetUSDC:input.testBudgetUSDC,testPurchasePayer:'buyer',settlementMode:'protected_inspection',inspection:{version:'buyer-probe-v1',targetUrl:input.targetUrl,method:'GET',paymentRecipient:input.paymentRecipient,maxTestAmountAtomic:input.testBudgetAtomic,maxPaidAttempts:1},note:'A negative or unresolved finding may earn the service fee. The external test payment is separate and not refunded by escrow.'};
+ return merchant.proposeWorkRequest(input.requestId,proposal);
+}
+
+// Selection returns protectedWorkHandoff. Use ProtectedInspectionClient for
+// escrow preparation. Exchange the job ID through your agreed channel; there
+// is no hosted inspection inbox or automatic notification. Require confirmed
+// funding and signed evidence via /start before beginning the paid inspection.

package/examples/protected-work.ts

@@ -0,0 +1,21 @@
+import {ProtectedWorkClient, type ProtectedWorkClientOptions, type ProtectedWorkPrepareRequest} from '../dist/index.js';
+
+// Supply a reviewed origin, contract and verifier hash; never copy a test contract into production.
+export async function prepareJsonWork(options: ProtectedWorkClientOptions, input: ProtectedWorkPrepareRequest) {
+  const client = new ProtectedWorkClient(options);
+  const capability = await client.getCapabilities();
+  if (!capability.configured) throw new Error('Protected work is disabled on this server.');
+  // The caller reviews the returned terms and EIP-712 data before asking its seller wallet to sign.
+  return client.prepare(input);
+}
+
+export async function readCandidate(options: ProtectedWorkClientOptions, jobId: string, wallet: string,
+  signMessage: (exactMessage: string) => Promise<string>) {
+  const client = new ProtectedWorkClient(options);
+  const challenge = await client.createReadChallenge(jobId, {action: 'read', wallet});
+  // The client has checked the challenge's origin, contract, wallet, job and expiry.
+  const signature = await signMessage(challenge.message);
+  return client.readResult(jobId, {proof: {wallet, expiresAt: challenge.expiresAt, signature}});
+}
+
+// A read or receipt is not acceptance. No example broadcasts, funds, signs acceptance or retries.

package/examples/respond-to-work-request.ts

@@ -0,0 +1,21 @@
+import {MerchantClient} from '../dist/index.js';
+
+// Supply an enrolled merchant client from your runtime's secret manager.
+// Register an accepting x402-endpoint-audit worker capability first.
+// Decide feasibility and authorize any test spending in your own runtime.
+export function proposeEndpointAudit(client:MerchantClient,requestId:string,deliveryDeadline:string){
+  return client.proposeWorkRequest(requestId,{
+    capability:'x402-endpoint-audit',
+    deliverable:'JSON findings with reproductions and transaction references.',
+    priceUSDC:'5',deliveryDeadline,
+    testPurchaseBudgetUSDC:'0.02',testPurchasePayer:'seller',
+    note:'Audit fee excludes seller-funded test purchases; scope follows the public request.'
+  });
+}
+
+export function declineEndpointAudit(client:MerchantClient,requestId:string){
+  return client.declineWorkRequest(requestId,{
+    reason:'endpoint_unavailable',
+    note:'The authorized feasibility check failed; no audit fee requested.'
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "402mob-merchant-sdk",
-  "version": "0.4.2",
+  "version": "0.6.0",
   "description": "TypeScript client for resolving agent resources and enrolling and operating 402Mob merchants.",
   "license": "MIT",
   "repository": {