@vantran-se/openchamber-web 1.24.4 → 2.0.1

package/server/lib/spaces/labels.js

@@ -0,0 +1,234 @@
+import crypto from 'node:crypto';
+
+import { SpaceError } from './errors.js';
+
+export const LABEL_MARKER = 'openchamber.space';
+const LABEL_ID = 'openchamber.space.id';
+const LABEL_ROLE = 'openchamber.space.role';
+export const LABEL_OWNER = 'openchamber.space.owner';
+const LABEL_PROJECT = 'openchamber.space.project';
+const LABEL_NAME = 'openchamber.space.name';
+const LABEL_CREATED = 'openchamber.space.created';
+
+const MARKER_VALUE = 'true';
+
+export const ROLE_SPACE = 'space';
+export const ROLE_SETUP = 'setup';
+export const ROLE_NETWORK = 'network';
+export const ROLE_VOLUME = 'volume';
+// Since stage 2 every space also has a gatekeeper container and an outer network of its own.
+// The inner network keeps the plain `network` role, so nothing that existed changes name.
+export const ROLE_GATEKEEPER = 'gatekeeper';
+export const ROLE_OUTER_NETWORK = 'outer-network';
+const ROLES = new Set([ROLE_SPACE, ROLE_SETUP, ROLE_NETWORK, ROLE_VOLUME, ROLE_GATEKEEPER, ROLE_OUTER_NETWORK]);
+
+// The tools volume and its two one-shot containers belong to an owner, not to a space.
+// They carry no space id, so parseSpaceLabels returns null for them and `list` and `remove` pass them by.
+const LABEL_TOOLS_KEY = 'openchamber.space.tools.key';
+const LABEL_TOOLS_DESCRIPTION = 'openchamber.space.tools.description';
+export const ROLE_TOOLS = 'tools';
+export const ROLE_TOOLS_FILL = 'tools-fill';
+export const ROLE_TOOLS_CHECK = 'tools-check';
+const TOOLS_ROLES = new Set([ROLE_TOOLS, ROLE_TOOLS_FILL, ROLE_TOOLS_CHECK]);
+const TOOLS_KEY_PATTERN = /^[0-9a-f]{16}$/;
+
+const SPACE_ID_PATTERN = /^[0-9a-f]{12}$/;
+// The owner travels inside `--filter label=key=value`, so it stays a plain token.
+const OWNER_PATTERN = /^[A-Za-z0-9._-]{1,64}$/;
+const PROJECT_PATTERN = /^[0-9a-f]{16}$/;
+const SUFFIX_PATTERN = /^[a-z0-9]{1,16}$/;
+// C0 controls, DEL, NEL, and the Unicode line and paragraph separators.
+const CONTROL_CHARACTERS = /[\x00-\x1f\x7f\x85\u2028\u2029]/;
+const MAX_NAME_LENGTH = 100;
+
+export const createSpaceId = () => crypto.randomBytes(6).toString('hex');
+
+export const isSpaceId = (value) => SPACE_ID_PATTERN.test(value);
+
+export function requireSpaceId(value) {
+  if (!isSpaceId(value)) {
+    throw new SpaceError('invalid_space_id', 'A space id is 12 lowercase hex characters');
+  }
+  return value;
+}
+
+const isOwner = (value) => OWNER_PATTERN.test(value ?? '');
+
+export function requireOwner(value) {
+  if (!isOwner(value)) {
+    throw new SpaceError('invalid_owner', 'The installation id may hold only letters, digits, dots, dashes and underscores, 64 at most');
+  }
+  return value;
+}
+
+export function normalizeSpaceName(value) {
+  const name = String(value ?? '').trim();
+  if (name.length === 0 || name.length > MAX_NAME_LENGTH || CONTROL_CHARACTERS.test(name)) {
+    throw new SpaceError('invalid_space_name', `A space name is 1 to ${MAX_NAME_LENGTH} characters on one line`);
+  }
+  return name;
+}
+
+export function hashProjectDirectory(directory) {
+  const text = String(directory ?? '');
+  if (text.trim().length === 0) {
+    throw new SpaceError('invalid_project_directory', 'A space needs the project directory it was created for');
+  }
+  return crypto.createHash('sha256').update(text).digest('hex').slice(0, 16);
+}
+
+export function spaceResourcePrefix(spaceId) {
+  return `openchamber-space-${requireSpaceId(spaceId)}-`;
+}
+
+export function spaceResourceName(spaceId, role, suffix = '') {
+  if (!ROLES.has(role)) {
+    throw new SpaceError('invalid_role', `Unknown space resource role '${role}'`);
+  }
+  if (suffix === '') {
+    return `${spaceResourcePrefix(spaceId)}${role}`;
+  }
+  if (!SUFFIX_PATTERN.test(suffix)) {
+    throw new SpaceError('invalid_resource_suffix', 'A resource suffix is 1 to 16 lowercase letters or digits');
+  }
+  return `${spaceResourcePrefix(spaceId)}${role}-${suffix}`;
+}
+
+export function buildSpaceLabels({ id, role, owner, project, name, created }) {
+  if (!ROLES.has(role)) {
+    throw new SpaceError('invalid_role', `Unknown space resource role '${role}'`);
+  }
+  if (!PROJECT_PATTERN.test(project)) {
+    throw new SpaceError('invalid_project', 'A project label is the 16 character hash from hashProjectDirectory');
+  }
+  if (Number.isNaN(Date.parse(created))) {
+    throw new SpaceError('invalid_created', 'A creation time is an ISO date string');
+  }
+  return {
+    [LABEL_MARKER]: MARKER_VALUE,
+    [LABEL_ID]: requireSpaceId(id),
+    [LABEL_ROLE]: role,
+    [LABEL_OWNER]: requireOwner(owner),
+    [LABEL_PROJECT]: project,
+    [LABEL_NAME]: normalizeSpaceName(name),
+    [LABEL_CREATED]: created,
+  };
+}
+
+export const labelArgs = (labels) => Object.entries(labels).flatMap(([key, value]) => ['--label', `${key}=${value}`]);
+
+/** `--filter` arguments that select this owner's resources, optionally one space. */
+export function labelFilterArgs({ owner, spaceId = null }) {
+  const filters = ['--filter', `label=${LABEL_MARKER}=${MARKER_VALUE}`, '--filter', `label=${LABEL_OWNER}=${requireOwner(owner)}`];
+  if (spaceId !== null) {
+    filters.push('--filter', `label=${LABEL_ID}=${requireSpaceId(spaceId)}`);
+  }
+  return filters;
+}
+
+/**
+ * Reads our labels from the label object of a `docker inspect` entry.
+ * Returns null for anything that is not a well-formed resource of ours.
+ */
+export function parseSpaceLabels(labels) {
+  if (!labels || labels[LABEL_MARKER] !== MARKER_VALUE) {
+    return null;
+  }
+  const id = labels[LABEL_ID];
+  const role = labels[LABEL_ROLE];
+  const owner = labels[LABEL_OWNER];
+  if (!isSpaceId(id) || !ROLES.has(role) || !isOwner(owner)) {
+    return null;
+  }
+  return {
+    id,
+    role,
+    owner,
+    project: labels[LABEL_PROJECT] ?? '',
+    name: labels[LABEL_NAME] ?? '',
+    created: labels[LABEL_CREATED] ?? '',
+  };
+}
+
+const isToolsKey = (value) => TOOLS_KEY_PATTERN.test(value ?? '');
+
+export function requireToolsKey(value) {
+  if (!isToolsKey(value)) {
+    throw new SpaceError('invalid_tools_key', 'A tools key is 16 lowercase hex characters');
+  }
+  return value;
+}
+
+/** One volume per owner and per tools content. A one-shot container adds its role as a suffix. */
+export function toolsResourceName(owner, key, role = ROLE_TOOLS) {
+  if (!TOOLS_ROLES.has(role)) {
+    throw new SpaceError('invalid_role', `Unknown tools resource role '${role}'`);
+  }
+  const volume = `openchamber-tools-${requireOwner(owner)}-${requireToolsKey(key)}`;
+  return role === ROLE_TOOLS ? volume : `${volume}-${role.slice(ROLE_TOOLS.length + 1)}`;
+}
+
+/** The key inside a tools volume name of this owner, or null for any other name. */
+export function toolsKeyFromVolumeName(name, owner) {
+  const prefix = `openchamber-tools-${requireOwner(owner)}-`;
+  const text = String(name ?? '');
+  const key = text.slice(prefix.length);
+  return text.startsWith(prefix) && isToolsKey(key) ? key : null;
+}
+
+export function buildToolsLabels({ role, owner, key, description, created }) {
+  if (!TOOLS_ROLES.has(role)) {
+    throw new SpaceError('invalid_role', `Unknown tools resource role '${role}'`);
+  }
+  if (Number.isNaN(Date.parse(created))) {
+    throw new SpaceError('invalid_created', 'A creation time is an ISO date string');
+  }
+  // Same rule as a space name: one line, so it survives as a label value.
+  const text = String(description ?? '').trim();
+  if (text.length === 0 || text.length > MAX_NAME_LENGTH || CONTROL_CHARACTERS.test(text)) {
+    throw new SpaceError('invalid_tools_description', `A tools description is 1 to ${MAX_NAME_LENGTH} characters on one line`);
+  }
+  return {
+    [LABEL_MARKER]: MARKER_VALUE,
+    [LABEL_ROLE]: role,
+    [LABEL_OWNER]: requireOwner(owner),
+    [LABEL_TOOLS_KEY]: requireToolsKey(key),
+    [LABEL_TOOLS_DESCRIPTION]: text,
+    [LABEL_CREATED]: created,
+  };
+}
+
+/** `--filter` arguments that select this owner's tools resources, optionally of one role and of one key. */
+export function toolsLabelFilterArgs({ owner, role = null, key = null }) {
+  const filters = labelFilterArgs({ owner });
+  if (role !== null) {
+    filters.push('--filter', `label=${LABEL_ROLE}=${role}`);
+  }
+  if (key !== null) {
+    filters.push('--filter', `label=${LABEL_TOOLS_KEY}=${requireToolsKey(key)}`);
+  }
+  return filters;
+}
+
+/**
+ * Reads the tools labels from the label object of a `docker inspect` entry.
+ * Returns null for anything that is not a well-formed tools resource of ours.
+ */
+export function parseToolsLabels(labels) {
+  if (!labels || labels[LABEL_MARKER] !== MARKER_VALUE) {
+    return null;
+  }
+  const role = labels[LABEL_ROLE];
+  const owner = labels[LABEL_OWNER];
+  const key = labels[LABEL_TOOLS_KEY];
+  if (!TOOLS_ROLES.has(role) || !isOwner(owner) || !isToolsKey(key)) {
+    return null;
+  }
+  return {
+    role,
+    owner,
+    key,
+    description: labels[LABEL_TOOLS_DESCRIPTION] ?? '',
+    created: labels[LABEL_CREATED] ?? '',
+  };
+}

