v0.5.0

This release is everything since v0.4.4.

Breaking

• The gateway now requires AUDIT_URL at boot, because audit is on by default. Set AUDIT_URL to the audit service's internal base URL, e.g. http://audit:3003. If you don't want audit, set AUDIT_ENABLED=false on the gateway. Any value other than true or false refuses boot.
• Route-registry apply now rejects service names that aren't 1–128 characters of [A-Za-z0-9._-]. The audit event's service field has the same limit.
• On organization and member routes that are audited, the gateway writes the audit intent before forwarding. While audit is down, those requests return 503 and the service is not called. Writes are audited by default.
• The gateway's check order changed: authenticate, rate limit, audit intent, then required_labels. A request denied by labels (403) now counts against the rate limit.
• The compose admin role in compose/roles.yml gains org:audit:read. Update your own ROLES_FILE if you want the same.

Added

• Audit service (services/audit, new image). Each audited organization or member request is recorded as one event in the subject org's audit log. The intent is written before the request is forwarded, and the outcome is written afterwards in the background. An event stays pending until its outcome arrives. A dropped or failed outcome write leaves the event pending.

• GET /org/audit-events is published by the audit catalog (services/audit/routes.yml) and requires the label org:audit:read.

• docs/audit.md describes the model and its guarantees.

• Route audit: true|false overrides the default, which is to audit writes. It applies to organization and member routes only.

• The identity invite list (GET /org/invites) sets audit: true, because it returns live tokens.

• Services can report what changed on X-Plat5-Audit-Details. The gateway stores it as sent and always strips it from requests and responses. It accepts one ASCII JSON object of at most 4096 bytes and ignores anything else with a warning.

• Gateway config:

  • AUDIT_ENABLED
  • AUDIT_URL
  • INTERNAL_AUTH_TOKEN is now also sent to audit.

• New metrics:

  • Gateway: audit_writes_total and audit_intent_duration_seconds.
  • Audit service: audit_intents_total and audit_outcomes_total.

• Compose files, CI, and the release workflow now include the audit service.

• Gateway request log lines (request completed and request failed) now carry the following fields, each present only when known:

  • auth_type: jwt, user_apikey, member_apikey, or member_session
  • key_prefix
  • user_id (admitted on user routes)
  • organization_id and member_id (admitted on organization and member routes)

  key_prefix is set before validation, so 401 and 403 lines carry it. It matches key_prefix on identity's key list, or a session's token_prefix. The key, token, and JWT are never logged, and the line has no labels or role (#21).

Changed

• Identity now reports changes to audit as from/to and reports creates by id. It never reports a secret or user_id. A new auditx helper does this for organization, member, service-account, invite, and member-key handlers.
• Organization update now reads the prior values and applies the change in one store call. Previously it read the organization first and saved it afterwards.
• Docs: wording for labels in the gateway route_config comments and in naming-conventions.md now matches the implementation (#20).
• Docs: updated routes.md, gateway-contract.md, identity.md, roles.md, self-hosting.md, and telemetry.md for audit.

Fixed

• Route-registry apply now refuses routes that can't be recorded in the audit log.
• The audit service reads the org's prior state under the lock, so concurrent writes see consistent prior values.

Images

All at v0.5.0:

• ghcr.io/plat5dev/gateway:v0.5.0
• ghcr.io/plat5dev/route-registry:v0.5.0
• ghcr.io/plat5dev/identity:v0.5.0
• ghcr.io/plat5dev/audit:v0.5.0

Compose images are pinned to v0.5.0 (PLAT5_VERSION).

Full changelog: v0.4.4...v0.5.0