template.yaml

AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: FAQ assistant worker Lambda - HTTP endpoint with shared-secret auth.

Parameters:
  OpenAIApiKey:
    Type: String
    NoEcho: true
    Description: OpenAI API key, exposed to the function as OPENAI_API_KEY.
  SharedSecret:
    Type: String
    NoEcho: true
    Default: ""
    Description: >-
      Shared secret callers send in the x-faq-assistant-secret header.
      Empty leaves the endpoint open (not recommended).
  OpikApiKey:
    Type: String
    NoEcho: true
    Default: ""
    Description: Opik Cloud API key for trace export, exposed as OPIK_API_KEY. Empty keeps tracing inert.
  GitHubRepo:
    Type: String
    Default: "DataTalksClub/faq-assistant"
    Description: owner/repo allowed to assume the deploy role via GitHub OIDC.

Globals:
  Function:
    Timeout: 30
    MemorySize: 256
    Architectures:
      - arm64

Resources:
  FaqWorkerFunction:
    Type: AWS::Serverless::Function
    Metadata:
      BuildMethod: makefile
    Properties:
      FunctionName: faq-assistant
      CodeUri: .
      Handler: faq_assistant.handler.lambda_handler
      Runtime: python3.14
      Environment:
        Variables:
          OPENAI_API_KEY: !Ref OpenAIApiKey
          FAQ_ASSISTANT_SHARED_SECRET: !Ref SharedSecret
          SEARCH_INDEX_PATH: search-index.zsx
          OPIK_ENABLED: "true"
          OPIK_URL_OVERRIDE: https://www.comet.com/opik/api
          OPIK_WORKSPACE: default
          OPIK_PROJECT_NAME: faq-assistant-lambda
          OPIK_API_KEY: !Ref OpikApiKey
      FunctionUrlConfig:
        AuthType: NONE

  # Role GitHub Actions assumes (via OIDC) to deploy this stack. Bootstrap: the
  # first deploy is done with other credentials; afterwards CI uses this role.
  # The OIDC provider (token.actions.githubusercontent.com) must already exist.
  GitHubDeployRole:
    Type: AWS::IAM::Role
    Properties:
      AssumeRolePolicyDocument:
        Version: "2012-10-17"
        Statement:
          - Effect: Allow
            Principal:
              Federated: !Sub "arn:aws:iam::${AWS::AccountId}:oidc-provider/token.actions.githubusercontent.com"
            Action: sts:AssumeRoleWithWebIdentity
            Condition:
              StringEquals:
                "token.actions.githubusercontent.com:aud": "sts.amazonaws.com"
              StringLike:
                "token.actions.githubusercontent.com:sub": !Sub "repo:${GitHubRepo}:*"
      # Least privilege: exactly what `sam deploy` of this stack needs. No
      # AdministratorAccess - this role is identical in dev and production.
      Policies:
        - PolicyName: faq-assistant-sam-deploy
          PolicyDocument:
            Version: "2012-10-17"
            Statement:
              - Sid: CloudFormationStack
                Effect: Allow
                Action:
                  - cloudformation:CreateStack
                  - cloudformation:UpdateStack
                  - cloudformation:DeleteStack
                  - cloudformation:DescribeStacks
                  - cloudformation:DescribeStackEvents
                  - cloudformation:DescribeStackResource
                  - cloudformation:DescribeStackResources
                  - cloudformation:GetTemplate
                  - cloudformation:ListStackResources
                  - cloudformation:CreateChangeSet
                  - cloudformation:DescribeChangeSet
                  - cloudformation:ExecuteChangeSet
                  - cloudformation:DeleteChangeSet
                Resource:
                  - !Sub "arn:aws:cloudformation:${AWS::Region}:${AWS::AccountId}:stack/faq-assistant/*"
                  # SAM's --resolve-s3 manages this stack to provision the deploy bucket.
                  - !Sub "arn:aws:cloudformation:${AWS::Region}:${AWS::AccountId}:stack/aws-sam-cli-managed-default/*"
              - Sid: CloudFormationServerlessTransform
                Effect: Allow
                Action: cloudformation:CreateChangeSet
                Resource: !Sub "arn:aws:cloudformation:${AWS::Region}:aws:transform/Serverless-2016-10-31"
              - Sid: CloudFormationTemplateInspection
                Effect: Allow
                Action:
                  - cloudformation:GetTemplateSummary
                  - cloudformation:ValidateTemplate
                Resource: "*"
              - Sid: SamDeployBucket
                Effect: Allow
                Action:
                  - s3:CreateBucket
                  - s3:GetBucketPolicy
                  - s3:PutBucketPolicy
                  - s3:PutBucketTagging
                  - s3:PutBucketVersioning
                  - s3:PutBucketPublicAccessBlock
                  - s3:PutEncryptionConfiguration
                  - s3:GetObject
                  - s3:PutObject
                  - s3:GetBucketLocation
                  - s3:ListBucket
                Resource:
                  - arn:aws:s3:::aws-sam-cli-managed-default-*
                  - arn:aws:s3:::aws-sam-cli-managed-default-*/*
              - Sid: LambdaFunction
                Effect: Allow
                Action:
                  - lambda:CreateFunction
                  - lambda:DeleteFunction
                  - lambda:GetFunction
                  - lambda:GetFunctionConfiguration
                  - lambda:UpdateFunctionCode
                  - lambda:UpdateFunctionConfiguration
                  - lambda:ListVersionsByFunction
                  - lambda:PublishVersion
                  - lambda:TagResource
                  - lambda:UntagResource
                  - lambda:ListTags
                  - lambda:AddPermission
                  - lambda:RemovePermission
                  - lambda:GetPolicy
                  - lambda:CreateFunctionUrlConfig
                  - lambda:UpdateFunctionUrlConfig
                  - lambda:GetFunctionUrlConfig
                  - lambda:DeleteFunctionUrlConfig
                Resource: !Sub "arn:aws:lambda:${AWS::Region}:${AWS::AccountId}:function:faq-assistant"
              - Sid: ManageStackRoles
                Effect: Allow
                Action:
                  - iam:CreateRole
                  - iam:DeleteRole
                  - iam:GetRole
                  - iam:TagRole
                  - iam:UntagRole
                  - iam:AttachRolePolicy
                  - iam:DetachRolePolicy
                  - iam:PutRolePolicy
                  - iam:DeleteRolePolicy
                  - iam:GetRolePolicy
                  - iam:ListRolePolicies
                  - iam:ListAttachedRolePolicies
                  - iam:UpdateAssumeRolePolicy
                Resource: !Sub "arn:aws:iam::${AWS::AccountId}:role/faq-assistant-*"
              - Sid: PassFunctionRoleToLambda
                Effect: Allow
                Action: iam:PassRole
                Resource: !Sub "arn:aws:iam::${AWS::AccountId}:role/faq-assistant-*"
                Condition:
                  StringEquals:
                    iam:PassedToService: lambda.amazonaws.com

Outputs:
  FunctionUrl:
    Description: Public HTTPS endpoint. Auth is the x-faq-assistant-secret header.
    Value: !GetAtt FaqWorkerFunctionUrl.FunctionUrl
  DeployRoleArn:
    Description: Set this as the AWS_DEPLOY_ROLE_ARN GitHub secret.
    Value: !GetAtt GitHubDeployRole.Arn