staging → main: the dpp-web audit remediation

.github/workflows/ci.yml

@@ -5,13 +5,34 @@ on:
     branches: [main]
   pull_request:
 
+# The job builds and inspects; it never writes to the repository. Without this
+# block it would inherit whatever the repository default happens to be, which is
+# the only privileged path in the file.
+permissions:
+  contents: read
+
 jobs:
   build:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
         uses: actions/checkout@v4
 
+      # The vendored OpenAPI spec is a copy of the engine's. Without the source
+      # beside it there is nothing to compare against, and a drift check that
+      # cannot see the source is a check that always passes.
+      #
+      # Full history, because the check reads the spec at the commit recorded in
+      # openapi-source.json rather than at whatever is currently on main. See
+      # that script's header for why the pin exists.
+      - name: Checkout dpp-engine (source of the vendored API spec)
+        uses: actions/checkout@v4
+        with:
+          repository: odal-node/dpp-engine
+          path: .dpp-engine
+          fetch-depth: 0
+          persist-credentials: false
+
       - name: Enable Corepack
         run: corepack enable
 
@@ -29,3 +50,48 @@ jobs:
 
       - name: Check
         run: pnpm -r check
+
+      # Markdown link targets are opaque strings to `astro check`. This reads
+      # the built output, so it sees what is actually published — including
+      # cross-site links, which neither site's own tooling can resolve.
+      - name: Check links
+        run: pnpm run check:links
+
+      # This repository is public. Internal decision-record numbers and paths
+      # into the private docs repo must not appear in it — including inside
+      # `public/`, which is served verbatim.
+      - name: Check for internal-vocabulary leakage
+        run: pnpm run check:leakage
+
+      - name: Check the vendored API spec against the engine
+        run: pnpm run check:openapi
+        env:
+          DPP_ENGINE_DIR: ${{ github.workspace }}/.dpp-engine
+
+      # Reports, without failing, how far the pin is behind the engine's main.
+      # Deliberately not a gate: the pinned copy being *correct* is this repo's
+      # problem and is enforced above, but the pin being *old* is a release-
+      # cadence judgement, and failing on it would redden every pull request
+      # here every time the engine merges anything. The number is printed on
+      # every run so the drift that started this — a published spec fifteen
+      # endpoints behind, with nothing to reveal it — cannot go unnoticed again.
+      - name: Report how far the API-spec pin is behind
+        if: always()
+        run: |
+          PIN=$(node -p "require('./site/dpp-docs/openapi-source.json').commit")
+          cd .dpp-engine
+          BEHIND=$(git rev-list --count "$PIN"..origin/main -- api/openapi.yaml 2>/dev/null || echo "?")
+          if [ "$BEHIND" = "0" ]; then
+            echo "API spec pin is current with the engine's main branch."
+          else
+            echo "::notice::The vendored API spec is pinned $BEHIND commit(s) behind changes to api/openapi.yaml on the engine's main. Run 'pnpm run sync:openapi' to bring it forward."
+            git --no-pager log --oneline "$PIN"..origin/main -- api/openapi.yaml || true
+          fi
+
+      # Fails on a high-severity advisory. The remaining advisories are all
+      # build-time or dev-server issues in transitive dependencies, which do not
+      # reach a static deploy — so this is set to fail on `critical` today and
+      # should be tightened to `high` once those clear. The point is that a new
+      # advisory becomes visible on the pull request that introduces it.
+      - name: Audit dependencies
+        run: pnpm audit --audit-level critical

.github/workflows/deploy.yml

