Node.js helpers

@piedap/consent/server exports helper functions next to the client. They check webhook signatures, compute proofs, fingerprints and capture hashes, spot skipped imports, read the consent cookie and verify receipts.

Requirements#

• Node.js 18 or later.
• For verifyWebhook(): the endpoint's signing secret, whsec_….
• For identityProof(): the key's identity secret, idv_….
• For subjectFingerprint() and captureReferenceHash(): the project's fingerprint key, sfk_….

Install#

The helpers ship in the same package as the client. See Install.

Import the helpers#

import {
  verifyWebhook,
  identityProof,
  subjectFingerprint,
  captureReferenceHash,
  isSkippedImport,
  parseConsentCookie,
  consentFromCookieHeader,
  verifyReceipt,
  canonicalize,
} from '@piedap/consent/server';

The helpers are plain functions. They make no network calls and need no client.

Functions#

verifyWebhook()#

Checks that a webhook delivery is genuine and recent. Pass one object with these fields:

Returns boolean: true only when the signature matches the raw body and the timestamp is within the tolerance.

Errors A payload that is not a string or a Buffer, such as parsed JSON, can throw a TypeError. A missing header, an empty secret or a malformed value gives false.

import {
  SIGNATURE_HEADER,
  TIMESTAMP_HEADER,
  verifyWebhook,
} from '@piedap/consent/server';

const ok = verifyWebhook({
  payload: req.body, // the raw bytes
  signature: req.get(SIGNATURE_HEADER),
  timestamp: req.get(TIMESTAMP_HEADER),
  secret: process.env.PIEDAP_WEBHOOK_SECRET,
});

See Verify signatures.

identityProof()#

Computes the proof that lets a browser or an app record consent under a signed-in person.

Returns string: the hex HMAC-SHA256 of <subjectType>:<subjectId>.

Errors Throws a TypeError when identitySecret is missing, such as an unset environment variable. The other arguments are not checked, so keep the order: type first, then the identifier.

const proof = identityProof(
  process.env.PIEDAP_IDENTITY_SECRET,
  'USER_ID',
  user.id,
);

See Signed-in visitors.

subjectFingerprint()#

Computes the fingerprint that receipts and webhooks carry for a person.

Returns string: the hex HMAC-SHA256 of the identifier. An email address is put in lower case first.

Errors Throws a TypeError when fingerprintKey is missing. Here the identifier comes before the type.

const fingerprint = subjectFingerprint(
  process.env.PIEDAP_FINGERPRINT_KEY,
  'usr_8f2K1xQz',
  'USER_ID',
);

See Match events to users.

captureReferenceHash()#

Computes the agentRefHash or locationRefHash that a capture context carries, so you can match it to your own staff id or site code.

Returns string: the hex HMAC-SHA256 of <kind>:<reference>, with the reference trimmed and in lower case.

Errors Throws a TypeError when fingerprintKey or reference is missing, or kind is neither value.

const agentRefHash = captureReferenceHash(
  process.env.PIEDAP_FINGERPRINT_KEY,
  'agent',
  'EMP-40213',
);

See Record consent taken in a branch, by phone or on paper.

isSkippedImport()#

Tells a write with collectedAt that the records overrule from a real error.

Returns boolean: true for a ConsentApiError with status 409 and one of the codes in SKIPPED_IMPORT_CODES.

Errors None.

try {
  await client.recordConsent(row);
} catch (error) {
  if (!isSkippedImport(error)) throw error;
  skipped.push({ row: row.idempotencyKey, code: error.code });
}

See Bring in consent given earlier.

parseConsentCookie()#

Reads the two cookie values the browser runtime wrote.

Returns a ConsentCookie, or null.

Errors None. null comes back when the visitor has not answered or the cookie is malformed.

const consent = parseConsentCookie(
  req.cookies.piedap_consent,
  req.cookies.piedap_partners,
);

consentFromCookieHeader()#

Finds both consent cookies in a whole Cookie request header and reads them.

Returns a ConsentCookie, or null.

Errors None. null comes back when the visitor has not answered or the cookie is malformed.

app.get('/', (req, res) => {
  const consent = consentFromCookieHeader(req.get('cookie'));
  const analytics = consent?.granted('analytics') ?? false;
  const matomo = consent?.granted('analytics', 'matomo') ?? false;
  res.render('home', { analytics, matomo });
});

verifyReceipt()#

Checks an Ed25519 receipt against the deployment's public keys without calling the API.

Returns boolean: true when the signature matches.

Errors None. It returns false for anything it cannot vouch for, including older HMAC-SHA256 receipts. Only the issuing deployment can check those, through POST /sdk/v1/receipts/verify.

const keys = await client.publicKeys();
const pack = await client.exportSubject('usr_8f2K1xQz', 'USER_ID');

for (const signed of pack.receipts) {
  console.log(signed.receipt.consentId, verifyReceipt(signed, keys));
}

canonicalize()#

Returns the exact string a receipt signature covers.

Returns string: JSON with the keys sorted at every depth and undefined values dropped.

Errors None.

const signedText = canonicalize(signed.receipt);

You need it only to check a signature with your own code.

Types#

ConsentCookie#

The cookie formats are in Cookies and browser storage. SignedReceipt and Jwk are in Types.

Constants#