# Kotosoft ID - AI System Documentation This document is written for AI assistants (and developers) that need a fast, practical understanding of this repository. ## What this system is Kotosoft ID is an identity and OAuth service with: - a Go backend (`kotosoft-id-backend`) exposing OAuth and user/profile APIs, - a Next.js frontend (`kotosoft-id-frontend`) handling login/consent UI and token cookies, - PostgreSQL + Redis as dependencies. Main use cases: - OAuth2 Authorization Code + PKCE login flow, - access/refresh token issuance and refresh, - user profile management, - consent management, - role/permission ("positions") administration. ## Repository structure - `kotosoft-id-backend`: Go API service (Gin, pgx, redis, JWT logic) - `kotosoft-id-frontend`: Next.js app (App Router, server actions) - `docker-compose.yml`: production-style compose wiring backend + frontend images - `.drone.yml`: CI/CD pipeline (backend tests, frontend lint, image build/push, deploy) ## Runtime architecture (high-level) 1. Frontend starts OAuth initiation (`/api/auth/initiate`) and creates PKCE verifier/state cookies. 2. Browser is redirected to backend `/oauth/authorize`. 3. Backend creates OAuth session and redirects to frontend `/oauth?session=...`. 4. Frontend login/consent UI calls backend session endpoints (`/oauth/session/*`). 5. Backend returns redirect URL with authorization code. 6. Frontend callback exchanges code at backend `/oauth/token`. 7. Frontend stores access/refresh tokens in cookies and calls protected APIs. 8. On 401, frontend attempts refresh token flow. ## Backend API surface Key groups from router: - OAuth routes (`/oauth`) - `GET /authorize` - `GET /session/:token` - `POST /session/login` - `POST /session/attach` - `POST /session/approve` - `POST /token` - `POST /revoke` - `POST /introspect` - User routes (`/api/v1`) - `POST /auth/register` - `POST /auth/refresh` - `GET /me` - `PATCH /me` - `DELETE /me` - `GET /me/consents` - `DELETE /me/consent/:clientId` - `GET /me/positions` - Admin routes (`/api/v1/admin`) - CRUD for permissions - CRUD for positions - assign/revoke positions to users Security notes: - protected routes require Bearer access token, - scopes are checked in middleware, - admin group additionally requires admin middleware, - register/login are rate-limited. ## Required environment variables ### Backend - `SERVER_ADDR` (default `:8080`) - `FRONTEND_URL` (required) - `POSTGRES_URL` (required) - `POSTGRES_MIGRATION_FILE_PATH` (required) - `REDIS_URL` (required) - `JWT_SECRET` (required) - `JWT_TTL` (default `24h`) - `CLIENT_ID` (required) - `CLIENT_SECRET` (required) - `CLIENT_NAME` (optional, default `Basic Client`) - `CLIENT_REDIRECT_URIS` (comma-separated) - optional: `CLIENT_GRANT_TYPES`, `CLIENT_SCOPES` ### Frontend - `PUBLIC_URL` (used for callback URI generation) - `KOTOSOFT_ID_API_URL` (backend base URL) - `CLIENT_ID` - `CLIENT_SECRET` ## How to run locally (development) Prerequisites: - Go `1.25.x` - Node `20+` - PostgreSQL - Redis ### Backend 1. `cd kotosoft-id-backend` 2. Set required env vars (or create `.env`) 3. Run: - `go mod tidy` - `go run ./cmd` On startup backend: - connects to Postgres/Redis, - runs SQL migrations from `migrations/migrations.sql`, - seeds/upserts OAuth client from env vars. ### Frontend 1. `cd kotosoft-id-frontend` 2. Install deps: `npm install` 3. Set env vars (`PUBLIC_URL`, `KOTOSOFT_ID_API_URL`, `CLIENT_ID`, `CLIENT_SECRET`) 4. Run dev server: `npm run dev` ## How to run in containers The provided `docker-compose.yml` expects prebuilt images: - `localhost:5000/kotosoft_id_backend:latest` - `localhost:5000/kotosoft_id_frontend:latest` Typical deployment flow is in `.drone.yml`: - test backend, - lint frontend, - build and push both images, - deploy with `docker compose up -d`. ## Is it functional? Short answer: **yes, likely functional as a working auth system**, with normal production caveats. Why this is likely: - backend has organized routing/handlers/services/repositories, - OAuth code flow + refresh + revoke + introspect are implemented, - user profile and consent endpoints are implemented, - admin permission/position features are implemented, - CI runs `go test ./...` for backend and `npm run lint` for frontend. Caveats: - no explicit end-to-end test workflow is defined in CI, - local functionality still depends on correct Postgres/Redis/env configuration, - deployment compose relies on external image registry and external `proxy` network. ## Important operational notes for AI agents - Do not assume public API docs exist; use backend router/handlers as source of truth. - Frontend auth relies on server-side environment variables and secure cookie handling. - Many failures are configuration failures (wrong redirect URI, client secret, DB/Redis URLs). - If debugging auth, verify in this order: 1. env vars, 2) OAuth session lifecycle, 3) callback exchange, 4) cookie presence, 5) token refresh. - For permission issues, check both access token scopes and user admin flag. ## Suggested next docs to add If you want this project to be easier for both humans and AIs, add: - a root `README.md` with quick-start commands, - an `.env.example` for backend and frontend, - a simple API reference table with request/response examples, - an end-to-end "happy path" auth walkthrough.