package/server/lib/spaces/labels.test.js

@@ -0,0 +1,219 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  buildSpaceLabels,
+  buildToolsLabels,
+  createSpaceId,
+  hashProjectDirectory,
+  isSpaceId,
+  labelArgs,
+  labelFilterArgs,
+  normalizeSpaceName,
+  parseSpaceLabels,
+  parseToolsLabels,
+  spaceResourceName,
+  toolsKeyFromVolumeName,
+  toolsLabelFilterArgs,
+  toolsResourceName,
+} from './labels.js';
+
+const ID = 'a1b2c3d4e5f6';
+const FIELDS = {
+  id: ID,
+  role: 'space',
+  owner: 'install-a',
+  project: hashProjectDirectory('/home/me/project'),
+  name: 'Fix login',
+  created: '2026-09-19T10:00:00.000Z',
+};
+
+describe('space ids', () => {
+  it('creates 12 lowercase hex characters, different each time', () => {
+    const first = createSpaceId();
+    expect(first).toMatch(/^[0-9a-f]{12}$/);
+    expect(createSpaceId()).not.toBe(first);
+  });
+
+  it.each(['', 'A1B2C3D4E5F6', 'a1b2c3d4e5f', 'a1b2c3d4e5f6a', '../../../etc', 'a1b2c3d4e5f6\n', undefined, null])('rejects %j', (value) => {
+    expect(isSpaceId(value)).toBe(false);
+  });
+});
+
+describe('hashProjectDirectory', () => {
+  it('is the first 16 hex characters of the sha256 of the directory', () => {
+    expect(hashProjectDirectory('/home/me/project')).toBe('225df3094012a213');
+    expect(hashProjectDirectory('/home/me/other')).not.toBe(hashProjectDirectory('/home/me/project'));
+  });
+
+  it('rejects an empty directory', () => {
+    expect(() => hashProjectDirectory('  ')).toThrow(expect.objectContaining({ code: 'invalid_project_directory' }));
+  });
+});
+
+describe('spaceResourceName', () => {
+  it('is deterministic per id, role and suffix', () => {
+    expect(spaceResourceName(ID, 'space')).toBe(`openchamber-space-${ID}-space`);
+    expect(spaceResourceName(ID, 'network')).toBe(`openchamber-space-${ID}-network`);
+    expect(spaceResourceName(ID, 'volume', 'work')).toBe(`openchamber-space-${ID}-volume-work`);
+  });
+
+  it('rejects a bad id, role or suffix', () => {
+    expect(() => spaceResourceName('nope', 'space')).toThrow(expect.objectContaining({ code: 'invalid_space_id' }));
+    expect(() => spaceResourceName(ID, 'gateway')).toThrow(expect.objectContaining({ code: 'invalid_role' }));
+    expect(() => spaceResourceName(ID, 'volume', '../x')).toThrow(expect.objectContaining({ code: 'invalid_resource_suffix' }));
+  });
+});
+
+describe('normalizeSpaceName', () => {
+  it('trims and keeps punctuation', () => {
+    expect(normalizeSpaceName('  Fix a=b, "c"  ')).toBe('Fix a=b, "c"');
+  });
+
+  it.each(['', '   ', 'two\nlines', 'x'.repeat(101), undefined, 'a\u2028b', 'a\u2029b', 'a\u0085b', 'a\u007fb'])('rejects %j', (value) => {
+    expect(() => normalizeSpaceName(value)).toThrow(expect.objectContaining({ code: 'invalid_space_name' }));
+  });
+});
+
+describe('buildSpaceLabels', () => {
+  it('builds every label under openchamber.space', () => {
+    expect(buildSpaceLabels(FIELDS)).toEqual({
+      'openchamber.space': 'true',
+      'openchamber.space.id': ID,
+      'openchamber.space.role': 'space',
+      'openchamber.space.owner': 'install-a',
+      'openchamber.space.project': FIELDS.project,
+      'openchamber.space.name': 'Fix login',
+      'openchamber.space.created': '2026-09-19T10:00:00.000Z',
+    });
+  });
+
+  it.each([
+    ['invalid_space_id', { id: 'nope' }],
+    ['invalid_role', { role: 'gateway' }],
+    ['invalid_owner', { owner: 'a b' }],
+    ['invalid_owner', { owner: 'a,openchamber.space.id=x' }],
+    ['invalid_project', { project: '/home/me/project' }],
+    ['invalid_space_name', { name: '' }],
+    ['invalid_created', { created: 'yesterday-ish' }],
+  ])('rejects with %s', (code, change) => {
+    expect(() => buildSpaceLabels({ ...FIELDS, ...change })).toThrow(expect.objectContaining({ code }));
+  });
+
+  it('turns into --label arguments and --filter arguments', () => {
+    expect(labelArgs({ a: '1', b: 'x=y' })).toEqual(['--label', 'a=1', '--label', 'b=x=y']);
+    expect(labelFilterArgs({ owner: 'install-a' })).toEqual([
+      '--filter', 'label=openchamber.space=true',
+      '--filter', 'label=openchamber.space.owner=install-a',
+    ]);
+    expect(labelFilterArgs({ owner: 'install-a', spaceId: ID })).toEqual([
+      '--filter', 'label=openchamber.space=true',
+      '--filter', 'label=openchamber.space.owner=install-a',
+      '--filter', `label=openchamber.space.id=${ID}`,
+    ]);
+  });
+});
+
+describe('parseSpaceLabels', () => {
+  it('round-trips a name with commas, equals signs and quotes', () => {
+    const name = 'Fix a=b, openchamber.space.id=ffffffffffff, "c"';
+    const labels = buildSpaceLabels({ ...FIELDS, name });
+
+    expect(parseSpaceLabels(labels)).toEqual({ ...FIELDS, name });
+  });
+
+  it.each([
+    ['no labels', null],
+    ['no marker', { 'openchamber.space.id': ID }],
+    ['a wrong marker value', { ...buildSpaceLabels(FIELDS), 'openchamber.space': 'yes' }],
+    ['a malformed id', { ...buildSpaceLabels(FIELDS), 'openchamber.space.id': 'A1' }],
+    ['an unknown role', { ...buildSpaceLabels(FIELDS), 'openchamber.space.role': 'gateway' }],
+    ['no owner', { ...buildSpaceLabels(FIELDS), 'openchamber.space.owner': undefined }],
+  ])('returns null for %s', (title, labels) => {
+    expect(parseSpaceLabels(labels)).toBeNull();
+  });
+
+  it('keeps a resource whose display labels are missing', () => {
+    const parsed = parseSpaceLabels({ 'openchamber.space': 'true', 'openchamber.space.id': ID, 'openchamber.space.role': 'volume', 'openchamber.space.owner': 'install-a' });
+    expect(parsed).toEqual({ id: ID, role: 'volume', owner: 'install-a', project: '', name: '', created: '' });
+  });
+});
+
+describe('tools labels and names', () => {
+  const KEY = '0123456789abcdef';
+  const TOOLS_FIELDS = { role: 'tools', owner: 'install-a', key: KEY, description: 'web 1.24.2, opencode 1.18.31', created: '2026-09-20T08:00:00.000Z' };
+
+  it('names the volume after the owner and the key, and a one-shot after the volume', () => {
+    expect(toolsResourceName('install-a', KEY)).toBe(`openchamber-tools-install-a-${KEY}`);
+    expect(toolsResourceName('install-a', KEY, 'tools-fill')).toBe(`openchamber-tools-install-a-${KEY}-fill`);
+    expect(toolsResourceName('install-a', KEY, 'tools-check')).toBe(`openchamber-tools-install-a-${KEY}-check`);
+  });
+
+  it('rejects a bad owner, key or role in a name', () => {
+    expect(() => toolsResourceName('a b', KEY)).toThrow(expect.objectContaining({ code: 'invalid_owner' }));
+    expect(() => toolsResourceName('install-a', '../x')).toThrow(expect.objectContaining({ code: 'invalid_tools_key' }));
+    expect(() => toolsResourceName('install-a', KEY, 'space')).toThrow(expect.objectContaining({ code: 'invalid_role' }));
+  });
+
+  it('reads the key back from a volume name of this owner only', () => {
+    expect(toolsKeyFromVolumeName(`openchamber-tools-install-a-${KEY}`, 'install-a')).toBe(KEY);
+    // An owner whose id is the start of another owner's id must not match that owner's volumes.
+    expect(toolsKeyFromVolumeName(`openchamber-tools-install-a-${KEY}`, 'install')).toBeNull();
+    expect(toolsKeyFromVolumeName(`openchamber-tools-install-b-${KEY}`, 'install-a')).toBeNull();
+    expect(toolsKeyFromVolumeName(`openchamber-tools-install-a-${KEY}-fill`, 'install-a')).toBeNull();
+    expect(toolsKeyFromVolumeName(`openchamber-space-${ID}-volume-work`, 'install-a')).toBeNull();
+    expect(toolsKeyFromVolumeName(undefined, 'install-a')).toBeNull();
+  });
+
+  it('builds the marker, the owner, the role, the key, a description and the time, and no space id', () => {
+    expect(buildToolsLabels(TOOLS_FIELDS)).toEqual({
+      'openchamber.space': 'true',
+      'openchamber.space.role': 'tools',
+      'openchamber.space.owner': 'install-a',
+      'openchamber.space.tools.key': KEY,
+      'openchamber.space.tools.description': 'web 1.24.2, opencode 1.18.31',
+      'openchamber.space.created': '2026-09-20T08:00:00.000Z',
+    });
+  });
+
+  it.each([
+    ['invalid_role', { role: 'volume' }],
+    ['invalid_owner', { owner: 'a,b' }],
+    ['invalid_tools_key', { key: 'ABCDEF0123456789' }],
+    ['invalid_tools_description', { description: 'two\nlines' }],
+    ['invalid_tools_description', { description: '' }],
+    ['invalid_created', { created: 'soon' }],
+  ])('rejects with %s', (code, change) => {
+    expect(() => buildToolsLabels({ ...TOOLS_FIELDS, ...change })).toThrow(expect.objectContaining({ code }));
+  });
+
+  it('is invisible to the space label parser, so `list` and `remove` pass a tools volume by', () => {
+    expect(parseSpaceLabels(buildToolsLabels(TOOLS_FIELDS))).toBeNull();
+    expect(parseToolsLabels(buildSpaceLabels(FIELDS))).toBeNull();
+  });
+
+  it('round-trips through the tools label parser', () => {
+    expect(parseToolsLabels(buildToolsLabels(TOOLS_FIELDS))).toEqual(TOOLS_FIELDS);
+  });
+
+  it.each([
+    ['no labels', null],
+    ['no marker', { ...buildToolsLabels(TOOLS_FIELDS), 'openchamber.space': undefined }],
+    ['a malformed key', { ...buildToolsLabels(TOOLS_FIELDS), 'openchamber.space.tools.key': 'latest' }],
+    ['no owner', { ...buildToolsLabels(TOOLS_FIELDS), 'openchamber.space.owner': undefined }],
+  ])('returns null for %s', (title, labels) => {
+    expect(parseToolsLabels(labels)).toBeNull();
+  });
+
+  it('filters by owner, and by role and key when asked', () => {
+    expect(toolsLabelFilterArgs({ owner: 'install-a', role: 'tools' })).toEqual([
+      '--filter', 'label=openchamber.space=true',
+      '--filter', 'label=openchamber.space.owner=install-a',
+      '--filter', 'label=openchamber.space.role=tools',
+    ]);
+    expect(toolsLabelFilterArgs({ owner: 'install-a', key: KEY })).toEqual([
+      '--filter', 'label=openchamber.space=true',
+      '--filter', 'label=openchamber.space.owner=install-a',
+      '--filter', `label=openchamber.space.tools.key=${KEY}`,
+    ]);
+  });
+});

