kms: the spec now declares the API the server actually serves

55 path groups down to 14. The 52 removed were inherited from Infisical and the
server has never served any of them: organizations, projects, environments,
tags, folders, secret-imports, identities, service-tokens, integrations,
/v1/kms/v4/secrets, /v1/kms/auth/universal-auth/*, /v1/kms/auth/login1.

This file is not documentation, it is a generator. SDKs in every language are
built from it, so the fiction shipped as real client code — and the breakage
stayed invisible, because the binary answered every unmatched path with its
embedded console SPA (200 text/html). A wrong URL read as a decode error rather
than a 404. luxfi/kms 1.12.8 removed that catch-all and those paths now return
honest JSON 404s, which is how this was found: four hand-written clients and at
least one generated one were all calling routes that do not exist.

What remains is verified against cmd/kms/main.go and probed live:

  POST   /v1/kms/auth/login                    the ONLY auth route
  GET    /v1/kms/orgs/{org}/secrets            list names (mirrors ZAP OpSecretList)
  POST   /v1/kms/orgs/{org}/secrets            create AND replace — one upsert
  GET    /v1/kms/orgs/{org}/secrets/{rest}     read one value
  DELETE /v1/kms/orgs/{org}/secrets/{rest}     delete
  GET    /healthz /health /v1/kms/healthz /v1/kms/health
  /v1/kms/keys/* + /v1/kms/status              MPC-gated; 404 on a secrets-only KMS
  POST   /v1/sdk/secrets                       envelope-signed plane

Corrections beyond deletions:

- The secret routes previously advertised PATCH. There is no PATCH. Create and
  replace are the same POST, because the store has one upsert.
- The list route existed on the ZAP wire (OpSecretList 0x0042) but not over HTTP
  until luxfi/kms 1.12.9. It is declared now, so generated clients stop having to
  open a ZAP connection or give up — giving up is what one of them did.
- The MPC key routes were declared at /v1/kms/kms/keys, a doubled prefix. The
  server serves /v1/kms/keys/*.
- {rest} now documents the rule that bites every client: the server splits it at
  its LAST slash into (path, name), so segments must be escaped individually —
  escaping the joined string encodes the separators away and the server reads one
  long name.
- The MPC-gated routes say plainly that they 404 on a secrets-only deployment
  rather than appearing unconditionally available.
- 43 schemas down to 2; the rest described the deleted surface.

Co-authored-by: Hanzo Dev <[email protected]>

This commit is contained in:

zeekay

2026-07-26 08:38:18 -07:00

co-authored by

Hanzo Dev

parent 3bd8edf79f

commit 16fb403c8d

1 changed files with 403 additions and 3633 deletions

kms/openapi.yaml

+403 -3633

View File

File diff suppressed because it is too large Load Diff