@corbado/observe 1.8.0 → 1.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@corbado/observe",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
@@ -8,7 +8,8 @@
     "./dist/cdn/*"
   ],
   "files": [
-    "dist"
+    "dist",
+    "tools"
   ],
   "scripts": {
     "build": "tsup src/index.ts --format cjs,esm --dts --minify --define.__CORBADO_OBSERVE_SDK_VERSION__='\"'${CORBADO_OBSERVE_SDK_VERSION:-0.0.0-dev}'\"' && pnpm build:analysis",
@@ -19,12 +20,13 @@
     "example:password-managers": "pnpm build:example:password-managers && pnpm dlx serve example/password-managers -p 4173",
     "dev": "tsup src/index.ts --format cjs,esm --watch --dts",
     "lint": "tsc --noEmit",
+    "check:browser-globals": "node scripts/check-browser-globals.mjs",
     "docs": "tsx scripts/inject-docs.ts",
     "test": "vitest run",
     "test:migration": "pnpm build:cdn && playwright test --config e2e/playwright.config.ts",
     "test:password-managers": "tsx --test e2e/password-managers/password-managers.test.ts",
     "test:watch": "vitest",
-    "test:data-guards": "pnpm build && node scripts/check-data-guards.mjs",
+    "test:data-guards": "pnpm build && pnpm build:cdn && node scripts/check-data-guards.mjs",
     "format": "prettier --write 'src/**/*.ts'",
     "format:check": "prettier --check 'src/**/*.ts'"
   },

package/tools/reader-meta-text.d.mts

@@ -0,0 +1,2 @@
+/** Why a customer-facing reader `title` / `group` reads as code, or `undefined` when it is plain language. */
+export declare function customerTextProblem(text: unknown): string | undefined;

package/tools/reader-meta-text.mjs

@@ -0,0 +1,26 @@
+// Rule for customer-facing reader metadata text (`title`, `group`): plain language a customer's PM or
+// security owner can read. API names, globals, config keys and code belong in `accessNote`.
+// Shared by the SDK's scanner (scripts/check-browser-globals.mjs) and @corbado/autocapture's manifest checks.
+
+// DOM event names that read as code in a title, e.g. "Page unload (pagehide)".
+const EVENT_NAMES =
+  /^(pagehide|pageshow|visibilitychange|popstate|hashchange|readystatechange|beforeunload|unload|focusin|focusout|pointerdown|pointerup|keydown|keyup|domcontentloaded|load|paste|submit|input|change|blur|focus)$/i;
+
+/**
+ * Why `text` reads as code, or `undefined` when it is plain language. Rejects backticks, `__`, `=`,
+ * `window.`, dotted identifiers (`navigator.webdriver`) and parentheses with code-ish content
+ * (camelCase, `.`/`_`/`/`/`:` and similar, calls, DOM event names).
+ */
+export function customerTextProblem(text) {
+  if (typeof text !== "string" || text.trim() === "") return "empty";
+  if (text.includes("`")) return "backtick";
+  if (text.includes("__")) return "double underscore";
+  if (text.includes("=")) return "'='";
+  if (/\bwindow\./.test(text)) return "'window.'";
+  if (/[A-Za-z_$][\w$]*\.[A-Za-z_$][\w$]*/.test(text)) return "dotted identifier";
+  for (const [, inner] of text.matchAll(/\(([^)]*)\)/g)) {
+    if (/[a-z][A-Z]|[._/$<>{}[\]:;]|\w\(/.test(inner) || EVENT_NAMES.test(inner.trim()))
+      return `code in parentheses "(${inner})"`;
+  }
+  return undefined;
+}

package/tools/strip-reader-meta.d.mts

@@ -0,0 +1,33 @@
+import type * as TS from "typescript";
+
+/** Manifest key shape `<kind>:<namespace>.<name>` of a reader metadata literal. */
+export declare const READER_META_KEY: RegExp;
+
+/** Whether `node` is a reader metadata object literal (object literal with a manifest-shaped `key` and `fields`). */
+export declare function isReaderMetaLiteral(ts: typeof TS, node: TS.Node): boolean;
+
+/** Replaces every reader metadata call argument in `code` with `0`. */
+export declare function stripReaderMeta(
+  ts: typeof TS,
+  code: string,
+  fileName?: string,
+): { code: string; count: number };
+
+export type StripReaderMetaOptions = {
+  /** Paths the plugin loads (default: TS/JS sources). */
+  filter?: RegExp;
+  /** A path must match this to be stripped. */
+  include?: RegExp;
+  /** Paths left alone (default `node_modules`); `null` disables. */
+  exclude?: RegExp | null;
+  /** The TypeScript compiler module (default: `import("typescript")`). */
+  typescript?: typeof TS;
+  /** Called for every changed module. */
+  onStrip?: (path: string, count: number) => void;
+};
+
+/** esbuild plugin (tsup: `esbuildPlugins`) replacing reader metadata call arguments with `0`. */
+export declare function stripReaderMetaPlugin(options?: StripReaderMetaOptions): {
+  name: string;
+  setup(build: unknown): void;
+};

package/tools/strip-reader-meta.mjs

@@ -0,0 +1,131 @@
+// esbuild plugin (also usable from tsup via `esbuildPlugins`) that removes reader metadata from shipped builds.
+//
+// Every reader call takes a literal `ReaderMeta` (`{ key: "<kind>:<namespace>.<name>", fields: [...], ... }`) with
+// no runtime effect: readers ignore it, and the collection manifest is extracted from the unminified analysis
+// build (`dist/analysis`), not from the shipped bundles. This plugin parses each loaded module with the
+// TypeScript compiler and replaces every such call argument with `0`, so titles, notes and field lists do not
+// ship to browsers. Everything else in the module is left byte-for-byte unchanged.
+//
+// A call argument is treated as reader metadata when it is an object literal with a `key` property whose value
+// is a string literal of the manifest key shape and a `fields` property. Object literals that are not call
+// arguments (e.g. exported constants that code reads at runtime) are never touched.
+//
+// Usage (esbuild / tsup):
+//   import { stripReaderMetaPlugin } from "@corbado/observe/tools/strip-reader-meta.mjs";
+//   esbuildPlugins: [stripReaderMetaPlugin()]                  // tsup
+//   plugins: [stripReaderMetaPlugin({ include: /\/src\// })]  // esbuild
+// Do NOT use it for analysis builds: the manifest extractor reads the literals there.
+//
+// Requires the `typescript` package (resolved from the consumer, or passed as `options.typescript`).
+import { readFile } from "node:fs/promises";
+
+/** Manifest key shape `<kind>:<namespace>.<name>` of a reader metadata literal. */
+export const READER_META_KEY = /^(dom|network|page|browser-api|storage|host-config):[A-Za-z0-9_-]+(\.[A-Za-z0-9_-]+)+$/;
+
+function propertyName(ts, prop) {
+  if (!ts.isPropertyAssignment(prop)) return undefined;
+  const name = prop.name;
+  if (ts.isIdentifier(name) || ts.isStringLiteral(name)) return name.text;
+  return undefined;
+}
+
+/** Whether `node` is a reader metadata object literal (see the header). */
+export function isReaderMetaLiteral(ts, node) {
+  if (!ts.isObjectLiteralExpression(node)) return false;
+  let key = false;
+  let fields = false;
+  for (const prop of node.properties) {
+    const name = propertyName(ts, prop);
+    if (name === "key") {
+      const value = prop.initializer;
+      key =
+        (ts.isStringLiteral(value) || ts.isNoSubstitutionTemplateLiteral(value)) && READER_META_KEY.test(value.text);
+    } else if (name === "fields") fields = true;
+  }
+  return key && fields;
+}
+
+function scriptKind(ts, fileName) {
+  if (/\.tsx$/.test(fileName)) return ts.ScriptKind.TSX;
+  if (/\.[cm]?ts$/.test(fileName)) return ts.ScriptKind.TS;
+  if (/\.jsx$/.test(fileName)) return ts.ScriptKind.JSX;
+  return ts.ScriptKind.JS;
+}
+
+/**
+ * Replaces every reader metadata call argument in `code` with `0`.
+ * Returns `{ code, count }` (`code` is the input unchanged when `count` is 0).
+ */
+export function stripReaderMeta(ts, code, fileName = "module.ts") {
+  if (!code.includes("fields")) return { code, count: 0 };
+  const sf = ts.createSourceFile(fileName, code, ts.ScriptTarget.Latest, true, scriptKind(ts, fileName));
+  const ranges = [];
+  const visit = (node) => {
+    if ((ts.isCallExpression(node) || ts.isNewExpression(node)) && node.arguments) {
+      for (const arg of node.arguments) {
+        let inner = arg;
+        while (ts.isParenthesizedExpression(inner) || ts.isAsExpression(inner) || ts.isSatisfiesExpression?.(inner))
+          inner = inner.expression;
+        if (isReaderMetaLiteral(ts, inner)) {
+          ranges.push([arg.getStart(sf), arg.getEnd()]);
+          return; // the literal is replaced as a whole; nothing inside it needs a visit
+        }
+      }
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(sf);
+  if (ranges.length === 0) return { code, count: 0 };
+  ranges.sort((a, b) => a[0] - b[0]);
+  let out = "";
+  let at = 0;
+  for (const [start, end] of ranges) {
+    out += code.slice(at, start) + "0";
+    at = end;
+  }
+  out += code.slice(at);
+  return { code: out, count: ranges.length };
+}
+
+function loaderOf(fileName) {
+  if (/\.tsx$/.test(fileName)) return "tsx";
+  if (/\.[cm]?ts$/.test(fileName)) return "ts";
+  if (/\.jsx$/.test(fileName)) return "jsx";
+  return "js";
+}
+
+/**
+ * esbuild plugin replacing reader metadata call arguments with `0`.
+ * Options: `filter` (RegExp of paths to load, default TS/JS sources), `include` (RegExp a path must match),
+ * `exclude` (RegExp, default `node_modules`), `typescript` (the compiler module; default `import("typescript")`),
+ * `onStrip(path, count)` (called per changed module, e.g. for build stats).
+ */
+export function stripReaderMetaPlugin(options = {}) {
+  const filter = options.filter ?? /\.[cm]?[jt]sx?$/;
+  const exclude = options.exclude === undefined ? /[\\/]node_modules[\\/]/ : options.exclude;
+  const include = options.include;
+  return {
+    name: "corbado-strip-reader-meta",
+    setup(build) {
+      let tsPromise;
+      const compiler = () => {
+        tsPromise ??= options.typescript
+          ? Promise.resolve(options.typescript)
+          : import("typescript").then((m) => m.default ?? m);
+        return tsPromise;
+      };
+      build.onLoad({ filter }, async (args) => {
+        if (args.namespace !== "file") return undefined;
+        if (exclude && exclude.test(args.path)) return undefined;
+        if (include && !include.test(args.path)) return undefined;
+        const source = await readFile(args.path, "utf8");
+        if (!source.includes("fields")) return undefined;
+        const ts = await compiler();
+        const { code, count } = stripReaderMeta(ts, source, args.path);
+        if (count === 0) return undefined;
+        options.onStrip?.(args.path, count);
+        return { contents: code, loader: loaderOf(args.path) };
+      });
+    },
+  };
+}