fix(security): address CodeRabbit PR#195 review findings

[bedatty]

GitHub Actions Shared Workflows

---

Description

Address all 13 actionable findings from CodeRabbit's review on PR #195. Changes span security hardening (least-privilege permissions, pinned refs), documentation accuracy (scoped cosign verify examples, missing permissions in examples), and rule consistency (cursor rules contradiction).

Workflows affected: build.yml, go-release.yml, typescript-build.yml, pr-security-scan.yml
Docs affected: docs/build-workflow.md, docs/go-release-workflow.md, docs/typescript-build.md, src/security/cosign-sign/README.md
Rules affected: .cursor/rules/reusable-workflows.mdc

Changes

• Least-privilege id-token: write: Moved from workflow-scope to job-scope (build/docker jobs only) in build.yml, go-release.yml, typescript-build.yml — other jobs no longer receive OIDC access
• Pinned cosign-sign ref: Replaced mutable @feat/cosign-sign branch with immutable @v1.23.0 tag in all three build workflows
• Fixed ghcr_org fallback: build.yml cosign-refs step now respects inputs.ghcr_org with fallback to normalized owner
• Scoped --certificate-identity-regexp: Replaced permissive ".*" with LerianStudio-scoped regexp in all cosign verify examples (4 docs)
• Added id-token: write to example: typescript-build.md Basic Example now includes the required OIDC permission
• Qualified image ref: cosign-sign README single-image example now uses docker.io/ prefix
• docker_build_args secret warning: Updated description in build.yml and pr-security-scan.yml to warn against passing secrets via build args
• Fixed workflow_dispatch contradiction: Cursor rules no longer state reusable workflows must support workflow_dispatch

Type of Change

• fix: Bug fix in a workflow (incorrect behavior, broken step, wrong condition)
• perf: Performance improvement (e.g. caching, parallelism, reduced steps)
• refactor: Internal restructuring with no behavior change
• docs: Documentation only (README, docs/, inline comments)
• ci: Changes to self-CI (workflows under .github/workflows/ that run on this repo)
• chore: Dependency bumps, config updates, maintenance
• test: Adding or updating tests
• BREAKING CHANGE: Callers must update their configuration after this PR

Breaking Changes

None. All changes are backwards-compatible:

• id-token: write is now job-scoped but still available to the jobs that need it
• cosign-sign ref points to the same code, just via immutable tag
• ghcr_org fallback preserves existing behavior when input is empty

Testing

• YAML syntax validated locally
• Triggered a real workflow run on a caller repository using @develop or the beta tag
• Verified all existing inputs still work with default values
• Confirmed no secrets or tokens are printed in logs
• Checked that unrelated workflows are not affected

Caller repo / workflow run: N/A — changes are permission scoping, ref pinning, and documentation only.

Related Issues

Addresses review findings from #195

Summary by CodeRabbit

• Documentation

  • Enhanced guidance on handling sensitive values in builds using BuildKit secrets.
  • Updated signature verification patterns for stricter certificate identity validation.
  • Clarified OIDC token permissions requirements for keyless signing workflows.

• Security

  • Tightened cosign certificate identity verification with specific regex patterns.
  • Applied least-privilege permission scoping to workflow jobs.
  • Pinned security action references to specific versions.

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

Walkthrough

Restructured workflow-level OIDC token permissions to job-level scope across multiple GitHub Actions workflows, pinned the cosign signing action to version v1.23.0, tightened certificate identity regexps in verification examples from permissive wildcards to specific GitHub workflow patterns, and clarified security guidance regarding Docker build arguments visibility in image history.

Changes

Cohort / File(s)	Summary
Workflow Permission & Action Restructuring .github/workflows/build.yml, .github/workflows/go-release.yml, .github/workflows/typescript-build.yml	Removed workflow-level permissions.id-token: write, added job-level permissions including id-token: write to respective build/docker jobs. Pinned cosign signing action from @feat/cosign-sign to @v1.23.0. Modified GHCR organization resolution to prioritize explicit input over fallback.
Build Arguments & Security Documentation .github/workflows/build.yml, .github/workflows/pr-security-scan.yml	Updated docker_build_args input descriptions to clarify that build arguments are visible in image history and direct users to use BuildKit secrets for sensitive values instead.
Cosign Verification Documentation docs/build-workflow.md, docs/go-release-workflow.md, docs/typescript-build.md, src/security/cosign-sign/README.md	Tightened --certificate-identity-regexp patterns from permissive .* to restrictive GitHub workflow-specific regex (^https://github.com/LerianStudio/.*/.github/workflows/.*@refs/heads/.*$). Updated example image reference to include explicit docker.io/ registry prefix.
Workflow Convention Updates .cursor/rules/reusable-workflows.mdc	Reversed requirement for workflow_dispatch trigger in reusable workflows; explicitly prohibits it and mandates separate internal .github/workflows/self-* entrypoint workflows for manual dispatch.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	Title accurately reflects the main change: addressing CodeRabbit PR#195 review findings across security, workflows, and documentation.
Description check	✅ Passed	Description fully covers all 13 changes with workflows/docs affected, type selection, testing approach, and clear backwards-compatibility statement.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/coderabbit-pr195-review-findings

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[lerian-studio]

🔍 Lint Analysis

Check	Files Scanned	Status
YAML Lint	4 file(s)	✅ success
Action Lint	4 file(s)	✅ success
Pinned Actions	4 file(s)	✅ success
Markdown Link Check	4 file(s)	✅ success
Spelling Check	9 file(s)	✅ success
Shell Check	4 file(s)	✅ success
README Check	4 file(s)	✅ success
Composite Schema	no changes	⏭️ skipped

---

_{🔍 View full scan logs}

[lerian-studio]

🛡️ CodeQL Analysis Results

Languages analyzed: actions

Found 1 issue(s): 1 Medium

Severity	Rule	File	Message
🟡 Medium	actions/untrusted-checkout/medium	.github/workflows/go-release.yml:127	Potential unsafe checkout of untrusted pull request on privileged workflow.

---

_{🔍 View full scan logs | 🛡️ Security tab}