@piifirewall/sdk

PII Firewall を任意の Node.js アプリに組み込む npm SDK

メール・電話番号・マイナンバー・住所などの個人情報（PII）を自動検出・マスク。Express / Hono / Fastify ミドルウェアとして1行で組み込めます。TypeScript 対応。

インストール

npm install @piifirewall/sdk

クイックスタート

基本的な使い方

const { createFirewall } = require('@piifirewall/sdk');

const fw = createFirewall();

const { masked, detections } = fw.mask('連絡先: [email protected] 電話: 090-1234-5678');
// masked:     "連絡先: [SECURED:type=email,id=abc123] 電話: [SECURED:type=phone,id=def456]"
// detections: [{ type: "email", count: 1 }, { type: "phone", count: 1 }]

// 元の値を復元
const id = masked.match(/id=([a-f0-9]+)/)[1];
const result = fw.restore(id);
// result: { type: "email", value: "[email protected]" }

Express ミドルウェア

const express = require('express');
const { createExpressMiddleware } = require('@piifirewall/sdk');

const app = express();
app.use(express.json());
app.use(createExpressMiddleware({ extraTypes: ['name'] }));

app.post('/chat', (req, res) => {
  // req.body.messages は自動的にマスク済み
  // req.piifw.detections で検出情報を参照できる
  console.log(req.piifw); // { detections: [...], masked: true }
  res.json(req.body);
});

Hono ミドルウェア

import { Hono } from 'hono';
import { createHonoMiddleware } from '@piifirewall/sdk';

const app = new Hono();
app.use(createHonoMiddleware({ extraTypes: ['name'] }));

app.post('/chat', (c) => {
  const body = c.get('piifw_body'); // マスク済みボディ
  const meta = c.get('piifw_meta'); // { detections, masked }
  return c.json(body);
});

Fastify プラグイン

const fastify = require('fastify')();
const { piiFirewallPlugin } = require('@piifirewall/sdk');

fastify.register(piiFirewallPlugin, { extraTypes: ['name'] });

fastify.post('/chat', async (request) => {
  // request.body は自動的にマスク済み
  // request.piifw.detections で検出情報を参照
  return request.body;
});

API リファレンス

createFirewall(config?)

createFirewall({
  extraTypes?: PiiType[],  // 追加検出タイプ（例: ["name"]）
  engine?: "XOR"           // 秘密分散エンジン（v1.4 で XOR のみ・Shamir は除外）
}): FirewallInstance

FirewallInstance メソッド

| メソッド | 説明 | | -------------------------- | ----------------------------------------------- | | mask(text) | PIIをマスクして { masked, detections } を返す | | maskMessages(messages) | OpenAI形式メッセージ配列をマスク | | detect(text) | PIIを検出（マスクしない） | | restore(id) | トークンIDで元の値を復元 | | restoreAll(text) | テキスト内の全トークンを一括復元 | | scanAndRestore(text) | 全トークンをスキャンして復元候補を返す | | storeStatus() | 秘密分散ストアのTTL状態を確認 | | detectInjection(text) | プロンプトインジェクションを検知 | | detectSQLInjection(text) | SQLインジェクションを検知 | | expressMiddleware() | Express ミドルウェアを生成 | | honoMiddleware() | Hono ミドルウェアを生成 | | fastifyPlugin() | Fastify プラグインを返す |

検出できる PII タイプ

| タイプ | 説明 | 自動 | | -------------- | -------------------- | --------------- | | email | メールアドレス | ✅ | | phone | 電話番号（日本形式） | ✅ | | my_number | マイナンバー（12桁） | ✅ | | credit_card | クレジットカード番号 | ✅ | | passport | パスポート番号 | ✅ | | address | 住所（都道府県から） | ✅ | | postal_code | 郵便番号 | ✅ | | bank_account | 銀行口座番号 | ✅ | | company | 法人名 | ✅ | | password | パスワード | ✅ | | api_key | APIキー・トークン | ✅ | | ip_address | IPアドレス | ✅ | | pin | PINコード | ✅ | | name | 氏名 | 🔲 要オプション |

氏名検出を有効化するには extraTypes: ["name"] を指定してください。

TypeScript

import { createFirewall, FirewallInstance, MaskResult } from '@piifirewall/sdk';

const fw: FirewallInstance = createFirewall({ extraTypes: ['name'] });
const result: MaskResult = fw.mask('山田 太郎のメール: [email protected]');

ライセンス

MIT