control-plane-api: expose capability bundles and bits in GraphQL, deprecate legacy capability fields

[GregorShear]

Next step in migrating the GraphQL API off the legacy ordered Capability enum (read/write/admin) and onto the orthogonal capability model, staged so the frontend can migrate operation-by-operation. The Capability type keeps its name; every field that reports it is deprecated, with a fine-grained CapabilityBit replacement to migrate to.

• Bundle variants are renamed to action-oriented names (Viewer→View, Writer→Write, Editor→Edit, Billing→ManageBilling, TeamAdmin→ManageUsers, ManageDataPlane→ManageDataPlanes), with a migration that relabels the capability_bundle enum values in place — existing user_grants.bundles / role_grants.bundles rows carry over without a backfill.
• prefixes(by:) gains a withCapabilities: [CapabilityBit!] filter and deprecates minCapability — a "minimum" has no meaning in the orthogonal model. The filter takes fine-grained bits rather than bundles because the bundle → bit mapping is dynamic: callers state the operations they need without tracking bundle composition. Both inputs reduce to a required CapabilitySet matched by superset; the user must hold all listed capabilities, so listing more only narrows results. Supplying both is an error, and supplying neither applies no capability filter.
• The GraphiQL playground now requests inputValueDeprecation in introspection, so deprecated inputs render struck through instead of disappearing from the docs.

Every legacy capability output (DataPlane.userCapability, StorageMapping.userCapability, LiveSpecRef.userCapability, PrefixRef.userCapability, InviteLink.capability, RedeemInviteLinkResult.capability) is now @deprecated, and each gains a capabilityBits: [CapabilityBit!] replacement reporting the user's fine-grained capabilities. UI gating consumes bits exclusively — resource-shaped types deliberately do not report bundles, which are a grant-time concept.

• LiveSpecRef's capabilityBits is null when the user has no access, mirroring userCapability.
• InviteLink and RedeemInviteLinkResult additionally report capabilityBundles: [CapabilityBundle!]! — the bundle explicitly selected when the link was created (bundles_for_legacy), not everything the grant implies: an admin link reports [Admin], not also ManageUsers, ManageBilling, etc. — while capabilityBits carries the full effective set (bits_for_legacy). createInviteLink still takes the single legacy capability input; input-side migration is deferred until invite links store explicit capability bundles.
• PrefixRef.capabilities: [CapabilityBit!]! already shipped, so it stays bits-typed and wire-compatible, deprecated as renamed to capabilityBits, and gets deleted once clients migrate — the capabilities name is never reused with a different type.
• New plumbing: tables::UserGrant::get_user_capabilities returns the union of capability bits at prefixes covering a name; attach_user_capabilities hands resolvers both the legacy capability and the bit set.
• flowctl builds with -D warnings and graphql_client turns schema deprecations into Rust #[deprecated], so its queries opt out via deprecated = "allow" until flowctl migrates.

Deploy ordering

The relabel migration must run before the new code rolls out, since the new binary reads and writes the new labels. During the rollout window, old pods can't decode grant rows carrying renamed bundle labels (only one tenant affected), and the old binary's private data-plane provisioning still writes manage_data_plane, which the relabeled enum rejects — avoid provisioning a private data plane mid-deploy.

[GregorShear]

make sure we can still see deprecated input fields in the graphql playground

[GregorShear]

i haven't quite figured out whether this migration should be (or can be) run before or after the deployment ... someone help me think about this

[GregorShear]

I think the strategy will be to run this migration right before we deploy the new build - my understanding is that there would be a few moments where snapshot refresh will fail, but it should recover gracefully (see error condition at /flow/crates/control-plane-api/src/server/snapshot.rs line 409)

[GregorShear]

And also there's only one tenant with a capability bundle manage_data_plane

[GregorShear]

keeps flowctl build working with deprecated fields

[jshearer]

Should this really be called capabilityBundles to align with capabilityBits right below?

[jgraettinger]

Drive by question: are we thinking to expose capability bits as a user / API facing concern? I'm a little unclear just from glossing the PR.

