Skip to content
Sign up

flagon-io/g1t

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