@stage-labs/metro 0.1.0-beta.15 → 0.1.0-beta.151

package/runtime/node_modules/@metro-labs/daemon/src/connectors/store.ts

@@ -0,0 +1,299 @@
+import { join } from 'node:path';
+import { syncPluginServers } from './plugin-sync.js';
+import { listRemoteTools, type RemoteTool } from './tools.js';
+import { readJson, writeSecure } from '@metro-labs/core/secure-fs';
+import { errMsg, log } from '@metro-labs/core/log';
+import {
+  connectorUrlText,
+  ConnectorVerifyError,
+  parseConnectorUrl,
+  verifyRemoteMcp,
+  type ConnectorAuth,
+  type OAuthAuth,
+} from './verify.js';
+import { oauthExpired, refreshOAuth } from './oauth.js';
+import { advertisesOAuth } from './oauth-discovery.js';
+import {
+  ConnectorError,
+  connectorAuth,
+  connectorClient,
+  connectorName,
+  readConfig,
+  stamp,
+  type ConnectorConfig,
+} from './config.js';
+import {
+  bearerHeaders,
+  fixedTarget,
+  unrefreshedTarget,
+  type RelayTarget,
+} from './relay-target.js';
+import {
+  connectorFromRow,
+  UNVERIFIED,
+  type Connector,
+  type ConnectorCheck,
+  type ConnectorInput,
+  type DeletedConnector,
+  type PendingConnectorInput,
+} from './model.js';
+import { agentsDir } from '../agents/files.js';
+import { assertLocalOwner, LOCAL_PROJECT_ID } from '../agents/file-admin.js';
+import { newId } from '@metro-labs/core/ids';
+import type { LoadedConnector } from '../stations/materialize.js';
+
+export interface LocalConnectorRow {
+  id: string;
+  name: string;
+  url: string;
+  transport: 'http';
+  config: ConnectorConfig;
+}
+
+const FILE = 'connectors.json';
+const filePath = (dir: string): string => join(dir, FILE);
+
+const isRow = (v: unknown): v is { id: string; name: string; url: string; config?: unknown } =>
+  typeof v === 'object' &&
+  v !== null &&
+  typeof (v as { id?: unknown }).id === 'string' &&
+  typeof (v as { name?: unknown }).name === 'string' &&
+  typeof (v as { url?: unknown }).url === 'string';
+
+const asList = (value: unknown): unknown[] =>
+  Array.isArray(value) ? value.map((item: unknown) => item) : [];
+
+export function readLocalConnectors(dir = agentsDir()): LocalConnectorRow[] {
+  const raw = readJson<{ connectors?: unknown }>(filePath(dir), {}, {
+    warn: 'connectors.json: malformed, ignoring',
+  });
+  return asList(raw.connectors).filter(isRow).map((r) => ({
+    id: r.id,
+    name: r.name,
+    url: r.url,
+    transport: 'http' as const,
+    config: readConfig(r.config),
+  }));
+}
+
+function writeRows(dir: string, rows: LocalConnectorRow[]): void {
+  writeSecure(filePath(dir), `${JSON.stringify({ version: 1, connectors: rows }, null, 2)}\n`);
+  if (dir === agentsDir()) syncPluginServers(rows);
+}
+
+const missing = (): ConnectorError => new ConnectorError('no such connector', 404);
+
+function ownedRows(subject: string, project: string, dir: string): LocalConnectorRow[] {
+  assertLocalOwner(subject, dir);
+  if (project !== LOCAL_PROJECT_ID) throw new ConnectorError('no such project', 404);
+  return readLocalConnectors(dir);
+}
+
+function rowOrThrow(subject: string, id: string, dir: string): LocalConnectorRow {
+  assertLocalOwner(subject, dir);
+  const row = readLocalConnectors(dir).find((r) => r.id === id);
+  if (row === undefined) throw missing();
+  return row;
+}
+
+function replace(dir: string, row: LocalConnectorRow): Connector {
+  writeRows(dir, readLocalConnectors(dir).map((r) => (r.id === row.id ? row : r)));
+  return connectorFromRow(row);
+}
+
+async function oauthCapable(url: URL, auth: ConnectorAuth): Promise<boolean> {
+  if (auth.kind === 'oauth') return true;
+  if (auth.kind === 'header') return false;
+  return advertisesOAuth(url);
+}
+
+export function localImportConnectors(
+  rows: LoadedConnector[],
+  dir = agentsDir(),
+  mode: 'append' | 'overwrite' = 'overwrite',
+): number {
+  const current = readLocalConnectors(dir);
+  const fresh =
+    mode === 'overwrite'
+      ? rows
+      : rows.filter((row) => !current.some((r) => r.id === row.id || r.name === row.name));
+  const imported: LocalConnectorRow[] = fresh.map((row) => ({
+    id: row.id,
+    name: row.name,
+    url: row.url,
+    transport: 'http',
+    config: readConfig(row.config),
+  }));
+  const ids = new Set(imported.map((r) => r.id));
+  const names = new Set(imported.map((r) => r.name));
+  writeRows(dir, [...current.filter((r) => !ids.has(r.id) && !names.has(r.name)), ...imported]);
+  return imported.length;
+}
+
+export async function localListConnectors(
+  subject: string,
+  project: string,
+  dir = agentsDir(),
+): Promise<Connector[]> {
+  return Promise.resolve(ownedRows(subject, project, dir).map(connectorFromRow));
+}
+
+export async function localGetConnector(subject: string, id: string, dir = agentsDir()): Promise<Connector> {
+  return Promise.resolve(connectorFromRow(rowOrThrow(subject, id, dir)));
+}
+
+function assertNameFree(name: string, exceptId: string | null, dir: string): void {
+  if (readLocalConnectors(dir).some((r) => r.id !== exceptId && r.name === name))
+    throw new ConnectorError(`a connector named '${name}' already exists on this daemon`, 409);
+}
+
+function insert(dir: string, name: string, url: URL, config: ConnectorConfig): Connector {
+  assertNameFree(name, null, dir);
+  const row: LocalConnectorRow = { id: newId(), name, url: connectorUrlText(url), transport: 'http', config };
+  writeRows(dir, [...readLocalConnectors(dir), row]);
+  return connectorFromRow(row);
+}
+
+export async function localCreateConnector(
+  subject: string,
+  project: string,
+  input: ConnectorInput,
+  dir = agentsDir(),
+): Promise<Connector> {
+  ownedRows(subject, project, dir);
+  const name = connectorName(input.name);
+  const url = parseConnectorUrl(input.url);
+  const auth = connectorAuth(input.header, input.value);
+  const client = connectorClient(input.clientId, input.clientSecret);
+  const verified = stamp(await verifyRemoteMcp(url, auth));
+  return insert(dir, name, url, {
+    auth,
+    createdAt: new Date().toISOString(),
+    verified,
+    oauth: await oauthCapable(url, auth),
+    client,
+  });
+}
+
+export async function localCreatePendingConnector(
+  subject: string,
+  project: string,
+  input: PendingConnectorInput,
+  dir = agentsDir(),
+): Promise<Connector> {
+  ownedRows(subject, project, dir);
+  const name = connectorName(input.name);
+  const url = parseConnectorUrl(input.url);
+  const client = connectorClient(input.clientId, input.clientSecret);
+  return Promise.resolve(
+    insert(dir, name, url, { auth: { kind: 'none' }, createdAt: new Date().toISOString(), verified: UNVERIFIED, oauth: true, client }),
+  );
+}
+
+export async function localReconnectConnector(
+  subject: string,
+  id: string,
+  auth: OAuthAuth,
+  dir = agentsDir(),
+): Promise<Connector> {
+  const row = rowOrThrow(subject, id, dir);
+  const verified = stamp(await verifyRemoteMcp(parseConnectorUrl(row.url), auth));
+  return replace(dir, { ...row, config: { ...row.config, auth, verified, oauth: true } });
+}
+
+const signedOut = (row: LocalConnectorRow): LocalConnectorRow => ({ ...row, config: { ...row.config, auth: { kind: 'none' }, oauth: true } });
+
+export async function localDisconnectConnector(subject: string, id: string, dir = agentsDir()): Promise<Connector> {
+  const row = rowOrThrow(subject, id, dir);
+  if (row.config.auth.kind !== 'oauth') throw new ConnectorError('that connector is not signed in', 400);
+  return Promise.resolve(replace(dir, signedOut(row)));
+}
+
+export function localMarkSignedOut(id: string, dir = agentsDir()): void {
+  const row = readLocalConnectors(dir).find((r) => r.id === id);
+  if (row?.config.auth.kind !== 'oauth') return;
+  log.info({ id, name: row.name }, 'local relay: the vendor refused the token after a refresh; the connector is signed out');
+  replace(dir, signedOut(row));
+}
+
+async function freshAuth(auth: ConnectorAuth, resource: string): Promise<ConnectorAuth> {
+  if (auth.kind !== 'oauth' || !oauthExpired(auth)) return auth;
+  return refreshOAuth(auth, resource);
+}
+
+export async function localVerifyConnector(subject: string, id: string, dir = agentsDir()): Promise<ConnectorCheck> {
+  const row = rowOrThrow(subject, id, dir);
+  try {
+    const url = parseConnectorUrl(row.url);
+    const auth = await freshAuth(row.config.auth, url.toString());
+    const verified = stamp(await verifyRemoteMcp(url, auth));
+    const oauth = row.config.oauth || (await oauthCapable(url, auth));
+    replace(dir, { ...row, config: { ...row.config, auth, verified, oauth } });
+    return { id: row.id, name: row.name, ok: true, verified };
+  } catch (err) {
+    if (!(err instanceof ConnectorVerifyError)) throw err;
+    return { id: row.id, name: row.name, ok: false, reason: err.message };
+  }
+}
+
+export async function localConnectorTools(subject: string, id: string, dir = agentsDir()): Promise<RemoteTool[]> {
+  const row = rowOrThrow(subject, id, dir);
+  const url = parseConnectorUrl(row.url);
+  const auth = await freshAuth(row.config.auth, url.toString());
+  if (auth !== row.config.auth) replace(dir, { ...row, config: { ...row.config, auth } });
+  return listRemoteTools(url, auth);
+}
+
+export async function localRenameConnector(subject: string, id: string, raw: string, dir = agentsDir()): Promise<Connector> {
+  const name = connectorName(raw);
+  const row = rowOrThrow(subject, id, dir);
+  assertNameFree(name, id, dir);
+  return Promise.resolve(replace(dir, { ...row, name }));
+}
+
+export async function localDeleteConnector(subject: string, id: string, dir = agentsDir()): Promise<DeletedConnector> {
+  const row = rowOrThrow(subject, id, dir);
+  writeRows(dir, readLocalConnectors(dir).filter((r) => r.id !== id));
+  return Promise.resolve({ id: row.id, name: row.name });
+}
+
+const inflight = new Map<string, Promise<OAuthAuth>>();
+
+function refreshOnce(row: LocalConnectorRow, auth: OAuthAuth, dir: string): Promise<OAuthAuth> {
+  const running = inflight.get(row.id);
+  if (running !== undefined) return running;
+  const job = refreshOAuth(auth, parseConnectorUrl(row.url).toString())
+    .then((fresh) => {
+      replace(dir, { ...row, config: { ...row.config, auth: fresh } });
+      return fresh;
+    })
+    .finally(() => {
+      inflight.delete(row.id);
+    });
+  inflight.set(row.id, job);
+  return job;
+}
+
+async function oauthTarget(row: LocalConnectorRow, auth: OAuthAuth, force: boolean, dir: string): Promise<RelayTarget> {
+  if (!force && !oauthExpired(auth)) return { kind: 'ok', url: row.url, headers: bearerHeaders(auth.accessToken) };
+  try {
+    const fresh = await refreshOnce(row, auth, dir);
+    return { kind: 'ok', url: row.url, headers: bearerHeaders(fresh.accessToken) };
+  } catch (err) {
+    log.warn({ id: row.id, err: errMsg(err) }, 'local relay: token refresh failed');
+    return unrefreshedTarget(row.url, auth, force);
+  }
+}
+
+export async function localRelayTarget(
+  connectorId: string,
+  force: boolean,
+  dir = agentsDir(),
+): Promise<RelayTarget> {
+  const row = readLocalConnectors(dir).find((r) => r.id === connectorId);
+  if (row === undefined) return { kind: 'missing' };
+  parseConnectorUrl(row.url);
+  const auth = row.config.auth;
+  if (auth.kind === 'oauth') return oauthTarget(row, auth, force, dir);
+  return fixedTarget(row.url, auth, force);
+}

