tramai-spring-secrets-file

Version: 0.6.0
Status: Preview
Role: Secret-backend module: resolves file: references from a permitted directory.

Purpose

This module contributes the core file: secret resolver to TramAI's Spring secret chain, so any *-secret-ref property can point at a file on disk. It participates in the bootstrap chain: file: references therefore work for the credentials that other resolver modules need for their own bootstrapping (for example a Vault token stored in a file).

FileSecretValueResolver itself lives in tramai-core; this module binds its configuration and marks it as a bootstrap resolver through FileSecretValueResolverAutoConfiguration.

What it provides

Reference semantics:

• A reference looks like file:secrets/openai.key. Relative paths resolve against the allowed directory; absolute paths are accepted only if they stay inside it.
• A path that escapes the allowed directory is rejected with an IllegalArgumentException.
• file: resolution without an allowed directory fails with IllegalStateException("file: secret resolution is disabled; …").
• A missing file resolves to nothing, which surfaces as the usual unresolved-secret startup failure on the property that referenced it: No SecretValueResolver could resolve '<ref>' for <field>.

Dependencies

dependencies {
    implementation(platform("dev.tramai:tramai-bom:0.6.0"))
    implementation("dev.tramai:tramai-spring-boot-starter")
    implementation("dev.tramai:tramai-spring-secrets-file")
}

tramai:
  secrets:
    file:
      allowed-directory: /etc/tramai/secrets
  providers:
    openai:
      api-key-secret-ref: file:openai.key

When to use this module

• Credentials are provisioned as files (Docker/Kubernetes secret mounts, air-gapped hosts) rather than environment variables.
• Another secret backend needs a file-backed bootstrap credential.

When NOT to use this module

• The secret lives in a secret manager: use tramai-spring-secrets-vault or tramai-spring-secrets-aws.
• The value can come from the environment — env: references work without any module.
• You want to point at an arbitrary path: the allowed directory is enforced, not advisory.