ci: harden Scorecard and add CodeQL

.github/workflows/codeql.yml

@@ -0,0 +1,43 @@
+# CodeQL static analysis workflow.
+# Author: Admilson B. F. Cossa
+# SPDX-License-Identifier: Apache-2.0
+
+name: CodeQL
+
+on:
+  workflow_dispatch:
+  pull_request:
+    branches:
+      - main
+  push:
+    branches:
+      - main
+  schedule:
+    - cron: "37 4 * * 1"
+
+permissions:
+  contents: read
+
+jobs:
+  analyze:
+    name: CodeQL analysis
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      security-events: write
+    strategy:
+      fail-fast: false
+      matrix:
+        language:
+          - javascript-typescript
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@68bde559dea0fdcac2102bfdf6230c5f70eb485e
+        with:
+          languages: ${{ matrix.language }}
+
+      - name: Analyze
+        uses: github/codeql-action/analyze@68bde559dea0fdcac2102bfdf6230c5f70eb485e

.github/workflows/scorecard.yml

@@ -11,13 +11,15 @@ on:
 
 permissions:
   contents: read
-  id-token: write
-  security-events: write
 
 jobs:
   scorecard:
     name: Scorecard analysis
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+      security-events: write
     steps:
       - name: Run Scorecard
         uses: ossf/scorecard-action@f49aabe0b5af0936a0987cfb85d86b75731b0186

OPENSSF-BEST-PRACTICES.md

@@ -0,0 +1,78 @@
+<!--
+Author: Admilson B. F. Cossa
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# OpenSSF Best Practices Process
+
+WorkIt uses the OpenSSF Best Practices badge as a public supply-chain hygiene
+checklist. The badge must not be shown as passing until the project entry exists
+and the checklist is complete.
+
+## Goal
+
+Use the OpenSSF Best Practices process to verify and document:
+
+- public source availability
+- Apache-2.0 licensing
+- security policy and private vulnerability reporting
+- reproducible verification commands
+- CI on pull requests and `main`
+- dependency update automation
+- vulnerability auditing
+- static analysis
+- signed releases and npm provenance
+- package contents discipline
+
+## Required Public Evidence
+
+Before claiming badge status, verify these repository facts:
+
+```sh
+npm run verify
+npm run test:coverage
+npm run test:evidence
+npm run bench:articles
+npm pack --dry-run --json
+```
+
+The public evidence files are:
+
+```txt
+README.md
+SECURITY.md
+CONTRIBUTING.md
+CODE_OF_CONDUCT.md
+LICENSE
+evidence/claims.json
+evidence/README.md
+benchmarks/results/articles.latest.json
+.github/workflows/ci.yml
+.github/workflows/codeql.yml
+.github/workflows/scorecard.yml
+.github/workflows/release-provenance.yml
+.github/dependabot.yml
+```
+
+## External Badge Steps
+
+1. Create the WorkIt project entry at the OpenSSF Best Practices site.
+2. Fill in the public repository URL: `https://github.com/WorkRuntime/workit`.
+3. Link the security policy: `SECURITY.md`.
+4. Link the license: `LICENSE`.
+5. Link the CI workflow and verification commands.
+6. Link the CodeQL workflow after the first successful run.
+7. Link the release provenance workflow and the latest GitHub release.
+8. Record any checklist items that are intentionally deferred.
+9. Add the badge to `README.md` only after the badge URL exists.
+
+## Deferred Items
+
+These checks require project maturity or a deliberate future feature:
+
+- broader contributor diversity
+- long-term maintenance age
+- recognized fuzzing integration
+- external security review
+
+Do not fake these items. Track them as roadmap work until real evidence exists.

SECURITY.md

@@ -63,17 +63,22 @@ npm pack --dry-run --json
 ```
 
 The provenance workflow is defined in `.github/workflows/release-provenance.yml`.
-Registry dry-runs and real publication are intentionally blocked while
-`package.json` has `private: true`. Final release requires a separate scoped
-commit that proves `@workit` npm scope ownership, flips `private` to `false`,
-and runs:
+Registry dry-runs and real publication must be triggered only from a signed
+release tag after the scoped release commit is clean and verified. The publish
+step runs:
 
 ```sh
 npm publish --provenance --access public --dry-run
 ```
 
-The package must not publish source maps, local docs, tests, secrets, temporary
-files, debug output, or private agent instructions.
+for dry runs, and:
+
+```sh
+npm publish --provenance --access public
+```
+
+for an approved release. The package must not publish source maps, local docs,
+tests, secrets, temporary files, debug output, or private agent instructions.
 
 Release tags must be signed. The release operator must create the version tag
 only after the scoped release commit is clean and verified:
@@ -85,6 +90,14 @@ git tag -v vX.Y.Z
 
 Unsigned release tags are not valid release evidence.
 
+## OpenSSF Best Practices
+
+The OpenSSF Best Practices badge is tracked as a public supply-chain hygiene
+process, not as a marketing badge. The project must not claim a passing badge
+until the external OpenSSF checklist is completed and the project entry exists.
+
+The process is documented in `OPENSSF-BEST-PRACTICES.md`.
+
 ## Responsible Disclosure Scope
 
 Reports are in scope when they affect: