@scryan7371/sdr-security 0.1.1

package/dist/app/client.d.ts

@@ -0,0 +1,52 @@
+import type { AuthResponse, DebugCodeResponse, DebugTokenResponse, RoleCatalogResponse, RegisterResponse, UserRolesResponse } from "../api/contracts";
+type FetchLike = typeof fetch;
+export type SecurityClientOptions = {
+    baseUrl: string;
+    getAccessToken: () => string | null;
+    fetchImpl?: FetchLike;
+};
+export declare const createSecurityClient: (options: SecurityClientOptions) => {
+    register: (payload: {
+        email: string;
+        password: string;
+        firstName?: string;
+        lastName?: string;
+    }) => Promise<RegisterResponse>;
+    login: (payload: {
+        email: string;
+        password: string;
+    }) => Promise<AuthResponse>;
+    loginWithGoogle: (payload: {
+        idToken: string;
+    }) => Promise<AuthResponse>;
+    refresh: (payload: {
+        refreshToken: string;
+    }) => Promise<AuthResponse>;
+    revoke: (payload: {
+        refreshToken: string;
+    }) => Promise<{
+        success: true;
+    }>;
+    logout: (payload: {
+        refreshToken?: string;
+    }) => Promise<{
+        success: true;
+    }>;
+    requestEmailVerification: () => Promise<DebugTokenResponse>;
+    verifyEmail: (token: string) => Promise<{
+        success: true;
+    }>;
+    requestPhoneVerification: () => Promise<DebugCodeResponse>;
+    verifyPhone: (code: string) => Promise<{
+        success: true;
+    }>;
+    getMyRoles: () => Promise<UserRolesResponse>;
+    listRoles: () => Promise<RoleCatalogResponse>;
+    createRole: (payload: {
+        role: string;
+        description?: string | null;
+    }) => Promise<RoleCatalogResponse>;
+    getUserRoles: (userId: string) => Promise<UserRolesResponse>;
+    setUserRoles: (userId: string, roles: string[]) => Promise<UserRolesResponse>;
+};
+export {};

package/dist/app/client.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSecurityClient = void 0;
+const createSecurityClient = (options) => {
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const request = async (path, init) => {
+        const token = options.getAccessToken();
+        const headers = {
+            "Content-Type": "application/json",
+            ...(init?.headers ? init.headers : {}),
+        };
+        if (token) {
+            headers.Authorization = `Bearer ${token}`;
+        }
+        const response = await fetchImpl(`${options.baseUrl}${path}`, {
+            ...init,
+            headers,
+        });
+        const text = await response.text();
+        const body = text ? JSON.parse(text) : {};
+        if (!response.ok) {
+            const message = typeof body?.message === "string"
+                ? body.message
+                : `Request failed: ${response.status}`;
+            throw new Error(message);
+        }
+        return body;
+    };
+    return {
+        register: (payload) => request("/auth/register", {
+            method: "POST",
+            body: JSON.stringify(payload),
+        }),
+        login: (payload) => request("/auth/login", {
+            method: "POST",
+            body: JSON.stringify(payload),
+        }),
+        loginWithGoogle: (payload) => request("/auth/login/google", {
+            method: "POST",
+            body: JSON.stringify(payload),
+        }),
+        refresh: (payload) => request("/auth/refresh", {
+            method: "POST",
+            body: JSON.stringify(payload),
+        }),
+        revoke: (payload) => request("/auth/revoke", {
+            method: "POST",
+            body: JSON.stringify(payload),
+        }),
+        logout: (payload) => request("/auth/logout", {
+            method: "POST",
+            body: JSON.stringify(payload),
+        }),
+        requestEmailVerification: () => request("/auth/request-email-verification", {
+            method: "POST",
+        }),
+        verifyEmail: (token) => request(`/auth/verify-email?token=${token}`),
+        requestPhoneVerification: () => request("/auth/request-phone-verification", {
+            method: "POST",
+        }),
+        verifyPhone: (code) => request("/auth/verify-phone", {
+            method: "POST",
+            body: JSON.stringify({ code }),
+        }),
+        getMyRoles: () => request("/auth/me/roles"),
+        listRoles: () => request("/admin/roles"),
+        createRole: (payload) => request("/admin/roles", {
+            method: "POST",
+            body: JSON.stringify(payload),
+        }),
+        getUserRoles: (userId) => request(`/admin/users/${userId}/roles`),
+        setUserRoles: (userId, roles) => request(`/admin/users/${userId}/roles`, {
+            method: "PUT",
+            body: JSON.stringify({ roles }),
+        }),
+    };
+};
+exports.createSecurityClient = createSecurityClient;

package/dist/app/index.d.ts

@@ -0,0 +1 @@
+export * from "./client";

package/dist/app/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;
+    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("./client"), exports);

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * as api from "./api";
+export * as app from "./app";

package/dist/index.js

@@ -0,0 +1,38 @@
+"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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.app = exports.api = void 0;
+exports.api = __importStar(require("./api"));
+exports.app = __importStar(require("./app"));

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@scryan7371/sdr-security",
+  "version": "0.1.1",
+  "description": "Reusable auth/security capability for API and app clients.",
+  "main": "dist/index.js",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "types": "dist/index.d.ts",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run clean && npm run build",
+    "test": "vitest run",
+    "test:cov": "vitest run --coverage"
+  },
+  "dependencies": {
+    "@babel/runtime": "7.28.6"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.3",
+    "@vitest/coverage-v8": "^4.0.18",
+    "typescript": "5.9.3",
+    "vitest": "4.0.18"
+  }
+}

package/src/api/access-policy.test.ts

@@ -0,0 +1,103 @@
+import { describe, expect, it } from "vitest";
+import {
+  accessBlockReasonToMessage,
+  getAuthBlockReason,
+} from "./access-policy";
+
+const baseUser = {
+  isActive: true,
+  emailVerifiedAt: new Date(),
+  phoneVerifiedAt: null,
+  adminApprovedAt: new Date(),
+};
+
+describe("getAuthBlockReason", () => {
+  it("returns null for user meeting default requirements", () => {
+    expect(getAuthBlockReason(baseUser)).toBeNull();
+  });
+
+  it("blocks deactivated users first", () => {
+    expect(
+      getAuthBlockReason({
+        ...baseUser,
+        isActive: false,
+        emailVerifiedAt: null,
+        adminApprovedAt: null,
+      }),
+    ).toBe("ACCOUNT_DEACTIVATED");
+  });
+
+  it("blocks when email verification is required and missing", () => {
+    expect(
+      getAuthBlockReason({
+        ...baseUser,
+        emailVerifiedAt: null,
+      }),
+    ).toBe("EMAIL_VERIFICATION_REQUIRED");
+  });
+
+  it("does not block missing phone when phone verification is disabled", () => {
+    expect(
+      getAuthBlockReason({
+        ...baseUser,
+        phoneVerifiedAt: null,
+      }),
+    ).toBeNull();
+  });
+
+  it("blocks missing phone when phone verification is enabled", () => {
+    expect(
+      getAuthBlockReason(
+        {
+          ...baseUser,
+          phoneVerifiedAt: null,
+        },
+        { requirePhoneVerification: true },
+      ),
+    ).toBe("PHONE_VERIFICATION_REQUIRED");
+  });
+
+  it("blocks when admin approval is required and missing", () => {
+    expect(
+      getAuthBlockReason({
+        ...baseUser,
+        adminApprovedAt: null,
+      }),
+    ).toBe("ADMIN_APPROVAL_REQUIRED");
+  });
+
+  it("respects disabled flags", () => {
+    expect(
+      getAuthBlockReason(
+        {
+          ...baseUser,
+          isActive: false,
+          emailVerifiedAt: null,
+          adminApprovedAt: null,
+        },
+        {
+          requireActive: false,
+          requireEmailVerification: false,
+          requireAdminApproval: false,
+        },
+      ),
+    ).toBeNull();
+  });
+});
+
+describe("accessBlockReasonToMessage", () => {
+  it("maps each reason to expected message", () => {
+    expect(accessBlockReasonToMessage("EMAIL_VERIFICATION_REQUIRED")).toBe(
+      "Email verification required",
+    );
+    expect(accessBlockReasonToMessage("PHONE_VERIFICATION_REQUIRED")).toBe(
+      "Phone verification required",
+    );
+    expect(accessBlockReasonToMessage("ADMIN_APPROVAL_REQUIRED")).toBe(
+      "Admin approval required",
+    );
+    expect(accessBlockReasonToMessage("ACCOUNT_DEACTIVATED")).toBe(
+      "Account deactivated",
+    );
+  });
+});

package/src/api/access-policy.ts

@@ -0,0 +1,68 @@
+export type AccessPolicyUser = {
+  isActive: boolean;
+  emailVerifiedAt: string | Date | null;
+  phoneVerifiedAt?: string | Date | null;
+  adminApprovedAt: string | Date | null;
+};
+
+export type AccessPolicyOptions = {
+  requireEmailVerification?: boolean;
+  requirePhoneVerification?: boolean;
+  requireAdminApproval?: boolean;
+  requireActive?: boolean;
+};
+
+export type AccessBlockReason =
+  | "EMAIL_VERIFICATION_REQUIRED"
+  | "PHONE_VERIFICATION_REQUIRED"
+  | "ADMIN_APPROVAL_REQUIRED"
+  | "ACCOUNT_DEACTIVATED";
+
+const DEFAULT_OPTIONS: Required<AccessPolicyOptions> = {
+  requireEmailVerification: true,
+  requirePhoneVerification: false,
+  requireAdminApproval: true,
+  requireActive: true,
+};
+
+export const getAuthBlockReason = (
+  user: AccessPolicyUser,
+  options: AccessPolicyOptions = {},
+): AccessBlockReason | null => {
+  const effective = { ...DEFAULT_OPTIONS, ...options };
+
+  if (effective.requireActive && !user.isActive) {
+    return "ACCOUNT_DEACTIVATED";
+  }
+
+  if (effective.requireEmailVerification && !user.emailVerifiedAt) {
+    return "EMAIL_VERIFICATION_REQUIRED";
+  }
+
+  if (effective.requirePhoneVerification && !user.phoneVerifiedAt) {
+    return "PHONE_VERIFICATION_REQUIRED";
+  }
+
+  if (effective.requireAdminApproval && !user.adminApprovedAt) {
+    return "ADMIN_APPROVAL_REQUIRED";
+  }
+
+  return null;
+};
+
+export const accessBlockReasonToMessage = (
+  reason: AccessBlockReason,
+): string => {
+  switch (reason) {
+    case "EMAIL_VERIFICATION_REQUIRED":
+      return "Email verification required";
+    case "PHONE_VERIFICATION_REQUIRED":
+      return "Phone verification required";
+    case "ADMIN_APPROVAL_REQUIRED":
+      return "Admin approval required";
+    case "ACCOUNT_DEACTIVATED":
+      return "Account deactivated";
+    default:
+      return "Unauthorized";
+  }
+};

package/src/api/contracts.ts

@@ -0,0 +1,47 @@
+export const ADMIN_ROLE = "ADMIN";
+export type UserRole = string;
+
+export type SafeUser = {
+  id: string;
+  email: string;
+  firstName: string | null;
+  lastName: string | null;
+  phone: string | null;
+  roles: UserRole[];
+  emailVerifiedAt: string | Date | null;
+  phoneVerifiedAt: string | Date | null;
+  adminApprovedAt: string | Date | null;
+  isActive: boolean;
+};
+
+export type UserRolesResponse = {
+  userId: string;
+  roles: UserRole[];
+};
+
+export type RoleDefinition = {
+  role: UserRole;
+  description: string | null;
+  isSystem: boolean;
+};
+
+export type RoleCatalogResponse = {
+  roles: RoleDefinition[];
+};
+
+export type AuthResponse = {
+  accessToken: string;
+  accessTokenExpiresIn: string;
+  refreshToken: string;
+  refreshTokenExpiresAt: string | Date;
+  user: SafeUser;
+};
+
+export type RegisterResponse = {
+  success: true;
+  user: SafeUser;
+  debugToken?: string;
+};
+
+export type DebugTokenResponse = { success: true; debugToken?: string };
+export type DebugCodeResponse = { success: true; debugCode?: string };

package/src/api/index.ts

@@ -0,0 +1,5 @@
+export * from "./contracts";
+export * from "./migrations";
+export * from "./access-policy";
+export * from "./validation";
+export * from "./roles";

package/src/api/migrations/1700000000001-add-refresh-tokens.ts

@@ -0,0 +1,47 @@
+export class AddRefreshTokens1700000000001 {
+  name = "AddRefreshTokens1700000000001";
+
+  async up(queryRunner: {
+    query: (sql: string) => Promise<unknown>;
+  }): Promise<void> {
+    const userTableRef = getUserTableReference();
+
+    await queryRunner.query(`
+      CREATE TABLE "refresh_token" (
+        "id" varchar PRIMARY KEY NOT NULL,
+        "token_hash" varchar NOT NULL,
+        "expires_at" timestamptz NOT NULL,
+        "revoked_at" timestamptz,
+        "userId" varchar,
+        "created_at" timestamptz NOT NULL DEFAULT (CURRENT_TIMESTAMP),
+        CONSTRAINT "FK_refresh_token_user" FOREIGN KEY ("userId") REFERENCES ${userTableRef} ("id") ON DELETE CASCADE ON UPDATE NO ACTION
+      )
+    `);
+    await queryRunner.query(
+      `CREATE INDEX "IDX_refresh_token_user" ON "refresh_token" ("userId")`,
+    );
+  }
+
+  async down(queryRunner: {
+    query: (sql: string) => Promise<unknown>;
+  }): Promise<void> {
+    await queryRunner.query(`DROP INDEX "IDX_refresh_token_user"`);
+    await queryRunner.query(`DROP TABLE "refresh_token"`);
+  }
+}
+
+const getUserTableReference = () => {
+  const table = getSafeIdentifier(process.env.USER_TABLE, "app_user");
+  const schema = process.env.USER_TABLE_SCHEMA
+    ? getSafeIdentifier(process.env.USER_TABLE_SCHEMA, "")
+    : "";
+  return schema ? `"${schema}"."${table}"` : `"${table}"`;
+};
+
+const getSafeIdentifier = (value: string | undefined, fallback: string) => {
+  const resolved = value?.trim() || fallback;
+  if (!resolved || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(resolved)) {
+    throw new Error(`Invalid SQL identifier: ${resolved}`);
+  }
+  return resolved;
+};

