{"id":49430309,"url":"https://github.com/bitsocialnet/mintpass","last_synced_at":"2026-04-29T12:00:57.236Z","repository":{"id":298490208,"uuid":"996827262","full_name":"bitsocialnet/mintpass","owner":"bitsocialnet","description":"NFT-based authentication system for Bitsocial communities","archived":false,"fork":false,"pushed_at":"2026-04-18T07:56:15.000Z","size":3183,"stargazers_count":4,"open_issues_count":4,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-04-18T09:37:26.449Z","etag":null,"topics":["anti-spam","anti-sybils","authentication","authentication-middleware","bitsocial","challenge","decentralized","nft","pkc","pkc-js","sms-verification","social-media","social-network","sybil-resistance"],"latest_commit_sha":null,"homepage":"https://mintpass.org","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bitsocialnet.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null},"funding":{"github":"tomcasaburi","patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"lfx_crowdfunding":null,"polar":null,"buy_me_a_coffee":null,"thanks_dev":null,"custom":null}},"created_at":"2025-06-05T14:19:29.000Z","updated_at":"2026-04-18T07:56:19.000Z","dependencies_parsed_at":"2025-07-06T20:31:16.544Z","dependency_job_id":"14d74a47-ffd5-46f5-a1e5-7ac63ffc6a35","html_url":"https://github.com/bitsocialnet/mintpass","commit_stats":null,"previous_names":["plebbitlabs/mintpass","bitsocialhq/mintpass","bitsocialnet/mintpass"],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/bitsocialnet/mintpass","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitsocialnet%2Fmintpass","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitsocialnet%2Fmintpass/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitsocialnet%2Fmintpass/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitsocialnet%2Fmintpass/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bitsocialnet","download_url":"https://codeload.github.com/bitsocialnet/mintpass/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitsocialnet%2Fmintpass/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32424499,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-29T11:26:24.167Z","status":"ssl_error","status_checked_at":"2026-04-29T11:26:13.719Z","response_time":110,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["anti-spam","anti-sybils","authentication","authentication-middleware","bitsocial","challenge","decentralized","nft","pkc","pkc-js","sms-verification","social-media","social-network","sybil-resistance"],"created_at":"2026-04-29T12:00:41.279Z","updated_at":"2026-04-29T12:00:57.224Z","avatar_url":"https://github.com/bitsocialnet.png","language":"TypeScript","funding_links":["https://github.com/sponsors/tomcasaburi"],"categories":[],"sub_categories":[],"readme":"[![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](http://commitizen.github.io/cz-cli/)\n\n# MintPass - NFT Authentication Middleware for Bitsocial\n\n\u003cimg src=\"public/mintpass.png\" alt=\"MintPass Logo\" width=\"90\" align=\"left\" /\u003e\n\nMintPass is an NFT-based authentication system that provides verified identity proofs for decentralized communities. It began as an anti‑spam challenge for Bitsocial communities, and it works equally well for other protocols and social applications. Users mint a non‑transferable verification NFT (e.g., after SMS OTP) that communities can check to reduce sybil attacks, such as fake upvotes/downvotes, fake conversations, and users evading bans.\n\n\u003cbr clear=\"left\" /\u003e\n\n## How people use MintPass\n\n1) Visit `mintpass.org/request`, enter a phone number, and complete SMS OTP.\n2) MintPass mints an NFT (on testnet in this reference deployment) to your wallet or records an equivalent “verified” state when on‑chain minting is disabled.\n3) Communities (e.g., Bitsocial communities) check ownership of the NFT to treat you as authenticated for anti‑spam.\n\nThe request form looks like this:\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"public/mintpass-request.jpg\" alt=\"MintPass request form screenshot\" width=\"862\" /\u003e\n\u003c/p\u003e\n\n## What is Bitsocial?\n\nBitsocial is p2p and decentralized social media protocol built completely with IPFS/IPNS/pubsub. It doesn't use any central server, central database, public HTTP endpoint or DNS, it is pure peer to peer (except for the web client that can't join a P2P swarm directly, web clients use interchangeable HTTP providers). It allows community owners to retain full ownership over their community. Whitepaper [here](https://github.com/pkc/whitepaper/discussions/2).\n\nMintPass integrates as a challenge so Bitsocial communities can distinguish real users and limit abuse without central servers. Because the artifact is an NFT, other decentralized apps can use the same credential to authenticate users.\n\n## Project Structure\n\n```\nmintpass/\n├── contracts/   # MintPassV1 smart contract and tooling\n├── challenge/   # Bitsocial challenge implementation (“mintpass”)\n├── web/         # Next.js website + API (mintpass.org)\n├── docs/        # Documentation and specifications\n├── tests/       # Cross‑component integration tests\n└── scripts/     # Deployment and utilities\n```\n\n### Subprojects\n\n- `contracts/`: Solidity contracts (MintPassV1). Versioned, role‑based minting, token types per NFT (type 0 = SMS). See `contracts/README.md`.\n- `challenge/`: The Bitsocial challenge that checks for a MintPass NFT and applies additional rules (e.g., transfer cooldowns) to resist sybils.\n- `web/`: The user‑facing site and serverless backend. Sends SMS codes, verifies OTP, and mints or records successful verification. See `web/README.md`.\n\n## Privacy and anti‑sybil design (high level)\n\n- Short‑lived operational data (OTP codes, verification markers, rate‑limit state) stored in Redis with TTLs.\n- Persistent “mint association” between wallet and phone to prevent duplicate mints.\n- Optional IP reputation (VPN/proxy) and phone‑risk checks, optional geoblocking, and per‑IP cooldowns.\n- Secrets live only in environment variables; logs avoid PII and never include OTPs or private keys.\n\n## Getting started\n\n1. Run `nvm install \u0026\u0026 nvm use`\n2. Run `corepack enable` once per machine so `yarn` resolves to the pinned Yarn 4 release\n3. Use plain `yarn install`, `yarn build`, and `yarn test`\n\n- Contracts: `cd contracts \u0026\u0026 yarn install \u0026\u0026 yarn test`\n- Challenge: `cd challenge \u0026\u0026 yarn install \u0026\u0026 yarn test`\n- Web: `cd web \u0026\u0026 yarn install \u0026\u0026 yarn dev` then open `https://mintpass.localhost/request`\n\n## Using MintPass in your community\n\nCommunity owners add the MintPass challenge to their community settings. When enabled, every publication (post, reply, vote) requires the author to hold a valid MintPass NFT. The challenge is published as [`@bitsocial/mintpass-challenge`](https://www.npmjs.com/package/@bitsocial/mintpass-challenge) on npm.\n\n### With pkc-js over RPC\n\nIf your RPC server is already running, first install the challenge on the server:\n\n```bash\nbitsocial challenge install @bitsocial/mintpass-challenge\n```\n\nThen from your RPC client, connect and set the challenge on your community by name — no npm install or challenge registration needed on the client side:\n\n```ts\nimport PKC from \"@pkcprotocol/pkc-js\";\n\nconst pkc = await PKC({\n  pkcRpcClientsOptions: [\"ws://localhost:9138\"]\n});\n\nconst community = await pkc.createCommunity({ address: \"your-community-address.bso\" });\n\nawait community.edit({\n  settings: {\n    challenges: [\n      {\n        name: \"@bitsocial/mintpass-challenge\",\n        options: {\n          chainTicker: \"base\",\n          contractAddress: \"0x13d41d6B8EA5C86096bb7a94C3557FCF184491b9\",\n          requiredTokenType: \"0\",\n          transferCooldownSeconds: \"604800\"\n        }\n      }\n    ]\n  }\n});\n```\n\n### With pkc-js (TypeScript)\n\nInstall the challenge package:\n\n```bash\nnpm install @bitsocial/mintpass-challenge\n```\n\nRegister the challenge and configure your community:\n\n```typescript\nimport PKC from '@pkcprotocol/pkc-js'\nimport mintpassChallenge from '@bitsocial/mintpass-challenge'\n\n// Register the challenge so it can be referenced by name\nPKC.challenges['@bitsocial/mintpass-challenge'] = mintpassChallenge\n\nconst pkc = await PKC({ /* your pkc options */ })\nconst community = await pkc.createCommunity({ address: 'your-community.bso' })\n\nawait community.edit({\n  settings: {\n    challenges: [{\n      name: '@bitsocial/mintpass-challenge',\n      options: {\n        chainTicker: 'base',\n        contractAddress: '0x13d41d6B8EA5C86096bb7a94C3557FCF184491b9',\n        requiredTokenType: '0',\n        bindToFirstAuthor: 'true',\n        transferCooldownSeconds: '604800',\n      }\n    }]\n  }\n})\n```\n\n#### Challenge options\n\nAll option values must be strings (pkc-js challenge convention).\n\n| Option | Default | Description |\n|--------|---------|-------------|\n| `chainTicker` | `\"base\"` | Chain where MintPass is deployed |\n| `contractAddress` | Base Sepolia default | Contract address (auto-detected for supported chains) |\n| `requiredTokenType` | `\"0\"` | Token type (0 = SMS, 1 = Email) |\n| `bindToFirstAuthor` | `\"true\"` | Bind NFT to first author per community |\n| `transferCooldownSeconds` | `\"604800\"` | Cooldown after NFT transfer (1 week) |\n| `error` | Default message | Custom error (`{authorAddress}` placeholder supported) |\n| `rpcUrl` | Chain default | Optional custom RPC URL |\n\n### With bitsocial-cli\n\nInstall the challenge package:\n\n```bash\nbitsocial challenge install @bitsocial/mintpass-challenge\n```\n\nEdit your community to use the challenge:\n\n```bash\nbitsocial community edit your-community.bso \\\n  '--settings.challenges[0].name' @bitsocial/mintpass-challenge \\\n  '--settings.challenges[0].options.chainTicker' base \\\n  '--settings.challenges[0].options.contractAddress' '0x13d41d6B8EA5C86096bb7a94C3557FCF184491b9' \\\n  '--settings.challenges[0].options.requiredTokenType' '0' \\\n  '--settings.challenges[0].options.bindToFirstAuthor' 'true' \\\n  '--settings.challenges[0].options.transferCooldownSeconds' '604800'\n```\n\nSee the [bitsocial-cli documentation](https://github.com/bitsocial/bitsocial-cli) for full CLI reference.\n\n## Where MintPass is useful\n\nWhile designed for Bitsocial, any decentralized or serverless social app can use MintPass NFTs as a lightweight proof‑of‑personhood. Apps only need to check ownership of a token type (e.g., type 0 for SMS) to gate actions or increase trust in votes and reports.\n\n## Roadmap and considerations\n\nWe plan to support multiple authentication methods alongside SMS OTP to fit different threat models and UX constraints:\n- Add a “pay‑to‑mint” option with a small fee that is high enough to deter bulk purchases but low enough for regular users.\n- Add additional human‑verification signals (e.g., email, government‑backed KYC providers, or proofs such as biometrics/world‑ID systems) when they can be integrated without compromising decentralization goals.\n- Expand admin tooling, heuristics, and optional device signals to further reduce abuse.\n\nThese items are exploratory; concrete work will land incrementally and stay configurable so communities can choose what they trust.\n\n## Technology Stack\n\n- **Smart Contracts**: Solidity, Hardhat/Foundry\n- **Website**: Next.js, React, Ethereum (ethers)\n- **Challenges**: TypeScript, pkc-js integration\n- **Deployment**: Base network (L2)\n\n## License\n\nMIT License — see [LICENSE](LICENSE).\n\nOpen source and commercial‑friendly. A hosted version is available at [mintpass.org](https://mintpass.org).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbitsocialnet%2Fmintpass","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbitsocialnet%2Fmintpass","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbitsocialnet%2Fmintpass/lists"}