@genn-inc/cluebase-frontend-sdk 0.0.1

package/README.md

@@ -0,0 +1,222 @@
+# @genn-inc/cluebase-frontend-sdk
+
+Cluebase browser ingest SDK.
+
+## Minimal integration
+
+After `pnpm add @genn-inc/cluebase-frontend-sdk`, the intended Next.js integration is:
+
+```ts
+import cluebase from "@genn-inc/cluebase-frontend-sdk";
+
+cluebase.init({
+  endpoint: process.env.NEXT_PUBLIC_CLUEBASE_API_BASE_URL!,
+  projectKey: process.env.NEXT_PUBLIC_CLUEBASE_PROJECT_KEY!,
+});
+
+cluebase.identify(user.id, { name: user.name });
+cluebase.group("organization", organization.id, { name: organization.name });
+```
+
+For Vite, use `import.meta.env.VITE_CLUEBASE_API_BASE_URL` and
+`import.meta.env.VITE_CLUEBASE_PROJECT_KEY`. For React apps that use the
+Create React App env contract, use `process.env.REACT_APP_CLUEBASE_API_BASE_URL`
+and `process.env.REACT_APP_CLUEBASE_PROJECT_KEY`. Other frontend frameworks should
+use the public env names generated by Cluebase setup.
+
+`projectKey` is the public ingest key. The API resolves authoritative
+`tenantId`, `projectId`, and dev/prod `ProjectService` from that key. `endpoint`
+is the Cluebase API base URL. The SDK appends `/api/v1/ingest/browser-tokens` and
+the canonical browser observation batch path internally.
+
+## Responsibility boundary
+
+- SDK captures browser signals and applies local minimization where the signal is obviously high-risk.
+- API ingest privacy gate is authoritative for final allow/deny/unmask policy.
+- Worker-side sanitize is defense-in-depth only.
+- SDK sends `projectKey`, `schemaVersion`, `sdkType`, `sdkVersion`, stable keys, and minimized capture payloads.
+- SDK does **not** authoritatively stamp `tenant_id`, `project_id`, `environment_id`, or final raw-ingest request/response payloads.
+
+The frontend SDK does **not** own final raw-ingest allowlist decisions.
+
+## Default privacy/minimization behavior
+
+The frontend SDK avoids shipping obvious high-risk plaintext and keeps the MVP
+default event surface intentionally narrow.
+
+- `input_change.value` -> local value metadata only
+- `selection_text` -> metadata only
+- raw selector/path -> never serialized; stable key only
+
+Current MVP defaults:
+
+- successful network emits one `request_finished`
+- failed network emits one `request_failed`
+- standard action capture emits `element_clicked`, `form_submitted`,
+  `input_committed`, `toggle_changed`, `selection_committed`,
+  `file_selected`, and `drag_drop_completed`
+- normal batching flushes when the queued payload reaches the 48KB send
+  threshold, every 180 seconds by default, or when the page is
+  leaving
+- event type does not change the delivery rule in MVP
+
+Stable key precedence:
+
+1. `data-testid`
+2. `data-qa`
+3. safe `name`
+4. safe `aria-label`
+5. structural fallback
+
+Cluebase-specific DOM attributes are not part of the MVP stable-key contract.
+Captured stable keys are best-effort evidence, not authoritative business
+meaning.
+
+## Sampling and cost guards
+
+- `sampling.sessionSampleRate` controls whether a session emits normal capture
+- oversized events degrade in stages before final drop:
+  - no raw payload body
+  - metadata/schema only
+  - shell only
+- oversized batches stay below the configured payload hard max
+
+## Flush reliability
+
+The SDK flushes on:
+
+- `visibilitychange` -> `hidden`
+- `pagehide`
+- `beforeunload`
+
+The page-leave flush is best effort. The SDK persists unsent source events in
+`localStorage` and removes them only after the ingest API accepts the batch.
+Lifecycle session URLs strip query strings and hashes before they enter the raw
+SDK event payload.
+
+## Keepalive flush contract
+
+- unload / hidden flush uses authenticated `fetch` with the `keepalive` hint
+- unload flush only sends when a valid browser token is already cached
+- events are not sent through `navigator.sendBeacon`
+
+## Degraded event contract
+
+Downstream ingest must accept these as normal input:
+
+- no raw payload body
+- metadata + schema only
+- shell-only event
+
+## Privacy and PII handling
+
+The SDK applies a layered privacy model:
+
+### 1. Hard-deny: PII / secrets are stripped before transport
+
+The SDK strips a built-in set of property keys **before** the event leaves
+the browser. These keys cannot be unmasked by the delivered privacy policy —
+selecting `body.email` in the Cluebase privacy screen does not bypass the
+hard-deny.
+
+Hard-deny categories (case- and separator-insensitive — `userEmail`,
+`user-email`, `USER_EMAIL`, `email_address` all match):
+
+- Auth credentials: `authorization`, `cookie`, `set-cookie`, `password`,
+  `passwd`, `secret`, `token`, `access_token`, `refresh_token`, `session`,
+  `session_token`, `api_key`, `apikey`, `private_key`
+- PII categories: `email`, `phone`, `credit_card`, `ssn`
+
+This list is a strict superset of the server-side ingest hard-deny
+(`@cluebase/shared` `INGEST_HARD_DENY_KEYS`), enforced by CI parity tests in
+all three SDKs.
+
+### 2. Default-masked: arbitrary values are masked unless allowlisted
+
+Properties that pass the hard-deny gate are still **masked by default**.
+The SDK emits a fingerprint or shape-only digest, not the raw value.
+
+To capture a specific field in plaintext, two things must both be true:
+
+1. The field path is selected in the Cluebase privacy screen. Cluebase delivers that
+   choice to the SDK with the ingest response, and the SDK applies it. This is
+   not an `init` option: until a policy arrives, and whenever the delivered
+   policy cannot be read, every value stays masked.
+2. The same property key appears in the project's server-side
+   project service `observationAnalysisPropertyAllowlist`.
+
+If condition 1 holds but condition 2 does not, the value is stored in
+raw observation storage only — `facts_json.analysisProperties.projected` will
+be empty and the field will not appear in Cluebase's analysis UI.
+
+### 3. Operational consequence: configure server allowlist before launch
+
+Customers who launch without setting `observationAnalysisPropertyAllowlist`
+on their resolved project service will see custom event names land in
+`observation_type` but **no projected properties** in dashboards. The
+raw observation store keeps masked/raw-only evidence for debugging, while
+analysis projection remains empty until the server allowlist includes the
+field. Configure the server allowlist via the Cluebase admin UI or project service
+allowlist API after taking a privacy review of which property names you want to
+project for analytics.
+
+## Architecture boundary
+
+The frontend SDK is a browser wrapper around capture, privacy minimization,
+correlation propagation, and transport. It sends source-signal envelopes such
+as `sdk_source_signal_observed`; the Cluebase backend ingest core performs final
+classification, unknown diagnostic handling, backend request correlation, and
+raw-ingest normalization.
+
+```text
+browser capture / OTel network span
+  -> frontend SDK source-signal envelope
+  -> /api/v1/ingest/browser
+  -> apps/api/src/modules/ingest core
+```
+
+Rules:
+
+- Keep browser code limited to raw facts, correlation context, standard OTel
+  attributes, local minimization, and transport.
+- Do not add frontend-only classification, source-hint strategy, semantic DOM
+  annotations, or custom fallback behavior.
+- Add classifier behavior in the backend ingest core so frontend-originated
+  requests, Node.js, Python, and future SDK wrappers receive the same behavior.
+- Preserve `interaction_id`, `request_span_id`, `request_id`, and `trace_id`
+  whenever they are available. User-action linkage is an ingest contract, not a
+  display-only field.
+
+### Explicit Event Emit: `cluebase.track`
+
+When DOM auto-capture cannot infer the operation (e.g. a custom
+keyboard shortcut, an API-only background sync, or a multi-step UI
+flow), the host app may emit an explicit semantic action:
+
+```ts
+import cluebase from "@genn-inc/cluebase-frontend-sdk";
+
+cluebase.track("report.create", { source: "shortcut", result: "success" });
+```
+
+`cluebase.track` emits a `custom_emitted` event for product actions that are not
+covered by DOM auto-capture. Keep properties privacy-safe and stable; the worker
+derives higher-level semantics downstream. Event names must match
+`^[A-Za-z0-9_.:-]{1,128}$`; invalid names are dropped with a public warning.
+
+### Identity Lifecycle: Organization
+
+The frontend SDK exposes the MVP identity lifecycle APIs that the worker uses to
+preserve anonymous → identified user → organization evidence:
+
+```ts
+cluebase.identify("user_42", { plan: "pro" });
+cluebase.group("organization", "org_3", { name: "Acme Inc." });
+cluebase.reset();
+```
+
+MVP does not expose Cluebase `account` or `workspace` as public group types. If the
+customer product calls its company concept an account, workspace, tenant, or
+team, pass that stable company id as `cluebase.group("organization", ...)`.
+Blank or non-string `identify` user ids and `organization` group ids are
+dropped with a public warning and do not update SDK identity state.

