{"id":17781642,"url":"https://github.com/monkeydioude/goauth","last_synced_at":"2026-05-01T13:33:07.724Z","repository":{"id":256957755,"uuid":"854860145","full_name":"monkeydioude/GOAuTh","owner":"monkeydioude","description":"User + JWT Authentification micro-service, both gRPC and JSON API","archived":false,"fork":false,"pushed_at":"2025-03-03T21:47:17.000Z","size":226,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-24T05:13:07.663Z","etag":null,"topics":["authentication","grpc","jwt-auth"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/monkeydioude.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-09-09T22:30:40.000Z","updated_at":"2025-02-23T17:32:04.000Z","dependencies_parsed_at":"2025-02-23T18:26:13.045Z","dependency_job_id":"a6caf774-6b33-4894-b0b3-bba766833336","html_url":"https://github.com/monkeydioude/GOAuTh","commit_stats":null,"previous_names":["monkeydioude/goauth"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/monkeydioude%2FGOAuTh","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/monkeydioude%2FGOAuTh/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/monkeydioude%2FGOAuTh/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/monkeydioude%2FGOAuTh/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/monkeydioude","download_url":"https://codeload.github.com/monkeydioude/GOAuTh/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246706022,"owners_count":20820783,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["authentication","grpc","jwt-auth"],"created_at":"2024-10-27T04:03:51.813Z","updated_at":"2026-05-01T13:33:07.710Z","avatar_url":"https://github.com/monkeydioude.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GOAuTh\n\n[![Go](https://github.com/monkeydioude/GOAuTh/actions/workflows/go.yml/badge.svg)](https://github.com/monkeydioude/GOAuTh/actions/workflows/go.yml)\n\nAuthentication provider web service written in Go. Exposes both a JSON REST API and a gRPC server for user creation, authentication, JWT management, user actions, and realm-based namespacing.\n\n## Table of Contents\n\n- [GOAuTh](#goauth)\n  - [Table of Contents](#table-of-contents)\n  - [Getting Started](#getting-started)\n    - [Prerequisites](#prerequisites)\n    - [Quick Start](#quick-start)\n  - [Configuration](#configuration)\n    - [Required](#required)\n    - [Optional](#optional)\n    - [Defaults](#defaults)\n  - [JSON API](#json-api)\n  - [gRPC API](#grpc-api)\n    - [Auth Service](#auth-service)\n    - [JWT Service](#jwt-service)\n    - [User Service](#user-service)\n    - [UserAction Service](#useraction-service)\n  - [Payloads](#payloads)\n    - [Auth (Signup / Login)](#auth-signup--login)\n    - [Edit User (Password / Login)](#edit-user-password--login)\n    - [JWT (Status / Refresh)](#jwt-status--refresh)\n    - [User Actions](#user-actions)\n  - [Architecture](#architecture)\n    - [Key Design Decisions](#key-design-decisions)\n  - [Docker](#docker)\n    - [Development Database](#development-database)\n    - [Production Image](#production-image)\n  - [Development](#development)\n  - [Testing](#testing)\n  - [Makefile Targets](#makefile-targets)\n  - [Other Binaries](#other-binaries)\n\n## Getting Started\n\n### Prerequisites\n\n- Go 1.25+\n- PostgreSQL (or Docker for a containerized instance)\n\n### Quick Start\n\n```bash\n# Install git hooks (run once)\nmake install\n\n# Start the dev PostgreSQL container and run GOAuTh with hot-reload\nmake dev\n```\n\nGOAuTh will start two servers concurrently:\n\n- **HTTP API** on the configured `API_PORT` (default `:8100`)\n- **gRPC server** on the configured `RPC_PORT` (default `:9100`)\n\nBoth servers shut down gracefully on `SIGINT` / `SIGTERM`.\n\n## Configuration\n\nEnvironment variables can be provided through a `.env` file in GOAuTh's working directory (loaded via [godotenv](https://github.com/joho/godotenv)).\n\n### Required\n\n| Variable    | Description                          | Example                                       |\n|-------------|--------------------------------------|-----------------------------------------------|\n| `DB_PATH`   | PostgreSQL connection string         | `postgres://user:pass@localhost:5432/mydb`    |\n| `DB_SCHEMA` | Database schema name                 | `users` (falls back to `public` if empty)     |\n\n### Optional\n\n| Variable                 | Default   | Description                              |\n|--------------------------|-----------|------------------------------------------|\n| `API_PORT`               | `8100`    | HTTP API listen port                     |\n| `RPC_PORT` / `GRPC_PORT` | `9100`    | gRPC listen port                         |\n| `JWT_SECRET`             | —         | Secret used for JWT HS256 signing        |\n| `PASSWD_SALT`            | —         | Salt used for Argon2 password hashing    |\n| `DB_LOG_LEVEL`           | `error`   | GORM log level (`info`, `warn`, `error`) |\n| `DB_SLOW_QUERY_LOG_MS`   | `20`      | Slow query threshold in milliseconds     |\n\n\u003e **Security note:** `JWT_SECRET` and `PASSWD_SALT` should be provided via system environment variables or a secrets manager in production. The `.env` file is only suitable for development.\n\n### Defaults\n\n- JWT expiration: **24 hours**\n- JWT refresh window: **4 weeks**\n- Argon2 parameters: time=3, memory=32 MiB, threads=4, keyLen=32 (RFC draft defaults)\n- Minimum password length: **4 characters**\n- Login constraint: must be a **valid email address**\n\n## JSON API\n\nAll routes are prefixed with `/identity/v1`.\n\n| Method   | Route                          | Description            |\n|----------|--------------------------------|------------------------|\n| `POST`   | `/identity/v1/auth/signup`     | Create a new user      |\n| `PUT`    | `/identity/v1/auth/login`      | Authenticate a user    |\n| `GET`    | `/identity/v1/jwt/status`      | Check JWT validity     |\n| `PUT`    | `/identity/v1/jwt/refresh`     | Refresh an expired JWT |\n| `PUT`    | `/identity/v1/user/password`   | Change password        |\n| `PUT`    | `/identity/v1/user/login`      | Change login (email)   |\n| `DELETE` | `/identity/v1/user/deactivate` | Soft-delete a user     |\n| `GET`    | `/identity/healthcheck`        | Health check           |\n\nAll requests are tagged with an `X-Request-ID` header (generated if missing). Authenticated endpoints expect an `Authorization` cookie containing `Bearer {JWT}`.\n\n## gRPC API\n\nDefined in [`proto/rpc_v1.proto`](./proto/rpc_v1.proto).\n\n### Auth Service\n\n| RPC                                | Description           |\n|------------------------------------|-----------------------|\n| `Signup(UserRequest) → Response`   | Create a new user     |\n| `Login(UserRequest) → Response`    | Authenticate a user   |\n| `Delete(AuthIdRequest) → Response` | Delete a user by ID   |\n\n### JWT Service\n\n| RPC                        | Description            |\n|----------------------------|------------------------|\n| `Status(Empty) → Response` | Check JWT validity     |\n| `Refresh(Empty) → Response`| Refresh an expired JWT |\n\n### User Service\n\n| RPC                                   | Description           |\n|---------------------------------------|-----------------------|\n| `Deactivate(Empty) → Response`        | Soft-delete a user    |\n| `EditUser(EditUserRequest) → Response`| Change login/password |\n\n### UserAction Service\n\n| RPC                                                   | Description                  |\n|-------------------------------------------------------|------------------------------|\n| `Create(UserActionRequest) → Response`                | Create a user action         |\n| `Validate(UserActionValidation) → Response`           | Validate a user action       |\n| `Status(UserActionRequest) → UserActionStatusResponse` | Get user action status      |\n\nJWT is passed via a `set-cookie` gRPC metadata entry containing `Authorization=Bearer {JWT}`.\n\n## Payloads\n\n### Auth (Signup / Login)\n\n**JSON:**\n\n```json\n{\n  \"login\": \"user@example.com\",\n  \"password\": \"s3cure!\",\n  \"realm_name\": \"my-realm\"\n}\n```\n\n**Protobuf:**\n\n```protobuf\nmessage UserRequest {\n    string login = 1;\n    string password = 2;\n    string realm = 3;\n}\n```\n\n### Edit User (Password / Login)\n\n**JSON (password change):**\n\n```json\n{\n  \"password\": \"current-password\",\n  \"new_password\": \"new-s3cure!\"\n}\n```\n\n**JSON (login change):**\n\n```json\n{\n  \"password\": \"current-password\",\n  \"login\": \"old@example.com\",\n  \"new_login\": \"new@example.com\"\n}\n```\n\n**Protobuf:**\n\n```protobuf\nmessage EditUserRequest {\n    string new_login = 1;\n    string new_password = 2;\n    string password = 3;\n}\n```\n\n### JWT (Status / Refresh)\n\nNo JSON body. Requires an `Authorization` cookie (HTTP) or `set-cookie` metadata (gRPC) containing `Bearer {JWT}`.\n\n### User Actions\n\n```protobuf\nmessage UserActionRequest {\n    string login = 1;\n    string realm = 2;\n    string action = 3;\n    string data = 4;\n}\n\nmessage UserActionValidation {\n    string realm = 1;\n    string data = 2;\n    string against = 3;\n}\n```\n\n## Architecture\n\n```\nbin/GOAuTh/          → Main binary (HTTP + gRPC servers)\ninternal/\n  api/handlers/      → HTTP route handlers (auth, jwt, user)\n  config/boot/       → Bootstrap (DB, JWT factory, user params)\n  config/consts/     → Environment variable names, defaults, error codes\n  config/middleware/  → Request logging, X-Request-ID (HTTP \u0026 gRPC)\n  domain/entities/   → GORM models (User, Realm, UserAction), constraints\n  domain/models/     → UsersParams (salt, Argon2 config, constraints)\n  domain/services/   → Business logic (auth, jwt, user, user actions)\npkg/\n  crypt/             → Argon2 hashing, JWT encode/decode (HS256)\n  data_types/        → Utility types (ptr, slice, tuple)\n  domain/entities/   → Generic interfaces (User, JWT)\n  errors/            → Error type with HTTP status mapping\n  grpc/v1/           → gRPC server implementations + generated code\n  http/              → Middleware, JSON request/response, RPC cookie helpers\n  plugins/           → Event-based plugin system (before/after hooks)\nplugins/             → Loadable plugin files (e.g. heyo broker integration)\nproto/               → Protocol Buffer definitions\n```\n\n### Key Design Decisions\n\n- **DDD-ish / Clean Architecture**: domain entities and services are separated from transport (HTTP/gRPC) handlers.\n- **Realm-based namespacing**: users belong to realms, allowing multi-tenant setups.\n- **Dual transport**: the same service layer is exposed over both HTTP and gRPC.\n- **Plugin system**: event hooks (`OnUserCreation`, etc.) with configurable timeouts for extensibility.\n- **Graceful shutdown**: `oklog/run` coordinates concurrent servers and OS signal handling.\n\n## Docker\n\n### Development Database\n\n```bash\ndocker compose up -d   # Starts PostgreSQL (dev/dev/dev_db) on port 5432\n```\n\n### Production Image\n\n```bash\ndocker build -t drannoc/goauth .\n```\n\nThe multi-stage Dockerfile builds `GOAuTh` and the `client` binary, then runs via an entrypoint script that:\n1. Waits for PostgreSQL readiness\n2. Writes a `.env` file from container environment variables\n3. Starts GOAuTh (or a custom command)\n\n## Development\n\n```bash\n# Start containers + hot-reload server (uses gow)\nmake dev\n\n# Regenerate protobuf code (Go + Rust)\nmake proto\n\n# Access the dev database via psql\nmake dpsql\n```\n\n## Testing\n\n```bash\n# Unit tests only (internal, pkg, plugins)\nmake unit-test\n\n# Full test suite (spins up a test DB container, runs all tests)\nmake test\n\n# Manually manage the test database container\nmake run-test-db\nmake stop-test-db\n```\n\n## Makefile Targets\n\n| Target          | Description                                           |\n|-----------------|-------------------------------------------------------|\n| `help`          | Show available targets                                |\n| `install`       | Install git pre-commit hook                           |\n| `all_up`        | Start all Docker Compose services                     |\n| `db_layout`     | Start DB container + import initial SQL               |\n| `dev`           | Start Docker + hot-reload GOAuTh with `gow`           |\n| `unit-test`     | Run unit tests                                        |\n| `test`          | Run full test suite (with ephemeral test DB)          |\n| `run-test-db`   | Start a standalone test PostgreSQL container          |\n| `stop-test-db`  | Stop the standalone test PostgreSQL container         |\n| `proto-go`      | Regenerate Go protobuf/gRPC code                      |\n| `proto-rust`    | Build Rust protobuf client                            |\n| `proto`         | Regenerate both Go and Rust protobuf code             |\n| `docker-build`  | Build and push the Docker image                       |\n| `dpsql`         | Open a psql shell to the dev database                 |\n\n## Other Binaries\n\nAdditional utility binaries live in `bin/`. Each has its own README:\n\n- [`bin/client/`](./bin/client/) — CLI client for interacting with GOAuTh via API or gRPC\n- [`bin/min-grpc-server/`](./bin/min-grpc-server/) — Minimal gRPC-only server (no HTTP)\n- [`bin/spy-token/`](./bin/spy-token/) — JWT token generator for development/debugging\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmonkeydioude%2Fgoauth","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmonkeydioude%2Fgoauth","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmonkeydioude%2Fgoauth/lists"}