@biffo/cli 0.38.0 → 0.41.0

package/_skeletons/sibling-template/infra/outputs.tf

@@ -0,0 +1,17 @@
+output "api_url" {
+  description = "This sibling's own API Gateway endpoint — set as NEXT_PUBLIC_API_URL in the frontend build."
+  value       = module.api_gateway.api_endpoint
+}
+
+output "site_bucket_name" {
+  value = module.storage.site_bucket_name
+}
+
+output "site_bucket_regional_domain" {
+  description = "Consumed by the core project's registration PR — written into its siblings.auto.tfvars.json as this sibling's bucket_regional_domain (see modules/cloud/aws/cdn's sibling_origins in the core repo)."
+  value       = module.storage.site_bucket_regional_domain
+}
+
+output "lambda_function_name" {
+  value = module.api.function_name
+}

package/_skeletons/sibling-template/infra/variables.tf

@@ -0,0 +1,63 @@
+variable "project_name" {
+  description = "This sibling's name — also the path segment it's routed on (baseurl.com/<project_name>/*, ADR-0007). Must match the \"name\" this sibling was registered with in the core project's siblings.auto.tfvars.json."
+  type        = string
+
+  validation {
+    condition     = can(regex("^[a-z][a-z0-9-]*$", var.project_name))
+    error_message = "project_name must be lowercase alphanumeric with hyphens, starting with a letter (it becomes a URL path segment and an AWS resource name prefix)."
+  }
+}
+
+variable "environment" {
+  type    = string
+  default = "dev"
+}
+
+variable "aws_region" {
+  type    = string
+  default = "us-east-1"
+}
+
+# ── Core project identity (ADR-0007) ───────────────────────────────────────
+# This sibling never provisions its own Cognito pool or CloudFront
+# distribution — it plugs into the core project's. These are plain
+# pass-through input variables, not resources.
+
+variable "core_cognito_user_pool_id" {
+  type = string
+}
+
+variable "core_cognito_client_id" {
+  type = string
+}
+
+variable "core_api_url" {
+  description = "Base URL of the core project's own API — the only place this sibling may read/write core-owned data (ADR-0002)."
+  type        = string
+}
+
+variable "core_portal_url" {
+  description = "Origin of the core portal (e.g. https://baseurl.com) — the frontend redirects here to sign in when there is no shared session."
+  type        = string
+}
+
+variable "cors_origins" {
+  description = "Origins allowed to call this sibling's API. Since the frontend is served path-routed on the SAME origin as the core portal, this is normally just [core_portal_url], plus http://localhost:3000 for local dev."
+  type        = list(string)
+  default     = ["http://localhost:3000"]
+}
+
+# ── Two-phase CDN registration (see modules/cloud/aws/cdn's sibling_origins
+# in the core project, and README.md's "Registering with the core project"
+# section) ─────────────────────────────────────────────────────────────────
+
+variable "parent_cloudfront_distribution_arn" {
+  description = "ARN of the core project's CloudFront distribution. Left empty until the core project's registration PR (opened by `biffo sibling create`) has merged and redeployed — the bucket policy below is skipped while empty, since there is no distribution ARN yet to trust. Re-apply with this set once that PR merges."
+  type        = string
+  default     = ""
+}
+
+variable "tags" {
+  type    = map(string)
+  default = {}
+}

package/_skeletons/sibling-template/modules/cloud/aws/api-gateway/main.tf

