@emilia-protocol/gate 0.9.0 → 0.9.1

package/deploy/helm/emilia-gate/templates/deployment.yaml

@@ -0,0 +1,134 @@
+# SPDX-License-Identifier: Apache-2.0
+# emilia-gate reference chart (EP-GATE-HELM-v1) — Deployment.
+# Single-container gate service. Env-driven config; issuer keys come from an
+# EXISTING Secret (never rendered here); the action-risk manifest is mounted
+# read-only from a ConfigMap. Fails closed: rendering aborts without a
+# pinned-issuer Secret reference.
+{{- $name := default .Chart.Name .Values.nameOverride }}
+{{- $fullname := default (printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-") .Values.fullnameOverride }}
+{{- $manifestConfigMap := default $fullname .Values.manifest.existingConfigMap }}
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: {{ $fullname }}
+  namespace: {{ .Release.Namespace }}
+  labels:
+    app.kubernetes.io/name: {{ $name }}
+    app.kubernetes.io/instance: {{ .Release.Name }}
+    app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
+    app.kubernetes.io/component: trusted-action-firewall
+    app.kubernetes.io/managed-by: {{ .Release.Service }}
+    helm.sh/chart: {{ printf "%s-%s" .Chart.Name .Chart.Version }}
+    emiliaprotocol.ai/chart-contract: EP-GATE-HELM-v1
+    emiliaprotocol.ai/maturity: experimental
+spec:
+  replicas: {{ .Values.replicaCount }}
+  selector:
+    matchLabels:
+      app.kubernetes.io/name: {{ $name }}
+      app.kubernetes.io/instance: {{ .Release.Name }}
+  template:
+    metadata:
+      labels:
+        app.kubernetes.io/name: {{ $name }}
+        app.kubernetes.io/instance: {{ .Release.Name }}
+        app.kubernetes.io/component: trusted-action-firewall
+        {{- with .Values.podLabels }}
+        {{- toYaml . | nindent 8 }}
+        {{- end }}
+      annotations:
+        {{- if not .Values.manifest.existingConfigMap }}
+        # Roll pods when the rendered action-risk manifest changes.
+        checksum/manifest: {{ include (print $.Template.BasePath "/configmap.yaml") . | sha256sum }}
+        {{- end }}
+        {{- with .Values.podAnnotations }}
+        {{- toYaml . | nindent 8 }}
+        {{- end }}
+    spec:
+      {{- with .Values.imagePullSecrets }}
+      imagePullSecrets:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      # The gate never talks to the Kubernetes API — do not mount a token.
+      automountServiceAccountToken: false
+      securityContext:
+        {{- toYaml .Values.podSecurityContext | nindent 8 }}
+      containers:
+        - name: gate
+          image: "{{ .Values.image.repository }}:{{ default .Chart.AppVersion .Values.image.tag }}"
+          imagePullPolicy: {{ .Values.image.pullPolicy }}
+          securityContext:
+            {{- toYaml .Values.containerSecurityContext | nindent 12 }}
+          ports:
+            - name: http
+              containerPort: {{ .Values.gate.port }}
+              protocol: TCP
+          env:
+            - name: NODE_ENV
+              value: production
+            - name: EP_GATE_PORT
+              value: {{ .Values.gate.port | quote }}
+            - name: EP_GATE_LOG_LEVEL
+              value: {{ .Values.gate.logLevel | quote }}
+            # Strict evidence log: never authorize an action the gate cannot
+            # durably account for.
+            - name: EP_GATE_EVIDENCE_STRICT
+              value: {{ .Values.gate.evidenceStrict | quote }}
+            - name: EP_GATE_MANIFEST_PATH
+              value: /etc/emilia-gate/{{ .Values.manifest.fileName }}
+            - name: EP_GATE_METRICS_ENABLED
+              value: {{ .Values.metrics.enabled | quote }}
+            # Pinned issuer keys — REFERENCED from an existing Secret, never
+            # rendered into the chart. `required` makes helm refuse to render
+            # a gate with no pinned issuers: fail closed.
+            - name: EP_GATE_ISSUER_KEYS
+              valueFrom:
+                secretKeyRef:
+                  name: {{ required "issuerKeys.existingSecret is required. This chart NEVER renders key material — create the Secret out-of-band (see README.md) and set issuerKeys.existingSecret to its name." .Values.issuerKeys.existingSecret }}
+                  key: {{ .Values.issuerKeys.secretKey }}
+            {{- with .Values.gate.extraEnv }}
+            {{- toYaml . | nindent 12 }}
+            {{- end }}
+          livenessProbe:
+            httpGet:
+              path: {{ .Values.probes.liveness.path }}
+              port: http
+            initialDelaySeconds: {{ .Values.probes.liveness.initialDelaySeconds }}
+            periodSeconds: {{ .Values.probes.liveness.periodSeconds }}
+            timeoutSeconds: {{ .Values.probes.liveness.timeoutSeconds }}
+            failureThreshold: {{ .Values.probes.liveness.failureThreshold }}
+          readinessProbe:
+            httpGet:
+              path: {{ .Values.probes.readiness.path }}
+              port: http
+            initialDelaySeconds: {{ .Values.probes.readiness.initialDelaySeconds }}
+            periodSeconds: {{ .Values.probes.readiness.periodSeconds }}
+            timeoutSeconds: {{ .Values.probes.readiness.timeoutSeconds }}
+            failureThreshold: {{ .Values.probes.readiness.failureThreshold }}
+          resources:
+            {{- toYaml .Values.resources | nindent 12 }}
+          volumeMounts:
+            - name: action-risk-manifest
+              mountPath: /etc/emilia-gate
+              readOnly: true
+            # Writable scratch for the runtime; rootfs stays read-only.
+            - name: tmp
+              mountPath: /tmp
+      volumes:
+        - name: action-risk-manifest
+          configMap:
+            name: {{ $manifestConfigMap }}
+        - name: tmp
+          emptyDir: {}
+      {{- with .Values.nodeSelector }}
+      nodeSelector:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      {{- with .Values.tolerations }}
+      tolerations:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      {{- with .Values.affinity }}
+      affinity:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}

package/deploy/helm/emilia-gate/templates/service.yaml

@@ -0,0 +1,28 @@
+# SPDX-License-Identifier: Apache-2.0
+# emilia-gate reference chart (EP-GATE-HELM-v1) — Service.
+{{- $name := default .Chart.Name .Values.nameOverride }}
+{{- $fullname := default (printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-") .Values.fullnameOverride }}
+apiVersion: v1
+kind: Service
+metadata:
+  name: {{ $fullname }}
+  namespace: {{ .Release.Namespace }}
+  labels:
+    app.kubernetes.io/name: {{ $name }}
+    app.kubernetes.io/instance: {{ .Release.Name }}
+    app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
+    app.kubernetes.io/component: trusted-action-firewall
+    app.kubernetes.io/managed-by: {{ .Release.Service }}
+    helm.sh/chart: {{ printf "%s-%s" .Chart.Name .Chart.Version }}
+    emiliaprotocol.ai/chart-contract: EP-GATE-HELM-v1
+    emiliaprotocol.ai/maturity: experimental
+spec:
+  type: {{ .Values.service.type }}
+  ports:
+    - name: http
+      port: {{ .Values.service.port }}
+      targetPort: http
+      protocol: TCP
+  selector:
+    app.kubernetes.io/name: {{ $name }}
+    app.kubernetes.io/instance: {{ .Release.Name }}

package/deploy/helm/emilia-gate/templates/servicemonitor.yaml

@@ -0,0 +1,41 @@
+# SPDX-License-Identifier: Apache-2.0
+# emilia-gate reference chart (EP-GATE-HELM-v1) — optional ServiceMonitor STUB.
+# Gated behind metrics.enabled; scrapes the gate's /metrics endpoint. Requires
+# the Prometheus Operator CRDs (monitoring.coreos.com/v1) to be installed —
+# installing this chart with metrics.enabled=true on a cluster without them
+# will fail at apply time. Stub: adapt relabelings/TLS to your monitoring
+# stack.
+{{- if .Values.metrics.enabled }}
+{{- $name := default .Chart.Name .Values.nameOverride }}
+{{- $fullname := default (printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-") .Values.fullnameOverride }}
+apiVersion: monitoring.coreos.com/v1
+kind: ServiceMonitor
+metadata:
+  name: {{ $fullname }}
+  namespace: {{ .Release.Namespace }}
+  labels:
+    app.kubernetes.io/name: {{ $name }}
+    app.kubernetes.io/instance: {{ .Release.Name }}
+    app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
+    app.kubernetes.io/component: trusted-action-firewall
+    app.kubernetes.io/managed-by: {{ .Release.Service }}
+    helm.sh/chart: {{ printf "%s-%s" .Chart.Name .Chart.Version }}
+    emiliaprotocol.ai/chart-contract: EP-GATE-HELM-v1
+    emiliaprotocol.ai/maturity: experimental
+    {{- with .Values.metrics.serviceMonitor.additionalLabels }}
+    {{- toYaml . | nindent 4 }}
+    {{- end }}
+spec:
+  selector:
+    matchLabels:
+      app.kubernetes.io/name: {{ $name }}
+      app.kubernetes.io/instance: {{ .Release.Name }}
+  namespaceSelector:
+    matchNames:
+      - {{ .Release.Namespace }}
+  endpoints:
+    - port: http
+      path: {{ .Values.metrics.path }}
+      interval: {{ .Values.metrics.serviceMonitor.interval }}
+      scrapeTimeout: {{ .Values.metrics.serviceMonitor.scrapeTimeout }}
+{{- end }}

package/deploy/helm/emilia-gate/values.yaml

@@ -0,0 +1,169 @@
+# SPDX-License-Identifier: Apache-2.0
+# Default values for the emilia-gate reference chart (EP-GATE-HELM-v1).
+#
+# HONEST LABEL: reference chart, experimental, BYOC. Review before use.
+#
+# SECURITY INVARIANTS (fail-closed by design):
+#   1. Issuer key material is NEVER rendered by this chart. You MUST create a
+#      Kubernetes Secret out-of-band and point issuerKeys.existingSecret at
+#      it — templating fails (helm refuses to render) if it is unset.
+#   2. The evidence log defaults to strict mode: the gate refuses to authorize
+#      an action it cannot durably account for.
+#   3. Pod security defaults are hardened (non-root, read-only rootfs, no
+#      capabilities, no service-account token). Loosen deliberately, not
+#      accidentally.
+
+replicaCount: 2
+
+image:
+  # BYOC: build and push your own image of the gate service; there is no
+  # official public image while the chart is experimental.
+  repository: ghcr.io/emilia-protocol/gate
+  # Defaults to the chart's appVersion when empty.
+  tag: ""
+  pullPolicy: IfNotPresent
+
+imagePullSecrets: []
+nameOverride: ""
+fullnameOverride: ""
+
+# ---------------------------------------------------------------------------
+# Gate service configuration — everything is env-driven; the container reads
+# these EP_GATE_* variables at boot (see README.md for the full contract).
+# ---------------------------------------------------------------------------
+gate:
+  # Port the gate HTTP service listens on (EP_GATE_PORT).
+  port: 8080
+  # Log verbosity (EP_GATE_LOG_LEVEL): error | warn | info | debug
+  logLevel: info
+  # Strict evidence log (EP_GATE_EVIDENCE_STRICT): when "true" the gate fails
+  # CLOSED if a decision record cannot be durably written. Keep true.
+  evidenceStrict: true
+  # Extra environment variables appended verbatim to the container (list of
+  # EnvVar objects — supports valueFrom for your own Secret/ConfigMap refs).
+  extraEnv: []
+
+# ---------------------------------------------------------------------------
+# Issuer keys — REQUIRED, referenced, never rendered.
+# Create the Secret yourself, e.g.:
+#   kubectl create secret generic emilia-gate-issuer-keys \
+#     --from-file=issuer-keys.json=./issuer-keys.json
+# where issuer-keys.json is a JSON array of pinned base64url SPKI-DER Ed25519
+# public keys (or {kid: key} map). The chart exposes it to the container as
+# EP_GATE_ISSUER_KEYS via a secretKeyRef. Rendering fails if existingSecret
+# is empty — a gate with no pinned issuers must not deploy (fail closed).
+# ---------------------------------------------------------------------------
+issuerKeys:
+  existingSecret: ""
+  secretKey: "issuer-keys.json"
+
+# ---------------------------------------------------------------------------
+# Action-risk manifest (EP-ACTION-RISK-MANIFEST-v0.1) — which actions are
+# guarded and what assurance each one requires. Rendered into a ConfigMap and
+# mounted read-only; the container reads it from EP_GATE_MANIFEST_PATH.
+# Set existingConfigMap to bring your own instead of the inline default.
+# ---------------------------------------------------------------------------
+manifest:
+  # File name of the manifest key inside the ConfigMap / mount.
+  fileName: action-risk-manifest.json
+  # Name of a pre-existing ConfigMap carrying the manifest under `fileName`.
+  # When set, the chart's own ConfigMap is not rendered.
+  existingConfigMap: ""
+  # Inline manifest — rendered to JSON verbatim. The default below is a
+  # SUBSET of the gate's built-in high-risk action packs (see
+  # packages/gate/action-packs.js for the full set); replace it with your
+  # organization's real manifest.
+  inline:
+    "@version": EP-ACTION-RISK-MANIFEST-v0.1
+    actions:
+      - id: money_movement.release
+        label: Money movement
+        action_type: payment.release
+        risk: critical
+        receipt_required: true
+        assurance_class: class_a
+        match: { protocol: mcp, tool: release_payment }
+        execution_binding:
+          required_fields:
+            - action_type
+            - amount_usd
+            - currency
+            - payment_instruction_id
+            - beneficiary_account_hash
+      - id: production.deploy
+        label: Production deploy
+        action_type: deploy.production
+        risk: critical
+        receipt_required: true
+        assurance_class: quorum
+        match: { protocol: mcp, tool: deploy_production }
+        execution_binding:
+          required_fields:
+            - action_type
+            - repo
+            - commit_sha
+            - environment
+            - artifact_digest
+
+service:
+  type: ClusterIP
+  port: 8080
+
+# ---------------------------------------------------------------------------
+# Metrics — matches the gate's /metrics endpoint. When enabled, the chart
+# sets EP_GATE_METRICS_ENABLED=true and renders a ServiceMonitor stub
+# (requires the Prometheus Operator CRDs to be installed in the cluster).
+# ---------------------------------------------------------------------------
+metrics:
+  enabled: false
+  path: /metrics
+  serviceMonitor:
+    interval: 30s
+    scrapeTimeout: 10s
+    # Extra labels for the ServiceMonitor (e.g. `release: prometheus` so your
+    # Prometheus instance selects it).
+    additionalLabels: {}
+
+probes:
+  liveness:
+    path: /healthz
+    initialDelaySeconds: 5
+    periodSeconds: 10
+    timeoutSeconds: 2
+    failureThreshold: 3
+  readiness:
+    path: /readyz
+    initialDelaySeconds: 5
+    periodSeconds: 10
+    timeoutSeconds: 2
+    failureThreshold: 3
+
+resources:
+  requests:
+    cpu: 100m
+    memory: 128Mi
+  limits:
+    cpu: 500m
+    memory: 256Mi
+
+# Hardened pod defaults — loosen deliberately, not accidentally.
+podSecurityContext:
+  runAsNonRoot: true
+  runAsUser: 10001
+  runAsGroup: 10001
+  fsGroup: 10001
+  seccompProfile:
+    type: RuntimeDefault
+
+containerSecurityContext:
+  allowPrivilegeEscalation: false
+  readOnlyRootFilesystem: true
+  capabilities:
+    drop:
+      - ALL
+
+podAnnotations: {}
+podLabels: {}
+nodeSelector: {}
+tolerations: []
+affinity: {}

package/deploy/terraform/README.md

@@ -0,0 +1,138 @@
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+
+# EMILIA Gate — reference 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
+contract, same fail-closed invariants, expressed as three Kubernetes resources
+in a cluster **you** control:
+
+| Resource | Purpose |
+| --- | --- |
+| `kubernetes_config_map_v1.manifest` | The action-risk manifest (the deny-by-default policy), mounted read-only at `/etc/emilia-gate/action-risk-manifest.json` |
+| `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 |
+
+**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
+deployer's keys, the deployer's responsibility for network policy, ingress,
+TLS, and durable storage. There is no official public gate image while this is
+experimental: build and push your own.
+
+## Key custody — read this first
+
+Issuer public keys (the keys the gate pins and trusts to have signed receipts)
+are consumed from an **existing Kubernetes Secret that you create**. The module
+takes the Secret's *name* only:
+
+- it never accepts key material inline,
+- it never creates or reads a Secret, so no key bytes enter Terraform state,
+- the `secretKeyRef` is `optional = false` — **no pinned issuers, no pods**. A
+  gate without pinned issuer keys must never come up permissive, so it fails
+  closed by not coming up at all.
+
+Create the Secret out-of-band (or via your own secrets tooling — ESO, sealed
+secrets, Vault injector):
+
+```sh
+kubectl -n emilia create secret generic emilia-gate-issuer-keys \
+  --from-file=issuer-keys.json=./issuer-keys.json
+```
+
+where `issuer-keys.json` is a JSON array of pinned base64url SPKI-DER Ed25519
+public keys (or a `{kid: key}` map). It reaches the container as
+`EP_GATE_ISSUER_KEYS`.
+
+## Usage
+
+```hcl
+provider "kubernetes" {
+  config_path = "~/.kube/config" # your cluster, your credentials
+}
+
+module "emilia_gate" {
+  source = "github.com/FutureEnterprises/emilia-protocol//packages/gate/deploy/terraform"
+
+  namespace = "emilia"                                  # must already exist
+  image     = "ghcr.io/your-org/emilia-gate@sha256:..." # pin a digest
+
+  replicas                = 2
+  issuer_keys_secret_name = "emilia-gate-issuer-keys" # NAME only, never keys
+
+  # The deny-by-default policy the gate enforces (EP-ACTION-RISK-MANIFEST).
+  manifest_json = file("${path.module}/manifest.json")
+}
+
+output "gate_endpoint" {
+  value = module.emilia_gate.service_endpoint
+  # e.g. http://emilia-gate.emilia.svc.cluster.local:8080
+}
+```
+
+The manifest is validated at `terraform plan` time (must be JSON with an
+`actions` field), and its sha256 is annotated onto the pod template so every
+policy change rolls the pods.
+
+## Container contract (identical to the Helm chart)
+
+| Env var | Source | Default |
+| --- | --- | --- |
+| `NODE_ENV` | fixed | `production` |
+| `EP_GATE_PORT` | `port` | `8080` |
+| `EP_GATE_LOG_LEVEL` | `log_level` | `info` |
+| `EP_GATE_EVIDENCE_STRICT` | `evidence_strict` | `true` |
+| `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) |
+
+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.
+
+## Inputs
+
+| Name | Default | Notes |
+| --- | --- | --- |
+| `image` | — (required) | Pin a digest or exact tag |
+| `manifest_json` | — (required) | JSON string; plan-time validated |
+| `issuer_keys_secret_name` | — (required) | Existing Secret, same namespace |
+| `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 |
+| `port` / `service_port` | `8080` / `8080` | |
+| `service_type` | `ClusterIP` | Anything more exposed is your explicit call |
+| `log_level` | `info` | `error` \| `warn` \| `info` \| `debug` |
+| `evidence_strict` | `true` | Keep true — fail-closed evidence log |
+| `metrics_enabled` | `false` | Scrape wiring is chart-only for now |
+| `liveness_path` / `readiness_path` | `/healthz` / `/readyz` | `null` disables |
+| `resources` | 100m/128Mi → 500m/256Mi | |
+| `run_as_user` | `10001` | Non-root enforced |
+| `read_only_root_filesystem` | `true` | `/tmp` is a writable emptyDir either way |
+| `extra_env`, `extra_labels` | `{}` | Plain-text only |
+
+Outputs: `service_name`, `namespace`, `service_endpoint`, `deployment_name`,
+`manifest_config_map_name`, `module_version`.
+
+## 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.
+- **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
+  deployer.
+
+## What has been validated
+
+`terraform fmt -check`, `terraform init -backend=false`, and
+`terraform validate` pass against 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
+applied against a live cluster as part of this repo's CI — treat it as
+reviewed reference code, not a certified install path.