@tokensmind/agent-network 0.1.0

package/src/runtime/connector.js

@@ -0,0 +1,204 @@
+import { randomUUID } from 'node:crypto';
+import { AgentNetworkHttpError } from './httpClient.js';
+import {
+  createPendingAuthorization,
+  createRemoteAuthorization,
+  exchangeAuthorization,
+  waitForApproval,
+} from './deviceAuthorization.js';
+import {
+  buildBusinessUrl,
+  isPublicDiscoveryRequest,
+  validateBusinessRequest,
+} from './requestPolicy.js';
+
+function requestHeaders({ token, idempotencyKey }) {
+  return {
+    'Content-Type': 'application/json',
+    ...(token ? { Authorization: `Bearer ${token}` } : {}),
+    ...(idempotencyKey ? { 'Idempotency-Key': idempotencyKey } : {}),
+  };
+}
+
+function canonicalize(value) {
+  if (Array.isArray(value)) return value.map(canonicalize);
+  if (!value || typeof value !== 'object') return value;
+  return Object.fromEntries(
+    Object.keys(value).sort().map((key) => [key, canonicalize(value[key])]),
+  );
+}
+
+function operationsMatch(left, right) {
+  return JSON.stringify(canonicalize(left)) === JSON.stringify(canonicalize(right));
+}
+
+function assertPendingMatches(pending, operation) {
+  if (!operationsMatch(pending.operation, operation)) {
+    throw new Error(
+      'A different Agent Network operation is pending; retry the original operation first',
+    );
+  }
+}
+
+function assertActiveCredential(active) {
+  if (!active?.token) {
+    throw new Error('Authorized Agent Network operation has no active stored credential');
+  }
+  return active;
+}
+
+function authorizationPending(verificationUrl) {
+  const error = new Error(
+    'Complete Agent Network authorization in the browser, then retry the action.',
+  );
+  error.status = 'authorization_required';
+  error.verificationUrl = verificationUrl;
+  return error;
+}
+
+async function executeBusinessRequest({ operation, token, baseUrl, http, signal }) {
+  return http.request({
+    url: buildBusinessUrl(baseUrl, operation.path),
+    method: operation.method,
+    headers: requestHeaders({ token, idempotencyKey: operation.idempotencyKey }),
+    body: operation.body,
+    signal,
+  });
+}
+
+async function loadInstanceId(store) {
+  const existing = await store.read('instance');
+  if (existing?.id) return existing.id;
+  const id = randomUUID();
+  await store.write('instance', { id });
+  return id;
+}
+
+async function preparePending({ operation, store }) {
+  const existing = await store.read('pending');
+  if (existing) return existing;
+  const instanceId = await loadInstanceId(store);
+  const pending = createPendingAuthorization({ operation, instanceId });
+  await store.write('pending', pending);
+  return pending;
+}
+
+async function authorize({ operation, store, browser, baseUrl, http, client, signal }) {
+  try {
+    let pending = await preparePending({ operation, store });
+    if (pending.phase === 'prepared') {
+      pending = await createRemoteAuthorization({ pending, baseUrl, http, client, signal });
+      await store.write('pending', pending);
+      await browser.open(pending.authorization.verificationUrl);
+      throw authorizationPending(pending.authorization.verificationUrl);
+    }
+    if (pending.phase === 'authorizing') {
+      await waitForApproval({ pending, baseUrl, http, signal });
+      const exchange = await exchangeAuthorization({ pending, baseUrl, http, signal });
+      const active = {
+        token: pending.token,
+        agentId: exchange.agent?.id || null,
+        credentialId: exchange.credential.id,
+        tokenPrefix: exchange.credential.tokenPrefix,
+      };
+      await store.write('active', active);
+      pending = { ...pending, phase: 'authorized' };
+      await store.write('pending', pending);
+      return active;
+    }
+    return store.read('active');
+  } catch (error) {
+    if (isTerminalAuthorizationError(error)) await store.remove('pending');
+    throw error;
+  }
+}
+
+function isTerminalAuthorizationError(error) {
+  return error instanceof AgentNetworkHttpError
+    && [
+      'DEVICE_AUTHORIZATION_DENIED',
+      'DEVICE_AUTHORIZATION_EXCHANGED',
+      'DEVICE_AUTHORIZATION_EXPIRED',
+    ].includes(error.code);
+}
+
+function isInvalidAgentCredential(error) {
+  return error instanceof AgentNetworkHttpError
+    && [
+      'AGENT_CREDENTIAL_EXPIRED',
+      'AGENT_CREDENTIAL_INVALID',
+      'AGENT_CREDENTIAL_REVOKED',
+    ].includes(error.code);
+}
+
+async function executeAndFinalize({ pending, active, dependencies }) {
+  assertActiveCredential(active);
+  try {
+    const result = await executeBusinessRequest({
+      operation: pending.operation,
+      token: active.token,
+      ...dependencies,
+    });
+    await dependencies.store.remove('pending');
+    return result;
+  } catch (error) {
+    if (error instanceof AgentNetworkHttpError && error.status < 500 && error.status !== 429) {
+      await dependencies.store.remove('pending');
+      if (isInvalidAgentCredential(error)) await dependencies.store.remove('active');
+    }
+    throw error;
+  }
+}
+
+export function createConnector({ store, browser, baseUrl, http, client }) {
+  let executionQueue = Promise.resolve();
+
+  const dependencies = (signal) => ({ store, browser, baseUrl, http, client, signal });
+
+  async function authorizeAndExecute(operation, signal) {
+    const active = await authorize({ operation, ...dependencies(signal) });
+    const pending = await store.read('pending');
+    return executeAndFinalize({ pending, active, dependencies: dependencies(signal) });
+  }
+
+  async function resumePending(pending, operation, signal) {
+    assertPendingMatches(pending, operation);
+    return authorizeAndExecute(pending.operation, signal);
+  }
+
+  async function executeWithActive(operation, active, signal) {
+    try {
+      return await executeBusinessRequest({ operation, token: active.token, baseUrl, http, signal });
+    } catch (error) {
+      if (!isInvalidAgentCredential(error)) throw error;
+      await store.remove('active');
+      return authorizeAndExecute(operation, signal);
+    }
+  }
+
+  async function executeOnce(params, { signal } = {}) {
+    if (signal?.aborted) throw signal.reason;
+    const normalized = validateBusinessRequest(params);
+    const operation = { ...normalized, body: params.body };
+    const reauthorize = params.reauthorize === true;
+    const pending = await store.read('pending');
+    const active = await store.read('active');
+
+    if (pending) return resumePending(pending, operation, signal);
+
+    if (isPublicDiscoveryRequest(operation) && !reauthorize) {
+      return executeBusinessRequest({ operation, baseUrl, http, signal });
+    }
+
+    if (!active || reauthorize) return authorizeAndExecute(operation, signal);
+    return executeWithActive(operation, active, signal);
+  }
+
+  return {
+    execute(params, options) {
+      const result = executionQueue.then(() => executeOnce(params, options));
+      executionQueue = result.catch(() => undefined);
+      return result;
+    },
+  };
+}

