If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/supertokens/supertokens-core shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Single-maintainer risk — review before adopting

• Last commit 1d ago
• 4 active contributors
• Other licensed
• CI configured
• Tests present
• ⚠ Small team — 4 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 96% of recent commits
• ⚠ Non-standard license (Other) — review terms

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live supertokens/supertokens-core repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/supertokens/supertokens-core.

What it runs against: a local clone of supertokens/supertokens-core — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in supertokens/supertokens-core | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of supertokens/supertokens-core. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/supertokens/supertokens-core.git
#   cd supertokens-core
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of supertokens/supertokens-core and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "supertokens/supertokens-core(\\.git)?\\b" \\
  && ok "origin remote is supertokens/supertokens-core" \\
  || miss "origin remote is not supertokens/supertokens-core (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Other)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Other\"" package.json 2>/dev/null) \\
  && ok "license is Other" \\
  || miss "license drift — was Other at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "build.gradle" \\
  && ok "build.gradle" \\
  || miss "missing critical file: build.gradle"
test -f "cli/src/main/java/io/supertokens/cli/Main.java" \\
  && ok "cli/src/main/java/io/supertokens/cli/Main.java" \\
  || miss "missing critical file: cli/src/main/java/io/supertokens/cli/Main.java"
test -f "cli/src/main/java/io/supertokens/cli/commandHandler/CommandHandler.java" \\
  && ok "cli/src/main/java/io/supertokens/cli/commandHandler/CommandHandler.java" \\
  || miss "missing critical file: cli/src/main/java/io/supertokens/cli/commandHandler/CommandHandler.java"
test -f "downloader/src/main/java/io/supertokens/downloader/Main.java" \\
  && ok "downloader/src/main/java/io/supertokens/downloader/Main.java" \\
  || miss "missing critical file: downloader/src/main/java/io/supertokens/downloader/Main.java"
test -f "coreDriverInterfaceSupported.json" \\
  && ok "coreDriverInterfaceSupported.json" \\
  || miss "missing critical file: coreDriverInterfaceSupported.json"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/supertokens/supertokens-core"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

SuperTokens Core is a self-hosted authentication and session management server (written in Java) that replaces Auth0, Firebase Auth, and AWS Cognito. It provides HTTP APIs for passwordless login, social login, email/phone password authentication, session refreshing, multi-factor authentication, and multi-tenancy, exposing these capabilities to backend SDKs via REST endpoints backed by a pluggable database layer (PostgreSQL, MySQL, MongoDB). Gradle monorepo: core auth logic lives in src/ (inferred from build.gradle), CLI tooling in cli/ subdirectory with its own build.gradle, CI orchestration in .circleci/ (Docker containers for testing, database setup scripts), GitHub Actions workflows for release and testing pipelines, plugin interface versioning system. Deployment via Docker (PostgreSQL, MySQL variants in .circleci/Dockerfile*).

Backend engineers and DevOps teams deploying self-hosted authentication infrastructure; developers building SDKs for Node.js, Go, Python, React.js who need a core auth server to integrate with; enterprises requiring on-premise auth compliance and control over user data.

Actively developed and production-ready. The repo has 8.7MB of Java code, comprehensive CI/CD via GitHub Actions (unit tests, release workflows, Docker builds in .github/workflows/), multiple database adapters, and Docker support. Releases are automated and versioned. The CircleCI config and release helper scripts indicate mature DevOps practices.

Low risk for stability; the codebase is large and established. Risks: Java dependency management via Gradle (build.gradle) needs auditing; the plugin interface versioning system (referenced in .circleci/getPluginInterfaceExactVersions.sh) adds maintenance complexity; database adapter plugins require careful version alignment. Check CHANGELOG.md for breaking changes before upgrading.

Active release cycle visible in .github/workflows/: do-release.yml and do-release-java15.yml automate version bumps and Docker publishing. Stress tests (stress-tests.yml) and container health checks (container-check.yml) are being run. Plugin interface versions are tracked and registered (register-new-plugin-version.py). Recent work includes Java 15 compatibility and multi-database support.

git clone https://github.com/supertokens/supertokens-core.git && cd supertokens-core && ./gradlew build. Then start the core server (consult README.md and .circleci/doTests.sh for environment setup: requires a running PostgreSQL/MySQL instance and config in core/config.yaml). Docker: docker build -f .circleci/Dockerfile -t supertokens .

Daily commands: Development: ./gradlew build && ./gradlew run (inferred from Gradle patterns; check build.gradle for exact task names). Testing: .circleci/doTests.sh orchestrates unit and integration tests against PostgreSQL/MySQL. Docker: .circleci/Dockerfile builds the production image; see .github/helpers/release-docker.sh for publishing.

