Skip to content

refactor(hubble): unify auth and permission modes - #758

Open
imbajin wants to merge 58 commits into
apache:masterfrom
hugegraph:cx/hubble-auth-redesign
Open

refactor(hubble): unify auth and permission modes#758
imbajin wants to merge 58 commits into
apache:masterfrom
hugegraph:cx/hubble-auth-redesign

Conversation

@imbajin

@imbajin imbajin commented Aug 16, 2026

Copy link
Copy Markdown
Member

Closeout TODO

  • Unify auth/non-auth client boundaries and keep only four presets: global administrator, GraphSpace read-only, GraphSpace read-write, and GraphSpace administrator.
  • Separate account IDs from usernames, restore membership before GraphSpace grants, compensate response-lost writes, and remove new accounts after any authorization failure.
  • Keep new-account work proportional to requested GraphSpaces; reserve full permission reconciliation for updates.
  • Keep anonymous graph access separate from auth management, including graphs and GraphSpaces named auth.
  • Pass the full 1.8 distributed-auth acceptance path: 1 Server + 3 PD + 3 Store + 1 Hubble, three GraphSpaces, at least two graphs per space, three representative users, and built-in admin.
  • Complete Chrome allow/deny, member management, global administration, Operations, account-switch, and first-write paths.
  • Complete the 1.7 compatibility paths with legacy profile reads, explicit read-only profile capability, password access, and fail-closed account management.
  • Keep the public bootstrap config limited to mode flags, and show upgrade
    guidance when a legacy service does not provide an individual Operations metric.
  • Filter authenticated GraphSpace discovery by current access, reject protected
    GraphSpaces through anonymous graph routes, and keep legacy membership visible.
  • Validate URI and request-body GraphSpace scopes before Loader, upload,
    Vermeer, or graph controller work; keep non-auth resource errors on-page.
  • Bind clone targets, global Ingest tasks, Gremlin collections, and
    execution-history IDs to their owning GraphSpace/graph scope.
  • Keep read-only presets read-only across Loader/Ingest/query mutations,
    and apply scoped predicates in the final database update/delete operation.
  • Use the shared 120-column threshold in Toolchain/Hubble and compact only current-PR code without reformatting legacy sources.
  • Resolve all current review threads on #27 and #758.
  • Keep speculative TinkerPop 3.7 merge-step work outside the current 3.5.1
    Server scope and resolve all threads on #3159.
  • Keep Codecov explicitly deferred without weakening its gate or adding
    coverage-only code. The new 02cbe0e4 current-head checks are running on Support customized date format #27/refactor(hubble): unify auth and permission modes #758; the existing correctness/design/security reviewers are Clean.
  • Complete the 1.5.0 standalone non-auth read, write, and Graph
    visualization smoke; remove its task-only runtime resources.
  • Remove fixed credentials, temporary users/data, and remaining task-only
    resources; preserve the shared Maven cache.

1.5–1.8 compatibility/usability

  • 1.5 · standalone · non-auth — anonymous schema/vertex write, separate
    read, and one-node Graph visualization passed; resources cleaned. Auth, PD,
    Operations, and distributed combinations are N/A for this acceptance scope.
  • 1.7 · standalone · non-auth — graph read and Gremlin passed; resources cleaned.
  • 1.7 · standalone · auth — admin/ordinary login and legacy profile capability passed; resources cleaned.
  • 1.7 · distributed · non-auth — 1+1+1 topology and Hubble flows passed; resources cleaned.
  • 1.7 · distributed · auth — 1+1+1 login/profile/account boundaries passed; resources cleaned.
  • 1.8 · standalone · non-auth — core flow and latest anonymous auth-named graph delta passed; resources cleaned.
  • 1.8 · standalone · auth — account and profile flows passed; resources cleaned.
  • 1.8 · distributed · non-auth — topology, Operations, and anonymous template lifecycle passed; resources cleaned.
  • 1.8 · distributed · auth — full 1+3+3 permission and usability scope passed; resources cleaned.

Non-auth compatibility snapshots

1.5.0 · standalone · non-auth 1.8/current · standalone · non-auth
Anonymous schema/vertex write followed by a separate read; Graph view renders one node. Anonymous graph query renders two vertices and one edge.
1.5 standalone non-auth Graph visualization 1.8 standalone non-auth Graph visualization

Before → After

