Initial commit

Author: jmgasper

.gitignore

@@ -0,0 +1,56 @@
+# compiled output
+/dist
+/node_modules
+/build
+
+# Logs
+logs
+*.log
+npm-debug.log*
+pnpm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log*
+
+# OS
+.DS_Store
+
+# Tests
+/coverage
+/.nyc_output
+
+# IDEs and editors
+/.idea
+.project
+.classpath
+.c9/
+*.launch
+.settings/
+*.sublime-workspace
+
+# IDE - VSCode
+.vscode/*
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+
+# dotenv environment variable files
+.env
+.env.development.local
+.env.test.local
+.env.production.local
+.env.local
+
+# temp directory
+.temp
+.tmp
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# Diagnostic reports (https://nodejs.org/api/report.html)
+report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json

.nvmrc

@@ -0,0 +1 @@
+v22.13.1

.prettierrc

@@ -0,0 +1,4 @@
+{
+  "singleQuote": true,
+  "trailingComma": "all"
+}

Dockerfile

@@ -0,0 +1,20 @@
+# syntax=docker/dockerfile:1
+
+FROM node:22.13.1-alpine
+
+RUN apk add --no-cache bash
+RUN apk update
+
+ARG RESET_DB_ARG=false
+ENV RESET_DB=$RESET_DB_ARG
+ARG SEED_DATA_ARG=""
+ENV SEED_DATA=$SEED_DATA_ARG
+ENV PRISMA_CLI_BINARY_TARGETS=linux-musl-openssl-3.0.x
+
+WORKDIR /app
+COPY . .
+RUN npm install pnpm -g
+RUN pnpm install
+RUN pnpm run build
+RUN chmod +x appStartUp.sh
+CMD ./appStartUp.sh

M2M_TOKEN_GUIDE.md

@@ -0,0 +1,98 @@
+# Machine-to-Machine (M2M) Token Guide for Topcoder Review API
+
+## Overview
+
+The Topcoder Review API supports machine-to-machine (M2M) authentication using Auth0 for service-to-service integrations.
+This guide explains how to use M2M tokens with the API.
+
+## What are M2M Tokens?
+
+Machine-to-Machine tokens are designed for service-to-service authentication where a human user is not directly involved.
+Instead of using user roles for authorization, M2M tokens use scopes, which are permissions attached to the token.
+
+## M2M Token Structure
+
+M2M tokens from Auth0 contain the following important claims:
+- `iss` (issuer): The Auth0 domain that issued the token
+- `sub` (subject): The client ID of the application
+- `aud` (audience): The API identifier (audience)
+- `exp` (expiration time): When the token expires
+- `iat` (issued at time): When the token was issued
+- `scope`: Space-separated list of authorized scopes
+
+## Available Scopes
+
+The Topcoder Review API supports the following scopes:
+
+### Group Scopes
+- `read:groups` - Do read action of groups
+- `write:groups` - Do write action of groups
+- `all:groups` - All groups-related operations
+
+## Getting an M2M Token
+
+To get an M2M token, you need to have a client registered in Auth0 with the appropriate permissions.
+
+### Example Request
+
+```bash
+curl --request POST \
+  --url https://topcoder-dev.auth0.com/oauth/token \
+  --header 'content-type: application/json' \
+  --data '{
+    "client_id": "YOUR_CLIENT_ID",
+    "client_secret": "YOUR_CLIENT_SECRET",
+    "audience": "https://m2m.topcoder-dev.com/",
+    "grant_type": "client_credentials"
+  }'
+```
+
+### Example Response
+
+```json
+{
+  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6...",
+  "scope": "read:appeal create:review all:scorecard",
+  "expires_in": 86400,
+  "token_type": "Bearer"
+}
+```
+
+## Using the Token
+
+Include the token in your API requests in the Authorization header:
+
+```
+Authorization: Bearer YOUR_ACCESS_TOKEN
+```
+
+## Scope Validation
+
+When a request is made to the API, the token's scopes are validated against the required scopes for the endpoint.
+If the token has at least one of the required scopes, access is granted.
+
+### Notes on "all:" Scopes
+
+Scopes that start with "all:" automatically grant access to all the specific operations in that category.
+For example, `all:groups` includes `read:groups`, `write:groups`, etc.
+
+## Testing M2M Tokens
+
+For testing locally, you can use the following predefined test tokens:
+
+- `m2m-token-all` - Has all available scopes
+- `m2m-token-groups` - Has all groups scopes
+
+Example usage with curl:
+
+```bash
+curl -X GET http://localhost:3000/v6/groups \
+  -H "Authorization: Bearer m2m-token-review"
+```
+
+## Troubleshooting
+
+If you receive a 403 Forbidden response, check that:
+1. Your token is valid and not expired
+2. The token has the required scope for the endpoint
+3. You're using the correct audience and issuer

README.md

@@ -0,0 +1,85 @@
+# Topcoder Group API
+
+Group API built on modern frameworks for managing all group-related Topcoder needs.
+
+## Project setup
+
+```bash
+$ pnpm install
+```
+
+## Compile and run the project
+
+```bash
+# development
+$ pnpm run start
+
+# watch mode
+$ pnpm run start:dev
+
+# production mode
+$ pnpm run start:prod
+```
+
+## Database
+
+```bash
+# run postgres in docker, or other approach
+docker run -p 5432:5432  -e POSTGRES_PASSWORD=mysecretpassword postgres:14
+
+export DATABASE_URL="postgresql://postgres:mysecretpassword@localhost:5432/group-api?schema=groups"
+
+# run migration
+npx prisma migrate dev
+
+# seed data
+npx prisma db seed
+or
+npx prisma migrate reset
+
+# if you modify prisma schema, run migration again
+# and it'll ask
+# Enter a name for the new migration:
+# just provide a good migration name, such as
+#- `add_user_table`
+#- `update_user_fields`
+#- `create_posts_table`
+#- `add_email_to_users`
+#- `update_foreign_keys`
+```
+
+## Data import
+
+- create a .env file `mv .env.sample .env`
+- update the postgres database url in .env file —
+  `DATABASE_URL="postgresql://postgres:mysecretpassword@localhost:5432/group-api?schema=groups"`
+- install dependencies `pnpm install`
+- run the prisma migration `npx prisma migrate dev`
+- run the prisma seed `npx prisma db seed`
+- run the project `pnpm run start`
+
+
+## Test API
+- import Postman collection. The files are `doc/Group API.postman_collection.json` and `doc/Group.postman_environment.json`
+- set env to suit your environment
+- run mock api `node mock/mock-api.js`
+- reset seed data `pnpm run seed-data`
+- start app `pnpm run start:dev`
+- generate the token
+
+```bash
+curl --request POST \
+  --url https://auth0proxy.topcoder-dev.com/token \
+  --header 'content-type: application/json' \
+  --data '{"auth0_url": "https://topcoder-dev.auth0.com/oauth/token", "client_id":"8uHVTW2WHp8BbBPX7J0YTAwgYbYTfjsM","client_secret":"hQXGeKO-cSZ15CLBNRDGZAGRcHWay6PAR_zTQQz4YjdX7QNU7NwGoaa3YuuUYvUv","audience":"https://m2m.topcoder-dev.com/","grant_type":"client_credentials"}'
+```
+
+For a read-only scope M2M token, use:
+
+```
+"client_id":"dgrh9mkk8N6sWsVPFf6JqdVmjjuibowf"
+"client_secret":"_6jFqIppsA3u87Tm7mRDXhX_yf8-DC2ooc5f0affjuWoRiLG1ZriHtUsMQgo61qp"
+```
+
+- then you can use Postman to test all apis
+- Swagger docs are accessible at `http://localhost:3000/api-docs`

appStartUp.sh

@@ -0,0 +1,16 @@
+#!/bin/bash
+set -eo pipefail
+
+export DATABASE_URL=$(echo -e ${DATABASE_URL})
+
+echo "Database - running migrations."
+if $RESET_DB; then
+    echo "Resetting DB"
+    npx prisma migrate reset --force
+else
+    echo "Running migrations"
+    npx prisma migrate deploy
+fi
+
+# Start the app
+pnpm start:prod

build.sh

@@ -0,0 +1,3 @@
+#!/bin/bash
+set -eo pipefail
+docker buildx build --no-cache=true --build-arg RESET_DB_ARG=<<pipeline.parameters.reset-db>> --build-arg SEED_DATA_ARG=${DEPLOYMENT_ENVIRONMENT} -t ${APPNAME}}:latest .