Merge pull request #253 from fgogolli/feat/provider-extension-points

feat: provider extension points, ProviderFulfilment contract, auth security fixes

Author: fgogolli

.github/workflows/ci-quality.yml

@@ -21,6 +21,19 @@ on:
       - 'uv.lock'
       - '.ruff.toml'
       - '.github/workflows/ci-quality.yml'
+  # pull_request_target is needed only for the auto-format-suggest job to call
+  # the PR Reviews API on fork PRs. All other jobs gate on event_name to avoid
+  # double execution.
+  pull_request_target:
+    branches: [ main, develop ]
+    paths:
+      - 'src/**'
+      - 'tests/**'
+      - 'pyproject.toml'
+      - 'requirements*.txt'
+      - 'uv.lock'
+      - '.ruff.toml'
+      - '.github/workflows/ci-quality.yml'
 
 permissions:
   contents: read
@@ -32,6 +45,8 @@ jobs:
 
   quality-check:
     name: Quality Standards
+    # Skip on pull_request_target — only auto-format-suggest needs that event.
+    if: github.event_name != 'pull_request_target'
     runs-on: ubuntu-latest
     needs: config
     permissions:
@@ -65,6 +80,8 @@ jobs:
 
   setup-cache:
     name: Setup Cache
+    # Runs on both pull_request and pull_request_target — auto-format-suggest
+    # depends on it and needs to run on pull_request_target for fork PRs.
     needs: config
     uses: ./.github/workflows/cache-management.yml
     with:
@@ -73,8 +90,10 @@ jobs:
       python-version: ${{ needs.config.outputs.default-python-version }}
 
   auto-format:
-    name: Auto-Format Code  
-    if: github.event_name == 'pull_request'
+    name: Auto-Format Code
+    # Same-repo PRs only: GITHUB_TOKEN can push directly to the branch.
+    # Fork PRs are handled by the auto-format-suggest job below.
+    if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository
     runs-on: ubuntu-latest
     needs: [config, setup-cache]
     permissions:
@@ -108,8 +127,48 @@ jobs:
             git push
           fi
 
+  auto-format-suggest:
+    name: Auto-Format Suggestions
+    # Fork PRs: post formatted changes as PR review suggestions for the
+    # contributor to apply via the GitHub UI's "Commit suggestion" button.
+    # Uses pull_request_target so the GITHUB_TOKEN can call the PR Reviews API
+    # (POST /pulls/{id}/reviews) — pull_request fork-PR tokens cannot.
+    # The workflow file is evaluated at the base ref (safe); only the PR head
+    # code is checked out into a non-elevated working tree for formatting.
+    if: github.event_name == 'pull_request_target' && github.event.pull_request.head.repo.full_name != github.repository
+    runs-on: ubuntu-latest
+    needs: [config, setup-cache]
+    permissions:
+      contents: read
+      pull-requests: write
+    steps:
+      - name: Checkout PR head
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10  # v6
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
+          # No token here — formatter does not need write access; this prevents
+          # untrusted PR code from authenticating with elevated permissions.
+          persist-credentials: false
+
+      - name: Setup UV with cache
+        uses: ./.github/actions/setup-uv-cached
+        with:
+          cache-key: ${{ needs.setup-cache.outputs.cache-key }}
+          fail-on-cache-miss: false
+
+      - name: Run formatter
+        run: make format-fix
+
+      - name: Post review suggestions
+        uses: reviewdog/action-suggester@aa38384ceb608d00f84b4690cacc83a5aba307ff  # v1.24.0
+        with:
+          tool_name: ruff
+          level: warning
+          fail_on_error: false
+
   lint-ruff:
     name: Ruff (Code Quality)
+    if: github.event_name != 'pull_request_target'
     runs-on: ubuntu-latest
     needs: [config, setup-cache]
     permissions:
@@ -129,6 +188,7 @@ jobs:
 
   lint-ruff-optional:
     name: Ruff (Extended Checks)
+    if: github.event_name != 'pull_request_target'
     runs-on: ubuntu-latest
     needs: [config, setup-cache, lint-ruff]
     permissions:
@@ -149,6 +209,7 @@ jobs:
 
   lint-pyright:
     name: Type Checking (pyright)
