@hivemind-os/collective-core 0.2.0

package/src/task/client.ts

@@ -0,0 +1,215 @@
+import pino from 'pino';
+
+import type { NetworkConfig, Task } from '@hivemind-os/collective-types';
+import type { Signer } from '@mysten/sui/cryptography';
+
+import { parseTaskFields } from '../internal/parsing.js';
+import { MeshSuiClient } from '../sui/client.js';
+import {
+  buildAcceptTaskTx,
+  buildCancelTaskTx,
+  buildClaimPaymentTx,
+  buildCompleteMeteredTaskTx,
+  buildCompleteTaskTx,
+  buildPostMeteredTaskTx,
+  buildPostTaskTx,
+  buildRefundExpiredTaskTx,
+  buildReleaseMeteredPaymentTx,
+  buildReleasePaymentTx,
+} from '../sui/tx-helpers.js';
+
+const logger = pino({ name: '@hivemind-os/collective-core:task' });
+
+export class TaskClient {
+  constructor(
+    private readonly suiClient: MeshSuiClient,
+    private readonly config: NetworkConfig,
+  ) {}
+
+  async postTask(params: {
+    capability: string;
+    category: string;
+    inputBlobId: string;
+    agreementHash?: string;
+    priceMist: bigint;
+    disputeWindowMs: number;
+    expiryHours: number;
+    keypair: Signer;
+  }): Promise<{ txDigest: string; taskId: string }> {
+    const tx = buildPostTaskTx({
+      packageId: this.config.packageId,
+      capability: params.capability,
+      category: params.category,
+      inputBlobId: params.inputBlobId,
+      agreementHash: params.agreementHash,
+      priceMist: params.priceMist,
+      disputeWindowMs: params.disputeWindowMs,
+      expiryHours: params.expiryHours,
+    });
+
+    return await this.submitTaskCreation(tx, params.keypair);
+  }
+
+  async postMeteredTask(params: {
+    capability: string;
+    category: string;
+    inputBlobId: string;
+    agreementHash?: string;
+    maxPriceMist: bigint;
+    unitPriceMist: bigint;
+    disputeWindowMs: number;
+    expiryHours: number;
+    keypair: Signer;
+  }): Promise<{ txDigest: string; taskId: string }> {
+    const tx = buildPostMeteredTaskTx({
+      packageId: this.config.packageId,
+      capability: params.capability,
+      category: params.category,
+      inputBlobId: params.inputBlobId,
+      agreementHash: params.agreementHash,
+      maxPriceMist: params.maxPriceMist,
+      unitPriceMist: params.unitPriceMist,
+      disputeWindowMs: params.disputeWindowMs,
+      expiryHours: params.expiryHours,
+    });
+
+    return await this.submitTaskCreation(tx, params.keypair);
+  }
+
+  async acceptTask(params: {
+    taskId: string;
+    keypair: Signer;
+  }): Promise<{ txDigest: string }> {
+    const tx = buildAcceptTaskTx({ packageId: this.config.packageId, taskId: params.taskId });
+    const response = await this.suiClient.executeTransaction(tx, params.keypair);
+    return { txDigest: response.digest };
+  }
+
+  async completeTask(params: {
+    taskId: string;
+    resultBlobId: string;
+    keypair: Signer;
+    providerCardId?: string;
+  }): Promise<{ txDigest: string }> {
+    const tx = buildCompleteTaskTx({
+      packageId: this.config.packageId,
+      taskId: params.taskId,
+      resultBlobId: params.resultBlobId,
+      providerCardId: params.providerCardId,
+    });
+    const response = await this.suiClient.executeTransaction(tx, params.keypair);
+    return { txDigest: response.digest };
+  }
+
+  async completeMeteredTask(params: {
+    taskId: string;
+    resultBlobId: string;
+    meteredUnits: number;
+    verificationHash: string;
+    keypair: Signer;
+    providerCardId?: string;
+  }): Promise<{ txDigest: string }> {
+    const tx = buildCompleteMeteredTaskTx({
+      packageId: this.config.packageId,
+      taskId: params.taskId,
+      resultBlobId: params.resultBlobId,
+      meteredUnits: params.meteredUnits,
+      verificationHash: params.verificationHash,
+      providerCardId: params.providerCardId,
+    });
+    const response = await this.suiClient.executeTransaction(tx, params.keypair);
+    return { txDigest: response.digest };
+  }
+
+  async releasePayment(params: {
+    taskId: string;
+    keypair: Signer;
+  }): Promise<{ txDigest: string }> {
+    const tx = buildReleasePaymentTx({ packageId: this.config.packageId, taskId: params.taskId });
+    const response = await this.suiClient.executeTransaction(tx, params.keypair);
+    return { txDigest: response.digest };
+  }
+
+  async releaseMeteredPayment(params: {
+    taskId: string;
+    keypair: Signer;
+  }): Promise<{ txDigest: string }> {
+    const tx = buildReleaseMeteredPaymentTx({ packageId: this.config.packageId, taskId: params.taskId });
+    const response = await this.suiClient.executeTransaction(tx, params.keypair);
+    return { txDigest: response.digest };
+  }
+
+  async claimPayment(params: {
+    taskId: string;
+    keypair: Signer;
+    providerCardId?: string;
+  }): Promise<{ txDigest: string }> {
+    const tx = buildClaimPaymentTx({
+      packageId: this.config.packageId,
+      taskId: params.taskId,
+      providerCardId: params.providerCardId,
+    });
+    const response = await this.suiClient.executeTransaction(tx, params.keypair);
+    return { txDigest: response.digest };
+  }
+
+  async cancelTask(params: {
+    taskId: string;
+    keypair: Signer;
+  }): Promise<{ txDigest: string }> {
+    const tx = buildCancelTaskTx({ packageId: this.config.packageId, taskId: params.taskId });
+    const response = await this.suiClient.executeTransaction(tx, params.keypair);
+    return { txDigest: response.digest };
+  }
+
+  async refundExpiredTask(params: {
+    taskId: string;
+    keypair: Signer;
+  }): Promise<{ txDigest: string }> {
+    const tx = buildRefundExpiredTaskTx({ packageId: this.config.packageId, taskId: params.taskId });
+    const response = await this.suiClient.executeTransaction(tx, params.keypair);
+    return { txDigest: response.digest };
+  }
+
+  async getTask(taskId: string): Promise<Task | null> {
+    try {
+      const object = await this.suiClient.getObject<Record<string, unknown>>(taskId);
+      return parseTaskFields(object, taskId);
+    } catch (error) {
+      if (isObjectMissingError(error)) {
+        return null;
+      }
+
+      throw error;
+    }
+  }
+
+  private async submitTaskCreation(tx: ReturnType<typeof buildPostTaskTx>, keypair: Signer): Promise<{ txDigest: string; taskId: string }> {
+    const response = await this.suiClient.executeTransaction(tx, keypair);
+    const taskId = extractObjectId(response.objectChanges, /::task::Task$/);
+
+    if (!taskId) {
+      logger.warn({ response }, 'Task posting succeeded without a Task object change.');
+      throw new Error('Unable to determine task id from transaction response.');
+    }
+
+    return { txDigest: response.digest, taskId };
+  }
+}
+
+function extractObjectId(
+  objectChanges: Array<Record<string, unknown>> | null | undefined,
+  objectTypePattern: RegExp,
+): string | undefined {
+  return objectChanges?.find(
+    (change) =>
+      (change.type === 'created' || change.type === 'mutated') &&
+      typeof change.objectType === 'string' &&
+      objectTypePattern.test(change.objectType) &&
+      typeof change.objectId === 'string',
+  )?.objectId as string | undefined;
+}
+
+function isObjectMissingError(error: unknown): boolean {
+  return error instanceof Error && /not found|does not contain move object data/i.test(error.message);
+}

