template.yaml

AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: Agent Hub (Forge) - authoritative personal agent hub with satellites (SAM)

Parameters:
  StageName:
    Type: String
    Default: dev
  DbName:
    Type: String
    Default: agenthub
  AuroraMinACU:
    Type: Number
    Default: 0.5
  AuroraMaxACU:
    Type: Number
    Default: 2
  PlannerModel:
    Type: String
    Default: gpt-4.1-mini

  MaxSpacesPerAgent:
    Type: String
    Default: "5"

  LiveKitUrl:
    Type: String
    Description: LiveKit server URL (e.g. wss://your.livekit.host or https://...). Leave empty to disable LiveKit token minting.
    Default: ""

  ApiDeploymentVersion:
    Type: String
    Description: Version string to force API Gateway deployment updates
    Default: "1"

  CognitoDomainPrefix:
    Type: String
    Description: Prefix for Cognito Hosted UI domain (must be globally unique across all AWS accounts). Leave empty to auto-generate.
    Default: ""

  EnableGoogleAuth:
    Type: String
    Description: Enable Google as a Cognito Hosted UI identity provider (requires google-oauth secret to be populated).
    AllowedValues:
      - "true"
      - "false"
    Default: "false"

  GuiCallbackUrls:
    Type: CommaDelimitedList
    Description: Allowed Cognito callback URLs for the (local) GUI OAuth flow
    Default: "http://localhost:8084/auth/callback,https://localhost:8084/auth/callback"

  GuiLogoutUrls:
    Type: CommaDelimitedList
    Description: Allowed Cognito logout URLs for the (local) GUI OAuth flow
    Default: "http://localhost:8084/logged-out,https://localhost:8084/logged-out"

Conditions:
  IsDeploymentV1: !Equals [!Ref ApiDeploymentVersion, "1"]
  IsDeploymentV2: !Equals [!Ref ApiDeploymentVersion, "2"]
  HasCognitoDomainPrefix: !Not [!Equals [!Ref CognitoDomainPrefix, ""]]
  GoogleAuthEnabled: !Equals [!Ref EnableGoogleAuth, "true"]
  GoogleAuthDisabled: !Equals [!Ref EnableGoogleAuth, "false"]

Globals:
  Function:
    Runtime: python3.11
    Timeout: 30
    MemorySize: 512
    Tracing: Active
    Environment:
      Variables:
        STAGE: !Ref StageName

Resources:
  # -----------------------------
  # Networking (minimal VPC for Aurora)
  # -----------------------------
  HubVpc:
    Type: AWS::EC2::VPC
    Properties:
      CidrBlock: 10.20.0.0/16
      EnableDnsSupport: true
      EnableDnsHostnames: true
      Tags:
        - Key: Name
          Value: !Sub ${AWS::StackName}-vpc

  PrivateSubnetA:
    Type: AWS::EC2::Subnet
    Properties:
      VpcId: !Ref HubVpc
      AvailabilityZone: !Select [0, !GetAZs '']
      CidrBlock: 10.20.0.0/24
      MapPublicIpOnLaunch: false
      Tags:
        - Key: Name
          Value: !Sub ${AWS::StackName}-priv-a

  PrivateSubnetB:
    Type: AWS::EC2::Subnet
    Properties:
      VpcId: !Ref HubVpc
      AvailabilityZone: !Select [1, !GetAZs '']
      CidrBlock: 10.20.1.0/24
      MapPublicIpOnLaunch: false
      Tags:
        - Key: Name
          Value: !Sub ${AWS::StackName}-priv-b

  PrivateRouteTable:
    Type: AWS::EC2::RouteTable
    Properties:
      VpcId: !Ref HubVpc

  PrivateSubnetARouteTableAssociation:
    Type: AWS::EC2::SubnetRouteTableAssociation
    Properties:
      SubnetId: !Ref PrivateSubnetA
      RouteTableId: !Ref PrivateRouteTable

  PrivateSubnetBRouteTableAssociation:
    Type: AWS::EC2::SubnetRouteTableAssociation
    Properties:
      SubnetId: !Ref PrivateSubnetB
      RouteTableId: !Ref PrivateRouteTable

  DbSecurityGroup:
    Type: AWS::EC2::SecurityGroup
    Properties:
      GroupDescription: !Sub ${AWS::StackName} Aurora SG
      VpcId: !Ref HubVpc

  DbSubnetGroup:
    Type: AWS::RDS::DBSubnetGroup
    Properties:
      DBSubnetGroupDescription: Subnet group for AgentHub Aurora
      SubnetIds:
        - !Ref PrivateSubnetA
        - !Ref PrivateSubnetB

  # -----------------------------
  # Secrets
  # -----------------------------
  DbCredentialsSecret:
    Type: AWS::SecretsManager::Secret
    Properties:
      Name: !Sub ${AWS::StackName}/db-credentials
      GenerateSecretString:
        SecretStringTemplate: '{"username":"agenthub"}'
        GenerateStringKey: password
        ExcludePunctuation: true
        PasswordLength: 32

  AdminApiKeySecret:
    Type: AWS::SecretsManager::Secret
    Properties:
      Name: !Sub ${AWS::StackName}/admin-api-key
      GenerateSecretString:
        SecretStringTemplate: '{"admin_api_key":""}'
        GenerateStringKey: admin_api_key
        PasswordLength: 40
        ExcludePunctuation: true

  OpenAISecret:
    Type: AWS::SecretsManager::Secret
    Properties:
      Name: !Sub ${AWS::StackName}/openai
      Description: Store your OpenAI API key as {"api_key":"..."}
      SecretString: '{"api_key":"REPLACE_ME"}'

  LiveKitSecret:
    Type: AWS::SecretsManager::Secret
    Properties:
      Name: !Sub ${AWS::StackName}/livekit
      Description: Store your LiveKit credentials as {"api_key":"...","api_secret":"..."}
      SecretString: '{"api_key":"REPLACE_ME","api_secret":"REPLACE_ME"}'

  GoogleOAuthSecret:
    Type: AWS::SecretsManager::Secret
    Properties:
      Name: !Sub ${AWS::StackName}/google-oauth
      Description: Store your Google OAuth credentials as {"client_id":"...","client_secret":"..."} for Cognito federation
      SecretString: '{"client_id":"REPLACE_ME","client_secret":"REPLACE_ME"}'

  # -----------------------------
  # Aurora PostgreSQL Serverless v2 + Data API
  # -----------------------------
  AuroraCluster:
    Type: AWS::RDS::DBCluster
    Properties:
      Engine: aurora-postgresql
      DatabaseName: !Ref DbName
      DBSubnetGroupName: !Ref DbSubnetGroup
      VpcSecurityGroupIds:
        - !Ref DbSecurityGroup
      StorageEncrypted: true
      MasterUsername: !Sub '{{resolve:secretsmanager:${DbCredentialsSecret}:SecretString:username}}'
      MasterUserPassword: !Sub '{{resolve:secretsmanager:${DbCredentialsSecret}:SecretString:password}}'
      EnableHttpEndpoint: true
      ServerlessV2ScalingConfiguration:
        MinCapacity: !Ref AuroraMinACU
        MaxCapacity: !Ref AuroraMaxACU

  AuroraInstance:
    Type: AWS::RDS::DBInstance
    Properties:
      Engine: aurora-postgresql
      DBClusterIdentifier: !Ref AuroraCluster
      DBInstanceClass: db.serverless

  # -----------------------------
  # S3 buckets
  # -----------------------------
  ArtifactBucket:
    Type: AWS::S3::Bucket
    DeletionPolicy: Retain
    UpdateReplacePolicy: Retain
    Properties:
      VersioningConfiguration:
        Status: Enabled
      PublicAccessBlockConfiguration:
        BlockPublicAcls: true
        BlockPublicPolicy: true
        IgnorePublicAcls: true
        RestrictPublicBuckets: true
      LifecycleConfiguration:
        Rules:
          - Id: ExpireRecognitionArtifacts
            Status: Enabled
            Prefix: recognition/
            ExpirationInDays: 1
            NoncurrentVersionExpirationInDays: 1
            AbortIncompleteMultipartUpload:
              DaysAfterInitiation: 1

  AuditBucket:
    Type: AWS::S3::Bucket
    DeletionPolicy: Retain
    UpdateReplacePolicy: Retain
    Properties:
      ObjectLockEnabled: true
      VersioningConfiguration:
        Status: Enabled
      ObjectLockConfiguration:
        ObjectLockEnabled: Enabled
        Rule:
          DefaultRetention:
            Mode: GOVERNANCE
            Days: 3650
      PublicAccessBlockConfiguration:
        BlockPublicAcls: true
        BlockPublicPolicy: true
        IgnorePublicAcls: true
        RestrictPublicBuckets: true

  # -----------------------------
  # Queues
  # -----------------------------
  TranscriptQueue:
    Type: AWS::SQS::Queue
    Properties:
      VisibilityTimeout: 60

  ActionQueue:
    Type: AWS::SQS::Queue
    Properties:
      VisibilityTimeout: 60

  RecognitionQueue:
    Type: AWS::SQS::Queue
    Properties:
      VisibilityTimeout: 60

  # -----------------------------
  # WebSocket connection registry
  # -----------------------------
  WsConnectionsTable:
    Type: AWS::DynamoDB::Table
    Properties:
      BillingMode: PAY_PER_REQUEST
      AttributeDefinitions:
        - AttributeName: connection_id
          AttributeType: S
        - AttributeName: device_id
          AttributeType: S
      KeySchema:
        - AttributeName: connection_id
          KeyType: HASH
      GlobalSecondaryIndexes:
        - IndexName: device_id_index
          KeySchema:
            - AttributeName: device_id
              KeyType: HASH
          Projection:
            ProjectionType: ALL
      TimeToLiveSpecification:
        AttributeName: ttl
        Enabled: true

  WsSubscriptionsTable:
    Type: AWS::DynamoDB::Table
    Properties:
      BillingMode: PAY_PER_REQUEST
      AttributeDefinitions:
        - AttributeName: topic_key
          AttributeType: S
        - AttributeName: connection_id
          AttributeType: S
      KeySchema:
        - AttributeName: topic_key
          KeyType: HASH
        - AttributeName: connection_id
          KeyType: RANGE
      GlobalSecondaryIndexes:
        - IndexName: connection_id_index
          KeySchema:
            - AttributeName: connection_id
              KeyType: HASH
            - AttributeName: topic_key
              KeyType: RANGE
          Projection:
            ProjectionType: KEYS_ONLY
      TimeToLiveSpecification:
        AttributeName: ttl
        Enabled: true

  # -----------------------------
  # Lambda layer
  # -----------------------------
  SharedLayer:
    Type: AWS::Serverless::LayerVersion
    Properties:
      LayerName: !Sub ${AWS::StackName}-shared
      ContentUri: layers/shared/
      CompatibleRuntimes:
        - python3.11

  # -----------------------------
  # REST API (Hub)
  # -----------------------------
  HubApi:
    Type: AWS::ApiGateway::RestApi
    Properties:
      Name: !Sub ${AWS::StackName}-hub-api
      EndpointConfiguration:
        Types:
          - REGIONAL

  HubApiFunction:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: functions/hub_api/
      Handler: lambda_handler.handler
      Layers:
        - !Ref SharedLayer
      Environment:
        Variables:
          DB_RESOURCE_ARN: !GetAtt AuroraCluster.DBClusterArn
          DB_SECRET_ARN: !Ref DbCredentialsSecret
          DB_NAME: !Ref DbName
          TRANSCRIPT_QUEUE_URL: !Ref TranscriptQueue
          ACTION_QUEUE_URL: !Ref ActionQueue
          RECOGNITION_QUEUE_URL: !Ref RecognitionQueue
          AUDIT_BUCKET: !Ref AuditBucket
          ARTIFACT_BUCKET: !Ref ArtifactBucket
          ADMIN_SECRET_ARN: !Ref AdminApiKeySecret
          OPENAI_SECRET_ARN: !Ref OpenAISecret
          LIVEKIT_URL: !Ref LiveKitUrl
          LIVEKIT_SECRET_ARN: !Ref LiveKitSecret
          # Cognito settings
          COGNITO_REGION: !Ref AWS::Region
          COGNITO_USER_POOL_ID: !Ref CognitoUserPool
          COGNITO_APP_CLIENT_ID: !If [GoogleAuthEnabled, !Ref CognitoUserPoolClientGoogle, !Ref CognitoUserPoolClientNative]
          COGNITO_DOMAIN: !If
            - HasCognitoDomainPrefix
            - !Sub ${CognitoDomainPrefix}.auth.${AWS::Region}.amazoncognito.com
            - !Sub marvain-${StageName}-${AWS::AccountId}.auth.${AWS::Region}.amazoncognito.com
          COGNITO_REDIRECT_URI: !Sub https://${HubApi}.execute-api.${AWS::Region}.amazonaws.com/${StageName}/auth/callback
          COGNITO_IDENTITY_PROVIDER: !If [GoogleAuthEnabled, "Google", ""]
          SESSION_SECRET_ARN: !Ref SessionSecret
          STACK_NAME: !Ref AWS::StackName
          WS_TABLE: !Ref WsConnectionsTable
          WS_SUBSCRIPTIONS_TABLE: !Ref WsSubscriptionsTable
          WS_API_ENDPOINT: !Sub https://${WsApi}.execute-api.${AWS::Region}.amazonaws.com/${StageName}
          AUTO_APPROVE_POLICY_MODE: "enforce"
          MARVAIN_METRICS_NAMESPACE: "Marvain"
          MAX_SPACES_PER_AGENT: !Ref MaxSpacesPerAgent
      Policies:
        - AWSLambdaBasicExecutionRole
        - DynamoDBCrudPolicy:
            TableName: !Ref WsConnectionsTable
        - DynamoDBCrudPolicy:
            TableName: !Ref WsSubscriptionsTable
        - Statement:
            - Effect: Allow
              Action:
                - rds-data:ExecuteStatement
                - rds-data:BatchExecuteStatement
                - rds-data:BeginTransaction
                - rds-data:CommitTransaction
                - rds-data:RollbackTransaction
              Resource: "*"
            - Effect: Allow
              Action:
                - secretsmanager:GetSecretValue
              Resource:
                - !Ref DbCredentialsSecret
                - !Ref AdminApiKeySecret
                - !Ref OpenAISecret
                - !Ref LiveKitSecret
                - !Ref SessionSecret
            - Effect: Allow
              Action:
                - sqs:SendMessage
                - sqs:GetQueueAttributes
              Resource:
                - !GetAtt TranscriptQueue.Arn
                - !GetAtt ActionQueue.Arn
                - !GetAtt RecognitionQueue.Arn
            - Effect: Allow
              Action:
                - logs:FilterLogEvents
                - logs:DescribeLogStreams
              Resource:
                - !Sub arn:aws:logs:${AWS::Region}:${AWS::AccountId}:log-group:/aws/lambda/${AWS::StackName}-ToolRunnerFunction*
            - Effect: Allow
              Action:
                - s3:PutObject
                - s3:GetObject
              Resource:
                - !Sub ${AuditBucket.Arn}/*
                - !Sub ${ArtifactBucket.Arn}/*
            - Effect: Allow
              Action:
                - execute-api:ManageConnections
              Resource: "*"

  # Explicit API Gateway integration (replaces Events section to avoid circular dependency)
  HubApiPermission:
    Type: AWS::Lambda::Permission
    Properties:
      FunctionName: !Ref HubApiFunction
      Action: lambda:InvokeFunction
      Principal: apigateway.amazonaws.com
      SourceArn: !Sub arn:aws:execute-api:${AWS::Region}:${AWS::AccountId}:${HubApi}/*/*

  HubApiResource:
    Type: AWS::ApiGateway::Resource
    Properties:
      RestApiId: !Ref HubApi
      ParentId: !GetAtt HubApi.RootResourceId
      PathPart: "{proxy+}"

  HubApiMethod:
    Type: AWS::ApiGateway::Method
    Properties:
      RestApiId: !Ref HubApi
      ResourceId: !Ref HubApiResource
      HttpMethod: ANY
      AuthorizationType: NONE
      Integration:
        Type: AWS_PROXY
        IntegrationHttpMethod: POST
        Uri: !Sub arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${HubApiFunction.Arn}/invocations

  # Add CORS support at the resource level
  HubApiCorsMethod:
    Type: AWS::ApiGateway::Method
    Properties:
      RestApiId: !Ref HubApi
      ResourceId: !Ref HubApiResource
      HttpMethod: OPTIONS
      AuthorizationType: NONE
      Integration:
        Type: MOCK
        IntegrationResponses:
          - StatusCode: 200
            ResponseParameters:
              method.response.header.Access-Control-Allow-Headers: "'Content-Type,Authorization,X-Admin-Key'"
              method.response.header.Access-Control-Allow-Methods: "'GET,POST,PUT,PATCH,DELETE,OPTIONS'"
              method.response.header.Access-Control-Allow-Origin: "'*'"
        RequestTemplates:
          application/json: '{"statusCode": 200}'
      MethodResponses:
        - StatusCode: 200
          ResponseParameters:
            method.response.header.Access-Control-Allow-Headers: true
            method.response.header.Access-Control-Allow-Methods: true
            method.response.header.Access-Control-Allow-Origin: true

  # Root resource method for /
  HubApiRootMethod:
    Type: AWS::ApiGateway::Method
    Properties:
      RestApiId: !Ref HubApi
      ResourceId: !GetAtt HubApi.RootResourceId
      HttpMethod: ANY
      AuthorizationType: NONE
      Integration:
        Type: AWS_PROXY
        IntegrationHttpMethod: POST
        Uri: !Sub arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${HubApiFunction.Arn}/invocations

  # Root resource CORS method
  HubApiRootCorsMethod:
    Type: AWS::ApiGateway::Method
    Properties:
      RestApiId: !Ref HubApi
      ResourceId: !GetAtt HubApi.RootResourceId
      HttpMethod: OPTIONS
      AuthorizationType: NONE
      Integration:
        Type: MOCK
        IntegrationResponses:
          - StatusCode: 200
            ResponseParameters:
              method.response.header.Access-Control-Allow-Headers: "'Content-Type,Authorization,X-Admin-Key'"
              method.response.header.Access-Control-Allow-Methods: "'GET,POST,PUT,PATCH,DELETE,OPTIONS'"
              method.response.header.Access-Control-Allow-Origin: "'*'"
        RequestTemplates:
          application/json: '{"statusCode": 200}'
      MethodResponses:
        - StatusCode: 200
          ResponseParameters:
            method.response.header.Access-Control-Allow-Headers: true
            method.response.header.Access-Control-Allow-Methods: true
            method.response.header.Access-Control-Allow-Origin: true

  HubApiDeploymentV1:
    Type: AWS::ApiGateway::Deployment
    Condition: IsDeploymentV1
    DependsOn:
      - HubApiMethod
      - HubApiCorsMethod
      - HubApiRootMethod
      - HubApiRootCorsMethod
    Properties:
      RestApiId: !Ref HubApi
      Description: "Deployment v1"

  HubApiDeploymentV2:
    Type: AWS::ApiGateway::Deployment
    Condition: IsDeploymentV2
    DependsOn:
      - HubApiMethod
      - HubApiCorsMethod
      - HubApiRootMethod
      - HubApiRootCorsMethod
    Properties:
      RestApiId: !Ref HubApi
      Description: "Deployment v2"

  HubApiStage:
    Type: AWS::ApiGateway::Stage
    Properties:
      RestApiId: !Ref HubApi
      DeploymentId: !If [IsDeploymentV2, !Ref HubApiDeploymentV2, !Ref HubApiDeploymentV1]
      StageName: !Ref StageName
      MethodSettings:
        - HttpMethod: "*"
          ResourcePath: "/*"
          ThrottlingBurstLimit: 50
          ThrottlingRateLimit: 100

  # -----------------------------
  # Planner (deliberative loop)
  # -----------------------------
  PlannerFunction:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: functions/planner/
      Handler: handler.handler
      Timeout: 60
      MemorySize: 1024
      Layers:
        - !Ref SharedLayer
      Environment:
        Variables:
          DB_RESOURCE_ARN: !GetAtt AuroraCluster.DBClusterArn
          DB_SECRET_ARN: !Ref DbCredentialsSecret
          DB_NAME: !Ref DbName
          ACTION_QUEUE_URL: !Ref ActionQueue
          AUDIT_BUCKET: !Ref AuditBucket
          OPENAI_SECRET_ARN: !Ref OpenAISecret
          PLANNER_MODEL: !Ref PlannerModel
          WS_TABLE: !Ref WsConnectionsTable
          WS_SUBSCRIPTIONS_TABLE: !Ref WsSubscriptionsTable
          WS_API_ENDPOINT: !Sub https://${WsApi}.execute-api.${AWS::Region}.amazonaws.com/${StageName}
          AUTO_APPROVE_POLICY_MODE: "enforce"
          MARVAIN_METRICS_NAMESPACE: "Marvain"
      Policies:
        - AWSLambdaBasicExecutionRole
        - DynamoDBCrudPolicy:
            TableName: !Ref WsConnectionsTable
        - DynamoDBCrudPolicy:
            TableName: !Ref WsSubscriptionsTable
        - Statement:
            - Effect: Allow
              Action:
                - rds-data:ExecuteStatement
                - rds-data:BatchExecuteStatement
                - rds-data:BeginTransaction
                - rds-data:CommitTransaction
                - rds-data:RollbackTransaction
              Resource: "*"
            - Effect: Allow
              Action:
                - secretsmanager:GetSecretValue
              Resource:
                - !Ref DbCredentialsSecret
                - !Ref OpenAISecret
            - Effect: Allow
              Action:
                - sqs:SendMessage
              Resource:
                - !GetAtt ActionQueue.Arn
            - Effect: Allow
              Action:
                - s3:PutObject
              Resource:
                - !Sub ${AuditBucket.Arn}/*
            - Effect: Allow
              Action:
                - execute-api:ManageConnections
              Resource: "*"
      Events:
        TranscriptQueueEvent:
          Type: SQS
          Properties:
            Queue: !GetAtt TranscriptQueue.Arn
            BatchSize: 5

  # -----------------------------
  # Tool Runner (execution plane)
  # -----------------------------
  ToolRunnerFunction:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: functions/tool_runner/
      Handler: handler.handler
      Timeout: 60
      MemorySize: 512
      Layers:
        - !Ref SharedLayer
      Environment:
        Variables:
          DB_RESOURCE_ARN: !GetAtt AuroraCluster.DBClusterArn
          DB_SECRET_ARN: !Ref DbCredentialsSecret
          DB_NAME: !Ref DbName
          AUDIT_BUCKET: !Ref AuditBucket
          WS_TABLE: !Ref WsConnectionsTable
          WS_SUBSCRIPTIONS_TABLE: !Ref WsSubscriptionsTable
          WS_API_ENDPOINT: !Sub https://${WsApi}.execute-api.${AWS::Region}.amazonaws.com/${StageName}
          DEVICE_RESULT_TIMEOUT_SECONDS: "90"
          MARVAIN_METRICS_NAMESPACE: "Marvain"
      Policies:
        - AWSLambdaBasicExecutionRole
        - DynamoDBCrudPolicy:
            TableName: !Ref WsConnectionsTable
        - DynamoDBCrudPolicy:
            TableName: !Ref WsSubscriptionsTable
        - Statement:
            - Effect: Allow
              Action:
                - rds-data:ExecuteStatement
                - rds-data:BatchExecuteStatement
                - rds-data:BeginTransaction
                - rds-data:CommitTransaction
                - rds-data:RollbackTransaction
              Resource: "*"
            - Effect: Allow
              Action:
                - secretsmanager:GetSecretValue
              Resource:
                - !Ref DbCredentialsSecret
            - Effect: Allow
              Action:
                - s3:PutObject
              Resource:
                - !Sub ${AuditBucket.Arn}/*
            - Effect: Allow
              Action:
                - execute-api:ManageConnections
              Resource: "*"
      Events:
        ActionQueueEvent:
          Type: SQS
          Properties:
            Queue: !GetAtt ActionQueue.Arn
            BatchSize: 5

  ActionTimeoutSweeperFunction:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: functions/action_timeout_sweeper/
      Handler: handler.handler
      Timeout: 30
      MemorySize: 256
      Layers:
        - !Ref SharedLayer
      Environment:
        Variables:
          DB_RESOURCE_ARN: !GetAtt AuroraCluster.DBClusterArn
          DB_SECRET_ARN: !Ref DbCredentialsSecret
          DB_NAME: !Ref DbName
          WS_TABLE: !Ref WsConnectionsTable
          WS_SUBSCRIPTIONS_TABLE: !Ref WsSubscriptionsTable
          WS_API_ENDPOINT: !Sub https://${WsApi}.execute-api.${AWS::Region}.amazonaws.com/${StageName}
          ACTION_TIMEOUT_SWEEPER_BATCH_SIZE: "200"
          MARVAIN_METRICS_NAMESPACE: "Marvain"
      Policies:
        - AWSLambdaBasicExecutionRole
        - DynamoDBCrudPolicy:
            TableName: !Ref WsConnectionsTable
        - DynamoDBCrudPolicy:
            TableName: !Ref WsSubscriptionsTable
        - Statement:
            - Effect: Allow
              Action:
                - rds-data:ExecuteStatement
                - rds-data:BatchExecuteStatement
              Resource: "*"
            - Effect: Allow
              Action:
                - secretsmanager:GetSecretValue
              Resource:
                - !Ref DbCredentialsSecret
            - Effect: Allow
              Action:
                - execute-api:ManageConnections
              Resource: "*"
      Events:
        SweepSchedule:
          Type: Schedule
          Properties:
            Schedule: rate(1 minute)

  # -----------------------------
  # WebSocket API (sideband control channel)
  # -----------------------------
  WsApi:
    Type: AWS::ApiGatewayV2::Api
    Properties:
      Name: !Sub ${AWS::StackName}-ws
      ProtocolType: WEBSOCKET
      RouteSelectionExpression: "$request.body.action"

  WsConnectFunction:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: functions/ws_connect/
      Handler: handler.handler
      Layers:
        - !Ref SharedLayer
      Environment:
        Variables:
          WS_TABLE: !Ref WsConnectionsTable
          WS_SUBSCRIPTIONS_TABLE: !Ref WsSubscriptionsTable
      Policies:
        - AWSLambdaBasicExecutionRole
        - DynamoDBCrudPolicy:
            TableName: !Ref WsConnectionsTable
        - DynamoDBCrudPolicy:
            TableName: !Ref WsSubscriptionsTable

  WsDisconnectFunction:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: functions/ws_disconnect/
      Handler: handler.handler
      Layers:
        - !Ref SharedLayer
      Environment:
        Variables:
          WS_TABLE: !Ref WsConnectionsTable
          WS_SUBSCRIPTIONS_TABLE: !Ref WsSubscriptionsTable
      Policies:
        - AWSLambdaBasicExecutionRole
        - DynamoDBCrudPolicy:
            TableName: !Ref WsConnectionsTable
        - DynamoDBCrudPolicy:
            TableName: !Ref WsSubscriptionsTable

  WsMessageFunction:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: functions/ws_message/
      Handler: handler.handler
      Layers:
        - !Ref SharedLayer
      Environment:
        Variables:
          WS_TABLE: !Ref WsConnectionsTable
          WS_SUBSCRIPTIONS_TABLE: !Ref WsSubscriptionsTable
          WS_AUTH_TTL_SECONDS: "3600"
          DB_RESOURCE_ARN: !GetAtt AuroraCluster.DBClusterArn
          DB_SECRET_ARN: !Ref DbCredentialsSecret
          DB_NAME: !Ref DbName
          MARVAIN_METRICS_NAMESPACE: "Marvain"
      Policies:
        - AWSLambdaBasicExecutionRole
        - DynamoDBCrudPolicy:
            TableName: !Ref WsConnectionsTable
        - DynamoDBCrudPolicy:
            TableName: !Ref WsSubscriptionsTable
        - Statement:
            - Effect: Allow
              Action:
                - rds-data:ExecuteStatement
              Resource: "*"
            - Effect: Allow
              Action:
                - secretsmanager:GetSecretValue
              Resource:
                - !Ref DbCredentialsSecret
            - Effect: Allow
              Action:
                - execute-api:ManageConnections
              Resource: "*"
            - Effect: Allow
              Action:
                - cognito-idp:GetUser
              Resource: !GetAtt CognitoUserPool.Arn

  WsConnectIntegration:
    Type: AWS::ApiGatewayV2::Integration
    Properties:
      ApiId: !Ref WsApi
      IntegrationType: AWS_PROXY
      IntegrationUri: !Sub arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${WsConnectFunction.Arn}/invocations

  WsDisconnectIntegration:
    Type: AWS::ApiGatewayV2::Integration
    Properties:
      ApiId: !Ref WsApi
      IntegrationType: AWS_PROXY
      IntegrationUri: !Sub arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${WsDisconnectFunction.Arn}/invocations

  WsMessageIntegration:
    Type: AWS::ApiGatewayV2::Integration
    Properties:
      ApiId: !Ref WsApi
      IntegrationType: AWS_PROXY
      IntegrationUri: !Sub arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${WsMessageFunction.Arn}/invocations

  WsConnectRoute:
    Type: AWS::ApiGatewayV2::Route
    Properties:
      ApiId: !Ref WsApi
      RouteKey: $connect
      AuthorizationType: NONE
      Target: !Join [ '/', [ 'integrations', !Ref WsConnectIntegration ] ]

  WsDisconnectRoute:
    Type: AWS::ApiGatewayV2::Route
    Properties:
      ApiId: !Ref WsApi
      RouteKey: $disconnect
      AuthorizationType: NONE
      Target: !Join [ '/', [ 'integrations', !Ref WsDisconnectIntegration ] ]

  WsDefaultRoute:
    Type: AWS::ApiGatewayV2::Route
    Properties:
      ApiId: !Ref WsApi
      RouteKey: $default
      AuthorizationType: NONE
      Target: !Join [ '/', [ 'integrations', !Ref WsMessageIntegration ] ]

  WsDeployment:
    Type: AWS::ApiGatewayV2::Deployment
    DependsOn:
      - WsConnectRoute
      - WsDisconnectRoute
      - WsDefaultRoute
    Properties:
      ApiId: !Ref WsApi

  WsStage:
    Type: AWS::ApiGatewayV2::Stage
    Properties:
      ApiId: !Ref WsApi
      StageName: !Ref StageName
      DeploymentId: !Ref WsDeployment

  WsConnectPermission:
    Type: AWS::Lambda::Permission
    Properties:
      Action: lambda:InvokeFunction
      FunctionName: !Ref WsConnectFunction
      Principal: apigateway.amazonaws.com
      SourceArn: !Sub arn:aws:execute-api:${AWS::Region}:${AWS::AccountId}:${WsApi}/*/$connect

  WsDisconnectPermission:
    Type: AWS::Lambda::Permission
    Properties:
      Action: lambda:InvokeFunction
      FunctionName: !Ref WsDisconnectFunction
      Principal: apigateway.amazonaws.com
      SourceArn: !Sub arn:aws:execute-api:${AWS::Region}:${AWS::AccountId}:${WsApi}/*/$disconnect

  WsDefaultPermission:
    Type: AWS::Lambda::Permission
    Properties:
      Action: lambda:InvokeFunction
      FunctionName: !Ref WsMessageFunction
      Principal: apigateway.amazonaws.com
      SourceArn: !Sub arn:aws:execute-api:${AWS::Region}:${AWS::AccountId}:${WsApi}/*/$default

  # -----------------------------
  # Cognito User Pool for Authentication
  # -----------------------------
  CognitoUserPool:
    Type: AWS::Cognito::UserPool
    Properties:
      UserPoolName: !Sub ${AWS::StackName}-users
      AutoVerifiedAttributes:
        - email
      # IMPORTANT: UsernameAttributes is immutable. Must match existing pool exactly.
      UsernameAttributes:
        - email
      UsernameConfiguration:
        CaseSensitive: false
      AdminCreateUserConfig:
        AllowAdminCreateUserOnly: true
      AccountRecoverySetting:
        RecoveryMechanisms:
          - Name: verified_email
            Priority: 1
      Policies:
        PasswordPolicy:
          MinimumLength: 8
          RequireLowercase: true
          RequireNumbers: true
          RequireSymbols: false
          RequireUppercase: true
      # NOTE: Do not specify Schema - it's immutable and the existing pool has the default schema

  CognitoGoogleIdentityProvider:
    Type: AWS::Cognito::UserPoolIdentityProvider
    Condition: GoogleAuthEnabled
    Properties:
      ProviderName: Google
      ProviderType: Google
      UserPoolId: !Ref CognitoUserPool
      ProviderDetails:
        client_id: !Sub '{{resolve:secretsmanager:${GoogleOAuthSecret}:SecretString:client_id}}'
        client_secret: !Sub '{{resolve:secretsmanager:${GoogleOAuthSecret}:SecretString:client_secret}}'
        authorize_scopes: "openid email profile"
      AttributeMapping:
        email: email
        name: name
        username: sub
        given_name: given_name
        family_name: family_name
        picture: picture

  CognitoUserPoolClientNative:
    Type: AWS::Cognito::UserPoolClient
    Condition: GoogleAuthDisabled
    Properties:
      ClientName: !Sub ${AWS::StackName}-app
      UserPoolId: !Ref CognitoUserPool
      GenerateSecret: false
      AllowedOAuthFlows:
        - code
      AllowedOAuthFlowsUserPoolClient: true
      AllowedOAuthScopes:
        - openid
        - email
        - profile
        - aws.cognito.signin.user.admin
      CallbackURLs: !Ref GuiCallbackUrls
      LogoutURLs: !Ref GuiLogoutUrls
      SupportedIdentityProviders:
        - COGNITO
      ExplicitAuthFlows:
        - ALLOW_USER_PASSWORD_AUTH
        - ALLOW_USER_SRP_AUTH
        - ALLOW_REFRESH_TOKEN_AUTH

  CognitoUserPoolClientGoogle:
    Type: AWS::Cognito::UserPoolClient
    Condition: GoogleAuthEnabled
    DependsOn:
      - CognitoGoogleIdentityProvider
    Properties:
      ClientName: !Sub ${AWS::StackName}-app
      UserPoolId: !Ref CognitoUserPool
      GenerateSecret: false
      AllowedOAuthFlows:
        - code
      AllowedOAuthFlowsUserPoolClient: true
      AllowedOAuthScopes:
        - openid
        - email
        - profile
        - aws.cognito.signin.user.admin
      CallbackURLs: !Ref GuiCallbackUrls
      LogoutURLs: !Ref GuiLogoutUrls
      SupportedIdentityProviders:
        - COGNITO
        - Google
      ExplicitAuthFlows:
        - ALLOW_USER_PASSWORD_AUTH
        - ALLOW_USER_SRP_AUTH
        - ALLOW_REFRESH_TOKEN_AUTH

  CognitoUserPoolDomain:
    Type: AWS::Cognito::UserPoolDomain
    Properties:
      Domain: !If [HasCognitoDomainPrefix, !Ref CognitoDomainPrefix, !Sub "marvain-${StageName}-${AWS::AccountId}"]
      UserPoolId: !Ref CognitoUserPool

  # Session secret for SessionMiddleware
  SessionSecret:
    Type: AWS::SecretsManager::Secret
    Properties:
      Name: !Sub ${AWS::StackName}/session-secret
      Description: Secret key for session middleware
      GenerateSecretString:
        SecretStringTemplate: '{}'
        GenerateStringKey: session_secret_key
        PasswordLength: 64
        ExcludeCharacters: '"@/\'

  MarvainObservabilityDashboard:
    Type: AWS::CloudWatch::Dashboard
    Properties:
      DashboardName: !Sub ${AWS::StackName}-observability
      DashboardBody: !Sub |
        {
          "widgets": [
            {
              "type": "metric",
              "x": 0,
              "y": 0,
              "width": 12,
              "height": 6,
              "properties": {
                "title": "Broadcast Delivery",
                "metrics": [
                  ["Marvain", "BroadcastDelivered"],
                  [".", "BroadcastDropped"]
                ],
                "stat": "Sum",
                "period": 300,
                "region": "${AWS::Region}"
              }
            },
            {
              "type": "metric",
              "x": 12,
              "y": 0,
              "width": 12,
              "height": 6,
              "properties": {
                "title": "Device Timeouts",
                "metrics": [
                  ["Marvain", "DeviceTimeout"]
                ],
                "stat": "Sum",
                "period": 300,
                "region": "${AWS::Region}"
              }
            }
          ]
        }

  BroadcastDroppedAlarm:
    Type: AWS::CloudWatch::Alarm
    Properties:
      AlarmName: !Sub ${AWS::StackName}-broadcast-dropped
      Namespace: Marvain
      MetricName: BroadcastDropped
      Statistic: Sum
      Period: 300
      EvaluationPeriods: 1
      Threshold: 10
      ComparisonOperator: GreaterThanThreshold
      TreatMissingData: notBreaching

  DeviceTimeoutAlarm:
    Type: AWS::CloudWatch::Alarm
    Properties:
      AlarmName: !Sub ${AWS::StackName}-device-timeout
      Namespace: Marvain
      MetricName: DeviceTimeout
      Statistic: Sum
      Period: 300
      EvaluationPeriods: 1
      Threshold: 5
      ComparisonOperator: GreaterThanThreshold
      TreatMissingData: notBreaching

Outputs:
  HubRestApiBase:
    Description: Base URL for Hub REST API
    Value: !Sub https://${HubApi}.execute-api.${AWS::Region}.amazonaws.com/${StageName}
  HubWebSocketUrl:
    Description: WebSocket URL for sideband control channel
    Value: !Sub wss://${WsApi}.execute-api.${AWS::Region}.amazonaws.com/${StageName}
  WsConnectionsTableName:
    Description: DynamoDB table name for WebSocket connections
    Value: !Ref WsConnectionsTable
  WsSubscriptionsTableName:
    Description: DynamoDB table name for topic subscription index
    Value: !Ref WsSubscriptionsTable
  AdminApiKeySecretArn:
    Description: Secrets Manager ARN containing admin API key
    Value: !Ref AdminApiKeySecret
  OpenAISecretArn:
    Description: Secrets Manager ARN containing OpenAI API key placeholder
    Value: !Ref OpenAISecret
  LiveKitSecretArn:
    Description: Secrets Manager ARN containing LiveKit API key/secret placeholder
    Value: !Ref LiveKitSecret
  LiveKitUrl:
    Description: LiveKit server URL for media connections
    Value: !Ref LiveKitUrl
  DbClusterArn:
    Description: Aurora cluster ARN (Data API resourceArn)
    Value: !GetAtt AuroraCluster.DBClusterArn
  DbSecretArn:
    Description: Aurora credentials secret ARN (Data API secretArn)
    Value: !Ref DbCredentialsSecret
  DbName:
    Description: Database name
    Value: !Ref DbName
  ArtifactBucketName:
    Description: Bucket for artifacts
    Value: !Ref ArtifactBucket
  RecognitionQueueUrl:
    Description: SQS queue URL for recognition events (voice.sample / face.snapshot)
    Value: !Ref RecognitionQueue
  AuditBucketName:
    Description: Bucket for tamper-evident audit log (Object Lock)
    Value: !Ref AuditBucket
  CognitoUserPoolId:
    Description: Cognito User Pool ID
    Value: !Ref CognitoUserPool
  CognitoAppClientId:
    Description: Cognito App Client ID
    Value: !If [GoogleAuthEnabled, !Ref CognitoUserPoolClientGoogle, !Ref CognitoUserPoolClientNative]
  CognitoIdentityProvider:
    Description: Optional forced identity provider for Hosted UI authorization (e.g. Google)
    Value: !If [GoogleAuthEnabled, "Google", ""]
  CognitoDomain:
    Description: Cognito Hosted UI domain
    Value: !If
      - HasCognitoDomainPrefix
      - !Sub ${CognitoDomainPrefix}.auth.${AWS::Region}.amazoncognito.com
      - !Sub marvain-${StageName}-${AWS::AccountId}.auth.${AWS::Region}.amazoncognito.com
  CognitoIdpResponseUrl:
    Description: Cognito redirect URL to configure in the external IdP (Google) OAuth client
    Value: !If
      - HasCognitoDomainPrefix
      - !Sub https://${CognitoDomainPrefix}.auth.${AWS::Region}.amazoncognito.com/oauth2/idpresponse
      - !Sub https://marvain-${StageName}-${AWS::AccountId}.auth.${AWS::Region}.amazoncognito.com/oauth2/idpresponse
  CognitoLoginUrl:
    Description: Cognito Hosted UI login URL (uses the first GUI callback URL)
    Value: !If
      - HasCognitoDomainPrefix
      - !Sub
          - https://${CognitoDomainPrefix}.auth.${AWS::Region}.amazoncognito.com/login?client_id=${ClientId}&response_type=code&scope=openid+email+profile&redirect_uri=${RedirectUri}
          - RedirectUri: !Select [0, !Ref GuiCallbackUrls]
            ClientId: !If [GoogleAuthEnabled, !Ref CognitoUserPoolClientGoogle, !Ref CognitoUserPoolClientNative]
      - !Sub
          - https://marvain-${StageName}-${AWS::AccountId}.auth.${AWS::Region}.amazoncognito.com/login?client_id=${ClientId}&response_type=code&scope=openid+email+profile&redirect_uri=${RedirectUri}
          - RedirectUri: !Select [0, !Ref GuiCallbackUrls]
            ClientId: !If [GoogleAuthEnabled, !Ref CognitoUserPoolClientGoogle, !Ref CognitoUserPoolClientNative]
  SessionSecretArn:
    Description: Secrets Manager ARN containing session secret key
    Value: !Ref SessionSecret
  GoogleOAuthSecretArn:
    Description: Secrets Manager ARN containing Google OAuth client_id/client_secret JSON
    Value: !Ref GoogleOAuthSecret