package/dist/_generated/correlation-attribute-keys.d.ts

@@ -0,0 +1,2 @@
+/** 伏せる処理を通しても残す、相関のための属性名。 */
+export declare const CLUEBASE_CORRELATION_ATTRIBUTE_KEYS: ReadonlySet<string>;

package/dist/_generated/correlation-attribute-keys.js

@@ -0,0 +1,33 @@
+// 自動生成です。**手で編集しないでください。**
+//
+// 正本: packages/cluebase-backend-contract/src/delivery/correlation-attribute-keys.v1.json
+// 出し直す: node scripts/generate-shared-contract-tables.mjs
+//
+// 正本を直したらこの file も一緒に commit してください。CI が
+// `node scripts/generate-shared-contract-tables.mjs --check` で照合し、ずれていれば落とします。
+/** 伏せる処理を通しても残す、相関のための属性名。 */
+export const CLUEBASE_CORRELATION_ATTRIBUTE_KEYS = new Set([
+    "cluebase.actor.anonymous_id",
+    "cluebase.actor.user_id",
+    "cluebase.interaction.id",
+    "cluebase.interaction_id",
+    "cluebase.organization.id",
+    "cluebase.organization_id",
+    "cluebase.origin_frontend_interaction.id",
+    "cluebase.parent_request_span_id",
+    "cluebase.parent_span_id",
+    "cluebase.request.id",
+    "cluebase.request_id",
+    "cluebase.request_span_id",
+    "cluebase.session.id",
+    "cluebase.session_id",
+    "cluebase.span_id",
+    "cluebase.subject.organization_id",
+    "cluebase.tab.id",
+    "cluebase.tab_id",
+    "cluebase.trace_id",
+    "enduser.id",
+    "mcp.client.name",
+    "mcp.client.version",
+    "mcp.session.id",
+]);

package/dist/_generated/identity-pii-policy.d.ts

@@ -0,0 +1,38 @@
+/** 見る順序。先に当たった種類を返します。 */
+export declare const PII_CATEGORY_ORDER: readonly ["email", "ssn", "credit_card", "phone"];
+/** 電子メールの形。 */
+export declare const PII_EMAIL_PATTERN = "[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Za-z]{2,}";
+/** 社会保障番号の形。 */
+export declare const PII_SSN_PATTERN = "(?:^|\\D)\\d{3}-\\d{2}-\\d{4}(?:\\D|$)";
+/** 電話とみなす桁数の範囲と、求める区切り。 */
+export declare const PII_PHONE_MIN_DIGITS = 10;
+export declare const PII_PHONE_MAX_DIGITS = 15;
+export declare const PII_PHONE_SEPARATOR_PATTERN = "[+().\\-\\s]";
+/** 支払い用の番号とみなす桁数の範囲。Luhn の検算を必ず通します。 */
+export declare const PII_CREDIT_CARD_MIN_DIGITS = 13;
+export declare const PII_CREDIT_CARD_MAX_DIGITS = 19;
+/** 先に取り除く、汎用の一意識別子の形。 */
+export declare const PII_UUID_PATTERN = "[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}";
+/** 数字の連なりの候補を切り出す形。 */
+export declare const PII_DIGIT_RUN_PATTERN = "\\+?\\d[0-9().\\-\\s]{5,}\\d";
+/** 伏せた値の形。同じ入力なら配る部品 3 つとも同じ値になります。 */
+export declare const PII_HASH_PREFIX = "cluebase_pii_hashed:";
+export declare const PII_HASH_HEX_LENGTH = 32;
+/** どの面の規則か（読み手が取り違えないため）。 */
+export declare const PII_SURFACE: "text_contains_pii";
+/**
+ * Luhn の検算。支払い用の番号らしさを、無作為な数字の並びと分けます。
+ *
+ * **手順もここから出します。** 桁数と綴りだけを正本化して手順を手書きで残すと、
+ * 同じ算法が 4 か所（受付側と配る部品 3 つ）に残ります。実際に残っていました。
+ */
+export declare const passesLuhn: (digits: string) => boolean;
+/**
+ * この文字列が個人情報を**含む**か。埋もれた形も拾います。
+ *
+ * 任意の文字列（自由文を含む項目値）に対して問います。埋もれた形を拾わないと、
+ * 「contact alice@example.com for access」のような値が生の個人情報のまま
+ * 保管されます。値**そのもの**が識別子かを問いたい面は、もう一方の面
+ * （whole_value_is_pii）を使ってください。
+ */
+export declare const detectIdentityPII: (value: string) => string | null;

