@encorearia/install 1.0.0

package/README.md

@@ -0,0 +1,53 @@
+# Encore Aria installer trust anchor
+
+This package installs only shell packages signed by an Ed25519 key pinned in
+`trusted-keys.json`. The shell package API may report trusted and revoked keys,
+but network data never adds a new trusted key: a package update or an explicit
+`ENCOREARIA_TRUSTED_KEYS` deployment override is required.
+
+## Bootstrap a production key
+
+Run this only in a secure release terminal after the backend migrations are
+applied. It writes the public key and fingerprint to
+`callable_shell_signing_keys`, then prints the private key once. It never
+writes the private key to a file or database.
+
+```sh
+DATABASE_URL='postgres://…' make agent-shell-keygen KEY_ID=agent-shell-YYYYMMDD
+```
+
+Immediately place these values in the backend deployment secret manager:
+
+```text
+AGENT_SHELL_SIGNING_KEY_ID=<printed key id>
+AGENT_SHELL_SIGNING_PRIVATE_KEY=<printed private key>
+```
+
+Copy only the printed public `trusted-keys.json` fragment into this package's
+`trusted-keys.json`, commit it, and ship the installer update before enabling
+the backend signer. Never paste the private value into Git, a database,
+configuration file, log, ticket, or chat.
+
+An empty `keys` array is deliberately fail-closed: installation reports that
+the trust anchor is empty instead of accepting an API-supplied key. It is the
+expected repository state until the first production release key has been
+created securely.
+
+## Rotate a key
+
+1. Generate a new key with a new `KEY_ID`.
+2. Add its public fragment alongside the old key in `trusted-keys.json` and
+   release the installer.
+3. Set the two backend signing environment variables to the new key and deploy
+   the backend. Existing shell releases remain verifiable through the old
+   pinned public key.
+4. Mark the old database key `retired` only after the rollout is complete; do
+   not reuse a key id or replace its public key.
+
+## Revoke a compromised key
+
+Use the administrator signing-key revoke endpoint. The API's revoked list
+blocks online installers immediately. Follow with an installer release that
+removes the revoked key from `trusted-keys.json`, because an offline installer
+cannot learn a revocation. Issue a fresh key and follow the rotation procedure
+before publishing new shells.

package/bin/install.mjs

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+import process from 'node:process';
+import { request, ensureDeviceLogin } from '../lib/api.mjs';
+import { atomicInstall } from '../lib/atomic-install.mjs';
+import { loadCredentials } from '../lib/credentials.mjs';
+import { detectTargets, targetRoot } from '../lib/targets.mjs';
+import { loadTrustedKeys, verifyPackage } from '../lib/verify.mjs';
+
+const args = process.argv.slice(2);
+const baseURL = String(valueAfter('--api') || process.env.ENCOREARIA_API_BASE || 'https://encorearia.com').replace(/\/$/, '');
+const targetArg = valueAfter('--target');
+const installerVersion = '1.0.0';
+
+if (args.includes('--list')) {
+  const target = (await detectTargets(targetArg ? targetArg.split(',') : []))[0];
+  let credentials = await loadCredentials();
+  if (!credentials?.access_token) {
+    const loginService = valueAfter('--service');
+    if (!loginService) fail('--list 首次使用需要同时提供 --service <id>');
+    credentials = await ensureDeviceLogin(baseURL, loginService, 'list', target);
+  }
+  let services;
+  try { services = await request(baseURL, '/api/agent/services', {}, credentials); }
+  catch (error) {
+    const loginService = valueAfter('--service');
+    if (!loginService) throw new Error(`设备授权已失效；请使用 --service <id> 重新授权。${error.message}`);
+    credentials = await ensureDeviceLogin(baseURL, loginService, 'list', target);
+    services = await request(baseURL, '/api/agent/services', {}, credentials);
+  }
+  for (const item of services) {
+    process.stdout.write(`${item.service_public_id}\t${item.title}\t${item.currency} ${(item.price_cents / 100).toFixed(2)}\t${item.active_installs} installs\n`);
+  }
+  process.exit(0);
+}
+
+const serviceID = positionalServiceID();
+if (!serviceID) fail('Usage: npx @encorearia/install <service_public_id> [--target codex,claude-code] [--api URL]');
+const pkg = await request(baseURL, '/api/callable-services/' + encodeURIComponent(serviceID) + '/shell');
+const trust = await loadTrustedKeys(baseURL);
+verifyPackage(pkg, trust, installerVersion);
+const targets = await detectTargets(targetArg ? targetArg.split(',') : []);
+const primaryTarget = targets[0];
+const credentials = await ensureDeviceLogin(baseURL, serviceID, pkg.manifest.shell_version, primaryTarget);
+for (const target of targets) {
+  const destination = await atomicInstall(targetRoot(target), serviceID, pkg.files, pkg.manifest);
+  await request(baseURL, '/api/agent/installs', { method: 'POST', body: JSON.stringify({
+    service_public_id: serviceID, shell_version: pkg.manifest.shell_version, client_target: target,
+  }) }, credentials);
+  process.stdout.write(`已安装到 ${target}: ${destination}\n`);
+}
+
+function valueAfter(flag) {
+  const index = args.indexOf(flag);
+  return index >= 0 ? args[index + 1] : '';
+}
+
+function positionalServiceID() {
+  const valuedFlags = new Set(['--api', '--target', '--service']);
+  for (let index = 0; index < args.length; index += 1) {
+    const value = args[index];
+    if (valuedFlags.has(value)) { index += 1; continue; }
+    if (!value.startsWith('--')) return value;
+  }
+  return '';
+}
+
+function fail(message) {
+  process.stderr.write(message + '\n');
+  process.exit(1);
+}

