@gregiteen/ssss-cli 0.13.1 → 0.14.1

package/scripts/cmd-serve.mjs

@@ -0,0 +1,155 @@
+/**
+ * ssss serve — reference HTTP server for the SSSS Operation Contract (spec §6.8).
+ * Dependency-free implementation using Node's built-in http module.
+ */
+import http from 'node:http';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createEngine } from '../src/engine.mjs';
+import { statusForResponse } from '../src/http.mjs';
+import { parseArgs, wantsHelp } from './lib/cli.mjs';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const VERSION = (() => {
+  try { return fs.readFileSync(path.resolve(HERE, '..', 'VERSION'), 'utf8').trim(); }
+  catch { return '0.0.0'; }
+})();
+
+export function createServer(options = {}) {
+  const vaultRoot = path.resolve(options.vault || '.');
+  const engine = options.engine || createEngine({
+    registryDir: options.registryDir,
+    extensionFile: options.extensionFile,
+  });
+
+  let expectedToken = null;
+  if (options.token) {
+    expectedToken = options.token.trim();
+  } else if (options.tokenFile) {
+    expectedToken = fs.readFileSync(path.resolve(options.tokenFile), 'utf8').trim();
+  }
+
+  const server = http.createServer(async (req, res) => {
+    res.setHeader('Content-Type', 'application/json');
+
+    if (req.method === 'GET' && (req.url === '/health' || req.url === '/healthz')) {
+      res.writeHead(200);
+      res.end(JSON.stringify({ ok: true, version: VERSION }));
+      return;
+    }
+
+    const hostHeader = req.headers.host || 'localhost';
+    const parsedUrl = new URL(req.url, `http://${hostHeader}`);
+
+    if (req.method !== 'POST' || (parsedUrl.pathname !== '/v1/operations' && parsedUrl.pathname !== '/')) {
+      res.writeHead(404);
+      res.end(JSON.stringify({
+        success: false,
+        error: { code: 'not_found', message: `Route '${req.method} ${parsedUrl.pathname}' not found.` },
+      }));
+      return;
+    }
+
+    if (expectedToken) {
+      const authHeader = req.headers.authorization || '';
+      const match = authHeader.match(/^Bearer\s+(.+)$/i);
+      const token = match ? match[1].trim() : null;
+      if (!token || token !== expectedToken) {
+        res.writeHead(401);
+        res.end(JSON.stringify({
+          success: false,
+          error: { code: 'unauthorized', message: 'Missing or invalid bearer token.' },
+        }));
+        return;
+      }
+    }
+
+    const chunks = [];
+    req.on('data', (chunk) => chunks.push(chunk));
+    req.on('end', async () => {
+      let payload;
+      try {
+        const text = Buffer.concat(chunks).toString('utf8');
+        payload = JSON.parse(text);
+      } catch (err) {
+        res.writeHead(400);
+        res.end(JSON.stringify({
+          success: false,
+          error: { code: 'invalid_request', message: `Malformed JSON: ${err.message}` },
+        }));
+        return;
+      }
+
+      const envelope = payload?.envelope || payload;
+      const callOptions = {};
+      if (payload?.principal) callOptions.principal = payload.principal;
+
+      try {
+        const response = await engine.processOperation(envelope, vaultRoot, callOptions);
+        const status = statusForResponse(response);
+        res.writeHead(status);
+        res.end(JSON.stringify(response));
+      } catch (err) {
+        res.writeHead(500);
+        res.end(JSON.stringify({
+          success: false,
+          error: { code: 'internal_error', message: err.message },
+        }));
+      }
+    });
+
+    req.on('error', (err) => {
+      if (!res.headersSent) {
+        res.writeHead(500);
+        res.end(JSON.stringify({ success: false, error: { code: 'internal_error', message: err.message } }));
+      }
+    });
+  });
+
+  return server;
+}
+
+export async function run(argv) {
+  if (wantsHelp(argv)) {
+    console.log(`Usage: ssss serve [options]
+
+Start a reference HTTP server exposing the SSSS Operation Contract (POST /v1/operations).
+
+Options:
+  --vault <dir>       Path to vault directory (default: '.')
+  --port <num>        Port to listen on (default: 8443, 0 for dynamic)
+  --host <ip>         Host address to bind to (default: 127.0.0.1)
+  --token <pat>       Optional bearer token required for requests
+  --token-file <file> Optional path to bearer token file
+  --registry <dir>    Path to registry directory
+  --extension <file>  Path to extension registry file
+  --quiet             Suppress listening message
+  --help, -h          Show help`);
+    return;
+  }
+
+  const { flags } = parseArgs(argv, { booleans: ['quiet'] });
+  const vault = flags.vault || '.';
+  const port = flags.port != null ? parseInt(flags.port, 10) : 8443;
+  const host = flags.host || '127.0.0.1';
+  const token = flags.token;
+  const tokenFile = flags['token-file'];
+  const registryDir = flags.registry;
+  const extensionFile = flags.extension;
+
+  const server = createServer({ vault, token, tokenFile, registryDir, extensionFile });
+  server.listen(port, host, () => {
+    const addr = server.address();
+    const actualPort = typeof addr === 'object' ? addr.port : port;
+    if (!flags.quiet) {
+      console.log(`SSSS reference server listening on http://${host}:${actualPort} (vault: ${path.resolve(vault)})`);
+    }
+  });
+
+  const close = () => {
+    server.close(() => process.exit(0));
+  };
+  process.on('SIGINT', close);
+  process.on('SIGTERM', close);
+}

