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.

git agents cloudflare rust forge mcp

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