package/lib/api.mjs

@@ -0,0 +1,97 @@
+import os from 'node:os';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { credentialsDirectory, loadCredentials, saveCredentials } from './credentials.mjs';
+
+export async function request(baseURL, route, options = {}, credentials = null) {
+  return requestWithRefresh(baseURL, route, options, credentials, true);
+}
+
+async function requestWithRefresh(baseURL, route, options, credentials, canRefresh) {
+  const headers = { 'Content-Type': 'application/json', ...(options.headers || {}) };
+  if (credentials?.access_token) headers.Authorization = `Bearer ${credentials.access_token}`;
+  const response = await fetch(baseURL + route, { ...options, headers });
+  const body = await response.json().catch(() => ({}));
+  const data = body.data === undefined ? body : body.data;
+  if (response.status === 401 && canRefresh && credentials?.refresh_token && route !== '/api/agent/token/refresh') {
+    await refreshCredentials(baseURL, credentials);
+    return requestWithRefresh(baseURL, route, options, credentials, false);
+  }
+  if (!response.ok) {
+    const error = new Error(body.message || body.code || `HTTP ${response.status}`);
+    error.code = body.code;
+    error.payload = body;
+    throw error;
+  }
+  return data;
+}
+
+async function refreshCredentials(baseURL, credentials) {
+  const directory = credentialsDirectory();
+  const lock = path.join(directory, 'refresh.lock');
+  await fs.mkdir(directory, { recursive: true, mode: 0o700 });
+  for (let attempt = 0; attempt < 80; attempt += 1) {
+    try {
+      await fs.mkdir(lock);
+      try {
+        const latest = await loadCredentials();
+        if (latest?.refresh_token && latest.refresh_token !== credentials.refresh_token) {
+          Object.assign(credentials, latest);
+          return;
+        }
+        const refreshed = await requestWithRefresh(baseURL, '/api/agent/token/refresh', {
+          method: 'POST', body: JSON.stringify({ refresh_token: credentials.refresh_token }),
+        }, null, false);
+        Object.assign(credentials, refreshed);
+        await saveCredentials(credentials);
+        return;
+      } finally {
+        await fs.rm(lock, { recursive: true, force: true });
+      }
+    } catch (error) {
+      if (error.code !== 'EEXIST') throw error;
+      const stat = await fs.stat(lock).catch(() => null);
+      if (stat && Date.now() - stat.mtimeMs > 30_000) await fs.rm(lock, { recursive: true, force: true });
+      await new Promise(resolve => setTimeout(resolve, 250));
+      const latest = await loadCredentials();
+      if (latest?.refresh_token && latest.refresh_token !== credentials.refresh_token) {
+        Object.assign(credentials, latest);
+        return;
+      }
+    }
+  }
+  throw new Error('Timed out waiting for the credential refresh lock.');
+}
+
+export async function ensureDeviceLogin(baseURL, serviceID, shellVersion, clientTarget) {
+  let credentials = await loadCredentials();
+  if (credentials?.access_token) {
+    try { await request(baseURL, '/api/agent/me', {}, credentials); return credentials; } catch {}
+  }
+  const start = await request(baseURL, '/api/agent/device/start', { method: 'POST', body: JSON.stringify({
+    service_public_id: serviceID, shell_version: shellVersion, client_name: os.hostname(), client_target: clientTarget,
+  }) });
+  process.stdout.write(`请在浏览器确认设备：${start.verification_uri_complete}\n验证码：${start.user_code}\n`);
+  openBrowser(start.verification_uri_complete);
+  let interval = start.interval_seconds || 5;
+  while (Date.now() < new Date(start.expires_at).getTime()) {
+    await new Promise(resolve => setTimeout(resolve, interval * 1000));
+    const token = await request(baseURL, '/api/agent/device/token', { method: 'POST', body: JSON.stringify({ device_code: start.device_code }) });
+    if (token.status === 'slow_down') { interval = token.interval_seconds || interval + 2; continue; }
+    if (token.status === 'authorization_pending') continue;
+    if (token.status !== 'authorized') throw new Error(`Device authorization ${token.status}.`);
+    credentials = token;
+    await saveCredentials(token);
+    return token;
+  }
+  throw new Error('Device authorization timed out.');
+}
+
+function openBrowser(url) {
+  const command = process.platform === 'win32' ? ['cmd', ['/c', 'start', '', url]]
+    : process.platform === 'darwin' ? ['open', [url]] : ['xdg-open', [url]];
+  const child = spawn(command[0], command[1], { detached: true, stdio: 'ignore', windowsHide: true });
+  child.on('error', () => {});
+  child.unref();
+}

package/lib/atomic-install.mjs

@@ -0,0 +1,59 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+export async function atomicInstall(root, serviceID, files, manifest = null) {
+  if (!/^[A-Za-z0-9_-]{1,100}$/.test(serviceID)) throw new Error('Unsafe service identifier.');
+  await fs.mkdir(root, { recursive: true, mode: 0o700 });
+  const destination = path.join(root, serviceID);
+  const temporary = path.join(root, `.${serviceID}.tmp-${process.pid}-${Date.now()}`);
+  const backup = path.join(root, `.${serviceID}.backup-${process.pid}-${Date.now()}`);
+  if (manifest) await assertNoRollback(destination, manifest);
+  await fs.mkdir(temporary, { recursive: false, mode: 0o700 });
+  try {
+    for (const [relative, content] of Object.entries(files)) {
+      const target = path.resolve(temporary, relative);
+      if (!target.startsWith(path.resolve(temporary) + path.sep)) throw new Error(`Unsafe path: ${relative}`);
+      await fs.mkdir(path.dirname(target), { recursive: true, mode: 0o700 });
+      await fs.writeFile(target, content, { mode: relative.endsWith('.mjs') ? 0o700 : 0o600 });
+    }
+    if (manifest) {
+      await fs.writeFile(path.join(temporary, '.encorearia-release.json'), JSON.stringify({
+        service_public_id: manifest.service_public_id,
+        shell_version: manifest.shell_version,
+        signing_key_id: manifest.signing_key_id,
+        issued_at: manifest.issued_at,
+      }, null, 2), { mode: 0o600 });
+    }
+    let hadPrevious = false;
+    try { await fs.rename(destination, backup); hadPrevious = true; } catch (error) { if (error.code !== 'ENOENT') throw error; }
+    try {
+      await fs.rename(temporary, destination);
+    } catch (error) {
+      if (hadPrevious) await fs.rename(backup, destination).catch(() => {});
+      throw error;
+    }
+    if (hadPrevious) await fs.rm(backup, { recursive: true, force: true });
+    return destination;
+  } catch (error) {
+    await fs.rm(temporary, { recursive: true, force: true });
+    throw error;
+  }
+}
+
+async function assertNoRollback(destination, manifest) {
+  let current;
+  try { current = JSON.parse(await fs.readFile(path.join(destination, '.encorearia-release.json'), 'utf8')); }
+  catch { return; }
+  if (current.service_public_id !== manifest.service_public_id) throw new Error('Installed service identity does not match the signed package.');
+  const oldSequence = releaseSequence(current.shell_version);
+  const newSequence = releaseSequence(manifest.shell_version);
+  const olderSequence = newSequence[0] < oldSequence[0] || (newSequence[0] === oldSequence[0] && newSequence[1] < oldSequence[1]);
+  const olderIssue = newSequence[0] === oldSequence[0] && newSequence[1] === oldSequence[1]
+    && Date.parse(manifest.issued_at) < Date.parse(current.issued_at);
+  if (olderSequence || olderIssue) throw new Error(`Shell rollback rejected: ${manifest.shell_version} is older than ${current.shell_version}.`);
+}
+
+function releaseSequence(value) {
+  const parts = String(value || '').split('.');
+  return [Number.parseInt(parts[0], 10) || 0, Number.parseInt(parts[1], 10) || 0];
+}

