# HCMS Compliance Shield

**Shared microservice encoding Suriname compliance rules. Consumed by HUMANABLE, ATLAS, and future HCMS apps via internal HTTP API.**

- Authoritative spec: `HCMS-FO-ComplianceShield-v1.0-2026.md`
- Owner: HCMS N.V. (subsidiary of K&K Heritage Group N.V.)
- Service owners: HCMS Compliance Advisor (business) + IQT Lead (technical)
- Phase: **0 (Bootstrap) — complete**

> **Internal-only.** This service is never exposed to the public internet. It binds to `localhost:8003` on the shared LiquidNet VPS and is reachable only via the internal `compliance-shield.internal` hostname. Read [CLAUDE.md](CLAUDE.md) before contributing.

---

## Stack

| Layer | Choice |
| :---- | :---- |
| Framework | Laravel 13 / PHP 8.3+ |
| Local DB | SQLite |
| Production DB | PostgreSQL 16 + pgvector (schema `compliance_shield`) |
| Auth | Laravel Sanctum service tokens (`tokenable = ConsumerApp`) |
| Admin | Filament 4 |
| Cache / queue / session | Laravel `database` driver |
| Monitoring | Laravel Pulse + self-hosted Sentry |
| Hosting | Shared LiquidNet US VPS (port 8003) |

No Docker, no Redis, no Meilisearch, no managed cloud services — per FO §11.

## Local setup

```bash
cp .env.example .env
php artisan key:generate
touch database/database.sqlite
composer install
php artisan migrate --seed
php artisan serve --host=127.0.0.1 --port=8003
```

Seeded service tokens for HUMANABLE and ATLAS are written to `storage/app/private/compliance-shield/seeded-tokens.json` (gitignored). Copy the values into the corresponding consumer app `.env` files, then delete the file. **Rotate before staging deploy.**

A Filament admin user is seeded for local development (`compliance-advisor@hcmsnv.local` / `password`). For staging/production, create users with `php artisan make:filament-user`.

## API surface (v1)

All endpoints require a Sanctum bearer token in `Authorization: Bearer <token>` (except `/api/v1/health`). Every response sets `X-Correlation-Id` and `X-Rule-Version-Applied` headers, and every request is persisted to `request_log`.

| Method | Endpoint | Module |
| :---- | :---- | :---- |
| GET | `/api/v1/health` | — (public) |
| GET | `/api/v1/rule-versions` | — |
| POST | `/api/v1/tax/pre-flight` | 1 (`tax_pre_flight`) |
| GET | `/api/v1/tax/historical/{tax_calculation_id}` | 1 |
| POST | `/api/v1/article-1639/check` | 2 (`article_1639`) |
| POST | `/api/v1/article-1639/clean-break/initiate` | 2 |
| POST | `/api/v1/work-permit/pre-screen` | 3 (`work_permit`) |
| GET | `/api/v1/work-permit/required-documents/{role_type}` | 3 |
| POST | `/api/v1/local-content/report/generate` | 4 (`local_content`) |
| GET | `/api/v1/local-content/report/{report_id}` | 4 |
| POST | `/api/v1/ai-audit/log` | **5 (`ai_act`)** |
| POST | `/api/v1/ai-audit/override` | 5 |
| GET | `/api/v1/ai-audit/subject/{subject_id}` | 5 |
| POST | `/api/v1/bias/scan` | 6 (`bias_detection`) |
| POST | `/api/v1/gdpr/request` | 7 (`gdpr`) |
| GET | `/api/v1/gdpr/request/{request_id}/status` | 7 |
| POST | `/api/v1/gdpr/request/{request_id}/fulfill` | 7 |
| POST | `/api/v1/right-to-work/verify` | 8 (`right_to_work`) |
| GET | `/api/v1/right-to-work/expirations/{employer_id}` | 8 |
| GET | `/api/v1/admin/audit-log` | — (admin) |

Phase 0 ships stub endpoints (HTTP 501) for all eight modules. Real logic ships in Phases 2–5 per FO §10.

## Consumer integration

Each consumer app holds one long-lived service token. Example call from HUMANABLE:

```php
$response = Http::withToken(config('services.compliance_shield.token'))
    ->acceptJson()
    ->post(config('services.compliance_shield.url').'/api/v1/ai-audit/log', [
        'subject_ref' => 'candidate:'.$candidate->id,
        'ai_agent_name' => 'HUMANABLE.TriageAgent',
        // ...
    ]);

if (! $response->successful()) {
    // BLOCK the workflow. Never silent-fall-through. (FO §4.3)
    throw new ComplianceShieldUnavailable;
}

$ruleVersion = $response->header('X-Rule-Version-Applied');
// Log $ruleVersion for cross-app audit trail.
```

Module allowlisting: `ConsumerApp::$allowed_modules` controls which modules a given consumer can call. An empty/null allowlist grants full access.

## Tests

```bash
php artisan test
```

Phase 0 ships three feature test suites covering health, service-token auth, module allowlisting, request logging, and rule-version stamping (10 tests / 41 assertions).

## Production deployment outline (DevOps — out of scope for this repo)

1. Provision Compliance Shield space on the shared LiquidNet VPS (same server as HUMANABLE + ATLAS).
2. Create PostgreSQL schema `compliance_shield` on the shared database server.
3. Configure Nginx to route `compliance-shield.internal:8003` (no public DNS).
4. systemd unit `compliance-shield.service` runs `php-fpm` behind Nginx.
5. systemd unit `compliance-shield-queue.service` runs the queue worker.
6. Cron entry runs `php artisan schedule:run` every minute.
7. Sentry DSN configured in `.env`.
8. Rotate seeded tokens; issue new ones via Filament Admin → Consumer Apps.

## License

Proprietary — HCMS N.V. (a K&K Heritage Group N.V. company).