@e4a/pg-wasm

pg-wasm

Most consumers want @e4a/pg-js instead of this package directly — it wraps these bindings with a friendlier API, and @e4a/pg-wasm is its dependency.

This package is published to npm on every pg-core release, at pg-core's version, and has no release cycle of its own. For what changed in a given version, read pg-core's changelog for the same version number.

This package contains automatically generated WebAssembly bindings to call into the PostGuard Rust library from Javascript or Typescript. This library has been configured to run in a browser via a bundler.

The ReadableStream and WritableStream Web APIs are required. Most notably, WritableStream is not supported on Firefox until version 100, see WritableStream.

If not available, please consider using a polyfill, see web-streams-polyfill.

Usage

See the examples in postguard-js for working examples.

Fetching keys

Fetching keys from the PKG (for both decryption/signing) is easiest using the Yivi frontend packages and a custom session field.

// The URL of the PKG.
const PKG_URL = "...";

const KeySorts = {
  Encryption: "key",
  Signing: "sign/key",
};

export async function fetchKey(
  sort,
  keyRequest,
  timestamp = undefined,
  signingKeyRequest = undefined
) {
  const session = {
    url: PKG_URL,
    start: {
      url: (o) => `${o.url}/v2/request/start`,
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(keyRequest),
    },
    result: {
      url: (o, { sessionToken }) => `${o.url}/v2/request/jwt/${sessionToken}`,
      parseResponse: (r) => {
        return r
          .text()
          .then((jwt) =>
            fetch(
              `${PKG_URL}/v2/irma/${sort}${
                timestamp ? "/" + timestamp.toString() : ""
              }`,
              {
                method: sort === KeySorts.Encryption ? "GET" : "POST",
                headers: {
                  Authorization: `Bearer ${jwt}`,
                  "Content-Type": "application/json",
                },
                ...(signingKeyRequest && {
                  body: JSON.stringify({ ...signingKeyRequest }),
                }),
              }
            )
          )
          .then((r) => r.json())
          .then((json) => {
            if (json.status !== "DONE" || json.proofStatus !== "VALID")
              throw new Error("not done and valid");
            return sort === KeySorts.Encryption
              ? json.key
              : { pubSignKey: json.pubSignKey, privSignKey: json.privSignKey };
          })
          .catch((e) => console.log("error: ", e));
      },
    },
  };

  const yivi = new YiviCore({ debugging: false, session });
  yivi.use(YiviClient);
  yivi.use(YiviPopup);
  return yivi.start();
}

Encryption

// Load the WASM module.
const { sealStream } = await import("@e4a/pg-wasm");

// Retrieve the public key from PKG API:
const resp = await fetch(`${url}/v2/parameters`);
const pk = await resp.json().then((r) => r.publicKey);

// We provide the policies which we want to use for encryption.
const policy = {
  Bob: {
    ts: Math.round(Date.now() / 1000),
    con: [{ t: "irma-demo.sidn-pbdf.email.email", v: "[email protected]" }],
  },
};

// We provide the policies which we want to sign with.

// This policy is visible to everyone.
const pubSignId = [
  { t: "irma-demo.gemeente.personalData.fullname", v: "Alice" },
];

// This policy is only visible to recipients.
const privSignId = [{ t: "irma-demo.gemeente.personalData.bsn", v: "1234" }];

// We retrieve keys for these policies.
let { pubSignKey, privSignKey } = await fetchKey(
  KeySorts.Signing,
  { con: [...pubSignId, ...privSignId] },
  undefined,
  { pubSignId, privSignId }
);

const sealOptions = {
  policy,
  pubSignKey,
  privSignKey,
};

// The following call reads data from a `ReadableStream` and seals it into `WritableStream`.
// Make sure that only chunks of type `Uint8Array` are enqueued to `readable`.
await sealStream(pk, sealOptions, readable, writable);

Decryption

// Load the WASM module.
const { StreamUnsealer } = await import("@e4a/pg-wasm");

// Retrieve to global verification key.
const vk = await fetch(`${PKG_URL}/v2/sign/parameters`)
  .then((r) => r.json())
  .then((j) => j.publicKey);

// Start reading from the ReadableStream. This will read
// the metadata up until the actual payload. The stream is still locked.
const unsealer = await StreamUnsealer.new(readable, vk);

// Retrieve the recipients (and their respective policies) from the header.
const recipients = unsealer.inspect_header();

// In this case it will yield:
// {
//  'Bob': {                                              // recipient identifier
//    ts: 1643634276,                                     // timestamp
//    con: [                                              // conjunction of attributes
//      { t: "irma-demo.sidn-pbdf.email.email", v: "" },  // type/value pairs
//    ],
//  },
// }

// The disclosed values have to match with the values used for encryption.
// Note that we do not include a timestamp here.
const keyRequest = {
  con: [{ t: "irma-demo.sidn-pbdf.email.email", v: "Bob" }],
};

const timestamp = recipients.get("Bob").ts;
const usk = await fetchKey(KeySorts.Encryption, keyRequest, timestamp);

// Unseal the contents, writing the plaintext to a `WritableStream`.
let sender = await unsealer.unseal("Bob", usk, writable);

// console.log(sender) will give the policy that was used to sign:
// {
//   "public": {
//     "ts": 1680531126,
//     "con": [
//       {
//         "t": "irma-demo.gemeente.personalData.fullname",
//         "v": "Alice"
//       }
//     ]
//   },
//   "private": {
//     "ts": 1680531130,
//     "con": [
//       {
//         "t": "irma-demo.gemeente.personalData.bsn",
//         "v": "1234"
//       }
//     ]
//   }
// }

Encrypting Uint8Array

Encrypting and decrypting Uint8Array works similar as the example above. The WASM module also exports seal and Unsealer, which can be used for this. The function seal returns a new Uint8Array. The Unsealer.unseal method returns an array [plain, policy], where plain is a Uint8Array containing the plaintext and policy is an object containing the sender's signing policy.

Using Web Workers

Since ReadableStream and WritableStream are transferable, it is advised to perform the sealing and unsealing off the main thread, e.g., in a Web Worker. Comlink can be a useful library to communicate between threads.