# Phase 15 — External Integrations and REST API

Phase 15 adds an airline-scoped REST API, generic integration-provider registry, encrypted credential storage, and an auditable outbound webhook queue. It does not expose or implement GPS, ADS-B, or any other live aircraft tracking.

## Files created

- `database/migrations/2026_07_19_000016_create_external_integrations_api_tables.php`
- `config/integrations.php`
- `routes/api.php`
- `app/Core/ApiContext.php`, `ApiErrorResponse.php`, `CredentialCipher.php`, and `DomainWebhookPublisher.php`
- `app/Core/Middleware/ApiMiddleware.php` and `ApiScopeMiddleware.php`
- `app/Modules/Integrations/Controllers/ApiController.php` and `IntegrationController.php`
- `app/Modules/Integrations/Repositories/ApiResourceRepository.php`, `ApiSecurityRepository.php`, and `IntegrationRepository.php`
- `app/Modules/Integrations/Services/ApiSecurityService.php` and `IntegrationService.php`
- Generic provider and transport contracts in `app/Shared/Integrations/`, plus the native HTTPS webhook transport
- `resources/views/integrations/index.php`

## Files modified

- Application bootstrap, request JSON parsing, installer key generation, web routes, navigation, environment example, permission seed data, tests, README, and generated frontend assets
- Flight scheduling/operations, fleet, maintenance, expenses, and finance services now publish the ten supported domain webhook events after successful domain changes

## Database migration added

Migration `2026_07_19_000016` creates: `api_clients`, `api_tokens`, `api_permissions`, `api_request_logs`, `webhook_endpoints`, `webhook_events`, `webhook_deliveries`, `integration_providers`, `integration_credentials`, `integration_logs`, and `failed_integration_jobs`.

Deploy to a configured MySQL 8 environment with:

```bash
php cli migrate
php cli seed
```

The seed step adds `integrations.view`, `integrations.manage`, and `integrations.replay` and assigns them to the intended default roles.

## Security controls added

- Bearer tokens are generated with cryptographic randomness and retained only as SHA-256 hashes; expiry and explicit revocation are enforced.
- Exact API scopes, airline isolation, server-side domain permissions, optional client IP/CIDR restrictions, and token-specific rate limits are enforced before controllers run.
- Mutation requests require JSON and a client-scoped idempotency key. A changed payload cannot reuse a completed key.
- API responses use stable JSON error envelopes with request IDs and masked server errors; request metadata and outcomes are retained in the API request log.
- Provider credentials and webhook secrets use AES-256-GCM. `APP_KEY` is generated by the installer; a mode-0600 ignored storage key is the manual-development fallback.
- Webhook URLs require HTTPS and reject credentials, fragments, and private/reserved network targets to reduce SSRF exposure.
- Deliveries use a timestamped HMAC-SHA256 signature, event UUID/idempotency headers, bounded timeouts, exponential retry, terminal failure retention, and permission-protected manual replay.
- All integration administration remains behind session authentication, CSRF, RBAC, audit logging, security headers, and escaped server-rendered output.

## Tests performed

- Full application suite: `php tests/run.php` — 56 passed, 0 failed.
- Verified all API resource collections, token hashing, invalid/revoked token rejection, scope denial, request logging, response envelopes, and mutation idempotency conflict/replay.
- Verified event deduplication, signature validation, successful delivery, retry, terminal failure record, and manual replay.
- Verified provider contracts, encrypted credential persistence, protected administration UI, and existing Phase 1–14 regression coverage.
- PHP syntax validation passed for every PHP file under `app`, `database`, `routes`, `config`, `resources/views`, and `tests`.
- Tailwind and Alpine/esbuild production assets rebuilt successfully using the bundled Node runtime.

## Remaining known limitations

- The current workspace has no configured `.env` database connection, so `php cli migrate` and `migrate:status` could not be executed against a live MySQL 8 instance here; both correctly reported `Database connection failed`. The migration was syntax-checked and its functional schema is exercised by the SQLite test harness.
- Webhook processing is synchronous through the protected administration action. Production should invoke the same queue service from a scheduled worker/CLI command.
- Provider interfaces are intentionally generic; vendor-specific adapters, inbound webhook handlers, external email/SMS/WhatsApp delivery, and cloud-storage implementations remain deployment-specific.
- API pagination returns page/per-page metadata but does not yet calculate a total row count or emit cursor pagination.
- There is no live aircraft tracking by design.