wowbagger 0.1.0-alpha.1

package/src/adapter/invoke.js

@@ -0,0 +1,294 @@
+import { ADAPTER_CONTRACT_VERSION, describeAdapter } from './describe.js';
+import { createHash } from 'node:crypto';
+import { verifyMutationAuthority } from './approval.js';
+import { validateInvokeContext } from './context.js';
+import { verifyCoreProbe } from './core-probe.js';
+import { validateInvocationLimits } from './limits.js';
+import { resolveInvocationPaths } from './paths.js';
+import { mapProcessOutcome } from './process-outcome.js';
+import { hasExactMembers, isPositiveSafeInteger } from './schema-helpers.js';
+import { normalizeJsonValue, parseJsonRequest } from '../request.js';
+import { INVOKE_MESSAGES } from './messages.js';
+
+const SAFE_ID = /^[A-Za-z0-9._-]{1,128}$/;
+const WOWBAGGER_ID = /^wb_[0-7][0-9A-HJKMNP-TV-Z]{25}$/;
+const DIGEST = /^sha256:[a-f0-9]{64}$/;
+
+function isMutationCommand(command) {
+  return command === 'create' || command === 'transition' || command === 'patch';
+}
+
+const MESSAGES = INVOKE_MESSAGES;
+
+function coreRequestIssue(coreRequest) {
+  if (coreRequest?.command === 'capabilities') {
+    return hasExactMembers(coreRequest, ['command']) ? null : 'core_request';
+  }
+  if (coreRequest?.command === 'validate') {
+    return hasExactMembers(coreRequest, ['command', 'ledger']) && typeof coreRequest.ledger === 'string'
+      ? null : 'core_request';
+  }
+  if (coreRequest?.command === 'ready') {
+    return hasExactMembers(coreRequest, ['command', 'ledger', 'as_of'])
+      && typeof coreRequest.ledger === 'string' && typeof coreRequest.as_of === 'string'
+      ? null : 'core_request';
+  }
+  if (coreRequest?.command === 'inspect') {
+    return hasExactMembers(coreRequest, ['command', 'ledger', 'id'])
+      && typeof coreRequest.ledger === 'string' && typeof coreRequest.id === 'string'
+      ? null : 'core_request';
+  }
+  if (isMutationCommand(coreRequest?.command)) {
+    return hasExactMembers(coreRequest, ['command', 'ledger', 'input_base64'])
+      && typeof coreRequest.ledger === 'string'
+      && typeof coreRequest.input_base64 === 'string'
+      ? null : 'core_request';
+  }
+  return 'core_request';
+}
+
+function argumentVector(coreRequest, ledger) {
+  switch (coreRequest.command) {
+    case 'capabilities': return ['capabilities', '--json'];
+    case 'validate': return ['validate', '--ledger', ledger, '--json'];
+    case 'ready': return ['ready', '--ledger', ledger, '--as-of', coreRequest.as_of, '--json'];
+    case 'inspect': return ['inspect', '--ledger', ledger, '--id', coreRequest.id, '--json'];
+    case 'create': return ['create', '--ledger', ledger, '--input', '-', '--json'];
+    case 'patch': return ['patch', '--ledger', ledger, '--input', '-', '--json'];
+    case 'transition': return ['transition', '--ledger', ledger, '--input', '-', '--json'];
+    default: throw new TypeError('unsupported core command');
+  }
+}
+
+function launchFailureObservation() {
+  return {
+    started: false,
+    process_tree_contained: true,
+    orphaned: false,
+    exit_code: null,
+    signal: null,
+    timed_out: false,
+    stdout_complete: true,
+    stderr_complete: true,
+    stdout_base64: '',
+    stderr_base64: '',
+  };
+}
+
+function streamEnvelope(bytes) {
+  return {
+    encoding: 'base64',
+    data: bytes.toString('base64'),
+    sha256: `sha256:${createHash('sha256').update(bytes).digest('hex')}`,
+    byte_length: bytes.length,
+  };
+}
+
+function refusal(requestId, code, details) {
+  return {
+    ok: false,
+    adapter_contract_version: ADAPTER_CONTRACT_VERSION,
+    request_id: requestId,
+    error: {
+      code,
+      message: MESSAGES[code] ?? `The adapter refused the operation (${code}).`,
+      details,
+    },
+  };
+}
+
+export async function invokeAdapter(requestBytes, runtime) {
+  if (!(requestBytes instanceof Uint8Array) || !isPositiveSafeInteger(runtime?.max_request_bytes)) {
+    return refusal(null, 'invalid-invocation', { member: 'request' });
+  }
+  if (requestBytes.byteLength > runtime.max_request_bytes) {
+    return refusal(null, 'invalid-invocation', {
+      member: 'request', reason: 'byte-limit-exceeded', limit_bytes: runtime.max_request_bytes,
+    });
+  }
+  const parsed = parseJsonRequest(requestBytes);
+  if (parsed.issues.length > 0) {
+    return refusal(null, 'invalid-invocation', { member: 'request_json' });
+  }
+  const request = normalizeJsonValue(parsed.value);
+  const requestId = typeof request?.request_id === 'string' && SAFE_ID.test(request.request_id)
+    ? request.request_id
+    : null;
+  if (!hasExactMembers(request, [
+    'adapter_contract_version', 'request_id', 'core_request', 'instruction_input', 'handoff_carrier', 'limits',
+  ], ['workspace']) || requestId === null) {
+    return refusal(requestId, 'invalid-invocation', { member: 'request' });
+  }
+  const described = describeAdapter(runtime.describe_request, runtime.manifest, runtime.dynamic);
+  if (!described.ok) {
+    return refusal(requestId, described.error_code, described.detail);
+  }
+  if (described.result.limits.max_request_bytes > runtime.max_request_bytes) {
+    return refusal(requestId, 'invalid-describe-result', { member: 'limits.max_request_bytes' });
+  }
+  if (requestBytes.byteLength > described.result.limits.max_request_bytes) {
+    return refusal(requestId, 'invalid-invocation', {
+      member: 'request', reason: 'byte-limit-exceeded', limit_bytes: described.result.limits.max_request_bytes,
+    });
+  }
+  if (request.adapter_contract_version !== described.result.selected_adapter_contract_version) {
+    return refusal(requestId, 'adapter-contract-selection-mismatch', {
+      expected: described.result.selected_adapter_contract_version,
+      received: request.adapter_contract_version,
+    });
+  }
+  const command = request.core_request?.command;
+  const mutation = isMutationCommand(command);
+  const required = ['command-execution'];
+  if (command !== 'capabilities') required.push('guarded-filesystem');
+  const available = [];
+  if (described.result.host.command_execution.supported) available.push('command-execution');
+  if (described.result.host.filesystem.workspace_selection === 'guarded-relative') {
+    available.push('guarded-filesystem');
+  }
+  const missing = required.filter((capability) => !available.includes(capability));
+  if (missing.length > 0) return refusal(requestId, 'capability-unavailable', { missing });
+
+  const activePlatform = runtime.platform ?? process.platform;
+  const platformStatus = described.result.platforms[activePlatform] ?? 'unknown';
+  if (platformStatus !== 'supported') {
+    return refusal(requestId, 'adapter-platform-mismatch', {
+      platform: activePlatform, status: platformStatus, required: 'supported',
+    });
+  }
+  const probed = verifyCoreProbe(described.result, runtime.core_probe);
+  if (!probed.ok) return refusal(requestId, probed.error_code, probed.detail);
+  const limits = validateInvocationLimits(request.limits, described.result.limits);
+  if (!limits.ok) return refusal(requestId, limits.error_code, limits.detail);
+  const requestIssue = coreRequestIssue(request.core_request);
+  if (requestIssue) return refusal(requestId, 'invalid-invocation', { member: requestIssue });
+  if (request.handoff_carrier !== null && described.result.host.handoff.supported !== true) {
+    return refusal(requestId, 'capability-unavailable', { missing: ['handoff'] });
+  }
+  const context = validateInvokeContext({
+    instruction_input: request.instruction_input,
+    handoff_carrier: request.handoff_carrier,
+    context_bytes: request.limits.context_bytes,
+    instruction_limits: described.result.host.instruction_input,
+    handoff_options: {
+      workspace_id: request.workspace?.workspace_id,
+      max_bytes: request.limits.context_bytes,
+      current: runtime.handoff_current,
+    },
+  });
+  if (!context.ok) {
+    return refusal(requestId, context.error_code, context.detail);
+  }
+
+  let workspace = null;
+  if (command !== 'capabilities') {
+    if (!hasExactMembers(request.workspace, ['workspace_id'], ['cwd'])
+      || typeof request.workspace.workspace_id !== 'string') {
+      return refusal(requestId, 'invalid-invocation', { member: 'workspace' });
+    }
+    const configured = runtime.workspaces?.[request.workspace.workspace_id];
+    if (!configured) {
+      return refusal(requestId, 'path-rejected', {
+        path_role: 'workspace', kind: 'unconfigured-workspace',
+      });
+    }
+    const resolved = resolveInvocationPaths({
+      workspace_root: configured.root,
+      cwd: request.workspace.cwd ?? '.',
+      ledger: request.core_request.ledger,
+      before: configured.before,
+      after: configured.after,
+    });
+    if (!resolved.ok) return refusal(requestId, resolved.error_code, resolved.detail);
+    workspace = resolved;
+  }
+
+  const argv = argumentVector(request.core_request, workspace?.ledger);
+  const mutationInput = mutation
+    ? Buffer.from(request.core_request.input_base64, 'base64')
+    : Buffer.alloc(0);
+  const parsedMutationRequest = mutation ? parseJsonRequest(mutationInput) : null;
+  const mutationRequest = parsedMutationRequest?.issues.length === 0
+    ? normalizeJsonValue(parsedMutationRequest.value)
+    : null;
+  if (mutation) {
+    if (described.result.host.trusted_approval?.supported !== true) {
+      return refusal(requestId, 'capability-unavailable', { missing: ['trusted-approval'] });
+    }
+    const authority = verifyMutationAuthority({
+      command,
+      approval: runtime.approval,
+      approvalOptions: {
+        binding: {
+          request_id: requestId,
+          adapter: {
+            id: described.result.adapter_id,
+            version: described.result.adapter_version,
+            contract_version: described.result.selected_adapter_contract_version,
+          },
+          core: {
+            executable_identity: runtime.core_executable_identity,
+            contract_version: described.result.core.required_core_contract_version,
+            argv,
+            input_base64: request.core_request.input_base64,
+          },
+          workspace: {
+            id: request.workspace.workspace_id,
+            root: runtime.workspaces[request.workspace.workspace_id].root,
+            cwd: workspace.cwd,
+            ledger: workspace.ledger,
+          },
+          limits: request.limits,
+          instruction_set_digest: context.instructions.instruction_set_digest,
+          handoff_digest: request.handoff_carrier?.sha256 ?? null,
+        },
+        now: runtime.now,
+        redeemedNonces: runtime.redeemed_nonces,
+        trustedSources: new Set(described.result.host.trusted_approval.sources),
+      },
+    });
+    if (!authority.ok) return refusal(requestId, authority.error_code, authority.detail);
+  }
+  let processObservation;
+  try {
+    processObservation = await runtime.launch({
+      command,
+      argv,
+      cwd: workspace?.cwd ?? runtime.package_root,
+      input: mutationInput,
+      limits: request.limits,
+    });
+  } catch {
+    processObservation = launchFailureObservation();
+  }
+  const processFailure = mapProcessOutcome({
+    adapter_contract_version: ADAPTER_CONTRACT_VERSION,
+    request_id: requestId,
+    command,
+    core_request: request.core_request,
+    mutation_request: mutationRequest,
+    mutation_input: mutation ? mutationInput : undefined,
+    item_id: WOWBAGGER_ID.test(mutationRequest?.id) ? mutationRequest.id : null,
+    expected_revision: DIGEST.test(mutationRequest?.expected_revision)
+      ? mutationRequest.expected_revision
+      : null,
+    stdout_limit_bytes: request.limits.stdout_bytes,
+    stderr_limit_bytes: request.limits.stderr_bytes,
+    process: processObservation,
+  });
+  if (processFailure) return processFailure;
+
+  const stdout = Buffer.from(processObservation.stdout_base64, 'base64');
+  const stderr = Buffer.from(processObservation.stderr_base64, 'base64');
+  return {
+    ok: true,
+    adapter_contract_version: ADAPTER_CONTRACT_VERSION,
+    request_id: requestId,
+    result: {
+      core_command: command,
+      core_exit_code: processObservation.exit_code,
+      stdout: streamEnvelope(stdout),
+      stderr: streamEnvelope(stderr),
+    },
+  };
+}

