Merge branch 'main' of https://github.com/Stirling-Tools/Stirling-PDF into feature/documentClassifierAgent

translation
Merge branch 'feature/documentClassifierAgent' of https://github.com/Stirling-Tools/Stirling-PDF into feature/documentClassifierAgent
2026-07-02 15:33:53 +01:00 · 2026-07-02 14:42:07 +01:00 · 2026-07-02 14:28:07 +01:00 · 2026-07-02 14:28:02 +01:00 · 2026-07-01 13:49:02 +01:00 · 2026-07-01 13:42:26 +01:00
772 changed files with 49475 additions and 20917 deletions
@@ -1,6 +1,6 @@
 # Maintainer: Stirling PDF Inc <contact@stirlingpdf.com>
 pkgname=stirling-pdf-desktop
-pkgver=2.13.1
+pkgver=2.14.0
 pkgrel=1
 pkgdesc="Locally hosted, web-based PDF manipulation tool (Tauri desktop app, official Stirling PDF Inc build)"
 arch=('x86_64')
@@ -1,6 +1,6 @@
 # Maintainer: Stirling PDF Inc <contact@stirlingpdf.com>
 pkgname=stirling-pdf-server-bin
-pkgver=2.13.1
+pkgver=2.14.0
 pkgrel=1
 pkgdesc="Locally hosted, web-based PDF manipulation tool (server JAR, prebuilt)"
 arch=('any')
@@ -222,7 +222,7 @@ jobs:
      - name: Setup Gradle
        uses: gradle/actions/setup-gradle@50e97c2cd7a37755bbfafc9c5b7cafaece252f6e # v6.1.0
        with:
-          gradle-version: 9.5.1
+          gradle-version: 9.6.0

      - name: Install Task
        uses: go-task/setup-task@01a4adf9db2d14c1de7a560f09170b6e0df736aa # v2.1.0
@@ -30,7 +30,7 @@ jobs:
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2

      - name: Install uv
-        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
        with:
          enable-cache: true

@@ -43,7 +43,7 @@ jobs:
      - name: Setup Gradle
        uses: gradle/actions/setup-gradle@50e97c2cd7a37755bbfafc9c5b7cafaece252f6e # v6.1.0
        with:
-          gradle-version: 9.5.1
+          gradle-version: 9.6.0

      - name: Install Task
        uses: go-task/setup-task@01a4adf9db2d14c1de7a560f09170b6e0df736aa # v2.1.0
@@ -58,7 +58,7 @@ jobs:
      - name: Setup Gradle
        uses: gradle/actions/setup-gradle@50e97c2cd7a37755bbfafc9c5b7cafaece252f6e # v6.1.0
        with:
-          gradle-version: 9.5.1
+          gradle-version: 9.6.0
          cache-disabled: true

      - name: Install Task
@@ -40,7 +40,7 @@ jobs:
      - name: Setup Gradle
        uses: gradle/actions/setup-gradle@50e97c2cd7a37755bbfafc9c5b7cafaece252f6e # v6.1.0
        with:
-          gradle-version: 9.5.1
+          gradle-version: 9.6.0
          cache-disabled: true

      - name: Install Task
@@ -45,7 +45,7 @@ jobs:
      - name: Setup Gradle
        uses: gradle/actions/setup-gradle@50e97c2cd7a37755bbfafc9c5b7cafaece252f6e # v6.1.0
        with:
-          gradle-version: 9.5.1
+          gradle-version: 9.6.0
          cache-disabled: true

      - name: Install Task
@@ -51,7 +51,7 @@ jobs:
      - name: Setup Gradle
        uses: gradle/actions/setup-gradle@50e97c2cd7a37755bbfafc9c5b7cafaece252f6e # v6.1.0
        with:
-          gradle-version: 9.3.1
+          gradle-version: 9.6.0
          cache-disabled: true

      - name: Set up Python
@@ -48,7 +48,7 @@ jobs:
      - name: Setup Gradle
        uses: gradle/actions/setup-gradle@50e97c2cd7a37755bbfafc9c5b7cafaece252f6e # v6.1.0
        with:
-          gradle-version: 9.5.1
+          gradle-version: 9.6.0
          cache-disabled: true

      # No `-PnoSpotless` here yet because the upstream cache layer matches the
@@ -61,14 +61,22 @@ jobs:
      - name: Setup Gradle
        uses: gradle/actions/setup-gradle@50e97c2cd7a37755bbfafc9c5b7cafaece252f6e # v6.1.0
        with:
-          gradle-version: 9.5.1
+          gradle-version: 9.6.0
          cache-disabled: true

+      # When the PR changes the base image, test.sh builds it locally
+      # (stirling-pdf-base:local) into the daemon image store. A buildx
+      # container builder can't see that store, so skip it here and let
+      # `docker buildx build` fall back to the default docker driver, which
+      # resolves the local base. The gha cache backend is also skipped (its
+      # runtime token isn't exposed) since the docker driver can't use it.
      - name: Set up Docker Buildx
+        if: inputs.docker-base-changed != 'true'
        uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4.0.0

      # Expose ACTIONS_RUNTIME_TOKEN / ACTIONS_RESULTS_URL for docker buildx type=gha cache backend.
      - name: Expose GitHub runtime for Buildx cache
+        if: inputs.docker-base-changed != 'true'
        uses: crazy-max/ghaction-github-runtime@04d248b84655b509d8c44dc1d6f990c879747487 # v4.0.0

      - name: Install Docker Compose
@@ -349,7 +349,7 @@ jobs:
      - name: Setup Gradle
        uses: gradle/actions/setup-gradle@50e97c2cd7a37755bbfafc9c5b7cafaece252f6e # v6.1.0
        with:
-          gradle-version: 9.5.1
+          gradle-version: 9.6.0

      - name: Install Task
        uses: go-task/setup-task@01a4adf9db2d14c1de7a560f09170b6e0df736aa # v2.1.0
@@ -73,7 +73,7 @@ jobs:
      - name: Setup Gradle
        uses: gradle/actions/setup-gradle@50e97c2cd7a37755bbfafc9c5b7cafaece252f6e # v6.1.0
        with:
-          gradle-version: 9.5.1
+          gradle-version: 9.6.0

      - name: Install Task
        uses: go-task/setup-task@01a4adf9db2d14c1de7a560f09170b6e0df736aa # v2.1.0
@@ -148,7 +148,7 @@ jobs:
      - name: Setup Gradle
        uses: gradle/actions/setup-gradle@50e97c2cd7a37755bbfafc9c5b7cafaece252f6e # v6.1.0
        with:
-          gradle-version: 9.5.1
+          gradle-version: 9.6.0

      - name: Setup Node.js
        if: matrix.variant.build_frontend == true
@@ -252,7 +252,7 @@ jobs:
      - name: Setup Gradle
        uses: gradle/actions/setup-gradle@50e97c2cd7a37755bbfafc9c5b7cafaece252f6e # v6.1.0
        with:
-          gradle-version: 9.5.1
+          gradle-version: 9.6.0

      - name: Install Task
        uses: go-task/setup-task@01a4adf9db2d14c1de7a560f09170b6e0df736aa # v2.1.0
@@ -41,6 +41,11 @@ jobs:
      - name: Install all Playwright browsers
        run: task e2e:install

+      - name: Build frontend (production bundle for vite preview)
+        env:
+          VITE_BUILD_FOR_PREVIEW: "1"
+        run: task frontend:build
+
      - name: Run E2E tests (all browsers)
        run: task e2e:cross-browser

@@ -62,4 +67,5 @@ jobs:
    uses: ./.github/workflows/tauri-build.yml
    with:
      platform: all
+      sign: false
    secrets: inherit
@@ -25,7 +25,7 @@ jobs:
          persist-credentials: false

      - name: Install uv
-        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
        with:
          enable-cache: true

@@ -78,7 +78,7 @@ jobs:
      - name: Setup Gradle
        uses: gradle/actions/setup-gradle@50e97c2cd7a37755bbfafc9c5b7cafaece252f6e # v6.1.0
        with:
-          gradle-version: 9.5.1
+          gradle-version: 9.6.0

      - name: Set up Docker Buildx
        id: buildx
@@ -155,9 +155,9 @@ jobs:
          cache-to: type=gha,mode=max,scope=stirling-pdf-latest
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
+          # No BASE_VERSION pin: inherit the Dockerfile ARG default (single source of truth).
          build-args: |
            VERSION_TAG=${{ steps.versionNumber.outputs.versionNumber }}
-            BASE_VERSION=1.0.0
          platforms: linux/amd64,linux/arm64/v8
          provenance: true
          sbom: true
@@ -48,7 +48,7 @@ jobs:
      - name: Setup Gradle
        uses: gradle/actions/setup-gradle@50e97c2cd7a37755bbfafc9c5b7cafaece252f6e # v6.1.0
        with:
-          gradle-version: 9.5.1
+          gradle-version: 9.6.0

      - name: Generate Swagger documentation
        run: ./gradlew :stirling-pdf:generateOpenApiDocs
@@ -61,7 +61,7 @@ jobs:
          pip install --require-hashes --only-binary=:all: -r ./.github/scripts/requirements_sync_readme.txt

      - name: Install uv
-        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
        with:
          enable-cache: true

@@ -16,6 +16,11 @@ on:
        required: false
        type: string
        default: "all"
+      sign:
+        description: "Sign and notarize the bundles."
+        required: false
+        type: boolean
+        default: true
  workflow_dispatch:
    inputs:
      platform:
@@ -28,6 +33,11 @@ on:
          - windows
          - macos
          - linux
+      sign:
+        description: "Sign and notarize the bundles."
+        required: false
+        default: true
+        type: boolean

 permissions:
  contents: read
@@ -122,7 +132,7 @@ jobs:
        uses: Swatinem/rust-cache@c19371144df3bb44fab255c43d04cbc2ab54d1c4 # v2.9.1
        with:
          workspaces: frontend/editor/src-tauri
-          # Stable key shared across workflows so the nightly warmer. 
+          # Stable key shared across workflows so the nightly warmer.
          # rust-cache still appends OS + rustc + Cargo.lock.
          shared-key: tauri-${{ matrix.name }}
          save-if: ${{ github.ref == 'refs/heads/main' }}
@@ -150,7 +160,7 @@ jobs:
      - name: Setup Gradle
        uses: gradle/actions/setup-gradle@50e97c2cd7a37755bbfafc9c5b7cafaece252f6e # v6.1.0
        with:
-          gradle-version: 9.5.1
+          gradle-version: 9.6.0

      - name: Setup Task
        uses: go-task/setup-task@01a4adf9db2d14c1de7a560f09170b6e0df736aa # v2.1.0
@@ -177,7 +187,7 @@ jobs:
      # DigiCert KeyLocker Setup (Cloud HSM)
      - name: Setup DigiCert KeyLocker
        id: digicert-setup
-        if: ${{ matrix.platform == 'windows-latest' && env.SM_API_KEY != '' && github.ref == 'refs/heads/main' }}
+        if: ${{ inputs.sign && matrix.platform == 'windows-latest' && env.SM_API_KEY != '' && github.ref == 'refs/heads/main' }}
        uses: digicert/ssm-code-signing@1d820463733701cf1484c7eb5d7d24a15ca2c454 # v1.2.1
        env:
          SM_API_KEY: ${{ secrets.SM_API_KEY }}
@@ -187,7 +197,7 @@ jobs:
          SM_HOST: ${{ secrets.SM_HOST }}

      - name: Setup DigiCert KeyLocker Certificate
-        if: ${{ matrix.platform == 'windows-latest' && env.SM_API_KEY != '' && github.ref == 'refs/heads/main' }}
+        if: ${{ inputs.sign && matrix.platform == 'windows-latest' && env.SM_API_KEY != '' && github.ref == 'refs/heads/main' }}
        shell: pwsh
        run: |
          Write-Host "Setting up DigiCert KeyLocker environment..."
@@ -222,7 +232,7 @@ jobs:

      # Traditional PFX Certificate Import (fallback if KeyLocker not configured)
      - name: Import Windows Code Signing Certificate
-        if: ${{ matrix.platform == 'windows-latest' && env.SM_API_KEY == '' && github.ref == 'refs/heads/main' }}
+        if: ${{ inputs.sign && matrix.platform == 'windows-latest' && env.SM_API_KEY == '' && github.ref == 'refs/heads/main' }}
        env:
          WINDOWS_CERTIFICATE: ${{ secrets.WINDOWS_CERTIFICATE }}
          WINDOWS_CERTIFICATE_PASSWORD: ${{ secrets.WINDOWS_CERTIFICATE_PASSWORD }}
@@ -253,7 +263,7 @@ jobs:
          }

      - name: Import Apple Developer Certificate
-        if: matrix.platform == 'macos-15' && env.APPLE_CERTIFICATE != ''
+        if: inputs.sign && matrix.platform == 'macos-15' && env.APPLE_CERTIFICATE != ''
        env:
          APPLE_CERTIFICATE: ${{ secrets.APPLE_CERTIFICATE }}
          APPLE_CERTIFICATE_PASSWORD: ${{ secrets.APPLE_CERTIFICATE_PASSWORD }}
@@ -274,7 +284,7 @@ jobs:
          rm certificate.p12

      - name: Verify Certificate
-        if: matrix.platform == 'macos-15' && env.APPLE_CERTIFICATE != ''
+        if: inputs.sign && matrix.platform == 'macos-15' && env.APPLE_CERTIFICATE != ''
        run: |
          echo "Verifying Apple Developer Certificate..."
          KEYCHAIN_PATH=$RUNNER_TEMP/app-signing.keychain-db
@@ -297,7 +307,7 @@ jobs:
          ls -la /usr/bin/hd* || echo "No hd* tools found"

      - name: Preflight smctl
-        if: ${{ matrix.platform == 'windows-latest' && env.SM_API_KEY != '' && github.ref == 'refs/heads/main' }}
+        if: ${{ inputs.sign && matrix.platform == 'windows-latest' && env.SM_API_KEY != '' && github.ref == 'refs/heads/main' }}
        shell: pwsh
        env:
          KEYPAIR_ALIAS: ${{ secrets.SM_KEYPAIR_ALIAS }}
@@ -310,7 +320,7 @@ jobs:
          if ($LASTEXITCODE -ne 0) { Write-Host "[WARN] smctl windows certsync returned non-zero - continuing" }

      - name: Configure Windows code signing
-        if: ${{ matrix.platform == 'windows-latest' && env.SM_API_KEY != '' && github.ref == 'refs/heads/main' }}
+        if: ${{ inputs.sign && matrix.platform == 'windows-latest' && env.SM_API_KEY != '' && github.ref == 'refs/heads/main' }}
        shell: bash
        env:
          KEYPAIR_ALIAS: ${{ secrets.SM_KEYPAIR_ALIAS }}
@@ -329,7 +339,7 @@ jobs:
          EOF

      - name: Import release GPG signing key (Linux)
-        if: matrix.platform == 'ubuntu-22.04' && env.RELEASE_GPG_PRIVATE_KEY != '' && github.ref == 'refs/heads/main'
+        if: inputs.sign && matrix.platform == 'ubuntu-22.04' && env.RELEASE_GPG_PRIVATE_KEY != '' && github.ref == 'refs/heads/main'
        run: |
          echo "$RELEASE_GPG_PRIVATE_KEY" | gpg --batch --import
          gpg --list-secret-keys --keyid-format=long
@@ -346,7 +356,8 @@ jobs:
            exit 1
          fi

-      - name: Build Tauri app
+      - name: Build Tauri app (signed)
+        if: inputs.sign
        uses: tauri-apps/tauri-action@84b9d35b5fc46c1e45415bdb6144030364f7ebc5 # v0.6.2
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
@@ -380,6 +391,26 @@ jobs:
          # failure (#6127 onwards) does not tank deb/rpm uploads.
          args: ${{ matrix.platform == 'ubuntu-22.04' && '--bundles deb,rpm' || matrix.args }}

+      - name: Build Tauri app (unsigned)
+        if: ${{ !inputs.sign }}
+        uses: tauri-apps/tauri-action@84b9d35b5fc46c1e45415bdb6144030364f7ebc5 # v0.6.2
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          SIGN: "0"
+          TAURI_SIGNING_PRIVATE_KEY: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY }}
+          TAURI_SIGNING_PRIVATE_KEY_PASSWORD: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY_PASSWORD }}
+          VITE_SUPABASE_PUBLISHABLE_DEFAULT_KEY: ${{ secrets.VITE_SUPABASE_PUBLISHABLE_DEFAULT_KEY || 'sb_publishable_UHz2SVRF5mvdrPHWkRteyA_yNlZTkYb' }}
+          VITE_SAAS_SERVER_URL: ${{ secrets.VITE_SAAS_SERVER_URL || 'https://app.stirlingpdf.com' }}
+          VITE_SAAS_BACKEND_API_URL: ${{ secrets.VITE_SAAS_BACKEND_API_URL || 'https://api.stirlingpdf.com' }}
+          CI: true
+        with:
+          projectPath: ./frontend/editor
+          tauriScript: npx tauri
+          # Linux: build deb+rpm only here. AppImage runs in its own
+          # continue-on-error step below so its persistent linuxdeploy
+          # failure (#6127 onwards) does not tank deb/rpm uploads.
+          args: ${{ matrix.platform == 'ubuntu-22.04' && '--bundles deb,rpm' || matrix.args }}
+
      # AppImage is decoupled so its linuxdeploy run gets a fresh process
      # (rpm scratch state torn down) and its failure can't tank deb/rpm.
      - name: Build Tauri app (Linux AppImage)
@@ -388,7 +419,7 @@ jobs:
        uses: tauri-apps/tauri-action@84b9d35b5fc46c1e45415bdb6144030364f7ebc5 # v0.6.2
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          SIGN: ${{ (env.RELEASE_GPG_PRIVATE_KEY != '' && github.ref == 'refs/heads/main') && '1' || '0' }}
+          SIGN: ${{ (inputs.sign && env.RELEASE_GPG_PRIVATE_KEY != '' && github.ref == 'refs/heads/main') && '1' || '0' }}
          APPIMAGETOOL_SIGN_PASSPHRASE: ${{ secrets.RELEASE_GPG_PASSPHRASE }}
          SIGN_KEY: ${{ vars.RELEASE_GPG_FINGERPRINT }}
          TAURI_SIGNING_PRIVATE_KEY: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY }}
@@ -403,7 +434,7 @@ jobs:
          args: --bundles appimage

      - name: Clear release GPG key from runner keyring (Linux)
-        if: always() && matrix.platform == 'ubuntu-22.04' && env.RELEASE_GPG_PRIVATE_KEY != '' && github.ref == 'refs/heads/main'
+        if: always() && inputs.sign && matrix.platform == 'ubuntu-22.04' && env.RELEASE_GPG_PRIVATE_KEY != '' && github.ref == 'refs/heads/main'
        env:
          RELEASE_GPG_FINGERPRINT: ${{ vars.RELEASE_GPG_FINGERPRINT }}
        run: |
@@ -413,7 +444,7 @@ jobs:
          fi

      - name: Verify notarization (macOS only)
-        if: matrix.platform == 'macos-15'
+        if: inputs.sign && matrix.platform == 'macos-15'
        run: |
          echo "🔍 Verifying notarization status..."
          cd ./frontend/editor/src-tauri/target
@@ -451,7 +482,7 @@ jobs:
      # Verify the MSI AND the inner exe extracted from it are signed.
      # The inner exe is what gets installed on users' machines and what AV scans.
      - name: Verify Windows Code Signature
-        if: matrix.platform == 'windows-latest' && env.SM_API_KEY != '' && github.ref == 'refs/heads/main'
+        if: inputs.sign && matrix.platform == 'windows-latest' && env.SM_API_KEY != '' && github.ref == 'refs/heads/main'
        shell: pwsh
        run: |
          $allSigned = $true
@@ -106,7 +106,7 @@ jobs:
      - name: Setup Gradle
        uses: gradle/actions/setup-gradle@50e97c2cd7a37755bbfafc9c5b7cafaece252f6e # v6.1.0
        with:
-          gradle-version: 9.5.1
+          gradle-version: 9.6.0
          cache-disabled: true

      - name: Install Task
@@ -155,6 +155,19 @@ jobs:
            echo "platforms=linux/amd64,linux/arm64/v8" >> "$GITHUB_OUTPUT"
          fi

+      # Base-changed PRs build the embedded image with the local docker driver
+      # so the locally-built stirling-pdf-base:pr-test (in the daemon image
+      # store) resolves. A buildx container builder cannot see it and would try
+      # to pull it from a registry, which fails. Single-platform, no gha cache.
+      - name: Build ${{ matrix.docker-rev }} against local base (PR base change)
+        if: github.event_name == 'pull_request' && inputs.docker-base-changed == 'true'
+        run: |
+          DOCKER_BUILDKIT=1 docker build \
+            --build-arg BASE_IMAGE=${{ steps.build-params.outputs.base_image }} \
+            --file ./${{ matrix.docker-rev }} \
+            --tag stirling-pdf-embedded:pr-test \
+            .
+
      - name: Build ${{ matrix.docker-rev }} (Depot)
        if: env.USE_DEPOT == 'true'
        uses: depot/build-push-action@98e78adca7817480b8185f474a400b451d74e287 # v1.16.0
@@ -169,8 +182,10 @@ jobs:
          provenance: true
          sbom: true

+      # Fork PRs that did NOT change the base use the buildx container builder
+      # (multi-platform + gha cache) against the published base image.
      - name: Build ${{ matrix.docker-rev }} (Docker fork fallback)
-        if: env.USE_DEPOT != 'true'
+        if: env.USE_DEPOT != 'true' && inputs.docker-base-changed != 'true'
        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
        with:
          builder: ${{ steps.buildx.outputs.name }}
@@ -51,7 +51,7 @@ jobs:
      - name: Setup Gradle
        uses: gradle/actions/setup-gradle@50e97c2cd7a37755bbfafc9c5b7cafaece252f6e # v6.1.0
        with:
-          gradle-version: 9.5.1
+          gradle-version: 9.6.0

      - name: Build with Gradle
        run: ./gradlew build
@@ -19,3 +19,11 @@ frontend/shared/components/CodeBlock.stories.tsx:curl-auth-header:4

 # Truncated placeholder API key in portal docs example (sk_live_8f2c...e10) - not a real secret.
 frontend/portal/src/components/docs/GettingStartedSection.tsx:generic-api-key:31
+
+# False positive: generic-api-key matches the Java type name "X509Certificate"
+# in a method signature (CreateSignatureBase.resolveSignatureAlgorithm) - not a secret.
+app/core/src/main/java/org/apache/pdfbox/examples/signature/CreateSignatureBase.java:generic-api-key:224
+
+# Supabase publishable key (public by design, RLS-protected) used as a CI fallback
+# default in the tauri-build workflow when the GitHub secret is unset - not a real secret.
+.github/workflows/tauri-build.yml:generic-api-key:402
@@ -26,9 +26,14 @@ tasks:
          AIENGINE_ENABLED: '{{.AIENGINE_ENABLED}}'
          AIENGINE_TIMEOUTSECONDS: '{{.AIENGINE_TIMEOUTSECONDS}}'
          SECURITY_ENABLELOGIN: '{{.SECURITY_ENABLELOGIN}}'
+          POLICIES_ENABLED: '{{.POLICIES_ENABLED}}'

  dev:proprietary:
    desc: "Start backend dev server in proprietary mode"
+    # `dotenv:` reads from the root Taskfile's directory (".") because this
+    # subtaskfile is included with `dir: .`. Local overrides in
+    # .env.proprietary.local win over the committed .env.proprietary defaults.
+    dotenv: ['app/.env.proprietary.local', 'app/.env.proprietary']
    ignore_error: true
    vars:
      PORT: '{{.PORT | default "8080"}}'
@@ -36,12 +41,13 @@ tasks:
      AIENGINE_ENABLED: '{{.AIENGINE_ENABLED | default "false"}}'
      AIENGINE_TIMEOUTSECONDS: '{{.AIENGINE_TIMEOUTSECONDS | default "120"}}'
      SECURITY_ENABLELOGIN: '{{.SECURITY_ENABLELOGIN | default ""}}'
+      POLICIES_ENABLED: '{{.POLICIES_ENABLED | default ""}}'
    env:
      SERVER_PORT: '{{.PORT}}'
    cmds:
-      - cmd: '{{if .AIENGINE_URL}}AIENGINE_URL={{.AIENGINE_URL}} AIENGINE_ENABLED={{.AIENGINE_ENABLED}} AIENGINE_TIMEOUTSECONDS={{.AIENGINE_TIMEOUTSECONDS}} {{end}}{{if .SECURITY_ENABLELOGIN}}SECURITY_ENABLELOGIN={{.SECURITY_ENABLELOGIN}} {{end}}cmd /c ".\gradlew.bat :stirling-pdf:bootRun"'
+      - cmd: '{{if .AIENGINE_URL}}AIENGINE_URL={{.AIENGINE_URL}} AIENGINE_ENABLED={{.AIENGINE_ENABLED}} AIENGINE_TIMEOUTSECONDS={{.AIENGINE_TIMEOUTSECONDS}} {{end}}{{if .SECURITY_ENABLELOGIN}}SECURITY_ENABLELOGIN={{.SECURITY_ENABLELOGIN}} {{end}}{{if .POLICIES_ENABLED}}POLICIES_ENABLED={{.POLICIES_ENABLED}} {{end}}cmd /c ".\gradlew.bat :stirling-pdf:bootRun"'
        platforms: [windows]
-      - cmd: '{{if .AIENGINE_URL}}AIENGINE_URL={{.AIENGINE_URL}} AIENGINE_ENABLED={{.AIENGINE_ENABLED}} AIENGINE_TIMEOUTSECONDS={{.AIENGINE_TIMEOUTSECONDS}} {{end}}{{if .SECURITY_ENABLELOGIN}}SECURITY_ENABLELOGIN={{.SECURITY_ENABLELOGIN}} {{end}}./gradlew :stirling-pdf:bootRun'
+      - cmd: '{{if .AIENGINE_URL}}AIENGINE_URL={{.AIENGINE_URL}} AIENGINE_ENABLED={{.AIENGINE_ENABLED}} AIENGINE_TIMEOUTSECONDS={{.AIENGINE_TIMEOUTSECONDS}} {{end}}{{if .SECURITY_ENABLELOGIN}}SECURITY_ENABLELOGIN={{.SECURITY_ENABLELOGIN}} {{end}}{{if .POLICIES_ENABLED}}POLICIES_ENABLED={{.POLICIES_ENABLED}} {{end}}./gradlew :stirling-pdf:bootRun'
        platforms: [linux, darwin]

  dev:bundled:
@@ -5,6 +5,11 @@ vars:
  # NoClassDefFoundError: jdk/dynalink/Namespace at runtime in get-info-on-pdf and verify-pdf
  JLINK_MODULES: "java.base,java.compiler,java.desktop,java.instrument,java.logging,java.management,java.naming,java.net.http,java.prefs,java.rmi,java.scripting,java.security.jgss,java.security.sasl,java.sql,java.transaction.xa,java.xml,java.xml.crypto,jdk.crypto.ec,jdk.crypto.cryptoki,jdk.unsupported,jdk.dynalink"

+  # Minimum Java major the bundled JRE must be. Keep in sync with build.gradle
+  # `modernJavaVersion` - the app JAR is compiled for this, so an older runtime
+  # fails at launch with UnsupportedClassVersionError. Enforced by jlink:verify.
+  REQUIRED_JAVA: "25"
+
  # Override via JPDFIUM_PLATFORMS env (csv of platform keys, or 'all').
  JPDFIUM_PLATFORMS:
    sh: |
@@ -102,6 +107,20 @@ tasks:
  jlink:
    desc: "Build backend JAR and create JLink runtime for Tauri"
    deps: [jlink:jar, jlink:runtime]
+    # Runs after the runtime is in place. Lives here (not in jlink:runtime's
+    # cmds) so it still fires when jlink:runtime short-circuits on its `status:`
+    # check and reuses an existing runtime/jre - that reuse path is exactly how
+    # a stale, too-old JRE slips through.
+    cmds:
+      - task: jlink:verify
+
+  jlink:verify:
+    desc: "Fail the build if the bundled JRE is older than the app JAR requires"
+    dir: editor
+    env:
+      REQUIRED_JAVA: "{{.REQUIRED_JAVA}}"
+    cmds:
+      - node scripts/verify-bundled-jre.mjs src-tauri/runtime/jre/release

  jlink:jar:
    desc: "Build backend JAR for Tauri bundling (host-OS natives only by default)"
@@ -127,15 +146,35 @@ tasks:
    cmds:
      - rm -rf runtime/jre
      - mkdir -p runtime