+    if: github.event_name != 'pull_request_target'
     runs-on: ubuntu-latest
     needs: [config, setup-cache, lint-ruff]
     permissions:
@@ -169,6 +230,7 @@ jobs:
 
   arch-validation:
     name: Architecture Validation
+    if: github.event_name != 'pull_request_target'
     runs-on: ubuntu-latest
     needs: [config, setup-cache, lint-ruff]
     permissions:

.github/workflows/security-code.yml

@@ -118,12 +118,17 @@ jobs:
         # in their PyPI METADATA. The compound string is treated as a single
         # non-allowlisted license. Each exemption below has been verified by reading
         # the package's METADATA license / License-Expression directly:
-        #   werkzeug         BSD-3-Clause AND LicenseRef-scancode-unknown-license-reference -> BSD-3-Clause
-        #   lark             MIT AND MPL-2.0                                                -> MIT (METADATA: License: MIT)
-        #   mcp              MIT AND Python-2.0                                             -> MIT (METADATA: License: MIT)
-        #   rfc3987-syntax   Apache-2.0 AND GPL-1.0-or-later AND MIT                        -> MIT (METADATA: License-Expression: MIT)
-        #   wcwidth          MIT AND HPND-Markus-Kuhn                                       -> MIT (METADATA: License-Expression: MIT)
-        allow-dependencies-licenses: 'pkg:pypi/werkzeug, pkg:githubactions/trufflesecurity/trufflehog, pkg:pypi/lark, pkg:pypi/mcp, pkg:pypi/rfc3987-syntax, pkg:pypi/wcwidth'
+        #   werkzeug                BSD-3-Clause AND LicenseRef-scancode-unknown-license-reference -> BSD-3-Clause
+        #   lark                    MIT AND MPL-2.0                                                -> MIT (METADATA: License: MIT)
+        #   mcp                     MIT AND Python-2.0                                             -> MIT (METADATA: License: MIT)
+        #   rfc3987-syntax          Apache-2.0 AND GPL-1.0-or-later AND MIT                        -> MIT (METADATA: License-Expression: MIT)
+        #   wcwidth                 MIT AND HPND-Markus-Kuhn                                       -> MIT (METADATA: License-Expression: MIT)
+        #   lxml                    BSD-3-Clause AND GPL-1.0-or-later                              -> BSD-3-Clause (METADATA: License: BSD-3-Clause; GPL applies to a single legacy source file)
+        #   protobuf                BSD-3-Clause AND LicenseRef-scancode-protobuf                  -> 3-Clause BSD (METADATA License text)
+        #   pywin32                 PSF-2.0                                                        -> PSF-2.0 (permissive, equivalent to BSD)
+        #   cyclonedx-python-lib    no detected license                                            -> Apache-2.0 (METADATA: License: Apache-2.0)
+        #   fastapi                 no detected license                                            -> MIT (METADATA: License-Expression: MIT)
+        allow-dependencies-licenses: 'pkg:pypi/werkzeug, pkg:githubactions/trufflesecurity/trufflehog, pkg:pypi/lark, pkg:pypi/mcp, pkg:pypi/rfc3987-syntax, pkg:pypi/wcwidth, pkg:pypi/lxml, pkg:pypi/protobuf, pkg:pypi/pywin32, pkg:pypi/cyclonedx-python-lib, pkg:pypi/fastapi'
 
   codeql-analysis:
     name: CodeQL Analysis

.github/workflows/validate-workflows.yml

@@ -69,4 +69,4 @@ jobs:
     - name: Validate shell scripts with shellcheck
       uses: ludeeus/action-shellcheck@00cae500b08a931fb5698e11e79bfbd38e612a38  # 2.0.0
       with:
-        ignore_paths: '.venv .git __pycache__ node_modules'
+        ignore_paths: '.venv .git __pycache__ node_modules k8s'

.gitignore

@@ -12,7 +12,8 @@ requirements-dev.txt
 work/
 
 # Test autogenerated files
