omitly-mcp 0.0.0 → 0.1.0

package/dist/paths.js

@@ -0,0 +1,77 @@
+/**
+ * Filesystem confinement for the MCP surface (threat-model prerequisite).
+ *
+ * Every path in a tool call comes from the MODEL, so an uncontained server is
+ * an arbitrary-read/-write primitive for whatever the model was talked into.
+ * All reads and writes are confined to one allowed root:
+ *
+ *   OMITLY_ALLOWED_DIR  — explicit root (recommended in the MCP config)
+ *   otherwise           — the directory the server was started in
+ *
+ * Checks resolve symlinks (realpath) before comparing, so a link inside the
+ * root that points outside it is rejected, and outputs must not clobber
+ * existing files — the model is told to pick a fresh name instead. These are
+ * guardrails against confused-deputy mistakes, not a sandbox for a hostile
+ * local user (they own the machine; see docs/THREAT-MODEL.md).
+ */
+import { existsSync, realpathSync } from "node:fs";
+import * as path from "node:path";
+/** The confinement root, resolved once at startup. */
+export function allowedRoot() {
+    const configured = process.env.OMITLY_ALLOWED_DIR?.trim();
+    const root = configured || process.cwd();
+    try {
+        return realpathSync(root);
+    }
+    catch {
+        throw new Error(`OMITLY_ALLOWED_DIR does not exist or is unreadable: ${root}. ` +
+            `Point it at the directory the agent may read/write PDFs in.`);
+    }
+}
+function within(root, target) {
+    const rel = path.relative(root, target);
+    return rel !== "" && !rel.startsWith("..") && !path.isAbsolute(rel);
+}
+function refusal(what, p, root) {
+    return new Error(`${what} "${p}" is outside the allowed directory (${root}). ` +
+        `This server only touches files under that directory; ` +
+        `set OMITLY_ALLOWED_DIR in the MCP config to change it.`);
+}
+/** Validate a model-supplied INPUT path: must exist inside the root (after
+ *  symlink resolution). Returns the resolved real path to hand to the engine. */
+export function confineInput(p, root) {
+    let real;
+    try {
+        real = realpathSync(path.resolve(root, p));
+    }
+    catch {
+        throw new Error(`input file not found: ${p}`);
+    }
+    if (!within(root, real))
+        throw refusal("input path", p, root);
+    return real;
+}
+/** Validate a model-supplied OUTPUT path: its parent must exist inside the
+ *  root, and neither the file nor its `.audit.json` sidecar may already exist
+ *  (never silently overwrite — ask the model to pick a fresh name). Returns
+ *  the resolved path to hand to the engine. */
+export function confineOutput(p, root) {
+    const resolved = path.resolve(root, p);
+    let parent;
+    try {
+        parent = realpathSync(path.dirname(resolved));
+    }
+    catch {
+        throw new Error(`output directory not found: ${path.dirname(p)}`);
+    }
+    const real = path.join(parent, path.basename(resolved));
+    if (!within(root, real))
+        throw refusal("output path", p, root);
+    for (const candidate of [real, `${real}.audit.json`]) {
+        if (existsSync(candidate)) {
+            throw new Error(`refusing to overwrite existing file: ${candidate}. Choose a new output name.`);
+        }
+    }
+    return real;
+}
+//# sourceMappingURL=paths.js.map

