start-vibing-stacks 2.16.0 → 2.18.0

package/stacks/php/skills/phpunit-testing/SKILL.md

@@ -1,40 +1,207 @@
 ---
 name: phpunit-testing
-version: 1.0.0
+version: 2.0.0
+description: "PHP testing for 2026 — covers PHPUnit 12 (released 2025, foundation for Pest 4) and Pest 4 (March 2026: 20-30% faster, browser testing via Playwright, visual regression, smoke testing, sharding for CI parallelization, mutation testing). Includes Unit / Feature / Browser / Architecture test layout, AAA pattern, data providers / datasets, mocking, fixtures, dataset sharding, coverage thresholds. Invoke when authoring tests, choosing PHPUnit vs Pest, configuring sharding/parallel, or wiring CI test stages."
 ---
 
-# PHPUnit Testing Skill
+# PHP Testing — PHPUnit 12 & Pest 4 (2026)
+
+**ALWAYS invoke when writing tests, choosing the framework, or wiring CI sharding.**
+
+> Pest 4 (Mar 10, 2026) is built on PHPUnit 12. New projects in 2026: prefer **Pest 4** for ergonomics and built-in browser/visual testing; stay on **PHPUnit 12** if your team has muscle memory or you need raw assertion control.
+
+## Framework Choice
+
+| Need | Pick |
+|---|---|
+| New Laravel app, want fluent expectation API + browser tests | **Pest 4** |
+| Plain PHP library, prefer xUnit-classic | **PHPUnit 12** |
+| Big legacy PHPUnit suite | **PHPUnit 12** (don't migrate just for migration's sake) |
+| Need visual regression / Playwright in PHP | **Pest 4** (built-in) |
+
+Both share the same engine — assertions, mocks, runners are interoperable through Pest's PHPUnit base. Pest is a thin DSL on top.
 
 ## Setup
 
+### Pest 4 (recommended for new Laravel projects)
+
 ```bash
-composer require --dev phpunit/phpunit
+composer require --dev pestphp/pest "^4.0"            # PHP 8.3+
+composer require --dev pestphp/pest-plugin-laravel "^4.0"
+./vendor/bin/pest --init
 ```
 
-## Test File Location
+### PHPUnit 12
+
+```bash
+composer require --dev phpunit/phpunit "^12.0"
+```
+
+## File Layout
 
 ```
 tests/
+├── Pest.php                      # Pest config (test dirs, datasets, helpers)
+├── TestCase.php                  # Shared base
 ├── Unit/
-│   ├── Services/
-│   │   └── UserServiceTest.php
-│   └── Helpers/
-│       └── StringHelperTest.php
+│   ├── Services/UserServiceTest.php
+│   └── Helpers/StringHelperTest.php
 ├── Feature/
-│   └── Api/
-│       └── UserApiTest.php
-└── phpunit.xml
+│   └── Api/UserApiTest.php
+├── Browser/                      # Pest 4 — Playwright-backed
+│   └── LoginFlowTest.php
+└── Arch/                         # Pest — architecture rules
+    └── LayerBoundariesTest.php
+phpunit.xml                       # used by both Pest & PHPUnit
+```
+
+## `phpunit.xml` — production-grade baseline
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<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"
+    requireCoverageMetadata="true"
+    beStrictAboutCoverageMetadata="true"
+    beStrictAboutOutputDuringTests="true"
+    failOnRisky="true"
+    failOnWarning="true"
+    executionOrder="random">
+
+    <testsuites>
+        <testsuite name="Unit">
+            <directory>tests/Unit</directory>
+        </testsuite>
+        <testsuite name="Feature">
+            <directory>tests/Feature</directory>
+        </testsuite>
+        <testsuite name="Browser">
+            <directory>tests/Browser</directory>
+        </testsuite>
+    </testsuites>
+
+    <source>
+        <include>
+            <directory>app</directory>
+        </include>
+    </source>
+
+    <coverage includeUncoveredFiles="true">
+        <report>
+            <clover outputFile="coverage.xml"/>
+            <text outputFile="php://stdout" showOnlySummary="true"/>
+        </report>
+    </coverage>
+
+    <php>
+        <env name="APP_ENV" value="testing"/>
+        <env name="DB_CONNECTION" value="sqlite"/>
+        <env name="DB_DATABASE" value=":memory:"/>
+    </php>
+</phpunit>
 ```
 
-## Test Template
+## Pest 4 — patterns
+
+### Unit + Feature
 
 ```php
