Merge pull request 'security: scope reusable-workflow secrets (least privilege) over secrets: inherit' (#9) from sec/scope-secrets into main

Reviewed-on: #9

.gitea/workflows/adversarial-review.yml

@@ -40,7 +40,13 @@ jobs:
               || github.actor == 'fizi'
               || github.actor == 'dazed'))
     uses: ./.gitea/workflows/review-reusable.yml
-    secrets: inherit
+    # Least privilege: forward ONLY the secrets this swarm uses (cloud + Claude
+    # Code + findings telemetry), not `secrets: inherit`. GITEA_TOKEN is auto.
+    secrets:
+      OLLAMA_CLOUD_API_KEY:    ${{ secrets.OLLAMA_CLOUD_API_KEY }}
+      CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+      GADFLY_FINDINGS_URL:     ${{ secrets.GADFLY_FINDINGS_URL }}
+      GADFLY_FINDINGS_TOKEN:   ${{ secrets.GADFLY_FINDINGS_TOKEN }}
     with:
       models: "minimax-m3:cloud,glm-5.2:cloud,glm-5.1:cloud,deepseek-v4-pro:cloud,nemotron-3-super:cloud,qwen3-coder:480b-cloud,claude-code/sonnet,claude-code/opus,claude-code/opus:max"
       specialists: "security,correctness,error-handling"

.gitea/workflows/review-reusable.yml

@@ -6,19 +6,25 @@
 #   jobs:
 #     review:
 #       if: ...                      # actor gate for the comment trigger
-#       uses: steve/gadfly/.gitea/workflows/review-reusable.yml@main
+#       uses: steve/gadfly/.gitea/workflows/review-reusable.yml@<sha>
-#       secrets: inherit             # passes OLLAMA_CLOUD_API_KEY etc. through
+#       secrets:                     # forward ONLY what the reviewer needs
+#         OLLAMA_CLOUD_API_KEY:    ${{ secrets.OLLAMA_CLOUD_API_KEY }}
+#         CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
 #       with: { models: "...", allowed_users: "..." }   # all optional
 #
 # Inputs are all optional and default to "" — an empty env value makes the
 # image/entrypoint use its own built-in default, so the caller only sets what it
-# wants to override. Secrets come via `secrets: inherit` (verified working on
+# wants to override. Secrets are DECLARED below (workflow_call.secrets) so a
-# this Gitea's act_runner); an undefined secret resolves to empty, so optional
+# caller forwards only the credentials the reviewer actually uses — least
-# ones (Claude Code token, foreman endpoints, findings store) are harmless when
+# privilege — rather than `secrets: inherit`, which leaks every caller secret
-# the consumer hasn't set them.
+# (registry/deploy/db creds) into this workflow. `secrets: inherit` still works
+# if you accept that exposure; the explicit form is recommended. GITEA_TOKEN is
+# the automatic job token (no need to forward it).
 #
 # Advisory only — never blocks a merge. The image is pinned to an immutable
 # :sha- tag here (act_runner caches :latest); bump it per Gadfly release.
+# Consumers should likewise pin `uses: ...@<sha>` (not @main) so a push to this
+# repo can't silently change the code that runs with their forwarded secrets.
 
 name: Gadfly review (reusable)
 
@@ -39,6 +45,24 @@ on:
       # Job wall-clock cap. 45 > 30 as a default: a multi-model swarm or a slow
       # lens (e.g. claude-code with extended thinking) can exceed 30 minutes.
       timeout_minutes:           { type: number, default: 45 }