package/src/api/migrations/1739490000000-add-google-subject-to-user.ts

@@ -0,0 +1,12 @@
+export class AddGoogleSubjectToUser1739490000000 {
+  name = "AddGoogleSubjectToUser1739490000000";
+
+  // Legacy migration retained for backward compatibility with existing migration history.
+  async up(): Promise<void> {
+    return;
+  }
+
+  async down(): Promise<void> {
+    return;
+  }
+}

package/src/api/migrations/1739500000000-create-security-identity.ts

@@ -0,0 +1,95 @@
+export class CreateSecurityIdentity1739500000000 {
+  name = "CreateSecurityIdentity1739500000000";
+
+  async up(queryRunner: {
+    query: (sql: string, params?: unknown[]) => Promise<unknown>;
+  }): Promise<void> {
+    const userTable = getSafeIdentifier(process.env.USER_TABLE, "app_user");
+    const userSchema = getSafeIdentifier(
+      process.env.USER_TABLE_SCHEMA,
+      "public",
+    );
+    const userTableRef = `"${userSchema}"."${userTable}"`;
+
+    await queryRunner.query(`CREATE EXTENSION IF NOT EXISTS "uuid-ossp"`);
+
+    await queryRunner.query(`
+      CREATE TABLE IF NOT EXISTS "security_identity" (
+        "id" uuid PRIMARY KEY NOT NULL DEFAULT uuid_generate_v4(),
+        "user_id" varchar NOT NULL,
+        "provider" varchar NOT NULL,
+        "provider_subject" varchar NOT NULL,
+        "created_at" timestamptz NOT NULL DEFAULT now(),
+        "updated_at" timestamptz NOT NULL DEFAULT now(),
+        CONSTRAINT "FK_security_identity_user_id" FOREIGN KEY ("user_id") REFERENCES ${userTableRef} ("id") ON DELETE CASCADE
+      )
+    `);
+
+    await queryRunner.query(
+      `CREATE UNIQUE INDEX IF NOT EXISTS "IDX_security_identity_provider_subject" ON "security_identity" ("provider", "provider_subject")`,
+    );
+    await queryRunner.query(
+      `CREATE UNIQUE INDEX IF NOT EXISTS "IDX_security_identity_user_provider" ON "security_identity" ("user_id", "provider")`,
+    );
+
+    const hasGoogleSubjectColumn = (await queryRunner.query(
+      `
+        SELECT 1
+        FROM information_schema.columns
+        WHERE table_schema = $1
+          AND table_name = $2
+          AND column_name = 'google_subject'
+        LIMIT 1
+      `,
+      [userSchema, userTable],
+    )) as Array<{ "?column?": number }>;
+
+    if (hasGoogleSubjectColumn.length > 0) {
+      await queryRunner.query(`
+        INSERT INTO "security_identity" (
+          "user_id",
+          "provider",
+          "provider_subject",
+          "created_at",
+          "updated_at"
+        )
+        SELECT
+          "id",
+          'google',
+          "google_subject",
+          now(),
+          now()
+        FROM ${userTableRef}
+        WHERE "google_subject" IS NOT NULL
+        ON CONFLICT ("provider", "provider_subject") DO NOTHING
+      `);
+
+      await queryRunner.query(
+        `DROP INDEX IF EXISTS "IDX_app_user_google_subject"`,
+      );
+      await queryRunner.query(
+        `ALTER TABLE ${userTableRef} DROP COLUMN IF EXISTS "google_subject"`,
+      );
+    }
+  }
+
+  async down(queryRunner: {
+    query: (sql: string) => Promise<unknown>;
+  }): Promise<void> {
+    await queryRunner.query(
+      `DROP INDEX IF EXISTS "IDX_security_identity_user_provider"`,
+    );
+    await queryRunner.query(
+      `DROP INDEX IF EXISTS "IDX_security_identity_provider_subject"`,
+    );
+    await queryRunner.query(`DROP TABLE IF EXISTS "security_identity"`);
+  }
+}
+
+const getSafeIdentifier = (value: string | undefined, fallback: string) => {
+  const resolved = value?.trim() || fallback;
+  if (!resolved || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(resolved)) {
+    throw new Error(`Invalid SQL identifier: ${resolved}`);
+  }
+  return resolved;
+};