ID Service

Allows users to sign up, login and manage Hedia accounts or apps.

flowchart TB
	DATA_SERVICE(Data Service)
	DEVELOPER_SERVICE(Developer Service)
	EVENT_SERVICE(Event Service)
	EXPORT_SERVICE(Export Service)
	HEDIA_SERVER(Hedia Server)
	ID_SERVICE(ID Service)
	MAIL_SERVICE(Mail Service)
	OAUTH2_SERVICE(OAuth2 Service)
	WEBHOOK_SERVICE(Webhook Service)

	DATA_SERVICE-->ID_SERVICE
	DEVELOPER_SERVICE-->ID_SERVICE
	EVENT_SERVICE-->ID_SERVICE
	EXPORT_SERVICE-. TBD .->ID_SERVICE
	WEBHOOK_SERVICE-->ID_SERVICE
	ID_SERVICE-->HEDIA_SERVER
	ID_SERVICE<-->OAUTH2_SERVICE
	ID_SERVICE-->MAIL_SERVICE

Features

The Id Service comes with an app, an API and an admin app.

The app (/) allows users to sign up, login, reset their password and update their account settings.

The API (/api/v1) can check the validity of a session and share some user profile with other services. It also provides endpoints to manage an app and its collaborators, installations, keys, links or permissions.

The admin app (/admin) offers a way to lookup a user and upgrade or revoke their access to the platform. It is also the place where app permissions are managed at a system level.

Permissions

App Flow

---
title: Can the current app perform an action on behalf of a given user for a given scope?
---
stateDiagram
	System: Was the current app granted a system permission to do so?
	User: Was the current app granted permission by the given user to do so?
	Action: Which action should be performed?
	Source: Which app wrote the data?
	App: Was the current app granted permission by the other app to do so?

	state ifSystem <<choice>>
	state ifUser <<choice>>
	state ifAction <<choice>>
	state ifSource <<choice>>
	state ifApp <<choice>>

	classDef Error fill:red,stroke:red
	classDef Success fill:green,stroke:green
	class Forbidden Error
	class Allowed Success

	[*] --> System
	System --> ifSystem
	ifSystem --> Forbidden: No
	ifSystem --> User: Yes
	User --> ifUser
	ifUser --> Forbidden: No
	ifUser --> Action: Yes
	Action --> ifAction
	ifAction --> Source: Read
	ifAction --> Allowed: Write
	Source --> ifSource
	ifSource --> App: Another App
	ifSource --> Allowed: Current App
	App --> ifApp
	ifApp --> Forbidden: No
	ifApp --> Allowed: Yes

User Flow

---
title: Can the current user perform an action on behalf of a given user for a given scope?
---
stateDiagram
	Actor: Are the current user and the given user the same user?
	Redirect: Follow the app flow replacing "current app" by "current user"
	note right of Redirect: The system prevents you from doing so at the moment

	state ifActor <<choice>>

	classDef Pending stroke:yellow
	classDef Success fill:green,stroke:green
	class Redirect Pending
	class Allowed Success

	[*] --> Actor
	Actor --> ifActor
	ifActor --> Redirect: No
	ifActor --> Allowed: Yes

Data Model

