ai-fly 0.0.0 → 0.1.0

package/dist/config-CO3WyW2H.mjs

@@ -0,0 +1,173 @@
+import { n as UsageError, t as CliError } from "./errors-BGtxPkM7.mjs";
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { z } from "zod";
+import { randomBytes } from "node:crypto";
+//#region src/cli/args.ts
+function expandTilde(value, homedir) {
+	if (value === "~") return homedir;
+	if (value.startsWith("~/")) return homedir + value.slice(1);
+	return value;
+}
+/**
+* 解析带 ms|s|m|h|d 后缀的时长；裸数字按毫秒（与 opendweb-example 同规）。
+* 语法错误抛 CliError；值域检查由调用方按各选项边界执行。
+*/
+function parseDurationMs(raw, label) {
+	const m = /^([0-9]+(?:\.[0-9]+)?)(ms|s|m|h|d)?$/.exec(String(raw).trim());
+	if (!m) throw new CliError(`error: invalid ${label} value: ${raw} (expected <number>[ms|s|m|h|d])`);
+	const ms = Number(m[1]) * ({
+		ms: 1,
+		s: 1e3,
+		m: 6e4,
+		h: 36e5,
+		d: 864e5
+	}[m[2] ?? "ms"] ?? 1);
+	if (!Number.isFinite(ms) || ms > Number.MAX_SAFE_INTEGER) return Number.POSITIVE_INFINITY;
+	return ms;
+}
+function assertDurationRange(ms, minMs, maxMs, label, rangeText) {
+	if (!(ms >= minMs && ms <= maxMs)) throw new CliError(`error: ${label} out of range (${rangeText})`);
+}
+function parseArgv(argv, spec, ctx = {}) {
+	const homedir = ctx.homedir ?? "";
+	const options = {};
+	const positionals = [];
+	const known = Object.keys(spec);
+	for (let i = 0; i < argv.length; i++) {
+		const tok = argv[i];
+		if (tok === "--") {
+			for (let j = i + 1; j < argv.length; j++) positionals.push(argv[j]);
+			break;
+		}
+		if (tok.startsWith("--")) {
+			const eq = tok.indexOf("=");
+			const name = (eq >= 0 ? tok.slice(2, eq) : tok.slice(2)).trim();
+			const inlineValue = eq >= 0 ? tok.slice(eq + 1) : void 0;
+			const decl = spec[name];
+			if (!decl) throw new UsageError(`error: unknown option --${name} (known: ${known.map((k) => `--${k}`).join(", ")})`);
+			if (decl.type === "boolean") {
+				if (inlineValue !== void 0) throw new UsageError(`error: option --${name} does not take a value`);
+				options[name] = true;
+			} else {
+				let value = inlineValue;
+				if (value === void 0) {
+					if (i + 1 >= argv.length) throw new UsageError(`error: option --${name} requires a value`);
+					value = argv[++i];
+				}
+				if (decl.tilde) value = expandTilde(value, homedir);
+				if (decl.type === "multi") {
+					const list = Array.isArray(options[name]) ? options[name] : [];
+					list.push(value);
+					options[name] = list;
+				} else options[name] = value;
+			}
+		} else positionals.push(tok);
+	}
+	return {
+		options,
+		positionals
+	};
+}
+//#endregion
+//#region src/wire/z32.ts
+/** z-base-32 字母表（fabric 同款，ybndrfg8…h769）。 */
+const Z32_ALPHABET = "ybndrfg8ejkmcpqxot1uwisza345h769";
+const CHAR_VALUE = (/* @__PURE__ */ new Uint8Array(128)).fill(255);
+for (let i = 0; i < 32; i++) CHAR_VALUE[Z32_ALPHABET.charCodeAt(i)] = i;
+/** 编码：高位在前、5 bit 一组；末组不足 5 bit 左移补零，不输出填充符。 */
+function encodeZ32(bytes) {
+	let out = "";
+	let acc = 0;
+	let bits = 0;
+	for (let i = 0; i < bytes.length; i++) {
+		acc = acc << 8 | bytes[i];
+		bits += 8;
+		while (bits >= 5) {
+			bits -= 5;
+			out += Z32_ALPHABET.charAt(acc >>> bits & 31);
+		}
+		acc &= (1 << bits) - 1;
+	}
+	if (bits > 0) out += Z32_ALPHABET.charAt(acc << 5 - bits & 31);
+	return out;
+}
+/** 解码：严格规范形校验（非法字符、尾位 padding 非零、非最短长度均抛错）。 */
+function decodeZ32(text) {
+	const out = [];
+	let acc = 0;
+	let bits = 0;
+	for (let i = 0; i < text.length; i++) {
+		const code = text.charCodeAt(i);
+		if (code >= 128 || CHAR_VALUE[code] === 255) throw new Error(`z32: invalid character at index ${i}`);
+		acc = acc << 5 | CHAR_VALUE[code];
+		bits += 5;
+		if (bits >= 8) {
+			bits -= 8;
+			out.push(acc >>> bits & 255);
+			acc &= (1 << bits) - 1;
+		}
+	}
+	if (bits > 0 && acc !== 0) throw new Error("z32: non-canonical trailing bits");
+	const bytes = Uint8Array.from(out);
+	if (encodeZ32(bytes).length !== text.length) throw new Error("z32: non-canonical length");
+	return bytes;
+}
+/** nBytes 字节密码学随机数的 z32 编码（request-id / serviceId / 密钥体共用）。 */
+function randomZ32(nBytes) {
+	return encodeZ32(randomBytes(nBytes));
+}
+//#endregion
+//#region src/cli/config.ts
+const configFileSchema = z.object({ 
+/** relay 入口 URL 列表（自托管 gateway 地址，如 http://192.168.2.13:8787） */
+relayUrls: z.array(z.string().url()).optional() });
+function configDir(base = homedir()) {
+	return join(base, ".aifly");
+}
+function configPath(base = homedir()) {
+	return join(configDir(base), "config.json");
+}
+/** 读取并校验配置文件；不存在返回 {}；损坏/非法时抛 CliError（不静默重置）。 */
+function loadConfig(base = homedir()) {
+	const p = configPath(base);
+	if (!existsSync(p)) return {};
+	let raw;
+	try {
+		raw = readFileSync(p, "utf8");
+	} catch (err) {
+		throw new CliError(`error: cannot read config ${p}: ${err.message}`);
+	}
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		throw new CliError(`error: config ${p} is not valid JSON (fix or remove it manually)`);
+	}
+	const result = configFileSchema.safeParse(parsed);
+	if (!result.success) throw new CliError(`error: config ${p} failed validation: ${result.error.message}`);
+	return result.data;
+}
+/**
+* 解析生效的 relay 入口：flag > 链接内嵌（import 消费侧）> env(AIFLY_RELAY，逗号
+* 分隔) > config file。返回 undefined 表示走 SDK 默认（n0 公共 relay）。
+* 链接层级的语义：aifly1. 链接内嵌的 relayUrls 是提供方签发 invite 的入口——
+* 兑换与后续连接都必须发生在同一 relay 网，故高于机器级 env/config（2026-09-09
+* 实机踩坑：不带 --relay 时落 SDK 公网默认，兑换成功但连接永败且无提示）。
+*/
+function resolveRelayUrls(input) {
+	const fromFlag = input.flag?.filter((u) => u.length > 0);
+	if (fromFlag && fromFlag.length > 0) return [...fromFlag];
+	const fromLink = input.link?.filter((u) => u.length > 0);
+	if (fromLink && fromLink.length > 0) return [...fromLink];
+	const envRaw = input.env?.trim();
+	if (envRaw) {
+		const urls = envRaw.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+		if (urls.length > 0) return urls;
+	}
+	const fromFile = input.file?.relayUrls;
+	if (fromFile && fromFile.length > 0) return [...fromFile];
+}
+//#endregion
+export { assertDurationRange as a, randomZ32 as i, resolveRelayUrls as n, parseArgv as o, decodeZ32 as r, parseDurationMs as s, loadConfig as t };

