refactor: authorization model to use .github/allowed_repos.json (#2)

* refactor: authorization model to use .github/allowed_repos.json

- Introduced .github/allowed_repos.json as the source of truth for authorized repositories, replacing the ALLOWED_REPOS secret.
- Updated workflows and documentation to reflect the new file-based allowlist approach.
- Removed ALLOWED_REPOS references from Makefile and README, enhancing clarity on authorization process.

This change improves maintainability and security by centralizing the allowlist within the repository.

Signed-off-by: Jonathan Kilzi <jkilzi@redhat.com>

* tests: Enhance Makefile and README with new testing targets and documentation

- Added `test-allowlist` target to run allowlist validation and authorization logic tests without Docker.
- Introduced `test-all` target to execute both allowlist tests and the full act workflow test.
- Updated help section in Makefile to reflect new targets and improved descriptions for existing commands.
- Enhanced README with instructions for running allowlist tests and clarified descriptions for make targets.

These changes improve the testing framework and documentation for better usability and clarity.

Signed-off-by: Jonathan Kilzi <jkilzi@redhat.com>

---------

Signed-off-by: Jonathan Kilzi <jkilzi@redhat.com>

Author: jkilzi

.github/workflows/generate-and-publish.yml

@@ -8,7 +8,7 @@
 # Output: Generated client is placed in the 'generated-client' directory
 #
 # Authorization: Calls from this repository are automatically authorized.
-# External repositories must be listed in the ALLOWED_REPOS secret.
+# External repositories must be listed in .github/allowed_repos.json (source of truth).
 #
 # Publishing Authentication (in order of precedence):
 #   1. npm Trusted Publishing (OIDC) - preferred, no long-lived tokens needed
@@ -55,19 +55,16 @@ on:
         type: boolean
         default: false
     secrets:
-      ALLOWED_REPOS:
-        description: 'JSON array of authorized repository names'
-        required: true
       NPM_TOKEN:
-        description: 'npm access token - fallback for when OIDC is unavailable (local testing with act-cli)'
+        description: 'npm access token - fallback for when OIDC is unavailable (e.g.: local testing with act-cli)'
         required: false
 
 jobs:
   # ===========================================================================
   # Job 1: Authorization Check
   # ===========================================================================
   # This repository is automatically authorized (for CI/testing).
-  # External repositories must be listed in ALLOWED_REPOS secret.
+  # External repositories must be listed in .github/allowed_repos.json.
   # ===========================================================================
   authorize:
     name: Verify Authorization
@@ -78,30 +75,30 @@ jobs:
       - name: Verify caller is authorized
         id: check
         env:
-          ALLOWED_REPOS: ${{ secrets.ALLOWED_REPOS }}
           CALLER_REPO: ${{ github.repository }}
           THIS_REPO: "kubev2v/migration-planner-client-generator"
+          ALLOWED_REPOS_URL: "https://raw.githubusercontent.com/kubev2v/migration-planner-client-generator/main/.github/allowed_repos.json"
         run: |
+          set -e
           # Allow calls from this repository (for CI/testing)
           if [ "$CALLER_REPO" = "$THIS_REPO" ]; then
             echo "authorized=true" >> $GITHUB_OUTPUT
             echo "✅ Repository is authorized (same-repo call)"
             exit 0
           fi
           
-          # For external callers, validate ALLOWED_REPOS secret
+          # Fetch allowed repos list (source of truth in this repo)
+          ALLOWED_REPOS=$(curl -sL "$ALLOWED_REPOS_URL") || true
           if [ -z "$ALLOWED_REPOS" ]; then
-            echo "::error::ALLOWED_REPOS secret is not configured"
+            echo "::error::Failed to fetch .github/allowed_repos.json"
             exit 1
           fi
           
-          # Validate secret is valid JSON
           if ! echo "$ALLOWED_REPOS" | jq empty 2>/dev/null; then
-            echo "::error::ALLOWED_REPOS secret is not valid JSON"
+            echo "::error::allowed_repos.json is not valid JSON"
             exit 1
           fi
           
-          # Check if caller repo is in the allowed list (exact match)
           if echo "$ALLOWED_REPOS" | jq -e --arg repo "$CALLER_REPO" 'index($repo) != null' > /dev/null; then
             echo "authorized=true" >> $GITHUB_OUTPUT
             echo "✅ Repository is authorized"

AGENTS.md

@@ -12,9 +12,11 @@ This is a **GitOps repository** providing a reusable GitHub Actions workflow for
 
 ```
 .
-├── .github/workflows/
-│   ├── generate-and-publish.yml   # Main reusable workflow (workflow_call)
-│   └── test.yml                   # CI test workflow
+├── .github/
+│   ├── allowed_repos.json         # Source of truth: repos allowed to call the workflow
+│   └── workflows/
+│       ├── generate-and-publish.yml   # Main reusable workflow (workflow_call)
+│       └── test.yml                   # CI test workflow
 ├── .actrc                         # act-cli configuration
 ├── .gitignore
 ├── LICENSE                        # Apache-2.0
@@ -32,8 +34,8 @@ This is a **GitOps repository** providing a reusable GitHub Actions workflow for
 
 2. **Authorization Model**
    - **Self-authorization**: This repository is automatically authorized (for CI/testing)
-   - External repos validated via `jq` exact-match against `ALLOWED_REPOS` secret
-   - Secret contains JSON array: `["org/repo1", "org/repo2"]`
+   - External repos validated via `.github/allowed_repos.json` (source of truth in this repo)
+   - Workflow fetches the file from `main`; file is a JSON array: `["org/repo1", "org/repo2"]`
    - Fails fast before any generation occurs
 
 ## Critical Constraints
@@ -79,11 +81,9 @@ This workflow uses **npm Trusted Publishing (OIDC)** as the primary authenticati
 ### Required Secrets
 
 **In this repository:**
-- `ALLOWED_REPOS` - JSON array of authorized external repository names (this repo is auto-authorized)
 - `NPM_TOKEN` - *(optional)* npm access token, only needed for local testing fallback
 
 **In calling repositories:**
-- `ALLOWED_REPOS` - Must be passed through to the reusable workflow
 - Calling workflow must have `permissions: id-token: write` for OIDC
 - Use `secrets: inherit` to pass OIDC permissions to the reusable workflow
 
@@ -133,7 +133,6 @@ For local publish testing:
 ```bash
 # .secrets file for local publish testing
 NPM_TOKEN=npm_your-real-granular-token-here
-ALLOWED_REPOS=["kubev2v/migration-planner-client-generator"]
 ```
 
 ### CI Feature Toggle
@@ -166,9 +165,9 @@ When publishing is enabled, the test package is automatically unpublished after
 
 ## Security Considerations
 
-1. **Never expose the ALLOWED_REPOS list** - Error messages should not reveal authorized repos
-2. **Use exact string matching** - `jq index()` prevents partial name attacks
-3. **Validate JSON before parsing** - Use `jq empty` to verify format
+1. **Use exact string matching** - `jq index()` prevents partial name attacks
+2. **Validate JSON before parsing** - Use `jq empty` to verify format before use
+3. **Allowed list is in repo** - `.github/allowed_repos.json` is the source of truth; only maintainers can change it
 4. **Secrets are masked** - GitHub automatically masks secret values in logs
 
 ## Related Repositories
@@ -182,9 +181,9 @@ When publishing is enabled, the test package is automatically unpublished after
 
 ### Adding a New Authorized Repository
 
-1. Update the `ALLOWED_REPOS` secret in GitHub Settings
+1. Edit `.github/allowed_repos.json` in this repository
 2. Add the repo to the JSON array: `["existing/repo", "new/repo"]`
-3. No code changes required
+3. Commit and push to `main` (workflow fetches from `main`)
 
 ### Updating Generator Settings
 
@@ -199,6 +198,5 @@ When publishing is enabled, the test package is automatically unpublished after
 
 1. If calling from this repo: Should auto-authorize; check workflow syntax
 2. If calling from external repo:
-   - Check `ALLOWED_REPOS` secret is valid JSON
-   - Verify exact repository name match (case-sensitive)
-   - Ensure calling workflow passes `ALLOWED_REPOS` secret through
+   - Ensure the repo is listed in `.github/allowed_repos.json` (exact `owner/repo` match, case-sensitive)
+   - Check that the file is valid JSON and fetchable from `main` (raw GitHub URL)

Makefile

@@ -4,27 +4,29 @@
 # Local testing with act-cli
 # =============================================================================
 
-.PHONY: help test test-publish test-verbose setup-secrets clean check-act
+.PHONY: help test test-publish test-verbose test-allowlist test-all setup-secrets clean check-act
 
 # Default target
 help:
 	@echo "OpenAPI Client Generator - Local Testing"
 	@echo ""
 	@echo "Usage:"
-	@echo "  make setup-secrets  Create .secrets file template"
-	@echo "  make test           Run test workflow (dry-run mode, no npm publish)"
-	@echo "  make test-publish   Run test workflow with actual npm publishing"
+	@echo "  make setup-secrets   Create .secrets file template"
+	@echo "  make test            Run test workflow via act (dry-run mode, no npm publish)"
+	@echo "  make test-publish    Run test workflow with actual npm publishing"
 	@echo "  make test-verbose   Run test workflow with verbose output"
-	@echo "  make clean          Remove generated artifacts"
-	@echo "  make check-act      Verify act-cli is installed"
+	@echo "  make test-allowlist Run allowlist validation and authorize logic tests (no Docker)"
+	@echo "  make test-all       Run test-allowlist then test (act)"
+	@echo "  make clean           Remove generated artifacts"
+	@echo "  make check-act       Verify act-cli is installed"
 	@echo ""
 	@echo "Variables:"
 	@echo "  GITHUB_REPOSITORY   Override github.repository context (default: kubev2v/migration-planner-client-generator)"
 	@echo "  TEST_NPM_PUBLISH    Set to 'true' to enable npm publishing (default: empty/dry-run)"
 	@echo ""
 	@echo "Prerequisites:"
-	@echo "  - act-cli: brew install act"
-	@echo "  - Docker: must be running"
+	@echo "  - act-cli: brew install act (for make test)"
+	@echo "  - Docker (or Podman): must be running (for make test)"
 
 # -----------------------------------------------------------------------------
 # Setup
@@ -45,9 +47,6 @@ setup-secrets:
 		echo '#   (OIDC/Trusted Publishing does not work locally, so token auth is used as fallback)' >> .secrets; \
 		echo 'NPM_TOKEN=fake-token-for-testing' >> .secrets; \
 		echo '' >> .secrets; \
-		echo '# Allowed repositories (JSON array)' >> .secrets; \
-		echo '# Include this repo for local testing' >> .secrets; \
-		echo 'ALLOWED_REPOS=["kubev2v/migration-planner-client-generator"]' >> .secrets; \
 		echo "✅ Created .secrets file"; \
 		echo ""; \
 		echo "Edit .secrets if you need to customize the values."; \
@@ -78,6 +77,17 @@ ACT_FLAGS = --secret-file .secrets \
 	--var TEST_NPM_PUBLISH=$(TEST_NPM_PUBLISH) \
 	-P ubuntu-latest=catthehacker/ubuntu:act-latest
 
+# Run allowlist and authorize logic tests (no Docker/act)
+test-allowlist:
+	@echo "🧪 Running allowlist and authorize logic tests..."
+	@./tests/validate_allowed_repos.sh
+	@./tests/test_authorize_logic.sh
+	@echo "✅ test-allowlist passed"
+
+# Run allowlist tests then full act workflow test
+test-all: test-allowlist test
+	@echo "✅ test-all passed"
+
 # Run test workflow (dry-run mode - no actual publishing)
 test: check-act
 	@if [ ! -f .secrets ]; then \

README.md

@@ -71,9 +71,10 @@ This workflow uses **npm Trusted Publishing (OIDC)** as the primary authenticati
 
 | Secret | Required | Description |
 |--------|----------|-------------|
-| `ALLOWED_REPOS` | Yes | JSON array of authorized repository names |
 | `NPM_TOKEN` | No | Only needed for local testing with act-cli (OIDC fallback) |
 
+Authorization is controlled by `.github/allowed_repos.json` in this repository (see [Authorization Model](#authorization-model)).
+
 ## Generator Configuration
 
 The workflow uses hardcoded generator settings that **cannot be modified by callers**:
@@ -96,26 +97,27 @@ These settings match the configuration in [kubev2v/migration-planner-ui](https:/
 The workflow includes a mandatory authorization check before generating and publishing clients.
 
 1. **Self-Authorization**: Calls from this repository (`kubev2v/migration-planner-client-generator`) are automatically authorized for CI/testing purposes
-2. **Secret-based Allowlist**: External repositories must be listed in the `ALLOWED_REPOS` secret (JSON array)
+2. **File-based Allowlist**: External repositories must be listed in `.github/allowed_repos.json` in this repository (source of truth)
 3. **Exact Match**: Uses `jq` for precise string matching (no partial matches)
 4. **Fail-Fast**: Unauthorized requests are rejected before any generation occurs
 
-### Configuring Authorization
+The workflow fetches the allowlist from the `main` branch at run time, so updates take effect as soon as they are merged.
+
+### Adding an Authorized Repository
 
-Set the `ALLOWED_REPOS` secret in this repository with a JSON array of external repositories:
+Edit `.github/allowed_repos.json` in this repository and add the repo to the JSON array:
 
 ```json
-["kubev2v/migration-planner", "kubev2v/migration-planner-ui"]
+["kubev2v/migration-planner", "kubev2v/assisted-migration-agent"]
 ```
 
-> **Note**: You don't need to add this repository to `ALLOWED_REPOS` - it's automatically authorized.
+> **Note**: You don't need to add this repository to the file—it's automatically authorized.
 
 ### Security Features
 
-- Allowlist is stored as a secret (never exposed in logs or workflow file)
+- Single source of truth in the repo; only maintainers can change the list
 - Exact string matching prevents partial name attacks
 - JSON format is validated before use
-- Error messages don't reveal which repos are authorized
 
 ## Local Development
 
@@ -140,11 +142,23 @@ make test-publish
 make clean
 ```
 
+### Allowlist tests (no Docker)
+
+Run allowlist validation and authorize logic tests without act/Docker:
+
+```bash
+make test-allowlist
+```
+
+These tests validate `.github/allowed_repos.json` (valid JSON, array of strings) and that the same allow/deny logic as the workflow behaves correctly (same-repo allowed, list lookup, exact match).
+
 ### Make Targets
 
 | Command | Description |
 |---------|-------------|
-| `make test` | Run workflow in dry-run mode (tests generation/build only) |
+| `make test` | Run workflow in dry-run mode via act (tests generation/build only) |
+| `make test-allowlist` | Run allowlist and authorize logic tests (no Docker) |
+| `make test-all` | Run test-allowlist then make test |
 | `make test-publish` | Run workflow with actual npm publishing + cleanup |
 | `make test-verbose` | Run workflow with verbose output |
 | `make setup-secrets` | Create `.secrets` file template |
@@ -166,12 +180,16 @@ When enabled, test packages are automatically unpublished after successful publi
 ```
 .
 ├── .github/
+│   ├── allowed_repos.json             # Allowed callers (source of truth)
 │   └── workflows/
 │       ├── generate-and-publish.yml   # Reusable workflow
 │       └── test.yml                   # CI test workflow
+├── tests/
+│   ├── validate_allowed_repos.sh      # Validate allowlist JSON
+│   └── test_authorize_logic.sh       # Test authorize allow/deny logic
 ├── .actrc                             # act-cli configuration
 ├── .gitignore                         # Ignores generated-client/, secrets, etc.
-├── Makefile                           # Local testing commands (make test, make clean)
+├── Makefile                           # Local testing commands (make test, make test-allowlist, etc.)
 ├── AGENTS.md                          # AI agent guidelines
 ├── LICENSE                            # Apache-2.0
 └── README.md                          # This file

tests/test_authorize_logic.sh

@@ -0,0 +1,83 @@
+#!/usr/bin/env bash
+# =============================================================================
+# Test authorize logic (same as workflow: same-repo shortcut + allowlist check)
+# =============================================================================
+# Uses local .github/allowed_repos.json (no curl). Verifies:
+# - Same repo (THIS_REPO) is always authorized
+# - Repo in allowed_repos.json is authorized
+# - Repo not in list is denied
+# =============================================================================
+set -e
+
+REPO_ROOT="${REPO_ROOT:-$(cd "$(dirname "$0")/.." && pwd)}"
+ALLOWED_REPOS_FILE="${REPO_ROOT}/.github/allowed_repos.json"
+THIS_REPO="kubev2v/migration-planner-client-generator"
+
+assert_authorized() {
+  local caller_repo="$1"
+  local list_content="$2"
+  if [ "$caller_repo" = "$THIS_REPO" ]; then
+    return 0
+  fi
+  echo "$list_content" | jq -e --arg repo "$caller_repo" 'index($repo) != null' >/dev/null
+}
+
+assert_unauthorized() {
+  local caller_repo="$1"
+  local list_content="$2"
+  if [ "$caller_repo" = "$THIS_REPO" ]; then
+    echo "Expected unauthorized but same-repo is always allowed: $caller_repo"
+    return 1
+  fi
+  ! echo "$list_content" | jq -e --arg repo "$caller_repo" 'index($repo) != null' >/dev/null 2>&1
+}
+
+list=$(cat "$ALLOWED_REPOS_FILE")
+if ! echo "$list" | jq empty 2>/dev/null; then
+  echo "::error::allowed_repos.json is not valid JSON (run validate_allowed_repos.sh first)"
+  exit 1
+fi
+
+errors=0
+
+# Same repo is always authorized (no list lookup)
+if assert_authorized "$THIS_REPO" "[]"; then
+  echo "✅ Same-repo ($THIS_REPO) is authorized (shortcut)"
+else
+  echo "::error::Same-repo should be authorized"
+  errors=$((errors + 1))
+fi
+
+# First repo in the list should be authorized when used as caller
+first_repo=$(echo "$list" | jq -r '.[0]')
+if [ -n "$first_repo" ] && [ "$first_repo" != "null" ]; then
+  if assert_authorized "$first_repo" "$list"; then
+    echo "✅ Caller in list ($first_repo) is authorized"
+  else
+    echo "::error::Caller in list ($first_repo) should be authorized"
+    errors=$((errors + 1))
+  fi
+fi
+
+# Random repo not in list should be unauthorized
+if assert_unauthorized "other-org/other-repo" "$list"; then
+  echo "✅ Caller not in list (other-org/other-repo) is denied"
+else
+  echo "::error::Caller not in list should be denied"
+  errors=$((errors + 1))
+fi
+
+# Partial match should be denied (exact match only)
+if echo "$list" | jq -e --arg repo "kubev2v/migration-planner-fake" 'index($repo) != null' >/dev/null 2>&1; then
+  echo "::error::Partial repo name should not match"
+  errors=$((errors + 1))
+else
+  echo "✅ Partial repo name does not match (exact match only)"
+fi
+
+if [ $errors -gt 0 ]; then
+  echo "::error::$errors assertion(s) failed"
+  exit 1
+fi
+
+echo "✅ All authorize logic tests passed"