package/runtime/node_modules/@metro-labs/daemon/src/connectors/tools.ts

@@ -0,0 +1,108 @@
+import { isRecord } from '@metro-labs/core/is-record';
+import { errMsg, log } from '@metro-labs/core/log';
+import { whyUnreachable } from './reach.js';
+import { refused } from './url.js';
+import { authHeaders, type ConnectorAuth } from './verify.js';
+
+export interface RemoteTool {
+  name: string;
+  description: string;
+  readOnly: boolean;
+}
+
+const TIMEOUT_MS = 15_000;
+const MAX_PAGES = 10;
+const ACCEPT = 'application/json, text/event-stream';
+
+function dataOf(text: string, contentType: string): string {
+  if (!contentType.includes('text/event-stream')) return text;
+  for (const line of text.replace(/\r\n/g, '\n').split('\n')) if (line.startsWith('data:')) return line.slice(5).trim();
+  return '';
+}
+
+async function post(url: URL, auth: ConnectorAuth, session: Map<string, string>, body: unknown): Promise<Response> {
+  try {
+    return await fetch(url, {
+      method: 'POST',
+      redirect: 'manual',
+      signal: AbortSignal.timeout(TIMEOUT_MS),
+      headers: { 'content-type': 'application/json', accept: ACCEPT, ...authHeaders(auth), ...Object.fromEntries(session) },
+      body: JSON.stringify(body),
+    });
+  } catch (err) {
+    throw refused(`Metro could not reach ${url.hostname}: ${whyUnreachable(err)}`);
+  }
+}
+
+function resultOf(text: string, contentType: string): Record<string, unknown> | null {
+  let parsed: unknown = null;
+  try {
+    parsed = JSON.parse(dataOf(text, contentType));
+  } catch {
+    return null;
+  }
+  return isRecord(parsed) && isRecord(parsed.result) ? parsed.result : null;
+}
+
+async function rpc(url: URL, auth: ConnectorAuth, session: Map<string, string>, body: unknown): Promise<Record<string, unknown> | null> {
+  const res = await post(url, auth, session, body);
+  const id = res.headers.get('mcp-session-id');
+  if (id !== null && id !== '') session.set('mcp-session-id', id);
+  const text = await res.text().catch(() => '');
+  if (res.status === 401 || res.status === 403) throw refused(`${url.hostname} rejected the credential; connect it again`);
+  if (!res.ok) throw refused(`${url.hostname} answered ${String(res.status)}`);
+  return resultOf(text, res.headers.get('content-type') ?? '');
+}
+
+function toTool(raw: unknown): RemoteTool | null {
+  if (!isRecord(raw) || typeof raw.name !== 'string') return null;
+  const annotations = isRecord(raw.annotations) ? raw.annotations : {};
+  const title = typeof raw.title === 'string' && raw.title !== '' ? raw.title : raw.name;
+  return { name: title, description: typeof raw.description === 'string' ? raw.description : '', readOnly: annotations.readOnlyHint === true };
+}
+
+async function endSession(url: URL, auth: ConnectorAuth, session: Map<string, string>): Promise<void> {
+  if (!session.has('mcp-session-id')) return;
+  try {
+    const res = await fetch(url, { method: 'DELETE', redirect: 'manual', signal: AbortSignal.timeout(TIMEOUT_MS), headers: { ...authHeaders(auth), ...Object.fromEntries(session) } });
+    await res.body?.cancel();
+  } catch (err) {
+    log.debug({ host: url.hostname, err: errMsg(err) }, 'connector-tools: the remote declined to end the session');
+  }
+}
+
+const toolsOf = (result: Record<string, unknown>): RemoteTool[] =>
+  Array.isArray(result.tools) ? result.tools.flatMap((raw: unknown) => toTool(raw) ?? []) : [];
+
+function nextCursor(result: Record<string, unknown>, current: string): string | null {
+  const next = result.nextCursor;
+  return typeof next !== 'string' || next === '' || next === current ? null : next;
+}
+
+async function walkTools(url: URL, auth: ConnectorAuth, session: Map<string, string>): Promise<RemoteTool[]> {
+  const tools: RemoteTool[] = [];
+  let cursor: string | null = '';
+  for (let page = 0; page < MAX_PAGES && cursor !== null; page += 1) {
+    const result = await rpc(url, auth, session, { jsonrpc: '2.0', id: 2 + page, method: 'tools/list', params: cursor === '' ? {} : { cursor } });
+    if (result === null) break;
+    tools.push(...toolsOf(result));
+    cursor = nextCursor(result, cursor);
+  }
+  return tools;
+}
+
+export async function listRemoteTools(url: URL, auth: ConnectorAuth): Promise<RemoteTool[]> {
+  const session = new Map<string, string>();
+  const init = await rpc(url, auth, session, {
+    jsonrpc: '2.0',
+    id: 1,
+    method: 'initialize',
+    params: { protocolVersion: '2025-11-25', capabilities: {}, clientInfo: { name: 'metro', version: '0.1.0' } },
+  });
+  if (init === null || typeof init.protocolVersion !== 'string') throw refused(`${url.hostname} answered, but it does not speak MCP.`);
+  session.set('mcp-protocol-version', init.protocolVersion);
+  await rpc(url, auth, session, { jsonrpc: '2.0', method: 'notifications/initialized' });
+  const tools = await walkTools(url, auth, session);
+  await endSession(url, auth, session);
+  return tools;
+}

