@emilia-protocol/gate 0.9.0 → 0.9.1

package/deploy/terraform/main.tf

@@ -0,0 +1,256 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# EMILIA Gate — reference Terraform module (EP-GATE-TF-v1).
+#
+# The Terraform sibling of the Helm chart (deploy/helm, EP-GATE-HELM-v1) for
+# BYOC installs: the deployer's cluster, the deployer's keys. Same container
+# contract as the chart — EP_GATE_* env, the action-risk manifest mounted at
+# /etc/emilia-gate/action-risk-manifest.json, pinned issuer keys arriving as
+# EP_GATE_ISSUER_KEYS from a Secret the DEPLOYER created. Three resources,
+# nothing hidden:
+#
+#   kubernetes_config_map_v1.manifest — the action-risk manifest (policy);
+#   kubernetes_deployment_v1.gate     — the gate pods, hardened defaults
+#     (non-root, read-only rootfs, no privilege escalation, all capabilities
+#     dropped, no service-account token);
+#   kubernetes_service_v1.gate        — cluster-internal Service in front of
+#     the pods (ClusterIP by default).
+#
+# Fail-closed wiring:
+#   - the issuer-keys secretKeyRef is NOT optional: if the deployer has not
+#     provisioned pinned issuer keys, the pods do not start — a gate without
+#     pinned issuers must never come up permissive;
+#   - EP_GATE_EVIDENCE_STRICT defaults to true: the gate refuses to authorize
+#     an action it cannot durably account for;
+#   - the manifest is validated as JSON at plan time (see variables.tf) and a
+#     sha256 of it is annotated onto the pod template, so every manifest change
+#     rolls the pods — a stale policy can't keep serving silently.
+
+locals {
+  module_version = "EP-GATE-TF-v1"
+
+  labels = merge({
+    "app.kubernetes.io/name"            = var.name
+    "app.kubernetes.io/component"       = "trusted-action-firewall"
+    "app.kubernetes.io/part-of"         = "emilia-protocol"
+    "emiliaprotocol.ai/module-contract" = local.module_version
+    "emiliaprotocol.ai/maturity"        = "experimental"
+  }, var.extra_labels)
+
+  selector_labels = {
+    "app.kubernetes.io/name"      = var.name
+    "app.kubernetes.io/component" = "trusted-action-firewall"
+  }
+
+  # Same paths as the Helm chart's container contract.
+  manifest_mount_dir = "/etc/emilia-gate"
+  manifest_file      = "action-risk-manifest.json"
+}
+
+# The policy the gate enforces. Plain ConfigMap: the manifest is deny-by-default
+# POLICY, not a secret — auditors should be able to read it in-cluster.
+resource "kubernetes_config_map_v1" "manifest" {
+  metadata {
+    name      = "${var.name}-manifest"
+    namespace = var.namespace
+    labels    = local.labels
+  }
+
+  data = {
+    (local.manifest_file) = var.manifest_json
+  }
+}
+
+resource "kubernetes_deployment_v1" "gate" {
+  metadata {
+    name      = var.name
+    namespace = var.namespace
+    labels    = local.labels
+  }
+
+  spec {
+    replicas = var.replicas
+
+    selector {
+      match_labels = local.selector_labels
+    }
+
+    template {
+      metadata {
+        labels = local.labels
+        annotations = {
+          # Roll the pods whenever the policy changes.
+          "emiliaprotocol.ai/manifest-sha256" = sha256(var.manifest_json)
+        }
+      }
+
+      spec {
+        # The gate does not call the Kubernetes API; no token, no ambient authority.
+        automount_service_account_token = false
+
+        security_context {
+          run_as_non_root = true
+          run_as_user     = var.run_as_user
+          run_as_group    = var.run_as_user
+          fs_group        = var.run_as_user
+
+          seccomp_profile {
+            type = "RuntimeDefault"
+          }
+        }
+
+        container {
+          name              = "gate"
+          image             = var.image
+          image_pull_policy = var.image_pull_policy
+
+          port {
+            name           = "http"
+            container_port = var.port
+            protocol       = "TCP"
+          }
+
+          env {
+            name  = "NODE_ENV"
+            value = "production"
+          }
+
+          env {
+            name  = "EP_GATE_PORT"
+            value = tostring(var.port)
+          }
+
+          env {
+            name  = "EP_GATE_LOG_LEVEL"
+            value = var.log_level
+          }
+
+          # Strict evidence log: never authorize an action the gate cannot
+          # durably account for.
+          env {
+            name  = "EP_GATE_EVIDENCE_STRICT"
+            value = tostring(var.evidence_strict)
+          }
+
+          env {
+            name  = "EP_GATE_MANIFEST_PATH"
+            value = "${local.manifest_mount_dir}/${local.manifest_file}"
+          }
+
+          env {
+            name  = "EP_GATE_METRICS_ENABLED"
+            value = tostring(var.metrics_enabled)
+          }
+
+          # Pinned issuer keys — REFERENCED from an existing Secret, never
+          # passed through Terraform. optional=false is the fail-closed
+          # switch: no pinned issuers, no pods.
+          env {
+            name = "EP_GATE_ISSUER_KEYS"
+            value_from {
+              secret_key_ref {
+                name     = var.issuer_keys_secret_name
+                key      = var.issuer_keys_secret_key
+                optional = false
+              }
+            }
+          }
+
+          dynamic "env" {
+            for_each = var.extra_env
+            content {
+              name  = env.key
+              value = env.value
+            }
+          }
+
+          volume_mount {
+            name       = "action-risk-manifest"
+            mount_path = local.manifest_mount_dir
+            read_only  = true
+          }
+
+          # Writable scratch for the runtime; rootfs stays read-only.
+          volume_mount {
+            name       = "tmp"
+            mount_path = "/tmp"
+          }
+
+          resources {
+            requests = var.resources.requests
+            limits   = var.resources.limits
+          }
+
+          dynamic "liveness_probe" {
+            for_each = var.liveness_path == null ? [] : [var.liveness_path]
+            content {
+              http_get {
+                path = liveness_probe.value
+                port = "http"
+              }
+              initial_delay_seconds = 5
+              period_seconds        = 10
+              timeout_seconds       = 2
+              failure_threshold     = 3
+            }
+          }
+
+          dynamic "readiness_probe" {
+            for_each = var.readiness_path == null ? [] : [var.readiness_path]
+            content {
+              http_get {
+                path = readiness_probe.value
+                port = "http"
+              }
+              initial_delay_seconds = 5
+              period_seconds        = 10
+              timeout_seconds       = 2
+              failure_threshold     = 3
+            }
+          }
+
+          security_context {
+            allow_privilege_escalation = false
+            read_only_root_filesystem  = var.read_only_root_filesystem
+
+            capabilities {
+              drop = ["ALL"]
+            }
+          }
+        }
+
+        volume {
+          name = "action-risk-manifest"
+          config_map {
+            name = kubernetes_config_map_v1.manifest.metadata[0].name
+          }
+        }
+
+        volume {
+          name = "tmp"
+          empty_dir {}
+        }
+      }
+    }
+  }
+}
+
+resource "kubernetes_service_v1" "gate" {
+  metadata {
+    name      = var.name
+    namespace = var.namespace
+    labels    = local.labels
+  }
+
+  spec {
+    type     = var.service_type
+    selector = local.selector_labels
+
+    port {
+      name        = "http"
+      port        = var.service_port
+      target_port = "http"
+      protocol    = "TCP"
+    }
+  }
+}