• build.gradle — Root Gradle build configuration defining dependencies, plugins, and build tasks for the entire multi-module SuperTokens core project.
• cli/src/main/java/io/supertokens/cli/Main.java — Entry point for the CLI tool that handles command parsing and routing for installation, startup, and management of SuperTokens instances.
• cli/src/main/java/io/supertokens/cli/commandHandler/CommandHandler.java — Abstract command handler framework that all CLI commands (start, stop, install, uninstall) inherit from; core abstraction for CLI extensibility.
• downloader/src/main/java/io/supertokens/downloader/Main.java — Entry point for the downloader module responsible for fetching and managing plugin versions and dependencies at runtime.
• coreDriverInterfaceSupported.json — Configuration specifying which core driver interface versions are supported by this build; critical for plugin compatibility.
• config.yaml — Default configuration template for SuperTokens core settings including database, logging, and API server parameters.
• .github/workflows/unit-test.yml — Primary CI/CD workflow automating unit tests, integration tests, and build validation on every PR and commit.

Add a New CLI Command

1. Create a new handler class extending CommandHandler in cli/src/main/java/io/supertokens/cli/commandHandler/yourcommand/ (cli/src/main/java/io/supertokens/cli/commandHandler/CommandHandler.java)
2. Implement handleCommand() method with your command logic and return appropriate exit code (cli/src/main/java/io/supertokens/cli/commandHandler/yourcommand/YourCommandHandler.java)
3. Register the command in Main.java by adding a case in the command routing switch statement (cli/src/main/java/io/supertokens/cli/Main.java)
4. Add CLI option parser in cli/src/main/java/io/supertokens/cli/cliOptionsParsers/ if command accepts arguments (cli/src/main/java/io/supertokens/cli/cliOptionsParsers/CLIOptionsParser.java)

Support a New Plugin Interface Version

1. Update coreDriverInterfaceSupported.json to add the new interface version number to the array (coreDriverInterfaceSupported.json)
2. The downloader will automatically validate plugins against this list when DownloaderRunnable checks versions (downloader/src/main/java/io/supertokens/downloader/DownloaderRunnable.java)
3. Build and test locally with devConfig.yaml to verify compatibility (devConfig.yaml)
4. Update CHANGELOG.md documenting the new supported interface version (CHANGELOG.md)

Add a New Server Configuration Option

1. Add the configuration key and default value to config.yaml template (config.yaml)
2. Update devConfig.yaml with development-appropriate defaults for local testing (devConfig.yaml)
3. Document the new option in README.md with description, type, and default value (README.md)
4. Update CHANGELOG.md to announce the new configuration option (CHANGELOG.md)

Release a New Core Version

1. Update version in build.gradle to new semantic version (build.gradle)
2. Document changes in CHANGELOG.md with features, fixes, and breaking changes (CHANGELOG.md)
3. Push to master; GitHub Actions workflow do-release.yml triggers automatically (.github/workflows/do-release.yml)
4. Release script runs tests, builds JAR/Docker images, and executes register-new-core-version.py (.github/helpers/register-new-core-version.py)

• Java / Gradle — Provides cross-platform JVM execution, strong type safety for CLI tooling, and Gradle's multi-module support for orchestrating CLI, downloader, and core projects.
• YAML configuration — Human-readable, hierarchical configuration format suitable for both server settings (database, logging) and development overrides without code recompilation.
• GitHub Actions + CircleCI — Dual CI/CD ensures comprehensive testing on multiple platforms; GitHub Actions handles releases, Docker builds, and version tagging; CircleCI provides additional test matrix coverage.
• Docker multi-stage builds — Enables lightweight, reproducible container images for different base OS versions (Ubuntu 18, 22) with optimized layer caching and minimal final image size.
• Plugin/driver interface versioning — Decouples core releases from backend SDK changes; coreDriverInterfaceSupported.json enforces compatibility contracts, allowing independent plugin development.

• Embedded installation scripts (install-linux.sh, install-windows.bat) bundled in JAR

  • Why: Simplifies distribution—single JAR contains all bootstrap logic; no external dependency downloads at install time.
  • Consequence: Installation scripts must be maintained in multiple languages (bash, batch); harder to iterate on setup UX without full rebuild.

• Downloader component dynamically fetches plugins at startup

  • Why: Allows runtime version selection and plugin updates without core redeployment; supports heterogeneous environments.
  • Consequence: Startup latency increases with plugin count; network failures during plugin download block server startup; requires reliable artifact repository access.

