Scion

Graft backend patterns into your project. Copy-paste, not install.

English | 中文

Scion is a copy-paste code library for Go backend development. Instead of installing a framework or pulling a dependency, you copy pre-built, production-ready modules into your project and own every line of code.

Why Copy-Paste?

Backend modules (auth, CRUD, file upload, rate limiting) share 80% of their skeleton across projects, but the remaining 20% differs in ways that make npm/go packages awkward:

• You need to customize business logic deep inside the module
• You want to own the code, not be locked to upstream versions
• Your AI coding assistant works better with code it can read and modify directly
• No dependency hell — standard library by default, with declared security exceptions

Quick Start

# 1. Install the source-template copier
go install github.com/DarkInno/scion/cmd/scion@latest

# 2. Copy a zero-dependency module into your project
scion add cache --to internal/cache

# 3. Inspect local changes against the embedded template later
scion diff cache --target internal/cache

Scion's CLI copies source files and writes .scion-module.json metadata for later comparison. It never edits your go.mod automatically. Modules marked stdlibOnly=false must be copied with --standalone so their go.mod/go.sum are explicit.

Manual copy still works:

# 1. Copy a module into your project
cp -r registry/cache/src/go/*.go yourproject/internal/cache/

# 2. Adapt the package to your project
#    Rename, trim tests, or wire it into your service as needed.

Available Modules

Module	Description	Security Features
auth	JWT email/password auth + bcrypt	Rate limiting, user enumeration prevention, JTI, aud/iss validation
crud	Generic CRUD with pagination	Sort/filter whitelist, SQL injection prevention, pagination ceiling
middleware	Recovery, CORS, logging, timeout, etc.	CRLF injection prevention, trusted proxy, body size limit
rbac	Role-based access control	Wildcard permissions, cycle detection, hierarchy inheritance
ratelimit	Fixed window / sliding window / token bucket	Memory exhaustion protection, LRU eviction, key length limit
validation	Chainable request validation builder	Regex DoS prevention (RE2), null byte/CRLF rejection, panic recovery
file-upload	Secure file upload handler	Magic bytes validation, path traversal prevention, size limit, rate limiting
health	Liveness/readiness probes	SSRF protection (private IP rejection), CRLF injection prevention
cache	Generic TTL + LRU cache	Background cleanup, goroutine leak prevention, max entries limit
pagination	Offset/limit + cursor pagination	Cursor base64 validation, negative offset clamp, max limit enforcement
mail	SMTP email with templates	Header injection prevention, XSS escaping, attachment sanitization, async queue

Project Structure

scion/
├── registry/
│   ├── index.json              # Machine-readable module index
│   ├── auth/                   # Authentication module
│   │   ├── __llms__.md         # AI-readable summary (~150 tokens)
│   │   ├── README.md           # Human-readable adaptation guide
│   │   ├── src/go/             # Go source code
│   │   └── examples/gin/       # Minimal runnable example
│   ├── crud/                   # CRUD operations module
│   ├── middleware/             # HTTP middleware collection
│   ├── rbac/                   # Role-based access control
│   ├── ratelimit/              # Rate limiting algorithms
│   ├── validation/             # Request validation builder
│   ├── file-upload/            # File upload handler
│   ├── health/                 # Health check probes
│   ├── cache/                  # In-memory cache
│   ├── pagination/             # Pagination utilities
│   └── mail/                   # Email sender
├── docs/
│   └── getting-started.md      # How to use Scion
├── AGENTS.md                   # AI coding agent instructions
├── CONTRIBUTING.md             # How to contribute
├── LICENSE                     # MIT
└── llms.txt                    # LLM-friendly project summary

Design Principles

1. Code ownership — every line is yours after copying. No upstream lock-in.
2. Self-contained — each module works independently; external dependencies are allowed only for declared security exceptions.
3. Framework-agnostic — uses Go standard net/http, adaptable to Gin/Echo/etc.
4. Security-first — input validation, rate limiting, injection prevention built in.
5. AI-friendly — __llms__.md files let AI assistants understand modules in ~200 tokens.
6. Tested — every module includes functional tests and penetration test cases.

Development

# Clone the repository
git clone https://github.com/DarkInno/scion.git
cd scion

# Regenerate the embedded CLI bundle after registry changes
go run ./internal/cmd/build-bundle

# Test the root CLI
go test ./cmd/... ./internal/...

# Run tests for a specific module
cd registry/auth/src/go && go test -v ./...

# Run tests for all modules
# (PowerShell)
$modules = @('middleware','auth','crud','rbac','ratelimit','validation','file-upload','health','cache','pagination','mail')
foreach ($m in $modules) { Push-Location "registry/$m/src/go"; go test ./...; Pop-Location }

# Format code
cd registry/auth/src/go && gofmt -w .

Contributing

We welcome contributions! Please read CONTRIBUTING.md for guidelines on adding new modules.

License

MIT