flagon-io/g1t

public

1	# sudo
2
3	g1t's staff console, at <https://sudo.g1t.sh>: the back office g1t is
4	building for itself, for sales, support and finance. It is organised the
5	way customers know g1t: by workspace.
6
7	The sidebar (`app/lib/nav.ts`) has Overview and Reach out at the top, then
8	sections that fold open to their pages: Customers, Revenue, Platform,
9	Support and Team. Each fold is a `<details>`, drawn open for the section
10	holding the current page; on a phone the same menu sits behind a "Menu"
11	button in the top bar. Pages not built yet are marked Soon: each is a
12	real page (`routes/soon.tsx`, made from its entry in `nav.ts`) saying what
13	it will do, why, and what it will have, so the sidebar doubles as the
14	roadmap.
15
16	- Overview (`/`): this month charged, cost and margin; the last six
17	months as a chart; this month by kind of usage; paying workspaces; how
18	many are stopped, near their limit or declined (each a link into Reach
19	out); open invoices; follow-ups due; and the five most urgent signals.
20	From billing's `admin_overview` and `admin_signals`.
21	- Reach out (`/reach-out`): every workspace worth a word, most urgent
22	first (at limit, declined, near limit, high spend, growing, established,
23	first payment), with its owners, the reason in a sentence, the figure,
24	and its sales stage and owner at g1t. Filter by why and by whose
25	(everyone's, unassigned, mine), or show only follow-ups due (a next
26	step due today or earlier, on a deal not won or lost; one per
27	workspace). Rows show the next step and its day. Each row opens the
28	workspace's Sales.
29	- Invoices (`/invoices`): every invoice g1t has sent, workspaces' and
30	enterprises', newest first (`admin_invoices`, at most 200). Filter by
31	status and month; totals for what is listed (amount, paid, outstanding);
32	each links to its workspace or enterprise and to Stripe's page (https
33	only).
34	- Audit log (`/audit`): every change made in sudo, and what Stripe told
35	billing, newest first, 100 a page with "Older" (`admin_audit`). Filter by
36	staff email and kind of change; each line links to its workspace or
37	enterprise.
38	- Workspaces (`/workspaces`): every workspace, newest first, 50 to a
39	page, with its owners, members, who it is billed to, its terms, this
40	month's usage against its limit, what it was charged and what it cost
41	g1t. Search by workspace, owner, email or enterprise (across the whole
42	list); filter to stopped or warning, comped or custom, or on an
43	enterprise. Billing's figures are fetched for exactly the page shown, so
44	the filters, and the totals over the list, cover that page; the page
45	says so when there is more than one. A workspace's page shows its members;
46	Sales (its stage, the staff member who has it, the next step and its
47	date, and notes, newest first; `admin_sales`, `admin_set_sales`,
48	`admin_add_note`); and under Billing its limit in words (trust, the
49	owners' own spend limit or the default, the most they may set, how it
50	grows), its last six months as a chart, its invoices (`admin_workspace_invoices`,
51	with Stripe's page and PDF), its terms, who it is billed to (move it onto or off an
52	enterprise), a credit form, a Stripe billing link, its ledger and its
53	audit log. If billing does not answer for sales or invoices, the page
54	still opens and says so in those sections. A protected workspace (one
55	nobody can ever delete: identity's `PROTECTED_WORKSPACES`, and
56	flagon-io always) says so beside its name.
57	- Deleted workspaces (`/workspaces/deleted`, linked from Workspaces):
58	workspaces their owners deleted, newest first (`admin_deleted_workspaces`),
59	each with who deleted it and when, when it is purged, what went with it
60	(repositories, projects, members, counted at the deletion) and the days
61	left. An owner deletes a workspace with everything in it in one step, and
62	identity keeps it 30 days (`WORKSPACE_RESTORE_DAYS`) so support can undo a
63	deletion that was a mistake or not theirs to make. Restore
64	(`admin_restore_workspace`) brings it back with its members and tokens,
65	and its repositories, projects and apps with `workspace.restored`; its
66	plan stays ended, so its owners start it again from Billing. Check that
67	whoever asks is an owner of it before restoring. Purge now
68	(`admin_purge_workspace`, the slug typed to confirm) removes it at once,
69	as the sweep does every 15 minutes once its 30 days are up; never for a
70	protected workspace. Both go in the workspace's audit log, as g1t, and in
71	sudo's (`workspace_restored`, `workspace_purged`), naming the staff
72	member.
73	- A person's page (`/users/<username>`, linked from a workspace's
74	members): their addresses (remove one, with a reason they see), their
75	security log, and Delete account. An account made with a shared
76	invite link says Joined through <label> under its name, linking to
77	the link on Invites. Delete only when the person asks
78	(from one of the account's confirmed addresses) or for abuse: give the
79	reason, which goes in sudo's audit log (`account_deleted`), and type the
80	username (`admin_delete_account`). It does what deleting their own
81	account from Settings does: signs them out everywhere, ends their tokens,
82	SSH keys, deploy keys they added and applications, takes them out of
83	every workspace, team and repository, and emails their addresses that
84	staff deleted it. While the account is the **only owner of a live
85	workspace**, the page lists those workspaces, each linking to its page,
86	and the form becomes **Delete account and the workspaces it alone
87	owns**: the reason, the username typed, and a box ticked to say the
88	named workspaces go too (`admin_delete_account` with
89	`withSoleWorkspaces`). Use it for an account g1t no longer needs, such
90	as a retired test account and its personal workspace; for a customer,
91	prefer another owner first (an owner makes one under People). Identity
92	checks every one of those workspaces before anything is deleted: one
93	that is protected, or whose billing cannot settle (`close_workspace`:
94	an unpaid invoice, prepaid credit, usage still metering, an enterprise
95	account), refuses the whole deletion, and the page says which and why
96	beside each, instead of the form. Then it deletes each workspace exactly
97	as its owner would (billing closes it, `workspace.deleting`, its
98	repositories and apps go with it, kept 30 days), with the staff member
99	as who deleted it, and the account last. Each workspace is recorded in
100	its own audit log as g1t (rule `staff`) and in sudo's
101	(`workspace_deleted`, with the reason); the account in sudo's
102	(`account_deleted`, naming the workspaces). Should one fail on the way
103	(a card declined that moment), the account is not deleted and the
104	error names the workspace and any that went before; restore those from
105	Deleted workspaces, or try again. Accounts that can never be deleted (`g1t`, `g1t-agent`, `ghost`,
106	and whatever identity's `PROTECTED_ACCOUNTS` names, by username or id)
107	are marked Protected and offer no form. A deleted account's page
108	says so, with who deleted it, why, when it is purged, and Restore and
109	Purge now, as on Deleted accounts; both work at once, with no wait.
110	When workspaces were deleted with it, it lists them too, each with its
111	own Purge now (`admin_purge_workspace`, the slug typed; identity
112	purges only a workspace that is still deleted, never a protected one),
113	so staff can remove everything straight away. Purge the workspaces
114	first: once the account is purged its page is gone (they stay on
115	Deleted workspaces). To undo it all, restore the account first, then
116	each workspace, so it comes back with its owner.
117	- Deleted accounts (`/users/deleted`, linked from Workspaces):
118	accounts deleted by the person or by staff, newest first
119	(`admin_deleted_accounts`), each with who deleted it (the person, or the
120	staff member and why), when it is purged, the days left and what it
121	left (workspaces, teams, repositories, tokens, SSH keys). Identity keeps
122	each 30 days (`ACCOUNT_RESTORE_DAYS`). Restore
123	(`admin_restore_account`) clears the deletion and puts back the
124	memberships, teams and repository roles it left where they still exist;
125	its sessions, tokens and keys stay ended, and the person signs in with
126	their password. Check that whoever asks owns one of its addresses first.
127	Purge now (`admin_purge_account`, the username typed) removes it at
128	once, as the sweep does every 15 minutes once its 30 days are up: its
129	row, addresses, keys, two-factor secret, GitHub link, profile and
130	security log go; its username is kept in `deleted_users` and never given
131	out again; what it wrote shows as `ghost`. Both go in sudo's audit log
132	(`account_restored`, `account_purged`), naming the staff member. There
133	is no API route for deleting an account; only the site and sudo can.
134	- Invites (`/invites`): g1t.sh is invite-only, and this page holds
135	every way in, one tab each. Waitlist: people who asked for access;
136	approve (identity mints an invite bound to the address and emails it,
137	with an optional note) or dismiss, one at a time or ticked together.
138	Invites: every invite code, searchable by a code's start, an email
139	or a username; revoke a pending one. Shared links: one link for a
140	group, such as the competition's judges, a post or a community. Make
141	one with a label (required, and not secret: sign-up says "Invited as
142	part of <label>"), how many accounts it makes (1 to 1000), its last day
143	(14 days ahead unless changed; up to a year; it works until the end of
144	that day, UTC) and, optionally, the email domains it is limited to
145	(exact domains, up to 10). Each use makes a new account, which makes its
146	own workspace: a shared link never joins anyone to an existing
147	workspace, and uses nobody's invites. The list shows each link's state
148	(live, used up, expired, revoked), its uses against its cap, its
149	expiry, who made it, the link itself in a read-only field to select and
150	copy while it is live (`https://g1t.sh/register?invite=<code>`;
151	identity keeps only the code's hash and a copy sealed under
152	IDENTITY_KEY), Revoke, and everyone who joined through it. Making
153	and revoking go in sudo's audit log (`shared_invite_created`,
154	`shared_invite_revoked`, filed under "Shared invite links"), naming
155	the staff member (`admin_shared_invites`,
156	`admin_create_shared_invite`, `admin_revoke_shared_invite`).
157	Grant & mint: more invites for a person or a workspace (a negative
158	number takes some back), and a one-off invite that uses nobody's.
159	Invite tree: where a person came from (who invited them, staff, or
160	the shared link they joined through) and whom they brought, three
161	levels down.
162	- Aliases (`/aliases`, under Customers): names that lead to a
163	workspace, set by staff only; there is no way for a customer to make
164	one, and nothing user-facing mentions them. `g1t`, the product's name,
165	leads to `flagon-io`, Flagon, Inc. (seeded by identity's migration
166	`0029_workspace_aliases.sql`), so nobody mistakes the trading name for
167	the organization. Every address under an alias leads to the workspace:
168	pages answer with a 301 to the same page (`/g1t/g1t/issues` to
169	`/flagon-io/g1t/issues`), git over HTTPS is answered in place as the
170	workspace's repository (pushes do not follow redirects), the API and MCP
171	run the call again under the workspace's slug, and the package
172	registries answer a 301 (308 for a publish). An alias points at the
173	workspace's id, so it follows a rename; it goes when the workspace is
174	purged. Each row shows the workspace, why the alias exists, and who added
175	it and when. Add (`admin_set_alias`) takes the alias, the
176	workspace's slug and why: identity refuses the site's own routes
177	(`settings`, `api`…), anyone's username, a workspace's slug (deleted, or
178	held after a rename for another workspace) and an existing alias.
179	Reserved names such as `g1t` can be aliases, and an alias is nobody's to
180	register or rename a workspace to while it exists. Remove
181	(`admin_remove_alias`) needs a reason. Both go in sudo's audit log
182	(`alias_added`, `alias_removed`), naming the staff member. `@g1t` in
183	text still means g1t's agent: it links to how the agent works, never to
184	`/g1t`.
185	- Enterprises: customers that pay for several workspaces with one
186	bill, one limit and one set of terms. Each has its workspaces (add or
187	remove them), combined usage, terms, credits, ledger and audit log, and
188	Invoices: where they go (the billing email, which also makes its
189	Stripe customer), a "Send invoice now" button, and every invoice with
190	its status (open, paid, overdue, void), a line per workspace, and a link
191	to Stripe's hosted invoice page. An invoice also goes out on its own as
192	each month closes: one Stripe invoice, a line per workspace for what it
193	owes, net 30, emailed by Stripe.
194	- Agents & models (`/agents`, under Platform): billing's model
195	catalogue, every model g1t can use (`admin_models`). **Check for new
196	models** lists each provider's models now, through the model proxy's
197	`Discovery` entrypoint (the `MODELS` binding), as the daily check does;
198	the result says what each provider listed, what is new or gone, or why a
199	provider could not be listed. Defaults: the model behind each of
200	Auto's tiers, the harness's background model and the AI Gateway's first
201	Claude (an available, priced Claude each, shown with what a typical run
202	costs on it), and each kind of job's starting tier and effort. A change
203	needs a reason and shows a review first, the current and new value side
204	by side with what a typical run would cost on each, before Save
205	(`admin_set_model_default`); runs pick it up within a minute. A default
206	that has fallen back (its model retired or no longer listed) says so.
207	New models: each model a check found, with its prices filled in
208	where known; confirm its name, tier and prices per million tokens (and
209	long-prompt prices) and Approve, or Retire it
210	(`admin_decide_model`). Catalogue: every other model with its status,
211	context, prices, typical run and when its provider last listed it, each
212	with Retire or Restore. Checks: the latest checks of each
213	provider. Every change names the staff member and why in the audit log
214	(account `models`). See docs/BILLING_OPERATIONS.md, "The model
215	catalogue".
216	- Stripe: whether billing's key is in test or live mode (or off), the
217	webhook Stripe calls (URL, endpoint id, events, who registered it and
218	when), and the events Stripe sent lately with what billing did with
219	each. "Register webhook" (or "Replace") has billing delete the endpoint
220	it made before, create a new one and keep its signing secret, which no
221	one sees. Do it once per mode, and again after switching to live keys.
222
223	Sales changes are not money, so they have no confirmation step; they are
224	still POSTs from sudo's own pages, recorded with who made them.
225
226	Billing's internal account ids (`ws_<slug>` for a workspace's own,
227	`ent_…` for an enterprise) are never shown as names; an enterprise's id
228	appears only as small "Billing account id" text. Old `/accounts/…` links
229	redirect to the workspace or enterprise they meant.
230
231	Cards stay on Stripe. sudo never shows a card field. To help a customer
232	update their card or see invoices, staff make a Stripe billing link on the
233	workspace's page (it is recorded) and send it to the owner.
234
235	It holds no data. Workspaces, owners and members come from identity's
236	staff methods (`admin_workspaces`, `admin_workspace`; `IdentityAdminApi` in
237	`packages/contracts/src/identity.ts`); everything about money goes to the
238	billing service's (`admin_*`, `BillingAdminApi` in
239	`packages/contracts/src/billing.ts`), where each change is recorded with
240	the staff member's email. Both are reached over service bindings only, and
241	nothing but sudo binds to them.
242
243	## How it is locked
244
245	1. Cloudflare Access sits in front of `sudo.g1t.sh` and signs people in.
246	2. The worker checks Access's work on every request, the stylesheet
247	included (`run_worker_first`): it verifies the `Cf-Access-Jwt-Assertion`
248	JWT itself (RS256 against the team's published keys, audience, issuer,
249	expiry), then requires its email to be in `STAFF_EMAILS`. That email is
250	who every change is recorded as. See `app/lib/access.ts`.
251	Service tokens. A program (Claude, working without a browser) signs
252	in with an Access service token instead: it sends `CF-Access-Client-Id`
253	and `CF-Access-Client-Secret`, the Access application has a policy with
254	the Service Auth action that includes the token, and Access sends
255	sudo a JWT with no email whose `common_name` is the token's client id.
256	sudo lets it in only if that client id is in `STAFF_SERVICE_TOKENS`
257	(`<client id>=<name>`, comma separated, in `wrangler.jsonc`), after the
258	same signature, audience, issuer and expiry checks, and records it as
259	`<name>@service.g1t.sh`: `claude@service.g1t.sh` for
260	`claude-sudo`. Its secret lives in `.credentials/sudo-service-token.json`
261	and is used by `scripts/ops/sudo.mjs`, which sends sudo's own `Origin`
262	with each POST so the same-origin check applies to it as to a browser.
263	To take its access away, remove its entry here, or delete or revoke the
264	token in Zero Trust.
265	3. It fails closed. Until `ACCESS_TEAM_DOMAIN`, `ACCESS_AUD` and
266	`STAFF_EMAILS` are all set, every request gets a 403 saying sudo is not
267	configured.
268	4. Changes are POSTs only, and only from sudo's own pages (`Origin`, or
269	`Referer`, must be `https://sudo.g1t.sh`). Terms, enterprise moves, new
270	enterprises, Stripe billing links, invoice emails, invoices and the
271	webhook show a confirmation step first; a credit needs the workspace's
272	slug typed out.
273	5. The pages ship no JavaScript. The content security policy forbids
274	every script and inline style; responses are `no-store`, `noindex` and
275	cannot be framed. The worker has no `workers.dev` address or preview URLs.
276
277	## Setting up Access (once, in the Cloudflare dashboard)
278
279	1. Zero Trust → Access → Applications → Add an application → Self-hosted.
280	- Application name: `sudo`.
281	- Session duration: short, such as 8 hours.
282	- Public hostname: `sudo.g1t.sh` (path empty, so it covers everything).
283	2. Add a policy (`g1t staff`): action Allow, include Emails → the
284	owner's address, and Emails ending in → `g1t.sh` for everyone with a
285	g1t address (the same entries as `STAFF_EMAILS`, where a domain is
286	written `@g1t.sh`). Add more staff here and in `STAFF_EMAILS`; either
287	one alone is not enough.
288	3. Save, then open the application's Overview (or Basic information)
289	and copy the Application Audience (AUD) tag.
290	4. Find the team domain under Zero Trust → Settings → Custom pages
291	(or Team name and domain): it looks like `<team>.cloudflareaccess.com`.
292	5. Put both into `wrangler.jsonc`:
293
294	```jsonc
295	"vars": {
296	"ACCESS_TEAM_DOMAIN": "<team>.cloudflareaccess.com",
297	"ACCESS_AUD": "<the AUD tag>",
298	"STAFF_EMAILS": "syntaqx@gmail.com, @g1t.sh"
299	}
300	```
301
302	6. Deploy: `scripts/deploy.sh sudo` (after `billing` and `identity`, whose
303	`admin_*` methods it calls).
304
305	Visit <https://sudo.g1t.sh>: Access asks you to sign in, then the workspaces
306	list opens. Anyone else gets Access's own refusal; anyone Access lets in who
307	is not in `STAFF_EMAILS` gets a 403 from the worker.
308
309	## Signing in through WARP
310
311	Staff signed in to the Zero Trust org in the Cloudflare One agent (WARP)
312	reach sudo without the login page: the org allows WARP sessions as Access
313	sign-ins (8 hours), the sudo app accepts them, and the `g1t staff` policy
314	is also on the WARP enrollment app, so staff can enroll their devices.
315	The same two checks still apply: the Access policy, and `STAFF_EMAILS`.
316
317	## Working on it
318
319	```sh
320	npm run typecheck -w @g1t/sudo
321	npm test -w @g1t/sudo # JWT verification, forms, money, the workspace join, paging, nav, charts, signals, models
322	npm run build -w @g1t/sudo
323	```
324
325	`npm run dev` serves the pages, but every request is refused without a real
326	Access token, by design.