@imput/cup2

Client/server implementation of the Chromium/Omaha CUP-ECDSA protocol in Typescript.

Installation

• Deno: deno add @imput/cup2
• Node.js: npx jsr add @imput/cup2

Examples

client

import { CupClient } from '@imput/cup2';

const keyId = /* your key ID goes here */;
const keyBytes = new Uint8Array([
    /* your EC pubkey bytes go here, or you can load it from a file */
]);

// This is the side of the requestor of resources,
// which is usually a browser reaching out to some API.
const publicKey = await crypto.subtle.importKey(
    'spki', keyBytes,
    { name: 'ECDSA', namedCurve: 'P-256' },
    false, ['verify'],
);

const client = new CupClient(keyId, publicKey);

const raw_request = new Request('http://clients2.google.com/time/1/current');
const { request, ticket } = await client.wrap(raw_request);

// make the request after adding cup parameters
const response = await fetch(request);

// verify() throws a CupError if the signature is not valid
await client.verify(response, ticket);

// we can now consume the response
console.log(await response.text());

server

import { CupServer } from '@imput/cup2';

const keys: Record<number, CryptoKey> = {
    /* keys should be periodically rotated,
       but we still need to support older
       clients. this is why you are able to
       insert multiple keys here. load them
       from a file or something, this is entirely
       up to you
    */
};

const cup = new CupServer(keys);

Deno.serve(async (request: Request) => {
    // this library assumes all your incoming requests use CUP.
    // if this is not the case, you need to check for presence
    // of cup2key in request.url.searchParams and decide whether
    // you want to use CUP or not

    // this is separated from the signing process
    // so that we can do some preliminary checks and not
    // waste processing time if the request does not meet the
    // preconditions.
    const ticket = await cup.makeTicket(request);
    // hold on to this ticket, do some work ...
    // ...
    // we have a response!
    const response = new Response();
    // sign and return
    // TODO: cup.* methods throw a CupError if something
    // is wrong -- you probably want to check for that.
    return cup.sign(response, ticket);
});

more:

• mod_test.ts
• client_test.ts

License

AGPL-3.0, see LICENSE.

For other licensing options, you can reach us at meow [@] imput.net.