Skip to content
Sign in

flagon-io/g1t

public
0
1,315 linesCodeBlameRaw
1//! Scopes: what an access token may do on its owner's behalf.
2//!
3//! A personal access token, a workspace's token and an application signed
4//! in with OAuth each carry a set of scopes. A token reaches whatever the
5//! one it acts as can reach: a person's token, that person's workspaces and
6//! repositories; a workspace's token, that workspace. What a request may do
7//! is the intersection of two things: the role of whoever the token acts as
8//! (see [`crate::access`]) and the token's scopes.
9//!
10//! Each scope is a resource and a level, written `resource:level`, such as
11//! `issues:write`. A higher level of a resource includes the lower ones:
12//! `repo:admin` includes `repo:write`, which includes `repo:read`.
13//!
14//! This module is the one source of truth: the API (REST and MCP) and git
15//! enforce it, and identity stores it. `packages/contracts/src/scopes.ts`
16//! mirrors the table for the site; a test keeps the two the same.
17
18use serde::{Deserialize, Serialize};
19
20use crate::credentials::Decision;
21
22/// Something a token can be given access to.
23#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
24pub enum Resource {
25 Account,
26 Notifications,
27 Workspace,
28 Billing,
29 Repo,
30 Code,
31 Security,
32 Packages,
33 Issues,
34 PullRequests,
35 Agents,
36 Workflows,
37 Checks,
38 Deployments,
39 Memory,
40 Access,
41 Webhooks,
42 Secrets,
43 Runners,
44 Models,
45}
46
47impl Resource {
48 pub const ALL: [Resource; 20] = [
49 Resource::Repo,
50 Resource::Code,
51 Resource::Security,
52 Resource::Packages,
53 Resource::Issues,
54 Resource::PullRequests,
55 Resource::Agents,
56 Resource::Workflows,
57 Resource::Checks,
58 Resource::Deployments,
59 Resource::Memory,
60 Resource::Account,
61 Resource::Notifications,
62 Resource::Workspace,
63 Resource::Billing,
64 Resource::Access,
65 Resource::Webhooks,
66 Resource::Secrets,
67 Resource::Runners,
68 Resource::Models,
69 ];
70
71 pub fn as_str(self) -> &'static str {
72 match self {
73 Resource::Account => "account",
74 Resource::Notifications => "notifications",
75 Resource::Workspace => "workspace",
76 Resource::Billing => "billing",
77 Resource::Repo => "repo",
78 Resource::Code => "code",
79 Resource::Security => "security",
80 Resource::Packages => "packages",
81 Resource::Issues => "issues",
82 Resource::PullRequests => "pull_requests",
83 Resource::Agents => "agents",
84 Resource::Workflows => "workflows",
85 Resource::Checks => "checks",
86 Resource::Deployments => "deployments",
87 Resource::Memory => "memory",
88 Resource::Access => "access",
89 Resource::Webhooks => "webhooks",
90 Resource::Secrets => "secrets",
91 Resource::Runners => "runners",
92 Resource::Models => "models",
93 }
94 }
95
96 /// Its name, for people.
97 pub fn label(self) -> &'static str {
98 match self {
99 Resource::Account => "Your account",
100 Resource::Notifications => "Notifications",
101 Resource::Workspace => "Workspaces",
102 Resource::Billing => "Billing",
103 Resource::Repo => "Repositories",
104 Resource::Code => "Code",
105 Resource::Security => "Security",
106 Resource::Packages => "Packages",
107 Resource::Issues => "Issues",
108 Resource::PullRequests => "Pull requests",
109 Resource::Agents => "g1t agents",
110 Resource::Workflows => "Workflows",
111 Resource::Checks => "Checks and statuses",
112 Resource::Deployments => "Deployments",
113 Resource::Memory => "Memory and context",
114 Resource::Access => "Who has access",
115 Resource::Webhooks => "Webhooks",
116 Resource::Secrets => "Secrets and variables",
117 Resource::Runners => "Self-hosted runners",
118 Resource::Models => "AI Gateway",
119 }
120 }
121}
122
123/// How much of a resource.
124#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
125pub enum Level {
126 Read,
127 Write,
128 /// Starting g1t's agents, which spends the workspace's money.
129 Run,
130 /// Deleting what cannot be brought back, such as a package's versions.
131 Delete,
132 Admin,
133}
134
135impl Level {
136 pub fn as_str(self) -> &'static str {
137 match self {
138 Level::Read => "read",
139 Level::Write => "write",
140 Level::Run => "run",
141 Level::Delete => "delete",
142 Level::Admin => "admin",
143 }
144 }
145}
146
147/// One scope. Its text form, `resource:level`, is what tokens store, OAuth
148/// clients ask for, and errors name.
149#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
150pub enum Scope {
151 RepoRead,
152 RepoWrite,
153 RepoAdmin,
154 CodeRead,
155 CodeWrite,
156 SecurityRead,
157 SecurityWrite,
158 PackagesRead,
159 PackagesWrite,
160 PackagesDelete,
161 IssuesRead,
162 IssuesWrite,
163 PullRequestsRead,
164 PullRequestsWrite,
165 AgentsRun,
166 WorkflowsRead,
167 WorkflowsWrite,
168 ChecksRead,
169 ChecksWrite,
170 DeploymentsRead,
171 DeploymentsWrite,
172 MemoryRead,
173 MemoryWrite,
174 AccountRead,
175 AccountWrite,
176 NotificationsRead,
177 NotificationsWrite,
178 WorkspaceRead,
179 WorkspaceAdmin,
180 BillingRead,
181 BillingWrite,
182 AccessRead,
183 AccessAdmin,
184 WebhooksRead,
185 WebhooksAdmin,
186 SecretsRead,
187 SecretsAdmin,
188 RunnersRead,
189 RunnersAdmin,
190 ModelsRead,
191 ModelsWrite,
192}
193
194impl Scope {
195 /// Every scope, grouped by resource, least first.
196 pub const ALL: [Scope; 41] = [
197 Scope::RepoRead,
198 Scope::RepoWrite,
199 Scope::RepoAdmin,
200 Scope::CodeRead,
201 Scope::CodeWrite,
202 Scope::SecurityRead,
203 Scope::SecurityWrite,
204 Scope::PackagesRead,
205 Scope::PackagesWrite,
206 Scope::PackagesDelete,
207 Scope::IssuesRead,
208 Scope::IssuesWrite,
209 Scope::PullRequestsRead,
210 Scope::PullRequestsWrite,
211 Scope::AgentsRun,
212 Scope::WorkflowsRead,
213 Scope::WorkflowsWrite,
214 Scope::ChecksRead,
215 Scope::ChecksWrite,
216 Scope::DeploymentsRead,
217 Scope::DeploymentsWrite,
218 Scope::MemoryRead,
219 Scope::MemoryWrite,
220 Scope::AccountRead,
221 Scope::AccountWrite,
222 Scope::NotificationsRead,
223 Scope::NotificationsWrite,
224 Scope::WorkspaceRead,
225 Scope::WorkspaceAdmin,
226 Scope::BillingRead,
227 Scope::BillingWrite,
228 Scope::AccessRead,
229 Scope::AccessAdmin,
230 Scope::WebhooksRead,
231 Scope::WebhooksAdmin,
232 Scope::SecretsRead,
233 Scope::SecretsAdmin,
234 Scope::RunnersRead,
235 Scope::RunnersAdmin,
236 Scope::ModelsRead,
237 Scope::ModelsWrite,
238 ];
239
240 pub fn as_str(self) -> &'static str {
241 match self {
242 Scope::RepoRead => "repo:read",
243 Scope::RepoWrite => "repo:write",
244 Scope::RepoAdmin => "repo:admin",
245 Scope::CodeRead => "code:read",
246 Scope::CodeWrite => "code:write",
247 Scope::SecurityRead => "security:read",
248 Scope::SecurityWrite => "security:write",
249 Scope::PackagesRead => "packages:read",
250 Scope::PackagesWrite => "packages:write",
251 Scope::PackagesDelete => "packages:delete",
252 Scope::IssuesRead => "issues:read",
253 Scope::IssuesWrite => "issues:write",
254 Scope::PullRequestsRead => "pull_requests:read",
255 Scope::PullRequestsWrite => "pull_requests:write",
256 Scope::AgentsRun => "agents:run",
257 Scope::WorkflowsRead => "workflows:read",
258 Scope::WorkflowsWrite => "workflows:write",
259 Scope::ChecksRead => "checks:read",
260 Scope::ChecksWrite => "checks:write",
261 Scope::DeploymentsRead => "deployments:read",
262 Scope::DeploymentsWrite => "deployments:write",
263 Scope::MemoryRead => "memory:read",
264 Scope::MemoryWrite => "memory:write",
265 Scope::AccountRead => "account:read",
266 Scope::AccountWrite => "account:write",
267 Scope::NotificationsRead => "notifications:read",
268 Scope::NotificationsWrite => "notifications:write",
269 Scope::WorkspaceRead => "workspace:read",
270 Scope::WorkspaceAdmin => "workspace:admin",
271 Scope::BillingRead => "billing:read",
272 Scope::BillingWrite => "billing:write",
273 Scope::AccessRead => "access:read",
274 Scope::AccessAdmin => "access:admin",
275 Scope::WebhooksRead => "webhooks:read",
276 Scope::WebhooksAdmin => "webhooks:admin",
277 Scope::SecretsRead => "secrets:read",
278 Scope::SecretsAdmin => "secrets:admin",
279 Scope::RunnersRead => "runners:read",
280 Scope::RunnersAdmin => "runners:admin",
281 Scope::ModelsRead => "models:read",
282 Scope::ModelsWrite => "models:write",
283 }
284 }
285
286 pub fn parse(text: &str) -> Option<Scope> {
287 let text = text.trim().to_ascii_lowercase();
288 Scope::ALL.into_iter().find(|scope| scope.as_str() == text)
289 }
290
291 pub fn resource(self) -> Resource {
292 let name = self.as_str().split_once(':').map_or("", |(resource, _)| resource);
293 Resource::ALL
294 .into_iter()
295 .find(|resource| resource.as_str() == name)
296 .unwrap_or(Resource::Account)
297 }
298
299 pub fn level(self) -> Level {
300 match self.as_str().rsplit_once(':').map_or("", |(_, level)| level) {
301 "write" => Level::Write,
302 "run" => Level::Run,
303 "delete" => Level::Delete,
304 "admin" => Level::Admin,
305 _ => Level::Read,
306 }
307 }
308
309 /// Whether holding `self` gives `other`: the same resource, at the same
310 /// level or a lower one.
311 pub fn includes(self, other: Scope) -> bool {
312 self.resource() == other.resource() && self.level() >= other.level()
313 }
314
315 /// Changes that are hard or impossible to undo, or that decide who can
316 /// reach what. Shown behind a warning wherever scopes are chosen.
317 pub fn dangerous(self) -> bool {
318 matches!(self.level(), Level::Admin | Level::Delete)
319 }
320
321 /// What it lets a token do, in plain words.
322 pub fn describe(self) -> &'static str {
323 match self {
324 Scope::RepoRead => "See repositories, their settings, labels, timelines, releases, languages, contributors and security alerts, and search",
325 Scope::RepoWrite => "Create repositories, rename branches, change how pull requests merge and publish releases",
326 Scope::RepoAdmin => "Rename, archive, transfer, delete or change who can see a repository, change its rulesets, and dismiss security alerts",
327 Scope::CodeRead => "Clone and fetch private repositories with git",
328 Scope::CodeWrite => "Push commits with git",
329 Scope::SecurityRead => "See secret scanning, code scanning and vulnerability alerts, custom patterns, the dependency graph and SBOM, and security settings",
330 Scope::SecurityWrite => "Dismiss and reopen alerts, bypass push protection, review bypass requests, manage custom patterns, upload SARIF and change security settings",
331 Scope::PackagesRead => "Pull container images and install private packages",
332 Scope::PackagesWrite => "Push container images and publish packages",
333 Scope::PackagesDelete => "Delete packages and their versions",
334 Scope::IssuesRead => "Read issues, comments and plans",
335 Scope::IssuesWrite => "Open, edit, close and comment on issues",
336 Scope::PullRequestsRead => "Read pull requests, their changes, sessions and merge queues",
337 Scope::PullRequestsWrite => "Open, review, close and merge pull requests",
338 Scope::AgentsRun => "Put g1t agents to work and message them, which uses the workspace's money",
339 Scope::WorkflowsRead => "Read workflows, runs and logs",
340 Scope::WorkflowsWrite => "Run, cancel, rerun and turn workflows on or off",
341 Scope::ChecksRead => "Read commits' statuses, check runs, check suites and annotations",
342 Scope::ChecksWrite => "Report statuses and check runs on commits, and ask for checks to run again",
343 Scope::DeploymentsRead => "See deployments, their statuses and environments",
344 Scope::DeploymentsWrite => "Report deployments and their statuses, from any CI",
345 Scope::MemoryRead => "Recall memory and search the workspace's context",
346 Scope::MemoryWrite => "Save memory for the next agent",
347 Scope::AccountRead => "Read your email addresses, invites, invitations, pinned projects and stars",
348 Scope::AccountWrite => "Change your email addresses, make invites, answer invitations, pin projects and star repositories",
349 Scope::NotificationsRead => "See your inbox, its threads, and what you subscribe to and watch",
350 Scope::NotificationsWrite => "Mark notifications read, done, saved or snoozed, subscribe to threads and watch repositories",
351 Scope::WorkspaceRead => "Read workspace settings, invites, integrations, model routes, teams and rulesets",
352 Scope::WorkspaceAdmin => "Create and delete workspaces, invite members, connect integrations, create, change and delete teams, and change the workspace's rulesets",
353 Scope::BillingRead => "See a workspace's usage, budget, AI credit and invoices",
354 Scope::BillingWrite => "Change a workspace's budget and buy AI credit",
355 Scope::AccessRead => "See who has access to repositories",
356 Scope::AccessAdmin => "Give and take away access to repositories, a team's included",
357 Scope::WebhooksRead => "See webhooks and their deliveries",
358 Scope::WebhooksAdmin => "Create, change and delete webhooks",
359 Scope::SecretsRead => "List secrets (never their values) and read variables",
360 Scope::SecretsAdmin => "Set and delete secrets and variables",
361 Scope::RunnersRead => "See self-hosted runners, their groups and where agents run",
362 Scope::RunnersAdmin => "Register and remove self-hosted runners, change their groups and settings",
363 Scope::ModelsRead => "See the workspace's AI Gateway requests: their models, tokens, cost and status",
364 Scope::ModelsWrite => "Send model requests through the AI Gateway, which uses the workspace's AI credit",
365 }
366 }
367}
368
369impl Serialize for Scope {
370 fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
371 serializer.serialize_str(self.as_str())
372 }
373}
374
375impl<'de> Deserialize<'de> for Scope {
376 fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
377 let text = String::deserialize(deserializer)?;
378 Scope::parse(&text).ok_or_else(|| serde::de::Error::custom(format!("unknown scope {text}")))
379 }
380}
381
382/// Scopes as written in a token's row or an OAuth request: separated by
383/// spaces or commas. Unknown names are left out, so a client asking for a
384/// scope from a newer version gets the rest.
385pub fn parse_scopes(text: &str) -> Vec<Scope> {
386 let mut scopes: Vec<Scope> = text
387 .split(|c: char| c.is_whitespace() || c == ',')
388 .filter_map(Scope::parse)
389 .collect();
390 normalize(&mut scopes);
391 scopes
392}
393
394/// In table order, without repeats.
395pub fn normalize(scopes: &mut Vec<Scope>) {
396 let given = std::mem::take(scopes);
397 scopes.extend(Scope::ALL.into_iter().filter(|scope| given.contains(scope)));
398}
399
400/// Space-separated, as stored and as OAuth writes them.
401pub fn scopes_text(scopes: &[Scope]) -> String {
402 scopes.iter().map(|scope| scope.as_str()).collect::<Vec<_>>().join(" ")
403}
404
405/// What a token stores for full access, which is not a scope a client can
406/// ask for by name.
407pub const FULL_ACCESS: &str = "*";
408
409/// Starting points for choosing scopes.
410#[derive(Clone, Copy, Debug, PartialEq, Eq)]
411pub enum Preset {
412 ReadOnly,
413 Agent,
414 Ci,
415 Full,
416}
417
418impl Preset {
419 pub const ALL: [Preset; 4] = [Preset::ReadOnly, Preset::Agent, Preset::Ci, Preset::Full];
420
421 pub fn as_str(self) -> &'static str {
422 match self {
423 Preset::ReadOnly => "read_only",
424 Preset::Agent => "agent",
425 Preset::Ci => "ci",
426 Preset::Full => "full",
427 }
428 }
429
430 pub fn label(self) -> &'static str {
431 match self {
432 Preset::ReadOnly => "Read only",
433 Preset::Agent => "Agent",
434 Preset::Ci => "CI",
435 Preset::Full => "Full access",
436 }
437 }
438
439 /// Its scopes; `None` for full access.
440 pub fn scopes(self) -> Option<Vec<Scope>> {
441 let reads = || Scope::ALL.into_iter().filter(|scope| scope.level() == Level::Read);
442 match self {
443 Preset::ReadOnly => Some(reads().collect()),
444 Preset::Agent => {
445 // Not the machines work runs on: an agent has no business
446 // knowing a workspace's own runners.
447 let mut scopes: Vec<Scope> = reads().filter(|scope| scope.resource() != Resource::Runners).collect();
448 // And answering what needs the person it works for: marking
449 // it done, subscribing, watching.
450 scopes.extend([
451 Scope::CodeWrite,
452 Scope::IssuesWrite,
453 Scope::PullRequestsWrite,
454 Scope::AgentsRun,
455 Scope::MemoryWrite,
456 Scope::NotificationsWrite,
457 ]);
458 normalize(&mut scopes);
459 Some(scopes)
460 }
461 Preset::Ci => Some(vec![
462 Scope::RepoRead,
463 Scope::CodeRead,
464 Scope::CodeWrite,
465 Scope::PackagesRead,
466 Scope::PackagesWrite,
467 Scope::WorkflowsRead,
468 Scope::WorkflowsWrite,
469 Scope::ChecksRead,
470 Scope::ChecksWrite,
471 Scope::DeploymentsRead,
472 Scope::DeploymentsWrite,
473 ]),
474 Preset::Full => None,
475 }
476 }
477}
478
479/// What an OAuth client gets when it asks for nothing in particular: the
480/// agent preset. Never an admin scope.
481pub fn oauth_default() -> Vec<Scope> {
482 Preset::Agent.scopes().unwrap_or_default()
483}
484
485/// Set on a [`crate::User`] resolved from an access token: what the token
486/// may do. Absent on a signed-in session, which may do whatever its person
487/// can.
488#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
489pub struct TokenAccess {
490 /// The token's id, as audit entries and errors name it.
491 #[serde(default)]
492 pub token_id: String,
493 /// Its scopes, as `resource:level`. Absent: full access, everything the
494 /// person (or workspace) can do.
495 #[serde(default, skip_serializing_if = "Option::is_none")]
496 pub scopes: Option<Vec<String>>,
497 /// Made before tokens had scopes: full access until someone narrows it.
498 #[serde(default, skip_serializing_if = "std::ops::Not::not")]
499 pub legacy: bool,
500 /// Set on a workflow job's token (`G1T_TOKEN`): the one repository it
501 /// reaches, as `owner/name`. Every other is refused, whatever its owner
502 /// could reach.
503 #[serde(default, skip_serializing_if = "Option::is_none")]
504 pub repo: Option<String>,
505 /// Set on a workflow job's token: the run and job it was made for. The
506 /// audit log records its changes as that job's, and what it changes
507 /// starts no workflows (only `workflow_dispatch` and
508 /// `repository_dispatch` do), so a workflow cannot set itself off.
509 #[serde(default, skip_serializing_if = "Option::is_none")]
510 pub job: Option<JobToken>,
511 /// The token's name, as its owner gave it, so a log can say which
512 /// token made a request. Absent where whoever resolved it did not say.
513 #[serde(default, skip_serializing_if = "Option::is_none")]
514 pub name: Option<String>,
515}
516
517/// The workflow job a token was made for.
518#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
519pub struct JobToken {
520 /// The run, `run_…`.
521 pub run_id: String,
522 /// The job, `job_…`.
523 pub job_id: String,
524 /// Whether it may open pull requests and approve them, by its
525 /// repository's and workspace's choice ("Allow g1t Actions to create and
526 /// approve pull requests"). Off unless chosen.
527 #[serde(default)]
528 pub pull_requests: bool,
529}
530
531impl TokenAccess {
532 /// Full access to everything: the access tokens made before scopes had.
533 pub fn full() -> Self {
534 TokenAccess::default()
535 }
536
537 /// Whether it may reach the repository `owner/name`: every token but a
538 /// workflow job's, which reaches its own repository only.
539 pub fn reaches(&self, repo: &str) -> bool {
540 self.repo.as_deref().is_none_or(|only| only.eq_ignore_ascii_case(repo))
541 }
542
543 pub fn is_full(&self) -> bool {
544 self.scopes.is_none()
545 }
546
547 /// The scopes it holds, or `None` for full access.
548 pub fn granted(&self) -> Option<Vec<Scope>> {
549 self.scopes
550 .as_ref()
551 .map(|scopes| scopes.iter().filter_map(|scope| Scope::parse(scope)).collect())
552 }
553
554 pub fn allows(&self, needed: Scope) -> bool {
555 match self.granted() {
556 None => true,
557 Some(granted) => granted.iter().any(|held| held.includes(needed)),
558 }
559 }
560}
561
562/// Every operation of the API and MCP server, with the scope it needs. An
563/// operation in [`NO_SCOPE`] needs none. The API checks that every one of
564/// its operations is in exactly one of the two.
565pub const OPERATIONS: &[(&str, Scope)] = &[
566 // Your account.
567 ("list_emails", Scope::AccountRead),
568 ("add_email", Scope::AccountWrite),
569 ("remove_email", Scope::AccountWrite),
570 ("update_email_settings", Scope::AccountWrite),
571 ("list_invites", Scope::AccountRead),
572 ("create_invite", Scope::AccountWrite),
573 ("revoke_invite", Scope::AccountWrite),
574 ("list_my_repo_invitations", Scope::AccountRead),
575 ("accept_repo_invitation", Scope::AccountWrite),
576 ("decline_repo_invitation", Scope::AccountWrite),
577 // Your pinned projects: a preference of your account.
578 ("list_pinned_projects", Scope::AccountRead),
579 ("pin_project", Scope::AccountWrite),
580 // Your stars: a preference of your account.
581 ("list_starred", Scope::AccountRead),
582 ("check_starred", Scope::AccountRead),
583 ("star_repo", Scope::AccountWrite),
584 ("unstar_repo", Scope::AccountWrite),
585 ("unpin_project", Scope::AccountWrite),
586 ("reorder_pinned_projects", Scope::AccountWrite),
587 // Your inbox: notifications, subscriptions and watching.
588 ("list_notifications", Scope::NotificationsRead),
589 ("get_notification_thread", Scope::NotificationsRead),
590 ("get_thread_subscription", Scope::NotificationsRead),
591 ("get_repo_subscription", Scope::NotificationsRead),
592 ("list_watched_repos", Scope::NotificationsRead),
593 ("mark_notifications_read", Scope::NotificationsWrite),
594 ("mark_thread_read", Scope::NotificationsWrite),
595 ("mark_thread_done", Scope::NotificationsWrite),
596 ("save_thread", Scope::NotificationsWrite),
597 ("snooze_thread", Scope::NotificationsWrite),
598 ("set_thread_subscription", Scope::NotificationsWrite),
599 ("delete_thread_subscription", Scope::NotificationsWrite),
600 ("set_repo_subscription", Scope::NotificationsWrite),
601 ("delete_repo_subscription", Scope::NotificationsWrite),
602 // Workspaces, their invites and integrations.
603 ("create_workspace", Scope::WorkspaceAdmin),
604 ("delete_workspace", Scope::WorkspaceAdmin),
605 ("get_workspace", Scope::WorkspaceRead),
606 ("update_workspace", Scope::WorkspaceAdmin),
607 ("list_workspace_invites", Scope::WorkspaceRead),
608 ("invite_member", Scope::WorkspaceAdmin),
609 ("revoke_workspace_invite", Scope::WorkspaceAdmin),
610 ("list_integrations", Scope::WorkspaceRead),
611 ("connect_integration", Scope::WorkspaceAdmin),
612 ("update_integration", Scope::WorkspaceAdmin),
613 ("disconnect_integration", Scope::WorkspaceAdmin),
614 ("test_integration", Scope::WorkspaceAdmin),
615 ("get_model_routes", Scope::WorkspaceRead),
616 ("set_model_routes", Scope::WorkspaceAdmin),
617 // Teams: reading them, and managing them. A team's role on a
618 // repository is who has access.
619 ("list_teams", Scope::WorkspaceRead),
620 ("get_team", Scope::WorkspaceRead),
621 ("list_team_members", Scope::WorkspaceRead),
622 ("list_child_teams", Scope::WorkspaceRead),
623 ("list_team_repos", Scope::WorkspaceRead),
624 ("list_user_teams", Scope::WorkspaceRead),
625 ("create_team", Scope::WorkspaceAdmin),
626 ("list_workspace_rulesets", Scope::WorkspaceRead),
627 ("get_workspace_ruleset", Scope::WorkspaceRead),
628 ("list_workspace_rule_evaluations", Scope::WorkspaceRead),
629 ("create_workspace_ruleset", Scope::WorkspaceAdmin),
630 ("update_workspace_ruleset", Scope::WorkspaceAdmin),
631 ("delete_workspace_ruleset", Scope::WorkspaceAdmin),
632 ("update_team", Scope::WorkspaceAdmin),
633 ("delete_team", Scope::WorkspaceAdmin),
634 ("set_team_member", Scope::WorkspaceAdmin),
635 ("remove_team_member", Scope::WorkspaceAdmin),
636 ("set_team_review_assignment", Scope::WorkspaceAdmin),
637 // A workspace's billing: usage, budget, AI credit and invoices.
638 ("get_usage", Scope::BillingRead),
639 ("get_budget", Scope::BillingRead),
640 ("get_ai_credit", Scope::BillingRead),
641 ("list_invoices", Scope::BillingRead),
642 ("get_billing_details", Scope::BillingRead),
643 ("set_budget", Scope::BillingWrite),
644 ("buy_ai_credit", Scope::BillingWrite),
645 // Repositories.
646 ("list_repos", Scope::RepoRead),
647 ("get_repo", Scope::RepoRead),
648 // Projects follow their repositories.
649 ("list_projects", Scope::RepoRead),
650 ("get_project", Scope::RepoRead),
651 ("search", Scope::RepoRead),
652 ("list_events", Scope::RepoRead),
653 // What the default branch says about a repository, who starred it, and
654 // its releases.
655 ("get_languages", Scope::RepoRead),
656 ("list_contributors", Scope::RepoRead),
657 ("get_license", Scope::RepoRead),
658 ("list_stargazers", Scope::RepoRead),
659 ("list_releases", Scope::RepoRead),
660 ("get_latest_release", Scope::RepoRead),
661 ("get_release_by_tag", Scope::RepoRead),
662 ("get_release", Scope::RepoRead),
663 ("create_release", Scope::RepoWrite),
664 ("update_release", Scope::RepoWrite),
665 ("delete_release", Scope::RepoWrite),
666 ("list_labels", Scope::RepoRead),
667 ("list_milestones", Scope::RepoRead),
668 ("get_milestone", Scope::RepoRead),
669 ("create_label", Scope::IssuesWrite),
670 ("update_label", Scope::IssuesWrite),
671 ("delete_label", Scope::IssuesWrite),
672 ("add_default_labels", Scope::IssuesWrite),
673 ("create_milestone", Scope::IssuesWrite),
674 ("update_milestone", Scope::IssuesWrite),
675 ("delete_milestone", Scope::IssuesWrite),
676 ("get_repo_settings", Scope::RepoRead),
677 ("list_check_names", Scope::RepoRead),
678 ("list_deleted_repos", Scope::RepoRead),
679 ("list_security_alerts", Scope::RepoRead),
680 ("get_codeowners_errors", Scope::RepoRead),
681 ("create_repo", Scope::RepoWrite),
682 ("update_repo", Scope::RepoWrite),
683 ("update_project", Scope::RepoWrite),
684 ("update_repo_settings", Scope::RepoWrite),
685 // Rulesets: reading them is reading the repository; changing them
686 // changes what everyone, agents included, may do, so it is admin.
687 ("list_repo_rulesets", Scope::RepoRead),
688 ("get_repo_ruleset", Scope::RepoRead),
689 ("get_branch_rules", Scope::RepoRead),
690 ("list_rule_evaluations", Scope::RepoRead),
691 ("create_repo_ruleset", Scope::RepoAdmin),
692 ("update_repo_ruleset", Scope::RepoAdmin),
693 ("delete_repo_ruleset", Scope::RepoAdmin),
694 ("rename_branch", Scope::RepoWrite),
695 ("rename_repo", Scope::RepoAdmin),
696 ("transfer_repo", Scope::RepoAdmin),
697 ("archive_repo", Scope::RepoAdmin),
698 ("unarchive_repo", Scope::RepoAdmin),
699 ("set_repo_visibility", Scope::RepoAdmin),
700 ("delete_repo", Scope::RepoAdmin),
701 ("restore_repo", Scope::RepoAdmin),
702 ("purge_repo", Scope::RepoAdmin),
703 // A dismissed secret is let through push protection.
704 ("dismiss_security_alert", Scope::RepoAdmin),
705 ("reopen_security_alert", Scope::RepoAdmin),
706 // The security suite: alerts, push protection, patterns, code
707 // scanning, the supply chain and settings.
708 ("list_secret_scanning_alerts", Scope::SecurityRead),
709 ("get_secret_scanning_alert", Scope::SecurityRead),
710 ("list_secret_scanning_locations", Scope::SecurityRead),
711 ("list_bypass_requests", Scope::SecurityRead),
712 ("list_custom_patterns", Scope::SecurityRead),
713 ("list_code_scanning_alerts", Scope::SecurityRead),
714 ("get_code_scanning_alert", Scope::SecurityRead),
715 ("list_code_scanning_analyses", Scope::SecurityRead),
716 ("get_sarif_upload", Scope::SecurityRead),
717 ("list_vulnerability_alerts", Scope::SecurityRead),
718 ("get_vulnerability_alert", Scope::SecurityRead),
719 ("get_dependency_graph", Scope::SecurityRead),
720 ("get_sbom", Scope::SecurityRead),
721 ("compare_dependencies", Scope::SecurityRead),
722 ("get_security_settings", Scope::SecurityRead),
723 ("get_workspace_security_settings", Scope::SecurityRead),
724 ("get_security_overview", Scope::SecurityRead),
725 ("update_secret_scanning_alert", Scope::SecurityWrite),
726 ("bypass_push_protection", Scope::SecurityWrite),
727 ("check_secret_validity", Scope::SecurityWrite),
728 ("review_bypass_request", Scope::SecurityWrite),
729 ("create_custom_pattern", Scope::SecurityWrite),
730 ("update_custom_pattern", Scope::SecurityWrite),
731 ("delete_custom_pattern", Scope::SecurityWrite),
732 ("dry_run_custom_pattern", Scope::SecurityWrite),
733 ("update_code_scanning_alert", Scope::SecurityWrite),
734 ("upload_sarif", Scope::SecurityWrite),
735 ("update_vulnerability_alert", Scope::SecurityWrite),
736 ("fix_security_alert", Scope::SecurityWrite),
737 ("update_security_settings", Scope::SecurityWrite),
738 ("update_workspace_security_settings", Scope::SecurityWrite),
739 // Issues and plans.
740 ("list_issues", Scope::IssuesRead),
741 ("get_issue", Scope::IssuesRead),
742 ("get_plan", Scope::IssuesRead),
743 ("create_issue", Scope::IssuesWrite),
744 ("update_issue", Scope::IssuesWrite),
745 ("list_issue_labels", Scope::IssuesRead),
746 ("add_issue_labels", Scope::IssuesWrite),
747 ("set_issue_labels", Scope::IssuesWrite),
748 ("remove_issue_labels", Scope::IssuesWrite),
749 ("close_issue", Scope::IssuesWrite),
750 ("reopen_issue", Scope::IssuesWrite),
751 ("add_comment", Scope::IssuesWrite),
752 ("import_issue", Scope::IssuesWrite),
753 ("apply_plan", Scope::IssuesWrite),
754 // Pull requests.
755 ("list_pull_requests", Scope::PullRequestsRead),
756 ("get_pull_request", Scope::PullRequestsRead),
757 ("get_pull_request_changes", Scope::PullRequestsRead),
758 ("read_session", Scope::PullRequestsRead),
759 ("get_merge_queue", Scope::PullRequestsRead),
760 ("create_pull_request", Scope::PullRequestsWrite),
761 ("update_pull_request", Scope::PullRequestsWrite),
762 ("record_session", Scope::PullRequestsWrite),
763 ("mark_pull_request_ready", Scope::PullRequestsWrite),
764 ("close_pull_request", Scope::PullRequestsWrite),
765 ("review_pull_request", Scope::PullRequestsWrite),
766 ("merge_pull_request", Scope::PullRequestsWrite),
767 ("request_reviewers", Scope::PullRequestsWrite),
768 ("remove_requested_reviewers", Scope::PullRequestsWrite),
769 // g1t's agents.
770 ("assign_issue", Scope::AgentsRun),
771 ("delegate", Scope::AgentsRun),
772 ("plan_work", Scope::AgentsRun),
773 ("message_agent", Scope::AgentsRun),
774 ("answer_message", Scope::AgentsRun),
775 ("take_messages", Scope::AgentsRun),
776 // Workflows.
777 ("list_workflows", Scope::WorkflowsRead),
778 ("list_workflow_runs", Scope::WorkflowsRead),
779 ("get_workflow_run", Scope::WorkflowsRead),
780 ("get_job_logs", Scope::WorkflowsRead),
781 ("dispatch_workflow", Scope::WorkflowsWrite),
782 ("cancel_workflow_run", Scope::WorkflowsWrite),
783 ("rerun_workflow_run", Scope::WorkflowsWrite),
784 ("update_workflow", Scope::WorkflowsWrite),
785 ("list_artifacts", Scope::WorkflowsRead),
786 ("list_workflow_run_artifacts", Scope::WorkflowsRead),
787 ("get_artifact", Scope::WorkflowsRead),
788 ("download_artifact", Scope::WorkflowsRead),
789 ("get_artifact_retention", Scope::WorkflowsRead),
790 ("delete_artifact", Scope::WorkflowsWrite),
791 ("set_artifact_retention", Scope::WorkflowsWrite),
792 // Checks: statuses, check runs and check suites on commits.
793 ("list_commit_statuses", Scope::ChecksRead),
794 ("get_combined_status", Scope::ChecksRead),
795 ("list_check_runs_for_ref", Scope::ChecksRead),
796 ("get_check_run", Scope::ChecksRead),
797 ("list_check_run_annotations", Scope::ChecksRead),
798 ("list_check_suites_for_ref", Scope::ChecksRead),
799 ("get_check_suite", Scope::ChecksRead),
800 ("create_commit_status", Scope::ChecksWrite),
801 ("create_check_run", Scope::ChecksWrite),
802 ("update_check_run", Scope::ChecksWrite),
803 ("rerequest_check_run", Scope::ChecksWrite),
804 ("rerequest_check_suite", Scope::ChecksWrite),
805 // Deployments, wherever they run: reading them, and reporting them.
806 ("list_deployments", Scope::DeploymentsRead),
807 ("get_deployment", Scope::DeploymentsRead),
808 ("list_deployment_statuses", Scope::DeploymentsRead),
809 ("list_environments", Scope::DeploymentsRead),
810 ("get_environment", Scope::DeploymentsRead),
811 ("create_deployment", Scope::DeploymentsWrite),
812 ("create_deployment_status", Scope::DeploymentsWrite),
813 // What keeps runs safe: the runs environments hold and reviewing them,
814 // approving a pull request's run, and a repository's own rules for
815 // its environments and tokens, which are an admin's.
816 ("get_pending_deployments", Scope::WorkflowsRead),
817 ("review_pending_deployments", Scope::WorkflowsWrite),
818 ("approve_workflow_run", Scope::WorkflowsWrite),
819 ("get_workflow_permissions", Scope::RepoRead),
820 ("get_fork_pr_approval", Scope::RepoRead),
821 ("update_environment", Scope::RepoAdmin),
822 ("delete_environment", Scope::RepoAdmin),
823 ("set_workflow_permissions", Scope::RepoAdmin),
824 ("set_fork_pr_approval", Scope::RepoAdmin),
825 // Starting workflows from outside, as a push would.
826 ("create_repository_dispatch", Scope::CodeWrite),
827 // A workspace's policy for its repositories' tokens.
828 ("get_workspace_workflow_permissions", Scope::WorkspaceRead),
829 ("set_workspace_workflow_permissions", Scope::WorkspaceAdmin),
830 // Memory and the context hub.
831 ("recall", Scope::MemoryRead),
832 ("search_context", Scope::MemoryRead),
833 ("get_entity", Scope::MemoryRead),
834 ("get_context", Scope::MemoryRead),
835 ("remember", Scope::MemoryWrite),
836 // Who has access.
837 ("list_collaborators", Scope::AccessRead),
838 ("get_collaborator_permission", Scope::AccessRead),
839 ("list_repo_invitations", Scope::AccessRead),
840 ("list_outside_collaborators", Scope::AccessRead),
841 ("add_collaborator", Scope::AccessAdmin),
842 ("update_collaborator", Scope::AccessAdmin),
843 ("remove_collaborator", Scope::AccessAdmin),
844 ("revoke_repo_invitation", Scope::AccessAdmin),
845 ("set_base_permission", Scope::AccessAdmin),
846 ("set_team_repo", Scope::AccessAdmin),
847 ("remove_team_repo", Scope::AccessAdmin),
848 // Webhooks.
849 ("list_webhooks", Scope::WebhooksRead),
850 ("list_webhook_deliveries", Scope::WebhooksRead),
851 ("create_webhook", Scope::WebhooksAdmin),
852 ("update_webhook", Scope::WebhooksAdmin),
853 ("delete_webhook", Scope::WebhooksAdmin),
854 ("ping_webhook", Scope::WebhooksAdmin),
855 ("redeliver_webhook", Scope::WebhooksAdmin),
856 // Secrets and variables.
857 ("list_actions_secrets", Scope::SecretsRead),
858 ("list_actions_variables", Scope::SecretsRead),
859 ("set_actions_secret", Scope::SecretsAdmin),
860 ("delete_actions_secret", Scope::SecretsAdmin),
861 ("set_actions_variable", Scope::SecretsAdmin),
862 ("delete_actions_variable", Scope::SecretsAdmin),
863 // Self-hosted runners.
864 ("list_runners", Scope::RunnersRead),
865 ("list_runner_groups", Scope::RunnersRead),
866 ("get_runner_settings", Scope::RunnersRead),
867 ("create_runner_registration_token", Scope::RunnersAdmin),
868 ("remove_runner", Scope::RunnersAdmin),
869 ("create_runner_group", Scope::RunnersAdmin),
870 ("update_runner_group", Scope::RunnersAdmin),
871 ("delete_runner_group", Scope::RunnersAdmin),
872 ("update_runner_settings", Scope::RunnersAdmin),
873 // The AI Gateway. Sending a request to a model needs `models:write`,
874 // checked by the model proxy at models.g1t.sh, not here.
875 ("list_gateway_requests", Scope::ModelsRead),
876];
877
878/// Operations any token may use: saying who it is.
879pub const NO_SCOPE: &[&str] = &["whoami"];
880
881/// The scope `operation` needs. `None` for one in [`NO_SCOPE`]; an
882/// operation in neither list needs full access.
883pub fn scope_for(operation: &str) -> Option<Scope> {
884 OPERATIONS
885 .iter()
886 .find(|(name, _)| *name == operation)
887 .map(|(_, scope)| *scope)
888}
889
890/// What a token needs for `operation` with this input beyond its own
891/// scope: starting agents from an operation that can, and making a
892/// repository public or private.
893pub fn extra_scopes(operation: &str, input: &serde_json::Value) -> Vec<Scope> {
894 let mut extra = Vec::new();
895 let assigns = input["assign"].as_bool() == Some(true)
896 || input["agent"].as_bool() == Some(true)
897 || input["assign_agent"].as_bool() == Some(true);
898 if assigns && matches!(operation, "apply_plan" | "import_issue" | "create_issue") {
899 extra.push(Scope::AgentsRun);
900 }
901 // Fixing an alert opens an issue and puts g1t on it.
902 if operation == "fix_security_alert" {
903 extra.extend([Scope::IssuesWrite, Scope::AgentsRun]);
904 }
905 // Opening the issue an agent is put on.
906 if operation == "delegate" {
907 extra.push(Scope::IssuesWrite);
908 }
909 // A workspace's base permission is who has access.
910 if operation == "update_workspace" && input.get("base_permission").is_some_and(|v| !v.is_null()) {
911 extra.push(Scope::AccessAdmin);
912 }
913 // Asking a g1t Actions job or run to run again reruns its workflow.
914 if matches!(operation, "rerequest_check_run" | "rerequest_check_suite")
915 && input["id"].as_str().is_some_and(|id| id.starts_with("job_") || id.starts_with("run_"))
916 {
917 extra.push(Scope::WorkflowsWrite);
918 }
919 if operation == "update_repo" && (input.get("private").is_some_and(|v| !v.is_null()) || input.get("default_branch").is_some_and(|v| !v.is_null())) {
920 extra.push(Scope::RepoAdmin);
921 }
922 extra
923}
924
925/// The scopes a call needs, its own first.
926pub fn needed(operation: &str, input: &serde_json::Value) -> Vec<Scope> {
927 scope_for(operation)
928 .into_iter()
929 .chain(extra_scopes(operation, input))
930 .collect()
931}
932
933/// Whether `access` may use `operation` with `input`. The person's (or
934/// workspace's) role is checked after this, by the service that owns what
935/// was asked about.
936pub fn decide(access: &TokenAccess, operation: &str, input: &serde_json::Value) -> Decision {
937 let rule = if access.legacy { "token:legacy" } else { "token:scope" };
938 // A workflow job may open or approve pull requests only where its
939 // repository and workspace let it, as on GitHub.
940 if let Some(job) = &access.job
941 && !job.pull_requests
942 && (operation == "create_pull_request" || (operation == "review_pull_request" && input["verdict"].as_str() == Some("approve")))
943 {
944 return Decision::deny(
945 "token:pull-requests",
946 "A workflow job cannot open or approve pull requests here: an admin can allow it under Settings, Actions.",
947 );
948 }
949 if let Some(only) = access.repo.as_deref()
950 && !NO_SCOPE.contains(&operation)
951 {
952 match input["repo"].as_str() {
953 Some(repo) if access.reaches(repo) => {}
954 Some(repo) => {
955 return Decision::deny("token:repository", format!("This token is a workflow job's in {only}: it cannot reach {repo}."));
956 }
957 None => {
958 return Decision::deny("token:repository", format!("This token is a workflow job's: it reaches only {only}, and {operation} is not about one repository."));
959 }
960 }
961 }
962 if access.scopes.is_some() {
963 let known = NO_SCOPE.contains(&operation) || scope_for(operation).is_some();
964 if !known {
965 return Decision::deny("token:scope", format!("This access token cannot use {operation}: it needs full access."));
966 }
967 if let Some(missing) = needed(operation, input).into_iter().find(|scope| !access.allows(*scope)) {
968 return Decision::deny(
969 "token:scope",
970 format!("This access token needs the {} scope to use {operation}.", missing.as_str()),
971 );
972 }
973 }
974 Decision::allow(rule)
975}
976
977/// Whether a token may use the repository `owner/name` at all: a refusal
978/// for a workflow job's token in another repository, else `None`. Git and
979/// the package registries ask this before [`decide_git`] and
980/// [`decide_packages`].
981pub fn decide_repo(access: &TokenAccess, repo: &str) -> Option<Decision> {
982 let only = access.repo.as_deref()?;
983 (!access.reaches(repo)).then(|| Decision::deny("token:repository", format!("This token is a workflow job's in {only}: it cannot reach {repo}.")))
984}
985
986/// Whether a token may clone or fetch (`write` false), or push to (`write`
987/// true), a repository with git. `public` is whether anyone may read it,
988/// which needs no scope.
989pub fn decide_git(access: &TokenAccess, write: bool, public: bool) -> Decision {
990 let needed = if write { Scope::CodeWrite } else { Scope::CodeRead };
991 if !access.allows(needed) && (write || !public) {
992 return Decision::deny(
993 "token:scope",
994 format!("This access token needs the {} scope to {} with git.", needed.as_str(), if write { "push" } else { "clone or fetch a private repository" }),
995 );
996 }
997 Decision::allow(if access.legacy { "token:legacy" } else { "token:scope" })
998}
999
1000/// Whether a token may pull (`Level::Read`), push or publish
1001/// (`Level::Write`), or delete (`Level::Delete`) packages. `public` is
1002/// whether anyone may pull the package, which needs no scope.
1003pub fn decide_packages(access: &TokenAccess, level: Level, public: bool) -> Decision {
1004 let (needed, doing) = match level {
1005 Level::Read => (Scope::PackagesRead, "pull a private package"),
1006 Level::Delete | Level::Admin => (Scope::PackagesDelete, "delete packages"),
1007 Level::Write | Level::Run => (Scope::PackagesWrite, "push or publish packages"),
1008 };
1009 if !access.allows(needed) && !(level == Level::Read && public) {
1010 return Decision::deny(
1011 "token:scope",
1012 format!("This access token needs the {} scope to {doing}.", needed.as_str()),
1013 );
1014 }
1015 Decision::allow(if access.legacy { "token:legacy" } else { "token:scope" })
1016}
1017
1018#[cfg(test)]
1019mod tests {
1020 use super::*;
1021 use serde_json::json;
1022
1023 fn token(scopes: &[Scope]) -> TokenAccess {
1024 TokenAccess {
1025 token_id: "tok_1".to_owned(),
1026 scopes: Some(scopes.iter().map(|scope| scope.as_str().to_owned()).collect()),
1027 legacy: false,
1028 name: None,
1029 ..TokenAccess::default()
1030 }
1031 }
1032
1033 #[test]
1034 fn every_scope_reads_back_and_belongs_to_a_resource() {
1035 for scope in Scope::ALL {
1036 assert_eq!(Scope::parse(scope.as_str()), Some(scope));
1037 assert!(scope.as_str().starts_with(scope.resource().as_str()));
1038 assert!(scope.includes(scope));
1039 }
1040 assert_eq!(Scope::parse(" Issues:Write "), Some(Scope::IssuesWrite));
1041 assert_eq!(Scope::parse("issues"), None);
1042 }
1043
1044 #[test]
1045 fn a_higher_level_includes_the_lower_ones_of_its_resource_only() {
1046 assert!(Scope::RepoAdmin.includes(Scope::RepoRead));
1047 assert!(Scope::RepoAdmin.includes(Scope::RepoWrite));
1048 assert!(Scope::IssuesWrite.includes(Scope::IssuesRead));
1049 assert!(!Scope::IssuesRead.includes(Scope::IssuesWrite));
1050 assert!(!Scope::RepoAdmin.includes(Scope::CodeWrite));
1051 assert!(!Scope::PullRequestsWrite.includes(Scope::IssuesWrite));
1052 }
1053
1054 #[test]
1055 fn operations_are_listed_once_and_never_also_free() {
1056 let mut seen = std::collections::HashSet::new();
1057 for (name, _) in OPERATIONS {
1058 assert!(seen.insert(*name), "{name} twice");
1059 assert!(!NO_SCOPE.contains(name), "{name}");
1060 }
1061 }
1062
1063 #[test]
1064 fn scopes_are_parsed_from_oauth_text_leaving_out_unknown_ones() {
1065 assert_eq!(
1066 parse_scopes("issues:write repo:read,bogus:thing issues:write"),
1067 vec![Scope::RepoRead, Scope::IssuesWrite]
1068 );
1069 assert_eq!(scopes_text(&[Scope::RepoRead, Scope::IssuesWrite]), "repo:read issues:write");
1070 }
1071
1072 #[test]
1073 fn the_oauth_default_is_the_agent_preset_and_never_admin() {
1074 let scopes = oauth_default();
1075 assert!(scopes.contains(&Scope::IssuesWrite));
1076 assert!(scopes.contains(&Scope::PullRequestsWrite));
1077 assert!(scopes.contains(&Scope::AgentsRun));
1078 assert!(scopes.iter().all(|scope| !scope.dangerous()), "{scopes:?}");
1079 for read in Scope::ALL.into_iter().filter(|scope| scope.level() == Level::Read) {
1080 // Every read but the machines work runs on.
1081 assert_eq!(scopes.contains(&read), read != Scope::RunnersRead, "{read:?}");
1082 }
1083 assert!(Preset::ReadOnly.scopes().unwrap().iter().all(|scope| scope.level() == Level::Read));
1084 assert_eq!(Preset::Full.scopes(), None);
1085 }
1086
1087 #[test]
1088 fn billing_is_read_by_presets_and_changed_by_none_but_full_access() {
1089 assert!(Preset::ReadOnly.scopes().unwrap().contains(&Scope::BillingRead));
1090 for preset in [Preset::ReadOnly, Preset::Agent, Preset::Ci] {
1091 assert!(!preset.scopes().unwrap().contains(&Scope::BillingWrite), "{}", preset.as_str());
1092 }
1093 assert_eq!(scope_for("set_budget"), Some(Scope::BillingWrite));
1094 assert_eq!(scope_for("buy_ai_credit"), Some(Scope::BillingWrite));
1095 assert_eq!(scope_for("get_usage"), Some(Scope::BillingRead));
1096 let reader = token(&[Scope::BillingRead]);
1097 assert!(decide(&reader, "list_invoices", &json!({})).allowed);
1098 assert!(decide(&reader, "set_budget", &json!({})).reason.unwrap().contains("billing:write"));
1099 }
1100
1101 #[test]
1102 fn the_ai_gateway_spends_only_with_models_write_which_no_preset_gives() {
1103 // Reading the log is a read like any other.
1104 assert_eq!(scope_for("list_gateway_requests"), Some(Scope::ModelsRead));
1105 assert!(Preset::ReadOnly.scopes().unwrap().contains(&Scope::ModelsRead));
1106 // Sending requests spends the workspace's AI credit: chosen on purpose.
1107 for preset in [Preset::ReadOnly, Preset::Agent, Preset::Ci] {
1108 assert!(!preset.scopes().unwrap().contains(&Scope::ModelsWrite), "{}", preset.as_str());
1109 }
1110 assert!(Scope::ModelsWrite.includes(Scope::ModelsRead));
1111 assert!(!Scope::ModelsWrite.dangerous());
1112 assert!(token(&[Scope::ModelsWrite]).allows(Scope::ModelsWrite));
1113 assert!(!token(&[Scope::BillingWrite]).allows(Scope::ModelsWrite));
1114 assert!(TokenAccess::full().allows(Scope::ModelsWrite));
1115 }
1116
1117 #[test]
1118 fn checks_are_reported_with_checks_write_which_ci_gets() {
1119 assert_eq!(scope_for("create_check_run"), Some(Scope::ChecksWrite));
1120 assert_eq!(scope_for("create_commit_status"), Some(Scope::ChecksWrite));
1121 assert_eq!(scope_for("list_check_runs_for_ref"), Some(Scope::ChecksRead));
1122 let ci = Preset::Ci.scopes().unwrap();
1123 assert!(ci.contains(&Scope::ChecksWrite));
1124 assert!(!Preset::Agent.scopes().unwrap().contains(&Scope::ChecksWrite));
1125 let reporter = token(&[Scope::ChecksWrite]);
1126 assert!(decide(&reporter, "update_check_run", &json!({ "id": "cr_1" })).allowed);
1127 assert!(decide(&reporter, "rerequest_check_run", &json!({ "id": "cr_1" })).allowed);
1128 // A g1t Actions job runs again as its workflow does.
1129 let refused = decide(&reporter, "rerequest_check_run", &json!({ "id": "job_1" }));
1130 assert!(refused.reason.unwrap().contains("workflows:write"));
1131 }
1132
1133 #[test]
1134 fn a_job_token_reaches_its_repository_only() {
1135 let job = TokenAccess {
1136 repo: Some("acme/web".into()),
1137 job: Some(JobToken { run_id: "run_1".into(), job_id: "job_1".into(), pull_requests: false }),
1138 ..token(&[Scope::RepoRead, Scope::IssuesWrite, Scope::IssuesRead, Scope::PullRequestsWrite])
1139 };
1140 assert!(decide(&job, "create_issue", &json!({ "repo": "acme/web" })).allowed);
1141 assert!(decide(&job, "create_issue", &json!({ "repo": "Acme/Web" })).allowed, "names compare without case");
1142 let elsewhere = decide(&job, "create_issue", &json!({ "repo": "acme/api" }));
1143 assert!(!elsewhere.allowed);
1144 assert_eq!(elsewhere.rule, "token:repository");
1145 // Nothing beyond the one repository, a workspace's listing included.
1146 assert!(!decide(&job, "list_repos", &json!({})).allowed);
1147 assert!(decide(&job, "whoami", &json!({})).allowed);
1148 // Its scopes still hold inside it.
1149 assert!(!decide(&job, "create_pull_request", &json!({ "repo": "acme/web" })).allowed);
1150 assert!(decide_repo(&job, "acme/web").is_none());
1151 assert!(!decide_repo(&job, "acme/api").unwrap().allowed);
1152 assert!(decide_repo(&token(&[Scope::CodeRead]), "acme/api").is_none(), "other tokens reach what their owner can");
1153 // Opening and approving pull requests is off unless allowed.
1154 assert_eq!(decide(&job, "create_pull_request", &json!({ "repo": "acme/web" })).rule, "token:pull-requests");
1155 assert!(!decide(&job, "review_pull_request", &json!({ "repo": "acme/web", "verdict": "approve" })).allowed);
1156 assert!(decide(&job, "review_pull_request", &json!({ "repo": "acme/web", "verdict": "request_changes" })).allowed);
1157 let allowed = TokenAccess { job: Some(JobToken { pull_requests: true, ..job.job.clone().unwrap() }), ..job.clone() };
1158 assert!(decide(&allowed, "create_pull_request", &json!({ "repo": "acme/web" })).allowed);
1159 }
1160
1161 #[test]
1162 fn a_legacy_token_can_do_everything() {
1163 let legacy = TokenAccess { legacy: true, ..TokenAccess::full() };
1164 for (operation, _) in OPERATIONS {
1165 assert!(decide(&legacy, operation, &json!({})).allowed, "{operation}");
1166 }
1167 assert_eq!(decide(&legacy, "delete_repo", &json!({})).rule, "token:legacy");
1168 }
1169
1170 #[test]
1171 fn a_missing_scope_is_named() {
1172 let read = token(&[Scope::IssuesRead]);
1173 assert!(decide(&read, "get_issue", &json!({})).allowed);
1174 assert!(decide(&read, "whoami", &json!({})).allowed);
1175 let refused = decide(&read, "create_issue", &json!({}));
1176 assert!(!refused.allowed);
1177 assert_eq!(refused.reason.as_deref(), Some("This access token needs the issues:write scope to use create_issue."));
1178 // An operation the table does not know needs full access.
1179 assert!(!decide(&read, "something_new", &json!({})).allowed);
1180 }
1181
1182 #[test]
1183 fn starting_agents_from_another_operation_needs_agents_run() {
1184 let writer = token(&[Scope::IssuesWrite]);
1185 assert!(decide(&writer, "apply_plan", &json!({})).allowed);
1186 let refused = decide(&writer, "apply_plan", &json!({ "assign": true }));
1187 assert!(refused.reason.unwrap().contains("agents:run"));
1188 let maintainer = token(&[Scope::RepoWrite]);
1189 assert!(decide(&maintainer, "update_repo", &json!({ "description": "x" })).allowed);
1190 assert!(!decide(&maintainer, "update_repo", &json!({ "private": true })).allowed);
1191 }
1192
1193 #[test]
1194 fn a_workspaces_base_permission_needs_access_admin_too() {
1195 let admin = token(&[Scope::WorkspaceAdmin]);
1196 assert!(decide(&admin, "update_workspace", &json!({ "name": "Acme" })).allowed);
1197 let refused = decide(&admin, "update_workspace", &json!({ "name": "Acme", "base_permission": "read" }));
1198 assert!(refused.reason.unwrap().contains("access:admin"));
1199 let both = token(&[Scope::WorkspaceAdmin, Scope::AccessAdmin]);
1200 assert!(decide(&both, "update_workspace", &json!({ "base_permission": "read" })).allowed);
1201 assert!(!decide(&token(&[Scope::WorkspaceRead]), "update_workspace", &json!({ "name": "Acme" })).allowed);
1202 }
1203
1204 #[test]
1205 fn delegating_needs_both_agents_and_issues() {
1206 let agents = token(&[Scope::AgentsRun]);
1207 assert!(decide(&agents, "delegate", &json!({})).reason.unwrap().contains("issues:write"));
1208 let both = token(&[Scope::AgentsRun, Scope::IssuesWrite]);
1209 assert!(decide(&both, "delegate", &json!({})).allowed);
1210 }
1211
1212 #[test]
1213 fn git_push_needs_code_write_and_private_reads_need_code_read() {
1214 let reader = token(&[Scope::CodeRead]);
1215 assert!(decide_git(&reader, false, false).allowed);
1216 let refused = decide_git(&reader, true, false);
1217 assert!(!refused.allowed);
1218 assert!(refused.reason.unwrap().contains("code:write"));
1219 let issues = token(&[Scope::IssuesWrite]);
1220 assert!(!decide_git(&issues, false, false).allowed);
1221 assert!(decide_git(&issues, false, true).allowed, "public code needs no scope");
1222 assert!(!decide_git(&issues, true, true).allowed, "pushing to public code still needs code:write");
1223 let writer = token(&[Scope::CodeWrite]);
1224 assert!(decide_git(&writer, true, false).allowed);
1225 assert!(decide_git(&writer, false, false).allowed, "code:write includes code:read");
1226 assert!(decide_git(&TokenAccess::full(), true, false).allowed);
1227 }
1228
1229 #[test]
1230 fn packages_need_their_own_scopes_and_public_pulls_none() {
1231 let reader = token(&[Scope::PackagesRead]);
1232 assert!(decide_packages(&reader, Level::Read, false).allowed);
1233 assert!(!decide_packages(&reader, Level::Write, false).allowed);
1234 let code = token(&[Scope::CodeWrite]);
1235 assert!(!decide_packages(&code, Level::Read, false).allowed, "code scopes are not package scopes");
1236 assert!(decide_packages(&code, Level::Read, true).allowed, "public packages pull with any token");
1237 let writer = token(&[Scope::PackagesWrite]);
1238 assert!(decide_packages(&writer, Level::Write, false).allowed);
1239 assert!(decide_packages(&writer, Level::Read, false).allowed, "packages:write includes packages:read");
1240 let refused = decide_packages(&writer, Level::Delete, false);
1241 assert!(refused.reason.unwrap().contains("packages:delete"));
1242 assert!(decide_packages(&token(&[Scope::PackagesDelete]), Level::Write, false).allowed);
1243 assert!(Scope::PackagesDelete.dangerous());
1244 // Tokens made before these scopes, and full-access ones, keep working.
1245 let legacy = TokenAccess { legacy: true, ..TokenAccess::full() };
1246 assert!(decide_packages(&legacy, Level::Delete, false).allowed);
1247 assert!(decide_packages(&TokenAccess::full(), Level::Write, false).allowed);
1248 }
1249
1250 #[test]
1251 fn token_access_travels_as_json() {
1252 let access = token(&[Scope::IssuesRead]);
1253 let wire = serde_json::to_value(&access).unwrap();
1254 assert_eq!(wire["scopes"], json!(["issues:read"]));
1255 assert!(wire.get("resources").is_none());
1256 let back: TokenAccess = serde_json::from_value(wire).unwrap();
1257 assert_eq!(back, access);
1258 let full: TokenAccess = serde_json::from_value(json!({})).unwrap();
1259 assert!(full.is_full());
1260 // A reach written by an older version is ignored: a token reaches
1261 // whatever its owner can.
1262 let older: TokenAccess = serde_json::from_value(json!({
1263 "token_id": "tok_1",
1264 "scopes": ["issues:read"],
1265 "resources": { "kind": "repositories", "repositories": ["acme/rocket"] },
1266 }))
1267 .unwrap();
1268 assert_eq!(older, access);
1269 }
1270
1271 /// The site's copy of the table, `packages/contracts/src/scopes.ts`,
1272 /// lists the same scopes in the same order, the same operations with
1273 /// the same scopes, and the same presets.
1274 #[test]
1275 fn the_typescript_mirror_has_the_same_table() {
1276 let ts = include_str!("../../../packages/contracts/src/scopes.ts");
1277 let section = |start: &str| {
1278 ts.split_once(start)
1279 .and_then(|(_, rest)| rest.split_once("] as const"))
1280 .map(|(table, _)| table)
1281 .unwrap_or_else(|| panic!("{start} in scopes.ts"))
1282 };
1283 let scopes: Vec<&str> = section("export const SCOPES = [")
1284 .lines()
1285 .filter_map(|line| line.split_once("scope: \"").and_then(|(_, rest)| rest.split_once('"')).map(|(scope, _)| scope))
1286 .collect();
1287 let expected: Vec<&str> = Scope::ALL.iter().map(|scope| scope.as_str()).collect();
1288 assert_eq!(scopes, expected);
1289 let operations: Vec<(String, String)> = section("export const OPERATION_SCOPES = [")
1290 .lines()
1291 .filter_map(|line| {
1292 let mut quoted = line.split('"').skip(1).step_by(2);
1293 Some((quoted.next()?.to_owned(), quoted.next()?.to_owned()))
1294 })
1295 .collect();
1296 let expected: Vec<(String, String)> = OPERATIONS
1297 .iter()
1298 .map(|(name, scope)| ((*name).to_owned(), scope.as_str().to_owned()))
1299 .collect();
1300 assert_eq!(operations, expected);
1301 for preset in Preset::ALL {
1302 let list = section(&format!("{}: [", preset.as_str()));
1303 let mirrored: Vec<&str> = list
1304 .split(',')
1305 .map(|item| item.trim().trim_matches('"'))
1306 .filter(|item| !item.is_empty())
1307 .collect();
1308 let expected: Vec<&str> = preset
1309 .scopes()
1310 .map(|scopes| scopes.iter().map(|scope| scope.as_str()).collect())
1311 .unwrap_or_else(|| vec!["*"]);
1312 assert_eq!(mirrored, expected, "{}", preset.as_str());
1313 }
1314 }
1315}