webpush/vapid

Types

VapidError

Represents possible errors that can occur during VAPID operations.

InvalidEndpoint(String): Indicates that the provided endpoint is invalid.
DecodeKeyError: Occurs when decoding a cryptographic key fails.
UnknownError(String): Represents an unspecified error with a message.
CryptoError(String): Represents an error related to cryptographic operations.

pub type VapidError {
  InvalidEndpoint(String)
  DecodeKeyError
  UnknownError(String)
  CryptoError(String)
}

Constructors

```
InvalidEndpoint(String)
```
```
DecodeKeyError
```
```
UnknownError(String)
```
```
CryptoError(String)
```

VapidKeys

</>

Represents a pair of VAPID (Voluntary Application Server Identification) keys used for Web Push authentication. Contains the private and public keys encoded in base64url format.

pub type VapidKeys {
  VapidKeys(
    private_key_b64url: String,
    public_key_b64url: String,
  )
}

Constructors

VapidKeys(private_key_b64url: String, public_key_b64url: String)

Values

decode_vapid_key

</>

pub fn decode_vapid_key(b64: String) -> Result(BitArray, Nil)

Decodes a VAPID key from a base64 or base64 URL encoded string.

Attempts to decode the given string using base64 URL decoding first. If that fails, it falls back to standard base64 decoding.

Returns Ok(BitArray) if decoding is successful, or Error(Nil) if both decoding attempts fail.

b64: The base64 or base64 URL encoded string representing the VAPID key.

generate_vapid_keys

</>

pub fn generate_vapid_keys() -> Result(VapidKeys, VapidError)

Generates a new pair of VAPID (Voluntary Application Server Identification) keys using the P-256 elliptic curve. The private and public keys are encoded in base64 URL-safe format. Returns a Result containing the generated VapidKeys on success, or a VapidError if key generation fails.

Returns

Ok(VapidKeys): Contains the base64 URL-encoded private and public keys.
Error(VapidError): Contains an error message if key generation fails.

now_unix

</>

pub fn now_unix() -> Int

Returns the current Unix timestamp as an integer. This function is implemented externally in Erlang via the webpush_vapid_ffi module. Useful for generating time-based values, such as VAPID token expiration.

vapid_authorization_header

</>

pub fn vapid_authorization_header(
  endpoint: String,
  subscriber: String,
  vapid_public_key_b64url: String,
  vapid_private_key_b64url: String,
  expiration_unix: Int,
) -> Result(String, VapidError)

Generates the Authorization header value required for Web Push (VAPID).

This function constructs a header in the format: vapid t=<jwt>, k=<base64url(pub)>, where <jwt> is a JSON Web Token signed with the provided VAPID private key, and <base64url(pub)> is the base64url-encoded VAPID public key.

Parameters:

endpoint: The push service endpoint URL.
subscriber: The subscriber’s contact information (e.g., mailto address).
vapid_public_key_b64url: The base64url-encoded VAPID public key.
vapid_private_key_b64url: The base64url-encoded VAPID private key.
expiration_unix: The expiration time for the JWT, as a Unix timestamp.

Returns:

Result(String, VapidError): On success, returns the header value as a string. On failure, returns a VapidError describing the error. Produce the Authorization header value for Web Push (VAPID). Returns: vapid t=<jwt>, k=<base64url(pub)>.

vapid_error_to_string

</>

pub fn vapid_error_to_string(error: VapidError) -> String

Converts a VapidError into a human-readable string message.

Arguments

error: The VapidError to be converted.

Returns

A descriptive string representing the error type and details.

Error Variants

InvalidEndpoint(endpoint): Indicates an invalid endpoint, includes the endpoint string.
DecodeKeyError: Indicates a failure to decode the VAPID key.
UnknownError(msg): Represents an unknown error with a message.
CryptoError(msg): Represents a cryptographic error with a message.