Skip to content

Latest commit

 

History

History
368 lines (338 loc) · 24.8 KB

ROADMAP.md

File metadata and controls

368 lines (338 loc) · 24.8 KB

Roadmap

This is the implementation roadmap for Rise's active architectural work. Normative behavior lives in the ADRs; this file tracks delivery order and must not duplicate or redefine those decisions.

Status legend: [x] shipped · [~] in progress · [ ] planned.

Governing decisions

1. Generic resource and authorization foundation

Shipped substrate

  • Generic resource envelope, Postgres resource store, built-in and external kind registration, optimistic concurrency, finalizers, and garbage collection.
  • Generic HTTP resource API with operator-only compatibility authorization.
  • Default Organization bootstrap and existing typed-row linkage.
  • Typed built-in resource registry.

Unified identity and RBAC

  • Move the dep-light ResourceStore contract and canonical SubjectId, dynamic-label SubjectRef, group-qualified ResourceKind, and Scope types into rise-resource-api; keep SQLX and Postgres adapters in rise-resource-store-postgres.
  • Implement policy types and validation for Role, RoleBinding, PlatformRole, and PlatformRoleBinding: structured roleRef, one subject per binding, normalized PascalCase subjectMembership: Any | ResourceOrganization on platform bindings (omission becomes Any; null is invalid), canonical scopes, pure Allow/Deny tuple evaluation, placement provenance, wildcard replacement, and Deny-aware subset checks. Activate these resources only through transaction-scoped normalization/admission.
  • Add closed contracts for the built-in identity resources: root User and Controller; Organization-owned Group and ServiceAccount; and fixed-parent UserIdentity, GroupMembership, ControllerTrustPolicy, and ServiceAccountTrustPolicy. User and UserIdentity carry platform-managed active state, defaulting true; shipped policy does not allow self-editing. GroupMembership is an empty marker named for its User. Reserve their collection definitions now, but activate them only through the transaction-scoped normalization/admission seam.
  • Add optional, UID-authoritative metadata.ownerReferences to the generic resource envelope and implement transactional reverse lookup, cycle-safe, finalizer-respecting dependent garbage collection. GroupMembership may name its User as lifecycle owner; backend-managed memberships normally do so, while operator-managed markers may intentionally remain unowned. Land this before GroupMembership runtime activation.
  • Add partial Postgres indexes for unique external User mappings, target-parent workload trust lookup, and reverse name-based membership edges. These remain internal storage projections and do not change the generic resource API shape.
  • Implement live membership expansion, per-item list filtering/projection, effective-label resolution, typed SubjectRef values for dynamic ownership, tiered platform/org Deny filtering, admin/operator classification, platform ceilings, and the centralized authorization choke point replacing require_operator. The choke point is live on the generic resource API, with per-item list filtering, the allowlisted list-only projection, and metadata.effectiveLabels on every response. Controllers are ordinary controller:<name> principals evaluated by the same choke point, whether they authenticate with a JWT matched against their trust policies or with an identity token from their /token subresource; the ResourceDefinition.allowedStatusControllerIds allowlist is removed.
  • Add Role/policy audit and explain diagnostics for semantically inert configuration — no-op recipient or membership constraints, owners with no current grant, selectors matching nothing, stale references, and shadowed Allows — as engine::audit (rise-authz) and its HTTP surface: the GET /api/v1/resources/policy-audit listing and the read-only explain subresource, both filtered per finding on the caller's own list/get grants. Diagnostics never reject a write: a create or update of a RoleBinding/PlatformRoleBinding runs the same detectors against the row just written and surfaces any finding as an HTTP Warning header, never as a failure.
  • Add request-local AuthorizationSnapshot memoization for membership, admin classification, and effective policies. Defer cross-request caching until it can be invalidated transactionally through an authorization epoch.
  • Decide cross-request authorization caching on measurement, not ahead of it. The request-local snapshot already removes the repeated cost inside one request; what remains is one role lookup per distinct roleRef on a snapshot's first evaluation, which batching fixes with no schema commitment — do that first. Only if authorization is still a measurable share of request time once the typed-object migration (§4) puts real traffic on the engine should a cross-request cache land, and then through a transactionally incremented global authorization_epoch keyed by at least principal UID, token-cap hash, epoch, and resource identity. A write path that forgets to bump the epoch is a stale-authorization bug no test will surface, which is why the measurement comes first.
  • Implement the write-time grant gate for Roles, bindings, membership, identity mappings, and access-driving labels. All authorization-changing writes use serializable transactions with bounded retry. The gate is rise-authz::engine::gate, including §6.6's label diff over the K-inheriting subtree and the credential-ceiling intersection; the resource API's write paths run it inside the SERIALIZABLE transaction that performs the mutation, replaying the whole operation on a serialization failure. A cascading delete's effect on policy resources beneath the deleted resource is not yet diffed.
  • Seed immutable/healable system-admin and platform resource-owner Roles, plus an operator-editable global PlatformRole/org-admin baseline. Organization creation atomically creates an exact org-root, scope-only RoleBinding from that role to an operator-selected existing User. That direct binding is the first admin's bootstrap affiliation; no pre-existing Group is required and no Group name has implicit authorization meaning. The five baseline resources are seeded at startup and the operator pair is immutable through the store; atomic Organization-plus-admin-binding creation is available on an Organization create via bootstrap.admin, in the same transaction and rolled back together on failure.
  • Add conformance coverage for every applicable ADR-0001 acceptance scenario, including multi-org admins, membership removal, UID-bound token invalidation, token caps, and grant/revocation races. A /// ADR-0001 scenario N marker on each covering test is enforced by mise run adr:conformance:check; scenario 10's operator-selector half remains deferred until the operatorIdentities item below lands.
  • Add the constrained Project ServiceAccount lifecycle operation. It uses fresh never-reused canonical names and atomically creates/deletes only its fixed Project-scoped policy and trust bundle, applying the effective-delta subset check to the result; ordinary Project users do not receive generic ServiceAccount or Role/RoleBinding creation authority.
  • JIT-create a generated User plus first UserIdentity after a validated unknown login. An inactive exact identity or inactive parent User fails without JIT; deleting a mapping permits a later login to provision a fresh User UID, so durable disablement uses active: false. Email never links accounts.
  • Load operatorIdentities (issuer, subject) selectors at process startup and derive operator status live when any identity attached to that User is active and matches the configured set. Reject hot reload; configuration changes complete only after all old instances are drained. Operators remain the recovery tier; legacy admins become qualifying default-org RoleBindings.