-<?php
+// tests/Unit/Services/UserServiceTest.php
+use App\Services\UserService;
+
+beforeEach(fn () => $this->service = new UserService);
+
+it('creates a user with valid data', function () {
+    $user = $this->service->create(['name' => 'John', 'email' => 'john@test.com']);
+
+    expect($user)
+        ->name->toBe('John')
+        ->email->toBe('john@test.com');
+});
+
+it('rejects invalid email', function () {
+    $this->service->create(['name' => 'John', 'email' => 'invalid']);
+})->throws(InvalidArgumentException::class, 'Invalid email');
+
+dataset('invalid_users', [
+    'empty name'  => [['name' => '',     'email' => 'a@b.com'], 'Name required'],
+    'empty email' => [['name' => 'John', 'email' => ''],        'Email required'],
+    'no data'     => [[],                                        'Name required'],
+]);
+
+it('rejects invalid data', function (array $data, string $expected) {
+    $this->service->create($data);
+})->with('invalid_users')->throws(InvalidArgumentException::class);
+```
+
+### Browser test (Pest 4 — Playwright-backed)
+
+```php
+// tests/Browser/LoginFlowTest.php
+use function Pest\Browser\visit;
+
+it('logs the user in', function () {
+    visit('/login')
+        ->fill('email',    'user@test.com')
+        ->fill('password', 'secret')
+        ->press('Sign in')
+        ->assertPathIs('/dashboard')
+        ->assertSee('Welcome back');
+});
+
+// Multi-viewport smoke
+it('login page is responsive', function (string $device) {
+    visit('/login')
+        ->onDevice($device)            // 'iphone-14', 'ipad', 'desktop-1280'
+        ->assertNoConsoleErrors()
+        ->assertNoBrokenLinks()
+        ->screenshot();
+})->with(['iphone-14', 'ipad', 'desktop-1280']);
+```
+
+### Architecture test (Pest)
 
+```php
+// tests/Arch/LayerBoundariesTest.php
+arch('controllers do not call DB directly')
+    ->expect('App\Http\Controllers')
+    ->not->toUse(['Illuminate\Support\Facades\DB']);
+
+arch('domain layer is framework-free')
+    ->expect('App\Domain')
+    ->not->toUse([
+        'Illuminate\Database',
+        'Illuminate\Http',
+        'Illuminate\Support\Facades',
+    ]);
+
+arch('strict types everywhere')
+    ->expect('App')
+    ->toUseStrictTypes();
+```
+
+### Mutation testing
+
+```bash
+./vendor/bin/pest --mutate --covered-only
+```
+
+Pest mutates your code and re-runs tests; surviving mutants reveal weak assertions.
+
+## PHPUnit 12 — same domain, classic style
+
+```php
+<?php
 declare(strict_types=1);
 
 namespace Tests\Unit\Services;
 
+use PHPUnit\Framework\Attributes\DataProvider;
+use PHPUnit\Framework\Attributes\Test;
 use PHPUnit\Framework\TestCase;
 use App\Services\UserService;
 
@@ -48,80 +215,99 @@ final class UserServiceTest extends TestCase
         $this->service = new UserService();
     }
 
-    public function testCreateUserWithValidData(): void
+    #[Test]
+    public function it_creates_a_user_with_valid_data(): void
     {
-        // Arrange
-        $data = ['name' => 'John', 'email' => 'john@test.com'];
-
-        // Act
-        $user = $this->service->create($data);
-
-        // Assert
-        $this->assertSame('John', $user->name);
-        $this->assertSame('john@test.com', $user->email);
+        $user = $this->service->create(['name' => 'John', 'email' => 'john@test.com']);
+        self::assertSame('John', $user->name);
+        self::assertSame('john@test.com', $user->email);
     }
 
