doc: Update doc to V2

doc/API-keys.md

@@ -0,0 +1,36 @@
+# API Keys
+
+When you use `API_KEY` as an [authentication method](authentication.md), you can control how API keys are created under `appSync.apiKeys`. It takes an array of api key definitions or strings.
+
+## Quick start
+
+```yaml
+appSync:
+  apiKeys:
+    - john
+    - name: jane
+      description: Jane's API key.
+      expiresAfter: 1M
+```
+
+## configuration
+
+It can either be string, which translates into the API key's name with default values for the other attributes, or use a custom configuration.
+
+- `name`: A unique name for this API key. Required.
+- `description`: An optional description for this API key.
+- `expiresAfter`: A time ater which this API key will expire. [See below](Expiry) for more details about expiry. Defaults to `365y`.
+- `expiresAt`: A time at which this API key will expire. [See below](Expiry) for more details about expiry.
+- `wafRules`: an array of [WAF rules](WAF.md) that will apply to this API key only.
+
+## Expiry
+
+You can control expiry of the API keys with the `expiresAfter` or `expiresAt` attribute.
+
+`expiresAfter` behaves as a sliding-window expiry date which extends after each deployment. It can be a number of hours until expiry or a more human-friendly string. e.g. `24h`, `30d`, `3M`, `1y`.
+
+`expiresAt` is an exact ISO datetime at which this API will expire. It will not be renewd unless you change this value. e.g. `2022-02-13T10:00:00`.
+
+`expiresAfter` takes precedence over `expiresAt`. If neither are passed, it defaults to a `expiresAfter` of `365d`
+
+**Note**: The minimum lifetime of an API key in AppSync is 1 day and maximum is 1 year (365 days). Expiry datetimes are always rounded down to the nearest hour. (e.g. `2022-02-13T10:45:00` becomes `2022-02-13T10:00:00`).

doc/WAF.md

