@devxcrew/platform 0.1.2

package/dist/modules/identity/identity.presentation-service.d.ts

@@ -0,0 +1,23 @@
+import type { Kysely } from "kysely";
+import type { IdentitySchema, Principal } from "./identity.types.js";
+export declare class IdentityPresentationService {
+    private readonly db;
+    private readonly appName;
+    constructor(db: Kysely<IdentitySchema>, appName: string);
+    configuration(appId: string, requiresOrganizationId: boolean): Promise<{
+        displayName: string;
+        requiresOrganizationId: boolean;
+    }>;
+    presentation(actor: Principal): Promise<{
+        displayName: string;
+        organizationDisplayName: string;
+        locale: string;
+        timeZone: string;
+    }>;
+    organizationSettings(actor: Principal): Promise<{
+        displayName: string;
+        locale: string;
+        timeZone: string;
+        version: number;
+    }>;
+}

package/dist/modules/identity/identity.presentation-service.js

@@ -0,0 +1,51 @@
+export class IdentityPresentationService {
+    db;
+    appName;
+    constructor(db, appName) {
+        this.db = db;
+        this.appName = appName;
+    }
+    async configuration(appId, requiresOrganizationId) {
+        const app = await this.db
+            .selectFrom("identity_app_settings")
+            .select("display_name")
+            .where("app_id", "=", appId)
+            .executeTakeFirst();
+        return {
+            displayName: app?.display_name ?? this.appName,
+            requiresOrganizationId,
+        };
+    }
+    async presentation(actor) {
+        const app = await this.db
+            .selectFrom("identity_app_settings")
+            .select(["display_name", "locale", "time_zone"])
+            .where("app_id", "=", actor.appId)
+            .executeTakeFirst();
+        const organization = await this.db
+            .selectFrom("identity_settings")
+            .selectAll()
+            .where("tenant_id", "=", actor.tenant.id)
+            .executeTakeFirst();
+        return {
+            displayName: app?.display_name ?? this.appName,
+            organizationDisplayName: organization?.display_name ?? actor.tenant.name,
+            locale: organization?.locale ?? app?.locale ?? "en",
+            timeZone: organization?.time_zone ?? app?.time_zone ?? "UTC",
+        };
+    }
+    async organizationSettings(actor) {
+        const organization = await this.db
+            .selectFrom("identity_settings")
+            .select("version")
+            .where("tenant_id", "=", actor.tenant.id)
+            .executeTakeFirst();
+        const presentation = await this.presentation(actor);
+        return {
+            displayName: presentation.organizationDisplayName,
+            locale: presentation.locale,
+            timeZone: presentation.timeZone,
+            version: Number(organization?.version ?? 0),
+        };
+    }
+}

package/dist/modules/identity/identity.provider.d.ts

@@ -0,0 +1,78 @@
+import type { Kysely } from "kysely";
+import type { IdentitySchema, IdentityProviderOptions } from "./identity.types.js";
+import { type IdentityPermissionDeclaration } from "./identity.permission-declarations.js";
+export declare function createIdentityProvider(database: Kysely<IdentitySchema>, environment: NodeJS.ProcessEnv, options?: IdentityProviderOptions): {
+    registerPermissions: (declaration: IdentityPermissionDeclaration) => Promise<{
+        owner: string;
+        permissionIds: string[];
+    }>;
+    handle: (request: import("node:http").IncomingMessage, response: import("node:http").ServerResponse, signal?: AbortSignal) => Promise<boolean>;
+    authenticate: (portal: import("./identity.types.js").Portal, token?: string) => Promise<import("./identity.types.js").Principal>;
+    authenticateRequest: (request: import("node:http").IncomingMessage, requestedPortal: import("./identity.types.js").Portal, signal?: AbortSignal) => Promise<import("./identity.types.js").Principal>;
+    requirePermission: (principal: import("./identity.types.js").Principal, permission: string) => void;
+    administration: {
+        list: (actor: import("./identity.types.js").Principal, resource: import("./identity.administration-schema.js").IdentityResource, query: import("./identity.administration-schema.js").IdentityListQuery) => Promise<{
+            data: Record<string, unknown>[];
+            meta: {
+                page: number;
+                perPage: number;
+                total: number;
+                lastPage: number;
+            };
+        }>;
+        show: (actor: import("./identity.types.js").Principal, resource: import("./identity.administration-schema.js").IdentityResource, id: string) => Promise<Record<string, unknown>>;
+        create: (actor: import("./identity.types.js").Principal, resource: import("./identity.administration-schema.js").IdentityResource, raw: unknown) => Promise<{
+            id: string;
+            name: string;
+            active: boolean;
+            version: number;
+        } | {
+            id: string;
+            userId: string;
+            tenantId: string;
+            roleId: string;
+            portal: import("./identity.types.js").Portal;
+            active: boolean;
+            version: number;
+        }>;
+        update: (actor: import("./identity.types.js").Principal, resource: import("./identity.administration-schema.js").IdentityResource, id: string, raw: unknown) => Promise<{
+            id: string;
+            userId: string;
+            tenantId: string;
+            roleId: string;
+            portal: import("./identity.types.js").Portal;
+            active: boolean;
+            version: number;
+        } | {
+            active: boolean;
+            version: number;
+            id: string;
+            name: string;
+        } | {
+            id: string;
+            permissionIds: string[];
+            version: number;
+        }>;
+        remove: (actor: import("./identity.types.js").Principal, resource: import("./identity.administration-schema.js").IdentityResource, id: string, expectedVersion?: number) => Promise<void>;
+        profile: (actor: import("./identity.types.js").Principal, raw?: unknown) => Promise<{
+            active: boolean;
+            version: number;
+            email: string;
+            id: string;
+            name: string;
+        }>;
+        settings: (actor: import("./identity.types.js").Principal, raw?: unknown) => Promise<{
+            displayName: string;
+            locale: string;
+            timeZone: string;
+            version: number;
+        }>;
+        presentation: (actor: import("./identity.types.js").Principal) => Promise<{
+            displayName: string;
+            organizationDisplayName: string;
+            locale: string;
+            timeZone: string;
+        }>;
+    };
+    verify(): Promise<void>;
+};

package/dist/modules/identity/identity.provider.js

