@aigne/aos 0.2.0-beta

package/dist/blocklet/types.d.cts

@@ -0,0 +1,70 @@
+import { AFSModule, AFSRoot, BlockletManifest } from "@aigne/afs";
+
+//#region src/blocklet/types.d.ts
+/** Information about a discovered blocklet. */
+interface BlockletInfo {
+  /** Unique identifier (from manifest.id) */
+  id: string;
+  /** Human-readable name (from manifest.name) */
+  name: string;
+  /** Parsed manifest */
+  manifest: BlockletManifest;
+  /** Where the blocklet was discovered */
+  source: "local" | "embedded" | "remote";
+  /** Mount path in the global AFS namespace */
+  mountPath: string;
+  /** Filesystem path (Node only, for module: mounts) */
+  diskPath?: string;
+}
+/**
+ * Runtime-specific blocklet discovery and loading.
+ *
+ * Each runtime implements this:
+ * - Node: scans blocklets/ directory, uses dynamic import()
+ * - CF: reads from worker bundle or R2
+ */
+interface BlockletLoader {
+  /** Discover available blocklets */
+  discover(): Promise<BlockletInfo[]>;
+  /** Load a blocklet's provider module */
+  loadProvider(blockletId: string, providerSpec: string): Promise<AFSModule>;
+}
+/** Credential store abstraction — runtime provides vault-backed implementation. */
+interface BlockletCredentialStore {
+  get(key: string): Promise<Record<string, string> | undefined>;
+  set(key: string, credentials: Record<string, string>): Promise<void>;
+  delete(key: string): Promise<boolean>;
+}
+/** Trigger specification discovered from ASH scripts. */
+interface TriggerSpec {
+  kind: "event" | "cron";
+  scriptPath: string;
+  jobName: string;
+  path?: string;
+  event?: string;
+  expression?: string;
+}
+/**
+ * Platform-specific hooks injected by runtime during blocklet activation.
+ * All hooks are optional — missing hooks mean the feature is unavailable.
+ */
+interface ActivationHooks {
+  /** Called when a blocklet declares a domain binding */
+  onDomainBind?(blockletId: string, domain: string): Promise<void>;
+  /** Called when a blocklet's domain binding is removed */
+  onDomainUnbind?(blockletId: string, domain: string): Promise<void>;
+  /** Called when a blocklet needs credentials for a provider */
+  onCredentialNeeded?(blockletId: string, providerSpec: string): Promise<BlockletCredentialStore | null>;
+  /** Called when ASH triggers are discovered in a blocklet */
+  onTriggersDiscovered?(blockletId: string, triggers: TriggerSpec[]): void;
+}
+/** Internal state for an activated blocklet instance. */
+interface ActivatedBlocklet {
+  info: BlockletInfo;
+  runtimeAFS: AFSRoot;
+  ownedProviders: AFSModule[];
+  domains: string[];
+}
+//#endregion
+export { ActivatedBlocklet, ActivationHooks, BlockletCredentialStore, BlockletInfo, BlockletLoader, TriggerSpec };
+//# sourceMappingURL=types.d.cts.map

package/dist/blocklet/types.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.cts","names":[],"sources":["../../src/blocklet/types.ts"],"mappings":";;;;UAciB,YAAA;EAMf;EAJA,EAAA;EAMA;EAJA,IAAA;EAQA;EANA,QAAA,EAAU,gBAAA;EAMF;EAJR,MAAA;EAc6B;EAZ7B,SAAA;EAcoB;EAZpB,QAAA;AAAA;;;;;;;;UAUe,cAAA;EAKkB;EAHjC,QAAA,IAAY,OAAA,CAAQ,YAAA;EAG4C;EAAhE,YAAA,CAAa,UAAA,UAAoB,YAAA,WAAuB,OAAA,CAAQ,SAAA;AAAA;AAQlE;AAAA,UAAiB,uBAAA;EACf,GAAA,CAAI,GAAA,WAAc,OAAA,CAAQ,MAAA;EAC1B,GAAA,CAAI,GAAA,UAAa,WAAA,EAAa,MAAA,mBAAyB,OAAA;EACvD,MAAA,CAAO,GAAA,WAAc,OAAA;AAAA;;UAIN,WAAA;EACf,IAAA;EACA,UAAA;EACA,OAAA;EACA,IAAA;EACA,KAAA;EACA,UAAA;AAAA;;;;;UAOe,eAAA;EAjBR;EAmBP,YAAA,EAAc,UAAA,UAAoB,MAAA,WAAiB,OAAA;EAnBvB;EAqB5B,cAAA,EAAgB,UAAA,UAAoB,MAAA,WAAiB,OAAA;EAjBtC;EAmBf,kBAAA,EACE,UAAA,UACA,YAAA,WACC,OAAA,CAAQ,uBAAA;;EAEX,oBAAA,EAAsB,UAAA,UAAoB,QAAA,EAAU,WAAA;AAAA;;UAQrC,iBAAA;EACf,IAAA,EAAM,YAAA;EACN,UAAA,EAAY,OAAA;EACZ,cAAA,EAAgB,SAAA;EAChB,OAAA;AAAA"}

