WAIT — Slowing — last commit 7mo ago

• Last commit 7mo ago
• 11 active contributors
• AGPL-3.0 licensed
• CI configured
• Tests present
• ⚠ Slowing — last commit 7mo ago
• ⚠ Single-maintainer risk — top contributor 85% of recent commits
• ⚠ AGPL-3.0 is copyleft — check downstream compatibility
• ⚠ Scorecard: marked unmaintained (0/10)

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests + OpenSSF Scorecard}

CodiMD is a self-hosted, real-time collaborative markdown editor built on HackMD's open-source codebase. It enables teams to write, edit, and present markdown documents simultaneously across multiple users with WebSocket-based synchronization, supporting slide mode and HTML rendering while maintaining full data ownership on user-controlled servers. Monolithic Node.js/Express architecture: root-level app.js serves as entry point, lib/auth/* contains pluggable authentication strategies, webpack bundles frontend assets (JavaScript 654KB, CSS 84KB, EJS templates for server-side rendering), deployments/ contains Docker/Heroku tooling, and config.js centralizes environment-based configuration. Database state managed via Sequelize with migrations.

DevOps engineers, community maintainers, and technical teams who need a self-hosted alternative to cloud-based collaborative markdown tools (like HackMD.io), requiring full control over their data and the ability to customize authentication (GitHub, GitLab, Google, Bitbucket, email-based, OpenID) and storage backends (S3, Azure, local).

Production-ready and actively maintained. Version 2.6.0 with AGPL-3.0 licensing, comprehensive test coverage via mocha/nyc, Docker support, CI/CD pipelines (GitHub Actions), and Sequelize ORM for multiple database backends. Last activity visible in GitHub workflows and deployment configurations suggests ongoing maintenance.

Moderate risk: large monolithic codebase (654KB JavaScript) with broad third-party auth integrations requiring careful credential management, dependency on Sequelize migrations (must run on startup via 'sequelize db:migrate'), and no visible lock file in the top-level structure suggests npm dependency drift potential. Single auth strategy failure could block access entirely.

Active Docker/Kubernetes deployment focus visible in .github/workflows (build.yml, push-image.yml, check-release.yml), recent devcontainer setup for VS Code remote development, and ongoing CI/CD refinement. Build system uses webpack in dev (with --watch) and production modes.

git clone https://github.com/hackmdio/codimd.git && cd codimd && npm install && npm run dev (for development with webpack watch) or npm start (which runs Sequelize migrations then node app.js). Requires Node.js version specified in .nvmrc.

Daily commands: Development: npm run dev (starts webpack with --watch and colors), then run node app.js in another terminal. Production: npm run build && npm start (which runs migrations then app.js). Docker: docker-compose -f deployments/docker-compose.yml up. Heroku: git push heroku and let bin/heroku_start.sh + heroku-postbuild script handle it.

• app.js — Main application entry point that initializes Express server, middleware, and routes for the collaborative markdown platform.
• lib/config/index.js — Central configuration loader that merges environment variables, defaults, and docker secrets—critical for understanding how CodiMD adapts to different deployment environments.
• lib/auth/index.js — Authentication orchestrator that coordinates 10+ auth strategies (OAuth2, SAML, LDAP, email, etc.); essential for understanding user identity flows.
• lib/history/index.js — Handles note revision history and authorship tracking, core to the collaborative editing experience.
• lib/imageRouter/index.js — Abstraction layer for multiple image backends (S3, Imgur, Minio, filesystem); critical for content storage strategy.
• lib/csp.js — Content Security Policy configuration that protects against XSS and injection attacks in a collaborative markdown editor.
• config.js — Configuration schema and validation; every deployment configuration question flows through here.

Add a New Authentication Strategy

1. Create strategy folder: lib/auth/newprovider/index.js with passport strategy configuration (lib/auth/newprovider/index.js)
2. Export strategy module that returns (app, config) => passport.use(...) (lib/auth/newprovider/index.js)
3. Register the strategy in the auth router switch statement (lib/auth/index.js)
4. Add configuration schema fields to config.js for the new provider (config.js)
5. Add environment variable mappings in lib/config/environment.js (lib/config/environment.js)

Add a New Image Storage Backend

1. Create backend implementation: lib/imageRouter/newbackend.js exporting upload(image) and getUrl(path) functions (lib/imageRouter/newbackend.js)
2. Add require() and case clause in the imageRouter switch (lib/imageRouter/index.js)
3. Add configuration options to config.js for the new backend credentials/settings (config.js)
4. Document the backend in environment variable mappings (lib/config/default.js)

Add a New Configuration Option