package/dist/_generated/identity-pii-policy.js

@@ -0,0 +1,103 @@
+// 自動生成です。**手で編集しないでください。**
+//
+// 正本: packages/cluebase-shared/src/ingest/identity-pii-policy.v1.json
+// 出し直す: node scripts/generate-shared-contract-tables.mjs
+//
+// 正本を直したらこの file も一緒に commit してください。CI が
+// `node scripts/generate-shared-contract-tables.mjs --check` で照合し、ずれていれば落とします。
+/** 見る順序。先に当たった種類を返します。 */
+export const PII_CATEGORY_ORDER = [
+    "email",
+    "ssn",
+    "credit_card",
+    "phone",
+];
+/** 電子メールの形。 */
+export const PII_EMAIL_PATTERN = "[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Za-z]{2,}";
+/** 社会保障番号の形。 */
+export const PII_SSN_PATTERN = "(?:^|\\D)\\d{3}-\\d{2}-\\d{4}(?:\\D|$)";
+/** 電話とみなす桁数の範囲と、求める区切り。 */
+export const PII_PHONE_MIN_DIGITS = 10;
+export const PII_PHONE_MAX_DIGITS = 15;
+export const PII_PHONE_SEPARATOR_PATTERN = "[+().\\-\\s]";
+/** 支払い用の番号とみなす桁数の範囲。Luhn の検算を必ず通します。 */
+export const PII_CREDIT_CARD_MIN_DIGITS = 13;
+export const PII_CREDIT_CARD_MAX_DIGITS = 19;
+/** 先に取り除く、汎用の一意識別子の形。 */
+export const PII_UUID_PATTERN = "[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}";
+/** 数字の連なりの候補を切り出す形。 */
+export const PII_DIGIT_RUN_PATTERN = "\\+?\\d[0-9().\\-\\s]{5,}\\d";
+/** 伏せた値の形。同じ入力なら配る部品 3 つとも同じ値になります。 */
+export const PII_HASH_PREFIX = "cluebase_pii_hashed:";
+export const PII_HASH_HEX_LENGTH = 32;
+/** どの面の規則か（読み手が取り違えないため）。 */
+export const PII_SURFACE = "text_contains_pii";
+/**
+ * Luhn の検算。支払い用の番号らしさを、無作為な数字の並びと分けます。
+ *
+ * **手順もここから出します。** 桁数と綴りだけを正本化して手順を手書きで残すと、
+ * 同じ算法が 4 か所（受付側と配る部品 3 つ）に残ります。実際に残っていました。
+ */
+export const passesLuhn = (digits) => {
+    let sum = 0;
+    let doubleDigit = false;
+    for (let index = digits.length - 1; index >= 0; index -= 1) {
+        let digit = Number(digits[index]);
+        if (doubleDigit) {
+            digit *= 2;
+            if (digit > 9)
+                digit -= 9;
+        }
+        sum += digit;
+        doubleDigit = !doubleDigit;
+    }
+    return sum % 10 === 0;
+};
+const EMAIL_RE = new RegExp(PII_EMAIL_PATTERN);
+const SSN_RE = new RegExp(PII_SSN_PATTERN);
+const UUID_RE = new RegExp(PII_UUID_PATTERN, "gi");
+const DIGIT_RUN_RE = new RegExp(PII_DIGIT_RUN_PATTERN, "g");
+const PHONE_SEPARATOR_RE = new RegExp(PII_PHONE_SEPARATOR_PATTERN);
+/** 値の全体を見て決まる種類。 */
+const WHOLE_VALUE_MATCHERS = {
+    email: EMAIL_RE,
+    ssn: SSN_RE,
+};
+/** 数字の連なりごとに決まる種類。 */
+const DIGIT_RUN_MATCHERS = {
+    credit_card: (_candidate, digits) => digits.length >= PII_CREDIT_CARD_MIN_DIGITS &&
+        digits.length <= PII_CREDIT_CARD_MAX_DIGITS &&
+        passesLuhn(digits),
+    phone: (candidate, digits) => digits.length >= PII_PHONE_MIN_DIGITS &&
+        digits.length <= PII_PHONE_MAX_DIGITS &&
+        PHONE_SEPARATOR_RE.test(candidate),
+};
+/**
+ * この文字列が個人情報を**含む**か。埋もれた形も拾います。
+ *
+ * 任意の文字列（自由文を含む項目値）に対して問います。埋もれた形を拾わないと、
+ * 「contact alice@example.com for access」のような値が生の個人情報のまま
+ * 保管されます。値**そのもの**が識別子かを問いたい面は、もう一方の面
+ * （whole_value_is_pii）を使ってください。
+ */
+export const detectIdentityPII = (value) => {
+    if (typeof value !== "string" || value.length === 0)
+        return null;
+    const trimmed = value.trim();
+    // 見る順序は正本が決めます。ここには書きません。
+    for (const category of PII_CATEGORY_ORDER) {
+        if (WHOLE_VALUE_MATCHERS[category]?.test(trimmed))
+            return category;
+    }
+    // 汎用の一意識別子を先に取り除きます。取り除かないと、区切り付きの 16 進の
+    // 並びが電話の候補に見えます。
+    const withoutUuids = trimmed.replace(UUID_RE, " ");
+    for (const candidate of withoutUuids.match(DIGIT_RUN_RE) ?? []) {
+        const digits = candidate.replace(/[^0-9]/g, "");
+        for (const category of PII_CATEGORY_ORDER) {
+            if (DIGIT_RUN_MATCHERS[category]?.(candidate, digits))
+                return category;
+        }
+    }
+    return null;
+};

