Download the PHP package phox/jev-secrets without Composer

jev-secrets

Replaces names, keys and other secrets in a Jev request with stand-ins before it is sent, and puts the originals back in the answers. For the PHP SDK and the official JavaScript and Python SDKs, or any code that builds the request body itself.

The second line is what Jev sees, with John Smith passed as a value and the rest found by the default patterns. In each replaced word every letter becomes another letter of the same case, vowels stay vowels, digits become digits, and punctuation stays, so a name still reads as a name and an email address as an email address. The same word gets the same stand-in everywhere in the request, including in the questions. The answers come back with the original question ids and choice labels.

This is pseudonymisation, not anonymisation: the mapping is held in memory in order to be able to reverse the process on the way back to the caller.

Contents: What gets replaced · The key · Config · What it does not do · Does it change the answers?

Install

A request of 1000 strings, 500 KB of JSON, takes 0.4-0.5 s in PHP and JavaScript and 1.1-1.4 s in Python; docs/performance.md has the measurements.

Use

With the SDK, wrap the client. Each call takes the values to hide in that request, on top of whatever the config finds:

jev_secrets.typesafe.AsyncSecretClient wraps the async Python client. The wrappers sit above the SDK, not in its transport, because the SDKs log request bodies at debug level before the transport sees them.

Any config option can be changed at call time. scope and dates merge entry by entry; any other option given replaces the configured one:

In JavaScript it is options.overrides, in Python overrides=, and without an SDK the third argument of pseudo().

Without an SDK, rewrite the body yourself and restore the decoded response:

pseudo() is also available as pseudonymise(), pseudonymize() and mask(), and restore() as unmask().

$done->replacements lists what was replaced, as a path into the sent request and the source that found it, without the values themselves.

What gets replaced

The sources, all optional:

secretKeys controls those key names: false for none, a list for exactly those, or {"add": [...], "remove": [...]} to change the default list. Names compare lowercased, ignoring spaces, hyphens and underscores, so member_number covers Member-Number.

Values and terms match case-insensitively, at word boundaries. Their words may be joined by any run of spaces, underscores, hyphens or dots, so Ellen Park is also found in is_from_ellen_park and [email protected]. A value shorter than 2 characters is refused. The value found at a field path is also replaced wherever else it appears in the request.

Names cannot be found by pattern. Pass them as values, list them as terms, or name the fields they're in.

Dates, and numbers the default patterns do not cover, are not replaced by default. Pass one as a value, or name its field, and a number is replaced digit by digit, a date or time moved (below). With dates.detect: true every date and time in the request is moved.

Where two matches overlap they merge, so a value inside an email address takes the rest of the address with it. catalogue/patterns.json holds the patterns and the key names; the PHP, JavaScript and Python implementations read the same file.

What a stand-in looks like

Recorded outputs of the character generator under a fixed key, from catalogue/fixtures.json:

• Letters: each becomes another from the same alphabet and case. With letters: "shape", the default, vowels stay vowels and consonants stay consonants, so the stand-in is pronounceable. Latin, Greek, Cyrillic, Armenian, Georgian, Hebrew, Arabic, Devanagari, Thai, kana, Hangul and CJK are drawn from their own scripts; a letter from any other script becomes an ASCII letter. Accents stay on.
• Digits: with digits: "lower", the default, 0 and 1 stay and every other digit becomes a lower one of at least 1, so an IP address or a version stays valid. A span made only of 0s and 1s, like 10.0.0.1, is drawn under digits: "any" instead.
• Dates and times are moved, not rewritten: every date in the request by the same number of weeks, every time by the same number of minutes, without crossing midnight. Order, intervals and weekdays survive, and the format stays as written, so Monday, 16 March 2026 at 3:40 pm becomes Monday, 12 October 2026 at 11:46 am. dates.order decides whether 03/04/2026 is 3 April (dmy, the default) or 4 March (mdy); a year written first is always year, month, day. With dates.mode: "digits" they get the digit rule instead, which is how the 2024-12-31 23:59 row above was made. docs/dates.md lists the formats.
• Everything else stays: spaces, punctuation, @, ., -, _.