flowchart LR
    B["Before<br/>auth and non-auth paths diverged<br/>permission checks crossed client boundaries<br/>cluster state was hard to interpret"]
    A["After<br/>session client vs anonymous client<br/>four explicit permission presets<br/>version differences at Client compatibility boundary<br/>Operations exposes health, freshness, capacity, and recovery"]
    B --> A
Loading
Area Before After
Connection Auth mode and anonymous mode followed different implicit paths Auth uses the session client; non-auth uses a real anonymous client
Permission model GraphSpace/member/graph capabilities were difficult to reason about together Four presets define scope and write boundaries; custom permissions are out of scope
Compatibility Version conditions could leak into pages and controllers Compatibility stays in the Client layer; 1.8 uses API 0.72 and the matching Server contract
Operations Cluster state required implementation-specific discovery behavior Operations shows node availability, freshness, size/capacity, Store status, and recovery guidance

Compatibility scope

The complete data and permission path is intentionally limited to 1.8 distributed auth. Version 1.7 proves the thinner compatibility boundary, including the API 0.71 profile and membership behavior. Version 1.5 is limited to standalone non-auth core graph access; unsupported combinations are marked N/A instead of becoming placeholder TODOs.

Current CI gate

Current Toolchain head is 02cbe0e4. The final permission delta validates
direct URI/body scopes and indirect owner scopes for clone, Ingest, Loader,
upload, Vermeer, Gremlin collections, and execution history. Non-auth
resource-level 401 errors remain on-page instead of redirecting to a disabled
login route. Read-only users cannot mutate Loader/Ingest/query state; visible
Ingest filtering and pagination run in the database, and final writes include
scope predicates. The exact anonymous scoped auth-state endpoint remains
readable while nested auth-management routes stay protected. Password-only
updates omit unchanged permission fields; true combined password/permission
changes are rejected before any write. The final legacy fail-closed delta passes 77/77 focused backend tests with\nCheckstyle 0. The switcher also clears a revoked PD GraphSpace when the masked\ngraph-list response is 404; its focused frontend suite passes 20/20 and ESLint\nis clean; the preceding Account UI tests pass 19/19 with ESLint and i18n
clean.
Fork #27 and Apache #758 point to the same current head and have no unresolved\nthread; non-Codecov current-head checks are running on both PRs. Codecov project remains failed and explicitly deferred rather than counted as
passing. The existing correctness/design/security
reviewers are Clean on the final Toolchain delta. Server #3159 removed speculative TinkerPop 3.7 merge-step work. Product
source still matches the validated 28641f54; only the dependency-review
Action upgrade follows it, and current-head CI is running.

- add a conservative 1.5/1.7 capability profile\n- document auth and PD connection boundaries\n- define Chrome evidence and compatibility support matrix
- add explicit auth.enabled Hubble option and config exposure\n- bypass session enforcement and use unauthenticated clients in anonymous mode\n- return a stable anonymous authorization context\n- let frontend route guards honor the configured mode
- route GraphSpace support through ServerCompatibility\n- keep legacy versions on conservative capability profile\n- avoid version literals in client flow
- bootstrap auth configuration before route rendering\n- hide anonymous account controls and low-level GS objects\n- map account forms through four semantic permission presets\n- retain focused legacy capability and Chrome evidence boundaries
- centralize 1.5/1.7 capability fallbacks\n- enforce preset-only GraphSpace administration\n- hide anonymous account controls and preserve legacy access\n- add Chrome compatibility captures and raise line limit to 120
@dosubot dosubot Bot added size:XL This PR changes 500-999 lines, ignoring generated files. enhancement New feature or request hubble hugegraph-hubble labels Aug 16, 2026
@github-actions github-actions Bot added the client hugegraph-client label Aug 16, 2026
- keep member reads available to GraphSpace managers\n- restrict low-level member mutations to authorization admins
@codecov

codecov Bot commented Aug 16, 2026

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 62.93980% with 474 lines in your changes missing coverage. Please review.
✅ Project coverage is 45.36%. Comparing base (b066b80) to head (83c2147).
⚠️ Report is 218 commits behind head on master.

