@xmemo/skill 1.1.25

package/skill/scripts/lib/core.mjs

@@ -0,0 +1,247 @@
+import path from 'node:path';
+import os from 'node:os';
+
+export const credentialsPath = path.join(os.homedir(), '.xmemo', 'skill-credentials.json');
+export const registrationPath = path.join(os.homedir(), '.xmemo', 'skill-registration.json');
+export const SCRIPT_COMMAND = 'node scripts/xmemo-skill.mjs';
+export const PLAINTEXT_STORAGE = 'plaintext-user-file';
+export const DEFAULT_BASE_URL = 'https://xmemo.dev';
+export const DEFAULT_TIMEOUT_MS = 30_000;
+export const MAX_TIMEOUT_MS = 300_000;
+export const MAX_RESPONSE_BYTES = 8_388_608;
+// Maximum memory content limit (512 KiB), matching memory-os server models/memory_schema.py: MAX_MEMORY_CONTENT_BYTES
+export const MAX_MEMORY_CONTENT_BYTES = 524_288;
+export const MAX_STATE_TTL_SECONDS = 2_592_000;
+export const DEFAULT_TEMPORARY_LIMITS = Object.freeze({
+  max_items: 100,
+  ttl_seconds: 1_209_600,
+  max_lifetime_seconds: 2_592_000,
+});
+export const EXIT_CODE = Object.freeze({
+  SUCCESS: 0,
+  USER_ERROR: 1,
+  AUTH_ERROR: 2,
+  SERVER_ERROR: 3,
+});
+
+export function exitCodeForHttpStatus(statusCode) {
+  const code = Number(statusCode);
+  if (code >= 200 && code < 300) {
+    return EXIT_CODE.SUCCESS;
+  }
+  if (code === 401 || code === 403) {
+    return EXIT_CODE.AUTH_ERROR;
+  }
+  if (code >= 500) {
+    return EXIT_CODE.SERVER_ERROR;
+  }
+  return EXIT_CODE.USER_ERROR;
+}
+
+export function exitCodeForErrorCode(code) {
+  if (!code || typeof code !== 'string') return null;
+  const normalized = code.toLowerCase();
+  if (
+    normalized === 'unauthorized' ||
+    normalized === 'forbidden' ||
+    normalized === 'tenant_forbidden' ||
+    normalized === 'auth_error' ||
+    normalized === 'invalid_token' ||
+    normalized === 'token_expired' ||
+    normalized === 'authentication_required' ||
+    normalized === 'missing_credentials'
+  ) {
+    return EXIT_CODE.AUTH_ERROR;
+  }
+  if (
+    normalized === 'server_error' ||
+    normalized === 'internal_error' ||
+    normalized === 'timeout' ||
+    normalized === 'bad_gateway' ||
+    normalized === 'service_unavailable' ||
+    normalized === 'econnrefused' ||
+    normalized === 'enotfound' ||
+    normalized === 'ehostunreach' ||
+    normalized === 'econnreset' ||
+    normalized === 'etimedout' ||
+    normalized === 'esockettimedout'
+  ) {
+    return EXIT_CODE.SERVER_ERROR;
+  }
+  if (
+    normalized === 'bad_request' ||
+    normalized === 'invalid_argument' ||
+    normalized === 'not_found' ||
+    normalized === 'rate_limited' ||
+    normalized === 'rate_limit_exceeded' ||
+    normalized === 'precondition_required'
+  ) {
+    return EXIT_CODE.USER_ERROR;
+  }
+  if (normalized.startsWith('http 401') || normalized.startsWith('http 403')) {
+    return EXIT_CODE.AUTH_ERROR;
+  }
+  if (normalized.startsWith('http 5')) {
+    return EXIT_CODE.SERVER_ERROR;
+  }
+  if (normalized.startsWith('http 4')) {
+    return EXIT_CODE.USER_ERROR;
+  }
+  return null;
+}
+
+export function exitCodeForError(err) {
+  if (!err) return EXIT_CODE.USER_ERROR;
+  if (typeof err.exitCode === 'number') {
+    return err.exitCode;
+  }
+  const status = Number(err.statusCode || err.status || err.httpStatus);
+  if (Number.isInteger(status) && status > 0) {
+    return exitCodeForHttpStatus(status);
+  }
+  const code = String(err.code || '').toUpperCase();
+  if (['ECONNREFUSED', 'ENOTFOUND', 'EHOSTUNREACH', 'ECONNRESET', 'ETIMEDOUT', 'ESOCKETTIMEDOUT', 'EAI_AGAIN', 'EPIPE'].includes(code)) {
+    return EXIT_CODE.SERVER_ERROR;
+  }
+  const msg = String(err.message || err).toLowerCase();
+  if (
+    msg.includes('timed out') ||
+    msg.includes('timeout') ||
+    msg.includes('safety limit') ||
+    msg.includes('socket hang up') ||
+    msg.includes('interrupted') ||
+    msg.includes('econnrefused') ||
+    msg.includes('enotfound') ||
+    msg.includes('ehostunreach') ||
+    msg.includes('server response exceeded') ||
+    msg.includes('server returned a non-json response') ||
+    msg.includes('server returned an empty response')
+  ) {
+    return EXIT_CODE.SERVER_ERROR;
+  }
+  if (
+    msg.includes('401') ||
+    msg.includes('unauthorized') ||
+    msg.includes('403') ||
+    msg.includes('forbidden') ||
+    msg.includes('invalid or expired token') ||
+    msg.includes('no xmemo credential found') ||
+    msg.includes('authentication required')
+  ) {
+    return EXIT_CODE.AUTH_ERROR;
+  }
+  return EXIT_CODE.USER_ERROR;
+}
+
+export const REST_COMMANDS = new Set([
+  'read', 'update', 'forget',
+  'ledger-list', 'ledger-summary',
+  'overview', 'activity', 'stats',
+  'remember', 'recall', 'search', 'save-state', 'restore-state', 'state-save', 'state-restore',
+  'restart-snapshot', 'restart-restore', 'recall-context',
+  'todo-add', 'todo-list', 'todo-done', 'expense-add', 'doctor',
+]);
+
+export const COMMAND_FLAGS = {
+  login: new Set(),
+  register: new Set(['reason']),
+  logout: new Set(),
+  doctor: new Set(),
+  read: new Set(['id', 'offset', 'limit', 'bucket', 'scope']),
+  update: new Set(['id', 'content', 'path', 'metadata', 'bucket', 'scope']),
+  forget: new Set(['id', 'reason', 'confirm']),
+  'ledger-list': new Set(['limit', 'offset', 'currency', 'from', 'to', 'category', 'min-amount', 'max-amount', 'type', 'month']),
+  'ledger-summary': new Set(['months', 'currency', 'type']),
+  overview: new Set(),
+  activity: new Set(['limit']),
+  stats: new Set(['scope', 'path', 'bucket', 'memory-type', 'memory_type', 'status', 'source', 'since', 'until', 'group-by', 'group_by', 'top-n', 'top_n', 'team-id', 'team_id']),
+  remember: new Set(['content', 'file', 'path', 'metadata', 'logic_path', 'bucket', 'scope', 'team_id']),
+  recall: new Set(['query', 'limit', 'threshold', 'path', 'bucket', 'scope', 'team_id', 'memory_type', 'explain', 'prefer_working']),
+  search: new Set(['query', 'limit', 'threshold', 'path', 'bucket', 'scope', 'team_id', 'memory_type', 'explain', 'prefer_working']),
+  'save-state': new Set(['key', 'state_key', 'content', 'current_task', 'next_action', 'blocked_reason', 'ttl_seconds', 'bucket', 'scope']),
+  'state-save': new Set(['key', 'state_key', 'content', 'current_task', 'next_action', 'blocked_reason', 'ttl_seconds', 'bucket', 'scope']),
+  'restore-state': new Set(['key', 'state_key', 'bucket', 'scope']),
+  'state-restore': new Set(['key', 'state_key', 'bucket', 'scope']),
+  'restart-snapshot': new Set(['session_id', 'state_key', 'timeline_limit', 'reminder_limit', 'decision_limit', 'metadata', 'bucket', 'scope', 'path', 'ttl_seconds']),
+  'restart-restore': new Set(['snapshot_id', 'source_session_id', 'target_session_id', 'state_key', 'restore_state', 'record_restore_event', 'ttl_seconds', 'bucket', 'scope']),
+  'recall-context': new Set(['query', 'path', 'bucket', 'scope', 'team_id', 'memory_type', 'status', 'threshold', 'max_items', 'max_tokens', 'limit', 'prefer_working', 'include_knowledge']),
+  'todo-add': new Set(['content', 'due_at', 'bucket', 'scope', 'path']),
+  'todo-list': new Set(['bucket', 'scope', 'status']),
+  'todo-done': new Set(['id', 'todo_id', 'note']),
+  'expense-add': new Set(['item', 'amount', 'currency', 'transaction_date', 'date', 'path', 'bucket', 'scope']),
+};
+
+export const AUTH_FLAGS = {
+  status: new Set(),
+  add: new Set(['from-stdin']),
+  'claim-status': new Set(),
+  'claim-confirm': new Set(),
+  'claim-deny': new Set(),
+};
+
+export function parsePositiveInteger(value, name, max = Number.MAX_SAFE_INTEGER) {
+  if (!/^\d+$/.test(String(value ?? ''))) {
+    throw new Error(`${name} must be a positive integer.`);
+  }
+  const parsed = Number(value);
+  if (!Number.isSafeInteger(parsed) || parsed <= 0 || parsed > max) {
+    throw new Error(`${name} must be between 1 and ${max}.`);
+  }
+  return parsed;
+}
+
+export function parseIntegerInRange(value, name, min, max) {
+  if (!/^\d+$/.test(String(value ?? ''))) {
+    throw new Error(`${name} must be an integer between ${min} and ${max}.`);
+  }
+  const parsed = Number(value);
+  if (!Number.isSafeInteger(parsed) || parsed < min || parsed > max) {
+    throw new Error(`${name} must be between ${min} and ${max}.`);
+  }
+  return parsed;
+}
+
+export function parseJsonObject(value, name) {
+  let parsed;
+  try {
+    parsed = JSON.parse(String(value));
+  } catch {
+    throw new Error(`${name} must be a valid JSON object.`);
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error(`${name} must be a JSON object.`);
+  }
+  return parsed;
+}
+
+export function parseStrictBoolean(value, name) {
+  if (value === true || value === 'true') return true;
+  if (value === false || value === 'false') return false;
+  throw new Error(`${name} must be true or false.`);
+}
+
+export function isLoopbackHostname(hostname) {
+  const normalized = String(hostname || '').toLowerCase();
+  return normalized === 'localhost'
+    || normalized === '127.0.0.1'
+    || normalized === '::1'
+    || normalized === '[::1]';
+}
+
+export function normalizeBaseUrl(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new Error(`Invalid XMemo base URL: ${value}`);
+  }
+  if (url.username || url.password) {
+    throw new Error('XMemo base URL must not contain embedded credentials.');
+  }
+  if (url.protocol !== 'https:' && !(url.protocol === 'http:' && isLoopbackHostname(url.hostname))) {
+    throw new Error('XMemo base URL must use HTTPS. Plain HTTP is allowed only for localhost/loopback development.');
+  }
+  url.hash = '';
+  url.search = '';
+  return url.toString().replace(/\/$/, '');
+}

package/skill/scripts/lib/help.mjs

@@ -0,0 +1,179 @@
+import {
+  SCRIPT_COMMAND,
+  DEFAULT_BASE_URL,
+  DEFAULT_TIMEOUT_MS,
+} from './core.mjs';
+
+export const COMMAND_USAGE_REGISTRY = {
+  login: {
+    usage: 'login --allow-plaintext',
+    desc: 'Start formal device login and explicitly permit local token storage',
+  },
+  register: {
+    usage: 'register --reason <unattended|declined> --allow-plaintext',
+    desc: 'Start limited temporary memory only when formal login is unavailable',
+  },
+  logout: {
+    usage: 'logout [--revoke-environment-token]',
+    desc: 'Revoke and remove a local credential',
+  },
+  'auth status': {
+    usage: 'auth status [--verify]',
+    desc: 'Show local or verified auth status (alias: auth-status)',
+  },
+  'auth add': {
+    usage: 'auth add --from-stdin --allow-plaintext',
+    desc: 'Store a formal token read from standard input',
+  },
+  'auth claim-status': {
+    usage: 'auth claim-status [--allow-plaintext]',
+    desc: 'Check temporary-account claim status',
+  },
+  'auth claim-confirm': {
+    usage: 'auth claim-confirm [--allow-plaintext]',
+    desc: 'Confirm a pending human claim and accept formal token handoff',
+  },
+  'auth claim-deny': {
+    usage: 'auth claim-deny [--allow-plaintext]',
+    desc: 'Decline a pending bind and keep isolated temporary access',
+  },
+  read: {
+    usage: 'read --id <id> [--offset <n>] [--limit <n>] [--bucket <bucket>] [--scope <scope>]',
+  },
+  update: {
+    usage: 'update --id <id> [--content <text>] [--path <path>] [--metadata <json>] [--bucket <bucket>] [--scope <scope>]',
+  },
+  forget: {
+    usage: 'forget --id <id> [--reason <text>] --confirm',
+  },
+  'ledger-list': {
+    usage: 'ledger-list [--month <YYYY-MM>] [--from <date>] [--to <date>] [--currency <code>] [--category <name>] [--type <type>] [--min-amount <n>] [--max-amount <n>] [--limit <n>] [--offset <n>]',
+  },
+  'ledger-summary': {
+    usage: 'ledger-summary [--months <n>] [--currency <code>] [--type <type>]',
+  },
+  overview: {
+    usage: 'overview',
+    desc: 'Show account overview (memories, storage, agents)',
+  },
+  activity: {
+    usage: 'activity [--limit <n>]',
+    desc: 'Show recent account activity',
+  },
+  stats: {
+    usage: 'stats [--scope <scope>] [--path <path>] [--bucket <bucket>] [--memory-type <type>] [--status <status>] [--source <src>] [--since <iso>] [--until <iso>] [--group-by <dims>] [--top-n <1..200>] [--team-id <id>]',
+    desc: 'Show memory statistics and breakdown',
+  },
+  remember: {
+    usage: 'remember (--content <text> | --content - | --file <path>) [--path <path>] [--metadata <json-object>]',
+  },
+  recall: {
+    usage: 'recall --query <text> [--limit <n>] [--explain <true|false>] [--prefer_working <true|false>] [--compact]',
+  },
+  search: {
+    usage: 'search --query <text> [--limit <n>] [--explain <true|false>] [--prefer_working <true|false>] [--compact]',
+  },
+  'recall-context': {
+    usage: 'recall-context --query <text> [--max_items <n>] [--max_tokens <n>] [--prefer_working <true|false>] [--include_knowledge <true|false>]',
+    desc: 'Read-only bounded Memory context; opt into Knowledge with true',
+  },
+  'save-state': {
+    usage: 'save-state --key <key> [--content <text>] [--ttl_seconds <0..604800>]',
+    desc: '(alias: state-save)',
+  },
+  'restore-state': {
+    usage: 'restore-state --key <key>',
+    desc: '(alias: state-restore)',
+  },
+  'state-save': {
+    usage: 'state-save --key <key> [--content <text>] [--ttl_seconds <0..604800>] (legacy alias)',
+    aliasOf: 'save-state',
+  },
+  'state-restore': {
+    usage: 'state-restore --key <key> (legacy alias)',
+    aliasOf: 'restore-state',
+  },
+  'restart-snapshot': {
+    usage: 'restart-snapshot [--state_key <key>] [--session_id <id>] [--ttl_seconds <0..2592000>]',
+    desc: 'Save a full restart-continuity snapshot',
+  },
+  'restart-restore': {
+    usage: 'restart-restore [--snapshot_id <id> | --source_session_id <id>] [--target_session_id <id>]',
+    desc: 'Restore the latest or selected restart snapshot',
+  },
+  'todo-add': {
+    usage: 'todo-add --content <text>',
+  },
+  'todo-list': {
+    usage: 'todo-list',
+  },
+  'todo-done': {
+    usage: 'todo-done --id <todo_id>',
+  },
+  'expense-add': {
+    usage: 'expense-add --item <text> --amount <number> --currency <code>',
+  },
+  doctor: {
+    usage: 'doctor [--anonymous]',
+  },
+};
+
+export function buildTopLevelHelp() {
+  const lines = [
+    'XMemo Standalone Skill Runtime',
+    '',
+    'Usage:',
+    `  ${SCRIPT_COMMAND} <command> [options]`,
+    '',
+    'Commands:',
+  ];
+  for (const entry of Object.values(COMMAND_USAGE_REGISTRY)) {
+    if (entry.aliasOf) continue;
+    if (entry.desc) {
+      lines.push(`  ${entry.usage.padEnd(35)} ${entry.desc}`);
+    } else {
+      lines.push(`  ${entry.usage}`);
+    }
+  }
+  lines.push('');
+  lines.push('Credential resolution:');
+  lines.push('  XMEMO_KEY                          Preferred; never copied to the local credential file');
+  lines.push('  User credential file               Read only as a fallback');
+  lines.push('');
+  lines.push('Global options:');
+  lines.push('  --json                             Print the API response as JSON');
+  lines.push('  --terminal                         Force human-readable terminal output even when piped');
+  lines.push(`  --base-url <url>                   Override ${DEFAULT_BASE_URL}; HTTPS or loopback HTTP only`);
+  lines.push(`  --timeout-ms <ms>                  Per-request timeout (default: ${DEFAULT_TIMEOUT_MS})`);
+  lines.push('  --compact                          Shorten recall/search content for terminals');
+  lines.push('  --allow-plaintext                  Explicitly permit unencrypted user-file credential storage');
+  lines.push('  --version                          Show the Skill runtime version');
+  lines.push('  --help, -h                         Show this help');
+  lines.push('');
+  lines.push(`Run \`${SCRIPT_COMMAND} <command> --help\` for command-specific usage.`);
+  return lines.join('\n');
+}
+
+export function printUsage(command) {
+  const commonOptions = '[--json] [--terminal] [--base-url <url>] [--timeout-ms <ms>]';
+  if (command === undefined || (!COMMAND_USAGE_REGISTRY[command] && command !== 'auth' && command !== 'auth-status')) {
+    console.log(buildTopLevelHelp());
+    return;
+  }
+
+  if (command === 'auth' || command === 'auth-status') {
+    console.log(`Usage:\n  ${SCRIPT_COMMAND} auth status [--verify] ${commonOptions}\n  ${SCRIPT_COMMAND} auth add --from-stdin --allow-plaintext\n  ${SCRIPT_COMMAND} auth claim-status [--allow-plaintext]\n  ${SCRIPT_COMMAND} auth claim-confirm [--allow-plaintext]\n  ${SCRIPT_COMMAND} auth claim-deny [--allow-plaintext]\n\nAlias: ${SCRIPT_COMMAND} auth-status [--verify]\nXMEMO_KEY remains the preferred non-file credential source. --allow-plaintext explicitly permits unencrypted user-file storage.\nRun \`${SCRIPT_COMMAND} --help\` to list all commands.`);
+    return;
+  }
+
+  const entry = COMMAND_USAGE_REGISTRY[command];
+  if (entry) {
+    console.log(`Usage:\n  ${SCRIPT_COMMAND} ${entry.usage} ${commonOptions}`);
+    if (command === 'logout') {
+      console.log('\nXMEMO_KEY is externally managed and is not revoked unless --revoke-environment-token is explicitly passed.');
+    }
+    return;
+  }
+
+  console.log(buildTopLevelHelp());
+}