package/deploy/terraform/outputs.tf

@@ -0,0 +1,33 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# EMILIA Gate — reference Terraform module (EP-GATE-TF-v1) — outputs.
+
+output "module_version" {
+  description = "Versioned identifier of this reference module."
+  value       = "EP-GATE-TF-v1"
+}
+
+output "service_name" {
+  description = "Name of the Kubernetes Service fronting the gate."
+  value       = kubernetes_service_v1.gate.metadata[0].name
+}
+
+output "namespace" {
+  description = "Namespace the gate is deployed into."
+  value       = kubernetes_service_v1.gate.metadata[0].namespace
+}
+
+output "service_endpoint" {
+  description = "In-cluster HTTP endpoint of the gate (cluster-DNS form). Point guarded callers at this."
+  value       = "http://${kubernetes_service_v1.gate.metadata[0].name}.${kubernetes_service_v1.gate.metadata[0].namespace}.svc.cluster.local:${var.service_port}"
+}
+
+output "deployment_name" {
+  description = "Name of the gate Deployment."
+  value       = kubernetes_deployment_v1.gate.metadata[0].name
+}
+
+output "manifest_config_map_name" {
+  description = "Name of the ConfigMap carrying the action-risk manifest."
+  value       = kubernetes_config_map_v1.manifest.metadata[0].name
+}

