diff --git a/.claude/settings.json b/.claude/settings.json
new file mode 100644
index 0000000000..40d0b73379
--- /dev/null
+++ b/.claude/settings.json
@@ -0,0 +1,19 @@
+{
+ "$schema": "https://json.schemastore.org/claude-code-settings.json",
+ "hooks": {
+ "Stop": [
+ {
+ "hooks": [
+ {
+ "type": "command",
+ "command": "node",
+ "args": [
+ "${CLAUDE_PROJECT_DIR}/scripts/lint/comment-lint-hook.mjs"
+ ],
+ "timeout": 60
+ }
+ ]
+ }
+ ]
+ }
+}
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
index 883c4f7f46..4ed61e37ec 100644
--- a/.github/dependabot.yml
+++ b/.github/dependabot.yml
@@ -8,11 +8,6 @@ updates:
- package-ecosystem: "gradle" # See documentation for possible values
directories:
- "/" # Location of package manifests
- - "/app/common"
- - "/app/core"
- - "/app/proprietary"
- - "/app/saas"
- - "/buildSrc"
schedule:
interval: "weekly"
cooldown:
diff --git a/.github/labeler-config-srvaroa.yml b/.github/labeler-config-srvaroa.yml
index bd1947d649..ea9613ea20 100644
--- a/.github/labeler-config-srvaroa.yml
+++ b/.github/labeler-config-srvaroa.yml
@@ -67,6 +67,7 @@ labels:
- 'frontend/**'
- 'frontend/.*'
- 'frontend/**/.*'
+ - '.taskfiles/frontend.yml'
- label: 'Tauri'
files:
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
index d9eb6dbe10..41666ff608 100644
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@@ -20,6 +20,7 @@ Closes #(issue_number)
- [ ] I have read the [Stirling-PDF Developer Guide](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/DeveloperGuide.md) (if applicable)
- [ ] I have read the [How to add new languages to Stirling-PDF](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/HowToAddNewLanguage.md) (if applicable)
- [ ] I have performed a self-review of my own code
+- [ ] Every comment I added says something the code does not ([guide](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/CODE_COMMENTS.md))
- [ ] My changes generate no new warnings
### Documentation
diff --git a/.github/workflows/Saas-Dev-Deploy.yml b/.github/workflows/Saas-Dev-Deploy.yml
new file mode 100644
index 0000000000..733b92bca2
--- /dev/null
+++ b/.github/workflows/Saas-Dev-Deploy.yml
@@ -0,0 +1,246 @@
+name: Auto SaaS Dev Deployment
+
+on:
+ push:
+ branches:
+ - saas-prod
+ workflow_dispatch:
+
+permissions:
+ contents: read
+
+env:
+ FRONTEND_PORT: "901"
+ BACKEND_PORT: "902"
+ DEPLOY_DIR: /stirling/SAAS-DEV
+
+jobs:
+ deploy-saas-dev:
+ runs-on: ubuntu-latest
+ environment: saas-dev
+ concurrency:
+ group: saas-dev-deploy
+ cancel-in-progress: true
+ permissions:
+ contents: read
+ packages: write
+
+ steps:
+ - name: Harden Runner
+ uses: step-security/harden-runner@bf7454d06d71f1098171f2acdf0cd4708d7b5920 # v2.20.0
+ with:
+ egress-policy: audit
+
+ - name: Check SaaS configuration
+ id: config
+ env:
+ PROJECT_REF: ${{ secrets.SAAS_DB_PROJECT_REF }}
+ run: |
+ echo "supabase_url=https://${PROJECT_REF}.supabase.co" >> "$GITHUB_OUTPUT"
+ echo "meter_endpoint=https://${PROJECT_REF}.supabase.co/functions/v1/meter-payg-units" >> "$GITHUB_OUTPUT"
+
+ - name: Checkout repository
+ uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+ with:
+ fetch-depth: 0
+
+ - name: Set up Docker Buildx
+ uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # v4.2.0
+
+ - name: Login to GitHub Container Registry
+ uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
+ with:
+ registry: ghcr.io
+ username: ${{ github.actor }}
+ password: ${{ github.token }}
+
+ - name: Convert repository owner to lowercase
+ id: repoowner
+ run: echo "lowercase=$(echo ${{ github.repository_owner }} | awk '{print tolower($0)}')" >> $GITHUB_OUTPUT
+
+ - name: Get commit hash
+ id: commit-hash
+ run: echo "app_short=$(git rev-parse --short=8 HEAD)" >> $GITHUB_OUTPUT
+
+ - name: Build and push backend image
+ uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
+ with:
+ context: .
+ file: ./docker/backend/Dockerfile
+ push: true
+ cache-from: type=gha,scope=stirling-saas-backend
+ cache-to: type=gha,mode=max,scope=stirling-saas-backend
+ tags: |
+ ghcr.io/${{ steps.repoowner.outputs.lowercase }}/stirling-pdf-test:saas-backend-${{ steps.commit-hash.outputs.app_short }}
+ ghcr.io/${{ steps.repoowner.outputs.lowercase }}/stirling-pdf-test:saas-backend-latest
+ build-args: |
+ VERSION_TAG=v2-alpha
+ STIRLING_FLAVOR=saas
+ platforms: linux/amd64
+
+ - name: Build and push frontend image
+ uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
+ with:
+ context: .
+ file: ./docker/frontend/Dockerfile
+ push: true
+ cache-from: type=gha,scope=stirling-saas-frontend
+ cache-to: type=gha,mode=max,scope=stirling-saas-frontend
+ tags: |
+ ghcr.io/${{ steps.repoowner.outputs.lowercase }}/stirling-pdf-test:saas-frontend-${{ steps.commit-hash.outputs.app_short }}
+ ghcr.io/${{ steps.repoowner.outputs.lowercase }}/stirling-pdf-test:saas-frontend-latest
+ build-args: |
+ VERSION_TAG=v2-alpha
+ STIRLING_FLAVOR=saas
+ VITE_BUILD_MODE=development
+ VITE_SUPABASE_URL=${{ steps.config.outputs.supabase_url }}
+ VITE_SUPABASE_PUBLISHABLE_DEFAULT_KEY=${{ secrets.SAAS_SUPABASE_PUBLISHABLE_KEY }}
+ platforms: linux/amd64
+
+ - name: Build and push AI engine image
+ uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
+ with:
+ context: .
+ file: ./engine/Dockerfile
+ push: true
+ cache-from: type=gha,scope=stirling-saas-engine
+ cache-to: type=gha,mode=max,scope=stirling-saas-engine
+ tags: |
+ ghcr.io/${{ steps.repoowner.outputs.lowercase }}/stirling-pdf-test:saas-engine-${{ steps.commit-hash.outputs.app_short }}
+ ghcr.io/${{ steps.repoowner.outputs.lowercase }}/stirling-pdf-test:saas-engine-latest
+ platforms: linux/amd64
+
+ - name: Set up SSH
+ env:
+ SSH_KEY: ${{ secrets.NEW_VPS_SSH_KEY }}
+ run: |
+ mkdir -p ~/.ssh/
+ echo "$SSH_KEY" > ../private.key
+ sudo chmod 600 ../private.key
+
+ - name: Deploy to VPS
+ env:
+ IMAGE_BASE: ghcr.io/${{ steps.repoowner.outputs.lowercase }}/stirling-pdf-test
+ IMAGE_TAG: ${{ steps.commit-hash.outputs.app_short }}
+ GHCR_USER: ${{ github.actor }}
+ GHCR_TOKEN: ${{ github.token }}
+ VPS_USERNAME: ${{ secrets.NEW_VPS_USERNAME }}
+ VPS_HOST: ${{ secrets.NEW_VPS_HOST }}
+ SAAS_DB_URL: ${{ secrets.SAAS_DB_URL }}
+ SAAS_DB_USERNAME: ${{ secrets.SAAS_DB_USERNAME || 'postgres' }}
+ SAAS_DB_PASSWORD: ${{ secrets.SAAS_DB_PASSWORD }}
+ SAAS_DB_PROJECT_REF: ${{ secrets.SAAS_DB_PROJECT_REF }}
+ SUPABASE_EDGE_FUNCTION_SECRET: ${{ secrets.SUPABASE_EDGE_FUNCTION_SECRET }}
+ PAYG_METER_ENDPOINT: ${{ steps.config.outputs.meter_endpoint }}
+ STIRLING_KEYGEN_ENABLED: ${{ secrets.KEYGEN_ACCOUNT_ID != '' && secrets.KEYGEN_API_TOKEN != '' && secrets.KEYGEN_POLICY_ID != '' }}
+ KEYGEN_ACCOUNT_ID: ${{ secrets.KEYGEN_ACCOUNT_ID }}
+ KEYGEN_API_TOKEN: ${{ secrets.KEYGEN_API_TOKEN }}
+ KEYGEN_POLICY_ID: ${{ secrets.KEYGEN_POLICY_ID }}
+ ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+ VOYAGE_API_KEY: ${{ secrets.VOYAGE_API_KEY }}
+ run: |
+ set -euo pipefail
+
+ BASE_URL="http://${VPS_HOST}:${FRONTEND_PORT}"
+
+ yaml() {
+ printf "'%s'" "$(printf '%s' "$1" | sed -e "s/'/''/g" -e 's/\$/$$/g')"
+ }
+
+ ENGINE_SECRET="$(openssl rand -hex 32)"
+ AI_BACKEND_VARS="
+ SYSTEM_AIENGINE_ENABLED: \"true\"
+ SYSTEM_AIENGINE_URL: \"http://saas-engine:5001\"
+ APP_AI_SERVICEBASEURL: \"http://saas-engine:5001\"
+ STIRLING_ENGINE_SHARED_SECRET: $(yaml "$ENGINE_SECRET")"
+ AI_SERVICE="
+
+ saas-engine:
+ container_name: stirling-saas-dev-engine
+ image: ${IMAGE_BASE}:saas-engine-${IMAGE_TAG}
+ environment:
+ ANTHROPIC_API_KEY: $(yaml "$ANTHROPIC_API_KEY")
+ VOYAGE_API_KEY: $(yaml "$VOYAGE_API_KEY")
+ STIRLING_ENGINE_SHARED_SECRET: $(yaml "$ENGINE_SECRET")
+ restart: on-failure:5"
+
+ cat > docker-compose.yml << EOF
+ version: '3.3'
+ services:
+ saas-backend:
+ container_name: stirling-saas-dev-backend
+ image: ${IMAGE_BASE}:saas-backend-${IMAGE_TAG}
+ ports:
+ - "${BACKEND_PORT}:8080"
+ volumes:
+ - ${DEPLOY_DIR}/config:/configs:rw
+ - ${DEPLOY_DIR}/logs:/logs:rw
+ - ${DEPLOY_DIR}/storage:/storage:rw
+ environment:
+ SPRING_PROFILES_ACTIVE: "saas"
+ DISABLE_ADDITIONAL_FEATURES: "false"
+ SAAS_DB_URL: $(yaml "$SAAS_DB_URL")
+ SAAS_DB_USERNAME: $(yaml "$SAAS_DB_USERNAME")
+ SAAS_DB_PASSWORD: $(yaml "$SAAS_DB_PASSWORD")
+ SAAS_DB_PROJECT_REF: $(yaml "$SAAS_DB_PROJECT_REF")
+ SUPABASE_EDGE_FUNCTION_SECRET: $(yaml "$SUPABASE_EDGE_FUNCTION_SECRET")
+ PAYG_METER_ENDPOINT: $(yaml "$PAYG_METER_ENDPOINT")
+ STIRLING_KEYGEN_ENABLED: $(yaml "$STIRLING_KEYGEN_ENABLED")
+ KEYGEN_ACCOUNT_ID: $(yaml "$KEYGEN_ACCOUNT_ID")
+ KEYGEN_API_TOKEN: $(yaml "$KEYGEN_API_TOKEN")
+ KEYGEN_POLICY_ID: $(yaml "$KEYGEN_POLICY_ID")
+ SYSTEM_DEFAULTLOCALE: en-US
+ SYSTEM_MAXFILESIZE: "100"
+ METRICS_ENABLED: "true"
+ SYSTEM_GOOGLEVISIBILITY: "false"
+ SWAGGER_SERVER_URL: "${BASE_URL}"
+ baseUrl: "${BASE_URL}"${AI_BACKEND_VARS}
+ restart: on-failure:5
+
+ saas-frontend:
+ container_name: stirling-saas-dev-frontend
+ image: ${IMAGE_BASE}:saas-frontend-${IMAGE_TAG}
+ ports:
+ - "${FRONTEND_PORT}:80"
+ environment:
+ VITE_API_BASE_URL: "http://saas-backend:8080"
+ depends_on:
+ - saas-backend
+ restart: on-failure:5${AI_SERVICE}
+ EOF
+
+ SSH_OPTS=(-i ../private.key -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null)
+
+ scp "${SSH_OPTS[@]}" docker-compose.yml "${VPS_USERNAME}@${VPS_HOST}:/tmp/saas-dev-docker-compose.yml"
+
+ ssh "${SSH_OPTS[@]}" -T "${VPS_USERNAME}@${VPS_HOST}" << ENDSSH
+ set -e
+ mkdir -p ${DEPLOY_DIR}/{config,logs,storage}
+ mv /tmp/saas-dev-docker-compose.yml ${DEPLOY_DIR}/docker-compose.yml
+ chmod 600 ${DEPLOY_DIR}/docker-compose.yml
+ cd ${DEPLOY_DIR}
+ printf '%s' "${GHCR_TOKEN}" | docker login ghcr.io -u "${GHCR_USER}" --password-stdin
+ docker-compose down --remove-orphans 2>/dev/null || true
+ docker-compose pull
+ docker-compose up -d
+ docker logout ghcr.io >/dev/null 2>&1 || true
+ docker image prune -af --filter "until=336h" --filter "label!=keep=true" || true
+ ENDSSH
+
+ - name: Wait for the backend to answer
+ env:
+ VPS_HOST: ${{ secrets.NEW_VPS_HOST }}
+ run: |
+ URL="http://${VPS_HOST}:${BACKEND_PORT}/api/v1/info/status"
+ for i in $(seq 1 60); do
+ code=$(curl -s -o /dev/null -w '%{http_code}' --max-time 5 "$URL" || true)
+ if [ "$code" = "200" ]; then echo "Healthy after $((i * 10))s"; exit 0; fi
+ sleep 10
+ done
+ echo "::error::SaaS dev backend did not become healthy within 10 minutes"
+ exit 1
+
+ - name: Cleanup temporary files
+ if: always()
+ run: rm -f ../private.key docker-compose.yml
+ continue-on-error: true
diff --git a/.github/workflows/ai-engine.yml b/.github/workflows/ai-engine.yml
index caa5af1acb..357dfa1e49 100644
--- a/.github/workflows/ai-engine.yml
+++ b/.github/workflows/ai-engine.yml
@@ -34,7 +34,6 @@ jobs:
cache-dependency-glob: |
engine/pyproject.toml
engine/uv.lock
- cache-suffix: ai-engine
- name: Install Task
uses: go-task/setup-task@01a4adf9db2d14c1de7a560f09170b6e0df736aa # v2.1.0
diff --git a/.github/workflows/check-generated-models.yml b/.github/workflows/check-generated-models.yml
index 476f9d21a7..f917a4c602 100644
--- a/.github/workflows/check-generated-models.yml
+++ b/.github/workflows/check-generated-models.yml
@@ -42,7 +42,6 @@ jobs:
cache-dependency-glob: |
engine/pyproject.toml
engine/uv.lock
- cache-suffix: generated-models
- name: Restore cache Gradle User Home
if: inputs.use_shared_cache
diff --git a/.github/workflows/pre_commit.yml b/.github/workflows/pre_commit.yml
index 674822363b..fbd9efc474 100644
--- a/.github/workflows/pre_commit.yml
+++ b/.github/workflows/pre_commit.yml
@@ -31,10 +31,14 @@ jobs:
cache-dependency-glob: |
engine/pyproject.toml
engine/uv.lock
- cache-suffix: pre-commit
- name: Install Task
uses: go-task/setup-task@01a4adf9db2d14c1de7a560f09170b6e0df736aa # v2.1.0
- name: Run pre-commit checks
run: task pre-commit
+
+ # The fixture corpus checks the comment rules themselves, so it runs here
+ # rather than on every local commit.
+ - name: Check the comment-lint fixture corpus
+ run: task pre-commit:comment-lint:selftest
diff --git a/.github/workflows/sync_files_v2.yml b/.github/workflows/sync_files_v2.yml
index a199fd6cbd..f688476159 100644
--- a/.github/workflows/sync_files_v2.yml
+++ b/.github/workflows/sync_files_v2.yml
@@ -59,7 +59,6 @@ jobs:
cache-dependency-glob: |
engine/pyproject.toml
engine/uv.lock
- cache-suffix: sync-files
- name: Install Python dependencies
run: |
diff --git a/.gitignore b/.gitignore
index 1290056e05..ca683dc5d4 100644
--- a/.gitignore
+++ b/.gitignore
@@ -298,8 +298,13 @@ docs/type3/signatures/
**/application-dev-local.properties
-# Claude
-.claude/
+# Claude. Contents are ignored so personal config stays local, with the two
+# shared pieces re-included: settings.json (the comment-lint hook) and skills/.
+# The directory itself cannot be ignored or git will not look inside it.
+.claude/*
+!.claude/settings.json
+!.claude/skills/
+.claude/settings.local.json
# Playwright MCP screenshots / traces
.playwright-mcp/
diff --git a/.taskfiles/backend.yml b/.taskfiles/backend.yml
index 08a12b9535..3e43321937 100644
--- a/.taskfiles/backend.yml
+++ b/.taskfiles/backend.yml
@@ -40,12 +40,15 @@ tasks:
AIENGINE_ENABLED: '{{.AIENGINE_ENABLED | default "false"}}'
AIENGINE_TIMEOUTSECONDS: '{{.AIENGINE_TIMEOUTSECONDS | default "120"}}'
SECURITY_ENABLELOGIN: '{{.SECURITY_ENABLELOGIN | default ""}}'
+ # Set by dev:linked. Inline rather than in `env:` so an empty value emits nothing
+ # and cannot blank the committed default.
+ ACCOUNT_LINK_SAAS_BASE_URL: '{{.ACCOUNT_LINK_SAAS_BASE_URL | 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 .ACCOUNT_LINK_SAAS_BASE_URL}}STIRLING_BILLING_ACCOUNT_LINK_ENABLED=true STIRLING_BILLING_ACCOUNT_LINK_SAAS_BASE_URL={{.ACCOUNT_LINK_SAAS_BASE_URL}} {{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 .ACCOUNT_LINK_SAAS_BASE_URL}}STIRLING_BILLING_ACCOUNT_LINK_ENABLED=true STIRLING_BILLING_ACCOUNT_LINK_SAAS_BASE_URL={{.ACCOUNT_LINK_SAAS_BASE_URL}} {{end}}./gradlew :stirling-pdf:bootRun'
platforms: [linux, darwin]
dev:bundled:
@@ -84,6 +87,8 @@ tasks:
AIENGINE_URL: '{{.AIENGINE_URL}}'
AIENGINE_ENABLED: '{{.AIENGINE_ENABLED}}'
AIENGINE_TIMEOUTSECONDS: '{{.AIENGINE_TIMEOUTSECONDS}}'
+ APP_BASE_URL: '{{.APP_BASE_URL}}'
+ BASE_PATH: '{{.BASE_PATH}}'
staging:saas:
desc: "Start SaaS backend against the shared v3 staging project"
@@ -95,10 +100,47 @@ tasks:
AIENGINE_URL: '{{.AIENGINE_URL}}'
AIENGINE_ENABLED: '{{.AIENGINE_ENABLED}}'
AIENGINE_TIMEOUTSECONDS: '{{.AIENGINE_TIMEOUTSECONDS}}'
+ APP_BASE_URL: '{{.APP_BASE_URL}}'
+ BASE_PATH: '{{.BASE_PATH}}'
+
+ dev:linked:
+ desc: "Self-hosted backend linked to a locally running SaaS backend (see task linked:*)"
+ ignore_error: true
+ vars:
+ PORT: '{{.PORT | default "8080"}}'
+ SAAS_BASE_URL: '{{.SAAS_BASE_URL | default "http://localhost:8081"}}'
+ cmds:
+ - 'echo ">> self-hosted :{{.PORT}} linking to SaaS at {{.SAAS_BASE_URL}}"'
+ # The two backends run different STIRLING_FLAVOURs, which are different Gradle
+ # project graphs sharing one build/ tree. Waiting avoids overlapping builds; it
+ # does not make the sharing safe, so avoid rebuilding one while the other runs.
+ - cmd: |
+ n=0
+ while [ "$n" -lt 150 ]; do
+ if curl -s -m 2 "{{.SAAS_BASE_URL}}" >/dev/null 2>&1; then
+ echo ">> SaaS backend is up, starting self-hosted"
+ break
+ fi
+ n=$((n + 1))
+ {{if eq OS "windows"}}powershell -NoProfile -Command "Start-Sleep -Seconds 2"{{else}}sleep 2{{end}}
+ done
+ if [ "$n" -ge 150 ]; then
+ echo ">> SaaS backend never answered; starting anyway"
+ fi
+ - task: dev:proprietary
+ vars:
+ PORT: '{{.PORT}}'
+ ACCOUNT_LINK_SAAS_BASE_URL: '{{.SAAS_BASE_URL}}'
_run:saas:
internal: true
- dotenv: ['app/.env.saas.local', 'app/.env.saas']
+ # The frontend files are here only for RUN_SUBPATH, which the authorize URL needs.
+ # Last, because dotenv is set-if-absent: app/* still decides everything else.
+ dotenv:
+ - 'app/.env.saas.local'
+ - 'app/.env.saas'
+ - 'frontend/editor/.env.saas.local'
+ - 'frontend/editor/.env.saas'
ignore_error: true
vars:
PORT: '{{.PORT | default "8080"}}'
@@ -111,12 +153,29 @@ tasks:
AIENGINE_URL: '{{.AIENGINE_URL | default ""}}'
AIENGINE_ENABLED: '{{.AIENGINE_ENABLED | default "false"}}'
AIENGINE_TIMEOUTSECONDS: '{{.AIENGINE_TIMEOUTSECONDS | default "120"}}'
+ # Empty is the same as unset: the property defaults to empty and is blank-checked.
+ APP_BASE_URL: '{{.APP_BASE_URL | default ""}}'
+ # Relocates configs/pipeline/logs, for a second backend in the same directory.
+ # Empty is the same as unset: the reader blank-checks it.
+ BASE_PATH: '{{.BASE_PATH | default ""}}'
env:
SERVER_PORT: '{{.PORT}}'
STIRLING_FLAVOR: saas
+ STIRLING_BASE_PATH: '{{.BASE_PATH}}'
AIENGINE_URL: '{{.AIENGINE_URL}}'
AIENGINE_ENABLED: '{{.AIENGINE_ENABLED}}'
AIENGINE_TIMEOUTSECONDS: '{{.AIENGINE_TIMEOUTSECONDS}}'
+ # Appends RUN_SUBPATH: the approval page is at /link, so a subpath build
+ # serves it at /app/link. An explicit value still wins.
+ SYSTEM_FRONTENDURL:
+ sh: |
+ if [ -n "${SYSTEM_FRONTENDURL:-}" ]; then
+ echo "${SYSTEM_FRONTENDURL}"
+ elif [ -n "{{.APP_BASE_URL}}" ] && [ -n "${RUN_SUBPATH:-}" ]; then
+ echo "{{.APP_BASE_URL}}/${RUN_SUBPATH}"
+ else
+ echo "{{.APP_BASE_URL}}"
+ fi
cmds:
# PROFILE_ARGS is empty when PROFILES=none, i.e. the bare `saas` profile
# against SAAS_DB_* (production).
diff --git a/.taskfiles/frontend.yml b/.taskfiles/frontend.yml
index 844306824d..9727538961 100644
--- a/.taskfiles/frontend.yml
+++ b/.taskfiles/frontend.yml
@@ -23,7 +23,7 @@ tasks:
- package-lock.json
- package.json
status:
- - test -d node_modules
+ - npm ls --depth=0
env:
CI: '{{ .CI | default "false" }}'
@@ -121,17 +121,17 @@ tasks:
sh: |
case "${SAAS_ENV:-dev}" in
staging) ref="${SAAS_STAGING_PROJECT_REF:?set it in app/.env.saas.local}" ;;
- *) ref="${SAAS_DEV_PROJECT_REF:?set it in app/.env.saas.local, or run task staging:saas}" ;;
+ *) ref="${SAAS_DEV_PROJECT_REF:?set it in app/.env.saas.local, or pass SAAS_ENV=staging}" ;;
esac
echo "https://${ref}.supabase.co"
VITE_SUPABASE_PUBLISHABLE_DEFAULT_KEY:
sh: |
case "${SAAS_ENV:-dev}" in
staging) echo "${SAAS_STAGING_PUBLISHABLE_KEY:?set it in app/.env.saas.local}" ;;
- *) echo "${SAAS_DEV_PUBLISHABLE_KEY:?set it in app/.env.saas.local}" ;;
+ *) echo "${SAAS_DEV_PUBLISHABLE_KEY:?set it in app/.env.saas.local, or pass SAAS_ENV=staging}" ;;
esac
cmds:
- - 'echo ">> frontend Supabase target: $VITE_SUPABASE_URL"'
+ - 'echo ">> frontend {{.SAAS_ENV}}: Supabase $VITE_SUPABASE_URL, backend $BACKEND_URL"'
- npx vite editor --mode saas --port {{.PORT}}{{if .OPEN}} --open{{end}}
dev:
@@ -173,6 +173,16 @@ tasks:
OPEN: '{{.OPEN}}'
SAAS_ENV: '{{.SAAS_ENV}}'
+ staging:saas:
+ desc: "Start frontend dev server against the shared v3 staging project"
+ cmds:
+ - task: dev:saas
+ vars:
+ SAAS_ENV: staging
+ PORT: '{{.PORT}}'
+ BACKEND_URL: '{{.BACKEND_URL}}'
+ OPEN: '{{.OPEN}}'
+
dev:desktop:
desc: "Start frontend dev server in desktop mode"
deps:
diff --git a/.taskfiles/pre-commit.yml b/.taskfiles/pre-commit.yml
index 444115010f..f65a296160 100644
--- a/.taskfiles/pre-commit.yml
+++ b/.taskfiles/pre-commit.yml
@@ -11,6 +11,7 @@ vars:
'.github/scripts/*.py'
'app/core/src/main/resources/static/python/*.py'
':(exclude)*split_photos.py'
+ ':(exclude)scripts/lint/fixtures/*'
SPELL_FILES: >-
'*.html'
'*.css'
@@ -59,6 +60,7 @@ tasks:
- task: gitleaks
- task: whitespace
- task: toml-sort
+ - task: comment-lint
fix:
desc: "Auto-fix formatting, spelling, and secrets issues across the repo"
@@ -75,6 +77,7 @@ tasks:
vars: { FIX: '1' }
- task: codespell
- task: gitleaks
+ - task: comment-lint
install:
desc: "Install the pinned pre-commit Python tools"
@@ -130,6 +133,85 @@ tasks:
cmds:
- "{{.GITLEAKS_BIN}} git --pre-commit --redact --staged --verbose"
+ comment-lint:
+ desc: "Check comment quality on the lines this branch adds"
+ summary: |
+ Blocks a comment that restates the code below it, a section banner, or a
+ block of commented-out code. Everything else it reports is advisory.
+
+ Scoped to added lines, so touching an old file never surfaces the standing
+ backlog. The standard is devGuide/CODE_COMMENTS.md.
+
+ With no arguments it diffs the working tree against HEAD, which is what a
+ pre-commit run wants: the lines you are about to commit. On a CI pull request
+ it diffs against the target branch instead, via GITHUB_BASE_REF.
+
+ To ask what a whole branch adds instead, use the branch variant, which
+ needs no argument passing:
+ task comment-lint:branch
+
+ Full tree (report only): task pre-commit:comment-lint:all
+ Fixture corpus: task pre-commit:comment-lint:selftest
+ # Depends on the frontend install because the .ts/.tsx half of the rule set
+ # runs as an oxlint plugin. Without it the TS engine warns and skips, which
+ # would leave the frontend silently unchecked on CI.
+ deps: [":frontend:install"]
+ cmds:
+ - node scripts/lint/comment-lint.mjs {{.CLI_ARGS}}
+
+ comment-lint:branch:
+ desc: "Check comment quality on everything this branch adds over its base"
+ summary: |
+ Like `task comment-lint`, but scoped to the whole branch rather than to
+ uncommitted work, so it still reports after you commit.
+
+ Exists as its own task because passing `-- --since origin/main` through Task
+ is not portable: with the npm build of Task the launcher is a PowerShell
+ script, and PowerShell strips the `--` before Task sees it, leaving Task to
+ print its own usage.
+
+ Override the base with BASE=.
+ vars:
+ BASE: '{{.BASE | default "origin/main"}}'
+ deps: [":frontend:install"]
+ cmds:
+ - node scripts/lint/comment-lint.mjs --since {{.BASE}}
+
+ comment-lint:ci:
+ desc: "Comment gate as CI runs it: fixture corpus, then the diff"
+ summary: |
+ The corpus checks the rules themselves rather than the code under review, so
+ it belongs on CI and not on every local commit. Run this before changing a
+ rule, and let CI run it on every pull request.
+ deps: [":frontend:install"]
+ cmds:
+ - node scripts/lint/comment-lint.mjs --selftest
+ - node scripts/lint/comment-lint.mjs {{.CLI_ARGS}}
+
+ comment-lint:hook:
+ desc: "Comment gate for the editor hook: everything this turn changed"
+ summary: |
+ Same scope as `task comment-lint`, kept as its own name so the hook has a
+ stable entry point and the taskfile shows every way the linter is invoked.
+
+ Not in the frontend-install dependency chain on purpose: this runs at the end
+ of every turn, so it stays as short as it can be. If oxlint is missing the TS
+ half warns and skips.
+ cmds:
+ - node scripts/lint/comment-lint.mjs
+
+ comment-lint:all:
+ desc: "Report every comment finding in the tree (never fails)"
+ deps: [":frontend:install"]
+ cmds:
+ - node scripts/lint/comment-lint.mjs --all
+
+ comment-lint:selftest:
+ desc: "Check both comment-lint engines against the fixture corpus"
+ deps: [":frontend:install"]
+ cmds:
+ - node scripts/lint/comment-lint.mjs --selftest
+
gitleaks-bin:
internal: true
desc: "Ensure the pinned, checksum-verified gitleaks binary is cached in .task/bin"
diff --git a/AGENTS.md b/AGENTS.md
index 7383ab3c3d..88543ca3c8 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -21,6 +21,43 @@ Task `desc:` fields should describe **what** the task does, not **how** it does
- `task docker:build` — build standard Docker image
- `task docker:up` — start Docker compose stack
+## Comments
+
+A comment must carry information the code cannot. If a reader could derive it from the code in front of them, delete it.
+
+Comment the current state. Not what the code used to do, not what changed, not why it changed: git holds that. Where history explains the shape, state the reason instead, so "this used to reimplement the modal internals" becomes "thin wrapper over the shared Modal: duplicating its portal and focus trap is how dialogs drift apart". Future state goes in a TODO with an issue.
+
+Write a comment when it does one of these four jobs:
+
+- **Contract.** What a caller must know that the signature cannot say: preconditions, invariants, units, ownership and lifetime, thread-safety, error semantics, side effects. Document the contract of everything a caller outside the file can reach, and nothing else. Goes on the type/method/module as Javadoc, JSDoc, or a docstring.
+- **Why.** The constraint the code satisfies, the bug it avoids, the alternative rejected and the reason.
+- **Hazard.** "Must stay in sync with X", "order matters because Y", "do not remove, it prevents Z".
+- **Map.** A short orientation at the top of a genuinely complex file: what it owns, and what it deliberately does not.
+
+Never write:
+
+- A comment that restates the next line. `// Handle drag start` above `handleDragStart` is noise.
+- Section banners or position markers: `// --- Types ---`, `// Helpers`, `// =====`.
+- Step narration in a function body (`// Step 1:`, `// Then we`). If the steps need labels they need names: extract functions. Numbering a genuinely numbered thing, like a wizard step, is fine.
+- Commented-out code. Delete it.
+- Doc tags that restate the signature. `@param blob - The blob` says nothing; omit the tag rather than pad it.
+- Docs on self-explanatory members with no constraint to state.
+
+Two tests before keeping a comment:
+
+- **Delete it.** Is any information lost? If not, it stays deleted.
+- **Could a name carry it instead?** A better identifier, an extracted function, or a named constant beats a comment. Prefer the code change.
+
+A comment at the end of a line usually decodes that line, and that is worth keeping: `{0x25, 0x50} // "%PDF"`, `50L * 1024 * 1024 // 50 MB`. The rules that compare a comment against the code below it do not apply there, but a trailing TODO or a trailing bit of history is judged like any other.
+
+A reference is supplementary, never load-bearing: the comment must survive deleting it. `// See #1234` is a dead end; `// saving first loses every annotation (#6865)` is not. Prefer a spec (`RFC 3161`) or CVE where one applies.
+
+A TODO needs an issue, not an owner: `// TODO(#1234): re-enable the gate once account syncing lands`. If it is not worth an issue, it is not worth a TODO. A question is not a TODO.
+
+A comment block over ~12 lines outside a file or type header usually means the code needs restructuring, or that the prose is product documentation and belongs in the docs repo.
+
+`task comment-lint` checks the mechanical part of this on the lines you add, and runs inside `task pre-commit`. Reasoning, worked examples and the linter's own rules: @devGuide/CODE_COMMENTS.md
+
## Common Development Commands
### Build and Test
@@ -70,7 +107,7 @@ The project structure is defined in `engine/pyproject.toml`. Any new dependencie
- Avoid nested functions and nested classes unless the language construct requires them.
- Prefer composition to inheritance when combining concepts.
- Avoid speculative abstractions. Add a layer only when it removes real duplication or clarifies lifecycle.
-- Add comments sparingly and only when they explain non-obvious intent.
+- Comments follow the repo-wide rules in the "Comments" section above.
#### Python Typing and Models
- Deserialize into Pydantic models as early as possible.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 65fc4bc262..371630193b 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -42,6 +42,7 @@ Please make sure your Pull Request adheres to the following guidelines:
- Keep commits atomic. One commit should contain one change. If you want to make multiple changes, submit multiple Pull Requests.
- Commits should be clear, concise, and easy to understand.
- References to the Issue number in the Pull Request and/or Commit message.
+- Every comment in the diff should say something the code does not. See [Code comments](devGuide/CODE_COMMENTS.md); `task comment-lint` checks the mechanical part.
## Translations
diff --git a/Taskfile.yml b/Taskfile.yml
index 92dcdcc742..eaec7dec92 100644
--- a/Taskfile.yml
+++ b/Taskfile.yml
@@ -121,6 +121,92 @@ tasks:
cmds:
- task: dev:_all
+ # No engine: linking never calls it.
+ linked:staging:
+ desc: "SaaS on the shared v3 project + a self-hosted instance linked to it"
+ cmds:
+ - task: linked:_all
+ vars: { SAAS_ENV: staging }
+
+ linked:dev:
+ desc: "SaaS on the current PR's preview branch + a self-hosted instance linked to it"
+ cmds:
+ - task: linked:_all
+ vars: { SAAS_ENV: dev }
+
+ linked:_all:
+ internal: true
+ vars:
+ SAAS_ENV: '{{.SAAS_ENV | default "staging"}}'
+ PORTS:
+ sh: '{{if eq OS "windows"}}{{.FIND_FREE_PORT_PS}} 8081 5174 8080 5173{{else}}{{.FIND_FREE_PORT_SH}} 8081 5174 8080 5173{{end}}'
+ SAAS_BACKEND_PORT: '{{index (splitList "\n" .PORTS) 0}}'
+ SAAS_FRONTEND_PORT: '{{index (splitList "\n" .PORTS) 1}}'
+ APP_BACKEND_PORT: '{{index (splitList "\n" .PORTS) 2}}'
+ APP_FRONTEND_PORT: '{{index (splitList "\n" .PORTS) 3}}'
+ deps:
+ # APP_BASE_URL is the SaaS *frontend*: the approval page is served by vite, not
+ # by the API. BASE_PATH moves this backend's configs/pipeline aside so it does not
+ # race the self-hosted one, which keeps ./configs and its existing database.
+ - task: 'backend:{{.SAAS_ENV}}:saas'
+ vars:
+ PORT: '{{.SAAS_BACKEND_PORT}}'
+ APP_BASE_URL: 'http://localhost:{{.SAAS_FRONTEND_PORT}}'
+ BASE_PATH: 'tmp/linked-saas'
+ - task: frontend:dev:saas
+ vars:
+ PORT: '{{.SAAS_FRONTEND_PORT}}'
+ BACKEND_URL: 'http://localhost:{{.SAAS_BACKEND_PORT}}'
+ SAAS_ENV: '{{.SAAS_ENV}}'
+ - task: backend:dev:linked
+ vars:
+ PORT: '{{.APP_BACKEND_PORT}}'
+ SAAS_BASE_URL: 'http://localhost:{{.SAAS_BACKEND_PORT}}'
+ - task: frontend:dev:proprietary
+ vars:
+ PORT: '{{.APP_FRONTEND_PORT}}'
+ BACKEND_URL: 'http://localhost:{{.APP_BACKEND_PORT}}'
+ OPEN: "true"
+ - task: linked:_ready
+ vars:
+ SAAS_BACKEND_PORT: '{{.SAAS_BACKEND_PORT}}'
+ SAAS_FRONTEND_PORT: '{{.SAAS_FRONTEND_PORT}}'
+ APP_BACKEND_PORT: '{{.APP_BACKEND_PORT}}'
+ APP_FRONTEND_PORT: '{{.APP_FRONTEND_PORT}}'
+
+ # Waits for all four to answer, then prints where they landed.
+ linked:_ready:
+ internal: true
+ cmds:
+ - cmd: |
+ n=0
+ ok=0
+ while [ "$n" -lt 150 ]; do
+ ok=1
+ for u in "http://localhost:{{.SAAS_BACKEND_PORT}}" \
+ "http://localhost:{{.SAAS_FRONTEND_PORT}}" \
+ "http://localhost:{{.APP_BACKEND_PORT}}" \
+ "http://localhost:{{.APP_FRONTEND_PORT}}"; do
+ # Not -o /dev/null: Windows curl.exe treats it as a real path and exits 23.
+ curl -s -m 2 "$u" >/dev/null 2>&1 || ok=0
+ done
+ if [ "$ok" = 1 ]; then break; fi
+ n=$((n + 1))
+ # `sleep` is a binary, not a builtin, and Windows has none.
+ {{if eq OS "windows"}}powershell -NoProfile -Command "Start-Sleep -Seconds 2"{{else}}sleep 2{{end}}
+ done
+ echo ""
+ if [ "$ok" = 1 ]; then
+ echo ">> all four answering"
+ else
+ echo ">> still waiting on one or more after 5 minutes; addresses below anyway"
+ fi
+ echo ">> self-hosted UI http://localhost:{{.APP_FRONTEND_PORT}}/processor"
+ echo ">> self-hosted api http://localhost:{{.APP_BACKEND_PORT}}"
+ echo ">> saas UI http://localhost:{{.SAAS_FRONTEND_PORT}}"
+ echo ">> saas api http://localhost:{{.SAAS_BACKEND_PORT}}"
+ echo ""
+
dev:_all:
internal: true
vars:
@@ -180,6 +266,20 @@ tasks:
cmds:
- task: frontend:lint
- task: engine:lint
+ - task: comment-lint
+
+ comment-lint:
+ desc: "Check comment quality on the lines this branch adds"
+ aliases: [comments]
+ cmds:
+ - task: pre-commit:comment-lint
+ vars: { CLI_ARGS: '{{.CLI_ARGS}}' }
+
+ comment-lint:branch:
+ desc: "Check comment quality on everything this branch adds over its base"
+ cmds:
+ - task: pre-commit:comment-lint:branch
+ vars: { BASE: '{{.BASE}}' }
fix:
desc: "Auto-fix all components"
diff --git a/app/common/build.gradle b/app/common/build.gradle
index 8af68bcb76..8ac1dfe0a9 100644
--- a/app/common/build.gradle
+++ b/app/common/build.gradle
@@ -3,6 +3,10 @@ bootRun {
enabled = false
}
dependencies {
+ // Security-hardening utilities (zip-slip, SSRF, filename sanitization, command injection).
+ // Declared as api here so core + proprietary (which depend on common) get it transitively,
+ // keeping it off modules that don't need it (e.g. saas).
+ api 'io.github.pixee:java-security-toolkit:1.2.3'
api "com.google.guava:guava:${guavaVersion}"
api 'org.springframework.boot:spring-boot-starter-webmvc'
api 'org.springframework.boot:spring-boot-starter-aspectj'
@@ -22,7 +26,10 @@ dependencies {
api "org.springdoc:springdoc-openapi-starter-webmvc-ui:3.0.3"
// Simple Java Mail for EML/MSG parsing (replaces direct Angus Mail usage)
api 'org.simplejavamail:simple-java-mail:9.3.2'
- api 'org.simplejavamail:outlook-module:9.3.2' // MSG file support
+ // MSG file support; exclude commons-math3 (only HSSF/formula needs it, MSG parsing doesn't)
+ api('org.simplejavamail:outlook-module:9.3.2') {
+ exclude group: 'org.apache.commons', module: 'commons-math3'
+ }
api 'jakarta.mail:jakarta.mail-api:2.1.5'
runtimeOnly 'org.eclipse.angus:angus-mail:2.0.5'
@@ -36,12 +43,30 @@ dependencies {
api "com.stirling:jpdfium:${jpdfiumVersion}"
- // -PjpdfiumPlatforms=all|none|
- // 'none' skips natives entirely (windows-arm64 builds, until JPDFium ships that platform).
- def jpdfiumPlatformsProp = (project.findProperty('jpdfiumPlatforms') ?: 'all').toString().trim()
- def jpdfiumAllPlatforms = ['linux-x64', 'linux-arm64', 'darwin-x64', 'darwin-arm64', 'windows-x64']
+ // -PjpdfiumPlatforms=auto|all|none| (windows-arm64 natives not published yet)
+ def jpdfiumPlatformsProp = (project.findProperty('jpdfiumPlatforms') ?: 'auto').toString().trim()
+ def jpdfiumAllPlatforms = ['linux-x64', 'linux-arm64', 'linux-musl-x64', 'linux-musl-arm64', 'darwin-x64', 'darwin-arm64', 'windows-x64']
def jpdfiumPlatforms
- if (jpdfiumPlatformsProp == 'all') {
+ if (jpdfiumPlatformsProp == 'auto') {
+ def osName = System.getProperty('os.name').toLowerCase()
+ def osArch = System.getProperty('os.arch').toLowerCase()
+ def isArm64 = osArch.contains('aarch64') || osArch.contains('arm64')
+ if (osName.contains('linux')) {
+ jpdfiumPlatforms = isArm64 ? ['linux-arm64'] : ['linux-x64']
+ } else if (osName.contains('mac')) {
+ jpdfiumPlatforms = isArm64 ? ['darwin-arm64'] : ['darwin-x64']
+ } else if (osName.contains('win')) {
+ if (isArm64) {
+ logger.lifecycle("JPDFium natives are not available for windows-arm64; set -PjpdfiumPlatforms=none to skip bundling natives.")
+ jpdfiumPlatforms = []
+ } else {
+ jpdfiumPlatforms = ['windows-x64']
+ }
+ } else {
+ // Fallback: bundle all platforms when host can't be determined
+ jpdfiumPlatforms = jpdfiumAllPlatforms
+ }
+ } else if (jpdfiumPlatformsProp == 'all') {
jpdfiumPlatforms = jpdfiumAllPlatforms
} else if (jpdfiumPlatformsProp == 'none') {
jpdfiumPlatforms = []
@@ -51,7 +76,7 @@ dependencies {
def jpdfiumInvalid = jpdfiumPlatforms.findAll { !jpdfiumAllPlatforms.contains(it) }
if (jpdfiumInvalid) {
throw new GradleException("Unknown jpdfiumPlatforms value(s): ${jpdfiumInvalid.join(', ')}. " +
- "Valid: ${jpdfiumAllPlatforms.join(', ')}, 'all' or 'none'.")
+ "Valid: ${jpdfiumAllPlatforms.join(', ')}, 'auto', 'all' or 'none'.")
}
logger.lifecycle("JPDFium native platforms: ${jpdfiumPlatforms ? jpdfiumPlatforms.join(', ') : 'none'}")
jpdfiumPlatforms.each { platform ->
diff --git a/app/common/src/main/java/stirling/software/SPDF/config/EndpointConfiguration.java b/app/common/src/main/java/stirling/software/SPDF/config/EndpointConfiguration.java
index 5e8f7fe336..291bf1dce6 100644
--- a/app/common/src/main/java/stirling/software/SPDF/config/EndpointConfiguration.java
+++ b/app/common/src/main/java/stirling/software/SPDF/config/EndpointConfiguration.java
@@ -48,7 +48,7 @@ public class EndpointConfiguration {
private final ApplicationProperties applicationProperties;
@Getter private Map endpointStatuses = new ConcurrentHashMap<>();
private Map> endpointGroups = new ConcurrentHashMap<>();
- private Set disabledGroups = new HashSet<>();
+ private Set disabledGroups = ConcurrentHashMap.newKeySet();
private Map endpointDisableReasons = new ConcurrentHashMap<>();
private Map groupDisableReasons = new ConcurrentHashMap<>();
private Map> endpointAlternatives = new ConcurrentHashMap<>();
diff --git a/app/common/src/main/java/stirling/software/SPDF/pdf/parser/TabulaTableParser.java b/app/common/src/main/java/stirling/software/SPDF/pdf/parser/TabulaTableParser.java
index b85ddbb08e..d3c516d1fe 100644
--- a/app/common/src/main/java/stirling/software/SPDF/pdf/parser/TabulaTableParser.java
+++ b/app/common/src/main/java/stirling/software/SPDF/pdf/parser/TabulaTableParser.java
@@ -237,7 +237,7 @@ public class TabulaTableParser implements TableParser {
score -= 0.3f;
}
- return Math.max(0f, Math.min(1f, score));
+ return Math.clamp(score, 0f, 1f);
}
private Bounds tableBounds(Table table) {
diff --git a/app/common/src/main/java/stirling/software/common/util/propertyeditor/StringToMapPropertyEditor.java b/app/common/src/main/java/stirling/software/common/util/propertyeditor/StringToMapPropertyEditor.java
index 63476d5568..7ab1013a8a 100644
--- a/app/common/src/main/java/stirling/software/common/util/propertyeditor/StringToMapPropertyEditor.java
+++ b/app/common/src/main/java/stirling/software/common/util/propertyeditor/StringToMapPropertyEditor.java
@@ -15,7 +15,8 @@ public class StringToMapPropertyEditor extends PropertyEditorSupport {
@Override
public void setAsText(String text) throws IllegalArgumentException {
try {
- TypeReference> typeRef = new TypeReference<>() {};
+ TypeReference> typeRef =
+ new TypeReference>() {};
Map map = objectMapper.readValue(text, typeRef);
setValue(map);
} catch (Exception e) {
diff --git a/app/common/src/test/java/stirling/software/common/util/RequestUriUtilsTest.java b/app/common/src/test/java/stirling/software/common/util/RequestUriUtilsTest.java
index 72e5eae9a2..c144f9726e 100644
--- a/app/common/src/test/java/stirling/software/common/util/RequestUriUtilsTest.java
+++ b/app/common/src/test/java/stirling/software/common/util/RequestUriUtilsTest.java
@@ -113,6 +113,16 @@ class RequestUriUtilsTest {
assertTrue(RequestUriUtils.isFrontendRoute("", "/split-pdf"));
}
+ @Test
+ void testIsFrontendRoute_editorRouteOwnedByFrontend() {
+ // /editor (and its tool routes) is an SPA route: a direct-nav/refresh must
+ // serve index.html, not the auth filter's 302-to-/login. Regression test for
+ // the editor moving from / to /editor, whose refresh bounced processor users
+ // to the processor because the redirect dropped the return path.
+ assertTrue(RequestUriUtils.isFrontendRoute("", "/editor"));
+ assertTrue(RequestUriUtils.isFrontendRoute("/app", "/app/editor"));
+ }
+
@Test
void testIsFrontendRoute_filesRouteOwnedByFrontend() {
// /files and /files/ are FileManagerView routes - they
diff --git a/app/core/.gitignore b/app/core/.gitignore
index 7d9dd62931..c207c6c09a 100644
--- a/app/core/.gitignore
+++ b/app/core/.gitignore
@@ -106,6 +106,7 @@ SwaggerDoc.json
# Log file
*.log
+*.log.gz
# BlueJ files
*.ctxt
diff --git a/app/core/build.gradle b/app/core/build.gradle
index 76828445a3..0e1533b6e8 100644
--- a/app/core/build.gradle
+++ b/app/core/build.gradle
@@ -62,8 +62,16 @@ dependencies {
// 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.5'
- implementation 'com.opencsv:opencsv:5.12.0' // https://mvnrepository.com/artifact/com.opencsv/opencsv
- implementation 'org.apache.poi:poi-ooxml:5.5.1'
+ // OpenCSV: Stirling-PDF only uses CSVWriter, not the opencsv-bean module.
+ // Exclude commons-beanutils + commons-collections.
+ implementation('com.opencsv:opencsv:5.12.0') {
+ exclude group: 'commons-beanutils', module: 'commons-beanutils'
+ exclude group: 'commons-collections', module: 'commons-collections'
+ }
+ // POI: only XSSF (modern Excel) is used, not HSSF/FormulaEvaluator which need commons-math3.
+ implementation('org.apache.poi:poi-ooxml:5.5.1') {
+ exclude group: 'org.apache.commons', module: 'commons-math3'
+ }
// 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
@@ -129,6 +137,10 @@ bootJar {
exclude 'META-INF/*.RSA'
exclude 'META-INF/*.EC'
+ // Exclude source maps from production JAR, dev-only debugging artifacts, not needed at runtime
+ exclude 'static/pdfjs-legacy/**/*.map'
+ exclude 'static/**/*.map'
+
manifest {
attributes(
'Implementation-Title': 'Stirling-PDF',
diff --git a/app/core/src/main/java/stirling/software/SPDF/controller/api/EditTextController.java b/app/core/src/main/java/stirling/software/SPDF/controller/api/EditTextController.java
index 17d1d7d8a7..b76f52144a 100644
--- a/app/core/src/main/java/stirling/software/SPDF/controller/api/EditTextController.java
+++ b/app/core/src/main/java/stirling/software/SPDF/controller/api/EditTextController.java
@@ -237,7 +237,7 @@ public class EditTextController {
Matcher matcher = edit.pattern().matcher(joined);
List spans = new ArrayList<>();
- StringBuffer interpolation = new StringBuffer();
+ StringBuilder interpolation = new StringBuilder();
int previousAppendPosition = 0;
while (matcher.find()) {
if (matcher.start() == matcher.end()) {
diff --git a/app/core/src/main/java/stirling/software/SPDF/controller/api/UIDataController.java b/app/core/src/main/java/stirling/software/SPDF/controller/api/UIDataController.java
index 7f93fb3d64..b6cef0b2d6 100644
--- a/app/core/src/main/java/stirling/software/SPDF/controller/api/UIDataController.java
+++ b/app/core/src/main/java/stirling/software/SPDF/controller/api/UIDataController.java
@@ -95,7 +95,8 @@ public class UIDataController {
try (InputStream is = resource.getInputStream()) {
Map> licenseData =
- objectMapper.readValue(is, new TypeReference<>() {});
+ objectMapper.readValue(
+ is, new TypeReference>>() {});
data.setDependencies(licenseData.get("dependencies"));
} catch (IOException e) {
log.error("Failed to load licenses data", e);
diff --git a/app/core/src/main/java/stirling/software/SPDF/controller/api/form/FormPayloadParser.java b/app/core/src/main/java/stirling/software/SPDF/controller/api/form/FormPayloadParser.java
index f48f419a6d..5236706f74 100644
--- a/app/core/src/main/java/stirling/software/SPDF/controller/api/form/FormPayloadParser.java
+++ b/app/core/src/main/java/stirling/software/SPDF/controller/api/form/FormPayloadParser.java
@@ -25,12 +25,15 @@ final class FormPayloadParser {
private static final String KEY_VALUE = "value";
private static final String KEY_DEFAULT_VALUE = "defaultValue";
- private static final TypeReference> MAP_TYPE = new TypeReference<>() {};
+ private static final TypeReference> MAP_TYPE =
+ new TypeReference>() {};
private static final TypeReference>
- MODIFY_FIELD_LIST_TYPE = new TypeReference<>() {};
+ MODIFY_FIELD_LIST_TYPE =
+ new TypeReference>() {};
private static final TypeReference> NEW_FIELD_LIST_TYPE =
new TypeReference<>() {};
- private static final TypeReference> STRING_LIST_TYPE = new TypeReference<>() {};
+ private static final TypeReference> STRING_LIST_TYPE =
+ new TypeReference>() {};
private FormPayloadParser() {}
diff --git a/app/core/src/main/java/stirling/software/SPDF/controller/api/misc/AddCommentsController.java b/app/core/src/main/java/stirling/software/SPDF/controller/api/misc/AddCommentsController.java
index dc2dd22863..09b1d282e9 100644
--- a/app/core/src/main/java/stirling/software/SPDF/controller/api/misc/AddCommentsController.java
+++ b/app/core/src/main/java/stirling/software/SPDF/controller/api/misc/AddCommentsController.java
@@ -96,7 +96,9 @@ public class AddCommentsController {
List dtos;
try {
- dtos = objectMapper.readValue(commentsJson, new TypeReference<>() {});
+ dtos =
+ objectMapper.readValue(
+ commentsJson, new TypeReference>() {});
} catch (JacksonException e) {
throw new ResponseStatusException(
HttpStatus.BAD_REQUEST, "comments must be a JSON array of CommentSpec objects");
diff --git a/app/core/src/main/java/stirling/software/SPDF/controller/api/misc/OCRController.java b/app/core/src/main/java/stirling/software/SPDF/controller/api/misc/OCRController.java
index 4803184a33..e10b86a866 100644
--- a/app/core/src/main/java/stirling/software/SPDF/controller/api/misc/OCRController.java
+++ b/app/core/src/main/java/stirling/software/SPDF/controller/api/misc/OCRController.java
@@ -114,6 +114,7 @@ public class OCRController {
List selectedLanguages = request.getLanguages();
boolean sidecar = request.isSidecar();
Boolean deskew = request.isDeskew();
+ Boolean rotatePages = request.isRotatePages();
Boolean clean = request.isClean();
Boolean cleanFinal = request.isCleanFinal();
String ocrType = request.getOcrType();
@@ -154,6 +155,7 @@ public class OCRController {
selectedLanguages,
sidecar,
deskew,
+ rotatePages,
clean,
cleanFinal,
ocrType,
@@ -236,6 +238,7 @@ public class OCRController {
List selectedLanguages,
Boolean sidecar,
Boolean deskew,
+ Boolean rotatePages,
Boolean clean,
Boolean cleanFinal,
String ocrType,
@@ -268,6 +271,10 @@ public class OCRController {
if (deskew != null && deskew) {
command.add("--deskew");
}
+ if (rotatePages != null && rotatePages) {
+ // Tesseract OSD-based automatic page orientation correction (90/180/270)
+ command.add("--rotate-pages");
+ }
if (clean != null && clean) {
command.add("--clean");
}
diff --git a/app/core/src/main/java/stirling/software/SPDF/controller/api/security/RedactController.java b/app/core/src/main/java/stirling/software/SPDF/controller/api/security/RedactController.java
index 7a186235cd..1c694da2b0 100644
--- a/app/core/src/main/java/stirling/software/SPDF/controller/api/security/RedactController.java
+++ b/app/core/src/main/java/stirling/software/SPDF/controller/api/security/RedactController.java
@@ -221,6 +221,10 @@ public class RedactController {
.normalizeFonts(false)
.fixToUnicode(false)
.glyphAware(true)
+ .ligatureAware(true)
+ .bidiAware(true)
+ .graphemeSafe(true)
+ .sanitizeStructure(false) // WIP/Experimental API
.redactMetadata(true)
.build();
diff --git a/app/core/src/main/java/stirling/software/SPDF/controller/api/security/TextRedactionService.java b/app/core/src/main/java/stirling/software/SPDF/controller/api/security/TextRedactionService.java
index 9cf4e6c700..c0b74f5428 100644
--- a/app/core/src/main/java/stirling/software/SPDF/controller/api/security/TextRedactionService.java
+++ b/app/core/src/main/java/stirling/software/SPDF/controller/api/security/TextRedactionService.java
@@ -110,6 +110,10 @@ class TextRedactionService {
.fixToUnicode(false)
.repairWidths(false)
.glyphAware(true)
+ .ligatureAware(true)
+ .bidiAware(true)
+ .graphemeSafe(true)
+ .sanitizeStructure(false)
.build();
try (PdfDocument checkDoc = PdfDocument.open(tempIn.toPath())) {
diff --git a/app/core/src/main/java/stirling/software/SPDF/model/api/misc/ProcessPdfWithOcrRequest.java b/app/core/src/main/java/stirling/software/SPDF/model/api/misc/ProcessPdfWithOcrRequest.java
index 2955d7160f..daa6930412 100644
--- a/app/core/src/main/java/stirling/software/SPDF/model/api/misc/ProcessPdfWithOcrRequest.java
+++ b/app/core/src/main/java/stirling/software/SPDF/model/api/misc/ProcessPdfWithOcrRequest.java
@@ -25,6 +25,11 @@ public class ProcessPdfWithOcrRequest extends PDFFile {
@Schema(description = "Deskew the input file if set to true")
private boolean deskew;
+ @Schema(
+ description =
+ "Auto-correct page orientation (90/180/270) using Tesseract OSD if set to true")
+ private boolean rotatePages;
+
@Schema(description = "Clean the input file if set to true")
private boolean clean;
diff --git a/app/core/src/main/java/stirling/software/SPDF/service/WeeklyActiveUsersService.java b/app/core/src/main/java/stirling/software/SPDF/service/WeeklyActiveUsersService.java
index 3b1ae1d048..23d8247218 100644
--- a/app/core/src/main/java/stirling/software/SPDF/service/WeeklyActiveUsersService.java
+++ b/app/core/src/main/java/stirling/software/SPDF/service/WeeklyActiveUsersService.java
@@ -4,7 +4,9 @@ import java.time.Instant;
import java.time.temporal.ChronoUnit;
import java.util.Map;
import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.atomic.AtomicLong;
+import org.springframework.scheduling.annotation.Scheduled;
import org.springframework.stereotype.Service;
import lombok.extern.slf4j.Slf4j;
@@ -21,7 +23,7 @@ public class WeeklyActiveUsersService {
private final Map activeBrowsers = new ConcurrentHashMap<>();
// Track total unique browsers seen (overall)
- private long totalUniqueBrowsers = 0;
+ private final AtomicLong totalUniqueBrowsers = new AtomicLong(0);
// Application start time
private final Instant startTime = Instant.now();
@@ -36,12 +38,12 @@ public class WeeklyActiveUsersService {
return;
}
- boolean isNewBrowser = !activeBrowsers.containsKey(browserId);
- activeBrowsers.put(browserId, Instant.now());
+ Instant now = Instant.now();
+ Instant previous = activeBrowsers.put(browserId, now);
- if (isNewBrowser) {
- totalUniqueBrowsers++;
- log.debug("New browser recorded: {} (Total: {})", browserId, totalUniqueBrowsers);
+ if (previous == null) {
+ long total = totalUniqueBrowsers.incrementAndGet();
+ log.debug("New browser recorded: {} (Total: {})", browserId, total);
}
}
@@ -61,7 +63,7 @@ public class WeeklyActiveUsersService {
* @return Total unique browsers count
*/
public long getTotalUniqueBrowsers() {
- return totalUniqueBrowsers;
+ return totalUniqueBrowsers.get();
}
/**
@@ -88,7 +90,8 @@ public class WeeklyActiveUsersService {
activeBrowsers.entrySet().removeIf(entry -> entry.getValue().isBefore(sevenDaysAgo));
}
- /** Manual cleanup trigger (can be called by scheduled task if needed) */
+ /** Scheduled cleanup trigger running every hour */
+ @Scheduled(fixedRate = 3600000)
public void performCleanup() {
int sizeBefore = activeBrowsers.size();
cleanupOldEntries();
diff --git a/app/core/src/main/resources/logback.xml b/app/core/src/main/resources/logback.xml
index c0779735ae..ebdeeda64b 100644
--- a/app/core/src/main/resources/logback.xml
+++ b/app/core/src/main/resources/logback.xml
@@ -16,8 +16,9 @@
%d %p %c{1} [%thread] %m%n
- ${LOG_PATH}/auth-%d{yyyy-MM-dd}.log
- 1
+ ${LOG_PATH}/auth-%d{yyyy-MM-dd}.log.gz
+ 7
+ 64MB
@@ -28,8 +29,9 @@
%d %p %c{1} [%thread] %m%n
- ${LOG_PATH}/info-%d{yyyy-MM-dd}.log
- 1
+ ${LOG_PATH}/info-%d{yyyy-MM-dd}.log.gz
+ 7
+ 256MB
diff --git a/app/core/src/main/resources/settings.yml.template b/app/core/src/main/resources/settings.yml.template
index fdfe40b352..ecf7ea8538 100644
--- a/app/core/src/main/resources/settings.yml.template
+++ b/app/core/src/main/resources/settings.yml.template
@@ -186,7 +186,7 @@ system:
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']). 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.
+ frontendUrl: "" # Base URL of the web app, as a browser reaches it (e.g. 'https://app.example.com', or 'https://example.com/app' if served under a base path). Optional - if not set, will use backendUrl. Used for any link handed to a browser: invite emails, share links, mobile QR codes, and the account-link handshake.
enableMobileScanner: true # Enable mobile phone QR code upload feature. Requires frontendUrl to be configured.
enableMobileSignature: true # Enable drawing signatures on a phone via QR code from the Sign tool. Requires frontendUrl to be configured.
mobileScannerSettings:
diff --git a/app/core/src/test/resources/certs/test-cert.cer b/app/core/src/test/resources/certs/test-cert.cer
index 729f85c73d..2663010d09 100644
--- a/app/core/src/test/resources/certs/test-cert.cer
+++ b/app/core/src/test/resources/certs/test-cert.cer
@@ -1,26 +1,21 @@
-Bag Attributes
- friendlyName: alias
- localKeyID: 43 4A B0 2D D5 03 52 9F 5B 78 50 64 54 22 AB F7 C8 0B 1F 2B
-subject=C = US, ST = CA, L = SF, O = Test, OU = Test, CN = Test
-issuer=C = US, ST = CA, L = SF, O = Test, OU = Test, CN = Test
-----BEGIN CERTIFICATE-----
-MIIDiTCCAnGgAwIBAgIUdWDUiSWDll+owMQEzypIuChp+bcwDQYJKoZIhvcNAQEL
+MIIDizCCAnOgAwIBAgIUZMcjBbPlADpy5PssUsPlPM/h7dcwDQYJKoZIhvcNAQEL
BQAwVDELMAkGA1UEBhMCVVMxCzAJBgNVBAgMAkNBMQswCQYDVQQHDAJTRjENMAsG
-A1UECgwEVGVzdDENMAsGA1UECwwEVGVzdDENMAsGA1UEAwwEVGVzdDAeFw0yNTA4
-MjYwNzQxMTBaFw0yNjA4MjYwNzQxMTBaMFQxCzAJBgNVBAYTAlVTMQswCQYDVQQI
-DAJDQTELMAkGA1UEBwwCU0YxDTALBgNVBAoMBFRlc3QxDTALBgNVBAsMBFRlc3Qx
-DTALBgNVBAMMBFRlc3QwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDM
-SfspXLx1WAKSo3AfDYIJAyeSrqFcTsPoNBEvT2U1b8w+SCTw4xR5sC3pNenbiEQ7
-4sI60hgURtOMOAt+iKvfI0A/9N8/wYadXUyis4qGZPkM/F6H5cBF9VaYisGptY2w
-ad9X8XcZgZFABYA5O50Jb5nbUM8fPwDYz2fISIejIpW36y+ApFsotJQCaISe4UWb
-K7bwW4UycghYh7AqfH/1OvgR35gGeL7S+SC0F+CZqGECgansFOh/yYL6VoatoggV
-oZxjIQblmuSrLtfwN1S7ngn85k3NFMBHm1ehMOHabx5G58Wg05/0mBK8bIrwjrNp
-Wzomit8BQJ7eIYUikZfVAgMBAAGjUzBRMB0GA1UdDgQWBBRm6hGFGnC1dxipumf/
-6ROdNE6/YDAfBgNVHSMEGDAWgBRm6hGFGnC1dxipumf/6ROdNE6/YDAPBgNVHRMB
-Af8EBTADAQH/MA0GCSqGSIb3DQEBCwUAA4IBAQB66MPy5kZlSlBgsK4HtB1LSr3M
-dmBWbnQQMq9rmD9AIBQV/shiIjMXGRGnt9zaB0Gg9M39iEvISE6ByMpaDQqV0Md5
-9y4XJu0rg/aMXLaHOGDAWJsb7nCGDt12cWdgn1Ni2mmXUHv4SJCRXNQF7mSgIr+p
-Fvd1ljyvzu/iig8qxrcuWoZvY677p3yen4dN8ocgi8Df3KjduGbsTjFAESYqqNQC
-f+bvypQfhHjxdvz5W3Lpk2swUufqOvhO2b6+cshYJX98qLU8mhai/rOnYkHE7haq
-WDH6XEthnVGtk2VJ4XFDbz+FID440DPzy5u/1OZw2Mcoyp6y7rZDKC/D0Uvh
+A1UECgwEVGVzdDENMAsGA1UECwwEVGVzdDENMAsGA1UEAwwEVGVzdDAgFw0yNTAx
+MDEwMDAwMDBaGA8yMTI1MDEwMTAwMDAwMFowVDELMAkGA1UEBhMCVVMxCzAJBgNV
+BAgMAkNBMQswCQYDVQQHDAJTRjENMAsGA1UECgwEVGVzdDENMAsGA1UECwwEVGVz
+dDENMAsGA1UEAwwEVGVzdDCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEB
+AMmEw2bpAoPnrUWkydKGmvDl0bHaCMoSY9yK2b/JL1xaTRwGT4H7DOuO/0Uu6/BV
+c93UEO0eHf1mt1kkYaRSPyOQLXF2QzRDkiW78c/xvqX+DgmfB7BFNrFSP+CRabdH
+wvepLUFtXJ6WwvWXjyvDXn8wEAirfETMdU8OXlPaJwS6cbQawYuB6GG5Z1ulxw6k
+GRi5hnq7PFJBxz1pg6Xx6pwKnaaNemW4Gp2B90St9N5yu7yV6V6XON84ZdohfXSQ
+livH3UTdkrpe+MO2m3CaAA19zlIxM6OIhkuo8r5GEPxoXCykPbgGMRFWPt0GNC3/
+AxZofAJg8atqy4peR8XL060CAwEAAaNTMFEwHQYDVR0OBBYEFDULr71QH24KKgNi
+2fyM6W9qJnzsMA8GA1UdEwEB/wQFMAMBAf8wHwYDVR0jBBgwFoAUNQuvvVAfbgoq
+A2LZ/Izpb2omfOwwDQYJKoZIhvcNAQELBQADggEBAASZENsvvyxygLjE913BBLd2
+73unxWNSDXakT4xssDEysf//4nGPGo57KjUGFU6M64IVUmhPRTT3aYq7PyA9pb5Q
+Ijritg5PdxfUMqd+H3CT++JvJmXxmIrFtKD9fZbmBgRg2wU7yvcp7MP+w36CYmqe
+MH1YF29VcBcF+GfI8k00y83qYHuoHpzPrNcL/Gu6MtcC+1Hy96bs+NYIEFH67dy8
+IJrN3Vvr4VXSF9qA+Vp5RatPv+hEKZssEFK2fNpGMFPGc1r+HBQ/HEAL4M2betEo
+Ne4DigJ3CkTIYAd+cZ2m4tdtzbqkeXZJ7SL+/d/5MIXKTnYITw+NrpiMZ6I72Zk=
-----END CERTIFICATE-----
diff --git a/app/core/src/test/resources/certs/test-cert.crt b/app/core/src/test/resources/certs/test-cert.crt
index 729f85c73d..2663010d09 100644
--- a/app/core/src/test/resources/certs/test-cert.crt
+++ b/app/core/src/test/resources/certs/test-cert.crt
@@ -1,26 +1,21 @@
-Bag Attributes
- friendlyName: alias
- localKeyID: 43 4A B0 2D D5 03 52 9F 5B 78 50 64 54 22 AB F7 C8 0B 1F 2B
-subject=C = US, ST = CA, L = SF, O = Test, OU = Test, CN = Test
-issuer=C = US, ST = CA, L = SF, O = Test, OU = Test, CN = Test
-----BEGIN CERTIFICATE-----
-MIIDiTCCAnGgAwIBAgIUdWDUiSWDll+owMQEzypIuChp+bcwDQYJKoZIhvcNAQEL
+MIIDizCCAnOgAwIBAgIUZMcjBbPlADpy5PssUsPlPM/h7dcwDQYJKoZIhvcNAQEL
BQAwVDELMAkGA1UEBhMCVVMxCzAJBgNVBAgMAkNBMQswCQYDVQQHDAJTRjENMAsG
-A1UECgwEVGVzdDENMAsGA1UECwwEVGVzdDENMAsGA1UEAwwEVGVzdDAeFw0yNTA4
-MjYwNzQxMTBaFw0yNjA4MjYwNzQxMTBaMFQxCzAJBgNVBAYTAlVTMQswCQYDVQQI
-DAJDQTELMAkGA1UEBwwCU0YxDTALBgNVBAoMBFRlc3QxDTALBgNVBAsMBFRlc3Qx
-DTALBgNVBAMMBFRlc3QwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDM
-SfspXLx1WAKSo3AfDYIJAyeSrqFcTsPoNBEvT2U1b8w+SCTw4xR5sC3pNenbiEQ7
-4sI60hgURtOMOAt+iKvfI0A/9N8/wYadXUyis4qGZPkM/F6H5cBF9VaYisGptY2w
-ad9X8XcZgZFABYA5O50Jb5nbUM8fPwDYz2fISIejIpW36y+ApFsotJQCaISe4UWb
-K7bwW4UycghYh7AqfH/1OvgR35gGeL7S+SC0F+CZqGECgansFOh/yYL6VoatoggV
-oZxjIQblmuSrLtfwN1S7ngn85k3NFMBHm1ehMOHabx5G58Wg05/0mBK8bIrwjrNp
-Wzomit8BQJ7eIYUikZfVAgMBAAGjUzBRMB0GA1UdDgQWBBRm6hGFGnC1dxipumf/
-6ROdNE6/YDAfBgNVHSMEGDAWgBRm6hGFGnC1dxipumf/6ROdNE6/YDAPBgNVHRMB
-Af8EBTADAQH/MA0GCSqGSIb3DQEBCwUAA4IBAQB66MPy5kZlSlBgsK4HtB1LSr3M
-dmBWbnQQMq9rmD9AIBQV/shiIjMXGRGnt9zaB0Gg9M39iEvISE6ByMpaDQqV0Md5
-9y4XJu0rg/aMXLaHOGDAWJsb7nCGDt12cWdgn1Ni2mmXUHv4SJCRXNQF7mSgIr+p
-Fvd1ljyvzu/iig8qxrcuWoZvY677p3yen4dN8ocgi8Df3KjduGbsTjFAESYqqNQC
-f+bvypQfhHjxdvz5W3Lpk2swUufqOvhO2b6+cshYJX98qLU8mhai/rOnYkHE7haq
-WDH6XEthnVGtk2VJ4XFDbz+FID440DPzy5u/1OZw2Mcoyp6y7rZDKC/D0Uvh
+A1UECgwEVGVzdDENMAsGA1UECwwEVGVzdDENMAsGA1UEAwwEVGVzdDAgFw0yNTAx
+MDEwMDAwMDBaGA8yMTI1MDEwMTAwMDAwMFowVDELMAkGA1UEBhMCVVMxCzAJBgNV
+BAgMAkNBMQswCQYDVQQHDAJTRjENMAsGA1UECgwEVGVzdDENMAsGA1UECwwEVGVz
+dDENMAsGA1UEAwwEVGVzdDCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEB
+AMmEw2bpAoPnrUWkydKGmvDl0bHaCMoSY9yK2b/JL1xaTRwGT4H7DOuO/0Uu6/BV
+c93UEO0eHf1mt1kkYaRSPyOQLXF2QzRDkiW78c/xvqX+DgmfB7BFNrFSP+CRabdH
+wvepLUFtXJ6WwvWXjyvDXn8wEAirfETMdU8OXlPaJwS6cbQawYuB6GG5Z1ulxw6k
+GRi5hnq7PFJBxz1pg6Xx6pwKnaaNemW4Gp2B90St9N5yu7yV6V6XON84ZdohfXSQ
+livH3UTdkrpe+MO2m3CaAA19zlIxM6OIhkuo8r5GEPxoXCykPbgGMRFWPt0GNC3/
+AxZofAJg8atqy4peR8XL060CAwEAAaNTMFEwHQYDVR0OBBYEFDULr71QH24KKgNi
+2fyM6W9qJnzsMA8GA1UdEwEB/wQFMAMBAf8wHwYDVR0jBBgwFoAUNQuvvVAfbgoq
+A2LZ/Izpb2omfOwwDQYJKoZIhvcNAQELBQADggEBAASZENsvvyxygLjE913BBLd2
+73unxWNSDXakT4xssDEysf//4nGPGo57KjUGFU6M64IVUmhPRTT3aYq7PyA9pb5Q
+Ijritg5PdxfUMqd+H3CT++JvJmXxmIrFtKD9fZbmBgRg2wU7yvcp7MP+w36CYmqe
+MH1YF29VcBcF+GfI8k00y83qYHuoHpzPrNcL/Gu6MtcC+1Hy96bs+NYIEFH67dy8
+IJrN3Vvr4VXSF9qA+Vp5RatPv+hEKZssEFK2fNpGMFPGc1r+HBQ/HEAL4M2betEo
+Ne4DigJ3CkTIYAd+cZ2m4tdtzbqkeXZJ7SL+/d/5MIXKTnYITw+NrpiMZ6I72Zk=
-----END CERTIFICATE-----
diff --git a/app/core/src/test/resources/certs/test-cert.der b/app/core/src/test/resources/certs/test-cert.der
index b931702b5b..0697fc18a4 100644
Binary files a/app/core/src/test/resources/certs/test-cert.der and b/app/core/src/test/resources/certs/test-cert.der differ
diff --git a/app/core/src/test/resources/certs/test-cert.jks b/app/core/src/test/resources/certs/test-cert.jks
index 5b6396b644..77a12954af 100644
Binary files a/app/core/src/test/resources/certs/test-cert.jks and b/app/core/src/test/resources/certs/test-cert.jks differ
diff --git a/app/core/src/test/resources/certs/test-cert.p12 b/app/core/src/test/resources/certs/test-cert.p12
index 02f74b04fd..a11646d84b 100644
Binary files a/app/core/src/test/resources/certs/test-cert.p12 and b/app/core/src/test/resources/certs/test-cert.p12 differ
diff --git a/app/core/src/test/resources/certs/test-cert.pem b/app/core/src/test/resources/certs/test-cert.pem
index 729f85c73d..2663010d09 100644
--- a/app/core/src/test/resources/certs/test-cert.pem
+++ b/app/core/src/test/resources/certs/test-cert.pem
@@ -1,26 +1,21 @@
-Bag Attributes
- friendlyName: alias
- localKeyID: 43 4A B0 2D D5 03 52 9F 5B 78 50 64 54 22 AB F7 C8 0B 1F 2B
-subject=C = US, ST = CA, L = SF, O = Test, OU = Test, CN = Test
-issuer=C = US, ST = CA, L = SF, O = Test, OU = Test, CN = Test
-----BEGIN CERTIFICATE-----
-MIIDiTCCAnGgAwIBAgIUdWDUiSWDll+owMQEzypIuChp+bcwDQYJKoZIhvcNAQEL
+MIIDizCCAnOgAwIBAgIUZMcjBbPlADpy5PssUsPlPM/h7dcwDQYJKoZIhvcNAQEL
BQAwVDELMAkGA1UEBhMCVVMxCzAJBgNVBAgMAkNBMQswCQYDVQQHDAJTRjENMAsG
-A1UECgwEVGVzdDENMAsGA1UECwwEVGVzdDENMAsGA1UEAwwEVGVzdDAeFw0yNTA4
-MjYwNzQxMTBaFw0yNjA4MjYwNzQxMTBaMFQxCzAJBgNVBAYTAlVTMQswCQYDVQQI
-DAJDQTELMAkGA1UEBwwCU0YxDTALBgNVBAoMBFRlc3QxDTALBgNVBAsMBFRlc3Qx
-DTALBgNVBAMMBFRlc3QwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDM
-SfspXLx1WAKSo3AfDYIJAyeSrqFcTsPoNBEvT2U1b8w+SCTw4xR5sC3pNenbiEQ7
-4sI60hgURtOMOAt+iKvfI0A/9N8/wYadXUyis4qGZPkM/F6H5cBF9VaYisGptY2w
-ad9X8XcZgZFABYA5O50Jb5nbUM8fPwDYz2fISIejIpW36y+ApFsotJQCaISe4UWb
-K7bwW4UycghYh7AqfH/1OvgR35gGeL7S+SC0F+CZqGECgansFOh/yYL6VoatoggV
-oZxjIQblmuSrLtfwN1S7ngn85k3NFMBHm1ehMOHabx5G58Wg05/0mBK8bIrwjrNp
-Wzomit8BQJ7eIYUikZfVAgMBAAGjUzBRMB0GA1UdDgQWBBRm6hGFGnC1dxipumf/
-6ROdNE6/YDAfBgNVHSMEGDAWgBRm6hGFGnC1dxipumf/6ROdNE6/YDAPBgNVHRMB
-Af8EBTADAQH/MA0GCSqGSIb3DQEBCwUAA4IBAQB66MPy5kZlSlBgsK4HtB1LSr3M
-dmBWbnQQMq9rmD9AIBQV/shiIjMXGRGnt9zaB0Gg9M39iEvISE6ByMpaDQqV0Md5
-9y4XJu0rg/aMXLaHOGDAWJsb7nCGDt12cWdgn1Ni2mmXUHv4SJCRXNQF7mSgIr+p
-Fvd1ljyvzu/iig8qxrcuWoZvY677p3yen4dN8ocgi8Df3KjduGbsTjFAESYqqNQC
-f+bvypQfhHjxdvz5W3Lpk2swUufqOvhO2b6+cshYJX98qLU8mhai/rOnYkHE7haq
-WDH6XEthnVGtk2VJ4XFDbz+FID440DPzy5u/1OZw2Mcoyp6y7rZDKC/D0Uvh
+A1UECgwEVGVzdDENMAsGA1UECwwEVGVzdDENMAsGA1UEAwwEVGVzdDAgFw0yNTAx
+MDEwMDAwMDBaGA8yMTI1MDEwMTAwMDAwMFowVDELMAkGA1UEBhMCVVMxCzAJBgNV
+BAgMAkNBMQswCQYDVQQHDAJTRjENMAsGA1UECgwEVGVzdDENMAsGA1UECwwEVGVz
+dDENMAsGA1UEAwwEVGVzdDCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEB
+AMmEw2bpAoPnrUWkydKGmvDl0bHaCMoSY9yK2b/JL1xaTRwGT4H7DOuO/0Uu6/BV
+c93UEO0eHf1mt1kkYaRSPyOQLXF2QzRDkiW78c/xvqX+DgmfB7BFNrFSP+CRabdH
+wvepLUFtXJ6WwvWXjyvDXn8wEAirfETMdU8OXlPaJwS6cbQawYuB6GG5Z1ulxw6k
+GRi5hnq7PFJBxz1pg6Xx6pwKnaaNemW4Gp2B90St9N5yu7yV6V6XON84ZdohfXSQ
+livH3UTdkrpe+MO2m3CaAA19zlIxM6OIhkuo8r5GEPxoXCykPbgGMRFWPt0GNC3/
+AxZofAJg8atqy4peR8XL060CAwEAAaNTMFEwHQYDVR0OBBYEFDULr71QH24KKgNi
+2fyM6W9qJnzsMA8GA1UdEwEB/wQFMAMBAf8wHwYDVR0jBBgwFoAUNQuvvVAfbgoq
+A2LZ/Izpb2omfOwwDQYJKoZIhvcNAQELBQADggEBAASZENsvvyxygLjE913BBLd2
+73unxWNSDXakT4xssDEysf//4nGPGo57KjUGFU6M64IVUmhPRTT3aYq7PyA9pb5Q
+Ijritg5PdxfUMqd+H3CT++JvJmXxmIrFtKD9fZbmBgRg2wU7yvcp7MP+w36CYmqe
+MH1YF29VcBcF+GfI8k00y83qYHuoHpzPrNcL/Gu6MtcC+1Hy96bs+NYIEFH67dy8
+IJrN3Vvr4VXSF9qA+Vp5RatPv+hEKZssEFK2fNpGMFPGc1r+HBQ/HEAL4M2betEo
+Ne4DigJ3CkTIYAd+cZ2m4tdtzbqkeXZJ7SL+/d/5MIXKTnYITw+NrpiMZ6I72Zk=
-----END CERTIFICATE-----
diff --git a/app/core/src/test/resources/certs/test-cert.pfx b/app/core/src/test/resources/certs/test-cert.pfx
index 02f74b04fd..a11646d84b 100644
Binary files a/app/core/src/test/resources/certs/test-cert.pfx and b/app/core/src/test/resources/certs/test-cert.pfx differ
diff --git a/app/core/src/test/resources/certs/test-key.key b/app/core/src/test/resources/certs/test-key.key
index 93b8804c09..d7c265953a 100644
--- a/app/core/src/test/resources/certs/test-key.key
+++ b/app/core/src/test/resources/certs/test-key.key
@@ -1,34 +1,34 @@
Bag Attributes
friendlyName: alias
- localKeyID: 43 4A B0 2D D5 03 52 9F 5B 78 50 64 54 22 AB F7 C8 0B 1F 2B
+ localKeyID: C0 76 69 F4 6E D7 E6 03 D1 EB AD F1 A4 66 C4 14 3A 9B CB D4
Key Attributes:
-----BEGIN ENCRYPTED PRIVATE KEY-----
-MIIFLTBXBgkqhkiG9w0BBQ0wSjApBgkqhkiG9w0BBQwwHAQIB/3nui1td5QCAggA
-MAwGCCqGSIb3DQIJBQAwHQYJYIZIAWUDBAEqBBDY04ug+QgB6t2TdOWPgdtIBIIE
-0IaMRXXtpzLzSjlpyQpLMWLX9Lu+MauINVQMpan8qspC3RGkGcCQUzTkliM3Ls5Q
-Pwv02iFlKAzUYg/Z5V/kONfDkuxjeZvLFjmzomtWNy6yIxp4ShZinH8AGon16J6E
-s1+xlQBBLZYrRXX7WCpnHKE2OKquOoFWpYcb23py6FlD7Uq6XB0LEHR+C35tgnTQ
-WkTFK/La+cbJ+zmWA11Nrnz5XzuWTrNoNB4ygVON78T9o25Hf4V8rWhSZj2N79+B
-QuCAvuqZyAO12aUI9sxZZyis00JOnX7xbAeOkJk8Hhk4iQRMUUudKb5rqLrh/lcm
-F9zZjpu6PxJh22ztnRik3L3LyZLdEhMJJGWk4Z/3tKO87K4EiluzwZhAfMLpqfxx
-qfRKu6By97pbfJFBKqBTzmli2eeJLOwhERlovIaDiublFU8o8RE92PxUPOr7kqL7
-3cx8Qx5AF2Mnu7ftcLIGgg/lN+haoxpACDkC5ZvTFCrGr7jD1DlkswSMoai9gknx
-IMjID9nq6pVWyBm+wt9cALeK2wNa5RsE9fFvF/DBathV/WNmBwjnTKCeX3uPP1nw
-CUE6d+zicrz79kRWRnmscE3phTTu3/O9TokCMe3rLzC0f+gOpIE7vXDSeRuek/xs
-7uahAAWm94cHdz8QIBR/Ub+fFyrz/VHStAGlZhs0SoVnCl+VnZ9D9OqiyqslOihg
-LMcNwH8QjEv4zRAU/Sf1OdVJItXyKfII5zSUCW/TpD/vWPlG80Ib/bc+H9uZDZsg
-OADQYSyWjxA6OUThbCi6Wr+OxFUuDwVaMXxKjz1xH3HjmjpWZeTJy6BAuqe/OLDg
-VxDdEyL8fgz+QaaM/uqFarVMTir2A5VYNJzTXh02rUn3mXXHbH7uZYSwSg7fJ/hU
-ycSUkr/TFe9ZfqKOg1+ZKDu7Q97/tkL7gBTQbPqitUSinGvBgtMZKTHBznEn8foq
-NL/VaFSR4MxTOxFyE2e+9riNJmR0tavZCSgA7LcJtcT9l62cbmwmMj8DvEw8fiSD
-AYpgwovMtDoVDVQGb7ixLMz8/ta1BB7zPpr2aK8x5pVz5c+9rW/NiWQ68LCpEiAc
-HxExUVR0b9thC5YvG4VepUtmZ768yTYyus9jDiDNwRH/qttmAosn4pq5gGK+IVao
-oJX5jcroYaQnvXDBwve2XXXKSkIWe62r8h7Jv6mxR9yBQdVeWNtCGQ5AYNJNxI0i
-ZbCmCcQJnIuMHLYddaIEmUuUBFOquQC9y/pVbMbmdWOMw5Nama+/q6bke/XGk81I
-/Ov2gNN4Eu2V9N9MzlF0GiAmk1784qITj9iDIiYXPESnQfybFyhi2DaUM+KmeHpB
-I2KHL2KA0EGVhBjvCd7FVAqDJL7Dy3nCiLxNiDKChCP9+DDXB2mEfZafltSWai6p
-FPfGZJImQ6NO4/I/2aeXIwr4urJVFt3mr2b6w+gGRjr4qur0ZcqpvvcA3Es+tMX1
-eY5Or9V8iw/wj0x+CrHvvsRBfvCTSN/yqweMr5p1xSZm3Hfz906/q8HSaHb/sNne
-HCjUiKWJ6WTrjDjf9ewYnXb6Qxs3P0zjuHwSrpbq0Pr3HQveQvO5Tfrwr5+ikK1k
-FyqiU4e4vjpLujkIj2dmH0CkJ6ase1j/rWU8nLr1XZSR
+MIIFNTBfBgkqhkiG9w0BBQ0wUjAxBgkqhkiG9w0BBQwwJAQQnH1/C+tgQtDL2ETF
+DVH1SQICCAAwDAYIKoZIhvcNAgkFADAdBglghkgBZQMEASoEEG7VLFdF6M627msk
+RRRS94wEggTQEOPfMCPRwnTb88nNFAGHr586zkrtG0MUftf4Lgfwns0D5l8qErV2
+oQZqla9XWqzwc1tM6SyeCbP+86vMBLNl4NXN/F/8j+P2njyahBumx9tym0Fs8KSW
+P6/GSmBESJWNJ2vT4lGAsuQyPf+iHvd+RAJbhKCtxWHXMY2OK7j2suCaTJSB5Jz1
+yyPazN/PZSFtDKhMJJRWcQ1pGGsJYaRoJ1v6/05yWtPGGrYGmnDBZ2eKxVm5dncv
+iYfqaIJ2HXmYZLvmDWy9AkHQSF+mNIMEN8jHXw9l1wGPx3GYtqcRr3r/cPDTZLd6
+SAjNY/U2YZUBqPqxgFy8sc1kHX6dJAXgBSeR4Rb8GNB8Ry14tMgJRsdsHi1bpMQ/
+hoqi2mUzYs9I/nz1ncGUB44jtwpN1OgkN9EgQN6i/pN1IJtMkFCnjQ+Ejgi/FRgQ
+R4fpqDxab2NkFGNE8hWiS0nsjvRyAtnqMwf6+flYAUYumeRbUkkYMelYOQelyJVb
+OxvfBUr6XBdTVwBR1B5S1MtFtHyw32i6+RCx0S5jRvA7jdX3CVfbTMnk5xLJOrP4
+7vIckCJaac0NfRQUe812sYWe68LSec3bzz0E4cytyuN7c5u2s1X7i6qs5ITjE7A8
+1Z2m0m+PDH1XjVvbQpzoLmbv4Spzus1fMQ7bGUjjGJw2PyfT9uD4ukEF12VI+S/n
+T6ckOkbUha6t5A47KXPpN4VpCnPFvvsJ4ej/ijzVoo5UbZ358tvCBE2D4uu9/TMq
+hAhWPMnM64JfYRvz96axKy2xgCRGDfYIpTSqBRvCwX3j1MyVKKfjvzIsraHCMb9g
++7ELpbBFB8rRSqV/8VRypWSxmSWhLlgTLgH1iPVd7riSzsxcnBAON2iUmgcE0IEV
+fPcD2uFGTtiNiXu8iZ0xgNZ0nrhquuiUO1hmO/tBquDia7IvyXMHedaugvxdOgu7
+sZ5YD0DJCGOKTPWvBAF3UZPBJ3kbv2zBl/zEQD5e2wcCo2Flubdwz1/Gf9TGehce
+TLz0csUdNXjGmu1wpzwBFdBECPUQ7xoLnwc/1K2AiPcktWdLSPjzTkw6ERsYP9NA
+5w1zi4KmgX2iG78mc/fqHUhppPnL0acLLGFWFKTjYK7mCnPSW5taoRl2EIW+BezK
+kQYrGz1aONC5ol9e9pmK6YHt7fkHiYqPs/pE44a2tuM80EZsfsz0Mn5RKUgAIOOL
+cLvK/zmaZ5pf24b8p9vD7kdlFqzEq+H2t5RGuyCGvanS5Z4LL/fDBjcsCh2E3N+i
+hTsLRPZmKVqeDBIHoyBtSpe5OhzNZTitd6k1JoLFECzHckJflLVEDR7lLvPTI5ko
+/xxDMxi9InTA62zoSokvFIfN95Rd2tXPqmj14gsZlrKT/3cUNmdva0YmgI2gluS0
+qT7zozaKHQDDDMzTjhVRheccZOoPuXgQNvnVaXUDBDNyxRSuy3BWnt5YVQRZBzPw
+HN71h6DxNar/eckRQ03inVn6tGlgwVan5w/JdS7fp1+ET0HF2N93T9f4ZzxHVbEV
+aam9K+1Vn3hZvL5L06Yq5MjNlIaH/RhMY6zlh5CHR7v+vjYIC02ctbZIrbGL3k2u
+JKOKDp2QMhTQQ6QQdzoR6BbRgFDGWz8bzOjtVsW2pY3ketp/7/tpfc4=
-----END ENCRYPTED PRIVATE KEY-----
diff --git a/app/core/src/test/resources/certs/test-key.pem b/app/core/src/test/resources/certs/test-key.pem
index 7653012a10..d7c265953a 100644
--- a/app/core/src/test/resources/certs/test-key.pem
+++ b/app/core/src/test/resources/certs/test-key.pem
@@ -1,34 +1,34 @@
Bag Attributes
friendlyName: alias
- localKeyID: 43 4A B0 2D D5 03 52 9F 5B 78 50 64 54 22 AB F7 C8 0B 1F 2B
+ localKeyID: C0 76 69 F4 6E D7 E6 03 D1 EB AD F1 A4 66 C4 14 3A 9B CB D4
Key Attributes:
-----BEGIN ENCRYPTED PRIVATE KEY-----
-MIIFLTBXBgkqhkiG9w0BBQ0wSjApBgkqhkiG9w0BBQwwHAQIXl98lJJ1MUsCAggA
-MAwGCCqGSIb3DQIJBQAwHQYJYIZIAWUDBAEqBBAcT6pXTGm0w+LUzlVH0GpJBIIE
-0NfOk8+haqEuGskrV8+JJVQLgqpKiOmXBjkiSHGReF4UTocKiUAwrHbvLj+j1VLM
-TNM/G68+SzGuWxI7gxpzA9u7p4Is5+2Sji9KsMuAh2CQlEuzkFsVaD9KXF2rje7g
-0G+4+ExZtsjlt/UqG2plFuWzJwji4J82Cy5dir1MQOOAweq5zG5/nzVpMmNoc1lo
-B9PO18R3SpY6qIp8Q0+d1QJC8zsXi/KKQ3ODiS83x5BL4KkQfjYDK/Lfr9yk5a3t
-JN8wE5jkDyGCLGGWgwy7Xq5N7m+kvcdeIEqKP9g5k5uZ7LppsDFe9dpHVymTHZGu
-tGrB74vi4D28YNhuG5qkTjp6CEehSjMwgWEo0Y6ZGu4WQvoTmkne88zly5vUFNrw
-JFM57YqE8U0Gzy7c/zeGtPq8U7y/Pd4z3muZe9sLpFoFAC7Aoq5yw662mPEBZRVb
-MDw8fK1OY9fnj9qHwQbYAD5AT9GmpwEP4tWkB6qNiDJBR8Jn3VmQ1uwR7oH+BiwX
-Y0xWjgl39JcpMORhzJim7K788FEjDrxR1ptepowC4EKjSeq92BGpO+Flf+lY/xYS
-3QR64h/wJEx7M3FrD7qxSHguW3h8rSMPHQg3YThyBUYsCc1tNpgmhQXNHXlE6G7o
-vdlDawf0Oybq6KzhdU25/kJyTaM7suiDkwyZf8SIElSD8R2VdYmL2AeowJsi26Qc
-0f7l/cL/Pws0j4vxYY+6DD5uw+bCBvsjE5Y8Fw6t0xgYwnMCALjfKr2p3CW/Ifa/
-uynI7Hd548orqkddc834DO6gcPuXMUgZ75RFYglpnD+DDvOzvqh7mrgDiCURZuXd
-eZkF3sr4Wfn4YsQfM0XdfB0/dmzLnGGIzbW9cuB4VQUswDZ9KCnZVMZOC8AMKvSQ
-eZn8VEYSr+qT5m8yKSmeUUQga6G/jN6yHj2mV8ura3o1NHvQpy82lHX3M+2d+cs1
-PWTcYM3AwPpHAM2HyisPYOeNNiEKvo3mtyw2SgV4P6kavdNXFk/xA7mzDWr0QnNX
-/j4ZZFynhUz46joCC6bew0yyRfL1Jqy+XDvtEOmjhy96nJvUDb5IqsMY5ZHRmGkc
-yO3uVQu7kexLcA8mYA5OK1llWuyHxffTyGuL5C0q7+8mBvPrkCakUjsLGAgIWYTE
-ftJ6q8u8xyDghXhRM0lvcoVLjzzjCIDaGVqeXl6HtgJ4grUaNCjESIfsURFylVxk
-3jNFojsxHPtv+zYAG0otqedSKjZaG0uNivjBt/v21luSs+lqEKbv4122yzC8H6pG
-zrS6OGkKb8fIqz3D5nAezMFuMjd+ORiGf/IUJToCeluqVGwXMXExdDSCDf0hFJny
-6y/eKmA88lu6uHYe4TB7ZR2wPyIGl1HPN3xj7Dc/T3wEhCDycKLN4/fY9ZNw5U6E
-F5yVnZFdcaA6qHiY99xvtOPX/EmxibcV6C84QV3HDmdXgjEIH52I9oK0WEjRb2hd
-U2lCnZDNqthn3zn0DZ/aSe4HDe5SfLnzFFGyD1wvCTRcM25901Op4kgVD/BPwWH+
-4E7KiBh91UueWn7m5h1B8cEnpsHwpQLxq2ZdNYzp3ZFyzvzSUXe3QvPveehAgr0M
-lEXzn1/fJpmRPP5hvt6uYqZ+y90BkiT6UlANFHpoA6x0
+MIIFNTBfBgkqhkiG9w0BBQ0wUjAxBgkqhkiG9w0BBQwwJAQQnH1/C+tgQtDL2ETF
+DVH1SQICCAAwDAYIKoZIhvcNAgkFADAdBglghkgBZQMEASoEEG7VLFdF6M627msk
+RRRS94wEggTQEOPfMCPRwnTb88nNFAGHr586zkrtG0MUftf4Lgfwns0D5l8qErV2
+oQZqla9XWqzwc1tM6SyeCbP+86vMBLNl4NXN/F/8j+P2njyahBumx9tym0Fs8KSW
+P6/GSmBESJWNJ2vT4lGAsuQyPf+iHvd+RAJbhKCtxWHXMY2OK7j2suCaTJSB5Jz1
+yyPazN/PZSFtDKhMJJRWcQ1pGGsJYaRoJ1v6/05yWtPGGrYGmnDBZ2eKxVm5dncv
+iYfqaIJ2HXmYZLvmDWy9AkHQSF+mNIMEN8jHXw9l1wGPx3GYtqcRr3r/cPDTZLd6
+SAjNY/U2YZUBqPqxgFy8sc1kHX6dJAXgBSeR4Rb8GNB8Ry14tMgJRsdsHi1bpMQ/
+hoqi2mUzYs9I/nz1ncGUB44jtwpN1OgkN9EgQN6i/pN1IJtMkFCnjQ+Ejgi/FRgQ
+R4fpqDxab2NkFGNE8hWiS0nsjvRyAtnqMwf6+flYAUYumeRbUkkYMelYOQelyJVb
+OxvfBUr6XBdTVwBR1B5S1MtFtHyw32i6+RCx0S5jRvA7jdX3CVfbTMnk5xLJOrP4
+7vIckCJaac0NfRQUe812sYWe68LSec3bzz0E4cytyuN7c5u2s1X7i6qs5ITjE7A8
+1Z2m0m+PDH1XjVvbQpzoLmbv4Spzus1fMQ7bGUjjGJw2PyfT9uD4ukEF12VI+S/n
+T6ckOkbUha6t5A47KXPpN4VpCnPFvvsJ4ej/ijzVoo5UbZ358tvCBE2D4uu9/TMq
+hAhWPMnM64JfYRvz96axKy2xgCRGDfYIpTSqBRvCwX3j1MyVKKfjvzIsraHCMb9g
++7ELpbBFB8rRSqV/8VRypWSxmSWhLlgTLgH1iPVd7riSzsxcnBAON2iUmgcE0IEV
+fPcD2uFGTtiNiXu8iZ0xgNZ0nrhquuiUO1hmO/tBquDia7IvyXMHedaugvxdOgu7
+sZ5YD0DJCGOKTPWvBAF3UZPBJ3kbv2zBl/zEQD5e2wcCo2Flubdwz1/Gf9TGehce
+TLz0csUdNXjGmu1wpzwBFdBECPUQ7xoLnwc/1K2AiPcktWdLSPjzTkw6ERsYP9NA
+5w1zi4KmgX2iG78mc/fqHUhppPnL0acLLGFWFKTjYK7mCnPSW5taoRl2EIW+BezK
+kQYrGz1aONC5ol9e9pmK6YHt7fkHiYqPs/pE44a2tuM80EZsfsz0Mn5RKUgAIOOL
+cLvK/zmaZ5pf24b8p9vD7kdlFqzEq+H2t5RGuyCGvanS5Z4LL/fDBjcsCh2E3N+i
+hTsLRPZmKVqeDBIHoyBtSpe5OhzNZTitd6k1JoLFECzHckJflLVEDR7lLvPTI5ko
+/xxDMxi9InTA62zoSokvFIfN95Rd2tXPqmj14gsZlrKT/3cUNmdva0YmgI2gluS0
+qT7zozaKHQDDDMzTjhVRheccZOoPuXgQNvnVaXUDBDNyxRSuy3BWnt5YVQRZBzPw
+HN71h6DxNar/eckRQ03inVn6tGlgwVan5w/JdS7fp1+ET0HF2N93T9f4ZzxHVbEV
+aam9K+1Vn3hZvL5L06Yq5MjNlIaH/RhMY6zlh5CHR7v+vjYIC02ctbZIrbGL3k2u
+JKOKDp2QMhTQQ6QQdzoR6BbRgFDGWz8bzOjtVsW2pY3ketp/7/tpfc4=
-----END ENCRYPTED PRIVATE KEY-----
diff --git a/app/proprietary/src/main/java/stirling/software/proprietary/accountlink/AccountLinkClient.java b/app/proprietary/src/main/java/stirling/software/proprietary/accountlink/AccountLinkClient.java
index bdd9df10a8..558341745d 100644
--- a/app/proprietary/src/main/java/stirling/software/proprietary/accountlink/AccountLinkClient.java
+++ b/app/proprietary/src/main/java/stirling/software/proprietary/accountlink/AccountLinkClient.java
@@ -24,22 +24,6 @@ import tools.jackson.databind.node.ObjectNode;
/**
* Outbound calls from a self-hosted instance to its linked SaaS backend (combined-billing "Mode
* A").
- *
- *
Calls:
- *
- *
- *
{@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.
- *
{@link #fetchEntitlement} — authenticates with the stored device credential against {@code
- * GET /api/v1/instance/entitlement}; what the local gate consults.
- *
{@link #reportUsage} — daily usage sync ({@code POST /api/v1/instance/sync}); reports
- * cumulative units and returns the refreshed entitlement.
- *
{@link #revokeSelf} — self-revokes the credential on local unlink ({@code POST
- * /api/v1/instance/revoke-self}).
- *
- *
- *
Uses {@code java.net.http.HttpClient} (the established self-hosted outbound pattern; see
- * {@code AiEngineClient}); base URL + client are injectable so tests can stub SaaS.
*/
@Slf4j
@Service
@@ -72,13 +56,7 @@ public class AccountLinkClient {
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.
- */
+ /** A non-2xx reply from the SaaS account-link API. */
public static class UpstreamException extends IOException {
private final int status;
@@ -92,11 +70,7 @@ public class AccountLinkClient {
}
}
- /**
- * Authoritative deny (401/403) — the device credential is revoked or invalid. Unlike a
- * transport/server failure (which returns {@code null} and fails open), the cache must BLOCK on
- * this. Unchecked so it propagates through {@link #fetchEntitlement}'s transport try/catch.
- */
+ /** Authoritative deny (401/403) — the device credential is revoked or invalid. */
public static final class RevokedException extends RuntimeException {
private final int status;
@@ -110,46 +84,142 @@ public class AccountLinkClient {
}
}
+ /** What the SaaS side hands back when it records a connect handshake. */
+ public record ConnectRequestResult(
+ String requestId, int expiresInSeconds, String authorizeUrl) {}
+
+ public enum ConnectClaimOutcome {
+ /** Approved and collected; the credential fields are populated. */
+ GRANTED,
+ /** A re-authentication was approved. */
+ CONFIRMED,
+ /** No human decision yet. */
+ PENDING,
+ /** Declined, expired or already used. */
+ REJECTED,
+ /** SaaS unreachable or erroring. */
+ UNAVAILABLE
+ }
+
+ public record ConnectClaimResult(
+ ConnectClaimOutcome outcome, String deviceId, String deviceSecret, Long teamId) {
+ static ConnectClaimResult of(ConnectClaimOutcome outcome) {
+ return new ConnectClaimResult(outcome, null, null, null);
+ }
+ }
+
+ /** Opens a connect handshake. */
+ public ConnectRequestResult connectRequest(
+ String name, String callbackUrl, String nonce, String claimSecret) throws IOException {
+ return connectRequest(name, callbackUrl, nonce, claimSecret, null);
+ }
+
/**
- * 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).
+ * As {@link #connectRequest}, but presenting an existing device credential so the SaaS side
+ * treats this as a re-authentication and pins the handshake to the team we already belong to.
*/
- public RegisterResult register(String supabaseJwt, String instanceName) throws IOException {
- String body =
- instanceName == null || instanceName.isBlank()
- ? "{}"
- : "{\"name\":" + mapper.writeValueAsString(instanceName) + "}";
- HttpRequest request =
+ public ConnectRequestResult connectRequest(
+ String name,
+ String callbackUrl,
+ String nonce,
+ String claimSecret,
+ DeviceCredential credential)
+ throws IOException {
+ ObjectNode root = mapper.createObjectNode();
+ if (name != null && !name.isBlank()) {
+ root.put("name", name);
+ }
+ root.put("callbackUrl", callbackUrl);
+ root.put("nonce", nonce);
+ root.put("claimSecret", claimSecret);
+
+ HttpRequest.Builder builder =
HttpRequest.newBuilder()
- .uri(uri("/api/v1/account-link/register"))
- .header("Authorization", "Bearer " + supabaseJwt)
+ .uri(uri("/api/v1/account-link/connect/request"))
.header("Content-Type", "application/json")
.header("Accept", "application/json")
.timeout(timeout())
- .POST(HttpRequest.BodyPublishers.ofString(body))
- .build();
+ .POST(HttpRequest.BodyPublishers.ofString(mapper.writeValueAsString(root)));
+ if (credential != null) {
+ builder.header(HEADER_DEVICE_ID, credential.getDeviceId())
+ .header(HEADER_DEVICE_SECRET, credential.getDeviceSecret());
+ }
- HttpResponse response = send(request);
+ HttpResponse response = send(builder.build());
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");
+ JsonNode body = mapper.readTree(response.body());
+ String requestId = text(body, "requestId");
+ if (requestId == null) {
+ throw new IOException("SaaS connect response missing requestId");
+ }
+ String authorizeUrl = text(body, "authorizeUrl");
+ if (authorizeUrl == null || !isAbsoluteHttpUrl(authorizeUrl)) {
+ throw new IOException("SaaS connect response carried no usable authorizeUrl");
+ }
+ return new ConnectRequestResult(requestId, body.path("expiresIn").asInt(0), authorizeUrl);
+ }
+
+ /**
+ * Collects the device credential for an approved handshake, proving possession of the claim
+ * secret.
+ */
+ public ConnectClaimResult connectClaim(String requestId, String claimSecret) {
+ HttpResponse response;
+ try {
+ ObjectNode root = mapper.createObjectNode();
+ root.put("requestId", requestId);
+ root.put("claimSecret", claimSecret);
+ HttpRequest request =
+ HttpRequest.newBuilder()
+ .uri(uri("/api/v1/account-link/connect/claim"))
+ .header("Content-Type", "application/json")
+ .header("Accept", "application/json")
+ .timeout(timeout())
+ .POST(
+ HttpRequest.BodyPublishers.ofString(
+ mapper.writeValueAsString(root)))
+ .build();
+ response = send(request);
+ } catch (Exception e) {
+ log.debug("Connect claim failed (transport): {}", e.getMessage());
+ return ConnectClaimResult.of(ConnectClaimOutcome.UNAVAILABLE);
+ }
+ int status = response.statusCode();
+ if (status == 202) {
+ return ConnectClaimResult.of(ConnectClaimOutcome.PENDING);
+ }
+ if (status >= 500 && status <= 599) {
+ return ConnectClaimResult.of(ConnectClaimOutcome.UNAVAILABLE);
+ }
+ if (status < 200 || status > 299) {
+ return ConnectClaimResult.of(ConnectClaimOutcome.REJECTED);
+ }
+ try {
+ JsonNode body = mapper.readTree(response.body());
+ Long teamId = body.hasNonNull("teamId") ? body.get("teamId").asLong() : null;
+ // A re-authentication says so explicitly and carries no credential, so an absent
+ // credential is only an error when we were expecting one.
+ if ("confirmed".equals(text(body, "status"))) {
+ return new ConnectClaimResult(ConnectClaimOutcome.CONFIRMED, null, null, teamId);
+ }
+ String deviceId = text(body, "deviceId");
+ String deviceSecret = text(body, "deviceSecret");
+ if (deviceId == null || deviceSecret == null) {
+ log.warn("Connect claim succeeded but the reply carried no credential");
+ return ConnectClaimResult.of(ConnectClaimOutcome.REJECTED);
+ }
+ return new ConnectClaimResult(
+ ConnectClaimOutcome.GRANTED, deviceId, deviceSecret, teamId);
+ } catch (RuntimeException e) {
+ log.debug("Connect claim parse failed: {}", e.getMessage());
+ return ConnectClaimResult.of(ConnectClaimOutcome.REJECTED);
}
- 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, authenticated by that credential.
- * Best-effort: returns {@code false} if SaaS is unreachable or rejects, so the caller (local
- * unlink) can still clear locally and log the orphan for follow-up. Idempotent on SaaS.
*/
public boolean revokeSelf(String deviceId, String deviceSecret) {
try {
@@ -174,17 +244,7 @@ public class AccountLinkClient {
}
}
- /**
- * Fetches the current entitlement using the stored device credential. Three outcomes:
- *
- *
- *
2xx → the parsed snapshot.
- *
401/403 → {@link RevokedException} (authoritative deny — revoked/invalid credential);
- * the caller must BLOCK, not fail open.
- *
transport failure, other non-2xx (e.g. 5xx), or a malformed body → {@code null}
- * ("unknown" — the caller fails open).
- *
- */
+ /** Fetches the current entitlement using the stored device credential. */
public InstanceEntitlement fetchEntitlement(String deviceId, String deviceSecret) {
HttpResponse response;
try {
@@ -224,9 +284,6 @@ public class AccountLinkClient {
/**
* Reports the period's cumulative per-category units to {@code POST /api/v1/instance/sync} and
* returns the fresh entitlement in the same reply — one round-trip both reports and refreshes.
- * SaaS bills the delta against its last-seen cumulative, so resending the same totals is
- * idempotent. Same three outcomes as {@link #fetchEntitlement}; on {@code null} the caller must
- * not advance its last-synced markers so the usage retries next sync.
*/
public InstanceEntitlement reportUsage(
String deviceId,
@@ -360,4 +417,19 @@ public class AccountLinkClient {
private static String text(JsonNode node, String field) {
return node.hasNonNull(field) ? node.get(field).asText() : null;
}
+
+ /** Absolute http(s) with a host. */
+ static boolean isAbsoluteHttpUrl(String candidate) {
+ try {
+ URI uri = URI.create(candidate.strip());
+ String scheme = uri.getScheme();
+ return uri.isAbsolute()
+ && scheme != null
+ && ("http".equalsIgnoreCase(scheme) || "https".equalsIgnoreCase(scheme))
+ && uri.getHost() != null
+ && !uri.getHost().isBlank();
+ } catch (IllegalArgumentException e) {
+ return false;
+ }
+ }
}
diff --git a/app/proprietary/src/main/java/stirling/software/proprietary/accountlink/AccountLinkController.java b/app/proprietary/src/main/java/stirling/software/proprietary/accountlink/AccountLinkController.java
index 52af366df4..b1826b7cca 100644
--- a/app/proprietary/src/main/java/stirling/software/proprietary/accountlink/AccountLinkController.java
+++ b/app/proprietary/src/main/java/stirling/software/proprietary/accountlink/AccountLinkController.java
@@ -16,21 +16,11 @@ import org.springframework.web.bind.annotation.RestController;
import io.swagger.v3.oas.annotations.Hidden;
+import jakarta.servlet.http.HttpServletRequest;
+
import lombok.extern.slf4j.Slf4j;
-/**
- * Same-origin account-link surface on the self-hosted instance (combined-billing "Mode A").
- *
- *
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; {@code GET /usage} exposes locally-accrued unsynced usage the portal adds
- * to SaaS-synced spend; {@code POST /sync-now} forces an immediate usage sync (ops "reconcile now"
- * / test aid).
- *
- *
Admin-only, {@code @Profile("!saas")}, gated behind {@code
- * stirling.billing.account-link.enabled} — off → bean absent → 404.
- */
+/** Same-origin account-link surface on the self-hosted instance (combined billing). */
@Slf4j
@Hidden
@RestController
@@ -41,51 +31,110 @@ import lombok.extern.slf4j.Slf4j;
public class AccountLinkController {
private final AccountLinkService service;
+ private final ConnectService connectService;
private final LocalUsageService localUsageService;
// Present only when metering is on (its own flag); absent → /sync-now reports 409.
private final ObjectProvider syncServiceProvider;
public AccountLinkController(
AccountLinkService service,
+ ConnectService connectService,
LocalUsageService localUsageService,
ObjectProvider syncServiceProvider) {
this.service = service;
+ this.connectService = connectService;
this.localUsageService = localUsageService;
this.syncServiceProvider = syncServiceProvider;
}
- /** {@code supabaseJwt} is the admin's short-lived token the portal already holds. */
- public record LinkRequest(String supabaseJwt, String name) {}
+ /** {@code callbackUrl} is the portal telling us where its own callback route lives. */
+ public record ConnectStartRequest(String name, String callbackUrl) {}
- @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"));
- }
+ /** {@code nonce} comes from the callback fragment the approval page redirected to. */
+ public record ConnectCompleteRequest(String nonce) {}
+
+ /**
+ * Opens a browser-mediated link handshake and returns the approval URL to send the admin to.
+ */
+ @PostMapping("/connect/start")
+ public ResponseEntity connectStart(
+ @RequestBody(required = false) ConnectStartRequest req, HttpServletRequest http) {
try {
- return ResponseEntity.ok(service.link(req.supabaseJwt(), req.name()));
+ return ResponseEntity.ok(
+ connectService.start(req != null ? req.name() : null, callbackHint(req, http)));
} 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());
+ log.warn("Account-link connect rejected upstream: HTTP {}", e.status());
return ResponseEntity.status(HttpStatus.BAD_GATEWAY)
- .body(java.util.Map.of("error", "LINK_FAILED"));
+ .body(java.util.Map.of("error", "CONNECT_FAILED"));
+ } catch (IOException e) {
+ // Same reasoning as /link: a transport message can carry the configured SaaS host.
+ log.warn("Account-link connect failed (transport): {}", e.getMessage());
+ return ResponseEntity.status(HttpStatus.BAD_GATEWAY)
+ .body(java.util.Map.of("error", "CONNECT_FAILED"));
}
}
+ /** Re-establishes the admin's SaaS session for a server that is already linked. */
+ @PostMapping("/connect/reauth")
+ public ResponseEntity connectReauth(
+ @RequestBody(required = false) ConnectStartRequest req, HttpServletRequest http) {
+ try {
+ return ResponseEntity.ok(connectService.startReauth(callbackHint(req, http)));
+ } catch (AccountLinkClient.UpstreamException e) {
+ log.warn("Account-link reauth rejected upstream: HTTP {}", e.status());
+ return ResponseEntity.status(HttpStatus.BAD_GATEWAY)
+ .body(java.util.Map.of("error", "CONNECT_FAILED"));
+ } catch (IOException e) {
+ log.warn("Account-link reauth failed: {}", e.getMessage());
+ return ResponseEntity.status(HttpStatus.BAD_GATEWAY)
+ .body(java.util.Map.of("error", "CONNECT_FAILED"));
+ }
+ }
+
+ /** Called by the callback page with the nonce it found in the fragment. */
+ @PostMapping("/connect/complete")
+ public ResponseEntity connectComplete(
+ @RequestBody(required = false) ConnectCompleteRequest req) {
+ return ResponseEntity.ok(connectService.complete(req != null ? req.nonce() : null));
+ }
+
+ /** Everything we know about where the admin's browser is, for the callback. */
+ private static ConnectService.CallbackHint callbackHint(
+ ConnectStartRequest req, HttpServletRequest http) {
+ return new ConnectService.CallbackHint(
+ req != null ? req.callbackUrl() : null, http.getHeader("Origin"), baseUrlOf(http));
+ }
+
+ /**
+ * This instance's base URL as the browser reached it, including any context path so a subpath
+ * deployment builds a callback that actually resolves.
+ */
+ private static String baseUrlOf(HttpServletRequest request) {
+ String forwardedProto = firstHop(request.getHeader("X-Forwarded-Proto"));
+ String forwardedHost = firstHop(request.getHeader("X-Forwarded-Host"));
+ String scheme = forwardedProto != null ? forwardedProto : request.getScheme();
+ String hostPort;
+ if (forwardedHost != null) {
+ hostPort = forwardedHost;
+ } else {
+ int port = request.getServerPort();
+ boolean defaultPort =
+ ("http".equals(scheme) && port == 80)
+ || ("https".equals(scheme) && port == 443);
+ hostPort = defaultPort ? request.getServerName() : request.getServerName() + ":" + port;
+ }
+ String context = request.getContextPath() == null ? "" : request.getContextPath();
+ return scheme + "://" + hostPort + context;
+ }
+
+ private static String firstHop(String headerValue) {
+ if (headerValue == null || headerValue.isBlank()) {
+ return null;
+ }
+ String first = headerValue.split(",")[0].strip();
+ return first.isEmpty() ? null : first;
+ }
+
@GetMapping("/status")
public ResponseEntity status() {
return ResponseEntity.ok(service.status());
@@ -106,12 +155,7 @@ public class AccountLinkController {
return ResponseEntity.ok(localUsageService.currentPeriodUnsynced());
}
- /**
- * Forces an immediate usage sync to SaaS — the same work the daily scheduler does. An admin
- * "reconcile now" action (and a test aid so you don't wait on the scheduler). Idempotent:
- * re-reports the current cumulative, so a repeat trigger bills nothing. {@code 204} once run;
- * {@code 409} when metering is off (the sync bean is absent).
- */
+ /** Forces an immediate usage sync to SaaS — the same work the daily scheduler does. */
@PostMapping("/sync-now")
public ResponseEntity syncNow() {
UsageSyncService sync = syncServiceProvider.getIfAvailable();
diff --git a/app/proprietary/src/main/java/stirling/software/proprietary/accountlink/AccountLinkProperties.java b/app/proprietary/src/main/java/stirling/software/proprietary/accountlink/AccountLinkProperties.java
index 6d1f1fb151..619aa10e86 100644
--- a/app/proprietary/src/main/java/stirling/software/proprietary/accountlink/AccountLinkProperties.java
+++ b/app/proprietary/src/main/java/stirling/software/proprietary/accountlink/AccountLinkProperties.java
@@ -8,29 +8,17 @@ import org.springframework.stereotype.Component;
import lombok.Getter;
import lombok.Setter;
-/**
- * Self-hosted side of combined-billing "Mode A" (connected self-hosted).
- *
- *
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
- * off by default and dark — when off nothing gates and the link endpoints 404.
- */
+/** Self-hosted side of combined billing: this instance bills through a linked SaaS team. */
@Getter
@Setter
@Component
@ConfigurationProperties(prefix = "stirling.billing.account-link")
public class AccountLinkProperties {
- /** Master switch. When {@code false} (default) the feature is fully inert. */
+ /** Master switch. */
private boolean enabled = false;
- /**
- * Base URL of the SaaS backend this instance links to (register + entitlement live there).
- *
- *
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.
- */
+ /** Base URL of the SaaS backend this instance links to (register + entitlement live there). */
private String saasBaseUrl = "https://stirling.com/app";
/** Cached entitlement is reused for this long before a refresh is attempted. */
@@ -39,20 +27,18 @@ public class AccountLinkProperties {
/** Connect/read timeout for the outbound SaaS calls. */
private int requestTimeoutSeconds = 10;
- /** Phase 2 usage metering + daily sync. Keyed under {@code …account-link.metering.*}. */
+ /** Phase 2 usage metering + daily sync. */
private final Metering metering = new Metering();
/**
- * Dedicated billing switch, separate from {@link #enabled} so the link plumbing can be
- * enabled (e.g. to test linking) without ever turning on real usage metering, reporting, or cap
- * enforcement. Both default off; metering requires the master flag too. This is the production
- * safety key — flipping it on is what actually bills linked instances.
+ * Separate from {@link #enabled} so linking can be exercised without billing anything. Both
+ * default off, and metering needs the master flag as well.
*/
@Getter
@Setter
public static class Metering {
- /** Turns on usage metering, the daily sync, and cap enforcement. Default off. */
+ /** Turns on usage metering, the daily sync, and cap enforcement. */
private boolean enabled = false;
/**
@@ -65,12 +51,7 @@ public class AccountLinkProperties {
*/
private int graceDays = 3;
- /**
- * Dedup window for identical input sets. A re-run of the same inputs within this window is
- * treated as workflow chaining and not re-charged; the same inputs run again after it are
- * billed afresh. Mirrors the cloud's {@code payg.lineage.workflow-window} so the same op
- * costs the same on the instance and in the cloud.
- */
+ /** Dedup window for identical input sets. */
private Duration workflowWindow = Duration.ofMinutes(5);
}
}
diff --git a/app/proprietary/src/main/java/stirling/software/proprietary/accountlink/AccountLinkService.java b/app/proprietary/src/main/java/stirling/software/proprietary/accountlink/AccountLinkService.java
index 1bb27d9cd6..e1283d83ba 100644
--- a/app/proprietary/src/main/java/stirling/software/proprietary/accountlink/AccountLinkService.java
+++ b/app/proprietary/src/main/java/stirling/software/proprietary/accountlink/AccountLinkService.java
@@ -1,6 +1,5 @@
package stirling.software.proprietary.accountlink;
-import java.io.IOException;
import java.util.Optional;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
@@ -9,13 +8,7 @@ import org.springframework.stereotype.Service;
import lombok.extern.slf4j.Slf4j;
-/**
- * Linking orchestrator (self-hosted side of combined-billing "Mode A").
- *
- *
{@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.
- */
+/** Linking orchestrator (self-hosted side of combined billing). */
@Slf4j
@Service
@Profile("!saas")
@@ -38,24 +31,9 @@ public class AccountLinkService {
/** 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.
+ * revoked_at} set), then clears locally regardless.
*/
public void unlink() {
credentialStore
diff --git a/app/proprietary/src/main/java/stirling/software/proprietary/accountlink/AccountLinkSyncState.java b/app/proprietary/src/main/java/stirling/software/proprietary/accountlink/AccountLinkSyncState.java
index fbac6a8603..2715b4743b 100644
--- a/app/proprietary/src/main/java/stirling/software/proprietary/accountlink/AccountLinkSyncState.java
+++ b/app/proprietary/src/main/java/stirling/software/proprietary/accountlink/AccountLinkSyncState.java
@@ -12,7 +12,7 @@ import lombok.NoArgsConstructor;
import lombok.Setter;
/**
- * Singleton row holding this instance's daily-sync bookkeeping (combined-billing "Mode A").
+ * Singleton row holding this instance's daily-sync bookkeeping (combined billing).
*
*
{@link #lastSyncSeq} is reserved (incremented + persisted) before each report so it
* is strictly monotonic across restarts and partial failures — SaaS dedups replays by comparing it,
diff --git a/app/proprietary/src/main/java/stirling/software/proprietary/accountlink/AccountLinkSyncStateRepository.java b/app/proprietary/src/main/java/stirling/software/proprietary/accountlink/AccountLinkSyncStateRepository.java
index 15b5e3842d..d0cdf36f90 100644
--- a/app/proprietary/src/main/java/stirling/software/proprietary/accountlink/AccountLinkSyncStateRepository.java
+++ b/app/proprietary/src/main/java/stirling/software/proprietary/accountlink/AccountLinkSyncStateRepository.java
@@ -2,5 +2,5 @@ package stirling.software.proprietary.accountlink;
import org.springframework.data.jpa.repository.JpaRepository;
-/** Persistence for the singleton {@link AccountLinkSyncState} (combined-billing "Mode A"). */
+/** Persistence for the singleton {@link AccountLinkSyncState} (combined billing). */
public interface AccountLinkSyncStateRepository extends JpaRepository {}
diff --git a/app/proprietary/src/main/java/stirling/software/proprietary/accountlink/ConnectService.java b/app/proprietary/src/main/java/stirling/software/proprietary/accountlink/ConnectService.java
new file mode 100644
index 0000000000..978d6d494e
--- /dev/null
+++ b/app/proprietary/src/main/java/stirling/software/proprietary/accountlink/ConnectService.java
@@ -0,0 +1,276 @@
+package stirling.software.proprietary.accountlink;
+
+import java.io.IOException;
+import java.net.URI;
+import java.net.URISyntaxException;
+import java.nio.charset.StandardCharsets;
+import java.security.MessageDigest;
+import java.security.SecureRandom;
+import java.time.Duration;
+import java.time.LocalDateTime;
+import java.util.Base64;
+import java.util.Locale;
+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;
+
+import lombok.extern.slf4j.Slf4j;
+
+import stirling.software.common.model.ApplicationProperties;
+
+/** Browser-mediated account linking, instance side. */
+@Slf4j
+@Service
+@Profile("!saas")
+@ConditionalOnProperty(name = "stirling.billing.account-link.enabled", havingValue = "true")
+public class ConnectService {
+
+ /** Frontend route that consumes the callback fragment. */
+ static final String CALLBACK_PATH = "/account-link/callback";
+
+ private static final int SECRET_BYTES = 32;
+
+ private final AccountLinkClient client;
+ private final ConnectStateRepository stateRepo;
+ private final DeviceCredentialStore credentialStore;
+ private final EntitlementCache entitlementCache;
+ private final ApplicationProperties applicationProperties;
+ private final SecureRandom random = new SecureRandom();
+
+ public ConnectService(
+ AccountLinkClient client,
+ ConnectStateRepository stateRepo,
+ DeviceCredentialStore credentialStore,
+ EntitlementCache entitlementCache,
+ ApplicationProperties applicationProperties) {
+ this.client = client;
+ this.stateRepo = stateRepo;
+ this.credentialStore = credentialStore;
+ this.entitlementCache = entitlementCache;
+ this.applicationProperties = applicationProperties;
+ }
+
+ public enum Phase {
+ /** Nothing in flight and not linked. */
+ NONE,
+ /** A handshake is open, waiting for a leader to approve it on the SaaS site. */
+ PENDING,
+ /** Linked. */
+ LINKED,
+ /** The handshake outlived its window; start a new one. */
+ EXPIRED,
+ /** Declined or already used; start a new one. */
+ REJECTED,
+ /** SaaS could not be reached; the handshake is still valid and can be retried. */
+ UNAVAILABLE
+ }
+
+ /** What the portal renders. */
+ public record ConnectStatus(
+ Phase phase, String authorizeUrl, Long secondsRemaining, Long teamId) {
+ static ConnectStatus of(Phase phase) {
+ return new ConnectStatus(phase, null, null, null);
+ }
+ }
+
+ /** Everything we know about where the admin's browser actually is, in decreasing authority. */
+ public record CallbackHint(
+ String requestedCallbackUrl, String browserOrigin, String derivedBaseUrl) {}
+
+ /** Opens a handshake and returns where to send the admin. */
+ @Transactional
+ public ConnectStatus start(String name, CallbackHint hint) throws IOException {
+ if (credentialStore.isLinked()) {
+ return status();
+ }
+ return open(name, hint, null);
+ }
+
+ /**
+ * Opens a handshake that only re-establishes the admin's browser session, for an instance that
+ * is already linked.
+ */
+ @Transactional
+ public ConnectStatus startReauth(CallbackHint hint) throws IOException {
+ DeviceCredential credential =
+ credentialStore
+ .get()
+ .orElseThrow(
+ () ->
+ new IOException(
+ "This server is not linked, so there is no session"
+ + " to re-establish"));
+ return open(credential.getDeviceId(), hint, credential);
+ }
+
+ private ConnectStatus open(String name, CallbackHint hint, DeviceCredential credential)
+ throws IOException {
+ String callbackUrl = resolveCallbackUrl(hint);
+ if (callbackUrl == null) {
+ throw new IOException(
+ "Cannot determine where to send the admin back to; set system.frontendUrl");
+ }
+ String nonce = randomSecret();
+ String claimSecret = randomSecret();
+
+ AccountLinkClient.ConnectRequestResult created =
+ client.connectRequest(name, callbackUrl, nonce, claimSecret, credential);
+
+ LocalDateTime now = LocalDateTime.now();
+ ConnectState state = new ConnectState();
+ state.setId(ConnectState.SINGLETON_ID);
+ state.setRequestId(created.requestId());
+ state.setNonce(nonce);
+ state.setClaimSecret(claimSecret);
+ state.setCallbackUrl(callbackUrl);
+ state.setAuthorizeUrl(created.authorizeUrl());
+ state.setCreatedAt(now);
+ state.setExpiresAt(
+ now.plusSeconds(created.expiresInSeconds() > 0 ? created.expiresInSeconds() : 900));
+ stateRepo.save(state);
+
+ log.info("Account-link connect: handshake {} opened", created.requestId());
+ return pendingStatus(state, now);
+ }
+
+ /** Finishes a handshake from the callback the approval page redirected to. */
+ @Transactional
+ public ConnectStatus complete(String nonce) {
+ Optional found = stateRepo.findById(ConnectState.SINGLETON_ID);
+ if (found.isEmpty()) {
+ // Already finished (a double-submitted callback) or never started.
+ return status();
+ }
+ ConnectState state = found.get();
+ if (state.isExpired(LocalDateTime.now())) {
+ stateRepo.delete(state);
+ return ConnectStatus.of(Phase.EXPIRED);
+ }
+ if (nonce == null || !nonceMatches(nonce, state.getNonce())) {
+ log.warn(
+ "Account-link connect: callback for handshake {} had a bad nonce",
+ state.getRequestId());
+ return ConnectStatus.of(Phase.REJECTED);
+ }
+
+ AccountLinkClient.ConnectClaimResult claim =
+ client.connectClaim(state.getRequestId(), state.getClaimSecret());
+ return switch (claim.outcome()) {
+ case GRANTED -> {
+ credentialStore.save(claim.deviceId(), claim.deviceSecret(), claim.teamId());
+ entitlementCache.invalidate();
+ stateRepo.delete(state);
+ log.info("Account-link connect: linked to team {}", claim.teamId());
+ yield new ConnectStatus(Phase.LINKED, null, null, claim.teamId());
+ }
+ case CONFIRMED -> {
+ stateRepo.delete(state);
+ log.info(
+ "Account-link connect: session re-established for team {}", claim.teamId());
+ yield new ConnectStatus(Phase.LINKED, null, null, claim.teamId());
+ }
+ case PENDING ->
+ // The admin reached the callback before the approval committed. The row stays,
+ // so a retry finishes it.
+ ConnectStatus.of(Phase.PENDING);
+ case REJECTED -> {
+ stateRepo.delete(state);
+ yield ConnectStatus.of(Phase.REJECTED);
+ }
+ case UNAVAILABLE -> ConnectStatus.of(Phase.UNAVAILABLE);
+ };
+ }
+
+ @Transactional(readOnly = true)
+ public ConnectStatus status() {
+ Optional credential = credentialStore.get();
+ if (credential.isPresent()) {
+ return new ConnectStatus(Phase.LINKED, null, null, credential.get().getTeamId());
+ }
+ Optional state = stateRepo.findById(ConnectState.SINGLETON_ID);
+ if (state.isEmpty()) {
+ return ConnectStatus.of(Phase.NONE);
+ }
+ LocalDateTime now = LocalDateTime.now();
+ if (state.get().isExpired(now)) {
+ return ConnectStatus.of(Phase.EXPIRED);
+ }
+ return pendingStatus(state.get(), now);
+ }
+
+ private static ConnectStatus pendingStatus(ConnectState state, LocalDateTime now) {
+ long remaining = Duration.between(now, state.getExpiresAt()).toSeconds();
+ return new ConnectStatus(
+ Phase.PENDING, state.getAuthorizeUrl(), Math.max(remaining, 0), null);
+ }
+
+ /** Decides the callback, preferring knowledge over inference. */
+ String resolveCallbackUrl(CallbackHint hint) {
+ String configured = applicationProperties.getSystem().getFrontendUrl();
+ if (configured != null && !configured.isBlank()) {
+ return trimTrailingSlash(configured.strip()) + CALLBACK_PATH;
+ }
+ String browserOrigin = originOf(hint.browserOrigin());
+ if (browserOrigin != null) {
+ String requested = hint.requestedCallbackUrl();
+ if (requested != null && browserOrigin.equals(originOf(requested))) {
+ return requested.strip();
+ }
+ return browserOrigin + CALLBACK_PATH;
+ }
+ return hint.derivedBaseUrl() == null || hint.derivedBaseUrl().isBlank()
+ ? null
+ : trimTrailingSlash(hint.derivedBaseUrl().strip()) + CALLBACK_PATH;
+ }
+
+ /** Scheme, host and port of an absolute http(s) URL; null if it is not one. */
+ private static String originOf(String candidate) {
+ if (candidate == null || candidate.isBlank()) {
+ return null;
+ }
+ URI uri;
+ try {
+ uri = new URI(candidate.strip());
+ } catch (URISyntaxException e) {
+ return null;
+ }
+ if (uri.getScheme() == null || uri.getHost() == null) {
+ return null;
+ }
+ String scheme = uri.getScheme().toLowerCase(Locale.ROOT);
+ if (!"http".equals(scheme) && !"https".equals(scheme)) {
+ return null;
+ }
+ int port = uri.getPort();
+ boolean defaultPort =
+ port == -1
+ || ("http".equals(scheme) && port == 80)
+ || ("https".equals(scheme) && port == 443);
+ return defaultPort
+ ? scheme + "://" + uri.getHost()
+ : scheme + "://" + uri.getHost() + ":" + port;
+ }
+
+ private static String trimTrailingSlash(String value) {
+ return value.replaceAll("/+$", "");
+ }
+
+ private String randomSecret() {
+ byte[] buf = new byte[SECRET_BYTES];
+ random.nextBytes(buf);
+ return Base64.getUrlEncoder().withoutPadding().encodeToString(buf);
+ }
+
+ /** Constant-time so a caller cannot probe the nonce a character at a time. */
+ private static boolean nonceMatches(String candidate, String expected) {
+ if (expected == null) {
+ return false;
+ }
+ return MessageDigest.isEqual(
+ candidate.getBytes(StandardCharsets.UTF_8),
+ expected.getBytes(StandardCharsets.UTF_8));
+ }
+}
diff --git a/app/proprietary/src/main/java/stirling/software/proprietary/accountlink/ConnectState.java b/app/proprietary/src/main/java/stirling/software/proprietary/accountlink/ConnectState.java
new file mode 100644
index 0000000000..c0dcea032e
--- /dev/null
+++ b/app/proprietary/src/main/java/stirling/software/proprietary/accountlink/ConnectState.java
@@ -0,0 +1,60 @@
+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 one in-flight "connect this server" handshake, instance side. */
+@Entity
+@Table(name = "account_link_connect_state")
+@NoArgsConstructor
+@Getter
+@Setter
+public class ConnectState implements Serializable {
+
+ private static final long serialVersionUID = 1L;
+
+ public static final Long SINGLETON_ID = 1L;
+
+ @Id
+ @Column(name = "id")
+ private Long id = SINGLETON_ID;
+
+ /** Opaque handle the SaaS side gave us; identifies the handshake on both sides. */
+ @Column(name = "request_id", nullable = false, length = 64)
+ private String requestId;
+
+ /** Correlator we minted. */
+ @Column(name = "nonce", nullable = false, length = 128)
+ private String nonce;
+
+ /** Secret we minted and sent to SaaS server to server. */
+ @Column(name = "claim_secret", nullable = false, length = 128)
+ private String claimSecret;
+
+ /** Where we asked the approval page to send the admin back to. */
+ @Column(name = "callback_url", nullable = false, length = 2048)
+ private String callbackUrl;
+
+ /** The approval URL handed to the browser, so a reload can offer it again. */
+ @Column(name = "authorize_url", nullable = false, length = 2048)
+ private String authorizeUrl;
+
+ @Column(name = "created_at", nullable = false)
+ private LocalDateTime createdAt;
+
+ @Column(name = "expires_at", nullable = false)
+ private LocalDateTime expiresAt;
+
+ public boolean isExpired(LocalDateTime now) {
+ return expiresAt != null && expiresAt.isBefore(now);
+ }
+}
diff --git a/app/proprietary/src/main/java/stirling/software/proprietary/accountlink/ConnectStateRepository.java b/app/proprietary/src/main/java/stirling/software/proprietary/accountlink/ConnectStateRepository.java
new file mode 100644
index 0000000000..995dfccde1
--- /dev/null
+++ b/app/proprietary/src/main/java/stirling/software/proprietary/accountlink/ConnectStateRepository.java
@@ -0,0 +1,6 @@
+package stirling.software.proprietary.accountlink;
+
+import org.springframework.data.jpa.repository.JpaRepository;
+
+/** Data access for the singleton {@link ConnectState} row. */
+public interface ConnectStateRepository extends JpaRepository {}
diff --git a/app/proprietary/src/main/java/stirling/software/proprietary/accountlink/DeviceCredential.java b/app/proprietary/src/main/java/stirling/software/proprietary/accountlink/DeviceCredential.java
index 4625572310..7da486b741 100644
--- a/app/proprietary/src/main/java/stirling/software/proprietary/accountlink/DeviceCredential.java
+++ b/app/proprietary/src/main/java/stirling/software/proprietary/accountlink/DeviceCredential.java
@@ -13,8 +13,8 @@ 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.
+ * The device credential this self-hosted instance received when it linked a SaaS account (combined
+ * billing). Singleton — one instance links to exactly one SaaS team.
*
*
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
diff --git a/app/proprietary/src/main/java/stirling/software/proprietary/accountlink/InstanceEntitlementGate.java b/app/proprietary/src/main/java/stirling/software/proprietary/accountlink/InstanceEntitlementGate.java
index 018684b73f..c0cc901e1f 100644
--- a/app/proprietary/src/main/java/stirling/software/proprietary/accountlink/InstanceEntitlementGate.java
+++ b/app/proprietary/src/main/java/stirling/software/proprietary/accountlink/InstanceEntitlementGate.java
@@ -8,7 +8,7 @@ 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.
+ * Decides whether a request may proceed under combined billing on a self-hosted instance.
*
*
Rules (in order):
*
diff --git a/app/proprietary/src/main/java/stirling/software/proprietary/accountlink/InstanceEntitlementInterceptor.java b/app/proprietary/src/main/java/stirling/software/proprietary/accountlink/InstanceEntitlementInterceptor.java
index 0cd71c9bda..9e73267561 100644
--- a/app/proprietary/src/main/java/stirling/software/proprietary/accountlink/InstanceEntitlementInterceptor.java
+++ b/app/proprietary/src/main/java/stirling/software/proprietary/accountlink/InstanceEntitlementInterceptor.java
@@ -39,8 +39,8 @@ import stirling.software.proprietary.policy.controller.PolicyRunRoutes;
import stirling.software.proprietary.security.model.ApiKeyAuthenticationToken;
/**
- * Request-time gate + meter for combined-billing "Mode A". {@code preHandle} blocks billable (API /
- * AI / automation) work when the instance is unlinked or over its limit; manual tools pass through.
+ * Request-time gate + meter for combined billing. {@code preHandle} blocks billable (API / AI /
+ * automation) work when the instance is unlinked or over its limit; manual tools pass through.
* {@code afterCompletion} meters a successful billable op into the per-period cumulative counter.
*
*
Blocking responds {@code 402} with a machine-readable body the FE maps to a "link to activate"
diff --git a/app/proprietary/src/main/java/stirling/software/proprietary/accountlink/MeteredInputSignature.java b/app/proprietary/src/main/java/stirling/software/proprietary/accountlink/MeteredInputSignature.java
index 1ed49d6a8b..278380a5da 100644
--- a/app/proprietary/src/main/java/stirling/software/proprietary/accountlink/MeteredInputSignature.java
+++ b/app/proprietary/src/main/java/stirling/software/proprietary/accountlink/MeteredInputSignature.java
@@ -16,11 +16,11 @@ import lombok.NoArgsConstructor;
/**
* The last time the instance metered a given input set this period — the local equivalent of the
- * cloud's lineage join (combined-billing "Mode A"). The meter dedups on a rolling workflow
- * window: an identical input set re-submitted within the window (see {@link
- * AccountLinkProperties.Metering}) is treated as workflow chaining and not re-charged, while the
- * same inputs run again after the window are billed afresh — matching the cloud's 5-minute open-job
- * window so the same operation costs the same on the instance and in the cloud.
+ * cloud's lineage join (combined billing). The meter dedups on a rolling workflow window: an
+ * identical input set re-submitted within the window (see {@link AccountLinkProperties.Metering})
+ * is treated as workflow chaining and not re-charged, while the same inputs run again after the
+ * window are billed afresh — matching the cloud's 5-minute open-job window so the same operation
+ * costs the same on the instance and in the cloud.
*
*
{@code lastMeteredAt} is refreshed on every sighting (the window slides, as recording a cloud
* artifact touches its job). One row per {@code (period, signature)}; the unique constraint also
diff --git a/app/proprietary/src/main/java/stirling/software/proprietary/accountlink/MeteredInputSignatureRepository.java b/app/proprietary/src/main/java/stirling/software/proprietary/accountlink/MeteredInputSignatureRepository.java
index 863f503f61..a31310a7b3 100644
--- a/app/proprietary/src/main/java/stirling/software/proprietary/accountlink/MeteredInputSignatureRepository.java
+++ b/app/proprietary/src/main/java/stirling/software/proprietary/accountlink/MeteredInputSignatureRepository.java
@@ -5,7 +5,7 @@ import java.util.Optional;
import org.springframework.data.jpa.repository.JpaRepository;
-/** Persistence for the per-period metered input-set signatures (combined-billing "Mode A"). */
+/** Persistence for the per-period metered input-set signatures (combined billing). */
public interface MeteredInputSignatureRepository
extends JpaRepository {
diff --git a/app/proprietary/src/main/java/stirling/software/proprietary/accountlink/UsageCounter.java b/app/proprietary/src/main/java/stirling/software/proprietary/accountlink/UsageCounter.java
index b90af07958..4c06089040 100644
--- a/app/proprietary/src/main/java/stirling/software/proprietary/accountlink/UsageCounter.java
+++ b/app/proprietary/src/main/java/stirling/software/proprietary/accountlink/UsageCounter.java
@@ -17,10 +17,10 @@ import lombok.NoArgsConstructor;
import stirling.software.proprietary.billing.BillingCategory;
/**
- * Durable per-(billing period, category) cumulative usage counter for combined-billing "Mode A".
- * Each successful billable op increments its row; the daily sync reports the cumulative totals and
- * SaaS bills the delta since the last sync. The cumulative model is idempotent (a resend bills
- * nothing) and tamper-evident (a counter that drops is a signal). One row per {@code (period_start,
+ * Durable per-(billing period, category) cumulative usage counter for combined billing. Each
+ * successful billable op increments its row; the daily sync reports the cumulative totals and SaaS
+ * bills the delta since the last sync. The cumulative model is idempotent (a resend bills nothing)
+ * and tamper-evident (a counter that drops is a signal). One row per {@code (period_start,
* category)}, auto-created by Hibernate; only the flag-gated {@link UsageMeterService} writes it.
*/
@Entity
diff --git a/app/proprietary/src/main/java/stirling/software/proprietary/accountlink/UsageCounterRepository.java b/app/proprietary/src/main/java/stirling/software/proprietary/accountlink/UsageCounterRepository.java
index 2140775abc..3013d00a52 100644
--- a/app/proprietary/src/main/java/stirling/software/proprietary/accountlink/UsageCounterRepository.java
+++ b/app/proprietary/src/main/java/stirling/software/proprietary/accountlink/UsageCounterRepository.java
@@ -9,7 +9,7 @@ import org.springframework.data.jpa.repository.Query;
import org.springframework.data.repository.query.Param;
import org.springframework.transaction.annotation.Transactional;
-/** Persistence for the per-period/per-category usage counters (combined-billing "Mode A"). */
+/** Persistence for the per-period/per-category usage counters (combined billing). */
public interface UsageCounterRepository extends JpaRepository {
/**
diff --git a/app/proprietary/src/main/java/stirling/software/proprietary/accountlink/UsageSyncService.java b/app/proprietary/src/main/java/stirling/software/proprietary/accountlink/UsageSyncService.java
index 4c4ce2377c..a12a26eb8a 100644
--- a/app/proprietary/src/main/java/stirling/software/proprietary/accountlink/UsageSyncService.java
+++ b/app/proprietary/src/main/java/stirling/software/proprietary/accountlink/UsageSyncService.java
@@ -18,8 +18,8 @@ import lombok.extern.slf4j.Slf4j;
import stirling.software.proprietary.billing.BillingCategory;
/**
- * Daily usage sender for combined-billing "Mode A". Reports each period's cumulative per-category
- * usage to SaaS, which bills the delta against its own last-seen totals.
+ * Daily usage sender for combined billing. Reports each period's cumulative per-category usage to
+ * SaaS, which bills the delta against its own last-seen totals.
*
*
Resilience: the sync seq is persisted before the report so it never regresses across
* restarts/failures; a transport failure leaves the {@code lastSyncedUnits} markers untouched so
diff --git a/app/proprietary/src/main/java/stirling/software/proprietary/audit/AuditLevel.java b/app/proprietary/src/main/java/stirling/software/proprietary/audit/AuditLevel.java
index 59adc2af80..c2b0e53eb7 100644
--- a/app/proprietary/src/main/java/stirling/software/proprietary/audit/AuditLevel.java
+++ b/app/proprietary/src/main/java/stirling/software/proprietary/audit/AuditLevel.java
@@ -59,7 +59,7 @@ public enum AuditLevel {
*/
public static AuditLevel fromInt(int level) {
// Ensure level is within valid bounds
- int boundedLevel = Math.min(Math.max(level, 0), 3);
+ int boundedLevel = Math.clamp(level, 0, 3);
for (AuditLevel auditLevel : values()) {
if (auditLevel.level == boundedLevel) {
diff --git a/app/proprietary/src/main/java/stirling/software/proprietary/billing/ContentHasher.java b/app/proprietary/src/main/java/stirling/software/proprietary/billing/ContentHasher.java
index 232dd499dc..182c162f6f 100644
--- a/app/proprietary/src/main/java/stirling/software/proprietary/billing/ContentHasher.java
+++ b/app/proprietary/src/main/java/stirling/software/proprietary/billing/ContentHasher.java
@@ -11,9 +11,9 @@ import java.util.HexFormat;
/**
* SHA-256 content fingerprint shared by the SaaS charge path and the linked self-hosted instance's
- * meter (combined-billing "Mode A"), so both derive an identical signature for the same
- * bytes — the basis for lineage dedup. Pure, no Spring: fixed 64 KiB buffer (allocation independent
- * of file size), hardware-accelerated by the JVM where available.
+ * meter (combined billing), so both derive an identical signature for the same bytes — the
+ * basis for lineage dedup. Pure, no Spring: fixed 64 KiB buffer (allocation independent of file
+ * size), hardware-accelerated by the JVM where available.
*
*
Lives in {@code :proprietary} (not {@code :common}) so it stays out of the community core
* build yet is reachable from {@code :saas} (which depends on {@code :proprietary}).
diff --git a/app/proprietary/src/main/java/stirling/software/proprietary/cluster/valkey/ValkeyJobStore.java b/app/proprietary/src/main/java/stirling/software/proprietary/cluster/valkey/ValkeyJobStore.java
index 8e93871859..f03992ed4d 100644
--- a/app/proprietary/src/main/java/stirling/software/proprietary/cluster/valkey/ValkeyJobStore.java
+++ b/app/proprietary/src/main/java/stirling/software/proprietary/cluster/valkey/ValkeyJobStore.java
@@ -17,16 +17,16 @@ import org.springframework.data.redis.core.ScanOptions;
import org.springframework.data.redis.core.StringRedisTemplate;
import org.springframework.stereotype.Component;
-import com.fasterxml.jackson.core.JsonProcessingException;
-import com.fasterxml.jackson.core.type.TypeReference;
-import com.fasterxml.jackson.databind.ObjectMapper;
-
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import stirling.software.common.cluster.JobStore;
import stirling.software.common.cluster.JobStoreEntry;
+import tools.jackson.core.JacksonException;
+import tools.jackson.core.type.TypeReference;
+import tools.jackson.databind.ObjectMapper;
+
/**
* Valkey-backed {@link JobStore}. Each job is one hash; a reverse index maps fileId to jobId.
*
@@ -44,8 +44,10 @@ public class ValkeyJobStore implements JobStore {
private static final String FILE_INDEX_PREFIX = "stirling:file2job:";
private static final ObjectMapper MAPPER = new ObjectMapper();
- private static final TypeReference> LIST_STRING = new TypeReference<>() {};
- private static final TypeReference> MAP_STRING = new TypeReference<>() {};
+ private static final TypeReference> LIST_STRING =
+ new TypeReference>() {};
+ private static final TypeReference> MAP_STRING =
+ new TypeReference>() {};
private final StringRedisTemplate template;
@@ -265,7 +267,7 @@ public class ValkeyJobStore implements JobStore {
}
try {
return MAPPER.readValue(v.toString(), MAP_STRING);
- } catch (JsonProcessingException e) {
+ } catch (JacksonException e) {
log.warn(
"JobStore {} field 'resultMeta' is not valid JSON '{}' - treating as empty",
key,
@@ -277,7 +279,7 @@ public class ValkeyJobStore implements JobStore {
private static String writeJson(Object value) {
try {
return MAPPER.writeValueAsString(value);
- } catch (JsonProcessingException e) {
+ } catch (JacksonException e) {
throw new IllegalStateException("Failed to JSON-serialize JobStore field", e);
}
}
@@ -286,7 +288,7 @@ public class ValkeyJobStore implements JobStore {
try {
List parsed = MAPPER.readValue(json, LIST_STRING);
return parsed == null ? new ArrayList<>() : parsed;
- } catch (JsonProcessingException e) {
+ } catch (JacksonException e) {
log.warn(
"JobStore {} field 'fileIds' is not valid JSON '{}' - treating as empty",
key,
diff --git a/app/proprietary/src/main/java/stirling/software/proprietary/config/AuditConfigurationProperties.java b/app/proprietary/src/main/java/stirling/software/proprietary/config/AuditConfigurationProperties.java
index 366d91b11c..ac6c25ac5e 100644
--- a/app/proprietary/src/main/java/stirling/software/proprietary/config/AuditConfigurationProperties.java
+++ b/app/proprietary/src/main/java/stirling/software/proprietary/config/AuditConfigurationProperties.java
@@ -35,7 +35,7 @@ public class AuditConfigurationProperties {
// Ensure level is within valid bounds (0-3)
int configLevel = auditConfig.getLevel();
- this.level = Math.min(Math.max(configLevel, 0), 3);
+ this.level = Math.clamp(configLevel, 0, 3);
// Retention days (0 means infinite)
this.retentionDays = auditConfig.getRetentionDays();
diff --git a/app/proprietary/src/main/java/stirling/software/proprietary/controller/api/UsageRestController.java b/app/proprietary/src/main/java/stirling/software/proprietary/controller/api/UsageRestController.java
index 1230d928cc..65bf8240a4 100644
--- a/app/proprietary/src/main/java/stirling/software/proprietary/controller/api/UsageRestController.java
+++ b/app/proprietary/src/main/java/stirling/software/proprietary/controller/api/UsageRestController.java
@@ -48,7 +48,7 @@ public class UsageRestController {
@RequestParam(value = "dataType", defaultValue = "all") String dataType,
@RequestParam(value = "days", defaultValue = "30") Integer days) {
- int lookbackDays = Math.max(1, Math.min(days, 365));
+ int lookbackDays = Math.clamp(days, 1, 365);
// Get audit events filtered by type
List events = getEventsByDataType(dataType, lookbackDays);
diff --git a/app/proprietary/src/main/java/stirling/software/proprietary/model/UserLicenseSettings.java b/app/proprietary/src/main/java/stirling/software/proprietary/model/UserLicenseSettings.java
index bb7f52142a..1683ad9134 100644
--- a/app/proprietary/src/main/java/stirling/software/proprietary/model/UserLicenseSettings.java
+++ b/app/proprietary/src/main/java/stirling/software/proprietary/model/UserLicenseSettings.java
@@ -1,5 +1,6 @@
package stirling.software.proprietary.model;
+import java.io.Serial;
import java.io.Serializable;
import jakarta.persistence.*;
@@ -19,7 +20,7 @@ import lombok.*;
@ToString
public class UserLicenseSettings implements Serializable {
- private static final long serialVersionUID = 1L;
+ @Serial private static final long serialVersionUID = 1L;
public static final Long SINGLETON_ID = 1L;
diff --git a/app/proprietary/src/main/java/stirling/software/proprietary/security/CustomLogoutSuccessHandler.java b/app/proprietary/src/main/java/stirling/software/proprietary/security/CustomLogoutSuccessHandler.java
index 4bfef06c9b..d83b684166 100644
--- a/app/proprietary/src/main/java/stirling/software/proprietary/security/CustomLogoutSuccessHandler.java
+++ b/app/proprietary/src/main/java/stirling/software/proprietary/security/CustomLogoutSuccessHandler.java
@@ -70,21 +70,23 @@ public class CustomLogoutSuccessHandler extends SimpleUrlLogoutSuccessHandler {
if (!response.isCommitted()) {
if (authentication != null) {
- if (authentication instanceof Saml2Authentication samlAuthentication) {
- // Handle SAML2 logout redirection
- getRedirect_saml2(request, response, samlAuthentication);
- } else if (authentication instanceof OAuth2AuthenticationToken oAuthToken) {
- // Handle OAuth2 logout redirection
- getRedirect_oauth2(request, response, oAuthToken);
- } else if (authentication instanceof UsernamePasswordAuthenticationToken) {
- // Handle Username/Password logout
- getRedirectStrategy().sendRedirect(request, response, LOGOUT_PATH);
- } else {
- // Handle unknown authentication types
- log.error(
- "Authentication class unknown: {}",
- authentication.getClass().getSimpleName());
- getRedirectStrategy().sendRedirect(request, response, LOGOUT_PATH);
+ switch (authentication) {
+ case Saml2Authentication samlAuthentication ->
+ // Handle SAML2 logout redirection
+ getRedirect_saml2(request, response, samlAuthentication);
+ case OAuth2AuthenticationToken oAuthToken ->
+ // Handle OAuth2 logout redirection
+ getRedirect_oauth2(request, response, oAuthToken);
+ case UsernamePasswordAuthenticationToken usernamePasswordAuthenticationToken ->
+ // Handle Username/Password logout
+ getRedirectStrategy().sendRedirect(request, response, LOGOUT_PATH);
+ default -> {
+ // Handle unknown authentication types
+ log.error(
+ "Authentication class unknown: {}",
+ authentication.getClass().getSimpleName());
+ getRedirectStrategy().sendRedirect(request, response, LOGOUT_PATH);
+ }
}
} else {
if (jwtService != null) {
diff --git a/app/proprietary/src/main/java/stirling/software/proprietary/security/configuration/SecurityConfiguration.java b/app/proprietary/src/main/java/stirling/software/proprietary/security/configuration/SecurityConfiguration.java
index 9fc4428f73..7c5b412d33 100644
--- a/app/proprietary/src/main/java/stirling/software/proprietary/security/configuration/SecurityConfiguration.java
+++ b/app/proprietary/src/main/java/stirling/software/proprietary/security/configuration/SecurityConfiguration.java
@@ -357,12 +357,12 @@ public class SecurityConfiguration {
req -> {
String uri = req.getRequestURI();
String contextPath = req.getContextPath();
- // Check if it's a public auth endpoint or static
- // resource
return RequestUriUtils.isStaticResource(
contextPath, uri)
|| RequestUriUtils.isPublicAuthEndpoint(
- uri, contextPath);
+ uri, contextPath)
+ || RequestUriUtils.isFrontendRoute(
+ contextPath, uri);
})
.permitAll()
.anyRequest()
@@ -392,40 +392,40 @@ public class SecurityConfiguration {
// Handle OAUTH2 Logins
if (securityProperties.isOauth2Active()) {
http.oauth2Login(
- oauth2 -> {
- oauth2.loginPage("/login")
- .authorizationEndpoint(
- authorizationEndpoint -> {
- if (clientRegistrationRepository != null) {
- authorizationEndpoint
- .authorizationRequestResolver(
- new TauriAuthorizationRequestResolver(
- clientRegistrationRepository));
- }
- })
- .successHandler(
- new CustomOAuth2AuthenticationSuccessHandler(
- loginAttemptService,
- securityProperties.getOauth2(),
- userService,
- jwtService,
- licenseSettingsService,
- applicationProperties))
- .failureHandler(new CustomOAuth2AuthenticationFailureHandler())
- // Add existing Authorities from the database
- .userInfoEndpoint(
- userInfoEndpoint ->
- userInfoEndpoint
- .oidcUserService(
- new CustomOAuth2UserService(
- securityProperties
- .getOauth2(),
- userService,
- loginAttemptService))
- .userAuthoritiesMapper(
- oAuth2userAuthoritiesMapper))
- .permitAll();
- });
+ oauth2 ->
+ oauth2.loginPage("/login")
+ .authorizationEndpoint(
+ authorizationEndpoint -> {
+ if (clientRegistrationRepository != null) {
+ authorizationEndpoint
+ .authorizationRequestResolver(
+ new TauriAuthorizationRequestResolver(
+ clientRegistrationRepository));
+ }
+ })
+ .successHandler(
+ new CustomOAuth2AuthenticationSuccessHandler(
+ loginAttemptService,
+ securityProperties.getOauth2(),
+ userService,
+ jwtService,
+ licenseSettingsService,
+ applicationProperties))
+ .failureHandler(
+ new CustomOAuth2AuthenticationFailureHandler())
+ // Add existing Authorities from the database
+ .userInfoEndpoint(
+ userInfoEndpoint ->
+ userInfoEndpoint
+ .oidcUserService(
+ new CustomOAuth2UserService(
+ securityProperties
+ .getOauth2(),
+ userService,
+ loginAttemptService))
+ .userAuthoritiesMapper(
+ oAuth2userAuthoritiesMapper))
+ .permitAll());
}
// Handle SAML
if (securityProperties.isSaml2Active() && runningProOrHigher) {
diff --git a/app/proprietary/src/main/java/stirling/software/proprietary/security/controller/api/AuthController.java b/app/proprietary/src/main/java/stirling/software/proprietary/security/controller/api/AuthController.java
index 86a1c5fe0c..6661c86395 100644
--- a/app/proprietary/src/main/java/stirling/software/proprietary/security/controller/api/AuthController.java
+++ b/app/proprietary/src/main/java/stirling/software/proprietary/security/controller/api/AuthController.java
@@ -703,17 +703,18 @@ public class AuthController {
}
private long extractEpochMillis(Object claimValue) {
- if (claimValue == null) {
- return -1L;
- }
-
- if (claimValue instanceof java.util.Date date) {
- return date.getTime();
- }
-
- if (claimValue instanceof Number number) {
- long epochSeconds = number.longValue();
- return epochSeconds * 1000L;
+ switch (claimValue) {
+ case null -> {
+ return -1L;
+ }
+ case java.util.Date date -> {
+ return date.getTime();
+ }
+ case Number number -> {
+ long epochSeconds = number.longValue();
+ return epochSeconds * 1000L;
+ }
+ default -> {}
}
return -1L;
diff --git a/app/proprietary/src/main/java/stirling/software/proprietary/security/controller/api/UserController.java b/app/proprietary/src/main/java/stirling/software/proprietary/security/controller/api/UserController.java
index fdacda72b2..2385eb011f 100644
--- a/app/proprietary/src/main/java/stirling/software/proprietary/security/controller/api/UserController.java
+++ b/app/proprietary/src/main/java/stirling/software/proprietary/security/controller/api/UserController.java
@@ -760,14 +760,14 @@ public class UserController {
for (Object principal : principals) {
List sessionsInformation =
sessionRegistry.getAllSessions(principal, false);
- if (principal instanceof UserDetails detailsUser) {
- userNameP = detailsUser.getUsername();
- } else if (principal instanceof OAuth2User oAuth2User) {
- userNameP = oAuth2User.getName();
- } else if (principal instanceof CustomSaml2AuthenticatedPrincipal saml2User) {
- userNameP = saml2User.name();
- } else if (principal instanceof String stringUser) {
- userNameP = stringUser;
+ switch (principal) {
+ case null -> {}
+ case UserDetails detailsUser -> userNameP = detailsUser.getUsername();
+ case OAuth2User oAuth2User -> userNameP = oAuth2User.getName();
+ case CustomSaml2AuthenticatedPrincipal saml2User ->
+ userNameP = saml2User.name();
+ case String stringUser -> userNameP = stringUser;
+ default -> {}
}
if (userNameP.equalsIgnoreCase(username)) {
for (SessionInformation sessionInfo : sessionsInformation) {
diff --git a/app/proprietary/src/main/java/stirling/software/proprietary/security/model/Authority.java b/app/proprietary/src/main/java/stirling/software/proprietary/security/model/Authority.java
index 659f7691bd..4ffea54740 100644
--- a/app/proprietary/src/main/java/stirling/software/proprietary/security/model/Authority.java
+++ b/app/proprietary/src/main/java/stirling/software/proprietary/security/model/Authority.java
@@ -1,5 +1,6 @@
package stirling.software.proprietary.security.model;
+import java.io.Serial;
import java.io.Serializable;
import org.springframework.security.core.GrantedAuthority;
@@ -28,7 +29,7 @@ import lombok.Setter;
@Setter
public class Authority implements GrantedAuthority, Serializable {
- private static final long serialVersionUID = 1L;
+ @Serial private static final long serialVersionUID = 1L;
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
diff --git a/app/proprietary/src/main/java/stirling/software/proprietary/security/model/InviteToken.java b/app/proprietary/src/main/java/stirling/software/proprietary/security/model/InviteToken.java
index 975220bf48..062cce058f 100644
--- a/app/proprietary/src/main/java/stirling/software/proprietary/security/model/InviteToken.java
+++ b/app/proprietary/src/main/java/stirling/software/proprietary/security/model/InviteToken.java
@@ -1,5 +1,6 @@
package stirling.software.proprietary.security.model;
+import java.io.Serial;
import java.io.Serializable;
import java.time.LocalDateTime;
@@ -18,7 +19,7 @@ import lombok.Setter;
@Setter
public class InviteToken implements Serializable {
- private static final long serialVersionUID = 1L;
+ @Serial private static final long serialVersionUID = 1L;
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
diff --git a/app/proprietary/src/main/java/stirling/software/proprietary/security/oauth2/CustomOAuth2AuthenticationFailureHandler.java b/app/proprietary/src/main/java/stirling/software/proprietary/security/oauth2/CustomOAuth2AuthenticationFailureHandler.java
index 784a9f0a2f..670b08c53f 100644
--- a/app/proprietary/src/main/java/stirling/software/proprietary/security/oauth2/CustomOAuth2AuthenticationFailureHandler.java
+++ b/app/proprietary/src/main/java/stirling/software/proprietary/security/oauth2/CustomOAuth2AuthenticationFailureHandler.java
@@ -36,57 +36,62 @@ public class CustomOAuth2AuthenticationFailureHandler
AuthenticationException exception)
throws IOException, ServletException {
- if (exception instanceof BadCredentialsException) {
- log.error("BadCredentialsException", exception);
- getRedirectStrategy().sendRedirect(request, response, "/login?error=badCredentials");
- return;
- }
- if (exception instanceof DisabledException) {
- log.error("User is deactivated: ", exception);
- getRedirectStrategy().sendRedirect(request, response, "/logout?userIsDisabled=true");
- return;
- }
- if (exception instanceof LockedException) {
- log.error("Account locked: ", exception);
- getRedirectStrategy().sendRedirect(request, response, "/logout?error=locked");
- return;
- }
- if (exception instanceof OAuth2AuthenticationException oAuth2Exception) {
- OAuth2Error error = oAuth2Exception.getError();
-
- String errorCode = error.getErrorCode();
-
- if ("Password must not be null".equals(error.getErrorCode())) {
- errorCode = "userAlreadyExistsWeb";
+ switch (exception) {
+ case BadCredentialsException badCredentialsException -> {
+ log.error("BadCredentialsException", exception);
+ getRedirectStrategy()
+ .sendRedirect(request, response, "/login?error=badCredentials");
+ return;
}
+ case DisabledException disabledException -> {
+ log.error("User is deactivated: ", exception);
+ getRedirectStrategy()
+ .sendRedirect(request, response, "/logout?userIsDisabled=true");
+ return;
+ }
+ case LockedException lockedException -> {
+ log.error("Account locked: ", exception);
+ getRedirectStrategy().sendRedirect(request, response, "/logout?error=locked");
+ return;
+ }
+ case OAuth2AuthenticationException oAuth2Exception -> {
+ OAuth2Error error = oAuth2Exception.getError();
- log.error(
- "OAuth2 Authentication error: {}",
- errorCode != null ? errorCode : exception.getMessage(),
- exception);
- String errorValue = errorCode != null ? errorCode : "oauth2AuthenticationError";
- clearRedirectCookie(response);
- boolean tauriState = TauriOAuthUtils.isTauriState(request);
- String redirectUrl;
- if (tauriState) {
- String basePath =
- TauriOAuthUtils.defaultTauriCallbackPath(request.getContextPath());
- redirectUrl = basePath;
- String stateParam = request.getParameter("state");
- if (stateParam != null && !stateParam.isBlank()) {
- redirectUrl = appendQueryParam(redirectUrl, "state", stateParam);
- // Extract and pass nonce for CSRF validation
- String nonce = TauriOAuthUtils.extractNonceFromState(stateParam);
- if (nonce != null) {
- redirectUrl = appendQueryParam(redirectUrl, "nonce", nonce);
- }
+ String errorCode = error.getErrorCode();
+
+ if ("Password must not be null".equals(error.getErrorCode())) {
+ errorCode = "userAlreadyExistsWeb";
}
- redirectUrl = appendQueryParam(redirectUrl, "errorOAuth", errorValue);
- } else {
- redirectUrl = buildFailureRedirectUrl(request, errorValue);
+
+ log.error(
+ "OAuth2 Authentication error: {}",
+ errorCode != null ? errorCode : exception.getMessage(),
+ exception);
+ String errorValue = errorCode != null ? errorCode : "oauth2AuthenticationError";
+ clearRedirectCookie(response);
+ boolean tauriState = TauriOAuthUtils.isTauriState(request);
+ String redirectUrl;
+ if (tauriState) {
+ String basePath =
+ TauriOAuthUtils.defaultTauriCallbackPath(request.getContextPath());
+ redirectUrl = basePath;
+ String stateParam = request.getParameter("state");
+ if (stateParam != null && !stateParam.isBlank()) {
+ redirectUrl = appendQueryParam(redirectUrl, "state", stateParam);
+ // Extract and pass nonce for CSRF validation
+ String nonce = TauriOAuthUtils.extractNonceFromState(stateParam);
+ if (nonce != null) {
+ redirectUrl = appendQueryParam(redirectUrl, "nonce", nonce);
+ }
+ }
+ redirectUrl = appendQueryParam(redirectUrl, "errorOAuth", errorValue);
+ } else {
+ redirectUrl = buildFailureRedirectUrl(request, errorValue);
+ }
+ getRedirectStrategy().sendRedirect(request, response, redirectUrl);
+ return;
}
- getRedirectStrategy().sendRedirect(request, response, redirectUrl);
- return;
+ default -> {}
}
log.error("Unhandled authentication exception", exception);
super.onAuthenticationFailure(request, response, exception);
diff --git a/app/proprietary/src/main/java/stirling/software/proprietary/security/saml2/CustomSaml2ResponseAuthenticationConverter.java b/app/proprietary/src/main/java/stirling/software/proprietary/security/saml2/CustomSaml2ResponseAuthenticationConverter.java
index b2ce4adb68..96dcdecd03 100644
--- a/app/proprietary/src/main/java/stirling/software/proprietary/security/saml2/CustomSaml2ResponseAuthenticationConverter.java
+++ b/app/proprietary/src/main/java/stirling/software/proprietary/security/saml2/CustomSaml2ResponseAuthenticationConverter.java
@@ -61,7 +61,12 @@ public class CustomSaml2ResponseAuthenticationConverter
@Override
public Saml2Authentication convert(ResponseToken responseToken) {
- Assertion assertion = responseToken.getResponse().getAssertions().getFirst();
+ List assertions = responseToken.getResponse().getAssertions();
+ if (assertions == null || assertions.isEmpty()) {
+ log.error("SAML response contains no assertions");
+ return null;
+ }
+ Assertion assertion = assertions.getFirst();
Map> attributes = extractAttributes(assertion);
// Debug log with actual values
diff --git a/app/proprietary/src/main/java/stirling/software/proprietary/security/service/CustomOAuth2UserService.java b/app/proprietary/src/main/java/stirling/software/proprietary/security/service/CustomOAuth2UserService.java
index c1057c7e36..b8054c89d9 100644
--- a/app/proprietary/src/main/java/stirling/software/proprietary/security/service/CustomOAuth2UserService.java
+++ b/app/proprietary/src/main/java/stirling/software/proprietary/security/service/CustomOAuth2UserService.java
@@ -213,8 +213,11 @@ public class CustomOAuth2UserService implements OAuth2UserService {}
+ case UserDetails detailsUser -> usernameP = detailsUser.getUsername();
+ case OAuth2User oAuth2User -> usernameP = oAuth2User.getName();
+ case CustomSaml2AuthenticatedPrincipal saml2User ->
+ usernameP = saml2User.name();
+ case String stringUser -> usernameP = stringUser;
+ default -> {}
}
if (usernameP.equalsIgnoreCase(username)) {
sessionRegistry.expireSession(sessionsInformation.getSessionId());
diff --git a/app/proprietary/src/main/java/stirling/software/proprietary/security/session/SessionPersistentRegistry.java b/app/proprietary/src/main/java/stirling/software/proprietary/security/session/SessionPersistentRegistry.java
index e615416e59..1f3a4e84ff 100644
--- a/app/proprietary/src/main/java/stirling/software/proprietary/security/session/SessionPersistentRegistry.java
+++ b/app/proprietary/src/main/java/stirling/software/proprietary/security/session/SessionPersistentRegistry.java
@@ -47,14 +47,13 @@ public class SessionPersistentRegistry implements SessionRegistry {
List sessionInformations = new ArrayList<>();
String principalName = null;
- if (principal instanceof UserDetails detailsUser) {
- principalName = detailsUser.getUsername();
- } else if (principal instanceof OAuth2User oAuth2User) {
- principalName = oAuth2User.getName();
- } else if (principal instanceof CustomSaml2AuthenticatedPrincipal saml2User) {
- principalName = saml2User.name();
- } else if (principal instanceof String stringUser) {
- principalName = stringUser;
+ switch (principal) {
+ case null -> {}
+ case UserDetails detailsUser -> principalName = detailsUser.getUsername();
+ case OAuth2User oAuth2User -> principalName = oAuth2User.getName();
+ case CustomSaml2AuthenticatedPrincipal saml2User -> principalName = saml2User.name();
+ case String stringUser -> principalName = stringUser;
+ default -> {}
}
if (principalName != null) {
@@ -78,14 +77,13 @@ public class SessionPersistentRegistry implements SessionRegistry {
public void registerNewSession(String sessionId, Object principal) {
String principalName = null;
- if (principal instanceof UserDetails detailsUser) {
- principalName = detailsUser.getUsername();
- } else if (principal instanceof OAuth2User oAuth2User) {
- principalName = oAuth2User.getName();
- } else if (principal instanceof CustomSaml2AuthenticatedPrincipal saml2User) {
- principalName = saml2User.name();
- } else if (principal instanceof String stringUser) {
- principalName = stringUser;
+ switch (principal) {
+ case null -> {}
+ case UserDetails detailsUser -> principalName = detailsUser.getUsername();
+ case OAuth2User oAuth2User -> principalName = oAuth2User.getName();
+ case CustomSaml2AuthenticatedPrincipal saml2User -> principalName = saml2User.name();
+ case String stringUser -> principalName = stringUser;
+ default -> {}
}
if (principalName != null) {
diff --git a/app/proprietary/src/main/java/stirling/software/proprietary/storage/converter/JsonMapConverter.java b/app/proprietary/src/main/java/stirling/software/proprietary/storage/converter/JsonMapConverter.java
index 1c9f7ab765..5576ebb181 100644
--- a/app/proprietary/src/main/java/stirling/software/proprietary/storage/converter/JsonMapConverter.java
+++ b/app/proprietary/src/main/java/stirling/software/proprietary/storage/converter/JsonMapConverter.java
@@ -3,16 +3,16 @@ package stirling.software.proprietary.storage.converter;
import java.util.HashMap;
import java.util.Map;
-import com.fasterxml.jackson.core.JsonProcessingException;
-import com.fasterxml.jackson.core.type.TypeReference;
-import com.fasterxml.jackson.databind.JsonNode;
-import com.fasterxml.jackson.databind.ObjectMapper;
-
import jakarta.persistence.AttributeConverter;
import jakarta.persistence.Converter;
import lombok.extern.slf4j.Slf4j;
+import tools.jackson.core.JacksonException;
+import tools.jackson.core.type.TypeReference;
+import tools.jackson.databind.JsonNode;
+import tools.jackson.databind.ObjectMapper;
+
/**
* JPA AttributeConverter for storing Map as JSON in database columns.
*
@@ -33,7 +33,7 @@ public class JsonMapConverter implements AttributeConverter,
try {
return objectMapper.writeValueAsString(attribute);
- } catch (JsonProcessingException e) {
+ } catch (JacksonException e) {
log.error("Failed to convert map to JSON", e);
throw new RuntimeException("Failed to convert map to JSON", e);
}
@@ -48,7 +48,7 @@ public class JsonMapConverter implements AttributeConverter,
try {
// Try normal parsing first
return objectMapper.readValue(dbData, new TypeReference>() {});
- } catch (JsonProcessingException e) {
+ } catch (JacksonException e) {
// Fallback: try double-parsing for legacy double-encoded data
// This handles data that was stored as JSON strings instead of JSON objects
log.debug("Attempting double-decode fallback for legacy metadata format");
@@ -69,7 +69,7 @@ public class JsonMapConverter implements AttributeConverter,
return objectMapper.readValue(
node.asText(), new TypeReference>() {});
}
- } catch (JsonProcessingException e2) {
+ } catch (JacksonException e2) {
log.error("Failed to parse metadata even with double-decode fallback", e2);
}
diff --git a/app/proprietary/src/main/java/stirling/software/proprietary/storage/model/FileShare.java b/app/proprietary/src/main/java/stirling/software/proprietary/storage/model/FileShare.java
index 1b0fd86f78..6ddd0c8a86 100644
--- a/app/proprietary/src/main/java/stirling/software/proprietary/storage/model/FileShare.java
+++ b/app/proprietary/src/main/java/stirling/software/proprietary/storage/model/FileShare.java
@@ -1,5 +1,6 @@
package stirling.software.proprietary.storage.model;
+import java.io.Serial;
import java.io.Serializable;
import java.time.LocalDateTime;
@@ -46,7 +47,7 @@ import stirling.software.proprietary.security.model.User;
@Setter
public class FileShare implements Serializable {
- private static final long serialVersionUID = 1L;
+ @Serial private static final long serialVersionUID = 1L;
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
diff --git a/app/proprietary/src/main/java/stirling/software/proprietary/storage/model/FileShareAccess.java b/app/proprietary/src/main/java/stirling/software/proprietary/storage/model/FileShareAccess.java
index 49f75a4a4c..cb2f5d5209 100644
--- a/app/proprietary/src/main/java/stirling/software/proprietary/storage/model/FileShareAccess.java
+++ b/app/proprietary/src/main/java/stirling/software/proprietary/storage/model/FileShareAccess.java
@@ -1,5 +1,6 @@
package stirling.software.proprietary.storage.model;
+import java.io.Serial;
import java.io.Serializable;
import java.time.LocalDateTime;
@@ -39,7 +40,7 @@ import stirling.software.proprietary.security.model.User;
@Setter
public class FileShareAccess implements Serializable {
- private static final long serialVersionUID = 1L;
+ @Serial private static final long serialVersionUID = 1L;
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
diff --git a/app/proprietary/src/main/java/stirling/software/proprietary/storage/model/StorageCleanupEntry.java b/app/proprietary/src/main/java/stirling/software/proprietary/storage/model/StorageCleanupEntry.java
index 3158f4c041..68afe20173 100644
--- a/app/proprietary/src/main/java/stirling/software/proprietary/storage/model/StorageCleanupEntry.java
+++ b/app/proprietary/src/main/java/stirling/software/proprietary/storage/model/StorageCleanupEntry.java
@@ -1,5 +1,6 @@
package stirling.software.proprietary.storage.model;
+import java.io.Serial;
import java.io.Serializable;
import java.time.LocalDateTime;
@@ -24,7 +25,7 @@ import lombok.Setter;
@Setter
public class StorageCleanupEntry implements Serializable {
- private static final long serialVersionUID = 1L;
+ @Serial private static final long serialVersionUID = 1L;
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
diff --git a/app/proprietary/src/main/java/stirling/software/proprietary/storage/model/StoredFile.java b/app/proprietary/src/main/java/stirling/software/proprietary/storage/model/StoredFile.java
index db80bd1e91..1b098672b6 100644
--- a/app/proprietary/src/main/java/stirling/software/proprietary/storage/model/StoredFile.java
+++ b/app/proprietary/src/main/java/stirling/software/proprietary/storage/model/StoredFile.java
@@ -1,5 +1,6 @@
package stirling.software.proprietary.storage.model;
+import java.io.Serial;
import java.io.Serializable;
import java.time.LocalDateTime;
import java.util.HashSet;
@@ -45,7 +46,7 @@ import stirling.software.proprietary.workflow.model.WorkflowSession;
@Setter
public class StoredFile implements Serializable {
- private static final long serialVersionUID = 1L;
+ @Serial private static final long serialVersionUID = 1L;
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
diff --git a/app/proprietary/src/main/java/stirling/software/proprietary/storage/model/StoredFileBlob.java b/app/proprietary/src/main/java/stirling/software/proprietary/storage/model/StoredFileBlob.java
index 52ef1107fc..4abcffd3e6 100644
--- a/app/proprietary/src/main/java/stirling/software/proprietary/storage/model/StoredFileBlob.java
+++ b/app/proprietary/src/main/java/stirling/software/proprietary/storage/model/StoredFileBlob.java
@@ -1,5 +1,6 @@
package stirling.software.proprietary.storage.model;
+import java.io.Serial;
import java.io.Serializable;
import jakarta.persistence.Column;
@@ -19,7 +20,7 @@ import lombok.Setter;
@Setter
public class StoredFileBlob implements Serializable {
- private static final long serialVersionUID = 1L;
+ @Serial private static final long serialVersionUID = 1L;
@Id
@Column(name = "storage_key", nullable = false, length = 128)
diff --git a/app/proprietary/src/main/java/stirling/software/proprietary/web/AuditWebFilter.java b/app/proprietary/src/main/java/stirling/software/proprietary/web/AuditWebFilter.java
index b6f5b47f3b..70847a0702 100644
--- a/app/proprietary/src/main/java/stirling/software/proprietary/web/AuditWebFilter.java
+++ b/app/proprietary/src/main/java/stirling/software/proprietary/web/AuditWebFilter.java
@@ -7,6 +7,7 @@ import org.slf4j.MDC;
import org.springframework.core.Ordered;
import org.springframework.core.annotation.Order;
import org.springframework.security.core.Authentication;
+import org.springframework.security.core.GrantedAuthority;
import org.springframework.security.core.context.SecurityContextHolder;
import org.springframework.stereotype.Component;
import org.springframework.web.filter.OncePerRequestFilter;
@@ -64,7 +65,7 @@ public class AuditWebFilter extends OncePerRequestFilter {
if (auth != null && auth.getAuthorities() != null) {
String roles =
auth.getAuthorities().stream()
- .map(a -> a.getAuthority())
+ .map(GrantedAuthority::getAuthority)
.reduce((a, b) -> a + "," + b)
.orElse("");
MDC.put("userRoles", roles);
diff --git a/app/proprietary/src/main/java/stirling/software/proprietary/workflow/controller/SigningSessionController.java b/app/proprietary/src/main/java/stirling/software/proprietary/workflow/controller/SigningSessionController.java
index 4e95707217..b224a09841 100644
--- a/app/proprietary/src/main/java/stirling/software/proprietary/workflow/controller/SigningSessionController.java
+++ b/app/proprietary/src/main/java/stirling/software/proprietary/workflow/controller/SigningSessionController.java
@@ -20,8 +20,6 @@ import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.multipart.MultipartFile;
import org.springframework.web.server.ResponseStatusException;
-import com.fasterxml.jackson.databind.ObjectMapper;
-
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
@@ -39,11 +37,14 @@ import stirling.software.proprietary.workflow.dto.CertificateInfo;
import stirling.software.proprietary.workflow.dto.CertificateValidationResponse;
import stirling.software.proprietary.workflow.dto.ParticipantRequest;
import stirling.software.proprietary.workflow.dto.WorkflowCreationRequest;
+import stirling.software.proprietary.workflow.model.WorkflowParticipant;
import stirling.software.proprietary.workflow.model.WorkflowSession;
import stirling.software.proprietary.workflow.service.CertificateSubmissionValidator;
import stirling.software.proprietary.workflow.service.SigningFinalizationService;
import stirling.software.proprietary.workflow.service.WorkflowSessionService;
+import tools.jackson.databind.ObjectMapper;
+
@Slf4j
@RestController
@RequestMapping("/api/v1/security")
@@ -259,7 +260,9 @@ public class SigningSessionController {
+ "database until manual cleanup.",
sessionId,
session.getParticipants() != null
- ? session.getParticipants().stream().map(p -> p.getEmail()).toList()
+ ? session.getParticipants().stream()
+ .map(WorkflowParticipant::getEmail)
+ .toList()
: "unknown",
e);
throw new ResponseStatusException(
diff --git a/app/proprietary/src/main/java/stirling/software/proprietary/workflow/controller/WorkflowParticipantController.java b/app/proprietary/src/main/java/stirling/software/proprietary/workflow/controller/WorkflowParticipantController.java
index 5f903e4b56..4df0c93e1d 100644
--- a/app/proprietary/src/main/java/stirling/software/proprietary/workflow/controller/WorkflowParticipantController.java
+++ b/app/proprietary/src/main/java/stirling/software/proprietary/workflow/controller/WorkflowParticipantController.java
@@ -5,6 +5,7 @@ import java.nio.charset.StandardCharsets;
import java.time.ZoneOffset;
import java.time.format.DateTimeFormatter;
import java.util.HashMap;
+import java.util.List;
import java.util.Map;
import org.springframework.http.ContentDisposition;
@@ -429,7 +430,7 @@ public class WorkflowParticipantController {
java.util.List> wetSigs =
objectMapper.readValue(
request.getWetSignaturesData(),
- new TypeReference>>() {});
+ new TypeReference>>() {});
if (wetSigs.size() > WetSignatureMetadata.MAX_SIGNATURES_PER_PARTICIPANT) {
throw new ResponseStatusException(
HttpStatus.BAD_REQUEST, "Too many wet signatures submitted");
diff --git a/app/proprietary/src/main/java/stirling/software/proprietary/workflow/model/WorkflowParticipant.java b/app/proprietary/src/main/java/stirling/software/proprietary/workflow/model/WorkflowParticipant.java
index 2e6091b963..b119565c13 100644
--- a/app/proprietary/src/main/java/stirling/software/proprietary/workflow/model/WorkflowParticipant.java
+++ b/app/proprietary/src/main/java/stirling/software/proprietary/workflow/model/WorkflowParticipant.java
@@ -1,5 +1,6 @@
package stirling.software.proprietary.workflow.model;
+import java.io.Serial;
import java.io.Serializable;
import java.time.LocalDateTime;
import java.util.ArrayList;
@@ -51,7 +52,7 @@ import stirling.software.proprietary.storage.model.ShareAccessRole;
@Setter
public class WorkflowParticipant implements Serializable {
- private static final long serialVersionUID = 1L;
+ @Serial private static final long serialVersionUID = 1L;
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
diff --git a/app/proprietary/src/main/java/stirling/software/proprietary/workflow/model/WorkflowSession.java b/app/proprietary/src/main/java/stirling/software/proprietary/workflow/model/WorkflowSession.java
index 3fc6b53b44..7df5af710f 100644
--- a/app/proprietary/src/main/java/stirling/software/proprietary/workflow/model/WorkflowSession.java
+++ b/app/proprietary/src/main/java/stirling/software/proprietary/workflow/model/WorkflowSession.java
@@ -1,5 +1,6 @@
package stirling.software.proprietary.workflow.model;
+import java.io.Serial;
import java.io.Serializable;
import java.time.LocalDateTime;
import java.util.ArrayList;
@@ -53,7 +54,7 @@ import stirling.software.proprietary.storage.model.StoredFile;
@Setter
public class WorkflowSession implements Serializable {
- private static final long serialVersionUID = 1L;
+ @Serial private static final long serialVersionUID = 1L;
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
diff --git a/app/proprietary/src/main/java/stirling/software/proprietary/workflow/service/SigningFinalizationService.java b/app/proprietary/src/main/java/stirling/software/proprietary/workflow/service/SigningFinalizationService.java
index e5e122df45..3fce8c69dd 100644
--- a/app/proprietary/src/main/java/stirling/software/proprietary/workflow/service/SigningFinalizationService.java
+++ b/app/proprietary/src/main/java/stirling/software/proprietary/workflow/service/SigningFinalizationService.java
@@ -217,16 +217,13 @@ public class SigningFinalizationService {
wetSignatures.size(),
session.getSessionId());
- PDDocument document = pdfDocumentFactory.load(new ByteArrayInputStream(pdfBytes));
- try {
+ try (PDDocument document = pdfDocumentFactory.load(new ByteArrayInputStream(pdfBytes))) {
for (WetSignatureMetadata wetSig : wetSignatures) {
applyWetSignatureToPage(document, wetSig);
}
ByteArrayOutputStream baos = new ByteArrayOutputStream();
document.save(baos);
return baos.toByteArray();
- } finally {
- document.close();
}
}
@@ -242,11 +239,10 @@ public class SigningFinalizationService {
}
PDPage page = document.getPage(pageIndex);
- PDPageContentStream contentStream =
- new PDPageContentStream(
- document, page, PDPageContentStream.AppendMode.APPEND, true, true);
- try {
+ try (PDPageContentStream contentStream =
+ new PDPageContentStream(
+ document, page, PDPageContentStream.AppendMode.APPEND, true, true)) {
// Use WetSignatureMetadata.extractBase64Data() to strip data URL prefix
String base64Data = wetSig.extractBase64Data();
if (base64Data == null || base64Data.isBlank()) {
@@ -279,8 +275,6 @@ public class SigningFinalizationService {
pdfY,
width,
height);
- } finally {
- contentStream.close();
}
}
diff --git a/app/proprietary/src/main/java/stirling/software/proprietary/workflow/service/WorkflowSessionService.java b/app/proprietary/src/main/java/stirling/software/proprietary/workflow/service/WorkflowSessionService.java
index 4c60c60df2..a2db5deb5a 100644
--- a/app/proprietary/src/main/java/stirling/software/proprietary/workflow/service/WorkflowSessionService.java
+++ b/app/proprietary/src/main/java/stirling/software/proprietary/workflow/service/WorkflowSessionService.java
@@ -954,21 +954,22 @@ public class WorkflowSessionService {
Object pemObject = pemParser.readObject();
JcaPEMKeyConverter converter = new JcaPEMKeyConverter().setProvider("BC");
PrivateKeyInfo keyInfo;
- if (pemObject instanceof PKCS8EncryptedPrivateKeyInfo encrypted) {
- InputDecryptorProvider decryptor =
- new JceOpenSSLPKCS8DecryptorProviderBuilder().build(password);
- keyInfo = encrypted.decryptPrivateKeyInfo(decryptor);
- } else if (pemObject instanceof PEMEncryptedKeyPair encryptedKeyPair) {
- PEMDecryptorProvider decryptor =
- new JcePEMDecryptorProviderBuilder().build(password);
- keyInfo = encryptedKeyPair.decryptKeyPair(decryptor).getPrivateKeyInfo();
- } else if (pemObject instanceof PEMKeyPair keyPair) {
- keyInfo = keyPair.getPrivateKeyInfo();
- } else if (pemObject instanceof PrivateKeyInfo info) {
- keyInfo = info;
- } else {
- throw new ResponseStatusException(
- HttpStatus.BAD_REQUEST, "Unsupported PEM private key format");
+ switch (pemObject) {
+ case PKCS8EncryptedPrivateKeyInfo encrypted -> {
+ InputDecryptorProvider decryptor =
+ new JceOpenSSLPKCS8DecryptorProviderBuilder().build(password);
+ keyInfo = encrypted.decryptPrivateKeyInfo(decryptor);
+ }
+ case PEMEncryptedKeyPair encryptedKeyPair -> {
+ PEMDecryptorProvider decryptor =
+ new JcePEMDecryptorProviderBuilder().build(password);
+ keyInfo = encryptedKeyPair.decryptKeyPair(decryptor).getPrivateKeyInfo();
+ }
+ case PEMKeyPair keyPair -> keyInfo = keyPair.getPrivateKeyInfo();
+ case PrivateKeyInfo info -> keyInfo = info;
+ case null, default ->
+ throw new ResponseStatusException(
+ HttpStatus.BAD_REQUEST, "Unsupported PEM private key format");
}
return converter.getPrivateKey(keyInfo);
}
diff --git a/app/proprietary/src/main/java/stirling/software/proprietary/workflow/util/WorkflowMapper.java b/app/proprietary/src/main/java/stirling/software/proprietary/workflow/util/WorkflowMapper.java
index b2f53c2824..8d61ae032c 100644
--- a/app/proprietary/src/main/java/stirling/software/proprietary/workflow/util/WorkflowMapper.java
+++ b/app/proprietary/src/main/java/stirling/software/proprietary/workflow/util/WorkflowMapper.java
@@ -4,14 +4,14 @@ import java.util.ArrayList;
import java.util.List;
import java.util.Map;
-import com.fasterxml.jackson.databind.ObjectMapper;
-
import stirling.software.proprietary.workflow.dto.ParticipantResponse;
import stirling.software.proprietary.workflow.dto.WetSignatureMetadata;
import stirling.software.proprietary.workflow.dto.WorkflowSessionResponse;
import stirling.software.proprietary.workflow.model.WorkflowParticipant;
import stirling.software.proprietary.workflow.model.WorkflowSession;
+import tools.jackson.databind.ObjectMapper;
+
/**
* Utility class for mapping workflow entities to DTOs. Centralizes conversion logic for consistent
* API responses.
diff --git a/app/proprietary/src/test/java/stirling/software/proprietary/accountlink/AccountLinkClientTest.java b/app/proprietary/src/test/java/stirling/software/proprietary/accountlink/AccountLinkClientTest.java
index 969111e9f5..2bce17d732 100644
--- a/app/proprietary/src/test/java/stirling/software/proprietary/accountlink/AccountLinkClientTest.java
+++ b/app/proprietary/src/test/java/stirling/software/proprietary/accountlink/AccountLinkClientTest.java
@@ -21,9 +21,9 @@ import org.mockito.ArgumentCaptor;
import tools.jackson.databind.ObjectMapper;
/**
- * Stubs the {@link HttpClient} so the SaaS endpoint is never actually called. Confirms register
- * relays the JWT and parses the credential, and that entitlement parsing + the fail-open (null on
- * unreachable) behaviour hold.
+ * Stubs the {@link HttpClient} so the SaaS endpoint is never actually called. Confirms the connect
+ * handshake refuses an authorize URL it would not navigate to and carries no user token, and that
+ * entitlement parsing + the fail-open (null on unreachable) behaviour hold.
*/
class AccountLinkClientTest {
@@ -48,39 +48,79 @@ class AccountLinkClientTest {
return resp;
}
+ // register() is gone with the JWT relay, and with it the two tests that asserted this client
+ // sends an Authorization: Bearer header. Nothing here carries a user token any more.
+
@Test
@SuppressWarnings("unchecked")
- void registerRelaysJwtAndParsesCredential() throws Exception {
- // Build the stub response first: nesting response() inside when() trips Mockito's
- // unfinished-stubbing check (inner when() runs mid outer when()).
+ void connectRequestRefusesAnAuthorizeUrlItWouldNotNavigateTo() throws Exception {
+ // The reply drives a browser navigation, so a non-absolute or non-http(s) value must fail
+ // loudly here rather than reach the admin.
HttpResponse resp =
- response(201, "{\"deviceId\":\"dev-1\",\"deviceSecret\":\"sec-1\",\"teamId\":42}");
- ArgumentCaptor captor = ArgumentCaptor.forClass(HttpRequest.class);
- when(httpClient.send(captor.capture(), any(HttpResponse.BodyHandler.class)))
- .thenReturn(resp);
+ response(201, "{\"requestId\":\"req-1\",\"authorizeUrl\":\"/link?request=req-1\"}");
+ when(httpClient.send(any(), any(HttpResponse.BodyHandler.class))).thenReturn(resp);
- AccountLinkClient.RegisterResult result = client.register("jwt-token", "My Server");
-
- assertEquals("dev-1", result.deviceId());
- assertEquals("sec-1", result.deviceSecret());
- assertEquals(42L, result.teamId());
-
- HttpRequest sent = captor.getValue();
- assertEquals("Bearer jwt-token", sent.headers().firstValue("Authorization").orElse(null));
- assertEquals(
- "https://saas.example.com/api/v1/account-link/register", sent.uri().toString());
+ assertThrows(
+ java.io.IOException.class,
+ () -> client.connectRequest("n", "https://pdf.example.com/cb", "nonce", "secret"));
}
@Test
@SuppressWarnings("unchecked")
- void registerThrowsUpstreamExceptionWithStatusOnNon2xx() throws Exception {
- HttpResponse resp = response(401, "{\"error\":\"unauthorized\"}");
+ void connectRequestParsesTheAuthorizeUrlItIsGiven() throws Exception {
+ HttpResponse resp =
+ response(
+ 201,
+ "{\"requestId\":\"req-1\",\"expiresIn\":900,"
+ + "\"authorizeUrl\":\"https://app.example.com/link?request=req-1\"}");
+ ArgumentCaptor captor = ArgumentCaptor.forClass(HttpRequest.class);
+ when(httpClient.send(captor.capture(), any(HttpResponse.BodyHandler.class)))
+ .thenReturn(resp);
+
+ AccountLinkClient.ConnectRequestResult result =
+ client.connectRequest("n", "https://pdf.example.com/cb", "nonce", "secret");
+
+ assertEquals("req-1", result.requestId());
+ assertEquals("https://app.example.com/link?request=req-1", result.authorizeUrl());
+ // No user token on this call, by design.
+ assertEquals(null, captor.getValue().headers().firstValue("Authorization").orElse(null));
+ }
+
+ @Test
+ @SuppressWarnings("unchecked")
+ void connectClaimGrantsTheCredentialOnSuccess() throws Exception {
+ HttpResponse resp =
+ response(200, "{\"deviceId\":\"dev-1\",\"deviceSecret\":\"sec-1\",\"teamId\":7}");
when(httpClient.send(any(), any(HttpResponse.BodyHandler.class))).thenReturn(resp);
- AccountLinkClient.UpstreamException ex =
- assertThrows(
- AccountLinkClient.UpstreamException.class,
- () -> client.register("jwt", null));
- assertEquals(401, ex.status());
+
+ AccountLinkClient.ConnectClaimResult result = client.connectClaim("req-1", "secret");
+
+ assertEquals(AccountLinkClient.ConnectClaimOutcome.GRANTED, result.outcome());
+ assertEquals("dev-1", result.deviceId());
+ assertEquals("sec-1", result.deviceSecret());
+ }
+
+ @Test
+ @SuppressWarnings("unchecked")
+ void connectClaimMapsTheStatusItIsGiven() throws Exception {
+ // The whole point of these four: a claim consumes the request server-side, so
+ // reading 200 as anything but success loses the credential irrecoverably.
+ assertEquals(AccountLinkClient.ConnectClaimOutcome.PENDING, claimOutcome(202, "{}"));
+ assertEquals(AccountLinkClient.ConnectClaimOutcome.UNAVAILABLE, claimOutcome(503, "{}"));
+ assertEquals(AccountLinkClient.ConnectClaimOutcome.REJECTED, claimOutcome(400, "{}"));
+ assertEquals(
+ AccountLinkClient.ConnectClaimOutcome.CONFIRMED,
+ claimOutcome(200, "{\"status\":\"confirmed\",\"teamId\":7}"));
+ }
+
+ @SuppressWarnings("unchecked")
+ private AccountLinkClient.ConnectClaimOutcome claimOutcome(int status, String body)
+ throws Exception {
+ // Built before the when(), not inside it: response() stubs a mock of its own, and
+ // Mockito cannot have that happen mid-stubbing.
+ HttpResponse resp = response(status, body);
+ when(httpClient.send(any(), any(HttpResponse.BodyHandler.class))).thenReturn(resp);
+ return client.connectClaim("req-1", "secret").outcome();
}
@Test
diff --git a/app/proprietary/src/test/java/stirling/software/proprietary/accountlink/AccountLinkControllerTest.java b/app/proprietary/src/test/java/stirling/software/proprietary/accountlink/AccountLinkControllerTest.java
index 41f544de7e..6e13021a40 100644
--- a/app/proprietary/src/test/java/stirling/software/proprietary/accountlink/AccountLinkControllerTest.java
+++ b/app/proprietary/src/test/java/stirling/software/proprietary/accountlink/AccountLinkControllerTest.java
@@ -1,6 +1,7 @@
package stirling.software.proprietary.accountlink;
import static org.assertj.core.api.Assertions.assertThat;
+import static org.mockito.ArgumentMatchers.any;
import static org.mockito.Mockito.mock;
import static org.mockito.Mockito.never;
import static org.mockito.Mockito.verify;
@@ -14,16 +15,15 @@ import org.springframework.beans.factory.ObjectProvider;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
-import stirling.software.proprietary.accountlink.AccountLinkController.LinkRequest;
-
/**
- * The local (self-hosted) account-link controller's error mapping: an upstream auth rejection
- * surfaces as 401/403 (so the portal can prompt a re-sign-in) while other upstream / transport
- * faults are a 502.
+ * The local (self-hosted) account-link controller's error mapping. Every upstream or transport
+ * failure is a 502, and the response body never echoes the exception, because a DNS or TLS message
+ * can carry the configured SaaS host.
*/
class AccountLinkControllerTest {
private AccountLinkService service;
+ private ConnectService connectService;
private UsageSyncService syncService;
private ObjectProvider syncProvider;
private AccountLinkController controller;
@@ -32,47 +32,54 @@ class AccountLinkControllerTest {
@SuppressWarnings("unchecked")
void setUp() {
service = mock(AccountLinkService.class);
+ connectService = mock(ConnectService.class);
syncService = mock(UsageSyncService.class);
syncProvider = mock(ObjectProvider.class);
controller =
- new AccountLinkController(service, mock(LocalUsageService.class), syncProvider);
+ new AccountLinkController(
+ service, connectService, mock(LocalUsageService.class), syncProvider);
}
- @Test
- void link_missingJwt_returns400() {
- ResponseEntity resp = controller.link(new LinkRequest(" ", null));
- assertThat(resp.getStatusCode()).isEqualTo(HttpStatus.BAD_REQUEST);
- }
+ // These asserted POST /link's error mapping, which distinguished 401/403 so the portal could
+ // prompt a re-sign-in. That endpoint is gone with the JWT relay, and the distinction went with
+ // it: connect/start carries no user token, so an upstream refusal is never the admin's session
+ // and everything non-transport is a plain gateway failure.
@Test
- void link_upstreamUnauthorized_maps401() throws Exception {
- when(service.link("jwt", null))
- .thenThrow(new AccountLinkClient.UpstreamException(401, "bad token"));
- ResponseEntity resp = controller.link(new LinkRequest("jwt", null));
- assertThat(resp.getStatusCode()).isEqualTo(HttpStatus.UNAUTHORIZED);
- }
-
- @Test
- void link_upstreamForbidden_maps403() throws Exception {
- when(service.link("jwt", null))
- .thenThrow(new AccountLinkClient.UpstreamException(403, "forbidden"));
- ResponseEntity resp = controller.link(new LinkRequest("jwt", null));
- assertThat(resp.getStatusCode()).isEqualTo(HttpStatus.FORBIDDEN);
- }
-
- @Test
- void link_upstreamServerError_maps502() throws Exception {
- when(service.link("jwt", null))
+ void connectStart_upstreamFailure_maps502() throws Exception {
+ when(connectService.start(any(), any()))
.thenThrow(new AccountLinkClient.UpstreamException(500, "boom"));
- ResponseEntity resp = controller.link(new LinkRequest("jwt", null));
+
+ ResponseEntity resp = controller.connectStart(null, request());
+
assertThat(resp.getStatusCode()).isEqualTo(HttpStatus.BAD_GATEWAY);
}
@Test
- void link_transportFailure_maps502() throws Exception {
- when(service.link("jwt", null)).thenThrow(new IOException("connection refused"));
- ResponseEntity resp = controller.link(new LinkRequest("jwt", null));
+ void connectStart_transportFailure_maps502WithoutLeakingTheHost() throws Exception {
+ when(connectService.start(any(), any()))
+ .thenThrow(new IOException("connection refused to saas.internal:8081"));
+
+ ResponseEntity resp = controller.connectStart(null, request());
+
assertThat(resp.getStatusCode()).isEqualTo(HttpStatus.BAD_GATEWAY);
+ // The body must not echo the exception: a DNS/TLS message can carry the configured SaaS
+ // host.
+ assertThat(String.valueOf(resp.getBody())).doesNotContain("saas.internal");
+ }
+
+ @Test
+ void connectReauth_onAnUnlinkedServer_maps502() throws Exception {
+ when(connectService.startReauth(any())).thenThrow(new IOException("not linked"));
+
+ ResponseEntity resp = controller.connectReauth(null, request());
+
+ assertThat(resp.getStatusCode()).isEqualTo(HttpStatus.BAD_GATEWAY);
+ }
+
+ /** Minimal request: the controller only reads Origin and the forwarded/host details from it. */
+ private static jakarta.servlet.http.HttpServletRequest request() {
+ return new org.springframework.mock.web.MockHttpServletRequest();
}
@Test
diff --git a/app/proprietary/src/test/java/stirling/software/proprietary/accountlink/AccountLinkServiceTest.java b/app/proprietary/src/test/java/stirling/software/proprietary/accountlink/AccountLinkServiceTest.java
index b909fb37a0..410ef8a8c7 100644
--- a/app/proprietary/src/test/java/stirling/software/proprietary/accountlink/AccountLinkServiceTest.java
+++ b/app/proprietary/src/test/java/stirling/software/proprietary/accountlink/AccountLinkServiceTest.java
@@ -3,12 +3,10 @@ package stirling.software.proprietary.accountlink;
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.ArgumentMatchers.any;
import static org.mockito.Mockito.mock;
import static org.mockito.Mockito.verify;
import static org.mockito.Mockito.when;
-import java.io.IOException;
import java.time.LocalDateTime;
import java.util.Optional;
@@ -30,33 +28,25 @@ class AccountLinkServiceTest {
service = new AccountLinkService(client, store, cache);
}
+ // The two link() tests here are gone with the JWT relay. Storing a credential and invalidating
+ // the entitlement cache is now ConnectService's job and is covered by ConnectServiceTest; what
+ // remains in this service is status and unlink.
+
@Test
- void link_storesCredentialAndInvalidatesCache() throws IOException {
- when(client.register("jwt", "name"))
- .thenReturn(new AccountLinkClient.RegisterResult("dev-1", "sec-1", 7L));
+ void status_linkedFromTheStoredCredential() {
DeviceCredential stored = new DeviceCredential();
stored.setDeviceId("dev-1");
stored.setTeamId(7L);
stored.setLinkedAt(LocalDateTime.now());
when(store.get()).thenReturn(Optional.of(stored));
- AccountLinkService.LinkStatus status = service.link("jwt", "name");
+ AccountLinkService.LinkStatus status = service.status();
- verify(store).save("dev-1", "sec-1", 7L);
- verify(cache).invalidate();
assertTrue(status.linked());
assertEquals("dev-1", status.deviceId());
assertEquals(7L, status.teamId());
}
- @Test
- void link_propagatesRegisterFailure() throws IOException {
- when(client.register(any(), any())).thenThrow(new IOException("boom"));
- org.junit.jupiter.api.Assertions.assertThrows(
- IOException.class, () -> service.link("jwt", null));
- verify(cache, org.mockito.Mockito.never()).invalidate();
- }
-
@Test
void status_unlinkedWhenNoCredential() {
when(store.get()).thenReturn(Optional.empty());
diff --git a/app/proprietary/src/test/java/stirling/software/proprietary/accountlink/ConnectServiceTest.java b/app/proprietary/src/test/java/stirling/software/proprietary/accountlink/ConnectServiceTest.java
new file mode 100644
index 0000000000..5e040e4ad7
--- /dev/null
+++ b/app/proprietary/src/test/java/stirling/software/proprietary/accountlink/ConnectServiceTest.java
@@ -0,0 +1,408 @@
+package stirling.software.proprietary.accountlink;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.anyString;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.verifyNoInteractions;
+import static org.mockito.Mockito.when;
+
+import java.time.LocalDateTime;
+import java.util.Optional;
+
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.ArgumentCaptor;
+import org.mockito.Mock;
+import org.mockito.junit.jupiter.MockitoExtension;
+import org.mockito.junit.jupiter.MockitoSettings;
+import org.mockito.quality.Strictness;
+
+import stirling.software.common.model.ApplicationProperties;
+import stirling.software.proprietary.accountlink.AccountLinkClient.ConnectClaimOutcome;
+import stirling.software.proprietary.accountlink.AccountLinkClient.ConnectClaimResult;
+import stirling.software.proprietary.accountlink.AccountLinkClient.ConnectRequestResult;
+import stirling.software.proprietary.accountlink.ConnectService.Phase;
+
+/** Unit tests for the instance half of the connect handshake. */
+@ExtendWith(MockitoExtension.class)
+@MockitoSettings(strictness = Strictness.LENIENT)
+class ConnectServiceTest {
+
+ private static final String NONCE = "the-nonce";
+ private static final String CLAIM_SECRET = "the-claim-secret";
+ private static final String AUTHORIZE_URL = "https://app.example.com/link?request=req-1";
+
+ @Mock private AccountLinkClient client;
+ @Mock private ConnectStateRepository stateRepo;
+ @Mock private DeviceCredentialStore credentialStore;
+ @Mock private EntitlementCache entitlementCache;
+
+ private ApplicationProperties applicationProperties;
+ private ConnectService service;
+
+ @BeforeEach
+ void setUp() {
+ applicationProperties = new ApplicationProperties();
+ service =
+ new ConnectService(
+ client,
+ stateRepo,
+ credentialStore,
+ entitlementCache,
+ applicationProperties);
+ }
+
+ private void configureFrontendUrl(String url) {
+ applicationProperties.getSystem().setFrontendUrl(url);
+ }
+
+ @Test
+ void start_advertisesTheConfiguredFrontendUrlInPreferenceToTheRequest() throws Exception {
+ configureFrontendUrl("https://pdf.example.com/");
+ stubCreate();
+
+ service.start("prod-1", fromRequest("http://10.0.0.5:8080"));
+
+ verify(client)
+ .connectRequest(
+ anyString(),
+ // Trailing slash trimmed, and the request's own view ignored.
+ org.mockito.ArgumentMatchers.eq(
+ "https://pdf.example.com" + ConnectService.CALLBACK_PATH),
+ anyString(),
+ anyString(),
+ // A first link carries no credential; that is what makes it a first link.
+ org.mockito.ArgumentMatchers.isNull());
+ }
+
+ @Test
+ void start_fallsBackToTheAddressTheRequestArrivedOn() throws Exception {
+ stubCreate();
+
+ service.start(null, fromRequest("https://pdf.internal:8443/stirling"));
+
+ ArgumentCaptor callback = ArgumentCaptor.forClass(String.class);
+ verify(client).connectRequest(any(), callback.capture(), anyString(), anyString(), any());
+ // Context path preserved, so a subpath deployment gets a callback that resolves.
+ assertThat(callback.getValue())
+ .isEqualTo("https://pdf.internal:8443/stirling" + ConnectService.CALLBACK_PATH);
+ }
+
+ @Test
+ void start_withNoAddressAtAllFailsRatherThanGuessing() {
+ assertThat(catchIo(() -> service.start(null, fromRequest(null))))
+ .hasMessageContaining("system.frontendUrl");
+ verifyNoInteractions(client);
+ }
+
+ @Test
+ void resolveCallback_honoursThePortalsOwnCallbackWhenTheBrowserOriginAgrees() {
+ // The frontend is the only party that knows its router's base path.
+ String requested = "http://localhost:5173/app/account-link/callback";
+
+ assertThat(
+ service.resolveCallbackUrl(
+ new ConnectService.CallbackHint(
+ requested,
+ "http://localhost:5173",
+ "http://localhost:8080")))
+ .isEqualTo(requested);
+ }
+
+ @Test
+ void resolveCallback_ignoresACallbackFromADifferentOrigin() {
+ assertThat(
+ service.resolveCallbackUrl(
+ new ConnectService.CallbackHint(
+ "https://evil.example.com/steal",
+ "http://localhost:5173",
+ "http://localhost:8080")))
+ .isEqualTo("http://localhost:5173" + ConnectService.CALLBACK_PATH);
+ }
+
+ @Test
+ void resolveCallback_prefersTheBrowserOriginOverTheApiRequest() {
+ // The whole point: :5173 is where the admin is, :8080 is where the call landed.
+ assertThat(
+ service.resolveCallbackUrl(
+ new ConnectService.CallbackHint(
+ null, "http://localhost:5173", "http://localhost:8080")))
+ .isEqualTo("http://localhost:5173" + ConnectService.CALLBACK_PATH);
+ }
+
+ @Test
+ void resolveCallback_letsConfigurationBeatEverything() {
+ configureFrontendUrl("https://pdf.example.com/");
+
+ assertThat(
+ service.resolveCallbackUrl(
+ new ConnectService.CallbackHint(
+ "http://localhost:5173/account-link/callback",
+ "http://localhost:5173",
+ "http://localhost:8080")))
+ .isEqualTo("https://pdf.example.com" + ConnectService.CALLBACK_PATH);
+ }
+
+ @Test
+ void resolveCallback_ignoresAnUnusableOriginHeader() {
+ // "null" is what a browser sends for an opaque origin; it must not become a callback.
+ assertThat(
+ service.resolveCallbackUrl(
+ new ConnectService.CallbackHint(
+ null, "null", "http://localhost:8080")))
+ .isEqualTo("http://localhost:8080" + ConnectService.CALLBACK_PATH);
+ }
+
+ @Test
+ void start_sendsTheAdminWhereverSaaSSaidToSendThem() throws Exception {
+ stubCreate();
+
+ ConnectService.ConnectStatus status =
+ service.start(null, fromRequest("https://pdf.example.com"));
+
+ assertThat(status.phase()).isEqualTo(Phase.PENDING);
+ // Not composed here: only the SaaS side knows where its approval page lives, so an
+ // instance configuring that could only get it wrong.
+ assertThat(status.authorizeUrl()).isEqualTo(AUTHORIZE_URL);
+ }
+
+ @Test
+ void start_keepsTheNonceAndClaimSecretItSent() throws Exception {
+ stubCreate();
+
+ service.start(null, fromRequest("https://pdf.example.com"));
+
+ ArgumentCaptor nonce = ArgumentCaptor.forClass(String.class);
+ ArgumentCaptor secret = ArgumentCaptor.forClass(String.class);
+ verify(client).connectRequest(any(), anyString(), nonce.capture(), secret.capture(), any());
+
+ ArgumentCaptor saved = ArgumentCaptor.forClass(ConnectState.class);
+ verify(stateRepo).save(saved.capture());
+ assertThat(saved.getValue().getNonce()).isEqualTo(nonce.getValue());
+ assertThat(saved.getValue().getClaimSecret()).isEqualTo(secret.getValue());
+ // Two independent secrets, not one value used twice.
+ assertThat(nonce.getValue()).isNotEqualTo(secret.getValue());
+ }
+
+ @Test
+ void start_whenAlreadyLinkedDoesNothing() throws Exception {
+ when(credentialStore.isLinked()).thenReturn(true);
+ when(credentialStore.get()).thenReturn(Optional.of(credential(7L)));
+
+ ConnectService.ConnectStatus status =
+ service.start(null, fromRequest("https://pdf.example.com"));
+
+ assertThat(status.phase()).isEqualTo(Phase.LINKED);
+ verifyNoInteractions(client);
+ verify(stateRepo, never()).save(any());
+ }
+
+ @Test
+ void complete_withTheRightNonceStoresTheCredentialAndClearsTheHandshake() {
+ ConnectState state = openHandshake();
+ when(stateRepo.findById(ConnectState.SINGLETON_ID)).thenReturn(Optional.of(state));
+ when(client.connectClaim("req-1", CLAIM_SECRET))
+ .thenReturn(new ConnectClaimResult(ConnectClaimOutcome.GRANTED, "dev", "sec", 7L));
+
+ ConnectService.ConnectStatus status = service.complete(NONCE);
+
+ assertThat(status.phase()).isEqualTo(Phase.LINKED);
+ assertThat(status.teamId()).isEqualTo(7L);
+ verify(credentialStore).save("dev", "sec", 7L);
+ verify(entitlementCache).invalidate();
+ verify(stateRepo).delete(state);
+ }
+
+ @Test
+ void complete_withAWrongNonceClaimsNothingAndLeavesTheHandshakeAlone() {
+ ConnectState state = openHandshake();
+ when(stateRepo.findById(ConnectState.SINGLETON_ID)).thenReturn(Optional.of(state));
+
+ ConnectService.ConnectStatus status = service.complete("not-the-nonce");
+
+ assertThat(status.phase()).isEqualTo(Phase.REJECTED);
+ // The important half: an unverified caller cannot cancel a legitimate handshake.
+ verify(stateRepo, never()).delete(any());
+ verifyNoInteractions(credentialStore);
+ verify(client, never()).connectClaim(anyString(), anyString());
+ }
+
+ @Test
+ void complete_withNoNonceAtAllIsRejected() {
+ when(stateRepo.findById(ConnectState.SINGLETON_ID))
+ .thenReturn(Optional.of(openHandshake()));
+
+ assertThat(service.complete(null).phase()).isEqualTo(Phase.REJECTED);
+ verify(client, never()).connectClaim(anyString(), anyString());
+ }
+
+ @Test
+ void complete_whenSaaSHasNotCommittedTheApprovalKeepsTheHandshake() {
+ when(stateRepo.findById(ConnectState.SINGLETON_ID))
+ .thenReturn(Optional.of(openHandshake()));
+ when(client.connectClaim(anyString(), anyString()))
+ .thenReturn(ConnectClaimResult.of(ConnectClaimOutcome.PENDING));
+
+ assertThat(service.complete(NONCE).phase()).isEqualTo(Phase.PENDING);
+ verify(stateRepo, never()).delete(any());
+ }
+
+ @Test
+ void complete_whenSaaSIsUnreachableKeepsTheHandshakeForARetry() {
+ when(stateRepo.findById(ConnectState.SINGLETON_ID))
+ .thenReturn(Optional.of(openHandshake()));
+ when(client.connectClaim(anyString(), anyString()))
+ .thenReturn(ConnectClaimResult.of(ConnectClaimOutcome.UNAVAILABLE));
+
+ assertThat(service.complete(NONCE).phase()).isEqualTo(Phase.UNAVAILABLE);
+ verify(stateRepo, never()).delete(any());
+ verifyNoInteractions(credentialStore);
+ }
+
+ @Test
+ void complete_whenDeclinedClearsTheHandshake() {
+ ConnectState state = openHandshake();
+ when(stateRepo.findById(ConnectState.SINGLETON_ID)).thenReturn(Optional.of(state));
+ when(client.connectClaim(anyString(), anyString()))
+ .thenReturn(ConnectClaimResult.of(ConnectClaimOutcome.REJECTED));
+
+ assertThat(service.complete(NONCE).phase()).isEqualTo(Phase.REJECTED);
+ verify(stateRepo).delete(state);
+ verifyNoInteractions(credentialStore);
+ }
+
+ @Test
+ void complete_onAnExpiredHandshakeClearsItWithoutClaiming() {
+ ConnectState state = openHandshake();
+ state.setExpiresAt(LocalDateTime.now().minusSeconds(1));
+ when(stateRepo.findById(ConnectState.SINGLETON_ID)).thenReturn(Optional.of(state));
+
+ assertThat(service.complete(NONCE).phase()).isEqualTo(Phase.EXPIRED);
+ verify(stateRepo).delete(state);
+ verify(client, never()).connectClaim(anyString(), anyString());
+ }
+
+ @Test
+ void startReauth_presentsTheCredentialSoSaaSCanPinTheTeam() throws Exception {
+ when(credentialStore.get()).thenReturn(Optional.of(credential(7L)));
+ when(client.connectRequest(any(), anyString(), anyString(), anyString(), any()))
+ .thenReturn(new ConnectRequestResult("req-1", 900, AUTHORIZE_URL));
+
+ service.startReauth(fromRequest("https://pdf.example.com"));
+
+ // Sending the credential is what makes the pinning trustworthy: the team comes from
+ // something only this instance holds.
+ verify(client)
+ .connectRequest(
+ any(),
+ anyString(),
+ anyString(),
+ anyString(),
+ org.mockito.ArgumentMatchers.argThat(
+ c -> c != null && "dev".equals(c.getDeviceId())));
+ }
+
+ @Test
+ void startReauth_onAnUnlinkedServerFails() {
+ assertThat(catchIo(() -> service.startReauth(fromRequest("https://pdf.example.com"))))
+ .hasMessageContaining("not linked");
+ verifyNoInteractions(client);
+ }
+
+ @Test
+ void complete_onAConfirmedReauthKeepsTheExistingCredential() {
+ ConnectState state = openHandshake();
+ when(stateRepo.findById(ConnectState.SINGLETON_ID)).thenReturn(Optional.of(state));
+ when(client.connectClaim(anyString(), anyString()))
+ .thenReturn(new ConnectClaimResult(ConnectClaimOutcome.CONFIRMED, null, null, 7L));
+
+ ConnectService.ConnectStatus status = service.complete(NONCE);
+
+ assertThat(status.phase()).isEqualTo(Phase.LINKED);
+ assertThat(status.teamId()).isEqualTo(7L);
+ // Nothing to store: a second credential would orphan the one we already hold.
+ verify(credentialStore, never()).save(anyString(), anyString(), any());
+ verify(stateRepo).delete(state);
+ }
+
+ @Test
+ void status_reportsNothingInFlightWhenThereIsNoHandshakeOrCredential() {
+ assertThat(service.status().phase()).isEqualTo(Phase.NONE);
+ }
+
+ @Test
+ void status_reportsAnExpiredHandshakeRatherThanOfferingAStaleLink() {
+ ConnectState state = openHandshake();
+ state.setExpiresAt(LocalDateTime.now().minusSeconds(1));
+ when(stateRepo.findById(ConnectState.SINGLETON_ID)).thenReturn(Optional.of(state));
+
+ ConnectService.ConnectStatus status = service.status();
+
+ assertThat(status.phase()).isEqualTo(Phase.EXPIRED);
+ assertThat(status.authorizeUrl()).isNull();
+ }
+
+ @Test
+ void status_countsDownWhileAHandshakeIsOpen() {
+ when(stateRepo.findById(ConnectState.SINGLETON_ID))
+ .thenReturn(Optional.of(openHandshake()));
+
+ ConnectService.ConnectStatus status = service.status();
+
+ assertThat(status.phase()).isEqualTo(Phase.PENDING);
+ assertThat(status.secondsRemaining()).isPositive();
+ assertThat(status.authorizeUrl()).isEqualTo("https://app.example.com/link?request=req-1");
+ }
+
+ // ---------------------------------------------------------------------------------------
+
+ /** A start with nothing but the reconstructed request URL, as a headless caller would send. */
+ private static ConnectService.CallbackHint fromRequest(String derivedBaseUrl) {
+ return new ConnectService.CallbackHint(null, null, derivedBaseUrl);
+ }
+
+ private void stubCreate() throws Exception {
+ // The five-argument overload: a first link passes a null credential rather than none.
+ when(client.connectRequest(any(), anyString(), anyString(), anyString(), any()))
+ .thenReturn(new ConnectRequestResult("req-1", 900, AUTHORIZE_URL));
+ }
+
+ private static ConnectState openHandshake() {
+ ConnectState state = new ConnectState();
+ state.setId(ConnectState.SINGLETON_ID);
+ state.setRequestId("req-1");
+ state.setNonce(NONCE);
+ state.setClaimSecret(CLAIM_SECRET);
+ state.setCallbackUrl("https://pdf.example.com/account-link/callback");
+ state.setAuthorizeUrl("https://app.example.com/link?request=req-1");
+ state.setCreatedAt(LocalDateTime.now());
+ state.setExpiresAt(LocalDateTime.now().plusMinutes(10));
+ return state;
+ }
+
+ private static DeviceCredential credential(Long teamId) {
+ DeviceCredential credential = new DeviceCredential();
+ credential.setDeviceId("dev");
+ credential.setDeviceSecret("sec");
+ credential.setTeamId(teamId);
+ credential.setLinkedAt(LocalDateTime.now());
+ return credential;
+ }
+
+ /** Runs a throwing call and returns the exception, so the assertion reads in one line. */
+ private static Throwable catchIo(ThrowingCall call) {
+ try {
+ call.run();
+ throw new AssertionError("expected the call to fail");
+ } catch (Exception e) {
+ return e;
+ }
+ }
+
+ private interface ThrowingCall {
+ void run() throws Exception;
+ }
+}
diff --git a/app/proprietary/src/test/resources/test-certs/expired-test.p12 b/app/proprietary/src/test/resources/test-certs/expired-test.p12
index c82b6188e3..5db3341f9a 100644
Binary files a/app/proprietary/src/test/resources/test-certs/expired-test.p12 and b/app/proprietary/src/test/resources/test-certs/expired-test.p12 differ
diff --git a/app/proprietary/src/test/resources/test-certs/not-yet-valid-test.p12 b/app/proprietary/src/test/resources/test-certs/not-yet-valid-test.p12
index f57b2e5cb2..817ef4da44 100644
Binary files a/app/proprietary/src/test/resources/test-certs/not-yet-valid-test.p12 and b/app/proprietary/src/test/resources/test-certs/not-yet-valid-test.p12 differ
diff --git a/app/proprietary/src/test/resources/test-certs/valid-test.jks b/app/proprietary/src/test/resources/test-certs/valid-test.jks
index 62407a32ca..5d9f8d4253 100644
Binary files a/app/proprietary/src/test/resources/test-certs/valid-test.jks and b/app/proprietary/src/test/resources/test-certs/valid-test.jks differ
diff --git a/app/proprietary/src/test/resources/test-certs/valid-test.p12 b/app/proprietary/src/test/resources/test-certs/valid-test.p12
index bb00bc60a3..3a5baf6a05 100644
Binary files a/app/proprietary/src/test/resources/test-certs/valid-test.p12 and b/app/proprietary/src/test/resources/test-certs/valid-test.p12 differ
diff --git a/app/saas/src/main/java/stirling/software/saas/accountlink/AccountLinkController.java b/app/saas/src/main/java/stirling/software/saas/accountlink/AccountLinkController.java
index 646791f76e..4703c32496 100644
--- a/app/saas/src/main/java/stirling/software/saas/accountlink/AccountLinkController.java
+++ b/app/saas/src/main/java/stirling/software/saas/accountlink/AccountLinkController.java
@@ -4,14 +4,12 @@ import java.util.List;
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.security.core.Authentication;
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.RestController;
@@ -19,25 +17,9 @@ import io.swagger.v3.oas.annotations.Hidden;
import lombok.extern.slf4j.Slf4j;
-import stirling.software.common.model.enumeration.TeamRole;
-import stirling.software.proprietary.model.TeamMembership;
-import stirling.software.proprietary.security.database.repository.UserRepository;
-import stirling.software.proprietary.security.model.User;
-import stirling.software.proprietary.security.repository.TeamMembershipRepository;
-import stirling.software.saas.util.AuthenticationUtils;
+import stirling.software.saas.accountlink.LeaderTeamResolver.LeaderTeam;
-/**
- * Account-link registration surface (combined-billing "Mode A").
- *
- *
A self-hosted instance's local backend calls {@code POST /register} with the admin's
- * short-lived Supabase JWT (validated by the existing {@code SupabaseSecurityConfig} chain — no new
- * auth here). We resolve the caller's team, mint a device credential bound to it, and return the
- * secret exactly once. Ongoing entitlement reads authenticate with that device credential, not this
- * JWT.
- *
- *
Whole surface gated behind {@code stirling.billing.account-link.enabled}: off → beans absent →
- * 404. Leader-only, and the team is always derived from the caller (never the request body).
- */
+/** Team-wide management of linked instances (combined billing). */
@Slf4j
@Hidden
@RestController
@@ -47,25 +29,13 @@ import stirling.software.saas.util.AuthenticationUtils;
public class AccountLinkController {
private final AccountLinkService service;
- private final TeamMembershipRepository memberRepo;
- private final UserRepository userRepository;
+ private final LeaderTeamResolver leaderTeams;
- public AccountLinkController(
- AccountLinkService service,
- TeamMembershipRepository memberRepo,
- UserRepository userRepository) {
+ public AccountLinkController(AccountLinkService service, LeaderTeamResolver leaderTeams) {
this.service = service;
- this.memberRepo = memberRepo;
- this.userRepository = userRepository;
+ this.leaderTeams = leaderTeams;
}
- /** Optional display name for the instance (hostname / label). */
- public record RegisterRequest(String name) {}
-
- /** {@code deviceSecret} is plaintext and returned exactly once — the caller must store it. */
- public record RegisterResponse(
- Long instanceId, Long teamId, String deviceId, String deviceSecret, String name) {}
-
public record InstanceRow(
Long instanceId,
String deviceId,
@@ -74,31 +44,10 @@ public class AccountLinkController {
String lastSeenAt,
boolean revoked) {}
- @PostMapping("/register")
- @PreAuthorize("isAuthenticated()")
- public ResponseEntity register(
- @RequestBody(required = false) RegisterRequest req, Authentication auth) {
- LeaderTeam lt = resolveLeaderTeam(auth);
- if (lt.error() != null) {
- return ResponseEntity.status(lt.error()).build();
- }
- String name = req != null ? req.name() : null;
- AccountLinkService.RegisteredInstance reg =
- service.register(lt.teamId(), lt.userId(), name);
- return ResponseEntity.status(HttpStatus.CREATED)
- .body(
- new RegisterResponse(
- reg.instanceId(),
- lt.teamId(),
- reg.deviceId(),
- reg.deviceSecret(),
- reg.name()));
- }
-
@GetMapping("/instances")
@PreAuthorize("isAuthenticated()")
public ResponseEntity> list(Authentication auth) {
- LeaderTeam lt = resolveLeaderTeam(auth);
+ LeaderTeam lt = leaderTeams.resolve(auth);
if (lt.error() != null) {
return ResponseEntity.status(lt.error()).build();
}
@@ -124,38 +73,11 @@ public class AccountLinkController {
@PostMapping("/instances/{instanceId}/revoke")
@PreAuthorize("isAuthenticated()")
public ResponseEntity revoke(@PathVariable Long instanceId, Authentication auth) {
- LeaderTeam lt = resolveLeaderTeam(auth);
+ LeaderTeam lt = leaderTeams.resolve(auth);
if (lt.error() != null) {
return ResponseEntity.status(lt.error()).build();
}
boolean ok = service.revoke(lt.teamId(), instanceId);
return ok ? ResponseEntity.noContent().build() : ResponseEntity.notFound().build();
}
-
- // ---------------------------------------------------------------------------------------
- // Helpers — team always derived from the caller; instance linking is a leader (billing) action.
- // ---------------------------------------------------------------------------------------
-
- /**
- * Resolved caller team, or an {@code error} status to return (teamId/userId null when error).
- */
- private record LeaderTeam(Long teamId, Long userId, HttpStatus error) {}
-
- private LeaderTeam resolveLeaderTeam(Authentication auth) {
- User user;
- try {
- user = AuthenticationUtils.getCurrentUser(auth, userRepository);
- } catch (SecurityException e) {
- return new LeaderTeam(null, null, HttpStatus.UNAUTHORIZED);
- }
- List rows = memberRepo.findPrimaryMembership(user.getId());
- if (rows.isEmpty()) {
- return new LeaderTeam(null, null, HttpStatus.FORBIDDEN);
- }
- TeamMembership m = rows.getFirst();
- if (m.getRole() != TeamRole.LEADER) {
- return new LeaderTeam(null, null, HttpStatus.FORBIDDEN);
- }
- return new LeaderTeam(m.getTeam().getId(), user.getId(), null);
- }
}
diff --git a/app/saas/src/main/java/stirling/software/saas/accountlink/AccountLinkService.java b/app/saas/src/main/java/stirling/software/saas/accountlink/AccountLinkService.java
index c31fc1b03e..fe6a0cc0e6 100644
--- a/app/saas/src/main/java/stirling/software/saas/accountlink/AccountLinkService.java
+++ b/app/saas/src/main/java/stirling/software/saas/accountlink/AccountLinkService.java
@@ -18,16 +18,7 @@ import org.springframework.transaction.annotation.Transactional;
import lombok.extern.slf4j.Slf4j;
-/**
- * Account-link instance registration + lifecycle (combined-billing "Mode A").
- *
- *
Mints a {@code device_id} (public) + {@code device_secret} (high-entropy, returned once) bound
- * to a team, persisting only the SHA-256 hash of the secret. The instance authenticates its
- * unattended entitlement reads with that credential.
- *
- *
Gated behind {@code stirling.billing.account-link.enabled}: when off the bean is absent, so
- * {@link AccountLinkController} (which depends on it) drops out too and its endpoints 404.
- */
+/** Account-link instance registration + lifecycle (combined billing). */
@Slf4j
@Service
@Profile("saas")
@@ -80,10 +71,7 @@ public class AccountLinkService {
return repo.findByTeamIdOrderByCreatedAtDesc(teamId);
}
- /**
- * Revokes an instance iff it belongs to {@code teamId}. Returns false if not found or owned by
- * a different team (so a caller can never revoke another team's instance). Idempotent.
- */
+ /** Revokes an instance iff it belongs to {@code teamId}. */
@Transactional
public boolean revoke(Long teamId, Long instanceId) {
Optional found = repo.findById(instanceId);
@@ -99,13 +87,30 @@ public class AccountLinkService {
return true;
}
+ /**
+ * Resolves an active instance from a device credential, or empty if it does not authenticate.
+ */
+ @Transactional(readOnly = true)
+ public Optional resolveActiveInstance(String deviceId, String deviceSecret) {
+ if (deviceId == null || deviceSecret == null) {
+ return Optional.empty();
+ }
+ return repo.findByDeviceIdAndRevokedAtIsNull(deviceId)
+ .filter(
+ instance ->
+ MessageDigest.isEqual(
+ sha256Hex(deviceSecret).getBytes(StandardCharsets.UTF_8),
+ instance.getDeviceSecretHash()
+ .getBytes(StandardCharsets.UTF_8)));
+ }
+
private String randomSecret() {
byte[] buf = new byte[SECRET_BYTES];
random.nextBytes(buf);
return Base64.getUrlEncoder().withoutPadding().encodeToString(buf);
}
- /** SHA-256 hex of a value. The device secret is high-entropy, so no salt is required. */
+ /** SHA-256 hex of a value. */
static String sha256Hex(String value) {
try {
MessageDigest md = MessageDigest.getInstance("SHA-256");
diff --git a/app/saas/src/main/java/stirling/software/saas/accountlink/ConnectController.java b/app/saas/src/main/java/stirling/software/saas/accountlink/ConnectController.java
new file mode 100644
index 0000000000..95f2ba5de7
--- /dev/null
+++ b/app/saas/src/main/java/stirling/software/saas/accountlink/ConnectController.java
@@ -0,0 +1,277 @@
+package stirling.software.saas.accountlink;
+
+import java.net.URLEncoder;
+import java.nio.charset.StandardCharsets;
+import java.util.Map;
+import java.util.Optional;
+
+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.security.core.Authentication;
+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.RestController;
+
+import io.swagger.v3.oas.annotations.Hidden;
+
+import jakarta.servlet.http.HttpServletRequest;
+
+import lombok.extern.slf4j.Slf4j;
+
+import stirling.software.common.model.ApplicationProperties;
+import stirling.software.saas.accountlink.LeaderTeamResolver.LeaderTeam;
+
+/** Browser-mediated "connect this server" handshake. */
+@Slf4j
+@Hidden
+@RestController
+@RequestMapping("/api/v1/account-link/connect")
+@Profile("saas")
+@ConditionalOnProperty(name = "stirling.billing.account-link.enabled", havingValue = "true")
+public class ConnectController {
+
+ /** Same headers the device-credential filter uses on the {@code /api/v1/instance} paths. */
+ static final String HEADER_DEVICE_ID = "X-Device-Id";
+
+ static final String HEADER_DEVICE_SECRET = "X-Device-Secret";
+
+ /** Frontend route serving the approval page. */
+ static final String LINK_PATH = "/link";
+
+ private final ConnectRequestService service;
+ private final LeaderTeamResolver leaderTeams;
+ private final AccountLinkService accountLinkService;
+ private final ApplicationProperties applicationProperties;
+
+ public ConnectController(
+ ConnectRequestService service,
+ LeaderTeamResolver leaderTeams,
+ AccountLinkService accountLinkService,
+ ApplicationProperties applicationProperties) {
+ this.service = service;
+ this.leaderTeams = leaderTeams;
+ this.accountLinkService = accountLinkService;
+ this.applicationProperties = applicationProperties;
+ }
+
+ /** Sent by the instance's own backend, before it holds any credential. */
+ public record CreateBody(String name, String callbackUrl, String nonce, String claimSecret) {}
+
+ /** {@code authorizeUrl} is where the instance should send its admin. */
+ public record CreateResponse(String requestId, int expiresIn, String authorizeUrl) {}
+
+ /** What the approval page renders. */
+ public record ViewResponse(
+ String requestId,
+ String name,
+ String callbackOrigin,
+ boolean insecureTransport,
+ String mode,
+ String status) {}
+
+ /** Where the approver's browser goes next, and the correlator the instance is waiting on. */
+ public record ApproveResponse(String callbackUrl, String nonce) {}
+
+ public record ClaimBody(String requestId, String claimSecret) {}
+
+ public record ClaimResponse(String deviceId, String deviceSecret, Long teamId) {}
+
+ /** Opens a handshake. */
+ @PostMapping("/request")
+ public ResponseEntity request(
+ @RequestBody(required = false) CreateBody body, HttpServletRequest http) {
+ if (body == null) {
+ return ResponseEntity.badRequest().body(Map.of("error", "BAD_REQUEST"));
+ }
+ String deviceId = http.getHeader(HEADER_DEVICE_ID);
+ String deviceSecret = http.getHeader(HEADER_DEVICE_SECRET);
+ boolean reauthRequested = deviceId != null || deviceSecret != null;
+
+ ConnectRequestService.CreateResult result;
+ if (reauthRequested) {
+ Long pinnedTeamId =
+ accountLinkService
+ .resolveActiveInstance(deviceId, deviceSecret)
+ .map(LinkedInstance::getTeamId)
+ .orElse(null);
+ result =
+ service.createReauth(
+ body.name(),
+ body.callbackUrl(),
+ body.nonce(),
+ body.claimSecret(),
+ clientIp(http),
+ pinnedTeamId);
+ } else {
+ result =
+ service.create(
+ body.name(),
+ body.callbackUrl(),
+ body.nonce(),
+ body.claimSecret(),
+ clientIp(http));
+ }
+ if (result.isRejected()) {
+ return switch (result.rejection()) {
+ case RATE_LIMITED ->
+ ResponseEntity.status(HttpStatus.TOO_MANY_REQUESTS)
+ .body(Map.of("error", "RATE_LIMITED"));
+ case BAD_CALLBACK ->
+ ResponseEntity.badRequest().body(Map.of("error", "BAD_CALLBACK"));
+ case BAD_NONCE -> ResponseEntity.badRequest().body(Map.of("error", "BAD_NONCE"));
+ case BAD_SECRET -> ResponseEntity.badRequest().body(Map.of("error", "BAD_SECRET"));
+ // A credential was offered and did not authenticate. Same answer as any other bad
+ // credential, and deliberately not distinguishable from "revoked".
+ case NOT_LINKED ->
+ ResponseEntity.status(HttpStatus.UNAUTHORIZED)
+ .body(Map.of("error", "NOT_LINKED"));
+ };
+ }
+ return ResponseEntity.status(HttpStatus.CREATED)
+ .body(
+ new CreateResponse(
+ result.requestId(),
+ result.expiresInSeconds(),
+ authorizeUrl(result.requestId(), http)));
+ }
+
+ /**
+ * Where to send the admin to approve a handshake. {@code system.frontendUrl} is the web app's
+ * own base URL, including any base path; without it the API's origin has to serve the app too.
+ */
+ private String authorizeUrl(String requestId, HttpServletRequest http) {
+ String frontendUrl = applicationProperties.getSystem().getFrontendUrl();
+ String base =
+ frontendUrl != null && !frontendUrl.isBlank()
+ ? frontendUrl.strip().replaceAll("/+$", "")
+ : requestOrigin(http);
+ return base
+ + LINK_PATH
+ + "?request="
+ + URLEncoder.encode(requestId, StandardCharsets.UTF_8);
+ }
+
+ /** Scheme, host and context path as the browser reached us, honouring a reverse proxy. */
+ private static String requestOrigin(HttpServletRequest request) {
+ String proto = firstHop(request.getHeader("X-Forwarded-Proto"));
+ String host = firstHop(request.getHeader("X-Forwarded-Host"));
+ String scheme = proto != null ? proto : request.getScheme();
+ // A forwarded host already carries its own port, if it needs one.
+ String hostPort =
+ host != null
+ ? host
+ : Origins.hostPort(
+ scheme, request.getServerName(), request.getServerPort());
+ String context = request.getContextPath() == null ? "" : request.getContextPath();
+ return scheme + "://" + hostPort + context;
+ }
+
+ private static String firstHop(String headerValue) {
+ if (headerValue == null || headerValue.isBlank()) {
+ return null;
+ }
+ String first = headerValue.split(",")[0].strip();
+ return first.isEmpty() ? null : first;
+ }
+
+ /** Detail for the approval page. */
+ @GetMapping("/{requestId}")
+ @PreAuthorize("isAuthenticated()")
+ public ResponseEntity view(@PathVariable String requestId) {
+ return service.lookup(requestId)
+ .map(
+ v ->
+ ResponseEntity.ok(
+ new ViewResponse(
+ v.requestId(),
+ v.name(),
+ v.callbackOrigin(),
+ v.insecureTransport(),
+ v.mode().name(),
+ v.status().name())))
+ .orElseGet(() -> ResponseEntity.notFound().build());
+ }
+
+ /** Approves a handshake. */
+ @PostMapping("/{requestId}/approve")
+ @PreAuthorize("isAuthenticated()")
+ public ResponseEntity approve(@PathVariable String requestId, Authentication auth) {
+ Optional view = service.lookup(requestId);
+ if (view.isEmpty()) {
+ return ResponseEntity.notFound().build();
+ }
+ boolean reauth = view.get().mode() == ConnectRequest.Mode.REAUTH;
+ LeaderTeam lt = reauth ? leaderTeams.resolveMember(auth) : leaderTeams.resolve(auth);
+ if (lt.isError()) {
+ return ResponseEntity.status(lt.error()).build();
+ }
+ ConnectRequestService.ApproveResult result =
+ service.approve(requestId, lt.teamId(), lt.userId());
+ if (result.isRejected()) {
+ return switch (result.rejection()) {
+ // Named separately so the page can say "you are signed in to a different account"
+ // rather than implying the request itself was bad.
+ case WRONG_TEAM ->
+ ResponseEntity.status(HttpStatus.CONFLICT)
+ .body(Map.of("error", "WRONG_TEAM"));
+ case UNAVAILABLE -> ResponseEntity.notFound().build();
+ };
+ }
+ return ResponseEntity.ok(
+ new ApproveResponse(result.target().callbackUrl(), result.target().nonce()));
+ }
+
+ @PostMapping("/{requestId}/deny")
+ @PreAuthorize("isAuthenticated()")
+ public ResponseEntity deny(@PathVariable String requestId, Authentication auth) {
+ LeaderTeam lt = leaderTeams.resolve(auth);
+ if (lt.isError()) {
+ return ResponseEntity.status(lt.error()).build();
+ }
+ return service.deny(requestId)
+ ? ResponseEntity.noContent().build()
+ : ResponseEntity.notFound().build();
+ }
+
+ /** Collects the device credential. */
+ @PostMapping("/claim")
+ public ResponseEntity claim(@RequestBody(required = false) ClaimBody body) {
+ if (body == null) {
+ return ResponseEntity.badRequest().body(Map.of("error", "BAD_REQUEST"));
+ }
+ ConnectRequestService.ClaimResult result =
+ service.claim(body.requestId(), body.claimSecret());
+ return switch (result.outcome()) {
+ case GRANTED ->
+ ResponseEntity.ok(
+ new ClaimResponse(
+ result.deviceId(), result.deviceSecret(), result.teamId()));
+ // A re-authentication carries no credential: the instance already has one. It only
+ // needs to know the browser leg succeeded, and which team it was confirmed against.
+ case CONFIRMED ->
+ ResponseEntity.ok(Map.of("status", "confirmed", "teamId", result.teamId()));
+ case PENDING ->
+ ResponseEntity.status(HttpStatus.ACCEPTED).body(Map.of("status", "pending"));
+ case REJECTED -> ResponseEntity.badRequest().body(Map.of("error", "CONNECT_REJECTED"));
+ };
+ }
+
+ /**
+ * Source address for the creation cap.
+ *
+ *
Deliberately not reading {@code X-Forwarded-For}: the caller sets it, so keying a cap on
+ * it lets one rotate fake addresses and have no cap at all. {@code
+ * server.forward-headers-strategy} is NATIVE, so the container has already resolved the real
+ * client from trusted proxies.
+ */
+ private static String clientIp(HttpServletRequest request) {
+ String remote = request.getRemoteAddr();
+ return remote == null || remote.length() <= 45 ? remote : remote.substring(0, 45);
+ }
+}
diff --git a/app/saas/src/main/java/stirling/software/saas/accountlink/ConnectRequest.java b/app/saas/src/main/java/stirling/software/saas/accountlink/ConnectRequest.java
new file mode 100644
index 0000000000..f9c204eef3
--- /dev/null
+++ b/app/saas/src/main/java/stirling/software/saas/accountlink/ConnectRequest.java
@@ -0,0 +1,103 @@
+package stirling.software.saas.accountlink;
+
+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.GeneratedValue;
+import jakarta.persistence.GenerationType;
+import jakarta.persistence.Id;
+import jakarta.persistence.Index;
+import jakarta.persistence.Table;
+
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+import lombok.Setter;
+
+/** One in-flight "connect this server" handshake. Short lived and single use. */
+@Entity
+@Table(
+ name = "account_link_connect_request",
+ indexes = @Index(name = "idx_alcr_ip_created", columnList = "requester_ip,created_at"))
+@Getter
+@Setter
+@NoArgsConstructor
+public class ConnectRequest {
+
+ public enum Mode {
+ LINK,
+ REAUTH
+ }
+
+ public enum Status {
+ PENDING,
+ APPROVED,
+ DENIED,
+ CONSUMED
+ }
+
+ @Id
+ @GeneratedValue(strategy = GenerationType.IDENTITY)
+ private Long id;
+
+ @Column(name = "request_id", nullable = false, unique = true, length = 64)
+ private String requestId;
+
+ @Column(name = "name", length = 255)
+ private String name;
+
+ /**
+ * Read back from here on approval, never from the request: that is what stops an open redirect.
+ */
+ @Column(name = "callback_url", nullable = false, length = 2048)
+ private String callbackUrl;
+
+ @Column(name = "callback_origin", nullable = false, length = 255)
+ private String callbackOrigin;
+
+ @Column(name = "nonce", nullable = false, length = 128)
+ private String nonce;
+
+ /** SHA-256; the secret itself is never stored. */
+ @Column(name = "claim_secret_hash", nullable = false, length = 64)
+ private String claimSecretHash;
+
+ @Enumerated(EnumType.STRING)
+ @Column(name = "mode", nullable = false, length = 16)
+ private Mode mode = Mode.LINK;
+
+ @Enumerated(EnumType.STRING)
+ @Column(name = "status", nullable = false, length = 16)
+ private Status status = Status.PENDING;
+
+ /** LINK: set on approval. REAUTH: pinned at creation, so approval can only confirm it. */
+ @Column(name = "team_id")
+ private Long teamId;
+
+ @Column(name = "approved_by_user_id")
+ private Long approvedByUserId;
+
+ @Column(name = "requester_ip", length = 45)
+ private String requesterIp;
+
+ @CreationTimestamp
+ @Column(name = "created_at", nullable = false, updatable = false)
+ private LocalDateTime createdAt;
+
+ @Column(name = "expires_at", nullable = false)
+ private LocalDateTime expiresAt;
+
+ @Column(name = "approved_at")
+ private LocalDateTime approvedAt;
+
+ @Column(name = "consumed_at")
+ private LocalDateTime consumedAt;
+
+ public boolean isExpired(LocalDateTime now) {
+ return expiresAt != null && expiresAt.isBefore(now);
+ }
+}
diff --git a/app/saas/src/main/java/stirling/software/saas/accountlink/ConnectRequestCleanupService.java b/app/saas/src/main/java/stirling/software/saas/accountlink/ConnectRequestCleanupService.java
new file mode 100644
index 0000000000..7712ee297a
--- /dev/null
+++ b/app/saas/src/main/java/stirling/software/saas/accountlink/ConnectRequestCleanupService.java
@@ -0,0 +1,47 @@
+package stirling.software.saas.accountlink;
+
+import java.time.LocalDateTime;
+
+import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
+import org.springframework.context.annotation.Profile;
+import org.springframework.scheduling.annotation.Scheduled;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+
+/**
+ * Removes connect requests that are past use.
+ *
+ *
Needed rather than merely tidy: anyone can create a row on {@code POST /connect/request}, and
+ * nothing else deletes one. Requests hold a callback URL and the requester's address, so they are
+ * swept soon after expiry rather than kept.
+ */
+@Slf4j
+@Service
+@Profile("saas")
+@ConditionalOnProperty(name = "stirling.billing.account-link.enabled", havingValue = "true")
+@RequiredArgsConstructor
+public class ConnectRequestCleanupService {
+
+ /** Long enough to answer "what happened to my link?" the next morning, and no longer. */
+ private static final int RETAIN_HOURS = 24;
+
+ private final ConnectRequestRepository repo;
+
+ @Scheduled(cron = "0 30 3 * * *")
+ @Transactional
+ public void purgeExpired() {
+ try {
+ LocalDateTime cutoff = LocalDateTime.now().minusHours(RETAIN_HOURS);
+ int deleted = repo.deleteByExpiresAtBefore(cutoff);
+ if (deleted > 0) {
+ log.info("Account-link connect: purged {} expired requests", deleted);
+ }
+ } catch (Exception e) {
+ // A failed sweep must not take the scheduler down; the next run retries.
+ log.error("Account-link connect: purge failed", e);
+ }
+ }
+}
diff --git a/app/saas/src/main/java/stirling/software/saas/accountlink/ConnectRequestRepository.java b/app/saas/src/main/java/stirling/software/saas/accountlink/ConnectRequestRepository.java
new file mode 100644
index 0000000000..6c5dec098b
--- /dev/null
+++ b/app/saas/src/main/java/stirling/software/saas/accountlink/ConnectRequestRepository.java
@@ -0,0 +1,28 @@
+package stirling.software.saas.accountlink;
+
+import java.time.LocalDateTime;
+import java.util.Optional;
+
+import org.springframework.data.jpa.repository.JpaRepository;
+import org.springframework.data.jpa.repository.Lock;
+import org.springframework.data.jpa.repository.Query;
+import org.springframework.data.repository.query.Param;
+
+import jakarta.persistence.LockModeType;
+
+/** Data access for {@link ConnectRequest}. */
+public interface ConnectRequestRepository extends JpaRepository {
+
+ Optional findByRequestId(String requestId);
+
+ /** Row-locking read used by approve, deny and claim. */
+ @Lock(LockModeType.PESSIMISTIC_WRITE)
+ @Query("SELECT r FROM ConnectRequest r WHERE r.requestId = :requestId")
+ Optional findByRequestIdForUpdate(@Param("requestId") String requestId);
+
+ /** Backs the per-IP creation cap, since creating a request needs no authentication. */
+ long countByRequesterIpAndCreatedAtAfter(String requesterIp, LocalDateTime after);
+
+ /** Sweeps rows past use, whatever they settled as. Anyone can create these. */
+ int deleteByExpiresAtBefore(LocalDateTime cutoff);
+}
diff --git a/app/saas/src/main/java/stirling/software/saas/accountlink/ConnectRequestService.java b/app/saas/src/main/java/stirling/software/saas/accountlink/ConnectRequestService.java
new file mode 100644
index 0000000000..64abc12fa6
--- /dev/null
+++ b/app/saas/src/main/java/stirling/software/saas/accountlink/ConnectRequestService.java
@@ -0,0 +1,391 @@
+package stirling.software.saas.accountlink;
+
+import java.net.URI;
+import java.net.URISyntaxException;
+import java.nio.charset.StandardCharsets;
+import java.security.MessageDigest;
+import java.security.SecureRandom;
+import java.time.LocalDateTime;
+import java.util.Base64;
+import java.util.Locale;
+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;
+
+import lombok.extern.slf4j.Slf4j;
+
+/** The "connect this server" handshake, SaaS side. */
+@Slf4j
+@Service
+@Profile("saas")
+@ConditionalOnProperty(name = "stirling.billing.account-link.enabled", havingValue = "true")
+public class ConnectRequestService {
+
+ /**
+ * Long enough for the approver to sign in, pick the right account and read the origin. Sized
+ * for the slowest real route: signing up, waiting for a confirmation email, and coming back.
+ */
+ static final int LIFETIME_MINUTES = 30;
+
+ /** Creating a request needs no authentication, so the only brake is per-source volume. */
+ static final int MAX_REQUESTS_PER_IP = 10;
+
+ private static final int REQUEST_ID_BYTES = 32;
+ private static final int MAX_NONCE_LENGTH = 128;
+ private static final int MAX_CALLBACK_LENGTH = 2048;
+ private static final int MAX_NAME_LENGTH = 255;
+
+ private final ConnectRequestRepository repo;
+ private final AccountLinkService accountLinkService;
+ private final SecureRandom random = new SecureRandom();
+
+ public ConnectRequestService(
+ ConnectRequestRepository repo, AccountLinkService accountLinkService) {
+ this.repo = repo;
+ this.accountLinkService = accountLinkService;
+ }
+
+ /** Rejected creation attempts, so the controller can pick a status without parsing messages. */
+ public enum CreateRejection {
+ BAD_CALLBACK,
+ BAD_NONCE,
+ BAD_SECRET,
+ RATE_LIMITED,
+ /**
+ * A re-authentication was asked for by something that could not prove it is a linked
+ * instance.
+ */
+ NOT_LINKED
+ }
+
+ /** Either a created request id, or the reason we would not create one. */
+ public record CreateResult(String requestId, int expiresInSeconds, CreateRejection rejection) {
+ static CreateResult ok(String requestId, int expiresInSeconds) {
+ return new CreateResult(requestId, expiresInSeconds, null);
+ }
+
+ static CreateResult rejected(CreateRejection rejection) {
+ return new CreateResult(null, 0, rejection);
+ }
+
+ public boolean isRejected() {
+ return rejection != null;
+ }
+ }
+
+ /** What the approval page shows. */
+ public record ConnectView(
+ String requestId,
+ String name,
+ String callbackOrigin,
+ boolean insecureTransport,
+ ConnectRequest.Mode mode,
+ ConnectRequest.Status status) {}
+
+ /** Where to send the browser once approved, plus the correlator the instance is expecting. */
+ public record ApprovalTarget(String callbackUrl, String nonce) {}
+
+ public enum ClaimOutcome {
+ /** Approved and collected; {@code credential} is populated. */
+ GRANTED,
+ /** A re-authentication was approved. */
+ CONFIRMED,
+ /** Still waiting on a human. */
+ PENDING,
+ /** Declined, expired, unknown, already collected, or a bad claim secret. */
+ REJECTED
+ }
+
+ public record ClaimResult(
+ ClaimOutcome outcome, String deviceId, String deviceSecret, Long teamId) {
+ static ClaimResult of(ClaimOutcome outcome) {
+ return new ClaimResult(outcome, null, null, null);
+ }
+ }
+
+ /** Records a handshake on behalf of an instance that has no credential yet. */
+ @Transactional
+ public CreateResult create(
+ String name, String callbackUrl, String nonce, String claimSecret, String requesterIp) {
+ return create(name, callbackUrl, nonce, claimSecret, requesterIp, null);
+ }
+
+ /**
+ * As {@link #create}, but for an instance that is already linked and only needs its admin's
+ * browser signed in again.
+ */
+ @Transactional
+ public CreateResult createReauth(
+ String name,
+ String callbackUrl,
+ String nonce,
+ String claimSecret,
+ String requesterIp,
+ Long pinnedTeamId) {
+ if (pinnedTeamId == null) {
+ return CreateResult.rejected(CreateRejection.NOT_LINKED);
+ }
+ return create(name, callbackUrl, nonce, claimSecret, requesterIp, pinnedTeamId);
+ }
+
+ private CreateResult create(
+ String name,
+ String callbackUrl,
+ String nonce,
+ String claimSecret,
+ String requesterIp,
+ Long pinnedTeamId) {
+ if (nonce == null || nonce.isBlank() || nonce.length() > MAX_NONCE_LENGTH) {
+ return CreateResult.rejected(CreateRejection.BAD_NONCE);
+ }
+ if (claimSecret == null || claimSecret.isBlank()) {
+ return CreateResult.rejected(CreateRejection.BAD_SECRET);
+ }
+ Optional parsed = validateCallback(callbackUrl);
+ if (parsed.isEmpty()) {
+ return CreateResult.rejected(CreateRejection.BAD_CALLBACK);
+ }
+ LocalDateTime now = LocalDateTime.now();
+ if (requesterIp != null
+ && repo.countByRequesterIpAndCreatedAtAfter(requesterIp, now.minusHours(1))
+ >= MAX_REQUESTS_PER_IP) {
+ return CreateResult.rejected(CreateRejection.RATE_LIMITED);
+ }
+
+ URI uri = parsed.get();
+ ConnectRequest request = new ConnectRequest();
+ request.setRequestId(randomToken());
+ request.setName(trim(name, MAX_NAME_LENGTH));
+ request.setCallbackUrl(uri.toString());
+ request.setCallbackOrigin(originOf(uri));
+ request.setNonce(nonce);
+ request.setClaimSecretHash(sha256Hex(claimSecret));
+ request.setStatus(ConnectRequest.Status.PENDING);
+ request.setMode(
+ pinnedTeamId == null ? ConnectRequest.Mode.LINK : ConnectRequest.Mode.REAUTH);
+ request.setTeamId(pinnedTeamId);
+ request.setRequesterIp(requesterIp);
+ request.setExpiresAt(now.plusMinutes(LIFETIME_MINUTES));
+ repo.save(request);
+
+ // Never log the nonce or the claim secret; both are live. The request id is the safe
+ // handle for correlating a support request against this row.
+ log.info(
+ "Account-link connect: request {} created for origin {}",
+ request.getRequestId(),
+ request.getCallbackOrigin());
+ return CreateResult.ok(request.getRequestId(), LIFETIME_MINUTES * 60);
+ }
+
+ /** The approver's view of a handshake. */
+ @Transactional(readOnly = true)
+ public Optional lookup(String requestId) {
+ return repo.findByRequestId(requestId)
+ .filter(r -> !r.isExpired(LocalDateTime.now()))
+ .map(
+ r ->
+ new ConnectView(
+ r.getRequestId(),
+ r.getName(),
+ r.getCallbackOrigin(),
+ !"https".equals(schemeOf(r.getCallbackOrigin())),
+ r.getMode(),
+ r.getStatus()));
+ }
+
+ /** Why an approval was refused, so the page can say something useful. */
+ public enum ApproveRejection {
+ /** Unknown, expired, or already settled. */
+ UNAVAILABLE,
+ /** The approver's team is not the team this server already belongs to. */
+ WRONG_TEAM
+ }
+
+ public record ApproveResult(ApprovalTarget target, ApproveRejection rejection) {
+ public boolean isRejected() {
+ return target == null;
+ }
+ }
+
+ /** Binds a pending handshake to the approver's team and returns where to send them next. */
+ @Transactional
+ public ApproveResult approve(String requestId, Long teamId, Long userId) {
+ Optional found = repo.findByRequestIdForUpdate(requestId);
+ if (found.isEmpty()) {
+ return new ApproveResult(null, ApproveRejection.UNAVAILABLE);
+ }
+ ConnectRequest request = found.get();
+ LocalDateTime now = LocalDateTime.now();
+ if (request.isExpired(now) || request.getStatus() != ConnectRequest.Status.PENDING) {
+ return new ApproveResult(null, ApproveRejection.UNAVAILABLE);
+ }
+ Long pinned = request.getTeamId();
+ if (pinned != null && !pinned.equals(teamId)) {
+ log.warn(
+ "Account-link connect: request {} approved by team {} but is pinned to team {};"
+ + " refusing",
+ requestId,
+ teamId,
+ pinned);
+ return new ApproveResult(null, ApproveRejection.WRONG_TEAM);
+ }
+ request.setStatus(ConnectRequest.Status.APPROVED);
+ request.setTeamId(teamId);
+ request.setApprovedByUserId(userId);
+ request.setApprovedAt(now);
+ repo.save(request);
+ log.info(
+ "Account-link connect: request {} approved for team {} ({})",
+ requestId,
+ teamId,
+ request.getMode());
+ return new ApproveResult(
+ new ApprovalTarget(request.getCallbackUrl(), request.getNonce()), null);
+ }
+
+ /** Declines a pending handshake. */
+ @Transactional
+ public boolean deny(String requestId) {
+ Optional found = repo.findByRequestIdForUpdate(requestId);
+ if (found.isEmpty()) {
+ return false;
+ }
+ ConnectRequest request = found.get();
+ if (request.getStatus() != ConnectRequest.Status.PENDING) {
+ return false;
+ }
+ request.setStatus(ConnectRequest.Status.DENIED);
+ repo.save(request);
+ log.info("Account-link connect: request {} denied", requestId);
+ return true;
+ }
+
+ /** Collects the device credential for an approved handshake. */
+ @Transactional
+ public ClaimResult claim(String requestId, String claimSecret) {
+ if (requestId == null || claimSecret == null) {
+ return ClaimResult.of(ClaimOutcome.REJECTED);
+ }
+ Optional found = repo.findByRequestIdForUpdate(requestId);
+ if (found.isEmpty()) {
+ return ClaimResult.of(ClaimOutcome.REJECTED);
+ }
+ ConnectRequest request = found.get();
+ if (!secretMatches(claimSecret, request.getClaimSecretHash())) {
+ // Same answer as an unknown id: a caller probing ids learns nothing from the
+ // difference.
+ log.warn("Account-link connect: claim for request {} had a bad secret", requestId);
+ return ClaimResult.of(ClaimOutcome.REJECTED);
+ }
+ if (request.isExpired(LocalDateTime.now())) {
+ return ClaimResult.of(ClaimOutcome.REJECTED);
+ }
+ return switch (request.getStatus()) {
+ case PENDING -> ClaimResult.of(ClaimOutcome.PENDING);
+ case APPROVED -> mint(request);
+ case DENIED, CONSUMED -> ClaimResult.of(ClaimOutcome.REJECTED);
+ };
+ }
+
+ /** Settles an approved handshake. */
+ private ClaimResult mint(ConnectRequest request) {
+ if (request.getMode() == ConnectRequest.Mode.REAUTH) {
+ request.setStatus(ConnectRequest.Status.CONSUMED);
+ request.setConsumedAt(LocalDateTime.now());
+ repo.save(request);
+ log.info(
+ "Account-link connect: request {} re-authenticated for team {}",
+ request.getRequestId(),
+ request.getTeamId());
+ return new ClaimResult(ClaimOutcome.CONFIRMED, null, null, request.getTeamId());
+ }
+ AccountLinkService.RegisteredInstance registered =
+ accountLinkService.register(
+ request.getTeamId(), request.getApprovedByUserId(), request.getName());
+ request.setStatus(ConnectRequest.Status.CONSUMED);
+ request.setConsumedAt(LocalDateTime.now());
+ repo.save(request);
+ log.info(
+ "Account-link connect: request {} claimed, instance {} bound to team {}",
+ request.getRequestId(),
+ registered.instanceId(),
+ request.getTeamId());
+ return new ClaimResult(
+ ClaimOutcome.GRANTED,
+ registered.deviceId(),
+ registered.deviceSecret(),
+ request.getTeamId());
+ }
+
+ /** Absolute http(s) URL, with a host, no credentials and no fragment of its own. */
+ static Optional validateCallback(String candidate) {
+ if (candidate == null || candidate.isBlank() || candidate.length() > MAX_CALLBACK_LENGTH) {
+ return Optional.empty();
+ }
+ URI uri;
+ try {
+ uri = new URI(candidate.strip());
+ } catch (URISyntaxException e) {
+ return Optional.empty();
+ }
+ if (!uri.isAbsolute() || uri.getScheme() == null) {
+ return Optional.empty();
+ }
+ String scheme = uri.getScheme().toLowerCase(Locale.ROOT);
+ if (!"http".equals(scheme) && !"https".equals(scheme)) {
+ return Optional.empty();
+ }
+ if (uri.getHost() == null || uri.getHost().isBlank()) {
+ return Optional.empty();
+ }
+ if (uri.getUserInfo() != null || uri.getFragment() != null) {
+ return Optional.empty();
+ }
+ return Optional.of(uri);
+ }
+
+ /** Scheme, host and port, with the default port omitted so origins compare cleanly. */
+ static String originOf(URI uri) {
+ String scheme = uri.getScheme().toLowerCase(Locale.ROOT);
+ return scheme + "://" + Origins.hostPort(scheme, uri.getHost(), uri.getPort());
+ }
+
+ private static String schemeOf(String origin) {
+ int sep = origin.indexOf("://");
+ return sep < 0 ? "" : origin.substring(0, sep);
+ }
+
+ private static String trim(String value, int max) {
+ if (value == null) {
+ return null;
+ }
+ String stripped = value.strip();
+ if (stripped.isEmpty()) {
+ return null;
+ }
+ return stripped.length() <= max ? stripped : stripped.substring(0, max);
+ }
+
+ private String randomToken() {
+ byte[] buf = new byte[REQUEST_ID_BYTES];
+ random.nextBytes(buf);
+ return Base64.getUrlEncoder().withoutPadding().encodeToString(buf);
+ }
+
+ /** Constant-time comparison so a claim cannot be brute-forced a byte at a time. */
+ private static boolean secretMatches(String candidate, String expectedHash) {
+ if (expectedHash == null) {
+ return false;
+ }
+ return MessageDigest.isEqual(
+ sha256Hex(candidate).getBytes(StandardCharsets.UTF_8),
+ expectedHash.getBytes(StandardCharsets.UTF_8));
+ }
+
+ private static String sha256Hex(String value) {
+ return AccountLinkService.sha256Hex(value);
+ }
+}
diff --git a/app/saas/src/main/java/stirling/software/saas/accountlink/DeviceCredentialAuthenticationFilter.java b/app/saas/src/main/java/stirling/software/saas/accountlink/DeviceCredentialAuthenticationFilter.java
index a2fd13a095..17cb340d60 100644
--- a/app/saas/src/main/java/stirling/software/saas/accountlink/DeviceCredentialAuthenticationFilter.java
+++ b/app/saas/src/main/java/stirling/software/saas/accountlink/DeviceCredentialAuthenticationFilter.java
@@ -19,7 +19,7 @@ import jakarta.servlet.http.HttpServletResponse;
import lombok.extern.slf4j.Slf4j;
/**
- * Authenticates a linked self-hosted instance by its device credential (combined-billing "Mode A").
+ * Authenticates a linked self-hosted instance by its device credential (combined billing).
*
*
Reads {@code X-Device-Id} + {@code X-Device-Secret}, looks up the active {@link
* LinkedInstance}, and constant-time compares the SHA-256 of the presented secret against the
diff --git a/app/saas/src/main/java/stirling/software/saas/accountlink/InstanceController.java b/app/saas/src/main/java/stirling/software/saas/accountlink/InstanceController.java
index 7c98d5e59b..9c313a1dfa 100644
--- a/app/saas/src/main/java/stirling/software/saas/accountlink/InstanceController.java
+++ b/app/saas/src/main/java/stirling/software/saas/accountlink/InstanceController.java
@@ -32,9 +32,9 @@ import stirling.software.saas.payg.policy.PricingPolicy;
import stirling.software.saas.payg.policy.PricingPolicyService;
/**
- * Instance-facing surface (combined-billing "Mode A"), authenticated by the device
- * credential — not a user JWT. Separate path prefix ({@code /api/v1/instance/**}) so the device
- * credential is scoped here and nowhere else.
+ * Instance-facing surface (combined billing), authenticated by the device credential — not a
+ * user JWT. Separate path prefix ({@code /api/v1/instance/**}) so the device credential is scoped
+ * here and nowhere else.
*
*
{@code GET /whoami} is the MVP round-trip proof: a registered instance presenting a valid
* device credential gets back its resolved {@code instanceId} + {@code teamId}. {@code GET
diff --git a/app/saas/src/main/java/stirling/software/saas/accountlink/LeaderTeamResolver.java b/app/saas/src/main/java/stirling/software/saas/accountlink/LeaderTeamResolver.java
new file mode 100644
index 0000000000..7118562a28
--- /dev/null
+++ b/app/saas/src/main/java/stirling/software/saas/accountlink/LeaderTeamResolver.java
@@ -0,0 +1,68 @@
+package stirling.software.saas.accountlink;
+
+import java.util.List;
+
+import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
+import org.springframework.context.annotation.Profile;
+import org.springframework.http.HttpStatus;
+import org.springframework.security.core.Authentication;
+import org.springframework.stereotype.Component;
+
+import stirling.software.common.model.enumeration.TeamRole;
+import stirling.software.proprietary.model.TeamMembership;
+import stirling.software.proprietary.security.database.repository.UserRepository;
+import stirling.software.proprietary.security.model.User;
+import stirling.software.proprietary.security.repository.TeamMembershipRepository;
+import stirling.software.saas.util.AuthenticationUtils;
+
+/** Who is allowed to bind a self-hosted instance to a team. */
+@Component
+@Profile("saas")
+@ConditionalOnProperty(name = "stirling.billing.account-link.enabled", havingValue = "true")
+public class LeaderTeamResolver {
+
+ private final TeamMembershipRepository memberRepo;
+ private final UserRepository userRepository;
+
+ public LeaderTeamResolver(TeamMembershipRepository memberRepo, UserRepository userRepository) {
+ this.memberRepo = memberRepo;
+ this.userRepository = userRepository;
+ }
+
+ /**
+ * Resolved caller, or an {@code error} status to return ({@code teamId}/{@code userId} null).
+ */
+ public record LeaderTeam(Long teamId, Long userId, HttpStatus error) {
+ public boolean isError() {
+ return error != null;
+ }
+ }
+
+ /** Caller must lead their team. */
+ public LeaderTeam resolve(Authentication auth) {
+ return resolve(auth, true);
+ }
+
+ /** Caller need only belong to a team. */
+ public LeaderTeam resolveMember(Authentication auth) {
+ return resolve(auth, false);
+ }
+
+ private LeaderTeam resolve(Authentication auth, boolean requireLeader) {
+ User user;
+ try {
+ user = AuthenticationUtils.getCurrentUser(auth, userRepository);
+ } catch (SecurityException e) {
+ return new LeaderTeam(null, null, HttpStatus.UNAUTHORIZED);
+ }
+ List rows = memberRepo.findPrimaryMembership(user.getId());
+ if (rows.isEmpty()) {
+ return new LeaderTeam(null, null, HttpStatus.FORBIDDEN);
+ }
+ TeamMembership membership = rows.getFirst();
+ if (requireLeader && membership.getRole() != TeamRole.LEADER) {
+ return new LeaderTeam(null, null, HttpStatus.FORBIDDEN);
+ }
+ return new LeaderTeam(membership.getTeam().getId(), user.getId(), null);
+ }
+}
diff --git a/app/saas/src/main/java/stirling/software/saas/accountlink/LinkedInstance.java b/app/saas/src/main/java/stirling/software/saas/accountlink/LinkedInstance.java
index ec92c97758..f460e82d5b 100644
--- a/app/saas/src/main/java/stirling/software/saas/accountlink/LinkedInstance.java
+++ b/app/saas/src/main/java/stirling/software/saas/accountlink/LinkedInstance.java
@@ -16,7 +16,7 @@ import lombok.NoArgsConstructor;
import lombok.Setter;
/**
- * One self-hosted instance that has linked a SaaS account (combined-billing "Mode A", {@code
+ * One self-hosted instance that has linked a SaaS account (combined billing, {@code
* linked_instance}, V22).
*
*
Created by {@code POST /api/v1/account-link/register}, authenticated with the admin's
diff --git a/app/saas/src/main/java/stirling/software/saas/accountlink/LinkedInstanceAuthenticationToken.java b/app/saas/src/main/java/stirling/software/saas/accountlink/LinkedInstanceAuthenticationToken.java
index af883bd66a..e393a162db 100644
--- a/app/saas/src/main/java/stirling/software/saas/accountlink/LinkedInstanceAuthenticationToken.java
+++ b/app/saas/src/main/java/stirling/software/saas/accountlink/LinkedInstanceAuthenticationToken.java
@@ -6,7 +6,7 @@ import org.springframework.security.authentication.AbstractAuthenticationToken;
import org.springframework.security.core.authority.SimpleGrantedAuthority;
/**
- * Authentication for a linked self-hosted instance (combined-billing "Mode A").
+ * Authentication for a linked self-hosted instance (combined billing).
*
*
Deliberately not a user: the principal is the instance ({@code instanceId}) bound to
* a {@code teamId}, with the single authority {@code ROLE_LINKED_INSTANCE}. It carries no {@code
diff --git a/app/saas/src/main/java/stirling/software/saas/accountlink/Origins.java b/app/saas/src/main/java/stirling/software/saas/accountlink/Origins.java
new file mode 100644
index 0000000000..629e0f7fc1
--- /dev/null
+++ b/app/saas/src/main/java/stirling/software/saas/accountlink/Origins.java
@@ -0,0 +1,22 @@
+package stirling.software.saas.accountlink;
+
+/**
+ * Origin formatting shared by the connect handshake.
+ *
+ *
One place on purpose: the origin a request arrives on and the origin parsed out of a callback
+ * URL are compared with each other, so if either side stopped omitting the default port the
+ * comparison would start failing quietly.
+ */
+final class Origins {
+
+ private Origins() {}
+
+ /** {@code host} or {@code host:port}, dropping a port that is the scheme's default. */
+ static String hostPort(String scheme, String host, int port) {
+ boolean isDefault =
+ port <= 0
+ || ("http".equals(scheme) && port == 80)
+ || ("https".equals(scheme) && port == 443);
+ return isDefault ? host : host + ":" + port;
+ }
+}
diff --git a/app/saas/src/main/java/stirling/software/saas/ai/controller/AiCreateController.java b/app/saas/src/main/java/stirling/software/saas/ai/controller/AiCreateController.java
index 28bbfbdea0..77a87a27bb 100644
--- a/app/saas/src/main/java/stirling/software/saas/ai/controller/AiCreateController.java
+++ b/app/saas/src/main/java/stirling/software/saas/ai/controller/AiCreateController.java
@@ -26,8 +26,8 @@ import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.server.ResponseStatusException;
import org.springframework.web.servlet.mvc.method.annotation.StreamingResponseBody;
-import com.fasterxml.jackson.core.JsonProcessingException;
-import com.fasterxml.jackson.databind.ObjectMapper;
+import tools.jackson.core.JacksonException;
+import tools.jackson.databind.ObjectMapper;
import io.swagger.v3.oas.annotations.Hidden;
import io.swagger.v3.oas.annotations.tags.Tag;
@@ -167,7 +167,7 @@ public class AiCreateController {
if (request.constraints() != null) {
try {
constraintsPayload = objectMapper.writeValueAsString(request.constraints());
- } catch (JsonProcessingException exc) {
+ } catch (JacksonException exc) {
throw new ResponseStatusException(
HttpStatus.BAD_REQUEST, "Invalid constraints payload", exc);
}
@@ -202,7 +202,7 @@ public class AiCreateController {
String payload;
try {
payload = objectMapper.writeValueAsString(request.draftSections());
- } catch (JsonProcessingException exc) {
+ } catch (JacksonException exc) {
throw new ResponseStatusException(
HttpStatus.BAD_REQUEST, "Invalid draft sections payload", exc);
}
@@ -392,7 +392,7 @@ public class AiCreateController {
objectMapper
.getTypeFactory()
.constructCollectionType(List.class, DraftSection.class));
- } catch (JsonProcessingException exc) {
+ } catch (JacksonException exc) {
log.warn("Failed to parse draft sections payload", exc);
return null;
}
@@ -408,7 +408,7 @@ public class AiCreateController {
objectMapper
.getTypeFactory()
.constructMapType(Map.class, String.class, Object.class));
- } catch (JsonProcessingException exc) {
+ } catch (JacksonException exc) {
log.warn("Failed to parse outline constraints payload", exc);
return null;
}
diff --git a/app/saas/src/main/java/stirling/software/saas/ai/controller/AiCreateInternalController.java b/app/saas/src/main/java/stirling/software/saas/ai/controller/AiCreateInternalController.java
index 60c8dc4615..04b8302e7e 100644
--- a/app/saas/src/main/java/stirling/software/saas/ai/controller/AiCreateInternalController.java
+++ b/app/saas/src/main/java/stirling/software/saas/ai/controller/AiCreateInternalController.java
@@ -14,8 +14,8 @@ import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.server.ResponseStatusException;
-import com.fasterxml.jackson.core.JsonProcessingException;
-import com.fasterxml.jackson.databind.ObjectMapper;
+import tools.jackson.core.JacksonException;
+import tools.jackson.databind.ObjectMapper;
import io.swagger.v3.oas.annotations.Hidden;
import io.swagger.v3.oas.annotations.tags.Tag;
@@ -61,7 +61,7 @@ public class AiCreateInternalController {
try {
outlineConstraintsPayload =
objectMapper.writeValueAsString(request.outlineConstraints());
- } catch (JsonProcessingException exc) {
+ } catch (JacksonException exc) {
throw new ResponseStatusException(
HttpStatus.BAD_REQUEST, "Invalid outline constraints payload", exc);
}
@@ -70,7 +70,7 @@ public class AiCreateInternalController {
if (request.draftSections() != null) {
try {
draftSectionsPayload = objectMapper.writeValueAsString(request.draftSections());
- } catch (JsonProcessingException exc) {
+ } catch (JacksonException exc) {
throw new ResponseStatusException(
HttpStatus.BAD_REQUEST, "Invalid draft sections payload", exc);
}
@@ -136,7 +136,7 @@ public class AiCreateInternalController {
.getTypeFactory()
.constructCollectionType(
List.class, AiCreateController.DraftSection.class));
- } catch (JsonProcessingException exc) {
+ } catch (JacksonException exc) {
log.warn("Failed to parse draft sections payload", exc);
return null;
}
@@ -152,7 +152,7 @@ public class AiCreateInternalController {
objectMapper
.getTypeFactory()
.constructMapType(Map.class, String.class, Object.class));
- } catch (JsonProcessingException exc) {
+ } catch (JacksonException exc) {
log.warn("Failed to parse outline constraints payload", exc);
return null;
}
diff --git a/app/saas/src/main/java/stirling/software/saas/billing/service/StripeUsageReportingService.java b/app/saas/src/main/java/stirling/software/saas/billing/service/StripeUsageReportingService.java
index d9445483a3..ae5d3d943a 100644
--- a/app/saas/src/main/java/stirling/software/saas/billing/service/StripeUsageReportingService.java
+++ b/app/saas/src/main/java/stirling/software/saas/billing/service/StripeUsageReportingService.java
@@ -12,7 +12,7 @@ import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Profile;
import org.springframework.stereotype.Service;
-import com.fasterxml.jackson.databind.ObjectMapper;
+import tools.jackson.databind.ObjectMapper;
import lombok.extern.slf4j.Slf4j;
diff --git a/app/saas/src/main/java/stirling/software/saas/config/SaasSchemaOwnership.java b/app/saas/src/main/java/stirling/software/saas/config/SaasSchemaOwnership.java
index dffd1eccf1..7853c56856 100644
--- a/app/saas/src/main/java/stirling/software/saas/config/SaasSchemaOwnership.java
+++ b/app/saas/src/main/java/stirling/software/saas/config/SaasSchemaOwnership.java
@@ -41,6 +41,7 @@ public final class SaasSchemaOwnership {
*/
public static final Set MIGRATION_OWNED =
Set.of(
+ "account_link_connect_request",
"ai_create_sessions",
"audit_events",
"authorities",
@@ -78,6 +79,7 @@ public final class SaasSchemaOwnership {
*/
public static final Set HIBERNATE_MANAGED =
Set.of(
+ "account_link_connect_state",
"account_link_device_credential",
"account_link_metered_signature",
"account_link_sync_state",
diff --git a/app/saas/src/main/java/stirling/software/saas/legal/LegalDocumentRegistry.java b/app/saas/src/main/java/stirling/software/saas/legal/LegalDocumentRegistry.java
index ffbe030863..48dd6a1c3b 100644
--- a/app/saas/src/main/java/stirling/software/saas/legal/LegalDocumentRegistry.java
+++ b/app/saas/src/main/java/stirling/software/saas/legal/LegalDocumentRegistry.java
@@ -13,8 +13,8 @@ import java.util.regex.Pattern;
import org.springframework.core.io.ClassPathResource;
import org.springframework.stereotype.Service;
-import com.fasterxml.jackson.databind.JsonNode;
-import com.fasterxml.jackson.databind.ObjectMapper;
+import tools.jackson.databind.JsonNode;
+import tools.jackson.databind.ObjectMapper;
import jakarta.annotation.PostConstruct;
@@ -56,28 +56,26 @@ public class LegalDocumentRegistry {
subprocessorUrl = root.path("subprocessorUrl").asText("");
eulaUrl = root.path("eulaUrl").asText("");
JsonNode docs = root.path("documents");
- docs.fieldNames()
- .forEachRemaining(
- id -> {
- JsonNode d = docs.get(id);
- List parts =
- objectMapper.convertValue(
- d.path("parts"),
- objectMapper
- .getTypeFactory()
- .constructCollectionType(
- List.class, String.class));
- documents.put(
+ docs.forEachEntry(
+ (id, d) -> {
+ List parts =
+ objectMapper.convertValue(
+ d.path("parts"),
+ objectMapper
+ .getTypeFactory()
+ .constructCollectionType(
+ List.class, String.class));
+ documents.put(
+ id,
+ new LegalDocumentMeta(
id,
- new LegalDocumentMeta(
- id,
- d.path("label").asText(id),
- d.path("displayName").asText(id),
- d.path("version").asText("0"),
- d.path("effectiveDate").asText(""),
- d.path("status").asText("draft"),
- parts == null ? List.of() : parts));
- });
+ d.path("label").asText(id),
+ d.path("displayName").asText(id),
+ d.path("version").asText("0"),
+ d.path("effectiveDate").asText(""),
+ d.path("status").asText("draft"),
+ parts == null ? List.of() : parts));
+ });
log.info("[legal] loaded {} document(s) from {}", documents.size(), MANIFEST);
}
diff --git a/app/saas/src/main/java/stirling/software/saas/payg/entitlement/EntitlementGuard.java b/app/saas/src/main/java/stirling/software/saas/payg/entitlement/EntitlementGuard.java
index ae8474fa42..441ebf1220 100644
--- a/app/saas/src/main/java/stirling/software/saas/payg/entitlement/EntitlementGuard.java
+++ b/app/saas/src/main/java/stirling/software/saas/payg/entitlement/EntitlementGuard.java
@@ -20,7 +20,7 @@ import org.springframework.stereotype.Component;
import org.springframework.web.method.HandlerMethod;
import org.springframework.web.servlet.HandlerInterceptor;
-import com.fasterxml.jackson.databind.ObjectMapper;
+import tools.jackson.databind.ObjectMapper;
import io.micrometer.core.instrument.Counter;
import io.micrometer.core.instrument.MeterRegistry;
diff --git a/app/saas/src/main/java/stirling/software/saas/payg/instance/InstanceUsageIngestService.java b/app/saas/src/main/java/stirling/software/saas/payg/instance/InstanceUsageIngestService.java
index c672540870..67e9c581d7 100644
--- a/app/saas/src/main/java/stirling/software/saas/payg/instance/InstanceUsageIngestService.java
+++ b/app/saas/src/main/java/stirling/software/saas/payg/instance/InstanceUsageIngestService.java
@@ -18,12 +18,12 @@ import stirling.software.saas.payg.model.ProcessType;
import stirling.software.saas.payg.repository.PaygInstanceUsageRepository;
/**
- * Ingests a linked instance's daily usage sync (combined-billing "Mode A"). The instance reports a
- * monotonic cumulative unit total per {@link BillingCategory}; we bill only the delta since the
- * last sync via {@link JobChargeService#chargeStandalone} (reusing the in-cloud free-grant split,
- * ledger DEBIT, Stripe meter and idempotency). Idempotent (a resend → delta 0 → no charge) and
- * tamper-evident (a backwards total is refused; a monotonic {@code syncSeq} dedups replays). The
- * cap is enforced at the instance gate, not here. Gated behind {@code account-link.enabled}.
+ * Ingests a linked instance's daily usage sync (combined billing). The instance reports a monotonic
+ * cumulative unit total per {@link BillingCategory}; we bill only the delta since the last sync via
+ * {@link JobChargeService#chargeStandalone} (reusing the in-cloud free-grant split, ledger DEBIT,
+ * Stripe meter and idempotency). Idempotent (a resend → delta 0 → no charge) and tamper-evident (a
+ * backwards total is refused; a monotonic {@code syncSeq} dedups replays). The cap is enforced at
+ * the instance gate, not here. Gated behind {@code account-link.enabled}.
*/
@Slf4j
@Service
diff --git a/app/saas/src/main/java/stirling/software/saas/payg/instance/PaygInstanceUsage.java b/app/saas/src/main/java/stirling/software/saas/payg/instance/PaygInstanceUsage.java
index 45a6435746..345cf46b75 100644
--- a/app/saas/src/main/java/stirling/software/saas/payg/instance/PaygInstanceUsage.java
+++ b/app/saas/src/main/java/stirling/software/saas/payg/instance/PaygInstanceUsage.java
@@ -19,9 +19,9 @@ import lombok.Setter;
/**
* Last-seen cumulative usage a linked self-hosted instance has reported for one {@code (team,
- * billing period, category)} (combined-billing "Mode A"). The instance reports monotonic cumulative
- * unit totals on its daily sync; SaaS bills {@code reportedCumulative - lastCumulativeUnits} via
- * the standard charge path and advances this row. {@code lastSyncSeq} dedups replays.
+ * billing period, category)} (combined billing). The instance reports monotonic cumulative unit
+ * totals on its daily sync; SaaS bills {@code reportedCumulative - lastCumulativeUnits} via the
+ * standard charge path and advances this row. {@code lastSyncSeq} dedups replays.
*/
@Entity
@Table(
diff --git a/app/saas/src/main/java/stirling/software/saas/procurement/api/ProcurementController.java b/app/saas/src/main/java/stirling/software/saas/procurement/api/ProcurementController.java
index 1c495b3afd..c08778bdbc 100644
--- a/app/saas/src/main/java/stirling/software/saas/procurement/api/ProcurementController.java
+++ b/app/saas/src/main/java/stirling/software/saas/procurement/api/ProcurementController.java
@@ -18,7 +18,7 @@ import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
-import com.fasterxml.jackson.databind.ObjectMapper;
+import tools.jackson.databind.ObjectMapper;
import io.swagger.v3.oas.annotations.Hidden;
diff --git a/app/saas/src/main/java/stirling/software/saas/procurement/legal/AgreementAssembler.java b/app/saas/src/main/java/stirling/software/saas/procurement/legal/AgreementAssembler.java
index c641f2e596..e75f3cbb32 100644
--- a/app/saas/src/main/java/stirling/software/saas/procurement/legal/AgreementAssembler.java
+++ b/app/saas/src/main/java/stirling/software/saas/procurement/legal/AgreementAssembler.java
@@ -10,7 +10,7 @@ import java.util.Map;
import org.springframework.stereotype.Service;
-import com.fasterxml.jackson.databind.ObjectMapper;
+import tools.jackson.databind.ObjectMapper;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
diff --git a/app/saas/src/main/java/stirling/software/saas/procurement/license/KeygenEnterpriseLicenseService.java b/app/saas/src/main/java/stirling/software/saas/procurement/license/KeygenEnterpriseLicenseService.java
index a11ad05755..a1c09a9cb9 100644
--- a/app/saas/src/main/java/stirling/software/saas/procurement/license/KeygenEnterpriseLicenseService.java
+++ b/app/saas/src/main/java/stirling/software/saas/procurement/license/KeygenEnterpriseLicenseService.java
@@ -16,8 +16,8 @@ import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.context.annotation.Profile;
import org.springframework.stereotype.Service;
-import com.fasterxml.jackson.databind.JsonNode;
-import com.fasterxml.jackson.databind.ObjectMapper;
+import tools.jackson.databind.JsonNode;
+import tools.jackson.databind.ObjectMapper;
import lombok.extern.slf4j.Slf4j;
diff --git a/app/saas/src/main/java/stirling/software/saas/procurement/service/ProcurementService.java b/app/saas/src/main/java/stirling/software/saas/procurement/service/ProcurementService.java
index a739e538b2..26bfb733dd 100644
--- a/app/saas/src/main/java/stirling/software/saas/procurement/service/ProcurementService.java
+++ b/app/saas/src/main/java/stirling/software/saas/procurement/service/ProcurementService.java
@@ -10,8 +10,8 @@ import org.springframework.context.annotation.Profile;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
-import com.fasterxml.jackson.core.JsonProcessingException;
-import com.fasterxml.jackson.databind.ObjectMapper;
+import tools.jackson.core.JacksonException;
+import tools.jackson.databind.ObjectMapper;
import lombok.extern.slf4j.Slf4j;
@@ -707,7 +707,7 @@ public class ProcurementService {
private String writeLineItems(QuoteBreakdown breakdown) {
try {
return OBJECT_MAPPER.writeValueAsString(breakdown.lineItems());
- } catch (JsonProcessingException e) {
+ } catch (JacksonException e) {
log.warn("[procurement] failed to serialise line items", e);
return "[]";
}
diff --git a/app/saas/src/main/java/stirling/software/saas/security/SupabaseSecurityConfig.java b/app/saas/src/main/java/stirling/software/saas/security/SupabaseSecurityConfig.java
index 36f3a4c06e..ea1c9bca9b 100644
--- a/app/saas/src/main/java/stirling/software/saas/security/SupabaseSecurityConfig.java
+++ b/app/saas/src/main/java/stirling/software/saas/security/SupabaseSecurityConfig.java
@@ -16,6 +16,7 @@ import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;
import org.springframework.core.annotation.Order;
+import org.springframework.core.env.Environment;
import org.springframework.http.HttpMethod;
import org.springframework.security.authentication.AbstractAuthenticationToken;
import org.springframework.security.config.Customizer;
@@ -71,6 +72,7 @@ public class SupabaseSecurityConfig {
private final SaasTeamService saasTeamService;
private final ApplicationProperties applicationProperties;
private final ApiKeyAuthenticationService apiKeyAuthenticationService;
+ private final Environment environment;
@Value("${app.supabase.issuer:}")
private String issuer;
@@ -105,6 +107,17 @@ public class SupabaseSecurityConfig {
.permitAll()
.requestMatchers("/actuator/health", "/api/v1/config/**")
.permitAll()
+ // Account-link connect handshake: an instance calls these
+ // before it holds any credential, so there is nothing to
+ // authenticate with yet. Neither grants anything on its
+ // own — /request records an intent a human must approve,
+ // and /claim requires a secret only the instance that
+ // created the request has ever held.
+ .requestMatchers(
+ HttpMethod.POST,
+ "/api/v1/account-link/connect/request",
+ "/api/v1/account-link/connect/claim")
+ .permitAll()
.requestMatchers(
req ->
RequestUriUtils.isStaticResource(
@@ -144,7 +157,7 @@ public class SupabaseSecurityConfig {
SupabaseSecurityConfig
::toAuthentication)));
- // Device-credential auth for linked self-hosted instances (combined-billing Mode A).
+ // Device-credential auth for linked self-hosted instances (combined billing).
// The filter bean exists only when stirling.billing.account-link.enabled=true; when off it
// is absent here, so the instance surface cannot authenticate at all until release.
DeviceCredentialAuthenticationFilter deviceFilter =
@@ -268,6 +281,28 @@ public class SupabaseSecurityConfig {
}
}
+ /**
+ * Loopback on any port, as Spring origin patterns. Only added outside production; see {@link
+ * #corsConfigurationSource()}.
+ */
+ private static final List LOOPBACK_ANY_PORT =
+ List.of("http://localhost:[*]", "http://127.0.0.1:[*]");
+
+ /**
+ * Profiles that mean "a developer's machine or a preview environment", never the production
+ * deployment. Production runs the bare {@code saas} profile.
+ */
+ private static final List NON_PRODUCTION_PROFILES = List.of("dev", "staging", "local");
+
+ private boolean isNonProduction() {
+ for (String profile : environment.getActiveProfiles()) {
+ if (NON_PRODUCTION_PROFILES.contains(profile)) {
+ return true;
+ }
+ }
+ return false;
+ }
+
@Bean
CorsConfigurationSource corsConfigurationSource() {
CorsConfiguration cfg = new CorsConfiguration();
@@ -297,7 +332,23 @@ public class SupabaseSecurityConfig {
origins.add(desktopOrigin);
}
}
- if (origins.stream().anyMatch(o -> o.contains("*"))) {
+ // Outside production, allow loopback on ANY port. Several dev servers run side by side
+ // (editor, saas web app, one per flavour under test) and their ports move, so pinning a
+ // list means every new local environment shows up as an opaque CORS failure. Unlike a
+ // wildcard subdomain, a wildcard port on loopback cannot be taken over: nothing but this
+ // machine can answer on it, so there is no lapsed-DNS or abandoned-vhost risk. Absent in
+ // production, where the profile check below is false.
+ if (!operatorOverride && isNonProduction()) {
+ origins.addAll(LOOPBACK_ANY_PORT);
+ log.info(
+ "Non-production profile active: allowing loopback CORS origins on any port {}",
+ LOOPBACK_ANY_PORT);
+ }
+ // Loopback port wildcards are exempt: the warning below is about hostname takeover, which
+ // does not apply to an origin only this machine can serve.
+ if (origins.stream()
+ .filter(o -> !LOOPBACK_ANY_PORT.contains(o))
+ .anyMatch(o -> o.contains("*"))) {
log.warn(
"CORS origins contain a wildcard paired with allowCredentials=true: {}."
+ " Wildcard subdomains can be taken over by an attacker (lapsed DNS,"
diff --git a/app/saas/src/main/java/stirling/software/saas/service/RateLimitService.java b/app/saas/src/main/java/stirling/software/saas/service/RateLimitService.java
index 775c5862ae..8a006a6934 100644
--- a/app/saas/src/main/java/stirling/software/saas/service/RateLimitService.java
+++ b/app/saas/src/main/java/stirling/software/saas/service/RateLimitService.java
@@ -113,19 +113,13 @@ public class RateLimitService {
public void cleanupExpiredBuckets() {
long now = System.currentTimeMillis();
- int hourlyRemoved =
- (int)
- hourlyLimits.entrySet().stream()
- .filter(e -> e.getValue().getResetTime() < now)
- .peek(e -> hourlyLimits.remove(e.getKey()))
- .count();
+ int hourlyBefore = hourlyLimits.size();
+ hourlyLimits.entrySet().removeIf(e -> e.getValue().getResetTime() < now);
+ int hourlyRemoved = hourlyBefore - hourlyLimits.size();
- int dailyRemoved =
- (int)
- dailyLimits.entrySet().stream()
- .filter(e -> e.getValue().getResetTime() < now)
- .peek(e -> dailyLimits.remove(e.getKey()))
- .count();
+ int dailyBefore = dailyLimits.size();
+ dailyLimits.entrySet().removeIf(e -> e.getValue().getResetTime() < now);
+ int dailyRemoved = dailyBefore - dailyLimits.size();
if (hourlyRemoved + dailyRemoved > 0) {
log.debug(
diff --git a/app/saas/src/main/java/stirling/software/saas/service/SaasTeamService.java b/app/saas/src/main/java/stirling/software/saas/service/SaasTeamService.java
index 0038cca42a..d81e0d9ee7 100644
--- a/app/saas/src/main/java/stirling/software/saas/service/SaasTeamService.java
+++ b/app/saas/src/main/java/stirling/software/saas/service/SaasTeamService.java
@@ -519,8 +519,8 @@ public class SaasTeamService {
* membership and its wallet) rather than deleting it, so a plain team is never orphaned. The
* only real hazard is a team the user is the last leader of that still carries live
* billing: an active paid/PAYG subscription, or a non-revoked linked self-hosted instance
- * ("Mode A"). Those block the join until the plan is cancelled / leadership transferred /
- * instances revoked. An unpaid, unlinked team (personal or shared) no longer blocks.
+ * (combined billing). Those block the join until the plan is cancelled / leadership transferred
+ * / instances revoked. An unpaid, unlinked team (personal or shared) no longer blocks.
*
*
The home team and the team being joined are excluded: neither is left by the join (home is
* parked, the joined team is kept), so their live billing cannot be stranded.
diff --git a/app/saas/src/test/java/stirling/software/saas/accountlink/AccountLinkControllerTest.java b/app/saas/src/test/java/stirling/software/saas/accountlink/AccountLinkControllerTest.java
index e12888edb3..b9c6f22305 100644
--- a/app/saas/src/test/java/stirling/software/saas/accountlink/AccountLinkControllerTest.java
+++ b/app/saas/src/test/java/stirling/software/saas/accountlink/AccountLinkControllerTest.java
@@ -1,6 +1,7 @@
package stirling.software.saas.accountlink;
import static org.assertj.core.api.Assertions.assertThat;
+import static org.mockito.Mockito.verify;
import static org.mockito.Mockito.verifyNoInteractions;
import static org.mockito.Mockito.when;
@@ -23,8 +24,7 @@ import stirling.software.proprietary.model.TeamMembership;
import stirling.software.proprietary.security.database.repository.UserRepository;
import stirling.software.proprietary.security.model.User;
import stirling.software.proprietary.security.repository.TeamMembershipRepository;
-import stirling.software.saas.accountlink.AccountLinkController.RegisterRequest;
-import stirling.software.saas.accountlink.AccountLinkController.RegisterResponse;
+import stirling.software.saas.accountlink.AccountLinkController.InstanceRow;
import stirling.software.saas.util.AuthenticationUtils;
/**
@@ -44,20 +44,27 @@ class AccountLinkControllerTest {
@BeforeEach
void setUp() {
- controller = new AccountLinkController(service, memberRepo, userRepository);
+ // Real resolver over the mocked repositories: the leader ladder moved into
+ // LeaderTeamResolver, and these tests are still asserting that ladder's behaviour
+ // through the controller.
+ controller =
+ new AccountLinkController(
+ service, new LeaderTeamResolver(memberRepo, userRepository));
auth =
new AnonymousAuthenticationToken(
"k", "anonymousUser", List.of(new SimpleGrantedAuthority("ROLE_USER")));
}
+ // The leader ladder used to be asserted through POST /register, which has been removed along
+ // with the JWT relay. It is exercised through /instances instead: same resolver, same rungs.
+
@Test
- void register_unauthenticated_returns401() {
+ void list_unauthenticated_returns401() {
try (var mocked = org.mockito.Mockito.mockStatic(AuthenticationUtils.class)) {
mocked.when(() -> AuthenticationUtils.getCurrentUser(auth, userRepository))
.thenThrow(new SecurityException("not authenticated"));
- ResponseEntity resp =
- controller.register(new RegisterRequest("host"), auth);
+ ResponseEntity> resp = controller.list(auth);
assertThat(resp.getStatusCode()).isEqualTo(HttpStatus.UNAUTHORIZED);
verifyNoInteractions(service);
@@ -65,14 +72,14 @@ class AccountLinkControllerTest {
}
@Test
- void register_noMembership_returns403() {
+ void list_noMembership_returns403() {
User user = mockUser(42L);
try (var mocked = org.mockito.Mockito.mockStatic(AuthenticationUtils.class)) {
mocked.when(() -> AuthenticationUtils.getCurrentUser(auth, userRepository))
.thenReturn(user);
when(memberRepo.findPrimaryMembership(42L)).thenReturn(List.of());
- ResponseEntity resp = controller.register(null, auth);
+ ResponseEntity> resp = controller.list(auth);
assertThat(resp.getStatusCode()).isEqualTo(HttpStatus.FORBIDDEN);
verifyNoInteractions(service);
@@ -80,7 +87,7 @@ class AccountLinkControllerTest {
}
@Test
- void register_nonLeader_returns403() {
+ void list_nonLeader_returns403() {
User user = mockUser(42L);
TeamMembership member = membership(7L, TeamRole.MEMBER);
try (var mocked = org.mockito.Mockito.mockStatic(AuthenticationUtils.class)) {
@@ -88,7 +95,7 @@ class AccountLinkControllerTest {
.thenReturn(user);
when(memberRepo.findPrimaryMembership(42L)).thenReturn(List.of(member));
- ResponseEntity resp = controller.register(null, auth);
+ ResponseEntity> resp = controller.list(auth);
assertThat(resp.getStatusCode()).isEqualTo(HttpStatus.FORBIDDEN);
verifyNoInteractions(service);
@@ -96,27 +103,20 @@ class AccountLinkControllerTest {
}
@Test
- void register_leader_mintsCredentialForCallerTeam() {
+ void list_leader_readsOnlyTheCallersTeam() {
User user = mockUser(42L);
TeamMembership leader = membership(7L, TeamRole.LEADER);
- when(service.register(7L, 42L, "host"))
- .thenReturn(
- new AccountLinkService.RegisteredInstance(99L, "dev-x", "sec-x", "host"));
+ when(service.list(7L)).thenReturn(List.of());
try (var mocked = org.mockito.Mockito.mockStatic(AuthenticationUtils.class)) {
mocked.when(() -> AuthenticationUtils.getCurrentUser(auth, userRepository))
.thenReturn(user);
when(memberRepo.findPrimaryMembership(42L)).thenReturn(List.of(leader));
- ResponseEntity resp =
- controller.register(new RegisterRequest("host"), auth);
+ ResponseEntity> resp = controller.list(auth);
- assertThat(resp.getStatusCode()).isEqualTo(HttpStatus.CREATED);
- RegisterResponse body = resp.getBody();
- assertThat(body).isNotNull();
- // Team comes from the caller's membership and is surfaced in the response.
- assertThat(body.teamId()).isEqualTo(7L);
- assertThat(body.instanceId()).isEqualTo(99L);
- assertThat(body.deviceSecret()).isEqualTo("sec-x");
+ assertThat(resp.getStatusCode()).isEqualTo(HttpStatus.OK);
+ // The team comes from the caller's membership, never from the request.
+ verify(service).list(7L);
}
}
diff --git a/app/saas/src/test/java/stirling/software/saas/accountlink/ConnectControllerTest.java b/app/saas/src/test/java/stirling/software/saas/accountlink/ConnectControllerTest.java
new file mode 100644
index 0000000000..d58c4c4098
--- /dev/null
+++ b/app/saas/src/test/java/stirling/software/saas/accountlink/ConnectControllerTest.java
@@ -0,0 +1,129 @@
+package stirling.software.saas.accountlink;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.anyString;
+import static org.mockito.ArgumentMatchers.isNull;
+import static org.mockito.Mockito.when;
+
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.Mock;
+import org.mockito.junit.jupiter.MockitoExtension;
+import org.mockito.junit.jupiter.MockitoSettings;
+import org.mockito.quality.Strictness;
+import org.springframework.mock.web.MockHttpServletRequest;
+
+import stirling.software.common.model.ApplicationProperties;
+import stirling.software.saas.accountlink.ConnectController.CreateBody;
+import stirling.software.saas.accountlink.ConnectController.CreateResponse;
+
+/**
+ * The authorize URL the instance is told to send its admin to. Everything else on this controller
+ * delegates; this is the only decision it makes on its own.
+ */
+@ExtendWith(MockitoExtension.class)
+@MockitoSettings(strictness = Strictness.LENIENT)
+class ConnectControllerTest {
+
+ private static final CreateBody BODY =
+ new CreateBody("prod-1", "https://pdf.example.com/account-link/callback", "n", "s");
+
+ @Mock private ConnectRequestService service;
+ @Mock private LeaderTeamResolver leaderTeams;
+ @Mock private AccountLinkService accountLinkService;
+
+ private ApplicationProperties applicationProperties;
+ private ConnectController controller;
+
+ @BeforeEach
+ void setUp() {
+ applicationProperties = new ApplicationProperties();
+ controller =
+ new ConnectController(
+ service, leaderTeams, accountLinkService, applicationProperties);
+ when(service.create(anyString(), anyString(), anyString(), anyString(), any()))
+ .thenReturn(ConnectRequestService.CreateResult.ok("req-1", 1800));
+ }
+
+ private String authorizeUrl(MockHttpServletRequest request) {
+ Object body = controller.request(BODY, request).getBody();
+ assertThat(body).isInstanceOf(CreateResponse.class);
+ return ((CreateResponse) body).authorizeUrl();
+ }
+
+ private static MockHttpServletRequest request(String scheme, String host, int port) {
+ MockHttpServletRequest request = new MockHttpServletRequest();
+ request.setScheme(scheme);
+ request.setServerName(host);
+ request.setServerPort(port);
+ return request;
+ }
+
+ @Test
+ void prefersTheConfiguredFrontendUrl() {
+ applicationProperties.getSystem().setFrontendUrl("https://app.example.com/app/");
+
+ // Trailing slash trimmed, base path kept, and the API's own origin ignored.
+ assertThat(authorizeUrl(request("https", "api.example.com", 443)))
+ .isEqualTo("https://app.example.com/app/link?request=req-1");
+ }
+
+ @Test
+ void fallsBackToTheOriginTheApiWasReachedOn() {
+ assertThat(authorizeUrl(request("https", "api.example.com", 443)))
+ .isEqualTo("https://api.example.com/link?request=req-1");
+ }
+
+ @Test
+ void keepsANonDefaultPortAndTheContextPath() {
+ MockHttpServletRequest request = request("http", "localhost", 8081);
+ request.setContextPath("/stirling");
+
+ assertThat(authorizeUrl(request))
+ .isEqualTo("http://localhost:8081/stirling/link?request=req-1");
+ }
+
+ @Test
+ void honoursTheForwardedSchemeAndHost() {
+ MockHttpServletRequest request = request("http", "10.0.0.5", 8080);
+ request.addHeader("X-Forwarded-Proto", "https");
+ request.addHeader("X-Forwarded-Host", "api.example.com");
+
+ assertThat(authorizeUrl(request)).isEqualTo("https://api.example.com/link?request=req-1");
+ }
+
+ @Test
+ void takesOnlyTheFirstForwardedHop() {
+ MockHttpServletRequest request = request("http", "10.0.0.5", 8080);
+ request.addHeader("X-Forwarded-Proto", "https, http");
+ request.addHeader("X-Forwarded-Host", "api.example.com, evil.example.com");
+
+ assertThat(authorizeUrl(request)).isEqualTo("https://api.example.com/link?request=req-1");
+ }
+
+ @Test
+ void percentEncodesTheRequestId() {
+ when(service.create(anyString(), anyString(), anyString(), anyString(), any()))
+ .thenReturn(ConnectRequestService.CreateResult.ok("a b&c", 1800));
+
+ assertThat(authorizeUrl(request("https", "api.example.com", 443)))
+ .isEqualTo("https://api.example.com/link?request=a+b%26c");
+ }
+
+ @Test
+ void aBodylessRequestIsRejectedBeforeAnythingIsRecorded() {
+ assertThat(controller.request(null, request("https", "api.example.com", 443)).getBody())
+ .isEqualTo(java.util.Map.of("error", "BAD_REQUEST"));
+ }
+
+ @Test
+ void offeringNoCredentialTakesTheFirstLinkPath() {
+ authorizeUrl(request("https", "api.example.com", 443));
+
+ // createReauth is the credentialled path; a first link must not reach it.
+ org.mockito.Mockito.verify(service, org.mockito.Mockito.never())
+ .createReauth(anyString(), anyString(), anyString(), anyString(), any(), isNull());
+ }
+}
diff --git a/app/saas/src/test/java/stirling/software/saas/accountlink/ConnectRequestServiceTest.java b/app/saas/src/test/java/stirling/software/saas/accountlink/ConnectRequestServiceTest.java
new file mode 100644
index 0000000000..f75c96becb
--- /dev/null
+++ b/app/saas/src/test/java/stirling/software/saas/accountlink/ConnectRequestServiceTest.java
@@ -0,0 +1,358 @@
+package stirling.software.saas.accountlink;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.anyLong;
+import static org.mockito.ArgumentMatchers.anyString;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.verifyNoInteractions;
+import static org.mockito.Mockito.when;
+
+import java.time.LocalDateTime;
+import java.util.Optional;
+
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.ValueSource;
+import org.mockito.ArgumentCaptor;
+import org.mockito.Mock;
+import org.mockito.junit.jupiter.MockitoExtension;
+import org.mockito.junit.jupiter.MockitoSettings;
+import org.mockito.quality.Strictness;
+
+import stirling.software.saas.accountlink.ConnectRequestService.ClaimOutcome;
+import stirling.software.saas.accountlink.ConnectRequestService.CreateRejection;
+
+/**
+ * Unit tests for the connect handshake's security properties, which are the reason this flow is
+ * safe rather than an open redirect: the callback is validated once and then read back from
+ * storage, the claim secret authenticates the collection, and one approval mints exactly one
+ * credential.
+ */
+@ExtendWith(MockitoExtension.class)
+@MockitoSettings(strictness = Strictness.LENIENT)
+class ConnectRequestServiceTest {
+
+ private static final String CALLBACK = "https://pdf.example.com/account-link/callback";
+ private static final String NONCE = "nonce-value";
+ private static final String CLAIM_SECRET = "claim-secret-value";
+
+ @Mock private ConnectRequestRepository repo;
+ @Mock private AccountLinkService accountLinkService;
+
+ private ConnectRequestService service;
+
+ @BeforeEach
+ void setUp() {
+ service = new ConnectRequestService(repo, accountLinkService);
+ }
+
+ @Test
+ void create_storesTheValidatedCallbackAndItsOrigin() {
+ ConnectRequestService.CreateResult result =
+ service.create("prod-1", CALLBACK, NONCE, CLAIM_SECRET, "10.0.0.1");
+
+ assertThat(result.isRejected()).isFalse();
+ assertThat(result.requestId()).isNotBlank();
+
+ ArgumentCaptor saved = ArgumentCaptor.forClass(ConnectRequest.class);
+ verify(repo).save(saved.capture());
+ ConnectRequest row = saved.getValue();
+ assertThat(row.getCallbackUrl()).isEqualTo(CALLBACK);
+ assertThat(row.getCallbackOrigin()).isEqualTo("https://pdf.example.com");
+ assertThat(row.getStatus()).isEqualTo(ConnectRequest.Status.PENDING);
+ assertThat(row.getName()).isEqualTo("prod-1");
+ // The claim secret is only ever stored as a hash.
+ assertThat(row.getClaimSecretHash()).isNotEqualTo(CLAIM_SECRET).hasSize(64);
+ }
+
+ @Test
+ void create_keepsANonDefaultPortInTheOrigin() {
+ service.create(
+ null, "http://pdf.internal:8080/account-link/callback", NONCE, CLAIM_SECRET, null);
+
+ ArgumentCaptor saved = ArgumentCaptor.forClass(ConnectRequest.class);
+ verify(repo).save(saved.capture());
+ assertThat(saved.getValue().getCallbackOrigin()).isEqualTo("http://pdf.internal:8080");
+ }
+
+ @ParameterizedTest
+ @ValueSource(
+ strings = {
+ "/account-link/callback", // not absolute
+ "ftp://pdf.example.com/cb", // wrong scheme
+ "javascript:alert(1)", // not a hierarchical http(s) URL
+ "https://user:pw@pdf.example.com/cb", // credentials in the URL
+ "https://pdf.example.com/cb#already", // would collide with our fragment
+ "https:///cb" // no host
+ })
+ void create_refusesCallbacksWeWouldNotWantToRedirectTo(String callback) {
+ ConnectRequestService.CreateResult result =
+ service.create(null, callback, NONCE, CLAIM_SECRET, null);
+
+ assertThat(result.rejection()).isEqualTo(CreateRejection.BAD_CALLBACK);
+ verify(repo, never()).save(any());
+ }
+
+ @Test
+ void create_refusesAMissingNonce() {
+ assertThat(service.create(null, CALLBACK, " ", CLAIM_SECRET, null).rejection())
+ .isEqualTo(CreateRejection.BAD_NONCE);
+ verify(repo, never()).save(any());
+ }
+
+ @Test
+ void create_namesTheSecretWhenTheSecretIsWhatIsMissing() {
+ assertThat(service.create(null, CALLBACK, NONCE, " ", null).rejection())
+ .isEqualTo(CreateRejection.BAD_SECRET);
+ verify(repo, never()).save(any());
+ }
+
+ @Test
+ void create_isCappedPerSourceAddress() {
+ when(repo.countByRequesterIpAndCreatedAtAfter(anyString(), any()))
+ .thenReturn((long) ConnectRequestService.MAX_REQUESTS_PER_IP);
+
+ ConnectRequestService.CreateResult result =
+ service.create(null, CALLBACK, NONCE, CLAIM_SECRET, "10.0.0.1");
+
+ assertThat(result.rejection()).isEqualTo(CreateRejection.RATE_LIMITED);
+ verify(repo, never()).save(any());
+ }
+
+ @Test
+ void lookup_flagsPlaintextTransportSoTheApproverCanSeeIt() {
+ ConnectRequest row = pending();
+ row.setCallbackOrigin("http://pdf.internal:8080");
+ when(repo.findByRequestId("req")).thenReturn(Optional.of(row));
+
+ assertThat(service.lookup("req")).get().extracting("insecureTransport").isEqualTo(true);
+ }
+
+ @Test
+ void lookup_hidesAnExpiredHandshake() {
+ ConnectRequest row = pending();
+ row.setExpiresAt(LocalDateTime.now().minusMinutes(1));
+ when(repo.findByRequestId("req")).thenReturn(Optional.of(row));
+
+ assertThat(service.lookup("req")).isEmpty();
+ }
+
+ @Test
+ void approve_bindsTheTeamAndReturnsTheStoredCallback() {
+ ConnectRequest row = pending();
+ when(repo.findByRequestIdForUpdate("req")).thenReturn(Optional.of(row));
+
+ ConnectRequestService.ApproveResult result = service.approve("req", 7L, 42L);
+
+ assertThat(result.isRejected()).isFalse();
+ // The destination comes from the row, never from the caller.
+ assertThat(result.target().callbackUrl()).isEqualTo(CALLBACK);
+ assertThat(result.target().nonce()).isEqualTo(NONCE);
+ assertThat(row.getStatus()).isEqualTo(ConnectRequest.Status.APPROVED);
+ assertThat(row.getTeamId()).isEqualTo(7L);
+ assertThat(row.getApprovedByUserId()).isEqualTo(42L);
+ // Approval on its own must not mint anything.
+ verifyNoInteractions(accountLinkService);
+ }
+
+ @Test
+ void approve_isSingleUse() {
+ ConnectRequest row = pending();
+ row.setStatus(ConnectRequest.Status.APPROVED);
+ when(repo.findByRequestIdForUpdate("req")).thenReturn(Optional.of(row));
+
+ assertThat(service.approve("req", 7L, 42L).isRejected()).isTrue();
+ }
+
+ @Test
+ void approve_refusesAnExpiredHandshake() {
+ ConnectRequest row = pending();
+ row.setExpiresAt(LocalDateTime.now().minusSeconds(1));
+ when(repo.findByRequestIdForUpdate("req")).thenReturn(Optional.of(row));
+
+ assertThat(service.approve("req", 7L, 42L).isRejected()).isTrue();
+ }
+
+ @Test
+ void createReauth_pinsTheTeamItWasToldByTheCredential() {
+ ConnectRequestService.CreateResult result =
+ service.createReauth(null, CALLBACK, NONCE, CLAIM_SECRET, null, 7L);
+
+ assertThat(result.isRejected()).isFalse();
+ ArgumentCaptor saved = ArgumentCaptor.forClass(ConnectRequest.class);
+ verify(repo).save(saved.capture());
+ assertThat(saved.getValue().getMode()).isEqualTo(ConnectRequest.Mode.REAUTH);
+ assertThat(saved.getValue().getTeamId()).isEqualTo(7L);
+ }
+
+ @Test
+ void createReauth_withoutAnAuthenticatedInstanceIsRefused() {
+ // The controller passes null when the offered device credential did not authenticate.
+ assertThat(
+ service.createReauth(null, CALLBACK, NONCE, CLAIM_SECRET, null, null)
+ .rejection())
+ .isEqualTo(CreateRejection.NOT_LINKED);
+ verify(repo, never()).save(any());
+ }
+
+ @Test
+ void create_leavesTheTeamOpenForAFirstLink() {
+ service.create("n", CALLBACK, NONCE, CLAIM_SECRET, null);
+
+ ArgumentCaptor saved = ArgumentCaptor.forClass(ConnectRequest.class);
+ verify(repo).save(saved.capture());
+ assertThat(saved.getValue().getMode()).isEqualTo(ConnectRequest.Mode.LINK);
+ // Approval is what decides the team on a first link.
+ assertThat(saved.getValue().getTeamId()).isNull();
+ }
+
+ @Test
+ void approve_refusesAnApproverFromADifferentTeam() {
+ ConnectRequest row = reauthPinnedTo(7L);
+ when(repo.findByRequestIdForUpdate("req")).thenReturn(Optional.of(row));
+
+ ConnectRequestService.ApproveResult result = service.approve("req", 99L, 42L);
+
+ // This is the "signed in to the wrong account" case, and it must not silently rebind.
+ assertThat(result.rejection()).isEqualTo(ConnectRequestService.ApproveRejection.WRONG_TEAM);
+ assertThat(row.getStatus()).isEqualTo(ConnectRequest.Status.PENDING);
+ assertThat(row.getTeamId()).isEqualTo(7L);
+ }
+
+ @Test
+ void approve_acceptsTheTeamTheServerAlreadyBelongsTo() {
+ ConnectRequest row = reauthPinnedTo(7L);
+ when(repo.findByRequestIdForUpdate("req")).thenReturn(Optional.of(row));
+
+ assertThat(service.approve("req", 7L, 42L).isRejected()).isFalse();
+ assertThat(row.getStatus()).isEqualTo(ConnectRequest.Status.APPROVED);
+ }
+
+ @Test
+ void claim_onAReauthConfirmsWithoutMintingASecondCredential() {
+ ConnectRequest row = reauthPinnedTo(7L);
+ row.setStatus(ConnectRequest.Status.APPROVED);
+ row.setApprovedByUserId(42L);
+ when(repo.findByRequestIdForUpdate("req")).thenReturn(Optional.of(row));
+
+ ConnectRequestService.ClaimResult result = service.claim("req", CLAIM_SECRET);
+
+ assertThat(result.outcome()).isEqualTo(ClaimOutcome.CONFIRMED);
+ assertThat(result.deviceId()).isNull();
+ assertThat(result.deviceSecret()).isNull();
+ assertThat(result.teamId()).isEqualTo(7L);
+ assertThat(row.getStatus()).isEqualTo(ConnectRequest.Status.CONSUMED);
+ // A second credential would orphan the one the instance already holds.
+ verifyNoInteractions(accountLinkService);
+ }
+
+ @Test
+ void claim_mintsOnceForAnApprovedHandshake() {
+ ConnectRequest row = approved();
+ when(repo.findByRequestIdForUpdate("req")).thenReturn(Optional.of(row));
+ when(accountLinkService.register(anyLong(), anyLong(), any()))
+ .thenReturn(
+ new AccountLinkService.RegisteredInstance(9L, "dev-id", "dev-secret", "n"));
+
+ ConnectRequestService.ClaimResult result = service.claim("req", CLAIM_SECRET);
+
+ assertThat(result.outcome()).isEqualTo(ClaimOutcome.GRANTED);
+ assertThat(result.deviceId()).isEqualTo("dev-id");
+ assertThat(result.deviceSecret()).isEqualTo("dev-secret");
+ assertThat(result.teamId()).isEqualTo(7L);
+ assertThat(row.getStatus()).isEqualTo(ConnectRequest.Status.CONSUMED);
+ verify(accountLinkService).register(7L, 42L, "n");
+ }
+
+ @Test
+ void claim_refusesASecondCollection() {
+ ConnectRequest row = approved();
+ row.setStatus(ConnectRequest.Status.CONSUMED);
+ when(repo.findByRequestIdForUpdate("req")).thenReturn(Optional.of(row));
+
+ assertThat(service.claim("req", CLAIM_SECRET).outcome()).isEqualTo(ClaimOutcome.REJECTED);
+ verifyNoInteractions(accountLinkService);
+ }
+
+ @Test
+ void claim_withTheWrongSecretMintsNothing() {
+ ConnectRequest row = approved();
+ when(repo.findByRequestIdForUpdate("req")).thenReturn(Optional.of(row));
+
+ assertThat(service.claim("req", "not-the-secret").outcome())
+ .isEqualTo(ClaimOutcome.REJECTED);
+ assertThat(row.getStatus()).isEqualTo(ConnectRequest.Status.APPROVED);
+ verifyNoInteractions(accountLinkService);
+ }
+
+ @Test
+ void claim_beforeApprovalTellsTheInstanceToWait() {
+ when(repo.findByRequestIdForUpdate("req")).thenReturn(Optional.of(pending()));
+
+ assertThat(service.claim("req", CLAIM_SECRET).outcome()).isEqualTo(ClaimOutcome.PENDING);
+ verifyNoInteractions(accountLinkService);
+ }
+
+ @Test
+ void claim_afterDenialIsTerminal() {
+ ConnectRequest row = pending();
+ row.setStatus(ConnectRequest.Status.DENIED);
+ when(repo.findByRequestIdForUpdate("req")).thenReturn(Optional.of(row));
+
+ assertThat(service.claim("req", CLAIM_SECRET).outcome()).isEqualTo(ClaimOutcome.REJECTED);
+ verifyNoInteractions(accountLinkService);
+ }
+
+ @Test
+ void claim_onAnExpiredHandshakeMintsNothing() {
+ ConnectRequest row = approved();
+ row.setExpiresAt(LocalDateTime.now().minusSeconds(1));
+ when(repo.findByRequestIdForUpdate("req")).thenReturn(Optional.of(row));
+
+ assertThat(service.claim("req", CLAIM_SECRET).outcome()).isEqualTo(ClaimOutcome.REJECTED);
+ verifyNoInteractions(accountLinkService);
+ }
+
+ @Test
+ void claim_forAnUnknownIdLooksTheSameAsABadSecret() {
+ when(repo.findByRequestIdForUpdate("nope")).thenReturn(Optional.empty());
+
+ assertThat(service.claim("nope", CLAIM_SECRET).outcome()).isEqualTo(ClaimOutcome.REJECTED);
+ }
+
+ // ---------------------------------------------------------------------------------------
+
+ private static ConnectRequest pending() {
+ ConnectRequest row = new ConnectRequest();
+ row.setRequestId("req");
+ row.setName("n");
+ row.setCallbackUrl(CALLBACK);
+ row.setCallbackOrigin("https://pdf.example.com");
+ row.setNonce(NONCE);
+ row.setClaimSecretHash(AccountLinkService.sha256Hex(CLAIM_SECRET));
+ row.setStatus(ConnectRequest.Status.PENDING);
+ row.setExpiresAt(LocalDateTime.now().plusMinutes(10));
+ return row;
+ }
+
+ /** A re-authentication whose team came from the instance's credential, not from a browser. */
+ private static ConnectRequest reauthPinnedTo(Long teamId) {
+ ConnectRequest row = pending();
+ row.setMode(ConnectRequest.Mode.REAUTH);
+ row.setTeamId(teamId);
+ return row;
+ }
+
+ private static ConnectRequest approved() {
+ ConnectRequest row = pending();
+ row.setStatus(ConnectRequest.Status.APPROVED);
+ row.setTeamId(7L);
+ row.setApprovedByUserId(42L);
+ row.setApprovedAt(LocalDateTime.now());
+ return row;
+ }
+}
diff --git a/app/saas/src/test/java/stirling/software/saas/payg/entitlement/EntitlementGuardTest.java b/app/saas/src/test/java/stirling/software/saas/payg/entitlement/EntitlementGuardTest.java
index 0a77de3e7e..a9ca7642a6 100644
--- a/app/saas/src/test/java/stirling/software/saas/payg/entitlement/EntitlementGuardTest.java
+++ b/app/saas/src/test/java/stirling/software/saas/payg/entitlement/EntitlementGuardTest.java
@@ -28,8 +28,8 @@ import org.springframework.security.core.context.SecurityContextHolder;
import org.springframework.security.oauth2.jwt.Jwt;
import org.springframework.web.method.HandlerMethod;
-import com.fasterxml.jackson.databind.JsonNode;
-import com.fasterxml.jackson.databind.ObjectMapper;
+import tools.jackson.databind.JsonNode;
+import tools.jackson.databind.ObjectMapper;
import io.micrometer.core.instrument.MeterRegistry;
import io.micrometer.core.instrument.simple.SimpleMeterRegistry;
diff --git a/app/saas/src/test/java/stirling/software/saas/security/SupabaseSecurityConfigMoreTest.java b/app/saas/src/test/java/stirling/software/saas/security/SupabaseSecurityConfigMoreTest.java
index da719e7ba5..4727d78463 100644
--- a/app/saas/src/test/java/stirling/software/saas/security/SupabaseSecurityConfigMoreTest.java
+++ b/app/saas/src/test/java/stirling/software/saas/security/SupabaseSecurityConfigMoreTest.java
@@ -14,6 +14,8 @@ import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;
import org.mockito.Mock;
import org.mockito.junit.jupiter.MockitoExtension;
+import org.springframework.core.env.Environment;
+import org.springframework.mock.env.MockEnvironment;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.oauth2.jwt.Jwt;
import org.springframework.security.oauth2.jwt.JwtDecoder;
@@ -48,13 +50,19 @@ class SupabaseSecurityConfigMoreTest {
apiKeyAuthenticationService;
private SupabaseSecurityConfig config(ApplicationProperties props) {
+ return config(props, new MockEnvironment());
+ }
+
+ /** Loopback CORS origins are only added outside production, so the environment decides. */
+ private SupabaseSecurityConfig config(ApplicationProperties props, Environment environment) {
return new SupabaseSecurityConfig(
userService,
teamService,
supabaseUserService,
saasTeamService,
props,
- apiKeyAuthenticationService);
+ apiKeyAuthenticationService,
+ environment);
}
@Nested
@@ -204,6 +212,50 @@ class SupabaseSecurityConfigMoreTest {
.hasSize(1);
}
+ @Test
+ @DisplayName("production does not allow loopback on arbitrary ports")
+ void productionHasNoLoopbackWildcard() {
+ CorsConfiguration cfg =
+ cors(config(new ApplicationProperties()).corsConfigurationSource());
+
+ assertThat(cfg.getAllowedOriginPatterns())
+ .doesNotContain("http://localhost:[*]", "http://127.0.0.1:[*]");
+ }
+
+ @Test
+ @DisplayName("non-production allows loopback on any port so dev servers can move")
+ void devAllowsAnyLoopbackPort() {
+ // Several dev servers run side by side and their ports change; pinning a list turns
+ // every new local environment into an opaque CORS failure.
+ MockEnvironment dev = new MockEnvironment();
+ dev.setActiveProfiles("saas", "dev");
+
+ CorsConfiguration cfg =
+ cors(config(new ApplicationProperties(), dev).corsConfigurationSource());
+
+ assertThat(cfg.getAllowedOriginPatterns())
+ .contains("http://localhost:[*]", "http://127.0.0.1:[*]")
+ // Still credentialed, which is the reason the pattern form matters.
+ .contains("https://stirling.com");
+ assertThat(cfg.getAllowCredentials()).isTrue();
+ }
+
+ @Test
+ @DisplayName("an operator origin list is respected verbatim even in dev")
+ void operatorOverrideSuppressesLoopbackWildcard() {
+ ApplicationProperties props = new ApplicationProperties();
+ props.getSystem().setCorsAllowedOrigins(List.of("https://custom.example.com"));
+ MockEnvironment dev = new MockEnvironment();
+ dev.setActiveProfiles("saas", "dev");
+
+ CorsConfiguration cfg = cors(config(props, dev).corsConfigurationSource());
+
+ // An operator who set the list meant it; we do not widen it behind their back.
+ assertThat(cfg.getAllowedOriginPatterns())
+ .contains("https://custom.example.com")
+ .doesNotContain("http://localhost:[*]");
+ }
+
@Test
@DisplayName("operator override replaces the default origin list")
void operatorOverrideUsed() {
diff --git a/build.gradle b/build.gradle
index 6382e75c12..fdc59f3680 100644
--- a/build.gradle
+++ b/build.gradle
@@ -42,7 +42,7 @@ ext {
bucket4jVersion = "8.19.0"
archunitVersion = "1.4.2"
batikVersion = "1.19"
- jpdfiumVersion = "1.0.4"
+ jpdfiumVersion = "1.1.3"
jwtVersion = "0.13.0"
awsSdkVersion = "2.51.3"
jschVersion = "2.28.6"
@@ -265,7 +265,6 @@ subprojects {
dependencies {
implementation 'org.springframework.boot:spring-boot-starter-actuator'
- implementation 'io.github.pixee:java-security-toolkit:1.2.3'
//tmp for security bumps
implementation "ch.qos.logback:logback-core:$logback"
@@ -307,7 +306,7 @@ subprojects {
systemProperty 'apple.awt.UIElement', 'true'
testLogging {
- events "started", "failed"
+ events "skipped", "failed"
showExceptions = true
showCauses = true
showStackTraces = true
@@ -543,6 +542,13 @@ subprojects {
}
}
+ // Lazy initialization defers bean creation until first use,
+ // reducing dev-mode RSS significantly (heap drops ~40-60%).
+ // Enable with: ./gradlew bootRun -PlazyInit=true
+ if (rootProject.findProperty('lazyInit') == 'true') {
+ runtimeArgs.add("-Dspring.main.lazy-initialization=true")
+ logger.lifecycle("Lazy initialization enabled (-PlazyInit=true)")
+ }
jvmArgs = runtimeArgs
}
}
diff --git a/devGuide/CODE_COMMENTS.md b/devGuide/CODE_COMMENTS.md
new file mode 100644
index 0000000000..739744142f
--- /dev/null
+++ b/devGuide/CODE_COMMENTS.md
@@ -0,0 +1,232 @@
+# Code comments
+
+A comment must carry information the code cannot. If a reader could derive it from
+the code in front of them, delete it: a redundant comment still has to be
+maintained, will eventually contradict the code, and dilutes the comments that
+matter.
+
+The operative rules are in `AGENTS.md`, kept short so they stay in an agent's
+context. This document is the reasoning and the worked examples behind them, plus
+how to run the linter.
+
+## Comment the current state
+
+Describe the code as it is. Not what it used to be, not what changed, not why it
+changed. A comment that narrates history is stale the moment the next change
+lands, and git already holds that record.
+
+When you know the history and it explains the shape of the code, the useful half is
+the reason, not the sequence. State the reason:
+
+```java
+// Don't:
+// This used to reimplement the modal internals, which is how the procurement
+// dialogs drifted from the billing ones.
+
+// Do:
+// Thin wrapper over the shared Modal: duplicating its portal and focus trap is
+// how dialogs drift apart.
+```
+
+Future state is the exception, and it belongs in a TODO with an issue.
+
+## The four jobs
+
+**Contract.** What a caller must know that the signature cannot say:
+preconditions, invariants, units, ownership and lifetime, thread-safety, error
+semantics, side effects.
+
+The bound is the surface, not the volume: document the contract of everything a
+caller outside the file can reach, and nothing else. Inside that surface say
+whatever a caller needs; outside it a comment earns its place on the same terms as
+any other.
+
+```java
+/**
+ * Authority on which filesystem locations a policy may read or write. Fail-closed
+ * in order: denied entirely under the saas profile; Stirling's own config dir is
+ * always rejected; the path must resolve within policies.allowedFolderRoots.
+ *
+ *
Compared after normalisation so {@code ..} cannot escape a root. Symlink
+ * escape is not defended: an operator who roots an allowlist on a symlink to a
+ * sensitive location is trusted.
+ */
+```
+
+**Why.** The constraint the code satisfies, the bug it avoids, the alternative
+rejected and the reason.
+
+```java
+// whenComplete runs on the worker thread after the run finishes, so the
+// terminal event never races the step events.
+handle.completion()
+```
+
+A reference is supplementary, never load-bearing: the comment must survive
+deleting it. `// See #1234` is a dead end.
+
+```java
+// flatten() reads the annotation list that save() clears, so saving first loses
+// every annotation (#6865).
+document.flatten(annotations);
+```
+
+Prefer a spec (`RFC 3161`, `ISO 4217`) or a CVE where one applies. Both are
+immutable; a ticket can be closed, moved or made private.
+
+**Hazard.** "Must stay in sync with X." "Order matters because Y." "Do not remove,
+it prevents Z."
+
+**Map.** A short orientation at the head of a genuinely complex file: what it owns,
+and what it deliberately does not.
+
+## The test that decides it
+
+A comment earns its place when it sits at a different level of detail than the line
+below it: lower, stating a precise fact the code implies but does not say, or
+higher, giving intent a reader would otherwise assemble from ten lines.
+Same-altitude is the definition of redundant.
+
+- **Delete it.** Is any information lost? If not, it stays deleted.
+- **Could a name carry it instead?** A better identifier, an extracted function or
+ a named constant beats a comment. Prefer the code change.
+
+## What not to write
+
+| Don't | Instead |
+| --- | --- |
+| `// Handle drag start` above `handleDragStart` | Nothing. The name already says it. |
+| `// ─── Types ───`, `// Helpers`, `// ====` | If a file needs internal signposting, split the file. |
+| `// Step 1:` narrating a function body | Extract functions. If the steps need labels they need names. |
+| `// No longer needed`, `// Previously this used X` | State why the code is as it is now, or nothing. |
+| Commented-out code | Delete it. Git remembers. |
+| `@param blob - The blob to download` | Omit the tag rather than pad it. |
+| Docs on a self-explanatory member | Nothing, unless there is a real constraint to state. |
+
+Step numbering is fine where it labels a genuinely numbered thing, such as a wizard
+step or a step in a written test procedure. It is narration when it numbers the
+lines of one function.
+
+## Comments at the end of a line
+
+A trailing comment usually does a different job from one above the code: it decodes
+the line it sits on. Those are worth keeping, and the linter leaves them alone.
+
+```java
+byte[] pdfBytes = {0x25, 0x50, 0x44, 0x46}; // "%PDF"
+long maxAttachmentSize = 50L * 1024 * 1024; // 50 MB
+double buffer = 0.10; // 10% headroom
+default -> toBytes(value, 2); // MB
+```
+
+Each overlaps in words with the code and each adds the interpretation the code
+leaves implicit, which is the lower-altitude case the test above asks for. So
+`CMT001` does not judge trailing comments; on this codebase it would have been
+wrong about roughly six in seven of them.
+
+What still applies is anything that does not depend on the code below: a trailing
+`// TODO fix this` is as unowned as one on its own line, and a trailing
+`// this used to run before the flush` narrates history wherever it sits.
+
+A comment block over about 12 lines, outside a file or type header, is usually a
+sign the code needs restructuring. If it is genuinely product documentation, it
+belongs in the docs repo.
+
+## TODOs
+
+A TODO needs an issue, because an issue is the only part that will close it:
+
+```java
+// TODO(#1234): re-enable the checkout gate once account syncing lands
+```
+
+An owner is not a substitute: a username goes stale when someone changes team and
+means nothing to an outside contributor. If the work is not worth an issue it is
+not worth a TODO, and the options are to do it now or leave the code alone. A
+question is not a TODO.
+
+## Per language
+
+**Java.** Google Java Style, which this repo already formats to. Its §7.3.1
+exception applies: omit Javadoc on a self-explanatory member where there is
+genuinely nothing to add, but do not cite it to skip something a reader needs.
+Summary fragments are noun or verb phrases, not sentences starting "This method
+returns".
+
+**TypeScript.** JSDoc on the `@app/*` seams, exported hooks, and anything crossing
+a layer boundary. No `@param`/`@returns` that restates a typed signature. JSX
+comments follow the same rules as any other.
+
+**Python.** Docstrings on modules, public functions and Pydantic models where the
+contract is not obvious from the type.
+
+## The linter
+
+```bash
+task comment-lint # what the working tree adds over HEAD
+task comment-lint:branch # what the branch adds over origin/main (BASE= to change)
+task pre-commit:comment-lint:ci # the fixture corpus, then the diff
+```
+
+`comment-lint` is the pre-commit question, so it reports nothing once you have
+committed; on a CI pull request it compares against the target branch via
+`GITHUB_BASE_REF`. `comment-lint:branch` is the review question. The corpus checks
+the rules themselves rather than the code under review, so it runs on CI and before
+a rule change, not on every local commit.
+
+`task comment-lint` also runs inside `task pre-commit`, and as a Claude Code `Stop`
+hook, so an agent is told before it finishes a turn and fixes the comment inside
+that turn. Stop rather than per file write: a run costs the same for one file as for
+twenty-five, and half of all writes in a turn go to a file already written in it.
+
+Findings are scoped to comment text that is new, not to lines git calls new, so
+reindenting or moving code does not resurface comments you did not write.
+
+The rules are the `RULES` object in
+[`scripts/lint/comment-rules.mjs`](../scripts/lint/comment-rules.mjs); the exact
+condition for each is the predicate of the same name in that file, with the
+readings it deliberately excludes beside it.
+
+**Every rule blocks.** A rule that only warns is a rule nobody acts on. So a
+finding you believe is wrong is a bug in the rule, not something to live with:
+narrow the rule, or mark the line and say why.
+
+Every comment form the repo writes is covered: `//` and `/* */`, Javadoc and JSDoc,
+JSX comments, `#`, and Python docstrings. `CMT007` reads all three parameter
+conventions in use here, Javadoc/JSDoc `@param`, Sphinx `:param name:` and Google
+`name: description` under `Args:`.
+
+Two engines, one rule set. `.ts`/`.tsx`/`.mjs` go to an oxlint JS plugin, so
+comments come from the parser: a `//` inside a string is not a comment, and JSX
+`{/* … */}` is. `.java`/`.py` go to a line scanner. Neither reads the other's
+files, so they cannot disagree about one file. `scripts/lint/fixtures/` is the
+corpus that keeps them meaning the same thing.
+
+### When a finding is wrong
+
+Name the rule on the line above:
+
+```ts
+// comment-lint-allow: CMT002
+// ─── kept deliberately, because ───
+```
+
+There is no form that disables every rule, and the directive has to earn its
+place. `CMT008` reports one that names something which is not a rule, and one that
+silences nothing, so a typo does not read as a suppression and a stale
+suppression does not sit there blinding the line. The whole comment must be the
+directive; prose that mentions the syntax is just prose.
+
+If you reach for this more than occasionally the rule is wrong: fix it in
+`comment-rules.mjs` and update the fixture corpus in the same commit, so the diff
+shows what moved.
+
+### The existing backlog
+
+`task pre-commit:comment-lint:all` reports the whole tree and never fails. There is
+a standing backlog being cleared by directory; diff scoping is what keeps it off
+whoever touches a file first.
+
+To turn the editor hook off, put `{ "env": { "COMMENT_LINT_HOOK": "0" } }` in
+`.claude/settings.local.json`. The commit-time gate still applies, so you lose the
+early warning rather than the check.
diff --git a/devGuide/README.md b/devGuide/README.md
index 5e8486f013..2ddaff63c3 100644
--- a/devGuide/README.md
+++ b/devGuide/README.md
@@ -8,6 +8,7 @@ This directory contains all development-related documentation for Stirling PDF.
- **[DeveloperGuide.md](../DeveloperGuide.md)** - Main developer setup and architecture guide (in repo root)
- **[Taskfile.yml](../Taskfile.yml)** - Unified task runner for all build/dev/test/lint commands
- **[EXCEPTION_HANDLING_GUIDE.md](./EXCEPTION_HANDLING_GUIDE.md)** - Exception handling patterns and i18n best practices
+- **[CODE_COMMENTS.md](./CODE_COMMENTS.md)** - What a comment is for, what not to write, and the `task comment-lint` rules
- **[HowToAddNewLanguage.md](./HowToAddNewLanguage.md)** - Internationalization and translation guide
- **[STORAGE_ENCRYPTION_AT_REST.md](./STORAGE_ENCRYPTION_AT_REST.md)** - Encryption at rest for stored files: key setup, migration, revocation, rotation
diff --git a/engine/src/stirling/models/tool_models.py b/engine/src/stirling/models/tool_models.py
index 6650942b6f..dff977a7f7 100644
--- a/engine/src/stirling/models/tool_models.py
+++ b/engine/src/stirling/models/tool_models.py
@@ -725,6 +725,9 @@ class OcrPdfParams(ApiModel):
)
ocr_type: OcrType = Field(..., description="Specify the OCR type, e.g., 'skip-text', 'force-ocr', or 'Normal'")
remove_images_after: bool | None = Field(None, description="Remove images from the output PDF if set to true")
+ rotate_pages: bool | None = Field(
+ None, description="Auto-correct page orientation (90/180/270) using Tesseract OSD if set to true"
+ )
sidecar: bool | None = Field(None, description="Include OCR text in a sidecar text file if set to true")
diff --git a/frontend/editor/public/locales/ar-AR/translation.toml b/frontend/editor/public/locales/ar-AR/translation.toml
index 4c4d45e2b4..4180d77811 100644
--- a/frontend/editor/public/locales/ar-AR/translation.toml
+++ b/frontend/editor/public/locales/ar-AR/translation.toml
@@ -3526,7 +3526,6 @@ label = "إحداثي Y"
[crop.error]
failed = "فشل قصّ PDF"
-invalidArea = "منطقة القص تتجاوز حدود PDF"
[crop.preview]
title = "معاينة منطقة القص"
diff --git a/frontend/editor/public/locales/az-AZ/translation.toml b/frontend/editor/public/locales/az-AZ/translation.toml
index f73930133e..0033be05d5 100644
--- a/frontend/editor/public/locales/az-AZ/translation.toml
+++ b/frontend/editor/public/locales/az-AZ/translation.toml
@@ -3526,7 +3526,6 @@ label = "Y mövqeyi"
[crop.error]
failed = "PDF-i kəsmək alınmadı"
-invalidArea = "Kəsmə sahəsi PDF sərhədlərini aşır"
[crop.preview]
title = "Kəsmə sahəsinin seçimi"
diff --git a/frontend/editor/public/locales/bg-BG/translation.toml b/frontend/editor/public/locales/bg-BG/translation.toml
index dc6ef92e39..07cf5a73d3 100644
--- a/frontend/editor/public/locales/bg-BG/translation.toml
+++ b/frontend/editor/public/locales/bg-BG/translation.toml
@@ -3526,7 +3526,6 @@ label = "Y позиция"
[crop.error]
failed = "Неуспешно изрязване на PDF"
-invalidArea = "Областта за изрязване излиза извън границите на PDF"
[crop.preview]
title = "Избор на област за изрязване"
diff --git a/frontend/editor/public/locales/bo-CN/translation.toml b/frontend/editor/public/locales/bo-CN/translation.toml
index 86d0b4f10d..21193f5f2d 100644
--- a/frontend/editor/public/locales/bo-CN/translation.toml
+++ b/frontend/editor/public/locales/bo-CN/translation.toml
@@ -3526,7 +3526,6 @@ label = "Yཡི་གནས་བབ།"
[crop.error]
failed = "སོན་བཟང་མ་འདང་བ། PDF"
-invalidArea = "སོན་འདེབས་རྒྱ་ཁྱོན་དེ་PDFམཚམས་ཐིག་ལས་བརྒལ་ཡོད།"
[crop.preview]
title = "སོན་བཟང་ཁུལ་འདེམས་པ།"
diff --git a/frontend/editor/public/locales/ca-CA/translation.toml b/frontend/editor/public/locales/ca-CA/translation.toml
index 498da94436..c22244ac98 100644
--- a/frontend/editor/public/locales/ca-CA/translation.toml
+++ b/frontend/editor/public/locales/ca-CA/translation.toml
@@ -3526,7 +3526,6 @@ label = "Posició Y"
[crop.error]
failed = "No s'ha pogut retallar el PDF"
-invalidArea = "L'àrea de retall s'estén més enllà dels límits del PDF"
[crop.preview]
title = "Selecció de l'àrea de retall"
diff --git a/frontend/editor/public/locales/cs-CZ/translation.toml b/frontend/editor/public/locales/cs-CZ/translation.toml
index 7b234329c7..f2161674f4 100644
--- a/frontend/editor/public/locales/cs-CZ/translation.toml
+++ b/frontend/editor/public/locales/cs-CZ/translation.toml
@@ -3526,7 +3526,6 @@ label = "Pozice Y"
[crop.error]
failed = "Oříznutí PDF se nezdařilo"
-invalidArea = "Oblast ořezu přesahuje hranice PDF"
[crop.preview]
title = "Výběr oblasti ořezu"
diff --git a/frontend/editor/public/locales/da-DK/translation.toml b/frontend/editor/public/locales/da-DK/translation.toml
index f4c068da92..a0ddd7f4d9 100644
--- a/frontend/editor/public/locales/da-DK/translation.toml
+++ b/frontend/editor/public/locales/da-DK/translation.toml
@@ -3526,7 +3526,6 @@ label = "Y-position"
[crop.error]
failed = "Kunne ikke beskære PDF"
-invalidArea = "Beskæringsområdet strækker sig ud over PDF'ens grænser"
[crop.preview]
title = "Valg af beskæringsområde"
diff --git a/frontend/editor/public/locales/de-DE/translation.toml b/frontend/editor/public/locales/de-DE/translation.toml
index 7c1bc79a8c..81c88d7599 100644
--- a/frontend/editor/public/locales/de-DE/translation.toml
+++ b/frontend/editor/public/locales/de-DE/translation.toml
@@ -3526,7 +3526,6 @@ label = "Y-Position"
[crop.error]
failed = "PDF zuschneiden fehlgeschlagen"
-invalidArea = "Zuschneidebereich überschreitet die PDF-Grenzen"
[crop.preview]
title = "Zuschneidebereich-Auswahl"
diff --git a/frontend/editor/public/locales/el-GR/translation.toml b/frontend/editor/public/locales/el-GR/translation.toml
index 5269791aec..57ebd2eb6b 100644
--- a/frontend/editor/public/locales/el-GR/translation.toml
+++ b/frontend/editor/public/locales/el-GR/translation.toml
@@ -3526,7 +3526,6 @@ label = "Θέση Y"
[crop.error]
failed = "Αποτυχία περικοπής του PDF"
-invalidArea = "Η περιοχή περικοπής εκτείνεται πέρα από τα όρια του PDF"
[crop.preview]
title = "Επιλογή περιοχής περικοπής"
diff --git a/frontend/editor/public/locales/en-GB/translation.toml b/frontend/editor/public/locales/en-GB/translation.toml
index 8fdd452928..d2b2aa38e3 100644
--- a/frontend/editor/public/locales/en-GB/translation.toml
+++ b/frontend/editor/public/locales/en-GB/translation.toml
@@ -3526,7 +3526,6 @@ label = "Y Position"
[crop.error]
failed = "Failed to crop PDF"
-invalidArea = "Crop area extends beyond PDF boundaries"
[crop.preview]
title = "Crop Area Selection"
diff --git a/frontend/editor/public/locales/en-US/translation.toml b/frontend/editor/public/locales/en-US/translation.toml
index f7fafed778..ef3d22cc0c 100644
--- a/frontend/editor/public/locales/en-US/translation.toml
+++ b/frontend/editor/public/locales/en-US/translation.toml
@@ -3003,6 +3003,293 @@ summary_one = "Ran 1 tool"
summary_other = "Ran {{count}} tools"
unknownTool = "Unknown tool"
+[classification.families]
+correspondence = "Correspondence"
+education = "Education"
+engineering = "Engineering"
+finance = "Financial"
+forms = "Forms"
+government = "Government"
+health = "Medical"
+hr = "HR"
+legal = "Legal"
+operations = "Operations"
+projects = "Projects"
+property = "Property"
+reports = "Reports"
+sales = "Marketing"
+travel = "Travel"
+
+[classification.labels]
+academic-record = "Academic record"
+action-plan = "Action plan"
+addendum = "Addendum"
+advertisement = "Advertisement"
+affidavit = "Affidavit"
+agenda = "Agenda"
+amendment = "Amendment"
+analytics-report = "Analytics report"
+announcement = "Announcement"
+annual-report = "Annual report"
+api-documentation = "API documentation"
+application-form = "Application form"
+appraisal-report = "Appraisal report"
+architecture-document = "Architecture document"
+articles-of-incorporation = "Articles of incorporation"
+assignment-brief = "Assignment brief"
+audit-report = "Audit report"
+balance-sheet = "Balance sheet"
+bank-statement = "Bank statement"
+benefits-summary = "Benefits summary"
+bill-of-lading = "Bill of lading"
+bill-of-materials = "Bill of materials"
+blueprint = "Blueprint"
+board-report = "Board report"
+board-resolution = "Board resolution"
+booking-confirmation = "Booking confirmation"
+brochure = "Brochure"
+budget = "Budget"
+business-plan = "Business plan"
+business-proposal = "Business proposal"
+bylaws = "Bylaws"
+campaign-brief = "Campaign brief"
+case-study = "Case study"
+cash-flow-statement = "Cash flow statement"
+catalog = "Catalog"
+cease-and-desist = "Cease and desist"
+certificate = "Certificate"
+certificate-of-completion = "Certificate of completion"
+change-log = "Change log"
+checklist = "Checklist"
+claim-form = "Claim form"
+closing-statement = "Closing statement"
+complaint-letter = "Complaint letter"
+compliance-document = "Compliance document"
+confirmation-letter = "Confirmation letter"
+consent-form = "Consent form"
+contract = "Contract"
+course-syllabus = "Course syllabus"
+court-filing = "Court filing"
+cover-letter = "Cover letter"
+credit-note = "Credit note"
+customs-declaration = "Customs declaration"
+customs-form = "Customs form"
+cv = "CV"
+datasheet = "Datasheet"
+debit-note = "Debit note"
+deed = "Deed"
+delivery-note = "Delivery note"
+demand-letter = "Demand letter"
+design-document = "Design document"
+diploma = "Diploma"
+discharge-summary = "Discharge summary"
+dissertation = "Dissertation"
+donation-receipt = "Donation receipt"
+dunning-letter = "Dunning letter"
+email-thread = "Email thread"
+employee-handbook = "Employee handbook"
+employment-contract = "Employment contract"
+estimate = "Estimate"
+event-agenda = "Event agenda"
+event-program = "Event program"
+eviction-notice = "Eviction notice"
+exam-paper = "Exam paper"
+expense-report = "Expense report"
+expense-summary = "Expense summary"
+explanation-of-benefits = "Explanation of benefits"
+fact-sheet = "Fact sheet"
+faq-document = "FAQ document"
+feasibility-study = "Feasibility study"
+feedback-form = "Feedback form"
+financial-forecast = "Financial forecast"
+financial-statement = "Financial statement"
+floor-plan = "Floor plan"
+flyer = "Flyer"
+form = "Form"
+franchise-agreement = "Franchise agreement"
+freight-document = "Freight document"
+gift-certificate = "Gift certificate"
+glossary = "Glossary"
+government-notice = "Government notice"
+grade-report = "Grade report"
+grant-agreement = "Grant agreement"
+grant-application = "Grant application"
+hoa-document = "HOA document"
+home-inspection-report = "Home inspection report"
+hr-memo = "HR memo"
+hr-policy = "HR policy"
+immigration-document = "Immigration document"
+immunization-record = "Immunization record"
+incident-report = "Incident report"
+income-statement = "Income statement"
+index = "Index"
+inspection-report = "Inspection report"
+insurance-certificate = "Insurance certificate"
+insurance-claim = "Insurance claim"
+insurance-policy = "Insurance policy"
+intake-form = "Intake form"
+inventory-list = "Inventory list"
+investment-summary = "Investment summary"
+invitation = "Invitation"
+invoice = "Invoice"
+itinerary = "Itinerary"
+job-application = "Job application"
+job-description = "Job description"
+lab-report = "Lab report"
+lease-agreement = "Lease agreement"
+leave-request = "Leave request"
+legal-brief = "Legal brief"
+legal-filing = "Legal filing"
+legal-notice = "Legal notice"
+legal-opinion = "Legal opinion"
+lesson-plan = "Lesson plan"
+letter = "Letter"
+letter-of-intent = "Letter of intent"
+license = "License"
+license-agreement = "License agreement"
+loan-agreement = "Loan agreement"
+loan-document = "Loan document"
+maintenance-log = "Maintenance log"
+manual = "Manual"
+market-research = "Market research"
+marketing-plan = "Marketing plan"
+media-kit = "Media kit"
+medical-invoice = "Medical invoice"
+medical-report = "Medical report"
+meeting-agenda = "Meeting agenda"
+meeting-minutes = "Meeting minutes"
+meeting-notes = "Meeting notes"
+membership-document = "Membership document"
+memo = "Memo"
+memorandum-of-understanding = "Memorandum of understanding"
+mortgage-document = "Mortgage document"
+nda = "NDA"
+newsletter = "Newsletter"
+non-compete-agreement = "Non-compete agreement"
+notice = "Notice"
+offer-letter = "Offer letter"
+onboarding-document = "Onboarding document"
+order-confirmation = "Order confirmation"
+order-form = "Order form"
+organization-chart = "Organization chart"
+packing-slip = "Packing slip"
+partnership-agreement = "Partnership agreement"
+patent = "Patent"
+pathology-report = "Pathology report"
+payment-reminder = "Payment reminder"
+payroll-document = "Payroll document"
+payslip = "Payslip"
+performance-review = "Performance review"
+permit = "Permit"
+petition = "Petition"
+pitch-deck = "Pitch deck"
+power-of-attorney = "Power of attorney"
+prescription = "Prescription"
+presentation = "Presentation"
+press-release = "Press release"
+price-list = "Price list"
+pricing-sheet = "Pricing sheet"
+privacy-policy = "Privacy policy"
+product-sheet = "Product sheet"
+proforma-invoice = "Proforma invoice"
+progress-report = "Progress report"
+project-charter = "Project charter"
+project-plan = "Project plan"
+promotional-material = "Promotional material"
+property-listing = "Property listing"
+proposal = "Proposal"
+public-notice = "Public notice"
+purchase-agreement = "Purchase agreement"
+purchase-order = "Purchase order"
+quality-report = "Quality report"
+quarterly-report = "Quarterly report"
+questionnaire = "Questionnaire"
+quick-start-guide = "Quick start guide"
+quote = "Quote"
+radiology-report = "Radiology report"
+receipt = "Receipt"
+recommendation-letter = "Recommendation letter"
+reference-letter = "Reference letter"
+referral-letter = "Referral letter"
+registration-confirmation = "Registration confirmation"
+registration-form = "Registration form"
+regulatory-filing = "Regulatory filing"
+release-notes = "Release notes"
+remittance-advice = "Remittance advice"
+rental-agreement = "Rental agreement"
+report = "Report"
+request-for-proposal = "Request for proposal"
+request-for-quotation = "Request for quotation"
+requirements-document = "Requirements document"
+research-abstract = "Research abstract"
+research-paper = "Research paper"
+reservation = "Reservation"
+resignation-letter = "Resignation letter"
+resume = "Resume"
+retrospective = "Retrospective"
+return-authorization = "Return authorization"
+risk-assessment = "Risk assessment"
+roadmap = "Roadmap"
+safety-data-sheet = "Safety data sheet"
+safety-procedure = "Safety procedure"
+sales-proposal = "Sales proposal"
+sales-report = "Sales report"
+schematic = "Schematic"
+scope-of-work = "Scope of work"
+service-agreement = "Service agreement"
+service-report = "Service report"
+settlement-agreement = "Settlement agreement"
+shareholder-agreement = "Shareholder agreement"
+shipping-confirmation = "Shipping confirmation"
+specification = "Specification"
+sponsorship-agreement = "Sponsorship agreement"
+standard-operating-procedure = "Standard operating procedure"
+statement-of-account = "Statement of account"
+statement-of-work = "Statement of work"
+status-report = "Status report"
+stock-report = "Stock report"
+study-guide = "Study guide"
+subpoena = "Subpoena"
+subscription-confirmation = "Subscription confirmation"
+supply-order = "Supply order"
+survey-form = "Survey form"
+survey-results = "Survey results"
+sustainability-report = "Sustainability report"
+table-of-contents = "Table of contents"
+tax-form = "Tax form"
+tax-return = "Tax return"
+tax-statement = "Tax statement"
+technical-drawing = "Technical drawing"
+technical-specification = "Technical specification"
+tenancy-agreement = "Tenancy agreement"
+tender-document = "Tender document"
+termination-letter = "Termination letter"
+terms-and-conditions = "Terms and conditions"
+terms-of-service = "Terms of service"
+test-plan = "Test plan"
+test-report = "Test report"
+thesis = "Thesis"
+ticket = "Ticket"
+timeline = "Timeline"
+timesheet = "Timesheet"
+title-document = "Title document"
+training-material = "Training material"
+transcript = "Transcript"
+travel-itinerary = "Travel itinerary"
+trust-document = "Trust document"
+user-guide = "User guide"
+utility-bill = "Utility bill"
+vendor-agreement = "Vendor agreement"
+visa-document = "Visa document"
+waiver = "Waiver"
+warehouse-receipt = "Warehouse receipt"
+warranty-document = "Warranty document"
+waybill = "Waybill"
+white-paper = "White paper"
+will = "Will"
+work-instruction = "Work instruction"
+work-order = "Work order"
+
[cloudBadge]
tooltip = "This operation will use your cloud credits"
@@ -3242,7 +3529,7 @@ enterEmailConfirm = "To confirm deletion, please type your email address ({{emai
guestDescription = "You are signed in as a guest. Consider upgrading your account above."
label = "Overview"
manageAccountPreferences = "Manage your account preferences"
-signedInAs = "Signed in as"
+signedInAs = "Account"
title = "Account Settings"
[config.account.profilePicture]
@@ -3353,6 +3640,39 @@ integration = "Integration Configuration"
security = "Security Configuration"
system = "System Configuration"
+[connect]
+loading = "Checking this request."
+redirecting = "Returning you to your server."
+
+[connect.confirm]
+acknowledge = "I recognise this address and want to connect it to my team"
+approve = "Connect server"
+deny = "Decline"
+lead = "A Stirling server is asking to connect to your team. Check the address below is yours before you approve."
+originLabel = "Address"
+signedInAs = "Signed in as"
+switchAccount = "Use a different account"
+title = "Connect this server?"
+unknownAccount = "an unknown account"
+
+[connect.confirm.insecure]
+body = "This address does not use HTTPS, so your sign-in will be sent over an unencrypted connection. Only approve it on a network you trust."
+label = "Not an encrypted address"
+
+[connect.declined]
+body = "Nothing was connected. You can close this page."
+title = "Request declined"
+
+[connect.error]
+failed = "That did not go through. Only a team owner can connect a server."
+
+[connect.meta]
+title = "Connect a server"
+
+[connect.notFound]
+body = "This connection request is not valid. It may have expired, or already been used. Start another one from your server."
+title = "Request not valid"
+
[convert]
autoRotate = "Auto Rotate"
autoRotateDescription = "Automatically rotate images to better fit the PDF page"
@@ -3528,7 +3848,6 @@ label = "Y Position"
[crop.error]
failed = "Failed to crop PDF"
-invalidArea = "Crop area extends beyond PDF boundaries"
[crop.preview]
title = "Crop Area Selection"
@@ -3848,7 +4167,6 @@ mobileShort = "Mobile"
mobileUpload = "Mobile Upload"
mobileUploadNotAvailable = "Mobile upload not enabled"
moreOptions = "More options"
-myFiles = "My Files"
nextFile = "Next file"
noFiles = "No files available"
noFilesFound = "No files found matching your search"
@@ -3949,9 +4267,9 @@ duplicateFailed = "Could not duplicate file"
expand = "Expand sidebar"
googleDrive = "Google Drive"
googleDriveDisabled = "Google Drive is not configured"
-leaveMyFiles = "Leave My Files"
+leaveMyFiles = "Leave File library"
library = "PDF Library"
-myFiles = "My Files"
+myFiles = "File library"
noFiles = "No files yet"
openFileManager = "Browse all files & folders"
openFromComputer = "Open from computer"
@@ -3994,7 +4312,7 @@ addToWorkspaceCount = "Add {{count}} to workspace"
allFiles = "All files"
back = "Back"
backToFolder = "Back to {{folder}}"
-backToMyFiles = "Back to My Files"
+backToMyFiles = "Back to File library"
breadcrumbs = "Folder path"
bulkActions = "Actions"
cancel = "Cancel"
@@ -4046,7 +4364,6 @@ localFoldersUnavailable = "Folders are cloud-only - save a file to the cloud to
moveSkippedRemote_one = "{{count}} file couldn't be moved on the server (no permission or already deleted)."
moveSkippedRemote_other = "{{count}} files couldn't be moved on the server (no permission or already deleted)."
moveTo = "Move to…"
-myFiles = "My Files"
newFolder = "New folder"
newFolderStorageDisabled = "Server folder storage isn't enabled. Ask your admin to turn it on."
newFolderTabUnavailable = "Switch to All or Cloud to create folders."
@@ -6520,6 +6837,34 @@ after = "to enable account linking against the hosted Stirling account. In dev y
before = "Set"
title = "SaaS login not configured"
+[portal.accountLink.connect.callback]
+continue = "Continue"
+linkedNotSignedIn = "You are not signed in to Stirling in this browser, so usage and billing will ask you to sign in."
+modalTitle = "Connecting this server"
+retry = "Try again"
+signedInAnyway = "You are signed in to Stirling, so billing and usage will load. Only the server link is incomplete."
+working = "Finishing the connection."
+
+[portal.accountLink.connect.callback.expired]
+body = "Connection requests are short lived. Start another one."
+title = "Request expired"
+
+[portal.accountLink.connect.callback.linked]
+body = "This server is connected to your Stirling account."
+title = "Server connected"
+
+[portal.accountLink.connect.callback.malformed]
+body = "This page was opened without a valid connection response. Start the connection from settings."
+title = "Could not read the response"
+
+[portal.accountLink.connect.callback.rejected]
+body = "This request was declined or has already been used. Start another one if that was not intended."
+title = "Connection not completed"
+
+[portal.accountLink.connect.callback.unfinished]
+body = "Stirling did not confirm the connection. This is usually temporary."
+title = "Not finished yet"
+
[portal.accountLink.gate]
action = "Link account"
description = "Link this org's Stirling account to use billable features."
@@ -6553,17 +6898,24 @@ minutesAgo_other = "{{count}}m ago"
never = "never"
[portal.accountLink.modal]
-linkSubtitle = "Sign in to the account this server should bill against."
-linkTitle = "Link your Stirling account"
-reauthSubtitle = "Your session expired — sign back in to your Stirling account. Your instance stays linked."
+cancel = "Cancel"
+continueLink = "Continue to Stirling"
+continueReauth = "Sign in again"
+linkSubtitle = "Connect this server to the Stirling account it should bill against."
+linkTitle = "Connect your Stirling account"
+noAuthorizeUrl = "Stirling did not return somewhere to continue. Try again in a moment."
+reauthSubtitle = "Your Stirling session expired. Sign in again to keep seeing usage and billing. This server stays connected either way."
reauthTitle = "Sign in again"
-simulateSignIn = "Simulate sign-in (dev)"
+startFailed = "Could not reach Stirling to start the connection. Check this server's outbound network access, then try again."
+step1 = "We send you to stirling.com to sign in. Any sign-in method works there, including Google and single sign-on."
+step2 = "You check this server's address and approve it. A team owner has to do this the first time."
+step3 = "Stirling brings you straight back here and finishes up."
[portal.accountLink.modal.loginNotConfigured]
-after = "to enable in-app linking against the hosted Stirling account."
+after = "so this server can finish the connection when you come back."
and = "and"
before = "Set"
-title = "SaaS login not configured"
+title = "Stirling connection not configured"
[portal.accountLink.panel]
instancesSub = "Every self-hosted instance registered to this org. Revoke a credential to immediately cut off its unattended access."
@@ -8851,7 +9203,6 @@ appEditor = "Editor"
appProcessor = "Processor"
linkAccount = "Link Stirling account"
primaryNav = "Primary navigation"
-switchApp = "Switch app"
[portal.shell.topbar]
closeNav = "Close navigation"
@@ -9330,6 +9681,16 @@ automate = "Automate"
config = "Config"
files = "Files"
+[quickNav]
+editor = "Editor"
+home = "Stirling"
+invite = "Invite"
+landmark = "Quick navigation"
+noProcessorAccess = "Ask an admin for processor access"
+notifications = "Notifications"
+processor = "Processor"
+reader = "Reader"
+
[read]
tags = "view,open,display,read,viewer,PDF viewer,PDF reader,open PDF,view PDF,display PDF,preview,browse"
@@ -11830,6 +12191,10 @@ title = "Watermark Text"
image = "Image"
text = "Text"
+[workbench.sessionRestore]
+none = "Your previous files are no longer stored on this device."
+partial = "Restored {{restored}} of {{total}} files. The rest are no longer stored on this device."
+
[workbenchBar]
activeFiles = "Active Files"
annotations = "Annotations"
diff --git a/frontend/editor/public/locales/es-ES/translation.toml b/frontend/editor/public/locales/es-ES/translation.toml
index 73aeb53429..5fffd6eae8 100644
--- a/frontend/editor/public/locales/es-ES/translation.toml
+++ b/frontend/editor/public/locales/es-ES/translation.toml
@@ -3526,7 +3526,6 @@ label = "Posición Y"
[crop.error]
failed = "Error al recortar PDF"
-invalidArea = "El área de recorte se extiende más allá de los límites del PDF"
[crop.preview]
title = "Selección de Área de Recorte"
diff --git a/frontend/editor/public/locales/eu-ES/translation.toml b/frontend/editor/public/locales/eu-ES/translation.toml
index b5a2388e67..018bfbabc5 100644
--- a/frontend/editor/public/locales/eu-ES/translation.toml
+++ b/frontend/editor/public/locales/eu-ES/translation.toml
@@ -3526,7 +3526,6 @@ label = "Y posizioa"
[crop.error]
failed = "Huts egin du PDFa mozteak"
-invalidArea = "Mozketa-area PDFaren mugak baino harago doa"
[crop.preview]
title = "Mozketa-arearen hautapena"
diff --git a/frontend/editor/public/locales/fa-IR/translation.toml b/frontend/editor/public/locales/fa-IR/translation.toml
index 14a40c4694..000d039dfa 100644
--- a/frontend/editor/public/locales/fa-IR/translation.toml
+++ b/frontend/editor/public/locales/fa-IR/translation.toml
@@ -3526,7 +3526,6 @@ label = "موقعیت Y"
[crop.error]
failed = "برش PDF ناموفق بود"
-invalidArea = "ناحیه برش از مرزهای PDF فراتر رفته است"
[crop.preview]
title = "انتخاب ناحیه برش"
diff --git a/frontend/editor/public/locales/fr-FR/translation.toml b/frontend/editor/public/locales/fr-FR/translation.toml
index 5550076052..e7d8a2a9ab 100644
--- a/frontend/editor/public/locales/fr-FR/translation.toml
+++ b/frontend/editor/public/locales/fr-FR/translation.toml
@@ -3526,7 +3526,6 @@ label = "Position Y"
[crop.error]
failed = "Échec du recadrage du PDF"
-invalidArea = "La zone de recadrage dépasse les limites du PDF"
[crop.preview]
title = "Sélection de la zone de recadrage"
diff --git a/frontend/editor/public/locales/ga-IE/translation.toml b/frontend/editor/public/locales/ga-IE/translation.toml
index 4d3ad56168..1507ae92df 100644
--- a/frontend/editor/public/locales/ga-IE/translation.toml
+++ b/frontend/editor/public/locales/ga-IE/translation.toml
@@ -3526,7 +3526,6 @@ label = "Suíomh Y"
[crop.error]
failed = "Theip ar an PDF a bhearradh"
-invalidArea = "Téann an limistéar bearrtha thar theorainneacha an PDF"
[crop.preview]
title = "Roghnú Limistéir Bhearrtha"
diff --git a/frontend/editor/public/locales/hi-IN/translation.toml b/frontend/editor/public/locales/hi-IN/translation.toml
index ae5993b387..bd769216a8 100644
--- a/frontend/editor/public/locales/hi-IN/translation.toml
+++ b/frontend/editor/public/locales/hi-IN/translation.toml
@@ -3526,7 +3526,6 @@ label = "Y स्थान"
[crop.error]
failed = "PDF क्रॉप करने में विफल"
-invalidArea = "क्रॉप क्षेत्र PDF सीमाओं से बाहर जा रहा है"
[crop.preview]
title = "क्रॉप क्षेत्र चयन"
diff --git a/frontend/editor/public/locales/hr-HR/translation.toml b/frontend/editor/public/locales/hr-HR/translation.toml
index 587933825b..371c1b782c 100644
--- a/frontend/editor/public/locales/hr-HR/translation.toml
+++ b/frontend/editor/public/locales/hr-HR/translation.toml
@@ -3526,7 +3526,6 @@ label = "Y položaj"
[crop.error]
failed = "Izrezivanje PDF-a nije uspjelo"
-invalidArea = "Područje izrezivanja prelazi granice PDF-a"
[crop.preview]
title = "Odabir područja izrezivanja"
diff --git a/frontend/editor/public/locales/hu-HU/translation.toml b/frontend/editor/public/locales/hu-HU/translation.toml
index 98d393c047..c8fb681564 100644
--- a/frontend/editor/public/locales/hu-HU/translation.toml
+++ b/frontend/editor/public/locales/hu-HU/translation.toml
@@ -3526,7 +3526,6 @@ label = "Y pozíció"
[crop.error]
failed = "A PDF vágása sikertelen"
-invalidArea = "A vágási terület túlnyúlik a PDF határain"
[crop.preview]
title = "Vágási terület kiválasztása"
diff --git a/frontend/editor/public/locales/id-ID/translation.toml b/frontend/editor/public/locales/id-ID/translation.toml
index 15fe756aa6..83751f1dce 100644
--- a/frontend/editor/public/locales/id-ID/translation.toml
+++ b/frontend/editor/public/locales/id-ID/translation.toml
@@ -3526,7 +3526,6 @@ label = "Posisi Y"
[crop.error]
failed = "Gagal memangkas PDF"
-invalidArea = "Area pangkas melampaui batas PDF"
[crop.preview]
title = "Pilihan Area Pangkas"
diff --git a/frontend/editor/public/locales/it-IT/translation.toml b/frontend/editor/public/locales/it-IT/translation.toml
index a99f00a343..592f644216 100644
--- a/frontend/editor/public/locales/it-IT/translation.toml
+++ b/frontend/editor/public/locales/it-IT/translation.toml
@@ -3526,7 +3526,6 @@ label = "Posizione Y"
[crop.error]
failed = "Impossibile ritagliare il PDF"
-invalidArea = "L’area di ritaglio supera i limiti del PDF"
[crop.preview]
title = "Selezione area di ritaglio"
diff --git a/frontend/editor/public/locales/ja-JP/translation.toml b/frontend/editor/public/locales/ja-JP/translation.toml
index dcc5735dbd..a8d6730ba4 100644
--- a/frontend/editor/public/locales/ja-JP/translation.toml
+++ b/frontend/editor/public/locales/ja-JP/translation.toml
@@ -3526,7 +3526,6 @@ label = "Y 位置"
[crop.error]
failed = "PDF の切り抜きに失敗しました"
-invalidArea = "切り抜き範囲が PDF の境界を超えています"
[crop.preview]
title = "切り抜き範囲の選択"
diff --git a/frontend/editor/public/locales/ko-KR/translation.toml b/frontend/editor/public/locales/ko-KR/translation.toml
index 833f710c7f..33ca27a071 100644
--- a/frontend/editor/public/locales/ko-KR/translation.toml
+++ b/frontend/editor/public/locales/ko-KR/translation.toml
@@ -3526,7 +3526,6 @@ label = "Y 위치"
[crop.error]
failed = "PDF 자르기에 실패했습니다"
-invalidArea = "자르기 영역이 PDF 경계를 벗어났습니다"
[crop.preview]
title = "자르기 영역 선택"
diff --git a/frontend/editor/public/locales/ml-ML/translation.toml b/frontend/editor/public/locales/ml-ML/translation.toml
index 53e8ef302f..10235abe24 100644
--- a/frontend/editor/public/locales/ml-ML/translation.toml
+++ b/frontend/editor/public/locales/ml-ML/translation.toml
@@ -3526,7 +3526,6 @@ label = "Y സ്ഥാനം"
[crop.error]
failed = "PDF ക്രോപ്പ് ചെയ്യാൻ കഴിഞ്ഞില്ല"
-invalidArea = "ക്രോപ്പ് ഏരിയ PDF അതിരുകൾക്ക് പുറത്തേക്ക് നീളുന്നു"
[crop.preview]
title = "ക്രോപ്പ് ഏരിയ തിരഞ്ഞെടുപ്പ്"
diff --git a/frontend/editor/public/locales/nl-NL/translation.toml b/frontend/editor/public/locales/nl-NL/translation.toml
index d4ada20e32..e5841842f2 100644
--- a/frontend/editor/public/locales/nl-NL/translation.toml
+++ b/frontend/editor/public/locales/nl-NL/translation.toml
@@ -3526,7 +3526,6 @@ label = "Y-positie"
[crop.error]
failed = "PDF bijsnijden mislukt"
-invalidArea = "Bijsnijgebied valt buiten PDF-randen"
[crop.preview]
title = "Selectie bijsnijgebied"
diff --git a/frontend/editor/public/locales/no-NB/translation.toml b/frontend/editor/public/locales/no-NB/translation.toml
index 9402f04f22..1dd1167219 100644
--- a/frontend/editor/public/locales/no-NB/translation.toml
+++ b/frontend/editor/public/locales/no-NB/translation.toml
@@ -3526,7 +3526,6 @@ label = "Y-posisjon"
[crop.error]
failed = "Kunne ikke beskjære PDF"
-invalidArea = "Beskjæringsområdet går utenfor PDF-grensene"
[crop.preview]
title = "Valg av beskjæringsområde"
diff --git a/frontend/editor/public/locales/pl-PL/translation.toml b/frontend/editor/public/locales/pl-PL/translation.toml
index 566a681f9a..c327cf2483 100644
--- a/frontend/editor/public/locales/pl-PL/translation.toml
+++ b/frontend/editor/public/locales/pl-PL/translation.toml
@@ -3526,7 +3526,6 @@ label = "Pozycja Y"
[crop.error]
failed = "Nie udało się przyciąć PDF"
-invalidArea = "Obszar przycięcia wykracza poza granice PDF"
[crop.preview]
title = "Wybór obszaru przycięcia"
diff --git a/frontend/editor/public/locales/pt-BR/translation.toml b/frontend/editor/public/locales/pt-BR/translation.toml
index d89968fdfa..8455176984 100644
--- a/frontend/editor/public/locales/pt-BR/translation.toml
+++ b/frontend/editor/public/locales/pt-BR/translation.toml
@@ -3526,7 +3526,6 @@ label = "Posição Y"
[crop.error]
failed = "Falha ao recortar o PDF"
-invalidArea = "A área de corte se estende além dos limites do PDF"
[crop.preview]
title = "Seleção da área de corte"
diff --git a/frontend/editor/public/locales/pt-PT/translation.toml b/frontend/editor/public/locales/pt-PT/translation.toml
index 0f9aebeff7..0b24388d75 100644
--- a/frontend/editor/public/locales/pt-PT/translation.toml
+++ b/frontend/editor/public/locales/pt-PT/translation.toml
@@ -3526,7 +3526,6 @@ label = "Posição Y"
[crop.error]
failed = "Falha ao recortar o PDF"
-invalidArea = "A área de recorte excede os limites do PDF"
[crop.preview]
title = "Seleção da área de recorte"
diff --git a/frontend/editor/public/locales/ro-RO/translation.toml b/frontend/editor/public/locales/ro-RO/translation.toml
index 0f7c1555b8..2a3f4eba7d 100644
--- a/frontend/editor/public/locales/ro-RO/translation.toml
+++ b/frontend/editor/public/locales/ro-RO/translation.toml
@@ -3526,7 +3526,6 @@ label = "Poziția Y"
[crop.error]
failed = "Nu s-a putut decupa PDF-ul"
-invalidArea = "Zona de decupare depășește limitele PDF-ului"
[crop.preview]
title = "Selecție zonă de decupare"
diff --git a/frontend/editor/public/locales/ru-RU/translation.toml b/frontend/editor/public/locales/ru-RU/translation.toml
index eae673f896..7d32f58a6f 100644
--- a/frontend/editor/public/locales/ru-RU/translation.toml
+++ b/frontend/editor/public/locales/ru-RU/translation.toml
@@ -3526,7 +3526,6 @@ label = "Положение Y"
[crop.error]
failed = "Не удалось обрезать PDF"
-invalidArea = "Область обрезки выходит за границы PDF"
[crop.preview]
title = "Выбор области обрезки"
diff --git a/frontend/editor/public/locales/sk-SK/translation.toml b/frontend/editor/public/locales/sk-SK/translation.toml
index 1906d101d0..9383f6a866 100644
--- a/frontend/editor/public/locales/sk-SK/translation.toml
+++ b/frontend/editor/public/locales/sk-SK/translation.toml
@@ -3526,7 +3526,6 @@ label = "Pozícia Y"
[crop.error]
failed = "Nepodarilo sa orezať PDF"
-invalidArea = "Oblasť orezania presahuje hranice PDF"
[crop.preview]
title = "Výber oblasti orezania"
diff --git a/frontend/editor/public/locales/sl-SI/translation.toml b/frontend/editor/public/locales/sl-SI/translation.toml
index 120606f790..c6c9cdbd54 100644
--- a/frontend/editor/public/locales/sl-SI/translation.toml
+++ b/frontend/editor/public/locales/sl-SI/translation.toml
@@ -3526,7 +3526,6 @@ label = "Položaj Y"
[crop.error]
failed = "Obrezovanje PDF-ja ni uspelo"
-invalidArea = "Območje obrezovanja presega meje PDF-ja"
[crop.preview]
title = "Izbira območja obrezovanja"
diff --git a/frontend/editor/public/locales/sr-LATN-RS/translation.toml b/frontend/editor/public/locales/sr-LATN-RS/translation.toml
index 2e4cb53c7b..c639e19155 100644
--- a/frontend/editor/public/locales/sr-LATN-RS/translation.toml
+++ b/frontend/editor/public/locales/sr-LATN-RS/translation.toml
@@ -3526,7 +3526,6 @@ label = "Y pozicija"
[crop.error]
failed = "Nije uspelo isecanje PDF-a"
-invalidArea = "Oblast isečka prelazi granice PDF-a"
[crop.preview]
title = "Izbor oblasti za isecanje"
diff --git a/frontend/editor/public/locales/sv-SE/translation.toml b/frontend/editor/public/locales/sv-SE/translation.toml
index bd61dbedff..ba2b56e5e0 100644
--- a/frontend/editor/public/locales/sv-SE/translation.toml
+++ b/frontend/editor/public/locales/sv-SE/translation.toml
@@ -3526,7 +3526,6 @@ label = "Y-position"
[crop.error]
failed = "Det gick inte att beskära PDF"
-invalidArea = "Beskärningsområdet sträcker sig utanför PDF:ens gränser"
[crop.preview]
title = "Val av beskärningsområde"
diff --git a/frontend/editor/public/locales/th-TH/translation.toml b/frontend/editor/public/locales/th-TH/translation.toml
index 6b1c927d9f..6a294505f1 100644
--- a/frontend/editor/public/locales/th-TH/translation.toml
+++ b/frontend/editor/public/locales/th-TH/translation.toml
@@ -3526,7 +3526,6 @@ label = "ตำแหน่ง Y"
[crop.error]
failed = "ครอบตัด PDF ไม่สำเร็จ"
-invalidArea = "พื้นที่ครอบตัดเกินขอบเขตของ PDF"
[crop.preview]
title = "การเลือกพื้นที่ครอบตัด"
diff --git a/frontend/editor/public/locales/tr-TR/translation.toml b/frontend/editor/public/locales/tr-TR/translation.toml
index 6ac3a86d07..ae580843e5 100644
--- a/frontend/editor/public/locales/tr-TR/translation.toml
+++ b/frontend/editor/public/locales/tr-TR/translation.toml
@@ -3526,7 +3526,6 @@ label = "Y Konumu"
[crop.error]
failed = "PDF kırpılamadı"
-invalidArea = "Kırpma alanı PDF sınırlarının dışına taşıyor"
[crop.preview]
title = "Kırpma Alanı Seçimi"
diff --git a/frontend/editor/public/locales/uk-UA/translation.toml b/frontend/editor/public/locales/uk-UA/translation.toml
index d51189230b..2f9e2daeef 100644
--- a/frontend/editor/public/locales/uk-UA/translation.toml
+++ b/frontend/editor/public/locales/uk-UA/translation.toml
@@ -3526,7 +3526,6 @@ label = "Позиція Y"
[crop.error]
failed = "Не вдалося обрізати PDF"
-invalidArea = "Область обрізки виходить за межі PDF"
[crop.preview]
title = "Вибір області обрізки"
diff --git a/frontend/editor/public/locales/vi-VN/translation.toml b/frontend/editor/public/locales/vi-VN/translation.toml
index a574d29833..566568dade 100644
--- a/frontend/editor/public/locales/vi-VN/translation.toml
+++ b/frontend/editor/public/locales/vi-VN/translation.toml
@@ -3526,7 +3526,6 @@ label = "Vị trí Y"
[crop.error]
failed = "Không cắt được PDF"
-invalidArea = "Vùng cắt vượt quá ranh giới PDF"
[crop.preview]
title = "Chọn vùng cắt"
diff --git a/frontend/editor/public/locales/zh-BO/translation.toml b/frontend/editor/public/locales/zh-BO/translation.toml
index 895fbc5c82..7a64d7453e 100644
--- a/frontend/editor/public/locales/zh-BO/translation.toml
+++ b/frontend/editor/public/locales/zh-BO/translation.toml
@@ -3526,7 +3526,6 @@ label = "Y 位置"
[crop.error]
failed = "裁剪 PDF 失败"
-invalidArea = "裁剪区域超出 PDF 边界"
[crop.preview]
title = "裁剪区域选择"
diff --git a/frontend/editor/public/locales/zh-CN/translation.toml b/frontend/editor/public/locales/zh-CN/translation.toml
index ccf73691ff..b29e3442d4 100644
--- a/frontend/editor/public/locales/zh-CN/translation.toml
+++ b/frontend/editor/public/locales/zh-CN/translation.toml
@@ -3526,7 +3526,6 @@ label = "Y 位置"
[crop.error]
failed = "裁剪 PDF 失败"
-invalidArea = "裁剪区域超出 PDF 边界"
[crop.preview]
title = "裁剪区域选择"
diff --git a/frontend/editor/public/locales/zh-TW/translation.toml b/frontend/editor/public/locales/zh-TW/translation.toml
index 269d9c9d59..efb8adb8b9 100644
--- a/frontend/editor/public/locales/zh-TW/translation.toml
+++ b/frontend/editor/public/locales/zh-TW/translation.toml
@@ -3526,7 +3526,6 @@ label = "Y 位置"
[crop.error]
failed = "裁切 PDF 失敗"
-invalidArea = "裁切區域超出 PDF 邊界"
[crop.preview]
title = "裁切區域選擇"
diff --git a/frontend/editor/src/cloud/components/shared/config/configSections/TeamSection.tsx b/frontend/editor/src/cloud/components/shared/config/configSections/TeamSection.tsx
index 4eb064d8bf..ab8a184828 100644
--- a/frontend/editor/src/cloud/components/shared/config/configSections/TeamSection.tsx
+++ b/frontend/editor/src/cloud/components/shared/config/configSections/TeamSection.tsx
@@ -360,11 +360,9 @@ const TeamSection: React.FC = () => {
verticalSpacing="sm"
withRowBorders
highlightOnHover
- style={
- {
- "--table-border-color": "var(--mantine-color-gray-3)",
- } as React.CSSProperties
- }
+ style={{
+ "--table-border-color": "var(--mantine-color-gray-3)",
+ }}
>
- {/* All other routes need AppProviders for backend integration */}
-
-
-
-
-
-
- }
- />
+ {/* The app, under a shared frame so the rail renders once outside it. */}
+ }>
+ {/* All other routes need AppProviders for backend integration */}
+
+
+
+
+
+
+ }
+ />
+
);
diff --git a/frontend/editor/src/core/api/signing.ts b/frontend/editor/src/core/api/signing.ts
new file mode 100644
index 0000000000..c58fad8aac
--- /dev/null
+++ b/frontend/editor/src/core/api/signing.ts
@@ -0,0 +1,21 @@
+import apiClient from "@app/services/apiClient";
+import type {
+ SignRequestSummary,
+ SessionSummary,
+} from "@app/types/signingSession";
+
+export interface SigningSessions {
+ signRequests: SignRequestSummary[];
+ mySessions: SessionSummary[];
+}
+
+/** The two lists the signing UI always needs together. */
+export async function fetchSigningSessions(): Promise {
+ const [requests, sessions] = await Promise.all([
+ apiClient.get(
+ "/api/v1/security/cert-sign/sign-requests",
+ ),
+ apiClient.get("/api/v1/security/cert-sign/sessions"),
+ ]);
+ return { signRequests: requests.data, mySessions: sessions.data };
+}
diff --git a/frontend/editor/src/core/components/AppProviders.tsx b/frontend/editor/src/core/components/AppProviders.tsx
index 01b2e42a82..ed1194eb4b 100644
--- a/frontend/editor/src/core/components/AppProviders.tsx
+++ b/frontend/editor/src/core/components/AppProviders.tsx
@@ -39,6 +39,7 @@ import { RedactionProvider } from "@app/contexts/RedactionContext";
import { FormFillProvider } from "@app/tools/formFill/FormFillContext";
import { FolderFileContextProvider } from "@app/contexts/FolderFileContext";
import { FolderProvider } from "@app/contexts/FolderContext";
+import { WorkbenchSessionPersistence } from "@app/components/session/WorkbenchSessionPersistence";
// Component to initialize scarf tracking (must be inside AppConfigProvider)
function ScarfTrackingInitializer() {
@@ -163,6 +164,7 @@ export function AppProviders({
+
{children}
diff --git a/frontend/editor/src/core/components/fileEditor/FileEditor.tsx b/frontend/editor/src/core/components/fileEditor/FileEditor.tsx
index 8cfef80d83..1072758275 100644
--- a/frontend/editor/src/core/components/fileEditor/FileEditor.tsx
+++ b/frontend/editor/src/core/components/fileEditor/FileEditor.tsx
@@ -336,7 +336,7 @@ const FileEditor = ({
(fileId: FileId) => {
const index = stubsRef.current.findIndex((r) => r.id === fileId);
if (index !== -1) {
- setActiveFileId(fileId as string);
+ setActiveFileId(fileId);
setActiveFileIndex(index);
navActions.setWorkbench("viewer");
}
@@ -410,10 +410,7 @@ const FileEditor = ({
onUnzipFile={handleUnzipFile}
toolMode={toolMode}
isSupported={isFileSupported(record.name)}
- policies={
- policyFileBadges.get(record.id as string) ??
- EMPTY_POLICIES
- }
+ policies={policyFileBadges.get(record.id) ?? EMPTY_POLICIES}
/>
);
})}
diff --git a/frontend/editor/src/core/components/fileManager/FileSourceButtons.tsx b/frontend/editor/src/core/components/fileManager/FileSourceButtons.tsx
index 6ac3e3c91e..20ebaa191e 100644
--- a/frontend/editor/src/core/components/fileManager/FileSourceButtons.tsx
+++ b/frontend/editor/src/core/components/fileManager/FileSourceButtons.tsx
@@ -173,7 +173,7 @@ const FileSourceButtons: React.FC = ({
mb="xs"
style={{ paddingLeft: "1rem" }}
>
- {t("fileManager.myFiles", "My Files")}
+ {t("fileSidebar.myFiles", "File library")}
{buttons}
diff --git a/frontend/editor/src/core/components/filesPage/FileDetailsPanel.tsx b/frontend/editor/src/core/components/filesPage/FileDetailsPanel.tsx
index 693d8efae7..ff570bbe1d 100644
--- a/frontend/editor/src/core/components/filesPage/FileDetailsPanel.tsx
+++ b/frontend/editor/src/core/components/filesPage/FileDetailsPanel.tsx
@@ -140,7 +140,7 @@ export function FileDetailsPanel({
return null;
}
- const single = files.length === 1 ? files[0]! : null;
+ const single = files.length === 1 ? files[0] : null;
const totalSize = files.reduce((sum, f) => sum + f.size, 0);
const ext = single ? (single.name.split(".").pop() ?? "").toUpperCase() : "";
// Files still needing a server upload; drives Save-to-server visibility.
diff --git a/frontend/editor/src/core/components/filesPage/FileGrid.tsx b/frontend/editor/src/core/components/filesPage/FileGrid.tsx
index cf425d79d6..62f35458d6 100644
--- a/frontend/editor/src/core/components/filesPage/FileGrid.tsx
+++ b/frontend/editor/src/core/components/filesPage/FileGrid.tsx
@@ -423,7 +423,7 @@ function GridView(props: FileGridProps) {
parentPath={entry.parentPath}
isSelected={selectedFileIds.has(entry.file.id)}
isInWorkspace={
- activeWorkspaceFileIds?.has(entry.file.id as string) ?? false
+ activeWorkspaceFileIds?.has(entry.file.id) ?? false
}
selectedFileIds={selectedFileIds}
multiSelectActive={selectedFileIds.size >= 2}
@@ -939,7 +939,7 @@ function FileCard({
shiftKey: false,
ctrlKey: true,
metaKey: true,
- } as unknown as React.MouseEvent);
+ });
}}
onChange={() => {
/* handled by onClick */
@@ -984,7 +984,7 @@ function FileCard({
·
{fileDate}
-
+
@@ -1139,7 +1139,7 @@ function ListView(
parentPath={entry.parentPath}
isSelected={selectedFileIds.has(entry.file.id)}
isInWorkspace={
- activeWorkspaceFileIds?.has(entry.file.id as string) ?? false
+ activeWorkspaceFileIds?.has(entry.file.id) ?? false
}
selectedFileIds={selectedFileIds}
multiSelectActive={selectedFileIds.size >= 2}
@@ -1426,7 +1426,7 @@ function FileRow({
shiftKey: false,
ctrlKey: true,
metaKey: true,
- } as unknown as React.MouseEvent);
+ });
}}
onChange={() => {
/* handled by onClick */
@@ -1494,7 +1494,7 @@ function FileRow({
-
+
{isInWorkspace && (
diff --git a/frontend/editor/src/core/components/filesPage/FileManagerView.tsx b/frontend/editor/src/core/components/filesPage/FileManagerView.tsx
index 36ffb9c4dc..4665784e79 100644
--- a/frontend/editor/src/core/components/filesPage/FileManagerView.tsx
+++ b/frontend/editor/src/core/components/filesPage/FileManagerView.tsx
@@ -474,7 +474,7 @@ export default function FileManagerView() {
if (idx >= 0 && lastIdx >= 0) {
const [a, b] = idx < lastIdx ? [idx, lastIdx] : [lastIdx, idx];
for (let i = a; i <= b; i += 1) {
- next.add(visibleFiles[i]!.id);
+ next.add(visibleFiles[i].id);
}
return next;
}
@@ -593,7 +593,7 @@ export default function FileManagerView() {
});
// Branch on requested stubs so already-active files still activate.
if (materialized.length === 1) {
- setActiveFileId(materialized[0]!.id);
+ setActiveFileId(materialized[0].id);
navActions.setWorkbench("viewer");
} else if (materialized.length > 1) {
navActions.setWorkbench("fileEditor");
@@ -1172,7 +1172,7 @@ export default function FileManagerView() {
else if (e.key === "End") next = TAB_DEFS.length - 1;
else return;
e.preventDefault();
- const target = TAB_DEFS[next]!;
+ const target = TAB_DEFS[next];
setCurrentTab(target.id);
focusTab(target.id);
}}
@@ -1602,7 +1602,7 @@ export default function FileManagerView() {
)
)
return;
- setViewMode(v as (typeof FILES_PAGE_VIEW_MODES)[number]);
+ setViewMode(v);
}}
aria-label={t("filesPage.viewMode.label", "View mode")}
options={[
diff --git a/frontend/editor/src/core/components/filesPage/FolderTreePanel.tsx b/frontend/editor/src/core/components/filesPage/FolderTreePanel.tsx
index eb7f19170c..b56915b757 100644
--- a/frontend/editor/src/core/components/filesPage/FolderTreePanel.tsx
+++ b/frontend/editor/src/core/components/filesPage/FolderTreePanel.tsx
@@ -121,7 +121,7 @@ export function FolderTreePanel({ active }: FolderTreePanelProps) {
- {t("filesPage.myFiles", "My Files")}
+ {t("fileSidebar.myFiles", "File library")}
diff --git a/frontend/editor/src/core/components/filesPage/VersionTimeline.tsx b/frontend/editor/src/core/components/filesPage/VersionTimeline.tsx
index 05c96685b2..f484f936ef 100644
--- a/frontend/editor/src/core/components/filesPage/VersionTimeline.tsx
+++ b/frontend/editor/src/core/components/filesPage/VersionTimeline.tsx
@@ -120,14 +120,14 @@ export function VersionTimeline({
};
const rows: Row[] = useMemo(() => {
if (!collapsible || showAllCollapsed) {
- return ordered.map((v) => ({ kind: "version", version: v }) as Row);
+ return ordered.map((v) => ({ kind: "version", version: v }));
}
const head = ordered
.slice(0, 3)
- .map((v) => ({ kind: "version", version: v }) as Row);
+ .map((v) => ({ kind: "version", version: v }));
const tail = ordered
.slice(-2)
- .map((v) => ({ kind: "version", version: v }) as Row);
+ .map((v) => ({ kind: "version", version: v }));
const hidden = ordered.length - 5;
return [...head, { kind: "ellipsis", hidden }, ...tail];
}, [collapsible, showAllCollapsed, ordered]);
diff --git a/frontend/editor/src/core/components/filesPage/filesPageReturnRoute.ts b/frontend/editor/src/core/components/filesPage/filesPageReturnRoute.ts
index 5e6292d62f..69a1bc1c53 100644
--- a/frontend/editor/src/core/components/filesPage/filesPageReturnRoute.ts
+++ b/frontend/editor/src/core/components/filesPage/filesPageReturnRoute.ts
@@ -1,6 +1,6 @@
/**
* Stores the route the user came from when they open files into the
- * workbench from My Files. Lets the workbench show a "Back to My Files"
+ * workbench from the file library. Lets the workbench show a "Back to File library"
* affordance and return to the exact folder they were browsing.
*
* Persisted in sessionStorage so a hard reload keeps the return path
diff --git a/frontend/editor/src/core/components/filesPage/folderTreeWidth.ts b/frontend/editor/src/core/components/filesPage/folderTreeWidth.ts
index 4aaf8099ec..a88b0e7f11 100644
--- a/frontend/editor/src/core/components/filesPage/folderTreeWidth.ts
+++ b/frontend/editor/src/core/components/filesPage/folderTreeWidth.ts
@@ -27,7 +27,7 @@ function depthOf(
let cursor: FolderRecord | undefined = folder;
while (cursor && cursor.parentFolderId) {
depth += 1;
- cursor = byId.get(cursor.parentFolderId as string);
+ cursor = byId.get(cursor.parentFolderId);
if (depth > 50) break;
}
return depth;
diff --git a/frontend/editor/src/core/components/layout/AppFrame.css b/frontend/editor/src/core/components/layout/AppFrame.css
new file mode 100644
index 0000000000..0cc20b30c6
--- /dev/null
+++ b/frontend/editor/src/core/components/layout/AppFrame.css
@@ -0,0 +1,18 @@
+/* ========== APP FRAME ========== */
+/* The rail's column, then whichever app is mounted, so a switch changes only the app. */
+.app-frame {
+ display: flex;
+ height: 100vh;
+ height: 100dvh; /* track mobile browser chrome */
+ overflow: hidden;
+ background-color: var(--c-bg);
+}
+
+/* min-width: 0 so the app shrinks instead of forcing the frame past the window. */
+.app-frame__content {
+ flex: 1;
+ min-width: 0;
+ height: 100%;
+}
+
+/* The rail hides itself below the mobile breakpoint - see QuickNavRailContainer.css. */
diff --git a/frontend/editor/src/core/components/layout/AppFrame.tsx b/frontend/editor/src/core/components/layout/AppFrame.tsx
new file mode 100644
index 0000000000..38fa92ecba
--- /dev/null
+++ b/frontend/editor/src/core/components/layout/AppFrame.tsx
@@ -0,0 +1,22 @@
+import { Suspense } from "react";
+import { Outlet } from "react-router-dom";
+import { LoadingFallback } from "@app/components/shared/LoadingFallback";
+import { QuickNavHostProvider } from "@app/contexts/QuickNavHostContext";
+import { QuickNavRailHost } from "@app/components/shared/quickNav/QuickNavRailHost";
+import "@app/components/layout/AppFrame.css";
+
+/** The rail renders once outside both apps; Suspense sits inside it, not above. */
+export function AppFrame() {
+ return (
+
+
+
+
+ }>
+
+
+
+
+
+ );
+}
diff --git a/frontend/editor/src/core/components/layout/NoAppChrome.tsx b/frontend/editor/src/core/components/layout/NoAppChrome.tsx
new file mode 100644
index 0000000000..04416c02f1
--- /dev/null
+++ b/frontend/editor/src/core/components/layout/NoAppChrome.tsx
@@ -0,0 +1,8 @@
+import { Outlet } from "react-router-dom";
+import { useSuppressQuickNavRail } from "@app/contexts/QuickNavHostContext";
+
+/** Pages that aren't the app: inside the frame for its providers, but with no rail. */
+export function NoAppChrome() {
+ useSuppressQuickNavRail();
+ return ;
+}
diff --git a/frontend/editor/src/core/components/layout/Workbench.module.css b/frontend/editor/src/core/components/layout/Workbench.module.css
index dd2b4a12bd..22d6fdc43c 100644
--- a/frontend/editor/src/core/components/layout/Workbench.module.css
+++ b/frontend/editor/src/core/components/layout/Workbench.module.css
@@ -12,10 +12,8 @@
.workbenchBarReopenTab {
position: absolute;
top: 100%;
- /* Right-align with the retract handle inside the bar: the bar's right
- margin (--nav-gutter) + 1px border + 8px bar padding + the handle's own
- 6px inset. */
- right: calc(var(--nav-gutter) + 15px);
+ /* Aligns with the retract handle: 8px bar padding plus its own 6px inset. */
+ right: 14px;
display: flex;
align-items: center;
justify-content: center;
diff --git a/frontend/editor/src/core/components/layout/Workbench.tsx b/frontend/editor/src/core/components/layout/Workbench.tsx
index 903c552fd2..0cac20e574 100644
--- a/frontend/editor/src/core/components/layout/Workbench.tsx
+++ b/frontend/editor/src/core/components/layout/Workbench.tsx
@@ -1,4 +1,4 @@
-import { useState, Suspense, lazy } from "react";
+import { useState, useEffect, useRef, Suspense, lazy } from "react";
import { useTranslation } from "react-i18next";
import KeyboardArrowDownIcon from "@mui/icons-material/KeyboardArrowDown";
import { Box, Loader, Center, Stack, Text } from "@mantine/core";
@@ -15,6 +15,7 @@ import { VIEWER_SUPPORTED_EXTENSIONS } from "@app/utils/fileUtils";
import { useAppConfig } from "@app/contexts/AppConfigContext";
import { useSigningOverlay } from "@app/contexts/SigningOverlayContext";
import { useCookieConsent } from "@app/hooks/useCookieConsent";
+import { useIsPhone } from "@app/hooks/useIsMobile";
import styles from "@app/components/layout/Workbench.module.css";
import WorkbenchBar from "@app/components/shared/WorkbenchBar";
@@ -58,10 +59,13 @@ export default function Workbench() {
setPageEditorFunctions,
setSidebarsVisible,
customWorkbenchViews,
+ readerMode,
} = useToolWorkflow();
const { handleToolSelect } = useToolWorkflow();
const { overlay: signingOverlay } = useSigningOverlay();
+ // Below this width the rail, and the bell it carries, is gone.
+ const isPhone = useIsPhone();
// Get navigation state - this is the source of truth
const { selectedTool: selectedToolId } = useNavigationState();
@@ -92,8 +96,20 @@ export default function Workbench() {
!isBaseWorkbench(currentView) ||
// Shared signing drives the viewer from the sidebar with no file in context.
(currentView === "viewer" && !!signingOverlay?.file);
- const showWorkbenchBar = topControlsAvailable && hasWorkbenchContent;
- const showFloatingSearch = topControlsAvailable && !hasWorkbenchContent;
+ // Reading hides the bar; the rail's Reader entry is the way back.
+ const showWorkbenchBar =
+ topControlsAvailable && hasWorkbenchContent && !readerMode;
+ const showFloatingSearch =
+ topControlsAvailable && !hasWorkbenchContent && !readerMode;
+
+ // On the transition, so reading sets the toolbar's start state without locking it.
+ const prevReaderModeRef = useRef(readerMode);
+ useEffect(() => {
+ if (readerMode !== prevReaderModeRef.current) {
+ setViewerToolbarCollapsed(readerMode);
+ prevReaderModeRef.current = readerMode;
+ }
+ }, [readerMode]);
const handlePreviewClose = () => {
setPreviewFile(null);
@@ -126,7 +142,7 @@ export default function Workbench() {
}
}
- // The "My Files" workbench is available regardless of whether files are
+ // The file-library workbench is available regardless of whether files are
// currently loaded into the workbench - it lives on top of the IDB store.
if (currentView === "myFiles") {
return ;
@@ -249,10 +265,8 @@ export default function Workbench() {
data-tour="workbench"
style={{ backgroundColor: "var(--c-bg)", minWidth: 0 }}
>
- {/* The bell normally rides in the workbench bar. Wherever that bar is not shown - My Files,
- an empty workbench, a custom view without top controls - it gets its own corner, rather
- than those being the places a user cannot see that something of theirs failed. */}
- {!showWorkbenchBar && (
+ {/* Phone only: above that the rail carries the bell, and here no bar does. */}
+ {isPhone && !showWorkbenchBar && (
diff --git a/frontend/editor/src/core/components/layout/WorkspaceFrame.css b/frontend/editor/src/core/components/layout/WorkspaceFrame.css
new file mode 100644
index 0000000000..05cabe95f9
--- /dev/null
+++ b/frontend/editor/src/core/components/layout/WorkspaceFrame.css
@@ -0,0 +1,16 @@
+/* ========== WORKSPACE FRAME ========== */
+/* Rail and sidebar side by side, full height. Shared by both apps. */
+.workspace-frame {
+ display: flex;
+ height: 100%;
+ flex-shrink: 0;
+ background-color: var(--c-bg);
+}
+
+/* On mobile the sidebar is a fixed drawer, so the frame stops laying out. */
+@media (max-width: 48rem) {
+ .workspace-frame {
+ display: block;
+ height: auto;
+ }
+}
diff --git a/frontend/editor/src/core/components/mobileSign/MobileDrawCanvas.tsx b/frontend/editor/src/core/components/mobileSign/MobileDrawCanvas.tsx
index 38c2be8e6c..8461727240 100644
--- a/frontend/editor/src/core/components/mobileSign/MobileDrawCanvas.tsx
+++ b/frontend/editor/src/core/components/mobileSign/MobileDrawCanvas.tsx
@@ -139,9 +139,9 @@ export const MobileDrawCanvas = forwardRef<
// where the per-frame synthetic event alone would drop curvature.
const events =
"getCoalescedEvents" in e.nativeEvent
- ? (e.nativeEvent as PointerEvent).getCoalescedEvents()
+ ? e.nativeEvent.getCoalescedEvents()
: [e.nativeEvent as PointerEvent];
- const rect = (e.currentTarget as HTMLCanvasElement).getBoundingClientRect();
+ const rect = e.currentTarget.getBoundingClientRect();
for (const ev of events) {
stroke.points.push({
x: ev.clientX - rect.left,
diff --git a/frontend/editor/src/core/components/notifications/NotificationBell.css b/frontend/editor/src/core/components/notifications/NotificationBell.css
index 9352f6bef8..46367a0b2b 100644
--- a/frontend/editor/src/core/components/notifications/NotificationBell.css
+++ b/frontend/editor/src/core/components/notifications/NotificationBell.css
@@ -10,7 +10,7 @@
position: relative;
padding: var(--sp-2, 0.5rem);
border: none;
- border-radius: var(--radius-md, 0.375rem);
+ border-radius: var(--radius-md);
background: transparent;
color: var(--c-text-muted);
cursor: pointer;
@@ -48,6 +48,12 @@
box-shadow: 0 10px 30px rgb(0 0 0 / 25%);
}
+/* The rail's bell is at the foot of a full-height column, so its panel rises beside it. */
+.notification-bell__panel--rail {
+ inset-inline-start: calc(var(--nav-rail-w) + var(--nav-gutter));
+ inset-block-end: var(--nav-gutter);
+}
+
.notification-bell__heading {
margin: 0 0 var(--sp-2, 0.5rem);
font-size: 0.875rem;
diff --git a/frontend/editor/src/core/components/notifications/NotificationBell.tsx b/frontend/editor/src/core/components/notifications/NotificationBell.tsx
index f2ac1e0a3a..def06eed8d 100644
--- a/frontend/editor/src/core/components/notifications/NotificationBell.tsx
+++ b/frontend/editor/src/core/components/notifications/NotificationBell.tsx
@@ -1,27 +1,15 @@
-import {
- Fragment,
- useEffect,
- useId,
- useLayoutEffect,
- useRef,
- useState,
-} from "react";
+import { useLayoutEffect, useRef, useState } from "react";
import { useTranslation } from "react-i18next";
import { BellIcon, Button } from "@app/ui";
-import DividerWithText from "@app/components/shared/DividerWithText";
import { useNotifications } from "@app/hooks/useNotifications";
import { useNotificationActions } from "@app/components/notifications/notificationActions";
-import { NotificationItem } from "@app/components/notifications/NotificationItem";
+import { NotificationPanel } from "@app/components/notifications/NotificationPanel";
import { useNotificationsAvailable } from "@app/components/notifications/useNotificationsAvailable";
import "@app/components/notifications/NotificationBell.css";
-/**
- * Renders whatever the server sends without knowing which subsystem produced it or what its actions
- * mean, so a new source or failure kind needs no change here. In core because both shells mount it.
- */
+/** For the narrow layouts where the rail, which carries the bell, is off screen. */
export function NotificationBell() {
- // A build with no notifications API gets no bell at all, rather than one that polls a
- // nonexistent endpoint forever to show nothing.
+ // No API means no bell at all, rather than one polling an endpoint that isn't there.
const available = useNotificationsAvailable();
if (!available) return null;
return ;
@@ -29,14 +17,10 @@ export function NotificationBell() {
function MountedNotificationBell() {
const { t } = useTranslation();
- const { notifications, unreadCount, documentStateFor, markAllSeen } =
- useNotifications();
+ const { unreadCount } = useNotifications();
const registry = useNotificationActions();
const [open, setOpen] = useState(false);
const container = useRef(null);
- const headingId = useId();
- // Where the new ones stop, frozen when the panel opens (opening marks everything read).
- const [firstSeenId, setFirstSeenId] = useState(null);
// Viewport-fixed, because the workbench bar clips its own overflow.
const [anchor, setAnchor] = useState<{ top: number; right: number } | null>(
null,
@@ -61,54 +45,17 @@ function MountedNotificationBell() {
};
}, [open]);
- // Opening marks them read, not closing: waiting would leave the badge lit while they read.
- const toggle = () => {
- setOpen((wasOpen) => {
- if (!wasOpen) {
- // Before marking, or there is nothing left to read.
- setFirstSeenId(notifications[unreadCount]?.id ?? null);
- markAllSeen();
- }
- return !wasOpen;
- });
- };
-
- /**
- * How many count as new. No boundary id means all of them were; one that has since left the list
- * leaves nothing to divide on, so it reads as none rather than guessing at a row.
- */
- const boundaryIndex = firstSeenId
- ? notifications.findIndex((notification) => notification.id === firstSeenId)
- : notifications.length;
- const dividedAt = Math.max(0, boundaryIndex);
-
- useEffect(() => {
- if (!open) return;
- const closeOnOutside = (event: MouseEvent) => {
- const target = event.target as HTMLElement;
- if (!container.current?.contains(target)) setOpen(false);
- };
- const closeOnEscape = (event: KeyboardEvent) => {
- if (event.key === "Escape") setOpen(false);
- };
- document.addEventListener("mousedown", closeOnOutside);
- document.addEventListener("keydown", closeOnEscape);
- return () => {
- document.removeEventListener("mousedown", closeOnOutside);
- document.removeEventListener("keydown", closeOnEscape);
- };
- }, [open]);
-
return (
- )}
- {/* Only with something on both sides: a lone "Earlier" over everything says
- nothing the empty badge has not. */}
- {index === dividedAt && dividedAt > 0 && (
-
-
-
- )}
- setOpen(false)}
- />
-
- ))}
-
- )}
-
+ />
)}
);
diff --git a/frontend/editor/src/core/components/notifications/NotificationPanel.tsx b/frontend/editor/src/core/components/notifications/NotificationPanel.tsx
new file mode 100644
index 0000000000..f3ff0c621e
--- /dev/null
+++ b/frontend/editor/src/core/components/notifications/NotificationPanel.tsx
@@ -0,0 +1,135 @@
+import { Fragment, useEffect, useId, useRef, useState } from "react";
+import { useTranslation } from "react-i18next";
+import DividerWithText from "@app/components/shared/DividerWithText";
+import { useNotifications } from "@app/hooks/useNotifications";
+import type { ClientActionRegistry } from "@app/components/notifications/notificationActions";
+import { NotificationItem } from "@app/components/notifications/NotificationItem";
+import "@app/components/notifications/NotificationBell.css";
+
+/** Named so a trigger in another tree can point at it with aria-controls. */
+export const NOTIFICATIONS_PANEL_ID = "quick-nav-notifications-panel";
+
+export interface NotificationPanelProps {
+ onClose: () => void;
+ id?: string;
+ /** Passed in: its document handover has to run whether the panel is open or not. */
+ registry: ClientActionRegistry;
+ style?: React.CSSProperties;
+ className?: string;
+}
+
+/** Mounted only while open, since mounting is what marks everything read. */
+export function NotificationPanel({
+ onClose,
+ registry,
+ id,
+ style,
+ className,
+}: NotificationPanelProps) {
+ const { t } = useTranslation();
+ const { notifications, unreadCount, documentStateFor, markAllSeen } =
+ useNotifications();
+ const panel = useRef(null);
+ const headingId = useId();
+ // Frozen on open, since opening marks them all read.
+ const [firstSeenId, setFirstSeenId] = useState(null);
+
+ // On mount, not on close: waiting leaves the badge lit while they read.
+ const marked = useRef(false);
+ useEffect(() => {
+ if (marked.current) return;
+ marked.current = true;
+ // Before marking, or there is nothing left to divide on.
+ setFirstSeenId(notifications[unreadCount]?.id ?? null);
+ markAllSeen();
+ }, [notifications, unreadCount, markAllSeen]);
+
+ // No boundary means all were new; one that has left the list means none.
+ const boundaryIndex = firstSeenId
+ ? notifications.findIndex((notification) => notification.id === firstSeenId)
+ : notifications.length;
+ const dividedAt = Math.max(0, boundaryIndex);
+
+ // Focus goes back to the opener only if it is still inside the panel on close.
+ useEffect(() => {
+ const opener = document.activeElement as HTMLElement | null;
+ panel.current?.focus();
+ return () => {
+ if (panel.current?.contains(document.activeElement)) opener?.focus();
+ };
+ }, []);
+
+ useEffect(() => {
+ const closeOnOutside = (event: MouseEvent) => {
+ const target = event.target as HTMLElement;
+ if (panel.current?.contains(target)) return;
+ // A trigger closes this itself; counting it as outside would reopen it.
+ if (target.closest?.("[data-notifications-trigger]")) return;
+ onClose();
+ };
+ const closeOnEscape = (event: KeyboardEvent) => {
+ if (event.key === "Escape") onClose();
+ };
+ document.addEventListener("mousedown", closeOnOutside);
+ document.addEventListener("keydown", closeOnEscape);
+ return () => {
+ document.removeEventListener("mousedown", closeOnOutside);
+ document.removeEventListener("keydown", closeOnEscape);
+ };
+ }, [onClose]);
+
+ return (
+
+
+ {t("notifications.title", "Notifications")}
+
+
+ {notifications.length === 0 ? (
+
+ {t("notifications.empty", "Nothing to report.")}
+
+
{/* Box 1 — top controls (open / my files / cloud). No title. File
search lives in the global super search (top bar), not here. */}
@@ -984,7 +972,7 @@ const FileSidebar = forwardRef(
{/* Tooltips only fire when collapsed - when expanded the visible
text label below already identifies each row, so a tooltip
would just flash a duplicate. Distinct icons (UploadFile for
- "Open from computer" vs FolderOpen for "My Files") so the
+ "Open from computer" vs FolderOpen for "File library") so the
collapsed rail isn't two identical folder icons either. */}
(
onClick={() => {
// "Open from computer" goes straight to the native OS file
// picker. The full file manager (recent + drives + folders)
- // is reachable via "My Files" below.
+ // is reachable via "File library" below.
nativeFileInputRef.current?.click();
}}
role="button"
@@ -1080,7 +1068,7 @@ const FileSidebar = forwardRef(
)}
(
}}
role="button"
tabIndex={0}
- aria-label={t("fileSidebar.myFiles", "My Files")}
+ aria-label={t("fileSidebar.myFiles", "File library")}
onKeyDown={(e) => {
if (e.key === "Enter" || e.key === " ") {
e.preventDefault();
@@ -1105,7 +1093,7 @@ const FileSidebar = forwardRef(
{!collapsed && (
- {t("fileSidebar.myFiles", "My Files")}
+ {t("fileSidebar.myFiles", "File library")}
)}
@@ -1370,15 +1358,15 @@ const FileSidebar = forwardRef(
{/* Getting-started checklist, floating above the footer (SaaS only). */}
- {/* Box 3 — the shared footer: credits, app switch, account row. */}
+ {/* Box 3 — the shared footer: credits, plan, and the account row unless hoisted. */}
diff --git a/frontend/editor/src/core/components/shared/SidebarHeader.tsx b/frontend/editor/src/core/components/shared/SidebarHeader.tsx
new file mode 100644
index 0000000000..1a2befa074
--- /dev/null
+++ b/frontend/editor/src/core/components/shared/SidebarHeader.tsx
@@ -0,0 +1,33 @@
+import { Logo } from "@app/ui/Logo";
+import { SidebarToggleButton } from "@app/components/shared/SidebarToggleButton";
+
+export interface SidebarHeaderProps {
+ collapsed?: boolean;
+ onToggleCollapse?: () => void;
+ toggleAriaLabel?: string;
+ toggleIcon?: React.ReactNode;
+ className?: string;
+}
+
+/** The wordmark and the collapse toggle; the brand mark sits in the rail beside it. */
+export function SidebarHeader({
+ collapsed,
+ onToggleCollapse,
+ toggleAriaLabel,
+ toggleIcon,
+ className,
+}: SidebarHeaderProps) {
+ return (
+
- )}
+ {header && }
- {/* Left: optional "Back to My Files" + view switcher */}
+ {/* Left: optional "Back to File library" + view switcher */}
{returnRoute && hasFiles && (
<>
@@ -501,7 +503,7 @@ export default function WorkbenchBar({
: "filesPage.backToMyFiles",
returnRoute.label
? `Back to ${returnRoute.label}`
- : "Back to My Files",
+ : "Back to File library",
{ folder: returnRoute.label ?? "" },
)}
leftSection={}
@@ -511,7 +513,7 @@ export default function WorkbenchBar({
? t("filesPage.backToFolder", "Back to {{folder}}", {
folder: returnRoute.label,
})
- : t("filesPage.backToMyFiles", "Back to My Files")}
+ : t("filesPage.backToMyFiles", "Back to File library")}
@@ -603,9 +605,13 @@ export default function WorkbenchBar({
enforcingProgress={enforcingProgress}
/>
)}
- {/* Last in the globals, so it is the rightmost control. */}
-
-
+ {isPhone && (
+ <>
+ {/* Last in the globals, so it is the rightmost control. */}
+
+
+
+ )}
);
diff --git a/frontend/editor/src/core/components/shared/navFooter/NavFooter.tsx b/frontend/editor/src/core/components/shared/navFooter/NavFooter.tsx
index 373c91bccf..848c0cb4a5 100644
--- a/frontend/editor/src/core/components/shared/navFooter/NavFooter.tsx
+++ b/frontend/editor/src/core/components/shared/navFooter/NavFooter.tsx
@@ -33,6 +33,8 @@ export interface NavFooterProps {
otherApp?: NavFooterAppLink | null;
/** Extra rows above the account row (the self-hosted link-account CTA). */
accountExtras?: ReactNode;
+ /** False where the rail owns the account control, so only one avatar is drawn. */
+ showAccount?: boolean;
/** Icon-rail state: labels collapse to tooltips. */
collapsed?: boolean;
className?: string;
@@ -69,6 +71,7 @@ export function NavFooter({
onOpenPlan,
otherApp,
accountExtras,
+ showAccount = true,
collapsed = false,
className,
}: NavFooterProps) {
@@ -144,49 +147,51 @@ export function NavFooter({
});
}
- rows.push({
- key: "account",
- node: (
-
-
+
+ ),
+ });
+ }
+
+ if (rows.length === 0) return null;
return (
void;
+}
+
+export function QuickNavBrand({ onReturnHome }: QuickNavBrandProps) {
+ const { t } = useTranslation();
+ const label = t("quickNav.home", "Stirling");
+
+ return (
+
+
+
+
+
+ );
+}
diff --git a/frontend/editor/src/core/components/shared/quickNav/QuickNavHostBridge.tsx b/frontend/editor/src/core/components/shared/quickNav/QuickNavHostBridge.tsx
new file mode 100644
index 0000000000..d97674464e
--- /dev/null
+++ b/frontend/editor/src/core/components/shared/quickNav/QuickNavHostBridge.tsx
@@ -0,0 +1,88 @@
+import { useCallback, useMemo, useState } from "react";
+import { useAccountIdentity } from "@app/hooks/useAccountIdentity";
+import {
+ NotificationPanel,
+ NOTIFICATIONS_PANEL_ID,
+} from "@app/components/notifications/NotificationPanel";
+import { useNotificationActions } from "@app/components/notifications/notificationActions";
+import { useQuickNavToolReasons } from "@app/components/shared/quickNav/useQuickNavToolReasons";
+import { useNotificationsAvailable } from "@app/components/notifications/useNotificationsAvailable";
+import { useSigningBadgeCount } from "@app/hooks/signing/useSigningBadgeCount";
+import {
+ useRegisterQuickNavHost,
+ type QuickNavToolReasons,
+} from "@app/contexts/QuickNavHostContext";
+import type { ToolId } from "@app/types/toolId";
+
+export interface QuickNavHostBridgeProps {
+ portalAccess?: boolean;
+ readerMode?: boolean;
+ onSetReaderMode?: (on: boolean) => void;
+ onOpenSettings: () => void;
+ requestNavigation?: (go: () => void) => void;
+ onGoToDefaultState?: () => void;
+ onSelectTool?: (toolId: ToolId) => void;
+ activeTool?: ToolId | null;
+ /** Merged over the reasons worked out here, for what only the app can see. */
+ toolReasons?: QuickNavToolReasons;
+}
+
+/** Registers with the rail what only the app can see, and owns the notifications panel. */
+export function QuickNavHostBridge({
+ portalAccess = false,
+ readerMode = false,
+ onSetReaderMode,
+ onOpenSettings,
+ requestNavigation,
+ onSelectTool,
+ activeTool = null,
+ onGoToDefaultState,
+ toolReasons,
+}: QuickNavHostBridgeProps) {
+ const { displayName, profilePictureUrl } = useAccountIdentity();
+ const signingBadge = useSigningBadgeCount();
+ const notificationsAvailable = useNotificationsAvailable();
+ // Built even when closed: it carries a one-shot document pickup that would sit unclaimed.
+ const notificationActions = useNotificationActions();
+ const endpointReasons = useQuickNavToolReasons();
+ const mergedToolReasons = useMemo(() => {
+ // An empty map from the app is silence, not an answer.
+ const extra =
+ toolReasons && Object.keys(toolReasons).length > 0 ? toolReasons : null;
+ if (!endpointReasons && !extra) return undefined;
+ return { ...endpointReasons, ...extra };
+ }, [endpointReasons, toolReasons]);
+ const [notificationsOpen, setNotificationsOpen] = useState(false);
+ const closeNotifications = useCallback(() => setNotificationsOpen(false), []);
+
+ useRegisterQuickNavHost(
+ {
+ identity: { displayName, profilePictureUrl },
+ signingBadge,
+ portalAccess,
+ readerMode,
+ activeTool,
+ notificationsOpen,
+ toolReasons: mergedToolReasons,
+ },
+ {
+ openSettings: onOpenSettings,
+ requestNavigation,
+ selectTool: onSelectTool,
+ setReaderMode: onSetReaderMode,
+ goToDefaultState: onGoToDefaultState,
+ toggleNotifications: () => setNotificationsOpen((open) => !open),
+ },
+ );
+
+ // Mounted only while open, so a closed panel never subscribes to the poll.
+ if (!notificationsAvailable || !notificationsOpen) return null;
+ return (
+
+ );
+}
diff --git a/frontend/editor/src/core/components/shared/quickNav/QuickNavRail.css b/frontend/editor/src/core/components/shared/quickNav/QuickNavRail.css
new file mode 100644
index 0000000000..4d6845f592
--- /dev/null
+++ b/frontend/editor/src/core/components/shared/quickNav/QuickNavRail.css
@@ -0,0 +1,173 @@
+/* ========== QUICK NAV RAIL ========== */
+
+.quick-nav-rail {
+ display: flex;
+ flex-direction: column;
+ align-items: center;
+ height: 100%;
+ width: 100%;
+}
+
+.quick-nav-rail-group {
+ display: flex;
+ flex-direction: column;
+ align-items: center;
+ gap: var(--quicknav-item-gap);
+ flex-shrink: 0;
+ width: 100%;
+}
+
+/* The glyph stays at the sidebar's scale; the button fills the rail for hit area. */
+.quick-nav-rail-item {
+ position: relative;
+ display: inline-flex;
+ align-items: center;
+ justify-content: center;
+ width: 100%;
+ height: 2.25rem;
+ padding: 0;
+ border: none;
+ border-radius: var(--radius-md);
+ background: transparent;
+ color: var(--c-text-subtle);
+ cursor: pointer;
+ transition:
+ background-color var(--motion-fast),
+ color var(--motion-fast);
+}
+
+.quick-nav-rail-item svg,
+.quick-nav-rail-item img {
+ width: 1.125rem;
+ height: 1.125rem;
+ color: inherit;
+ fill: currentColor;
+}
+
+/* Taller than wide (71x79), so height drives the width. */
+.quick-nav-rail-item .sui-brandmark {
+ width: auto;
+ height: 1.125rem;
+}
+
+.quick-nav-rail-item[aria-disabled="true"] .sui-brandmark,
+.quick-nav-rail-item[aria-disabled="true"] svg[viewBox="0 0 256 256"] {
+ filter: grayscale(1);
+}
+
+.quick-nav-rail-item:hover {
+ background: var(--c-hover);
+ color: var(--c-text);
+}
+
+/* Opacity rather than a colour: there is no disabled-text token. */
+.quick-nav-rail-item[aria-disabled="true"] {
+ opacity: 0.5;
+ cursor: not-allowed;
+}
+.quick-nav-rail-item[aria-disabled="true"]:hover {
+ background: transparent;
+ color: var(--c-primary);
+}
+
+.quick-nav-rail-item:focus-visible {
+ outline: 0.125rem solid var(--c-primary);
+ outline-offset: -0.125rem;
+}
+
+.quick-nav-rail-badge {
+ position: absolute;
+ top: 0.125rem;
+ inset-inline-end: 0.125rem;
+ min-width: 0.875rem;
+ height: 0.875rem;
+ padding: 0 0.1875rem;
+ border-radius: var(--radius-pill);
+ /* The solid step: 9px numerals need the darker end of the ramp. */
+ background: var(--c-danger-solid);
+ color: var(--c-text-on-primary);
+ font-size: 0.5625rem;
+ font-weight: var(--font-weight-semibold);
+ line-height: 0.875rem;
+ text-align: center;
+ font-variant-numeric: tabular-nums;
+ pointer-events: none;
+}
+
+.quick-nav-rail-badge[data-tone="warning"] {
+ background: var(--c-warning-solid);
+}
+
+/* Top margin only: the group below supplies the other half, centring the rule. */
+.quick-nav-rail-divider {
+ width: 100%;
+ height: 0;
+ margin: var(--quicknav-item-gap) 0 0;
+ border: 0;
+ border-top: 1px solid var(--c-border);
+}
+
+.quick-nav-rail-footer {
+ margin-top: auto;
+ display: flex;
+ flex-direction: column;
+ align-items: center;
+ gap: var(--quicknav-item-gap);
+ width: 100%;
+ flex-shrink: 0;
+}
+
+/* ---- Brand: one header row tall, so it lines up with the sidebar's wordmark ---- */
+.quick-nav-brand {
+ width: 100%;
+ height: var(--nav-header-h);
+ flex-shrink: 0;
+ /* The bar's inset supplies part of the gap; only the remainder is added here. */
+ margin-bottom: calc(var(--quicknav-item-gap) - var(--quicknav-surface-pad));
+}
+
+.quick-nav-brand-button {
+ display: flex;
+ align-items: center;
+ justify-content: center;
+ width: 100%;
+ height: 100%;
+ border: none;
+ background: transparent;
+ padding: 0;
+ cursor: pointer;
+}
+
+.quick-nav-brand-button:focus-visible {
+ outline: 0.125rem solid var(--c-primary);
+ outline-offset: -0.125rem;
+ border-radius: var(--radius-md);
+}
+
+/* The "on" state: a solid block with the glyph knocked out, hover owning the tints. */
+.quick-nav-rail-item[aria-current="true"],
+.quick-nav-rail-item[aria-current="true"]:hover,
+.quick-nav-rail-item[aria-pressed="true"],
+.quick-nav-rail-item[aria-pressed="true"]:hover {
+ background: var(--c-text);
+ color: var(--c-surface);
+}
+
+/* On a dark ground full ink is white, so mix the block back toward the surface. */
+[data-theme="dark"] .quick-nav-rail-item[aria-current="true"],
+[data-theme="dark"] .quick-nav-rail-item[aria-current="true"]:hover,
+[data-theme="dark"] .quick-nav-rail-item[aria-pressed="true"],
+[data-theme="dark"] .quick-nav-rail-item[aria-pressed="true"]:hover,
+html[data-app-theme="midnight"] .quick-nav-rail-item[aria-current="true"],
+html[data-app-theme="midnight"] .quick-nav-rail-item[aria-current="true"]:hover,
+html[data-app-theme="midnight"] .quick-nav-rail-item[aria-pressed="true"],
+html[data-app-theme="midnight"] .quick-nav-rail-item[aria-pressed="true"]:hover,
+[data-mantine-color-scheme="dark"] .quick-nav-rail-item[aria-current="true"],
+[data-mantine-color-scheme="dark"]
+ .quick-nav-rail-item[aria-current="true"]:hover,
+[data-mantine-color-scheme="dark"] .quick-nav-rail-item[aria-pressed="true"],
+[data-mantine-color-scheme="dark"]
+ .quick-nav-rail-item[aria-pressed="true"]:hover {
+ background: color-mix(in srgb, var(--c-text) 80%, var(--c-surface));
+ color: var(--c-surface);
+}
diff --git a/frontend/editor/src/core/components/shared/quickNav/QuickNavRailAccount.css b/frontend/editor/src/core/components/shared/quickNav/QuickNavRailAccount.css
new file mode 100644
index 0000000000..c12a6a1f71
--- /dev/null
+++ b/frontend/editor/src/core/components/shared/quickNav/QuickNavRailAccount.css
@@ -0,0 +1,29 @@
+/* The account control, pinned to the bottom of the bar. */
+
+.quick-nav-rail-account {
+ display: flex;
+ flex-direction: column;
+ align-items: center;
+ gap: var(--space-1);
+ flex-shrink: 0;
+ /* Further than the shortcut gap: a filled disc reads heavier than a line glyph. */
+ margin-top: var(--space-2);
+ /* Matches the slack centring the brand mark leaves at the top. */
+ padding-bottom: 0.3125rem;
+}
+
+.quick-nav-rail-avatar-target {
+ display: inline-flex;
+}
+
+/* Appearance comes from the shared Avatar; only the button reset is ours. */
+.quick-nav-rail-avatar {
+ border: none;
+ padding: 0;
+ user-select: none;
+}
+
+.quick-nav-rail-avatar:focus-visible {
+ outline: 0.125rem solid var(--c-primary);
+ outline-offset: 0.125rem;
+}
diff --git a/frontend/editor/src/core/components/shared/quickNav/QuickNavRailAccount.tsx b/frontend/editor/src/core/components/shared/quickNav/QuickNavRailAccount.tsx
new file mode 100644
index 0000000000..1404925de6
--- /dev/null
+++ b/frontend/editor/src/core/components/shared/quickNav/QuickNavRailAccount.tsx
@@ -0,0 +1,45 @@
+import { useTranslation } from "react-i18next";
+import { Tooltip } from "@app/components/shared/Tooltip";
+import { Avatar } from "@app/ui/Avatar";
+import type { QuickNavIdentity } from "@app/contexts/QuickNavHostContext";
+import "@app/components/shared/quickNav/QuickNavRailAccount.css";
+
+export interface QuickNavRailAccountProps {
+ onOpenSettings: () => void;
+ /** Null between apps; the disc still renders, so the bar keeps its shape. */
+ identity: QuickNavIdentity | null;
+}
+
+/** The avatar opens settings, so there is no separate gear beside it. */
+export function QuickNavRailAccount({
+ onOpenSettings,
+ identity,
+}: QuickNavRailAccountProps) {
+ const { t } = useTranslation();
+ const displayName =
+ identity?.displayName ?? t("auth.displayName.user", "User");
+ const profilePictureUrl = identity?.profilePictureUrl ?? null;
+ const label = `${displayName} — ${t("fileSidebar.openSettings", "Open settings")}`;
+
+ return (
+
+
+ {/* A span, not the Avatar: Tooltip binds by cloning its child. */}
+
+
+
+
+
+ );
+}
diff --git a/frontend/editor/src/core/components/shared/quickNav/QuickNavRailBase.test.tsx b/frontend/editor/src/core/components/shared/quickNav/QuickNavRailBase.test.tsx
new file mode 100644
index 0000000000..328f2d8f4e
--- /dev/null
+++ b/frontend/editor/src/core/components/shared/quickNav/QuickNavRailBase.test.tsx
@@ -0,0 +1,123 @@
+import { describe, it, expect } from "vitest";
+import { render } from "@testing-library/react";
+import {
+ QuickNavRailBase,
+ type QuickNavEntry,
+} from "@app/components/shared/quickNav/QuickNavRailBase";
+
+/** The rail needs no providers. */
+function withProviders(ui: React.ReactNode) {
+ return <>{ui};
+}
+
+function entry(
+ id: string,
+ overrides: Partial = {},
+): QuickNavEntry {
+ return {
+ id,
+ label: id,
+ icon: null,
+ onClick: () => {},
+ ...overrides,
+ };
+}
+
+const PROCESSOR = entry("processor");
+const WITHIN = [entry("files"), entry("reader")];
+
+function renderRail(groups: QuickNavEntry[][]) {
+ const { container } = render(
+ withProviders(),
+ );
+ return {
+ labels: [...container.querySelectorAll(".quick-nav-rail-item")].map((b) =>
+ b.getAttribute("aria-label"),
+ ),
+ dividers: container.querySelectorAll(".quick-nav-rail-divider").length,
+ };
+}
+
+describe("QuickNavRailBase — groups", () => {
+ it("divides one group from the next", () => {
+ const { labels, dividers } = renderRail([[PROCESSOR], WITHIN]);
+
+ expect(labels).toEqual(["processor", "files", "reader"]);
+ expect(dividers).toBe(1);
+ });
+
+ it("drops an empty group, and the divider with it", () => {
+ const { labels, dividers } = renderRail([[], WITHIN]);
+
+ expect(labels).toEqual(["files", "reader"]);
+ expect(dividers).toBe(0);
+ });
+});
+
+describe("QuickNavRailBase — entry state", () => {
+ it("reports on/off for a toggle and nothing for the rest", () => {
+ // Nothing here is a view you occupy, so only a real toggle has state.
+ const { container } = render(
+ withProviders(
+ ,
+ ),
+ );
+
+ const state = [...container.querySelectorAll(".quick-nav-rail-item")].map(
+ (b) => [b.getAttribute("aria-label"), b.getAttribute("aria-pressed")],
+ );
+ expect(state).toEqual([
+ ["processor", null],
+ ["reader", "true"],
+ ["files", null],
+ ]);
+ expect(container.querySelectorAll("[aria-current]")).toHaveLength(0);
+ });
+
+ it("keeps a disabled entry in the tab order so its reason stays reachable", () => {
+ // The tooltip carrying the reason is only reachable while it can be focused.
+ const { container } = render(
+ withProviders(
+ ,
+ ),
+ );
+
+ const automate = container.querySelector('[aria-label="automate"]')!;
+ expect(automate.getAttribute("aria-disabled")).toBe("true");
+ expect(automate.hasAttribute("disabled")).toBe(false);
+ });
+
+ it("keeps an unavailable entry rendered, disabled rather than dropped", () => {
+ // Slots must not appear and vanish as access resolves.
+ const { container } = render(
+ withProviders(
+ ,
+ ),
+ );
+
+ const processor = container.querySelector('[aria-label="processor"]');
+ expect(processor).not.toBeNull();
+ expect(processor?.getAttribute("aria-disabled")).toBe("true");
+ // aria-disabled, not the disabled attribute: it stays focusable for its tooltip.
+ expect(processor?.hasAttribute("disabled")).toBe(false);
+ });
+});
diff --git a/frontend/editor/src/core/components/shared/quickNav/QuickNavRailBase.tsx b/frontend/editor/src/core/components/shared/quickNav/QuickNavRailBase.tsx
new file mode 100644
index 0000000000..5c0be45db0
--- /dev/null
+++ b/frontend/editor/src/core/components/shared/quickNav/QuickNavRailBase.tsx
@@ -0,0 +1,101 @@
+import type { ReactNode } from "react";
+import { useTranslation } from "react-i18next";
+import { Tooltip } from "@app/components/shared/Tooltip";
+import "@app/components/shared/quickNav/QuickNavRail.css";
+
+export type QuickNavTarget = "reader" | "editor" | "files" | "processor";
+
+export interface QuickNavEntry {
+ id: string;
+ label: string;
+ icon: ReactNode;
+ /** The app you are in, drawn with an edge bar. */
+ current?: boolean;
+ /** Only for entries that toggle something; use `current` for the app you are in. */
+ pressed?: boolean;
+ /** Inert, with `reason` as its tooltip. Entries are dimmed, never dropped. */
+ disabled?: boolean;
+ reason?: string;
+ badge?: number;
+ /** Popup semantics for an entry whose panel is rendered in another tree. */
+ expanded?: boolean;
+ controls?: string;
+ /** "danger" waits on the user; "warning" is awareness only. */
+ badgeTone?: "danger" | "warning";
+ onClick: () => void;
+}
+
+export interface QuickNavRailBaseProps {
+ /** Divided by a rule; empty groups are dropped. */
+ groups: QuickNavEntry[][];
+ footer?: ReactNode;
+}
+
+/** Exported so footer entries reuse it rather than a lookalike. */
+export function RailButton({
+ label,
+ icon,
+ pressed,
+ disabled,
+ reason,
+ badge,
+ badgeTone = "danger",
+ current,
+ expanded,
+ controls,
+ onClick,
+}: Omit) {
+ return (
+
+
+
+ );
+}
+
+export function QuickNavRailBase({ groups, footer }: QuickNavRailBaseProps) {
+ const { t } = useTranslation();
+ const populated = groups.filter((entries) => entries.length > 0);
+ return (
+
+ );
+}
diff --git a/frontend/editor/src/core/components/shared/quickNav/QuickNavRailContainer.css b/frontend/editor/src/core/components/shared/quickNav/QuickNavRailContainer.css
new file mode 100644
index 0000000000..606c2c3831
--- /dev/null
+++ b/frontend/editor/src/core/components/shared/quickNav/QuickNavRailContainer.css
@@ -0,0 +1,38 @@
+.quick-nav-rail-container {
+ /* On the column, so the parts outside the nav inherit them too. */
+ --quicknav-item-gap: var(--space-3);
+ --quicknav-surface-pad: 0.375rem;
+
+ width: var(--nav-rail-w);
+ height: 100%;
+ flex-shrink: 0;
+ box-sizing: border-box;
+ /* On the column, not the bar, so the fill covers the gutters too. */
+ background-color: var(--c-surface);
+ border-inline-end: 1px solid var(--c-border-subtle);
+ display: flex;
+ flex-direction: column;
+ padding-block: var(--nav-gutter);
+ padding-inline: calc(var(--nav-gutter) / 2);
+}
+
+/* Child selector to beat .sui-nav-surface, which would win on order. */
+.quick-nav-rail-container > .quick-nav-rail-surface {
+ background: transparent;
+ border: 0;
+ border-radius: 0;
+}
+
+.quick-nav-rail-surface {
+ flex: 1;
+ min-height: 0;
+ /* No inline padding: the bar is one target wide and would squeeze the buttons. */
+ padding: var(--quicknav-surface-pad) 0;
+}
+
+/* Below this width the sidebar is an off-canvas drawer, and the rail is just noise. */
+@media (max-width: 48rem) {
+ .quick-nav-rail-container {
+ display: none;
+ }
+}
diff --git a/frontend/editor/src/core/components/shared/quickNav/QuickNavRailContainer.tsx b/frontend/editor/src/core/components/shared/quickNav/QuickNavRailContainer.tsx
new file mode 100644
index 0000000000..154700518e
--- /dev/null
+++ b/frontend/editor/src/core/components/shared/quickNav/QuickNavRailContainer.tsx
@@ -0,0 +1,83 @@
+import { useTranslation } from "react-i18next";
+import { NavSurface } from "@app/ui/NavSurface";
+import LocalIcon from "@app/components/shared/LocalIcon";
+import { QuickNavBrand } from "@app/components/shared/quickNav/QuickNavBrand";
+import type { QuickNavIdentity } from "@app/contexts/QuickNavHostContext";
+import {
+ QuickNavRailBase,
+ RailButton,
+ type QuickNavRailBaseProps,
+} from "@app/components/shared/quickNav/QuickNavRailBase";
+import { QuickNavRailAccount } from "@app/components/shared/quickNav/QuickNavRailAccount";
+import { QuickNavRailNotifications } from "@app/components/shared/quickNav/QuickNavRailNotifications";
+import "@app/components/shared/quickNav/QuickNavRailContainer.css";
+
+export type {
+ QuickNavEntry,
+ QuickNavTarget,
+} from "@app/components/shared/quickNav/QuickNavRailBase";
+
+export interface QuickNavRailContainerProps extends Omit<
+ QuickNavRailBaseProps,
+ "footer"
+> {
+ /** The rail owns the account control, so the sidebars drop their own row. */
+ onOpenSettings?: () => void;
+ /** Omitted in builds with no processor to invite anyone into. */
+ onInvite?: () => void;
+ onToggleNotifications?: () => void;
+ notificationsOpen?: boolean;
+ identity?: QuickNavIdentity | null;
+ onReturnHome: () => void;
+}
+
+/** The fixed-width column the rail sits in. */
+export function QuickNavRailContainer({
+ onOpenSettings,
+ onInvite,
+ onToggleNotifications,
+ notificationsOpen,
+ identity = null,
+ onReturnHome,
+ ...railProps
+}: QuickNavRailContainerProps) {
+ const { t } = useTranslation();
+ return (
+