package/skill/scripts/lib/muse-vault.mjs

@@ -0,0 +1,198 @@
+import http from 'node:http';
+import fs from 'node:fs/promises';
+import { DEFAULT_BASE_URL } from './core.mjs';
+
+export const VAULT_CREDENTIAL_NAME = 'custom.xmemo';
+export const VAULT_ENTRY_NAME = 'access_token';
+export const DEFAULT_AUTHD_SOCKET = '/run/hatch/auth/authd.sock';
+export const VAULT_ALLOWED_ORIGIN = new URL(DEFAULT_BASE_URL).origin;
+export const AUTHD_TIMEOUT_MS = 2000;
+export const MAX_AUTHD_RESPONSE_BYTES = 65536;
+
+export class VaultKeyError extends Error {
+  constructor(message, codeOrOptions = 'authd_error') {
+    super(message);
+    this.name = 'VaultKeyError';
+    if (typeof codeOrOptions === 'string') {
+      this.code = codeOrOptions;
+    } else if (codeOrOptions && typeof codeOrOptions === 'object') {
+      this.code = codeOrOptions.code || 'authd_error';
+      if (codeOrOptions.statusCode !== undefined) this.statusCode = codeOrOptions.statusCode;
+      if (codeOrOptions.cause !== undefined) this.cause = codeOrOptions.cause;
+    } else {
+      this.code = 'authd_error';
+    }
+  }
+}
+
+export function isSurrogateToken(value) {
+  return typeof value === 'string' && value.startsWith('hsurr:');
+}
+
+export function validateSurrogate(token) {
+  if (typeof token !== 'string' || !token.startsWith('hsurr:')) {
+    throw new VaultKeyError('Invalid surrogate token: missing hsurr: prefix', 'authd_error');
+  }
+  if (token.length < 7 || token.length > 4096) {
+    throw new VaultKeyError('Invalid surrogate token: length out of bounds', 'authd_error');
+  }
+  if (/[\s\u0000-\u001F\u007F-\u009F]/.test(token)) {
+    throw new VaultKeyError('Invalid surrogate token: contains whitespace or control characters', 'authd_error');
+  }
+  return token;
+}
+
+export function assertSurrogateOrigin(authHeader, targetUrl) {
+  if (!authHeader || typeof authHeader !== 'string') return;
+  const match = authHeader.match(/^Bearer\s+(\S+)$/i);
+  if (!match) return;
+  const token = match[1];
+  if (!isSurrogateToken(token)) return;
+
+  const urlObj = typeof targetUrl === 'string' ? new URL(targetUrl) : targetUrl;
+  if (urlObj.origin !== new URL(VAULT_ALLOWED_ORIGIN).origin) {
+    throw new Error(
+      `Meta Muse vault credentials (surrogate) are restricted to ${VAULT_ALLOWED_ORIGIN} and cannot be sent to ${urlObj.origin}. Unset XMEMO_BASE_URL or use a standard credential.`
+    );
+  }
+}
+
+export async function getVaultSurrogate(options = {}) {
+  const socketPath = options.socketPath || process.env.JARVIS_AUTHD_SOCK || DEFAULT_AUTHD_SOCKET;
+
+  try {
+    await fs.stat(socketPath);
+  } catch (err) {
+    throw new VaultKeyError(`Auth daemon socket unavailable at ${socketPath}`, 'unavailable');
+  }
+
+  return new Promise((resolve, reject) => {
+    const postData = JSON.stringify({ name: VAULT_CREDENTIAL_NAME });
+    const reqOptions = {
+      socketPath,
+      path: '/v1/credentials/surrogate',
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Content-Length': Buffer.byteLength(postData),
+      },
+    };
+
+    const timeout = options.timeoutMs || AUTHD_TIMEOUT_MS;
+    let settled = false;
+    let deadlineTimer = null;
+    const cleanup = () => {
+      if (deadlineTimer) {
+        clearTimeout(deadlineTimer);
+        deadlineTimer = null;
+      }
+    };
+    const settleResolve = (val) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      resolve(val);
+    };
+    const settleReject = (err) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      reject(err);
+    };
+
+    const req = http.request(reqOptions, (res) => {
+      let responseData = '';
+      let byteCount = 0;
+
+      res.on('data', (chunk) => {
+        byteCount += Buffer.byteLength(chunk);
+        if (byteCount > MAX_AUTHD_RESPONSE_BYTES) {
+          res.destroy();
+          settleReject(new VaultKeyError('Auth daemon response exceeded size limit', 'authd_error'));
+          return;
+        }
+        responseData += chunk;
+      });
+
+      res.on('end', () => {
+        if (res.statusCode === 403 || res.statusCode === 404) {
+          settleReject(new VaultKeyError(`Vault credential missing or access denied (HTTP ${res.statusCode})`, {
+            code: 'missing',
+            statusCode: res.statusCode,
+          }));
+          return;
+        }
+
+        if (res.statusCode < 200 || res.statusCode >= 300) {
+          settleReject(new VaultKeyError(`Auth daemon returned HTTP ${res.statusCode}`, {
+            code: 'authd_error',
+            statusCode: res.statusCode,
+          }));
+          return;
+        }
+
+        let parsed;
+        try {
+          parsed = JSON.parse(responseData);
+        } catch (err) {
+          settleReject(new VaultKeyError('Failed to parse auth daemon response as JSON', {
+            code: 'authd_error',
+            cause: err,
+          }));
+          return;
+        }
+
+        const candidate = typeof parsed === 'string'
+          ? parsed
+          : (parsed?.[VAULT_ENTRY_NAME] || parsed?.surrogate || parsed?.token);
+
+        if (!candidate || typeof candidate !== 'string') {
+          settleReject(new VaultKeyError('No valid surrogate entry found in auth daemon response', 'authd_error'));
+          return;
+        }
+
+        try {
+          const validated = validateSurrogate(candidate);
+          settleResolve(validated);
+        } catch (err) {
+          settleReject(err);
+        }
+      });
+
+      res.on('error', (err) => {
+        settleReject(new VaultKeyError(`Auth daemon stream error: ${err.message}`, {
+          code: 'authd_error',
+          cause: err,
+        }));
+      });
+    });
+
+    deadlineTimer = setTimeout(() => {
+      req.destroy();
+      settleReject(new VaultKeyError(`Auth daemon request timed out (exceeded total deadline of ${timeout} ms)`, 'authd_error'));
+    }, timeout);
+    if (deadlineTimer.unref) deadlineTimer.unref();
+
+    req.setTimeout(timeout, () => {
+      req.destroy();
+      settleReject(new VaultKeyError(`Auth daemon request timed out after ${timeout} ms`, 'authd_error'));
+    });
+
+    req.on('error', (err) => {
+      if (err.code === 'ENOENT' || err.code === 'ECONNREFUSED') {
+        settleReject(new VaultKeyError(`Auth daemon socket connection failed: ${err.message}`, {
+          code: 'unavailable',
+          cause: err,
+        }));
+      } else {
+        settleReject(new VaultKeyError(`Auth daemon request failed: ${err.message}`, {
+          code: 'authd_error',
+          cause: err,
+        }));
+      }
+    });
+
+    req.write(postData);
+    req.end();
+  });
+}