-    public function testCreateUserThrowsOnInvalidEmail(): void
+    #[Test]
+    #[DataProvider('invalidDataProvider')]
+    public function it_rejects_invalid_data(array $data, string $expected): void
     {
         $this->expectException(\InvalidArgumentException::class);
-        $this->expectExceptionMessage('Invalid email');
-
-        $this->service->create(['name' => 'John', 'email' => 'invalid']);
-    }
-
-    /**
-     * @dataProvider invalidDataProvider
-     */
-    public function testCreateUserRejectsInvalidData(array $data, string $expectedError): void
-    {
-        $this->expectException(\InvalidArgumentException::class);
-        $this->expectExceptionMessage($expectedError);
-
+        $this->expectExceptionMessage($expected);
         $this->service->create($data);
     }
 
     public static function invalidDataProvider(): array
     {
         return [
-            'empty name' => [['name' => '', 'email' => 'a@b.com'], 'Name required'],
-            'empty email' => [['name' => 'John', 'email' => ''], 'Email required'],
-            'null data' => [[], 'Name required'],
+            'empty name'  => [['name' => '',     'email' => 'a@b.com'], 'Name required'],
+            'empty email' => [['name' => 'John', 'email' => ''],        'Email required'],
+            'no data'     => [[],                                        'Name required'],
         ];
     }
 }
 ```
 
+> PHPUnit 12 deprecated `/** @test */` and `/** @dataProvider */` annotations — use the `#[Test]` and `#[DataProvider]` attributes shown above.
+
 ## Mocking
 
 ```php
-public function testServiceCallsRepository(): void
-{
-    $repo = $this->createMock(UserRepository::class);
-    $repo->expects($this->once())
-         ->method('save')
-         ->with($this->isInstanceOf(User::class))
-         ->willReturn(true);
+// PHPUnit
+$repo = $this->createMock(UserRepository::class);
+$repo->expects($this->once())
+     ->method('save')
+     ->with($this->isInstanceOf(User::class))
+     ->willReturn(true);
 
-    $service = new UserService($repo);
-    $result = $service->create(['name' => 'John', 'email' => 'j@t.com']);
+// Pest — same engine, fluent
+$repo = mock(UserRepository::class)
+    ->shouldReceive('save')->once()->andReturn(true)
+    ->getMock();
+```
 
-    $this->assertTrue($result);
-}
+For HTTP: `Http::fake()` (Laravel) or Saloon's `MockClient` — see `external-api-patterns`.
+
+## Sharding for CI *(Pest 4 / PHPUnit 12)*
+
+```bash
+# Split a slow suite across 4 runners
+./vendor/bin/pest --parallel --shard=1/4
+./vendor/bin/pest --parallel --shard=2/4
+./vendor/bin/pest --parallel --shard=3/4
+./vendor/bin/pest --parallel --shard=4/4
+```
+
+```yaml
+# .github/workflows/ci.yml
+strategy:
+  matrix:
+    shardIndex: [1, 2, 3, 4]
+    shardTotal: [4]
+steps:
+  - run: ./vendor/bin/pest --parallel --shard=${{ matrix.shardIndex }}/${{ matrix.shardTotal }}
 ```
 
-## Running
+## Coverage Thresholds
 
 ```bash
-vendor/bin/phpunit                          # All tests
-vendor/bin/phpunit tests/Unit/              # Unit only
-vendor/bin/phpunit --filter testCreateUser  # Specific test
-vendor/bin/phpunit --coverage-text          # With coverage
+# Fail under 70%
+./vendor/bin/pest --coverage --min=70
+./vendor/bin/phpunit --coverage-text --min=70
 ```
 
+Realistic 2026 baseline: **70% line coverage minimum**, 100% on Services / Domain layer, lower for Controllers (covered by feature tests anyway).
+
 ## Rules
 
