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

package/dist/auth/legacyShim.d.ts

@@ -0,0 +1,43 @@
+import type { hub } from '@evomap/evolver-core';
+export declare function isNodeSecret(value: string): boolean;
+export declare function parseNodeSecretVersion(value: unknown): number | undefined;
+export type NodeSecretRotationHandler = (nodeSecret: string, nodeSecretVersion?: number) => void;
+export type NodeSecretVersionHandler = (nodeSecretVersion?: number) => void;
+/**
+ * Fired when the hub HTTP-200s an app-level rejection of our cached node_secret
+ * (reason ∈ {node_secret_invalid, rotation_requires_current_secret, invalid_secret}).
+ * The locally-cached secret has DIVERGED from the hub's record (hub-side reset,
+ * restored-from-backup machine, manual unlink). The handler owns clearing the
+ * durable copies (store keys + on-disk legacy files) so the next start re-acquires
+ * cleanly via an unauthenticated hello. Mirrors v1 a2aProtocol.js divergence recovery.
+ */
+export type NodeSecretDivergenceHandler = () => void;
+/**
+ * node_secret 双轨过渡(M6-5, 6 个月). 包旧 64-hex node_secret 成 AuthProvider.
+ * **node_secret 走 request body**(gep-a2a 契约, 实测 dev: requireNodeSecret 读 body 非 header), 不轮换.
+ */
+export declare class LegacyAuthShim implements hub.AuthProvider {
+    private nodeSecret;
+    private readonly onRotate?;
+    private readonly onVersionUpdate?;
+    private readonly onDiverged?;
+    readonly kind: "oauth_device_token";
+    private nodeSecretVersion?;
+    constructor(nodeSecret: string | undefined, onRotate?: NodeSecretRotationHandler | undefined, initialNodeSecretVersion?: number, onVersionUpdate?: NodeSecretVersionHandler | undefined, onDiverged?: NodeSecretDivergenceHandler | undefined);
+    login(): Promise<hub.Credential>;
+    authenticate(): Promise<hub.SignedRequest>;
+    rotate(): Promise<hub.Credential>;
+    revoke(): Promise<void>;
+    getNodeSecretVersion(): number | undefined;
+    adoptNodeSecret(nodeSecret: string, nodeSecretVersion?: number): void;
+    adoptNodeSecretVersion(nodeSecretVersion?: number): void;
+    clearNodeSecret(): void;
+    /**
+     * Hub rejected our cached node_secret as diverged (v1 a2aProtocol.js L1983-2017).
+     * Drop the in-memory secret + version so buildHubHeaders/authenticate fall back to
+     * unauthenticated on the next /a2a/hello, then hand off to onDiverged for the durable
+     * clear (store keys + on-disk legacy files). Does NOT route through onVersionUpdate —
+     * the divergence handler performs the full clear, including the version, atomically.
+     */
+    notifyNodeSecretDiverged(): void;
+}

package/dist/auth/legacyShim.js

