Skip to content
yijiu2025Public

Latest commit

 

History

1,304 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

CoreFlow

A backend framework on Fastify v5 + Sequelize v6: authentication · PBAC permissions · five-layer firewall · OAuth 2.1

English · 简体中文


The documentation site is currently written in Chinese. This README and the doc map (docs/README.md) are the English entry points.

What this is

A backend skeleton you can actually boot, taking the parts every project rewrites from scratch — auth, authorization, rate limiting, request interception, audit — and shipping them as framework capabilities:

  • Authentication: session cookie (default) or JWT bearer, RSA-encrypted login, HMAC-signed cookies, nonce-based replay protection
  • Permissions (PBAC): app:resource:action triples with wildcards, deny-before-allow precedence and role weights; three guard levels (System → Group → API)
  • Firewall: a five-stage pipeline (connection tracking → blocking → challenge → bot detection → geo/endpoint rate limiting), tunable at runtime from the admin API
  • OAuth 2.1: authorization code + PKCE, client credentials, device code, OIDC discovery, refresh-token rotation with reuse detection
  • Redis is optional, but the semantics are explicit: with no Redis configured it runs on in-process implementations (single instance, zero setup); once configured it must be reachable — otherwise the access layer returns 503 instead of silently falling back to memory, because a quiet downgrade breaks sessions and rate limiting across instances

What this is not

Since 2026-10-31 this repository contains the backend only. The frontend projects (oauth21 / posecraft / admin / poseadmin / firewall / phonecopy) have been removed from the index and are maintained separately (oauth21 → oauth-web).

Frontend and backend are coupled through an HTTP wire protocol only: session cookies, the x-sign header, the x-csrf-token header. The contract lives in Authentication integration; any frontend stack will do.

Architecture

Three backend architecture diagrams (click to open the full-size image).

Backend architecture diagram 1
Figure 1

Backend architecture diagram 2
Figure 2

Backend architecture diagram 3
Figure 3

Quick start

# 1. Clone (theme-core is a git submodule)
git clone --recurse-submodules https://github.com/yijiu2025/CoreFlow.git
cd CoreFlow

# 2. Install dependencies
npm install

# 3. Configure the environment (three secrets MUST be changed; weak values refuse to boot
#    in production)
cp .env.example .env

# 4. Create the schema
npm run migrate

# 5. Create a super admin
npm run setup:admin -- --email admin@example.com

# 6. Boot (dev mode, nodemon hot reload)
npm run dev

Verify:

curl -i http://localhost:3000/v1/health/live    # liveness (200 while the process runs)
curl -i http://localhost:3000/v1/health/ready   # readiness (503 when a critical dependency is down)

Every response is wrapped as { code, message, data, timestamp, requestId } — never a bare object. Requirements: Node ≥ 24 (the LTS line CI and the image both run — .nvmrc pins it), MySQL ≥ 8.0; Redis optional (mandatory for multi-instance).

Why 24:

  • @fastify/static@10 pulls the ESM-only content-disposition@3, which needs require(esm) (Node ≥ 20.19 / 22.12) — this is what ruled out Node 18;
  • geoip-lite@2 declares engines: >= 24, and it is a runtime dependency of the firewall. Running 22 works today only because we never hit the version-gated path — declaring 20/22 while shipping 24 would just move that surprise to someone's deploy. Full walkthrough and troubleshooting: Quick start.

Project layout

src/
├── app.js              # Fastify instance creation + lifecycle orchestration
├── framework/          # Infrastructure, grouped in six families (no business logic)
│   ├── config/         #   Config & paths: env validation / override layer / paths.js
│   ├── persistence/    #   db / redis / storage
│   ├── security/       #   auth / verify / jwt / keys / crypto
│   ├── ingress/        #   http / websocket / firewall (five-stage pipeline)
│   ├── lifecycle/      #   loader / startup / scheduler
│   └── support/        #   log / cli / notice
├── app/                # Business apps (one directory = one app: oauth21 / user / admin /
│                       #   firewall / guard / notice / posecraft / retroweb)
├── api/                # Route layer (domain/version); guard.js is the three-level guard engine
├── models/             # Sequelize models (user / iam / oauth21 / session / key /
│                       #   notice / guard / posecraft / retroweb)
├── config/             # Static overrides (firewall / auth / db / redis / verify), optional per deployment
└── shared/  utils/     # Shared exceptions / DAO / helpers

Runtime state lives at the repo root, not under src/: data/ (hot-reloadable JSON: firewall / scheduler / traffic stats), logs/, public/<app>/… (public uploads), storage/<app>/u/<ownerId>/… (private files, served only through an authenticated route). A guard test fails the build if anything writes into src/{data,public,storage}.

For the full tree (including loader order and fail-fast semantics) see Project structure.

What happens on boot

index.js → createApp() → initLoader(), loading in filename-prefix order from src/framework/lifecycle/loader/registry/:

00-globals   decorate reply.result       06-models   scan src/models/ and register every model
01-monitor   request metrics / slow-request warnings   07-keys   JWT keys + startup self-check
02-redis     connect + health monitoring 08-api      scan src/api/ and register routes
03-db        Sequelize connection        09-notice  seed SMTP config
04-auth      session validation + ALS    10-apps    app config + roles + OAuth clients
05-firewall  five-stage pipeline

