@emptyos/client 0.1.0 → 0.1.1

package/README.md

@@ -262,3 +262,8 @@ npm test
 
 Tests use temporary real Git repositories and fake `ssh`/`git` executables;
 they do not require a network connection or an EmptyOS computer.
+
+`lib/vendor/` holds byte-identical copies of the `provision/lib` modules the
+client imports, because the published package must not reach outside its own
+tree and those modules also ship to computers. `test/vendor.test.js` fails
+when a copy drifts; refresh it with `cp provision/lib/<name> client/lib/vendor/<name>`.

package/lib/constants.js

@@ -1,4 +1,4 @@
-export const CLIENT_VERSION = '0.1.0';
+export const CLIENT_VERSION = '0.1.1';
 export const PROTOCOL_VERSION = 2;
 
 export const ALIAS_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;

package/lib/platform-update.js

@@ -4,8 +4,10 @@ import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-import { parseReleaseArtifactBytes } from '../../provision/lib/platform-release-artifact.mjs';
-import { PLATFORM_RELEASE_CATALOG_URL } from '../../provision/lib/platform-release-channel.mjs';
+// Byte-identical copies of the provision modules (client/test/vendor.test.js):
+// the published package must import nothing outside its own tree.
+import { parseReleaseArtifactBytes } from './vendor/platform-release-artifact.mjs';
+import { PLATFORM_RELEASE_CATALOG_URL } from './vendor/platform-release-channel.mjs';
 import { ClientError } from './errors.js';
 import { runCaptured, runInherited } from './process.js';
 import { sshCommand, sshTransport } from './rpc.js';

package/lib/vendor/platform-release-artifact.mjs

