AWS

This path attaches an AWS WAF Web ACL to your CloudFront distribution, so only bots need a token. AWS WAF evaluates each request before your Lambda@Edge function runs. It lets bots you trust through, blocks other bots that don't carry a token, and sends everyone else a browser challenge that human visitors pass automatically. Your Lambda@Edge function then verifies any token that is present.

1. Create a distribution in front of your website.

   

   

   When you reach Enable security, keep AWS WAF security protections enabled. This creates a Web ACL for your distribution, which you'll add rules to in steps 5 and 6.

   

   

2. Create your Lambda@Edge function.

   

   Ensure it is created in the us-east-1 (N. Virginia) region. CloudFront's control plane runs there and replicates edge functions from it, regardless of which region your CloudFront distribution otherwise uses. Lambda@Edge functions are also subject to their own restrictions and quotas, which differ from a regular Lambda function. Leave ARM64 architecture off, since Lambda@Edge only supports x86_64. The function's execution role must also allow CloudFront to run it at the edge. You can keep the default role and update its trust policy after creating the function; see Lambda@Edge permissions.

3. Start from this path's example Lambda@Edge code, which verifies the kya token when a request includes one. AWS WAF, which you'll configure next, decides which requests must include one. The code depends on the aws-jwt-verify package, which the Lambda console editor doesn't include, so install it locally and upload the code and its node_modules folder together as a .zip file. Adapt the code to your needs, then publish a version of the function (Actions > Publish new version).

4. In the AWS WAF console, open the Web ACL that CloudFront created for your distribution in step 1. It's listed under Protection packs (web ACLs) with a name starting with CreatedByCloudFront.

   

5. Add the AWS WAF Bot Control managed rule group to the Web ACL. It labels each request by bot category, for example a verified search engine crawler or an unverified automated client. The demo uses the Targeted inspection level, and some of the labels the rules in step 6 match on only exist at that level.

   

   In the rule group, set the categories you trust to Allow. An Allow action lets the request through immediately and skips every rule after it, so these bots never need a token. The demo allows CategorySearchEngine and CategorySeo.

   