package/lib/credentials.mjs

@@ -0,0 +1,33 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+const service = 'encorearia-agent';
+const account = 'default';
+export const credentialsDirectory = () => process.env.ENCOREARIA_CONFIG_DIR || path.join(os.homedir(), '.encorearia');
+const file = () => path.join(credentialsDirectory(), 'credentials.json');
+
+async function keytar() {
+  try { return (await import('keytar')).default; } catch { return null; }
+}
+
+export async function loadCredentials() {
+  const keychain = await keytar();
+  if (keychain) {
+    const raw = await keychain.getPassword(service, account);
+    if (raw) return JSON.parse(raw);
+  }
+  try { return JSON.parse(await fs.readFile(file(), 'utf8')); } catch { return null; }
+}
+
+export async function saveCredentials(value) {
+  const keychain = await keytar();
+  if (keychain) {
+    await keychain.setPassword(service, account, JSON.stringify(value));
+    return;
+  }
+  const dir = path.dirname(file());
+  await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+  await fs.writeFile(file(), JSON.stringify(value, null, 2), { mode: 0o600 });
+  if (process.platform !== 'win32') await fs.chmod(file(), 0o600);
+}

package/lib/targets.mjs

@@ -0,0 +1,28 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+export const TARGETS = {
+  codex: () => process.env.CODEX_SKILLS_DIR || path.join(os.homedir(), '.codex', 'skills'),
+  'claude-code': () => process.env.CLAUDE_SKILLS_DIR || path.join(os.homedir(), '.claude', 'skills'),
+};
+
+export async function detectTargets(requested) {
+  if (requested && requested.length) return [...new Set(requested.map(normalizeTarget))];
+  const found = [];
+  for (const [name, root] of Object.entries(TARGETS)) {
+    try { await fs.access(path.dirname(root())); found.push(name); } catch {}
+  }
+  return found.length ? found : ['codex'];
+}
+
+export function targetRoot(target) {
+  const normalized = normalizeTarget(target);
+  return TARGETS[normalized]();
+}
+
+function normalizeTarget(value) {
+  const target = String(value || '').toLowerCase();
+  if (!TARGETS[target]) throw new Error(`Unsupported Agent target: ${value}`);
+  return target;
+}

package/lib/verify.mjs