package/src/task/index.ts

@@ -0,0 +1 @@
+export * from './client.js';

package/src/x402/client.ts

@@ -0,0 +1,295 @@
+import { encodePaymentSignatureHeader, decodePaymentRequiredHeader } from '@x402/core/http';
+import type { PaymentRequirements } from '@x402/core/types';
+import { ExactEvmScheme } from '@x402/evm/exact/client';
+import { getAddress, verifyTypedData } from 'viem';
+
+import { PERMIT2_ADDRESS, USDC_ADDRESS } from '../evm/constants.js';
+import type { EvmWallet } from '../evm/wallet.js';
+
+const X402_TYPED_DATA_TYPES = {
+  PaymentAuthorization: [
+    { name: 'payerAddress', type: 'address' },
+    { name: 'paymentAddress', type: 'address' },
+    { name: 'amount', type: 'uint256' },
+    { name: 'currency', type: 'string' },
+    { name: 'nonce', type: 'string' },
+    { name: 'expiresAt', type: 'uint256' },
+  ],
+} as const;
+
+type InternalX402PaymentRequest = X402PaymentRequest & {
+  __x402?: {
+    x402Version: number;
+    requirements: PaymentRequirements;
+  };
+};
+
+export interface X402PaymentRequest {
+  paymentAddress: string;
+  amount: string;
+  currency: string;
+  network: string;
+  nonce: string;
+  expiresAt: number;
+}
+
+export interface X402PaymentSignature {
+  signature: string;
+  payerAddress: string;
+  network: string;
+  nonce: string;
+}
+
+export class X402Client {
+  constructor(private readonly wallet: EvmWallet) {}
+
+  parse402Response(headers: Record<string, string>, body?: unknown): X402PaymentRequest {
+    const normalizedHeaders = normalizeHeaders(headers);
+    const paymentRequiredHeader = normalizedHeaders['payment-required'];
+
+    if (paymentRequiredHeader) {
+      const paymentRequired = decodePaymentRequiredHeader(paymentRequiredHeader);
+      const requirements = selectRequirement(paymentRequired.accepts, this.wallet.chain.id);
+      const request: InternalX402PaymentRequest = {
+        paymentAddress: requirements.payTo,
+        amount: requirements.amount,
+        currency: inferCurrency(requirements),
+        network: normalizeNetwork(requirements.network),
+        nonce: readString(requirements.extra?.nonce) ?? '',
+        expiresAt: readPositiveNumber(requirements.extra?.expiresAt) ?? Date.now() + requirements.maxTimeoutSeconds * 1_000,
+        __x402: {
+          x402Version: paymentRequired.x402Version,
+          requirements,
+        },
+      };
+
+      return request;
+    }
+
+    const payload = extractBodyPayload(body);
+    const paymentAddress = readString(payload.paymentAddress) ?? normalizedHeaders['payment-address'];
+    const amount = readString(payload.amount) ?? normalizedHeaders['payment-amount'];
+    const currency = readString(payload.currency) ?? normalizedHeaders['payment-currency'];
+    const network = readString(payload.network) ?? normalizedHeaders['payment-network'];
+    const nonce = readString(payload.nonce) ?? normalizedHeaders['payment-nonce'];
+    const expiresAt = readPositiveNumber(payload.expiresAt ?? normalizedHeaders['payment-expires-at']);
+
+    if (!paymentAddress || !amount || !currency || !network || !nonce || expiresAt === undefined) {
+      throw new Error('402 response did not contain a supported payment challenge.');
+    }
+
+    return {
+      paymentAddress,
+      amount,
+      currency,
+      network: normalizeNetwork(network),
+      nonce,
+      expiresAt,
+    };
+  }
+
+  async signPayment(request: X402PaymentRequest): Promise<X402PaymentSignature> {
+    assertNotExpired(request);
+    assertWalletMatchesNetwork(this.wallet.chain.id, request.network);
+
+    const signature = await this.wallet.signTypedData(buildTypedData(request, this.wallet.address));
+
+    return {
+      signature,
+      payerAddress: this.wallet.address,
+      network: normalizeNetwork(request.network),
+      nonce: request.nonce,
+    };
+  }
+
+  async createPaymentHeader(request: X402PaymentRequest): Promise<string> {
+    const internalRequest = request as InternalX402PaymentRequest;
+    if (internalRequest.__x402) {
+      const scheme = new ExactEvmScheme({
+        address: this.wallet.address as `0x${string}`,
+        signTypedData: (message) => this.wallet.signTypedData(message) as Promise<`0x${string}`>,
+        readContract: (args) => this.wallet.getPublicClient().readContract(args),
+      });
+      const { x402Version, requirements } = internalRequest.__x402;
+      const result = await scheme.createPaymentPayload(x402Version, requirements);
+
+      return encodePaymentSignatureHeader({
+        x402Version: result.x402Version,
+        accepted: requirements,
+        payload: result.payload,
+        extensions: result.extensions,
+      });
+    }
+
+    const signature = await this.signPayment(request);
+    return Buffer.from(JSON.stringify(signature)).toString('base64');
+  }
+
+  async verifyPayment(signature: X402PaymentSignature, request: X402PaymentRequest): Promise<boolean> {
+    if (Date.now() > request.expiresAt) {
+      return false;
+    }
+
+    if (normalizeNetwork(signature.network) !== normalizeNetwork(request.network) || signature.nonce !== request.nonce) {
+      return false;
+    }
+
+    try {
+      return await verifyTypedData({
+        address: normalizeAddress(signature.payerAddress),
+        ...buildTypedData(request, signature.payerAddress),
+        signature: signature.signature as `0x${string}`,
+      });
+    } catch {
+      return false;
+    }
+  }
+}
+
+function buildTypedData(request: X402PaymentRequest, payerAddress: string) {
+  return {
+    domain: {
+      name: 'AgenticMeshX402',
+      version: '1',
+      chainId: getChainId(request.network),
+      verifyingContract: normalizeAddress(request.paymentAddress),
+    },
+    types: X402_TYPED_DATA_TYPES,
+    primaryType: 'PaymentAuthorization' as const,
+    message: {
+      payerAddress: normalizeAddress(payerAddress),
+      paymentAddress: normalizeAddress(request.paymentAddress),
+      amount: BigInt(request.amount),
+      currency: request.currency,
+      nonce: request.nonce,
+      expiresAt: BigInt(request.expiresAt),
+    },
+  };
+}
+
+function normalizeHeaders(headers: Record<string, string>): Record<string, string> {
+  return Object.fromEntries(Object.entries(headers).map(([key, value]) => [key.toLowerCase(), value]));
+}
+
+function extractBodyPayload(body: unknown): Record<string, unknown> {
+  if (!body || typeof body !== 'object') {
+    return {};
+  }
+
+  const record = body as Record<string, unknown>;
+  if (record.payment && typeof record.payment === 'object') {
+    return record.payment as Record<string, unknown>;
+  }
+
+  if (record.paymentRequest && typeof record.paymentRequest === 'object') {
+    return record.paymentRequest as Record<string, unknown>;
+  }
+
+  return record;
+}
+
+function selectRequirement(
+  accepts: PaymentRequirements | PaymentRequirements[],
+  chainId: number,
+): PaymentRequirements {
+  const requirements = Array.isArray(accepts) ? accepts : [accepts];
+  const preferredNetwork = chainIdToNetwork(chainId);
+  return requirements.find((entry) => normalizeNetwork(entry.network) === preferredNetwork) ?? requirements[0]!;
+}
+
+function inferCurrency(requirements: PaymentRequirements): string {
+  const explicit = readString(requirements.extra?.currency) ?? readString(requirements.extra?.symbol);
+  if (explicit) {
+    return explicit.toUpperCase();
+  }
+
+  const network = normalizeNetwork(requirements.network);
+  const usdcAddress = network in USDC_ADDRESS ? USDC_ADDRESS[network as keyof typeof USDC_ADDRESS] : undefined;
+  if (usdcAddress && normalizeAddress(requirements.asset) === normalizeAddress(usdcAddress)) {
+    return 'USDC';
+  }
+
+  if (normalizeAddress(requirements.asset) === normalizeAddress(PERMIT2_ADDRESS)) {
+    return 'ETH';
+  }
+
+  return requirements.asset;
+}
+
+function normalizeNetwork(network: string): string {
+  const normalized = network.trim().toLowerCase();
+  switch (normalized) {
+    case 'base':
+    case 'eip155:8453':
+      return 'base';
+    case 'base-sepolia':
+    case 'eip155:84532':
+      return 'base-sepolia';
+    case 'localhost':
+    case 'anvil':
+    case 'eip155:31337':
+      return 'localhost';
+    default:
+      return normalized;
+  }
+}
+
+function chainIdToNetwork(chainId: number): string {
+  switch (chainId) {
+    case 8453:
+      return 'base';
+    case 84_532:
+      return 'base-sepolia';
+    case 31_337:
+      return 'localhost';
+    default:
+      return `eip155:${chainId}`;
+  }
+}
+
+function getChainId(network: string): number {
+  switch (normalizeNetwork(network)) {
+    case 'base':
+      return 8453;
+    case 'base-sepolia':
+      return 84_532;
+    case 'localhost':
+      return 31_337;
+    default:
+      throw new Error(`Unsupported x402 network: ${network}`);
+  }
+}
+
+function assertNotExpired(request: X402PaymentRequest): void {
+  if (Date.now() > request.expiresAt) {
+    throw new Error('Payment challenge has expired.');
+  }
+}
+
+function assertWalletMatchesNetwork(chainId: number, network: string): void {
+  const walletNetwork = chainIdToNetwork(chainId);
+  const requestNetwork = normalizeNetwork(network);
+  if (walletNetwork !== requestNetwork) {
+    throw new Error(`Wallet network ${walletNetwork} does not match payment network ${requestNetwork}.`);
+  }
+}
+
+function normalizeAddress(address: string): `0x${string}` {
+  return getAddress(address);
+}
+
+function readString(value: unknown): string | undefined {
+  return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+
+function readPositiveNumber(value: unknown): number | undefined {
+  if (typeof value === 'number' && Number.isFinite(value) && value >= 0) {
+    return value;
+  }
+
+  if (typeof value === 'string' && /^\d+$/.test(value.trim())) {
+    return Number(value.trim());
+  }
+
+  return undefined;
+}

package/src/x402/index.ts

@@ -0,0 +1 @@
+export * from './client.js';

package/tests/auth/device-flow.test.ts

@@ -0,0 +1,62 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { pollDeviceFlow, startDeviceFlow } from '../../src/auth/device-flow.js';
+import type { OAuthConfig } from '../../src/auth/types.js';
+
+const config: OAuthConfig = {
+  provider: 'google',
+  clientId: 'test-client',
+  redirectUri: 'http://127.0.0.1/callback',
+  deviceCodeEndpoint: 'https://oidc.example/device',
+  tokenEndpoint: 'https://oidc.example/token',
+};
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  vi.restoreAllMocks();
+});
+
+describe('device flow', () => {
+  it('starts the device authorization flow', async () => {
+    const fetchMock = vi.fn().mockResolvedValue(
+      new Response(
+        JSON.stringify({
+          user_code: 'ABCD-EFGH',
+          verification_uri: 'https://oidc.example/verify',
+          device_code: 'device-code',
+          interval: 3,
+          expires_in: 900,
+        }),
+      ),
+    );
+    vi.stubGlobal('fetch', fetchMock);
+
+    const result = await startDeviceFlow(config);
+
+    expect(result).toEqual({
+      userCode: 'ABCD-EFGH',
+      verificationUri: 'https://oidc.example/verify',
+      deviceCode: 'device-code',
+      pollInterval: 3,
+      expiresIn: 900,
+    });
+  });
+
+  it('returns null while authorization is pending and then returns tokens', async () => {
+    const fetchMock = vi
+      .fn()
+      .mockResolvedValueOnce(
+        new Response(JSON.stringify({ error: 'authorization_pending' }), { status: 400 }),
+      )
+      .mockResolvedValueOnce(
+        new Response(JSON.stringify({ id_token: 'jwt-token', refresh_token: 'refresh-token' })),
+      );
+    vi.stubGlobal('fetch', fetchMock);
+
+    expect(await pollDeviceFlow('device-code', config)).toBeNull();
+    await expect(pollDeviceFlow('device-code', config)).resolves.toEqual({
+      jwt: 'jwt-token',
+      refreshToken: 'refresh-token',
+    });
+  });
+});

