API Reference — RFC-0043 UCVG (Untrusted-Contributor Verification Gate)

/** RFC-0022 `reviewerAuthorityModel` values that affect UCVG engagement. */
type ReviewerAuthorityModel = 'open' | 'allowlist' | 'allowlist+role';

/** Classification outcome. */
type TrustClassification = 'trusted' | 'untrusted';

/**
 * Reason paired with the trust classification for audit/event logging.
 * Maps to: OQ-1 precedence rules.
 */
type TrustReason =
  | 'author-in-allowlist'          // found in .ai-sdlc/trusted-reviewers.yaml
  | 'reviewerAuthorityModel-open'  // open model → everyone trusted
  | 'fork-pr-always-untrusted'     // fork PR not overridden by allowlist
  | 'author-not-in-allowlist';     // allowlist/allowlist+role, not in file

interface TrustResult {
  classification: TrustClassification;
  reason: TrustReason;
  /** The PR author login that was evaluated. */
  author: string;
  /** The effective reviewer authority model consulted. */
  reviewerAuthorityModel: ReviewerAuthorityModel;
  /** Author logins found in the allowlist at evaluation time (for audit). */
  allowlistedAuthors: string[];
}

interface TrustClassifierInput {
  /** GitHub login of the PR author. */
  author: string;
  /** True when the PR was opened from a forked repo. */
  isFork: boolean;
  /**
   * RFC-0022 reviewer authority model from `.ai-sdlc/compliance.yaml`.
   * Defaults to `'open'` when not supplied.
   */
  reviewerAuthorityModel?: ReviewerAuthorityModel;
  /**
   * Absolute path to the repo root.
   * Used to resolve `.ai-sdlc/trusted-reviewers.yaml`.
   * Defaults to `process.cwd()`.
   */
  workDir?: string;
}

import { classifyTrust } from 'pipeline-cli/src/pipeline/trust-classifier.js';

const result = classifyTrust({
  author: 'alice-contrib',
  isFork: true,
  reviewerAuthorityModel: 'allowlist',
  workDir: '/path/to/repo',
});
// result.classification: 'trusted' | 'untrusted'
// result.reason: 'author-in-allowlist' | ...

/** Outcome of the AST gate evaluation. */
type AstGateOutcome = 'pass' | 'abort-protected-path';

interface AstGateResult {
  outcome: AstGateOutcome;
  /** Paths that triggered the abort (empty on pass). */
  offendingPaths: string[];
  /** Content heuristic findings (empty on pass). */
  heuristicFindings: HeuristicFinding[];
}

interface HeuristicFinding {
  type: 'packageJsonLifecycleScript' | 'newGithubActionUses';
  path: string;
  detail: string;
}

/** Content heuristic action: abort or warn. */
type HeuristicAction = 'abort' | 'warn';

/** Adopter-configurable AST gate configuration. */
interface AstGateConfig {
  /** Paths that trigger `abort-protected-path` on mutation (deny wins). */
  protectedPaths: string[];
  /** Only files matching these globs may change in an untrusted PR. */
  allowedMutationGlobs: string[];
  contentHeuristics: {
    /** Abort when `preinstall`/`postinstall`/`prepare` are added to package.json. */
    packageJsonLifecycleScripts: HeuristicAction;
    /** Abort when a new `uses:` reference appears in file content. */
    newGithubActionUses: HeuristicAction;
  };
}

/** A single changed file in the PR diff. */
interface ChangedFile {
  /** Repo-relative file path. */
  path: string;
  status: 'added' | 'modified' | 'deleted' | 'renamed';
  /** File content AFTER the change (for content heuristics). Optional. */
  afterContent?: string;
  /** File content BEFORE the change (for detecting additions). Optional. */
  beforeContent?: string;
}

/** Default protected paths per RFC-0043 §Stage 1. Deny wins. */
const DEFAULT_PROTECTED_PATHS: readonly string[];

/** Default allowed mutation globs per RFC-0043 §Stage 1. */
const DEFAULT_ALLOWED_MUTATION_GLOBS: readonly string[];

/** Default content heuristics. */
const DEFAULT_CONTENT_HEURISTICS: AstGateConfig['contentHeuristics'];

/** Combined default config. */
const DEFAULT_AST_GATE_CONFIG: AstGateConfig;

/** The five supported sandbox drivers per RFC-0043 OQ-5 resolution. */
type SandboxDriverKind = 'docker' | 'podman' | 'kata' | 'gvisor' | 'microvm';

/** RFC-0022 compliance regimes that force a minimum isolation level. */
type ComplianceRegime = 'hipaa' | 'fedramp-high' | 'pci-dss-level-1' | 'none';

/** Sandbox configuration. Loaded from `.ai-sdlc/untrusted-pr-gate.yaml`. */
interface SandboxConfig {
  /** Which compute driver to use. Default: `docker`. */
  sandboxDriver: SandboxDriverKind;
  /** Differential test configuration including resource limits. */
  differentialTest: DifferentialTestConfig;
  /** RFC-0022 compliance regime (auto-overrides driver for HIPAA/FedRAMP/PCI). */
  complianceRegime?: ComplianceRegime;
  /** CI or local deployment mode per OQ-2. Default: `ci`. */
  deployment?: 'ci' | 'local';
}

