From 643761fa908b4b5dff1262009cabf34a35a0bcf5 Mon Sep 17 00:00:00 2001 From: Surajsm60720 <1ds22is166@dsce.edu.in> Date: Sun, 8 Nov 2026 07:43:13 +0530 Subject: [PATCH 1/5] chore(kin): claim APPR-11 rulesets and CODEOWNERS Co-Authored-By: Claude Opus 5.5 From a82f220a2c6369129c3dc36908897afe00f680c7 Mon Sep 17 00:00:00 2001 From: Surajsm60720 <1ds22is166@dsce.edu.in> Date: Sun, 8 Nov 2026 07:59:16 +0530 Subject: [PATCH 2/5] feat(kin): rulesets, CODEOWNERS check and security test 23 (APPR-11) scripts/kin-rulesets.ts applies the approvals spec section 10 branch and tag rulesets by name, reports every drifted field with --check (bypass actors included), checks CODEOWNERS, and runs security test 23 on a scratch repo. It runs only on the owner's own admin sign-in and refuses the bot App's credential before any request. Co-Authored-By: Claude Opus 5.5 --- apps/server/src/kin/github/KinRulesets.ts | 192 ++++++ apps/server/src/kin/github/githubRest.ts | 4 +- .../src/kin/github/rulesetsSetup.test.ts | 403 +++++++++++ apps/server/src/kin/github/rulesetsSetup.ts | 651 ++++++++++++++++++ docs/kin/specs/approvals.md | 13 +- knip.jsonc | 1 + scripts/kin-rulesets.ts | 17 + 7 files changed, 1274 insertions(+), 7 deletions(-) create mode 100644 apps/server/src/kin/github/KinRulesets.ts create mode 100644 apps/server/src/kin/github/rulesetsSetup.test.ts create mode 100644 apps/server/src/kin/github/rulesetsSetup.ts create mode 100644 scripts/kin-rulesets.ts diff --git a/apps/server/src/kin/github/KinRulesets.ts b/apps/server/src/kin/github/KinRulesets.ts new file mode 100644 index 000000000000..29be132d6329 --- /dev/null +++ b/apps/server/src/kin/github/KinRulesets.ts @@ -0,0 +1,192 @@ +// Pure: the approvals spec section 10 rulesets and CODEOWNERS rule. Apply, `--check` and the +// tests all read `kinRulesets`, so there is one definition of what GitHub should hold. + +/** The owner: sole code owner, and the only sign-in the script accepts. */ +export const KIN_OWNER_LOGIN = "GLDRoger"; + +/** Required status check contexts per Kin repository; other repos pass `--status-check`. */ +export const KIN_REPO_REQUIRED_CHECKS: Readonly>> = { + // ci.yml's `Check` job fails unless every other CI job passed or was skipped as not needed. + "GLDRoger/t3code": ["Check"], +}; + +export const KIN_CODEOWNERS_PATH = ".github/CODEOWNERS"; + +export interface KinRulesetRule { + readonly type: string; + readonly parameters?: Readonly>; +} + +export interface KinRuleset { + readonly name: string; + readonly target: "branch" | "tag"; + readonly enforcement: "active"; + /** Always empty: a bypass for admins lets the owner's merge token skip review, one for the App lets the bot merge alone. */ + readonly bypass_actors: readonly []; + readonly conditions: { + readonly ref_name: { readonly include: ReadonlyArray; readonly exclude: readonly [] }; + }; + readonly rules: ReadonlyArray; +} + +/** @public The rulesets for one repository, given its required status check contexts. */ +export const kinRulesets = (requiredChecks: ReadonlyArray): ReadonlyArray => [ + { + name: "kin-main", + target: "branch", + enforcement: "active", + bypass_actors: [], + conditions: { ref_name: { include: ["~DEFAULT_BRANCH"], exclude: [] } }, + rules: [ + { type: "deletion" }, + { type: "non_fast_forward" }, + { + type: "pull_request", + parameters: { + required_approving_review_count: 1, + require_code_owner_review: true, + dismiss_stale_reviews_on_push: true, + require_last_push_approval: true, + required_review_thread_resolution: true, + allowed_merge_methods: ["squash"], + }, + }, + { + type: "required_status_checks", + parameters: { + strict_required_status_checks_policy: true, + do_not_enforce_on_create: false, + required_status_checks: requiredChecks.map((context) => ({ context })), + }, + }, + ], + }, + { + name: "kin-release", + target: "tag", + enforcement: "active", + bypass_actors: [], + conditions: { ref_name: { include: ["refs/tags/v*"], exclude: [] } }, + rules: [{ type: "creation" }, { type: "update" }, { type: "deletion" }], + }, +]; + +/** The fields of a GitHub ruleset that `diffRuleset` reads. */ +export interface LiveRuleset { + readonly target: string; + readonly enforcement: string; + /** GitHub omits this for a credential that can't administer the repository. */ + readonly bypass_actors?: + | ReadonlyArray<{ + readonly actor_id?: number | null | undefined; + readonly actor_type: string; + readonly bypass_mode?: string | undefined; + }> + | undefined; + readonly conditions?: unknown; + readonly rules?: + | ReadonlyArray<{ + readonly type: string; + readonly parameters?: Readonly> | undefined; + }> + | undefined; +} + +export interface KinRulesetDrift { + readonly field: string; + readonly expected: string; + readonly actual: string; +} + +/** Key-sorted, and array order ignored: GitHub doesn't promise to keep either. */ +const canonical = (value: unknown): string => { + if (value === undefined) return "absent"; + if (Array.isArray(value)) return `[${value.map(canonical).toSorted().join(",")}]`; + if (value !== null && typeof value === "object") { + const record = value as Readonly>; + return `{${Object.keys(record) + .toSorted() + .map((key) => `${key}:${canonical(record[key])}`) + .join(",")}}`; + } + return JSON.stringify(value); +}; + +/** + * Every field where `live` differs from `desired`: missing rules, rules someone added, changed + * parameters and any bypass actor. Parameters GitHub added that the spec doesn't set are not read. + */ +export function diffRuleset( + desired: KinRuleset, + live: LiveRuleset | undefined, +): ReadonlyArray { + if (live === undefined) return [{ field: "ruleset", expected: "present", actual: "missing" }]; + const drift: Array = []; + const compare = (field: string, expected: unknown, actual: unknown) => { + if (canonical(expected) !== canonical(actual)) { + drift.push({ field, expected: canonical(expected), actual: canonical(actual) }); + } + }; + compare("target", desired.target, live.target); + compare("enforcement", desired.enforcement, live.enforcement); + if (live.bypass_actors === undefined) { + drift.push({ + field: "bypass_actors", + expected: "none", + actual: "not visible to this credential", + }); + } + for (const actor of live.bypass_actors ?? []) { + drift.push({ + field: "bypass_actors", + expected: "none", + actual: `${actor.actor_type}${actor.actor_id == null ? "" : ` ${actor.actor_id}`} (${actor.bypass_mode ?? "always"})`, + }); + } + compare("conditions", desired.conditions, live.conditions ?? undefined); + const liveRules = new Map((live.rules ?? []).map((rule) => [rule.type, rule])); + for (const rule of desired.rules) { + const got = liveRules.get(rule.type); + if (got === undefined) { + drift.push({ field: `rules.${rule.type}`, expected: "present", actual: "missing" }); + continue; + } + for (const [key, want] of Object.entries(rule.parameters ?? {})) { + // GitHub may leave out a boolean parameter that is false. + const value = got.parameters?.[key] ?? (want === false ? false : undefined); + compare(`rules.${rule.type}.${key}`, want, value); + } + } + const desiredTypes = new Set(desired.rules.map((rule) => rule.type)); + for (const type of liveRules.keys()) { + if (!desiredTypes.has(type)) { + drift.push({ field: `rules.${type}`, expected: "absent", actual: "present" }); + } + } + return drift; +} + +/** + * Why `content` (the default branch's `.github/CODEOWNERS`) fails to make `owner` the sole code + * owner of every path; empty when it passes. A `*` rule must exist, and every rule must name + * exactly the owner, so no later rule can hand a path to someone else or to no one. + */ +export function codeownersProblems(content: string, owner: string): ReadonlyArray { + const problems: Array = []; + const expected = `@${owner}`.toLowerCase(); + let coversAll = false; + content.split(/\r?\n/).forEach((raw, index) => { + const tokens = raw.trim().split(/\s+/).filter(Boolean); + const commentAt = tokens.findIndex((token) => token.startsWith("#")); + const [pattern, ...owners] = commentAt === -1 ? tokens : tokens.slice(0, commentAt); + if (pattern === undefined) return; + if (pattern === "*") coversAll = true; + if (owners.length !== 1 || owners[0]!.toLowerCase() !== expected) { + problems.push( + `line ${index + 1}: "${pattern}" is owned by ${owners.length === 0 ? "no one" : owners.join(" ")}, not only @${owner}`, + ); + } + }); + if (!coversAll) problems.unshift(`no "* @${owner}" rule, so some paths have no code owner`); + return problems; +} diff --git a/apps/server/src/kin/github/githubRest.ts b/apps/server/src/kin/github/githubRest.ts index eeaca459f2fb..6e1d1f849f9f 100644 --- a/apps/server/src/kin/github/githubRest.ts +++ b/apps/server/src/kin/github/githubRest.ts @@ -36,7 +36,7 @@ export interface GitHubJsonResponse { /** Standard headers for a Kin GitHub REST call. */ export const gitHubRequest = ( - method: "GET" | "POST" | "PUT" | "DELETE", + method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE", path: string, token: Redacted.Redacted | undefined, ) => { @@ -54,7 +54,7 @@ export const gitHubRequest = ( export const gitHubJson = Effect.fn("KinGitHub.request")(function* (input: { readonly client: HttpClient.HttpClient; readonly operation: string; - readonly method: "GET" | "POST" | "PUT" | "DELETE"; + readonly method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE"; readonly path: string; readonly token?: Redacted.Redacted | undefined; readonly body?: unknown; diff --git a/apps/server/src/kin/github/rulesetsSetup.test.ts b/apps/server/src/kin/github/rulesetsSetup.test.ts new file mode 100644 index 000000000000..c18c47f6d32b --- /dev/null +++ b/apps/server/src/kin/github/rulesetsSetup.test.ts @@ -0,0 +1,403 @@ +import { RepoSlug } from "@t3tools/contracts"; +import { assert, it } from "@effect/vitest"; +import * as Effect from "effect/Effect"; +import * as Redacted from "effect/Redacted"; +import * as Schema from "effect/Schema"; +import { describe } from "vite-plus/test"; + +import { codeownersProblems, kinRulesets } from "./KinRulesets.ts"; +import * as Rulesets from "./rulesetsSetup.ts"; +import { fakeGitHub, type FakeAnswer, type RecordedRequest } from "./testFakes.ts"; + +const OWNER_TOKEN = "gho_owner-test"; +const BOT_TOKEN = "ghs_bot-test"; +const MERGE_TOKEN = "github_pat_merge-test"; +const repo = Schema.decodeSync(RepoSlug)("GLDRoger/t3code"); +const scratch = Schema.decodeSync(RepoSlug)("GLDRoger/kin-scratch"); +const target = (token = OWNER_TOKEN, slug = repo): Rulesets.RepoTarget => ({ + repo: slug, + owner: "GLDRoger", + token: Redacted.make(token), +}); + +type StoredRuleset = Record & { + id: number; + name: string; + target: string; + rules: Array<{ type: string; parameters?: Record }>; +}; + +/** Repository settings GitHub would hold, answered the way its REST API does. */ +const githubRepo = ( + options: { + readonly slug?: string; + readonly codeowners?: string | null; + readonly codeownersErrors?: ReadonlyArray<{ line: number; kind: string }>; + readonly user?: { login: string; type: string } | null; + readonly admin?: boolean; + readonly onPull?: (request: RecordedRequest) => FakeAnswer | undefined; + } = {}, +) => { + const base = `/repos/${options.slug ?? "GLDRoger/t3code"}`; + const rulesets: Array = []; + let nextId = 1; + // GitHub adds parameters the spec doesn't set and omits false booleans on the way back. + const asReturned = (ruleset: StoredRuleset) => ({ + ...ruleset, + source_type: "Repository", + source: options.slug ?? "GLDRoger/t3code", + rules: ruleset.rules.map((rule) => + rule.type === "pull_request" + ? { + ...rule, + parameters: { ...rule.parameters, automatic_copilot_code_review_enabled: false }, + } + : rule.type === "required_status_checks" + ? { + ...rule, + parameters: Object.fromEntries( + Object.entries(rule.parameters ?? {}).filter(([, value]) => value !== false), + ), + } + : rule, + ), + }); + const github = fakeGitHub((request): FakeAnswer => { + const token = request.authorization?.replace(/^Bearer /, ""); + if (request.path === "/user") { + const user = + token !== OWNER_TOKEN + ? null + : "user" in options + ? options.user + : { login: "GLDRoger", type: "User" }; + return user === null ? { status: 403 } : { status: 200, body: user }; + } + if (request.method === "GET" && request.path === base) { + return { + status: 200, + body: { default_branch: "kin", permissions: { admin: options.admin ?? true } }, + }; + } + if (request.path === `${base}/contents/.github/CODEOWNERS?ref=kin`) { + const content = options.codeowners === undefined ? "* @GLDRoger\n" : options.codeowners; + return content === null + ? { status: 404, body: { message: "Not Found" } } + : { + status: 200, + body: { content: Buffer.from(content).toString("base64"), encoding: "base64" }, + }; + } + if (request.path === `${base}/codeowners/errors?ref=kin`) { + return { status: 200, body: { errors: options.codeownersErrors ?? [] } }; + } + if (request.path === `${base}/rulesets?includes_parents=false&per_page=100`) { + return { + status: 200, + body: rulesets.map(({ id, name, target }) => ({ + id, + name, + target, + source_type: "Repository", + })), + }; + } + if (request.method === "POST" && request.path === `${base}/rulesets`) { + const created = { ...(request.body as StoredRuleset), id: nextId++ }; + rulesets.push(created); + return { status: 201, body: { id: created.id } }; + } + const one = request.path.match(new RegExp(`^${base}/rulesets/(\\d+)$`)); + if (one) { + const index = rulesets.findIndex((ruleset) => ruleset.id === Number(one[1])); + if (index === -1) return { status: 404 }; + if (request.method === "PUT") { + rulesets[index] = { ...(request.body as StoredRuleset), id: rulesets[index]!.id }; + return { status: 200, body: { id: rulesets[index]!.id } }; + } + return { status: 200, body: asReturned(rulesets[index]!) }; + } + return options.onPull?.(request) ?? { status: 404 }; + }); + return { rulesets, ...github }; +}; + +const writes = (requests: ReadonlyArray) => + requests.filter((request) => request.method !== "GET"); + +const checks = ["Check"]; +const apply = (t = target()) => Rulesets.applyRepo(t, { requiredChecks: checks }); +const check = (t = target()) => Rulesets.checkRepo(t, { requiredChecks: checks, rulesets: true }); + +describe("kin-rulesets apply", () => { + it.effect("creates both rulesets, then a second apply writes nothing and --check passes", () => { + const github = githubRepo(); + return Effect.gen(function* () { + const first = yield* apply(); + assert.isTrue(first.ok); + assert.include(first.lines, "Ruleset kin-main (branch): created"); + assert.include(first.lines, "Ruleset kin-release (tag): created"); + assert.deepStrictEqual( + writes(github.requests).map((request) => request.body), + [...kinRulesets(checks)], + ); + const before = github.requests.length; + const second = yield* apply(); + assert.isTrue(second.ok); + assert.include(second.lines, "Ruleset kin-main (branch): unchanged"); + assert.lengthOf(writes(github.requests.slice(before)), 0); + const checked = yield* check(); + assert.isTrue(checked.ok); + assert.strictEqual(checked.lines.at(-1), "PASS: no drift."); + }).pipe(Effect.provide(github.layer)); + }); + + it.effect("refuses to apply, and writes nothing, while CODEOWNERS is missing", () => { + const github = githubRepo({ codeowners: null }); + return Effect.gen(function* () { + const result = yield* apply(); + assert.isFalse(result.ok); + assert.include( + result.lines, + ' FAIL .github/CODEOWNERS is missing on kin; add "* @GLDRoger".', + ); + assert.lengthOf(writes(github.requests), 0); + }).pipe(Effect.provide(github.layer)); + }); +}); + +const branchRule = (rulesets: Array) => + rulesets.find((ruleset) => ruleset.name === "kin-main")!; +const pullRequestParameters = (rulesets: Array) => + branchRule(rulesets).rules.find((rule) => rule.type === "pull_request")!.parameters!; + +describe("kin-rulesets --check", () => { + it.effect.each([ + [ + "a bypass actor someone added", + (rulesets: Array) => { + branchRule(rulesets).bypass_actors = [ + { actor_id: 5, actor_type: "RepositoryRole", bypass_mode: "always" }, + ]; + }, + " FAIL bypass_actors: expected none, got RepositoryRole 5 (always)", + ], + [ + "the code-owner review switched off", + (rulesets: Array) => { + pullRequestParameters(rulesets).require_code_owner_review = false; + }, + " FAIL rules.pull_request.require_code_owner_review: expected true, got false", + ], + [ + "merge commits allowed", + (rulesets: Array) => { + pullRequestParameters(rulesets).allowed_merge_methods = ["squash", "merge"]; + }, + ' FAIL rules.pull_request.allowed_merge_methods: expected ["squash"], got ["merge","squash"]', + ], + [ + "the deletion rule removed", + (rulesets: Array) => { + const branch = branchRule(rulesets); + branch.rules = branch.rules.filter((rule) => rule.type !== "deletion"); + }, + " FAIL rules.deletion: expected present, got missing", + ], + [ + "enforcement set to evaluate", + (rulesets: Array) => { + branchRule(rulesets).enforcement = "evaluate"; + }, + ' FAIL enforcement: expected "active", got "evaluate"', + ], + [ + "the tag ruleset deleted", + (rulesets: Array) => { + rulesets.splice( + rulesets.findIndex((ruleset) => ruleset.name === "kin-release"), + 1, + ); + }, + " FAIL ruleset: expected present, got missing", + ], + ] as const)("reports %s, and apply repairs it", ([, mutate, line]) => { + const github = githubRepo(); + return Effect.gen(function* () { + yield* apply(); + mutate(github.rulesets); + const drifted = yield* check(); + assert.isFalse(drifted.ok); + assert.include(drifted.lines, line); + assert.strictEqual(drifted.lines.at(-1), "FAIL: see above."); + const before = github.requests.length; + assert.isTrue((yield* apply()).ok); + assert.lengthOf(writes(github.requests.slice(before)), 1); + assert.isTrue((yield* check()).ok); + }).pipe(Effect.provide(github.layer)); + }); +}); + +describe("kin-rulesets CODEOWNERS", () => { + it.each([ + ["# Kin\n* @gldroger # owner\n", []], + ["", ['no "* @GLDRoger" rule, so some paths have no code owner']], + ["* @priya\n", ['line 1: "*" is owned by @priya, not only @GLDRoger']], + ["* @GLDRoger @priya\n", ['line 1: "*" is owned by @GLDRoger @priya, not only @GLDRoger']], + [ + "* @GLDRoger\n/docs/ @priya\n/apps/\n", + [ + 'line 2: "/docs/" is owned by @priya, not only @GLDRoger', + 'line 3: "/apps/" is owned by no one, not only @GLDRoger', + ], + ], + ] as const)("judges %j", (content, problems) => { + assert.deepStrictEqual(codeownersProblems(content, "GLDRoger"), problems); + }); + + it.effect("fails when GitHub reports CODEOWNERS syntax errors", () => { + const github = githubRepo({ codeownersErrors: [{ line: 1, kind: "Unknown owner" }] }); + return Effect.gen(function* () { + const result = yield* Rulesets.checkRepo(target(), { + requiredChecks: checks, + rulesets: false, + }); + assert.isFalse(result.ok); + assert.include(result.lines, " FAIL line 1: GitHub reports Unknown owner"); + }).pipe(Effect.provide(github.layer)); + }); +}); + +describe("kin-rulesets credential", () => { + it.effect("never sends the bot App's installation token anywhere", () => { + const github = githubRepo(); + return Effect.gen(function* () { + const error = yield* Effect.flip(apply(target(BOT_TOKEN))); + assert.strictEqual(error._tag, "KinRulesetsRefusedError"); + assert.lengthOf(github.requests, 0); + }).pipe(Effect.provide(github.layer)); + }); + + it.effect.each([ + ["a token GitHub maps to no user", { user: null }, "maps this credential to no user"], + ["the bot account", { user: { login: "kin-gldroger[bot]", type: "Bot" } }, "is a bot account"], + [ + "someone other than the owner", + { user: { login: "priya", type: "User" } }, + "signed in as priya", + ], + ["a credential without admin", { admin: false }, "can't administer GLDRoger/t3code"], + ] as const)("refuses %s and writes nothing", ([, options, reason]) => { + const github = githubRepo(options); + return Effect.gen(function* () { + const error = yield* Effect.flip(apply()); + assert.strictEqual(error._tag, "KinRulesetsRefusedError"); + assert.include(error.message, reason); + assert.lengthOf(writes(github.requests), 0); + }).pipe(Effect.provide(github.layer)); + }); +}); + +/** Answers the test 23 calls as a repository with the rulesets applied would. */ +const scratchRepo = (broken: { mergeTokenCanReview?: boolean; botCanMerge?: boolean } = {}) => { + const base = "/repos/GLDRoger/kin-scratch"; + let ownerReviewed = false; + const state = { branchDeleted: false, closed: false }; + const github = githubRepo({ + slug: "GLDRoger/kin-scratch", + onPull: (request) => { + const token = request.authorization?.replace(/^Bearer /, ""); + const route = `${request.method} ${request.path}`; + switch (route) { + case `GET ${base}/git/ref/heads/kin`: + return { status: 200, body: { object: { sha: "a".repeat(40) } } }; + case `POST ${base}/git/refs`: + return { status: 201, body: { ref: "refs/heads/kin-test-23-0" } }; + case `PUT ${base}/contents/kin-test-23/0.md`: + return { status: 201, body: { commit: { sha: "b".repeat(40) } } }; + case `POST ${base}/pulls`: + return { status: 201, body: { number: 7, head: { sha: "b".repeat(40) } } }; + case `POST ${base}/statuses/${"b".repeat(40)}`: + return { status: 201, body: { id: 1 } }; + case `POST ${base}/pulls/7/reviews`: + if (token === OWNER_TOKEN) ownerReviewed = true; + return token === OWNER_TOKEN || broken.mergeTokenCanReview + ? { status: 200, body: {} } + : { status: 403 }; + case `PUT ${base}/pulls/7/merge`: + return (token === BOT_TOKEN && broken.botCanMerge) || + (token === MERGE_TOKEN && ownerReviewed) + ? { status: 200, body: { merged: true } } + : { status: 405 }; + case `PATCH ${base}/git/refs/heads/kin`: + return { status: 422 }; + case `PATCH ${base}/pulls/7`: + state.closed = true; + return { status: 200, body: {} }; + case `DELETE ${base}/git/refs/heads/kin-test-23-0`: + state.branchDeleted = true; + return { status: 204 }; + } + return undefined; + }, + }); + return { ...github, state }; +}; + +const test23 = () => + Effect.gen(function* () { + yield* Rulesets.applyRepo(target(OWNER_TOKEN, scratch), { requiredChecks: ["ci"] }); + return yield* Rulesets.runTest23({ + target: target(OWNER_TOKEN, scratch), + requiredChecks: ["ci"], + botToken: Redacted.make(BOT_TOKEN), + mergeToken: Redacted.make(MERGE_TOKEN), + }); + }); + +describe("security test 23 (kin-rulesets --test-23)", () => { + it.effect("passes against a repository that enforces the rulesets", () => { + const github = scratchRepo(); + return Effect.gen(function* () { + const result = yield* test23(); + assert.isTrue(result.ok, result.lines.join("\n")); + assert.include(result.lines, " PASS the owner merge token can't submit a review (HTTP 403)"); + assert.include(result.lines, " PASS the bot can't merge to the default branch (HTTP 405)"); + assert.include(result.lines, " PASS the bot can't push to the default branch (HTTP 422)"); + assert.include( + result.lines, + " PASS a merge without a code-owner review is blocked (HTTP 405)", + ); + assert.isTrue(github.state.branchDeleted); + assert.isFalse(github.state.closed); + }).pipe(Effect.provide(github.layer)); + }); + + it.effect.each([ + ["a merge token that can review", { mergeTokenCanReview: true }], + ["a bot that can merge alone", { botCanMerge: true }], + ] as const)("fails with %s and cleans up its PR", ([, broken]) => { + const github = scratchRepo(broken); + return Effect.gen(function* () { + const result = yield* test23(); + assert.isFalse(result.ok); + assert.isTrue(result.lines.some((line) => line.startsWith(" FAIL"))); + assert.isTrue(github.state.closed); + assert.isTrue(github.state.branchDeleted); + }).pipe(Effect.provide(github.layer)); + }); + + it.effect("doesn't run until the scratch repo has no drift", () => { + const github = scratchRepo(); + return Effect.gen(function* () { + const result = yield* Rulesets.runTest23({ + target: target(OWNER_TOKEN, scratch), + requiredChecks: ["ci"], + botToken: Redacted.make(BOT_TOKEN), + mergeToken: Redacted.make(MERGE_TOKEN), + }); + assert.isFalse(result.ok); + assert.lengthOf(writes(github.requests), 0); + }).pipe(Effect.provide(github.layer)); + }); +}); diff --git a/apps/server/src/kin/github/rulesetsSetup.ts b/apps/server/src/kin/github/rulesetsSetup.ts new file mode 100644 index 000000000000..f1d61725e55d --- /dev/null +++ b/apps/server/src/kin/github/rulesetsSetup.ts @@ -0,0 +1,651 @@ +// The CLI behind scripts/kin-rulesets.ts: apply the approvals spec section 10 rulesets, `--check` +// them for drift, check CODEOWNERS, and run security test 23 on a scratch repository. It runs on +// the owner's own GitHub sign-in and refuses the bot's. +import { KinOrgId, RepoSlug } from "@t3tools/contracts"; +import * as Clock from "effect/Clock"; +import * as Config from "effect/Config"; +import * as Console from "effect/Console"; +import * as Effect from "effect/Effect"; +import * as Layer from "effect/Layer"; +import * as Option from "effect/Option"; +import * as Redacted from "effect/Redacted"; +import * as Schema from "effect/Schema"; +import { Command, Flag, Prompt } from "effect/cli"; +import { FetchHttpClient, HttpClient, HttpClientRequest } from "effect/http"; + +import { gitHubJson, gitHubRequest, KinGitHubRequestError } from "./githubRest.ts"; +import * as Keychain from "./Keychain.ts"; +import * as KinGitHubApp from "./KinGitHubApp.ts"; +import { + KIN_CODEOWNERS_PATH, + KIN_OWNER_LOGIN, + KIN_REPO_REQUIRED_CHECKS, + codeownersProblems, + diffRuleset, + kinRulesets, + type KinRuleset, +} from "./KinRulesets.ts"; +import * as OwnerMergeClient from "./OwnerMergeClient.ts"; + +export interface RulesetsResult { + readonly ok: boolean; + readonly lines: ReadonlyArray; +} + +export class KinRulesetsRefusedError extends Schema.TaggedError()( + "KinRulesetsRefusedError", + // Built from logins and repository names only, never from a credential. + { reason: Schema.String }, +) { + override get message(): string { + return `Refused: ${this.reason}`; + } +} + +export interface RepoTarget { + readonly repo: RepoSlug; + readonly owner: string; + readonly token: Redacted.Redacted; +} + +const UserResponse = Schema.Struct({ login: Schema.String, type: Schema.String }); +const RepoResponse = Schema.Struct({ + default_branch: Schema.String, + permissions: Schema.optional(Schema.Struct({ admin: Schema.Boolean })), +}); +const RulesetSummary = Schema.Struct({ + id: Schema.Int, + name: Schema.String, + target: Schema.optional(Schema.String), + source_type: Schema.optional(Schema.String), +}); +const RulesetDetail = Schema.Struct({ + id: Schema.Int, + name: Schema.String, + target: Schema.String, + enforcement: Schema.String, + bypass_actors: Schema.optional( + Schema.Array( + Schema.Struct({ + actor_id: Schema.optional(Schema.NullOr(Schema.Int)), + actor_type: Schema.String, + bypass_mode: Schema.optional(Schema.String), + }), + ), + ), + conditions: Schema.optional(Schema.NullOr(Schema.Unknown)), + rules: Schema.optional( + Schema.Array( + Schema.Struct({ + type: Schema.String, + parameters: Schema.optional(Schema.Record(Schema.String, Schema.Unknown)), + }), + ), + ), +}); +type RulesetDetail = typeof RulesetDetail.Type; +const ContentResponse = Schema.Struct({ content: Schema.String, encoding: Schema.String }); +const CodeownersErrors = Schema.Struct({ + errors: Schema.Array(Schema.Struct({ line: Schema.Int, kind: Schema.String })), +}); +const RefResponse = Schema.Struct({ object: Schema.Struct({ sha: Schema.String }) }); +const PullResponse = Schema.Struct({ + number: Schema.Int, + head: Schema.Struct({ sha: Schema.String }), +}); + +const refuse = (reason: string) => Effect.fail(new KinRulesetsRefusedError({ reason })); + +const repoPath = (repo: RepoSlug) => { + const [owner, name] = repo.split("/") as [string, string]; + return `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}`; +}; + +/** One call where only the status matters; the body is never read. */ +const statusOf = Effect.fn("kinRulesets.statusOf")(function* (input: { + readonly operation: string; + readonly method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE"; + readonly path: string; + readonly token: Redacted.Redacted; + readonly body?: unknown; +}) { + const client = yield* HttpClient.HttpClient; + const transport = () => + new KinGitHubRequestError({ operation: input.operation, stage: "transport" }); + let request = gitHubRequest(input.method, input.path, input.token); + if (input.body !== undefined) { + request = yield* HttpClientRequest.bodyJson(request, input.body).pipe( + Effect.mapError(transport), + ); + } + const response = yield* client.execute(request).pipe(Effect.mapError(transport)); + return response.status; +}); + +/** + * The owner's own admin sign-in, or a refusal. The bot App's installation tokens (`ghs_`) never + * leave the process; any credential GitHub reports as a bot or as someone else is refused. + */ +export const verifyOwnerCredential = Effect.fn("kinRulesets.verifyOwnerCredential")(function* ( + target: RepoTarget, +) { + const client = yield* HttpClient.HttpClient; + if (Redacted.value(target.token).startsWith("ghs_")) { + return yield* refuse( + "this is a GitHub App installation token, the bot's credential. Use the owner's own sign-in.", + ); + } + const user = yield* gitHubJson({ + client, + operation: "user.get", + method: "GET", + path: "/user", + token: target.token, + schema: UserResponse, + }).pipe( + Effect.mapError((error) => + error.stage === "status" && (error.status === 401 || error.status === 403) + ? new KinRulesetsRefusedError({ + reason: + "GitHub maps this credential to no user, as it does for App installation tokens. Use the owner's own sign-in.", + }) + : error, + ), + ); + const { login, type } = user.body; + if (type === "Bot" || login.endsWith("[bot]")) { + return yield* refuse(`${login} is a bot account. Use the owner's own sign-in.`); + } + if (login.toLowerCase() !== target.owner.toLowerCase()) { + return yield* refuse(`signed in as ${login}, not the owner ${target.owner}.`); + } + const repo = yield* gitHubJson({ + client, + operation: "repos.get", + method: "GET", + path: repoPath(target.repo), + token: target.token, + schema: RepoResponse, + }); + if (repo.body.permissions?.admin !== true) { + return yield* refuse( + `${login} can't administer ${target.repo} with this credential, so it can't see or set bypass actors.`, + ); + } + return { login, defaultBranch: repo.body.default_branch }; +}); + +/** CODEOWNERS on the default branch, which is the copy GitHub reads for reviews into it. */ +export const checkCodeowners = Effect.fn("kinRulesets.checkCodeowners")(function* ( + target: RepoTarget, + defaultBranch: string, +) { + const client = yield* HttpClient.HttpClient; + const ref = `ref=${encodeURIComponent(defaultBranch)}`; + const file = yield* gitHubJson({ + client, + operation: "repos.codeowners", + method: "GET", + path: `${repoPath(target.repo)}/contents/${KIN_CODEOWNERS_PATH}?${ref}`, + token: target.token, + schema: Schema.Union([ContentResponse, Schema.Struct({ message: Schema.String })]), + okStatuses: [200, 404], + }).pipe(Effect.map((response) => ("content" in response.body ? response.body : undefined))); + if (file === undefined) { + return [`${KIN_CODEOWNERS_PATH} is missing on ${defaultBranch}; add "* @${target.owner}".`]; + } + const content = Buffer.from(file.content, "base64").toString("utf8"); + const syntax = yield* gitHubJson({ + client, + operation: "repos.codeownersErrors", + method: "GET", + path: `${repoPath(target.repo)}/codeowners/errors?${ref}`, + token: target.token, + schema: CodeownersErrors, + }); + return [ + ...syntax.body.errors.map((error) => `line ${error.line}: GitHub reports ${error.kind}`), + ...codeownersProblems(content, target.owner), + ]; +}); + +const readRulesets = Effect.fn("kinRulesets.read")(function* ( + target: RepoTarget, + desired: ReadonlyArray, +) { + const client = yield* HttpClient.HttpClient; + const summaries = yield* gitHubJson({ + client, + operation: "repos.rulesets", + method: "GET", + path: `${repoPath(target.repo)}/rulesets?includes_parents=false&per_page=100`, + token: target.token, + schema: Schema.Array(RulesetSummary), + }); + const live = new Map(); + for (const ruleset of desired) { + const matches = summaries.body.filter( + (summary) => + summary.name === ruleset.name && + (summary.target ?? ruleset.target) === ruleset.target && + (summary.source_type ?? "Repository") === "Repository", + ); + if (matches.length > 1) { + return yield* refuse( + `${target.repo} has ${matches.length} ${ruleset.target} rulesets named ${ruleset.name}; delete the extras.`, + ); + } + if (matches[0] === undefined) continue; + const detail = yield* gitHubJson({ + client, + operation: "repos.ruleset", + method: "GET", + path: `${repoPath(target.repo)}/rulesets/${matches[0].id}`, + token: target.token, + schema: RulesetDetail, + }); + live.set(ruleset.name, detail.body); + } + return live; +}); + +const driftLines = (desired: ReadonlyArray, live: ReadonlyMap) => + desired.map((ruleset) => { + const drift = diffRuleset(ruleset, live.get(ruleset.name)); + return { + ok: drift.length === 0, + lines: [ + `Ruleset ${ruleset.name} (${ruleset.target}): ${drift.length === 0 ? "ok" : "DRIFT"}`, + ...drift.map( + (line) => ` FAIL ${line.field}: expected ${line.expected}, got ${line.actual}`, + ), + ], + }; + }); + +const codeownersLines = (problems: ReadonlyArray, owner: string) => + problems.length === 0 + ? [`CODEOWNERS: ok (@${owner} owns every path)`] + : ["CODEOWNERS: FAIL", ...problems.map((problem) => ` FAIL ${problem}`)]; + +/** `--check` and `--codeowners`: nothing is written. */ +export const checkRepo = Effect.fn("kinRulesets.check")(function* ( + target: RepoTarget, + input: { readonly requiredChecks: ReadonlyArray; readonly rulesets: boolean }, +) { + const { login, defaultBranch } = yield* verifyOwnerCredential(target); + const problems = yield* checkCodeowners(target, defaultBranch); + const lines = [ + `${target.repo} (default branch ${defaultBranch}), checked as ${login}`, + ...codeownersLines(problems, target.owner), + ]; + let ok = problems.length === 0; + if (input.rulesets) { + const desired = kinRulesets(input.requiredChecks); + for (const result of driftLines(desired, yield* readRulesets(target, desired))) { + ok &&= result.ok; + lines.push(...result.lines); + } + } + lines.push(ok ? "PASS: no drift." : "FAIL: see above."); + return { ok, lines } satisfies RulesetsResult; +}); + +/** Apply: creates or replaces each ruleset by name, writes nothing when it already matches. */ +export const applyRepo = Effect.fn("kinRulesets.apply")(function* ( + target: RepoTarget, + input: { readonly requiredChecks: ReadonlyArray }, +) { + const client = yield* HttpClient.HttpClient; + const { login, defaultBranch } = yield* verifyOwnerCredential(target); + const problems = yield* checkCodeowners(target, defaultBranch); + const lines = [ + `${target.repo} (default branch ${defaultBranch}), applying as ${login}`, + ...codeownersLines(problems, target.owner), + ]; + // Without CODEOWNERS, require_code_owner_review is met by anyone's approval. + if (problems.length > 0) { + lines.push("FAIL: fix CODEOWNERS on the default branch first; no ruleset was changed."); + return { ok: false, lines } satisfies RulesetsResult; + } + const desired = kinRulesets(input.requiredChecks); + const before = yield* readRulesets(target, desired); + for (const ruleset of desired) { + const live = before.get(ruleset.name); + const drift = diffRuleset(ruleset, live); + if (drift.length === 0) { + lines.push(`Ruleset ${ruleset.name} (${ruleset.target}): unchanged`); + continue; + } + yield* gitHubJson({ + client, + operation: live === undefined ? "repos.createRuleset" : "repos.updateRuleset", + method: live === undefined ? "POST" : "PUT", + path: `${repoPath(target.repo)}/rulesets${live === undefined ? "" : `/${live.id}`}`, + token: target.token, + body: ruleset, + schema: Schema.Struct({ id: Schema.Int }), + okStatuses: live === undefined ? [201] : [200], + }); + lines.push( + live === undefined + ? `Ruleset ${ruleset.name} (${ruleset.target}): created` + : `Ruleset ${ruleset.name} (${ruleset.target}): updated ${drift.map((line) => line.field).join(", ")}`, + ); + } + let ok = true; + for (const result of driftLines(desired, yield* readRulesets(target, desired))) { + if (result.ok) continue; + ok = false; + lines.push("GitHub stored something other than what was sent:", ...result.lines); + } + lines.push(ok ? "PASS: rulesets applied with no drift." : "FAIL: see above."); + return { ok, lines } satisfies RulesetsResult; +}); + +// Success codes would mean the action went through; 401 and 404 mean the probe never reached +// the rule, so they don't count as blocked either. +const isBlocked = (status: number) => status >= 400 && status !== 401 && status !== 404; + +/** + * Security test 23 on a scratch repository: the bot opens a PR, then the owner merge token tries + * to review, the bot tries to merge and to push, and the merge token tries to merge without a + * code-owner review. A final review by the owner followed by a successful merge shows the + * earlier blocks came from the review rule. Required checks get success statuses from the owner. + */ +export const runTest23 = Effect.fn("kinRulesets.test23")(function* (input: { + readonly target: RepoTarget; + readonly requiredChecks: ReadonlyArray; + readonly botToken: Redacted.Redacted; + readonly mergeToken: Redacted.Redacted; +}) { + const client = yield* HttpClient.HttpClient; + const { target } = input; + const path = repoPath(target.repo); + const check = yield* checkRepo(target, { requiredChecks: input.requiredChecks, rulesets: true }); + if (!check.ok) { + return { + ok: false, + lines: [...check.lines, "Test 23 not run: apply the rulesets to the scratch repo first."], + } satisfies RulesetsResult; + } + const { defaultBranch } = yield* verifyOwnerCredential(target); + const stamp = yield* Clock.currentTimeMillis; + const branch = `kin-test-23-${stamp}`; + const base = yield* gitHubJson({ + client, + operation: "git.getRef", + method: "GET", + path: `${path}/git/ref/heads/${encodeURIComponent(defaultBranch)}`, + token: input.botToken, + schema: RefResponse, + }); + yield* gitHubJson({ + client, + operation: "git.createRef", + method: "POST", + path: `${path}/git/refs`, + token: input.botToken, + body: { ref: `refs/heads/${branch}`, sha: base.body.object.sha }, + schema: Schema.Struct({ ref: Schema.String }), + okStatuses: [201], + }); + let merged = false; + let pullNumber: number | undefined; + const run = Effect.gen(function* () { + yield* gitHubJson({ + client, + operation: "repos.createFile", + method: "PUT", + path: `${path}/contents/kin-test-23/${stamp}.md`, + token: input.botToken, + body: { + message: "test: kin security test 23", + content: Buffer.from("Kin security test 23. Safe to delete.\n").toString("base64"), + branch, + }, + schema: Schema.Struct({ commit: Schema.Struct({ sha: Schema.String }) }), + okStatuses: [201], + }); + const pull = yield* gitHubJson({ + client, + operation: "pulls.create", + method: "POST", + path: `${path}/pulls`, + token: input.botToken, + body: { title: "Kin security test 23", head: branch, base: defaultBranch }, + schema: PullResponse, + okStatuses: [201], + }); + pullNumber = pull.body.number; + const headSha = pull.body.head.sha; + const pullPath = `${path}/pulls/${pull.body.number}`; + for (const context of input.requiredChecks) { + yield* gitHubJson({ + client, + operation: "repos.createStatus", + method: "POST", + path: `${path}/statuses/${headSha}`, + token: target.token, + body: { state: "success", context, description: "Kin security test 23" }, + schema: Schema.Struct({ id: Schema.Int }), + okStatuses: [201], + }); + } + const mergeBody = { sha: headSha, merge_method: "squash" }; + const probes: ReadonlyArray<{ + readonly name: string; + readonly pass: (status: number) => boolean; + readonly request: Parameters[0]; + }> = [ + { + name: "the owner merge token can't submit a review", + pass: (status) => status === 403, + request: { + operation: "pulls.createReview", + method: "POST", + path: `${pullPath}/reviews`, + token: input.mergeToken, + body: { event: "APPROVE", commit_id: headSha }, + }, + }, + { + name: "the bot can't merge to the default branch", + pass: isBlocked, + request: { + operation: "pulls.merge", + method: "PUT", + path: `${pullPath}/merge`, + token: input.botToken, + body: mergeBody, + }, + }, + { + name: "the bot can't push to the default branch", + pass: isBlocked, + request: { + operation: "git.updateRef", + method: "PATCH", + path: `${path}/git/refs/heads/${encodeURIComponent(defaultBranch)}`, + token: input.botToken, + body: { sha: headSha, force: false }, + }, + }, + { + name: "a merge without a code-owner review is blocked", + pass: isBlocked, + request: { + operation: "pulls.merge", + method: "PUT", + path: `${pullPath}/merge`, + token: input.mergeToken, + body: mergeBody, + }, + }, + ]; + const lines = [ + `Test 23 on ${target.repo}, PR #${pull.body.number} by the bot at ${headSha.slice(0, 7)}:`, + ]; + let ok = true; + for (const probe of probes) { + const status = yield* statusOf(probe.request); + const pass = probe.pass(status); + ok &&= pass; + lines.push(` ${pass ? "PASS" : "FAIL"} ${probe.name} (HTTP ${status})`); + if (!pass) return { ok: false, lines: [...lines, "FAIL: stopped at the first failure."] }; + } + const review = yield* statusOf({ + operation: "pulls.createReview", + method: "POST", + path: `${pullPath}/reviews`, + token: target.token, + body: { event: "APPROVE", commit_id: headSha }, + }); + let merge: number | undefined; + // GitHub recomputes mergeability after a review, so the first merge can still see it blocked. + for (let attempt = 0; review === 200 && attempt < 5; attempt++) { + merge = yield* statusOf(probes[3]!.request); + if (merge !== 405) break; + yield* Effect.sleep("2 seconds"); + } + merged = merge === 200; + ok &&= merged; + lines.push( + ` ${merged ? "PASS" : "FAIL"} after ${target.owner}'s review the merge token merges (review HTTP ${review}, merge HTTP ${merge ?? "not tried"}), so the blocks came from the rules`, + ok ? "PASS: security test 23." : "FAIL: see above.", + ); + return { ok, lines } satisfies RulesetsResult; + }); + const cleanup = Effect.gen(function* () { + if (!merged && pullNumber !== undefined) { + yield* statusOf({ + operation: "pulls.close", + method: "PATCH", + path: `${path}/pulls/${pullNumber}`, + token: input.botToken, + body: { state: "closed" }, + }); + } + yield* statusOf({ + operation: "git.deleteRef", + method: "DELETE", + path: `${path}/git/refs/heads/${encodeURIComponent(branch)}`, + token: input.botToken, + }); + }).pipe(Effect.ignore); + return yield* run.pipe(Effect.ensuring(cleanup)); +}); + +const decodeRepo = Schema.decodeUnknownEffect(RepoSlug); +const decodeOrgId = Schema.decodeUnknownEffect(KinOrgId); + +const ownerToken = Effect.gen(function* () { + const fromEnv = yield* Config.option(Config.Redacted("GH_TOKEN")); + if (Option.isSome(fromEnv)) return fromEnv.value; + const pasted = yield* Prompt.run( + Prompt.Hidden({ message: "Paste the owner's GitHub token (hidden; `gh auth token`)" }), + ); + return Redacted.make(String(Redacted.value(pasted))); +}); + +const failed = (error: { readonly message: string }) => + Effect.succeed({ ok: false, lines: [error.message] } satisfies RulesetsResult); + +/** @public Run by scripts/kin-rulesets.ts, which loads this file by URL. */ +export const kinRulesetsCommand = Command.make( + "kin-rulesets", + { + repo: Flag.String("repo").pipe(Flag.withDescription("The repository, as owner/name.")), + check: Flag.Boolean("check").pipe( + Flag.withDescription( + "Report drift from the approvals spec rulesets and CODEOWNERS; change nothing.", + ), + Flag.withDefault(false), + ), + codeowners: Flag.Boolean("codeowners").pipe( + Flag.withDescription("Check only CODEOWNERS."), + Flag.withDefault(false), + ), + test23: Flag.Boolean("test-23").pipe( + Flag.withDescription("Run security test 23 on a scratch repository (opens and merges a PR)."), + Flag.withDefault(false), + ), + owner: Flag.String("owner").pipe( + Flag.withDescription("The owner's GitHub login: sole code owner and the required sign-in."), + Flag.withDefault(KIN_OWNER_LOGIN), + ), + statusCheck: Flag.String("status-check").pipe( + Flag.withDescription( + "A required status check context (repeatable); Kin repos have defaults.", + ), + Flag.atLeast(0), + ), + kinOrg: Flag.String("kin-org").pipe( + Flag.withDescription("For --test-23: the Kin org whose merge token is in the keychain."), + Flag.optional, + ), + appId: Flag.String("app-id").pipe( + Flag.withDescription("For --test-23: the bot App id; defaults to KIN_GITHUB_APP_ID."), + Flag.optional, + ), + }, + (input) => { + const program = Effect.gen(function* () { + const repo = yield* decodeRepo(input.repo).pipe( + Effect.mapError( + () => new KinRulesetsRefusedError({ reason: "--repo must be owner/name." }), + ), + ); + const requiredChecks = + input.statusCheck.length > 0 ? input.statusCheck : (KIN_REPO_REQUIRED_CHECKS[repo] ?? []); + if (requiredChecks.length === 0 && !input.codeowners) { + return yield* refuse( + `${repo} has no default required checks; pass --status-check .`, + ); + } + if (input.test23 && repo in KIN_REPO_REQUIRED_CHECKS) { + return yield* refuse(`${repo} is a Kin repository; run --test-23 on a scratch repository.`); + } + const target = { repo, owner: input.owner, token: yield* ownerToken } satisfies RepoTarget; + if (input.codeowners) return yield* checkRepo(target, { requiredChecks, rulesets: false }); + if (input.check) return yield* checkRepo(target, { requiredChecks, rulesets: true }); + if (!input.test23) return yield* applyRepo(target, { requiredChecks }); + if (Option.isNone(input.kinOrg)) return yield* refuse("--test-23 needs --kin-org ."); + const orgId = yield* decodeOrgId(input.kinOrg.value); + const appConfig = Option.match(input.appId, { + onNone: () => KinGitHubApp.KinGitHubAppConfig.layer, + onSome: (appId) => Layer.succeed(KinGitHubApp.KinGitHubAppConfig, { appId }), + }); + return yield* Effect.gen(function* () { + const bot = yield* (yield* KinGitHubApp.KinGitHubApp).installationToken({ + repo, + permissions: { contents: "write", pull_requests: "write" }, + }); + const mergeToken = yield* (yield* OwnerMergeClient.OwnerMergeClient).token(orgId); + return yield* runTest23({ target, requiredChecks, botToken: bot.token, mergeToken }); + }).pipe( + Effect.provide( + Layer.mergeAll(KinGitHubApp.layer.pipe(Layer.provide(appConfig)), OwnerMergeClient.layer), + ), + ); + }); + return program.pipe( + Effect.catch(failed), + Effect.provide(Layer.mergeAll(Keychain.layer, FetchHttpClient.layer)), + Effect.flatMap(({ ok, lines }) => + Console.log(lines.join("\n")).pipe( + // exitCode, not a failed exit, so piped output is not cut off. + Effect.andThen( + Effect.sync(() => { + if (!ok) process.exitCode = 1; + }), + ), + ), + ), + ); + }, +).pipe( + Command.withDescription( + "Apply and check Kin's GitHub rulesets and CODEOWNERS, and run security test 23 on a scratch repo.", + ), +); diff --git a/docs/kin/specs/approvals.md b/docs/kin/specs/approvals.md index 48bb7da4a68e..222a66ae9445 100644 --- a/docs/kin/specs/approvals.md +++ b/docs/kin/specs/approvals.md @@ -349,7 +349,7 @@ Webhook events (consumed by the triggers spec): `pull_request`, `pull_request_re **The owner's GitHub review comes from the phone.** The ruleset needs a code-owner approval that the server can't produce, since the merge token above can't review. When the owner taps Approve, the phone, after the same biometric prompt, calls `POST /repos/{o}/{r}/pulls/{n}/reviews` with `{event: "APPROVE", commit_id: headSha}` directly to GitHub, using a user-to-server token for the Kin App held only on the phone (`expo-secure-store` with `requireAuthentication: true`, obtained once by device flow). Then it submits the grant. The server never sees this token. If the phone has no token, the card offers "Approve on GitHub" and waits for the `pull_request_review` webhook before enabling the Kin approval. -**Ruleset on each Kin repo** (`scripts/kin-rulesets.ts` applies it with `POST /repos/{o}/{r}/rulesets` and checks for drift): +**Ruleset on each Kin repo** (`scripts/kin-rulesets.ts` applies it with `POST /repos/{o}/{r}/rulesets` and checks for drift; the desired rulesets are one definition, `kinRulesets` in `apps/server/src/kin/github/KinRulesets.ts`): ```json { @@ -376,6 +376,7 @@ Webhook events (consumed by the triggers spec): `pull_request`, `pull_request_re "type": "required_status_checks", "parameters": { "strict_required_status_checks_policy": true, + "do_not_enforce_on_create": false, "required_status_checks": [{ "context": "" }] } } @@ -384,8 +385,10 @@ Webhook events (consumed by the triggers spec): `pull_request`, `pull_request_re ``` - `bypass_actors` is empty, including repository admins. Otherwise the owner's merge token could skip review. -- `.github/CODEOWNERS` contains `* @GLDRoger`, so the bot's approval never counts, and a PR that changes CODEOWNERS needs the owner's review too. -- A tag ruleset `kin-release` restricts `v*` tag creation and deletion, with no bypass, for when releases arrive. +- `.github/CODEOWNERS` contains `* @GLDRoger`, so the bot's approval never counts, and a PR that changes CODEOWNERS needs the owner's review too. The check reads the copy on the default branch (the one GitHub uses for reviews into it) and GitHub's `codeowners/errors`, and requires a `*` rule with every rule naming exactly `@GLDRoger`, so no later rule hands a path to someone else or to no one. Without it, `require_code_owner_review` is met by anyone's approval, so apply refuses to change any ruleset until CODEOWNERS passes. +- A tag ruleset `kin-release` (`refs/tags/v*`) blocks tag creation, update and deletion, with no bypass, for when releases arrive. Update is included so a release tag can't be moved to another commit. +- The required check for `GLDRoger/t3code` is `Check`, the `ci.yml` job that fails unless every other job passed or was skipped as not needed. Other repos pass `--status-check`. +- The script takes the owner's own sign-in (`GH_TOKEN` or a hidden prompt) and refuses anything else before writing: an installation token (`ghs_`, refused before any request), a credential `GET /user` rejects or reports as a bot, a login other than the owner's, and a credential without admin on the repo (GitHub hides `bypass_actors` from those, so drift could go unseen). `--check` reports every drifted field, including any bypass actor, a rule someone added or removed, and changed parameters; parameters GitHub adds that the spec doesn't set are not compared. Apply creates or replaces each ruleset by name, writes nothing when it already matches, and re-reads to confirm no drift. ### 11. Audit @@ -514,7 +517,7 @@ RPCs and scopes: `kin.approvals.list` (stream) and `get` → `orchestration:read 20. `the audit chain detects an edited row` (`kin.audit.verify`). 21. `the first approver key can't be confirmed from a remote session`. 22. Mobile (`apps/mobile/modules/kin-approval-key`, device test): `signing without biometrics fails`, `re-enrolling biometrics invalidates the key`, `DER signatures convert to compact and verify on the server`. -23. GitHub (`scripts/kin-rulesets.ts --check`, run against a scratch repo): `the owner merge token can't submit a review` (expect 403), `the bot can't merge to main` and `a merge without a code-owner review is blocked`. +23. GitHub (`scripts/kin-rulesets.ts --test-23`, run against a scratch repo after `--check` passes there): the bot opens a PR, the owner posts success statuses for the required checks, then `the owner merge token can't submit a review` (expect 403), `the bot can't merge to main` (and can't push to it), and `a merge without a code-owner review is blocked`. A last step has the owner approve and the merge token merge, which shows the blocks came from the review rule rather than something else. The logic is tested against a fake GitHub in `apps/server/src/kin/github/rulesetsSetup.test.ts`. Acceptance for phase 1: on `GLDRoger/t3code`, the lead requests a merge of a bot PR; the owner approves on the phone with Face ID; the GitHub review lands from the phone; the executor merges with the pinned SHA; the audit lists grant, device, SHA, provenance and merge commit. Tests 1–21 pass in CI; 22–23 pass on the release checklist. @@ -565,7 +568,7 @@ Later, marked by phase: ## Open questions 1. The phone needs a GitHub user token for the Kin App (device flow, once). Is that acceptable, or should phase 1 start with "Approve on GitHub" only and add the phone token later? -2. Owner-written PRs under an empty bypass list: route them through the bot, or add a time-boxed bypass toggled by an owner-signed action? +2. Owner-written PRs under an empty bypass list: route them through the bot, or add a time-boxed bypass toggled by an owner-signed action? Upstream syncs make this urgent: once `kin-main` is on `GLDRoger/t3code`, `KIN.md`'s `git push origin main kin` is rejected, a sync PR the owner opens has no code owner left to approve it, the bot can't open one because upstream merges change `.github/workflows` (no Workflows permission), and squash-only would flatten the upstream merge so the next sync conflicts. Decide before applying the ruleset there; one option is `allowed_merge_methods: ["squash", "merge"]` plus a second code owner for sync PRs. 3. Merge-queue repos: support `enablePullRequestAutoMerge` with `expectedHeadOid` later, or keep refusing? 4. Should the executor run as a separate OS user with its own keychain, so code running as the Kin server's user can't read the merge token at all? Phase 1 relies on the token being unable to review. 5. Desktop approvals: a Touch ID-gated Secure Enclave key on macOS through a native addon, or phone-only for good? diff --git a/knip.jsonc b/knip.jsonc index 6b5a8c8cbacf..1fc0e098e43e 100644 --- a/knip.jsonc +++ b/knip.jsonc @@ -28,6 +28,7 @@ // These fixture scripts are injected into a browser page by path. "fixtures/*/*.js", "kin-github-app.ts", + "kin-rulesets.ts", "knip-schemas.ts", "linux-after-pack.ts", "mobile-behavior/run.ts", diff --git a/scripts/kin-rulesets.ts b/scripts/kin-rulesets.ts new file mode 100644 index 000000000000..a214ac96dfe6 --- /dev/null +++ b/scripts/kin-rulesets.ts @@ -0,0 +1,17 @@ +// Kin's GitHub rulesets (approvals spec section 10): apply them, `--check` them for drift, +// `--codeowners`, or `--test-23` on a scratch repo. Runs on the owner's own GitHub sign-in +// (GH_TOKEN or a hidden prompt) and refuses the bot's. The command is apps/server/src/kin/github/ +// rulesetsSetup.ts, loaded by URL because the scripts project can't include server files. +import * as NodeRuntime from "@effect/platform-node/NodeRuntime"; +import * as NodeServices from "@effect/platform-node/NodeServices"; +import * as Effect from "effect/Effect"; +import { Command } from "effect/cli"; + +const setup: { + readonly kinRulesetsCommand: Command.Command<"kin-rulesets", unknown, never, never>; +} = await import(new URL("../apps/server/src/kin/github/rulesetsSetup.ts", import.meta.url).href); + +Command.run(setup.kinRulesetsCommand, { version: "0.0.0" }).pipe( + Effect.provide(NodeServices.layer), + NodeRuntime.runMain, +); From 76a4074c37531a009fe37d80b3eab7017c564e22 Mon Sep 17 00:00:00 2001 From: Surajsm60720 <1ds22is166@dsce.edu.in> Date: Sun, 8 Nov 2026 08:33:45 +0530 Subject: [PATCH 3/5] fix(kin): harden rulesets and security test 23 per review (APPR-11) - Tag ruleset sends update_allows_fetch_and_merge and covers v*/**; the test fake rejects rules missing parameters GitHub requires. - Required checks are pinned to GitHub Actions (integration 15368), and --check requires current_user_can_bypass "never". - --test-23 refuses Kin repos in any case, names without "scratch", and a GET /repos full_name that differs from --repo (redirects). - Test 23 waits for Actions checks and mergeable_state, matches refusals by status and GitHub's message, re-reads refs, and adds bait-and-switch, merge-token push, v* tag and ruleset probes. Cleanup failures are reported, and the bot token is revoked. - --owner is pinned to KIN_GITHUB_OWNER_LOGIN for Kin repos. - CODEOWNERS lines must be printable ASCII; tokens split on spaces/tabs. - Proposed upstream sync flow: require_last_push_approval off, squash and merge allowed (owner to confirm, open question 2). Co-Authored-By: Claude Opus 5.5 --- apps/server/src/kin/github/KinRulesets.ts | 48 +- apps/server/src/kin/github/githubRest.ts | 40 ++ .../src/kin/github/rulesetsSetup.test.ts | 523 +++++++++++++++--- apps/server/src/kin/github/rulesetsSetup.ts | 371 +++++-------- apps/server/src/kin/github/rulesetsTest23.ts | 504 +++++++++++++++++ docs/kin/specs/approvals.md | 29 +- 6 files changed, 1183 insertions(+), 332 deletions(-) create mode 100644 apps/server/src/kin/github/rulesetsTest23.ts diff --git a/apps/server/src/kin/github/KinRulesets.ts b/apps/server/src/kin/github/KinRulesets.ts index 29be132d6329..7fb32bd295c8 100644 --- a/apps/server/src/kin/github/KinRulesets.ts +++ b/apps/server/src/kin/github/KinRulesets.ts @@ -1,15 +1,21 @@ // Pure: the approvals spec section 10 rulesets and CODEOWNERS rule. Apply, `--check` and the // tests all read `kinRulesets`, so there is one definition of what GitHub should hold. -/** The owner: sole code owner, and the only sign-in the script accepts. */ -export const KIN_OWNER_LOGIN = "GLDRoger"; - -/** Required status check contexts per Kin repository; other repos pass `--status-check`. */ +/** + * Required status check contexts per Kin repository; other repos pass `--status-check`. Its keys + * count as Kin repositories even when `KIN_GITHUB_REPOS` leaves them out. + */ export const KIN_REPO_REQUIRED_CHECKS: Readonly>> = { // ci.yml's `Check` job fails unless every other CI job passed or was skipped as not needed. "GLDRoger/t3code": ["Check"], }; +/** + * The GitHub Actions App (`GET /apps/github-actions`). Pinning required checks to it stops a + * status anyone with commit-status access posts from satisfying them. + */ +export const GITHUB_ACTIONS_INTEGRATION_ID = 15368; + export const KIN_CODEOWNERS_PATH = ".github/CODEOWNERS"; export interface KinRulesetRule { @@ -46,9 +52,12 @@ export const kinRulesets = (requiredChecks: ReadonlyArray): ReadonlyArra required_approving_review_count: 1, require_code_owner_review: true, dismiss_stale_reviews_on_push: true, - require_last_push_approval: true, + // Off: it adds nothing against the bot, whose pushes the owner must approve anyway, and + // it deadlocks an upstream sync branch the owner pushed (spec section 10). + require_last_push_approval: false, required_review_thread_resolution: true, - allowed_merge_methods: ["squash"], + // `merge` is for the owner's upstream syncs; the executor squashes bot PRs. + allowed_merge_methods: ["squash", "merge"], }, }, { @@ -56,7 +65,10 @@ export const kinRulesets = (requiredChecks: ReadonlyArray): ReadonlyArra parameters: { strict_required_status_checks_policy: true, do_not_enforce_on_create: false, - required_status_checks: requiredChecks.map((context) => ({ context })), + required_status_checks: requiredChecks.map((context) => ({ + context, + integration_id: GITHUB_ACTIONS_INTEGRATION_ID, + })), }, }, ], @@ -66,8 +78,13 @@ export const kinRulesets = (requiredChecks: ReadonlyArray): ReadonlyArra target: "tag", enforcement: "active", bypass_actors: [], - conditions: { ref_name: { include: ["refs/tags/v*"], exclude: [] } }, - rules: [{ type: "creation" }, { type: "update" }, { type: "deletion" }], + // `*` stops at `/`, so `v*/**` covers tags like `v1/rc`. + conditions: { ref_name: { include: ["refs/tags/v*", "refs/tags/v*/**"], exclude: [] } }, + rules: [ + { type: "creation" }, + { type: "update", parameters: { update_allows_fetch_and_merge: false } }, + { type: "deletion" }, + ], }, ]; @@ -83,6 +100,8 @@ export interface LiveRuleset { readonly bypass_mode?: string | undefined; }> | undefined; + /** How the credential reading the ruleset could bypass it: `never` for every Kin credential. */ + readonly current_user_can_bypass?: string | undefined; readonly conditions?: unknown; readonly rules?: | ReadonlyArray<{ @@ -129,12 +148,15 @@ export function diffRuleset( }; compare("target", desired.target, live.target); compare("enforcement", desired.enforcement, live.enforcement); + // GitHub omits `bypass_actors` for a token without Administration even when its user is an admin. if (live.bypass_actors === undefined) { drift.push({ field: "bypass_actors", expected: "none", actual: "not visible to this credential", }); + } else { + compare("current_user_can_bypass", "never", live.current_user_can_bypass); } for (const actor of live.bypass_actors ?? []) { drift.push({ @@ -176,7 +198,13 @@ export function codeownersProblems(content: string, owner: string): ReadonlyArra const expected = `@${owner}`.toLowerCase(); let coversAll = false; content.split(/\r?\n/).forEach((raw, index) => { - const tokens = raw.trim().split(/\s+/).filter(Boolean); + // A BOM, non-breaking space or other non-ASCII character can make GitHub read a line + // differently from this check, so only printable ASCII and tabs are accepted. + if (/[^\t\x20-\x7e]/.test(raw)) { + problems.push(`line ${index + 1}: has a non-ASCII or control character (or a BOM)`); + return; + } + const tokens = raw.split(/[ \t]+/).filter(Boolean); const commentAt = tokens.findIndex((token) => token.startsWith("#")); const [pattern, ...owners] = commentAt === -1 ? tokens : tokens.slice(0, commentAt); if (pattern === undefined) return; diff --git a/apps/server/src/kin/github/githubRest.ts b/apps/server/src/kin/github/githubRest.ts index 3398786edcd6..7985f592c5af 100644 --- a/apps/server/src/kin/github/githubRest.ts +++ b/apps/server/src/kin/github/githubRest.ts @@ -107,3 +107,43 @@ export const gitHubStatus = Effect.fn("KinGitHub.status")(function* (input: { const response = yield* input.client.execute(request).pipe(Effect.mapError(fail)); return response.status; }); + +/** `/repos/{owner}/{name}` for an `owner/name` slug. */ +export const repoPath = (repo: string) => { + const [owner = "", name = ""] = repo.split("/"); + return `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}`; +}; + +export interface GitHubAnswer { + readonly status: number; + /** GitHub's `message`, or "" when the body has none. Error messages carry no credential. */ + readonly message: string; + readonly body: unknown; +} + +/** One GitHub REST call whose answer is judged by the caller; any status is returned. */ +export const gitHubAnswer = Effect.fn("KinGitHub.answer")(function* (input: { + readonly client: HttpClient.HttpClient; + readonly operation: string; + readonly method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE"; + readonly path: string; + readonly token: Redacted.Redacted; + readonly body?: unknown; +}) { + yield* Effect.annotateCurrentSpan({ "kin.github.operation": input.operation }); + const fail = () => new KinGitHubRequestError({ operation: input.operation, stage: "transport" }); + let request = gitHubRequest(input.method, input.path, input.token); + if (input.body !== undefined) { + request = yield* HttpClientRequest.bodyJson(request, input.body).pipe(Effect.mapError(fail)); + } + const response = yield* input.client.execute(request).pipe(Effect.mapError(fail)); + const body: unknown = yield* response.json.pipe(Effect.orElseSucceed(() => null)); + const message = + typeof body === "object" && + body !== null && + "message" in body && + typeof body.message === "string" + ? body.message + : ""; + return { status: response.status, message, body } satisfies GitHubAnswer; +}); diff --git a/apps/server/src/kin/github/rulesetsSetup.test.ts b/apps/server/src/kin/github/rulesetsSetup.test.ts index c18c47f6d32b..e8aa7b31cf68 100644 --- a/apps/server/src/kin/github/rulesetsSetup.test.ts +++ b/apps/server/src/kin/github/rulesetsSetup.test.ts @@ -7,13 +7,15 @@ import { describe } from "vite-plus/test"; import { codeownersProblems, kinRulesets } from "./KinRulesets.ts"; import * as Rulesets from "./rulesetsSetup.ts"; +import { isKinBlock, type KinBlock } from "./rulesetsTest23.ts"; import { fakeGitHub, type FakeAnswer, type RecordedRequest } from "./testFakes.ts"; const OWNER_TOKEN = "gho_owner-test"; const BOT_TOKEN = "ghs_bot-test"; const MERGE_TOKEN = "github_pat_merge-test"; -const repo = Schema.decodeSync(RepoSlug)("GLDRoger/t3code"); -const scratch = Schema.decodeSync(RepoSlug)("GLDRoger/kin-scratch"); +const decodeRepo = Schema.decodeSync(RepoSlug); +const repo = decodeRepo("GLDRoger/t3code"); +const scratch = decodeRepo("GLDRoger/kin-scratch"); const target = (token = OWNER_TOKEN, slug = repo): Rulesets.RepoTarget => ({ repo: slug, owner: "GLDRoger", @@ -27,56 +29,129 @@ type StoredRuleset = Record & { rules: Array<{ type: string; parameters?: Record }>; }; +// GitHub's REST reference (repos/rules) marks these parameters required; it answers 422 without them. +const REQUIRED_PARAMETERS: Record> = { + creation: {}, + deletion: {}, + non_fast_forward: {}, + update: { update_allows_fetch_and_merge: "boolean" }, + pull_request: { + dismiss_stale_reviews_on_push: "boolean", + require_code_owner_review: "boolean", + require_last_push_approval: "boolean", + required_approving_review_count: "number", + required_review_thread_resolution: "boolean", + }, + required_status_checks: { + required_status_checks: "array", + strict_required_status_checks_policy: "boolean", + }, +}; +const invalidRule = (rule: { type: string; parameters?: Record }) => { + const required = REQUIRED_PARAMETERS[rule.type]; + if (required === undefined) return `unknown rule ${rule.type}`; + if (Object.keys(required).length === 0) { + return rule.parameters === undefined ? null : `${rule.type} takes no parameters`; + } + for (const [key, type] of Object.entries(required)) { + const value = rule.parameters?.[key]; + const ok = type === "array" ? Array.isArray(value) : typeof value === type; + if (!ok) return `${rule.type}.${key} is required`; + } + const methods = rule.parameters?.allowed_merge_methods; + if ( + Array.isArray(methods) && + (methods.length === 0 || methods.some((m) => !["merge", "squash", "rebase"].includes(m))) + ) { + return "allowed_merge_methods"; + } + const checks = rule.parameters?.required_status_checks; + if ( + Array.isArray(checks) && + checks.some( + (check: { context?: unknown; integration_id?: unknown }) => + typeof check.context !== "string" || + (check.integration_id !== undefined && typeof check.integration_id !== "number"), + ) + ) { + return "required_status_checks items"; + } + return null; +}; + /** Repository settings GitHub would hold, answered the way its REST API does. */ const githubRepo = ( options: { readonly slug?: string; + /** What `GET /repos/{slug}` names, which differs after a rename or transfer. */ + readonly fullName?: string; readonly codeowners?: string | null; readonly codeownersErrors?: ReadonlyArray<{ line: number; kind: string }>; readonly user?: { login: string; type: string } | null; readonly admin?: boolean; + /** A token whose user is an admin but which lacks the Administration permission. */ + readonly hideBypass?: boolean; + /** Lets tokens other than the owner's write rulesets. */ + readonly anyoneCanAdminister?: boolean; readonly onPull?: (request: RecordedRequest) => FakeAnswer | undefined; } = {}, ) => { - const base = `/repos/${options.slug ?? "GLDRoger/t3code"}`; + const slug = options.slug ?? "GLDRoger/t3code"; + const base = `/repos/${slug}`; const rulesets: Array = []; let nextId = 1; - // GitHub adds parameters the spec doesn't set and omits false booleans on the way back. - const asReturned = (ruleset: StoredRuleset) => ({ - ...ruleset, - source_type: "Repository", - source: options.slug ?? "GLDRoger/t3code", - rules: ruleset.rules.map((rule) => - rule.type === "pull_request" - ? { - ...rule, - parameters: { ...rule.parameters, automatic_copilot_code_review_enabled: false }, - } - : rule.type === "required_status_checks" + // GitHub adds parameters the spec doesn't set and omits false booleans on the way back. Only an + // admin with the Administration permission sees bypass actors. + const asReturned = (ruleset: StoredRuleset, admin: boolean) => { + const { bypass_actors, ...rest } = ruleset; + return { + ...rest, + ...(admin ? { bypass_actors } : {}), + current_user_can_bypass: ruleset.current_user_can_bypass ?? "never", + source_type: "Repository", + source: slug, + rules: ruleset.rules.map((rule) => + rule.type === "pull_request" ? { ...rule, - parameters: Object.fromEntries( - Object.entries(rule.parameters ?? {}).filter(([, value]) => value !== false), - ), + parameters: { ...rule.parameters, automatic_copilot_code_review_enabled: false }, } - : rule, - ), - }); + : rule.type === "required_status_checks" + ? { + ...rule, + parameters: Object.fromEntries( + Object.entries(rule.parameters ?? {}).filter(([, value]) => value !== false), + ), + } + : rule, + ), + }; + }; + const validate = (body: StoredRuleset): FakeAnswer | null => { + const problem = body.rules.map(invalidRule).find((value) => value !== null); + return problem === undefined + ? null + : { status: 422, body: { message: `Invalid request.\n\n${problem}` } }; + }; const github = fakeGitHub((request): FakeAnswer => { const token = request.authorization?.replace(/^Bearer /, ""); + const owner = token === OWNER_TOKEN; if (request.path === "/user") { - const user = - token !== OWNER_TOKEN - ? null - : "user" in options - ? options.user - : { login: "GLDRoger", type: "User" }; + const user = !owner + ? null + : "user" in options + ? options.user + : { login: "GLDRoger", type: "User" }; return user === null ? { status: 403 } : { status: 200, body: user }; } if (request.method === "GET" && request.path === base) { return { status: 200, - body: { default_branch: "kin", permissions: { admin: options.admin ?? true } }, + body: { + full_name: options.fullName ?? slug, + default_branch: "kin", + permissions: { admin: options.admin ?? true }, + }, }; } if (request.path === `${base}/contents/.github/CODEOWNERS?ref=kin`) { @@ -102,20 +177,30 @@ const githubRepo = ( })), }; } + const canAdminister = owner || options.anyoneCanAdminister === true; if (request.method === "POST" && request.path === `${base}/rulesets`) { + if (!canAdminister) return { status: 403 }; + const invalid = validate(request.body as StoredRuleset); + if (invalid !== null) return invalid; const created = { ...(request.body as StoredRuleset), id: nextId++ }; rulesets.push(created); return { status: 201, body: { id: created.id } }; } + if (/\/rulesets\/\d+\/history$/.test(request.path)) { + return canAdminister ? { status: 200, body: [] } : { status: 403 }; + } const one = request.path.match(new RegExp(`^${base}/rulesets/(\\d+)$`)); if (one) { const index = rulesets.findIndex((ruleset) => ruleset.id === Number(one[1])); if (index === -1) return { status: 404 }; if (request.method === "PUT") { + if (!canAdminister) return { status: 403 }; + const invalid = validate(request.body as StoredRuleset); + if (invalid !== null) return invalid; rulesets[index] = { ...(request.body as StoredRuleset), id: rulesets[index]!.id }; return { status: 200, body: { id: rulesets[index]!.id } }; } - return { status: 200, body: asReturned(rulesets[index]!) }; + return { status: 200, body: asReturned(rulesets[index]!, owner && !options.hideBypass) }; } return options.onPull?.(request) ?? { status: 404 }; }); @@ -134,7 +219,7 @@ describe("kin-rulesets apply", () => { const github = githubRepo(); return Effect.gen(function* () { const first = yield* apply(); - assert.isTrue(first.ok); + assert.isTrue(first.ok, first.lines.join("\n")); assert.include(first.lines, "Ruleset kin-main (branch): created"); assert.include(first.lines, "Ruleset kin-release (tag): created"); assert.deepStrictEqual( @@ -168,8 +253,8 @@ describe("kin-rulesets apply", () => { const branchRule = (rulesets: Array) => rulesets.find((ruleset) => ruleset.name === "kin-main")!; -const pullRequestParameters = (rulesets: Array) => - branchRule(rulesets).rules.find((rule) => rule.type === "pull_request")!.parameters!; +const ruleParameters = (rulesets: Array, type: string) => + branchRule(rulesets).rules.find((rule) => rule.type === type)!.parameters!; describe("kin-rulesets --check", () => { it.effect.each([ @@ -182,19 +267,39 @@ describe("kin-rulesets --check", () => { }, " FAIL bypass_actors: expected none, got RepositoryRole 5 (always)", ], + [ + "a reader that could bypass", + (rulesets: Array) => { + branchRule(rulesets).current_user_can_bypass = "always"; + }, + ' FAIL current_user_can_bypass: expected "never", got "always"', + ], [ "the code-owner review switched off", (rulesets: Array) => { - pullRequestParameters(rulesets).require_code_owner_review = false; + ruleParameters(rulesets, "pull_request").require_code_owner_review = false; }, " FAIL rules.pull_request.require_code_owner_review: expected true, got false", ], [ - "merge commits allowed", + "rebase merges allowed", (rulesets: Array) => { - pullRequestParameters(rulesets).allowed_merge_methods = ["squash", "merge"]; + ruleParameters(rulesets, "pull_request").allowed_merge_methods = [ + "squash", + "merge", + "rebase", + ]; }, - ' FAIL rules.pull_request.allowed_merge_methods: expected ["squash"], got ["merge","squash"]', + ' FAIL rules.pull_request.allowed_merge_methods: expected ["merge","squash"], got ["merge","rebase","squash"]', + ], + [ + "a required check any integration can satisfy", + (rulesets: Array) => { + ruleParameters(rulesets, "required_status_checks").required_status_checks = [ + { context: "Check" }, + ]; + }, + ' FAIL rules.required_status_checks.required_status_checks: expected [{context:"Check",integration_id:15368}], got [{context:"Check"}]', ], [ "the deletion rule removed", @@ -236,11 +341,25 @@ describe("kin-rulesets --check", () => { assert.isTrue((yield* check()).ok); }).pipe(Effect.provide(github.layer)); }); + + it.effect("counts bypass actors it can't see as drift", () => { + const github = githubRepo({ hideBypass: true }); + return Effect.gen(function* () { + yield* apply(); + const result = yield* check(); + assert.isFalse(result.ok); + assert.include( + result.lines, + " FAIL bypass_actors: expected none, got not visible to this credential", + ); + }).pipe(Effect.provide(github.layer)); + }); }); describe("kin-rulesets CODEOWNERS", () => { it.each([ ["# Kin\n* @gldroger # owner\n", []], + ["*\t@GLDRoger\r\n", []], ["", ['no "* @GLDRoger" rule, so some paths have no code owner']], ["* @priya\n", ['line 1: "*" is owned by @priya, not only @GLDRoger']], ["* @GLDRoger @priya\n", ['line 1: "*" is owned by @GLDRoger @priya, not only @GLDRoger']], @@ -251,6 +370,15 @@ describe("kin-rulesets CODEOWNERS", () => { 'line 3: "/apps/" is owned by no one, not only @GLDRoger', ], ], + [ + "* @GLDRoger\n* @GLDRoger @priya\n* @GLDRoger\u000B@priya\n", + [ + 'no "* @GLDRoger" rule, so some paths have no code owner', + "line 1: has a non-ASCII or control character (or a BOM)", + "line 2: has a non-ASCII or control character (or a BOM)", + "line 3: has a non-ASCII or control character (or a BOM)", + ], + ], ] as const)("judges %j", (content, problems) => { assert.deepStrictEqual(codeownersProblems(content, "GLDRoger"), problems); }); @@ -298,61 +426,209 @@ describe("kin-rulesets credential", () => { }); }); -/** Answers the test 23 calls as a repository with the rulesets applied would. */ -const scratchRepo = (broken: { mergeTokenCanReview?: boolean; botCanMerge?: boolean } = {}) => { +const ruleViolation = (rule: string) => ({ + message: `Repository rule violations found\n\n${rule}\n\n`, + documentation_url: "https://docs.github.com/rest", + status: "422", +}); + +describe("test 23 refusal matching", () => { + it.each([ + [422, ruleViolation("Changes must be made through a pull request."), "rule_violation", true], + [ + 422, + ruleViolation("Cannot create ref due to creations being restricted."), + "rule_violation", + true, + ], + [422, { message: "Reference does not exist" }, "rule_violation", false], + [403, ruleViolation("Changes must be made through a pull request."), "rule_violation", false], + [ + 405, + ruleViolation("At least 1 approving review is required by reviewers with write access."), + "review_required", + true, + ], + [405, { message: "Waiting on code owner review from GLDRoger." }, "review_required", true], + [405, ruleViolation('Required status check "ci" is expected.'), "review_required", false], + [ + 409, + { message: "Head branch was modified. Review and try the merge again." }, + "review_required", + false, + ], + [403, { message: "Resource not accessible by personal access token" }, "forbidden", true], + [404, { message: "Not Found" }, "forbidden", false], + [404, { message: "Not Found" }, "refused", true], + [200, { message: "" }, "refused", false], + ] as const)("HTTP %i %j as %s is %s", (status, body, block, expected) => { + assert.strictEqual(isKinBlock({ status, message: body.message }, block as KinBlock), expected); + }); +}); + +const sha = (char: string) => char.repeat(40); + +/** + * A scratch repository with the rulesets applied, simulated: refs, the PR's head, reviews with + * stale dismissal, Actions check runs and merges. `broken` switches off one protection. + */ +const scratchRepo = ( + broken: { + readonly mergeTokenCanReview?: boolean; + readonly botCanMerge?: boolean; + readonly pushAllowed?: boolean; + readonly tagMovable?: boolean; + readonly noStaleDismissal?: boolean; + readonly anyoneCanAdminister?: boolean; + readonly noReleaseTag?: boolean; + readonly fullName?: string; + } = {}, +) => { const base = "/repos/GLDRoger/kin-scratch"; - let ownerReviewed = false; - const state = { branchDeleted: false, closed: false }; + const refs = new Map([["heads/kin", sha("a")]]); + if (!broken.noReleaseTag) refs.set("tags/v1.0.0", sha("7")); + const reviews: Array<{ state: string; commit_id: string; user: { login: string } }> = []; + const commits = new Map([ + ["0.md", sha("b")], + ["0-after-review.md", sha("c")], + ]); + const state = { head: "", merged: false, closed: false, revoked: false }; + const approved = () => + reviews.some((review) => review.state === "APPROVED" && review.commit_id === state.head); + const violation = (rule: string): FakeAnswer => ({ status: 422, body: ruleViolation(rule) }); const github = githubRepo({ slug: "GLDRoger/kin-scratch", + ...(broken.fullName === undefined ? {} : { fullName: broken.fullName }), + ...(broken.anyoneCanAdminister ? { anyoneCanAdminister: true } : {}), onPull: (request) => { const token = request.authorization?.replace(/^Bearer /, ""); + const body = request.body as Record | undefined; const route = `${request.method} ${request.path}`; + if (route === "DELETE /installation/token") { + state.revoked = token === BOT_TOKEN; + return { status: 204 }; + } + const ref = request.path.match(new RegExp(`^${base}/git/refs?/(.+)$`))?.[1]; + if (request.method === "GET" && ref !== undefined && request.path.includes("/git/ref/")) { + const at = refs.get(ref); + return at === undefined + ? { status: 404, body: { message: "Not Found" } } + : { status: 200, body: { ref: `refs/${ref}`, object: { sha: at } } }; + } + if (route === `GET ${base}/git/matching-refs/tags/v`) { + return { + status: 200, + body: [...refs] + .filter(([name]) => name.startsWith("tags/v")) + .map(([name, at]) => ({ ref: `refs/${name}`, object: { sha: at } })), + }; + } + if (route === `POST ${base}/git/refs`) { + const name = body!.ref!.slice("refs/".length); + if (name.startsWith("tags/v")) { + return violation("Cannot create ref due to creations being restricted."); + } + refs.set(name, body!.sha!); + return { status: 201, body: { ref: body!.ref } }; + } + if (request.method === "PATCH" && ref !== undefined) { + const allowed = ref === "heads/kin" ? broken.pushAllowed : broken.tagMovable; + if (!allowed) { + return violation( + ref === "heads/kin" + ? "Changes must be made through a pull request." + : "Cannot update this protected ref.", + ); + } + refs.set(ref, body!.sha!); + return { status: 200, body: { ref: `refs/${ref}`, object: { sha: body!.sha } } }; + } + if (request.method === "DELETE" && ref !== undefined) { + refs.delete(ref); + return { status: 204 }; + } + const file = request.path.match(new RegExp(`^${base}/contents/kin-test-23/(.+)$`))?.[1]; + if (request.method === "PUT" && file !== undefined) { + const commit = commits.get(file)!; + refs.set(`heads/${body!.branch}`, commit); + if (state.head !== "" && !broken.noStaleDismissal) { + for (const review of reviews) review.state = "DISMISSED"; + } + state.head = commit; + return { status: 201, body: { commit: { sha: commit } } }; + } switch (route) { - case `GET ${base}/git/ref/heads/kin`: - return { status: 200, body: { object: { sha: "a".repeat(40) } } }; - case `POST ${base}/git/refs`: - return { status: 201, body: { ref: "refs/heads/kin-test-23-0" } }; - case `PUT ${base}/contents/kin-test-23/0.md`: - return { status: 201, body: { commit: { sha: "b".repeat(40) } } }; case `POST ${base}/pulls`: - return { status: 201, body: { number: 7, head: { sha: "b".repeat(40) } } }; - case `POST ${base}/statuses/${"b".repeat(40)}`: - return { status: 201, body: { id: 1 } }; + return { status: 201, body: { number: 7, head: { sha: state.head } } }; + case `GET ${base}/pulls/7`: + return { + status: 200, + body: { + number: 7, + head: { sha: state.head }, + mergeable: true, + mergeable_state: approved() ? "clean" : "blocked", + }, + }; + case `GET ${base}/commits/${state.head}/check-runs?per_page=100`: + return { + status: 200, + body: { + check_runs: [ + { name: "ci", status: "completed", conclusion: "success", app: { id: 15368 } }, + ], + }, + }; case `POST ${base}/pulls/7/reviews`: - if (token === OWNER_TOKEN) ownerReviewed = true; - return token === OWNER_TOKEN || broken.mergeTokenCanReview - ? { status: 200, body: {} } - : { status: 403 }; + if (token === OWNER_TOKEN || broken.mergeTokenCanReview) { + reviews.push({ + state: "APPROVED", + commit_id: body!.commit_id!, + user: { login: "GLDRoger" }, + }); + return { status: 200, body: {} }; + } + return { + status: 403, + body: { message: "Resource not accessible by personal access token" }, + }; + case `GET ${base}/pulls/7/reviews?per_page=100`: + return { status: 200, body: reviews }; case `PUT ${base}/pulls/7/merge`: - return (token === BOT_TOKEN && broken.botCanMerge) || - (token === MERGE_TOKEN && ownerReviewed) - ? { status: 200, body: { merged: true } } - : { status: 405 }; - case `PATCH ${base}/git/refs/heads/kin`: - return { status: 422 }; + if (approved() || (token === BOT_TOKEN && broken.botCanMerge)) { + state.merged = true; + return { status: 200, body: { merged: true } }; + } + return { + status: 405, + body: ruleViolation("Waiting on code owner review from GLDRoger."), + }; case `PATCH ${base}/pulls/7`: state.closed = true; return { status: 200, body: {} }; - case `DELETE ${base}/git/refs/heads/kin-test-23-0`: - state.branchDeleted = true; - return { status: 204 }; } return undefined; }, }); - return { ...github, state }; + return { ...github, refs, state }; }; +const tokens = Effect.succeed({ + botToken: Redacted.make(BOT_TOKEN), + mergeToken: Redacted.make(MERGE_TOKEN), +}); +const kinRepos = Rulesets.kinRepos([]); +const runTest23 = (slug = scratch) => + Rulesets.runTest23({ + target: target(OWNER_TOKEN, slug), + requiredChecks: ["ci"], + kinRepos, + tokens, + }); const test23 = () => Effect.gen(function* () { yield* Rulesets.applyRepo(target(OWNER_TOKEN, scratch), { requiredChecks: ["ci"] }); - return yield* Rulesets.runTest23({ - target: target(OWNER_TOKEN, scratch), - requiredChecks: ["ci"], - botToken: Redacted.make(BOT_TOKEN), - mergeToken: Redacted.make(MERGE_TOKEN), - }); + return yield* runTest23(); }); describe("security test 23 (kin-rulesets --test-23)", () => { @@ -361,43 +637,118 @@ describe("security test 23 (kin-rulesets --test-23)", () => { return Effect.gen(function* () { const result = yield* test23(); assert.isTrue(result.ok, result.lines.join("\n")); - assert.include(result.lines, " PASS the owner merge token can't submit a review (HTTP 403)"); - assert.include(result.lines, " PASS the bot can't merge to the default branch (HTTP 405)"); - assert.include(result.lines, " PASS the bot can't push to the default branch (HTTP 422)"); - assert.include( - result.lines, - " PASS a merge without a code-owner review is blocked (HTTP 405)", - ); - assert.isTrue(github.state.branchDeleted); + for (const line of [ + " PASS GitHub reports the PR blocked at bbbbbbb (mergeable_state blocked)", + " PASS the merge token can't submit a review (HTTP 403: Resource not accessible by personal access token)", + " PASS the bot can't merge without a code-owner review (HTTP 405: Repository rule violations found Waiting on code owner review from GLDRoger.)", + " PASS the merge token can't push to kin (HTTP 422: Repository rule violations found Changes must be made through a pull request.)", + " PASS the bot can't create a v* tag (HTTP 422: Repository rule violations found Cannot create ref due to creations being restricted.)", + " PASS the merge token can't move v1.0.0 (HTTP 422: Repository rule violations found Cannot update this protected ref.)", + " PASS the bot can't bypass kin-main (HTTP 200, current_user_can_bypass never)", + " PASS the merge token can't read kin-release's history (HTTP 403)", + " PASS the merge token can't change kin-main (HTTP 403)", + " PASS GitHub reports the PR clean at bbbbbbb (mergeable_state clean)", + " PASS the push dismissed GLDRoger's review (DISMISSED)", + " PASS the merge token can't merge the switched head (HTTP 405: Repository rule violations found Waiting on code owner review from GLDRoger.)", + " PASS the rulesets show no drift afterwards", + "PASS: security test 23.", + ]) { + assert.include(result.lines, line); + } + assert.isTrue(github.state.merged); assert.isFalse(github.state.closed); + assert.isTrue(github.state.revoked); + assert.isFalse(github.refs.has("heads/kin-test-23-0")); + assert.isFalse(result.lines.some((line) => line.includes("WARN"))); }).pipe(Effect.provide(github.layer)); }); it.effect.each([ - ["a merge token that can review", { mergeTokenCanReview: true }], - ["a bot that can merge alone", { botCanMerge: true }], - ] as const)("fails with %s and cleans up its PR", ([, broken]) => { + ["a merge token that can review", { mergeTokenCanReview: true }, "can't submit a review"], + ["a bot that can merge alone", { botCanMerge: true }, "the bot can't merge"], + ["a push to the default branch", { pushAllowed: true }, "but heads/kin is now"], + ["a movable release tag", { tagMovable: true }, "but tags/v1.0.0 is now"], + ["no stale-review dismissal", { noStaleDismissal: true }, "dismissed GLDRoger's review"], + [ + "tokens that can administer rulesets", + { anyoneCanAdminister: true }, + "the bot can't read kin-main's history", + ], + ] as const)("fails with %s and cleans up", ([, broken, failing]) => { const github = scratchRepo(broken); return Effect.gen(function* () { const result = yield* test23(); assert.isFalse(result.ok); - assert.isTrue(result.lines.some((line) => line.startsWith(" FAIL"))); - assert.isTrue(github.state.closed); - assert.isTrue(github.state.branchDeleted); + const failed = result.lines.find((line) => line.startsWith(" FAIL")); + assert.include(failed, failing); + assert.isTrue(github.state.revoked); + assert.isFalse(github.refs.has("heads/kin-test-23-0")); + assert.isFalse(github.refs.has("tags/v0.0.0-kin-test-23-0")); + assert.strictEqual(github.refs.get("tags/v1.0.0"), sha("7")); + if (!github.state.merged) assert.isTrue(github.state.closed); }).pipe(Effect.provide(github.layer)); }); - it.effect("doesn't run until the scratch repo has no drift", () => { + it.effect("doesn't run, or take tokens, until the scratch repo has no drift", () => { const github = scratchRepo(); return Effect.gen(function* () { const result = yield* Rulesets.runTest23({ target: target(OWNER_TOKEN, scratch), requiredChecks: ["ci"], - botToken: Redacted.make(BOT_TOKEN), - mergeToken: Redacted.make(MERGE_TOKEN), + kinRepos, + tokens: Effect.die("tokens taken"), }); assert.isFalse(result.ok); assert.lengthOf(writes(github.requests), 0); }).pipe(Effect.provide(github.layer)); }); + + it.effect("needs a v* tag to try moving, and opens nothing without one", () => { + const github = scratchRepo({ noReleaseTag: true }); + return Effect.gen(function* () { + const result = yield* test23(); + const before = github.requests.findIndex((request) => request.path.includes("matching-refs")); + assert.isFalse(result.ok); + assert.include(result.lines[0], "has no v* tag"); + assert.deepStrictEqual( + writes(github.requests.slice(before)).map((request) => request.path), + ["/installation/token"], + ); + }).pipe(Effect.provide(github.layer)); + }); + + it.effect.each([ + ["a Kin repository in another case", "gldroger/t3code", "is a Kin repository"], + ["a repository not named scratch", "GLDRoger/sandbox", 'has no "scratch" in its name'], + ] as const)("refuses %s before any request", ([, slug, reason]) => { + const github = scratchRepo(); + const requested = decodeRepo(slug); + return Effect.gen(function* () { + const error = yield* Effect.flip(runTest23(requested)); + assert.include(error.message, reason); + assert.lengthOf(github.requests, 0); + }).pipe(Effect.provide(github.layer)); + }); + + it.effect.each([ + ["redirects to a Kin repository", "GLDRoger/t3code", "not GLDRoger/kin-scratch"], + ["answers for another scratch repository", "GLDRoger/other-scratch", "renamed or moved"], + ] as const)("refuses, writing nothing, when GitHub %s", ([, fullName, reason]) => { + const github = scratchRepo({ fullName }); + return Effect.gen(function* () { + yield* Rulesets.applyRepo(target(OWNER_TOKEN, scratch), { requiredChecks: ["ci"] }); + const before = github.requests.length; + const error = yield* Effect.flip(runTest23()); + assert.include(error.message, reason); + assert.lengthOf(writes(github.requests.slice(before)), 0); + }).pipe(Effect.provide(github.layer)); + }); + + it.effect("accepts a name GitHub reports in another case", () => { + const github = scratchRepo({ fullName: "gldroger/KIN-SCRATCH" }); + return Effect.gen(function* () { + const result = yield* test23(); + assert.isTrue(result.ok, result.lines.join("\n")); + }).pipe(Effect.provide(github.layer)); + }); }); diff --git a/apps/server/src/kin/github/rulesetsSetup.ts b/apps/server/src/kin/github/rulesetsSetup.ts index 1cca3ab4f258..577e684ef0c7 100644 --- a/apps/server/src/kin/github/rulesetsSetup.ts +++ b/apps/server/src/kin/github/rulesetsSetup.ts @@ -2,7 +2,6 @@ // them for drift, check CODEOWNERS, and run security test 23 on a scratch repository. It runs on // the owner's own GitHub sign-in and refuses the bot's. import { KinOrgId, RepoSlug } from "@t3tools/contracts"; -import * as Clock from "effect/Clock"; import * as Config from "effect/Config"; import * as Console from "effect/Console"; import * as Effect from "effect/Effect"; @@ -11,14 +10,13 @@ import * as Option from "effect/Option"; import * as Redacted from "effect/Redacted"; import * as Schema from "effect/Schema"; import { Command, Flag, Prompt } from "effect/cli"; -import { FetchHttpClient, HttpClient, HttpClientRequest } from "effect/http"; +import { FetchHttpClient, HttpClient } from "effect/http"; -import { gitHubJson, gitHubRequest, KinGitHubRequestError } from "./githubRest.ts"; +import { gitHubAnswer, gitHubJson, repoPath } from "./githubRest.ts"; import * as Keychain from "./Keychain.ts"; import * as KinGitHubApp from "./KinGitHubApp.ts"; import { KIN_CODEOWNERS_PATH, - KIN_OWNER_LOGIN, KIN_REPO_REQUIRED_CHECKS, codeownersProblems, diffRuleset, @@ -27,6 +25,7 @@ import { } from "./KinRulesets.ts"; import { KinGitHubScope } from "./KinGitHubScope.ts"; import * as OwnerMergeClient from "./OwnerMergeClient.ts"; +import { runTest23Probes } from "./rulesetsTest23.ts"; export interface RulesetsResult { readonly ok: boolean; @@ -51,6 +50,7 @@ export interface RepoTarget { const UserResponse = Schema.Struct({ login: Schema.String, type: Schema.String }); const RepoResponse = Schema.Struct({ + full_name: Schema.String, default_branch: Schema.String, permissions: Schema.optional(Schema.Struct({ admin: Schema.Boolean })), }); @@ -65,6 +65,7 @@ const RulesetDetail = Schema.Struct({ name: Schema.String, target: Schema.String, enforcement: Schema.String, + current_user_can_bypass: Schema.optional(Schema.String), bypass_actors: Schema.optional( Schema.Array( Schema.Struct({ @@ -89,40 +90,8 @@ const ContentResponse = Schema.Struct({ content: Schema.String, encoding: Schema const CodeownersErrors = Schema.Struct({ errors: Schema.Array(Schema.Struct({ line: Schema.Int, kind: Schema.String })), }); -const RefResponse = Schema.Struct({ object: Schema.Struct({ sha: Schema.String }) }); -const PullResponse = Schema.Struct({ - number: Schema.Int, - head: Schema.Struct({ sha: Schema.String }), -}); - const refuse = (reason: string) => Effect.fail(new KinRulesetsRefusedError({ reason })); -const repoPath = (repo: RepoSlug) => { - const [owner, name] = repo.split("/") as [string, string]; - return `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}`; -}; - -/** One call where only the status matters; the body is never read. */ -const statusOf = Effect.fn("kinRulesets.statusOf")(function* (input: { - readonly operation: string; - readonly method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE"; - readonly path: string; - readonly token: Redacted.Redacted; - readonly body?: unknown; -}) { - const client = yield* HttpClient.HttpClient; - const transport = () => - new KinGitHubRequestError({ operation: input.operation, stage: "transport" }); - let request = gitHubRequest(input.method, input.path, input.token); - if (input.body !== undefined) { - request = yield* HttpClientRequest.bodyJson(request, input.body).pipe( - Effect.mapError(transport), - ); - } - const response = yield* client.execute(request).pipe(Effect.mapError(transport)); - return response.status; -}); - /** * The owner's own admin sign-in, or a refusal. The bot App's installation tokens (`ghs_`) never * leave the process; any credential GitHub reports as a bot or as someone else is refused. @@ -173,8 +142,9 @@ export const verifyOwnerCredential = Effect.fn("kinRulesets.verifyOwnerCredentia `${login} can't administer ${target.repo} with this credential, so it can't see or set bypass actors.`, ); } - return { login, defaultBranch: repo.body.default_branch }; + return { login, defaultBranch: repo.body.default_branch, fullName: repo.body.full_name }; }); +type VerifiedOwner = Effect.Success>; /** CODEOWNERS on the default branch, which is the copy GitHub reads for reviews into it. */ export const checkCodeowners = Effect.fn("kinRulesets.checkCodeowners")(function* ( @@ -269,26 +239,36 @@ const codeownersLines = (problems: ReadonlyArray, owner: string) => ? [`CODEOWNERS: ok (@${owner} owns every path)`] : ["CODEOWNERS: FAIL", ...problems.map((problem) => ` FAIL ${problem}`)]; -/** `--check` and `--codeowners`: nothing is written. */ -export const checkRepo = Effect.fn("kinRulesets.check")(function* ( +const checkVerified = Effect.fn("kinRulesets.checkVerified")(function* ( target: RepoTarget, + { login, defaultBranch }: VerifiedOwner, input: { readonly requiredChecks: ReadonlyArray; readonly rulesets: boolean }, ) { - const { login, defaultBranch } = yield* verifyOwnerCredential(target); const problems = yield* checkCodeowners(target, defaultBranch); const lines = [ `${target.repo} (default branch ${defaultBranch}), checked as ${login}`, ...codeownersLines(problems, target.owner), ]; let ok = problems.length === 0; + const live = input.rulesets + ? yield* readRulesets(target, kinRulesets(input.requiredChecks)) + : new Map(); if (input.rulesets) { - const desired = kinRulesets(input.requiredChecks); - for (const result of driftLines(desired, yield* readRulesets(target, desired))) { + for (const result of driftLines(kinRulesets(input.requiredChecks), live)) { ok &&= result.ok; lines.push(...result.lines); } } lines.push(ok ? "PASS: no drift." : "FAIL: see above."); + return { ok, lines, live }; +}); + +/** `--check` and `--codeowners`: nothing is written. */ +export const checkRepo = Effect.fn("kinRulesets.check")(function* ( + target: RepoTarget, + input: { readonly requiredChecks: ReadonlyArray; readonly rulesets: boolean }, +) { + const { ok, lines } = yield* checkVerified(target, yield* verifyOwnerCredential(target), input); return { ok, lines } satisfies RulesetsResult; }); @@ -344,197 +324,117 @@ export const applyRepo = Effect.fn("kinRulesets.apply")(function* ( return { ok, lines } satisfies RulesetsResult; }); -// Success codes would mean the action went through; 401 and 404 mean the probe never reached -// the rule, so they don't count as blocked either. -const isBlocked = (status: number) => status >= 400 && status !== 401 && status !== 404; +const isKinRepo = (kinRepos: ReadonlyArray, repo: string) => + kinRepos.some((kin) => kin.toLowerCase() === repo.toLowerCase()); /** - * Security test 23 on a scratch repository: the bot opens a PR, then the owner merge token tries - * to review, the bot tries to merge and to push, and the merge token tries to merge without a - * code-owner review. A final review by the owner followed by a successful merge shows the - * earlier blocks came from the review rule. Required checks get success statuses from the owner. + * Why `repo` can't host test 23, or null. Test 23 opens and merges a PR and tries to move tags, so + * it runs only on a repository named as a scratch one and never on a Kin repository. */ -export const runTest23 = Effect.fn("kinRulesets.test23")(function* (input: { +export function scratchRepoProblem(repo: string, kinRepos: ReadonlyArray): string | null { + if (isKinRepo(kinRepos, repo)) { + return `${repo} is a Kin repository; run --test-23 on a scratch repository.`; + } + if (!/scratch/i.test(repo.split("/")[1] ?? "")) { + return `${repo} has no "scratch" in its name; test 23 runs only on a scratch repository.`; + } + return null; +} + +/** The repositories test 23 must never touch: `KIN_GITHUB_REPOS` and the known Kin ones. */ +export const kinRepos = (scoped: ReadonlyArray) => [ + ...scoped, + ...Object.keys(KIN_REPO_REQUIRED_CHECKS), +]; + +/** + * Security test 23 on a scratch repository. The owner is checked once, and the repository GitHub + * answers for (`full_name`, which follows renames and transfers) must be the one asked for and a + * scratch one. `tokens` runs only after that and after `--check` passes; the bot token it returns + * is revoked at the end. + */ +export const runTest23 = Effect.fn("kinRulesets.test23Run")(function* (input: { readonly target: RepoTarget; readonly requiredChecks: ReadonlyArray; - readonly botToken: Redacted.Redacted; - readonly mergeToken: Redacted.Redacted; + readonly kinRepos: ReadonlyArray; + readonly tokens: Effect.Effect< + { + readonly botToken: Redacted.Redacted; + readonly mergeToken: Redacted.Redacted; + }, + E, + R + >; }) { - const client = yield* HttpClient.HttpClient; const { target } = input; - const path = repoPath(target.repo); - const check = yield* checkRepo(target, { requiredChecks: input.requiredChecks, rulesets: true }); + const before = scratchRepoProblem(target.repo, input.kinRepos); + if (before !== null) return yield* refuse(before); + const owner = yield* verifyOwnerCredential(target); + const answered = + owner.fullName.toLowerCase() === target.repo.toLowerCase() + ? scratchRepoProblem(owner.fullName, input.kinRepos) + : `GitHub answered for ${owner.fullName}, not ${target.repo}; it was renamed or moved.`; + if (answered !== null) return yield* refuse(answered); + const desired = kinRulesets(input.requiredChecks); + const check = yield* checkVerified(target, owner, { + requiredChecks: input.requiredChecks, + rulesets: true, + }); if (!check.ok) { return { ok: false, lines: [...check.lines, "Test 23 not run: apply the rulesets to the scratch repo first."], } satisfies RulesetsResult; } - const { defaultBranch } = yield* verifyOwnerCredential(target); - const stamp = yield* Clock.currentTimeMillis; - const branch = `kin-test-23-${stamp}`; - const base = yield* gitHubJson({ - client, - operation: "git.getRef", - method: "GET", - path: `${path}/git/ref/heads/${encodeURIComponent(defaultBranch)}`, - token: input.botToken, - schema: RefResponse, - }); - yield* gitHubJson({ + const { botToken, mergeToken } = yield* input.tokens; + const client = yield* HttpClient.HttpClient; + const revokeLines: Array = []; + const revoke = gitHubAnswer({ client, - operation: "git.createRef", - method: "POST", - path: `${path}/git/refs`, - token: input.botToken, - body: { ref: `refs/heads/${branch}`, sha: base.body.object.sha }, - schema: Schema.Struct({ ref: Schema.String }), - okStatuses: [201], + operation: "installation.revokeToken", + method: "DELETE", + path: "/installation/token", + token: botToken, + }).pipe( + Effect.map((answer) => (answer.status === 204 ? null : `HTTP ${answer.status}`)), + Effect.orElseSucceed(() => "GitHub unreachable"), + Effect.map((problem) => { + if (problem !== null) { + revokeLines.push( + ` WARN cleanup: couldn't revoke the bot token (${problem}); it expires within the hour`, + ); + } + }), + ); + const probes = yield* runTest23Probes({ + repo: target.repo, + owner: target.owner, + defaultBranch: owner.defaultBranch, + requiredChecks: input.requiredChecks, + rulesets: desired.flatMap((ruleset) => { + const id = check.live.get(ruleset.name)?.id; + return id === undefined ? [] : [{ id, desired: ruleset }]; + }), + ownerToken: target.token, + botToken, + mergeToken, + }).pipe(Effect.ensuring(revoke)); + // The change probes sent the desired bodies, so drift here means something else wrote to them. + const after = yield* checkVerified(target, owner, { + requiredChecks: input.requiredChecks, + rulesets: true, }); - let merged = false; - let pullNumber: number | undefined; - const run = Effect.gen(function* () { - yield* gitHubJson({ - client, - operation: "repos.createFile", - method: "PUT", - path: `${path}/contents/kin-test-23/${stamp}.md`, - token: input.botToken, - body: { - message: "test: kin security test 23", - content: Buffer.from("Kin security test 23. Safe to delete.\n").toString("base64"), - branch, - }, - schema: Schema.Struct({ commit: Schema.Struct({ sha: Schema.String }) }), - okStatuses: [201], - }); - const pull = yield* gitHubJson({ - client, - operation: "pulls.create", - method: "POST", - path: `${path}/pulls`, - token: input.botToken, - body: { title: "Kin security test 23", head: branch, base: defaultBranch }, - schema: PullResponse, - okStatuses: [201], - }); - pullNumber = pull.body.number; - const headSha = pull.body.head.sha; - const pullPath = `${path}/pulls/${pull.body.number}`; - for (const context of input.requiredChecks) { - yield* gitHubJson({ - client, - operation: "repos.createStatus", - method: "POST", - path: `${path}/statuses/${headSha}`, - token: target.token, - body: { state: "success", context, description: "Kin security test 23" }, - schema: Schema.Struct({ id: Schema.Int }), - okStatuses: [201], - }); - } - const mergeBody = { sha: headSha, merge_method: "squash" }; - const probes: ReadonlyArray<{ - readonly name: string; - readonly pass: (status: number) => boolean; - readonly request: Parameters[0]; - }> = [ - { - name: "the owner merge token can't submit a review", - pass: (status) => status === 403, - request: { - operation: "pulls.createReview", - method: "POST", - path: `${pullPath}/reviews`, - token: input.mergeToken, - body: { event: "APPROVE", commit_id: headSha }, - }, - }, - { - name: "the bot can't merge to the default branch", - pass: isBlocked, - request: { - operation: "pulls.merge", - method: "PUT", - path: `${pullPath}/merge`, - token: input.botToken, - body: mergeBody, - }, - }, - { - name: "the bot can't push to the default branch", - pass: isBlocked, - request: { - operation: "git.updateRef", - method: "PATCH", - path: `${path}/git/refs/heads/${encodeURIComponent(defaultBranch)}`, - token: input.botToken, - body: { sha: headSha, force: false }, - }, - }, - { - name: "a merge without a code-owner review is blocked", - pass: isBlocked, - request: { - operation: "pulls.merge", - method: "PUT", - path: `${pullPath}/merge`, - token: input.mergeToken, - body: mergeBody, - }, - }, - ]; - const lines = [ - `Test 23 on ${target.repo}, PR #${pull.body.number} by the bot at ${headSha.slice(0, 7)}:`, - ]; - let ok = true; - for (const probe of probes) { - const status = yield* statusOf(probe.request); - const pass = probe.pass(status); - ok &&= pass; - lines.push(` ${pass ? "PASS" : "FAIL"} ${probe.name} (HTTP ${status})`); - if (!pass) return { ok: false, lines: [...lines, "FAIL: stopped at the first failure."] }; - } - const review = yield* statusOf({ - operation: "pulls.createReview", - method: "POST", - path: `${pullPath}/reviews`, - token: target.token, - body: { event: "APPROVE", commit_id: headSha }, - }); - let merge: number | undefined; - // GitHub recomputes mergeability after a review, so the first merge can still see it blocked. - for (let attempt = 0; review === 200 && attempt < 5; attempt++) { - merge = yield* statusOf(probes[3]!.request); - if (merge !== 405) break; - yield* Effect.sleep("2 seconds"); - } - merged = merge === 200; - ok &&= merged; - lines.push( - ` ${merged ? "PASS" : "FAIL"} after ${target.owner}'s review the merge token merges (review HTTP ${review}, merge HTTP ${merge ?? "not tried"}), so the blocks came from the rules`, + const ok = probes.ok && after.ok; + return { + ok, + lines: [ + ...probes.lines, + ...revokeLines, + after.ok ? " PASS the rulesets show no drift afterwards" : " FAIL the rulesets drifted:", + ...(after.ok ? [] : after.lines), ok ? "PASS: security test 23." : "FAIL: see above.", - ); - return { ok, lines } satisfies RulesetsResult; - }); - const cleanup = Effect.gen(function* () { - if (!merged && pullNumber !== undefined) { - yield* statusOf({ - operation: "pulls.close", - method: "PATCH", - path: `${path}/pulls/${pullNumber}`, - token: input.botToken, - body: { state: "closed" }, - }); - } - yield* statusOf({ - operation: "git.deleteRef", - method: "DELETE", - path: `${path}/git/refs/heads/${encodeURIComponent(branch)}`, - token: input.botToken, - }); - }).pipe(Effect.ignore); - return yield* run.pipe(Effect.ensuring(cleanup)); + ], + } satisfies RulesetsResult; }); const decodeRepo = Schema.decodeUnknownEffect(RepoSlug); @@ -592,8 +492,10 @@ export const kinRulesetsCommand = Command.make( Flag.withDefault(false), ), owner: Flag.String("owner").pipe( - Flag.withDescription("The owner's GitHub login: sole code owner and the required sign-in."), - Flag.withDefault(KIN_OWNER_LOGIN), + Flag.withDescription( + "The code owner and required sign-in, for a repository outside Kin; Kin repos and --test-23 use KIN_GITHUB_OWNER_LOGIN.", + ), + Flag.optional, ), statusCheck: Flag.String("status-check").pipe( Flag.withDescription( @@ -613,21 +515,33 @@ export const kinRulesetsCommand = Command.make( () => new KinRulesetsRefusedError({ reason: "--repo must be owner/name." }), ), ); - const requiredChecks = - input.statusCheck.length > 0 ? input.statusCheck : (KIN_REPO_REQUIRED_CHECKS[repo] ?? []); + const scope = yield* KinGitHubScope; + const protectedRepos = kinRepos(scope.repos); + if (input.test23) { + const problem = scratchRepoProblem(repo, protectedRepos); + if (problem !== null) return yield* refuse(problem); + } + // Kin repos and test 23's merge token belong to the configured owner, and no one else. + const pinned = input.test23 || isKinRepo(protectedRepos, repo); + const owner = Option.getOrElse(input.owner, () => scope.ownerLogin); + if (pinned && owner.toLowerCase() !== scope.ownerLogin.toLowerCase()) { + return yield* refuse( + `--owner ${owner} differs from KIN_GITHUB_OWNER_LOGIN (${scope.ownerLogin}), which ${input.test23 ? "test 23" : repo} must use.`, + ); + } + const known = Object.entries(KIN_REPO_REQUIRED_CHECKS).find( + ([slug]) => slug.toLowerCase() === repo.toLowerCase(), + )?.[1]; + const requiredChecks = input.statusCheck.length > 0 ? input.statusCheck : (known ?? []); if (requiredChecks.length === 0 && !input.codeowners) { return yield* refuse( `${repo} has no default required checks; pass --status-check .`, ); } - if (input.test23 && repo in KIN_REPO_REQUIRED_CHECKS) { - return yield* refuse(`${repo} is a Kin repository; run --test-23 on a scratch repository.`); - } - const target = { repo, owner: input.owner, token: yield* ownerToken } satisfies RepoTarget; + const target = { repo, owner, token: yield* ownerToken } satisfies RepoTarget; if (input.codeowners) return yield* checkRepo(target, { requiredChecks, rulesets: false }); if (input.check) return yield* checkRepo(target, { requiredChecks, rulesets: true }); if (!input.test23) return yield* applyRepo(target, { requiredChecks }); - const scope = yield* KinGitHubScope; const appConfig = Option.match(input.appId, { onNone: () => KinGitHubApp.KinGitHubAppConfig.layer, onSome: (appId) => Layer.succeed(KinGitHubApp.KinGitHubAppConfig, { appId }), @@ -636,7 +550,7 @@ export const kinRulesetsCommand = Command.make( // token is scoped to the Kin repos, so test 23 takes a scratch token with the same shape and // runs `save`'s probes on it without keeping it. const scratchScope = Layer.succeed(KinGitHubScope, { ...scope, repos: [repo] }); - return yield* Effect.gen(function* () { + const tokens = Effect.gen(function* () { const mergeToken = yield* scratchMergeToken; yield* (yield* OwnerMergeClient.OwnerMergeClient).save({ orgId: TEST_23_ORG, @@ -647,7 +561,7 @@ export const kinRulesetsCommand = Command.make( permissions: { contents: "write", pull_requests: "write" }, holder: "worker", }); - return yield* runTest23({ target, requiredChecks, botToken: bot.token, mergeToken }); + return { botToken: bot.token, mergeToken }; }).pipe( Effect.provide( Layer.mergeAll( @@ -658,6 +572,7 @@ export const kinRulesetsCommand = Command.make( ), ), ); + return yield* runTest23({ target, requiredChecks, kinRepos: protectedRepos, tokens }); }).pipe(Effect.provide(KinGitHubScope.layer)); return program.pipe( Effect.catch(failed), diff --git a/apps/server/src/kin/github/rulesetsTest23.ts b/apps/server/src/kin/github/rulesetsTest23.ts new file mode 100644 index 000000000000..c81642c39075 --- /dev/null +++ b/apps/server/src/kin/github/rulesetsTest23.ts @@ -0,0 +1,504 @@ +// Security test 23's probes (approvals spec section 10), run by `kin-rulesets --test-23` on a +// scratch repository that already passes `--check`. rulesetsSetup.ts verifies the owner and the +// repository before calling this, and checks for drift again after it. +import type { RepoSlug } from "@t3tools/contracts"; +import * as Clock from "effect/Clock"; +import type * as Duration from "effect/Duration"; +import * as Effect from "effect/Effect"; +import type * as Redacted from "effect/Redacted"; +import * as Schema from "effect/Schema"; +import { HttpClient } from "effect/http"; + +import { + gitHubAnswer, + gitHubJson, + repoPath, + type GitHubAnswer, + type KinGitHubRequestError, +} from "./githubRest.ts"; +import { GITHUB_ACTIONS_INTEGRATION_ID, type KinRuleset } from "./KinRulesets.ts"; + +/** What a refused call must look like; anything else, success included, fails the probe. */ +export type KinBlock = + /** 403: the token lacks the permission. */ + | "forbidden" + /** 403 or 404. GitHub answers 404 to hide an endpoint the token can't use; nothing is written. */ + | "refused" + /** 422 "Repository rule violations found": a ruleset stopped a ref write. */ + | "rule_violation" + /** 405 naming a missing review: the merge was stopped by the pull request rule. */ + | "review_required"; + +/** Whether `answer` is the refusal `block` expects. Status alone can't tell a rule from a typo. */ +export function isKinBlock(answer: Pick, block: KinBlock) { + switch (block) { + case "forbidden": + return answer.status === 403; + case "refused": + return answer.status === 403 || answer.status === 404; + case "rule_violation": + return answer.status === 422 && /^Repository rule violations found/.test(answer.message); + case "review_required": + return ( + answer.status === 405 && + /approving review|code owner review|review is required/i.test(answer.message) + ); + } +} + +const describe = (answer: GitHubAnswer) => { + const message = answer.message.replace(/\s+/g, " ").trim().slice(0, 160); + return `HTTP ${answer.status}${message === "" ? "" : `: ${message}`}`; +}; + +const RefResponse = Schema.Struct({ + ref: Schema.String, + object: Schema.Struct({ sha: Schema.String }), +}); +const PullResponse = Schema.Struct({ + number: Schema.Int, + head: Schema.Struct({ sha: Schema.String }), + mergeable: Schema.optional(Schema.NullOr(Schema.Boolean)), + mergeable_state: Schema.optional(Schema.String), +}); +type PullState = typeof PullResponse.Type; +const CheckRuns = Schema.Struct({ + check_runs: Schema.Array( + Schema.Struct({ + name: Schema.String, + status: Schema.String, + conclusion: Schema.NullOr(Schema.String), + app: Schema.optional(Schema.NullOr(Schema.Struct({ id: Schema.Int }))), + }), + ), +}); +const Reviews = Schema.Array( + Schema.Struct({ + state: Schema.String, + commit_id: Schema.optional(Schema.NullOr(Schema.String)), + user: Schema.optional(Schema.NullOr(Schema.Struct({ login: Schema.String }))), + }), +); +const RulesetRead = Schema.Struct({ + bypass_actors: Schema.optional(Schema.Array(Schema.Unknown)), + current_user_can_bypass: Schema.optional(Schema.String), +}); +const CommitResponse = Schema.Struct({ commit: Schema.Struct({ sha: Schema.String }) }); +const decodeRef = Schema.decodeUnknownOption(RefResponse); +const decodePull = Schema.decodeUnknownOption(PullResponse); +const decodeRulesetRead = Schema.decodeUnknownOption(RulesetRead); +const decodeCommit = Schema.decodeUnknownOption(CommitResponse); + +interface Poll { + readonly every: Duration.Input; + readonly times: number; +} +// GitHub computes mergeability in the background; Actions runs take minutes. +const MERGEABLE_POLL: Poll = { every: "2 seconds", times: 30 }; +const CHECKS_POLL: Poll = { every: "10 seconds", times: 60 }; + +const poll = Effect.fn("kinRulesets.test23.poll")(function* ( + read: Effect.Effect, + done: (value: A) => boolean, + schedule: Poll, +) { + let last = yield* read; + for (let attempt = 1; !done(last) && attempt < schedule.times; attempt++) { + yield* Effect.sleep(schedule.every); + last = yield* read; + } + return last; +}); + +interface Step { + readonly pass: boolean; + readonly line: string; +} + +/** Ref paths keep their slashes: `tags/v1/rc`, not `tags%2Fv1%2Frc`. */ +const refPath = (ref: string) => ref.split("/").map(encodeURIComponent).join("/"); + +export const runTest23Probes = Effect.fn("kinRulesets.test23")(function* (input: { + readonly repo: RepoSlug; + readonly owner: string; + readonly defaultBranch: string; + readonly requiredChecks: ReadonlyArray; + /** The live ids of the desired rulesets, for the read and change probes. */ + readonly rulesets: ReadonlyArray<{ readonly id: number; readonly desired: KinRuleset }>; + readonly ownerToken: Redacted.Redacted; + readonly botToken: Redacted.Redacted; + readonly mergeToken: Redacted.Redacted; +}) { + const client = yield* HttpClient.HttpClient; + const path = repoPath(input.repo); + const tokens = [ + ["the bot", input.botToken], + ["the merge token", input.mergeToken], + ] as const; + const call = ( + operation: string, + method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE", + route: string, + token: Redacted.Redacted, + body?: unknown, + ) => gitHubAnswer({ client, operation, method, path: `${path}${route}`, token, body }); + const read = (operation: string, route: string, schema: S) => + gitHubJson({ + client, + operation, + method: "GET", + path: `${path}${route}`, + token: input.ownerToken, + schema, + }).pipe(Effect.map((response) => response.body)); + const refSha = (ref: string) => + call("git.getRef", "GET", `/git/ref/${refPath(ref)}`, input.ownerToken).pipe( + Effect.map((answer) => (answer.status === 200 ? decodeRef(answer.body) : undefined)), + Effect.map((ref) => (ref === undefined || ref._tag === "None" ? null : ref.value.object.sha)), + ); + + // Moving a tag needs one to exist, and the tag ruleset stops even the owner from making one. + const tags = yield* read( + "git.matchingTags", + "/git/matching-refs/tags/v", + Schema.Array(RefResponse), + ); + const releaseTag = tags.find((tag) => tag.ref.startsWith("refs/tags/v")); + if (releaseTag === undefined) { + return { + ok: false, + lines: [ + `Test 23 not run: ${input.repo} has no v* tag to try moving. Set kin-release to disabled, push a tag such as v0.0.0, then apply again.`, + ], + }; + } + const releaseRef = releaseTag.ref.slice("refs/".length); + + const stamp = yield* Clock.currentTimeMillis; + const branch = `kin-test-23-${stamp}`; + const newTag = `tags/v0.0.0-kin-test-23-${stamp}`; + const defaultRef = `heads/${input.defaultBranch}`; + const baseSha = (yield* read("git.getRef", `/git/ref/${refPath(defaultRef)}`, RefResponse)).object + .sha; + const created = yield* call("git.createRef", "POST", "/git/refs", input.botToken, { + ref: `refs/heads/${branch}`, + sha: baseSha, + }); + if (created.status !== 201) { + return { + ok: false, + lines: [`Test 23 not run: the bot couldn't create ${branch} (${describe(created)}).`], + }; + } + + const state = { + pull: undefined as number | undefined, + merged: false, + tagCreated: false, + tagMoved: false, + }; + const botCommit = Effect.fn("kinRulesets.test23.botCommit")(function* (file: string) { + const answer = yield* call( + "repos.createFile", + "PUT", + `/contents/kin-test-23/${file}`, + input.botToken, + { + message: "test: kin security test 23", + content: Buffer.from("Kin security test 23. Safe to delete.\n").toString("base64"), + branch, + }, + ); + const commit = decodeCommit(answer.body); + return answer.status === 201 && commit._tag === "Some" ? commit.value.commit.sha : null; + }); + + const run = Effect.gen(function* () { + const h1 = yield* botCommit(`${stamp}.md`); + if (h1 === null) return { ok: false, lines: ["FAIL the bot couldn't commit to its branch."] }; + const opened = yield* call("pulls.create", "POST", "/pulls", input.botToken, { + title: "Kin security test 23", + head: branch, + base: input.defaultBranch, + }); + const pull = decodePull(opened.body); + if (opened.status !== 201 || pull._tag === "None") { + return { ok: false, lines: [`FAIL the bot couldn't open a PR (${describe(opened)}).`] }; + } + const number = pull.value.number; + state.pull = number; + const pullRoute = `/pulls/${number}`; + const lines = [`Test 23 on ${input.repo}, PR #${number} by the bot at ${h1.slice(0, 7)}:`]; + + const checksPass = Effect.fn("kinRulesets.test23.checks")(function* (sha: string) { + const verdict = (runs: typeof CheckRuns.Type) => + input.requiredChecks.map((context) => { + const own = runs.check_runs.filter( + (run) => run.name === context && run.app?.id === GITHUB_ACTIONS_INTEGRATION_ID, + ); + if (own.some((run) => run.status === "completed" && run.conclusion === "success")) { + return "success" as const; + } + return own.length > 0 && own.every((run) => run.status === "completed") + ? ("failed" as const) + : ("pending" as const); + }); + const runs = yield* poll( + read("checks.list", `/commits/${sha}/check-runs?per_page=100`, CheckRuns), + (value) => !verdict(value).includes("pending"), + CHECKS_POLL, + ); + const result = verdict(runs); + return { + pass: result.every((value) => value === "success"), + line: `the required checks (${input.requiredChecks.join(", ")}) pass on ${sha.slice(0, 7)} from GitHub Actions (${result.join(", ")})`, + } satisfies Step; + }); + const reportedAs = Effect.fn("kinRulesets.test23.mergeableState")(function* ( + sha: string, + expected: "blocked" | "clean", + ) { + const computed = (pr: PullState) => + pr.head.sha === sha && pr.mergeable !== null && pr.mergeable !== undefined; + // Only `clean` is waited for: GitHub may lag a review, but a PR is never briefly clean early. + const pr = yield* poll( + read("pulls.get", pullRoute, PullResponse), + (value) => computed(value) && (expected === "blocked" || value.mergeable_state === "clean"), + MERGEABLE_POLL, + ); + return { + pass: computed(pr) && pr.mergeable_state === expected, + line: `GitHub reports the PR ${expected} at ${sha.slice(0, 7)} (mergeable_state ${pr.mergeable_state ?? "absent"})`, + } satisfies Step; + }); + const probe = Effect.fn("kinRulesets.test23.probe")(function* ( + name: string, + block: KinBlock, + request: Effect.Effect, + after?: Effect.Effect, + ) { + const answer = yield* request; + const blocked = isKinBlock(answer, block); + const problem = after === undefined ? null : yield* after; + return { + pass: blocked && problem === null, + line: `${name} (${describe(answer)})${problem === null ? "" : `; ${problem}`}`, + } satisfies Step; + }); + const approve = (sha: string): Effect.Effect => + call("pulls.createReview", "POST", `${pullRoute}/reviews`, input.ownerToken, { + event: "APPROVE", + commit_id: sha, + }).pipe( + Effect.map((answer) => ({ + pass: answer.status === 200, + line: `${input.owner} approves at ${sha.slice(0, 7)} (${describe(answer)})`, + })), + ); + const mergeAs = (token: Redacted.Redacted, sha: string) => + call("pulls.merge", "PUT", `${pullRoute}/merge`, token, { sha, merge_method: "squash" }); + const unmoved = (ref: string, sha: string | null) => + refSha(ref).pipe( + Effect.map((now) => { + if (now === sha) return null; + if (ref === newTag) state.tagCreated = true; + if (ref === releaseRef) state.tagMoved = true; + return `but ${ref} is now ${now ?? "missing"}`; + }), + ); + + const steps: Array> = [ + checksPass(h1), + reportedAs(h1, "blocked"), + probe( + "the merge token can't submit a review", + "forbidden", + call("pulls.createReview", "POST", `${pullRoute}/reviews`, input.mergeToken, { + event: "APPROVE", + commit_id: h1, + }), + ), + ...tokens.flatMap(([who, token]) => [ + probe( + `${who} can't merge without a code-owner review`, + "review_required", + mergeAs(token, h1), + ), + probe( + `${who} can't push to ${input.defaultBranch}`, + "rule_violation", + call("git.updateRef", "PATCH", `/git/refs/${refPath(defaultRef)}`, token, { + sha: h1, + force: false, + }), + unmoved(defaultRef, baseSha), + ), + probe( + `${who} can't create a v* tag`, + "rule_violation", + call("git.createRef", "POST", "/git/refs", token, { ref: `refs/${newTag}`, sha: h1 }), + unmoved(newTag, null), + ), + probe( + `${who} can't move ${releaseRef.slice("tags/".length)}`, + "rule_violation", + call("git.updateRef", "PATCH", `/git/refs/${refPath(releaseRef)}`, token, { + sha: h1, + force: true, + }), + unmoved(releaseRef, releaseTag.object.sha), + ), + ...input.rulesets.flatMap(({ id, desired }) => [ + // Reading a ruleset needs only Metadata, which every token has, so the read is allowed; + // what matters is that GitHub says this token can never bypass it. + call("repos.ruleset", "GET", `/rulesets/${id}`, token).pipe( + Effect.map((answer) => { + const body = decodeRulesetRead(answer.body); + const canBypass = + body._tag === "Some" + ? (body.value.current_user_can_bypass ?? "absent") + : "unreadable"; + const pass = + isKinBlock(answer, "refused") || + (answer.status === 200 && + canBypass === "never" && + body._tag === "Some" && + (body.value.bypass_actors ?? []).length === 0); + return { + pass, + line: `${who} can't bypass ${desired.name} (HTTP ${answer.status}, current_user_can_bypass ${canBypass})`, + }; + }), + ), + probe( + `${who} can't read ${desired.name}'s history`, + "refused", + call("repos.rulesetHistory", "GET", `/rulesets/${id}/history`, token), + ), + // The desired body, so even a wrongly accepted write changes nothing. + probe( + `${who} can't change ${desired.name}`, + "refused", + call("repos.updateRuleset", "PUT", `/rulesets/${id}`, token, desired), + ), + ]), + ]), + approve(h1), + reportedAs(h1, "clean"), + ]; + + const runSteps = Effect.fn("kinRulesets.test23.steps")(function* ( + list: ReadonlyArray>, + ) { + for (const step of list) { + const { pass, line } = yield* step; + lines.push(` ${pass ? "PASS" : "FAIL"} ${line}`); + if (!pass) return false; + } + return true; + }); + const stopped = () => ({ ok: false, lines: [...lines, "FAIL: stopped at the first failure."] }); + if (!(yield* runSteps(steps))) return stopped(); + + // Bait and switch: a push after the owner's approval must dismiss it. + const h2 = yield* botCommit(`${stamp}-after-review.md`); + lines.push( + ` ${h2 === null ? "FAIL" : "PASS"} the bot pushes ${h2?.slice(0, 7) ?? "nothing"} after the review`, + ); + if (h2 === null) return stopped(); + const dismissed: Effect.Effect = read( + "pulls.reviews", + `${pullRoute}/reviews?per_page=100`, + Reviews, + ).pipe( + Effect.map((reviews) => { + const review = reviews.find( + (one) => + one.commit_id === h1 && one.user?.login.toLowerCase() === input.owner.toLowerCase(), + ); + return { + pass: review?.state === "DISMISSED", + line: `the push dismissed ${input.owner}'s review (${review?.state ?? "no review found"})`, + }; + }), + ); + const merged = mergeAs(input.mergeToken, h2).pipe( + Effect.map((answer) => { + state.merged = answer.status === 200; + return { + pass: state.merged, + line: `after ${input.owner} approves the new head the merge token merges (${describe(answer)}), so the blocks came from the rules`, + }; + }), + ); + if ( + !(yield* runSteps([ + checksPass(h2), + reportedAs(h2, "blocked"), + dismissed, + probe( + "the merge token can't merge the switched head", + "review_required", + mergeAs(input.mergeToken, h2), + ), + approve(h2), + reportedAs(h2, "clean"), + merged, + ])) + ) { + return stopped(); + } + return { ok: true, lines }; + }); + + const cleanupLines: Array = []; + const attempt = ( + name: string, + request: Effect.Effect, + ok: ReadonlyArray, + ) => + request.pipe( + Effect.map((answer) => (ok.includes(answer.status) ? null : describe(answer))), + Effect.orElseSucceed(() => "GitHub unreachable"), + Effect.map((problem) => { + if (problem !== null) cleanupLines.push(` WARN cleanup: couldn't ${name} (${problem})`); + }), + ); + const cleanup = Effect.gen(function* () { + if (!state.merged && state.pull !== undefined) { + yield* attempt( + `close PR #${state.pull}`, + call("pulls.update", "PATCH", `/pulls/${state.pull}`, input.botToken, { state: "closed" }), + [200], + ); + } + // 422 when GitHub already deleted the merged branch. + yield* attempt( + `delete ${branch}`, + call("git.deleteRef", "DELETE", `/git/refs/${refPath(`heads/${branch}`)}`, input.botToken), + [204, 422], + ); + if (state.tagCreated) { + yield* attempt( + `delete ${newTag}`, + call("git.deleteRef", "DELETE", `/git/refs/${refPath(newTag)}`, input.ownerToken), + [204], + ); + } + if (state.tagMoved) { + yield* attempt( + `move ${releaseRef} back to ${releaseTag.object.sha.slice(0, 7)}`, + call("git.updateRef", "PATCH", `/git/refs/${refPath(releaseRef)}`, input.ownerToken, { + sha: releaseTag.object.sha, + force: true, + }), + [200], + ); + } + }); + const result = yield* run.pipe( + Effect.ensuring(cleanup), + Effect.tapError(() => Effect.logWarning("Test 23 cleanup", { lines: cleanupLines })), + ); + return { ok: result.ok, lines: [...result.lines, ...cleanupLines] }; +}); diff --git a/docs/kin/specs/approvals.md b/docs/kin/specs/approvals.md index 11c2a8ba3317..6ae011ea2ceb 100644 --- a/docs/kin/specs/approvals.md +++ b/docs/kin/specs/approvals.md @@ -386,9 +386,9 @@ These probes assume GitHub checks a fine-grained token's permission before it lo "required_approving_review_count": 1, "require_code_owner_review": true, "dismiss_stale_reviews_on_push": true, - "require_last_push_approval": true, + "require_last_push_approval": false, "required_review_thread_resolution": true, - "allowed_merge_methods": ["squash"] + "allowed_merge_methods": ["squash", "merge"] } }, { @@ -396,18 +396,31 @@ These probes assume GitHub checks a fine-grained token's permission before it lo "parameters": { "strict_required_status_checks_policy": true, "do_not_enforce_on_create": false, - "required_status_checks": [{ "context": "" }] + "required_status_checks": [{ "context": "", "integration_id": 15368 }] } } ] } ``` -- `bypass_actors` is empty, including repository admins. Otherwise the owner's merge token could skip review. +- `bypass_actors` is empty, including repository admins. Otherwise the owner's merge token could skip review. `--check` also requires `current_user_can_bypass: "never"`, and counts a ruleset whose bypass actors it can't see as drift. +- `integration_id` 15368 is the GitHub Actions App (`GET /apps/github-actions`), so a commit status posted with any token that has commit-status access can't stand in for CI. +- `require_last_push_approval` is off. Against the bot it adds nothing, since `dismiss_stale_reviews_on_push` already voids the owner's approval when the bot pushes. And it would deadlock an upstream sync branch the owner pushed, because the owner's approval can't count for their own last push. `merge` is allowed for those syncs (below); the executor squashes bot PRs. - `.github/CODEOWNERS` contains `* @GLDRoger`, so the bot's approval never counts, and a PR that changes CODEOWNERS needs the owner's review too. The check reads the copy on the default branch (the one GitHub uses for reviews into it) and GitHub's `codeowners/errors`, and requires a `*` rule with every rule naming exactly `@GLDRoger`, so no later rule hands a path to someone else or to no one. Without it, `require_code_owner_review` is met by anyone's approval, so apply refuses to change any ruleset until CODEOWNERS passes. -- A tag ruleset `kin-release` (`refs/tags/v*`) blocks tag creation, update and deletion, with no bypass, for when releases arrive. Update is included so a release tag can't be moved to another commit. +- A tag ruleset `kin-release` (`refs/tags/v*` and `refs/tags/v*/**`, since `*` stops at `/`) blocks tag creation, update (`update_allows_fetch_and_merge: false`) and deletion, with no bypass, for when releases arrive. Update is included so a release tag can't be moved to another commit. GitHub requires the `update` parameter; the test fake rejects rules missing any parameter the REST reference marks required. - The required check for `GLDRoger/t3code` is `Check`, the `ci.yml` job that fails unless every other job passed or was skipped as not needed. Other repos pass `--status-check`. -- The script takes the owner's own sign-in (`GH_TOKEN` or a hidden prompt) and refuses anything else before writing: an installation token (`ghs_`, refused before any request), a credential `GET /user` rejects or reports as a bot, a login other than the owner's, and a credential without admin on the repo (GitHub hides `bypass_actors` from those, so drift could go unseen). `--check` reports every drifted field, including any bypass actor, a rule someone added or removed, and changed parameters; parameters GitHub adds that the spec doesn't set are not compared. Apply creates or replaces each ruleset by name, writes nothing when it already matches, and re-reads to confirm no drift. +- The script reads `KinGitHubScope`. The owner is `KIN_GITHUB_OWNER_LOGIN`; `--owner` may name someone else only for a repository outside Kin, and is refused for `KIN_GITHUB_REPOS`, `GLDRoger/t3code` and `--test-23`. It takes the owner's own sign-in (`GH_TOKEN` or a hidden prompt) and refuses anything else before writing: an installation token (`ghs_`, refused before any request), a credential `GET /user` rejects or reports as a bot, a login other than the owner's, and a credential without admin on the repo (GitHub hides `bypass_actors` from those, so drift could go unseen). `--check` reports every drifted field, including any bypass actor, a rule someone added or removed, and changed parameters; parameters GitHub adds that the spec doesn't set are not compared. Apply creates or replaces each ruleset by name, writes nothing when it already matches, and re-reads to confirm no drift. + +**Upstream syncs (proposed resolution of open question 2, owner to confirm).** The bot can't carry a sync: an upstream merge changes `.github/workflows`, which its missing Workflows permission rejects, and squashing would flatten the merge so the next sync conflicts. So the owner carries it, and Kin only opens the PR: + +1. The owner merges upstream locally and pushes `sync/` with the merge commit, using their own credential, never the Kin host's. +2. The bot opens the PR from that branch (Pull requests: write only; it pushes nothing). +3. The owner approves as code owner. The approval counts because `require_last_push_approval` is off; the bot authored the PR, so it isn't the owner's own PR. +4. The owner merges in the GitHub UI with a merge commit, which `allowed_merge_methods` permits. +5. The executor keeps squashing bot PRs (`merge_method: "squash"`). +6. The merge token can't take this path: it has no Workflows permission, so GitHub refuses it a merge that changes workflows. + +Cost: `merge` is allowed for every PR into the default branch, so a code-owner-approved bot PR could be merge-committed by hand. That changes history shape, not who may merge. ### 11. Audit @@ -538,7 +551,7 @@ RPCs and scopes: `kin.approvals.list` (stream) and `get` → `orchestration:read 20. `the audit chain detects an edited row` (`kin.audit.verify`). 21. `the first approver key can't be confirmed from a remote session`. 22. Mobile (`apps/mobile/modules/kin-approval-key`, device test): `signing without biometrics fails`, `re-enrolling biometrics invalidates the key`, `DER signatures convert to compact and verify on the server`. -23. GitHub (`scripts/kin-rulesets.ts --test-23`, run against a scratch repo after `--check` passes there): the bot opens a PR, the owner posts success statuses for the required checks, then `the owner merge token can't submit a review` (expect 403), `the bot can't merge to main` (and can't push to it), and `a merge without a code-owner review is blocked`. A last step has the owner approve and the merge token merge, which shows the blocks came from the review rule rather than something else. After the owner's review at the current head, the bot's `contents: write` token could merge too: the ruleset doesn't limit who merges (threat model, open question 7). The logic is tested against a fake GitHub in `apps/server/src/kin/github/rulesetsSetup.test.ts`. +23. GitHub (`scripts/kin-rulesets.ts --test-23 --repo /`, after `--check` passes there): it refuses a Kin repository (`KIN_GITHUB_REPOS` or `GLDRoger/t3code`, in any case), a name without `scratch`, and a repository whose `GET /repos` `full_name` differs from `--repo` (a rename or transfer redirect). It needs a `v*` tag on the scratch repo and an Actions workflow that runs the required checks on pull requests. It takes a scratch-only fine-grained token of the owner's, checked by `OwnerMergeClient.save`'s probes and not stored, and mints a `worker` App token, which it revokes at the end. The bot opens a PR; once the Actions checks pass and GitHub reports `mergeable_state: "blocked"`: `the merge token can't submit a review` (403); for both the bot and the merge token, `can't merge without a code-owner review` (405 naming the review), `can't push to the default branch` (422 "Repository rule violations", and the ref hasn't moved), `can't create or move a v* tag` (same), `can't bypass either ruleset` (reading one needs only Metadata, so the read may succeed, but must report `current_user_can_bypass: "never"` and no bypass actors), and `can't read a ruleset's history or change a ruleset` (403, or 404, which GitHub uses to hide endpoints a token can't use; the change sends the desired body, and drift is checked again afterwards). The owner approves and GitHub reports `clean`. Then bait and switch: the bot pushes, the owner's review shows `DISMISSED`, and the merge token's merge of the new head is blocked. The owner approves again and the merge token merges, which shows the blocks came from the rules. After the owner's review at the current head, the bot's `contents: write` token could merge too: the ruleset doesn't limit who merges (threat model, open question 7); test 23 doesn't merge with it. The logic is tested against a fake GitHub in `apps/server/src/kin/github/rulesetsSetup.test.ts`; GitHub's exact refusal messages are assumed there and confirmed by the first real run. Acceptance for phase 1: on `GLDRoger/t3code`, the lead requests a merge of a bot PR; the owner approves on the phone with Face ID; the GitHub review lands from the phone; the executor merges with the pinned SHA; the audit lists grant, device, SHA, provenance and merge commit. Tests 1–21 pass in CI; 22–23 pass on the release checklist. @@ -589,7 +602,7 @@ Later, marked by phase: ## Open questions 1. The phone needs a GitHub user token for the Kin App (device flow, once). Is that acceptable, or should phase 1 start with "Approve on GitHub" only and add the phone token later? -2. Owner-written PRs under an empty bypass list: route them through the bot, or add a time-boxed bypass toggled by an owner-signed action? Upstream syncs make this urgent: once `kin-main` is on `GLDRoger/t3code`, `KIN.md`'s `git push origin main kin` is rejected, a sync PR the owner opens has no code owner left to approve it, the bot can't open one because upstream merges change `.github/workflows` (no Workflows permission), and squash-only would flatten the upstream merge so the next sync conflicts. Decide before applying the ruleset there; one option is `allowed_merge_methods: ["squash", "merge"]` plus a second code owner for sync PRs. +2. Owner-written PRs under an empty bypass list: route them through the bot, or add a time-boxed bypass toggled by an owner-signed action? Upstream syncs make this urgent: once `kin-main` is on `GLDRoger/t3code`, `KIN.md`'s `git push origin main kin` is rejected, a sync PR the owner opens has no code owner left to approve it, the bot can't open one because upstream merges change `.github/workflows` (no Workflows permission), and squash-only would flatten the upstream merge so the next sync conflicts. Decide before applying the ruleset there; one option is `allowed_merge_methods: ["squash", "merge"]` plus a second code owner for sync PRs. **Proposed resolution, owner to confirm:** the sync flow in section 10, where the owner pushes `sync/`, the bot opens the PR, and the owner approves and merge-commits it. This needs `require_last_push_approval` off and `merge` allowed, as `kinRulesets` now has. 3. Merge-queue repos: support `enablePullRequestAutoMerge` with `expectedHeadOid` later, or keep refusing? 4. Should the executor run as a separate OS user with its own keychain, so code running as the Kin server's user can't read the merge token at all? Phase 1 relies on the token being unable to review. 5. Desktop approvals: a Touch ID-gated Secure Enclave key on macOS through a native addon, or phone-only for good? From 976e2810a4fa99b62bf7c3a872385cd8ffedcb0f Mon Sep 17 00:00:00 2001 From: Surajsm60720 <1ds22is166@dsce.edu.in> Date: Sun, 8 Nov 2026 08:53:29 +0530 Subject: [PATCH 4/5] fix(kin): test 23 treats rate limits as try-again and takes --probe-pr (APPR-11) Test 23's probes now read headers and use APPR-8's rate-limit rule, shared from githubRest.ts, so a 429 or rate-limit 403 stops the run as "try again later" instead of counting as a block. --probe-pr passes through to OwnerMergeClient.save's review probe on the scratch token. Co-Authored-By: Claude Opus 5.5 --- .../server/src/kin/github/OwnerMergeClient.ts | 9 +-- apps/server/src/kin/github/githubRest.ts | 18 +++++- .../src/kin/github/rulesetsSetup.test.ts | 39 ++++++++++++- apps/server/src/kin/github/rulesetsSetup.ts | 13 ++++- apps/server/src/kin/github/rulesetsTest23.ts | 58 ++++++++++++++++--- 5 files changed, 119 insertions(+), 18 deletions(-) diff --git a/apps/server/src/kin/github/OwnerMergeClient.ts b/apps/server/src/kin/github/OwnerMergeClient.ts index be5ffa8e3713..daf352958aae 100644 --- a/apps/server/src/kin/github/OwnerMergeClient.ts +++ b/apps/server/src/kin/github/OwnerMergeClient.ts @@ -14,6 +14,7 @@ import { CredentialHygienePass } from "../approvals/CredentialHygiene.ts"; import { gitHubJson, gitHubStatus, + isGitHubRateLimit, type GitHubStatusResponse, type KinGitHubRequestError, } from "./githubRest.ts"; @@ -62,15 +63,9 @@ const RepoInfo = Schema.Struct({ function classifyProbe( answer: GitHubStatusResponse, ): "denied" | "rate_limited" | "inconclusive" | "allowed" { - if (answer.status === 429) return "rate_limited"; + if (isGitHubRateLimit(answer)) return "rate_limited"; if (answer.status === 404) return "inconclusive"; if (answer.status !== 403) return "allowed"; - if ( - answer.headers["x-ratelimit-remaining"] === "0" || - answer.headers["retry-after"] !== undefined - ) { - return "rate_limited"; - } return answer.message?.trim() === NOT_ACCESSIBLE_MESSAGE ? "denied" : "allowed"; } diff --git a/apps/server/src/kin/github/githubRest.ts b/apps/server/src/kin/github/githubRest.ts index b9e5e8ca6361..2bdbb1b0c716 100644 --- a/apps/server/src/kin/github/githubRest.ts +++ b/apps/server/src/kin/github/githubRest.ts @@ -127,6 +127,16 @@ export const gitHubStatus = Effect.fn("KinGitHub.status")(function* (input: { } satisfies GitHubStatusResponse; }); +/** + * GitHub's rate limits: 429, or a 403 that says so in its headers. A rate-limited refusal says + * nothing about the token's permissions. + */ +export const isGitHubRateLimit = (answer: Pick) => + answer.status === 429 || + (answer.status === 403 && + (answer.headers["x-ratelimit-remaining"] === "0" || + answer.headers["retry-after"] !== undefined)); + /** `/repos/{owner}/{name}` for an `owner/name` slug. */ export const repoPath = (repo: string) => { const [owner = "", name = ""] = repo.split("/"); @@ -135,6 +145,7 @@ export const repoPath = (repo: string) => { export interface GitHubAnswer { readonly status: number; + readonly headers: Readonly>; /** GitHub's `message`, or "" when the body has none. Error messages carry no credential. */ readonly message: string; readonly body: unknown; @@ -164,5 +175,10 @@ export const gitHubAnswer = Effect.fn("KinGitHub.answer")(function* (input: { typeof body.message === "string" ? body.message : ""; - return { status: response.status, message, body } satisfies GitHubAnswer; + return { + status: response.status, + headers: response.headers, + message, + body, + } satisfies GitHubAnswer; }); diff --git a/apps/server/src/kin/github/rulesetsSetup.test.ts b/apps/server/src/kin/github/rulesetsSetup.test.ts index e8aa7b31cf68..2db7e54699ab 100644 --- a/apps/server/src/kin/github/rulesetsSetup.test.ts +++ b/apps/server/src/kin/github/rulesetsSetup.test.ts @@ -432,6 +432,9 @@ const ruleViolation = (rule: string) => ({ status: "422", }); +const NOT_ACCESSIBLE = { message: "Resource not accessible by personal access token" }; +const RETRY = { "retry-after": "60" }; + describe("test 23 refusal matching", () => { it.each([ [422, ruleViolation("Changes must be made through a pull request."), "rule_violation", true], @@ -462,7 +465,19 @@ describe("test 23 refusal matching", () => { [404, { message: "Not Found" }, "refused", true], [200, { message: "" }, "refused", false], ] as const)("HTTP %i %j as %s is %s", (status, body, block, expected) => { - assert.strictEqual(isKinBlock({ status, message: body.message }, block as KinBlock), expected); + assert.strictEqual( + isKinBlock({ status, headers: {}, message: body.message }, block as KinBlock), + expected, + ); + }); + + // A rate limit means "try again later", whatever the body says. + it.each([ + [403, NOT_ACCESSIBLE, { "x-ratelimit-remaining": "0" }, "forbidden"], + [403, { message: "You have exceeded a secondary rate limit." }, RETRY, "refused"], + [429, { message: "" }, {}, "refused"], + ] as const)("HTTP %i %j with %j is never %s", (status, body, headers, block) => { + assert.isFalse(isKinBlock({ status, headers, message: body.message }, block as KinBlock)); }); }); @@ -475,6 +490,8 @@ const sha = (char: string) => char.repeat(40); const scratchRepo = ( broken: { readonly mergeTokenCanReview?: boolean; + /** GitHub rate-limits the merge token's review attempt with a 403 it would also use to refuse. */ + readonly rateLimitReview?: boolean; readonly botCanMerge?: boolean; readonly pushAllowed?: boolean; readonly tagMovable?: boolean; @@ -580,6 +597,9 @@ const scratchRepo = ( }, }; case `POST ${base}/pulls/7/reviews`: + if (token === MERGE_TOKEN && broken.rateLimitReview) { + return { status: 403, body: NOT_ACCESSIBLE, headers: { "x-ratelimit-remaining": "0" } }; + } if (token === OWNER_TOKEN || broken.mergeTokenCanReview) { reviews.push({ state: "APPROVED", @@ -689,6 +709,23 @@ describe("security test 23 (kin-rulesets --test-23)", () => { }).pipe(Effect.provide(github.layer)); }); + it.effect("stops on a rate limit without counting it as a block, and cleans up", () => { + const github = scratchRepo({ rateLimitReview: true }); + return Effect.gen(function* () { + const result = yield* test23(); + assert.isFalse(result.ok); + assert.include( + result.lines, + " WAIT the merge token can't submit a review (HTTP 403: Resource not accessible by personal access token): GitHub rate-limited this call, so it proves nothing", + ); + assert.include(result.lines.at(-1), "try again later"); + assert.isFalse(result.lines.some((line) => line.startsWith(" FAIL"))); + assert.isTrue(github.state.closed); + assert.isTrue(github.state.revoked); + assert.isFalse(github.refs.has("heads/kin-test-23-0")); + }).pipe(Effect.provide(github.layer)); + }); + it.effect("doesn't run, or take tokens, until the scratch repo has no drift", () => { const github = scratchRepo(); return Effect.gen(function* () { diff --git a/apps/server/src/kin/github/rulesetsSetup.ts b/apps/server/src/kin/github/rulesetsSetup.ts index 577e684ef0c7..2ea2712d516b 100644 --- a/apps/server/src/kin/github/rulesetsSetup.ts +++ b/apps/server/src/kin/github/rulesetsSetup.ts @@ -432,7 +432,11 @@ export const runTest23 = Effect.fn("kinRulesets.test23Run")(function* (inp ...revokeLines, after.ok ? " PASS the rulesets show no drift afterwards" : " FAIL the rulesets drifted:", ...(after.ok ? [] : after.lines), - ok ? "PASS: security test 23." : "FAIL: see above.", + ok + ? "PASS: security test 23." + : probes.rateLimited + ? "NOT DONE: GitHub rate-limited test 23, which proves nothing either way; try again later." + : "FAIL: see above.", ], } satisfies RulesetsResult; }); @@ -507,6 +511,12 @@ export const kinRulesetsCommand = Command.make( Flag.withDescription("For --test-23: the bot App id; defaults to KIN_GITHUB_APP_ID."), Flag.optional, ), + probePr: Flag.Int("probe-pr").pipe( + Flag.withDescription( + "For --test-23: an existing PR on the scratch repo for the merge token's review probe; defaults to #1.", + ), + Flag.optional, + ), }, (input) => { const program = Effect.gen(function* () { @@ -555,6 +565,7 @@ export const kinRulesetsCommand = Command.make( yield* (yield* OwnerMergeClient.OwnerMergeClient).save({ orgId: TEST_23_ORG, token: mergeToken, + probePr: Option.getOrUndefined(input.probePr), }); const bot = yield* (yield* KinGitHubApp.KinGitHubApp).installationToken({ repo, diff --git a/apps/server/src/kin/github/rulesetsTest23.ts b/apps/server/src/kin/github/rulesetsTest23.ts index c81642c39075..142e5c167f9e 100644 --- a/apps/server/src/kin/github/rulesetsTest23.ts +++ b/apps/server/src/kin/github/rulesetsTest23.ts @@ -12,6 +12,7 @@ import { HttpClient } from "effect/http"; import { gitHubAnswer, gitHubJson, + isGitHubRateLimit, repoPath, type GitHubAnswer, type KinGitHubRequestError, @@ -29,8 +30,15 @@ export type KinBlock = /** 405 naming a missing review: the merge was stopped by the pull request rule. */ | "review_required"; -/** Whether `answer` is the refusal `block` expects. Status alone can't tell a rule from a typo. */ -export function isKinBlock(answer: Pick, block: KinBlock) { +/** + * Whether `answer` is the refusal `block` expects. Status alone can't tell a rule from a typo, and + * a rate limit is never a block: it says nothing about the token or the rules. + */ +export function isKinBlock( + answer: Pick, + block: KinBlock, +) { + if (isGitHubRateLimit(answer)) return false; switch (block) { case "forbidden": return answer.status === 403; @@ -113,6 +121,8 @@ const poll = Effect.fn("kinRulesets.test23.poll")(function* ( interface Step { readonly pass: boolean; readonly line: string; + /** GitHub rate-limited the call, so the step proves nothing either way. */ + readonly rateLimited?: boolean; } /** Ref paths keep their slashes: `tags/v1/rc`, not `tags%2Fv1%2Frc`. */ @@ -167,6 +177,7 @@ export const runTest23Probes = Effect.fn("kinRulesets.test23")(function* (input: if (releaseTag === undefined) { return { ok: false, + rateLimited: false, lines: [ `Test 23 not run: ${input.repo} has no v* tag to try moving. Set kin-release to disabled, push a tag such as v0.0.0, then apply again.`, ], @@ -187,6 +198,7 @@ export const runTest23Probes = Effect.fn("kinRulesets.test23")(function* (input: if (created.status !== 201) { return { ok: false, + rateLimited: false, lines: [`Test 23 not run: the bot couldn't create ${branch} (${describe(created)}).`], }; } @@ -215,7 +227,12 @@ export const runTest23Probes = Effect.fn("kinRulesets.test23")(function* (input: const run = Effect.gen(function* () { const h1 = yield* botCommit(`${stamp}.md`); - if (h1 === null) return { ok: false, lines: ["FAIL the bot couldn't commit to its branch."] }; + if (h1 === null) + return { + ok: false, + rateLimited: false, + lines: ["FAIL the bot couldn't commit to its branch."], + }; const opened = yield* call("pulls.create", "POST", "/pulls", input.botToken, { title: "Kin security test 23", head: branch, @@ -223,7 +240,11 @@ export const runTest23Probes = Effect.fn("kinRulesets.test23")(function* (input: }); const pull = decodePull(opened.body); if (opened.status !== 201 || pull._tag === "None") { - return { ok: false, lines: [`FAIL the bot couldn't open a PR (${describe(opened)}).`] }; + return { + ok: false, + rateLimited: false, + lines: [`FAIL the bot couldn't open a PR (${describe(opened)}).`], + }; } const number = pull.value.number; state.pull = number; @@ -283,6 +304,7 @@ export const runTest23Probes = Effect.fn("kinRulesets.test23")(function* (input: return { pass: blocked && problem === null, line: `${name} (${describe(answer)})${problem === null ? "" : `; ${problem}`}`, + rateLimited: isGitHubRateLimit(answer), } satisfies Step; }); const approve = (sha: string): Effect.Effect => @@ -293,6 +315,7 @@ export const runTest23Probes = Effect.fn("kinRulesets.test23")(function* (input: Effect.map((answer) => ({ pass: answer.status === 200, line: `${input.owner} approves at ${sha.slice(0, 7)} (${describe(answer)})`, + rateLimited: isGitHubRateLimit(answer), })), ); const mergeAs = (token: Redacted.Redacted, sha: string) => @@ -367,6 +390,7 @@ export const runTest23Probes = Effect.fn("kinRulesets.test23")(function* (input: return { pass, line: `${who} can't bypass ${desired.name} (HTTP ${answer.status}, current_user_can_bypass ${canBypass})`, + rateLimited: isGitHubRateLimit(answer), }; }), ), @@ -387,17 +411,30 @@ export const runTest23Probes = Effect.fn("kinRulesets.test23")(function* (input: reportedAs(h1, "clean"), ]; + let limited = false; const runSteps = Effect.fn("kinRulesets.test23.steps")(function* ( list: ReadonlyArray>, ) { for (const step of list) { - const { pass, line } = yield* step; + const { pass, line, rateLimited } = yield* step; + if (rateLimited) { + lines.push(` WAIT ${line}: GitHub rate-limited this call, so it proves nothing`); + limited = true; + return false; + } lines.push(` ${pass ? "PASS" : "FAIL"} ${line}`); if (!pass) return false; } return true; }); - const stopped = () => ({ ok: false, lines: [...lines, "FAIL: stopped at the first failure."] }); + const stopped = () => ({ + ok: false, + rateLimited: limited, + lines: [ + ...lines, + limited ? "Stopped at the rate limit." : "FAIL: stopped at the first failure.", + ], + }); if (!(yield* runSteps(steps))) return stopped(); // Bait and switch: a push after the owner's approval must dismiss it. @@ -428,6 +465,7 @@ export const runTest23Probes = Effect.fn("kinRulesets.test23")(function* (input: return { pass: state.merged, line: `after ${input.owner} approves the new head the merge token merges (${describe(answer)}), so the blocks came from the rules`, + rateLimited: isGitHubRateLimit(answer), }; }), ); @@ -448,7 +486,7 @@ export const runTest23Probes = Effect.fn("kinRulesets.test23")(function* (input: ) { return stopped(); } - return { ok: true, lines }; + return { ok: true, rateLimited: false, lines }; }); const cleanupLines: Array = []; @@ -500,5 +538,9 @@ export const runTest23Probes = Effect.fn("kinRulesets.test23")(function* (input: Effect.ensuring(cleanup), Effect.tapError(() => Effect.logWarning("Test 23 cleanup", { lines: cleanupLines })), ); - return { ok: result.ok, lines: [...result.lines, ...cleanupLines] }; + return { + ok: result.ok, + rateLimited: result.rateLimited, + lines: [...result.lines, ...cleanupLines], + }; }); From 86ecc29c9bc684b0b156c1854753d614d0c52122 Mon Sep 17 00:00:00 2001 From: Surajsm60720 <1ds22is166@dsce.edu.in> Date: Sun, 8 Nov 2026 09:25:29 +0530 Subject: [PATCH 5/5] fix(kin): require last-push approval and harden test 23 cleanup (APPR-11) Stale dismissal skips diff-neutral pushes, so a bot add-then-revert kept the owner's approval and could land an unreviewed commit via a merge commit. require_last_push_approval is back on; the upstream sync flow now ends with a bot same-tree commit so the owner's approval still counts. Test 23: a ref read is "missing" only on 404, writes the rules should refuse are recorded as soon as GitHub accepts them, "forbidden" needs GitHub's exact fine-grained-token message (shared with OwnerMergeClient), and cleanup prints manual steps for refs the rulesets stop it from restoring. Co-Authored-By: Claude Opus 5.5 --- apps/server/src/kin/github/KinRulesets.ts | 6 +- .../server/src/kin/github/OwnerMergeClient.ts | 5 +- apps/server/src/kin/github/githubRest.ts | 6 ++ .../src/kin/github/rulesetsSetup.test.ts | 61 +++++++++++-- apps/server/src/kin/github/rulesetsTest23.ts | 89 +++++++++++++++---- docs/kin/specs/approvals.md | 19 ++-- 6 files changed, 148 insertions(+), 38 deletions(-) diff --git a/apps/server/src/kin/github/KinRulesets.ts b/apps/server/src/kin/github/KinRulesets.ts index 7fb32bd295c8..c11c0e439a4a 100644 --- a/apps/server/src/kin/github/KinRulesets.ts +++ b/apps/server/src/kin/github/KinRulesets.ts @@ -52,9 +52,9 @@ export const kinRulesets = (requiredChecks: ReadonlyArray): ReadonlyArra required_approving_review_count: 1, require_code_owner_review: true, dismiss_stale_reviews_on_push: true, - // Off: it adds nothing against the bot, whose pushes the owner must approve anyway, and - // it deadlocks an upstream sync branch the owner pushed (spec section 10). - require_last_push_approval: false, + // Stale dismissal ignores diff-neutral pushes, so a bot commit added then reverted would + // keep the owner's approval. Upstream syncs end with a bot push for this (spec section 10). + require_last_push_approval: true, required_review_thread_resolution: true, // `merge` is for the owner's upstream syncs; the executor squashes bot PRs. allowed_merge_methods: ["squash", "merge"], diff --git a/apps/server/src/kin/github/OwnerMergeClient.ts b/apps/server/src/kin/github/OwnerMergeClient.ts index daf352958aae..2c527d9c9455 100644 --- a/apps/server/src/kin/github/OwnerMergeClient.ts +++ b/apps/server/src/kin/github/OwnerMergeClient.ts @@ -12,6 +12,7 @@ import { HttpClient } from "effect/http"; // inside effects, after both modules have loaded. import { CredentialHygienePass } from "../approvals/CredentialHygiene.ts"; import { + GITHUB_PAT_NOT_ACCESSIBLE, gitHubJson, gitHubStatus, isGitHubRateLimit, @@ -34,8 +35,6 @@ const PASS_MAX_AGE_MS = 60 * 1000; * when the token could review, so the probe can never create a review. */ const DEFAULT_REVIEW_PROBE_PR = 1; -/** What GitHub says when a fine-grained token lacks the permission an endpoint needs. */ -const NOT_ACCESSIBLE_MESSAGE = "Resource not accessible by personal access token"; const REVIEW_PROBE_BODY = { event: "KIN_PERMISSION_PROBE", commit_id: "0000000000000000000000000000000000000000", @@ -66,7 +65,7 @@ function classifyProbe( if (isGitHubRateLimit(answer)) return "rate_limited"; if (answer.status === 404) return "inconclusive"; if (answer.status !== 403) return "allowed"; - return answer.message?.trim() === NOT_ACCESSIBLE_MESSAGE ? "denied" : "allowed"; + return answer.message?.trim() === GITHUB_PAT_NOT_ACCESSIBLE ? "denied" : "allowed"; } export class OwnerMergeTokenRefusedError extends Schema.TaggedError()( diff --git a/apps/server/src/kin/github/githubRest.ts b/apps/server/src/kin/github/githubRest.ts index 34562fc5c40a..12c87bf6a0cf 100644 --- a/apps/server/src/kin/github/githubRest.ts +++ b/apps/server/src/kin/github/githubRest.ts @@ -143,6 +143,12 @@ export const isGitHubRateLimit = ( // GitHub's secondary limit can come with neither header. (answer.message?.toLowerCase().includes("secondary rate limit") ?? false))); +/** + * GitHub's 403 message when a fine-grained token lacks the permission an endpoint needs. An App + * installation token gets "Resource not accessible by integration" instead. + */ +export const GITHUB_PAT_NOT_ACCESSIBLE = "Resource not accessible by personal access token"; + /** `/repos/{owner}/{name}` for an `owner/name` slug. */ export const repoPath = (repo: string) => { const [owner = "", name = ""] = repo.split("/"); diff --git a/apps/server/src/kin/github/rulesetsSetup.test.ts b/apps/server/src/kin/github/rulesetsSetup.test.ts index 2db7e54699ab..7d8426c62d3e 100644 --- a/apps/server/src/kin/github/rulesetsSetup.test.ts +++ b/apps/server/src/kin/github/rulesetsSetup.test.ts @@ -281,6 +281,13 @@ describe("kin-rulesets --check", () => { }, " FAIL rules.pull_request.require_code_owner_review: expected true, got false", ], + [ + "last-push approval switched off", + (rulesets: Array) => { + ruleParameters(rulesets, "pull_request").require_last_push_approval = false; + }, + " FAIL rules.pull_request.require_last_push_approval: expected true, got false", + ], [ "rebase merges allowed", (rulesets: Array) => { @@ -460,7 +467,18 @@ describe("test 23 refusal matching", () => { "review_required", false, ], - [403, { message: "Resource not accessible by personal access token" }, "forbidden", true], + [403, NOT_ACCESSIBLE, "forbidden", true], + [403, { message: "Resource not accessible by integration" }, "forbidden", false], + [ + 403, + { + message: + "Resource protected by organization SAML enforcement. You must grant your Personal Access token access to this organization.", + }, + "forbidden", + false, + ], + [403, { message: "Must have admin rights to Repository." }, "forbidden", false], [404, { message: "Not Found" }, "forbidden", false], [404, { message: "Not Found" }, "refused", true], [200, { message: "" }, "refused", false], @@ -495,6 +513,9 @@ const scratchRepo = ( readonly botCanMerge?: boolean; readonly pushAllowed?: boolean; readonly tagMovable?: boolean; + readonly tagCreatable?: boolean; + /** Reading back the tag the probe tried to create is rate-limited. */ + readonly rateLimitTagRead?: boolean; readonly noStaleDismissal?: boolean; readonly anyoneCanAdminister?: boolean; readonly noReleaseTag?: boolean; @@ -527,6 +548,9 @@ const scratchRepo = ( } const ref = request.path.match(new RegExp(`^${base}/git/refs?/(.+)$`))?.[1]; if (request.method === "GET" && ref !== undefined && request.path.includes("/git/ref/")) { + if (broken.rateLimitTagRead && ref.startsWith("tags/v0.0.0-kin-test-23")) { + return { status: 429, body: { message: "API rate limit exceeded" } }; + } const at = refs.get(ref); return at === undefined ? { status: 404, body: { message: "Not Found" } } @@ -542,7 +566,7 @@ const scratchRepo = ( } if (route === `POST ${base}/git/refs`) { const name = body!.ref!.slice("refs/".length); - if (name.startsWith("tags/v")) { + if (name.startsWith("tags/v") && !broken.tagCreatable) { return violation("Cannot create ref due to creations being restricted."); } refs.set(name, body!.sha!); @@ -608,10 +632,7 @@ const scratchRepo = ( }); return { status: 200, body: {} }; } - return { - status: 403, - body: { message: "Resource not accessible by personal access token" }, - }; + return { status: 403, body: NOT_ACCESSIBLE }; case `GET ${base}/pulls/7/reviews?per_page=100`: return { status: 200, body: reviews }; case `PUT ${base}/pulls/7/merge`: @@ -633,6 +654,8 @@ const scratchRepo = ( return { ...github, refs, state }; }; +const scratchBroken = { pushAllowed: { pushAllowed: true } } as const; + const tokens = Effect.succeed({ botToken: Redacted.make(BOT_TOKEN), mergeToken: Redacted.make(MERGE_TOKEN), @@ -686,7 +709,7 @@ describe("security test 23 (kin-rulesets --test-23)", () => { it.effect.each([ ["a merge token that can review", { mergeTokenCanReview: true }, "can't submit a review"], ["a bot that can merge alone", { botCanMerge: true }, "the bot can't merge"], - ["a push to the default branch", { pushAllowed: true }, "but heads/kin is now"], + ["a push to the default branch", scratchBroken.pushAllowed, "but heads/kin is now"], ["a movable release tag", { tagMovable: true }, "but tags/v1.0.0 is now"], ["no stale-review dismissal", { noStaleDismissal: true }, "dismissed GLDRoger's review"], [ @@ -706,6 +729,30 @@ describe("security test 23 (kin-rulesets --test-23)", () => { assert.isFalse(github.refs.has("tags/v0.0.0-kin-test-23-0")); assert.strictEqual(github.refs.get("tags/v1.0.0"), sha("7")); if (!github.state.merged) assert.isTrue(github.state.closed); + if (broken === scratchBroken.pushAllowed) { + assert.include( + result.lines, + " WARN cleanup: undo by hand: kin moved to bbbbbbb; disable kin-main, then `git push --force origin aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:refs/heads/kin`, then apply kin-rulesets to GLDRoger/kin-scratch again.", + ); + } + }).pipe(Effect.provide(github.layer)); + }); + + it.effect("deletes a tag it created even when reading it back fails", () => { + const github = scratchRepo({ tagCreatable: true, rateLimitTagRead: true }); + return Effect.gen(function* () { + const error = yield* Effect.flip(test23()); + assert.strictEqual(error._tag, "KinGitHubRequestError"); + assert.isTrue( + github.requests.some( + (request) => + request.method === "DELETE" && + request.path === "/repos/GLDRoger/kin-scratch/git/refs/tags/v0.0.0-kin-test-23-0", + ), + ); + assert.isFalse(github.refs.has("tags/v0.0.0-kin-test-23-0")); + assert.isTrue(github.state.closed); + assert.isTrue(github.state.revoked); }).pipe(Effect.provide(github.layer)); }); diff --git a/apps/server/src/kin/github/rulesetsTest23.ts b/apps/server/src/kin/github/rulesetsTest23.ts index 142e5c167f9e..d34c88406542 100644 --- a/apps/server/src/kin/github/rulesetsTest23.ts +++ b/apps/server/src/kin/github/rulesetsTest23.ts @@ -5,23 +5,28 @@ import type { RepoSlug } from "@t3tools/contracts"; import * as Clock from "effect/Clock"; import type * as Duration from "effect/Duration"; import * as Effect from "effect/Effect"; +import * as Option from "effect/Option"; import type * as Redacted from "effect/Redacted"; import * as Schema from "effect/Schema"; import { HttpClient } from "effect/http"; import { + GITHUB_PAT_NOT_ACCESSIBLE, gitHubAnswer, gitHubJson, isGitHubRateLimit, + KinGitHubRequestError, repoPath, type GitHubAnswer, - type KinGitHubRequestError, } from "./githubRest.ts"; import { GITHUB_ACTIONS_INTEGRATION_ID, type KinRuleset } from "./KinRulesets.ts"; /** What a refused call must look like; anything else, success included, fails the probe. */ export type KinBlock = - /** 403: the token lacks the permission. */ + /** + * 403 with GitHub's missing-permission message for a fine-grained token, the only kind it's used + * for (the merge token). A 403 for SAML, an IP allow list or a block isn't the permission. + */ | "forbidden" /** 403 or 404. GitHub answers 404 to hide an endpoint the token can't use; nothing is written. */ | "refused" @@ -41,7 +46,7 @@ export function isKinBlock( if (isGitHubRateLimit(answer)) return false; switch (block) { case "forbidden": - return answer.status === 403; + return answer.status === 403 && answer.message.trim() === GITHUB_PAT_NOT_ACCESSIBLE; case "refused": return answer.status === 403 || answer.status === 404; case "rule_violation": @@ -161,10 +166,24 @@ export const runTest23Probes = Effect.fn("kinRulesets.test23")(function* (input: token: input.ownerToken, schema, }).pipe(Effect.map((response) => response.body)); + /** `null` only for a 404: any other failed read can't show the ref is missing. */ const refSha = (ref: string) => call("git.getRef", "GET", `/git/ref/${refPath(ref)}`, input.ownerToken).pipe( - Effect.map((answer) => (answer.status === 200 ? decodeRef(answer.body) : undefined)), - Effect.map((ref) => (ref === undefined || ref._tag === "None" ? null : ref.value.object.sha)), + Effect.flatMap((answer) => { + if (answer.status === 404) return Effect.succeed(null); + const found = answer.status === 200 ? decodeRef(answer.body) : Option.none(); + return Option.match(found, { + onSome: (value) => Effect.succeed(value.object.sha), + onNone: () => + Effect.fail( + new KinGitHubRequestError({ + operation: "git.getRef", + stage: answer.status === 200 ? "decode" : "status", + status: answer.status, + }), + ), + }); + }), ); // Moving a tag needs one to exist, and the tag ruleset stops even the owner from making one. @@ -208,6 +227,7 @@ export const runTest23Probes = Effect.fn("kinRulesets.test23")(function* (input: merged: false, tagCreated: false, tagMoved: false, + defaultMovedTo: null as string | null, }; const botCommit = Effect.fn("kinRulesets.test23.botCommit")(function* (file: string) { const answer = yield* call( @@ -320,12 +340,20 @@ export const runTest23Probes = Effect.fn("kinRulesets.test23")(function* (input: ); const mergeAs = (token: Redacted.Redacted, sha: string) => call("pulls.merge", "PUT", `${pullRoute}/merge`, token, { sha, merge_method: "squash" }); + // Records a wrongly accepted write before the read-back, which can fail. + const marking = ( + request: Effect.Effect, + accepted: number, + mark: () => void, + ) => + request.pipe(Effect.tap((answer) => Effect.sync(() => answer.status === accepted && mark()))); const unmoved = (ref: string, sha: string | null) => refSha(ref).pipe( Effect.map((now) => { if (now === sha) return null; if (ref === newTag) state.tagCreated = true; if (ref === releaseRef) state.tagMoved = true; + if (ref === defaultRef) state.defaultMovedTo = now; return `but ${ref} is now ${now ?? "missing"}`; }), ); @@ -350,25 +378,37 @@ export const runTest23Probes = Effect.fn("kinRulesets.test23")(function* (input: probe( `${who} can't push to ${input.defaultBranch}`, "rule_violation", - call("git.updateRef", "PATCH", `/git/refs/${refPath(defaultRef)}`, token, { - sha: h1, - force: false, - }), + marking( + call("git.updateRef", "PATCH", `/git/refs/${refPath(defaultRef)}`, token, { + sha: h1, + force: false, + }), + 200, + () => (state.defaultMovedTo = h1), + ), unmoved(defaultRef, baseSha), ), probe( `${who} can't create a v* tag`, "rule_violation", - call("git.createRef", "POST", "/git/refs", token, { ref: `refs/${newTag}`, sha: h1 }), + marking( + call("git.createRef", "POST", "/git/refs", token, { ref: `refs/${newTag}`, sha: h1 }), + 201, + () => (state.tagCreated = true), + ), unmoved(newTag, null), ), probe( `${who} can't move ${releaseRef.slice("tags/".length)}`, "rule_violation", - call("git.updateRef", "PATCH", `/git/refs/${refPath(releaseRef)}`, token, { - sha: h1, - force: true, - }), + marking( + call("git.updateRef", "PATCH", `/git/refs/${refPath(releaseRef)}`, token, { + sha: h1, + force: true, + }), + 200, + () => (state.tagMoved = true), + ), unmoved(releaseRef, releaseTag.object.sha), ), ...input.rulesets.flatMap(({ id, desired }) => [ @@ -500,8 +540,14 @@ export const runTest23Probes = Effect.fn("kinRulesets.test23")(function* (input: Effect.orElseSucceed(() => "GitHub unreachable"), Effect.map((problem) => { if (problem !== null) cleanupLines.push(` WARN cleanup: couldn't ${name} (${problem})`); + return problem === null; }), ); + // The rulesets have no bypass, so the owner can't undo these either until one is disabled. + const byHand = (steps: string) => + cleanupLines.push( + ` WARN cleanup: undo by hand: ${steps}, then apply kin-rulesets to ${input.repo} again.`, + ); const cleanup = Effect.gen(function* () { if (!state.merged && state.pull !== undefined) { yield* attempt( @@ -517,14 +563,15 @@ export const runTest23Probes = Effect.fn("kinRulesets.test23")(function* (input: [204, 422], ); if (state.tagCreated) { - yield* attempt( + const deleted = yield* attempt( `delete ${newTag}`, call("git.deleteRef", "DELETE", `/git/refs/${refPath(newTag)}`, input.ownerToken), [204], ); + if (!deleted) byHand(`disable kin-release, then delete refs/${newTag}`); } if (state.tagMoved) { - yield* attempt( + const restored = yield* attempt( `move ${releaseRef} back to ${releaseTag.object.sha.slice(0, 7)}`, call("git.updateRef", "PATCH", `/git/refs/${refPath(releaseRef)}`, input.ownerToken, { sha: releaseTag.object.sha, @@ -532,6 +579,16 @@ export const runTest23Probes = Effect.fn("kinRulesets.test23")(function* (input: }), [200], ); + if (!restored) { + byHand( + `disable kin-release, then move refs/${releaseRef} back to ${releaseTag.object.sha}`, + ); + } + } + if (state.defaultMovedTo !== null) { + byHand( + `${input.defaultBranch} moved to ${state.defaultMovedTo.slice(0, 7)}; disable kin-main, then \`git push --force origin ${baseSha}:refs/heads/${input.defaultBranch}\``, + ); } }); const result = yield* run.pipe( diff --git a/docs/kin/specs/approvals.md b/docs/kin/specs/approvals.md index af6c1f9e712b..3d13c80a3a2a 100644 --- a/docs/kin/specs/approvals.md +++ b/docs/kin/specs/approvals.md @@ -390,7 +390,7 @@ These probes assume GitHub checks a fine-grained token's permission before it lo "required_approving_review_count": 1, "require_code_owner_review": true, "dismiss_stale_reviews_on_push": true, - "require_last_push_approval": false, + "require_last_push_approval": true, "required_review_thread_resolution": true, "allowed_merge_methods": ["squash", "merge"] } @@ -409,7 +409,7 @@ These probes assume GitHub checks a fine-grained token's permission before it lo - `bypass_actors` is empty, including repository admins. Otherwise the owner's merge token could skip review. `--check` also requires `current_user_can_bypass: "never"`, and counts a ruleset whose bypass actors it can't see as drift. - `integration_id` 15368 is the GitHub Actions App (`GET /apps/github-actions`), so a commit status posted with any token that has commit-status access can't stand in for CI. -- `require_last_push_approval` is off. Against the bot it adds nothing, since `dismiss_stale_reviews_on_push` already voids the owner's approval when the bot pushes. And it would deadlock an upstream sync branch the owner pushed, because the owner's approval can't count for their own last push. `merge` is allowed for those syncs (below); the executor squashes bot PRs. +- `require_last_push_approval` is on. `dismiss_stale_reviews_on_push` only dismisses an approval when a push changes the diff, so a bot push that adds a commit and a second that reverts it would keep the owner's approval, and with merge commits allowed the unreviewed commit would land in history. Last-push approval makes any bot push after the review need a new one. It would deadlock a sync branch the owner pushed last, so the sync flow below ends with a bot push. `merge` is allowed for those syncs; the executor squashes bot PRs. - `.github/CODEOWNERS` contains `* @GLDRoger`, so the bot's approval never counts, and a PR that changes CODEOWNERS needs the owner's review too. The check reads the copy on the default branch (the one GitHub uses for reviews into it) and GitHub's `codeowners/errors`, and requires a `*` rule with every rule naming exactly `@GLDRoger`, so no later rule hands a path to someone else or to no one. Without it, `require_code_owner_review` is met by anyone's approval, so apply refuses to change any ruleset until CODEOWNERS passes. - A tag ruleset `kin-release` (`refs/tags/v*` and `refs/tags/v*/**`, since `*` stops at `/`) blocks tag creation, update (`update_allows_fetch_and_merge: false`) and deletion, with no bypass, for when releases arrive. Update is included so a release tag can't be moved to another commit. GitHub requires the `update` parameter; the test fake rejects rules missing any parameter the REST reference marks required. - The required check for `GLDRoger/t3code` is `Check`, the `ci.yml` job that fails unless every other job passed or was skipped as not needed. Other repos pass `--status-check`. @@ -418,11 +418,12 @@ These probes assume GitHub checks a fine-grained token's permission before it lo **Upstream syncs (proposed resolution of open question 2, owner to confirm).** The bot can't carry a sync: an upstream merge changes `.github/workflows`, which its missing Workflows permission rejects, and squashing would flatten the merge so the next sync conflicts. So the owner carries it, and Kin only opens the PR: 1. The owner merges upstream locally and pushes `sync/` with the merge commit, using their own credential, never the Kin host's. -2. The bot opens the PR from that branch (Pull requests: write only; it pushes nothing). -3. The owner approves as code owner. The approval counts because `require_last_push_approval` is off; the bot authored the PR, so it isn't the owner's own PR. -4. The owner merges in the GitHub UI with a merge commit, which `allowed_merge_methods` permits. -5. The executor keeps squashing bot PRs (`merge_method: "squash"`). -6. The merge token can't take this path: it has no Workflows permission, so GitHub refuses it a merge that changes workflows. +2. The bot pushes one same-tree commit on top, so it is the last pusher: `POST /git/commits` with the merge commit's tree and the merge commit as its only parent, then `PATCH /git/refs/heads/sync/` to it. The commit changes no files, so its lack of the Workflows permission shouldn't block it; test 23's manual steps confirm this. +3. The bot opens the PR from that branch. +4. The owner approves as code owner. The approval counts because the bot pushed last and authored the PR. +5. The owner merges in the GitHub UI with a merge commit, which `allowed_merge_methods` permits. +6. The executor keeps squashing bot PRs (`merge_method: "squash"`). +7. The merge token can't take this path: it has no Workflows permission, so GitHub refuses it a merge that changes workflows. Cost: `merge` is allowed for every PR into the default branch, so a code-owner-approved bot PR could be merge-committed by hand. That changes history shape, not who may merge. @@ -558,7 +559,7 @@ RPCs and scopes: `kin.approvals.list` (stream) and `get` → `orchestration:read 20. `the audit chain detects an edited row` (`kin.audit.verify`). 21. `the first approver key can't be confirmed from a remote session`. 22. Mobile (`apps/mobile/modules/kin-approval-key`, device test): `signing without biometrics fails`, `re-enrolling biometrics invalidates the key`, `DER signatures convert to compact and verify on the server`. -23. GitHub (`scripts/kin-rulesets.ts --test-23 --repo /`, after `--check` passes there): it refuses a Kin repository (`KIN_GITHUB_REPOS` or `GLDRoger/t3code`, in any case), a name without `scratch`, and a repository whose `GET /repos` `full_name` differs from `--repo` (a rename or transfer redirect). It needs a `v*` tag on the scratch repo and an Actions workflow that runs the required checks on pull requests. It takes a scratch-only fine-grained token of the owner's, checked by `OwnerMergeClient.save`'s probes (`--probe-pr ` names an existing PR for the review probe) and not stored, and mints a `worker` App token, which it revokes at the end. The bot opens a PR; once the Actions checks pass and GitHub reports `mergeable_state: "blocked"`: `the merge token can't submit a review` (403); for both the bot and the merge token, `can't merge without a code-owner review` (405 naming the review), `can't push to the default branch` (422 "Repository rule violations", and the ref hasn't moved), `can't create or move a v* tag` (same), `can't bypass either ruleset` (reading one needs only Metadata, so the read may succeed, but must report `current_user_can_bypass: "never"` and no bypass actors), and `can't read a ruleset's history or change a ruleset` (403, or 404, which GitHub uses to hide endpoints a token can't use; the change sends the desired body, and drift is checked again afterwards). The owner approves and GitHub reports `clean`. Then bait and switch: the bot pushes, the owner's review shows `DISMISSED`, and the merge token's merge of the new head is blocked. The owner approves again and the merge token merges, which shows the blocks came from the rules. After the owner's review at the current head, the bot's `contents: write` token could merge too: the ruleset doesn't limit who merges (threat model, open question 7); test 23 doesn't merge with it. The logic is tested against a fake GitHub in `apps/server/src/kin/github/rulesetsSetup.test.ts`; A rate-limited answer (429, or a 403 with `x-ratelimit-remaining: 0` or `retry-after`) never counts as a block: the run stops and says to try again later. GitHub's exact refusal messages are assumed there and confirmed by the first real run. On the same scratch repo, confirm the section 10 probe assumptions by hand: `--merge-token` accepts a Contents + Metadata token and refuses each broader one listed there; the review probe leaves no PENDING review on the probe PR (`GET /pulls/{n}/reviews` lists none from the owner afterwards); and `permissions.push` is false for a Contents: Read token. Also ask: can an App installation token with Pull requests write and no Contents write enable auto-merge (`enablePullRequestAutoMerge`) on a reviewed PR? If it can, a lead could merge without `contents: write`, and open question 7 needs another answer. Test 23 runs as the server's OS user, which on Linux can read the App's private key and mint unnarrowed tokens (threat model); it proves what the narrowed tokens can't do, not what code running as that user can't. +23. GitHub (`scripts/kin-rulesets.ts --test-23 --repo /`, after `--check` passes there): it refuses a Kin repository (`KIN_GITHUB_REPOS` or `GLDRoger/t3code`, in any case), a name without `scratch`, and a repository whose `GET /repos` `full_name` differs from `--repo` (a rename or transfer redirect). It needs a `v*` tag on the scratch repo and an Actions workflow that runs the required checks on pull requests. It takes a scratch-only fine-grained token of the owner's, checked by `OwnerMergeClient.save`'s probes (`--probe-pr ` names an existing PR for the review probe) and not stored, and mints a `worker` App token, which it revokes at the end. The bot opens a PR; once the Actions checks pass and GitHub reports `mergeable_state: "blocked"`: `the merge token can't submit a review` (403); for both the bot and the merge token, `can't merge without a code-owner review` (405 naming the review), `can't push to the default branch` (422 "Repository rule violations", and the ref hasn't moved), `can't create or move a v* tag` (same), `can't bypass either ruleset` (reading one needs only Metadata, so the read may succeed, but must report `current_user_can_bypass: "never"` and no bypass actors), and `can't read a ruleset's history or change a ruleset` (403, or 404, which GitHub uses to hide endpoints a token can't use; the change sends the desired body, and drift is checked again afterwards). The owner approves and GitHub reports `clean`. Then bait and switch: the bot pushes, the owner's review shows `DISMISSED`, and the merge token's merge of the new head is blocked. The owner approves again and the merge token merges, which shows the blocks came from the rules. After the owner's review at the current head, the bot's `contents: write` token could merge too: the ruleset doesn't limit who merges (threat model, open question 7); test 23 doesn't merge with it. The logic is tested against a fake GitHub in `apps/server/src/kin/github/rulesetsSetup.test.ts`; A rate-limited answer (429, or a 403 with `x-ratelimit-remaining: 0` or `retry-after`) never counts as a block: the run stops and says to try again later. GitHub's exact refusal messages are assumed there and confirmed by the first real run. On the same scratch repo, confirm the section 10 probe assumptions by hand: `--merge-token` accepts a Contents + Metadata token and refuses each broader one listed there; the review probe leaves no PENDING review on the probe PR (`GET /pulls/{n}/reviews` lists none from the owner afterwards); and `permissions.push` is false for a Contents: Read token. Run the section 10 sync flow once: push a branch whose merge commit changes `.github/workflows` with the owner's credential, have a `worker` App token add the same-tree commit (`POST /git/commits`, then the ref update), and confirm GitHub accepts it without the Workflows permission and that the owner's approval then reports the PR `clean`. Also ask: can an App installation token with Pull requests write and no Contents write enable auto-merge (`enablePullRequestAutoMerge`) on a reviewed PR? If it can, a lead could merge without `contents: write`, and open question 7 needs another answer. Test 23 runs as the server's OS user, which on Linux can read the App's private key and mint unnarrowed tokens (threat model); it proves what the narrowed tokens can't do, not what code running as that user can't. Acceptance for phase 1: on `GLDRoger/t3code`, the lead requests a merge of a bot PR; the owner approves on the phone with Face ID; the GitHub review lands from the phone; the executor merges with the pinned SHA; the audit lists grant, device, SHA, provenance and merge commit. Tests 1–21 pass in CI; 22–23 pass on the release checklist. @@ -609,7 +610,7 @@ Later, marked by phase: ## Open questions 1. The phone needs a GitHub user token for the Kin App (device flow, once). Is that acceptable, or should phase 1 start with "Approve on GitHub" only and add the phone token later? -2. Owner-written PRs under an empty bypass list: route them through the bot, or add a time-boxed bypass toggled by an owner-signed action? Upstream syncs make this urgent: once `kin-main` is on `GLDRoger/t3code`, `KIN.md`'s `git push origin main kin` is rejected, a sync PR the owner opens has no code owner left to approve it, the bot can't open one because upstream merges change `.github/workflows` (no Workflows permission), and squash-only would flatten the upstream merge so the next sync conflicts. Decide before applying the ruleset there; one option is `allowed_merge_methods: ["squash", "merge"]` plus a second code owner for sync PRs. **Proposed resolution, owner to confirm:** the sync flow in section 10, where the owner pushes `sync/`, the bot opens the PR, and the owner approves and merge-commits it. This needs `require_last_push_approval` off and `merge` allowed, as `kinRulesets` now has. +2. Owner-written PRs under an empty bypass list: route them through the bot, or add a time-boxed bypass toggled by an owner-signed action? Upstream syncs make this urgent: once `kin-main` is on `GLDRoger/t3code`, `KIN.md`'s `git push origin main kin` is rejected, a sync PR the owner opens has no code owner left to approve it, the bot can't open one because upstream merges change `.github/workflows` (no Workflows permission), and squash-only would flatten the upstream merge so the next sync conflicts. Decide before applying the ruleset there; one option is `allowed_merge_methods: ["squash", "merge"]` plus a second code owner for sync PRs. **Proposed resolution, owner to confirm:** the sync flow in section 10, where the owner pushes `sync/`, the bot pushes a same-tree commit on top and opens the PR, and the owner approves and merge-commits it. This keeps `require_last_push_approval` on and needs `merge` allowed, as `kinRulesets` now has. 3. Merge-queue repos: support `enablePullRequestAutoMerge` with `expectedHeadOid` later, or keep refusing? 4. Should the executor run as a separate OS user with its own keychain, so code running as the Kin server's user can't read the merge token at all? Phase 1 relies on the token being unable to review. The same holds for the App's private key: on Linux, and on any host where agents run as the server's OS user, an agent can read `kin-github-app` from the keychain and mint installation tokens that `installationToken` never narrowed, with the App's full permission table. It can also find an SSH agent socket or other credentials that user holds. A separate executor OS user that alone holds the keychain items, and only the narrowing service hands out tokens, is the real fix. 5. Desktop approvals: a Touch ID-gated Secure Enclave key on macOS through a native addon, or phone-only for good?