https://github.com/blackcatacademy/blackcat-core
BlackCat Core — Web3-backed TrustKernel security: HTTPS-only request hardening, fail-closed runtime config, and guarded DB/crypto entrypoints.
https://github.com/blackcatacademy/blackcat-core
blackcat blockchain evm fail-closed hardening https integrity php runtime-config security sql-injection ssrf supply-chain-security tls trust-kernel web3 zero-trust
Last synced: 14 days ago
JSON representation
BlackCat Core — Web3-backed TrustKernel security: HTTPS-only request hardening, fail-closed runtime config, and guarded DB/crypto entrypoints.
- Host: GitHub
- URL: https://github.com/blackcatacademy/blackcat-core
- Owner: blackcatacademy
- License: other
- Created: 2025-10-09T13:55:17.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2026-01-04T15:09:13.000Z (5 months ago)
- Last Synced: 2026-01-04T17:36:24.343Z (5 months ago)
- Topics: blackcat, blockchain, evm, fail-closed, hardening, https, integrity, php, runtime-config, security, sql-injection, ssrf, supply-chain-security, tls, trust-kernel, web3, zero-trust
- Language: PHP
- Homepage:
- Size: 1.03 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE
- Security: .github/SECURITY.md
- Roadmap: docs/ROADMAP.md
Awesome Lists containing this project
README
# BlackCat Core (Kernel)
[](https://github.com/blackcatacademy/blackcat-core/actions/workflows/ci.yml)
`blackcat-core` is the **minimal kernel** of the BlackCat ecosystem: a small, auditable set of primitives and utilities that other modules build on.
It is designed for two modes:
- **Kernel-only deployments** (extreme minimalism / custom systems)
- **Modular deployments** (recommended): `blackcat-core` + purpose-built modules (`blackcat-database`, `blackcat-auth`, `blackcat-messaging`, …)
## What lives here
- `BlackCat\Core\Database` — hardened PDO wrapper (prepared statements, retries, observability helpers, safety guards).
- `BlackCat\Database\SqlDialect` + `BlackCat\Database\Support\Observability` / `QueryObserver` — shared DB primitives used by the kernel DB wrapper and generated repositories.
- `BlackCat\Core\Security\KeyManager` / `Crypto` / `CSRF` / `FileVault` — low-level security primitives (versioned keys, AEAD, CSRF binding, file-at-rest encryption).
- `BlackCat\Core\Cache\*` — PSR-16 caches (memory/file/null) and locking support.
- `BlackCat\Core\Log\Logger` / `AuditLogger` — lightweight logging helpers for kernel-only stacks.
- `BlackCat\Core\Migrations\MigrationRunner` — tiny migration runner (no schema source of truth inside core).
- `BlackCat\Core\Templates\Templates` + `BlackCat\Core\Validation\Validator` — small DX helpers.
## What does NOT live here
To keep a single source of truth and avoid duplicated business logic, these belong to dedicated modules:
- **DB schema, views, joins, generated repositories** → `blackcatacademy/blackcat-database`
- **DB encryption ingress (automatic field encryption/hmac)** → `blackcatacademy/blackcat-database-crypto` (+ `blackcat/crypto`)
- **Auth flows (register/login/verify/reset/magic-link/webauthn)** → `blackcatacademy/blackcat-auth`
- **Sessions** → `blackcatacademy/blackcat-sessions`
- **Outbox/inbox workers + transports** → `blackcatacademy/blackcat-messaging`
- **Notifications + mailing worker** → `blackcatacademy/blackcat-mailing`
- **Job queue** → `blackcatacademy/blackcat-jobs`
- **JWT** → `blackcatacademy/blackcat-jwt`
- **RBAC** → `blackcatacademy/blackcat-rbac`
- **GoPay** → `blackcatacademy/blackcat-gopay`
## No legacy facades
For a fail-closed kernel and a clean single-source-of-truth model, `blackcat-core` intentionally does **not** ship `class_alias` compatibility facades for other modules.
If you need auth/sessions/jobs/jwt/rbac/messaging/payments, depend on the dedicated module directly (see list above).
## Install
```bash
composer require blackcatacademy/blackcat-core
```
## Kernel bootstrap (Trust Kernel)
For kernel-only deployments where Web3 integrity enforcement is mandatory, use:
```php
use BlackCat\Core\Kernel\KernelBootstrap;
KernelBootstrap::bootOrFail(); // fail-closed
```
This requires `blackcatacademy/blackcat-config` + a runtime config that includes `trust.web3` + `trust.integrity`.
Note:
- As a safety net, kernel primitives (`KeyManager`, `Database`) attempt a **one-time** Trust Kernel auto-bootstrap when a guard is missing.
- When `blackcatacademy/blackcat-config` is installed, auto-bootstrap is **trust-required** (missing runtime config / missing `trust.web3` fails closed).
- Production should still call `KernelBootstrap::bootOrFail()` as early as possible (before any app logic runs).
## Quick start (Database)
```php
use BlackCat\Core\Database;
Database::init([
'dsn' => 'mysql:host=127.0.0.1;dbname=app;charset=utf8mb4',
'user' => 'app',
'pass' => 'secret',
'appName' => 'my-service',
]);
$db = Database::getInstance();
$row = $db->fetch('SELECT 1 AS ok');
```
## Documentation
- [Docs index](docs/README.md)
- [Bootstrap examples](docs/BOOTSTRAP_EXAMPLES.md)
- [Database](docs/DATABASE.md)
- [Security](docs/SECURITY.md)
- [Troubleshooting](docs/TROUBLESHOOTING.md)
- [Roadmap](docs/ROADMAP.md)
## Project meta
- Contributing: `.github/CONTRIBUTING.md`
- Security: `.github/SECURITY.md`