@hasna/uptime 0.1.12 → 0.1.13

package/CHANGELOG.md

@@ -6,6 +6,15 @@ project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.1.13] - 2026-06-28
+
+### Added
+
+- Added opt-in Terraform support for private AWS VPC endpoints. Infra owners can
+  enable interface endpoints for ECR API, ECR Docker, CloudWatch Logs, and
+  Secrets Manager, plus an S3 gateway endpoint when private route tables are
+  provided.
+
 ## [0.1.12] - 2026-06-28
 
 ### Added

package/dist/cli/index.js

@@ -6932,7 +6932,7 @@ function buildAwsDeploymentPlan(options = {}) {
   const image = clean(options.image, `${imageRepositoryUri}@sha256:<image-digest>`);
   const evidenceBucket = clean(options.evidenceBucket, `hasna-${stage}-${prefix}-evidence`);
   const hostedSqliteDbPath = clean(options.hostedSqliteDbPath, DEFAULT_HOSTED_SQLITE_DB);
-  const runtimePackageVersion = clean(options.runtimePackageVersion, "0.1.12");
+  const runtimePackageVersion = clean(options.runtimePackageVersion, "0.1.13");
   const protectedAccessMode = options.protectedAccessMode ?? DEFAULT_PROTECTED_ACCESS_MODE;
   const protectedAccessUrl = protectedAccessMode === "cloudfront_default_domain" ? "https://<cloudfront-domain>" : `https://${hostname}`;
   const cluster = `${prefix}-${stage}`;

package/dist/cloud-plan.js

@@ -21,7 +21,7 @@ function buildAwsDeploymentPlan(options = {}) {
   const image = clean(options.image, `${imageRepositoryUri}@sha256:<image-digest>`);
   const evidenceBucket = clean(options.evidenceBucket, `hasna-${stage}-${prefix}-evidence`);
   const hostedSqliteDbPath = clean(options.hostedSqliteDbPath, DEFAULT_HOSTED_SQLITE_DB);
-  const runtimePackageVersion = clean(options.runtimePackageVersion, "0.1.12");
+  const runtimePackageVersion = clean(options.runtimePackageVersion, "0.1.13");
   const protectedAccessMode = options.protectedAccessMode ?? DEFAULT_PROTECTED_ACCESS_MODE;
   const protectedAccessUrl = protectedAccessMode === "cloudfront_default_domain" ? "https://<cloudfront-domain>" : `https://${hostname}`;
   const cluster = `${prefix}-${stage}`;

package/dist/index.js

@@ -4338,7 +4338,7 @@ function buildAwsDeploymentPlan(options = {}) {
   const image = clean(options.image, `${imageRepositoryUri}@sha256:<image-digest>`);
   const evidenceBucket = clean(options.evidenceBucket, `hasna-${stage}-${prefix}-evidence`);
   const hostedSqliteDbPath = clean(options.hostedSqliteDbPath, DEFAULT_HOSTED_SQLITE_DB);
-  const runtimePackageVersion = clean(options.runtimePackageVersion, "0.1.12");
+  const runtimePackageVersion = clean(options.runtimePackageVersion, "0.1.13");
   const protectedAccessMode = options.protectedAccessMode ?? DEFAULT_PROTECTED_ACCESS_MODE;
   const protectedAccessUrl = protectedAccessMode === "cloudfront_default_domain" ? "https://<cloudfront-domain>" : `https://${hostname}`;
   const cluster = `${prefix}-${stage}`;

package/docs/aws-deployment-runbook.md

@@ -80,8 +80,10 @@ The plan expects:
 - Encrypted EFS file system, access point, mount targets, and AWS Backup plan
   for `HASNA_UPTIME_HOSTED_SQLITE_DB=/data/uptime/uptime.db`.
 - S3 bucket for redacted browser evidence and generated report artifacts.
-- Secrets Manager or SSM refs for app env, hosted token, probe config, and
-  reporting channel refs.
+- Secrets Manager refs for app env, hosted token, probe config, and reporting
+  channel refs. If any ECS secret uses an SSM Parameter Store ARN, add `ssm` to
+  `interface_vpc_endpoint_services` or document the approved alternate egress
+  path before running private-only tasks.
 - CloudWatch log groups for every component plus initial web 5xx/unhealthy
   alarms. Scheduler-stall, stale-probe, and report-delivery alarms remain
   blocked until those workers emit cloud metrics.
@@ -176,8 +178,12 @@ Before setting `desired_counts.web = 1`, verify:
 - `HASNA_UPTIME_ALLOWED_ORIGINS` matches the public HTTPS edge origin;
 - CloudFront origin access is distribution-bound, not just narrowed to
   CloudFront origin-facing ranges;
-- web egress to ECR, Secrets Manager, CloudWatch Logs, S3, EFS, and any required
-  endpoints has been proven through NAT or VPC endpoints;
+- web egress to ECR, Secrets Manager or SSM, CloudWatch Logs, S3, EFS, and any
+  required endpoints has been proven from a real ECS task. Terraform endpoint
+  ids, route tables, and security-group rules are creation evidence only; the
+  scale-up evidence must include image pull, secret injection, log delivery, S3
+  access, and EFS mount checks through the selected NAT or private-endpoint
+  path;
 - scheduler, public-probe, reporter, and migration remain at `0`.
 
 Scale only the web task, then capture the ECS deployment id and task definition

package/infra/aws/README.md

@@ -52,6 +52,25 @@ type, and cost-center tags. Set `monthly_budget_limit_usd` plus
 forecasted and actual spend alerts. Leaving the email list empty skips budget
 creation and is not sufficient for live scale-out approval.
 
+Private AWS API egress can be pinned through opt-in VPC endpoints by setting
+`enable_private_vpc_endpoints = true` and passing `private_route_table_ids`.
+This creates interface endpoints for ECR API, ECR Docker, CloudWatch Logs, and
+Secrets Manager, plus an S3 gateway endpoint when route tables are supplied. The
+default is `false` so package consumers do not create endpoint hourly cost
+without explicit infra-owner approval. The S3 gateway endpoint is required for
+private ECR image layer pulls; the module adds S3 managed-prefix-list egress for
+web and non-public worker security groups when the gateway endpoint is enabled.
+Endpoint policies are scoped to the Open Uptime repository, log groups,
+configured secret refs, KMS key, evidence bucket, and the regional ECR layer
+bucket.
+
+Interface endpoint private DNS is VPC-wide. In shared VPCs, either keep endpoint
+creation in the approved networking root, or pass
+`additional_vpc_endpoint_source_security_group_ids` for every workload that must
+keep using those private DNS names. If any ECS secret ref uses SSM Parameter
+Store instead of Secrets Manager, add `ssm` to
+`interface_vpc_endpoint_services` or keep an approved non-endpoint egress path.
+
 ## Current Blockers
 
 - Hosted production auth/RBAC still needs scoped, revocable credentials.

package/infra/aws/main.tf

@@ -14,6 +14,7 @@ provider "aws" {
 }
 
 data "aws_caller_identity" "current" {}
+data "aws_partition" "current" {}
 
 locals {
   prefix                = "${var.service_name}-${var.stage}"
@@ -63,6 +64,21 @@ locals {
     AppType     = var.app_type
     CostCenter  = var.cost_center
   }
+  s3_gateway_endpoint_enabled = var.enable_private_vpc_endpoints && contains(var.gateway_vpc_endpoint_services, "s3") && length(var.private_route_table_ids) > 0
+  endpoint_secret_refs        = distinct(flatten([for service in values(local.services) : values(service.secrets)]))
+  secretsmanager_secret_refs  = [for ref in local.endpoint_secret_refs : ref if can(regex(":secretsmanager:", ref))]
+  ssm_parameter_refs          = [for ref in local.endpoint_secret_refs : ref if can(regex(":ssm:", ref))]
+  secretsmanager_policy_refs = (
+    length(local.secretsmanager_secret_refs) > 0
+    ? local.secretsmanager_secret_refs
+    : ["arn:${data.aws_partition.current.partition}:secretsmanager:${var.region}:${data.aws_caller_identity.current.account_id}:secret:${local.prefix}/no-secretsmanager-refs-configured-*"]
+  )
+  ssm_policy_refs = (
+    length(local.ssm_parameter_refs) > 0
+    ? local.ssm_parameter_refs
+    : ["arn:${data.aws_partition.current.partition}:ssm:${var.region}:${data.aws_caller_identity.current.account_id}:parameter/${local.prefix}/no-ssm-refs-configured"]
+  )
+  service_log_group_arns = [for group in aws_cloudwatch_log_group.service : "${group.arn}:*"]
 }
 
 data "aws_vpc" "target" {
@@ -383,6 +399,278 @@ resource "aws_security_group_rule" "worker_egress" {
   cidr_blocks       = each.key == "public-probe" ? ["0.0.0.0/0"] : [data.aws_vpc.target.cidr_block]
 }
 
+resource "aws_security_group_rule" "web_s3_gateway_egress" {
+  count = local.s3_gateway_endpoint_enabled ? 1 : 0
+
+  type              = "egress"
+  description       = "HTTPS to S3 gateway endpoint prefix list"
+  security_group_id = aws_security_group.web.id
+  from_port         = 443
+  to_port           = 443
+  protocol          = "tcp"
+  prefix_list_ids   = [aws_vpc_endpoint.gateway["s3"].prefix_list_id]
+}
+
+resource "aws_security_group_rule" "worker_s3_gateway_egress" {
+  for_each = local.s3_gateway_endpoint_enabled ? {
+    for key, value in aws_security_group.worker : key => value if key != "public-probe"
+  } : {}
+
+  type              = "egress"
+  description       = "HTTPS to S3 gateway endpoint prefix list"
+  security_group_id = each.value.id
+  from_port         = 443
+  to_port           = 443
+  protocol          = "tcp"
+  prefix_list_ids   = [aws_vpc_endpoint.gateway["s3"].prefix_list_id]
+}
+
+resource "aws_security_group" "vpc_endpoints" {
+  count       = var.enable_private_vpc_endpoints ? 1 : 0
+  name        = "${local.prefix}-vpc-endpoints-sg"
+  description = "Open Uptime interface VPC endpoints"
+  vpc_id      = data.aws_vpc.target.id
+  tags        = merge(local.tags, { Component = "vpc-endpoints" })
+}
+
+resource "aws_security_group_rule" "vpc_endpoints_from_web" {
+  count                    = var.enable_private_vpc_endpoints ? 1 : 0
+  type                     = "ingress"
+  description              = "HTTPS from Open Uptime web tasks"
+  security_group_id        = aws_security_group.vpc_endpoints[0].id
+  from_port                = 443
+  to_port                  = 443
+  protocol                 = "tcp"
+  source_security_group_id = aws_security_group.web.id
+}
+
+resource "aws_security_group_rule" "vpc_endpoints_from_worker" {
+  for_each = var.enable_private_vpc_endpoints ? aws_security_group.worker : {}
+
+  type                     = "ingress"
+  description              = "HTTPS from Open Uptime ${each.key} tasks"
+  security_group_id        = aws_security_group.vpc_endpoints[0].id
+  from_port                = 443
+  to_port                  = 443
+  protocol                 = "tcp"
+  source_security_group_id = each.value.id
+}
+
+resource "aws_security_group_rule" "vpc_endpoints_from_additional_sources" {
+  for_each = var.enable_private_vpc_endpoints ? toset(var.additional_vpc_endpoint_source_security_group_ids) : toset([])
+
+  type                     = "ingress"
+  description              = "HTTPS from additional approved source security group"
+  security_group_id        = aws_security_group.vpc_endpoints[0].id
+  from_port                = 443
+  to_port                  = 443
+  protocol                 = "tcp"
+  source_security_group_id = each.value
+}
+
+data "aws_iam_policy_document" "vpc_endpoint_ecr_api" {
+  statement {
+    sid       = "AllowEcrAuthorization"
+    actions   = ["ecr:GetAuthorizationToken"]
+    resources = ["*"]
+
+    principals {
+      type        = "*"
+      identifiers = ["*"]
+    }
+  }
+
+  statement {
+    sid = "AllowOpenUptimeRepositoryRead"
+    actions = [
+      "ecr:BatchCheckLayerAvailability",
+      "ecr:BatchGetImage",
+      "ecr:DescribeImages",
+      "ecr:DescribeRepositories",
+      "ecr:GetDownloadUrlForLayer",
+    ]
+    resources = [aws_ecr_repository.open_uptime.arn]
+
+    principals {
+      type        = "*"
+      identifiers = ["*"]
+    }
+  }
+}
+
+data "aws_iam_policy_document" "vpc_endpoint_ecr_dkr" {
+  statement {
+    sid = "AllowOpenUptimeRegistryRead"
+    actions = [
+      "ecr:BatchCheckLayerAvailability",
+      "ecr:BatchGetImage",
+      "ecr:GetDownloadUrlForLayer",
+    ]
+    resources = [aws_ecr_repository.open_uptime.arn]
+
+    principals {
+      type        = "*"
+      identifiers = ["*"]
+    }
+  }
+}
+
+data "aws_iam_policy_document" "vpc_endpoint_logs" {
+  statement {
+    sid = "AllowOpenUptimeLogDelivery"
+    actions = [
+      "logs:CreateLogStream",
+      "logs:DescribeLogStreams",
+      "logs:PutLogEvents",
+    ]
+    resources = local.service_log_group_arns
+
+    principals {
+      type        = "*"
+      identifiers = ["*"]
+    }
+  }
+}
+
+data "aws_iam_policy_document" "vpc_endpoint_secretsmanager" {
+  statement {
+    sid = "AllowOpenUptimeSecretReads"
+    actions = [
+      "secretsmanager:DescribeSecret",
+      "secretsmanager:GetSecretValue",
+    ]
+    resources = local.secretsmanager_policy_refs
+
+    principals {
+      type        = "*"
+      identifiers = ["*"]
+    }
+  }
+}
+
+data "aws_iam_policy_document" "vpc_endpoint_ssm" {
+  statement {
+    sid = "AllowOpenUptimeParameterReads"
+    actions = [
+      "ssm:GetParameter",
+      "ssm:GetParameters",
+    ]
+    resources = local.ssm_policy_refs
+
+    principals {
+      type        = "*"
+      identifiers = ["*"]
+    }
+  }
+}
+
+data "aws_iam_policy_document" "vpc_endpoint_sts" {
+  statement {
+    sid       = "AllowCallerIdentity"
+    actions   = ["sts:GetCallerIdentity"]
+    resources = ["*"]
+
+    principals {
+      type        = "*"
+      identifiers = ["*"]
+    }
+  }
+}
+
+data "aws_iam_policy_document" "vpc_endpoint_kms" {
+  statement {
+    sid = "AllowOpenUptimeKeyUse"
+    actions = [
+      "kms:Decrypt",
+      "kms:DescribeKey",
+      "kms:GenerateDataKey*",
+    ]
+    resources = [var.kms_key_arn]
+
+    principals {
+      type        = "*"
+      identifiers = ["*"]
+    }
+  }
+}
+
+data "aws_iam_policy_document" "vpc_endpoint_s3" {
+  statement {
+    sid = "AllowOpenUptimeEvidenceBucket"
+    actions = [
+      "s3:AbortMultipartUpload",
+      "s3:GetBucketLocation",
+      "s3:GetObject",
+      "s3:ListBucket",
+      "s3:PutObject",
+    ]
+    resources = [
+      aws_s3_bucket.evidence.arn,
+      "${aws_s3_bucket.evidence.arn}/*",
+    ]
+
+    principals {
+      type        = "*"
+      identifiers = ["*"]
+    }
+  }
+
+  statement {
+    sid       = "AllowEcrLayerBucket"
+    actions   = ["s3:GetObject"]
+    resources = ["arn:${data.aws_partition.current.partition}:s3:::prod-${var.region}-starport-layer-bucket/*"]
+
+    principals {
+      type        = "*"
+      identifiers = ["*"]
+    }
+  }
+}
+
+resource "aws_vpc_endpoint" "interface" {
+  for_each = var.enable_private_vpc_endpoints ? toset(var.interface_vpc_endpoint_services) : toset([])
+
+  vpc_id              = data.aws_vpc.target.id
+  service_name        = "com.amazonaws.${var.region}.${each.key}"
+  vpc_endpoint_type   = "Interface"
+  subnet_ids          = var.private_subnet_ids
+  security_group_ids  = [aws_security_group.vpc_endpoints[0].id]
+  private_dns_enabled = true
+  policy = {
+    "ecr.api"      = data.aws_iam_policy_document.vpc_endpoint_ecr_api.json
+    "ecr.dkr"      = data.aws_iam_policy_document.vpc_endpoint_ecr_dkr.json
+    logs           = data.aws_iam_policy_document.vpc_endpoint_logs.json
+    secretsmanager = data.aws_iam_policy_document.vpc_endpoint_secretsmanager.json
+    ssm            = data.aws_iam_policy_document.vpc_endpoint_ssm.json
+    sts            = data.aws_iam_policy_document.vpc_endpoint_sts.json
+    kms            = data.aws_iam_policy_document.vpc_endpoint_kms.json
+  }[each.key]
+
+  tags = merge(local.tags, {
+    Name      = "${local.prefix}-${replace(each.key, ".", "-")}-endpoint"
+    Component = "vpc-endpoint"
+    Endpoint  = each.key
+  })
+}
+
+resource "aws_vpc_endpoint" "gateway" {
+  for_each = var.enable_private_vpc_endpoints && length(var.private_route_table_ids) > 0 ? toset(var.gateway_vpc_endpoint_services) : toset([])
+
+  vpc_id            = data.aws_vpc.target.id
+  service_name      = "com.amazonaws.${var.region}.${each.key}"
+  vpc_endpoint_type = "Gateway"
+  route_table_ids   = var.private_route_table_ids
+  policy = {
+    s3 = data.aws_iam_policy_document.vpc_endpoint_s3.json
+  }[each.key]
+
+  tags = merge(local.tags, {
+    Name      = "${local.prefix}-${each.key}-endpoint"
+    Component = "vpc-endpoint"
+    Endpoint  = each.key
+  })
+}
+
 resource "aws_security_group" "efs" {
   name        = "${local.prefix}-efs-sg"
   description = "Open Uptime EFS data store"

package/infra/aws/outputs.tf

@@ -75,3 +75,10 @@ output "service_names" {
     [for service in aws_ecs_service.worker : service.name],
   )
 }
+
+output "vpc_endpoint_ids" {
+  value = {
+    interface = { for service, endpoint in aws_vpc_endpoint.interface : service => endpoint.id }
+    gateway   = { for service, endpoint in aws_vpc_endpoint.gateway : service => endpoint.id }
+  }
+}

package/infra/aws/terraform.tfvars.example

@@ -14,8 +14,9 @@ protected_access_mode    = "cloudfront_default_domain"
 public_subnet_ids        = ["subnet-replace-public-a", "subnet-replace-public-b"]
 alb_ingress_cidr_blocks = []
 private_subnet_ids       = ["subnet-replace-private-a", "subnet-replace-private-b"]
+private_route_table_ids  = ["rtb-replace-private"]
 container_image          = "123456789012.dkr.ecr.us-east-1.amazonaws.com/open-uptime@sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
-runtime_package_version  = "0.1.12"
+runtime_package_version  = "0.1.13"
 certificate_arn          = null
 hosted_zone_id           = null
 app_env_secret_arn       = "arn:aws:secretsmanager:us-east-1:123456789012:secret:open-uptime/prod/app/env"
@@ -25,6 +26,8 @@ reporting_secret_arn     = "arn:aws:secretsmanager:us-east-1:123456789012:secret
 kms_key_arn              = "arn:aws:kms:us-east-1:123456789012:key/00000000-0000-0000-0000-000000000000"
 alarm_actions            = []
 monthly_budget_limit_usd = 0
+enable_private_vpc_endpoints = false
+additional_vpc_endpoint_source_security_group_ids = []
 
 desired_counts = {
   web            = 0

package/infra/aws/variables.tf

@@ -116,7 +116,7 @@ variable "container_image" {
 variable "runtime_package_version" {
   description = "Published @hasna/uptime package version that CodeBuild should build into the ECR image."
   type        = string
-  default     = "0.1.12"
+  default     = "0.1.13"
 
   validation {
     condition     = can(regex("^[0-9]+\\.[0-9]+\\.[0-9]+(-[0-9A-Za-z.-]+)?$", var.runtime_package_version))
@@ -237,3 +237,45 @@ variable "budget_alert_email_addresses" {
   type        = list(string)
   default     = []
 }
+
+variable "enable_private_vpc_endpoints" {
+  description = "Create private VPC endpoints for ECS access to AWS APIs. Requires private subnet ids; S3 gateway endpoint also requires private_route_table_ids."
+  type        = bool
+  default     = false
+}
+
+variable "interface_vpc_endpoint_services" {
+  description = "Regional interface endpoint service short names to create when enable_private_vpc_endpoints is true."
+  type        = list(string)
+  default     = ["ecr.api", "ecr.dkr", "logs", "secretsmanager"]
+
+  validation {
+    condition = alltrue([
+      for service in var.interface_vpc_endpoint_services : contains(["ecr.api", "ecr.dkr", "logs", "secretsmanager", "sts", "ssm", "kms"], service)
+    ])
+    error_message = "interface_vpc_endpoint_services must contain only approved AWS service short names."
+  }
+}
+
+variable "additional_vpc_endpoint_source_security_group_ids" {
+  description = "Additional source security groups allowed to use Open Uptime interface VPC endpoints in a shared VPC. Keep empty for dedicated Open Uptime subnets."
+  type        = list(string)
+  default     = []
+}
+
+variable "gateway_vpc_endpoint_services" {
+  description = "Regional gateway endpoint service short names to create when enable_private_vpc_endpoints is true."
+  type        = list(string)
+  default     = ["s3"]
+
+  validation {
+    condition     = alltrue([for service in var.gateway_vpc_endpoint_services : contains(["s3"], service)])
+    error_message = "gateway_vpc_endpoint_services currently supports only s3."
+  }
+}
+
+variable "private_route_table_ids" {
+  description = "Private route table ids for gateway VPC endpoints such as S3. Leave empty to skip gateway endpoint creation."
+  type        = list(string)
+  default     = []
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/uptime",
-  "version": "0.1.12",
+  "version": "0.1.13",
   "description": "Local-first uptime and downtime monitoring service with CLI, MCP, SDK, SQLite persistence, and a dashboard.",
   "license": "Apache-2.0",
   "type": "module",