package/dist/blocklet/types.d.mts

@@ -0,0 +1,70 @@
+import { AFSModule, AFSRoot, BlockletManifest } from "@aigne/afs";
+
+//#region src/blocklet/types.d.ts
+/** Information about a discovered blocklet. */
+interface BlockletInfo {
+  /** Unique identifier (from manifest.id) */
+  id: string;
+  /** Human-readable name (from manifest.name) */
+  name: string;
+  /** Parsed manifest */
+  manifest: BlockletManifest;
+  /** Where the blocklet was discovered */
+  source: "local" | "embedded" | "remote";
+  /** Mount path in the global AFS namespace */
+  mountPath: string;
+  /** Filesystem path (Node only, for module: mounts) */
+  diskPath?: string;
+}
+/**
+ * Runtime-specific blocklet discovery and loading.
+ *
+ * Each runtime implements this:
+ * - Node: scans blocklets/ directory, uses dynamic import()
+ * - CF: reads from worker bundle or R2
+ */
+interface BlockletLoader {
+  /** Discover available blocklets */
+  discover(): Promise<BlockletInfo[]>;
+  /** Load a blocklet's provider module */
+  loadProvider(blockletId: string, providerSpec: string): Promise<AFSModule>;
+}
+/** Credential store abstraction — runtime provides vault-backed implementation. */
+interface BlockletCredentialStore {
+  get(key: string): Promise<Record<string, string> | undefined>;
+  set(key: string, credentials: Record<string, string>): Promise<void>;
+  delete(key: string): Promise<boolean>;
+}
+/** Trigger specification discovered from ASH scripts. */
+interface TriggerSpec {
+  kind: "event" | "cron";
+  scriptPath: string;
+  jobName: string;
+  path?: string;
+  event?: string;
+  expression?: string;
+}
+/**
+ * Platform-specific hooks injected by runtime during blocklet activation.
+ * All hooks are optional — missing hooks mean the feature is unavailable.
+ */
+interface ActivationHooks {
+  /** Called when a blocklet declares a domain binding */
+  onDomainBind?(blockletId: string, domain: string): Promise<void>;
+  /** Called when a blocklet's domain binding is removed */
+  onDomainUnbind?(blockletId: string, domain: string): Promise<void>;
+  /** Called when a blocklet needs credentials for a provider */
+  onCredentialNeeded?(blockletId: string, providerSpec: string): Promise<BlockletCredentialStore | null>;
+  /** Called when ASH triggers are discovered in a blocklet */
+  onTriggersDiscovered?(blockletId: string, triggers: TriggerSpec[]): void;
+}
+/** Internal state for an activated blocklet instance. */
+interface ActivatedBlocklet {
+  info: BlockletInfo;
+  runtimeAFS: AFSRoot;
+  ownedProviders: AFSModule[];
+  domains: string[];
+}
+//#endregion
+export { ActivatedBlocklet, ActivationHooks, BlockletCredentialStore, BlockletInfo, BlockletLoader, TriggerSpec };
+//# sourceMappingURL=types.d.mts.map

