Skip to content
Sign in

flagon-io/g1t

public
0
903 linesCodeBlameRaw
1import type { AccessClient, BasePermission, RepoGrant } from "./access";
2import type { PermissionAccess, RepositorySelection } from "./fine-grained";
3import type { MemberPrivileges, OrgRole, PolicyHold } from "./members";
4import type { Acting, CreateRunCredentialInput, RunBinding } from "./audit";
5import type { RepoPath } from "./repos";
6import type { Result } from "./result";
7import type { TeamCreation, TeamsClient } from "./teams";
8import type { DeployKeysClient } from "./deploy-keys";
9
10export type User = {
11 id: string;
12 username: string;
13 /**
14 * `workspace` when a workspace is acting through one of its own access
15 * tokens: `id` is then the workspace's and `username` its slug. `system`
16 * is g1t itself doing platform work, such as a security update
17 * (`username` `g1t`). Absent means `user`.
18 */
19 kind?: "user" | "workspace" | "agent" | "system";
20 /**
21 * Whether the account's email address is confirmed. Only set on users
22 * resolved from credentials; unverified accounts cannot change anything.
23 */
24 verified?: boolean;
25 /**
26 * The workspaces this user belongs to. Set on users resolved from
27 * credentials, so any service can authorize from it.
28 */
29 workspaces?: Membership[];
30 /**
31 * The person's uploaded avatar: the SHA-256 of its bytes, served at
32 * `/avatars/<avatar>`. Only set on the signed-in person; absent means
33 * the generated letter avatar.
34 */
35 avatar?: string;
36 /**
37 * Set on an agent resolved from its token: who it acts for ("g1t
38 * on behalf of syntaqx"), with which credential, and what it may do.
39 */
40 acting?: Acting;
41 /**
42 * The repositories this user has a role on directly, whether or not they
43 * belong to its workspace. Set with `workspaces`; see `access.ts`.
44 */
45 grants?: RepoGrant[];
46 /**
47 * Set on a user resolved from an access token: its scopes (null for full
48 * access) and the workspaces or repositories it reaches. See scopes.ts.
49 */
50 token?: {
51 token_id: string;
52 scopes?: string[] | null;
53 legacy?: boolean;
54 /** The token's name, as its owner gave it. */
55 name?: string;
56 /** A fine-grained token's reach: its resource owner and repositories. */
57 fine_grained?: {
58 workspace?: string | null;
59 repositories?: "all" | "selected" | "public";
60 repo_ids?: string[];
61 };
62 /** A workspace's own token an owner gave Admin. */
63 admin?: boolean;
64 /** Set on what a deploy key resolves to. */
65 deploy_key?: string;
66 /** The one repository a job's token or a deploy key reaches. */
67 repo?: string;
68 };
69 /**
70 * Workspaces the person belongs to but cannot use until they meet its
71 * policy, such as turning on two-factor authentication. Left out of
72 * `workspaces` and `grants` meanwhile.
73 */
74 held?: PolicyHold[];
75};
76
77/** What a member may do: an owner also manages the workspace's members. */
78export type Role = "owner" | "member";
79
80export type Membership = {
81 /** The workspace's name in URLs: `g1t.sh/<slug>`. */
82 slug: string;
83 role: Role;
84 /** Its display name. Set on users resolved from credentials. */
85 name?: string;
86 /** Its uploaded icon, as `Workspace.avatar`. */
87 avatar?: string;
88 /** The workspace's base permission: what members get on every repository. Absent means `write`. */
89 base_permission?: BasePermission;
90 /** Who may create its teams. Absent means any member. */
91 team_creation?: TeamCreation;
92 /** The roles held besides owner or member. */
93 org_roles?: OrgRole[];
94 /** What the workspace lets its members do. Absent means the defaults. */
95 privileges?: MemberPrivileges;
96};
97
98/** How long an old workspace slug redirects, and stays reserved for it, after a rename. */
99export const SLUG_HOLD_DAYS = 90;
100
101/** How long a workspace must wait between renames. */
102export const RENAME_COOLDOWN_HOURS = 24;
103
104/** The largest avatar that can be uploaded, in bytes. */
105export const MAX_AVATAR_BYTES = 1024 * 1024;
106
107/**
108 * Where a workspace keeps its repositories' git data: anywhere g1t stores
109 * it (the default), or in the EU only. It applies to repositories made
110 * after it is set.
111 */
112export type DataResidency = "anywhere" | "eu";
113
114/**
115 * A workspace: the owner of repositories, and the first segment of their
116 * URLs. A person's own space and a team's are the same thing.
117 */
118export type Workspace = {
119 id: string;
120 slug: string;
121 name: string;
122 /** One line saying what the workspace is for. */
123 description: string | null;
124 /** RFC 3339. */
125 createdAt: string;
126 memberCount: number;
127 /**
128 * The workspace's uploaded icon: the SHA-256 of its bytes, served at
129 * `/avatars/<avatar>`. Null means the generated letter avatar.
130 */
131 avatar: string | null;
132 /** What every member gets on each repository; owners have Admin. */
133 basePermission?: BasePermission;
134 /** Who may create its teams. Absent means any member. */
135 teamCreation?: TeamCreation;
136 /** Whether members and outside collaborators need two-factor authentication. */
137 twoFactorRequirementEnabled?: boolean;
138} & Partial<MemberPrivileges>;
139
140export type Member = {
141 username: string;
142 role: Role;
143 /** The roles they hold besides `role`. */
144 org_roles?: OrgRole[];
145 /** Whether two-factor authentication is on; owners only, null for anyone else. */
146 two_factor?: boolean | null;
147 /** Their display name, when they set one. */
148 name?: string | null;
149 /** Their uploaded avatar's hash, served at `/avatars/<avatar>`; null for the generated letter avatar. */
150 avatar?: string | null;
151};
152
153/** An owner of a workspace, as staff see them. */
154export type AdminOwner = { username: string; email: string | null };
155
156/** A workspace as staff see it. Mirrors `AdminWorkspace` in `crates/contracts/src/identity.rs`. */
157export type AdminWorkspace = {
158 slug: string;
159 name: string;
160 /** RFC 3339. */
161 createdAt: string;
162 owners: AdminOwner[];
163 memberCount: number;
164};
165
166/** A member of a workspace, as staff see them. */
167export type AdminMember = { username: string; email: string | null; role: Role; /** RFC 3339. */ joined: string };
168
169export type AdminWorkspaceDetail = {
170 slug: string;
171 name: string;
172 description: string | null;
173 /** RFC 3339. */
174 createdAt: string;
175 /** Owners first, then by username. */
176 members: AdminMember[];
177 /** It can never be deleted, by anyone (identity's `PROTECTED_WORKSPACES`). */
178 protected: boolean;
179};
180
181/** The most workspaces one `workspaces` call returns. */
182export const ADMIN_WORKSPACES_LIMIT = 500;
183
184/**
185 * Whether anyone may make an account, or only someone with an invite.
186 * Identity's `REGISTRATION_MODE`; unset means `invite`.
187 */
188export type RegistrationMode = "invite" | "open";
189
190/** How many invites a person may have out at once, unless identity's `INVITES_PER_USER` says otherwise. */
191export const INVITES_PER_USER = 5;
192/** How long an invite works, unless identity's `INVITE_TTL_DAYS` says otherwise. */
193export const INVITE_TTL_DAYS = 30;
194
195/** Only a pending invite can be used or revoked. Revoked and expired ones never used give the invite back. */
196export type InviteStatus = "pending" | "redeemed" | "expired" | "revoked";
197
198/** One invite. Mirrors `Invite` in `crates/contracts/src/identity.rs`. */
199export type Invite = {
200 id: string;
201 /** `g1t-k7m2-…`: returned when it is made, and to its maker while pending. */
202 code: string | null;
203 /** The code's first group, such as `g1t-k7m2`. */
204 hint: string;
205 /** Only this address can use it. */
206 email: string | null;
207 /** `account` makes an account; `workspace` joins an existing one to `workspace`. */
208 kind: "account" | "workspace";
209 /** The workspace using it joins. */
210 workspace: string | null;
211 status: InviteStatus;
212 /** Whose allowance it used. */
213 chargedTo: "user" | "workspace" | "none";
214 /** Its maker's username; null when g1t staff made it. */
215 invitedBy: string | null;
216 /** The account that used it. */
217 redeemedBy: string | null;
218 /** RFC 3339. */
219 createdAt: string;
220 /** RFC 3339. */
221 expiresAt: string;
222 redeemedAt: string | null;
223 revokedAt: string | null;
224 /** The staff member who minted it; only in staff views. */
225 staff?: string | null;
226};
227
228/** How many invites someone may have out. `limit` and `remaining` are null for no limit. */
229export type Allowance = { limit: number | null; used: number; remaining: number | null };
230
231export type InvitesOverview = {
232 mode: RegistrationMode;
233 allowance: Allowance;
234 /** Workspaces the person owns that were granted invites to share. */
235 workspaces: { slug: string; allowance: Allowance }[];
236 invites: Invite[];
237};
238
239/** What a valid code is for, before it is used. */
240export type InvitePreview = {
241 kind: "account" | "workspace";
242 /** Pending, unless `anyStatus` asked about a code that is spent. */
243 status: InviteStatus;
244 /** Null when g1t staff sent it. */
245 invitedBy: { username: string; name: string | null; avatar: string | null } | null;
246 workspace: ProfileWorkspace | null;
247 /** The repository it accepts an invitation to, such as `{ name: "flagon-io/g1t", role: "write" }`. */
248 repository: { name: string; role: string } | null;
249 /** Partly hidden, such as `a•••@example.com`. */
250 email: string | null;
251 /** The bound address in full, while the invite is pending: it fills in and locks the sign-up form. */
252 address: string | null;
253 /** Whether the bound address has a g1t account already: sign in to accept. */
254 hasAccount: boolean;
255 /** With a viewer: whether it is theirs (for one of their confirmed addresses, or used by them). */
256 forViewer: boolean | null;
257 expiresAt: string;
258};
259
260export type WaitlistStatus = "waiting" | "invited" | "dismissed";
261
262export type WaitlistEntry = {
263 id: string;
264 email: string;
265 about: string | null;
266 status: WaitlistStatus;
267 inviteId: string | null;
268 decidedBy: string | null;
269 decidedAt: string | null;
270 /** What staff wrote when approving; it went in the invite email. */
271 note: string | null;
272 /** The account made with the invite, once it was used. */
273 joinedAs: string | null;
274 /** When they first asked. */
275 createdAt: string;
276 /** When they last asked. */
277 updatedAt: string;
278};
279
280export type InviteGrant = { amount: number; note: string | null; grantedBy: string; createdAt: string };
281export type InviteTreeNode = { username: string; joinedAt: string; invited: InviteTreeNode[] };
282
283/** Where a person came from and whom they brought. For a workspace, `username` is its slug. */
284export type InviteTree = {
285 username: string;
286 /** Who invited them, then who invited that person, and so on. */
287 invitedBy: string[];
288 /** The staff member who minted their invite, when staff did. */
289 staff: string | null;
290 allowance: Allowance;
291 grants: InviteGrant[];
292 invites: Invite[];
293 /** Whom they invited, three levels down. */
294 invited: InviteTreeNode[];
295};
296
297/** The most rows one staff listing of invites or the waitlist returns. */
298export const ADMIN_INVITES_LIMIT = 500;
299
300/**
301 * Staff-only identity, for sudo.g1t.sh. It takes no viewer and checks no
302 * membership: only sudo calls it, over its service binding, once Cloudflare
303 * Access and its staff list have let someone in. Never call it on behalf of
304 * a customer.
305 */
306export interface IdentityAdminApi {
307 /** Every workspace, newest first, at most 500; `query` matches slug, name, or an owner's username or email. */
308 workspaces(query?: string): Promise<AdminWorkspace[]>;
309 /** One workspace with all its members, or null. */
310 workspace(slug: string): Promise<AdminWorkspaceDetail | null>;
311
312 /** The waitlist, newest first; `query` matches the address or what they said. */
313 waitlist(query?: string | null, status?: WaitlistStatus | null): Promise<WaitlistEntry[]>;
314 /** How many requests are waiting, for the navigation's badge. */
315 waitlistPending(): Promise<number>;
316 /**
317 * Approving mints an invite bound to the address and emails it, with
318 * `note` (up to 500 characters) if given; dismissing only marks it.
319 */
320 decideWaitlist(id: string, approve: boolean, staff: string, note?: string | null): Promise<Result<WaitlistEntry>>;
321 /** Invites, newest first; `query` is a code's start, or part of an email, inviter or redeemer. */
322 invites(query?: string | null): Promise<Invite[]>;
323 revokeInvite(id: string, staff: string): Promise<Result<Invite>>;
324 /** An invite that uses nobody's allowance, optionally bound to (and emailed to) `email`. */
325 mintInvite(email: string | null, staff: string): Promise<Result<Invite>>;
326 /** More invites (or fewer, with a negative amount) for a person or a workspace. */
327 grantInvites(
328 target: "user" | "workspace",
329 name: string,
330 amount: number,
331 note: string,
332 staff: string,
333 ): Promise<Result<Allowance>>;
334 /** Where a person came from and whom they brought, or null. */
335 inviteTree(username: string): Promise<InviteTree | null>;
336 /** A workspace's granted invites and the invites made for it, or null. */
337 workspaceInvites(slug: string): Promise<InviteTree | null>;
338
339 /** Workspaces owners deleted that are not purged yet, newest first. */
340 deletedWorkspaces(): Promise<DeletedWorkspace[]>;
341 /**
342 * Brings a deleted workspace back, with its members, tokens and what went
343 * with it, while it is still restorable. Publishes `workspace.restored`.
344 */
345 restoreWorkspace(workspaceId: string, staff: string): Promise<Result<boolean>>;
346 /**
347 * Purges a deleted workspace now rather than at `purgeAfter`. `confirm` is
348 * its slug, typed out. Refused for a protected workspace. Publishes
349 * `workspace.deleted`.
350 */
351 purgeWorkspace(workspaceId: string, staff: string, confirm: string): Promise<Result<boolean>>;
352
353 /** Every workspace alias, by name. */
354 aliases(): Promise<WorkspaceAlias[]>;
355 /**
356 * Points `alias` at the workspace whose slug is `workspace`. Refused for
357 * one of the site's routes, anyone's username, a workspace's slug (deleted
358 * or held after a rename) and an existing alias. `note` says why.
359 */
360 setAlias(alias: string, workspace: string, note: string, staff: string): Promise<Result<WorkspaceAlias>>;
361 /** Removes an alias; `reason` goes in sudo's audit log. */
362 removeAlias(alias: string, reason: string, staff: string): Promise<Result<boolean>>;
363}
364
365/**
366 * A name g1t's staff point at a workspace, so its addresses lead there under
367 * the workspace's own name: `g1t`, the product, leads to `flagon-io`, Flagon,
368 * Inc. Staff-managed only; it follows the workspace through renames.
369 */
370export type WorkspaceAlias = {
371 alias: string;
372 workspaceId: string;
373 /** The workspace's slug and name now. */
374 workspace: string;
375 workspaceName: string;
376 /** Why it exists. */
377 note: string;
378 /** The staff member who set it, or `migration`. */
379 createdBy: string;
380 /** RFC 3339. */
381 createdAt: string;
382};
383
384/** Who is asking. Every read and write in every service takes one. */
385export type Viewer = User | null;
386
387export type SshKey = {
388 id: string;
389 title: string;
390 fingerprint: string;
391 /** RFC 3339. */
392 createdAt: string;
393 /** When it last signed in over SSH, RFC 3339, to within 5 minutes; null when it never has. */
394 lastUsedAt: string | null;
395};
396
397export type AccessToken = {
398 id: string;
399 name: string;
400 /** RFC 3339. */
401 createdAt: string;
402 /** RFC 3339, to within a few minutes. Null until it is first used. */
403 lastUsedAt: string | null;
404 /**
405 * For a workspace's token, the username of the member who made it. Null
406 * once that account is gone, and on personal tokens.
407 */
408 createdBy: string | null;
409 /** Its scopes, as `resource:level`. Null: full access. */
410 scopes: string[] | null;
411 /** Made before tokens had scopes: full access until someone narrows it. */
412 legacy: boolean;
413 /** RFC 3339. Null: it does not expire. */
414 expiresAt: string | null;
415 /** Classic, fine-grained, or a workspace's own. */
416 kind?: TokenKind;
417 /** What it is for, as its owner wrote it. */
418 description?: string | null;
419 /** A fine-grained token's resource owner, repositories, permissions and status. */
420 fineGrained?: FineGrainedDetails | null;
421 /** A workspace's own token an owner gave Admin when making it. */
422 admin?: boolean;
423};
424
425export type TokenKind = "classic" | "fine_grained" | "workspace";
426
427/** Whether a fine-grained token may be used on its resource owner. */
428export type TokenStatus = "active" | "pending" | "denied" | "revoked";
429
430export type FineGrainedDetails = {
431 /** The resource owner's slug; null for your own account. */
432 workspace: string | null;
433 repositorySelection: RepositorySelection;
434 /** With `selected`: the repositories, as `owner/name`, that you can see. */
435 repositories: string[];
436 permissions: Partial<Record<string, PermissionAccess>>;
437 status: TokenStatus;
438 /** Why an owner denied or revoked it. */
439 reviewReason?: string | null;
440};
441
442/** What a new fine-grained token is. */
443export type FineGrainedTokenInput = {
444 name: string;
445 description?: string | null;
446 /** Between 1 and 366 days, and no more than the workspace allows. */
447 ttlSeconds: number;
448 /** The resource owner: a workspace's slug, or null for your own account. */
449 workspace: string | null;
450 repositorySelection: RepositorySelection;
451 /** With `selected`: `owner/name` or names in the workspace. */
452 repositories: string[];
453 /** Each permission's level by name; names left out are none. */
454 permissions: Record<string, PermissionAccess>;
455};
456
457/** A workspace's rules for personal access tokens. */
458export type TokenPolicy = {
459 allowClassic: boolean;
460 allowFineGrained: boolean;
461 requireApproval: boolean;
462 /** Null: no limit. */
463 maxLifetimeDays: number | null;
464 forbidNoExpiry: boolean;
465 updatedBy?: string | null;
466 updatedAt?: string | null;
467};
468
469/** A member's personal token that reaches a workspace, as its owners see it. */
470export type MemberToken = {
471 owner: string;
472 token: AccessToken;
473 /** Whether it reaches the workspace now. */
474 reaches: boolean;
475 /** Why not: pending approval, denied, revoked, classic tokens not allowed, lasts too long, never expires. */
476 blockedBy?: string | null;
477};
478
479/** What a new or changed token may do. */
480export type TokenGrant = {
481 /** Null: full access. */
482 scopes: string[] | null;
483};
484
485export type DeviceStart = {
486 /** Secret held by the tool and exchanged for a token once approved. */
487 deviceCode: string;
488 /** Short code shown to the person, e.g. `WDJB-MJHT`. */
489 userCode: string;
490 /** Seconds until both codes stop working. */
491 expiresIn: number;
492 /** Seconds the tool should wait between polls. */
493 interval: number;
494};
495
496export type DeviceRequest = { userCode: string; clientName: string };
497
498export type DeviceClaim =
499 | { status: "pending" | "denied" | "expired" }
500 | { status: "approved"; token: string; user: User };
501
502/** What the site passes on once a person has approved an application. */
503export type OAuthApproval = {
504 clientId: string;
505 /** Shown wherever the application's access is listed. */
506 clientName: string;
507 redirectUri: string;
508 /** PKCE challenge, method S256. */
509 codeChallenge: string;
510 /** What the person granted. Null: full access. */
511 scopes: string[] | null;
512};
513
514export type OAuthTokens = {
515 accessToken: string;
516 /** Works once; using it returns the next one. */
517 refreshToken: string;
518 /** Seconds until the access token stops working. */
519 expiresIn: number;
520 /** The scopes granted, space-separated, or `*` for full access. */
521 scope?: string | null;
522};
523
524/** An application a person has signed in to. */
525export type OAuthGrant = {
526 id: string;
527 clientName: string;
528 /** RFC 3339. */
529 createdAt: string;
530 /** RFC 3339. */
531 lastUsedAt: string;
532 /** What the person granted. Null: full access. */
533 scopes: string[] | null;
534 /** Signed in before applications had scopes: full access until narrowed. */
535 legacy: boolean;
536};
537
538/** Accounts, credentials and sessions. */
539/**
540 * What deleting a workspace takes with it, and what stands in the way:
541 * nothing does while `billing` is null and it is not `protected`.
542 */
543export type WorkspaceDeletion = {
544 /** Its live repositories, deleted with it. */
545 repositories: number;
546 /** Its projects, hidden with it. */
547 projects: number;
548 members: number;
549 /** Why billing cannot close it yet, in words for its owner. */
550 billing: string | null;
551 /** It can never be deleted, by anyone. */
552 protected: boolean;
553};
554
555/** How long a deleted workspace is kept, for g1t's staff to restore, before it is purged. */
556export const WORKSPACE_RESTORE_DAYS = 30;
557
558/**
559 * Workspaces nobody can delete, whatever identity's `PROTECTED_WORKSPACES`
560 * says: Flagon's, which runs g1t. Services that act on `workspace.deleting`
561 * check it too, so one published for it by mistake changes nothing.
562 */
563export const ALWAYS_PROTECTED_WORKSPACES: readonly string[] = ["flagon-io"];
564
565/** Whether `slug` is one of `ALWAYS_PROTECTED_WORKSPACES`, in any case. */
566export function isProtectedWorkspace(slug: string): boolean {
567 return ALWAYS_PROTECTED_WORKSPACES.includes(slug.trim().toLowerCase());
568}
569
570/** A workspace an owner deleted, kept until `purgeAfter` for staff to restore. */
571export type DeletedWorkspace = {
572 workspaceId: string;
573 slug: string;
574 name: string;
575 /** RFC 3339. */
576 deletedAt: string;
577 /** The username of the owner who deleted it. */
578 deletedBy: string;
579 /** RFC 3339: when it is purged unless restored first. */
580 purgeAfter: string;
581 /** What went with it, counted when it was deleted. */
582 went: WorkspaceDeletion;
583 /** Whether staff can still restore it. */
584 restorable: boolean;
585};
586
587export interface IdentityApi extends AccessClient, TeamsClient, DeployKeysClient {
588 /**
589 * Creates an account and signs it in. While registration is invite-only,
590 * `inviteCode` must be an unused, unexpired invite (and, when it names an
591 * email, that address); it is ignored while registration is open.
592 */
593 register(
594 username: string,
595 email: string,
596 password: string,
597 inviteCode?: string | null,
598 /** Who is asking, such as the visitor's IP address, for rate limits. */
599 client?: string | null,
600 ): Promise<Result<{ user: User; sessionToken: string }>>;
601 /** Verifies a username and password for website sign-in. */
602 /**
603 * Verifies a username, or any confirmed address of the account, and its
604 * password. Wrong passwords are counted against the account and `client`
605 * (the visitor's IP address); past a limit nothing is checked for a while.
606 */
607 signIn(
608 username: string,
609 password: string,
610 client?: string | null,
611 ): Promise<Result<{ user: User; sessionToken: string; twoFactorChallenge?: string | null }>>;
612 /**
613 * The second step of signing in, for an account with two-factor
614 * authentication: the challenge `signIn` returned, and a code from the
615 * app or a recovery code.
616 */
617 twoFactorSignIn(challenge: string, code: string, client?: string | null): Promise<Result<{ user: User; sessionToken: string }>>;
618 signOut(sessionToken: string): Promise<void>;
619
620 /** Sends the confirmation email again. */
621 resendVerification(user: User): Promise<Result<boolean>>;
622 /** Confirms the address the emailed token was sent to. */
623 verifyEmail(token: string): Promise<Result<User>>;
624 /** Emails a reset link if the address has an account. Always resolves. */
625 /**
626 * Any confirmed address of an account works; the link goes to it, and the
627 * primary and backup are told. A few an hour per address and per `client`.
628 */
629 requestPasswordReset(email: string, client?: string | null): Promise<boolean>;
630 /** Sets a new password from an emailed token and ends every session. */
631 resetPassword(token: string, password: string): Promise<Result<User>>;
632
633 /**
634 * Device sign-in (RFC 8628). A tool starts a request, a person approves
635 * its short code in a browser, and the tool claims an access token.
636 */
637 deviceStart(clientName: string): Promise<DeviceStart>;
638 /** What a user code is asking for, or null if it is not valid. */
639 deviceLookup(userCode: string): Promise<DeviceRequest | null>;
640 deviceResolve(userCode: string, user: User, approve: boolean): Promise<Result<boolean>>;
641 deviceClaim(deviceCode: string): Promise<DeviceClaim>;
642
643 /**
644 * OAuth 2.1 for applications that sign a person in through the browser.
645 * The caller has checked the client and its redirect address; this
646 * returns the one-time code the application exchanges for tokens.
647 */
648 oauthAuthorize(user: User, approval: OAuthApproval): Promise<{ code: string }>;
649 /** Redeems a code. It works once, for that client, with the PKCE verifier. */
650 oauthExchange(code: string, codeVerifier: string, clientId: string, redirectUri: string): Promise<Result<OAuthTokens>>;
651 /** Trades a refresh token for new tokens; the old ones stop working. */
652 oauthRefresh(refreshToken: string, clientId: string): Promise<Result<OAuthTokens>>;
653 /** Applications the user has signed in to, most recently used first. */
654 listOAuthGrants(user: User): Promise<OAuthGrant[]>;
655 /** Signs an application out. */
656 revokeOAuthGrant(user: User, id: string): Promise<void>;
657 /** Changes what an application may do, at once and when it refreshes. */
658 updateOAuthGrant(user: User, id: string, grant: TokenGrant): Promise<Result<OAuthGrant>>;
659
660 createWorkspace(user: User, slug: string, name: string): Promise<Result<Workspace>>;
661 /** Public details of a workspace, or null. */
662 getWorkspace(slug: string): Promise<Workspace | null>;
663 /** Where a workspace keeps its repositories' git data; null when there is no such workspace. */
664 workspaceResidency(slug: string): Promise<DataResidency | null>;
665 /**
666 * Owners only. Applies to repositories made from then on. Offer `eu`
667 * only when the repos service's `storageOptions()` says it is available.
668 */
669 setWorkspaceResidency(actor: User, slug: string, residency: DataResidency): Promise<Result<DataResidency>>;
670 /** Members only. */
671 listMembers(slug: string, viewer: Viewer): Promise<Result<Member[]>>;
672 /** Owners only. */
673 addMember(actor: User, slug: string, username: string): Promise<Result<boolean>>;
674 /** Owners only; your own username is leaving. Never the last owner. */
675 removeMember(actor: User, slug: string, username: string): Promise<Result<boolean>>;
676 /** Owners only: owner or member, and the roles held besides it. Never leaves no owner. */
677 updateMember(actor: User, slug: string, username: string, change: { role?: Role; org_roles?: OrgRole[] }): Promise<Result<Member>>;
678 /** Owners only: `username` becomes an owner, and you a member. */
679 transferOwnership(actor: User, slug: string, username: string): Promise<Result<boolean>>;
680 /** You leave the workspace. Never the last owner. */
681 leaveWorkspace(user: User, slug: string): Promise<Result<boolean>>;
682 /** Owners only: change some member privileges; returns all of them. */
683 setMemberPrivileges(actor: User, slug: string, change: Partial<MemberPrivileges>): Promise<Result<MemberPrivileges>>;
684 /** Owners only, with two-factor on themselves: require it of everyone. */
685 setTwoFactorRequirement(actor: User, slug: string, required: boolean): Promise<Result<boolean>>;
686 /** Owners only. An empty name falls back to the slug. */
687 updateWorkspace(actor: User, slug: string, details: { name: string; description: string }): Promise<Result<Workspace>>;
688 /**
689 * Owners only. Changes the slug, the first segment of the workspace's
690 * URLs; the display name is untouched. The old slug redirects to the new
691 * one, and stays reserved for this workspace, for `SLUG_HOLD_DAYS`.
692 * Publishes `workspace.renamed`.
693 */
694 renameWorkspace(actor: User, slug: string, newSlug: string): Promise<Result<Workspace>>;
695 /** Whether `renameWorkspace` would be allowed, changing nothing. */
696 checkWorkspaceRename(actor: User, slug: string, newSlug: string): Promise<Result<boolean>>;
697 /**
698 * The workspace's current slug when `slug` is one it was renamed from
699 * within `SLUG_HOLD_DAYS`, or when `slug` is an alias staff set for it
700 * (`WorkspaceAlias`); null otherwise, including for a slug in use.
701 */
702 resolveSlug(slug: string): Promise<string | null>;
703 /**
704 * Owners only, a person only. `confirm` is the slug, typed out. Refused
705 * for a protected workspace, and while billing cannot settle it. Its
706 * repositories, projects and apps go with it; it is kept for
707 * `WORKSPACE_RESTORE_DAYS`, when g1t's staff can restore it, then purged.
708 * Its slug is never given to anyone else; the person whose username it is
709 * may make it again once it is purged. Publishes `workspace.deleting`.
710 */
711 deleteWorkspace(actor: User, slug: string, confirm: string): Promise<Result<boolean>>;
712 /** What `deleteWorkspace` would take with it, and what stands in its way, changing nothing. */
713 checkWorkspaceDeletion(actor: User, slug: string): Promise<Result<WorkspaceDeletion>>;
714 /**
715 * Owners only. `image` is the file in base64: PNG, JPEG, WebP or GIF, at
716 * most `MAX_AVATAR_BYTES`, checked by its bytes. Null removes the icon.
717 */
718 setWorkspaceAvatar(actor: User, slug: string, image: string | null): Promise<Result<Workspace>>;
719 /** A person's own avatar, as `setWorkspaceAvatar`: the new one, or null. */
720 setUserAvatar(user: User, image: string | null): Promise<Result<string | null>>;
721
722 /**
723 * A workspace's own access tokens. They belong to the workspace, act as
724 * it, and keep working when the member who made one leaves. Members only.
725 */
726 listWorkspaceTokens(slug: string, viewer: Viewer): Promise<Result<AccessToken[]>>;
727 /** Owners only. The plaintext token is returned once and never stored. */
728 createWorkspaceToken(
729 actor: User,
730 slug: string,
731 name: string,
732 grant?: TokenGrant & { ttlSeconds?: number; admin?: boolean },
733 ): Promise<Result<{ token: string; info: AccessToken }>>;
734 /** Owners only. */
735 removeWorkspaceToken(actor: User, slug: string, id: string): Promise<Result<boolean>>;
736
737 /**
738 * A fine-grained personal access token: one resource owner, some of its
739 * repositories, a level for each permission. People only. It starts
740 * pending when its workspace asks for approval and you are not an owner.
741 */
742 createFineGrainedToken(user: User, input: FineGrainedTokenInput): Promise<Result<{ token: string; info: AccessToken }>>;
743 /** Its owner changes it; what is left out stays. Widening it asks for approval again. */
744 updateFineGrainedToken(
745 user: User,
746 id: string,
747 change: Partial<Omit<FineGrainedTokenInput, "ttlSeconds" | "workspace">>,
748 ): Promise<Result<AccessToken>>;
749 /** A workspace's rules for personal access tokens. Members only. */
750 getTokenPolicy(slug: string, viewer: Viewer): Promise<Result<TokenPolicy>>;
751 /** Owners only, as people. `maxLifetimeDays` of 0 removes the limit. */
752 setTokenPolicy(
753 actor: User,
754 slug: string,
755 change: Partial<Omit<TokenPolicy, "updatedBy" | "updatedAt">>,
756 ): Promise<Result<TokenPolicy>>;
757 /** The members' tokens that can reach a workspace. Owners only. */
758 listMemberTokens(
759 actor: User,
760 slug: string,
761 filter?: { status?: TokenStatus; kind?: TokenKind },
762 ): Promise<Result<MemberToken[]>>;
763 /** Approve or deny a fine-grained token waiting for approval. Owners only. */
764 reviewTokenRequest(actor: User, slug: string, id: string, approve: boolean, reason?: string | null): Promise<Result<MemberToken>>;
765 /** Take a member's token out of the workspace. Owners only. */
766 revokeMemberToken(actor: User, slug: string, id: string, reason?: string | null): Promise<Result<boolean>>;
767
768 userForSession(sessionToken: string): Promise<Viewer>;
769
770 /** Whether registration is invite-only. */
771 registration(): Promise<RegistrationMode>;
772 /** A person's invites and what they have left. */
773 listInvites(user: User): Promise<InvitesOverview>;
774 /**
775 * A person makes an invite, optionally for one address (emailed to it),
776 * using one of theirs or, with `workspace`, one the workspace was granted.
777 * People only: never an agent or a workspace's token.
778 */
779 createInvite(user: User, options?: { email?: string | null; workspace?: string | null }): Promise<Result<Invite>>;
780 /** Its maker, or an owner of its workspace, revokes a pending invite; the invite comes back. */
781 revokeInvite(user: User, id: string): Promise<Result<Invite>>;
782 /**
783 * What a code is for. Unknown, used, revoked and expired codes all get the
784 * same answer, unless `anyStatus`: then a real code that is spent is
785 * described, with its `status`. `viewer` sets `forViewer`.
786 */
787 checkInvite(
788 code: string,
789 client?: string | null,
790 options?: { viewer?: User | null; anyStatus?: boolean },
791 ): Promise<Result<InvitePreview>>;
792 /**
793 * A signed-in person uses a workspace invite sent to their address, or one
794 * sent with a repository invitation; returns the workspace's slug, or
795 * `workspace/repo`.
796 */
797 acceptInvite(user: User, code: string): Promise<Result<string>>;
798 /** Owners only. Invites an address into a workspace, always with an invite bound to it. */
799 inviteMember(actor: User, slug: string, email: string): Promise<Result<Invite>>;
800 /** Owners only: the workspace's invites, newest first. */
801 workspaceInvites(slug: string, viewer: Viewer): Promise<Result<Invite[]>>;
802 /** Owners only. */
803 revokeWorkspaceInvite(actor: User, slug: string, id: string): Promise<Result<Invite>>;
804 /** Someone without an invite asks for one. Always the same answer for a valid address. */
805 requestAccess(email: string, about: string, client?: string | null): Promise<Result<boolean>>;
806
807 /** Verifies git credentials: the account password or an access token. */
808 userForGitCredentials(username: string, secret: string): Promise<Viewer>;
809 /** Resolves a `g1t_…` access token, as sent to the API and MCP server. */
810 userForAccessToken(token: string): Promise<Viewer>;
811 userForSshKey(fingerprint: string): Promise<Viewer>;
812 userByUsername(username: string): Promise<Viewer>;
813 /** The names behind account and workspace ids; unknown ids are left out. */
814 usernames(ids: string[]): Promise<Record<string, string>>;
815
816 /** A person's public profile, or null if there is no such account. Never an email address. */
817 profile(username: string): Promise<Profile | null>;
818 /** A person changes their own profile. Every field is replaced; an empty one is cleared. */
819 updateProfile(actor: User, fields: ProfileFields): Promise<Result<Profile>>;
820 /**
821 * The workspaces a profile shows `viewer`: those the viewer belongs to
822 * as well, and those of `publicIn` (where the person made a public
823 * project) that the person really belongs to. Nothing else.
824 */
825 profileWorkspaces(username: string, viewer: Viewer, publicIn: string[]): Promise<ProfileWorkspace[]>;
826
827 listSshKeys(user: User): Promise<SshKey[]>;
828 /** Takes one line in OpenSSH public key format. */
829 addSshKey(user: User, title: string, publicKey: string): Promise<Result<SshKey>>;
830 removeSshKey(user: User, id: string): Promise<void>;
831
832 listAccessTokens(user: User): Promise<AccessToken[]>;
833 /**
834 * The plaintext token is returned once and never stored. With
835 * `ttlSeconds` the token expires and is left out of token lists; that
836 * form is used for hosted agents. A token made for a workspace acting
837 * through a token of its own belongs to that workspace too.
838 */
839 createAccessToken(
840 user: User,
841 name: string,
842 ttlSeconds?: number,
843 grant?: TokenGrant & { listed?: boolean },
844 ): Promise<{ token: string; info: AccessToken }>;
845 /** Changes what one of a person's tokens may do; the token is unchanged. */
846 updateAccessToken(user: User, id: string, grant: TokenGrant): Promise<Result<AccessToken>>;
847 /**
848 * A token for a g1t agent working for `onBehalfOf`: it acts as
849 * `g1t`, in `scope.repo` only, and only for `scope.operations`.
850 */
851 createAgentToken(
852 onBehalfOf: User,
853 scope: AgentScope,
854 ttlSeconds: number,
855 ): Promise<{ token: string; info: AccessToken }>;
856 removeAccessToken(user: User, id: string): Promise<void>;
857 /**
858 * A token for one sandbox run: it acts as the agent on behalf of
859 * `onBehalfOf`, can do only what the run's kind needs in `repo`, and
860 * expires after `ttlSeconds`. See `audit.ts`.
861 */
862 createRunCredential(input: CreateRunCredentialInput): Promise<{ token: string; info: AccessToken }>;
863 /** Ties tokens, by the SHA-256 of their text in hex, to the agent run their sandbox recorded. */
864 bindRunCredentials(tokenHashes: string[], runId: string): Promise<boolean>;
865 /** Ends a sandbox's run credentials, by hash or by run. Never touches another token. */
866 revokeRunCredentials(target: { tokenHashes?: string[]; runId?: string | null }): Promise<boolean>;
867}
868
869
870/** What an agent's token may do: these operations, in this repository. */
871export type AgentScope = { repo: RepoPath; operations: string[]; run?: RunBinding };
872
873/** The most characters each profile field takes. Mirrors `crates/contracts/src/identity.rs`. */
874export const PROFILE_LIMITS = { name: 80, bio: 160, location: 80, website: 200, pronouns: 40 } as const;
875
876/** What anyone may see about a person, at `g1t.sh/u/<username>`. */
877export type Profile = {
878 username: string;
879 /** The name they go by, if they gave one. */
880 name: string | null;
881 bio: string | null;
882 location: string | null;
883 /** Always an `https://` address. */
884 website: string | null;
885 pronouns: string | null;
886 /** The uploaded avatar's hash, served at `/avatars/<avatar>`. */
887 avatar: string | null;
888 /** When the account was made. RFC 3339. */
889 createdAt: string;
890};
891
892/** What a person may change on their profile. Empty clears a field. */
893export type ProfileFields = {
894 name: string;
895 bio: string;
896 location: string;
897 /** `https://…`; a bare `example.com` is taken as `https://example.com`. */
898 website: string;
899 pronouns: string;
900};
901
902/** A workspace on a person's profile. */
903export type ProfileWorkspace = { slug: string; name: string; avatar: string | null };