@pipeline-builder/api-core 3.1.0

package/lib/helpers/access-helpers.d.ts

@@ -0,0 +1,40 @@
+import type { Request, Response } from 'express';
+/**
+ * Apply access control to a filter object.
+ *
+ * Non-system-admins are restricted to 'private' (org-scoped) resources.
+ * System admins see all access modifiers.
+ *
+ * @param filter - Query filter to modify
+ * @param req - Express request (used to check admin status)
+ * @returns Filter with accessModifier applied for non-admins
+ *
+ * @example
+ * ```typescript
+ * const effectiveFilter = applyAccessControl(filter, req);
+ * const results = await service.find(effectiveFilter, orgId);
+ * ```
+ */
+export declare function applyAccessControl<T extends {
+    accessModifier?: string;
+}>(filter: T, req: Request): T;
+/**
+ * Check whether a non-admin user may modify a public resource.
+ *
+ * Returns `true` if the request may proceed. Returns `false` and sends
+ * a 403 response if the user lacks permission.
+ *
+ * @param req - Express request
+ * @param res - Express response
+ * @param resource - Resource with an accessModifier field
+ * @returns `true` if access is allowed, `false` if blocked (response already sent)
+ *
+ * @example
+ * ```typescript
+ * if (!requirePublicAccess(req, res, pipeline)) return;
+ * await pipelineService.delete(id, orgId, userId);
+ * ```
+ */
+export declare function requirePublicAccess(req: Request, res: Response, resource: {
+    accessModifier?: string;
+}): boolean;

package/lib/helpers/access-helpers.js