package/dist/_generated/ingest-privacy-tables.d.ts

@@ -0,0 +1,120 @@
+/** 受付側が、どの許可設定によらず必ず落とす項目名。 */
+export declare const INGEST_HARD_DENY_KEYS: readonly string[];
+/**
+ * 配る部品が送り出す前に落とす項目名。
+ *
+ * 必ず {@link INGEST_HARD_DENY_KEYS} を含みます（同じ正本の配列を先頭に
+ * 並べて出しているため、包含関係は**構造で保証**されます。試験の主張ではありません）。
+ */
+export declare const SDK_ALWAYS_DENIED_KEYS: readonly string[];
+/**
+ * 受付側が**計測の属性**（OpenTelemetry の span 属性）を畳む時に落とす項目名。
+ *
+ * この面は顧客の任意の属性が丸ごと来るので、本文・問い合わせ文・見出しの類を
+ * 面ごと落とします。広すぎて利用者の項目名の面へは広げられないため、面ごとの
+ * 追加として持ちます。{@link INGEST_HARD_DENY_KEYS} を必ず含みます（同じ正本の
+ * 配列を先頭に並べて出しているため、包含関係は**構造で保証**されます）。
+ */
+export declare const INGEST_SIGNAL_DENIED_KEYS: readonly string[];
+/**
+ * 自分たちが出す**追跡情報（trace）の属性**で落とす項目名。
+ *
+ * この面は開発者が書いた属性がそのまま外へ出るので、広く落として困りません。
+ * `session` はこの面だけです。取り込みの面へ広げると、相関に使う
+ * `cluebase.session_id` まで落ちます。**面ごとに違うのは落とす語の一覧だけで、
+ * 突き合わせ方は 1 つ**です。
+ */
+export declare const INGEST_TRACE_DENIED_KEYS: readonly string[];
+/**
+ * 見た目が同じ別の文字を ASCII へ畳む表。
+ *
+ * NFKC はこれらを畳みません（互換分解ではなく別の文字だからです）。畳まないと
+ * \`τօκen\` のような綴りが \`token\` に一致せず、資格情報が伏せられないまま
+ * 送出されます。
+ *
+ * **畳んだ先はすべて小文字です。これは正しい形です。** Unicode の規格（UTS #39）は、
+ * 見た目が同じ文字を畳んだ結果について「大文字小文字を保つ形ではない」「項目名の
+ * 正規化として使ってはならない」と明記しています。したがって**畳んだ後の大文字小文字を
+ * 当てにする突き合わせを書いてはいけません**（下の突き合わせ用の形は、大文字小文字も
+ * 区切りも捨てます）。
+ */
+export declare const ASCII_CONFUSABLES_FOLD: Readonly<Record<string, string>>;
+export declare const foldAsciiConfusables: (value: string) => string;
+/**
+ * 項目名を、区切りの見える形にします。
+ *
+ * \`userEmail\` / \`user_email\` / \`user-email\` / \`USER_EMAIL\` / \`User.Email\`
+ * はすべて \`user_email\` になります。**この形は「経路っぽい項目名か」の判定に使います。**
+ * 落とすかどうかの突き合わせには使いません（下の {@link toPrivacyMatchKey} を使います）。
+ */
+export declare const normalizePrivacyLookupKey: (key: string) => string;
+/**
+ * 突き合わせる形。**区切りを落として詰めます。**
+ *
+ * 区切りを残してはいけません。区切りの位置は**送ってくる側が決められる**からです。
+ * 上の形は大文字の位置から区切りを補いますが、大文字を「見た目が同じ小文字の別文字」
+ * に替えられると、その区切りが消えます（\`accessтoken\` の \`т\` はキリル文字の小文字）。
+ * ASCII だけでも \`accesstoken\` \`ACCESSTOKEN\` のように区切りを 1 つも書かない綴りが
+ * 普通にあり、これらは**同形異字を使わなくても**素通りしていました。
+ *
+ * したがって**区切りに頼らない形にしてから突き合わせます。**
+ */
+export declare const toPrivacyMatchKey: (key: string) => string;
+/**
+ * 落とす語を含むが、落としてはいけないと決めた項目名。
+ *
+ * 部分一致で落とす方式は必ず巻き添えを出すので、業界の既定は逃し口を
+ * **完全一致**の一覧として持つことです（Sentry の Safe Fields も完全一致）。
+ * 中身は「トークンの個数」だけです。資格情報ではなく数量で、生成 AI の費用の
+ * 分析に要ります。
+ */
+export declare const INGEST_DENY_EXEMPT_KEYS: readonly string[];
+/** 落とす項目名の一覧を、突き合わせ用の集合にします。空になるものは捨てます。 */
+export declare const toDeniedLookupKeySet: (deniedKeys: readonly string[]) => Set<string>;
+/**
+ * 詰めた形への部分一致で突き合わせる、落とす語の最短の長さ。
+ *
+ * これ未満の語は、区切りの塊の**端に接している**時だけ落とします。
+ */
+export declare const PRIVACY_SUBSTRING_MATCH_MIN_LENGTH = 4;
+/** 既に伏せてある値の綴り（そのまま一致する分）。 */
+export declare const MASKED_VALUE_EXACT: readonly string[];
+/** 既に伏せてある値の綴り（先頭が一致する分）。後ろは指紋です。 */
+export declare const MASKED_VALUE_PREFIXES: readonly string[];
+/**
+ * 連絡先（メール）の形。**指紋にする前に小文字へ畳んでよいかだけを決めます。**
+ *
+ * 合えば前後の空白を落として小文字にしてから指紋にし、合わなければ元の値のまま
+ * 指紋にします。**両側で同じ規則でなければ、同じ人の同じメールが経路ごとに別の
+ * 指紋になり、突き合わせが 0 件で返ります。**
+ */
+export declare const CONTACT_EMAIL_SHAPE = "^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$";
+/** その値は、指紋にする前に小文字へ畳んでよい形か。 */
+export declare const isContactEmailShaped: (value: string) => boolean;
+/**
+ * この項目名を落とすか。**落とす語の長さで、突き合わせ方を分けます。**
+ *
+ * | 落とす語 | 突き合わせ | 例 |
+ * |---|---|---|
+ * | 4 文字以上 | 詰めた形への**部分一致** | `token` が `accesstoken` `ACCESSTOKEN` `myAccessToken` `accessтoken` に当たる |
+ * | 4 文字未満 | 区切りの塊の**端に接する**か、塊を繋いだ形と一致 | `ssn` が `user_ssn` `ssnLast4` `userssn` `s.s.n` に当たり、`class_snapshot` には当たらない |
+ *
+ * **部分一致は業界の既定ですが、3 文字の頭字語に当てると顧客の正当な項目名を
+ * 無言で捨てます。** 実測（2026-08-14）: 辞書由来の項目名 160 万件のうち
+ * **50,041 件**が誤って落ち、`class_snapshot`（`classsnapshot` の中の `ssn`）・
+ * `boss_snapshot`・`cross_snapshot`・`business_snapshot`・`press_note`・
+ * `adobe_id`（`adobe` の中の `dob`）が消えていました。
+ *
+ * **業界が同じことをしていない、とは書けません。** Rails の
+ * `ActiveSupport::ParameterFilter` は既定で `ssn` `cvv` `cvc` を持ち、部分一致で
+ * 当てています。Rails で許されるのは対象が**ログ出力**だけで、誤爆しても
+ * `[FILTERED]` と出るだけで元データが残るからです。**こちらは取り込みで項目
+ * そのものを捨てるので復元できません。**釣り合いが違うので、Rails の許容は
+ * こちらへ持ち込めません。
+ *
+ * **両方は満たせません。** 部分一致をやめた分だけ、詰めた綴り（`xssnvalue`）は
+ * 通ります。攻撃綴り 11,627 件での素通りは、この案で 560 件です（塊とちょうど
+ * 一致させる案は 984 件）。この案は**現行が落とすものしか落とさない**ので、
+ * 誤爆を新たに増やしません。
+ */
+export declare const isDeniedLookupKey: (key: string, deniedSet: ReadonlySet<string>) => boolean;