@devxcrew/platform 0.1.2

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

@@ -0,0 +1,395 @@
+import { randomBytes, randomUUID } from "node:crypto";
+import { digest, hashPassword } from "./identity.password.js";
+import { IdentityError } from "./identity.error.js";
+import { IdentityRepository } from "./identity.repository.js";
+import { checkIdentityRequest } from "./identity.request-context.js";
+import { invitationSchema, recoverySchema, tokenCompletionSchema, } from "./identity.lifecycle-schema.js";
+export class IdentityLifecycleService {
+    db;
+    config;
+    delivery;
+    constructor(db, config, delivery) {
+        this.db = db;
+        this.config = config;
+        this.delivery = delivery;
+    }
+    async invite(actor, raw) {
+        if (actor.portal === "user" ||
+            !actor.permissions.includes("identity.manage"))
+            throw new IdentityError(403, "Access denied.");
+        const input = invitationSchema.parse(raw);
+        const tenantId = input.tenantId ?? actor.tenant.id;
+        if (actor.portal !== "super-admin" &&
+            (tenantId !== actor.tenant.id || input.roleId !== "user"))
+            throw new IdentityError(403, "Access denied.");
+        this.requireDelivery();
+        if ((await new IdentityRepository(this.db).throttle(digest(`${actor.appId}:invitation:${actor.user.id}`))) > 20)
+            throw new IdentityError(429, "Too many invitations. Try again later.");
+        const tenant = await this.db
+            .selectFrom("identity_tenants")
+            .select("id")
+            .where("id", "=", tenantId)
+            .where("active", "=", 1)
+            .executeTakeFirst();
+        if (!tenant)
+            throw new IdentityError(422, "Organization is inactive or unavailable.");
+        if (await this.db
+            .selectFrom("identity_users")
+            .select("id")
+            .where("email", "=", input.email)
+            .executeTakeFirst())
+            throw new IdentityError(409, "This account already exists. Manage its membership instead.");
+        const row = await this.issue("invitation", input.email, input.name, input.roleId, tenantId, null, actor.user.id);
+        return this.present(row);
+    }
+    async requestRecovery(portal, raw, address) {
+        const input = recoverySchema
+            .refine((value) => this.config.mode !== "multi-tenant" || Boolean(value.tenantId), { path: ["tenantId"], message: "Enter an organization ID." })
+            .parse(raw);
+        this.requireDelivery();
+        const repository = new IdentityRepository(this.db);
+        if ((await repository.throttle(digest(`${this.config.appId}:recovery-ip:${address}`))) > 20)
+            throw new IdentityError(429, "Too many recovery requests. Try again later.");
+        if ((await repository.throttle(digest(`${this.config.appId}:recovery:${address}:${input.email}`))) > 5)
+            throw new IdentityError(429, "Too many recovery requests. Try again later.");
+        const tenantId = this.config.mode === "single-client"
+            ? this.config.tenantId
+            : input.tenantId;
+        const user = await repository.user(input.email);
+        const principal = user?.active && tenantId
+            ? await repository.principal(user.id, tenantId, portal, this.config.appId)
+            : null;
+        if (user?.active &&
+            tenantId &&
+            principal?.permissions.includes("identity.password")) {
+            await this.db
+                .updateTable("identity_tokens")
+                .set({ consumed_at: new Date().toISOString() })
+                .where("app_id", "=", this.config.appId)
+                .where("kind", "=", "recovery")
+                .where("user_id", "=", user.id)
+                .execute();
+            await this.issue("recovery", user.email, user.name, portal, tenantId, user.id);
+        }
+        return {
+            message: "If this account can recover access, an email will arrive.",
+        };
+    }
+    async complete(portal, kind, raw, address) {
+        const input = tokenCompletionSchema.parse(raw);
+        const repository = new IdentityRepository(this.db);
+        if ((await repository.throttle(digest(`${this.config.appId}:complete:${address}`))) > 10)
+            throw new IdentityError(429, "Too many account requests. Try again later.");
+        const available = await this.db
+            .selectFrom("identity_tokens")
+            .select("id")
+            .where("token_hash", "=", digest(input.token))
+            .where("app_id", "=", this.config.appId)
+            .where("kind", "=", kind)
+            .where("role_id", "=", portal)
+            .where("delivered", "=", 1)
+            .where("consumed_at", "is", null)
+            .where("expires_at", ">", new Date().toISOString())
+            .executeTakeFirst();
+        if (!available)
+            throw new IdentityError(422, "This link is invalid or expired.");
+        const passwordHash = await hashPassword(input.password);
+        checkIdentityRequest();
+        return this.db.transaction().execute(async (trx) => {
+            checkIdentityRequest();
+            const token = await trx
+                .selectFrom("identity_tokens")
+                .selectAll()
+                .where("token_hash", "=", digest(input.token))
+                .where("app_id", "=", this.config.appId)
+                .where("kind", "=", kind)
+                .where("role_id", "=", portal)
+                .where("delivered", "=", 1)
+                .where("consumed_at", "is", null)
+                .where("expires_at", ">", new Date().toISOString())
+                .executeTakeFirst();
+            if (!token ||
+                (this.config.mode === "single-client" &&
+                    token.tenant_id !== this.config.tenantId))
+                throw new IdentityError(422, "This link is invalid or expired.");
+            const activeTenant = await trx
+                .selectFrom("identity_tenants")
+                .select("id")
+                .where("id", "=", token.tenant_id)
+                .where("active", "=", 1)
+                .executeTakeFirst();
+            if (!activeTenant)
+                throw new IdentityError(422, "This link is invalid or expired.");
+            const claimed = await trx
+                .updateTable("identity_tokens")
+                .set({ consumed_at: new Date().toISOString() })
+                .where("id", "=", token.id)
+                .where("consumed_at", "is", null)
+                .executeTakeFirst();
+            if (claimed.numUpdatedRows !== 1n)
+                throw new IdentityError(409, "This link was already used.");
+            const userId = token.user_id ?? randomUUID();
+            if (kind === "invitation") {
+                if (await trx
+                    .selectFrom("identity_users")
+                    .select("id")
+                    .where("email", "=", token.email)
+                    .executeTakeFirst())
+                    throw new IdentityError(409, "Account already exists. Request a new invitation.");
+                await trx
+                    .insertInto("identity_users")
+                    .values({
+                    id: userId,
+                    email: token.email,
+                    name: token.name,
+                    password_hash: passwordHash,
+                    active: 1,
+                })
+                    .execute();
+                await trx
+                    .insertInto("identity_memberships")
+                    .values({
+                    user_id: userId,
+                    tenant_id: token.tenant_id,
+                    role_id: token.role_id,
+                })
+                    .execute();
+            }
+            else {
+                const principal = await new IdentityRepository(trx).principal(userId, token.tenant_id, portal, this.config.appId);
+                if (!principal?.permissions.includes("identity.password"))
+                    throw new IdentityError(422, "This link is invalid or expired.");
+                await trx
+                    .updateTable("identity_users")
+                    .set({ password_hash: passwordHash })
+                    .where("id", "=", userId)
+                    .execute();
+                await trx
+                    .deleteFrom("identity_sessions")
+                    .where("user_id", "=", userId)
+                    .execute();
+                await trx
+                    .updateTable("identity_tokens")
+                    .set({ consumed_at: new Date().toISOString() })
+                    .where("user_id", "=", userId)
+                    .where("kind", "=", "recovery")
+                    .execute();
+            }
+            await trx
+                .insertInto("identity_audit_events")
+                .values({
+                id: randomUUID(),
+                app_id: this.config.appId,
+                actor_id: userId,
+                tenant_id: token.tenant_id,
+                action: `identity.${kind}.completed`,
+                resource_id: token.id,
+                created_at: new Date().toISOString(),
+            })
+                .execute();
+            checkIdentityRequest();
+            return { message: "Account access updated. Sign in to continue." };
+        });
+    }
+    async list(actor, query) {
+        if (actor.portal === "user" ||
+            !actor.permissions.includes("identity.manage"))
+            throw new IdentityError(403, "Access denied.");
+        let select = this.db
+            .selectFrom("identity_tokens")
+            .where("app_id", "=", actor.appId)
+            .where("kind", "=", "invitation");
+        if (actor.portal !== "super-admin")
+            select = select.where("tenant_id", "=", actor.tenant.id);
+        if (query.search)
+            select = select.where((eb) => eb.or([
+                eb("email", "like", `%${query.search}%`),
+                eb("name", "like", `%${query.search}%`),
+            ]));
+        const count = await select
+            .select((eb) => eb.fn.countAll().as("total"))
+            .executeTakeFirstOrThrow();
+        const rows = await select
+            .selectAll()
+            .orderBy(query.sort, query.direction)
+            .orderBy("id", "asc")
+            .limit(query.perPage)
+            .offset((query.page - 1) * query.perPage)
+            .execute();
+        const total = Number(count.total);
+        return {
+            data: rows.map((row) => this.present(row)),
+            meta: {
+                page: query.page,
+                perPage: query.perPage,
+                total,
+                lastPage: Math.max(1, Math.ceil(total / query.perPage)),
+            },
+        };
+    }
+    async show(actor, id) {
+        if (actor.portal === "user" ||
+            !actor.permissions.includes("identity.manage"))
+            throw new IdentityError(403, "Access denied.");
+        let query = this.db
+            .selectFrom("identity_tokens")
+            .selectAll()
+            .where("id", "=", id)
+            .where("app_id", "=", actor.appId)
+            .where("kind", "=", "invitation");
+        if (actor.portal !== "super-admin")
+            query = query.where("tenant_id", "=", actor.tenant.id);
+        const row = await query.executeTakeFirst();
+        if (!row)
+            throw new IdentityError(404, "Invitation not found.");
+        return this.present(row);
+    }
+    async resend(actor, id) {
+        const old = await this.show(actor, id);
+        if (old.status === "closed")
+            throw new IdentityError(409, "This invitation is closed.");
+        const result = await this.invite(actor, {
+            email: old.email,
+            name: old.name,
+            roleId: old.roleId,
+            tenantId: old.tenantId,
+        });
+        await this.revoke(actor, id);
+        return result;
+    }
+    async revoke(actor, id) {
+        if (actor.portal === "user" ||
+            !actor.permissions.includes("identity.manage"))
+            throw new IdentityError(403, "Access denied.");
+        const token = await this.db
+            .selectFrom("identity_tokens")
+            .select("tenant_id")
+            .where("id", "=", id)
+            .where("app_id", "=", actor.appId)
+            .where("kind", "=", "invitation")
+            .executeTakeFirst();
+        if (!token ||
+            (actor.portal !== "super-admin" && token.tenant_id !== actor.tenant.id))
+            throw new IdentityError(404, "Invitation not found.");
+        await this.db.transaction().execute(async (trx) => {
+            checkIdentityRequest();
+            let query = trx
+                .updateTable("identity_tokens")
+                .set({ consumed_at: new Date().toISOString() })
+                .where("id", "=", id)
+                .where("app_id", "=", actor.appId)
+                .where("kind", "=", "invitation");
+            if (actor.portal !== "super-admin")
+                query = query.where("tenant_id", "=", actor.tenant.id);
+            if ((await query.executeTakeFirst()).numUpdatedRows !== 1n)
+                throw new IdentityError(404, "Invitation not found.");
+            await trx
+                .insertInto("identity_audit_events")
+                .values({
+                id: randomUUID(),
+                app_id: actor.appId,
+                actor_id: actor.user.id,
+                tenant_id: token.tenant_id,
+                action: "identity.invitation.revoked",
+                resource_id: id,
+                created_at: new Date().toISOString(),
+            })
+                .execute();
+            checkIdentityRequest();
+        });
+    }
+    requireDelivery() {
+        if (!this.delivery)
+            throw new IdentityError(503, "Account email is unavailable. Contact your administrator.");
+    }
+    async issue(kind, email, name, role, tenantId, userId, actorId = userId ?? "system") {
+        const token = randomBytes(32).toString("base64url");
+        const row = {
+            id: randomUUID(),
+            token_hash: digest(token),
+            app_id: this.config.appId,
+            tenant_id: tenantId,
+            kind,
+            email,
+            name,
+            role_id: role,
+            user_id: userId,
+            expires_at: new Date(Date.now() + (kind === "recovery" ? 1800 : 86400) * 1000).toISOString(),
+            consumed_at: null,
+            delivered: 0,
+        };
+        checkIdentityRequest();
+        await this.db.insertInto("identity_tokens").values(row).execute();
+        const path = role === "user" ? "" : role === "admin" ? "/admin" : "/sa";
+        const link = `${this.config.origin}${path}/${kind === "invitation" ? "accept-invitation" : "reset-password"}#token=${token}`;
+        try {
+            const delivered = await this.delivery.send({
+                to: email,
+                subject: kind === "invitation"
+                    ? "Account invitation"
+                    : "Recover account access",
+                text: `${name}, open this link to ${kind === "invitation" ? "set up your account" : "reset your password"}: ${link}\nThis link expires at ${row.expires_at}.`,
+            });
+            if (!delivered.messageId)
+                throw new Error("Missing delivery receipt.");
+            checkIdentityRequest();
+            await this.db.transaction().execute(async (trx) => {
+                await trx
+                    .updateTable("identity_tokens")
+                    .set({ delivered: 1 })
+                    .where("id", "=", row.id)
+                    .execute();
+                await trx
+                    .insertInto("identity_audit_events")
+                    .values({
+                    id: randomUUID(),
+                    app_id: this.config.appId,
+                    actor_id: actorId,
+                    tenant_id: tenantId,
+                    action: `identity.${kind}.issued`,
+                    resource_id: row.id,
+                    created_at: new Date().toISOString(),
+                })
+                    .execute();
+                checkIdentityRequest();
+            });
+            return { ...row, delivered: 1 };
+        }
+        catch {
+            await this.db
+                .deleteFrom("identity_tokens")
+                .where("id", "=", row.id)
+                .execute();
+            throw new IdentityError(503, "Account email is unavailable. Contact your administrator.");
+        }
+    }
+    present(row) {
+        return {
+            id: row.id,
+            email: row.email,
+            name: row.name,
+            roleId: row.role_id,
+            tenantId: row.tenant_id,
+            expiresAt: row.expires_at,
+            status: row.consumed_at
+                ? "closed"
+                : row.expires_at <= new Date().toISOString()
+                    ? "expired"
+                    : "pending",
+        };
+    }
+    async audit(actor, action, resourceId, tenantId = actor.tenant.id) {
+        await this.db
+            .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.membership-policy.d.ts

@@ -0,0 +1,3 @@
+import type { Transaction } from "kysely";
+import type { IdentitySchema } from "./identity.types.js";
+export declare function protectAdministrators(trx: Transaction<IdentitySchema>, userId: string, tenantId?: string, roleId?: string): Promise<void>;

package/dist/modules/identity/identity.membership-policy.js

@@ -0,0 +1,27 @@
+import { IdentityError } from "./identity.error.js";
+export async function protectAdministrators(trx, userId, tenantId, roleId) {
+    let query = trx
+        .selectFrom("identity_memberships")
+        .selectAll()
+        .where("user_id", "=", userId)
+        .where("active", "=", 1)
+        .where("role_id", "in", ["admin", "super-admin"]);
+    if (tenantId)
+        query = query.where("tenant_id", "=", tenantId);
+    if (roleId)
+        query = query.where("role_id", "=", roleId);
+    for (const member of await query.execute()) {
+        const peer = await trx
+            .selectFrom("identity_memberships as m")
+            .innerJoin("identity_users as u", "u.id", "m.user_id")
+            .select("u.id")
+            .where("m.tenant_id", "=", member.tenant_id)
+            .where("m.role_id", "=", member.role_id)
+            .where("m.active", "=", 1)
+            .where("u.active", "=", 1)
+            .where("u.id", "!=", userId)
+            .executeTakeFirst();
+        if (!peer)
+            throw new IdentityError(409, "Keep at least one active administrator for this role and organization.");
+    }
+}

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

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

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

@@ -0,0 +1,79 @@
+export const identityMigration = {
+    async up(db) {
+        await db.schema
+            .createTable("identity_users")
+            .addColumn("id", "text", (c) => c.primaryKey())
+            .addColumn("email", "text", (c) => c.notNull().unique())
+            .addColumn("name", "text", (c) => c.notNull())
+            .addColumn("password_hash", "text", (c) => c.notNull())
+            .addColumn("active", "integer", (c) => c.notNull().defaultTo(1))
+            .execute();
+        await db.schema
+            .createTable("identity_tenants")
+            .addColumn("id", "text", (c) => c.primaryKey())
+            .addColumn("name", "text", (c) => c.notNull())
+            .addColumn("active", "integer", (c) => c.notNull().defaultTo(1))
+            .execute();
+        await db.schema
+            .createTable("identity_roles")
+            .addColumn("id", "text", (c) => c.primaryKey())
+            .execute();
+        await db.schema
+            .createTable("identity_permissions")
+            .addColumn("id", "text", (c) => c.primaryKey())
+            .execute();
+        await db.schema
+            .createTable("identity_role_permissions")
+            .addColumn("role_id", "text", (c) => c.notNull().references("identity_roles.id"))
+            .addColumn("permission_id", "text", (c) => c.notNull().references("identity_permissions.id"))
+            .addPrimaryKeyConstraint("identity_role_permission_pk", [
+            "role_id",
+            "permission_id",
+        ])
+            .execute();
+        await db.schema
+            .createTable("identity_memberships")
+            .addColumn("user_id", "text", (c) => c.notNull().references("identity_users.id").onDelete("cascade"))
+            .addColumn("tenant_id", "text", (c) => c.notNull().references("identity_tenants.id").onDelete("cascade"))
+            .addColumn("role_id", "text", (c) => c.notNull().references("identity_roles.id"))
+            .addPrimaryKeyConstraint("identity_membership_pk", [
+            "user_id",
+            "tenant_id",
+            "role_id",
+        ])
+            .execute();
+        await db.schema
+            .createTable("identity_sessions")
+            .addColumn("token_hash", "text", (c) => c.primaryKey())
+            .addColumn("user_id", "text", (c) => c.notNull().references("identity_users.id").onDelete("cascade"))
+            .addColumn("tenant_id", "text", (c) => c.notNull().references("identity_tenants.id").onDelete("cascade"))
+            .addColumn("app_id", "text", (c) => c.notNull())
+            .addColumn("portal", "text", (c) => c.notNull())
+            .addColumn("expires_at", "text", (c) => c.notNull())
+            .execute();
+        await db.schema
+            .createIndex("identity_sessions_expiry")
+            .on("identity_sessions")
+            .column("expires_at")
+            .execute();
+        await db.schema
+            .createTable("identity_throttles")
+            .addColumn("key", "text", (c) => c.primaryKey())
+            .addColumn("attempts", "integer", (c) => c.notNull())
+            .addColumn("expires_at", "text", (c) => c.notNull())
+            .execute();
+    },
+    async down(db) {
+        for (const table of [
+            "identity_throttles",
+            "identity_sessions",
+            "identity_memberships",
+            "identity_role_permissions",
+            "identity_permissions",
+            "identity_roles",
+            "identity_tenants",
+            "identity_users",
+        ])
+            await db.schema.dropTable(table).execute();
+    },
+};

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

@@ -0,0 +1,3 @@
+export declare function hashPassword(password: string): Promise<string>;
+export declare function verifyPassword(password: string, encoded: string): Promise<boolean>;
+export declare function digest(value: string): string;

package/dist/modules/identity/identity.password.js

@@ -0,0 +1,21 @@
+import { randomBytes, scrypt, timingSafeEqual, createHash } from "node:crypto";
+const options = { N: 32768, r: 8, p: 3, maxmem: 64 * 1024 * 1024 };
+export async function hashPassword(password) {
+    const salt = randomBytes(16).toString("hex");
+    const key = await derive(password, salt);
+    return `scrypt$${salt}$${key.toString("hex")}`;
+}
+export async function verifyPassword(password, encoded) {
+    const [algorithm, salt, hex] = encoded.split("$");
+    if (algorithm !== "scrypt" ||
+        !/^[a-f0-9]{32}$/.test(salt ?? "") ||
+        !/^[a-f0-9]{128}$/.test(hex ?? ""))
+        return false;
+    return timingSafeEqual(await derive(password, salt), Buffer.from(hex, "hex"));
+}
+export function digest(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+function derive(password, salt) {
+    return new Promise((resolve, reject) => scrypt(password, salt, 64, options, (error, key) => error ? reject(error) : resolve(key)));
+}

package/dist/modules/identity/identity.permission-declarations-migration.d.ts

@@ -0,0 +1,5 @@
+import type { Kysely } from "kysely";
+export declare const identityPermissionDeclarationsMigration: {
+    up(db: Kysely<any>): Promise<void>;
+    down(db: Kysely<any>): Promise<void>;
+};

package/dist/modules/identity/identity.permission-declarations-migration.js

@@ -0,0 +1,15 @@
+export const identityPermissionDeclarationsMigration = {
+    async up(db) {
+        await db.schema.createTable("identity_permission_declarations")
+            .addColumn("permission_id", "text", (column) => column.primaryKey().references("identity_permissions.id"))
+            .addColumn("app_id", "text", (column) => column.notNull())
+            .addColumn("owner", "text", (column) => column.notNull())
+            .addColumn("portals", "text", (column) => column.notNull()).execute();
+    },
+    async down(db) {
+        const declared = await db.selectFrom("identity_permission_declarations").select("permission_id").executeTakeFirst();
+        if (declared)
+            throw new Error("Restore a compatible snapshot before removing permission ownership restrictions.");
+        await db.schema.dropTable("identity_permission_declarations").execute();
+    },
+};

package/dist/modules/identity/identity.permission-declarations.d.ts

@@ -0,0 +1,23 @@
+import { z } from "zod";
+import type { Kysely, Transaction } from "kysely";
+import type { IdentitySchema, Portal } from "./identity.types.js";
+declare const declarationSchema: z.ZodObject<{
+    owner: z.ZodString;
+    permissions: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        portals: z.ZodArray<z.ZodEnum<{
+            admin: "admin";
+            "super-admin": "super-admin";
+            user: "user";
+        }>>;
+        label: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type IdentityPermissionDeclaration = z.input<typeof declarationSchema>;
+export declare function registerIdentityPermissions(db: Kysely<IdentitySchema>, appId: string, raw: unknown): Promise<{
+    owner: string;
+    permissionIds: string[];
+}>;
+export declare function validateDeclaredPermissions(db: Kysely<IdentitySchema> | Transaction<IdentitySchema>, appId: string, portal: Portal, ids: string[]): Promise<void>;
+export declare function filterDeclaredPermissions(db: Kysely<IdentitySchema>, appId: string, portal: Portal, ids: string[]): Promise<string[]>;
+export {};

package/dist/modules/identity/identity.permission-declarations.js

@@ -0,0 +1,57 @@
+import { z } from "zod";
+import { IdentityError } from "./identity.error.js";
+import { portalSchema } from "./identity.schema.js";
+const declarationSchema = z.object({
+    owner: z.string().regex(/^[a-z][a-z0-9-]{0,63}$/).refine((value) => !["identity", "desk"].includes(value)),
+    permissions: z.array(z.object({
+        id: z.string().regex(/^[a-z][a-z0-9-]*(?:\.[a-z][a-z0-9-]*){2,8}$/).max(250),
+        portals: z.array(portalSchema).min(1).max(3),
+        label: z.string().trim().min(1).max(100).regex(/^[^\x00-\x1f\x7f]+$/).optional(),
+    }).strict()).min(1).max(100),
+}).strict();
+export async function registerIdentityPermissions(db, appId, raw) {
+    const declaration = declarationSchema.parse(raw);
+    const ids = new Set();
+    for (const permission of declaration.permissions) {
+        if (!permission.id.startsWith(`${appId}.${declaration.owner}.`) || ids.has(permission.id))
+            throw new IdentityError(422, "Use unique permission IDs in this app and owner namespace.");
+        ids.add(permission.id);
+    }
+    return db.transaction().execute(async (trx) => {
+        for (const permission of declaration.permissions) {
+            const portals = JSON.stringify([...new Set(permission.portals)].sort());
+            const previous = await trx.selectFrom("identity_permission_declarations").selectAll()
+                .where("permission_id", "=", permission.id).executeTakeFirst();
+            if (previous) {
+                if (previous.app_id !== appId || previous.owner !== declaration.owner || previous.portals !== portals)
+                    throw new IdentityError(409, "Permission declaration conflicts with its registered owner or portal policy.");
+                if (permission.label !== undefined && permission.label !== previous.label)
+                    await trx.updateTable("identity_permission_declarations").set({ label: permission.label })
+                        .where("permission_id", "=", permission.id).execute();
+                continue;
+            }
+            if (await trx.selectFrom("identity_permissions").select("id").where("id", "=", permission.id).executeTakeFirst())
+                throw new IdentityError(409, "Permission already exists without this owner declaration.");
+            await trx.insertInto("identity_permissions").values({ id: permission.id }).execute();
+            await trx.insertInto("identity_permission_declarations").values({
+                permission_id: permission.id, app_id: appId, owner: declaration.owner, portals, label: permission.label ?? null,
+            }).execute();
+        }
+        return { owner: declaration.owner, permissionIds: [...ids] };
+    });
+}
+export async function validateDeclaredPermissions(db, appId, portal, ids) {
+    const declarations = await db.selectFrom("identity_permission_declarations").selectAll().execute();
+    for (const id of ids) {
+        const declaration = declarations.find((row) => row.permission_id === id);
+        if (declaration && (declaration.app_id !== appId || !JSON.parse(declaration.portals).includes(portal)))
+            throw new IdentityError(403, "Permission is unavailable in this app or portal.");
+    }
+}
+export async function filterDeclaredPermissions(db, appId, portal, ids) {
+    const declarations = await db.selectFrom("identity_permission_declarations").selectAll().execute();
+    return ids.filter((id) => {
+        const declaration = declarations.find((row) => row.permission_id === id);
+        return !declaration || (declaration.app_id === appId && JSON.parse(declaration.portals).includes(portal));
+    });
+}

package/dist/modules/identity/identity.permission-labels-migration.d.ts

@@ -0,0 +1,5 @@
+import type { Kysely } from "kysely";
+export declare const identityPermissionLabelsMigration: {
+    up(db: Kysely<any>): Promise<void>;
+    down(db: Kysely<any>): Promise<void>;
+};

package/dist/modules/identity/identity.permission-labels-migration.js

@@ -0,0 +1,9 @@
+// Additive migration. Do not rewrite the previously applied declaration schema.
+export const identityPermissionLabelsMigration = {
+    async up(db) {
+        await db.schema.alterTable("identity_permission_declarations").addColumn("label", "text").execute();
+    },
+    async down(db) {
+        await db.schema.alterTable("identity_permission_declarations").dropColumn("label").execute();
+    },
+};