A stand-in is drawn again until it differs from every word already in the request and from every other stand-in. Short numbers under the digit rule can run out of stand-ins and share one; docs/generation.md has the exact rules.

The key

Stand-ins and date offsets are drawn under a key:

With a random key the stand-ins change from call to call. With a fixed one the same request gives the same stand-ins every time, in every implementation. Nothing is stored between calls, so rotating the key costs nothing: calls after the change get different stand-ins. The library reads the process environment, not a .env file; load that the way your framework does.

What is rewritten and restored

A score's legend keys and probability keys are rubric indices and are never restored, nor is any number in the response. A string field in an answer that this library does not know gets word-by-word replacement of the stand-ins.

Config

The same object in PHP, JavaScript and Python. spec/config.schema.json has every option and its default.

allow protects a string from terms, fields, patterns and the defaults; a value passed to a call still replaces it.

When it refuses to send

After rewriting, every original value is looked for again across every string and key under state and questions. If one is still there, the call throws LeakException (LeakError in JavaScript and Python) and nothing is sent. The message names the path and the source, never the value, and suggests the fix for the usual causes: a value in an object key while scope.keys is off, or in the questions while scope.questions is off.

In PHP, a request that cannot be searched is refused too: text that is not valid UTF-8, or a regex that stops at PCRE's backtrack limit (MatchException). Matching cannot say what it missed, so nothing is sent. JavaScript and Python strings are always Unicode, and their regexes have no such limit.

A config that cannot work is refused when it is made: an unknown option, a pattern that does not compile, a term with no letter or digit or shorter than minLength. A value passed to a call is checked the same way when the call is made.

What it does not do

• Find names by itself. Only values, terms and fields hide names.
• Hide shape. A stand-in has the same length, capitals, punctuation and word count as the original, and the same word always gets the same stand-in, so the number of times a name appears is visible.
• Hide every digit. Under the default digit rule 0 and 1 are kept and 2 can only become 1.
• Keep order between numbers. Each number is lowered on its own, so 19 and 22 can come out as 17 and 11, and two short numbers can share a stand-in when the rule leaves no other in range. Dates and times keep their order unless dates.mode is digits.
• Keep a date's relation to the real world. A moved date is up to a year away from the original, so "is this overdue?" against today, "last Friday" or an age written in words no longer line up.
• Catch everything the defaults target. The patterns trade recall for precision: a phone number without a leading + is missed, a version string like 1.2.3.4 reads as an IPv4 address, and about one in ten 12 to 19 digit numbers passes the Luhn check by chance.
• Unlink calls under a fixed key. With a fixed key, from the config or JEV_SECRETS_KEY, a word gets the same stand-in in every call, so whoever receives the requests can tell that two calls mention the same person, and anyone holding the key can test a guessed name against a stand-in. Use a random key unless you need repeatable output.
• Keep an object keyed "0", "1", ... an object in PHP. PHP decodes it, and {}, as a list, so its keys are not rewritten and it is sent as a JSON array. The PHP SDK has the same limit. For the same reason secretKeys: {} means no secret keys in PHP, and no change to the default list in JavaScript and Python.
• Keep numeric-keyed requests identical in JavaScript. JavaScript orders integer-like object keys ascending, and stand-ins that collide are redrawn in walk order.

Does it change the answers?

Over 67 labelled questions on 50 PII-heavy requests (docs/evidence.md):

• The default config got 64 of 67 right in both runs; tags got 58, the plain request 67. The default moved answers least, by 0.05 on average against 0.17 for tags.
• All 16 questions comparing dates or times kept their answers: every date and time moves by the same offset. Names in Chinese, Arabic, Greek and Japanese script made no difference.
• What replacing removes is lost: whether an email domain is a company's, or +44 a UK number.
• Comparing two plain numbers passed as values fails, since the digit rule keeps neither size nor order. Leave out of values any number a question compares.

Documentation

docs/dates.md are the byte-level contract the implementations share. catalogue/fixtures.json holds the cases each must reproduce: php scripts/golden.php records them from the PHP implementation, and the JavaScript and Python suites require the same output.