01-monitor / 02-redis / 09-notice are optional loaders (failures only warn); everything else is fail-fast — a process that binds a port but cannot serve correct responses is harder to diagnose than one that exits.

Permissions: three guard levels

Level Declared in Options
System src/api/<domain>/system.json enabled / allowIps / requireLogin
Group registerGroupMetadata() enabled / allowIps / allowRoles
API registerSecureRoute() requireLogin / requirePermission / requireSignature / config.rateLimit
// Single permission (deny beats allow; wildcards work at the tail *and* mid-segment:
// `user:*` / `user:*:read`)
registerSecureRoute(fastify, {
  name: 'readConfig',
  method: 'GET',
  url: '/config',
  requirePermission: 'fw:config:read',
  handler: async (req, reply) => reply.result.success(await readConfig())
});

// Any of (OR)
requirePermission: {
  any: ['fw:block:write', 'fw:admin:*'];
}

// All of (AND)
requirePermission: {
  all: ['fw:config:read', 'fw:config:write'];
}

Evaluation order: enabled → IP/roles → login → permissions (a deny short-circuits). Not logged in returns 401, insufficient permissions 403, and a malformed permission string fails closed (also 403).

Firewall: five-stage pipeline

request → ① connection tracking (concurrency cap) → ② global blocking (IP/device/fingerprint lists)
        → ③ human challenge (challenge cookie) → ④ bot detection (UA patterns + burst behaviour)
        → ⑤ geo-fencing / endpoint rate limiting

Detectors live in src/framework/ingress/firewall/engine/detectors/: rate-limiter (sliding window, one Redis Lua round-trip + in-memory fallback), bot-detector, brute-force, scan-trap (404/403 scan trap), geo-filter. Rules and thresholds come from data/firewall_config.json and can be hot-edited through the admin API (PATCH /api/firewall/v1/monitor/settings).

API domains

Domain Prefix Capabilities
oauth21 /oauth2.1 Authorization code + PKCE / login / token / revocation / device code / OIDC
user /user/v1 Profile, permissions, sessions, devices, registration, password reset
auth /auth/v1 Session binding / account switching / H5 signed tokens / challenge verification
admin /admin/v1 IAM roles, policies, client management
notice /notice/v1 Notification channels and templates
verify /verify/v1 Image CAPTCHA, email verification codes
firewall /api/firewall/v1 Monitoring, blocks, allowlists, config, WebSocket
system /v1 Health probes, system info
posecraft / retroweb /posecraft · /retroweb Bundled business apps (removable)

Endpoint details: OAuth 2.1 API report and API route conventions.

Environment variables

validateEnv checks 19 keys at boot (DB_HOST / DB_NAME / DB_USER always; APP_SECRET / SESSION_SECRET / FIREWALL_SECRET additionally in production). .env.example documents 38 keys with comments and defaults. The three secrets you must set in production:

APP_SECRET=       # ≥ 32 chars; weak/default values are rejected by validateEnv at boot
SESSION_SECRET=   # cookie signing (rotating it logs everyone out)
FIREWALL_SECRET=  # challenge-cookie signing

DB_HOST=127.0.0.1
DB_NAME=your_database_name
DB_USER=root

CORS_ORIGINS=https://your-domain.com   # required in production: sensitive endpoints fail closed when empty

Two more that commonly bite:

  • PROXY_TRUST_CIDR: set it only when a reverse proxy really sits in front, and list the proxy's exact address (e.g. 172.18.0.2/32). Trusting a whole subnet lets clients forge X-Forwarded-For, which defeats IP allowlists, rate-limit keys and block records.
  • REDIS_ENABLED: if set, Redis must be reachable (otherwise 503 at the access layer); if unset, in-process implementations are used.

Commands

npm run dev            # development (nodemon hot reload)
npm start              # production start (reads .env.production)
npm run migrate        # run database migrations
npm run setup:admin    # create / grant a super admin
npm run revoke:admin   # revoke a super admin (the last one is refused)
npm run cli            # interactive admin terminal
npm test               # Jest (full suite; counts grow — trust the output, not this line)
npm run test:coverage  # same + coverage ratchet (thresholds live in jest.config.js)
npm run lint           # ESLint (auto-fix)
npm run verify:all     # cross-process gates (locks / queues / guard sync / metrics / WS fan-out)
npm run docs:dev       # serve the documentation site locally

Documentation

Entry What it covers
docs/README.md Documentation map — read this before searching
Online docs Full VitePress site (Chinese)
Architecture Layering and dependency direction
Request pipeline The full path of one request
Auth integration Frontend/backend wire protocol (cookies / signatures / CSRF)

Contributing

Run npm run lint && npm test before committing. Commit messages follow Conventional Commits (fix → patch, feat → minor, breaking change → major); releases are cut by node scripts/release.mjs --apply. Details: Git commit and release rules.

Translations are welcome — add README.<locale>.md next to this file and link it in the language switcher at the top.

License

GPL-3.0

Releases

Sponsor this project

Packages

Used by

Contributors

Languages