Request Validation

Ship It Signature

The Auth0 token provided in the X-User-Token header can be used to confirm that the user is authenticated with Auth0, but in order to verify that the billing headers described above originated from Ship It, you must verify the Ship It signature header. This can be done using the public key visible on the sites configuration page in the Ship It dashboard.

JavaScript / TypeScript

Please use the @ship-it-app/validate package to easily validate headers from Ship It.

Install

npm i @ship-it-app/validate

Usage

import { validate } from '@ship-it-app/validate';

async function fetch(request, env) {
    const isValid = await validate(
		env.REQUEST_PUBLIC_KEY,
		request.headers.get('X-Proxy-Signature'),
		request.headers.get('X-Proxy-Timestamp'),
		request.headers.get('X-User-Sub'),
	);
    if (!isValid) {
        return new Response(
            "unauthorized",
            {
                status: 401
            }
        );
    }
}

Python

Please use the ship-it-validate package to easily validate headers from Ship It.

Install

pip install ship-it-validate

Usage

For example, validate headers before every request in a Flask app:

from ship_it_validate import validate
from flask import request

@app.before_request
def before_request():
    try:
        validate(
            request.headers.get('X-PROXY-SIGNATURE'),
            request.headers.get('X-USER-SUB'),
            request.headers.get('X-PROXY-TIMESTAMP'),
        )
    except ValueError as e:
        app.logger.warning('Invalid Ship It signature: %s', e)
        return "Unauthorized", 401

Ruby

Coming Soon

Rust

Here is an example of validating the signature in Rust using the jsonwebtoken crate:

[dependencies]
base64="0.22"
jsonwebtoken= { version="9", default-features = false }

#![allow(unused)]
fn main() {
use http::{HeaderMap, HeaderName, HeaderValue};
use jsonwebtoken::Algorithm;

#[derive(Debug)]
#[allow(dead_code)]
pub enum Error {
    Base64(base64::DecodeError),
    Deserialize(serde_json::Error),
    Jwt(jsonwebtoken::errors::Error),
}

/// Validate the request headers using the public key provided by Ship It.
/// - Returns `Ok(true)` if the signature is valid and the headers can be trusted.
/// - Returns `Ok(false)` if the request is invalid (return 400 Bad Request 
///   or 401 Unauthorized).
/// - Returns an `Err(Error) if an unexpected internal error 
///   occurred (return 500 Internal Server Error).
pub fn validate(
	// The base64-encoded public key obtained from the Ship It UI
	jwk_encoded: &str,
	// The request headers
	headers: &HeaderMap<HeaderName, HeaderValue>
) -> Result<bool, Error> {
    use base64::Engine;

    // Parse Key, you may only want to do this once
    let jwk_string = base64::prelude::BASE64_STANDARD
        .decode(jwk_encoded)
        .map_err(Error::Base64)?;
    let jwk: jsonwebtoken::jwk::Jwk =
        serde_json::from_slice(&jwk_string).map_err(Error::Deserialize)?;
    let key = jsonwebtoken::DecodingKey::from_jwk(&jwk).map_err(Error::Jwt)?;

    // Headers
    let sig_encoded = match headers.get("X-Proxy-Signature") {
        Some(sub) => sub.as_bytes(),
        None => return Ok(false),
    };
    let sub = match headers.get("X-User-Sub") {
        Some(sub) => sub.as_bytes(),
        None => return Ok(false),
    };
    let timestamp = match headers.get("X-Proxy-Timestamp") {
        Some(sub) => sub.as_bytes(),
        None => return Ok(false),
    };

    // Signature
	// `jsonwebtoken` expects a slightly different base64 encoding than the one sent
	// by Ship It, so we re-encode.
    let Ok(sig) = base64::prelude::BASE64_STANDARD.decode(sig_encoded) {
			return Ok(false);
	}
    let sig_encoded = base64::prelude::BASE64_URL_SAFE_NO_PAD.encode(&sig);

    // Payload
    let mut message = Vec::with_capacity(sub.len() + timestamp.len() + 1);
    message.extend_from_slice(sub);
    message.push(b'@');
    message.extend_from_slice(timestamp);

    // Validation
    let is_valid =
        jsonwebtoken::crypto::verify(&sig_encoded, &message, &key, Algorithm::ES256)
            .map_err(Error::Jwt)?;

    Ok(is_valid)
}
}

Other Languages

If you need to implement verification in a new language, it can be done as follows:

1. Base64 decode the public key and parse it as JSON to obtain the P-256 ECDSA JSON Web Key (JWK) which can be used with many JSON Web Token (JWT) libraries.
2. Use the X-Proxy-Sub and X-Proxy-Timestamp headers to form the string "SUB@TIMESTAMP".
3. Base64 decode the signature, and use a cryptography library to verify the signature for the string from step 2 using the JWK from step 1.

Here is a reference implementation in TypeScript:

function byteStringToUint8Array(byteString: string): Uint8Array {
	const ui = new Uint8Array(byteString.length);
	for (let i = 0; i < byteString.length; ++i) {
		ui[i] = byteString.charCodeAt(i);
	}
	return ui;
}

export async function verify_request(
	env: Env,
	receivedMacBase64: string | null,
	sub: string | null,
	timestamp: string | null
): Promise<boolean> {
	const jwk: JsonWebKey = JSON.parse(atob(env.REQUEST_PUBLIC_KEY));

	if (!receivedMacBase64 || !sub || !timestamp) {
		return false;
	}

	const key = await crypto.subtle.importKey(
		"jwk",
		jwk,
		{
			name: "ECDSA",
			namedCurve: "P-256",
		},
		false,
		["verify"]
	);
	const encoder = new TextEncoder();
	const payload = `${sub}@${timestamp}`;

	const receivedMac = byteStringToUint8Array(atob(receivedMacBase64));

	const verified = await crypto.subtle.verify(
		{ name: "ECDSA", hash: "SHA-256" },
		key,
		receivedMac,
		encoder.encode(payload)
	);

	return verified;
}

export default {
	async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
		const receivedMacBase64 = request.headers.get('X-Proxy-Signature');
		const timestamp = request.headers.get('X-Proxy-Timestamp');
		const sub = request.headers.get('X-User-Sub');
		const isValid = await verify_request(env, receivedMacBase64, sub, timestamp);
		if (!isValid) {
			return new Response('Unauthorized', { status: 401 });
		}
		
		// Handle valid request.
	},
};

Auth0 JWT

Ship It provides you with the user's access_token obtained from Auth0. If you wish to confirm that a request is legitimate and that it originates from a user that has authenticated with Auth0, you can validate this token, and also use it to fetch information about the user from Auth0.