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/tinyauthapp/tinyauth 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 — Mixed signals — read the receipts

• Last commit today
• 8 active contributors
• Distributed ownership (top contributor 44% of recent commits)
• GPL-3.0 licensed
• CI configured
• ⚠ GPL-3.0 is copyleft — check downstream compatibility
• ⚠ No test directory detected

_{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 tinyauthapp/tinyauth repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/tinyauthapp/tinyauth.

What it runs against: a local clone of tinyauthapp/tinyauth — 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 tinyauthapp/tinyauth | Confirms the artifact applies here, not a fork | | 2 | License is still GPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of tinyauthapp/tinyauth. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/tinyauthapp/tinyauth.git
#   cd tinyauth
#
# 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 tinyauthapp/tinyauth and re-run."
  exit 2
fi

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

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

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

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
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/tinyauthapp/tinyauth"
  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).

Tinyauth is a minimal, self-contained authentication and authorization server written in Go that acts as an identity provider and middleware for applications. It supports OAuth, LDAP, and access control policies, and integrates as middleware for reverse proxies like Traefik, Nginx, and Caddy. The core value is being the 'tiniest' auth server—a single binary with no external database dependency required, making it ideal for resource-constrained deployments. Monorepo with clear separation: cmd/tinyauth/ contains CLI entry points (create_user.go, create_oidc_client.go, verify_user.go, healthcheck.go), frontend/ is a separate React/TypeScript app built with Vite. The 348KB Go codebase likely contains core auth logic, handlers, and storage; frontend is TypeScript/React (91KB) with TailwindCSS. Dockerfiles provided for both production (Dockerfile.distroless) and development (Dockerfile.dev).

DevOps engineers and self-hosters who need lightweight authentication for their application stack without the operational overhead of Identity servers like Keycloak. Also appeals to developers building internal tools who want OAuth/OIDC without deploying a heavyweight identity platform.

Actively developed but pre-1.0: README explicitly warns that configuration may change often and advises reading release notes. CI/CD is solid (GitHub Actions workflows for CI, nightly builds, releases, security scanning). The OpenSSF Scorecard and Best Practices badges indicate security-conscious development. This is production-usable but expect breaking changes during 0.x releases.

The project is in organizational migration (from individual owner to tinyauthapp GitHub org) which introduces process change risk. Dependency footprint appears moderate (56 Go dependencies implied by codebase size). No visible public issue count in provided data, but pre-1.0 status means API stability risk. Single repository hosting everything (server + frontend) increases blast radius for breaking changes.

Active CI/CD with nightly builds (nightly.yml), automated dependency updates (dependabot.yml), and security scanning (scorecard.yml). Localization effort underway (crowdin.yml integration). The presence of air.toml (hot-reload tool config) and Dockerfile.dev suggests active development loop. Migration to tinyauthapp org is recent and ongoing.

Clone and install with: git clone https://github.com/tinyauthapp/tinyauth.git && cd tinyauth. For frontend development: cd frontend && npm install (package manager shown is npm/bun based on bun.lock presence). Then npm run dev starts Vite dev server. For backend: make likely builds the Go binary (see Makefile). Use docker-compose.dev.yml for full stack: docker-compose -f docker-compose.dev.yml up.

Daily commands: Frontend dev: cd frontend && npm run dev (Vite dev server, see package.json). Backend dev: Likely make dev or direct go run ./cmd/tinyauth (air.toml configured for hot reload). Full stack demo: docker-compose -f docker-compose.dev.yml up includes Traefik + Whoami + Tinyauth. Production: docker run tinyauthapp/tinyauth:latest after configuring .env (see .env.example).

• cmd/tinyauth/tinyauth.go: Main entry point and HTTP server bootstrap—start here to understand request routing and middleware chain
• cmd/tinyauth/create_user.go: User creation logic—reveals data model and authentication flow design
• cmd/tinyauth/create_oidc_client.go: OIDC client registration—key feature for OAuth server mode
• frontend/package.json: Frontend dependency tree and dev scripts—defines the React build pipeline
• .github/workflows/ci.yml: CI/CD pipeline—shows test execution, build matrix, and quality gates
• Dockerfile.distroless: Production container image—reveals dependencies and runtime requirements for deployment
• .env.example: Configuration documentation—all runtime parameters and secrets needed to run Tinyauth
• docker-compose.dev.yml: Development environment definition—shows integration with Traefik and Whoami for middleware testing

Auth logic changes: cmd/tinyauth/ for CLI commands and handlers. User/OIDC client management: Look at create_user.go, create_oidc_client.go, verify_user.go—likely entry points to core auth service. UI changes: frontend/src/ (not shown but standard React structure). Proxy integration: Search for middleware handler code in main Go codebase. New LDAP/OAuth provider: Add to existing handler chain (likely in main codebase). Configuration: .env.example documents all settings; update Dockerfile/docker-compose.dev.yml for testing.

