flagon-io/g1t

public

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