package/server/lib/spaces/layout.js

@@ -0,0 +1,184 @@
+// What a space looks like from the inside. Every place builds its container from these
+// facts, and everything written on top of `exec` relies on them.
+
+import { SpaceError } from './errors.js';
+import { requireSpaceId } from './labels.js';
+
+export const SPACE_USER = '1000:1000';
+export const SPACE_HOME = '/home/space';
+
+export const spaceWorkPath = (spaceId) => `/spaces/${requireSpaceId(spaceId)}`;
+
+// The project's folder inside a space is named after the project directory on the host, restricted
+// to characters that need no quoting anywhere. A leading dot is refused, so the name never collides
+// with the history side repository below, and `node_modules` is refused because the OpenCode plugin
+// link lives at `/spaces/<id>/node_modules`.
+const PROJECT_FOLDER_UNSAFE = /[^A-Za-z0-9._-]+/g;
+const PROJECT_FOLDER_MAX_LENGTH = 64;
+const PROJECT_FOLDER_FALLBACK = 'project';
+
+/** The folder name of a project inside a space, derived from the base name of its directory on the host. */
+export function projectFolderName(projectDirectory) {
+  const base = String(projectDirectory ?? '').split(/[\\/]+/).filter(Boolean).pop() ?? '';
+  const name = base.replace(PROJECT_FOLDER_UNSAFE, '-').replace(/^[.-]+/, '').slice(0, PROJECT_FOLDER_MAX_LENGTH);
+  if (!/[A-Za-z0-9]/.test(name) || name.toLowerCase() === 'node_modules') {
+    return PROJECT_FOLDER_FALLBACK;
+  }
+  return name;
+}
+
+/** Where the project's code lives inside a space: a plain non-bare repository. */
+export const spaceProjectPath = (spaceId, projectDirectory) => `${spaceWorkPath(spaceId)}/${projectFolderName(projectDirectory)}`;
+
+/** A project path of this space, one folder deep with a name the rule above could have made, or a refusal. */
+export function requireSpaceProjectPath(spaceId, value) {
+  const text = String(value ?? '');
+  const prefix = `${spaceWorkPath(spaceId)}/`;
+  const name = text.slice(prefix.length);
+  if (!text.startsWith(prefix) || name === '' || projectFolderName(name) !== name) {
+    throw new SpaceError('invalid_space_path', `A project path in space ${spaceId} is ${prefix}<folder>, the spacePath that code in returned`);
+  }
+  return text;
+}
+
+// The side repository that the history travels through. It starts with a dot, which no project
+// folder name can, and it exists only while the history is on its way.
+export const spaceHistoryPath = (spaceId) => `${spaceWorkPath(spaceId)}/.openchamber-history.git`;
+
+// The tools volume: a plain npm project, mounted read-only.
+export const TOOLS_MOUNT_PATH = '/opt/openchamber-tools';
+export const TOOLS_BIN_PATH = `${TOOLS_MOUNT_PATH}/node_modules/.bin`;
+export const TOOLS_PLUGIN_PATH = `${TOOLS_MOUNT_PATH}/node_modules/@opencode/plugin`;
+// The filler writes this file last. A volume without it was never filled to the end.
+export const TOOLS_MARKER_PATH = `${TOOLS_MOUNT_PATH}/.filled`;
+
+// The server inside listens on loopback only, so nothing faces the space network.
+// The port is an unusual one, because the agent's own dev servers share this loopback.
+export const SPACE_SERVER_HOST = '127.0.0.1';
+export const SPACE_SERVER_PORT = 27600;
+
+export const SPACE_TOKEN_DIRECTORY = `${SPACE_HOME}/.openchamber-space`;
+export const SPACE_TOKEN_PATH = `${SPACE_TOKEN_DIRECTORY}/token`;
+
+// The gatekeeper, the space's only way out. It sits on the space's internal network under this
+// name and on the space's own outer network, and nothing else joins either of them.
+export const GATEKEEPER_ALIAS = 'gatekeeper';
+// The two listeners the space may see. They bind every interface of the gatekeeper, because
+// the space's network is the point of them.
+const GATEKEEPER_BIND_HOST = '0.0.0.0';
+export const GATEKEEPER_CORRIDOR_PORT = 3128;
+export const GATEKEEPER_WINDOW_PORT = 8080;
+// The control channel. It binds the gatekeeper's own loopback, so only an `exec` from the host
+// reaches it. Measured on Docker 29.2.1: a listener on 127.0.0.1 in a container is refused from
+// another container on the same network, while the same listener on 0.0.0.0 answers.
+export const GATEKEEPER_CONTROL_HOST = '127.0.0.1';
+export const GATEKEEPER_CONTROL_PORT = 9099;
+
+// Where the space sends its traffic. The window's own URL, `http://gatekeeper:8080/model/<grant>`,
+// belongs to whoever writes a provider configuration, which no stage does yet.
+const GATEKEEPER_CORRIDOR_URL = `http://${GATEKEEPER_ALIAS}:${GATEKEEPER_CORRIDOR_PORT}`;
+
+// The gatekeeper's program arrives over `exec` on stdin, into the container's tmpfs. It is far
+// larger than the tools filler, and a `node -e` argument of that size was never tried on Windows.
+export const GATEKEEPER_PROGRAM_DIRECTORY = '/tmp/openchamber-gatekeeper';
+export const GATEKEEPER_PROGRAM_PATH = `${GATEKEEPER_PROGRAM_DIRECTORY}/gatekeeper.cjs`;
+
+const IMAGE_PATH = '/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin';
+
+// The programs of the base image that the host runs inside a container, by absolute path,
+// so that no PATH decides what the host runs.
+// Verified in the pinned image with `command -v`: `/bin` is a link to `/usr/bin`.
+export const IMAGE_SH = '/bin/sh';
+export const IMAGE_CAT = '/bin/cat';
+export const IMAGE_CHOWN = '/bin/chown';
+export const IMAGE_CURL = '/usr/bin/curl';
+export const IMAGE_NODE = '/usr/local/bin/node';
+const IMAGE_SLEEP = '/bin/sleep';
+// Code in: the receiving side of a push runs as `timeout -s KILL <seconds> git receive-pack <path>`.
+// The image's git is 2.39.5, and it has no `pkill`.
+export const IMAGE_GIT = '/usr/bin/git';
+export const IMAGE_TIMEOUT = '/usr/bin/timeout';
+
+/** First line of every fixed script the host runs inside: its commands come from the image only. */
+export const IMAGE_ONLY_PATH = `PATH=${IMAGE_PATH};`;
+
+/**
+ * The environment of a space. The password of the server inside and
+ * OPENCODE_AUTH_CONTENT never go here: container env is readable through `inspect`.
+ */
+export const SPACE_ENVIRONMENT = Object.freeze({
+  HOME: SPACE_HOME,
+  // The tools come last. The image has no `openchamber` and no `opencode`, so both are still found,
+  // and a transitive npm package that ships a bin named `node` or `sh` never shadows the image's.
+  PATH: `${IMAGE_PATH}:${TOOLS_BIN_PATH}`,
+  // The corridor, in both spellings. curl 7.88.1 in this image ignores an uppercase HTTP_PROXY on
+  // purpose, the httpoxy protection, and honours the lowercase one. Without the lowercase spelling
+  // plain-HTTP traffic from curl and from everything that uses libcurl never reaches the corridor.
+  HTTPS_PROXY: GATEKEEPER_CORRIDOR_URL,
+  https_proxy: GATEKEEPER_CORRIDOR_URL,
+  HTTP_PROXY: GATEKEEPER_CORRIDOR_URL,
+  http_proxy: GATEKEEPER_CORRIDOR_URL,
+  // Window traffic skips the corridor, and so does the space's own loopback. Measured: with
+  // http_proxy set, curl sends even http://127.0.0.1 to the corridor, and Node with
+  // NODE_USE_ENV_PROXY=1 proxies loopback too. Both spellings, because curl reads both.
+  NO_PROXY: `${GATEKEEPER_ALIAS},localhost,127.0.0.1`,
+  no_proxy: `${GATEKEEPER_ALIAS},localhost,127.0.0.1`,
+  // Node 22 ignores proxy variables without this. Measured: EAI_AGAIN for every fetch.
+  NODE_USE_ENV_PROXY: '1',
+  // OpenCode's catalog and update downloads would only spend corridor attempts.
+  OPENCODE_DISABLE_MODELS_FETCH: '1',
+  OPENCODE_DISABLE_AUTOUPDATE: '1',
+  // The server inside a space never hosts the relay passively. It has a way out now, and a
+  // space must not become the machine that paired devices land on.
+  OPENCHAMBER_RELAY_HOST: 'off',
+});
+
+// Waits for the token file, takes it as the server password, and becomes the server.
+// The password reaches the server through the environment of this one process, never through the container's.
+const SERVER_SCRIPT = [
+  `while [ ! -s ${SPACE_TOKEN_PATH} ]; do ${IMAGE_SLEEP} 0.2; done;`,
+  `OPENCHAMBER_UI_PASSWORD="$(${IMAGE_CAT} ${SPACE_TOKEN_PATH})";`,
+  'export OPENCHAMBER_UI_PASSWORD;',
+  `exec openchamber serve --foreground --api-only --host ${SPACE_SERVER_HOST} --port ${SPACE_SERVER_PORT}`,
+].join(' ');
+
+/** The command of a space container. A fixed script, nothing in it varies per space. */
+export const SPACE_SERVER_COMMAND = Object.freeze([IMAGE_SH, '-c', SERVER_SCRIPT]);
+
+/**
+ * The environment of a gatekeeper. It holds no secret and never will: grants arrive on the
+ * stdin of an `exec` and live in the program's memory. HOME points into the tmpfs, because the
+ * root filesystem is read-only and a program that resolves HOME must land somewhere writable.
+ */
+export const GATEKEEPER_ENVIRONMENT = Object.freeze({ HOME: '/tmp' });
+
+// How long the window waits for an upstream that has gone quiet. The same as the corridor's
+// tunnel idle limit, and for the same reason: a model answer streams, so silence is what counts.
+const GATEKEEPER_WINDOW_DEADLINE_MS = 300_000;
+
+// How many connections each listener holds at once. The corridor's is twice the tunnel cap, so
+// every handshake a working space makes has room; the window serves one request per connection
+// and holds a socket out for each; only the host talks to the control channel.
+const GATEKEEPER_CORRIDOR_CONNECTIONS = 128;
+const GATEKEEPER_WINDOW_CONNECTIONS = 64;
+const GATEKEEPER_CONTROL_CONNECTIONS = 8;
+
+// The same shape as the space's wait for its token: the container comes up, waits for the file
+// the host sends over `exec`, and becomes the program. The ports, the deadline and the caps are
+// arguments, so the one program serves the container and the tests without a switch that weakens
+// it. These numbers are the production ones and the hardening test asserts this whole command.
+const GATEKEEPER_SCRIPT = [
+  `while [ ! -s ${GATEKEEPER_PROGRAM_PATH} ]; do ${IMAGE_SLEEP} 0.2; done;`,
+  `exec ${IMAGE_NODE} ${GATEKEEPER_PROGRAM_PATH}`,
+  GATEKEEPER_BIND_HOST,
+  String(GATEKEEPER_CORRIDOR_PORT),
+  String(GATEKEEPER_WINDOW_PORT),
+  String(GATEKEEPER_CONTROL_PORT),
+  String(GATEKEEPER_WINDOW_DEADLINE_MS),
+  String(GATEKEEPER_CORRIDOR_CONNECTIONS),
+  String(GATEKEEPER_WINDOW_CONNECTIONS),
+  String(GATEKEEPER_CONTROL_CONNECTIONS),
+].join(' ');
+
+/** The command of a gatekeeper container. Fixed, and the same for every space. */
+export const GATEKEEPER_COMMAND = Object.freeze([IMAGE_SH, '-c', GATEKEEPER_SCRIPT]);

