@evomap/evolver-adapter-public 2.0.0-beta.0

package/dist/antiAbuseTelemetry.d.ts

@@ -0,0 +1,36 @@
+import { bootstrap } from '@evomap/evolver-core';
+export declare const ANTI_ABUSE_SCHEMA_VERSION = "anti_abuse.v1";
+export declare const ANTI_ABUSE_REDACTION_VERSION = "anti_abuse_redaction.v1";
+export declare const DEFAULT_ANTI_ABUSE_TTL_DAYS = 90;
+export declare const MAX_INTEGRITY_FILE_BYTES: number;
+export type AntiAbuseTelemetryMode = 'heartbeat' | 'off';
+export interface AntiAbuseTelemetryOptions {
+    env?: NodeJS.ProcessEnv | Record<string, string | undefined>;
+    envFingerprint?: bootstrap.EnvFingerprint;
+    now?: Date | string;
+    packageRoot?: string;
+    proxyPortConfigured?: boolean;
+    salt?: string;
+    saltId?: string | null;
+    source?: string;
+    nodeId?: string;
+    evolverVersion?: string;
+    taskMeta?: Record<string, unknown>;
+    workspaceId?: string;
+}
+export interface IntegrityHashes {
+    package_json_hash: string | null;
+    cli_entry_hash: string | null;
+    lockfile_hashes: Record<string, string>;
+}
+export declare function antiAbuseTelemetryMode(env?: NodeJS.ProcessEnv | Record<string, string | undefined>): AntiAbuseTelemetryMode;
+export declare function hmacPseudonym(value: unknown, opts?: {
+    salt?: string;
+    purpose?: string;
+}): string | null;
+export declare function antiAbuseEnvFingerprintKey(fp: bootstrap.EnvFingerprint): string;
+export declare function resolveAdapterPackageRoot(startDir?: string): string;
+export declare function resolveWorkspaceRoot(startDir?: string): string;
+export declare function resolveCliPackageRoot(packageRoot?: string, workspaceRoot?: string): string | null;
+export declare function collectIntegrityHashes(packageRoot?: string): IntegrityHashes;
+export declare function buildHeartbeatAntiAbuseTelemetry(opts?: AntiAbuseTelemetryOptions): Record<string, unknown>;

package/dist/antiAbuseTelemetry.js

