dokkebi-guard-upload 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,154 @@
+/** 단일 라벨 점수 */
+export interface LabelScore {
+    label: string;
+    score: number;
+}
+/** NSFW 스캔 결과 */
+export interface ScanResult {
+    /** 업로드 허용 여부 */
+    pass: boolean;
+    /** NSFW 관련 최고 점수 (0–1) */
+    nsfwScore: number;
+    /** 모델이 반환한 전체 라벨 점수 */
+    labels: LabelScore[];
+    /** 차단 시 사용자에게 보여줄 이유 */
+    reason?: string;
+    /** 처리에 걸린 시간(ms) */
+    durationMs: number;
+}
+export interface GuardUploadOptions {
+    /** NSFW 점수가 이 값 이상이면 차단 (0–1, 기본 0.75) */
+    nsfwThreshold?: number;
+    /** 차단 대상 라벨 (소문자 비교). 기본: nsfw, porn, explicit, hentai, sexy */
+    blockLabels?: string[];
+    /** Hugging Face 모델 ID (기본 AdamCodd/vit-base-nsfw-detector — Transformers.js ONNX) */
+    modelId?: string;
+    /** ONNX dtype: q4 | fp16 | fp32 (기본 q4, WASM 호환) */
+    modelDtype?: 'q4' | 'q4f16' | 'fp16' | 'fp32' | 'q8';
+    /** 추론 전 이미지 최대 변 (기본 512) */
+    maxImageSide?: number;
+    /** ONNX WASM 디렉터리. 미설정 시 Vite 등 번들러가 worker와 함께 wasm을 제공 (권장) */
+    onnxWasmPaths?: string;
+    /** Web Worker URL. 미지정 시 패키지 worker 또는 blob worker */
+    workerUrl?: string | URL;
+    /** 모델 로드 진행 콜백 */
+    onLoadProgress?: (progress: number, detail?: LoadProgressDetail) => void;
+    /** 스캔 시작/완료 콜백 */
+    onScanStart?: () => void;
+    onScanComplete?: (result: ScanResult) => void;
+    /** 배포용 무결성·proof (서버 검증) */
+    security?: GuardSecurityConfig;
+}
+/** 빌드 manifest (`guard-manifest.json`) */
+export interface GuardManifest {
+    buildId: string;
+    workerSha256: string;
+    libVersion: string;
+    builtAt: string;
+}
+/** 서버 proof·무결성 검증 설정 */
+export interface GuardSecurityConfig {
+    /** 빌드 ID (manifest.buildId) */
+    buildId: string;
+    /** Worker 스크립트 SHA-256 hex (manifest.workerSha256) */
+    workerSha256: string;
+    /** proof 발급 API (POST) */
+    proofEndpoint: string;
+    /** 변조 리포트 API (POST, 선택) */
+    reportEndpoint?: string;
+    /** proof 요청 추가 헤더 */
+    proofHeaders?: Record<string, string>;
+    proofCredentials?: RequestCredentials;
+    /** Worker 해시 검증 (기본 true) */
+    verifyWorker?: boolean;
+}
+export interface GuardSecurityOptions extends GuardUploadOptions {
+    security: GuardSecurityConfig;
+}
+export interface LoadProgressDetail {
+    status?: string;
+    loaded?: number;
+    total?: number;
+    file?: string;
+}
+export interface UploadOptions {
+    /** multipart 업로드 URL */
+    endpoint: string;
+    /** FormData 필드명 (기본 'file') */
+    fieldName?: string;
+    /** 추가 FormData 필드 */
+    extraFields?: Record<string, string | Blob>;
+    /** fetch 헤더 (Authorization 등) */
+    headers?: Record<string, string>;
+    /** proof 토큰 헤더명 (security 사용 시 기본 X-Guard-Token) */
+    guardTokenHeader?: string;
+    /** 응답 JSON에서 URL을 꺼낼 키 (기본 'url') */
+    urlKey?: string;
+    /** fetch credentials */
+    credentials?: RequestCredentials;
+    /** security.proofEndpoint 를 upload 에서도 쓸 경우 false 로 개별 지정 */
+    skipProof?: boolean;
+}
+export interface UploadResult {
+    url: string;
+    scan: ScanResult;
+    raw: unknown;
+    /** security 사용 시 발급된 proof 토큰 */
+    guardToken?: string;
+}
+export interface GuardUploadInstance {
+    /** 모델 로드 (최초 scan/upload 전 1회) */
+    load(): Promise<void>;
+    /** 이미지만 검열 */
+    scan(file: File | Blob): Promise<ScanResult>;
+    /** 검열 통과 시에만 업로드 */
+    upload(file: File | Blob, options: UploadOptions): Promise<UploadResult>;
+    /** Worker 종료 */
+    dispose(): void;
+    /** 모델 로드 완료 여부 */
+    readonly ready: boolean;
+}
+/** Worker ↔ Main 메시지 타입 */
+export type WorkerOutMessage = {
+    type: 'loading';
+    device?: string;
+} | {
+    type: 'progress';
+    progress: number;
+    loaded?: number;
+    total?: number;
+    file?: string;
+} | {
+    type: 'ready';
+    device?: string;
+} | {
+    type: 'result';
+    labels: LabelScore[];
+    nsfwScore: number;
+    pass: boolean;
+    reason?: string;
+} | {
+    type: 'error';
+    message: string;
+};
+export type WorkerInMessage = {
+    type: 'load';
+    data: {
+        modelId: string;
+        modelDtype: string;
+        onnxWasmPaths?: string;
+        nsfwThreshold: number;
+        blockLabels: string[];
+    };
+} | {
+    type: 'scan';
+    data: {
+        pixels: ArrayBuffer;
+        width: number;
+        height: number;
+    };
+};
+export declare const DEFAULT_MODEL_ID = "AdamCodd/vit-base-nsfw-detector";
+export declare const DEFAULT_MODEL_DTYPE: "q4";
+export declare const DEFAULT_BLOCK_LABELS: string[];
+export declare const DEFAULT_NSFW_THRESHOLD = 0.75;

package/dist/utils/image.d.ts

@@ -0,0 +1,9 @@
+/** File/Blob → RGBA 픽셀 (최대 변 리사이즈) */
+export interface ImagePixels {
+    pixels: Uint8ClampedArray;
+    width: number;
+    height: number;
+}
+export declare function fileToPixels(file: File | Blob, maxSide?: number): Promise<ImagePixels>;
+export declare function isImageFile(file: File | Blob): boolean;
+export declare function guessFilename(file: File | Blob, fallback?: string): string;

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "dokkebi-guard-upload",
+  "version": "0.1.0",
+  "description": "Client-side NSFW image screening before upload — browser Web Worker + ONNX",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "types": "./dist/index.d.ts"
+    },
+    "./worker": "./src/worker/nsfw-worker.ts",
+    "./server": "./server/guard-handler.mjs"
+  },
+  "files": [
+    "dist",
+    "src/worker",
+    "server",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "vite build && tsc --emitDeclarationOnly",
+    "copy-onnx": "node scripts/copy-onnx.mjs",
+    "dev": "npm run dev:vanilla",
+    "dev:vanilla": "vite --config examples/vanilla/vite.config.ts",
+    "dev:react": "vite --config examples/react/vite.config.ts",
+    "dev:vue": "vite --config examples/vue/vite.config.ts",
+    "guard:manifest": "vite build --config examples/react/vite.config.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "nsfw",
+    "content-moderation",
+    "image-upload",
+    "onnx",
+    "browser",
+    "dokkebi"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@huggingface/transformers": "^3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@huggingface/transformers": {
+      "optional": false
+    }
+  },
+  "devDependencies": {
+    "@huggingface/transformers": "^3.4.0",
+    "@types/react": "^18.3.0",
+    "@types/react-dom": "^18.3.0",
+    "@vitejs/plugin-react": "^4.3.0",
+    "@vitejs/plugin-vue": "^5.1.0",
+    "react": "^18.3.0",
+    "react-dom": "^18.3.0",
+    "typescript": "^5.5.3",
+    "vite": "^5.4.0",
+    "vite-plugin-dts": "^4.3.0",
+    "vue": "^3.4.0"
+  }
+}

