feat: 4.0.0 — event-driven provider listening + actp request + Sentinel onboarding

.github/CODEOWNERS

@@ -0,0 +1,22 @@
+# Code owners for @agirails/sdk (TypeScript)
+#
+# Per Apex audit 2026-05-17 FIND-003 — couples with branch protection
+# "Require review from Code Owners" once enabled.
+
+# Default — any file not matched by a more specific rule.
+*                              @DamirAGI @roosch269
+
+# SDK source — runtime behaviour, on-chain interactions, key handling.
+/src/                          @DamirAGI @roosch269
+
+# Wallet and keystore code — sensitive surface, key-material adjacent.
+/src/wallet/                   @DamirAGI @roosch269
+/src/cli/commands/deploy-env.ts @DamirAGI @roosch269
+/src/cli/commands/deploy-check.ts @DamirAGI @roosch269
+
+# Package metadata — version bumps and publish-time settings.
+/package.json                  @DamirAGI @roosch269
+/package-lock.json             @DamirAGI @roosch269
+
+# CI and Dependabot config — release-integrity surface.
+/.github/                      @DamirAGI @roosch269

.github/workflows/codeql.yml

@@ -0,0 +1,51 @@
+name: CodeQL
+
+# Apex audit FIND-004 — JS/TS SAST floor. Runs GitHub's default JS/TS
+# query pack on PRs, pushes to main, and a weekly cron. Catches the
+# defect classes the secret-scan layer (already enabled at the repo)
+# doesn't cover: unsafe eval, prototype pollution, regex injection,
+# hardcoded crypto primitives, taint flows through fetch / fs / child_process.
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    # Weekly Monday 06:00 UTC catches drift in dependencies that the
+    # PR-time scan wouldn't surface unless the dep tree was edited.
+    - cron: '0 6 * * 1'
+
+permissions:
+  contents: read
+
+jobs:
+  analyze:
+    name: Analyze (javascript-typescript)
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      security-events: write  # required for CodeQL to upload SARIF
+      actions: read
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11  # v4.1.1
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@379614612a29c9e28f31f39a59013eb8012a51f0  # v3.24.6
+        with:
+          languages: javascript-typescript
+          # Default + security-extended give a reasonable first-pass
+          # signal-to-noise. Tune via .github/codeql/codeql-config.yml
+          # if first runs surface too much benign noise.
+          queries: security-extended,security-and-quality
+
+      # Build step intentionally omitted — CodeQL autobuilds JS/TS from
+      # source without compilation. Adding a build step here would slow
+      # PRs without adding analysis coverage (CodeQL doesn't need tsc).
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@379614612a29c9e28f31f39a59013eb8012a51f0  # v3.24.6
+        with:
+          category: '/language:javascript-typescript'

.github/workflows/publish.yml

@@ -0,0 +1,97 @@
+name: Publish to npm
+
+# Apex audit FIND-007 — tag-driven publish pipeline with npm provenance.
+# Fires only on annotated git tags matching v*.*.* (including pre-release
+# tags like v4.0.0-beta.10). The published tarball is signed by sigstore
+# via npm's trusted-publishing OIDC flow, so the npm registry can prove
+# the build came from this repo + this commit. Closes the forensic gap
+# noted in the Apex 2026-05-17 refresh: prior 4.0.0-beta.0..9 publishes
+# had no provenance attestation.
+
+on:
+  push:
+    tags:
+      - 'v*.*.*'
+      - 'v*.*.*-*'  # pre-release tags (alpha/beta/rc)
+
+# Least-privilege default. The publish job widens to `id-token: write`
+# for OIDC; nothing else needs to write.
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write  # required for npm provenance via OIDC
+    steps:
+      # Pin all third-party actions by full-length commit SHA, not `@vN`,
+      # per the Apex audit recommendation (tj-actions/changed-files class
+      # of compromise — CVE-2025-30066).
+      - name: Checkout
+        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11  # v4.1.1
+        with:
+          fetch-depth: 0  # we want the full history so the tag points at a real commit
+
+      - name: Setup Node 20 with npm cache
+        uses: actions/setup-node@60edb5dd545a775178f52524783378180af0d1f8  # v4.0.2
+        with:
+          node-version: 20
+          cache: 'npm'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Verify tag matches package.json version
+        # The tag drives the workflow but we double-check it agrees with
+        # the in-tree version so an accidentally-mistagged commit fails
+        # loudly before reaching the publish step.
+        run: |
+          PKG_VERSION=$(node -p "require('./package.json').version")
+          TAG_VERSION="${GITHUB_REF_NAME#v}"
+          if [ "$PKG_VERSION" != "$TAG_VERSION" ]; then
+            echo "::error::Tag $GITHUB_REF_NAME (=> $TAG_VERSION) does not match package.json version $PKG_VERSION"
+            exit 1
+          fi
+          echo "Tag and package.json agree on version $PKG_VERSION"
+
+      - name: Install dependencies (lockfile-pinned)
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+
+      - name: Test
+        run: npm test
+
+      - name: Lint
+        run: npm run lint
+
+      - name: Determine dist-tag from version
+        # Pre-release versions (containing `-`) go to a channel matching the
+        # pre-release suffix ('next' for beta.X, 'alpha' for alpha.X, etc.).
+        # Stable versions go to 'latest'. Avoids accidentally clobbering
+        # @latest with a beta.
+        run: |
+          VERSION=$(node -p "require('./package.json').version")
+          if echo "$VERSION" | grep -q '-beta'; then
+            echo "DIST_TAG=next" >> "$GITHUB_ENV"
+          elif echo "$VERSION" | grep -q '-alpha'; then
+            echo "DIST_TAG=alpha" >> "$GITHUB_ENV"
+          elif echo "$VERSION" | grep -q '-rc'; then
+            echo "DIST_TAG=rc" >> "$GITHUB_ENV"
+          elif echo "$VERSION" | grep -q '-'; then
+            # Any other pre-release suffix → next (conservative default)
+            echo "DIST_TAG=next" >> "$GITHUB_ENV"
+          else
+            echo "DIST_TAG=latest" >> "$GITHUB_ENV"
+          fi
+
+      - name: Publish to npm with provenance
+        # `--provenance` triggers npm's OIDC handshake with sigstore and
+        # attaches a publish attestation to the tarball. Requires
+        # `id-token: write` on this job and that the package is allowed
+        # to publish from this repo (npm-side admin setting on the
+        # @agirails org).
+        run: npm publish --tag "$DIST_TAG" --access public --provenance
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

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

