comfyProjects
Create projects. Edit names, verification/reset page URLs, exact allowed browser origins, and renewal time limits. Up to 100 projects per developer.
THE VISUAL GUIDE · PAGE 3 OF 3
A place for every app.
A reason for every file.
See how projects stay separate, how the dashboard checks access, and what we keep in the database.
A
Your workspace contains projects. Projects contain users.
YOU · DEVELOPER ACCOUNT
Your ComfyAuth workspace
Ownership records connect your account to the projects you create.
↓ One developer can own many projects
EXAMPLE PROJECT A
Your shop
Its own users, password records, sessions, keys, and settings.
EXAMPLE PROJECT B
Your other app
A separate set of users, password records, sessions, keys, and settings.
Illustrative projects, not live customer data. The same email can belong to both apps as two separate accounts. A project ID identifies the app; it does not prove ownership.
B
Every project action goes through an ownership check.
-
Developer clicks
Create a project, change a setting, view users, or manage a key.
-
Check the session
Read the protected cookie. For changes, require the exact trusted website origin.
-
Check the owner
Look up the project’s owner. For changes, recheck the developer session inside the transaction.
-
Do the operation
Only then read or change the project’s records. Record supported changes in the activity log.
Another developer’s project is returned as “not found.” Creating a project and saving its owner happen together: both succeed, or neither does.
What can I do in the portal?
Users
Search users. Disable or enable an account. Revoke sessions. Disabling also cancels active sessions and email action links. Enabling does not verify an email.
Keys + activity
Create server keys, shown once; store only their hashes. Revoke a key to stop its use. Create up to 20 active keys per project. All active keys and 80 recent revoked keys stay visible. View the latest 100 activity events.
Developer account controls also list/revoke sessions, change password, and log out everywhere. Activity records are retained for 90 days. Team roles and project deletion are not implemented.
C
The database is just labelled drawers.
projectsOne record per application: ID, name, URLs, allowed
origins and session time limits.
↓ Related records carry the project ID
People & ownership
- project_owners
- Which developer owns a project.
- users
- ID, email, optional name, verified/disabled state.
- password_credentials
- The user’s password hash.
Passes & proofs
- sessions
- One stable record per login/device, with the current pass hash, time limits and revocation.
- refresh_tokens
- Current and spent renewal-token hashes. Reusing a spent token ends that session.
- verification_tokens
- Single-use email/reset token hashes.
- api_keys
- Server administration key hashes.
History & housekeeping
- audit_events
- Supported account/project activity.
- email_outbox
- Encrypted messages waiting to be sent.
- rate_limits
- Shared counters that slow repeated requests.
- schema_migrations
- Which database changes have been applied.
Related records use project + user references to prevent accidental cross-project links. Ownership can point only to a developer account in the reserved developer workspace. This is logical separation in one database; database administrators can access all projects.
D
Where does each piece of code live?
cmd/
Starts the server or runs an operator command.
internal/httpapi/
Receives requests and serves the website.
internal/auth/
Account rules, cryptography, and project ownership.
internal/database/
Database connections and numbered schema changes.
internal/mail/ + scheduled/
Message delivery, retries, and cleanup jobs.
scripts/ · docs/ · examples/
Checks, explanations, and an integration example.
Open the complete file-by-file map.
This index includes the source, tests, docs, and deployment files. Local credentials and generated files are deliberately excluded.
| File | Its job |
|---|---|
cmd/comfyauth/main.go | Server lifecycle, graceful shutdown, operator commands, one-time key output |
cmd/api/main.go | Vercel Go entrypoint, production configuration, small connection pool, finite email work |
internal/config/config.go | Environment configuration, verified database TLS requirement, callback/origin validation |
internal/config/config_test.go | Production configuration and unsafe URL tests |
internal/config/limits.go | Configurable public API capacity budgets and conservative defaults |
internal/config/limits_test.go | Public capacity configuration validation and default tests |
internal/database/database.go | Connection limits/timeouts, migration lock, embedded SQL, checksum validation |
internal/database/migrations/001_initial.sql | Tables, indexes, tenant constraints, retention-related fields |
internal/database/migrations/002_developer_portal.sql | Reserved developer workspace and constrained ownership table |
internal/database/migrations/003_session_renewal.sql | Additive renewable-session deadlines and tenant-scoped refresh-token history |
internal/auth/portal_integration_test.go | Cloud database tests for ownership, cookie/CSRF boundaries, revocation, and secret redaction |
internal/auth/key_visibility_test.go | Ensures active keys stay visible and revocable after many rotations |
internal/auth/http_limits_test.go | Database tests for shared-backend capacity, account limits, and error handling |
internal/httpapi/portal_test.go | Embedded page routes, security headers, callback validation |
internal/auth/portal.go | Ownership-scoped project, user, key, and activity operations |
internal/auth/models.go | Public response types, project/principal types, controlled service errors |
internal/auth/crypto.go | Argon2id, random IDs/tokens, hashes, AES-GCM, input normalization |
internal/auth/service.go | Account/session operations, atomic recovery, shared limits, key administration, cleanup |
internal/auth/renewal.go | Opt-in renewable login, atomic refresh rotation and replay revocation |
internal/auth/renewal_integration_test.go | Database tests for rotation, replay, expiry, concurrency and revocation |
internal/auth/crypto_test.go | Password policy/hash, token format, ciphertext tampering and identity-binding tests |
internal/auth/integration_test.go | Isolated PostgreSQL lifecycle, isolation, concurrency, expiry, outbox, and HTTP tests |
internal/httpapi/portal.go | Embedded website, exact-origin cookie authentication, portal HTTP routes |
internal/httpapi/web/guide-system.html | Visual guide 1: people, hosting, request/code flow, deployment |
internal/httpapi/web/guide-accounts.html | Visual guide 2: signup, email, login, identity checks, recovery and revocation |
internal/httpapi/web/guide-workspace.html | Visual guide 3: ownership, portal controls, database and full file map |
internal/httpapi/web/guide.css | Responsive HTML flowcharts, connected boxes, expandable explanations and print layout |
internal/httpapi/web/index.html | Public product website with a visual system overview |
internal/httpapi/web/auth.html | Developer signup, login, verification, recovery screens |
internal/httpapi/web/dashboard.html | Accessible developer console shell and dialogs |
internal/httpapi/web/docs.html | Public quickstart, API reference, and security explanation |
internal/httpapi/web/style.css | Responsive dark visual system, layouts, focus and reduced motion states |
internal/httpapi/web/app.js | Portal forms and real project/user/key/session controls; no persisted browser tokens |
internal/httpapi/web/mark.svg | Local ComfyAuth brand mark and favicon |
internal/httpapi/api.go | Routing, strict JSON, status codes, CORS, bearer credentials, proxy handling |
internal/httpapi/api_test.go | Malformed input, origin, bearer parsing, and proxy spoofing tests |
internal/httpapi/limits.go | Separates public project capacity and account limits from portal IP controls |
internal/mail/mail.go | Bounded SMTP delivery, required production STARTTLS, retries, queue cleanup |
internal/scheduled/handler.go | Inline project-scoped delivery and authenticated, bounded email/cleanup jobs |
internal/scheduled/handler_test.go | Job authorization, finite work, error privacy, and inline response preservation tests |
examples/bff/server.mjs | Customer-owned browser backend; server-held tokens, secure cookies, CSRF checks |
examples/bff/server.test.mjs | Token isolation, CSRF, cookies, safe retry metadata and bounded upstream deadline tests |
scripts/init_dev.py | Private, non-overwriting development secret/config generation |
scripts/portal_ui.test.mjs | Escaping, token removal, final verification password, credentials and secret-dialog tests |
scripts/check_docs.py | Enforces matching README/HTML file maps, local links, HTTP routes and OpenAPI references |
scripts/vercel_build.sh | Requires a separate test database, runs Go checks, builds Vercel binary |
scripts/smoke_vercel.py | HTTPS live health/auth rejection checks and optional test-account login/revocation |
docs/portal.md | Portal setup, ownership boundaries, browser security, limits and full route inventory |
docs/openapi.json | Versioned HTTP API schema, request/response definitions, security schemes |
docs/openapi.go | Embeds the same API contract for the public /openapi.json route |
docs/integration.md | Customer integration and credential-handling guide |
docs/security.md | Threat model, implemented safeguards, limitations, production requirements |
docs/deployment.md | Setup, production environment, testing, migrations, backups and restore |
docs/vercel.md | Vercel Hobby configuration, setup sequence, live verification and retry limitations |
docs/domain-setup.md | Namecheap domain connection, canonical portal origin and separate sender-domain setup |
docs/verification.md | Observed checks and explicit environment blockers |
.github/workflows/ci.yml | Go/PostgreSQL race tests, browser tests, build, and vulnerability scan |
go.mod | Go version and pinned direct dependencies |
go.sum | Dependency checksums verified against Go's signed checksum database |
Dockerfile | Multi-stage nonroot runtime image |
compose.yaml | Local database, migrations, API, and captured email |
vercel.json | Go framework, build gate, function duration, daily cleanup cron |
.vercelignore | Excludes development secrets and local/generated files from uploads |
Makefile | Build/test/format/check shortcuts |
.env.example | Configuration names and placeholders; never real shared secrets |
.gitignore.dockerignore | Exclude local secrets and generated files |
README.md | This living architecture and file map |