fix: Restructure environment variables / configuration parameters [DE…

…V-2758] (#240) * Rearrange variables * Rename ISSUER_DATABASE_CERT * Rename CUSTOMER_ID * Rename ENABLE_AUTH * Rename AUDIENCE_ENDPOINT * Rename LOGTO_ env vars * Update Dockerfile * Update environment variables * Update authentication.ts * Bump deps * Update README
cheqd · Jun 5, 2023 · b206958 · b206958
1 parent 1af5f5d
commit b206958
Show file tree

Hide file tree

Showing 11 changed files with 3,498 additions and 520 deletions.
diff --git a/.env.example b/.env.example
@@ -6,19 +6,19 @@ ALLOWED_ORIGINS="http://localhost:8787"
 # Database
 DB_CONNECTION_URL=postgres://logto:password@localhost:5432/logto
 DB_ENCRYPTION_KEY="<db-encryption-key>"
-# ISSUER_DATABASE_CERT="certs/issuer.crt"
+# DB_CERTIFICATE="certs/issuer.crt"
 
 # OpenId
 OIDC_JWKS_ENDPOINT='http://localhost:3001/oidc/jwks'
 OIDC_ISSUER='http://localhost:3001/oidc'
-AUDIENCE_ENDPOINT='http://localhost:8787/1.0/api/'
+LOGTO_RESOURCE_URL='http://localhost:8787/1.0/api/'
 
 # Authentication
-ENABLE_AUTH="boolean,default:false"
-CUSTOMER_ID="default customer id"
+ENABLE_AUTHENTICATION="boolean,default:false"
+DEFAULT_CUSTOMER_ID="default customer id"
 
 # verida
-USE_VERIDA_CONNECTOR="false"
+ENABLE_VERIDA_CONNECTOR="false"
 VERIDA_PRIVATE_KEY="akjvncanv....avoa"
 POLYGON_PRIVATE_KEY="alnvca...dvncioa"
 VERIDA_NETWORK="testnet"
diff --git a/Dockerfile b/Dockerfile
@@ -40,52 +40,67 @@ COPY --from=builder --chown=node:node /home/node/app/dist ./dist
 # Install production dependencies
 RUN npm ci
 
-# Build-time arguments
+# Base arguments: build-time
 ARG NPM_CONFIG_LOGLEVEL=warn
 ARG PORT=3000
-ARG DB_ENCRYPTION_KEY
+
+# Network API endpoints: build-time
+ARG MAINNET_RPC_URL=https://rpc.cheqd.net:443
+ARG TESTNET_RPC_URL=https://rpc.cheqd.network:443
+ARG RESOLVER_URL=https://resolver.cheqd.net/1.0/identifiers/
+
+# Veramo Database configuration: build-time
 ARG DB_CONNECTION_URL
-ARG ISSUER_DATABASE_CERT
-ARG MAINNET_RPC_URL
-ARG TESTNET_RPC_URL
-ARG RESOLVER_URL
+ARG DB_ENCRYPTION_KEY
+ARG DB_CERTIFICATE
+
+#  LogTo: build-time
+ARG ENABLE_AUTHENTICATION=false
+ARG LOGTO_ENDPOINT
+ARG LOGTO_RESOURCE_URL
+ARG LOGTO_APP_ID
+ARG LOGTO_APP_SECRET
 ARG ALLOWED_ORIGINS
-#  LogTo
-ARG OIDC_JWKS_ENDPOINT
-ARG AUDIENCE_ENDPOINT
-ARG OIDC_ISSUER
-# Authentication
-ARG ENABLE_AUTH
-ARG CUSTOMER_ID
-# verida
-ARG USE_VERIDA_CONNECTOR
+ARG DEFAULT_CUSTOMER_ID
+
+# Verida connector: build-time
+ARG ENABLE_VERIDA_CONNECTOR=false
+ARG VERIDA_NETWORK=testnet
+ARG POLYGON_RPC_URL=https://rpc-mumbai.maticvigil.com
 ARG VERIDA_PRIVATE_KEY
 ARG POLYGON_PRIVATE_KEY
-ARG VERIDA_NETWORK
 
-# Run-time environment variables
+# Environment variables: base configuration
 ENV NPM_CONFIG_LOGLEVEL ${NPM_CONFIG_LOGLEVEL}
 ENV PORT ${PORT}
-ENV DB_ENCRYPTION_KEY ${DB_ENCRYPTION_KEY}
-ENV DB_CONNECTION_URL ${DB_CONNECTION_URL}
-ENV ISSUER_DATABASE_CERT ${ISSUER_DATABASE_CERT}
+
+# Environment variables: network API endpoints
 ENV MAINNET_RPC_URL ${MAINNET_RPC_URL}
 ENV TESTNET_RPC_URL ${TESTNET_RPC_URL}
 ENV RESOLVER_URL ${RESOLVER_URL}
+
+# Environment variables: Veramo Database configuration
+ENV DB_CONNECTION_URL ${DB_CONNECTION_URL}
+ENV DB_ENCRYPTION_KEY ${DB_ENCRYPTION_KEY}
+ENV DB_CERTIFICATE ${DB_CERTIFICATE}
+
+# Environment variables: LogTo
+ENV ENABLE_AUTHENTICATION ${ENABLE_AUTHENTICATION}
+ENV DEFAULT_CUSTOMER_ID ${DEFAULT_CUSTOMER_ID}
+ENV LOGTO_ENDPOINT ${LOGTO_ENDPOINT}
+ENV LOGTO_RESOURCE_URL ${LOGTO_RESOURCE_URL}
+ENV LOGTO_APP_ID ${LOGTO_APP_ID}
+ENV LOGTO_APP_SECRET ${LOGTO_APP_SECRET}
 ENV ALLOWED_ORIGINS ${ALLOWED_ORIGINS}
-# LogTo
-ENV OIDC_JWKS_ENDPOINT ${OIDC_JWKS_ENDPOINT}
-ENV AUDIENCE_ENDPOINT ${AUDIENCE_ENDPOINT}
-ENV OIDC_ISSUER ${OIDC_ISSUER}
-# Authentication
-ENV ENABLE_AUTH ${ENABLE_AUTH}
-ENV CUSTOMER_ID ${CUSTOMER_ID}
-# verida
-ENV USE_VERIDA_CONNECTOR ${USE_VERIDA_CONNECTOR}
+
+# Environment variables: Verida connector
+ENV ENABLE_VERIDA_CONNECTOR ${ENABLE_VERIDA_CONNECTOR}
+ENV VERIDA_NETWORK ${VERIDA_NETWORK}
+ENV POLYGON_RPC_URL ${POLYGON_RPC_URL}
 ENV VERIDA_PRIVATE_KEY ${VERIDA_PRIVATE_KEY}
 ENV POLYGON_PRIVATE_KEY ${POLYGON_PRIVATE_KEY}
-ENV VERIDA_NETWORK ${VERIDA_NETWORK}
 
+# Set ownership permissions
 RUN chown -R node:node /home/node/app
 
 # Specify default port

diff --git a/README.md b/README.md
@@ -14,7 +14,7 @@ The purpose of this service is to issue and verify credentials. This service by
 
 ### Issue a credential
 
-- **Endpoint** POST `/1.0/api/credentials/issue`
+- **Endpoint** POST `/credentials/issue`
 - **Accepts**: `application/json`
 - **Request Body**: JSON object with following fields
   - `attributes` - A json object with all the credential attributes
@@ -28,7 +28,7 @@ The purpose of this service is to issue and verify credentials. This service by
 
 ### Verify a Credential
 
-- **Endpoint** POST `/1.0/api/credentials/verify`
+- **Endpoint** POST `/credentials/verify`
 - **Accepts**: `application/json`
 - **Request Body**: JSON object with following fields:
   - `credential` - A verifiable credential or the JWT string
@@ -42,36 +42,54 @@ The purpose of this service is to issue and verify credentials. This service by
 
 - **Endpoint**: `/` (This endpoint redirects to the swagger api docs)
 
-## 🧑‍💻🛠 Developer Guide
+## 🔧 Configuration
 
-### Setup
+The application allows configuring the following parameters using environment variables.
 
-Dependencies can be installed using NPM or any other node package manager.
+### Core configuration
 
-```bash
-npm install
-npm run build
-```
+#### Network API endpoints
+
+1. `MAINNET_RPC_URL`: RPC endpoint for cheqd mainnet. (Default: `https://rpc.cheqd.net:443`)
+2. `TESTNET_RPC_URL`: RPC endpoint for cheqd testnet. (`https://rpc.cheqd.network:443`)
+3. `RESOLVER_URL`: API endpoint for a [DID Resolver](https://github.com/cheqd/did-resolver) endpoint that supports `did:cheqd`.
+
+#### Veramo KMS Database
+
+The application supports two modes in which keys are managed: either just storing them in-memory while a container is running, or persisting them in a PostgresSQL database with Veramo SDK. Using an external Postgres database allows for "custodian" mode where identity and cheqd/Cosmos keys can be offloaded by client applications to be stored in the database.
+
+1. `DB_CONNECTION_URL`: Postgres database connection URL, e.g. `postgres://<user>:<password>@<host>:<port>/<database>`
+2. `DB_ENCRYPTION_KEY`: Secret key used to encrypt the Veramo key-specific database tables. This adds a layer of protection by not storing the database in plaintext.
+3. `DB_CERTIFICATE`: Custom CA certificate required to connect to the database (optional).
+
+#### API Authentication using LogTo
+
+By default, the application has API authentication disabled (which can be changed in configuration). If, however, you'd like to run the app with API authentication features, the following variables need to be configured.
+
+We use a self-hosted version of [LogTo](https://logto.io/), which supports OpenID Connect. Theoretically, these values could also be replaced with [LogTo Cloud](http://cloud.logto.io/) or any other OpenID Connect identity provider.
+
+1. `ENABLE_AUTHENTICATION`: Turns API authentication guards on/off. (Default: `false`)
+2. `LOGTO_ENDPOINT`: API endpoint for LogTo server
+3. `ALLOWED_ORIGINS`: CORS allowed origins used in the app
+4. `DEFAULT_CUSTOMER_ID`: Customer/user in LogTo to use for unauthenticated users.
 
-### Configuration
+### 3rd Party Connectors
 
-The application expects the following environment variables to be defined for the app to function:
+The app supports 3rd party connectors for credential storage and delivery.
 
-1. `DB_CONNECTION_URL`: The postgres database url e.g. `postgres://<user>:<password>@<host>:<port>/<database>?<query>`
-2. `DB_ENCRYPTION_KEY`: A secret key for the veramo wallet
-3. `PORT`: Port number for the credential service (optional)
-4. `FEE_PAYER_MNENONIC_TESTNET`: Mnemonic for the issuer's Cosmos account to be used for testnet.
-5. `FEE_PAYER_MNENONIC_MAINNET`: Mnemonic for the issuer's Cosmos account to be used for mainnet.
-6. `MAINNET_RPC_URL`: Optional RPC URL for a node on cheqd mainnet, e.g., `https://rpc.cheqd.net`
-7. `TESTNET_RPC_URL`: Optional RPC URL for a node on cheqd testnet, e.g., `https://rpc.cheqd.network`
-8. `ISSUER_DATABASE_CERT`: Optional ca certificate parameter of the database
-9. `OIDC_JWKS_ENDPOINT`: Endpoint to logTo `jwks` checker. Usual `<logto_endpoint>/oidc/jwks`
-10. `AUDIENCE_ENDPOINT`: Endpoint for ResourceAPI in LogTo. For now it seems to be a root path for CredentialServce, like `<credential-service>/1.0/api` . Also, it should be exactly the same as `LOGTO_RESOURCE_URL` on frontend, cause for this particular endpoint jwt token will be issued.
-11. `OIDC_ISSUER`: endopoint of jwt token issuer. In our case it will be LogTo `oidc` endpoint, like `<logto_endpoint>/oidc`
+#### Verida
 
-### Run
+The app's [Verida Network](https://www.verida.network/) connector can be enabled to deliver generated credentials to Verida Wallet.
 
-Run a postgres instance
+1. `ENABLE_VERIDA_CONNECTOR`: Turns Verida connector on/off. (Default: `false`)
+2. `VERIDA_NETWORK`: Verida Network type to connect to. (Default: `testnet`)
+3. `VERIDA_PRIVATE_KEY`: Secret key for Verida Network API.
+4. `POLYGON_RPC_URL`: Polygon Network RPC URL for connections.
+5. `POLYGON_PRIVATE_KEY`: Secret key for Polygon Network.
+
+### Run the application
+
+Initiate a Postgres database, in case you're using an external database.
 
 ```bash
 docker pull postgres
@@ -86,7 +104,20 @@ Once configured, the app can be run using NPM:
 npm start
 ```
 
-Or, to build and run in Docker, use the [Dockerfile](Dockerfile) provided.
+## 🧑‍💻🛠 Developer Guide
+
+### Build using NPM
+
+Dependencies can be installed using NPM or any other node package manager.
+
+```bash
+npm install
+npm run build
+```
+
+### Build using Docker
+
+To build and run in Docker, use the [Dockerfile](Dockerfile) provided.
 
 ```bash
 docker build -t credential-service .