Sign in

flagon-io/g1t

public

g1t/packages/contracts/src/identity.ts

705 lines28,837 bytesCodeBlame

Pick any line to see why it is the way it is: the commit, the pull request and issue it came from, and what the agent was thinking.

Invite-only launch: sign in with GitHub, repository access and lifecycle, many emails, a new look1import type { AccessClient, BasePermission, RepoGrant } from "./access";
Agents get guardrails, run credentials, an audit log, a context hub, repository instructions and mentions; security upkeep; snake_case API2import type { Acting, CreateRunCredentialInput, RunBinding } from "./audit";
Agents as a team: lifecycle, merge queue, billing and a new shell3import type { RepoPath } from "./repos";
Initial g1t: services, event bus, intents and attempts4import type { Result } from "./result";
5
Email verification, password reset, and Git for AI scale positioning6export type User = {
7 id: string;
8 username: string;
9 /**
Agents as a team: lifecycle, merge queue, billing and a new shell10 * `workspace` when a workspace is acting through one of its own access
Git storage hardened, pages in tens of milliseconds, honest security alerts, and costs reconciled daily11 * tokens: `id` is then the workspace's and `username` its slug. `system`
12 * is g1t itself doing platform work, such as a security update
13 * (`username` `g1t`). Absent means `user`.
Agents as a team: lifecycle, merge queue, billing and a new shell14 */
Git storage hardened, pages in tens of milliseconds, honest security alerts, and costs reconciled daily15 kind?: "user" | "workspace" | "agent" | "system";
Agents as a team: lifecycle, merge queue, billing and a new shell16 /**
Email verification, password reset, and Git for AI scale positioning17 * Whether the account's email address is confirmed. Only set on users
18 * resolved from credentials; unverified accounts cannot change anything.
19 */
20 verified?: boolean;
Workspaces own repositories21 /**
22 * The workspaces this user belongs to. Set on users resolved from
23 * credentials, so any service can authorize from it.
24 */
25 workspaces?: Membership[];
Workspace names and icons, and a component kit for every control26 /**
27 * The person's uploaded avatar: the SHA-256 of its bytes, served at
28 * `/avatars/<avatar>`. Only set on the signed-in person; absent means
29 * the generated letter avatar.
30 */
31 avatar?: string;
Agents get guardrails, run credentials, an audit log, a context hub, repository instructions and mentions; security upkeep; snake_case API32 /**
g1t is one name: its agent's work, commits and comments show as @g1t, and nobody can claim g1t or g1t-agent33 * Set on an agent resolved from its token: who it acts for ("g1t
Agents get guardrails, run credentials, an audit log, a context hub, repository instructions and mentions; security upkeep; snake_case API34 * on behalf of syntaqx"), with which credential, and what it may do.
35 */
36 acting?: Acting;
Invite-only launch: sign in with GitHub, repository access and lifecycle, many emails, a new look37 /**
38 * The repositories this user has a role on directly, whether or not they
39 * belong to its workspace. Set with `workspaces`; see `access.ts`.
40 */
41 grants?: RepoGrant[];
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step42 /**
43 * Set on a user resolved from an access token: its scopes (null for full
44 * access) and the workspaces or repositories it reaches. See scopes.ts.
45 */
46 token?: {
47 token_id: string;
48 scopes?: string[] | null;
49 legacy?: boolean;
50 };
Email verification, password reset, and Git for AI scale positioning51};
Initial g1t: services, event bus, intents and attempts52
Workspaces own repositories53/** What a member may do: an owner also manages the workspace's members. */
54export type Role = "owner" | "member";
55
Workspace names and icons, and a component kit for every control56export type Membership = {
57 /** The workspace's name in URLs: `g1t.sh/<slug>`. */
58 slug: string;
59 role: Role;
60 /** Its display name. Set on users resolved from credentials. */
61 name?: string;
62 /** Its uploaded icon, as `Workspace.avatar`. */
63 avatar?: string;
Invite-only launch: sign in with GitHub, repository access and lifecycle, many emails, a new look64 /** The workspace's base permission: what members get on every repository. Absent means `write`. */
65 base_permission?: BasePermission;
Workspace names and icons, and a component kit for every control66};
Workspaces own repositories67
Agents and memory, checks and conflicts, profiles, slug renames, custom domains68/** How long an old workspace slug redirects, and stays reserved for it, after a rename. */
69export const SLUG_HOLD_DAYS = 90;
70
71/** How long a workspace must wait between renames. */
72export const RENAME_COOLDOWN_HOURS = 24;
73
Workspace names and icons, and a component kit for every control74/** The largest avatar that can be uploaded, in bytes. */
75export const MAX_AVATAR_BYTES = 1024 * 1024;
76
Workspaces own repositories77/**
78 * A workspace: the owner of repositories, and the first segment of their
79 * URLs. A person's own space and a team's are the same thing.
80 */
81export type Workspace = {
82 id: string;
83 slug: string;
84 name: string;
Agents as a team: lifecycle, merge queue, billing and a new shell85 /** One line saying what the workspace is for. */
86 description: string | null;
Workspaces own repositories87 /** RFC 3339. */
88 createdAt: string;
89 memberCount: number;
Workspace names and icons, and a component kit for every control90 /**
91 * The workspace's uploaded icon: the SHA-256 of its bytes, served at
92 * `/avatars/<avatar>`. Null means the generated letter avatar.
93 */
94 avatar: string | null;
Invite-only launch: sign in with GitHub, repository access and lifecycle, many emails, a new look95 /** What every member gets on each repository; owners have Admin. */
96 basePermission?: BasePermission;
Workspaces own repositories97};
98
Invite-only launch: sign in with GitHub, repository access and lifecycle, many emails, a new look99export type Member = {
100 username: string;
101 role: Role;
102 /** Their display name, when they set one. */
103 name?: string | null;
104 /** Their uploaded avatar's hash, served at `/avatars/<avatar>`; null for the generated letter avatar. */
105 avatar?: string | null;
106};
Workspaces own repositories107
Billing on Stripe's pages, month-end charges, warnings; sudo by workspace108/** An owner of a workspace, as staff see them. */
109export type AdminOwner = { username: string; email: string | null };
110
111/** A workspace as staff see it. Mirrors `AdminWorkspace` in `crates/contracts/src/identity.rs`. */
112export type AdminWorkspace = {
113 slug: string;
114 name: string;
115 /** RFC 3339. */
116 createdAt: string;
117 owners: AdminOwner[];
118 memberCount: number;
119};
120
121/** A member of a workspace, as staff see them. */
122export type AdminMember = { username: string; email: string | null; role: Role; /** RFC 3339. */ joined: string };
123
124export type AdminWorkspaceDetail = {
125 slug: string;
126 name: string;
127 description: string | null;
128 /** RFC 3339. */
129 createdAt: string;
130 /** Owners first, then by username. */
131 members: AdminMember[];
Packages, with a container registry on g1t.sh; workspaces deleted whole and kept 30 days; Members for every member132 /** It can never be deleted, by anyone (identity's `PROTECTED_WORKSPACES`). */
133 protected: boolean;
Billing on Stripe's pages, month-end charges, warnings; sudo by workspace134};
135
136/** The most workspaces one `workspaces` call returns. */
137export const ADMIN_WORKSPACES_LIMIT = 500;
138
139/**
Invite-only launch: sign in with GitHub, repository access and lifecycle, many emails, a new look140 * Whether anyone may make an account, or only someone with an invite.
141 * Identity's `REGISTRATION_MODE`; unset means `invite`.
142 */
143export type RegistrationMode = "invite" | "open";
144
145/** How many invites a person may have out at once, unless identity's `INVITES_PER_USER` says otherwise. */
146export const INVITES_PER_USER = 5;
147/** How long an invite works, unless identity's `INVITE_TTL_DAYS` says otherwise. */
148export const INVITE_TTL_DAYS = 30;
149
150/** Only a pending invite can be used or revoked. Revoked and expired ones never used give the invite back. */
151export type InviteStatus = "pending" | "redeemed" | "expired" | "revoked";
152
153/** One invite. Mirrors `Invite` in `crates/contracts/src/identity.rs`. */
154export type Invite = {
155 id: string;
156 /** `g1t-k7m2-…`: returned when it is made, and to its maker while pending. */
157 code: string | null;
158 /** The code's first group, such as `g1t-k7m2`. */
159 hint: string;
160 /** Only this address can use it. */
161 email: string | null;
162 /** `account` makes an account; `workspace` joins an existing one to `workspace`. */
163 kind: "account" | "workspace";
164 /** The workspace using it joins. */
165 workspace: string | null;
166 status: InviteStatus;
167 /** Whose allowance it used. */
168 chargedTo: "user" | "workspace" | "none";
169 /** Its maker's username; null when g1t staff made it. */
170 invitedBy: string | null;
171 /** The account that used it. */
172 redeemedBy: string | null;
173 /** RFC 3339. */
174 createdAt: string;
175 /** RFC 3339. */
176 expiresAt: string;
177 redeemedAt: string | null;
178 revokedAt: string | null;
179 /** The staff member who minted it; only in staff views. */
180 staff?: string | null;
181};
182
183/** How many invites someone may have out. `limit` and `remaining` are null for no limit. */
184export type Allowance = { limit: number | null; used: number; remaining: number | null };
185
186export type InvitesOverview = {
187 mode: RegistrationMode;
188 allowance: Allowance;
189 /** Workspaces the person owns that were granted invites to share. */
190 workspaces: { slug: string; allowance: Allowance }[];
191 invites: Invite[];
192};
193
194/** What a valid code is for, before it is used. */
195export type InvitePreview = {
196 kind: "account" | "workspace";
status.g1t.sh with incident management, invites that land you in the workspace, settings as pages, usage without quotas197 /** Pending, unless `anyStatus` asked about a code that is spent. */
198 status: InviteStatus;
Invite-only launch: sign in with GitHub, repository access and lifecycle, many emails, a new look199 /** Null when g1t staff sent it. */
200 invitedBy: { username: string; name: string | null; avatar: string | null } | null;
201 workspace: ProfileWorkspace | null;
status.g1t.sh with incident management, invites that land you in the workspace, settings as pages, usage without quotas202 /** The repository it accepts an invitation to, such as `{ name: "flagon-io/g1t", role: "write" }`. */
203 repository: { name: string; role: string } | null;
Invite-only launch: sign in with GitHub, repository access and lifecycle, many emails, a new look204 /** Partly hidden, such as `a•••@example.com`. */
205 email: string | null;
status.g1t.sh with incident management, invites that land you in the workspace, settings as pages, usage without quotas206 /** The bound address in full, while the invite is pending: it fills in and locks the sign-up form. */
207 address: string | null;
208 /** Whether the bound address has a g1t account already: sign in to accept. */
209 hasAccount: boolean;
210 /** With a viewer: whether it is theirs (for one of their confirmed addresses, or used by them). */
211 forViewer: boolean | null;
Invite-only launch: sign in with GitHub, repository access and lifecycle, many emails, a new look212 expiresAt: string;
213};
214
215export type WaitlistStatus = "waiting" | "invited" | "dismissed";
216
217export type WaitlistEntry = {
218 id: string;
219 email: string;
220 about: string | null;
221 status: WaitlistStatus;
222 inviteId: string | null;
223 decidedBy: string | null;
224 decidedAt: string | null;
status.g1t.sh with incident management, invites that land you in the workspace, settings as pages, usage without quotas225 /** What staff wrote when approving; it went in the invite email. */
226 note: string | null;
227 /** The account made with the invite, once it was used. */
228 joinedAs: string | null;
Invite-only launch: sign in with GitHub, repository access and lifecycle, many emails, a new look229 /** When they first asked. */
230 createdAt: string;
231 /** When they last asked. */
232 updatedAt: string;
233};
234
235export type InviteGrant = { amount: number; note: string | null; grantedBy: string; createdAt: string };
236export type InviteTreeNode = { username: string; joinedAt: string; invited: InviteTreeNode[] };
237
238/** Where a person came from and whom they brought. For a workspace, `username` is its slug. */
239export type InviteTree = {
240 username: string;
241 /** Who invited them, then who invited that person, and so on. */
242 invitedBy: string[];
243 /** The staff member who minted their invite, when staff did. */
244 staff: string | null;
245 allowance: Allowance;
246 grants: InviteGrant[];
247 invites: Invite[];
248 /** Whom they invited, three levels down. */
249 invited: InviteTreeNode[];
250};
251
252/** The most rows one staff listing of invites or the waitlist returns. */
253export const ADMIN_INVITES_LIMIT = 500;
254
255/**
Billing on Stripe's pages, month-end charges, warnings; sudo by workspace256 * Staff-only identity, for sudo.g1t.sh. It takes no viewer and checks no
257 * membership: only sudo calls it, over its service binding, once Cloudflare
258 * Access and its staff list have let someone in. Never call it on behalf of
259 * a customer.
260 */
261export interface IdentityAdminApi {
262 /** Every workspace, newest first, at most 500; `query` matches slug, name, or an owner's username or email. */
263 workspaces(query?: string): Promise<AdminWorkspace[]>;
264 /** One workspace with all its members, or null. */
265 workspace(slug: string): Promise<AdminWorkspaceDetail | null>;
Invite-only launch: sign in with GitHub, repository access and lifecycle, many emails, a new look266
status.g1t.sh with incident management, invites that land you in the workspace, settings as pages, usage without quotas267 /** The waitlist, newest first; `query` matches the address or what they said. */
Invite-only launch: sign in with GitHub, repository access and lifecycle, many emails, a new look268 waitlist(query?: string | null, status?: WaitlistStatus | null): Promise<WaitlistEntry[]>;
status.g1t.sh with incident management, invites that land you in the workspace, settings as pages, usage without quotas269 /** How many requests are waiting, for the navigation's badge. */
270 waitlistPending(): Promise<number>;
271 /**
272 * Approving mints an invite bound to the address and emails it, with
273 * `note` (up to 500 characters) if given; dismissing only marks it.
274 */
275 decideWaitlist(id: string, approve: boolean, staff: string, note?: string | null): Promise<Result<WaitlistEntry>>;
Invite-only launch: sign in with GitHub, repository access and lifecycle, many emails, a new look276 /** Invites, newest first; `query` is a code's start, or part of an email, inviter or redeemer. */
277 invites(query?: string | null): Promise<Invite[]>;
278 revokeInvite(id: string, staff: string): Promise<Result<Invite>>;
279 /** An invite that uses nobody's allowance, optionally bound to (and emailed to) `email`. */
280 mintInvite(email: string | null, staff: string): Promise<Result<Invite>>;
281 /** More invites (or fewer, with a negative amount) for a person or a workspace. */
282 grantInvites(
283 target: "user" | "workspace",
284 name: string,
285 amount: number,
286 note: string,
287 staff: string,
288 ): Promise<Result<Allowance>>;
289 /** Where a person came from and whom they brought, or null. */
290 inviteTree(username: string): Promise<InviteTree | null>;
291 /** A workspace's granted invites and the invites made for it, or null. */
292 workspaceInvites(slug: string): Promise<InviteTree | null>;
Packages, with a container registry on g1t.sh; workspaces deleted whole and kept 30 days; Members for every member293
294 /** Workspaces owners deleted that are not purged yet, newest first. */
295 deletedWorkspaces(): Promise<DeletedWorkspace[]>;
296 /**
297 * Brings a deleted workspace back, with its members, tokens and what went
298 * with it, while it is still restorable. Publishes `workspace.restored`.
299 */
300 restoreWorkspace(workspaceId: string, staff: string): Promise<Result<boolean>>;
301 /**
302 * Purges a deleted workspace now rather than at `purgeAfter`. `confirm` is
303 * its slug, typed out. Refused for a protected workspace. Publishes
304 * `workspace.deleted`.
305 */
306 purgeWorkspace(workspaceId: string, staff: string, confirm: string): Promise<Result<boolean>>;
Billing on Stripe's pages, month-end charges, warnings; sudo by workspace307}
308
Initial g1t: services, event bus, intents and attempts309/** Who is asking. Every read and write in every service takes one. */
310export type Viewer = User | null;
311
312export type SshKey = {
313 id: string;
314 title: string;
315 fingerprint: string;
RFC 3339 timestamps in identity and repos316 /** RFC 3339. */
317 createdAt: string;
Initial g1t: services, event bus, intents and attempts318};
319
Agents as a team: lifecycle, merge queue, billing and a new shell320export type AccessToken = {
321 id: string;
322 name: string;
323 /** RFC 3339. */
324 createdAt: string;
325 /** RFC 3339, to within a few minutes. Null until it is first used. */
326 lastUsedAt: string | null;
327 /**
328 * For a workspace's token, the username of the member who made it. Null
329 * once that account is gone, and on personal tokens.
330 */
331 createdBy: string | null;
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step332 /** Its scopes, as `resource:level`. Null: full access. */
333 scopes: string[] | null;
334 /** Made before tokens had scopes: full access until someone narrows it. */
335 legacy: boolean;
336 /** RFC 3339. Null: it does not expire. */
337 expiresAt: string | null;
338};
339
340/** What a new or changed token may do. */
341export type TokenGrant = {
342 /** Null: full access. */
343 scopes: string[] | null;
Agents as a team: lifecycle, merge queue, billing and a new shell344};
Initial g1t: services, event bus, intents and attempts345
Device sign-in replaces registering and minting tokens over the API346export type DeviceStart = {
347 /** Secret held by the tool and exchanged for a token once approved. */
348 deviceCode: string;
349 /** Short code shown to the person, e.g. `WDJB-MJHT`. */
350 userCode: string;
351 /** Seconds until both codes stop working. */
352 expiresIn: number;
353 /** Seconds the tool should wait between polls. */
354 interval: number;
355};
356
357export type DeviceRequest = { userCode: string; clientName: string };
358
359export type DeviceClaim =
360 | { status: "pending" | "denied" | "expired" }
361 | { status: "approved"; token: string; user: User };
362
OAuth 2.1 sign-in for MCP clients and other applications363/** What the site passes on once a person has approved an application. */
364export type OAuthApproval = {
365 clientId: string;
366 /** Shown wherever the application's access is listed. */
367 clientName: string;
368 redirectUri: string;
369 /** PKCE challenge, method S256. */
370 codeChallenge: string;
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step371 /** What the person granted. Null: full access. */
372 scopes: string[] | null;
OAuth 2.1 sign-in for MCP clients and other applications373};
374
375export type OAuthTokens = {
376 accessToken: string;
377 /** Works once; using it returns the next one. */
378 refreshToken: string;
379 /** Seconds until the access token stops working. */
380 expiresIn: number;
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step381 /** The scopes granted, space-separated, or `*` for full access. */
382 scope?: string | null;
OAuth 2.1 sign-in for MCP clients and other applications383};
384
385/** An application a person has signed in to. */
386export type OAuthGrant = {
387 id: string;
388 clientName: string;
389 /** RFC 3339. */
390 createdAt: string;
391 /** RFC 3339. */
392 lastUsedAt: string;
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step393 /** What the person granted. Null: full access. */
394 scopes: string[] | null;
395 /** Signed in before applications had scopes: full access until narrowed. */
396 legacy: boolean;
OAuth 2.1 sign-in for MCP clients and other applications397};
398
Initial g1t: services, event bus, intents and attempts399/** Accounts, credentials and sessions. */
Packages, with a container registry on g1t.sh; workspaces deleted whole and kept 30 days; Members for every member400/**
401 * What deleting a workspace takes with it, and what stands in the way:
402 * nothing does while `billing` is null and it is not `protected`.
403 */
Invite-only launch: sign in with GitHub, repository access and lifecycle, many emails, a new look404export type WorkspaceDeletion = {
Packages, with a container registry on g1t.sh; workspaces deleted whole and kept 30 days; Members for every member405 /** Its live repositories, deleted with it. */
Invite-only launch: sign in with GitHub, repository access and lifecycle, many emails, a new look406 repositories: number;
Packages, with a container registry on g1t.sh; workspaces deleted whole and kept 30 days; Members for every member407 /** Its projects, hidden with it. */
Invite-only launch: sign in with GitHub, repository access and lifecycle, many emails, a new look408 projects: number;
Packages, with a container registry on g1t.sh; workspaces deleted whole and kept 30 days; Members for every member409 members: number;
Invite-only launch: sign in with GitHub, repository access and lifecycle, many emails, a new look410 /** Why billing cannot close it yet, in words for its owner. */
411 billing: string | null;
Packages, with a container registry on g1t.sh; workspaces deleted whole and kept 30 days; Members for every member412 /** It can never be deleted, by anyone. */
413 protected: boolean;
414};
415
416/** How long a deleted workspace is kept, for g1t's staff to restore, before it is purged. */
417export const WORKSPACE_RESTORE_DAYS = 30;
418
419/**
420 * Workspaces nobody can delete, whatever identity's `PROTECTED_WORKSPACES`
421 * says: Flagon's, which runs g1t. Services that act on `workspace.deleting`
422 * check it too, so one published for it by mistake changes nothing.
423 */
424export const ALWAYS_PROTECTED_WORKSPACES: readonly string[] = ["flagon-io"];
425
426/** Whether `slug` is one of `ALWAYS_PROTECTED_WORKSPACES`, in any case. */
427export function isProtectedWorkspace(slug: string): boolean {
428 return ALWAYS_PROTECTED_WORKSPACES.includes(slug.trim().toLowerCase());
429}
430
431/** A workspace an owner deleted, kept until `purgeAfter` for staff to restore. */
432export type DeletedWorkspace = {
433 workspaceId: string;
434 slug: string;
435 name: string;
436 /** RFC 3339. */
437 deletedAt: string;
438 /** The username of the owner who deleted it. */
439 deletedBy: string;
440 /** RFC 3339: when it is purged unless restored first. */
441 purgeAfter: string;
442 /** What went with it, counted when it was deleted. */
443 went: WorkspaceDeletion;
444 /** Whether staff can still restore it. */
445 restorable: boolean;
Invite-only launch: sign in with GitHub, repository access and lifecycle, many emails, a new look446};
447
448export interface IdentityApi extends AccessClient {
449 /**
450 * Creates an account and signs it in. While registration is invite-only,
451 * `inviteCode` must be an unused, unexpired invite (and, when it names an
452 * email, that address); it is ignored while registration is open.
453 */
454 register(
455 username: string,
456 email: string,
457 password: string,
458 inviteCode?: string | null,
459 /** Who is asking, such as the visitor's IP address, for rate limits. */
460 client?: string | null,
461 ): Promise<Result<{ user: User; sessionToken: string }>>;
Initial g1t: services, event bus, intents and attempts462 /** Verifies a username and password for website sign-in. */
Invite-only launch: sign in with GitHub, repository access and lifecycle, many emails, a new look463 /**
464 * Verifies a username, or any confirmed address of the account, and its
465 * password. Wrong passwords are counted against the account and `client`
466 * (the visitor's IP address); past a limit nothing is checked for a while.
467 */
468 signIn(username: string, password: string, client?: string | null): Promise<Result<{ user: User; sessionToken: string }>>;
Initial g1t: services, event bus, intents and attempts469 signOut(sessionToken: string): Promise<void>;
Email verification, password reset, and Git for AI scale positioning470
471 /** Sends the confirmation email again. */
472 resendVerification(user: User): Promise<Result<boolean>>;
473 /** Confirms the address the emailed token was sent to. */
474 verifyEmail(token: string): Promise<Result<User>>;
475 /** Emails a reset link if the address has an account. Always resolves. */
Invite-only launch: sign in with GitHub, repository access and lifecycle, many emails, a new look476 /**
477 * Any confirmed address of an account works; the link goes to it, and the
478 * primary and backup are told. A few an hour per address and per `client`.
479 */
480 requestPasswordReset(email: string, client?: string | null): Promise<boolean>;
Email verification, password reset, and Git for AI scale positioning481 /** Sets a new password from an emailed token and ends every session. */
482 resetPassword(token: string, password: string): Promise<Result<User>>;
483
Device sign-in replaces registering and minting tokens over the API484 /**
485 * Device sign-in (RFC 8628). A tool starts a request, a person approves
486 * its short code in a browser, and the tool claims an access token.
487 */
488 deviceStart(clientName: string): Promise<DeviceStart>;
489 /** What a user code is asking for, or null if it is not valid. */
490 deviceLookup(userCode: string): Promise<DeviceRequest | null>;
491 deviceResolve(userCode: string, user: User, approve: boolean): Promise<Result<boolean>>;
492 deviceClaim(deviceCode: string): Promise<DeviceClaim>;
493
OAuth 2.1 sign-in for MCP clients and other applications494 /**
495 * OAuth 2.1 for applications that sign a person in through the browser.
496 * The caller has checked the client and its redirect address; this
497 * returns the one-time code the application exchanges for tokens.
498 */
499 oauthAuthorize(user: User, approval: OAuthApproval): Promise<{ code: string }>;
500 /** Redeems a code. It works once, for that client, with the PKCE verifier. */
501 oauthExchange(code: string, codeVerifier: string, clientId: string, redirectUri: string): Promise<Result<OAuthTokens>>;
502 /** Trades a refresh token for new tokens; the old ones stop working. */
503 oauthRefresh(refreshToken: string, clientId: string): Promise<Result<OAuthTokens>>;
504 /** Applications the user has signed in to, most recently used first. */
505 listOAuthGrants(user: User): Promise<OAuthGrant[]>;
506 /** Signs an application out. */
507 revokeOAuthGrant(user: User, id: string): Promise<void>;
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step508 /** Changes what an application may do, at once and when it refreshes. */
509 updateOAuthGrant(user: User, id: string, grant: TokenGrant): Promise<Result<OAuthGrant>>;
OAuth 2.1 sign-in for MCP clients and other applications510
Workspaces own repositories511 createWorkspace(user: User, slug: string, name: string): Promise<Result<Workspace>>;
512 /** Public details of a workspace, or null. */
513 getWorkspace(slug: string): Promise<Workspace | null>;
514 /** Members only. */
515 listMembers(slug: string, viewer: Viewer): Promise<Result<Member[]>>;
516 /** Owners only. */
517 addMember(actor: User, slug: string, username: string): Promise<Result<boolean>>;
518 /** Owners only. */
519 removeMember(actor: User, slug: string, username: string): Promise<Result<boolean>>;
Agents as a team: lifecycle, merge queue, billing and a new shell520 /** Owners only. An empty name falls back to the slug. */
521 updateWorkspace(actor: User, slug: string, details: { name: string; description: string }): Promise<Result<Workspace>>;
Workspace names and icons, and a component kit for every control522 /**
Agents and memory, checks and conflicts, profiles, slug renames, custom domains523 * Owners only. Changes the slug, the first segment of the workspace's
524 * URLs; the display name is untouched. The old slug redirects to the new
525 * one, and stays reserved for this workspace, for `SLUG_HOLD_DAYS`.
526 * Publishes `workspace.renamed`.
527 */
528 renameWorkspace(actor: User, slug: string, newSlug: string): Promise<Result<Workspace>>;
529 /** Whether `renameWorkspace` would be allowed, changing nothing. */
530 checkWorkspaceRename(actor: User, slug: string, newSlug: string): Promise<Result<boolean>>;
531 /**
532 * The workspace's current slug when `slug` is one it was renamed from
533 * within `SLUG_HOLD_DAYS`; null otherwise, including for a slug in use.
534 */
535 resolveSlug(slug: string): Promise<string | null>;
536 /**
Invite-only launch: sign in with GitHub, repository access and lifecycle, many emails, a new look537 * Owners only, a person only. `confirm` is the slug, typed out. Refused
Packages, with a container registry on g1t.sh; workspaces deleted whole and kept 30 days; Members for every member538 * for a protected workspace, and while billing cannot settle it. Its
539 * repositories, projects and apps go with it; it is kept for
540 * `WORKSPACE_RESTORE_DAYS`, when g1t's staff can restore it, then purged.
541 * Its slug is never given to anyone else; the person whose username it is
542 * may make it again once it is purged. Publishes `workspace.deleting`.
Invite-only launch: sign in with GitHub, repository access and lifecycle, many emails, a new look543 */
544 deleteWorkspace(actor: User, slug: string, confirm: string): Promise<Result<boolean>>;
Packages, with a container registry on g1t.sh; workspaces deleted whole and kept 30 days; Members for every member545 /** What `deleteWorkspace` would take with it, and what stands in its way, changing nothing. */
Invite-only launch: sign in with GitHub, repository access and lifecycle, many emails, a new look546 checkWorkspaceDeletion(actor: User, slug: string): Promise<Result<WorkspaceDeletion>>;
547 /**
Workspace names and icons, and a component kit for every control548 * Owners only. `image` is the file in base64: PNG, JPEG, WebP or GIF, at
549 * most `MAX_AVATAR_BYTES`, checked by its bytes. Null removes the icon.
550 */
551 setWorkspaceAvatar(actor: User, slug: string, image: string | null): Promise<Result<Workspace>>;
552 /** A person's own avatar, as `setWorkspaceAvatar`: the new one, or null. */
553 setUserAvatar(user: User, image: string | null): Promise<Result<string | null>>;
Workspaces own repositories554
Agents as a team: lifecycle, merge queue, billing and a new shell555 /**
556 * A workspace's own access tokens. They belong to the workspace, act as
557 * it, and keep working when the member who made one leaves. Members only.
558 */
559 listWorkspaceTokens(slug: string, viewer: Viewer): Promise<Result<AccessToken[]>>;
560 /** Owners only. The plaintext token is returned once and never stored. */
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step561 createWorkspaceToken(
562 actor: User,
563 slug: string,
564 name: string,
565 grant?: TokenGrant & { ttlSeconds?: number },
566 ): Promise<Result<{ token: string; info: AccessToken }>>;
Agents as a team: lifecycle, merge queue, billing and a new shell567 /** Owners only. */
568 removeWorkspaceToken(actor: User, slug: string, id: string): Promise<Result<boolean>>;
569
Initial g1t: services, event bus, intents and attempts570 userForSession(sessionToken: string): Promise<Viewer>;
571
Invite-only launch: sign in with GitHub, repository access and lifecycle, many emails, a new look572 /** Whether registration is invite-only. */
573 registration(): Promise<RegistrationMode>;
574 /** A person's invites and what they have left. */
575 listInvites(user: User): Promise<InvitesOverview>;
576 /**
577 * A person makes an invite, optionally for one address (emailed to it),
578 * using one of theirs or, with `workspace`, one the workspace was granted.
579 * People only: never an agent or a workspace's token.
580 */
581 createInvite(user: User, options?: { email?: string | null; workspace?: string | null }): Promise<Result<Invite>>;
582 /** Its maker, or an owner of its workspace, revokes a pending invite; the invite comes back. */
583 revokeInvite(user: User, id: string): Promise<Result<Invite>>;
status.g1t.sh with incident management, invites that land you in the workspace, settings as pages, usage without quotas584 /**
585 * What a code is for. Unknown, used, revoked and expired codes all get the
586 * same answer, unless `anyStatus`: then a real code that is spent is
587 * described, with its `status`. `viewer` sets `forViewer`.
588 */
589 checkInvite(
590 code: string,
591 client?: string | null,
592 options?: { viewer?: User | null; anyStatus?: boolean },
593 ): Promise<Result<InvitePreview>>;
594 /**
595 * A signed-in person uses a workspace invite sent to their address, or one
596 * sent with a repository invitation; returns the workspace's slug, or
597 * `workspace/repo`.
598 */
Invite-only launch: sign in with GitHub, repository access and lifecycle, many emails, a new look599 acceptInvite(user: User, code: string): Promise<Result<string>>;
600 /** Owners only. Invites an address into a workspace, always with an invite bound to it. */
601 inviteMember(actor: User, slug: string, email: string): Promise<Result<Invite>>;
602 /** Owners only: the workspace's invites, newest first. */
603 workspaceInvites(slug: string, viewer: Viewer): Promise<Result<Invite[]>>;
604 /** Owners only. */
605 revokeWorkspaceInvite(actor: User, slug: string, id: string): Promise<Result<Invite>>;
606 /** Someone without an invite asks for one. Always the same answer for a valid address. */
607 requestAccess(email: string, about: string, client?: string | null): Promise<Result<boolean>>;
608
Initial g1t: services, event bus, intents and attempts609 /** Verifies git credentials: the account password or an access token. */
610 userForGitCredentials(username: string, secret: string): Promise<Viewer>;
API and MCP server, Rust identity service, registration, site redesign611 /** Resolves a `g1t_…` access token, as sent to the API and MCP server. */
612 userForAccessToken(token: string): Promise<Viewer>;
Initial g1t: services, event bus, intents and attempts613 userForSshKey(fingerprint: string): Promise<Viewer>;
614 userByUsername(username: string): Promise<Viewer>;
What happened across an outcome, as a feed beside its graph615 /** The names behind account and workspace ids; unknown ids are left out. */
616 usernames(ids: string[]): Promise<Record<string, string>>;
Initial g1t: services, event bus, intents and attempts617
Agents and memory, checks and conflicts, profiles, slug renames, custom domains618 /** A person's public profile, or null if there is no such account. Never an email address. */
619 profile(username: string): Promise<Profile | null>;
620 /** A person changes their own profile. Every field is replaced; an empty one is cleared. */
621 updateProfile(actor: User, fields: ProfileFields): Promise<Result<Profile>>;
622 /**
623 * The workspaces a profile shows `viewer`: those the viewer belongs to
624 * as well, and those of `publicIn` (where the person made a public
625 * project) that the person really belongs to. Nothing else.
626 */
627 profileWorkspaces(username: string, viewer: Viewer, publicIn: string[]): Promise<ProfileWorkspace[]>;
628
Initial g1t: services, event bus, intents and attempts629 listSshKeys(user: User): Promise<SshKey[]>;
630 /** Takes one line in OpenSSH public key format. */
631 addSshKey(user: User, title: string, publicKey: string): Promise<Result<SshKey>>;
632 removeSshKey(user: User, id: string): Promise<void>;
633
634 listAccessTokens(user: User): Promise<AccessToken[]>;
Account dropdown, llms.txt onboarding, hosted agent runner (not yet deployed)635 /**
Agents as a team: lifecycle, merge queue, billing and a new shell636 * The plaintext token is returned once and never stored. With
637 * `ttlSeconds` the token expires and is left out of token lists; that
638 * form is used for hosted agents. A token made for a workspace acting
639 * through a token of its own belongs to that workspace too.
Account dropdown, llms.txt onboarding, hosted agent runner (not yet deployed)640 */
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step641 createAccessToken(
642 user: User,
643 name: string,
644 ttlSeconds?: number,
645 grant?: TokenGrant & { listed?: boolean },
646 ): Promise<{ token: string; info: AccessToken }>;
647 /** Changes what one of a person's tokens may do; the token is unchanged. */
648 updateAccessToken(user: User, id: string, grant: TokenGrant): Promise<Result<AccessToken>>;
Agents as a team: lifecycle, merge queue, billing and a new shell649 /**
650 * A token for a g1t agent working for `onBehalfOf`: it acts as
g1t is one name: its agent's work, commits and comments show as @g1t, and nobody can claim g1t or g1t-agent651 * `g1t`, in `scope.repo` only, and only for `scope.operations`.
Agents as a team: lifecycle, merge queue, billing and a new shell652 */
653 createAgentToken(
654 onBehalfOf: User,
655 scope: AgentScope,
656 ttlSeconds: number,
657 ): Promise<{ token: string; info: AccessToken }>;
Initial g1t: services, event bus, intents and attempts658 removeAccessToken(user: User, id: string): Promise<void>;
Agents get guardrails, run credentials, an audit log, a context hub, repository instructions and mentions; security upkeep; snake_case API659 /**
660 * A token for one sandbox run: it acts as the agent on behalf of
661 * `onBehalfOf`, can do only what the run's kind needs in `repo`, and
662 * expires after `ttlSeconds`. See `audit.ts`.
663 */
664 createRunCredential(input: CreateRunCredentialInput): Promise<{ token: string; info: AccessToken }>;
665 /** Ties tokens, by the SHA-256 of their text in hex, to the agent run their sandbox recorded. */
666 bindRunCredentials(tokenHashes: string[], runId: string): Promise<boolean>;
667 /** Ends a sandbox's run credentials, by hash or by run. Never touches another token. */
668 revokeRunCredentials(target: { tokenHashes?: string[]; runId?: string | null }): Promise<boolean>;
Initial g1t: services, event bus, intents and attempts669}
Agents as a team: lifecycle, merge queue, billing and a new shell670
671
672/** What an agent's token may do: these operations, in this repository. */
Agents get guardrails, run credentials, an audit log, a context hub, repository instructions and mentions; security upkeep; snake_case API673export type AgentScope = { repo: RepoPath; operations: string[]; run?: RunBinding };
Agents and memory, checks and conflicts, profiles, slug renames, custom domains674
675/** The most characters each profile field takes. Mirrors `crates/contracts/src/identity.rs`. */
676export const PROFILE_LIMITS = { name: 80, bio: 160, location: 80, website: 200, pronouns: 40 } as const;
677
678/** What anyone may see about a person, at `g1t.sh/u/<username>`. */
679export type Profile = {
680 username: string;
681 /** The name they go by, if they gave one. */
682 name: string | null;
683 bio: string | null;
684 location: string | null;
685 /** Always an `https://` address. */
686 website: string | null;
687 pronouns: string | null;
688 /** The uploaded avatar's hash, served at `/avatars/<avatar>`. */
689 avatar: string | null;
690 /** When the account was made. RFC 3339. */
691 createdAt: string;
692};
693
694/** What a person may change on their profile. Empty clears a field. */
695export type ProfileFields = {
696 name: string;
697 bio: string;
698 location: string;
699 /** `https://…`; a bare `example.com` is taken as `https://example.com`. */
700 website: string;
701 pronouns: string;
702};
703
704/** A workspace on a person's profile. */
705export type ProfileWorkspace = { slug: string; name: string; avatar: string | null };