@hivemind-os/collective-core 0.2.0

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@hivemind-os/collective-core",
+  "version": "0.2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "dependencies": {
+    "@mysten/sui": "^1.30.0",
+    "@noble/ciphers": "^1.3.0",
+    "@noble/curves": "^2.2.0",
+    "@noble/ed25519": "^2.0.0",
+    "@noble/hashes": "^1.4.0",
+    "@x402/core": "^2.12.0",
+    "@x402/evm": "^2.12.0",
+    "better-sqlite3": "^11.0.0",
+    "bs58": "^6.0.0",
+    "pino": "^9.0.0",
+    "viem": "^2.48.11",
+    "@hivemind-os/collective-types": "0.2.0"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "optionalDependencies": {
+    "keytar": "^7.9.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest",
+    "lint": "eslint src/ tests/ vitest.config.ts"
+  }
+}

package/src/auth/device-flow.ts

@@ -0,0 +1,108 @@
+import type { DeviceFlowStatus, OAuthConfig } from './types.js';
+
+const DEFAULT_ENDPOINTS = {
+  google: {
+    deviceCodeEndpoint: 'https://oauth2.googleapis.com/device/code',
+    tokenEndpoint: 'https://oauth2.googleapis.com/token',
+  },
+  apple: {
+    deviceCodeEndpoint: '',
+    tokenEndpoint: 'https://appleid.apple.com/auth/token',
+  },
+} as const;
+
+export async function startDeviceFlow(config: OAuthConfig): Promise<DeviceFlowStatus> {
+  const endpoint = config.deviceCodeEndpoint ?? DEFAULT_ENDPOINTS[config.provider].deviceCodeEndpoint;
+  if (!endpoint) {
+    throw new Error(`Device authorization is not configured for provider ${config.provider}.`);
+  }
+
+  const response = await fetch(endpoint, {
+    method: 'POST',
+    headers: {
+      'content-type': 'application/x-www-form-urlencoded',
+    },
+    body: new URLSearchParams({
+      client_id: config.clientId,
+      scope: (config.scopes ?? ['openid', 'email']).join(' '),
+    }).toString(),
+  });
+
+  const payload = (await response.json()) as Record<string, unknown>;
+  if (!response.ok) {
+    throw new Error(readOAuthError(payload, response.status));
+  }
+
+  const userCode = readRequiredString(payload.user_code, 'user_code');
+  const verificationUri =
+    readOptionalString(payload.verification_uri) ?? readRequiredString(payload.verification_url, 'verification_url');
+
+  return {
+    userCode,
+    verificationUri,
+    deviceCode: readRequiredString(payload.device_code, 'device_code'),
+    pollInterval: readOptionalNumber(payload.interval) ?? 5,
+    expiresIn: readOptionalNumber(payload.expires_in) ?? 600,
+  };
+}
+
+export async function pollDeviceFlow(
+  deviceCode: string,
+  config: OAuthConfig,
+): Promise<{
+  jwt: string;
+  refreshToken?: string;
+} | null> {
+  const endpoint = config.tokenEndpoint ?? DEFAULT_ENDPOINTS[config.provider].tokenEndpoint;
+  if (!endpoint) {
+    throw new Error(`Token polling is not configured for provider ${config.provider}.`);
+  }
+
+  const response = await fetch(endpoint, {
+    method: 'POST',
+    headers: {
+      'content-type': 'application/x-www-form-urlencoded',
+    },
+    body: new URLSearchParams({
+      client_id: config.clientId,
+      device_code: deviceCode,
+      grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
+    }).toString(),
+  });
+
+  const payload = (await response.json()) as Record<string, unknown>;
+  if (!response.ok) {
+    const code = readOptionalString(payload.error);
+    if (code === 'authorization_pending' || code === 'slow_down') {
+      return null;
+    }
+
+    throw new Error(readOAuthError(payload, response.status));
+  }
+
+  return {
+    jwt: readRequiredString(payload.id_token, 'id_token'),
+    refreshToken: readOptionalString(payload.refresh_token),
+  };
+}
+
+function readRequiredString(value: unknown, field: string): string {
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new Error(`OAuth response is missing ${field}.`);
+  }
+
+  return value;
+}
+
+function readOptionalString(value: unknown): string | undefined {
+  return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+
+function readOptionalNumber(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+
+function readOAuthError(payload: Record<string, unknown>, status: number): string {
+  const message = readOptionalString(payload.error_description) ?? readOptionalString(payload.error) ?? 'OAuth request failed';
+  return `${message} (${status})`;
+}

package/src/auth/ed25519-provider.ts

@@ -0,0 +1,43 @@
+import { Ed25519Keypair } from '@mysten/sui/keypairs/ed25519';
+
+import { createDID } from '../identity/did.js';
+
+import type { AuthProvider } from './types.js';
+
+const encoder = new TextEncoder();
+
+export class Ed25519AuthProvider implements AuthProvider {
+  readonly mode = 'ed25519' as const;
+
+  constructor(private readonly keypair: Ed25519Keypair) {}
+
+  async getAddress(): Promise<string> {
+    return this.keypair.toSuiAddress();
+  }
+
+  getDID(): string {
+    return createDID(this.keypair.getPublicKey().toRawBytes());
+  }
+
+  async signTransaction(tx: Uint8Array): Promise<Uint8Array> {
+    const { signature } = await this.keypair.signTransaction(tx);
+    return encoder.encode(signature);
+  }
+
+  async signPersonalMessage(message: Uint8Array): Promise<{ signature: Uint8Array }> {
+    const { signature } = await this.keypair.signPersonalMessage(message);
+    return { signature: encoder.encode(signature) };
+  }
+
+  isAuthenticated(): boolean {
+    return true;
+  }
+
+  getPublicKey(): Uint8Array {
+    return this.keypair.getPublicKey().toRawBytes();
+  }
+
+  toSuiSigner(): Ed25519Keypair {
+    return this.keypair;
+  }
+}

package/src/auth/errors.ts

@@ -0,0 +1,82 @@
+import { SessionState } from './session-state.js';
+import type { StoredZkLoginSession } from './types.js';
+
+interface SessionContext {
+  address: string;
+  iss: string;
+  maxEpoch: number;
+  updatedAt: number;
+}
+
+function toSessionContext(session?: StoredZkLoginSession | null): SessionContext | undefined {
+  if (!session) {
+    return undefined;
+  }
+
+  return {
+    address: session.address,
+    iss: session.iss,
+    maxEpoch: session.maxEpoch,
+    updatedAt: session.updatedAt,
+  };
+}
+
+export interface SessionRefreshErrorOptions {
+  attempts: number;
+  maxAttempts: number;
+  retryDelaysMs: readonly number[];
+  consecutiveFailures: number;
+  sessionState: SessionState;
+  session?: StoredZkLoginSession | null;
+  cause?: unknown;
+}
+
+export class SessionRefreshError extends Error {
+  readonly attempts: number;
+  readonly maxAttempts: number;
+  readonly retryDelaysMs: readonly number[];
+  readonly consecutiveFailures: number;
+  readonly sessionState: SessionState;
+  readonly session?: SessionContext;
+
+  constructor(message: string, options: SessionRefreshErrorOptions) {
+    super(message, { cause: options.cause });
+    this.name = 'SessionRefreshError';
+    this.attempts = options.attempts;
+    this.maxAttempts = options.maxAttempts;
+    this.retryDelaysMs = options.retryDelaysMs;
+    this.consecutiveFailures = options.consecutiveFailures;
+    this.sessionState = options.sessionState;
+    this.session = toSessionContext(options.session);
+  }
+}
+
+export interface SessionExpiredErrorOptions {
+  attempts?: number;
+  maxAttempts?: number;
+  retryDelaysMs?: readonly number[];
+  consecutiveFailures?: number;
+  sessionState?: SessionState;
+  session?: StoredZkLoginSession | null;
+  cause?: unknown;
+}
+
+export class SessionExpiredError extends Error {
+  readonly attempts?: number;
+  readonly maxAttempts?: number;
+  readonly retryDelaysMs?: readonly number[];
+  readonly consecutiveFailures?: number;
+  readonly sessionState: SessionState;
+  readonly session?: SessionContext;
+
+  constructor(message: string, options: SessionExpiredErrorOptions = {}) {
+    super(message, { cause: options.cause });
+    this.name = 'SessionExpiredError';
+    this.attempts = options.attempts;
+    this.maxAttempts = options.maxAttempts;
+    this.retryDelaysMs = options.retryDelaysMs;
+    this.consecutiveFailures = options.consecutiveFailures;
+    this.sessionState = options.sessionState ?? SessionState.NEEDS_REAUTH;
+    this.session = toSessionContext(options.session);
+  }
+}

package/src/auth/evm-key.ts

@@ -0,0 +1,55 @@
+import { hkdf } from '@noble/hashes/hkdf';
+import { sha256 } from '@noble/hashes/sha256';
+
+const DERIVED_KEY_LENGTH = 32;
+const encoder = new TextEncoder();
+
+export function deriveEvmKey(identityPrivateKey: Uint8Array, userSalt: string, oauthSub: string): Uint8Array {
+  if (identityPrivateKey.byteLength === 0) {
+    throw new Error('identityPrivateKey must not be empty.');
+  }
+
+  const normalizedUserSalt = normalizeRequiredString(userSalt, 'userSalt');
+  const normalizedOauthSub = normalizeRequiredString(oauthSub, 'oauthSub');
+
+  return hkdf(
+    sha256,
+    identityPrivateKey,
+    buildDerivationSalt(normalizedUserSalt, normalizedOauthSub),
+    encoder.encode('agentic-mesh:evm:v1'),
+    DERIVED_KEY_LENGTH,
+  );
+}
+
+function normalizeRequiredString(value: string, field: string): string {
+  const normalized = value.trim();
+  if (!normalized) {
+    throw new Error(`${field} must not be empty.`);
+  }
+
+  return normalized;
+}
+
+function buildDerivationSalt(userSalt: string, oauthSub: string): Uint8Array {
+  return sha256(concatBytes(encodeLengthPrefixed(userSalt), encodeLengthPrefixed(oauthSub)));
+}
+
+function encodeLengthPrefixed(value: string): Uint8Array {
+  const encodedValue = encoder.encode(value);
+  const lengthPrefix = new Uint8Array(4);
+  new DataView(lengthPrefix.buffer).setUint32(0, encodedValue.length, false);
+  return concatBytes(lengthPrefix, encodedValue);
+}
+
+function concatBytes(...parts: Uint8Array[]): Uint8Array {
+  const totalLength = parts.reduce((sum, part) => sum + part.byteLength, 0);
+  const result = new Uint8Array(totalLength);
+  let offset = 0;
+
+  for (const part of parts) {
+    result.set(part, offset);
+    offset += part.byteLength;
+  }
+
+  return result;
+}

package/src/auth/index.ts

@@ -0,0 +1,8 @@
+export * from './types.js';
+export * from './session-state.js';
+export * from './errors.js';
+export * from './ed25519-provider.js';
+export * from './zklogin-provider.js';
+export * from './session-store.js';
+export * from './device-flow.js';
+export * from './evm-key.js';

package/src/auth/session-state.ts

@@ -0,0 +1,25 @@
+import type { StoredZkLoginSession } from './types.js';
+
+export enum SessionState {
+  VALID = 'valid',
+  REFRESHING = 'refreshing',
+  NEEDS_REAUTH = 'needs_reauth',
+  EXPIRED = 'expired',
+}
+
+export interface SessionRefreshPolicy {
+  maxAttempts?: number;
+  backoffMs?: readonly number[];
+  maxConsecutiveFailures?: number;
+}
+
+export interface SessionStateChangeEvent {
+  previousState: SessionState;
+  currentState: SessionState;
+  session: StoredZkLoginSession | null;
+  reason?: string;
+  refreshFailureCount: number;
+  error?: unknown;
+}
+
+export type SessionStateChangeCallback = (event: SessionStateChangeEvent) => void;