Resource API maturation

  • Reject create below an ancestor that is already tombstoned. Built-in placement validation walks the whole chain and refuses a deleting ancestor; ResourceDefinition-registered kinds have no equivalent check, so a create can still add a child to a subtree the garbage collector is draining. Creation is the case that matters, and it matters most under a deleting Organization, whose policy resources are tombstoned with it while an operator-authored platform grant survives. Reads, delete, and the status/finalizers subresources must keep working, or controllers cannot remove their finalizers and the subtree never drains.
  • Add pagination plus label/field selectors. Labels remain JSONB initially; measure before introducing a separate label table.
  • Add JSON Merge Patch and RFC 6902 Patch through the common mutation pipeline. Main writes preserve protected status and finalizers; subresource writes mutate only their protected fields.
  • Add Server-Side Apply and managed fields without allowing main-resource apply to claim protected subresource fields.
  • Add secret/protected schema annotations with encryption at rest and response redaction.
  • Serve discovery, JSON Schema, and OpenAPI from the registry using the canonical group-qualified ResourceKind vocabulary and registered subresources.
  • Add a resumable Watch API with explicit backpressure, connection limits, and observability.
  • Build rise-resource-client in the shape of Kubernetes' dynamic client: (group, version, plural) plus ancestor-name addressing over untyped envelopes, verbs and named subresources that line up one-to-one with the authorization tuples, Rise-issued credential providers (a session bearer, and a /token-refreshed identity token from an external assertion or a delegating principal), watch resume, and generic finalizer/subresource helpers. The e2e harness and the CLI's token source become its first consumers; typed wrappers for built-in kinds layer on top later.
  • Add built-in version conversion and define external ResourceDefinition schema-evolution behavior.
  • Close built-in (group, kind) shadowing and finish audit coverage for RBAC, Patch/Apply, discovery, and subresource execution.