@@ -0,0 +1,119 @@
+import { z } from "zod";
+import { IdentityRepository } from "./identity.repository.js";
+import { IdentityService } from "./identity.service.js";
+import { IdentityController } from "./identity.controller.js";
+import { IdentityAdministrationService } from "./identity.administration-service.js";
+import { IdentityLifecycleService } from "./identity.lifecycle-service.js";
+import { identityKeySchema } from "./identity.schema.js";
+import { registerIdentityPermissions } from "./identity.permission-declarations.js";
+export function createIdentityProvider(database, environment, options = {}) {
+    const config = z
+        .object({
+        appId: z.string().regex(/^[a-z][a-z0-9-]{0,63}$/),
+        origin: z.url(),
+        mode: z.enum(["single-client", "multi-tenant"]),
+        tenantId: identityKeySchema,
+        sessionSeconds: z.coerce.number().int().min(300).max(86400),
+    })
+        .parse({
+        appId: environment.APP_ID,
+        origin: environment.APP_URL,
+        mode: environment.IDENTITY_MODE ?? "single-client",
+        tenantId: environment.IDENTITY_TENANT_ID ?? "default",
+        sessionSeconds: environment.IDENTITY_SESSION_SECONDS ?? 28800,
+    });
+    const origin = new URL(config.origin);
+    if (origin.origin !== config.origin ||
+        !["http:", "https:"].includes(origin.protocol))
+        throw new Error("Identity requires a valid application origin.");
+    if (origin.protocol !== "https:" &&
+        !["127.0.0.1", "localhost", "[::1]"].includes(origin.hostname))
+        throw new Error("Identity requires HTTPS outside loopback development.");
+    const service = new IdentityService(new IdentityRepository(database), config);
+    const appName = z
+        .string()
+        .trim()
+        .min(1)
+        .max(100)
+        .parse(environment.APP_NAME || config.appId);
+    const administration = new IdentityAdministrationService(database, appName);
+    const lifecycle = new IdentityLifecycleService(database, config, options.delivery);
+    const controller = new IdentityController(service, config, administration, lifecycle);
+    return {
+        registerPermissions: (declaration) => registerIdentityPermissions(database, config.appId, declaration),
+        handle: controller.handle.bind(controller),
+        authenticate: service.authenticate.bind(service),
+        authenticateRequest: controller.authenticateRequest.bind(controller),
+        requirePermission: service.requirePermission.bind(service),
+        administration: {
+            list: administration.list.bind(administration),
+            show: administration.show.bind(administration),
+            create: administration.create.bind(administration),
+            update: administration.update.bind(administration),
+            remove: administration.remove.bind(administration),
+            profile: administration.profile.bind(administration),
+            settings: administration.settings.bind(administration),
+            presentation: administration.presentation.bind(administration),
+        },
+        async verify() {
+            await database.selectFrom("identity_permission_declarations").select(["permission_id", "label"]).limit(1).execute();
+            for (const declaration of options.permissions ?? [])
+                await registerIdentityPermissions(database, config.appId, declaration);
+            await database
+                .selectFrom("identity_roles")
+                .select("id")
+                .limit(1)
+                .execute();
+            await database
+                .selectFrom("identity_users")
+                .select("version")
+                .limit(1)
+                .execute();
+            await database
+                .selectFrom("identity_tenants")
+                .select("version")
+                .limit(1)
+                .execute();
+            await database
+                .selectFrom("identity_roles")
+                .select("version")
+                .limit(1)
+                .execute();
+            await database
+                .selectFrom("identity_settings")
+                .select("version")
+                .limit(1)
+                .execute();
+            await database
+                .selectFrom("identity_app_settings")
+                .select(["version", "session_seconds"])
+                .limit(1)
+                .execute();
+            await database
+                .selectFrom("identity_tokens")
+                .select(["delivered", "consumed_at"])
+                .limit(1)
+                .execute();
+            await database
+                .selectFrom("identity_audit_events")
+                .select("created_at")
+                .limit(1)
+                .execute();
+            await database
+                .selectFrom("identity_custom_roles")
+                .select(["app_id", "tenant_id", "version"])
+                .limit(1)
+                .execute();
+            await database
+                .selectFrom("identity_custom_role_permissions")
+                .select("permission_id")
+                .limit(1)
+                .execute();
+            await database
+                .selectFrom("identity_memberships")
+                .select(["custom_role_id", "active", "version"])
+                .limit(1)
+                .execute();
+        },
+    };
+}

package/dist/modules/identity/identity.public-schemas.d.ts

@@ -0,0 +1,4 @@
+export * from "./identity.administration-schema.js";
+export * from "./identity.lifecycle-schema.js";
+export { loginSchema, passwordSchema, portalSchema, } from "./identity.schema.js";
+export type { IdentityPermissionCatalogEntry } from "./identity.types.js";

package/dist/modules/identity/identity.public-schemas.js

@@ -0,0 +1,3 @@
+export * from "./identity.administration-schema.js";
+export * from "./identity.lifecycle-schema.js";
+export { loginSchema, passwordSchema, portalSchema, } from "./identity.schema.js";

package/dist/modules/identity/identity.repository.d.ts

@@ -0,0 +1,40 @@
+import { type Kysely } from "kysely";
+import type { IdentitySchema, Portal } from "./identity.types.js";
+export declare class IdentityRepository {
+    private readonly db;
+    constructor(db: Kysely<IdentitySchema>);
+    user(email: string): Promise<{
+        active: number;
+        email: string;
+        id: string;
+        name: string;
+        password_hash: string;
+        version: number;
+    } | undefined>;
+    sessionSeconds(appId: string, fallback: number): Promise<number>;
+    principal(userId: string, tenantId: string, portal: Portal, appId: string): Promise<{
+        user: {
+            id: string;
+            email: string;
+            name: string;
+        };
+        tenant: {
+            id: string;
+            name: string;
+        };
+        permissions: string[];
+    } | null>;
+    session(tokenHash: string, appId: string, portal: Portal, now: string): Promise<{
+        app_id: string;
+        expires_at: string;
+        portal: Portal;
+        tenant_id: string;
+        token_hash: string;
+        user_id: string;
+    } | undefined>;
+    createSession(session: IdentitySchema["identity_sessions"], expectedHash: string, previous?: string): Promise<boolean>;
+    revoke(tokenHash: string, appId: string, portal: Portal): Promise<void>;
+    throttle(key: string): Promise<number>;
+    clearThrottle(key: string): Promise<void>;
+    changePassword(userId: string, expectedHash: string, passwordHash: string): Promise<boolean>;
+}

