Skip to content

an open-source alternative to the dots, bots and muses of the world, run an office of claude code/codex like agents on your laptop, sandboxes or anywhere, uses your existing subscriptions

fix(hires): enforce runtime allowlists in gallery validator

HaningZS971154807fb8
diff --git a/docs/hires/spec/HIRE_SPEC.md b/docs/hires/spec/HIRE_SPEC.md
index d2b1c8d4..9c8ada55 100644
--- a/docs/hires/spec/HIRE_SPEC.md
+++ b/docs/hires/spec/HIRE_SPEC.md
@@ -20,6 +20,8 @@ and imported into anyone's office with one click.
"model": "claude-sonnet-4-6",
"commandFlags": ["--max-turns", "80"],
"capabilities": ["docs", "writing", "markdown"],
+ "skills": ["md-audit"],
+ "mcpServers": ["fetch"],
"isolate": false,
"tokenCap": 2000000,
"author": "Jason Choplin",
@@ -46,16 +48,24 @@ A manifest is untrusted input. The format is designed so it **cannot**:
- **Auto-spawn an agent.** Import only pre-fills the form. A human reviews every field —
the modal shows an "imported" banner — and clicks spawn.
- **Name an executable.** There is no `command` field. The spawn binary always comes from the
- user's locally configured provider preset (`claude`, `agy`, `codex`). `provider: "custom"`
+ user's locally configured provider preset (`claude`, `agy`, `codex`, `cursor`). `provider: "custom"`
is rejected.
-- **Smuggle shell syntax.** `commandFlags` entries must match `^[A-Za-z0-9._/=:,@%+-]{1,100}$`
- (no quotes, whitespace, semicolons, pipes, backticks), the first entry must be flag-shaped
- (`-…`), and args are passed to node-pty as argv — never through a shell.
+- **Select arbitrary CLI behavior.** `commandFlags` is default-deny. Only `--model`,
+ `--max-turns`, `--output-format`, and `--verbose` are accepted, either as
+ `--flag value` or `--flag=value`. A bare value may only immediately follow an allowed
+ split-form flag. Every token must also match the conservative character set
+ `^[A-Za-z0-9._/=:,@+-]{1,100}$`; quotes, whitespace, percent expansion, and shell
+ metacharacters are rejected. Args are passed to node-pty as argv, never through a shell.
+- **Name arbitrary skills or MCP processes.** `skills` and `mcpServers` contain ids from
+ the app's bundled allowlists, never paths, package names, commands, environment variables,
+ or raw MCP specs. MCP entries that need write access or secrets require explicit consent
+ during import and are never auto-enabled.
- **Be oversized or off-origin.** 64 KB cap, https-only fetch, every string field length-capped.
-Things a manifest *can* legitimately influence that you should still eyeball before spawning:
-flags like `--permission-mode` change how autonomously the agent runs, and `goal` is prompt
-text the agent will act on. That's exactly why import never skips the review step.
+The safe flags still influence model selection, turn limits, output shape, or verbosity, and
+`goal` is prompt text the agent will act on. Review them before spawning. Permission, sandbox,
+approval, provider/backend, configuration, MCP, and prompt-injection flags are intentionally
+not shareable; add an exceptional flag by hand after import if you trust and need it.
## Field reference
@@ -67,14 +77,16 @@ text the agent will act on. That's exactly why import never skips the review ste
| `goal` | string ≤ 4000 | | standing mission text |
| `character` | string ≤ 24 | | office cast id; unknown → default sprite |
| `accent` | string ≤ 24 | | color name; unknown → default |
-| `provider` | `claude` \| `antigravity` \| `agy` \| `codex` | | `agy` = alias for `antigravity`; omit = user default |
+| `provider` | `claude` \| `antigravity` \| `agy` \| `codex` \| `cursor` | | `agy` = alias for `antigravity`; omit = user default |
| `model` | string ≤ 80 | | provider model id/label |
-| `commandFlags` | string[] ≤ 16 | | flag-shaped tokens appended to the locally-built command |
+| `commandFlags` | string[] ≤ 16 | | allowlisted safe flags and their immediately following values |
| `capabilities` | string[] ≤ 12 | | hive routing tags |
| `isolate` | boolean | | spawn in own git worktree |
| `tokenCap` | int 1…1e10 | | per-agent token budget |
| `author` | string ≤ 80 | | attribution |
| `homepage` | string ≤ 300 | | https only |
+| `skills` | bundled skill id[] ≤ 8 | | built-in safe skills only; no paths or arbitrary ids |
+| `mcpServers` | MCP catalog id[] ≤ 8 | | built-in catalog only; write/secret tiers require consent |
## Conventions
diff --git a/docs/hires/spec/hire.schema.json b/docs/hires/spec/hire.schema.json
index ae11d0ab..06d4f49a 100644
--- a/docs/hires/spec/hire.schema.json
+++ b/docs/hires/spec/hire.schema.json
@@ -40,7 +40,7 @@
"examples": ["mint"]
},
"provider": {
- "enum": ["claude", "antigravity", "agy", "codex"],
+ "enum": ["claude", "antigravity", "agy", "codex", "cursor"],
"description": "Which CLI the role is designed for. 'agy' is an alias for 'antigravity'. 'custom' is deliberately not allowed — a manifest can never choose an arbitrary local binary."
},
"model": {
@@ -54,9 +54,9 @@
"maxItems": 16,
"items": {
"type": "string",
- "pattern": "^[A-Za-z0-9._/=:,@%+-]{1,100}$"
+ "pattern": "^(?=.{1,100}$)(?:--(?:model|max-turns|output-format|verbose)(?:=[A-Za-z0-9._/=:,@+-]*)?|[A-Za-z0-9._/=:,@+][A-Za-z0-9._/=:,@+-]*)$"
},
- "description": "Extra flag-shaped args appended to the LOCALLY-built spawn command (the binary always comes from the user's provider preset). The first entry must start with '-'. No quotes, whitespace, or shell metacharacters; args are passed as argv, never through a shell."
+ "description": "Extra args appended to the LOCALLY-built spawn command (the binary always comes from the user's provider preset). Flag tokens are default-deny: only --model, --max-turns, --output-format, and --verbose are allowed, in split or --flag=value form. A bare value may only immediately follow an allowed split-form flag; this positional rule is enforced by the runtime and browser validators because JSON Schema draft-07 cannot express it. No quotes, whitespace, percent expansion, or shell metacharacters."
},
"capabilities": {
"type": "array",
diff --git a/docs/hires/validator.js b/docs/hires/validator.js
index 13f4dc21..bcacb22a 100644
--- a/docs/hires/validator.js
+++ b/docs/hires/validator.js
@@ -8,6 +8,15 @@ window.HireSpec = (function () {
const PROVIDERS = ['claude', 'antigravity', 'codex', 'cursor'];
const PROVIDER_LABEL = { claude: 'Claude Code', antigravity: 'Antigravity', codex: 'Codex', cursor: 'Cursor' };
const FLAG_RE = /^[A-Za-z0-9._\/=:,@+-]{1,100}$/;
+ // Keep these allowlists in lockstep with src/shared/hire.ts and
+ // src/shared/mcpCatalog.ts. test/hire-validator-parity.test.cjs locks the
+ // browser validator to the canonical runtime validator.
+ const SAFE_FLAG_NAMES = new Set(['--model', '--max-turns', '--output-format', '--verbose']);
+ const BUNDLED_SKILL_IDS = new Set(['md-hive-sync', 'md-fetch-summarize', 'md-audit']);
+ const MCP_SERVER_IDS = new Set([
+ 'sequential-thinking', 'time', 'fetch', 'context7', 'filesystem', 'git',
+ 'github-token', 'db', 'email-calendar', 'search-with-key'
+ ]);
// model flows onto the spawn command line — reject shell metacharacters
// (mirror of MODEL_RE in the app's src/shared/hire.ts).
const MODEL_RE = /^[A-Za-z0-9 ._()[\]\/:@+-]{1,80}$/;
@@ -16,6 +25,10 @@ window.HireSpec = (function () {
const ACCENTS = ['coral', 'mint', 'sky', 'lemon', 'lilac', 'peach'];
function normalizeProvider(p) { return p === 'agy' ? 'antigravity' : p; }
+ function isSafeFlag(token) {
+ if (!token.startsWith('-')) return false;
+ return SAFE_FLAG_NAMES.has(token.split('=', 1)[0].toLowerCase());
+ }
function validate(raw) {
const errors = [];
@@ -49,12 +62,59 @@ window.HireSpec = (function () {
if (!Array.isArray(raw.commandFlags) || raw.commandFlags.length > 16) {
errors.push('"commandFlags" must be an array of at most 16 items');
} else {
- raw.commandFlags.forEach((f) => {
- if (!str(f) || !FLAG_RE.test(f)) errors.push('commandFlags entry ' + JSON.stringify(f) + ' is not a safe flag token');
+ let valueAllowed = false;
+ raw.commandFlags.forEach((f, index) => {
+ if (!str(f) || !FLAG_RE.test(f)) {
+ errors.push('commandFlags entry ' + JSON.stringify(f) + ' is not a safe flag token');
+ valueAllowed = false;
+ return;
+ }
+ if (index === 0 && !f.startsWith('-')) {
+ errors.push('"commandFlags" must start with a flag (e.g. "--model")');
+ valueAllowed = false;
+ return;
+ }
+ if (f.startsWith('-')) {
+ if (!isSafeFlag(f)) {
+ errors.push('commandFlags entry ' + JSON.stringify(f) + ' is not in the shared-hire safe-flag list (' + Array.from(SAFE_FLAG_NAMES).join(', ') + ')');
+ valueAllowed = false;
+ return;
+ }
+ valueAllowed = !f.includes('=');
+ } else {
+ if (!valueAllowed) {
+ errors.push('commandFlags entry ' + JSON.stringify(f) + ' is not allowed here (a value may only follow an allowed flag such as "--model")');
+ return;
+ }
+ valueAllowed = false;
+ }
+ });
+ }
+ }
+ if (raw.skills !== undefined) {
+ if (!Array.isArray(raw.skills) || raw.skills.length > 8) {
+ errors.push('"skills" must be an array of at most 8 items');
+ } else {
+ raw.skills.forEach((skill) => {
+ if (!str(skill) || !skill.trim()) {
+ errors.push('"skills" entries must be non-empty strings');
+ } else if (!BUNDLED_SKILL_IDS.has(skill.trim())) {
+ errors.push('"skills" entry ' + JSON.stringify(skill.trim()) + ' is not a bundled skill id');
+ }
+ });
+ }
+ }
+ if (raw.mcpServers !== undefined) {
+ if (!Array.isArray(raw.mcpServers) || raw.mcpServers.length > 8) {
+ errors.push('"mcpServers" must be an array of at most 8 items');
+ } else {
+ raw.mcpServers.forEach((server) => {
+ if (!str(server) || !server.trim()) {
+ errors.push('"mcpServers" entries must be non-empty strings');
+ } else if (!MCP_SERVER_IDS.has(server.trim())) {
+ errors.push('"mcpServers" entry ' + JSON.stringify(server.trim()) + ' is not a known catalog id');
+ }
});
- if (raw.commandFlags.length && str(raw.commandFlags[0]) && !raw.commandFlags[0].startsWith('-')) {
- errors.push('"commandFlags" must start with a flag (e.g. "--max-turns")');
- }
}
}
if (raw.capabilities !== undefined && (!Array.isArray(raw.capabilities) || raw.capabilities.length > 12)) {
@@ -64,7 +124,7 @@ window.HireSpec = (function () {
if (raw.tokenCap !== undefined && !(Number.isInteger(raw.tokenCap) && raw.tokenCap > 0 && raw.tokenCap <= 1e10)) {
errors.push('"tokenCap" must be a positive integer (max 1e10)');
}
- if (str(raw.homepage) && raw.homepage && !raw.homepage.startsWith('https://')) errors.push('"homepage" must be https');
+ if (str(raw.homepage) && raw.homepage.trim() && !raw.homepage.trim().startsWith('https://')) errors.push('"homepage" must be https');
return { ok: errors.length === 0, errors };
}
diff --git a/test/hire-validator-parity.test.cjs b/test/hire-validator-parity.test.cjs
new file mode 100644
index 00000000..f06f602c
--- /dev/null
+++ b/test/hire-validator-parity.test.cjs
@@ -0,0 +1,249 @@
+'use strict';
+
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const test = require('node:test');
+const vm = require('node:vm');
+
+const loadTs = require('./load-ts.cjs');
+const { BUNDLED_SKILL_IDS, validateHireManifest } = loadTs('src/shared/hire.ts');
+const { MCP_CATALOG } = loadTs('src/shared/mcpCatalog.ts');
+
+const ROOT = path.resolve(__dirname, '..');
+
+function loadGalleryValidator() {
+ const source = fs.readFileSync(path.join(ROOT, 'docs/hires/validator.js'), 'utf8');
+ const context = { window: {} };
+ vm.createContext(context);
+ vm.runInContext(source, context, { filename: 'docs/hires/validator.js' });
+ return context.window.HireSpec.validate;
+}
+
+const validateInGallery = loadGalleryValidator();
+
+function manifest(overrides = {}) {
+ return {
+ spec: 'munder-difflin/hire@1',
+ name: 'Parity check',
+ ...overrides
+ };
+}
+
+const parityCases = [
+ {
+ name: 'accepts a minimal manifest',
+ raw: manifest(),
+ expected: true
+ },
+ {
+ name: 'accepts the provider alias and safe flags in split and inline forms',
+ raw: manifest({
+ provider: 'agy',
+ commandFlags: ['--model', 'claude-sonnet-4-6', '--max-turns=80', '--output-format=json', '--verbose']
+ }),
+ expected: true
+ },
+ {
+ name: 'accepts Cursor plus allowlisted skills and MCP servers',
+ raw: manifest({
+ provider: 'cursor',
+ skills: ['md-hive-sync', 'md-audit'],
+ mcpServers: ['fetch', 'github-token']
+ }),
+ expected: true
+ },
+ {
+ name: 'accepts surrounding whitespace that the runtime trims from an https homepage',
+ raw: manifest({ homepage: ' https://example.com/hire ' }),
+ expected: true
+ },
+ {
+ name: 'rejects a permission-escalating flag',
+ raw: manifest({ commandFlags: ['--permission-mode', 'bypassPermissions'] }),
+ expected: false
+ },
+ {
+ name: 'rejects an arbitrary provider-selection flag',
+ raw: manifest({ commandFlags: ['--provider', 'attacker-controlled'] }),
+ expected: false
+ },
+ {
+ name: 'rejects the Codex config override short flag',
+ raw: manifest({ commandFlags: ['-c', 'model_providers.evil.base_url=https://attacker.example'] }),
+ expected: false
+ },
+ {
+ name: 'rejects a second bare value after the safe flag value is consumed',
+ raw: manifest({ commandFlags: ['--model', 'safe-model', 'unexpected'] }),
+ expected: false
+ },
+ {
+ name: 'rejects an unknown skill id',
+ raw: manifest({ skills: ['read-secrets'] }),
+ expected: false
+ },
+ {
+ name: 'rejects more than eight skills',
+ raw: manifest({ skills: Array(9).fill('md-audit') }),
+ expected: false
+ },
+ {
+ name: 'rejects a non-string skill id',
+ raw: manifest({ skills: ['md-audit', 42] }),
+ expected: false
+ },
+ {
+ name: 'rejects an unknown MCP catalog id',
+ raw: manifest({ mcpServers: ['attacker-server'] }),
+ expected: false
+ },
+ {
+ name: 'rejects more than eight MCP servers',
+ raw: manifest({ mcpServers: Array(9).fill('fetch') }),
+ expected: false
+ },
+ {
+ name: 'rejects a non-string MCP catalog id',
+ raw: manifest({ mcpServers: ['fetch', null] }),
+ expected: false
+ }
+];
+
+for (const { name, raw, expected } of parityCases) {
+ test(`runtime and gallery validator ${name}`, () => {
+ const runtime = validateHireManifest(raw);
+ const gallery = validateInGallery(raw);
+
+ assert.equal(runtime.ok, expected, `runtime errors: ${runtime.errors.join('; ')}`);
+ assert.equal(
+ gallery.ok,
+ expected,
+ `gallery result must match runtime; gallery errors: ${Array.from(gallery.errors).join('; ')}`
+ );
+ if (!expected) assert.ok(gallery.errors.length > 0, 'invalid input must explain why it was rejected');
+ });
+}
+
+function findHireManifests(directory) {
+ return fs.readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {
+ const fullPath = path.join(directory, entry.name);
+ if (entry.isDirectory()) return findHireManifests(fullPath);
+ return entry.name.endsWith('.hire.json') ? [fullPath] : [];
+ });
+}
+
+test('every published hire manifest passes both validators', () => {
+ const files = findHireManifests(path.join(ROOT, 'docs/hires/manifests'));
+ assert.ok(files.length > 0, 'expected published hire manifests');
+
+ for (const file of files) {
+ const raw = JSON.parse(fs.readFileSync(file, 'utf8'));
+ const runtime = validateHireManifest(raw);
+ const gallery = validateInGallery(raw);
+ const relative = path.relative(ROOT, file);
+ assert.equal(runtime.ok, true, `${relative}: runtime rejected: ${runtime.errors.join('; ')}`);
+ assert.equal(gallery.ok, true, `${relative}: gallery rejected: ${Array.from(gallery.errors).join('; ')}`);
+ }
+});
+
+test('every runtime provider and allowlisted capability id passes the gallery validator', () => {
+ for (const provider of ['claude', 'antigravity', 'agy', 'codex', 'cursor']) {
+ assert.equal(validateInGallery(manifest({ provider })).ok, true, `provider ${provider}`);
+ }
+ for (const skill of BUNDLED_SKILL_IDS) {
+ assert.equal(validateInGallery(manifest({ skills: [skill] })).ok, true, `skill ${skill}`);
+ }
+ for (const { id } of MCP_CATALOG) {
+ assert.equal(validateInGallery(manifest({ mcpServers: [id] })).ok, true, `MCP server ${id}`);
+ }
+});
+
+test('runtime and gallery validators agree across every manifest field boundary', () => {
+ const fieldCases = [
+ {},
+ { spec: undefined },
+ { spec: 'munder-difflin/hire@2' },
+ { name: undefined },
+ { name: '' },
+ { name: ' '.repeat(3) },
+ { name: 'n'.repeat(40) },
+ { name: 'n'.repeat(41) },
+ { name: 42 },
+ { description: null },
+ { description: 'd'.repeat(200) },
+ { description: 'd'.repeat(201) },
+ { goal: 'g'.repeat(4000) },
+ { goal: 'g'.repeat(4001) },
+ { character: 'c'.repeat(25) },
+ { accent: false },
+ { model: 'Gemini 3.1 Pro (High)' },
+ { model: 'model%PATH%' },
+ { model: 'model&command' },
+ { model: 'm'.repeat(81) },
+ { provider: 'claude' },
+ { provider: 'agy' },
+ { provider: 'custom' },
+ { provider: 42 },
+ { commandFlags: [] },
+ { commandFlags: Array(17).fill('--verbose') },
+ { commandFlags: [42] },
+ { commandFlags: ['value-first'] },
+ { commandFlags: ['--model', 'safe', '--output-format=json'] },
+ { commandFlags: ['--MODEL', 'safe'] },
+ { commandFlags: ['--model', 'unsafe%value'] },
+ { capabilities: null },
+ { capabilities: Array(13).fill('tag') },
+ { capabilities: ['valid', 42, ''] },
+ { isolate: true },
+ { isolate: 'true' },
+ { tokenCap: 1 },
+ { tokenCap: 1e10 },
+ { tokenCap: 0 },
+ { tokenCap: 1.5 },
+ { tokenCap: 1e10 + 1 },
+ { author: 'a'.repeat(81) },
+ { homepage: null },
+ { homepage: ' ' },
+ { homepage: 'http://example.com' },
+ { homepage: 'https://example.com' },
+ { homepage: ' https://example.com/hire ' },
+ { skills: null },
+ { skills: [] },
+ { skills: [' md-audit '] },
+ { skills: ['unknown'] },
+ { mcpServers: null },
+ { mcpServers: [] },
+ { mcpServers: [' fetch '] },
+ { mcpServers: ['unknown'] }
+ ];
+
+ for (const overrides of fieldCases) {
+ const raw = manifest(overrides);
+ const runtime = validateHireManifest(raw);
+ const gallery = validateInGallery(raw);
+ assert.equal(
+ gallery.ok,
+ runtime.ok,
+ `${JSON.stringify(overrides)}\nruntime: ${runtime.errors.join('; ')}\ngallery: ${Array.from(gallery.errors).join('; ')}`
+ );
+ }
+});
+
+test('the published JSON schema reflects runtime providers and allowlists', () => {
+ const schema = JSON.parse(fs.readFileSync(path.join(ROOT, 'docs/hires/spec/hire.schema.json'), 'utf8'));
+ assert.deepEqual(
+ schema.properties.provider.enum,
+ ['claude', 'antigravity', 'agy', 'codex', 'cursor']
+ );
+ assert.deepEqual(schema.properties.skills.items.enum, Array.from(BUNDLED_SKILL_IDS));
+ assert.deepEqual(schema.properties.mcpServers.items.enum, MCP_CATALOG.map(({ id }) => id));
+
+ const commandTokenPattern = new RegExp(schema.properties.commandFlags.items.pattern);
+ for (const token of ['--model', '--model=claude-sonnet-4-6', '--max-turns', '80', '--output-format=json', '--verbose']) {
+ assert.equal(commandTokenPattern.test(token), true, `schema should accept ${token}`);
+ }
+ for (const token of ['--provider', '--permission-mode=bypassPermissions', '%PATH%']) {
+ assert.equal(commandTokenPattern.test(token), false, `schema should reject ${token}`);
+ }
+});