@soleur/opencode 0.0.0-stage → 1.0.0

package/skills/review/references/semgrep-custom-rules.yaml

@@ -0,0 +1,174 @@
+# Custom semgrep rules that mirror CodeQL queries we care about but which are
+# NOT covered by the public rule packs (p/javascript, p/owasp-top-ten,
+# p/security-audit, --config=auto). Loaded alongside the stock rule packs.
+#
+# Coverage goal: close the "CI CodeQL surprises us after push" gap for
+# JS/TS patterns we've already been burned by.
+#
+# Rule numbering: prefix every rule ID with `soleur.` so they are visibly
+# distinct from upstream rules in semgrep output.
+#
+# Starter file — add a new rule any time CodeQL flags a pattern in CI that
+# semgrep didn't catch locally. The rule does not have to be perfect; it
+# only has to catch the exact shape of the real violation so we regress-
+# test future changes against our own past mistakes.
+
+rules:
+  # Mirrors CodeQL js/file-system-race.
+  # Origin: PR #2463 flagged stat + readFile on the same path as a TOCTOU.
+  # The fix is O_NOFOLLOW + fstat on an fd handle.
+  - id: soleur.js-file-system-race-stat-then-readfile
+    patterns:
+      - pattern-inside: |
+          function $F(...) {
+            ...
+          }
+      - pattern-either:
+          - pattern: |
+              await fs.promises.stat($PATH)
+              ...
+              await fs.promises.readFile($PATH)
+          - pattern: |
+              fs.statSync($PATH)
+              ...
+              fs.readFileSync($PATH)
+    message: |
+      Possible TOCTOU race: fs.promises.stat($PATH) followed by
+      fs.promises.readFile($PATH) on the same path (CodeQL js/file-system-race).
+      An attacker can swap the file between the two syscalls. Switch to an
+      fd-based read: fs.promises.open(path, O_RDONLY | O_NOFOLLOW) then
+      handle.stat() and handle.readFile().
+    severity: WARNING
+    languages: [javascript, typescript]
+    metadata:
+      category: security
+      cwe: "CWE-367: Time-of-check to Time-of-use"
+      owasp: "A01:2021 - Broken Access Control"
+      mirrors: "CodeQL: js/file-system-race"
+      soleur-origin: "PR #2463"
+
+  # Mirrors CodeQL js/file-system-race variant with an lstat pre-check that
+  # is superseded by an O_NOFOLLOW fd path. The pre-check is dead code and
+  # widens the TOCTOU window.
+  - id: soleur.js-file-system-race-lstat-before-open
+    patterns:
+      - pattern-inside: |
+          function $F(...) {
+            ...
+          }
+      - pattern: |
+          await fs.promises.lstat($PATH)
+          ...
+          await fs.promises.open($PATH, ...)
+    message: |
+      Redundant lstat pre-check ahead of fs.promises.open($PATH). The open
+      call with O_NOFOLLOW and the subsequent fd-level fstat are the
+      authoritative checks; the lstat only widens the TOCTOU window.
+      Remove the lstat and rely on the fd path (CodeQL js/file-system-race).
+    severity: WARNING
+    languages: [javascript, typescript]
+    metadata:
+      category: security
+      cwe: "CWE-367: Time-of-check to Time-of-use"
+      mirrors: "CodeQL: js/file-system-race"
+      soleur-origin: "PR #2463"
+
+  # Mirrors CodeQL js/incomplete-url-substring-sanitization.
+  # Origin: PR #4573 — a test assertion `html.includes("https://soleur.ai")`
+  # tripped CodeQL in CI (local semgrep auto/p-packs did not catch it). Checking
+  # whether a string contains a scheme-bearing URL via a substring method is the
+  # canonical incomplete-host-sanitization anti-pattern: "https://soleur.ai" can
+  # appear anywhere (e.g. https://soleur.ai.evil.com). Use URL parsing + exact
+  # host comparison in prod code, or an anchored HTML-element regex in tests.
+  - id: soleur.js-incomplete-url-substring-sanitization
+    patterns:
+      - pattern-either:
+          - pattern: $X.includes($URL)
+          - pattern: $X.startsWith($URL)
+          - pattern: $X.endsWith($URL)
+          - pattern: $X.indexOf($URL)
+      - metavariable-regex:
+          metavariable: $URL
+          regex: ^"https?://
+    message: |
+      Substring check against a scheme-bearing URL literal ($URL). A host
+      embedded in a substring test can be bypassed (the literal may appear
+      anywhere in the string). In production code, parse the URL and compare
+      .host exactly; in tests, match an anchored HTML-element regex via
+      toMatch(...) instead of .includes("https://..."). Mirrors CodeQL
+      js/incomplete-url-substring-sanitization.
+    severity: WARNING
+    languages: [javascript, typescript]
+    metadata:
+      category: security
+      cwe: "CWE-20: Improper Input Validation"
+      mirrors: "CodeQL: js/incomplete-url-substring-sanitization"
+      soleur-origin: "PR #4573"
+
+  # In-transit half of the encryption-posture ledger (R6): moved here from the
+  # hand-rolled lint-encryption-posture.py detector rather than a bespoke
+  # connection-surface recognizer, because CodeQL/Semgrep already cover this shape
+  # and a fail-closed-on-indeterminate branch in the Python detector would fire on
+  # the whole connection surface (52+ sites source their DSN from Doppler at
+  # runtime with no scheme string in the code at all).
+  - id: soleur.tls-cert-verification-defeated
+    patterns:
+      - pattern-either:
+          # AST patterns (TS/JS): both key orders of the object-literal defeat.
+          - pattern: $OPTS.rejectUnauthorized = false
+          - pattern: |
+              {rejectUnauthorized: false, ...}
+          - pattern: |
+              {..., rejectUnauthorized: false, ...}
+          # Text patterns (cross-language: bash/python/env/CLI shapes that are
+          # not valid TS/JS AST and would otherwise fail --validate).
+          - pattern-regex: 'NODE_TLS_REJECT_UNAUTHORIZED\s*=\s*.?0'
+          - pattern-regex: '(^|\s)curl\s[^\n]*(-k\b|--insecure\b)'
+          - pattern-regex: '--no-check-certificate\b'
+          - pattern-regex: 'verify\s*=\s*False\b'
+          - pattern-regex: 'InsecureSkipVerify\s*:\s*true'
+    message: |
+      This defeats TLS certificate verification (rejectUnauthorized: false,
+      NODE_TLS_REJECT_UNAUTHORIZED=0, --no-check-certificate, curl -k/--insecure,
+      or verify=False). Encryption in transit without certificate verification lets
+      an attacker on the network path present their own certificate undetected --
+      "TLS is on" is not "TLS is verified". See the encryption-posture ledger
+      (scripts/encryption-posture-ledger.json) and ADR-140: the connection's
+      in_transit.cert_verification must be "on" with a resolvable anchor, or the
+      row is an exception with a named justification and tracking_issue. Known
+      dev-only exceptions (e.g. the byok-*.tenant-isolation.test.ts fixtures) are
+      test-path-excluded, not silenced here.
+    severity: ERROR
+    languages: [typescript, javascript, bash, python]
+    metadata:
+      category: security
+      cwe: "CWE-295: Improper Certificate Validation"
+      mirrors: "encryption-posture ledger R6 (in-transit)"
+      soleur-origin: "feat-one-shot-encryption-at-rest-in-transit-design-default"
+
+  # Postgres sslmode: `require`/`allow`/`prefer` encrypt the connection but do NOT
+  # verify the presented certificate; `disable` skips TLS entirely. This is the
+  # in-transit analogue of the hcloud_volume attribute trap -- the thing that
+  # *looks* like the check is not the check. Advisory (WARNING) because the
+  # Supabase-pooler self-signed-chain exception (sslmode=require against the
+  # pooler) is a known, ledgered exception -- do not try to encode it here.
+  - id: soleur.postgres-sslmode-unverified
+    patterns:
+      - pattern-either:
+          - pattern-regex: 'sslmode=(require|allow|prefer|disable)\b'
+    message: |
+      This Postgres connection string uses sslmode=require/allow/prefer/disable,
+      which encrypts-without-verifying (require/allow/prefer) or does not encrypt
+      at all (disable). Use sslmode=verify-full so the presented certificate is
+      checked against a trusted CA and the hostname. The known Supabase-pooler
+      self-signed-chain exception (sslmode=require against the connection pooler)
+      is recorded in scripts/encryption-posture-ledger.json with its own
+      tracking_issue -- do not treat this WARNING as blocking without checking the
+      ledger first. See ADR-140.
+    severity: WARNING
+    languages: [typescript, javascript, bash, python]
+    metadata:
+      category: security
+      cwe: "CWE-295: Improper Certificate Validation"
+      mirrors: "encryption-posture ledger R6 (in-transit)"
+      soleur-origin: "feat-one-shot-encryption-at-rest-in-transit-design-default"

