Merge pull request #195 from LerianStudio/develop

fix(release): merge develop into main

Author: bedatty

.cursor/rules/reusable-workflows.mdc

@@ -417,6 +417,92 @@ uses: some-action/tool@main    # use a specific tag or SHA
 - Never print secrets via `echo`, env dumps, or step summaries
 - Complex conditional logic belongs in the workflow (not in composites) — full log visibility
 
+### pull_request_target — NEVER checkout fork code
+
+- NEVER use `actions/checkout` with `ref: ${{ github.event.pull_request.head.ref }}` or `ref: ${{ github.event.pull_request.head.sha }}` in `pull_request_target` workflows
+- If `pull_request_target` is needed (e.g., labeling, commenting), it MUST NOT run any code from the fork (no build, no test, no script execution from the PR branch)
+- Prefer `pull_request` trigger over `pull_request_target` unless write permissions to the base repo are explicitly required
+- NEVER use `secrets: inherit` in workflows triggered by `pull_request_target` — it exposes all repository secrets to fork code
+
+### Expression injection — sanitize ALL untrusted inputs
+
+NEVER use these directly in `run:` steps:
+
+```yaml
+# ❌ All of these are injectable — NEVER interpolate directly in run:
+${{ github.event.pull_request.title }}
+${{ github.event.pull_request.body }}
+${{ github.event.issue.title }}
+${{ github.event.issue.body }}
+${{ github.event.comment.body }}
+${{ github.event.head_commit.message }}
+${{ github.event.head_commit.author.name }}
+${{ github.event.commits[*].message }}
+${{ github.event.discussion.title }}
+${{ github.event.discussion.body }}
+${{ github.event.review.body }}
+${{ github.head_ref }}
+${{ github.event.pages[*].page_name }}
+```
+
+If any of these values are needed in a `run:` step, pass them through an environment variable:
+
+```yaml
+# ✅ Safe — shell variable, not template injection
+env:
+  PR_TITLE: ${{ github.event.pull_request.title }}
+run: echo "$PR_TITLE"
+```
+
+### workflow_run — treat artifacts as untrusted
+
+- Workflows triggered by `workflow_run` MUST NOT trust artifacts from the triggering workflow blindly
+- Validate/sanitize any data extracted from artifacts before use in shell commands or API calls
+- Never extract and execute scripts from artifacts without verification
+
+### Permissions — principle of least privilege
+
+- ALWAYS declare explicit `permissions:` block at workflow level
+- Default to `contents: read` — only escalate per-job when needed
+- NEVER use `permissions: write-all` or leave permissions undeclared (defaults to broad access in public repos)
+- For comment/label-only workflows: `permissions: { pull-requests: write }` — nothing else
+
+```yaml
+# ✅ Explicit, minimal permissions
+permissions:
+  contents: read
+
+jobs:
+  comment:
+    permissions:
+      pull-requests: write   # escalated only for this job
+```
+
+### Secrets in fork contexts
+
+- NEVER pass secrets to steps that run fork code
+- `pull_request` from a fork does NOT have access to secrets by default — do not circumvent this
+- If a workflow needs secrets + fork code, split into two workflows:
+  - `pull_request` (no secrets, runs fork code)
+  - `workflow_run` (has secrets, runs trusted code only)
+
+### Script injection via labels/branches
+
+- Validate branch names and label names before using in shell commands
+- Branch names can contain shell metacharacters — always quote variables
+
+```yaml
+# ✅ Always quote branch/label variables
+run: echo "$BRANCH_NAME"
+env:
+  BRANCH_NAME: ${{ github.head_ref }}
+```
+
+### Self-hosted runners
+
+- NEVER use self-hosted runners for `pull_request` or `pull_request_target` from public repos — a fork can execute arbitrary code on the runner
+- Self-hosted runners are only safe for `push`, `workflow_dispatch`, `schedule`, and other non-fork triggers
+
 ### Reserved names — never use as custom secret or input names
 
 GitHub reserves the `GITHUB_*` prefix for all built-in variables and the `ACTIONS_*` prefix for runner internals. Declaring a custom secret or input with these names causes the job to fail silently or be ignored:

.github/workflows/build.yml

@@ -122,14 +122,24 @@ on:
         description: 'Force multi-platform build (amd64+arm64) even for beta/rc tags'
         type: boolean
         default: false
+      docker_build_args:
+        description: 'Newline-separated Docker build arguments to pass to docker build (e.g., "APP_NAME=spi\nCOMPONENT_NAME=api"). Forwarded to docker/build-push-action build-args.'
+        type: string
+        required: false
+        default: ''
       build_context_from_working_dir:
         description: 'Use the component working_dir as Docker build context instead of build_context. Useful for independent modules (e.g., tools with their own go.mod).'
         type: boolean
         default: false
