TramAI - governed AI workflows for Java and Kotlin

tramai-security

Version: 0.6.0
Status: Preview
Role: Governance core — policy decisions, approval lifecycle, tamper-evident audit and evidence for AI invocations.

Purpose

tramai-security owns TramAI's governance semantics. It provides the deny-by-default policy engine, the DLP interceptor, the approval-gate machinery, the audit engine with hash-chained storage and the runtime evidence exporters that record what the runtime decided.

It is consumed by tramai-sovereign, by the tramai-spring-sovereign integration, and by any application that wants policy enforcement without adopting the full sovereign profile.

What it provides

Policy

  • DefaultPolicyEngine(config: PolicyConfiguration) — evaluates every EnforcementPoint: BEFORE_PROVIDER_RESOLUTION, BEFORE_PROVIDER_INVOCATION, BEFORE_FALLBACK, BEFORE_TOOL_EXPOSURE, BEFORE_TOOL_EXECUTION, BEFORE_TOOL_RESULT_REINJECTION, BEFORE_RESPONSE_RETURN, BEFORE_WORKFLOW_RESUME.
  • PolicyConfiguration.secure() — the secure baseline: every allowlist is empty, so unknown tools, models and providers are denied; HIGH and CRITICAL risk tools require approval.
  • PolicyConfiguration.preview() — a permissive preset for 0.4.x migration and testing only: wildcard allowlists (*) bypass most registry checks. Never use it as a production posture.
  • ProviderRoutingConfiguration + ProviderTrustZone (LOCAL, EU_CLOUD, GLOBAL_CLOUD) — the classification-aware routing matrix that decides which trust zones a data classification may reach.

DLP

  • RuleBasedDlpInterceptor with RuleBasedDlpConfiguration / DlpRule — redacts provider-bound and provider-returned payloads.

Approval

  • dev.tramai.security.approval.* — DefaultApprovalGateCoordinator, InMemoryApprovalStore, InMemoryApprovalContinuationStore, SecureRandomApprovalTokenGenerator, Sha256ApprovalTokenDigester, Sha256ToolArgumentsDigester, UuidApprovalIdGenerator. Durable implementations come from tramai-persistence-file or tramai-persistence-jdbc.

Audit and evidence

  • dev.tramai.security.audit.* — AuditEngine(store, clock), AuditStore, InMemoryAuditStore, AuditChainVerifier, and the emitters AuditEnginePolicyDecisionAuditEmitter, AuditEngineDlpRedactionAuditEmitter, AuditEngineApprovalLifecycleAuditEmitter. Events are sequenced per stream and hash-chained via previousEventHash.
  • dev.tramai.security.evidence.* — PolicyDecisionRuntimeEvidenceExporter, ToolPermissionRuntimeEvidenceExporter.
  • dev.tramai.security.model.InMemoryModelRegistry — an approved-model registry for local composition and tests.

Dependencies

dependencies {
    implementation(platform("dev.tramai:tramai-bom:0.6.0"))
    implementation("dev.tramai:tramai-security")
}

val policy = DefaultPolicyEngine(
    PolicyConfiguration.secure().copy(
        allowedModels = setOf("gpt-4o"),
        allowedProviders = setOf("openai"),
        allowedTools = setOf("customer_lookup"),
    ),
)

val auditEngine = AuditEngine(store = InMemoryAuditStore())

When to use this module

  • You need policy decisions, approval gates or an audit trail on AI invocations.
  • You are embedding the sovereign profile and want its building blocks directly.
  • You are implementing a custom PolicyEngine, DlpInterceptor or AuditStore and want the reference implementations and TCKs.

When NOT to use this module

  • You want the runtime already sealed and validated end to end — use tramai-sovereign.
  • You need persistence: this module keeps state in memory; durable stores live in the persistence modules.
  • You need framework integration — this module has no Spring dependency, by design.
Previous
Next