@@ -0,0 +1,114 @@
+terraform {
+  required_providers {
+    aws = { source = "hashicorp/aws", version = "~> 5.0" }
+  }
+}
+
+locals {
+  name_prefix = "${var.project_name}-${var.environment}"
+}
+
+resource "aws_apigatewayv2_api" "main" {
+  name          = "${local.name_prefix}-api"
+  protocol_type = "HTTP"
+  description   = "Sibling API - ${local.name_prefix}"
+  tags          = var.tags
+
+  # Applied by API Gateway itself, independent of the Lambda integration — this is
+  # what puts CORS headers on responses the JWT authorizer rejects before invoking
+  # Lambda (see the $default route below). FastAPI's CORSMiddleware only covers
+  # requests that actually reach the Lambda.
+  cors_configuration {
+    allow_origins     = var.cors_origins
+    allow_methods     = ["*"]
+    allow_headers     = ["*"]
+    allow_credentials = true
+  }
+}
+
+# JWT authorizer backed by the CORE project's Cognito pool (ADR-0007) —
+# validates Bearer tokens on all protected routes. This is one of two layers
+# of defense in depth: API Gateway rejects invalid/missing tokens before
+# Lambda is ever invoked, and the Lambda's own auth middleware
+# (services/api/src/api/middleware/auth.py) independently re-verifies the
+# same token again.
+resource "aws_apigatewayv2_authorizer" "cognito" {
+  api_id           = aws_apigatewayv2_api.main.id
+  authorizer_type  = "JWT"
+  identity_sources = ["$request.header.Authorization"]
+  name             = "${local.name_prefix}-cognito"
+
+  jwt_configuration {
+    audience = [var.cognito_client_id]
+    issuer   = "https://cognito-idp.${var.aws_region}.amazonaws.com/${var.cognito_user_pool_id}"
+  }
+}
+
+resource "aws_apigatewayv2_integration" "lambda" {
+  api_id                 = aws_apigatewayv2_api.main.id
+  integration_type       = "AWS_PROXY"
+  integration_uri        = var.lambda_function_arn
+  payload_format_version = "2.0"
+  timeout_milliseconds   = 29000
+}
+
+# Health check — no auth required (public endpoint)
+resource "aws_apigatewayv2_route" "health" {
+  api_id             = aws_apigatewayv2_api.main.id
+  route_key          = "GET /api/v1/health"
+  target             = "integrations/${aws_apigatewayv2_integration.lambda.id}"
+  authorization_type = "NONE"
+}
+
+# OPTIONS preflight — no auth so CORS preflight is never blocked by the JWT authorizer.
+resource "aws_apigatewayv2_route" "options" {
+  api_id    = aws_apigatewayv2_api.main.id
+  route_key = "OPTIONS /{proxy+}"
+  target    = "integrations/${aws_apigatewayv2_integration.lambda.id}"
+}
+
+# Catch-all — all other routes require a valid Cognito JWT
+resource "aws_apigatewayv2_route" "default" {
+  api_id             = aws_apigatewayv2_api.main.id
+  route_key          = "$default"
+  target             = "integrations/${aws_apigatewayv2_integration.lambda.id}"
+  authorization_type = "JWT"
+  authorizer_id      = aws_apigatewayv2_authorizer.cognito.id
+}
+
+resource "aws_apigatewayv2_stage" "main" {
+  api_id      = aws_apigatewayv2_api.main.id
+  name        = "$default"
+  auto_deploy = true
+
+  access_log_settings {
+    destination_arn = aws_cloudwatch_log_group.access_logs.arn
+    format = jsonencode({
+      requestId        = "$context.requestId"
+      ip               = "$context.identity.sourceIp"
+      requestTime      = "$context.requestTime"
+      httpMethod       = "$context.httpMethod"
+      routeKey         = "$context.routeKey"
+      status           = "$context.status"
+      protocol         = "$context.protocol"
+      responseLength   = "$context.responseLength"
+      integrationError = "$context.integrationErrorMessage"
+    })
+  }
+
+  tags = var.tags
+}
+
+resource "aws_cloudwatch_log_group" "access_logs" {
+  name              = "/sibling/${local.name_prefix}/api-gateway"
+  retention_in_days = var.environment == "prod" ? 90 : 14
+  tags              = var.tags
+}
+
+resource "aws_lambda_permission" "api_gateway" {
+  statement_id  = "AllowAPIGatewayInvoke"
+  action        = "lambda:InvokeFunction"
+  function_name = var.lambda_function_name
+  principal     = "apigateway.amazonaws.com"
+  source_arn    = "${aws_apigatewayv2_api.main.execution_arn}/*/*"
+}

package/_skeletons/sibling-template/modules/cloud/aws/api-gateway/outputs.tf

