Skip to content
Sign in

flagon-io/g1t

public
0

g1t/crates/contracts/src/identity.rs

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