@proteinjs/db-encryption-driver-gcp-kms 0.2.0

package/.eslintrc.js

@@ -0,0 +1,20 @@
+module.exports = {
+  extends: ['eslint:recommended', 'plugin:@typescript-eslint/recommended', 'plugin:prettier/recommended', 'prettier'],
+  parser: '@typescript-eslint/parser',
+  plugins: ['@typescript-eslint', 'prettier'],
+  root: true,
+  ignorePatterns: ['**/dist/*', '**/node_modules/*', '*.md'],
+
+  rules: {
+    'prettier/prettier': ['warn'],
+    curly: ['warn'],
+    'eol-last': ['warn', 'always'],
+    'keyword-spacing': ['warn', { before: true }],
+    'no-undef': 'off',
+    '@typescript-eslint/no-unused-vars': 'off',
+    '@typescript-eslint/no-var-requires': 'off',
+    '@typescript-eslint/no-explicit-any': 'off',
+    '@typescript-eslint/prefer-as-const': 'off',
+    '@typescript-eslint/ban-types': 'off',
+  },
+};

package/.prettierignore

@@ -0,0 +1,4 @@
+node_modules/
+dist/
+.DS_Store
+*.md

package/.prettierrc

@@ -0,0 +1,8 @@
+{
+  "trailingComma": "es5",
+  "tabWidth": 2,
+  "semi": true,
+  "singleQuote": true,
+  "jsxSingleQuote": true,
+  "printWidth": 120
+}

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
+
+# 0.2.0 (2026-08-28)
+
+
+### Features
+
+* column encryption as a first-class db-layer feature ([d57339d](https://github.com/proteinjs/db/commit/d57339d97bb00109b7db68ec76caad7be592d6e3))

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Brent Bahry
+
+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/dist/generated/index.d.ts

@@ -0,0 +1,5 @@
+/** Load Dependency Source Graphs */
+import '@proteinjs/db';
+import '@proteinjs/logger';
+export * from '../index';
+//# sourceMappingURL=index.d.ts.map

package/dist/generated/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../generated/index.ts"],"names":[],"mappings":"AAAA,oCAAoC;AAEpC,OAAO,eAAe,CAAC;AACvB,OAAO,mBAAmB,CAAC;AAuB3B,cAAc,UAAU,CAAC"}

package/dist/generated/index.js

@@ -0,0 +1,31 @@
+"use strict";
+/** Load Dependency Source Graphs */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+require("@proteinjs/db");
+require("@proteinjs/logger");
+/** Generate Source Graph */
+var sourceGraph = "{\"options\":{\"directed\":true,\"multigraph\":false,\"compound\":false},\"nodes\":[{\"v\":\"@proteinjs/db-encryption-driver-gcp-kms/GcpKmsMasterKeyProvider\",\"value\":{\"packageName\":\"@proteinjs/db-encryption-driver-gcp-kms\",\"name\":\"GcpKmsMasterKeyProvider\",\"filePath\":\"src/GcpKmsMasterKeyProvider.ts\",\"qualifiedName\":\"@proteinjs/db-encryption-driver-gcp-kms/GcpKmsMasterKeyProvider\",\"isAbstract\":false,\"isStatic\":false,\"visibility\":\"public\",\"properties\":[{\"name\":\"config\",\"type\":{\"packageName\":\"@proteinjs/db-encryption-driver-gcp-kms\",\"name\":\"GcpKmsMasterKeyConfig\",\"filePath\":null,\"qualifiedName\":\"@proteinjs/db-encryption-driver-gcp-kms/GcpKmsMasterKeyConfig\",\"typeParameters\":null,\"directParents\":null},\"isOptional\":false,\"isAbstract\":false,\"isStatic\":false,\"visibility\":\"private\"},{\"name\":\"client\",\"type\":{\"packageName\":\"@google-cloud/kms\",\"name\":\"KeyManagementServiceClient\",\"filePath\":null,\"qualifiedName\":\"@google-cloud/kms/KeyManagementServiceClient\",\"typeParameters\":null,\"directParents\":null},\"isOptional\":false,\"isAbstract\":false,\"isStatic\":false,\"visibility\":\"private\"}],\"methods\":[{\"name\":\"wrapDataKey\",\"returnType\":{\"packageName\":\"\",\"name\":\"Promise<string>\",\"filePath\":null,\"qualifiedName\":\"/Promise<string>\",\"typeParameters\":null,\"directParents\":null},\"isAsync\":true,\"isOptional\":false,\"isAbstract\":false,\"isStatic\":false,\"visibility\":\"public\",\"parameters\":[{\"name\":\"plaintextKeyMaterial\",\"type\":{\"packageName\":\"\",\"name\":\"Buffer\",\"filePath\":null,\"qualifiedName\":\"/Buffer\",\"typeParameters\":null,\"directParents\":null}}]},{\"name\":\"unwrapDataKey\",\"returnType\":{\"packageName\":\"\",\"name\":\"Promise<Buffer>\",\"filePath\":null,\"qualifiedName\":\"/Promise<Buffer>\",\"typeParameters\":null,\"directParents\":null},\"isAsync\":true,\"isOptional\":false,\"isAbstract\":false,\"isStatic\":false,\"visibility\":\"public\",\"parameters\":[{\"name\":\"wrappedKeyMaterial\",\"type\":{\"packageName\":\"\",\"name\":\"string\",\"filePath\":null,\"qualifiedName\":\"/string\",\"typeParameters\":null,\"directParents\":null}}]},{\"name\":\"getMasterKeyId\",\"returnType\":{\"packageName\":\"\",\"name\":\"string\",\"filePath\":null,\"qualifiedName\":\"/string\",\"typeParameters\":null,\"directParents\":null},\"isAsync\":false,\"isOptional\":false,\"isAbstract\":false,\"isStatic\":false,\"visibility\":\"public\",\"parameters\":[]}],\"typeParameters\":[],\"directParentInterfaces\":[{\"packageName\":\"@proteinjs/db\",\"name\":\"MasterKeyProvider\",\"filePath\":null,\"qualifiedName\":\"@proteinjs/db/MasterKeyProvider\",\"properties\":[],\"methods\":[],\"typeParameters\":[],\"directParents\":[]}],\"directParentClasses\":[],\"sourceType\":2}},{\"v\":\"@proteinjs/db/MasterKeyProvider\"}],\"edges\":[{\"v\":\"@proteinjs/db-encryption-driver-gcp-kms/GcpKmsMasterKeyProvider\",\"w\":\"@proteinjs/db/MasterKeyProvider\",\"value\":\"implements interface\"}]}";
+/** Generate Source Links */
+var GcpKmsMasterKeyProvider_1 = require("../src/GcpKmsMasterKeyProvider");
+var sourceLinks = {
+    '@proteinjs/db-encryption-driver-gcp-kms/GcpKmsMasterKeyProvider': GcpKmsMasterKeyProvider_1.GcpKmsMasterKeyProvider,
+};
+/** Load Source Graph and Links */
+var reflection_1 = require("@proteinjs/reflection");
+reflection_1.SourceRepository.merge(sourceGraph, sourceLinks);
+__exportStar(require("../index"), exports);
+//# sourceMappingURL=index.js.map

package/dist/generated/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../generated/index.ts"],"names":[],"mappings":";AAAA,oCAAoC;;;;;;;;;;;;;;;;AAEpC,yBAAuB;AACvB,6BAA2B;AAG3B,4BAA4B;AAE5B,IAAM,WAAW,GAAG,o9FAAo9F,CAAC;AAGz+F,4BAA4B;AAE5B,0EAAyE;AAEzE,IAAM,WAAW,GAAG;IACnB,iEAAiE,EAAE,iDAAuB;CAC1F,CAAC;AAGF,kCAAkC;AAElC,oDAAyD;AACzD,6BAAgB,CAAC,KAAK,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC;AAGjD,2CAAyB"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './src/GcpKmsMasterKeyProvider';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,cAAc,+BAA+B,CAAC"}

package/dist/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./src/GcpKmsMasterKeyProvider"), exports);
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,gEAA8C"}

package/dist/src/GcpKmsMasterKeyProvider.d.ts

@@ -0,0 +1,37 @@
+/// <reference types="node" />
+/// <reference types="node" />
+import { KeyManagementServiceClient } from '@google-cloud/kms';
+import { MasterKeyProvider } from '@proteinjs/db';
+export interface GcpKmsMasterKeyConfig {
+    /**
+     * The Cloud KMS crypto key's full resource name:
+     * `projects/<project>/locations/<location>/keyRings/<ring>/cryptoKeys/<key>`
+     */
+    keyName: string;
+}
+/**
+ * The production `MasterKeyProvider` for @proteinjs/db column encryption: the master key
+ * lives in Cloud KMS and never leaves the vault — KMS performs the wrap (encrypt) and
+ * unwrap (decrypt) of per-owner data keys for callers holding permission on the key.
+ *
+ * Operational shape (see the framework's `DataKeyStore`): the vault is called once per data
+ * key and cached in-process, never per row — a warm request makes zero KMS calls. Grant
+ * `roles/cloudkms.cryptoKeyEncrypterDecrypter` on the key to the identity the production
+ * server runs as (its service account) and to nothing else; granting anyone else is a
+ * configuration change Google records in admin logs that cannot be turned off.
+ *
+ * Key rotation note: KMS crypto keys can rotate their PRIMARY version automatically;
+ * `decrypt` transparently uses the version that encrypted each wrapped key, so stored
+ * wrapped data keys keep unwrapping across KMS rotations with no application involvement
+ * (per-owner DATA-key rotation is the framework's own `rotate-keys` walk, a separate
+ * concern).
+ */
+export declare class GcpKmsMasterKeyProvider implements MasterKeyProvider {
+    private config;
+    private client;
+    constructor(config: GcpKmsMasterKeyConfig, client?: KeyManagementServiceClient);
+    wrapDataKey(plaintextKeyMaterial: Buffer): Promise<string>;
+    unwrapDataKey(wrappedKeyMaterial: string): Promise<Buffer>;
+    getMasterKeyId(): string;
+}
+//# sourceMappingURL=GcpKmsMasterKeyProvider.d.ts.map

package/dist/src/GcpKmsMasterKeyProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GcpKmsMasterKeyProvider.d.ts","sourceRoot":"","sources":["../../src/GcpKmsMasterKeyProvider.ts"],"names":[],"mappings":";;AAAA,OAAO,EAAE,0BAA0B,EAAE,MAAM,mBAAmB,CAAC;AAC/D,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAElD,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,uBAAwB,YAAW,iBAAiB;IAC/D,OAAO,CAAC,MAAM,CAAwB;IACtC,OAAO,CAAC,MAAM,CAA6B;gBAE/B,MAAM,EAAE,qBAAqB,EAAE,MAAM,CAAC,EAAE,0BAA0B;IAKxE,WAAW,CAAC,oBAAoB,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAY1D,aAAa,CAAC,kBAAkB,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAYhE,cAAc,IAAI,MAAM;CAGzB"}

package/dist/src/GcpKmsMasterKeyProvider.js

@@ -0,0 +1,107 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g;
+    return g = { next: verb(0), "throw": verb(1), "return": verb(2) }, typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GcpKmsMasterKeyProvider = void 0;
+var kms_1 = require("@google-cloud/kms");
+/**
+ * The production `MasterKeyProvider` for @proteinjs/db column encryption: the master key
+ * lives in Cloud KMS and never leaves the vault — KMS performs the wrap (encrypt) and
+ * unwrap (decrypt) of per-owner data keys for callers holding permission on the key.
+ *
+ * Operational shape (see the framework's `DataKeyStore`): the vault is called once per data
+ * key and cached in-process, never per row — a warm request makes zero KMS calls. Grant
+ * `roles/cloudkms.cryptoKeyEncrypterDecrypter` on the key to the identity the production
+ * server runs as (its service account) and to nothing else; granting anyone else is a
+ * configuration change Google records in admin logs that cannot be turned off.
+ *
+ * Key rotation note: KMS crypto keys can rotate their PRIMARY version automatically;
+ * `decrypt` transparently uses the version that encrypted each wrapped key, so stored
+ * wrapped data keys keep unwrapping across KMS rotations with no application involvement
+ * (per-owner DATA-key rotation is the framework's own `rotate-keys` walk, a separate
+ * concern).
+ */
+var GcpKmsMasterKeyProvider = /** @class */ (function () {
+    function GcpKmsMasterKeyProvider(config, client) {
+        this.config = config;
+        this.client = client !== null && client !== void 0 ? client : new kms_1.KeyManagementServiceClient();
+    }
+    GcpKmsMasterKeyProvider.prototype.wrapDataKey = function (plaintextKeyMaterial) {
+        return __awaiter(this, void 0, void 0, function () {
+            var result;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0: return [4 /*yield*/, this.client.encrypt({
+                            name: this.config.keyName,
+                            plaintext: plaintextKeyMaterial,
+                        })];
+                    case 1:
+                        result = (_a.sent())[0];
+                        if (!result.ciphertext) {
+                            throw new Error("Cloud KMS encrypt returned no ciphertext for key ".concat(this.config.keyName));
+                        }
+                        return [2 /*return*/, Buffer.from(result.ciphertext).toString('base64')];
+                }
+            });
+        });
+    };
+    GcpKmsMasterKeyProvider.prototype.unwrapDataKey = function (wrappedKeyMaterial) {
+        return __awaiter(this, void 0, void 0, function () {
+            var result;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0: return [4 /*yield*/, this.client.decrypt({
+                            name: this.config.keyName,
+                            ciphertext: Buffer.from(wrappedKeyMaterial, 'base64'),
+                        })];
+                    case 1:
+                        result = (_a.sent())[0];
+                        if (!result.plaintext) {
+                            throw new Error("Cloud KMS decrypt returned no plaintext for key ".concat(this.config.keyName));
+                        }
+                        return [2 /*return*/, Buffer.from(result.plaintext)];
+                }
+            });
+        });
+    };
+    GcpKmsMasterKeyProvider.prototype.getMasterKeyId = function () {
+        return this.config.keyName;
+    };
+    return GcpKmsMasterKeyProvider;
+}());
+exports.GcpKmsMasterKeyProvider = GcpKmsMasterKeyProvider;
+//# sourceMappingURL=GcpKmsMasterKeyProvider.js.map

package/dist/src/GcpKmsMasterKeyProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GcpKmsMasterKeyProvider.js","sourceRoot":"","sources":["../../src/GcpKmsMasterKeyProvider.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,yCAA+D;AAW/D;;;;;;;;;;;;;;;;GAgBG;AACH;IAIE,iCAAY,MAA6B,EAAE,MAAmC;QAC5E,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,MAAM,GAAG,MAAM,aAAN,MAAM,cAAN,MAAM,GAAI,IAAI,gCAA0B,EAAE,CAAC;IAC3D,CAAC;IAEK,6CAAW,GAAjB,UAAkB,oBAA4B;;;;;4BAC3B,qBAAM,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC;4BACzC,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,OAAO;4BACzB,SAAS,EAAE,oBAAoB;yBAChC,CAAC,EAAA;;wBAHK,MAAM,GAAI,CAAA,SAGf,CAAA,GAHW;wBAIb,IAAI,CAAC,MAAM,CAAC,UAAU,EAAE;4BACtB,MAAM,IAAI,KAAK,CAAC,2DAAoD,IAAI,CAAC,MAAM,CAAC,OAAO,CAAE,CAAC,CAAC;yBAC5F;wBAED,sBAAO,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,UAAwB,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAC;;;;KACxE;IAEK,+CAAa,GAAnB,UAAoB,kBAA0B;;;;;4BAC3B,qBAAM,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC;4BACzC,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,OAAO;4BACzB,UAAU,EAAE,MAAM,CAAC,IAAI,CAAC,kBAAkB,EAAE,QAAQ,CAAC;yBACtD,CAAC,EAAA;;wBAHK,MAAM,GAAI,CAAA,SAGf,CAAA,GAHW;wBAIb,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE;4BACrB,MAAM,IAAI,KAAK,CAAC,0DAAmD,IAAI,CAAC,MAAM,CAAC,OAAO,CAAE,CAAC,CAAC;yBAC3F;wBAED,sBAAO,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,SAAuB,CAAC,EAAC;;;;KACpD;IAED,gDAAc,GAAd;QACE,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC;IAC7B,CAAC;IACH,8BAAC;AAAD,CAAC,AApCD,IAoCC;AApCY,0DAAuB"}

package/dist/test/GcpKmsMasterKeyProvider.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=GcpKmsMasterKeyProvider.test.d.ts.map

package/dist/test/GcpKmsMasterKeyProvider.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GcpKmsMasterKeyProvider.test.d.ts","sourceRoot":"","sources":["../../test/GcpKmsMasterKeyProvider.test.ts"],"names":[],"mappings":""}

package/dist/test/GcpKmsMasterKeyProvider.test.js

@@ -0,0 +1,135 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g;
+    return g = { next: verb(0), "throw": verb(1), "return": verb(2) }, typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+var crypto_1 = require("crypto");
+var GcpKmsMasterKeyProvider_1 = require("../src/GcpKmsMasterKeyProvider");
+var KEY_NAME = 'projects/p/locations/l/keyRings/r/cryptoKeys/k';
+/**
+ * An in-memory stand-in for the KMS service (the adapter's only unmockable dependency is
+ * the network): encrypts/decrypts with a local AES key, and records the key resource names
+ * it was called with — so the adapter's contract (right key name, bytes-in/bytes-out,
+ * base64 at the storage boundary) is pinned without live GCP. The live path is exercised
+ * manually against a real key ring before production use (no cloud creds in CI).
+ */
+var FakeKmsClient = /** @class */ (function () {
+    function FakeKmsClient() {
+        this.encryptCalls = [];
+        this.decryptCalls = [];
+        this.key = (0, crypto_1.randomBytes)(32);
+    }
+    FakeKmsClient.prototype.encrypt = function (request) {
+        return __awaiter(this, void 0, void 0, function () {
+            var iv, cipher, ciphertext;
+            return __generator(this, function (_a) {
+                this.encryptCalls.push(request.name);
+                iv = (0, crypto_1.randomBytes)(12);
+                cipher = (0, crypto_1.createCipheriv)('aes-256-gcm', this.key, iv);
+                ciphertext = Buffer.concat([cipher.update(request.plaintext), cipher.final()]);
+                return [2 /*return*/, [{ ciphertext: Buffer.concat([iv, cipher.getAuthTag(), ciphertext]) }]];
+            });
+        });
+    };
+    FakeKmsClient.prototype.decrypt = function (request) {
+        return __awaiter(this, void 0, void 0, function () {
+            var bytes, decipher;
+            return __generator(this, function (_a) {
+                this.decryptCalls.push(request.name);
+                bytes = request.ciphertext;
+                decipher = (0, crypto_1.createDecipheriv)('aes-256-gcm', this.key, bytes.subarray(0, 12));
+                decipher.setAuthTag(bytes.subarray(12, 28));
+                return [2 /*return*/, [
+                        {
+                            plaintext: Buffer.concat([decipher.update(bytes.subarray(28)), decipher.final()]),
+                        },
+                    ]];
+            });
+        });
+    };
+    return FakeKmsClient;
+}());
+describe('GcpKmsMasterKeyProvider', function () {
+    test('wrap/unwrap round-trips data-key material through the configured KMS key', function () { return __awaiter(void 0, void 0, void 0, function () {
+        var fakeClient, provider, material, wrapped, unwrapped;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    fakeClient = new FakeKmsClient();
+                    provider = new GcpKmsMasterKeyProvider_1.GcpKmsMasterKeyProvider({ keyName: KEY_NAME }, fakeClient);
+                    material = (0, crypto_1.randomBytes)(64);
+                    return [4 /*yield*/, provider.wrapDataKey(material)];
+                case 1:
+                    wrapped = _a.sent();
+                    expect(typeof wrapped).toBe('string');
+                    expect(wrapped).not.toContain(material.toString('base64'));
+                    return [4 /*yield*/, provider.unwrapDataKey(wrapped)];
+                case 2:
+                    unwrapped = _a.sent();
+                    expect(unwrapped.equals(material)).toBe(true);
+                    expect(fakeClient.encryptCalls).toEqual([KEY_NAME]);
+                    expect(fakeClient.decryptCalls).toEqual([KEY_NAME]);
+                    expect(provider.getMasterKeyId()).toBe(KEY_NAME);
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+    test('an empty KMS response fails loudly, never returns empty key material', function () { return __awaiter(void 0, void 0, void 0, function () {
+        var emptyClient, provider;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    emptyClient = {
+                        encrypt: function () { return __awaiter(void 0, void 0, void 0, function () { return __generator(this, function (_a) {
+                            return [2 /*return*/, [{}]];
+                        }); }); },
+                        decrypt: function () { return __awaiter(void 0, void 0, void 0, function () { return __generator(this, function (_a) {
+                            return [2 /*return*/, [{}]];
+                        }); }); },
+                    };
+                    provider = new GcpKmsMasterKeyProvider_1.GcpKmsMasterKeyProvider({ keyName: KEY_NAME }, emptyClient);
+                    return [4 /*yield*/, expect(provider.wrapDataKey((0, crypto_1.randomBytes)(64))).rejects.toThrow(/no ciphertext/)];
+                case 1:
+                    _a.sent();
+                    return [4 /*yield*/, expect(provider.unwrapDataKey('AAAA')).rejects.toThrow(/no plaintext/)];
+                case 2:
+                    _a.sent();
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+});
+//# sourceMappingURL=GcpKmsMasterKeyProvider.test.js.map

package/dist/test/GcpKmsMasterKeyProvider.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GcpKmsMasterKeyProvider.test.js","sourceRoot":"","sources":["../../test/GcpKmsMasterKeyProvider.test.ts"],"names":[],"mappings":"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"}

package/generated/index.ts

@@ -0,0 +1,24 @@
+/** Load Dependency Source Graphs */
+
+import '@proteinjs/db';
+import '@proteinjs/logger';
+
+/** Generate Source Graph */
+
+const sourceGraph =
+  '{"options":{"directed":true,"multigraph":false,"compound":false},"nodes":[{"v":"@proteinjs/db-encryption-driver-gcp-kms/GcpKmsMasterKeyProvider","value":{"packageName":"@proteinjs/db-encryption-driver-gcp-kms","name":"GcpKmsMasterKeyProvider","filePath":"src/GcpKmsMasterKeyProvider.ts","qualifiedName":"@proteinjs/db-encryption-driver-gcp-kms/GcpKmsMasterKeyProvider","isAbstract":false,"isStatic":false,"visibility":"public","properties":[{"name":"config","type":{"packageName":"@proteinjs/db-encryption-driver-gcp-kms","name":"GcpKmsMasterKeyConfig","filePath":null,"qualifiedName":"@proteinjs/db-encryption-driver-gcp-kms/GcpKmsMasterKeyConfig","typeParameters":null,"directParents":null},"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"private"},{"name":"client","type":{"packageName":"@google-cloud/kms","name":"KeyManagementServiceClient","filePath":null,"qualifiedName":"@google-cloud/kms/KeyManagementServiceClient","typeParameters":null,"directParents":null},"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"private"}],"methods":[{"name":"wrapDataKey","returnType":{"packageName":"","name":"Promise<string>","filePath":null,"qualifiedName":"/Promise<string>","typeParameters":null,"directParents":null},"isAsync":true,"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"public","parameters":[{"name":"plaintextKeyMaterial","type":{"packageName":"","name":"Buffer","filePath":null,"qualifiedName":"/Buffer","typeParameters":null,"directParents":null}}]},{"name":"unwrapDataKey","returnType":{"packageName":"","name":"Promise<Buffer>","filePath":null,"qualifiedName":"/Promise<Buffer>","typeParameters":null,"directParents":null},"isAsync":true,"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"public","parameters":[{"name":"wrappedKeyMaterial","type":{"packageName":"","name":"string","filePath":null,"qualifiedName":"/string","typeParameters":null,"directParents":null}}]},{"name":"getMasterKeyId","returnType":{"packageName":"","name":"string","filePath":null,"qualifiedName":"/string","typeParameters":null,"directParents":null},"isAsync":false,"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"public","parameters":[]}],"typeParameters":[],"directParentInterfaces":[{"packageName":"@proteinjs/db","name":"MasterKeyProvider","filePath":null,"qualifiedName":"@proteinjs/db/MasterKeyProvider","properties":[],"methods":[],"typeParameters":[],"directParents":[]}],"directParentClasses":[],"sourceType":2}},{"v":"@proteinjs/db/MasterKeyProvider"}],"edges":[{"v":"@proteinjs/db-encryption-driver-gcp-kms/GcpKmsMasterKeyProvider","w":"@proteinjs/db/MasterKeyProvider","value":"implements interface"}]}';
+
+/** Generate Source Links */
+
+import { GcpKmsMasterKeyProvider } from '../src/GcpKmsMasterKeyProvider';
+
+const sourceLinks = {
+  '@proteinjs/db-encryption-driver-gcp-kms/GcpKmsMasterKeyProvider': GcpKmsMasterKeyProvider,
+};
+
+/** Load Source Graph and Links */
+
+import { SourceRepository } from '@proteinjs/reflection';
+SourceRepository.merge(sourceGraph, sourceLinks);
+
+export * from '../index';

package/index.ts

@@ -0,0 +1 @@
+export * from './src/GcpKmsMasterKeyProvider';

package/jest.config.js

@@ -0,0 +1,10 @@
+module.exports = {
+  roots: ['<rootDir>/test'],
+  transform: {
+    '^.+\\.tsx?$': 'ts-jest',
+  },
+  testRegex: '(/__tests__/.*|(\\.|/)(test|spec))\\.tsx?$',
+  moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json', 'node'],
+  testEnvironment: 'node',
+  testTimeout: 30000,
+};

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@proteinjs/db-encryption-driver-gcp-kms",
+  "version": "0.2.0",
+  "description": "Cloud KMS master-key provider for @proteinjs/db column encryption",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/proteinjs/db.git"
+  },
+  "bugs": {
+    "url": "https://github.com/proteinjs/db/issues"
+  },
+  "homepage": "https://github.com/proteinjs/db#readme",
+  "author": "Brent Bahry",
+  "license": "ISC",
+  "scripts": {
+    "clean": "rm -rf dist/ node_modules/ generated/",
+    "build": "reflection-build && tsc",
+    "test": "jest --runInBand --passWithNoTests",
+    "watch": "reflection-watch"
+  },
+  "dependencies": {
+    "@google-cloud/kms": "6.0.0",
+    "@proteinjs/db": "^1.36.0",
+    "@proteinjs/logger": "^1.0.21",
+    "@proteinjs/reflection": "^1.2.0"
+  },
+  "devDependencies": {
+    "@proteinjs/reflection-build": "^2.0.1",
+    "@types/jest": "29.5.5",
+    "@types/node": "14.0.27",
+    "@typescript-eslint/eslint-plugin": "7.8.0",
+    "@typescript-eslint/parser": "7.8.0",
+    "eslint": "8.57.0",
+    "eslint-config-prettier": "9.1.0",
+    "eslint-plugin-prettier": "5.1.3",
+    "jest": "29.7.0",
+    "ts-jest": "29.1.1",
+    "typescript": "5.2.2"
+  },
+  "main": "./dist/generated/index.js",
+  "types": "./dist/generated/index.d.ts",
+  "gitHead": "b25c88ae26fffd1c784b4c7b1174825b52751987"
+}

package/src/GcpKmsMasterKeyProvider.ts

@@ -0,0 +1,65 @@
+import { KeyManagementServiceClient } from '@google-cloud/kms';
+import { MasterKeyProvider } from '@proteinjs/db';
+
+export interface GcpKmsMasterKeyConfig {
+  /**
+   * The Cloud KMS crypto key's full resource name:
+   * `projects/<project>/locations/<location>/keyRings/<ring>/cryptoKeys/<key>`
+   */
+  keyName: string;
+}
+
+/**
+ * The production `MasterKeyProvider` for @proteinjs/db column encryption: the master key
+ * lives in Cloud KMS and never leaves the vault — KMS performs the wrap (encrypt) and
+ * unwrap (decrypt) of per-owner data keys for callers holding permission on the key.
+ *
+ * Operational shape (see the framework's `DataKeyStore`): the vault is called once per data
+ * key and cached in-process, never per row — a warm request makes zero KMS calls. Grant
+ * `roles/cloudkms.cryptoKeyEncrypterDecrypter` on the key to the identity the production
+ * server runs as (its service account) and to nothing else; granting anyone else is a
+ * configuration change Google records in admin logs that cannot be turned off.
+ *
+ * Key rotation note: KMS crypto keys can rotate their PRIMARY version automatically;
+ * `decrypt` transparently uses the version that encrypted each wrapped key, so stored
+ * wrapped data keys keep unwrapping across KMS rotations with no application involvement
+ * (per-owner DATA-key rotation is the framework's own `rotate-keys` walk, a separate
+ * concern).
+ */
+export class GcpKmsMasterKeyProvider implements MasterKeyProvider {
+  private config: GcpKmsMasterKeyConfig;
+  private client: KeyManagementServiceClient;
+
+  constructor(config: GcpKmsMasterKeyConfig, client?: KeyManagementServiceClient) {
+    this.config = config;
+    this.client = client ?? new KeyManagementServiceClient();
+  }
+
+  async wrapDataKey(plaintextKeyMaterial: Buffer): Promise<string> {
+    const [result] = await this.client.encrypt({
+      name: this.config.keyName,
+      plaintext: plaintextKeyMaterial,
+    });
+    if (!result.ciphertext) {
+      throw new Error(`Cloud KMS encrypt returned no ciphertext for key ${this.config.keyName}`);
+    }
+
+    return Buffer.from(result.ciphertext as Uint8Array).toString('base64');
+  }
+
+  async unwrapDataKey(wrappedKeyMaterial: string): Promise<Buffer> {
+    const [result] = await this.client.decrypt({
+      name: this.config.keyName,
+      ciphertext: Buffer.from(wrappedKeyMaterial, 'base64'),
+    });
+    if (!result.plaintext) {
+      throw new Error(`Cloud KMS decrypt returned no plaintext for key ${this.config.keyName}`);
+    }
+
+    return Buffer.from(result.plaintext as Uint8Array);
+  }
+
+  getMasterKeyId(): string {
+    return this.config.keyName;
+  }
+}

package/test/GcpKmsMasterKeyProvider.test.ts

@@ -0,0 +1,74 @@
+import { KeyManagementServiceClient } from '@google-cloud/kms';
+import { createCipheriv, createDecipheriv, randomBytes } from 'crypto';
+import { GcpKmsMasterKeyProvider } from '../src/GcpKmsMasterKeyProvider';
+
+const KEY_NAME = 'projects/p/locations/l/keyRings/r/cryptoKeys/k';
+
+/**
+ * An in-memory stand-in for the KMS service (the adapter's only unmockable dependency is
+ * the network): encrypts/decrypts with a local AES key, and records the key resource names
+ * it was called with — so the adapter's contract (right key name, bytes-in/bytes-out,
+ * base64 at the storage boundary) is pinned without live GCP. The live path is exercised
+ * manually against a real key ring before production use (no cloud creds in CI).
+ */
+class FakeKmsClient {
+  public encryptCalls: string[] = [];
+  public decryptCalls: string[] = [];
+  private key = randomBytes(32);
+
+  async encrypt(request: { name: string; plaintext: Buffer }): Promise<[{ ciphertext: Uint8Array }]> {
+    this.encryptCalls.push(request.name);
+    const iv = randomBytes(12);
+    const cipher = createCipheriv('aes-256-gcm', this.key, iv);
+    const ciphertext = Buffer.concat([cipher.update(request.plaintext), cipher.final()]);
+    return [{ ciphertext: Buffer.concat([iv, cipher.getAuthTag(), ciphertext]) }];
+  }
+
+  async decrypt(request: { name: string; ciphertext: Buffer }): Promise<[{ plaintext: Uint8Array }]> {
+    this.decryptCalls.push(request.name);
+    const bytes = request.ciphertext;
+    const decipher = createDecipheriv('aes-256-gcm', this.key, bytes.subarray(0, 12));
+    decipher.setAuthTag(bytes.subarray(12, 28));
+    return [
+      {
+        plaintext: Buffer.concat([decipher.update(bytes.subarray(28)), decipher.final()]),
+      },
+    ];
+  }
+}
+
+describe('GcpKmsMasterKeyProvider', () => {
+  test('wrap/unwrap round-trips data-key material through the configured KMS key', async () => {
+    const fakeClient = new FakeKmsClient();
+    const provider = new GcpKmsMasterKeyProvider(
+      { keyName: KEY_NAME },
+      fakeClient as unknown as KeyManagementServiceClient
+    );
+
+    const material = randomBytes(64);
+    const wrapped = await provider.wrapDataKey(material);
+    expect(typeof wrapped).toBe('string');
+    expect(wrapped).not.toContain(material.toString('base64'));
+
+    const unwrapped = await provider.unwrapDataKey(wrapped);
+    expect(unwrapped.equals(material)).toBe(true);
+
+    expect(fakeClient.encryptCalls).toEqual([KEY_NAME]);
+    expect(fakeClient.decryptCalls).toEqual([KEY_NAME]);
+    expect(provider.getMasterKeyId()).toBe(KEY_NAME);
+  });
+
+  test('an empty KMS response fails loudly, never returns empty key material', async () => {
+    const emptyClient = {
+      encrypt: async () => [{}],
+      decrypt: async () => [{}],
+    };
+    const provider = new GcpKmsMasterKeyProvider(
+      { keyName: KEY_NAME },
+      emptyClient as unknown as KeyManagementServiceClient
+    );
+
+    await expect(provider.wrapDataKey(randomBytes(64))).rejects.toThrow(/no ciphertext/);
+    await expect(provider.unwrapDataKey('AAAA')).rejects.toThrow(/no plaintext/);
+  });
+});

package/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "noEmitOnError": true,
+    "rootDir": "./",
+    "target": "es5",
+    "module": "commonjs",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist/",
+    "strict": true,
+    "noImplicitAny": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "typeRoots": ["./node_modules/@types"],
+    "types": ["node", "jest"]
+  },
+  "include": ["./src/**/*.ts", "./test/**/*.ts", "./generated/**/*.ts", "./generated/index.ts"],
+  "exclude": ["./dist"]
+}