plan.md
c136 plan: Mechanic Access (draft, before kick-off)
Gate: c130 D6 ruled (2026-11-09). Kick-off waits for the plane's identity model (c134 D2) and Tyler's say on where grants live. Phase 0 (prior art) can run now. Reader: Mark; Tyler for the plane side; the build partner's admin, who is the audience of the grant screen and the docs; c134's and c131's executors. Mode: formula (time-boxed, scoped access is a codified pattern: support roles, break-glass, access transparency) → assemblage (the grant is composed from the plane's identity, the audit log and the native app's Status line). Defaults: D1–D7 confirmed by Mark on 2026-11-09; the clarifying questions stay open for Tyler and the partners. Where it came from: Mark's words in the c130 walk, not a customer call. Team judgement until a partner is asked (clarifying question 1).
Why
A build partner runs a plane (one running control-plane instance, SaaS or self-hosted) with their own data in it. Qpoint will need to get in: to fix a documented problem, to implement a feature they asked for, to hot-fix an incident. Without a design, that is a screen share or a shared credential, which is the kind of exposure the product exists to remove. Mark's framing: the partner opens access to Qpoint for three days, for a stated reason, at a documented level, and closes it. If the categories and levels are specified now, before the first plane ships, partners grant with confidence and we never ask for more than the job needs.
Through the methodology: a grant is a module with a purpose (why) and a protocol (what, for how long, logged how). The partner does not need to know how our mechanic works, only what they let in. Visibility before control: the partner sees what is being done under the grant while it runs and what was done when it closes. The brand's "vigilant guardian you don't have to think about" applied to our own access is a documented, time-boxed, audited door.
The shape
A grant is one record on the plane:
| Field | Meaning |
|---|---|
| Purpose | one category (below) and the partner's own sentence: "fix the ClickHouse retention bug, ticket 142" |
| Level | observe · operate · change (below) |
| Scope | the whole plane, or named parts: one endpoint group, one integration, the database layer |
| Window | start, duration (1 h · 1 d · 3 d · 7 d at most), automatic expiry; revocable at any moment |
| Who | the admin who granted; the Qpoint people admitted, by name, never a shared account |
| Record | every action under the grant in the audit log carrying the grant id; a summary to the admin at close |
Purpose categories. The three Mark named, plus the one that comes before them:
- Diagnose: look, change nothing. An investigation before any of the next three.
- Fix a documented problem (a ticket exists).
- Implement a feature the partner asked for.
- Hot-fix an incident in progress.
Levels. Each said in one sentence on the grant screen:
- Observe: read configuration, logs, metrics and the audit log; no event payloads unless the scope names them.
- Operate: observe, plus restart services, run shipped migrations, change settings.
- Change: operate, plus deploy a build or a hot-fix. The highest level, the shortest default window.
Honest states. In the web app: "Qpoint has access to this plane until Thursday 14:00 (fix · operate). 3 actions so far." In the native app's Status page: one line when a grant is active on the plane this endpoint reports to; when none, nothing (invisible when working).
Rules
- R1. The partner grants. Qpoint never self-grants and never holds standing access to a customer's plane.
- R2. Every grant ends. Short defaults, seven days at most; a renewal is a new grant with its own record.
- R3. Least level by default. Diagnose and observe are the defaults; the admin raises them.
- R4. Named people. Each action in the audit log names the person, never "Qpoint support".
- R5. The partner can watch. Actions under a grant are visible live and summarised at close; revocation is one click and immediate.
- R6. Plain words. The grant screen says what each level allows in one sentence; no jargon (brand).
- R7. Nothing phones home. A self-hosted plane with no Qpoint reachability simply has no grants.
Decisions (defaults)
| # | Question | Default |
|---|---|---|
| D1 | Where grants live | the plane (c134). Grants are plane objects; the native app only reads them. |
| D2 | Who can grant | the plane's org admin; optional second-admin approval for the Change level, off by default. |
| D3 | How the mechanic gets in | with a named Qpoint identity (OIDC from Qpoint's IdP) that the partner's plane accepts only while a grant names it; for a self-hosted plane with no reachability, a one-time invitation link that expires with the grant. |
| D4 | Transport | the same plane API and web app the partner uses, under the grant's level. No separate back door. Shell access only at Change level and only to the plane's own containers. |
| D5 | The audit record | one access.grant.* event family (opened · action · revoked · closed) in the same stream as everything else; each action carries the grant id. |
| D6 | Categories and levels | the four purposes and three levels above; adding one is a cycle decision, not a configuration. |
| D7 | Native app surface | read-only: the Status line and the audit entries. The grant flow itself belongs to the web app. |
Phases
0. Prior art (written 2026-11-11)
How others do it, in a short prior-art.md: AWS support roles and IAM session duration; Google Access Transparency and Access Approval; Azure Customer Lockbox; GitHub App installation screens (permissions as sentences); Tailscale's admin console; break-glass patterns. What to copy, what to refuse.
Written: prior-art.md, 2026-11-11, with Okta and Salesforce as the seventh precedent and Kolide for the words. It tests the model against each, adds the session and the request as records, the ticket and the requested-versus-granted window as fields, four events to D5's family, and nine questions (5 to 13 there) with defaults.
1. The model
The grant, categories, levels, states and events as data; the sentences for R6; the states for the two honest surfaces.
2. The mock
The grant screen and the active-grant states in the lab, in c134's shell; the Status line as a c131 story. Review stop.
3. The contract
Routes and events agreed with Tyler and Kamal; aligned with c134's identity decision (D2 there). Added to c134's API document.
4. The partner page
One page a build partner's admin reads before granting, in the same sentences as the UI. With Mark Peterson's install docs if they are under way.
5. Hand-off
To c134 (the plane side) and c131 (the Status line); the record here.
Clarifying questions
- Are the four purposes the words partners use, or do they think in "incident", "change request", "support case"? Ask two partners before Phase 1.
- Should the Change level need two admins (D2)?
- Does a grant ever reach an endpoint machine (our mechanic inside a laptop), or only the plane? Default: plane only.
- Do the contracts need a line that mirrors the levels? Probably; later, with Rob.
Patterns to consider
- Access Transparency (Google): every access logged with its reason and visible to the customer. The model for R5.
- Permissions as sentences (GitHub Apps): the model for R6.
- The grant as a story on the design site: none · requested · active · revoked · closed with summary. Five states, one component in the layer and one in the kit.
- The same door for partners' partners: an MSP managing a customer's plane later uses the same grant. Note it; do not build it.
- The grant notice is a message: when a grant opens on a plane, the operators get a message through c137's channel. One schema, not a second one.