diff --git a/apps/server/src/kin/github/KinRulesets.ts b/apps/server/src/kin/github/KinRulesets.ts new file mode 100644 index 000000000000..c11c0e439a4a --- /dev/null +++ b/apps/server/src/kin/github/KinRulesets.ts @@ -0,0 +1,220 @@ +// 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. + +/** + * 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 { + 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, + // 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"], + }, + }, + { + type: "required_status_checks", + parameters: { + strict_required_status_checks_policy: true, + do_not_enforce_on_create: false, + required_status_checks: requiredChecks.map((context) => ({ + context, + integration_id: GITHUB_ACTIONS_INTEGRATION_ID, + })), + }, + }, + ], + }, + { + name: "kin-release", + target: "tag", + enforcement: "active", + bypass_actors: [], + // `*` 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" }, + ], + }, +]; + +/** 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; + /** 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<{ + 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); + // 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({ + 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) => { + // 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; + 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/OwnerMergeClient.ts b/apps/server/src/kin/github/OwnerMergeClient.ts index a823e6e169ca..2c527d9c9455 100644 --- a/apps/server/src/kin/github/OwnerMergeClient.ts +++ b/apps/server/src/kin/github/OwnerMergeClient.ts @@ -12,8 +12,10 @@ 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, type GitHubStatusResponse, type KinGitHubRequestError, } from "./githubRest.ts"; @@ -33,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", @@ -62,18 +62,10 @@ 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"; - } - // GitHub's secondary limit can come with neither header. - if (answer.message?.toLowerCase().includes("secondary rate limit")) return "rate_limited"; - 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 037d4f00892a..12c87bf6a0cf 100644 --- a/apps/server/src/kin/github/githubRest.ts +++ b/apps/server/src/kin/github/githubRest.ts @@ -37,7 +37,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, ) => { @@ -55,7 +55,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; @@ -126,3 +126,71 @@ 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 & { + readonly message?: string | null | undefined; + }, +) => + answer.status === 429 || + (answer.status === 403 && + (answer.headers["x-ratelimit-remaining"] === "0" || + answer.headers["retry-after"] !== undefined || + // 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("/"); + return `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}`; +}; + +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; +} + +/** 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, + 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 new file mode 100644 index 000000000000..7d8426c62d3e --- /dev/null +++ b/apps/server/src/kin/github/rulesetsSetup.test.ts @@ -0,0 +1,838 @@ +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 { 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 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", + token: Redacted.make(token), +}); + +type StoredRuleset = Record & { + id: number; + name: string; + target: string; + 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 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. 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: { ...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 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 = !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: { + full_name: options.fullName ?? slug, + 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", + })), + }; + } + 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]!, owner && !options.hideBypass) }; + } + 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, first.lines.join("\n")); + 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 ruleParameters = (rulesets: Array, type: string) => + branchRule(rulesets).rules.find((rule) => rule.type === type)!.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)", + ], + [ + "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) => { + ruleParameters(rulesets, "pull_request").require_code_owner_review = false; + }, + " 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) => { + ruleParameters(rulesets, "pull_request").allowed_merge_methods = [ + "squash", + "merge", + "rebase", + ]; + }, + ' 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", + (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)); + }); + + 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']], + [ + "* @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', + ], + ], + [ + "* @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); + }); + + 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)); + }); +}); + +const ruleViolation = (rule: string) => ({ + message: `Repository rule violations found\n\n${rule}\n\n`, + documentation_url: "https://docs.github.com/rest", + 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], + [ + 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, 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], + ] as const)("HTTP %i %j as %s is %s", (status, body, block, 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)); + }); +}); + +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; + /** 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; + 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; + readonly fullName?: string; + } = {}, +) => { + const base = "/repos/GLDRoger/kin-scratch"; + 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/")) { + 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" } } + : { 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") && !broken.tagCreatable) { + 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 `POST ${base}/pulls`: + 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 === 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", + commit_id: body!.commit_id!, + user: { login: "GLDRoger" }, + }); + return { status: 200, body: {} }; + } + 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`: + 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: {} }; + } + return undefined; + }, + }); + 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), +}); +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* runTest23(); + }); + +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")); + 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 }, "can't submit a review"], + ["a bot that can merge alone", { botCanMerge: true }, "the bot can't merge"], + ["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"], + [ + "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); + 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); + 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)); + }); + + 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* () { + const result = yield* Rulesets.runTest23({ + target: target(OWNER_TOKEN, scratch), + requiredChecks: ["ci"], + 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 new file mode 100644 index 000000000000..eb2d816ab23c --- /dev/null +++ b/apps/server/src/kin/github/rulesetsSetup.ts @@ -0,0 +1,607 @@ +// 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 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 } from "effect/http"; + +import { gitHubAnswer, gitHubJson, repoPath } from "./githubRest.ts"; +import * as Keychain from "./Keychain.ts"; +import * as KinGitHubApp from "./KinGitHubApp.ts"; +import { + KIN_CODEOWNERS_PATH, + KIN_REPO_REQUIRED_CHECKS, + codeownersProblems, + diffRuleset, + kinRulesets, + type KinRuleset, +} 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; + 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({ + full_name: Schema.String, + 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, + current_user_can_bypass: Schema.optional(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 refuse = (reason: string) => Effect.fail(new KinRulesetsRefusedError({ reason })); + +/** + * 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, 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* ( + 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}`)]; + +const checkVerified = Effect.fn("kinRulesets.checkVerified")(function* ( + target: RepoTarget, + { login, defaultBranch }: VerifiedOwner, + input: { readonly requiredChecks: ReadonlyArray; readonly rulesets: boolean }, +) { + 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) { + 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; +}); + +/** 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; +}); + +const isKinRepo = (kinRepos: ReadonlyArray, repo: string) => + kinRepos.some((kin) => kin.toLowerCase() === repo.toLowerCase()); + +/** + * 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 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 kinRepos: ReadonlyArray; + readonly tokens: Effect.Effect< + { + readonly botToken: Redacted.Redacted; + readonly mergeToken: Redacted.Redacted; + }, + E, + R + >; +}) { + const { target } = input; + 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 { botToken, mergeToken } = yield* input.tokens; + const client = yield* HttpClient.HttpClient; + const revokeLines: Array = []; + const revoke = gitHubAnswer({ + client, + 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, + }); + 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." + : probes.rateLimited + ? "NOT DONE: GitHub rate-limited test 23, which proves nothing either way; try again later." + : "FAIL: see above.", + ], + } satisfies RulesetsResult; +}); + +const decodeRepo = Schema.decodeUnknownEffect(RepoSlug); +const TEST_23_ORG = Schema.decodeSync(KinOrgId)("kin-test-23"); + +/** `OwnerMergeClient.save` writes to this, so test 23's probes run without storing the token. */ +const discardKeychain = Layer.succeed( + Keychain.KinKeychain, + Keychain.KinKeychain.of({ + get: Effect.fn("discardKeychain.get")(function* () { + return Option.none>(); + }), + set: Effect.fn("discardKeychain.set")(function* () {}), + remove: Effect.fn("discardKeychain.remove")(function* () {}), + ready: Effect.fn("discardKeychain.ready")(function* () {}), + }), +); + +const scratchMergeToken = Prompt.run( + Prompt.Hidden({ + message: + "Paste a fine-grained token of the owner's for the scratch repo only, with Contents: Read and write and Metadata: Read (hidden)", + }), +).pipe(Effect.map((pasted) => Redacted.make(String(Redacted.value(pasted))))); + +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 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( + "A required status check context (repeatable); Kin repos have defaults.", + ), + Flag.atLeast(0), + ), + appId: Flag.String("app-id").pipe( + 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* () { + const repo = yield* decodeRepo(input.repo).pipe( + Effect.mapError( + () => new KinRulesetsRefusedError({ reason: "--repo must be owner/name." }), + ), + ); + 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 .`, + ); + } + 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 appConfig = Option.match(input.appId, { + onNone: () => KinGitHubApp.KinGitHubAppConfig.layer, + onSome: (appId) => Layer.succeed(KinGitHubApp.KinGitHubAppConfig, { appId }), + }); + // The App and the merge token are checked against the scratch repo alone. The stored merge + // 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] }); + const tokens = Effect.gen(function* () { + const mergeToken = yield* scratchMergeToken; + yield* (yield* OwnerMergeClient.OwnerMergeClient).save({ + orgId: TEST_23_ORG, + token: mergeToken, + probePr: Option.getOrUndefined(input.probePr), + }); + const bot = yield* (yield* KinGitHubApp.KinGitHubApp).installationToken({ + repo, + permissions: { contents: "write", pull_requests: "write" }, + holder: "server", + }); + return { botToken: bot.token, mergeToken }; + }).pipe( + Effect.provide( + Layer.mergeAll( + KinGitHubApp.layer.pipe(Layer.provide(Layer.mergeAll(appConfig, scratchScope))), + OwnerMergeClient.layer.pipe( + Layer.provide(Layer.mergeAll(scratchScope, discardKeychain)), + ), + ), + ), + ); + return yield* runTest23({ target, requiredChecks, kinRepos: protectedRepos, tokens }); + }).pipe(Effect.provide(KinGitHubScope.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/apps/server/src/kin/github/rulesetsTest23.ts b/apps/server/src/kin/github/rulesetsTest23.ts new file mode 100644 index 000000000000..d34c88406542 --- /dev/null +++ b/apps/server/src/kin/github/rulesetsTest23.ts @@ -0,0 +1,603 @@ +// 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 * 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, +} 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 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" + /** 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, 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 && answer.message.trim() === GITHUB_PAT_NOT_ACCESSIBLE; + 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; + /** 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`. */ +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)); + /** `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.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. + 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, + 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.`, + ], + }; + } + 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, + rateLimited: 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, + defaultMovedTo: null as string | null, + }; + 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, + 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, + base: input.defaultBranch, + }); + const pull = decodePull(opened.body); + if (opened.status !== 201 || pull._tag === "None") { + return { + ok: false, + rateLimited: 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}`}`, + rateLimited: isGitHubRateLimit(answer), + } 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)})`, + rateLimited: isGitHubRateLimit(answer), + })), + ); + 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"}`; + }), + ); + + 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", + 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", + 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", + 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 }) => [ + // 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})`, + rateLimited: isGitHubRateLimit(answer), + }; + }), + ), + 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"), + ]; + + let limited = false; + const runSteps = Effect.fn("kinRulesets.test23.steps")(function* ( + list: ReadonlyArray>, + ) { + for (const step of list) { + 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, + 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. + 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`, + rateLimited: isGitHubRateLimit(answer), + }; + }), + ); + 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, rateLimited: false, 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})`); + 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( + `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) { + 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) { + 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, + force: true, + }), + [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( + Effect.ensuring(cleanup), + Effect.tapError(() => Effect.logWarning("Test 23 cleanup", { lines: cleanupLines })), + ); + return { + ok: result.ok, + rateLimited: result.rateLimited, + lines: [...result.lines, ...cleanupLines], + }; +}); diff --git a/docs/kin/specs/approvals.md b/docs/kin/specs/approvals.md index fab213846d01..f1dd5b0714f4 100644 --- a/docs/kin/specs/approvals.md +++ b/docs/kin/specs/approvals.md @@ -394,7 +394,7 @@ These probes assume GitHub checks a fine-grained token's permission before it lo **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 { @@ -414,23 +414,42 @@ These probes assume GitHub checks a fine-grained token's permission before it lo "dismiss_stale_reviews_on_push": true, "require_last_push_approval": true, "required_review_thread_resolution": true, - "allowed_merge_methods": ["squash"] + "allowed_merge_methods": ["squash", "merge"] } }, { "type": "required_status_checks", "parameters": { "strict_required_status_checks_policy": true, - "required_status_checks": [{ "context": "" }] + "do_not_enforce_on_create": false, + "required_status_checks": [{ "context": "", "integration_id": 15368 }] } } ] } ``` -- `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. +- `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 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`. +- 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. + +`kinRulesets` targets `~DEFAULT_BRANCH`. On `GLDRoger/t3code` that is `kin`, where PRs land; `main` is the upstream mirror and is held by a hand-made "main: upstream mirror" ruleset with an admin bypass that `--check` doesn't read. Bringing `main` under `kinRulesets` is open. + +**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 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, only after Kin checks that `head^` is the SHA the owner pushed and `head^{tree}` equals that commit's tree; the card shows the result. Without the check, a change could hide inside a large upstream diff and the owner would approve it as the last push. Until `sync/*` has its own ruleset, the bot could also force-push the branch before review, so the check runs against the head being approved. +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. ### 11. Audit @@ -581,7 +600,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`, `only one signature at a time, under the grant's own text`, `an overlay over the sheet can't approve`, `a double tap can't land on Approve`, `a cover removed after the first tap can't approve` (including about 50 randomised-timer hides: Approve never enables less than 0.7 s after the cover goes), `a cover mounted after Approve arms and hidden on the first tap can't approve on the second`, `the app's own web-view picture in picture closes before the sheet shows and while it is up`, `system UI doesn't lock the sheet out`. The module's README has the checklist; its grant parser's vectors run without a device. -23. GitHub (`scripts/kin-rulesets.ts --check`, run against a scratch repo): `the owner merge token can't submit a review` (expect 403), `a merge without a code-owner review is blocked`, and `the bot can't merge to main before the owner's review`. After the owner's review at the current head, a `server` holder's `contents: write` token can merge too: the ruleset doesn't limit who merges (threat model, open question 7). The test asserts that limit as it is, so a change in GitHub's behaviour shows up. The same run confirms the section 10 probe assumptions: `--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. It also asks: 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 `server` App token (the only holder allowed `contents: write`), 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, a `server` holder'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 `server` 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. @@ -632,7 +651,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. **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? diff --git a/knip.jsonc b/knip.jsonc index 76becad7b271..7e05711fc107 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, +);