@stage-labs/metro 0.1.0-beta.13 → 0.1.0-beta.130

package/runtime/node_modules/@metro-labs/daemon/src/agents/file-admin.ts

@@ -0,0 +1,371 @@
+import { existsSync, readFileSync, rmdirSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { ApiError } from '@metro-labs/http/api-error';
+import { ensureSecureDir, writeSecure } from '@metro-labs/core/secure-fs';
+import {
+  AgentAdminError,
+  newApiKey,
+  normalizeAgentName,
+  type AgentSummary,
+  type CreatedAgent,
+  type DeletedAgent,
+  type OwnedAgent,
+  type ResetAgentKey,
+} from './admin.js';
+import type { AccountRef } from './account-attach.js';
+import {
+  AGENT_FILE,
+  AgentFileError,
+  agentsDir,
+  listAgentFiles,
+  parseAgentFile,
+  readAgentFile,
+  type AgentFile,
+} from './files.js';
+import { newId } from '@metro-labs/core/ids';
+import { registerKey, rotateAgentKey, unregisterAgentKey } from './keys.js';
+import { MOVABLE_STATIONS, type LoadedAgent } from '../stations/materialize.js';
+import type { StationName } from '@metro-labs/core/station-names';
+import { normalizeAddress } from '@metro-labs/core/address';
+
+export const LOCAL_PROJECT_ID = 'localdaemon';
+const OWNER_FILE = '.owner';
+
+interface Stored {
+  path: string;
+  file: AgentFile;
+}
+
+const missing = (): AgentAdminError => new AgentAdminError('no such agent', 404);
+
+export function localOwner(dir = agentsDir()): string | null {
+  try {
+    return normalizeAddress(readFileSync(join(dir, OWNER_FILE), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+export function setLocalOwner(raw: string, dir = agentsDir()): string {
+  const address = normalizeAddress(raw);
+  if (address === null) throw new ApiError(`'${raw}' is not an Ethereum address`, 400);
+  ensureSecureDir(dir);
+  writeSecure(join(dir, OWNER_FILE), `${address}\n`);
+  return address;
+}
+
+
+function isOwner(subject: string, dir: string): boolean {
+  const owner = localOwner(dir);
+  return owner !== null && owner === normalizeAddress(subject);
+}
+
+function storedAgents(dir: string): Stored[] {
+  return listAgentFiles(dir).map((path) => ({ path, file: readAgentFile(path) }));
+}
+
+function save(stored: Stored): void {
+  writeSecure(stored.path, `${JSON.stringify(stored.file, null, 2)}\n`);
+}
+
+function ownedOrThrow(subject: string, id: string, dir: string): Stored {
+  if (!isOwner(subject, dir)) throw missing();
+  const found = storedAgents(dir).find((s) => s.file.id === id);
+  if (found === undefined) throw missing();
+  return found;
+}
+
+export async function localOwnedAgentOrThrow(
+  subject: string,
+  id: string,
+  dir = agentsDir(),
+): Promise<{ agent: OwnedAgent }> {
+  const { file } = ownedOrThrow(subject, id, dir);
+  return Promise.resolve({ agent: { id: file.id, name: file.name } });
+}
+
+export async function localListAgents(
+  subject: string,
+  project: string,
+  dir = agentsDir(),
+): Promise<AgentSummary[]> {
+  if (project !== LOCAL_PROJECT_ID || !isOwner(subject, dir))
+    throw new AgentAdminError('no such project', 404);
+  return Promise.resolve(
+    storedAgents(dir)
+      .map(({ file }) => ({ id: file.id, name: file.name, owned: true, key: file.key }))
+      .sort((a, b) => a.name.localeCompare(b.name) || a.id.localeCompare(b.id)),
+  );
+}
+
+function freshId(taken: Set<string>): string {
+  for (let attempt = 0; attempt < 5; attempt += 1) {
+    const id = newId();
+    if (!taken.has(id)) return id;
+  }
+  throw new AgentAdminError('could not allocate a free id', 500);
+}
+
+export async function localCreateAgent(
+  subject: string,
+  project: string,
+  rawName: string,
+  dir = agentsDir(),
+): Promise<CreatedAgent> {
+  if (project !== LOCAL_PROJECT_ID || !isOwner(subject, dir))
+    throw new AgentAdminError('no such project', 404);
+  const name = normalizeAgentName(rawName);
+  const folder = join(dir, name);
+  if (existsSync(join(folder, AGENT_FILE)))
+    throw new AgentAdminError(
+      `an agent named '${name}' already exists on this machine`,
+      409,
+    );
+  const existing = storedAgents(dir);
+  const id = freshId(new Set(existing.map((s) => s.file.id)));
+  const key = newApiKey();
+  ensureSecureDir(folder);
+  save({
+    path: join(folder, AGENT_FILE),
+    file: { version: 1, id, name, key, owner: localOwner(dir), stations: [], connectors: [] },
+  });
+  registerKey(key, id);
+  return Promise.resolve({ id, name, key });
+}
+
+export async function localResetAgentKey(
+  subject: string,
+  id: string,
+  dir = agentsDir(),
+): Promise<ResetAgentKey> {
+  const stored = ownedOrThrow(subject, id, dir);
+  const key = newApiKey();
+  stored.file.key = key;
+  save(stored);
+  rotateAgentKey(id, key);
+  return Promise.resolve({ id, name: stored.file.name, key });
+}
+
+export async function localDeleteAgent(
+  subject: string,
+  id: string,
+  dir = agentsDir(),
+): Promise<DeletedAgent> {
+  const stored = ownedOrThrow(subject, id, dir);
+  const attached = stored.file.stations.length;
+  if (attached > 0)
+    throw new AgentAdminError(
+      `agent '${stored.file.name}' still has ${String(attached)} station account(s) attached — detach them first`,
+      409,
+    );
+  rmSync(stored.path);
+  removeIfEmpty(join(stored.path, '..'));
+  unregisterAgentKey(id);
+  return Promise.resolve({ id, name: stored.file.name });
+}
+
+function assertUnclaimed(existing: Stored[], agent: LoadedAgent): void {
+  for (const { file } of existing) {
+    if (file.id === agent.id)
+      throw new AgentAdminError(`agent ${agent.id} is already on this machine`, 409);
+    if (agent.key !== null && file.key === agent.key)
+      throw new AgentAdminError('that agent key is already on this machine', 409);
+  }
+}
+
+export function assertLocalOwner(subject: string, dir = agentsDir()): void {
+  if (!isOwner(subject, dir)) throw new AgentAdminError('no such project', 404);
+}
+
+function assertImportable(agent: LoadedAgent): asserts agent is LoadedAgent & { key: string } {
+  const immovable = agent.accounts.find((a) => !MOVABLE_STATIONS.has(a.station));
+  if (immovable !== undefined)
+    throw new AgentAdminError(
+      `a ${immovable.station} endpoint needs a public url and cannot live on a local daemon`,
+      400,
+    );
+  if (agent.key === null)
+    throw new AgentAdminError('that agent has no key; reset it on metro.box first', 400);
+}
+
+interface ImportTarget {
+  path: string;
+  previous: AgentFile | undefined;
+}
+
+function importTarget(dir: string, agent: LoadedAgent & { key: string }): ImportTarget {
+  const existing = storedAgents(dir);
+  const same = existing.find((s) => s.file.id === agent.id);
+  const fresh = join(dir, agent.name, AGENT_FILE);
+  if (same === undefined && existsSync(fresh))
+    throw new AgentAdminError(
+      `an agent named '${agent.name}' already exists on this machine`,
+      409,
+    );
+  assertUnclaimed(existing.filter((s) => s !== same), agent);
+  return { path: same?.path ?? fresh, previous: same?.file };
+}
+
+export type ImportMode = 'append' | 'overwrite';
+
+export async function localImportAgent(
+  subject: string,
+  agent: LoadedAgent,
+  dir = agentsDir(),
+  mode: ImportMode = 'overwrite',
+): Promise<{ id: string; name: string; key: string; stations: number }> {
+  assertLocalOwner(subject, dir);
+  assertImportable(agent);
+  const { path, previous } = importTarget(dir, agent);
+  const file = fileFor(agent, localOwner(dir), path, previous, mode);
+  ensureSecureDir(join(path, '..'));
+  save({ path, file });
+  if (previous !== undefined && previous.key !== agent.key) unregisterAgentKey(agent.id);
+  registerKey(agent.key, agent.id);
+  return Promise.resolve({
+    id: agent.id,
+    name: agent.name,
+    key: agent.key,
+    stations: file.stations.length,
+  });
+}
+
+function mergedStations(
+  agent: LoadedAgent,
+  previous: AgentFile | undefined,
+  mode: ImportMode,
+): AgentFile['stations'] {
+  const before = previous?.stations ?? [];
+  const here = (station: string, id: string): boolean => before.some((s) => s.station === station && s.id === id);
+  const fromMetro = agent.accounts
+    .map((a) => ({ ...a, allowlist: a.allowlist ?? ['*'] }))
+    .filter((m) => mode === 'overwrite' || !here(m.station, m.id));
+  const kept = before.filter((s) => !fromMetro.some((m) => m.station === s.station && m.id === s.id));
+  return [...fromMetro, ...kept];
+}
+
+function fileFor(
+  agent: LoadedAgent,
+  owner: string | null,
+  path: string,
+  previous: AgentFile | undefined,
+  mode: ImportMode,
+): AgentFile {
+  try {
+    return parseAgentFile(
+      JSON.stringify({
+        version: 1,
+        id: agent.id,
+        name: previous?.name ?? agent.name,
+        key: agent.key,
+        owner,
+        stations: mergedStations(agent, previous, mode),
+        connectors: previous?.connectors ?? [],
+      }),
+      path,
+    );
+  } catch (err) {
+    if (err instanceof AgentFileError)
+      throw new AgentAdminError(`metro's copy of this agent cannot be written here: ${err.message}`, 400);
+    throw err;
+  }
+}
+
+export function readLocalAgentFile(agentId: string, dir = agentsDir()): AgentFile {
+  const found = storedAgents(dir).find((s) => s.file.id === agentId);
+  if (found === undefined) throw missing();
+  return found.file;
+}
+
+function removeIfEmpty(folder: string): void {
+  try {
+    rmdirSync(folder);
+  } catch {
+    return;
+  }
+}
+
+function assertTokenFree(all: Stored[], station: StationName, token: string): void {
+  const taken = all.some((s) =>
+    s.file.stations.some(
+      (a) => a.station === station && a.config.token === token,
+    ),
+  );
+  if (taken)
+    throw new AgentAdminError(
+      'that bot token is already attached to an agent on this machine',
+      409,
+    );
+}
+
+export async function localAttachAccount(
+  subject: string,
+  agentId: string,
+  station: StationName,
+  config: Record<string, unknown>,
+  dir = agentsDir(),
+): Promise<AccountRef> {
+  const stored = ownedOrThrow(subject, agentId, dir);
+  if (!MOVABLE_STATIONS.has(station))
+    throw new AgentAdminError(
+      `a ${station} endpoint needs a public url and cannot live on a local daemon`,
+      400,
+    );
+  const token = config.token;
+  if (typeof token === 'string') assertTokenFree(storedAgents(dir), station, token);
+  const taken = new Set(stored.file.stations.map((a) => a.id));
+  const accountId = freshId(taken);
+  stored.file.stations.push({ station, id: accountId, allowlist: ['*'], enabled: true, config });
+  save(stored);
+  return Promise.resolve({ agentId, station, accountId });
+}
+
+export async function localSetAllowlist(
+  subject: string,
+  agentId: string,
+  station: StationName,
+  accountId: string,
+  allowlist: string[],
+  dir = agentsDir(),
+): Promise<string[]> {
+  const stored = ownedOrThrow(subject, agentId, dir);
+  const account = stored.file.stations.find((a) => a.station === station && a.id === accountId);
+  if (account === undefined) throw new AgentAdminError('no such account on this agent', 404);
+  account.allowlist = allowlist;
+  save(stored);
+  return Promise.resolve(allowlist);
+}
+
+export async function localSetAccountEnabled(
+  subject: string,
+  agentId: string,
+  station: StationName,
+  accountId: string,
+  enabled: boolean,
+  dir = agentsDir(),
+): Promise<boolean> {
+  const stored = ownedOrThrow(subject, agentId, dir);
+  const account = stored.file.stations.find((a) => a.station === station && a.id === accountId);
+  if (account === undefined) throw new AgentAdminError('no such account on this agent', 404);
+  account.enabled = enabled;
+  save(stored);
+  return Promise.resolve(enabled);
+}
+
+export async function localDetachAccount(
+  subject: string,
+  agentId: string,
+  station: StationName,
+  accountId: string,
+  dir = agentsDir(),
+): Promise<AccountRef> {
+  const stored = ownedOrThrow(subject, agentId, dir);
+  const before = stored.file.stations.length;
+  stored.file.stations = stored.file.stations.filter(
+    (a) => !(a.station === station && a.id === accountId),
+  );
+  if (stored.file.stations.length === before)
+    throw new AgentAdminError('no such account on this agent', 404);
+  save(stored);
+  return Promise.resolve({ agentId, station, accountId });
+}

package/runtime/node_modules/@metro-labs/daemon/src/agents/files.ts

@@ -0,0 +1,155 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { AGENT_NAME_RE, ID_RE } from '@metro-labs/core/ids';
+import { STATIONS, type StationName } from '@metro-labs/core/station-names';
+import type { LoadedAccount, LoadedAgent, StationSource } from '../stations/materialize.js';
+import { isRecord } from '@metro-labs/core/is-record';
+
+export const AGENT_FILE = 'agent.json';
+
+const KEY_RE = /^[A-Za-z0-9_-]{16,128}$/;
+const ADDRESS_RE = /^0x[0-9a-f]{40}$/;
+const STATION_NAMES = new Set<string>(STATIONS);
+
+export class AgentFileError extends Error {}
+
+export interface AgentFile {
+  version: 1;
+  id: string;
+  name: string;
+  key: string | null;
+  owner: string | null;
+  stations: LoadedAccount[];
+  connectors: string[];
+}
+
+export function agentsDir(): string {
+  const explicit = process.env.METRO_AGENTS_DIR?.trim();
+  return explicit !== undefined && explicit !== ''
+    ? explicit
+    : join(homedir(), '.metro', 'agents');
+}
+
+function fail(path: string, reason: string): never {
+  throw new AgentFileError(`${path}: ${reason}`);
+}
+
+function isStationName(value: unknown): value is StationName {
+  return typeof value === 'string' && STATION_NAMES.has(value);
+}
+
+function allowlistOf(raw: unknown, path: string, where: string): string[] | null {
+  if (raw === null || raw === undefined) return null;
+  if (!Array.isArray(raw)) fail(path, `${where}.allowlist is not a list of strings`);
+  const list = raw.filter((entry): entry is string => typeof entry === 'string');
+  if (list.length !== raw.length)
+    fail(path, `${where}.allowlist is not a list of strings`);
+  return list;
+}
+
+function stationOf(raw: unknown, path: string, index: number): LoadedAccount {
+  const where = `stations[${String(index)}]`;
+  if (!isRecord(raw)) fail(path, `${where} is not an object`);
+  const { station, id, config } = raw;
+  if (!isStationName(station)) fail(path, `${where}.station is not a known station`);
+  if (typeof id !== 'string' || !ID_RE.test(id))
+    fail(path, `${where}.id is not an 11-character id`);
+  if (!isRecord(config)) fail(path, `${where}.config is not an object`);
+  return { station, id, allowlist: allowlistOf(raw.allowlist, path, where), enabled: raw.enabled !== false, config };
+}
+
+function optionalMatch(
+  value: unknown,
+  re: RegExp,
+  path: string,
+  what: string,
+): string | null {
+  if (value === null || value === undefined) return null;
+  if (typeof value !== 'string' || !re.test(value)) fail(path, what);
+  return value;
+}
+
+const connectorsOf = (raw: unknown): string[] =>
+  Array.isArray(raw) ? raw.filter((id): id is string => typeof id === 'string' && ID_RE.test(id)) : [];
+
+export function parseAgentFile(raw: string, path: string): AgentFile {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    fail(path, 'is not valid JSON');
+  }
+  if (!isRecord(parsed)) fail(path, 'is not a JSON object');
+  if (parsed.version !== 1) fail(path, 'version must be 1');
+  const { id, name, stations } = parsed;
+  if (typeof id !== 'string' || !ID_RE.test(id))
+    fail(path, 'id is not an 11-character id');
+  if (typeof name !== 'string' || !AGENT_NAME_RE.test(name))
+    fail(path, 'name is not a valid agent name');
+  const key = optionalMatch(parsed.key, KEY_RE, path, 'key is not an agent key');
+  const owner = optionalMatch(
+    parsed.owner,
+    ADDRESS_RE,
+    path,
+    'owner is not a lowercase Ethereum address',
+  );
+  if (!Array.isArray(stations)) fail(path, 'stations is not a list');
+  return {
+    version: 1,
+    id,
+    name,
+    key,
+    owner,
+    stations: stations.map((s, i) => stationOf(s, path, i)),
+    connectors: connectorsOf(parsed.connectors),
+  };
+}
+
+export function readAgentFile(path: string): AgentFile {
+  let raw: string;
+  try {
+    raw = readFileSync(path, 'utf8');
+  } catch {
+    fail(path, 'cannot be read');
+  }
+  return parseAgentFile(raw, path);
+}
+
+export function listAgentFiles(dir = agentsDir()): string[] {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => join(dir, entry.name, AGENT_FILE))
+    .filter((path) => existsSync(path))
+    .sort();
+}
+
+function assertUnique(agents: AgentFile[], paths: string[]): void {
+  const ids = new Map<string, string>();
+  const keys = new Map<string, string>();
+  agents.forEach((agent, i) => {
+    const path = paths[i] ?? '';
+    const sameId = ids.get(agent.id);
+    if (sameId !== undefined) fail(path, `id ${agent.id} is already used by ${sameId}`);
+    ids.set(agent.id, path);
+    if (agent.key === null) return;
+    const sameKey = keys.get(agent.key);
+    if (sameKey !== undefined) fail(path, `its key is already used by ${sameKey}`);
+    keys.set(agent.key, path);
+  });
+}
+
+export function loadFileAgents(dir = agentsDir()): LoadedAgent[] {
+  const paths = listAgentFiles(dir);
+  const agents = paths.map(readAgentFile);
+  assertUnique(agents, paths);
+  return agents.map((agent) => ({
+    id: agent.id,
+    name: agent.name,
+    key: agent.key,
+    accounts: agent.stations,
+  }));
+}
+
+export const fileSource: StationSource = () => Promise.resolve(loadFileAgents());

package/runtime/node_modules/@metro-labs/daemon/src/agents/keys.ts

@@ -0,0 +1,45 @@
+import { createHash } from 'node:crypto';
+import { ID_RE } from '@metro-labs/core/ids';
+
+const digest = (token: string): string =>
+  createHash('sha256').update(token).digest('hex');
+
+let agentIdByKeyHash = new Map<string, string>();
+
+export interface KeyOwner {
+  key: string;
+  agentId: string;
+}
+
+const usable = (e: KeyOwner): boolean =>
+  e.key !== '' && ID_RE.test(e.agentId);
+
+export function setKeyMap(entries: KeyOwner[]): void {
+  agentIdByKeyHash = new Map(
+    entries.filter(usable).map((e) => [digest(e.key), e.agentId]),
+  );
+}
+
+export function registerKey(key: string, agentId: string): void {
+  if (!usable({ key, agentId })) return;
+  agentIdByKeyHash.set(digest(key), agentId);
+}
+
+export function unregisterAgentKey(agentId: string): void {
+  for (const [hash, id] of agentIdByKeyHash)
+    if (id === agentId) agentIdByKeyHash.delete(hash);
+}
+
+export function rotateAgentKey(agentId: string, key: string | null): void {
+  unregisterAgentKey(agentId);
+  if (key !== null) registerKey(key, agentId);
+}
+
+export function agentIdForKey(token: string): string | undefined {
+  if (token === '') return undefined;
+  return agentIdByKeyHash.get(digest(token));
+}
+
+export function hasAnyKey(): boolean {
+  return agentIdByKeyHash.size > 0;
+}

package/runtime/node_modules/@metro-labs/daemon/src/agents/map.ts

@@ -0,0 +1,95 @@
+export type AgentMap = Record<string, string>;
+export type AgentNameMap = Record<string, string>;
+export type AllowlistMap = Record<string, string[]>;
+
+const mapKey = (station: string, accountId: string): string =>
+  `${station}/${accountId}`;
+
+let agentMap: AgentMap = {};
+let agentNames: AgentNameMap = {};
+let allowlistMap: AllowlistMap = {};
+let disabledAccounts = new Set<string>();
+
+export function setAgentMap(map: AgentMap, names: AgentNameMap): void {
+  agentMap = map;
+  agentNames = names;
+}
+
+export function setAllowlistMap(map: AllowlistMap): void {
+  allowlistMap = map;
+}
+
+export function setDisabledAccounts(ids: Set<string>): void {
+  disabledAccounts = ids;
+}
+
+export const accountEnabled = (station: string, accountId: string): boolean => !disabledAccounts.has(mapKey(station, accountId));
+
+export function accountFromLine(
+  line: string,
+): { station: string; accountId: string } | undefined {
+  const parts = line.split('/');
+  const station = parts[2];
+  const accountId = parts[3];
+  if (!station || !accountId) return undefined;
+  return { station, accountId };
+}
+
+export function agentIdForAccount(
+  station: string,
+  accountId: string,
+): string | undefined {
+  return agentMap[mapKey(station, accountId)];
+}
+
+export function agentIdForLine(line: string): string | undefined {
+  const a = accountFromLine(line);
+  return a ? agentIdForAccount(a.station, a.accountId) : undefined;
+}
+
+export function agentForLine(line: string): string | undefined {
+  const id = agentIdForLine(line);
+  return id === undefined ? undefined : agentNames[id];
+}
+
+export interface KnownAccount {
+  station: string;
+  id: string;
+  agentId: string;
+}
+
+export function knownAccounts(): KnownAccount[] {
+  return Object.entries(agentMap).flatMap(([key, agentId]) => {
+    const cut = key.indexOf('/');
+    return cut === -1 ? [] : [{ station: key.slice(0, cut), id: key.slice(cut + 1), agentId }];
+  });
+}
+
+export function stationAgentIds(station: string): string[] {
+  const prefix = `${station}/`;
+  return Object.entries(agentMap)
+    .filter(([key]) => key.startsWith(prefix))
+    .map(([, id]) => id);
+}
+
+export function allowlistForAccount(station: string, accountId: string): string[] | undefined {
+  return allowlistMap[mapKey(station, accountId)];
+}
+
+export function allowlistForLine(line: string): string[] | undefined {
+  const a = accountFromLine(line);
+  return a ? allowlistMap[mapKey(a.station, a.accountId)] : undefined;
+}
+
+export function senderMatchesAllowlist(
+  allowlist: string[],
+  from: string,
+): boolean {
+  if (allowlist.length === 0 || allowlist.includes('*')) return true;
+  const f = (from ?? '').toLowerCase();
+  const id = f.split('/').pop() ?? f;
+  return allowlist.some((a) => {
+    const v = a.toLowerCase();
+    return v === f || v === id;
+  });
+}