package/src/adapter/limits.js

@@ -0,0 +1,26 @@
+import { hasExactMembers, isNonNegativeSafeInteger, isPositiveSafeInteger } from './schema-helpers.js';
+
+function refuse(error_code, detail) {
+  return { ok: false, error_code, detail };
+}
+
+export function validateInvocationLimits(requested, advertised) {
+  if (!hasExactMembers(requested, ['context_bytes', 'stdout_bytes', 'stderr_bytes', 'timeout_ms'])) {
+    return refuse('invalid-invocation', { member: 'limits' });
+  }
+  const limits = [
+    ['context_bytes', 'max_context_bytes', isNonNegativeSafeInteger, 'context-limit-exceeded'],
+    ['stdout_bytes', 'max_stdout_bytes', isNonNegativeSafeInteger, 'output-limit-exceeded'],
+    ['stderr_bytes', 'max_stderr_bytes', isNonNegativeSafeInteger, 'output-limit-exceeded'],
+    ['timeout_ms', 'max_timeout_ms', isPositiveSafeInteger, 'timeout-limit-exceeded'],
+  ];
+  for (const [requestedKey, maximumKey, valid, exceededCode] of limits) {
+    if (!valid(requested[requestedKey]) || !valid(advertised?.[maximumKey])) {
+      return refuse('invalid-invocation', { member: `limits.${requestedKey}` });
+    }
+    if (requested[requestedKey] > advertised[maximumKey]) {
+      return refuse(exceededCode, { member: requestedKey });
+    }
+  }
+  return { ok: true };
+}

package/src/adapter/manifest.js

@@ -0,0 +1,93 @@
+const ROOT_MEMBERS = Object.freeze([
+  'adapter_manifest_version', 'adapter_id', 'adapter_version',
+  'adapter_contract_versions', 'bootstrap_wire_version',
+  'required_core_contract_version', 'entrypoints', 'platforms',
+]);
+
+function refuse(detail) {
+  return { ok: false, error_code: 'invalid-adapter-manifest', detail };
+}
+
+// C0 controls (below U+0020) and DEL (U+007F). U+0020 and U+007E are the
+// inclusive edges of the accepted printable range; the boundary is exact.
+export function hasControlCharacter(value) {
+  for (let index = 0; index < value.length; index += 1) {
+    const code = value.charCodeAt(index);
+    if (code < 32 || code === 127) {
+      return true;
+    }
+  }
+  return false;
+}
+
+export function isSafeRelativeExecutable(value) {
+  if (typeof value !== 'string' || value.length === 0) {
+    return false;
+  }
+  if (hasControlCharacter(value)) {
+    return false;
+  }
+  if (value.includes('\\') || value.startsWith('/')) {
+    return false;
+  }
+  if (/^[A-Za-z]:/.test(value)) {
+    return false;
+  }
+  if (/^volume\{[^/]*\}(\/|$)/i.test(value)) {
+    return false;
+  }
+  const segments = value.split('/');
+  return segments.every((segment) => segment !== '' && segment !== '.' && segment !== '..');
+}
+
+export function validateAdapterManifest(value) {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    return refuse('manifest is not an object');
+  }
+  const present = Object.keys(value);
+  for (const member of present) {
+    if (!ROOT_MEMBERS.includes(member)) {
+      return refuse(`unknown root member ${member}`);
+    }
+  }
+  for (const member of ROOT_MEMBERS) {
+    if (!present.includes(member)) {
+      return refuse(`missing root member ${member}`);
+    }
+  }
+  if (value.entrypoints === null || typeof value.entrypoints !== 'object' || Array.isArray(value.entrypoints)) {
+    return refuse('entrypoints is not an object');
+  }
+  const entrypointMembers = Object.keys(value.entrypoints);
+  if (entrypointMembers.length !== 2 || !entrypointMembers.includes('describe') || !entrypointMembers.includes('invoke')) {
+    return refuse('entrypoints does not have exactly describe and invoke');
+  }
+  for (const key of ['describe', 'invoke']) {
+    const entrypoint = value.entrypoints?.[key];
+    if (entrypoint === null || typeof entrypoint !== 'object' || Array.isArray(entrypoint)) {
+      return refuse(`entrypoint ${key} is not an object`);
+    }
+    if (entrypoint.kind === 'host-tool') {
+      const members = Object.keys(entrypoint).sort();
+      if (members.join(',') !== 'kind,name' || typeof entrypoint.name !== 'string' || entrypoint.name === '') {
+        return refuse(`entrypoint ${key} host-tool schema is not exact`);
+      }
+      continue;
+    }
+    if (entrypoint.kind !== 'command') {
+      return refuse(`entrypoint ${key} kind is unknown`);
+    }
+    const members = Object.keys(entrypoint).sort();
+    if (members.join(',') !== 'executable,fixed_args,kind') {
+      return refuse(`entrypoint ${key} command schema is not exact`);
+    }
+    if (!isSafeRelativeExecutable(entrypoint.executable)) {
+      return refuse(`entrypoint ${key} executable is unsafe`);
+    }
+    if (!Array.isArray(entrypoint.fixed_args)
+      || entrypoint.fixed_args.some((arg) => typeof arg !== 'string' || hasControlCharacter(arg))) {
+      return refuse(`entrypoint ${key} fixed_args are invalid`);
+    }
+  }
+  return { ok: true, manifest: value };
+}