@@ -0,0 +1,12 @@
+output "api_id" {
+  value = aws_apigatewayv2_api.main.id
+}
+
+output "api_endpoint" {
+  description = "Base URL of the HTTP API — set as NEXT_PUBLIC_API_URL in the frontend build"
+  value       = trimsuffix(aws_apigatewayv2_stage.main.invoke_url, "/")
+}
+
+output "execution_arn" {
+  value = aws_apigatewayv2_api.main.execution_arn
+}

package/_skeletons/sibling-template/modules/cloud/aws/api-gateway/variables.tf

@@ -0,0 +1,41 @@
+variable "project_name" {
+  type = string
+}
+
+variable "environment" {
+  type = string
+}
+
+variable "lambda_function_arn" {
+  description = "ARN of the sibling API Lambda function to integrate"
+  type        = string
+}
+
+variable "lambda_function_name" {
+  description = "Name of the sibling API Lambda function (for the invoke permission)"
+  type        = string
+}
+
+variable "cognito_user_pool_id" {
+  description = "The CORE project's Cognito User Pool ID (ADR-0007) — this sibling has no pool of its own."
+  type        = string
+}
+
+variable "cognito_client_id" {
+  description = "The CORE project's Cognito App Client ID (ADR-0007) — same client as the core portal, so sessions are shared."
+  type        = string
+}
+
+variable "aws_region" {
+  type = string
+}
+
+variable "cors_origins" {
+  description = "Origins allowed to call this API. Must be applied at the API Gateway level (not just FastAPI's CORSMiddleware) because the JWT authorizer rejects unauthenticated requests before they ever reach the Lambda, so no CORS headers would otherwise be present on 401s."
+  type        = list(string)
+}
+
+variable "tags" {
+  type    = map(string)
+  default = {}
+}

package/_skeletons/sibling-template/modules/cloud/aws/compute/main.tf

@@ -0,0 +1,157 @@
+terraform {
+  required_providers {
+    aws     = { source = "hashicorp/aws", version = "~> 5.0" }
+    archive = { source = "hashicorp/archive", version = "~> 2.0" }
+  }
+}
+
+# Minimal placeholder zip — Terraform creates this automatically during plan.
+# The CI/CD pipeline overwrites the function code on every deploy;
+# this only exists so the Lambda resource can be created on first apply.
+data "archive_file" "placeholder" {
+  type        = "zip"
+  output_path = "${path.module}/placeholder.zip"
+  source {
+    content  = "def handler(event, context):\n    pass\n"
+    filename = "handler.py"
+  }
+}
+
+locals {
+  name_prefix   = "${var.project_name}-${var.environment}"
+  function_name = "${local.name_prefix}-${var.function_name}"
+}
+
+# Dead letter queue for failed invocations — encrypted at rest with KMS
+resource "aws_sqs_queue" "dlq" {
+  name                      = "${local.function_name}-dlq"
+  message_retention_seconds = 1209600 # 14 days
+  kms_master_key_id         = var.sqs_kms_key_id
+  tags                      = var.tags
+}
+
+# Security group — only created when this function is attached to a VPC
+# (var.enable_vpc_access). A sibling with no DB of its own (ADR-0002/
+# ADR-0007) should generally leave this false.
+resource "aws_security_group" "lambda" {
+  count       = var.enable_vpc_access ? 1 : 0
+  name        = "${local.function_name}-sg"
+  description = "Lambda function security group for ${local.function_name}"
+  vpc_id      = var.vpc_id
+
+  egress {
+    from_port   = 0
+    to_port     = 0
+    protocol    = "-1"
+    cidr_blocks = ["0.0.0.0/0"]
+  }
+
+  tags = merge(var.tags, { Name = "${local.function_name}-sg" })
+}
+
+resource "aws_cloudwatch_log_group" "function" {
+  name              = "/aws/lambda/${local.function_name}"
+  retention_in_days = 365 # 1 year — satisfies CKV_AWS_338
+  kms_key_id        = var.cloudwatch_kms_key_id
+  tags              = var.tags
+}
+
+# Least-privilege execution role — no AdministratorAccess, no PowerUser
+data "aws_iam_policy_document" "lambda_trust" {
+  statement {
+    effect  = "Allow"
+    actions = ["sts:AssumeRole"]
+    principals {
+      type        = "Service"
+      identifiers = ["lambda.amazonaws.com"]
+    }
+  }
+}
+
+resource "aws_iam_role" "lambda" {
+  name               = "${local.function_name}-role"
+  assume_role_policy = data.aws_iam_policy_document.lambda_trust.json
+  tags               = var.tags
+}
+
+resource "aws_iam_role_policy_attachment" "vpc_access" {
+  count      = var.enable_vpc_access ? 1 : 0
+  role       = aws_iam_role.lambda.name
+  policy_arn = "arn:aws:iam::aws:policy/service-role/AWSLambdaVPCAccessExecutionRole"
+}
+
+data "aws_iam_policy_document" "lambda_permissions" {
+  statement {
+    sid    = "CloudWatchLogs"
+    effect = "Allow"
+    actions = [
+      "logs:CreateLogStream",
+      "logs:PutLogEvents"
+    ]
+    resources = ["${aws_cloudwatch_log_group.function.arn}:*"]
+  }
+
+  statement {
+    sid       = "DLQAccess"
+    effect    = "Allow"
+    actions   = ["sqs:SendMessage"]
+    resources = [aws_sqs_queue.dlq.arn]
+  }
+}
+
+resource "aws_iam_role_policy" "lambda" {
+  name   = "sibling-lambda-policy"
+  role   = aws_iam_role.lambda.id
+  policy = data.aws_iam_policy_document.lambda_permissions.json
+}
+
+resource "aws_lambda_function" "main" {
+  function_name = local.function_name
+  role          = aws_iam_role.lambda.arn
+  handler       = var.handler
+  runtime       = var.runtime
+  memory_size   = var.memory_size
+  timeout       = var.timeout
+
+  filename         = data.archive_file.placeholder.output_path
+  source_code_hash = data.archive_file.placeholder.output_base64sha256
+
+  dead_letter_config {
+    target_arn = aws_sqs_queue.dlq.arn
+  }
+
+  dynamic "vpc_config" {
+    for_each = var.enable_vpc_access ? [1] : []
+    content {
+      subnet_ids         = var.private_subnet_ids
+      security_group_ids = [aws_security_group.lambda[0].id]
+    }
+  }
+
+  environment {
+    variables = merge(
+      var.environment_variables,
+      {
+        POWERTOOLS_SERVICE_NAME = local.function_name
+        POWERTOOLS_LOG_LEVEL    = var.environment == "prod" ? "WARNING" : "INFO"
+      }
+    )
+  }
+
+  tracing_config {
+    mode = "Active"
+  }
+
+  depends_on = [
+    aws_cloudwatch_log_group.function,
+    aws_iam_role_policy_attachment.vpc_access,
+    aws_iam_role_policy.lambda,
+  ]
+
+  lifecycle {
+    # Code is managed by the CI/CD pipeline — Terraform only manages config
+    ignore_changes = [filename, source_code_hash]
+  }
+
+  tags = var.tags
+}

package/_skeletons/sibling-template/modules/cloud/aws/compute/outputs.tf

@@ -0,0 +1,4 @@
+output "function_arn" { value = aws_lambda_function.main.arn }
+output "function_name" { value = aws_lambda_function.main.function_name }
+output "role_arn" { value = aws_iam_role.lambda.arn }
+output "dlq_arn" { value = aws_sqs_queue.dlq.arn }

package/_skeletons/sibling-template/modules/cloud/aws/compute/variables.tf

