aiwg 2026.5.3 → 2026.5.4

package/CLAUDE.md

@@ -87,7 +87,7 @@ All 10 providers receive all 4 artifact types (agents, commands, skills, rules).
 | Warp Terminal | `.warp/agents/` + WARP.md | `.warp/commands/` | `.warp/skills/` + `.agents/skills/` | `.warp/rules/` | `aiwg use sdlc --provider warp` |
 | Windsurf | AGENTS.md | `.windsurf/workflows/` | `.windsurf/skills/` + `.agents/skills/` | `.windsurf/rules/` | `aiwg use sdlc --provider windsurf` |
 | OpenClaw | `~/.openclaw/agents/` | `~/.openclaw/commands/` | `~/.openclaw/skills/` + `.agents/skills/` | `~/.openclaw/rules/` | `aiwg use sdlc --provider openclaw` |
-| Hermes | AGENTS.md | — | `~/.hermes/skills/` | — | `aiwg use sdlc --provider hermes` |
+| Hermes | AGENTS.md + .hermes.md | via MCP `command-run` | `~/.hermes/skills/` (kernel) + `~/.hermes/skills/.aiwg/` (standard) | inlined in AGENTS.md + MCP `rule-list`/`rule-show` | `aiwg use sdlc --provider hermes` |
 
 **Special cases:**
 - **Codex**: Commands and skills deploy to home directory (`~/.codex/prompts/`, `~/.codex/skills/`) for user-level availability across all projects. `.codex/commands/` also deploys at project scope for operator visibility, but Codex commands are a static built-in enum in codex-rs and these files are not auto-scanned by the loader; AGENTS.md is the discovery bridge per ADR-1. Reference: `src/smiths/platform-paths.ts:23`.
@@ -95,6 +95,7 @@ All 10 providers receive all 4 artifact types (agents, commands, skills, rules).
 - **Warp**: Agents and commands are also aggregated into `WARP.md` for single-file context loading
 - **Windsurf**: Agents are aggregated into `AGENTS.md` at project root
 - **OpenClaw**: All artifacts deploy to home directory (`~/.openclaw/`). First provider to support behaviors (`~/.openclaw/behaviors/`)
+- **Hermes**: MCP sidecar architecture (`Hermes → MCP → AIWG`). Commands reach AIWG via `mcp_aiwg_command_run` (allow-listed). Standard skills (~385) live under `~/.hermes/skills/.aiwg/` and are recursively discovered; kernel skills (~9) live at the top level and are protected from the Curator (v0.12.0+) via the `.bundled_manifest`. The MCP server has ~12 core tools by default; ~45 additional via `AIWG_MCP_TOOLSETS=<csv>`. See `docs/integrations/hermes-quickstart.md`.
 
 ## Writing Principles
 

package/agentic/code/frameworks/security-engineering/manifest.json

@@ -43,8 +43,8 @@
     "last_updated": "2026-05-13",
     "total_agents": 0,
     "total_commands": 0,
-    "total_skills": 11,
-    "total_rules": 0,
+    "total_skills": 15,
+    "total_rules": 6,
     "status": "active"
   },
   "memory": {

package/agentic/code/frameworks/security-engineering/rules/RULES-INDEX.md

@@ -1,10 +1,10 @@
 # Security Engineering Rules Index
 
-Applied-security enforcement rules for cryptographic primitive choices, chain-of-trust integrity, secret handling, and related design-time concerns. Deployed when the `security-engineering` framework is installed.
+Applied-security enforcement rules for cryptographic primitive choices, chain-of-trust integrity, secret handling, supply-chain pinning, dependency-source policy, and related design-time concerns. Deployed when the `security-engineering` framework is installed.
 
 ---
 
-## Tier 1 Rules (4 rules — applied cryptography)
+## Tier 1 Rules (6 rules — applied cryptography + supply chain)
 
 ### HIGH
 
@@ -32,6 +32,18 @@ Applied-security enforcement rules for cryptographic primitive choices, chain-of
 **Maps to review finding**: H6
 **Full rule**: @$AIWG_ROOT/agentic/code/frameworks/security-engineering/rules/crypto-flag-verification.md
 
+#### ci-action-pinning
+**Summary**: Every CI workflow `uses:` reference MUST be a 40-character commit SHA (not a tag); every `container:`/`image:` reference MUST be `<name>:<tag>@sha256:<digest>`. Tools downloaded via `curl | sh` must record an observed-SHA log and support strict-mode SHA enforcement. Floating tags expose CI to silent supply-chain attacks (Shai-Hulud-class worm propagation). Maintain a pin manifest (`ci/digests.txt` or equivalent) as source of truth for diffs.
+**When to apply**: Any workflow file under `.github/workflows/`, `.gitea/workflows/`, or equivalent; any tool-install step in CI
+**Maps to issue**: #1293 (B3 / Mini Shai-Hulud)
+**Full rule**: @$AIWG_ROOT/agentic/code/frameworks/security-engineering/rules/ci-action-pinning.md
+
+#### dependency-source-policy
+**Summary**: Non-registry dependency sources (`git+`, `github:`, raw tarball URLs, `file:`, `link:`) are PROHIBITED — they bypass registry signature verification and can execute arbitrary code at install time via `prepare` scripts (Mini Shai-Hulud's primary propagation vector). Policy applies to `package.json` AND transitive lockfile entries. Exceptions require an allowlist entry with owner, reason, review_date, and explicit risk acceptance. pnpm workspaces must set `blockExoticSubdeps: true` for workspace-scope enforcement.
+**When to apply**: Any change to `package.json`, `package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`, or `bun.lockb`; CI lint should run on every push
+**Maps to issue**: #1297 (Mini Shai-Hulud follow-up)
+**Full rule**: @$AIWG_ROOT/agentic/code/frameworks/security-engineering/rules/dependency-source-policy.md
+
 ---
 
 ## Quick Reference by Context
@@ -43,7 +55,10 @@ Applied-security enforcement rules for cryptographic primitive choices, chain-of
 | **Multi-key systems** | no-key-reuse-across-purposes, no-adhoc-kdf |
 | **Password handling** | no-adhoc-kdf (Argon2id/PBKDF2 ≥600k) |
 | **CLI crypto invocations** | crypto-flag-verification, no-unauthenticated-encryption |
-| **Reviewing cryptographic decisions** | All four rules in sequence |
+| **CI workflow review** | ci-action-pinning |
+| **Container image references** | ci-action-pinning |
+| **package.json / lockfile review** | dependency-source-policy |
+| **Reviewing cryptographic decisions** | All four crypto rules in sequence |
 
 ---
 
@@ -53,5 +68,5 @@ Future Tier 2 rules will cover authentication-factor architecture, degraded-mode
 
 ---
 
-*Generated from security-engineering framework — 4 rules in Tier 1*
+*Generated from security-engineering framework — 6 rules in Tier 1*
 *Full rule files: @$AIWG_ROOT/agentic/code/frameworks/security-engineering/rules/*

package/agentic/code/frameworks/security-engineering/rules/ci-action-pinning.md

@@ -0,0 +1,145 @@
+# CI Action and Container Pinning
+
+**Enforcement Level**: HIGH
+**Scope**: All CI workflow files (`.github/workflows/`, `.gitea/workflows/`, equivalent) and any `container:` references therein
+**Issue**: #1293
+
+## Principle
+
+CI workflows execute third-party code with broad permissions on every push. A workflow that references `actions/checkout@v4` or `node:24` resolves the reference at run time — the bytes that execute today are not guaranteed to be the bytes that execute tomorrow. Anyone who can move the `v4` tag (a GitHub Action maintainer compromise, a registry account takeover, a published-but-malicious update) silently runs new code in your CI. Pinning by immutable digest closes this attack surface.
+
+This is the same standard AIWG applies to its own CI per [`dev-idempotent-builds.md`](.claude/rules/dev-idempotent-builds.md) rule 2 ("no `:latest` in production"). B3 extends the standard to user projects as a deployable rule.
+
+## Mandatory Rules
+
+### Rule 1: GitHub Actions references pinned by 40-char commit SHA
+
+Every `uses:` reference in a workflow file MUST point at a 40-character commit SHA, not a tag or branch.
+
+**FORBIDDEN**:
+```yaml
+- uses: actions/checkout@v4              # tag — can move
+- uses: actions/checkout@main            # branch — definitely moves
+- uses: actions/checkout@v4.3.1          # version tag — usually immutable but a compromised account can re-point it
+```
+
+**REQUIRED**:
+```yaml
+- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4.3.1
+```
+
+The trailing comment is non-optional. It preserves human-readable diffability without compromising the immutability of the SHA pin.
+
+### Rule 2: Container images pinned by sha256 digest
+
+Every `container:` or `image:` reference in a workflow MUST be `<name>:<tag>@sha256:<digest>`.
+
+**FORBIDDEN**:
+```yaml
+container: node:24
+container: node:latest
+container: node:24-bookworm
+container: ghcr.io/owner/image:v2.1.0
+```
+
+**REQUIRED**:
+```yaml
+container: node:24@sha256:050bf2bbe33c1d6754e060bec89378a79ed831f04a7bb1a53fe45e997df7b3bb  # 24.15.0
+```
+
+The `<name>:<tag>` prefix is retained for human readability; the digest is the trust anchor. Trailing comment captures the resolved version for diff context.
+
+### Rule 3: Pin manifest at `ci/digests.txt` (or equivalent)
+
+Every project that enforces this rule MUST maintain a pin manifest listing each pinned reference, its resolved version, the date pinned, and the rationale. The manifest is the source of truth for diffs — a SHA change without a corresponding manifest entry is a red flag.
+
+Reference manifest format: see AIWG's own [`ci/digests.txt`](https://git.integrolabs.net/roctinam/aiwg/src/branch/main/ci/digests.txt).
+
+Minimum row format:
+```
+<kind>  <name>            <pin>                                          <resolved-version>  <date-pinned>  <update-rationale>
+container  node:24       sha256:050bf2bbe33c1d6754e060bec89378a79ed831f04a7bb1a53fe45e997df7b3bb  24.15.0  2026-05-12  initial pin
+action  actions/checkout  93cb6efe18208431cddfb8368fd83d5badbf9bfd       v5.0.1              2026-05-12  initial pin
+```
+
+### Rule 4: Pin bumps go through review
+
+Every pin update is a reviewable change. The commit should:
+- Reference the issue or advisory motivating the bump (CVE, needed feature, scheduled rotation)
+- Update the manifest row in the same commit as the workflow file edit
+- Include `chore(ci): bump <name> pin to <version> (refs #<issue>)` style commit message
+
+Workflow diffs that change a digest without a corresponding manifest update fail review.
+
+### Rule 5: Standalone tools pinned by version + checksum
+
+Tools downloaded by `curl | sh` or equivalent in CI (e.g., `syft install.sh`, ad-hoc binary releases) MUST pin a specific version AND record the installer's content hash. The version pin gives reproducibility; the content hash detects upstream tampering.
+
+**Acceptable pattern** (strict-mode opt-in, with observed-SHA logging):
+```yaml
+- name: Install syft
+  run: |
+    VERSION=v1.18.0
+    EXPECTED_INSTALL_SHA=""  # populate after first run; logs `observed` SHA
+    SCRIPT=$(curl -fsSL "https://raw.githubusercontent.com/anchore/syft/${VERSION}/install.sh")
+    OBSERVED_SHA=$(printf '%s' "$SCRIPT" | sha256sum | awk '{print $1}')
+    echo "observed install-script SHA: ${OBSERVED_SHA}"
+    if [ -n "$EXPECTED_INSTALL_SHA" ] && [ "$OBSERVED_SHA" != "$EXPECTED_INSTALL_SHA" ]; then
+      echo "✗ install-script SHA drift — refusing to execute"
+      exit 1
+    fi
+    printf '%s' "$SCRIPT" | sh -s -- -b /usr/local/bin "$VERSION"
+```
+
+## Detection Patterns
+
+CI lint should flag the following:
+
+```bash
+# Floating action tags
+grep -rE '^\s*-\s*uses:\s*[a-zA-Z0-9._-]+/[a-zA-Z0-9._-]+@(v?[0-9]+(\.[0-9]+)*|main|master|latest)\s*(#.*)?$' \
+  .github/workflows/ .gitea/workflows/ 2>/dev/null
+
+# Unpinned container images
+grep -rE '^\s*(container|image):\s*[a-zA-Z0-9._/-]+:[a-zA-Z0-9._-]+\s*(#.*)?$' \
+  .github/workflows/ .gitea/workflows/ 2>/dev/null \
+  | grep -v 'sha256:'
+
+# Bare :latest anywhere
+grep -rnE ':latest\b' .github/workflows/ .gitea/workflows/ 2>/dev/null
+
+# Curl-pipe-shell installers without a content hash check
+grep -rnE 'curl[^|]+\|\s*(bash|sh)' .github/workflows/ .gitea/workflows/ 2>/dev/null
+```
+
+Wire these into a `npm run lint:ci-pins` script (or equivalent) and call it from the CI workflow itself so the rule is self-enforcing.
+
+## Acceptable Exceptions
+
+The following are NOT subject to this rule:
+
+1. **Dockerfile `FROM` instructions in build stages** that are NOT consumed by CI directly — those are governed by the project's image-build pipeline (which should follow the same standard, but the rule lives in the Dockerfile review, not the workflow review).
+2. **Ephemeral self-hosted runners** that pull pre-baked AMIs/images with their own attestation chain — the chain-of-trust is at the AMI level, not the workflow level.
+3. **Reusable workflows from the same repository** (`uses: ./.github/workflows/foo.yml`) — these are pinned to the repository state at the calling commit.
+4. **Build-arg substitutions for the same digest** — `FROM ${BASE_IMAGE}` where `BASE_IMAGE` is built from a digest-pinned reference one level up.
+
+Document any other exception in a code comment adjacent to the unpinned reference, with reasoning and an issue link tracking eventual migration to a pin.
+
+## Rationale
+
+The mutable-tag attack surface is one of the largest unaddressed components of npm-ecosystem supply-chain risk as of 2026. The recent Shai-Hulud worm campaign demonstrated that compromised maintainer accounts can push malicious updates that propagate via floating version tags within hours. Workflows pinned by SHA stop that propagation at the boundary of every individual project that pins.
+
+Pin-bump cost is low (one curl/git ls-remote command); incident cost from an unpinned dependency executing in CI with secret access is high. The asymmetry justifies the rule.
+
+## References
+
+- [`dev-idempotent-builds.md`](.claude/rules/dev-idempotent-builds.md) — base rule on reproducible builds
+- AIWG's own pin manifest: `ci/digests.txt`
+- Defenses brief C7 (action pinning) and C8 (container pinning)
+- Shai-Hulud worm post-mortem references
+- GitHub Actions documentation: pinning third-party actions to a full-length commit SHA
+
+---
+
+**Rule Status**: ACTIVE
+**Last Updated**: 2026-05-13

package/agentic/code/frameworks/security-engineering/rules/dependency-source-policy.md

@@ -0,0 +1,177 @@
+# Dependency Source Policy
+
+**Enforcement Level**: HIGH
+**Scope**: `package.json` and lockfile (`package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`, `bun.lockb`) — direct AND transitive entries
+**Issue**: #1297
+
+## Principle
+
+Non-registry dependency sources (`git+`, `github:`, raw tarball URLs, `file:`, `link:`) bypass registry signature verification AND can execute arbitrary code during install via lifecycle scripts (especially `prepare`). The May 2026 Mini Shai-Hulud campaign's primary propagation vector was an `optionalDependencies` entry sourced from `git+https://...attacker-repo` whose `prepare` script ran during every `npm install` of any project that pulled in the affected package.
+
+Registry-hosted tarballs (`registry.npmjs.org/.../foo.tgz`, `registry.yarnpkg.com/...`, `npm.pkg.github.com/...`) are fine — they're the normal `resolved` URL format `npm install` emits for every registry-published dep. The policy only flags non-registry sources.
+
+Companion to [`ci-action-pinning`](ci-action-pinning.md) (CI execution-environment trust) and the per-package-manager release-age-gate skills (which gate freshly-published registry versions). Together they cover the three primary supply-chain attack vectors: CI environment poisoning, registry-version poisoning, and direct dep-source injection.
+
+## Mandatory Rules
+
+### Rule 1: Six dep-source patterns are forbidden by default
+
+Every dep in `package.json` AND every entry in the lockfile (including transitive) MUST be a registry-published version reference. The following patterns are blocked:
+
+| Pattern | Example | Reason |
+|---|---|---|
+| `git+*` scheme | `"foo": "git+https://github.com/owner/foo.git"` | npm clones the repo and runs its `prepare` script — arbitrary code execution at install time |
+| `git://` scheme | `"foo": "git://github.com/owner/foo.git"` | Same as above |
+| `github:` shorthand | `"foo": "github:owner/foo"` | Same as above; npm expands to git+ |
+| Non-registry tarball | `"foo": "https://example.com/foo-1.0.0.tgz"` | Tarball can contain any payload and lifecycle scripts; bypasses registry signature verification |
+| `file:` path | `"foo": "file:./vendor/foo"` | Local-path deps bypass dep-resolution review and lockfile signature checks |
+| `link:` symlink | `"foo": "link:./packages/foo"` | Follows the symlink target wherever it points; same gaps as `file:` |
+
+Registry-hosted patterns that are ALWAYS acceptable:
+
+- `"foo": "^1.2.3"` — registry semver range
+- `"foo": "1.2.3"` — exact registry version
+- `"foo": "npm:@scope/foo@^1.2.3"` — aliased registry dep
+- Lockfile `"resolved": "https://registry.npmjs.org/..."` — registry-served tarball
+
+### Rule 2: Exceptions require an allowlist entry
+
+If a legitimate non-registry source exists (e.g., temporary fork pending upstream merge, monorepo-internal `file:` link with a known security boundary), it MUST be allowlisted with:
+
+- **Owner** — who took the risk-acceptance decision
+- **Reason** — why a registry version isn't viable today
+- **Expiry / review date** — when this exception must be re-evaluated (max 1 year)
+- **Risk acceptance** — explicit statement that the operator accepts the dep-source bypass
+
+Allowlist file format (committed at `.aiwg/security/dep-source-allowlist.yaml` or equivalent):
+
+```yaml
+allowlist:
+  - dep: "foo"
+    source: "git+https://github.com/owner/foo.git#sha-or-tag"
+    owner: "alice@example.org"
+    reason: "Upstream PR #123 not yet merged; we need fix from main for issue X"
+    review_date: "2026-08-01"
+    risk_acceptance: "Source pinned to commit SHA; reviewed prepare script line-by-line; no shell exec in install path"
+  - dep: "@internal/shared"
+    source: "file:./packages/shared"
+    owner: "bob@example.org"
+    reason: "Monorepo-internal package; not published to registry"
+    review_date: "2027-01-01"
+    risk_acceptance: "Source within same security boundary as host package; no external code path"
+```
+
+Allowlist entries beyond their `review_date` are treated as policy violations.
+
+### Rule 3: Lockfile entries are policy targets
+
+Direct deps in `package.json` are easy to spot. Transitive entries in the lockfile are the actual attack surface — Mini Shai-Hulud propagated via transitive `optionalDependencies` with exotic sources. The CI lint MUST scan the lockfile for the same patterns, including:
+
+- `"resolved": "git+..."` in `package-lock.json`
+- `tarball: ...` URLs in `pnpm-lock.yaml` that don't match a registry origin
+- `resolution: ` blocks in `yarn.lock`
+- Binary lockfile (`bun.lockb`) — extract via `bun pm ls --all` and pattern-match the output
+
+### Rule 4: pnpm workspaces enable `blockExoticSubdeps`
+
+When pnpm is the package manager, the workspace MUST set `blockExoticSubdeps: true` (in `pnpm-workspace.yaml`) or the per-repo equivalent in `.npmrc`:
+
+```yaml
+# pnpm-workspace.yaml
+packages:
+  - 'packages/*'
+blockExoticSubdeps: true
+```
+
+This is the pnpm advantage over npm: workspace-scope enforcement that npm has no equivalent for. The `pnpm-release-age-gate` skill documents the wiring.
+
+### Rule 5: Failure messages point to remediation
+
+When CI rejects a violation, the failure message MUST:
+
+1. State which dep and which source pattern matched
+2. Reference the operator's choices: switch to a registry version, request an allowlist entry, or accept install-time compromise risk
+3. Link to this rule (or the project's adaptation of it) so the receiving developer can read the policy
+
+Reference failure-message format (from AIWG's own `tools/lint/dep-source.mjs`):
+
+```
+✗ Dependency source policy violation
+
+  foo (in package.json)
+    source: git+https://github.com/owner/foo.git
+    pattern: git+ scheme
+
+  This dependency source bypasses registry signature verification and
+  executes arbitrary code at install time via the prepare script.
+
+  Options:
+    1. Switch to a registry-published version: npm install foo@<version>
+    2. Add an allowlist entry: see .aiwg/security/dep-source-allowlist.yaml
+    3. Read the policy: docs/contributing/dependency-sources.md
+```
+
+## Detection Patterns
+
+```bash
+# package.json — direct deps with exotic sources
+node -p "
+  const p = require('./package.json');
+  const all = {...p.dependencies, ...p.devDependencies, ...p.optionalDependencies, ...p.peerDependencies};
+  for (const [name, source] of Object.entries(all || {})) {
+    if (/^(git\+|git:|github:|file:|link:)/.test(source) ||
+        (/^https?:\/\//.test(source) && /\.tgz/.test(source))) {
+      console.log(name, '=', source);
+    }
+  }
+"
+
+# package-lock.json — transitive entries with exotic resolved URLs
+node -p "
+  const lock = require('./package-lock.json');
+  function walk(pkgs, prefix = '') {
+    for (const [path, entry] of Object.entries(pkgs || {})) {
+      if (entry.resolved && /^(git\+|git:)/.test(entry.resolved)) {
+        console.log(prefix + path, '=', entry.resolved);
+      }
+    }
+  }
+  walk(lock.packages);
+"
+
+# pnpm-lock.yaml — exotic resolution blocks
+grep -E 'resolution:\s*\{(git|tarball:.*[^.]https?://[^/]+/[^.]*\.tgz)' pnpm-lock.yaml 2>/dev/null
+
+# yarn.lock — exotic resolved entries
+grep -E '"?resolved"?\s*"?:?\s*"?(git\+|git:)' yarn.lock 2>/dev/null
+```
+
+Reference implementation: AIWG's own [`tools/lint/dep-source.mjs`](https://git.integrolabs.net/roctinam/aiwg/src/branch/main/tools/lint/dep-source.mjs) — runs `npm run lint:dep-sources` and exits non-zero on any violation.
+
+## Acceptable Exceptions
+
+Three exception categories beyond explicit allowlist entries:
+
+1. **Monorepo workspace links** — `file:` or `link:` deps between packages in the same `pnpm-workspace.yaml` / `lerna.json` / `nx.json` / `package.json workspaces` configuration. These are within the same security boundary; flag as INFO only.
+2. **Lockfile resolved-URL prefixes that look exotic but ARE registry URLs** — e.g., `https://registry.npmjs.org/...` matches `^https://` but is a registry origin. The detection logic above already excludes these correctly by checking the host.
+3. **Dev-only deps for build tooling that consume only `package.json`-declared scripts** — debatable; recommend treating as standard policy violations and using allowlist entries for the temporary cases.
+
+## Rationale
+
+Mini Shai-Hulud demonstrated that a single transitive `optionalDependencies` entry from a compromised maintainer can propagate a `prepare`-script payload to every downstream `npm install`. The registry's "this version was published by an authenticated maintainer" guarantee is the foundation of `npm audit signatures`; non-registry sources bypass that guarantee entirely.
+
+Cost of compliance is low (most deps are already registry-published). Cost of a single exotic-source incident is high (full secret-rotation cycle, downstream user trust loss, potential CVE assignment). The asymmetry justifies the rule.
+
+## References
+
+- [`ci-action-pinning`](ci-action-pinning.md) — CI execution-environment trust (companion rule)
+- AIWG's lint implementation: [`tools/lint/dep-source.mjs`](https://git.integrolabs.net/roctinam/aiwg/src/branch/main/tools/lint/dep-source.mjs)
+- AIWG's contributor doc: [`docs/contributing/dependency-sources.md`](https://git.integrolabs.net/roctinam/aiwg/src/branch/main/docs/contributing/dependency-sources.md)
+- ADR: `.aiwg/architecture/adr-dep-source-policy.md` (in AIWG's own repo)
+- pnpm `blockExoticSubdeps`: <https://pnpm.io/settings#blockexoticsubdeps>
+- Mini Shai-Hulud post-mortem references
+
+---
+
+**Rule Status**: ACTIVE
+**Last Updated**: 2026-05-13

package/agentic/code/frameworks/security-engineering/skills/bun-release-age-gate/SKILL.md

@@ -0,0 +1,193 @@
+---
+namespace: aiwg
+name: bun-release-age-gate
+platforms: [all]
+description: Configure Bun's install.minimumReleaseAge gate (7-day default, 10-day high-sensitivity) for JavaScript projects on Bun. Includes Corepack-equivalent version detection and lockfile-caveat warning.
+---
+
+# bun-release-age-gate
+
+Use this skill when a user has chosen Bun as their JavaScript runtime
+and package manager and wants release-age-gate hardening parallel to
+what `npm-release-age-gate`, `pnpm-release-age-gate`, and
+`yarn-release-age-gate` provide for their respective ecosystems.
+
+## Triggers
+
+- "bun release age gate"
+- "bun minimumReleaseAge"
+- "bun supply chain hardening"
+- "bun install hardening"
+
+## Prerequisites
+
+- Bun v1.1.30+ installed (`bun --version`)
+- `package.json` exists at repo root
+- `bunfig.toml` exists (or will be created) — Bun's config file
+
+If Bun is below v1.1.30, the skill should refuse to proceed:
+`install.minimumReleaseAge` was introduced in v1.1.30 and earlier
+versions silently ignore it.
+
+## Configuration
+
+Add the gate to `bunfig.toml` at repo root:
+
+```toml
+[install]
+# Refuse dependency versions published less than 7 days ago.
+# Bun interprets the value in SECONDS. 604800 = 7 days; 864000 = 10 days.
+# Defends against newly-published malicious versions.
+minimumReleaseAge = 604800
+
+# Optional: reject git+ and tarball-URL sources during install
+# (Bun's equivalent of pnpm's blockExoticSubdeps — check current
+# version's docs for the exact key name; the API is evolving)
+# safeRegistry = true
+```
+
+## Unit conversion reference
+
+Bun uses **seconds** for `install.minimumReleaseAge`:
+
+| Days | Seconds value |
+|---|---|
+| 1 | `86400` |
+| 7 (recommended default) | `604800` |
+| 10 (high-sensitivity profile) | `864000` |
+| 14 | `1209600` |
+| 30 | `2592000` |
+
+This differs from npm (**days**), pnpm (**minutes**), and Yarn
+(**duration string** like `7d`). Document the unit inline when
+committing the config so future readers don't misread it.
+
+## Lockfile caveat
+
+The gate is checked at resolution time. If `bun.lockb` was generated
+without the gate, the gate applies on the NEXT resolution pass — not
+retroactively against the existing lockfile.
+
+To apply the gate retroactively:
+
+```bash
+# Force re-resolution
+rm bun.lockb
+bun install
+```
+
+This is destructive to existing pins. Coordinate before running.
+
+## Version detection (Corepack-equivalent)
+
+Bun is not currently in the Corepack supported set, but version
+pinning is still important. The `packageManager` field in
+`package.json` can pin Bun:
+
+```bash
+node -p "require('./package.json').packageManager"
+```
+
+If the value is `bun@<version>`, that's the pinned version (CI
+should use this). If empty, recommend setting it:
+
+```json
+{
+  "packageManager": "bun@1.1.30"
+}
+```
+
+The skill should:
+
+1. Confirm pinned version is ≥ v1.1.30 (else flag — gate is silently ignored)
+2. Document the pinned version
+3. If unpinned, suggest pinning before applying the gate
+
+## Override policy
+
+Genuine emergency overrides:
+
+```bash
+# Bypass the gate for a single install (rare)
+bun add <pkg> --minimum-release-age=0
+```
+
+Document every override with reason + sunset date.
+
+## CI integration
+
+Add a verification step to the publish/build workflow:
+
+```yaml
+- name: Verify Bun gate active
+  run: |
+    set -euo pipefail
+    GATE=$(grep -E '^\s*minimumReleaseAge\s*=' bunfig.toml | awk -F'=' '{print $2}' | tr -d ' ')
+    if [ -z "$GATE" ] || [ "$GATE" -lt 604800 ]; then
+      echo "✗ Bun install.minimumReleaseAge not configured to baseline (≥604800 = 7 days)"
+      exit 1
+    fi
+    echo "✓ Bun install.minimumReleaseAge = $GATE seconds"
+```
+
+## What to inspect during review
+
+- `bunfig.toml` for `[install] minimumReleaseAge`
+- `package.json` `packageManager` field for Bun version pin
+- CI workflow has the verification step above
+- `bun.lockb` was generated AFTER the gate was committed (timestamp check)
+
+## Output format
+
+When auditing an existing Bun project, produce a structured report
+at `.aiwg/security/working/bun-release-age-audit.md`:
+
+```markdown
+# Bun Release-Age Gate Audit
+
+**Bun version**: <version>  (Pinned in package.json: yes/no)
+**Gate active**: yes (604800s) / yes (864000s) / yes (custom: <value>) / no
+
+## Findings
+
+### <severity> — <description>
+
+- File: <path>
+- Issue: <what's wrong>
+- Fix: <exact change>
+
+## Clean Checks
+
+- ...
+
+## Recommendations
+
+- ...
+```
+
+## Bun-specific notes
+
+Bun's install API is younger than npm/pnpm/Yarn — settings names have
+changed across versions. The skill should:
+
+- Check the installed Bun version's docs for the canonical setting name
+- If `install.minimumReleaseAge` isn't recognized by the installed
+  version, fall back to checking for older keys (`minReleaseAge`,
+  `releaseAge`) and recommend upgrade
+
+When in doubt, run `bun pm --help` and `bun install --help` to
+discover the current supported flags.
+
+## See Also
+
+- [`npm-release-age-gate` skill](../npm-release-age-gate/SKILL.md) — npm equivalent
+- [`pnpm-release-age-gate` skill](../pnpm-release-age-gate/SKILL.md) — pnpm equivalent
+- [`yarn-release-age-gate` skill](../yarn-release-age-gate/SKILL.md) — Yarn equivalent
+- [`npm-supply-chain-audit` skill](../npm-supply-chain-audit/SKILL.md) — companion audit
+- [`supply-chain-hardening-quickstart` skill](../supply-chain-hardening-quickstart/SKILL.md) — orchestrator
+
+## References
+
+- Bun install settings: <https://bun.com/docs/runtime/bunfig#install>
+- Bun `bunfig.toml` reference: <https://bun.com/docs/runtime/bunfig>
+- Bun release notes for `minimumReleaseAge` introduction: check Bun changelog for v1.1.30