package/runtime/node_modules/@metro-labs/daemon/src/connectors/url.ts

@@ -0,0 +1,59 @@
+import { ApiError } from '@metro-labs/http/api-error';
+
+export class ConnectorVerifyError extends ApiError {}
+
+export class ConnectorUnauthorized extends ConnectorVerifyError {}
+
+export const POLICY_MESSAGE =
+  'Metro connects from its own server, so it cannot reach a URL on your machine. localhost and private addresses are not usable as connectors.';
+
+let localAllowed = false;
+
+export function allowLocalConnectors(on: boolean): void {
+  localAllowed = on;
+}
+
+const IPV4 = /^\d{1,3}(?:\.\d{1,3}){3}$/;
+const PRIVATE_SUFFIX = /(?:^|\.)(?:localhost|local|internal|flycast)$/;
+
+export function refused(message: string): ConnectorVerifyError {
+  return new ConnectorVerifyError(message, 400);
+}
+
+function hostAllowed(host: string): boolean {
+  if (host === '' || host.startsWith('[')) return false;
+  if (IPV4.test(host) || !host.includes('.')) return false;
+  return !PRIVATE_SUFFIX.test(host);
+}
+
+function schemeAllowed(url: URL): boolean {
+  return url.protocol === 'https:' || (localAllowed && url.protocol === 'http:');
+}
+
+function refuseShape(url: URL): void {
+  if (!schemeAllowed(url)) throw refused('a connector url must start with https://');
+  if (url.username !== '' || url.password !== '')
+    throw refused('a connector url must not carry a user:password');
+  if (url.hash !== '')
+    throw refused('a connector url must not carry a #fragment');
+  if (!localAllowed && !hostAllowed(url.hostname.toLowerCase())) throw refused(POLICY_MESSAGE);
+}
+
+export function parseConnectorUrl(raw: unknown): URL {
+  const text = typeof raw === 'string' ? raw.trim() : '';
+  if (text === '') throw refused('a connector url is required');
+  let url: URL;
+  try {
+    url = new URL(text);
+  } catch {
+    throw refused('that is not a valid url');
+  }
+  refuseShape(url);
+  return url;
+}
+
+export function connectorUrlText(url: URL): string {
+  const text = url.toString();
+  if (url.pathname !== '/' || url.search !== '') return text;
+  return text.endsWith('/') ? text.slice(0, -1) : text;
+}