package/src/runtime/constants.js

@@ -0,0 +1,10 @@
+export const DEFAULT_BASE_URL = 'https://tokensmind.ai';
+export const DEVICE_CODE_PREFIX = 'tm_device_';
+export const AGENT_TOKEN_PREFIX = 'tm_agent_';
+export const DEVICE_AUTHORIZATION_PATH = '/agent-network-api/device-authorizations';
+export const MUTATION_METHODS = new Set(['POST', 'PATCH', 'DELETE']);
+
+export const INTERNAL_PATH_PATTERNS = [
+  /^\/agent-network-api\/device-authorizations(?:\/|$)/,
+  /^\/agent-network-api\/agents\/[^/]+\/credentials(?:\/|$)/,
+];

package/src/runtime/credentialStore.js

@@ -0,0 +1,162 @@
+import { isDeepStrictEqual } from 'node:util';
+import os from 'node:os';
+import path from 'node:path';
+import {
+  createPortableStore,
+  originNamespace,
+  resolvePortableStateDir,
+} from './portableStore.js';
+import { resolveSystemCredentialStore } from './systemCredentialStore.js';
+
+const RECORD_NAMES = Object.freeze(['instance', 'pending', 'active']);
+
+function requireHome(homeDir) {
+  const home = String(homeDir || '').trim();
+  if (!home) throw new Error('Unable to resolve the current user home directory');
+  return home;
+}
+
+function windowsLegacyDirs(env) {
+  const localAppData = String(env.LOCALAPPDATA || '').trim();
+  return localAppData ? [path.win32.join(localAppData, 'TokensMind', 'AgentNetwork')] : [];
+}
+
+function linuxLegacyDirs({ env, home }) {
+  const defaultDirectory = path.join(home, '.local', 'state', 'tokensmind', 'agent-network');
+  const xdgStateHome = String(env.XDG_STATE_HOME || '').trim();
+  if (!xdgStateHome) return [defaultDirectory];
+  return [...new Set([
+    path.join(xdgStateHome, 'tokensmind', 'agent-network'), defaultDirectory,
+  ])];
+}
+
+export function resolveLegacyStateDirs({
+  platform = process.platform,
+  env = process.env,
+  homeDir = os.homedir(),
+} = {}) {
+  const home = requireHome(homeDir);
+  if (platform === 'darwin') {
+    return [path.join(home, 'Library', 'Application Support', 'TokensMind', 'AgentNetwork')];
+  }
+  if (platform === 'win32') return windowsLegacyDirs(env);
+  if (platform !== 'linux') return [];
+  return linuxLegacyDirs({ env, home });
+}
+
+async function collectSourceRecords(sources) {
+  const candidates = new Map();
+  for (const source of sources) {
+    for (const name of RECORD_NAMES) {
+      const value = await source.read(name);
+      if (value === null) continue;
+      const candidate = candidates.get(name);
+      if (candidate && !isDeepStrictEqual(candidate.value, value)) {
+        throw new Error(`Conflicting Agent Network ${name} records exist in known local stores`);
+      }
+      if (candidate) candidate.sources.push(source);
+      else candidates.set(name, { value, sources: [source] });
+    }
+  }
+  return candidates;
+}
+
+async function validateMigrationTarget(target, candidates) {
+  const missing = [];
+  for (const [name, candidate] of candidates) {
+    const current = await target.read(name);
+    if (current === null) missing.push([name, candidate.value]);
+    else if (!isDeepStrictEqual(current, candidate.value)) {
+      throw new Error(`Stored Agent Network ${name} conflicts with a known legacy record`);
+    }
+  }
+  return missing;
+}
+
+async function verifyWrites(target, records) {
+  for (const [name, expected] of records) {
+    const actual = await target.read(name);
+    if (!isDeepStrictEqual(actual, expected)) {
+      throw new Error(`Agent Network ${name} migration could not be verified`);
+    }
+  }
+}
+
+async function removeMigratedSources(candidates) {
+  for (const [name, candidate] of candidates) {
+    for (const source of candidate.sources) await source.remove(name);
+  }
+}
+
+export async function migrateCredentialStores({ target, sources }) {
+  const candidates = await collectSourceRecords(sources);
+  if (candidates.size === 0) return;
+  const missing = await validateMigrationTarget(target, candidates);
+  for (const [name, value] of missing) await target.write(name, value);
+  await verifyWrites(target, [...candidates].map(([name, item]) => [name, item.value]));
+  await removeMigratedSources(candidates);
+}
+
+function createLazyStore(resolveStore) {
+  let storePromise;
+  const getStore = () => {
+    storePromise ||= resolveStore();
+    return storePromise;
+  };
+  return {
+    async read(name) {
+      return (await getStore()).read(name);
+    },
+    async write(name, value) {
+      return (await getStore()).write(name, value);
+    },
+    async remove(name) {
+      return (await getStore()).remove(name);
+    },
+  };
+}
+
+function createFileStores({ directories, origin, platform, env, homeDir, fs, randomId }) {
+  return directories.map((stateDir) => createPortableStore({
+    stateDir, origin, platform, env, homeDir, fs, randomId,
+  }));
+}
+
+export function createCredentialStore({
+  stateDir,
+  origin,
+  platform = process.platform,
+  env = process.env,
+  homeDir = os.homedir(),
+  fs,
+  randomId,
+  secureStore,
+  resolveSecureStore = resolveSystemCredentialStore,
+  run,
+} = {}) {
+  if (stateDir) {
+    return createPortableStore({ stateDir, origin, platform, env, homeDir, fs, randomId });
+  }
+  const fallbackDirectory = resolvePortableStateDir({ platform, env, homeDir });
+  const fallback = createPortableStore({
+    stateDir: fallbackDirectory, origin, platform, env, homeDir, fs, randomId,
+  });
+  return createLazyStore(async () => {
+    const systemStore = secureStore === undefined
+      ? await resolveSecureStore({
+        platform, namespace: originNamespace(origin), env, fs, run,
+      })
+      : secureStore;
+    const target = systemStore || fallback;
+    const sourceDirectories = [
+      ...(systemStore ? [fallbackDirectory] : []),
+      ...resolveLegacyStateDirs({ platform, env, homeDir }),
+    ];
+    const sources = createFileStores({
+      directories: [...new Set(sourceDirectories)],
+      origin, platform, env, homeDir, fs, randomId,
+    });
+    await migrateCredentialStores({ target, sources });
+    return target;
+  });
+}

