openlinktoken 2.0.0__py3-none-any.whl

openlinktoken/tokentransformer/jwe_match_token_formatter.py

@@ -0,0 +1,128 @@
+# SPDX-License-Identifier: MIT
+"""
+JWE Match Token Formatter for Open Link Token V1 format.
+"""
+
+import base64
+import json
+import time
+from typing import Optional, Union
+
+from jwcrypto import jwe, jwk
+
+from openlinktoken.tokentransformer.match_token_constants import (
+    HEADER_KEY_ALGORITHM,
+    HEADER_KEY_ENCRYPTION,
+    HEADER_KEY_KEY_ID,
+    HEADER_KEY_TYPE,
+    PAYLOAD_KEY_HASH_ALGORITHM,
+    PAYLOAD_KEY_ISSUED_AT,
+    PAYLOAD_KEY_ISSUER,
+    PAYLOAD_KEY_MAC_ALGORITHM,
+    PAYLOAD_KEY_PPID,
+    PAYLOAD_KEY_RING_ID,
+    PAYLOAD_KEY_RULE_ID,
+    TOKEN_TYPE,
+    V1_TOKEN_PREFIX,
+)
+from openlinktoken.tokentransformer.token_transformer import TokenTransformer
+
+
+class JweMatchTokenFormatter(TokenTransformer):
+    """
+    Formats tokens in the JWE-based match token format (olt.V1.<JWE>).
+
+    This formatter wraps the privacy-protected identifier (PPID) in a
+    self-contained JWE structure with all necessary metadata for versioning
+    and cryptographic agility.
+
+    See RFC 7516 - JSON Web Encryption (JWE)
+    """
+
+    def __init__(self, encryption_key: Union[str, bytes], ring_id: str, rule_id: str, issuer: Optional[str] = None):
+        """
+        Initialize the JWE match token formatter.
+
+        Accepts either a ``str`` (UTF-8 encoded; must encode to exactly 32 bytes) or
+        raw ``bytes`` (must be exactly 32 bytes) for the encryption key.
+
+        Args:
+            encryption_key: The encryption key (must be exactly 32 bytes for AES-256).
+            ring_id: The ring identifier for key management.
+            rule_id: The token rule identifier (e.g., "T1", "T2", etc.).
+            issuer: The issuer identifier (optional, defaults to "org.openlinktoken").
+
+        Raises:
+            ValueError: If encryption_key, ring_id, or rule_id are invalid.
+        """
+        if isinstance(encryption_key, bytes):
+            key_bytes = encryption_key
+        else:
+            key_bytes = encryption_key.encode("utf-8") if encryption_key else b""
+
+        if not key_bytes or len(key_bytes) != 32:
+            raise ValueError("Encryption key must be exactly 32 bytes (256 bits)")
+        if not ring_id:
+            raise ValueError("Ring ID must not be None or empty")
+        if not rule_id:
+            raise ValueError("Rule ID must not be None or empty")
+
+        self.ring_id = ring_id
+        self.rule_id = rule_id
+        self.issuer = issuer if issuer else "org.openlinktoken"
+
+        # Create JWK from the encryption key - needs to be base64url-encoded
+        key_b64 = base64.urlsafe_b64encode(key_bytes).decode("utf-8").rstrip("=")
+        self.jwk_key = jwk.JWK(kty="oct", k=key_b64)
+
+    def transform(self, token: str) -> str:
+        """
+        Transform a token (PPID) into the JWE match token format.
+
+        The input token should be the base64-encoded HMAC output from previous transformers.
+        This method wraps it in a JWE structure with metadata and prepends the "olt.V1." prefix.
+
+        Args:
+            token: The privacy-protected identifier (PPID) to wrap in JWE format
+
+        Returns:
+            The formatted match token: olt.V1.<JWE compact serialization>
+
+        Raises:
+            Exception: If JWE encryption or serialization fails
+        """
+        if not token:
+            # Return as-is for blank tokens
+            return token
+
+        try:
+            # Build the JWE payload with metadata
+            payload = {
+                PAYLOAD_KEY_RULE_ID: self.rule_id,
+                PAYLOAD_KEY_HASH_ALGORITHM: "SHA-256",
+                PAYLOAD_KEY_MAC_ALGORITHM: "HS256",
+                PAYLOAD_KEY_PPID: [token],  # PPID as an array (single element for hash-based tokens)
+                PAYLOAD_KEY_RING_ID: self.ring_id,
+                PAYLOAD_KEY_ISSUER: self.issuer,
+                PAYLOAD_KEY_ISSUED_AT: int(time.time()),
+            }
+
+            # Create JWE header with algorithm and encryption method
+            protected_header = {
+                HEADER_KEY_ALGORITHM: "dir",  # Direct encryption (key used directly)
+                HEADER_KEY_ENCRYPTION: "A256GCM",  # AES-256-GCM encryption
+                HEADER_KEY_TYPE: TOKEN_TYPE,
+                HEADER_KEY_KEY_ID: self.ring_id,
+            }
+
+            # Create JWE object
+            jwe_token = jwe.JWE(
+                plaintext=json.dumps(payload).encode("utf-8"), recipient=self.jwk_key, protected=protected_header
+            )
+
+            # Serialize to compact form and prepend the olt.V1. prefix
+            jwe_compact = jwe_token.serialize(compact=True)
+            return V1_TOKEN_PREFIX + jwe_compact
+
+        except Exception as e:
+            raise Exception(f"JWE token generation failed for rule {self.rule_id}: {str(e)}")

