From 963a9d1040a01cca6429fc5d535d2f4310457584 Mon Sep 17 00:00:00 2001 From: fISHIE <83373559+WhoIsFishie@users.noreply.github.com> Date: Sun, 8 Feb 2026 15:39:49 +0500 Subject: [PATCH] updated readme --- README.md | 291 +++++++++++++++++++++++++--------- frontend-react/vite.config.ts | 2 +- 2 files changed, 213 insertions(+), 80 deletions(-) diff --git a/README.md b/README.md index f75cc61..2cb534e 100644 --- a/README.md +++ b/README.md @@ -1,117 +1,250 @@ -# WPetition +# WPetition -a self hostable e petition system to collect signatures for your cause. -this is made to be hosted by the person running the Petition and not as a full on petition platform. -you will still have to export the signatures and submit it to the parliment +a self hostable e-petition system to collect signatures for your cause. +this is made to be hosted by the person running the petition and not as a full on petition platform. +you will still have to export the signatures and submit it to the parliament. for more info check out https://majlis.gov.mv/en/pes/petitions ## why make this -maldives parliment promised the release of a e-petition system powered by efass will be released months ago and then never released it -i said fuck it i want data protection bill so i made this simple signature collection system since the law doesnt care if youre signature is signed digitally or via wet ink. -## how to selfhost this (READ) -first you will need to edit the `sample.Petition.md` file to fit your petition needs -then boot up the api server and upload the file +maldives parliament promised the release of a e-petition system powered by efass will be released months ago and then never released it +i said fuck it i want data protection bill so i made this simple signature collection system since the law doesnt care if your signature is signed digitally or via wet ink. -``` -curl -X 'POST' \ - 'http://localhost:5299/api/Debug/upload-petition' \ - -H 'accept: */*' \ - -H 'Content-Type: multipart/form-data' \ - -F 'file=@my_WPetition.md' -``` +## features -this will create the petition in the DB and will also return a guid you can use +- sign petitions with digital signatures (SVG) +- bilingual support (Dhivehi and English) +- rate limiting (3 signatures per minute per IP) +- duplicate signature prevention (one signature per ID card per petition) +- Cloudflare Turnstile bot protection +- SVG signature security validation (blocks XSS, scripts, external URIs) +- admin dashboard with JWT authentication +- export signatures as printable HTML for parliament submission +- petition approval workflow +- slug-based petition URLs +- MongoDB backend +- Docker support -``` +## tech stack + +| component | tech | +|-----------|------| +| API | ASP.NET Core 9.0 | +| Frontend | React 19 + TypeScript + Vite + TailwindCSS | +| Database | MongoDB | +| Bot protection | Cloudflare Turnstile | +| Auth | JWT (HS256, 24h expiry) | +| Web server | Nginx | +| Container | Docker | + +## how to selfhost this + +### 1. configure appsettings + +update `appsettings.json` (or `appsettings.Production.json` for docker) with your settings: + +```json { - "message": "Petition created successfully", - "petitionId": "13921eaa-aea4-4d74-a0f5-52a81c5e7355", + "Turnstile": { + "SecretKey": "your-turnstile-secret-key" + }, + "PetitionSettings": { + "AllowPetitionCreation": true + }, + "MongoDbSettings": { + "ConnectionString": "mongodb://localhost:27017", + "DatabaseName": "petition_database" + }, + "AdminSettings": { + "Username": "your-admin-username", + "Password": "a-strong-password" + }, + "Jwt": { + "Key": "a-sufficiently-long-secret-key-at-least-32-chars", + "Issuer": "SubmissionApi" + } } ``` -now go back to appsettings.json and set this to false +> **important:** change the default admin credentials and JWT key before deploying to production. -``` - "PetitionSettings": { - "AllowPetitionCreation": false - }, +### 2. create a petition + +head to the frontend and use the petition creation form to submit your petition with all the details (title, body in Dhivehi and English, author info, start date). the form handles Turnstile verification automatically. + +you'll get back a petition ID once it's created: +```json +{ + "message": "Petition created successfully", + "petitionId": "13921eaa-aea4-4d74-a0f5-52a81c5e7355" +} ``` -next you will need to host your frontend but before you do that go to line 80 on index.html and edit this line to point to your api server +### 3. lock down petition creation -``` -baseUrl: 'http://localhost:5299' +go to `appsettings.json` and set this to false: + +```json +"PetitionSettings": { + "AllowPetitionCreation": false +} ``` -now you are ready to roll +restart the server. this prevents anyone from creating new petitions. -go to www.yourdomain.com/index.html?id=[your petition id] and it should all be set +### 4. approve the petition -## nerd shit +login to the admin dashboard and approve your petition, or use the API directly: -for more info check the readme inside the api folder +```bash +# get a token +curl -X POST 'http://localhost:5299/api/auth/login' \ + -H 'Content-Type: application/json' \ + -d '{"username": "your-username", "password": "your-password"}' + +# approve the petition +curl -X PATCH 'http://localhost:5299/api/admin/petitions/{petition_id}/approve' \ + -H 'Authorization: Bearer YOUR_TOKEN' \ + -H 'Content-Type: application/json' \ + -d '{"IsApproved": true}' +``` + +### 5. share + +petitions can be accessed by ID or slug: +- `www.yourdomain.com/?id={petition_id}` +- `www.yourdomain.com/{slug}` + +## docker compose -## docker compose yaml -Deploy Production ```yaml services: - api: - image: git.shihaam.dev/mvdevsunion/wpetition/api:latest - restart: unless-stopped - environment: - - ASPNETCORE_ENVIRONMENT=Production - - ASPNETCORE_URLS=http://+:9755 - - MongoDbSettings__ConnectionString=mongodb://admin:yourpassword@mongodb:27017 - depends_on: - - mongodb - volumes: - - ./data/api/config/appsettings.Production.json:/app/appsettings.Production.json:ro + api: + image: git.shihaam.dev/mvdevsunion/wpetition/api:latest + restart: unless-stopped + environment: + - ASPNETCORE_ENVIRONMENT=Production + - ASPNETCORE_URLS=http://+:9755 + - MongoDbSettings__ConnectionString=mongodb://admin:yourpassword@mongodb:27017 + depends_on: + - mongodb + volumes: + - ./data/api/config/appsettings.Production.json:/app/appsettings.Production.json:ro - frontend: - image: git.shihaam.dev/mvdevsunion/wpetition/frontend:latest - restart: unless-stopped - ports: - - "80:80" - depends_on: - - api - volumes: - - ./data/frontend/index.html:/usr/share/nginx/html/index.html + frontend: + image: git.shihaam.dev/mvdevsunion/wpetition/frontend:latest + restart: unless-stopped + ports: + - "80:80" + depends_on: + - api + volumes: + - ./data/frontend/index.html:/usr/share/nginx/html/index.html - mongodb: - image: mongo:latest - restart: unless-stopped - volumes: - - ./data/mongodb:/data/db - environment: - - MONGO_INITDB_ROOT_USERNAME=admin - - MONGO_INITDB_ROOT_PASSWORD=yourpassword + mongodb: + image: mongo:latest + restart: unless-stopped + volumes: + - ./data/mongodb:/data/db + environment: + - MONGO_INITDB_ROOT_USERNAME=admin + - MONGO_INITDB_ROOT_PASSWORD=yourpassword ``` -## Troubleshooting +## local development -### Common Issues +```bash +# restore dependencies +dotnet restore + +# run the api +dotnet run --project Submission.Api +``` + +the API will be available with Swagger UI at `http://localhost:5xxx/swagger` + +## API overview + +### public endpoints + +| method | endpoint | description | +|--------|----------|-------------| +| `POST` | `/api/Sign/petition/{id}` | sign a petition (rate limited: 3/min) | +| `GET` | `/api/Sign/petition/{id}` | get petition details by ID | +| `GET` | `/api/Sign/petition/by-slug/{slug}` | get petition details by slug | +| `POST` | `/api/Petition/upload-petition-form` | create a new petition | +| `GET` | `/api/Petition/get-latest-petitions` | get 10 most recent approved petitions | + +### admin endpoints (JWT required) + +| method | endpoint | description | +|--------|----------|-------------| +| `POST` | `/api/auth/login` | authenticate and get JWT token | +| `GET` | `/api/admin/petitions` | list all petitions | +| `GET` | `/api/admin/export/{id}` | export signatures as printable HTML | +| `PATCH` | `/api/admin/petitions/{id}/approve` | approve/unapprove a petition | + +for detailed admin API docs, see [ADMIN_API.md](ADMIN_API.md). + +## security + +- **rate limiting** - 3 signatures per minute per IP (fixed window) +- **Cloudflare Turnstile** - bot protection on form submissions +- **SVG validation** - blocks `