euredact 0.6.0 → 0.7.0

package/NOTICE

@@ -0,0 +1,11 @@
+euredact
+Copyright the euredact authors. Licensed under the Apache License 2.0;
+see LICENSE.
+
+This package bundles BIC6 prefixes derived from the BIC/LEI Mapping Table,
+published by GLEIF (https://www.gleif.org) and developed by SWIFT, used
+under the BIC/LEI Mapping Table License Agreement:
+
+SWIFT © and database rights September 2026. All rights reserved.
+This Mapping Table has been developed by SWIFT. Any use of the Mapping Table, in whole or in part, is subject to the BIC/LEI Mapping Table License Agreement as published with the Mapping Table available on GLEIF's website.
+The Mapping Table is updated monthly. For the latest BIC information and updates, always refer to www.swift.com/bic .

package/README.md

@@ -34,7 +34,7 @@ console.log(result.detections);
 ## Features
 
 - **31 European countries** with country-specific patterns
-- **41 PII entity types** (30 from the rules engine, 11 from the
+- **40 PII entity types** (30 from the rules engine, 10 from the
   [cloud tier](#cloud-tier)): national IDs, IBANs, phone numbers, email, VAT
   numbers, license plates, credit cards, BIC/SWIFT, VIN, IMEI, GPS coordinates,
   UUIDs, social handles, IP/IPv6, MAC addresses, secrets/API keys, and more
@@ -114,6 +114,7 @@ interface RedactOptions {
   allowlistDomains?: string[] | null; // domains never redacted (EMAIL/URL)
   detectDates?: boolean;            // include DOB / date of death
   cache?: boolean;                  // reuse results for identical input
+  idempotencyKey?: string;          // mode: "cloud" only; see the table below
 }
 ```
 
@@ -141,6 +142,7 @@ interface RedactOptions {
 | Parameter | Default | Description |
 |---|---|---|
 | `mode` | `"rules"` | `"rules"` runs locally and synchronously. `"cloud"` must go through [`redactAsync()`](#redactasynctext-options) — `redact()` is synchronous and a network call cannot be. See [Cloud tier](#cloud-tier). |
+| `idempotencyKey` | generated | `mode: "cloud"` only (through `redactAsync`): sent as the request's `Idempotency-Key`, so the same key returns the same job instead of running and billing the document again. Throws in rules mode. See [What the service said](#what-the-service-said-resultcloud). |
 | `context` | `null` | Share country evidence across the chunks of one document. Pass the same `DocumentContext` to every chunk. Disables the cache. See [Chunked documents](#chunked-documents). |
 | `chunkOffset` | `0` | Where this chunk starts in the whole document. Only rebases spans recorded in `context`; returned detections stay relative to `text`. |
 | `cache` | `true` | Reuse the result for an identical input and configuration. |
@@ -248,10 +250,18 @@ instance, which is what makes one instance per tenant the right default.
 interface RedactResult {
   redactedText: string;       // The input text with PII replaced
   detections: Detection[];    // All PII spans found
-  source: string;             // Detection backend ("rules")
+  source: string;             // "rules" or "cloud"
   degraded: boolean;          // True if the engine fell back to a simpler mode
+
+  // Country inference — see "Country-independent detection"
+  inferredCountries: Array<[string, number]>; // [country, confidence], strongest first
+  evidence: CountryEvidence[];                // every signal, with the span behind it
+  detectionMode: string;                      // "declared" if countries was passed,
+                                              // "inferred" otherwise
   tokens: Record<string, string>; // token -> original value; only with tokenize: true
   exempted: Exemption[];          // spans the allowlist kept, with the rule that matched
+  cloud?: CloudInfo;              // mode: "cloud" only: job id, model, cost, unplaced
+                                  // findings — see "What the service said"
 }
 ```
 
@@ -265,7 +275,7 @@ interface Detection {
   text: string;                    // The matched substring
   source: DetectionSource;         // "rules" or "cloud"
   country: string | null;          // ISO code or null for shared/custom patterns
-  confidence: string;              // "high" | "medium" | "low" — see below
+  confidence: string | null;       // "high" | "medium" | "low"; null for a cloud-model span — see below
   countryConfidence?: number;      // How strongly the document supports `country`,
                                    // in [0, 1]. 0 means the attribution rests on
                                    // a checksum alone.
@@ -282,6 +292,7 @@ about whether the span is masked — every detection is, at every level.
 | `"high"` | a pattern matched and, where one exists, its checksum passed |
 | `"medium"` | the type comes from a label touching the span, because no pattern of that type claimed it — `Αρ. Ταυτότητας: 00892341` is a `NATIONAL_ID` although nothing can checksum it |
 | `"low"` | a pattern matched, its checksum *failed*, and the document labels the span as that very type — `Rijksregisternummer: 85.03.19-284.73` is a national number with a bad check digit |
+| `null` | a span the cloud model found (`source` is `cloud`). The model reports no confidence, so none is invented: a model span is not checksum-backed, and filtering on `"high"` keeps rules detections only *(rules-engine#108)* |
 
 Filter on it when you need only checksum-backed detections:
 
@@ -294,24 +305,6 @@ identifier: the shape and the label agree, the check digit does not. Earlier
 versions dropped these, which meant a redaction library printed in full an
 identifier it had recognised and rejected.
 
-#### `RedactResult`
-
-```ts
-interface RedactResult {
-  redactedText: string;
-  detections: Detection[];
-  source: string;
-  degraded: boolean;
-
-  // Country inference — see "Country-independent detection"
-  inferredCountries: Array<[string, number]>; // [country, confidence], strongest first
-  evidence: CountryEvidence[];                // every signal, with the span behind it
-  detectionMode: string;                      // "declared" if countries was passed,
-                                              // "inferred" otherwise
-  tokens: Record<string, string>;             // token -> original value; only with tokenize: true
-}
-```
-
 #### `EntityType`
 
 String enum with all supported PII categories:
@@ -330,10 +323,15 @@ Cloud tier only — the rule engine never emits these, because there is no shape
 to match on. That is precisely why the model exists:
 
 ORGANISATION_NAME JOB_TITLE         MEDICAL_CONDITION SENSITIVE_ATTRIBUTE
-BIOMETRIC_REF     FINANCIAL_AMOUNT  QUASI_IDENTIFIER  CREDENTIAL
-URL
+BIOMETRIC_REF     FINANCIAL_AMOUNT  QUASI_IDENTIFIER  URL
 ```
 
+`SECRET` is the one type for credentials, whichever layer finds them: the rules
+engine's shaped keys and tokens, and the cloud model's prose passwords and
+connection-string secrets, which the service labels `CREDENTIAL`. The SDK
+reports those as `SECRET`, and `CREDENTIAL` remains only as a legacy alias of
+it (rules-engine#111).
+
 `INTERNAL_ID` — an employee, badge or customer number tied to a person — is
 emitted **only** when an explicit label names it (`medarbejdernummer:`,
 `Personalnummer:`, `Employee No:`, `Betriebsstättennr.`, `Badge`). There is no
@@ -420,8 +418,10 @@ const results = await Promise.all(
 );
 ```
 
-Bound that yourself if the batch is large — the service enforces quotas and will
-answer `429`, which the client honours via `Retry-After`.
+Bound that yourself if the batch is large. The service's rate limit answers
+`429`, which the client retries, honouring `Retry-After`, before throwing
+`RateLimitedError`. A `429` for the daily quota throws `QuotaExceededError`
+at once: it will not clear before the day does.
 
 ### Reuse one instance
 
@@ -473,6 +473,11 @@ result.detections.map(d => [d.entityType, d.text]);
 // [["PERSON_NAME", "Bas Verhoeven"], ["PHONE", "+32 ..."]]
 ```
 
+The endpoint defaults to `https://api.euredact.dev`; `baseUrl` (or
+`EUREDACT_BASE_URL`) overrides it. It must be `https://`: plain `http://` is
+refused except to `localhost`, `127.0.0.1` or `::1`, so the key and the text
+never travel unencrypted.
+
 **`redact()` is synchronous and cannot serve the cloud tier**, so
 `redact(text, { mode: "cloud" })` throws and names `redactAsync`. It never
 falls back to rules-only output: a caller who believes names and diagnoses were
@@ -590,6 +595,340 @@ either, no hosted model can help; run one yourself against
 `local.redactedText`.
 
 
+### What the service said: `result.cloud`
+
+A cloud result carries `cloud`, what the service reported beside the spans;
+it is absent on a rules-only result.
+
+```ts
+const result = await redactAsync(text, {
+  countries: ["BE"], mode: "cloud", idempotencyKey: "invoice-2291-v1",
+});
+result.cloud?.jobId;         // support, Jobs.retrieve, replays
+result.cloud?.modelVersion;  // the model that answered; null when only rules ran
+for (const item of result.cloud?.unlocated ?? []) console.log(item.entityType, item.text);
+const usage = result.cloud?.usage;
+if (usage) {
+  const { tokens, billingRate, credits, factors } = usage;
+  for (const f of factors) console.log(f.code, f.types ?? "", f.detail);
+}
+```
+
+- **`idempotencyKey`** is sent as the request's `Idempotency-Key`: the same key
+  returns the same job instead of running and billing the document again. One
+  is generated per call when omitted. It applies to `mode: "cloud"` only.
+- **`usage`** is the total the request was charged and the reasons for it, never
+  a cost per step. `credits` is `round(tokens × billingRate)`, the formula the
+  service debits by. The factor codes are `rules_only`, `document_length`,
+  `instructions`, `dense_document`, `special_category_check` (with the `types`
+  that triggered it), `long_document` and `batch_rate`; a code added later
+  still arrives, as its string. Absent when the service does not report it or
+  reported it malformed: a cost report never fails a redaction.
+- **`unlocated`** lists what the model found but could not match to a position
+  in the text it was sent. Nothing was masked for these.
+- **Batch documents** carry `modelVersion` and `unlocated`; no `jobId` or
+  `usage`, which belong to the batch (`batch.tokens`, `batch.creditsCharged`,
+  `batch.billingRate`).
+
+All four types are exported from `euredact`:
+
+```ts
+interface CloudInfo {
+  jobId: string | null;          // null for a batch document
+  modelVersion: string | null;   // null when only rules ran
+  usage?: Usage;                 // absent from older services, batch documents, or a malformed block
+  unlocated: Unlocated[];
+}
+
+interface Unlocated {
+  text: string;                  // what the model reported
+  entityType: EntityType | string; // e.g. "PERSON_NAME"; unknown types stay strings
+}
+
+interface Usage {
+  tokens: number;                // every model call the document triggered
+  billingRate: number;           // 1, or e.g. 0.75 for a batch
+  credits: number;               // round(tokens * billingRate): what was debited
+  factors: UsageFactor[];
+}
+
+interface UsageFactor {
+  code: string;                  // see the list above; new codes arrive as strings
+  detail: string;                // one sentence from the service ("" if none)
+  types?: string[];              // special_category_check only
+}
+```
+
+**Retrying safely.** Pass your own `idempotencyKey` when your code may send the
+same document twice: after a timeout of your own, from a retried queue message
+or a restarted worker. Derive it from something stable (an invoice number plus
+a version), not from a random value per attempt. A replay returns the same
+`result.cloud.jobId` and is not billed again.
+
+### Account, past jobs and the batch list
+
+Everything an API key may do on the service is reachable from the SDK. What
+needs a signed-in person (logging in, minting keys, settings, members, terms)
+is not, because a key cannot do it. Every call returns a `Promise`.
+
+| Call | Service endpoint | Resolves to |
+|---|---|---|
+| `new Account().summary()` | `GET /v1/account` | `AccountSummary` |
+| `new Account().credits()` | `GET /v1/account/credits` | `Credits` |
+| `new Account().creditHistory(limit = 50)` | `GET /v1/account/credits/history` | `CreditEntry[]`, newest first; `limit` 1–500 |
+| `new Account().usage(days = 30)` | `GET /v1/account/usage` | `UsageDay[]` |
+| `new Account().usageByKey(days = 30)` | `GET /v1/account/usage/by-key` | `KeyUsage[]` |
+| `new Account().keys()` | `GET /v1/account/keys` | `ApiKey[]` |
+| `new Account().revokeKey(keyId)` | `POST /v1/account/keys/{id}/revoke` | `KeyRevocation` |
+| `new Jobs().retrieve(jobId)` | `GET /v1/jobs/{id}` | `Job` |
+| `new Batches().list(limit = 20)` | `GET /v1/batches` | `Batch[]`, newest first; `limit` 1–100 |
+
+```ts
+import { Account, Batches, Jobs } from "euredact";
+
+const account = new Account();
+const summary = await account.summary();
+if (summary.quotaRemaining !== null && summary.quotaRemaining < 100) {
+  console.log(`${summary.quotaRemaining} documents left today`);
+}
+console.log((await account.credits()).balance);
+for (const day of await account.usage(7)) console.log(day.day, day.documents, day.tokens);
+for (const key of await account.keys()) console.log(key.id, key.name, key.active, key.lastUsedAt);
+
+const job = await new Jobs().retrieve("job-7f3a…");
+if (job.result) console.log(job.result.redactedText);
+
+for (const batch of await new Batches().list(20)) {
+  console.log(batch.id, batch.status, batch.documents, batch.creditsCharged);
+}
+```
+
+#### Creating the clients
+
+`Account` and `Jobs` read the configuration `configure()` set (or
+`EUREDACT_API_KEY`). Both take two optional arguments:
+`new Account(config?, { fetchImpl? })`. `config` is a `CloudConfig` of its own,
+for a second key or another endpoint: a plain object with `apiKey`, `baseUrl`,
+`timeoutMs`, `pollTimeoutMs`, `maxRetries` and `headers`, checked for an
+`https://` base URL like `configure()` does; `fetchImpl` replaces the platform `fetch`,
+for a proxy or a mock in your tests. (`Batches` takes the same two inside its
+options object: `new Batches({ config, fetchImpl })`.) There is nothing to close.
+They need a global `fetch`: Node 18+, or a browser, or pass `fetchImpl`.
+
+#### What each call resolves to
+
+Each value has `raw`, the service's JSON as received, so a field the SDK does
+not type yet is still reachable; every field is `null` when the service left
+it out or sent the wrong type, rather than the call failing.
+
+```ts
+interface AccountSummary {
+  tenantId: string | null; tenantName: string | null; active: boolean | null;
+  memberSince: string | null;        // ISO date
+  role: string | null;
+  retentionMode: string | null;      // "ttl", or "none": text discarded on delivery
+  payloadTtlHours: number | null;    // 0 under "none"
+  documentsToday: number | null; documentsThisMonth: number | null;
+  tokensThisMonth: number | null; failures24h: number | null;
+  dailyQuota: number | null;         // null: no daily quota on this account
+  quotaRemaining: number | null;
+  activeKeys: number | null;
+  batchesAvailable: boolean | null;  // batches need retention ("ttl")
+  raw: Record<string, unknown>;
+}
+interface Credits { balance: number | null; granted: number | null; spent: number | null;
+                    unit: string | null /* "tokens" */; raw: Record<string, unknown> }
+interface CreditEntry {              // rolled up per minute, reason and direction
+  at: string | null; delta: number | null /* negative for a debit */;
+  reason: string | null; count: number | null; jobId: string | null; sourceRef: string | null;
+  raw: Record<string, unknown>;
+}
+interface UsageDay { day: string | null; documents: number | null; tokens: number | null;
+                     failures: number | null; rulesOnly: number | null; raw: Record<string, unknown> }
+interface KeyUsage {                 // the busiest keys one by one; the rest in one entry, keyId null
+  keyId: number | null; name: string | null;
+  documents: number | null; tokens: number | null; failures: number | null;
+  series: UsageDay[]; raw: Record<string, unknown>;
+}
+interface ApiKey {                   // never the secret: shown once, when minted
+  id: number | null; name: string | null; createdBy: string | null;
+  createdAt: string | null; lastUsedAt: string | null; revokedAt: string | null;
+  active: boolean | null; raw: Record<string, unknown>;
+}
+interface KeyRevocation {
+  id: number | null; keysRemaining: number | null;
+  lockedOut: boolean | null;         // true: no active key left; mint one in the console
+  selfRevoked: boolean | null;       // true: you revoked the key this client uses
+  raw: Record<string, unknown>;
+}
+interface Job {
+  jobId: string;
+  status: string;                    // "queued", "running" or "succeeded"
+  createdAt: string | null;
+  result: RedactResult | null;       // set once succeeded
+  raw: Record<string, unknown>;
+}
+```
+
+`Batch` gained four fields beside `id`, `status`, `counts` and the timestamps:
+`documents`, `tokens` (`{ prompt, completion }`), `creditsCharged` and
+`billingRate` (e.g. `0.75`).
+
+#### Retrieving a job
+
+`redactAsync(text, { mode: "cloud" })` already waits for its job, polling past
+the service's synchronous window, so most code never needs `Jobs`. It is for
+support and audits (look up `result.cloud.jobId` later) and for a job the
+client gave up polling on (`pollTimeoutMs`), which may still finish.
+
+A failed or rejected job throws (`CloudError` with status 502, `TooLargeError`)
+rather than resolving with a status. The result is over the text the service
+received: under `mode: "cloud"` that is the locally masked text, so its offsets
+and `redactedText` are not your original's. Results are kept for the account's
+retention period (`AccountSummary.payloadTtlHours`), and not at all under
+`retentionMode === "none"`; after that, `ResultExpiredError`.
+
+#### Revoking a key
+
+`revokeKey` is the one write an API key may make, for a key that leaked. It is
+sent once and never retried. Revoking the key the client itself uses succeeds
+and reports `selfRevoked: true`; every later call with it fails with status
+401. When `lockedOut` is `true`, no active key is left and only a person in the
+console can mint one.
+
+#### Handling errors
+
+All errors extend `CloudError`, which carries `status` (the HTTP status, or
+`undefined` for a network failure) and `detail` (the service's JSON detail).
+Test the specific ones first: `RateLimitedError` extends `QuotaExceededError`.
+
+```ts
+import {
+  CloudError, QuotaExceededError, RateLimitedError, TooLargeError, redactAsync,
+} from "euredact";
+
+try {
+  const result = await redactAsync(text, {
+    countries: ["BE"], mode: "cloud", idempotencyKey: `invoice-${invoice.id}-v${invoice.version}`,
+  });
+} catch (err) {
+  if (err instanceof RateLimitedError) {
+    // rate limit still hit after every retry: back off, then retry with the same key
+  } else if (err instanceof QuotaExceededError) {
+    // daily quota used up (err.detail.used, err.detail.limit): wait for tomorrow
+  } else if (err instanceof TooLargeError) {
+    // over the input cap: split the document and send the parts
+  } else if (err instanceof CloudError) {
+    // anything else; err.status says what
+  } else {
+    throw err;
+  }
+}
+```
+
+| Error | Status | When | Retried by the SDK |
+|---|---|---|---|
+| `NotConfiguredError` | — | no API key configured, or no global `fetch` | no |
+| `CloudError` | 401 | the key is wrong or revoked | no |
+| `CloudError` | 403 | the service refused the call. Account calls are accepted with an API key while the service does not require a browser `Origin`; if that changes they answer 403 | no |
+| `CloudError` | 403 | `Batches.create` on a workspace without retention: `detail.code === "retention_required"` (see [Batches](#batches)) | no |
+| `NotFoundError` | 404 | no such job, batch or key — or another account's; also every batch call, `list()` included, while batches are not enabled on the service (`batches_not_enabled`) | no |
+| `CloudError` | 409 | `revokeKey` on a key already revoked | no |
+| `ResultExpiredError` | 410 | the job's result is past retention | no |
+| `TooLargeError` | 413 | the document is over the input cap; also a rejected job | no |
+| `QuotaExceededError` | 429 | the daily document quota is used up | **no**: it will not clear before the day does |
+| `RateLimitedError` | 429 | the edge's rate limit, still hit after every retry | yes, `maxRetries` times with backoff |
+| `CloudError` | 5xx, `undefined` | the service or the network failed | yes for reads and `redactAsync`; never for `revokeKey` |
+
+`NotFoundError`, `ResultExpiredError` and `RateLimitedError` are exported from
+`euredact` alongside the others.
+
+**Availability:** like the rest of the cloud tier, these calls are in private
+alpha, and the response shapes may still change between releases. The batch
+calls, `list()` included, answer `NotFoundError` until batches are enabled on
+the service (see [Batches](#batches)).
+
+### Batches
+
+> **Availability:** private alpha, like the rest of the cloud tier. Batches
+> need **retention** on the workspace (see below); while batches are not
+> enabled on the service, every batch call answers `NotFoundError`
+> (`batches_not_enabled`).
+
+A batch hands up to 5,000 documents to the cloud tier and collects the answers
+within 24 hours, at a lower price and without your plan's concurrency limit.
+It keeps the same promise as `mode: "cloud"`: each document is masked **on
+your machine**, and only the masked text is uploaded. What is needed to map the
+answers back stays in a **local batch file**, `~/.euredact/batches/<batchId>.json`
+(directory `0700`, file `0600`): the originals, their local detections and a
+SHA-256 of the masked text sent. The file format is shared with the Python SDK,
+so a batch created by one can be resolved by the other.
+
+```ts
+import { configure, Batches } from "euredact";
+
+configure({ apiKey: "erk_..." });
+const batches = new Batches();
+const batch = await batches.create([
+  { customId: "invoice-2291", text: invoiceText, countries: ["BE"] },
+  { customId: "memo-17", text: memoText, countries: ["NL"] },
+]);
+
+// Later, possibly in another process:
+const outcome = await batches.results(batch.id);
+if (outcome.status === "resolved") {
+  for (const [customId, doc] of Object.entries(outcome.documents)) {
+    console.log(customId, doc.ok ? doc.result!.redactedText : `${doc.error}: ${doc.message}`);
+  }
+}
+```
+
+**Batches need retention.** The service holds each document until it is
+processed and each result until you fetch it, so a workspace that erases
+documents on delivery (`retentionMode === "none"`, or 0 hours of retention)
+cannot create one. `create()` then throws `CloudError` with status 403 and
+`detail.code === "retention_required"`, before anything is uploaded or written
+locally. The workspace owner turns retention on in the console, on the
+**Account** tab. To check first:
+
+```ts
+import { Account, CloudError } from "euredact";
+
+if (!(await new Account().summary()).batchesAvailable) {
+  // no retention on this workspace: send the documents with mode: "cloud"
+}
+
+try {
+  await batches.create(documents);
+} catch (err) {
+  if (err instanceof CloudError && err.status === 403 && err.detail?.code === "retention_required") {
+    // ask the workspace owner to turn retention on
+  }
+  throw err;
+}
+```
+
+- **`results()`** returns `not_ended` while the batch runs and changes nothing.
+  Once it has ended it maps every document, wipes the originals and leaves a
+  text-free receipt; a second call returns `already_resolved`.
+- **Integrity.** Each masked text is rebuilt from the file and must match the
+  hash the gateway reports before a span is placed. An edited file, a missing
+  entry or no file is an error for that document (`local_mismatch`,
+  `missing_local_entry`), never the masked text passed off as a result.
+- **`pending()`**, **`retrieve(id)`**, **`cancel(id)`** (the file stays until
+  the finished documents are mapped) and **`purge(id)`**. Receipts and
+  unmapped files are cleaned up once the gateway's results expire.
+- **In a browser** there is no filesystem: pass `store`, any object with async
+  `read`, `write`, `delete` and `list`. In Node, `batchDir` moves the
+  directory. `cipher` (`encrypt`/`decrypt`) encrypts the file at rest with a
+  key you hold.
+- **Limits** checked before anything is masked or uploaded: 5,000 documents,
+  unique `customId`s of 1-64 characters from `A-Z a-z 0-9 _ . : -` (the
+  gateway's rule, exported as `CUSTOM_ID`), one country each, a 128 MB body. The 5,000-token limit
+  per document is **not** checked by the SDK: it is counted by the model's
+  tokenizer on the gateway. A document over it comes back as `too_long`, whose
+  message says so; split it and submit the parts.
+
 ## `NAME` is now `PERSON_NAME`
 
 The canonical type name is `PERSON_NAME`; `NAME` is a legacy alias, exactly as
@@ -802,14 +1141,23 @@ BIC is the only bank identifier here with **no check digit**, and characters
 | Stage | Condition | Result |
 |---|---|---|
 | Gate 0 | the token also occurs as an ordinary lowercase word in the same document | never emitted |
-| Tier 1 | registry hit on the BIC6 institution+country prefix | emitted |
+| Tier 1 | registry hit on the BIC6 institution+country prefix (your registry, or the bundled seed of major banks) | emitted |
 | Gate 2 | heading / shouted-word shape | never emitted |
-| Tier 2 | `BIC`/`SWIFT` keyword, an IBAN, or a bank block in the enclosing line, record or paragraph | emitted |
+| Tier 2 | `BIC`/`SWIFT` keyword, an IBAN, or a bank block in the enclosing line, record or paragraph | emitted — but a **letters-only** code (`BETALING`, `HOFFMANN`), unless the bundled GLEIF mapping knows the institution, also needs a `BIC`/`SWIFT` label touching it |
 | — | none of the above | never emitted |
 
-The package bundles **no licensed BIC data** — only a small seed list of BIC6
-prefixes compiled from publicly published bank data. Deployments holding a
-licensed directory install it at startup:
+The package bundles about **10,400 BIC6 prefixes** for the 31 supported countries,
+derived from the [GLEIF BIC-to-LEI mapping](https://www.gleif.org/en/lei-data/lei-mapping/download-bic-to-lei-relationship-files),
+which SWIFT develops and licenses for redistribution under the BIC/LEI Mapping
+Table License Agreement; its required notice is in `NOTICE`. They tell a real
+bank from an ordinary word next to an IBAN, but do not by themselves license a
+code in bare prose: with that many real prefixes, some words begin with one
+(`DERNIERS` → `DERN`+`IE`, an Irish institution). `scripts/refresh_bic_registry.py`
+regenerates the list; GLEIF publishes the mapping monthly.
+
+The complete SWIFTRef BIC Directory is a commercial product and is not
+bundled. Deployments holding it install it at startup, where it works like the
+seed — a hit is emitted without context:
 
 ```ts
 import { setBicRegistry } from "euredact";
@@ -819,10 +1167,10 @@ setBicRegistry(bic => myDirectory.has(bic));          // membership callable
 setBicRegistry(null);                                 // remove
 ```
 
-The registry is an **accept** signal, never a filter: a code missing from it
-falls through to the context gate and is still detected when banking context is
-present. A stale list costs a little recall on bare, contextless BICs — it
-never causes a leak. Annual review is sufficient.
+The registry is mostly an **accept** signal: a code missing from it falls
+through to the context gate and is still detected when banking context is
+present — except a letters-only code, the only shape an ordinary word can take,
+which then also needs a `BIC`/`SWIFT` label touching it (rules-engine#57).
 
 ## `IBAN` is now `BANK_ACCOUNT`
 
@@ -996,8 +1344,8 @@ and two tokenized documents never reveal that they share a value. That is the
 opposite retention model from `referentialIntegrity`, which is why the two
 cannot be combined. `redactBatch` tokenizes each text on its own.
 
-A token is `TYPE_` plus four characters from `ABCDEFGHJKLMNPQRSTUVWXYZ23456789`
-(no vowels, no `0`/`1`/`I`/`O`). Tokens are kept clear of any token-shaped
+A token is `TYPE_` plus four characters from `BCDFGHJKLMNPQRSTVWXZ23456789`
+(no vowels or `Y`, no `0`/`1`/`I`/`O`), about 615,000 suffixes. Tokens are kept clear of any token-shaped
 string already in the document, so an LLM's reply to a tokenized prompt can
 itself be redacted without `restore()` putting the wrong value back.
 `restore()` replaces every occurrence, including a token an LLM glued to other
@@ -1175,11 +1523,12 @@ bundler, edge-runtime and Deno compatibility — would buy nothing.
 
 | Package | |
 |---|---:|
-| Tarball | 150 kB |
-| Unpacked | 629 kB |
+| Tarball | 232 kB |
+| Unpacked | 817 kB |
 | Runtime dependencies | **0** |
 
-Measured with `npm pack --dry-run` at 0.5.1. A stale duplicate of this section
+Measured with `npm pack --dry-run` with the bundled BIC prefix list, which
+accounts for about 60 kB of the tarball (shipped in both the ESM and CJS builds). A stale duplicate of this section
 previously quoted 0.02 ms and 86 KB; both were wrong, and the figures above are
 the measured ones.
 
@@ -1189,6 +1538,21 @@ the measured ones.
 const { redact } = require("euredact");
 ```
 
+## Browsers
+
+The package bundles for a page as published. Its only platform dependency is a
+SHA-256 digest (the result-cache key) and a random index (token suffixes); on
+Node both come from `node:crypto`, and a bundler targeting the browser (esbuild,
+webpack, Rollup, Vite) follows the `browser` field in `package.json` to a build
+that uses `crypto.getRandomValues` and a synchronous SHA-256 of its own, checked
+against `node:crypto` byte for byte. `redact` runs entirely in the page, and so
+does the local half of `redactAsync({ mode: "cloud" })`: only the masked text
+leaves it.
+
+```js
+import { redact } from "euredact";   // esbuild --platform=browser, webpack, Vite
+```
+
 ## License
 
 Apache-2.0

package/dist/cjs/cache.js

@@ -2,7 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ResultCache = void 0;
 exports.resultChars = resultChars;
-const node_crypto_1 = require("node:crypto");
+const platform_js_1 = require("./platform.js");
 // Default ceiling on retained characters, not entries. A count-only cap of
 // 1024 entries says nothing about memory: 1024 cached 1 MB documents is a
 // gigabyte of PII-bearing text held live. ~16M characters is a few tens of MB.
@@ -37,13 +37,7 @@ class ResultCache {
         // deployment an attacker who can guess a victim's document could submit a
         // same-length colliding one and be served the victim's cached result,
         // detections and raw matched PII included.
-        return (0, node_crypto_1.createHash)("sha256")
-            .update(text)
-            .update("|")
-            .update(sorted.join("|"))
-            .update("|")
-            .update(mode)
-            .digest("hex");
+        return (0, platform_js_1.sha256Hex)([text, "|", sorted.join("|"), "|", mode]);
     }
     get(key) {
         if (!this.enabled)