package/server/guard-handler.mjs

@@ -0,0 +1,276 @@
+/**
+ * Guard proof API — Node 18+ / Cloudflare Workers (Web Crypto)
+ * import from 'dokkebi-guard-upload/server' in host app
+ */
+
+const DEFAULT_TTL_SEC = 30;
+
+function b64urlEncode(bytes) {
+  return Buffer.from(bytes).toString('base64url');
+}
+
+function b64urlDecode(s) {
+  return new Uint8Array(Buffer.from(s, 'base64url'));
+}
+
+function canonicalProofMessage(p) {
+  return [p.v, p.bid, p.wh, p.fp, p.ns.toFixed(6), String(p.exp), p.nonce].join('|');
+}
+
+async function hmacSign(secret, message) {
+  const key = await crypto.subtle.importKey(
+    'raw',
+    new TextEncoder().encode(secret),
+    { name: 'HMAC', hash: 'SHA-256' },
+    false,
+    ['sign'],
+  );
+  const sig = await crypto.subtle.sign('HMAC', key, new TextEncoder().encode(message));
+  return b64urlEncode(new Uint8Array(sig));
+}
+
+export async function signProofPayload(secret, payload) {
+  const body = b64urlEncode(new TextEncoder().encode(JSON.stringify(payload)));
+  const sig = await hmacSign(secret, canonicalProofMessage(payload));
+  return `${body}.${sig}`;
+}
+
+export async function verifyProofToken(secret, token, nowMs = Date.now()) {
+  const dot = token.lastIndexOf('.');
+  if (dot <= 0) return { ok: false, reason: 'MALFORMED_TOKEN' };
+
+  let payload;
+  try {
+    payload = JSON.parse(new TextDecoder().decode(b64urlDecode(token.slice(0, dot))));
+  } catch {
+    return { ok: false, reason: 'INVALID_PAYLOAD' };
+  }
+
+  if (payload.v !== 1) return { ok: false, reason: 'UNSUPPORTED_VERSION', payload };
+  if (payload.exp * 1000 < nowMs) return { ok: false, reason: 'EXPIRED', payload };
+
+  const expectedSig = await hmacSign(secret, canonicalProofMessage(payload));
+  const actualSig = token.slice(dot + 1);
+  if (expectedSig !== actualSig) return { ok: false, reason: 'SIGNATURE_MISMATCH', payload };
+
+  return { ok: true, payload };
+}
+
+/** @typedef {{ buildId: string; workerSha256: string; nsfwThreshold?: number }} AllowedBuild */
+
+/**
+ * @param {object} opts
+ * @param {string} opts.secret GUARD_PROOF_SECRET
+ * @param {AllowedBuild[]} opts.allowedBuilds
+ * @param {number} [opts.nsfwThreshold=0.75]
+ * @param {(event: object) => void} [opts.auditLog]
+ */
+export function createGuardHandlers(opts) {
+  const secret = opts.secret || 'dev-guard-secret-change-me';
+  const threshold = opts.nsfwThreshold ?? 0.75;
+  const allowed = new Map(
+    (opts.allowedBuilds || []).map((b) => [b.buildId, b]),
+  );
+  const audit = opts.auditLog || ((e) => console.info('[guard-audit]', JSON.stringify(e)));
+
+  async function handleProofRequest(body, meta = {}) {
+    const {
+      buildId,
+      workerSha256,
+      fileFingerprint,
+      nsfwScore,
+      pass,
+      labels,
+      durationMs,
+    } = body || {};
+
+    const base = {
+      ts: new Date().toISOString(),
+      buildId,
+      workerSha256,
+      fileFingerprint,
+      nsfwScore,
+      ip: meta.ip,
+      userAgent: meta.userAgent,
+    };
+
+    if (!buildId || !workerSha256 || !fileFingerprint) {
+      audit({ ...base, event: 'proof_rejected', code: 'MISSING_FIELDS' });
+      return { status: 400, json: { ok: false, code: 'MISSING_FIELDS', error: '필수 필드 누락' } };
+    }
+
+    const reg = allowed.get(buildId);
+    if (!reg) {
+      audit({ ...base, event: 'proof_rejected', code: 'UNKNOWN_BUILD' });
+      return { status: 403, json: { ok: false, code: 'UNKNOWN_BUILD', error: '등록되지 않은 빌드' } };
+    }
+
+    if (reg.workerSha256 && reg.workerSha256.toLowerCase() !== String(workerSha256).toLowerCase()) {
+      audit({
+        ...base,
+        event: 'integrity_mismatch',
+        expected: reg.workerSha256,
+        actual: workerSha256,
+      });
+      return {
+        status: 403,
+        json: { ok: false, code: 'INTEGRITY_MISMATCH', error: 'Worker 무결성 불일치' },
+      };
+    }
+
+    const limit = reg.nsfwThreshold ?? threshold;
+    if (!pass || Number(nsfwScore) >= limit) {
+      audit({ ...base, event: 'scan_blocked', threshold: limit, labels });
+      return { status: 403, json: { ok: false, code: 'SCAN_BLOCKED', error: '검열 미통과' } };
+    }
+
+    const exp = Math.floor(Date.now() / 1000) + DEFAULT_TTL_SEC;
+    const payload = {
+      v: 1,
+      bid: buildId,
+      wh: workerSha256.toLowerCase(),
+      fp: fileFingerprint,
+      ns: Number(nsfwScore),
+      exp,
+      nonce: crypto.randomUUID(),
+    };
+
+    const token = await signProofPayload(secret, payload);
+    audit({ ...base, event: 'proof_issued', exp, durationMs });
+
+    return { status: 200, json: { ok: true, token, exp } };
+  }
+
+  async function handleReport(body, meta = {}) {
+    audit({
+      ts: new Date().toISOString(),
+      event: body?.event || 'security_report',
+      ...body,
+      ip: meta.ip,
+      userAgent: meta.userAgent,
+    });
+    return { status: 204, json: null };
+  }
+
+  async function verifyUploadToken(token, fileFingerprint, buildId) {
+    const v = await verifyProofToken(secret, token);
+    if (!v.ok) return v;
+    if (v.payload.bid !== buildId) return { ok: false, reason: 'BUILD_MISMATCH' };
+    if (v.payload.fp !== fileFingerprint) return { ok: false, reason: 'FILE_MISMATCH' };
+    return v;
+  }
+
+  async function handleDemoUpload(req, meta = {}) {
+    const token = req.headers['x-guard-token'];
+    if (!token || typeof token !== 'string') {
+      audit({
+        ts: new Date().toISOString(),
+        event: 'upload_rejected',
+        code: 'MISSING_TOKEN',
+        ip: meta.ip,
+        userAgent: meta.userAgent,
+      });
+      return { status: 401, json: { ok: false, error: 'X-Guard-Token 필요' } };
+    }
+
+    const v = await verifyProofToken(secret, token);
+    if (!v.ok) {
+      audit({
+        ts: new Date().toISOString(),
+        event: 'upload_rejected',
+        code: v.reason,
+        ip: meta.ip,
+        userAgent: meta.userAgent,
+      });
+      return { status: 403, json: { ok: false, error: `토큰 검증 실패: ${v.reason}` } };
+    }
+
+    audit({
+      ts: new Date().toISOString(),
+      event: 'upload_accepted',
+      buildId: v.payload.bid,
+      fileFingerprint: v.payload.fp,
+      ip: meta.ip,
+    });
+
+    return {
+      status: 200,
+      json: { ok: true, url: `https://demo.local/upload/${v.payload.nonce}` },
+    };
+  }
+
+  return { handleProofRequest, handleReport, handleDemoUpload, verifyUploadToken, verifyProofToken };
+}
+
+/** Vite dev middleware (Connect) */
+export function guardDevMiddleware(options = {}) {
+  const resolveBuilds = () =>
+    typeof options.allowedBuilds === 'function'
+      ? options.allowedBuilds()
+      : options.allowedBuilds || [];
+
+  return async function guardMiddleware(req, res, next) {
+    const handlers = createGuardHandlers({
+      ...options,
+      allowedBuilds: resolveBuilds(),
+    });
+    const url = req.url?.split('?')[0] || '';
+    if (!url.startsWith('/api/guard/')) return next();
+
+    if (req.method === 'OPTIONS') {
+      res.statusCode = 204;
+      res.end();
+      return;
+    }
+
+    const meta = {
+      ip: req.headers['x-forwarded-for'] || req.socket?.remoteAddress,
+      userAgent: req.headers['user-agent'],
+    };
+
+    let body = {};
+    if (req.method === 'POST' && url.startsWith('/api/guard/')) {
+      body = await readJsonBody(req);
+    }
+
+    let result;
+    if (url === '/api/guard/proof' && req.method === 'POST') {
+      result = await handlers.handleProofRequest(body, meta);
+    } else if (url === '/api/guard/report' && req.method === 'POST') {
+      result = await handlers.handleReport(body, meta);
+    } else if (url === '/api/upload' && req.method === 'POST') {
+      result = await handlers.handleDemoUpload(req, meta);
+    } else {
+      res.statusCode = 404;
+      res.setHeader('Content-Type', 'application/json');
+      res.end(JSON.stringify({ error: 'Not found' }));
+      return;
+    }
+
+    res.statusCode = result.status;
+    res.setHeader('Content-Type', 'application/json');
+    if (result.status === 204) {
+      res.end();
+    } else {
+      res.end(JSON.stringify(result.json));
+    }
+  };
+}
+
+function readJsonBody(req) {
+  return new Promise((resolve, reject) => {
+    let data = '';
+    req.on('data', (c) => {
+      data += c;
+      if (data.length > 65536) reject(new Error('body too large'));
+    });
+    req.on('end', () => {
+      try {
+        resolve(data ? JSON.parse(data) : {});
+      } catch {
+        resolve({});
+      }
+    });
+    req.on('error', reject);
+  });
+}