1. Define the option schema in config.js with type, default, and description (config.js)
2. Add environment variable mapping in lib/config/environment.js (lib/config/environment.js)
3. Add default value in lib/config/default.js if non-obvious (lib/config/default.js)
4. Use the config value in app.js or relevant module via require('config') (app.js)

• Express.js — Lightweight, battle-tested Node.js framework for routing and middleware; ideal for real-time collaborative apps with WebSocket support.
• Sequelize ORM — Abstracts multiple databases (MySQL, PostgreSQL, SQLite) through migrations; critical for supporting diverse deployments without code changes.
• Passport.js — Industry-standard auth middleware supporting 500+ strategies; enables pluggable OAuth, SAML, LDAP, and local authentication without reinventing security.
• WebSocket (Socket.io implied) — Real-time bidirectional communication for collaborative editing; required to push note changes to multiple connected clients instantly.
• Multiple Image Backends (S3, Minio, Imgur, Filesystem) — Abstraction strategy allows deployment flexibility: cloud-native orgs use S3, on-prem use Minio/filesystem, avoiding vendor lock-in.

• Multi-strategy authentication (OAuth2, SAML, LDAP, email, social) vs. single SSO

  • Why: Serve diverse user bases: enterprises want SAML, startups want GitHub OAuth, self-hosted want email or LDAP.
  • Consequence: Higher auth codebase complexity and more test coverage needed; but enables market fit across segments.

• Support multiple database backends (MySQL, PostgreSQL, SQLite) via Sequelize migrations

  • Why: Maximize deployment flexibility across different infrastructure choices.
  • Consequence: Cannot use database-specific features; must test all three backends in CI; slightly slower queries due to ORM abstraction layer.

• Image storage abstraction with 5+ pluggable backends

  • Why: Avoid vendor lock-in and support self-hosted, cloud, and hybrid deployments.
  • Consequence: More code paths to maintain; each backend has unique error modes and latency profiles; users must correctly configure their choice.

• Session-based authentication (cookies) in app.js

  • Why: Simpler for browser-based collaborative UX; stateful sessions easier to revoke globally on logout.
  • Consequence: Horizontal scaling requires shared session store (Redis/Database); token-based auth would scale easier but complicates real-time sync.

• Not a real-time database: CodiMD does not persist collaborative edits to a shared oplog; it reads/writes committed note state to Sequelize ORM only.
• Not JWT-native: CodiMD uses session cookies by default, not bearer tokens; API token support exists but is secondary.
• Not multi-tenant by design: Single codimd instance serves one logical workspace; no built-in account isolation or namespace partitioning.
• Not mobile-optimized at server level: No dedicated mobile API endpoints or mobile-specific sync logic; relies on responsive frontend and standard HTTP.

Sequelize db:migrate runs on every app startup (npm start) — must have DB accessible immediately or app crashes silently. Auth callback URLs must exactly match OAuth provider configuration (GitHub, GitLab, etc.) or login fails cryptically. Config.js environment variables are loaded at start time; changes require restart. Webpack dev mode requires separate process (npm run dev) and won't auto-update app.js changes. EJS templates are served server-side; client-side changes in /public need webpack rebuild. .sequelizerc.example is an example — actual .sequelizerc must exist and reference config.js for migrations.

• Operational Transformation (OT) / CRDT — CodiMD's real-time collaborative editing requires conflict resolution when multiple users edit the same document simultaneously; understanding whether it uses OT (like Google Docs) or CRDT determines how merge conflicts are handled
• OAuth2 / OpenID Connect — Authentication backbone supporting GitHub, GitLab, Google, Bitbucket, and custom OpenID providers; misconfigured scopes or callback URLs are the most common deployment issues
• Sequelize ORM Migrations — Database schema changes are applied via Sequelize migrations on every app startup (npm start); understanding migration creation and rollback is critical for schema modifications
• Server-Sent Events (SSE) / WebSocket Sync — Collaborative document updates must propagate to all connected clients in real-time; CodiMD likely uses WebSocket or SSE for this bidirectional communication
• Webpack Module Bundling — Frontend code (654KB JavaScript) is bundled separately for dev (npm run dev with --watch) and production (npm run build); Babel transpilation means ES6+ source requires understanding build pipeline modifications
• Markdown AST Parsing (@hackmd/meta-marked) — CodiMD dependency on custom meta-marked fork suggests custom markdown parsing and frontmatter handling; extending markdown syntax requires modifying the parser
• Container Orchestration / Docker Compose — deployments/docker-compose.yml and GitHub Actions workflows show Docker-first deployment approach; understanding multi-container networking and environment variable passing is essential for DevOps changes