interface ResourceLimits {
  /** Wall-clock timeout in seconds. Default: 600 (10 min). */
  wallClockSeconds: number;
  /** CPU cores. Default: 2. */
  cpuCores: number;
  /** Memory in megabytes. Default: 4096 (4 GB). */
  memoryMb: number;
  /** Per-test timeout in seconds. Optional adopter refinement. */
  perTestTimeoutSeconds?: number;
}

interface DifferentialTestConfig {
  resourceLimits: ResourceLimits;
}

/** Input for a sandbox spawn request. */
interface SandboxSpawnInput {
  /** Absolute path to the OpenShell policy file. */
  policyFilePath: string;
  /** The PR diff to apply (unified diff format). */
  prDiff: string;
  /** URL or local path of the clean upstream main to clone. */
  upstreamMainRef: string;
  /** Resource limits to enforce. */
  resourceLimits: ResourceLimits;
  /** The PR number being tested (for resource breach event attribution). */
  prNumber: number;
  /**
   * Environment variables to inject into the sandbox.
   * SECURITY CONSTRAINT: MUST NOT include signing-key.pem, write-scoped
   * GITHUB_TOKEN, NPM_TOKEN, or AI_SDLC_PAT.
   */
  sandboxEnv?: Record<string, string>;
}

type ResourceBreachType = 'wall-clock' | 'memory' | 'cpu';

/** Emitted when the sandbox breaches a resource limit. */
interface ResourceBreachEvent {
  type: 'ResourceBreach';
  breachType: ResourceBreachType;
  /** The configured limit that was exceeded. */
  limit: number;
  /** The unit of the limit (seconds, MB, cores). */
  limitUnit: string;
  /** The observed value at breach time (may be approximate). */
  observedValue?: number;
  prNumber: number;
  ts: string;
}

/** Default resource limits per OQ-3 resolution. */
const DEFAULT_RESOURCE_LIMITS: ResourceLimits;  // 600s / 2 CPU / 4096 MB

/** Default sandbox config: docker driver, OQ-3 limits, no regime, CI deployment. */
const DEFAULT_SANDBOX_CONFIG: SandboxConfig;

type SandboxResult =
  | { outcome: 'success'; differentialTest: DifferentialTestResult; durationMs: number }
  | { outcome: 'resource-breach'; breach: ResourceBreachEvent }
  | { outcome: 'error'; error: string };

interface RunSandboxInput {
  prNumber: number;
  prDiff: string;
  upstreamMainRef: string;
  config: SandboxConfig;
  workDir?: string;
  driverOverride?: SandboxDriver;
  policyFilePath?: string;
}

interface SandboxDriver {
  readonly kind: SandboxDriverKind;
  spawn(input: SandboxSpawnInput): Promise<SandboxResult>;
  teardown(): Promise<void>;
}

/** The three reviewer roles in the RFC-0010 §13 matrix. */
type ReviewerRole = 'code' | 'test' | 'security';

/** Injection attempt category — maps to the five corpus categories (AC-5). */
type InjectionCategory =
  | 'direct-instruction'
  | 'hidden-content'
  | 'code-comment'
  | 'markdown-formatted'
  | 'multi-language';

interface InjectionMatch {
  category: InjectionCategory;
  matchedText: string;   // truncated to 200 chars
  lineIndex?: number;    // 0-indexed line within the diff
}

interface InjectionDetectionResult {
  detected: boolean;
  matches: InjectionMatch[];
}

/** Opening delimiter marker for untrusted PR diff content. */
const DIFF_OPEN_MARKER: string;   // '<<<UNTRUSTED_PR_DIFF>>>'

/** Closing delimiter marker for untrusted PR diff content. */
const DIFF_CLOSE_MARKER: string;  // '<<<END_UNTRUSTED_PR_DIFF>>>'

/** Decision Catalog summary for corpus extension requests. */
const INJECTION_CORPUS_EXTENSION_REQUEST_SUMMARY: string;
// = 'prompt-injection-corpus-extension-request'

const framedDiff = buildHardenedDiffSection(rawPrDiff);
const prompt = reviewerTemplateBody.replace('{{PR_DIFF}}', framedDiff);

/**
 * Result of validating an untrusted-PR report artifact.
 * Discriminated union: { valid: true, report } | { valid: false, error }.
 */
type ReportValidationResult =
  | { valid: true; report: UntrustedPrReport }
  | { valid: false; error: string };

