@authcube/pst v1.1.6
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
- build
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);
}