package/dist/blocklet/types.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.mts","names":[],"sources":["../../src/blocklet/types.ts"],"mappings":";;;;UAciB,YAAA;EAMf;EAJA,EAAA;EAMA;EAJA,IAAA;EAQA;EANA,QAAA,EAAU,gBAAA;EAMF;EAJR,MAAA;EAc6B;EAZ7B,SAAA;EAcoB;EAZpB,QAAA;AAAA;;;;;;;;UAUe,cAAA;EAKkB;EAHjC,QAAA,IAAY,OAAA,CAAQ,YAAA;EAG4C;EAAhE,YAAA,CAAa,UAAA,UAAoB,YAAA,WAAuB,OAAA,CAAQ,SAAA;AAAA;AAQlE;AAAA,UAAiB,uBAAA;EACf,GAAA,CAAI,GAAA,WAAc,OAAA,CAAQ,MAAA;EAC1B,GAAA,CAAI,GAAA,UAAa,WAAA,EAAa,MAAA,mBAAyB,OAAA;EACvD,MAAA,CAAO,GAAA,WAAc,OAAA;AAAA;;UAIN,WAAA;EACf,IAAA;EACA,UAAA;EACA,OAAA;EACA,IAAA;EACA,KAAA;EACA,UAAA;AAAA;;;;;UAOe,eAAA;EAjBR;EAmBP,YAAA,EAAc,UAAA,UAAoB,MAAA,WAAiB,OAAA;EAnBvB;EAqB5B,cAAA,EAAgB,UAAA,UAAoB,MAAA,WAAiB,OAAA;EAjBtC;EAmBf,kBAAA,EACE,UAAA,UACA,YAAA,WACC,OAAA,CAAQ,uBAAA;;EAEX,oBAAA,EAAsB,UAAA,UAAoB,QAAA,EAAU,WAAA;AAAA;;UAQrC,iBAAA;EACf,IAAA,EAAM,YAAA;EACN,UAAA,EAAY,OAAA;EACZ,cAAA,EAAgB,SAAA;EAChB,OAAA;AAAA"}

package/dist/devices/chain.cjs

@@ -0,0 +1,127 @@
+let ufo = require("ufo");
+
+//#region src/devices/chain.ts
+/**
+* Chain device helpers.
+*
+* Phase 1 of `planning/chain-as-device-placement` — pure helpers for
+* normalizing chain network configurations into AFS `MountEntry` form.
+*
+* Source contracts:
+* - `planning/chain-as-device-placement/schema.md` §三 / §四 (decisions)
+* - `planning/chain-as-device-placement/README.md` §3.5 / §3.6 (rules)
+* - `docs/architecture/chain-as-device.md` §4.2 (placement)
+*
+* Helpers are runtime-agnostic: Node daemon and CF worker both consume them.
+* They do NOT instantiate AFSOCAP nor mount anything — that lives in
+* runtime-specific setup glue (Phase 2 / 5).
+*/
+/** Mount path prefix for chain devices: `/dev/chain`. */
+const CHAIN_DEVICE_PREFIX = "/dev/chain";
+const MAX_NETWORK_NAME_LENGTH = 128;
+const MAX_ENDPOINT_LENGTH = 2048;
+const MAX_CONFIGS_LENGTH = 1e3;
+const NETWORK_NAME_RE = /^[a-z][a-z0-9-]*$/;
+const RESERVED_NETWORK_NAMES = new Set([
+	"__proto__",
+	"constructor",
+	"prototype"
+]);
+const ALLOWED_ENDPOINT_SCHEMES = new Set(["http:", "https:"]);
+/**
+* Built-in default networks injected when no user configuration is provided.
+*
+* Deeply frozen (array + each element) so accidental mutation throws in
+* strict mode rather than silently corrupting shared defaults.
+*/
+const BUILTIN_CHAIN_NETWORKS = Object.freeze([Object.freeze({
+	network: "main",
+	endpoint: "https://main.abtnetwork.io/api"
+}), Object.freeze({
+	network: "beta",
+	endpoint: "https://beta.abtnetwork.io/api"
+})]);
+/**
+* Sanitize a value for inclusion in error messages: truncate long input and
+* escape control characters so a hostile name cannot smuggle ANSI escapes
+* or null bytes into log lines.
+*/
+function safeLabel(value, max = 64) {
+	const str = typeof value === "string" ? value : String(value);
+	const truncated = str.length > max ? `${str.slice(0, max)}…` : str;
+	let out = "";
+	for (let i = 0; i < truncated.length; i++) {
+		const code = truncated.charCodeAt(i);
+		if (code < 32 || code === 127) out += `\\x${code.toString(16).padStart(2, "0")}`;
+		else out += truncated[i];
+	}
+	return out;
+}
+function validateNetwork(value) {
+	if (typeof value !== "string") throw new Error(`network must be a string, got ${typeof value}`);
+	if (value.length === 0) throw new Error("network name must be non-empty");
+	if (value.length > MAX_NETWORK_NAME_LENGTH) throw new Error(`network name too long: ${value.length} > ${MAX_NETWORK_NAME_LENGTH}`);
+	if (RESERVED_NETWORK_NAMES.has(value)) throw new Error(`network "${safeLabel(value)}" is a reserved identifier`);
+	if (!NETWORK_NAME_RE.test(value)) throw new Error(`network "${safeLabel(value)}" invalid: must match ^[a-z][a-z0-9-]*$`);
+	return value;
+}
+function validateEndpoint(endpoint, network) {
+	if (typeof endpoint !== "string") throw new Error(`endpoint must be a string for network "${safeLabel(network)}"`);
+	if (endpoint.length === 0) throw new Error(`endpoint required for network "${safeLabel(network)}"`);
+	if (endpoint.length > MAX_ENDPOINT_LENGTH) throw new Error(`endpoint too long: ${endpoint.length} > ${MAX_ENDPOINT_LENGTH}`);
+	let url;
+	try {
+		url = new URL(endpoint);
+	} catch {
+		throw new Error(`endpoint for network "${safeLabel(network)}" is not a valid URL`);
+	}
+	if (!ALLOWED_ENDPOINT_SCHEMES.has(url.protocol)) {
+		const scheme = url.protocol.replace(/:$/, "");
+		throw new Error(`endpoint scheme not allowed: ${safeLabel(scheme, 16)}`);
+	}
+	if (url.username || url.password) throw new Error("endpoint must not contain basic auth credentials");
+}
+/**
+* Validate an array of `ChainNetworkConfig`.
+*
+* Throws a standard `Error` on any violation. Error messages are
+* sanitized — they never include the path / query string / fragment of an
+* endpoint, so a misconfigured token cannot leak into daemon logs.
+*
+* Pure function: input array and elements are not mutated.
+*/
+function validateChainNetworks(configs) {
+	if (!Array.isArray(configs)) throw new Error("chain configs must be an array");
+	if (configs.length > MAX_CONFIGS_LENGTH) throw new Error(`chain configs exceed limit: ${configs.length} > ${MAX_CONFIGS_LENGTH}`);
+	const seen = /* @__PURE__ */ new Set();
+	for (let i = 0; i < configs.length; i++) {
+		const cfg = configs[i];
+		if (cfg === null || typeof cfg !== "object") throw new Error(`chain configs[${i}] must be an object`);
+		const name = validateNetwork(cfg.network);
+		validateEndpoint(cfg.endpoint, name);
+		if (seen.has(name)) throw new Error(`network "${safeLabel(name)}" duplicated`);
+		seen.add(name);
+	}
+}
+/**
+* Normalize one `ChainNetworkConfig` to a `MountEntry`.
+*
+* Pure function: the input config is not mutated, and each call returns a
+* fresh independent `MountEntry` with no shared object references.
+*
+* Validation is the caller's responsibility — invoke
+* `validateChainNetworks` before normalization in setup paths.
+*/
+function chainNetworkToMountEntry(cfg) {
+	return {
+		path: (0, ufo.joinURL)(CHAIN_DEVICE_PREFIX, cfg.network),
+		provider: "ocap",
+		options: { endpoint: cfg.endpoint }
+	};
+}
+
+//#endregion
+exports.BUILTIN_CHAIN_NETWORKS = BUILTIN_CHAIN_NETWORKS;
+exports.CHAIN_DEVICE_PREFIX = CHAIN_DEVICE_PREFIX;
+exports.chainNetworkToMountEntry = chainNetworkToMountEntry;
+exports.validateChainNetworks = validateChainNetworks;

