Skip to content

feat(auth): add discovery-only readers and workspace scopes - #4964

Open
TaylorMutch wants to merge 7 commits into
feat/4722-gateway-service-auth/TaylorMutchfrom
feat/4668-discovery-readers/TaylorMutch
Open

TaylorMutch wants to merge 7 commits into
feat/4722-gateway-service-auth/TaylorMutchfrom
feat/4668-discovery-readers/TaylorMutch

Conversation

@TaylorMutch

@TaylorMutch TaylorMutch commented Oct 27, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

Allow noninteractive discovery consumers to read routes for one workspace, a selected set, or all active workspaces using narrowly authorized certificate-bound identities.

Based on main at df6a799eb. Stacked on feat/4722-gateway-service-auth/TaylorMutch.

Related Issue

Closes #4668. Part of RFC 0017.

Changes

  • Scope discovery-only credentials to the separate openshell.v1.ServiceDiscovery service and apply discovery admission budgets to single, finite, and all-workspace selections.

  • Add administrator-managed discovery grants bound to trusted OU=discovery certificates without operator credentials or workspace membership.

  • Authorize only snapshot/watch RPCs; deny general resource APIs, mutations, credentials, and supervisor APIs. Discovery-only credentials do not satisfy gateway application authentication when enable_gateway_service_auth = true; that independent flag defaults to false, preserving legacy application routing.

  • Bound and validate workspace selection and aggregate snapshots, preserving existing user authorization and workspace lifecycle handling.

  • Reauthorize watches against grant changes and certificate expiry; document file reload, renewal, and revocation propagation.

Release Notes

Compatibility

discovery_grants_file explicitly enables discovery-only certificate classification. Without it, an existing OU=discovery certificate retains ordinary mTLS behavior. Once configured, missing, invalid, or revoked grants fail closed. The added workspace selector fields are additive protobuf fields; ordinary SDK request initialization and single-workspace calls remain compatible.

Testing

  • Canonical Helm service-auth configuration passed the full chart/runtime-parser suite and final combined-chart tests, generated Helm docs, and Markdown lint. Tests cover the runtime default plus explicit true/false in gatewayConfig."openshell.gateway".enable_gateway_service_auth.

  • Renamed the auth setting consistently across TOML, CLI, environment, Helm, tests, man page, and docs. Standalone auth-stage server tests (2,822 passed; 51 PostgreSQL-dependent tests skipped), combined-stack server/proxy tests, strict Clippy, full Helm runtime validation, generated docs, Markdown lint, and formatting passed. Default remains false; no live E2E was rerun for this configuration-only rename.

  • Rebased all five branches onto main df6a799eb, preserving the SPIFFE provider-token limiter and application-auth peer metadata. Branch ancestry, patch scope, and frozen Python/Go SDK checks passed.

  • Standalone URL PR: 2,801 server tests (50 PostgreSQL-dependent tests skipped), 650 core tests, 336 Kubernetes-driver tests, 300 supervisor tests, and 409 CLI library tests passed.

  • Combined auth/discovery-reader/proxy stack: 2,831 server tests (51 PostgreSQL-dependent tests skipped) and all nine proxy tests passed. Strict all-target Clippy passed for server, core, Kubernetes driver, supervisor, CLI, and proxy.

  • Full Helm suites passed for the URL/Helm follow-up, including rendered TOML, resource coherence, ownership, and scaling. The combined stack passed all 500 gateway-chart unit tests. Generated Helm docs, Markdown/MDX lint, Rust formatting, and whitespace checks passed.

  • Fresh live k3d shared/push/graceful E2E passed on the rebased URL/Helm stage with matching locally built images: Pod-IP ingress without app Services, HTTP/WebSockets, Host/SNI, NetworkPolicy, withdrawal/re-exposure, takeover preserving workload identity/process/memory, and listener-disabled gateway fallback using enable_gateway_service_routing: true. The isolated release and namespace were removed.

Dedicated, poll, abrupt-loss, and external-ingress scenarios were not rerun for these review fixes. Current-head GitHub CI is pending.

Qualification limits

