Scope and default
- Scope: every surface that serves fleet data or accepts fleet requests from
someone other than the owner. That covers the Mira desks (WhatsApp, Zalo,
Discord), the Fleet area of Mastermind web, the Fleet view of the Mastermind
mobile section, the
/api/v1/fleet/**API and the intent queue the orchestrator reads. - Default: deny. Nobody but the owner has fleet access until the owner grants it. A grant names one person, one tier, a set of projects and an optional expiry.
- Owner: the configured owner UUID that also holds a live explicit root
manage_mastermindgrant (see Mobile Mastermind). Both checks are required. The Owner tier cannot be granted. - Boundary with Mastermind: a fleet grant admits only Fleet routes and
/api/v1/fleet/**. Existing Mastermind shell data, hub, push and mobile Mastermind routes keep their owner-only gates. - Supplements, never replaces: fleet approval adds to existing custody, review, CI and release gates. An approved deploy intent still needs every gate the release runbooks require.
- Exceptions: the time-limited Slice 0 Observer described below.
Tiers
Tiers are ordered. Each tier holds every capability of the tiers below it, but only inside the projects its grant names.
A grant may hold fewer capabilities than its tier’s ceiling, never more; the
database rejects a grant above its ceiling.
approve.migration stays
Owner-only because production migrations need explicit owner approval.
Credentials, secrets and DNS have no fleet capability: no tier can ask the
fleet to read, rotate or reveal them.
Intent kinds and binding
Each intent kind defines its request capability, its approval capability and a strict payload schema made of enumerated values and server-resolved identifiers.
An Observer
ask executes as a read. Every Observer steer request is filed as
intent.request and needs Owner approval of the exact action.
- Authoritative project: the server resolves each target (lane, thread, repository path, deployment) to its owning project from the project catalog. A request naming a target outside the requester’s projects is refused, even when the request labels another project. The catalog’s target mapping carries a version number.
- Immutable approval: an approval binds one intent ID and a hash of the canonical action: kind, authoritative project IDs, every execution parameter, resolved targets, environment and commit SHA. Project ownership is re-resolved before dispatch, and any drift voids the approval.
- Desk requests: a desk-filed request never approves itself. Low- and
medium-risk requests from a desk wait for approval even when the requester
holds
approve.low. Desk-filedcommentandstatus_questionintents need no approval and still execute. - Owner at a desk: desk operations resolve a live grant row, and the Owner tier is never granted. The Owner needs a non-Owner grant, whose projects, capabilities and caps then apply, to use a desk.
- High risk: needs an approver other than the requester and an interactive step-up (fresh tuturuuu.com sign-in within five minutes). Chat channels can file high-risk requests but cannot approve them.
- Critical actions (migration, billing, access, fleet stop) stay Owner-only and outside the intent queue’s self-service paths.
Protections
- No secrets or private data. Fleet answers come from a digest of schema-validated status fields (lane, project, state, ETA, short SHA, release title, readiness item). Titles and readiness items are controlled values or explicitly approved display strings. Aggregates are computed only from the caller’s authorised projects, and the digest is filtered by those projects before any answer. Receipt reads are scoped to the requester or an authorised approver. It never includes raw coordination files, environment values, logs, transcripts, emails, phone numbers, customer names or host paths.
- No production, deploy, billing or credential action below Operator.
- Every steer is audited. Each intent, decision and refusal writes an append-only event with actor, channel, time, action and a reason code. The verbatim quote is stored separately, redacted, readable only by the Owner and the requester, and deleted after 90 days.
- Rate and budget caps per person. Each grant carries
questions_per_hour(default 30),intents_per_day(default 10) andmodel_budget_per_month. The database enforces them atomically with the insert. Exhausted caps defer the request and audit the refusal. - Requests are untrusted input. Execution briefs are built only from enumerated values and server-resolved identifiers. Quotes and comments stay on the display path and never reach an executing lane. Ask runs in a tool-free model context over the caller’s scoped digest only. Lane tool and target restrictions are enforced by the orchestrator, independent of model output.
- Live authorisation, revocation and stop. Every protected read and mutation checks the live grant. Grants and the fleet stop carry generation numbers. The consumer rechecks requester and approver grants and the stop generation at claim and dispatch, and the lease and generation fences are enforced at the side-effect boundary itself, together with the approved target-to-project mapping version, atomically with the action. An operation that cannot honour the fence is rejected. A stale lease, generation or mapping version fails closed and voids the approval. An uncertain dispatch is reconciled before any retry. Resume after a stop requires fresh authorisation for every fenced intent.
- Verified identity. See Identity. Display names prove nothing; an unlinked sender gets the desk’s ordinary behaviour.
Identity
- tuturuuu.com account: the source of truth for a person and their grant.
- Channel identity: a WhatsApp, Zalo or Discord sender linked to that account. Linking: the person signs in to the Fleet page and takes a single-use code valid for ten minutes, sends it to the desk in a private one-to-one conversation, then confirms the pending link on the signed-in page. The server stores a keyed hash of the provider sender ID, unique per provider account, together with the linked private conversation.
- Event binding: desks accept only authenticated provider events from approved private conversations. Linking, digest reads and submissions require API-verifiable event evidence from trusted ingress. The evidence binds the provider account, sender, conversation, event ID, the one permitted operation and a hash of its inputs. The API consumes the event ID atomically within its provider account, so a replay fails. The server resolves the actor from the linked provider account, sender and private conversation; desk credentials alone confer no actor authority.
- Person registry: each desk’s registry mirrors links and tiers for routing only. The API decides every request.
Surfaces
Mastermind web
The Fleet area lives in Mastermind web (apps/mastermind) at
mastermind.tuturuuu.com/{locale}/fleet-access. The #fleet anchor on the
Mastermind page shows machines and lanes, so the Fleet area takes its own
route. Tabs follow the live capabilities that GET /api/v1/fleet/access
returns, and the API still decides every read and write:
- Status (
status.read): lanes, releases, readiness items and blockers for the person’s projects, with each snapshot’s generated and received time and a stale badge. - Ask (
askandstatus.read): a project and a typed topic (status, readiness or timeline) answered from the scoped digest in the page, without a model. Free-text questions wait for the tool-free Ask execution path. - Requests: the person’s receipts with typed states and short intent IDs,
and a typed form per intent kind the grant can file. Kinds filed through
intent.requestare marked in the kind list, carry a persistent note and confirm as sent for Owner approval. Target keys are typed as catalog keys. - Link chat: issue a link code, send it to Mira in a private chat, preview the pending channel and account label, then confirm.
- Approvals (
approve.low) and Access (Owner only: grants, revocation, caps, fleet stop and the audit log) stay hidden until their APIs exist.
@tuturuuu/internal-api/fleet schemas.
Admission takes the actor only from the verified Tuturuuu Auth session (the
owner also needs a second-factor check from the last 24 hours) and admits a fleet grantee only to the Fleet page,
its assets and its server functions, rechecking the live grant on every
request. No Cloudflare Access application fronts the host, and identity
headers are ignored. See
Fleet access admission.
All strings ship in English and Vietnamese.
Mira chat
A verified person can ask about status, readiness and timelines. Mira answers from the scoped digest and says when it is more than one hour old. A steering request is acknowledged and filed as an intent; Mira never runs it.Mastermind mobile
A Fleet view appears to anyone whose fleet access answer is enabled, separate from the owner-only Mastermind entry and its offline fallback. The app decides nothing; the API enforces every rule.- Entries: the Apps hub’s “Fleet access” tile (“Quyền truy cập đội máy”),
its own app module beside the owner-only Mastermind tile; Today’s navbar
action; and a Requests row at the end of Inbox, which opens Requests. Each
shows only while the access answer is enabled, never while the check loads
or fails. The Apps hub’s pull to refresh and an app resume re-check a
failed answer, as they do for Mastermind.
?view=requests,?view=linkand?view=approvalsopen a segment, as does the app link/mastermind/fleet-access/requests(orlink,approvals). - Dock: the route belongs to the Fleet access module, not the Mastermind
tab shell. Someone the owner gate admits keeps the Mastermind tabs; anyone
else gets only Back, which falls back to the Apps hub. The code lives in
apps/mobile/lib/features/mastermind/fleet_access/. - Gate: only
GET /api/v1/fleet/accessdecides. The route is held on a skeleton while the check runs and redirected to the Apps hub when the answer is disabled or stopped, or the check is refused. A check that cannot finish shows a retry. The owner-only Mastermind gate does not apply to it. The answer is never stored, so there is no offline fallback. A 403 from any Fleet call, an app resume and pull to refresh re-check it, and logout or an account switch forgets it. - Status: lane totals, then each project’s latest snapshot with its received and generated times. A Stale badge shows when the server marks the snapshot stale or an hour has passed since receipt while it stays on screen.
- Requests: the person’s own receipts, newest first, with their typed
state and Show older. New request opens a full-screen form above the shell.
It offers the kinds the grant files directly or as
intent.request, the grant’s projects, and only the enumerated fields the kind sends. A kind the grant files only asintent.requestis marked “Needs Owner approval”, and sending it confirms “Sent for Owner approval.” Target keys and commit SHAs are checked against the API syntax before sending. Closing a filled form asks before discarding it, and a refusal stays on the form with a fixed category message. - Link chat: take a code (Copy, ten-minute countdown, a new code once it expires), send it to Mira in a private chat, paste the link ID and confirmation code Mira replies with, check the channel and desk account, then confirm.
- Approvals: shown only to a grant holding an approval capability, and read-only: no API lists or decides approvals yet.
- Sessions: the app calls every Fleet route with its Supabase bearer
session, the mobile access token. The reads and the writes
(
POST /api/v1/fleet/intents,identity/link-codesandidentity/confirm) accept it; a session the API refuses shows “Fleet couldn’t verify your session”.
Intent queue
- States:
pending_approval,approved,rejected,claimed,dispatched,done,failed,expired,cancelled. Pending intents expire after 72 hours. Transitions are enforced in the database. - Dry-run consumption: Cron Control examines at most 20 approved or
previously claimed intents per 15-minute tick. It uses a 15-minute lease
and the intent’s idempotency key. The database rechecks the stop, live
grants, target mapping and medium-risk quota at claim and receipt.
dry_runcloses the intent asdonewithout moving throughdispatched. Owner-required and high-risk approvals remain outside this consumer’s scope. After a restart, a still-live claim keeps its lease and key. An expired or stale lease is settled without renewal. See the consumer runbook.
Machine principals
Machine credentials confer no approval or grant authority.
Transitional Slice 0
Until the API exists, the desk host runs a local Observer rule:- the person registry holds an owner-confirmed Observer entry with the owner’s written authorisation as provenance;
- before every reply and every queue write, the desk verifies the provider’s authentication, matches the configured provider account, sender and private one-to-one conversation, rejects replayed events, and checks the stop file, revocation and expiry;
- a scheduled script on the desk host writes a sanitised digest from lane receipts every 15 minutes, using the field allowlist above;
- desks answer the Observer through a tool-free path from the Owner-approved project digest only;
- steering stays disabled: a steer request is only appended to a local queue for Owner review, and that queue cannot dispatch work;
- access ends on the local stop file, on revocation, or at the earlier of API cutover and the 2026-12-21 expiry.
Data model
Base tables stay private with no grants toanon or authenticated. Callers
reach them through SECURITY DEFINER functions with pinned search_path.
Each function revokes PUBLIC execution at creation and grants execution only
to its designated roles. The functions derive the actor from trusted request identity, scope
every read by live capability and project, and enforce quotas, state
transitions and audit writes atomically.
Triggers reject updates and deletes on audit events, capabilities above the
tier ceiling and Owner-tier grants. Fleet access is not a workspace role
permission and is never implied by creator,
admin or default permissions.
The database starts with an empty grant table and an unconfigured Owner UUID.
Configuring private.fleet_control.owner_user_id is a separate database-owner
operation. The management functions require a database-owner connection with
the verified user’s request identity and a live explicit root Mastermind grant.
The service role can submit a server-resolved intent. The insert checks the
live grant, project versions and the rolling one-hour question and 24-hour
intent counts. The daily intent quota is the medium-risk budget. Slice 5
rechecks that budget at claim and dry-run completion. Model budget consumption belongs to the Ask
execution path.
Auth account deletion revokes the grant and retains its generation and historical
intent references. Fleet grant, project and control rows retain their fences.
The Observer API uses service-role-only definer functions. It binds read actors
to verified Tuturuuu sessions and checks live grants, stop state and project
scope before reading digest rows.
Slice 3 binds submissions to the signed-in web user, a Supabase session
bearer (the mobile access token), a Mastermind app-session user, or a desk
event verified against a separate trusted ingress key.
The platform CLI audience can read its own receipts and cannot submit,
issue a link code, or confirm one. The desk’s event
fingerprint, linked actor lookup and intent admission share one database
transaction. Authoritative target aliases resolve across the project catalog,
and the resolved action hash excludes the display quote.
Slice 4 requires v2 desk evidence and a live, unquiesced desk-owner row for
every desk operation. FLEET_DESKS carries key material only. The database
checks the bearer, verifying key, signed claims and owner generation in the
action transaction before consuming the event. Owner changes advance the
generation by one through Owner-only audited functions, and a retired desk
credential is never admitted again. The desk digest returns the linked
actor’s grant-scoped snapshot and uses the same hourly question quota as
status-question intents. Approval requires a separate authorized principal.
See the desk API and cutover procedure.
Link codes expire after ten minutes and a signed-in account must confirm the
pending link with proof returned in the verified private conversation. The page
can preview the pending provider and account label before confirming. A fresh
code or an expired confirmation attempt clears pending identity fingerprints.
Authenticated desk-event refusals without a linked actor carry a channel and
reason in the append-only audit log.
Keep replay fingerprints for 90 days from consumed_at. Trusted ingress
must enforce provider-event freshness, including when it signs a redelivered
event. The Cloudflare retention job purges expired link codes, expired quotes and
event fingerprints older than 90 days. Unconfirmed link codes stay usable
until expiry. Confirmation consumes the code and account deletion removes its
codes. Every scheduled purge records counts in the append-only audit log.
Quote readers must filter on expires_at from their first release.
Activation
Shipping code grants nobody access. Each step below is separate, and each is run by the owner or the release owners:- Database: the gated production migration workflow applies the Fleet migrations after their exact-SQL review, CI and staging.
- Grant: the Owner grants a person a tier and projects through the owner-only grant function. That person needs a tuturuuu.com account.
- Catalog and digest: the Owner registers project catalog rows and approved display values, and the digest publisher token is issued so status exists to read.
- Web admission: none beyond the grant. The person signs in to Mastermind web with their tuturuuu.com account, and the live grant admits them to the Fleet area, as described in the Mastermind web runbook.
- Mobile: the next app release carries the Fleet access view and its Apps hub tile.
- Chat desks: each desk follows the v2 cutover in the API reference. Until then, Slice 0 stays dormant on the desk host.
- Consumer: the Slice 5 consumer token and mode are set only when dry-run receipts are wanted. Its kill switch and the Fleet stop both halt it.
Implementation plan
Slice 4 cutover requires Slice 5 acceptance. Slice 8 live dispatch requires
passing lease, reconciliation and durable stop-fence tests. New scheduling and
delivery for slices 2 and later run on Cloudflare.
Regression coverage
Each slice links its coverage here when it lands:- Slice 1 covers default deny, table and function privileges, tier ceilings, Owner-only mutations, audit immutability, quota refusals, quote expiry, grant and project fences, and intent approvals and leases. See fleet-access.sql.
- Slice 1 also races two PostgreSQL sessions against the final question and steer slots. See fleet-access-quota-race.sql.
- Slice 2 covers default deny, live revocation, no-store responses, scoped totals, strict schema validation and the machine-only publish boundary in the Fleet route tests. The digest SQL tests cover actual project filtering, revoked and expired grants, stop, label approvals and snapshot ordering.
- Slice 3 covers write audience restrictions, strict payload schemas, desk
signature, input binding and freshness, one-time events and codes, signed-in
preview and confirmation, refusal audit, target scope, receipt reads,
revocation, quota, quote isolation and digest JSON types.
See route tests,
mobile write-session tests,
and fleet-intent-admission.sql.
The write-session tests admit a verified Supabase bearer on intent submit,
link-code issue, and link confirmation, and refuse a
platformCLI session, an unknown bearer, and a forgedx-user-id. - Slice 6 covers tab visibility per tier, request options against intent admission, typed drafts, digest answers, redirect refusal, strict response validation, refusal mapping, the link flow and bilingual message parity. See the Fleet access web tests.
- Slice 6 admission covers grantee reach, 403 on every owner route without session work, revocation and stop on the next request, identity binding, unchanged Owner admission and pinned server-function IDs in fleet-admission.test.ts.
- Slice 5 covers racing claims, lease expiry, idempotent receipts,
requester and approver generations, mapping drift, the dispatch fence and
bounded retention in
apps/database/supabase/tests/fleet-dry-run-consumer.sql.apps/cron-control/src/fleet-access-consumer.test.tsexercises operation limits, stop and restart through the scheduler and ledger.apps/web/src/app/api/v1/fleet/consumer/route.test.tschecks bearer isolation, request bounds and the private RPC bindings. - Slice 7 covers the mobile gate (disabled, enabled, stopped, failed, revoked mid-session, account reset, the owner gate exemption), the Apps hub tile, the grantee and owner docks in the real shell (registered destinations), strict parsing, the stale badge, request validation and payloads, receipts paging and the link flow in the Fleet access mobile tests.
- Slice 4 covers Owner-only transitions, privileges and pinned search paths, monotonic generations, direct-write fences, credential history, quiesce, every bearer, key and claim mismatch, stale replicas, linked conversation and project scope, capability, stop, revocation, shared question quotas, desk self-approval and cross-operation replay in fleet-desk-admission.sql. The Fleet desk route tests cover v2 proof, v1 claims, signature domain and configuration rejection, strict digest inputs, scoped totals and denial responses.