Skip to content
Sign in

flagon-io/g1t

public
0

g1t/packages/contracts/src/identity.ts

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