@alanszp/audit 4.0.2

package/.gitignore

@@ -0,0 +1,3 @@
+node_modules
+*.log
+dist

package/.npmignore

@@ -0,0 +1,3 @@
+node_modules
+src
+*.log

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 Alan Szpigiel
+
+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/audit.d.ts

@@ -0,0 +1,10 @@
+import { ILogger } from "@alanszp/logger";
+import { AuditBody } from ".";
+export declare class Audit {
+    logger: ILogger;
+    additions: Partial<AuditBody>;
+    constructor(logger: ILogger);
+    log(body: Partial<AuditBody>): void;
+    add(body: Partial<AuditBody>): void;
+    merge(body: Partial<AuditBody>): Partial<AuditBody>;
+}

package/dist/audit.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Audit = void 0;
+const logger_1 = require("@alanszp/logger");
+const lodash_1 = require("lodash");
+const _1 = require(".");
+const MissingAuditFieldsError_1 = require("./errors/MissingAuditFieldsError");
+class Audit {
+    constructor(logger) {
+        this.logger = logger;
+        this.additions = {};
+    }
+    log(body) {
+        const completeBody = this.merge(body);
+        const missingFields = (0, lodash_1.difference)(_1.REQUIRED_FIELDS, Object.keys(completeBody));
+        if (missingFields.length > 0) {
+            throw new MissingAuditFieldsError_1.MissingAuditFieldsError(missingFields);
+        }
+        const action = completeBody.action;
+        delete completeBody.action;
+        this.logger.info(action, Object.assign({ log_type: logger_1.LogType.AUDIT }, completeBody));
+    }
+    add(body) {
+        this.additions = this.merge(body);
+    }
+    merge(body) {
+        return (0, lodash_1.merge)(this.additions, body);
+    }
+}
+exports.Audit = Audit;
+//# sourceMappingURL=audit.js.map

package/dist/audit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.js","sourceRoot":"","sources":["../src/audit.ts"],"names":[],"mappings":";;;AAAA,4CAAmD;AACnD,mCAA2C;AAC3C,wBAA+C;AAC/C,8EAA2E;AAE3E,MAAa,KAAK;IAKhB,YAAY,MAAe;QACzB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,SAAS,GAAG,EAAE,CAAC;IACtB,CAAC;IAEM,GAAG,CAAC,IAAwB;QACjC,MAAM,YAAY,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAEtC,MAAM,aAAa,GAAG,IAAA,mBAAU,EAC9B,kBAAe,EACf,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC,CAC1B,CAAC;QAEF,IAAI,aAAa,CAAC,MAAM,GAAG,CAAC,EAAE;YAC5B,MAAM,IAAI,iDAAuB,CAAC,aAAa,CAAC,CAAC;SAClD;QAED,MAAM,MAAM,GAAG,YAAY,CAAC,MAAgB,CAAC;QAC7C,OAAO,YAAY,CAAC,MAAM,CAAC;QAE3B,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,kBAAI,QAAQ,EAAE,gBAAO,CAAC,KAAK,IAAK,YAAY,EAAG,CAAC;IACzE,CAAC;IAEM,GAAG,CAAC,IAAwB;QACjC,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACpC,CAAC;IAEM,KAAK,CAAC,IAAwB;QACnC,OAAO,IAAA,cAAK,EAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;IACrC,CAAC;CACF;AAnCD,sBAmCC"}

package/dist/errors/AuditError.d.ts

@@ -0,0 +1,3 @@
+import { BaseError } from "@alanszp/errors";
+export declare class AuditError extends BaseError {
+}

package/dist/errors/AuditError.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuditError = void 0;
+const errors_1 = require("@alanszp/errors");
+class AuditError extends errors_1.BaseError {
+}
+exports.AuditError = AuditError;
+//# sourceMappingURL=AuditError.js.map

package/dist/errors/AuditError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AuditError.js","sourceRoot":"","sources":["../../src/errors/AuditError.ts"],"names":[],"mappings":";;;AAAA,4CAA4C;AAE5C,MAAa,UAAW,SAAQ,kBAAS;CAAG;AAA5C,gCAA4C"}

package/dist/errors/MissingAuditFieldsError.d.ts

@@ -0,0 +1,9 @@
+import { RenderableContext, RenderableError } from "@alanszp/errors";
+import { AuditError } from "./AuditError";
+export declare class MissingAuditFieldsError extends AuditError implements RenderableError {
+    missingFields: string[];
+    constructor(missingFields: string[]);
+    code(): string;
+    renderMessage(): string;
+    context(): RenderableContext;
+}

package/dist/errors/MissingAuditFieldsError.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MissingAuditFieldsError = void 0;
+const AuditError_1 = require("./AuditError");
+class MissingAuditFieldsError extends AuditError_1.AuditError {
+    constructor(missingFields) {
+        super("MissingAuditFieldsError");
+        this.missingFields = missingFields;
+    }
+    code() {
+        return "missing_audit_fields_error";
+    }
+    renderMessage() {
+        return "Missing properties on audit log.";
+    }
+    context() {
+        return {
+            missingFields: this.missingFields,
+        };
+    }
+}
+exports.MissingAuditFieldsError = MissingAuditFieldsError;
+//# sourceMappingURL=MissingAuditFieldsError.js.map

package/dist/errors/MissingAuditFieldsError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MissingAuditFieldsError.js","sourceRoot":"","sources":["../../src/errors/MissingAuditFieldsError.ts"],"names":[],"mappings":";;;AACA,6CAA0C;AAE1C,MAAa,uBACX,SAAQ,uBAAU;IAKlB,YAAY,aAAuB;QACjC,KAAK,CAAC,yBAAyB,CAAC,CAAC;QACjC,IAAI,CAAC,aAAa,GAAG,aAAa,CAAC;IACrC,CAAC;IAED,IAAI;QACF,OAAO,4BAA4B,CAAC;IACtC,CAAC;IAED,aAAa;QACX,OAAO,kCAAkC,CAAC;IAC5C,CAAC;IAED,OAAO;QACL,OAAO;YACL,aAAa,EAAE,IAAI,CAAC,aAAa;SAClC,CAAC;IACJ,CAAC;CACF;AAxBD,0DAwBC"}

package/dist/errors/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./AuditError";
+export * from "./MissingAuditFieldsError";

package/dist/errors/index.js

@@ -0,0 +1,15 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    Object.defineProperty(o, k2, { enumerable: true, get: function() { return m[k]; } });
+}) : (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("./AuditError"), exports);
+__exportStar(require("./MissingAuditFieldsError"), exports);
+//# sourceMappingURL=index.js.map

package/dist/errors/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/errors/index.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,+CAA6B;AAC7B,4DAA0C"}

package/dist/factory.d.ts

@@ -0,0 +1,4 @@
+import { ILogger } from "@alanszp/logger";
+import { Audit } from "./audit";
+export declare function createAuditLogger(appName: string): Audit;
+export declare function createAuditLogger(logger: ILogger): Audit;

package/dist/factory.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAuditLogger = void 0;
+const logger_1 = require("@alanszp/logger");
+const audit_1 = require("./audit");
+function createAuditLogger(appNameOrLogger) {
+    const logger = typeof appNameOrLogger === "string"
+        ? (0, logger_1.createLogger)({
+            appName: appNameOrLogger,
+            console: { level: logger_1.LogLevel.INFO },
+        })
+        : appNameOrLogger;
+    return new audit_1.Audit(logger);
+}
+exports.createAuditLogger = createAuditLogger;
+//# sourceMappingURL=factory.js.map

package/dist/factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.js","sourceRoot":"","sources":["../src/factory.ts"],"names":[],"mappings":";;;AAAA,4CAAkE;AAClE,mCAAgC;AAIhC,SAAgB,iBAAiB,CAAC,eAAiC;IACjE,MAAM,MAAM,GACV,OAAO,eAAe,KAAK,QAAQ;QACjC,CAAC,CAAC,IAAA,qBAAY,EAAC;YACX,OAAO,EAAE,eAAe;YACxB,OAAO,EAAE,EAAE,KAAK,EAAE,iBAAQ,CAAC,IAAI,EAAE;SAClC,CAAC;QACJ,CAAC,CAAC,eAAe,CAAC;IAEtB,OAAO,IAAI,aAAK,CAAC,MAAM,CAAC,CAAC;AAC3B,CAAC;AAVD,8CAUC"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./factory";
+export * from "./audit";
+export * from "./interfaces";
+export * from "./errors";

package/dist/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    Object.defineProperty(o, k2, { enumerable: true, get: function() { return m[k]; } });
+}) : (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("./factory"), exports);
+__exportStar(require("./audit"), exports);
+__exportStar(require("./interfaces"), exports);
+__exportStar(require("./errors"), exports);
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,4CAA0B;AAC1B,0CAAwB;AACxB,+CAA6B;AAC7B,2CAAyB"}

package/dist/interfaces.d.ts

@@ -0,0 +1,18 @@
+export declare enum CommonMetadataKeys {
+    EMPLOYEE_ID = "employee_id",
+    EMPLOYEE_IDS = "employee_ids",
+    CHANGES = "changes"
+}
+export interface Metadata {
+    [key: string]: unknown;
+}
+export declare const REQUIRED_FIELDS: string[];
+export interface AuditBody {
+    actorRef: string;
+    orgRef: string;
+    ip: string | string[];
+    action: string;
+    succeed: boolean;
+    targetRef?: string;
+    metadata?: Metadata;
+}

package/dist/interfaces.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REQUIRED_FIELDS = exports.CommonMetadataKeys = void 0;
+var CommonMetadataKeys;
+(function (CommonMetadataKeys) {
+    CommonMetadataKeys["EMPLOYEE_ID"] = "employee_id";
+    CommonMetadataKeys["EMPLOYEE_IDS"] = "employee_ids";
+    CommonMetadataKeys["CHANGES"] = "changes";
+})(CommonMetadataKeys = exports.CommonMetadataKeys || (exports.CommonMetadataKeys = {}));
+exports.REQUIRED_FIELDS = [
+    "actorRef",
+    "orgRef",
+    "ip",
+    "action",
+    "succeed",
+];
+// When will be set by logger (log time)
+// Where will be set by logger (host name)
+// Articles that we based to create this:
+// https://workos.com/blog/the-developers-guide-to-audit-logs-siem
+// https://www.strongdm.com/blog/audit-log-review-management
+//# sourceMappingURL=interfaces.js.map

package/dist/interfaces.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interfaces.js","sourceRoot":"","sources":["../src/interfaces.ts"],"names":[],"mappings":";;;AAAA,IAAY,kBAIX;AAJD,WAAY,kBAAkB;IAC5B,iDAA2B,CAAA;IAC3B,mDAA6B,CAAA;IAC7B,yCAAmB,CAAA;AACrB,CAAC,EAJW,kBAAkB,GAAlB,0BAAkB,KAAlB,0BAAkB,QAI7B;AAMY,QAAA,eAAe,GAAG;IAC7B,UAAU;IACV,QAAQ;IACR,IAAI;IACJ,QAAQ;IACR,SAAS;CACV,CAAC;AAiBF,wCAAwC;AACxC,0CAA0C;AAE1C,yCAAyC;AACzC,kEAAkE;AAClE,4DAA4D"}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@alanszp/audit",
+  "version": "4.0.2",
+  "description": "Alan's audit util.",
+  "main": "dist/index.js",
+  "typings": "dist/index.d.ts",
+  "license": "MIT",
+  "files": [
+    "**/*"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "compile": "rm -rf ./dist && tsc --declaration",
+    "compile-watch": "tsc -w",
+    "build": "yarn run compile",
+    "prepack": "yarn run build"
+  },
+  "dependencies": {
+    "@alanszp/errors": "^4.0.0",
+    "@alanszp/logger": "^4.0.2",
+    "lodash": "^4.17.21"
+  },
+  "gitHead": "c983be912daf7999c18052e7bcef490f3df9f863"
+}

package/src/audit.ts

