@wichayutdew/pi-workflows 0.3.0 → 1.0.1

package/src/policy/bash-types.ts

@@ -0,0 +1,20 @@
+export type BashAuthorization = {
+  readonly allowed: boolean;
+  readonly reason?: string;
+  readonly tokens?: Array<string>;
+};
+
+export type RestrictedCommandTokens =
+  | {
+      readonly tokens: Array<string>;
+      readonly error?: never;
+    }
+  | {
+      readonly tokens?: never;
+      readonly error: string;
+    };
+
+export type RestrictedGitCommand = {
+  readonly subcommand: string;
+  readonly subcommandIndex: number;
+};

package/src/policy/bash.ts

@@ -1,346 +1,4 @@
-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 (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);
-}
+export { authorizeBash } from './bash-authorization.ts';
+export type { BashAuthorization, RestrictedGitCommand } from './bash-types.ts';
+export { tokenizeRestrictedCommand } from './restricted-command.ts';
+export { parseRestrictedGitCommand } from './restricted-git.ts';

package/src/policy/completion-batch.ts

@@ -1,28 +1,33 @@
-interface ToolCallContent {
-  type: 'toolCall';
-  id: string;
-  name: string;
-}
+type ToolCallContent = {
+  readonly type: 'toolCall';
+  readonly id: string;
+  readonly name: string;
+};
+
+const isRecord = (value: unknown): value is Readonly<Record<string, unknown>> =>
+  value !== null && typeof value === 'object' && !Array.isArray(value);
 
