feat(api): gate bgg-warehouse-api via authoritative Terraform invoker binding

terraform/warehouse_api.tf

@@ -0,0 +1,36 @@
+# Gating for the warehouse read API (bgg-warehouse-api Cloud Run service).
+#
+# The service itself is deployed by the Cloud Build Actions workflow
+# (config/cloudbuild.warehouse-api.yaml). Terraform owns ONLY its inbound invoker IAM,
+# as an AUTHORITATIVE binding so `allUsers` can never be (re)added out of band — the
+# whole point of the gating. Applied by .github/workflows/terraform.yml.
+#
+# ORDERING: this binding targets an existing service, so it must be applied AFTER the
+# service is first deployed (merge the deploy PR before merging this one).
+#
+# See docs/superpowers/specs/2026-07-16-service-auth-pattern-design.md
+
+variable "warehouse_api_invoker_members" {
+  description = <<-EOT
+    Principals granted roles/run.invoker on bgg-warehouse-api (AUTHORITATIVE — this is
+    the complete allow-list; anything not here, including allUsers, cannot invoke).
+
+    This list IS the grant surface: to give a consumer access, add its identity here and
+    merge (terraform.yml applies it) — grants stay in code, reviewed, and git-audited.
+      - a person:  "user:someone@example.com"
+      - a service: "serviceAccount:new-frontend@bgg-data-warehouse.iam.gserviceaccount.com"
+    (A "group:..." member is possible too, but a group's membership is managed outside
+    Terraform/Actions — prefer listing identities directly here.)
+  EOT
+  type    = list(string)
+  default = ["user:phil.henrickson@gmail.com"]
+}
+
+resource "google_cloud_run_v2_service_iam_binding" "warehouse_api_invokers" {
+  project  = var.project_id
+  location = var.region
+  name     = "bgg-warehouse-api"
+  role     = "roles/run.invoker"
+
+  members = var.warehouse_api_invoker_members
+}