@@ -0,0 +1,41 @@
+import { ILogger, LogType } from "@alanszp/logger";
+import { difference, merge } from "lodash";
+import { AuditBody, REQUIRED_FIELDS } from ".";
+import { MissingAuditFieldsError } from "./errors/MissingAuditFieldsError";
+
+export class Audit {
+  public logger: ILogger;
+
+  public additions: Partial<AuditBody>;
+
+  constructor(logger: ILogger) {
+    this.logger = logger;
+    this.additions = {};
+  }
+
+  public log(body: Partial<AuditBody>): void {
+    const completeBody = this.merge(body);
+
+    const missingFields = difference(
+      REQUIRED_FIELDS,
+      Object.keys(completeBody)
+    );
+
+    if (missingFields.length > 0) {
+      throw new MissingAuditFieldsError(missingFields);
+    }
+
+    const action = completeBody.action as string;
+    delete completeBody.action;
+
+    this.logger.info(action, { log_type: LogType.AUDIT, ...completeBody });
+  }
+
+  public add(body: Partial<AuditBody>): void {
+    this.additions = this.merge(body);
+  }
+
+  public merge(body: Partial<AuditBody>): Partial<AuditBody> {
+    return merge(this.additions, body);
+  }
+}

package/src/errors/AuditError.ts

@@ -0,0 +1,3 @@
+import { BaseError } from "@alanszp/errors";
+
+export class AuditError extends BaseError {}

package/src/errors/MissingAuditFieldsError.ts

@@ -0,0 +1,28 @@
+import { RenderableContext, RenderableError } from "@alanszp/errors";
+import { AuditError } from "./AuditError";
+
+export class MissingAuditFieldsError
+  extends AuditError
+  implements RenderableError
+{
+  public missingFields: string[];
+
+  constructor(missingFields: string[]) {
+    super("MissingAuditFieldsError");
+    this.missingFields = missingFields;
+  }
+
+  code(): string {
+    return "missing_audit_fields_error";
+  }
+
+  renderMessage(): string {
+    return "Missing properties on audit log.";
+  }
+
+  context(): RenderableContext {
+    return {
+      missingFields: this.missingFields,
+    };
+  }
+}

package/src/errors/index.ts

@@ -0,0 +1,2 @@
+export * from "./AuditError";
+export * from "./MissingAuditFieldsError";

package/src/factory.ts

@@ -0,0 +1,16 @@
+import { createLogger, ILogger, LogLevel } from "@alanszp/logger";
+import { Audit } from "./audit";
+
+export function createAuditLogger(appName: string): Audit;
+export function createAuditLogger(logger: ILogger): Audit;
+export function createAuditLogger(appNameOrLogger: string | ILogger): Audit {
+  const logger =
+    typeof appNameOrLogger === "string"
+      ? createLogger({
+          appName: appNameOrLogger,
+          console: { level: LogLevel.INFO },
+        })
+      : appNameOrLogger;
+
+  return new Audit(logger);
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from "./factory";
+export * from "./audit";
+export * from "./interfaces";
+export * from "./errors";

package/src/interfaces.ts

@@ -0,0 +1,39 @@
+export enum CommonMetadataKeys {
+  EMPLOYEE_ID = "employee_id",
+  EMPLOYEE_IDS = "employee_ids",
+  CHANGES = "changes",
+}
+
+export interface Metadata {
+  [key: string]: unknown;
+}
+
+export const REQUIRED_FIELDS = [
+  "actorRef",
+  "orgRef",
+  "ip",
+  "action",
+  "succeed",
+];
+
+export interface AuditBody {
+  // Who
+  actorRef: string;
+  orgRef: string;
+
+  // Where (it can be an array since the request can jump between nodes, and http keeps record of their IPs)
+  ip: string | string[];
+
+  // What
+  action: string;
+  succeed: boolean;
+  targetRef?: string;
+  metadata?: Metadata;
+}
+
+// When will be set by logger (log time)
+// Where will be set by logger (host name)
+
+// Articles that we based to create this:
+// https://workos.com/blog/the-developers-guide-to-audit-logs-siem
+// https://www.strongdm.com/blog/audit-log-review-management

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist",
+    "module": "commonjs",
+    "target": "es6",
+    "types": ["node"],
+    "esModuleInterop": true,
+    "sourceMap": true,
+
+    "alwaysStrict": true,
+    "strictNullChecks": true
+  },
+  "exclude": ["node_modules"]
+}