package/dist/devices/chain.d.cts

@@ -0,0 +1,48 @@
+import { MountEntry } from "../mount-config.cjs";
+
+//#region src/devices/chain.d.ts
+/** Mount path prefix for chain devices: `/dev/chain`. */
+declare const CHAIN_DEVICE_PREFIX = "/dev/chain";
+/**
+ * One chain network configuration entry.
+ *
+ * Cross-runtime contract: the same shape is consumed by the Node daemon
+ * (`[[devices.chain]]` TOML section) and CF worker (post-normalization of
+ * `AFS_MOUNTS`). See schema.md §3.3 for the normalization table.
+ */
+interface ChainNetworkConfig {
+  /** Network name. Must match `^[a-z][a-z0-9-]*$`, ≤128 chars. */
+  network: string;
+  /** OCAP HTTP endpoint URL. Scheme ∈ {http, https}, ≤2048 chars, no basic auth. */
+  endpoint: string;
+}
+/**
+ * Built-in default networks injected when no user configuration is provided.
+ *
+ * Deeply frozen (array + each element) so accidental mutation throws in
+ * strict mode rather than silently corrupting shared defaults.
+ */
+declare const BUILTIN_CHAIN_NETWORKS: readonly ChainNetworkConfig[];
+/**
+ * Validate an array of `ChainNetworkConfig`.
+ *
+ * Throws a standard `Error` on any violation. Error messages are
+ * sanitized — they never include the path / query string / fragment of an
+ * endpoint, so a misconfigured token cannot leak into daemon logs.
+ *
+ * Pure function: input array and elements are not mutated.
+ */
+declare function validateChainNetworks(configs: ChainNetworkConfig[]): void;
+/**
+ * Normalize one `ChainNetworkConfig` to a `MountEntry`.
+ *
+ * Pure function: the input config is not mutated, and each call returns a
+ * fresh independent `MountEntry` with no shared object references.
+ *
+ * Validation is the caller's responsibility — invoke
+ * `validateChainNetworks` before normalization in setup paths.
+ */
+declare function chainNetworkToMountEntry(cfg: ChainNetworkConfig): MountEntry;
+//#endregion
+export { BUILTIN_CHAIN_NETWORKS, CHAIN_DEVICE_PREFIX, ChainNetworkConfig, chainNetworkToMountEntry, validateChainNetworks };
+//# sourceMappingURL=chain.d.cts.map

