diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 0000000..a12b633 --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,3 @@ +# Default ownership for repository changes. +# Keep this file aligned with the maintainers who can review security and release changes. +* @eimyroot diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..e51776c --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,30 @@ +## Summary + + + +## Scope + +- Included: +- Intentionally excluded: + +## Verification + + + +## Risk and security + +- Risk class: documentation / internal / behavior / security / release +- Trust, data, compatibility, and operational impact: +- Secrets or personal data introduced: no + +## Rollback + + + +## Evidence checklist + +- [ ] The diff is focused and reviewed. +- [ ] Tests or checks cover the changed behavior. +- [ ] Documentation matches implemented reality. +- [ ] No generated runtime state, secrets, or personal data are committed. +- [ ] Required owner approval is identified. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..e3fd5db --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,28 @@ +# Contributing to TICTOE + +Thank you for helping improve TICTOE. Keep changes focused, reviewable, tested, and reversible. + +## Workflow + +1. Open or reference an issue for material behavior changes. +2. Create a focused branch from the repository's default branch. +3. Make the smallest complete change that solves the stated problem. +4. Add or update tests and documentation. +5. Run the repository's documented verification commands. +6. Open a pull request and include risk, evidence, and rollback notes. + +## Pull request standard + +A pull request must state: + +- what changed and why; +- what was intentionally left out; +- verification commands and results; +- security, compatibility, data, and operational risks; +- rollback or safe-disable procedure. + +Do not commit secrets, personal data, generated runtime state, local databases, or unverifiable claims. A green check proves only the scope exercised by that check. + +## Governance + +Maintainer review is required. Security-sensitive, release, authorization, persistence, billing, and production-effect changes require explicit owner approval and must fail closed when required evidence is missing. diff --git a/README.md b/README.md index a8f6888..e01bd44 100644 --- a/README.md +++ b/README.md @@ -1,44 +1,108 @@ -# T3A // Private Real Multiplayer Arena +
-Password-protected, server-authoritative multiplayer proof-of-concept for Team Tic-Tac-Toe Arena. +# T3A -## Render deployment +### Private, server-authoritative multiplayer arena -Use this repository as a Render **Web Service**. +A compact real-time Team Tic-Tac-Toe proof of concept for invited testers. -- Runtime: Node -- Branch: `main` -- Build command: `npm run check` -- Start command: `npm start` -- Health check: `/health` -- Instance: Free (demo only) +![Node.js](https://img.shields.io/badge/Node.js-%3E%3D22-339933?logo=node.js&logoColor=white) +![Runtime](https://img.shields.io/badge/runtime-Node-111827) +![Transport](https://img.shields.io/badge/realtime-WebSocket-7C3AED) +![Status](https://img.shields.io/badge/status-private%20POC-F59E0B) -Required secret environment variable: +
-- `T3A_ACCESS_PASSWORD` — password shared with invited testers +--- -Recommended secret: +## What it demonstrates + +- password-gated access for invited testers; +- signed `HttpOnly` session cookies; +- authenticated WebSocket upgrades; +- server-authoritative match state; +- rate-limited login attempts; +- deterministic syntax and smoke verification; +- one-command Render deployment configuration. + +## Runtime flow + +```text +browser + │ password login + ▼ +Node HTTP server + │ signed session + ▼ +authenticated WebSocket + │ server-authoritative events + ▼ +in-memory match state +``` -- `T3A_SESSION_SECRET` — Render can generate this automatically when using `render.yaml` +The browser is a client, not the authority for authentication or match state. -Never commit either secret to Git. +## Quick start -## Local run +Requirements: Node.js 22 or newer. ```bash -T3A_ACCESS_PASSWORD='change-me' T3A_SESSION_SECRET='local-dev-secret-change-me' npm start +npm install +T3A_ACCESS_PASSWORD='change-me' \ +T3A_SESSION_SECRET='local-dev-secret-change-me' \ +npm start ``` Open `http://localhost:8787`. -## Security model +Run the complete repository verification: + +```bash +npm run verify +``` + +## Render deployment + +Create a Render **Web Service** from this repository. + +| Setting | Value | +|---|---| +| Runtime | Node | +| Branch | `main` | +| Build command | `npm run check` | +| Start command | `npm start` | +| Health check | `/health` | +| Instance | Free, demo only | + +Required secret: + +- `T3A_ACCESS_PASSWORD` — password shared with invited testers. + +Recommended secret: + +- `T3A_SESSION_SECRET` — a strong independently generated session-signing secret. + +Never commit either value. + +## Security boundary + +- access passwords are verified on the server; +- successful login creates a signed `HttpOnly` session cookie; +- WebSocket upgrades require a valid authenticated session; +- login attempts are rate limited in memory; +- secrets are supplied through environment variables, never frontend JavaScript. + +Report suspected vulnerabilities according to [SECURITY.md](SECURITY.md). + +## Known limitations + +T3A is a private proof of concept, not production infrastructure. -- Access password is verified on the server. -- Successful login creates a signed `HttpOnly` session cookie. -- WebSocket upgrades require a valid authenticated session. -- Login attempts are rate limited in memory. -- Secrets are supplied through environment variables, not frontend JavaScript. +- state is held in memory and disappears after restart; +- a free hosting instance may spin down; +- in-memory rate limiting is not shared across replicas; +- there is no production persistence, matchmaking, moderation, or availability guarantee. -## Scope +## Contributing -This is a private demo/POC, not production infrastructure. Match state is in memory and is lost when the service restarts or a free Render instance spins down. +Review [CONTRIBUTING.md](CONTRIBUTING.md) before proposing a change. Pull requests must include verification evidence, risk notes, and a rollback path. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..2f3f153 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,23 @@ +# Security Policy + +## Supported scope + +Security fixes are maintained on the current default branch while TICTOE remains pre-release. Repository visibility or a passing CI run is not a production-readiness guarantee. + +## Reporting a vulnerability + +Do not disclose vulnerabilities, credentials, personal data, private URLs, or exploit details in public issues or pull requests. Use GitHub private vulnerability reporting when enabled. If it is unavailable, open a public issue requesting a private contact without including sensitive details. + +Include the affected revision, component, prerequisites, minimal reproduction, impact, expected safe behavior, and a suggested mitigation when known. + +## Security baseline + +- never commit credentials or production data; +- keep privileged decisions and authorization server-side; +- apply least privilege and deny-by-default behavior; +- validate untrusted input and bound resource use; +- preserve auditable evidence without logging secrets; +- treat missing or unverifiable security evidence as a failure, not success; +- rotate exposed credentials even if the committed file is later removed. + +No response-time or remediation SLA is promised while the project remains pre-release.