1. Configuration drift risk: .env.example must be consulted; many settings likely required (OAUTH_CLIENT_ID, LDAP endpoints, etc.). 2. Frontend build step required: npm run build compiles TypeScript and Vite output—don't assume Go binary includes pre-built UI. 3. Database not specified in file list: Core logic for user storage (SQLite? in-memory?) not visible; may require init migrations. 4. Reverse proxy routing critical: Tinyauth works via middleware injection—Traefik/Nginx/Caddy must be configured correctly or auth is bypassed. 5. Node version constraint: Check Dockerfile.dev for node version pinning; Vite may have compatibility requirements.

• OAuth 2.0 Authorization Code Flow — Tinyauth acts as an OIDC provider implementing this flow; understanding redirect URIs, auth codes, and token exchange is essential to debug integration issues
• LDAP (Lightweight Directory Access Protocol) — Tinyauth supports LDAP as an authentication backend; knowing LDAP bind operations, search filters, and DN structure is needed to configure or troubleshoot LDAP auth
• Reverse Proxy Middleware Pattern — Tinyauth integrates with Traefik/Nginx/Caddy via middleware; understanding how these proxies intercept requests and inject headers is critical to the entire auth flow
• OIDC (OpenID Connect) — Tinyauth is an OIDC provider; understanding ID tokens, userinfo endpoints, and client registration is essential for extending or debugging auth flows
• TOTP (Time-based One-Time Password) — Visible in cmd/tinyauth/generate_totp.go; Tinyauth likely supports 2FA via TOTP—understanding HMAC-based generation and time windows is needed for MFA features
• Access Control Lists (ACLs) / Policy-Based Authorization — Tinyauth advertises 'access-controls' as a core feature; understanding how policies are evaluated and enforced at the middleware layer is needed to implement custom authorization rules
• Single Binary Deployment Model — Tinyauth's design principle (no external DB, distroless Docker image); understanding how state is persisted locally (likely embedded SQLite or in-memory) impacts production deployment strategies

• dexidp/dex — Alternative OIDC provider in Go with more features but larger footprint; direct competitor solving the same identity problem
• ory/hydra — Heavyweight OAuth 2.0 & OIDC server by Ory; solves same problem but with database dependency and greater complexity
• traefik/traefik — Reverse proxy that Tinyauth integrates with as authentication middleware—needed to understand the proxy-auth flow
• tinyauthapp/docs — Official Tinyauth documentation repository—referenced in README as separate repo housing guides and API docs
• oauth2-proxy/oauth2-proxy — Lightweight OAuth middleware for proxies; simpler alternative if you only need OAuth without full auth server capabilities

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 frontend component tests for auth forms (login-form.tsx, totp-form.tsx)

The frontend directory has React components for authentication flows (login-form.tsx, totp-form.tsx) but there are no visible test files. A new contributor could add unit tests using React Testing Library to verify form validation, submission, and error handling. This directly improves reliability of critical auth UI components.

• [ ] Create frontend/src/components/auth/tests directory
• [ ] Add login-form.test.tsx covering form submission, field validation, and error states
• [ ] Add totp-form.test.tsx covering TOTP input validation and submission
• [ ] Update package.json with testing dependencies (vitest or jest) if not present
• [ ] Configure test setup in vite.config.ts or create vitest.config.ts

Add internationalization (i18n) translation files for supported languages

The project has i18next configured in package.json and crowdin.yml for translations, but the frontend/src directory structure doesn't show locale/translation files. A contributor could set up the translation file structure and populate initial language files (en, es, fr, etc.) that crowdin references.

• [ ] Create frontend/src/locales directory structure with language folders (en, es, fr, de, etc.)
• [ ] Create translation JSON files (frontend/src/locales/en/common.json, etc.) for common UI strings
• [ ] Update frontend/src/main.tsx or App.tsx to properly initialize i18next with the locales backend
• [ ] Add translations for auth components (login labels, error messages, TOTP instructions)
• [ ] Reference the crowdin.yml configuration to ensure file paths match expected structure

Add API integration tests for CLI commands (create_user.go, create_oidc_client.go, verify_user.go)

The cmd/tinyauth directory contains multiple CLI command files but there's no visible test coverage for these commands. A new contributor could add integration tests that verify these commands correctly interact with the backend API, test error handling, and validate expected outputs.

