@genn-inc/cluebase-frontend-sdk 0.0.1

package/dist/exporter/sanitize.js

@@ -0,0 +1,177 @@
+import { sha256 } from "@noble/hashes/sha256";
+import { bytesToHex, utf8ToBytes } from "@noble/hashes/utils";
+// 個人情報の形を見分ける規則も、正本から生成した部品を読みます。
+import { detectIdentityPII, PII_HASH_HEX_LENGTH, PII_HASH_PREFIX, } from "../_generated/identity-pii-policy.js";
+// 落とす項目名・同形異字を畳む表・突き合わせの手順は、正本から生成した部品を
+// 読みます。ここへ写すと受付側とずれます（AGENTS §0.2）。
+import { isDeniedLookupKey, toDeniedLookupKeySet, } from "../_generated/ingest-privacy-tables.js";
+import { toPathTemplate } from "../exporter/path-template.js";
+import { ALWAYS_DENIED_KEYS, MASKED_VALUE, MAX_SANITIZE_DEPTH, } from "../provider/constants.js";
+const normalizeHeaderKey = (key) => key.trim().toLowerCase();
+const toDeniedSet = (deniedKeys) => toDeniedLookupKeySet([...ALWAYS_DENIED_KEYS, ...deniedKeys]);
+const isDeniedKeyWithSet = (key, deniedSet) => isDeniedLookupKey(key, deniedSet);
+const isSanitizableObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+export const isDeniedKey = (key, deniedKeys = []) => {
+    return isDeniedKeyWithSet(key, toDeniedSet(deniedKeys));
+};
+export const sanitizeHeaders = (headers, deniedKeys = []) => {
+    const deniedSet = toDeniedSet(deniedKeys);
+    const sanitized = {};
+    for (const [key, value] of Object.entries(headers)) {
+        if (isDeniedKeyWithSet(key, deniedSet)) {
+            continue;
+        }
+        sanitized[normalizeHeaderKey(key)] = value;
+    }
+    return sanitized;
+};
+export const sanitizeObject = (value, deniedKeys = [], summary, pathPrefix = "") => {
+    const deniedSet = toDeniedSet(deniedKeys);
+    const seen = new WeakSet();
+    const walk = (current, depth, path) => {
+        if (current == null) {
+            return null;
+        }
+        if (depth > MAX_SANITIZE_DEPTH) {
+            return null;
+        }
+        if (Array.isArray(current)) {
+            return current.map((entry, index) => {
+                const next = walk(entry, depth + 1, `${path}[${index}]`);
+                return next === undefined ? null : next;
+            });
+        }
+        if (isSanitizableObject(current)) {
+            const objectValue = current;
+            if (seen.has(objectValue)) {
+                return null;
+            }
+            seen.add(objectValue);
+            const sanitized = {};
+            for (const [key, child] of Object.entries(objectValue)) {
+                if (isDeniedKeyWithSet(key, deniedSet)) {
+                    if (summary)
+                        summary.droppedFieldCount += 1;
+                    continue;
+                }
+                const childPath = path ? `${path}.${key}` : key;
+                const next = walk(child, depth + 1, childPath);
+                if (next === undefined) {
+                    continue;
+                }
+                sanitized[key] = next;
+            }
+            seen.delete(objectValue);
+            return sanitized;
+        }
+        if (typeof current === "function" || typeof current === "symbol") {
+            return undefined;
+        }
+        // Value-level PII shape detection. The denied-key gate above catches
+        // `email = "..."`, but a non-denied key like
+        // `metadata.customer_contact = "alice@example.com"` would still leak
+        // the email verbatim. Replace any string whose shape matches an
+        // identity-PII pattern (email / phone / SSN / credit_card with
+        // Luhn) with the canonical masked sentinel.
+        if (typeof current === "string" && detectIdentityPII(current) !== null) {
+            if (current === MASKED_VALUE)
+                return current;
+            if (summary) {
+                summary.maskedValueCount += 1;
+                if (path)
+                    summary.maskedFields.add(path);
+            }
+            return MASKED_VALUE;
+        }
+        return current;
+    };
+    return walk(value, 0, pathPrefix);
+};
+export const parseUrlForNetwork = (rawUrl) => {
+    const toQueryRecord = (url) => {
+        const query = {};
+        url.searchParams.forEach((value, key) => {
+            const current = query[key];
+            if (current === undefined) {
+                query[key] = value;
+                return;
+            }
+            if (Array.isArray(current)) {
+                query[key] = [...current, value];
+                return;
+            }
+            query[key] = [current, value];
+        });
+        return query;
+    };
+    try {
+        const url = new URL(rawUrl, globalThis.location?.origin);
+        const query = url.search ? `?${MASKED_VALUE}` : "";
+        return {
+            host: url.host,
+            pathTemplate: toPathTemplate(url.pathname),
+            path: url.pathname,
+            query: toQueryRecord(url),
+            urlMaskedQuery: `${url.origin}${url.pathname}${query}`,
+        };
+    }
+    catch {
+        return {
+            host: "",
+            pathTemplate: "/",
+            path: "/",
+            query: {},
+            urlMaskedQuery: MASKED_VALUE,
+        };
+    }
+};
+export const maybeParseJson = (value) => {
+    if (typeof value !== "string") {
+        return value;
+    }
+    const trimmed = value.trim();
+    if (!trimmed) {
+        return null;
+    }
+    const isJsonLike = (trimmed.startsWith("{") && trimmed.endsWith("}")) ||
+        (trimmed.startsWith("[") && trimmed.endsWith("]"));
+    if (!isJsonLike) {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(trimmed);
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+};
+// ---------------------------------------------------------------------------
+// Identity-value PII detection for browser payloads.
+//
+// The frontend SDK does not propagate identity via W3C Baggage (browser-side
+// never opens outgoing HTTP to non-Cluebase services), so the leak vector here is
+// the canonical span attribute `cluebase.actor.user_id` getting captured in raw
+// observation storage / facts_json. Hashing PII-shaped identity values
+// prevents that.
+//
+// この面は値の**中**を走査します（裏の配る部品は両端で留めます）。違いは本物で、
+// 意図したものです——**問いが違うからです。** ここは「この文字列が個人情報を
+// 含むか」、裏は「この値そのものが個人情報か」。正本
+// （`identity-pii-policy.v1.json` の面 `text_contains_pii`）に 1 度だけ書かれ、
+// 下の生成物から読みます。**面の名前は生成物の `PII_SURFACE` が名乗ります。**
+// 判定の手順は**正本から出した部品が持ちます**。ここには手順が手で書かれており、
+// 受付側にも同じ手順の 2 本目が手で書かれていました（AGENTS §0.2）。
+export { detectIdentityPII };
+/**
+ * Synchronous deterministic SHA-256 hash for identity values that look
+ * like PII. The identity sanitization path must remain synchronous
+ * because `identify(userId)` is sync-only by SDK contract.
+ *
+ * Output format: `cluebase_pii_hashed:<32-hex>`.
+ *
+ * The algorithm name, the digest length and the prefix are read from the
+ * generated policy, not written here, so the three SDKs produce the same
+ * token for the same input by construction rather than by assertion.
+ */
+export const hashIdentityValue = (value) => `${PII_HASH_PREFIX}${bytesToHex(sha256(utf8ToBytes(value))).slice(0, PII_HASH_HEX_LENGTH)}`;

package/dist/exporter/schema-evidence.d.ts

@@ -0,0 +1,20 @@
+type SchemaEvidence = {
+    schemaHash: string | null;
+    fieldPaths: string[];
+    shapeSize: number;
+};
+export declare const buildSchemaEvidence: (value: unknown) => SchemaEvidence;
+export declare const extractErrorCodeCandidate: (value: unknown) => string | null;
+export declare const deriveOutcomeClass: (input: {
+    statusCode?: number | null;
+    failureType?: string | null;
+    responseBody?: unknown;
+}) => string;
+export type GraphqlEvidence = {
+    requestKind: "graphql" | null;
+    graphqlOperationName: string | null;
+    graphqlOperationType: "query" | "mutation" | "subscription" | null;
+    graphqlTopLevelFields: string[];
+};
+export declare const extractGraphqlEvidence: (body: unknown) => GraphqlEvidence;
+export {};

package/dist/exporter/schema-evidence.js

@@ -0,0 +1,232 @@
+import { fingerprintText } from "./text-fingerprint.js";
+const MAX_FIELD_PATHS = 100;
+const MAX_DEPTH = 8;
+const isReadableObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const valueType = (value) => {
+    if (value === null) {
+        return "null";
+    }
+    if (Array.isArray(value)) {
+        return "array";
+    }
+    if (typeof value === "object") {
+        return "object";
+    }
+    return typeof value;
+};
+const buildShape = (value, path, fieldPaths, depth) => {
+    if (depth > MAX_DEPTH) {
+        return { type: "max_depth" };
+    }
+    if (Array.isArray(value)) {
+        if (path && fieldPaths.length < MAX_FIELD_PATHS) {
+            fieldPaths.push(`${path}[]`);
+        }
+        return {
+            type: "array",
+            items: value.length > 0
+                ? buildShape(value[0], `${path}[]`, fieldPaths, depth + 1)
+                : "empty",
+        };
+    }
+    if (isReadableObject(value)) {
+        const fields = {};
+        for (const key of Object.keys(value).sort()) {
+            const childPath = path ? `${path}.${key}` : key;
+            if (fieldPaths.length < MAX_FIELD_PATHS) {
+                fieldPaths.push(childPath);
+            }
+            fields[key] = buildShape(value[key], childPath, fieldPaths, depth + 1);
+        }
+        return {
+            type: "object",
+            fields,
+        };
+    }
+    return { type: valueType(value) };
+};
+export const buildSchemaEvidence = (value) => {
+    if (value === null || value === undefined) {
+        return {
+            schemaHash: null,
+            fieldPaths: [],
+            shapeSize: 0,
+        };
+    }
+    const fieldPaths = [];
+    const shape = buildShape(value, "", fieldPaths, 0);
+    const uniqueFieldPaths = [...new Set(fieldPaths)].sort();
+    return {
+        schemaHash: fingerprintText(JSON.stringify(shape)),
+        fieldPaths: uniqueFieldPaths,
+        shapeSize: uniqueFieldPaths.length,
+    };
+};
+const sanitizeToken = (value) => {
+    if (typeof value !== "string") {
+        return null;
+    }
+    const trimmed = value.trim();
+    if (!trimmed || trimmed.length > 96) {
+        return null;
+    }
+    if (!/^[A-Za-z0-9_.:-]+$/.test(trimmed)) {
+        return null;
+    }
+    return trimmed.toLowerCase();
+};
+export const extractErrorCodeCandidate = (value) => {
+    if (Array.isArray(value)) {
+        for (const entry of value) {
+            const candidate = extractErrorCodeCandidate(entry);
+            if (candidate) {
+                return candidate;
+            }
+        }
+        return null;
+    }
+    if (!isReadableObject(value)) {
+        return sanitizeToken(value);
+    }
+    for (const key of ["code", "error_code", "type", "error"]) {
+        const candidate = sanitizeToken(value[key]);
+        if (candidate) {
+            return candidate;
+        }
+    }
+    for (const key of ["errors", "detail", "extensions"]) {
+        const candidate = extractErrorCodeCandidate(value[key]);
+        if (candidate) {
+            return candidate;
+        }
+    }
+    return null;
+};
+export const deriveOutcomeClass = (input) => {
+    const statusCode = input.statusCode ?? null;
+    if (statusCode !== null && statusCode > 0) {
+        if (statusCode === 401) {
+            return "auth_denied";
+        }
+        if (statusCode === 403) {
+            return "permission_denied";
+        }
+        if (statusCode === 409) {
+            return "conflict";
+        }
+        if (statusCode === 422) {
+            return "validation_error";
+        }
+        if (statusCode === 429) {
+            return "rate_limited";
+        }
+        if (statusCode >= 500) {
+            return "server_error";
+        }
+        if (statusCode >= 400) {
+            return "client_error";
+        }
+        return "success";
+    }
+    const failureType = input.failureType ?? null;
+    if (failureType) {
+        if (failureType === "AbortError" || failureType.includes("abort")) {
+            return "aborted";
+        }
+        if (failureType.includes("timeout")) {
+            return "timeout";
+        }
+        return "network_failed";
+    }
+    return "success";
+};
+const stripGraphqlNoise = (query) => {
+    return query
+        .replace(/#[^\n\r]*/g, "")
+        .replace(/"([^"\\]|\\.)*"/g, '""')
+        .replace(/'([^'\\]|\\.)*'/g, "''");
+};
+const readTopLevelGraphqlFields = (query) => {
+    const openIndex = query.indexOf("{");
+    if (openIndex < 0) {
+        return [];
+    }
+    const fields = [];
+    let depth = 0;
+    let parenDepth = 0;
+    let token = "";
+    for (let index = openIndex; index < query.length; index += 1) {
+        const char = query[index];
+        if (char === "(") {
+            if (depth === 1) {
+                if (/^[A-Za-z_][A-Za-z0-9_]*$/.test(token) && token !== "on") {
+                    fields.push(token);
+                }
+                token = "";
+            }
+            parenDepth += 1;
+            continue;
+        }
+        if (char === ")") {
+            parenDepth = Math.max(0, parenDepth - 1);
+            token = "";
+            continue;
+        }
+        if (char === "{") {
+            depth += 1;
+            token = "";
+            continue;
+        }
+        if (char === "}") {
+            if (depth === 1 && /^[A-Za-z_][A-Za-z0-9_]*$/.test(token)) {
+                fields.push(token);
+            }
+            depth -= 1;
+            token = "";
+            continue;
+        }
+        if (depth !== 1 || parenDepth > 0) {
+            continue;
+        }
+        if (/[A-Za-z0-9_]/.test(char)) {
+            token += char;
+            continue;
+        }
+        if (/^[A-Za-z_][A-Za-z0-9_]*$/.test(token) && token !== "on") {
+            fields.push(token);
+        }
+        token = "";
+    }
+    return [...new Set(fields)].slice(0, 20).sort();
+};
+export const extractGraphqlEvidence = (body) => {
+    if (!isReadableObject(body)) {
+        return {
+            requestKind: null,
+            graphqlOperationName: null,
+            graphqlOperationType: null,
+            graphqlTopLevelFields: [],
+        };
+    }
+    const query = typeof body.query === "string" ? body.query : null;
+    if (!query) {
+        return {
+            requestKind: null,
+            graphqlOperationName: null,
+            graphqlOperationType: null,
+            graphqlTopLevelFields: [],
+        };
+    }
+    const normalizedQuery = stripGraphqlNoise(query);
+    const operationMatch = normalizedQuery.match(/\b(query|mutation|subscription)\s*([A-Za-z_][A-Za-z0-9_]*)?/);
+    const operationType = operationMatch?.[1] ?? "query";
+    const operationName = typeof body.operationName === "string" && body.operationName.trim()
+        ? body.operationName.trim()
+        : (operationMatch?.[2] ?? null);
+    return {
+        requestKind: "graphql",
+        graphqlOperationName: operationName,
+        graphqlOperationType: operationType,
+        graphqlTopLevelFields: readTopLevelGraphqlFields(normalizedQuery),
+    };
+};