+    # Declared so callers can forward ONLY the secrets the reviewer needs
+    # (least privilege) instead of `secrets: inherit`, which would hand this
+    # workflow every secret in the caller's repo (registry/deploy/db creds the
+    # review never touches). All optional — an unset/unpassed secret resolves to
+    # empty, harmless for the providers a given consumer doesn't use. GITEA_TOKEN
+    # is the automatic job token and need not be declared/forwarded. Consumers
+    # with bespoke GADFLY_ENDPOINT_<NAME>s beyond M1/M5 need the full stub.
+    secrets:
+      OLLAMA_CLOUD_API_KEY:    { required: false }
+      OPENAI_API_KEY:          { required: false }
+      ANTHROPIC_API_KEY:       { required: false }
+      GOOGLE_API_KEY:          { required: false }
+      GADFLY_API_KEY:          { required: false }
+      CLAUDE_CODE_OAUTH_TOKEN: { required: false }
+      GADFLY_ENDPOINT_M1:      { required: false }
+      GADFLY_ENDPOINT_M5:      { required: false }
+      GADFLY_FINDINGS_URL:     { required: false }
+      GADFLY_FINDINGS_TOKEN:   { required: false }
 
 # The reusable job posts the review comment, so it needs issues/PR write. Gitea
 # caps these by the caller's granted permissions; declaring them here is explicit.
@@ -56,7 +80,11 @@ jobs:
         env:
           # --- event context (from the CALLER's github.*) -------------------
           GITEA_API: ${{ github.server_url }}/api/v1/repos/${{ github.repository }}
-          GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
+          # github.token is the auto job token from the github CONTEXT (not a
+          # secret), so it's present even without `secrets: inherit`. Using
+          # secrets.GITEA_TOKEN here would be empty under explicit secret
+          # forwarding, since the auto token isn't a forwarded workflow_call secret.
+          GITEA_TOKEN: ${{ github.token }}
           EVENT_NAME: ${{ github.event_name }}
           PR: ${{ github.event.pull_request.number || github.event.issue.number || github.event.inputs.pr_number }}
           PR_BRANCH: ${{ github.head_ref }}
@@ -64,7 +92,7 @@ jobs:
           COMMENT_BODY: ${{ github.event.comment.body }}
           COMMENT_ID: ${{ github.event.comment.id }}
           ACTOR: ${{ github.actor }}
-          # --- provider auth (via secrets: inherit; empty if consumer unset) -
+          # --- provider auth (forwarded workflow_call secrets; empty if the caller doesn't forward it) -
           OLLAMA_CLOUD_API_KEY: ${{ secrets.OLLAMA_CLOUD_API_KEY }}
           OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
           ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

CLAUDE.md

