{"id":27185022,"url":"https://github.com/threefoldtech/tf-kyc-verifier","last_synced_at":"2025-04-09T17:10:09.336Z","repository":{"id":258765651,"uuid":"869425229","full_name":"threefoldtech/tf-kyc-verifier","owner":"threefoldtech","description":"The TFGrid KYC Verifier is a robust identity verification service integrated with iDenfy to ensure secure and compliant user deployments on TFGrid cloud","archived":false,"fork":false,"pushed_at":"2025-02-12T16:23:32.000Z","size":345,"stargazers_count":0,"open_issues_count":11,"forks_count":0,"subscribers_count":9,"default_branch":"development","last_synced_at":"2025-04-09T17:10:01.821Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/threefoldtech.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-10-08T09:19:43.000Z","updated_at":"2025-01-21T11:48:12.000Z","dependencies_parsed_at":"2024-10-28T18:53:38.868Z","dependency_job_id":"00e7af6f-99d7-47ed-9b59-0dcad4f677ba","html_url":"https://github.com/threefoldtech/tf-kyc-verifier","commit_stats":null,"previous_names":["threefoldtech/tfgrid-kyc-verifier","threefoldtech/tf-kyc-verifier"],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/threefoldtech%2Ftf-kyc-verifier","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/threefoldtech%2Ftf-kyc-verifier/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/threefoldtech%2Ftf-kyc-verifier/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/threefoldtech%2Ftf-kyc-verifier/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/threefoldtech","download_url":"https://codeload.github.com/threefoldtech/tf-kyc-verifier/tar.gz/refs/heads/development","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248074976,"owners_count":21043490,"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":[],"created_at":"2025-04-09T17:10:08.397Z","updated_at":"2025-04-09T17:10:09.319Z","avatar_url":"https://github.com/threefoldtech.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TF KYC Service\n\n## Overview\n\nTF KYC Service is a Go-based service that provides Know Your Customer (KYC) functionality for the TF Grid. It integrates with iDenfy for identity verification.\n\n## Features\n\n- Identity verification using iDenfy\n- Blockchain integration with TFChain (Substrate-based)\n- MongoDB for data persistence\n- RESTful API endpoints for KYC operations\n- Swagger documentation\n- Containerized deployment\n\n## Prerequisites\n\n- Go 1.22+\n- MongoDB 4.4+\n- Docker and Docker Compose (for containerized deployment)\n- iDenfy API credentials\n\n## Installation\n\n1. Clone the repository:\n\n    ```bash\n    git clone https://github.com/yourusername/tf-kyc-verifier.git\n    cd tf-kyc-verifier\n    ```\n\n2. Set up your environment variables:\n\n    ```bash\n    cp .app.env.example .app.env\n    cp .db.env.example .db.env\n    ```\n\nEdit `.app.env` and `.db.env` with your specific configuration details.\n\n## Configuration\n\nThe application uses environment variables for configuration. Here's a list of all available configuration options:\n\n### Database Configuration\n\n- `MONGO_URI`: MongoDB connection URI (default: \"mongodb://localhost:27017\")\n- `DATABASE_NAME`: Name of the MongoDB database (default: \"tf-kyc-db\")\n\n### Server Configuration\n\n- `PORT`: Port on which the server will run (default: \"8080\")\n\n### iDenfy Configuration\n\n- `IDENFY_API_KEY`: API key for iDenfy service (required) (note: make sure to use correct iDenfy API key for the environment dev, test, and production) (iDenfy dev -\u003e TFChain Devnet, iDenfy test -\u003e TFChain QAnet, iDenfy prod -\u003e TFChain Testnet and Mainnet)\n- `IDENFY_API_SECRET`: API secret for iDenfy service (required)\n- `IDENFY_BASE_URL`: Base URL for iDenfy API (default: \"\u003chttps://ivs.idenfy.com\u003e\")\n- `IDENFY_CALLBACK_SIGN_KEY`: Callback signing key for iDenfy webhooks (required) (note: should match the signing key in iDenfy dashboard for the related environment and should be at least 32 characters long)\n- `IDENFY_WHITELISTED_IPS`: Comma-separated list of whitelisted IPs for iDenfy callbacks\n- `IDENFY_DEV_MODE`: Enable development mode for iDenfy integration (default: false) (note: works only in iDenfy dev environment, enabling it in test or production environment will cause iDenfy to reject the requests)\n- `IDENFY_CALLBACK_URL`: URL for iDenfy verification update callbacks. (example: `https://{KYC-SERVICE-DOMAIN}/webhooks/idenfy/verification-update`)\n- `IDENFY_NAMESPACE`: Namespace for isolating diffrent TF KYC verifier services data in same iDenfy backend (default: \"\") (note: if you are using the same iDenfy backend for multiple services on same tfchain network, you can set this to the unique identifier of the service to isolate the data. don't touch unless you know what you are doing)\n\n### TFChain Configuration\n\n- `TFCHAIN_WS_PROVIDER_URL`: WebSocket provider URL for TFChain (default: \"wss://tfchain.grid.tf\")\n\n### Verification Settings\n\n- `VERIFICATION_SUSPICIOUS_VERIFICATION_OUTCOME`: Outcome for suspicious verifications (default: \"APPROVED\")\n- `VERIFICATION_EXPIRED_DOCUMENT_OUTCOME`: Outcome for expired documents (default: \"REJECTED\")\n- `VERIFICATION_MIN_BALANCE_TO_VERIFY_ACCOUNT`: Minimum balance in unitTFT required to verify an account (default: 10000000)\n- `VERIFICATION_ALWAYS_VERIFIED_IDS`: Comma-separated list of TFChain SS58Addresses that are always verified (default: \"\")\n- `VERIFICATION_ALWAYS_VERIFIED_IDS`: When the AlwaysVerifiedIDsOnly is true, the creation of KYC tokens is disabled on this network (default: false)\n\n### Rate Limiting\n\n#### IP-based Rate Limiting\n\n- `IP_LIMITER_MAX_TOKEN_REQUESTS`: Maximum number of token requests per IP (default: 4)\n- `IP_LIMITER_TOKEN_EXPIRATION`: Token expiration time in minutes (default: 1440)\n\n#### ID-based Rate Limiting\n\n- `ID_LIMITER_MAX_TOKEN_REQUESTS`: Maximum number of token requests per ID (default: 4)\n- `ID_LIMITER_TOKEN_EXPIRATION`: Token expiration time in minutes (default: 1440)\n\n### Challenge Configuration\n\n- `CHALLENGE_WINDOW`: Time window in seconds for challenge validation (default: 8)\n- `CHALLENGE_DOMAIN`: Current service domain name for challenge validation (required) (example: `tfkyc.dev.grid.tf`)\n\n### Logging\n\n- `DEBUG`: Enable debug logging (default: false)\n\nTo configure these options, you can either set them as environment variables or include them in your `.env` file.\n\nRegarding the iDenfy signing key, it's best to use key composed of alphanumeric characters to avoid such issues.\nYou can generate a random key using the following command:\n\n```bash\ncat /dev/urandom | tr -dc 'a-zA-Z0-9' | fold -w 32 | head -n 1\n```\n\nRefer to `internal/configs/config.go` for the implementation details of these configuration options.\n\n## Running the Application\n\n### Using Docker Compose\n\nFirst make sure to create and set the environment variables in the `.app.env`, `.db.env` files.\nExamples can be found in `.app.env.example`, `.db.env.example`.\nIn beta releases, we include the mongo-express container, but you can opt to disable it.\n\nTo start only the core services (API and MongoDB) using Docker Compose:\n\n```bash\ndocker compose up -d\n```\n\nTo include mongo-express for development, make sure to create and set the environment variables in the `.express.env` file as well, then run:\n\n```bash\ndocker compose -f docker-compose.yml -f docker-compose.dev.yml up -d\n```\n\nTo start only mongo-express if core services are already running, run:\n\n```bash\ndocker compose -f docker-compose.yml -f docker-compose.dev.yml up -d mongo-express\n```\n\n### Running Locally\n\nTo run the application locally:\n\n1. Ensure MongoDB is running and accessible.\n2. export the environment variables:\n\n    ```bash\n    set -a\n    source .app.env\n    set +a\n    ```\n\n3. Run the application:\n\n    ```bash\n    go run cmd/api/main.go\n    ```\n\n## API Endpoints\n\n### Client Endpoints\n\n#### Token Management\n\n- `POST /api/v1/token`\n  - Get or create a verification token\n  - Required Headers:\n    - `X-Client-ID`: TFChain SS58Address (48 chars)\n    - `X-Challenge`: Hex-encoded message `{api-domain}:{timestamp}`\n    - `X-Signature`: Hex-encoded sr25519|ed25519 signature (128 chars)\n  - Responses:\n    - `200`: Existing token retrieved\n    - `201`: New token created\n    - `400`: Bad request\n    - `401`: Unauthorized\n    - `402`: Payment required\n    - `403`: Forbidden\n    - `409`: Conflict\n\n#### Verification\n\n- `GET /api/v1/data`\n  - Get verification data for a client\n  - Required Headers:\n    - `X-Client-ID`: TFChain SS58Address (48 chars)\n    - `X-Challenge`: Hex-encoded message `{api-domain}:{timestamp}`\n    - `X-Signature`: Hex-encoded sr25519|ed25519 signature (128 chars)\n  - Responses:\n    - `200`: Success\n    - `400`: Bad request\n    - `401`: Unauthorized\n    - `404`: Not found\n\n- `GET /api/v1/status`\n  - Get verification status\n  - Query Parameters (at least one required):\n    - `client_id`: TFChain SS58Address (48 chars)\n    - `twin_id`: Twin ID\n  - Responses:\n    - `200`: Success\n    - `400`: Bad request\n    - `404`: Not found\n\n### Webhook Endpoints\n\n- `POST /webhooks/idenfy/verification-update`\n  - Process verification update from iDenfy\n  - Required Headers:\n    - `Idenfy-Signature`: Verification signature\n  - Responses:\n    - `200`: Success\n    - `400`: Bad request\n\n- `POST /webhooks/idenfy/id-expiration`\n  - Process document expiration notification (Not implemented)\n  - Responses:\n    - `501`: Not implemented\n\n### Health Check\n\n- `GET /api/v1/health`\n  - Check service health status\n  - Responses:\n    - `200`: Returns health status\n      - `healthy`: All systems operational\n      - `degraded`: Some systems experiencing issues\n\n### Miscellaneous\n\n- `GET /api/v1/version`\n  - Get application version\n  - Responses:\n    - `200`: Returns application version\n      - `version`: Application version\n\n- `GET /api/v1/configs`\n  - Get application configurations\n  - Responses:\n    - `200`: Returns application configurations\n\n### Documentation\n\n- `GET /docs`\n  - Swagger documentation interface\n  - Provides interactive API documentation and testing interface\n\nRefer to the Swagger documentation at `/docs` endpoint for detailed information about request/response formats and examples.\n\n## Swagger Documentation\n\nSwagger documentation is available. To view it, run the application and navigate to the `/docs` endpoint in your browser.\n\n## Project Structure\n\n- `cmd/`: Application entrypoints\n  - `api/`: Main API server\n- `internal/`: Internal packages\n  - `clients/`: External service clients\n  - `configs/`: Configuration handling\n  - `errors/`: Custom error types\n  - `handlers/`: HTTP request handlers\n  - `logger/`: Logging configuration\n  - `middlewares/`: HTTP middlewares\n  - `models/`: Data models\n  - `repositories/`: Data access layer\n  - `responses/`: API response structures\n  - `server/`: Server setup and routing\n  - `services/`: Business logic\n- `api/`: API documentation\n  - `docs/`: Swagger documentation files\n- `.github/`: GitHub specific files\n  - `workflows/`: GitHub Actions workflows\n- `scripts/`: Utility and Development scripts\n- `docs/`: Documentation\n\n- Configuration files:\n  - `.app.env.example`: Example application environment variables\n  - `.db.env.example`: Example database environment variables\n  - `Dockerfile`: Container build instructions\n  - `docker-compose.yml`: Multi-container Docker setup\n  - `go.mod`: Go module definition\n  - `go.sum`: Go module checksums\n\n## Development\n\n### Running Tests\n\nTo run the test suite:\n\nTODO: Add tests\n\n### Building the Docker Image\n\nTo build the Docker image:\n\n```bash\ndocker build -t tf_kyc_verifier .\n```\n\n### Running the Docker Container\n\nTo run the Docker container and use .env variables:\n\n```bash\ndocker run -d -p 8080:8080 --env-file .app.env tf_kyc_verifier\n```\n\n### Creating database dump\n\nMost of the normal tools will work, although their usage might be a little convoluted in some cases to ensure they have access to the mongod server. A simple way to ensure this is to use docker exec and run the tool from the same container, similar to the following:\n\n```bash\n#!/bin/bash\n# mongo_backup.sh\n\n# Install Environment file\nsource .db.env\n\ndocker exec tf_kyc_db mongodump --username $MONGO_INITDB_ROOT_USERNAME  --password $MONGO_INITDB_ROOT_PASSWORD  --authenticationDatabase admin --db tfgrid-kyc-db --archive=mongo.kyc.archive.dump\ndocker cp tf_kyc_db:/mongo.kyc.archive.dump mongo.kyc.archive.dump\n```\n\n### Restoring database dump\n\nTo restore the previously created backup, you can use a similar script as follows:\n\n```bash\n#!/bin/bash\n# mongo_restore.sh\n\n# Install Environment file\nsource .db.env\n\ndocker cp mongo.kyc.archive.dump tf_kyc_db:/mongo.kyc.archive.dump\ndocker exec tf_kyc_db mongorestore --username $MONGO_INITDB_ROOT_USERNAME  --password $MONGO_INITDB_ROOT_PASSWORD  --authenticationDatabase admin --nsInclude='tfgrid-kyc-db.*' --archive=mongo.kyc.archive.dump\n```\n\n## Production\n\nRefer to the [Production Setup](./docs/production.md) documentation for production setup details.\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## License\n\nThis project is licensed under the Apache 2.0 License. See the `LICENSE` file for more details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthreefoldtech%2Ftf-kyc-verifier","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthreefoldtech%2Ftf-kyc-verifier","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthreefoldtech%2Ftf-kyc-verifier/lists"}