Harden manual integration test trust boundary

.github/scripts/resolve_integration_test_target.js

@@ -0,0 +1,170 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+const DECISIVE_REVIEW_STATES = new Set(['APPROVED', 'CHANGES_REQUESTED', 'DISMISSED']);
+const SHA_PATTERN = /^[0-9a-f]{40}$/;
+const BRANCH_PATTERN = /^[a-zA-Z0-9_./-]+$/;
+
+function assertValidSha(sha, description) {
+  if (!SHA_PATTERN.test(sha)) {
+    throw new Error(`GitHub returned an invalid ${description} SHA.`);
+  }
+}
+
+function hasWritePermission(permissionData) {
+  return permissionData.user?.permissions?.push === true
+    || ['admin', 'maintain', 'write'].includes(permissionData.permission);
+}
+
+function latestDecisiveReviews(reviews) {
+  const latestByReviewer = new Map();
+  const sortedReviews = [...reviews].sort((left, right) => {
+    const submittedComparison = (left.submitted_at || '').localeCompare(right.submitted_at || '');
+    return submittedComparison || Number(left.id) - Number(right.id);
+  });
+
+  for (const review of sortedReviews) {
+    const state = review.state?.toUpperCase();
+    const reviewer = review.user?.login?.toLowerCase();
+    if (reviewer && DECISIVE_REVIEW_STATES.has(state)) {
+      latestByReviewer.set(reviewer, review);
+    }
+  }
+
+  return latestByReviewer;
+}
+
+async function resolvePullRequest({ github, context, core, prNumber, requiredApprovals }) {
+  if (!/^[0-9]+$/.test(prNumber)) {
+    throw new Error('Invalid PR number. Only numeric values are allowed.');
+  }
+
+  const pullNumber = Number(prNumber);
+  const { data: pullRequest } = await github.rest.pulls.get({
+    ...context.repo,
+    pull_number: pullNumber,
+  });
+
+  if (pullRequest.state !== 'open') {
+    throw new Error(`PR #${pullNumber} is not open (state: ${pullRequest.state}).`);
+  }
+
+  const headSha = pullRequest.head.sha;
+  const baseSha = pullRequest.base.sha;
+  assertValidSha(headSha, 'PR head');
+  assertValidSha(baseSha, 'PR base');
+
+  const reviews = await github.paginate(github.rest.pulls.listReviews, {
+    ...context.repo,
+    pull_number: pullNumber,
+    per_page: 100,
+  });
+  const latestReviews = latestDecisiveReviews(reviews);
+  const author = pullRequest.user?.login?.toLowerCase();
+  const approvalCandidates = [...latestReviews.entries()]
+    .filter(([, review]) => review.state.toUpperCase() === 'APPROVED')
+    .filter(([, review]) => review.commit_id === headSha)
+    .filter(([reviewer]) => reviewer !== author);
+
+  const approvedMaintainers = [];
+  for (const [reviewer] of approvalCandidates) {
+    const { data: permissionData } = await github.rest.repos.getCollaboratorPermissionLevel({
+      ...context.repo,
+      username: reviewer,
+    });
+    if (hasWritePermission(permissionData)) {
+      approvedMaintainers.push(reviewer);
+    } else {
+      core.info(`Ignoring approval from ${reviewer}: reviewer does not have write permission.`);
+    }
+  }
+
+  if (approvedMaintainers.length < requiredApprovals) {
+    throw new Error(
+      `PR #${pullNumber} head ${headSha} requires ${requiredApprovals} approvals from unique `
+      + `write-capable maintainers; found ${approvedMaintainers.length}.`,
+    );
+  }
+
+  core.info(
+    `PR #${pullNumber} head ${headSha} approved by: ${approvedMaintainers.join(', ')}.`,
+  );
+  return {
+    baseRef: baseSha,
+    checkoutRef: headSha,
+    description: `PR #${pullNumber}`,
+  };
+}
+
+async function resolveBranch({ github, context, core, branch }) {
+  if (!BRANCH_PATTERN.test(branch)) {
+    throw new Error(
+      'Invalid branch name. Only alphanumeric characters, hyphens, underscores, dots, and slashes '
+      + 'are allowed.',
+    );
+  }
+
+  const [{ data: repository }, { data: targetBranch }] = await Promise.all([
+    github.rest.repos.get(context.repo),
+    github.rest.repos.getBranch({ ...context.repo, branch }),
+  ]);
+  const { data: baseBranch } = await github.rest.repos.getBranch({
+    ...context.repo,
+    branch: repository.default_branch,
+  });
+
+  const checkoutRef = targetBranch.commit.sha;
+  const baseRef = baseBranch.commit.sha;
+  assertValidSha(checkoutRef, 'branch head');
+  assertValidSha(baseRef, 'default branch');
+  core.info(`Branch ${branch} resolved to immutable commit ${checkoutRef}.`);
+
+  return {
+    baseRef,
+    checkoutRef,
+    description: `branch ${branch}`,
+  };
+}
+
+/**
+ * Resolve a manually requested integration-test target to an immutable commit.
+ *
+ * Pull requests must have fresh approvals from two unique write-capable
+ * maintainers for the exact head commit. Branches are limited to branches in
+ * the base repository and are pinned to their current commit.
+ */
+async function resolveIntegrationTestTarget({
+  github,
+  context,
+  core,
+  prNumber = '',
+  branch = '',
+  requiredApprovals = 2,
+}) {
+  const normalizedPrNumber = prNumber.trim();
+  const normalizedBranch = branch.trim();
+
+  if (normalizedPrNumber && normalizedBranch) {
+    throw new Error('Please provide either a PR number or a branch name, not both.');
+  }
+  if (!normalizedPrNumber && !normalizedBranch) {
+    throw new Error('Please provide either a PR number or a branch name.');
+  }
+
+  if (normalizedPrNumber) {
+    return resolvePullRequest({
+      github,
+      context,
+      core,
+      prNumber: normalizedPrNumber,
+      requiredApprovals,
+    });
+  }
+  return resolveBranch({
+    github,
+    context,
+    core,
+    branch: normalizedBranch,
+  });
+}
+
+module.exports = resolveIntegrationTestTarget;

