@gregiteen/ssss-cli 0.8.0 → 0.9.1

package/src/leases.mjs

@@ -0,0 +1,173 @@
+/** Standard lease store semantics. */
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+function validateLeaseInput(value) {
+  for (const field of ['workspace_id', 'target', 'principal_id', 'operation_id']) {
+    if (typeof value?.[field] !== 'string' || !value[field]) throw new Error(`Lease ${field} is required.`);
+  }
+}
+
+export class MemoryLeaseStore {
+  #leases = new Map();
+  constructor({ clock = () => Date.now() } = {}) { this.clock = clock; }
+  #key(workspaceId, target) { return JSON.stringify([workspaceId, target]); }
+  async acquire(input, ttlMs = 30_000) {
+    validateLeaseInput(input);
+    const key = this.#key(input.workspace_id, input.target);
+    const existing = this.#leases.get(key);
+    if (existing && existing.expires_at > this.clock()) throw new Error('Lease conflict.');
+    const lease = { ...input, lease_id: input.lease_id || crypto.randomUUID(), issued_at: this.clock(), expires_at: this.clock() + ttlMs };
+    this.#leases.set(key, lease);
+    return { ...lease };
+  }
+  async verify(input) {
+    const lease = this.#leases.get(this.#key(input.workspace_id, input.target));
+    if (!lease) return { valid: false, reason: 'Required lease is missing.' };
+    if (lease.expires_at <= this.clock()) return { valid: false, reason: 'Lease has expired.' };
+    for (const field of ['lease_id', 'principal_id', 'operation_id']) {
+      if (lease[field] !== input[field]) return { valid: false, reason: `Lease ${field} mismatch.` };
+    }
+    return { valid: true, lease: { ...lease } };
+  }
+  async renew(input, ttlMs = 30_000) {
+    const verified = await this.verify(input);
+    if (!verified.valid) throw new Error(verified.reason);
+    verified.lease.expires_at = this.clock() + ttlMs;
+    this.#leases.set(this.#key(input.workspace_id, input.target), verified.lease);
+    return { ...verified.lease };
+  }
+  async release(input) {
+    const verified = await this.verify(input);
+    if (!verified.valid) throw new Error(verified.reason);
+    this.#leases.delete(this.#key(input.workspace_id, input.target));
+    return { released: true, lease_id: input.lease_id };
+  }
+}
+
+export function leaseStatePath(root, workspaceId, target) {
+  const hash = crypto.createHash('sha256').update(`${workspaceId}\0${target}`).digest('hex');
+  return path.join(root, `${hash}.lease.json`);
+}
+
+export class FileLeaseStore {
+  constructor(root, options = {}) {
+    fs.mkdirSync(root, { recursive: true });
+    this.root = fs.realpathSync(root);
+    this.clock = options.clock || (() => Date.now());
+  }
+  #file(workspaceId, target) {
+    return leaseStatePath(this.root, workspaceId, target);
+  }
+  #load(workspaceId, target) {
+    const file = this.#file(workspaceId, target);
+    if (!fs.existsSync(file)) return null;
+    const stat = fs.lstatSync(file);
+    if (stat.isSymbolicLink() || !stat.isFile()) throw new Error('Lease state is unreadable.');
+    try { return JSON.parse(fs.readFileSync(file, 'utf8')); }
+    catch { throw new Error('Lease state is unreadable.'); }
+  }
+  #write(lease) {
+    const file = this.#file(lease.workspace_id, lease.target);
+    const temp = `${file}.${crypto.randomUUID()}.tmp`;
+    try {
+      fs.writeFileSync(temp, `${JSON.stringify(lease)}\n`, { flag: 'wx', mode: 0o600 });
+      fs.renameSync(temp, file);
+    } finally { fs.rmSync(temp, { force: true }); }
+  }
+  async acquire(input, ttlMs = 30_000) {
+    validateLeaseInput(input);
+    const existing = this.#load(input.workspace_id, input.target);
+    if (existing && existing.expires_at > this.clock()) throw new Error('Lease conflict.');
+    const lease = { ...input, lease_id: input.lease_id || crypto.randomUUID(), issued_at: this.clock(), expires_at: this.clock() + ttlMs };
+    this.#write(lease);
+    return { ...lease };
+  }
+  async verify(input) {
+    const lease = this.#load(input.workspace_id, input.target);
+    if (!lease) return { valid: false, reason: 'Required lease is missing.' };
+    if (lease.expires_at <= this.clock()) return { valid: false, reason: 'Lease has expired.' };
+    for (const field of ['lease_id', 'principal_id', 'operation_id']) {
+      if (lease[field] !== input[field]) return { valid: false, reason: `Lease ${field} mismatch.` };
+    }
+    return { valid: true, lease };
+  }
+  async renew(input, ttlMs = 30_000) {
+    const verified = await this.verify(input);
+    if (!verified.valid) throw new Error(verified.reason);
+    verified.lease.expires_at = this.clock() + ttlMs;
+    this.#write(verified.lease);
+    return verified.lease;
+  }
+  async release(input) {
+    const verified = await this.verify(input);
+    if (!verified.valid) throw new Error(verified.reason);
+    fs.rmSync(this.#file(input.workspace_id, input.target), { force: true });
+    return { released: true, lease_id: input.lease_id };
+  }
+}
+
+export async function runLeaseContract(store, { clock } = {}) {
+  const input = {
+    workspace_id: `ws-${crypto.randomUUID()}`,
+    target: `rules/${crypto.randomUUID()}.md`,
+    principal_id: 'principal',
+    operation_id: 'operation',
+  };
+  const checks = [];
+  const record = (name, passed) => checks.push({ name, passed: !!passed });
+  const acquired = await store.acquire(input, 10_000);
+  record('acquire returns bound lease', acquired.lease_id && acquired.principal_id === input.principal_id);
+  record('matching lease verifies', (await store.verify({ ...input, lease_id: acquired.lease_id })).valid);
+  record('mismatched owner fails closed', !(await store.verify({ ...input, principal_id: 'other', lease_id: acquired.lease_id })).valid);
+  record('mismatched lease_id fails closed', !(await store.verify({ ...input, lease_id: crypto.randomUUID() })).valid);
+  record('missing lease fails closed', !(await store.verify({
+    workspace_id: input.workspace_id,
+    target: `missing/${crypto.randomUUID()}.md`,
+    principal_id: input.principal_id,
+    operation_id: input.operation_id,
+    lease_id: acquired.lease_id,
+  })).valid);
+  const renewed = await store.renew({ ...input, lease_id: acquired.lease_id }, 20_000);
+  record('renew extends expiry', renewed.expires_at >= acquired.expires_at);
+  await store.release({ ...input, lease_id: acquired.lease_id });
+  record('released lease is missing', !(await store.verify({ ...input, lease_id: acquired.lease_id })).valid);
+
+  // Controllable clock proves expiry fail-closed for any store that accepts injection.
+  if (typeof store.clock === 'function' || clock) {
+    let now = 1_000_000;
+    const timed = store.constructor === MemoryLeaseStore
+      ? new MemoryLeaseStore({ clock: () => now })
+      : store.constructor === FileLeaseStore
+        ? new FileLeaseStore(path.join(store.root, `expiry-${crypto.randomUUID()}`), { clock: () => now })
+        : null;
+    if (timed) {
+      const timedInput = { ...input, target: `rules/expiry-${crypto.randomUUID()}.md` };
+      const short = await timed.acquire(timedInput, 50);
+      now = short.expires_at + 1;
+      record('expired lease fails closed', !(await timed.verify({ ...timedInput, lease_id: short.lease_id })).valid);
+    }
+  }
+
+  // Filesystem stores must fail closed on corrupt/unreadable state.
+  if (store instanceof FileLeaseStore) {
+    const corruptInput = {
+      workspace_id: `ws-${crypto.randomUUID()}`,
+      target: `rules/corrupt-${crypto.randomUUID()}.md`,
+      principal_id: 'principal',
+      operation_id: 'operation',
+    };
+    const good = await store.acquire(corruptInput, 30_000);
+    fs.writeFileSync(leaseStatePath(store.root, corruptInput.workspace_id, corruptInput.target), '{not-json', { mode: 0o600 });
+    let unreadable = false;
+    try {
+      await store.verify({ ...corruptInput, lease_id: good.lease_id });
+    } catch (error) {
+      unreadable = /unreadable/i.test(error.message);
+    }
+    record('unreadable lease state fails closed', unreadable);
+  }
+
+  return { passed: checks.every((check) => check.passed), checks };
+}