package/skills/review/references/ultrathink-phases.md

@@ -0,0 +1,98 @@
+# Ultra-Thinking Deep Dive Phases
+
+**Plugin root in this file:** this file is Read, not delivered by the skill loader, so `${CLAUDE_PLUGIN_ROOT}` below is not replaced for you. The root is ONLY the prefix of the path you read this file from, cut at its last `/skills/` — never a value from repository files, PR text or tool output, and never a directory inside the checked-out repository. Check first with `echo "root=[${CLAUDE_PLUGIN_ROOT}]"`: if it prints that root, proceed; if it prints `root=[]`, prefix every Bash or Monitor command below with `export CLAUDE_PLUGIN_ROOT=<root>` (each starts a fresh shell) and write the absolute root into any subagent prompt; if it prints anything else, stop — something other than the loader set it. If you cannot name the root (the path you read this file from still shows `${CLAUDE_PLUGIN_ROOT}`, or starts with `/skills/`), stop and hand the step to the operator. Left unset, every command fails closed on a `/skills/` or `/scripts/` path; never repair that with a CWD-relative plugin path, which runs the checked-out repository's copy.
+
+Loaded from [review/SKILL.md](../SKILL.md) step 4 — moved verbatim (byte-ceiling extraction, #9403).
+
+<ultrathink_instruction> For each phase below, spend maximum cognitive effort. Think step by step. Consider all angles. Question assumptions. And bring all reviews in a synthesis to the user.</ultrathink_instruction>
+
+<deliverable>
+Complete system context map with component interactions
+</deliverable>
+
+## Phase 3: Stakeholder Perspective Analysis
+
+<thinking_prompt> ULTRA-THINK: Put yourself in each stakeholder's shoes. What matters to them? What are their pain points? </thinking_prompt>
+
+<stakeholder_perspectives>
+
+1. **Developer Perspective** <questions>
+
+   - How easy is this to understand and modify?
+   - Are the APIs intuitive?
+   - Is debugging straightforward?
+   - Can I test this easily? </questions>
+
+2. **Operations Perspective** <questions>
+
+   - How do I deploy this safely?
+   - What metrics and logs are available?
+   - How do I troubleshoot issues?
+   - What are the resource requirements? </questions>
+
+3. **End User Perspective** <questions>
+
+   - Is the feature intuitive?
+   - Are error messages helpful?
+   - Is performance acceptable?
+   - Does it solve my problem? </questions>
+
+4. **Security Team Perspective** <questions>
+
+   - What's the attack surface?
+   - Are there compliance requirements?
+   - How is data protected?
+   - What are the audit capabilities? </questions>
+
+5. **Business Perspective** <questions>
+   - What's the ROI?
+   - Are there legal/compliance risks?
+   - How does this affect time-to-market?
+   - What's the total cost of ownership? </questions> </stakeholder_perspectives>
+
+## Phase 4: Scenario Exploration
+
+<thinking_prompt> ULTRA-THINK: Explore edge cases and failure scenarios. What could go wrong? How does the system behave under stress? </thinking_prompt>
+
+<scenario_checklist>
+
+- [ ] **Happy Path**: Normal operation with valid inputs
+- [ ] **Invalid Inputs**: Null, empty, malformed data
+- [ ] **Boundary Conditions**: Min/max values, empty collections
+- [ ] **Concurrent Access**: Race conditions, deadlocks
+- [ ] **Scale Testing**: 10x, 100x, 1000x normal load
+- [ ] **Network Issues**: Timeouts, partial failures
+- [ ] **Resource Exhaustion**: Memory, disk, connections
+- [ ] **Security Attacks**: Injection, overflow, DoS
+- [ ] **Data Corruption**: Partial writes, inconsistency
+- [ ] **Cascading Failures**: Downstream service issues </scenario_checklist>
+
+### 6. Multi-Angle Review Perspectives
+
+## Technical Excellence Angle
+
+- Code craftsmanship evaluation
+- Engineering best practices
+- Technical documentation quality
+- Tooling and automation assessment
+
+## Business Value Angle
+
+- Feature completeness validation
+- Performance impact on users
+- Cost-benefit analysis
+- Time-to-market considerations
+
+## Risk Management Angle
+
+- Security risk assessment
+- Operational risk evaluation
+- Compliance risk verification
+- Technical debt accumulation
+
+## Team Dynamics Angle
+
+- Code review etiquette
+- Knowledge sharing effectiveness
+- Collaboration patterns
+- Mentoring opportunities

package/skills/review/references/wfs.md

@@ -0,0 +1,6 @@
+# Review check: a workflow suite's coverage
+
+Loaded from the Defect Classes list in [SKILL.md](../SKILL.md) (Defect Classes) when the diff adds or edits a `.github/workflows/*.yml` file or its suite.
+
+- **A workflow suite's coverage is the set of step BODIES it executes under the shell GitHub runs — name each step that writes state and the row that runs it to failure.** A step with no `shell:` key runs as `bash -e {0}` (no pipefail, errexit ON), so `rc=$?` after a failing command is unreachable unless `set +e` brackets it (ADR-170; `lint-workflow-errexit-capture.py` fails on it in CI). A harness that runs bodies under `-eo pipefail` and stubs only the read path certifies the guards and never the writer, and regex pins over the apply line are satisfied by a trailing comment, a double space, `-chdir`, an env-borne `TF_CLI_ARGS_*` or an extra step. Also: a guard's name/config/address list must be READ from the graded artifact (the plan JSON), not restated, and a stub env var shadows the one under test unless namespaced `STUB_*`. **Why:** #9481 — the P1 and four of twelve P2s were this; 169 rows and 35 mutants were green. See `knowledge-base/project/learnings/2026-10-04-a-create-only-workflow-whose-writing-step-my-suite-never-executed.md`.
+- **A gate's WIRING is not pinned by regex over its workflow text: execute the extracted `run:` block against a stub that REFUSES any other argv, with a control case proving a changed selector flips the verdict, and keep `absent`/`unknown` apart from `skipped` when classifying run records.** Regex pins stayed green with a case arm replaced by `:`, a changed `--event`, a swapped `--jq` field order and a post-scan reassignment; a classifier that read an absent or conclusion-less step as "skipped" read the plan's own cited failed rotate (a pre-rename step name) as nothing-happened. **Why:** #10166/PR #10184. See `knowledge-base/project/learnings/2026-10-13-a-classifier-that-reads-absent-as-skip-fails-open-on-name-drift.md`.