@wichayutdew/pi-workflows 0.1.1

package/src/policy/approved-commands.ts

@@ -0,0 +1,225 @@
+import { basename } from 'node:path';
+import type { BashApprovalSource } from '../config/types.ts';
+import {
+  parseRestrictedGitCommand,
+  tokenizeRestrictedCommand,
+} from './bash.ts';
+
+const SHELL_WRAPPERS = new Set([
+  'bash',
+  'env',
+  'exec',
+  'fish',
+  'sh',
+  'xargs',
+  'zsh',
+]);
+const REMOTE_EXECUTABLES = new Set(['curl', 'scp', 'ssh', 'rsync', 'wget']);
+const FORBIDDEN_LONG_PUSH_OPTIONS = [
+  '--force',
+  '--force-if-includes',
+  '--force-with-lease',
+  '--all',
+  '--delete',
+  '--mirror',
+  '--prune',
+  '--tags',
+] as const;
+const PUBLISH_EXECUTABLES = new Set(['bun', 'cargo', 'npm', 'pnpm', 'yarn']);
+const LOCAL_VERIFICATION_GIT_SUBCOMMANDS = new Set([
+  'add',
+  'branch',
+  'commit',
+  'diff',
+  'grep',
+  'log',
+  'ls-files',
+  'rev-parse',
+  'show',
+  'status',
+  'worktree',
+]);
+
+function hasDestructivePushShortOption(token: string): boolean {
+  return (
+    token.startsWith('-') &&
+    !token.startsWith('--') &&
+    (token.slice(1).includes('f') || token.slice(1).includes('d'))
+  );
+}
+
+function hasForbiddenLongPushOption(token: string): boolean {
+  if (!token.startsWith('--') || token === '--') return false;
+  const optionName = token.split('=', 1)[0] ?? token;
+  return FORBIDDEN_LONG_PUSH_OPTIONS.some((option) =>
+    option.startsWith(optionName),
+  );
+}
+
+function hasEmptyPushRefspecSide(token: string): boolean {
+  const separator = token.indexOf(':');
+  return separator >= 0 && (separator === 0 || separator === token.length - 1);
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function parseJsonDocuments(text: string): unknown[] {
+  const documents: unknown[] = [];
+  const trimmed = text.trim();
+  if (trimmed.startsWith('{') || trimmed.startsWith('[')) {
+    try {
+      documents.push(JSON.parse(trimmed));
+    } catch {
+      // Markdown artifacts are normally handled by fenced JSON below.
+    }
+  }
+
+  const fences = /```(?:json)?[ \t]*\r?\n([\s\S]*?)```/gi;
+  for (const match of text.matchAll(fences)) {
+    const candidate = match[1]?.trim();
+    if (!candidate) continue;
+    try {
+      documents.push(JSON.parse(candidate));
+    } catch {
+      // Other fenced examples are not approval contracts.
+    }
+  }
+  return documents;
+}
+
+function verificationCommands(
+  value: unknown,
+  role: 'worker' | 'reviewer',
+): string[] {
+  if (!isObject(value) || !Array.isArray(value.repositories)) return [];
+  const commands: string[] = [];
+  for (const repository of value.repositories) {
+    if (!isObject(repository) || !Array.isArray(repository[role])) continue;
+    for (const check of repository[role]) {
+      if (isObject(check) && typeof check.command === 'string') {
+        commands.push(check.command);
+      }
+    }
+  }
+  return commands;
+}
+
+function remoteActionCommands(value: unknown): string[] {
+  if (!isObject(value) || !Array.isArray(value.actions)) return [];
+  const commands: string[] = [];
+  for (const action of value.actions) {
+    if (
+      isObject(action) &&
+      action.toolName === 'bash' &&
+      isObject(action.input) &&
+      typeof action.input.command === 'string'
+    ) {
+      commands.push(action.input.command);
+    }
+  }
+  return commands;
+}
+
+function containsPublishOperation(tokens: readonly string[]): boolean {
+  return tokens
+    .slice(1)
+    .some((token) => token.length >= 3 && 'publish'.startsWith(token));
+}
+
+function safeVerificationCommand(command: string): boolean {
+  const parsed = tokenizeRestrictedCommand(command);
+  if (!parsed.tokens) return false;
+  const executable = basename(parsed.tokens[0] ?? '');
+  if (SHELL_WRAPPERS.has(executable) || REMOTE_EXECUTABLES.has(executable)) {
+    return false;
+  }
+  const subcommand =
+    executable === 'git'
+      ? parseRestrictedGitCommand(parsed.tokens)?.subcommand
+      : parsed.tokens[1];
+  if (
+    executable === 'git' &&
+    (!subcommand || !LOCAL_VERIFICATION_GIT_SUBCOMMANDS.has(subcommand))
+  ) {
+    return false;
+  }
+  if (executable === 'gh' || executable === 'glab') return false;
+  if (
+    PUBLISH_EXECUTABLES.has(executable) &&
+    containsPublishOperation(parsed.tokens)
+  ) {
+    return false;
+  }
+  if (executable === 'docker' && parsed.tokens.slice(1).includes('push')) {
+    return false;
+  }
+  return true;
+}
+
+function safeRemoteActionCommand(command: string): boolean {
+  const parsed = tokenizeRestrictedCommand(command);
+  if (!parsed.tokens) return false;
+  const executable = parsed.tokens[0];
+  const subcommand =
+    executable === 'git'
+      ? parseRestrictedGitCommand(parsed.tokens)?.subcommand
+      : parsed.tokens[1];
+  if (executable === 'gh' || executable === 'glab') {
+    if (subcommand !== 'api') return false;
+    return !parsed.tokens.slice(2).some((token, index, apiTokens) => {
+      const upper = token.toUpperCase();
+      return (
+        upper === '--METHOD=DELETE' ||
+        upper === '-XDELETE' ||
+        ((upper === '--METHOD' || upper === '-X') &&
+          apiTokens[index + 1]?.toUpperCase() === 'DELETE')
+      );
+    });
+  }
+  if (executable !== 'git' || subcommand !== 'push') return false;
+  return !parsed.tokens
+    .slice(1)
+    .some(
+      (token) =>
+        hasForbiddenLongPushOption(token) ||
+        token.startsWith('+') ||
+        hasEmptyPushRefspecSide(token) ||
+        hasDestructivePushShortOption(token),
+    );
+}
+
+/**
+ * Extract exact Bash capabilities from machine-readable JSON that a
+ * human review gate already displayed and approved.
+ */
+export function extractApprovedBashCommands(
+  artifact: string,
+  sources: readonly BashApprovalSource[],
+): string[] {
+  if (!artifact.trim() || sources.length === 0) return [];
+  const commands: string[] = [];
+  for (const document of parseJsonDocuments(artifact)) {
+    for (const source of sources) {
+      if (source === 'verification-worker') {
+        commands.push(
+          ...verificationCommands(document, 'worker').filter(
+            safeVerificationCommand,
+          ),
+        );
+      } else if (source === 'verification-reviewer') {
+        commands.push(
+          ...verificationCommands(document, 'reviewer').filter(
+            safeVerificationCommand,
+          ),
+        );
+      } else {
+        commands.push(
+          ...remoteActionCommands(document).filter(safeRemoteActionCommand),
+        );
+      }
+    }
+  }
+  return [...new Set(commands)];
+}

package/src/policy/bash.ts

@@ -0,0 +1,355 @@
+import { basename } from 'node:path';
+import type { BashPermission, BashRule } from '../config/types.ts';
+
+const UNQUOTED_SHELL_META = new Set([
+  ';',
+  '&',
+  '|',
+  '<',
+  '>',
+  '\n',
+  '\r',
+  '`',
+  '$',
+  '(',
+  ')',
+  '{',
+  '}',
+  '#',
+  '\0',
+]);
+const PATHNAME_EXPANSION = new Set(['*', '?', '[', ']', '~']);
+const WRAPPER_COMMANDS = new Set([
+  'bash',
+  'builtin',
+  'command',
+  'env',
+  'exec',
+  'fish',
+  'sh',
+  'time',
+  'xargs',
+  'zsh',
+]);
+const READ_ONLY_EXECUTABLES = new Set([
+  'grep',
+  'head',
+  'ls',
+  'pwd',
+  'rg',
+  'stat',
+  'tail',
+  'wc',
+]);
+const READ_ONLY_GIT_SUBCOMMANDS = new Set([
+  'diff',
+  'grep',
+  'log',
+  'ls-files',
+  'rev-parse',
+  'show',
+  'status',
+]);
+const DANGEROUS_GIT_OPTIONS = [
+  '--config-env',
+  '--exec',
+  '--ext-diff',
+  '--open-files-in-pager',
+  '--output',
+  '--textconv',
+];
+const DANGEROUS_GIT_SHORT_OPTIONS: ReadonlyArray<{
+  subcommand: string;
+  option: string;
+}> = [
+  // `git grep -O<pager>` executes the supplied pager command.
+  { subcommand: 'grep', option: '-O' },
+];
+const HOSTED_API_MUTATION_OPTIONS = [
+  '--field',
+  '--form',
+  '--input',
+  '--method',
+  '--raw-field',
+  '-F',
+  '-X',
+  '-f',
+];
+
+export interface BashAuthorization {
+  allowed: boolean;
+  reason?: string;
+  tokens?: string[];
+}
+
+function reject(reason: string): BashAuthorization {
+  return { allowed: false, reason };
+}
+
+/**
+ * Tokenize the deliberately small shell subset accepted by restricted modes.
+ * Shell operators, substitutions, expansions, and comments are rejected first.
+ */
+export function tokenizeRestrictedCommand(command: string): ValidationTokens {
+  if (!command.trim()) return { error: 'empty Bash command' };
+
+  const tokens: string[] = [];
+  let token = '';
+  let quote: "'" | '"' | undefined;
+  let escaping = false;
+  let tokenStarted = false;
+
+  for (const character of command) {
+    if (quote === "'") {
+      if (character === '\n' || character === '\r' || character === '\0') {
+        return { error: 'multiline and null characters are not allowed' };
+      }
+      if (character === "'") {
+        quote = undefined;
+      } else {
+        token += character;
+      }
+      tokenStarted = true;
+      continue;
+    }
+    if (quote === '"') {
+      if (character === '\n' || character === '\r' || character === '\0') {
+        return { error: 'multiline and null characters are not allowed' };
+      }
+      if (character === '"') {
+        quote = undefined;
+      } else if (character === '$' || character === '`' || character === '\\') {
+        return {
+          error:
+            'substitutions and escapes are not allowed inside double quotes',
+        };
+      } else {
+        token += character;
+      }
+      tokenStarted = true;
+      continue;
+    }
+    if (escaping) {
+      if (character === '\n' || character === '\r' || character === '\0') {
+        return { error: 'multiline and null characters are not allowed' };
+      }
+      token += character;
+      escaping = false;
+      tokenStarted = true;
+      continue;
+    }
+    if (character === '\\') {
+      escaping = true;
+      tokenStarted = true;
+      continue;
+    }
+    if (quote) {
+      if (character === quote) {
+        quote = undefined;
+      } else {
+        token += character;
+      }
+      tokenStarted = true;
+      continue;
+    }
+    if (character === "'" || character === '"') {
+      quote = character;
+      tokenStarted = true;
+      continue;
+    }
+    if (UNQUOTED_SHELL_META.has(character)) {
+      return {
+        error:
+          'shell operators, substitutions, expansions, and comments are not allowed',
+      };
+    }
+    if (PATHNAME_EXPANSION.has(character)) {
+      return {
+        error: 'unquoted pathname and tilde expansion are not allowed',
+      };
+    }
+    if (/\s/.test(character)) {
+      if (tokenStarted) {
+        tokens.push(token);
+        token = '';
+        tokenStarted = false;
+      }
+      continue;
+    }
+    token += character;
+    tokenStarted = true;
+  }
+
+  if (escaping) return { error: 'trailing Bash escape is not allowed' };
+  if (quote) return { error: 'unterminated Bash quote' };
+  if (tokenStarted) tokens.push(token);
+  if (tokens.length === 0) return { error: 'empty Bash command' };
+  return { tokens };
+}
+
+interface ValidationTokens {
+  tokens?: string[];
+  error?: string;
+}
+
+export interface RestrictedGitCommand {
+  subcommand: string;
+  subcommandIndex: number;
+}
+
+export function parseRestrictedGitCommand(
+  tokens: readonly string[],
+): RestrictedGitCommand | undefined {
+  let index = 1;
+  while (index < tokens.length) {
+    const token = tokens[index];
+    if (token === '-C') {
+      if (!tokens[index + 1]) return undefined;
+      index += 2;
+      continue;
+    }
+    if (token === '--no-pager') {
+      index += 1;
+      continue;
+    }
+    if (!token || token.startsWith('-')) return undefined;
+    return { subcommand: token, subcommandIndex: index };
+  }
+  return undefined;
+}
+
+function matchesRule(tokens: readonly string[], rule: BashRule): boolean {
+  if (tokens[0] !== rule.executable) return false;
+  return rule.argsPrefix.every(
+    (expected, index) => tokens[index + 1] === expected,
+  );
+}
+
+function hasOption(tokens: readonly string[], option: string): boolean {
+  return tokens.some(
+    (token) => token === option || token.startsWith(`${option}=`),
+  );
+}
+
+function authorizeReadOnly(tokens: readonly string[]): BashAuthorization {
+  const executable = tokens[0] ?? '';
+  if (READ_ONLY_EXECUTABLES.has(executable)) {
+    if (
+      executable === 'rg' &&
+      (hasOption(tokens, '--pre') || hasOption(tokens, '--pre-glob'))
+    ) {
+      return reject('rg preprocessors are not allowed in read-only mode');
+    }
+    return { allowed: true, tokens: [...tokens] };
+  }
+
+  if (executable !== 'git') {
+    return reject(`"${executable}" is not in the read-only Bash preset`);
+  }
+  const gitCommand = parseRestrictedGitCommand(tokens);
+  if (!gitCommand || !READ_ONLY_GIT_SUBCOMMANDS.has(gitCommand.subcommand)) {
+    return reject(
+      `git subcommand "${gitCommand?.subcommand ?? ''}" is not read-only`,
+    );
+  }
+  const dangerousOption = DANGEROUS_GIT_OPTIONS.find((option) =>
+    hasOption(tokens, option),
+  );
+  if (dangerousOption) {
+    return reject(
+      `git option "${dangerousOption}" is not allowed in read-only mode`,
+    );
+  }
+  const dangerousShortOption = DANGEROUS_GIT_SHORT_OPTIONS.find(
+    ({ subcommand: matchedSubcommand, option }) =>
+      gitCommand.subcommand === matchedSubcommand &&
+      tokens
+        .slice(gitCommand.subcommandIndex + 1)
+        .some((token) => token === option || token.startsWith(option)),
+  );
+  if (dangerousShortOption) {
+    return reject(
+      `git option "${dangerousShortOption.option}" is not allowed in read-only mode`,
+    );
+  }
+  return { allowed: true, tokens: [...tokens] };
+}
+
+function usesReadOnlyPreset(tokens: readonly string[]): boolean {
+  const executable = tokens[0] ?? '';
+  return (
+    READ_ONLY_EXECUTABLES.has(executable) ||
+    (executable === 'git' &&
+      READ_ONLY_GIT_SUBCOMMANDS.has(
+        parseRestrictedGitCommand(tokens)?.subcommand ?? '',
+      ))
+  );
+}
+
+function authorizeHostedApiRead(tokens: readonly string[]): BashAuthorization {
+  const executable = basename(tokens[0] ?? '');
+  if ((executable !== 'gh' && executable !== 'glab') || tokens[1] !== 'api') {
+    return { allowed: true, tokens: [...tokens] };
+  }
+  const mutationOption = HOSTED_API_MUTATION_OPTIONS.find((option) =>
+    tokens
+      .slice(2)
+      .some(
+        (token) =>
+          token === option ||
+          token.startsWith(`${option}=`) ||
+          (option.length === 2 && token.startsWith(option)),
+      ),
+  );
+  if (mutationOption) {
+    return reject(
+      `${executable} api option "${mutationOption}" is not allowed by a static read-only rule`,
+    );
+  }
+  return { allowed: true, tokens: [...tokens] };
+}
+
+export function authorizeBash(
+  command: string,
+  permission: BashPermission,
+  approvedCommands: readonly string[] = [],
+): BashAuthorization {
+  if (
+    (permission.approvedSources?.length ?? 0) > 0 &&
+    approvedCommands.includes(command)
+  ) {
+    return { allowed: true };
+  }
+  if (permission.mode === 'unrestricted') {
+    return { allowed: true };
+  }
+  if (permission.mode === 'deny') {
+    return reject('Bash is disabled for this workflow step');
+  }
+
+  const parsed = tokenizeRestrictedCommand(command);
+  if (!parsed.tokens) return reject(parsed.error ?? 'invalid Bash command');
+  const executable = parsed.tokens[0] ?? '';
+  if (WRAPPER_COMMANDS.has(basename(executable))) {
+    return reject(
+      `shell wrapper "${executable}" is not allowed in restricted mode`,
+    );
+  }
+  if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(executable)) {
+    return reject('environment assignments are not allowed in restricted mode');
+  }
+
+  if (permission.mode === 'read-only') {
+    return authorizeReadOnly(parsed.tokens);
+  }
+  const rule = permission.allow.find((candidate) =>
+    matchesRule(parsed.tokens ?? [], candidate),
+  );
+  if (!rule) {
+    return reject(`command does not match this step's Bash allow-list`);
+  }
+  if (usesReadOnlyPreset(parsed.tokens)) {
+    return authorizeReadOnly(parsed.tokens);
+  }
+  return authorizeHostedApiRead(parsed.tokens);
+}

