# gizlang:acme

ACME v2 (RFC 8555). One account and one domain set per private Dir. Mount challenge(dir, request) on the caller's public HTTP port 80 before certificate() runs. No listener, HTTP codec or JSON codec is owned here.

```gizlang
import * as Acme from "gizlang:acme";
```

## Types

### `AcmeError`

```gizlang
type AcmeError = { stage: string; status: i64; problem: string; detail: string; }
```

Why an issue failed: the stage, the HTTP status (0 without one), the ACME problem type and a detail.

- `stage`: `string`
- `status`: `i64`
- `problem`: `string`
- `detail`: `string`

### `Certificate`

```gizlang
type Certificate = { chain: bytes; key: bytes; from: i64; until: i64; }
```

An issued certificate: the PEM chain, the PEM private key, and its validity in milliseconds since the epoch.

- `chain`: `bytes`
- `key`: `bytes`
- `from`: `i64`
- `until`: `i64`

## Functions

### `jws`

```gizlang
function jws(key: bytes, kid: string, nonce: string, url: string, payload: string): string throws AcmeError
```

One flattened JWS. An empty payload is POST-as-GET; kid and jwk are exclusive.

Effects: fail.

### `retryAfter`

```gizlang
function retryAfter(headers: Vec<Http.Header>, now: i64): i64 throws AcmeError
```

Retry-After is either delta seconds or an HTTP date; cap the wait.

Effects: fail.

### `challenge`

```gizlang
function challenge(dir: Dir, request: Http.Request): Http.Response
```

Exact HTTP-01 token lookup. It cannot select a filesystem path.

Effects: fail, io.

### `certificate`

```gizlang
function certificate(sys: System, dir: Dir, directoryUrl: string, domains: Vec<string>, contact: string): Certificate throws AcmeError
```

Return the stored certificate until two thirds of its lifetime have elapsed.
Calling this entry agrees to the directory's terms of service.

Effects: fail, read, write, console, io.

### `renew`

```gizlang
function renew(sys: System, dir: Dir, directoryUrl: string, domains: Vec<string>, contact: string, credentials: Tls.Credentials): Task.Task<Result<bool, AcmeError>>
```

Renew at two thirds of the lifetime and publish to the shared TLS cell.
Errors are returned by the task. The caller must join or monitor it.

Effects: fail, read, write, console, io.

## Constants

### `TIMEOUT_MS`

```gizlang
const TIMEOUT_MS = 120000
```

The time limit for one whole certificate issue, in milliseconds.

### `REQUEST_TIMEOUT_MS`

```gizlang
const REQUEST_TIMEOUT_MS = 10000
```

The time limit for one request to the ACME server, in milliseconds.

### `MAX_POLLS`

```gizlang
const MAX_POLLS = 30
```

The most times an order or authorization is polled before the issue fails.

### `MAX_RESPONSE_BYTES`

```gizlang
const MAX_RESPONSE_BYTES = 65536
```

The largest ACME response body and stored file that are read, in bytes.