-      - |
-        JLINK_COMPRESS="$(jlink --help 2>&1 | grep -q 'zip-\[0-9\]' && echo zip-6 || echo 2)"
-        jlink \
-          --add-modules {{.JLINK_MODULES}} \
-          --strip-debug \
-          --compress="$JLINK_COMPRESS" \
-          --no-header-files \
-          --no-man-pages \
-          --output runtime/jre
+      # Pin jlink to JAVA_HOME so the bundled JRE matches the JDK the build
+      # uses. Bare `jlink` on PATH can resolve to an older system Java (the
+      # ubuntu runner ships Java 11), producing a runtime jlink:verify rejects.
+      #
+      # jdk.crypto.mscapi (the Windows certificate store / SunMSCAPI provider, used by
+      # hardware-backed cert signing) is a Windows-only module - it only exists in a Windows
+      # JDK's jmods, so it is added on Windows only or jlink fails to resolve it elsewhere.
+      - cmd: |
+          JLINK="${JAVA_HOME:+$JAVA_HOME/bin/}jlink"
+          JLINK_COMPRESS="$("$JLINK" --help 2>&1 | grep -q 'zip-\[0-9\]' && echo zip-6 || echo 2)"
+          "$JLINK" \
+            --add-modules {{.JLINK_MODULES}},jdk.crypto.mscapi \
+            --strip-debug \
+            --compress="$JLINK_COMPRESS" \
+            --no-header-files \
+            --no-man-pages \
+            --output runtime/jre
+        platforms: [windows]
+      - cmd: |
+          JLINK="${JAVA_HOME:+$JAVA_HOME/bin/}jlink"
+          JLINK_COMPRESS="$("$JLINK" --help 2>&1 | grep -q 'zip-\[0-9\]' && echo zip-6 || echo 2)"
+          "$JLINK" \
+            --add-modules {{.JLINK_MODULES}} \
+            --strip-debug \
+            --compress="$JLINK_COMPRESS" \
+            --no-header-files \
+            --no-man-pages \
+            --output runtime/jre
+        platforms: [linux, darwin]
      # jlink emits its files mode 444 (read-only). Tauri's build-script
      # resource copier preserves source permissions when staging
      # `runtime/jre/**/*` into `target/<profile>/runtime/jre/...`, so the
@@ -55,6 +55,15 @@ tasks:
      - editor/src/core/data/ogImageMap.json
      - editor/public/og-metadata.json

+  prepare:classifier-categories:
+    internal: true
+    run: when_changed
+    desc: "Regenerate the engine classifier categories JSON from the TS source of truth"
+    cmds:
+      - npx tsx editor/scripts/generate-classification-taxonomy.mts
+    sources:
+      - editor/src/proprietary/data/classificationTaxonomy.ts
+
  prepare:
    desc: "Set up dev environment"
    run: when_changed
@@ -65,6 +74,7 @@ tasks:
        vars: { MODE: '{{.MODE}}' }
      - prepare:icons
      - prepare:og
+      - prepare:classifier-categories

  # ============================================================
  # Development
@@ -295,17 +305,26 @@ tasks:
    cmds:
      - task: typecheck:proprietary

+  typecheck:_run:
+    internal: true
+    env:
+      CI: '{{ .CI | default "false" }}'
+    cmds:
+      - '{{ if eq .CI "true" }}npx tsc{{ else }}npx tsgo{{ end }} --noEmit --project {{.PROJECT}}'
+
  typecheck:core:
    desc: "Typecheck core build variant"
    deps: [prepare]
    cmds:
-      - npx tsc --noEmit --project editor/src/core/tsconfig.json
+      - task: typecheck:_run
+        vars: { PROJECT: editor/src/core/tsconfig.json }

  typecheck:proprietary:
    desc: "Typecheck proprietary build variant"
    deps: [prepare]
    cmds:
-      - npx tsc --noEmit --project editor/src/proprietary/tsconfig.json
+      - task: typecheck:_run
+        vars: { PROJECT: editor/src/proprietary/tsconfig.json }

  typecheck:saas:
    desc: "Typecheck SaaS build variant"
@@ -313,7 +332,8 @@ tasks:
      - task: prepare
        vars: { MODE: saas }
    cmds:
-      - npx tsc --noEmit --project editor/src/saas/tsconfig.json
+      - task: typecheck:_run
+        vars: { PROJECT: editor/src/saas/tsconfig.json }

  typecheck:desktop:
    desc: "Typecheck desktop build variant"
@@ -321,38 +341,45 @@ tasks:
      - task: prepare
        vars: { MODE: desktop }
    cmds:
-      - npx tsc --noEmit --project editor/src/desktop/tsconfig.json
+      - task: typecheck:_run
+        vars: { PROJECT: editor/src/desktop/tsconfig.json }

  typecheck:cloud:
    desc: "Typecheck cloud shared layer (standalone)"
    deps: [prepare]
    cmds:
-      - npx tsc --noEmit --project editor/src/cloud/tsconfig.json
+      - task: typecheck:_run
+        vars: { PROJECT: editor/src/cloud/tsconfig.json }

  typecheck:scripts:
    desc: "Typecheck scripts"
    deps: [prepare]
    cmds:
-      - npx tsc --noEmit --project scripts/tsconfig.json
-      - npx tsc --noEmit --project editor/scripts/tsconfig.json
+      - task: typecheck:_run
+        vars: { PROJECT: scripts/tsconfig.json }
+      - task: typecheck:_run
+        vars: { PROJECT: editor/scripts/tsconfig.json }

  typecheck:prototypes:
    desc: "Typecheck prototypes build variant"
    deps: [prepare]
    cmds:
-      - npx tsc --noEmit --project editor/src/prototypes/tsconfig.json
+      - task: typecheck:_run
+        vars: { PROJECT: editor/src/prototypes/tsconfig.json }

  typecheck:portal:
    desc: "Typecheck developer portal build variant"
    deps: [install]
    cmds:
-      - npx tsc --noEmit --project portal/tsconfig.json
+      - task: typecheck:_run
+        vars: { PROJECT: portal/tsconfig.json }

  typecheck:shared:
    desc: "Typecheck the shared design system"
    deps: [install]
    cmds:
-      - npx tsc --noEmit --project shared/tsconfig.json
+      - task: typecheck:_run
+        vars: { PROJECT: shared/tsconfig.json }

  typecheck:all:
    desc: "Typecheck all build variants"
@@ -384,12 +411,23 @@ tasks:
    cmds:
      - node editor/scripts/generate-og-metadata.mjs --check

+  classifier-categories:
+    desc: "Regenerate the engine classifier categories JSON from the TS source"
+    cmds:
+      - npx tsx editor/scripts/generate-classification-taxonomy.mts
+
+  classifier-categories:check:
+    desc: "Fail if the committed classifier categories JSON is out of date"
+    cmds:
+      - npx tsx editor/scripts/generate-classification-taxonomy.mts --check
+
  check:all:
    desc: "Full CI quality gate"
    cmds:
      # Runs first, before prepare regenerates: guards the committed og-metadata.json /
      # ogImageMap.json that the Cloudflare Pages (plain `vite build`) deploy relies on.
      - task: og:check
+      - task: classifier-categories:check
      - task: typecheck:all
      - task: lint
      - task: format:check
@@ -404,10 +442,22 @@ tasks:

  test:
    desc: "Run tests"
+    cmds:
+      - task: test:editor
+      - task: test:portal
+
+  test:editor:
+    desc: "Run editor tests"
    deps: [prepare]
    cmds:
      - npx vitest run --root editor

+  test:portal:
+    desc: "Run portal tests"
+    deps: [prepare]
+    cmds:
+      - npx vitest run --root portal
+
  test:watch:
    desc: "Run tests in watch mode"
    deps: [prepare]
@@ -90,10 +90,12 @@ tasks:
        vars:
          PORT: '{{.BACKEND_PORT}}'
          SECURITY_ENABLELOGIN: "true"
+          POLICIES_ENABLED: "true"
      - task: frontend:dev:portal
        vars:
          PORT: '{{.PORTAL_PORT}}'
          BACKEND_URL: 'http://localhost:{{.BACKEND_PORT}}'
+          MOCKS: 'false'
          OPEN: "true"

  dev:portal:all:
@@ -109,12 +111,39 @@ tasks:
        vars:
          PORT: '{{.BACKEND_PORT}}'
          SECURITY_ENABLELOGIN: "true"
+          POLICIES_ENABLED: "true"
      - task: frontend:dev:portal
        vars:
          PORT: '{{.PORTAL_PORT}}'
          BACKEND_URL: 'http://localhost:{{.BACKEND_PORT}}'
          # Point the portal's "Editor" app switcher at the editor we spawn here.
          EDITOR_URL: 'http://localhost:{{.EDITOR_PORT}}/'
+          MOCKS: 'false'
+          OPEN: "true"
+      - task: frontend:dev
+        vars:
+          PORT: '{{.EDITOR_PORT}}'
+          BACKEND_URL: 'http://localhost:{{.BACKEND_PORT}}'
+
+  dev:portal:all:saas:
+    desc: "Start SaaS backend + developer portal + editor concurrently on free ports"
+    vars:
+      PORTS:
+        sh: '{{if eq OS "windows"}}{{.FIND_FREE_PORT_PS}} 8080 5173 5174{{else}}{{.FIND_FREE_PORT_SH}} 8080 5173 5174{{end}}'
+      BACKEND_PORT: '{{index (splitList "\n" .PORTS) 0}}'
+      PORTAL_PORT: '{{index (splitList "\n" .PORTS) 1}}'
+      EDITOR_PORT: '{{index (splitList "\n" .PORTS) 2}}'
+    deps:
+      - task: backend:dev:saas
+        vars:
+          PORT: '{{.BACKEND_PORT}}'
+          POLICIES_ENABLED: "true"
+      - task: frontend:dev:portal
+        vars:
+          PORT: '{{.PORTAL_PORT}}'
+          BACKEND_URL: 'http://localhost:{{.BACKEND_PORT}}'
+          EDITOR_URL: 'http://localhost:{{.EDITOR_PORT}}/'
+          MOCKS: 'false'
          OPEN: "true"
      - task: frontend:dev
        vars:
@@ -135,6 +164,7 @@ tasks:
        vars:
          PORT: '{{.BACKEND_PORT}}'
          SECURITY_ENABLELOGIN: "true"
+          POLICIES_ENABLED: "true"
      - task: frontend:dev:proprietary
        vars:
          PORT: '{{.EDITOR_PORT}}'
@@ -210,6 +240,7 @@ tasks:
        vars:
          PORT: '{{.BACKEND_PORT}}'
          SECURITY_ENABLELOGIN: "true"
+          POLICIES_ENABLED: "true"
      - task: frontend:preview:portal:proxy
        vars:
          PORT: '{{.PROXY_PORT}}'
@@ -0,0 +1,8 @@
+# Committed defaults for `task backend:dev:proprietary` (self-hosted / proprietary
+# flavor). Local overrides + secrets live in app/.env.proprietary.local (ignored).
+
+# Combined-billing account link (Mode A). Feature-flagged: OFF until release.
+# Flip to true in app/.env.proprietary.local to test linking locally.
+STIRLING_BILLING_ACCOUNT_LINK_ENABLED=false
+# SaaS base URL the linked instance calls (register + entitlement).
+STIRLING_BILLING_ACCOUNT_LINK_SAAS_BASE_URL=https://stirling.com/app
@@ -1,3 +1,4 @@
 # Whitelist committed env defaults. `.env.saas.local` (and any other .env*)
 # stays ignored via the root .gitignore.
 !.env.saas
+!.env.proprietary
@@ -29,13 +29,13 @@ spotless {
    }
 }
 dependencies {
-    api 'com.google.guava:guava:33.6.0-jre'
+    api "com.google.guava:guava:${guavaVersion}"
    api 'org.springframework.boot:spring-boot-starter-webmvc'
    api 'org.springframework.boot:spring-boot-starter-aspectj'
    api 'com.googlecode.owasp-java-html-sanitizer:owasp-java-html-sanitizer:20260313.1'
    api 'com.fathzer:javaluator:3.0.6'
    api 'com.posthog.java:posthog:1.2.0'
-    api 'org.apache.commons:commons-lang3:3.20.0'
+    api "org.apache.commons:commons-lang3:${commonsLang3}"
    api 'com.drewnoakes:metadata-extractor:2.20.0' // Image metadata extractor
    api 'com.vladsch.flexmark:flexmark-html2md-converter:0.64.8'
    api "org.apache.pdfbox:pdfbox:$pdfboxVersion"
@@ -60,7 +60,7 @@ dependencies {
        exclude group: 'com.google.code.gson', module: 'gson'
    }

-    api 'com.stirling:jpdfium:1.0.2'
+    api "com.stirling:jpdfium:${jpdfiumVersion}"

    // -PjpdfiumPlatforms=all|<csv of linux-x64,linux-arm64,darwin-x64,darwin-arm64,windows-x64>
    def jpdfiumPlatformsProp = (project.findProperty('jpdfiumPlatforms') ?: 'all').toString().trim()
@@ -75,12 +75,12 @@ dependencies {
    }
    logger.lifecycle("JPDFium native platforms: ${jpdfiumPlatforms.join(', ')}")
    jpdfiumPlatforms.each { platform ->
-        runtimeOnly "com.stirling:jpdfium-natives-${platform}:1.0.2"
+        runtimeOnly "com.stirling:jpdfium-natives-${platform}:${jpdfiumVersion}"
    }

    // Bucket4j (local in-process token bucket for RateLimitStore default impl)
-    implementation 'com.bucket4j:bucket4j_jdk17-core:8.19.0'
+    implementation "com.bucket4j:bucket4j_jdk17-core:${bucket4jVersion}"

    // ArchUnit: enforces module dependency direction (see ArchitectureTest)
-    testImplementation 'com.tngtech.archunit:archunit-junit5:1.4.2'
+    testImplementation "com.tngtech.archunit:archunit-junit5:${archunitVersion}"
 }
@@ -206,6 +206,11 @@ public class ApplicationProperties {

    @Data
    public static class Policies {
+        /**
+         * Master switch for the policy + sources subsystem (the PAYG-metered automation surface).
+         */
+        private boolean enabled = false;
+
        /**
         * Absolute directories that policy folder input sources and output sinks may read from or
         * write to. Empty (the default) disables folder access entirely, so a policy can never be
@@ -514,6 +519,14 @@ public class ApplicationProperties {
        private String accessibilityStatement;
        private String cookiePolicy;
        private String impressum;
+        private LoginAgreement loginAgreement = new LoginAgreement();
+
+        @Data
+        public static class LoginAgreement {
+            private boolean enabled = false;
+            private boolean showInAnonymousMode = true;
+            private String fallbackText = "";
+        }
    }

    @Data
@@ -582,7 +595,7 @@ public class ApplicationProperties {
        public static class SAML2 {
            private String provider;
            private Boolean enabled = false;
-            private Boolean autoCreateUser = false;
+            private Boolean autoCreateUser = true;
            private Boolean blockRegistration = false;
            private String registrationId = "stirling";

@@ -659,7 +672,7 @@ public class ApplicationProperties {
            private String issuer;
            private String clientId;
            @ToString.Exclude private String clientSecret;
-            private Boolean autoCreateUser = false;
+            private Boolean autoCreateUser = true;
            private Boolean blockRegistration = false;
            private String useAsUsername;
            private Collection<String> scopes = new ArrayList<>();
@@ -730,7 +743,6 @@ public class ApplicationProperties {
        @Data
        public static class Jwt {
            private boolean enableKeystore = true;
-            private boolean enableKeyRotation = false;
            private boolean enableKeyCleanup = true;

            /**
@@ -834,8 +846,8 @@ public class ApplicationProperties {
            @Data
            public static class Trust {
                private boolean serverAsAnchor = true;
-                private boolean useSystemTrust = false;
-                private boolean useMozillaBundle = false;
+                private boolean useSystemTrust = true;
+                private boolean useMozillaBundle = true;
                private boolean useAATL = false;
                private boolean useEUTL = false;
            }
@@ -869,8 +881,8 @@ public class ApplicationProperties {
    public static class System {
        private String defaultLocale;
        private boolean googlevisibility;
-        private boolean showUpdate;
-        private boolean showUpdateOnlyAdmin;
+        private boolean showUpdate = true;
+        private boolean showUpdateOnlyAdmin = true;
        private boolean showSettingsWhenNoLogin = true;
        private boolean customHTMLFiles;
        private String tessdataDir;
@@ -878,10 +890,10 @@ public class ApplicationProperties {
        private Boolean enableAnalytics;
        private Boolean enablePosthog;
        private Boolean enableScarf;
-        private Boolean enableDesktopInstallSlide;
+        private Boolean enableDesktopInstallSlide = true;
        private Datasource datasource;
        private boolean disableSanitize;
-        private int maxDPI;
+        private int maxDPI = 500;
        private boolean enableUrlToPDF;
        private Html html = new Html();
        private CustomPaths customPaths = new CustomPaths();
@@ -895,8 +907,9 @@ public class ApplicationProperties {
        private String frontendUrl; // Frontend URL for invite email links (e.g.

        // 'https://app.example.com'). If not set, falls back to backendUrl.
-        private boolean enableMobileScanner = false; // Enable mobile phone QR code upload feature
+        private boolean enableMobileScanner = true; // Enable mobile phone QR code upload feature
        private MobileScannerSettings mobileScannerSettings = new MobileScannerSettings();
+        private ServerCertificate serverCertificate = new ServerCertificate();

        @Data
        public static class MobileScannerSettings {
@@ -906,6 +919,16 @@ public class ApplicationProperties {
            private boolean stretchToFit = false; // Whether to stretch image to fill page
        }

+        @Data
+        public static class ServerCertificate {
+            private boolean enabled =
+                    true; // Enable server-side "Sign with Stirling-PDF" certificate
+            private String organizationName = "Stirling PDF Inc";
+            private int validity = 365; // Certificate validity in days
+            private boolean regenerateOnStartup =
+                    false; // Generate a new certificate on each startup
+        }
+
        public boolean isAnalyticsEnabled() {
            return this.enableAnalytics != null && this.enableAnalytics;
        }
@@ -990,7 +1013,7 @@ public class ApplicationProperties {
        @Data
        public static class Sharing {
            private boolean enabled = false;
-            private boolean linkEnabled = false;
+            private boolean linkEnabled = true;
            private boolean emailEnabled = false;
            private int linkExpirationDays = 3;
        }
@@ -1164,7 +1187,7 @@ public class ApplicationProperties {

    @Data
    public static class Metrics {
-        private boolean enabled;
+        private boolean enabled = true;
    }

    @Data
@@ -1216,7 +1239,7 @@ public class ApplicationProperties {
        private boolean enableInvites = false;
        private int inviteLinkExpiryHours = 72; // Default: 72 hours (3 days)
        private String host;
-        private int port;
+        private int port = 587;
        private String username;
        @ToString.Exclude private String password;
        private String from;
@@ -1243,10 +1266,10 @@ public class ApplicationProperties {
        @ToString.Exclude private String botToken;
        private String botUsername;
        private String pipelineInboxFolder = "telegram";
-        private Boolean customFolderSuffix = false;
-        private Boolean enableAllowUserIDs = false;
+        private Boolean customFolderSuffix = true;
+        private Boolean enableAllowUserIDs = true;
        private List<Long> allowUserIDs = new ArrayList<>();
-        private Boolean enableAllowChannelIDs = false;
+        private Boolean enableAllowChannelIDs = true;
        private List<Long> allowChannelIDs = new ArrayList<>();
        private long processingTimeoutSeconds = 180;
        private long pollingIntervalMillis = 2000;
@@ -0,0 +1,204 @@
+package stirling.software.common.service;
+
+import java.io.IOException;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.AtomicMoveNotSupportedException;
+import java.nio.file.Files;
+import java.nio.file.LinkOption;
+import java.nio.file.Path;
+import java.nio.file.StandardCopyOption;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Set;
+import java.util.TreeSet;
+import java.util.regex.Pattern;
+import java.util.stream.Stream;
+
+import org.springframework.stereotype.Service;
+
+import lombok.extern.slf4j.Slf4j;
+
+import stirling.software.common.configuration.InstallationPathConfig;
+import stirling.software.common.model.ApplicationProperties;
+
+// Resolves login agreement text from customFiles/disclaimer/<locale>.md (read live);
+// enable/visibility come from the legal.loginAgreement settings.
+@Service
+@Slf4j
+public class LoginAgreementService {
+
+    // Locale codes only: rejects path separators and dots so the value can never escape the
+    // disclaimer directory. Matches e.g. en, en-GB, fr-FR, zh-Hant, pt-BR.
+    private static final Pattern LOCALE_PATTERN =
+            Pattern.compile("^[A-Za-z]{2,3}([_-][A-Za-z0-9]{2,8})*$");
+
+    // BCP-47 tags are well under this; the cap also prevents the regex's repetition group
+    // from recursing far enough to overflow the stack on a hostile over-length input.
+    private static final int MAX_LOCALE_LENGTH = 35;
+
+    // Disclaimers are short markdown; cap the read so an oversized file can't be loaded
+    // wholesale into heap on every public request.
+    private static final long MAX_FILE_BYTES = 256 * 1024;
+
+    private final ApplicationProperties applicationProperties;
+
+    public LoginAgreementService(ApplicationProperties applicationProperties) {
+        this.applicationProperties = applicationProperties;
+    }
+
+    public boolean isEnabled() {
+        return config().isEnabled();
+    }
+
+    public boolean isShowInAnonymousMode() {
+        return config().isShowInAnonymousMode();
+    }
+
+    /**
+     * Resolve the markdown to show for the requested language, falling back through the base
+     * language, the configured default locale (and its base), then the configured fallbackText.
+     * Returns an empty string when nothing is configured.
+     */
+    public String resolveContent(String requestedLang) {
+        List<String> candidates = new ArrayList<>();
+        addLocaleCandidates(candidates, requestedLang);
+        addLocaleCandidates(candidates, applicationProperties.getSystem().getDefaultLocale());
+
+        for (String candidate : candidates) {
+            String content = readFileIfExists(candidate);
+            if (content != null && !content.isBlank()) {
+                return content;
+            }
+        }
+
+        String fallback = config().getFallbackText();
+        return fallback == null ? "" : fallback;
+    }
+
+    /**
+     * Admin read of a single locale's raw file. Returns null for an invalid locale, "" if absent.
+     */
+    public String readRawForLocale(String locale) {
+        if (!isValidLocale(locale)) {
+            return null;
+        }
+        String content = readFileIfExists(locale);
+        return content == null ? "" : content;
+    }
+
+    /** Admin write. Blank content deletes the file so it falls back cleanly. */
+    public void writeForLocale(String locale, String content) throws IOException {
+        Path file = resolveLocaleFile(locale);
+        if (file == null) {
+            throw new IllegalArgumentException("Invalid locale: " + locale);
+        }
+        if (content == null || content.isBlank()) {
+            Files.deleteIfExists(file);
+            return;
+        }
+        Files.createDirectories(file.getParent());
+        // Write to a sibling temp file then atomically swap, so a concurrent reader (the public
+        // /login-disclaimer fetch is lockless) never observes a truncated/partial file.
+        Path tmp = Files.createTempFile(file.getParent(), "disclaimer", ".md.tmp");
+        try {
+            Files.writeString(tmp, content, StandardCharsets.UTF_8);
+            try {
+                Files.move(
+                        tmp,
+                        file,
+                        StandardCopyOption.ATOMIC_MOVE,
+                        StandardCopyOption.REPLACE_EXISTING);
+            } catch (AtomicMoveNotSupportedException e) {
+                Files.move(tmp, file, StandardCopyOption.REPLACE_EXISTING);
+            }
+        } finally {
+            Files.deleteIfExists(tmp);
+        }
+    }
+
+    /** Locales that currently have a markdown file, for the admin editor. */
+    public Set<String> listLocalesWithContent() {
+        Set<String> result = new TreeSet<>();
+        Path dir = disclaimerDir();
+        if (!Files.isDirectory(dir)) {
+            return result;
+        }
+        try (Stream<Path> files = Files.list(dir)) {
+            files.filter(Files::isRegularFile)
+                    .map(path -> path.getFileName().toString())
+                    .filter(name -> name.endsWith(".md"))
+                    .map(name -> name.substring(0, name.length() - ".md".length()))
+                    .filter(this::isValidLocale)
+                    .forEach(result::add);
+        } catch (IOException e) {
+            log.warn("Failed listing login agreement files", e);
+        }
+        return result;
+    }
+
+    private ApplicationProperties.Legal.LoginAgreement config() {
+        return applicationProperties.getLegal().getLoginAgreement();
+    }
+
+    private Path disclaimerDir() {
+        return Path.of(InstallationPathConfig.getCustomFilesPath(), "disclaimer").normalize();
+    }
+
+    private void addLocaleCandidates(List<String> out, String locale) {
+        if (!isValidLocale(locale)) {
+            return;
+        }
+        if (!out.contains(locale)) {
+            out.add(locale);
+        }
+        String base = locale.split("[_-]", 2)[0];
+        if (!base.equals(locale) && !out.contains(base)) {
+            out.add(base);
+        }
+    }
+
+    private String readFileIfExists(String locale) {
+        Path file = resolveLocaleFile(locale);
+        if (file == null) {
+            return null;
+        }
+        try {
+            // NOFOLLOW_LINKS: a symlinked entry is treated as non-regular and skipped, so a
+            // planted symlink can't expose files outside the disclaimer dir via the public read.
+            if (Files.isRegularFile(file, LinkOption.NOFOLLOW_LINKS)) {
+                if (Files.size(file) > MAX_FILE_BYTES) {
+                    log.warn(
+                            "Login agreement file for locale {} exceeds {} bytes; ignoring",
+                            locale,
+                            MAX_FILE_BYTES);
+                    return null;
+                }
+                return Files.readString(file, StandardCharsets.UTF_8);
+            }
+        } catch (IOException e) {
+            log.warn("Failed reading login agreement file for locale {}", locale, e);
+        }
+        return null;
+    }
+
+    private Path resolveLocaleFile(String locale) {
+        if (!isValidLocale(locale)) {
+            return null;
+        }
+        Path dir = disclaimerDir();
+        Path file = dir.resolve(locale + ".md").normalize();
+        // Defence in depth: the regex already blocks separators, but confirm containment.
+        if (!file.startsWith(dir)) {
+            return null;
+        }
+        return file;
+    }
+
+    private boolean isValidLocale(String locale) {
+        // Length check BEFORE the regex: LOCALE_PATTERN's repetition group recurses one stack
+        // frame per repeat in java.util.regex, so an unbounded input could overflow the stack.
+        return locale != null
+                && locale.length() <= MAX_LOCALE_LENGTH
+                && LOCALE_PATTERN.matcher(locale).matches();
+    }
+}
@@ -7,6 +7,7 @@ import java.time.format.DateTimeFormatter;
 import java.util.Calendar;

 import org.apache.pdfbox.pdmodel.PDDocument;
+import org.apache.pdfbox.pdmodel.PDDocumentInformation;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.beans.factory.annotation.Qualifier;
 import org.springframework.stereotype.Service;
@@ -17,6 +18,11 @@ import stirling.software.common.model.PdfMetadata;
@Service
 public class PdfMetadataService {

+    /**
+     * ({@code {category, docType, typeConfidence, tags}}). Written by the classify-and-tag tool.
+     */
+    public static final String CLASSIFICATION_KEY = "StirlingPDFClassification";
+
    private final ApplicationProperties applicationProperties;
    private final String stirlingPDFLabel;
    private final UserServiceInterface userService;
@@ -177,4 +183,14 @@ public class PdfMetadataService {
        }
        pdf.getDocumentInformation().setAuthor(author);
    }
+
+    /**
+     * Write the document classifier's JSON result into the custom Info-dictionary field {@link
+     * #CLASSIFICATION_KEY}, leaving all other metadata untouched.
+     */
+    public void setClassificationMetadata(PDDocument pdf, String classificationJson) {
+        PDDocumentInformation info = pdf.getDocumentInformation();
+        info.setCustomMetadataValue(CLASSIFICATION_KEY, classificationJson);
+        pdf.setDocumentInformation(info);
+    }
 }
@@ -244,10 +244,7 @@ public class SvgSanitizer {
            return false;
        }