Live Kubernetes qualification covers dedicated/shared supervisors, graceful shared-owner replacement, gateway outage, and policy isolation. Hashed URL/public-port behavior is covered by unit tests. Whole-node failure, real network partitions, metric-driven HPA, sustained production load, external ingress/DNS automation, and published release artifacts remain unqualified. Installation-status presentation (#4670) remains separate work. The example Kubernetes HTTPRoute controller remains a separate compatibility POC.

Checklist

  • Follows Conventional Commits
  • Commits are signed off (DCO)
  • Relevant implementation, configuration, and API documentation updated

PR dependency order: #4956 → #4963 → #4964 → #4957.

@copy-pr-bot

copy-pr-bot Bot commented Oct 27, 2026

Copy link
Copy Markdown

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

@github-actions

Copy link
Copy Markdown

@TaylorMutch
TaylorMutch added this pull request to stack #4965 October 27, 2026 05:46
@TaylorMutch
TaylorMutch removed this pull request from stack #4965 October 27, 2026 05:47
@TaylorMutch
TaylorMutch force-pushed the feat/4722-gateway-service-auth/TaylorMutch branch from 18b394a to ce2a99e Compare October 27, 2026 06:24
@TaylorMutch
TaylorMutch force-pushed the feat/4668-discovery-readers/TaylorMutch branch from 6d1fb23 to 9b730e6 Compare October 27, 2026 06:24
@TaylorMutch
TaylorMutch force-pushed the feat/4722-gateway-service-auth/TaylorMutch branch from ce2a99e to de94456 Compare October 27, 2026 06:25
@TaylorMutch
TaylorMutch force-pushed the feat/4668-discovery-readers/TaylorMutch branch 2 times, most recently from 8fef4ac to 8d568c1 Compare October 27, 2026 06:46
@TaylorMutch
TaylorMutch force-pushed the feat/4722-gateway-service-auth/TaylorMutch branch from de94456 to 3b08d4c Compare October 27, 2026 06:46
@TaylorMutch
TaylorMutch force-pushed the feat/4668-discovery-readers/TaylorMutch branch from 8d568c1 to de13e31 Compare October 27, 2026 21:06
@TaylorMutch
TaylorMutch force-pushed the feat/4722-gateway-service-auth/TaylorMutch branch 2 times, most recently from c35e581 to caacd27 Compare October 28, 2026 17:05
@TaylorMutch
TaylorMutch force-pushed the feat/4668-discovery-readers/TaylorMutch branch from de13e31 to 05974d6 Compare October 28, 2026 17:05
@TaylorMutch
TaylorMutch force-pushed the feat/4722-gateway-service-auth/TaylorMutch branch from caacd27 to 6e5245e Compare October 28, 2026 22:52
@TaylorMutch
TaylorMutch force-pushed the feat/4668-discovery-readers/TaylorMutch branch from 05974d6 to 2441c08 Compare October 28, 2026 22:52
@TaylorMutch
TaylorMutch force-pushed the feat/4722-gateway-service-auth/TaylorMutch branch from 6e5245e to c37b455 Compare October 29, 2026 01:16
@TaylorMutch
TaylorMutch force-pushed the feat/4668-discovery-readers/TaylorMutch branch from 2441c08 to 1c8e5a4 Compare October 29, 2026 01:16
@TaylorMutch
TaylorMutch force-pushed the feat/4722-gateway-service-auth/TaylorMutch branch from c37b455 to dd566cd Compare October 30, 2026 17:57
@TaylorMutch
TaylorMutch force-pushed the feat/4668-discovery-readers/TaylorMutch branch 2 times, most recently from 5ec14a7 to d4a1630 Compare October 30, 2026 18:13
@TaylorMutch
TaylorMutch force-pushed the feat/4722-gateway-service-auth/TaylorMutch branch from 00061b6 to acc3754 Compare October 30, 2026 21:11
@TaylorMutch
TaylorMutch force-pushed the feat/4668-discovery-readers/TaylorMutch branch from d4a1630 to a3be433 Compare October 30, 2026 21:11
@TaylorMutch
TaylorMutch force-pushed the feat/4722-gateway-service-auth/TaylorMutch branch 2 times, most recently from 7224961 to 5f66489 Compare November 13, 2026 21:15
@TaylorMutch
TaylorMutch force-pushed the feat/4668-discovery-readers/TaylorMutch branch from 8df72ee to a18cc74 Compare November 13, 2026 21:15
@purp purp added area:enterprise Authentication, multitenancy, gateway interceptors, FIPS, and enterprise requirements. topic:api Public APIs, gRPC/protobuf, SDK interfaces, versioning, compatibility, and API design standards. topic:authnz Authentication, authorization, identity, sessions, credential protection, and policy integrity. topic:documentation Architecture docs, READMEs, project website updates, and automated documentation generation. topic:security Vulnerability management, security analysis/auditing, bypass detection, and abuse prevention. labels Nov 15, 2026
@TaylorMutch
TaylorMutch marked this pull request as ready for review November 16, 2026 19:22
@github-actions

Copy link
Copy Markdown

Compatibility review (advisory)

New or updated breaking changes; see the full report for all findings.

1. rust-sdk — No explicit risk acceptance found

GetServiceRouteSnapshotRequest and WatchServiceRoutesRequest previously allowed exhaustive literals containing only workspace_scope; both now require a workspaces field.

  • Impact: Downstream Rust callers and mocks constructing these public raw::proto messages fail with missing-field errors, although Default-based construction and generated server-trait signatures remain compatible.
  • Action: Preserve the existing request structs in this patch by exposing multi-workspace requests separately, or defer the break to a minor release with notice and guidance to add workspaces: Vec::new() or ..Default::default().
  • PR: feat(auth): add discovery-only readers and workspace scopes #4964

2. typescript-sdk — No explicit risk acceptance found

Complete objects typed as the exported GetServiceRouteSnapshotRequest or WatchServiceRoutesRequest previously needed no workspaces property but now require workspaces: string[].

  • Impact: Consumers constructing complete typed discovery requests or mock messages stop type-checking, while schema-based initialization and ordinary partial RPC arguments remain compatible.
  • Action: Preserve the existing exported message shapes in this patch, or defer their expansion to a minor release with notice and guidance to add workspaces: [] or use create(RequestSchema, init).
  • PR: feat(auth): add discovery-only readers and workspace scopes #4964

3. api-behavior — No explicit risk acceptance found

A trusted OU=discovery certificate previously authenticated as an ordinary mTLS user but now becomes a discovery-only principal even when discovery_grants_file is unset.

  • Impact: Existing CLI and SDK consumers using such certificates receive PERMISSION_DENIED for ordinary authenticated RPCs, and presenting a valid bearer credential alongside the certificate no longer restores access.
  • Action: Make discovery-only certificate classification explicitly opt-in while preserving existing mTLS identities in v0.1.9, and reserve any unconditional OU restriction for a minor release with certificate-reissuance guidance.
  • PR: feat(auth): add discovery-only readers and workspace scopes #4964
Review details
  • Execution: complete
  • Candidate: PR #4964 (9f7482585aeaaac43a6efc96a2d3d01411f86986)
  • Baseline: 5f664899ec7e4475e15fa71ec50e3b8c01a141d2 (5f664899ec7e4475e15fa71ec50e3b8c01a141d2)
  • Reviewed: rust-sdk, python-sdk, typescript-sdk, api-behavior, cli, configuration, policy, helm, state

Advisory review; publication gates are unchanged.

Branch check run

@TaylorMutch
TaylorMutch force-pushed the feat/4668-discovery-readers/TaylorMutch branch from a18cc74 to df8f36d Compare November 16, 2026 19:55
@TaylorMutch
TaylorMutch force-pushed the feat/4722-gateway-service-auth/TaylorMutch branch 2 times, most recently from 2bc4518 to f79878c Compare November 16, 2026 21:48
@TaylorMutch
TaylorMutch force-pushed the feat/4668-discovery-readers/TaylorMutch branch 2 times, most recently from 5a248b8 to 0baec0a Compare November 16, 2026 22:27
@TaylorMutch
TaylorMutch force-pushed the feat/4722-gateway-service-auth/TaylorMutch branch 2 times, most recently from 0b04cc3 to c0123e1 Compare November 17, 2026 00:48
@TaylorMutch
TaylorMutch force-pushed the feat/4668-discovery-readers/TaylorMutch branch 2 times, most recently from 78300dd to d70a49b Compare November 17, 2026 23:14
@TaylorMutch

Copy link
Copy Markdown
Collaborator Author

/ok to test 36a4c97

@TaylorMutch

Copy link
Copy Markdown
Collaborator Author

/ok to test fdccee0

@TaylorMutch

Copy link
Copy Markdown
Collaborator Author

/ok to test fe3b0bb

Implement discovery-only certificate grants, bounded single/set/all workspace views, and live grant and certificate expiry checks. Preserve existing user authorization and reject discovery credentials on other APIs and application requests.

Closes #4668

Signed-off-by: Taylor Mutch <taylormutch@gmail.com>
Signed-off-by: Taylor Mutch <taylormutch@gmail.com>
Signed-off-by: Taylor Mutch <taylormutch@gmail.com>
Signed-off-by: Taylor Mutch <taylormutch@gmail.com>
Signed-off-by: Taylor Mutch <taylormutch@gmail.com>
Signed-off-by: Taylor Mutch <taylormutch@gmail.com>
Signed-off-by: Taylor Mutch <taylormutch@gmail.com>
@TaylorMutch

Copy link
Copy Markdown
Collaborator Author

/ok to test 0309cf2

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area:enterprise Authentication, multitenancy, gateway interceptors, FIPS, and enterprise requirements. topic:api Public APIs, gRPC/protobuf, SDK interfaces, versioning, compatibility, and API design standards. topic:authnz Authentication, authorization, identity, sessions, credential protection, and policy integrity. topic:documentation Architecture docs, READMEs, project website updates, and automated documentation generation. topic:security Vulnerability management, security analysis/auditing, bypass detection, and abuse prevention.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants