@apitap/core 1.0.0

package/src/capture/oauth-detector.ts

@@ -0,0 +1,106 @@
+// src/capture/oauth-detector.ts
+
+export interface OAuthInfo {
+  tokenEndpoint: string;
+  clientId: string;
+  grantType: 'refresh_token' | 'client_credentials';
+  scope?: string;
+  clientSecret?: string;
+}
+
+/**
+ * Detect OAuth2 token endpoint requests from captured traffic.
+ * Only recognizes refreshable flows (refresh_token, client_credentials).
+ * Ignores authorization_code (initial auth, not refreshable in isolation).
+ */
+export function isOAuthTokenRequest(req: {
+  url: string;
+  method: string;
+  headers: Record<string, string>;
+  postData?: string;
+}): OAuthInfo | null {
+  // Only POST requests
+  if (req.method.toUpperCase() !== 'POST') return null;
+
+  // URL heuristic: must contain /token or /oauth
+  const urlLower = req.url.toLowerCase();
+  if (!urlLower.includes('/token') && !urlLower.includes('/oauth')) return null;
+
+  if (!req.postData) return null;
+
+  // Parse body — support URL-encoded and JSON
+  const params = parseBody(req.postData, req.headers['content-type'] ?? '');
+  if (!params) return null;
+
+  const grantType = params.get('grant_type');
+  if (!grantType) return null;
+
+  // Only refreshable flows
+  if (grantType !== 'refresh_token' && grantType !== 'client_credentials') return null;
+
+  // Extract client_id — may also be in Basic auth header
+  let clientId = params.get('client_id') ?? '';
+  let clientSecret = params.get('client_secret');
+
+  if (!clientId) {
+    const basic = parseBasicAuth(req.headers['authorization'] ?? '');
+    if (basic) {
+      clientId = basic.username;
+      if (!clientSecret) clientSecret = basic.password;
+    }
+  }
+
+  if (!clientId) return null;
+
+  const result: OAuthInfo = {
+    tokenEndpoint: req.url.split('?')[0]!, // strip query params
+    clientId,
+    grantType: grantType as 'refresh_token' | 'client_credentials',
+  };
+
+  const scope = params.get('scope');
+  if (scope) result.scope = scope;
+  if (clientSecret) result.clientSecret = clientSecret;
+
+  return result;
+}
+
+function parseBody(body: string, contentType: string): Map<string, string> | null {
+  try {
+    if (contentType.includes('application/json')) {
+      const obj = JSON.parse(body);
+      if (typeof obj !== 'object' || obj === null) return null;
+      const map = new Map<string, string>();
+      for (const [k, v] of Object.entries(obj)) {
+        if (typeof v === 'string') map.set(k, v);
+      }
+      return map;
+    }
+
+    // Default: URL-encoded (+ is space in application/x-www-form-urlencoded)
+    const map = new Map<string, string>();
+    const pairs = body.split('&');
+    for (const pair of pairs) {
+      const idx = pair.indexOf('=');
+      if (idx === -1) continue;
+      const key = decodeURIComponent(pair.slice(0, idx).replace(/\+/g, ' '));
+      const val = decodeURIComponent(pair.slice(idx + 1).replace(/\+/g, ' '));
+      map.set(key, val);
+    }
+    return map.size > 0 ? map : null;
+  } catch {
+    return null;
+  }
+}
+
+function parseBasicAuth(header: string): { username: string; password: string } | null {
+  if (!header.startsWith('Basic ')) return null;
+  try {
+    const decoded = Buffer.from(header.slice(6), 'base64').toString('utf-8');
+    const idx = decoded.indexOf(':');
+    if (idx === -1) return null;
+    return { username: decoded.slice(0, idx), password: decoded.slice(idx + 1) };
+  } catch {
+    return null;
+  }
+}

package/src/capture/pagination.ts

@@ -0,0 +1,49 @@
+// src/capture/pagination.ts
+import type { PaginationInfo } from '../types.js';
+
+const OFFSET_PARAMS = new Set(['offset', 'skip']);
+const CURSOR_PARAMS = new Set(['cursor', 'after', 'before', 'next_cursor', 'starting_after']);
+const PAGE_PARAMS = new Set(['page', 'p', 'page_number']);
+const LIMIT_PARAMS = new Set(['limit', 'per_page', 'page_size', 'count', 'size']);
+
+/**
+ * Detect pagination patterns from query parameters.
+ * Returns null if no pagination pattern is detected.
+ */
+export function detectPagination(
+  queryParams: Record<string, { type: string; example: string }>,
+): PaginationInfo | null {
+  const paramNames = Object.keys(queryParams);
+  const limitParam = paramNames.find(p => LIMIT_PARAMS.has(p.toLowerCase()));
+
+  // Check offset-based (offset/skip + optional limit)
+  for (const name of paramNames) {
+    if (OFFSET_PARAMS.has(name.toLowerCase())) {
+      return {
+        type: 'offset',
+        paramName: name,
+        ...(limitParam ? { limitParam } : {}),
+      };
+    }
+  }
+
+  // Check cursor-based
+  for (const name of paramNames) {
+    if (CURSOR_PARAMS.has(name.toLowerCase())) {
+      return { type: 'cursor', paramName: name };
+    }
+  }
+
+  // Check page-based
+  for (const name of paramNames) {
+    if (PAGE_PARAMS.has(name.toLowerCase())) {
+      return {
+        type: 'page',
+        paramName: name,
+        ...(limitParam && limitParam !== name ? { limitParam } : {}),
+      };
+    }
+  }
+
+  return null;
+}

package/src/capture/parameterize.ts

@@ -0,0 +1,68 @@
+// src/capture/parameterize.ts
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const PURE_NUMERIC_RE = /^\d+$/;
+const LONG_DIGITS_RE = /\d{8,}/;
+const NEXT_DATA_PREFIX_RE = /^\/_next\/data\/[^/]+\//;
+
+/**
+ * Check if a path segment is a dynamic value that should be parameterized.
+ * Returns the parameter name (:id, :hash, :slug) or null if static.
+ */
+function classifySegment(segment: string): string | null {
+  // Pure numeric → :id
+  if (PURE_NUMERIC_RE.test(segment)) return ':id';
+
+  // UUID → :id
+  if (UUID_RE.test(segment)) return ':id';
+
+  // Slug with embedded long number (8+ consecutive digits) — check before hash
+  // because slugs like "btc-updown-15m-1770254100" would also match the hash rule
+  if (LONG_DIGITS_RE.test(segment)) {
+    return ':slug';
+  }
+
+  // Strip hyphens/underscores for character analysis
+  const stripped = segment.replace(/[-_]/g, '');
+
+  // Hash-like: 12+ alphanumeric chars with both letters and digits
+  if (stripped.length >= 12 && /[a-zA-Z]/.test(stripped) && /\d/.test(stripped)) {
+    return ':hash';
+  }
+
+  return null;
+}
+
+/**
+ * Replace dynamic path segments with :param placeholders.
+ *
+ * Rules:
+ * - Pure numeric → :id
+ * - UUID → :id
+ * - 12+ alphanum with mixed letters+digits → :hash
+ * - Contains 8+ consecutive digits → :slug
+ */
+export function parameterizePath(path: string): string {
+  const segments = path.split('/');
+  const result = segments.map(seg => {
+    if (seg === '') return seg;
+    return classifySegment(seg) ?? seg;
+  });
+  return result.join('/');
+}
+
+/**
+ * Strip framework-specific path noise for clean endpoint IDs.
+ *
+ * - Strips /_next/data/<hash>/ prefix (Next.js data routes)
+ * - Strips .json suffix
+ */
+export function cleanFrameworkPath(path: string): string {
+  let cleaned = path;
+  // Strip _next/data/<hash>/ prefix
+  cleaned = cleaned.replace(NEXT_DATA_PREFIX_RE, '/');
+  // Strip .json suffix
+  cleaned = cleaned.replace(/\.json$/, '');
+  // Ensure we have at least /
+  return cleaned || '/';
+}

package/src/capture/scrubber.ts

@@ -0,0 +1,49 @@
+// src/capture/scrubber.ts
+
+// Email: standard pattern
+const EMAIL_RE = /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g;
+
+// Phone (international): requires + prefix
+const PHONE_INTL_RE = /\+[1-9]\d{7,14}/g;
+
+// Phone (US): requires separators — (123) 456-7890 or 123-456-7890 or 123.456.7890
+const PHONE_US_RE = /\(\d{3}\)[-.\s]\d{3}[-.\s]\d{4}|\d{3}[-.\s]\d{3}[-.\s]\d{4}/g;
+
+// IPv4: four octets, each 0-255, validated programmatically
+const IPV4_RE = /\b(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})\b/g;
+
+// Credit card: 16 digits with optional dashes or spaces every 4
+const CARD_RE = /\b\d{4}[- ]?\d{4}[- ]?\d{4}[- ]?\d{4}\b/g;
+
+// US SSN: 123-45-6789
+const SSN_RE = /\b\d{3}-\d{2}-\d{4}\b/g;
+
+/**
+ * Scrub PII from a string. Returns the string with PII replaced by placeholders.
+ * Order matters: SSN before phone (SSN is more specific).
+ */
+export function scrubPII(input: string): string {
+  let result = input;
+
+  // Email first (most distinctive pattern)
+  result = result.replace(EMAIL_RE, '[email]');
+
+  // SSN before phone (SSN pattern 123-45-6789 could be confused)
+  result = result.replace(SSN_RE, '[ssn]');
+
+  // Credit cards
+  result = result.replace(CARD_RE, '[card]');
+
+  // IPv4 with octet validation
+  result = result.replace(IPV4_RE, (_match, o1, o2, o3, o4) => {
+    const octets = [o1, o2, o3, o4].map(Number);
+    if (octets.every(o => o <= 255)) return '[ip]';
+    return _match;
+  });
+
+  // Phone (international, then US)
+  result = result.replace(PHONE_INTL_RE, '[phone]');
+  result = result.replace(PHONE_US_RE, '[phone]');
+
+  return result;
+}