Skip to content
Sign in

flagon-io/g1t

public
0

g1t/packages/contracts/src/identity.ts

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