6. Add three custom rules, placed after the Bot Control rule group, since they match on the labels it adds.

   IsAutomatedUnverifiedRequest (Count) adds a single label to any request Bot Control flagged as an unverified bot or automated browser. Count doesn't block anything; it groups those requests so the next rule can target them.

   

   JSON: IsAutomatedUnverifiedRequest

   JSON

     {
       "Action": {
         "Count": {}
       },
       "Name": "IsAutomatedUnverifiedRequest",
       "Priority": 9,
       "RuleLabels": [
         {
           "Name": "IsAutomatedUnverifiedRequest"
         }
       ],
       "Statement": {
         "OrStatement": {
           "Statements": [
             {
               "LabelMatchStatement": {
                 "Key": "awswaf:managed:aws:bot-control:bot:unverified",
                 "Scope": "LABEL"
               }
             },
             {
               "LabelMatchStatement": {
                 "Key": "awswaf:managed:aws:bot-control:signal:non_browser_user_agent",
                 "Scope": "LABEL"
               }
             },
             {
               "LabelMatchStatement": {
                 "Key": "awswaf:managed:aws:bot-control:signal:automated_browser",
                 "Scope": "LABEL"
               }
             },
             {
               "LabelMatchStatement": {
                 "Key": "awswaf:managed:aws:bot-control:targeted:signal:automated_browser",
                 "Scope": "LABEL"
               }
             },
             {
               "LabelMatchStatement": {
                 "Key": "awswaf:managed:aws:bot-control:targeted:signal:browser_automation_extension",
                 "Scope": "LABEL"
               }
             }
           ]
         }
       },
       "VisibilityConfig": {
         "CloudWatchMetricsEnabled": true,
         "MetricName": "BotsRequireSkyfireToken",
         "SampledRequestsEnabled": true
       }
     }

   BlockIfAutomatedRequestWithNoSkyfireToken (Block) blocks requests with that label unless the token header holds a value shaped like a JWT. AWS WAF only checks the format here; your Lambda@Edge function verifies the token itself.

   

   JSON: BlockIfAutomatedRequestWithNoSkyfireToken

   JSON

     {
       "Action": {
         "Block": {
           "CustomResponse": {
             "CustomResponseBodyKey": "missing-KYA-token-error",
             "ResponseCode": 401
           }
         }
       },
       "Name": "BlockIfAutomatedRequestWithNoSkyfireToken",
       "Priority": 10,
       "Statement": {
         "AndStatement": {
           "Statements": [
             {
               "LabelMatchStatement": {
                 "Key": "IsAutomatedUnverifiedRequest",
                 "Scope": "LABEL"
               }
             },
             {
               "NotStatement": {
                 "Statement": {
                   "RegexMatchStatement": {
                     "FieldToMatch": {
                       "SingleHeader": {
                         "Name": "kyapay-token"
                       }
                     },
                     "RegexString": "^[A-Za-z0-9-_]+\\.[A-Za-z0-9-_]+\\.[A-Za-z0-9-_]*$",
                     "TextTransformations": [
                       {
                         "Priority": 0,
                         "Type": "NONE"
                       }
                     ]
                   }
                 }
               }
             }
           ]
         }
       },
       "VisibilityConfig": {
         "CloudWatchMetricsEnabled": true,
         "MetricName": "ChallengeIfUnverifieBotWithNoSkyfireToken",
         "SampledRequestsEnabled": true
       }
     }

   On this rule, enable a custom response so a blocked caller learns how to get a token. It returns 401, the recommended status for a missing token (see Handling Missing or Invalid Tokens).

   

   JSON: custom response body

   JSON

     {
       "CustomResponseBodies": {
         "missing-KYA-token-error": {
           "Content": "{\"message\":\"ERROR: Missing token in the `kyapay-token` header. Please create an account at https://app.skyfire.xyz and create a kya token - https://docs.skyfire.xyz/reference/create-token and include it in your request in the `kyapay-token` header.\"}",
           "ContentType": "APPLICATION_JSON"
         }
       }
     }

   CheckIfHumanTraffic (Challenge) challenges any remaining request that isn't a verified bot, isn't labeled automated, and has no token header. A browser completes the challenge automatically, so human visitors get through; automated clients typically can't.

   

   JSON: CheckIfHumanTraffic

   JSON

     {
       "Action": {
         "Challenge": {}
       },
       "Name": "CheckIfHumanTraffic",
       "Priority": 12,
       "Statement": {
         "AndStatement": {
           "Statements": [
             {
               "NotStatement": {
                 "Statement": {
                   "LabelMatchStatement": {
                     "Key": "awswaf:managed:aws:bot-control:bot:verified",
                     "Scope": "LABEL"
                   }
                 }
               }
             },
             {
               "NotStatement": {
                 "Statement": {
                   "LabelMatchStatement": {
                     "Key": "IsAutomatedUnverifiedRequest",
                     "Scope": "LABEL"
                   }
                 }
               }
             },
             {
               "NotStatement": {
                 "Statement": {
                   "RegexMatchStatement": {
                     "FieldToMatch": {
                       "SingleHeader": {
                         "Name": "kyapay-token"
                       }
                     },
                     "RegexString": "^[A-Za-z0-9-_]+\\.[A-Za-z0-9-_]+\\.[A-Za-z0-9-_]*$",
                     "TextTransformations": [
                       {
                         "Priority": 0,
                         "Type": "NONE"
                       }
                     ]
                   }
                 }
               }
             }
           ]
         }
       },
       "VisibilityConfig": {
         "CloudWatchMetricsEnabled": true,
         "MetricName": "CheckIfHumanTraffic",
         "SampledRequestsEnabled": true
       }
     }

   You can reorder or extend these rules to fit your needs. The full Web ACL from the demo is in the reference repo.

7. With your function published, add a trigger: open your distribution's Behaviors tab, edit the default behavior, and under Function associations, associate the function's versioned ARN with the Viewer request event. Token verification then happens before CloudFront checks its cache.