Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
// Allowlist of safe commands
export const ALLOWED_COMMANDS = new Set([
'npm', 'npx', 'pnpm', 'yarn', 'bun',
'node', 'deno',
'git', 'gh',
'pm2',
'ls', 'cat', 'head', 'tail', 'grep', 'find', 'wc',
'pwd', 'which', 'echo',
'curl', 'wget',
'docker', 'docker-compose',
'make', 'cargo', 'go', 'python', 'python3', 'pip', 'pip3',
'brew'
]);
// Pre-sorted list for API responses
export const ALLOWED_COMMANDS_SORTED = Array.from(ALLOWED_COMMANDS).sort();
// Narrower allowlist for the UNATTENDED lane (Layered Intelligence `cmd` custom
// sources), which runs on a schedule with nobody watching. Read-only repository
// and tracker inspection is the entire documented purpose of a `cmd` source, so
// this list deliberately excludes every network-fetch and code-execution verb
// that ALLOWED_COMMANDS admits for the operator-driven runner (`npx`, `node`,
// `python`, `pip`, `curl`, `wget`, `go`, `cargo`, `make`, `brew`, `pm2`, …).
// `npx <pkg>` / `pip install <pkg>` / `curl -o <path> <url>` contain no shell
// metacharacter, so the metacharacter filter alone does NOT stop them.
//
// Scope: membership here is necessary but NOT sufficient. Four of these binaries
// are multi-purpose — `git`, `find`, `gh` and `glab` all accept destructive or
// mutating verbs (`git reset --hard`, `find . -delete`, `gh api -X POST`) that
// carry no shell metacharacter. Those are rejected a second time by the
// per-binary subcommand gate below (`UNATTENDED_SUBCOMMAND_VALIDATORS`, wired
// into `validateUnattendedCommand`). The remaining entries (`ls`, `cat`, `head`,
// `tail`, `grep`, `wc`, `pwd`, `echo`) have no write mode at all and stay
// binary-level.
export const UNATTENDED_READONLY_COMMANDS = new Set([
'git', 'gh', 'glab',
'ls', 'cat', 'head', 'tail', 'grep', 'find', 'wc',
'pwd', 'echo'
]);
const UNATTENDED_READONLY_COMMANDS_SORTED = Array.from(UNATTENDED_READONLY_COMMANDS).sort();
// Shell metacharacters that could be used for command injection
// Security: Reject any command containing these to prevent injection via pipes, chaining, etc.
export const DANGEROUS_SHELL_CHARS = /[;|&`$(){}[\]<>\\!#*?~]/;
/**
* Parse command string into args, respecting quoted strings.
* e.g. 'git commit -m "msg with spaces"' → ['git', 'commit', '-m', 'msg with spaces']
*/
export function parseCommandArgs(str) {
const args = [];
let current = '';
let inQuote = null;
let hasQuote = false;
for (const ch of str) {
if (inQuote) {
if (ch === inQuote) { inQuote = null; continue; }
current += ch;
} else if (ch === '"' || ch === "'") {
inQuote = ch;
hasQuote = true;
} else if (/\s/.test(ch)) {
if (current || hasQuote) { args.push(current); current = ''; hasQuote = false; }
} else {
current += ch;
}
}
if (inQuote) return str.split(/\s+/); // fallback on unmatched quotes
if (current || hasQuote) args.push(current);
return args;
}
// PM2 runs ONE shared daemon for every app on the machine. These subcommands
// take the whole daemon (and therefore every other app, including PortOS itself)
// down or rewrite system boot config — never legitimate for a single app's
// scoped management. Blocked regardless of who issues them. This list is mirrored
// in the agent PATH-shim (server/lib/agentGuard/bin/pm2) — keep them in sync.
export const PM2_BLOCKED_SUBCOMMANDS = new Set(['kill', 'startup', 'unstartup']);
// Daemon-wide verbs that are fine against a single named process but catastrophic
// with the `all` target (`pm2 stop all`, `pm2 delete all`, `pm2 restart all` —
// the unscoped form the user's AGENTS.md explicitly forbids). Blocked only when
// the target is `all`.
export const PM2_ALL_TARGET_VERBS = new Set([
'stop', 'delete', 'del', 'restart', 'reload', 'gracefulreload', 'scale',
]);
// Mirror the argument grammar of PM2's Commander CLI before applying policy.
// Required values consume even a flag-shaped token; optional values do not.
const PM2_REQUIRED_OPTIONS = new Set([
'--ext', '--name', '--interpreter', '--interpreter-args', '--node-args',
'--output', '--error', '--log-type', '--log-date-format', '--env', '--instances',
'--parallel', '--pid', '--kill-timeout', '--listen-timeout', '--max-memory-restart',
'--restart-delay', '--exp-backoff-restart-delay', '--user', '--uid', '--gid',
'--namespace', '--cwd', '--hp', '--service-name', '--cron', '--cron-restart',
'--only', '--ignore-watch', '--watch-delay', '--stop-exit-codes', '--sort',
'-n', '-o', '-e', '-i', '-p', '-k', '-u', '-c',
]);
const PM2_OPTIONAL_OPTIONS = new Set(['--log', '-l', '--filter-env', '--max-restarts', '--watch']);
const PM2_BOOLEAN_OPTIONS = new Set([
'-v', '--version', '-s', '--silent', '-m', '--mini-list', '--time', '--disable-logs',
'-a', '--update-env', '-f', '--force', '--shutdown-with-message', '-x', '--execute-command',
'--wait-ip', '-w', '--write', '--no-daemon', '--source-map-support',
'--disable-source-map-support', '--wait-ready', '--merge-logs', '--no-color',
'--no-vizion', '--no-autostart', '--no-autorestart', '--no-treekill', '--no-pmx',
'--no-automation', '--trace', '--disable-trace', '--attach', '--v8',
'--event-loop-inspector', '--deep-monitoring', '-h', '--help',
]);
function pm2Positionals(args) {
const normalized = [];
for (let i = 0; i < args.length; i++) {
const arg = args[i];
if (arg === '--') { normalized.push(...args.slice(i)); break; }
if (PM2_REQUIRED_OPTIONS.has(args[i - 1])) normalized.push(arg);
else if (/^-[^-]/.test(arg)) normalized.push(...arg.slice(1).split('').map(c => `-${c}`));
else if (arg.startsWith('--') && arg.includes('=')) {
const split = arg.indexOf('=');
normalized.push(arg.slice(0, split), arg.slice(split + 1));
} else normalized.push(arg);
}
const positionals = [];
for (let i = 0; i < normalized.length; i++) {
const arg = normalized[i];
if (arg === '--') return [...positionals, ...normalized.slice(i + 1)];
if (PM2_REQUIRED_OPTIONS.has(arg)) i++;
else if (PM2_BOOLEAN_OPTIONS.has(arg)) continue;
else if (PM2_OPTIONAL_OPTIONS.has(arg)) {
const next = normalized[i + 1];
if (next != null && (!next.startsWith('-') || next === '-')) i++;
} else if (arg.length > 1 && arg.startsWith('-')) {
// Commander retains unknown options separately, consuming a plain value.
if (normalized[i + 1] != null && !normalized[i + 1].startsWith('-')) i++;
} else positionals.push(arg);
}
return positionals;
}
/**
* Reject pm2 invocations that would disrupt the shared PM2 daemon or other apps.
* `args` is everything after the `pm2` base command.
* Returns { valid, error? }.
*/
export function validatePm2Command(args) {
const positionals = pm2Positionals(args);
const sub = (positionals[0] || '').toLowerCase();
if (PM2_BLOCKED_SUBCOMMANDS.has(sub)) {
return { valid: false, error: `'pm2 ${sub}' is blocked — it would take down the shared PM2 daemon or every app on this machine (including PortOS). Use a scoped command like 'pm2 restart <process-name>'.` };
}
if (PM2_ALL_TARGET_VERBS.has(sub) && positionals.slice(1).some(a => a.toLowerCase() === 'all')) {
return { valid: false, error: `'pm2 ${sub} all' is blocked — it affects every app on this shared server. Target a specific process by name instead.` };
}
return { valid: true };
}
// ---------------------------------------------------------------------------
// Unattended subcommand gate (#5808)
//
// `UNATTENDED_READONLY_COMMANDS` admits four multi-purpose binaries whose
// destructive verbs contain no shell metacharacter, so the allowlist and the
// metacharacter filter both wave them through. These validators run only on the
// unattended lane, keyed off the base command exactly the way `validateCommand`
// keys the pm2 check off its own base command. The operator lane is untouched:
// a human triggers and watches it, and `git commit` there is legitimate.
// ---------------------------------------------------------------------------
// Read-only git verbs. Allowlist, not denylist — git grows verbs, and an unknown
// verb must fail closed rather than inherit a permission nobody reviewed.
const UNATTENDED_GIT_SUBCOMMANDS = new Set([
'log', 'show', 'status', 'diff', 'blame', 'describe', 'rev-parse',
'branch', 'tag', 'remote', 'config', 'ls-files', 'shortlog',
]);
// `git config` only reads when asked to read; a bare `git config a.b c` writes.
const GIT_CONFIG_READ_FLAGS = new Set(['--get', '--get-all', '--get-regexp', '--get-urlmatch', '--list', '-l']);
// The three listing verbs above still expose a small mutating flag surface
// (`git branch -D`, `git tag -d`, `git remote remove`). Their listing forms stay
// allowed; these forms do not.
const GIT_BRANCH_MUTATING_FLAGS = new Set(['-d', '-D', '--delete', '-m', '-M', '--move', '-c', '-C', '--copy', '--set-upstream-to', '-u', '--unset-upstream', '--edit-description']);
const GIT_TAG_MUTATING_FLAGS = new Set(['-d', '--delete', '-a', '--annotate', '-s', '--sign', '-f', '--force', '-m', '--message', '-F', '--file']);
// `git branch <name>` / `git tag <name>` CREATE a ref; the same verbs only read
// when the positional is a filter for an explicit list mode. So a positional is
// admitted only alongside one of these.
const GIT_LIST_MODE_FLAGS = new Set(['-l', '--list', '--contains', '--no-contains', '--points-at', '--merged', '--no-merged']);
const GIT_REMOTE_READ_VERBS = new Set(['show', 'get-url']);
// `--output[=<file>]` on log/show/diff (and any verb sharing diff-options)
// writes the command's output to an arbitrary path — the same file-write
// primitive `find -fprint*` is denied for below (#12020). Checked for every
// verb rather than per verb so a newly allowlisted verb cannot inherit it.
// `--output-indicator-*` only changes diff markers and is not matched.
const GIT_OUTPUT_FLAG = '--output';
// `find` action flags: `-delete` removes files and `-exec`/`-ok` family runs
// arbitrary binaries, which would defeat the allowlist entirely. `-f*print*`
// writes attacker-chosen files. Everything else (`-name`, `-type`, `-maxdepth`,
// `-print`) only inspects.
const FIND_ACTION_FLAGS = new Set([
'-delete', '-exec', '-execdir', '-ok', '-okdir',
'-fls', '-fprint', '-fprint0', '-fprintf',
]);
// gh/glab write verbs are authenticated mutations against the tracker using the
// operator's own credentials, so only `<noun> list`, `<noun> view` and read-only
// `api` calls are admitted.
const GH_READ_VERBS = new Set(['list', 'view']);
const GH_METHOD_FLAGS = new Set(['-X', '--method']);
// gh/glab switch `api` to POST implicitly when a field flag is present, so a
// method check alone is not enough.
const GH_FIELD_FLAGS = new Set(['-f', '-F', '--field', '--raw-field', '--input']);
// Both CLIs parse flags with pflag, which also accepts a shorthand with its
// value attached (`-XPOST`, `-Fbody=@file`) and clustered after booleans
// (`-iXPOST`). Scanning a single-dash cluster: `-X` with anything but GET or
// a field shorthand rejects; another value-taking shorthand ends the scan
// (the rest is its value); an unknown letter fails closed. A cluster ending
// in `-X` (`-iX GET`) takes the method from the next argument, as pflag does.
const GH_API_VALUE_SHORTHANDS = new Set(['H', 'p', 'q', 't']);
const GH_API_BOOLEAN_SHORTHANDS = new Set(['i']);
const ghApiClusterWrites = (arg, next) => {
const cluster = arg.slice(1);
for (let i = 0; i < cluster.length; i += 1) {
const flag = cluster[i];
if (GH_API_BOOLEAN_SHORTHANDS.has(flag)) continue;
if (flag === 'X') {
const attached = cluster.slice(i + 1).replace(/^=/, '');
return (attached || next || '').toUpperCase() !== 'GET';
}
return !GH_API_VALUE_SHORTHANDS.has(flag);
}
return false;
};
const deny = (error) => ({ valid: false, error });
// True when `git branch` / `git tag` args only list refs: no mutating flag, and
// no bare positional unless an explicit list-mode flag makes it a filter.
function isGitRefListing(sub, rest) {
const mutating = sub === 'branch' ? GIT_BRANCH_MUTATING_FLAGS : GIT_TAG_MUTATING_FLAGS;
if (rest.some(a => mutating.has(a))) return false;
const hasPositional = rest.some(a => !a.startsWith('-'));
return !hasPositional || rest.some(a => GIT_LIST_MODE_FLAGS.has(a));
}
function validateUnattendedGit(args) {
const sub = args[0];
if (!sub) return deny("'git' needs a read-only subcommand on the unattended lane.");
// Global options (`-c key=val`, `--git-dir`, `--work-tree`, `--exec-path`,
// `--config-env`, `-C`) precede the verb and reconfigure what it runs
// against; the verb must be the first argument.
if (sub.startsWith('-')) {
return deny(`'git ${sub}' is not allowed on the unattended lane — global options before the subcommand are rejected; the first argument must be a read-only verb.`);
}
if (!UNATTENDED_GIT_SUBCOMMANDS.has(sub)) {
return deny(`'git ${sub}' is not allowed on the unattended lane — only read-only inspection subcommands are: ${[...UNATTENDED_GIT_SUBCOMMANDS].sort().join(', ')}.`);
}
const rest = args.slice(1);
const outputFlag = rest.find(a => a === GIT_OUTPUT_FLAG || a.startsWith(`${GIT_OUTPUT_FLAG}=`));
if (outputFlag) {
return deny(`'git ${sub} ${outputFlag}' is not allowed on the unattended lane — '--output' writes command output to a file.`);
}
if (sub === 'config' && !rest.some(a => GIT_CONFIG_READ_FLAGS.has(a))) {
return deny("'git config' is only allowed in its read form on the unattended lane (e.g. 'git config --get <key>').");
}
if ((sub === 'branch' || sub === 'tag') && !isGitRefListing(sub, rest)) {
return deny(`'git ${sub}' is only allowed in its listing form on the unattended lane — naming a ref (or a delete/move flag) writes to the repo.`);
}
if (sub === 'remote' && rest.length && !GIT_REMOTE_READ_VERBS.has(rest[0]) && !rest[0].startsWith('-')) {
return deny("'git remote' is only allowed in its listing form on the unattended lane (e.g. 'git remote -v', 'git remote show <name>').");
}
return { valid: true };
}
function validateUnattendedFind(args) {
const action = args.find(a => FIND_ACTION_FLAGS.has(a));
if (action) {
return deny(`'find ${action}' is not allowed on the unattended lane — it deletes, writes, or executes. Use inspection predicates ('-name', '-type', '-maxdepth', '-print') instead.`);
}
return { valid: true };
}
function validateUnattendedGhLike(base, args) {
const sub = args[0];
if (!sub) return deny(`'${base}' needs a read-only subcommand on the unattended lane.`);
if (sub === 'api') {
const rest = args.slice(1);
for (let i = 0; i < rest.length; i += 1) {
const arg = rest[i];
// `?? ''` keeps a trailing `-X` with no value from crashing here — and a
// methodless `-X` is malformed anyway, so failing closed is correct.
const method = GH_METHOD_FLAGS.has(arg) ? (rest[i + 1] ?? '')
: arg.startsWith('--method=') ? arg.slice('--method='.length)
: null;
if (method !== null && method.toUpperCase() !== 'GET') {
return deny(`'${base} api' is limited to GET on the unattended lane — '${method}' is an authenticated write.`);
}
if (GH_FIELD_FLAGS.has(arg) || /^--(?:field|raw-field|input)=/.test(arg)) {
return deny(`'${base} api ${arg}' is not allowed on the unattended lane — a field flag makes the request a POST.`);
}
if (method === null && /^-[^-]/.test(arg) && arg.length > 2 && ghApiClusterWrites(arg, rest[i + 1])) {
return deny(`'${base} api ${arg}' is not allowed on the unattended lane — a method or field shorthand with an attached value can make the request a write.`);
}
}
return { valid: true };
}
const verb = args[1];
if (!GH_READ_VERBS.has(verb)) {
return deny(`'${base} ${sub}${verb ? ` ${verb}` : ''}' is not allowed on the unattended lane — only '${base} <noun> list', '${base} <noun> view' and read-only '${base} api' are.`);
}
return { valid: true };
}
// Keyed by base command; a binary with no entry is accepted on membership alone.
// A Map, not an object literal — the key comes from the parsed command string,
// and a Map has no prototype chain for `constructor`/`__proto__` to resolve into.
const UNATTENDED_SUBCOMMAND_VALIDATORS = new Map([
['git', validateUnattendedGit],
['find', validateUnattendedFind],
['gh', (args) => validateUnattendedGhLike('gh', args)],
['glab', (args) => validateUnattendedGhLike('glab', args)],
]);
/**
* Shared shape/metacharacter/allowlist gate. Both public validators route
* through this so the two lanes can never disagree about parsing or about
* which shell metacharacters are rejected — only the allowlist differs.
* Returns { valid, error?, baseCommand?, args? }
*/
function validateAgainst(command, allowlist, allowlistSorted) {
if (!command || typeof command !== 'string') {
return { valid: false, error: 'Command is required' };
}
const trimmed = command.trim();
if (!trimmed) return { valid: false, error: 'Command cannot be empty' };
if (DANGEROUS_SHELL_CHARS.test(trimmed)) {
return { valid: false, error: 'Command contains disallowed shell characters' };
}
const parts = parseCommandArgs(trimmed);
const baseCommand = parts[0];
if (!allowlist.has(baseCommand)) {
return { valid: false, error: `Command '${baseCommand}' is not in the allowlist. Allowed: ${allowlistSorted.join(', ')}` };
}
return { valid: true, baseCommand, args: parts.slice(1) };
}
/**
* Validate a command against the operator-driven allowlist (the manual command
* runner, POST /api/commands/execute — a human triggers and watches each run).
* Returns { valid, error?, baseCommand?, args? }
*/
export function validateCommand(command) {
const check = validateAgainst(command, ALLOWED_COMMANDS, ALLOWED_COMMANDS_SORTED);
if (!check.valid) return check;
if (check.baseCommand === 'pm2') {
const pm2Check = validatePm2Command(check.args);
if (!pm2Check.valid) return pm2Check;
}
return check;
}
/**
* Validate a command for the UNATTENDED lane — a scheduled job executing a
* string that lives in persistent, attacker-reachable config with no human in
* the loop. Same parsing and metacharacter rules as `validateCommand`, but only
* `UNATTENDED_READONLY_COMMANDS` are admitted, so a config that lands `npx`,
* `curl` or `pip install` cannot reach a spawn. Multi-purpose binaries then get
* a per-binary subcommand check (`git`, `find`, `gh`, `glab`), so `git reset
* --hard`, `find . -delete` and `gh api -X POST` are rejected too. No pm2
* sub-check is needed — pm2 is not on the list at all.
* Returns { valid, error?, baseCommand?, args? }
*/
export function validateUnattendedCommand(command) {
const check = validateAgainst(command, UNATTENDED_READONLY_COMMANDS, UNATTENDED_READONLY_COMMANDS_SORTED);
if (!check.valid) return check;
const subCheck = UNATTENDED_SUBCOMMAND_VALIDATORS.get(check.baseCommand)?.(check.args);
if (subCheck && !subCheck.valid) return subCheck;
return check;
}
// Sensitive key names: a segment of the key, separated by `_`, `.` or `-`, so
// `API_TOKEN` and `github.token` match while `author` does not.
const SENSITIVE_KEY_WORDS = 'KEY|SECRET|TOKEN|PASSWORD|PASSPHRASE|MACAROON|CERT|CREDENTIAL|AUTH';
// JSON key/value pairs, e.g. `"SECRET_KEY": "value"` in `pm2 jlist` env blocks.
const SENSITIVE_ENV_PATTERN = new RegExp(`("(?:[a-z0-9]+_)*(?:${SENSITIVE_KEY_WORDS})(?:_[a-z0-9]+)*":\\s*)"[^"]+"`, 'gi');
// Assignment lines, e.g. `API_TOKEN=value` from a dotenv read or
// `github.token=value` from `git config --list` (#12019). Anchored to the
// line (horizontal whitespace only) so a value is only ever the remainder of
// its own line.
const SENSITIVE_ASSIGNMENT_PATTERN = new RegExp(`^([ \\t]*(?:export[ \\t]+)?(?:[a-z0-9]+[_.-])*(?:${SENSITIVE_KEY_WORDS})(?:[_.-][a-z0-9]+)*[ \\t]*=)(.+)$`, 'gim');
/**
* Redact sensitive values from command output before it is persisted,
* broadcast, or returned. Covers JSON key/value pairs and `KEY=value`
* assignment lines whose key names a secret. Shell-level leaks (env
* expansion, command substitution) are not covered — the allowlist and the
* metacharacter filter keep those out of the spawn in the first place.
*/
export function redactOutput(output) {
if (!output) return output;
return output
.replace(SENSITIVE_ENV_PATTERN, '$1"[REDACTED]"')
.replace(SENSITIVE_ASSIGNMENT_PATTERN, '$1[REDACTED]');
}