Skip to content
Sign in

flagon-io/g1t

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