{"id":43518946,"url":"https://github.com/ryo-arima/locky","last_synced_at":"2026-02-03T14:09:31.330Z","repository":{"id":321956519,"uuid":"1087720774","full_name":"ryo-arima/locky","owner":"ryo-arima","description":"A robust Role-Based Access Control (RBAC) service built with Go, providing comprehensive user, group, member, and role management with fine-grained permissions.","archived":false,"fork":false,"pushed_at":"2025-12-06T16:19:11.000Z","size":53774,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-10T08:22:45.741Z","etag":null,"topics":["authorization","go","golang","jwt"],"latest_commit_sha":null,"homepage":"https://ryo-arima.github.io/locky/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ryo-arima.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-01T14:02:05.000Z","updated_at":"2025-12-06T16:19:15.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ryo-arima/locky","commit_stats":null,"previous_names":["ryo-arima/locky"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/ryo-arima/locky","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ryo-arima%2Flocky","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ryo-arima%2Flocky/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ryo-arima%2Flocky/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ryo-arima%2Flocky/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ryo-arima","download_url":"https://codeload.github.com/ryo-arima/locky/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ryo-arima%2Flocky/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29047376,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-03T10:09:22.136Z","status":"ssl_error","status_checked_at":"2026-02-03T10:09:16.814Z","response_time":96,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["authorization","go","golang","jwt"],"created_at":"2026-02-03T14:09:30.710Z","updated_at":"2026-02-03T14:09:31.312Z","avatar_url":"https://github.com/ryo-arima.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Locky\n\nA robust Role-Based Access Control (RBAC) service built with Go, providing comprehensive user, group, member, and role management with fine-grained permissions.\n\n[![Go Version](https://img.shields.io/badge/Go-1.25.5+-00ADD8?style=flat\u0026logo=go)](https://golang.org)\n[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![E2E Tests](https://github.com/ryo-arima/locky/actions/workflows/e2e-test.yml/badge.svg)](https://github.com/ryo-arima/locky/actions/workflows/e2e-test.yml)\n[![Documentation](https://img.shields.io/badge/docs-GitHub%20Pages-success)](https://ryo-arima.github.io/locky/)\n\n## Features\n\n- 🔐 **JWT Authentication**: Secure token-based authentication with HS256\n- 🛡️ **Casbin RBAC**: Flexible policy-based authorization\n- 👥 **User Management**: Complete CRUD operations for user accounts\n- 📦 **Group Management**: Organize users into logical groups\n- 👤 **Member Management**: Control group membership and relationships\n- 🎭 **Role Management**: Define and assign fine-grained permissions\n- ⚡ **Redis Caching**: High-performance caching with token denylist\n- 🗄️ **MySQL/TiDB**: Reliable persistent data storage\n- 🌐 **Multi-tier API**: Public, Internal, and Private endpoints\n- 📱 **CLI Clients**: Admin, App, and Anonymous command-line interfaces\n\n## Quick Start\n\n### Prerequisites\n\n- Go 1.25.5 or higher\n- MySQL 8.0+ or TiDB\n- Redis 6.0+\n- Docker \u0026 Docker Compose (optional)\n\n### Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/ryo-arima/locky.git\ncd locky\n\n# Start dependencies with Docker Compose\ndocker compose up -d\n\n# Copy configuration\ncp etc/app.dev.yaml etc/app.yaml\n\n# Build the server\ngo build -o .bin/locky-server ./cmd/server/main.go\n\n# Start the server\n./.bin/locky-server\n```\n\nThe server will start on `http://localhost:8080`.\n\n### Quick Test\n\n```bash\n# Register a user\ncurl -X POST http://localhost:8080/v1/public/user \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\":\"Test User\",\"email\":\"test@example.com\",\"password\":\"password123\"}'\n\n# Login\ncurl -X POST http://localhost:8080/v1/public/token \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"email\":\"test@example.com\",\"password\":\"password123\"}'\n\n# Use the JWT token from the response for authenticated requests\n```\n\n## Architecture\n\nLocky follows a clean, layered architecture:\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│                       Client Layer                          │\n│              (Admin CLI, App CLI, Anonymous CLI)            │\n└─────────────────────────────────────────────────────────────┘\n                              ↓\n┌─────────────────────────────────────────────────────────────┐\n│                        API Layer                            │\n│        (Gin Router, JWT Auth, Casbin RBAC, Logger)         │\n└─────────────────────────────────────────────────────────────┘\n                              ↓\n┌─────────────────────────────────────────────────────────────┐\n│                    Controller Layer                         │\n│          (Public, Internal, Private Controllers)            │\n└─────────────────────────────────────────────────────────────┘\n                              ↓\n┌─────────────────────────────────────────────────────────────┐\n│                 Business Logic Layer                        │\n│              (User, Group, Member, Role Usecases)           │\n└─────────────────────────────────────────────────────────────┘\n                              ↓\n┌─────────────────────────────────────────────────────────────┐\n│                   Repository Layer                          │\n│         (User, Group, Member, Role Repositories)            │\n└─────────────────────────────────────────────────────────────┘\n                              ↓\n┌─────────────────────────────────────────────────────────────┐\n│                      Data Layer                             │\n│              (MySQL/TiDB, Redis, Casbin Policies)           │\n└─────────────────────────────────────────────────────────────┘\n```\n\n[View detailed architecture diagram →](https://ryo-arima.github.io/locky/architecture/high-level.html)\n\n## Documentation\n\nComprehensive documentation is available at **[https://ryo-arima.github.io/locky/](https://ryo-arima.github.io/locky/)**\n\n- **[Getting Started](https://ryo-arima.github.io/locky/development/getting-started.html)** - Installation and setup\n- **[Architecture](https://ryo-arima.github.io/locky/architecture/high-level.html)** - System design and components\n- **[API Reference](https://ryo-arima.github.io/locky/api/overview.html)** - REST API documentation\n- **[Configuration](https://ryo-arima.github.io/locky/configuration/guide.html)** - Configuration guide\n- **[Swagger UI](https://ryo-arima.github.io/locky/swagger/index.html)** - Interactive API documentation\n- **[GoDoc](https://ryo-arima.github.io/locky/godoc/index.html)** - Go package documentation\n\n## API Endpoints\n\n### Public Endpoints (No Authentication Required)\n\n- `POST /v1/public/user` - Register a new user\n- `POST /v1/public/token` - Authenticate and get JWT token\n- `GET /health` - Health check\n\n### Share Endpoints (JWT Required)\n\n- `POST /v1/share/token/refresh` - Refresh JWT token\n- `DELETE /v1/share/token` - Logout and invalidate token\n- `GET /v1/share/token/validate` - Validate JWT token\n- `GET /v1/share/token/user` - Get user info from token\n\n### Internal Endpoints (JWT + Casbin Authorization Required)\n\n- `GET /v1/internal/users` - List users\n- `GET /v1/internal/groups` - List groups\n- `GET /v1/internal/members` - List members\n- `GET /v1/internal/roles` - List roles\n- `GET /v1/internal/resources` - List resources\n\n### Private Endpoints (JWT Required, No Casbin)\n\n- `PUT /v1/private/user/{id}` - Update user\n- `DELETE /v1/private/user/{id}` - Delete user\n- `POST /v1/private/group` - Create group\n- `POST /v1/private/role` - Create role\n- `POST /v1/private/resource` - Create resource\n\n[Full API documentation →](https://ryo-arima.github.io/locky/swagger/index.html)\n\n## Configuration\n\nCreate `etc/app.yaml` from the template:\n\n```bash\ncp etc/app.yaml.example etc/app.yaml\n```\n\nEdit the configuration with your settings:\n\n```yaml\nServer:\n  host: \"0.0.0.0\"\n  port: 8080\n  jwt_secret: \"your-secure-secret-256-bits\"\n  Redis:\n    JWTCache: true      # Enable JWT token caching\n    CacheTTL: 3600      # Cache TTL in seconds\n\nMySQL:\n  host: \"localhost\"\n  user: \"locky\"\n  pass: \"password\"\n  db: \"locky\"\n\nRedis:\n  host: \"localhost\"\n  port: 6379\n  db: 0\n\nCasbin:\n  app_model: \"etc/casbin/locky/model.conf\"\n  app_policy: \"etc/casbin/locky/policy.csv\"\n```\n\n[Configuration guide →](https://ryo-arima.github.io/locky/configuration/guide.html)\n\n## Development\n\n### Building\n\n```bash\n# Build all binaries\nmake build\n\n# Or build individually\ngo build -o .bin/locky-server ./cmd/server/main.go\ngo build -o .bin/locky-client-admin ./cmd/client/admin/main.go\ngo build -o .bin/locky-client-app ./cmd/client/app/main.go\ngo build -o .bin/locky-client-anonymous ./cmd/client/anonymous/main.go\n```\n\n### Testing\n\n#### Unit Tests\n\n```bash\n# Run tests\nmake test\n\n# Run with coverage\ngo test -v -cover ./...\n```\n\n#### E2E Tests\n\nE2E tests verify the entire system including server, database, Redis, and CLI clients.\n\n**Prerequisites:**\n- Docker \u0026 Docker Compose\n- Go 1.25.5+\n\n**Platform Configuration:**\n\nFor Apple Silicon (M1/M2/M3) Macs:\n```bash\n# Create .env.local (ignored by git)\necho \"DOCKER_PLATFORM=linux/arm64\" \u003e .env.local\n```\n\nFor Intel Macs and Linux x86_64:\n```bash\n# Create .env.local (ignored by git)\necho \"DOCKER_PLATFORM=linux/amd64\" \u003e .env.local\n```\n\n**Run E2E Tests:**\n\n```bash\n# 1. Start dependencies (MySQL and Redis)\ndocker compose up -d mysql redis\n\n# 2. Wait for services to be ready (about 10 seconds)\nsleep 10\n\n# 3. Build CLI binaries\nmkdir -p bin\ngo build -o bin/locky-admin ./cmd/client/admin\ngo build -o bin/locky-app ./cmd/client/app\ngo build -o bin/locky-anonymous ./cmd/client/anonymous\n\n# 4. Run E2E tests\ngo test -v -timeout 15m ./test/e2e/testcase/\n\n# 5. Cleanup\ndocker compose down -v\n```\n\n**Test Coverage:**\n- ✅ Anonymous User Registration\n- ⏭️ Authentication Flow (Login, Token validation, Refresh, Logout) - Endpoints need implementation\n- ⏭️ App User Group CRUD - Requires authentication implementation\n- ⏭️ User/Role Read Operations - Requires authentication implementation\n- ⏭️ Admin operations - Requires admin role assignment\n\n**Note:** Most E2E tests are currently skipped pending full authentication and authorization implementation.\n\n**GitHub Actions:**\nE2E tests run automatically on pull requests and pushes to `dev` branch using `linux/amd64` platform.\n\n## Ephemeral Mail/Test Environment (Experimental)\n\nAn internal mail sandbox (Postfix/Dovecot via docker-mailserver + dnsmasq + Roundcube) can be fully recreated for browser‑based tests. All data is ephemeral.\n\n```bash\n# Full teardown \u0026 rebuild (containers, network, volumes) + account provisioning\n./scripts/main.sh env recreate\n\n# Access Roundcube (webmail)\nopen http://localhost:3005  # or manually open in browser\n\n# Example login\n#   user: test1@locky.local\n#   pass: TestPassword123!\n```\n\nSend a test message from test1 to test2 and verify it appears in test2's inbox after switching accounts. Logs:\n\n```bash\n# Postfix / Dovecot logs (mailserver container)\ndocker compose logs -f mailserver\n```\n\nTo iterate after config changes always use force recreate:\n\n```bash\ndocker compose up -d --force-recreate mailserver roundcube\n```\n\nIf authentication fails, rerun the full recreate script to ensure accounts are re-applied cleanly.\n\n### Documentation\n\n```bash\n# Build documentation\n./scripts/main.sh docs build\n\n# Serve documentation locally\ncd docs/dist \u0026\u0026 python3 -m http.server 8000\n```\n\n### Publishing to pkg.go.dev\n\nTo make your package available on pkg.go.dev, you have two options:\n\n#### Option 1: GitHub Actions (Recommended)\n\n**Manual trigger:**\n1. Go to **Actions** tab in GitHub\n2. Select \"Create Release Tag\" workflow\n3. Click \"Run workflow\"\n4. Enter version (e.g., `v0.1.0`)\n5. Add release notes (optional)\n6. Click \"Run workflow\"\n\n**Automatic trigger:**\n1. Update the `VERSION` file with new version (e.g., `0.2.0`)\n2. Commit and push to main branch\n3. GitHub Actions will automatically create the tag\n\n#### Option 2: Manual Script\n\n```bash\n# Publish with default version (v0.1.0)\n./scripts/publish-to-pkggodev.sh\n\n# Or specify a version\n./scripts/publish-to-pkggodev.sh v0.2.0\n```\n\nAfter publishing (either method), your package will be available at:\n- https://pkg.go.dev/github.com/ryo-arima/locky\n- https://pkg.go.dev/github.com/ryo-arima/locky/pkg/server\n- https://pkg.go.dev/github.com/ryo-arima/locky/pkg/client\n\n**Note:** It may take 5-10 minutes for pkg.go.dev to index the package after tag creation.\n\n## CLI Clients\n\n### Admin Client\n\nAdministrative operations with elevated privileges:\n\n```bash\n./.bin/locky-client-admin --help\n```\n\n### App Client\n\nApplication-level operations for authenticated users:\n\n```bash\n./.bin/locky-client-app --help\n```\n\n### Anonymous Client\n\nPublic operations without authentication:\n\n```bash\n./.bin/locky-client-anonymous --help\n```\n\n## Project Structure\n\n```\nlocky/\n├── cmd/                    # Command-line applications\n│   ├── server/            # HTTP server\n│   └── client/            # CLI clients (admin, app, anonymous)\n├── pkg/                   # Shared packages\n│   ├── server/           # Server implementation\n│   │   ├── controller/   # HTTP handlers\n│   │   ├── middleware/   # Middleware components\n│   │   └── repository/   # Data access layer\n│   ├── client/           # Client implementation\n│   ├── config/           # Configuration management\n│   └── entity/           # Data models and DTOs\n├── etc/                   # Configuration files\n│   ├── casbin/           # Casbin policy files\n│   └── app.yaml.example  # Configuration template\n├── docs/                  # Documentation\n│   ├── books/            # mdBook source\n│   ├── dist/             # Built documentation (GitHub Pages)\n│   ├── architecture/     # Architecture diagrams\n│   └── swagger/          # OpenAPI specification\n├── scripts/              # Build and utility scripts\n└── test/                 # Test files\n```\n\n## Technology Stack\n\n- **Language**: Go 1.25.5+\n- **Web Framework**: [Gin](https://github.com/gin-gonic/gin)\n- **ORM**: [GORM](https://gorm.io/)\n- **Authentication**: JWT with [golang-jwt](https://github.com/golang-jwt/jwt)\n- **Authorization**: [Casbin](https://casbin.org/) (Group-based RBAC)\n- **Database**: MySQL 8.0+ / TiDB\n- **Cache**: Redis 6.0+ (JWT token caching, session management)\n- **Documentation**: mdBook, Swagger/OpenAPI\n\n## Contributing\n\nContributions are welcome! Please read our [Contributing Guide](https://ryo-arima.github.io/locky/development/contributing.html) for details.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add some amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Testing\n\n### E2E Tests\n\nEnd-to-end tests are located in `test/e2e/testcase/` and test the complete application stack.\n\n#### Running E2E Tests\n\n**1. Start required services (MySQL and Redis only):**\n```bash\n# For ARM64 (Mac M1/M2/M3, etc.)\ndocker compose up -d mysql redis\n\n# For AMD64 (GitHub Actions, x86_64 Linux, etc.)\nDOCKER_PLATFORM=linux/amd64 docker compose up -d mysql redis\n```\n\n**2. Build CLI binaries:**\n```bash\nmake build\n```\n\n**3. Run E2E tests:**\n```bash\n# Run all E2E tests\ngo test -v ./test/e2e/testcase/\n\n# Run specific test\ngo test -v ./test/e2e/testcase/ -run TestAuthenticationFlow\n```\n\n**4. Stop services:**\n```bash\ndocker compose down\n```\n\n#### Test Coverage\n\nCurrently implemented E2E tests:\n- ✅ **TestMain** - Test environment initialization\n- ⏭️ All other tests - Pending authentication and authorization implementation\n\n**Note:** E2E test implementation is in progress. Most test cases are currently disabled pending full system integration.\n\n#### CI/CD\n\nE2E tests run automatically on GitHub Actions for every pull request and push to main branch. See [`.github/workflows/e2e-test.yml`](.github/workflows/e2e-test.yml) for details.\n\n## Links\n\n- **Documentation**: https://ryo-arima.github.io/locky/\n- **API Documentation**: https://ryo-arima.github.io/locky/swagger/index.html\n- **GoDoc**: https://ryo-arima.github.io/locky/godoc/index.html (or [pkg.go.dev](https://pkg.go.dev/github.com/ryo-arima/locky) when published)\n- **Issue Tracker**: https://github.com/ryo-arima/locky/issues\n- **Discussions**: https://github.com/ryo-arima/locky/discussions\n\n## Support\n\n- 📖 [Documentation](https://ryo-arima.github.io/locky/)\n- 💬 [GitHub Discussions](https://github.com/ryo-arima/locky/discussions)\n- 🐛 [Issue Tracker](https://github.com/ryo-arima/locky/issues)\n\n---\n\nMade with ❤️ by [Ryo ARIMA](https://github.com/ryo-arima)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fryo-arima%2Flocky","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fryo-arima%2Flocky","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fryo-arima%2Flocky/lists"}