package/dist/modules/identity/identity.repository.js

@@ -0,0 +1,196 @@
+import { filterDeclaredPermissions } from "./identity.permission-declarations.js";
+import { sql } from "kysely";
+import { checkIdentityRequest } from "./identity.request-context.js";
+export class IdentityRepository {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    user(email) {
+        return this.db
+            .selectFrom("identity_users")
+            .selectAll()
+            .where("email", "=", email)
+            .executeTakeFirst();
+    }
+    async sessionSeconds(appId, fallback) {
+        const row = await this.db
+            .selectFrom("identity_app_settings")
+            .select("session_seconds")
+            .where("app_id", "=", appId)
+            .executeTakeFirst();
+        return Number(row?.session_seconds ?? fallback);
+    }
+    async principal(userId, tenantId, portal, appId) {
+        const member = await this.db
+            .selectFrom("identity_memberships as m")
+            .innerJoin("identity_users as u", "u.id", "m.user_id")
+            .innerJoin("identity_tenants as t", "t.id", "m.tenant_id")
+            .select([
+            "u.id",
+            "u.email",
+            "u.name",
+            "t.id as tenantId",
+            "t.name as tenantName",
+            "m.custom_role_id as customRoleId",
+        ])
+            .where("u.id", "=", userId)
+            .where("m.tenant_id", "=", tenantId)
+            .where("m.role_id", "=", portal)
+            .where("m.active", "=", 1)
+            .where("u.active", "=", 1)
+            .where("t.active", "=", 1)
+            .executeTakeFirst();
+        if (!member)
+            return null;
+        if (member.customRoleId) {
+            const role = await this.db
+                .selectFrom("identity_custom_roles")
+                .select("id")
+                .where("id", "=", member.customRoleId)
+                .where("app_id", "=", appId)
+                .where("tenant_id", "=", tenantId)
+                .where("active", "=", 1)
+                .executeTakeFirst();
+            if (!role || portal !== "user")
+                return null;
+            const permissions = await this.db
+                .selectFrom("identity_custom_role_permissions")
+                .select("permission_id")
+                .where("role_id", "=", role.id)
+                .execute();
+            return {
+                user: { id: member.id, email: member.email, name: member.name },
+                tenant: { id: member.tenantId, name: member.tenantName },
+                permissions: await filterDeclaredPermissions(this.db, appId, portal, permissions.map((row) => row.permission_id)),
+            };
+        }
+        const permissions = await this.db
+            .selectFrom("identity_role_permissions")
+            .select("permission_id")
+            .where("role_id", "=", portal)
+            .execute();
+        return {
+            user: { id: member.id, email: member.email, name: member.name },
+            tenant: { id: member.tenantId, name: member.tenantName },
+            permissions: await filterDeclaredPermissions(this.db, appId, portal, permissions.map((p) => p.permission_id)),
+        };
+    }
+    async session(tokenHash, appId, portal, now) {
+        return this.db
+            .selectFrom("identity_sessions")
+            .selectAll()
+            .where("token_hash", "=", tokenHash)
+            .where("app_id", "=", appId)
+            .where("portal", "=", portal)
+            .where("expires_at", ">", now)
+            .executeTakeFirst();
+    }
+    async createSession(session, expectedHash, previous) {
+        return this.db.transaction().execute(async (trx) => {
+            checkIdentityRequest();
+            const current = await trx
+                .selectFrom("identity_users")
+                .select("id")
+                .where("id", "=", session.user_id)
+                .where("password_hash", "=", expectedHash)
+                .where("active", "=", 1)
+                .executeTakeFirst();
+            if (!current)
+                return false;
+            const membership = await trx
+                .selectFrom("identity_memberships")
+                .select("custom_role_id")
+                .where("user_id", "=", session.user_id)
+                .where("tenant_id", "=", session.tenant_id)
+                .where("role_id", "=", session.portal)
+                .where("active", "=", 1)
+                .executeTakeFirst();
+            if (!membership)
+                return false;
+            if (membership.custom_role_id) {
+                const role = await trx
+                    .selectFrom("identity_custom_roles")
+                    .select("id")
+                    .where("id", "=", membership.custom_role_id)
+                    .where("app_id", "=", session.app_id)
+                    .where("tenant_id", "=", session.tenant_id)
+                    .where("active", "=", 1)
+                    .executeTakeFirst();
+                if (!role)
+                    return false;
+            }
+            await trx
+                .deleteFrom("identity_sessions")
+                .where("expires_at", "<=", new Date().toISOString())
+                .execute();
+            if (previous)
+                await trx
+                    .deleteFrom("identity_sessions")
+                    .where("token_hash", "=", previous)
+                    .where("app_id", "=", session.app_id)
+                    .where("portal", "=", session.portal)
+                    .execute();
+            await trx.insertInto("identity_sessions").values(session).execute();
+            checkIdentityRequest();
+            return true;
+        });
+    }
+    async revoke(tokenHash, appId, portal) {
+        checkIdentityRequest();
+        await this.db
+            .deleteFrom("identity_sessions")
+            .where("token_hash", "=", tokenHash)
+            .where("app_id", "=", appId)
+            .where("portal", "=", portal)
+            .execute();
+    }
+    async throttle(key) {
+        const now = new Date();
+        return this.db.transaction().execute(async (trx) => {
+            await trx
+                .deleteFrom("identity_throttles")
+                .where("expires_at", "<=", now.toISOString())
+                .execute();
+            await trx
+                .insertInto("identity_throttles")
+                .values({
+                key,
+                attempts: 1,
+                expires_at: new Date(now.getTime() + 15 * 60 * 1000).toISOString(),
+            })
+                .onConflict((c) => c.column("key").doUpdateSet({ attempts: sql `attempts + 1` }))
+                .execute();
+            const row = await trx
+                .selectFrom("identity_throttles")
+                .select("attempts")
+                .where("key", "=", key)
+                .executeTakeFirstOrThrow();
+            return Number(row.attempts);
+        });
+    }
+    async clearThrottle(key) {
+        await this.db
+            .deleteFrom("identity_throttles")
+            .where("key", "=", key)
+            .execute();
+    }
+    async changePassword(userId, expectedHash, passwordHash) {
+        return this.db.transaction().execute(async (trx) => {
+            checkIdentityRequest();
+            const result = await trx
+                .updateTable("identity_users")
+                .set({ password_hash: passwordHash })
+                .where("id", "=", userId)
+                .where("password_hash", "=", expectedHash)
+                .executeTakeFirst();
+            if (result.numUpdatedRows !== 1n)
+                return false;
+            await trx
+                .deleteFrom("identity_sessions")
+                .where("user_id", "=", userId)
+                .execute();
+            return true;
+        });
+    }
+}

package/dist/modules/identity/identity.request-context.d.ts

@@ -0,0 +1,2 @@
+export declare function runIdentityRequest<T>(signal: AbortSignal | undefined, work: () => T): T;
+export declare function checkIdentityRequest(): void;

package/dist/modules/identity/identity.request-context.js

@@ -0,0 +1,10 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { IdentityError } from "./identity.error.js";
+const requestSignals = new AsyncLocalStorage();
+export function runIdentityRequest(signal, work) {
+    return signal ? requestSignals.run(signal, work) : work();
+}
+export function checkIdentityRequest() {
+    if (requestSignals.getStore()?.aborted)
+        throw new IdentityError(408, "The request expired. Try again.");
+}

package/dist/modules/identity/identity.roles-migration.d.ts

@@ -0,0 +1,2 @@
+import type { Migration } from "kysely/migration";
+export declare const identityRolesMigration: Migration;

package/dist/modules/identity/identity.roles-migration.js

@@ -0,0 +1,64 @@
+export const identityRolesMigration = {
+    async up(db) {
+        await db.schema
+            .createTable("identity_custom_roles")
+            .addColumn("id", "text", (c) => c.primaryKey())
+            .addColumn("app_id", "text", (c) => c.notNull())
+            .addColumn("tenant_id", "text", (c) => c.notNull().references("identity_tenants.id"))
+            .addColumn("name", "text", (c) => c.notNull())
+            .addColumn("active", "integer", (c) => c.notNull().defaultTo(1))
+            .addColumn("version", "integer", (c) => c.notNull().defaultTo(0))
+            .addUniqueConstraint("identity_custom_role_name", [
+            "app_id",
+            "tenant_id",
+            "name",
+        ])
+            .execute();
+        await db.schema
+            .createTable("identity_custom_role_permissions")
+            .addColumn("role_id", "text", (c) => c.notNull().references("identity_custom_roles.id").onDelete("cascade"))
+            .addColumn("permission_id", "text", (c) => c.notNull().references("identity_permissions.id"))
+            .addPrimaryKeyConstraint("identity_custom_role_permission_pk", [
+            "role_id",
+            "permission_id",
+        ])
+            .execute();
+        await db.schema
+            .alterTable("identity_memberships")
+            .addColumn("custom_role_id", "text", (c) => c.references("identity_custom_roles.id"))
+            .execute();
+        await db.schema
+            .alterTable("identity_memberships")
+            .addColumn("active", "integer", (c) => c.notNull().defaultTo(1))
+            .execute();
+        await db.schema
+            .alterTable("identity_memberships")
+            .addColumn("version", "integer", (c) => c.notNull().defaultTo(0))
+            .execute();
+    },
+    async down(db) {
+        const customRole = await db
+            .selectFrom("identity_custom_roles")
+            .select("id")
+            .limit(1)
+            .executeTakeFirst();
+        const restrictedMembership = await db
+            .selectFrom("identity_memberships")
+            .select("user_id")
+            .where((eb) => eb.or([
+            eb("custom_role_id", "is not", null),
+            eb("active", "!=", 1),
+        ]))
+            .limit(1)
+            .executeTakeFirst();
+        if (customRole || restrictedMembership)
+            throw new Error("Role rollback would remove access restrictions. Restore a compatible database snapshot instead.");
+        for (const column of ["custom_role_id", "active", "version"])
+            await db.schema
+                .alterTable("identity_memberships")
+                .dropColumn(column)
+                .execute();
+        await db.schema.dropTable("identity_custom_role_permissions").execute();
+        await db.schema.dropTable("identity_custom_roles").execute();
+    },
+};

