@emilia-protocol/gate 0.9.5 → 0.10.0

package/deploy/terraform/service/outputs.tf

@@ -0,0 +1,19 @@
+output "service_name" {
+  description = "ClusterIP Service name."
+  value       = kubernetes_service_v1.gate.metadata[0].name
+}
+
+output "service_dns" {
+  description = "In-cluster DNS name for the Gate service."
+  value       = "${kubernetes_service_v1.gate.metadata[0].name}.${var.namespace}.svc"
+}
+
+output "deployment_name" {
+  description = "Gate Deployment name."
+  value       = kubernetes_deployment_v1.gate.metadata[0].name
+}
+
+output "migration_job_name" {
+  description = "Migration Job name, or null when migrations are disabled."
+  value       = var.migration_enabled ? kubernetes_job_v1.migration[0].metadata[0].name : null
+}

package/deploy/terraform/service/tests/validate.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+module_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+terraform_bin="${TERRAFORM_BIN:-terraform}"
+
+if ! command -v "$terraform_bin" >/dev/null 2>&1; then
+  echo "terraform is required (or set TERRAFORM_BIN)" >&2
+  exit 127
+fi
+
+"$terraform_bin" fmt -check -recursive "$module_dir"
+
+tmp_dir="$(mktemp -d)"
+trap 'rm -rf "$tmp_dir"' EXIT
+cp "$module_dir"/*.tf "$tmp_dir"/
+cp -R "$module_dir/tests" "$tmp_dir/tests"
+
+TF_DATA_DIR="$tmp_dir/.terraform" "$terraform_bin" -chdir="$tmp_dir" init \
+  -backend=false -input=false >/dev/null
+TF_DATA_DIR="$tmp_dir/.terraform" "$terraform_bin" -chdir="$tmp_dir" validate
+TF_DATA_DIR="$tmp_dir/.terraform" "$terraform_bin" -chdir="$tmp_dir" test
+
+echo "Terraform formatting, provider-schema, and validation-contract tests passed"

package/deploy/terraform/service/tests/validation.tftest.hcl

@@ -0,0 +1,168 @@
+mock_provider "kubernetes" {}
+
+run "valid_distinct_migration_and_secret_env" {
+  command = plan
+
+  variables {
+    namespace                      = "gate-system"
+    image                          = "registry.example.test/security/emilia-gate-service@sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+    configuration_secret_name      = "gate-configuration"
+    postgres_secret_name           = "gate-postgres"
+    migration_postgres_secret_name = "gate-postgres-migrate"
+    migration_postgres_secret_key  = "database-url"
+    api_token_secret_name          = "gate-api-token"
+    issuer_roots_secret_name       = "gate-issuer-roots"
+    github_token_secret_name       = "gate-github"
+    github_token_secret_key        = "token"
+    secret_env = {
+      SIEM_TOKEN = {
+        secret_name = "gate-siem"
+        secret_key  = "token"
+      }
+    }
+  }
+
+  assert {
+    condition = anytrue([
+      for item in kubernetes_deployment_v1.gate.spec[0].template[0].spec[0].container[0].env :
+      item.name == "GITHUB_TOKEN"
+      && try(item.value_from[0].secret_key_ref[0].name == "gate-github", false)
+    ])
+    error_message = "GitHub token must render only as a secretKeyRef."
+  }
+
+  assert {
+    condition = anytrue([
+      for item in kubernetes_deployment_v1.gate.spec[0].template[0].spec[0].container[0].env :
+      item.name == "SIEM_TOKEN"
+      && try(item.value_from[0].secret_key_ref[0].name == "gate-siem", false)
+    ])
+    error_message = "Generic secret environment input must render as a secretKeyRef."
+  }
+
+  assert {
+    condition = anytrue([
+      for item in kubernetes_job_v1.migration[0].spec[0].template[0].spec[0].container[0].env :
+      item.name == "DATABASE_URL"
+      && try(item.value_from[0].secret_key_ref[0].name == "gate-postgres-migrate", false)
+    ])
+    error_message = "Migration Job must use the distinct migration Secret."
+  }
+
+  assert {
+    condition = (
+      kubernetes_deployment_v1.gate.spec[0].template[0].spec[0].container[0].startup_probe[0].http_get[0].path == "/v1/live"
+      && kubernetes_deployment_v1.gate.spec[0].template[0].spec[0].container[0].liveness_probe[0].http_get[0].path == "/v1/live"
+      && kubernetes_deployment_v1.gate.spec[0].template[0].spec[0].container[0].readiness_probe[0].http_get[0].path == "/v1/ready"
+    )
+    error_message = "Gate probes must use the service live and ready routes."
+  }
+}
+
+run "reject_explicit_latest_image" {
+  command = plan
+
+  variables {
+    namespace                      = "gate-system"
+    image                          = "registry.example.test/security/emilia-gate-service:latest"
+    configuration_secret_name      = "gate-configuration"
+    postgres_secret_name           = "gate-postgres"
+    migration_postgres_secret_name = "gate-postgres-migrate"
+    migration_postgres_secret_key  = "database-url"
+    api_token_secret_name          = "gate-api-token"
+    issuer_roots_secret_name       = "gate-issuer-roots"
+  }
+
+  expect_failures = [var.image]
+}
+
+run "reject_implicit_latest_image" {
+  command = plan
+
+  variables {
+    namespace                      = "gate-system"
+    image                          = "registry.example.test/security/emilia-gate-service"
+    configuration_secret_name      = "gate-configuration"
+    postgres_secret_name           = "gate-postgres"
+    migration_postgres_secret_name = "gate-postgres-migrate"
+    migration_postgres_secret_key  = "database-url"
+    api_token_secret_name          = "gate-api-token"
+    issuer_roots_secret_name       = "gate-issuer-roots"
+  }
+
+  expect_failures = [var.image]
+}
+
+run "reject_missing_migration_secret" {
+  command = plan
+
+  variables {
+    namespace                 = "gate-system"
+    image                     = "registry.example.test/security/emilia-gate-service@sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+    configuration_secret_name = "gate-configuration"
+    postgres_secret_name      = "gate-postgres"
+    api_token_secret_name     = "gate-api-token"
+    issuer_roots_secret_name  = "gate-issuer-roots"
+  }
+
+  expect_failures = [kubernetes_job_v1.migration]
+}
+
+run "reject_equal_migration_secret" {
+  command = plan
+
+  variables {
+    namespace                      = "gate-system"
+    image                          = "registry.example.test/security/emilia-gate-service@sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+    configuration_secret_name      = "gate-configuration"
+    postgres_secret_name           = "gate-postgres"
+    migration_postgres_secret_name = "gate-postgres"
+    migration_postgres_secret_key  = "database-url"
+    api_token_secret_name          = "gate-api-token"
+    issuer_roots_secret_name       = "gate-issuer-roots"
+  }
+
+  expect_failures = [kubernetes_job_v1.migration]
+}
+
+run "allow_disabled_migration_without_secret" {
+  command = plan
+
+  variables {
+    namespace                 = "gate-system"
+    image                     = "registry.example.test/security/emilia-gate-service@sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+    configuration_secret_name = "gate-configuration"
+    postgres_secret_name      = "gate-postgres"
+    api_token_secret_name     = "gate-api-token"
+    issuer_roots_secret_name  = "gate-issuer-roots"
+    migration_enabled         = false
+  }
+
+  assert {
+    condition     = length(kubernetes_job_v1.migration) == 0
+    error_message = "Disabled migrations must not create a Job."
+  }
+}
+
+run "reject_secret_env_override" {
+  command = plan
+
+  variables {
+    namespace                      = "gate-system"
+    image                          = "registry.example.test/security/emilia-gate-service@sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+    configuration_secret_name      = "gate-configuration"
+    postgres_secret_name           = "gate-postgres"
+    migration_postgres_secret_name = "gate-postgres-migrate"
+    migration_postgres_secret_key  = "database-url"
+    api_token_secret_name          = "gate-api-token"
+    issuer_roots_secret_name       = "gate-issuer-roots"
+    secret_env = {
+      DATABASE_URL = {
+        secret_name = "attacker-secret"
+        secret_key  = "database-url"
+      }
+    }
+  }
+
+  expect_failures = [kubernetes_deployment_v1.gate]
+}

package/deploy/terraform/service/variables.tf

@@ -0,0 +1,459 @@
+variable "name" {
+  description = "Kubernetes resource name prefix."
+  type        = string
+  default     = "emilia-gate-service"
+
+  validation {
+    condition     = can(regex("^[a-z0-9]([-a-z0-9]*[a-z0-9])?$", var.name)) && length(var.name) <= 52
+    error_message = "name must be a DNS label no longer than 52 characters."
+  }
+}
+
+variable "namespace" {
+  description = "Existing Kubernetes namespace in which to deploy."
+  type        = string
+
+  validation {
+    condition     = can(regex("^[a-z0-9]([-a-z0-9]*[a-z0-9])?$", var.namespace))
+    error_message = "namespace must be a Kubernetes DNS label."
+  }
+}
+
+variable "image" {
+  description = "Complete BYOC image reference built from Dockerfile.gate. No official public image is implied. Use a digest in production."
+  type        = string
+
+  validation {
+    condition = (
+      trimspace(var.image) == var.image
+      && (
+        can(regex("@sha256:[a-f0-9]{64}$", var.image))
+        || (
+          can(regex(":[A-Za-z0-9_][A-Za-z0-9._-]{0,127}$", element(reverse(split("/", var.image)), 0)))
+          && !endswith(lower(var.image), ":latest")
+        )
+      )
+    )
+    error_message = "image must use an explicit non-latest tag or sha256 digest; untagged and implicit-latest references are refused."
+  }
+}
+
+variable "image_pull_policy" {
+  description = "Kubernetes image pull policy."
+  type        = string
+  default     = "IfNotPresent"
+
+  validation {
+    condition     = contains(["Always", "IfNotPresent", "Never"], var.image_pull_policy)
+    error_message = "image_pull_policy must be Always, IfNotPresent, or Never."
+  }
+}
+
+variable "image_pull_secrets" {
+  description = "Names of existing image pull Secrets."
+  type        = list(string)
+  default     = []
+}
+
+variable "replicas" {
+  description = "Gate service replicas. Two is the production-shaped default."
+  type        = number
+  default     = 2
+
+  validation {
+    condition     = var.replicas >= 1 && floor(var.replicas) == var.replicas
+    error_message = "replicas must be a positive integer."
+  }
+}
+
+variable "port" {
+  description = "Gate service container and ClusterIP port."
+  type        = number
+  default     = 8080
+
+  validation {
+    condition     = var.port >= 1 && var.port <= 65535
+    error_message = "port must be between 1 and 65535."
+  }
+}
+
+variable "log_level" {
+  description = "EP_GATE_LOG_LEVEL passed to the service."
+  type        = string
+  default     = "info"
+
+  validation {
+    condition     = contains(["debug", "info", "warn", "error"], var.log_level)
+    error_message = "log_level must be debug, info, warn, or error."
+  }
+}
+
+variable "configuration_secret_name" {
+  description = "Name of an existing Secret containing the operator-owned gate.config.mjs and migrate.mjs modules."
+  type        = string
+
+  validation {
+    condition     = trimspace(var.configuration_secret_name) != ""
+    error_message = "configuration_secret_name is required."
+  }
+}
+
+variable "configuration_secret_key" {
+  description = "Key in configuration_secret_name containing the apps/gate-service ESM config module."
+  type        = string
+  default     = "gate.config.mjs"
+}
+
+variable "migration_script_secret_key" {
+  description = "Key in configuration_secret_name containing the idempotent migration module."
+  type        = string
+  default     = "migrate.mjs"
+}
+
+variable "configuration_mount_path" {
+  description = "Read-only directory where operator configuration modules are mounted."
+  type        = string
+  default     = "/app/config"
+}
+
+variable "postgres_secret_name" {
+  description = "Name of an existing Secret containing the Postgres connection URL. Only the reference is stored by Terraform."
+  type        = string
+
+  validation {
+    condition     = trimspace(var.postgres_secret_name) != ""
+    error_message = "postgres_secret_name is required."
+  }
+}
+
+variable "postgres_secret_key" {
+  description = "Key in postgres_secret_name containing the connection URL."
+  type        = string
+  default     = "database-url"
+}
+
+variable "postgres_env_name" {
+  description = "Runtime environment variable populated from the Postgres Secret."
+  type        = string
+  default     = "DATABASE_URL"
+}
+
+variable "migration_postgres_secret_name" {
+  description = "Existing Secret for a DDL-capable migration login. Required when migration_enabled is true and must differ from postgres_secret_name."
+  type        = string
+  default     = null
+  nullable    = true
+}
+
+variable "migration_postgres_secret_key" {
+  description = "Key in migration_postgres_secret_name containing the migration URL. Required when migration_enabled is true."
+  type        = string
+  default     = null
+  nullable    = true
+}
+
+variable "api_token_secret_name" {
+  description = "Name of an existing Secret containing the Gate action-API bearer token. Only the reference is stored by Terraform."
+  type        = string
+
+  validation {
+    condition     = trimspace(var.api_token_secret_name) != ""
+    error_message = "api_token_secret_name is required."
+  }
+}
+
+variable "api_token_secret_key" {
+  description = "Key in api_token_secret_name containing the Gate API token."
+  type        = string
+  default     = "api-token"
+}
+
+variable "api_token_env_name" {
+  description = "Runtime environment variable populated from the Gate API-token Secret."
+  type        = string
+  default     = "EMILIA_GATE_API_TOKEN"
+}
+
+variable "kms_secret_name" {
+  description = "Optional existing Secret containing KMS configuration used by an operator extension. The Gate service itself does not mint or require a signing key."
+  type        = string
+  default     = null
+  nullable    = true
+
+  validation {
+    condition     = var.kms_secret_name == null ? true : trimspace(var.kms_secret_name) != ""
+    error_message = "kms_secret_name must be null or non-empty."
+  }
+}
+
+variable "kms_secret_key" {
+  description = "Key in kms_secret_name containing the KMS key identifier/config."
+  type        = string
+  default     = "kms-key-id"
+}
+
+variable "kms_env_name" {
+  description = "Runtime environment variable populated from the KMS Secret."
+  type        = string
+  default     = "EP_KMS_KEY_ID"
+}
+
+variable "issuer_roots_secret_name" {
+  description = "Name of an existing Secret containing the pinned issuer-root set. Only the reference is stored by Terraform."
+  type        = string
+
+  validation {
+    condition     = trimspace(var.issuer_roots_secret_name) != ""
+    error_message = "issuer_roots_secret_name is required."
+  }
+}
+
+variable "issuer_roots_secret_key" {
+  description = "Key in issuer_roots_secret_name containing the pinned issuer-root set."
+  type        = string
+  default     = "issuer-roots.json"
+}
+
+variable "issuer_roots_env_name" {
+  description = "Runtime environment variable populated from the issuer-roots Secret."
+  type        = string
+  default     = "EP_GATE_ISSUER_ROOTS"
+}
+
+variable "github_token_secret_name" {
+  description = "Optional existing Secret containing a GitHub token. Only the Secret reference enters Terraform state."
+  type        = string
+  default     = null
+  nullable    = true
+
+  validation {
+    condition     = var.github_token_secret_name == null ? true : can(regex("^[a-z0-9]([-a-z0-9.]*[a-z0-9])?$", var.github_token_secret_name))
+    error_message = "github_token_secret_name must be null or a Kubernetes Secret name."
+  }
+}
+
+variable "github_token_secret_key" {
+  description = "Key in github_token_secret_name containing the GitHub token."
+  type        = string
+  default     = "token"
+
+  validation {
+    condition     = trimspace(var.github_token_secret_key) != ""
+    error_message = "github_token_secret_key must be non-empty."
+  }
+}
+
+variable "github_token_env_name" {
+  description = "Runtime environment variable populated from github_token_secret_name."
+  type        = string
+  default     = "GITHUB_TOKEN"
+
+  validation {
+    condition     = can(regex("^[A-Za-z_][A-Za-z0-9_]*$", var.github_token_env_name))
+    error_message = "github_token_env_name must be a valid environment variable name."
+  }
+}
+
+variable "secret_env" {
+  description = "Additional runtime environment variables populated from existing Kubernetes Secrets. Values are references only; secret bytes never enter this module."
+  type = map(object({
+    secret_name = string
+    secret_key  = string
+  }))
+  default = {}
+
+  validation {
+    condition = alltrue([
+      for env_name, reference in var.secret_env :
+      can(regex("^[A-Za-z_][A-Za-z0-9_]*$", env_name))
+      && trimspace(reference.secret_name) != ""
+      && trimspace(reference.secret_key) != ""
+    ])
+    error_message = "secret_env keys must be environment variable names and each Secret name/key must be non-empty."
+  }
+}
+
+variable "extra_env" {
+  description = "Additional non-secret literal environment variables. Use external Secret wiring for sensitive values."
+  type        = map(string)
+  default     = {}
+}
+
+variable "migration_enabled" {
+  description = "Run the database migration Job before the Deployment. Keep enabled outside controlled recovery operations."
+  type        = bool
+  default     = true
+}
+
+variable "migration_command" {
+  description = "Command run by the migration Job."
+  type        = list(string)
+  default     = ["node", "/app/config/migrate.mjs"]
+
+  validation {
+    condition     = length(var.migration_command) > 0
+    error_message = "migration_command must contain at least one element."
+  }
+}
+
+variable "migration_revision" {
+  description = "Bump when migration inputs change without changing the image; it is included in the immutable Job name."
+  type        = string
+  default     = "schema-v1"
+}
+
+variable "migration_active_deadline_seconds" {
+  description = "Maximum migration Job runtime."
+  type        = number
+  default     = 600
+}
+
+variable "migration_backoff_limit" {
+  description = "Migration Job retry limit."
+  type        = number
+  default     = 3
+}
+
+variable "resources" {
+  description = "Service container requests and limits."
+  type = object({
+    requests = map(string)
+    limits   = map(string)
+  })
+  default = {
+    requests = {
+      cpu    = "100m"
+      memory = "128Mi"
+    }
+    limits = {
+      cpu    = "1"
+      memory = "512Mi"
+    }
+  }
+}
+
+variable "migration_resources" {
+  description = "Migration Job requests and limits."
+  type = object({
+    requests = map(string)
+    limits   = map(string)
+  })
+  default = {
+    requests = {
+      cpu    = "50m"
+      memory = "64Mi"
+    }
+    limits = {
+      cpu    = "500m"
+      memory = "256Mi"
+    }
+  }
+}
+
+variable "pdb_enabled" {
+  description = "Create a PodDisruptionBudget for service pods."
+  type        = bool
+  default     = true
+}
+
+variable "pdb_min_available" {
+  description = "Minimum service pods available during voluntary disruption."
+  type        = string
+  default     = "1"
+}
+
+variable "network_policy_enabled" {
+  description = "Create default-deny and explicit allow NetworkPolicies for gate and migration pods."
+  type        = bool
+  default     = true
+}
+
+variable "allow_same_namespace_ingress" {
+  description = "Allow pods in the deployment namespace to reach the gate service port."
+  type        = bool
+  default     = true
+}
+
+variable "dns_namespace_labels" {
+  description = "Namespace selector labels for cluster DNS."
+  type        = map(string)
+  default = {
+    "kubernetes.io/metadata.name" = "kube-system"
+  }
+}
+
+variable "dns_pod_labels" {
+  description = "Pod selector labels for cluster DNS."
+  type        = map(string)
+  default = {
+    "k8s-app" = "kube-dns"
+  }
+}
+
+variable "postgres_port" {
+  description = "Postgres egress port."
+  type        = number
+  default     = 5432
+}
+
+variable "postgres_pod_labels" {
+  description = "Same-namespace Postgres pod selector. Set to an empty map when using only managed-Postgres CIDRs."
+  type        = map(string)
+  default = {
+    "app.kubernetes.io/name" = "postgresql"
+  }
+}
+
+variable "postgres_egress_cidrs" {
+  description = "Stable managed-Postgres or egress-proxy CIDRs allowed on postgres_port."
+  type        = list(string)
+  default     = []
+}
+
+variable "kms_egress_cidrs" {
+  description = "Stable KMS proxy/NAT CIDRs allowed on TCP 443. Standard NetworkPolicy cannot select KMS FQDNs."
+  type        = list(string)
+  default     = []
+}
+
+variable "github_egress_cidrs" {
+  description = "Stable GitHub egress-proxy CIDRs allowed on TCP 443. Prefer an FQDN-aware CNI policy over public IP snapshots."
+  type        = list(string)
+  default     = []
+}
+
+variable "siem_egress_cidrs" {
+  description = "Stable SIEM egress-proxy CIDRs allowed on TCP 443. Prefer an FQDN-aware CNI policy for SaaS SIEM endpoints."
+  type        = list(string)
+  default     = []
+}
+
+variable "pod_annotations" {
+  description = "Additional service pod annotations."
+  type        = map(string)
+  default     = {}
+}
+
+variable "labels" {
+  description = "Additional labels added to resources. Do not override selector labels."
+  type        = map(string)
+  default     = {}
+}
+
+variable "node_selector" {
+  description = "Service pod node selector."
+  type        = map(string)
+  default     = {}
+}
+
+variable "tolerations" {
+  description = "Service pod tolerations in Kubernetes provider shape."
+  type = list(object({
+    key                = optional(string)
+    operator           = optional(string)
+    value              = optional(string)
+    effect             = optional(string)
+    toleration_seconds = optional(number)
+  }))
+  default = []
+}

package/deploy/terraform/service/versions.tf

@@ -0,0 +1,10 @@
+terraform {
+  required_version = ">= 1.6.0"
+
+  required_providers {
+    kubernetes = {
+      source  = "hashicorp/kubernetes"
+      version = ">= 2.31.0, < 3.0.0"
+    }
+  }
+}