package/src/policy/completion-batch.ts

@@ -0,0 +1,36 @@
+interface ToolCallContent {
+  type: 'toolCall';
+  id: string;
+  name: string;
+}
+
+function toolCalls(message: unknown): ToolCallContent[] {
+  if (message === null || typeof message !== 'object') return [];
+  const candidate = message as { role?: unknown; content?: unknown };
+  if (candidate.role !== 'assistant' || !Array.isArray(candidate.content))
+    return [];
+
+  return candidate.content.filter(
+    (item): item is ToolCallContent =>
+      item !== null &&
+      typeof item === 'object' &&
+      (item as { type?: unknown }).type === 'toolCall' &&
+      typeof (item as { id?: unknown }).id === 'string' &&
+      typeof (item as { name?: unknown }).name === 'string',
+  );
+}
+
+/**
+ * A completion changes the active step and its permissions. It is therefore
+ * safe only when it is the sole tool call in an assistant message.
+ */
+export function invalidCompletionCallIds(
+  message: unknown,
+  completionTool: string,
+): Set<string> {
+  const calls = toolCalls(message);
+  if (calls.length === 1 && calls[0]?.name === completionTool) return new Set();
+  return new Set(
+    calls.filter((call) => call.name === completionTool).map((call) => call.id),
+  );
+}

package/src/policy/immutable-input.ts

@@ -0,0 +1,18 @@
+/**
+ * Pi intentionally lets later extensions mutate tool inputs. Once this harness
+ * authorizes a workflow call, freeze the validated argument graph so a later
+ * handler cannot change what the tool will execute.
+ */
+export function freezeToolInput<T extends object>(input: T): T {
+  const seen = new WeakSet<object>();
+
+  const freeze = (value: unknown): void => {
+    if (value === null || typeof value !== 'object' || seen.has(value)) return;
+    seen.add(value);
+    for (const child of Object.values(value)) freeze(child);
+    Object.freeze(value);
+  };
+
+  freeze(input);
+  return input;
+}