@@ -0,0 +1,413 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+import {
+  assertValidProtocolTarget,
+  assertValidTarget,
+  manifestAtRevision,
+  manifestDigest,
+  normalizeManifest,
+  readSourceScope,
+  serializeManifest,
+  validateRelativePath,
+} from './platform-release.mjs';
+
+export const RELEASE_ARTIFACT_COMPONENT = 'emptyos-platform-release';
+export const RELEASE_ARTIFACT_VERSION = 1;
+export const UPDATE_PROTOCOL_VERSION = 1;
+
+const RELEASE_FILE = /^[A-Za-z0-9._/-]+$/;
+const RELEASE_ID = /^sha256:[0-9a-f]{64}$/;
+const MAX_ARTIFACT_BYTES = 64 * 1024 * 1024;
+const MAX_FILES = 10_000;
+const MAX_BASELINES = 100_000;
+
+function fail(message) {
+  throw new Error(message);
+}
+
+function run(command, args, { cwd, env = process.env, timeout = 120_000, quiet = false } = {}) {
+  const result = spawnSync(command, args, {
+    cwd,
+    env: { ...env, LC_ALL: 'C' },
+    encoding: 'utf8',
+    stdio: quiet ? ['ignore', 'pipe', 'pipe'] : ['ignore', 'inherit', 'inherit'],
+    timeout,
+  });
+  if (result.error) throw result.error;
+  if (result.status !== 0) {
+    const detail = quiet ? (result.stderr || result.stdout || '').trim() : '';
+    fail(`\`${command} ${args.join(' ')}\` failed${detail ? `: ${detail}` : ''}`);
+  }
+  return quiet ? result.stdout.trimEnd() : '';
+}
+
+function git(repo, args) {
+  return run('git', ['-C', repo, ...args], { quiet: true });
+}
+
+function gitBlobId(contents, length) {
+  const algorithm = length === 64 ? 'sha256' : 'sha1';
+  return crypto.createHash(algorithm)
+    .update(`blob ${contents.length}\0`)
+    .update(contents)
+    .digest('hex');
+}
+
+function normalizeReleaseFile(file) {
+  if (!file || typeof file !== 'object' || Array.isArray(file)) fail('Invalid platform release file');
+  const relativePath = String(file.path ?? '');
+  const segments = relativePath.split('/');
+  if (!RELEASE_FILE.test(relativePath) || relativePath.startsWith('/') || relativePath.length > 4096 ||
+      segments.some((segment) => segment === '' || segment === '.' || segment === '..' ||
+        segment === '.git' || segment.length > 255)) {
+    fail(`Unsafe platform release path: ${JSON.stringify(relativePath)}`);
+  }
+  const mode = String(file.mode ?? '');
+  if (!['100644', '100755'].includes(mode)) fail(`Invalid platform release mode for ${relativePath}`);
+  const blob = String(file.blob ?? '');
+  if (!/^[0-9a-f]{40}$|^[0-9a-f]{64}$/.test(blob)) fail(`Invalid platform release blob for ${relativePath}`);
+  const sha256 = String(file.sha256 ?? '');
+  if (!/^[0-9a-f]{64}$/.test(sha256)) fail(`Invalid platform release sha256 for ${relativePath}`);
+  const data = String(file.data ?? '');
+  const contents = Buffer.from(data, 'base64');
+  if (contents.toString('base64') !== data) fail(`Invalid base64 payload for ${relativePath}`);
+  if (gitBlobId(contents, blob.length) !== blob) fail(`Payload does not match manifest blob for ${relativePath}`);
+  if (crypto.createHash('sha256').update(contents).digest('hex') !== sha256) {
+    fail(`Payload does not match sha256 for ${relativePath}`);
+  }
+  return { path: relativePath, mode, blob, sha256, data };
+}
+
+export function normalizeReleaseArtifact(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) fail('Invalid platform release artifact');
+  if (value.version !== RELEASE_ARTIFACT_VERSION || value.component !== RELEASE_ARTIFACT_COMPONENT) {
+    fail('Unsupported platform release artifact');
+  }
+  if (value.updateProtocol !== UPDATE_PROTOCOL_VERSION) {
+    fail(`Unsupported platform update protocol ${JSON.stringify(value.updateProtocol)}`);
+  }
+
+  if (value.target?.version !== 1 || value.target?.component !== 'emptyos-platform' || !Array.isArray(value.target.files)) {
+    fail('Platform release has an invalid target manifest');
+  }
+  const target = normalizeManifest(value.target.files);
+  assertValidProtocolTarget(target);
+  const targetRelease = `sha256:${manifestDigest(target)}`;
+  if (value.release !== targetRelease) fail('Platform release id does not match its target manifest');
+
+  if (!Array.isArray(value.acceptedBaselines) || value.acceptedBaselines.length === 0) {
+    fail('Platform release has no accepted baselines');
+  }
+  if (value.acceptedBaselines.length > MAX_BASELINES) fail('Platform release has too many accepted baselines');
+  const acceptedBaselines = [...new Set(value.acceptedBaselines.map(String))].sort();
+  if (acceptedBaselines.some((release) => !RELEASE_ID.test(release))) {
+    fail('Platform release has an invalid accepted baseline');
+  }
+  if (!acceptedBaselines.includes(targetRelease)) fail('Platform release must accept its own target baseline');
+
+  if (!Array.isArray(value.files)) fail('Platform release files must be an array');
+  if (value.files.length > MAX_FILES) fail('Platform release has too many files');
+  const comparePath = (left, right) => left.path < right.path ? -1 : left.path > right.path ? 1 : 0;
+  const files = value.files.map(normalizeReleaseFile).sort(comparePath);
+  for (let index = 1; index < files.length; index += 1) {
+    if (files[index - 1].path === files[index].path) {
+      fail(`Duplicate platform release path: ${files[index].path}`);
+    }
+  }
+  const targetFiles = [...target.files].sort(comparePath);
+  if (files.length !== targetFiles.length) fail('Platform release payload does not match its target manifest');
+  for (let index = 0; index < files.length; index += 1) {
+    const payload = files[index];
+    const manifest = targetFiles[index];
+    if (payload.path !== manifest.path || payload.mode !== manifest.mode || payload.blob !== manifest.blob) {
+      fail('Platform release payload does not match its target manifest');
+    }
+  }
+
+  return {
+    version: RELEASE_ARTIFACT_VERSION,
+    component: RELEASE_ARTIFACT_COMPONENT,
+    updateProtocol: UPDATE_PROTOCOL_VERSION,
+    release: targetRelease,
+    acceptedBaselines,
+    target,
+    files,
+  };
+}
+
+export function serializeReleaseArtifact(value) {
+  return `${JSON.stringify(normalizeReleaseArtifact(value), null, 2)}\n`;
+}
+
+export function parseReleaseArtifact(file) {
+  let raw;
+  try {
+    const stat = fs.lstatSync(file);
+    if (!stat.isFile() || stat.isSymbolicLink()) fail(`Platform release artifact is not a regular file: ${file}`);
+    if (stat.size > MAX_ARTIFACT_BYTES) fail(`Platform release artifact exceeds ${MAX_ARTIFACT_BYTES} bytes`);
+    raw = fs.readFileSync(file);
+  } catch (error) {
+    fail(`Cannot read platform release artifact ${file}: ${error.message}`);
+  }
+  return parseReleaseArtifactBytes(raw, file);
+}
+
+export function parseReleaseArtifactBytes(raw, label = '<memory>') {
+  if (!Buffer.isBuffer(raw)) fail('Platform release artifact bytes must be a Buffer');
+  if (raw.length > MAX_ARTIFACT_BYTES) fail(`Platform release artifact exceeds ${MAX_ARTIFACT_BYTES} bytes`);
+  let value;
+  try {
+    value = JSON.parse(raw.toString('utf8'));
+  } catch (error) {
+    fail(`Cannot parse platform release artifact ${label}: ${error.message}`);
+  }
+  const release = normalizeReleaseArtifact(value);
+  const canonical = Buffer.from(serializeReleaseArtifact(release), 'utf8');
+  if (!raw.equals(canonical)) fail(`Platform release artifact is not canonical: ${label}`);
+  return {
+    ...release,
+    artifactSha256: crypto.createHash('sha256').update(raw).digest('hex'),
+  };
+}
+
+export function releaseArtifactDigest(value) {
+  return crypto.createHash('sha256').update(serializeReleaseArtifact(value)).digest('hex');
+}
+
+export function extractReleaseArtifact(file, destination) {
+  const release = parseReleaseArtifact(file);
+  fs.mkdirSync(path.dirname(destination), { recursive: true, mode: 0o700 });
+  fs.mkdirSync(destination, { mode: 0o700 });
+  try {
+    fs.chmodSync(destination, 0o700);
+    const payloadRoot = path.join(destination, 'payload', 'seed');
+    fs.mkdirSync(payloadRoot, { recursive: true, mode: 0o700 });
+    fs.chmodSync(path.join(destination, 'payload'), 0o700);
+    fs.chmodSync(payloadRoot, 0o700);
+    for (const entry of release.files) {
+      const output = path.join(payloadRoot, ...entry.path.split('/'));
+      const relative = path.relative(payloadRoot, output);
+      if (relative.startsWith('..') || path.isAbsolute(relative)) fail(`Unsafe extracted platform path: ${entry.path}`);
+      fs.mkdirSync(path.dirname(output), { recursive: true, mode: 0o700 });
+      for (let current = path.dirname(output); current.startsWith(payloadRoot); current = path.dirname(current)) {
+        fs.chmodSync(current, 0o700);
+        if (current === payloadRoot) break;
+      }
+      fs.writeFileSync(output, Buffer.from(entry.data, 'base64'), { flag: 'wx' });
+      fs.chmodSync(output, entry.mode === '100755' ? 0o755 : 0o644);
+    }
+    const targetFile = path.join(destination, 'target.json');
+    const releaseFile = path.join(destination, 'release.json');
+    fs.writeFileSync(targetFile, serializeManifest(release.target), { flag: 'wx' });
+    fs.chmodSync(targetFile, 0o600);
+    fs.writeFileSync(releaseFile, `${JSON.stringify({
+      version: RELEASE_ARTIFACT_VERSION,
+      component: RELEASE_ARTIFACT_COMPONENT,
+      updateProtocol: UPDATE_PROTOCOL_VERSION,
+      release: release.release,
+      artifactSha256: release.artifactSha256,
+      acceptedBaselines: release.acceptedBaselines,
+    }, null, 2)}\n`, { flag: 'wx' });
+    fs.chmodSync(releaseFile, 0o600);
+  } catch (error) {
+    fs.rmSync(destination, { recursive: true, force: true });
+    throw error;
+  }
+  return release;
+}
+
+function packageRecords(manifest) {
+  const byPath = new Map(manifest.files.map((entry) => [entry.path, entry]));
+  return ['package.json', 'package-lock.json'].map((name) => byPath.get(name)?.blob ?? null).join(':');
+}
+
+function repositoryScopePath(repo, scopeFile) {
+  const relative = path.relative(repo, fs.realpathSync(scopeFile));
+  if (!relative || path.isAbsolute(relative) || relative === '..' || relative.startsWith(`..${path.sep}`)) {
+    return null;
+  }
+  return relative.split(path.sep).join('/');
+}
+
+function parseCommittedSourceScope(contents, label) {
+  const entries = contents.split(/\r?\n/).filter(Boolean);
+  if (entries.length === 0) fail(`Platform source scope is empty at ${label}`);
+  const seen = new Set();
+  for (const entry of entries) {
+    if (!entry.startsWith('seed/')) fail(`Platform source scope escaped seed/ at ${label}`);
+    const remotePath = entry.slice('seed/'.length);
+    validateRelativePath(entry.endsWith('/') ? remotePath.slice(0, -1) : remotePath);
+    if (seen.has(entry)) fail(`Platform source scope contains a duplicate entry at ${label}: ${entry}`);
+    seen.add(entry);
+  }
+  return entries;
+}
+
+function committedSourceScope(repo, revision, scopePath) {
+  const treeEntry = git(repo, ['ls-tree', revision, '--', scopePath]);
+  if (!treeEntry) return null;
+  const match = /^(100644|100755) blob [0-9a-f]{40,64}\t(.+)$/u.exec(treeEntry);
+  if (!match || match[2] !== scopePath) {
+    fail(`Platform source scope is not a regular Git file at ${revision}`);
+  }
+  return parseCommittedSourceScope(git(repo, ['show', `${revision}:${scopePath}`]), revision);
+}
+
+function scopeEntryCoveredByTarget(entry, targetScope) {
+  return targetScope.some((targetEntry) =>
+    targetEntry.endsWith('/') ? entry.startsWith(targetEntry) : entry === targetEntry,
+  );
+}
+
+function scopeIsAdditiveCompatible(ancestorScope, targetScope) {
+  return ancestorScope.every((entry) => scopeEntryCoveredByTarget(entry, targetScope));
+}
+
+export function buildReleaseArtifact({ repo, revision, scopeFile, output, validate = true }) {
+  const resolvedRepo = fs.realpathSync(repo);
+  const commit = git(resolvedRepo, ['rev-parse', '--verify', `${revision}^{commit}`]);
+  const supportedScope = readSourceScope(scopeFile);
+  const scopePath = repositoryScopePath(resolvedRepo, scopeFile);
+  const sourceScope = scopePath ? committedSourceScope(resolvedRepo, commit, scopePath) : supportedScope;
+  if (sourceScope == null) fail(`Platform source scope is missing at target revision ${commit}`);
+  if (JSON.stringify(sourceScope) !== JSON.stringify(supportedScope)) {
+    fail(`Platform source scope at target revision ${commit} differs from the supported atomic release unit`);
+  }
+  const target = manifestAtRevision(resolvedRepo, commit, sourceScope);
+  assertValidTarget(target);
+  const targetPackages = packageRecords(target);
+
+  const acceptedBaselines = new Set();
+  for (const ancestor of git(resolvedRepo, ['rev-list', commit]).split('\n').filter(Boolean)) {
+    const ancestorScope = scopePath ? committedSourceScope(resolvedRepo, ancestor, scopePath) : sourceScope;
+    if (ancestorScope == null || !scopeIsAdditiveCompatible(ancestorScope, sourceScope)) continue;
+    const manifest = manifestAtRevision(resolvedRepo, ancestor, ancestorScope);
+    if (packageRecords(manifest) === targetPackages) {
+      acceptedBaselines.add(`sha256:${manifestDigest(manifest)}`);
+    }
+  }
+
+  const stage = fs.mkdtempSync(path.join(os.tmpdir(), 'emptyos-release-build.'));
+  try {
+    const archive = path.join(stage, 'source.tar');
+    const exported = path.join(stage, 'source');
+    fs.mkdirSync(exported);
+    const sourceFiles = target.files.map((entry) => `seed/${entry.path}`);
+    run('git', ['-C', resolvedRepo, 'archive', '--format=tar', '--output', archive, commit, '--', ...sourceFiles], {
+      quiet: true,
+    });
+    run('tar', ['-xf', archive, '-C', exported], { quiet: true });
+
+    const seed = path.join(exported, 'seed');
+    if (validate) {
+      run('npm', ['ci'], { cwd: seed, timeout: 180_000, quiet: true });
+      run('npm', ['test'], { cwd: seed, timeout: 180_000, quiet: true });
+    }
+
+    const files = target.files.map((entry) => {
+      const contents = fs.readFileSync(path.join(seed, ...entry.path.split('/')));
+      return {
+        ...entry,
+        sha256: crypto.createHash('sha256').update(contents).digest('hex'),
+        data: contents.toString('base64'),
+      };
+    });
+    const artifact = normalizeReleaseArtifact({
+      version: RELEASE_ARTIFACT_VERSION,
+      component: RELEASE_ARTIFACT_COMPONENT,
+      updateProtocol: UPDATE_PROTOCOL_VERSION,
+      release: `sha256:${manifestDigest(target)}`,
+      acceptedBaselines: [...acceptedBaselines],
+      target,
+      files,
+    });
+    fs.mkdirSync(path.dirname(path.resolve(output)), { recursive: true });
+    fs.writeFileSync(output, serializeReleaseArtifact(artifact), { mode: 0o644 });
+    return { artifact, commit, artifactSha256: releaseArtifactDigest(artifact) };
+  } finally {
+    fs.rmSync(stage, { recursive: true, force: true });
+  }
+}
+
+export function buildReleasePackage({ repo, revision, scopeFile, outputDirectory, validate = true }) {
+  const destination = path.resolve(outputDirectory);
+  if (fs.existsSync(destination)) fail(`Platform release package destination already exists: ${destination}`);
+  const parent = path.dirname(destination);
+  fs.mkdirSync(parent, { recursive: true });
+  const stage = fs.mkdtempSync(path.join(parent, `.${path.basename(destination)}.`));
+  try {
+    const temporaryArtifact = path.join(stage, 'release.json');
+    const result = buildReleaseArtifact({ repo, revision, scopeFile, output: temporaryArtifact, validate });
+    const releases = path.join(stage, 'releases');
+    fs.mkdirSync(releases, { mode: 0o755 });
+    const artifactName = `${result.artifactSha256}.json`;
+    const artifactFile = path.join(releases, artifactName);
+    fs.renameSync(temporaryArtifact, artifactFile);
+    const catalog = path.join(stage, 'catalog.json');
+    fs.writeFileSync(catalog, `${JSON.stringify({
+      version: 1,
+      component: 'emptyos-platform-catalog',
+      updateProtocol: UPDATE_PROTOCOL_VERSION,
+      release: {
+        id: result.artifact.release,
+        url: `./releases/${artifactName}`,
+        sha256: result.artifactSha256,
+      },
+    }, null, 2)}\n`, { mode: 0o644 });
+    fs.renameSync(stage, destination);
+    return {
+      ...result,
+      outputDirectory: destination,
+      artifactFile: path.join(destination, 'releases', artifactName),
+      catalog: path.join(destination, 'catalog.json'),
+      artifactRelativePath: `releases/${artifactName}`,
+    };
+  } catch (error) {
+    fs.rmSync(stage, { recursive: true, force: true });
+    throw error;
+  }
+}
+
+export function packageReleaseArtifact({ artifactFile, outputDirectory }) {
+  const source = path.resolve(artifactFile);
+  const artifact = parseReleaseArtifact(source);
+  const artifactBytes = fs.readFileSync(source);
+  const destination = path.resolve(outputDirectory);
+  if (fs.existsSync(destination)) fail(`Platform release package destination already exists: ${destination}`);
+  const parent = path.dirname(destination);
+  fs.mkdirSync(parent, { recursive: true });
+  const stage = fs.mkdtempSync(path.join(parent, `.${path.basename(destination)}.`));
+  try {
+    const releases = path.join(stage, 'releases');
+    fs.mkdirSync(releases, { mode: 0o755 });
+    const artifactName = `${artifact.artifactSha256}.json`;
+    const stagedArtifact = path.join(releases, artifactName);
+    fs.writeFileSync(stagedArtifact, artifactBytes, { flag: 'wx', mode: 0o644 });
+    const catalog = path.join(stage, 'catalog.json');
+    fs.writeFileSync(catalog, `${JSON.stringify({
+      version: 1,
+      component: 'emptyos-platform-catalog',
+      updateProtocol: UPDATE_PROTOCOL_VERSION,
+      release: {
+        url: `./releases/${artifactName}`,
+        sha256: artifact.artifactSha256,
+      },
+    }, null, 2)}\n`, { flag: 'wx', mode: 0o644 });
+    fs.renameSync(stage, destination);
+    return {
+      artifact,
+      artifactSha256: artifact.artifactSha256,
+      outputDirectory: destination,
+      artifactFile: path.join(destination, 'releases', artifactName),
+      catalog: path.join(destination, 'catalog.json'),
+      artifactRelativePath: `releases/${artifactName}`,
+    };
+  } catch (error) {
+    fs.rmSync(stage, { recursive: true, force: true });
+    throw error;
+  }
+}