package/runtime/node_modules/@metro-labs/daemon/src/connectors/verify.ts

@@ -0,0 +1,101 @@
+import { isRecord } from '@metro-labs/core/is-record';
+import { whyUnreachable } from './reach.js';
+import { ConnectorUnauthorized, refused } from './url.js';
+
+export {
+  ConnectorUnauthorized,
+  ConnectorVerifyError,
+  connectorUrlText,
+  parseConnectorUrl,
+} from './url.js';
+
+export interface OAuthTokens {
+  accessToken: string;
+  refreshToken?: string;
+  expiresAt?: number;
+}
+
+export interface OAuthAuth extends OAuthTokens {
+  kind: 'oauth';
+  issuer: string;
+  tokenEndpoint: string;
+  clientId: string;
+  clientSecret?: string;
+  scope?: string;
+}
+
+export type ConnectorAuth =
+  | { kind: 'none' }
+  | { kind: 'header'; name: string; value: string }
+  | OAuthAuth;
+
+export interface VerifiedServer {
+  server: string;
+}
+
+export interface VerifiedRecord extends VerifiedServer {
+  at: string;
+}
+
+const PROTOCOL_VERSION = '2025-11-25';
+const PROBE_TIMEOUT_MS = 10_000;
+
+const INITIALIZE = {
+  jsonrpc: '2.0',
+  id: 1,
+  method: 'initialize',
+  params: { protocolVersion: PROTOCOL_VERSION, capabilities: {}, clientInfo: { name: 'metro', version: '0.1.0' } },
+};
+
+export function authHeaders(auth: ConnectorAuth): Record<string, string> {
+  if (auth.kind === 'header') return { [auth.name]: auth.value };
+  if (auth.kind === 'oauth') return { authorization: `Bearer ${auth.accessToken}` };
+  return {};
+}
+
+function payloadOf(text: string, contentType: string): string {
+  if (!contentType.includes('text/event-stream')) return text;
+  for (const line of text.replace(/\r\n/g, '\n').split('\n')) if (line.startsWith('data:')) return line.slice(5).trim();
+  return '';
+}
+
+function serverNameOf(url: URL, text: string, contentType: string): string {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(payloadOf(text, contentType));
+  } catch {
+    throw refused(`${url.hostname} answered, but it does not speak MCP.`);
+  }
+  const result = isRecord(parsed) && isRecord(parsed.result) ? parsed.result : null;
+  if (result === null || typeof result.protocolVersion !== 'string') throw refused(`${url.hostname} answered, but it does not speak MCP.`);
+  const info = isRecord(result.serverInfo) ? result.serverInfo : {};
+  const title = typeof info.title === 'string' ? info.title : '';
+  if (title !== '') return title;
+  return typeof info.name === 'string' ? info.name : url.hostname;
+}
+
+async function post(url: URL, auth: ConnectorAuth): Promise<Response> {
+  try {
+    return await fetch(url, {
+      method: 'POST',
+      redirect: 'manual',
+      signal: AbortSignal.timeout(PROBE_TIMEOUT_MS),
+      headers: { 'content-type': 'application/json', accept: 'application/json, text/event-stream', ...authHeaders(auth) },
+      body: JSON.stringify(INITIALIZE),
+    });
+  } catch (err) {
+    throw refused(`Metro could not reach ${url.hostname}: ${whyUnreachable(err)}`);
+  }
+}
+
+export async function verifyRemoteMcp(url: URL, auth: ConnectorAuth): Promise<VerifiedServer> {
+  const res = await post(url, auth);
+  const text = await res.text().catch(() => '');
+  if (res.status >= 300 && res.status < 400) throw refused('that url redirects — use the url it redirects to');
+  if (res.status === 401 || res.status === 403)
+    throw new ConnectorUnauthorized(auth.kind === 'none' ? `${url.hostname} requires authorization.` : `${url.hostname} rejected that credential.`, 400);
+  if (res.status === 404 || res.status === 405)
+    throw refused(`${url.hostname} did not accept an MCP initialize over HTTP POST. If it is a legacy SSE server, Metro cannot verify it yet.`);
+  if (!res.ok) throw refused(`${url.hostname} answered ${String(res.status)} instead of an MCP initialize.`);
+  return { server: serverNameOf(url, text, res.headers.get('content-type') ?? '') };
+}

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

