Expose typed endpoint permissions and detect permission drift

[sdairs]

The OpenAPI analyzer currently ignores operation security requirements, so published permission changes can leave the library and CLI with no usable permission information. Add an offline, typed operation catalog and drift checks that keep it aligned with the spec.

• Generate all 157 descriptors under meta::operations, with exact operation ID, Rust method, HTTP method/path, and all required API-key permission IDs. Unknown operation lookup returns None; a known empty list means a valid API key with no extra named permissions.
• Resolve operation/root security consistently for generation and comparison. Detect snapshot permission deltas, stale/missing/invalid descriptors, mismatched identities and catalog coverage/order. Unsupported security shapes remain actionable and cannot generate misleading empty requirements.
• Upgrade the shared report to schema 10, render permission deltas in drift issues, and keep analyzer/parser dependencies outside the published runtime dependency graph.

Refs #998. CLI consumption is the separate PR #1000 in the permissions series.

Stack and merge order

This is the first PR in GitHub stack #1001, targeting main. PR #1000 builds on this branch. The previous prerequisite stack and external PR #993 have merged; both permission commits have now been replayed onto that merged main. Merge this PR before #1000.

Validation

• cargo fmt --all --check
• cargo clippy -p clickhouse-cloud-api -p clickhouse-openapi-analyzer --all-targets -- -D warnings
• cargo test -p clickhouse-cloud-api -p clickhouse-openapi-analyzer
• python3 -m unittest discover -s scripts/tests -p 'test_*.py'
• Permission-only add/remove/replace/root-inheritance fixtures, unsupported/malformed security, snapshot-refresh mismatch, descriptor/catalog validation, exact-ID lookup, deterministic reports and generated catalog parity.

Live Cloud provisioning tests are not part of the local test run; this change adds static metadata and offline tooling, with no request-execution changes.

Rebase verification

Rebased onto merged main without conflicts; git range-diff confirms both permission patches are unchanged. Formatting, all eight permission-unit tests, three permission-help subprocess tests, the query-endpoint request test, and the inherited pagination shell-token test pass on the rebased top branch. CI and live Cloud checks must attest the new PR head.

[mdevils]

I'm not really sure that we should bundle permissions. One thing is API schema, it's supposed to be backwards compatible. But permissions may change (become more gradual). That information can be easily extracted in runtime by requesting the OpenAPI schema via /v1.json (or /v1.yaml).

[sdairs]

@mdevils I'm open to it, but my concern would be

1. latency
2. offline support

perhaps caching the OpenAPI locally could work but it would need some baked in fallbacks.

[mdevils]

@sdairs from what I see in the code, permissions are not used anywhere right now. My understanding is that they will be used in permission negotiation process, which of course requires a network connection. Is there any other use-case?
Also, for proper negotiation, the connection between CLI commands and OpenAPI operations should exist in some way. Is that rust_method field?

[sdairs]

@mdevils that's a good point. It will exclusively be used for cloud stuff, and so the offline support side of things is probably not that important. That said, the CLI still needs to work offline. Even though you won't be able to actually do any cloud operations, we can't have failures if people do want to explore cloud commands offline, so there needs to be something. Primary use case for the permissions is agent permission negotiation.

I also don't think that we necessarily need to go the dynamic route from the get-go. None of this is a single-way door, we can always go down a dynamic route in the future if we see the permissions are changing to a degree that the CLI is becoming out of sync. We have a similar thing anyway with commands being changed in the Open API that are then hard-coded in the CLI, and fields of requests changing in the Open API, so we have this problem outside of just permissions already. To date it hasn't been a problem, we move fast to react to change in the OpenAPI.

I am not entirely sure what the second question means - a user/agent doesn't need to know what OpenAPI operations are performed behind the scenes.

[mdevils]

@sdairs

I also don't think that we necessarily need to go the dynamic route from the get-go.

OK, fair enough, we can start this way.

I am not entirely sure what the second question means - a user/agent doesn't need to know what OpenAPI operations are performed behind the scenes.

Operations are exactly the list you've generated in this PR:

I.e.:

pub const ACTIVE_BALANCES_GET: OperationMetadata = OperationMetadata {
    operation_id: "activeBalancesGet",
    rust_method: "active_balances_get",
    method: "GET",
    path: "/v1/organizations/{organizationId}/activeBalances",
    required_permissions: &["control-plane:organization:view-billing"],
};

I see that you map rust_method to operation_id. Does it mean we know operationId for any CLI command and can get necessary permission?

If so, it would be useful to have some kind of flag:

clickhousectl cloud postgres create --show-permission

And then it shows what permission it needs to run it.

That way agent can figure out for what commands what permissions are needed.

[sdairs]

@mdevils got it - correct: #1000 this PR demonstrates consumption by the CLI. It just exposes it in help, we don't need to introduce more flags/commands atm.