package/dist/devices/chain.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chain.d.cts","names":[],"sources":["../../src/devices/chain.ts"],"mappings":";;;;cAoBa,mBAAA;AAkHb;;;;;AAgCA;;AAhCA,UA9FiB,kBAAA;EA8H4D;EA5H3E,OAAA;EA4HuC;EA1HvC,QAAA;AAAA;;;;;;;cASW,sBAAA,WAAiC,kBAAA;;;;;;;;;;iBAiF9B,qBAAA,CAAsB,OAAA,EAAS,kBAAA;;;;;;;;;;iBAgC/B,wBAAA,CAAyB,GAAA,EAAK,kBAAA,GAAqB,UAAA"}

package/dist/devices/chain.d.mts

@@ -0,0 +1,48 @@
+import { MountEntry } from "../mount-config.mjs";
+
+//#region src/devices/chain.d.ts
+/** Mount path prefix for chain devices: `/dev/chain`. */
+declare const CHAIN_DEVICE_PREFIX = "/dev/chain";
+/**
+ * One chain network configuration entry.
+ *
+ * Cross-runtime contract: the same shape is consumed by the Node daemon
+ * (`[[devices.chain]]` TOML section) and CF worker (post-normalization of
+ * `AFS_MOUNTS`). See schema.md §3.3 for the normalization table.
+ */
+interface ChainNetworkConfig {
+  /** Network name. Must match `^[a-z][a-z0-9-]*$`, ≤128 chars. */
+  network: string;
+  /** OCAP HTTP endpoint URL. Scheme ∈ {http, https}, ≤2048 chars, no basic auth. */
+  endpoint: string;
+}
+/**
+ * Built-in default networks injected when no user configuration is provided.
+ *
+ * Deeply frozen (array + each element) so accidental mutation throws in
+ * strict mode rather than silently corrupting shared defaults.
+ */
+declare const BUILTIN_CHAIN_NETWORKS: readonly ChainNetworkConfig[];
+/**
+ * Validate an array of `ChainNetworkConfig`.
+ *
+ * Throws a standard `Error` on any violation. Error messages are
+ * sanitized — they never include the path / query string / fragment of an
+ * endpoint, so a misconfigured token cannot leak into daemon logs.
+ *
+ * Pure function: input array and elements are not mutated.
+ */
+declare function validateChainNetworks(configs: ChainNetworkConfig[]): void;
+/**
+ * Normalize one `ChainNetworkConfig` to a `MountEntry`.
+ *
+ * Pure function: the input config is not mutated, and each call returns a
+ * fresh independent `MountEntry` with no shared object references.
+ *
+ * Validation is the caller's responsibility — invoke
+ * `validateChainNetworks` before normalization in setup paths.
+ */
+declare function chainNetworkToMountEntry(cfg: ChainNetworkConfig): MountEntry;
+//#endregion
+export { BUILTIN_CHAIN_NETWORKS, CHAIN_DEVICE_PREFIX, ChainNetworkConfig, chainNetworkToMountEntry, validateChainNetworks };
+//# sourceMappingURL=chain.d.mts.map

package/dist/devices/chain.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chain.d.mts","names":[],"sources":["../../src/devices/chain.ts"],"mappings":";;;;cAoBa,mBAAA;AAkHb;;;;;AAgCA;;AAhCA,UA9FiB,kBAAA;EA8H4D;EA5H3E,OAAA;EA4HuC;EA1HvC,QAAA;AAAA;;;;;;;cASW,sBAAA,WAAiC,kBAAA;;;;;;;;;;iBAiF9B,qBAAA,CAAsB,OAAA,EAAS,kBAAA;;;;;;;;;;iBAgC/B,wBAAA,CAAyB,GAAA,EAAK,kBAAA,GAAqB,UAAA"}

package/dist/devices/chain.mjs

