Sign in

flagon-io/g1t

public

g1t/packages/contracts/src/identity.ts

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