+      enable_cosign_sign:
+        description: 'Sign container images with cosign keyless (OIDC) signing after push. Requires id-token: write permission in the caller.'
+        type: boolean
+        default: true
 
 permissions:
   contents: read
   packages: write
+  id-token: write
 
 jobs:
   prepare:
@@ -283,6 +293,7 @@ jobs:
             type=semver,pattern={{major}},value=${{ steps.version.outputs.version }},enable=${{ needs.prepare.outputs.is_release }}
 
       - name: Build and push Docker image
+        id: build-push
         uses: docker/build-push-action@d08e5c354a6adb9ed34480a06d141179aa583294 # v7
         with:
           context: ${{ inputs.build_context_from_working_dir == true && matrix.app.working_dir || inputs.build_context }}
@@ -291,14 +302,50 @@ jobs:
           push: true
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}
+          build-args: ${{ inputs.docker_build_args }}
           sbom: generator=docker/scout-sbom-indexer:latest
           provenance: mode=max
           cache-from: type=gha
           cache-to: type=gha,mode=max
           secrets: |
             github_token=${{ secrets.MANAGE_TOKEN }}
 
-      # GitOps artifacts for downstream gitops-update workflow
+      # ----------------- Cosign Image Signing -----------------
+      - name: Build cosign image references
+        if: inputs.enable_cosign_sign
+        id: cosign-refs
+        env:
+          DIGEST: ${{ steps.build-push.outputs.digest }}
+          ENABLE_DOCKERHUB: ${{ inputs.enable_dockerhub }}
+          ENABLE_GHCR: ${{ inputs.enable_ghcr }}
+          DOCKERHUB_ORG: ${{ inputs.dockerhub_org }}
+          APP_NAME: ${{ matrix.app.name }}
+          GHCR_ORG: ${{ steps.normalize.outputs.owner_lower }}
+        run: |
+          REFS=""
+
+          if [ "$ENABLE_DOCKERHUB" == "true" ]; then
+            REFS="${DOCKERHUB_ORG}/${APP_NAME}@${DIGEST}"
+          fi
+
+          if [ "$ENABLE_GHCR" == "true" ]; then
+            [ -n "$REFS" ] && REFS="${REFS}"$'\n'
+            REFS="${REFS}ghcr.io/${GHCR_ORG}/${APP_NAME}@${DIGEST}"
+          fi
+
+          {
+            echo "refs<<EOF"
+            echo "$REFS"
+            echo "EOF"
+          } >> "$GITHUB_OUTPUT"
+
+      - name: Sign container images with cosign
+        if: inputs.enable_cosign_sign
+        uses: LerianStudio/github-actions-shared-workflows/src/security/cosign-sign@feat/cosign-sign
+        with:
+          image-refs: ${{ steps.cosign-refs.outputs.refs }}
+
+      # ----------------- GitOps Artifacts -----------------
       - name: Create GitOps tag artifact
         if: inputs.enable_gitops_artifacts
         run: |

.github/workflows/go-release.yml

@@ -67,10 +67,15 @@ on:
         description: 'Enable release notifications'
         type: boolean
         default: false
+      enable_cosign_sign:
+        description: 'Sign container images with cosign keyless (OIDC) signing after push. Requires id-token: write permission in the caller.'
+        type: boolean
+        default: true
 
 permissions:
   contents: write
   packages: write
+  id-token: write
 
 jobs:
   release:
@@ -164,6 +169,7 @@ jobs:
           tags: ${{ inputs.docker_tags }}
 
       - name: Build and push
+        id: build-push
         uses: docker/build-push-action@d08e5c354a6adb9ed34480a06d141179aa583294 # v7
         with:
           context: .
@@ -174,6 +180,24 @@ jobs:
           cache-from: type=gha
           cache-to: type=gha,mode=max
 
+      # ----------------- Cosign Image Signing -----------------
+      - name: Build cosign image references
+        if: inputs.enable_cosign_sign
+        id: cosign-refs
+        env:
+          DIGEST: ${{ steps.build-push.outputs.digest }}
+          DOCKER_REGISTRY: ${{ inputs.docker_registry }}
+          REPOSITORY: ${{ github.repository }}
+        run: |
+          REPO=$(echo "$REPOSITORY" | tr '[:upper:]' '[:lower:]')
+          echo "refs=${DOCKER_REGISTRY}/${REPO}@${DIGEST}" >> "$GITHUB_OUTPUT"
+
+      - name: Sign container images with cosign
+        if: inputs.enable_cosign_sign
+        uses: LerianStudio/github-actions-shared-workflows/src/security/cosign-sign@feat/cosign-sign
+        with:
+          image-refs: ${{ steps.cosign-refs.outputs.refs }}
+
   # Slack notification
   notify:
     name: Notify