thinkwork-cli 0.13.2 → 1.0.0

package/dist/terraform/modules/app/www-dns/main.tf

@@ -3,12 +3,11 @@
 #
 # Responsibilities:
 #   1. ACM certificate in us-east-1 covering apex + www
-#      (+ optional docs + optional admin + optional app + optional computer).
+#      (+ optional admin + optional app + optional computer).
 #   2. Cloudflare DNS records for ACM DNS validation.
 #   3. Apex CNAME in Cloudflare → primary CloudFront distribution (DNS-only).
 #   4. Second CloudFront distribution fronting an S3 website-redirect bucket
 #      that 301s www.<domain> → https://<domain>, plus its Cloudflare CNAME.
-#   5. Optional docs.<domain> CNAME → docs CloudFront distribution.
 #   6. Optional admin.<domain> CNAME → admin CloudFront distribution.
 #   7. Optional app.<domain> CNAME → end-user app CloudFront distribution.
 #   8. Optional computer.<domain> → app.<domain> 301 compatibility redirect.
@@ -37,7 +36,6 @@ terraform {
 locals {
   apex     = var.domain
   www      = "www.${var.domain}"
-  docs     = "docs.${var.domain}"
   admin    = "admin.${var.domain}"
   app      = "app.${var.domain}"
   computer = "computer.${var.domain}"
@@ -47,7 +45,7 @@ locals {
   n8n      = "n8n.${var.domain}"
   name_id  = replace(var.domain, ".", "-")
 
-  # ACM SANs: always include www, conditionally include docs, admin, computer,
+  # ACM SANs: always include www, conditionally include admin, computer,
   # and api. The Computer iframe sandbox and CRM ALB use their own certificates
   # so adding or rotating those hosts never forces a replacement of this shared
   # production certificate.
@@ -56,11 +54,16 @@ locals {
   # depend on the cert, so the cert mustn't depend on those outputs.
   cert_sans = concat(
     [local.www],
-    var.include_docs ? [local.docs] : [],
     var.include_admin ? [local.admin] : [],
     var.include_app ? [local.app] : [],
     var.include_computer ? [local.computer] : [],
     var.include_api ? [local.api] : [],
+    # Retired docs.<domain> SAN, retained on stacks deployed before THINK-702.
+    # Shrinking the SAN list forces a create-before-destroy replacement of this
+    # shared certificate, which cannot be ordered against the thinkwork module
+    # (the two modules feed each other) and fails the plan with a cycle. A dead
+    # SAN costs nothing and its validation CNAME stays in place for renewals.
+    var.retain_docs_san ? ["docs.${var.domain}"] : [],
   )
 
   # Existing CNAME records stay gated on non-empty targets because their target
@@ -68,7 +71,6 @@ locals {
   # such as app/computer compatibility/sandbox/crm CNAMEs must gate only on
   # explicit booleans so Terraform can plan the resource count before the new
   # load balancer exists.
-  create_docs_record     = var.include_docs && var.docs_cloudfront_domain_name != ""
   create_admin_record    = var.include_admin && var.admin_cloudfront_domain_name != ""
   create_app_record      = var.include_app
   create_computer_record = var.include_computer
@@ -78,7 +80,7 @@ locals {
 }
 
 ################################################################################
-# ACM certificate (us-east-1, covers apex + www [+ docs])
+# ACM certificate (us-east-1, covers apex + www [+ optional subdomains])
 ################################################################################
 
 resource "aws_acm_certificate" "www" {
@@ -244,26 +246,6 @@ resource "cloudflare_record" "www_redirect" {
   comment = "thinkwork-${var.stage} www → redirect distribution"
 }
 
-################################################################################
-# docs.<domain> → docs CloudFront distribution (optional)
-#
-# Created only when the greenfield stack wires docs_cloudfront_domain_name.
-# The docs CloudFront alias picks up the same ACM cert via certificate_arn
-# on the thinkwork module's docs_site.
-################################################################################
-
-resource "cloudflare_record" "docs" {
-  count = local.create_docs_record ? 1 : 0
-
-  zone_id = var.cloudflare_zone_id
-  name    = local.docs
-  content = var.docs_cloudfront_domain_name
-  type    = "CNAME"
-  ttl     = 300
-  proxied = false
-  comment = "thinkwork-${var.stage} docs → CloudFront"
-}
-
 ################################################################################
 # admin.<domain> → admin CloudFront distribution (optional)
 ################################################################################

package/dist/terraform/modules/app/www-dns/variables.tf

@@ -18,20 +18,14 @@ variable "cloudfront_domain_name" {
   type        = string
 }
 
-variable "include_docs" {
-  description = "When true, add docs.<domain> to the ACM cert SANs and create a Cloudflare CNAME for it. Separated from docs_cloudfront_domain_name to avoid a Terraform dependency cycle (distribution depends on cert, so the cert can't depend on the distribution output)."
+variable "retain_docs_san" {
+  description = "When true, keep the retired docs.<domain> SAN on the shared ACM certificate. Set on stacks deployed before THINK-702 so removing the docs site does not force a certificate replacement (which cycles against the thinkwork module). New stacks leave this false."
   type        = bool
   default     = false
 }
 
-variable "docs_cloudfront_domain_name" {
-  description = "CloudFront distribution domain name for the docs site. Used as the target for the docs.<domain> Cloudflare CNAME when include_docs is true."
-  type        = string
-  default     = ""
-}
-
 variable "include_admin" {
-  description = "When true, add admin.<domain> to the ACM cert SANs and create a Cloudflare CNAME for it. Same cycle-avoidance rationale as include_docs."
+  description = "When true, add admin.<domain> to the ACM cert SANs and create a Cloudflare CNAME for it. Gated on a plain bool (not a CloudFront output) to keep the dependency graph acyclic."
   type        = bool
   default     = false
 }
@@ -67,7 +61,7 @@ variable "computer_cloudfront_domain_name" {
 }
 
 variable "include_computer_sandbox" {
-  description = "When true, add sandbox.<domain> to the ACM cert SANs and create a Cloudflare CNAME for it. Same cycle-avoidance rationale as include_docs."
+  description = "When true, add sandbox.<domain> to the ACM cert SANs and create a Cloudflare CNAME for it. Gated on a plain bool (not a CloudFront output) to keep the dependency graph acyclic."
   type        = bool
   default     = false
 }

package/dist/terraform/modules/data/aurora-postgres/README.md

@@ -78,6 +78,8 @@ module "database" {
 | `max_capacity` | number | `2` | Aurora max ACU (aurora-serverless only) |
 | `rds_instance_class` | string | `"db.t4g.micro"` | RDS instance class (rds-postgres only) |
 | `rds_allocated_storage` | number | `20` | Storage in GB (rds-postgres only) |
+| `publicly_accessible` | bool | `true` | Public IP on the cluster instance / RDS instance. `false` once every client is inside the VPC (THINK-1082) |
+| `public_ingress_cidrs` | list(string) | `["0.0.0.0/0"]` | CIDR tcp/5432 ingress seeded on a **new** database security group. `[]` = none. Does not revoke a live rule (see below) |
 | `deletion_protection` | bool | `null` | Auto: `true` for Aurora, `false` for RDS |
 
 ## Outputs
@@ -90,3 +92,35 @@ module "database" {
 | `db_security_group_id` | Security group ID |
 | `database_url` | Full connection string (sensitive) |
 | `database_engine` | Which engine is running |
+
+## Closing the public port (THINK-1082)
+
+By default the database gets a public endpoint (`publicly_accessible = true`)
+and its security group is seeded with a world-open `0.0.0.0/0 -> 5432` ingress.
+Every client that has no `vpc_config` (the api Lambdas, the deployment runner's
+`psql`) depends on that rule. Revoking it before those clients move inside the
+VPC takes the app down (auth-me -> DB timeout -> 401).
+
+Two facts govern the close:
+
+1. The security group has `lifecycle { ignore_changes = [name, ingress] }` so
+   app modules can attach standalone `aws_security_group_rule` grants for their
+   own security groups (ECS tasks, the runner, the api-lambda group). Because of
+   that, setting `public_ingress_cidrs = []` on an existing stage changes what
+   Terraform would create and stops it re-seeding the rule, but **does not
+   revoke the rule that already exists**. The operator revokes it by hand, once:
+
+   ```bash
+   aws ec2 revoke-security-group-ingress --group-id <thinkwork-<stage>-db-sg> \
+     --protocol tcp --port 5432 --cidr 0.0.0.0/0
+   ```
+
+2. `publicly_accessible = false` removes the public IP (a modify on the
+   instance, applied immediately). Do it in the same step as, or after, the
+   ingress close — never before the clients are in the VPC.
+
+The RDS Data API (`enable_http_endpoint = true`) keeps working throughout: it
+needs IAM, not a network path, so operator SQL and the Pi session store are
+unaffected. The stage-level order (Lambdas first, runner second, port last) is
+in `modules/app/deployment-control-plane/README.md`, "Closing the database
+port".

package/dist/terraform/modules/data/aurora-postgres/alarms.tf

@@ -0,0 +1,82 @@
+################################################################################
+# Aurora Serverless v2 saturation alarms
+#
+# STATISTIC MATTERS HERE. RDS publishes CPUUtilization from 1-second samples,
+# so the `Maximum` statistic over any period reports the single busiest second
+# in that period — on Serverless v2 that reads as ~100% essentially forever
+# and tells you nothing. An operator chasing "the database is pegged" off the
+# Maximum series is chasing an artifact of the sampling rate, not load.
+#
+# Both alarms below therefore use `Average`, which is the statistic that
+# actually tracks sustained saturation:
+#   - CPUUtilization  — average CPU across the 5-minute period.
+#   - ACUUtilization  — how much of the configured max_capacity ACU ceiling
+#                       the cluster is consuming. This is the one that
+#                       matters for Serverless v2: sustained high ACU means
+#                       the cluster is near its scaling ceiling and the next
+#                       load step has nowhere to go.
+#
+# 3 × 5-minute evaluation periods (15 minutes of sustained pressure) so a
+# migration, a backfill, or a burst of agent traffic does not page anyone.
+#
+# alarm_actions are empty by module convention — this module owns no SNS
+# topic, and the app module's only topic is the cost-alert channel (see
+# terraform/modules/app/lambda-api/memory-alarms.tf for the same reasoning).
+# Operators subscribe a topic when a stage needs paging.
+#
+# Aurora-only: ACUUtilization does not exist for the rds-postgres dev/test
+# engine, and the pairing is what makes these useful, so both are gated on
+# local.use_aurora.
+################################################################################
+
+resource "aws_cloudwatch_metric_alarm" "aurora_cpu_utilization_high" {
+  count = local.use_aurora ? 1 : 0
+
+  alarm_name        = "thinkwork-${var.stage}-db-cpu-utilization-high"
+  alarm_description = "Aurora writer instance averaged >${var.cpu_utilization_alarm_threshold}% CPU for 15 minutes. Statistic is Average by design — the Maximum series is ~100% at all times because RDS samples CPU every second."
+
+  namespace   = "AWS/RDS"
+  metric_name = "CPUUtilization"
+  statistic   = "Average"
+
+  period              = 300
+  evaluation_periods  = 3
+  threshold           = var.cpu_utilization_alarm_threshold
+  comparison_operator = "GreaterThanThreshold"
+  treat_missing_data  = "notBreaching"
+  alarm_actions       = []
+
+  dimensions = {
+    DBInstanceIdentifier = aws_rds_cluster_instance.main[0].identifier
+  }
+
+  tags = {
+    Name = "thinkwork-${var.stage}-db-cpu-utilization-high"
+  }
+}
+
+resource "aws_cloudwatch_metric_alarm" "aurora_acu_utilization_high" {
+  count = local.use_aurora ? 1 : 0
+
+  alarm_description = "Aurora Serverless v2 averaged >${var.acu_utilization_alarm_threshold}% of its max_capacity ACU ceiling for 15 minutes — the cluster is close to having nowhere left to scale. Raise max_capacity or shed load."
+  alarm_name        = "thinkwork-${var.stage}-db-acu-utilization-high"
+
+  namespace   = "AWS/RDS"
+  metric_name = "ACUUtilization"
+  statistic   = "Average"
+
+  period              = 300
+  evaluation_periods  = 3
+  threshold           = var.acu_utilization_alarm_threshold
+  comparison_operator = "GreaterThanThreshold"
+  treat_missing_data  = "notBreaching"
+  alarm_actions       = []
+
+  dimensions = {
+    DBInstanceIdentifier = aws_rds_cluster_instance.main[0].identifier
+  }
+
+  tags = {
+    Name = "thinkwork-${var.stage}-db-acu-utilization-high"
+  }
+}

package/dist/terraform/modules/data/aurora-postgres/main.tf

@@ -53,12 +53,20 @@ resource "aws_security_group" "db" {
   description = "Security group for Thinkwork PostgreSQL database"
   vpc_id      = var.vpc_id
 
-  ingress {
-    from_port   = 5432
-    to_port     = 5432
-    protocol    = "tcp"
-    cidr_blocks = ["0.0.0.0/0"]
-    description = "PostgreSQL access"
+  # THINK-1082: the inline CIDR ingress is now driven by public_ingress_cidrs
+  # (default ["0.0.0.0/0"] = today's world-open rule; [] = none). Because
+  # ingress is in ignore_changes below, this only shapes a NEW group and stops
+  # Terraform from re-seeding the rule — it never revokes a live one.
+  dynamic "ingress" {
+    for_each = length(var.public_ingress_cidrs) > 0 ? [1] : []
+
+    content {
+      from_port   = 5432
+      to_port     = 5432
+      protocol    = "tcp"
+      cidr_blocks = var.public_ingress_cidrs
+      description = "PostgreSQL access"
+    }
   }
 
   egress {
@@ -76,7 +84,10 @@ resource "aws_security_group" "db" {
     # App modules grant their own task security groups database access through
     # standalone aws_security_group_rule resources. Keep this shared group from
     # trying to reconcile those externally managed ingress rules during targeted
-    # managed-app deploys.
+    # managed-app deploys. Consequence (THINK-1082): setting
+    # public_ingress_cidrs = [] on a live stage does not revoke the existing
+    # 0.0.0.0/0 rule — the operator revokes it by hand once the clients are
+    # in the VPC (see README.md "Closing the public port").
     ignore_changes = [name, ingress]
   }
 }
@@ -117,15 +128,11 @@ resource "aws_rds_cluster" "main" {
   deletion_protection  = local.deletion_protection
   storage_encrypted    = true
 
-  # THINK-229 U1 (R1): the analyst-query-broker Lambda authenticates as
-  # analyst_reader with per-connect RDS IAM auth tokens instead of a
-  # stored password. Cluster-level flag; applies without downtime.
-  # apply_immediately is required: the provider default defers cluster
-  # modifications to the maintenance window, and if the GRANT rds_iam
-  # migration (0229) landed inside that pending window the role would
-  # refuse BOTH password (grant applied) and IAM (flag still pending)
-  # login. Deploys on this platform are CLI/CI-driven and expect
-  # immediate semantics.
+  # RDS IAM database authentication: roles granted rds_iam log in with
+  # per-connect auth tokens instead of a stored password. Cluster-level
+  # flag; applies without downtime. apply_immediately is required — the
+  # provider default defers cluster modifications to the maintenance
+  # window, which can strand a role between the GRANT and the flag.
   iam_database_authentication_enabled = true
   apply_immediately                   = true
 
@@ -154,7 +161,7 @@ resource "aws_rds_cluster_instance" "main" {
   engine             = aws_rds_cluster.main[0].engine
   engine_version     = aws_rds_cluster.main[0].engine_version
 
-  publicly_accessible  = true
+  publicly_accessible  = var.publicly_accessible
   db_subnet_group_name = aws_db_subnet_group.main[0].name
 
   tags = {
@@ -188,13 +195,12 @@ resource "aws_db_instance" "main" {
   db_subnet_group_name   = aws_db_subnet_group.main[0].name
   vpc_security_group_ids = [aws_security_group.db[0].id]
 
-  publicly_accessible = true
+  publicly_accessible = var.publicly_accessible
   skip_final_snapshot = true
   deletion_protection = local.deletion_protection
 
-  # THINK-229 U1 (R1): keep the rds-postgres dev/test engine at parity
-  # with the Aurora cluster — analyst_reader logs in with IAM tokens.
-  # apply_immediately for the same both-paths-stranded reason as the
+  # Keep the rds-postgres dev/test engine at IAM-auth parity with the
+  # Aurora cluster. apply_immediately for the same stranding reason as the
   # Aurora cluster block above.
   iam_database_authentication_enabled = true
   apply_immediately                   = true
@@ -377,39 +383,3 @@ resource "aws_secretsmanager_secret" "compliance_reader" {
     Role = "compliance_reader"
   }
 }
-
-################################################################################
-# Secrets Manager — Analyst Reader Role Credentials (THINK-228 U2)
-#
-# Container for the analyst_reader Aurora role used by the analyst
-# query-broker Lambda. Terraform owns the SECRET CONTAINER; the operator
-# owns the SECRET VALUE (populated by scripts/bootstrap-analyst-roles.sh,
-# which also applies drizzle/0227_analyst_reader_role.sql to create the
-# matching hardened read-only role).
-################################################################################
-
-resource "aws_secretsmanager_secret" "analyst_reader" {
-  count = local.create ? 1 : 0
-  name  = "thinkwork/${var.stage}/analyst/reader-credentials"
-
-  tags = {
-    Name = "thinkwork-${var.stage}-analyst-reader-credentials"
-    Role = "analyst_reader"
-  }
-}
-
-# Broker caller credential for the analyst query broker (THINK-228 U3).
-# The connector row (tenant_mcp_servers, seeded by
-# scripts/provision-analyst-connector.mts) references this ARN as its
-# auth_config.secretRef; the broker Lambda validates incoming Bearer
-# tokens against it. Value shape: JSON {token, tenantId} — populated by
-# the provisioning script, never by Terraform.
-resource "aws_secretsmanager_secret" "analyst_broker" {
-  count = local.create ? 1 : 0
-  name  = "thinkwork/${var.stage}/analyst/broker-credential"
-
-  tags = {
-    Name = "thinkwork-${var.stage}-analyst-broker-credential"
-    Role = "analyst_query_broker"
-  }
-}

package/dist/terraform/modules/data/aurora-postgres/outputs.tf

@@ -68,12 +68,3 @@ output "compliance_reader_secret_arn" {
   value       = local.create ? aws_secretsmanager_secret.compliance_reader[0].arn : ""
 }
 
-output "analyst_reader_secret_arn" {
-  description = "Secrets Manager ARN for the analyst_reader Aurora role (THINK-228 U2). Empty string when create_database = false."
-  value       = local.create ? aws_secretsmanager_secret.analyst_reader[0].arn : ""
-}
-
-output "analyst_broker_secret_arn" {
-  description = "Secrets Manager ARN for the analyst query-broker caller credential (THINK-228 U3). Empty string when create_database = false."
-  value       = local.create ? aws_secretsmanager_secret.analyst_broker[0].arn : ""
-}

package/dist/terraform/modules/data/aurora-postgres/variables.tf

@@ -113,6 +113,31 @@ variable "deletion_protection" {
   default     = null
 }
 
+# ---------------------------------------------------------------------------
+# Network exposure (THINK-1082). Defaults reproduce today's posture: a public
+# endpoint plus a world-open 0.0.0.0/0 -> 5432 ingress. A stage whose database
+# clients (api Lambdas, deployment runner, ECS tasks) all reach the cluster by
+# security group closes the port by setting public_ingress_cidrs = [] and
+# publicly_accessible = false. NOTE: the DB security group ignores ingress
+# drift (lifecycle.ignore_changes) so that app modules can own their own
+# standalone rules — which means shrinking this list does NOT revoke a rule
+# that already exists on a live group. The operator revokes it by hand once;
+# this variable governs what a fresh group is created with and what
+# Terraform stops re-seeding. See README.md "Closing the public port".
+# ---------------------------------------------------------------------------
+
+variable "publicly_accessible" {
+  description = "Whether the cluster instance / RDS instance gets a public IP (publicly_accessible). Default true = today's posture. Set false once every client reaches the database inside the VPC by security group."
+  type        = bool
+  default     = true
+}
+
+variable "public_ingress_cidrs" {
+  description = "CIDR blocks seeded as tcp/5432 ingress on the database security group when it is created. Default [\"0.0.0.0/0\"] = today's world-open rule. [] seeds no inline rule (clients are admitted by security-group-sourced rules instead). Because the group ignores ingress drift, changing this on an existing stage does not revoke the live rule — revoke it by hand after the clients are inside the VPC."
+  type        = list(string)
+  default     = ["0.0.0.0/0"]
+}
+
 # ---------------------------------------------------------------------------
 # aws_s3 Aurora extension (optional — set backups_bucket_arn to enable)
 # ---------------------------------------------------------------------------
@@ -123,6 +148,22 @@ variable "backups_bucket_arn" {
   default     = null
 }
 
+# ---------------------------------------------------------------------------
+# CloudWatch saturation alarms (aurora-serverless engine only; see alarms.tf)
+# ---------------------------------------------------------------------------
+
+variable "cpu_utilization_alarm_threshold" {
+  description = "Average CPUUtilization percentage that, sustained for 3x5min, raises the Aurora CPU alarm. Evaluated against the Average statistic — the Maximum statistic is meaningless on RDS (1-second sampling pins it near 100%)."
+  type        = number
+  default     = 70
+}
+
+variable "acu_utilization_alarm_threshold" {
+  description = "Average ACUUtilization percentage (share of max_capacity consumed) that, sustained for 3x5min, raises the Aurora Serverless v2 scaling-headroom alarm."
+  type        = number
+  default     = 85
+}
+
 variable "enable_aws_s3" {
   description = "Plan-time gate for the aws_s3 Aurora extension IAM role. Set true when Aurora should be allowed to PutObject into backups_bucket_arn. Only effective when database_engine = 'aurora-serverless'. Defaults to false to preserve the prior 'opt-in by passing backups_bucket_arn' shape when this variable is omitted."
   type        = bool

package/dist/terraform/modules/data/s3-buckets/main.tf

@@ -1,7 +1,7 @@
 ################################################################################
 # S3 Buckets — Data Module
 #
-# Creates the primary S3 bucket for skills, artifacts, knowledge base docs,
+# Creates the primary S3 bucket for skills, artifacts,
 # and email inbound storage. HTTPS-only enforcement + SES inbound policy.
 ################################################################################
 
@@ -109,11 +109,10 @@ output "bucket_arn" {
   value       = aws_s3_bucket.main.arn
 }
 
-# Analyst query-broker result staging (THINK-228 U3). Results larger than
-# the inline envelope cap land as CSVs under analyst-staging/<tenantId>/
-# with SSE; they are scratch data consumed by the agent sandbox within the
-# same delegation, so a short TTL bounds both storage cost and the window
-# in which a leaked object key is useful.
+# Janitor for the RETIRED analyst query broker's staged results. The broker
+# is gone, but stages that ran it still hold CSVs under analyst-staging/.
+# Keeping the expiry rule drains them; deleting it would strand that data
+# with no TTL. Safe to remove once every stage's prefix is empty.
 resource "aws_s3_bucket_lifecycle_configuration" "analyst_staging" {
   bucket = aws_s3_bucket.main.id
 

package/dist/terraform/modules/foundation/cognito/main.tf

@@ -42,11 +42,6 @@ locals {
       logout_urls        = var.mobile_logout_urls
       refresh_token_days = 90
     }
-    desktop = {
-      callback_urls      = var.desktop_callback_urls
-      logout_urls        = var.desktop_callback_urls
-      refresh_token_days = 30
-    }
     cli = {
       callback_urls      = var.cli_callback_urls
       logout_urls        = var.cli_logout_urls
@@ -526,7 +521,6 @@ resource "aws_cognito_user_pool_client" "auth_route" {
 
   write_attributes = [
     "email",
-    "email_verified",
     "name",
     "custom:tenant_id",
     "custom:entra_tenant_id",
@@ -608,8 +602,8 @@ resource "aws_cognito_user_pool_client" "admin" {
 
   supported_identity_providers = local.identity_providers
 
-  callback_urls = distinct(concat(var.admin_callback_urls, var.desktop_callback_urls, var.cli_callback_urls))
-  logout_urls   = distinct(concat(var.admin_logout_urls, var.desktop_callback_urls, var.cli_logout_urls))
+  callback_urls = distinct(concat(var.admin_callback_urls, var.cli_callback_urls))
+  logout_urls   = distinct(concat(var.admin_logout_urls, var.cli_logout_urls))
 
   access_token_validity  = 1
   id_token_validity      = 1
@@ -696,6 +690,76 @@ resource "aws_cognito_user_pool_client" "mobile" {
   ]
 }
 
+################################################################################
+# App Client — Company Brain console (U13, optional; ship-inert default off)
+#
+# Same OAuth flows/scopes/providers as the web client family. Gated on
+# console_client_enabled so merging this creates nothing; enablement requires
+# the console's callback URLs to be registered here FIRST (redirect_mismatch
+# otherwise).
+################################################################################
+
+resource "aws_cognito_user_pool_client" "console" {
+  count        = local.create && var.console_client_enabled ? 1 : 0
+  name         = "ThinkworkConsole"
+  user_pool_id = aws_cognito_user_pool.main[0].id
+
+  generate_secret                      = false
+  allowed_oauth_flows_user_pool_client = true
+  allowed_oauth_flows                  = ["code"]
+  allowed_oauth_scopes                 = ["openid", "email", "profile"]
+
+  explicit_auth_flows = [
+    "ALLOW_USER_PASSWORD_AUTH",
+    "ALLOW_USER_SRP_AUTH",
+    "ALLOW_REFRESH_TOKEN_AUTH",
+  ]
+
+  supported_identity_providers = local.identity_providers
+
+  callback_urls = distinct(var.console_callback_urls)
+  logout_urls   = distinct(var.console_logout_urls)
+
+  enable_token_revocation       = true
+  prevent_user_existence_errors = "ENABLED"
+  access_token_validity         = 1
+  id_token_validity             = 1
+  refresh_token_validity        = 30
+
+  token_validity_units {
+    access_token  = "hours"
+    id_token      = "hours"
+    refresh_token = "days"
+  }
+
+  read_attributes = [
+    "email",
+    "email_verified",
+    "name",
+    "custom:tenant_id",
+  ]
+
+  write_attributes = [
+    "email",
+    "name",
+    "custom:tenant_id",
+  ]
+
+  lifecycle {
+    precondition {
+      condition     = length(var.console_callback_urls) > 0
+      error_message = "console_callback_urls must be non-empty when console_client_enabled — register the console URL before first login or Cognito fails with redirect_mismatch."
+    }
+  }
+
+  depends_on = [
+    aws_cognito_identity_provider.google,
+    aws_cognito_identity_provider.microsoft_organizations,
+    aws_cognito_identity_provider.oidc,
+    aws_cognito_identity_provider.saml,
+  ]
+}
+
 ################################################################################
 # Identity Pool
 ################################################################################
@@ -726,6 +790,15 @@ resource "aws_cognito_identity_pool" "main" {
     }
   }
 
+  dynamic "cognito_identity_providers" {
+    for_each = aws_cognito_user_pool_client.console
+    content {
+      client_id               = cognito_identity_providers.value.id
+      provider_name           = "cognito-idp.${var.region}.amazonaws.com/${aws_cognito_user_pool.main[0].id}"
+      server_side_token_check = true
+    }
+  }
+
   tags = {
     Name = "thinkwork-${var.stage}-identity-pool"
   }

package/dist/terraform/modules/foundation/cognito/outputs.tf

@@ -18,6 +18,11 @@ output "mobile_client_id" {
   value       = local.mobile_client_id
 }
 
+output "console_client_id" {
+  description = "App client ID for the optional Company Brain console client (null while console_client_enabled = false)"
+  value       = one(aws_cognito_user_pool_client.console[*].id)
+}
+
 output "identity_pool_id" {
   description = "Identity pool ID (created or existing)"
   value       = local.identity_pool_id

package/dist/terraform/modules/foundation/cognito/variables.tf

@@ -147,8 +147,8 @@ variable "microsoft_oauth_tenant" {
   default     = ""
 
   validation {
-    condition     = var.microsoft_oauth_tenant == "" || can(regex("^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$", var.microsoft_oauth_tenant))
-    error_message = "microsoft_oauth_tenant must be an Entra directory GUID."
+    condition     = var.microsoft_oauth_tenant == "" || contains(["common", "organizations", "consumers"], var.microsoft_oauth_tenant) || can(regex("^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$", var.microsoft_oauth_tenant))
+    error_message = "microsoft_oauth_tenant must be an Entra directory GUID or one of the Cognito-supported aliases: common, organizations, consumers."
   }
 }
 
@@ -295,16 +295,6 @@ variable "admin_logout_urls" {
   ]
 }
 
-variable "desktop_callback_urls" {
-  description = "OAuth callback and logout URLs for the desktop client that reuses the ThinkworkAdmin public Cognito client."
-  type        = list(string)
-  default = [
-    "thinkwork://oauth/callback",
-    "thinkwork-dev://oauth/callback",
-    "thinkwork-canary://oauth/callback",
-  ]
-}
-
 variable "cli_callback_urls" {
   description = "OAuth loopback callbacks reserved for the CLI client family."
   type        = list(string)
@@ -323,6 +313,28 @@ variable "cli_logout_urls" {
   ]
 }
 
+# ---------------------------------------------------------------------------
+# Company Brain console client (U13 — ship-inert, default off)
+# ---------------------------------------------------------------------------
+
+variable "console_client_enabled" {
+  description = "Create the optional Company Brain console app client. Default false = no client, console_client_id output is null (ship-inert until Eric reviews the console app)."
+  type        = bool
+  default     = false
+}
+
+variable "console_callback_urls" {
+  description = "OAuth callback URLs for the console client. MUST include the console's CloudFront/custom-domain URL BEFORE first login — Cognito rejects unregistered origins with redirect_mismatch. Required non-empty when console_client_enabled."
+  type        = list(string)
+  default     = []
+}
+
+variable "console_logout_urls" {
+  description = "OAuth logout URLs for the console client"
+  type        = list(string)
+  default     = []
+}
+
 variable "existing_auth_route_clients" {
   description = "Safe route-client manifest when using a BYO Cognito pool. Keys use <family>:<route>."
   type = map(object({