HashiCorp Vault Secrets Management

naftiko: "1.0.0-alpha1"

info:
  label: "HashiCorp Vault Secrets Management"
  description: "Unified workflow capability for platform engineers and DevOps teams managing secrets with HashiCorp Vault. Combines KV secrets CRUD, version management, metadata operations, and system configuration into a single AI-accessible interface for secrets lifecycle management."
  tags:
    - HashiCorp Vault
    - Secrets Management
    - DevOps
    - Platform Engineering
    - Security
  created: "2026-05-03"
  modified: "2026-05-03"

binds:
  - namespace: env
    keys:
      VAULT_TOKEN: VAULT_TOKEN
      VAULT_ADDR: VAULT_ADDR

capability:
  consumes:
    - import: vault-kv
      location: ./shared/kv-secrets.yaml
    - import: vault-sys
      location: ./shared/sys-backend.yaml

  exposes:
    - type: rest
      port: 8080
      namespace: vault-secrets-api
      description: "Unified REST API for HashiCorp Vault secrets lifecycle management."
      resources:
        - path: /v1/secrets/{path}
          name: secrets
          description: "KV v2 secret CRUD with versioning."
          operations:
            - method: GET
              name: read-secret
              description: "Read a secret from Vault KV v2 by path."
              call: "vault-kv.read-secret"
              with:
                path: "rest.path"
                version: "rest.version"
              outputParameters:
                - type: object
                  mapping: "$."

            - method: POST
              name: write-secret
              description: "Write a secret to Vault KV v2."
              call: "vault-kv.write-secret"
              with:
                path: "rest.path"
                data: "rest.data"
              outputParameters:
                - type: object
                  mapping: "$."

            - method: DELETE
              name: delete-secret
              description: "Soft delete the latest version of a secret."
              call: "vault-kv.delete-latest-secret-version"
              with:
                path: "rest.path"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/secrets/{path}/metadata
          name: secret-metadata
          description: "Secret metadata and version history."
          operations:
            - method: GET
              name: read-secret-metadata
              description: "Read metadata and version history for a secret."
              call: "vault-kv.read-secret-metadata"
              with:
                path: "rest.path"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/auth-methods
          name: auth-methods
          description: "Vault authentication method management."
          operations:
            - method: GET
              name: list-auth-methods
              description: "List all enabled authentication methods."
              call: "vault-sys.list-auth-methods"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/mounts
          name: secrets-mounts
          description: "Vault secrets engine mount management."
          operations:
            - method: GET
              name: list-secrets-mounts
              description: "List all mounted secrets engines."
              call: "vault-sys.list-secrets-mounts"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/policies
          name: policies
          description: "Vault ACL policy management."
          operations:
            - method: GET
              name: list-policies
              description: "List all ACL policies."
              call: "vault-sys.list-policies"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/health
          name: health
          description: "Vault health status."
          operations:
            - method: GET
              name: get-health
              description: "Check Vault health status."
              call: "vault-sys.get-health"
              outputParameters:
                - type: object
                  mapping: "$."

    - type: mcp
      port: 9090
      namespace: vault-secrets-mcp
      transport: http
      description: "MCP server for AI-assisted HashiCorp Vault secrets management workflows."
      tools:
        - name: read-secret
          description: "Read a secret from HashiCorp Vault KV v2 store by path. Returns the secret data and version metadata."
          hints:
            readOnly: true
            openWorld: false
          call: "vault-kv.read-secret"
          with:
            path: "tools.path"
            version: "tools.version"
          outputParameters:
            - type: object
              mapping: "$."

        - name: write-secret
          description: "Write a secret to HashiCorp Vault KV v2. Each write creates a new version."
          hints:
            readOnly: false
            idempotent: false
          call: "vault-kv.write-secret"
          with:
            path: "tools.path"
            data: "tools.data"
          outputParameters:
            - type: object
              mapping: "$."

        - name: delete-secret
          description: "Soft delete the latest version of a secret in Vault. The data can be recovered with undelete."
          hints:
            readOnly: false
            destructive: false
            idempotent: true
          call: "vault-kv.delete-latest-secret-version"
          with:
            path: "tools.path"
          outputParameters:
            - type: object
              mapping: "$."

        - name: read-secret-metadata
          description: "Read metadata and version history for a Vault secret including creation time, current version, and all version states."
          hints:
            readOnly: true
            openWorld: false
          call: "vault-kv.read-secret-metadata"
          with:
            path: "tools.path"
          outputParameters:
            - type: object
              mapping: "$."

        - name: list-auth-methods
          description: "List all authentication methods enabled in Vault including type, path, and configuration."
          hints:
            readOnly: true
            openWorld: false
          call: "vault-sys.list-auth-methods"
          outputParameters:
            - type: object
              mapping: "$."

        - name: list-secrets-mounts
          description: "List all secrets engines mounted in Vault with their type, path, and configuration."
          hints:
            readOnly: true
            openWorld: false
          call: "vault-sys.list-secrets-mounts"
          outputParameters:
            - type: object
              mapping: "$."

        - name: list-policies
          description: "List all ACL policies configured in Vault."
          hints:
            readOnly: true
            openWorld: false
          call: "vault-sys.list-policies"
          outputParameters:
            - type: object
              mapping: "$."

        - name: read-policy
          description: "Read a specific Vault ACL policy by name to view its path-based access rules."
          hints:
            readOnly: true
            openWorld: false
          call: "vault-sys.read-policy"
          with:
            name: "tools.name"
          outputParameters:
            - type: object
              mapping: "$."

        - name: write-policy
          description: "Create or update a Vault ACL policy with HCL rules defining path-based capabilities."
          hints:
            readOnly: false
            idempotent: true
          call: "vault-sys.write-policy"
          with:
            name: "tools.name"
            policy: "tools.policy"
          outputParameters:
            - type: object
              mapping: "$."

        - name: lookup-lease
          description: "Look up a Vault lease by ID to check TTL, expiration time, and renewable status."
          hints:
            readOnly: true
            openWorld: false
          call: "vault-sys.lookup-lease"
          with:
            lease_id: "tools.lease_id"
          outputParameters:
            - type: object
              mapping: "$."

        - name: renew-lease
          description: "Renew a Vault lease to extend the TTL of dynamic secrets and tokens."
          hints:
            readOnly: false
            idempotent: false
          call: "vault-sys.renew-lease"
          with:
            lease_id: "tools.lease_id"
            increment: "tools.increment"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-vault-health
          description: "Check HashiCorp Vault health status including initialized, sealed, and standby state."
          hints:
            readOnly: true
            openWorld: true
          call: "vault-sys.get-health"
          outputParameters:
            - type: object
              mapping: "$."