Skip to content
Sign up

flagon-io/g1t

public
0
396 linesCodeBlameRaw

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.

Agents get guardrails, run credentials, an audit log, a context hub, repository instructions and mentions; security upkeep; snake_case API1//! The audit log: who did what, with which credential, to what, and
2//! whether it was allowed.
3//!
4//! Every action taken with a run credential is recorded, reads included,
5//! and so is every change people and workspace tokens make through the API
6//! and git. Refusals are recorded with the rule that refused them. Entries
7//! are only ever appended.
8//!
9//! The events service keeps the log, beside the event log; the API and the
10//! repos service, which see the requests, write to it. Methods, served at
11//! `POST /rpc/<method>` on the events service:
12//!
13//! - `audit_record` takes `RecordAuditArgs` and returns how many were kept.
14//! - `audit_list` takes `ListAuditArgs` and returns `AuditPage`. Callers
15//! check who may see a workspace's log and say so in `visibility`.
16
17use serde::{Deserialize, Serialize};
18
19use crate::credentials::{Acting, Decision};
20use crate::{PrincipalKind, User};
21
22/// What kind of actor did it.
23#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
24#[serde(rename_all = "snake_case")]
25pub enum ActorKind {
26 Person,
27 Agent,
28 /// A workspace's own access token.
29 Workspace,
Fast pages, required checks on the branch, self-hosted runners, honest incidents30 /// A self-hosted runner, with its own credential.
31 Runner,
Git storage hardened, pages in tens of milliseconds, honest security alerts, and costs reconciled daily32 /// g1t itself: what the platform does on its own, such as a security
33 /// update or a merge from the queue.
34 System,
Agents get guardrails, run credentials, an audit log, a context hub, repository instructions and mentions; security upkeep; snake_case API35}
36
37impl ActorKind {
38 pub fn as_str(self) -> &'static str {
39 match self {
40 ActorKind::Person => "person",
41 ActorKind::Agent => "agent",
42 ActorKind::Workspace => "workspace",
Fast pages, required checks on the branch, self-hosted runners, honest incidents43 ActorKind::Runner => "runner",
Git storage hardened, pages in tens of milliseconds, honest security alerts, and costs reconciled daily44 ActorKind::System => "system",
Agents get guardrails, run credentials, an audit log, a context hub, repository instructions and mentions; security upkeep; snake_case API45 }
46 }
47}
48
49/// Whether the action was let through.
50#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
51#[serde(rename_all = "snake_case")]
52pub enum AuditOutcome {
53 Allowed,
54 Denied,
55}
56
57impl AuditOutcome {
58 pub fn as_str(self) -> &'static str {
59 match self {
60 AuditOutcome::Allowed => "allowed",
61 AuditOutcome::Denied => "denied",
62 }
63 }
64}
65
66/// Where the request came in.
67#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
68#[serde(rename_all = "snake_case")]
69pub enum Surface {
70 Rest,
71 Mcp,
72 Git,
Invite-only launch: sign in with GitHub, repository access and lifecycle, many emails, a new look73 /// g1t.sh itself: settings changed on its pages.
74 Web,
Packages, with a container registry on g1t.sh; workspaces deleted whole and kept 30 days; Members for every member75 /// The package registries: `docker push`, `npm publish` and the like.
76 Registry,
Agents get guardrails, run credentials, an audit log, a context hub, repository instructions and mentions; security upkeep; snake_case API77}
78
79/// The actor of an entry, from whoever made the request.
80#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
81#[serde(rename_all = "camelCase")]
82pub struct AuditActor {
83 pub actor_kind: Option<ActorKind>,
g1t is one name: its agent's work, commits and comments show as @g1t, and nobody can claim g1t or g1t-agent84 /// The username: a person's, the agent's (`g1t`), or the
Agents get guardrails, run credentials, an audit log, a context hub, repository instructions and mentions; security upkeep; snake_case API85 /// workspace's slug.
86 pub actor: String,
87 pub actor_id: String,
88 pub agent: Option<String>,
89 /// The person an agent acted for.
90 pub on_behalf_of: Option<String>,
91 pub run_id: Option<String>,
92 pub run_kind: Option<String>,
93 /// The token used, when one was.
94 pub credential_id: Option<String>,
95}
96
Merge branch 'worktree-agent-a3abfcce648e87dca'97/// The `run_kind` of what a workflow job's token did.
98pub const WORKFLOW_JOB: &str = "workflow_job";
99
Agents get guardrails, run credentials, an audit log, a context hub, repository instructions and mentions; security upkeep; snake_case API100impl AuditActor {
101 pub fn of(user: &User) -> Self {
102 let kind = match user.kind {
103 PrincipalKind::User => ActorKind::Person,
104 PrincipalKind::Agent => ActorKind::Agent,
105 PrincipalKind::Workspace => ActorKind::Workspace,
Git storage hardened, pages in tens of milliseconds, honest security alerts, and costs reconciled daily106 PrincipalKind::System => ActorKind::System,
Agents get guardrails, run credentials, an audit log, a context hub, repository instructions and mentions; security upkeep; snake_case API107 };
108 let acting: Option<&Acting> = user.acting.as_deref();
Merge branch 'worktree-agent-a3abfcce648e87dca'109 // A workflow job's token: what it does is the job's, under its run.
110 let job = user.token.as_deref().and_then(|token| token.job.as_ref().map(|job| (token, job)));
Agents get guardrails, run credentials, an audit log, a context hub, repository instructions and mentions; security upkeep; snake_case API111 AuditActor {
112 actor_kind: Some(kind),
113 actor: user.username.clone(),
114 actor_id: user.id.clone(),
115 agent: acting.map(|acting| acting.agent.clone()),
116 on_behalf_of: acting.map(|acting| acting.on_behalf_of.username.clone()),
117 run_id: acting
118 .and_then(|acting| acting.run())
Merge branch 'worktree-agent-a3abfcce648e87dca'119 .and_then(|run| run.run_id.clone())
120 .or_else(|| job.map(|(_, job)| job.run_id.clone())),
Agents get guardrails, run credentials, an audit log, a context hub, repository instructions and mentions; security upkeep; snake_case API121 run_kind: acting
122 .and_then(|acting| acting.run())
Merge branch 'worktree-agent-a3abfcce648e87dca'123 .map(|run| run.kind.as_str().to_owned())
124 .or_else(|| job.map(|_| WORKFLOW_JOB.to_owned())),
Merge main into Artifacts Phase 2125 // The token used, whatever the surface: a person's or a
126 // workspace's on the API, MCP or git, and a person's on the
127 // website (apps/web, app/lib/website-token.ts).
Merge branch 'worktree-agent-a3abfcce648e87dca'128 credential_id: acting
129 .map(|acting| acting.credential_id.clone())
Merge main into Artifacts Phase 2130 .or_else(|| job.map(|(token, _)| token.token_id.clone()))
131 .or_else(|| user.token.as_deref().map(|token| token.token_id.clone()).filter(|id| !id.is_empty())),
Agents get guardrails, run credentials, an audit log, a context hub, repository instructions and mentions; security upkeep; snake_case API132 }
133 }
134
Git storage hardened, pages in tens of milliseconds, honest security alerts, and costs reconciled daily135 /// g1t itself, as the actor of what it does on its own.
136 pub fn system() -> Self {
137 AuditActor {
138 actor_kind: Some(ActorKind::System),
139 actor: crate::system::USERNAME.to_owned(),
140 actor_id: crate::system::ID.to_owned(),
141 ..AuditActor::default()
142 }
143 }
144
Agents get guardrails, run credentials, an audit log, a context hub, repository instructions and mentions; security upkeep; snake_case API145 /// Whether everything this actor does is recorded, reads too.
146 pub fn records_reads(&self) -> bool {
147 self.actor_kind == Some(ActorKind::Agent)
148 }
149}
150
151/// What an action was done to.
152#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
153#[serde(rename_all = "camelCase")]
154pub struct AuditTarget {
155 /// The workspace's slug: whose log it goes in.
156 pub workspace: String,
157 /// `owner/name`, when the action was about one repository.
158 pub repo: Option<String>,
159 /// The issue or pull request.
160 pub number: Option<u32>,
161 /// A full git ref, such as `refs/heads/main`.
162 pub git_ref: Option<String>,
163 /// A file, or another path the action named.
164 pub path: Option<String>,
165}
166
167/// An entry to record. The log assigns the id and time.
168#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
169#[serde(rename_all = "camelCase")]
170pub struct NewAuditEntry {
171 #[serde(flatten)]
172 pub actor: AuditActor,
173 /// An API or MCP operation, such as `create_issue`, or `git.push` and
174 /// `git.fetch`.
175 pub action: String,
176 pub surface: Surface,
177 #[serde(flatten)]
178 pub target: AuditTarget,
179 pub outcome: AuditOutcome,
180 /// The rule that allowed or refused it, such as `run:implement/tools`,
181 /// `scope:repository` or `member`.
182 pub rule: String,
183 /// `ok`, or the failure's code when the service refused or failed it.
184 pub result: Option<String>,
185 /// Why it was refused, when it was.
186 pub message: Option<String>,
187 pub request_id: String,
188}
189
190impl NewAuditEntry {
191 pub fn new(
192 actor: AuditActor,
193 action: impl Into<String>,
194 surface: Surface,
195 target: AuditTarget,
196 decision: &Decision,
197 request_id: impl Into<String>,
198 ) -> Self {
199 NewAuditEntry {
200 actor,
201 action: action.into(),
202 surface,
203 target,
204 outcome: if decision.allowed {
205 AuditOutcome::Allowed
206 } else {
207 AuditOutcome::Denied
208 },
209 rule: decision.rule.clone(),
210 result: None,
211 message: decision.reason.clone(),
212 request_id: request_id.into(),
213 }
214 }
215}
216
217/// A recorded entry.
218#[derive(Clone, Debug, Serialize, Deserialize)]
219#[serde(rename_all = "camelCase")]
220pub struct AuditEntry {
221 pub id: String,
222 /// RFC 3339.
223 pub time: String,
224 #[serde(flatten)]
225 pub entry: NewAuditEntry,
226}
227
228#[derive(Clone, Debug, Default, Serialize, Deserialize)]
229pub struct RecordAuditArgs {
230 pub entries: Vec<NewAuditEntry>,
231}
232
233/// Which of a workspace's entries the viewer may see.
234#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
235#[serde(tag = "kind", rename_all = "snake_case")]
236pub enum AuditVisibility {
237 /// An owner: everything.
238 All,
239 /// A member: what was done to the workspace's projects, and what they
240 /// did themselves or had done on their behalf; not what owners did to
241 /// the workspace itself.
242 Projects { username: String },
243}
244
245/// The most entries one `audit_list` returns.
246pub const MAX_AUDIT_PAGE: u32 = 500;
247
248#[derive(Clone, Debug, Serialize, Deserialize)]
249#[serde(rename_all = "camelCase")]
250pub struct ListAuditArgs {
251 pub workspace: String,
252 pub visibility: AuditVisibility,
253 /// Matches the actor or whoever an agent acted for.
254 #[serde(default)]
255 pub actor: Option<String>,
256 #[serde(default)]
257 pub agent: Option<String>,
258 #[serde(default)]
259 pub action: Option<String>,
260 /// `owner/name`.
261 #[serde(default)]
262 pub repo: Option<String>,
263 #[serde(default)]
264 pub number: Option<u32>,
265 #[serde(default)]
266 pub outcome: Option<AuditOutcome>,
267 #[serde(default)]
268 pub actor_kind: Option<ActorKind>,
269 /// Entries of these runs only.
270 #[serde(default)]
271 pub run_ids: Vec<String>,
272 /// RFC 3339; inclusive.
273 #[serde(default)]
274 pub since: Option<String>,
275 /// RFC 3339; exclusive.
276 #[serde(default)]
277 pub until: Option<String>,
278 /// Entries older than this entry id, for the next page.
279 #[serde(default)]
280 pub before: Option<String>,
281 #[serde(default)]
282 pub limit: Option<u32>,
283}
284
285/// Newest first.
286#[derive(Clone, Debug, Default, Serialize, Deserialize)]
287#[serde(rename_all = "camelCase")]
288pub struct AuditPage {
289 pub entries: Vec<AuditEntry>,
290 /// Pass as `before` for the next page; null on the last.
291 pub next: Option<String>,
292}
293
294#[cfg(test)]
295mod tests {
296 use super::*;
297 use crate::credentials::{CredentialUse, Principal, RunBinding, RunCredentialKind};
298 use crate::identity::AgentScope;
299 use crate::repos::RepoPath;
300
301 #[test]
302 fn an_agent_is_recorded_with_who_it_worked_for() {
303 let user = User {
304 id: "usr_g1t_agent".to_owned(),
g1t is one name: its agent's work, commits and comments show as @g1t, and nobody can claim g1t or g1t-agent305 username: "g1t".to_owned(),
Agents get guardrails, run credentials, an audit log, a context hub, repository instructions and mentions; security upkeep; snake_case API306 kind: PrincipalKind::Agent,
307 acting: Some(Box::new(Acting {
308 credential_id: "tok_9".to_owned(),
g1t is one name: its agent's work, commits and comments show as @g1t, and nobody can claim g1t or g1t-agent309 agent: "g1t".to_owned(),
Agents get guardrails, run credentials, an audit log, a context hub, repository instructions and mentions; security upkeep; snake_case API310 on_behalf_of: Principal {
311 id: "usr_1".to_owned(),
312 username: "syntaqx".to_owned(),
313 },
314 scope: AgentScope {
315 repo: RepoPath {
316 namespace: "acme".to_owned(),
317 name: "rocket".to_owned(),
318 },
319 operations: vec![],
320 run: Some(RunBinding {
321 kind: RunCredentialKind::Implement,
322 usage: CredentialUse::Tools,
323 run_id: Some("run_3".to_owned()),
324 number: Some(4),
g1t is one name: its agent's work, commits and comments show as @g1t, and nobody can claim g1t or g1t-agent325 agent: "g1t".to_owned(),
Git storage hardened, pages in tens of milliseconds, honest security alerts, and costs reconciled daily326 system: false,
Agents get guardrails, run credentials, an audit log, a context hub, repository instructions and mentions; security upkeep; snake_case API327 read: vec![],
328 push: vec![],
329 }),
330 },
331 })),
332 ..User::default()
333 };
334 let actor = AuditActor::of(&user);
335 assert_eq!(actor.actor_kind, Some(ActorKind::Agent));
336 assert_eq!(actor.on_behalf_of.as_deref(), Some("syntaqx"));
337 assert_eq!(actor.run_id.as_deref(), Some("run_3"));
338 assert_eq!(actor.run_kind.as_deref(), Some("implement"));
339 assert_eq!(actor.credential_id.as_deref(), Some("tok_9"));
340 assert!(actor.records_reads());
341
342 let person = AuditActor::of(&User {
343 id: "usr_1".to_owned(),
344 username: "syntaqx".to_owned(),
345 ..User::default()
346 });
347 assert_eq!(person.actor_kind, Some(ActorKind::Person));
348 assert!(!person.records_reads());
Merge main into Artifacts Phase 2349 assert_eq!(person.credential_id, None, "signed in: no token");
350 }
351
352 #[test]
353 fn a_person_using_a_token_is_recorded_with_it_on_any_surface() {
354 let user = User {
355 id: "usr_1".to_owned(),
356 username: "syntaqx".to_owned(),
357 token: Some(Box::new(crate::scopes::TokenAccess {
358 token_id: "tok_web".to_owned(),
359 website: true,
360 ..crate::scopes::TokenAccess::default()
361 })),
362 ..User::default()
363 };
364 let actor = AuditActor::of(&user);
365 assert_eq!(actor.actor_kind, Some(ActorKind::Person));
366 assert_eq!(actor.actor, "syntaqx");
367 assert_eq!(actor.credential_id.as_deref(), Some("tok_web"));
368 assert!(!actor.records_reads());
Agents get guardrails, run credentials, an audit log, a context hub, repository instructions and mentions; security upkeep; snake_case API369 }
370
371 #[test]
372 fn an_entry_carries_the_rule_that_refused_it() {
373 let entry = NewAuditEntry::new(
374 AuditActor::default(),
375 "merge_pull_request",
376 Surface::Mcp,
377 AuditTarget::default(),
378 &Decision::deny("never", "No."),
379 "req_1",
380 );
381 assert_eq!(entry.outcome, AuditOutcome::Denied);
382 assert_eq!(entry.rule, "never");
383 assert_eq!(entry.message.as_deref(), Some("No."));
384 let json = serde_json::to_value(&entry).unwrap();
385 // Flattened, in the names the site reads.
386 assert_eq!(json["outcome"], "denied");
387 assert_eq!(json["surface"], "mcp");
388 assert!(json.get("actorKind").is_some());
389 assert!(json.get("gitRef").is_some());
390 let visibility = serde_json::to_value(AuditVisibility::Projects {
391 username: "ana".to_owned(),
392 })
393 .unwrap();
394 assert_eq!(visibility["kind"], "projects");
395 }
396}

This file's history is long; its oldest lines are credited to the oldest commit read.