Land nuclear-expansion plan: Phase 2-4 audit-chain bundle

.github/workflows/chargeback-velocity.yml

@@ -0,0 +1,88 @@
+name: Chargeback velocity (daily)
+
+# P3.RAIL3 — runs scripts/chargeback-velocity.ts daily at 08:30 UTC
+# (just after the reconciliation cron clears at 08:00 UTC). Tiers
+# every connected account green/yellow/red and:
+#   - inserts a chargeback_alerts row for non-green tiers
+#   - sends a developer-facing email (rate-limited yellow 7d / red 24h)
+#   - flips developers.onboarding_paused = true on red tier
+#
+# Hostile posture (per audit):
+#   (a) idempotent payout-schedule update (handled in
+#       packages/rails/src/stripe.ts — see updatePayoutSchedule)
+#   (b) low-sample-size guard via --min-charges (default 10)
+#   (c) auto-pause is reversible via the founder admin UI
+#   (d) email rate-limit per (developer, tier)
+#
+# Auto-push of any outputs is OFF (nothing to push — DB-only side
+# effects). Workflow_dispatch is allowed for ad-hoc runs.
+
+on:
+  schedule:
+    - cron: '30 8 * * *'
+  workflow_dispatch:
+    inputs:
+      developer_id:
+        description: 'Run for a single developer (UUID). Empty → all developers.'
+        required: false
+        default: ''
+      dry_run:
+        description: 'Skip Stripe / DB / email side effects.'
+        required: false
+        default: 'false'
+        type: boolean
+
+permissions:
+  contents: read
+
+concurrency:
+  group: chargeback-velocity
+  cancel-in-progress: false
+
+jobs:
+  run:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    env:
+      DATABASE_URL: ${{ secrets.RECONCILE_DATABASE_URL }}
+      STRIPE_RECONCILE_KEY: ${{ secrets.STRIPE_RECONCILE_KEY }}
+      RESEND_API_KEY: ${{ secrets.RESEND_API_KEY }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      - run: npm ci
+
+      - name: Build @settlegrid/rails
+        run: npm --workspace @settlegrid/rails run build
+
+      - name: Run chargeback velocity
+        # workflow_dispatch inputs are bound via env vars (not ${{ }}
+        # template substitution) so a malicious dispatcher can't
+        # inject shell metacharacters via the developer_id field.
+        env:
+          INPUT_DEVELOPER_ID: ${{ github.event.inputs.developer_id }}
+          INPUT_DRY_RUN: ${{ github.event.inputs.dry_run }}
+        run: |
+          set -euo pipefail
+          ARGS=()
+          if [[ -n "${INPUT_DEVELOPER_ID:-}" ]]; then
+            # Hostile-review fix: the loose regex `^[0-9a-f-]{36}$`
+            # accepts e.g. 36 dashes. Require the canonical UUID
+            # 8-4-4-4-12 layout instead.
+            if ! [[ "${INPUT_DEVELOPER_ID}" =~ ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ ]]; then
+              echo "Invalid developer_id: ${INPUT_DEVELOPER_ID}" >&2
+              exit 2
+            fi
+            ARGS+=(--developer-id "${INPUT_DEVELOPER_ID}")
+          fi
+          if [[ "${INPUT_DRY_RUN:-false}" == "true" ]]; then
+            ARGS+=(--dry-run)
+          fi
+          npx tsx scripts/chargeback-velocity.ts "${ARGS[@]}"

.github/workflows/python-sdk-ci.yml

@@ -0,0 +1,115 @@
+name: Python SDK CI
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'packages/sdk-python/**'
+      - '.github/workflows/python-sdk-ci.yml'
+  pull_request:
+    paths:
+      - 'packages/sdk-python/**'
+      - '.github/workflows/python-sdk-ci.yml'
+
+# H9 hostile fix — least-privilege explicit permissions (default for new
+# repos, but stating it here makes the contract explicit and survives
+# org-level default changes).
+permissions:
+  contents: read
+
+# Cancel in-progress runs when a new commit lands on the same ref —
+# avoids burning CI minutes on superseded commits.
+concurrency:
+  group: python-sdk-ci-${{ github.ref }}
+  cancel-in-progress: true
+
+defaults:
+  run:
+    working-directory: packages/sdk-python
+
+jobs:
+  test:
+    name: test (py${{ matrix.python-version }} / ${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    # H8 hostile fix — bound CI duration; a hung pytest used to be able
+    # to consume 6h of CI time silently before getting killed.
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python-version: ['3.10', '3.11', '3.12']
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: 'pip'
+          cache-dependency-path: packages/sdk-python/pyproject.toml
+
+      - name: Install dev dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Verify no transitive-dep conflicts
+        run: pip check
+
+      - name: Lint (ruff)
+        run: ruff check settlegrid tests
+
+      - name: Type check (mypy)
+        run: mypy settlegrid
+
+      - name: Tests + coverage
+        run: pytest --cov=settlegrid --cov-report=xml --cov-report=term --cov-fail-under=90
+
+      - name: Upload coverage report
+        if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.12'
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-xml
+          path: packages/sdk-python/coverage.xml
+          if-no-files-found: error
+
+  build:
+    name: build wheel + sdist + smoke install
+    runs-on: ubuntu-latest
+    needs: test
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python 3.10
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.10'
+
+      - name: Install build backend
+        run: |
+          python -m pip install --upgrade pip
+          pip install build twine
+
+      - name: Build wheel + sdist
+        run: python -m build
+
+      - name: twine check
+        run: twine check dist/*
+
+      - name: Smoke install in fresh venv
+        run: |
+          python -m venv /tmp/smoke
+          /tmp/smoke/bin/pip install --upgrade pip
+          /tmp/smoke/bin/pip install dist/*.whl
+          /tmp/smoke/bin/pip check
+          /tmp/smoke/bin/python -c "import settlegrid; print(settlegrid.SDK_VERSION)"
+          /tmp/smoke/bin/python -c "from settlegrid import SettleGrid, Wrapper, Invocation, InvalidKeyError, RateLimitedError, KeyValidationResult, MeterResult"
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: sdk-python-dist
+          path: packages/sdk-python/dist/
+          if-no-files-found: error

.github/workflows/stripe-reconcile.yml

@@ -0,0 +1,144 @@
+name: Stripe reconciliation (daily)
+
+# P3.RAIL2 — Reconciles the SettleGrid unified ledger against Stripe
+# Balance Transactions + Connect Transfers for the previous UTC
+# calendar day. Reports drift to data/reconciliation/stripe/{date}.json,
+# posts a one-line summary to Slack/Discord, and opens a rate-limited
+# GitHub issue when drift breaches the configured threshold (1% / 100
+# bps by default). The orchestrator caps GitHub issues at one per
+# 24h via .reconcile-state.json, so a 24h Stripe outage that produces
+# 24 daily drift reports opens AT MOST one issue.
+#
+# Hostile-lens posture:
+#   (a) Schedule is FIXED at 08:00 UTC — well after Stripe's UTC-day
+#       window closes, so the run sees a complete day.
+#   (b) Workflow runs on the default branch only and uses the
+#       repository's default GITHUB_TOKEN scopes. No third-party
+#       actions handle secrets.
+#   (c) workflow_dispatch input is allowed for ad-hoc backfills,
+#       but the script validates --date through the same
+#       utcDayBounds() guard the cron path uses.
+#   (d) The job commits its outputs (data/reconciliation/stripe/*
+#       and data/reconciliation/.reconcile-state.json) so the
+#       audit trail lives in git, not action artifacts.
+
+on:
+  schedule:
+    # Daily 08:00 UTC. Verifier check 17 expects this exact cron string.
+    - cron: '0 8 * * *'
+  workflow_dispatch:
+    inputs:
+      date:
+        description: 'UTC calendar day to reconcile (YYYY-MM-DD). Empty → yesterday UTC.'
+        required: false
+        default: ''
+      dry_run:
+        description: 'Skip DB / Stripe / disk / webhook calls.'
+        required: false
+        default: 'false'
+        type: boolean
+
+permissions:
+  # `contents: write` is reserved for the opt-in auto-push step
+  # (gated by vars.RECONCILE_AUTO_PUSH). When the variable is unset,
+  # the step is skipped and the token is unused.
+  contents: write
+  issues: write
+
+concurrency:
+  # One reconciliation at a time. A 2nd manual run while a cron run is
+  # in flight queues rather than racing the state file.
+  group: stripe-reconciliation
+  cancel-in-progress: false
+
+jobs:
+  reconcile:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    env:
+      DATABASE_URL: ${{ secrets.RECONCILE_DATABASE_URL }}
+      # Per spec: use a Stripe restricted key with
+      # rak_balance_transaction_read + rak_transfer_read scopes only.
+      # Repo secret name = STRIPE_RECONCILE_KEY (rotate independently
+      # of the platform STRIPE_SECRET_KEY).
+      STRIPE_RECONCILE_KEY: ${{ secrets.STRIPE_RECONCILE_KEY }}
+      SLACK_RECONCILE_WEBHOOK: ${{ secrets.SLACK_RECONCILE_WEBHOOK }}
+      DISCORD_RECONCILE_WEBHOOK: ${{ secrets.DISCORD_RECONCILE_WEBHOOK }}
+      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      RECONCILE_REPO_SLUG: ${{ github.repository }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # Auto-push is opt-in (see step below). Default checkout is
+          # shallow; deepen only if we actually intend to push.
+          fetch-depth: 1
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      - run: npm ci
+
+      - name: Build @settlegrid/rails
+        run: npm --workspace @settlegrid/rails run build
+
+      - name: Run reconciliation
+        # Bind workflow_dispatch inputs to env vars instead of pasting
+        # them via `${{ ... }}` template substitution. The `${{ }}`
+        # form is expanded by GitHub BEFORE the shell sees it, so a
+        # malicious `date: 2026-04-23 && rm -rf /` would inject. The
+        # env-var form passes the value through `process.env` and the
+        # shell's quoting; safe.
+        env:
+          INPUT_DATE: ${{ github.event.inputs.date }}
+          INPUT_DRY_RUN: ${{ github.event.inputs.dry_run }}
+        run: |
+          set -euo pipefail
+          ARGS=()
+          if [[ -n "${INPUT_DATE:-}" ]]; then
+            # Reject anything but YYYY-MM-DD up-front so we never feed
+            # an unvalidated string to the script even on a misconfigured
+            # input. The script also re-validates via utcDayBounds.
+            if ! [[ "${INPUT_DATE}" =~ ^[0-9]{4}-[0-9]{2}-[0-9]{2}$ ]]; then
+              echo "Invalid date input: ${INPUT_DATE}" >&2
+              exit 2
+            fi
+            ARGS+=(--date "${INPUT_DATE}")
+          fi
+          if [[ "${INPUT_DRY_RUN:-false}" == "true" ]]; then
+            ARGS+=(--dry-run)
+          fi
+          npx tsx scripts/reconcile-stripe.ts "${ARGS[@]}"
+
+      - name: Upload reconciliation report
+        if: ${{ github.event.inputs.dry_run != 'true' }}
+        uses: actions/upload-artifact@v4
+        with:
+          name: stripe-reconciliation-${{ github.run_id }}
+          path: data/reconciliation/
+          retention-days: 90
+          if-no-files-found: warn
+
+      - name: Commit reconciliation report and state (opt-in)
+        # Auto-push is OPT-IN via the `RECONCILE_AUTO_PUSH` repo
+        # variable. Default-off because pushing data files to the
+        # default branch triggers Vercel rebuilds on every nightly
+        # run, which burns the deploy budget. Operators who need an
+        # in-git audit trail can set
+        # `vars.RECONCILE_AUTO_PUSH=true` in the repo's "Variables"
+        # tab; the commit-and-push path will then run.
+        if: ${{ github.event.inputs.dry_run != 'true' && vars.RECONCILE_AUTO_PUSH == 'true' }}
+        env:
+          REF_NAME: ${{ github.ref_name }}
+        run: |
+          set -euo pipefail
+          if [[ -z "$(git status --porcelain data/reconciliation/)" ]]; then
+            echo "No reconciliation changes to commit."
+            exit 0
+          fi
+          git config user.name 'settlegrid-bot'
+          git config user.email 'bot@settlegrid.dev'
+          git add data/reconciliation/
+          git commit -m "chore(reconcile): nightly Stripe reconciliation $(date -u +%Y-%m-%d)"
+          git push origin "HEAD:${REF_NAME}"