@@ -0,0 +1,70 @@
+variable "project_name" {
+  type = string
+}
+
+variable "environment" {
+  type = string
+}
+
+variable "function_name" {
+  type = string
+}
+
+variable "handler" {
+  type = string
+}
+
+variable "runtime" {
+  type    = string
+  default = "python3.13"
+}
+
+variable "enable_vpc_access" {
+  description = "Attach this Lambda's ENIs to a VPC. Defaults to false — a sibling with no database of its own (ADR-0002/ADR-0007) gets nothing from VPC attachment, and in NAT-less networking configs it would cut off outbound internet access including calls to the core project's API."
+  type        = bool
+  default     = false
+}
+
+variable "vpc_id" {
+  description = "VPC to attach this Lambda's ENIs to. Only used when enable_vpc_access is true."
+  type        = string
+  default     = ""
+}
+
+variable "private_subnet_ids" {
+  description = "Private subnets to place ENIs in. Only used when enable_vpc_access is true."
+  type        = list(string)
+  default     = []
+}
+
+variable "memory_size" {
+  type    = number
+  default = 512
+}
+
+variable "timeout" {
+  type    = number
+  default = 30
+}
+
+variable "environment_variables" {
+  type    = map(string)
+  default = {}
+}
+
+variable "tags" {
+  type    = map(string)
+  default = {}
+}
+
+variable "sqs_kms_key_id" {
+  description = "KMS key ID for SQS queue encryption (CKV_AWS_27). Leave empty for AWS-owned key."
+  type        = string
+  default     = ""
+}
+
+variable "cloudwatch_kms_key_id" {
+  description = "KMS key ID for CloudWatch log group encryption (CKV_AWS_158). Leave empty for AWS-owned key."
+  type        = string
+  default     = ""
+}

package/_skeletons/sibling-template/modules/cloud/aws/storage/main.tf

@@ -0,0 +1,78 @@
+terraform {
+  required_providers {
+    aws = { source = "hashicorp/aws", version = "~> 5.0" }
+  }
+}
+
+data "aws_caller_identity" "current" {}
+
+locals {
+  name_prefix = "${var.project_name}-${var.environment}"
+  site_bucket = "${local.name_prefix}-site-${data.aws_caller_identity.current.account_id}"
+  logs_bucket = "${local.name_prefix}-logs-${data.aws_caller_identity.current.account_id}"
+}
+
+# Access logs bucket
+resource "aws_s3_bucket" "logs" {
+  bucket        = local.logs_bucket
+  force_destroy = true
+  tags          = var.tags
+}
+
+resource "aws_s3_bucket_public_access_block" "logs" {
+  bucket                  = aws_s3_bucket.logs.id
+  block_public_acls       = true
+  block_public_policy     = true
+  ignore_public_acls      = true
+  restrict_public_buckets = true
+}
+
+resource "aws_s3_bucket_server_side_encryption_configuration" "logs" {
+  bucket = aws_s3_bucket.logs.id
+  rule {
+    apply_server_side_encryption_by_default {
+      sse_algorithm = "AES256"
+    }
+  }
+}
+
+# This sibling's static frontend export — served via the PARENT project's
+# CloudFront distribution as a new origin/ordered_cache_behavior (ADR-0007;
+# see modules/cloud/aws/cdn/main.tf in the parent repo). The bucket policy
+# trusting that distribution's ARN is deliberately NOT in this module — it
+# lives in infra/main.tf, parameterized by var.parent_cloudfront_distribution_arn,
+# because this module has no way to know that ARN (it belongs to a
+# distribution this repo doesn't own or create).
+resource "aws_s3_bucket" "site" {
+  bucket        = local.site_bucket
+  force_destroy = true
+  tags          = var.tags
+}
+
+resource "aws_s3_bucket_public_access_block" "site" {
+  bucket                  = aws_s3_bucket.site.id
+  block_public_acls       = true
+  block_public_policy     = true
+  ignore_public_acls      = true
+  restrict_public_buckets = true
+}
+
+resource "aws_s3_bucket_versioning" "site" {
+  bucket = aws_s3_bucket.site.id
+  versioning_configuration { status = "Enabled" }
+}
+
+resource "aws_s3_bucket_server_side_encryption_configuration" "site" {
+  bucket = aws_s3_bucket.site.id
+  rule {
+    apply_server_side_encryption_by_default {
+      sse_algorithm = "AES256"
+    }
+  }
+}
+
+resource "aws_s3_bucket_logging" "site" {
+  bucket        = aws_s3_bucket.site.id
+  target_bucket = aws_s3_bucket.logs.id
+  target_prefix = "site-access-logs/"
+}