/** Inferred TypeScript type from UntrustedPrReportSchema. */
type UntrustedPrReport = {
  schemaVersion: 'untrusted-pr-report.v1';
  prNumber: number;        // positive integer
  headSha: string;         // /^[0-9a-f]{40}$/i
  baseSha: string;         // /^[0-9a-f]{40}$/i
  generatedAt: string;     // ISO 8601 datetime
  trust: {
    classification: 'untrusted' | 'trusted';
    reason: string;
  };
  astGate: {
    outcome: 'pass' | 'abort-protected-path';
    offendingPaths: string[];
  };
  differentialTest: {
    upstreamSuitePassed: boolean;
    newTestsPassed: boolean;
    newCodeCoveragePct: number;   // [0, 100]
  };
  reviewers: {
    code: ReviewerVerdict;
    test: ReviewerVerdict;
    security: ReviewerVerdict;
  };
  consensus: {
    approved: boolean;
    blockingFindings: number;     // non-negative integer
  };
};

/** Single reviewer verdict. */
type ReviewerVerdict = {
  approved: boolean;
  findings: Finding[];
  promptInjectionDetected: boolean;  // REQUIRED field — sandbox MUST always emit
};

/** Single reviewer finding. */
type Finding = {
  severity: 'critical' | 'major' | 'minor' | 'suggestion';
  message: string;        // min length 1
  path?: string;          // optional file path
};

import { validateReport } from 'pipeline-cli/src/pipeline/report-validator.js';

const result = validateReport(JSON.parse(artifactJson));
if (!result.valid) {
  // Reject — do NOT proceed to key resolution
  throw new Error(`[clean-room-signer] Report rejected: ${result.error}`);
}
const report = result.report;
// ... proceed to build Merkle tree + sign

/** Sentinel file/directory names that indicate an active sandbox environment. */
const SANDBOX_ARTIFACT_SENTINELS: readonly string[];
// Values: 'untrusted-pr-eval-active', 'stages-1-3-output', 'sandbox-output',
//         '.sandbox-pid', 'untrusted-pr-eval.lock'

interface CleanRoomSignerOptions {
  /** Absolute path to the unsigned report artifact file. */
  reportArtifactPath: string;
  /** Absolute path to the repo root. */
  repoRoot: string;
  /** Task ID used to select which transcript leaves belong to this PR. */
  taskId: string;
  /** Git commit SHA of the PR head. Bound to the envelope subject. */
  headSha: string;
  /** Optional content-addressed patch-id (AISDLC-398). */
  patchId?: string;
  /** Optional identity string embedded in the attestation envelope. */
  signerIdentity?: string;
  /**
   * Working directory for the isolation-invariant check (AC#8).
   * Defaults to `process.cwd()`. MUST be the operator's directory, not the sandbox.
   */
  workDir?: string;
}

type CleanRoomSignerResult = CleanRoomSignerSuccess | CleanRoomSignerFailure;

interface CleanRoomSignerSuccess {
  success: true;
  report: UntrustedPrReport;
  envelopePath: string;
}

interface CleanRoomSignerFailure {
  success: false;
  phase: 'isolation-check' | 'artifact-read' | 'zod-validation'
       | 'consensus-rejected' | 'key-resolution' | 'signing';
  error: string;
}

node pipeline-cli/bin/cli-ucvg.mjs <subcommand> [flags]

node pipeline-cli/bin/cli-ucvg.mjs classify \
  --author <github-login> \
  --is-fork <true|false> \
  --work-dir <repo-root>

printf '%s\n' "$CHANGED_FILES" | node pipeline-cli/bin/cli-ucvg.mjs ast-gate \
  --pr-number <number> \
  --author <github-login> \
  --work-dir <repo-root>

node pipeline-cli/bin/cli-ucvg.mjs sandbox-run \
  --pr-number <number> \
  --head-sha <sha> \
  --base-sha <sha> \
  --pr-content-dir <path> \
  --work-dir <repo-root> \
  --output-dir <path>

node pipeline-cli/bin/cli-ucvg.mjs clean-room-sign \
  --report-path <path> \
  --pr-number <number> \
  --head-sha <sha> \
  --work-dir <repo-root>

# Stage 1 config
protectedPaths:         # Full-replacement list (not merge); must include defaults you want
  - '.github/**'
  - '**/package.json'
  - '**/pnpm-lock.yaml'
  - '**/package-lock.json'
  - '**/yarn.lock'
  - '.ai-sdlc/**'
  - 'ai-sdlc-plugin/agents/**'

allowedMutationGlobs:   # Full-replacement list
  - '**/*.ts'
  - '**/*.tsx'
  - '**/*.js'
  - '**/*.jsx'
  - '**/*.md'

contentHeuristics:
  packageJsonLifecycleScripts: abort  # or: warn
  newGithubActionUses: abort          # or: warn

# Stage 2/3 config
sandboxDriver: docker         # or: podman | kata | gvisor | microvm
complianceRegime: none        # or: hipaa | fedramp-high | pci-dss-level-1
deployment: ci                # or: local

differentialTest:
  resourceLimits:
    wallClockSeconds: 600     # 10 min default
    cpuCores: 2
    memoryMb: 4096            # 4 GB default
    perTestTimeoutSeconds: 60 # optional per-test cap