package/dist/errors-BGtxPkM7.mjs

@@ -0,0 +1,27 @@
+//#region src/cli/errors.ts
+var CliError = class extends Error {
+	exitCode;
+	constructor(message, exitCode = 1) {
+		super(message);
+		this.name = "CliError";
+		this.exitCode = exitCode;
+	}
+};
+var UsageError = class extends CliError {
+	constructor(message) {
+		super(message, 2);
+		this.name = "UsageError";
+	}
+};
+/** 顶层兜底：把 Error 映射为终端输出 + 退出码；CliError 按其携带码，其余按 1。 */
+function reportCliError(err) {
+	if (err instanceof CliError) {
+		process.stderr.write(`${err.message}\n`);
+		return err.exitCode;
+	}
+	const msg = err instanceof Error ? err.message : String(err);
+	process.stderr.write(`error: ${msg}\n`);
+	return 1;
+}
+//#endregion
+export { UsageError as n, reportCliError as r, CliError as t };

package/dist/forget-BEbNwPip.mjs

@@ -0,0 +1,22 @@
+import { n as UsageError } from "./errors-BGtxPkM7.mjs";
+import { o as parseArgv } from "./config-CO3WyW2H.mjs";
+import { _ as removeKeyring, c as consumersRoot, n as ctxHomedir, r as ctxOut } from "./common-4VeA_3wo.mjs";
+import { homedir } from "node:os";
+//#region src/cli/commands/consumer/forget.ts
+async function run(argv, ctx = {}) {
+	const { options, positionals } = parseArgv(argv, { data: {
+		type: "string",
+		tilde: true
+	} }, { homedir: ctx.homedir ?? homedir() });
+	const ref = positionals[0];
+	if (ref === void 0) throw new UsageError("error: forget requires a provider reference\nusage: ai-fly forget <endpointId|8-char-prefix|alias> [--data <dir>]");
+	const out = ctxOut(ctx);
+	const root = consumersRoot(options.data, ctxHomedir(ctx));
+	const removed = removeKeyring(root, ref);
+	out(`forgot provider '${removed.ring.alias}' (${removed.ring.endpointId})`);
+	out(`removed ${removed.dir} (keyring + fabric identity)`);
+	out("note: provider-side revocation must be done on the provider (ai-fly key revoke / ai-fly revoke)");
+	return 0;
+}
+//#endregion
+export { run };