.github/tests/test_resolve_integration_test_target.js

@@ -0,0 +1,212 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+/**
+ * Tests for resolve_integration_test_target.js.
+ *
+ * Run with: node --test .github/tests/test_resolve_integration_test_target.js
+ */
+
+const { describe, it } = require('node:test');
+const assert = require('node:assert/strict');
+
+const resolveIntegrationTestTarget = require('../scripts/resolve_integration_test_target.js');
+
+const HEAD_SHA = 'a'.repeat(40);
+const BASE_SHA = 'b'.repeat(40);
+
+function review({
+  id,
+  login,
+  state = 'APPROVED',
+  commitId = HEAD_SHA,
+  submittedAt = `2026-07-13T00:00:${String(id).padStart(2, '0')}Z`,
+}) {
+  return {
+    id,
+    state,
+    commit_id: commitId,
+    submitted_at: submittedAt,
+    user: { login },
+  };
+}
+
+function createMocks({
+  pullState = 'open',
+  pullAuthor = 'contributor',
+  reviews = [],
+  permissions = {},
+} = {}) {
+  const core = {
+    infoMessages: [],
+    info(message) {
+      this.infoMessages.push(message);
+    },
+  };
+  const context = {
+    repo: { owner: 'microsoft', repo: 'agent-framework' },
+  };
+  const github = {
+    paginate: async () => reviews,
+    rest: {
+      pulls: {
+        get: async () => ({
+          data: {
+            state: pullState,
+            user: { login: pullAuthor },
+            head: { sha: HEAD_SHA },
+            base: { sha: BASE_SHA },
+          },
+        }),
+        listReviews: async () => {},
+      },
+      repos: {
+        get: async () => ({ data: { default_branch: 'main' } }),
+        getBranch: async ({ branch }) => ({
+          data: { commit: { sha: branch === 'main' ? BASE_SHA : HEAD_SHA } },
+        }),
+        getCollaboratorPermissionLevel: async ({ username }) => ({
+          data: permissions[username] || {
+            permission: 'read',
+            user: { permissions: { push: false } },
+          },
+        }),
+      },
+    },
+  };
+
+  return { core, context, github };
+}
+
+const WRITE_PERMISSION = {
+  permission: 'write',
+  user: { permissions: { push: true } },
+};
+
+describe('input validation', () => {
+  it('rejects missing and conflicting targets', async () => {
+    const mocks = createMocks();
+    await assert.rejects(
+      () => resolveIntegrationTestTarget(mocks),
+      /provide either a PR number or a branch name/,
+    );
+    await assert.rejects(
+      () => resolveIntegrationTestTarget({ ...mocks, prNumber: '1', branch: 'feature' }),
+      /not both/,
+    );
+  });
+
+  it('rejects invalid PR numbers and branch names', async () => {
+    const mocks = createMocks();
+    await assert.rejects(
+      () => resolveIntegrationTestTarget({ ...mocks, prNumber: '1;echo' }),
+      /Invalid PR number/,
+    );
+    await assert.rejects(
+      () => resolveIntegrationTestTarget({ ...mocks, branch: 'feature branch' }),
+      /Invalid branch name/,
+    );
+  });
+});
+
+describe('pull request resolution', () => {
+  it('pins an open PR with two fresh write-capable approvals', async () => {
+    const mocks = createMocks({
+      reviews: [
+        review({ id: 1, login: 'maintainer-one' }),
+        review({ id: 2, login: 'maintainer-two' }),
+      ],
+      permissions: {
+        'maintainer-one': WRITE_PERMISSION,
+        'maintainer-two': WRITE_PERMISSION,
+      },
+    });
+
+    const result = await resolveIntegrationTestTarget({ ...mocks, prNumber: '123' });
+
+    assert.deepEqual(result, {
+      baseRef: BASE_SHA,
+      checkoutRef: HEAD_SHA,
+      description: 'PR #123',
+    });
+  });
+
+  it('rejects closed PRs', async () => {
+    const mocks = createMocks({ pullState: 'closed' });
+    await assert.rejects(
+      () => resolveIntegrationTestTarget({ ...mocks, prNumber: '123' }),
+      /is not open/,
+    );
+  });
+
+  it('ignores stale, self, and read-only approvals', async () => {
+    const mocks = createMocks({
+      reviews: [
+        review({ id: 1, login: 'stale', commitId: 'c'.repeat(40) }),
+        review({ id: 2, login: 'contributor' }),
+        review({ id: 3, login: 'reader' }),
+        review({ id: 4, login: 'maintainer' }),
+      ],
+      permissions: {
+        contributor: WRITE_PERMISSION,
+        reader: { permission: 'read', user: { permissions: { push: false } } },
+        maintainer: WRITE_PERMISSION,
+      },
+    });
+
+    await assert.rejects(
+      () => resolveIntegrationTestTarget({ ...mocks, prNumber: '123' }),
+      /found 1/,
+    );
+  });
+
+  it('uses each reviewer latest decisive review and ignores later comments', async () => {
+    const mocks = createMocks({
+      reviews: [
+        review({ id: 1, login: 'changes-requested' }),
+        review({ id: 2, login: 'changes-requested', state: 'CHANGES_REQUESTED' }),
+        review({ id: 3, login: 'maintainer-one' }),
+        review({ id: 4, login: 'maintainer-one', state: 'COMMENTED' }),
+        review({ id: 5, login: 'maintainer-two' }),
+      ],
+      permissions: {
+        'changes-requested': WRITE_PERMISSION,
+        'maintainer-one': WRITE_PERMISSION,
+        'maintainer-two': WRITE_PERMISSION,
+      },
+    });
+
+    const result = await resolveIntegrationTestTarget({ ...mocks, prNumber: '123' });
+    assert.equal(result.checkoutRef, HEAD_SHA);
+  });
+
+  it('does not count a dismissed approval', async () => {
+    const mocks = createMocks({
+      reviews: [
+        review({ id: 1, login: 'dismissed', state: 'DISMISSED' }),
+        review({ id: 2, login: 'maintainer' }),
+      ],
+      permissions: {
+        dismissed: WRITE_PERMISSION,
+        maintainer: WRITE_PERMISSION,
+      },
+    });
+
+    await assert.rejects(
+      () => resolveIntegrationTestTarget({ ...mocks, prNumber: '123' }),
+      /found 1/,
+    );
+  });
+});
+
+describe('branch resolution', () => {
+  it('pins base-repository branches and their comparison base to SHAs', async () => {
+    const mocks = createMocks();
+    const result = await resolveIntegrationTestTarget({ ...mocks, branch: 'feature/test' });
+
+    assert.deepEqual(result, {
+      baseRef: BASE_SHA,
+      checkoutRef: HEAD_SHA,
+      description: 'branch feature/test',
+    });
+  });
+});