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.
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:actiontriples 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
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-signheader, thex-csrf-tokenheader. The contract lives in Authentication integration; any frontend stack will do.
Three backend architecture diagrams (click to open the full-size image).
# 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 devVerify:
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 —.nvmrcpins it), MySQL ≥ 8.0; Redis optional (mandatory for multi-instance).Why 24:
@fastify/static@10pulls the ESM-onlycontent-disposition@3, which needsrequire(esm)(Node ≥ 20.19 / 22.12) — this is what ruled out Node 18;geoip-lite@2declaresengines: >= 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.
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 intosrc/{data,public,storage}.
For the full tree (including loader order and fail-fast semantics) see Project structure.
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.
| 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).
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).
| 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.
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 emptyTwo 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 forgeX-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.
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| 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) |
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.