package/dist/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAElC,sDAAsD;AACtD,MAAM,UAAU,WAAW;IACzB,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,kBAAkB,EAAE,IAAI,EAAE,CAAC;IAC1D,MAAM,IAAI,GAAG,UAAU,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;IACzC,IAAI,CAAC;QACH,OAAO,YAAY,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CACb,uDAAuD,IAAI,IAAI;YAC7D,6DAA6D,CAChE,CAAC;IACJ,CAAC;AACH,CAAC;AAED,SAAS,MAAM,CAAC,IAAY,EAAE,MAAc;IAC1C,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACxC,OAAO,GAAG,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;AACtE,CAAC;AAED,SAAS,OAAO,CAAC,IAAY,EAAE,CAAS,EAAE,IAAY;IACpD,OAAO,IAAI,KAAK,CACd,GAAG,IAAI,KAAK,CAAC,uCAAuC,IAAI,KAAK;QAC3D,uDAAuD;QACvD,wDAAwD,CAC3D,CAAC;AACJ,CAAC;AAED;iFACiF;AACjF,MAAM,UAAU,YAAY,CAAC,CAAS,EAAE,IAAY;IAClD,IAAI,IAAY,CAAC;IACjB,IAAI,CAAC;QACH,IAAI,GAAG,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IAC7C,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CAAC,yBAAyB,CAAC,EAAE,CAAC,CAAC;IAChD,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC;QAAE,MAAM,OAAO,CAAC,YAAY,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC;IAC9D,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;+CAG+C;AAC/C,MAAM,UAAU,aAAa,CAAC,CAAS,EAAE,IAAY;IACnD,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;IACvC,IAAI,MAAc,CAAC;IACnB,IAAI,CAAC;QACH,MAAM,GAAG,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;IAChD,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CAAC,+BAA+B,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACpE,CAAC;IACD,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC;IACxD,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC;QAAE,MAAM,OAAO,CAAC,aAAa,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC;IAC/D,KAAK,MAAM,SAAS,IAAI,CAAC,IAAI,EAAE,GAAG,IAAI,aAAa,CAAC,EAAE,CAAC;QACrD,IAAI,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;YAC1B,MAAM,IAAI,KAAK,CACb,wCAAwC,SAAS,6BAA6B,CAC/E,CAAC;QACJ,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/package.json

@@ -1,8 +1,55 @@
 {
   "name": "omitly-mcp",
-  "version": "0.0.0",
-  "description": "Placeholder to seed the package name for OIDC trusted publishing. Real releases are published from CI (GitHub Actions).",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Model Context Protocol server exposing Omitly's local, verifiable PDF redaction to AI agents. Redaction runs on-device — documents are never uploaded.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "pdf",
+    "redaction",
+    "claude",
+    "ai",
+    "agent",
+    "local",
+    "privacy"
+  ],
   "license": "SEE LICENSE IN LICENSE",
-  "repository": { "type": "git", "url": "git+https://github.com/ghadmin-innisfallen-master/omitly.git" },
-  "homepage": "https://omitly.app/mcp"
+  "homepage": "https://omitly.app/mcp",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ghadmin-innisfallen-master/omitly"
+  },
+  "bin": {
+    "omitly-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.test.*",
+    "wasm",
+    "skill",
+    "README.md",
+    "LICENSE",
+    "THIRD-PARTY-NOTICES.md"
+  ],
+  "scripts": {
+    "build:wasm": "wasm-pack build ../crates/leakcheck-wasm --target nodejs --out-dir ../../omitly-mcp/wasm --release && rm -f wasm/.gitignore",
+    "build": "npm run build:wasm && tsc",
+    "start": "node dist/index.js",
+    "dev": "tsc --watch",
+    "test": "npm run build:wasm && tsc && node --test \"dist/**/*.test.js\"",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "generate-license-file": "4.2.1",
+    "typescript": "^5.5.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
 }

package/skill/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: omitly-redaction
+description: >-
+  Redact PDFs and audit redactions on-device with Omitly. Use when the user wants
+  to remove sensitive data (SSNs, emails, names, account numbers) from a PDF, check
+  whether an already-"redacted" PDF still leaks data underneath its black boxes, or
+  locate PII in a document — all without uploading the file anywhere. Triggers:
+  "redact this PDF", "is this redaction safe", "did the black boxes actually work",
+  "scrub PII from this document", "check this redacted file".
+---
+
+# Omitly redaction
+
+Omitly removes sensitive data from PDFs **on the user's machine** and proves it's
+gone. Nothing is uploaded. These tools come from the `omitly-mcp` server; they
+shell out to a local engine, so the file's bytes never leave the device.
+
+The core insight to convey to users: **a black box drawn over text is not
+redaction.** The characters stay in the file and are trivially recoverable. Omitly
+removes the underlying bytes and independently verifies each region is empty.
+
+## Pick the tool by intent
+
+- **"Did my redaction actually work?" / auditing a file someone else redacted** →
+  `check_redaction` (free, read-only). Reports any PII still in the text layer.
+  This is the fastest way to show value: run it first on a supposedly-safe file.
+
+- **"What sensitive data is in here?" (review before acting)** →
+  `find_sensitive_regions`. Returns candidates (page + coordinates + masked
+  preview). Use when the user wants to confirm before anything is removed.
+
+- **"Redact these specific things I name" (names, addresses, account refs)** →
+  `locate_text` to resolve their coordinates, then `redact_pdf`.
+
+- **"Just scrub the obvious PII"** → `redact_by_entity` (scan + remove + verify in
+  one step; optionally limit to `kinds` like `["ssn","card"]`).
+
+- **Redact known regions** → `redact_pdf`. **Confirm an output** → `verify_redaction`.
+
+## Rules
+
+1. **Never echo a raw sensitive value.** The tools return *masked* previews
+   (`•••-••-6789`) on purpose. Drive redaction by page + coordinates, not by
+   repeating the secret back to the user.
+2. **Detection is pattern-based, not complete.** Emails/SSNs are reliable; names,
+   addresses, and text inside scanned images need the user's own judgement or the
+   desktop app. Say so — don't imply "0 found" means "safe".
+3. **Redaction is irreversible.** For destructive `redact_*` calls, confirm the
+   source/output paths with the user and write to a *new* output file.
+4. When a `check_redaction` finds leaks, explain the fix: removing the data for
+   real (not covering it) with a verified, audited result is what the Omitly app
+   does — https://omitly.app.
+
+## Typical flow
+
+```
+user: "I redacted this in Preview — is it actually safe?"
+→ check_redaction(pdfPath)            # free audit
+   ⚠️ finds 4 SSNs still in the text layer
+→ explain: the black boxes only cover them; offer to remove for real
+→ redact_by_entity(pdfPath, outputPath, kinds:["ssn"])   # removes + verifies
+→ verify_redaction(outputPath)        # independent confirmation
+```

package/wasm/leakcheck_wasm.d.ts

@@ -0,0 +1,26 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/**
+ * Engine/version string for the page footer ("scanned locally by Omitly vX").
+ */
+export function engine_version(): string;
+
+/**
+ * Locate literal strings (names, addresses — whatever the caller's own entity
+ * recognition turns up) and return their masked positions, the wasm twin of the
+ * engine's `find_text`. Lets the standalone MCP offer `locate_text` without a
+ * native binary. `needles_json` is a JSON array of strings; returns the same
+ * `ScanResult` shape as `scan` (kind is "text").
+ */
+export function locate(bytes: Uint8Array, needles_json: string): string;
+
+/**
+ * Scan PDF bytes for residual sensitive text and return a JSON `ScanResult`.
+ *
+ * Called from JS as `scan(new Uint8Array(arrayBuffer))`. Always returns JSON;
+ * parse errors come back as `{ ok: false, error }` rather than throwing, so the
+ * UI has one code path. A non-empty `leaks` list on an *already-redacted* file
+ * is the whole point: it means the redaction only painted over the data.
+ */
+export function scan(bytes: Uint8Array): string;

package/wasm/leakcheck_wasm.js

