prisma-extension-saltids 1.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pond918
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,102 @@
+# prisma-extension-saltids
+
+**SaltIDs** is a Prisma 5+ extension that transparently transforms `Auto-Increment Int ID` + `Random Salt` into a single `Int` Public ID at the application layer. It provides an ID obfuscation solution with **zero schema overhead** through intelligent query interception.
+
+* **App Layer**: Sees `123312` (Number).
+* **DB Layer**: Stores `id: 312` and `idSalt: 123`.
+
+This prevents **ID enumeration attacks** (scraping) while maintaining **primary key index performance**.
+
+## Core Advantages
+
+* 🛡️ **Enumeration Protection**: Even though IDs are auto-incrementing, the external world sees randomly jumping numbers.
+* ⚡ **Zero Performance Cost**: Leverages the original primary key index for queries, requiring no additional indexes.
+* 🪄 **Fully Transparent**:
+  * Reading `user.id` automatically returns SaltID.
+  * Writing `userId: SaltID` automatically unpacks and stores.
+  * Querying `findUnique({ where: { id: SaltID } })` is automatically handled.
+* 🙈 **Clean Output**: The `idSalt` field is hidden from `JSON.stringify` and loops.
+
+## Installation
+
+```bash
+npm install prisma-extension-saltids
+```
+
+## Schema Preparation
+
+Simply use the `Int` type and ensure there's a `idSalt` field. **No** additional `@@unique` indexes are required.
+
+```prisma
+model User {
+  // 1. Physical Primary Key (Int)
+  id Int @id @default(autoincrement())
+  // 2. Random Salt (Int)
+  idSalt Int?
+
+  posts Post[]
+}
+
+model Post {
+  postPk Int @id @default(autoincrement())
+  postPkSalt Int?
+
+  title String
+
+  // 3. Relation Field Naming Convention (xxx + xxxSalt)
+  authorId Int
+  authorIdSalt Int?
+  author User @relation(fields: [authorId], references: [id])
+
+  @@index([authorId])
+}
+```
+
+## Register Extension
+
+```typescript
+import { PrismaClient } from '@prisma/client';
+import { saltIdsExtension } from 'prisma-extension-saltids';
+
+const prisma = new PrismaClient().$extends(
+  saltIdsExtension({
+    saltLength: 3, // Default: 3 digits
+    saltSuffix: 'Salt', // Default suffix for salt fields
+  })
+);
+```
+
+## Usage Example
+
+```typescript
+async function main() {
+  // 1. Create (Transparent unpacking)
+  const user = await prisma.user.create({
+    data: { name: 'Geek' }
+  });
+
+  // 2. Read (Transparent composition)
+  console.log(user.id); // 123312 (Number)
+  console.log(JSON.stringify(user)); // {"id":123312, "name":"Geek"}
+
+  // 3. Query (Automatically downgraded to findFirst)
+  // Although you're calling findUnique, because the query condition becomes { id, idSalt }
+  // the plugin automatically converts it to an efficient findFirst query, leveraging the id index.
+  const found = await prisma.user.findUnique({
+    where: { id: user.id }
+  });
+
+  // 4. Relations (Transparent)
+  // Automatically unpacks authorId (SaltID) -> authorId + authorIdSalt
+  await prisma.post.create({
+    data: {
+      title: 'Hello SaltIDs',
+      authorId: user.id
+    }
+  });
+}
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+import { SaltIdsOptions } from "./types";
+export { SaltIdsOptions };
+export declare const saltIdsExtension: (options?: SaltIdsOptions) => (client: any) => {
+    $extends: {
+        extArgs: {
+            result: {};
+            model: {};
+            query: {};
+            client: {};
+        };
+    };
+};

package/dist/index.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.saltIdsExtension = void 0;
+const client_1 = require("@prisma/client");
+const logic_1 = require("./logic");
+const utils_1 = require("./utils");
+const saltIdsExtension = (options) => {
+    const config = {
+        saltLength: options?.saltLength ?? 4,
+        saltSuffix: options?.saltSuffix ?? "Salt",
+    };
+    const registry = new utils_1.ModelRegistry();
+    return client_1.Prisma.defineExtension((client) => {
+        return client.$extends({
+            name: "prisma-extension-saltids",
+            query: {
+                $allModels: {
+                    async $allOperations({ model, operation, args, query }) {
+                        // Ensure registry is initialized
+                        // @ts-ignore
+                        if (client_1.Prisma.dmmf) {
+                            // @ts-ignore
+                            registry.init(client_1.Prisma.dmmf, config.saltSuffix);
+                        }
+                        // ------------------------------------------------
+                        // 1. 输入参数转换 (Input Transformation)
+                        // ------------------------------------------------
+                        let didTransformId = false;
+                        // args 包含 where, data, select, include 等
+                        // 我们直接对 args 进行变换，递归中会根据 Key 匹配字段
+                        if (args) {
+                            const res = (0, logic_1.deepTransformInput)(args, model, registry, config);
+                            didTransformId = res.didTransformId;
+                        }
+                        // ------------------------------------------------
+                        // 2. 自动生成 Salt (Auto Generate Salt)
+                        // ------------------------------------------------
+                        if (operation === "create" || operation === "createMany") {
+                            if (args.data)
+                                (0, logic_1.deepInjectSalt)(args.data, model, registry, config, false);
+                        }
+                        else if (operation === "update" || operation === "updateMany") {
+                            if (args.data)
+                                (0, logic_1.deepInjectSalt)(args.data, model, registry, config, true);
+                        }
+                        else if (operation === "upsert") {
+                            if (args.create)
+                                (0, logic_1.deepInjectSalt)(args.create, model, registry, config, false);
+                            if (args.update)
+                                (0, logic_1.deepInjectSalt)(args.update, model, registry, config, true);
+                        }
+                        // ------------------------------------------------
+                        // 3. 执行查询 (含自动降级逻辑)
+                        // ------------------------------------------------
+                        let result;
+                        // 场景：用户调用 findUnique，但我们注入了 salt。
+                        // 此时 args.where 包含 { id, salt }，这在没有联合唯一索引时会导致 Prisma 报错。
+                        // 解决：拦截此操作，手动改为调用 findFirst。
+                        if (operation === "findUnique" && didTransformId) {
+                            result = await client[model].findFirst(args);
+                        }
+                        else {
+                            result = await query(args);
+                        }
+                        // ------------------------------------------------
+                        // 4. 结果劫持 (隐藏 Salt，暴露 SaltID)
+                        // ------------------------------------------------
+                        if (result) {
+                            (0, logic_1.deepHijackResult)(result, config);
+                        }
+                        return result;
+                    },
+                },
+            },
+        });
+    });
+};
+exports.saltIdsExtension = saltIdsExtension;

package/dist/logic.d.ts

@@ -0,0 +1,7 @@
+import { ModelRegistry } from "./utils";
+import { SaltIdsOptions } from "./types";
+export declare function deepTransformInput(obj: any, modelName: string, registry: ModelRegistry, options: Required<SaltIdsOptions>): {
+    didTransformId: boolean;
+};
+export declare function deepInjectSalt(data: any, modelName: string, registry: ModelRegistry, options: Required<SaltIdsOptions>, skipRootInjection?: boolean): void;
+export declare function deepHijackResult(data: any, options: Required<SaltIdsOptions>): void;

package/dist/logic.js

@@ -0,0 +1,164 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deepTransformInput = deepTransformInput;
+exports.deepInjectSalt = deepInjectSalt;
+exports.deepHijackResult = deepHijackResult;
+const utils_1 = require("./utils");
+// -----------------------------------------------------------------------------
+// 1. 输入参数转换 (Input Transformation)
+// -----------------------------------------------------------------------------
+// 逻辑：将 SaltID (Number) 拆解为 Real ID (Number) + Salt (Number)
+// 动态匹配：根据 ModelRegistry 查找当前模型中成对出现的字段 (xxx, xxxSalt)
+function deepTransformInput(obj, modelName, registry, options) {
+    let didTransformId = false;
+    if (!obj || typeof obj !== "object")
+        return { didTransformId };
+    if (!modelName)
+        return { didTransformId }; // Safety check
+    if (Array.isArray(obj)) {
+        for (const item of obj) {
+            const res = deepTransformInput(item, modelName, registry, options);
+            if (res.didTransformId)
+                didTransformId = true;
+        }
+        return { didTransformId };
+    }
+    // 获取当前模型的 Salt 字段定义
+    const saltFields = registry.getSaltFields(modelName);
+    for (const key of Object.keys(obj)) {
+        const val = obj[key];
+        // Case A: 假如 key 是某个需要混淆的字段 (base field)
+        const saltFieldDef = saltFields.find((f) => f.base === key);
+        if (saltFieldDef && typeof val === "number") {
+            // 检查是否看起来像 SaltID
+            if (utils_1.SaltIdsHelper.isPotentialSaltId(val, options.saltLength)) {
+                const { id, salt } = utils_1.SaltIdsHelper.decode(val, options.saltLength);
+                obj[key] = id; // 替换为真实 ID
+                // 自动注入 Salt (如果缺失)
+                if (obj[saltFieldDef.salt] === undefined) {
+                    obj[saltFieldDef.salt] = salt;
+                }
+                // 标记：如果转换了字段，可能影响 findUnique
+                // 简单启发式：只要转换了任何字段，都标记一下
+                didTransformId = true;
+            }
+        }
+        // Case B: 递归处理对象 (可能是关系嵌套，也可能是操作符)
+        else if (typeof val === "object" && val !== null) {
+            // Check if `key` is a known relation
+            const relation = registry.getRelation(modelName, key);
+            if (relation) {
+                // 如果是关系字段，切换上下文到目标模型
+                const res = deepTransformInput(val, relation.type, registry, options);
+                if (res.didTransformId)
+                    didTransformId = true;
+            }
+            else {
+                // 如果不是关系字段 (如 AND, OR, create, where 等操作符)，保持当前模型上下文
+                const res = deepTransformInput(val, modelName, registry, options);
+                if (res.didTransformId)
+                    didTransformId = true;
+            }
+        }
+    }
+    return { didTransformId };
+}
+// -----------------------------------------------------------------------------
+// 1.5. 自动注入 Salt (Auto Inject Salt)
+// -----------------------------------------------------------------------------
+// 逻辑：在 create 场景下，为所有缺失 Salt 的字段自动生成随机 Salt
+function deepInjectSalt(data, modelName, registry, options, skipRootInjection = false) {
+    if (!data || typeof data !== "object")
+        return;
+    if (!modelName)
+        return;
+    if (Array.isArray(data)) {
+        data.forEach((item) => deepInjectSalt(item, modelName, registry, options, skipRootInjection));
+        return;
+    }
+    // 1. 注入当前层级的 Salt
+    if (!skipRootInjection) {
+        const saltFields = registry.getSaltFields(modelName);
+        for (const { base, salt } of saltFields) {
+            // 策略：如果 Salt 字段缺失，则生成
+            // 不管 base 是否存在 (Base 可能是 autoincrement，所以不存在 data 中)
+            if (data[salt] === undefined) {
+                data[salt] = utils_1.SaltIdsHelper.generateSalt(options.saltLength);
+            }
+        }
+    }
+    // 2. 递归查找嵌套写入
+    for (const key of Object.keys(data)) {
+        const val = data[key];
+        if (typeof val === "object" && val !== null) {
+            // Check for relation
+            const relation = registry.getRelation(modelName, key);
+            const targetModel = relation ? relation.type : undefined;
+            if (targetModel) {
+                // Prisma Nested Writes Keywords
+                const nestedOps = ["create", "update", "upsert", "connectOrCreate"];
+                // Handle simple nested create (e.g. { posts: { create: ... } })
+                if (val.create) {
+                    deepInjectSalt(val.create, targetModel, registry, options, false);
+                }
+                if (val.createMany && val.createMany.data) {
+                    deepInjectSalt(val.createMany.data, targetModel, registry, options, false);
+                }
+                if (val.connectOrCreate && val.connectOrCreate.create) {
+                    deepInjectSalt(val.connectOrCreate.create, targetModel, registry, options, false);
+                }
+                if (val.upsert && val.upsert.create) {
+                    deepInjectSalt(val.upsert.create, targetModel, registry, options, false);
+                }
+                // Note: 'update' usually takes 'data', which might need injection if we allow updating ID?
+                // Usually ID/Salt is immutable, but if needed, add logic here.
+            }
+        }
+    }
+}
+// -----------------------------------------------------------------------------
+// 2. 结果劫持 (Result Hijacking)
+// -----------------------------------------------------------------------------
+// 逻辑：保持原样，利用后缀匹配来隐藏 Salt 并劫持 Getter
+function deepHijackResult(data, options) {
+    if (!data || typeof data !== "object")
+        return;
+    if (Array.isArray(data)) {
+        data.forEach((item) => deepHijackResult(item, options));
+        return;
+    }
+    const keys = Object.keys(data);
+    for (const key of keys) {
+        if (key.endsWith(options.saltSuffix)) {
+            const saltVal = data[key];
+            if (typeof saltVal === "number") {
+                const baseKey = key.slice(0, -options.saltSuffix.length);
+                const baseVal = data[baseKey];
+                if (typeof baseVal === "number") {
+                    // 1. Hide Salt
+                    Object.defineProperty(data, key, {
+                        enumerable: false,
+                        value: saltVal,
+                        writable: true,
+                        configurable: true,
+                    });
+                    // 2. Hijack Base ID
+                    Object.defineProperty(data, baseKey, {
+                        enumerable: true,
+                        configurable: true,
+                        get() {
+                            return utils_1.SaltIdsHelper.encode(baseVal, saltVal, options.saltLength);
+                        },
+                        set(v) {
+                            // no-op
+                        },
+                    });
+                }
+            }
+        }
+        const val = data[key];
+        if (typeof val === "object" && val !== null && !(val instanceof Date)) {
+            deepHijackResult(val, options);
+        }
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,11 @@
+export interface SaltIdsOptions {
+    /**
+     * Salt 长度 (默认为 4)
+     */
+    saltLength?: number;
+    /**
+     * Salt 字段后缀 (默认为 'Salt')
+     * 例如: userId -> userSalt
+     */
+    saltSuffix?: string;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/utils.d.ts

@@ -0,0 +1,27 @@
+export declare class SaltIdsHelper {
+    static encode(realId: number, salt: number, saltLen?: number): number;
+    static decode(pid: number, saltLen?: number): {
+        id: number;
+        salt: number;
+    };
+    static isPotentialSaltId(val: number, saltLen?: number): boolean;
+    static generateSalt(saltLen?: number): number;
+}
+export interface SaltField {
+    base: string;
+    salt: string;
+}
+export interface RelationField {
+    name: string;
+    type: string;
+    isList: boolean;
+}
+export declare class ModelRegistry {
+    private saltFields;
+    private relations;
+    private initialized;
+    init(dmmf: any, suffix: string): void;
+    private parse;
+    getSaltFields(model: string): SaltField[];
+    getRelation(model: string, field: string): RelationField | undefined;
+}

package/dist/utils.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ModelRegistry = exports.SaltIdsHelper = void 0;
+/**
+ * SaltID Helper (Pure Number)
+ */
+const DEFAULT_SALT_LEN = 6;
+class SaltIdsHelper {
+    static encode(realId, salt, saltLen = DEFAULT_SALT_LEN) {
+        return Number(`${salt}${realId}`);
+    }
+    static decode(pid, saltLen = DEFAULT_SALT_LEN) {
+        const str = pid.toString();
+        // 容错：长度不足则不做处理
+        if (str.length <= saltLen) {
+            return { id: pid, salt: 0 };
+        }
+        const saltStr = str.slice(0, saltLen);
+        const idStr = str.slice(saltLen);
+        return {
+            salt: parseInt(saltStr, 10),
+            id: parseInt(idStr, 10),
+        };
+    }
+    static isPotentialSaltId(val, saltLen = DEFAULT_SALT_LEN) {
+        return val.toString().length > saltLen;
+    }
+    static generateSalt(saltLen = DEFAULT_SALT_LEN) {
+        const min = Math.pow(10, saltLen - 1); // e.g. 100
+        const max = Math.pow(10, saltLen) - 1; // e.g. 999
+        return Math.floor(min + Math.random() * (max - min + 1));
+    }
+}
+exports.SaltIdsHelper = SaltIdsHelper;
+class ModelRegistry {
+    constructor() {
+        this.saltFields = new Map();
+        this.relations = new Map();
+        this.initialized = false;
+    }
+    init(dmmf, suffix) {
+        if (this.initialized)
+            return;
+        this.parse(dmmf, suffix);
+        this.initialized = true;
+    }
+    parse(dmmf, suffix) {
+        const models = dmmf.datamodel.models;
+        for (const model of models) {
+            const fields = model.fields;
+            const validSalts = [];
+            const relationMap = new Map();
+            // 1. Map all Int fields
+            const intFields = new Set();
+            fields.forEach((f) => {
+                if (f.kind === "scalar" && f.type === "Int") {
+                    intFields.add(f.name);
+                }
+                if (f.kind === "object") {
+                    relationMap.set(f.name, {
+                        name: f.name,
+                        type: f.type,
+                        isList: f.isList,
+                    });
+                }
+            });
+            // 2. Find Pairs
+            intFields.forEach((fieldName) => {
+                // assumption: base field "xxx", salt field "xxxSalt" (if suffix is "Salt")
+                // Check if this field could be a base?
+                // If "postPk" exists, check if "postPkSalt" exists.
+                const potentialSaltName = `${fieldName}${suffix}`;
+                if (intFields.has(potentialSaltName)) {
+                    validSalts.push({ base: fieldName, salt: potentialSaltName });
+                }
+            });
+            this.saltFields.set(model.name, validSalts);
+            this.relations.set(model.name, relationMap);
+        }
+    }
+    getSaltFields(model) {
+        return this.saltFields.get(model) || [];
+    }
+    getRelation(model, field) {
+        return this.relations.get(model)?.get(field);
+    }
+}
+exports.ModelRegistry = ModelRegistry;

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "prisma-extension-saltids",
+  "version": "1.0.2",
+  "description": "Transparently transform Auto-Increment Int ID + Random Salt into a single Public Int ID. Zero schema overhead.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "prepublishOnly": "pnpm run build"
+  },
+  "keywords": [
+    "prisma",
+    "extension",
+    "saltids",
+    "hashids",
+    "sqids",
+    "id",
+    "salt"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pond918/prisma-extension-saltids.git"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "author": "James P",
+  "license": "MIT",
+  "peerDependencies": {
+    "@prisma/client": "^5.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "prisma": "^5.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^4.0.18"
+  }
+}