2. Rise-issued authentication and token issuance

Shipped transition

  • Extracted JWT verification/signing into rise-backend-auth.
  • Added the transitional POST /api/v1/auth/token exchange endpoint, Rise access-token claims, middleware consumption, and CLI auto-exchange.
  • Finish raw-external-token deprecation telemetry, then disable and remove direct external JWT acceptance from ordinary resource endpoints.

Authentication entry points

Every way a credential enters Rise, and whether it stays. A new credential path is added to this table in the same change that introduces it, and nothing permanent is built on an endpoint marked retires.

Entry point Credential presented Status Why / gate
Browser login (/auth/signin → /auth/callback) IdP authorization code and host-only browser nonce Stays Human UI login; callback requires the initiating browser proof before code exchange; PKCE and single-use state bind the back-channel exchange
CLI login (/auth/code/exchange) IdP authorization code Stays Human CLI login; retains its flow-specific PKCE and callback correlation
CLI device login (/auth/device/exchange) Rise-issued device code, approved on Rise's /device page Stays Machines without a local browser. The approving session must be a browser session (rise_client: browser, so a CLI session can never mint its successor), must be fresh (≤ 10 min, so it traces back to a bound browser login), and must name its User and identity. The device session is minted for that same (User, UserIdentity) and re-checked when redeemed. The code is single-use, stored hashed, and expires in 10 min. No IdP token is presented
App sign-in (/.rise/auth/signin/start → /auth/signin/begin → /auth/callback → /.rise/auth/complete) IdP authorization code plus independent app-host and central-host browser proofs Stays Callback and completion require their respective initiating-browser proofs; the transaction pins project identity and exact app origin. The app-scoped ingress token keeps the IdP sub because apps read it
/token on ServiceAccount / Controller — workload exchange External assertion (Kubernetes projected token, CI OIDC, …) Stays The target design for every non-human caller; checked only against the target's trust policies
/token on ServiceAccount / Controller — delegated issuance Rise bearer holding (create, <kind>, token) Stays Minting for another identity, optionally for an external audience
POST /api/v1/identity/token Deployed app's bootstrap credential Stays Outbound federation from deployed apps (AWS STS, GCP WIF, Vault); not authentication to Rise
Raw external JWTs on API endpoints (auth.allow_raw_external_tokens) Third-party JWT, unexchanged Retires Disabled, then removed, once deprecation telemetry shows no use (item above)
POST /api/v1/auth/token with identity CI OIDC JWT for a typed project service account Retires Replaced by ServiceAccount /token; gated on every typed service account migrating and its traffic draining to zero (item below)
POST /api/v1/auth/token without identity External JWT matching a ControllerTrustPolicy Retires Duplicates Controller /token; removed once the remaining controllers (rise-k8s-controller, §5) use /token. With the row above gone, the endpoint is deleted
Legacy session tokens (no rise_uid) Session issued before User resolution Retires No longer minted; they lapse within one session lifetime and are refused by the resource API meanwhile
Operator standing by email / IdP group (auth.operator_users, auth.operator_idp_groups) — (configuration) Retires Replaced by operatorIdentities selectors (§1)
ID-token exchange for sessions Presented IdP ID token Rejected Would honor any ID token the IdP issues for Rise's client (cross-client trust, token exchange, multi-audience) with no PKCE/state/nonce binding, and provision Users from it. Reconsidered only behind an opt-in setting, off by default, with a single aud, azp == client_id, and the session capped at the ID token's expiry