package/_skeletons/sibling-template/modules/cloud/aws/storage/outputs.tf

@@ -0,0 +1,4 @@
+output "site_bucket_name" { value = aws_s3_bucket.site.bucket }
+output "site_bucket_arn" { value = aws_s3_bucket.site.arn }
+output "site_bucket_regional_domain" { value = aws_s3_bucket.site.bucket_regional_domain_name }
+output "logs_bucket_name" { value = aws_s3_bucket.logs.bucket }

package/_skeletons/sibling-template/modules/cloud/aws/storage/variables.tf

@@ -0,0 +1,12 @@
+variable "project_name" {
+  type = string
+}
+
+variable "environment" {
+  type = string
+}
+
+variable "tags" {
+  type    = map(string)
+  default = {}
+}

package/_skeletons/sibling-template/services/api/pyproject.toml

@@ -0,0 +1,69 @@
+[project]
+name = "sibling-api"
+version = "0.0.0"
+description = "Sibling app backend — verifies the shared core Cognito JWT and calls the core API for all data (ADR-0002/ADR-0007). No database client of any kind belongs in this service."
+requires-python = ">=3.13"
+dependencies = [
+  "fastapi>=0.115.6",
+  "mangum>=0.19.0",
+  "pydantic>=2.10.4",
+  "pydantic-settings>=2.7.1",
+  "aws-lambda-powertools[tracer]>=3.4.0",
+  "pyjwt[crypto]>=2.10.0",
+  "httpx>=0.28.1",
+]
+
+[dependency-groups]
+dev = [
+  "pytest>=8.3.4",
+  "pytest-asyncio>=0.25.2",
+  "pytest-cov>=6.0.0",
+  "bandit>=1.8.0",
+  "pip-audit>=2.8.0",
+  "ruff>=0.8.0",
+  "pyright>=1.1.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/api"]
+
+[tool.ruff]
+target-version = "py313"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "B", "S", "UP", "ANN"]
+ignore = [
+  "S101", # allow assert in tests
+  "B008", # FastAPI's Depends(...)/Security(...) default-argument pattern is
+  # the sanctioned idiom (see FastAPI's own docs) — not the mutable-default
+  # footgun this rule otherwise guards against.
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = ["S101", "ANN"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+
+[tool.pyright]
+pythonVersion = "3.13"
+typeCheckingMode = "standard"
+venvPath = "."
+venv = ".venv"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py", "*_test.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+asyncio_mode = "auto"
+
+[tool.coverage.run]
+source = ["src"]
+omit = ["*/tests/*"]

package/_skeletons/sibling-template/services/api/src/api/config.py

@@ -0,0 +1,31 @@
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    # Change this prefix to your own sibling's name if you want a more
+    # specific env var namespace — just keep it consistent with
+    # infra/main.tf's environment_variables block.
+    model_config = SettingsConfigDict(env_prefix="SIBLING_", case_sensitive=False)
+
+    # Cognito — deliberately the CORE project's pool/client, not a new one
+    # (ADR-0007): this sibling verifies the same JWT the core portal issued,
+    # so users get single sign-on across the core and every sibling for free.
+    cognito_user_pool_id: str = ""
+    cognito_client_id: str = ""
+    cognito_region: str = "us-east-1"
+    # Pre-loaded JWKS JSON string — set by Terraform at apply time in no-NAT
+    # dev environments so the Lambda can verify JWTs without an outbound
+    # call. If empty, the JWKS is fetched at runtime (requires NAT or a
+    # cognito-idp VPC endpoint).
+    cognito_jwks_json: str = ""
+
+    # The core project's own API — the ONLY place this service is allowed to
+    # get or persist data (ADR-0002). Never add a database client here.
+    core_api_url: str = ""
+
+    environment: str = "dev"
+    log_level: str = "INFO"
+    cors_origins: list[str] = ["http://localhost:3000"]
+
+
+settings = Settings()