• [ ] Create cmd/tinyauth/*_test.go files for each command (create_user_test.go, create_oidc_client_test.go, verify_user_test.go)
• [ ] Set up test fixtures and mock authentication for integration tests
• [ ] Add tests for success paths, validation errors, and edge cases for each command
• [ ] Update the Makefile with a test target if not present (e.g., 'make test-cli')
• [ ] Ensure tests are included in .github/workflows/ci.yml test execution

• Add integration tests for LDAP provider: cmd/tinyauth lacks visible test files for verify_user.go LDAP logic. Write TestLDAPAuthentication covering success, invalid credentials, and connection timeout cases.
• Document CLI commands: create_user.go, create_oidc_client.go, verify_user.go have no visible help text or usage docs. Add -h flags and update README with examples like tinyauth create-user --username admin --password secret.
• Add TypeScript type safety to API layer: frontend/ uses axios but likely lacks generated types from OpenAPI/Swagger spec. Create types/api.ts with interfaces for /api/user, /api/login, /api/oidc endpoints based on actual Go handler signatures.

• High · Default Server Binding to 0.0.0.0 — .env.example - TINYAUTH_SERVER_ADDRESS setting. The default configuration in .env.example shows TINYAUTH_SERVER_ADDRESS='0.0.0.0', which exposes the authentication server to all network interfaces. This is dangerous for an auth server as it makes the service accessible from untrusted networks. Fix: Change default to 'localhost' or '127.0.0.1'. Document that binding to 0.0.0.0 requires proper network segmentation and firewall rules. Only expose via reverse proxy in production.
• High · Potential XSS via react-markdown — frontend/package.json - react-markdown dependency and frontend/src/components. The frontend includes 'react-markdown' (^10.1.0) dependency which can be vulnerable to XSS if not properly configured. If user input or untrusted content is rendered with markdown, it could execute malicious scripts without proper sanitization. Fix: Ensure react-markdown is used with sanitization plugins (like remark-gfm with proper configuration). Never render unsanitized user input. Validate and escape all markdown content on both frontend and backend.
• Medium · Axios HTTP Client Without Request Timeout Configuration — frontend/package.json - axios dependency. The project uses axios (^1.15.0) but there is no visible timeout configuration in the package.json or common patterns. Without request timeouts, the application is vulnerable to slowloris and hanging request attacks. Fix: Configure axios with reasonable timeout values for all HTTP requests (e.g., 5-10 seconds). Implement request interceptors to enforce timeouts globally.
• Medium · Missing Security Headers Configuration — Backend configuration (not visible in provided files). No visible configuration for HTTP security headers (CSP, X-Frame-Options, X-Content-Type-Options, HSTS, etc.) in the provided file structure. This leaves the application vulnerable to various attacks including clickjacking, MIME-sniffing, and man-in-the-middle attacks. Fix: Implement comprehensive security headers in the Go backend: Content-Security-Policy, X-Frame-Options: DENY, X-Content-Type-Options: nosniff, Strict-Transport-Security, X-XSS-Protection.
• Medium · Database File Stored in Default Location Without Encryption — .env.example - TINYAUTH_DATABASE_PATH setting. The .env.example shows TINYAUTH_DATABASE_PATH='./tinyauth.db' - a relative path with no encryption at rest. SQLite databases store credentials and user data in plaintext unless encrypted. An attacker with filesystem access can directly read sensitive data. Fix: Use SQLCipher or similar encrypted SQLite variant. Implement database encryption at rest. Ensure proper file permissions (600). Document security best practices for production deployments.
• Medium · Unvalidated Configuration Parameters — .env.example - IP allowlist/blocklist configuration. Multiple configuration parameters in .env.example (TINYAUTH_AUTH_IP_ALLOW, TINYAUTH_AUTH_IP_BLOCK) lack visible validation logic. Misconfigured IP allowlists/blocklists could provide false sense of security or cause legitimate users to be blocked. Fix: Implement strict validation for IP CIDR ranges. Log configuration errors on startup. Provide clear error messages for invalid formats. Consider using a configuration validation library.
• Medium · Dependency Version Pinning Not Strict — frontend/package.json - all dependency version declarations. The package.json uses caret (^) versioning for most dependencies, allowing minor and patch updates automatically. While generally safe, this could introduce unexpected breaking changes or security issues in transitive dependencies without review. Fix: Use exact versions (without ^) for critical security libraries or use lock file verification (bun.lock is present but ensure CI validates exact versions). Implement automated dependency scanning with tools like npm audit or Dependabot.
• Low · Missing CORS Configuration Visibility — Backend configuration (not visible in provided files). No visible CORS configuration in the provided files. An auth server requires careful CORS setup to prevent unauthorized cross-origin requests that could leak sensitive tokens or credentials. Fix: Implement explicit

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.