• CLI commands execute as subprocess (not embedded HTTP

  • Why: undefined
  • Consequence: undefined

1. Plugin interface versions must match between core and adapters (see .circleci/getPluginInterfaceExactVersions.sh)—mismatches cause runtime failures. 2. Database initialization scripts (.circleci/startDb.sh, runMySQL.sh) must complete before tests run; check their exit codes. 3. Config file location and schema (likely core/config.yaml based on deploy patterns) is undocumented in the file list—consult README or GitHub Issues. 4. Java version matters: separate workflows for Java 8 and Java 15 (do-release.yml vs do-release-java15.yml) suggest compatibility constraints. 5. CircleCI and GitHub Actions workflows use different database startup methods; local dev may diverge from CI.

• Session token refresh rotation — SuperTokens Core implements secure session token refresh patterns (access + refresh tokens) to minimize credential exposure; understanding token lifecycle and rotation is essential for using the core APIs correctly.
• Plugin interface versioning (semantic versioning for adapters) — The core uses a plugin system for database adapters with explicit version tracking (.circleci/getPluginInterfaceExactVersions.sh); mismatched versions break runtime, so understanding versioning constraints is critical for operations.
• Multi-tenancy and row-level security (RLS) — SuperTokens Core supports multi-tenant deployments (enterprise SSO mentioned in README); this requires database schemas with tenant isolation, which affects schema design and query patterns.
• JWT (JSON Web Tokens) and claims mapping — Core generates and validates JWTs for session management and delegates claims; understanding JWT structure and claim validation is required for integrating with backend SDKs.
• Container orchestration and health checks — The repo includes multiple Dockerfile variants and health-check workflows (.github/workflows/container-check.yml); deploying Core requires understanding container readiness and liveness probes.
• Database abstraction layers and adapter patterns — Core abstracts PostgreSQL, MySQL, and MongoDB via a plugin system; understanding the adapter interface is necessary to add database support or debug adapter compatibility issues.
• OAuth 2.0 and OpenID Connect (OIDC) — Social login and multi-tenancy features rely on OAuth 2.0 / OIDC flows; understanding grant types and federation is needed to implement or debug auth flows.

• keycloak/keycloak — Open-source auth server with similar feature set (session management, multi-tenancy, MFA) but focused on OpenID Connect standards; direct competitor in self-hosted auth space.
• ory/kratos — Self-hosted identity and user management server; lighter-weight alternative focused on passwordless auth and microservices, shares the same market as SuperTokens.
• supertokens/supertokens-node — Official Node.js backend SDK that consumes SuperTokens Core APIs; primary consumer of this repository's REST endpoints.
• supertokens/supertokens-auth-react — Official React frontend SDK that works with backend SDKs communicating with SuperTokens Core; completes the three-tier architecture shown in README.
• supertokens/supertokens-root — Meta-repository orchestrating all SuperTokens projects (Core, SDKs, plugins); references this repo as a core component in the overall auth platform.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for CLI command handlers

The CLI module (cli/src/main/java/io/supertokens/cli/commandHandler/) has multiple command handlers (install, start, list, hashingCalibrate, help) but there's no visible test directory. Adding comprehensive integration tests would ensure CLI reliability across different operating systems and command scenarios, which is critical since the CLI is a primary user-facing tool.

• [ ] Create cli/src/test/java/io/supertokens/cli/commandHandler/ directory structure
• [ ] Add unit tests for InstallHandler.java covering different OS types (OperatingSystem.java already has multi-OS support)
• [ ] Add integration tests for StartHandler.java validating process startup and configuration
• [ ] Add tests for ListHandler.java to verify output parsing
• [ ] Update cli/build.gradle to include test dependencies (JUnit, Mockito)
• [ ] Document test execution in CONTRIBUTING.md

Add GitHub Actions workflow for dependency vulnerability scanning

The project has multiple package.json files (.github/helpers/package.json) and Java dependencies (build.gradle, cli/build.gradle) but no visible security scanning workflow in .github/workflows/. Adding automated dependency vulnerability checks (via npm audit, Dependabot, or OWASP) is critical for an auth/security-focused project to prevent supply chain attacks.

• [ ] Create .github/workflows/dependency-audit.yml workflow
• [ ] Configure npm audit scanning for .github/helpers/package.json and any other Node.js dependencies
• [ ] Add Gradle dependency check plugin configuration to build.gradle and cli/build.gradle
• [ ] Set workflow to fail on high/critical vulnerabilities
• [ ] Add scheduled daily runs plus on-push triggers for dependency files
• [ ] Document security scanning process in CONTRIBUTING.md

Add missing test coverage for Docker build validation across all Dockerfiles

The project maintains 4 different Dockerfiles (.circleci/Dockerfile, Dockerfile-original, Dockerfile-ubuntu18, Dockerfile-ubuntu22) but the existing container-check.yml workflow appears minimal. Given that Docker distribution is critical (Docker pull stats shown in README), comprehensive validation across all image variants is needed to prevent broken releases.

• [ ] Enhance .github/workflows/container-check.yml to build all 4 Dockerfile variants
• [ ] Add smoke tests that validate: java version, supertokens binary presence, configuration paths
• [ ] Add layer caching validation to ensure optimal image sizes across Ubuntu versions
• [ ] Test multi-architecture builds if applicable (arm64 support for M1 Macs)
• [ ] Add workflow that compares image sizes across the 4 variants with failure thresholds
• [ ] Document Docker build requirements in CONTRIBUTING.md with specific Ubuntu version support matrix

• Add unit tests for the CLI jar (cli/jar/cli.jar exists but no cli/src/test visible in the file list)—create a test suite in cli/src/test/java to cover configuration and database management commands.
• Document the plugin interface versioning system: create a PLUGINS.md guide explaining how .circleci/getPluginInterfaceExactVersions.sh works and how to add a new database adapter, since .github/helpers/register-new-plugin-version.py exists but is undocumented.
• Add missing Dockerfile variants for newer Ubuntu LTS versions: .circleci/Dockerfile-ubuntu18 and Dockerfile-ubuntu22 exist, but no Ubuntu 24.04 variant—create Dockerfile-ubuntu24 and add it to the build matrix in .github/workflows/container-check.yml.

The SuperTokens core repository demonstrates a solid security foundation with comprehensive CI/CD workflows and structured architecture. However, there are notable vulnerabilities in dependency management, particularly the outdated axios package and unpinned external dependencies. The primary security concerns are: (1) vulnerable npm dependencies that require immediate updating, (2) lack of explicit dependency version constraints and lock files, (3) missing automated vulnerability scanning in CI/CD pipelines, and (4) potential credential exposure in shell scripts used for sensitive operations. Addressing the critical axios vulnerability and implementing automated dependency scanning should be immediate priorities.

• High · Outdated axios dependency with known vulnerabilities — .github/helpers/package.json. The package.json specifies axios version ^0.26.1, which is outdated and contains multiple known security vulnerabilities including prototype pollution and data exposure issues. Current versions should be 1.6.0 or higher. Fix: Update axios to the latest stable version (^1.6.0 or higher). Run 'npm audit fix' to identify and resolve all vulnerable dependencies.
• High · External git dependency without version pinning — .github/helpers/package.json. The package.json references 'github-workflow-helpers' from a GitHub repository without a specific commit hash or release tag. This allows for potential supply chain attacks if the repository is compromised or branch changes unexpectedly. Fix: Pin the dependency to a specific commit hash or release tag (e.g., 'github:supertokens/github-workflow-helpers#v1.0.0' or use a commit SHA instead of branch reference).
• Medium · Overly permissive dependency version constraints — .github/helpers/package.json. The use of caret (^) version constraints in package.json allows for automatic updates to minor and patch versions that may introduce breaking changes or security issues without explicit review. Fix: Consider using more restrictive version pinning (e.g., exact versions or tilde ~) for production dependencies, especially for security-critical packages. Regularly audit and update dependencies explicitly.
• Medium · Missing npm audit and dependency scanning in CI/CD — .github/workflows/. While the repository has extensive CI/CD workflows, there is no evident automated npm audit or SBOM (Software Bill of Materials) generation in the visible GitHub Actions workflows for the Node.js helper scripts. Fix: Add npm audit checks to the PR validation workflow (.github/workflows/pr-checks.yml) and implement dependency scanning using GitHub Dependabot or similar tools.
• Medium · Potential credential exposure in shell scripts — .circleci/*.sh, .github/helpers/*.sh. Multiple shell scripts in .circleci and .github/helpers directories are used for sensitive operations (database startup, releases, Docker operations). Without visible secrets management patterns, these may be vulnerable to credential exposure. Fix: Ensure all credentials are managed through GitHub Secrets or environment variables, never hardcoded in scripts. Implement secret scanning with git-secrets or similar tools.
• Low · Missing package-lock.json or yarn.lock — .github/helpers/. No lock file is visible for the .github/helpers Node.js dependencies, which could lead to non-reproducible builds and version inconsistencies across environments. Fix: Commit a package-lock.json (for npm) or yarn.lock (for yarn) file to ensure reproducible dependency installations and enable better vulnerability tracking.
• Low · Docker image update strategy not visible — .circleci/Dockerfile*, .github/helpers/Dockerfile. Multiple Dockerfile variants exist without clear versioning strategy, and base images (if any) are not specified in the provided content. This could lead to inconsistent or vulnerable base images. Fix: Use specific base image versions (e.g., 'ubuntu:22.04' instead of 'ubuntu:latest') and implement regular image scanning with tools like Trivy or Grype in CI/CD.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.