@tokensmind/agent-network 0.1.0

package/skills/tokensmind-agent-network-runtime/scripts/lib/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/skills/tokensmind-agent-network-runtime/scripts/lib/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/skills/tokensmind-agent-network-runtime/scripts/lib/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);
+    },
+  };
+}

package/skills/tokensmind-agent-network-runtime/scripts/lib/runtime/portableStore.js

@@ -0,0 +1,193 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { promises as defaultFs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const DIRECTORY_MODE = 0o700;
+const FILE_MODE = 0o600;
+const RECORD_NAMES = new Set(['active', 'pending', 'instance']);
+const PENDING_PHASES = new Set(['prepared', 'authorizing', 'authorized']);
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const SHA256_PATTERN = /^[a-f0-9]{64}$/;
+const DEVICE_CODE_PATTERN = /^tm_device_[A-Za-z0-9_-]{43}$/;
+const AGENT_TOKEN_PATTERN = /^tm_agent_[A-Za-z0-9_-]{43}$/;
+
+function requireHomeDirectory(homeDir) {
+  const value = String(homeDir || '').trim();
+  if (!value) throw new Error('Unable to resolve the current user home directory');
+  return value;
+}
+
+export function resolvePortableStateDir({
+  platform = process.platform,
+  homeDir = os.homedir(),
+} = {}) {
+  const pathApi = platform === 'win32' ? path.win32 : path;
+  return pathApi.join(requireHomeDirectory(homeDir), '.tokensmind', 'agent-network');
+}
+
+function isObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function isNonEmptyString(value) {
+  return typeof value === 'string' && value.length > 0;
+}
+
+function isOperation(value) {
+  return isObject(value)
+    && ['GET', 'POST', 'PATCH', 'DELETE'].includes(value.method)
+    && isNonEmptyString(value.path);
+}
+
+function isInstance(value) {
+  return isObject(value) && UUID_PATTERN.test(value.id);
+}
+
+function isActive(value) {
+  return isObject(value)
+    && AGENT_TOKEN_PATTERN.test(value.token)
+    && (value.agentId === null || isNonEmptyString(value.agentId))
+    && isNonEmptyString(value.credentialId)
+    && isNonEmptyString(value.tokenPrefix)
+    && value.token.startsWith(value.tokenPrefix);
+}
+
+function hasPendingSecrets(value) {
+  return UUID_PATTERN.test(value.authorizationId)
+    && UUID_PATTERN.test(value.instanceId)
+    && UUID_PATTERN.test(value.createIdempotencyKey)
+    && UUID_PATTERN.test(value.exchangeIdempotencyKey)
+    && DEVICE_CODE_PATTERN.test(value.deviceCode)
+    && SHA256_PATTERN.test(value.deviceCodeHash)
+    && AGENT_TOKEN_PATTERN.test(value.token)
+    && SHA256_PATTERN.test(value.tokenHash)
+    && isNonEmptyString(value.tokenPrefix)
+    && value.token.startsWith(value.tokenPrefix);
+}
+
+function hasAuthorization(value) {
+  return isObject(value.authorization)
+    && value.authorization.authorizationId === value.authorizationId
+    && isNonEmptyString(value.authorization.verificationUrl)
+    && Number.isFinite(Date.parse(value.authorization.expiresAt))
+    && Number.isInteger(value.authorization.intervalSeconds)
+    && value.authorization.intervalSeconds > 0;
+}
+
+function isPending(value) {
+  if (!isObject(value) || !PENDING_PHASES.has(value.phase)) return false;
+  if (!isOperation(value.operation) || !hasPendingSecrets(value)) return false;
+  return value.phase === 'prepared' || hasAuthorization(value);
+}
+
+export function validatePortableRecord(name, value) {
+  const valid = name === 'active'
+    ? isActive(value)
+    : name === 'pending'
+      ? isPending(value)
+      : isInstance(value);
+  if (!valid) throw new Error(`Portable Agent Network ${name} state has an invalid structure`);
+}
+
+function validateRecordName(name) {
+  if (!RECORD_NAMES.has(name)) throw new Error(`Unsupported portable state record: ${name}`);
+}
+
+export function originNamespace(origin) {
+  const url = new URL(origin);
+  if (!['http:', 'https:'].includes(url.protocol) || url.origin !== origin) {
+    throw new Error('Portable Agent Network store requires a normalized HTTP origin');
+  }
+  return createHash('sha256').update(origin, 'utf8').digest('hex');
+}
+
+function isMissing(error) {
+  return error?.code === 'ENOENT';
+}
+
+async function ensurePrivateDirectory({ fs, directory, platform }) {
+  await fs.mkdir(directory, { recursive: true, mode: DIRECTORY_MODE });
+  if (platform !== 'win32') await fs.chmod(directory, DIRECTORY_MODE);
+}
+
+async function removeTemporaryFile(fs, filePath) {
+  try {
+    await fs.unlink(filePath);
+  } catch (error) {
+    if (!isMissing(error)) throw error;
+  }
+}
+
+function createReadOperation({ fs, recordPath }) {
+  return async function read(name) {
+    validateRecordName(name);
+    let source;
+    try {
+      source = await fs.readFile(recordPath(name), 'utf8');
+    } catch (error) {
+      if (isMissing(error)) return null;
+      throw error;
+    }
+    let value;
+    try {
+      value = JSON.parse(source);
+    } catch (error) {
+      throw new Error(`Portable Agent Network ${name} state is invalid JSON`, { cause: error });
+    }
+    validatePortableRecord(name, value);
+    return value;
+  };
+}
+
+function createWriteOperation({ fs, directory, platform, randomId, recordPath }) {
+  return async function write(name, value) {
+    validateRecordName(name);
+    validatePortableRecord(name, value);
+    await ensurePrivateDirectory({ fs, directory, platform });
+    const target = recordPath(name);
+    const temporary = path.join(directory, `.${name}.${process.pid}.${randomId()}.tmp`);
+    try {
+      await fs.writeFile(temporary, JSON.stringify(value), {
+        encoding: 'utf8', mode: FILE_MODE, flag: 'wx',
+      });
+      if (platform !== 'win32') await fs.chmod(temporary, FILE_MODE);
+      await fs.rename(temporary, target);
+      if (platform !== 'win32') await fs.chmod(target, FILE_MODE);
+    } catch (error) {
+      await removeTemporaryFile(fs, temporary);
+      throw error;
+    }
+  };
+}
+
+function createRemoveOperation({ fs, recordPath }) {
+  return async function remove(name) {
+    validateRecordName(name);
+    try {
+      await fs.unlink(recordPath(name));
+    } catch (error) {
+      if (!isMissing(error)) throw error;
+    }
+  };
+}
+
+export function createPortableStore({
+  stateDir,
+  origin,
+  platform = process.platform,
+  env = process.env,
+  homeDir = os.homedir(),
+  fs = defaultFs,
+  randomId = randomUUID,
+} = {}) {
+  const baseDirectory = path.resolve(stateDir || resolvePortableStateDir({ platform, env, homeDir }));
+  const directory = path.join(baseDirectory, originNamespace(origin));
+  const recordPath = (name) => path.join(directory, `${name}.json`);
+  const context = { fs, directory, platform, randomId, recordPath };
+  return {
+    read: createReadOperation(context),
+    write: createWriteOperation(context),
+    remove: createRemoveOperation(context),
+  };
+}

package/skills/tokensmind-agent-network-runtime/scripts/lib/runtime/requestPolicy.js

@@ -0,0 +1,55 @@
+import { INTERNAL_PATH_PATTERNS, MUTATION_METHODS } from './constants.js';
+
+const SUPPORTED_METHODS = new Set(['GET', 'POST', 'PATCH', 'DELETE']);
+const PUBLIC_AGENT_DIRECTORY_PATH = '/agent-network-api/agents';
+
+export function normalizeBaseUrl(value) {
+  const url = new URL(value);
+  if (!['http:', 'https:'].includes(url.protocol)) {
+    throw new Error('Agent Network baseUrl must use http or https');
+  }
+  url.pathname = '/';
+  url.search = '';
+  url.hash = '';
+  return url.origin;
+}
+
+export function validateBusinessRequest({ method, path, idempotencyKey, reauthorize }) {
+  const normalizedMethod = String(method).toUpperCase();
+  if (!SUPPORTED_METHODS.has(normalizedMethod)) {
+    throw new Error(`Unsupported Agent Network method: ${normalizedMethod}`);
+  }
+  if (!path.startsWith('/agent-network-api/')) {
+    throw new Error('Agent Network path must start with /agent-network-api/');
+  }
+  if (INTERNAL_PATH_PATTERNS.some((pattern) => pattern.test(path))) {
+    throw new Error('This endpoint is not available through the ordinary-user connector');
+  }
+  if (MUTATION_METHODS.has(normalizedMethod) && !idempotencyKey?.trim()) {
+    throw new Error('Mutating Agent Network requests require a stable Idempotency-Key');
+  }
+  if (reauthorize !== undefined && typeof reauthorize !== 'boolean') {
+    throw new Error('Agent Network reauthorize must be a boolean');
+  }
+  return { method: normalizedMethod, path, idempotencyKey: idempotencyKey?.trim() };
+}
+
+export function buildBusinessUrl(baseUrl, path) {
+  const url = new URL(path, `${baseUrl}/`);
+  if (url.origin !== baseUrl || !url.pathname.startsWith('/agent-network-api/')) {
+    throw new Error('Agent Network request must remain on the configured origin');
+  }
+  if (INTERNAL_PATH_PATTERNS.some((pattern) => pattern.test(url.pathname))) {
+    throw new Error('This endpoint is not available through the ordinary-user connector');
+  }
+  return url.toString();
+}
+
+export function isPublicDiscoveryRequest({ method, path }) {
+  if (method !== 'GET') return false;
+  const url = new URL(path, 'https://tokensmind.invalid');
+  const mineRequested = [...url.searchParams.entries()]
+    .some(([key, value]) => key === 'mine' && value === '1');
+  return url.pathname === PUBLIC_AGENT_DIRECTORY_PATH
+    && !mineRequested;
+}

package/skills/tokensmind-agent-network-runtime/scripts/lib/runtime/systemCredentialStore.js

@@ -0,0 +1,176 @@
+import { spawn as defaultSpawn } from 'node:child_process';
+import { constants as fsConstants, promises as defaultFs } from 'node:fs';
+import path from 'node:path';
+import { validatePortableRecord } from './portableStore.js';
+
+const SERVICE_NAME = 'TokensMind Agent Network';
+const APPLICATION_NAME = 'tokensmind-agent-network';
+const RECORD_NAMES = new Set(['active', 'pending', 'instance']);
+const MACOS_SECURITY_PATH = '/usr/bin/security';
+const MACOS_ITEM_NOT_FOUND = 44;
+
+function validateRecordName(name) {
+  if (!RECORD_NAMES.has(name)) throw new Error(`Unsupported portable state record: ${name}`);
+}
+
+function credentialAccount(namespace, name) {
+  validateRecordName(name);
+  return `${namespace}:${name}`;
+}
+
+function parseRecord(name, source) {
+  let value;
+  try {
+    value = JSON.parse(source);
+  } catch (error) {
+    throw new Error(`System Agent Network ${name} credential is invalid JSON`, { cause: error });
+  }
+  validatePortableRecord(name, value);
+  return value;
+}
+
+function commandFailure(backend, operation, result) {
+  return new Error(
+    `${backend} ${operation} failed with exit code ${String(result.code)}`,
+  );
+}
+
+export function createCommandRunner({ spawnImpl = defaultSpawn } = {}) {
+  return ({ command, args, input = '' }) => new Promise((resolve, reject) => {
+    const child = spawnImpl(command, args, { stdio: ['pipe', 'pipe', 'pipe'] });
+    const stdout = [];
+    const stderr = [];
+    let settled = false;
+    child.stdout.on('data', (chunk) => stdout.push(chunk));
+    child.stderr.on('data', (chunk) => stderr.push(chunk));
+    child.stdin.on('error', (error) => {
+      if (error.code === 'EPIPE' || settled) return;
+      settled = true;
+      reject(error);
+    });
+    child.on('error', (error) => {
+      if (settled) return;
+      settled = true;
+      reject(error);
+    });
+    child.on('close', (code) => {
+      if (settled) return;
+      resolve({
+        code,
+        stdout: Buffer.concat(stdout).toString('utf8'),
+        stderr: Buffer.concat(stderr).toString('utf8'),
+      });
+    });
+    child.stdin.end(input);
+  });
+}
+
+function createMacOperations({ namespace, run }) {
+  return {
+    async read(name) {
+      const account = credentialAccount(namespace, name);
+      const result = await run({
+        command: MACOS_SECURITY_PATH,
+        args: ['find-generic-password', '-a', account, '-s', SERVICE_NAME, '-w'],
+      });
+      if (result.code === MACOS_ITEM_NOT_FOUND) return null;
+      if (result.code !== 0) throw commandFailure('macOS Keychain', 'read', result);
+      return parseRecord(name, result.stdout.trim());
+    },
+    async write(name, value) {
+      validateRecordName(name);
+      validatePortableRecord(name, value);
+      const account = credentialAccount(namespace, name);
+      const result = await run({
+        command: MACOS_SECURITY_PATH,
+        args: ['add-generic-password', '-a', account, '-s', SERVICE_NAME, '-U', '-w'],
+        input: `${JSON.stringify(value)}\n`,
+      });
+      if (result.code !== 0) throw commandFailure('macOS Keychain', 'write', result);
+    },
+    async remove(name) {
+      const account = credentialAccount(namespace, name);
+      const result = await run({
+        command: MACOS_SECURITY_PATH,
+        args: ['delete-generic-password', '-a', account, '-s', SERVICE_NAME],
+      });
+      if (![0, MACOS_ITEM_NOT_FOUND].includes(result.code)) {
+        throw commandFailure('macOS Keychain', 'remove', result);
+      }
+    },
+  };
+}
+
+function linuxAttributes(namespace, name) {
+  validateRecordName(name);
+  return ['application', APPLICATION_NAME, 'origin', namespace, 'record', name];
+}
+
+function createLinuxOperations({ namespace, command, run }) {
+  async function lookup(name) {
+    const result = await run({
+      command,
+      args: ['lookup', ...linuxAttributes(namespace, name)],
+    });
+    const missing = result.code === 1 && !result.stdout.trim() && !result.stderr.trim();
+    if (missing) return null;
+    if (result.code !== 0) throw commandFailure('Linux Secret Service', 'read', result);
+    return parseRecord(name, result.stdout.trim());
+  }
+  return {
+    read: lookup,
+    async write(name, value) {
+      validatePortableRecord(name, value);
+      const result = await run({
+        command,
+        args: ['store', `--label=${SERVICE_NAME}`, ...linuxAttributes(namespace, name)],
+        input: `${JSON.stringify(value)}\n`,
+      });
+      if (result.code !== 0) throw commandFailure('Linux Secret Service', 'write', result);
+    },
+    async remove(name) {
+      if (await lookup(name) === null) return;
+      const result = await run({
+        command,
+        args: ['clear', ...linuxAttributes(namespace, name)],
+      });
+      if (result.code !== 0) throw commandFailure('Linux Secret Service', 'remove', result);
+    },
+  };
+}
+
+async function isExecutable(fs, filePath) {
+  try {
+    await fs.access(filePath, fsConstants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function findExecutable({ name, env, fs }) {
+  const directories = String(env.PATH || '').split(path.delimiter).filter(Boolean);
+  for (const directory of directories) {
+    const candidate = path.join(directory, name);
+    if (await isExecutable(fs, candidate)) return candidate;
+  }
+  return null;
+}
+
+export async function resolveSystemCredentialStore({
+  platform,
+  namespace,
+  env = process.env,
+  fs = defaultFs,
+  run = createCommandRunner(),
+} = {}) {
+  if (platform === 'darwin') {
+    if (!await isExecutable(fs, MACOS_SECURITY_PATH)) return null;
+    return createMacOperations({ namespace, run });
+  }
+  if (platform === 'linux') {
+    const command = await findExecutable({ name: 'secret-tool', env, fs });
+    return command ? createLinuxOperations({ namespace, command, run }) : null;
+  }
+  return null;
+}