package/scripts/cmd-upgrade.mjs

@@ -0,0 +1,110 @@
+/**
+ * `ssss upgrade` — move an installed capability bundle to a new version via
+ * structural-only patch envelopes (spec §17.4). Refuses any tenant_private
+ * modification.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { exportBundle, upgradeBundle, importBundle } from '../src/bundle.mjs';
+import { createEngine } from '../src/engine.mjs';
+import { parseArgs, usage, die, wantsHelp } from './lib/cli.mjs';
+
+const HELP = usage({
+  summary: 'Upgrade an installed bundle to a new version via structural-only patches (§17.4).',
+  usage: 'ssss upgrade <bundle.ucw.json> --vault <dir> [options]',
+  options: [
+    ['--vault <dir>', 'Target vault directory. Required.'],
+    ['--from <file>', 'Baseline bundle or plan (if omitted, exported from vault).'],
+    ['--workspace <id>', 'Target workspace id (default: ws-upgrade).'],
+    ['--prefix <path>', 'Path prefix for the bundle within the vault.'],
+    ['--dry-run', 'Validate every patch envelope without committing.'],
+    ['--json', 'Emit machine-readable JSON upgrade summary.'],
+    ['--registry <dir>', 'Registry directory (default: core registry).'],
+  ],
+  examples: [
+    'ssss upgrade festival-v2.ucw.json --vault ./tenant',
+    'ssss upgrade festival-v2.ucw.json --vault ./tenant --dry-run',
+    'ssss upgrade festival-v2.ucw.json --vault ./tenant --from festival-v1.ucw.json',
+  ],
+  seeAlso: ['ssss import', 'ssss provision', 'ssss export'],
+});
+
+export async function run(argv) {
+  if (wantsHelp(argv)) { console.log(HELP); return; }
+  const { positionals, flags } = parseArgs(argv, { booleans: ['dry-run', 'json'] });
+  const file = positionals[0];
+  if (!file) die('upgrade needs a new bundle file.\n\n' + HELP);
+  if (!fs.existsSync(file)) die(`no such file: ${file}`);
+  if (!flags.vault) die('upgrade needs --vault <dir>.\n\n' + HELP);
+
+  const vault = path.resolve(flags.vault);
+  if (!fs.existsSync(vault)) die(`no such vault directory: ${vault}`);
+
+  let nextBundle;
+  try { nextBundle = JSON.parse(fs.readFileSync(file, 'utf8')); }
+  catch (err) { die(`bundle is not valid JSON: ${err.message}`); }
+
+  let installedBundle;
+  if (flags.from) {
+    if (!fs.existsSync(flags.from)) die(`no such baseline file: ${flags.from}`);
+    try { installedBundle = JSON.parse(fs.readFileSync(flags.from, 'utf8')); }
+    catch (err) { die(`baseline file is not valid JSON: ${err.message}`); }
+  } else {
+    try {
+      installedBundle = exportBundle(vault, {
+        profile: 'backup',
+        registryDir: flags.registry,
+      });
+    } catch (err) {
+      die(`failed to inspect current vault state: ${err.message}`);
+    }
+  }
+
+  const upgrade = upgradeBundle(installedBundle, nextBundle, {
+    workspaceId: flags.workspace || 'ws-upgrade',
+    pathPrefix: flags.prefix || '',
+    dryRun: !!flags['dry-run'],
+    registryDir: flags.registry,
+  });
+
+  if (!upgrade.ok) {
+    for (const e of upgrade.errors) console.error(`✗ upgrade error: ${e}`);
+    process.exit(1);
+  }
+
+  const declared = nextBundle?.manifest?.required_extensions;
+  const registryNames = Array.isArray(declared) && declared.length ? declared : null;
+  const engine = createEngine({ registryDir: flags.registry, ...(registryNames ? { registryNames } : {}) });
+
+  const result = await importBundle(upgrade.plan, vault, engine);
+  const failed = result.results.filter((r) => !r.success);
+
+  if (flags.json) {
+    const summary = {
+      ok: result.ok,
+      from_version: upgrade.fromVersion,
+      to_version: upgrade.toVersion,
+      migration: upgrade.migration,
+      patches_count: upgrade.patchesCount,
+      operations_count: upgrade.operationsCount,
+      committed: result.committed,
+      would_commit: result.wouldCommit,
+      failed_count: failed.length,
+      dry_run: !!flags['dry-run'],
+    };
+    console.log(JSON.stringify(summary, null, 2));
+    if (!result.ok) process.exit(1);
+    return;
+  }
+
+  if (flags['dry-run']) {
+    console.log(`${result.ok ? '✓' : '✗'} upgrade dry-run ${upgrade.fromVersion} → ${upgrade.toVersion}: ${result.wouldCommit || 0} would apply, ${upgrade.plan.length - (result.wouldCommit || 0)} unchanged, ${failed.length} failed → ${vault}`);
+  } else {
+    console.log(`${result.ok ? '✓' : '✗'} upgrade ${upgrade.fromVersion} → ${upgrade.toVersion}: ${result.committed} committed, ${upgrade.plan.length - result.committed} unchanged, ${failed.length} failed → ${vault}`);
+  }
+
+  if (failed.length) {
+    for (const r of failed) console.error(`  ✗ ${r.path}: ${(r.validation?.errors || []).join('; ')}`);
+    process.exit(1);
+  }
+}

package/scripts/conformance-09.mjs

@@ -303,6 +303,12 @@ async function checkCapabilities(root, check) {
     capabilityCovers('ssss:assistant:*', 'ssss:assistant:create') && !capabilityCovers('ssss:assistant:*', 'ssss:rule:create'));
   check('capabilities: a namespace wildcard covers its namespace only',
     capabilityCovers('ssss:*', 'ssss:rule:patch') && !capabilityCovers('acme:*', 'ssss:rule:patch') && !capabilityCovers('ss:*', 'ssss:rule:patch'));
+  check('capabilities: path selector @<glob> grants matching path',
+    capabilityCovers('ssss:rule:*@rules/marketing/**', 'ssss:rule:create', 'rules/marketing/promo.md')
+    && !capabilityCovers('ssss:rule:*@rules/marketing/**', 'ssss:rule:create', 'rules/finance/audit.md'));
+  check('capabilities: path selector @<glob> with *:* grants only matching paths',
+    capabilityCovers('*:*@capabilities/messaging/**', 'ssss:rule:create', 'capabilities/messaging/rules.md')
+    && !capabilityCovers('*:*@capabilities/messaging/**', 'ssss:rule:create', 'capabilities/other/rules.md'));
 
   const engine = createEngine();
   const vault = path.join(root, 'legacy-roles');
@@ -313,11 +319,123 @@ async function checkCapabilities(root, check) {
   await write('lr-1', 'roles/editor/ROLE.md', role('editor', ['"write:rule"']), 'system');
   await write('lr-2', 'roles/owner/ROLE.md', role('owner', ['"write:*"']), 'system');
   await write('lr-3', 'roles/typed/ROLE.md', role('typed', ['"*:assistant"']), 'system');
+  await write('lr-rw', 'roles/rolewriter/ROLE.md', role('rolewriter', ['"write:role"']), 'system');
   check('legacy roles: write:<type> grants writes to that type', (await write('lr-4', 'rules/a.md', doc('rule', 'A'), 'editor')).success);
   check('legacy roles: write:<type> denies other types', (await write('lr-5', 'assistants/b/ASSISTANT.md', doc('assistant', 'B'), 'editor')).error?.code === 'forbidden');
   check('legacy roles: *:<type> grants writes to that type', (await write('lr-6', 'assistants/c/ASSISTANT.md', doc('assistant', 'C'), 'typed')).success);
   check('legacy roles: write:* grants writes to every type', (await write('lr-7', 'workflows/d/WORKFLOW.md', doc('workflow', 'D'), 'owner')).success);
   check('legacy roles: an unknown role is forbidden, not promoted', (await write('lr-8', 'rules/e.md', doc('rule', 'E'), 'ghost')).error?.code === 'forbidden');
+  check('legacy roles: write:role grants writes to security_role (alias unification)',
+    (await write('lr-aliased-1', 'roles/sec/ROLE.md', role('sec', ['"write:rule"']), 'rolewriter')).success);
+
+  const roleDoc = (name, permissions) => `---\ntype: role\ntitle: "${name}"\ndescription: "Canonical role."\ntimestamp: "2026-09-24T00:00:00Z"\nname: "${name}"\npermissions: [${permissions.join(', ')}]\n---\n`;
+  const replaceRes = await write('lr-aliased-replace', 'roles/sec/ROLE.md', roleDoc('sec', ['"write:rule"', '"write:task"']), 'rolewriter');
+  check('kernel mutation: replace security_role with role succeeds (alias unification)', replaceRes.success);
+
+  const illegalTypeChange = await write('lr-illegal-type', 'roles/sec/ROLE.md', doc('assistant', 'SecAsst'), 'owner');
+  check('kernel mutation: replace role with assistant fails closed',
+    illegalTypeChange.error?.code === 'validation_failed' &&
+    illegalTypeChange.error?.message?.includes('Operation may not change an existing document type.'));
+
+  const convDoc = `---\ntype: conversation\ntitle: "Thread"\ndescription: "Chat transcript."\ntimestamp: "2026-09-24T00:00:00Z"\nthread_id: "t-1"\n---\n\nInitial message.\n`;
+  await engine.processOperation({ type: 'operation', workspace_id: 'w', idempotency_key: 'conv-init', path: 'threads/t1/CONVERSATION.md', content: convDoc, actor: { role: 'system' } }, vault);
+  const patchRes = await engine.processOperation({
+    type: 'patch', workspace_id: 'w', idempotency_key: 'conv-patch-alias', path: 'threads/t1/CONVERSATION.md',
+    patches: { type: 'thread', __body__: 'New reply.' },
+    actor: { role: 'system' },
+  }, vault);
+  check('kernel mutation: patch conversation with type thread succeeds (alias unification)', patchRes.success);
+
+  const regTypes = engine._registry.types;
+  check('core registry: release, model, page, conflict declare deprecated: true',
+    regTypes.get('release')?.deprecated === true &&
+    regTypes.get('model')?.deprecated === true &&
+    regTypes.get('page')?.deprecated === true &&
+    regTypes.get('conflict')?.deprecated === true);
+
+  let selfAliasRejected = false;
+  try {
+    composeRegistries({
+      core: {
+        registry: 'ssss',
+        version: '0.14.0',
+        universal_fields: ['type'],
+        portability: { classes: { structural: {} } },
+        document_primitives: {
+          rule: { family: 'core', append_only: false, portability: 'structural', required_fields: ['type'], aliases: ['rule'] },
+        },
+      },
+      extensions: [],
+    });
+  } catch (err) {
+    selfAliasRejected = err.message.includes('cannot alias itself');
+  }
+  check('core registry: self-alias on a primitive is rejected', selfAliasRejected);
+
+  let asymmetricAliasRejected = false;
+  try {
+    composeRegistries({
+      core: {
+        registry: 'ssss',
+        version: '0.14.0',
+        universal_fields: ['type'],
+        portability: { classes: { structural: {} } },
+        document_primitives: {
+          rule: { family: 'core', append_only: false, portability: 'structural', required_fields: ['type'], aliases: ['assistant'] },
+          assistant: { family: 'core', append_only: false, portability: 'structural', required_fields: ['type'] },
+        },
+      },
+      extensions: [],
+    });
+  } catch (err) {
+    asymmetricAliasRejected = err.message.includes('collides with existing primitive');
+  }
+  check('core registry: non-mutual core alias collision is rejected', asymmetricAliasRejected);
+
+  const floorAuthorizer = createCapabilityAuthorizer({
+    policyFloors: { 'ssss:role': { create: ['governance:elevated'] } },
+  });
+  const secRoleDef = regTypes.get('security_role');
+  const floorBlocked = await floorAuthorizer({
+    principal: {
+      id: 'u1',
+      kind: 'agent',
+      workspaceIds: ['w'],
+      capabilities: ['ssss:security_role:create'],
+      authentication: { provider: 'token', assurance: 'verified' },
+    },
+    workspaceId: 'w',
+    definition: secRoleDef,
+    action: 'create',
+  });
+  const floorAllowed = await floorAuthorizer({
+    principal: {
+      id: 'u1',
+      kind: 'agent',
+      workspaceIds: ['w'],
+      capabilities: ['ssss:security_role:create', 'governance:elevated'],
+      authentication: { provider: 'token', assurance: 'verified' },
+    },
+    workspaceId: 'w',
+    definition: secRoleDef,
+    action: 'create',
+  });
+  check('authorization: policyFloors on ssss:role apply when mutating security_role alias',
+    floorBlocked.allowed === false && floorBlocked.missing?.includes('governance:elevated') && floorAllowed.allowed === true);
+
+  const pathPrincipal = {
+    id: 'scoped-user',
+    kind: 'agent',
+    workspaceIds: ['w'],
+    capabilities: ['ssss:rule:*@rules/marketing/**'],
+    authentication: { provider: 'token', assurance: 'verified' },
+  };
+  const writeScoped = (key, pathName, content) => engine.processOperation(
+    { type: 'operation', workspace_id: 'w', idempotency_key: key, path: pathName, content }, vault, { principal: pathPrincipal });
+  check('kernel authorization: path-scoped grant allows matching path (G5)',
+    (await writeScoped('ps-1', 'rules/marketing/banner.md', doc('rule', 'Banner'))).success);
+  check('kernel authorization: path-scoped grant forbids non-matching path (G5)',
+    (await writeScoped('ps-2', 'rules/engineering/lint.md', doc('rule', 'Lint'))).error?.code === 'forbidden');
 }
 
 // Resource hooks (spec §6.3): every prepare ends in exactly one finalize or
@@ -412,6 +530,27 @@ async function checkResourceLifecycle(check) {
   check('references: a reference to a disallowed type is rejected', wrongType.error?.code === 'validation_failed');
   check('references: a patch cannot repoint a reference at a missing document', repointed.error?.code === 'validation_failed');
 
+  const withRoleRefs = createValidator({ extensions: [{
+    registry: 'acme', extends: 'core',
+    document_primitives: {
+      grant_doc: {
+        family: 'extension', append_only: false, portability: 'structural', required_fields: ['type', 'name', 'role_ref'],
+        references: { role_ref: { allowed_types: ['role'] } },
+      },
+      deny_role_doc: {
+        family: 'extension', append_only: false, portability: 'structural', required_fields: ['type', 'name', 'target_ref'],
+        references: { target_ref: { disallowed_types: ['role'] } },
+      },
+    },
+  }] });
+  const roleRefKernel = createKernel({ vfs: new MemoryVfs(), eventStore: new MemoryEventStore(), validator: withRoleRefs });
+  const writeRef = (key, pathName, content) => roleRefKernel.execute({ type: 'operation', workspace_id: 'w', idempotency_key: key, path: pathName, content }, { principal });
+  await writeRef('rr-1', 'roles/admin.md', `---\ntype: security_role\ntitle: "Admin"\ndescription: "D"\ntimestamp: "2026-09-24T00:00:00Z"\nrole_id: "admin"\nname: "Admin"\npermissions: ["*:*"]\n---\n`);
+  const allowedViaAlias = await writeRef('rr-2', 'grants/g1.md', `---\ntype: grant_doc\ntitle: "G"\ndescription: "D"\ntimestamp: "2026-09-24T00:00:00Z"\nname: "G"\nrole_ref: "roles/admin.md"\n---\n`);
+  const disallowedViaAlias = await writeRef('rr-3', 'denies/d1.md', `---\ntype: deny_role_doc\ntitle: "D"\ndescription: "D"\ntimestamp: "2026-09-24T00:00:00Z"\nname: "D"\ntarget_ref: "roles/admin.md"\n---\n`);
+  check('references: allowed_types role accepts aliased security_role target', allowedViaAlias.success);
+  check('references: disallowed_types role rejects aliased security_role target', disallowedViaAlias.error?.code === 'validation_failed');
+
   // Every failure carries a symbolic code that maps to the §6.5 status table.
   const plain = createKernel({ vfs: new MemoryVfs(), eventStore: new MemoryEventStore(), leaseStore: new MemoryLeaseStore() });
   const missing = await plain.execute({ type: 'patch', workspace_id: 'w', idempotency_key: 'ec-404', path: 'rules/none.md', patches: { name: 'x' } }, { principal });