@devxcrew/platform 0.1.2

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

@@ -0,0 +1,327 @@
+import { randomUUID } from "node:crypto";
+import { validateDeclaredPermissions } from "./identity.permission-declarations.js";
+import { IdentityError } from "./identity.error.js";
+import { checkIdentityRequest } from "./identity.request-context.js";
+import { protectAdministrators } from "./identity.membership-policy.js";
+import { customRoleCreateSchema, customRoleUpdateSchema, membershipUpdateSchema, } from "./identity.administration-schema.js";
+export class IdentityRolesService {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    async resolve(database, actor, roleId, tenantId) {
+        if (["user", "admin", "super-admin"].includes(roleId)) {
+            if (actor.portal !== "super-admin" && roleId !== "user")
+                throw new IdentityError(403, "Only super administrators can assign privileged roles.");
+            return { portal: roleId, customRoleId: null };
+        }
+        const role = await database
+            .selectFrom("identity_custom_roles")
+            .select("id")
+            .where("id", "=", roleId)
+            .where("app_id", "=", actor.appId)
+            .where("tenant_id", "=", tenantId)
+            .where("active", "=", 1)
+            .executeTakeFirst();
+        if (!role)
+            throw new IdentityError(422, "Select an active role in this organization.");
+        return { portal: "user", customRoleId: role.id };
+    }
+    async create(actor, raw) {
+        this.manage(actor);
+        const input = customRoleCreateSchema.parse(raw);
+        const tenantId = input.tenantId ?? actor.tenant.id;
+        this.scope(actor, tenantId);
+        return this.db.transaction().execute(async (trx) => {
+            checkIdentityRequest();
+            const tenant = await trx
+                .selectFrom("identity_tenants")
+                .select("id")
+                .where("id", "=", tenantId)
+                .where("active", "=", 1)
+                .executeTakeFirst();
+            if (!tenant)
+                throw new IdentityError(422, "Organization is inactive or unavailable.");
+            await this.permissions(trx, input.permissionIds, actor.appId);
+            await this.uniqueName(trx, actor.appId, tenantId, input.name);
+            const id = randomUUID();
+            await trx
+                .insertInto("identity_custom_roles")
+                .values({
+                id,
+                app_id: actor.appId,
+                tenant_id: tenantId,
+                name: input.name,
+            })
+                .execute();
+            await this.replacePermissions(trx, id, input.permissionIds);
+            await this.audit(trx, actor, tenantId, "identity.role.created", id);
+            checkIdentityRequest();
+            return {
+                id,
+                name: input.name,
+                tenantId,
+                portal: "user",
+                system: false,
+                active: true,
+                version: 0,
+                permissionIds: [...new Set(input.permissionIds)],
+            };
+        });
+    }
+    async update(actor, id, raw) {
+        this.manage(actor);
+        const input = customRoleUpdateSchema.parse(raw);
+        return this.db.transaction().execute(async (trx) => {
+            checkIdentityRequest();
+            const role = await trx
+                .selectFrom("identity_custom_roles")
+                .selectAll()
+                .where("id", "=", id)
+                .where("app_id", "=", actor.appId)
+                .executeTakeFirst();
+            if (!role ||
+                (actor.portal !== "super-admin" && role.tenant_id !== actor.tenant.id))
+                throw new IdentityError(404, "Role not found.");
+            if (Number(role.version) !== input.expectedVersion)
+                throw new IdentityError(409, "This record changed. Reload before saving.");
+            if (input.permissionIds)
+                await this.permissions(trx, input.permissionIds, actor.appId);
+            if (input.name)
+                await this.uniqueName(trx, actor.appId, role.tenant_id, input.name, id);
+            const updated = await trx
+                .updateTable("identity_custom_roles")
+                .set({
+                name: input.name ?? role.name,
+                active: input.active === undefined ? role.active : Number(input.active),
+                version: input.expectedVersion + 1,
+            })
+                .where("id", "=", id)
+                .where("version", "=", input.expectedVersion)
+                .executeTakeFirst();
+            if (updated.numUpdatedRows !== 1n)
+                throw new IdentityError(409, "This record changed. Reload before saving.");
+            if (input.permissionIds)
+                await this.replacePermissions(trx, id, input.permissionIds);
+            await trx
+                .deleteFrom("identity_sessions")
+                .where("app_id", "=", actor.appId)
+                .where("tenant_id", "=", role.tenant_id)
+                .where("user_id", "in", trx
+                .selectFrom("identity_memberships")
+                .select("user_id")
+                .where("custom_role_id", "=", id))
+                .execute();
+            await this.audit(trx, actor, role.tenant_id, "identity.role.changed", id);
+            const permissions = await trx
+                .selectFrom("identity_custom_role_permissions")
+                .select("permission_id")
+                .where("role_id", "=", id)
+                .execute();
+            checkIdentityRequest();
+            return {
+                id,
+                name: input.name ?? role.name,
+                tenantId: role.tenant_id,
+                portal: "user",
+                system: false,
+                active: input.active ?? Boolean(role.active),
+                version: input.expectedVersion + 1,
+                permissionIds: permissions.map((row) => row.permission_id),
+            };
+        });
+    }
+    async updateMembership(actor, id, raw) {
+        this.manage(actor);
+        const input = membershipUpdateSchema.parse(raw);
+        const [userId, tenantId, oldPortal, extra] = id.split("~");
+        if (!userId || !tenantId || !oldPortal || extra)
+            throw new IdentityError(404, "Membership not found.");
+        this.scope(actor, tenantId);
+        if (actor.portal !== "super-admin" && oldPortal !== "user")
+            throw new IdentityError(403, "Only super administrators can change privileged memberships.");
+        return this.db.transaction().execute(async (trx) => {
+            checkIdentityRequest();
+            const current = await trx
+                .selectFrom("identity_memberships")
+                .selectAll()
+                .where("user_id", "=", userId)
+                .where("tenant_id", "=", tenantId)
+                .where("role_id", "=", oldPortal)
+                .executeTakeFirst();
+            if (!current)
+                throw new IdentityError(404, "Membership not found.");
+            if (current.custom_role_id &&
+                !(await trx
+                    .selectFrom("identity_custom_roles")
+                    .select("id")
+                    .where("id", "=", current.custom_role_id)
+                    .where("app_id", "=", actor.appId)
+                    .executeTakeFirst()))
+                throw new IdentityError(404, "Membership not found.");
+            if (input.active &&
+                !(await trx
+                    .selectFrom("identity_tenants")
+                    .select("id")
+                    .where("id", "=", tenantId)
+                    .where("active", "=", 1)
+                    .executeTakeFirst()))
+                throw new IdentityError(422, "Organization is inactive or unavailable.");
+            if (Number(current.version) !== input.expectedVersion)
+                throw new IdentityError(409, "This record changed. Reload before saving.");
+            const selected = await this.resolve(trx, actor, input.roleId, tenantId);
+            if (!input.active || selected.portal !== oldPortal)
+                await protectAdministrators(trx, userId, tenantId, oldPortal);
+            if (selected.portal !== oldPortal &&
+                (await trx
+                    .selectFrom("identity_memberships")
+                    .select("user_id")
+                    .where("user_id", "=", userId)
+                    .where("tenant_id", "=", tenantId)
+                    .where("role_id", "=", selected.portal)
+                    .executeTakeFirst()))
+                throw new IdentityError(409, "This account already has that portal membership.");
+            const changed = await trx
+                .updateTable("identity_memberships")
+                .set({
+                role_id: selected.portal,
+                custom_role_id: selected.customRoleId,
+                active: Number(input.active),
+                version: input.expectedVersion + 1,
+            })
+                .where("user_id", "=", userId)
+                .where("tenant_id", "=", tenantId)
+                .where("role_id", "=", oldPortal)
+                .where("version", "=", input.expectedVersion)
+                .executeTakeFirst();
+            if (changed.numUpdatedRows !== 1n)
+                throw new IdentityError(409, "This record changed. Reload before saving.");
+            await trx
+                .deleteFrom("identity_sessions")
+                .where("app_id", "=", actor.appId)
+                .where("user_id", "=", userId)
+                .where("tenant_id", "=", tenantId)
+                .where("portal", "=", oldPortal)
+                .execute();
+            const nextId = `${userId}~${tenantId}~${selected.portal}`;
+            await this.audit(trx, actor, tenantId, "identity.membership.changed", nextId);
+            checkIdentityRequest();
+            return {
+                id: nextId,
+                userId,
+                tenantId,
+                roleId: selected.customRoleId ?? selected.portal,
+                portal: selected.portal,
+                active: input.active,
+                version: input.expectedVersion + 1,
+            };
+        });
+    }
+    async removeMembership(actor, id, expectedVersion) {
+        this.manage(actor);
+        if (!Number.isInteger(expectedVersion) || Number(expectedVersion) < 0)
+            throw new IdentityError(422, "Provide the current membership version.");
+        const [userId, tenantId, portal, extra] = id.split("~");
+        if (!userId || !tenantId || !portal || extra)
+            throw new IdentityError(404, "Membership not found.");
+        this.scope(actor, tenantId);
+        if (actor.portal !== "super-admin" && portal !== "user")
+            throw new IdentityError(403, "Only super administrators can change privileged memberships.");
+        await this.db.transaction().execute(async (trx) => {
+            checkIdentityRequest();
+            const current = await trx
+                .selectFrom("identity_memberships")
+                .select(["custom_role_id", "version"])
+                .where("user_id", "=", userId)
+                .where("tenant_id", "=", tenantId)
+                .where("role_id", "=", portal)
+                .executeTakeFirst();
+            if (!current ||
+                (current.custom_role_id &&
+                    !(await trx
+                        .selectFrom("identity_custom_roles")
+                        .select("id")
+                        .where("id", "=", current.custom_role_id)
+                        .where("app_id", "=", actor.appId)
+                        .executeTakeFirst())))
+                throw new IdentityError(404, "Membership not found.");
+            if (Number(current.version) !== expectedVersion)
+                throw new IdentityError(409, "This record changed. Reload before saving.");
+            await protectAdministrators(trx, userId, tenantId, portal);
+            await trx
+                .deleteFrom("identity_memberships")
+                .where("user_id", "=", userId)
+                .where("tenant_id", "=", tenantId)
+                .where("role_id", "=", portal)
+                .execute();
+            await trx
+                .deleteFrom("identity_sessions")
+                .where("app_id", "=", actor.appId)
+                .where("user_id", "=", userId)
+                .where("tenant_id", "=", tenantId)
+                .where("portal", "=", portal)
+                .execute();
+            await this.audit(trx, actor, tenantId, "identity.membership.removed", id);
+            checkIdentityRequest();
+        });
+    }
+    manage(actor) {
+        if (actor.portal === "user" ||
+            !actor.permissions.includes("identity.manage"))
+            throw new IdentityError(403, "Access denied.");
+    }
+    scope(actor, tenantId) {
+        if (actor.portal !== "super-admin" && tenantId !== actor.tenant.id)
+            throw new IdentityError(403, "Access denied.");
+    }
+    async permissions(trx, ids, appId) {
+        await validateDeclaredPermissions(trx, appId, "user", ids);
+        if (!ids.includes("desk.user"))
+            throw new IdentityError(422, "Keep the user desk permission.");
+        if (ids.some((id) => id === "identity.manage" ||
+            (id.startsWith("desk.") && id !== "desk.user")))
+            throw new IdentityError(403, "Custom user roles cannot grant administration access.");
+        const known = await trx
+            .selectFrom("identity_permissions")
+            .select("id")
+            .execute();
+        if (ids.some((id) => !known.some((row) => row.id === id)))
+            throw new IdentityError(422, "Unknown permission.");
+    }
+    async uniqueName(trx, appId, tenantId, name, exceptId = "") {
+        if (await trx
+            .selectFrom("identity_custom_roles")
+            .select("id")
+            .where("app_id", "=", appId)
+            .where("tenant_id", "=", tenantId)
+            .where("name", "=", name)
+            .where("id", "!=", exceptId)
+            .executeTakeFirst())
+            throw new IdentityError(409, "A role with this name already exists.");
+    }
+    async replacePermissions(trx, id, permissions) {
+        await trx
+            .deleteFrom("identity_custom_role_permissions")
+            .where("role_id", "=", id)
+            .execute();
+        for (const permission of new Set(permissions))
+            await trx
+                .insertInto("identity_custom_role_permissions")
+                .values({ role_id: id, permission_id: permission })
+                .execute();
+    }
+    async audit(trx, actor, tenantId, action, resourceId) {
+        await trx
+            .insertInto("identity_audit_events")
+            .values({
+            id: randomUUID(),
+            app_id: actor.appId,
+            actor_id: actor.user.id,
+            tenant_id: tenantId,
+            action,
+            resource_id: resourceId,
+            created_at: new Date().toISOString(),
+        })
+            .execute();
+    }
+}

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

@@ -0,0 +1,22 @@
+import type { Portal } from "./identity.types.js";
+export declare const identityRoutes: readonly [{
+    readonly method: "POST";
+    readonly path: "sessions";
+    readonly action: "login";
+}, {
+    readonly method: "GET";
+    readonly path: "sessions/current";
+    readonly action: "session";
+}, {
+    readonly method: "DELETE";
+    readonly path: "sessions/current";
+    readonly action: "logout";
+}, {
+    readonly method: "PATCH";
+    readonly path: "password";
+    readonly action: "password";
+}];
+export declare const portalRoutes: Record<Portal, {
+    login: string;
+    desk: string;
+}>;

package/dist/modules/identity/identity.routes.js

@@ -0,0 +1,11 @@
+export const identityRoutes = [
+    { method: "POST", path: "sessions", action: "login" },
+    { method: "GET", path: "sessions/current", action: "session" },
+    { method: "DELETE", path: "sessions/current", action: "logout" },
+    { method: "PATCH", path: "password", action: "password" },
+];
+export const portalRoutes = {
+    user: { login: "/login", desk: "/desk" },
+    admin: { login: "/admin/login", desk: "/admin/desk" },
+    "super-admin": { login: "/sa/login", desk: "/sa/desk" },
+};

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

@@ -0,0 +1,27 @@
+import { z } from "zod";
+export declare const portalSchema: z.ZodEnum<{
+    admin: "admin";
+    "super-admin": "super-admin";
+    user: "user";
+}>;
+export declare const identityKeySchema: z.ZodString;
+export declare const loginSchema: z.ZodObject<{
+    email: z.ZodPipe<z.ZodEmail, z.ZodTransform<string, string>>;
+    password: z.ZodString;
+    tenantId: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const passwordSchema: z.ZodObject<{
+    currentPassword: z.ZodString;
+    password: z.ZodString;
+}, z.core.$strict>;
+export declare const accountSchema: z.ZodObject<{
+    email: z.ZodPipe<z.ZodEmail, z.ZodTransform<string, string>>;
+    name: z.ZodString;
+    password: z.ZodString;
+    portal: z.ZodEnum<{
+        admin: "admin";
+        "super-admin": "super-admin";
+        user: "user";
+    }>;
+    tenantId: z.ZodString;
+}, z.core.$strict>;

package/dist/modules/identity/identity.schema.js

@@ -0,0 +1,34 @@
+import { z } from "zod";
+export const portalSchema = z.enum(["user", "admin", "super-admin"]);
+export const identityKeySchema = z
+    .string()
+    .regex(/^[a-zA-Z0-9._-]{1,100}$/)
+    .refine((value) => !/^\.+$/.test(value), "Use an identifier with a letter or number.");
+export const loginSchema = z
+    .object({
+    email: z
+        .email()
+        .max(254)
+        .transform((value) => value.trim().toLowerCase()),
+    password: z.string().min(1).max(256),
+    tenantId: identityKeySchema.optional(),
+})
+    .strict();
+export const passwordSchema = z
+    .object({
+    currentPassword: z.string().min(1).max(256),
+    password: z.string().min(12).max(256),
+})
+    .strict();
+export const accountSchema = z
+    .object({
+    email: z
+        .email()
+        .max(254)
+        .transform((value) => value.toLowerCase()),
+    name: z.string().trim().min(1).max(100),
+    password: z.string().min(12).max(256),
+    portal: portalSchema,
+    tenantId: identityKeySchema,
+})
+    .strict();

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

@@ -0,0 +1,3 @@
+import type { Kysely } from "kysely";
+import type { IdentitySchema } from "./identity.types.js";
+export declare function seedIdentity(db: Kysely<IdentitySchema>, env: NodeJS.ProcessEnv): Promise<void>;

package/dist/modules/identity/identity.seed.js

@@ -0,0 +1,81 @@
+import { randomUUID } from "node:crypto";
+import { accountSchema } from "./identity.schema.js";
+import { hashPassword } from "./identity.password.js";
+export async function seedIdentity(db, env) {
+    const tenantId = env.IDENTITY_TENANT_ID ?? "default";
+    const accounts = ["user", "admin", "super-admin"].flatMap((portal) => {
+        const prefix = `IDENTITY_SEED_${portal.toUpperCase().replace("-", "_")}`;
+        const email = env[`${prefix}_EMAIL`];
+        const password = env[`${prefix}_PASSWORD`];
+        if (!email && !password)
+            return [];
+        return [
+            accountSchema.parse({
+                email,
+                password,
+                name: env[`${prefix}_NAME`]?.trim() || portal,
+                portal,
+                tenantId,
+            }),
+        ];
+    });
+    await db.transaction().execute(async (trx) => {
+        await trx
+            .insertInto("identity_tenants")
+            .values({
+            id: tenantId,
+            name: env.IDENTITY_TENANT_NAME ?? "Default organization",
+            active: 1,
+        })
+            .onConflict((c) => c.column("id").doNothing())
+            .execute();
+        for (const portal of ["user", "admin", "super-admin"]) {
+            await trx
+                .insertInto("identity_roles")
+                .values({ id: portal })
+                .onConflict((c) => c.column("id").doNothing())
+                .execute();
+            for (const permission of [
+                `desk.${portal}`,
+                "identity.self",
+                "identity.password",
+                ...(portal === "user" ? [] : ["identity.manage"]),
+            ]) {
+                await trx
+                    .insertInto("identity_permissions")
+                    .values({ id: permission })
+                    .onConflict((c) => c.column("id").doNothing())
+                    .execute();
+                await trx
+                    .insertInto("identity_role_permissions")
+                    .values({ role_id: portal, permission_id: permission })
+                    .onConflict((c) => c.columns(["role_id", "permission_id"]).doNothing())
+                    .execute();
+            }
+        }
+        for (const account of accounts) {
+            const existing = await trx
+                .selectFrom("identity_users")
+                .select("id")
+                .where("email", "=", account.email)
+                .executeTakeFirst();
+            if (existing)
+                continue;
+            const id = randomUUID();
+            await trx
+                .insertInto("identity_users")
+                .values({
+                id,
+                email: account.email,
+                name: account.name,
+                password_hash: await hashPassword(account.password),
+                active: 1,
+            })
+                .execute();
+            await trx
+                .insertInto("identity_memberships")
+                .values({ user_id: id, tenant_id: tenantId, role_id: account.portal })
+                .execute();
+        }
+    });
+}

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

@@ -0,0 +1,32 @@
+import { IdentityRepository } from "./identity.repository.js";
+import type { IdentityConfig, Portal, Principal } from "./identity.types.js";
+import type { z } from "zod";
+import type { loginSchema, passwordSchema } from "./identity.schema.js";
+export declare class IdentityService {
+    private readonly repository;
+    private readonly config;
+    private readonly dummyHash;
+    constructor(repository: IdentityRepository, config: IdentityConfig);
+    login(portal: Portal, input: z.infer<typeof loginSchema>, address: string, previous?: string): Promise<{
+        token: string;
+        sessionSeconds: number;
+        principal: {
+            user: {
+                id: string;
+                email: string;
+                name: string;
+            };
+            tenant: {
+                id: string;
+                name: string;
+            };
+            permissions: string[];
+            appId: string;
+            portal: Portal;
+        };
+    }>;
+    authenticate(portal: Portal, token?: string): Promise<Principal>;
+    requirePermission(principal: Principal, permission: string): void;
+    logout(portal: Portal, token?: string): Promise<void>;
+    changePassword(principal: Principal, input: z.infer<typeof passwordSchema>): Promise<void>;
+}

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

@@ -0,0 +1,83 @@
+import { randomBytes } from "node:crypto";
+import { digest, hashPassword, verifyPassword } from "./identity.password.js";
+import { IdentityError } from "./identity.error.js";
+export class IdentityService {
+    repository;
+    config;
+    dummyHash = hashPassword(randomBytes(32).toString("hex"));
+    constructor(repository, config) {
+        this.repository = repository;
+        this.config = config;
+    }
+    async login(portal, input, address, previous) {
+        const key = digest(`${this.config.appId}:${portal}:${address}:${input.email}`);
+        const ipKey = digest(`${this.config.appId}:ip:${address}`);
+        if ((await this.repository.throttle(ipKey)) > 100 ||
+            (await this.repository.throttle(key)) > 10)
+            throw new IdentityError(429, "Too many sign-in attempts. Try again later.");
+        const user = await this.repository.user(input.email);
+        const valid = await verifyPassword(input.password, user?.password_hash ?? (await this.dummyHash));
+        const tenantId = this.config.mode === "single-client"
+            ? this.config.tenantId
+            : input.tenantId;
+        if (!valid ||
+            !user ||
+            !Number(user.active) ||
+            !tenantId ||
+            (this.config.mode === "single-client" &&
+                input.tenantId &&
+                input.tenantId !== tenantId))
+            throw new IdentityError(401, "Invalid credentials or portal access.");
+        const principal = await this.repository.principal(user.id, tenantId, portal, this.config.appId);
+        if (!principal?.permissions.includes(`desk.${portal}`))
+            throw new IdentityError(401, "Invalid credentials or portal access.");
+        const token = randomBytes(32).toString("base64url");
+        const sessionSeconds = await this.repository.sessionSeconds(this.config.appId, this.config.sessionSeconds);
+        const created = await this.repository.createSession({
+            token_hash: digest(token),
+            user_id: user.id,
+            tenant_id: tenantId,
+            app_id: this.config.appId,
+            portal,
+            expires_at: new Date(Date.now() + sessionSeconds * 1000).toISOString(),
+        }, user.password_hash, previous ? digest(previous) : undefined);
+        if (!created)
+            throw new IdentityError(401, "Invalid credentials or portal access.");
+        await this.repository.clearThrottle(key);
+        return {
+            token,
+            sessionSeconds,
+            principal: { ...principal, appId: this.config.appId, portal },
+        };
+    }
+    async authenticate(portal, token) {
+        if (!token || !/^[A-Za-z0-9_-]{43}$/.test(token))
+            throw new IdentityError(401, "Sign in to continue.");
+        const session = await this.repository.session(digest(token), this.config.appId, portal, new Date().toISOString());
+        if (!session ||
+            (this.config.mode === "single-client" &&
+                session.tenant_id !== this.config.tenantId))
+            throw new IdentityError(401, "Sign in to continue.");
+        const principal = await this.repository.principal(session.user_id, session.tenant_id, portal, this.config.appId);
+        if (!principal)
+            throw new IdentityError(401, "Sign in to continue.");
+        return { ...principal, appId: this.config.appId, portal };
+    }
+    requirePermission(principal, permission) {
+        if (!principal.permissions.includes(permission))
+            throw new IdentityError(403, "Access denied.");
+    }
+    async logout(portal, token) {
+        if (token)
+            await this.repository.revoke(digest(token), this.config.appId, portal);
+    }
+    async changePassword(principal, input) {
+        this.requirePermission(principal, "identity.password");
+        const user = await this.repository.user(principal.user.email);
+        if (!user ||
+            !(await verifyPassword(input.currentPassword, user.password_hash)))
+            throw new IdentityError(422, "Current password is incorrect.");
+        if (!(await this.repository.changePassword(user.id, user.password_hash, await hashPassword(input.password))))
+            throw new IdentityError(409, "Account changed. Sign in again.");
+    }
+}