@@ -0,0 +1,125 @@
+import { joinURL } from "ufo";
+
+//#region src/devices/chain.ts
+/**
+* Chain device helpers.
+*
+* Phase 1 of `planning/chain-as-device-placement` — pure helpers for
+* normalizing chain network configurations into AFS `MountEntry` form.
+*
+* Source contracts:
+* - `planning/chain-as-device-placement/schema.md` §三 / §四 (decisions)
+* - `planning/chain-as-device-placement/README.md` §3.5 / §3.6 (rules)
+* - `docs/architecture/chain-as-device.md` §4.2 (placement)
+*
+* Helpers are runtime-agnostic: Node daemon and CF worker both consume them.
+* They do NOT instantiate AFSOCAP nor mount anything — that lives in
+* runtime-specific setup glue (Phase 2 / 5).
+*/
+/** Mount path prefix for chain devices: `/dev/chain`. */
+const CHAIN_DEVICE_PREFIX = "/dev/chain";
+const MAX_NETWORK_NAME_LENGTH = 128;
+const MAX_ENDPOINT_LENGTH = 2048;
+const MAX_CONFIGS_LENGTH = 1e3;
+const NETWORK_NAME_RE = /^[a-z][a-z0-9-]*$/;
+const RESERVED_NETWORK_NAMES = new Set([
+	"__proto__",
+	"constructor",
+	"prototype"
+]);
+const ALLOWED_ENDPOINT_SCHEMES = new Set(["http:", "https:"]);
+/**
+* Built-in default networks injected when no user configuration is provided.
+*
+* Deeply frozen (array + each element) so accidental mutation throws in
+* strict mode rather than silently corrupting shared defaults.
+*/
+const BUILTIN_CHAIN_NETWORKS = Object.freeze([Object.freeze({
+	network: "main",
+	endpoint: "https://main.abtnetwork.io/api"
+}), Object.freeze({
+	network: "beta",
+	endpoint: "https://beta.abtnetwork.io/api"
+})]);
+/**
+* Sanitize a value for inclusion in error messages: truncate long input and
+* escape control characters so a hostile name cannot smuggle ANSI escapes
+* or null bytes into log lines.
+*/
+function safeLabel(value, max = 64) {
+	const str = typeof value === "string" ? value : String(value);
+	const truncated = str.length > max ? `${str.slice(0, max)}…` : str;
+	let out = "";
+	for (let i = 0; i < truncated.length; i++) {
+		const code = truncated.charCodeAt(i);
+		if (code < 32 || code === 127) out += `\\x${code.toString(16).padStart(2, "0")}`;
+		else out += truncated[i];
+	}
+	return out;
+}
+function validateNetwork(value) {
+	if (typeof value !== "string") throw new Error(`network must be a string, got ${typeof value}`);
+	if (value.length === 0) throw new Error("network name must be non-empty");
+	if (value.length > MAX_NETWORK_NAME_LENGTH) throw new Error(`network name too long: ${value.length} > ${MAX_NETWORK_NAME_LENGTH}`);
+	if (RESERVED_NETWORK_NAMES.has(value)) throw new Error(`network "${safeLabel(value)}" is a reserved identifier`);
+	if (!NETWORK_NAME_RE.test(value)) throw new Error(`network "${safeLabel(value)}" invalid: must match ^[a-z][a-z0-9-]*$`);
+	return value;
+}
+function validateEndpoint(endpoint, network) {
+	if (typeof endpoint !== "string") throw new Error(`endpoint must be a string for network "${safeLabel(network)}"`);
+	if (endpoint.length === 0) throw new Error(`endpoint required for network "${safeLabel(network)}"`);
+	if (endpoint.length > MAX_ENDPOINT_LENGTH) throw new Error(`endpoint too long: ${endpoint.length} > ${MAX_ENDPOINT_LENGTH}`);
+	let url;
+	try {
+		url = new URL(endpoint);
+	} catch {
+		throw new Error(`endpoint for network "${safeLabel(network)}" is not a valid URL`);
+	}
+	if (!ALLOWED_ENDPOINT_SCHEMES.has(url.protocol)) {
+		const scheme = url.protocol.replace(/:$/, "");
+		throw new Error(`endpoint scheme not allowed: ${safeLabel(scheme, 16)}`);
+	}
+	if (url.username || url.password) throw new Error("endpoint must not contain basic auth credentials");
+}
+/**
+* Validate an array of `ChainNetworkConfig`.
+*
+* Throws a standard `Error` on any violation. Error messages are
+* sanitized — they never include the path / query string / fragment of an
+* endpoint, so a misconfigured token cannot leak into daemon logs.
+*
+* Pure function: input array and elements are not mutated.
+*/
+function validateChainNetworks(configs) {
+	if (!Array.isArray(configs)) throw new Error("chain configs must be an array");
+	if (configs.length > MAX_CONFIGS_LENGTH) throw new Error(`chain configs exceed limit: ${configs.length} > ${MAX_CONFIGS_LENGTH}`);
+	const seen = /* @__PURE__ */ new Set();
+	for (let i = 0; i < configs.length; i++) {
+		const cfg = configs[i];
+		if (cfg === null || typeof cfg !== "object") throw new Error(`chain configs[${i}] must be an object`);
+		const name = validateNetwork(cfg.network);
+		validateEndpoint(cfg.endpoint, name);
+		if (seen.has(name)) throw new Error(`network "${safeLabel(name)}" duplicated`);
+		seen.add(name);
+	}
+}
+/**
+* Normalize one `ChainNetworkConfig` to a `MountEntry`.
+*
+* Pure function: the input config is not mutated, and each call returns a
+* fresh independent `MountEntry` with no shared object references.
+*
+* Validation is the caller's responsibility — invoke
+* `validateChainNetworks` before normalization in setup paths.
+*/
+function chainNetworkToMountEntry(cfg) {
+	return {
+		path: joinURL(CHAIN_DEVICE_PREFIX, cfg.network),
+		provider: "ocap",
+		options: { endpoint: cfg.endpoint }
+	};
+}
+
+//#endregion
+export { BUILTIN_CHAIN_NETWORKS, CHAIN_DEVICE_PREFIX, chainNetworkToMountEntry, validateChainNetworks };
+//# sourceMappingURL=chain.mjs.map