Files with missing lines Patch % Lines
...org/apache/hugegraph/service/auth/UserService.java 61.15% 67 Missing and 27 partials ⚠️
.../hugegraph/controller/ingest/IngestController.java 31.34% 39 Missing and 7 partials ⚠️
.../hugegraph/service/auth/GraphSpaceUserService.java 81.66% 18 Missing and 26 partials ⚠️
...rg/apache/hugegraph/controller/BaseController.java 59.09% 18 Missing and 9 partials ⚠️
...che/hugegraph/service/space/GraphSpaceService.java 77.86% 14 Missing and 13 partials ⚠️
...graph/controller/algorithm/OltpAlgoController.java 0.00% 26 Missing ⚠️
...raph/controller/auth/GraphSpaceUserController.java 41.66% 17 Missing and 4 partials ⚠️
...ache/hugegraph/service/load/JobManagerService.java 0.00% 18 Missing ⚠️
...gegraph/controller/space/GraphSpaceController.java 37.50% 9 Missing and 6 partials ⚠️
...hugegraph/service/query/ExecuteHistoryService.java 0.00% 15 Missing ⚠️
... and 28 more
Additional details and impacted files
@@              Coverage Diff              @@
##             master     #758       +/-   ##
=============================================
- Coverage     62.49%   45.36%   -17.14%     
- Complexity     1903     4254     +2351     
=============================================
  Files           262      601      +339     
  Lines          9541    28872    +19331     
  Branches        886     3348     +2462     
=============================================
+ Hits           5963    13097     +7134     
- Misses         3190    14501    +11311     
- Partials        388     1274      +886     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

- match CI unit-test coverage and authorization contracts\n- guard anonymous status and legacy admin-space updates\n- preserve mixed member roles and anonymous statistics\n- refresh 1.8 Chrome evidence and compatibility documentation
- show actionable account and graphspace errors\n- make account nickname optional and move password field\n- hide unsupported node metrics and normalize PD role labels\n- keep Java formatting within the 120-column rule
- proxy local API calls to the running Hubble instance\n- keep the target configurable through HUBBLE_API_TARGET\n- preserve relative API paths for production builds
@imbajin
imbajin force-pushed the cx/hubble-auth-redesign branch from 018b53e to f31977a Compare August 16, 2026 09:22

@imbajin imbajin left a comment

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Blocking: yes. Summary: No additional actionable source-level finding was confirmed, but this PR is not approvable until the required review evidence and failing latest-head checks are resolved. Evidence: targeted Hubble authorization tests 72/72, frontend auth/route suites 90/90, and ServerCompatibilityTest 2/2; failed checks: hubble-ci (11, 3.11), codecov/patch, codecov/project.