@@ -7,6 +7,7 @@
       - 'package.json'
       - 'package-lock.json'
       - 'tsconfig.json'
+      - 'jest.config.js'
       - '.github/workflows/sdk-ts-ci.yml'
   push:
     branches: [main]
@@ -15,11 +16,21 @@
       - 'package.json'
       - 'package-lock.json'
       - 'tsconfig.json'
+      - 'jest.config.js'
       - '.github/workflows/sdk-ts-ci.yml'
 
 jobs:
   secret-scan:
     runs-on: ubuntu-latest
+    # gitleaks-action started requiring a paid license for GitHub Organizations
+    # in late 2024 (see https://github.com/gitleaks/gitleaks-action#-announcement).
+    # Until an org-level GITLEAKS_LICENSE secret is provisioned (tracked
+    # separately from this PR), we run the action but don't gate the
+    # pipeline on it — the job becomes a warning rather than a blocker.
+    # Downstream jobs that have `needs: secret-scan` still proceed because
+    # `continue-on-error` reports success-with-errors to dependents.
+    # Revert this once GITLEAKS_LICENSE is configured.
+    continue-on-error: true
     steps:
       - uses: actions/checkout@v4
         with:
@@ -128,3 +139,55 @@
             );
             console.log('tsconfig.json module = commonjs — OK');
           "
+
+  # ----------------------------------------------------------------------
+  # PRD §8.2 — Anvil-fork blockchain-runtime e2e suite.
+  #
+  # Spins up real anvil processes against a forked Base Sepolia state to
+  # cover the 15 scenarios in src/__e2e__/blockchain-runtime/. The suite
+  # requires two repository secrets:
+  #   - BASE_SEPOLIA_RPC: paid-tier upstream RPC URL anvil forks against
+  #     (Alchemy / Infura — free public RPCs throttle queryFilter scans)
+  #   - CI_TEST_KEYSTORE_BASE64: base64 of a BIP-39 mnemonic with small
+  #     amounts of Base Sepolia ETH + test USDC on the first few HD slots
+  #
+  # Gate: pull requests from forks don't have access to repository
+  # secrets, so this job runs only on push-to-main or PRs from the same
+  # repository. Forks see a single "skipped" entry on the PR check list
+  # and the main test matrix above still gates merge.
+  # ----------------------------------------------------------------------
+  fork-e2e:
+    needs: lint-build-test
+    runs-on: ubuntu-latest
+    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Build (tsc)
+        run: npm run build
+
+      - name: Install foundry (anvil)
+        uses: foundry-rs/foundry-toolchain@v1
+        with:
+          version: stable
+
+      - name: Verify anvil is on PATH
+        run: anvil --version
+
+      - name: Run anvil-fork e2e suite
+        env:
+          BASE_SEPOLIA_RPC: ${{ secrets.BASE_SEPOLIA_RPC }}
+          CI_TEST_KEYSTORE_BASE64: ${{ secrets.CI_TEST_KEYSTORE_BASE64 }}
+        run: |
+          if [ -z "$BASE_SEPOLIA_RPC" ] || [ -z "$CI_TEST_KEYSTORE_BASE64" ]; then
+            echo "::warning::Fork-e2e secrets not configured for this run — suite skip-gate will fire and report 0 failures, but no on-chain assertions ran."
+          fi
+          npm run test:fork-e2e