Thank you for your interest in contributing to ProtocolSoup! This project aims to make identity protocols approachable through hands-on experimentation—and contributions from the community are essential to that mission.

• Getting Started
• Development Setup
• Making Contributions
• Pull Request Process
• Coding Standards
• Adding New Protocols
• Getting Help

• Good First Issues: Look for issues labeled good first issue-these are scoped for newcomers
• Help Wanted: Issues labeled help wanted are ready for contribution
• Protocol Requests: Check for new protocol proposals if you have domain expertise

Before starting work on a significant change, please open an issue to discuss your approach. This prevents duplicate effort and ensures alignment with project direction.

Comment on the issue to let maintainers know you're working on it. If you don't see activity on an issue for two weeks after someone claims it, feel free to pick it up.

# Clone the repository
git clone https://github.com/ParleSec/ProtocolSoup.git
cd ProtocolSoup

# Backend setup
cd backend
go mod tidy
go build ./cmd/server

# Frontend setup
cd ../frontend
npm install

Option 1: Split development (recommended for frontend work)

# Terminal 1: Start backend
cd backend
go run ./cmd/server

# Terminal 2: Start frontend dev server
cd frontend
npm run dev

The frontend runs at http://localhost:3000 and proxies API requests to the backend at http://localhost:8080.

Option 2: Docker Compose (full stack)

cd docker
docker-compose -f docker-compose.dev.yml up

Option 3: With SPIFFE/SPIRE

cd docker
docker-compose -f docker-compose.yml -f docker-compose.spiffe.yml up

1. Open http://localhost:3000 (or http://localhost:8080 for Docker)
2. Navigate to Looking Glass
3. Run an OAuth 2.0 Authorization Code flow
4. Verify you see real-time events in the timeline

This project uses the Developer Certificate of Origin to ensure contributions can be legally distributed under our Apache 2.0 license.

You must sign off on every commit. This certifies that you wrote the code or have the right to submit it:

git commit -s -m "Add feature X"

This adds a Signed-off-by: Your Name <[email protected]> line to your commit.

Configure Git to sign off automatically:

git config --global user.name "Your Name"
git config --global user.email "[email protected]"

If you forget to sign off, amend your commit:

git commit --amend -s

For multiple commits:

git rebase HEAD~N --signoff  # where N is the number of commits

Use descriptive branch names:

• feature/webauthn-support
• fix/oauth-pkce-validation
• docs/spiffe-setup-guide

Write clear, descriptive commit messages:

Add PKCE validation to OAuth 2.0 token endpoint

- Implement code_verifier validation against code_challenge
- Support S256 and plain challenge methods
- Add test coverage for PKCE edge cases

Signed-off-by: Your Name <[email protected]>

1. Fork and branch: Create a feature branch from main
2. Make changes: Implement your feature or fix
3. Test locally: Ensure all tests pass
4. Sign commits: All commits must include DCO sign-off
5. Open PR: Submit against main with a clear description
6. Respond to feedback: Address review comments promptly

Before submitting, verify:

• All commits are signed off (git log --show-signature)
• Backend tests pass (go test ./...)
• Frontend lints pass (npm run lint)
• Code follows project style guidelines
• Documentation is updated if needed
• No secrets or credentials are committed
• PR description explains the change and motivation

• A maintainer will review your PR within a few days
• CI checks must pass before merge
• At least one maintainer approval is required
• Squash-merge is used for most contributions

• Follow Effective Go conventions
• Run golangci-lint before committing
• Use meaningful variable and function names
• Add comments for exported functions and types
• Handle errors explicitly-don't ignore them

# Install linter
go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest

# Run linter
golangci-lint run ./...

• Follow the existing ESLint configuration
• Use TypeScript strict mode
• Prefer functional components with hooks
• Use Tailwind CSS for styling (no separate CSS files)
• Keep components focused and composable

# Run linter
npm run lint

# Type check
npx tsc --noEmit

• Backend: Add tests for new endpoints and business logic
• Protocol implementations: Include tests for happy path and error cases

# Backend tests
cd backend && go test ./... -v

ProtocolSoup uses a plugin architecture for protocols. See ADDING_PROTOCOLS.md for the complete guide.

1. Create plugin directory: backend/internal/protocols/newprotocol/
2. Implement the ProtocolPlugin interface in plugin.go
3. Add HTTP handlers in handlers.go
4. Register in cmd/server/main.go
5. Create frontend components in frontend/src/components/protocols/newprotocol/
6. Add Looking Glass integration for real-time visualization

When proposing a new protocol:

1. Open an issue first describing the protocol and its value to practitioners
2. Reference the RFC(s) or specifications you're implementing
3. Start with core flows before edge cases
4. Emit Looking Glass events for all significant operations-visibility is our differentiator

Understanding the codebase helps you contribute effectively:

ProtocolSoup/
├── backend/
│   ├── cmd/server/          # Application entry point
│   └── internal/
│       ├── core/            # HTTP server, config, middleware
│       ├── crypto/          # JWT/JWK key management
│       ├── lookingglass/    # Real-time protocol inspection
│       ├── mockidp/         # Mock identity provider
│       ├── plugin/          # Plugin system interfaces
│       └── protocols/       # Protocol implementations
├── frontend/
│   └── src/
│       ├── components/      # Shared UI components
│       ├── lookingglass/    # Flow executors & visualization
│       ├── pages/           # Route pages
│       └── protocols/       # Protocol registry
└── docker/                  # Container configurations

See ARCHITECTURE.md for detailed system design documentation.

• Bugs/Questions: File a GitHub Issue or reach out to me anywhere you can find me :)
• Security issues: See SECURITY.md for responsible disclosure

Thank you for contributing to ProtocolSoup! Your work helps practitioners understand and implement identity protocols correctly.