erDiagram
	App ||--o{ Collaborator : has
	App ||--o{ Installation : has
	App ||--o{ Link : creates
	App ||--|| Owner : has
	App ||--|| Owner : is
	Email ||--o{ EmailVerification : has
	EmailVerification ||--o{ EmailVerificationAttempt : has
	Login ||--|| Email : uses
	Login ||--|| Password : uses
	Login ||--|| Phone : uses
	Owner ||--o{ Key : has
	Owner ||--o{ Permission : grants
	Owner ||--o{ Permission : requests
	PasswordReset ||--o{ PasswordResetAttempt : has
	Phone ||--o{ PhoneVerification : has
	PhoneVerification ||--o{ PhoneVerificationAttempt : has
	Session ||--o{ CSRF : allows
	User ||--o{ Collaborator : is
	User ||--o{ Email : has
	User ||--o{ Installation : uses
	User ||--o{ Link : uses
	User ||--o{ Login : uses
	User ||--|| Owner : is
	User ||--o{ PasswordReset : uses
	User ||--|| Password : has
	User ||--o{ Phone : has
	User ||--o{ Session : has
	User ||--|| Signup : uses

	App {
		UUID id PK
		string name
		string title
		string description
		string url
		UUID ownerId FK
		boolean firstParty
		Date createdAt
		UUID createdBy
		Date updatedAt
		UUID updatedBy
		Date deletedAt
		UUID deletedBy
	}

	Collaborator {
		UUID id PK
		UUID appId FK
		UUID userId FK
		Date createdAt
		UUID createdBy
		Date deletedAt
		UUID deletedBy
	}

	CSRF {
		UUID id PK
		UUID sessionId FK
		Date expiresAt
	}

	Email {
		UUID id PK
		UUID userId FK
		string value
		boolean verified
		Date createdAt
		UUID createdBy
		Date updatedAt
		UUID updatedBy
		Date deletedAt
		UUID deletedBy
	}

	EmailVerification {
		UUID id PK
		UUID emailId FK
		string status
		string code
		Date expiresAt
		Date createdAt
		UUID createdBy
		Date updatedAt
		UUID updatedBy
	}

	EmailVerificationAttempt {
		UUID id PK
		UUID emailVerificationId FK
		string status
		string code
		Date createdAt
		UUID createdBy
	}

	Installation {
		UUID id PK
		UUID appId FK
		UUID userId FK
		Date createdAt
		UUID createdBy
		Date deletedAt
		UUID deletedBy
	}

	Key {
		UUID id PK
		string key
		UUID ownerId FK
		Date createdAt
		UUID createdBy
		Date deletedAt
		UUID deletedBy
	}

	Link {
		UUID id PK
		UUID sourceId FK
		UUID targetId FK
		UUID userId FK
		URL callbackUrl
		string codeChallenge
		Date expiresAt
		Date createdAt
		UUID createdBy
		Date deletedAt
		UUID deletedBy
	}

	Login {
		UUID id PK
		UUID userId FK
		UUID emailId FK
		UUID phoneId FK
		UUID passwordId FK
		string status
		Date createdAt
	}

	Owner {
		UUID id PK
	}

	PasswordReset {
		UUID id PK
		UUID userId FK
		string emailOrPhone
		string status
		string code
		Date expiresAt
		Date createdAt
		UUID createdBy
		Date updatedAt
		UUID updatedBy
	}

	PasswordResetAttempt {
		UUID id PK
		UUID passwordResetId FK
		string status
		string code
		Date createdAt
		UUID createdBy
	}

	Password {
		UUID id PK
		UUID userId FK
		number algVersion
		string hash
		string salt
		Date createdAt
		Date deletedAt
		UUID deletedBy
	}

	Permission {
		UUID id PK
		string action
		string scope
		UUID sourceId FK
		string sourceType
		UUID targetId FK
		string targetType
		boolean approved
		Date createdAt
		UUID createdBy
		Date updatedAt
		UUID updatedBy
		Date deletedAt
		UUID deletedBy
	}

	Phone {
		UUID id PK
		UUID userId FK
		string value
		boolean verified
		Date createdAt
		UUID createdBy
		Date updatedAt
		UUID updatedBy
		Date deletedAt
		UUID deletedBy
	}

	PhoneVerification {
		UUID id PK
		UUID phoneId FK
		string status
		string code
		Date expiresAt
		Date createdAt
		UUID createdBy
		Date updatedAt
		UUID updatedBy
	}

	PhoneVerificationAttempt {
		UUID id PK
		UUID phoneVerificationId FK
		string status
		string code
		Date createdAt
		UUID createdBy
	}

	Session {
		UUID id PK
		UUID userId FK
		Date expiresAt
		Date createdAt
		UUID createdBy
		Date deletedAt
		UUID deletedBy
	}

	Signup {
		UUID id PK
		UUID userId FK
		Date createdAt
	}

	User {
		UUID id PK
		string name
		boolean blocked
		string role
		string country
		string language
		Date createdAt
		UUID createdBy
		Date updatedAt
		UUID updatedBy
		Date deletedAt
		UUID deletedBy
	}

Configuration

Install dependencies:

npm install

Build the source code:

npm run build

Set environment variables:

| Name | Description | | ----------------------------------- | --------------------------------------------------------------------------------------------- | | BASE_URL or ID_SERVICE_BASE_URL | The base url of this service. | | COOKIE_NAME | The name of the cookie to be used: ID-Sessionor __Secure-ID-Session. | | COOKIE_SECRET | The secret used to encrypt/decrypt cookies randomBytes(16).toString("hex"). | | CSRF_SECRET | The secret used to encrypt CSRF tokens. | | DATA_SERVICE_BASE_URL | The base url of the data service. | | DEVELOPER_SERVICE_BASE_URL | The base url of the developer service. | | ELEVATED_SESSION_TIMEOUT_MINUTES | The duration (in minutes) for which an elevated session is valid after secure authentication. | | EMAIL_PATTERNS | The list of emails ([email protected]) or domains (*@hedia.com) allowed to sign up. | | EVENT_SERVICE_BASE_URL | The base url of the event service. | | EXPORT_SERVICE_BASE_URL | The base url of the export service. | | HEDIA_SERVER_BASE_URL | The base url of the hedia server. | | LOCAL_PG_URL | The local postgres connection string. | | LOG_FORMAT | The log format that should be used by the logger. | | LOG_LEVEL | The minimum log level that should be logged. | | MAIL_SERVICE_BASE_URL | The base url of the mail service. | | MAIL_SERVICE_EMAIL_SENDER | The sender email that should be used by the mail service. | | OAUTH2_SERVICE_BASE_URL | The base url of the oauth2 service. | | PRIVATE_KEY | The private key of this service in JSON Web Key format. | | PUBLIC_KEY | The public key of this service in JSON Web Key format. | | RATE_LIMIT | The maximum number of attempts to perform an action in a given time frame. | | RATE_LIMIT_TIME_FRAME | The time frame in seconds during which a user can attempt to perform an action. | | REMOTE_PG_URL | The remote postgres connection string shared with other services. | | SERVER_PORT | The port of the HTTP Server. | | STATE_SECRET | The secret used to encrypt url state. | | WEBHOOK_SERVICE_BASE_URL | The base url of the webhook service. |

Tip: Run the following script to set them up automatically (fetches the local env config from 1Password):

npm run env

Setup the database with a default admin user:

npm run setup [email]

Run

Option #1: Run in development mode (project rebuilt and restarted when source files change)

npm run dev

Option #2: Run in production mode

npm run start