package/dist/modules/identity/identity.roles-service.d.ts

@@ -0,0 +1,49 @@
+import type { Kysely } from "kysely";
+import type { IdentitySchema, Portal, Principal } from "./identity.types.js";
+export declare class IdentityRolesService {
+    private readonly db;
+    constructor(db: Kysely<IdentitySchema>);
+    resolve(database: Kysely<IdentitySchema>, actor: Principal, roleId: string, tenantId: string): Promise<{
+        portal: Portal;
+        customRoleId: null;
+    } | {
+        portal: "user";
+        customRoleId: string;
+    }>;
+    create(actor: Principal, raw: unknown): Promise<{
+        id: `${string}-${string}-${string}-${string}-${string}`;
+        name: string;
+        tenantId: string;
+        portal: string;
+        system: boolean;
+        active: boolean;
+        version: number;
+        permissionIds: string[];
+    }>;
+    update(actor: Principal, id: string, raw: unknown): Promise<{
+        id: string;
+        name: string;
+        tenantId: string;
+        portal: string;
+        system: boolean;
+        active: boolean;
+        version: number;
+        permissionIds: string[];
+    }>;
+    updateMembership(actor: Principal, id: string, raw: unknown): Promise<{
+        id: string;
+        userId: string;
+        tenantId: string;
+        roleId: string;
+        portal: Portal;
+        active: boolean;
+        version: number;
+    }>;
+    removeMembership(actor: Principal, id: string, expectedVersion?: number): Promise<void>;
+    private manage;
+    private scope;
+    private permissions;
+    private uniqueName;
+    private replacePermissions;
+    private audit;
+}