@stll/anonymize-mcp 0.0.1-placeholder.0 → 2.4.0

package/LICENSE

@@ -0,0 +1,17 @@
+Apache License
+Version 2.0, January 2004
+https://www.apache.org/licenses/LICENSE-2.0
+
+Copyright 2026 stella labs, s.r.o.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    https://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,160 @@
+# `@stll/anonymize-mcp`
+
+Local, path-only MCP tools for stella anonymization. The server uses stdio only,
+performs no network I/O, accepts no document text in tool arguments, and never
+returns document text or plaintext session mappings.
+
+Requires Node.js 20 or newer. This requirement applies to the MCP package only;
+its native advisory-lock loader does not support Node.js 18.
+
+```json
+{
+  "mcpServers": {
+    "stella-anonymize": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@stll/anonymize-mcp",
+        "--root",
+        "/absolute/path/to/workspace",
+        "--pdftoppm",
+        "/absolute/path/to/pdftoppm",
+        "--tesseract",
+        "/absolute/path/to/tesseract"
+      ]
+    }
+  }
+}
+```
+
+Repeat `--root` to allow more than one directory. Inputs and outputs must be
+absolute paths within those roots. Outputs must be explicit new paths; the
+server refuses overwrites and writes with owner-only permissions. Text must be
+valid UTF-8; text and DOCX inputs are limited to 64 MiB. A server process holds
+at most 256 in-memory sessions.
+
+Tools:
+
+- `capabilities` (public manifest and MCP metadata only)
+- `anonymize_text_file`
+- `anonymize_text_file_with_external_detections`
+- `restore_text_file`
+- `anonymize_docx_file`
+- `anonymize_pdf_file`
+- `restore_docx_file`
+- `inspect_docx_file`
+
+`anonymize_pdf_file` accepts only absolute input/output PDF paths inside the
+configured roots plus bounded raster options and one explicit Tesseract language
+pack. Executable paths are server startup configuration and never tool input.
+The tool renders and OCRs locally, then publishes a fresh image-only PDF; it
+never overlays or copies source PDF objects. Its response contains aggregate
+page/detection/region counts and structural verification only—never document
+text, spans, mappings, or a claim of perfect OCR/detector recall. The certificate
+always reports `piiCleanGuaranteed=false`.
+
+By default, sessions live only in the MCP server process. Restoration therefore
+requires the same `sessionId` and the same running process that performed
+anonymization. Stopping the server discards mappings.
+
+## External detection sidecars
+
+`anonymize_text_file_with_external_detections` merges native detections with a
+provider-neutral `ExternalDetectionBatch` v1 JSON sidecar. The tool accepts only
+an input `.txt` path, sidecar `.json` path, new output `.txt` path, `sessionId`,
+and the same optional in-memory `language`; it never accepts or returns document
+content, spans, mappings, or provider payloads. Both inputs must be inside the
+configured roots. Text is capped at 64 MiB and the sidecar at 16 MiB.
+
+A model-neutral local workflow is:
+
+1. An application-owned fake or real provider reads the local text file.
+2. It writes a closed-schema v1 sidecar containing the exact document SHA-256,
+   one declared offset unit, explicit label mappings, and non-PII provenance
+   IDs.
+3. The MCP client calls the external-detection tool with paths only.
+4. stella validates the digest/schema/offset boundaries, runs native detection,
+   merges both sources through the normal session pipeline, and publishes only
+   the anonymized file plus aggregate counts.
+
+This package includes no GLiNER dependency or model runner. A fake provider is
+enough for deterministic integration tests; any real provider remains outside
+the MCP trust boundary. Stale digests, unknown fields, invalid boundaries,
+unsafe paths, and oversized sidecars fail before output publication. In durable
+mode the tool uses the full package and rejects `language`, exactly like the
+ordinary text tool.
+
+Failures from this tool cross the MCP boundary only as fixed audit-safe error
+codes and messages. Parser, provider, label, document, path, native-plan, and
+storage details are never copied into tool errors or logs.
+
+## Encrypted durable sessions
+
+Durable sessions are opt-in. Supply both an existing absolute private session
+directory and an existing absolute private key file; supplying only one fails
+startup:
+
+```json
+{
+  "mcpServers": {
+    "stella-anonymize": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@stll/anonymize-mcp",
+        "--root",
+        "/absolute/path/to/workspace",
+        "--session-dir",
+        "/absolute/private/path/to/sessions",
+        "--key-file",
+        "/absolute/private/path/to/session.key"
+      ]
+    }
+  }
+}
+```
+
+The key file format is exactly 32 raw bytes; text, hexadecimal, base64, and
+password-derived keys are not accepted. The key file must be a regular,
+owner-owned file with no group or other permissions. The session directory must
+already exist, be owner-owned, grant no group or other permissions, and contain
+no symbolic-link path components. Generate and protect the key outside the MCP
+server; losing it makes archives unrecoverable, while disclosure permits anyone
+with the archives to recover mappings.
+
+Durable mode currently supports macOS and Linux only. Startup fails closed on
+other platforms because the server requires POSIX owner identities,
+`O_NOFOLLOW`, directory handles and `fsync`, plus process-lifetime advisory file
+locks. One server exclusively locks the whole session directory; a second
+server fails startup, and the operating system releases the lock if the holder
+exits or crashes. The persistent `.stella-session.lock` file contains no session
+metadata and is not itself proof that a live process holds the lock.
+
+The server stores only bounded, authenticated encrypted session archives. It
+never writes plaintext mappings or includes key material in tools, results, or
+logs. Archive filenames are SHA-256 hashes of validated session IDs. Writes are
+owner-only and atomically replace the preceding archive. The archive is made
+durable before its corresponding output is published. If output publication
+fails, the server rolls both memory and durable storage back to the preceding
+successful state, or deletes a newly created session. If rollback storage itself
+fails, the in-memory copy is discarded and later work must reload and
+authenticate whichever atomic archive remains. At most 256 archives and 256 MiB
+of archive data are accepted. Restore authenticates the expected session ID and
+evaluates lifecycle expiry at the current time. A wrong key, tampered archive,
+expired session, unsafe path, partial write, or permission change fails closed.
+
+The encrypted core archive intentionally contains session state, not MCP
+pipeline-selection metadata. To keep pipeline identity stable across restarts,
+durable sessions always use the full all-language package and reject a
+`language` argument. In-memory sessions retain the existing language-scoped
+behavior. This avoids unauthenticated sidecar metadata and never guesses which
+language package created an archive.
+
+Transport closure, `SIGINT`, and `SIGTERM` stop new work, drain active
+operations, close the durable store, release its advisory lock, and zero the
+in-memory key before the process exits.
+
+Tool results contain only aggregate, audit-safe counts and statuses. The
+read-only `capabilities` tool returns `CAPABILITY_MANIFEST`, the native runtime
+version, tool and format lists, stdio transport metadata, and either `memory` or
+`durable-encrypted` session mode; it never returns document or session data.

