docs(adr): ADR-0011 — owner-issued grant for remoteControl.tls credentials

[thc1006]

Proposed — no CRD, controller or flag ships here. This records a design and corrects part of an earlier one.

Why now

Three gaps remain on main after #219, #251/#300, #296, #297, #309 and #313. I checked each against main @ 93c47f3 rather than assuming. They look separate but share one shape: the Secret's owner cannot express, revocably, what their credential may be used for.

Gap	State on main
Authorization is not revocable	#309's ValidatingAdmissionPolicy is evaluated at admission only — ADR-0009's own amendment says stored objects are not re-validated. Withdrawing an author's RBAC does not re-evaluate the CRs they already created.
A credential is not bound to a destination	--remote-control-allowed-endpoint-hosts is admin-global. Grepped the tree: zero per-Secret endpoint binding. Any labelled Secret can be paired with any allow-listed endpoint.
Revocation is invisible	Secrets are get-only by design (an informer needs cluster-wide list/watch, rejected in #298). Withdrawn consent is unseen until the next real push — measured at 166 s on a live 1.36.3 cluster, driven by the referenced SatelliteEphemeris's heartbeat, not by any per-cell retry.

A failing push is already fine — RemoteEndpointRejected, RemoteControlCredentialUnavailable and RemoteControlEndpointNotAllowed all self-heal on the 5-minute poll. The gap is the healthy cell, where the dedup early-return sits ahead of resolveRemoteControlTLS, so nothing re-reads the credential at all.

The design

RemoteControlCredentialGrant, namespaced, created by the Secret's owner in the Secret's namespace: secretRef, allowedConfigs (name + optional uid), allowedEndpoints, allowedModes.

Being an object rather than a check is what buys all three properties at once — it can be deleted (revocable), it can be watched and field-indexed so revocation enqueues the affected NTNCellConfigs instead of waiting on an unrelated heartbeat, and it has somewhere to put an endpoint and a mode.

Enforcement is admin-gated and default-off behind --require-credential-grant. The tempting "enforce whenever a grant exists for that Secret" variant is rejected in the ADR: an attacker simply would not create one, so the feature would do nothing precisely when it matters.

It corrects ADR-0009, and says which part

ADR-0009 recommended SAR-at-admission over a grant CRD, calling the latter "heavier than the problem warrants". That was sound for the requirement as stated there — deciding who may create the reference. It does not survive two requirements that were not on the table:

• Revocability — a SAR is a point-in-time check on a write. ADR-0009's amendment records this limitation itself.
• Endpoint binding — a SAR answers "may this principal read this Secret?" and can never express "…and only to reach that gNB".

So a grant is not a heavier way to do the same job; it does three jobs, which is what changes the calculus. ADR-0009 now carries a forward pointer in its header so nobody lands on it and acts on the superseded bullet.

#309 is explicitly not replaced. It stays the cheap default tier — no CRD, no controller, one declarative policy — and stops the confused deputy at write time. The grant is the opt-in stronger tier for multi-tenant namespaces. #300's allow-list remains the admin's outer bound on destinations.

What the ADR refuses to claim

• It does not close track: remoteControl.tls credential rotation/revocation is bounded by the ~3m epoch cadence (deferred from #219) #298. Rotating a Secret's contents touches no grant and fires no watch, so that path keeps the ~3-minute bound. The optional credentialRevision field is an opt-in escape hatch that depends on the owner remembering to bump it — not a Secret watch, and the ADR says so.
• A patch-capable principal in the Secret's namespace can still write a grant they should not; namespace RBAC remains the ceiling.
• A grant governs what the operator will present, not what the gNB accepts.

Cost, stated up front

A fifth CRD means make manifests bundle nephio-sync across four copies plus docs/api-reference.md, chart RBAC and samples. The controller gains list/watch on the new CRD but not on Secrets — that is the point: consent becomes watchable without widening Secret access, which is the trade #298 rejected an informer for.

Follow-up, deliberately not bundled

Automated E2E for the credentialed push. The chain is verified manually and shipped as a sample (#326), but no test in test/e2e/ exercises wss/mTLS, so a regression would ship green. Tracked separately — it is independent of this design decision.

[thc1006]

Superseded by #337 (authoritative consolidated ADR set, now on main). The owner-issued credential grant lives at docs/adr/0011-remote-control-credential-grant.md, with the layered-authorization context consolidated in 0009-remote-control-credential-boundary.md. Closing in favour of that.