@@ -0,0 +1,191 @@
+# Web Application Firewall (WAF)
+
+AppSync [supports WAF](https://aws.amazon.com/blogs/mobile/appsync-waf/). WAF is an Application Firewall that helps you protect your API against common web exploits.
+
+This plugin comes with some handy pre-defined rules that you can enable in just a few lines of code.
+
+You can configure WAF rules under the `appSync.waf` attribute.
+
+## Quick start
+
+```yaml
+appSync:
+  name: my-api
+  waf:
+    enabled: true
+    defaultAction: 'Allow'
+    rules:
+      - throttle
+      - disableIntrospection
+```
+
+## Configuration
+
+- `enabled`: Boolean. Enable or disable WAF. Defaults to `true` when `appSync.waf` is defined.
+- `name`: Optional. The name of this WAF instance. Defaults to the name of your API.
+- `defaultAction`: Optional. The default action if a request does not match a rule. `Allow` or `Block`. Defaults to `Allow`.
+- `description`: A description for this WAF instance.
+- `visibilityConfig`: Optional. A [visibility config](https://docs.aws.amazon.com/waf/latest/APIReference/API_VisibilityConfig.html) for this WAF
+  - `name`: Metric name
+  - `cloudWatchMetricsEnabled`: A boolean indicating whether the associated resource sends metrics to Amazon CloudWatch
+  - `sampledRequestsEnabled`: A boolean indicating whether AWS WAF should store a sampling of the web requests that match the rule
+- `rules`: An array of [rules](#rules).
+
+## Rules
+
+### Configuration
+
+Common configuration to all rules:
+
+- `name`: The name of the rule
+- `action`: How this rule should handle the incoming request. `Allow` or `Deny`. Defaults to `Allow`.
+- `priority`: The priority of this rule. See [Rules Priority](#rules-priority)
+- `visibilityConfig`: The [visibility config](https://docs.aws.amazon.com/waf/latest/APIReference/API_VisibilityConfig.html) for this rule.
+
+### Throttling
+
+Throttling will disallow requests coming from the same ip address when a limit is reached within a 5-minutes period. It corresponds to a rules with a [RateBasedStatement](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-wafv2-webacl-ratebasedstatement.html).
+
+Examples:
+
+```yml
+waf:
+  enabled: true
+  rules:
+    - throttle # limit to 100 requests per 5 minutes period
+    - throttle: 200 # limit to 200 requests per 5 minutes period
+    - throttle:
+        limit: 200
+        priority: 10
+        aggregateKeyType: FORWARDED_IP
+        forwardedIPConfig:
+          headerName: 'X-Forwarded-For'
+          fallbackBehavior: 'MATCH'
+```
+
+#### Configuration
+
+See the [CloudFormation documentation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-wafv2-webacl-ratebasedstatement.html)
+
+- `aggregateKeyType`: `IP` or `FORWARDED_IP`
+- `limit`: The limit of requests in a 5-minutes window for the same IP address.
+- `forwardedIPConfig`: [forwardedIPConfig](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-wafv2-webacl-forwardedipconfiguration.html)
+- `scopeDownStatement`: [WebACL Statement](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-wafv2-webacl-statement.html)
+
+### Disable Introspection
+
+Sometimes, you want to disable introspection to disallow untrusted consumers to discover the structure of your API.
+
+```yml
+waf:
+  enabled: true
+  rules:
+    - disableIntrospection # disables introspection for everyone
+    - disableIntrospection: # using custom configuration
+        name: Disable introspection
+        priority: 200
+```
+
+### Custom rules
+
+You can also specify custom rules. For more info on how to define a rule, see the [Cfn documentation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-wafv2-webacl-rule.html)
+
+Example:
+
+```yml
+waf:
+  enabled: true
+  defaultAction: Block
+  rules:
+    # Only allow US users
+    - action: Allow
+      name: UsOnly
+      statement:
+        GeoMatchStatement:
+          CountryCodes:
+            - US
+```
+
+### Per API Key rules
+
+In some cases, you might want to enable a rule for a given API key only. You can specify `wafRules` under the `appSync.apiKeys` attribute. The rules will apply only to that API key.
+
+```yml
+apiKeys:
+  - name: MyApiKey
+    expiresAfter: 365d
+    wafRules:
+      - throttle # throttles this API key
+      - disableIntrospection # disables introspection for this API key
+```
+
+Adding a rule to an API key without any _statement_ will add a _match-all_ rule for that key (all requests will match that rule). This is usefull for example to exclude API keys from global rules. In that case, you need to make sure to attribute a higher priority to that rule.
+
+Example:
+
+- Block all requests by default, except in the US.
+- The `WorldWideApiKey` API key should be excluded from that rule.
+
+```yml
+appSync:
+  waf:
+    enabled: true
+    defaultAction: Block # Block all by default
+    rules:
+      # allow US requests
+      - action: Allow
+        name: UsOnly
+        priority: 5
+        statement:
+          geoMatchStatement:
+            countryCodes:
+              - US
+  apiKeys:
+    - name: Key1 # no rule is set, the global rule applies (US only)
+    - name: Key1 # no rule is set, the global rule applies (US only)
+    - name: WorldWideApiKey
+      wafRules:
+        - name: WorldWideApiKeyRule
+          action: Allow
+          priority: 1 # Since priority is higher than 5, all requests will be Allowed
+```
+
+### Rules priority
+
+The priorities don't need to be consecutive, but they must all be different.
+
+Setting a priority to the rules is not required, but recommended. If you don't set priority, it will be automatically attributed and sequentially incremented according to the following rules:
+
+First the global rules (under `appSync.waf.rules`), in the order that they are defined, then the API key rules, in order of the API keys and their rules.
+
+Auto-generated priorities start at 100. This gives you som room (0-99) to add other rules that should get a higher priority, if you need to.
+
+For more info about how rules are executed, pease refer to [the documentation](https://docs.aws.amazon.com/waf/latest/developerguide/web-acl-processing.html)
+
+Example:
+
+```yml
+appSync:
+  waf:
+    enabled: true
+    rules:
+      - name: Rule1
+        # (no-set) Priority = 100
+      - name: Rule2
+        priority: 5 # Priority = 5
+      - name: Rule3
+        # (no-set) Priority = 101
+  apiKeys:
+    - name: Key1
+      wafRules:
+        - name: Rule4
+          # (no-set) Priority = 102
+        - name: Rule5
+          # (no-set) Priority = 103
+    - name: Key
+      wafRules:
+        - name: Rule6
+          priority: 1 # Priority = 1
+        - name: Rule7
+          # (no-set) Priority = 104
+```

doc/authentication.md

@@ -0,0 +1,100 @@
+# Authentication
+
+[Authentication](https://docs.aws.amazon.com/appsync/latest/devguide/security-authz.html) definitions are found under the `appSync.authentication` (for the default authentication method) and `appSync.additionalAuthenticationProviders` (as an array) for additional ones
+
+## Quick start
+
+```yaml
+appSync:
+  authentication:
+    type: 'API_KEY'
+  additionalAuthenticationProviders:
+    - type: 'AMAZON_COGNITO_USER_POOLS'
+      config:
+        userPoolId: '123456789'
+```
+
+## Configuration
+
+- `type`: The type of authentication. Can be `API_KEY`, `AWS_IAM`, `AMAZON_COGNITO_USER_POOLS`, `AWS_LAMBDA` or `OPENID_CONNECT`
+- `config`: The configuration for the provided `type` (See below).
+
+### API Keys
+
+Enables the API Key based authentication. See the [API Keys section](API-keys.md) to see how to configure them.
+
+```yaml
+appSync:
+  authentication:
+    type: 'API_KEY'
+```
+
+`config` is not required for this type.
+
+### IAM
+
+Allows IAM users ands roles to access the API.
+
+```yaml
+appSync:
+  authentication:
+    type: 'AWS_IAM'
+```
+
+`config` is not required for this type.
+
+### Cognito
+
+Allows authentication using a Cognito.
+
+```yaml
+appSync:
+  authentication:
+    type: 'AMAZON_COGNITO_USER_POOLS'
+    config:
+      userPoolId: '123456789'
+```
+
+- `userPoolId`: The user pool id to use.
+- `awsRegion`: The region where the user pool is located. Defaults to the stack's region.
+- `appIdClientRegex`: An optional regular expression for validating the incoming Amazon Cognito user pool app client ID.
+
+### OIDC
+
+Allows users to authenticate against the API using a third-party OIDC auth provider.
+
+```yaml
+appSync:
+  authentication:
+    type: 'OPENID_CONNECT'
+    config:
+      issuer: 'https://auth.example.com'
+      clientId: '5fbc318d-5920-48a8-92ea-20d62d16cc60'
+```
+
+- `issuer`: The issuer of this OIDC config.
+- `clientId`: Optional. The client identifier of the Relying party at the OpenID identity provider. This identifier is typically obtained when the Relying party is registered with the OpenID identity provider. You can specify a regular expression so that AWS AppSync can validate against multiple client identifiers at a time.
+- `iatTTL`: Optional. The number of milliseconds that a token is valid after it's issued to a user.
+- `authTTL`: Optional. The number of milliseconds that a token is valid after being authenticated.
+
+### Lambda
+
+Allows custom authentication thoguht Lambda.
+
+```yaml
+appSync:
+  authentication:
+    type: 'AWS_LAMBDA'
+    config:
+      authorizerResultTtlInSeconds: 300
+      function:
+        timeout: 30
+        handler: 'functions/auth.handler'
+```
+
+- `identityValidationExpression`: Optional. A regular expression for validation of tokens before the Lambda function is called.
+- `authorizerResultTtlInSeconds`: Optional. The number of seconds a response should be cached for. The default is 5 minutes (300 seconds).
+- `function`: A Lambda function definition as you would define it under the `functions` section of your `serverless.yml` file.
+- `functionName`: The name of the function as defined under the `functions` section of the `serverless.yml` file
+- `functionAlias`: A specific function alias to use.
+- `functionArn`: The function ARN to use.

doc/caching.md

@@ -0,0 +1,32 @@
+# Caching
+
+AppSync supports [server-side data caching](https://docs.aws.amazon.com/appsync/latest/devguide/enabling-caching.html). You can find the caching configuration under the `appSync.caching` attribute.
+
+## Quick start
+
+```yaml
+appSync:
+  name: my-api
+  caching:
+    behavior: 'PER_RESOLVER_CACHING'
+    type: 'SMALL'
+    ttl: 3600
+    atRestEncryption: false
+    transitEncryption: false
+```
+
+## Configuration
+
+- `behavior`: `FULL_REQUEST_CACHING` or `PER_RESOLVER_CACHING`
+- `type`: The type of the Redis instance. `SMALL`, `MEDIUM`, `LARGE`, `XLARGE`, `LARGE_2X`, `LARGE_4X`, `LARGE_8X`, `LARGE_12X`. Defaults to `SMALL`
+- `ttl`: The default TTL of the cache in seconds. Defaults to `3600`. Maximum is `3600`
+- `atRestEncryption`: Boolean. Whether to encrypt the data at rest. Defaults to `false`
+- `transitEncryption`: Boolean. Whether to encrypt the data in transit. Detaults to `false`
+
+## Per resolver caching
+
+See [Resolver cacing](resolvers.md#caching)
+
+## Flushing the cache
+
+You can use the [flush-cache command](commands.md#flush-cache) to easily flush the cache.