@goliapkg/sentori-react-native 1.0.0-rc.8 → 1.0.0

package/src/report-security.ts

@@ -0,0 +1,165 @@
+// v1.1 chunk S2 — security event reporting.
+//
+// `sentori.reportSecurity(kind, data)` POSTs a single security event
+// to `/v1/security:report`. Helpers wrap common kinds with the right
+// payload shape so dashboards can rely on it without coordinating
+// schemas with every host app.
+//
+// Why a separate API from `captureException` / `track`: security
+// reports have different retention + access patterns (the trust
+// scoring engine in S3 reads them on a hot path) and conflating
+// them with errors would pollute issue grouping. Single endpoint,
+// no batching: pin mismatches and root-detection signals are
+// low-volume by nature (one per app-lifetime in most cases).
+
+import { getConfig, isInitialized } from './config';
+import { peekInstallId } from './install-id';
+import { getCurrentUserId } from './capture';
+
+const SDK_VERSION = '0.0.0';
+
+export type SecurityReportData = Record<string, unknown>;
+
+/**
+ * Report an arbitrary security signal. Fire-and-forget; resolves
+ * with the server-assigned event id on success or `null` on any
+ * failure (network down, server unhappy, SDK not initialised).
+ *
+ * Use the dedicated helpers (`reportPinMismatch`, future
+ * `reportRootDetected`, …) when their shape applies — the dashboard
+ * renders kind-specific panels off the well-known kinds.
+ */
+export async function reportSecurity(
+  kind: string,
+  data: SecurityReportData = {},
+): Promise<null | string> {
+  if (!isInitialized()) return null;
+  if (typeof kind !== 'string' || kind.length === 0 || kind.length > 100) {
+    return null;
+  }
+  if (Object.keys(data).length > 40) return null;
+
+  const config = getConfig();
+  if (!config) return null;
+  const body = {
+    kind,
+    data,
+    ts: new Date().toISOString(),
+    userId: getCurrentUserId(),
+    installId: peekInstallId() ?? undefined,
+    release: config.release,
+    environment: config.environment,
+  };
+  try {
+    const resp = await fetch(`${config.ingestUrl}/v1/security:report`, {
+      body: JSON.stringify(body),
+      headers: {
+        Authorization: `Bearer ${config.token}`,
+        'Content-Type': 'application/json',
+        'Sentori-Sdk': `react-native/${SDK_VERSION}`,
+      },
+      method: 'POST',
+    });
+    if (!resp.ok) return null;
+    const parsed = (await resp.json().catch(() => null)) as null | { id?: string };
+    return parsed?.id ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * v1.1 chunk S4 — link the current device's user / install to a
+ * federated identity (e.g. a Google sub or Apple `sub`). Idempotent;
+ * call on every sign-in. Posts to `/v1/security/link`. The dashboard
+ * uses this to stitch the same user across projects in the Posture
+ * cross-project view.
+ *
+ * Privacy: only the opaque OAuth `subject` value travels. Never pass
+ * the email, display name, avatar, or any other identity attribute.
+ */
+export async function linkFederatedIdentity(args: {
+  provider: string;
+  subject: string;
+  userId?: string;
+}): Promise<boolean> {
+  if (!args || typeof args.provider !== 'string' || args.provider.length === 0) return false;
+  if (typeof args.subject !== 'string' || args.subject.length === 0) return false;
+  if (!isInitialized()) return false;
+  const config = getConfig();
+  if (!config) return false;
+  const installId = peekInstallId() ?? undefined;
+  const body = {
+    provider: args.provider,
+    subject: args.subject,
+    userId: args.userId ?? getCurrentUserId(),
+    installId,
+  };
+  try {
+    const resp = await fetch(`${config.ingestUrl}/v1/security/link`, {
+      body: JSON.stringify(body),
+      headers: {
+        Authorization: `Bearer ${config.token}`,
+        'Content-Type': 'application/json',
+        'Sentori-Sdk': `react-native/${SDK_VERSION}`,
+      },
+      method: 'POST',
+    });
+    return resp.ok;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * TLS certificate pin mismatch — caller observed a server cert that
+ * didn't match the configured pin set. Posts `kind = 'pin.mismatch'`
+ * with the expected + observed pin (or hash) so the dashboard's
+ * Pin anomaly panel can cluster reports by server.
+ */
+export async function reportPinMismatch(args: {
+  expected: string;
+  observed: string;
+  /** Hostname the SDK was connecting to. Used by the dashboard to
+   *  cluster reports per server. */
+  serverName: string;
+}): Promise<null | string> {
+  if (!args || typeof args.serverName !== 'string' || args.serverName.length === 0) {
+    return null;
+  }
+  // The serverName rides on the top-level envelope (column-typed on
+  // the server) so dashboard queries don't need to crack the data
+  // JSONB. We still echo it inside `data` for self-contained payloads.
+  if (!isInitialized()) return null;
+  const config = getConfig();
+  if (!config) return null;
+  const body = {
+    kind: 'pin.mismatch',
+    serverName: args.serverName,
+    ts: new Date().toISOString(),
+    userId: getCurrentUserId(),
+    installId: peekInstallId() ?? undefined,
+    release: config.release,
+    environment: config.environment,
+    data: {
+      expected: args.expected,
+      observed: args.observed,
+    },
+  };
+  try {
+    const resp = await fetch(`${config.ingestUrl}/v1/security:report`, {
+      body: JSON.stringify(body),
+      headers: {
+        Authorization: `Bearer ${config.token}`,
+        'Content-Type': 'application/json',
+        'Sentori-Sdk': `react-native/${SDK_VERSION}`,
+      },
+      method: 'POST',
+    });
+    if (!resp.ok) return null;
+    const parsed = (await resp.json().catch(() => null)) as null | { id?: string };
+    return parsed?.id ?? null;
+  } catch {
+    return null;
+  }
+}

package/src/track.ts

@@ -0,0 +1,114 @@
+// v1.1 chunk B — analytics `track` events on the SDK side.
+//
+// `sentori.track(name, props?)` pushes a single typed analytics event
+// into a fixed-size ring. A timer flushes the ring every 30 s (or
+// when the buffer hits 500) to `POST /v1/track:batch`. Best-effort;
+// a flush failure drops the batch — analytics aren't critical
+// telemetry.
+//
+// Why not one fetch per event: a busy app emitting `$pageview` +
+// custom funnel events every nav would saturate the JS thread and
+// the host's outbound connection pool. The same batching shape the
+// metrics module uses keeps `track()` cheap to call from render
+// hooks.
+//
+// Auto-pageview (`$pageview`) is emitted from `useTraceNavigation`
+// in navigation.ts whenever react-navigation swaps the active route.
+// Hosts that don't use react-navigation can call
+// `sentori.track('$pageview', { route: 'Cart' })` themselves.
+
+import { getCurrentUserId } from './capture';
+import { getConfig, isInitialized } from './config';
+import { sendTrackBatch } from './transport';
+
+export type TrackProps = Record<string, unknown>;
+
+export type TrackEvent = {
+  environment?: string;
+  name: string;
+  props?: TrackProps;
+  release?: string;
+  route?: string;
+  sessionId?: string;
+  ts: string;
+  userId?: string;
+};
+
+const MAX_BUFFER = 500;
+const NAME_MAX = 200;
+const PROPS_KEYS_MAX = 40;
+const FLUSH_INTERVAL_MS = 30_000;
+
+let _buf: TrackEvent[] = [];
+let _timer: null | ReturnType<typeof setInterval> = null;
+
+/**
+ * Record a typed analytics event. Cheap to call from render hooks —
+ * pushes into a 500-slot ring drained every 30 s (or on overflow) by
+ * the transport flusher.
+ *
+ * Reserved names start with `$` (e.g. `$pageview`) and are emitted by
+ * the SDK itself; you can still call `track('$pageview', …)` from app
+ * code to backfill routes the auto-instrumentation missed.
+ *
+ * Server caps: name ≤ 200 chars, ≤ 40 prop keys. Calls exceeding the
+ * cap are dropped client-side (no throw) so app code can fire-and-
+ * forget without try/catch.
+ */
+export function track(name: string, props?: TrackProps, route?: string): void {
+  if (!isInitialized()) return;
+  if (typeof name !== 'string' || name.length === 0 || name.length > NAME_MAX) {
+    return;
+  }
+  if (props && Object.keys(props).length > PROPS_KEYS_MAX) {
+    return;
+  }
+  const config = getConfig();
+  const ev: TrackEvent = {
+    name,
+    props,
+    release: config?.release,
+    environment: config?.environment,
+    route,
+    ts: new Date().toISOString(),
+    userId: getCurrentUserId(),
+  };
+  _buf.push(ev);
+  if (_buf.length >= MAX_BUFFER) {
+    void flushTrack();
+  }
+}
+
+export async function flushTrack(): Promise<void> {
+  if (_buf.length === 0) return;
+  const config = getConfig();
+  if (!config) return;
+  const batch = _buf;
+  _buf = [];
+  await sendTrackBatch(config.ingestUrl, config.token, batch);
+}
+
+/**
+ * Start the 30 s flush timer. Called once from `init()`. Idempotent.
+ * `__resetTrackForTests` is exposed for vitest / bun:test teardown.
+ */
+export function startTrackTimer(): void {
+  if (_timer !== null) return;
+  _timer = setInterval(() => {
+    void flushTrack();
+  }, FLUSH_INTERVAL_MS);
+  // Don't keep the process alive solely for this timer.
+  (_timer as unknown as { unref?: () => void }).unref?.();
+}
+
+export function __peekTrackBuffer(): readonly TrackEvent[] {
+  return _buf;
+}
+
+export function __resetTrackForTests(): void {
+  if (_timer !== null) {
+    clearInterval(_timer);
+    _timer = null;
+  }
+  _buf = [];
+}

package/src/transport.ts

@@ -263,6 +263,41 @@ export const sendSessionPing = async (
   }
 };
 
+/**
+ * v1.1 chunk B — flush a batched set of `sentori.track()` analytics
+ * events. The host SDK batches calls into a fixed-size ring drained
+ * every 30 s. Best-effort; a failure drops the batch.
+ */
+export const sendTrackBatch = async (
+  ingestUrl: string,
+  token: string,
+  events: Array<{
+    environment?: string;
+    name: string;
+    props?: Record<string, unknown>;
+    release?: string;
+    route?: string;
+    sessionId?: string;
+    ts: string;
+    userId?: string;
+  }>,
+): Promise<void> => {
+  if (events.length === 0) return;
+  try {
+    await fetch(`${ingestUrl}/v1/track:batch`, {
+      body: JSON.stringify({ events }),
+      headers: {
+        Authorization: `Bearer ${token}`,
+        'Content-Type': 'application/json',
+        'Sentori-Sdk': `react-native/${SDK_VERSION}`,
+      },
+      method: 'POST',
+    });
+  } catch {
+    // best-effort
+  }
+};
+
 /**
  * v0.8.3 — flush a batched set of custom metrics. The host SDK
  * batches recordMetric() calls into a fixed-size ring (drained on

package/src/trust-score.ts

@@ -0,0 +1,176 @@
+// v1.1 chunk S3 — `sentori.queryTrustScore()` for the host app.
+//
+// Returns the device's current trust score (0–100, higher = healthier)
+// plus the per-kind signal mix that produced it. The host app uses
+// this to decide whether to step up authentication, decline a
+// purchase, or simply log a soft warning.
+//
+// Caching:
+//   L1 — process-memory, ~30 s. Same process should not re-fetch on
+//        every screen render; the score moves on a "minutes" cadence.
+//   L2 — install-id-derived AsyncStorage entry, ~5 minutes. Lets the
+//        host paint a cached score on cold start without waiting for
+//        the network. Stale entries are still served; the SDK
+//        re-fetches in the background.
+//
+// Fail-soft posture: if the network's down or the SDK isn't
+// initialised, returns the cached value (if any), else the safe
+// default (score = 100). The host should never see a thrown error
+// from this call — the score system is supposed to be invisible.
+
+import { isAnyNativeModuleLinked } from './native-loader';
+import { getConfig, isInitialized } from './config';
+import { getInstallId } from './install-id';
+
+const SDK_VERSION = '0.0.0';
+const STORAGE_KEY = '@sentori/trust-score';
+const L1_TTL_MS = 30_000;
+const L2_TTL_MS = 5 * 60_000;
+
+export type TrustSignal = {
+  count: number;
+  kind: string;
+  weight: number;
+};
+
+export type TrustScore = {
+  computedAt: string;
+  installId: string;
+  score: number;
+  signals: TrustSignal[];
+};
+
+type CacheEntry = { fetchedAt: number; score: TrustScore };
+
+type AsyncStorageLike = {
+  getItem: (key: string) => Promise<null | string>;
+  setItem: (key: string, value: string) => Promise<void>;
+};
+
+let _l1: null | CacheEntry = null;
+let _inflight: null | Promise<TrustScore> = null;
+
+function loadAsyncStorage(): AsyncStorageLike | null {
+  if (!isAnyNativeModuleLinked(['RNCAsyncStorage', 'AsyncStorageModule'])) return null;
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const mod = require('@react-native-async-storage/async-storage') as {
+      default?: AsyncStorageLike;
+    };
+    return mod.default ?? (mod as unknown as AsyncStorageLike);
+  } catch {
+    return null;
+  }
+}
+
+function safeDefault(installId: string): TrustScore {
+  return {
+    computedAt: new Date().toISOString(),
+    installId,
+    score: 100,
+    signals: [],
+  };
+}
+
+async function readL2(): Promise<null | CacheEntry> {
+  const storage = loadAsyncStorage();
+  if (!storage) return null;
+  try {
+    const raw = await storage.getItem(STORAGE_KEY);
+    if (!raw) return null;
+    const parsed = JSON.parse(raw) as CacheEntry;
+    if (
+      typeof parsed?.fetchedAt !== 'number' ||
+      typeof parsed?.score?.score !== 'number'
+    ) {
+      return null;
+    }
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+async function writeL2(entry: CacheEntry): Promise<void> {
+  const storage = loadAsyncStorage();
+  if (!storage) return;
+  try {
+    await storage.setItem(STORAGE_KEY, JSON.stringify(entry));
+  } catch {
+    // best-effort
+  }
+}
+
+async function fetchFresh(installId: string): Promise<TrustScore> {
+  const config = getConfig();
+  if (!config) return safeDefault(installId);
+  try {
+    const resp = await fetch(
+      `${config.ingestUrl}/v1/security/score?installId=${encodeURIComponent(installId)}`,
+      {
+        headers: {
+          Authorization: `Bearer ${config.token}`,
+          'Sentori-Sdk': `react-native/${SDK_VERSION}`,
+        },
+        method: 'GET',
+      }
+    );
+    if (!resp.ok) return safeDefault(installId);
+    const parsed = (await resp.json()) as TrustScore;
+    return parsed;
+  } catch {
+    return safeDefault(installId);
+  }
+}
+
+/**
+ * Resolve the device's trust score. Always resolves — never throws,
+ * never rejects. The two-layer cache means the first call after cold
+ * start usually serves a < 1 ms result while a background refresh
+ * keeps the value current.
+ */
+export async function queryTrustScore(): Promise<TrustScore> {
+  if (!isInitialized()) {
+    const id = await getInstallId();
+    return safeDefault(id);
+  }
+  // L1 hit
+  const now = Date.now();
+  if (_l1 && now - _l1.fetchedAt < L1_TTL_MS) {
+    return _l1.score;
+  }
+  // Coalesce concurrent calls onto the same inflight fetch.
+  if (_inflight) return _inflight;
+
+  _inflight = (async () => {
+    try {
+      const installId = await getInstallId();
+      // L2 hit — serve immediately, kick off background refresh
+      const l2 = await readL2();
+      if (l2 && now - l2.fetchedAt < L2_TTL_MS && l2.score.installId === installId) {
+        _l1 = l2;
+        // background refresh (don't block caller)
+        void (async () => {
+          const fresh = await fetchFresh(installId);
+          const entry: CacheEntry = { fetchedAt: Date.now(), score: fresh };
+          _l1 = entry;
+          await writeL2(entry);
+        })();
+        return l2.score;
+      }
+      const fresh = await fetchFresh(installId);
+      const entry: CacheEntry = { fetchedAt: Date.now(), score: fresh };
+      _l1 = entry;
+      await writeL2(entry);
+      return fresh;
+    } finally {
+      _inflight = null;
+    }
+  })();
+  return _inflight;
+}
+
+export function __resetTrustScoreForTests(): void {
+  _l1 = null;
+  _inflight = null;
+}