@@ -0,0 +1,82 @@
+export function isNodeSecret(value) {
+    return /^[a-f0-9]{64}$/i.test(value);
+}
+export function parseNodeSecretVersion(value) {
+    if (typeof value === 'number' && Number.isInteger(value) && value > 0)
+        return value;
+    if (typeof value !== 'string')
+        return undefined;
+    const trimmed = value.trim();
+    if (!/^[1-9]\d*$/.test(trimmed))
+        return undefined;
+    const parsed = Number(trimmed);
+    return Number.isSafeInteger(parsed) ? parsed : undefined;
+}
+/**
+ * node_secret 双轨过渡(M6-5, 6 个月). 包旧 64-hex node_secret 成 AuthProvider.
+ * **node_secret 走 request body**(gep-a2a 契约, 实测 dev: requireNodeSecret 读 body 非 header), 不轮换.
+ */
+export class LegacyAuthShim {
+    nodeSecret;
+    onRotate;
+    onVersionUpdate;
+    onDiverged;
+    kind = 'oauth_device_token';
+    nodeSecretVersion;
+    constructor(nodeSecret, onRotate, initialNodeSecretVersion, onVersionUpdate, onDiverged) {
+        this.nodeSecret = nodeSecret;
+        this.onRotate = onRotate;
+        this.onVersionUpdate = onVersionUpdate;
+        this.onDiverged = onDiverged;
+        if (!nodeSecret || !isNodeSecret(nodeSecret))
+            throw new Error('node_secret 必须是 64-hex');
+        this.nodeSecretVersion = parseNodeSecretVersion(initialNodeSecretVersion);
+    }
+    async login() { return { id: 'legacy-node-secret', kind: 'oauth_device_token', token: this.nodeSecret ?? '' }; }
+    async authenticate() {
+        return {
+            headers: this.nodeSecretVersion !== undefined
+                ? { 'X-EvoMap-Node-Secret-Version': String(this.nodeSecretVersion) }
+                : {},
+            // node_secret_version travels via the X-EvoMap-Node-Secret-Version header on every request (above)
+            // and is added to the heartbeat body explicitly by PublicHubCapability. It is intentionally NOT
+            // injected into generic request bodies — matching v1, which carries it in the body only on heartbeat.
+            bodyFields: {
+                ...(this.nodeSecret ? { node_secret: this.nodeSecret } : {}),
+            },
+        };
+    }
+    async rotate() { return this.login(); }
+    async revoke() { }
+    getNodeSecretVersion() {
+        return this.nodeSecretVersion;
+    }
+    adoptNodeSecret(nodeSecret, nodeSecretVersion) {
+        if (!isNodeSecret(nodeSecret))
+            throw new Error('node_secret 必须是 64-hex');
+        this.nodeSecret = nodeSecret;
+        this.nodeSecretVersion = parseNodeSecretVersion(nodeSecretVersion);
+        this.onRotate?.(nodeSecret, this.nodeSecretVersion);
+    }
+    adoptNodeSecretVersion(nodeSecretVersion) {
+        this.nodeSecretVersion = parseNodeSecretVersion(nodeSecretVersion);
+        this.onVersionUpdate?.(this.nodeSecretVersion);
+    }
+    clearNodeSecret() {
+        this.nodeSecret = undefined;
+        this.nodeSecretVersion = undefined;
+        this.onVersionUpdate?.(undefined);
+    }
+    /**
+     * Hub rejected our cached node_secret as diverged (v1 a2aProtocol.js L1983-2017).
+     * Drop the in-memory secret + version so buildHubHeaders/authenticate fall back to
+     * unauthenticated on the next /a2a/hello, then hand off to onDiverged for the durable
+     * clear (store keys + on-disk legacy files). Does NOT route through onVersionUpdate —
+     * the divergence handler performs the full clear, including the version, atomically.
+     */
+    notifyNodeSecretDiverged() {
+        this.nodeSecret = undefined;
+        this.nodeSecretVersion = undefined;
+        this.onDiverged?.();
+    }
+}

package/dist/auth/machineId.d.ts

@@ -0,0 +1,20 @@
+/** OS 级 machineId 读取器(按平台). 返回首个非空, 读不到返 undefined. */
+export type OsIdReader = () => string | undefined;
+/** Linux: /etc/machine-id | /var/lib/dbus/machine-id; macOS/Windows 由调用方注入. */
+export declare const DEFAULT_OS_READERS: OsIdReader[];
+export interface MachineIdOptions {
+    /** 软兜底 UUID 路径(默认 ~/.evomap/machine-id). */
+    softIdPath: string;
+    /** OS 读取器(默认 Linux); 测试可注入. */
+    osReaders?: OsIdReader[];
+}
+/**
+ * 机器标识(CEO 决策, 2026-06-06): **优先 OS machineId(/etc/machine-id 等), 读不到回退安装时软 UUID**.
+ * 容器/CI 不脆、不依赖 MAC、跨平台一致. 软 UUID 首次生成存 0600.
+ */
+export declare function resolveMachineId(opts: MachineIdOptions): {
+    id: string;
+    source: 'os' | 'soft';
+};
+/** device token 绑定用的指纹 = sha256(machineId). 不直接外泄 machineId. */
+export declare function machineFingerprint(machineId: string): string;