package/lib/vendor/platform-release-channel.mjs

@@ -0,0 +1,91 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { parseReleaseArtifactBytes } from './platform-release-artifact.mjs';
+
+export const PLATFORM_RELEASE_PUBLIC_ORIGIN = 'https://release.emptyos.com/platform/v1/';
+export const PLATFORM_RELEASE_CATALOG_URL = new URL('catalog.json', PLATFORM_RELEASE_PUBLIC_ORIGIN).href;
+
+const ARTIFACT_PATH = /^\.\/releases\/([0-9a-f]{64})\.json$/;
+const RELEASE_ID = /^sha256:[0-9a-f]{64}$/;
+
+export function parseReleaseCatalogBytes(catalogBytes, { requireId = false } = {}) {
+  let catalog;
+  try {
+    catalog = JSON.parse(catalogBytes.toString('utf8'));
+  } catch (error) {
+    throw new Error(`Invalid platform release catalog: ${error.message}`);
+  }
+  if (!catalog || typeof catalog !== 'object' || Array.isArray(catalog) ||
+      catalog.version !== 1 || catalog.component !== 'emptyos-platform-catalog' ||
+      catalog.updateProtocol !== 1 || !catalog.release ||
+      typeof catalog.release !== 'object' || Array.isArray(catalog.release)) {
+    throw new Error('Invalid platform release catalog');
+  }
+  const artifactSha256 = String(catalog.release.sha256 ?? '');
+  const releaseKeys = Object.keys(catalog.release);
+  const legacyCatalog = releaseKeys.length === 2 && releaseKeys[0] === 'url' && releaseKeys[1] === 'sha256';
+  const identifiedCatalog = releaseKeys.length === 3 && releaseKeys[0] === 'id' &&
+    releaseKeys[1] === 'url' && releaseKeys[2] === 'sha256';
+  if (!legacyCatalog && !identifiedCatalog) throw new Error('Invalid platform release catalog release shape');
+  if (requireId && !identifiedCatalog) {
+    throw new Error('Platform release catalog does not identify its resident release');
+  }
+  if (identifiedCatalog && (typeof catalog.release.id !== 'string' || !RELEASE_ID.test(catalog.release.id))) {
+    throw new Error('Platform release catalog has an invalid release id');
+  }
+  const match = ARTIFACT_PATH.exec(String(catalog.release.url ?? ''));
+  if (!match || match[1] !== artifactSha256) {
+    throw new Error('Platform release catalog must reference its content-addressed artifact');
+  }
+  const expectedCatalog = `${JSON.stringify({
+    version: 1,
+    component: 'emptyos-platform-catalog',
+    updateProtocol: 1,
+    release: {
+      ...(identifiedCatalog ? { id: catalog.release.id } : {}),
+      url: catalog.release.url,
+      sha256: artifactSha256,
+    },
+  }, null, 2)}\n`;
+  if (!catalogBytes.equals(Buffer.from(expectedCatalog))) throw new Error('Platform release catalog is not canonical');
+  return catalog;
+}
+
+export function readReleasePackage(directory) {
+  const root = fs.realpathSync(directory);
+  const catalogFile = path.join(root, 'catalog.json');
+  const catalogBytes = readRegularFile(catalogFile, 1024 * 1024);
+  const catalog = parseReleaseCatalogBytes(catalogBytes);
+  const artifactSha256 = catalog.release.sha256;
+  const identifiedCatalog = Object.hasOwn(catalog.release, 'id');
+
+  const artifactRelativePath = `releases/${artifactSha256}.json`;
+  const artifactFile = path.join(root, artifactRelativePath);
+  const artifactBytes = readRegularFile(artifactFile, 64 * 1024 * 1024);
+  const observedSha256 = crypto.createHash('sha256').update(artifactBytes).digest('hex');
+  if (observedSha256 !== artifactSha256) throw new Error('Platform release artifact digest does not match its catalog');
+  const artifact = parseReleaseArtifactBytes(artifactBytes, artifactFile);
+  if (identifiedCatalog && catalog.release.id !== artifact.release) {
+    throw new Error('Platform release catalog id does not match its artifact release');
+  }
+  return {
+    root,
+    catalog,
+    catalogFile,
+    catalogBytes,
+    artifact,
+    artifactFile,
+    artifactBytes,
+    artifactSha256,
+    artifactRelativePath,
+  };
+}
+
+function readRegularFile(file, maximumBytes) {
+  const stat = fs.lstatSync(file);
+  if (!stat.isFile() || stat.isSymbolicLink()) throw new Error(`Release package entry is not a regular file: ${file}`);
+  if (stat.size > maximumBytes) throw new Error(`Release package entry exceeds ${maximumBytes} bytes: ${file}`);
+  return fs.readFileSync(file);
+}

