Skip to content
Sign in

flagon-io/g1t

public
0
646 linesCodeBlameRaw
1//! Access tokens: the `g1t_…` secrets used by git, the API and the MCP
2//! server.
3//!
4//! There is one implementation and two kinds of owner. A personal token
5//! acts as the person who made it. A workspace's token belongs to the
6//! workspace and acts as it, so automation needs no account of its own and
7//! keeps working when the member who set it up leaves.
8
9use g1t_contracts::identity::*;
10use g1t_contracts::scopes::{FULL_ACCESS, JobToken, Scope, TokenAccess, parse_scopes, scopes_text};
11use g1t_contracts::time::{SQL_NOW, rfc3339};
12use g1t_contracts::tokens::TokenKind;
13use g1t_contracts::{FailureCode, Membership, Outcome, PrincipalKind, Role, User, Viewer, new_id};
14use g1t_kit::now_ms;
15use serde::Deserialize;
16use worker::Result;
17use worker::wasm_bindgen::JsValue;
18
19use crate::{Identity, crypto};
20
21pub const TOKEN_PREFIX: &str = "g1t_";
22/// How stale a token's last-used time may get before it is written again.
23const LAST_USED_RESOLUTION_MS: u64 = 5 * 60 * 1000;
24const MAX_TOKENS_PER_WORKSPACE: usize = 50;
25const WORKSPACE_ID_PREFIX: &str = "wsp_";
26
27pub(crate) const TOKEN_COLUMNS: &str = "access_tokens.id, access_tokens.name, access_tokens.created_at,
28 access_tokens.last_used_at, users.username AS created_by, access_tokens.scopes,
29 access_tokens.expires_at, access_tokens.kind, access_tokens.description, access_tokens.admin,
30 access_tokens.workspace_id, access_tokens.repository_selection, access_tokens.permissions,
31 access_tokens.status, access_tokens.review_reason,
32 (SELECT slug FROM workspaces WHERE workspaces.id = access_tokens.owner_workspace_id) AS owner_workspace";
33
34/// Who a new token belongs to.
35pub(crate) enum Owner<'a> {
36 User(&'a str),
37 Workspace {
38 id: &'a str,
39 created_by: Option<&'a str>,
40 },
41}
42
43#[derive(Deserialize)]
44pub(crate) struct TokenRow {
45 id: String,
46 name: String,
47 created_at: String,
48 last_used_at: Option<String>,
49 created_by: Option<String>,
50 scopes: Option<String>,
51 expires_at: Option<String>,
52 /// What a fine-grained token, and a workspace's, add (migration 0034;
53 /// see token_reach.rs).
54 #[serde(flatten)]
55 pub(crate) more: crate::token_reach::TokenRowMore,
56}
57
58/// What a token or grant may do, as it is to be stored. A token reaches
59/// whatever its owner can; only its scopes narrow that.
60///
61/// The `resources` columns (migration 0022) held a limit to some
62/// workspaces or repositories. That limit was retired (migration 0023);
63/// the columns stay, since D1 cannot drop them in place, and nothing
64/// reads or writes them.
65#[derive(Clone, Debug, Default)]
66pub(crate) struct Grant {
67 /// Null: full access.
68 pub scopes: Option<Vec<Scope>>,
69}
70
71impl Grant {
72 /// From what a caller asked for: unknown scopes are left out.
73 pub(crate) fn asked(scopes: &Option<Vec<String>>) -> Self {
74 Grant {
75 scopes: scopes.as_ref().map(|scopes| parse_scopes(&scopes.join(" "))),
76 }
77 }
78
79 /// The `scopes` column: `*` for full access.
80 pub(crate) fn scopes_column(&self) -> String {
81 match &self.scopes {
82 None => FULL_ACCESS.to_owned(),
83 Some(scopes) => scopes_text(scopes),
84 }
85 }
86}
87
88/// A `scopes` column read back: the scopes (null for full access), and
89/// whether it is a legacy row, made before scopes.
90pub(crate) fn stored_scopes(column: Option<&str>) -> (Option<Vec<String>>, bool) {
91 match column {
92 None => (None, true),
93 Some(FULL_ACCESS) => (None, false),
94 Some(text) => (
95 Some(parse_scopes(text).iter().map(|scope| scope.as_str().to_owned()).collect()),
96 false,
97 ),
98 }
99}
100
101/// The owner of a token being used.
102#[derive(Deserialize)]
103struct Presented {
104 id: String,
105 user_id: Option<String>,
106 workspace_id: Option<String>,
107 last_used_at: Option<String>,
108 /// Set on an agent's token: what it may do, as JSON `AgentScope`.
109 agent_scope: Option<String>,
110 scopes: Option<String>,
111 #[serde(default)]
112 name: Option<String>,
113 /// Set on a workflow job's token (job_tokens.rs): its repository, job
114 /// and run.
115 #[serde(default)]
116 repo: Option<String>,
117 #[serde(default)]
118 job_id: Option<String>,
119 #[serde(default)]
120 job_run_id: Option<String>,
121 #[serde(default)]
122 job_pulls: Option<u32>,
123 /// A fine-grained token's resource owner and status, a workspace
124 /// token's Admin, and when it was made and expires, for the rules of
125 /// the workspaces it reaches (token_reach.rs).
126 #[serde(flatten)]
127 facts: crate::token_reach::Facts,
128}
129
130#[derive(Deserialize)]
131struct WorkspaceRef {
132 id: String,
133 slug: String,
134}
135
136fn text(value: Option<&str>) -> JsValue {
137 value.map_or(JsValue::NULL, JsValue::from)
138}
139
140impl Identity {
141 pub async fn user_for_access_token(&self, token: &str) -> Result<Viewer> {
142 if !token.starts_with(TOKEN_PREFIX) {
143 return Ok(None);
144 }
145 let Some(presented) = self
146 .db
147 .prepare(format!(
148 "SELECT id, user_id, workspace_id, last_used_at, agent_scope, scopes, name,
149 repo, job_id, job_run_id, job_pulls, created_at, expires_at, kind,
150 owner_workspace_id, repository_selection, status, admin
151 FROM access_tokens
152 WHERE token_hash = ? AND (expires_at IS NULL OR expires_at > {SQL_NOW})"
153 ))
154 .bind(&[crypto::sha256_hex(token).into()])?
155 .first::<Presented>(None)
156 .await?
157 else {
158 return Ok(None);
159 };
160 // An agent's token: g1t on behalf of the person it was made
161 // for, in its repository's workspace while they belong to it, and
162 // only for what its scope lists. See run_credentials.rs.
163 if let Some(scope) = presented
164 .agent_scope
165 .as_deref()
166 .and_then(|scope| serde_json::from_str::<AgentScope>(scope).ok())
167 {
168 return self
169 .agent_principal(
170 &presented.id,
171 presented.user_id.as_deref(),
172 presented.workspace_id.as_deref(),
173 scope,
174 )
175 .await;
176 }
177 let mut viewer = match (&presented.user_id, &presented.workspace_id) {
178 (Some(user_id), _) => {
179 self.find_user(
180 "SELECT id, username, email_verified_at IS NOT NULL AS verified
181 FROM users WHERE id = ?",
182 user_id,
183 )
184 .await?
185 }
186 (None, Some(workspace_id)) => self.workspace_principal(workspace_id).await?,
187 (None, None) => None,
188 };
189 if let Some(user) = viewer.as_mut() {
190 self.note_use(&presented).await?;
191 let (scopes, legacy) = stored_scopes(presented.scopes.as_deref());
192 user.token = Some(Box::new(TokenAccess {
193 token_id: presented.id.clone(),
194 scopes,
195 legacy,
196 name: presented.name.clone(),
197 repo: presented.repo.clone(),
198 job: match (&presented.job_id, &presented.job_run_id) {
199 (Some(job_id), Some(run_id)) => Some(JobToken {
200 run_id: run_id.clone(),
201 job_id: job_id.clone(),
202 pull_requests: presented.job_pulls == Some(1),
203 }),
204 _ => None,
205 },
206 ..TokenAccess::default()
207 }));
208 // What it reaches: a fine-grained token's resource owner and
209 // repositories, the workspaces whose rules let it in, a
210 // workspace token's role.
211 self.apply_reach(user, &presented.id, presented.user_id.is_some(), &presented.facts).await?;
212 }
213 Ok(viewer)
214 }
215
216 pub(crate) fn info(row: TokenRow) -> AccessToken {
217 let (scopes, legacy) = stored_scopes(row.scopes.as_deref());
218 let mut info = AccessToken {
219 id: row.id,
220 name: row.name,
221 created_at: row.created_at,
222 last_used_at: row.last_used_at,
223 created_by: row.created_by,
224 scopes,
225 legacy,
226 expires_at: row.expires_at,
227 ..AccessToken::default()
228 };
229 row.more.describe(&mut info);
230 info
231 }
232
233 /// A workspace as the actor behind one of its own tokens. It can do
234 /// what a member can, in that workspace only.
235 pub(crate) async fn workspace_principal(&self, workspace_id: &str) -> Result<Viewer> {
236 let workspace = self
237 .db
238 // A deleted workspace's tokens are refused until it is restored.
239 .prepare("SELECT id, slug FROM workspaces WHERE id = ? AND deleted_at IS NULL")
240 .bind(&[workspace_id.into()])?
241 .first::<WorkspaceRef>(None)
242 .await?;
243 Ok(workspace.map(|workspace| User {
244 id: workspace.id,
245 username: workspace.slug.clone(),
246 kind: PrincipalKind::Workspace,
247 verified: true,
248 workspaces: vec![Membership::member(workspace.slug)],
249 ..User::default()
250 }))
251 }
252
253 async fn note_use(&self, presented: &Presented) -> Result<()> {
254 let now = now_ms();
255 let stale = rfc3339(now.saturating_sub(LAST_USED_RESOLUTION_MS));
256 if presented
257 .last_used_at
258 .as_deref()
259 .is_some_and(|at| at >= stale.as_str())
260 {
261 return Ok(());
262 }
263 self.db
264 .prepare("UPDATE access_tokens SET last_used_at = ? WHERE id = ?")
265 .bind(&[rfc3339(now).into(), presented.id.as_str().into()])?
266 .run()
267 .await?;
268 Ok(())
269 }
270
271 pub(crate) async fn mint(
272 &self,
273 owner: Owner<'_>,
274 name: &str,
275 ttl_seconds: Option<u64>,
276 grant: &Grant,
277 listed: bool,
278 ) -> Result<CreatedAccessToken> {
279 let token = format!("{TOKEN_PREFIX}{}", crypto::random_hex(20));
280 let now = now_ms();
281 let name: String = match name.trim() {
282 "" => "Access token".to_owned(),
283 name => name.chars().take(100).collect(),
284 };
285 let (user_id, workspace_id, created_by) = match owner {
286 Owner::User(id) => (Some(id), None, Some(id)),
287 Owner::Workspace { id, created_by } => (None, Some(id), created_by),
288 };
289 let expires_at = ttl_seconds.map(|ttl| rfc3339(now + ttl * 1000));
290 let info = AccessToken {
291 id: new_id("tok", now),
292 name,
293 created_at: rfc3339(now),
294 last_used_at: None,
295 created_by: None,
296 scopes: grant
297 .scopes
298 .as_ref()
299 .map(|scopes| scopes.iter().map(|scope| scope.as_str().to_owned()).collect()),
300 legacy: false,
301 expires_at: expires_at.clone(),
302 kind: if workspace_id.is_some() { TokenKind::Workspace } else { TokenKind::Classic },
303 ..AccessToken::default()
304 };
305 self.db
306 .prepare(
307 "INSERT INTO access_tokens
308 (id, user_id, workspace_id, created_by, name, token_hash, created_at, expires_at,
309 scopes, listed)
310 VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
311 )
312 .bind(&[
313 info.id.as_str().into(),
314 text(user_id),
315 text(workspace_id),
316 text(created_by),
317 info.name.as_str().into(),
318 crypto::sha256_hex(&token).into(),
319 info.created_at.as_str().into(),
320 text(expires_at.as_deref()),
321 grant.scopes_column().into(),
322 JsValue::from(u8::from(listed)),
323 ])?
324 .run()
325 .await?;
326 Ok(CreatedAccessToken { token, info })
327 }
328
329 /// A workspace's own token that expires and is never listed: what a
330 /// workflow job's token is minted as (job_tokens.rs).
331 pub(crate) async fn mint_for_workspace(
332 &self,
333 workspace_id: &str,
334 name: &str,
335 ttl_seconds: u64,
336 grant: &Grant,
337 ) -> Result<CreatedAccessToken> {
338 self.mint(
339 Owner::Workspace {
340 id: workspace_id,
341 created_by: None,
342 },
343 name,
344 Some(ttl_seconds),
345 grant,
346 false,
347 )
348 .await
349 }
350
351 pub async fn create_access_token(
352 &self,
353 a: CreateAccessTokenArgs,
354 ) -> Result<CreatedAccessToken> {
355 // Told apart by the id, which says what it names, since callers pass
356 // on actors that other services stored as an id and a name.
357 let owner = if a.user.id.starts_with(WORKSPACE_ID_PREFIX) {
358 Owner::Workspace {
359 id: &a.user.id,
360 created_by: None,
361 }
362 } else {
363 Owner::User(&a.user.id)
364 };
365 let created = self.mint(owner, &a.name, a.ttl_seconds, &Grant::asked(&a.scopes), a.listed).await?;
366 // A person's lasting token: in their security log and their
367 // workspaces' audit logs. Short-lived ones (agents' runs, OAuth
368 // access tokens) are recorded where they are made.
369 if a.ttl_seconds.is_none() && !a.user.id.starts_with(WORKSPACE_ID_PREFIX) && !a.user.username.is_empty() {
370 self.log_security(&a.user.id, "token_created", Some(&created.info.name), None).await;
371 self.audit_account(&a.user, "token.created", &format!("Created access token {}", created.info.name)).await;
372 }
373 Ok(created)
374 }
375
376 /// `remove_access_token`: deletes one of a person's own tokens.
377 pub async fn remove_access_token(&self, a: RemoveArgs) -> Result<()> {
378 let name: Option<String> = self
379 .db
380 .prepare("DELETE FROM access_tokens WHERE id = ? AND user_id = ? RETURNING name")
381 .bind(&[a.id.as_str().into(), a.user.id.as_str().into()])?
382 .first(Some("name"))
383 .await?;
384 if let Some(name) = name {
385 self.log_security(&a.user.id, "token_deleted", Some(&name), None).await;
386 self.audit_account(&a.user, "token.deleted", &format!("Deleted access token {name}")).await;
387 }
388 Ok(())
389 }
390
391 /// Changes what one of a person's own tokens may do.
392 pub async fn update_access_token(&self, a: UpdateAccessTokenArgs) -> Result<Outcome<AccessToken>> {
393 let grant = Grant::asked(&a.scopes);
394 let found: Option<String> = self
395 .db
396 .prepare(
397 "UPDATE access_tokens SET scopes = ?
398 WHERE id = ? AND user_id = ? AND agent_scope IS NULL AND kind IS NULL
399 RETURNING id",
400 )
401 .bind(&[
402 grant.scopes_column().into(),
403 a.id.as_str().into(),
404 a.user.id.as_str().into(),
405 ])?
406 .first(Some("id"))
407 .await?;
408 if found.is_none() {
409 return Ok(Outcome::fail(FailureCode::NotFound, "No such token."));
410 }
411 let row = self
412 .db
413 .prepare(format!(
414 "SELECT {TOKEN_COLUMNS} FROM access_tokens
415 LEFT JOIN users ON users.id = access_tokens.created_by
416 WHERE access_tokens.id = ?"
417 ))
418 .bind(&[a.id.into()])?
419 .first::<TokenRow>(None)
420 .await?;
421 match row {
422 Some(row) => {
423 let info = Self::info(row);
424 self.log_security(&a.user.id, "token_rescoped", Some(&info.name), None).await;
425 self.audit_account(&a.user, "token.rescoped", &format!("Changed the scopes of access token {}", info.name)).await;
426 Ok(Outcome::Ok(info))
427 }
428 None => Ok(Outcome::fail(FailureCode::NotFound, "No such token.")),
429 }
430 }
431
432 /// A token for a g1t agent working for `on_behalf_of`, which can do
433 /// only what `scope` lists. It is recorded as theirs, so it is listed and
434 /// can be deleted with their other tokens.
435 pub async fn create_agent_token(&self, a: CreateAgentTokenArgs) -> Result<CreatedAccessToken> {
436 let created = self
437 .mint(
438 Owner::User(&a.on_behalf_of.id),
439 &format!("g1t agent in {}/{}", a.scope.repo.namespace, a.scope.repo.name),
440 Some(a.ttl_seconds),
441 &Grant::default(),
442 false,
443 )
444 .await?;
445 self.db
446 .prepare("UPDATE access_tokens SET agent_scope = ? WHERE id = ?")
447 .bind(&[
448 serde_json::to_string(&a.scope)?.into(),
449 created.info.id.as_str().into(),
450 ])?
451 .run()
452 .await?;
453 Ok(created)
454 }
455
456 /// What an agent's token may do, or `None` for any other token.
457 pub async fn agent_scope(&self, a: TokenArgs) -> Result<Option<AgentScope>> {
458 let scope: Option<Option<String>> = self
459 .db
460 .prepare(format!(
461 "SELECT agent_scope FROM access_tokens
462 WHERE token_hash = ? AND (expires_at IS NULL OR expires_at > {SQL_NOW})"
463 ))
464 .bind(&[crypto::sha256_hex(&a.token).into()])?
465 .first::<Option<String>>(Some("agent_scope"))
466 .await?;
467 Ok(scope
468 .flatten()
469 .and_then(|scope| serde_json::from_str(&scope).ok()))
470 }
471
472 pub async fn list_access_tokens(&self, a: UserArgs) -> Result<Vec<AccessToken>> {
473 let mut tokens = self.tokens_where("access_tokens.user_id = ?", &a.user.id).await?;
474 // A fine-grained token's selected repositories, by name.
475 self.name_repositories(&mut tokens, &Some(a.user)).await?;
476 Ok(tokens)
477 }
478
479 /// The tokens a person or workspace made on purpose: those that do not
480 /// expire, and those made with an expiry from settings, rather than
481 /// those issued to an application or a hosted agent.
482 async fn tokens_where(&self, owner: &str, id: &str) -> Result<Vec<AccessToken>> {
483 let rows = self
484 .db
485 .prepare(format!(
486 "SELECT {TOKEN_COLUMNS} FROM access_tokens
487 LEFT JOIN users ON users.id = access_tokens.created_by
488 WHERE {owner} AND (access_tokens.expires_at IS NULL OR access_tokens.listed = 1)
489 AND access_tokens.agent_scope IS NULL
490 ORDER BY access_tokens.id"
491 ))
492 .bind(&[id.into()])?
493 .all()
494 .await?
495 .results::<TokenRow>()?;
496 Ok(rows.into_iter().map(Self::info).collect())
497 }
498
499 pub async fn list_workspace_tokens(
500 &self,
501 a: WorkspaceTokensArgs,
502 ) -> Result<Outcome<Vec<AccessToken>>> {
503 let slug = a.slug.to_lowercase();
504 if !a.viewer.is_some_and(|viewer| viewer.is_member(&slug)) {
505 return Ok(Outcome::fail(
506 FailureCode::Forbidden,
507 "Only members can see a workspace's access tokens.",
508 ));
509 }
510 let Some(workspace) = self.get_workspace(SlugArgs { slug }).await? else {
511 return Ok(Outcome::fail(FailureCode::NotFound, "Workspace not found."));
512 };
513 Ok(Outcome::Ok(
514 self.tokens_where("access_tokens.workspace_id = ?", &workspace.id)
515 .await?,
516 ))
517 }
518
519 /// The workspace's id, if `actor` is a person who owns it.
520 async fn owned_workspace(&self, actor: &User, slug: &str) -> Result<Outcome<String>> {
521 let slug = slug.to_lowercase();
522 if actor.kind != PrincipalKind::User || actor.role_in(&slug) != Some(Role::Owner) {
523 return Ok(Outcome::fail(
524 FailureCode::Forbidden,
525 "Only an owner can manage a workspace's access tokens.",
526 ));
527 }
528 Ok(match self.get_workspace(SlugArgs { slug }).await? {
529 Some(workspace) => Outcome::Ok(workspace.id),
530 None => Outcome::fail(FailureCode::NotFound, "Workspace not found."),
531 })
532 }
533
534 pub async fn create_workspace_token(
535 &self,
536 a: CreateWorkspaceTokenArgs,
537 ) -> Result<Outcome<CreatedAccessToken>> {
538 let workspace_id = match self.owned_workspace(&a.actor, &a.slug).await? {
539 Outcome::Ok(id) => id,
540 Outcome::Fail(failure) => return Ok(Outcome::Fail(failure)),
541 };
542 if a.name.trim().is_empty() {
543 return Ok(Outcome::fail(
544 FailureCode::Invalid,
545 "Name the token after what will use it.",
546 ));
547 }
548 let existing = self
549 .tokens_where("access_tokens.workspace_id = ?", &workspace_id)
550 .await?;
551 if existing.len() >= MAX_TOKENS_PER_WORKSPACE {
552 return Ok(Outcome::fail(
553 FailureCode::Conflict,
554 "This workspace has the maximum number of access tokens. Delete one first.",
555 ));
556 }
557 // A workspace's token reaches that workspace only: it acts as the
558 // workspace (see `workspace_principal`), narrowed by its scopes.
559 let grant = Grant::asked(&a.scopes);
560 let mut created = self
561 .mint(
562 Owner::Workspace {
563 id: &workspace_id,
564 created_by: Some(&a.actor.id),
565 },
566 &a.name,
567 a.ttl_seconds,
568 &grant,
569 true,
570 )
571 .await?;
572 created.info.created_by = Some(a.actor.username.clone());
573 // Admin on the workspace's repositories, only when the owner says.
574 if a.admin {
575 self.db
576 .prepare("UPDATE access_tokens SET admin = 1 WHERE id = ?")
577 .bind(&[created.info.id.as_str().into()])?
578 .run()
579 .await?;
580 created.info.admin = true;
581 }
582 self.audit_workspace(
583 &a.actor,
584 "workspace_token.created",
585 &a.slug.to_lowercase(),
586 g1t_contracts::audit::Surface::Web,
587 format!(
588 "Created workspace access token {}{}",
589 created.info.name,
590 if created.info.admin { " with Admin" } else { "" }
591 ),
592 )
593 .await;
594 Ok(Outcome::Ok(created))
595 }
596
597 pub async fn remove_workspace_token(
598 &self,
599 a: RemoveWorkspaceTokenArgs,
600 ) -> Result<Outcome<bool>> {
601 let workspace_id = match self.owned_workspace(&a.actor, &a.slug).await? {
602 Outcome::Ok(id) => id,
603 Outcome::Fail(failure) => return Ok(Outcome::Fail(failure)),
604 };
605 let name: Option<String> = self
606 .db
607 .prepare("DELETE FROM access_tokens WHERE id = ? AND workspace_id = ? RETURNING name")
608 .bind(&[a.id.into(), workspace_id.into()])?
609 .first(Some("name"))
610 .await?;
611 if let Some(name) = name {
612 self.audit_workspace(
613 &a.actor,
614 "workspace_token.deleted",
615 &a.slug.to_lowercase(),
616 g1t_contracts::audit::Surface::Web,
617 format!("Deleted workspace access token {name}"),
618 )
619 .await;
620 }
621 Ok(Outcome::Ok(true))
622 }
623}
624
625#[cfg(test)]
626mod tests {
627 use super::*;
628
629 #[test]
630 fn a_row_without_scopes_is_legacy_full_access() {
631 assert_eq!(stored_scopes(None), (None, true));
632 assert_eq!(stored_scopes(Some("*")), (None, false));
633 assert_eq!(
634 stored_scopes(Some("issues:write repo:read nonsense")),
635 (Some(vec!["repo:read".to_owned(), "issues:write".to_owned()]), false)
636 );
637 }
638
639 #[test]
640 fn scopes_are_stored_as_text() {
641 let grant = Grant::asked(&Some(vec!["issues:read".to_owned(), "bogus".to_owned()]));
642 assert_eq!(grant.scopes_column(), "issues:read");
643 assert_eq!(Grant::asked(&None).scopes_column(), "*");
644 assert_eq!(Grant::asked(&Some(vec![])).scopes_column(), "");
645 }
646}