@wopr-network/platform-core 0.1.0

package/biome.json

@@ -0,0 +1,61 @@
+{
+  "vcs": {
+    "enabled": true,
+    "clientKind": "git",
+    "useIgnoreFile": true
+  },
+  "files": {
+    "includes": [
+      "src/**/*.ts"
+    ]
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2,
+    "lineWidth": 120
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true,
+      "correctness": {
+        "noUnusedVariables": "error",
+        "noUnusedImports": "error"
+      },
+      "suspicious": {
+        "noExplicitAny": "error",
+        "noConsole": {
+          "level": "error",
+          "options": {
+            "allow": [
+              "assert",
+              "error",
+              "info",
+              "warn"
+            ]
+          }
+        }
+      },
+      "style": {
+        "noNonNullAssertion": "error",
+        "useConst": "error"
+      }
+    }
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "double",
+      "semicolons": "always",
+      "trailingCommas": "all"
+    }
+  },
+  "assist": {
+    "enabled": true,
+    "actions": {
+      "source": {
+        "organizeImports": "on"
+      }
+    }
+  }
+}

package/dist/admin/admin-audit-log-repository.d.ts

@@ -0,0 +1,33 @@
+import type { PlatformDb } from "../db/index.js";
+import type { AdminAuditLogRow, AuditFilters } from "./audit-log.js";
+/** Repository interface for admin audit log operations. */
+export interface IAdminAuditLogRepository {
+    /** Insert a new admin audit entry. */
+    insert(row: AdminAuditLogRow): Promise<void>;
+    /** Query entries with filters. Returns matching entries and total count. */
+    query(filters: AuditFilters): Promise<{
+        entries: AdminAuditLogRow[];
+        total: number;
+    }>;
+    /** Query all entries matching filters (no pagination). For CSV export. */
+    queryAll(filters: Omit<AuditFilters, "limit" | "offset">): Promise<AdminAuditLogRow[]>;
+    /** Count entries grouped by action. */
+    countByAction(filters: {
+        from?: number;
+        to?: number;
+    }): Promise<Record<string, number>>;
+}
+export declare class DrizzleAdminAuditLogRepository implements IAdminAuditLogRepository {
+    private readonly db;
+    constructor(db: PlatformDb);
+    insert(row: AdminAuditLogRow): Promise<void>;
+    query(filters: AuditFilters): Promise<{
+        entries: AdminAuditLogRow[];
+        total: number;
+    }>;
+    queryAll(filters: Omit<AuditFilters, "limit" | "offset">): Promise<AdminAuditLogRow[]>;
+    countByAction(filters: {
+        from?: number;
+        to?: number;
+    }): Promise<Record<string, number>>;
+}

package/dist/admin/admin-audit-log-repository.js

