Private State Tokens

Typescript library implementing Private State Token API (https://wicg.github.io/trust-token-api/)

This library depends on Cloudflare's voprf-ts tested implementation to compute the Scalars and transformations.

Security Disclaimer

🚨 This library is offered as-is, and without a guarantee. Therefore, it is expected that changes in the code, repository, and API occur in the future. We recommend to take caution before using this library in a production application since part of its content is experimental. All security issues must be reported, please notify us immediately.

Install Dependencies and Build

npm install
npm run build

Sample Issuer

Sample has been built using Express Library

• Start Sample Server

  npm run example
  

• Running with Docker

  • build

    docker-compose build
    

  • start

    docker-compose up
    

Running with Static Key-Pair and Expiration

• Generate up to 6 KeyPairs

  node bin/voprf_gen_keys.cjs 1
  node bin/voprf_gen_keys.cjs 2
  # Keep creating until node bin/voprf_gen_keys.cjs 6
  

• Export Keys as Environment Variables

  export PRIVATE_KEY1=<BASE64 PRIVATE KEY 1 GENERATED PREVIOUSLY>
  export PUBLIC_KEY1=<BASE64 PUBLIC KEY 1 GENERATED PREVIOUSLY>
  export PRIVATE_KEY2=<BASE64 PRIVATE KEY 2 GENERATED PREVIOUSLY>
  export PUBLIC_KEY2=<BASE64 PUBLIC KEY 2 GENERATED PREVIOUSLY>
  # Keep defining until PRIVATE_KEY6 and PUBLIC_KEY6
  

• Export Key Expiration as Environment Variable

  export EXPIRY1=1709509052048
  export EXPIRY2=1709994102048
  # Keep defining until EXPIRY6
  

If running with Docker define those variables in docker-compose.yaml or -e argument for docker inline

Endpoints

• Key Commitment Endpoint

  curl http://localhost:3000/.well-known/trust-token/key-commitment
  

Resources, Libraries and Specs:

• Google Privacy Sandbox - Private State Tokens
• Private State Tokens API Spec
• Privacy Pass Issuance Protocol Spec
• Oblivious Pseudorandom Functions (OPRFs) Spec
• Batched Tokens Issuance Protocol Spec
• CloudFlare - Privacy Pass TypeScript Library
• CloudFlare - VOPRF TypeScript Library

How to use this library

Token Issuance

To issue a token, you must check for the request header sec-private-state-token, after verify it is present and it is not null or empty you can use the Issuer class like the code bellow:

import { PSTRedeemer, PSTResources } from "@authcube/pst";

const sec_private_state_token = req.headers[
  "sec-private-state-token"
] as string;
if (sec_private_state_token && !sec_private_state_token.match(BASE64FORMAT)) {
  return res.sendStatus(400);
}

try {
  let issuer = await PSTResources.getIssuer();
  const token = await issuer.issueToken(sec_private_state_token);

  res.statusCode = 200;
  res.setHeader("Content-Type", "text/html");
  res.append("sec-private-state-token", token);
  res.setHeader("Sec-Private-State-Token", token);
  res.write("Issuing tokens.");
  res.send();

  return res.end();
} catch (e: any) {
  // deal with the error as you see fit
  console.error("Error issuing PST", e);
  return res.sendStatus(500);
}

Token Redeemption

To redeem an issued token the process is similar, your endpoint must check for the request header sec-private-state-token, if it is present and it is not null or empty you can proceed to the redeemption

import { PSTRedeemer, PSTResources } from "@authcube/pst";

try {
  const redemptionToken = req.headers["sec-private-state-token"] as string;

  if (redemptionToken && !redemptionToken.match(BASE64FORMAT)) {
    return res.sendStatus(400);
  }

  const redeemer = new PSTRedeemer();

  // This call will throw an Error if the token is invalid
  const resToken = await redeemer.redeemToken(redemptionToken);

  res.statusCode = 200;
  res.setHeader("Access-Control-Allow-Origin", "*");
  res.append("sec-private-state-token", resToken);
  res.write("Token redeemed.");
  return res.send();
} catch (e) {
  // deal with the error as you see fit
  console.error(`Error on redemption: ${e}`);
  return res.sendStatus(400);
}