package/dist/group-Csy9VmFb.mjs

@@ -0,0 +1,92 @@
+import { n as UsageError, r as reportCliError } from "./errors-BGtxPkM7.mjs";
+import { o as parseArgv } from "./config-CO3WyW2H.mjs";
+import { d as str, l as resolveDataDir, n as multi, r as openStore, s as parsePositiveInt } from "./common-BULbPtYn.mjs";
+import { homedir } from "node:os";
+//#region src/cli/commands/provider/group.ts
+const SPEC = {
+	data: {
+		type: "string",
+		tilde: true
+	},
+	service: { type: "multi" },
+	"max-concurrency": { type: "string" },
+	"daily-requests": { type: "string" }
+};
+const USAGE = `usage:
+  ai-fly group add <name> [--service <serviceName>]... [--max-concurrency <n>] [--daily-requests <n>] [--data <dir>]
+  ai-fly group set-services <name> [--service <serviceName>]... [--data <dir>]
+  ai-fly group remove <name> [--data <dir>]
+  ai-fly group list [--data <dir>]`;
+async function run(argv, ctx = {}) {
+	try {
+		const home = ctx.homedir ?? homedir();
+		const { options, positionals } = parseArgv(argv, SPEC, { homedir: home });
+		const sub = positionals[0];
+		if (sub === "add") return add(options, positionals, home);
+		if (sub === "set-services") return setServices(options, positionals, home);
+		if (sub === "remove") return remove(options, positionals, home);
+		if (sub === "list") return list(options, home);
+		if (sub === void 0) throw new UsageError(USAGE);
+		throw new UsageError(`error: unknown group subcommand '${sub}' (known: add, set-services, remove, list)`);
+	} catch (err) {
+		return reportCliError(err);
+	}
+}
+function add(options, positionals, home) {
+	const name = positionals[1];
+	if (name === void 0) throw new UsageError("error: group add requires a <name> argument");
+	const services = multi(options.service);
+	const maxConcurrency = options["max-concurrency"] === void 0 ? void 0 : parsePositiveInt(str(options["max-concurrency"]), "max-concurrency");
+	const dailyRequests = options["daily-requests"] === void 0 ? void 0 : parsePositiveInt(str(options["daily-requests"]), "daily-requests");
+	const group = openStore(resolveDataDir(str(options.data), home)).addGroup(name, services, maxConcurrency === void 0 && dailyRequests === void 0 ? void 0 : {
+		maxConcurrency,
+		dailyRequests
+	});
+	const limits = group.limits === void 0 ? "unlimited" : `maxConcurrency=${group.limits.maxConcurrency ?? "-"}, dailyRequests=${group.limits.dailyRequests ?? "-"}`;
+	process.stdout.write([
+		`group added: ${group.name}`,
+		`  services: ${services.length > 0 ? services.join(", ") : "(none yet)"}`,
+		`  limits  : ${limits}`,
+		""
+	].join("\n"));
+	return 0;
+}
+function setServices(options, positionals, home) {
+	const name = positionals[1];
+	if (name === void 0) throw new UsageError("error: group set-services requires a <name> argument");
+	const services = multi(options.service);
+	if (services.length === 0) throw new UsageError("error: group set-services requires at least one --service <serviceName> (use the store API to empty a group)");
+	const store = openStore(resolveDataDir(str(options.data), home));
+	const group = store.setGroupServices(name, services);
+	const names = group.serviceIds.map((id) => store.getService(id)?.name ?? id).join(", ");
+	process.stdout.write(`group updated: ${group.name}\n  services: ${names}\n`);
+	return 0;
+}
+function remove(options, positionals, home) {
+	const name = positionals[1];
+	if (name === void 0) throw new UsageError("error: group remove requires a <name> argument");
+	openStore(resolveDataDir(str(options.data), home)).removeGroup(name);
+	process.stdout.write(`group removed: ${name}\n`);
+	return 0;
+}
+function list(options, home) {
+	const store = openStore(resolveDataDir(str(options.data), home));
+	const groups = store.listGroups();
+	if (groups.length === 0) {
+		process.stdout.write("no groups configured (see: ai-fly group add)\n");
+		return 0;
+	}
+	const serviceNames = new Map(store.listServices().map((s) => [s.serviceId, s.name]));
+	const keys = store.listKeys();
+	const lines = [];
+	for (const g of groups) {
+		const members = g.serviceIds.map((id) => serviceNames.get(id) ?? id).join(", ");
+		const limits = g.limits === void 0 ? "unlimited" : `maxConcurrency=${g.limits.maxConcurrency ?? "-"}, dailyRequests=${g.limits.dailyRequests ?? "-"}`;
+		const activeKeys = keys.filter((k) => k.group === g.name && k.revokedAt === void 0).length;
+		lines.push(`${g.name}  (services: ${members || "(none)"}; keys active: ${activeKeys}; limits: ${limits})`);
+	}
+	process.stdout.write(`${lines.join("\n")}\n`);
+	return 0;
+}
+//#endregion
+export { run };