@@ -0,0 +1,99 @@
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+import { ID_RE } from '@metro-labs/core/ids';
+import { readFileSync } from 'node:fs';
+import { resolveCachedAttachment } from '@metro-labs/core/stations/attachments';
+import { writeSecure } from '@metro-labs/core/secure-fs';
+
+const GRANT_SUFFIX = '.grant';
+
+export interface AttachmentGrant {
+  token: string;
+  agentId: string;
+  mintedAt: number;
+}
+
+function newAttachmentToken(prefix = 'at'): string {
+  return `${prefix}_${randomBytes(32).toString('base64url')}`;
+}
+
+function parseGrant(raw: string): AttachmentGrant | undefined {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return undefined;
+  }
+  if (typeof parsed !== 'object' || parsed === null) return undefined;
+  const { token, agentId, mintedAt } = parsed as Record<string, unknown>;
+  if (typeof token !== 'string' || token === '') return undefined;
+  if (typeof agentId !== 'string' || !ID_RE.test(agentId)) return undefined;
+  return {
+    token,
+    agentId,
+    mintedAt: typeof mintedAt === 'number' ? mintedAt : 0,
+  };
+}
+
+function readGrant(path: string): AttachmentGrant | undefined {
+  try {
+    return parseGrant(readFileSync(`${path}${GRANT_SUFFIX}`, 'utf8'));
+  } catch {
+    return undefined;
+  }
+}
+
+export function issueGrant(
+  path: string,
+  agentId: string,
+  prefix?: string,
+): string {
+  const existing = readGrant(path);
+  if (existing?.agentId === agentId) return existing.token;
+  const grant: AttachmentGrant = {
+    token: newAttachmentToken(prefix),
+    agentId,
+    mintedAt: Date.now(),
+  };
+  writeSecure(`${path}${GRANT_SUFFIX}`, `${JSON.stringify(grant)}\n`);
+  return grant.token;
+}
+
+function sameToken(presented: string, stored: string): boolean {
+  const a = Buffer.from(presented, 'utf8');
+  const b = Buffer.from(stored, 'utf8');
+  return a.length === b.length && timingSafeEqual(a, b);
+}
+
+export function grantAllowsPath(
+  path: string,
+  owner: string,
+  presented: string,
+): boolean {
+  if (presented === '') return false;
+  const grant = readGrant(path);
+  if (grant === undefined) return false;
+  if (grant.agentId !== owner) return false;
+  return sameToken(presented, grant.token);
+}
+
+export function readAttachmentGrant(name: string): AttachmentGrant | undefined {
+  const path = resolveCachedAttachment(name);
+  return path === null ? undefined : readGrant(path);
+}
+
+export function issueAttachmentGrant(
+  name: string,
+  agentId: string,
+): string | undefined {
+  const path = resolveCachedAttachment(name);
+  return path === null ? undefined : issueGrant(path, agentId);
+}
+
+export function grantAllows(
+  name: string,
+  owner: string,
+  presented: string,
+): boolean {
+  const path = resolveCachedAttachment(name);
+  return path === null ? false : grantAllowsPath(path, owner, presented);
+}