package/dist/exporter/source-event.d.ts

@@ -0,0 +1,99 @@
+import type { CanonicalJsonValue, CluebasePrivacySummary, CluebaseSubjectProfile, SdkCollectionMode } from "../provider/types.js";
+export declare const SDK_SOURCE_SIGNAL_EVENT_NAME = "sdk_source_signal_observed";
+export declare const SDK_SOURCE_SIGNAL_EVENT_TYPE = "sdk_source_signal";
+export type BrowserSdkSignalContext = {
+    producer_id: string | null;
+    anonymous_id: string | null;
+    user_id: string | null;
+    organization_id: string | null;
+    user_profile: CluebaseSubjectProfile | null;
+    session_id: string | null;
+    tab_id: string;
+    trace_id: string;
+    request_id: string;
+    request_span_id: string;
+    interaction_id: string;
+    correlation_id: string | null;
+    sdk_collection_mode: SdkCollectionMode;
+    frontend_release: string | null;
+    locale: string | null;
+    country: string | null;
+    device_type: string | null;
+    browser: string | null;
+    os: string | null;
+    referrer: string | null;
+    browser_family: string | null;
+    browser_major_version: string | null;
+    browser_engine: string | null;
+    os_family: string | null;
+    os_major_version: string | null;
+    timezone: string | null;
+    pointer_type_candidate: string | null;
+    touch_capable: boolean | null;
+    cookies_enabled: boolean | null;
+    local_storage_available: boolean | null;
+    session_storage_available: boolean | null;
+    service_worker_supported: boolean | null;
+    webgl_supported: boolean | null;
+    reduced_motion: string | null;
+    color_scheme: string | null;
+    subject_traits: Record<string, CanonicalJsonValue>;
+    organization_traits: Record<string, CanonicalJsonValue>;
+    context_traits: Record<string, CanonicalJsonValue>;
+};
+export type BrowserSdkSignal = {
+    surface: "frontend";
+    kind: "span";
+    name: string;
+    span_kind: string | number | null;
+    trace_id: string;
+    span_id: string | null;
+    parent_span_id: string | null;
+    start_time_unix_nano: string;
+    end_time_unix_nano: string;
+    status_code: number | null;
+    status_message: string | null;
+    instrumentation_scope_name: string | null;
+    attributes: Record<string, CanonicalJsonValue>;
+    events: Array<{
+        name: string;
+        attributes: Record<string, CanonicalJsonValue>;
+    }>;
+    resource: Record<string, CanonicalJsonValue>;
+    context: BrowserSdkSignalContext;
+};
+export type BrowserSourceSignalEvent = {
+    event_id: string;
+    source_event_id?: string;
+    source_schema_version?: string;
+    source_event_type: typeof SDK_SOURCE_SIGNAL_EVENT_TYPE;
+    source_event_kind: typeof SDK_SOURCE_SIGNAL_EVENT_TYPE;
+    producer_id: string | null;
+    service_name?: string | null;
+    event_name: typeof SDK_SOURCE_SIGNAL_EVENT_NAME;
+    event_category: "context";
+    event_source: "frontend_sdk";
+    event_version: number;
+    occurred_at: string;
+    ingested_at: string;
+    status: string;
+    sdk_collection_mode: string;
+    privacy_state?: "allow" | "masked" | "blocked";
+    privacy_level?: "default_masked" | "allowlisted";
+    masking_state?: "masked" | "partially_unmasked" | "unmasked";
+    allowed_value_keys?: string[];
+    privacy_summary?: CluebasePrivacySummary;
+    trace_id: string;
+    span_id?: string | null;
+    parent_span_id?: string | null;
+    request_id: string;
+    request_span_id: string;
+    interaction_id: string;
+    frontend_release: string | null;
+    backend_release: string | null;
+    properties: Record<string, CanonicalJsonValue>;
+    metrics: Record<string, number>;
+    sdk_signal: BrowserSdkSignal;
+};
+export type BrowserSourceEvent = BrowserSourceSignalEvent;
+export declare function isBrowserSourceSignalEvent(event: unknown): event is BrowserSourceSignalEvent;

