BlackCat Core (Kernel)

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

composer require blackcatacademy/blackcat-core

Kernel bootstrap (Trust Kernel)

For kernel-only deployments where Web3 integrity enforcement is mandatory, use:

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)

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
• Bootstrap examples
• Database
• Security
• Troubleshooting
• Roadmap

Project meta

• Contributing: .github/CONTRIBUTING.md
• Security: .github/SECURITY.md