package/dist/index.d.mts

@@ -0,0 +1,172 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod/v4";
+//#region src/durable-sessions.d.ts
+declare const SESSION_ARCHIVE_KEY_BYTES = 32;
+declare const SESSION_ARCHIVE_MAX_BYTES: number;
+declare const SESSION_ARCHIVE_MAX_COUNT = 256;
+declare const SESSION_ARCHIVE_TOTAL_MAX_BYTES: number;
+declare const DURABLE_SESSION_FAULT_POINTS: {
+  readonly beforeDirectoryFsync: "before-directory-fsync";
+  readonly beforeRename: "before-rename";
+  readonly beforeStagingFsync: "before-staging-fsync";
+  readonly beforeStagingWrite: "before-staging-write";
+};
+type DurableSessionFaultPoint = (typeof DURABLE_SESSION_FAULT_POINTS)[keyof typeof DURABLE_SESSION_FAULT_POINTS];
+type DurableSessionStoreOptions = {
+  faultInjector?: (point: DurableSessionFaultPoint) => Promise<void> | void;
+  keyFile: string;
+  sessionDirectory: string;
+};
+type StoredSessionArchive = {
+  bytes: Uint8Array;
+};
+type EncryptableSession = {
+  toEncryptedArchiveAt(key: Uint8Array, observedAtEpochSeconds: number): Uint8Array;
+};
+type EncryptedSessionRestorer<Session> = {
+  restoreEncryptedRedactionSession(options: {
+    archive: Uint8Array;
+    expectedSessionId: string;
+    key: Uint8Array;
+    observedAtEpochSeconds: number;
+  }): Session;
+};
+type RestoreStoredSessionOptions<Session> = {
+  archive: Uint8Array;
+  expectedSessionId: string;
+  observedAtEpochSeconds: number;
+  restorer: EncryptedSessionRestorer<Session>;
+};
+declare class DurableSessionStore {
+  #private;
+  private constructor();
+  static create({ keyFile, sessionDirectory, faultInjector }: DurableSessionStoreOptions): Promise<DurableSessionStore>;
+  seal(session: EncryptableSession, observedAtEpochSeconds: number): Uint8Array;
+  restore<Session>({ archive, expectedSessionId, observedAtEpochSeconds, restorer }: RestoreStoredSessionOptions<Session>): Session;
+  close(): Promise<void>;
+  load(sessionId: string): Promise<StoredSessionArchive | undefined>;
+  save(sessionId: string, archive: Uint8Array): Promise<void>;
+  delete(sessionId: string): Promise<void>;
+}
+//#endregion
+//#region src/local.d.ts
+declare const MCP_SESSION_MODES: {
+  readonly durableEncrypted: "durable-encrypted";
+  readonly memory: "memory";
+};
+type McpSessionMode = (typeof MCP_SESSION_MODES)[keyof typeof MCP_SESSION_MODES];
+type AuditSafeResult = {
+  operation: "anonymize" | "inspect" | "restore";
+  format: "docx" | "pdf" | "text";
+  outputCreated: boolean;
+  sessionId?: string;
+  entityCount?: number;
+  blockCount?: number;
+  rewrittenBlockCount?: number;
+  restoredPlaceholderCount?: number;
+  coverageStatus?: "full" | "partial";
+  externalDetectionBatchStatus?: "accepted";
+  externalDetectionCount?: number;
+  retainedExternalDetectionCount?: number;
+  pageCount?: number;
+  mappedRegionCount?: number;
+  structurePixelRewriteVerified?: true;
+  piiCleanGuaranteed?: false;
+};
+type LocalAnonymizeServiceFaults = {
+  beforeOutputPublish?: () => void;
+};
+type ReadInputOptions = {
+  path: string;
+  extension: ".docx" | ".json" | ".pdf" | ".txt";
+  maximumBytes: number;
+  label: "DOCX" | "External detection batch" | "PDF" | "Text";
+};
+type ScopedInput = {
+  bytes: Uint8Array;
+  path: string;
+};
+type DirectoryIdentity = {
+  dev: number;
+  ino: number;
+  path: string;
+};
+declare class ScopedOutput {
+  readonly parent: DirectoryIdentity;
+  readonly path: string;
+  constructor(path: string, parent: DirectoryIdentity);
+  write(bytes: Uint8Array | string): Promise<void>;
+}
+declare class PathScope {
+  #private;
+  private constructor();
+  static create(roots: readonly string[]): Promise<PathScope>;
+  readInput({ path, extension, maximumBytes, label }: ReadInputOptions): Promise<ScopedInput>;
+  output(path: string, extension: ".docx" | ".pdf" | ".txt"): Promise<ScopedOutput>;
+}
+declare const textInput: z.ZodObject<{
+  inputPath: z.ZodString;
+  outputPath: z.ZodString;
+  sessionId: z.ZodString;
+  language: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+declare const externalDetectionTextInput: z.ZodObject<{
+  inputPath: z.ZodString;
+  outputPath: z.ZodString;
+  sessionId: z.ZodString;
+  language: z.ZodOptional<z.ZodString>;
+  detectionBatchPath: z.ZodString;
+}, z.core.$strip>;
+declare const restoreInput: z.ZodObject<{
+  inputPath: z.ZodString;
+  outputPath: z.ZodString;
+  sessionId: z.ZodString;
+}, z.core.$strip>;
+declare const docxRestoreInput: z.ZodObject<{
+  inputPath: z.ZodString;
+  outputPath: z.ZodString;
+  sessionId: z.ZodString;
+  allowPartialCoverage: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+}, z.core.$strip>;
+declare const docxInput: z.ZodObject<{
+  inputPath: z.ZodString;
+  outputPath: z.ZodString;
+  sessionId: z.ZodString;
+  language: z.ZodOptional<z.ZodString>;
+  allowPartialCoverage: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+}, z.core.$strip>;
+declare const pdfInput: z.ZodObject<{
+  inputPath: z.ZodString;
+  outputPath: z.ZodString;
+  ocrLanguage: z.ZodString;
+  detectionLanguage: z.ZodOptional<z.ZodString>;
+  dpi: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+  timeoutMs: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+  fillRgb: z.ZodDefault<z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>>>;
+}, z.core.$strip>;
+type LocalPdfProviderConfiguration = {
+  pdftoppmPath?: string | undefined;
+  tesseractPath?: string | undefined;
+};
+type LocalAnonymizeServiceOptions = {
+  durableSessions?: DurableSessionStore | undefined;
+  faults?: LocalAnonymizeServiceFaults | undefined;
+  pdfProvider?: LocalPdfProviderConfiguration | undefined;
+};
+declare class LocalAnonymizeService {
+  #private;
+  constructor(scope: PathScope, options?: LocalAnonymizeServiceOptions);
+  get sessionMode(): McpSessionMode;
+  close(): Promise<void>;
+  anonymizeText(input: z.infer<typeof textInput>): Promise<AuditSafeResult>;
+  anonymizePdf(input: z.infer<typeof pdfInput>): Promise<AuditSafeResult>;
+  restoreText(input: z.infer<typeof restoreInput>): Promise<AuditSafeResult>;
+  anonymizeTextWithExternalDetections(input: z.infer<typeof externalDetectionTextInput>): Promise<AuditSafeResult>;
+  anonymizeDocx(input: z.infer<typeof docxInput>): Promise<AuditSafeResult>;
+  restoreDocx(input: z.infer<typeof docxRestoreInput>): Promise<AuditSafeResult>;
+  inspectDocx(inputPath: string): Promise<AuditSafeResult>;
+}
+declare const createAnonymizeMcpServer: (service: LocalAnonymizeService) => McpServer;
+//#endregion
+export { type AuditSafeResult, DURABLE_SESSION_FAULT_POINTS, type DurableSessionFaultPoint, DurableSessionStore, type DurableSessionStoreOptions, type EncryptableSession, type EncryptedSessionRestorer, LocalAnonymizeService, type LocalAnonymizeServiceFaults, type LocalAnonymizeServiceOptions, type LocalPdfProviderConfiguration, MCP_SESSION_MODES, type McpSessionMode, PathScope, type RestoreStoredSessionOptions, SESSION_ARCHIVE_KEY_BYTES, SESSION_ARCHIVE_MAX_BYTES, SESSION_ARCHIVE_MAX_COUNT, SESSION_ARCHIVE_TOTAL_MAX_BYTES, type StoredSessionArchive, createAnonymizeMcpServer };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -0,0 +1,2 @@
+import { a as DURABLE_SESSION_FAULT_POINTS, c as SESSION_ARCHIVE_MAX_BYTES, i as createAnonymizeMcpServer, l as SESSION_ARCHIVE_MAX_COUNT, n as MCP_SESSION_MODES, o as DurableSessionStore, r as PathScope, s as SESSION_ARCHIVE_KEY_BYTES, t as LocalAnonymizeService, u as SESSION_ARCHIVE_TOTAL_MAX_BYTES } from "./local.mjs";
+export { DURABLE_SESSION_FAULT_POINTS, DurableSessionStore, LocalAnonymizeService, MCP_SESSION_MODES, PathScope, SESSION_ARCHIVE_KEY_BYTES, SESSION_ARCHIVE_MAX_BYTES, SESSION_ARCHIVE_MAX_COUNT, SESSION_ARCHIVE_TOTAL_MAX_BYTES, createAnonymizeMcpServer };