-tests/onaws/run_templates*
+tests/providers/aws/live/run_templates/
+tests/providers/aws/live/run_templates/**
 
 # Desloppify scan artifacts
 .desloppify/

.trivyignore

@@ -16,3 +16,9 @@ __pycache__/**
 htmlcov/**
 .tox/**
 .mypy_cache/**
+
+# CVE exceptions for transitive CI/dev-only dependencies with no upstream patch
+# nltk 3.9.4 — CVE-2026-54293 (HIGH). Pulled in transitively by `safety` (CI-only
+# security scanner). No fixed version available upstream as of 2026-06-17. Not
+# present in runtime install. Re-evaluate when nltk publishes a patched release.
+CVE-2026-54293

CHANGELOG.md

@@ -8,6 +8,36 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 <!-- insertion marker -->
 ## Unreleased
 
+### Added
+
+- New `[aws]` extra (alias for AWS deps currently in core). The canonical install
+  command going forward is `pip install orb-py[aws]`. This continues to work
+  unchanged when AWS deps move out of core in a future major version.
+- New `[all-providers]` meta-extra: pulls in all currently implemented providers.
+- New `[monitoring-aws]` extra: AWS-specific OpenTelemetry boto instrumentation (previously bundled inside `[monitoring]`).
+- New `[test-aws]` extra: moto + response-mocking deps for AWS test suites.
+- Architecture test `test_boto3_leak_detection.py`: asserts boto3/botocore are never imported outside `providers/aws/` except by guarded backward-compat shims.
+- Unit tests `test_no_provider_install.py`: verifies ORB core modules boot cleanly when AWS deps are absent.
+
+### Changed
+
+- `[monitoring]` extra no longer includes `opentelemetry-instrumentation-boto` (use `[monitoring-aws]`).
+- `[all]` extra now includes `[all-providers]` so `pip install orb-py[all]` still pulls everything.
+- `[dev]` shim extra now includes `[all-providers]` for full local development.
+- Three module-level import sites guarded with `try/except ImportError` so ORB core boots when AWS extras are absent:
+  `config/schemas/cleanup_schema.py`, `infrastructure/storage/registration.py`,
+  `providers/registration.py` (deprecated shims).
+- `tests/conftest.py`: bare `import boto3` replaced with guarded `AWS_AVAILABLE` flag; AWS provider tests auto-skip when `[aws]` extra is absent.
+
+### Notes
+
+- `boto3` + `botocore` **remain in core** `[project.dependencies]` for now to
+  preserve backward compatibility — `pip install orb-py` still works unchanged.
+- When the second provider (Azure / GCP / OCI) lands, AWS deps will move from
+  core to the `[aws]` extra and a major-version bump will signal the breaking
+  change. Operators who use `pip install orb-py[aws]` today will see no
+  behavior change at that cutover.
+
 <small>[Compare with latest](https://github.com/awslabs/open-resource-broker/compare/v0.1.0rc0...HEAD)</small>
 
 ### Features

README.md

@@ -83,12 +83,36 @@ Get ORB installed and configured for your environment.
 <details>
 <summary>Installation</summary>
 
-### Standard install
+### Standard install (core only — no provider)
 
 ```bash
 pip install orb-py
 ```
 
+ORB boots cleanly with no provider registered.  Any command that needs a provider
+will return a clear "no provider configured" error rather than an ImportError.
+
+### Per-provider install
+
+```bash
+pip install "orb-py[aws]"          # AWS provider (boto3 + botocore)
+pip install "orb-py[aws,cli]"      # AWS provider + colored CLI output
+pip install "orb-py[aws,api]"      # AWS provider + REST API server
+pip install "orb-py[monitoring-aws]"  # AWS provider + full monitoring stack
+pip install "orb-py[all]"          # All providers + all features
+```
+
+### Provider extras matrix
+
+| Use case | Install command |
+|----------|----------------|
+| Core only (no provider) | `pip install orb-py` |
+| AWS operator | `pip install "orb-py[aws]"` |
+| AWS + colored CLI | `pip install "orb-py[aws,cli]"` |
+| AWS + REST API | `pip install "orb-py[aws,api]"` |
+| AWS + monitoring | `pip install "orb-py[monitoring-aws]"` |
+| Full (all providers + features) | `pip install "orb-py[all]"` |
+
 ### With colored CLI output
 
 ```bash