@cubis/foundry 0.3.82 → 0.3.84

package/workflows/skills/php-best-practices/references/security.md

@@ -1,347 +0,0 @@
-# PHP Security Reference
-
-## SQL Injection Prevention
-
-### Always use prepared statements
-
-```php
-<?php declare(strict_types=1);
-
-// BAD — SQL injection vulnerability
-$stmt = $pdo->query("SELECT * FROM users WHERE email = '{$email}'");
-
-// GOOD — prepared statement with positional parameters
-$stmt = $pdo->prepare('SELECT * FROM users WHERE email = ?');
-$stmt->execute([$email]);
-
-// GOOD — prepared statement with named parameters
-$stmt = $pdo->prepare('SELECT * FROM users WHERE email = :email AND status = :status');
-$stmt->execute(['email' => $email, 'status' => $status]);
-```
-
-### PDO configuration
-
-```php
-<?php declare(strict_types=1);
-
-$pdo = new PDO($dsn, $user, $pass, [
-    // Use real prepared statements, not emulated
-    PDO::ATTR_EMULATE_PREPARES => false,
-    // Throw exceptions on errors
-    PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
-    // Return associative arrays by default
-    PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC,
-    // Use strict typing for bound parameters
-    PDO::ATTR_STRINGIFY_FETCHES => false,
-]);
-```
-
-### Query builder safety
-
-When using Doctrine DBAL or Eloquent query builders, parameters are automatically bound:
-
-```php
-<?php declare(strict_types=1);
-
-// Doctrine DBAL — parameters are bound
-$qb = $connection->createQueryBuilder()
-    ->select('*')
-    ->from('users')
-    ->where('email = :email')
-    ->setParameter('email', $email);
-
-// BAD — even with query builders, raw interpolation is dangerous
-$qb->where("email = '{$email}'"); // SQL INJECTION!
-```
-
-## Cross-Site Scripting (XSS) Prevention
-
-### Output encoding
-
-```php
-<?php declare(strict_types=1);
-
-// HTML context — escape for HTML entities
-echo htmlspecialchars($userInput, ENT_QUOTES | ENT_HTML5, 'UTF-8');
-
-// Templating engines (Twig, Blade) auto-escape by default
-// Twig: {{ user.name }} — auto-escaped
-// Twig: {{ user.bio|raw }} — DANGEROUS, only for trusted HTML
-
-// JSON context — use json_encode flags
-echo json_encode($data, JSON_HEX_TAG | JSON_HEX_APOS | JSON_HEX_QUOT | JSON_HEX_AMP);
-```
-
-### Content Security Policy
-
-```php
-<?php declare(strict_types=1);
-
-// Set CSP header to prevent inline scripts
-header("Content-Security-Policy: default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'");
-```
-
-## Session Security
-
-### Secure session configuration
-
-```php
-<?php declare(strict_types=1);
-
-// In php.ini or at runtime
-ini_set('session.cookie_httponly', '1');     // Prevent JS access
-ini_set('session.cookie_secure', '1');       // HTTPS only
-ini_set('session.cookie_samesite', 'Lax');   // CSRF protection
-ini_set('session.use_strict_mode', '1');     // Reject uninitialized session IDs
-ini_set('session.use_only_cookies', '1');    // No URL session IDs
-ini_set('session.sid_length', '48');         // Longer session IDs
-ini_set('session.sid_bits_per_character', '6'); // More entropy
-```
-
-### Session regeneration
-
-```php
-<?php declare(strict_types=1);
-
-// Regenerate session ID on privilege change (login, role change)
-function loginUser(User $user): void
-{
-    // Destroy old session to prevent fixation
-    session_regenerate_id(true);
-
-    $_SESSION['user_id'] = $user->id;
-    $_SESSION['user_role'] = $user->role->value;
-    $_SESSION['login_time'] = time();
-    $_SESSION['ip_address'] = $_SERVER['REMOTE_ADDR'];
-}
-
-// Validate session integrity on each request
-function validateSession(): bool
-{
-    if (!isset($_SESSION['user_id'])) {
-        return false;
-    }
-
-    // Detect session hijacking via IP change
-    if ($_SESSION['ip_address'] !== $_SERVER['REMOTE_ADDR']) {
-        session_destroy();
-        return false;
-    }
-
-    // Expire sessions after inactivity
-    if (time() - ($_SESSION['last_activity'] ?? 0) > 1800) {
-        session_destroy();
-        return false;
-    }
-
-    $_SESSION['last_activity'] = time();
-    return true;
-}
-```
-
-## Password Handling
-
-### Hashing
-
-```php
-<?php declare(strict_types=1);
-
-// Hash with Argon2id (recommended) or bcrypt
-$hash = password_hash($plaintext, PASSWORD_ARGON2ID, [
-    'memory_cost' => 65536,  // 64 MB
-    'time_cost' => 4,         // 4 iterations
-    'threads' => 3,
-]);
-
-// Verify — timing-safe comparison built in
-if (password_verify($plaintext, $hash)) {
-    // Authenticated
-}
-
-// Check if hash needs upgrading (algorithm or cost changed)
-if (password_needs_rehash($hash, PASSWORD_ARGON2ID)) {
-    $newHash = password_hash($plaintext, PASSWORD_ARGON2ID);
-    updateUserHash($userId, $newHash);
-}
-```
-
-### Never do this
-
-```php
-// BAD — reversible, no salt, fast to brute-force
-$hash = md5($password);
-$hash = sha1($password);
-$hash = hash('sha256', $password . $salt); // DIY salting is fragile
-```
-
-## CSRF Protection
-
-### Token-based CSRF protection
-
-```php
-<?php declare(strict_types=1);
-
-// Generate token
-function generateCsrfToken(): string
-{
-    if (empty($_SESSION['csrf_token'])) {
-        $_SESSION['csrf_token'] = bin2hex(random_bytes(32));
-    }
-    return $_SESSION['csrf_token'];
-}
-
-// Validate token
-function validateCsrfToken(string $token): bool
-{
-    return hash_equals($_SESSION['csrf_token'] ?? '', $token);
-}
-
-// In form
-echo '<input type="hidden" name="_token" value="' . htmlspecialchars(generateCsrfToken()) . '">';
-
-// On submission
-if (!validateCsrfToken($_POST['_token'] ?? '')) {
-    http_response_code(403);
-    exit('CSRF validation failed');
-}
-```
-
-### SameSite cookie (modern approach)
-
-`SameSite=Lax` (or `Strict`) prevents the browser from sending cookies with cross-site requests, mitigating CSRF without tokens for GET-safe endpoints.
-
-## Input Validation
-
-### Validate at the boundary
-
-```php
-<?php declare(strict_types=1);
-
-final readonly class CreateUserRequest
-{
-    public function __construct(
-        public string $name,
-        public string $email,
-        public int $age,
-    ) {
-        if (trim($name) === '' || mb_strlen($name) > 255) {
-            throw new ValidationException('name', 'Name must be 1-255 characters');
-        }
-        if (!filter_var($email, FILTER_VALIDATE_EMAIL)) {
-            throw new ValidationException('email', 'Invalid email address');
-        }
-        if ($age < 0 || $age > 150) {
-            throw new ValidationException('age', 'Age must be 0-150');
-        }
-    }
-}
-
-// Usage — validation happens at construction
-$request = new CreateUserRequest(
-    name: trim($_POST['name'] ?? ''),
-    email: trim($_POST['email'] ?? ''),
-    age: (int) ($_POST['age'] ?? 0),
-);
-```
-
-### filter_var for common validations
-
-| Filter | Validates |
-| --- | --- |
-| `FILTER_VALIDATE_EMAIL` | Email format |
-| `FILTER_VALIDATE_URL` | URL format |
-| `FILTER_VALIDATE_IP` | IP address |
-| `FILTER_VALIDATE_INT` | Integer with optional range |
-| `FILTER_VALIDATE_DOMAIN` | Domain name (PHP 7+) |
-
-## Deserialization Safety
-
-### Never unserialize untrusted data
-
-```php
-<?php declare(strict_types=1);
-
-// BAD — arbitrary object instantiation, remote code execution
-$data = unserialize($_COOKIE['preferences']); // DANGEROUS
-
-// GOOD — use JSON for data exchange
-$data = json_decode($_COOKIE['preferences'], true, 512, JSON_THROW_ON_ERROR);
-
-// If you must use unserialize, restrict allowed classes
-$data = unserialize($input, ['allowed_classes' => [AllowedClass::class]]);
-```
-
-## File Upload Security
-
-```php
-<?php declare(strict_types=1);
-
-function handleUpload(array $file): string
-{
-    // Validate upload error
-    if ($file['error'] !== UPLOAD_ERR_OK) {
-        throw new \RuntimeException('Upload failed');
-    }
-
-    // Validate MIME type (check content, not just extension)
-    $finfo = new \finfo(FILEINFO_MIME_TYPE);
-    $mimeType = $finfo->file($file['tmp_name']);
-    $allowedTypes = ['image/jpeg', 'image/png', 'image/webp'];
-
-    if (!in_array($mimeType, $allowedTypes, true)) {
-        throw new \RuntimeException("Invalid file type: {$mimeType}");
-    }
-
-    // Validate size
-    if ($file['size'] > 5 * 1024 * 1024) { // 5 MB limit
-        throw new \RuntimeException('File too large');
-    }
-
-    // Generate safe filename — NEVER use the original filename
-    $extension = match ($mimeType) {
-        'image/jpeg' => 'jpg',
-        'image/png' => 'png',
-        'image/webp' => 'webp',
-        default => throw new \RuntimeException('Unsupported type'),
-    };
-    $safeName = bin2hex(random_bytes(16)) . '.' . $extension;
-
-    // Move to upload directory outside web root
-    $destination = '/var/uploads/' . $safeName;
-    if (!move_uploaded_file($file['tmp_name'], $destination)) {
-        throw new \RuntimeException('Failed to move uploaded file');
-    }
-
-    return $safeName;
-}
-```
-
-## HTTP Security Headers
-
-```php
-<?php declare(strict_types=1);
-
-// Set security headers (in middleware or bootstrap)
-header('X-Content-Type-Options: nosniff');
-header('X-Frame-Options: DENY');
-header('X-XSS-Protection: 0'); // Disabled — CSP is the modern replacement
-header('Referrer-Policy: strict-origin-when-cross-origin');
-header('Permissions-Policy: camera=(), microphone=(), geolocation=()');
-header("Content-Security-Policy: default-src 'self'; script-src 'self'; object-src 'none'");
-header('Strict-Transport-Security: max-age=31536000; includeSubDomains');
-```
-
-## Security Checklist
-
-| Category | Check |
-| --- | --- |
-| SQL | All queries use prepared statements |
-| XSS | All output is context-encoded |
-| CSRF | State-changing requests require token or SameSite cookie |
-| Auth | Passwords hashed with Argon2id or bcrypt |
-| Session | HttpOnly, Secure, SameSite flags set |
-| Session | Regenerated on privilege change |
-| Upload | MIME validated, filename generated, stored outside web root |
-| Headers | HSTS, CSP, X-Content-Type-Options set |
-| Dependencies | `composer audit` runs in CI |
-| Serialization | No `unserialize()` on untrusted data |

