Python helpers

piedap_consent exports helper functions next to the client. They check webhook signatures, compute proofs, fingerprints and capture hashes, spot skipped imports, and read the consent cookie.

Requirements#

• Python 3.9 or later.
• For verify_webhook(): the endpoint's signing secret, whsec_….
• For identity_proof(): the key's identity secret, idv_….
• For subject_fingerprint() and capture_reference_hash(): the project's fingerprint key, sfk_….

Install#

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

Import the helpers#

from piedap_consent import (
    capture_reference_hash,
    identity_proof,
    is_skipped_import,
    parse_consent_cookie,
    parse_partner_cookie,
    subject_fingerprint,
    verify_webhook,
)

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

Functions#

verify_webhook()#

Checks that a webhook delivery is genuine and recent.

Returns bool: True only when the signature matches the raw body and the timestamp is within the tolerance. Missing or malformed headers give False.

Errors Raises ValueError for an empty secret or a negative tolerance. Both are set-up mistakes, not bad deliveries.

import os

from flask import Flask, abort, request
from piedap_consent import (
    SIGNATURE_HEADER,
    TIMESTAMP_HEADER,
    verify_webhook,
)

app = Flask(__name__)


@app.post("/webhooks/piedap")
def consent_hook():
    if not verify_webhook(
        request.get_data(),
        request.headers.get(SIGNATURE_HEADER),
        request.headers.get(TIMESTAMP_HEADER),
        secret=os.environ["PIEDAP_WEBHOOK_SECRET"],
    ):
        abort(401)
    return "", 204

In Django, pass request.body as the payload. See Verify signatures.

identity_proof()#

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

Returns str: the lower-case hex HMAC-SHA256 of <subject_type>:<subject_id>.

Errors Raises ValueError for any other subject_type and for an empty identity_secret.

import os

from piedap_consent import identity_proof

proof = identity_proof(
    os.environ["PIEDAP_IDENTITY_SECRET"],
    "USER_ID",
    user.id,
)

See Signed-in visitors.

subject_fingerprint()#

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

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

Errors Raises ValueError for an empty fingerprint_key. Here the identifier comes before the type.

import os

from piedap_consent import subject_fingerprint

fingerprint = subject_fingerprint(
    os.environ["PIEDAP_FINGERPRINT_KEY"],
    "usr_8f2K1xQz",
    "USER_ID",
)

See Match events to users.

capture_reference_hash()#

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

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

Errors Raises ValueError for another kind, an empty fingerprint_key, or a reference that is empty or not printable ASCII. Raises TypeError when reference is not a string.

import os

from piedap_consent import capture_reference_hash

agent_ref_hash = capture_reference_hash(
    os.environ["PIEDAP_FINGERPRINT_KEY"],
    "agent",
    "EMP-40213",
)

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

is_skipped_import()#

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

Returns bool: True for a ConsentError with status 409 and a code in SKIPPED_IMPORT_CODES.

Errors None.

from piedap_consent import ConsentError, is_skipped_import

try:
    client.record_consent(**row)
except ConsentError as error:
    if not is_skipped_import(error):
        raise
    skipped.append((row["idempotency_key"], error.code))

See Bring in consent given earlier.

parse_consent_cookie()#

Reads the two cookie values the browser runtime wrote.

Returns a ConsentCookie, or None.

Errors None. A missing or malformed cookie gives None, so a damaged cookie reads as "no answer".

from piedap_consent import (
    COOKIE_NAME,
    PARTNER_COOKIE_NAME,
    parse_consent_cookie,
)

cookie = parse_consent_cookie(
    request.cookies.get(COOKIE_NAME),
    request.cookies.get(PARTNER_COOKIE_NAME),
)

analytics = bool(cookie and cookie.granted("analytics"))
matomo = bool(cookie and cookie.granted("analytics", "matomo"))

The example reads Flask's request.cookies. In Django, use request.COOKIES.

parse_partner_cookie()#

Reads a piedap_partners value on its own.

Returns dict[str, tuple[str, ...]], purpose key to the partner keys the visitor refused, or None.

Errors None. A missing or malformed cookie gives None.

declined = parse_partner_cookie(request.cookies.get(PARTNER_COOKIE_NAME))
print(declined)  # {'analytics': ('matomo', 'plausible')}

Types#

ConsentCookie#

A frozen dataclass.

The cookie formats are in Cookies and browser storage. The models the client returns are in Models.

Constants#