flagon-io/g1t

public

Where people and agents ship software together. The open-source git platform for the whole job: issues, agents, checks and deploys to the edge.

g1t.sh

git agents cloudflare rust forge mcp

1,678 linesCode BlameRaw

1	//! The identity service: accounts, credentials and sessions.
2	//!
3	//! Each `*Args` struct is the argument of the method of the same name,
4	//! served at `POST /rpc/<method>`.
5
6	use serde::{Deserialize, Serialize};
7
8	use crate::User;
9
10	#[derive(Clone, Debug, Serialize, Deserialize)]
11	#[serde(rename_all = "camelCase")]
12	pub struct SshKey {
13	pub id: String,
14	pub title: String,
15	pub fingerprint: String,
16	/// RFC 3339.
17	pub created_at: String,
18	/// When it was last used to sign in over SSH, RFC 3339, to within 5
19	/// minutes; null when it never was.
20	#[serde(default)]
21	pub last_used_at: Option<String>,
22	}
23
24	#[derive(Clone, Debug, Default, Serialize, Deserialize)]
25	#[serde(rename_all = "camelCase")]
26	pub struct AccessToken {
27	pub id: String,
28	pub name: String,
29	/// RFC 3339.
30	pub created_at: String,
31	/// RFC 3339, to within a few minutes. Null until it is first used.
32	pub last_used_at: Option<String>,
33	/// For a workspace's token, the username of the member who made it.
34	/// Null once that account is gone, and on personal tokens.
35	pub created_by: Option<String>,
36	/// Its scopes, as `resource:level`, the highest of each resource.
37	/// Null: full access (an application's or an agent's credential).
38	#[serde(default)]
39	pub scopes: Option<Vec<String>>,
40	/// Made before tokens had scopes: full access until someone narrows it.
41	#[serde(default)]
42	pub legacy: bool,
43	/// RFC 3339. Null: it does not expire.
44	#[serde(default)]
45	pub expires_at: Option<String>,
46	/// Its scopes as permissions: each resource it may use, by name, at
47	/// the highest level, such as `{"issues": "write"}`. Every resource at
48	/// its highest when `scopes` is null.
49	#[serde(default)]
50	pub permissions: std::collections::BTreeMap<String, String>,
51	/// What it is for, as its owner wrote it.
52	#[serde(default, skip_serializing_if = "Option::is_none")]
53	pub description: Option<String>,
54	/// A personal token's reach: the workspace it is made for, by slug;
55	/// null for every workspace its owner belongs to (or, with
56	/// `repository_selection` public, none). Null on a workspace's own
57	/// token, which reaches its workspace.
58	#[serde(default)]
59	pub workspace: Option<String>,
60	/// Which repositories of that workspace it reaches.
61	#[serde(default)]
62	pub repository_selection: crate::scopes::RepositorySelection,
63	/// With `selected`: the repositories, as `owner/name`, that the viewer
64	/// can see.
65	#[serde(default)]
66	pub repositories: Vec<String>,
67	/// Whether a token made for a workspace that approves tokens may be
68	/// used there yet.
69	#[serde(default)]
70	pub status: crate::tokens::TokenStatus,
71	/// Why an owner denied or revoked it.
72	#[serde(default, skip_serializing_if = "Option::is_none")]
73	pub review_reason: Option<String>,
74	/// Whether it is a workspace's own token, acting as the workspace.
75	#[serde(default, skip_serializing_if = "std::ops::Not::not")]
76	pub workspace_owned: bool,
77	/// A workspace's own token with Repositories: admin, which acts as an
78	/// admin of the workspace's repositories rather than with Write.
79	#[serde(default, skip_serializing_if = "std::ops::Not::not")]
80	pub admin: bool,
81	/// A person's token its owner let use the website (g1t.sh) as them,
82	/// with `Authorization: Bearer`. See [`crate::scopes::TokenAccess::website`].
83	#[serde(default, skip_serializing_if = "std::ops::Not::not")]
84	pub website: bool,
85	}
86
87	/// `sign_in`: verifies a username, or any confirmed email address of the
88	/// account, and its password, for website sign-in. Wrong passwords are
89	/// counted against the account and `client`, and past a limit nothing is
90	/// checked for a while (see identity's `throttle.rs`).
91	/// Returns `Outcome<SignedIn>`.
92	#[derive(Debug, Serialize, Deserialize)]
93	pub struct SignInArgs {
94	pub username: String,
95	pub password: String,
96	/// Who is asking, such as the visitor's IP address, for rate limits.
97	#[serde(default)]
98	pub client: Option<String>,
99	}
100
101	#[derive(Debug, Serialize, Deserialize)]
102	#[serde(rename_all = "camelCase")]
103	pub struct SignedIn {
104	pub user: User,
105	/// Empty while `two_factor_challenge` is set: no session is made until
106	/// the code is given.
107	pub session_token: String,
108	/// Set when the account has two-factor authentication on: the token to
109	/// pass to `two_factor_sign_in` with a code. Valid for
110	/// `accounts::TWO_FACTOR_CHALLENGE_SECONDS`.
111	#[serde(default, skip_serializing_if = "Option::is_none")]
112	pub two_factor_challenge: Option<String>,
113	}
114
115	/// `sign_out` and `user_for_session`.
116	#[derive(Debug, Serialize, Deserialize)]
117	#[serde(rename_all = "camelCase")]
118	pub struct SessionArgs {
119	pub session_token: String,
120	}
121
122	/// `user_for_git_credentials`: the account password or an access token.
123	#[derive(Debug, Serialize, Deserialize)]
124	pub struct GitCredentialsArgs {
125	pub username: String,
126	pub secret: String,
127	}
128
129	/// `user_for_access_token`.
130	#[derive(Debug, Serialize, Deserialize)]
131	pub struct TokenArgs {
132	pub token: String,
133	}
134
135	/// `user_for_ssh_key`, and `principal_for_ssh_key` (see [`crate::deploy_keys`]).
136	#[derive(Debug, Serialize, Deserialize)]
137	pub struct FingerprintArgs {
138	pub fingerprint: String,
139	}
140
141	/// `user_by_username`.
142	#[derive(Debug, Serialize, Deserialize)]
143	pub struct UsernameArgs {
144	pub username: String,
145	}
146
147	/// `usernames`: the names behind account and workspace ids, as events and
148	/// other records store them. Returns a map from id to name; ids it does
149	/// not know are left out. Also `accounts`: the accounts behind user ids,
150	/// each with its username and avatar (`HashMap<String, accounts::EmailOwner>`).
151	#[derive(Debug, Serialize, Deserialize)]
152	pub struct UsernamesArgs {
153	pub ids: Vec<String>,
154	}
155
156	/// `display_usernames`: how each of these people (by lowercased username,
157	/// at most 200) wrote their username, for showing it beside the key.
158	/// Returns a map from the lowercased username to its chosen case; people
159	/// who chose none, and names nobody has, are left out.
160	#[derive(Debug, Default, Serialize, Deserialize)]
161	pub struct DisplayUsernamesArgs {
162	pub usernames: Vec<String>,
163	}
164
165	/// `list_ssh_keys` and `list_access_tokens`.
166	#[derive(Debug, Serialize, Deserialize)]
167	pub struct UserArgs {
168	pub user: User,
169	}
170
171	/// `ssh_key_owners`: services only. The account (user id) that registered
172	/// each key, by fingerprint (`SHA256:…`, as `ssh-keygen -lf` prints it),
173	/// for verifying commits signed with SSH keys. Returns a map of the
174	/// fingerprints found to user ids.
175	#[derive(Debug, Serialize, Deserialize)]
176	pub struct SshKeyOwnersArgs {
177	pub fingerprints: Vec<String>,
178	}
179
180	/// `add_ssh_key`: `public_key` is one line in OpenSSH format.
181	/// Returns `Outcome<SshKey>`.
182	#[derive(Debug, Serialize, Deserialize)]
183	#[serde(rename_all = "camelCase")]
184	pub struct AddSshKeyArgs {
185	pub user: User,
186	pub title: String,
187	pub public_key: String,
188	}
189
190	/// `remove_ssh_key` and `remove_access_token`.
191	#[derive(Debug, Serialize, Deserialize)]
192	pub struct RemoveArgs {
193	pub user: User,
194	pub id: String,
195	}
196
197	/// `create_access_token`: a token that acts as `user`. For a workspace
198	/// acting through a token of its own, the new token belongs to that
199	/// workspace too.
200	#[derive(Debug, Serialize, Deserialize)]
201	#[serde(rename_all = "camelCase")]
202	pub struct CreateAccessTokenArgs {
203	pub user: User,
204	pub name: String,
205	/// When set, the token stops working after this many seconds and is
206	/// left out of the user's token list, unless `listed`. Used for hosted
207	/// attempts.
208	#[serde(default)]
209	pub ttl_seconds: Option<u64>,
210	/// Its scopes, as `resource:level`; unknown names are left out. Null:
211	/// full access.
212	#[serde(default)]
213	pub scopes: Option<Vec<String>>,
214	/// Listed with the person's tokens although it expires: one they made
215	/// themselves, with an expiry.
216	#[serde(default)]
217	pub listed: bool,
218	/// The one repository it reaches, as `owner/name`: every other is
219	/// refused, whatever its owner could reach. Used for a session g1t
220	/// starts on someone's Anthropic account (`start_agent_session`).
221	#[serde(default, skip_serializing_if = "Option::is_none")]
222	pub repo: Option<String>,
223	}
224
225	/// `create_job_token`: a workflow job's `G1T_TOKEN`. It acts as the
226	/// repository's workspace, reaches that repository only, holds `scopes`
227	/// (from the job's `permissions`), and is never listed. The actions service
228	/// revokes it when the job ends (`revoke_job_tokens`); `ttl_seconds` is a
229	/// backstop. Returns `CreatedAccessToken`.
230	#[derive(Debug, Serialize, Deserialize)]
231	#[serde(rename_all = "camelCase")]
232	pub struct CreateJobTokenArgs {
233	/// The workspace the repository belongs to, as its own principal.
234	pub workspace: User,
235	pub repo: crate::repos::RepoPath,
236	pub run_id: String,
237	pub job_id: String,
238	/// What the token is listed as in logs: `G1T_TOKEN for acme/web run 4`.
239	pub name: String,
240	pub ttl_seconds: u64,
241	/// As `resource:level`; unknown names are left out.
242	pub scopes: Vec<String>,
243	/// Whether it may open and approve pull requests (`JobToken::pull_requests`).
244	#[serde(default)]
245	pub pull_requests: bool,
246	}
247
248	/// `revoke_job_tokens`: ends a workflow job's tokens at once, when the job
249	/// finishes or is cancelled. Only job tokens are touched. Returns `bool`.
250	#[derive(Debug, Default, Serialize, Deserialize)]
251	#[serde(rename_all = "camelCase")]
252	pub struct RevokeJobTokensArgs {
253	pub job_id: String,
254	}
255
256	/// `create_ask_token`: the credential Ask g1t reads g1t with while it
257	/// answers one question, through the MCP server, as the person asking.
258	///
259	/// It is that person's own token, so every read is checked exactly as
260	/// theirs would be, cut down three ways: it holds the read scopes only
261	/// ([`ask_token_scopes`]), so every change is refused whatever the person's
262	/// role; it is made for `workspace` alone (its repositories, and public
263	/// ones); and it expires in [`ASK_TOKEN_TTL_SECONDS`]. It is never listed,
264	/// never shown to the model or the browser, and the integrations service
265	/// revokes it when the answer ends (`revoke_ask_token`). A workspace's
266	/// rules for personal access tokens do not apply to it: g1t makes it, for
267	/// a feature the workspace's owner turned on, and nobody ever holds it.
268	///
269	/// Only the integrations service calls it, over its service binding.
270	/// Returns `Outcome<AskToken>`: refused for anyone but a person who belongs
271	/// to the workspace.
272	#[derive(Debug, Serialize, Deserialize)]
273	#[serde(rename_all = "camelCase")]
274	pub struct CreateAskTokenArgs {
275	pub actor: User,
276	pub workspace: String,
277	}
278
279	/// What `create_ask_token` returns. The plaintext token is returned once
280	/// and never stored.
281	#[derive(Debug, Serialize, Deserialize)]
282	#[serde(rename_all = "camelCase")]
283	pub struct AskToken {
284	pub token: String,
285	/// Its id, to revoke it with.
286	pub id: String,
287	}
288
289	/// `revoke_ask_token`: ends an Ask credential at once. Only Ask's tokens
290	/// are touched. Returns `bool`.
291	#[derive(Debug, Default, Serialize, Deserialize)]
292	#[serde(rename_all = "camelCase")]
293	pub struct RevokeAskTokenArgs {
294	pub id: String,
295	}
296
297	/// How long an Ask credential lives at most: longer than any one answer.
298	pub const ASK_TOKEN_TTL_SECONDS: u64 = 5 * 60;
299	/// What an Ask credential is named, in audit entries and logs.
300	pub const ASK_TOKEN_NAME: &str = "Ask g1t";
301	/// Marks a token as Ask's in identity's records (`access_tokens.purpose`).
302	pub const ASK_TOKEN_PURPOSE: &str = "ask";
303
304	/// What an Ask credential holds: every read scope and nothing else.
305	pub fn ask_token_scopes() -> Vec<crate::scopes::Scope> {
306	crate::scopes::Preset::ReadOnly.scopes().unwrap_or_default()
307	}
308
309	/// The plaintext token is returned once and never stored.
310	#[derive(Debug, Serialize, Deserialize)]
311	pub struct CreatedAccessToken {
312	pub token: String,
313	pub info: AccessToken,
314	}
315
316	/// `register`: creates an account and signs it in.
317	/// Returns `Outcome<SignedIn>`.
318	///
319	/// Anyone may register. `invite_code` is optional: an invitation sent to
320	/// an address without an account (`invite_member`, or a repository
321	/// invitation) carries one, and using it applies the invitation once the
322	/// address is confirmed.
323	#[derive(Debug, Serialize, Deserialize)]
324	pub struct RegisterArgs {
325	pub username: String,
326	pub email: String,
327	pub password: String,
328	/// An invite code such as `g1t-k7m2-q9xd-4hpw-…`, from an invitation.
329	/// One that is unknown, spent or for another address is ignored.
330	#[serde(default)]
331	pub invite_code: Option<String>,
332	/// The `proof` from the invite email's link. When it is the invite's
333	/// own and `email` is the address the invite was sent to, the account
334	/// starts with that address confirmed; otherwise it is ignored.
335	#[serde(default)]
336	pub email_proof: Option<String>,
337	/// Who is asking, such as the visitor's IP address, for rate limits.
338	#[serde(default)]
339	pub client: Option<String>,
340	}
341
342	/// `verify_email`: the token from the emailed link. Returns `Outcome<User>`.
343	#[derive(Debug, Serialize, Deserialize)]
344	pub struct EmailTokenArgs {
345	pub token: String,
346	}
347
348	/// `request_password_reset`. Always succeeds, so it cannot be used to find
349	/// out which addresses have accounts. Any confirmed address of an account
350	/// works: the link goes to the address given, and the primary (and the
351	/// backup) are told a reset was asked for. A few requests an hour per
352	/// address and per `client`; past that, nothing is sent.
353	#[derive(Debug, Serialize, Deserialize)]
354	pub struct EmailArgs {
355	pub email: String,
356	/// Who is asking, such as the visitor's IP address, for rate limits.
357	#[serde(default)]
358	pub client: Option<String>,
359	}
360
361	/// `reset_password`: sets a new password and ends every session.
362	/// Returns `Outcome<User>`.
363	#[derive(Debug, Serialize, Deserialize)]
364	pub struct ResetPasswordArgs {
365	pub token: String,
366	pub password: String,
367	}
368
369	/// `device_start`: begins a device sign-in. Returns `DeviceStart`.
370	#[derive(Debug, Serialize, Deserialize)]
371	#[serde(rename_all = "camelCase")]
372	pub struct DeviceStartArgs {
373	/// What is asking, shown to the person approving, e.g. "Claude Code".
374	pub client_name: String,
375	}
376
377	#[derive(Debug, Serialize, Deserialize)]
378	#[serde(rename_all = "camelCase")]
379	pub struct DeviceStart {
380	/// Secret held by the tool and exchanged for a token once approved.
381	pub device_code: String,
382	/// Short code shown to the person, e.g. `WDJB-MJHT`.
383	pub user_code: String,
384	/// Seconds until both codes stop working.
385	pub expires_in: u32,
386	/// Seconds the tool should wait between polls.
387	pub interval: u32,
388	}
389
390	/// `device_lookup`: what a user code is asking for, or null if it is not
391	/// valid. Returns `Option<DeviceRequest>`.
392	#[derive(Debug, Serialize, Deserialize)]
393	#[serde(rename_all = "camelCase")]
394	pub struct DeviceLookupArgs {
395	pub user_code: String,
396	}
397
398	#[derive(Debug, Serialize, Deserialize)]
399	#[serde(rename_all = "camelCase")]
400	pub struct DeviceRequest {
401	pub user_code: String,
402	pub client_name: String,
403	}
404
405	/// `device_resolve`: the signed-in person approves or denies a request.
406	/// Returns `Outcome<bool>`.
407	#[derive(Debug, Serialize, Deserialize)]
408	#[serde(rename_all = "camelCase")]
409	pub struct DeviceResolveArgs {
410	pub user_code: String,
411	pub user: User,
412	pub approve: bool,
413	}
414
415	/// `device_claim`: the tool asks whether its request was approved.
416	#[derive(Debug, Serialize, Deserialize)]
417	#[serde(rename_all = "camelCase")]
418	pub struct DeviceClaimArgs {
419	pub device_code: String,
420	}
421
422	/// The answer to a `device_claim`.
423	#[derive(Debug, Serialize, Deserialize)]
424	#[serde(tag = "status", rename_all = "snake_case")]
425	pub enum DeviceClaim {
426	/// Nobody has approved or denied it yet; ask again after the interval.
427	Pending,
428	Denied,
429	/// The code was never issued, has expired, or was already used.
430	Expired,
431	/// The access token, returned once.
432	Approved {
433	token: String,
434	user: User,
435	},
436	}
437
438	/// A workspace: the owner of repositories, and the first segment of their
439	/// URLs. A person's own space and a team's are the same thing.
440	#[derive(Clone, Debug, Serialize, Deserialize)]
441	#[serde(rename_all = "camelCase")]
442	pub struct Workspace {
443	pub id: String,
444	pub slug: String,
445	pub name: String,
446	/// One line saying what the workspace is for.
447	pub description: Option<String>,
448	/// RFC 3339.
449	pub created_at: String,
450	pub member_count: u32,
451	/// The workspace's uploaded icon: the SHA-256 of its bytes, served at
452	/// `/avatars/<avatar>`. Null means the generated letter avatar.
453	#[serde(default)]
454	pub avatar: Option<String>,
455	/// What every member gets on each of its repositories; owners have
456	/// Admin. See [`crate::access`].
457	#[serde(default)]
458	pub base_permission: crate::access::BasePermission,
459	/// Who may create its teams. See [`crate::teams::TeamCreation`].
460	#[serde(default)]
461	pub team_creation: crate::teams::TeamCreation,
462	/// What members may do, by GitHub's names for each
463	/// (`members_can_create_public_repositories`...), at the top level as
464	/// GitHub's organization has them. See [`crate::MemberPrivileges`].
465	#[serde(flatten)]
466	pub privileges: crate::MemberPrivileges,
467	/// Whether members and outside collaborators need two-factor
468	/// authentication to use it.
469	#[serde(default)]
470	pub two_factor_requirement_enabled: bool,
471	}
472
473	#[derive(Clone, Debug, Serialize, Deserialize)]
474	pub struct Member {
475	pub username: String,
476	/// The username as its owner wrote it (`Ana`), when that differs from
477	/// `username`: what pages show.
478	#[serde(default, skip_serializing_if = "Option::is_none")]
479	pub display_username: Option<String>,
480	pub role: crate::Role,
481	/// The roles they hold besides `role`.
482	#[serde(default)]
483	pub org_roles: Vec<crate::OrgRole>,
484	/// Whether they have two-factor authentication on. Shown to owners
485	/// only; null for anyone else.
486	#[serde(default)]
487	pub two_factor: Option<bool>,
488	/// Their display name, when they set one.
489	#[serde(default)]
490	pub name: Option<String>,
491	/// Their uploaded avatar: the SHA-256 of its bytes, served at
492	/// `/avatars/<avatar>`. None means the generated letter avatar.
493	#[serde(default)]
494	pub avatar: Option<String>,
495	}
496
497	/// Where a workspace keeps its repositories' git data: anywhere g1t
498	/// stores it (the default), or in the EU only. It applies to repositories
499	/// made after it is set; the repos service reads it when it places a new
500	/// one (`storage_options` says whether the EU can be chosen).
501	#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
502	#[serde(rename_all = "lowercase")]
503	pub enum DataResidency {
504	#[default]
505	Anywhere,
506	Eu,
507	}
508
509	impl DataResidency {
510	pub fn as_str(self) -> &'static str {
511	match self {
512	DataResidency::Anywhere => "anywhere",
513	DataResidency::Eu => "eu",
514	}
515	}
516
517	pub fn parse(text: &str) -> Option<Self> {
518	match text.trim().to_ascii_lowercase().as_str() {
519	"anywhere" => Some(DataResidency::Anywhere),
520	"eu" => Some(DataResidency::Eu),
521	_ => None,
522	}
523	}
524	}
525
526	/// `workspace_residency` takes [`SlugArgs`] and returns
527	/// `Option<DataResidency>` (null when there is no such workspace).
528	/// `set_workspace_residency`: owners only. Returns `Outcome<DataResidency>`.
529	#[derive(Debug, Serialize, Deserialize)]
530	pub struct SetResidencyArgs {
531	pub actor: User,
532	pub slug: String,
533	pub residency: DataResidency,
534	}
535
536	/// `create_workspace`. Returns `Outcome<Workspace>`.
537	#[derive(Debug, Serialize, Deserialize)]
538	pub struct CreateWorkspaceArgs {
539	pub user: User,
540	pub slug: String,
541	#[serde(default)]
542	pub name: String,
543	}
544
545	/// `get_workspace`: public details, or null. Returns `Option<Workspace>`.
546	#[derive(Debug, Serialize, Deserialize)]
547	pub struct SlugArgs {
548	pub slug: String,
549	}
550
551	/// `list_members`: members only. Owners also see each member's
552	/// `two_factor`. Returns `Outcome<Vec<Member>>`.
553	#[derive(Debug, Serialize, Deserialize)]
554	pub struct ListMembersArgs {
555	pub slug: String,
556	pub viewer: crate::Viewer,
557	}
558
559	/// `add_member` and `remove_member`: owners only. `add_member` never adds a
560	/// person at once: it sends them a workspace invitation to accept or
561	/// decline, as `invite_member` with a username does. Only g1t's own agent
562	/// is added at once. Removing yourself is
563	/// leaving (`members::LeaveWorkspaceArgs`); removing an owner is refused
564	/// when they are the last. Each returns `Outcome<bool>`.
565	#[derive(Debug, Serialize, Deserialize)]
566	pub struct MemberArgs {
567	pub actor: User,
568	pub slug: String,
569	pub username: String,
570	#[serde(default)]
571	pub surface: Option<crate::audit::Surface>,
572	}
573
574	/// `update_workspace`: owners only. An empty name falls back to the slug;
575	/// an empty description clears it. Returns `Outcome<Workspace>`.
576	#[derive(Debug, Serialize, Deserialize)]
577	pub struct UpdateWorkspaceArgs {
578	pub actor: User,
579	pub slug: String,
580	pub name: String,
581	pub description: String,
582	}
583
584	/// `rename_workspace`: owners only. Changes the workspace's slug, the first
585	/// segment of its URLs, to `new_slug`; the display name is untouched. The
586	/// old slug redirects to the new one, and is held for this workspace, for
587	/// [`SLUG_HOLD_DAYS`]. Publishes `workspace.renamed`. Returns
588	/// `Outcome<Workspace>`.
589	///
590	/// `check_workspace_rename` takes the same arguments and answers whether
591	/// the rename would be allowed, changing nothing. Returns `Outcome<bool>`.
592	#[derive(Debug, Serialize, Deserialize)]
593	#[serde(rename_all = "camelCase")]
594	pub struct RenameWorkspaceArgs {
595	pub actor: User,
596	pub slug: String,
597	pub new_slug: String,
598	}
599
600	/// `delete_workspace`: owners only, and only a person. `confirm` must be
601	/// the workspace's slug, typed out. Refused for a protected workspace
602	/// ([`protected_names`]), whoever asks, and while billing cannot settle it
603	/// (`close_workspace`). Everything in it goes with it at once: nobody can
604	/// reach it, its tokens stop working, its pages are not found, and its
605	/// repositories, projects and apps are deleted with it. It is kept for
606	/// [`WORKSPACE_RESTORE_DAYS`] so g1t's staff can restore it, then purged:
607	/// its memberships, access tokens and old-slug redirects go, and billing's
608	/// ledger and the audit log keep its history. The slug is never given to
609	/// another workspace; the person whose username it is may make a workspace
610	/// of that name again once it is purged. Publishes `workspace.deleting`,
611	/// and `workspace.deleted` at the purge. Returns `Outcome<bool>`.
612	///
613	/// `check_workspace_deletion` takes the same arguments (with `confirm`
614	/// ignored) and says what would go and whether anything stands in the way,
615	/// changing nothing. Returns `Outcome<WorkspaceDeletion>`.
616	#[derive(Debug, Serialize, Deserialize)]
617	pub struct DeleteWorkspaceArgs {
618	pub actor: User,
619	pub slug: String,
620	#[serde(default)]
621	pub confirm: String,
622	/// Where the request came in, for the audit log; g1t.sh when absent.
623	#[serde(default)]
624	pub surface: Option<crate::audit::Surface>,
625	}
626
627	/// What deleting a workspace takes with it, and what stands in the way.
628	/// Nothing does when `billing` is null and it is not `protected`.
629	#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
630	pub struct WorkspaceDeletion {
631	/// Its live repositories, which are deleted with it.
632	pub repositories: u32,
633	/// Its projects, hidden with it.
634	pub projects: u32,
635	#[serde(default)]
636	pub members: u32,
637	/// Why billing cannot close the workspace yet, in words for its owner.
638	pub billing: Option<String>,
639	/// It can never be deleted, by anyone ([`protected_names`]).
640	#[serde(default)]
641	pub protected: bool,
642	}
643
644	impl WorkspaceDeletion {
645	pub fn blocked(&self) -> bool {
646	self.protected \|\| self.billing.is_some()
647	}
648
649	/// Why the workspace cannot be deleted, as one sentence, or `None`.
650	pub fn reason(&self, slug: &str) -> Option<String> {
651	if self.protected {
652	return Some(protected_refusal(slug));
653	}
654	self.billing.clone()
655	}
656	}
657
658	/// How long a deleted workspace is kept, for staff to restore, before it is
659	/// purged.
660	pub const WORKSPACE_RESTORE_DAYS: u64 = 30;
661
662	/// Workspaces nobody can delete, whatever identity's `PROTECTED_WORKSPACES`
663	/// says: Flagon's, which runs g1t.
664	pub const ALWAYS_PROTECTED: &[&str] = &["flagon-io"];
665
666	/// The protected workspaces: `configured` (comma-separated slugs or
667	/// workspace ids, as identity's `PROTECTED_WORKSPACES` holds them), and
668	/// [`ALWAYS_PROTECTED`] whatever it says, so an empty or missing variable
669	/// still protects them. Lowercased, without duplicates.
670	pub fn protected_names(configured: Option<&str>) -> Vec<String> {
671	let mut names: Vec<String> = Vec::new();
672	let given = configured.unwrap_or_default().split(',');
673	for name in ALWAYS_PROTECTED.iter().copied().chain(given) {
674	let name = name.trim().to_lowercase();
675	if !name.is_empty() && !names.contains(&name) {
676	names.push(name);
677	}
678	}
679	names
680	}
681
682	/// Why a protected workspace is not deleted, purged or acted on.
683	pub fn protected_refusal(slug: &str) -> String {
684	format!("{slug} is protected and can never be deleted.")
685	}
686
687	/// `admin_deleted_workspaces` takes no arguments (`{}`) and returns
688	/// `Vec<DeletedWorkspace>`, newest first. Staff only.
689	///
690	/// A workspace an owner deleted, kept until `purge_after` for staff to
691	/// restore.
692	#[derive(Clone, Debug, Serialize, Deserialize)]
693	#[serde(rename_all = "camelCase")]
694	pub struct DeletedWorkspace {
695	pub workspace_id: String,
696	pub slug: String,
697	pub name: String,
698	/// RFC 3339.
699	pub deleted_at: String,
700	/// The username of the owner who deleted it, or the staff member (by
701	/// email) who deleted it with the account that was its only owner.
702	pub deleted_by: String,
703	/// RFC 3339: when it is purged unless restored first.
704	pub purge_after: String,
705	/// What went with it, counted when it was deleted.
706	pub went: WorkspaceDeletion,
707	/// Whether staff can still restore it.
708	pub restorable: bool,
709	}
710
711	/// `admin_restore_workspace` and `admin_purge_workspace`: staff restore a
712	/// deleted workspace within [`WORKSPACE_RESTORE_DAYS`], or purge it now.
713	/// `staff` is who, for the audit logs. Purging needs `confirm`, the slug
714	/// typed out, and is refused for a protected workspace. Restoring publishes
715	/// `workspace.restored`; purging, `workspace.deleted`. Both return
716	/// `Outcome<bool>`.
717	#[derive(Debug, Serialize, Deserialize)]
718	#[serde(rename_all = "camelCase")]
719	pub struct AdminDeletedWorkspaceArgs {
720	pub workspace_id: String,
721	pub staff: String,
722	#[serde(default)]
723	pub confirm: String,
724	}
725
726	/// `transfer_repo_scopes`: a repository moved from `from` to `to`; the
727	/// tokens of agents at work on it are kept pointing at it. For repos'
728	/// `transfer`. Returns `bool`.
729	#[derive(Debug, Serialize, Deserialize)]
730	pub struct TransferRepoScopesArgs {
731	pub from: crate::repos::RepoPath,
732	pub to: crate::repos::RepoPath,
733	}
734
735	/// How long a workspace's old slug keeps redirecting to it, and stays
736	/// reserved for it, after a rename.
737	pub const SLUG_HOLD_DAYS: u64 = 90;
738
739	/// How long a workspace must wait between renames.
740	pub const RENAME_COOLDOWN_HOURS: u64 = 24;
741
742	// `resolve_slug` takes `SlugArgs` and returns `Option<String>`: the
743	// workspace's current slug when `slug` is one it was renamed from within
744	// the last `SLUG_HOLD_DAYS`, and null otherwise (including for a slug that
745	// is in use), or the workspace's slug when `slug` is one of its aliases.
746
747	// `resolve_alias` takes `SlugArgs` and returns `Option<String>`: the slug
748	// now of the workspace `slug` is an alias of, and null when it is none.
749	// Aliases are set by g1t's staff only: `g1t` is Flagon, Inc.'s `flagon-io`.
750	// An alias follows its workspace through renames.
751
752	/// `admin_aliases` takes no arguments (`{}`) and returns
753	/// `Vec<WorkspaceAlias>`, by alias. Staff only.
754	///
755	/// A name staff point at a workspace, so that its addresses (pages, git,
756	/// the API, packages) lead to the workspace under its own name.
757	#[derive(Clone, Debug, Serialize, Deserialize)]
758	#[serde(rename_all = "camelCase")]
759	pub struct WorkspaceAlias {
760	pub alias: String,
761	pub workspace_id: String,
762	/// The workspace's slug and name now.
763	pub workspace: String,
764	pub workspace_name: String,
765	/// Why it exists, as staff wrote it.
766	pub note: String,
767	/// The staff member who set it, or `migration`.
768	pub created_by: String,
769	/// RFC 3339.
770	pub created_at: String,
771	}
772
773	/// `admin_set_alias`: points `alias` at the workspace whose slug is
774	/// `workspace`. The alias must have a namespace's shape, must not be one of
775	/// the site's routes, and must not be anyone's username, a workspace's slug
776	/// (deleted, or held after a rename) or another alias. `note` is required:
777	/// it is the reason, kept with the alias and in sudo's audit log. Staff
778	/// only. Returns `Outcome<WorkspaceAlias>`.
779	#[derive(Debug, Serialize, Deserialize)]
780	#[serde(rename_all = "camelCase")]
781	pub struct AdminSetAliasArgs {
782	pub alias: String,
783	pub workspace: String,
784	pub note: String,
785	pub staff: String,
786	}
787
788	/// `admin_remove_alias`: the alias stops leading anywhere, and the name is
789	/// nobody's again unless it is reserved. `reason` goes in sudo's audit log.
790	/// Staff only. Returns `Outcome<bool>`.
791	#[derive(Debug, Serialize, Deserialize)]
792	#[serde(rename_all = "camelCase")]
793	pub struct AdminRemoveAliasArgs {
794	pub alias: String,
795	pub reason: String,
796	pub staff: String,
797	}
798
799	/// `set_workspace_avatar`: owners only. `image` is the file's bytes in
800	/// base64: PNG, JPEG, WebP or GIF, at most `MAX_AVATAR_BYTES`. Null removes
801	/// the icon. Returns `Outcome<Workspace>`.
802	#[derive(Debug, Serialize, Deserialize)]
803	pub struct SetWorkspaceAvatarArgs {
804	pub actor: User,
805	pub slug: String,
806	pub image: Option<String>,
807	}
808
809	/// `set_user_avatar`: a person's own avatar, as `SetWorkspaceAvatarArgs`.
810	/// Returns `Outcome<Option<String>>`: the new avatar, or null once removed.
811	#[derive(Debug, Serialize, Deserialize)]
812	pub struct SetUserAvatarArgs {
813	pub user: User,
814	pub image: Option<String>,
815	}
816
817	/// The largest avatar that can be uploaded, in bytes.
818	pub const MAX_AVATAR_BYTES: usize = 1024 * 1024;
819
820	/// `list_workspace_tokens`: members only. Returns
821	/// `Outcome<Vec<AccessToken>>`.
822	#[derive(Debug, Serialize, Deserialize)]
823	pub struct WorkspaceTokensArgs {
824	pub slug: String,
825	pub viewer: crate::Viewer,
826	}
827
828	/// `remove_workspace_token`: owners only. Returns `Outcome<bool>`.
829	#[derive(Debug, Serialize, Deserialize)]
830	pub struct RemoveWorkspaceTokenArgs {
831	pub actor: User,
832	pub slug: String,
833	pub id: String,
834	}
835
836	/// `oauth_authorize`: the signed-in person approved an application. The
837	/// caller has checked the client and that it may be redirected to
838	/// `redirect_uri`. Returns `OAuthCode`.
839	#[derive(Debug, Serialize, Deserialize)]
840	#[serde(rename_all = "camelCase")]
841	pub struct OAuthAuthorizeArgs {
842	pub user: User,
843	pub client_id: String,
844	/// Shown wherever the application's access is listed.
845	pub client_name: String,
846	pub redirect_uri: String,
847	/// PKCE challenge, method S256.
848	pub code_challenge: String,
849	/// What the person granted, as `resource:level`. Null: full access.
850	#[serde(default)]
851	pub scopes: Option<Vec<String>>,
852	}
853
854	#[derive(Debug, Serialize, Deserialize)]
855	pub struct OAuthCode {
856	pub code: String,
857	}
858
859	/// `oauth_exchange`: redeems an authorization code.
860	/// Returns `Outcome<OAuthTokens>`.
861	#[derive(Debug, Serialize, Deserialize)]
862	#[serde(rename_all = "camelCase")]
863	pub struct OAuthExchangeArgs {
864	pub code: String,
865	pub code_verifier: String,
866	pub client_id: String,
867	pub redirect_uri: String,
868	}
869
870	/// `oauth_refresh`: trades a refresh token for new tokens.
871	/// Returns `Outcome<OAuthTokens>`.
872	#[derive(Debug, Serialize, Deserialize)]
873	#[serde(rename_all = "camelCase")]
874	pub struct OAuthRefreshArgs {
875	pub refresh_token: String,
876	pub client_id: String,
877	}
878
879	#[derive(Debug, Serialize, Deserialize)]
880	#[serde(rename_all = "camelCase")]
881	pub struct OAuthTokens {
882	pub access_token: String,
883	/// Works once; using it returns the next one.
884	pub refresh_token: String,
885	/// Seconds until the access token stops working.
886	pub expires_in: u64,
887	/// The scopes granted, space-separated, or `*` for full access.
888	#[serde(default)]
889	pub scope: Option<String>,
890	}
891
892	/// An application a person has signed in to. Listed by `list_oauth_grants`
893	/// and ended by `revoke_oauth_grant`.
894	#[derive(Debug, Serialize, Deserialize)]
895	#[serde(rename_all = "camelCase")]
896	pub struct OAuthGrant {
897	pub id: String,
898	pub client_name: String,
899	/// RFC 3339.
900	pub created_at: String,
901	/// RFC 3339.
902	pub last_used_at: String,
903	/// What the person granted. Null: full access.
904	#[serde(default)]
905	pub scopes: Option<Vec<String>>,
906	/// Signed in before applications were given scopes: full access until
907	/// someone narrows it.
908	#[serde(default)]
909	pub legacy: bool,
910	}
911
912	/// `update_oauth_grant`: changes what an application the person signed in
913	/// to may do, at once and when it refreshes. Returns `Outcome<OAuthGrant>`.
914	#[derive(Debug, Serialize, Deserialize)]
915	pub struct UpdateOAuthGrantArgs {
916	pub user: User,
917	pub id: String,
918	#[serde(default)]
919	pub scopes: Option<Vec<String>>,
920	}
921
922
923	/// What a scoped token may do: these operations, in this repository. Run
924	/// credentials (a token for one CI or sandbox run, see
925	/// [`crate::credentials`]) carry one today, and so do tokens g1t's retired
926	/// hosted agents were issued, which still parse so their stored rows and
927	/// the `@g1t` history they wrote read as before.
928	#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
929	pub struct AgentScope {
930	pub repo: crate::repos::RepoPath,
931	/// API and MCP operation names, such as `create_issue`.
932	pub operations: Vec<String>,
933	/// Set on a run credential: the run it belongs to, and what it may do
934	/// with git. See [`crate::credentials`].
935	#[serde(default, skip_serializing_if = "Option::is_none")]
936	pub run: Option<crate::credentials::RunBinding>,
937	}
938
939	/// The id g1t's retired hosted agent acted under. Only ever stored, never
940	/// shown: rows it wrote keep it, and still render as g1t's
941	/// ([`crate::system::ID`]) work without counting as g1t itself, such as
942	/// for whether an approval counts.
943	pub const AGENT_ID: &str = "usr_g1t_agent";
944	/// The name g1t's agent is shown by: g1t's own, [`crate::system::USERNAME`].
945	/// Everything it does, people see g1t do.
946	pub const AGENT_NAME: &str = crate::system::USERNAME;
947
948	// --- Staff ---------------------------------------------------------------
949	//
950	// Staff-only methods, for sudo.g1t.sh. They take no viewer and check no
951	// membership: only sudo calls them, over its service binding, after it has
952	// verified a Cloudflare Access sign-in and its staff list. Nothing a
953	// customer can reach should ever forward to them.
954
955	/// `notify_owners`: emails a short notice, with one link, to each owner of
956	/// a workspace with a confirmed address. Called by other services (billing
957	/// warns owners near their usage limit), never on a person's behalf.
958	/// Returns how many were sent.
959	#[derive(Clone, Debug, Serialize, Deserialize)]
960	pub struct NotifyOwnersArgs {
961	pub workspace: String,
962	pub subject: String,
963	/// One or two sentences: what happened and what it means.
964	pub intro: String,
965	/// The button's words, such as `Open billing`.
966	pub action: String,
967	/// Where the button goes; must be on g1t.sh.
968	pub link: String,
969	/// Small print: why they got it.
970	pub footer: String,
971	}
972
973	/// `admin_workspaces`: every workspace, newest first, at most
974	/// [`ADMIN_WORKSPACES_LIMIT`], optionally only those whose slug, name or
975	/// an owner's username or email contains `query`. Returns
976	/// `Vec<AdminWorkspace>`. Staff only.
977	#[derive(Debug, Default, Serialize, Deserialize)]
978	pub struct AdminWorkspacesArgs {
979	#[serde(default)]
980	pub query: Option<String>,
981	}
982
983	/// The most workspaces one `admin_workspaces` call returns.
984	pub const ADMIN_WORKSPACES_LIMIT: usize = 500;
985
986	/// An owner of a workspace, as staff see them.
987	#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
988	pub struct AdminOwner {
989	pub username: String,
990	pub email: Option<String>,
991	}
992
993	/// A workspace as staff see it: who owns it and how many belong to it.
994	#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
995	#[serde(rename_all = "camelCase")]
996	pub struct AdminWorkspace {
997	pub slug: String,
998	pub name: String,
999	/// RFC 3339.
1000	pub created_at: String,
1001	pub owners: Vec<AdminOwner>,
1002	pub member_count: u32,
1003	}
1004
1005	/// `admin_workspace`: one workspace with every member, or null. Takes
1006	/// `SlugArgs`; returns `Option<AdminWorkspaceDetail>`. Staff only.
1007	#[derive(Clone, Debug, Serialize, Deserialize)]
1008	#[serde(rename_all = "camelCase")]
1009	pub struct AdminWorkspaceDetail {
1010	pub slug: String,
1011	pub name: String,
1012	pub description: Option<String>,
1013	/// RFC 3339.
1014	pub created_at: String,
1015	/// Owners first, then by username.
1016	pub members: Vec<AdminMember>,
1017	/// It can never be deleted ([`protected_names`]).
1018	#[serde(default)]
1019	pub protected: bool,
1020	/// Set while staff have it suspended.
1021	#[serde(default)]
1022	pub suspended: Option<Suspension>,
1023	}
1024
1025	/// A member of a workspace, as staff see them.
1026	#[derive(Clone, Debug, Serialize, Deserialize)]
1027	pub struct AdminMember {
1028	pub username: String,
1029	pub email: Option<String>,
1030	pub role: crate::Role,
1031	/// When they joined the workspace. RFC 3339.
1032	pub joined: String,
1033	}
1034
1035	// --- Profiles ------------------------------------------------------------
1036	//
1037	// A person's public page at `g1t.sh/u/<username>`. Everything in a
1038	// `Profile` is shown to anyone, signed in or not; an email address never is.
1039
1040	/// The most characters each profile field takes.
1041	pub const MAX_PROFILE_NAME: usize = 80;
1042	pub const MAX_PROFILE_BIO: usize = 160;
1043	pub const MAX_PROFILE_LOCATION: usize = 80;
1044	pub const MAX_PROFILE_WEBSITE: usize = 200;
1045	pub const MAX_PROFILE_PRONOUNS: usize = 40;
1046	pub const MAX_PROFILE_TIMEZONE: usize = 64;
1047
1048	/// What anyone may see about a person.
1049	#[derive(Clone, Debug, Default, Serialize, Deserialize)]
1050	#[serde(rename_all = "camelCase")]
1051	pub struct Profile {
1052	/// Lowercased: what the profile is found and linked by.
1053	pub username: String,
1054	/// The username as its owner wrote it, when that differs: what the page shows.
1055	#[serde(default, skip_serializing_if = "Option::is_none")]
1056	pub display_username: Option<String>,
1057	/// The name they go by, if they gave one.
1058	pub name: Option<String>,
1059	/// One or two lines about them, at most [`MAX_PROFILE_BIO`] characters.
1060	pub bio: Option<String>,
1061	pub location: Option<String>,
1062	/// An `https://` address.
1063	pub website: Option<String>,
1064	pub pronouns: Option<String>,
1065	/// The time zone they are in, an IANA name such as `America/Denver`.
1066	#[serde(default)]
1067	pub timezone: Option<String>,
1068	/// The uploaded avatar's hash, served at `/avatars/<avatar>`.
1069	pub avatar: Option<String>,
1070	/// When the account was made. RFC 3339.
1071	pub created_at: String,
1072	}
1073
1074	// `profile` takes `UsernameArgs` and returns `Option<Profile>`: null for
1075	// an account that does not exist.
1076
1077	/// `update_profile`: a person changes their own profile. Every field is
1078	/// replaced; an empty one is cleared. Returns `Outcome<Profile>`.
1079	#[derive(Debug, Default, Serialize, Deserialize)]
1080	#[serde(rename_all = "camelCase")]
1081	pub struct UpdateProfileArgs {
1082	pub actor: User,
1083	#[serde(default)]
1084	pub name: String,
1085	#[serde(default)]
1086	pub bio: String,
1087	#[serde(default)]
1088	pub location: String,
1089	#[serde(default)]
1090	pub website: String,
1091	#[serde(default)]
1092	pub pronouns: String,
1093	/// An IANA time zone name, such as `America/Denver`.
1094	#[serde(default)]
1095	pub timezone: String,
1096	}
1097
1098	/// `profile_workspaces`: the workspaces shown on a person's profile, as
1099	/// `viewer` may see them. A membership is shown only when it is no secret
1100	/// from the viewer: a workspace the viewer belongs to as well, or one of
1101	/// `public`, the workspaces the caller found the person has made a public
1102	/// project in (whose page shows that already). Returns
1103	/// `Vec<ProfileWorkspace>`; empty for an account that does not exist.
1104	#[derive(Debug, Serialize, Deserialize)]
1105	pub struct ProfileWorkspacesArgs {
1106	pub username: String,
1107	pub viewer: crate::Viewer,
1108	#[serde(default)]
1109	pub public: Vec<String>,
1110	}
1111
1112	/// A workspace on a person's profile.
1113	#[derive(Clone, Debug, Serialize, Deserialize)]
1114	pub struct ProfileWorkspace {
1115	pub slug: String,
1116	pub name: String,
1117	pub avatar: Option<String>,
1118	}
1119
1120	// --- Dock pins -------------------------------------------------------------
1121	//
1122	// The apps a person pins to their dock in a workspace, kept with their
1123	// account so the dock follows them to every device. Each person's own:
1124	// nobody else reads or sets them.
1125
1126	/// The most apps a person pins in one workspace.
1127	pub const MAX_DOCK_PINS: usize = 24;
1128	/// The most characters an app key takes.
1129	pub const MAX_DOCK_APP_KEY: usize = 32;
1130
1131	/// `dock_pins`: the apps `user` pinned in the workspace `workspace` (a
1132	/// slug), in the order they set. Returns `Option<Vec<String>>`: null when
1133	/// they never saved any there, or are not one of its members.
1134	#[derive(Debug, Default, Serialize, Deserialize)]
1135	#[serde(rename_all = "camelCase")]
1136	pub struct DockPinsArgs {
1137	pub user: User,
1138	pub workspace: String,
1139	}
1140
1141	/// `set_dock_pins`: replaces `user`'s pins in `workspace` with `apps`, in
1142	/// that order. Each key is lowercase letters, digits and hyphens, at most
1143	/// [`MAX_DOCK_APP_KEY`] characters; a repeat is dropped; at most
1144	/// [`MAX_DOCK_PINS`]. Which keys name real apps is the web app's to say.
1145	/// Returns `Outcome<Vec<String>>`: the pins as saved.
1146	#[derive(Debug, Default, Serialize, Deserialize)]
1147	#[serde(rename_all = "camelCase")]
1148	pub struct SetDockPinsArgs {
1149	pub user: User,
1150	pub workspace: String,
1151	#[serde(default)]
1152	pub apps: Vec<String>,
1153	}
1154
1155	// --- Sounds and desktop notifications --------------------------------------
1156	//
1157	// What a person hears when chat moves, kept with their account so a phone,
1158	// a laptop and the desktop app all sound the same. Which sound plays when
1159	// is the web app's rule (apps/web/app/lib/chat-sounds.ts); identity keeps
1160	// the choices. Do not disturb is not here: it is the person's presence
1161	// (`dnd_until`, services/notify), which also silences pop-ups and pushes.
1162	// Mirrors `SoundSettings` in packages/contracts/src/identity.ts.
1163
1164	/// The sets of sounds a person can choose from.
1165	pub const SOUND_SETS: [&str; 2] = ["soft", "bright"];
1166	/// The cues a person can turn on and off. `call` is reserved and has no setting.
1167	pub const SOUND_CUES: [&str; 4] = ["message", "direct", "mention", "sent"];
1168	/// Cues that no longer play: `agent_done`, from g1t's retired hosted
1169	/// agents. Saved settings that name one still read, without it, and a
1170	/// change that names one leaves it out rather than failing.
1171	pub const RETIRED_SOUND_CUES: [&str; 1] = ["agent_done"];
1172	/// Before anyone changes them: every cue but the tick as you send.
1173	pub const SOUND_CUES_OFF_BY_DEFAULT: [&str; 1] = ["sent"];
1174	pub const DEFAULT_SOUND_SET: &str = "soft";
1175	pub const DEFAULT_SOUND_VOLUME: u8 = 60;
1176
1177	/// A person's sound settings, as kept and as answered. Wire fields are
1178	/// snake_case, as the site's JSON is.
1179	#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
1180	pub struct SoundSettings {
1181	/// Whether anything plays at all.
1182	pub sounds_enabled: bool,
1183	/// One of [`SOUND_SETS`].
1184	pub sound_set: String,
1185	/// 0 to 100.
1186	pub sound_volume: u8,
1187	/// Each cue on or off, by name; a cue left out is on, except `sent`.
1188	#[serde(default)]
1189	pub sound_cues: std::collections::BTreeMap<String, bool>,
1190	/// Whether an open tab shows a system notification for a message to
1191	/// you while its window is not in front.
1192	pub desktop_toasts: bool,
1193	}
1194
1195	impl Default for SoundSettings {
1196	fn default() -> Self {
1197	SoundSettings {
1198	sounds_enabled: true,
1199	sound_set: DEFAULT_SOUND_SET.to_owned(),
1200	sound_volume: DEFAULT_SOUND_VOLUME,
1201	sound_cues: SOUND_CUES
1202	.iter()
1203	.map(\|cue\| ((*cue).to_owned(), !SOUND_CUES_OFF_BY_DEFAULT.contains(cue)))
1204	.collect(),
1205	desktop_toasts: false,
1206	}
1207	}
1208	}
1209
1210	/// A change to them: only what is sent changes; `sound_cues` merges by cue.
1211	#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
1212	pub struct SoundSettingsChange {
1213	#[serde(default)]
1214	pub sounds_enabled: Option<bool>,
1215	#[serde(default)]
1216	pub sound_set: Option<String>,
1217	#[serde(default)]
1218	pub sound_volume: Option<i64>,
1219	#[serde(default)]
1220	pub sound_cues: Option<std::collections::BTreeMap<String, bool>>,
1221	#[serde(default)]
1222	pub desktop_toasts: Option<bool>,
1223	}
1224
1225	/// `sound_settings`: `user`'s own, or the defaults when they never changed
1226	/// them. Returns `SoundSettings`. People only.
1227	#[derive(Debug, Default, Serialize, Deserialize)]
1228	#[serde(rename_all = "camelCase")]
1229	pub struct SoundSettingsArgs {
1230	pub user: User,
1231	}
1232
1233	/// `set_sound_settings`: changes `user`'s own. Returns
1234	/// `Outcome<SoundSettings>`: the settings as kept, or `invalid` for a set
1235	/// or cue g1t does not have, or a volume outside 0 to 100.
1236	#[derive(Debug, Default, Serialize, Deserialize)]
1237	#[serde(rename_all = "camelCase")]
1238	pub struct SetSoundSettingsArgs {
1239	pub user: User,
1240	#[serde(default)]
1241	pub change: SoundSettingsChange,
1242	}
1243
1244	/// `directory`: every account or every workspace, as their public pages
1245	/// show them, a page at a time in name order. For services that index
1246	/// them, such as search; nothing private is in it. Returns
1247	/// `DirectoryPage`.
1248	#[derive(Debug, Default, Serialize, Deserialize)]
1249	pub struct DirectoryArgs {
1250	/// `user` or `workspace`.
1251	pub kind: String,
1252	/// Names after this one.
1253	#[serde(default)]
1254	pub after: Option<String>,
1255	pub limit: u32,
1256	}
1257
1258	/// One account or workspace in the directory.
1259	#[derive(Clone, Debug, Serialize, Deserialize)]
1260	#[serde(rename_all = "camelCase")]
1261	pub struct DirectoryEntry {
1262	/// The account's or workspace's id.
1263	pub id: String,
1264	/// A username or a workspace's slug.
1265	pub slug: String,
1266	/// A person's display name or a workspace's name.
1267	pub name: Option<String>,
1268	/// A person's bio or a workspace's description.
1269	pub bio: Option<String>,
1270	pub avatar: Option<String>,
1271	/// RFC 3339.
1272	pub created_at: String,
1273	}
1274
1275	#[derive(Clone, Debug, Default, Serialize, Deserialize)]
1276	pub struct DirectoryPage {
1277	pub entries: Vec<DirectoryEntry>,
1278	/// Where the next page starts; null on the last.
1279	pub next: Option<String>,
1280	}
1281
1282	// --- Invites ---------------------------------------------------------------
1283	//
1284	// An invitation into a workspace or onto a repository, sent to an address
1285	// without an account, carries an invite code: registering with it applies
1286	// the invitation once the address is confirmed. Anyone may register
1287	// without one. See services/identity/src/invites.rs.
1288
1289	/// How long an invite works, unless identity's `INVITE_TTL_DAYS` var says
1290	/// otherwise.
1291	pub const INVITE_TTL_DAYS: u64 = 30;
1292
1293	/// Where an invite stands. Only a pending invite can be used. A pending
1294	/// invite can be revoked, and so can one awaiting confirmation.
1295	#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
1296	#[serde(rename_all = "snake_case")]
1297	pub enum InviteStatus {
1298	Pending,
1299	/// Used to make an account that has not confirmed its email address
1300	/// yet. The code is spent; the workspace (or repository) it gives is
1301	/// joined when the address is confirmed, unless it is revoked first.
1302	AwaitingConfirmation,
1303	/// Used to make an account that has confirmed its address, for a
1304	/// workspace it has not yet joined or declined: the workspace
1305	/// invitation waits for the person's answer (`accept_invitation`).
1306	AwaitingAnswer,
1307	Redeemed,
1308	/// Its person declined the workspace it invited them to.
1309	Declined,
1310	Expired,
1311	Revoked,
1312	}
1313
1314	/// What using an invite does.
1315	#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
1316	#[serde(rename_all = "snake_case")]
1317	pub enum InviteKind {
1318	/// Makes a new account, and joins `workspace` when one is set.
1319	Account,
1320	/// An existing account joins `workspace`. Never makes an account.
1321	Workspace,
1322	}
1323
1324	/// One invite, as the person who made it sees it.
1325	#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
1326	#[serde(rename_all = "camelCase")]
1327	pub struct Invite {
1328	pub id: String,
1329	/// The code, such as `g1t-k7m2-q9xd-…`: returned once when the invite
1330	/// is made, and afterwards to whoever made it while it is pending.
1331	/// Null otherwise.
1332	pub code: Option<String>,
1333	/// The code's first group, such as `g1t-k7m2`, to recognise it by.
1334	pub hint: String,
1335	/// Only an account with this address can use it. Null: anyone with
1336	/// the code.
1337	pub email: Option<String>,
1338	pub kind: InviteKind,
1339	/// The workspace it joins, by slug.
1340	pub workspace: Option<String>,
1341	pub status: InviteStatus,
1342	/// Who made it, by username. Null when g1t staff did.
1343	pub invited_by: Option<String>,
1344	/// The account that used it, by username.
1345	pub redeemed_by: Option<String>,
1346	/// RFC 3339.
1347	pub created_at: String,
1348	/// RFC 3339.
1349	pub expires_at: String,
1350	/// RFC 3339.
1351	pub redeemed_at: Option<String>,
1352	/// RFC 3339.
1353	pub revoked_at: Option<String>,
1354	/// The account a workspace invitation is for, by username: someone
1355	/// invited by username, or the account the invite made.
1356	#[serde(default)]
1357	pub invitee: Option<String>,
1358	/// The role `workspace` is joined with. Null when it names none.
1359	#[serde(default)]
1360	pub role: Option<crate::Role>,
1361	/// The staff member who minted it. Only in staff views.
1362	#[serde(default, skip_serializing_if = "Option::is_none")]
1363	pub staff: Option<String>,
1364	}
1365
1366	/// `check_invite`: what an invite code is for, before using it. Returns
1367	/// `Outcome<InvitePreview>`; a code that is unknown, used, revoked or
1368	/// expired gets the same answer, so codes cannot be probed. With
1369	/// `any_status`, a real code that can no longer be used is described
1370	/// instead (its `status` says why), so the page can say whom to ask for a
1371	/// new one; an unknown code still gets the one answer.
1372	#[derive(Debug, Serialize, Deserialize)]
1373	pub struct InviteCodeArgs {
1374	pub code: String,
1375	/// Who is asking, such as the visitor's IP address, for rate limits.
1376	#[serde(default)]
1377	pub client: Option<String>,
1378	/// Who is looking, if signed in: sets `InvitePreview::for_viewer`.
1379	#[serde(default)]
1380	pub viewer: Option<User>,
1381	#[serde(default)]
1382	pub any_status: bool,
1383	/// The `proof` from the invite email's link, if the page was opened
1384	/// from it: sets `InvitePreview::email_proven`.
1385	#[serde(default)]
1386	pub email_proof: Option<String>,
1387	}
1388
1389	/// Someone shown on an invite.
1390	#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
1391	pub struct InviteFrom {
1392	pub username: String,
1393	pub name: Option<String>,
1394	pub avatar: Option<String>,
1395	}
1396
1397	/// A repository an invite code was sent with: using the code accepts the
1398	/// invitation to collaborate on it.
1399	#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
1400	pub struct InviteRepository {
1401	/// `workspace/repo`.
1402	pub name: String,
1403	/// The role it gives, such as `write`.
1404	pub role: String,
1405	}
1406
1407	/// What a valid invite code is for.
1408	#[derive(Clone, Debug, Serialize, Deserialize)]
1409	#[serde(rename_all = "camelCase")]
1410	pub struct InvitePreview {
1411	pub kind: InviteKind,
1412	/// Pending, unless `any_status` asked about a code that is spent.
1413	pub status: InviteStatus,
1414	/// Null when g1t staff sent it.
1415	pub invited_by: Option<InviteFrom>,
1416	pub workspace: Option<ProfileWorkspace>,
1417	/// The repository it accepts an invitation to, if it was sent with one.
1418	pub repository: Option<InviteRepository>,
1419	/// The address it is for, partly hidden, such as `a•••@example.com`.
1420	pub email: Option<String>,
1421	/// The address in full, while it is pending: whoever holds the code
1422	/// was sent it there. Fills in and locks the sign-up form.
1423	pub address: Option<String>,
1424	/// Whether the address it is for has a g1t account already, so the
1425	/// page asks them to sign in rather than sign up.
1426	pub has_account: bool,
1427	/// With a viewer: whether the invite is theirs (it is for one of their
1428	/// confirmed addresses, or they used it). Null without a viewer or,
1429	/// for a pending invite, when it is for anyone with the code.
1430	pub for_viewer: Option<bool>,
1431	/// RFC 3339.
1432	pub expires_at: String,
1433	/// Whether `email_proof` was this pending invite's own, from the email
1434	/// it was sent in: the account made with it starts with `address`
1435	/// confirmed. False without a proof, with a wrong one, and for an
1436	/// invite bound to no address.
1437	#[serde(default)]
1438	pub email_proven: bool,
1439	}
1440
1441	/// `accept_invite`: a signed-in person uses a workspace invite made for
1442	/// their confirmed address, and joins the workspace, or an invite sent with
1443	/// a repository invitation, and accepts it. Returns `Outcome<String>`: the
1444	/// workspace's slug, or `workspace/repo`.
1445	#[derive(Debug, Serialize, Deserialize)]
1446	pub struct AcceptInviteArgs {
1447	pub user: User,
1448	pub code: String,
1449	}
1450
1451	/// `invite_member`: an owner invites an email address into a workspace.
1452	/// It always makes an invite bound to that address and emails it, so the
1453	/// answer never says whether the address has an account. Without one, the
1454	/// invite registers and joins in one step. Returns `Outcome<Invite>`, with
1455	/// the code.
1456	#[derive(Debug, Serialize, Deserialize)]
1457	pub struct InviteMemberArgs {
1458	pub actor: User,
1459	pub slug: String,
1460	/// An email address. Give this or `username`.
1461	#[serde(default)]
1462	pub email: String,
1463	/// A g1t username: that account gets a workspace invitation to accept
1464	/// or decline, in its inbox and by email. Nobody joins without saying
1465	/// yes.
1466	#[serde(default)]
1467	pub username: Option<String>,
1468	/// The role they join with; member when absent.
1469	#[serde(default)]
1470	pub role: Option<crate::Role>,
1471	/// A note from whoever invites, quoted in the invitation email. Up to
1472	/// [`MAX_INVITE_MESSAGE`] characters; longer is cut, blank is none.
1473	#[serde(default)]
1474	pub message: Option<String>,
1475	/// Where the request came in, for the audit log; g1t.sh when absent.
1476	#[serde(default)]
1477	pub surface: Option<crate::audit::Surface>,
1478	}
1479
1480	/// The most characters an invitation's note keeps.
1481	pub const MAX_INVITE_MESSAGE: usize = 500;
1482
1483	/// A workspace invitation waiting for its person's answer, as they see it.
1484	/// `list_invitations` (takes `UserArgs`) returns `Vec<WorkspaceInvitation>`,
1485	/// newest first: pending ones only, never expired, revoked or answered.
1486	#[derive(Clone, Debug, Serialize, Deserialize)]
1487	#[serde(rename_all = "camelCase")]
1488	pub struct WorkspaceInvitation {
1489	pub id: String,
1490	pub workspace: ProfileWorkspace,
1491	/// The role accepting joins with.
1492	pub role: crate::Role,
1493	/// Null when g1t staff sent it.
1494	pub invited_by: Option<InviteFrom>,
1495	/// RFC 3339.
1496	pub created_at: String,
1497	/// RFC 3339.
1498	pub expires_at: String,
1499	}
1500
1501	/// `accept_invitation`: the person it is for joins the workspace with the
1502	/// role it names. Returns `Outcome<String>`, the workspace's slug.
1503	///
1504	/// `decline_invitation`: they say no; whoever sent it is told in their
1505	/// inbox. Returns `Outcome<bool>`.
1506	#[derive(Debug, Serialize, Deserialize)]
1507	pub struct InvitationArgs {
1508	pub user: User,
1509	pub id: String,
1510	/// Where the request came in, for the audit log; g1t.sh when absent.
1511	#[serde(default)]
1512	pub surface: Option<crate::audit::Surface>,
1513	}
1514
1515	/// `find_people`: accounts whose username starts with `query`, or whose
1516	/// name contains it, for picking someone to invite. Only what a profile
1517	/// shows: a username, a name and an avatar, never an email address.
1518	/// Returns `Vec<InviteFrom>`, at most `limit` (10 at most, 8 when absent).
1519	#[derive(Debug, Serialize, Deserialize)]
1520	pub struct FindPeopleArgs {
1521	pub query: String,
1522	#[serde(default)]
1523	pub limit: Option<u32>,
1524	}
1525
1526	/// `workspace_invites` (takes `ListMembersArgs`): a workspace's invites,
1527	/// newest first. Owners only. Returns `Outcome<Vec<Invite>>`.
1528	///
1529	/// `revoke_workspace_invite`: owners only. Returns `Outcome<Invite>`.
1530	///
1531	/// `resend_workspace_invite`: owners only. Sends a pending invitation
1532	/// again, by email to the address it is bound to or the invited account's
1533	/// confirmed address, and again in that account's inbox. The invitation
1534	/// itself is unchanged: same code, same day it stops working. Returns
1535	/// `Outcome<Invite>`; one that is not pending answers `409`.
1536	#[derive(Debug, Serialize, Deserialize)]
1537	pub struct WorkspaceInviteArgs {
1538	pub actor: User,
1539	pub slug: String,
1540	pub id: String,
1541	}
1542
1543	// --- Invites, staff only ---
1544
1545	/// The most rows one staff listing of invites returns.
1546	pub const ADMIN_INVITES_LIMIT: usize = 500;
1547
1548	/// `admin_invites`: every invite, newest first, at most
1549	/// [`ADMIN_INVITES_LIMIT`], optionally only those whose code starts with
1550	/// `query`, or whose email, inviter or redeemer contains it. Returns
1551	/// `Vec<Invite>`.
1552	#[derive(Debug, Default, Serialize, Deserialize)]
1553	pub struct AdminInvitesArgs {
1554	#[serde(default)]
1555	pub query: Option<String>,
1556	}
1557
1558	/// `admin_revoke_invite`: revokes any pending invite. Returns
1559	/// `Outcome<Invite>`.
1560	#[derive(Debug, Serialize, Deserialize)]
1561	pub struct AdminRevokeInviteArgs {
1562	pub id: String,
1563	pub staff: String,
1564	}
1565
1566	// --- Suspension and blocked email domains, staff only ---
1567	//
1568	// See services/identity/src/suspension.rs. A suspended account cannot sign
1569	// in, and its sessions and tokens stop working at once; a suspended
1570	// workspace's own tokens stop working, and sudo also puts a hold on its
1571	// compute (billing), which stops its runs, deploys, new self-hosted
1572	// runners and telemetry. Both are undone the same way. A blocked email
1573	// domain makes no new accounts and confirms no new addresses.
1574
1575	/// Why and since when staff suspended an account or a workspace.
1576	#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
1577	#[serde(rename_all = "camelCase")]
1578	pub struct Suspension {
1579	pub reason: String,
1580	/// RFC 3339.
1581	pub at: String,
1582	/// The staff member, by email.
1583	pub by: String,
1584	}
1585
1586	/// `admin_suspend_user` (`name` a username) and `admin_suspend_workspace`
1587	/// (`name` a slug): `suspend` true suspends with `reason` (required),
1588	/// false lifts it. Returns `Outcome<Option<Suspension>>`: what stands now.
1589	#[derive(Debug, Serialize, Deserialize)]
1590	pub struct AdminSuspendArgs {
1591	pub name: String,
1592	pub suspend: bool,
1593	#[serde(default)]
1594	pub reason: String,
1595	pub staff: String,
1596	}
1597
1598	/// An email domain no new account may sign up with.
1599	#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
1600	#[serde(rename_all = "camelCase")]
1601	pub struct BlockedDomain {
1602	/// Lowercased, such as `spam.example`. Its subdomains are blocked too.
1603	pub domain: String,
1604	pub reason: String,
1605	pub blocked_by: String,
1606	/// RFC 3339.
1607	pub created_at: String,
1608	}
1609
1610	/// `admin_blocked_domains` takes `{}` and returns `Vec<BlockedDomain>`.
1611	///
1612	/// `admin_block_domain`: `block` true blocks `domain` with `reason`,
1613	/// false unblocks it. Returns `Outcome<Vec<BlockedDomain>>`, the list now.
1614	#[derive(Debug, Serialize, Deserialize)]
1615	pub struct AdminBlockDomainArgs {
1616	pub domain: String,
1617	pub block: bool,
1618	#[serde(default)]
1619	pub reason: String,
1620	pub staff: String,
1621	}
1622
1623	// --- Shared invite links ---
1624	//
1625	// Before registration opened, staff handed groups shared invite links.
1626	// None are made or used any more; staff still see which one an account
1627	// was made with.
1628
1629	/// The shared invite link an account was made with.
1630	#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
1631	pub struct SharedInviteSource {
1632	pub id: String,
1633	pub label: String,
1634	}
1635
1636	#[cfg(test)]
1637	mod deletion_tests {
1638	use super::{WorkspaceDeletion, protected_names};
1639
1640	#[test]
1641	fn only_billing_or_protection_stands_in_the_way() {
1642	let clear = WorkspaceDeletion {
1643	repositories: 2,
1644	projects: 1,
1645	members: 3,
1646	..WorkspaceDeletion::default()
1647	};
1648	assert!(!clear.blocked());
1649	assert_eq!(clear.reason("acme"), None);
1650	let owing = WorkspaceDeletion {
1651	billing: Some("Pay first.".into()),
1652	..WorkspaceDeletion::default()
1653	};
1654	assert!(owing.blocked());
1655	assert_eq!(owing.reason("acme").as_deref(), Some("Pay first."));
1656	let protected = WorkspaceDeletion {
1657	billing: Some("Pay first.".into()),
1658	protected: true,
1659	..WorkspaceDeletion::default()
1660	};
1661	assert!(protected.blocked());
1662	assert_eq!(
1663	protected.reason("flagon-io").as_deref(),
1664	Some("flagon-io is protected and can never be deleted.")
1665	);
1666	}
1667
1668	#[test]
1669	fn flagon_is_protected_whatever_the_variable_says() {
1670	assert_eq!(protected_names(None), ["flagon-io"]);
1671	assert_eq!(protected_names(Some("")), ["flagon-io"]);
1672	assert_eq!(protected_names(Some(" , ")), ["flagon-io"]);
1673	assert_eq!(
1674	protected_names(Some("Flagon-IO, acme ,wsp_1")),
1675	["flagon-io", "acme", "wsp_1"]
1676	);
1677	}
1678	}