package/src/runtime/crypto.js

@@ -0,0 +1,25 @@
+import { createHash, randomBytes, randomUUID } from 'node:crypto';
+
+function randomCredential(prefix) {
+  return `${prefix}${randomBytes(32).toString('base64url')}`;
+}
+
+export function sha256(value) {
+  return createHash('sha256').update(value, 'utf8').digest('hex');
+}
+
+export function createAuthorizationMaterial({ devicePrefix, tokenPrefix }) {
+  const deviceCode = randomCredential(devicePrefix);
+  const token = randomCredential(tokenPrefix);
+
+  return {
+    authorizationId: randomUUID(),
+    createIdempotencyKey: randomUUID(),
+    exchangeIdempotencyKey: randomUUID(),
+    deviceCode,
+    deviceCodeHash: sha256(deviceCode),
+    token,
+    tokenHash: sha256(token),
+    tokenPrefix: token.slice(0, 20),
+  };
+}

package/src/runtime/deviceAuthorization.js

@@ -0,0 +1,194 @@
+import {
+  AGENT_TOKEN_PREFIX,
+  DEVICE_AUTHORIZATION_PATH,
+  DEVICE_CODE_PREFIX,
+} from './constants.js';
+import { createAuthorizationMaterial } from './crypto.js';
+import { AgentNetworkHttpError } from './httpClient.js';
+
+const DEVICE_STATUSES = new Set(['pending', 'approved', 'denied', 'expired', 'exchanged']);
+const CLIENT_FIELDS = ['name', 'version', 'deviceName', 'platform'];
+
+function headers({ bearer, idempotencyKey } = {}) {
+  return {
+    'Content-Type': 'application/json',
+    ...(bearer ? { Authorization: `Bearer ${bearer}` } : {}),
+    ...(idempotencyKey ? { 'Idempotency-Key': idempotencyKey } : {}),
+  };
+}
+
+function sleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(signal.reason || new Error('Agent Network authorization aborted'));
+    };
+    const timer = setTimeout(() => {
+      signal?.removeEventListener('abort', onAbort);
+      resolve();
+    }, ms);
+    signal?.addEventListener('abort', onAbort, { once: true });
+  });
+}
+
+function isExpectedVerificationUrl(url, pending, baseUrl) {
+  const expectedPath = `/console/agent-network/authorize/${encodeURIComponent(pending.authorizationId)}`;
+  return url.origin === baseUrl
+    && url.pathname === expectedPath
+    && !url.search
+    && !url.hash;
+}
+
+function hasValidExpiry(response) {
+  const expiresAt = Date.parse(response.expiresAt);
+  return Number.isFinite(expiresAt) && expiresAt > Date.now();
+}
+
+function hasValidInterval(response) {
+  return Number.isInteger(response.intervalSeconds) && response.intervalSeconds > 0;
+}
+
+function assertCreateResponse(response, pending, baseUrl) {
+  if (response?.authorizationId !== pending.authorizationId) {
+    throw new Error('Agent Network authorization response has a mismatched identifier');
+  }
+  const verificationUrl = new URL(response.verificationUrl);
+  if (!isExpectedVerificationUrl(verificationUrl, pending, baseUrl)) {
+    throw new Error('Agent Network returned an invalid verification URL');
+  }
+  if (!hasValidExpiry(response)) {
+    throw new Error('Agent Network returned an invalid authorization expiry');
+  }
+  if (!hasValidInterval(response)) {
+    throw new Error('Agent Network returned an invalid polling interval');
+  }
+  if (typeof response.userCode !== 'string' || !response.userCode) {
+    throw new Error('Agent Network authorization response is missing its user code');
+  }
+}
+
+function hasMatchingCredential(exchange, pending, agentId) {
+  return Boolean(exchange.credential?.id)
+    && exchange.credential.agentId === agentId
+    && exchange.credential.tokenPrefix === pending.tokenPrefix;
+}
+
+function exposesCredentialMaterial(exchange) {
+  if (Object.hasOwn(exchange, 'apiToken')) return true;
+  if (Object.hasOwn(exchange.credential, 'tokenHash')) return true;
+  return Object.hasOwn(exchange.credential, 'apiToken');
+}
+
+function assertStatusResponse(status, pending) {
+  if (status?.authorizationId !== pending.authorizationId
+    || !DEVICE_STATUSES.has(status?.status)) {
+    throw new Error('Agent Network returned an invalid authorization status');
+  }
+  if (Date.parse(status.expiresAt) !== Date.parse(pending.authorization.expiresAt)) {
+    throw new Error('Agent Network authorization expiry changed unexpectedly');
+  }
+}
+
+function assertExchange(exchange, pending) {
+  if (exchange?.status !== 'exchanged') {
+    throw new Error('Agent Network credential exchange did not complete');
+  }
+  if (exchange.authorizationId !== pending.authorizationId) {
+    throw new Error('Agent Network credential exchange has a mismatched identifier');
+  }
+  if (exchange.credential?.tokenPrefix !== pending.tokenPrefix) {
+    throw new Error('Agent Network credential prefix verification failed');
+  }
+  const agentId = exchange.agent?.id || null;
+  if (!hasMatchingCredential(exchange, pending, agentId)) {
+    throw new Error('Agent Network exchange response is missing credential metadata');
+  }
+  if (exposesCredentialMaterial(exchange)) {
+    throw new Error('Agent Network exchange response exposed forbidden credential material');
+  }
+}
+
+function assertClientMetadata(client) {
+  if (!client || CLIENT_FIELDS.some((field) => typeof client[field] !== 'string'
+    || !client[field].trim())) {
+    throw new Error('Agent Network client metadata is incomplete');
+  }
+}
+
+export function createPendingAuthorization({ operation, instanceId }) {
+  return {
+    phase: 'prepared',
+    operation,
+    instanceId,
+    ...createAuthorizationMaterial({
+      devicePrefix: DEVICE_CODE_PREFIX,
+      tokenPrefix: AGENT_TOKEN_PREFIX,
+    }),
+  };
+}
+
+export async function createRemoteAuthorization({ pending, baseUrl, http, client, signal }) {
+  assertClientMetadata(client);
+  const response = await http.request({
+    url: `${baseUrl}${DEVICE_AUTHORIZATION_PATH}`,
+    method: 'POST',
+    headers: headers({ idempotencyKey: pending.createIdempotencyKey }),
+    body: {
+      authorizationId: pending.authorizationId,
+      deviceCodeHash: pending.deviceCodeHash,
+      client: {
+        ...client,
+        instanceId: pending.instanceId,
+      },
+      credential: { tokenHash: pending.tokenHash, tokenPrefix: pending.tokenPrefix },
+    },
+    signal,
+  });
+  assertCreateResponse(response, pending, baseUrl);
+  return { ...pending, phase: 'authorizing', authorization: response };
+}
+
+async function pollOnce({ pending, baseUrl, http, signal }) {
+  return http.request({
+    url: `${baseUrl}${DEVICE_AUTHORIZATION_PATH}/${pending.authorizationId}`,
+    headers: headers({ bearer: pending.deviceCode }),
+    signal,
+  });
+}
+
+export async function waitForApproval({ pending, baseUrl, http, signal }) {
+  const intervalMs = pending.authorization.intervalSeconds * 1000;
+  while (Date.now() < Date.parse(pending.authorization.expiresAt)) {
+    const status = await pollOnce({ pending, baseUrl, http, signal });
+    assertStatusResponse(status, pending);
+    if (status.status === 'approved' || status.status === 'exchanged') return status;
+    if (status.status !== 'pending') {
+      const denied = status.status === 'denied';
+      throw new AgentNetworkHttpError({
+        status: denied ? 403 : 410,
+        code: denied ? 'DEVICE_AUTHORIZATION_DENIED' : 'DEVICE_AUTHORIZATION_EXPIRED',
+        message: `Agent Network authorization ended with status ${status.status}`,
+      });
+    }
+    await sleep(intervalMs, signal);
+  }
+  throw new AgentNetworkHttpError({
+    status: 410,
+    code: 'DEVICE_AUTHORIZATION_EXPIRED',
+    message: 'Agent Network authorization expired',
+  });
+}
+
+export async function exchangeAuthorization({ pending, baseUrl, http, signal }) {
+  const exchange = await http.request({
+    url: `${baseUrl}${DEVICE_AUTHORIZATION_PATH}/${pending.authorizationId}/exchange`,
+    method: 'POST',
+    headers: headers({
+      bearer: pending.deviceCode,
+      idempotencyKey: pending.exchangeIdempotencyKey,
+    }),
+    signal,
+  });
+  assertExchange(exchange, pending);
+  return exchange;
+}