package/workflows/skills/php-best-practices/references/testing.md

@@ -1,367 +0,0 @@
-# PHP Testing Reference
-
-## PHPUnit Setup
-
-### Installation and configuration
-
-```json
-{
-    "require-dev": {
-        "phpunit/phpunit": "^11.0"
-    }
-}
-```
-
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<!-- phpunit.xml.dist -->
-<phpunit
-    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-    xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
-    bootstrap="vendor/autoload.php"
-    colors="true"
-    cacheDirectory=".phpunit.cache"
-    executionOrder="depends,defects"
-    failOnWarning="true"
-    failOnRisky="true"
-    beStrictAboutOutputDuringTests="true"
->
-    <testsuites>
-        <testsuite name="Unit">
-            <directory>tests/Unit</directory>
-        </testsuite>
-        <testsuite name="Integration">
-            <directory>tests/Integration</directory>
-        </testsuite>
-    </testsuites>
-    <source>
-        <include>
-            <directory>src</directory>
-        </include>
-    </source>
-</phpunit>
-```
-
-### Basic test structure
-
-```php
-<?php declare(strict_types=1);
-
-namespace App\Tests\Unit\Domain;
-
-use App\Domain\ValueObject\Money;
-use PHPUnit\Framework\Attributes\Test;
-use PHPUnit\Framework\TestCase;
-
-final class MoneyTest extends TestCase
-{
-    #[Test]
-    public function it_adds_same_currency(): void
-    {
-        $a = new Money(1000, 'USD');
-        $b = new Money(2500, 'USD');
-
-        $result = $a->add($b);
-
-        self::assertSame(3500, $result->amount);
-        self::assertSame('USD', $result->currency);
-    }
-
-    #[Test]
-    public function it_rejects_different_currencies(): void
-    {
-        $a = new Money(1000, 'USD');
-        $b = new Money(1000, 'EUR');
-
-        $this->expectException(\InvalidArgumentException::class);
-        $this->expectExceptionMessage('Cannot combine USD with EUR');
-
-        $a->add($b);
-    }
-}
-```
-
-## Data Providers
-
-### Attribute-based data providers (PHP 8+)
-
-```php
-<?php declare(strict_types=1);
-
-use PHPUnit\Framework\Attributes\DataProvider;
-use PHPUnit\Framework\Attributes\Test;
-
-final class EmailValidatorTest extends TestCase
-{
-    #[Test]
-    #[DataProvider('validEmails')]
-    public function it_accepts_valid_emails(string $email): void
-    {
-        $validator = new EmailValidator();
-        self::assertTrue($validator->isValid($email));
-    }
-
-    #[Test]
-    #[DataProvider('invalidEmails')]
-    public function it_rejects_invalid_emails(string $email, string $reason): void
-    {
-        $validator = new EmailValidator();
-        self::assertFalse($validator->isValid($email), $reason);
-    }
-
-    /** @return iterable<string, array{string}> */
-    public static function validEmails(): iterable
-    {
-        yield 'standard' => ['user@example.com'];
-        yield 'subdomain' => ['user@sub.example.com'];
-        yield 'plus addressing' => ['user+tag@example.com'];
-        yield 'dotted local' => ['first.last@example.com'];
-    }
-
-    /** @return iterable<string, array{string, string}> */
-    public static function invalidEmails(): iterable
-    {
-        yield 'no at sign' => ['userexample.com', 'Missing @ symbol'];
-        yield 'no domain' => ['user@', 'Missing domain'];
-        yield 'no local part' => ['@example.com', 'Missing local part'];
-        yield 'spaces' => ['user @example.com', 'Contains spaces'];
-        yield 'empty string' => ['', 'Empty string'];
-    }
-}
-```
-
-### Complex data providers with objects
-
-```php
-<?php declare(strict_types=1);
-
-/** @return iterable<string, array{Order, Discount}> */
-public static function discountScenarios(): iterable
-{
-    yield 'premium customer over threshold' => [
-        new Order(total: 15000, customerTier: CustomerTier::Premium),
-        new Discount(percentage: 15, reason: 'Premium loyalty discount'),
-    ];
-
-    yield 'standard customer no discount' => [
-        new Order(total: 5000, customerTier: CustomerTier::Standard),
-        new Discount(percentage: 0, reason: 'No applicable discount'),
-    ];
-}
-```
-
-## Mocking
-
-### PHPUnit built-in mocks
-
-```php
-<?php declare(strict_types=1);
-
-#[Test]
-public function it_saves_order_on_checkout(): void
-{
-    $repository = $this->createMock(OrderRepositoryInterface::class);
-    $repository->expects($this->once())
-        ->method('save')
-        ->with($this->callback(fn(Order $order) =>
-            $order->status === OrderStatus::Pending
-            && $order->total->amount === 2999
-        ));
-
-    $service = new CheckoutService($repository);
-    $service->checkout($this->createCart());
-}
-```
-
-### Mockery (more expressive)
-
-```php
-<?php declare(strict_types=1);
-
-use Mockery;
-use Mockery\Adapter\Phpunit\MockeryPHPUnitIntegration;
-
-final class NotificationServiceTest extends TestCase
-{
-    use MockeryPHPUnitIntegration;
-
-    #[Test]
-    public function it_sends_email_for_high_priority_orders(): void
-    {
-        $mailer = Mockery::mock(MailerInterface::class);
-        $mailer->shouldReceive('send')
-            ->once()
-            ->with(Mockery::on(fn(Email $e) =>
-                str_contains($e->subject, 'High Priority')
-            ));
-
-        $service = new NotificationService($mailer);
-        $service->notify(new OrderEvent(priority: Priority::High));
-    }
-}
-```
-
-### Spy pattern
-
-```php
-<?php declare(strict_types=1);
-
-#[Test]
-public function it_logs_failed_payment_attempts(): void
-{
-    $logger = Mockery::spy(LoggerInterface::class);
-    $gateway = Mockery::mock(PaymentGateway::class);
-    $gateway->shouldReceive('charge')->andThrow(new PaymentFailedException());
-
-    $service = new PaymentService($gateway, $logger);
-
-    try {
-        $service->processPayment($this->createPayment());
-    } catch (PaymentFailedException) {
-        // expected
-    }
-
-    $logger->shouldHaveReceived('error')
-        ->with(Mockery::pattern('/payment failed/i'), Mockery::type('array'));
-}
-```
-
-## Pest Framework
-
-Pest provides a more expressive, functional syntax built on top of PHPUnit.
-
-### Basic Pest tests
-
-```php
-<?php declare(strict_types=1);
-
-it('creates a user with default role', function () {
-    $user = new User(name: 'Alice', email: 'alice@example.com');
-
-    expect($user->role)->toBe(Role::Member);
-    expect($user->isActive)->toBeTrue();
-});
-
-it('rejects invalid email addresses', function (string $email) {
-    expect(fn() => new User(name: 'Test', email: $email))
-        ->toThrow(\InvalidArgumentException::class);
-})->with([
-    'empty' => [''],
-    'no at' => ['invalid'],
-    'no domain' => ['user@'],
-]);
-```
-
-### Pest datasets
-
-```php
-<?php declare(strict_types=1);
-
-dataset('currencies', [
-    'USD' => [Currency::USD, '$'],
-    'EUR' => [Currency::EUR, '€'],
-    'GBP' => [Currency::GBP, '£'],
-]);
-
-it('formats currency with correct symbol', function (Currency $currency, string $symbol) {
-    expect($currency->symbol())->toBe($symbol);
-})->with('currencies');
-```
-
-## Test Architecture
-
-### Directory structure
-
-```
-tests/
-├── Unit/
-│   ├── Domain/
-│   │   ├── ValueObject/
-│   │   │   ├── MoneyTest.php
-│   │   │   └── ProductIdTest.php
-│   │   └── Entity/
-│   │       └── ProductTest.php
-│   ├── Application/
-│   │   └── InventoryServiceTest.php
-│   └── Helpers/
-│       └── TestDataFactory.php
-├── Integration/
-│   ├── Repository/
-│   │   └── PdoProductRepositoryTest.php
-│   └── Api/
-│       └── ProductApiTest.php
-└── Pest.php  (or bootstrap.php)
-```
-
-### Test data factories
-
-```php
-<?php declare(strict_types=1);
-
-final class TestDataFactory
-{
-    public static function createProduct(
-        ?string $id = null,
-        ?string $name = null,
-        int $priceInCents = 9999,
-        int $stockLevel = 100,
-        ProductStatus $status = ProductStatus::Active,
-    ): Product {
-        return new Product(
-            id: new ProductId($id ?? self::uuid()),
-            name: $name ?? 'Test Product',
-            sku: 'TEST-' . random_int(1000, 9999),
-            price: new Money($priceInCents, 'USD'),
-            stockLevel: new Quantity($stockLevel),
-            baseStatus: $status,
-        );
-    }
-
-    private static function uuid(): string
-    {
-        return sprintf('%04x%04x-%04x-%04x-%04x-%04x%04x%04x',
-            random_int(0, 0xffff), random_int(0, 0xffff),
-            random_int(0, 0xffff), random_int(0, 0x0fff) | 0x4000,
-            random_int(0, 0x3fff) | 0x8000,
-            random_int(0, 0xffff), random_int(0, 0xffff), random_int(0, 0xffff));
-    }
-}
-```
-
-## CI Configuration
-
-```yaml
-# .github/workflows/test.yml
-jobs:
-  test:
-    runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        php: ['8.4']
-
-    steps:
-      - uses: actions/checkout@v4
-      - uses: shivammathur/setup-php@v2
-        with:
-          php-version: ${{ matrix.php }}
-          coverage: xdebug
-
-      - run: composer install --no-progress
-      - run: vendor/bin/phpstan analyse
-      - run: vendor/bin/phpunit --coverage-clover coverage.xml
-
-      - uses: codecov/codecov-action@v4
-        with:
-          files: coverage.xml
-```
-
-## Testing Anti-patterns
-
-| Anti-pattern | Fix |
-| --- | --- |
-| Testing private methods directly | Test through public API |
-| Mocking the class under test | Mock only dependencies |
-| Testing framework internals | Test your behavior, not Laravel/Symfony |
-| Copy-paste test methods | Use data providers |
-| Relying on execution order | Each test is independent |
-| Testing trivial getters/setters | Test behavior, not structure |