@anonymask/core 0.4.3 → 1.0.0

package/README.md

@@ -1,87 +1,346 @@
-# `@napi-rs/package-template`
+# @anonymask/core
 
-![https://github.com/napi-rs/package-template/actions](https://github.com/napi-rs/package-template/workflows/CI/badge.svg)
+![CI](https://github.com/gokul-viswanathan/anonymask/workflows/CI/badge.svg)
+![NPM Version](https://img.shields.io/npm/v/@anonymask/core)
+![License](https://img.shields.io/npm/l/@anonymask/core)
 
-> Template project for writing node packages with napi-rs.
+> Secure anonymization/de-anonymization library for protecting Personally Identifiable Information (PII) in Node.js applications. Built with Rust for maximum performance.
 
-# Usage
+## ✨ Features
 
-1. Click **Use this template**.
-2. **Clone** your project.
-3. Run `yarn install` to install dependencies.
-4. Run `yarn napi rename -n [@your-scope/package-name] -b [binary-name]` command under the project folder to rename your package.
+- **🚀 Blazing Fast**: Rust-powered core with < 5ms processing time
+- **🔍 Comprehensive Detection**: EMAIL, PHONE, SSN, CREDIT_CARD, IP_ADDRESS, URL
+- **🔒 Secure Placeholders**: Deterministic UUID-based anonymization
+- **🛡️ Type-Safe**: Full TypeScript support with detailed definitions
+- **⚡ Zero Dependencies**: No external runtime dependencies
+- **🧵 Thread-Safe**: Safe for concurrent use
 
-## Install this test package
+## 📦 Installation
 
 ```bash
-yarn add @napi-rs/package-template
+npm install @anonymask/core
 ```
 
-## Ability
+## 🚀 Quick Start
 
-### Build
+```javascript
+const { Anonymizer } = require("@anonymask/core");
 
-After `yarn build/npm run build` command, you can see `package-template.[darwin|win32|linux].node` file in project root. This is the native addon built from [lib.rs](./src/lib.rs).
+// Initialize with desired entity types
+const anonymizer = new Anonymizer(["email", "phone", "ssn"]);
 
-### Test
+// Anonymize text
+const text = "Contact john@email.com or call 555-123-4567. SSN: 123-45-6789";
+const result = anonymizer.anonymize(text);
 
-With [ava](https://github.com/avajs/ava), run `yarn test/npm run test` to testing native addon. You can also switch to another testing framework if you want.
+console.log(result.anonymizedText);
+// "Contact EMAIL_xxx or call PHONE_xxx. SSN: SSN_xxx"
 
-### CI
+console.log(result.mapping);
+// { EMAIL_xxx: 'john@email.com', PHONE_xxx: '555-123-4567', SSN_xxx: '123-45-6789' }
 
-With GitHub Actions, each commit and pull request will be built and tested automatically in [`node@20`, `@node22`] x [`macOS`, `Linux`, `Windows`] matrix. You will never be afraid of the native addon broken in these platforms.
+console.log(result.entities);
+// [
+//   { entity_type: 'email', value: 'john@email.com', start: 8, end: 22 },
+//   { entity_type: 'phone', value: '555-123-4567', start: 31, end: 43 },
+//   { entity_type: 'ssn', value: '123-45-6789', start: 50, end: 60 }
+// ]
 
-### Release
+// Deanonymize back to original
+const original = anonymizer.deanonymize(result.anonymized_text, result.mapping);
+console.log(original);
+// "Contact john@email.com or call 555-123-4567. SSN: 123-45-6789"
+```
 
-Release native package is very difficult in old days. Native packages may ask developers who use it to install `build toolchain` like `gcc/llvm`, `node-gyp` or something more.
+## 🎯 Supported Entity Types
 
-With `GitHub actions`, we can easily prebuild a `binary` for major platforms. And with `N-API`, we should never be afraid of **ABI Compatible**.
+| Type          | Description             | Examples                                            |
+| ------------- | ----------------------- | --------------------------------------------------- |
+| `email`       | Email addresses         | `user@domain.com`, `john.doe@company.co.uk`         |
+| `phone`       | Phone numbers           | `555-123-4567`, `555-123`, `(555) 123-4567`, `555.123.4567` |
+| `ssn`         | Social Security Numbers | `123-45-6789`, `123456789`                          |
+| `credit_card` | Credit card numbers     | `1234-5678-9012-3456`, `1234567890123456`           |
+| `ip_address`  | IP addresses            | `192.168.1.1`, `2001:0db8:85a3::8a2e:0370:7334`     |
+| `url`         | URLs                    | `https://example.com`, `http://sub.domain.org/path` |
 
-The other problem is how to deliver prebuild `binary` to users. Downloading it in `postinstall` script is a common way that most packages do it right now. The problem with this solution is it introduced many other packages to download binary that has not been used by `runtime codes`. The other problem is some users may not easily download the binary from `GitHub/CDN` if they are behind a private network (But in most cases, they have a private NPM mirror).
+## 📚 API Reference
 
-In this package, we choose a better way to solve this problem. We release different `npm packages` for different platforms. And add it to `optionalDependencies` before releasing the `Major` package to npm.
+### Constructor
 
-`NPM` will choose which native package should download from `registry` automatically. You can see [npm](./npm) dir for details. And you can also run `yarn add @napi-rs/package-template` to see how it works.
+```javascript
+const anonymizer = new Anonymizer(entityTypes: string[])
+```
 
-## Develop requirements
+- `entityTypes`: Array of entity types to detect (see supported types above)
 
-- Install the latest `Rust`
-- Install `Node.js@10+` which fully supported `Node-API`
-- Install `yarn@1.x`
+### Methods
 
-## Test in local
+#### `anonymize(text: string) => AnonymizationResult`
 
-- yarn
-- yarn build
-- yarn test
+Anonymizes the input text using automatic detection and returns detailed result.
 
-And you will see:
+**Returns:**
 
-```bash
-$ ava --verbose
+```typescript
+interface AnonymizationResult {
+  anonymizedText: string; // Text with PII replaced by placeholders
+  mapping: Record<string, string>; // Placeholder -> original value mapping
+  entities: Entity[]; // Array of detected entities with metadata
+}
+
+interface Entity {
+  entity_type: string; // Type of entity (email, phone, etc.)
+  value: string; // Original detected value
+  start: number; // Start position in original text
+  end: number; // End position in original text
+}
+```
+
+#### `anonymizeWithCustom(text: string, customEntities?: Record<string, string[]>) => AnonymizationResult`
+
+Anonymizes the input text using both automatic detection and custom entities.
+
+**Parameters:**
+- `text`: The input text to anonymize
+- `customEntities`: Optional map of entity types to arrays of custom values to anonymize
+
+**Example:**
+```javascript
+const customEntities = {
+  email: ["secret@company.com", "admin@internal.org"],
+  phone: ["555-999-0000"]
+};
+
+const result = anonymizer.anonymizeWithCustom(text, customEntities);
+```
+
+#### `deanonymize(text: string, mapping: Record<string, string>) => string`
+
+Restores original text using the provided mapping.
+
+## 💡 Use Cases
+
+### Express Middleware
+
+```javascript
+const express = require("express");
+const { Anonymizer } = require("@anonymask/core");
+
+const app = express();
+const anonymizer = new Anonymizer(["email", "phone", "ssn"]);
+
+// Middleware to anonymize request bodies
+app.use(express.json());
+app.use((req, res, next) => {
+  if (req.body && req.body.text) {
+    const result = anonymizer.anonymize(req.body.text);
+    req.body.anonymized_text = result.anonymized_text;
+    req.body.pii_mapping = result.mapping;
+  }
+  next();
+});
+
+app.post("/api/chat", (req, res) => {
+  // Send req.body.anonymized_text to LLM
+  // Store req.body.pii_mapping for deanonymization
+  res.json({ message: "Processed securely" });
+});
+```
+
+### LLM Integration
+
+```javascript
+const { Anonymizer } = require("@anonymask/core");
+
+class SecureLLMClient {
+  constructor() {
+    this.anonymizer = new Anonymizer(["email", "phone", "ssn", "credit_card"]);
+  }
+
+  async processMessage(userMessage, customEntities = null) {
+    // Anonymize user input with optional custom entities
+    const result = customEntities 
+      ? this.anonymizer.anonymizeWithCustom(userMessage, customEntities)
+      : this.anonymizer.anonymize(userMessage);
+
+    // Send anonymized message to LLM
+    const llmResponse = await this.callLLM(result.anonymized_text);
+
+    // Deanonymize LLM response
+    const safeResponse = this.anonymizer.deanonymize(
+      llmResponse,
+      result.mapping,
+    );
+
+    return safeResponse;
+  }
+}
+```
+
+### Custom Entity Anonymization
+
+```javascript
+const { Anonymizer } = require("@anonymask/core");
+
+// Initialize with basic detection
+const anonymizer = new Anonymizer(["email"]);
+
+// Define custom entities to anonymize
+const customEntities = {
+  email: ["internal@company.com", "admin@secure.org"],
+  phone: ["555-999-0000", "555-888-1111"],
+  // You can even specify entity types not in the initial list
+  ssn: ["123-45-6789"]
+};
+
+const text = "Contact internal@company.com or call 555-999-0000";
+const result = anonymizer.anonymizeWithCustom(text, customEntities);
 
-  ✔ sync function from native code
-  ✔ sleep function from native code (201ms)
-  ─
+console.log(result.anonymizedText);
+// "Contact EMAIL_xxx or call PHONE_xxx"
 
-  2 tests passed
-✨  Done in 1.12s.
+console.log(result.mapping);
+// { EMAIL_xxx: 'internal@company.com', PHONE_xxx: '555-999-0000' }
 ```
 
-## Release package
+### Batch Processing
+
+```javascript
+const { Anonymizer } = require("@anonymask/core");
+const fs = require("fs").promises;
+
+async function processDataset(filePath) {
+  const anonymizer = new Anonymizer(["email", "phone", "ssn"]);
+  const data = await fs.readFile(filePath, "utf8");
+  const records = JSON.parse(data);
+
+  const processedRecords = records.map((record) => {
+    const result = anonymizer.anonymize(record.text);
+    return {
+      ...record,
+      original_text: record.text,
+      anonymized_text: result.anonymized_text,
+      pii_mapping: result.mapping,
+      entities_detected: result.entities.length,
+    };
+  });
+
+  await fs.writeFile(
+    "processed_data.json",
+    JSON.stringify(processedRecords, null, 2),
+  );
+  return processedRecords;
+}
+```
+
+## 🧪 Testing
 
-Ensure you have set your **NPM_TOKEN** in the `GitHub` project setting.
+```bash
+# Install dependencies
+npm install
 
-In `Settings -> Secrets`, add **NPM_TOKEN** into it.
+# Run tests
+npm test
 
-When you want to release the package:
+# Run tests with coverage
+npm run test:coverage
+
+# Build the package
+npm run build
+
+# Run benchmarks
+npm run bench
+```
+
+## 🔧 Development
+
+### Building from Source
 
 ```bash
-npm version [<newversion> | major | minor | patch | premajor | preminor | prepatch | prerelease [--preid=<prerelease-id>] | from-git]
+# Clone the repository
+git clone https://github.com/gokul-viswanathan/anonymask.git
+cd anonymask/anonymask-node
+
+# Install dependencies
+npm install
+
+# Build the native addon
+npm run build
+
+# Run tests
+npm test
+```
+
+### Project Structure
 
-git push
 ```
+anonymask-node/
+├── src/
+│   └── lib.rs              # Rust NAPI bindings
+├── index.js                # JavaScript entry point
+├── index.d.ts              # TypeScript definitions
+├── tests/
+│   └── test_anonymask.test.js  # Test suite
+├── package.json
+└── README.md
+```
+
+## 🏗️ Architecture
+
+This package uses NAPI-RS to create high-performance Node.js bindings from the Rust core library:
+
+```
+JavaScript/TypeScript → NAPI-RS → Rust Core → Native Performance
+```
+
+The Rust core provides:
+
+- **Memory Safety**: No buffer overflows or memory leaks
+- **Performance**: Near-native execution speed
+- **Concurrency**: Thread-safe operations
+- **Reliability**: Robust error handling
+
+## 📊 Performance
+
+- **Processing Speed**: < 5ms for typical messages (< 500 words)
+- **Memory Usage**: Minimal footprint with zero-copy operations
+- **Startup Time**: Fast initialization with lazy loading
+- **Concurrency**: Safe for use in multi-threaded environments
+
+## 🔒 Security
+
+- **Cryptographically Secure**: UUID v4 for unique placeholder generation
+- **Deterministic**: Same input always produces same output
+- **No Data Leakage**: Secure handling of PII throughout the process
+- **Input Validation**: Comprehensive validation and error handling
+
+## 📄 License
+
+MIT License - see [LICENSE](../LICENSE) file for details.
+
+## 🤝 Contributing
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Add tests for new functionality
+4. Ensure all tests pass (`npm test`)
+5. Follow the existing code style
+6. Submit a pull request
+
+## 🗺️ Roadmap
+
+- [ ] Streaming API for large texts
+- [ ] Custom entity pattern support
+- [ ] Persistent mapping storage
+- [ ] Performance optimizations
+- [ ] Additional entity types
+
+## 📞 Support
+
+- 📖 [Documentation](https://github.com/gokul-viswanathan/anonymask#readme)
+- 🐛 [Issue Tracker](https://github.com/gokul-viswanathan/anonymask/issues)
+- 💬 [Discussions](https://github.com/gokul-viswanathan/anonymask/discussions)
 
-GitHub actions will do the rest job for you.
+---
 
-> WARN: Don't run `npm publish` manually.
+**Version**: 0.4.5 | **Built with ❤️ using Rust and NAPI-RS**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anonymask/core",
-  "version": "0.4.3",
+  "version": "1.0.0",
   "description": "Secure anonymization/de-anonymization library for PII data",
   "main": "index.js",
   "types": "index.d.ts",
@@ -68,10 +68,10 @@
     "typescript": "^5.9.2"
   },
   "optionalDependencies": {
-    "@anonymask/core-win32-x64-msvc": "0.4.3",
-    "@anonymask/core-darwin-x64": "0.4.3",
-    "@anonymask/core-linux-x64-gnu": "0.4.3",
-    "@anonymask/core-linux-arm64-gnu": "0.4.3",
-    "@anonymask/core-darwin-arm64": "0.4.3"
+    "@anonymask/core-win32-x64-msvc": "1.0.0",
+    "@anonymask/core-darwin-x64": "1.0.0",
+    "@anonymask/core-linux-x64-gnu": "1.0.0",
+    "@anonymask/core-linux-arm64-gnu": "1.0.0",
+    "@anonymask/core-darwin-arm64": "1.0.0"
   }
 }