{"id":24441882,"url":"https://github.com/abyanmajid/auth","last_synced_at":"2025-10-06T00:57:10.481Z","repository":{"id":249823618,"uuid":"832660077","full_name":"abyanmajid/auth","owner":"abyanmajid","description":"Lightweight cookie-based JWT identity server","archived":false,"fork":false,"pushed_at":"2024-07-27T07:28:36.000Z","size":3902,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-03-14T02:26:18.898Z","etag":null,"topics":["authentication","authorization","jwt","microservices"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":false,"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/abyanmajid.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}},"created_at":"2024-07-23T13:17:50.000Z","updated_at":"2025-02-11T17:46:50.000Z","dependencies_parsed_at":null,"dependency_job_id":"ce93fc9e-85d6-4584-b34a-376e91a78942","html_url":"https://github.com/abyanmajid/auth","commit_stats":null,"previous_names":["abyan-dev/auth","abyanmajid/auth"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/abyanmajid/auth","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abyanmajid%2Fauth","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abyanmajid%2Fauth/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abyanmajid%2Fauth/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abyanmajid%2Fauth/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/abyanmajid","download_url":"https://codeload.github.com/abyanmajid/auth/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abyanmajid%2Fauth/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259584749,"owners_count":22880194,"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","authorization","jwt","microservices"],"created_at":"2025-01-20T21:42:30.869Z","updated_at":"2025-10-06T00:57:05.451Z","avatar_url":"https://github.com/abyanmajid.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Auth\n\n![Tests](https://github.com/abyan-dev/auth/actions/workflows/ci.yaml/badge.svg) [![codecov](https://codecov.io/gh/abyan-dev/auth/graph/badge.svg?token=S679A5TSW7)](https://codecov.io/gh/abyan-dev/auth) [![Go Report](https://goreportcard.com/badge/abyan-dev/auth)](https://goreportcard.com/report/abyan-dev/auth) [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/YanSystems/compiler/blob/main/LICENSE)\n\nAuthentication and authorization service that exposes a REST API for issuing,  invalidating, and revoking HS256-encrypted JSON Web Tokens (JWT). Tokens are stored in `Httponly`, `Secure`, and `Strictly Samesite` cookies, thereby minimizing XSS and CSRF vulnerabilities. \n\n**Table of Contents:**\n\n- [Features](#features)\n- [Quickstart](#quickstart)\n- [API](#api)\n\n## Features\n\nThe service currently provides the following features:\n\n- Credentials-based registration, login, and logout\n- Account verification through email\n- Forgot password / password reset mechanism\n- Two-factor authentication by emailing shortlived JWT\n\n## Quickstart\n\nTo integrate this service to your application, build a linux executable and use it to create a lightweight docker image on alpine OS:\n\n```\nenv GOOS=linux CGO_ENABLED=0 go build -o auth ./cmd/api \u0026\u0026 make image\n```\n\nThe app is dependent on a postgres instance. Run the following to quickly spin up one: \n\n```\nmake db-up\n```\n\nNow serve the container:\n\n```\ndocker run -p 8080:8080 --name auth auth\n```\n\nYour application can interact with the service at `localhost:8080`. Alternatively, if you are using an orchestrator like Compose or Kubernetes, you can leverage their DNS by using `auth:8080` instead.\n\n## API\n\n### `POST` /api/auth/register\n\nThis endpoint accepts the following request payload:\n\n```json\n{\n  \"name\": \"username\",\n  \"email\": \"user@example.com\",\n  \"password\": \"securePassword@123\",\n  \"confirm_password\": \"securePassword@123\",\n}\n```\n\nIt creates a new user in the database, notably with field `verified = false`. An email will be sent to the address specified containing a JWT-embedded URL that will call the `/api/auth/verify` route to set `verified = true`. \n\nThe verification URL expires 10 minutes after it was created, and there is a scheduled cleanup of unverified users that triggers every 24 hours. \n\n### `POST` /api/auth/verify\n\nThis endpoint sets the `verified` field in created users to `true`. It accepts a `?token=\u003ctoken\u003e` query parameter, which would have been embedded to the URL sent by the `/api/auth/register` endpoint to the user's email address.\n\n### `POST` /api/auth/login\n\nThis endpoint accepts the following request payload:\n\n```json\n{\n  \"email\": \"user@example.com\",\n  \"password\": \"securePassword@123\"\n}\n```\n\nIt checks for an existing record of the user in the database, and issues access and refresh tokens as `Httponly`, `Secure`, `Strictly samesite` cookies. \n\n### `POST` /api/auth/logout **(PROTECTED)**\n\n**PROTECTED RESOURCE:** This endpoint is a protected resource. A middleware expects `access_token` and `refresh_token` cookies with every request. \n\nThis endpoint is responsible for (1) invalidating these tokens by altering their expiration date to be in the past, and (2) revoking these tokens so they can no longer be used for authorization.\n\n### `GET` /api/auth/decode **(PROTECTED)**\n\n**PROTECTED RESOURCE:** This endpoint is a protected resource. A middleware expects `access_token` and `refresh_token` cookies with every request. \n\nThis endpoint simply decodes the access token and returns the claims to be used by the frontend - typically for managing user state.\n\n### `POST` /api/auth/2fa/email/request\n\nThis endpoint sends a verification URL to the user's email address, embedded with a JWT that expires in 10 minutes.\n\n### `POST` /api/auth/2fa/email/verify\n\nThis endpoint expects a `?token=\u003ctoken\u003e` query parameter. If the token is valid, then access and refresh tokens will be issued as `Httponly`, `Secure`, and `Strictly Samesite` cookies.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabyanmajid%2Fauth","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fabyanmajid%2Fauth","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabyanmajid%2Fauth/lists"}