Target convergence

  • Issue User sessions with canonical sub plus immutable rise_uid after exact live, active UserIdentity (issuer, subject) and active parent User resolution. Sessions carry typ: rise-session+jwt and are re-resolved on every request.
  • Move workload token exchange to each ServiceAccount or Controller /token subresource, introduced additively per kind: a resource-API-backed identity gains its /token route without touching any other, not-yet-migrated identity of the same kind still on the legacy exchange endpoint. Validate external assertions only against trust-policy children of that URL target; do not perform a global source-identity search, and mask target/assertion/policy failures behind the same coarse authentication error. The route is live on rise.dev/ServiceAccount and rise.dev/Controller; the minted identity token (RS256, typ: rise-identity+jwt, canonical sub plus rise_uid) is a principal of the generic resource API, re-resolved to one live resource on every request, and the same token minted for a requested audience is verifiable by that party against Rise's JWKS.
  • Support delegated issuance on the same /token route for an already Rise-authenticated principal holding (create, qualified ResourceKind, token). Workload exchange and delegated request modes are disjoint.
  • Add a canonical RFC 9396 authorization_details claim with type: rise.dev/rbac, one qualified scope per entry, and multiple entries whose permissions union. Reject empty permission axes, carry the parsed cap on AuthenticatedPrincipal, and enforce live RBAC intersected with that cap on every primary and secondary decision.
  • Add bounded nested act attribution. Delegation chains are allowed only across explicit live token-create grants; there is no token-class/one-hop bypass rule.
  • [~] Reject stale UID tokens, inactive/deleted principals, Group subjects as principals, malformed subjects/scopes, and external workload JWTs on every non-token endpoint. Identity tokens are rejected on every one of those grounds; raw external JWTs on ordinary endpoints remain governed by the transitional auth.allow_raw_external_tokens above.
  • Retire the typed service_accounts table, its synthetic users/emails, and the transitional identity-selection contract — gated on every service account having migrated to a resource-API ServiceAccount and that legacy path's traffic having drained to zero (ADR-0001 §10), not merely on the /token route existing. Unlike Controller's auth.controllers[], which carried no production traffic and was removed unconditionally in the same change that shipped ControllerTrustPolicy (§1), the typed ServiceAccount table is in production use today and needs the same measure-then-drain-then-remove discipline as auth.allow_raw_external_tokens.
  • [~] Keep the platform-global maximum token TTL and add negative tests for audience, cap, target trust, mode-confusion, and name-recreation behavior. The maximum is server.auth_token_max_ttl_seconds for both token kinds, and cap, target-trust, mode-confusion, and name-recreation behavior are tested through the route; audience-mismatch coverage waits on the middleware-level test harness.

3. Subresource execution

  • Resolve ADR-0002's open interface questions and move it from Draft to Proposed before implementing the general registry seam.
  • Register generic status and finalizers mutation strategies once in the resource layer; individual resource handlers must not reimplement their field separation.
  • [~] Register token as a generated finite response with the two typed authentication outcomes from ADR-0001. Raw assertions are consumed before handler invocation. Both outcomes are served today on the two built-in identity kinds; moving that fixed registration onto the declared registry seam waits on ADR-0002.
  • Make discovery report each kind's supported subresources, verbs, media types, and execution shape.
  • Design Deployment logs as the first streaming product subresource, including source selection, retention, follow/tail behavior, backpressure, disconnect cancellation, limits, redaction, and audit metadata.
  • Defer proxy, exec, and upgraded connections until a concrete product use case justifies their larger trust boundary.

4. Typed-object migration