package/src/runtime/httpClient.js

@@ -0,0 +1,54 @@
+export class AgentNetworkHttpError extends Error {
+  constructor({ status, code, message, response, retryAfter, correction }) {
+    super(message || `Agent Network request failed with HTTP ${status}`);
+    this.name = 'AgentNetworkHttpError';
+    this.status = status;
+    this.code = code;
+    this.response = response;
+    this.retryAfter = retryAfter;
+    this.correction = correction;
+  }
+}
+
+async function parseResponse(response) {
+  const text = await response.text();
+  if (!text) return null;
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new Error(`Agent Network returned non-JSON HTTP ${response.status}`);
+  }
+}
+
+function unwrapSuccess(response, payload) {
+  if (!response.ok) return undefined;
+  if (payload?.success === true && Object.hasOwn(payload, 'data')) return payload.data;
+  throw new Error('Agent Network returned an invalid success response envelope');
+}
+
+function throwHttpError(response, payload) {
+  throw new AgentNetworkHttpError({
+    status: response.status,
+    code: payload?.code,
+    message: payload?.message,
+    response: payload,
+    retryAfter: response.headers.get('Retry-After'),
+    correction: payload?.correction,
+  });
+}
+
+export function createHttpClient({ fetchImpl = fetch } = {}) {
+  return {
+    async request({ url, method = 'GET', headers, body, signal }) {
+      const response = await fetchImpl(url, {
+        method,
+        headers,
+        body: body === undefined ? undefined : JSON.stringify(body),
+        signal,
+      });
+      const payload = await parseResponse(response);
+      if (response.ok) return unwrapSuccess(response, payload);
+      return throwHttpError(response, payload);
+    },
+  };
+}