# schemes-secure

Source: https://apigenie.pl/docs/linter/swagger/rules/schemes-secure

This rule checks whether a Swagger 2.0 document serves its API over secure
transfer protocols only, and whether its host is written in lower case.

## Rule Details

The root `schemes` list, and the `schemes` lists of operations that override
it, name the transfer protocols of the API. `http` and `ws` send requests,
credentials and responses unencrypted, so production APIs should use `https`
and `wss` instead.

The `schemes-secure` rule reports:

- `Insecure scheme (http)` or `Insecure scheme (ws)` for every insecure
  scheme in the root `schemes` list and in the `schemes` list of every
  operation,
- `Host is not lower case` when the root `host` contains upper case
  letters. Host names are case-insensitive, and lower case is their canonical
  form.

Insecure schemes are allowed when `host` is a loopback address: `localhost`
(in any letter case), `127.0.0.1` or `[::1]`, with or without a port. When
`host` is missing, insecure schemes are reported.

## Configuration

The rule accepts an object with one option:

- `upgradeInsecure`: whether `--fix` replaces insecure schemes with their
  secure variants. Default: `false`.

**Configuration Example**

```yaml
version: "1.0"
commands:
  lint:
    swagger:
      rules:
        schemes-secure:
          - error
          - upgradeInsecure: true
```

## Examples

**Good**.

```yaml
swagger: '2.0'
info:
  title: Pet Store
  version: 1.0.0
host: api.example.com
schemes: [https, wss]
paths: {}
```

**Good**. A local development server may use `http`.

```yaml
swagger: '2.0'
info:
  title: Pet Store
  version: 1.0.0
host: localhost:8080
schemes: [http]
paths: {}
```

**Bad**. The root object allows `http`, an operation uses `ws`, and the host
is not lower case.

```yaml
swagger: '2.0'
info:
  title: Pet Store
  version: 1.0.0
host: API.Example.com
schemes: [http, https]
paths:
  /pets/events:
    get:
      schemes: [ws]
      responses:
        '101':
          description: Switching to the event stream.
```

## Automatic fixes

When invoked with `--fix`, the rule always converts the root `host` to lower
case.

With `upgradeInsecure: true`, it also rewrites every root and operation
`schemes` list that contains an insecure scheme, unless the host is a loopback
address: `http` becomes `https`, `ws` becomes `wss`, and duplicates are
removed while the order is kept. For example, `[http, https, ws]` becomes
`[https, wss]`. Without this option the insecure schemes are reported, but not
changed, because switching protocols requires the server to support them.

## When Not to Use It

You may disable this rule for documents that describe APIs that are only
reachable in a trusted network, or for an operation with
`x-lint-disable: [schemes-secure]`.

## Compatibility

This rule is compatible with Swagger 2.0 documents. OpenAPI 3.x documents are
linted by the OpenAPI linter, whose `server-urls` rule checks the URLs of
servers.