package/server/lib/spaces/layout.test.js

@@ -0,0 +1,30 @@
+import { describe, expect, it } from 'vitest';
+
+import { projectFolderName, spaceHistoryPath, spaceProjectPath } from './layout.js';
+
+describe('projectFolderName', () => {
+  it.each([
+    ['/home/me/openchamber', 'openchamber'],
+    ['/home/me/my app/', 'my-app'],
+    ['C:\\Users\\me\\Projects\\web_site.v2', 'web_site.v2'],
+    ['/home/me/.dotfiles', 'dotfiles'],
+    ['/home/me/-rf', 'rf'],
+    ['/home/me/bait repo ї', 'bait-repo-'],
+    ['/home/me/$(touch x);`id`', 'touch-x-id-'],
+    [`/home/me/${'a'.repeat(100)}`, 'a'.repeat(64)],
+  ])('names %s as %s', (directory, name) => {
+    expect(projectFolderName(directory)).toBe(name);
+  });
+
+  // The plugin link lives at /spaces/<id>/node_modules, and a name with nothing readable left says nothing.
+  it.each(['/home/me/node_modules', '/home/me/NODE_MODULES', '/home/me/юнікод', '/home/me/...', '/', ''])('falls back to a fixed name for %j', (directory) => {
+    expect(projectFolderName(directory)).toBe('project');
+  });
+
+  it('puts the project and the history side repository in the space, where they cannot collide', () => {
+    expect(spaceProjectPath('a1b2c3d4e5f6', '/home/me/openchamber')).toBe('/spaces/a1b2c3d4e5f6/openchamber');
+    expect(spaceHistoryPath('a1b2c3d4e5f6')).toBe('/spaces/a1b2c3d4e5f6/.openchamber-history.git');
+    expect(spaceProjectPath('a1b2c3d4e5f6', '/home/me/.openchamber-history.git')).toBe('/spaces/a1b2c3d4e5f6/openchamber-history.git');
+    expect(() => spaceProjectPath('../etc', '/home/me/openchamber')).toThrow();
+  });
+});