webpush - v2.0.0

webpush/vapid

Types

VapidError

</>

Represents possible errors that can occur during VAPID operations.

  • InvalidEndpoint(String): The endpoint has no scheme and host to derive the JWT audience from.
  • InvalidSubscriber(String): The contact is empty. RFC 8292 requires a mailto: or https: URI the push service operator can reach.
  • DecodeKeyError: Occurs when decoding a cryptographic key fails.
  • InvalidPrivateKey(Int): The private key is not the 32 byte P-256 scalar.
  • InvalidPublicKey(Int): The public key is not a 65 byte uncompressed point.
  • MismatchedKeyPair: The public key does not belong to the private key.
  • CryptoError(String): Represents an error related to cryptographic operations.
pub type VapidError {
  InvalidEndpoint(String)
  InvalidSubscriber(String)
  DecodeKeyError
  InvalidPrivateKey(Int)
  InvalidPublicKey(Int)
  MismatchedKeyPair
  CryptoError(String)
}

Constructors 

  • InvalidEndpoint(String)
  • InvalidSubscriber(String)
  • DecodeKeyError
  • InvalidPrivateKey(Int)
  • InvalidPublicKey(Int)
  • MismatchedKeyPair
  • 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 string.

Accepts either alphabet, padded or not: base64_url_decode maps the URL safe characters onto the standard ones and restores any missing padding.

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.

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

✨ Search Document