package/lib/vendor/platform-release.mjs

@@ -0,0 +1,368 @@
+import { spawnSync } from 'node:child_process';
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const PLATFORM_COMPONENT = 'emptyos-platform';
+export const BASELINE_FILE = 'platform-release.json';
+
+export const PLATFORM_SCOPE = Object.freeze([
+  '.agents/skills/build-emptyos-things/',
+  '.agents/skills/operate-emptyos-computer/',
+  '.gitignore',
+  'EMPTY.md',
+  'README.md',
+  'cli/',
+  'gateway/',
+  'lib/',
+  'package-lock.json',
+  'package.json',
+  'test/build-emptyos-things-skill.test.js',
+  'test/cli.test.js',
+  'test/extensions.test.js',
+  'test/gateway.test.js',
+  'test/git-changes.test.js',
+  'test/helpers.js',
+  'test/lib.test.js',
+  'test/skill.test.js',
+  'test/thing-import.test.js',
+  'web/',
+]);
+
+// Protocol-v1 artifacts remain valid against the semantic minimum that existed
+// when the protocol was introduced. Growing this list would invalidate already
+// published immutable artifacts; removing or renaming one of these paths needs
+// a new update protocol.
+const PROTOCOL_V1_REQUIRED_TARGET_PATHS = Object.freeze([
+  '.agents/skills/operate-emptyos-computer/SKILL.md',
+  'EMPTY.md',
+  'cli/empty.js',
+  'gateway/server.js',
+  'lib/manifests.js',
+  'package-lock.json',
+  'package.json',
+  'test/skill.test.js',
+  'web/index.html',
+]);
+const REQUIRED_TARGET_PATHS = Object.freeze([
+  ...PROTOCOL_V1_REQUIRED_TARGET_PATHS,
+  '.agents/skills/build-emptyos-things/SKILL.md',
+  'test/build-emptyos-things-skill.test.js',
+]);
+const PACKAGE_PATHS = new Set(['package.json', 'package-lock.json']);
+const SAFE_PATH = /^(?!\/)(?!.*(?:^|\/)\.\.(?:\/|$))[A-Za-z0-9._/-]+$/;
+const ALLOWED_MODES = new Set(['100644', '100755']);
+
+function fail(message) {
+  throw new Error(message);
+}
+
+function run(command, args, { cwd, timeout = 30_000 } = {}) {
+  const result = spawnSync(command, args, {
+    cwd,
+    encoding: 'utf8',
+    env: { ...process.env, LC_ALL: 'C' },
+    timeout,
+  });
+  if (result.error) throw result.error;
+  if (result.status !== 0) {
+    const detail = (result.stderr || result.stdout || '').trim();
+    fail(`\`${command} ${args.join(' ')}\` failed${detail ? `: ${detail}` : ''}`);
+  }
+  return result.stdout.trimEnd();
+}
+
+export function tryRun(command, args, { cwd, timeout = 30_000 } = {}) {
+  const result = spawnSync(command, args, {
+    cwd,
+    encoding: 'utf8',
+    env: { ...process.env, LC_ALL: 'C' },
+    timeout,
+  });
+  if (result.error) throw result.error;
+  return result;
+}
+
+export function git(repo, args, options = {}) {
+  return run('git', ['-C', repo, ...args], options);
+}
+
+export function validateRelativePath(relativePath) {
+  const segments = String(relativePath).split('/');
+  if (!SAFE_PATH.test(relativePath) || relativePath.length > 4096 ||
+      segments.some((segment) => segment === '' || segment === '.' || segment === '..' ||
+        segment === '.git' || segment.length > 255)) {
+    fail(`Unsafe platform path: ${JSON.stringify(relativePath)}`);
+  }
+  return relativePath;
+}
+
+export function pathIsCovered(relativePath, scope = PLATFORM_SCOPE) {
+  return scope.some((entry) =>
+    entry.endsWith('/') ? relativePath.startsWith(entry) : relativePath === entry,
+  );
+}
+
+export function readSourceScope(scopeFile) {
+  const entries = fs.readFileSync(scopeFile, 'utf8').split(/\r?\n/).filter(Boolean);
+  const expected = PLATFORM_SCOPE.map((entry) => `seed/${entry}`);
+  if (JSON.stringify(entries) !== JSON.stringify(expected)) {
+    fail('Platform source scope differs from the supported atomic release unit');
+  }
+  return entries;
+}
+
+export function readRemoteScope(scopeFile) {
+  const entries = fs.readFileSync(scopeFile, 'utf8').split(/\r?\n/).filter(Boolean);
+  if (JSON.stringify(entries) !== JSON.stringify(PLATFORM_SCOPE)) {
+    fail('Remote platform scope differs from the supported atomic release unit');
+  }
+  return entries;
+}
+
+function normalizeRecord(record) {
+  const normalized = {
+    path: validateRelativePath(record.path),
+    mode: String(record.mode),
+    blob: String(record.blob),
+  };
+  if (!ALLOWED_MODES.has(normalized.mode)) {
+    fail(`Unsupported mode ${normalized.mode} for ${normalized.path}`);
+  }
+  if (!/^[0-9a-f]{40,64}$/.test(normalized.blob)) {
+    fail(`Invalid blob id for ${normalized.path}`);
+  }
+  if (!pathIsCovered(normalized.path)) {
+    fail(`Platform file escaped the declared scope: ${normalized.path}`);
+  }
+  return normalized;
+}
+
+export function normalizeManifest(files) {
+  const sorted = files.map(normalizeRecord).sort((left, right) =>
+    left.path < right.path ? -1 : left.path > right.path ? 1 : 0,
+  );
+  const seen = new Set();
+  for (let index = 0; index < sorted.length; index += 1) {
+    const file = sorted[index];
+    if (seen.has(file.path)) fail(`Duplicate platform path: ${file.path}`);
+    const segments = file.path.split('/');
+    for (let length = 1; length < segments.length; length += 1) {
+      const parent = segments.slice(0, length).join('/');
+      if (seen.has(parent)) fail(`Conflicting platform paths: ${parent} and ${file.path}`);
+    }
+    seen.add(file.path);
+  }
+  return { version: 1, component: PLATFORM_COMPONENT, files: sorted };
+}
+
+export function serializeManifest(manifest) {
+  return `${JSON.stringify(normalizeManifest(manifest.files), null, 2)}\n`;
+}
+
+export function parseManifest(file) {
+  const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+  if (parsed?.version !== 1 || parsed?.component !== PLATFORM_COMPONENT || !Array.isArray(parsed.files)) {
+    fail(`Invalid platform manifest: ${file}`);
+  }
+  return normalizeManifest(parsed.files);
+}
+
+export function manifestDigest(manifest) {
+  return crypto.createHash('sha256').update(serializeManifest(manifest)).digest('hex');
+}
+
+export function releaseId(manifest) {
+  return `sha256:${manifestDigest(manifest)}`;
+}
+
+function parseTreeLine(line, prefix = '') {
+  const match = /^(100644|100755) blob ([0-9a-f]{40,64})\t(.+)$/.exec(line);
+  if (!match) fail(`Unsupported Git tree entry: ${line}`);
+  const relativePath = prefix && match[3].startsWith(prefix)
+    ? match[3].slice(prefix.length)
+    : match[3];
+  return { path: relativePath, mode: match[1], blob: match[2] };
+}
+
+export function manifestAtRevision(repo, revision, sourceScope) {
+  const output = git(repo, ['ls-tree', '-r', revision, '--', ...sourceScope]);
+  const files = output ? output.split('\n').map((line) => parseTreeLine(line, 'seed/')) : [];
+  return normalizeManifest(files);
+}
+
+function parseIndexLine(line) {
+  const match = /^(100644|100755) ([0-9a-f]{40,64}) 0\t(.+)$/.exec(line);
+  if (!match) fail(`Unsupported Git index entry: ${line}`);
+  return { path: match[3], mode: match[1], blob: match[2] };
+}
+
+export function manifestFromIndex(repo, scope = PLATFORM_SCOPE) {
+  const output = git(repo, ['ls-files', '--stage', '--', ...scope]);
+  const files = output ? output.split('\n').map(parseIndexLine) : [];
+  return normalizeManifest(files);
+}
+
+function fileMode(stat) {
+  return stat.mode & 0o111 ? '100755' : '100644';
+}
+
+function listWorktreeFiles(root, relativePath, output) {
+  const absolutePath = path.join(root, relativePath);
+  if (!fs.existsSync(absolutePath)) return;
+  const stat = fs.lstatSync(absolutePath);
+  if (stat.isSymbolicLink()) fail(`Symlink is not allowed in platform scope: ${relativePath}`);
+  if (stat.isFile()) {
+    output.push({
+      path: relativePath,
+      mode: fileMode(stat),
+      blob: git(root, ['hash-object', '--no-filters', '--', absolutePath]),
+    });
+    return;
+  }
+  if (!stat.isDirectory()) fail(`Unsupported platform entry: ${relativePath}`);
+  for (const name of fs.readdirSync(absolutePath).sort()) {
+    listWorktreeFiles(root, path.posix.join(relativePath.replace(/\/$/, ''), name), output);
+  }
+}
+
+export function manifestFromWorktree(repo, scope = PLATFORM_SCOPE) {
+  const files = [];
+  for (const entry of scope) listWorktreeFiles(repo, entry, files);
+  return normalizeManifest(files);
+}
+
+export function assertManifestEqual(left, right, message = 'platform manifests differ') {
+  if (serializeManifest(left) !== serializeManifest(right)) fail(message);
+}
+
+function assertRequiredTargetPaths(manifest, requiredPaths, message) {
+  const paths = new Set(manifest.files.map((file) => file.path));
+  for (const required of requiredPaths) {
+    if (!paths.has(required)) fail(`${message}: ${required}`);
+  }
+}
+
+export function assertValidProtocolTarget(manifest) {
+  assertRequiredTargetPaths(
+    manifest,
+    PROTOCOL_V1_REQUIRED_TARGET_PATHS,
+    'platform protocol v1 target is missing required path',
+  );
+}
+
+export function assertValidTarget(manifest) {
+  assertRequiredTargetPaths(manifest, REQUIRED_TARGET_PATHS, 'platform target is missing required path');
+}
+
+export function recordsByPath(manifest) {
+  return new Map(manifest.files.map((file) => [file.path, file]));
+}
+
+export function recordsEqual(left, right) {
+  if (!left || !right) return left == null && right == null;
+  return left.mode === right.mode && left.blob === right.blob;
+}
+
+export function classifyRelease(baseline, local, target) {
+  assertValidProtocolTarget(target);
+  const baselineByPath = recordsByPath(baseline);
+  const localByPath = recordsByPath(local);
+  const targetByPath = recordsByPath(target);
+  const paths = [...new Set([
+    ...baselineByPath.keys(),
+    ...localByPath.keys(),
+    ...targetByPath.keys(),
+  ])].sort();
+  const entries = [];
+
+  for (const relativePath of paths) {
+    const base = baselineByPath.get(relativePath) ?? null;
+    const current = localByPath.get(relativePath) ?? null;
+    const incoming = targetByPath.get(relativePath) ?? null;
+    let action;
+    if (recordsEqual(current, incoming)) action = 'already-target';
+    else if (recordsEqual(current, base)) action = incoming ? 'install-target' : 'delete-target';
+    else if (recordsEqual(incoming, base)) action = 'preserve-local';
+    else action = 'reconcile';
+    entries.push({ path: relativePath, action, baseline: base, local: current, target: incoming });
+  }
+
+  const targetChangedPackages = entries.filter((entry) =>
+    PACKAGE_PATHS.has(entry.path) && !recordsEqual(entry.baseline, entry.target),
+  );
+  return {
+    release: releaseId(target),
+    baseline: releaseId(baseline),
+    entries,
+    conflicts: entries.filter((entry) => entry.action === 'reconcile'),
+    targetChangedPackages,
+  };
+}
+
+export function planLines(plan) {
+  const labels = {
+    'already-target': 'current ',
+    'install-target': 'update  ',
+    'delete-target': 'delete  ',
+    'preserve-local': 'preserve',
+    reconcile: 'resolve ',
+  };
+  return plan.entries
+    .filter((entry) => entry.action !== 'already-target')
+    .map((entry) => `${labels[entry.action]} ${entry.path}`);
+}
+
+export function baselineDocument(manifest, { appliedCommit = null } = {}) {
+  if (appliedCommit != null && !/^[0-9a-f]{40,64}$/.test(appliedCommit)) {
+    fail('Invalid applied commit in platform baseline');
+  }
+  const baseline = normalizeManifest(manifest.files);
+  return {
+    version: 1,
+    component: PLATFORM_COMPONENT,
+    release: releaseId(baseline),
+    appliedCommit,
+    baseline,
+  };
+}
+
+export function serializeBaseline(manifest, options = {}) {
+  return `${JSON.stringify(baselineDocument(manifest, options), null, 2)}\n`;
+}
+
+export function parseBaseline(file) {
+  const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+  if (parsed?.version !== 1 || parsed?.component !== PLATFORM_COMPONENT ||
+      !parsed.baseline || !Array.isArray(parsed.baseline.files)) {
+    fail(`Invalid platform baseline: ${file}`);
+  }
+  const baseline = normalizeManifest(parsed.baseline.files);
+  if (parsed.release !== releaseId(baseline)) fail('Platform baseline release digest mismatch');
+  if (parsed.appliedCommit != null && !/^[0-9a-f]{40,64}$/.test(parsed.appliedCommit)) {
+    fail('Platform baseline has an invalid applied commit');
+  }
+  return { ...parsed, baseline };
+}
+
+export function writeFileAtomic(destination, contents, mode = 0o600) {
+  fs.mkdirSync(path.dirname(destination), { recursive: true, mode: 0o700 });
+  const temporary = path.join(
+    path.dirname(destination),
+    `.${path.basename(destination)}.${process.pid}.${crypto.randomBytes(6).toString('hex')}`,
+  );
+  fs.writeFileSync(temporary, contents, { mode, flag: 'wx' });
+  fs.renameSync(temporary, destination);
+}
+
+export function writeBaseline(destination, manifest, options = {}) {
+  writeFileAtomic(destination, serializeBaseline(manifest, options));
+}
+
+export function changedPaths(left, right) {
+  const leftByPath = recordsByPath(left);
+  const rightByPath = recordsByPath(right);
+  return [...new Set([...leftByPath.keys(), ...rightByPath.keys()])]
+    .sort()
+    .filter((relativePath) => !recordsEqual(leftByPath.get(relativePath), rightByPath.get(relativePath)));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@emptyos/client",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "module",
   "description": "External EmptyOS client",
   "license": "MIT",