• joplin/joplin — Markdown note-taking app with real-time sync and self-hosting; different architecture (Electron + web frontend) but same user problem domain
• ProseMirror/prosemirror — Underlying collaborative editing engine library; CodiMD could benefit from ProseMirror's CRDT-based conflict resolution instead of custom sync logic
• outline/outline — Team wiki built with real-time collaboration and OAuth integrations; architectural parallel for understanding shared auth and sync patterns
• mattermost/mattermost-server — Mentioned in dependencies (@mattermost/client); CodiMD integrates with Mattermost for notifications and embedding
• sequelize/sequelize — CodiMD's ORM for database abstraction; understanding Sequelize migrations and models is essential for schema changes

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for lib/auth modules

The repo has 11 authentication strategies (GitHub, GitLab, Google, OAuth2, SAML, LDAP, etc.) in lib/auth/* but the test directory structure is not shown. Given the critical security implications of auth, these modules likely lack adequate test coverage. A new contributor could add unit tests for at least 3 auth strategies (e.g., OAuth2 strategy, SAML index, OpenID index) to verify token handling, user serialization, and edge cases.

• [ ] Create test/lib/auth/oauth2/ directory with tests for lib/auth/oauth2/strategy.js
• [ ] Create test/lib/auth/utils.test.js for lib/auth/utils.js helper functions
• [ ] Add tests covering token validation, user profile parsing, and error handling for at least one OAuth provider
• [ ] Run 'npm run coverage' to measure improvement in auth module coverage
• [ ] Ensure mocha tests follow existing patterns and pass with 'npm run mocha'

Add GitHub Actions workflow for dependency security scanning

The repo has .github/workflows/ (build.yml, check-release.yml, push-image.yml) but likely lacks automated dependency vulnerability scanning. With 50+ dependencies listed and security-critical features (auth, storage), adding a Dependabot or npm audit workflow would catch vulnerable package versions early and is a high-value CI addition.

• [ ] Create .github/workflows/security-audit.yml with npm audit or Dependabot configuration
• [ ] Configure the workflow to run on push to develop/main and on pull requests
• [ ] Add step to check for critical/high vulnerabilities in package.json dependencies
• [ ] Include notification/failure conditions for vulnerable dependencies
• [ ] Test the workflow by temporarily downgrading a package to a known vulnerable version

Add integration tests for lib/config modules with environment variables

The repo has lib/config/environment.js, lib/config/dockerSecret.js, lib/config/enum.js, and lib/config/default.js, which handle critical runtime configuration from multiple sources (env vars, Docker secrets, defaults). Testing these edge cases (missing vars, invalid values, precedence) is essential for deployment reliability but appears to be missing.

• [ ] Create test/lib/config/ directory with test files for each config module
• [ ] Add test/lib/config/environment.test.js testing environment variable parsing with various cases (missing, empty, invalid types)
• [ ] Add test/lib/config/dockerSecret.test.js mocking Docker secret file reads and error handling
• [ ] Test config precedence (e.g., environment.js overriding default.js) in test/lib/config/index.test.js
• [ ] Run 'npm run coverage:ci' and verify config modules reach >80% coverage

• Add missing test coverage for lib/auth/dropbox/index.js and lib/auth/bitbucket/index.js — currently only auth/github has visible test patterns. Create test/auth/dropbox.test.js and test/auth/bitbucket.test.js files mirroring the GitHub auth test structure.
• Document configuration options for all OAuth providers in lib/auth/* in CONTRIBUTING.md or create AUTHENTICATION.md — currently no file explains required env vars for each strategy (e.g., GITHUB_CLIENT_ID, GITLAB_CLIENT_ID, GOOGLE_CLIENT_ID, etc.). List required and optional environment variables per provider.
• Add GitHub Actions workflow step to test the manual deployment path (bin/setup) — currently CI only tests npm start path. Create .github/workflows/manual-deploy-test.yml that runs bin/setup in a test environment to catch setup script bit-rot.

• High · Outdated and Vulnerable Dependencies — package.json, all dependencies section. The package.json shows multiple outdated dependencies with known vulnerabilities: @aws-sdk/client-s3-node v0.1.0-preview.2 (preview version), azure-storage v2.10.3 (deprecated), and @mattermost/client v9.2.0. Preview/alpha versions should not be used in production. Azure Storage SDK v2.x reached end-of-life and has known security issues. Regular dependency audits reveal multiple CVEs in the dependency tree. Fix: 1. Upgrade all dependencies to latest stable versions. 2. Replace azure-storage with @azure/storage-blob v12+. 3. Use @aws-sdk/client-s3 instead of preview version. 4. Run 'npm audit' and fix all critical/high severity issues. 5. Implement automated dependency scanning in CI/CD pipeline.
• High · Missing CSRF Protection Configuration — app.js, lib/auth/index.js. The codebase shows Express.js application (app.js) with multiple authentication providers (OAuth, SAML, OpenID, etc.) but no visible CSRF token middleware in the file structure. This could expose state-changing operations to CSRF attacks. Fix: 1. Implement CSRF middleware (express-csurf or similar). 2. Ensure all state-changing operations (POST, PUT, DELETE) validate CSRF tokens. 3. Configure SameSite cookie attributes to 'Strict' or 'Lax'. 4. Use double-submit cookie pattern as fallback.
• High · Multiple Authentication Providers Without Unified Validation — lib/auth/ directory (all provider implementations). The auth module supports 11+ different authentication strategies (GitHub, Google, Facebook, SAML, LDAP, OAuth2, etc.) across separate directories. Without centralized validation logic, there's high risk of authentication bypass, improper token handling, or session fixation vulnerabilities in individual providers. Fix: 1. Implement centralized authentication validation middleware. 2. Audit each authentication provider for proper token validation and expiration handling. 3. Enforce consistent session management across all providers. 4. Add security tests for token manipulation and session hijacking scenarios.
• High · Potential SQL Injection via Sequelize ORM — lib/ directory (database query files not shown), .sequelizerc.example. The application uses Sequelize ORM (.sequelizerc.example present) for database operations. If raw queries or improper parameterization are used anywhere in the codebase, SQL injection is possible. No visible query sanitization patterns in provided file structure. Fix: 1. Always use Sequelize parameterized queries and avoid raw SQL. 2. If raw queries are necessary, use 'sequelize.query()' with replacements parameter. 3. Never concatenate user input into SQL strings. 4. Implement input validation before database operations. 5. Add security tests for SQLi vectors.
• High · No Visible Security Headers Configuration — lib/csp.js, app.js. While lib/csp.js exists (suggesting CSP implementation), other critical security headers are not evident: HSTS, X-Frame-Options, X-Content-Type-Options, X-XSS-Protection. Missing headers increase XSS, clickjacking, and MIME-sniffing attack surface. Fix: 1. Implement helmet.js middleware for all security headers. 2. Set Content-Security-Policy with strict directives (avoid 'unsafe-inline'). 3. Configure HSTS with preload. 4. Set X-Frame-Options to DENY or SAMEORIGIN. 5. Enable X-Content-Type-Options: nosniff.
• Medium · Hardcoded Configuration and Secrets Risk — config.js, config.json.example, .sequelizerc.example, lib/config/. The presence of config.json.example and .sequelizerc.example suggests configuration files may be tracked in git or contain sensitive defaults. Config.js and environment-based config loading (lib/config/environment.js) may expose secrets through environment variables without proper validation. Fix: 1. Ensure config.json and .sequelizerc are in .gitignore (verify .gitignore content). 2. Use environment variables with validation via lib/config/utils.js. 3. Never store secrets in code or examples. 4. Implement

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/hackmdio/codimd shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live hackmdio/codimd repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/hackmdio/codimd.

What it runs against: a local clone of hackmdio/codimd — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in hackmdio/codimd | Confirms the artifact applies here, not a fork | | 2 | License is still AGPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch develop exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 251 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of hackmdio/codimd. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/hackmdio/codimd.git
#   cd codimd
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of hackmdio/codimd and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "hackmdio/codimd(\\.git)?\\b" \\
  && ok "origin remote is hackmdio/codimd" \\
  || miss "origin remote is not hackmdio/codimd (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(AGPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"AGPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is AGPL-3.0" \\
  || miss "license drift — was AGPL-3.0 at generation time"

# 3. Default branch
git rev-parse --verify develop >/dev/null 2>&1 \\
  && ok "default branch develop exists" \\
  || miss "default branch develop no longer exists"

# 4. Critical files exist
test -f "app.js" \\
  && ok "app.js" \\
  || miss "missing critical file: app.js"
test -f "lib/config/index.js" \\
  && ok "lib/config/index.js" \\
  || miss "missing critical file: lib/config/index.js"
test -f "lib/auth/index.js" \\
  && ok "lib/auth/index.js" \\
  || miss "missing critical file: lib/auth/index.js"
test -f "lib/history/index.js" \\
  && ok "lib/history/index.js" \\
  || miss "missing critical file: lib/history/index.js"
test -f "lib/imageRouter/index.js" \\
  && ok "lib/imageRouter/index.js" \\
  || miss "missing critical file: lib/imageRouter/index.js"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 251 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~221d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/hackmdio/codimd"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.