-        return normalized.startsWith("http://")
-                || normalized.startsWith("https://")
-                || normalized.startsWith("//")
-                || normalized.startsWith("file:");
+        return true;
    }

    private boolean isUrlAllowed(String url) {
@@ -0,0 +1,201 @@
+package stirling.software.common.service;
+
+import static org.junit.jupiter.api.Assertions.assertDoesNotThrow;
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.mockito.Mockito.mockStatic;
+
+import java.io.IOException;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.Path;
+
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.io.TempDir;
+import org.mockito.MockedStatic;
+
+import stirling.software.common.configuration.InstallationPathConfig;
+import stirling.software.common.model.ApplicationProperties;
+
+/**
+ * Unit tests for {@link LoginAgreementService}. The service resolves per-language markdown from
+ * {@code <customFiles>/disclaimer/<locale>.md}; here {@link
+ * InstallationPathConfig#getCustomFilesPath()} is mocked to a {@link TempDir} so file IO is
+ * isolated.
+ */
+class LoginAgreementServiceTest {
+
+    @TempDir Path customFilesDir;
+
+    private ApplicationProperties properties;
+    private ApplicationProperties.Legal.LoginAgreement config;
+    private LoginAgreementService service;
+    private Path disclaimerDir;
+
+    @BeforeEach
+    void setUp() {
+        properties = new ApplicationProperties();
+        config = properties.getLegal().getLoginAgreement();
+        service = new LoginAgreementService(properties);
+        disclaimerDir = customFilesDir.resolve("disclaimer");
+    }
+
+    /**
+     * Run {@code action} with InstallationPathConfig.getCustomFilesPath() pointing at the temp dir.
+     */
+    private void withMockedPath(Runnable action) {
+        try (MockedStatic<InstallationPathConfig> mocked =
+                mockStatic(InstallationPathConfig.class)) {
+            mocked.when(InstallationPathConfig::getCustomFilesPath)
+                    .thenReturn(customFilesDir.toString());
+            action.run();
+        }
+    }
+
+    private void writeFile(String locale, String content) throws IOException {
+        Files.createDirectories(disclaimerDir);
+        Files.writeString(disclaimerDir.resolve(locale + ".md"), content, StandardCharsets.UTF_8);
+    }
+
+    @Test
+    void flagsReflectConfig() {
+        config.setEnabled(true);
+        config.setShowInAnonymousMode(false);
+        assertTrue(service.isEnabled());
+        assertFalse(service.isShowInAnonymousMode());
+    }
+
+    @Test
+    void resolveContentReturnsExactLocaleFile() throws IOException {
+        writeFile("fr-FR", "# Avis");
+        withMockedPath(() -> assertEquals("# Avis", service.resolveContent("fr-FR")));
+    }
+
+    @Test
+    void resolveContentFallsBackToBaseLanguage() throws IOException {
+        // Only a language-only file exists; a region-specific request should fall back to it.
+        writeFile("de", "# Hinweis");
+        withMockedPath(() -> assertEquals("# Hinweis", service.resolveContent("de-DE")));
+    }
+
+    @Test
+    void resolveContentFallsBackToDefaultLocale() throws IOException {
+        properties.getSystem().setDefaultLocale("en-GB");
+        writeFile("en-GB", "# Notice");
+        // No file for the requested locale -> falls through to the configured default locale.
+        withMockedPath(() -> assertEquals("# Notice", service.resolveContent("es-ES")));
+    }
+
+    @Test
+    void resolveContentFallsBackToFallbackTextWhenNoFile() {
+        config.setFallbackText("# Fallback");
+        withMockedPath(() -> assertEquals("# Fallback", service.resolveContent("ja-JP")));
+    }
+
+    @Test
+    void resolveContentReturnsEmptyWhenNothingConfigured() {
+        withMockedPath(() -> assertEquals("", service.resolveContent("ja-JP")));
+    }
+
+    @Test
+    void resolveContentDoesNotEscapeDisclaimerDirectory() throws IOException {
+        // Plant a file outside the disclaimer dir; a traversal-style locale must not read it.
+        Files.writeString(
+                customFilesDir.resolve("secret.md"), "TOP SECRET", StandardCharsets.UTF_8);
+        config.setFallbackText("safe");
+        withMockedPath(
+                () -> {
+                    assertEquals("safe", service.resolveContent("../secret"));
+                    assertEquals("safe", service.resolveContent("..%2Fsecret"));
+                    assertEquals("safe", service.resolveContent("/etc/passwd"));
+                });
+    }
+
+    @Test
+    void readRawRejectsInvalidLocale() {
+        withMockedPath(
+                () -> {
+                    assertNull(service.readRawForLocale("../secret"));
+                    assertNull(service.readRawForLocale("en/GB"));
+                    assertNull(service.readRawForLocale("C:\\x"));
+                    assertNull(service.readRawForLocale(null));
+                });
+    }
+
+    @Test
+    void readRawReturnsEmptyForValidButAbsentLocale() {
+        withMockedPath(() -> assertEquals("", service.readRawForLocale("pt-BR")));
+    }
+
+    @Test
+    void overlongLocaleIsRejectedWithoutStackOverflow() {
+        // Guards against the regex-recursion stack overflow on unbounded input.
+        String hostile = "en" + "-ab".repeat(4000);
+        withMockedPath(
+                () -> {
+                    assertDoesNotThrow(() -> service.readRawForLocale(hostile));
+                    assertNull(service.readRawForLocale(hostile));
+                    assertDoesNotThrow(() -> service.resolveContent(hostile));
+                });
+    }
+
+    @Test
+    void writeThenReadRoundTrips() throws IOException {
+        withMockedPath(
+                () -> {
+                    assertDoesNotThrow(() -> service.writeForLocale("fr-FR", "# Bonjour"));
+                    assertEquals("# Bonjour", service.readRawForLocale("fr-FR"));
+                });
+        assertTrue(Files.isRegularFile(disclaimerDir.resolve("fr-FR.md")));
+    }
+
+    @Test
+    void writeBlankDeletesFile() throws IOException {
+        writeFile("fr-FR", "# Bonjour");
+        withMockedPath(
+                () -> {
+                    assertDoesNotThrow(() -> service.writeForLocale("fr-FR", "   "));
+                    assertEquals("", service.readRawForLocale("fr-FR"));
+                });
+        assertFalse(Files.exists(disclaimerDir.resolve("fr-FR.md")));
+    }
+
+    @Test
+    void writeRejectsInvalidLocale() {
+        withMockedPath(
+                () ->
+                        assertThrows(
+                                IllegalArgumentException.class,
+                                () -> service.writeForLocale("../escape", "x")));
+    }
+
+    @Test
+    void listLocalesWithContentReturnsOnlyValidMarkdownFiles() throws IOException {
+        writeFile("en-GB", "a");
+        writeFile("fr-FR", "b");
+        Files.writeString(disclaimerDir.resolve("notes.txt"), "x", StandardCharsets.UTF_8);
+        withMockedPath(
+                () -> {
+                    var locales = service.listLocalesWithContent();
+                    assertTrue(locales.contains("en-GB"));
+                    assertTrue(locales.contains("fr-FR"));
+                    assertEquals(2, locales.size());
+                });
+    }
+
+    @Test
+    void oversizedFileIsIgnored() throws IOException {
+        // Files beyond the read cap are skipped rather than loaded into heap.
+        byte[] big = new byte[300 * 1024];
+        java.util.Arrays.fill(big, (byte) 'x');
+        Files.createDirectories(disclaimerDir);
+        Files.write(disclaimerDir.resolve("en-GB.md"), big);
+        config.setFallbackText("small-fallback");
+        properties.getSystem().setDefaultLocale("en-GB");
+        withMockedPath(() -> assertEquals("small-fallback", service.resolveContent("en-GB")));
+    }
+}
@@ -97,4 +97,51 @@ class SvgSanitizerTest {
        byte[] invalid = "not xml at all".getBytes(StandardCharsets.UTF_8);
        assertThrows(IOException.class, () -> sanitizer.sanitize(invalid));
    }
+
+    @Test
+    void testSanitize_removesRootRelativeLocalPath() throws IOException {
+        when(ssrfProtectionService.isUrlAllowed(anyString())).thenReturn(false);
+        String svg =
+                "<svg xmlns=\"http://www.w3.org/2000/svg\">"
+                        + "<image href=\"/tmp/image.png\" width=\"10\" height=\"10\"/></svg>";
+        byte[] result = sanitizer.sanitize(svg.getBytes(StandardCharsets.UTF_8));
+        String output = new String(result, StandardCharsets.UTF_8);
+        assertFalse(output.contains("/tmp/image.png"), "Root-relative local path must be stripped");
+    }
+
+    @Test
+    void testSanitize_removesRelativeLocalPath() throws IOException {
+        when(ssrfProtectionService.isUrlAllowed(anyString())).thenReturn(false);
+        String svg =
+                "<svg xmlns=\"http://www.w3.org/2000/svg\">"
+                        + "<image href=\"../../assets/image.png\" width=\"10\" height=\"10\"/></svg>";
+        byte[] result = sanitizer.sanitize(svg.getBytes(StandardCharsets.UTF_8));
+        String output = new String(result, StandardCharsets.UTF_8);
+        assertFalse(output.contains("assets/image.png"), "Relative local path must be stripped");
+    }
+
+    @Test
+    void testSanitize_removesRootRelativeWindowsDrivePath() throws IOException {
+        when(ssrfProtectionService.isUrlAllowed(anyString())).thenReturn(false);
+        String svg =
+                "<svg xmlns=\"http://www.w3.org/2000/svg\" "
+                        + "xmlns:xlink=\"http://www.w3.org/1999/xlink\">"
+                        + "<image xlink:href=\"/C:/Users/x/external-image.svg\""
+                        + " width=\"10\" height=\"10\"/></svg>";
+        byte[] result = sanitizer.sanitize(svg.getBytes(StandardCharsets.UTF_8));
+        String output = new String(result, StandardCharsets.UTF_8);
+        assertFalse(
+                output.contains("external-image"), "Root-relative Windows path must be stripped");
+    }
+
+    @Test
+    void testSanitize_keepsInDocumentFragmentReference() throws IOException {
+        String svg =
+                "<svg xmlns=\"http://www.w3.org/2000/svg\">"
+                        + "<use href=\"#gradient\"/><rect width=\"10\" height=\"10\"/></svg>";
+        byte[] result = sanitizer.sanitize(svg.getBytes(StandardCharsets.UTF_8));
+        String output = new String(result, StandardCharsets.UTF_8);
+        assertTrue(
+                output.contains("#gradient"), "In-document fragment references must be preserved");
+    }
 }
@@ -67,7 +67,7 @@ dependencies {
        exclude group: 'com.fasterxml.jackson.jaxrs'
        exclude group: 'com.fasterxml.jackson.module', module: 'jackson-module-jaxb-annotations'
    }
-    implementation 'commons-io:commons-io:2.22.0'
+    implementation "commons-io:commons-io:$commonsIoVersion"
    implementation "org.bouncycastle:bcprov-jdk18on:$bouncycastleVersion"
    implementation "org.bouncycastle:bcpkix-jdk18on:$bouncycastleVersion"
    implementation 'io.micrometer:micrometer-core'
