Skip to content
Sign up

flagon-io/g1t

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