package/dist/import-BVAFw5Tx.mjs

@@ -0,0 +1,63 @@
+import { n as UsageError } from "./errors-BGtxPkM7.mjs";
+import { o as parseArgv } from "./config-CO3WyW2H.mjs";
+import { a as ringsForRun, c as consumersRoot, i as printListeners, n as ctxHomedir, o as waitForSignals, p as listKeyrings, r as ctxOut, t as createSdkFabricFactory } from "./common-4VeA_3wo.mjs";
+import { a as importLink, i as formatLinkPreview, n as decodeShareLink, r as formatKeyringSummary } from "./join-B9op0juF.mjs";
+import { n as createFabricProviderTransport, t as startEngine } from "./runtime-Dg4en1D8.mjs";
+import { homedir } from "node:os";
+//#region src/cli/commands/consumer/import.ts
+async function run(argv, ctx = {}) {
+	const { options, positionals } = parseArgv(argv, {
+		data: {
+			type: "string",
+			tilde: true
+		},
+		preview: { type: "boolean" },
+		run: { type: "boolean" },
+		"strict-ports": { type: "boolean" },
+		relay: { type: "multi" }
+	}, { homedir: ctx.homedir ?? homedir() });
+	const link = positionals[0];
+	if (link === void 0) throw new UsageError("error: import requires a share link argument\nusage: ai-fly import <aifly1-link> [--data <dir>] [--preview] [--run]");
+	const out = ctxOut(ctx);
+	const root = consumersRoot(options.data, ctxHomedir(ctx));
+	const payload = decodeShareLink(link);
+	if (options.preview === true) {
+		for (const line of formatLinkPreview(payload)) out(line);
+		return 0;
+	}
+	const linkRelays = payload.provider.relayUrls;
+	const flagRelays = options.relay;
+	if (flagRelays !== void 0 && flagRelays.length > 0 && linkRelays.length > 0) {
+		if (!(flagRelays.length === linkRelays.length && flagRelays.every((u) => linkRelays.includes(u)))) out("warning: --relay overrides the share link's relay entries; if the provider stays unreachable, drop the flag to use the link's entries");
+	} else if (linkRelays.length > 0) out(`relay: using ${linkRelays.length} entry URL(s) from the share link (override with --relay)`);
+	const factory = await createSdkFabricFactory(flagRelays, ctx, linkRelays);
+	const result = await importLink(link, {
+		consumersRoot: root,
+		fabric: factory
+	});
+	out(result.redeemed ? "invite redeemed - fabric identity created" : "existing fabric identity reused - invite not consumed");
+	for (const line of formatKeyringSummary(result.ring)) out(line);
+	if (options.run === true) {
+		const { rings, warnings } = listKeyrings(root);
+		for (const w of warnings) out(`warning: ${w}`);
+		const engine = await startEngine({
+			rings: ringsForRun(rings),
+			consumersRoot: root,
+			sessionFactoryFor: (ring) => createFabricProviderTransport(factory, {
+				dataDir: `${root}/${ring.endpointId.slice(0, 8)}/fabric`,
+				providerEndpointId: ring.endpointId,
+				...ring.relayUrls.length > 0 ? { relayUrls: ring.relayUrls } : {}
+			}),
+			strictPorts: options["strict-ports"] === true,
+			onNotice: out
+		});
+		printListeners(out, engine.gateway.listenerInfo());
+		out("gateway running - press Ctrl-C to stop");
+		await waitForSignals();
+		await engine.stop();
+		out("gateway stopped");
+	}
+	return 0;
+}
+//#endregion
+export { run };