package/deploy/terraform/variables.tf

@@ -0,0 +1,205 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# EMILIA Gate — reference Terraform module (EP-GATE-TF-v1) — inputs.
+#
+# KEY CUSTODY RULE (non-negotiable): issuer public keys are consumed from an
+# EXISTING Kubernetes Secret that the deployer creates and controls. This
+# module takes the secret's NAME only. It never accepts key material inline,
+# never creates a Secret, and never reads secret data — so no key bytes ever
+# enter Terraform state, plan output, or version control via this module.
+
+variable "name" {
+  description = "Base name for all resources (Deployment, Service, ConfigMap prefix)."
+  type        = string
+  default     = "emilia-gate"
+
+  validation {
+    condition     = can(regex("^[a-z0-9]([-a-z0-9]*[a-z0-9])?$", var.name)) && length(var.name) <= 53
+    error_message = "name must be a DNS-1123 label (lowercase alphanumerics and '-', max 53 chars to leave room for suffixes)."
+  }
+}
+
+variable "namespace" {
+  description = "Kubernetes namespace to deploy into. Must already exist — this module does not create namespaces."
+  type        = string
+  default     = "default"
+
+  validation {
+    condition     = can(regex("^[a-z0-9]([-a-z0-9]*[a-z0-9])?$", var.namespace))
+    error_message = "namespace must be a DNS-1123 label."
+  }
+}
+
+variable "image" {
+  description = "Container image for the gate (registry/repo:tag or @digest). BYOC: build and push your own image; pin a digest or exact tag for production — never a floating tag."
+  type        = string
+
+  validation {
+    condition     = length(trimspace(var.image)) > 0
+    error_message = "image is required."
+  }
+}
+
+variable "image_pull_policy" {
+  description = "Kubernetes imagePullPolicy for the gate container."
+  type        = string
+  default     = "IfNotPresent"
+
+  validation {
+    condition     = contains(["Always", "IfNotPresent", "Never"], var.image_pull_policy)
+    error_message = "image_pull_policy must be one of Always, IfNotPresent, Never."
+  }
+}
+
+variable "replicas" {
+  description = "Number of gate replicas. Replay defense across >1 replica requires a shared consumption store (see README) — the module deploys the pods either way, but fleet-safety is the deployer's configuration responsibility."
+  type        = number
+  default     = 2
+
+  validation {
+    condition     = var.replicas >= 1 && floor(var.replicas) == var.replicas
+    error_message = "replicas must be a whole number >= 1."
+  }
+}
+
+variable "manifest_json" {
+  description = "The action-risk manifest (EP-ACTION-RISK-MANIFEST) as a JSON string — the deny-by-default policy the gate enforces. Rendered into a ConfigMap and mounted read-only. Must parse as JSON and contain an \"actions\" array; an unparseable manifest fails at plan time, not in the cluster."
+  type        = string
+
+  validation {
+    condition     = can(jsondecode(var.manifest_json)) && can(jsondecode(var.manifest_json).actions)
+    error_message = "manifest_json must be valid JSON with an \"actions\" field (EP-ACTION-RISK-MANIFEST shape)."
+  }
+}
+
+variable "issuer_keys_secret_name" {
+  description = "Name of an EXISTING Kubernetes Secret (in the same namespace) holding the pinned issuer public keys the gate trusts. Referenced by name only — key material must NEVER be passed to Terraform. Exposed to the container as EP_GATE_ISSUER_KEYS via a non-optional secretKeyRef: pods do not start without it (fail closed — a gate with no pinned issuers must never come up permissive)."
+  type        = string
+
+  validation {
+    # DNS-1123 subdomain. This also structurally rejects pasted key material
+    # (PEM headers, JSON, base64url with '_') landing in this variable.
+    condition     = can(regex("^[a-z0-9]([-a-z0-9.]*[a-z0-9])?$", var.issuer_keys_secret_name)) && length(var.issuer_keys_secret_name) <= 253
+    error_message = "issuer_keys_secret_name must be the NAME of an existing Secret (DNS-1123 subdomain). Never inline key material here."
+  }
+}
+
+variable "issuer_keys_secret_key" {
+  description = "Key inside the issuer-keys Secret that holds the pinned keys (a JSON array of base64url SPKI-DER Ed25519 public keys, or a {kid: key} map). Matches the Helm chart's issuerKeys.secretKey."
+  type        = string
+  default     = "issuer-keys.json"
+
+  validation {
+    condition     = length(trimspace(var.issuer_keys_secret_key)) > 0
+    error_message = "issuer_keys_secret_key must be non-empty."
+  }
+}
+
+variable "port" {
+  description = "Port the gate HTTP service listens on inside the container (EP_GATE_PORT). Matches the Helm chart's gate.port."
+  type        = number
+  default     = 8080
+
+  validation {
+    condition     = var.port >= 1 && var.port <= 65535
+    error_message = "port must be 1-65535."
+  }
+}
+
+variable "service_port" {
+  description = "Port the Service exposes inside the cluster."
+  type        = number
+  default     = 8080
+
+  validation {
+    condition     = var.service_port >= 1 && var.service_port <= 65535
+    error_message = "service_port must be 1-65535."
+  }
+}
+
+variable "service_type" {
+  description = "Kubernetes Service type. ClusterIP (default) keeps the gate cluster-internal; anything more exposed is the deployer's explicit choice."
+  type        = string
+  default     = "ClusterIP"
+
+  validation {
+    condition     = contains(["ClusterIP", "NodePort", "LoadBalancer"], var.service_type)
+    error_message = "service_type must be one of ClusterIP, NodePort, LoadBalancer."
+  }
+}
+
+variable "log_level" {
+  description = "Gate log verbosity (EP_GATE_LOG_LEVEL)."
+  type        = string
+  default     = "info"
+
+  validation {
+    condition     = contains(["error", "warn", "info", "debug"], var.log_level)
+    error_message = "log_level must be one of error, warn, info, debug."
+  }
+}
+
+variable "evidence_strict" {
+  description = "Strict evidence log (EP_GATE_EVIDENCE_STRICT): when true the gate fails CLOSED if a decision record cannot be durably written — it never authorizes an action it cannot account for. Keep true."
+  type        = bool
+  default     = true
+}
+
+variable "metrics_enabled" {
+  description = "Sets EP_GATE_METRICS_ENABLED. Scrape wiring (ServiceMonitor etc.) is out of scope for this module — see the Helm chart."
+  type        = bool
+  default     = false
+}
+
+variable "liveness_path" {
+  description = "HTTP path for the liveness probe. Set to null to disable."
+  type        = string
+  default     = "/healthz"
+}
+
+variable "readiness_path" {
+  description = "HTTP path for the readiness probe. Set to null to disable."
+  type        = string
+  default     = "/readyz"
+}
+
+variable "resources" {
+  description = "Container resource requests/limits (Kubernetes quantity strings)."
+  type = object({
+    requests = map(string)
+    limits   = map(string)
+  })
+  default = {
+    requests = { cpu = "100m", memory = "128Mi" }
+    limits   = { cpu = "500m", memory = "256Mi" }
+  }
+}
+
+variable "run_as_user" {
+  description = "UID/GID the gate container runs as (must be non-root; the pod security context enforces runAsNonRoot). Matches the Helm chart's default of 10001."
+  type        = number
+  default     = 10001
+
+  validation {
+    condition     = var.run_as_user > 0
+    error_message = "run_as_user must be non-zero: the gate never runs as root."
+  }
+}
+
+variable "read_only_root_filesystem" {
+  description = "Mount the container's root filesystem read-only (hardened default). A writable emptyDir is mounted at /tmp for runtime scratch either way."
+  type        = bool
+  default     = true
+}
+
+variable "extra_env" {
+  description = "Additional plain-text environment variables for the gate container (e.g. a durable consumption-store URL host/port). Do NOT put secrets here — values in this map land in Terraform state. Reference deployer-managed Secrets instead."
+  type        = map(string)
+  default     = {}
+}
+
+variable "extra_labels" {
+  description = "Additional labels merged onto every resource."
+  type        = map(string)
+  default     = {}
+}