@@ -0,0 +1,81 @@
+name: Deploy
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+    paths:
+      - 'site/**'
+      - 'packages/**'
+      - 'public/**'
+      - '.github/workflows/deploy.yml'
+
+jobs:
+  purge-cloudflare-cache-landing:
+    name: Purge Cloudflare Cache (landing)
+    runs-on: ubuntu-latest
+    environment: ${{ vars.CLOUDFLARE_ENVIRONMENT_LANDING || 'landing' }}
+
+    steps:
+      - name: Check Cloudflare secrets
+        id: cloudflare
+        env:
+          CLOUDFLARE_ZONE_ID: ${{ secrets.CLOUDFLARE_ZONE_ID }}
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+        run: |
+          if [ -n "$CLOUDFLARE_ZONE_ID" ] && [ -n "$CLOUDFLARE_API_TOKEN" ]; then
+            echo "ready=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "ready=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Purge Cloudflare cache
+        if: steps.cloudflare.outputs.ready == 'true'
+        env:
+          CLOUDFLARE_ZONE_ID: ${{ secrets.CLOUDFLARE_ZONE_ID }}
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+        run: |
+          curl --fail --silent --show-error \
+            -X POST "https://api.cloudflare.com/client/v4/zones/${CLOUDFLARE_ZONE_ID}/purge_cache" \
+            -H "Authorization: Bearer ${CLOUDFLARE_API_TOKEN}" \
+            -H "Content-Type: application/json" \
+            --data '{"purge_everything":true}'
+
+      - name: Skip purge if secrets are missing
+        if: steps.cloudflare.outputs.ready != 'true'
+        run: echo "Skipping Cloudflare cache purge because the required secrets are not configured for the landing environment."
+
+  purge-cloudflare-cache-docs:
+    name: Purge Cloudflare Cache (docs)
+    runs-on: ubuntu-latest
+    environment: ${{ vars.CLOUDFLARE_ENVIRONMENT_DOCS || 'docs' }}
+
+    steps:
+      - name: Check Cloudflare secrets
+        id: cloudflare
+        env:
+          CLOUDFLARE_ZONE_ID: ${{ secrets.CLOUDFLARE_ZONE_ID }}
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+        run: |
+          if [ -n "$CLOUDFLARE_ZONE_ID" ] && [ -n "$CLOUDFLARE_API_TOKEN" ]; then
+            echo "ready=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "ready=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Purge Cloudflare cache
+        if: steps.cloudflare.outputs.ready == 'true'
+        env:
+          CLOUDFLARE_ZONE_ID: ${{ secrets.CLOUDFLARE_ZONE_ID }}
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+        run: |
+          curl --fail --silent --show-error \
+            -X POST "https://api.cloudflare.com/client/v4/zones/${CLOUDFLARE_ZONE_ID}/purge_cache" \
+            -H "Authorization: Bearer ${CLOUDFLARE_API_TOKEN}" \
+            -H "Content-Type: application/json" \
+            --data '{"purge_everything":true}'
+
+      - name: Skip purge if secrets are missing
+        if: steps.cloudflare.outputs.ready != 'true'
+        run: echo "Skipping Cloudflare cache purge because the required secrets are not configured for the docs environment."

.gitignore

@@ -26,3 +26,7 @@ Thumbs.db
 # CI / deploy artefacts
 .wrangler/
 .cloudflare/
+
+# local-only assets (never publish, never commit — this repo is public)
+deprecated/
+.claude/

package.json

@@ -15,6 +15,10 @@
     "build:docs": "pnpm --filter dpp-docs build",
     "build": "pnpm -r build",
     "check": "pnpm -r check",
+    "check:links": "node scripts/check-links.mjs",
+    "check:leakage": "node scripts/check-leakage.mjs",
+    "check:openapi": "pnpm --filter dpp-docs run check:openapi",
+    "sync:openapi": "pnpm --filter dpp-docs run sync:openapi",
     "preview:landing": "pnpm --filter dpp-landing preview",
     "preview:docs": "pnpm --filter dpp-docs preview",
     "clean": "pnpm -r exec rm -rf dist .astro node_modules && rm -rf node_modules"

packages/brand-tokens/src/colors.ts

@@ -6,12 +6,12 @@
  * Starlight CSS-variable overrides import from here (directly, or via the
  * mirrored CSS custom properties in `tokens.css`).
  *
- * See BRAND.md section 4.1 for the editorial rationale behind each scale.
+ * Each scale is tuned for a specific surface; see the contrast notes below.
  */
 
 /**
  * Primary scale — navy/ice blue family, anchored on the logo
- * (decision 2026-06-10, docs/redesign/DESIGN_SPEC.md §1).
+ * (decision 2026-06-10).
  * 50–300 are ice tints (the logo stroke is 300); 500/600 are the interactive
  * action blues (AA on white); 800/900 are the navy surfaces (logo field = 900).
  */

packages/brand-tokens/src/spacing.ts

@@ -1,7 +1,7 @@
 /**
  * Odal Node — spacing and radius tokens.
  *
- * 8-pixel base scale with a 12px outlier (see BRAND.md section 4.3).
+ * 8-pixel base scale with a 12px outlier.
  */
 
 export const spacing = {

packages/brand-tokens/src/tokens.css

@@ -8,7 +8,7 @@
  *      that does `@import "tailwindcss"; @import "@odal/brand-tokens/tokens.css";`
  *      gets utility classes for the full brand palette without further config.
  *
- * Palette decision 2026-06-10 (docs/redesign/DESIGN_SPEC.md §1): the brand
+ * Palette decision 2026-06-10: the brand
  * colour system follows the logo — navy field (#080C2C) + ice-blue strokes
  * (#B7D4F0) — with a darkened action blue for interactive elements so links
  * and buttons hold AA contrast on white. The former green scale is retired.

packages/brand-tokens/src/typography.ts

@@ -1,7 +1,7 @@
 /**
  * Odal Node — typography tokens.
  *
- * System-stack-first. No web fonts. See BRAND.md section 4.2 for rationale.
+ * System-stack-first. No web fonts, so no page issues a third-party font request.
  */
 
 export const fontFamily = {