package/skill/scripts/lib/openclaw-egress.mjs

@@ -0,0 +1,63 @@
+import { DEFAULT_BASE_URL } from './core.mjs';
+import { isSurrogateToken, assertSurrogateOrigin } from './muse-vault.mjs';
+
+export const OPENCLAW_SENTINEL_REGEX = /^oc-sent-v2\.[A-Za-z0-9_-]+\.end$/;
+export const ALLOWED_EGRESS_ORIGIN = new URL(DEFAULT_BASE_URL).origin;
+
+export function isOpenClawSentinel(value) {
+  return typeof value === 'string' && OPENCLAW_SENTINEL_REGEX.test(value);
+}
+
+export function isProxyEnvActive(env = process.env) {
+  const proxy = env.HTTPS_PROXY || env.https_proxy;
+  const nodeProxy = env.NODE_USE_ENV_PROXY;
+  const isNodeProxyTruthy = Boolean(
+    nodeProxy && nodeProxy !== '0' && String(nodeProxy).toLowerCase() !== 'false'
+  );
+  return Boolean(proxy && isNodeProxyTruthy);
+}
+
+export function sanitizeSensitiveValue(value) {
+  if (typeof value !== 'string') return value;
+  if (value.startsWith('hsurr:') || isOpenClawSentinel(value)) return '[REDACTED]';
+  if (value.includes('oc-sent-v2.') || value.includes('hsurr:')) {
+    return value
+      .replace(/hsurr:[^\s"'>]+/g, '[REDACTED]')
+      .replace(/oc-sent-v2\.[A-Za-z0-9_-]+\.end/g, '[REDACTED]');
+  }
+  return value;
+}
+
+export function assertOpenClawEgress(token, targetUrl, env = process.env) {
+  if (!isOpenClawSentinel(token)) return;
+
+  if (!isProxyEnvActive(env)) {
+    throw new Error(
+      'OpenClaw egress proxy is required when using OpenClaw secrets. Enable secrets.egressProxy.enabled and ensure execution runs in Gateway-hosted exec (HTTPS_PROXY and NODE_USE_ENV_PROXY=1 must be set).'
+    );
+  }
+
+  const urlObj = typeof targetUrl === 'string' ? new URL(targetUrl) : targetUrl;
+  if (urlObj.origin !== ALLOWED_EGRESS_ORIGIN) {
+    throw new Error(
+      `OpenClaw secret sentinels are restricted to ${ALLOWED_EGRESS_ORIGIN} and cannot be sent to ${urlObj.origin}. Unset XMEMO_BASE_URL or use a standard credential.`
+    );
+  }
+}
+
+export function assertEgressSecurity(authHeader, targetUrl, env = process.env) {
+  if (!authHeader || typeof authHeader !== 'string') return;
+  const match = authHeader.match(/^Bearer\s+(\S+)$/i);
+  if (!match) return;
+  const token = match[1];
+
+  if (isSurrogateToken(token)) {
+    assertSurrogateOrigin(authHeader, targetUrl);
+  } else if (isOpenClawSentinel(token)) {
+    assertOpenClawEgress(token, targetUrl, env);
+  }
+}
+
+export function configureEgressRequest(reqOptions, authHeader, targetUrl, env = process.env) {
+  assertEgressSecurity(authHeader, targetUrl, env);
+}