package/deploy/terraform/versions.tf

@@ -0,0 +1,18 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# EMILIA Gate — reference Terraform module (EP-GATE-TF-v1).
+# Provider and core version constraints. The kubernetes provider is the ONLY
+# provider this module uses: everything lands in the deployer's own cluster,
+# authenticated with the deployer's own credentials. No EMILIA-hosted backend,
+# no remote state requirement, no callbacks.
+
+terraform {
+  required_version = ">= 1.5.0"
+
+  required_providers {
+    kubernetes = {
+      source  = "hashicorp/kubernetes"
+      version = ">= 2.23.0, < 3.0.0"
+    }
+  }
+}

package/enterprise.js

@@ -0,0 +1,174 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * EMILIA Gate — enterprise entitlement layer (EP-GATE-ENTITLEMENT-v1).
+ *
+ * The license key IS an EP-style artifact: a signed entitlement — Ed25519 over
+ * canonical JSON (sorted keys, same idiom as receipts/evidence) of
+ * { org, tier, features[], limits, not_before, expires_at, kid }. Verifiers pin
+ * issuer keys by kid; nothing in the artifact is trusted until the signature
+ * verifies against a pinned key.
+ *
+ * OPEN-CORE SEMANTICS — two different fail directions, by design:
+ *   - The CORE gate is never bricked. No entitlement, an expired one, a
+ *     tampered one, an unknown kid — all resolve to { valid:false,
+ *     tier:'community' } with a machine-readable reason. Community tier always
+ *     works; a licensing failure can never block the firewall itself.
+ *   - Enterprise FEATURES fail closed. `requireFeature` returns true ONLY for
+ *     a cryptographically valid, in-window entitlement that explicitly lists
+ *     the feature. Everything else — including community fallback — is false.
+ *
+ * Pure functions: inputs in, verdict out. Time is injected (`now`), never read
+ * from the wall clock implicitly, so verification is deterministic.
+ */
+import crypto from 'node:crypto';
+
+export const ENTITLEMENT_VERSION = 'EP-GATE-ENTITLEMENT-v1';
+export const ENTITLEMENT_TIERS = ['community', 'team', 'business', 'enterprise', 'regulated'];
+
+/** The tier every failure path resolves to — the gate keeps working on it. */
+const COMMUNITY = 'community';
+
+/** Canonical JSON (recursive sorted keys) — matches @emilia-protocol/verify. */
+function canonical(v) {
+  if (v === null || v === undefined) return JSON.stringify(v);
+  if (Array.isArray(v)) return `[${v.map(canonical).join(',')}]`;
+  if (typeof v === 'object') {
+    return `{${Object.keys(v).sort().map((k) => JSON.stringify(k) + ':' + canonical(v[k])).join(',')}}`;
+  }
+  return JSON.stringify(v);
+}
+
+function toMs(t) {
+  if (t == null) return null;
+  const ms = typeof t === 'number' ? t : Date.parse(t);
+  return Number.isFinite(ms) ? ms : null;
+}
+
+/** Community fallback — every refusal shape is identical and machine-readable. */
+function community(reason, extra = {}) {
+  return { valid: false, tier: COMMUNITY, features: [], limits: null, reason, ...extra };
+}
+
+/**
+ * Mint a signed entitlement (test/ops helper — the licensing service, not the
+ * verifier, holds the private key). Throws on invalid fields: a malformed
+ * license must never be issued, only refused.
+ * @param {crypto.KeyObject} privateKey Ed25519 private key
+ * @param {object} fields { org, tier, features?, limits?, not_before, expires_at, kid }
+ * @returns {{ '@version': string, payload: object, signature: { algorithm: 'Ed25519', value: string } }}
+ */
+export function mintEntitlement(privateKey, {
+  org, tier, features = [], limits = {}, not_before, expires_at, kid,
+} = {}) {
+  if (!org || typeof org !== 'string') throw new Error('entitlement: org is required');
+  if (!ENTITLEMENT_TIERS.includes(tier)) {
+    throw new Error(`entitlement: unknown tier "${tier}" (expected one of ${ENTITLEMENT_TIERS.join('|')})`);
+  }
+  if (!Array.isArray(features) || features.some((f) => typeof f !== 'string')) {
+    throw new Error('entitlement: features must be an array of strings');
+  }
+  if (!limits || typeof limits !== 'object' || Array.isArray(limits)) {
+    throw new Error('entitlement: limits must be an object');
+  }
+  if (toMs(not_before) == null) throw new Error('entitlement: not_before is required (ISO or ms)');
+  if (toMs(expires_at) == null) throw new Error('entitlement: expires_at is required (ISO or ms)');
+  if (!kid || typeof kid !== 'string') throw new Error('entitlement: kid is required');
+  const payload = { org, tier, features, limits, not_before, expires_at, kid };
+  const value = crypto.sign(null, Buffer.from(canonical(payload), 'utf8'), privateKey).toString('base64url');
+  return { '@version': ENTITLEMENT_VERSION, payload, signature: { algorithm: 'Ed25519', value } };
+}
+
+/** Resolve a base64url SPKI-DER key for `kid` from a map or an entry list. */
+function issuerKeyFor(issuerKeys, kid) {
+  if (!issuerKeys) return null;
+  if (Array.isArray(issuerKeys)) {
+    const e = issuerKeys.find((x) => x && x.kid === kid && typeof x.key === 'string');
+    return e ? e.key : null;
+  }
+  const k = issuerKeys[kid];
+  return typeof k === 'string' ? k : null;
+}
+
+/**
+ * Verify an entitlement. NEVER throws for a bad artifact — every failure
+ * resolves to the community tier with a machine-readable reason, so a licensing
+ * problem degrades gracefully instead of bricking the gate. Enterprise features
+ * remain gated by `requireFeature`, which fails closed on any non-valid result.
+ *
+ * @param {object|string|null} entitlementJson the artifact (object or JSON string); absence -> community
+ * @param {object} o
+ * @param {object|Array<{kid:string,key:string}>} o.issuerKeys pinned kid -> base64url SPKI-DER public key
+ * @param {number|string|function} [o.now=Date.now] injected clock (ms, ISO, or () => ms)
+ * @returns {{ valid: boolean, tier: string, features: string[], limits: object|null, reason: string, org?: string, kid?: string }}
+ */
+export function verifyEntitlement(entitlementJson, { issuerKeys, now = Date.now } = {}) {
+  // Absence is NOT an error: the open-core floor. Community keeps working.
+  if (entitlementJson == null || entitlementJson === '') return community('no_entitlement');
+
+  let doc = entitlementJson;
+  if (typeof doc === 'string') {
+    try { doc = JSON.parse(doc); } catch { return community('entitlement_unparseable'); }
+  }
+  if (!doc || typeof doc !== 'object') return community('entitlement_malformed');
+  if (doc['@version'] !== ENTITLEMENT_VERSION) return community('unsupported_version');
+
+  const p = doc.payload;
+  const sig = doc.signature;
+  if (!p || typeof p !== 'object' || !sig || typeof sig !== 'object') return community('entitlement_malformed');
+  if (sig.algorithm !== 'Ed25519' || typeof sig.value !== 'string') return community('unsupported_algorithm');
+  if (!ENTITLEMENT_TIERS.includes(p.tier)) return community('unknown_tier');
+  if (!Array.isArray(p.features) || p.features.some((f) => typeof f !== 'string')) return community('entitlement_malformed');
+
+  // Issuer pinning: the kid must resolve to a PINNED key. An entitlement can
+  // never nominate its own key — unknown kid (or no pins at all) fails closed.
+  const keyB64 = issuerKeyFor(issuerKeys, p.kid);
+  if (!keyB64) return community('unknown_kid', { kid: p.kid ?? null });
+
+  let ok = false;
+  try {
+    const pub = crypto.createPublicKey({ key: Buffer.from(keyB64, 'base64url'), format: 'der', type: 'spki' });
+    ok = crypto.verify(null, Buffer.from(canonical(p), 'utf8'), pub, Buffer.from(sig.value, 'base64url'));
+  } catch { ok = false; }
+  // One reason covers both tampering and a wrong key: the signature does not
+  // verify against the pinned key for this kid.
+  if (!ok) return community('bad_signature', { kid: p.kid });
+
+  // Validity window — checked only AFTER the signature, so the timestamps
+  // themselves are authenticated. Both bounds are required; an unparseable
+  // window fails closed.
+  const nowMs = typeof now === 'function' ? now() : toMs(now);
+  const nbf = toMs(p.not_before);
+  const exp = toMs(p.expires_at);
+  if (nbf == null || exp == null || nowMs == null) return community('invalid_validity_window', { kid: p.kid });
+  if (nowMs < nbf) return community('not_yet_valid', { kid: p.kid, not_before: p.not_before });
+  if (nowMs > exp) return community('expired', { kid: p.kid, expires_at: p.expires_at });
+
+  return {
+    valid: true,
+    tier: p.tier,
+    features: p.features.slice(),
+    limits: (p.limits && typeof p.limits === 'object') ? { ...p.limits } : {},
+    reason: 'entitlement_verified',
+    org: p.org,
+    kid: p.kid,
+    not_before: p.not_before,
+    expires_at: p.expires_at,
+  };
+}
+
+/**
+ * Is `feature` licensed? FAIL CLOSED: true only for a valid entitlement that
+ * explicitly lists the feature. Community fallback, invalid/expired/tampered
+ * artifacts, and unlisted features are all false — no enterprise code path
+ * runs without a live license naming it.
+ * @param {object} verified the result of verifyEntitlement
+ * @param {string} feature
+ * @returns {boolean}
+ */
+export function requireFeature(verified, feature) {
+  if (!verified || verified.valid !== true) return false;
+  if (typeof feature !== 'string' || feature.length === 0) return false;
+  return Array.isArray(verified.features) && verified.features.includes(feature);
+}
+
+export default { mintEntitlement, verifyEntitlement, requireFeature, ENTITLEMENT_VERSION, ENTITLEMENT_TIERS };