package/dist/exporter/source-event.js

@@ -0,0 +1,13 @@
+export const SDK_SOURCE_SIGNAL_EVENT_NAME = "sdk_source_signal_observed";
+export const SDK_SOURCE_SIGNAL_EVENT_TYPE = "sdk_source_signal";
+const isReadableObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+export function isBrowserSourceSignalEvent(event) {
+    if (!isReadableObject(event)) {
+        return false;
+    }
+    const sdkSignal = event.sdk_signal;
+    return (event.event_name === SDK_SOURCE_SIGNAL_EVENT_NAME &&
+        event.source_event_type === SDK_SOURCE_SIGNAL_EVENT_TYPE &&
+        event.source_event_kind === SDK_SOURCE_SIGNAL_EVENT_TYPE &&
+        isReadableObject(sdkSignal));
+}

package/dist/exporter/span-to-source-signal.d.ts

@@ -0,0 +1,8 @@
+import type { ReadableSpan } from "@opentelemetry/sdk-trace-base";
+import type { CluebaseContext } from "../provider/types.js";
+import { type BrowserSourceSignalEvent } from "./source-event.js";
+export interface SpanToSourceSignalOptions {
+    context: CluebaseContext;
+    deniedKeys?: readonly string[];
+}
+export declare function spanToSourceSignalEvent(span: ReadableSpan, options: SpanToSourceSignalOptions): BrowserSourceSignalEvent;