@@ -0,0 +1,267 @@
+import { createHash, createHmac } from 'node:crypto';
+import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { bootstrap } from '@evomap/evolver-core';
+export const ANTI_ABUSE_SCHEMA_VERSION = 'anti_abuse.v1';
+export const ANTI_ABUSE_REDACTION_VERSION = 'anti_abuse_redaction.v1';
+export const DEFAULT_ANTI_ABUSE_TTL_DAYS = 90;
+export const MAX_INTEGRITY_FILE_BYTES = 10 * 1024 * 1024;
+export function antiAbuseTelemetryMode(env = process.env) {
+    const raw = env['EVOLVER_ANTI_ABUSE_TELEMETRY'];
+    const v = String(raw ?? '').trim().toLowerCase();
+    if (v.length === 0)
+        return 'heartbeat';
+    if (v === '0' || v === 'false' || v === 'no' || v === 'off')
+        return 'off';
+    if (v === '1' || v === 'true' || v === 'yes' || v === 'on' || v === 'heartbeat')
+        return 'heartbeat';
+    return 'off';
+}
+export function hmacPseudonym(value, opts = {}) {
+    const raw = value == null ? '' : String(value);
+    const salt = opts.salt ? String(opts.salt) : '';
+    const purpose = opts.purpose ? String(opts.purpose) : 'anti_abuse';
+    if (!raw || !salt)
+        return null;
+    return createHmac('sha256', salt).update(purpose).update('\0').update(raw).digest('hex').slice(0, 32);
+}
+export function antiAbuseEnvFingerprintKey(fp) {
+    const nodeMajor = (fp.node_version || '').replace(/^v/, '').split('.')[0] ?? '';
+    return [fp.platform, fp.arch, `node${nodeMajor}`, fp.region ?? '', fp.container ? 'container' : 'host'].join('|');
+}
+export function resolveAdapterPackageRoot(startDir = dirname(fileURLToPath(import.meta.url))) {
+    let dir = startDir;
+    for (let i = 0; i < 8; i++) {
+        try {
+            const pkg = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'));
+            if (pkg.name === '@evomap/evolver-adapter-public')
+                return dir;
+        }
+        catch {
+            // Source and built layouts place package.json at different depths.
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return startDir;
+}
+export function resolveWorkspaceRoot(startDir = resolveAdapterPackageRoot()) {
+    let dir = startDir;
+    for (let i = 0; i < 12; i++) {
+        if (existsSync(join(dir, 'pnpm-workspace.yaml')) || existsSync(join(dir, 'pnpm-lock.yaml')))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return startDir;
+}
+export function resolveCliPackageRoot(packageRoot = resolveAdapterPackageRoot(), workspaceRoot = resolveWorkspaceRoot(packageRoot)) {
+    const candidates = [
+        join(workspaceRoot, 'packages', 'evolver-cli'),
+        join(workspaceRoot, 'node_modules', '@evomap', 'evolver-cli'),
+        join(dirname(packageRoot), 'evolver-cli'),
+    ];
+    for (const candidate of candidates) {
+        const pkgPath = containedRealPath(candidate, join(candidate, 'package.json'));
+        const pkg = pkgPath ? safeJsonFile(pkgPath) : {};
+        if (pkg.name === '@evomap/evolver-cli')
+            return candidate;
+    }
+    return null;
+}
+export function collectIntegrityHashes(packageRoot = resolveAdapterPackageRoot()) {
+    const pkgPath = containedRealPath(packageRoot, join(packageRoot, 'package.json'));
+    const workspaceRoot = resolveWorkspaceRoot(packageRoot);
+    const cliRoot = resolveCliPackageRoot(packageRoot, workspaceRoot);
+    const cliPkgPath = cliRoot ? containedRealPath(cliRoot, join(cliRoot, 'package.json')) : null;
+    const cliPkg = cliPkgPath ? safeJsonFile(cliPkgPath) : {};
+    const bin = typeof cliPkg.bin === 'object' && cliPkg.bin && typeof cliPkg.bin['evolver'] === 'string' ? cliPkg.bin['evolver'] : null;
+    const binPath = bin && cliRoot ? containedRealPath(cliRoot, resolve(cliRoot, bin)) : null;
+    const lockfileHashes = {};
+    for (const name of ['package-lock.json', 'pnpm-lock.yaml', 'yarn.lock', 'bun.lockb']) {
+        const p = containedRealPath(workspaceRoot, join(workspaceRoot, name));
+        const digest = p ? sha256File(p) : null;
+        if (digest)
+            lockfileHashes[name] = digest;
+    }
+    return {
+        package_json_hash: pkgPath ? sha256File(pkgPath) : null,
+        cli_entry_hash: binPath ? sha256File(binPath) : null,
+        lockfile_hashes: lockfileHashes,
+    };
+}
+export function buildHeartbeatAntiAbuseTelemetry(opts = {}) {
+    const env = opts.env ?? process.env;
+    const fp = opts.envFingerprint ?? bootstrap.captureEnvFingerprint({ env });
+    const salt = opts.salt ?? env['EVOLVER_ANTI_ABUSE_SALT'];
+    const saltId = opts.saltId ?? env['EVOLVER_ANTI_ABUSE_SALT_ID'] ?? (salt ? 'env' : null);
+    const pseudonymStatus = salt ? 'salt_configured' : 'salt_missing';
+    const devicePseudonym = hmacPseudonym(fp.device, { salt, purpose: 'device' });
+    const workspacePseudonym = hmacPseudonym(opts.workspaceId ?? process.cwd(), { salt, purpose: 'workspace' });
+    const unavailableFields = [
+        ...(devicePseudonym ? [] : [unavailable('device_pseudonym', 'anti_abuse_salt_missing', 'signed_policy_or_env')]),
+        ...(workspacePseudonym ? [] : [unavailable('workspace_pseudonym', 'anti_abuse_salt_missing', 'signed_policy_or_env')]),
+        unavailable('client_ip', 'server_observed_required', 'hub_edge'),
+        unavailable('asn', 'server_observed_required', 'hub_edge'),
+        unavailable('proxy_vpn_tor_datacenter_class', 'server_observed_required', 'hub_edge'),
+        unavailable('account_security', 'account_service_required', 'hub_account'),
+        unavailable('payout_method_token', 'payments_service_required', 'hub_payments'),
+        unavailable('risk_action_case', 'risk_engine_required', 'hub_risk'),
+    ];
+    return {
+        schema_version: ANTI_ABUSE_SCHEMA_VERSION,
+        event_type: 'node.heartbeat',
+        purpose: 'anti_abuse',
+        pii_class: 'medium',
+        consent_level: 'default',
+        retention_ttl_days: ttlDays(env),
+        policy_version: env['EVOLVER_ANTI_ABUSE_POLICY_VERSION'] ?? 'local-default',
+        redaction_version: ANTI_ABUSE_REDACTION_VERSION,
+        source: opts.source ?? 'evolver-client',
+        generated_at: nowIso(opts.now),
+        source_confidence: {
+            node_identity: 'client_attested',
+            device_integrity: 'client_attested',
+            task_metrics: 'client_attested',
+            network_source: 'server_observed_required',
+            account_security: 'server_observed_required',
+            payout: 'server_observed_required',
+            risk_decision: 'server_observed_required',
+        },
+        identity: {
+            node_id: opts.nodeId ?? null,
+            account_id: null,
+            org_id: null,
+        },
+        device: {
+            device_pseudonym: devicePseudonym,
+            workspace_pseudonym: workspacePseudonym,
+            pseudonym_salt_id: saltId,
+            pseudonym_status: pseudonymStatus,
+            ...(pseudonymStatus === 'salt_missing' ? { pseudonym_warning: 'anti_abuse_salt_missing' } : {}),
+            env_fingerprint_key: antiAbuseEnvFingerprintKey(fp),
+            platform: fp.platform,
+            arch: fp.arch,
+            os_release: fp.os_release,
+            node_version: fp.node_version,
+            // Underlying LLM model, BEST-EFFORT from this node's OWN env (detectModelName() → 'unknown' fallback).
+            // Anti-sybil clustering signal (v1 PR #174). Deliberately env-only: the long-lived evolver-proxy daemon and
+            // the standalone evolver-llm-proxy are SEPARATE processes by design (the LLM proxy must not require a hub
+            // credential), so the heartbeat can't see the per-request model the LLM proxy observes — piping it across
+            // would re-couple the two binaries. Consequence: a proxy daemon whose env lacks a model var emits 'unknown'
+            // here (honest, never fabricated). To populate it, set EVOLVER_MODEL_NAME in the daemon's environment. The
+            // AUTHORITATIVE per-asset model lives on the capsule (threaded from input.model), so 'unknown' on a heartbeat
+            // is "this node didn't say", never a contradiction of a capsule's real model.
+            model: fp.model,
+            evolver_version: opts.evolverVersion ?? null,
+            client: '@evomap/evolver-adapter-public',
+            client_version: null,
+            region: fp.region ?? null,
+            container: fp.container,
+        },
+        integrity: collectIntegrityHashes(opts.packageRoot),
+        local_security_boundary: {
+            proxy_bind_address_class: 'loopback',
+            proxy_port_configured: opts.proxyPortConfigured != null
+                ? Boolean(opts.proxyPortConfigured)
+                : boolFromEnv(env['EVOMAP_PROXY']) || Boolean(env['EVOMAP_PROXY_PORT']),
+            settings_permission_class: settingsPermissionClass(env),
+        },
+        task_timing: normalizeTaskMetrics(opts.taskMeta),
+        unavailable_fields: unavailableFields,
+    };
+}
+function containedRealPath(root, candidate) {
+    try {
+        const realRoot = realpathSync(root);
+        const real = realpathSync(candidate);
+        return real.startsWith(realRoot + sep) ? real : null;
+    }
+    catch {
+        return null;
+    }
+}
+function sha256File(filePath) {
+    try {
+        const st = statSync(filePath);
+        if (!st.isFile() || st.size > MAX_INTEGRITY_FILE_BYTES)
+            return null;
+        return createHash('sha256').update(readFileSync(filePath)).digest('hex');
+    }
+    catch {
+        return null;
+    }
+}
+function safeJsonFile(filePath) {
+    try {
+        return JSON.parse(readFileSync(filePath, 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+function nowIso(now) {
+    if (now instanceof Date)
+        return now.toISOString();
+    if (typeof now === 'string' && now.length > 0)
+        return now;
+    return new Date().toISOString();
+}
+function boolFromEnv(value) {
+    const v = String(value ?? '').trim().toLowerCase();
+    return v === '1' || v === 'true' || v === 'yes' || v === 'on';
+}
+function ttlDays(env) {
+    const raw = Number(env['EVOLVER_ANTI_ABUSE_TTL_DAYS']);
+    return Number.isFinite(raw) && raw > 0 ? Math.floor(raw) : DEFAULT_ANTI_ABUSE_TTL_DAYS;
+}
+function settingsPermissionClass(env) {
+    const settingsDir = env['EVOLVER_SETTINGS_DIR']
+        ?? env['EVOMAP_DIR']
+        ?? env['EVOLVER_HOME']
+        ?? env['EVOMAP_HOME']
+        ?? join(homedir(), '.evomap');
+    return filePermissionClass(join(settingsDir, 'settings.json'));
+}
+function filePermissionClass(filePath) {
+    try {
+        const st = statSync(filePath);
+        if (!st.isFile())
+            return 'not_file';
+        const mode = st.mode & 0o777;
+        if ((mode & 0o077) === 0)
+            return 'owner_only';
+        if ((mode & 0o007) !== 0)
+            return 'world_accessible';
+        return 'group_accessible';
+    }
+    catch {
+        return existsSync(filePath) ? 'unreadable' : 'missing';
+    }
+}
+function normalizeTaskMetrics(taskMeta) {
+    const metrics = taskMeta?.['task_metrics'];
+    if (!metrics || typeof metrics !== 'object')
+        return null;
+    const m = metrics;
+    return {
+        pending: finiteNumberOrNull(m['pending']),
+        claimed: finiteNumberOrNull(m['claimed']),
+        completed: finiteNumberOrNull(m['completed']),
+        failed: finiteNumberOrNull(m['failed']),
+        avg_completion_ms: finiteNumberOrNull(m['avg_completion_ms']),
+    };
+}
+function finiteNumberOrNull(value) {
+    const n = Number(value);
+    return Number.isFinite(n) ? n : null;
+}
+function unavailable(field, reason, expectedSource) {
+    return { field, reason, expected_source: expectedSource };
+}

package/dist/atp.d.ts

@@ -0,0 +1,54 @@
+import type { hub } from '@evomap/evolver-core';
+import { ATP_EXECUTION_MODES, ATP_PROOF_STATUSES, ATP_ROLES, ATP_ROUTING_MODES, ATP_VERIFY_ACTIONS, ATP_VERIFY_MODES } from '@evomap/atp-sdk';
+import { type FetchLike } from './hubFetch.js';
+export { ATP_EXECUTION_MODES, ATP_PROOF_STATUSES, ATP_ROLES, ATP_ROUTING_MODES, ATP_VERIFY_ACTIONS, ATP_VERIFY_MODES, };
+export type AtpVerifyMode = (typeof ATP_VERIFY_MODES)[number];
+export type AtpVerifyAction = (typeof ATP_VERIFY_ACTIONS)[number];
+export type AtpRoutingMode = (typeof ATP_ROUTING_MODES)[number];
+export type AtpProofStatus = (typeof ATP_PROOF_STATUSES)[number];
+export type AtpRole = (typeof ATP_ROLES)[number];
+export type AtpExecutionMode = (typeof ATP_EXECUTION_MODES)[number];
+export interface AtpResult<T = unknown> {
+    ok: boolean;
+    data?: T;
+    error?: string;
+    status?: number;
+}
+export interface AtpOrderOptions {
+    capabilities: readonly string[];
+    budget?: number;
+    routingMode?: AtpRoutingMode | string;
+    verifyMode?: AtpVerifyMode | string;
+    question?: string;
+    signals?: readonly string[];
+    minReputation?: number;
+}
+export interface AtpListProofsOptions {
+    nodeId?: string;
+    role?: AtpRole | string;
+    status?: AtpProofStatus | string;
+    limit?: number;
+}
+export interface AtpClientOptions {
+    baseUrl: string;
+    auth: hub.AuthProvider;
+    fetchFn: FetchLike;
+    senderId: () => string | undefined;
+}
+export declare class AtpHubClient {
+    private readonly opts;
+    private readonly http;
+    constructor(opts: AtpClientOptions);
+    placeOrder<T = unknown>(opts: AtpOrderOptions): Promise<AtpResult<T>>;
+    submitDelivery<T = unknown>(orderId: string, proofPayload?: unknown): Promise<AtpResult<T>>;
+    verifyDelivery<T = unknown>(orderId: string, action?: AtpVerifyAction | string): Promise<AtpResult<T>>;
+    settleOrder<T = unknown>(orderId: string): Promise<AtpResult<T>>;
+    disputeOrder<T = unknown>(orderId: string, reason: string): Promise<AtpResult<T>>;
+    getMerchantTier<T = unknown>(nodeId?: string): Promise<AtpResult<T>>;
+    getOrderStatus<T = unknown>(orderId: string): Promise<AtpResult<T>>;
+    listProofs<T = unknown>(opts?: AtpListProofsOptions): Promise<AtpResult<T>>;
+    getAtpPolicy<T = unknown>(): Promise<AtpResult<T>>;
+    listMyTasks<T = unknown>(limit?: number, nodeId?: string): Promise<AtpResult<T>>;
+    private callResult;
+}
+export declare function normalizeAtpResult<T = unknown>(raw: unknown): AtpResult<T>;

package/dist/atp.js

@@ -0,0 +1,140 @@
+import { ATP_EXECUTION_MODES, ATP_PROOF_STATUSES, ATP_ROLES, ATP_ROUTING_MODES, ATP_VERIFY_ACTIONS, ATP_VERIFY_MODES, } from '@evomap/atp-sdk';
+import { HubClientError, HubFetch } from './hubFetch.js';
+export { ATP_EXECUTION_MODES, ATP_PROOF_STATUSES, ATP_ROLES, ATP_ROUTING_MODES, ATP_VERIFY_ACTIONS, ATP_VERIFY_MODES, };
+export class AtpHubClient {
+    opts;
+    http;
+    constructor(opts) {
+        this.opts = opts;
+        this.http = new HubFetch({ baseUrl: opts.baseUrl, auth: opts.auth, fetchFn: opts.fetchFn, senderId: opts.senderId });
+    }
+    async placeOrder(opts) {
+        const capabilities = opts.capabilities.map((s) => String(s).trim()).filter(Boolean);
+        if (capabilities.length === 0)
+            throw new Error('ATP order requires at least one capability');
+        const body = {
+            capabilities,
+            budget: clampBudget(opts.budget),
+            routing_mode: enumValue(opts.routingMode ?? 'fastest', ATP_ROUTING_MODES, 'routingMode'),
+            verify_mode: enumValue(opts.verifyMode ?? 'auto', ATP_VERIFY_MODES, 'verifyMode'),
+        };
+        if (opts.question !== undefined)
+            body['question'] = opts.question;
+        if (opts.signals !== undefined)
+            body['signals'] = opts.signals;
+        if (opts.minReputation !== undefined)
+            body['min_reputation'] = opts.minReputation;
+        return this.callResult('POST', '/a2a/atp/order', body);
+    }
+    async submitDelivery(orderId, proofPayload = {}) {
+        return this.callResult('POST', '/a2a/atp/deliver', {
+            order_id: nonEmpty(orderId, 'orderId'),
+            proof_payload: proofPayload,
+        });
+    }
+    async verifyDelivery(orderId, action = 'confirm') {
+        return this.callResult('POST', '/a2a/atp/verify', {
+            order_id: nonEmpty(orderId, 'orderId'),
+            action: enumValue(action, ATP_VERIFY_ACTIONS, 'action'),
+        });
+    }
+    async settleOrder(orderId) {
+        return this.callResult('POST', '/a2a/atp/settle', { order_id: nonEmpty(orderId, 'orderId') });
+    }
+    async disputeOrder(orderId, reason) {
+        return this.callResult('POST', '/a2a/atp/dispute', {
+            order_id: nonEmpty(orderId, 'orderId'),
+            reason: nonEmpty(reason, 'reason'),
+        });
+    }
+    async getMerchantTier(nodeId) {
+        const nid = nodeId ?? this.opts.senderId();
+        return this.callResult('GET', '/a2a/atp/merchant/tier', undefined, nid ? { node_id: nid } : undefined);
+    }
+    async getOrderStatus(orderId) {
+        return this.callResult('GET', `/a2a/atp/order/${encodeURIComponent(nonEmpty(orderId, 'orderId'))}`);
+    }
+    async listProofs(opts = {}) {
+        const query = {
+            node_id: opts.nodeId ?? this.opts.senderId(),
+            role: opts.role === undefined ? undefined : enumValue(opts.role, ATP_ROLES, 'role'),
+            status: opts.status === undefined ? undefined : enumValue(opts.status, ATP_PROOF_STATUSES, 'status'),
+            limit: opts.limit === undefined ? undefined : clampLimit(opts.limit),
+        };
+        return this.callResult('GET', '/a2a/atp/proofs', undefined, query);
+    }
+    async getAtpPolicy() {
+        return this.callResult('GET', '/a2a/atp/policy');
+    }
+    async listMyTasks(limit, nodeId) {
+        const nid = nodeId ?? this.opts.senderId();
+        const query = {
+            node_id: nid,
+            limit: limit === undefined ? undefined : clampLimit(limit),
+        };
+        return this.callResult('GET', '/a2a/task/my', undefined, query);
+    }
+    async callResult(method, path, body, query) {
+        try {
+            const raw = await this.http.call(method, path, body, query);
+            return normalizeAtpResult(raw);
+        }
+        catch (err) {
+            if (err instanceof HubClientError) {
+                return normalizeAtpError(err.status, err.body);
+            }
+            throw err;
+        }
+    }
+}
+export function normalizeAtpResult(raw) {
+    const rec = asRecord(raw);
+    const data = rec ? (rec['data'] ?? rec['payload'] ?? raw) : raw;
+    if (typeof rec?.['ok'] === 'boolean') {
+        if (rec['ok'])
+            return { ok: true, data: data };
+        return { ok: false, data: data, error: extractError(raw, 'atp_error') };
+    }
+    return { ok: true, data: data };
+}
+function normalizeAtpError(status, raw) {
+    const data = asRecord(raw)?.['data'] ?? asRecord(raw)?.['payload'] ?? raw;
+    return { ok: false, status, data: data, error: extractError(raw, `hub ${status}`) };
+}
+function asRecord(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
+}
+function extractError(value, fallback) {
+    if (typeof value === 'string' && value.trim())
+        return value;
+    const rec = asRecord(value);
+    const payload = asRecord(rec?.['payload']);
+    const data = asRecord(rec?.['data']);
+    const direct = rec?.['error'] ?? rec?.['message'] ?? payload?.['error'] ?? payload?.['message'] ?? data?.['error'] ?? data?.['message'];
+    return typeof direct === 'string' && direct.trim() ? direct : fallback;
+}
+function enumValue(value, allowed, name) {
+    const v = String(value);
+    if (!allowed.includes(v)) {
+        throw new Error(`invalid ATP ${name}: ${v} (expected ${allowed.join('|')})`);
+    }
+    return v;
+}
+function nonEmpty(value, name) {
+    const v = String(value ?? '').trim();
+    if (!v)
+        throw new Error(`ATP ${name} is required`);
+    return v;
+}
+function clampBudget(value) {
+    const n = Math.round(Number(value) || 10);
+    // budget is a spend cap that goes on the wire: a non-finite value (e.g. `1e400` parses to Infinity)
+    // JSON-serializes to `null`, which the hub could read as "no cap". Force a finite positive integer so the
+    // wire never carries null/Infinity/NaN as a budget. (An explicit upper MAX_BUDGET ceiling is a separate
+    // policy decision for the hub/maintainer; this only guarantees finiteness.)
+    return Number.isFinite(n) ? Math.max(1, n) : 10;
+}
+function clampLimit(value) {
+    const n = Math.round(Number(value) || 20);
+    return Math.max(1, Math.min(100, n));
+}

package/dist/auth/credentialStore.d.ts

@@ -0,0 +1,8 @@
+import type { hub } from '@evomap/evolver-core';
+/** 凭证持久化(~/.evomap, 0600). token/keypair 私钥都经此, 文件权限收紧. */
+export declare class CredentialStore {
+    private readonly path;
+    constructor(path: string);
+    load(): hub.Credential | null;
+    save(cred: hub.Credential): void;
+}

package/dist/auth/credentialStore.js

@@ -0,0 +1,23 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+/** 凭证持久化(~/.evomap, 0600). token/keypair 私钥都经此, 文件权限收紧. */
+export class CredentialStore {
+    path;
+    constructor(path) {
+        this.path = path;
+    }
+    load() {
+        if (!existsSync(this.path))
+            return null;
+        try {
+            return JSON.parse(readFileSync(this.path, 'utf8'));
+        }
+        catch {
+            return null;
+        }
+    }
+    save(cred) {
+        mkdirSync(dirname(this.path), { recursive: true });
+        writeFileSync(this.path, JSON.stringify(cred), { mode: 0o600 });
+    }
+}

package/dist/auth/keypair.d.ts

@@ -0,0 +1,42 @@
+import type { hub } from '@evomap/evolver-core';
+export interface KeypairProviderOptions {
+    credPath: string;
+    /** 注册公钥到 hub(注入; M6-6 真 HTTP). 返回 hub 侧凭证 id. */
+    registerPublicKey: (publicKeyPem: string) => Promise<{
+        credentialId: string;
+    }>;
+    revokeRemote?: (credentialId: string) => Promise<void>;
+    /** Injected clock (test determinism). Default Date.now. */
+    now?: () => number;
+    /** Injected per-request nonce generator (test determinism). Default 16 random bytes hex. */
+    nonceGen?: () => string;
+}
+/**
+ * Ed25519 keypair 认证(M6-5, 进阶/审计级). 私钥只存本机 0600, authenticate 对 body 签名(审计可信源).
+ * rotate=生成新对+注册+撤旧. 实现 core AuthProvider.
+ */
+export declare class KeypairProvider implements hub.AuthProvider {
+    private readonly opts;
+    readonly kind: "keypair";
+    private readonly store;
+    constructor(opts: KeypairProviderOptions);
+    login(): Promise<hub.Credential>;
+    private generate;
+    authenticate(req: hub.HttpRequestLike): Promise<hub.SignedRequest>;
+    rotate(): Promise<hub.Credential>;
+    revoke(credentialId: string): Promise<void>;
+    /**
+     * Verify a signed request (reference for the hub side). Checks all three: (1) Ed25519 signature over
+     * method+path+body+timestamp+nonce, (2) freshness — timestamp within ±maxSkewMs of now, (3) replay —
+     * the nonce has not been seen (when a seenNonces set is supplied; it is mutated to record this nonce).
+     * Returns false on any failure (bad sig / stale / replayed). The hub keeps seenNonces with a short TTL.
+     */
+    static verify(publicKeyPem: string, req: hub.HttpRequestLike, signatureB64: string, proof: {
+        timestamp: string;
+        nonce: string;
+    }, opts?: {
+        now?: () => number;
+        maxSkewMs?: number;
+        seenNonces?: Set<string>;
+    }): boolean;
+}

package/dist/auth/keypair.js

@@ -0,0 +1,80 @@
+import { generateKeyPairSync, sign as edSign, verify as edVerify, createPublicKey, createPrivateKey, randomBytes } from 'node:crypto';
+import { CredentialStore } from './credentialStore.js';
+/** 把 PEM 私钥还原成 KeyObject 用于签名. */
+function privFromPem(pem) { return createPrivateKey(pem); }
+/**
+ * Ed25519 keypair 认证(M6-5, 进阶/审计级). 私钥只存本机 0600, authenticate 对 body 签名(审计可信源).
+ * rotate=生成新对+注册+撤旧. 实现 core AuthProvider.
+ */
+export class KeypairProvider {
+    opts;
+    kind = 'keypair';
+    store;
+    constructor(opts) {
+        this.opts = opts;
+        this.store = new CredentialStore(opts.credPath);
+    }
+    async login() {
+        const existing = this.store.load();
+        if (existing && 'privateKey' in existing)
+            return existing;
+        return this.generate();
+    }
+    async generate() {
+        const { publicKey, privateKey } = generateKeyPairSync('ed25519');
+        const pubPem = publicKey.export({ type: 'spki', format: 'pem' }).toString();
+        const privPem = privateKey.export({ type: 'pkcs8', format: 'pem' }).toString();
+        const { credentialId } = await this.opts.registerPublicKey(pubPem);
+        const cred = { id: credentialId, kind: 'keypair', publicKey: pubPem, privateKey: privPem };
+        this.store.save(cred);
+        return cred;
+    }
+    async authenticate(req) {
+        const cred = this.store.load();
+        if (!cred || !('privateKey' in cred))
+            throw new Error('keypair 未初始化, 先 login()');
+        const body = req.body ?? '';
+        // Sign method+path+body+timestamp+nonce (#9): timestamp+nonce defeat REPLAY (a captured request can't be
+        // re-sent — verify rejects a stale timestamp or a seen nonce), not just substitution. Both travel as headers
+        // so the verifier can rebuild the exact signing string.
+        const timestamp = String((this.opts.now ?? Date.now)());
+        const nonce = (this.opts.nonceGen ?? (() => randomBytes(16).toString('hex')))();
+        const signing = `${req.method}\n${req.path}\n${body}\n${timestamp}\n${nonce}`;
+        const bodySignature = edSign(null, Buffer.from(signing), privFromPem(cred.privateKey)).toString('base64');
+        return {
+            headers: { 'x-evomap-key-id': cred.id, 'x-evomap-signature': bodySignature, 'x-evomap-timestamp': timestamp, 'x-evomap-nonce': nonce },
+            bodySignature,
+        };
+    }
+    async rotate() {
+        const old = this.store.load();
+        const fresh = await this.generate();
+        if (old && this.opts.revokeRemote)
+            await this.opts.revokeRemote(old.id).catch(() => { });
+        return fresh;
+    }
+    async revoke(credentialId) {
+        if (this.opts.revokeRemote)
+            await this.opts.revokeRemote(credentialId);
+    }
+    /**
+     * Verify a signed request (reference for the hub side). Checks all three: (1) Ed25519 signature over
+     * method+path+body+timestamp+nonce, (2) freshness — timestamp within ±maxSkewMs of now, (3) replay —
+     * the nonce has not been seen (when a seenNonces set is supplied; it is mutated to record this nonce).
+     * Returns false on any failure (bad sig / stale / replayed). The hub keeps seenNonces with a short TTL.
+     */
+    static verify(publicKeyPem, req, signatureB64, proof, opts = {}) {
+        const now = (opts.now ?? Date.now)();
+        const maxSkew = opts.maxSkewMs ?? 300_000; // 5 min
+        const ts = Number(proof.timestamp);
+        if (!Number.isFinite(ts) || Math.abs(now - ts) > maxSkew)
+            return false; // stale / future-dated → reject
+        if (opts.seenNonces) {
+            if (opts.seenNonces.has(proof.nonce))
+                return false; // replay → reject
+            opts.seenNonces.add(proof.nonce);
+        }
+        const signing = `${req.method}\n${req.path}\n${req.body ?? ''}\n${proof.timestamp}\n${proof.nonce}`;
+        return edVerify(null, Buffer.from(signing), createPublicKey(publicKeyPem), Buffer.from(signatureB64, 'base64'));
+    }
+}