@@ -47,7 +47,7 @@ entrypoint.sh          container brains: trigger gating, PR clone, model loop (t
 Dockerfile             multi-stage; private-module creds via BuildKit secrets never reach the final image
 .gitea/workflows/build-image.yml   push main → :latest; tag v* → :<tag>+:latest; PR → build-only
 .gitea/workflows/review-reusable.yml  reusable (workflow_call) review job; consumers subscribe with
-                       an ~8-line caller + `secrets: inherit` (Phase 4). gadfly's own
+                       an ~8-line caller forwarding only the secrets the reviewer needs (Phase 4). gadfly's own
                        adversarial-review.yml is a thin caller of it (dogfoods the path).
 examples/              copy-paste consumer stub workflows for different providers
 ```

README.md

@@ -38,8 +38,8 @@ it. Drop one file in your repo and set a couple of secrets/vars:
 
 1. Copy a stub from [`examples/`](examples/) to `.gitea/workflows/adversarial-review.yml` in
    your repo. Two flavors: the slim [`reusable.yml`](examples/reusable.yml) — a tiny caller of
-   Gadfly's **reusable workflow** (`uses: steve/gadfly/.gitea/workflows/review-reusable.yml@…`
+   Gadfly's **reusable workflow** (`uses: steve/gadfly/.gitea/workflows/review-reusable.yml@…`,
-   + `secrets: inherit`), best when you take the defaults — or the full self-contained
+   forwarding only the secrets the reviewer needs), best when you take the defaults — or the full self-contained
    [`adversarial-review.yml`](examples/adversarial-review.yml) (Ollama Cloud default, with inline
    notes for every provider / local Ollama / OpenAI-compatible / endpoint aliases). See the
    [examples index](examples/README.md).

examples/README.md

@@ -6,7 +6,7 @@ set the secrets/vars it references. Gadfly is advisory only — it never blocks
 
 | File | Backend | Needs |
 |------|---------|-------|
-| [`reusable.yml`](reusable.yml) | **slimmest stub** — calls Gadfly's reusable workflow (`secrets: inherit`); take the defaults or override a few inputs | secret `OLLAMA_CLOUD_API_KEY` |
+| [`reusable.yml`](reusable.yml) | **slimmest stub** — calls Gadfly's reusable workflow, forwarding only the secrets the reviewer needs (least privilege, not `secrets: inherit`); take the defaults or override a few inputs | secret `OLLAMA_CLOUD_API_KEY` |
 | [`adversarial-review.yml`](adversarial-review.yml) | **Ollama Cloud** (default) + inline notes for every provider; full self-contained stub | secret `OLLAMA_CLOUD_API_KEY` |
 | [`local-ollama.yml`](local-ollama.yml) | a **local/LAN Ollama** daemon | nothing (or `GADFLY_BASE_URL` for a remote host) |
 | [`openai-compatible.yml`](openai-compatible.yml) | any **OpenAI-compatible** endpoint (local Ollama `/v1`, gateway, vLLM, OpenRouter…) | `GADFLY_BASE_URL` (+ a key for most gateways) |

examples/reusable.yml

@@ -6,8 +6,12 @@
 # the triggers, the comment-trigger actor gate, and any overrides you want.
 #
 # Needs: secret OLLAMA_CLOUD_API_KEY (the default Ollama Cloud provider).
-# `secrets: inherit` passes your repo/org/user secrets through to the reusable
+# Forward ONLY the secrets the reviewer uses (least privilege) — see the
-# workflow (GITEA_TOKEN is automatic). Pin @<ref> to a Gadfly tag/branch.
+# `secrets:` block below. GITEA_TOKEN is automatic. `secrets: inherit` also works
+# but hands the reusable EVERY secret in your repo (registry/deploy/db creds the
+# review never touches), so prefer the explicit form. Pin @<sha> to an immutable
+# Gadfly commit (not @main) so a push there can't change what runs with your
+# secrets.
 #
 # Prefer this when you're happy with the defaults. For custom named endpoints
 # (GADFLY_ENDPOINT_<NAME>) or a provider the reusable doesn't map, use the full
@@ -40,9 +44,17 @@ jobs:
     if: >-
       github.event_name != 'issue_comment'
       || (github.event.issue.pull_request && github.actor == 'your-username')
-    # Pin @<ref> to a Gadfly release tag for stability (@main tracks latest).
+    # Pin @<sha> to an immutable Gadfly commit (replace @main below) so a push to
+    # gadfly can't silently change the code that runs with your forwarded secrets.
     uses: steve/gadfly/.gitea/workflows/review-reusable.yml@main
-    secrets: inherit
+    # Forward ONLY what the reviewer needs. Add provider keys you use
+    # (ANTHROPIC_API_KEY, OPENAI_API_KEY, GOOGLE_API_KEY, GADFLY_API_KEY) and/or
+    # GADFLY_ENDPOINT_M1/M5; drop the findings ones if you don't run telemetry.
+    secrets:
+      OLLAMA_CLOUD_API_KEY:    ${{ secrets.OLLAMA_CLOUD_API_KEY }}
+      # CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+      # GADFLY_FINDINGS_URL:     ${{ secrets.GADFLY_FINDINGS_URL }}
+      # GADFLY_FINDINGS_TOKEN:   ${{ secrets.GADFLY_FINDINGS_TOKEN }}
     with:
       # All optional — omit to take Gadfly's defaults. Examples:
       # models: "qwen3-coder:480b-cloud,gpt-oss:120b-cloud"