Ordering: the built-in registry enables data-plane migration; unified RBAC must land before user-facing routes flip to the generic API. Pagination/Watch and secret handling remain kind-specific prerequisites.

  • Implement resource families (ADR-0003): ResourceFamily, the family name pool, the unversioned family collection route, and printer columns. A family cannot be retrofitted onto kinds that already have instances, so this lands before the extension migration below.
  • Migrate extension kinds to external ResourceDefinition resources under the Extension family, preserving today's per-project extension name pool; secret-bearing extensions wait for encrypted fields.
  • Migrate Project (Organization child) and Environment (Project child) as built-ins. Authorization ownership is rise.dev/owner plus policy; lifecycle metadata.ownerReferences never grant access.
  • Migrate User, UserIdentity, Group, and GroupMembership, mapping the existing Rise Team concept to Group while preserving stable generated User names and exact SSO mappings.
  • Migrate ServiceAccount as an Organization child and trust mappings as ServiceAccountTrustPolicy children.
  • Migrate Controller as a root built-in and trust mappings as ControllerTrustPolicy children.
  • Migrate Deployment as a Project child after pagination and Watch; controllers update it through registered status and finalizers subresources.
  • Migrate env vars, custom domains, and project app users before dropping the remaining Project foreign-key fan-in.
  • Drop each typed table only after its resource-backed path has baked and compatibility reads are no longer needed.

5. External controllers and multi-org routing

  • Build an extension provisioner as the first external controller, against rise-resource-client with a Rise-issued Controller token and Watch. It goes first for blast radius, per ADR-0004 §7; it depends on resource families and the extension-kind migration (§4).
  • Build rise-k8s-controller on the same seam, using a Rise-issued Controller token and Watch rather than a raw controller JWT or typed-table polling. Second, once the seam has carried a lower-risk controller.
  • Store org-agnostic Controller identities separately from per-org selection/configuration. Organizations reference an available controller class through ordinary governed resource data; credentials stay in trust policy children or secret resources, not embedded config blobs.
  • Prove isolation with two controllers reconciling two Organizations into separate clusters/accounts, including controller reassignment and in-flight Deployment behavior.

6. Codebase decomposition

  • Extracted the deployment backends onto the rise-backend-core seam (DeploymentBackend, DeploymentStore, the provider and runtime-log traits): rise-backend-docker, rise-backend-kubernetes, and rise-backend-ecs, with the Traefik routing they share in rise-backend-traefik. Each crate owns its controller and its runtime-log backend, and reaches deployment state only through DeploymentStore (its one PgPool is the rise-runtime-sync leader lease); rise-deploy implements the store and composes the backends from its settings.
  • Complete remaining backend extraction work only where it supports the resource/controller migration above; avoid parallel abstractions that bypass the generic resource API or unified authorization engine.
  • Split ResourceStore into the remotable ResourceApi surface and the apiserver-internal one (ADR-0004 §3), and hold in-tree callers to the former. Only the handlers, GC worker, authorization engine, and composition root name the wide trait; the Docker reconciler, the Metacontroller webhook's Organization view, the Organization delete guard, and bootstrap moved to ResourceApi.
  • Extract rise-apiserver as its own binary and process (ADR-0004 §§1, 8) once that ADR's gates are met. The gates are §1 and §4 work, so this lands near the end of the typed-object migration rather than beside it.

Verification gates

  • Every PR: formatting, clippy with warnings denied, workspace tests, affected SQLX preparation, schema checks, and documentation build.
  • Unified RBAC complete: all non-deferred ADR-0001 conformance scenarios pass against pure policy tests, fake-store engine tests, and server/Postgres integration tests.
  • Resource API mature: an ordinary governed User can create, patch/apply, list, watch, and use subresources without operator-only paths.
  • Authentication converged: ordinary endpoints accept only Rise-issued, UID-bound principals; workload token exchange and delegated minting are tested through target /token; cap narrowing is end-to-end.
  • Migration complete: typed commands are resource-backed and typed-table writes have ceased before tables are removed.
  • Multi-controller complete: separate Rise-issued Controller identities reconcile separate orgs with no cross-org access or workload loss.