# gizlang/webpush

Web Push: a message to a browser that subscribed, which it shows even with no tab of the site open. The message is encrypted for the browser (RFC 8291, aes128gcm, one record) and the request is signed by the sender's VAPID key (RFC 8292, an ES256 JWT). `push` sends one and answers the push service's status: 404 and 410 say the subscription is gone.

```gizlang
import * as Webpush from "gizlang/webpush";
```

## Types

### `Vapid`

```gizlang
type Vapid = { key: bytes; public: bytes; subject: string; }
```

A sender's VAPID key: the P-256 private scalar, its public point (65 octets, uncompressed) and the contact
address the push service may write to (`mailto:` or `https:`).

- `key`: `bytes`
- `public`: `bytes`
- `subject`: `string`

## Functions

### `vapid`

```gizlang
function vapid(key: string, subject: string): Option<Vapid>
```

The VAPID key of KEY, a base64url P-256 private scalar (32 octets), with SUBJECT; undefined when KEY is none.

Effects: fail, alloc.

### `sealed`

```gizlang
function sealed(payload: bytes, ua: bytes, auth: bytes, asKey: bytes, salt: bytes): Option<bytes>
```

PAYLOAD encrypted for the browser key UA (65 octets) and secret AUTH (16), by the ephemeral key AS_KEY with SALT
(16): the whole aes128gcm body. Undefined for a key of another size or a point off the curve.

Effects: fail, alloc.

### `authorization`

```gizlang
function authorization(v: Vapid, endpoint: string, now: i64): Option<string>
```

The VAPID Authorization header value for ENDPOINT at NOW (seconds), valid 12 hours.

Effects: fail, alloc.

### `push`

```gizlang
function push(v: Vapid, endpoint: string, p256dh: string, auth: string, payload: bytes): i64 throws string
```

Sends PAYLOAD from V to the browser at ENDPOINT with its keys P256DH and AUTH (base64url, as the browser's
subscription has them), kept by the push service a day: the service's status. Throws when the keys are invalid or
the service cannot be reached.

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