@@ -81,25 +81,24 @@ dependencies {

    implementation 'org.verapdf:validation-model:1.28.2'
    // CVE-2025-66453: Explicit rhino 1.7.15 to override verapdf's 1.7.13
-    implementation 'org.mozilla:rhino:1.9.1'
+    implementation "org.mozilla:rhino:${rhinoVersion}"

    // veraPDF still uses javax.xml.bind, not the new jakarta namespace
    implementation 'javax.xml.bind:jaxb-api:2.3.1'
    implementation 'com.sun.xml.bind:jaxb-impl:2.3.9'
    implementation 'com.sun.xml.bind:jaxb-core:4.0.7'
-    implementation 'org.apache.poi:poi-ooxml:5.5.1'

-    // CVE-2022-25647: Explicit gson 2.13.2 to prevent unsafe deserialization (tabula would pull 2.8.7)
-    implementation 'com.google.code.gson:gson:2.13.2'
+    // CVE-2022-25647: Explicit gson to prevent unsafe deserialization (tabula would pull 2.8.7)
+    implementation "com.google.code.gson:gson:${gsonVersion}"
    implementation 'org.apache.pdfbox:jbig2-imageio:3.0.4'
    implementation 'com.opencsv:opencsv:5.12.0' // https://mvnrepository.com/artifact/com.opencsv/opencsv
    implementation 'org.apache.poi:poi-ooxml:5.5.1'

    // Batik only bridge module needed (transitively pulls anim, gvt, util, css, dom, svg-dom)
    // Replaces batik-all which included unused codec, svggen, transcoder, script modules
-    implementation 'org.apache.xmlgraphics:batik-bridge:1.19'
+    implementation "org.apache.xmlgraphics:batik-bridge:${batikVersion}"
    // Required by TwelveMonkeys imageio-batik SPI (SVGImageReaderSpi) during ImageIO init
-    runtimeOnly 'org.apache.xmlgraphics:batik-transcoder:1.19'
+    runtimeOnly "org.apache.xmlgraphics:batik-transcoder:${batikVersion}"

    // PDFBox Graphics2D bridge for Batik SVG to PDF conversion
    implementation 'de.rototor.pdfbox:graphics2d:3.0.5'
@@ -24,12 +24,14 @@ import java.security.KeyStore;
 import java.security.KeyStoreException;
 import java.security.NoSuchAlgorithmException;
 import java.security.PrivateKey;
+import java.security.Provider;
 import java.security.UnrecoverableKeyException;
 import java.security.cert.Certificate;
 import java.security.cert.CertificateException;
 import java.security.cert.X509Certificate;
 import java.util.Arrays;
 import java.util.Enumeration;
+import java.util.Locale;

 import org.apache.pdfbox.pdmodel.interactive.digitalsignature.SignatureInterface;
 import org.bouncycastle.cert.jcajce.JcaCertStore;
@@ -50,6 +52,13 @@ public abstract class CreateSignatureBase implements SignatureInterface {
    @Getter private Certificate[] certificateChain;
    @Setter private String tsaUrl;

+    /**
+     * Provider that must service the signing operation. Set for hardware-held keys (SunPKCS11 for
+     * USB tokens, SunMSCAPI for the Windows store) so the {@link java.security.Signature} runs on
+     * the token. Left {@code null} for software keystores, which use the default provider.
+     */
+    @Setter private Provider signingProvider;
+
    /**
     * Specifies whether the external signing scenario should be used. If set to {@code true},
     * external signing will be performed and {@link SignatureInterface} will be used for signing.
@@ -80,25 +89,48 @@ public abstract class CreateSignatureBase implements SignatureInterface {
                    NoSuchAlgorithmException,
                    IOException,
                    CertificateException {
-        // grabs the first alias from the keystore and get the private key. An
-        // alternative method or constructor could be used for setting a specific
-        // alias that should be used.
+        this(keystore, pin, null);
+    }
+
+    /**
+     * Initialize the signature creator, optionally selecting a specific certificate by alias. A
+     * hardware token / the Windows store can hold several certificates, so the caller picks one;
+     * when {@code requestedAlias} is null the first usable entry is used (software keystore
+     * behaviour).
+     *
+     * @param keystore the keystore (software, PKCS#11 or Windows-MY)
+     * @param pin the keystore / token PIN, may be null for the Windows store
+     * @param requestedAlias the alias to sign with, or null to pick the first usable entry
+     */
+    public CreateSignatureBase(KeyStore keystore, char[] pin, String requestedAlias)
+            throws KeyStoreException,
+                    UnrecoverableKeyException,
+                    NoSuchAlgorithmException,
+                    IOException,
+                    CertificateException {
+        if (requestedAlias != null
+                && !requestedAlias.isBlank()
+                && keystore.containsAlias(requestedAlias)) {
+            privateKey = (PrivateKey) keystore.getKey(requestedAlias, pin);
+            certificateChain = resolveChain(keystore, requestedAlias);
+            if (certificateChain == null) {
+                throw new IOException("Could not find certificate for alias " + requestedAlias);
+            }
+            checkValidity(certificateChain[0]);
+            return;
+        }
+
+        // grabs the first alias from the keystore and gets the private key.
        Enumeration<String> aliases = keystore.aliases();
-        String alias;
        Certificate cert = null;
        while (cert == null && aliases.hasMoreElements()) {
-            alias = aliases.nextElement();
+            String alias = aliases.nextElement();
            privateKey = (PrivateKey) keystore.getKey(alias, pin);
-            Certificate[] certChain = keystore.getCertificateChain(alias);
+            Certificate[] certChain = resolveChain(keystore, alias);
            if (certChain != null) {
                certificateChain = certChain;
                cert = certChain[0];
-                if (cert instanceof X509Certificate) {
-                    // avoid expired certificate
-                    ((X509Certificate) cert).checkValidity();
-
-                    //// SigUtils.checkCertificateUsage((X509Certificate) cert);
-                }
+                checkValidity(cert);
            }
        }

@@ -107,6 +139,27 @@ public abstract class CreateSignatureBase implements SignatureInterface {
        }
    }

+    /**
+     * Resolve the certificate chain for an alias. PKCS#11 tokens and the Windows store frequently
+     * expose only the leaf certificate (a null chain), so fall back to the single certificate.
+     */
+    private static Certificate[] resolveChain(KeyStore keystore, String alias)
+            throws KeyStoreException {
+        Certificate[] chain = keystore.getCertificateChain(alias);
+        if (chain != null && chain.length > 0) {
+            return chain;
+        }
+        Certificate single = keystore.getCertificate(alias);
+        return single != null ? new Certificate[] {single} : null;
+    }
+
+    private static void checkValidity(Certificate cert) throws CertificateException {
+        if (cert instanceof X509Certificate x509Cert) {
+            // avoid expired certificate
+            x509Cert.checkValidity();
+        }
+    }
+
    public final void setPrivateKey(PrivateKey privateKey) {
        this.privateKey = privateKey;
    }
@@ -136,12 +189,18 @@ public abstract class CreateSignatureBase implements SignatureInterface {
        try {
            CMSSignedDataGenerator gen = new CMSSignedDataGenerator();
            X509Certificate cert = (X509Certificate) certificateChain[0];
-            ContentSigner sha1Signer =
-                    new JcaContentSignerBuilder("SHA256WithRSA").build(privateKey);
+            JcaContentSignerBuilder signerBuilder =
+                    new JcaContentSignerBuilder(resolveSignatureAlgorithm(privateKey, cert));
+            // Hardware keys (PKCS#11 / Windows store) must sign on their own provider so the
+            // operation runs on the token; software keys use the default provider.
+            if (signingProvider != null) {
+                signerBuilder.setProvider(signingProvider);
+            }
+            ContentSigner signer = signerBuilder.build(privateKey);
            gen.addSignerInfoGenerator(
                    new JcaSignerInfoGeneratorBuilder(
                                    new JcaDigestCalculatorProviderBuilder().build())
-                            .build(sha1Signer, cert));
+                            .build(signer, cert));
            gen.addCertificates(new JcaCertStore(Arrays.asList(certificateChain)));
            CMSProcessableInputStream msg = new CMSProcessableInputStream(content);
            CMSSignedData signedData = gen.generate(msg, false);
@@ -157,4 +216,26 @@ public abstract class CreateSignatureBase implements SignatureInterface {
            throw new IOException(e);
        }
    }
+
+    /**
+     * Pick a SHA-256 signature algorithm that matches the key type. RSA keeps the historical
+     * default; EC / EdDSA tokens are common, so they are handled too.
+     */
+    private static String resolveSignatureAlgorithm(PrivateKey key, X509Certificate cert) {
+        String alg = key.getAlgorithm();
+        if (alg == null || alg.isBlank()) {
+            alg = cert.getPublicKey().getAlgorithm();
+        }
+        alg = alg == null ? "" : alg.toUpperCase(Locale.ROOT);
+        if (alg.contains("ED25519") || alg.contains("EDDSA")) {
+            return "Ed25519";
+        }
+        if (alg.contains("EC")) { // EC, ECDSA
+            return "SHA256withECDSA";
+        }
+        if (alg.contains("DSA")) {
+            return "SHA256withDSA";
+        }
+        return "SHA256withRSA";
+    }
 }
@@ -85,7 +85,6 @@ public class WebMvcConfig implements WebMvcConfigurer {
                        "/icons/**",
                        "/modern-logo/**",
                        "/classic-logo/**",
-                        "/robots.txt",
                        "/3rdPartyLicenses.json",
                        "/pdfjs/**",
                        "/pdfjs-legacy/**",
@@ -3,9 +3,12 @@ package stirling.software.SPDF.controller.api;
 import java.io.IOException;
 import java.util.ArrayList;
 import java.util.Collections;
+import java.util.HashSet;
 import java.util.List;
 import java.util.Locale;
+import java.util.Set;

+import org.apache.pdfbox.cos.COSDictionary;
 import org.apache.pdfbox.pdmodel.PDDocument;
 import org.apache.pdfbox.pdmodel.PDPage;
 import org.apache.pdfbox.pdmodel.PDPageTree;
@@ -261,10 +264,19 @@ public class RearrangePagesPDFController {
                log.info("newPageOrder = {}", newPageOrder);
                log.info("totalPages = {}", totalPages);

-                // Snapshot the desired pages before mutating the source document's page tree.
+                // Snapshot desired pages before mutating the tree; clone repeats (e.g. DUPLICATE)
+                // so each slot is a distinct node, not one PDPage under multiple /Kids.
                List<PDPage> newPages = new ArrayList<>(newPageOrder.size());
+                Set<Integer> seenIndices = new HashSet<>();
                for (Integer idx : newPageOrder) {
-                    newPages.add(document.getPage(idx));
+                    PDPage page = document.getPage(idx);
+                    if (!seenIndices.add(idx)) {
+                        // Duplicate index: distinct page node sharing content/resources.
+                        COSDictionary clonedDict = new COSDictionary();
+                        clonedDict.addAll(page.getCOSObject());
+                        page = new PDPage(clonedDict);
+                    }
+                    newPages.add(page);
                }

                // Rearrange in-place on the source document rather than copying pages into a
@@ -22,6 +22,7 @@ import stirling.software.SPDF.config.InitialSetup;
 import stirling.software.SPDF.controller.api.security.TimestampController;
 import stirling.software.common.annotations.api.ConfigApi;
 import stirling.software.common.configuration.AppConfig;
+import stirling.software.common.configuration.interfaces.ShowAdminInterface;
 import stirling.software.common.model.ApplicationProperties;
 import stirling.software.common.service.ServerCertificateServiceInterface;
 import stirling.software.common.service.UserServiceInterface;
@@ -37,6 +38,7 @@ public class ConfigController {
    private final EndpointConfiguration endpointConfiguration;
    private final ServerCertificateServiceInterface serverCertificateService;
    private final UserServiceInterface userService;
+    private final ShowAdminInterface showAdmin;
    private final stirling.software.common.service.LicenseServiceInterface licenseService;
    private final stirling.software.SPDF.config.ExternalAppDepConfig externalAppDepConfig;

@@ -48,6 +50,8 @@ public class ConfigController {
                    ServerCertificateServiceInterface serverCertificateService,
            @org.springframework.beans.factory.annotation.Autowired(required = false)
                    UserServiceInterface userService,
+            @org.springframework.beans.factory.annotation.Autowired(required = false)
+                    ShowAdminInterface showAdmin,
            @org.springframework.beans.factory.annotation.Autowired(required = false)
                    stirling.software.common.service.LicenseServiceInterface licenseService,
            stirling.software.SPDF.config.ExternalAppDepConfig externalAppDepConfig) {
@@ -56,6 +60,7 @@ public class ConfigController {
        this.endpointConfiguration = endpointConfiguration;
        this.serverCertificateService = serverCertificateService;
        this.userService = userService;
+        this.showAdmin = showAdmin;
        this.licenseService = licenseService;
        this.externalAppDepConfig = externalAppDepConfig;
    }
@@ -315,6 +320,10 @@ public class ConfigController {
            configData.put(
                    "enableAlphaFunctionality",
                    applicationProperties.getSystem().isEnableAlphaFunctionality());
+            boolean shouldShowUpdate =
+                    applicationProperties.getSystem().isShowUpdate()
+                            && (showAdmin == null || showAdmin.getShowUpdateOnlyAdmins());
+            configData.put("shouldShowUpdate", shouldShowUpdate);
            configData.put(
                    "enableAnalytics", applicationProperties.getSystem().getEnableAnalytics());
            configData.put("enablePosthog", applicationProperties.getSystem().getEnablePosthog());
@@ -341,6 +350,18 @@ public class ConfigController {
                    "serverCertificateEnabled",
                    serverCertificateService != null && serverCertificateService.isEnabled());

+            // Hardware-backed signing (Windows store / USB PKCS#11 tokens) is only viable on the
+            // desktop bundle, where the backend runs locally in the user's session. The Tauri
+            // bundle signals this via STIRLING_PDF_TAURI_MODE (machineType is Server-jar there);
+            // the bare-jar desktop launcher signals it via a Client-* machineType.
+            boolean hardwareSigningAvailable =
+                    Boolean.parseBoolean(System.getProperty("STIRLING_PDF_TAURI_MODE", "false"));
+            if (!hardwareSigningAvailable && applicationContext.containsBean("machineType")) {
+                String mt = applicationContext.getBean("machineType", String.class);
+                hardwareSigningAvailable = mt != null && mt.startsWith("Client-");
+            }
+            configData.put("hardwareSigningAvailable", hardwareSigningAvailable);
+
            // Legal settings
            configData.put(
                    "termsAndConditions", applicationProperties.getLegal().getTermsAndConditions());
@@ -0,0 +1,49 @@
+package stirling.software.SPDF.controller.api.misc;
+
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+
+import io.swagger.v3.oas.annotations.Hidden;
+import io.swagger.v3.oas.annotations.Operation;
+
+import lombok.RequiredArgsConstructor;
+
+import stirling.software.common.annotations.api.ConfigApi;
+import stirling.software.common.service.LoginAgreementService;
+
+/**
+ * Serves the login agreement / disclaimer for the frontend. Shares the /api/v1/config access rules:
+ * it requires authentication when login is enabled (the modal is shown after login, never on the
+ * login screen) and is permit-all in anonymous/no-login mode and in SaaS. The text is read live
+ * from disk, so admin edits take effect on the next login without a restart.
+ */
+@ConfigApi
+@Hidden
+@RequiredArgsConstructor
+public class LoginDisclaimerController {
+
+    private final LoginAgreementService loginAgreementService;
+
+    @GetMapping("/login-disclaimer")
+    @Operation(
+            summary = "Get the login agreement/disclaimer",
+            description =
+                    "Returns whether the login agreement is enabled and, if so, the markdown to"
+                            + " display for the requested language.")
+    public LoginDisclaimerResponse getLoginDisclaimer(
+            @RequestParam(name = "lang", required = false) String lang) {
+        boolean showInAnonymousMode = loginAgreementService.isShowInAnonymousMode();
+        if (!loginAgreementService.isEnabled()) {
+            return new LoginDisclaimerResponse(false, showInAnonymousMode, "", "markdown");
+        }
+        String content = loginAgreementService.resolveContent(lang);
+        // Enabled but no resolvable text (no file for any candidate locale and no fallbackText):
+        // report disabled so clients don't try to render an empty agreement.
+        boolean hasContent = content != null && !content.isBlank();
+        return new LoginDisclaimerResponse(
+                hasContent, showInAnonymousMode, hasContent ? content : "", "markdown");
+    }
+
+    public record LoginDisclaimerResponse(
+            boolean enabled, boolean showInAnonymousMode, String content, String format) {}
+}
@@ -70,10 +70,13 @@ import io.micrometer.common.util.StringUtils;
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.tags.Tag;

+import jakarta.servlet.http.HttpServletRequest;
+
 import lombok.extern.slf4j.Slf4j;

 import stirling.software.SPDF.config.swagger.StandardPdfResponse;
 import stirling.software.SPDF.model.api.security.SignPDFWithCertRequest;
+import stirling.software.SPDF.service.HardwareKeyStoreService;
 import stirling.software.common.annotations.AutoJobPostMapping;
 import stirling.software.common.enumeration.ResourceWeight;
 import stirling.software.common.service.CustomPDFDocumentFactory;
@@ -109,14 +112,17 @@ public class CertSignController {
    private final CustomPDFDocumentFactory pdfDocumentFactory;
    private final ServerCertificateServiceInterface serverCertificateService;
    private final TempFileManager tempFileManager;
+    private final HardwareKeyStoreService hardwareKeyStoreService;

    public CertSignController(
            CustomPDFDocumentFactory pdfDocumentFactory,
            @Autowired(required = false) ServerCertificateServiceInterface serverCertificateService,
-            TempFileManager tempFileManager) {
+            TempFileManager tempFileManager,
+            HardwareKeyStoreService hardwareKeyStoreService) {
        this.pdfDocumentFactory = pdfDocumentFactory;
        this.serverCertificateService = serverCertificateService;
        this.tempFileManager = tempFileManager;
+        this.hardwareKeyStoreService = hardwareKeyStoreService;
    }

    public static void sign(
@@ -170,7 +176,8 @@ public class CertSignController {
                    "This endpoint accepts a PDF file, a digital certificate and related"
                            + " information to sign the PDF. It then returns the digitally signed PDF"
                            + " file. Input:PDF Output:PDF Type:SISO")
-    public ResponseEntity<Resource> signPDFWithCert(@ModelAttribute SignPDFWithCertRequest request)
+    public ResponseEntity<Resource> signPDFWithCert(
+            @ModelAttribute SignPDFWithCertRequest request, HttpServletRequest httpRequest)
            throws Exception {
        MultipartFile pdf = request.getFileInput();
        String certType = request.getCertType();
@@ -196,6 +203,8 @@ public class CertSignController {

        KeyStore ks = null;
        String keystorePassword = password;
+        Provider signingProvider = null;
+        HardwareKeyStoreService.Pkcs11Session pkcs11Session = null;

        switch (certType) {
            case "PEM":
@@ -245,6 +254,31 @@ public class CertSignController {
                ks = serverCertificateService.getServerKeyStore();
                keystorePassword = serverCertificateService.getServerCertificatePassword();
                break;
+            case "WINDOWS_STORE":
+                hardwareKeyStoreService.assertLocalDesktop(httpRequest);
+                ks = hardwareKeyStoreService.loadWindowsKeyStore();
+                signingProvider = hardwareKeyStoreService.windowsProvider();
+                // PIN is prompted by the Windows CSP / token middleware, not passed here.
+                keystorePassword = password;
+                break;
+            case "PKCS11":
+                hardwareKeyStoreService.assertLocalDesktop(httpRequest);
+                char[] pkcs11Pin = password != null ? password.toCharArray() : null;
+                try {
+                    pkcs11Session =
+                            hardwareKeyStoreService.openPkcs11(
+                                    request.getPkcs11LibraryPath(),
+                                    request.getPkcs11Slot(),
+                                    pkcs11Pin);
+                } finally {
+                    if (pkcs11Pin != null) {
+                        java.util.Arrays.fill(pkcs11Pin, '\0');
+                    }
+                }
+                ks = pkcs11Session.keyStore();
+                signingProvider = pkcs11Session.provider();
+                keystorePassword = password;
+                break;
            default:
                throw ExceptionUtils.createIllegalArgumentException(
                        "error.invalidArgument",
@@ -252,7 +286,9 @@ public class CertSignController {
                        "certificate type: " + certType);
        }

-        CreateSignature createSignature = new CreateSignature(ks, keystorePassword.toCharArray());
+        char[] pin = keystorePassword != null ? keystorePassword.toCharArray() : null;
+        CreateSignature createSignature =
+                new CreateSignature(ks, pin, request.getAlias(), signingProvider);
        TempFile signedOut = tempFileManager.createManagedTempFile(".pdf");
        try (OutputStream os = new FileOutputStream(signedOut.getFile())) {
            sign(
@@ -269,6 +305,14 @@ public class CertSignController {
        } catch (IOException e) {
            signedOut.close();
            throw e;
+        } finally {
+            // Clear the PIN copy and log out the token session once signing is done.
+            if (pin != null) {
+                java.util.Arrays.fill(pin, '\0');
+            }
+            if (pkcs11Session != null) {
+                pkcs11Session.close();
+            }
        }
        // Return the signed PDF
        return WebResponseUtils.pdfFileToWebResponse(
@@ -324,7 +368,22 @@ public class CertSignController {
                        NoSuchAlgorithmException,
                        IOException,
                        CertificateException {
-            super(keystore, pin);
+            this(keystore, pin, null, null);
+        }
+
+        public CreateSignature(
+                KeyStore keystore, char[] pin, String alias, Provider signingProvider)
+                throws KeyStoreException,
+                        UnrecoverableKeyException,
+                        NoSuchAlgorithmException,
+                        IOException,
+                        CertificateException {
+            super(keystore, pin, alias);
+            setSigningProvider(signingProvider);
+            loadLogo();
+        }
+
+        private void loadLogo() throws IOException {
            ClassPathResource resource = new ClassPathResource("static/images/signature.png");
            try (InputStream is = resource.getInputStream()) {
                logoFile = Files.createTempFile("signature", ".png").toFile();
@@ -305,6 +305,23 @@ public class GetInfoOnPDF {
        }
    }

+    /**
+     * Info-dictionary keys exposed above via typed getters; any other key in the dictionary is
+     * surfaced as custom metadata (e.g. the classification policy's StirlingPDFClassification
+     * entry).
+     */
+    private static final java.util.Set<String> STANDARD_INFO_KEYS =
+            java.util.Set.of(
+                    "Title",
+                    "Author",
+                    "Subject",
+                    "Keywords",
+                    "Producer",
+                    "Creator",
+                    "CreationDate",
+                    "ModDate",
+                    "Trapped");
+
    private static ObjectNode extractMetadata(PDDocument document) {
        ObjectNode metadata = objectMapper.createObjectNode();

@@ -335,6 +352,18 @@ public class GetInfoOnPDF {
                if (modificationDate != null) {
                    metadata.put("ModificationDate", modificationDate);
                }
+
+                // Surface custom Info-dictionary entries (anything beyond the
+                // standard fields above) — e.g. StirlingPDFClassification
+                for (String key : info.getMetadataKeys()) {
+                    if (STANDARD_INFO_KEYS.contains(key)) {
+                        continue;
+                    }
+                    String value = info.getCustomMetadataValue(key);
+                    if (value != null && !value.isBlank()) {
+                        metadata.put(key, value);
+                    }
+                }
            }
        } catch (Exception e) {
            log.error("Error extracting metadata: {}", e.getMessage());
@@ -0,0 +1,85 @@
+package stirling.software.SPDF.controller.api.security;
+
+import java.util.List;
+
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
+
+import jakarta.servlet.http.HttpServletRequest;
+
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+
+import stirling.software.SPDF.model.api.security.HardwareCertificateInfo;
+import stirling.software.SPDF.model.api.security.HardwareSigningCapabilities;
+import stirling.software.SPDF.model.api.security.Pkcs11CertificatesRequest;
+import stirling.software.SPDF.service.HardwareKeyStoreService;
+
+/**
+ * Lets the desktop frontend discover which hardware-backed signing options the local backend can
+ * reach (Windows certificate store, plugged-in USB / PKCS#11 tokens) and enumerate the certificates
+ * available to sign with. Enumeration endpoints are restricted to the desktop bundle, reached over
+ * loopback - see {@link HardwareKeyStoreService#assertLocalDesktop}.
+ */
+@RestController
+@RequestMapping("/api/v1/security/cert-sign/hardware")
+@RequiredArgsConstructor
+@Slf4j
+@Tag(name = "Security", description = "Security APIs")
+public class HardwareSigningController {
+
+    private final HardwareKeyStoreService hardwareKeyStoreService;
+
+    @GetMapping("/capabilities")
+    @Operation(
+            summary = "Hardware signing capabilities",
+            description =
+                    "Reports whether hardware-backed signing is available on this device and which"
+                            + " PKCS#11 driver libraries were detected. Returns desktop=false when"
+                            + " not running as the desktop app.")
+    public ResponseEntity<HardwareSigningCapabilities> getCapabilities() {
+        return ResponseEntity.ok(hardwareKeyStoreService.capabilities());
+    }
+
+    @GetMapping("/windows-certificates")
+    @Operation(
+            summary = "List Windows certificate store signing certificates",
+            description =
+                    "Enumerates certificates with a usable private key from the current user's"
+                            + " Windows certificate store. Desktop-only, loopback-only.")
+    public ResponseEntity<List<HardwareCertificateInfo>> getWindowsCertificates(
+            HttpServletRequest request) throws Exception {
+        hardwareKeyStoreService.assertLocalDesktop(request);
+        return ResponseEntity.ok(hardwareKeyStoreService.listWindowsCertificates());
+    }
+
+    @PostMapping("/pkcs11-certificates")
+    @Operation(
+            summary = "List PKCS#11 token signing certificates",
+            description =
+                    "Logs into a PKCS#11 token with the supplied PIN and enumerates its signing"
+                            + " certificates. The PIN is used only for this call. Desktop-only,"
+                            + " loopback-only.")
+    public ResponseEntity<List<HardwareCertificateInfo>> getPkcs11Certificates(
+            HttpServletRequest request, @RequestBody Pkcs11CertificatesRequest body)
+            throws Exception {
+        hardwareKeyStoreService.assertLocalDesktop(request);
+        char[] pin = body.pin() != null ? body.pin().toCharArray() : null;
+        try {
+            return ResponseEntity.ok(
+                    hardwareKeyStoreService.listPkcs11Certificates(
+                            body.libraryPath(), body.slot(), pin));
+        } finally {
+            if (pin != null) {
+                java.util.Arrays.fill(pin, '\0');
+            }
+        }
+    }
+}
@@ -102,8 +102,27 @@ public class ValidateSignatureController {
        try (PDDocument document = pdfDocumentFactory.load(file.getInputStream())) {
            List<PDSignature> signatures = document.getSignatureDictionaries();

+            // Detect content appended outside every signature's ByteRange (added after signing). A
+            // properly signed document has its last signature cover all the way to EOF; if the
+            // furthest any signature reaches stops short of the file length, the tail is unsigned.
+            // Taking the max across all signatures avoids false positives on legitimately
+            // multi-signed PDFs, where an earlier signature intentionally omits later revisions.
+            long fileLength = file.getSize();
+            long maxCovered = 0;
+            for (PDSignature sig : signatures) {
+                int[] byteRange = sig.getByteRange();
+                if (byteRange != null && byteRange.length == 4) {
+                    long end = (long) byteRange[2] + byteRange[3];
+                    if (end > maxCovered) {
+                        maxCovered = end;
+                    }
+                }
+            }
+            boolean documentCovered = maxCovered <= 0 || maxCovered >= fileLength;
+
            for (PDSignature sig : signatures) {
                SignatureValidationResult result = new SignatureValidationResult();
+                result.setCoversEntireDocument(documentCovered);

                try {
                    byte[] signedContent = sig.getSignedContent(file.getInputStream());
@@ -0,0 +1,30 @@
+package stirling.software.SPDF.controller.web;
+
+import org.springframework.http.MediaType;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.ResponseBody;
+import org.springframework.web.bind.annotation.RestController;
+
+import stirling.software.common.model.ApplicationProperties;
+
+/**
+ * Serves /robots.txt dynamically so the system.googlevisibility flag actually controls
+ * search-engine indexing. 'true' returns an allow-all policy; 'false' returns a disallow-all policy
+ * to keep the instance out of search engines (useful for embedded/internal deployments).
+ */
+@RestController
+public class RobotsController {
+
+    private final ApplicationProperties applicationProperties;
+
+    public RobotsController(ApplicationProperties applicationProperties) {
+        this.applicationProperties = applicationProperties;
+    }
+
+    @GetMapping(value = "/robots.txt", produces = MediaType.TEXT_PLAIN_VALUE)
+    @ResponseBody
+    public String robotsTxt() {
+        boolean allowIndexing = applicationProperties.getSystem().isGooglevisibility();
+        return "User-agent: *\n" + (allowIndexing ? "Allow: /\n" : "Disallow: /\n");
+    }
+}
@@ -0,0 +1,21 @@
+package stirling.software.SPDF.model.api.security;
+
+/**
+ * Metadata for a single signing certificate discovered on a hardware source (Windows certificate
+ * store or a PKCS#11 token). Returned to the desktop frontend so the user can pick which
+ * certificate to sign with. Never carries private key material - signing always happens on the
+ * token / OS.
+ */
+public record HardwareCertificateInfo(
+        String alias,
+        String source,
+        String subject,
+        String issuer,
+        String subjectCommonName,
+        String issuerCommonName,
+        String serialNumber,
+        String keyAlgorithm,
+        String notBefore,
+        String notAfter,
+        boolean expired,
+        boolean notYetValid) {}
@@ -0,0 +1,19 @@
+package stirling.software.SPDF.model.api.security;
+
+import java.util.List;
+
+/**
+ * Describes what hardware-backed signing the local backend can offer. Only meaningful on the
+ * desktop bundle, where the backend runs as a local sidecar in the signed-in user's session and can
+ * reach the Windows certificate store / a plugged-in USB PKCS#11 token.
+ */
+public record HardwareSigningCapabilities(
+        boolean desktop,
+        String osName,
+        boolean windowsStoreSupported,
+        boolean pkcs11Supported,
+        List<Pkcs11LibraryInfo> detectedLibraries) {
+
+    /** A PKCS#11 driver library detected on disk (or supplied via configuration). */
+    public record Pkcs11LibraryInfo(String name, String path) {}
+}
@@ -0,0 +1,7 @@
+package stirling.software.SPDF.model.api.security;
+
+/**
+ * Request body for enumerating the certificates on a PKCS#11 token. The PIN is required to log into
+ * the token; it is used only for the duration of the call and never stored.
+ */
+public record Pkcs11CertificatesRequest(String libraryPath, Integer slot, String pin) {}
@@ -14,8 +14,10 @@ import stirling.software.common.model.api.PDFFile;
 public class SignPDFWithCertRequest extends PDFFile {

    @Schema(
-            description = "The type of the digital certificate",
-            allowableValues = {"PEM", "PKCS12", "PFX", "JKS", "SERVER"},
+            description =
+                    "The type of the digital certificate. WINDOWS_STORE and PKCS11 are"
+                            + " hardware-backed and only available in the desktop app.",
+            allowableValues = {"PEM", "PKCS12", "PFX", "JKS", "SERVER", "WINDOWS_STORE", "PKCS11"},
            requiredMode = Schema.RequiredMode.REQUIRED)
    private String certType;

@@ -39,9 +41,31 @@ public class SignPDFWithCertRequest extends PDFFile {
    @Schema(description = "The JKS keystore file (Java Key Store)")
    private MultipartFile jksFile;

-    @Schema(description = "The password for the keystore or the private key", format = "password")
+    @Schema(
+            description =
+                    "The password for the keystore / private key, or the token PIN for PKCS11",
+            format = "password")
    private String password;

+    @Schema(
+            description =
+                    "The alias of the certificate to sign with. Required for WINDOWS_STORE and"
+                            + " recommended for PKCS11 tokens holding multiple certificates.")
+    private String alias;
+
+    @Schema(
+            description =
+                    "Absolute path to the PKCS#11 driver library (required for PKCS11 type). Must"
+                            + " be an allowed driver - a detected one or configured via"
+                            + " STIRLING_PKCS11_LIBRARIES.")
+    private String pkcs11LibraryPath;
+
+    @Schema(
+            description =
+                    "Optional PKCS#11 slot index. When omitted the first slot with a token is"
+                            + " used.")
+    private Integer pkcs11Slot;
+
    @Schema(
            description = "Whether to visually show the signature in the PDF file",
            defaultValue = "false",
@@ -18,6 +18,11 @@ public class SignatureValidationResult {
    // Time validation
    private boolean notExpired;

+    // Whether the document's signatures cover all of its bytes. False when content was appended
+    // outside every signature's ByteRange (i.e. added after signing), which the signature can't
+    // attest to even though the signed bytes themselves remain cryptographically intact.
+    private boolean coversEntireDocument = true;
+
    // Revocation validation
    private boolean revocationChecked; // true if PKIX revocation was enabled
    private String revocationStatus; // "not-checked" | "good" | "revoked" | "soft-fail" | "unknown"
@@ -115,7 +115,8 @@ public class CertificateValidationService {
            log.info("Enabled AIA certificate fetching and revocation checking");
        }

-        // Trust only what we explicitly opt into:
+        // Trust only what we explicitly opt into. Desktop follows the same flags as the server -
+        // our own signing cert is trusted via serverAsAnchor, not by force-loading every system CA.
        if (validation.getTrust().isServerAsAnchor()) loadServerCertAsAnchor();
        if (validation.getTrust().isUseSystemTrust()) loadJavaSystemTrustStore();
        if (validation.getTrust().isUseMozillaBundle()) loadBundledMozillaCACerts();
@@ -0,0 +1,483 @@
+package stirling.software.SPDF.service;
+
+import java.net.InetAddress;
+import java.net.NetworkInterface;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.security.KeyStore;
+import java.security.Provider;
+import java.security.Security;
+import java.security.cert.Certificate;
+import java.security.cert.X509Certificate;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.Enumeration;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Locale;
+import java.util.Map;
+import java.util.Set;
+import java.util.stream.Collectors;
+
+import javax.security.auth.x500.X500Principal;
+
+import org.bouncycastle.asn1.x500.RDN;
+import org.bouncycastle.asn1.x500.X500Name;
+import org.bouncycastle.asn1.x500.style.BCStyle;
+import org.bouncycastle.asn1.x500.style.IETFUtils;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.beans.factory.annotation.Qualifier;
+import org.springframework.stereotype.Service;
+
+import jakarta.servlet.http.HttpServletRequest;
+
+import lombok.extern.slf4j.Slf4j;
+
+import stirling.software.SPDF.model.api.security.HardwareCertificateInfo;
+import stirling.software.SPDF.model.api.security.HardwareSigningCapabilities;
+import stirling.software.SPDF.model.api.security.HardwareSigningCapabilities.Pkcs11LibraryInfo;
+import stirling.software.common.util.ExceptionUtils;
+
+/**
+ * Bridges PDF signing to hardware-held keys: the Windows certificate store (via the JDK SunMSCAPI
+ * provider) and USB / smart-card PKCS#11 tokens (via SunPKCS11). The private key never leaves the
+ * token - the JCA routes the actual signing operation onto the hardware.
+ *
+ * <p>These code paths are gated to the desktop bundle. On a hosted server the backend cannot reach
+ * a remote user's USB token anyway, and loading an arbitrary PKCS#11 driver library is effectively
+ * native code execution, so PKCS#11 libraries are additionally restricted to an allowlist of
+ * detected / configured driver paths.
+ */
+@Service
+@Slf4j
+public class HardwareKeyStoreService {
+
+    public static final String SOURCE_WINDOWS_STORE = "WINDOWS_STORE";
+    public static final String SOURCE_PKCS11 = "PKCS11";
+
+    private static final String WINDOWS_KEYSTORE_TYPE = "Windows-MY";
+    private static final String MSCAPI_PROVIDER = "SunMSCAPI";
+    private static final String PKCS11_BASE_PROVIDER = "SunPKCS11";
+
+    /** Extra PKCS#11 driver libraries, absolute paths, comma/`File.pathSeparator` separated. */
+    private static final String PKCS11_LIBRARIES_ENV = "STIRLING_PKCS11_LIBRARIES";
+
+    /** Same as {@link #PKCS11_LIBRARIES_ENV} but as a JVM system property. */
+    private static final String PKCS11_LIBRARIES_PROP = "stirling.pkcs11.libraries";
+
+    private final String machineType;
+
+    public HardwareKeyStoreService(
+            @Autowired(required = false) @Qualifier("machineType") String machineType) {
+        this.machineType = machineType;
+    }
+
+    // ---------------------------------------------------------------------
+    // Gating
+    // ---------------------------------------------------------------------
+
+    /**
+     * True when running as the desktop bundle (local sidecar in the user's session). The Tauri
+     * bundle sets {@code STIRLING_PDF_TAURI_MODE=true} (with {@code BROWSER_OPEN=false}, so
+     * machineType is {@code Server-jar} there); the bare-jar desktop launcher instead yields a
+     * {@code Client-*} machineType. Accept either.
+     */
+    public boolean isDesktop() {
+        if (Boolean.parseBoolean(System.getProperty("STIRLING_PDF_TAURI_MODE", "false"))) {
+            return true;
+        }
+        return machineType != null && machineType.startsWith("Client-");
+    }
+
+    public boolean isWindows() {
+        return System.getProperty("os.name", "").toLowerCase(Locale.ROOT).contains("win");
+    }
+
+    private boolean windowsStoreSupported() {
+        return isWindows() && Security.getProvider(MSCAPI_PROVIDER) != null;
+    }
+
+    private boolean pkcs11Supported() {
+        return Security.getProvider(PKCS11_BASE_PROVIDER) != null;
+    }
+
+    /** Reject anything that is not the desktop bundle reached over loopback. */
+    public void assertLocalDesktop(HttpServletRequest request) {
+        if (!isDesktop()) {
+            throw ExceptionUtils.createIllegalArgumentException(
+                    "error.hardwareSigningDesktopOnly",
+                    "Hardware-backed signing is only available in the Stirling PDF desktop app");
+        }
+        if (request != null && !isLocalRequest(request.getRemoteAddr())) {
+            throw ExceptionUtils.createIllegalArgumentException(
+                    "error.hardwareSigningLocalOnly",
+                    "Hardware-backed signing can only be used from this device");
+        }
+    }
+
+    /**
+     * True when the request originates from this machine. Loopback (incl. IPv4-mapped IPv6 like
+     * {@code ::ffff:127.0.0.1}) counts, as does any address bound to a local interface - so it
+     * works whether the desktop app reaches the sidecar over {@code localhost} or a LAN IP, while
+     * still rejecting other machines on the network.
+     */
+    static boolean isLocalRequest(String remoteAddr) {
+        if (remoteAddr == null || remoteAddr.isBlank()) {
+            return false;
+        }
+        try {
+            InetAddress addr = InetAddress.getByName(remoteAddr);
+            if (addr.isLoopbackAddress() || addr.isAnyLocalAddress()) {
+                return true;
+            }
+            return NetworkInterface.networkInterfaces()
+                    .anyMatch(nif -> nif.inetAddresses().anyMatch(local -> local.equals(addr)));
+        } catch (Exception e) {
+            return false;
+        }
+    }
+
+    // ---------------------------------------------------------------------
+    // Capabilities
+    // ---------------------------------------------------------------------
+
+    public HardwareSigningCapabilities capabilities() {
+        boolean desktop = isDesktop();
+        if (!desktop) {
+            return new HardwareSigningCapabilities(false, "", false, false, List.of());
+        }
+        return new HardwareSigningCapabilities(
+                true,
+                System.getProperty("os.name", ""),
+                windowsStoreSupported(),
+                pkcs11Supported(),
+                detectPkcs11Libraries());
+    }
+
+    /**
+     * Known driver install locations plus any paths configured via {@code
+     * STIRLING_PKCS11_LIBRARIES}.
+     */
+    public List<Pkcs11LibraryInfo> detectPkcs11Libraries() {
+        Map<String, List<String>> candidates = new LinkedHashMap<>();
+        String os = System.getProperty("os.name", "").toLowerCase(Locale.ROOT);
+
+        if (os.contains("win")) {
+            candidates.put(
+                    "OpenSC",
+                    List.of(
+                            "C:\\Program Files\\OpenSC Project\\OpenSC\\pkcs11\\opensc-pkcs11.dll"));
+            candidates.put(
+                    "YubiKey (ykcs11)",
+                    List.of("C:\\Program Files\\Yubico\\Yubico PIV Tool\\bin\\libykcs11.dll"));
+            candidates.put("SafeNet eToken", List.of("C:\\Windows\\System32\\eTPKCS11.dll"));
+            candidates.put(
+                    "Thales/Gemalto IDPrime", List.of("C:\\Windows\\System32\\IDPrimePKCS11.dll"));
+            candidates.put(
+                    "SoftHSM2",
+                    List.of(
+                            "C:\\Program Files\\SoftHSM2\\lib\\softhsm2-x64.dll",
+                            "C:\\SoftHSM2\\lib\\softhsm2-x64.dll"));
+        } else if (os.contains("mac")) {
+            candidates.put(
+                    "OpenSC",
+                    List.of(
+                            "/Library/OpenSC/lib/opensc-pkcs11.so",
+                            "/usr/local/lib/opensc-pkcs11.so"));
+            candidates.put(
+                    "YubiKey (ykcs11)",
+                    List.of("/usr/local/lib/libykcs11.dylib", "/opt/homebrew/lib/libykcs11.dylib"));
+            candidates.put(
+                    "SoftHSM2",
+                    List.of(
+                            "/usr/local/lib/softhsm/libsofthsm2.so",
+                            "/opt/homebrew/lib/softhsm/libsofthsm2.so"));
+        } else {
+            candidates.put(
+                    "OpenSC",
+                    List.of(
+                            "/usr/lib/x86_64-linux-gnu/opensc-pkcs11.so",
+                            "/usr/lib/opensc-pkcs11.so",
+                            "/usr/lib64/opensc-pkcs11.so"));
+            candidates.put(
+                    "YubiKey (ykcs11)",
+                    List.of(
+                            "/usr/lib/x86_64-linux-gnu/libykcs11.so",
+                            "/usr/local/lib/libykcs11.so"));
+            candidates.put(
+                    "SoftHSM2",
+                    List.of(
+                            "/usr/lib/softhsm/libsofthsm2.so",
+                            "/usr/lib64/softhsm/libsofthsm2.so",
+                            "/usr/local/lib/softhsm/libsofthsm2.so"));
+        }
+
+        List<Pkcs11LibraryInfo> result = new ArrayList<>();
+        candidates.forEach(
+                (name, paths) ->
+                        paths.stream()
+                                .filter(p -> Files.exists(Path.of(p)))
+                                .findFirst()
+                                .ifPresent(p -> result.add(new Pkcs11LibraryInfo(name, p))));
+
+        for (String configured : configuredLibraries()) {
+            if (Files.exists(Path.of(configured))
+                    && result.stream().noneMatch(l -> sameFile(l.path(), configured))) {
+                result.add(new Pkcs11LibraryInfo(fileName(configured), configured));
+            }
+        }
+        return result;
+    }
+
+    private static List<String> configuredLibraries() {
+        String env = System.getenv(PKCS11_LIBRARIES_ENV);
+        String prop = System.getProperty(PKCS11_LIBRARIES_PROP);
+        StringBuilder combined = new StringBuilder();
+        if (env != null && !env.isBlank()) {
+            combined.append(env);
+        }
+        if (prop != null && !prop.isBlank()) {
+            if (combined.length() > 0) {
+                combined.append(java.io.File.pathSeparator);
+            }
+            combined.append(prop);
+        }
+        if (combined.length() == 0) {
+            return List.of();
+        }
+        return Arrays.stream(combined.toString().split("[,;" + java.io.File.pathSeparator + "]"))
+                .map(String::trim)
+                .filter(s -> !s.isEmpty())
+                .toList();
+    }
+
+    // ---------------------------------------------------------------------
+    // Windows certificate store
+    // ---------------------------------------------------------------------
+
+    public KeyStore loadWindowsKeyStore() throws Exception {
+        if (!windowsStoreSupported()) {
+            throw ExceptionUtils.createIllegalArgumentException(
+                    "error.windowsStoreUnavailable",
+                    "The Windows certificate store is not available on this platform");
+        }
+        KeyStore ks = KeyStore.getInstance(WINDOWS_KEYSTORE_TYPE, MSCAPI_PROVIDER);
+        ks.load(null, null);
+        return ks;
+    }
+
+    public Provider windowsProvider() {
+        return Security.getProvider(MSCAPI_PROVIDER);
+    }
+
+    public List<HardwareCertificateInfo> listWindowsCertificates() throws Exception {
+        return listSigningCertificates(loadWindowsKeyStore(), SOURCE_WINDOWS_STORE);
+    }
+
+    // ---------------------------------------------------------------------
+    // PKCS#11 tokens
+    // ---------------------------------------------------------------------
+
+    /**
+     * A configured, logged-in PKCS#11 keystore plus the provider that must service signing. Closing
+     * logs the session out so the PIN-authenticated session does not outlive the request. The
+     * provider stays cached (logout is C_Logout, not C_Finalize) so the next call reuses the same
+     * C_Initialize. Single-user desktop model - logout is best-effort.
+     */
+    public record Pkcs11Session(KeyStore keyStore, Provider provider) implements AutoCloseable {
+        @Override
+        public void close() {
+            if (provider instanceof java.security.AuthProvider authProvider) {
+                try {
+                    authProvider.logout();
+                } catch (Exception e) {
+                    // Not logged in / already logged out - nothing to clear.
+                }
+            }
+        }
+    }
+
+    // One SunPKCS11 provider per driver+slot, reused across enumerate + sign. A PKCS#11 module
+    // typically allows C_Initialize only once per process, so configuring a fresh provider on every
+    // call races with the previous (not-yet-GC'd) one - the cause of "first sign fails, second
+    // works". Reusing the provider keeps a single C_Initialize alive for the session.
+    private final java.util.concurrent.ConcurrentHashMap<String, Provider> pkcs11Providers =
+            new java.util.concurrent.ConcurrentHashMap<>();
+
+    public Pkcs11Session openPkcs11(String libraryPath, Integer slot, char[] pin) throws Exception {
+        validateLibraryAllowed(libraryPath);
+        if (!pkcs11Supported()) {
+            throw ExceptionUtils.createIllegalArgumentException(
+                    "error.pkcs11Unavailable", "PKCS#11 support is not available in this runtime");
+        }
+
+        String cacheKey = libraryPath + "|" + slot;
+        Provider provider =
+                pkcs11Providers.computeIfAbsent(
+                        cacheKey, k -> buildPkcs11Provider(libraryPath, slot));
+        try {
+            KeyStore ks = KeyStore.getInstance("PKCS11", provider);
+            ks.load(null, pin);
+            return new Pkcs11Session(ks, provider);
+        } catch (Exception e) {
+            // A wrong PIN must not be retried: a second C_Login would burn the token's retry
+            // counter twice per attempt and can lock the token. Only rebuild on provider/init
+            // failures (e.g. token removed/re-inserted leaving a stale provider).
+            if (isAuthFailure(e)) {
+                throw e;
+            }
+            pkcs11Providers.remove(cacheKey, provider);
+            Provider fresh =
+                    pkcs11Providers.computeIfAbsent(
+                            cacheKey, k -> buildPkcs11Provider(libraryPath, slot));
+            KeyStore ks = KeyStore.getInstance("PKCS11", fresh);
+            ks.load(null, pin);
+            return new Pkcs11Session(ks, fresh);
+        }
+    }
+
+    /** True when the failure is a bad/locked PIN rather than a provider/init/device problem. */
+    private static boolean isAuthFailure(Throwable t) {
+        while (t != null) {
+            if (t instanceof javax.security.auth.login.FailedLoginException) {
+                return true;
+            }
+            String msg = t.getMessage();
+            if (msg != null && msg.toUpperCase(Locale.ROOT).contains("CKR_PIN")) {
+                return true; // CKR_PIN_INCORRECT / CKR_PIN_LOCKED / CKR_PIN_INVALID / ...
+            }
+            t = t.getCause();
+        }
+        return false;
+    }
+
+    private Provider buildPkcs11Provider(String libraryPath, Integer slot) {
+        StringBuilder config = new StringBuilder();
+        config.append("--name=").append(providerName(libraryPath)).append('\n');
+        config.append("library=").append(libraryPath).append('\n');
+        if (slot != null) {
+            config.append("slot=").append(slot).append('\n');
+        }
+        try {
+            return Security.getProvider(PKCS11_BASE_PROVIDER).configure(config.toString());
+        } catch (Exception e) {
+            throw ExceptionUtils.createIllegalArgumentException(
+                    "error.pkcs11ConfigFailed",
+                    "Failed to initialise the PKCS#11 driver: {0}",
+                    e.getMessage());
+        }
+    }
+
+    public List<HardwareCertificateInfo> listPkcs11Certificates(
+            String libraryPath, Integer slot, char[] pin) throws Exception {
+        try (Pkcs11Session session = openPkcs11(libraryPath, slot, pin)) {
+            return listSigningCertificates(session.keyStore(), SOURCE_PKCS11);
+        }
+    }
+
+    /**
+     * Reject driver paths that are not detected on disk / configured - blocks arbitrary DLL loads.
+     */
+    public void validateLibraryAllowed(String libraryPath) {
+        if (libraryPath == null || libraryPath.isBlank()) {
+            throw ExceptionUtils.createIllegalArgumentException(
+                    "error.pkcs11LibraryRequired", "A PKCS#11 driver library path is required");
+        }
+        Set<String> allowed =
+                detectPkcs11Libraries().stream()
+                        .map(Pkcs11LibraryInfo::path)
+                        .collect(Collectors.toSet());
+        boolean ok = allowed.stream().anyMatch(p -> sameFile(p, libraryPath));
+        if (!ok) {
+            throw ExceptionUtils.createIllegalArgumentException(
+                    "error.pkcs11LibraryNotAllowed",
+                    "PKCS#11 driver is not in the allowed list. Add it via the"
+                            + " STIRLING_PKCS11_LIBRARIES setting: {0}",
+                    libraryPath);
+        }
+    }
+
+    // ---------------------------------------------------------------------
+    // Shared helpers
+    // ---------------------------------------------------------------------
+
+    private List<HardwareCertificateInfo> listSigningCertificates(KeyStore ks, String source)
+            throws Exception {
+        List<HardwareCertificateInfo> certs = new ArrayList<>();
+        Enumeration<String> aliases = ks.aliases();
+        while (aliases.hasMoreElements()) {
+            String alias = aliases.nextElement();
+            if (!ks.isKeyEntry(alias)) {
+                continue; // only entries we can sign with
+            }
+            Certificate cert = ks.getCertificate(alias);
+            if (cert instanceof X509Certificate x509) {
+                certs.add(toInfo(alias, x509, source));
+            }
+        }
+        return certs;
+    }
+
+    private static HardwareCertificateInfo toInfo(
+            String alias, X509Certificate cert, String source) {
+        java.util.Date now = new java.util.Date();
+        return new HardwareCertificateInfo(
+                alias,
+                source,
+                cert.getSubjectX500Principal().getName(),
+                cert.getIssuerX500Principal().getName(),
+                commonName(cert.getSubjectX500Principal()),
+                commonName(cert.getIssuerX500Principal()),
+                cert.getSerialNumber().toString(16),
+                cert.getPublicKey().getAlgorithm(),
+                cert.getNotBefore().toInstant().toString(),
+                cert.getNotAfter().toInstant().toString(),
+                now.after(cert.getNotAfter()),
+                now.before(cert.getNotBefore()));
+    }
+
+    private static String commonName(X500Principal principal) {
+        try {
+            X500Name x500Name = new X500Name(principal.getName());
+            RDN[] rdns = x500Name.getRDNs(BCStyle.CN);
+            if (rdns.length > 0) {
+                return IETFUtils.valueToString(rdns[0].getFirst().getValue());
+            }
+        } catch (Exception e) {
+            log.debug("Could not parse common name from {}", principal.getName());
+        }
+        return principal.getName();
+    }
+
+    private static String providerName(String libraryPath) {
+        String base = fileName(libraryPath).replaceAll("[^a-zA-Z0-9]", "");
+        if (base.isEmpty()) {
+            base = "token";
+        }
+        return "StirlingHW" + base;
+    }
+
+    private static String fileName(String path) {
+        try {
+            return Path.of(path).getFileName().toString();
+        } catch (Exception e) {
+            return path;
+        }
+    }
+
+    private static boolean sameFile(String a, String b) {
+        if (a == null || b == null) {
+            return false;
+        }
+        try {
+            Path pa = Path.of(a);
+            Path pb = Path.of(b);
+            if (Files.exists(pa) && Files.exists(pb)) {
+                return Files.isSameFile(pa, pb);
+            }
+            return pa.toAbsolutePath().normalize().equals(pb.toAbsolutePath().normalize());
+        } catch (Exception e) {
+            return a.equalsIgnoreCase(b);
+        }
+    }
+}
@@ -45,6 +45,10 @@ public class SvgOverlayUtil {
                        @Override
                        public void checkLoadExternalResource(
                                ParsedURL resourceURL, ParsedURL docURL) {
+                            // Inline data: URIs are self-contained (no network/file fetch).
+                            if (resourceURL != null && "data".equals(resourceURL.getProtocol())) {
+                                return;
+                            }
                            throw new SecurityException(
                                    "External resource loading is disabled for SVG overlays: "
                                            + resourceURL);
@@ -19,6 +19,7 @@ import org.apache.batik.bridge.GVTBuilder;
 import org.apache.batik.bridge.UserAgent;
 import org.apache.batik.bridge.UserAgentAdapter;
 import org.apache.batik.gvt.GraphicsNode;
+import org.apache.batik.util.ParsedURL;
 import org.apache.batik.util.XMLResourceDescriptor;
 import org.apache.pdfbox.pdmodel.PDDocument;
 import org.apache.pdfbox.pdmodel.PDPage;
@@ -63,7 +64,7 @@ public class SvgToPdf {
            }

            // 2. Build the GVT (Graphics Vector Tree) with timeout protection
-            UserAgent userAgent = new UserAgentAdapter();
+            UserAgent userAgent = createSecureUserAgent();
            DocumentLoader loader = new DocumentLoader(userAgent);
            BridgeContext ctx = new BridgeContext(userAgent, loader);
            ctx.setDynamicState(BridgeContext.DYNAMIC);
@@ -94,6 +95,21 @@ public class SvgToPdf {
        }
    }

+    private UserAgent createSecureUserAgent() {
+        return new UserAgentAdapter() {
+            @Override
+            public void checkLoadExternalResource(ParsedURL resourceURL, ParsedURL docURL) {
+                // Inline data: URIs are self-contained (no network/file fetch) - allow them.
+                if (resourceURL != null && "data".equals(resourceURL.getProtocol())) {
+                    return;
+                }
+                throw new SecurityException(
+                        "External resource loading is disabled for SVG to PDF conversion: "
+                                + resourceURL);
+            }
+        };
+    }
+
    private GraphicsNode buildGvtWithTimeout(BridgeContext ctx, SVGDocument svgDoc)
            throws IOException {
        GVTBuilder builder = new GVTBuilder();
@@ -202,7 +218,7 @@ public class SvgToPdf {
            svgDoc = factory.createSVGDocument("file:///input.svg", inputStream);
        }

-        UserAgent userAgent = new UserAgentAdapter();
+        UserAgent userAgent = createSecureUserAgent();
        DocumentLoader loader = new DocumentLoader(userAgent);
        BridgeContext ctx = new BridgeContext(userAgent, loader);
        ctx.setDynamicState(BridgeContext.DYNAMIC);
@@ -62,8 +62,6 @@ security:
    # IMPORTANT: For SAML setup, download your SP metadata from the BACKEND URL: http://localhost:8080/saml2/service-provider-metadata/{registrationId}
    # Do NOT use the frontend dev server URL (localhost:5173) as it will generate incorrect ACS URLs. Always use the backend URL (localhost:8080) for SAML configuration.
  jwt: # This feature is currently under development and not yet fully supported. Do not use in production.
-    persistence: true # Set to 'true' to enable JWT key store
-    enableKeyRotation: true # Set to 'true' to enable key pair rotation
    enableKeyCleanup: true # Set to 'true' to enable key pair cleanup
    tokenExpiryMinutes: 1440 # JWT access token lifetime in minutes for web clients (1 day).
    desktopTokenExpiryMinutes: 43200 # JWT access token lifetime in minutes for desktop clients (30 days).
@@ -141,10 +139,10 @@ telegram:
  botUsername: "" # Telegram bot username (without @)
  pipelineInboxFolder: telegram # Name of the pipeline inbox folder for Telegram uploads
  customFolderSuffix: true # set to 'true' to allow users to specify custom target folders via UserID
-  enableAllowUserIDs: true # set to 'true' to restrict access to specific Telegram user IDs
-  allowUserIDs: [] # List of allowed Telegram user IDs (e.g. [123456789, 987654321]). Leave empty to allow all users.
-  enableAllowChannelIDs: true # set to 'true' to restrict access to specific Telegram channel IDs
-  allowChannelIDs: [] # List of allowed Telegram channel IDs (e.g. [-1001234567890, -1009876543210]). Leave empty to allow all channels.
+  enableAllowUserIDs: true # set to 'true' to restrict access to specific Telegram user IDs. NOTE: only takes effect when allowUserIDs is non-empty; with an empty list every user is still allowed even when this is 'true'
+  allowUserIDs: [] # List of allowed Telegram user IDs (e.g. [123456789, 987654321]). Leave empty to allow all users (the enableAllowUserIDs toggle has no effect until this list is populated).
+  enableAllowChannelIDs: true # set to 'true' to restrict access to specific Telegram channel IDs. NOTE: only takes effect when allowChannelIDs is non-empty; with an empty list every channel is still allowed even when this is 'true'
+  allowChannelIDs: [] # List of allowed Telegram channel IDs (e.g. [-1001234567890, -1009876543210]). Leave empty to allow all channels (the enableAllowChannelIDs toggle has no effect until this list is populated).
  processingTimeoutSeconds: 180 # Maximum time in seconds to wait for processing a Telegram request
  pollingIntervalMillis: 2000 # Interval in milliseconds between polling for new messages
  feedback:
@@ -165,13 +163,17 @@ legal:
  accessibilityStatement: "" # URL to the accessibility statement of your application (e.g. https://example.com/accessibility). Empty string to disable or filename to load from local file in static folder
  cookiePolicy: "" # URL to the cookie policy of your application (e.g. https://example.com/cookie). Empty string to disable or filename to load from local file in static folder
  impressum: "" # URL to the impressum of your application (e.g. https://example.com/impressum). Empty string to disable or filename to load from local file in static folder
+  loginAgreement:
+    enabled: false # set to 'true' to show a login agreement/disclaimer popup after login (and on app launch when login is disabled). Per-language text is read from customFiles/disclaimer/<locale>.md (e.g. en-GB.md, fr-FR.md)
+    showInAnonymousMode: true # when login is disabled, set to 'false' to suppress the agreement in anonymous (no-login) mode
+    fallbackText: "" # optional markdown used for any language that has no customFiles/disclaimer/<locale>.md file (also settable via the LEGAL_LOGINAGREEMENT_FALLBACKTEXT env var for single-language headless installs)

 system:
  defaultLocale: "" # force a default language for new users (e.g. 'en-US', 'de-DE'). Empty string auto-detects from the browser, falling back to en-US
-  googlevisibility: false # 'true' to allow Google visibility (via robots.txt), 'false' to disallow
+  googlevisibility: false # 'true' serves an allow-all /robots.txt; 'false' serves a disallow-all /robots.txt to keep the instance out of search engines
  enableAlphaFunctionality: false # set to enable functionality which might need more testing before it fully goes live (this feature might make no changes)
-  showUpdate: false # see when a new update is available
-  showUpdateOnlyAdmin: false # only admins can see when a new update is available, depending on showUpdate it must be set to 'true'
+  showUpdate: true # see when a new update is available
+  showUpdateOnlyAdmin: true # only admins can see when a new update is available, depending on showUpdate it must be set to 'true'
  showSettingsWhenNoLogin: true # set to 'false' to hide settings button when login is disabled (enableLogin: false). Only applies when login is disabled.
  customHTMLFiles: false # enable to have files placed in /customFiles/templates override the existing template HTML files
  tessdataDir: "" # path to the directory containing the Tessdata files. This setting is relevant for Windows systems. For Windows users, this path should be adjusted to point to the appropriate directory where the Tessdata files are stored.
@@ -182,7 +184,7 @@ system:
  enableUrlToPDF: false # Set to 'true' to enable URL to PDF, INTERNAL ONLY, known security issues, should not be used externally
  disableSanitize: false # set to true to disable Sanitize HTML; (can lead to injections in HTML)
  maxDPI: 500 # Maximum allowed DPI for PDF to image conversion
-  corsAllowedOrigins: [] # List of allowed origins for CORS (e.g. ['http://localhost:5173', 'https://app.example.com']). Leave empty to disable CORS. For local development with frontend on port 5173, add 'http://localhost:5173'
+  corsAllowedOrigins: [] # List of allowed origins for CORS (e.g. ['http://localhost:5173', 'https://app.example.com']). WARNING: leaving this empty falls back to allowing ALL origins (with credentials), it does NOT disable CORS. Set explicit origins to lock it down.
  backendUrl: "" # Backend base URL for SAML/OAuth/API callbacks (e.g. 'http://localhost:8080' for dev, 'https://api.example.com' for production). REQUIRED for SSO authentication to work correctly. This is where your IdP will send SAML responses and OAuth callbacks. Leave empty to default to 'http://localhost:8080' in development.
  frontendUrl: "" # Frontend URL for invite email links (e.g. 'https://app.example.com'). Optional - if not set, will use backendUrl. This is the URL users click in invite emails.
  enableMobileScanner: true # Enable mobile phone QR code upload feature. Requires frontendUrl to be configured.
@@ -193,7 +195,7 @@ system:
    stretchToFit: false # Whether to stretch images to fill the entire page (may distort aspect ratio). If false, images are centered with preserved aspect ratio. Only applies when convertToPdf is true.
  serverCertificate:
    enabled: true # Enable server-side certificate for "Sign with Stirling-PDF" option
-    organizationName: Stirling-PDF # Organization name for generated certificates
+    organizationName: Stirling PDF Inc # Organization name for generated certificates
    validity: 365 # Certificate validity in days
    regenerateOnStartup: false # Generate new certificate on each startup
  html:
@@ -300,7 +302,7 @@ autoPipeline:
    allowedExtensions: [] # Optional extension allow-list (case-insensitive, without the leading dot). Empty list = accept all extensions. Example: ["pdf", "tiff"]

 ui:
-  appNameNavbar: "" # name displayed on the navigation bar
+  appNameNavbar: "" # custom app/brand name. NOTE: no longer shown in the navbar (the navbar renders the logo). It IS used as the browser tab title and as the TOTP/2FA issuer label in authenticator apps. Empty falls back to "Stirling PDF"
  logoStyle: classic # Options: 'classic' (default - classic S icon) or 'modern' (minimalist logo)
  languages: [] # If empty, all languages are enabled. To restrict to specific languages, use a whitelist like ["de_DE", "pl_PL", "sv_SE"]. Empty list or not restricting any languages will enable all available languages.
  defaultHideUnavailableTools: false # Default user preference: hide disabled tools instead of greying them out
@@ -179,6 +179,13 @@
            "moduleLicense": "Apache-2.0",
            "moduleLicenseUrl": "https://www.apache.org/licenses/LICENSE-2.0.txt"
        },
+        {
+            "moduleName": "com.google.code.gson:gson",
+            "moduleUrl": "https://github.com/google/gson",
+            "moduleVersion": "2.14.0",
+            "moduleLicense": "Apache-2.0",
+            "moduleLicenseUrl": "https://www.apache.org/licenses/LICENSE-2.0.txt"
+        },
        {
            "moduleName": "com.google.errorprone:error_prone_annotations",
            "moduleUrl": "https://errorprone.info/error_prone_annotations",
@@ -186,6 +193,13 @@
            "moduleLicense": "Apache 2.0",
            "moduleLicenseUrl": "http://www.apache.org/licenses/LICENSE-2.0.txt"
        },
+        {
+            "moduleName": "com.google.errorprone:error_prone_annotations",
+            "moduleUrl": "https://errorprone.info/error_prone_annotations",
+            "moduleVersion": "2.48.0",
+            "moduleLicense": "Apache 2.0",
+            "moduleLicenseUrl": "http://www.apache.org/licenses/LICENSE-2.0.txt"
+        },
        {
            "moduleName": "com.google.guava:failureaccess",
            "moduleUrl": "https://github.com/google/guava/",
@@ -629,13 +643,6 @@
            "moduleLicense": "Apache License, Version 2.0",
            "moduleLicenseUrl": "http://www.apache.org/licenses/LICENSE-2.0.txt"
        },
-        {
-            "moduleName": "commons-io:commons-io",
-            "moduleUrl": "https://commons.apache.org/proper/commons-io/",
-            "moduleVersion": "2.21.0",
-            "moduleLicense": "Apache-2.0",
-            "moduleLicenseUrl": "https://www.apache.org/licenses/LICENSE-2.0.txt"
-        },
        {
            "moduleName": "commons-io:commons-io",
            "moduleUrl": "https://commons.apache.org/proper/commons-io/",
@@ -9,6 +9,7 @@ import java.io.File;
 import java.io.IOException;
 import java.nio.file.Files;
 import java.util.ArrayList;
+import java.util.HashSet;
 import java.util.List;

 import org.apache.pdfbox.Loader;
@@ -302,6 +303,11 @@ class RearrangePagesPDFControllerTest {
            assertNotNull(response);
            // 2 pages * 3 duplicates = 6 final pages
            assertEquals(6, realDoc.getNumberOfPages());
+            // Each duplicate must be a distinct page node in the saved output; a shared
+            // node under multiple /Kids is an invalid tree readers reject as cyclic.
+            List<Object> savedPages = reloadAndSnapshot(response);
+            assertEquals(6, savedPages.size());
+            assertEquals(6, new HashSet<>(savedPages).size());
        }
    }

@@ -323,4 +329,29 @@ class RearrangePagesPDFControllerTest {
            assertEquals(4, realDoc.getNumberOfPages());
        }
    }
+
+    @Test
+    void testRearrangePages_SideStitchBooklet_RepeatedPaddingPagesAreDistinctNodes()
+            throws IOException {
+        MockMultipartFile file = createMockPdf();
+        RearrangePagesRequest request = new RearrangePagesRequest();
+        request.setFileInput(file);
+        request.setPageNumbers("");
+        request.setCustomMode("SIDE_STITCH_BOOKLET_SORT");
+
+        // 6 pages is not a multiple of 4, so booklet padding repeats the last page index
+        // several times; each repeat must be a distinct page node, not one shared node.
+        try (PDDocument realDoc = buildRealPdf(6)) {
+            when(pdfDocumentFactory.load(file)).thenReturn(realDoc);
+
+            ResponseEntity<Resource> response = controller.rearrangePages(request);
+
+            assertNotNull(response);
+            assertEquals(200, response.getStatusCode().value());
+            assertEquals(8, realDoc.getNumberOfPages());
+            List<Object> savedPages = reloadAndSnapshot(response);
+            assertEquals(8, savedPages.size());
+            assertEquals(8, new HashSet<>(savedPages).size());
+        }
+    }
 }
@@ -26,6 +26,7 @@ import jakarta.servlet.http.HttpServletRequest;
 import stirling.software.SPDF.config.EndpointConfiguration;
 import stirling.software.SPDF.config.ExternalAppDepConfig;
 import stirling.software.common.configuration.AppConfig;
+import stirling.software.common.configuration.interfaces.ShowAdminInterface;
 import stirling.software.common.model.ApplicationProperties;
 import stirling.software.common.service.LicenseServiceInterface;
 import stirling.software.common.service.ServerCertificateServiceInterface;
@@ -45,6 +46,7 @@ class ConfigControllerMoreTest {
    @Mock private EndpointConfiguration endpointConfiguration;
    @Mock private ServerCertificateServiceInterface serverCertificateService;
    @Mock private UserServiceInterface userService;
+    @Mock private ShowAdminInterface showAdmin;
    @Mock private LicenseServiceInterface licenseService;
    @Mock private ExternalAppDepConfig externalAppDepConfig;
    @Mock private AppConfig appConfig;
@@ -70,6 +72,7 @@ class ConfigControllerMoreTest {
                endpointConfiguration,
                serverCertificateService,
                userService,
+                showAdmin,
                licenseService,
                externalAppDepConfig);
    }
@@ -21,6 +21,7 @@ import stirling.software.SPDF.config.EndpointConfiguration;
 import stirling.software.SPDF.config.EndpointConfiguration.DisableReason;
 import stirling.software.SPDF.config.EndpointConfiguration.EndpointAvailability;
 import stirling.software.common.configuration.AppConfig;
+import stirling.software.common.configuration.interfaces.ShowAdminInterface;
 import stirling.software.common.model.ApplicationProperties;
 import stirling.software.common.model.ApplicationProperties.System;
 import stirling.software.common.service.LicenseServiceInterface;
@@ -35,6 +36,7 @@ class ConfigControllerTest {
    @Mock private EndpointConfiguration endpointConfiguration;
    @Mock private ServerCertificateServiceInterface serverCertificateService;
    @Mock private UserServiceInterface userService;
+    @Mock private ShowAdminInterface showAdmin;
    @Mock private LicenseServiceInterface licenseService;

    private ConfigController configController;
@@ -48,6 +50,7 @@ class ConfigControllerTest {
                        endpointConfiguration,
                        serverCertificateService,
                        userService,
+                        showAdmin,
                        licenseService,
                        mock(stirling.software.SPDF.config.ExternalAppDepConfig.class));
    }
@@ -0,0 +1,63 @@
+package stirling.software.SPDF.controller.api.misc;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.mockito.Mockito.when;
+
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.InjectMocks;
+import org.mockito.Mock;
+import org.mockito.junit.jupiter.MockitoExtension;
+
+import stirling.software.SPDF.controller.api.misc.LoginDisclaimerController.LoginDisclaimerResponse;
+import stirling.software.common.service.LoginAgreementService;
+
+@ExtendWith(MockitoExtension.class)
+class LoginDisclaimerControllerTest {
+
+    @Mock LoginAgreementService loginAgreementService;
+
+    @InjectMocks LoginDisclaimerController controller;
+
+    @Test
+    void disabledReturnsEmptyContent() {
+        when(loginAgreementService.isEnabled()).thenReturn(false);
+        when(loginAgreementService.isShowInAnonymousMode()).thenReturn(true);
+
+        LoginDisclaimerResponse resp = controller.getLoginDisclaimer("en-GB");
+
+        assertFalse(resp.enabled());
+        assertEquals("", resp.content());
+        assertTrue(resp.showInAnonymousMode());
+        assertEquals("markdown", resp.format());
+    }
+
+    @Test
+    void enabledWithContentReturnsIt() {
+        when(loginAgreementService.isEnabled()).thenReturn(true);
+        when(loginAgreementService.isShowInAnonymousMode()).thenReturn(false);
+        when(loginAgreementService.resolveContent("fr-FR")).thenReturn("# Avis");
+
+        LoginDisclaimerResponse resp = controller.getLoginDisclaimer("fr-FR");
+
+        assertTrue(resp.enabled());
+        assertEquals("# Avis", resp.content());
+        assertFalse(resp.showInAnonymousMode());
+    }
+
+    @Test
+    void enabledButBlankContentReportsDisabled() {
+        // No file for any candidate locale and no fallbackText -> report disabled so clients
+        // don't render an empty agreement.
+        when(loginAgreementService.isEnabled()).thenReturn(true);
+        when(loginAgreementService.isShowInAnonymousMode()).thenReturn(true);
+        when(loginAgreementService.resolveContent("ja-JP")).thenReturn("   ");
+
+        LoginDisclaimerResponse resp = controller.getLoginDisclaimer("ja-JP");
+
+        assertFalse(resp.enabled());
+        assertEquals("", resp.content());
+    }
+}
@@ -30,7 +30,10 @@ import org.springframework.http.ResponseEntity;
 import org.springframework.mock.web.MockMultipartFile;
 import org.springframework.web.multipart.MultipartFile;

+import jakarta.servlet.http.HttpServletRequest;
+
 import stirling.software.SPDF.model.api.security.SignPDFWithCertRequest;
+import stirling.software.SPDF.service.HardwareKeyStoreService;
 import stirling.software.common.service.CustomPDFDocumentFactory;
 import stirling.software.common.util.TempFile;
 import stirling.software.common.util.TempFileManager;
@@ -51,6 +54,8 @@ class CertSignControllerTest {

    @Mock private CustomPDFDocumentFactory pdfDocumentFactory;
    @Mock private TempFileManager tempFileManager;
+    @Mock private HardwareKeyStoreService hardwareKeyStoreService;
+    @Mock private HttpServletRequest httpRequest;

    @InjectMocks private CertSignController certSignController;

@@ -169,7 +174,8 @@ class CertSignControllerTest {
        request.setPageNumber(1);
        request.setShowLogo(false);

-        ResponseEntity<Resource> response = certSignController.signPDFWithCert(request);
+        ResponseEntity<Resource> response =
+                certSignController.signPDFWithCert(request, httpRequest);

        assertNotNull(response.getBody());
        assertTrue(drainBody(response).length > 0);
@@ -195,7 +201,8 @@ class CertSignControllerTest {
        request.setPageNumber(1);
        request.setShowLogo(false);

-        ResponseEntity<Resource> response = certSignController.signPDFWithCert(request);
+        ResponseEntity<Resource> response =
+                certSignController.signPDFWithCert(request, httpRequest);

        assertNotNull(response.getBody());
        assertTrue(drainBody(response).length > 0);
@@ -221,7 +228,7 @@ class CertSignControllerTest {
        IllegalArgumentException exception =
                assertThrows(
                        IllegalArgumentException.class,
-                        () -> certSignController.signPDFWithCert(request));
+                        () -> certSignController.signPDFWithCert(request, httpRequest));

        assertTrue(exception.getMessage().contains("PKCS12 keystore"));
    }
@@ -247,7 +254,8 @@ class CertSignControllerTest {
        request.setPageNumber(1);
        request.setShowLogo(false);

-        ResponseEntity<Resource> response = certSignController.signPDFWithCert(request);
+        ResponseEntity<Resource> response =
+                certSignController.signPDFWithCert(request, httpRequest);

        assertNotNull(response.getBody());
        assertTrue(drainBody(response).length > 0);
@@ -278,7 +286,8 @@ class CertSignControllerTest {
        request.setPageNumber(1);
        request.setShowLogo(false);

-        ResponseEntity<Resource> response = certSignController.signPDFWithCert(request);
+        ResponseEntity<Resource> response =
+                certSignController.signPDFWithCert(request, httpRequest);

        assertNotNull(response.getBody());
        assertTrue(drainBody(response).length > 0);
@@ -309,7 +318,8 @@ class CertSignControllerTest {
        request.setPageNumber(1);
        request.setShowLogo(false);

-        ResponseEntity<Resource> response = certSignController.signPDFWithCert(request);
+        ResponseEntity<Resource> response =
+                certSignController.signPDFWithCert(request, httpRequest);

        assertNotNull(response.getBody());
        assertTrue(drainBody(response).length > 0);
@@ -340,7 +350,8 @@ class CertSignControllerTest {
        request.setPageNumber(1);
        request.setShowLogo(false);

-        ResponseEntity<Resource> response = certSignController.signPDFWithCert(request);
+        ResponseEntity<Resource> response =
+                certSignController.signPDFWithCert(request, httpRequest);

        assertNotNull(response.getBody());
        assertTrue(drainBody(response).length > 0);
@@ -371,7 +382,8 @@ class CertSignControllerTest {
        request.setPageNumber(1);
        request.setShowLogo(false);

-        ResponseEntity<Resource> response = certSignController.signPDFWithCert(request);
+        ResponseEntity<Resource> response =
+                certSignController.signPDFWithCert(request, httpRequest);

        assertNotNull(response.getBody());
        assertTrue(drainBody(response).length > 0);
@@ -89,9 +89,13 @@ class CertificateValidationServiceMoreTest {
    }

    private static ApplicationProperties defaultProps() {
-        // Real POJO defaults: trust all off, revocation "none".
+        // Test baseline: every trust source explicitly off so each test enables only what it
+        // exercises (the shipped POJO defaults now enable system + Mozilla trust).
        ApplicationProperties props = new ApplicationProperties();
-        props.getSecurity().getValidation().getTrust().setServerAsAnchor(false);
+        var trust = props.getSecurity().getValidation().getTrust();
+        trust.setServerAsAnchor(false);
+        trust.setUseSystemTrust(false);
+        trust.setUseMozillaBundle(false);
        return props;
    }

@@ -0,0 +1,146 @@
+package stirling.software.SPDF.service;
+
+import static org.junit.jupiter.api.Assertions.assertDoesNotThrow;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.when;
+
+import java.nio.file.Files;
+import java.nio.file.Path;
+
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.io.TempDir;
+
+import jakarta.servlet.http.HttpServletRequest;
+
+import stirling.software.SPDF.model.api.security.HardwareSigningCapabilities;
+
+/** Unit tests for the gating / allowlist logic that protects the hardware signing paths. */
+class HardwareKeyStoreServiceTest {
+
+    private static final String PKCS11_PROP = "stirling.pkcs11.libraries";
+
+    private HardwareKeyStoreService service(String machineType) {
+        return new HardwareKeyStoreService(machineType);
+    }
+
+    @Test
+    void isDesktop_trueOnlyForClientMachineTypes() {
+        assertTrue(service("Client-windows").isDesktop());
+        assertTrue(service("Client-mac").isDesktop());
+        assertTrue(service("Client-unix").isDesktop());
+        assertFalse(service("Server-jar").isDesktop());
+        assertFalse(service("Docker").isDesktop());
+        assertFalse(service(null).isDesktop());
+    }
+
+    @Test
+    void isDesktop_trueInTauriModeEvenWithoutClientMachineType() {
+        // The Tauri bundle sets STIRLING_PDF_TAURI_MODE=true while machineType stays Server-jar.
+        String previous = System.getProperty("STIRLING_PDF_TAURI_MODE");
+        try {
+            System.setProperty("STIRLING_PDF_TAURI_MODE", "true");
+            assertTrue(service("Server-jar").isDesktop());
+            assertTrue(service(null).isDesktop());
+        } finally {
+            if (previous == null) {
+                System.clearProperty("STIRLING_PDF_TAURI_MODE");
+            } else {
+                System.setProperty("STIRLING_PDF_TAURI_MODE", previous);
+            }
+        }
+    }
+
+    @Test
+    void capabilities_notDesktop_reportsUnavailable() {
+        HardwareSigningCapabilities caps = service("Server-jar").capabilities();
+        assertFalse(caps.desktop());
+        assertFalse(caps.windowsStoreSupported());
+        assertFalse(caps.pkcs11Supported());
+        assertTrue(caps.detectedLibraries().isEmpty());
+    }
+
+    @Test
+    void capabilities_desktop_reportsOsName() {
+        HardwareSigningCapabilities caps = service("Client-windows").capabilities();
+        assertTrue(caps.desktop());
+        assertFalse(caps.osName().isBlank());
+    }
+
+    @Test
+    void assertLocalDesktop_rejectsNonDesktop() {
+        HttpServletRequest request = mock(HttpServletRequest.class);
+        when(request.getRemoteAddr()).thenReturn("127.0.0.1");
+        assertThrows(
+                IllegalArgumentException.class,
+                () -> service("Server-jar").assertLocalDesktop(request));
+    }
+
+    @Test
+    void assertLocalDesktop_rejectsRemoteCallerEvenOnDesktop() {
+        HttpServletRequest request = mock(HttpServletRequest.class);
+        // 203.0.113.0/24 is TEST-NET-3 (RFC 5737) - never a real local interface address.
+        when(request.getRemoteAddr()).thenReturn("203.0.113.5");
+        assertThrows(
+                IllegalArgumentException.class,
+                () -> service("Client-windows").assertLocalDesktop(request));
+    }
+
+    @Test
+    void assertLocalDesktop_allowsLoopbackOnDesktop() {
+        HttpServletRequest request = mock(HttpServletRequest.class);
+        when(request.getRemoteAddr()).thenReturn("127.0.0.1");
+        assertDoesNotThrow(() -> service("Client-windows").assertLocalDesktop(request));
+        // No servlet context (e.g. internal call) is also allowed.
+        assertDoesNotThrow(() -> service("Client-windows").assertLocalDesktop(null));
+    }
+
+    @Test
+    void isLocalRequest_acceptsLoopbackForms_rejectsRemote() {
+        assertTrue(HardwareKeyStoreService.isLocalRequest("127.0.0.1"));
+        assertTrue(HardwareKeyStoreService.isLocalRequest("::1"));
+        assertTrue(HardwareKeyStoreService.isLocalRequest("0:0:0:0:0:0:0:1"));
+        // IPv4-mapped IPv6 loopback - what Tomcat reports for the desktop webview.
+        assertTrue(HardwareKeyStoreService.isLocalRequest("::ffff:127.0.0.1"));
+        assertFalse(HardwareKeyStoreService.isLocalRequest("203.0.113.5"));
+        assertFalse(HardwareKeyStoreService.isLocalRequest(null));
+    }
+
+    @Test
+    void validateLibraryAllowed_blankPath_throws() {
+        assertThrows(
+                IllegalArgumentException.class,
+                () -> service("Client-windows").validateLibraryAllowed("   "));
+    }
+
+    @Test
+    void validateLibraryAllowed_unknownPath_throws() {
+        assertThrows(
+                IllegalArgumentException.class,
+                () ->
+                        service("Client-windows")
+                                .validateLibraryAllowed("/definitely/not/a/real/driver.so"));
+    }
+
+    @Test
+    void validateLibraryAllowed_configuredPath_isAllowed(@TempDir Path tempDir) throws Exception {
+        Path fakeDriver = Files.createFile(tempDir.resolve("fake-pkcs11.so"));
+        String previous = System.getProperty(PKCS11_PROP);
+        try {
+            System.setProperty(PKCS11_PROP, fakeDriver.toString());
+            HardwareKeyStoreService service = service("Client-windows");
+            assertDoesNotThrow(() -> service.validateLibraryAllowed(fakeDriver.toString()));
+            assertTrue(
+                    service.detectPkcs11Libraries().stream()
+                            .anyMatch(l -> l.path().equals(fakeDriver.toString())));
+        } finally {
+            if (previous == null) {
+                System.clearProperty(PKCS11_PROP);
+            } else {
+                System.setProperty(PKCS11_PROP, previous);
+            }
+        }
+    }
+}
@@ -2,12 +2,23 @@ package stirling.software.SPDF.utils;

 import static org.junit.jupiter.api.Assertions.*;

+import java.awt.Color;
+import java.awt.Graphics2D;
+import java.awt.image.BufferedImage;
 import java.io.IOException;
 import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.Path;
 import java.util.Arrays;
+import java.util.Base64;
 import java.util.Collections;
 import java.util.List;

+import javax.imageio.ImageIO;
+
+import org.apache.pdfbox.Loader;
+import org.apache.pdfbox.pdmodel.PDDocument;
+import org.apache.pdfbox.rendering.PDFRenderer;
 import org.junit.jupiter.api.Test;

 class SvgToPdfTest {
@@ -124,4 +135,91 @@ class SvgToPdfTest {
        List<byte[]> svgs = Arrays.asList(null, null, new byte[0]);
        assertThrows(IOException.class, () -> SvgToPdf.combineIntoPdf(svgs));
    }
+
+    @Test
+    void convert_doesNotEmbedExternalFileResource() throws Exception {
+        Path external = Files.createTempFile("svg-external", ".png");
+        BufferedImage red = new BufferedImage(100, 100, BufferedImage.TYPE_INT_RGB);
+        Graphics2D g = red.createGraphics();
+        g.setColor(Color.RED);
+        g.fillRect(0, 0, 100, 100);
+        g.dispose();
+        ImageIO.write(red, "png", external.toFile());
+
+        try {
+            String svg =
+                    "<svg xmlns=\"http://www.w3.org/2000/svg\" "
+                            + "xmlns:xlink=\"http://www.w3.org/1999/xlink\" width=\"100\" height=\"100\">"
+                            + "<image x=\"0\" y=\"0\" width=\"100\" height=\"100\" xlink:href=\""
+                            + external.toUri()
+                            + "\"/></svg>";
+
+            byte[] pdf;
+            try {
+                pdf = SvgToPdf.convert(svg.getBytes(StandardCharsets.UTF_8));
+            } catch (IOException blocked) {
+                return;
+            }
+
+            try (PDDocument doc = Loader.loadPDF(pdf)) {
+                BufferedImage page = new PDFRenderer(doc).renderImageWithDPI(0, 72);
+                int rgb = page.getRGB(page.getWidth() / 2, page.getHeight() / 2);
+                int r = (rgb >> 16) & 0xff;
+                int gg = (rgb >> 8) & 0xff;
+                int b = rgb & 0xff;
+                assertFalse(
+                        r > 200 && gg < 60 && b < 60,
+                        "External file image must not be rendered into the PDF");
+            }
+        } finally {
+            Files.deleteIfExists(external);
+        }
+    }
+
+    // A self-contained SVG whose only content is an inline base64 data: image (a solid-red vector
+    // SVG). Vector data: images decode via batik-bridge without batik-codec, so this exercises the
+    // data: security allowance independent of raster codecs.
+    private static String svgWithInlineRedImage() {
+        String innerSvg =
+                "<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"100\" height=\"100\">"
+                        + "<rect width=\"100\" height=\"100\" fill=\"red\"/></svg>";
+        String dataUri =
+                "data:image/svg+xml;base64,"
+                        + Base64.getEncoder()
+                                .encodeToString(innerSvg.getBytes(StandardCharsets.UTF_8));
+        return "<svg xmlns=\"http://www.w3.org/2000/svg\" "
+                + "xmlns:xlink=\"http://www.w3.org/1999/xlink\" width=\"100\" height=\"100\">"
+                + "<image x=\"0\" y=\"0\" width=\"100\" height=\"100\" xlink:href=\""
+                + dataUri
+                + "\"/></svg>";
+    }
+
+    @Test
+    void convert_rendersInlineDataUriImage() throws IOException {
+        byte[] pdf = SvgToPdf.convert(svgWithInlineRedImage().getBytes(StandardCharsets.UTF_8));
+        try (PDDocument doc = Loader.loadPDF(pdf)) {
+            BufferedImage page = new PDFRenderer(doc).renderImageWithDPI(0, 72);
+            int rgb = page.getRGB(page.getWidth() / 2, page.getHeight() / 2);
+            int r = (rgb >> 16) & 0xff;
+            int gg = (rgb >> 8) & 0xff;
+            int b = rgb & 0xff;
+            assertTrue(
+                    r > 200 && gg < 60 && b < 60,
+                    "Inline data: image must be rendered into the PDF (center rgb="
+                            + Integer.toHexString(rgb)
+                            + ")");
+        }
+    }
+
+    @Test
+    void combineIntoPdf_keepsPageWithInlineDataUriImage() throws IOException {
+        List<byte[]> svgs =
+                List.of(
+                        SIMPLE_SVG.getBytes(StandardCharsets.UTF_8),
+                        svgWithInlineRedImage().getBytes(StandardCharsets.UTF_8));
+        byte[] pdf = SvgToPdf.combineIntoPdf(svgs);
+        try (PDDocument doc = Loader.loadPDF(pdf)) {
+            assertEquals(2, doc.getNumberOfPages(), "inline data: image page must not be dropped");
+        }
+    }
 }
@@ -3,12 +3,6 @@ repositories {
    maven { url = "https://build.shibboleth.net/maven/releases" }
 }

-ext {
-    jwtVersion = '0.13.0'
-    awsSdkVersion = '2.44.12'
-    testcontainersMinioVersion = '1.21.4'
-}
-
 bootRun {
    enabled = false
 }
@@ -41,7 +35,7 @@ spotless {
 }
 dependencies {
    implementation project(':common')
-    api 'com.google.guava:guava:33.6.0-jre'
+    api "com.google.guava:guava:${guavaVersion}"

    api 'org.springframework:spring-jdbc'
    api 'org.springframework:spring-webmvc'
@@ -61,37 +55,41 @@ dependencies {
    api 'com.github.ben-manes.caffeine:caffeine'
    implementation 'org.springframework.boot:spring-boot-starter-data-redis'
    api 'io.swagger.core.v3:swagger-core-jakarta:2.2.46'
-    implementation 'com.bucket4j:bucket4j_jdk17-core:8.19.0'
+    implementation "com.bucket4j:bucket4j_jdk17-core:${bucket4jVersion}"
    // Lettuce-backed Bucket4j ProxyManager used by ValkeyRateLimitStore for cluster-wide
    // token-bucket rate limiting (parity with in-process Bucket4j semantics; no fixed-window
    // boundary doubling).
-    implementation 'com.bucket4j:bucket4j_jdk17-lettuce:8.19.0'
+    implementation "com.bucket4j:bucket4j_jdk17-lettuce:${bucket4jVersion}"

    // https://mvnrepository.com/artifact/com.bucket4j/bucket4j_jdk17
    implementation "org.bouncycastle:bcprov-jdk18on:$bouncycastleVersion"

-    implementation 'com.google.code.gson:gson:2.13.2'
+    implementation "com.google.code.gson:gson:${gsonVersion}"

    api 'io.micrometer:micrometer-registry-prometheus'

-    api "io.jsonwebtoken:jjwt-api:$jwtVersion"
-    runtimeOnly "io.jsonwebtoken:jjwt-impl:$jwtVersion"
-    runtimeOnly "io.jsonwebtoken:jjwt-jackson:$jwtVersion"
+    api "io.jsonwebtoken:jjwt-api:${jwtVersion}"
+    runtimeOnly "io.jsonwebtoken:jjwt-impl:${jwtVersion}"
+    runtimeOnly "io.jsonwebtoken:jjwt-jackson:${jwtVersion}"
    runtimeOnly 'com.h2database:h2:2.3.232' // Don't upgrade h2database - file format incompatible with 2.4.x, would break existing user databases
    runtimeOnly 'org.postgresql:postgresql:42.7.11'
    implementation('com.coveo:saml-client:5.0.0') {
        exclude group: 'org.opensaml', module: 'opensaml-core'
    }

-    implementation "software.amazon.awssdk:s3:$awsSdkVersion"
-    implementation "software.amazon.awssdk:url-connection-client:$awsSdkVersion"
+    implementation "software.amazon.awssdk:s3:${awsSdkVersion}"
+    implementation "software.amazon.awssdk:url-connection-client:${awsSdkVersion}"
+
+    // @DataJpaTest slice (Boot 4 ships test slices as separate starters, like webmvc-test at the
+    // root) so policy.source repositories can be exercised against embedded H2.
+    testImplementation 'org.springframework.boot:spring-boot-starter-data-jpa-test'

    // Testcontainers: real MinIO/LocalStack (S3) and Valkey for integration tests in CI without
    // manually-started instances. Tests skip cleanly when Docker is unavailable.
-    testImplementation "org.testcontainers:testcontainers:$testcontainersMinioVersion"
-    testImplementation "org.testcontainers:minio:$testcontainersMinioVersion"
-    testImplementation "org.testcontainers:localstack:$testcontainersMinioVersion"
-    testImplementation "org.testcontainers:junit-jupiter:$testcontainersMinioVersion"
+    testImplementation "org.testcontainers:testcontainers:${testcontainersMinioVersion}"
+    testImplementation "org.testcontainers:minio:${testcontainersMinioVersion}"
+    testImplementation "org.testcontainers:localstack:${testcontainersMinioVersion}"
+    testImplementation "org.testcontainers:junit-jupiter:${testcontainersMinioVersion}"
 }

 tasks.register('prepareKotlinBuildScriptModel') {}
@@ -0,0 +1,20 @@
+package stirling.software.proprietary.access.config;
+
+import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+
+import stirling.software.proprietary.access.service.DefaultTeamLeadLookup;
+import stirling.software.proprietary.access.service.TeamLeadLookup;
+
+/** Access-layer bean wiring. */
+@Configuration
+public class AccessConfig {
+
+    /** No-op {@link TeamLeadLookup} unless another bean is defined. */
+    @Bean
+    @ConditionalOnMissingBean(TeamLeadLookup.class)
+    TeamLeadLookup defaultTeamLeadLookup() {
+        return new DefaultTeamLeadLookup();
+    }
+}
@@ -0,0 +1,101 @@
+package stirling.software.proprietary.access.controller;
+
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+import org.springframework.http.ResponseEntity;
+import org.springframework.security.access.prepost.PreAuthorize;
+import org.springframework.security.core.annotation.AuthenticationPrincipal;
+import org.springframework.web.bind.annotation.DeleteMapping;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.RestController;
+
+import io.swagger.v3.oas.annotations.tags.Tag;
+
+import lombok.RequiredArgsConstructor;
+
+import stirling.software.proprietary.access.model.AccessPermission;
+import stirling.software.proprietary.access.model.PrincipalType;
+import stirling.software.proprietary.access.model.ResourceGrant;
+import stirling.software.proprietary.access.model.ResourceType;
+import stirling.software.proprietary.access.service.ResourceAccessService;
+import stirling.software.proprietary.security.model.User;
+
+/** Admin endpoints to grant/revoke access to gated resources (the portal, integration configs). */
+@RestController
+@RequestMapping("/api/v1/admin/access")
+@RequiredArgsConstructor
+@PreAuthorize("hasRole('ADMIN')")
+@Tag(name = "Access Control", description = "Manage resource access grants (portal, integrations)")
+public class ResourceGrantController {
+
+    private final ResourceAccessService accessService;
+
+    @GetMapping("/grants")
+    public ResponseEntity<?> list(
+            @RequestParam ResourceType resourceType,
+            @RequestParam(required = false, defaultValue = "") String resourceId) {
+        List<ResourceGrant> grants = accessService.listGrants(resourceType, resourceId);
+        return ResponseEntity.ok(grants.stream().map(this::toDto).toList());
+    }
+
+    @PostMapping("/grants")
+    public ResponseEntity<?> create(
+            @RequestBody GrantRequest request, @AuthenticationPrincipal User admin) {
+        if (request.resourceType() == null
+                || request.principalType() == null
+                || request.principalId() == null) {
+            return ResponseEntity.badRequest()
+                    .body(
+                            Map.of(
+                                    "error",
+                                    "resourceType, principalType and principalId are required"));
+        }
+        AccessPermission permission =
+                request.permission() == null ? AccessPermission.USE : request.permission();
+        // PORTAL is a singleton resource; its grants always target the whole type.
+        String resourceId =
+                request.resourceType() == ResourceType.PORTAL ? "" : request.resourceId();
+        ResourceGrant grant =
+                accessService.grant(
+                        request.resourceType(),
+                        resourceId,
+                        request.principalType(),
+                        request.principalId(),
+                        permission,
+                        admin);
+        return ResponseEntity.ok(toDto(grant));
+    }
+
+    @DeleteMapping("/grants/{id}")
+    public ResponseEntity<?> delete(@PathVariable Long id) {
+        accessService.revoke(id);
+        return ResponseEntity.ok(Map.of("message", "Grant revoked"));
+    }
+
+    private Map<String, Object> toDto(ResourceGrant g) {
+        Map<String, Object> m = new HashMap<>();
+        m.put("id", g.getId());
+        m.put("resourceType", g.getResourceType());
+        m.put("resourceId", g.getResourceId());
+        m.put("principalType", g.getPrincipalType());
+        m.put("principalId", g.getPrincipalId());
+        m.put("permission", g.getPermission());
+        m.put("createdAt", g.getCreatedAt());
+        return m;
+    }
+
+    /** Request body for creating a grant. */
+    public record GrantRequest(
+            ResourceType resourceType,
+            String resourceId,
+            PrincipalType principalType,
+            Long principalId,
+            AccessPermission permission) {}
+}
@@ -0,0 +1,7 @@
+package stirling.software.proprietary.access.model;
+
+/** Permission level a grant confers. MANAGE implies USE. */
+public enum AccessPermission {
+    USE,
+    MANAGE
+}
@@ -0,0 +1,14 @@
+package stirling.software.proprietary.access.model;
+
+/**
+ * Fallback policy applied when no explicit {@link ResourceGrant} matches. Admins (org owners)
+ * always pass regardless of this policy.
+ */
+public enum DefaultAccessPolicy {
+    // Every authenticated user in the deployment (org) may use the resource.
+    ORG_ALL,
+    // Only org admins and team leaders. This is the default for the portal.
+    ADMINS_AND_TEAM_LEADS,
+    // Nobody but the owner, admins, and explicit grantees.
+    EXPLICIT_ONLY
+}
@@ -0,0 +1,57 @@
+package stirling.software.proprietary.access.model;
+
+import jakarta.persistence.Column;
+import jakarta.persistence.EnumType;
+import jakarta.persistence.Enumerated;
+import jakarta.persistence.FetchType;
+import jakarta.persistence.JoinColumn;
+import jakarta.persistence.ManyToOne;
+import jakarta.persistence.MappedSuperclass;
+
+import lombok.Getter;
+import lombok.Setter;
+
+import stirling.software.proprietary.model.Team;
+import stirling.software.proprietary.security.model.User;
+
+/** Base for a resource owned by a user, a team, or the server, with grant-based access. */
+@MappedSuperclass
+@Getter
+@Setter
+public abstract class OwnedResource {
+
+    @Enumerated(EnumType.STRING)
+    @Column(name = "scope", nullable = false, length = 32)
+    private OwnerScope scope;
+
+    @ManyToOne(fetch = FetchType.LAZY)
+    @JoinColumn(name = "owner_user_id")
+    private User ownerUser;
+
+    @ManyToOne(fetch = FetchType.LAZY)
+    @JoinColumn(name = "owner_team_id")
+    private Team ownerTeam;
+
+    @Column(name = "enabled", nullable = false)
+    private boolean enabled = true;
+
+    // Server resource that users cannot override with their own of the same kind.
+    @Column(name = "locked", nullable = false)
+    private boolean locked = false;
+
+    // Who, besides owner/admin/grantees, may use this resource.
+    @Enumerated(EnumType.STRING)
+    @Column(name = "default_access", nullable = false, length = 32)
+    private DefaultAccessPolicy defaultAccess = DefaultAccessPolicy.EXPLICIT_ONLY;
+
+    /** Subclass primary key. */
+    public abstract Long getId();
+
+    public Long getOwnerUserId() {
+        return ownerUser != null ? ownerUser.getId() : null;
+    }
+
+    public Long getOwnerTeamId() {
+        return ownerTeam != null ? ownerTeam.getId() : null;
+    }
+}
@@ -0,0 +1,8 @@
+package stirling.software.proprietary.access.model;
+
+/** Ownership scope of an {@link OwnedResource}: a single user, a team, or the whole server. */
+public enum OwnerScope {
+    USER,
+    TEAM,
+    SERVER
+}
@@ -0,0 +1,7 @@
+package stirling.software.proprietary.access.model;
+
+/** Who a {@link ResourceGrant} is granted to. Org-wide access is expressed via default policy. */
+public enum PrincipalType {
+    USER,
+    TEAM
+}
@@ -0,0 +1,86 @@
+package stirling.software.proprietary.access.model;
+
+import java.io.Serializable;
+import java.time.LocalDateTime;
+
+import org.hibernate.annotations.CreationTimestamp;
+
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.EnumType;
+import jakarta.persistence.Enumerated;
+import jakarta.persistence.FetchType;
+import jakarta.persistence.GeneratedValue;
+import jakarta.persistence.GenerationType;
+import jakarta.persistence.Id;
+import jakarta.persistence.Index;
+import jakarta.persistence.JoinColumn;
+import jakarta.persistence.ManyToOne;
+import jakarta.persistence.Table;
+import jakarta.persistence.UniqueConstraint;
+
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+import lombok.Setter;
+
+import stirling.software.proprietary.security.model.User;
+
+/** Grants a user or team access to a resource. Owner and admin access are implicit. */
+@Entity
+@Table(
+        name = "resource_grants",
+        uniqueConstraints =
+                @UniqueConstraint(
+                        name = "uk_resource_grant",
+                        columnNames = {
+                            "resource_type",
+                            "resource_id",
+                            "principal_type",
+                            "principal_id",
+                            "permission"
+                        }),
+        indexes = {
+            @Index(name = "idx_resource_grants_lookup", columnList = "resource_type,resource_id"),
+            @Index(
+                    name = "idx_resource_grants_principal",
+                    columnList = "principal_type,principal_id")
+        })
+@NoArgsConstructor
+@Getter
+@Setter
+public class ResourceGrant implements Serializable {
+
+    private static final long serialVersionUID = 1L;
+
+    @Id
+    @GeneratedValue(strategy = GenerationType.IDENTITY)
+    @Column(name = "resource_grant_id")
+    private Long id;
+
+    @Enumerated(EnumType.STRING)
+    @Column(name = "resource_type", nullable = false, length = 64)
+    private ResourceType resourceType;
+
+    // Empty string (never null) for a whole-type grant such as the portal.
+    @Column(name = "resource_id", nullable = false, length = 255)
+    private String resourceId = "";
+
+    @Enumerated(EnumType.STRING)
+    @Column(name = "principal_type", nullable = false, length = 32)
+    private PrincipalType principalType;
+
+    @Column(name = "principal_id", nullable = false)
+    private Long principalId;
+
+    @Enumerated(EnumType.STRING)
+    @Column(name = "permission", nullable = false, length = 32)
+    private AccessPermission permission;
+
+    @ManyToOne(fetch = FetchType.LAZY)
+    @JoinColumn(name = "granted_by_user_id")
+    private User grantedBy;
+
+    @CreationTimestamp
+    @Column(name = "created_at", updatable = false)
+    private LocalDateTime createdAt;
+}
@@ -0,0 +1,9 @@
+package stirling.software.proprietary.access.model;
+
+/** Types of resources whose access can be gated by {@link ResourceGrant}. */
+public enum ResourceType {
+    // The admin portal / processor (frontend/portal). Singleton resource (empty resourceId).
+    PORTAL,
+    // A stored S3/MCP/API integration configuration.
+    INTEGRATION_CONFIG
+}
@@ -0,0 +1,28 @@
+package stirling.software.proprietary.access.repository;
+
+import java.util.List;
+
+import org.springframework.data.jpa.repository.JpaRepository;
+import org.springframework.stereotype.Repository;
+
+import stirling.software.proprietary.access.model.PrincipalType;
+import stirling.software.proprietary.access.model.ResourceGrant;
+import stirling.software.proprietary.access.model.ResourceType;
+
+@Repository
+public interface ResourceGrantRepository extends JpaRepository<ResourceGrant, Long> {
+
+    List<ResourceGrant> findByResourceTypeAndResourceId(
+            ResourceType resourceType, String resourceId);
+
+    List<ResourceGrant> findByResourceTypeAndPrincipalTypeAndPrincipalId(
+            ResourceType resourceType, PrincipalType principalType, Long principalId);
+
+    void deleteByResourceTypeAndResourceId(ResourceType resourceType, String resourceId);
+
+    boolean existsByResourceTypeAndResourceIdAndPrincipalTypeAndPrincipalId(
+            ResourceType resourceType,
+            String resourceId,
+            PrincipalType principalType,
+            Long principalId);
+}
@@ -0,0 +1,44 @@
+package stirling.software.proprietary.access.security;
+
+import org.springframework.security.core.Authentication;
+import org.springframework.security.core.context.SecurityContextHolder;
+import org.springframework.security.core.userdetails.UserDetails;
+import org.springframework.stereotype.Component;
+
+import lombok.RequiredArgsConstructor;
+
+import stirling.software.proprietary.access.service.ResourceAccessService;
+import stirling.software.proprietary.security.model.User;
+import stirling.software.proprietary.security.service.UserService;
+
+/** {@code @PreAuthorize} bean for portal-access checks. Active in self-hosted and saas. */
+@Component("resourceAccess")
+@RequiredArgsConstructor
+public class ResourceAccessSecurity {
+
+    private final ResourceAccessService accessService;
+    private final UserService userService;
+
+    public boolean canUsePortal() {
+        User user = currentUser();
+        return user != null && accessService.canAccessPortal(user);
+    }
+
+    private User currentUser() {
+        Authentication auth = SecurityContextHolder.getContext().getAuthentication();
+        if (auth == null || !auth.isAuthenticated()) {
+            return null;
+        }
+        Object principal = auth.getPrincipal();
+        if (principal instanceof User user) {
+            return user;
+        }
+        if (principal instanceof UserDetails userDetails) {
+            return userService.findByUsername(userDetails.getUsername()).orElse(null);
+        }
+        if (principal instanceof String username && !"anonymousUser".equals(username)) {
+            return userService.findByUsername(username).orElse(null);
+        }
+        return null;
+    }
+}
@@ -0,0 +1,17 @@
+package stirling.software.proprietary.access.service;
+
+import stirling.software.proprietary.security.model.User;
+
+/** No-op {@link TeamLeadLookup}: always false. */
+public class DefaultTeamLeadLookup implements TeamLeadLookup {
+
+    @Override
+    public boolean isAnyTeamLeader(User user) {
+        return false;
+    }
+
+    @Override
+    public boolean isLeaderOfTeam(User user, Long teamId) {
+        return false;
+    }
+}
@@ -0,0 +1,116 @@
+package stirling.software.proprietary.access.service;
+
+import java.util.Set;
+import java.util.function.BooleanSupplier;
+
+import org.springframework.http.HttpStatus;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+import org.springframework.web.server.ResponseStatusException;
+
+import lombok.RequiredArgsConstructor;
+
+import stirling.software.common.model.enumeration.Role;
+import stirling.software.proprietary.access.model.OwnedResource;
+import stirling.software.proprietary.access.model.OwnerScope;
+import stirling.software.proprietary.access.model.ResourceType;
+import stirling.software.proprietary.model.Team;
+import stirling.software.proprietary.security.model.User;
+import stirling.software.proprietary.security.repository.TeamRepository;
+
+/** Ownership and access checks for {@link OwnedResource}, backed by the resource-grant ACL. */
+@Service
+@RequiredArgsConstructor
+@Transactional(readOnly = true)
+public class OwnershipService {
+
+    private final ResourceAccessService accessService;
+    private final TeamLeadLookup teamLeadLookup;
+    private final TeamRepository teamRepository;
+
+    /** Whether the user may use the resource. */
+    public boolean canUse(ResourceType type, OwnedResource resource, User user) {
+        if (!resource.isEnabled()) {
+            return isAdmin(user) || isOwner(resource, user);
+        }
+        return accessService.canUseResource(
+                type,
+                String.valueOf(resource.getId()),
+                resource.getOwnerUserId(),
+                resource.getDefaultAccess(),
+                user);
+    }
+
+    /** Whether the user may manage the resource. */
+    public boolean canManage(ResourceType type, OwnedResource resource, User user) {
+        return accessService.canManageResource(
+                type, String.valueOf(resource.getId()), resource.getOwnerUserId(), user);
+    }
+
+    /**
+     * Authorizes the scope and assigns ownership; {@code lockedOverrideBlocks} guards USER scope.
+     */
+    public void assignOwnership(
+            OwnedResource resource,
+            OwnerScope scope,
+            Long teamId,
+            User user,
+            BooleanSupplier lockedOverrideBlocks) {
+        resource.setScope(scope);
+        switch (scope) {
+            case USER -> {
+                if (lockedOverrideBlocks.getAsBoolean() && !isAdmin(user)) {
+                    throw forbidden(
+                            "This is locked to the server configuration by an administrator");
+                }
+                resource.setOwnerUser(user);
+            }
+            case SERVER -> {
+                if (!isAdmin(user)) {
+                    throw forbidden("Only administrators can create server-owned resources");
+                }
+            }
+            case TEAM -> {
+                if (teamId == null) {
+                    throw new ResponseStatusException(
+                            HttpStatus.BAD_REQUEST, "ownerTeamId is required");
+                }
+                Team team =
+                        teamRepository
+                                .findById(teamId)
+                                .orElseThrow(() -> notFound("Team not found"));
+                if (!isAdmin(user) && !teamLeadLookup.isLeaderOfTeam(user, team.getId())) {
+                    throw forbidden("Only admins or team leaders can create team-owned resources");
+                }
+                resource.setOwnerTeam(team);
+            }
+        }
+    }
+
+    /** Resource ids of the given type the user or their team holds a grant on. */
+    public Set<String> grantedResourceIds(ResourceType type, User user) {
+        return accessService.grantedResourceIds(type, user);
+    }
+
+    public boolean isAdmin(User user) {
+        return user.getAuthorities().stream()
+                .anyMatch(a -> Role.ADMIN.getRoleId().equals(a.getAuthority()));
+    }
+
+    public boolean isOwner(OwnedResource resource, User user) {
+        if (resource.getOwnerUserId() != null && resource.getOwnerUserId().equals(user.getId())) {
+            return true;
+        }
+        // Team-owned: the lead of the owning team owns it.
+        return resource.getOwnerTeamId() != null
+                && teamLeadLookup.isLeaderOfTeam(user, resource.getOwnerTeamId());
+    }
+
+    private ResponseStatusException forbidden(String message) {
+        return new ResponseStatusException(HttpStatus.FORBIDDEN, message);
+    }
+
+    private ResponseStatusException notFound(String message) {
+        return new ResponseStatusException(HttpStatus.NOT_FOUND, message);
+    }
+}
@@ -0,0 +1,188 @@
+package stirling.software.proprietary.access.service;
+
+import java.util.HashSet;
+import java.util.List;
+import java.util.Set;
+
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+
+import stirling.software.common.model.enumeration.Role;
+import stirling.software.proprietary.access.model.AccessPermission;
+import stirling.software.proprietary.access.model.DefaultAccessPolicy;
+import stirling.software.proprietary.access.model.PrincipalType;
+import stirling.software.proprietary.access.model.ResourceGrant;
+import stirling.software.proprietary.access.model.ResourceType;
+import stirling.software.proprietary.access.repository.ResourceGrantRepository;
+import stirling.software.proprietary.security.model.User;
+
+/** Resolves access to gated resources: owner, then admin, then grant, then default policy. */
+@Service
+@RequiredArgsConstructor
+@Slf4j
+@Transactional(readOnly = true)
+public class ResourceAccessService {
+
+    private final ResourceGrantRepository grantRepository;
+    private final TeamLeadLookup teamLeadLookup;
+
+    @Value("${security.portal.defaultAccess:ADMINS_AND_TEAM_LEADS}")
+    private DefaultAccessPolicy portalDefaultPolicy;
+
+    // ---- public checks ----
+
+    /** Whether the user may use the portal / processor. */
+    public boolean canAccessPortal(User user) {
+        return canUseResource(ResourceType.PORTAL, "", null, portalDefaultPolicy, user);
+    }
+
+    /** Whether the user may use a resource, falling back to its default policy. */
+    public boolean canUseResource(
+            ResourceType type,
+            String resourceId,
+            Long ownerUserId,
+            DefaultAccessPolicy defaultPolicy,
+            User user) {
+        if (user == null) {
+            return false;
+        }
+        if (isOwner(ownerUserId, user) || isAdmin(user)) {
+            return true;
+        }
+        if (hasGrant(type, normalize(resourceId), user, AccessPermission.USE)) {
+            return true;
+        }
+        return matchesDefault(defaultPolicy, user);
+    }
+
+    /** Whether the user may manage (edit/delete/share) a resource. No default-policy fallback. */
+    public boolean canManageResource(
+            ResourceType type, String resourceId, Long ownerUserId, User user) {
+        if (user == null) {
+            return false;
+        }
+        if (isOwner(ownerUserId, user) || isAdmin(user)) {
+            return true;
+        }
+        return hasGrant(type, normalize(resourceId), user, AccessPermission.MANAGE);
+    }
+
+    // ---- grant management ----
+
+    @Transactional
+    public ResourceGrant grant(
+            ResourceType type,
+            String resourceId,
+            PrincipalType principalType,
+            Long principalId,
+            AccessPermission permission,
+            User grantedBy) {
+        String rid = normalize(resourceId);
+        ResourceGrant grant =
+                grantRepository.findByResourceTypeAndResourceId(type, rid).stream()
+                        .filter(
+                                g ->
+                                        g.getPrincipalType() == principalType
+                                                && g.getPrincipalId().equals(principalId))
+                        .findFirst()
+                        .orElseGet(ResourceGrant::new);
+        grant.setResourceType(type);
+        grant.setResourceId(rid);
+        grant.setPrincipalType(principalType);
+        grant.setPrincipalId(principalId);
+        grant.setPermission(permission);
+        if (grantedBy != null) {
+            grant.setGrantedBy(grantedBy);
+        }
+        return grantRepository.save(grant);
+    }
+
+    @Transactional
+    public void revoke(Long grantId) {
+        grantRepository.deleteById(grantId);
+    }
+
+    public List<ResourceGrant> listGrants(ResourceType type, String resourceId) {
+        return grantRepository.findByResourceTypeAndResourceId(type, normalize(resourceId));
+    }
+
+    /** Resource ids of the given type that this user (or their team) holds any grant on. */
+    public Set<String> grantedResourceIds(ResourceType type, User user) {
+        if (user == null) {
+            return Set.of();
+        }
+        Set<String> ids = new HashSet<>();
+        for (ResourceGrant g :
+                grantRepository.findByResourceTypeAndPrincipalTypeAndPrincipalId(
+                        type, PrincipalType.USER, user.getId())) {
+            ids.add(g.getResourceId());
+        }
+        if (user.getTeam() != null) {
+            for (ResourceGrant g :
+                    grantRepository.findByResourceTypeAndPrincipalTypeAndPrincipalId(
+                            type, PrincipalType.TEAM, user.getTeam().getId())) {
+                ids.add(g.getResourceId());
+            }
+        }
+        return ids;
+    }
+
+    // ---- internals ----
+
+    private boolean hasGrant(
+            ResourceType type, String resourceId, User user, AccessPermission required) {
+        Long teamId = user.getTeam() != null ? user.getTeam().getId() : null;
+        for (ResourceGrant g : grantRepository.findByResourceTypeAndResourceId(type, resourceId)) {
+            if (!permissionSatisfies(g.getPermission(), required)) {
+                continue;
+            }
+            if (g.getPrincipalType() == PrincipalType.USER
+                    && g.getPrincipalId().equals(user.getId())) {
+                return true;
+            }
+            if (g.getPrincipalType() == PrincipalType.TEAM
+                    && teamId != null
+                    && g.getPrincipalId().equals(teamId)) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    // MANAGE implies USE.
+    private boolean permissionSatisfies(AccessPermission held, AccessPermission required) {
+        if (required == AccessPermission.USE) {
+            return held == AccessPermission.USE || held == AccessPermission.MANAGE;
+        }
+        return held == AccessPermission.MANAGE;
+    }
+
+    private boolean matchesDefault(DefaultAccessPolicy policy, User user) {
+        if (policy == null) {
+            return false;
+        }
+        return switch (policy) {
+            case ORG_ALL -> true;
+            // Admins already pass above; only team leads here.
+            case ADMINS_AND_TEAM_LEADS -> teamLeadLookup.isAnyTeamLeader(user);
+            case EXPLICIT_ONLY -> false;
+        };
+    }
+
+    private boolean isOwner(Long ownerUserId, User user) {
+        return ownerUserId != null && ownerUserId.equals(user.getId());
+    }
+
+    private boolean isAdmin(User user) {
+        return user.getAuthorities().stream()
+                .anyMatch(a -> Role.ADMIN.getRoleId().equals(a.getAuthority()));
+    }
+
+    private String normalize(String resourceId) {
+        return resourceId == null ? "" : resourceId;
+    }
+}
@@ -0,0 +1,151 @@
+package stirling.software.proprietary.access.service;
+
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Locale;
+import java.util.Map;
+import java.util.Set;
+
+import org.springframework.stereotype.Component;
+
+/** Masks, merges and sanitizes secret values in a config map, recursing into nested maps/lists. */
+@Component
+public class SecretMasker {
+
+    public static final String MASK = "********";
+
+    // Cap recursion so a pathologically nested payload cannot overflow the stack.
+    private static final int MAX_DEPTH = 32;
+
+    private static final Set<String> SENSITIVE_HINTS =
+            Set.of(
+                    "secret",
+                    "password",
+                    "token",
+                    "apikey",
+                    "accesskey",
+                    "credential",
+                    "privatekey");
+
+    /** Replace sensitive values with the mask (recursively) for safe display. */
+    public Map<String, Object> mask(Map<String, Object> config) {
+        return mask(config, 0);
+    }
+
+    /** Drop sensitive blank/masked values from an incoming create payload. */
+    public Map<String, Object> sanitize(Map<String, Object> config) {
+        return sanitize(config, 0);
+    }
+
+    /**
+     * Merge an update over the stored map, keeping stored secrets where the incoming is redacted.
+     */
+    public Map<String, Object> merge(Map<String, Object> stored, Map<String, Object> incoming) {
+        return merge(stored, incoming, 0);
+    }
+
+    private Map<String, Object> mask(Map<String, Object> config, int depth) {
+        Map<String, Object> out = new LinkedHashMap<>();
+        for (Map.Entry<String, Object> e : config.entrySet()) {
+            out.put(e.getKey(), maskValue(e.getKey(), e.getValue(), depth));
+        }
+        return out;
+    }
+
+    private Map<String, Object> sanitize(Map<String, Object> config, int depth) {
+        if (config == null) {
+            return new LinkedHashMap<>();
+        }
+        Map<String, Object> out = new LinkedHashMap<>();
+        for (Map.Entry<String, Object> e : config.entrySet()) {
+            if (isSensitive(e.getKey()) && isRedacted(e.getValue(), depth)) {
+                continue;
+            }
+            out.put(
+                    e.getKey(),
+                    e.getValue() instanceof Map<?, ?> m && depth < MAX_DEPTH
+                            ? sanitize(castMap(m), depth + 1)
+                            : e.getValue());
+        }
+        return out;
+    }
+
+    private Map<String, Object> merge(
+            Map<String, Object> stored, Map<String, Object> incoming, int depth) {
+        Map<String, Object> out = new LinkedHashMap<>(stored);
+        for (Map.Entry<String, Object> e : incoming.entrySet()) {
+            String key = e.getKey();
+            Object value = e.getValue();
+            if (isSensitive(key)) {
+                if (!isRedacted(value, depth)) {
+                    out.put(key, value); // a real new secret replaces the stored one
+                }
+                continue; // redacted (blank / mask) -> keep stored
+            }
+            if (depth < MAX_DEPTH
+                    && out.get(key) instanceof Map<?, ?> s
+                    && value instanceof Map<?, ?> i) {
+                out.put(key, merge(castMap(s), castMap(i), depth + 1));
+            } else {
+                out.put(key, value);
+            }
+        }
+        return out;
+    }
+
+    // A sensitive key masks its whole value; recurse into non-sensitive containers.
+    private Object maskValue(String key, Object value, int depth) {
+        if (isSensitive(key)) {
+            if (value == null || (value instanceof String s && s.isBlank())) {
+                return value;
+            }
+            return MASK;
+        }
+        if (depth >= MAX_DEPTH) {
+            // Too deep to descend; mask containers rather than risk leaking an unmasked secret.
+            return value instanceof Map<?, ?> || value instanceof List<?> ? MASK : value;
+        }
+        if (value instanceof Map<?, ?> m) {
+            return mask(castMap(m), depth + 1);
+        }
+        if (value instanceof List<?> list) {
+            List<Object> out = new ArrayList<>();
+            for (Object item : list) {
+                out.add(item instanceof Map<?, ?> m ? mask(castMap(m), depth + 1) : item);
+            }
+            return out;
+        }
+        return value;
+    }
+
+    private boolean isSensitive(String key) {
+        String lower = key.toLowerCase(Locale.ROOT);
+        return SENSITIVE_HINTS.stream().anyMatch(lower::contains);
+    }
+
+    /** Blank, the mask placeholder, or any structure that still contains the mask. */
+    private boolean isRedacted(Object value, int depth) {
+        if (value == null) {
+            return true;
+        }
+        if (value instanceof String s) {
+            return s.isBlank() || MASK.equals(s);
+        }
+        if (depth >= MAX_DEPTH) {
+            return false;
+        }
+        if (value instanceof Map<?, ?> m) {
+            return m.values().stream().anyMatch(v -> isRedacted(v, depth + 1));
+        }
+        if (value instanceof List<?> list) {
+            return list.stream().anyMatch(v -> isRedacted(v, depth + 1));
+        }
+        return false;
+    }
+
+    @SuppressWarnings("unchecked")
+    private Map<String, Object> castMap(Map<?, ?> map) {
+        return (Map<String, Object>) map;
+    }
+}
@@ -0,0 +1,13 @@
+package stirling.software.proprietary.access.service;
+
+import stirling.software.proprietary.security.model.User;
+
+/** Resolves whether a user leads a team. */
+public interface TeamLeadLookup {
+
+    /** Whether the user leads at least one team. */
+    boolean isAnyTeamLeader(User user);
+
+    /** Whether the user leads the given team. */
+    boolean isLeaderOfTeam(User user, Long teamId);
+}
@@ -0,0 +1,265 @@
+package stirling.software.proprietary.accountlink;
+
+import java.io.IOException;
+import java.net.URI;
+import java.net.http.HttpClient;
+import java.net.http.HttpRequest;
+import java.net.http.HttpResponse;
+import java.time.Duration;
+
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
+import org.springframework.context.annotation.Profile;
+import org.springframework.stereotype.Service;
+
+import lombok.extern.slf4j.Slf4j;
+
+import tools.jackson.databind.JsonNode;
+import tools.jackson.databind.ObjectMapper;
+
+/**
+ * Outbound calls from a self-hosted instance to its linked SaaS backend (combined-billing "Mode
+ * A").
+ *
+ * <p>Two calls:
+ *
+ * <ul>
+ *   <li>{@link #register} — relays the admin's short-lived Supabase JWT to {@code POST
+ *       /api/v1/account-link/register}; the SaaS side mints + returns a device credential.
+ *   <li>{@link #fetchEntitlement} — authenticates with the stored device credential against {@code
+ *       GET /api/v1/instance/entitlement}; what the local gate consults.
+ * </ul>
+ *
+ * <p>Uses {@code java.net.http.HttpClient} (the established self-hosted outbound pattern, see
+ * {@code AiEngineClient}). The base URL + client are injectable so tests can stub the SaaS
+ * endpoint.
+ */
+@Slf4j
+@Service
+@Profile("!saas")
+@ConditionalOnProperty(name = "stirling.billing.account-link.enabled", havingValue = "true")
+public class AccountLinkClient {
+
+    static final String HEADER_DEVICE_ID = "X-Device-Id";
+    static final String HEADER_DEVICE_SECRET = "X-Device-Secret";
+
+    private final AccountLinkProperties properties;
+    private final ObjectMapper mapper;
+    private final HttpClient httpClient;
+
+    @Autowired
+    public AccountLinkClient(AccountLinkProperties properties, ObjectMapper mapper) {
+        this(
+                properties,
+                mapper,
+                HttpClient.newBuilder()
+                        .connectTimeout(Duration.ofSeconds(properties.getRequestTimeoutSeconds()))
+                        .build());
+    }
+
+    /** Package-private: lets tests inject a stub {@link HttpClient}. */
+    AccountLinkClient(
+            AccountLinkProperties properties, ObjectMapper mapper, HttpClient httpClient) {
+        this.properties = properties;
+        this.mapper = mapper;
+        this.httpClient = httpClient;
+    }
+
+    /** The device credential a successful {@link #register} returns. */
+    public record RegisterResult(String deviceId, String deviceSecret, Long teamId) {}
+
+    /**
+     * A non-2xx reply from the SaaS account-link API. Carries the upstream status so the caller can
+     * map auth failures (401/403) through rather than masking everything as a 502.
+     */
+    public static class UpstreamException extends IOException {
+        private final int status;
+
+        public UpstreamException(int status, String body) {
+            super("SaaS account-link returned HTTP " + status + ": " + body);
+            this.status = status;
+        }
+
+        public int status() {
+            return status;
+        }
+    }
+
+    /**
+     * Authoritative deny (401/403) from the entitlement endpoint — the device credential is revoked
+     * or invalid. Distinct from a transport/server failure (which returns {@code null} and fails
+     * open): the cache must BLOCK billable work on this rather than serve a stale entitled
+     * snapshot. Unchecked so it propagates cleanly through {@link #fetchEntitlement}'s transport
+     * try/catch.
+     */
+    public static final class RevokedException extends RuntimeException {
+        private final int status;
+
+        public RevokedException(int status) {
+            super("SaaS entitlement denied (credential revoked/invalid): HTTP " + status);
+            this.status = status;
+        }
+
+        public int status() {
+            return status;
+        }
+    }
+
+    /**
+     * Relays the admin Supabase JWT to the SaaS register endpoint and returns the minted
+     * credential.
+     *
+     * @throws IOException on transport failure or a non-2xx response (caller surfaces to the
+     *     admin).
+     */
+    public RegisterResult register(String supabaseJwt, String instanceName) throws IOException {
+        String body =
+                instanceName == null || instanceName.isBlank()
+                        ? "{}"
+                        : "{\"name\":" + mapper.writeValueAsString(instanceName) + "}";
+        HttpRequest request =
+                HttpRequest.newBuilder()
+                        .uri(uri("/api/v1/account-link/register"))
+                        .header("Authorization", "Bearer " + supabaseJwt)
+                        .header("Content-Type", "application/json")
+                        .header("Accept", "application/json")
+                        .timeout(timeout())
+                        .POST(HttpRequest.BodyPublishers.ofString(body))
+                        .build();
+
+        HttpResponse<String> response = send(request);
+        if (response.statusCode() / 100 != 2) {
+            throw new UpstreamException(response.statusCode(), response.body());
+        }
+        JsonNode root = mapper.readTree(response.body());
+        String deviceId = text(root, "deviceId");
+        String deviceSecret = text(root, "deviceSecret");
+        if (deviceId == null || deviceSecret == null) {
+            throw new IOException("SaaS register response missing deviceId/deviceSecret");
+        }
+        Long teamId = root.hasNonNull("teamId") ? root.get("teamId").asLong() : null;
+        return new RegisterResult(deviceId, deviceSecret, teamId);
+    }
+
+    /**
+     * Revokes this instance's own credential on the SaaS side ({@code POST
+     * /api/v1/instance/revoke-self}), authenticated by the device credential — a credential is
+     * allowed to revoke its own identity. Best-effort: returns {@code false} if SaaS is unreachable
+     * or rejects the call, so the caller (local unlink) can still clear locally and log the orphan
+     * row for follow-up. Idempotent on SaaS (already-revoked → still 204).
+     */
+    public boolean revokeSelf(String deviceId, String deviceSecret) {
+        try {
+            HttpRequest request =
+                    HttpRequest.newBuilder()
+                            .uri(uri("/api/v1/instance/revoke-self"))
+                            .header(HEADER_DEVICE_ID, deviceId)
+                            .header(HEADER_DEVICE_SECRET, deviceSecret)
+                            .header("Accept", "application/json")
+                            .timeout(timeout())
+                            .POST(HttpRequest.BodyPublishers.noBody())
+                            .build();
+            HttpResponse<String> response = send(request);
+            if (response.statusCode() / 100 != 2) {
+                log.debug("Self-revoke returned HTTP {}", response.statusCode());
+                return false;
+            }
+            return true;
+        } catch (Exception e) {
+            log.debug("Self-revoke failed: {}", e.getMessage());
+            return false;
+        }
+    }
+
+    /**
+     * Fetches the current entitlement using the stored device credential. Three outcomes:
+     *
+     * <ul>
+     *   <li>2xx → the parsed snapshot.
+     *   <li>401/403 → {@link RevokedException} (authoritative deny — revoked/invalid credential);
+     *       the caller must BLOCK, not fail open.
+     *   <li>transport failure, other non-2xx (e.g. 5xx), or a malformed body → {@code null}
+     *       ("unknown" — the caller fails open).
+     * </ul>
+     */
+    public InstanceEntitlement fetchEntitlement(String deviceId, String deviceSecret) {
+        HttpResponse<String> response;
+        try {
+            HttpRequest request =
+                    HttpRequest.newBuilder()
+                            .uri(uri("/api/v1/instance/entitlement"))
+                            .header(HEADER_DEVICE_ID, deviceId)
+                            .header(HEADER_DEVICE_SECRET, deviceSecret)
+                            .header("Accept", "application/json")
+                            .timeout(timeout())
+                            .GET()
+                            .build();
+            response = send(request);
+        } catch (Exception e) {
+            // Transport failure (timeout / connection refused / interrupted) → unknown, fail open.
+            log.debug("Entitlement fetch failed: {}", e.getMessage());
+            return null;
+        }
+        int status = response.statusCode();
+        if (status == 401 || status == 403) {
+            // Authoritative deny — the SaaS side rejected the credential (revoked/invalid).
+            throw new RevokedException(status);
+        }
+        if (status / 100 != 2) {
+            // Server / transient error → unknown, fail open (do NOT treat as a deny).
+            log.debug("Entitlement fetch returned HTTP {}", status);
+            return null;
+        }
+        try {
+            return parseEntitlement(response.body());
+        } catch (IOException e) {
+            log.debug("Entitlement parse failed: {}", e.getMessage());
+            return null;
+        }
+    }
+
+    private InstanceEntitlement parseEntitlement(String body) throws IOException {
+        JsonNode root = mapper.readTree(body);
+        boolean subscribed = root.path("subscribed").asBoolean(false);
+        long freeRemaining = root.path("freeRemainingUnits").asLong(0);
+        long periodSpend = root.path("periodSpendUnits").asLong(0);
+        Long periodCap =
+                root.hasNonNull("periodCapUnits") ? root.get("periodCapUnits").asLong() : null;
+        EntitlementState state = mapState(root.path("state").asText(null));
+        return new InstanceEntitlement(subscribed, freeRemaining, periodSpend, periodCap, state);
+    }
+
+    /** Maps the SaaS state string to our coarse enum; unrecognised → UNKNOWN. */
+    private static EntitlementState mapState(String raw) {
+        if (raw == null) {
+            return EntitlementState.UNKNOWN;
+        }
+        return switch (raw) {
+            case "OK", "ACTIVE", "SUBSCRIBED", "FREE" -> EntitlementState.OK;
+            case "OVER_LIMIT", "PAYG_LIMIT_REACHED", "BLOCKED" -> EntitlementState.OVER_LIMIT;
+            default -> EntitlementState.UNKNOWN;
+        };
+    }
+
+    private HttpResponse<String> send(HttpRequest request) throws IOException {
+        try {
+            return httpClient.send(request, HttpResponse.BodyHandlers.ofString());
+        } catch (InterruptedException e) {
+            Thread.currentThread().interrupt();
+            throw new IOException("Interrupted calling SaaS account-link", e);
+        }
+    }
+
+    private URI uri(String path) {
+        String base = properties.getSaasBaseUrl().strip().replaceAll("/+$", "");
+        return URI.create(base + path);
+    }
+
+    private Duration timeout() {
+        return Duration.ofSeconds(properties.getRequestTimeoutSeconds());
+    }
+
+    private static String text(JsonNode node, String field) {
+        return node.hasNonNull(field) ? node.get(field).asText() : null;
+    }
+}
@@ -0,0 +1,88 @@
+package stirling.software.proprietary.accountlink;
+
+import java.io.IOException;
+
+import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
+import org.springframework.context.annotation.Profile;
+import org.springframework.http.HttpStatus;
+import org.springframework.http.ResponseEntity;
+import org.springframework.security.access.prepost.PreAuthorize;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+import io.swagger.v3.oas.annotations.Hidden;
+
+import lombok.extern.slf4j.Slf4j;
+
+/**
+ * Same-origin account-link surface on the self-hosted instance (combined-billing "Mode A").
+ *
+ * <p>The portal (served from this same origin, admin authenticated by the existing self-hosted
+ * security chain) calls these. {@code POST /link} relays the admin's Supabase JWT to the SaaS
+ * backend, which mints + returns a device credential we store locally. {@code GET /status} backs
+ * the portal's link card.
+ *
+ * <p>Admin-only, {@code @Profile("!saas")}, gated behind {@code
+ * stirling.billing.account-link.enabled} — off → bean absent → 404.
+ */
+@Slf4j
+@Hidden
+@RestController
+@RequestMapping("/api/v1/account-link")
+@Profile("!saas")
+@PreAuthorize("hasRole('ADMIN')")
+@ConditionalOnProperty(name = "stirling.billing.account-link.enabled", havingValue = "true")
+public class AccountLinkController {
+
+    private final AccountLinkService service;
+
+    public AccountLinkController(AccountLinkService service) {
+        this.service = service;
+    }
+
+    /** {@code supabaseJwt} is the admin's short-lived token the portal already holds. */
+    public record LinkRequest(String supabaseJwt, String name) {}
+
+    @PostMapping("/link")
+    public ResponseEntity<?> link(@RequestBody LinkRequest req) {
+        if (req == null || req.supabaseJwt() == null || req.supabaseJwt().isBlank()) {
+            return ResponseEntity.badRequest()
+                    .body(java.util.Map.of("error", "supabaseJwt is required"));
+        }
+        try {
+            return ResponseEntity.ok(service.link(req.supabaseJwt(), req.name()));
+        } catch (AccountLinkClient.UpstreamException e) {
+            // Auth failures are the admin's token, not a gateway fault: surface 401/403 as-is so
+            // the portal can prompt a re-sign-in. Anything else upstream → 502. Don't echo the
+            // raw upstream body back to the browser.
+            HttpStatus status =
+                    e.status() == HttpStatus.UNAUTHORIZED.value()
+                                    || e.status() == HttpStatus.FORBIDDEN.value()
+                            ? HttpStatus.valueOf(e.status())
+                            : HttpStatus.BAD_GATEWAY;
+            log.warn("Account-link register rejected upstream: HTTP {}", e.status());
+            return ResponseEntity.status(status).body(java.util.Map.of("error", "LINK_FAILED"));
+        } catch (IOException e) {
+            // Don't echo e.getMessage() to the browser: a DNS/connection/TLS failure can carry the
+            // configured SaaS host/IP. Log it server-side; return the same opaque body the
+            // UpstreamException branch does.
+            log.warn("Account-link failed (transport): {}", e.getMessage());
+            return ResponseEntity.status(HttpStatus.BAD_GATEWAY)
+                    .body(java.util.Map.of("error", "LINK_FAILED"));
+        }
+    }
+
+    @GetMapping("/status")
+    public ResponseEntity<AccountLinkService.LinkStatus> status() {
+        return ResponseEntity.ok(service.status());
+    }
+
+    @PostMapping("/unlink")
+    public ResponseEntity<Void> unlink() {
+        service.unlink();
+        return ResponseEntity.noContent().build();
+    }
+}
@@ -0,0 +1,39 @@
+package stirling.software.proprietary.accountlink;
+
+import org.springframework.boot.context.properties.ConfigurationProperties;
+import org.springframework.stereotype.Component;
+
+import lombok.Getter;
+import lombok.Setter;
+
+/**
+ * Self-hosted side of combined-billing "Mode A" (connected self-hosted).
+ *
+ * <p>Binds the {@code stirling.billing.account-link.*} keys. {@link #enabled} mirrors the same flag
+ * the gated beans test with {@code @ConditionalOnProperty}; it is kept here only so non-conditional
+ * code (e.g. the gate's flag-off short-circuit, exposed status) can read it. The whole feature is
+ * <b>off by default</b> and <b>dark</b> — when off nothing gates and the link endpoints 404.
+ */
+@Getter
+@Setter
+@Component
+@ConfigurationProperties(prefix = "stirling.billing.account-link")
+public class AccountLinkProperties {
+
+    /** Master switch. When {@code false} (default) the feature is fully inert. */
+    private boolean enabled = false;
+
+    /**
+     * Base URL of the SaaS backend this instance links to (register + entitlement live there).
+     *
+     * <p>STUB: defaults to the public cloud host; an operator overrides it for staging. There is no
+     * existing SaaS-base-url property in the self-hosted profile, so this is introduced here.
+     */
+    private String saasBaseUrl = "https://stirling.com/app";
+
+    /** Cached entitlement is reused for this long before a refresh is attempted. */
+    private long entitlementCacheSeconds = 300;
+
+    /** Connect/read timeout for the outbound SaaS calls. */
+    private int requestTimeoutSeconds = 10;
+}
@@ -0,0 +1,92 @@
+package stirling.software.proprietary.accountlink;
+
+import java.io.IOException;
+import java.util.Optional;
+
+import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
+import org.springframework.context.annotation.Profile;
+import org.springframework.stereotype.Service;
+
+import lombok.extern.slf4j.Slf4j;
+
+/**
+ * Linking orchestrator (self-hosted side of combined-billing "Mode A").
+ *
+ * <p>{@link #link} is the same-origin action the portal triggers: it relays the admin's Supabase
+ * JWT to the SaaS register endpoint, then persists the returned device credential secure-at-rest.
+ * The credential — not the JWT — authenticates all later unattended entitlement calls.
+ */
+@Slf4j
+@Service
+@Profile("!saas")
+@ConditionalOnProperty(name = "stirling.billing.account-link.enabled", havingValue = "true")
+public class AccountLinkService {
+
+    private final AccountLinkClient client;
+    private final DeviceCredentialStore credentialStore;
+    private final EntitlementCache entitlementCache;
+
+    public AccountLinkService(
+            AccountLinkClient client,
+            DeviceCredentialStore credentialStore,
+            EntitlementCache entitlementCache) {
+        this.client = client;
+        this.credentialStore = credentialStore;
+        this.entitlementCache = entitlementCache;
+    }
+
+    /** Status of this instance's link, for the portal's "Account link" card. */
+    public record LinkStatus(boolean linked, String deviceId, Long teamId, String linkedAt) {}
+
+    /**
+     * Registers this instance with the SaaS team behind {@code supabaseJwt} and stores the
+     * credential.
+     *
+     * @throws IOException if the SaaS register call fails (surfaced to the admin as a link error).
+     */
+    public LinkStatus link(String supabaseJwt, String instanceName) throws IOException {
+        AccountLinkClient.RegisterResult result = client.register(supabaseJwt, instanceName);
+        credentialStore.save(result.deviceId(), result.deviceSecret(), result.teamId());
+        entitlementCache.invalidate();
+        log.info("Account-link: instance linked to team {}", result.teamId());
+        return status();
+    }
+
+    /**
+     * Unlinks this instance — best-effort tells SaaS to revoke first (so the row gets {@code
+     * revoked_at} set), then clears locally regardless. If SaaS is unreachable the local clear
+     * still proceeds (admin's intent must win); the orphan row can be revoked from the portal.
+     */
+    public void unlink() {
+        credentialStore
+                .get()
+                .ifPresent(
+                        c -> {
+                            boolean ok = client.revokeSelf(c.getDeviceId(), c.getDeviceSecret());
+                            if (!ok) {
+                                log.warn(
+                                        "Account-link: SaaS self-revoke failed for device {};"
+                                                + " clearing locally anyway (admin can revoke"
+                                                + " from the portal).",
+                                        c.getDeviceId());
+                            }
+                        });
+        credentialStore.clear();
+        entitlementCache.invalidate();
+        log.info("Account-link: instance unlinked");
+    }
+
+    public LinkStatus status() {
+        Optional<DeviceCredential> cred = credentialStore.get();
+        return cred.map(
+                        c ->
+                                new LinkStatus(
+                                        true,
+                                        c.getDeviceId(),
+                                        c.getTeamId(),
+                                        c.getLinkedAt() != null
+                                                ? c.getLinkedAt().toString()
+                                                : null))
+                .orElseGet(() -> new LinkStatus(false, null, null, null));
+    }
+}
@@ -0,0 +1,36 @@
+package stirling.software.proprietary.accountlink;
+
+import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.context.annotation.Profile;
+import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
+import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
+
+/**
+ * Registers the account-link entitlement gate. Path patterns cover the billable API surface; the
+ * interceptor itself re-checks billability (and short-circuits manual tools), but scoping here
+ * keeps the gate off the bulk of interactive endpoints entirely.
+ *
+ * <p>Whole config is gated behind {@code stirling.billing.account-link.enabled} +
+ * {@code @Profile("!saas")}; absent when off, so no interceptor is registered.
+ */
+@Configuration
+@Profile("!saas")
+@ConditionalOnProperty(name = "stirling.billing.account-link.enabled", havingValue = "true")
+public class AccountLinkWebMvcConfig implements WebMvcConfigurer {
+
+    private final InstanceEntitlementInterceptor gateInterceptor;
+
+    public AccountLinkWebMvcConfig(InstanceEntitlementInterceptor gateInterceptor) {
+        this.gateInterceptor = gateInterceptor;
+    }
+
+    @Override
+    public void addInterceptors(InterceptorRegistry registry) {
+        // AI surface is always billable; the broad /api/v1/** catch lets automation-marked manual
+        // calls be gated too, while the interceptor lets genuine manual tools through.
+        registry.addInterceptor(gateInterceptor)
+                .addPathPatterns("/api/v1/**")
+                .excludePathPatterns("/api/v1/account-link/**");
+    }
+}
@@ -0,0 +1,38 @@
+package stirling.software.proprietary.accountlink;
+
+import jakarta.servlet.http.HttpServletRequest;
+
+import stirling.software.common.service.InternalApiClient;
+
+/**
+ * Classifies a request as <b>billable</b> (AI / automation) or free (a manual tool).
+ *
+ * <p>Mirrors the saas billing categorisation at a coarse level, without depending on the saas
+ * module: billable = the AI surface ({@code /api/v1/ai/**}) or any request carrying the automation
+ * marker header ({@link InternalApiClient#AUTOMATION_HEADER}, set on pipeline / workflow / policy
+ * sub-steps). Everything else — interactive manual PDF tools — is always free.
+ */
+public final class BillableOperationClassifier {
+
+    private static final String AI_PATH_PREFIX = "/api/v1/ai/";
+
+    private BillableOperationClassifier() {}
+
+    public static boolean isBillable(HttpServletRequest request) {
+        if (request.getHeader(InternalApiClient.AUTOMATION_HEADER) != null) {
+            return true;
+        }
+        String uri = request.getRequestURI();
+        if (uri == null) {
+            return false;
+        }
+        // Prefix-match the AI surface (not a loose substring contains), stripping a deployment
+        // context path so /<ctx>/api/v1/ai/** still classifies as billable.
+        String ctx = request.getContextPath();
+        String path =
+                ctx != null && !ctx.isEmpty() && uri.startsWith(ctx)
+                        ? uri.substring(ctx.length())
+                        : uri;
+        return path.startsWith(AI_PATH_PREFIX);
+    }
+}
@@ -0,0 +1,53 @@
+package stirling.software.proprietary.accountlink;
+
+import java.io.Serializable;
+import java.time.LocalDateTime;
+
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.Id;
+import jakarta.persistence.Table;
+
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+import lombok.Setter;
+
+/**
+ * The device credential this self-hosted instance received when it linked a SaaS account
+ * (combined-billing "Mode A"). Singleton — one instance links to exactly one SaaS team.
+ *
+ * <p>Unlike the SaaS side (which stores only a hash), the instance must keep the plaintext {@code
+ * deviceSecret} so it can present it on every unattended entitlement call. It lives in the local
+ * database (the same store that already holds API-key material and the license signature), so it is
+ * as secure-at-rest as the rest of the instance's secrets.
+ */
+@Entity
+@Table(name = "account_link_device_credential")
+@NoArgsConstructor
+@Getter
+@Setter
+public class DeviceCredential implements Serializable {
+
+    private static final long serialVersionUID = 1L;
+
+    public static final Long SINGLETON_ID = 1L;
+
+    @Id
+    @Column(name = "id")
+    private Long id = SINGLETON_ID;
+
+    /** Public identifier minted by the SaaS register call; sent as {@code X-Device-Id}. */
+    @Column(name = "device_id", nullable = false, length = 64)
+    private String deviceId;
+
+    /** High-entropy secret returned once by register; sent as {@code X-Device-Secret}. */
+    @Column(name = "device_secret", nullable = false, length = 128)
+    private String deviceSecret;
+
+    /** SaaS team this instance is linked to; informational on the instance side. */
+    @Column(name = "team_id")
+    private Long teamId;
+
+    @Column(name = "linked_at", nullable = false)
+    private LocalDateTime linkedAt;
+}
@@ -0,0 +1,15 @@
+package stirling.software.proprietary.accountlink;
+
+import java.util.Optional;
+
+import org.springframework.data.jpa.repository.JpaRepository;
+import org.springframework.stereotype.Repository;
+
+@Repository
+public interface DeviceCredentialRepository extends JpaRepository<DeviceCredential, Long> {
+
+    /** The singleton credential, if this instance has linked. */
+    default Optional<DeviceCredential> findCredential() {
+        return findById(DeviceCredential.SINGLETON_ID);
+    }
+}
@@ -0,0 +1,55 @@
+package stirling.software.proprietary.accountlink;
+
+import java.time.LocalDateTime;
+import java.util.Optional;
+
+import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
+import org.springframework.context.annotation.Profile;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+
+/**
+ * Secure-at-rest persistence for this instance's device credential. Thin wrapper over the
+ * singleton-row repository so the rest of the feature never touches JPA directly.
+ *
+ * <p>Gated + {@code @Profile("!saas")}: only the self-hosted profile links outward to a SaaS team.
+ */
+@Service
+@Profile("!saas")
+@ConditionalOnProperty(name = "stirling.billing.account-link.enabled", havingValue = "true")
+public class DeviceCredentialStore {
+
+    private final DeviceCredentialRepository repo;
+
+    public DeviceCredentialStore(DeviceCredentialRepository repo) {
+        this.repo = repo;
+    }
+
+    @Transactional(readOnly = true)
+    public Optional<DeviceCredential> get() {
+        return repo.findCredential();
+    }
+
+    @Transactional(readOnly = true)
+    public boolean isLinked() {
+        return repo.findCredential().isPresent();
+    }
+
+    /** Persists (or replaces) the credential returned by a SaaS register call. */
+    @Transactional
+    public void save(String deviceId, String deviceSecret, Long teamId) {
+        DeviceCredential cred = repo.findCredential().orElseGet(DeviceCredential::new);
+        cred.setId(DeviceCredential.SINGLETON_ID);
+        cred.setDeviceId(deviceId);
+        cred.setDeviceSecret(deviceSecret);
+        cred.setTeamId(teamId);
+        cred.setLinkedAt(LocalDateTime.now());
+        repo.save(cred);
+    }
+
+    /** Unlinks this instance locally (idempotent). */
+    @Transactional
+    public void clear() {
+        repo.findCredential().ifPresent(repo::delete);
+    }
+}
@@ -0,0 +1,124 @@
+package stirling.software.proprietary.accountlink;
+
+import java.time.Duration;
+import java.time.Instant;
+import java.util.Optional;
+import java.util.concurrent.atomic.AtomicBoolean;
+
+import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
+import org.springframework.context.annotation.Profile;
+import org.springframework.stereotype.Service;
+
+import lombok.extern.slf4j.Slf4j;
+
+/**
+ * Caches the linked team's entitlement so the request-time gate does not call the SaaS backend on
+ * every billable request. Single-slot (one instance = one linked team), TTL-based.
+ *
+ * <p>Fail-open friendly for TRANSPORT failures: {@link #current()} returns the freshest snapshot it
+ * has, even if a refresh just failed; it returns {@link Optional#empty()} only when nothing has
+ * ever been fetched <i>and</i> the latest refresh failed (the gate treats empty as "unknown →
+ * allow").
+ *
+ * <p>But an AUTHORITATIVE deny (revoked/invalid credential → {@link
+ * AccountLinkClient.RevokedException}) is NOT a transport failure: the snapshot is replaced with a
+ * {@link EntitlementState#REVOKED} blocked entitlement so the gate stops billable work immediately
+ * rather than serving a stale entitled snapshot.
+ */
+@Slf4j
+@Service
+@Profile("!saas")
+@ConditionalOnProperty(name = "stirling.billing.account-link.enabled", havingValue = "true")
+public class EntitlementCache {
+
+    private final DeviceCredentialStore credentialStore;
+    private final AccountLinkClient client;
+    private final Duration ttl;
+
+    /** Entitlement + fetch time, swapped atomically as one value so readers never tear. */
+    private record Snapshot(InstanceEntitlement entitlement, Instant fetchedAt) {}
+
+    private static final Snapshot EMPTY = new Snapshot(null, Instant.EPOCH);
+
+    /** Blocked entitlement synthesised on an authoritative deny (revoked/invalid credential). */
+    private static final InstanceEntitlement REVOKED =
+            new InstanceEntitlement(false, 0, 0, null, EntitlementState.REVOKED);
+
+    private volatile Snapshot snapshot = EMPTY;
+
+    /** Single-flight guard: one thread refreshes while others serve the current snapshot. */
+    private final AtomicBoolean refreshing = new AtomicBoolean(false);
+
+    public EntitlementCache(
+            DeviceCredentialStore credentialStore,
+            AccountLinkClient client,
+            AccountLinkProperties properties) {
+        this.credentialStore = credentialStore;
+        this.client = client;
+        this.ttl = Duration.ofSeconds(properties.getEntitlementCacheSeconds());
+    }
+
+    /**
+     * Current entitlement, refreshing if stale. {@link Optional#empty()} means "unknown" — either
+     * not linked or the SaaS side is unreachable and we have no prior snapshot.
+     */
+    public Optional<InstanceEntitlement> current() {
+        // Single-flight: when stale, exactly one thread refreshes (blocking on the SaaS
+        // call) while concurrent callers serve the last snapshot — no thundering herd of
+        // synchronous round-trips on the billable hot path. Safe because the gate fails open.
+        if (isStale(snapshot) && refreshing.compareAndSet(false, true)) {
+            try {
+                refresh();
+            } finally {
+                refreshing.set(false);
+            }
+        }
+        return Optional.ofNullable(snapshot.entitlement());
+    }
+
+    private boolean isStale(Snapshot snap) {
+        // fetchedAt is the last *attempt* time (stamped on success AND failure), so a failed
+        // fetch backs off for a full TTL instead of every billable request re-triggering a
+        // blocking round-trip against a dead/slow SaaS endpoint.
+        return Duration.between(snap.fetchedAt(), Instant.now()).compareTo(ttl) >= 0;
+    }
+
+    /**
+     * Pulls a fresh snapshot. Keeps the previous entitlement on a TRANSPORT failure (fail-open) but
+     * still stamps the attempt time so re-fetches throttle to the TTL; on an AUTHORITATIVE deny
+     * (revoked credential) replaces it with a blocked snapshot so the gate stops billable work.
+     */
+    void refresh() {
+        Optional<DeviceCredential> cred = credentialStore.get();
+        if (cred.isEmpty()) {
+            // Unlinked: clear any stale snapshot so the gate sees "not linked".
+            snapshot = new Snapshot(null, Instant.now());
+            return;
+        }
+        try {
+            InstanceEntitlement fresh =
+                    client.fetchEntitlement(cred.get().getDeviceId(), cred.get().getDeviceSecret());
+            if (fresh != null) {
+                snapshot = new Snapshot(fresh, Instant.now());
+            } else {
+                // Unreachable / server error: keep the last known entitlement (may be null) but
+                // stamp the attempt so we don't hammer SaaS; the gate fails open in the meantime.
+                log.debug(
+                        "Entitlement refresh failed; reusing last known snapshot, backing off a TTL");
+                snapshot = new Snapshot(snapshot.entitlement(), Instant.now());
+            }
+        } catch (AccountLinkClient.RevokedException e) {
+            // Authoritative deny — credential revoked/invalid. Do NOT fail open: block immediately
+            // rather than serving the stale entitled snapshot until the next unlink.
+            log.info(
+                    "Entitlement denied (HTTP {}); blocking billable work for the revoked credential",
+                    e.status());
+            snapshot = new Snapshot(REVOKED, Instant.now());
+        }
+    }
+
+    /** Forces a refresh on the next {@link #current()} (e.g. right after linking). */
+    public void invalidate() {
+        snapshot = new Snapshot(snapshot.entitlement(), Instant.EPOCH);
+    }
+}
@@ -0,0 +1,19 @@
+package stirling.software.proprietary.accountlink;
+
+/**
+ * Coarse entitlement state the local gate enforces against. Proprietary-local (no coupling to the
+ * saas billing module): the SaaS entitlement response is parsed into this minimal shape.
+ */
+public enum EntitlementState {
+    /** Within free pool or covered by an active subscription — billable work allowed. */
+    OK,
+    /** Free pool exhausted and no subscription / over the period cap — billable work blocked. */
+    OVER_LIMIT,
+    /**
+     * Device credential revoked/invalid on the SaaS side (authoritative 401/403 deny) — billable
+     * work blocked. Synthesised locally by {@code EntitlementCache}, never sent by SaaS.
+     */
+    REVOKED,
+    /** Unrecognised/malformed reply — the gate falls back to its numeric checks, not this flag. */
+    UNKNOWN
+}
@@ -0,0 +1,34 @@
+package stirling.software.proprietary.accountlink;
+
+/**
+ * Outcome of {@link InstanceEntitlementGate}. {@link #allowed} is what the interceptor enforces;
+ * {@link #reason} carries the machine-readable signal the FE maps to a prompt (e.g. "link to
+ * activate"). Manual-tool and fail-open allows carry an informational reason but never block.
+ */
+public record GateDecision(boolean allowed, Reason reason) {
+
+    public enum Reason {
+        /** Feature flag is off — gate is fully inert. */
+        FLAG_OFF,
+        /** Operation is a manual tool — always free, never gated. */
+        MANUAL_FREE,
+        /** Linked + within entitlement — billable work allowed. */
+        ENTITLED,
+        /** Entitlement source unreachable — fail open, allow. */
+        FAIL_OPEN,
+        /** Not linked — block billable work; FE should prompt to link. */
+        NOT_LINKED,
+        /** Linked but over the limit / no subscription — block billable work. */
+        OVER_LIMIT,
+        /** Credential revoked/invalid on the SaaS side — block billable work. */
+        REVOKED
+    }
+
+    public static GateDecision allow(Reason reason) {
+        return new GateDecision(true, reason);
+    }
+
+    public static GateDecision block(Reason reason) {
+        return new GateDecision(false, reason);
+    }
+}
@@ -0,0 +1,19 @@
+package stirling.software.proprietary.accountlink;
+
+/**
+ * Cached, proprietary-local view of the SaaS {@code GET /api/v1/instance/entitlement} response —
+ * just the fields the gate needs. Mirrors the saas {@code EntitlementResponse} shape but carries no
+ * saas types.
+ *
+ * @param subscribed team has an active subscription
+ * @param freeRemainingUnits remaining free-pool units (>0 means free work is available)
+ * @param periodSpendUnits paid units spent this period
+ * @param periodCapUnits paid cap for the period; {@code null} = uncapped
+ * @param state coarse state classification (see {@link EntitlementState})
+ */
+public record InstanceEntitlement(
+        boolean subscribed,
+        long freeRemainingUnits,
+        long periodSpendUnits,
+        Long periodCapUnits,
+        EntitlementState state) {}
@@ -0,0 +1,104 @@
+package stirling.software.proprietary.accountlink;
+
+import java.util.Optional;
+
+import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
+import org.springframework.context.annotation.Profile;
+import org.springframework.stereotype.Service;
+
+/**
+ * Decides whether a request may proceed under combined-billing "Mode A" on a self-hosted instance.
+ *
+ * <p>Rules (in order):
+ *
+ * <ol>
+ *   <li>Flag off → always allow (feature inert).
+ *   <li>Manual tool → always allow (manual tools are free, never metered).
+ *   <li>Billable + not linked → block with {@code NOT_LINKED} ("link to activate").
+ *   <li>Billable + linked + entitlement unknown (unreachable) → <b>fail open</b>, allow.
+ *   <li>Billable + linked + entitled → allow.
+ *   <li>Billable + linked + credential revoked → block with {@code REVOKED}.
+ *   <li>Billable + linked + over limit → block with {@code OVER_LIMIT}.
+ * </ol>
+ *
+ * <p>The decision logic is the pure static {@link #decide}; the Spring wrapper just supplies the
+ * live flag / linked-state / entitlement. This is the unit-tested core.
+ */
+@Service
+@Profile("!saas")
+@ConditionalOnProperty(name = "stirling.billing.account-link.enabled", havingValue = "true")
+public class InstanceEntitlementGate {
+
+    private final AccountLinkProperties properties;
+    private final DeviceCredentialStore credentialStore;
+    private final EntitlementCache entitlementCache;
+
+    public InstanceEntitlementGate(
+            AccountLinkProperties properties,
+            DeviceCredentialStore credentialStore,
+            EntitlementCache entitlementCache) {
+        this.properties = properties;
+        this.credentialStore = credentialStore;
+        this.entitlementCache = entitlementCache;
+    }
+
+    /** Evaluates the gate for a request, resolving live state from the store + cache. */
+    public GateDecision evaluate(boolean billable) {
+        if (!properties.isEnabled()) {
+            return GateDecision.allow(GateDecision.Reason.FLAG_OFF);
+        }
+        if (!billable) {
+            return GateDecision.allow(GateDecision.Reason.MANUAL_FREE);
+        }
+        boolean linked = credentialStore.isLinked();
+        Optional<InstanceEntitlement> entitlement =
+                linked ? entitlementCache.current() : Optional.empty();
+        return decide(true, true, linked, entitlement);
+    }
+
+    /**
+     * Pure decision function — no Spring, no I/O. {@code entitlement} empty means "unknown"
+     * (unreachable): when linked, that fails open.
+     */
+    public static GateDecision decide(
+            boolean flagEnabled,
+            boolean billable,
+            boolean linked,
+            Optional<InstanceEntitlement> entitlement) {
+        if (!flagEnabled) {
+            return GateDecision.allow(GateDecision.Reason.FLAG_OFF);
+        }
+        if (!billable) {
+            return GateDecision.allow(GateDecision.Reason.MANUAL_FREE);
+        }
+        if (!linked) {
+            return GateDecision.block(GateDecision.Reason.NOT_LINKED);
+        }
+        if (entitlement.isEmpty()) {
+            // Linked but entitlement source unreachable — never hard-block billable work on our
+            // inability to reach billing.
+            return GateDecision.allow(GateDecision.Reason.FAIL_OPEN);
+        }
+        InstanceEntitlement e = entitlement.get();
+        if (e.state() == EntitlementState.REVOKED) {
+            // Credential revoked/invalid (authoritative deny) — block, distinct from over-limit.
+            return GateDecision.block(GateDecision.Reason.REVOKED);
+        }
+        return entitled(e)
+                ? GateDecision.allow(GateDecision.Reason.ENTITLED)
+                : GateDecision.block(GateDecision.Reason.OVER_LIMIT);
+    }
+
+    /** True when the snapshot permits billable work (subscribed, free pool left, or within cap). */
+    private static boolean entitled(InstanceEntitlement e) {
+        if (e.state() == EntitlementState.OVER_LIMIT || e.state() == EntitlementState.REVOKED) {
+            return false;
+        }
+        if (e.subscribed()) {
+            // Subscribed: allowed unless a period cap is set and exceeded.
+            return e.periodCapUnits() == null || e.periodSpendUnits() < e.periodCapUnits();
+        }
+        // Unsubscribed: only the free pool covers billable work.
+        return e.freeRemainingUnits() > 0;
+    }
+}
@@ -0,0 +1,65 @@
+package stirling.software.proprietary.accountlink;
+
+import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
+import org.springframework.context.annotation.Profile;
+import org.springframework.http.HttpStatus;
+import org.springframework.stereotype.Component;
+import org.springframework.web.servlet.HandlerInterceptor;
+
+import jakarta.servlet.http.HttpServletRequest;
+import jakarta.servlet.http.HttpServletResponse;
+
+import lombok.extern.slf4j.Slf4j;
+
+/**
+ * Request-time gate for combined-billing "Mode A". Runs before billable (AI / automation) work and
+ * blocks it when the instance is unlinked or over its limit; manual tools pass straight through.
+ *
+ * <p>Blocking responds {@code 402 Payment Required} with a small machine-readable body — {@code
+ * {"error":"ACCOUNT_LINK_REQUIRED","reason":"NOT_LINKED"}} — that the FE maps to a "link to
+ * activate" prompt (the same DownstreamEntitlementError-style envelope already used for saas limit
+ * responses). Fail-open and flag-off both let the request continue.
+ *
+ * <p>Gated + {@code @Profile("!saas")}; when the flag is off the bean is absent and the {@link
+ * AccountLinkWebMvcConfig} never registers it, so there is no per-request cost.
+ */
+@Slf4j
+@Component
+@Profile("!saas")
+@ConditionalOnProperty(name = "stirling.billing.account-link.enabled", havingValue = "true")
+public class InstanceEntitlementInterceptor implements HandlerInterceptor {
+
+    private final InstanceEntitlementGate gate;
+
+    public InstanceEntitlementInterceptor(InstanceEntitlementGate gate) {
+        this.gate = gate;
+    }
+
+    @Override
+    public boolean preHandle(
+            HttpServletRequest request, HttpServletResponse response, Object handler)
+            throws Exception {
+        GateDecision decision;
+        try {
+            decision = gate.evaluate(BillableOperationClassifier.isBillable(request));
+        } catch (RuntimeException e) {
+            // Fail open: an inability to resolve entitlement (e.g. a DB or SaaS blip) must never
+            // turn into a hard block on billable work.
+            log.debug("Account-link gate evaluation failed; allowing request", e);
+            return true;
+        }
+        if (decision.allowed()) {
+            return true;
+        }
+
+        log.debug("Account-link gate blocked {} ({})", request.getRequestURI(), decision.reason());
+        response.setStatus(HttpStatus.PAYMENT_REQUIRED.value());
+        response.setContentType("application/json");
+        response.getWriter()
+                .write(
+                        "{\"error\":\"ACCOUNT_LINK_REQUIRED\",\"reason\":\""
+                                + decision.reason().name()
+                                + "\"}");
+        return false;
+    }
+}
@@ -0,0 +1,116 @@
+package stirling.software.proprietary.classification;
+
+import org.springframework.boot.autoconfigure.condition.ConditionalOnBooleanProperty;
+import org.springframework.http.HttpStatus;
+import org.springframework.http.MediaType;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.DeleteMapping;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PutMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+import org.springframework.web.server.ResponseStatusException;
+
+import io.swagger.v3.oas.annotations.Hidden;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
+
+import lombok.RequiredArgsConstructor;
+
+import stirling.software.common.model.ApplicationProperties;
+import stirling.software.common.service.UserServiceInterface;
+import stirling.software.proprietary.classification.model.ClassificationTaxonomy;
+import stirling.software.proprietary.classification.model.TaxonomyValidator;
+import stirling.software.proprietary.classification.store.TaxonomyStore;
+import stirling.software.proprietary.policy.config.PolicyManagementAuthority;
+
+/**
+ * Read/write the caller's team classification taxonomy — the vocabulary the document classifier
+ * runs against. Team-scoped exactly like policies: every user reads their own team's taxonomy, and
+ * only a user who may edit policies (a team leader on SaaS, the global admin self-hosted; see
+ * {@link PolicyManagementAuthority}) may change it. Editing is gated only when login is enabled;
+ * single-user deployments trust the local operator. A team with no stored taxonomy reads as {@code
+ * 204} and the classifier falls back to the engine's built-in default.
+ */
+@RestController
+@RequestMapping("/api/v1/classification/taxonomy")
+@Hidden
+@RequiredArgsConstructor
+@Tag(name = "Classification", description = "Team-scoped document-classification taxonomy")
+@ConditionalOnBooleanProperty(name = "policies.enabled")
+public class TaxonomyController {
+
+    private final TaxonomyStore taxonomyStore;
+    private final PolicyManagementAuthority policyManagementAuthority;
+    private final ApplicationProperties applicationProperties;
+    private final UserServiceInterface userService;
+
+    @GetMapping
+    @Operation(
+            summary = "Get the team's classification taxonomy",
+            description =
+                    "Returns the caller's team taxonomy, or 204 when the team has none (the"
+                            + " classifier then uses the built-in default).")
+    public ResponseEntity<ClassificationTaxonomy> getTaxonomy() {
+        return taxonomyStore
+                .findByTeam(currentTeamId())
+                .map(ResponseEntity::ok)
+                .orElseGet(() -> ResponseEntity.noContent().build());
+    }
+
+    @PutMapping(consumes = MediaType.APPLICATION_JSON_VALUE)
+    @Operation(
+            summary = "Save the team's classification taxonomy",
+            description =
+                    "Validates and stores the taxonomy for the caller's team, shared by everyone on"
+                            + " the team. Requires the policy-editor role for the team.")
+    public ResponseEntity<ClassificationTaxonomy> saveTaxonomy(
+            @RequestBody ClassificationTaxonomy taxonomy) {
+        requireEditingAllowed();
+        try {
+            TaxonomyValidator.validate(taxonomy);
+        } catch (IllegalArgumentException e) {
+            throw new ResponseStatusException(HttpStatus.BAD_REQUEST, e.getMessage());
+        }
+        ClassificationTaxonomy saved =
+                taxonomyStore.save(currentTeamId(), taxonomy, currentUsername());
+        return ResponseEntity.ok(saved);
+    }
+
+    @DeleteMapping
+    @Operation(
+            summary = "Reset the team's classification taxonomy",
+            description =
+                    "Removes the team's stored taxonomy so the classifier falls back to the built-in"
+                            + " default. Requires the policy-editor role for the team.")
+    public ResponseEntity<Void> resetTaxonomy() {
+        requireEditingAllowed();
+        taxonomyStore.deleteByTeam(currentTeamId());
+        return ResponseEntity.noContent().build();
+    }
+
+    /**
+     * Editing the taxonomy requires the editor role for the caller's team — the same gate policies
+     * use (team leader on SaaS, global admin self-hosted). Single-user deployments (login disabled)
+     * have no such role, so they trust the local operator.
+     */
+    private void requireEditingAllowed() {
+        if (!applicationProperties.getSecurity().isEnableLogin()) {
+            return;
+        }
+        if (!policyManagementAuthority.canEditPolicies()) {
+            throw new ResponseStatusException(
+                    HttpStatus.FORBIDDEN,
+                    "The classification taxonomy may only be changed by a team leader");
+        }
+    }
+
+    private Long currentTeamId() {
+        return policyManagementAuthority.currentUserTeamId();
+    }
+
+    private String currentUsername() {
+        return userService == null ? null : userService.getCurrentUsername();
+    }
+}
@@ -0,0 +1,18 @@
+package stirling.software.proprietary.classification.model;
+
+import java.util.List;
+
+/**
+ * The vocabulary a document is classified against — team-scoped and admin-editable. Its shape
+ * mirrors the engine's {@code ClassificationTaxonomy} contract (categories owning doc_types, plus
+ * free-standing cross-cutting tags), so a stored taxonomy is passed to the engine verbatim as the
+ * per-request override. When a team has no stored taxonomy the engine falls back to its built-in
+ * default.
+ */
+public record ClassificationTaxonomy(List<TaxonomyCategory> categories, List<String> tags) {
+
+    public ClassificationTaxonomy {
+        categories = categories == null ? List.of() : List.copyOf(categories);
+        tags = tags == null ? List.of() : List.copyOf(tags);
+    }
+}
@@ -0,0 +1,15 @@
+package stirling.software.proprietary.classification.model;
+
+import java.util.List;
+
+/**
+ * A structural family of documents, owning the doc_types shaped like it. {@code docTypes} is
+ * serialized in the engine's camelCase shape (the engine's {@code ClassificationTaxonomy} model
+ * aliases {@code doc_types} onto it), so a stored taxonomy passes straight through to the engine.
+ */
+public record TaxonomyCategory(String id, String label, List<TaxonomyDocumentType> docTypes) {
+
+    public TaxonomyCategory {
+        docTypes = docTypes == null ? List.of() : List.copyOf(docTypes);
+    }
+}
@@ -0,0 +1,7 @@
+package stirling.software.proprietary.classification.model;
+
+/**
+ * A specific instrument within a category (e.g. {@code nda} under {@code contract}).
+ * Category-scoped: the engine enforces that a doc_type can only apply to its owning category.
+ */
+public record TaxonomyDocumentType(String id, String label) {}
--- a/Show More
+++ b/Show More