package/tests/auth/ed25519-provider.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'vitest';
+
+import { Ed25519AuthProvider } from '../../src/auth/ed25519-provider.js';
+import { createDID } from '../../src/identity/did.js';
+import { Ed25519Keypair } from '@mysten/sui/keypairs/ed25519';
+
+describe('Ed25519AuthProvider', () => {
+  it('wraps an Ed25519 keypair as an auth provider', async () => {
+    const keypair = Ed25519Keypair.generate();
+    const provider = new Ed25519AuthProvider(keypair);
+
+    expect(await provider.getAddress()).toBe(keypair.toSuiAddress());
+    expect(provider.getDID()).toBe(createDID(keypair.getPublicKey().toRawBytes()));
+    expect(provider.isAuthenticated()).toBe(true);
+    expect(provider.getPublicKey()).toEqual(keypair.getPublicKey().toRawBytes());
+
+    const signedTransaction = await provider.signTransaction(new Uint8Array([1, 2, 3]));
+    const signedMessage = await provider.signPersonalMessage(new Uint8Array([4, 5, 6]));
+
+    expect(signedTransaction.length).toBeGreaterThan(0);
+    expect(signedMessage.signature.length).toBeGreaterThan(0);
+    expect(provider.toSuiSigner().toSuiAddress()).toBe(await provider.getAddress());
+  });
+});