package/dist/auth/machineId.js

@@ -0,0 +1,38 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { createHash, randomUUID } from 'node:crypto';
+import { dirname } from 'node:path';
+/** Linux: /etc/machine-id | /var/lib/dbus/machine-id; macOS/Windows 由调用方注入. */
+export const DEFAULT_OS_READERS = [
+    () => tryRead('/etc/machine-id'),
+    () => tryRead('/var/lib/dbus/machine-id'),
+];
+function tryRead(p) {
+    try {
+        const v = readFileSync(p, 'utf8').trim();
+        return v || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * 机器标识(CEO 决策, 2026-06-06): **优先 OS machineId(/etc/machine-id 等), 读不到回退安装时软 UUID**.
+ * 容器/CI 不脆、不依赖 MAC、跨平台一致. 软 UUID 首次生成存 0600.
+ */
+export function resolveMachineId(opts) {
+    for (const r of opts.osReaders ?? DEFAULT_OS_READERS) {
+        const v = r();
+        if (v)
+            return { id: v, source: 'os' };
+    }
+    if (existsSync(opts.softIdPath))
+        return { id: readFileSync(opts.softIdPath, 'utf8').trim(), source: 'soft' };
+    const fresh = randomUUID();
+    mkdirSync(dirname(opts.softIdPath), { recursive: true });
+    writeFileSync(opts.softIdPath, fresh, { mode: 0o600 });
+    return { id: fresh, source: 'soft' };
+}
+/** device token 绑定用的指纹 = sha256(machineId). 不直接外泄 machineId. */
+export function machineFingerprint(machineId) {
+    return createHash('sha256').update(machineId).digest('hex');
+}

package/dist/auth/oauthDeviceToken.d.ts

@@ -0,0 +1,62 @@
+import type { hub } from '@evomap/evolver-core';
+import { type MachineIdOptions } from './machineId.js';
+export declare const TOKEN_TTL_MS: number;
+export declare const ROTATE_BEFORE_MS: number;
+export interface DeviceCodeResp {
+    deviceCode: string;
+    userCode: string;
+    verificationUri: string;
+    intervalMs: number;
+}
+export interface TokenResp {
+    token: string;
+    expiresInMs?: number;
+    refreshToken?: string;
+}
+/** 注入的 OAuth device flow 传输(M6-6 真 HTTP; 测试用桩). refresh 走 refresh_token grant. */
+export interface OAuthTransport {
+    requestDeviceCode: (fingerprint: string) => Promise<DeviceCodeResp>;
+    pollToken: (deviceCode: string) => Promise<TokenResp | {
+        pending: true;
+    }>;
+    refresh?: (refreshToken: string) => Promise<TokenResp>;
+}
+export interface PublicOAuthOptions {
+    credPath: string;
+    machine: MachineIdOptions;
+    transport: OAuthTransport;
+    now?: () => number;
+    /** 展示 user code 给用户(默认 console). */
+    onUserCode?: (d: DeviceCodeResp) => void;
+    /** 轮询间隔等待(默认 setTimeout; 测试可注入 no-op). */
+    sleep?: (ms: number) => Promise<void>;
+    /** 整个 device flow 的最长等待(默认 15min); 超时抛 device_flow_timeout. */
+    maxWaitMs?: number;
+}
+/**
+ * device token 认证(M6-5, 默认路径 evolver login). device code flow(学 gh auth login):
+ * 显示 user code → 用户在浏览器授权 → 轮询拿 token. 绑机器指纹(CEO: OS machineId+软兜底).
+ * hub access token 短寿(~1h)+ refresh_token 续期; 过期前 ROTATE_BEFORE_MS 自动 rotate.
+ */
+export declare class PublicOAuthProvider implements hub.AuthProvider {
+    private readonly opts;
+    readonly kind: "oauth_device_token";
+    private readonly store;
+    private readonly now;
+    private readonly sleep;
+    private readonly maxWaitMs;
+    constructor(opts: PublicOAuthOptions);
+    private fingerprint;
+    /**
+     * Full device-flow login: reuse a still-valid cached token, else request a
+     * device code (shown once via onUserCode) and poll until the user approves in
+     * the browser, returning + persisting the credential. Drives the poll loop
+     * itself (respecting the server interval); a terminal error from the transport
+     * (access_denied / expired_token) propagates.
+     */
+    login(): Promise<hub.Credential>;
+    authenticate(): Promise<hub.SignedRequest>;
+    rotate(): Promise<hub.Credential>;
+    revoke(): Promise<void>;
+    private persist;
+}

package/dist/auth/oauthDeviceToken.js

@@ -0,0 +1,83 @@
+import { CredentialStore } from './credentialStore.js';
+import { resolveMachineId, machineFingerprint } from './machineId.js';
+export const TOKEN_TTL_MS = 24 * 60 * 60_000; // fallback only; the hub supplies expiresInMs (~1h)
+export const ROTATE_BEFORE_MS = 5 * 60_000; // refresh 5min before expiry (hub access tokens are short-lived ~1h)
+/**
+ * device token 认证(M6-5, 默认路径 evolver login). device code flow(学 gh auth login):
+ * 显示 user code → 用户在浏览器授权 → 轮询拿 token. 绑机器指纹(CEO: OS machineId+软兜底).
+ * hub access token 短寿(~1h)+ refresh_token 续期; 过期前 ROTATE_BEFORE_MS 自动 rotate.
+ */
+export class PublicOAuthProvider {
+    opts;
+    kind = 'oauth_device_token';
+    store;
+    now;
+    sleep;
+    maxWaitMs;
+    constructor(opts) {
+        this.opts = opts;
+        this.store = new CredentialStore(opts.credPath);
+        this.now = opts.now ?? (() => Date.now());
+        this.sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+        this.maxWaitMs = opts.maxWaitMs ?? 15 * 60_000;
+    }
+    fingerprint() { return machineFingerprint(resolveMachineId(this.opts.machine).id); }
+    /**
+     * Full device-flow login: reuse a still-valid cached token, else request a
+     * device code (shown once via onUserCode) and poll until the user approves in
+     * the browser, returning + persisting the credential. Drives the poll loop
+     * itself (respecting the server interval); a terminal error from the transport
+     * (access_denied / expired_token) propagates.
+     */
+    async login() {
+        const cached = this.store.load();
+        if (cached && 'token' in cached && (cached.expiresAt ?? 0) - ROTATE_BEFORE_MS > this.now())
+            return cached;
+        const fp = this.fingerprint();
+        const dc = await this.opts.transport.requestDeviceCode(fp);
+        (this.opts.onUserCode ?? ((d) => { process.stdout.write(`授权码 ${d.userCode} → ${d.verificationUri}\n`); }))(dc);
+        const deadline = this.now() + this.maxWaitMs;
+        let intervalMs = dc.intervalMs;
+        for (;;) {
+            const res = await this.opts.transport.pollToken(dc.deviceCode);
+            if (!('pending' in res))
+                return this.persist(res, fp);
+            if (this.now() >= deadline)
+                throw new Error('device_flow_timeout');
+            await this.sleep(intervalMs);
+            intervalMs += 1000; // gentle back-off; the hub's slow_down also surfaces as pending
+        }
+    }
+    async authenticate() {
+        let cred = this.store.load();
+        if (!cred || !('token' in cred))
+            throw new Error('oauth 未登录, 先 login()');
+        if ((cred.expiresAt ?? 0) - ROTATE_BEFORE_MS <= this.now())
+            cred = await this.rotate();
+        return { headers: { authorization: `Bearer ${cred.token}`, 'x-evomap-device': cred.device ?? '' } };
+    }
+    async rotate() {
+        const cred = this.store.load();
+        const fp = this.fingerprint();
+        // Prefer a seamless refresh_token rotation; fall back to a fresh device-flow
+        // login only when there is no usable refresh token (or no refresh transport).
+        if (cred && 'refreshToken' in cred && cred.refreshToken && this.opts.transport.refresh) {
+            const res = await this.opts.transport.refresh(cred.refreshToken);
+            return this.persist(res, fp, cred.refreshToken);
+        }
+        return this.login();
+    }
+    async revoke() { }
+    // fallbackRefresh: carry the prior refresh token forward when the hub's refresh
+    // response does not rotate it (so a later rotate() still has one to use).
+    persist(res, fingerprint, fallbackRefresh) {
+        const refreshToken = res.refreshToken ?? fallbackRefresh;
+        const cred = {
+            id: `oauth-${fingerprint.slice(0, 12)}`, kind: 'oauth_device_token', device: fingerprint,
+            token: res.token, expiresAt: this.now() + (res.expiresInMs ?? TOKEN_TTL_MS),
+            ...(refreshToken ? { refreshToken } : {}),
+        };
+        this.store.save(cred);
+        return cred;
+    }
+}

package/dist/auth/oauthHttpTransport.d.ts

@@ -0,0 +1,33 @@
+import { type FetchLike } from '../hubFetch.js';
+import type { OAuthTransport } from './oauthDeviceToken.js';
+/** First-party public client seeded on the hub (scripts/seed-evolver-oauth-client.js). */
+export declare const DEFAULT_CLIENT_ID = "evolver-cli";
+/**
+ * Default scopes requested by `evolver login`. `a2a` is the converged
+ * replacement for node_secret on the agent surface (Phase 2); the recipe/gene
+ * scopes cover the publish path. The hub clamps to the client's allowedScopes,
+ * so over-asking is safe.
+ */
+export declare const DEFAULT_SCOPES: string[];
+export interface OAuthHttpTransportOptions {
+    /** Hub base URL, e.g. https://evomap.ai (same EVOMAP_HUB_URL the /a2a calls use). */
+    hubUrl: string;
+    clientId?: string;
+    scopes?: string[];
+    /** Injected for tests; defaults to the secure global fetch (https guard + forced TLS). */
+    fetchFn?: FetchLike;
+}
+/**
+ * Real HTTP transport (M6-6) for the RFC 8628 device authorization grant. The
+ * device_authorization + token endpoints are PUBLIC (the device_code itself is
+ * the credential), so this posts plain JSON and does NOT go through HubFetch's
+ * AuthProvider header injection. Egress still runs through the secure FetchLike
+ * (https-only guard + forced-TLS dispatcher) — same chokepoint as /a2a.
+ *
+ * Wire shapes are pinned to the deployed hub (verified on prod): the hub speaks
+ * JSON (it mounts express.json() only), returns RFC 8628 fields, and signals
+ * polling state via `{ "error": "authorization_pending" | "slow_down" }` (HTTP
+ * 400). `slow_down`/`authorization_pending` map to `{ pending: true }`; any other
+ * error (access_denied / expired_token / invalid_grant) throws.
+ */
+export declare function createOAuthHttpTransport(opts: OAuthHttpTransportOptions): OAuthTransport;

package/dist/auth/oauthHttpTransport.js

@@ -0,0 +1,93 @@
+import { assertHubUrlSecure, globalFetchLike } from '../hubFetch.js';
+const DEVICE_GRANT = 'urn:ietf:params:oauth:grant-type:device_code';
+/** First-party public client seeded on the hub (scripts/seed-evolver-oauth-client.js). */
+export const DEFAULT_CLIENT_ID = 'evolver-cli';
+/**
+ * Default scopes requested by `evolver login`. `a2a` is the converged
+ * replacement for node_secret on the agent surface (Phase 2); the recipe/gene
+ * scopes cover the publish path. The hub clamps to the client's allowedScopes,
+ * so over-asking is safe.
+ */
+export const DEFAULT_SCOPES = ['a2a', 'recipe:read', 'recipe:write', 'recipe:publish', 'gene:read', 'reuse:query'];
+/**
+ * Real HTTP transport (M6-6) for the RFC 8628 device authorization grant. The
+ * device_authorization + token endpoints are PUBLIC (the device_code itself is
+ * the credential), so this posts plain JSON and does NOT go through HubFetch's
+ * AuthProvider header injection. Egress still runs through the secure FetchLike
+ * (https-only guard + forced-TLS dispatcher) — same chokepoint as /a2a.
+ *
+ * Wire shapes are pinned to the deployed hub (verified on prod): the hub speaks
+ * JSON (it mounts express.json() only), returns RFC 8628 fields, and signals
+ * polling state via `{ "error": "authorization_pending" | "slow_down" }` (HTTP
+ * 400). `slow_down`/`authorization_pending` map to `{ pending: true }`; any other
+ * error (access_denied / expired_token / invalid_grant) throws.
+ */
+export function createOAuthHttpTransport(opts) {
+    const base = opts.hubUrl.replace(/\/$/, '');
+    const clientId = opts.clientId ?? DEFAULT_CLIENT_ID;
+    const scope = (opts.scopes ?? DEFAULT_SCOPES).join(' ');
+    const fetchFn = opts.fetchFn ?? globalFetchLike;
+    async function postJson(path, body) {
+        const url = `${base}${path}`;
+        assertHubUrlSecure(url); // defense in depth; also enforced inside globalFetchLike
+        const res = await fetchFn(url, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify(body),
+        });
+        const json = (await res.json().catch(() => ({})));
+        return { status: res.status, json };
+    }
+    return {
+        async requestDeviceCode(_fingerprint) {
+            // The hub binds the device authorization to the client + the approving
+            // user, not to a machine fingerprint, so the fingerprint is not sent here;
+            // it is bound locally on the resulting credential (x-evomap-device header).
+            const { status, json } = await postJson('/oauth/device_authorization', {
+                client_id: clientId,
+                scope,
+            });
+            if (status >= 400 || !json.device_code || !json.user_code) {
+                throw new Error(`device_authorization failed (HTTP ${status}): ${json.error ?? 'no device_code'}`);
+            }
+            return {
+                deviceCode: json.device_code,
+                userCode: json.user_code,
+                verificationUri: json.verification_uri_complete ?? json.verification_uri ?? '',
+                intervalMs: (json.interval ?? 5) * 1000,
+            };
+        },
+        async pollToken(deviceCode) {
+            const { status, json } = await postJson('/oauth/token', {
+                grant_type: DEVICE_GRANT,
+                device_code: deviceCode,
+                client_id: clientId,
+            });
+            if (json.access_token) {
+                return tokenResp(json);
+            }
+            if (json.error === 'authorization_pending' || json.error === 'slow_down') {
+                return { pending: true };
+            }
+            throw new Error(`token poll failed (HTTP ${status}): ${json.error ?? 'unknown'}`);
+        },
+        async refresh(refreshToken) {
+            const { status, json } = await postJson('/oauth/token', {
+                grant_type: 'refresh_token',
+                refresh_token: refreshToken,
+                client_id: clientId,
+            });
+            if (!json.access_token) {
+                throw new Error(`refresh failed (HTTP ${status}): ${json.error ?? 'no access_token'}`);
+            }
+            return tokenResp(json);
+        },
+    };
+}
+function tokenResp(json) {
+    return {
+        token: json.access_token,
+        ...(json.expires_in ? { expiresInMs: json.expires_in * 1000 } : {}),
+        ...(json.refresh_token ? { refreshToken: json.refresh_token } : {}),
+    };
+}

package/dist/connect.d.ts

@@ -0,0 +1,40 @@
+import type { hub } from '@evomap/evolver-core';
+import { PublicHubCapability } from './hubCapability.js';
+import type { AntiAbuseTelemetryOptions } from './antiAbuseTelemetry.js';
+import { type FetchLike } from './hubFetch.js';
+import { type OAuthTransport } from './auth/oauthDeviceToken.js';
+export type AuthMode = 'oauth' | 'keypair' | 'legacy';
+export interface ConnectPublicOptions {
+    hubUrl: string;
+    authMode: AuthMode;
+    senderId: () => string | undefined;
+    fetchFn?: FetchLike;
+    evomapDir?: string;
+    /** legacy 模式: 64-hex node_secret. */
+    nodeSecret?: string;
+    /** legacy 模式: node_secret 对应的可选 Hub keyring version. */
+    nodeSecretVersion?: number;
+    /** legacy 模式: hello rotate 返回新 node_secret 后持久化到调用方状态存储. */
+    onNodeSecretRotated?: (nodeSecret: string, nodeSecretVersion?: number) => void;
+    /** legacy 模式: hello 返回 version 但未轮换 secret 时持久化 version. */
+    onNodeSecretVersionUpdated?: (nodeSecretVersion?: number) => void;
+    /**
+     * legacy 模式: hub HTTP-200 拒绝本地 node_secret(已与 hub 记录漂移)时回调.
+     * 实现方负责清除持久副本(store keys + 磁盘 legacy 文件), 下次启动以未认证 hello 重新获取.
+     * v1 a2aProtocol.js 的 secret-divergence 自愈.
+     */
+    onNodeSecretDiverged?: () => void;
+    /** oauth 模式: device flow 传输(缺省=真 HTTP, 此处需注入或由 hubUrl 推导). */
+    oauthTransport?: OAuthTransport;
+    /** keypair 模式: 注册公钥到 hub. */
+    registerPublicKey?: (pem: string) => Promise<{
+        credentialId: string;
+    }>;
+    /** Optional anti-abuse metadata context for heartbeat payloads. */
+    antiAbuse?: AntiAbuseTelemetryOptions;
+}
+/** 选址装配公版 hub(M6-7): 按 authMode 组 AuthProvider(M6-5) + PublicHubCapability(M6-6). */
+export declare function connectPublicHub(opts: ConnectPublicOptions): {
+    hub: PublicHubCapability;
+    auth: hub.AuthProvider;
+};

package/dist/connect.js

@@ -0,0 +1,38 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { PublicHubCapability } from './hubCapability.js';
+import { globalFetchLike } from './hubFetch.js';
+import { LegacyAuthShim } from './auth/legacyShim.js';
+import { PublicOAuthProvider } from './auth/oauthDeviceToken.js';
+import { createOAuthHttpTransport } from './auth/oauthHttpTransport.js';
+import { KeypairProvider } from './auth/keypair.js';
+/** 选址装配公版 hub(M6-7): 按 authMode 组 AuthProvider(M6-5) + PublicHubCapability(M6-6). */
+export function connectPublicHub(opts) {
+    const dir = opts.evomapDir ?? join(homedir(), '.evomap');
+    const fetchFn = opts.fetchFn ?? globalFetchLike;
+    let auth;
+    switch (opts.authMode) {
+        case 'legacy':
+            if (!opts.nodeSecret)
+                throw new Error('legacy 模式需 nodeSecret');
+            auth = new LegacyAuthShim(opts.nodeSecret, opts.onNodeSecretRotated, opts.nodeSecretVersion, opts.onNodeSecretVersionUpdated, opts.onNodeSecretDiverged);
+            break;
+        case 'keypair':
+            if (!opts.registerPublicKey)
+                throw new Error('keypair 模式需 registerPublicKey');
+            auth = new KeypairProvider({ credPath: join(dir, 'keys', 'keypair.json'), registerPublicKey: opts.registerPublicKey });
+            break;
+        case 'oauth': {
+            // Default to the real HTTP device-flow transport derived from hubUrl;
+            // tests/embedders may still inject their own.
+            const transport = opts.oauthTransport ?? createOAuthHttpTransport({ hubUrl: opts.hubUrl, fetchFn });
+            auth = new PublicOAuthProvider({ credPath: join(dir, 'token.json'), machine: { softIdPath: join(dir, 'machine-id') }, transport });
+            break;
+        }
+        default: {
+            const _x = opts.authMode;
+            throw new Error(`未知 authMode: ${String(_x)}`);
+        }
+    }
+    return { hub: new PublicHubCapability({ baseUrl: opts.hubUrl, auth, fetchFn, senderId: opts.senderId, antiAbuse: opts.antiAbuse }), auth };
+}