@@ -0,0 +1,102 @@
+import { and, count, desc, eq, gte, lte } from "drizzle-orm";
+import { adminAuditLog } from "../db/schema/index.js";
+const MAX_LIMIT = 250;
+const DEFAULT_LIMIT = 50;
+/** Build Drizzle WHERE conditions from filters. */
+function buildConditions(filters) {
+    const conditions = [];
+    if (filters.admin) {
+        conditions.push(eq(adminAuditLog.adminUser, filters.admin));
+    }
+    if (filters.action) {
+        conditions.push(eq(adminAuditLog.action, filters.action));
+    }
+    if (filters.category) {
+        conditions.push(eq(adminAuditLog.category, filters.category));
+    }
+    if (filters.tenant) {
+        conditions.push(eq(adminAuditLog.targetTenant, filters.tenant));
+    }
+    if (filters.from != null) {
+        conditions.push(gte(adminAuditLog.createdAt, filters.from));
+    }
+    if (filters.to != null) {
+        conditions.push(lte(adminAuditLog.createdAt, filters.to));
+    }
+    return conditions.length > 0 ? and(...conditions) : undefined;
+}
+/** Map a Drizzle row to a snake_case AdminAuditLogRow. */
+function toRow(r) {
+    return {
+        id: r.id,
+        admin_user: r.adminUser,
+        action: r.action,
+        category: r.category,
+        target_tenant: r.targetTenant,
+        target_user: r.targetUser,
+        details: r.details,
+        ip_address: r.ipAddress,
+        user_agent: r.userAgent,
+        created_at: r.createdAt,
+        outcome: r.outcome ?? null,
+    };
+}
+export class DrizzleAdminAuditLogRepository {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    async insert(row) {
+        await this.db.insert(adminAuditLog).values({
+            id: row.id,
+            adminUser: row.admin_user,
+            action: row.action,
+            category: row.category,
+            targetTenant: row.target_tenant,
+            targetUser: row.target_user,
+            details: row.details,
+            ipAddress: row.ip_address,
+            userAgent: row.user_agent,
+            createdAt: row.created_at,
+            outcome: row.outcome,
+        });
+    }
+    async query(filters) {
+        const where = buildConditions(filters);
+        const countResult = await this.db.select({ count: count() }).from(adminAuditLog).where(where);
+        const total = countResult[0]?.count ?? 0;
+        const limit = Math.min(Math.max(1, filters.limit ?? DEFAULT_LIMIT), MAX_LIMIT);
+        const offset = Math.max(0, filters.offset ?? 0);
+        const rows = await this.db
+            .select()
+            .from(adminAuditLog)
+            .where(where)
+            .orderBy(desc(adminAuditLog.createdAt))
+            .limit(limit)
+            .offset(offset);
+        return { entries: rows.map(toRow), total };
+    }
+    async queryAll(filters) {
+        const where = buildConditions(filters);
+        const rows = await this.db.select().from(adminAuditLog).where(where).orderBy(desc(adminAuditLog.createdAt));
+        return rows.map(toRow);
+    }
+    async countByAction(filters) {
+        const conditions = [];
+        if (filters.from != null)
+            conditions.push(gte(adminAuditLog.createdAt, filters.from));
+        if (filters.to != null)
+            conditions.push(lte(adminAuditLog.createdAt, filters.to));
+        const where = conditions.length > 0 ? and(...conditions) : undefined;
+        const rows = await this.db
+            .select({ action: adminAuditLog.action, count: count() })
+            .from(adminAuditLog)
+            .where(where)
+            .groupBy(adminAuditLog.action);
+        const result = {};
+        for (const row of rows) {
+            result[row.action] = row.count;
+        }
+        return result;
+    }
+}

package/dist/admin/audit-log.d.ts

@@ -0,0 +1,49 @@
+import type { IAdminAuditLogRepository } from "./admin-audit-log-repository.js";
+export type AuditCategory = "account" | "credits" | "roles" | "config" | "support" | "bulk" | "infrastructure";
+export interface AuditEntry {
+    adminUser: string;
+    action: string;
+    category: AuditCategory;
+    targetTenant?: string;
+    targetUser?: string;
+    details: Record<string, unknown>;
+    ipAddress?: string;
+    userAgent?: string;
+    outcome?: "success" | "failure";
+}
+export interface AdminAuditLogRow {
+    id: string;
+    admin_user: string;
+    action: string;
+    category: string;
+    target_tenant: string | null;
+    target_user: string | null;
+    details: string;
+    ip_address: string | null;
+    user_agent: string | null;
+    created_at: number;
+    outcome: string | null;
+}
+export interface AuditFilters {
+    admin?: string;
+    action?: string;
+    category?: string;
+    tenant?: string;
+    from?: number;
+    to?: number;
+    limit?: number;
+    offset?: number;
+}
+export declare class AdminAuditLog {
+    private repo;
+    constructor(repo: IAdminAuditLogRepository);
+    /** Append an audit entry. Immutable -- no updates or deletes. */
+    log(entry: AuditEntry): Promise<AdminAuditLogRow>;
+    /** Query audit log with filters. */
+    query(filters: AuditFilters): Promise<{
+        entries: AdminAuditLogRow[];
+        total: number;
+    }>;
+    /** Export as CSV string for compliance. */
+    exportCsv(filters: AuditFilters): Promise<string>;
+}

package/dist/admin/audit-log.js

@@ -0,0 +1,63 @@
+import crypto from "node:crypto";
+export class AdminAuditLog {
+    repo;
+    constructor(repo) {
+        this.repo = repo;
+    }
+    /** Append an audit entry. Immutable -- no updates or deletes. */
+    async log(entry) {
+        const row = {
+            id: crypto.randomUUID(),
+            admin_user: entry.adminUser,
+            action: entry.action,
+            category: entry.category,
+            target_tenant: entry.targetTenant ?? null,
+            target_user: entry.targetUser ?? null,
+            details: JSON.stringify(entry.details),
+            ip_address: entry.ipAddress ?? null,
+            user_agent: entry.userAgent ?? null,
+            created_at: Date.now(),
+            outcome: entry.outcome ?? null,
+        };
+        try {
+            await this.repo.insert(row);
+        }
+        catch {
+            // Audit log failures are non-fatal — swallow to prevent unhandled rejections
+            // when the database is unavailable or closing (e.g. in tests).
+        }
+        return row;
+    }
+    /** Query audit log with filters. */
+    async query(filters) {
+        return this.repo.query(filters);
+    }
+    /** Export as CSV string for compliance. */
+    async exportCsv(filters) {
+        const exportFilters = { ...filters, limit: undefined, offset: undefined };
+        const rows = await this.repo.queryAll(exportFilters);
+        const header = "id,admin_user,action,category,target_tenant,target_user,details,ip_address,user_agent,created_at,outcome";
+        const csvEscape = (v) => {
+            if (/^[=+\-@]/.test(v))
+                v = `'${v}`;
+            return /[",\n\r]/.test(v) ? `"${v.replace(/"/g, '""')}"` : v;
+        };
+        const lines = rows.map((r) => {
+            const fields = [
+                csvEscape(r.id),
+                csvEscape(r.admin_user),
+                csvEscape(r.action),
+                csvEscape(r.category),
+                csvEscape(r.target_tenant ?? ""),
+                csvEscape(r.target_user ?? ""),
+                csvEscape(r.details),
+                csvEscape(r.ip_address ?? ""),
+                csvEscape(r.user_agent ?? ""),
+                String(r.created_at),
+                csvEscape(r.outcome ?? ""),
+            ];
+            return fields.join(",");
+        });
+        return [header, ...lines].join("\n");
+    }
+}

package/dist/admin/index.d.ts

@@ -0,0 +1,6 @@
+export type { IAdminAuditLogRepository } from "./admin-audit-log-repository.js";
+export { DrizzleAdminAuditLogRepository } from "./admin-audit-log-repository.js";
+export type { AuditCategory, AuditEntry, AdminAuditLogRow, AuditFilters } from "./audit-log.js";
+export { AdminAuditLog } from "./audit-log.js";
+export type { Role, UserRoleRow } from "./role-store.js";
+export { isValidRole, RoleStore } from "./role-store.js";

package/dist/admin/index.js

@@ -0,0 +1,3 @@
+export { DrizzleAdminAuditLogRepository } from "./admin-audit-log-repository.js";
+export { AdminAuditLog } from "./audit-log.js";
+export { isValidRole, RoleStore } from "./role-store.js";

package/dist/admin/role-store.d.ts

@@ -0,0 +1,37 @@
+import type { PlatformDb } from "../db/index.js";
+export type Role = "platform_admin" | "tenant_admin" | "user";
+export interface UserRoleRow {
+    user_id: string;
+    tenant_id: string;
+    role: string;
+    granted_by: string | null;
+    granted_at: number;
+}
+/** Validate that a string is a valid Role. */
+export declare function isValidRole(role: string): role is Role;
+/**
+ * CRUD store for user roles backed by Drizzle ORM.
+ *
+ * Platform admins are stored with a special sentinel tenant_id ("*") so they
+ * can be queried independently of any specific tenant.
+ */
+export declare class RoleStore {
+    private readonly db;
+    /** Sentinel tenant_id used for platform-wide admin roles. */
+    static readonly PLATFORM_TENANT = "*";
+    constructor(db: PlatformDb);
+    /** Get the role for a user in a specific tenant (or null if none). */
+    getRole(userId: string, tenantId: string): Promise<Role | null>;
+    /** Upsert a role for a user in a tenant. */
+    setRole(userId: string, tenantId: string, role: Role, grantedBy: string | null): Promise<void>;
+    /** Remove a user's role in a tenant. */
+    removeRole(userId: string, tenantId: string): Promise<boolean>;
+    /** List all users with roles in a given tenant. */
+    listByTenant(tenantId: string): Promise<UserRoleRow[]>;
+    /** List all platform admins (users with platform_admin role in the sentinel tenant). */
+    listPlatformAdmins(): Promise<UserRoleRow[]>;
+    /** Check if a user is a platform admin. */
+    isPlatformAdmin(userId: string): Promise<boolean>;
+    /** Count the number of platform admins. */
+    countPlatformAdmins(): Promise<number>;
+}

package/dist/admin/role-store.js

@@ -0,0 +1,106 @@
+import { and, count, eq, sql } from "drizzle-orm";
+import { userRoles } from "../db/schema/index.js";
+const VALID_ROLES = new Set(["platform_admin", "tenant_admin", "user"]);
+/** Validate that a string is a valid Role. */
+export function isValidRole(role) {
+    return VALID_ROLES.has(role);
+}
+/**
+ * CRUD store for user roles backed by Drizzle ORM.
+ *
+ * Platform admins are stored with a special sentinel tenant_id ("*") so they
+ * can be queried independently of any specific tenant.
+ */
+export class RoleStore {
+    db;
+    /** Sentinel tenant_id used for platform-wide admin roles. */
+    static PLATFORM_TENANT = "*";
+    constructor(db) {
+        this.db = db;
+    }
+    /** Get the role for a user in a specific tenant (or null if none). */
+    async getRole(userId, tenantId) {
+        const rows = await this.db
+            .select({ role: userRoles.role })
+            .from(userRoles)
+            .where(and(eq(userRoles.userId, userId), eq(userRoles.tenantId, tenantId)));
+        return rows[0] ? rows[0].role : null;
+    }
+    /** Upsert a role for a user in a tenant. */
+    async setRole(userId, tenantId, role, grantedBy) {
+        if (!isValidRole(role)) {
+            throw new Error(`Invalid role: ${role}`);
+        }
+        await this.db
+            .insert(userRoles)
+            .values({
+            userId,
+            tenantId,
+            role,
+            grantedBy,
+            grantedAt: Date.now(),
+        })
+            .onConflictDoUpdate({
+            target: [userRoles.userId, userRoles.tenantId],
+            set: {
+                role,
+                grantedBy,
+                grantedAt: Date.now(),
+            },
+        });
+    }
+    /** Remove a user's role in a tenant. */
+    async removeRole(userId, tenantId) {
+        const result = await this.db
+            .delete(userRoles)
+            .where(and(eq(userRoles.userId, userId), eq(userRoles.tenantId, tenantId)))
+            .returning({ userId: userRoles.userId });
+        return result.length > 0;
+    }
+    /** List all users with roles in a given tenant. */
+    async listByTenant(tenantId) {
+        const rows = await this.db
+            .select()
+            .from(userRoles)
+            .where(eq(userRoles.tenantId, tenantId))
+            .orderBy(sql `${userRoles.grantedAt} DESC`);
+        return rows.map(toRow);
+    }
+    /** List all platform admins (users with platform_admin role in the sentinel tenant). */
+    async listPlatformAdmins() {
+        const rows = await this.db
+            .select()
+            .from(userRoles)
+            .where(and(eq(userRoles.tenantId, RoleStore.PLATFORM_TENANT), eq(userRoles.role, "platform_admin")))
+            .orderBy(sql `${userRoles.grantedAt} DESC`);
+        return rows.map(toRow);
+    }
+    /** Check if a user is a platform admin. */
+    async isPlatformAdmin(userId) {
+        const rows = await this.db
+            .select({ userId: userRoles.userId })
+            .from(userRoles)
+            .where(and(eq(userRoles.userId, userId), eq(userRoles.tenantId, RoleStore.PLATFORM_TENANT), eq(userRoles.role, "platform_admin")));
+        return rows.length > 0;
+    }
+    /** Count the number of platform admins. */
+    async countPlatformAdmins() {
+        const rows = await this.db
+            .select({ count: count() })
+            .from(userRoles)
+            .where(and(eq(userRoles.tenantId, RoleStore.PLATFORM_TENANT), eq(userRoles.role, "platform_admin")));
+        return rows[0]?.count ?? 0;
+    }
+}
+// ---------------------------------------------------------------------------
+// Row mapper
+// ---------------------------------------------------------------------------
+function toRow(row) {
+    return {
+        user_id: row.userId,
+        tenant_id: row.tenantId,
+        role: row.role,
+        granted_by: row.grantedBy,
+        granted_at: row.grantedAt,
+    };
+}

package/dist/auth/api-key-repository.d.ts

@@ -0,0 +1,11 @@
+import type { PlatformDb } from "../db/index.js";
+import type { AuthUser } from "./index.js";
+export interface IApiKeyRepository {
+    /** Look up an API key by its SHA-256 hash. Returns null if not found, revoked, or expired. */
+    findByHash(keyHash: string): Promise<AuthUser | null>;
+}
+export declare class DrizzleApiKeyRepository implements IApiKeyRepository {
+    private readonly db;
+    constructor(db: PlatformDb);
+    findByHash(keyHash: string): Promise<AuthUser | null>;
+}

package/dist/auth/api-key-repository.js

@@ -0,0 +1,33 @@
+import { and, eq, gt, isNull, or } from "drizzle-orm";
+import { platformApiKeys } from "../db/schema/platform-api-keys.js";
+export class DrizzleApiKeyRepository {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    async findByHash(keyHash) {
+        const now = Date.now();
+        const rows = await this.db
+            .select({
+            userId: platformApiKeys.userId,
+            roles: platformApiKeys.roles,
+        })
+            .from(platformApiKeys)
+            .where(and(eq(platformApiKeys.keyHash, keyHash), isNull(platformApiKeys.revokedAt), or(isNull(platformApiKeys.expiresAt), gt(platformApiKeys.expiresAt, now))))
+            .limit(1);
+        const row = rows[0];
+        if (!row)
+            return null;
+        let roles;
+        try {
+            roles = JSON.parse(row.roles);
+        }
+        catch {
+            return null;
+        }
+        return {
+            id: row.userId,
+            roles,
+        };
+    }
+}

package/dist/auth/api-key-repository.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/auth/api-key-repository.test.js

@@ -0,0 +1,46 @@
+import { createHash } from "node:crypto";
+import { describe, expect, it } from "vitest";
+// In-memory mock that follows the same contract
+function createMockRepo(rows) {
+    return {
+        async findByHash(hash) {
+            const now = Date.now();
+            const row = rows.find((r) => r.keyHash === hash && r.revokedAt === null && (r.expiresAt === null || r.expiresAt > now));
+            if (!row)
+                return null;
+            return { id: row.userId, roles: JSON.parse(row.roles) };
+        },
+    };
+}
+function sha256(token) {
+    return createHash("sha256").update(token).digest("hex");
+}
+describe("IApiKeyRepository contract", () => {
+    const hash = sha256("test-token");
+    it("returns AuthUser for valid key", async () => {
+        const repo = createMockRepo([
+            { keyHash: hash, userId: "user-1", roles: '["admin","user"]', expiresAt: null, revokedAt: null },
+        ]);
+        const user = await repo.findByHash(hash);
+        expect(user).toEqual({ id: "user-1", roles: ["admin", "user"] });
+    });
+    it("returns null for revoked key", async () => {
+        const repo = createMockRepo([
+            { keyHash: hash, userId: "user-1", roles: '["admin"]', expiresAt: null, revokedAt: Date.now() - 1000 },
+        ]);
+        const user = await repo.findByHash(hash);
+        expect(user).toBeNull();
+    });
+    it("returns null for expired key", async () => {
+        const repo = createMockRepo([
+            { keyHash: hash, userId: "user-1", roles: '["admin"]', expiresAt: Date.now() - 1000, revokedAt: null },
+        ]);
+        const user = await repo.findByHash(hash);
+        expect(user).toBeNull();
+    });
+    it("returns null for unknown hash", async () => {
+        const repo = createMockRepo([]);
+        const user = await repo.findByHash(sha256("unknown"));
+        expect(user).toBeNull();
+    });
+});

package/dist/auth/auth.test.d.ts

@@ -0,0 +1 @@
+export {};