From 0a2c61336c8f8e14f363f3cc116ece6fc62a78c4 Mon Sep 17 00:00:00 2001 From: willxue Date: Mon, 8 Jun 2026 11:18:29 +0800 Subject: [PATCH] Prepare the admin template for open-source reuse Opening the template to external users requires more than working code: consumers need a license, environment example, contribution and security expectations, release notes, and package metadata that describe ownership and support surfaces. This adds those project files and documents the production security boundary so frontend RBAC is not mistaken for backend authorization. Constraint: Keep the project installable with the existing npm workflow and avoid adding runtime dependencies. Rejected: Leave the PostCSS advisory as documentation only | npm overrides can pin the transitive package to a patched version without changing Next APIs. Confidence: high Scope-risk: narrow Directive: Remove the PostCSS override once Next depends on a patched PostCSS release directly. Tested: npm audit --omit=dev --registry=https://registry.npmjs.org Tested: npm run verify Not-tested: Fresh npm ci on GitHub-hosted Linux after push. Co-authored-by: OmX --- .env.example | 8 ++++++++ CHANGELOG.md | 19 +++++++++++++++++++ CODE_OF_CONDUCT.md | 31 +++++++++++++++++++++++++++++++ CONTRIBUTING.md | 36 ++++++++++++++++++++++++++++++++++++ LICENSE | 21 +++++++++++++++++++++ README.md | 36 ++++++++++++++++++++++++++++++++++++ SECURITY.md | 33 +++++++++++++++++++++++++++++++++ package-lock.json | 44 ++++++++++---------------------------------- package.json | 24 +++++++++++++++++++++++- 9 files changed, 217 insertions(+), 35 deletions(-) create mode 100644 .env.example create mode 100644 CHANGELOG.md create mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.md create mode 100644 LICENSE create mode 100644 SECURITY.md diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..e6c7a08 --- /dev/null +++ b/.env.example @@ -0,0 +1,8 @@ +# API mode. Use "mock" for local demos and "http" for a real backend. +NEXT_PUBLIC_API_MODE=mock + +# Required when NEXT_PUBLIC_API_MODE=http. +NEXT_PUBLIC_API_BASE_URL=https://api.example.com + +# Default HTTP timeout in milliseconds. Set to 0 only when callers provide AbortSignal. +NEXT_PUBLIC_API_TIMEOUT_MS=15000 diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..9517575 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,19 @@ +# Changelog + +All notable changes to this project will be documented in this file. + +## 0.1.0 - 2026-06-08 + +### Added + +- Next.js App Router admin shell with login, dashboard, global search, sidebar navigation, and account profile. +- Mock and HTTP API adapter boundary with normalized errors, request IDs, timeout handling, and session-expiry routing. +- RBAC primitives for routes, buttons, action permissions, and role data scopes. +- CRUD patterns for users, roles, menus, notifications, sessions, settings, and audit logs. +- System health page for runtime mode, backend readiness, version, and operational indicators. +- Source-level smoke suites for i18n, auth, API contracts, permissions, CRUD, audit, accessibility, production readiness, and template hardening. +- GitHub Actions CI using `npm run verify`. + +### Security + +- Documented backend authorization requirements and known dependency advisory handling. diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..1bd34e0 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,31 @@ +# Code of Conduct + +WeBase follows the Contributor Covenant Code of Conduct, version 2.1. + +## Our pledge + +We pledge to make participation in this project a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation. + +## Our standards + +Examples of behavior that contributes to a positive environment: + +- using welcoming and inclusive language +- being respectful of differing viewpoints and experiences +- gracefully accepting constructive feedback +- focusing on what is best for the community +- showing empathy toward other community members + +Examples of unacceptable behavior: + +- sexualized language or imagery +- insulting or derogatory comments +- public or private harassment +- publishing others' private information without permission +- other conduct that could reasonably be considered inappropriate in a professional setting + +## Enforcement + +Project maintainers may remove, edit, or reject comments, commits, code, issues, and other contributions that do not align with this Code of Conduct. Maintainers may also temporarily or permanently ban contributors for behavior they deem inappropriate, threatening, offensive, or harmful. + +Instances of abusive, harassing, or otherwise unacceptable behavior may be reported through the project's security or maintainer contact channels. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..6cee514 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,36 @@ +# Contributing + +Thanks for helping improve WeBase Admin Template. + +## Local setup + +```bash +npm ci +cp .env.example .env.local +npm run dev +``` + +Use mock mode for most UI and template work. Use HTTP mode only when validating a real backend contract. + +## Before opening a pull request + +Run the full verification gate: + +```bash +npm run verify +``` + +For feature modules, also update the relevant source-level smoke script or add a focused script under `scripts/`. + +## Development expectations + +- Keep route metadata in `src/lib/navigation/route-registry.ts`. +- Keep permission keys in `src/lib/auth/permissions.ts`. +- Call feature services from pages and components instead of importing adapters directly. +- Treat frontend RBAC as a UI convenience only; backend authorization remains mandatory in production. +- Keep mock data deterministic so demos and smoke scripts stay stable. +- Avoid new dependencies unless they materially reduce risk or complexity. + +## Commit messages + +Use clear, decision-oriented commit messages. Include verification evidence in the body when a change affects behavior, release readiness, auth, permissions, or API contracts. diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..d6e2c41 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 WeOpen + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md index 5313b1f..d0fe68f 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,16 @@ WeBase Admin Template is an independent Next.js App Router admin scaffold for building operational management consoles. It includes a polished dark-first login experience, an admin shell, dashboard metrics, local mock CRUD flows, role/menu governance, global search, and system settings. +## Quick start + +```bash +npm ci +cp .env.example .env.local +npm run dev +``` + +Open `http://localhost:3000`, then sign in with the mock credentials below. + ## Tech stack - Next.js 16 App Router @@ -40,6 +50,16 @@ The login form is prefilled with demo credentials: The current mock adapter accepts the displayed `admin / admin123` credentials, then returns a local demo session. HTTP mode delegates credential validation to the backend. +## Environment variables + +Copy `.env.example` to `.env.local` and adjust as needed: + +| Variable | Purpose | +| --- | --- | +| `NEXT_PUBLIC_API_MODE` | `mock` for local demos, `http` for a real backend | +| `NEXT_PUBLIC_API_BASE_URL` | Backend base URL when HTTP mode is enabled | +| `NEXT_PUBLIC_API_TIMEOUT_MS` | Default HTTP timeout in milliseconds | + ## Development commands ```bash @@ -70,11 +90,23 @@ npm run verify Then open `/system/health` to confirm API mode, backend/mock status, frontend version, build target, and operational indicators. +## Production security boundary + +Frontend RBAC, route guards, mock sessions, and permission-aware UI controls are template conveniences. A production backend must enforce authentication, authorization, data-scope checks, session expiry, audit logging, CSRF protection where applicable, and rate limiting. Do not treat hidden buttons or client route redirects as security controls. + +## Dependency audit note + +PostCSS is pinned through npm `overrides` so transitive consumers use a patched release. Track upstream Next.js releases and remove the override once Next depends on a patched PostCSS version directly. + ## Template extension docs - [Add an admin module](docs/add-admin-module.md) - [API adapter guide](docs/api-adapter.md) - [Permissions and RBAC](docs/permissions.md) +- [Contributing](CONTRIBUTING.md) +- [Security policy](SECURITY.md) +- [Code of conduct](CODE_OF_CONDUCT.md) +- [Changelog](CHANGELOG.md) - [Admin template hardening plan](docs/plans/2026-06-05-admin-template-hardening.md) ## API adapter note @@ -82,3 +114,7 @@ Then open `/system/health` to confirm API mode, backend/mock status, frontend ve The app is wired through `src/lib/api/client.ts`, which delegates to the in-memory mock adapter in `src/lib/api/mock-adapter.ts` by default and can switch to `src/lib/api/http-adapter.ts` with `NEXT_PUBLIC_API_MODE=http`. Feature services under `src/lib/services/` call this client instead of importing mock data directly, so replacing the mock layer with real HTTP requests should be limited to the API client/adapter boundary while preserving service contracts. Mock data is stored in memory in `src/lib/api/mock-data.ts`; create, update, and delete interactions are for the current browser session only and are not persisted. + +## License + +MIT diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..435948a --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,33 @@ +# Security Policy + +## Supported versions + +Security updates target the latest `main` branch and the latest tagged release. + +## Reporting a vulnerability + +Please report suspected vulnerabilities through GitHub Security Advisories or by opening a private report with the maintainers. Do not disclose exploitable details in public issues before maintainers have had a chance to investigate. + +Include: + +- affected version or commit +- reproduction steps +- expected and actual behavior +- impact assessment +- any known workaround + +## Production security boundary + +WeBase Admin Template includes frontend route guards, permission guards, mock sessions, and HTTP adapter contracts. These are template conveniences, not a replacement for backend security. + +Production deployments must enforce authentication, authorization, data-scope checks, audit logging, session expiry, CSRF protection where applicable, and rate limiting on the backend. + +## Dependency advisories + +Run: + +```bash +npm audit --omit=dev +``` + +The project pins PostCSS through npm `overrides` so transitive consumers use a patched release. Track upstream Next.js releases and remove the override once Next depends on a patched PostCSS version directly. diff --git a/package-lock.json b/package-lock.json index 907be28..d95ba87 100644 --- a/package-lock.json +++ b/package-lock.json @@ -31,6 +31,10 @@ "eslint-config-next": "16.2.6", "tailwindcss": "4.3.0", "typescript": "6.0.3" + }, + "license": "MIT", + "overrides": { + "postcss": "8.5.15" } }, "node_modules/@alloc/quick-lru": { @@ -5883,34 +5887,6 @@ "react-dom": "^16.8 || ^17 || ^18 || ^19 || ^19.0.0-rc" } }, - "node_modules/next/node_modules/postcss": { - "version": "8.4.31", - "resolved": "https://registry.npmmirror.com/postcss/-/postcss-8.4.31.tgz", - "integrity": "sha512-PS08Iboia9mts/2ygV3eLpY5ghnUcfLV/EXTOW1E2qYxJKGGBUtNjN76FYHnMs36RmARn41bC0AZmn+rR0OVpQ==", - "funding": [ - { - "type": "opencollective", - "url": "https://opencollective.com/postcss/" - }, - { - "type": "tidelift", - "url": "https://tidelift.com/funding/github/npm/postcss" - }, - { - "type": "github", - "url": "https://github.com/sponsors/ai" - } - ], - "license": "MIT", - "dependencies": { - "nanoid": "^3.3.6", - "picocolors": "^1.0.0", - "source-map-js": "^1.0.2" - }, - "engines": { - "node": "^10 || ^12 || >=14" - } - }, "node_modules/node-exports-info": { "version": "1.6.0", "resolved": "https://registry.npmmirror.com/node-exports-info/-/node-exports-info-1.6.0.tgz", @@ -6198,10 +6174,9 @@ } }, "node_modules/postcss": { - "version": "8.5.14", - "resolved": "https://registry.npmmirror.com/postcss/-/postcss-8.5.14.tgz", - "integrity": "sha512-SoSL4+OSEtR99LHFZQiJLkT59C5B1amGO1NzTwj7TT1qCUgUO6hxOvzkOYxD+vMrXBM3XJIKzokoERdqQq/Zmg==", - "dev": true, + "version": "8.5.15", + "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.15.tgz", + "integrity": "sha512-FfR8sjd4em2T6fb3I2MwAJU7HWVMr9zba+enmQeeWFfCbm+UOC/0X4DS8XtpUTMwWMGbjKYP7xjfNekzyGmB3A==", "funding": [ { "type": "opencollective", @@ -6218,13 +6193,14 @@ ], "license": "MIT", "dependencies": { - "nanoid": "^3.3.11", + "nanoid": "^3.3.12", "picocolors": "^1.1.1", "source-map-js": "^1.2.1" }, "engines": { "node": "^10 || ^12 || >=14" - } + }, + "dev": true }, "node_modules/prelude-ls": { "version": "1.2.1", diff --git a/package.json b/package.json index 9cb456e..0ba651e 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,29 @@ { "name": "webase-admin-template", "version": "0.1.0", - "private": true, + "description": "A production-ready Next.js admin template for generic management consoles.", + "license": "MIT", + "homepage": "https://github.com/WeOpen/WeBase#readme", + "repository": { + "type": "git", + "url": "git+https://github.com/WeOpen/WeBase.git" + }, + "bugs": { + "url": "https://github.com/WeOpen/WeBase/issues" + }, + "keywords": [ + "admin", + "dashboard", + "management-console", + "nextjs", + "react", + "typescript", + "rbac", + "template" + ], + "overrides": { + "postcss": "8.5.15" + }, "scripts": { "dev": "next dev", "build": "next build",