@@ -0,0 +1,56 @@
+"use strict";
+// Copyright 2026 Pipeline Builder Contributors
+// SPDX-License-Identifier: Apache-2.0
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyAccessControl = applyAccessControl;
+exports.requirePublicAccess = requirePublicAccess;
+const auth_1 = require("../middleware/auth");
+const error_codes_1 = require("../types/error-codes");
+const pipeline_1 = require("../types/pipeline");
+const response_1 = require("../utils/response");
+/**
+ * Apply access control to a filter object.
+ *
+ * Non-system-admins are restricted to 'private' (org-scoped) resources.
+ * System admins see all access modifiers.
+ *
+ * @param filter - Query filter to modify
+ * @param req - Express request (used to check admin status)
+ * @returns Filter with accessModifier applied for non-admins
+ *
+ * @example
+ * ```typescript
+ * const effectiveFilter = applyAccessControl(filter, req);
+ * const results = await service.find(effectiveFilter, orgId);
+ * ```
+ */
+function applyAccessControl(filter, req) {
+    return !(0, auth_1.isSystemAdmin)(req)
+        ? { ...filter, accessModifier: pipeline_1.AccessModifier.PRIVATE }
+        : filter;
+}
+/**
+ * Check whether a non-admin user may modify a public resource.
+ *
+ * Returns `true` if the request may proceed. Returns `false` and sends
+ * a 403 response if the user lacks permission.
+ *
+ * @param req - Express request
+ * @param res - Express response
+ * @param resource - Resource with an accessModifier field
+ * @returns `true` if access is allowed, `false` if blocked (response already sent)
+ *
+ * @example
+ * ```typescript
+ * if (!requirePublicAccess(req, res, pipeline)) return;
+ * await pipelineService.delete(id, orgId, userId);
+ * ```
+ */
+function requirePublicAccess(req, res, resource) {
+    if (!(0, auth_1.isSystemAdmin)(req) && resource.accessModifier !== pipeline_1.AccessModifier.PRIVATE) {
+        (0, response_1.sendError)(res, 403, 'Only system admins can modify public resources.', error_codes_1.ErrorCode.INSUFFICIENT_PERMISSIONS);
+        return false;
+    }
+    return true;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYWNjZXNzLWhlbHBlcnMuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvaGVscGVycy9hY2Nlc3MtaGVscGVycy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiO0FBQUEsK0NBQStDO0FBQy9DLHNDQUFzQzs7QUF3QnRDLGdEQU9DO0FBbUJELGtEQWVDO0FBOURELDZDQUFtRDtBQUNuRCxzREFBaUQ7QUFDakQsZ0RBQW1EO0FBQ25ELGdEQUE4QztBQUU5Qzs7Ozs7Ozs7Ozs7Ozs7O0dBZUc7QUFDSCxTQUFnQixrQkFBa0IsQ0FDaEMsTUFBUyxFQUNULEdBQVk7SUFFWixPQUFPLENBQUMsSUFBQSxvQkFBYSxFQUFDLEdBQUcsQ0FBQztRQUN4QixDQUFDLENBQUMsRUFBRSxHQUFHLE1BQU0sRUFBRSxjQUFjLEVBQUUseUJBQWMsQ0FBQyxPQUFPLEVBQUU7UUFDdkQsQ0FBQyxDQUFDLE1BQU0sQ0FBQztBQUNiLENBQUM7QUFFRDs7Ozs7Ozs7Ozs7Ozs7OztHQWdCRztBQUNILFNBQWdCLG1CQUFtQixDQUNqQyxHQUFZLEVBQ1osR0FBYSxFQUNiLFFBQXFDO0lBRXJDLElBQUksQ0FBQyxJQUFBLG9CQUFhLEVBQUMsR0FBRyxDQUFDLElBQUksUUFBUSxDQUFDLGNBQWMsS0FBSyx5QkFBYyxDQUFDLE9BQU8sRUFBRSxDQUFDO1FBQzlFLElBQUEsb0JBQVMsRUFDUCxHQUFHLEVBQ0gsR0FBRyxFQUNILGlEQUFpRCxFQUNqRCx1QkFBUyxDQUFDLHdCQUF3QixDQUNuQyxDQUFDO1FBQ0YsT0FBTyxLQUFLLENBQUM7SUFDZixDQUFDO0lBQ0QsT0FBTyxJQUFJLENBQUM7QUFDZCxDQUFDIiwic291cmNlc0NvbnRlbnQiOlsiLy8gQ29weXJpZ2h0IDIwMjYgUGlwZWxpbmUgQnVpbGRlciBDb250cmlidXRvcnNcbi8vIFNQRFgtTGljZW5zZS1JZGVudGlmaWVyOiBBcGFjaGUtMi4wXG5cbmltcG9ydCB0eXBlIHsgUmVxdWVzdCwgUmVzcG9uc2UgfSBmcm9tICdleHByZXNzJztcbmltcG9ydCB7IGlzU3lzdGVtQWRtaW4gfSBmcm9tICcuLi9taWRkbGV3YXJlL2F1dGgnO1xuaW1wb3J0IHsgRXJyb3JDb2RlIH0gZnJvbSAnLi4vdHlwZXMvZXJyb3ItY29kZXMnO1xuaW1wb3J0IHsgQWNjZXNzTW9kaWZpZXIgfSBmcm9tICcuLi90eXBlcy9waXBlbGluZSc7XG5pbXBvcnQgeyBzZW5kRXJyb3IgfSBmcm9tICcuLi91dGlscy9yZXNwb25zZSc7XG5cbi8qKlxuICogQXBwbHkgYWNjZXNzIGNvbnRyb2wgdG8gYSBmaWx0ZXIgb2JqZWN0LlxuICpcbiAqIE5vbi1zeXN0ZW0tYWRtaW5zIGFyZSByZXN0cmljdGVkIHRvICdwcml2YXRlJyAob3JnLXNjb3BlZCkgcmVzb3VyY2VzLlxuICogU3lzdGVtIGFkbWlucyBzZWUgYWxsIGFjY2VzcyBtb2RpZmllcnMuXG4gKlxuICogQHBhcmFtIGZpbHRlciAtIFF1ZXJ5IGZpbHRlciB0byBtb2RpZnlcbiAqIEBwYXJhbSByZXEgLSBFeHByZXNzIHJlcXVlc3QgKHVzZWQgdG8gY2hlY2sgYWRtaW4gc3RhdHVzKVxuICogQHJldHVybnMgRmlsdGVyIHdpdGggYWNjZXNzTW9kaWZpZXIgYXBwbGllZCBmb3Igbm9uLWFkbWluc1xuICpcbiAqIEBleGFtcGxlXG4gKiBgYGB0eXBlc2NyaXB0XG4gKiBjb25zdCBlZmZlY3RpdmVGaWx0ZXIgPSBhcHBseUFjY2Vzc0NvbnRyb2woZmlsdGVyLCByZXEpO1xuICogY29uc3QgcmVzdWx0cyA9IGF3YWl0IHNlcnZpY2UuZmluZChlZmZlY3RpdmVGaWx0ZXIsIG9yZ0lkKTtcbiAqIGBgYFxuICovXG5leHBvcnQgZnVuY3Rpb24gYXBwbHlBY2Nlc3NDb250cm9sPFQgZXh0ZW5kcyB7IGFjY2Vzc01vZGlmaWVyPzogc3RyaW5nIH0+KFxuICBmaWx0ZXI6IFQsXG4gIHJlcTogUmVxdWVzdCxcbik6IFQge1xuICByZXR1cm4gIWlzU3lzdGVtQWRtaW4ocmVxKVxuICAgID8geyAuLi5maWx0ZXIsIGFjY2Vzc01vZGlmaWVyOiBBY2Nlc3NNb2RpZmllci5QUklWQVRFIH1cbiAgICA6IGZpbHRlcjtcbn1cblxuLyoqXG4gKiBDaGVjayB3aGV0aGVyIGEgbm9uLWFkbWluIHVzZXIgbWF5IG1vZGlmeSBhIHB1YmxpYyByZXNvdXJjZS5cbiAqXG4gKiBSZXR1cm5zIGB0cnVlYCBpZiB0aGUgcmVxdWVzdCBtYXkgcHJvY2VlZC4gUmV0dXJucyBgZmFsc2VgIGFuZCBzZW5kc1xuICogYSA0MDMgcmVzcG9uc2UgaWYgdGhlIHVzZXIgbGFja3MgcGVybWlzc2lvbi5cbiAqXG4gKiBAcGFyYW0gcmVxIC0gRXhwcmVzcyByZXF1ZXN0XG4gKiBAcGFyYW0gcmVzIC0gRXhwcmVzcyByZXNwb25zZVxuICogQHBhcmFtIHJlc291cmNlIC0gUmVzb3VyY2Ugd2l0aCBhbiBhY2Nlc3NNb2RpZmllciBmaWVsZFxuICogQHJldHVybnMgYHRydWVgIGlmIGFjY2VzcyBpcyBhbGxvd2VkLCBgZmFsc2VgIGlmIGJsb2NrZWQgKHJlc3BvbnNlIGFscmVhZHkgc2VudClcbiAqXG4gKiBAZXhhbXBsZVxuICogYGBgdHlwZXNjcmlwdFxuICogaWYgKCFyZXF1aXJlUHVibGljQWNjZXNzKHJlcSwgcmVzLCBwaXBlbGluZSkpIHJldHVybjtcbiAqIGF3YWl0IHBpcGVsaW5lU2VydmljZS5kZWxldGUoaWQsIG9yZ0lkLCB1c2VySWQpO1xuICogYGBgXG4gKi9cbmV4cG9ydCBmdW5jdGlvbiByZXF1aXJlUHVibGljQWNjZXNzKFxuICByZXE6IFJlcXVlc3QsXG4gIHJlczogUmVzcG9uc2UsXG4gIHJlc291cmNlOiB7IGFjY2Vzc01vZGlmaWVyPzogc3RyaW5nIH0sXG4pOiBib29sZWFuIHtcbiAgaWYgKCFpc1N5c3RlbUFkbWluKHJlcSkgJiYgcmVzb3VyY2UuYWNjZXNzTW9kaWZpZXIgIT09IEFjY2Vzc01vZGlmaWVyLlBSSVZBVEUpIHtcbiAgICBzZW5kRXJyb3IoXG4gICAgICByZXMsXG4gICAgICA0MDMsXG4gICAgICAnT25seSBzeXN0ZW0gYWRtaW5zIGNhbiBtb2RpZnkgcHVibGljIHJlc291cmNlcy4nLFxuICAgICAgRXJyb3JDb2RlLklOU1VGRklDSUVOVF9QRVJNSVNTSU9OUyxcbiAgICApO1xuICAgIHJldHVybiBmYWxzZTtcbiAgfVxuICByZXR1cm4gdHJ1ZTtcbn1cbiJdfQ==

package/lib/helpers/crud-helpers.d.ts

@@ -0,0 +1,16 @@
+import type { Response } from 'express';
+/**
+ * Generic record normalizer - ensures array fields are always arrays
+ * @param record - The record to normalize
+ * @param arrayFields - Fields that should be arrays
+ * @returns Normalized record with array fields guaranteed to be arrays
+ */
+export declare function normalizeArrayFields<T extends Record<string, unknown>>(record: T, arrayFields: (keyof T)[]): T;
+/**
+ * Generic entity not-found response
+ * Sends standardized 404 response for missing entities
+ * @param res - Express response object
+ * @param entityName - Name of the entity type (e.g., "Pipeline", "Plugin")
+ * @returns Express response
+ */
+export declare function sendEntityNotFound(res: Response, entityName: string): void;

package/lib/helpers/crud-helpers.js

@@ -0,0 +1,34 @@
+"use strict";
+// Copyright 2026 Pipeline Builder Contributors
+// SPDX-License-Identifier: Apache-2.0
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeArrayFields = normalizeArrayFields;
+exports.sendEntityNotFound = sendEntityNotFound;
+const error_codes_1 = require("../types/error-codes");
+const response_1 = require("../utils/response");
+/**
+ * Generic record normalizer - ensures array fields are always arrays
+ * @param record - The record to normalize
+ * @param arrayFields - Fields that should be arrays
+ * @returns Normalized record with array fields guaranteed to be arrays
+ */
+function normalizeArrayFields(record, arrayFields) {
+    const normalized = { ...record };
+    for (const field of arrayFields) {
+        if (field in normalized && !Array.isArray(normalized[field])) {
+            normalized[field] = [];
+        }
+    }
+    return normalized;
+}
+/**
+ * Generic entity not-found response
+ * Sends standardized 404 response for missing entities
+ * @param res - Express response object
+ * @param entityName - Name of the entity type (e.g., "Pipeline", "Plugin")
+ * @returns Express response
+ */
+function sendEntityNotFound(res, entityName) {
+    (0, response_1.sendError)(res, 404, `${entityName} not found.`, error_codes_1.ErrorCode.NOT_FOUND);
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY3J1ZC1oZWxwZXJzLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL2hlbHBlcnMvY3J1ZC1oZWxwZXJzLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiI7QUFBQSwrQ0FBK0M7QUFDL0Msc0NBQXNDOztBQVl0QyxvREFXQztBQVNELGdEQUVDO0FBL0JELHNEQUFpRDtBQUNqRCxnREFBOEM7QUFFOUM7Ozs7O0dBS0c7QUFDSCxTQUFnQixvQkFBb0IsQ0FDbEMsTUFBUyxFQUNULFdBQXdCO0lBRXhCLE1BQU0sVUFBVSxHQUFHLEVBQUUsR0FBRyxNQUFNLEVBQUUsQ0FBQztJQUNqQyxLQUFLLE1BQU0sS0FBSyxJQUFJLFdBQVcsRUFBRSxDQUFDO1FBQ2hDLElBQUksS0FBSyxJQUFJLFVBQVUsSUFBSSxDQUFDLEtBQUssQ0FBQyxPQUFPLENBQUMsVUFBVSxDQUFDLEtBQUssQ0FBQyxDQUFDLEVBQUUsQ0FBQztZQUM1RCxVQUFzQyxDQUFDLEtBQWUsQ0FBQyxHQUFHLEVBQUUsQ0FBQztRQUNoRSxDQUFDO0lBQ0gsQ0FBQztJQUNELE9BQU8sVUFBVSxDQUFDO0FBQ3BCLENBQUM7QUFFRDs7Ozs7O0dBTUc7QUFDSCxTQUFnQixrQkFBa0IsQ0FBQyxHQUFhLEVBQUUsVUFBa0I7SUFDbEUsSUFBQSxvQkFBUyxFQUFDLEdBQUcsRUFBRSxHQUFHLEVBQUUsR0FBRyxVQUFVLGFBQWEsRUFBRSx1QkFBUyxDQUFDLFNBQVMsQ0FBQyxDQUFDO0FBQ3ZFLENBQUMiLCJzb3VyY2VzQ29udGVudCI6WyIvLyBDb3B5cmlnaHQgMjAyNiBQaXBlbGluZSBCdWlsZGVyIENvbnRyaWJ1dG9yc1xuLy8gU1BEWC1MaWNlbnNlLUlkZW50aWZpZXI6IEFwYWNoZS0yLjBcblxuaW1wb3J0IHR5cGUgeyBSZXNwb25zZSB9IGZyb20gJ2V4cHJlc3MnO1xuaW1wb3J0IHsgRXJyb3JDb2RlIH0gZnJvbSAnLi4vdHlwZXMvZXJyb3ItY29kZXMnO1xuaW1wb3J0IHsgc2VuZEVycm9yIH0gZnJvbSAnLi4vdXRpbHMvcmVzcG9uc2UnO1xuXG4vKipcbiAqIEdlbmVyaWMgcmVjb3JkIG5vcm1hbGl6ZXIgLSBlbnN1cmVzIGFycmF5IGZpZWxkcyBhcmUgYWx3YXlzIGFycmF5c1xuICogQHBhcmFtIHJlY29yZCAtIFRoZSByZWNvcmQgdG8gbm9ybWFsaXplXG4gKiBAcGFyYW0gYXJyYXlGaWVsZHMgLSBGaWVsZHMgdGhhdCBzaG91bGQgYmUgYXJyYXlzXG4gKiBAcmV0dXJucyBOb3JtYWxpemVkIHJlY29yZCB3aXRoIGFycmF5IGZpZWxkcyBndWFyYW50ZWVkIHRvIGJlIGFycmF5c1xuICovXG5leHBvcnQgZnVuY3Rpb24gbm9ybWFsaXplQXJyYXlGaWVsZHM8VCBleHRlbmRzIFJlY29yZDxzdHJpbmcsIHVua25vd24+PihcbiAgcmVjb3JkOiBULFxuICBhcnJheUZpZWxkczogKGtleW9mIFQpW10sXG4pOiBUIHtcbiAgY29uc3Qgbm9ybWFsaXplZCA9IHsgLi4ucmVjb3JkIH07XG4gIGZvciAoY29uc3QgZmllbGQgb2YgYXJyYXlGaWVsZHMpIHtcbiAgICBpZiAoZmllbGQgaW4gbm9ybWFsaXplZCAmJiAhQXJyYXkuaXNBcnJheShub3JtYWxpemVkW2ZpZWxkXSkpIHtcbiAgICAgIChub3JtYWxpemVkIGFzIFJlY29yZDxzdHJpbmcsIHVua25vd24+KVtmaWVsZCBhcyBzdHJpbmddID0gW107XG4gICAgfVxuICB9XG4gIHJldHVybiBub3JtYWxpemVkO1xufVxuXG4vKipcbiAqIEdlbmVyaWMgZW50aXR5IG5vdC1mb3VuZCByZXNwb25zZVxuICogU2VuZHMgc3RhbmRhcmRpemVkIDQwNCByZXNwb25zZSBmb3IgbWlzc2luZyBlbnRpdGllc1xuICogQHBhcmFtIHJlcyAtIEV4cHJlc3MgcmVzcG9uc2Ugb2JqZWN0XG4gKiBAcGFyYW0gZW50aXR5TmFtZSAtIE5hbWUgb2YgdGhlIGVudGl0eSB0eXBlIChlLmcuLCBcIlBpcGVsaW5lXCIsIFwiUGx1Z2luXCIpXG4gKiBAcmV0dXJucyBFeHByZXNzIHJlc3BvbnNlXG4gKi9cbmV4cG9ydCBmdW5jdGlvbiBzZW5kRW50aXR5Tm90Rm91bmQocmVzOiBSZXNwb25zZSwgZW50aXR5TmFtZTogc3RyaW5nKTogdm9pZCB7XG4gIHNlbmRFcnJvcihyZXMsIDQwNCwgYCR7ZW50aXR5TmFtZX0gbm90IGZvdW5kLmAsIEVycm9yQ29kZS5OT1RfRk9VTkQpO1xufVxuIl19

package/lib/helpers/index.d.ts

@@ -0,0 +1,4 @@
+export * from './crud-helpers';
+export * from './access-helpers';
+export * from './mask-helpers';
+export * from './sse-helpers';

package/lib/helpers/index.js

@@ -0,0 +1,23 @@
+"use strict";
+// Copyright 2026 Pipeline Builder Contributors
+// SPDX-License-Identifier: Apache-2.0
+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("./crud-helpers"), exports);
+__exportStar(require("./access-helpers"), exports);
+__exportStar(require("./mask-helpers"), exports);
+__exportStar(require("./sse-helpers"), exports);
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvaGVscGVycy9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiO0FBQUEsK0NBQStDO0FBQy9DLHNDQUFzQzs7Ozs7Ozs7Ozs7Ozs7OztBQUV0QyxpREFBK0I7QUFDL0IsbURBQWlDO0FBQ2pDLGlEQUErQjtBQUMvQixnREFBOEIiLCJzb3VyY2VzQ29udGVudCI6WyIvLyBDb3B5cmlnaHQgMjAyNiBQaXBlbGluZSBCdWlsZGVyIENvbnRyaWJ1dG9yc1xuLy8gU1BEWC1MaWNlbnNlLUlkZW50aWZpZXI6IEFwYWNoZS0yLjBcblxuZXhwb3J0ICogZnJvbSAnLi9jcnVkLWhlbHBlcnMnO1xuZXhwb3J0ICogZnJvbSAnLi9hY2Nlc3MtaGVscGVycyc7XG5leHBvcnQgKiBmcm9tICcuL21hc2staGVscGVycyc7XG5leHBvcnQgKiBmcm9tICcuL3NzZS1oZWxwZXJzJztcbiJdfQ==

package/lib/helpers/mask-helpers.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Mask the middle digits of a sensitive identifier.
+ * Preserves the first and last `visible` characters, replacing the rest with asterisks.
+ *
+ * @param value - The string to mask
+ * @param visible - Number of characters to keep visible on each side (default: 4)
+ * @returns Masked string, or '****' if the input is too short
+ *
+ * @example maskId('123456789012') → '1234****9012'
+ */
+export declare function maskId(value: string, visible?: number): string;
+/**
+ * One-way hash of a sensitive identifier using SHA-256.
+ * Returns a deterministic, fixed-length hex string that cannot be reversed.
+ *
+ * @param value - The sensitive value to hash (e.g. AWS account number)
+ * @param length - Number of hex characters to return (default: 12, matching AWS account length)
+ * @returns Truncated SHA-256 hex digest
+ *
+ * @example hashId('123456789012') → 'a1b2c3d4e5f6'
+ */
+export declare function hashId(value: string, length?: number): string;
+/**
+ * Replace the AWS account number in an ARN with its SHA-256 hash.
+ * Both the deploy registration and event ingestion sides call this function,
+ * so registry lookups still match — the real account never reaches the database.
+ *
+ * ARN format: `arn:partition:service:region:account:resource`
+ *
+ * @example hashAccountInArn('arn:aws:codepipeline:us-east-1:123456789012:my-pipeline')
+ *   → 'arn:aws:codepipeline:us-east-1:a1b2c3d4e5f6:my-pipeline'
+ */
+export declare function hashAccountInArn(arn: string): string;

package/lib/helpers/mask-helpers.js

@@ -0,0 +1,54 @@
+"use strict";
+// Copyright 2026 Pipeline Builder Contributors
+// SPDX-License-Identifier: Apache-2.0
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.maskId = maskId;
+exports.hashId = hashId;
+exports.hashAccountInArn = hashAccountInArn;
+const crypto_1 = require("crypto");
+/**
+ * Mask the middle digits of a sensitive identifier.
+ * Preserves the first and last `visible` characters, replacing the rest with asterisks.
+ *
+ * @param value - The string to mask
+ * @param visible - Number of characters to keep visible on each side (default: 4)
+ * @returns Masked string, or '****' if the input is too short
+ *
+ * @example maskId('123456789012') → '1234****9012'
+ */
+function maskId(value, visible = 4) {
+    if (!value || value.length <= visible * 2)
+        return '****';
+    return value.slice(0, visible) + '*'.repeat(value.length - visible * 2) + value.slice(-visible);
+}
+/**
+ * One-way hash of a sensitive identifier using SHA-256.
+ * Returns a deterministic, fixed-length hex string that cannot be reversed.
+ *
+ * @param value - The sensitive value to hash (e.g. AWS account number)
+ * @param length - Number of hex characters to return (default: 12, matching AWS account length)
+ * @returns Truncated SHA-256 hex digest
+ *
+ * @example hashId('123456789012') → 'a1b2c3d4e5f6'
+ */
+function hashId(value, length = 12) {
+    return (0, crypto_1.createHash)('sha256').update(value).digest('hex').slice(0, length);
+}
+/**
+ * Replace the AWS account number in an ARN with its SHA-256 hash.
+ * Both the deploy registration and event ingestion sides call this function,
+ * so registry lookups still match — the real account never reaches the database.
+ *
+ * ARN format: `arn:partition:service:region:account:resource`
+ *
+ * @example hashAccountInArn('arn:aws:codepipeline:us-east-1:123456789012:my-pipeline')
+ *   → 'arn:aws:codepipeline:us-east-1:a1b2c3d4e5f6:my-pipeline'
+ */
+function hashAccountInArn(arn) {
+    const parts = arn.split(':');
+    if (parts.length < 5 || !parts[4])
+        return arn;
+    parts[4] = hashId(parts[4]);
+    return parts.join(':');
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoibWFzay1oZWxwZXJzLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL2hlbHBlcnMvbWFzay1oZWxwZXJzLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiI7QUFBQSwrQ0FBK0M7QUFDL0Msc0NBQXNDOztBQWN0Qyx3QkFHQztBQVlELHdCQUVDO0FBWUQsNENBS0M7QUE5Q0QsbUNBQW9DO0FBRXBDOzs7Ozs7Ozs7R0FTRztBQUNILFNBQWdCLE1BQU0sQ0FBQyxLQUFhLEVBQUUsT0FBTyxHQUFHLENBQUM7SUFDL0MsSUFBSSxDQUFDLEtBQUssSUFBSSxLQUFLLENBQUMsTUFBTSxJQUFJLE9BQU8sR0FBRyxDQUFDO1FBQUUsT0FBTyxNQUFNLENBQUM7SUFDekQsT0FBTyxLQUFLLENBQUMsS0FBSyxDQUFDLENBQUMsRUFBRSxPQUFPLENBQUMsR0FBRyxHQUFHLENBQUMsTUFBTSxDQUFDLEtBQUssQ0FBQyxNQUFNLEdBQUcsT0FBTyxHQUFHLENBQUMsQ0FBQyxHQUFHLEtBQUssQ0FBQyxLQUFLLENBQUMsQ0FBQyxPQUFPLENBQUMsQ0FBQztBQUNsRyxDQUFDO0FBRUQ7Ozs7Ozs7OztHQVNHO0FBQ0gsU0FBZ0IsTUFBTSxDQUFDLEtBQWEsRUFBRSxNQUFNLEdBQUcsRUFBRTtJQUMvQyxPQUFPLElBQUEsbUJBQVUsRUFBQyxRQUFRLENBQUMsQ0FBQyxNQUFNLENBQUMsS0FBSyxDQUFDLENBQUMsTUFBTSxDQUFDLEtBQUssQ0FBQyxDQUFDLEtBQUssQ0FBQyxDQUFDLEVBQUUsTUFBTSxDQUFDLENBQUM7QUFDM0UsQ0FBQztBQUVEOzs7Ozs7Ozs7R0FTRztBQUNILFNBQWdCLGdCQUFnQixDQUFDLEdBQVc7SUFDMUMsTUFBTSxLQUFLLEdBQUcsR0FBRyxDQUFDLEtBQUssQ0FBQyxHQUFHLENBQUMsQ0FBQztJQUM3QixJQUFJLEtBQUssQ0FBQyxNQUFNLEdBQUcsQ0FBQyxJQUFJLENBQUMsS0FBSyxDQUFDLENBQUMsQ0FBQztRQUFFLE9BQU8sR0FBRyxDQUFDO0lBQzlDLEtBQUssQ0FBQyxDQUFDLENBQUMsR0FBRyxNQUFNLENBQUMsS0FBSyxDQUFDLENBQUMsQ0FBQyxDQUFDLENBQUM7SUFDNUIsT0FBTyxLQUFLLENBQUMsSUFBSSxDQUFDLEdBQUcsQ0FBQyxDQUFDO0FBQ3pCLENBQUMiLCJzb3VyY2VzQ29udGVudCI6WyIvLyBDb3B5cmlnaHQgMjAyNiBQaXBlbGluZSBCdWlsZGVyIENvbnRyaWJ1dG9yc1xuLy8gU1BEWC1MaWNlbnNlLUlkZW50aWZpZXI6IEFwYWNoZS0yLjBcblxuaW1wb3J0IHsgY3JlYXRlSGFzaCB9IGZyb20gJ2NyeXB0byc7XG5cbi8qKlxuICogTWFzayB0aGUgbWlkZGxlIGRpZ2l0cyBvZiBhIHNlbnNpdGl2ZSBpZGVudGlmaWVyLlxuICogUHJlc2VydmVzIHRoZSBmaXJzdCBhbmQgbGFzdCBgdmlzaWJsZWAgY2hhcmFjdGVycywgcmVwbGFjaW5nIHRoZSByZXN0IHdpdGggYXN0ZXJpc2tzLlxuICpcbiAqIEBwYXJhbSB2YWx1ZSAtIFRoZSBzdHJpbmcgdG8gbWFza1xuICogQHBhcmFtIHZpc2libGUgLSBOdW1iZXIgb2YgY2hhcmFjdGVycyB0byBrZWVwIHZpc2libGUgb24gZWFjaCBzaWRlIChkZWZhdWx0OiA0KVxuICogQHJldHVybnMgTWFza2VkIHN0cmluZywgb3IgJyoqKionIGlmIHRoZSBpbnB1dCBpcyB0b28gc2hvcnRcbiAqXG4gKiBAZXhhbXBsZSBtYXNrSWQoJzEyMzQ1Njc4OTAxMicpIOKGkiAnMTIzNCoqKio5MDEyJ1xuICovXG5leHBvcnQgZnVuY3Rpb24gbWFza0lkKHZhbHVlOiBzdHJpbmcsIHZpc2libGUgPSA0KTogc3RyaW5nIHtcbiAgaWYgKCF2YWx1ZSB8fCB2YWx1ZS5sZW5ndGggPD0gdmlzaWJsZSAqIDIpIHJldHVybiAnKioqKic7XG4gIHJldHVybiB2YWx1ZS5zbGljZSgwLCB2aXNpYmxlKSArICcqJy5yZXBlYXQodmFsdWUubGVuZ3RoIC0gdmlzaWJsZSAqIDIpICsgdmFsdWUuc2xpY2UoLXZpc2libGUpO1xufVxuXG4vKipcbiAqIE9uZS13YXkgaGFzaCBvZiBhIHNlbnNpdGl2ZSBpZGVudGlmaWVyIHVzaW5nIFNIQS0yNTYuXG4gKiBSZXR1cm5zIGEgZGV0ZXJtaW5pc3RpYywgZml4ZWQtbGVuZ3RoIGhleCBzdHJpbmcgdGhhdCBjYW5ub3QgYmUgcmV2ZXJzZWQuXG4gKlxuICogQHBhcmFtIHZhbHVlIC0gVGhlIHNlbnNpdGl2ZSB2YWx1ZSB0byBoYXNoIChlLmcuIEFXUyBhY2NvdW50IG51bWJlcilcbiAqIEBwYXJhbSBsZW5ndGggLSBOdW1iZXIgb2YgaGV4IGNoYXJhY3RlcnMgdG8gcmV0dXJuIChkZWZhdWx0OiAxMiwgbWF0Y2hpbmcgQVdTIGFjY291bnQgbGVuZ3RoKVxuICogQHJldHVybnMgVHJ1bmNhdGVkIFNIQS0yNTYgaGV4IGRpZ2VzdFxuICpcbiAqIEBleGFtcGxlIGhhc2hJZCgnMTIzNDU2Nzg5MDEyJykg4oaSICdhMWIyYzNkNGU1ZjYnXG4gKi9cbmV4cG9ydCBmdW5jdGlvbiBoYXNoSWQodmFsdWU6IHN0cmluZywgbGVuZ3RoID0gMTIpOiBzdHJpbmcge1xuICByZXR1cm4gY3JlYXRlSGFzaCgnc2hhMjU2JykudXBkYXRlKHZhbHVlKS5kaWdlc3QoJ2hleCcpLnNsaWNlKDAsIGxlbmd0aCk7XG59XG5cbi8qKlxuICogUmVwbGFjZSB0aGUgQVdTIGFjY291bnQgbnVtYmVyIGluIGFuIEFSTiB3aXRoIGl0cyBTSEEtMjU2IGhhc2guXG4gKiBCb3RoIHRoZSBkZXBsb3kgcmVnaXN0cmF0aW9uIGFuZCBldmVudCBpbmdlc3Rpb24gc2lkZXMgY2FsbCB0aGlzIGZ1bmN0aW9uLFxuICogc28gcmVnaXN0cnkgbG9va3VwcyBzdGlsbCBtYXRjaCDigJQgdGhlIHJlYWwgYWNjb3VudCBuZXZlciByZWFjaGVzIHRoZSBkYXRhYmFzZS5cbiAqXG4gKiBBUk4gZm9ybWF0OiBgYXJuOnBhcnRpdGlvbjpzZXJ2aWNlOnJlZ2lvbjphY2NvdW50OnJlc291cmNlYFxuICpcbiAqIEBleGFtcGxlIGhhc2hBY2NvdW50SW5Bcm4oJ2Fybjphd3M6Y29kZXBpcGVsaW5lOnVzLWVhc3QtMToxMjM0NTY3ODkwMTI6bXktcGlwZWxpbmUnKVxuICogICDihpIgJ2Fybjphd3M6Y29kZXBpcGVsaW5lOnVzLWVhc3QtMTphMWIyYzNkNGU1ZjY6bXktcGlwZWxpbmUnXG4gKi9cbmV4cG9ydCBmdW5jdGlvbiBoYXNoQWNjb3VudEluQXJuKGFybjogc3RyaW5nKTogc3RyaW5nIHtcbiAgY29uc3QgcGFydHMgPSBhcm4uc3BsaXQoJzonKTtcbiAgaWYgKHBhcnRzLmxlbmd0aCA8IDUgfHwgIXBhcnRzWzRdKSByZXR1cm4gYXJuO1xuICBwYXJ0c1s0XSA9IGhhc2hJZChwYXJ0c1s0XSk7XG4gIHJldHVybiBwYXJ0cy5qb2luKCc6Jyk7XG59XG4iXX0=

package/lib/helpers/sse-helpers.d.ts

@@ -0,0 +1,13 @@
+import type { Request, Response } from 'express';
+/**
+ * Set SSE response headers and flush.
+ * Returns an `aborted()` function to check if the client disconnected.
+ */
+export declare function initSSEStream(req: Request, res: Response, timeoutMs: number): {
+    aborted: () => boolean;
+};
+/**
+ * Classify AI generation errors and send the appropriate HTTP response or SSE event.
+ * If headers are already sent (streaming), writes an SSE error event and ends the response.
+ */
+export declare function handleAIError(res: Response, message: string, fallbackMessage: string): void;

package/lib/helpers/sse-helpers.js

@@ -0,0 +1,40 @@
+"use strict";
+// Copyright 2026 Pipeline Builder Contributors
+// SPDX-License-Identifier: Apache-2.0
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.initSSEStream = initSSEStream;
+exports.handleAIError = handleAIError;
+const response_1 = require("../utils/response");
+/**
+ * Set SSE response headers and flush.
+ * Returns an `aborted()` function to check if the client disconnected.
+ */
+function initSSEStream(req, res, timeoutMs) {
+    res.setHeader('Content-Type', 'text/event-stream');
+    res.setHeader('Cache-Control', 'no-cache');
+    res.setHeader('Connection', 'keep-alive');
+    res.setHeader('X-Accel-Buffering', 'no');
+    res.setTimeout(timeoutMs);
+    res.flushHeaders();
+    let _aborted = false;
+    req.on('close', () => { _aborted = true; });
+    return { aborted: () => _aborted };
+}
+/**
+ * Classify AI generation errors and send the appropriate HTTP response or SSE event.
+ * If headers are already sent (streaming), writes an SSE error event and ends the response.
+ */
+function handleAIError(res, message, fallbackMessage) {
+    if (!res.headersSent) {
+        if (message.includes('not configured') || message.includes('API key')) {
+            return (0, response_1.sendInternalError)(res, 'AI generation is not configured for the requested provider');
+        }
+        if (message.includes('not available for provider')) {
+            return (0, response_1.sendBadRequest)(res, message);
+        }
+        return (0, response_1.sendInternalError)(res, fallbackMessage, { details: message });
+    }
+    res.write(`data: ${JSON.stringify({ type: 'error', message })}\n\n`);
+    res.end();
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic3NlLWhlbHBlcnMuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvaGVscGVycy9zc2UtaGVscGVycy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiO0FBQUEsK0NBQStDO0FBQy9DLHNDQUFzQzs7QUFTdEMsc0NBVUM7QUFNRCxzQ0FZQztBQWxDRCxnREFBc0U7QUFFdEU7OztHQUdHO0FBQ0gsU0FBZ0IsYUFBYSxDQUFDLEdBQVksRUFBRSxHQUFhLEVBQUUsU0FBaUI7SUFDMUUsR0FBRyxDQUFDLFNBQVMsQ0FBQyxjQUFjLEVBQUUsbUJBQW1CLENBQUMsQ0FBQztJQUNuRCxHQUFHLENBQUMsU0FBUyxDQUFDLGVBQWUsRUFBRSxVQUFVLENBQUMsQ0FBQztJQUMzQyxHQUFHLENBQUMsU0FBUyxDQUFDLFlBQVksRUFBRSxZQUFZLENBQUMsQ0FBQztJQUMxQyxHQUFHLENBQUMsU0FBUyxDQUFDLG1CQUFtQixFQUFFLElBQUksQ0FBQyxDQUFDO0lBQ3pDLEdBQUcsQ0FBQyxVQUFVLENBQUMsU0FBUyxDQUFDLENBQUM7SUFDMUIsR0FBRyxDQUFDLFlBQVksRUFBRSxDQUFDO0lBQ25CLElBQUksUUFBUSxHQUFHLEtBQUssQ0FBQztJQUNyQixHQUFHLENBQUMsRUFBRSxDQUFDLE9BQU8sRUFBRSxHQUFHLEVBQUUsR0FBRyxRQUFRLEdBQUcsSUFBSSxDQUFDLENBQUMsQ0FBQyxDQUFDLENBQUM7SUFDNUMsT0FBTyxFQUFFLE9BQU8sRUFBRSxHQUFHLEVBQUUsQ0FBQyxRQUFRLEVBQUUsQ0FBQztBQUNyQyxDQUFDO0FBRUQ7OztHQUdHO0FBQ0gsU0FBZ0IsYUFBYSxDQUFDLEdBQWEsRUFBRSxPQUFlLEVBQUUsZUFBdUI7SUFDbkYsSUFBSSxDQUFDLEdBQUcsQ0FBQyxXQUFXLEVBQUUsQ0FBQztRQUNyQixJQUFJLE9BQU8sQ0FBQyxRQUFRLENBQUMsZ0JBQWdCLENBQUMsSUFBSSxPQUFPLENBQUMsUUFBUSxDQUFDLFNBQVMsQ0FBQyxFQUFFLENBQUM7WUFDdEUsT0FBTyxJQUFBLDRCQUFpQixFQUFDLEdBQUcsRUFBRSw0REFBNEQsQ0FBQyxDQUFDO1FBQzlGLENBQUM7UUFDRCxJQUFJLE9BQU8sQ0FBQyxRQUFRLENBQUMsNEJBQTRCLENBQUMsRUFBRSxDQUFDO1lBQ25ELE9BQU8sSUFBQSx5QkFBYyxFQUFDLEdBQUcsRUFBRSxPQUFPLENBQUMsQ0FBQztRQUN0QyxDQUFDO1FBQ0QsT0FBTyxJQUFBLDRCQUFpQixFQUFDLEdBQUcsRUFBRSxlQUFlLEVBQUUsRUFBRSxPQUFPLEVBQUUsT0FBTyxFQUFFLENBQUMsQ0FBQztJQUN2RSxDQUFDO0lBQ0QsR0FBRyxDQUFDLEtBQUssQ0FBQyxTQUFTLElBQUksQ0FBQyxTQUFTLENBQUMsRUFBRSxJQUFJLEVBQUUsT0FBTyxFQUFFLE9BQU8sRUFBRSxDQUFDLE1BQU0sQ0FBQyxDQUFDO0lBQ3JFLEdBQUcsQ0FBQyxHQUFHLEVBQUUsQ0FBQztBQUNaLENBQUMiLCJzb3VyY2VzQ29udGVudCI6WyIvLyBDb3B5cmlnaHQgMjAyNiBQaXBlbGluZSBCdWlsZGVyIENvbnRyaWJ1dG9yc1xuLy8gU1BEWC1MaWNlbnNlLUlkZW50aWZpZXI6IEFwYWNoZS0yLjBcblxuaW1wb3J0IHR5cGUgeyBSZXF1ZXN0LCBSZXNwb25zZSB9IGZyb20gJ2V4cHJlc3MnO1xuaW1wb3J0IHsgc2VuZEJhZFJlcXVlc3QsIHNlbmRJbnRlcm5hbEVycm9yIH0gZnJvbSAnLi4vdXRpbHMvcmVzcG9uc2UnO1xuXG4vKipcbiAqIFNldCBTU0UgcmVzcG9uc2UgaGVhZGVycyBhbmQgZmx1c2guXG4gKiBSZXR1cm5zIGFuIGBhYm9ydGVkKClgIGZ1bmN0aW9uIHRvIGNoZWNrIGlmIHRoZSBjbGllbnQgZGlzY29ubmVjdGVkLlxuICovXG5leHBvcnQgZnVuY3Rpb24gaW5pdFNTRVN0cmVhbShyZXE6IFJlcXVlc3QsIHJlczogUmVzcG9uc2UsIHRpbWVvdXRNczogbnVtYmVyKTogeyBhYm9ydGVkOiAoKSA9PiBib29sZWFuIH0ge1xuICByZXMuc2V0SGVhZGVyKCdDb250ZW50LVR5cGUnLCAndGV4dC9ldmVudC1zdHJlYW0nKTtcbiAgcmVzLnNldEhlYWRlcignQ2FjaGUtQ29udHJvbCcsICduby1jYWNoZScpO1xuICByZXMuc2V0SGVhZGVyKCdDb25uZWN0aW9uJywgJ2tlZXAtYWxpdmUnKTtcbiAgcmVzLnNldEhlYWRlcignWC1BY2NlbC1CdWZmZXJpbmcnLCAnbm8nKTtcbiAgcmVzLnNldFRpbWVvdXQodGltZW91dE1zKTtcbiAgcmVzLmZsdXNoSGVhZGVycygpO1xuICBsZXQgX2Fib3J0ZWQgPSBmYWxzZTtcbiAgcmVxLm9uKCdjbG9zZScsICgpID0+IHsgX2Fib3J0ZWQgPSB0cnVlOyB9KTtcbiAgcmV0dXJuIHsgYWJvcnRlZDogKCkgPT4gX2Fib3J0ZWQgfTtcbn1cblxuLyoqXG4gKiBDbGFzc2lmeSBBSSBnZW5lcmF0aW9uIGVycm9ycyBhbmQgc2VuZCB0aGUgYXBwcm9wcmlhdGUgSFRUUCByZXNwb25zZSBvciBTU0UgZXZlbnQuXG4gKiBJZiBoZWFkZXJzIGFyZSBhbHJlYWR5IHNlbnQgKHN0cmVhbWluZyksIHdyaXRlcyBhbiBTU0UgZXJyb3IgZXZlbnQgYW5kIGVuZHMgdGhlIHJlc3BvbnNlLlxuICovXG5leHBvcnQgZnVuY3Rpb24gaGFuZGxlQUlFcnJvcihyZXM6IFJlc3BvbnNlLCBtZXNzYWdlOiBzdHJpbmcsIGZhbGxiYWNrTWVzc2FnZTogc3RyaW5nKTogdm9pZCB7XG4gIGlmICghcmVzLmhlYWRlcnNTZW50KSB7XG4gICAgaWYgKG1lc3NhZ2UuaW5jbHVkZXMoJ25vdCBjb25maWd1cmVkJykgfHwgbWVzc2FnZS5pbmNsdWRlcygnQVBJIGtleScpKSB7XG4gICAgICByZXR1cm4gc2VuZEludGVybmFsRXJyb3IocmVzLCAnQUkgZ2VuZXJhdGlvbiBpcyBub3QgY29uZmlndXJlZCBmb3IgdGhlIHJlcXVlc3RlZCBwcm92aWRlcicpO1xuICAgIH1cbiAgICBpZiAobWVzc2FnZS5pbmNsdWRlcygnbm90IGF2YWlsYWJsZSBmb3IgcHJvdmlkZXInKSkge1xuICAgICAgcmV0dXJuIHNlbmRCYWRSZXF1ZXN0KHJlcywgbWVzc2FnZSk7XG4gICAgfVxuICAgIHJldHVybiBzZW5kSW50ZXJuYWxFcnJvcihyZXMsIGZhbGxiYWNrTWVzc2FnZSwgeyBkZXRhaWxzOiBtZXNzYWdlIH0pO1xuICB9XG4gIHJlcy53cml0ZShgZGF0YTogJHtKU09OLnN0cmluZ2lmeSh7IHR5cGU6ICdlcnJvcicsIG1lc3NhZ2UgfSl9XFxuXFxuYCk7XG4gIHJlcy5lbmQoKTtcbn1cbiJdfQ==

package/lib/index.d.ts

@@ -0,0 +1,57 @@
+/**
+ * @module @pipeline-builder/api-core
+ *
+ * Core API utilities shared across all services.
+ *
+ * **Middleware**
+ * - requireAuth, optionalAuth, requireOrganization, requireAdmin — JWT authentication
+ * - isSystemOrg, isSystemAdmin — authorization helpers
+ *
+ * **Types**
+ * - ErrorCode, ErrorCodeStatus — standardized error code enum and status mapping
+ * - RequestIdentity — parsed JWT identity
+ * - ServiceConfig, RequestOptions, HttpResponse — HTTP client types
+ * - QuotaType, QuotaCheckResult — quota service types
+ * - PipelineType, ComputeType, AccessModifier — pipeline domain types
+ * - FeatureFlags, BillingPlan — feature and billing types
+ *
+ * **Utilities**
+ * - createLogger — Winston-based structured logger factory
+ * - sendSuccess, sendError, sendPaginated, sendBadRequest, sendInternalError — HTTP response helpers
+ * - getParam, getRequiredParam, getParams, getOrgId, getAuthHeader — request parameter extraction
+ * - parseQueryBoolean, parseQueryInt, parseQueryString — query string parsing
+ * - getIdentity, validateIdentity — identity extraction from requests
+ * - errorMessage — safe error-to-string conversion
+ *
+ * **Constants**
+ * - HTTP status codes, AI provider identifiers, time constants
+ *
+ * **Services**
+ * - InternalHttpClient, createSafeClient — internal service-to-service HTTP client
+ * - createQuotaService — quota enforcement client factory
+ * - CacheService — in-memory TTL cache
+ * - ComplianceClient — compliance service client
+ * - EntityEventEmitter — domain event pub/sub
+ *
+ * **Errors**
+ * - AppError, NotFoundError, ForbiddenError — typed HTTP error classes
+ *
+ * **Validation**
+ * - Zod-based request validation schemas and middleware
+ *
+ * **Routes**
+ * - Health check route factory
+ *
+ * **OpenAPI**
+ * - Schema registry and spec generation
+ */
+export * from './types';
+export * from './constants';
+export * from './utils';
+export * from './helpers';
+export * from './services';
+export * from './middleware';
+export * from './routes';
+export * from './errors';
+export * from './validation';
+export * from './openapi';

package/lib/index.js

@@ -0,0 +1,86 @@
+"use strict";
+// Copyright 2026 Pipeline Builder Contributors
+// SPDX-License-Identifier: Apache-2.0
+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 });
+/**
+ * @module @pipeline-builder/api-core
+ *
+ * Core API utilities shared across all services.
+ *
+ * **Middleware**
+ * - requireAuth, optionalAuth, requireOrganization, requireAdmin — JWT authentication
+ * - isSystemOrg, isSystemAdmin — authorization helpers
+ *
+ * **Types**
+ * - ErrorCode, ErrorCodeStatus — standardized error code enum and status mapping
+ * - RequestIdentity — parsed JWT identity
+ * - ServiceConfig, RequestOptions, HttpResponse — HTTP client types
+ * - QuotaType, QuotaCheckResult — quota service types
+ * - PipelineType, ComputeType, AccessModifier — pipeline domain types
+ * - FeatureFlags, BillingPlan — feature and billing types
+ *
+ * **Utilities**
+ * - createLogger — Winston-based structured logger factory
+ * - sendSuccess, sendError, sendPaginated, sendBadRequest, sendInternalError — HTTP response helpers
+ * - getParam, getRequiredParam, getParams, getOrgId, getAuthHeader — request parameter extraction
+ * - parseQueryBoolean, parseQueryInt, parseQueryString — query string parsing
+ * - getIdentity, validateIdentity — identity extraction from requests
+ * - errorMessage — safe error-to-string conversion
+ *
+ * **Constants**
+ * - HTTP status codes, AI provider identifiers, time constants
+ *
+ * **Services**
+ * - InternalHttpClient, createSafeClient — internal service-to-service HTTP client
+ * - createQuotaService — quota enforcement client factory
+ * - CacheService — in-memory TTL cache
+ * - ComplianceClient — compliance service client
+ * - EntityEventEmitter — domain event pub/sub
+ *
+ * **Errors**
+ * - AppError, NotFoundError, ForbiddenError — typed HTTP error classes
+ *
+ * **Validation**
+ * - Zod-based request validation schemas and middleware
+ *
+ * **Routes**
+ * - Health check route factory
+ *
+ * **OpenAPI**
+ * - Schema registry and spec generation
+ */
+// Types
+__exportStar(require("./types"), exports);
+// Constants
+__exportStar(require("./constants"), exports);
+// Utils
+__exportStar(require("./utils"), exports);
+// Helpers
+__exportStar(require("./helpers"), exports);
+// Services
+__exportStar(require("./services"), exports);
+// Middleware
+__exportStar(require("./middleware"), exports);
+// Routes
+__exportStar(require("./routes"), exports);
+// Errors
+__exportStar(require("./errors"), exports);
+// Validation
+__exportStar(require("./validation"), exports);
+// OpenAPI
+__exportStar(require("./openapi"), exports);
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9zcmMvaW5kZXgudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IjtBQUFBLCtDQUErQztBQUMvQyxzQ0FBc0M7Ozs7Ozs7Ozs7Ozs7Ozs7QUFFdEM7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7R0E4Q0c7QUFFSCxRQUFRO0FBQ1IsMENBQXdCO0FBRXhCLFlBQVk7QUFDWiw4Q0FBNEI7QUFFNUIsUUFBUTtBQUNSLDBDQUF3QjtBQUV4QixVQUFVO0FBQ1YsNENBQTBCO0FBRTFCLFdBQVc7QUFDWCw2Q0FBMkI7QUFFM0IsYUFBYTtBQUNiLCtDQUE2QjtBQUU3QixTQUFTO0FBQ1QsMkNBQXlCO0FBRXpCLFNBQVM7QUFDVCwyQ0FBeUI7QUFFekIsYUFBYTtBQUNiLCtDQUE2QjtBQUU3QixVQUFVO0FBQ1YsNENBQTBCIiwic291cmNlc0NvbnRlbnQiOlsiLy8gQ29weXJpZ2h0IDIwMjYgUGlwZWxpbmUgQnVpbGRlciBDb250cmlidXRvcnNcbi8vIFNQRFgtTGljZW5zZS1JZGVudGlmaWVyOiBBcGFjaGUtMi4wXG5cbi8qKlxuICogQG1vZHVsZSBAcGlwZWxpbmUtYnVpbGRlci9hcGktY29yZVxuICpcbiAqIENvcmUgQVBJIHV0aWxpdGllcyBzaGFyZWQgYWNyb3NzIGFsbCBzZXJ2aWNlcy5cbiAqXG4gKiAqKk1pZGRsZXdhcmUqKlxuICogLSByZXF1aXJlQXV0aCwgb3B0aW9uYWxBdXRoLCByZXF1aXJlT3JnYW5pemF0aW9uLCByZXF1aXJlQWRtaW4g4oCUIEpXVCBhdXRoZW50aWNhdGlvblxuICogLSBpc1N5c3RlbU9yZywgaXNTeXN0ZW1BZG1pbiDigJQgYXV0aG9yaXphdGlvbiBoZWxwZXJzXG4gKlxuICogKipUeXBlcyoqXG4gKiAtIEVycm9yQ29kZSwgRXJyb3JDb2RlU3RhdHVzIOKAlCBzdGFuZGFyZGl6ZWQgZXJyb3IgY29kZSBlbnVtIGFuZCBzdGF0dXMgbWFwcGluZ1xuICogLSBSZXF1ZXN0SWRlbnRpdHkg4oCUIHBhcnNlZCBKV1QgaWRlbnRpdHlcbiAqIC0gU2VydmljZUNvbmZpZywgUmVxdWVzdE9wdGlvbnMsIEh0dHBSZXNwb25zZSDigJQgSFRUUCBjbGllbnQgdHlwZXNcbiAqIC0gUXVvdGFUeXBlLCBRdW90YUNoZWNrUmVzdWx0IOKAlCBxdW90YSBzZXJ2aWNlIHR5cGVzXG4gKiAtIFBpcGVsaW5lVHlwZSwgQ29tcHV0ZVR5cGUsIEFjY2Vzc01vZGlmaWVyIOKAlCBwaXBlbGluZSBkb21haW4gdHlwZXNcbiAqIC0gRmVhdHVyZUZsYWdzLCBCaWxsaW5nUGxhbiDigJQgZmVhdHVyZSBhbmQgYmlsbGluZyB0eXBlc1xuICpcbiAqICoqVXRpbGl0aWVzKipcbiAqIC0gY3JlYXRlTG9nZ2VyIOKAlCBXaW5zdG9uLWJhc2VkIHN0cnVjdHVyZWQgbG9nZ2VyIGZhY3RvcnlcbiAqIC0gc2VuZFN1Y2Nlc3MsIHNlbmRFcnJvciwgc2VuZFBhZ2luYXRlZCwgc2VuZEJhZFJlcXVlc3QsIHNlbmRJbnRlcm5hbEVycm9yIOKAlCBIVFRQIHJlc3BvbnNlIGhlbHBlcnNcbiAqIC0gZ2V0UGFyYW0sIGdldFJlcXVpcmVkUGFyYW0sIGdldFBhcmFtcywgZ2V0T3JnSWQsIGdldEF1dGhIZWFkZXIg4oCUIHJlcXVlc3QgcGFyYW1ldGVyIGV4dHJhY3Rpb25cbiAqIC0gcGFyc2VRdWVyeUJvb2xlYW4sIHBhcnNlUXVlcnlJbnQsIHBhcnNlUXVlcnlTdHJpbmcg4oCUIHF1ZXJ5IHN0cmluZyBwYXJzaW5nXG4gKiAtIGdldElkZW50aXR5LCB2YWxpZGF0ZUlkZW50aXR5IOKAlCBpZGVudGl0eSBleHRyYWN0aW9uIGZyb20gcmVxdWVzdHNcbiAqIC0gZXJyb3JNZXNzYWdlIOKAlCBzYWZlIGVycm9yLXRvLXN0cmluZyBjb252ZXJzaW9uXG4gKlxuICogKipDb25zdGFudHMqKlxuICogLSBIVFRQIHN0YXR1cyBjb2RlcywgQUkgcHJvdmlkZXIgaWRlbnRpZmllcnMsIHRpbWUgY29uc3RhbnRzXG4gKlxuICogKipTZXJ2aWNlcyoqXG4gKiAtIEludGVybmFsSHR0cENsaWVudCwgY3JlYXRlU2FmZUNsaWVudCDigJQgaW50ZXJuYWwgc2VydmljZS10by1zZXJ2aWNlIEhUVFAgY2xpZW50XG4gKiAtIGNyZWF0ZVF1b3RhU2VydmljZSDigJQgcXVvdGEgZW5mb3JjZW1lbnQgY2xpZW50IGZhY3RvcnlcbiAqIC0gQ2FjaGVTZXJ2aWNlIOKAlCBpbi1tZW1vcnkgVFRMIGNhY2hlXG4gKiAtIENvbXBsaWFuY2VDbGllbnQg4oCUIGNvbXBsaWFuY2Ugc2VydmljZSBjbGllbnRcbiAqIC0gRW50aXR5RXZlbnRFbWl0dGVyIOKAlCBkb21haW4gZXZlbnQgcHViL3N1YlxuICpcbiAqICoqRXJyb3JzKipcbiAqIC0gQXBwRXJyb3IsIE5vdEZvdW5kRXJyb3IsIEZvcmJpZGRlbkVycm9yIOKAlCB0eXBlZCBIVFRQIGVycm9yIGNsYXNzZXNcbiAqXG4gKiAqKlZhbGlkYXRpb24qKlxuICogLSBab2QtYmFzZWQgcmVxdWVzdCB2YWxpZGF0aW9uIHNjaGVtYXMgYW5kIG1pZGRsZXdhcmVcbiAqXG4gKiAqKlJvdXRlcyoqXG4gKiAtIEhlYWx0aCBjaGVjayByb3V0ZSBmYWN0b3J5XG4gKlxuICogKipPcGVuQVBJKipcbiAqIC0gU2NoZW1hIHJlZ2lzdHJ5IGFuZCBzcGVjIGdlbmVyYXRpb25cbiAqL1xuXG4vLyBUeXBlc1xuZXhwb3J0ICogZnJvbSAnLi90eXBlcyc7XG5cbi8vIENvbnN0YW50c1xuZXhwb3J0ICogZnJvbSAnLi9jb25zdGFudHMnO1xuXG4vLyBVdGlsc1xuZXhwb3J0ICogZnJvbSAnLi91dGlscyc7XG5cbi8vIEhlbHBlcnNcbmV4cG9ydCAqIGZyb20gJy4vaGVscGVycyc7XG5cbi8vIFNlcnZpY2VzXG5leHBvcnQgKiBmcm9tICcuL3NlcnZpY2VzJztcblxuLy8gTWlkZGxld2FyZVxuZXhwb3J0ICogZnJvbSAnLi9taWRkbGV3YXJlJztcblxuLy8gUm91dGVzXG5leHBvcnQgKiBmcm9tICcuL3JvdXRlcyc7XG5cbi8vIEVycm9yc1xuZXhwb3J0ICogZnJvbSAnLi9lcnJvcnMnO1xuXG4vLyBWYWxpZGF0aW9uXG5leHBvcnQgKiBmcm9tICcuL3ZhbGlkYXRpb24nO1xuXG4vLyBPcGVuQVBJXG5leHBvcnQgKiBmcm9tICcuL29wZW5hcGknO1xuIl19

package/lib/middleware/auth.d.ts

@@ -0,0 +1,50 @@
+import { Request, Response, NextFunction } from 'express';
+export interface RequireAuthOptions {
+    /**
+     * Allow x-org-id/x-org-name headers to override the JWT's organization fields.
+     *
+     * **SECURITY WARNING:** When enabled, a caller can set `x-org-id` to ANY
+     * organization ID, effectively impersonating that org. This MUST only be
+     * used on routes that are:
+     *   1. Internal service-to-service routes (not exposed to end users)
+     *   2. Behind network isolation (container network, VPC, etc.)
+     *
+     * NEVER enable this on user-facing API routes. If unsure, leave it disabled.
+     */
+    allowOrgHeaderOverride?: boolean;
+}
+/** JWT auth middleware. Use directly or call with options. */
+export declare function requireAuth(req: Request, res: Response, next: NextFunction): void;
+export declare function requireAuth(options?: RequireAuthOptions): (req: Request, res: Response, next: NextFunction) => void;
+/** Requires organization membership. Use after requireAuth. */
+export declare function requireOrganization(req: Request, res: Response, next: NextFunction): void;
+/**
+ * Requires admin role. Use after requireAuth.
+ * Permits users whose per-org role is 'admin' or 'owner'.
+ */
+export declare function requireAdmin(req: Request, res: Response, next: NextFunction): void;
+/** Organization ID/name that identifies the system (super-admin) tenant. */
+export declare const SYSTEM_ORG_ID: string;
+/**
+ * Check if an orgId or orgName matches the system org.
+ * Use this instead of comparing directly against SYSTEM_ORG_ID,
+ * because the JWT orgId is a database ID (e.g. MongoDB ObjectId)
+ * while SYSTEM_ORG_ID is the well-known name "system".
+ */
+export declare function isSystemOrgId(orgId?: string, orgName?: string): boolean;
+export declare function isSystemOrg(req: Request): boolean;
+/**
+ * Check if the request is from a system admin.
+ * A system admin has per-org role 'admin' or 'owner' in the system organization.
+ */
+export declare function isSystemAdmin(req: Request): boolean;
+/** Requires system admin (admin role + system organization). */
+export declare function requireSystemAdmin(req: Request, res: Response, next: NextFunction): void;
+/**
+ * Require a specific feature flag. Use after requireAuth.
+ * Checks the `features` array in the JWT payload (set at token issuance).
+ * System org users always pass (all features enabled).
+ */
+export declare function requireFeature(feature: string): (req: Request, res: Response, next: NextFunction) => void;
+/** Only system admins can set access to 'public'; everyone else gets 'private'. */
+export declare function resolveAccessModifier(req: Request, requested: string | undefined): 'public' | 'private';