-1. **One assertion concept per test**
-2. **Descriptive method names**: `testMethodName_Scenario_ExpectedResult`
-3. **Use data providers** for multiple inputs
-4. **setUp/tearDown** for shared state
-5. **Never skip tests** in commits
+1. **One concept per test** — don't `@dataProvider` a test that mixes unrelated assertions
+2. **Descriptive names** — `it_rejects_invalid_email`, not `testCreateUser2`
+3. **Datasets / data providers** for input matrices (DRY assertions, named cases)
+4. **`#[Test]` attribute, not `@test` PHPDoc** (PHPUnit 12 deprecated the latter)
+5. **`setUp` for shared fresh state, not shared mutable state**
+6. **Architecture tests on every Laravel project** — enforce layer rules in code, not docs
+7. **Mutation testing on critical Services** quarterly — catches "fake green" suites
+8. **Never `->skip()` / `->only()` in committed code**
+9. **Browser tests use real browsers (Pest 4 Playwright)** — no jsdom hacks
+
+## See Also
+
+- `playwright-automation` (`_shared`) — same Playwright engine Pest 4 uses
+- `quality-gate` — test step ordering
+- `external-api-patterns` — `Http::fake()` / Saloon mocking patterns
+- `phpstan-analysis` — typing that makes tests cheaper

package/stacks/php/skills/security-scan-php/SKILL.md

@@ -1,9 +1,12 @@
 ---
 name: security-scan-php
-version: 1.0.0
+version: 2.0.0
+description: "Laravel-specific security overlay on top of `security-baseline` (OWASP 2021 + 2025 deltas). Mass assignment, Sanctum/policies, Blade XSS, env() pitfalls in Octane, file upload validation, signed URLs, password hashing (Argon2id default since L10), CSRF on web routes, role-aware scoping, supply-chain hardening (composer audit + Roave Security Advisories + gitleaks 3-layer). Cross-references stay aligned with `security-baseline` §A01–§A10 anchors so the security-auditor agent can match. Invoke when reviewing any Laravel feature touching user data, auth, persistence, file IO, or external calls."
 ---
 
-# Laravel Security Scan
+# Laravel Security Scan (overlay on `security-baseline`)
+
+> **This skill is a Laravel overlay.** The universal OWASP rules (with 2025 deltas — Software Supply Chain Failures, Mishandling Exceptional Conditions) live in `_shared/skills/security-baseline`. The §A01–§A10 anchors below match those (2021 numbering kept for security-auditor cross-references).
 
 ## OWASP Top 10 for Laravel
 
@@ -189,15 +192,105 @@ $user = $request->user();
 - [ ] Sensitive headers set (X-Content-Type-Options, X-Frame-Options, CSP)
 - [ ] Rate limiting on authentication endpoints
 
+## Supply-Chain Hardening (OWASP 2025-A03)
+
+Laravel apps inherit every CVE in the Composer tree. The build server is a target.
+
+```bash
+# Production install — never run third-party scripts on the build server
+composer install --no-dev --no-scripts --optimize-autoloader --classmap-authoritative
+
+# Audit (Composer 2.8+) — fail the PR on vulns OR abandoned packages
+composer audit --abandoned=fail --ignore-severity=low
+```
+
+```json
+// composer.json — refuse to install any version with a known CVE
+"require-dev": {
+    "roave/security-advisories": "dev-latest"
+},
+"config": {
+    "allow-plugins": {
+        "pestphp/pest-plugin": true
+        // Add new plugins explicitly. Default-deny.
+    }
+}
+```
+
+Layered secret detection (mirrors `secrets-management` skill):
+
+```yaml
+# .github/workflows/ci.yml
+- uses: gitleaks/gitleaks-action@v2     # Layer 2 — CI scan
+- run: composer audit --abandoned=fail   # Composer-side audit
+```
+
+Layer 1 = pre-commit gitleaks hook locally. Layer 3 = GitHub Push Protection at the org/repo. See `secrets-management` skill for full setup.
+
+---
+
+## Mishandling Exceptional Conditions (OWASP 2025-A10) — Laravel-specific
+
+The new 2025 category. Common Laravel mistakes:
+
+| Anti-pattern | Why dangerous | Fix |
+|---|---|---|
+| `try { Gate::authorize(...) } catch { /* ignore */ }` | Authz fails open — caller proceeds as if allowed | Let it bubble; Laravel maps `AuthorizationException` to 403 |
+| `Render::abort` returning a 500 with full stack trace | Leaks file paths, ORM internals, env hints | Set `APP_DEBUG=false` in prod; custom `app/Exceptions/Handler.php` returns generic problem+json |
+| Webhook handler returns 500 on parse error | Provider retries forever, floods the queue | Verify signature first; on parse error log + return 200 (idempotently dropped) |
+| Partial writes when transaction rolls back partially | Money charged but order not created | `DB::transaction()` closure (auto-rollback) — see `mariadb-octane` |
+| `if (!config('feature.requireMfa')) return $user;` | Missing config = MFA bypassed | Default-deny: `if (config('feature.requireMfa', true) === false && app()->runningInConsole())` — and even then, gate behind explicit env |
+| Octane uncaught exception leaves DB in TX | Next request inherits open TX → cascading failures | `try/finally { DB::rollBack() }` or `DB::transaction()` closure (see `mariadb-octane`) |
+
+```php
+// Correct webhook reception — fail closed on signature, fail open on parse
+public function handle(Request $request): JsonResponse
+{
+    try {
+        $event = \Stripe\Webhook::constructEvent(
+            $request->getContent(),
+            $request->header('Stripe-Signature'),
+            config('services.stripe.webhook_secret'),
+        );
+    } catch (\UnexpectedValueException | \Stripe\Exception\SignatureVerificationException $e) {
+        Log::warning('[stripe] invalid signature', ['err' => $e->getMessage()]);
+        return response()->json(['error' => 'invalid signature'], 400);   // 4xx → provider stops retrying
+    }
+
+    try {
+        ProcessStripeEvent::dispatch($event->type, $event->data->object);
+    } catch (\Throwable $e) {
+        Log::error('[stripe] dispatch failed', ['event' => $event->id, 'err' => $e->getMessage()]);
+        // Acknowledge anyway — we'll reconcile from the webhook log
+    }
+    return response()->json(['status' => 'received']);
+}
+```
+
+---
+
 ## Sensitive Patterns (FORBIDDEN)
 
 | Pattern | Risk |
 |---------|------|
 | `DB::raw()` with user input | SQL Injection |
 | `{!! $userInput !!}` | XSS |
-| `md5()` / `sha1()` for passwords | Weak hashing |
+| `md5()` / `sha1()` for passwords | Weak hashing (Argon2id is the Laravel 10+ default) |
 | Dynamic code execution | RCE |
 | `unserialize()` on user data | Object injection |
 | `$request->all()` without `$fillable` | Mass assignment |
 | `env()` in runtime code | Null after config cache |
 | Static user state in services | Data leaks in Octane |
+| `composer install` with `--ignore-platform-reqs` in prod | Hides incompatible PHP/ext versions |
+| `composer install` in prod **without** `--no-scripts` | Supply-chain RCE on package post-install hooks |
+| Missing `roave/security-advisories` dev dep | Known CVE installs silently |
+| `try { ... } catch { /* nothing */ }` around authz | 2025-A10 fail-open |
+
+## See Also
+
+- `_shared/skills/security-baseline` — universal §A01–§A10 (OWASP 2021 + 2025 deltas)
+- `_shared/skills/secrets-management` — gitleaks 3-layer + OIDC + Roave
+- `_shared/skills/observability` — log redaction
+- `composer-workflow` — `audit` + `roave/security-advisories`
+- `mariadb-octane` — transaction safety in long-lived workers
+- `api-security` — Sanctum cookie SPA + CORS hardening

package/stacks/python/skills/api-security-python/SKILL.md

@@ -1,14 +1,14 @@
 ---
 name: api-security-python
-version: 1.0.0
-description: Production-grade API hardening for Python (FastAPI, Django, Flask). Rate limit, CORS, JWT, secure cookies, CSRF, OAuth2.
+version: 2.0.0
+description: "Python (FastAPI / Django / Flask) overlay on top of _shared/security-baseline v2 (OWASP Top 10:2025). Production-grade hardening: security headers via Starlette middleware and SECURE_* settings, strict CORS allowlist, rate limiting (slowapi / django-ratelimit), HttpOnly+Secure+SameSite cookies, JWT with algorithms=[ALG] pinning + jti for revocation using PyJWT (python-jose is unmaintained as of 2025), CSRF built-in for Django and double-submit cookie for FastAPI, Pydantic V2 extra='forbid' against mass-assignment, file-upload magic-byte sniffing, Argon2id passwords, parameterised SQL/ORM. Cross-references 2025-A03 (Software Supply Chain Failures) and 2025-A10 (Mishandling Exceptional Conditions)."
 ---
 
-# API Security — Python
+# API Security — Python (FastAPI / Django / Flask)
 
 **ALWAYS invoke when building API endpoints, auth flows, or admin actions.**
 
-> Pair this with `security-baseline` for OWASP Top 10. This skill is stack-specific hardening.
+> Stack-specific overlay on top of `_shared/skills/security-baseline` v2 (OWASP Top 10:2025). The shared skill defines §A01–§A10 anchors; this one wires the Python equivalents.
 
 ## Layered Defense
 
@@ -136,13 +136,16 @@ response.set_cookie(
 
 ## 5. JWT / OAuth2 — FastAPI
 
+> **Library choice (2026):** Use **PyJWT** (`pyjwt[crypto]`) or **authlib** for OAuth2/OIDC flows. `python-jose` has been effectively unmaintained since 2024 and should be removed from dependencies. For the resource-server side that just verifies tokens, PyJWT is enough.
+
 ```python
 from datetime import datetime, timedelta, timezone
-from jose import jwt, JWTError
 import os, uuid
+import jwt
+from jwt import InvalidTokenError
 
 SECRET = os.environ["JWT_SECRET"]
-ALG = "HS256"
+ALG = "HS256"                    # use RS256/EdDSA when verifying tokens minted elsewhere
 
 def issue_access_token(user_id: str, role: str) -> str:
     now = datetime.now(timezone.utc)
@@ -151,8 +154,11 @@ def issue_access_token(user_id: str, role: str) -> str:
             "sub": user_id,
             "role": role,
             "iat": now,
+            "nbf": now,
             "exp": now + timedelta(minutes=15),
             "jti": str(uuid.uuid4()),
+            "iss": os.environ["JWT_ISSUER"],
+            "aud": os.environ["JWT_AUDIENCE"],
         },
         SECRET,
         algorithm=ALG,
@@ -160,9 +166,18 @@ def issue_access_token(user_id: str, role: str) -> str:
 
 async def current_user(token: str = Depends(oauth2_scheme)) -> User:
     try:
-        payload = jwt.decode(token, SECRET, algorithms=[ALG])  # pin algorithm
-    except JWTError:
+        payload = jwt.decode(
+            token,
+            SECRET,
+            algorithms=[ALG],                # pin — never accept "alg: none"
+            audience=os.environ["JWT_AUDIENCE"],
+            issuer=os.environ["JWT_ISSUER"],
+            options={"require": ["exp", "iat", "sub", "jti"]},
+        )
+    except InvalidTokenError:
         raise HTTPException(401, "Invalid token")
+    if await is_revoked(payload["jti"]):     # check revocation list (Redis set)
+        raise HTTPException(401, "Token revoked")
     user = await User.get_or_none(id=payload["sub"])
     if not user:
         raise HTTPException(401, "User not found")
@@ -170,9 +185,11 @@ async def current_user(token: str = Depends(oauth2_scheme)) -> User:
 ```
 
 Rules:
-- Access tokens: ≤ 15 min. Refresh tokens: rotate on use, store hash in DB, revocable.
-- Pin `algorithms=[ALG]`. Never accept `alg: none`.
-- Include `jti` for revocation lists.
+- Access tokens ≤ 15 min. Refresh tokens: rotate on use, store **hash** in DB, revocable.
+- Pin `algorithms=[ALG]`. Never accept `alg: none` or omit the kwarg (confusion attack).
+- Always validate `aud` and `iss` when present.
+- Include `jti` and check a revocation set for sensitive scopes.
+- Store JWTs in **HttpOnly+Secure+SameSite cookies**, not `localStorage` (XSS exfiltration).
 
 ---
 
@@ -280,6 +297,91 @@ user = await User.get(id=user_id)                   # Tortoise / SQLAlchemy / Dj
 
 ---
 
+## 11. Outbound calls — SSRF guard (OWASP 2025 still relevant)
+
+SSRF was demoted from a top-level OWASP category in the 2025 list but remains in scope. Any time you fetch a URL the user controls (preview cards, webhooks, image proxies), validate the destination:
+
+```python
+import ipaddress
+import socket
+from urllib.parse import urlparse
+import httpx
+
+PRIVATE = ipaddress.collapse_addresses([
+    ipaddress.ip_network("10.0.0.0/8"),
+    ipaddress.ip_network("172.16.0.0/12"),
+    ipaddress.ip_network("192.168.0.0/16"),
+    ipaddress.ip_network("169.254.0.0/16"),     # link-local + AWS metadata
+    ipaddress.ip_network("127.0.0.0/8"),
+    ipaddress.ip_network("::1/128"),
+])
+
+def safe_url(url: str) -> str:
+    p = urlparse(url)
+    if p.scheme not in {"http", "https"}:
+        raise ValueError("scheme")
+    host = p.hostname
+    if not host:
+        raise ValueError("host")
+    for fam, _, _, _, sockaddr in socket.getaddrinfo(host, None):
+        ip = ipaddress.ip_address(sockaddr[0])
+        if any(ip in net for net in PRIVATE):
+            raise ValueError("private")
+    return url
+
+async def fetch_user_url(url: str):
+    safe_url(url)
+    async with httpx.AsyncClient(timeout=10.0, follow_redirects=False) as c:
+        return await c.get(url)
+```
+
+Disable redirect-following or re-validate every hop — otherwise an attacker can redirect from a public IP to `169.254.169.254` (cloud metadata).
+
+## 12. OWASP 2025 deltas — Python specifics
+
+### §A03 — Software Supply Chain Failures (NEW in 2025)
+
+```toml
+# pyproject.toml — pin everything; uv produces a deterministic lockfile
+[project]
+dependencies = ["fastapi>=0.115,<0.116", "pydantic>=2.6,<3"]
+
+[tool.uv]
+dev-dependencies = ["pip-audit>=2.7", "ruff>=0.5"]
+```
+
+```bash
+# Lock + verify in CI
+uv lock --check                              # fails if lockfile drifted
+uv export --format requirements-txt --no-dev | pip-audit -r /dev/stdin --strict
+```
+
+- Use `uv` (or Poetry) to produce a deterministic lockfile; never `pip install` without one in production.
+- Run `pip-audit` (PyPA) **and** subscribe to GHSA advisories for your deps.
+- Pin GitHub Actions by SHA, not tag — see `_shared/skills/secrets-management`.
+
+### §A10 — Mishandling Exceptional Conditions (NEW in 2025)
+
+```python
+# WRONG — silently swallows everything, including programming bugs
+try:
+    user = await get_user(id)
+except Exception:
+    user = None
+
+# CORRECT — narrow except + log + propagate or translate
+try:
+    user = await get_user(id)
+except UserNotFoundError:
+    raise HTTPException(404, "user not found")
+except DatabaseUnavailableError as e:
+    logger.exception("db-down", extra={"user_id": id})
+    raise HTTPException(503, "service unavailable") from e
+# Programming errors (KeyError, TypeError) are NOT caught — let the global handler 500 + log
+```
+
+Bare `except Exception:` (or worse, `except:`) is now an explicit OWASP pattern to flag. Use `logger.exception()` so the stack trace lands in logs, return a **generic** message to the client, never the original exception text.
+
 ## Endpoint Checklist
 
 - [ ] `Depends(current_user)` for protected routes
@@ -306,7 +408,8 @@ user = await User.get(id=user_id)                   # Tortoise / SQLAlchemy / Dj
 
 ## See Also
 
-- `security-baseline` — OWASP Top 10
-- `secrets-management` — env vars, rotation
-- `pydantic-validation` — schema patterns
-- `observability` — structured logs without PII
+- `_shared/skills/security-baseline` v2 — OWASP Top 10:2025 (§A01–§A10 anchors)
+- `_shared/skills/secrets-management` v2 — OIDC federation, gitleaks 3-layer, SOPS+age
+- `_shared/skills/observability` v2 — structured logs without PII, GenAI semconv 1.41+
+- `pydantic-validation` v2 — `extra="forbid"` against mass-assignment
+- `fastapi-patterns` v2 — lifespan, DI, exception handlers