package/src/adapter/messages.js

@@ -0,0 +1,15 @@
+// Single source of truth for the ship-side Invoke refusal messages. The
+// reference model's `OUTER_ERROR_MESSAGES` in spec/adapter-reference.js
+// documents the same text; a test pins the two sides so a divergence turns
+// red instead of silently diverging the wire from the reference model.
+// (Item 39: the message used to exist as a bare literal in the entrypoint
+// and in two tables, with nothing pinning it.)
+export const INVOKE_MESSAGES = Object.freeze({
+  'capability-unavailable': 'The configured host cannot invoke the Wowbagger core.',
+  'consumer-approval-required': 'The consumer must approve this ledger mutation.',
+  'invalid-invocation': 'The adapter invocation is invalid.',
+  'mutation-outcome-unknown': 'The mutation may have been applied; inspect current state before retrying.',
+  'output-limit-exceeded': 'The core output exceeded the requested bound.',
+  'path-rejected': 'The requested ledger path is not a guarded real directory.',
+  'path-replaced': 'A guarded path component changed before core launch.',
+});

package/src/adapter/paths.js

@@ -0,0 +1,88 @@
+import path from 'node:path';
+import { hasControlCharacter } from './manifest.js';
+import { hasExactMembers, isNonNegativeSafeInteger, sameJson } from './schema-helpers.js';
+
+function refuse(error_code, detail) {
+  return { ok: false, error_code, detail };
+}
+
+export function isSafeLogicalPath(value) {
+  return value === '.' || (typeof value === 'string'
+    && value.length > 0
+    && !value.startsWith('/')
+    && !value.includes('\\')
+    && !value.includes('\0')
+    && !/^[A-Za-z]:/.test(value)
+    && !/^volume\{[^}]+\}(?:\/|$)/i.test(value)
+    && value.split('/').every((segment) => segment !== '' && segment !== '.' && segment !== '..'));
+}
+
+function cumulativeComponents(logicalPath) {
+  if (logicalPath === '.') return [];
+  const segments = logicalPath.split('/');
+  return segments.map((_, index) => segments.slice(0, index + 1).join('/'));
+}
+
+function isIdentityMember(value) {
+  return (typeof value === 'string' && value.length > 0 && !hasControlCharacter(value))
+    || isNonNegativeSafeInteger(value);
+}
+
+function isValidIdentity(value) {
+  if (typeof value === 'string') return isIdentityMember(value);
+  if (hasExactMembers(value, ['dev', 'ino'])) {
+    return isIdentityMember(value.dev) && isIdentityMember(value.ino);
+  }
+  if (hasExactMembers(value, ['volume_id', 'file_id'])) {
+    return isIdentityMember(value.volume_id) && isIdentityMember(value.file_id);
+  }
+  return false;
+}
+
+function snapshotIssue(snapshot) {
+  if (snapshot === null || typeof snapshot !== 'object' || Array.isArray(snapshot)) return 'missing';
+  if (!Object.hasOwn(snapshot, 'kind')) return 'invalid-kind';
+  if (snapshot.kind !== 'directory') return snapshot.kind;
+  if (!Object.hasOwn(snapshot, 'identity') || !isValidIdentity(snapshot.identity)) return 'invalid-identity';
+  if (!hasExactMembers(snapshot, ['kind', 'identity'])) return 'invalid-snapshot';
+  return null;
+}
+
+function snapshotRefusal(pathRole, component, kind, snapshot) {
+  const detail = { path_role: pathRole, component, kind };
+  if (kind.startsWith('invalid-')) detail.snapshot = snapshot;
+  return refuse('path-rejected', detail);
+}
+
+export function resolveInvocationPaths({ workspace_root: workspaceRoot, cwd, ledger, before, after }) {
+  for (const [role, logicalPath] of [['cwd', cwd], ['ledger', ledger]]) {
+    if (!isSafeLogicalPath(logicalPath)) {
+      return refuse('path-rejected', { path_role: role, kind: 'invalid-logical-path' });
+    }
+  }
+
+  const components = [
+    { role: 'workspace', logical: '.' },
+    ...cumulativeComponents(cwd).map((logical) => ({ role: 'cwd', logical })),
+    ...cumulativeComponents(ledger).map((logical) => ({ role: 'ledger', logical })),
+  ];
+  const seen = new Set();
+  for (const { role, logical } of components) {
+    if (seen.has(logical)) continue;
+    seen.add(logical);
+    const initialIssue = snapshotIssue(before?.[logical]);
+    if (initialIssue) return snapshotRefusal(role, logical, initialIssue, 'initial');
+    const finalIssue = snapshotIssue(after?.[logical]);
+    if (finalIssue) return snapshotRefusal(role, logical, finalIssue, 'final');
+    if (!sameJson(before[logical].identity, after[logical].identity)) {
+      return refuse('path-replaced', { path_role: role, component: logical });
+    }
+  }
+
+  return {
+    ok: true,
+    workspace_root: workspaceRoot,
+    cwd: cwd === '.' ? workspaceRoot : path.posix.join(workspaceRoot, cwd),
+    ledger: ledger === '.' ? workspaceRoot : path.posix.join(workspaceRoot, ledger),
+  };
+}