package/src/primitive.mjs

@@ -0,0 +1,227 @@
+/**
+ * SSSS primitive-definition API (spec 0.9).
+ *
+ * Human-facing names and descriptions may be authored in any language. Stable
+ * primitive/field/action/capability identifiers are symbolic controls and are
+ * generated or validated here rather than translated by presentation layers.
+ */
+import crypto from 'node:crypto';
+import { isPrimitiveTypeName } from './registry.mjs';
+
+export const PRIMITIVE_MUTATIONS = ['replace', 'append'];
+export const PRIMITIVE_PORTABILITY = ['structural', 'tenant_private', 'resource_bound'];
+export const PRIMITIVE_SCOPES = ['system', 'account', 'workspace', 'user'];
+export const FIELD_KINDS = [
+  'string', 'text', 'number', 'integer', 'boolean', 'datetime', 'date',
+  'enum', 'object', 'array', 'reference', 'secret_reference', 'resource_reference',
+];
+
+const NAMESPACE_RE = /^[a-z][a-z0-9_-]{0,63}$/;
+const SYMBOL_RE = /^[a-z][a-z0-9_-]{0,127}$/;
+const LANGUAGE_RE = /^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$/;
+const CAPABILITY_RE = /^[a-z][a-z0-9_.-]{0,63}:[a-z][a-z0-9_.-]{0,127}$/;
+
+function isRecord(value) {
+  return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function issue(field, message) {
+  return { field, issue: message };
+}
+
+function uniqueStrings(value) {
+  return Array.isArray(value) && value.every((item) => typeof item === 'string' && item) &&
+    new Set(value).size === value.length;
+}
+
+/** Generate a stable opaque local ID from an authored name in any language. */
+export function generatePrimitiveId({ namespace, name, salt = '' }) {
+  if (!NAMESPACE_RE.test(namespace || '')) throw new Error('namespace must be a safe lowercase identifier.');
+  if (typeof name !== 'string' || !name.trim()) throw new Error('name must be non-empty.');
+  const digest = crypto.createHash('sha256')
+    .update(`${namespace}\0${name.normalize('NFKC')}\0${salt}`)
+    .digest('hex')
+    .slice(0, 20);
+  return `${namespace}:p_${digest}`;
+}
+
+export function validatePrimitiveDefinition(definition) {
+  const errors = [];
+  if (!isRecord(definition)) return { valid: false, errors: [issue('(root)', 'Primitive definition must be an object.')] };
+  const required = ['primitive_id', 'namespace', 'version', 'name', 'mutation', 'portability', 'scopes', 'fields'];
+  for (const field of required) {
+    const value = definition[field];
+    if (value === undefined || value === null || value === '' || (Array.isArray(value) && !value.length)) {
+      errors.push(issue(field, `Missing required field '${field}'.`));
+    }
+  }
+  if (!NAMESPACE_RE.test(definition.namespace || '')) {
+    errors.push(issue('namespace', 'Use a lowercase namespace containing letters, numbers, underscore, or hyphen.'));
+  }
+  if (!isPrimitiveTypeName(definition.primitive_id) ||
+      !definition.primitive_id?.startsWith(`${definition.namespace}:`)) {
+    errors.push(issue('primitive_id', 'Use a qualified identifier whose prefix matches namespace.'));
+  }
+  if (!Number.isInteger(definition.version) || definition.version < 1) {
+    errors.push(issue('version', 'Version must be a positive integer.'));
+  }
+  if (definition.revision !== undefined && (!Number.isInteger(definition.revision) || definition.revision < 1)) {
+    errors.push(issue('revision', 'Revision must be a positive integer.'));
+  }
+  if (typeof definition.name !== 'string' || !definition.name.trim()) {
+    errors.push(issue('name', 'Name may use any language but must not be empty.'));
+  }
+  if (definition.language !== undefined && !LANGUAGE_RE.test(definition.language)) {
+    errors.push(issue('language', 'Use a BCP-47-style language tag.'));
+  }
+  if (!PRIMITIVE_MUTATIONS.includes(definition.mutation)) {
+    errors.push(issue('mutation', `Use one of: ${PRIMITIVE_MUTATIONS.join(', ')}.`));
+  }
+  if (!PRIMITIVE_PORTABILITY.includes(definition.portability)) {
+    errors.push(issue('portability', `Use one of: ${PRIMITIVE_PORTABILITY.join(', ')}.`));
+  }
+  if (!uniqueStrings(definition.scopes) ||
+      definition.scopes.some((scope) => !PRIMITIVE_SCOPES.includes(scope))) {
+    errors.push(issue('scopes', `Provide a unique non-empty subset of: ${PRIMITIVE_SCOPES.join(', ')}.`));
+  }
+  if (!Array.isArray(definition.fields)) {
+    errors.push(issue('fields', 'Fields must be an array.'));
+  } else {
+    const ids = new Set();
+    for (const [index, field] of definition.fields.entries()) {
+      const prefix = `fields[${index}]`;
+      if (!isRecord(field)) {
+        errors.push(issue(prefix, 'Field definition must be an object.'));
+        continue;
+      }
+      if (!SYMBOL_RE.test(field.id || '')) errors.push(issue(`${prefix}.id`, 'Use a stable lowercase symbolic field ID.'));
+      else if (ids.has(field.id)) errors.push(issue(`${prefix}.id`, `Duplicate field ID '${field.id}'.`));
+      else ids.add(field.id);
+      if (typeof field.name !== 'string' || !field.name.trim()) {
+        errors.push(issue(`${prefix}.name`, 'Field name may use any language but must not be empty.'));
+      }
+      if (!FIELD_KINDS.includes(field.kind)) {
+        errors.push(issue(`${prefix}.kind`, `Use one of: ${FIELD_KINDS.join(', ')}.`));
+      }
+      if (field.kind === 'enum' && !uniqueStrings(field.values)) {
+        errors.push(issue(`${prefix}.values`, 'Enum fields require unique non-empty symbolic values.'));
+      }
+      if (field.pattern !== undefined) {
+        try { new RegExp(field.pattern, 'u'); }
+        catch (error) { errors.push(issue(`${prefix}.pattern`, `Invalid regular expression: ${error.message}`)); }
+      }
+    }
+  }
+  if (definition.capabilities !== undefined) {
+    if (!isRecord(definition.capabilities)) errors.push(issue('capabilities', 'Capabilities must be an action-to-list object.'));
+    else for (const [action, values] of Object.entries(definition.capabilities)) {
+      if (!SYMBOL_RE.test(action) || !uniqueStrings(values) || values.some((value) => !CAPABILITY_RE.test(value))) {
+        errors.push(issue(`capabilities.${action}`, 'Use unique qualified capability IDs.'));
+      }
+    }
+  }
+  if (definition.projections !== undefined && !Array.isArray(definition.projections)) {
+    errors.push(issue('projections', 'Projections must be an array.'));
+  }
+  if (definition.aliases !== undefined && (!uniqueStrings(definition.aliases) ||
+      definition.aliases.some((alias) => !isPrimitiveTypeName(alias)))) {
+    errors.push(issue('aliases', 'Aliases must be unique safe primitive identifiers.'));
+  }
+  if (definition.migrations !== undefined && !Array.isArray(definition.migrations)) {
+    errors.push(issue('migrations', 'Migrations must be an array.'));
+  }
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Normalize a user/repo-authored definition and generate missing symbolic IDs.
+ */
+export function definePrimitive(input, options = {}) {
+  if (!isRecord(input)) throw new Error('Primitive input must be an object.');
+  const namespace = input.namespace || options.namespace;
+  const primitive_id = input.primitive_id || generatePrimitiveId({ namespace, name: input.name, salt: options.salt });
+  const fields = (input.fields || []).map((field, index) => ({
+    ...field,
+    id: field.id || `field_${crypto.createHash('sha256')
+      .update(`${primitive_id}\0${field.name || index}`)
+      .digest('hex').slice(0, 12)}`,
+  }));
+  const definition = {
+    type: 'ssss:primitive',
+    version: 1,
+    revision: 1,
+    mutation: 'replace',
+    portability: 'structural',
+    scopes: ['workspace'],
+    ...input,
+    namespace,
+    primitive_id,
+    fields,
+  };
+  const result = validatePrimitiveDefinition(definition);
+  if (!result.valid) {
+    const error = new Error(result.errors.map((entry) => `${entry.field}: ${entry.issue}`).join('; '));
+    error.field_errors = result.errors;
+    throw error;
+  }
+  return definition;
+}
+
+/** Convert a rich primitive definition into the executable registry schema. */
+export function primitiveDefinitionToRegistryEntry(definition) {
+  const result = validatePrimitiveDefinition(definition);
+  if (!result.valid) throw new Error(result.errors.map((entry) => `${entry.field}: ${entry.issue}`).join('; '));
+  const required_fields = ['type'];
+  const optional_fields = [];
+  const enums = {};
+  const patterns = {};
+  const references = {};
+  for (const field of definition.fields) {
+    (field.required ? required_fields : optional_fields).push(field.id);
+    if (field.kind === 'enum') enums[field.id] = field.values;
+    if (field.pattern) patterns[field.id] = field.pattern;
+    if (field.kind === 'reference') references[field.id] = {
+      must_exist: field.must_exist !== false,
+      ...(field.allowed_types ? { allowed_types: field.allowed_types } : {}),
+      ...(field.allowed_portability ? { allowed_portability: field.allowed_portability } : {}),
+    };
+  }
+  return {
+    family: definition.family || 'extension',
+    canonical_path: definition.path_template || null,
+    append_only: definition.mutation === 'append',
+    portability: definition.portability,
+    required_fields,
+    optional_fields,
+    ...(Object.keys(enums).length ? { enums } : {}),
+    ...(Object.keys(patterns).length ? { patterns } : {}),
+    ...(Object.keys(references).length ? { references } : {}),
+    scopes: definition.scopes,
+    capabilities: definition.capabilities || {},
+    events: definition.events || [],
+    projections: definition.projections || [],
+    ui: definition.ui || {},
+    aliases: definition.aliases || [],
+    migrations: definition.migrations || [],
+    primitive_version: definition.version,
+    primitive_revision: definition.revision || 1,
+    authored_language: definition.language || null,
+  };
+}
+
+/** Package one or more definitions as an extension registry object. */
+export function definitionsToExtensionRegistry(namespace, definitions, options = {}) {
+  if (!NAMESPACE_RE.test(namespace || '')) throw new Error('Invalid namespace.');
+  const document_primitives = {};
+  for (const definition of definitions) {
+    if (definition.namespace !== namespace) throw new Error(`Definition '${definition.primitive_id}' belongs to another namespace.`);
+    document_primitives[definition.primitive_id] = primitiveDefinitionToRegistryEntry(definition);
+  }
+  return {
+    registry: namespace,
+    extends: 'ssss',
+    version: options.version || '1.0.0',
+    requires: options.requires || {},
+    document_primitives,
+  };
+}

package/src/projections.mjs

@@ -0,0 +1,133 @@
+/** Replayable, cursor-aware SSSS projection coordinator and host adapter examples. */
+import crypto from 'node:crypto';
+
+function stable(value) {
+  if (Array.isArray(value)) return value.map(stable);
+  if (value && typeof value === 'object') return Object.fromEntries(Object.keys(value).sort().map((key) => [key, stable(value[key])]));
+  return value;
+}
+
+export function projectionHash(value) {
+  return `sha256:${crypto.createHash('sha256').update(JSON.stringify(stable(value))).digest('hex')}`;
+}
+
+/**
+ * Reference projection destination adapters.
+ * Hosts own durable destination writes; these prove the shared apply/reset/snapshot contract.
+ */
+export function createSqlProjectionAdapter({ table = 'ssss_events' } = {}) {
+  const rows = new Map();
+  return {
+    id: `sql:${table}`,
+    kind: 'sql',
+    apply: async (event) => {
+      rows.set(event.event_id, {
+        event_id: event.event_id,
+        subject: event.subject,
+        action: event.action,
+        after_hash: event.after_hash,
+        workspace_id: event.workspace_id,
+      });
+    },
+    reset: async () => rows.clear(),
+    snapshot: async () => Object.fromEntries([...rows.entries()].sort()),
+  };
+}
+
+export function createSearchProjectionAdapter({ index = 'ssss' } = {}) {
+  const documents = new Map();
+  return {
+    id: `search:${index}`,
+    kind: 'search',
+    apply: async (event) => {
+      documents.set(event.subject, {
+        subject: event.subject,
+        terms: [event.action, event.primitive_id, event.subject].filter(Boolean).join(' '),
+        after_hash: event.after_hash,
+      });
+    },
+    reset: async () => documents.clear(),
+    snapshot: async () => Object.fromEntries([...documents.entries()].sort()),
+  };
+}
+
+export function createQueueProjectionAdapter({ topic = 'ssss.mutations' } = {}) {
+  const messages = [];
+  return {
+    id: `queue:${topic}`,
+    kind: 'queue',
+    apply: async (event) => {
+      messages.push({ topic, event_id: event.event_id, subject: event.subject, action: event.action });
+    },
+    reset: async () => { messages.length = 0; },
+    snapshot: async () => messages.map((message) => ({ ...message })),
+  };
+}
+
+export function createViewModelProjectionAdapter({ view = 'detail' } = {}) {
+  const models = new Map();
+  return {
+    id: `view:${view}`,
+    kind: 'view_model',
+    apply: async (event) => {
+      models.set(event.subject, {
+        subject: event.subject,
+        version: event.after_hash || event.before_hash || null,
+        last_action: event.action,
+        principal_id: event.principal?.id || null,
+      });
+    },
+    reset: async () => models.clear(),
+    snapshot: async () => Object.fromEntries([...models.entries()].sort()),
+  };
+}
+
+export class ProjectionCoordinator {
+  constructor({ eventStore, cursorStore = new Map() } = {}) {
+    if (!eventStore) throw new Error('ProjectionCoordinator requires an eventStore.');
+    this.eventStore = eventStore;
+    this.cursorStore = cursorStore;
+    this.projections = new Map();
+  }
+  register(definition) {
+    if (!definition?.id || typeof definition.apply !== 'function') throw new Error('Projection id and apply(event, context) are required.');
+    if (this.projections.has(definition.id)) throw new Error(`Duplicate projection '${definition.id}'.`);
+    this.projections.set(definition.id, definition);
+  }
+  async replay(id, options = {}) {
+    const projection = this.projections.get(id);
+    if (!projection) throw new Error(`Unknown projection '${id}'.`);
+    let cursor = options.rebuild ? 0 : (this.cursorStore.get(id) || 0);
+    if (options.rebuild && projection.reset) await projection.reset();
+    let applied = 0;
+    for await (const item of this.eventStore.replay({ cursor, workspaceId: options.workspaceId })) {
+      if (!projection.filter || projection.filter(item.event)) {
+        await projection.apply(item.event, { replay: true, cursor: item.cursor });
+        applied++;
+      }
+      cursor = item.cursor;
+      this.cursorStore.set(id, cursor);
+    }
+    const state = projection.snapshot ? await projection.snapshot() : null;
+    return { id, cursor, applied, output_hash: state === null ? null : projectionHash(state) };
+  }
+  async dispatch(event) {
+    const results = [];
+    for (const projection of this.projections.values()) {
+      if (projection.filter && !projection.filter(event)) continue;
+      try {
+        await projection.apply(event, { replay: false });
+        results.push({ id: projection.id, success: true });
+      } catch (error) {
+        results.push({ id: projection.id, success: false, error: error.message });
+      }
+    }
+    return results;
+  }
+  async detectDrift(id, expectedHash) {
+    const projection = this.projections.get(id);
+    if (!projection?.snapshot) throw new Error(`Projection '${id}' does not expose snapshot().`);
+    const actualHash = projectionHash(await projection.snapshot());
+    return { drift: actualHash !== expectedHash, expected_hash: expectedHash, actual_hash: actualHash };
+  }
+}