package/dist/devices/chain.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"chain.mjs","names":[],"sources":["../../src/devices/chain.ts"],"sourcesContent":["/**\n * Chain device helpers.\n *\n * Phase 1 of `planning/chain-as-device-placement` — pure helpers for\n * normalizing chain network configurations into AFS `MountEntry` form.\n *\n * Source contracts:\n * - `planning/chain-as-device-placement/schema.md` §三 / §四 (decisions)\n * - `planning/chain-as-device-placement/README.md` §3.5 / §3.6 (rules)\n * - `docs/architecture/chain-as-device.md` §4.2 (placement)\n *\n * Helpers are runtime-agnostic: Node daemon and CF worker both consume them.\n * They do NOT instantiate AFSOCAP nor mount anything — that lives in\n * runtime-specific setup glue (Phase 2 / 5).\n */\n\nimport { joinURL } from \"ufo\";\nimport type { MountEntry } from \"../mount-config.js\";\n\n/** Mount path prefix for chain devices: `/dev/chain`. */\nexport const CHAIN_DEVICE_PREFIX = \"/dev/chain\";\n\nconst MAX_NETWORK_NAME_LENGTH = 128;\nconst MAX_ENDPOINT_LENGTH = 2048;\nconst MAX_CONFIGS_LENGTH = 1000;\nconst NETWORK_NAME_RE = /^[a-z][a-z0-9-]*$/;\nconst RESERVED_NETWORK_NAMES: ReadonlySet<string> = new Set([\n  \"__proto__\",\n  \"constructor\",\n  \"prototype\",\n]);\nconst ALLOWED_ENDPOINT_SCHEMES: ReadonlySet<string> = new Set([\"http:\", \"https:\"]);\n\n/**\n * One chain network configuration entry.\n *\n * Cross-runtime contract: the same shape is consumed by the Node daemon\n * (`[[devices.chain]]` TOML section) and CF worker (post-normalization of\n * `AFS_MOUNTS`). See schema.md §3.3 for the normalization table.\n */\nexport interface ChainNetworkConfig {\n  /** Network name. Must match `^[a-z][a-z0-9-]*$`, ≤128 chars. */\n  network: string;\n  /** OCAP HTTP endpoint URL. Scheme ∈ {http, https}, ≤2048 chars, no basic auth. */\n  endpoint: string;\n}\n\n/**\n * Built-in default networks injected when no user configuration is provided.\n *\n * Deeply frozen (array + each element) so accidental mutation throws in\n * strict mode rather than silently corrupting shared defaults.\n */\nexport const BUILTIN_CHAIN_NETWORKS: readonly ChainNetworkConfig[] = Object.freeze([\n  Object.freeze({ network: \"main\", endpoint: \"https://main.abtnetwork.io/api\" }),\n  Object.freeze({ network: \"beta\", endpoint: \"https://beta.abtnetwork.io/api\" }),\n]);\n\n/**\n * Sanitize a value for inclusion in error messages: truncate long input and\n * escape control characters so a hostile name cannot smuggle ANSI escapes\n * or null bytes into log lines.\n */\nfunction safeLabel(value: unknown, max = 64): string {\n  const str = typeof value === \"string\" ? value : String(value);\n  const truncated = str.length > max ? `${str.slice(0, max)}…` : str;\n  let out = \"\";\n  for (let i = 0; i < truncated.length; i++) {\n    const code = truncated.charCodeAt(i);\n    if (code < 0x20 || code === 0x7f) {\n      out += `\\\\x${code.toString(16).padStart(2, \"0\")}`;\n    } else {\n      out += truncated[i];\n    }\n  }\n  return out;\n}\n\nfunction validateNetwork(value: unknown): string {\n  if (typeof value !== \"string\") {\n    throw new Error(`network must be a string, got ${typeof value}`);\n  }\n  if (value.length === 0) {\n    throw new Error(\"network name must be non-empty\");\n  }\n  if (value.length > MAX_NETWORK_NAME_LENGTH) {\n    throw new Error(`network name too long: ${value.length} > ${MAX_NETWORK_NAME_LENGTH}`);\n  }\n  if (RESERVED_NETWORK_NAMES.has(value)) {\n    throw new Error(`network \"${safeLabel(value)}\" is a reserved identifier`);\n  }\n  if (!NETWORK_NAME_RE.test(value)) {\n    throw new Error(`network \"${safeLabel(value)}\" invalid: must match ^[a-z][a-z0-9-]*$`);\n  }\n  return value;\n}\n\nfunction validateEndpoint(endpoint: unknown, network: string): void {\n  if (typeof endpoint !== \"string\") {\n    throw new Error(`endpoint must be a string for network \"${safeLabel(network)}\"`);\n  }\n  if (endpoint.length === 0) {\n    throw new Error(`endpoint required for network \"${safeLabel(network)}\"`);\n  }\n  if (endpoint.length > MAX_ENDPOINT_LENGTH) {\n    throw new Error(`endpoint too long: ${endpoint.length} > ${MAX_ENDPOINT_LENGTH}`);\n  }\n\n  let url: URL;\n  try {\n    url = new URL(endpoint);\n  } catch {\n    throw new Error(`endpoint for network \"${safeLabel(network)}\" is not a valid URL`);\n  }\n\n  if (!ALLOWED_ENDPOINT_SCHEMES.has(url.protocol)) {\n    const scheme = url.protocol.replace(/:$/, \"\");\n    throw new Error(`endpoint scheme not allowed: ${safeLabel(scheme, 16)}`);\n  }\n\n  if (url.username || url.password) {\n    throw new Error(\"endpoint must not contain basic auth credentials\");\n  }\n}\n\n/**\n * Validate an array of `ChainNetworkConfig`.\n *\n * Throws a standard `Error` on any violation. Error messages are\n * sanitized — they never include the path / query string / fragment of an\n * endpoint, so a misconfigured token cannot leak into daemon logs.\n *\n * Pure function: input array and elements are not mutated.\n */\nexport function validateChainNetworks(configs: ChainNetworkConfig[]): void {\n  if (!Array.isArray(configs)) {\n    throw new Error(\"chain configs must be an array\");\n  }\n  if (configs.length > MAX_CONFIGS_LENGTH) {\n    throw new Error(`chain configs exceed limit: ${configs.length} > ${MAX_CONFIGS_LENGTH}`);\n  }\n\n  const seen = new Set<string>();\n  for (let i = 0; i < configs.length; i++) {\n    const cfg = configs[i];\n    if (cfg === null || typeof cfg !== \"object\") {\n      throw new Error(`chain configs[${i}] must be an object`);\n    }\n    const name = validateNetwork((cfg as ChainNetworkConfig).network);\n    validateEndpoint((cfg as ChainNetworkConfig).endpoint, name);\n    if (seen.has(name)) {\n      throw new Error(`network \"${safeLabel(name)}\" duplicated`);\n    }\n    seen.add(name);\n  }\n}\n\n/**\n * Normalize one `ChainNetworkConfig` to a `MountEntry`.\n *\n * Pure function: the input config is not mutated, and each call returns a\n * fresh independent `MountEntry` with no shared object references.\n *\n * Validation is the caller's responsibility — invoke\n * `validateChainNetworks` before normalization in setup paths.\n */\nexport function chainNetworkToMountEntry(cfg: ChainNetworkConfig): MountEntry {\n  return {\n    path: joinURL(CHAIN_DEVICE_PREFIX, cfg.network),\n    provider: \"ocap\",\n    options: { endpoint: cfg.endpoint },\n  };\n}\n"],"mappings":"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"}