@@ -0,0 +1,78 @@
+import { createHash, createPublicKey, verify as verifySignature } from 'node:crypto';
+import fs from 'node:fs/promises';
+
+const safePath = /^(?![./])(?:[A-Za-z0-9._-]+\/)*[A-Za-z0-9._-]+$/;
+
+export function sha256(content) {
+  return createHash('sha256').update(content).digest('hex');
+}
+
+export function compareVersions(left, right) {
+  const a = String(left).split('.').map(value => Number.parseInt(value, 10) || 0);
+  const b = String(right).split('.').map(value => Number.parseInt(value, 10) || 0);
+  for (let i = 0; i < Math.max(a.length, b.length); i += 1) {
+    if ((a[i] || 0) !== (b[i] || 0)) return (a[i] || 0) - (b[i] || 0);
+  }
+  return 0;
+}
+
+export async function loadTrustedKeys(baseURL) {
+  const bundled = JSON.parse(await fs.readFile(new URL('../trusted-keys.json', import.meta.url), 'utf8'));
+  const injected = process.env.ENCOREARIA_TRUSTED_KEYS ? JSON.parse(process.env.ENCOREARIA_TRUSTED_KEYS) : { keys: [] };
+  const trusted = new Map([...(bundled.keys || []), ...(injected.keys || [])]
+    .filter(item => item && typeof item.key_id === 'string' && typeof item.public_key_base64 === 'string')
+    .map(item => [item.key_id, item.public_key_base64]));
+  let revoked = new Set();
+  try {
+    const response = await fetch(baseURL + '/api/agent/signing-keys');
+    const body = await response.json();
+    const data = body.data || body;
+    revoked = new Set((data.revoked || []).map(item => item.key_id));
+  } catch {
+    // Network failure must not expand trust. Bundled/injected trust remains,
+    // while a package explicitly marked revoked is still rejected below.
+  }
+  return { trusted, revoked };
+}
+
+export function verifyPackage(pkg, trust, installerVersion) {
+  if (!pkg || !pkg.manifest || !pkg.files) throw new Error('Invalid shell package response.');
+  const manifest = pkg.manifest;
+  if (!trust || !trust.trusted || trust.trusted.size === 0) {
+    throw new Error('Installer trust anchor is empty. Install an official installer release that includes this signing key, or ask the platform operator to publish the trusted-key update.');
+  }
+  if (!['active', 'retired'].includes(pkg.key_status)) throw new Error(`Signing key is ${pkg.key_status || 'untrusted'}.`);
+  if (trust.revoked.has(manifest.signing_key_id)) throw new Error('Signing key has been revoked.');
+  const trustedPublicKey = trust.trusted.get(manifest.signing_key_id);
+  if (!trustedPublicKey) {
+    throw new Error(`Signing key ${manifest.signing_key_id || '(missing)'} is not pinned by this installer. Update to an official installer release that trusts this key.`);
+  }
+  if (trustedPublicKey !== pkg.public_key_base64) {
+    throw new Error('Pinned signing key does not match the package public key. Stop installation and obtain an official installer update.');
+  }
+  if (compareVersions(installerVersion, manifest.min_installer_version) < 0) {
+    throw new Error(`Installer ${manifest.min_installer_version}+ is required.`);
+  }
+  const canonical = Buffer.from(pkg.manifest_canonical_base64 || '', 'base64');
+  if (!canonical.length) throw new Error('Missing canonical signed manifest.');
+  const parsedCanonical = JSON.parse(canonical.toString('utf8'));
+  if (JSON.stringify(parsedCanonical) !== JSON.stringify(manifest)) throw new Error('Manifest canonical payload does not match response.');
+  const rawPublic = Buffer.from(trustedPublicKey, 'base64');
+  if (rawPublic.length !== 32) throw new Error('Pinned Ed25519 public key has invalid length.');
+  const spkiPrefix = Buffer.from('302a300506032b6570032100', 'hex');
+  const publicKey = createPublicKey({ key: Buffer.concat([spkiPrefix, rawPublic]), format: 'der', type: 'spki' });
+  if (!verifySignature(null, canonical, publicKey, Buffer.from(pkg.signature_base64, 'base64'))) throw new Error('Shell signature verification failed.');
+  const listed = new Map();
+  for (const file of manifest.files || []) {
+    if (!safePath.test(file.path) || file.path.includes('..')) throw new Error(`Unsafe shell path: ${file.path}`);
+    if (listed.has(file.path)) throw new Error(`Duplicate shell path: ${file.path}`);
+    listed.set(file.path, file.sha256);
+  }
+  const actual = Object.keys(pkg.files).sort();
+  const expected = [...listed.keys()].sort();
+  if (JSON.stringify(actual) !== JSON.stringify(expected)) throw new Error('Shell file list does not exactly match the signed manifest.');
+  for (const [file, expectedHash] of listed) {
+    if (sha256(pkg.files[file]) !== expectedHash) throw new Error(`Shell file hash mismatch: ${file}`);
+  }
+  return pkg;
+}

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@encorearia/install",
+  "version": "1.0.0",
+  "description": "Verify and install signed Encore Aria call-shell skills for Codex and Claude Code.",
+  "type": "module",
+  "bin": {
+    "encorearia-install": "./bin/install.mjs"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "trusted-keys.json"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "license": "UNLICENSED"
+}

package/trusted-keys.json

@@ -0,0 +1,10 @@
+{
+  "schema_version": 1,
+  "keys": [
+    {
+      "key_id": "agent-shell-20260718",
+      "public_key_base64": "81nWHPJZePLAvdN5NbKhYWVHc1IxpsGqTrfZ1lYCfCE=",
+      "fingerprint_sha256": "7a8acc34839a47f49689e708c5dcc19832678cfb2b003eb041385cbe48802ca0"
+    }
+  ]
+}