@emilia-protocol/gate 0.9.4 → 0.10.0

package/deploy/terraform/README.md

@@ -1,6 +1,6 @@
 <!-- SPDX-License-Identifier: Apache-2.0 -->
 
-# EMILIA Gate — reference Terraform module (`EP-GATE-TF-v1`)
+# EMILIA Gate — deprecated Terraform module (`EP-GATE-TF-v1`)
 
 Terraform sibling of the Helm chart (`../helm`, `EP-GATE-HELM-v1`) for BYOC
 (bring-your-own-cloud) installs of the Trusted Action Firewall. Same container
@@ -13,6 +13,10 @@ in a cluster **you** control:
 | `kubernetes_deployment_v1.gate` | The gate pods — non-root, read-only rootfs, no privilege escalation, all capabilities dropped, no service-account token; pinned issuer keys arrive via a non-optional `secretKeyRef` to **your** Secret |
 | `kubernetes_service_v1.gate` | Cluster-internal Service (ClusterIP by default) in front of the pods |
 
+**Deprecated:** this legacy module may run per-process in-memory consumption and
+evidence state. New deployments should use `./service`, which targets
+`apps/gate-service` and requires durable operator adapters.
+
 **Honest framing:** this is a *reference module* and it is *experimental*. It
 is a starting point for your platform team to review, fork, and own — not a
 managed service, not a turnkey production install. The deployer's cluster, the
@@ -57,8 +61,9 @@ module "emilia_gate" {
   namespace = "emilia"                                  # must already exist
   image     = "ghcr.io/your-org/emilia-gate@sha256:..." # pin a digest
 
-  replicas                = 2
+  replicas                = 1
   issuer_keys_secret_name = "emilia-gate-issuer-keys" # NAME only, never keys
+  github_token_secret_name = "emilia-gate-github"
 
   # The deny-by-default policy the gate enforces (EP-ACTION-RISK-MANIFEST).
   manifest_json = file("${path.module}/manifest.json")
@@ -85,9 +90,11 @@ policy change rolls the pods.
 | `EP_GATE_MANIFEST_PATH` | ConfigMap mount | `/etc/emilia-gate/action-risk-manifest.json` |
 | `EP_GATE_METRICS_ENABLED` | `metrics_enabled` | `false` |
 | `EP_GATE_ISSUER_KEYS` | `secretKeyRef` → your existing Secret | — (required) |
+| `GITHUB_TOKEN` | `github_token_secret_name` → existing Secret | — (optional) |
 
 Extra plain-text env goes in `extra_env` — **never secrets** (values in that
-map land in Terraform state); wire secret env from your own Secrets.
+map land in Terraform state). Use `secret_env` for generic non-optional
+`secretKeyRef` entries; the module accepts Secret names/keys, never values.
 
 ## Inputs
 
@@ -99,7 +106,10 @@ map land in Terraform state); wire secret env from your own Secrets.
 | `issuer_keys_secret_key` | `issuer-keys.json` | Key inside that Secret |
 | `name` | `emilia-gate` | DNS-1123 label |
 | `namespace` | `default` | Must already exist |
-| `replicas` | `2` | See replay-defense note below |
+| `replicas` | `1` | Values above one require both shared backend references |
+| `shared_consumption_backend`, `shared_evidence_backend` | `null` | Secret-backed adapter environment references required above one replica |
+| `github_token_secret_name` | `null` | Existing GitHub token Secret reference |
+| `secret_env` | `{}` | Generic environment-to-existing-Secret references |
 | `port` / `service_port` | `8080` / `8080` | |
 | `service_type` | `ClusterIP` | Anything more exposed is your explicit call |
 | `log_level` | `info` | `error` \| `warn` \| `info` \| `debug` |
@@ -116,12 +126,11 @@ Outputs: `service_name`, `namespace`, `service_endpoint`, `deployment_name`,
 
 ## Operational notes
 