openlinktoken/tokentransformer/match_token_constants.py

@@ -0,0 +1,57 @@
+"""Shared constants for match token formatting and parsing."""
+
+# Canonical prefix for version 1 match tokens.
+V1_TOKEN_PREFIX = "olt.V1."
+
+# Prefixes accepted by readers that consume JWE-wrapped V1 tokens.
+SUPPORTED_V1_TOKEN_PREFIXES = (V1_TOKEN_PREFIX,)
+
+# Token type value used in the protected JWE header.
+TOKEN_TYPE = "match-token"
+
+# Payload key for token rule identifier.
+PAYLOAD_KEY_RULE_ID = "rlid"
+
+# Payload key for hash algorithm metadata.
+PAYLOAD_KEY_HASH_ALGORITHM = "hash_alg"
+
+# Payload key for MAC algorithm metadata.
+PAYLOAD_KEY_MAC_ALGORITHM = "mac_alg"
+
+# Payload key for PPID values.
+PAYLOAD_KEY_PPID = "ppid"
+
+# Payload key for ring identifier.
+PAYLOAD_KEY_RING_ID = "rid"
+
+# Payload key for issuer identifier.
+PAYLOAD_KEY_ISSUER = "iss"
+
+# Payload key for issued-at UNIX timestamp.
+PAYLOAD_KEY_ISSUED_AT = "iat"
+
+# Protected header key for JOSE algorithm.
+HEADER_KEY_ALGORITHM = "alg"
+
+# Protected header key for content encryption algorithm.
+HEADER_KEY_ENCRYPTION = "enc"
+
+# Protected header key for token type.
+HEADER_KEY_TYPE = "typ"
+
+# Protected header key for key identifier.
+HEADER_KEY_KEY_ID = "kid"
+
+
+def is_supported_v1_token(token: str) -> bool:
+    """Return True when the token starts with a recognized V1 JWE prefix."""
+    return any(token.startswith(prefix) for prefix in SUPPORTED_V1_TOKEN_PREFIXES)
+
+
+def strip_supported_v1_token_prefix(token: str) -> str:
+    """Strip the recognized V1 JWE prefix from a token and return the JWE body."""
+    for prefix in SUPPORTED_V1_TOKEN_PREFIXES:
+        if token.startswith(prefix):
+            return token[len(prefix) :]
+
+    raise ValueError("Token does not start with a supported V1 prefix")

openlinktoken/tokentransformer/no_operation_token_transformer.py

@@ -0,0 +1,24 @@
+# SPDX-License-Identifier: MIT
+
+from openlinktoken.tokentransformer.token_transformer import TokenTransformer
+
+
+class NoOperationTokenTransformer(TokenTransformer):
+    """
+    A No Operation token transformer. No transformation is
+    applied whatsoever.
+    """
+
+    def transform(self, token: str) -> str:
+        """
+        No operation token transformer.
+
+        Does not transform the token in any ways.
+
+        Args:
+            token: The token to be transformed.
+
+        Returns:
+            The unchanged token.
+        """
+        return token

openlinktoken/tokentransformer/token_transformer.py

@@ -0,0 +1,22 @@
+# SPDX-License-Identifier: MIT
+
+from abc import ABC, abstractmethod
+
+
+class TokenTransformer(ABC):
+    """A generic interface for the token transformer."""
+
+    @abstractmethod
+    def transform(self, token: str) -> str:
+        """
+        Transforms the token using a token transformation rule/strategy.
+
+        Args:
+            token: The token to be transformed.
+
+        Returns:
+            The transformed token.
+
+        Raises:
+            Exception: Error encountered while transforming the token.
+        """