My last understanding of the agreed approach is that the DB and API surfaces would only ever speak in terms of bundles, never bits -- bits are purely an implementation detail internal to the code of a released control plane application, so that we have flexibility to allocate new bits and change the mapping of bundle => bits at any time (aside: it's fine to have a bundle that maps to a single bit, but the key property we're preserving is freedom to re-map that bundle from one bit to multiple bits as a transparent operation).

[jshearer]

Maybe we should chat about ☝️? From my POV, the capability bits are the actual atoms that gate authorization questions ("can this subject perform this action to this object"), and multiple bundles can compose them. Thinking about the UI's behavior, it's going to need to answer those same questions in order to gate UI features/behavior: "can this user read billing info for this tenant", "can this user publish to this prefix", and maybe in a fancy future world, "can this prefix read data from this other prefix?"

Those are all questions answered by capability bits, not bundles. Put another way, the logic that decides whether to show the billing tab in the admin UI shouldn't need to know that both TeamAdmin and ManageBilling (or whatever we end up calling these bundles) both confer the ViewBilling capability bit.

OTOH, the "invite user" and "create service account" UI flows will clearly operate over bundles not bits, since that's how the grants behave. Indeed, the list of users with access to your tenant should probably also show their bundles, rather than enumerate all of their grant's composed bits. I don't have high conviction on whether we should actually communicate the concept of "bits" + "bundles" to users. It seems reasonable enough to hide the "bits" concept from the user, even though the UI will still use them internally to manage what features a user has access to visually.

[GregorShear]

Maybe we should chat about ☝️? From my POV, the capability bits are the actual atoms that gate authorization questions ("can this subject perform this action to this object"), and multiple bundles can compose them. Thinking about the UI's behavior, it's going to need to answer those same questions in order to gate UI features/behavior: "can this user read billing info for this tenant", "can this user publish to this prefix", and maybe in a fancy future world, "can this prefix read data from this other prefix?"

Those are all questions answered by capability bits, not bundles. Put another way, the logic that decides whether to show the billing tab in the admin UI shouldn't need to know that both TeamAdmin and ManageBilling (or whatever we end up calling these bundles) both confer the ViewBilling capability bit.

OTOH, the "invite user" and "create service account" UI flows will clearly operate over bundles not bits, since that's how the grants behave. Indeed, the list of users with access to your tenant should probably also show their bundles, rather than enumerate all of their grant's composed bits. I don't have high conviction on whether we should actually communicate the concept of "bits" + "bundles" to users. It seems reasonable enough to hide the "bits" concept from the user, even though the UI will still use them internally to manage what features a user has access to visually.

I think we're in agreement about bundles being the main user-facing concept - users will interact with bundles when managing user (and service account) access.

UI logic will operate on bits, i.e. show edit button X if user has capabilityBit Y on prefix Z... I guess i don't have an opinion on whether or not the users ever see the named bits. I imagine knowing which bundles carry which bits could be useful, where a disabled edit button might show a tool tip that says "This requires capability A B or C - talk to your admin" but I don't think we have to decide that now.

[jshearer]

Greg and I talked this through on a call today. The conclusion is that we're deferring this PR and shipping service accounts first on legacy read/write/admin, for a couple reasons:

• A service account is deliberately just an ordinary auth.users user with ordinary user_grants, so that it works through flowctl and the existing PostgREST path without making the GraphQL migration a prerequisite to shipping. PostgREST can only authorize along the read/write/admin axis, so any API that still has PostgREST callers has to keep working off a legacy capability; bundles and bits were always scoped to new GraphQL-only APIs. That means a service account grant carries a legacy capability exactly like a user grant does: authorization-wise we can't do anything different for service accounts than we do for users.
• We haven't started unbundling yet (e.g. splitting billing out of admin), and we can't meaningfully unbundle anything whose surfaces still have PostgREST callers, since those callers only understand read/write/admin. So there's nothing more for the service accounts UI to show than read or admin anyway. Same goes for invite links. A bundles-only service account API would just synthesize a legacy capability under the hood without getting us any closer to actual unbundling.

We'll pick this PR back up after, as its own focused effort: actually exercising bundles, the UX for selecting them, and the great unbundling. None of the API groundwork here changes: grants still take/report bundles alongside the legacy capability, resources still report bits.