- derive modern permission support from Server API 0.72
- expose source-owned size and capacity facts with recovery guidance
- preserve specific account errors and gate legacy permission flows
- pin modern CI to the matching Server API contract
- cover compatibility, freshness, permissions, and large metrics
- add one strict environment override at the config boundary
- preserve file configuration when the override is absent
- reject invalid deployment values during startup
- cover override behavior in the Hubble unit suite
- document container and orchestrator usage
- expose read-only Operations capabilities in non-auth mode
- follow the authoritative PD REST leader within configured peers
- retain strict origin and DNS validation for leader requests
- cover anonymous access and trusted leader fallback
@dosubot dosubot Bot added size:L This PR changes 100-499 lines, ignoring generated files. and removed size:XL This PR changes 500-999 lines, ignoring generated files. labels Aug 17, 2026
- create ordinary legacy accounts without implicit elevation
- preserve mixed GraphSpace grants during profile edits
- use GraphSpace-wide observer roles with capability guidance
- narrow bootstrap auth bypass and cover proxy precedence
- use GraphSpace-wide observer self-permission checks
- cover permission preset application and cleanup paths
- exercise modern and legacy client user lookup branches
- raise executable patch coverage above the required gate
- disable the PD-only cluster overview action in non-PD mode
- keep standalone node inspection available through its own capability
- remove stale compatibility screenshots from older candidate heads
@dosubot dosubot Bot added size:XL This PR changes 500-999 lines, ignoring generated files. and removed size:L This PR changes 100-499 lines, ignoring generated files. labels Aug 17, 2026
- keep the legacy analyst self-permission check
- gate only the newer observer role lookup
- cover profile and GraphSpace list visibility
imbajin added 28 commits August 18, 2026 12:16
- map every supported PD cluster state to a stable health level
- preserve source freshness and per-node health as separate signals
- cover not-ready topology and near-match fallback behavior
- align EditorConfig, Prettier, and contributor guidance
- compact only current PR code within the new limit
- preserve readable chains and existing behavior
- require owner or GraphSpace manager for template mutations
- preserve anonymous-mode template operations
- cover owner manager denial and non-auth paths
- enrich only the requested GraphSpace page
- load all permission options through bounded pagination
- cover totals, hard limits, and authorization branches
- replace the constant pagination loop with explicit completion state
- align boolean and ternary wrapping with frontend lint rules
- preserve the tested pagination and hard-limit behavior
- suppress old route restoration throughout logout transitions
- clear inaccessible GraphSpace context without guessing a fallback
- cover HTTP and business 401 account-switch recovery paths
- hide protected GraphSpaces from anonymous endpoints
- resolve current users from verified token identity
- share bounded pagination across account permission views
- map stale identity context to unauthorized
- map observed missing-space 400 responses to anonymous 404
- preserve propagation for unrelated upstream failures
- align anonymous detail and auth tests with runtime behavior
- require a GraphSpace for every scoped permission preset
- validate preset and superadmin consistency before mutations
- preserve profile-only edits without changing account permissions
- reject malformed or mixed permission payloads
- use legacy GraphSpace membership checks without default-role APIs
- derive fallback identity only from verified legacy tokens
- expose read-only profile and password capabilities explicitly
- keep modern profile and default-role behavior unchanged
- roll back new accounts when scoped permission setup fails
- avoid reconciling unrelated GraphSpaces during account creation
- match anonymous auth-management routes by path structure
- cover account cleanup and auth-named graph regressions
- snapshot GraphSpace grants before multi-space reconciliation
- restore earlier spaces when a later permission mutation fails
- roll back profile and super-admin changes with the same request
- cover cross-space and account-level compensation
- use usernames for manager and default-role operations
- keep account IDs for user and role-assignment APIs
- compensate every post-create authorization failure
- restore membership before GraphSpace grants
- compact current-PR Java signatures and calls
- align affected backend test formatting
- keep frontend expectation wrapping within 120 columns
- expose only authentication and deployment-mode flags
- avoid reading the standalone backend URL for public config
- cover the public bootstrap response with a focused test
- keep unsupported metric groups locally degraded
- show upgrade guidance from the availability badge
- cover the tooltip and bilingual copy
- show 1.5 standalone anonymous read/write visualization
- show current standalone anonymous vertex and edge rendering
- keep the two durable PR assets under Hubble docs
- validate anonymous graph clients against public spaces
- filter GraphSpace discovery by current user access
- preserve legacy membership visibility without preset inference
- reject anonymous authorization management
- validate URI and body GraphSpace scopes before controller work
- cover loader metadata and uploads through the shared interceptor
- keep non-auth resource failures local instead of redirecting to login
- reuse request-scoped validation to avoid duplicate access checks
- validate graph clone targets from request bodies
- filter global Ingest task views by visible GraphSpaces
- authorize task and job mutations through their owning scope
- preserve GraphSpace collection routes in interceptor parsing
- bind Gremlin collection lookups to GraphSpace and graph
- prevent collection updates from moving records across scopes
- bind execution-history reads and deletes to the active graph
- return a stable not-found response for cross-scope IDs
- require GraphSpace write access for Loader and query mutations
- authorize global Ingest changes through their owning GraphSpace
- apply GraphSpace and graph predicates to final update/delete SQL
- push visible Ingest filtering and pagination into database queries
- allow anonymous reads of scoped auth status\n- keep nested GraphSpace auth management protected\n- reject combined password and permission mutations\n- omit unchanged permissions from password updates
- keep legacy PD account creation and profile edits non-elevated
- reject unsupported preset, GraphSpace admin, and super-admin changes before writes
- preserve standalone and modern permission behavior
- cover legacy fail-closed boundaries with focused tests
- treat masked 404 responses as inaccessible only for PD graph lists
- clear stale local graph context after GraphSpace access is revoked
- preserve retry behavior for GraphSpace lists and non-PD graph lists
- cover the masked missing GraphSpace path with a regression test
- omit the support section when it has no entries\n- preserve operations and account navigation when available\n- cover anonymous standalone navigation
- retain login credentials server-side for legacy Gremlin HTTP\n- prefer Basic auth for authenticated request clients\n- clear legacy credentials with the auth session\n- cover login and session cleanup behavior
- keep Bearer for REST requests\n- use Basic only for Gremlin controllers\n- preserve legacy query, sample, and algorithm access\n- cover profile and auth routing regressions
@dosubot dosubot Bot added size:XL This PR changes 500-999 lines, ignoring generated files. and removed size:L This PR changes 100-499 lines, ignoring generated files. labels Aug 19, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

client hugegraph-client enhancement New feature or request hubble hugegraph-hubble size:XL This PR changes 500-999 lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant