feat!: secure configJson credentials, slimmer client contract (#5, #8, #9)

[schmunk42]

Closes #5, closes #8, closes #9.

Summary

#8 — credentials in configJson

• Every operation of ApiConfiguration, reads and /health included, requires ROLE_ADMIN.
• Type schemas mark secret keys with "writeOnly": true (nested objects, $ref, oneOf, list items, maps).
• Marked keys are encrypted at rest (CredentialEncryption, Doctrine onFlush listener), masked as ******** in responses and validator logs, and decrypted only in ApiClientFactory.
• PUT/PATCH: an omitted key or the mask keeps the stored secret, null removes it, nothing carries over when type changes.
• No usable key → SecretEncryptionException, never clear text. Configurations without secrets need no key.
• app:api-configuration:encrypt-secrets [--dry-run] encrypts existing rows, idempotent.

#9 — client contract

• ApiClientInterface keeps what every source supports; getCustomers(), getTodoLists(), hasChanges() move to CustomerAwareApiClientInterface, TodoListAwareApiClientInterface, ChangeProbeInterface.
• authenticate(): void throws AuthenticationFailedException with the transport exception as previous.
• ApiClientFactory::create() validates the decrypted config against the extension's schema.json (InvalidConfigurationException names the field; _-prefixed keys are skipped).
• HealthProbeInterface for types without a full client (schema-only types, MCP); ApiConfigurationHealthChecker is shared by the health route and command.
• Health route keeps metadata/error keys in JSON-LD (api_sub_level).

Fixes

• Write operations return HTTP 500 when no config schema provider is registered (empty anyOf) #5: with no configuration schema registered, writes returned HTTP 500 (anyOf must have at least one element); the validator now reports a violation (422). Root cause stays in SchemaRegistry::getUnifiedSchema() emits invalid empty anyOf when no providers are registered openapi-json-schema-bundle#3.
• symfony/validator declared; it was used directly but only installed transitively (CI resolved 8.1).
• app:api:test-connection and app:api:validate-file called non-existent entity methods (getCredentials(), getFileConfig()); both now go through the client, validate-file delegates to FileApiClientInterface::validateFile()/parseFile().

Breaking changes

Listed in CHANGELOG.md; release as 0.5.0.

1. Reads require ROLE_ADMIN (no option to restore ROLE_USER).
2. Secrets are masked in responses, also for admins.
3. getConfigJson() returns enc:v1:… for marked keys; code reading secrets from the entity directly must use ConfigSecrets::decrypt().
4. A usable CREDENTIALS_ENCRYPTION_KEY is required once a secret is stored.
5. ApiClientInterface slimmer; authenticate() returns void and throws.
6. ApiClientFactory rejects configs that violate the extension schema.
7. Constructor changes in ApiClientFactory, ApiConfigurationValidator, CreateApiConfigurationCommand, ApiConfigurationHealthProvider, ApiConfigurationHealthCommand (autowired consumers unaffected).

Required downstream changes

• Key: dmstr_api_platform_utils.credential_encryption.key: '%env(base64:CREDENTIALS_ENCRYPTION_KEY)%' — CredentialEncryption expects raw bytes, dmstr:generate-encryption-key prints base64. Then run app:api-configuration:encrypt-secrets once.
• Schemas: add "writeOnly": true to password, token, client_secret and equivalents in every type schema (adapters in the applications, flowable bundle, MCP type). Unmarked keys stay clear text.
• Clients (Basecamp 2/4, GitHub, GitLab, Jira XML):
  • authenticate(): void, rethrow via AuthenticationFailedException::fromPrevious($apiName, $e);
  • drop stubs, implement only the capability interfaces the source supports;
  • hasChanges() must fail open — the Jira XML client currently returns false on error;
  • required-field isset() checks in createClient() can go.
• Callers (scanners, sync): instanceof checks before getCustomers(), getTodoLists(), hasChanges(); a client without ChangeProbeInterface counts as changed. Catch AuthenticationFailedException instead of checking a bool.
• Extensions reading secrets from the entity (e.g. an OAuth client secret in buildAuthorizeUrl()): decrypt with ConfigSecrets::decrypt().
• Non-admin consumers of /api/admin/api_configurations (including /health) need ROLE_ADMIN.

Tests

44 tests, 119 assertions (GitHub Actions, PHP 8.4): encryption round trip and idempotence, masking, keep-on-update rules, missing/wrong key, re-encryption command and onFlush listener against SQLite, ROLE_ADMIN on every operation, factory schema validation, health probe vs. client fallback, health operation metadata. Known limitation, not changed here: the validator checks against the unified anyOf schema of SchemaRegistry, which cannot resolve a type schema's local $ref: #/definitions/… (opis Unresolved reference). No type schema in the known applications uses local refs; ApiClientFactory validates against the extension's own schema and is not affected.

Not covered end-to-end (needs a kernel): the 403 over HTTP and the JSON-LD output of /health.

🤖 Generated with Claude Code

[schmunk42]

@eluhr Breaking Changes in 0.5.0-beta1 upcoming - FYI