| 1 | import { describe, expect, it } from "vitest"; |
| 2 | import { parseWorkflow, type Workflow } from "@diffinery/workflow-yaml"; |
| 3 | import { |
| 4 | PERMISSIVE_DEFAULT, |
| 5 | READ_ALL, |
| 6 | RESTRICTED_DEFAULT, |
| 7 | denied, |
| 8 | permissionsForJob, |
| 9 | readOnly, |
| 10 | requestPermission, |
| 11 | resolvePermissions, |
| 12 | roleForPermissions, |
| 13 | type JobPermissions, |
| 14 | } from "../../src/lib/job-permissions.js"; |
| 15 | import { expandReusable, type Loader } from "../../src/repo/reusable.js"; |
| 16 | |
| 17 | const wf = (yaml: string): Workflow => { |
| 18 | const { workflow, errors } = parseWorkflow(yaml, ".github/workflows/x.yml"); |
| 19 | if (!workflow) throw new Error(errors.map((e) => e.message).join("; ")); |
| 20 | return workflow; |
| 21 | }; |
| 22 | const job = (perms?: string) => ` runs-on: ubuntu-latest\n${perms ? ` permissions: ${perms}\n` : ""} steps: [{ run: echo }]\n`; |
| 23 | const expand = async (root: Workflow, lib?: Workflow) => { |
| 24 | const load: Loader = async (_uses, from) => ({ workflow: lib!, source: from }); |
| 25 | return expandReusable(root, { repoId: null, sha: "abc" }, load); |
| 26 | }; |
| 27 | const writes = (p: JobPermissions) => Object.entries(p).filter(([, v]) => v === "write").map(([k]) => k).sort(); |
| 28 | |
| 29 | describe("permissions: as written", () => { |
| 30 | it("resolves read-all, write-all, {} and mappings like GitHub", () => { |
| 31 | expect(resolvePermissions("read-all")).toEqual(READ_ALL); |
| 32 | expect(resolvePermissions("write-all")["id-token"]).toBe("write"); |
| 33 | expect(resolvePermissions("write-all").models).toBe("read"); |
| 34 | expect(Object.values(resolvePermissions({})).every((v) => v === "none")).toBe(true); |
| 35 | const p = resolvePermissions({ contents: "read", issues: "write", "id-token": "read" }); |
| 36 | expect(p).toMatchObject({ contents: "read", issues: "write", "id-token": "none", statuses: "none" }); |
| 37 | expect(PERMISSIVE_DEFAULT).toMatchObject({ contents: "write", issues: "write", packages: "write", "id-token": "none" }); |
| 38 | expect(roleForPermissions(resolvePermissions({ issues: "write" }))).toBe("write"); |
| 39 | expect(roleForPermissions(resolvePermissions({ "id-token": "write", contents: "read" }))).toBe("read"); |
| 40 | }); |
| 41 | }); |
| 42 | |
| 43 | describe("effective permissions of a job", () => { |
| 44 | it("uses the job's, else the workflow's, else the permissive default", async () => { |
| 45 | const exp = await expand( |
| 46 | wf(`on: push |
| 47 | permissions: { contents: read, issues: write } |
| 48 | jobs: |
| 49 | inherits: |
| 50 | ${job()} own: |
| 51 | ${job("{ statuses: write }")}`), |
| 52 | ); |
| 53 | expect(writes(permissionsForJob(exp, "inherits"))).toEqual(["issues"]); |
| 54 | expect(permissionsForJob(exp, "inherits").contents).toBe("read"); |
| 55 | // Job level replaces the workflow level entirely. |
| 56 | expect(writes(permissionsForJob(exp, "own"))).toEqual(["statuses"]); |
| 57 | expect(permissionsForJob(exp, "own").contents).toBe("none"); |
| 58 | const open = await expand(wf(`on: push\njobs:\n a:\n${job()}`)); |
| 59 | expect(permissionsForJob(open, "a")).toEqual(PERMISSIVE_DEFAULT); |
| 60 | }); |
| 61 | |
| 62 | it("defaults to the repository's setting: read-only contents and packages, or everything", async () => { |
| 63 | const open = await expand(wf(`on: push\njobs:\n a:\n${job()}`)); |
| 64 | expect(permissionsForJob(open, "a", { repoDefault: "read" })).toEqual(RESTRICTED_DEFAULT); |
| 65 | expect(writes(RESTRICTED_DEFAULT)).toEqual([]); |
| 66 | expect(RESTRICTED_DEFAULT).toMatchObject({ contents: "read", packages: "read", issues: "none", "pull-requests": "none" }); |
| 67 | expect(permissionsForJob(open, "a", { repoDefault: "write" })).toEqual(PERMISSIVE_DEFAULT); |
| 68 | // what a workflow asks for is not limited by the default |
| 69 | const asks = await expand(wf(`on: push\npermissions: { issues: write }\njobs:\n a:\n${job()}`)); |
| 70 | expect(writes(permissionsForJob(asks, "a", { repoDefault: "read" }))).toEqual(["issues"]); |
| 71 | }); |
| 72 | |
| 73 | it("never gives a fork's pull request write", async () => { |
| 74 | const exp = await expand(wf(`on: pull_request\npermissions: write-all\njobs:\n a:\n${job()}`)); |
| 75 | expect(writes(permissionsForJob(exp, "a", { untrusted: true }))).toEqual([]); |
| 76 | expect(permissionsForJob(exp, "a", { untrusted: true }).contents).toBe("read"); |
| 77 | }); |
| 78 | |
| 79 | it("caps a reusable workflow by the calling job", async () => { |
| 80 | const lib = wf(`on: workflow_call |
| 81 | jobs: |
| 82 | plain: |
| 83 | ${job()} greedy: |
| 84 | ${job("write-all")}`); |
| 85 | const exp = await expand( |
| 86 | wf(`on: push |
| 87 | permissions: read-all |
| 88 | jobs: |
| 89 | call: |
| 90 | permissions: { contents: read, issues: write } |
| 91 | uses: ./.github/workflows/lib.yml |
| 92 | `), |
| 93 | lib, |
| 94 | ); |
| 95 | expect(writes(permissionsForJob(exp, "call/plain"))).toEqual(["issues"]); |
| 96 | expect(writes(permissionsForJob(exp, "call/greedy"))).toEqual(["issues"]); |
| 97 | expect(permissionsForJob(exp, "call/greedy")["id-token"]).toBe("none"); |
| 98 | }); |
| 99 | }); |
| 100 | |
| 101 | describe("what each request needs", () => { |
| 102 | const p = resolvePermissions({ contents: "read", issues: "write" }); |
| 103 | const check = (method: string, path: string, min: "read" | "write" = "read") => denied(p, requestPermission(method, path, min)); |
| 104 | |
| 105 | it("maps endpoints to permission scopes", () => { |
| 106 | expect(check("POST", "/api/v3/repos/o/r/issues")).toBeNull(); |
| 107 | expect(check("POST", "/api/v3/repos/o/r/issues/3/comments")).toBeNull(); |
| 108 | expect(check("POST", "/api/v3/repos/o/r/labels")).toBeNull(); |
| 109 | expect(check("GET", "/api/v3/repos/o/r/contents/README.md")).toBeNull(); |
| 110 | expect(check("GET", "/api/v3/repos/o/r")).toBeNull(); |
| 111 | expect(check("PUT", "/api/v3/repos/o/r/contents/x")).toMatch(/contents: write/); |
| 112 | expect(check("POST", "/api/v3/repos/o/r/statuses/abc")).toMatch(/statuses: write/); |
| 113 | expect(check("POST", "/api/v3/repos/o/r/check-runs")).toMatch(/checks: write/); |
| 114 | expect(check("POST", "/api/v3/repos/o/r/pulls")).toMatch(/pull-requests: write/); |
| 115 | expect(check("PUT", "/api/v3/repos/o/r/pulls/1/merge")).toMatch(/contents: write/); |
| 116 | expect(check("GET", "/api/v3/repos/o/r/actions/runs")).toMatch(/actions: read/); |
| 117 | expect(check("POST", "/api/v3/repos/o/r/releases")).toMatch(/contents: write/); |
| 118 | expect(check("POST", "/api/uploads/repos/o/r/releases/1/assets")).toMatch(/contents: write/); |
| 119 | expect(check("POST", "/api/v3/repos/o/r/commits/abc/comments")).toMatch(/contents: write/); |
| 120 | expect(check("PATCH", "/api/v3/repos/o/r/comments/7")).toMatch(/contents: write/); |
| 121 | expect(check("PATCH", "/api/v3/repos/o/r/issues/comments/7")).toBeNull(); |
| 122 | // git: fetches are POSTs that read; pushes need contents: write |
| 123 | expect(check("POST", "/o/r.git/git-upload-pack")).toBeNull(); |
| 124 | expect(check("GET", "/o/r.git/info/refs", "write")).toMatch(/contents: write/); |
| 125 | expect(check("POST", "/o/r.git/info/lfs/objects/batch")).toBeNull(); |
| 126 | // web pages: the code, a commit, the editor, and pull requests by their web path |
| 127 | expect(check("GET", "/o/r")).toBeNull(); |
| 128 | expect(requestPermission("GET", "/o/r", "read")).toEqual({ scopes: ["contents"], access: "read" }); |
| 129 | expect(requestPermission("GET", "/o/r/commit/abc", "read")).toEqual({ scopes: ["contents"], access: "read" }); |
| 130 | expect(check("POST", "/o/r/edit/main/README.md")).toMatch(/contents: write/); |
| 131 | expect(check("POST", "/o/r/new/main")).toMatch(/contents: write/); |
| 132 | expect(check("POST", "/o/r/pull/1/merge")).toMatch(/pull-requests: write/); |
| 133 | expect(requestPermission("GET", "/o/r/pull/1", "read")).toEqual({ scopes: ["pull-requests"], access: "read" }); |
| 134 | }); |
| 135 | |
| 136 | it("lets anyone's reads of a public repository through, never its writes", () => { |
| 137 | expect(readOnly(requestPermission("GET", "/api/v3/repos/o/r", "read"))).toBe(true); |
| 138 | expect(readOnly(requestPermission("GET", "/api/v3/repos/o/r/contents/x", "read"))).toBe(true); |
| 139 | expect(readOnly(requestPermission("POST", "/o/r.git/git-upload-pack", "read"))).toBe(true); |
| 140 | expect(readOnly(requestPermission("PUT", "/api/v3/repos/o/r/contents/x", "write"))).toBe(false); |
| 141 | expect(readOnly(requestPermission("GET", "/o/r.git/info/refs", "write"))).toBe(false); |
| 142 | expect(readOnly(requestPermission("GET", "/api/v3/repos/o/r/actions/secrets", "read"))).toBe(false); |
| 143 | // contents: none still blocks the code (of a private repository; loadRepo lets public reads through) |
| 144 | const none = resolvePermissions({ contents: "none" }); |
| 145 | expect(denied(none, requestPermission("GET", "/api/v3/repos/o/r/contents/x", "read"))).toMatch(/contents: read/); |
| 146 | }); |
| 147 | |
| 148 | it("keeps repository administration away from job tokens", () => { |
| 149 | const all = resolvePermissions("write-all"); |
| 150 | const admin = (method: string, path: string) => denied(all, requestPermission(method, path, "read")); |
| 151 | expect(admin("PATCH", "/api/v3/repos/o/r")).toMatch(/not available|cannot/); |
| 152 | expect(admin("PUT", "/api/v3/repos/o/r/actions/secrets/X")).toMatch(/not available/); |
| 153 | expect(admin("GET", "/api/v3/repos/o/r/actions/secrets")).toMatch(/not available/); |
| 154 | expect(admin("PUT", "/api/v3/repos/o/r/branches/main/protection")).toMatch(/not available/); |
| 155 | expect(admin("POST", "/api/v3/repos/o/r/hooks")).toMatch(/not available/); |
| 156 | expect(admin("POST", "/api/v3/repos/o/r/actions/runners/claim")).toMatch(/not available/); |
| 157 | expect(admin("POST", "/mcp")).toMatch(/not available/); |
| 158 | // a file or branch that happens to be called "settings" or "secrets" is still just contents |
| 159 | expect(admin("GET", "/api/v3/repos/o/r/contents/settings/secrets.md")).toBeNull(); |
| 160 | }); |
| 161 | }); |