-- **Replay defense across replicas:** with `replicas > 1`, one-time receipt
-  consumption is only fleet-safe if the gate is configured with a *shared*
-  durable consumption store (Redis/Postgres — see
-  `createDurableConsumptionStore` in `@emilia-protocol/gate`). The module
-  deploys the pods either way; pointing them at a shared store (e.g. via
-  `extra_env`) is your configuration responsibility.
+- **Replay defense across replicas:** the module refuses `replicas > 1` unless
+  both `shared_consumption_backend` and `shared_evidence_backend` provide
+  complete Secret-backed environment references. That proves wiring exists,
+  not that a custom legacy image implements the required atomic adapters;
+  prefer the service module.
 - **Namespace:** not created by this module — pass one that exists.
 - **Ingress/TLS/NetworkPolicy/ServiceMonitor:** intentionally out of scope.
   The default posture is cluster-internal; exposure decisions belong to the
@@ -129,10 +138,11 @@ Outputs: `service_name`, `namespace`, `service_endpoint`, `deployment_name`,
 
 ## What has been validated
 
-`terraform fmt -check`, `terraform init -backend=false`, and
-`terraform validate` pass against Terraform 1.9.8 with
+`packages/gate/deploy/terraform/tests/validate.sh` runs formatting, provider
+schema validation, and mocked plan tests that cover the one-replica default,
+multi-replica refusal, and Secret-backed environment rendering. It uses
+Terraform 1.9.8 with
 `hashicorp/kubernetes` 2.38. A create-only `terraform plan` renders all three
-resources, and the plan-time input validations (unparseable manifest, inline
-key material, zero replicas) refuse as designed. The module has **not** been
+resources, and the plan-time input validations refuse unsafe scaling. The module has **not** been
 applied against a live cluster as part of this repo's CI — treat it as
 reviewed reference code, not a certified install path.

package/deploy/terraform/main.tf

@@ -35,6 +35,8 @@ locals {
     "app.kubernetes.io/part-of"         = "emilia-protocol"
     "emiliaprotocol.ai/module-contract" = local.module_version
     "emiliaprotocol.ai/maturity"        = "experimental"
+    "emiliaprotocol.ai/deprecated"      = "true"
+    "emiliaprotocol.ai/replacement"     = "emilia-gate-service"
   }, var.extra_labels)
 
   selector_labels = {
@@ -45,6 +47,34 @@ locals {
   # Same paths as the Helm chart's container contract.
   manifest_mount_dir = "/etc/emilia-gate"
   manifest_file      = "action-risk-manifest.json"
+
+  secret_env_references = concat(
+    var.shared_consumption_backend == null ? [] : [var.shared_consumption_backend],
+    var.shared_evidence_backend == null ? [] : [var.shared_evidence_backend],
+    var.github_token_secret_name == null ? [] : [{
+      env_name    = var.github_token_env_name
+      secret_name = var.github_token_secret_name
+      secret_key  = var.github_token_secret_key
+    }],
+    [for env_name, reference in var.secret_env : {
+      env_name    = env_name
+      secret_name = reference.secret_name
+      secret_key  = reference.secret_key
+    }],
+  )
+  configurable_env_names = concat(
+    [for reference in local.secret_env_references : reference.env_name],
+    keys(var.extra_env),
+  )
+  reserved_env_names = toset([
+    "NODE_ENV",
+    "EP_GATE_PORT",
+    "EP_GATE_LOG_LEVEL",
+    "EP_GATE_EVIDENCE_STRICT",
+    "EP_GATE_MANIFEST_PATH",
+    "EP_GATE_METRICS_ENABLED",
+    "EP_GATE_ISSUER_KEYS",
+  ])
 }
 
 # The policy the gate enforces. Plain ConfigMap: the manifest is deny-by-default
@@ -156,6 +186,20 @@ resource "kubernetes_deployment_v1" "gate" {
             }
           }
 
+          dynamic "env" {
+            for_each = { for index, reference in local.secret_env_references : tostring(index) => reference }
+            content {
+              name = env.value.env_name
+              value_from {
+                secret_key_ref {
+                  name     = env.value.secret_name
+                  key      = env.value.secret_key
+                  optional = false
+                }
+              }
+            }
+          }
+
           dynamic "env" {
             for_each = var.extra_env
             content {
@@ -233,6 +277,21 @@ resource "kubernetes_deployment_v1" "gate" {
       }
     }
   }