@@ -0,0 +1,232 @@
+/* @ts-self-types="./leakcheck_wasm.d.ts" */
+
+/**
+ * Engine/version string for the page footer ("scanned locally by Omitly vX").
+ * @returns {string}
+ */
+function engine_version() {
+    let deferred1_0;
+    let deferred1_1;
+    try {
+        const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+        wasm.engine_version(retptr);
+        var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+        var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+        deferred1_0 = r0;
+        deferred1_1 = r1;
+        return getStringFromWasm0(r0, r1);
+    } finally {
+        wasm.__wbindgen_add_to_stack_pointer(16);
+        wasm.__wbindgen_export2(deferred1_0, deferred1_1, 1);
+    }
+}
+exports.engine_version = engine_version;
+
+/**
+ * Locate literal strings (names, addresses — whatever the caller's own entity
+ * recognition turns up) and return their masked positions, the wasm twin of the
+ * engine's `find_text`. Lets the standalone MCP offer `locate_text` without a
+ * native binary. `needles_json` is a JSON array of strings; returns the same
+ * `ScanResult` shape as `scan` (kind is "text").
+ * @param {Uint8Array} bytes
+ * @param {string} needles_json
+ * @returns {string}
+ */
+function locate(bytes, needles_json) {
+    let deferred3_0;
+    let deferred3_1;
+    try {
+        const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+        const ptr0 = passArray8ToWasm0(bytes, wasm.__wbindgen_export3);
+        const len0 = WASM_VECTOR_LEN;
+        const ptr1 = passStringToWasm0(needles_json, wasm.__wbindgen_export3, wasm.__wbindgen_export4);
+        const len1 = WASM_VECTOR_LEN;
+        wasm.locate(retptr, ptr0, len0, ptr1, len1);
+        var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+        var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+        deferred3_0 = r0;
+        deferred3_1 = r1;
+        return getStringFromWasm0(r0, r1);
+    } finally {
+        wasm.__wbindgen_add_to_stack_pointer(16);
+        wasm.__wbindgen_export2(deferred3_0, deferred3_1, 1);
+    }
+}
+exports.locate = locate;
+
+/**
+ * Scan PDF bytes for residual sensitive text and return a JSON `ScanResult`.
+ *
+ * Called from JS as `scan(new Uint8Array(arrayBuffer))`. Always returns JSON;
+ * parse errors come back as `{ ok: false, error }` rather than throwing, so the
+ * UI has one code path. A non-empty `leaks` list on an *already-redacted* file
+ * is the whole point: it means the redaction only painted over the data.
+ * @param {Uint8Array} bytes
+ * @returns {string}
+ */
+function scan(bytes) {
+    let deferred2_0;
+    let deferred2_1;
+    try {
+        const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+        const ptr0 = passArray8ToWasm0(bytes, wasm.__wbindgen_export3);
+        const len0 = WASM_VECTOR_LEN;
+        wasm.scan(retptr, ptr0, len0);
+        var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+        var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+        deferred2_0 = r0;
+        deferred2_1 = r1;
+        return getStringFromWasm0(r0, r1);
+    } finally {
+        wasm.__wbindgen_add_to_stack_pointer(16);
+        wasm.__wbindgen_export2(deferred2_0, deferred2_1, 1);
+    }
+}
+exports.scan = scan;
+function __wbg_get_imports() {
+    const import0 = {
+        __proto__: null,
+        __wbg_getRandomValues_cc7f052a444bb2ce: function() { return handleError(function (arg0, arg1) {
+            globalThis.crypto.getRandomValues(getArrayU8FromWasm0(arg0, arg1));
+        }, arguments); },
+        __wbindgen_object_drop_ref: function(arg0) {
+            takeObject(arg0);
+        },
+    };
+    return {
+        __proto__: null,
+        "./leakcheck_wasm_bg.js": import0,
+    };
+}
+
+function addHeapObject(obj) {
+    if (heap_next === heap.length) heap.push(heap.length + 1);
+    const idx = heap_next;
+    heap_next = heap[idx];
+
+    heap[idx] = obj;
+    return idx;
+}
+
+function dropObject(idx) {
+    if (idx < 1028) return;
+    heap[idx] = heap_next;
+    heap_next = idx;
+}
+
+function getArrayU8FromWasm0(ptr, len) {
+    ptr = ptr >>> 0;
+    return getUint8ArrayMemory0().subarray(ptr / 1, ptr / 1 + len);
+}
+
+let cachedDataViewMemory0 = null;
+function getDataViewMemory0() {
+    if (cachedDataViewMemory0 === null || cachedDataViewMemory0.buffer.detached === true || (cachedDataViewMemory0.buffer.detached === undefined && cachedDataViewMemory0.buffer !== wasm.memory.buffer)) {
+        cachedDataViewMemory0 = new DataView(wasm.memory.buffer);
+    }
+    return cachedDataViewMemory0;
+}
+
+function getStringFromWasm0(ptr, len) {
+    return decodeText(ptr >>> 0, len);
+}
+
+let cachedUint8ArrayMemory0 = null;
+function getUint8ArrayMemory0() {
+    if (cachedUint8ArrayMemory0 === null || cachedUint8ArrayMemory0.byteLength === 0) {
+        cachedUint8ArrayMemory0 = new Uint8Array(wasm.memory.buffer);
+    }
+    return cachedUint8ArrayMemory0;
+}
+
+function getObject(idx) { return heap[idx]; }
+
+function handleError(f, args) {
+    try {
+        return f.apply(this, args);
+    } catch (e) {
+        wasm.__wbindgen_export(addHeapObject(e));
+    }
+}
+
+let heap = new Array(1024).fill(undefined);
+heap.push(undefined, null, true, false);
+
+let heap_next = heap.length;
+
+function passArray8ToWasm0(arg, malloc) {
+    const ptr = malloc(arg.length * 1, 1) >>> 0;
+    getUint8ArrayMemory0().set(arg, ptr / 1);
+    WASM_VECTOR_LEN = arg.length;
+    return ptr;
+}
+
+function passStringToWasm0(arg, malloc, realloc) {
+    if (realloc === undefined) {
+        const buf = cachedTextEncoder.encode(arg);
+        const ptr = malloc(buf.length, 1) >>> 0;
+        getUint8ArrayMemory0().subarray(ptr, ptr + buf.length).set(buf);
+        WASM_VECTOR_LEN = buf.length;
+        return ptr;
+    }
+
+    let len = arg.length;
+    let ptr = malloc(len, 1) >>> 0;
+
+    const mem = getUint8ArrayMemory0();
+
+    let offset = 0;
+
+    for (; offset < len; offset++) {
+        const code = arg.charCodeAt(offset);
+        if (code > 0x7F) break;
+        mem[ptr + offset] = code;
+    }
+    if (offset !== len) {
+        if (offset !== 0) {
+            arg = arg.slice(offset);
+        }
+        ptr = realloc(ptr, len, len = offset + arg.length * 3, 1) >>> 0;
+        const view = getUint8ArrayMemory0().subarray(ptr + offset, ptr + len);
+        const ret = cachedTextEncoder.encodeInto(arg, view);
+
+        offset += ret.written;
+        ptr = realloc(ptr, len, offset, 1) >>> 0;
+    }
+
+    WASM_VECTOR_LEN = offset;
+    return ptr;
+}
+
+function takeObject(idx) {
+    const ret = getObject(idx);
+    dropObject(idx);
+    return ret;
+}
+
+let cachedTextDecoder = new TextDecoder('utf-8', { ignoreBOM: true, fatal: true });
+cachedTextDecoder.decode();
+function decodeText(ptr, len) {
+    return cachedTextDecoder.decode(getUint8ArrayMemory0().subarray(ptr, ptr + len));
+}
+
+const cachedTextEncoder = new TextEncoder();
+
+if (!('encodeInto' in cachedTextEncoder)) {
+    cachedTextEncoder.encodeInto = function (arg, view) {
+        const buf = cachedTextEncoder.encode(arg);
+        view.set(buf);
+        return {
+            read: arg.length,
+            written: buf.length
+        };
+    };
+}
+
+let WASM_VECTOR_LEN = 0;
+
+const wasmPath = `${__dirname}/leakcheck_wasm_bg.wasm`;
+const wasmBytes = require('fs').readFileSync(wasmPath);
+const wasmModule = new WebAssembly.Module(wasmBytes);
+let wasmInstance = new WebAssembly.Instance(wasmModule, __wbg_get_imports());
+let wasm = wasmInstance.exports;

package/wasm/leakcheck_wasm_bg.wasm.d.ts

@@ -0,0 +1,11 @@
+/* tslint:disable */
+/* eslint-disable */
+export const memory: WebAssembly.Memory;
+export const engine_version: (a: number) => void;
+export const locate: (a: number, b: number, c: number, d: number, e: number) => void;
+export const scan: (a: number, b: number, c: number) => void;
+export const __wbindgen_export: (a: number) => void;
+export const __wbindgen_add_to_stack_pointer: (a: number) => number;
+export const __wbindgen_export2: (a: number, b: number, c: number) => void;
+export const __wbindgen_export3: (a: number, b: number) => number;
+export const __wbindgen_export4: (a: number, b: number, c: number, d: number) => number;

package/wasm/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "leakcheck-wasm",
+  "description": "In-browser PDF redaction leak checker — wasm-bindgen wrapper over redaction-core's detector. Runs 100% client-side; no upload.",
+  "version": "0.1.0",
+  "files": [
+    "leakcheck_wasm_bg.wasm",
+    "leakcheck_wasm.js",
+    "leakcheck_wasm.d.ts"
+  ],
+  "main": "leakcheck_wasm.js",
+  "types": "leakcheck_wasm.d.ts"
+}