package/dist/join-B9op0juF.mjs

@@ -0,0 +1,228 @@
+import { t as CliError } from "./errors-BGtxPkM7.mjs";
+import { i as randomZ32, r as decodeZ32 } from "./config-CO3WyW2H.mjs";
+import { u as SERVICE_ENTRY_SCHEMA } from "./sdk-C6xDRbzg.mjs";
+import { b as upsertKey, d as hasFabricIdentity, f as keyringDir, h as mergeImportView, l as fabricDir, m as loadKeyring, u as findKeyringDir, v as saveKeyring } from "./common-4VeA_3wo.mjs";
+import { existsSync, mkdirSync, renameSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { z } from "zod";
+//#region src/consumer/join.ts
+const SHARE_LINK_PREFIX = "aifly1.";
+const KEY_PREFIX = "sk-aifly-";
+const INVITE_PREFIX = "dweb1.";
+/** base64url 字符集（解码前先做形态校验，拒绝 Buffer 宽容解析）。 */
+const BASE64URL_RE = /^[A-Za-z0-9_-]+$/;
+const LINK_PAYLOAD_SCHEMA = z.strictObject({
+	v: z.literal(1),
+	invite: z.string().refine((s) => s.startsWith("dweb1.") && s.length > 6, { message: `invite must be a '${INVITE_PREFIX}' token` }),
+	key: z.string().refine((s) => s.startsWith("sk-aifly-") && s.length > 9, { message: `key must be a '${KEY_PREFIX}' secret` }),
+	keyId: z.string().min(1).max(128),
+	provider: z.strictObject({
+		alias: z.string().min(1).max(256),
+		endpointId: z.string().min(8).max(128),
+		relayUrls: z.array(z.string().min(1).max(2048))
+	}),
+	group: z.string().min(1).max(256),
+	services: z.array(SERVICE_ENTRY_SCHEMA).max(256)
+});
+/** 解码 aifly1.<base64url(payload JSON)>；任何坏形态以 CliError（退出码 1）报出。 */
+function decodeShareLink(link) {
+	if (!link.startsWith("aifly1.")) throw new CliError(`error: not an ai-fly share link (expected '${SHARE_LINK_PREFIX}<base64url>)`);
+	const body = link.slice(7);
+	if (body.length === 0 || !BASE64URL_RE.test(body)) throw new CliError("error: share link payload is not valid base64url");
+	let json;
+	try {
+		json = JSON.parse(Buffer.from(body, "base64url").toString("utf8"));
+	} catch {
+		throw new CliError("error: share link payload is not valid JSON");
+	}
+	const parsed = LINK_PAYLOAD_SCHEMA.safeParse(json);
+	if (!parsed.success) {
+		const first = parsed.error.issues[0];
+		const where = first?.path.length ? ` at ${first.path.join(".")}` : "";
+		throw new CliError(`error: share link payload failed validation${where}: ${first?.message ?? "unknown"}`);
+	}
+	return parsed.data;
+}
+/** --preview 摘要（纯文本、英文 ASCII、零网络）。 */
+function formatLinkPreview(payload) {
+	const lines = [];
+	lines.push(`provider : ${payload.provider.alias} (${payload.provider.endpointId})`);
+	lines.push(`group    : ${payload.group}`);
+	lines.push(`key id   : ${payload.keyId}`);
+	lines.push(`relay    : ${payload.provider.relayUrls.length > 0 ? payload.provider.relayUrls.join(", ") : "(none)"}`);
+	lines.push(`services :`);
+	for (const s of payload.services) {
+		const match = s.match.map((m) => `${m.type}:${m.value}`).join("|");
+		lines.push(`  - ${s.name}  [${s.serviceId}]  default port ${s.defaultPort}${match ? `  (${match})` : ""}`);
+	}
+	lines.push("note: this link embeds a secret key - treat it like a password");
+	return lines;
+}
+/**
+* 设备入网：staging 目录先行兑换（失败即弃），成功后从名册识别提供者（root：
+* 非自身成员中 sinceMs 最早者），把 fabric 身份目录归位到 <endpointId8>/fabric 并
+* 写入空钥环骨架。既有身份则丢弃 staging 并提示（令牌已被消耗属 fabric 语义）。
+*/
+async function joinDevice(token, root, deps) {
+	if (!token.startsWith("dweb1.")) throw new CliError(`error: not a fabric invite token (expected '${INVITE_PREFIX}...')`);
+	const staging = join(root, `.join-staging-${randomZ32(4)}`);
+	let fabric;
+	try {
+		mkdirSync(staging, { recursive: true });
+		fabric = await deps.fabric.joinWithToken({ dataDir: staging }, token);
+	} catch (err) {
+		rmSync(staging, {
+			recursive: true,
+			force: true
+		});
+		throw new CliError(`error: join failed: ${err.message}`);
+	}
+	try {
+		const me = fabric.endpointId;
+		const provider = (await fabric.members()).filter((m) => m.endpointId !== me).sort((a, b) => a.sinceMs - b.sinceMs)[0];
+		if (provider === void 0) throw new CliError("error: joined fabric has no provider member (nothing to consume)");
+		const target = keyringDir(root, provider.endpointId);
+		if (hasFabricIdentity(root, provider.endpointId)) {
+			const existing = loadKeyring(root, provider.endpointId);
+			const alias = existing?.alias ?? provider.displayName ?? provider.endpointId.slice(0, 8);
+			const ring = existing ?? {
+				alias,
+				endpointId: provider.endpointId,
+				relayUrls: [],
+				keys: [],
+				services: [],
+				ports: {}
+			};
+			if (existing === void 0) saveKeyring(root, ring);
+			return {
+				ring,
+				provider,
+				alreadyJoined: true
+			};
+		}
+		mkdirSync(keyringDir(root, provider.endpointId), { recursive: true });
+		rmSync(join(target, "fabric"), {
+			recursive: true,
+			force: true
+		});
+		renameSync(staging, fabricDir(root, provider.endpointId));
+		const ring = {
+			alias: provider.displayName && provider.displayName.length > 0 ? provider.displayName : provider.endpointId.slice(0, 8),
+			endpointId: provider.endpointId,
+			relayUrls: [],
+			keys: [],
+			services: [],
+			ports: {}
+		};
+		const existing = loadKeyring(root, provider.endpointId);
+		saveKeyring(root, existing ?? ring);
+		return {
+			ring: existing ?? ring,
+			provider,
+			alreadyJoined: false
+		};
+	} finally {
+		await fabric.shutdown().catch(() => void 0);
+		rmSync(staging, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+/** 裸密钥格式校验：sk-aifly-<z32(32B)>（z32 严格解码拒绝非规范形）。 */
+function assertKeyFormat(key) {
+	if (!key.startsWith("sk-aifly-")) throw new CliError(`error: not an ai-fly key (expected '${KEY_PREFIX}<z32>)`);
+	const body = key.slice(9);
+	try {
+		const bytes = decodeZ32(body);
+		if (bytes.length !== 32) throw new Error(`expected 32 bytes, got ${bytes.length}`);
+	} catch (err) {
+		throw new CliError(`error: invalid key format: ${err.message}`);
+	}
+}
+/**
+* 裸密钥入环：定位已入网提供者（endpointId / 8 字符前缀 / 别名；要求已有 fabric
+* 身份或既有钥环），未找到报错并指引先 join/import。keyId/group 由下次 AUTH_OK 回填。
+*/
+function addKey(key, providerRef, root) {
+	assertKeyFormat(key);
+	const dir = findKeyringDir(root, providerRef);
+	if (dir === void 0) throw new CliError(`error: provider '${providerRef}' is not joined on this machine - run 'ai-fly join <invite>' or 'ai-fly import <link>' first (a bare key carries no network info)`);
+	const ring = loadKeyring(root, providerRef);
+	if (ring === void 0) throw new CliError(`error: provider '${providerRef}' has no readable keyring at ${dir}`);
+	if (!hasFabricIdentity(root, ring.endpointId)) throw new CliError(`error: provider '${ring.alias}' has keys but no fabric identity - run 'ai-fly join <invite>' first`);
+	const result = upsertKey(ring, {
+		keyId: "",
+		key,
+		group: ""
+	});
+	saveKeyring(root, result.ring);
+	return {
+		ring: result.ring,
+		added: result.added
+	};
+}
+/**
+* 组合链接导入：本机已有该 endpointId 的 fabric 目录 → Fabric.open 校验既有身份、
+* 跳过兑换；否则 Fabric.joinWithToken 兑换（失败整体回收新目录）。两种路径统一
+* 将链接内 {key,keyId,group} 入环、链接服务视图并入后持久化。
+*/
+async function importLink(link, opts) {
+	const payload = decodeShareLink(link);
+	const root = opts.consumersRoot;
+	const target = keyringDir(root, payload.provider.endpointId);
+	const fabricPath = fabricDir(root, payload.provider.endpointId);
+	let redeemed = false;
+	if (hasFabricIdentity(root, payload.provider.endpointId)) try {
+		await (await opts.fabric.open({ dataDir: fabricPath })).shutdown().catch(() => void 0);
+	} catch (err) {
+		throw new CliError(`error: existing fabric identity for '${payload.provider.alias}' failed to load: ${err.message}`);
+	}
+	else {
+		redeemed = true;
+		const created = !existsSync(target);
+		try {
+			mkdirSync(target, { recursive: true });
+			await (await opts.fabric.joinWithToken({ dataDir: fabricPath }, payload.invite)).shutdown().catch(() => void 0);
+		} catch (err) {
+			if (created) rmSync(target, {
+				recursive: true,
+				force: true
+			});
+			else rmSync(fabricPath, {
+				recursive: true,
+				force: true
+			});
+			throw new CliError(`error: import failed: ${err.message}`);
+		}
+	}
+	const existing = loadKeyring(root, payload.provider.endpointId);
+	const { ring } = mergeImportView(existing, {
+		...payload.provider,
+		services: payload.services
+	}, {
+		keyId: payload.keyId,
+		key: payload.key,
+		group: payload.group
+	});
+	saveKeyring(root, ring);
+	return {
+		ring,
+		payload,
+		redeemed
+	};
+}
+/** 导入/入环后打印的钥环摘要行（别名/EndpointId/relay/分组服务与默认端口）。 */
+function formatKeyringSummary(ring, extra) {
+	const lines = [];
+	lines.push(`provider  : ${ring.alias} (${ring.endpointId})`);
+	lines.push(`relay     : ${ring.relayUrls.length > 0 ? ring.relayUrls.join(", ") : "(none)"}`);
+	lines.push(`keyring   : ${ring.keys.length} key(s)${ring.keys.length > 0 ? ` - ${[...new Set(ring.keys.map((k) => k.group).filter((g) => g !== ""))].join(", ")}` : ""}`);
+	lines.push(`services  :`);
+	if (ring.services.length === 0) lines.push(`  (none yet - run 'ai-fly run' to connect and fetch the catalog)`);
+	for (const s of ring.services) lines.push(`  - ${s.name}  [${s.serviceId}]  default port ${s.defaultPort}`);
+	if (extra !== void 0) lines.push(...extra);
+	return lines;
+}
+//#endregion
+export { importLink as a, formatLinkPreview as i, decodeShareLink as n, joinDevice as o, formatKeyringSummary as r, addKey as t };

package/dist/join-E1_-Rt-7.mjs

@@ -0,0 +1,32 @@
+import { n as UsageError } from "./errors-BGtxPkM7.mjs";
+import { o as parseArgv } from "./config-CO3WyW2H.mjs";
+import { c as consumersRoot, n as ctxHomedir, r as ctxOut, t as createSdkFabricFactory } from "./common-4VeA_3wo.mjs";
+import { o as joinDevice } from "./join-B9op0juF.mjs";
+import { homedir } from "node:os";
+//#region src/cli/commands/consumer/join.ts
+async function run(argv, ctx = {}) {
+	const { options, positionals } = parseArgv(argv, {
+		data: {
+			type: "string",
+			tilde: true
+		},
+		relay: { type: "multi" }
+	}, { homedir: ctx.homedir ?? homedir() });
+	const token = positionals[0];
+	if (token === void 0) throw new UsageError("error: join requires an invite token argument\nusage: ai-fly join <dweb1-token> [--data <dir>]");
+	const out = ctxOut(ctx);
+	const root = consumersRoot(options.data, ctxHomedir(ctx));
+	const factory = await createSdkFabricFactory(options.relay, ctx);
+	const result = await joinDevice(token, root, { fabric: factory });
+	if (result.alreadyJoined) {
+		out(`already joined to provider '${result.ring.alias}' (${result.ring.endpointId})`);
+		out("note: the invite token was consumed by this redemption; the existing identity was kept");
+	} else {
+		out(`joined to provider '${result.ring.alias}' (${result.ring.endpointId})`);
+		out(`fabric identity: ${root}/${result.ring.endpointId.slice(0, 8)}/fabric`);
+		out("no keys in the keyring yet - get a share link (ai-fly import <aifly1.>) or a bare key (ai-fly key add)");
+	}
+	return 0;
+}
+//#endregion
+export { run };

package/dist/key-Bt4EWiuO.mjs

@@ -0,0 +1,31 @@
+import { n as UsageError } from "./errors-BGtxPkM7.mjs";
+import { o as parseArgv } from "./config-CO3WyW2H.mjs";
+import { c as consumersRoot, n as ctxHomedir, r as ctxOut } from "./common-4VeA_3wo.mjs";
+import { r as formatKeyringSummary, t as addKey } from "./join-B9op0juF.mjs";
+import { homedir } from "node:os";
+//#region src/cli/commands/consumer/key.ts
+async function run(argv, ctx = {}) {
+	const sub = argv[0];
+	if (sub === void 0) throw new UsageError("error: key requires a subcommand\nusage (consumer): ai-fly key add <sk-aifly-key> --provider <id|alias>\nusage (provider): ai-fly key issue|list|revoke --group <name>");
+	if (sub !== "add") throw new UsageError(`error: 'key ${sub}' is a provider-side subcommand (issue/list/revoke run on the provider machine)\nusage (consumer): ai-fly key add <sk-aifly-key> --provider <id|alias>`);
+	const { options, positionals } = parseArgv(argv.slice(1), {
+		data: {
+			type: "string",
+			tilde: true
+		},
+		provider: { type: "string" }
+	}, { homedir: ctx.homedir ?? homedir() });
+	const key = positionals[0];
+	if (key === void 0) throw new UsageError("error: key add requires a key argument\nusage: ai-fly key add <sk-aifly-key> --provider <id|alias>");
+	const provider = options.provider;
+	if (provider === void 0) throw new UsageError("error: --provider is required (endpointId, 8-char prefix, or alias)");
+	const out = ctxOut(ctx);
+	const root = consumersRoot(options.data, ctxHomedir(ctx));
+	const result = addKey(key, provider, root);
+	out(result.added ? "key added to keyring" : "key updated in keyring (existing entry)");
+	for (const line of formatKeyringSummary(result.ring)) out(line);
+	out("note: key id and group metadata are filled in on the next successful authorization");
+	return 0;
+}
+//#endregion
+export { run };