+
+  lifecycle {
+    precondition {
+      condition     = var.replicas == 1 || (var.shared_consumption_backend != null && var.shared_evidence_backend != null)
+      error_message = "The deprecated legacy module refuses replicas > 1 without both shared_consumption_backend and shared_evidence_backend Secret references. Prefer terraform/service."
+    }
+    precondition {
+      condition     = length(distinct(local.configurable_env_names)) == length(local.configurable_env_names)
+      error_message = "Secret-backed and literal environment variables must not use duplicate names."
+    }
+    precondition {
+      condition     = length(setintersection(toset(local.configurable_env_names), local.reserved_env_names)) == 0
+      error_message = "secret_env and extra_env must not override module-managed environment variables."
+    }
+  }
 }
 
 resource "kubernetes_service_v1" "gate" {

package/deploy/terraform/service/README.md

@@ -0,0 +1,81 @@
+# EMILIA Gate service Terraform module
+
+This Kubernetes module deploys the BYOC image built from `Dockerfile.gate`. It
+does not publish, default, or make a claim about an official EMILIA image.
+
+The module creates a dedicated token-free ServiceAccount, migration Job,
+two-replica Deployment, ClusterIP Service, PDB, and additive default-deny
+NetworkPolicies. The migration Job is network-restricted, waits to complete,
+and gates Deployment creation. Its immutable name includes the image, command,
+and `migration_revision`; bump the revision when migration inputs change
+without changing the image.
+
+Only existing Secret names and keys enter Terraform. The operator config,
+Postgres URL, Gate API token, and issuer roots are read at pod start with
+non-optional references. Their values are not module variables and therefore
+are not written to Terraform state by this module. The configuration Secret
+must contain `gate.config.mjs` and `migrate.mjs`; these remain operator-owned
+because `apps/gate-service` defines durable adapter contracts rather than
+shipping an unsafe generic production fallback.
+
+Set `migration_postgres_secret_name` and `migration_postgres_secret_key` to a
+separate DDL-capable login Secret. Migrations enabled with a missing Secret or
+the runtime Secret name are rejected; there is no fallback. The module cannot
+compare Secret contents, so provision genuinely distinct credentials. The
+long-lived service should use a least-privilege role that cannot alter schema.
+
+## Example
+
+```hcl
+module "emilia_gate" {
+  source = "./packages/gate/deploy/terraform/service"
+
+  namespace = "emilia-gate"
+  image     = "registry.example.com/security/emilia-gate-service@sha256:REPLACE"
+
+  configuration_secret_name = "emilia-gate-configuration"
+  postgres_secret_name     = "emilia-gate-postgres"
+  migration_postgres_secret_name = "emilia-gate-postgres-migrate"
+  migration_postgres_secret_key  = "database-url"
+  api_token_secret_name    = "emilia-gate-api-token"
+  issuer_roots_secret_name = "emilia-gate-issuer-roots"
+  github_token_secret_name = "emilia-gate-github"
+
+  secret_env = {
+    SIEM_TOKEN = {
+      secret_name = "emilia-gate-siem"
+      secret_key  = "token"
+    }
+  }
+
+  # For managed Postgres, disable the in-cluster selector and allow only the
+  # stable database endpoint or egress-proxy CIDR.
+  postgres_pod_labels  = {}
+  postgres_egress_cidrs = ["10.40.12.8/32"]
+
+  # Standard NetworkPolicy cannot select FQDNs. Prefer stable egress proxies
+  # or an FQDN-aware CNI policy for KMS, GitHub, and SaaS SIEM endpoints.
+  kms_egress_cidrs    = ["10.40.20.10/32"]
+  github_egress_cidrs = ["10.40.20.11/32"]
+  siem_egress_cidrs   = ["10.40.20.12/32"]
+}
+```
+
+Configure the `kubernetes` provider in the calling root module. Create the
+namespace and all Secrets outside this module. GitHub and generic secret-backed
+environment inputs render only non-optional `secretKeyRef` metadata; Secret
+values never become variables, Deployment literals, or module-managed state.
+Prefer an immutable image digest
+and a remote Terraform state backend with encryption and access logging even
+though this module stores Secret references only.
+
+## Clusterless validation
+
+```bash
+packages/gate/deploy/terraform/service/tests/validate.sh
+```
+
+The script runs formatting checks, initializes the Kubernetes provider schema
+in a temporary directory, runs `terraform validate`, and executes mocked plan
+tests for migration credential separation and Secret-backed environment wiring.
+It does not configure credentials or contact a Kubernetes cluster.