package/src/worker/nsfw-worker.ts

@@ -0,0 +1,169 @@
+/// <reference lib="webworker" />
+
+import { env, pipeline, RawImage } from '@huggingface/transformers';
+
+import {
+  DEFAULT_BLOCK_LABELS,
+  type LabelScore,
+  type WorkerInMessage,
+  type WorkerOutMessage,
+} from '../types';
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type Classifier = any;
+
+let classifier: Classifier | null = null;
+let nsfwThreshold = 0.75;
+let blockLabels = DEFAULT_BLOCK_LABELS;
+
+function configureEnv(onnxWasmPaths?: string) {
+  env.allowLocalModels = false;
+  env.useBrowserCache = true;
+
+  if (!onnxWasmPaths) return;
+
+  const e = env as Record<string, unknown> & {
+    backends?: { onnx?: { wasm?: Record<string, unknown> } };
+  };
+  if (!e.backends) e.backends = {};
+  if (!e.backends.onnx) e.backends.onnx = {};
+  if (!e.backends.onnx.wasm) e.backends.onnx.wasm = {};
+  e.backends.onnx.wasm.wasmPaths = onnxWasmPaths;
+  e.backends.onnx.wasm.numThreads = 1;
+}
+
+function normalizeLabel(label: string): string {
+  return label.toLowerCase().replace(/^label[_\s]*/i, '').trim();
+}
+
+function isBlockedLabel(label: string): boolean {
+  const norm = normalizeLabel(label);
+  if (norm === 'normal' || norm === 'safe' || norm === 'neutral' || norm === 'sfw') return false;
+  return blockLabels.some((b) => norm.includes(b) || b.includes(norm));
+}
+
+function computeNsfwScore(labels: LabelScore[]): number {
+  let max = 0;
+  for (const { label, score } of labels) {
+    if (isBlockedLabel(label)) max = Math.max(max, score);
+  }
+  return max;
+}
+
+function evaluate(labels: LabelScore[]): { pass: boolean; nsfwScore: number; reason?: string } {
+  const nsfwScore = computeNsfwScore(labels);
+  const pass = nsfwScore < nsfwThreshold;
+  if (pass) return { pass, nsfwScore };
+
+  const top = [...labels]
+    .filter(({ label }) => isBlockedLabel(label))
+    .sort((a, b) => b.score - a.score)[0];
+
+  const pct = Math.round(nsfwScore * 100);
+  const reason = top
+    ? `성인/노출 콘텐츠로 판단되어 업로드할 수 없습니다. (${normalizeLabel(top.label)} ${pct}%)`
+    : `성인/노출 콘텐츠로 판단되어 업로드할 수 없습니다. (${pct}%)`;
+
+  return { pass, nsfwScore, reason };
+}
+
+const FALLBACK_DTYPES = ['q4', 'fp16', 'fp32'] as const;
+
+async function loadClassifier(
+  modelId: string,
+  preferredDtype: string,
+  onProgress: (p: Record<string, unknown>) => void,
+): Promise<{ classifier: Classifier; dtype: string }> {
+  const order = [
+    preferredDtype,
+    ...FALLBACK_DTYPES.filter((d) => d !== preferredDtype),
+  ];
+  let lastErr: unknown;
+  for (const dtype of order) {
+    try {
+      const clf = await pipeline('image-classification', modelId, {
+        device: 'wasm',
+        dtype,
+        progress_callback: onProgress,
+      });
+      return { classifier: clf, dtype };
+    } catch (err) {
+      lastErr = err;
+      const msg = err instanceof Error ? err.message : String(err);
+      // ConvInteger 등 WASM 미지원 양자화 → 다음 dtype 시도
+      if (/ConvInteger|Could not find an implementation|no available backend/i.test(msg)) {
+        continue;
+      }
+      throw err;
+    }
+  }
+  throw lastErr instanceof Error ? lastErr : new Error(String(lastErr));
+}
+
+self.addEventListener('message', async (ev: MessageEvent<WorkerInMessage>) => {
+  const msg = ev.data;
+
+  if (msg.type === 'load') {
+    const { modelId, modelDtype, nsfwThreshold: threshold, blockLabels: labels } = msg.data;
+    nsfwThreshold = threshold;
+    blockLabels = labels;
+
+    try {
+      configureEnv(msg.data.onnxWasmPaths);
+
+      const onProgress = (p: Record<string, unknown>) => {
+        if (p.status === 'progress') {
+          self.postMessage({
+            type: 'progress',
+            progress: (p.progress as number) ?? 0,
+            loaded: p.loaded as number | undefined,
+            total: p.total as number | undefined,
+            file: p.file as string | undefined,
+          } satisfies WorkerOutMessage);
+        }
+      };
+
+      self.postMessage({ type: 'loading', device: 'wasm' } satisfies WorkerOutMessage);
+
+      const loaded = await loadClassifier(modelId, modelDtype, onProgress);
+      classifier = loaded.classifier;
+
+      self.postMessage({ type: 'ready', device: `wasm/${loaded.dtype}` } satisfies WorkerOutMessage);
+    } catch (err: unknown) {
+      const message = err instanceof Error ? err.message : String(err);
+      self.postMessage({ type: 'error', message } satisfies WorkerOutMessage);
+    }
+    return;
+  }
+
+  if (msg.type === 'scan') {
+    if (!classifier) {
+      self.postMessage({
+        type: 'error',
+        message: '모델이 로드되지 않았습니다. load()를 먼저 호출하세요.',
+      } satisfies WorkerOutMessage);
+      return;
+    }
+
+    try {
+      const { pixels, width, height } = msg.data;
+      const input = new RawImage(new Uint8ClampedArray(pixels), width, height, 4);
+      const raw = await classifier(input);
+      const labels: LabelScore[] = (raw as LabelScore[]).map(({ label, score }) => ({
+        label: String(label),
+        score: Number(score),
+      }));
+      const verdict = evaluate(labels);
+      self.postMessage({
+        type: 'result',
+        labels,
+        nsfwScore: verdict.nsfwScore,
+        pass: verdict.pass,
+        reason: verdict.reason,
+      } satisfies WorkerOutMessage);
+    } catch (err: unknown) {
+      const message = err instanceof Error ? err.message : String(err);
+      self.postMessage({ type: 'error', message } satisfies WorkerOutMessage);
+    }
+  }
+});