@lanonasis/secret-prescan

Pre-extraction security gate for the MIRA context extraction pipeline.

MIRA should only see sanitized/cataloged context, never raw transcripts by default.

What It Does

Wraps @lanonasis/privacy-sdk with three additions:

1. Value stripping — scan reports never store raw detected values. Only: type, count, confidence, hash (SHA-256, truncated), masked sample, line hint.
2. Extended secret patterns — 25+ patterns beyond built-in PII: OpenAI/Anthropic/Stripe/GitHub/AWS/GCP/Supabase/Vercel/Netlify/Slack/npm keys, JWTs, bearer tokens, private keys, connection strings, .env assignments, high-entropy strings.
3. Configurable output — reports go to ~/.hermes/private/context-scans/ by default (never iCloud-backed paths). Owner-only permissions (0o700 dirs, 0o600 files).

Pipeline Integration

Raw Source (JSONL / context files)
    ↓
secret-prescan.prescan(sdk, config) → ScanReport
    ↓
Classification: SAFE / FLAGGED / QUARANTINED
    ↓
If SAFE  → extract metadata (MIRA proceeds)
If FLAGGED → log for manual review (VERA)
If QUARANTINED → blocked, quarantine path logged

Usage

import { prescan, prescanAndSave, getSafeFiles, printSummary } from '@lanonasis/secret-prescan';
import { PrivacySDK } from '@lanonasis/privacy-sdk';

const sdk = new PrivacySDK();

// Full directory scan with report saved to disk
const reportPath = prescanAndSave(sdk, {
  target_path: '/path/to/context-convergence',
  output_dir: '~/.hermes/private/context-scans/', // optional, this is the default
});

// Or get the report object directly
const report = prescan(sdk, {
  target_path: '/path/to/project',
  exclude_patterns: ['.git', 'node_modules', 'dist'],
});

// Get files safe for MIRA extraction
const safeFiles = getSafeFiles(report);

// Print human-readable summary
printSummary(report);

Single file check

import { isSafeForExtraction } from '@lanonasis/secret-prescan';

if (isSafeForExtraction(sdk, '/path/to/session.jsonl')) {
  // Safe for MIRA to extract
} else {
  // Block extraction, log for review
}

Custom patterns

const report = prescan(sdk, {
  target_path: '/path/to/project',
  custom_patterns: [
    {
      type: 'internal-token',
      pattern: /INTERNAL_[A-Z0-9]{32}/g,
      sensitivity: 'critical',
      regulations: ['Internal'],
    },
  ],
});

Report Schema

Reports are JSON files with this structure:

{
  "version": "1.0.0",
  "scanned_at": "2026-04-12T15:30:00.000Z",
  "scan_root": "/path/to/context-convergence",
  "total_files": 142,
  "summary": {
    "safe": 135,
    "flagged": 5,
    "quarantined": 2,
    "errors": 0,
    "total_detections": 14,
    "detection_types": {
      "openai-api-key": 3,
      "stripe-secret-key": 2,
      "env-secret-assignment": 5,
      "email": 4
    }
  },
  "files": [
    {
      "path": "source/.zshrc.backup",
      "classification": "QUARANTINED",
      "detection_count": 5,
      "detections": [
        {
          "type": "stripe-secret-key",
          "confidence": 0.99,
          "hash": "a1b2c3d4e5f6g7h8",
          "masked_sample": "sk_live_************",
          "sensitivity": "critical",
          "line_hint": 47,
          "regulations": ["PCI-DSS", "Internal"]
        }
      ]
    }
  ]
}

Note: absolute_path is redacted in saved reports. Raw values are never stored.

Monorepo Placement

lan-onasis-monorepo/
├── packages/
│   ├── secret-prescan/      ← this module
│   │   ├── src/
│   │   │   ├── index.ts     # barrel export
│   │   │   ├── scanner.ts   # core logic
│   │   │   ├── patterns.ts  # 25+ secret patterns
│   │   │   └── types.ts     # type definitions
│   │   ├── package.json
│   │   └── tsconfig.json
│   └── privacy-sdk/         # scaffold (not canonical)
├── apps/
│   └── v-secure/
│       └── privacy-sdk/     # canonical SDK (published to npm)

Design Decisions

• No raw values in reports: The advanced SDK returns value in detections. This wrapper strips it and stores only hash + masked sample. This prevents secret leakage through scan artifacts.
• No iCloud-backed output paths: Default output is ~/.hermes/private/context-scans/ with 0o700 directory permissions. Desktop/Documents paths are explicitly avoided.
• No hardcoded user paths: Everything is configurable via ScanConfig. No /Users/seyederick/... assumptions.
• Peer dependency on privacy-sdk: This module wraps but does not bundle the SDK. Install both.
• Quarantine threshold: Default is 1 critical detection = QUARANTINED. Configurable per scan.