package/tests/auth/evm-key.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, it } from 'vitest';
+
+import { deriveEvmKey } from '../../src/auth/evm-key.js';
+
+describe('deriveEvmKey', () => {
+  it('derives the same key for the same inputs', () => {
+    const first = deriveEvmKey(new Uint8Array([1, 2, 3, 4]), 'salt-1', 'user-1');
+    const second = deriveEvmKey(new Uint8Array([1, 2, 3, 4]), 'salt-1', 'user-1');
+
+    expect(Buffer.from(first).toString('hex')).toBe(Buffer.from(second).toString('hex'));
+    expect(first).toHaveLength(32);
+  });
+
+  it('changes when any input changes, even for concatenation-collision cases', () => {
+    const base = Buffer.from(deriveEvmKey(new Uint8Array([1, 2, 3, 4]), 'salt-1', 'user-1')).toString('hex');
+    const differentSalt = Buffer.from(deriveEvmKey(new Uint8Array([1, 2, 3, 4]), 'salt-2', 'user-1')).toString('hex');
+    const differentSub = Buffer.from(deriveEvmKey(new Uint8Array([1, 2, 3, 4]), 'salt-1', 'user-2')).toString('hex');
+    const collisionA = Buffer.from(deriveEvmKey(new Uint8Array([1, 2, 3, 4]), 'ab', 'c')).toString('hex');
+    const collisionB = Buffer.from(deriveEvmKey(new Uint8Array([1, 2, 3, 4]), 'a', 'bc')).toString('hex');
+
+    expect(differentSalt).not.toBe(base);
+    expect(differentSub).not.toBe(base);
+    expect(collisionA).not.toBe(collisionB);
+  });
+
+  it('rejects empty inputs', () => {
+    expect(() => deriveEvmKey(new Uint8Array(), 'salt-1', 'user-1')).toThrow('identityPrivateKey must not be empty.');
+    expect(() => deriveEvmKey(new Uint8Array([1]), '   ', 'user-1')).toThrow('userSalt must not be empty.');
+    expect(() => deriveEvmKey(new Uint8Array([1]), 'salt-1', '   ')).toThrow('oauthSub must not be empty.');
+  });
+});