Gurant NPM | npm.io

gurant

Gurant is an OAuth 2.0 provider built with Typescript/NodeJS. It is an authorization framework based on the OAuth 2.0 Specification.

Additionally, it also has a built-in authentication using Firebase. Currently, it is opinionated and will only support Firebase.

Lastly, this project uses Hasura's GrahpQL Engine for handling database queries and mutations. That would also mean that Gurant is database agnostic as long as Hasura supports it.

Environment Variables

CRYPTO_SECRET_KEY=
CRYPTO_INIT_VECTOR=
FIREBASE_PROJECT_ID=
FIREBASE_DATABASE_URL=
FIREBASE_CLIENT_EMAIL=
FIREBASE_PRIVATE_KEY=
HASURA_ADMIN_SECRET=
JWT_PUBLIC_KEY=
JWT_PRIVATE_KEY=

Change the GraphQL Endpoint (https://gurant.hasura.app/v1/graphql) in the codegen.config.js to the GraphQL Endpoint of your Hasura Project.

Endpoints

Resource Owner Endpoints

`GET /user`

Fetches the resource owner's profile details.

Response Payload

property	type	description
`id`	string	the resource owner's identifier
`created_at`	timestamp	timestamp when the resource is created
`updated_at`	timestamp	timestamp when the resource is updated
`display_name`	string	the resource owner's display name
`email`	string	the resource owner's email
`client_live`	object	refer to the table below
`client_test`	object	refer to the table below

Client Object

property	type	description
`id`	string	the client identifier
`created_at`	timestamp	timestamp when the resource is created
`updated_at`	timestamp	timestamp when the resource is updated
`secret`	string	the client secret
`is_live`	boolean	determines whether the credentias is for a live or test enviroment
`redirect_uri`	string	the client's redirect enpoint

`POST /user`

Request Payload

property	type	description
`redirect_uri`	string	the user specified redirect enpoint

Response Payload

property	type	description
`id`	string	the resource owner's identifier
`created_at`	timestamp	timestamp when the resource is created
`updated_at`	timestamp	timestamp when the resource is updated
`display_name`	string	the resource owner's display name
`email`	string	the resource owner's email
`client_live_id`	string	the resource owner's live client identifier
`client_test_id`	string	the resource owner's test client identifier

`PUT /user/clients/:client_id`

Update the specified client's redirect endpoint, requires Firebase token for authorization.

Request Payload

property	type	description
`redirect_uri`	string *	The new redirect enpoint for the client

Response Payload

property	type	description
`id`	string	the updated client's client identifier
`redirect_uri`	string	the new redirect enpoint for the client

OAuth 2.0 Endpoints

`GET /oauth2/authorize`

Retrieve the authrization code after the authorization grant, requires Firebase token authorization.

Request Parameters

property	type	description
`response_type`	string *	value MUST be `code`
`client_id`	string *	the registered client's client identifier
`redirect_url`	string *	value MUST be the same with the client's `redirect_url`
`scope`	string *	the scope of which the authorization is applicable
`state`	string	additional state to be passed, could be user info

Response Parameters

The response is the redirect url injected with the parameters below | property | type | description | | -------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------- | | code | string | the authorization code that'll be exchanged to the access token | | state | string | value MUST be the same with state parameter passed in the request |

`POST /oauth2/token?grant_type=authorization_code`

This endpoint is responsible for generating tokens using the previously generated authorization code. This also requires client authentication (HTTP Basic Auth).

The generated access and refresh tokens comply with the JSON Web Token (JWT) Specification.

Request Parameter

property	type	description
`grant_type`	string *	the type of request in how the access token should be generated, value MUST be `authorization_code`
`code`	string *	the authorization code that'll be exchanged to the access token
`redirect_uri`	string *	the redirect enpoint used in the previous authorization grant
`client_id`	string *	the registered client's client identifier

Response Payload

property	type	description
`access_token`	string	the access token used to access protected resources
`refresh_token`	string	the refresh token used to refresh an access token
`scope`	string	the scope of which access is applicable
`expires_in`	number	the lifetime in seconds of the access token
`token_type`	string	the type of the access token, value is always `bearer`

`POST /oauth2/token?grant_type=refresh_token`

This endpoint is responsible for generating tokens using a refresh_token. This also requires client authentication (HTTP Basic Auth).

Request Parameter

property	type	description
`grant_type`	string *	the type of request in how the access token should be generated, value MUST be `refresh_token`
`refresh_token`	string *	the refresh token used to refresh an access token

Response Payload

property	type	description
`access_token`	string	the access token used to access protected resources
`refresh_token`	string	the refresh token used to refresh an access token
`scope`	string	the scope of which access is applicable
`expires_in`	number	the lifetime in seconds of the access token
`token_type`	string	the type of the access token, value is always `bearer`

`POST /oauth2/revoke`

Revoke an access token, requires client authentication (HTTP Basic Auth). This follows the OAuth 2.0 Token Revocation Specification

Request Parameter

property	type	description
`token`	string *	The token the client wants to revoke
`token_type_hint`	string *	A hint about the type of the token submitted for revocation. For now, the value MUST be `access_token` only

Response Payload

property	type	description
`status`	string	the HTTP status
`statusCode`	number	the HTTP status code

Utility Endpoints

`GET /health`

This endpoint is used for health checks

Response Payload

property	type	description
`status`	string	the HTTP status
`statusCode`	number	the HTTP status code

`GET /generate-crypto-keys`

This endpoint SHOULD NOT be exposed in production as it SHOULD only be used for debugging purposes. Generates a secret_key and an initialization vector.

Response Payload

property	type	description
`secret_key`	string	the raw key used by the algorithm and the initialization vector
`initialization_vector`	string	a cryptographically random 16 byte string

`GET /generate-jwt-keys`

This endpoint SHOULD NOT be exposed in production as it SHOULD only be used for debugging purposes. Generates a public and private signed with the secp256r1 elliptic curve.

Response Payload

property	type	description
`public_key`	string	the public key in a PEM format
`private_key`	string	the private key in a PEM format

`GET /verify-token`

This endpoint SHOULD NOT be exposed in production as it SHOULD only be used for debugging purposes. Verifies and decodes a given JSON Web Token (JWT).