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.
- ADR-0001: Unified Permission Model is the target authorization and identity model.
- ADR-0002: Generic Resource Subresource Execution Model
is Draft and defines the intended execution seam for
status,finalizers,token, and future generated or streaming subresources. - ADR-0003: Resource Families groups kinds that share a name pool and list as a unit; it gates the extension-kind migration in §4.
- ADR-0004: Control-Plane Process Topology makes the resource API its own process with every other component a client, and sets the gates that ordering must satisfy. It governs the sequencing in §5 and §6.
- Where shipped compatibility behavior differs from an ADR, it is transitional; new work converges on the ADR rather than extending the old shape.
- 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.
- Move the dep-light
ResourceStorecontract and canonicalSubjectId, dynamic-labelSubjectRef, group-qualifiedResourceKind, andScopetypes intorise-resource-api; keep SQLX and Postgres adapters inrise-resource-store-postgres. - Implement policy types and validation for
Role,RoleBinding,PlatformRole, andPlatformRoleBinding: structuredroleRef, one subject per binding, normalized PascalCasesubjectMembership: Any | ResourceOrganizationon platform bindings (omission becomesAny; 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
UserandController; Organization-ownedGroupandServiceAccount; and fixed-parentUserIdentity,GroupMembership,ControllerTrustPolicy, andServiceAccountTrustPolicy. User and UserIdentity carry platform-managedactivestate, 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.ownerReferencesto 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
SubjectRefvalues for dynamic ownership, tiered platform/org Deny filtering, admin/operator classification, platform ceilings, and the centralized authorization choke point replacingrequire_operator. The choke point is live on the generic resource API, with per-item list filtering, the allowlisted list-only projection, andmetadata.effectiveLabelson every response. Controllers are ordinarycontroller:<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/tokensubresource; theResourceDefinition.allowedStatusControllerIdsallowlist 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: theGET /api/v1/resources/policy-auditlisting and the read-onlyexplainsubresource, both filtered per finding on the caller's ownlist/getgrants. Diagnostics never reject a write: a create or update of aRoleBinding/PlatformRoleBindingruns the same detectors against the row just written and surfaces any finding as an HTTPWarningheader, never as a failure. - Add request-local
AuthorizationSnapshotmemoization 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
roleRefon 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 globalauthorization_epochkeyed 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 theSERIALIZABLEtransaction 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-adminand platformresource-ownerRoles, plus an operator-editable globalPlatformRole/org-adminbaseline. Organization creation atomically creates an exact org-root, scope-onlyRoleBindingfrom 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 viabootstrap.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 Nmarker on each covering test is enforced bymise run adr:conformance:check; scenario 10's operator-selector half remains deferred until theoperatorIdentitiesitem 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.
- Reject
createbelow 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 thestatus/finalizerssubresources 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
statusandfinalizers; 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
ResourceKindvocabulary and registered subresources. - Add a resumable Watch API with explicit backpressure, connection limits, and observability.
- Build
rise-resource-clientin 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
ResourceDefinitionschema-evolution behavior. - Close built-in
(group, kind)shadowing and finish audit coverage for RBAC, Patch/Apply, discovery, and subresource execution.
- Extracted JWT verification/signing into
rise-backend-auth. - Added the transitional
POST /api/v1/auth/tokenexchange 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.
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 |
- Issue User sessions with canonical
subplus immutablerise_uidafter exact live, activeUserIdentity (issuer, subject)and active parent User resolution. Sessions carrytyp: rise-session+jwtand are re-resolved on every request. - Move workload token exchange to each ServiceAccount or Controller
/tokensubresource, introduced additively per kind: a resource-API-backed identity gains its/tokenroute 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 onrise.dev/ServiceAccountandrise.dev/Controller; the minted identity token (RS256,typ: rise-identity+jwt, canonicalsubplusrise_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 requestedaudienceis verifiable by that party against Rise's JWKS. - Support delegated issuance on the same
/tokenroute 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_detailsclaim withtype: rise.dev/rbac, one qualifiedscopeper entry, and multiple entries whose permissions union. Reject empty permission axes, carry the parsed cap onAuthenticatedPrincipal, and enforce live RBAC intersected with that cap on every primary and secondary decision. - Add bounded nested
actattribution. 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_tokensabove. - Retire the typed
service_accountstable, its synthetic users/emails, and the transitional identity-selection contract — gated on every service account having migrated to a resource-APIServiceAccountand that legacy path's traffic having drained to zero (ADR-0001 §10), not merely on the/tokenroute existing. Unlike Controller'sauth.controllers[], which carried no production traffic and was removed unconditionally in the same change that shippedControllerTrustPolicy(§1), the typed ServiceAccount table is in production use today and needs the same measure-then-drain-then-remove discipline asauth.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_secondsfor 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.
- Resolve ADR-0002's open interface questions and move it from Draft to Proposed before implementing the general registry seam.
- Register generic
statusandfinalizersmutation strategies once in the resource layer; individual resource handlers must not reimplement their field separation. - [~] Register
tokenas 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
logsas 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.
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
ResourceDefinitionresources under theExtensionfamily, preserving today's per-project extension name pool; secret-bearing extensions wait for encrypted fields. - Migrate
Project(Organization child) andEnvironment(Project child) as built-ins. Authorization ownership isrise.dev/ownerplus policy; lifecyclemetadata.ownerReferencesnever grant access. - Migrate
User,UserIdentity,Group, andGroupMembership, mapping the existing Rise Team concept toGroupwhile preserving stable generated User names and exact SSO mappings. - Migrate
ServiceAccountas an Organization child and trust mappings asServiceAccountTrustPolicychildren. - Migrate
Controlleras a root built-in and trust mappings asControllerTrustPolicychildren. - Migrate
Deploymentas a Project child after pagination and Watch; controllers update it through registeredstatusandfinalizerssubresources. - 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.
- Build an extension provisioner as the first external controller,
against
rise-resource-clientwith 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-controlleron 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.
- Extracted the deployment backends onto the
rise-backend-coreseam (DeploymentBackend,DeploymentStore, the provider and runtime-log traits):rise-backend-docker,rise-backend-kubernetes, andrise-backend-ecs, with the Traefik routing they share inrise-backend-traefik. Each crate owns its controller and its runtime-log backend, and reaches deployment state only throughDeploymentStore(its onePgPoolis therise-runtime-syncleader lease);rise-deployimplements 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
ResourceStoreinto the remotableResourceApisurface 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 toResourceApi. - Extract
rise-apiserveras 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.
- 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.