Skip to content

fix(cloud): restrict SDK resolution to a trusted catalog - #556

Closed
dustin-sale wants to merge 1 commit into
oracle:mainfrom
dustin-sale:codex/cloud-sdk-resolution
Closed

dustin-sale wants to merge 1 commit into
oracle:mainfrom
dustin-sale:codex/cloud-sdk-resolution

Conversation

@dustin-sale

Copy link
Copy Markdown
Contributor

Description

Constrain OCI Cloud SDK resolution to a committed catalog before importing client or model modules. The current dispatcher checks namespace/class-name patterns before importing, then validates membership afterward; parameter-error hints can also repeat resolution of rejected input.

This change:

  • Generates and packages a deterministic catalog for the existing OCI SDK 2.185.1 pin: 322 service clients, 8,220 operations and 16,327 models, including exported and defining-module aliases.
  • Uses the same catalog for invocation, operation descriptions, client/operation discovery and every request-model resolution path. Nested models and polymorphic subtypes use the selected model's service and approved inheritance relationships.
  • Completes operation/model resolution before credentials or client/model construction. Error repair reuses validated state instead of importing rejected names again.
  • Fails startup for missing, malformed or SDK-version-mismatched catalogs. Generation derives sdk_version from the exact pyproject.toml pin and checks the installed SDK, lockfile and reviewed schema-exception version. Builds, installation and startup consume the committed resource without regeneration.
  • Records the pinned SDK's 65 missing field-type references explicitly, preserving raw values and approved model hints without making nonexistent types constructible.
  • Adds generator failure-path tests and independent reconciliation of catalog operations, aliases, defining classes and inheritance with the installed SDK. Updates the README, agent guidance and changelog, and bumps the package/lock metadata to 2.3.1.

Compatibility: Supported service operations, aliases, coercion, pagination and caller-specific authentication remain supported. Infrastructure/helper/vendor classes, composite wrappers, private/unlisted operations and unknown/conflicting model hints are rejected. Catalog membership constrains Python resolution; OCI permissions and write-policy defaults remain unchanged.

Dependencies: No dependent PRs or dependency upgrades. The OCI SDK pin and Common dependency are unchanged. Nonroot execution and immutable application/SDK import locations remain deployment requirements; this PR documents them without changing a deployment.

Tracking reference: Not supplied.

Type of change

  • Bug fix (non-breaking change which fixes an issue)
  • This change requires a documentation update

How Has This Been Tested?

Validation covers the committed branch contents at b574f19. Run from the repository root with the pinned tools:

moon run oci-cloud-mcp-server:lock-check
uv run --directory src/oci-cloud-mcp-server --locked python3 scripts/generate_sdk_catalog.py --check
moon run oci-cloud-mcp-server:test --force
moon run root:lint
moon run oci-cloud-mcp-server:build --force
  • Unit and MCP-boundary tests: 403 passed. Cover rejection before imports/authentication/construction, early-error repair, client/model aliases, nested/list/dictionary coercion, cross-service hints, polymorphism, startup failures, authentication isolation and pagination/result regressions.
  • Generator checks: Deterministic bytes and read-only drift detection; manifest/SDK/lock/exception version agreement; malformed SDK declarations, unexpected helpers, missing bases and stale exceptions; CLI success/failure without overwriting an existing catalog. Synthetic fixtures do not execute SDK modules or constructors, and version expectations come from the manifest.
  • Independent SDK reconciliation: Catalog operations, aliases, defining classes and direct model inheritance agree with the installed SDK.
  • Lock, lint and build: All passed. Both the 2.3.1 wheel and sdist contain the exact regenerated catalog bytes.
Coverage scope Statements + branches
Package total 94.47%
Catalog resolver 99.12%
Server 92.60%
Catalog generator 99.22%

The configured package coverage gate is 90%. One existing upstream Authlib deprecation warning remains. The generator's remaining unmeasured line is its CLI entrypoint, which subprocess tests exercise outside the parent coverage process.

Clean wheel/sdist/rebuilt-wheel installations and 18 invalid-catalog startup checks also passed during implementation, before the final package-version metadata and test-only follow-ups. That installation matrix has not been rerun against the final 2.3.1 artifacts. Live OCI calls, HTTP token exchange and deployed filesystem protections were not exercised.

Test Configuration:

  • Firmware version: Not applicable.
  • Hardware: macOS ARM64.
  • Toolchain: Python 3.13.15, pytest 9.0.3, Moon 2.6.2 and uv 0.12.1.
  • SDK: OCI Python SDK 2.185.1; FastMCP 3.4.10.

Checklist:

  • My code follows the style guidelines of this project
  • I have performed a self-review of my own code
  • I have commented my code, particularly in hard-to-understand areas
  • I have made corresponding changes to the documentation
  • My changes generate no new warnings
  • I have added tests that prove my fix is effective or that my feature works
  • New and existing unit tests pass locally with my changes
  • Any dependent changes have been merged and published in downstream modules — not applicable; no dependent changes

@oracle-contributor-agreement oracle-contributor-agreement Bot added the OCA Verified All contributors have signed the Oracle Contributor Agreement. label Nov 10, 2026
@dustin-sale
dustin-sale marked this pull request as ready for review November 10, 2026 20:07
@dustin-sale
dustin-sale force-pushed the codex/cloud-sdk-resolution branch from b574f19 to db37c93 Compare November 10, 2026 20:44
@gebhardtr

gebhardtr commented Nov 10, 2026 •

Copy link
Copy Markdown
Member

what prevents someone from just updating the on-disk catalog? and how did we determine what is "trusted"?

@dustin-sale
dustin-sale marked this pull request as draft November 10, 2026 21:40
@dustin-sale
dustin-sale deleted the codex/cloud-sdk-resolution branch November 12, 2026 14:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

OCA Verified All contributors have signed the Oracle Contributor Agreement.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants