Adding RPST bootstrap method to the common auth module

[shyam2511]

Description

Adds resource_principal_v212 authentication support to oracle-mcp-common for the Database-service resource-principal token exchange.

The common auth module previously supported the OCI SDK’s standard resource-principal environment flow, but did not accept the PR’s RCI/T0 bootstrap inputs or generate the required security context. The new mode uses the OCI SDK’s EphemeralResourcePrincipalV21Signer for token retrieval, exchange, and refresh, while common auth validates and supplies the required configuration.

Also:

• Simplified HOTP-style digest truncation with int.from_bytes.
• Bumped oracle-mcp-common from 0.1.0 to 0.2.0.
• Updated adopter compatibility bounds to >=0.2.0,<0.3.0.
• Added common-module documentation and changelog entries.

Fixes #

Dependencies required:

• oci>=2.179.0 (already required; provides EphemeralResourcePrincipalV21Signer)
• Adopters must use oracle-mcp-common>=0.2.0,<0.3.0

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality) Issue Add Resource Principal Bootstrap Auth Mechanism to commons module #412
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update

How Has This Been Tested?

• make test project=common
• make lint
• Black and isort run on changed common auth files
• Ran the source code on a db system using rpst authentication and successfully ran mcp commands

Test Configuration:

• Firmware version: N/A
• Hardware: macOS development environment
• Toolchain: Python 3.14.5, uv
• SDK: OCI Python SDK 2.182.0

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

[dustin-sale]

Review by @dustin-sale via Codex.

Requested changes

• src/common/oracle_mcp_common/auth.py:566 — [P1] Regenerate the time-derived security context for every RPT acquisition.
• src/common/oracle_mcp_common/auth.py:549 — [P1] Resolve default endpoints using the region's OCI realm.
• src/common/oracle_mcp_common/auth.py:74 — [P1] Prevent the RCI HMAC key from appearing in representations.
• src/oci-api-mcp-server/pyproject.toml:15 — [P1] Add the OCI API server release version and changelog update.
• src/oci-cloud-mcp-server/pyproject.toml:15 — [P1] Add the OCI Cloud server release version and changelog update.
• src/oci-database-mcp-server/pyproject.toml:15 — [P1] Add and synchronize the Database server release version and changelog update.

Additional review notes

• [P2] Preserve the RPv2.1.2 tenancy ID in AuthContext.
• [P2] Add a deterministic cryptographic and refresh regression test.
• [P2] Update repository guidance to the common 0.2 compatibility window.

Validation

• make lint, make test project=common, the full make test, all four lock checks, and all four requested make install checks passed.
• The full suite completed with 2,199 passed, one skipped, and 91% combined coverage.

See the inline comments in this review for evidence, impact, and suggested remediation.

[shyam2511]

Addressed the PR comments by @dustin-sale , the server now:

• Refreshes the RPv2.1.2 security context before every RPT acquisition.
• Uses OCI realm-aware database and auth endpoints.
• Redacts the RCI HMAC key from dataclass representations.
• Preserves the supplied RPv2.1.2 tenancy ID in AuthContext.
• Added deterministic signature, refresh, and realm endpoint regression tests.
• Updated common-library guidance to >=0.2.0,<0.3.0.

[dustin-sale]

Review by @dustin-sale via Codex.

Requested changes

• src/common/oracle_mcp_common/auth.py:578 — [P1] Regenerate the proof for SDK retry attempts.

Additional review notes

• src/common/README.md:96 — [P2] Document and lock down RCI secret handling.
• src/common/oracle_mcp_common/tests/test_auth.py:602 — [P2] Exercise timestamp validation independently.
• src/common/README.md — [P2] Update the common dependency example.
• src/common/README.md:99 — [P2] Describe realm-aware endpoint defaults.

Validation

• Lint and the full repository suite passed: 2,259 passed, 1 skipped, with 91% combined coverage.
• Lock checks and make install passed for common 0.2.0 and the updated API, Cloud, and Database server versions.

See the inline comments in this review for evidence, impact, and suggested remediation.

[shyam2511]

Review by @dustin-sale via Codex.

Requested changes

• src/common/oracle_mcp_common/auth.py:578 — [P1] Regenerate the proof for SDK retry attempts.

Additional review notes

• src/common/README.md:96 — [P2] Document and lock down RCI secret handling.
• src/common/oracle_mcp_common/tests/test_auth.py:602 — [P2] Exercise timestamp validation independently.
• src/common/README.md — [P2] Update the common dependency example.
• src/common/README.md:99 — [P2] Describe realm-aware endpoint defaults.

Validation

• Lint and the full repository suite passed: 2,259 passed, 1 skipped, with 91% combined coverage.
• Lock checks and make install passed for common 0.2.0 and the updated API, Cloud, and Database server versions.

See the inline comments in this review for evidence, impact, and suggested remediation.

Addressed and pushed the new review feedback i:
Regenerates the RPT security proof inside the SDK retry callable, so every retry gets a distinct header.
Added retry-level, secret-redaction, and malformed/naive/future timestamp tests.
Documented RCI as sensitive HMAC-key material.
Corrected README dependency guidance and realm-aware endpoint documentation.
Validation passed: make test project=common, make lint, and make test.

[dustin-sale]

Review by @dustin-sale via Codex.

Requested changes

• src/common/oracle_mcp_common/auth.py:570 — [P1] Install the retry hook before the initial exchange.

Additional review notes

• src/common/oracle_mcp_common/auth.py:580 — [P2] Fail closed if the SDK retry hook cannot be installed.
• src/common/pyproject.toml:3 — [P2] Synchronize the common package's exported version.

Validation

• make lint, make test project=common, and the full make test suite passed; 2,264 tests passed, 1 was skipped, and combined coverage was 91%.
• Lockfile checks and make install passed for common, API, Cloud, and Database. All GitHub checks are green.

See the inline comments in this review for evidence, impact, and suggested remediation.

[shyam2511]

Implemented @dustin-sale's requested changes.
RPv2.1.2 now subclasses the OCI SDK signer so proof regeneration is active during the constructor’s initial exchange and every RPT retry.
Construction fails explicitly if the SDK retry hook is unavailable.
oracle_mcp_common.version now matches package metadata: 0.2.0.
Added regression tests for initial retry freshness and incompatible SDK behavior.

[dustin-sale]

Review by @dustin-sale via Codex.

Requested changes

No blocking changes requested.

Additional review notes

None.

Validation

• make lint, make test project=common, and the full make test suite passed; 2,265 tests passed, 1 was skipped, and combined coverage was 91%.
• Lockfile checks, affected package installations, runtime version synchronization, and OCI SDK compatibility probes passed. All GitHub checks are green.

No inline comments.

This will need additional reviews from @gebhardtr and @robander