-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))
+const toolCalls = (message: unknown): Array<ToolCallContent> => {
+  if (!isRecord(message)) return [];
+  if (message.role !== 'assistant' || !Array.isArray(message.content))
     return [];
 
-  return candidate.content.filter(
+  return message.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',
+      isRecord(item) &&
+      item.type === 'toolCall' &&
+      typeof item.id === 'string' &&
+      typeof item.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.
+ *
+ * @param message - Assistant message to validate.
+ * @param completionTool - Workflow completion tool name.
+ * @returns IDs of invalid completion calls.
  */
 export function invalidCompletionCallIds(
   message: unknown,

package/src/policy/immutable-input.ts

@@ -2,9 +2,12 @@
  * 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.
+ *
+ * @param input - Validated tool input to freeze recursively.
+ * @returns The same input after it has been frozen.
  */
-export function freezeToolInput<T extends object>(input: T): T {
-  const seen = new WeakSet<object>();
+export function freezeToolInput<TInput extends object>(input: TInput): TInput {
+  const seen = new WeakSet();
 
   const freeze = (value: unknown): void => {
     if (value === null || typeof value !== 'object' || seen.has(value)) return;

package/src/policy/mcp-authorization.ts

@@ -0,0 +1,71 @@
+import type { ToolAuthorization } from './tool-types.ts';
+
+const UNSUPPORTED_MCP_PROXY_FIELDS = [
+  'action',
+  'connect',
+  'describe',
+  'search',
+  'regex',
+  'includeSchemas',
+] as const;
+
+const reject = (reason: string): ToolAuthorization => ({
+  allowed: false,
+  reason,
+});
+
+const selectorAllows = (
+  selectors: ReadonlyArray<string>,
+  server: string,
+  tool: string,
+): boolean =>
+  selectors.some((selector) => {
+    const separator = selector.indexOf('/');
+    if (separator === -1) return selector === server;
+    return (
+      selector.slice(0, separator) === server &&
+      selector.slice(separator + 1) === tool
+    );
+  });
+
+/**
+ * Authorizes an explicit MCP proxy server and tool selection.
+ *
+ * Discovery and other broad proxy modes are disabled so selectors cannot be
+ * widened at runtime.
+ *
+ * @param input - MCP proxy input.
+ * @param selectors - Allowed `server` or `server/tool` selectors.
+ * @returns The authorization decision.
+ */
+export const authorizeMcpProxy = (
+  input: Readonly<Record<string, unknown>>,
+  selectors: ReadonlyArray<string>,
+): ToolAuthorization => {
+  if (selectors.length === 0) {
+    return reject('MCP access is disabled for this workflow step');
+  }
+
+  const unsupportedMode = UNSUPPORTED_MCP_PROXY_FIELDS.find(
+    (field) => input[field] !== undefined,
+  );
+  if (unsupportedMode) {
+    return reject(
+      `MCP proxy mode "${unsupportedMode}" is disabled; use an explicit server and tool`,
+    );
+  }
+  if (typeof input.server !== 'string' || !input.server.trim()) {
+    return reject('MCP proxy calls must name an explicit server');
+  }
+  if (typeof input.tool !== 'string' || !input.tool.trim()) {
+    return reject('MCP proxy calls must name an explicit tool');
+  }
+
+  const server = input.server.trim();
+  const tool = input.tool.trim();
+  return selectorAllows(selectors, server, tool)
+    ? { allowed: true }
+    : reject(
+        `MCP tool "${server}/${tool}" is not allowed for this workflow step`,
+      );
+};

package/src/policy/restricted-command.ts

@@ -0,0 +1,141 @@
+import type { RestrictedCommandTokens } from './bash-types.ts';
+
+const UNQUOTED_SHELL_METACHARACTERS: ReadonlySet<string> = new Set([
+  ';',
+  '&',
+  '|',
+  '<',
+  '>',
+  '\n',
+  '\r',
+  '`',
+  '$',
+  '(',
+  ')',
+  '{',
+  '}',
+  '#',
+  '\0',
+]);
+const PATHNAME_EXPANSION_CHARACTERS: ReadonlySet<string> = new Set([
+  '*',
+  '?',
+  '[',
+  ']',
+  '~',
+]);
+
+type Quote = "'" | '"';
+
+const invalidCharacter = (character: string): string | undefined => {
+  if (character === '\n' || character === '\r' || character === '\0') {
+    return 'multiline and null characters are not allowed';
+  }
+  return undefined;
+};
+
+/**
+ * Tokenizes the deliberately small shell subset accepted by restricted modes.
+ *
+ * Shell operators, substitutions, expansions, and comments are rejected
+ * before authorization rules are evaluated.
+ *
+ * @param command - Command text to tokenize.
+ * @returns Parsed tokens or a validation error.
+ */
+export const tokenizeRestrictedCommand = (
+  command: string,
+): RestrictedCommandTokens => {
+  if (!command.trim()) return { error: 'empty Bash command' };
+
+  const tokens: Array<string> = [];
+  let token = '';
+  let quote: Quote | undefined;
+  let isEscaping = false;
+  let isTokenStarted = false;
+
+  for (const character of command) {
+    if (quote === "'") {
+      const error = invalidCharacter(character);
+      if (error) return { error };
+
+      if (character === "'") {
+        quote = undefined;
+      } else {
+        token += character;
+      }
+      isTokenStarted = true;
+      continue;
+    }
+
+    if (quote === '"') {
+      const error = invalidCharacter(character);
+      if (error) return { error };
+
+      if (character === '"') {
+        quote = undefined;
+      } else if (character === '$' || character === '`' || character === '\\') {
+        return {
+          error:
+            'substitutions and escapes are not allowed inside double quotes',
+        };
+      } else {
+        token += character;
+      }
+      isTokenStarted = true;
+      continue;
+    }
+
+    if (isEscaping) {
+      const error = invalidCharacter(character);
+      if (error) return { error };
+
+      token += character;
+      isEscaping = false;
+      isTokenStarted = true;
+      continue;
+    }
+
+    if (character === '\\') {
+      isEscaping = true;
+      isTokenStarted = true;
+      continue;
+    }
+
+    if (character === "'" || character === '"') {
+      quote = character;
+      isTokenStarted = true;
+      continue;
+    }
+
+    if (UNQUOTED_SHELL_METACHARACTERS.has(character)) {
+      return {
+        error:
+          'shell operators, substitutions, expansions, and comments are not allowed',
+      };
+    }
+
+    if (PATHNAME_EXPANSION_CHARACTERS.has(character)) {
+      return {
+        error: 'unquoted pathname and tilde expansion are not allowed',
+      };
+    }
+
+    if (/\s/u.test(character)) {
+      if (isTokenStarted) {
+        tokens.push(token);
+        token = '';
+        isTokenStarted = false;
+      }
+      continue;
+    }
+
+    token += character;
+    isTokenStarted = true;
+  }
+
+  if (isEscaping) return { error: 'trailing Bash escape is not allowed' };
+  if (quote) return { error: 'unterminated Bash quote' };
+  if (isTokenStarted) tokens.push(token);
+  return tokens.length > 0 ? { tokens } : { error: 'empty Bash command' };
+};

package/src/policy/restricted-git.ts

@@ -0,0 +1,30 @@
+import type { RestrictedGitCommand } from './bash-types.ts';
+
+/**
+ * Finds the Git subcommand in a tokenized restricted command.
+ *
+ * Only the global options deliberately supported by the policy are skipped.
+ *
+ * @param tokens - Tokenized Git command.
+ * @returns The subcommand and its index, or `undefined` for an invalid shape.
+ */
+export const parseRestrictedGitCommand = (
+  tokens: ReadonlyArray<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;
+};