openlinktoken-2.0.0.dist-info/METADATA

@@ -0,0 +1,21 @@
+Metadata-Version: 2.4
+Name: openlinktoken
+Version: 2.0.0
+Summary: Open Link Token Python core library for record linkage
+Home-page: https://github.com/TruvetaPublic/OpenLinkToken
+Author: Open Link Token Contributors
+Project-URL: Source, https://github.com/TruvetaPublic/OpenLinkToken
+Project-URL: Documentation, https://github.com/TruvetaPublic/OpenLinkToken/blob/main/README.md
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: cryptography==48.0.1
+Requires-Dist: jwcrypto==1.5.7
+Dynamic: author
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: project-url
+Dynamic: requires-python
+Dynamic: summary
+
+Open Link Token Python implementation for record linkage.

openlinktoken-2.0.0.dist-info/RECORD

@@ -0,0 +1,72 @@
+openlinktoken/__init__.py,sha256=srpf_Qj0yHW0mwqElujCL6GO0L79xedSRVYDLEkyNBc,285
+openlinktoken/ec_key_utils.py,sha256=773XoCyL2JNP2MDjpT4RCPG97KxwgVWrb7viNcKwAcw,6951
+openlinktoken/exchange_config.py,sha256=pSOGUeLrqp8GuwEl8zb4aZ-HaXTsWH0aqXSIK1C9I5I,12671
+openlinktoken/exchange_jwe.py,sha256=FMjqDMOIk9dhA6WOXuoEikZS4nIe0Uqk296jmQP79Dc,3984
+openlinktoken/metadata.py,sha256=ZY0bodkz3r87XNxyq_AP3yey1swFh5KV7p9LGyPi4bY,3457
+openlinktoken/attributes/__init__.py,sha256=d4YS_FuWyjpWKyLSd4BkoBVyikO7nUKX4uZFBx9aITI,490
+openlinktoken/attributes/attribute.py,sha256=fvQo6qY4iZqShQd4vxZAxzmuYop7KIP1VwXqWt-9Njk,683
+openlinktoken/attributes/attribute_expression.py,sha256=kj_fAN2iAYrS9zLkRRm_gITEKrNx907Iy9DrAH1WKNY,7645
+openlinktoken/attributes/attribute_loader.py,sha256=eCZg0hIvy6qSRSNoytgryJNe3sWb9Q1VU4WPW4rJ9gQ,2029
+openlinktoken/attributes/base_attribute.py,sha256=PsImVO9JfjHxp9-vPq3rvU78_pm8xyZ6uK-g5MG6om0,1192
+openlinktoken/attributes/combined_attribute.py,sha256=UJgWdQJvKhWZmgc_xvASYnK9wjVPAegAK2Ku_1JnqW4,2372
+openlinktoken/attributes/serializable_attribute.py,sha256=e7Bg0VQPHV3x3LMVJcXSUpVeh-mWsubq-ggujhjK5H4,173
+openlinktoken/attributes/general/__init__.py,sha256=HfaNUQeD-lo3TDl3Fxq6-6k5Lv3UCKQLzUas3uf6JdU,480
+openlinktoken/attributes/general/date_attribute.py,sha256=JdpEkmRZn3hudgSFPpZjIWwsBUaVWvs7j3VVxr6zbKU,3729
+openlinktoken/attributes/general/decimal_attribute.py,sha256=IbdVV8vx0HqYkk-1ZhlINL3IHKaQqACle9kdGQ6a9HE,2970
+openlinktoken/attributes/general/integer_attribute.py,sha256=XQV3tdS760W-a0IKDJ3lgbCgczTLBaGbipLv3H7Ot44,2586
+openlinktoken/attributes/general/record_id_attribute.py,sha256=uUjspCI5odsptjh_YclDFuK2NBoNfLtLC_OoshTFDf0,1158
+openlinktoken/attributes/general/string_attribute.py,sha256=YrofYIREzNWZboyTHTKVipQw2siovfEhDl0DKTmHX8M,1466
+openlinktoken/attributes/general/year_attribute.py,sha256=8BDojLLDuSFpUjwoTzJZ_E7i2WRu21Noya4oL2da5xc,2604
+openlinktoken/attributes/person/__init__.py,sha256=RRHUGb7t5y8GNmtOEbRCwXWPcDjh-h68Dr91k7dOIXk,880
+openlinktoken/attributes/person/age_attribute.py,sha256=iJFdeEW-FKPXAaKOCMrLaHeX4-znbQvYMg4y-yLkIL8,1247
+openlinktoken/attributes/person/birth_date_attribute.py,sha256=33GZJXJkHsW7d1_jQtFHupohvZ108bZCUdMXnGhqdfY,1211
+openlinktoken/attributes/person/birth_year_attribute.py,sha256=CQmexwGmf_gnmZrtzlXyccSd2fVY3CtJxLHTNCNKLHI,1206
+openlinktoken/attributes/person/canadian_postal_code_attribute.py,sha256=VlfeDL0vehbGZXU0N8PmLF2hBpyfGqb5yBl2iD3t3Yk,6721
+openlinktoken/attributes/person/first_name_attribute.py,sha256=M1fo8dtJzJ44pFO2_WTzVoJzuu3kOhM5DQGdlCluJM0,3835
+openlinktoken/attributes/person/last_name_attribute.py,sha256=rb4cRFJIhZ_BiLuQNYir6lcABeqJWF0df-2L4DuaPhI,5753
+openlinktoken/attributes/person/postal_code_attribute.py,sha256=VN7ygip3tcSr_t_r43rrECY9YAPPbZjoFZ6VIEkGXLA,1731
+openlinktoken/attributes/person/sex_attribute.py,sha256=tgWWK4kAfLI4CZbj2t9Q78Oey2Qt8FQqV4KBo409ClY,1426
+openlinktoken/attributes/person/social_security_number_attribute.py,sha256=BkG8oZ-qvshHIDVs1pRyTR4_id_g-r6ODn9dSrCzQo8,4134
+openlinktoken/attributes/person/us_postal_code_attribute.py,sha256=TvJUp3JJUtzmvz_rADdRlO25GqhChYSlxp9VVjlSmKE,3821
+openlinktoken/attributes/utilities/__init__.py,sha256=tBT47qbeiD1jub0RBwiNxjqZvQYZ-9tOpdeekMlbjFo,142
+openlinktoken/attributes/utilities/attribute_utilities.py,sha256=Yl7E6xfMB2wFxHV4G6_NbXwfluTBk2rLwQBzvAc8urk,7392
+openlinktoken/attributes/validation/__init__.py,sha256=moJKBJF89c9U3Gtq-WoAssVXhC-Vz6Yh7_h9RsHQKgM,807
+openlinktoken/attributes/validation/age_range_validator.py,sha256=rWnZgvqoXSaXgLzjvHp-4XFIUlOc6Q2SImyM1qa5-1I,1115
+openlinktoken/attributes/validation/attribute_validator.py,sha256=qxKGRabyj77tSmM-uGseepD5NYpLcbraxi4wmXFQNdg,434
+openlinktoken/attributes/validation/date_range_validator.py,sha256=7hg3nfDSHhUXDK0ZXBNY0SeK-oMfD9EUcFj89_ralsA,3438
+openlinktoken/attributes/validation/not_in_validator.py,sha256=rvrMfyLzI-ueYyj4vyVs1QlmSQrRywp_tnipQ8BCEvA,1485
+openlinktoken/attributes/validation/not_null_or_empty_validator.py,sha256=no2xr_AH-lklB9xEisFFLsJ_on27KpM__9FZU_4X-6Q,630
+openlinktoken/attributes/validation/not_starts_with_validator.py,sha256=vPllw0ElioQ55hAo9tSMsYSI62q3DOtfD9zuvxaYYis,1484
+openlinktoken/attributes/validation/regex_validator.py,sha256=iBgPvIMX1Bmmn6SLyUydEHVzKneN6DdqU7azAsIIhmE,1261
+openlinktoken/attributes/validation/serializable_attribute_validator.py,sha256=4-IdX7qAcUpUypmTHzozjKc4glkb5GqGWiygLsXbTqM,959
+openlinktoken/attributes/validation/year_range_validator.py,sha256=jRjzmydSYrRBB0D205vkDr2YD8ay5heB_Je9ibzUtPY,1311
+openlinktoken/tokens/__init__.py,sha256=29B6pjlkSpwo1pnvGFtodWRMum7UPfFGc7CxD8ASvrg,586
+openlinktoken/tokens/base_token_definition.py,sha256=vnpeVpxvnK4eq1V1Rvw42RgvMf9RpLEYKxppEPp5ZYQ,1235
+openlinktoken/tokens/token.py,sha256=rQ0Vp_OTAp6U3Wn8zbl1qtZfQUBPtJiV3Pxd5s7gJn8,1102
+openlinktoken/tokens/token_definition.py,sha256=gJIFSlM9vS-DE9zkQB6hIhKw7J7IJNqo8SpWtaE91P0,1480
+openlinktoken/tokens/token_generation_exception.py,sha256=OtDPyq59PqF_VjQNJKiAe4tIZmCcY1bZW7X8pukQ8BY,428
+openlinktoken/tokens/token_generator.py,sha256=tfGfcyNXEFH49Cc31-fuoXoRvCW-vdnAreOWHZulMbg,7442
+openlinktoken/tokens/token_generator_result.py,sha256=0P3XYmF1ruV7flMGx1TmTtVFTCUOaLc4hI0PFwpCn0U,944
+openlinktoken/tokens/token_registry.py,sha256=5eDfQbNsGgMEWKRFj_zl0g8lEXi3NRLk0a4WT-JMhsw,1659
+openlinktoken/tokens/definitions/t1_token.py,sha256=IRCDKLTICAk7AybicFBXkeU7tpZptJ3oO-EU8V_KJFM,1444
+openlinktoken/tokens/definitions/t2_token.py,sha256=OVKb24ZauHKudFlg10TWbsO4wmHlPCkY8S0SjMs5u5Q,1468
+openlinktoken/tokens/definitions/t3_token.py,sha256=heOwzGbx1JcBQviR3ib3JzlX0OBkivWSv0ghX6uoAsg,1435
+openlinktoken/tokens/definitions/t4_token.py,sha256=bVHyk853q3j1EKLWc1XFSQFATGnbPlyfD5-4pQBVm3Y,1330
+openlinktoken/tokens/definitions/t5_token.py,sha256=l3gMQfimLEhY7X_0AIroS39hGNSej4T8pY4F-d0mDIY,1289
+openlinktoken/tokens/tokenizer/__init__.py,sha256=4_6iDHljxDNAb5Hjwcyhmemmak_eHGUMxoxAfS_A9TA,273
+openlinktoken/tokens/tokenizer/passthrough_tokenizer.py,sha256=828CmdXEM55oBP4HkBlwNR0M5LhaASaef31z9USds88,1990
+openlinktoken/tokens/tokenizer/sha256_tokenizer.py,sha256=PmdTLYCimj2-tvd47ueMJV_xMF8ZrXdqM4tQoVw1-GE,2045
+openlinktoken/tokens/tokenizer/tokenizer.py,sha256=ScSlP5GdESQlN6wcrFVPJbHWXclTj_j-5CnbMQrUwhM,850
+openlinktoken/tokentransformer/__init__.py,sha256=_BvICwuwJQF2Mo6-BUhaBRrz9VfzYfCO3_Hd3N7ke0Q,1234
+openlinktoken/tokentransformer/decrypt_token_transformer.py,sha256=u3nlGEryTBW7Qtq_CfarFPbuzPgR1TW3dvrfMnvvMQY,3489
+openlinktoken/tokentransformer/encrypt_token_transformer.py,sha256=f2iXfUQrEePS3z_KONp5w7jSephWtIOCuhekxSbVXcY,3177
+openlinktoken/tokentransformer/encryption_constants.py,sha256=3FWc4h2oD_6kw8vItnggcceJ8z_EdW1v8j505xoPvB0,562
+openlinktoken/tokentransformer/hash_token_transformer.py,sha256=4fs8ZrF8qAywX_5GZeZTcDOlWIXWexn1-SUsGYSw6UA,2795
+openlinktoken/tokentransformer/jwe_match_token_formatter.py,sha256=W6jOieN4PNZnC2Gw7wtXsroJQYtnXVFLIIg2u_rrBNE,4711
+openlinktoken/tokentransformer/match_token_constants.py,sha256=YU78uiL4gC1-Nzs50yUALraCJOeJ_OgxnDAOKzyrmVk,1677
+openlinktoken/tokentransformer/no_operation_token_transformer.py,sha256=pbAAafrr3R0A0XMdvmakWNFyIbNLV2AvXWldkrSyCHM,559
+openlinktoken/tokentransformer/token_transformer.py,sha256=i9V0yMay87tXUmvKDE8FdE3sLdTqJD2bUrkpKNB8wrU,522
+openlinktoken-2.0.0.dist-info/METADATA,sha256=fE5ktzFWey6y9bQQfRYD-HIKXKpcOhaK5sn2jstrOYM,722
+openlinktoken-2.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+openlinktoken-2.0.0.dist-info/top_level.txt,sha256=3J1WoaQlJrajzOwqIpHIUPAohdiE74wH_UIkPWMrYoQ,14
+openlinktoken-2.0.0.dist-info/RECORD,,

openlinktoken-2.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

openlinktoken-2.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+openlinktoken