@things-factory/auth-base 10.1.79 → 10.1.106

package/dist-server/utils/access-request-review.d.ts

@@ -0,0 +1,69 @@
+export type AccessRequestState = 'PENDING' | 'GRANTED' | 'DENIED' | 'WITHDRAWN' | 'EXPIRED';
+export type AccessDecisionKind = 'GRANT' | 'DENY';
+export type PrivilegeName = {
+    category: string;
+    privilege: string;
+};
+/** The privilege that lets its holder put people into roles - a role carrying it hands that power on. */
+export declare const ROLE_GRANTING_PRIVILEGE: PrivilegeName;
+/** How long a request waits for a decision (questions Q7). */
+export declare const ACCESS_REQUEST_PENDING_DAYS = 14;
+export interface DecisionFacts {
+    request: {
+        state: AccessRequestState;
+        requesterId: string;
+        category: string;
+        privilege: string;
+        expiresAt?: Date | string | null;
+    } | null;
+    deciderId: string;
+    decision: AccessDecisionKind;
+    reason?: string | null;
+    /** The role chosen to grant - absent when it is not this domain's to assign. */
+    role?: {
+        id: string;
+        name: string;
+        privileges: PrivilegeName[];
+    } | null;
+    /** A role id was named but not found in the domain's scope. */
+    roleNamedButNotAssignable?: boolean;
+    requester: {
+        active: boolean;
+        inDomain: boolean;
+    } | null;
+    /** The requester holds the privilege now - through some other role, since the request was made. */
+    requesterHoldsIt: boolean;
+    /** Every assignable role that grants the privilege, with how many privileges each carries. */
+    candidates: {
+        id: string;
+        name: string;
+        privilegeCount: number;
+    }[];
+    /** The decider's own privileges - to tell them when a role gives what they do not have. */
+    deciderPrivileges: PrivilegeName[];
+    /** Whether the decider is a domain owner - an owner may give anything. */
+    deciderIsOwner: boolean;
+    /** The latest earlier denial of the same requester and privilege. */
+    deniedBefore?: {
+        by: string;
+        at: Date | string;
+        reason?: string | null;
+    } | null;
+    now: Date;
+}
+export interface DecisionIssue {
+    code: string;
+    blocking: boolean;
+    field?: 'request' | 'decision' | 'role' | 'reason';
+    params?: Record<string, string | number | boolean | null>;
+}
+/** A pending request past its time is expired, whatever the column still says. */
+export declare function effectiveState(state: AccessRequestState, expiresAt: Date | string | null | undefined, now: Date): AccessRequestState;
+export declare function expiryFrom(now: Date, days?: number): Date;
+export declare function reviewAccessDecision(facts: DecisionFacts): DecisionIssue[];
+/** The smallest candidate - what the draft card proposes by default. Ties go by name, so the answer is the same every time. */
+export declare function smallestRole<T extends {
+    name: string;
+    privilegeCount: number;
+}>(candidates: T[]): T | undefined;
+export declare const isBlocked: (issues: DecisionIssue[]) => boolean;

package/dist-server/utils/access-request-review.js

@@ -0,0 +1,119 @@
+"use strict";
+/*
+ * The checks an access decision passes - one function, read by the list screen, by the AI 입력 draft card
+ * (its `check`, when the card is made and again when it is pressed) and by `decideAccessRequest` itself
+ * (ADR-0103 decision 4: the card and the screen cannot say different things).
+ *
+ * Pure: the facts are collected by `access-request-facts.ts`; this decides what they mean. A model never
+ * judges a role as risky - this does, the same way every time, and the model only words the result.
+ *
+ * Blocking issues keep the decision from being written. The rest are told to the person deciding.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isBlocked = exports.ACCESS_REQUEST_PENDING_DAYS = exports.ROLE_GRANTING_PRIVILEGE = void 0;
+exports.effectiveState = effectiveState;
+exports.expiryFrom = expiryFrom;
+exports.reviewAccessDecision = reviewAccessDecision;
+exports.smallestRole = smallestRole;
+/** The privilege that lets its holder put people into roles - a role carrying it hands that power on. */
+exports.ROLE_GRANTING_PRIVILEGE = { category: 'user', privilege: 'mutation' };
+/** How long a request waits for a decision (questions Q7). */
+exports.ACCESS_REQUEST_PENDING_DAYS = 14;
+const same = (a, b) => a.category === b.category && a.privilege === b.privilege;
+const nameOf = (p) => `${p.category}:${p.privilege}`;
+/** A pending request past its time is expired, whatever the column still says. */
+function effectiveState(state, expiresAt, now) {
+    if (state !== 'PENDING' || !expiresAt)
+        return state;
+    const at = new Date(expiresAt);
+    return isNaN(at.getTime()) || at.getTime() > now.getTime() ? state : 'EXPIRED';
+}
+function expiryFrom(now, days = exports.ACCESS_REQUEST_PENDING_DAYS) {
+    return new Date(now.getTime() + days * 24 * 60 * 60 * 1000);
+}
+function reviewAccessDecision(facts) {
+    const issues = [];
+    const { request } = facts;
+    if (!request) {
+        return [{ code: 'access-request-not-found', blocking: true, field: 'request' }];
+    }
+    const state = effectiveState(request.state, request.expiresAt, facts.now);
+    if (state !== 'PENDING') {
+        issues.push({ code: 'request-not-pending', blocking: true, field: 'request', params: { state } });
+    }
+    if (request.requesterId === facts.deciderId) {
+        issues.push({ code: 'own-request', blocking: true, field: 'request' });
+    }
+    if (!facts.requester || !facts.requester.inDomain || !facts.requester.active) {
+        issues.push({ code: 'requester-unavailable', blocking: true, field: 'request' });
+    }
+    if (facts.decision === 'DENY') {
+        if (!facts.reason || !facts.reason.trim()) {
+            issues.push({ code: 'deny-needs-reason', blocking: true, field: 'reason' });
+        }
+    }
+    else {
+        issues.push(...grantIssues(facts, { category: request.category, privilege: request.privilege }));
+    }
+    if (facts.deniedBefore) {
+        issues.push({
+            code: 'denied-before',
+            blocking: false,
+            field: 'request',
+            params: { by: facts.deniedBefore.by, at: new Date(facts.deniedBefore.at).toISOString(), reason: facts.deniedBefore.reason ?? '' }
+        });
+    }
+    return issues;
+}
+function grantIssues(facts, asked) {
+    const issues = [];
+    if (facts.requesterHoldsIt) {
+        issues.push({ code: 'already-holds', blocking: true, field: 'request', params: { privilege: nameOf(asked) } });
+    }
+    if (!facts.role) {
+        issues.push({
+            code: facts.roleNamedButNotAssignable ? 'role-not-assignable' : 'role-required',
+            blocking: true,
+            field: 'role'
+        });
+        return issues;
+    }
+    const { role } = facts;
+    if (!role.privileges.some(p => same(p, asked))) {
+        issues.push({ code: 'role-does-not-grant', blocking: true, field: 'role', params: { role: role.name, privilege: nameOf(asked) } });
+        return issues;
+    }
+    const more = role.privileges.filter(p => !same(p, asked));
+    if (more.length > 0) {
+        issues.push({
+            code: 'role-grants-more',
+            blocking: false,
+            field: 'role',
+            params: { role: role.name, count: more.length, privileges: more.map(nameOf).join(', ') }
+        });
+    }
+    if (!same(asked, exports.ROLE_GRANTING_PRIVILEGE) && role.privileges.some(p => same(p, exports.ROLE_GRANTING_PRIVILEGE))) {
+        issues.push({ code: 'role-grants-admin', blocking: false, field: 'role', params: { role: role.name } });
+    }
+    const smaller = facts.candidates
+        .filter(c => c.id !== role.id && c.privilegeCount < role.privileges.length)
+        .sort((a, b) => a.privilegeCount - b.privilegeCount || a.name.localeCompare(b.name))[0];
+    if (smaller) {
+        issues.push({ code: 'smaller-role-exists', blocking: false, field: 'role', params: { role: smaller.name, count: smaller.privilegeCount } });
+    }
+    if (!facts.deciderIsOwner) {
+        const lacking = role.privileges.filter(p => !facts.deciderPrivileges.some(d => same(d, p)));
+        if (lacking.length > 0) {
+            /* Told, not refused (questions Q6) - the role screen gives the same role today; ruling both is a separate decision. */
+            issues.push({ code: 'decider-lacks-it', blocking: false, field: 'role', params: { privileges: lacking.map(nameOf).join(', ') } });
+        }
+    }
+    return issues;
+}
+/** The smallest candidate - what the draft card proposes by default. Ties go by name, so the answer is the same every time. */
+function smallestRole(candidates) {
+    return [...candidates].sort((a, b) => a.privilegeCount - b.privilegeCount || a.name.localeCompare(b.name))[0];
+}
+const isBlocked = (issues) => issues.some(issue => issue.blocking);
+exports.isBlocked = isBlocked;
+//# sourceMappingURL=access-request-review.js.map

package/dist-server/utils/access-request-review.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"access-request-review.js","sourceRoot":"","sources":["../../server/utils/access-request-review.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * The checks an access decision passes - one function, read by the list screen, by the AI 입력 draft card\n * (its `check`, when the card is made and again when it is pressed) and by `decideAccessRequest` itself\n * (ADR-0103 decision 4: the card and the screen cannot say different things).\n *\n * Pure: the facts are collected by `access-request-facts.ts`; this decides what they mean. A model never\n * judges a role as risky - this does, the same way every time, and the model only words the result.\n *\n * Blocking issues keep the decision from being written. The rest are told to the person deciding.\n */\n\nexport type AccessRequestState = 'PENDING' | 'GRANTED' | 'DENIED' | 'WITHDRAWN' | 'EXPIRED'\n\nexport type AccessDecisionKind = 'GRANT' | 'DENY'\n\nexport type PrivilegeName = { category: string; privilege: string }\n\n/** The privilege that lets its holder put people into roles - a role carrying it hands that power on. */\nexport const ROLE_GRANTING_PRIVILEGE: PrivilegeName = { category: 'user', privilege: 'mutation' }\n\n/** How long a request waits for a decision (questions Q7). */\nexport const ACCESS_REQUEST_PENDING_DAYS = 14\n\nexport interface DecisionFacts {\n  request: {\n    state: AccessRequestState\n    requesterId: string\n    category: string\n    privilege: string\n    expiresAt?: Date | string | null\n  } | null\n  deciderId: string\n  decision: AccessDecisionKind\n  reason?: string | null\n  /** The role chosen to grant - absent when it is not this domain's to assign. */\n  role?: { id: string; name: string; privileges: PrivilegeName[] } | null\n  /** A role id was named but not found in the domain's scope. */\n  roleNamedButNotAssignable?: boolean\n  requester: { active: boolean; inDomain: boolean } | null\n  /** The requester holds the privilege now - through some other role, since the request was made. */\n  requesterHoldsIt: boolean\n  /** Every assignable role that grants the privilege, with how many privileges each carries. */\n  candidates: { id: string; name: string; privilegeCount: number }[]\n  /** The decider's own privileges - to tell them when a role gives what they do not have. */\n  deciderPrivileges: PrivilegeName[]\n  /** Whether the decider is a domain owner - an owner may give anything. */\n  deciderIsOwner: boolean\n  /** The latest earlier denial of the same requester and privilege. */\n  deniedBefore?: { by: string; at: Date | string; reason?: string | null } | null\n  now: Date\n}\n\nexport interface DecisionIssue {\n  code: string\n  blocking: boolean\n  field?: 'request' | 'decision' | 'role' | 'reason'\n  params?: Record<string, string | number | boolean | null>\n}\n\nconst same = (a: PrivilegeName, b: PrivilegeName) => a.category === b.category && a.privilege === b.privilege\nconst nameOf = (p: PrivilegeName) => `${p.category}:${p.privilege}`\n\n/** A pending request past its time is expired, whatever the column still says. */\nexport function effectiveState(state: AccessRequestState, expiresAt: Date | string | null | undefined, now: Date): AccessRequestState {\n  if (state !== 'PENDING' || !expiresAt) return state\n  const at = new Date(expiresAt)\n  return isNaN(at.getTime()) || at.getTime() > now.getTime() ? state : 'EXPIRED'\n}\n\nexport function expiryFrom(now: Date, days = ACCESS_REQUEST_PENDING_DAYS): Date {\n  return new Date(now.getTime() + days * 24 * 60 * 60 * 1000)\n}\n\nexport function reviewAccessDecision(facts: DecisionFacts): DecisionIssue[] {\n  const issues: DecisionIssue[] = []\n  const { request } = facts\n\n  if (!request) {\n    return [{ code: 'access-request-not-found', blocking: true, field: 'request' }]\n  }\n\n  const state = effectiveState(request.state, request.expiresAt, facts.now)\n  if (state !== 'PENDING') {\n    issues.push({ code: 'request-not-pending', blocking: true, field: 'request', params: { state } })\n  }\n\n  if (request.requesterId === facts.deciderId) {\n    issues.push({ code: 'own-request', blocking: true, field: 'request' })\n  }\n\n  if (!facts.requester || !facts.requester.inDomain || !facts.requester.active) {\n    issues.push({ code: 'requester-unavailable', blocking: true, field: 'request' })\n  }\n\n  if (facts.decision === 'DENY') {\n    if (!facts.reason || !facts.reason.trim()) {\n      issues.push({ code: 'deny-needs-reason', blocking: true, field: 'reason' })\n    }\n  } else {\n    issues.push(...grantIssues(facts, { category: request.category, privilege: request.privilege }))\n  }\n\n  if (facts.deniedBefore) {\n    issues.push({\n      code: 'denied-before',\n      blocking: false,\n      field: 'request',\n      params: { by: facts.deniedBefore.by, at: new Date(facts.deniedBefore.at).toISOString(), reason: facts.deniedBefore.reason ?? '' }\n    })\n  }\n\n  return issues\n}\n\nfunction grantIssues(facts: DecisionFacts, asked: PrivilegeName): DecisionIssue[] {\n  const issues: DecisionIssue[] = []\n\n  if (facts.requesterHoldsIt) {\n    issues.push({ code: 'already-holds', blocking: true, field: 'request', params: { privilege: nameOf(asked) } })\n  }\n\n  if (!facts.role) {\n    issues.push({\n      code: facts.roleNamedButNotAssignable ? 'role-not-assignable' : 'role-required',\n      blocking: true,\n      field: 'role'\n    })\n    return issues\n  }\n\n  const { role } = facts\n  if (!role.privileges.some(p => same(p, asked))) {\n    issues.push({ code: 'role-does-not-grant', blocking: true, field: 'role', params: { role: role.name, privilege: nameOf(asked) } })\n    return issues\n  }\n\n  const more = role.privileges.filter(p => !same(p, asked))\n  if (more.length > 0) {\n    issues.push({\n      code: 'role-grants-more',\n      blocking: false,\n      field: 'role',\n      params: { role: role.name, count: more.length, privileges: more.map(nameOf).join(', ') }\n    })\n  }\n\n  if (!same(asked, ROLE_GRANTING_PRIVILEGE) && role.privileges.some(p => same(p, ROLE_GRANTING_PRIVILEGE))) {\n    issues.push({ code: 'role-grants-admin', blocking: false, field: 'role', params: { role: role.name } })\n  }\n\n  const smaller = facts.candidates\n    .filter(c => c.id !== role.id && c.privilegeCount < role.privileges.length)\n    .sort((a, b) => a.privilegeCount - b.privilegeCount || a.name.localeCompare(b.name))[0]\n  if (smaller) {\n    issues.push({ code: 'smaller-role-exists', blocking: false, field: 'role', params: { role: smaller.name, count: smaller.privilegeCount } })\n  }\n\n  if (!facts.deciderIsOwner) {\n    const lacking = role.privileges.filter(p => !facts.deciderPrivileges.some(d => same(d, p)))\n    if (lacking.length > 0) {\n      /* Told, not refused (questions Q6) - the role screen gives the same role today; ruling both is a separate decision. */\n      issues.push({ code: 'decider-lacks-it', blocking: false, field: 'role', params: { privileges: lacking.map(nameOf).join(', ') } })\n    }\n  }\n\n  return issues\n}\n\n/** The smallest candidate - what the draft card proposes by default. Ties go by name, so the answer is the same every time. */\nexport function smallestRole<T extends { name: string; privilegeCount: number }>(candidates: T[]): T | undefined {\n  return [...candidates].sort((a, b) => a.privilegeCount - b.privilegeCount || a.name.localeCompare(b.name))[0]\n}\n\nexport const isBlocked = (issues: DecisionIssue[]) => issues.some(issue => issue.blocking)\n"]}

package/dist-server/utils/assignable-roles.d.ts

@@ -0,0 +1,23 @@
+import { EntityManager, WhereExpressionBuilder } from 'typeorm';
+import { Domain } from '@things-factory/shell';
+import { Role } from '../service/role/role.js';
+import { User } from '../service/user/user.js';
+/** Restricts `alias` (a Role) to what `domain` can assign. Parameters are named after the alias, so two uses do not collide. */
+export declare function whereAssignableBy<T extends WhereExpressionBuilder>(qb: T, alias: string, domain: Domain): T;
+/** The roles among `ids` that `domain` can assign. */
+export declare function findAssignableRoles(ids: string[], domain: Domain, tx?: EntityManager): Promise<Role[]>;
+/** Refuses with the ids that are not this domain's to assign - a name and values, spoken by `SpeakRefusals`. */
+export declare function requireAssignableRoles(ids: string[], domain: Domain, tx?: EntityManager): Promise<Role[]>;
+/**
+ * Puts `user` into `add` and takes them out of `remove` - every id found again in `domain`'s scope first.
+ * Roles the user holds outside that scope are not touched, whatever `remove` says.
+ *
+ * @returns the saved user, and the roles that were added (not already held).
+ */
+export declare function assignRoles(user: User, { add, remove }: {
+    add?: string[];
+    remove?: string[];
+}, domain: Domain, tx?: EntityManager): Promise<{
+    user: User;
+    added: Role[];
+}>;

package/dist-server/utils/assignable-roles.js

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.whereAssignableBy = whereAssignableBy;
+exports.findAssignableRoles = findAssignableRoles;
+exports.requireAssignableRoles = requireAssignableRoles;
+exports.assignRoles = assignRoles;
+const typeorm_1 = require("typeorm");
+const shell_1 = require("@things-factory/shell");
+const granted_role_js_1 = require("../service/granted-role/granted-role.js");
+const role_js_1 = require("../service/role/role.js");
+const user_js_1 = require("../service/user/user.js");
+/*
+ * The roles a domain can assign - and the one place a person is put into or taken out of them.
+ *
+ * ── The scope ─────────────────────────────────────────────────────────────
+ * Three kinds: the domain's own roles, its parent's (one level, as `userRoles` · `myRoles`), and roles a
+ * partner granted to it (`grantedRoles`). `User.roles` answers exactly this scope (cb9a41e040), so the
+ * user screen's checkboxes and what can be saved are the same set.
+ *
+ * ── Why the ids are found again ──────────────────────────────────────────
+ * `updateUserRoles` took the client's `selectedRoles` and concatenated them onto the user, and took its
+ * `availableRoles` and removed every held role with one of those ids. Neither was looked at. A role id of
+ * another tenant was added as sent, and another tenant's role id in `availableRoles` took that role away from
+ * the person in the other domain. Both are found here, in this domain's scope, by id. A role to add that is not
+ * there is refused by name (ADR-0103 decision 2); a role to remove that is not there is not this domain's to take.
+ *
+ * The access request grants through this too, so the two ways into a role are one.
+ */
+/** Restricts `alias` (a Role) to what `domain` can assign. Parameters are named after the alias, so two uses do not collide. */
+function whereAssignableBy(qb, alias, domain) {
+    const domainIds = [domain.id, domain.parentId].filter(Boolean);
+    const own = `${alias}_assignableDomainIds`;
+    const grantedTo = `${alias}_assignableGrantedTo`;
+    qb.andWhere(new typeorm_1.Brackets(inner => {
+        inner.where(`${alias}.domain IN (:...${own})`, { [own]: domainIds });
+        inner.orWhere(sub => {
+            const granted = sub
+                .subQuery()
+                .select('GRANTED.role')
+                .from(granted_role_js_1.GrantedRole, 'GRANTED')
+                .where(`GRANTED.domain = :${grantedTo}`, { [grantedTo]: domain.id })
+                .getQuery();
+            return `${alias}.id IN ${granted}`;
+        });
+    }));
+    return qb;
+}
+/** The roles among `ids` that `domain` can assign. */
+async function findAssignableRoles(ids, domain, tx) {
+    const unique = [...new Set((ids || []).filter(Boolean))];
+    if (unique.length === 0)
+        return [];
+    const qb = (0, shell_1.getRepository)(role_js_1.Role, tx).createQueryBuilder('ROLE').where({ id: (0, typeorm_1.In)(unique) });
+    return await whereAssignableBy(qb, 'ROLE', domain).getMany();
+}
+/** Refuses with the ids that are not this domain's to assign - a name and values, spoken by `SpeakRefusals`. */
+async function requireAssignableRoles(ids, domain, tx) {
+    const found = await findAssignableRoles(ids, domain, tx);
+    const foundIds = new Set(found.map(role => role.id));
+    const missing = [...new Set((ids || []).filter(Boolean))].filter(id => !foundIds.has(id));
+    if (missing.length > 0) {
+        throw new shell_1.Refusal('role-not-assignable-here', { roles: missing.join(', ') }, `This domain cannot assign the role(s) ${missing.join(', ')}.`);
+    }
+    return found;
+}
+/**
+ * Puts `user` into `add` and takes them out of `remove` - every id found again in `domain`'s scope first.
+ * Roles the user holds outside that scope are not touched, whatever `remove` says.
+ *
+ * @returns the saved user, and the roles that were added (not already held).
+ */
+async function assignRoles(user, { add = [], remove = [] }, domain, tx) {
+    const adding = await requireAssignableRoles(add, domain, tx);
+    /*
+     * `remove` is the caller's scope ("every role this screen shows"), not a demand - `user-detail.ts` builds it
+     * from the list it read. Inside this domain's scope it is honoured; an id outside it is a role this domain
+     * does not own, and it stays with the person.
+     */
+    const removing = await findAssignableRoles(remove, domain, tx);
+    const addingIds = new Set(adding.map(role => role.id));
+    const removingIds = new Set(removing.map(role => role.id).filter(id => !addingIds.has(id)));
+    const held = (user.roles || []).filter(role => !removingIds.has(role.id));
+    const heldIds = new Set(held.map(role => role.id));
+    const added = adding.filter(role => !heldIds.has(role.id));
+    user.roles = [...held, ...added];
+    const saved = await (0, shell_1.getRepository)(user_js_1.User, tx).save(user);
+    return { user: saved, added };
+}
+//# sourceMappingURL=assignable-roles.js.map

package/dist-server/utils/assignable-roles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assignable-roles.js","sourceRoot":"","sources":["../../server/utils/assignable-roles.ts"],"names":[],"mappings":"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","sourcesContent":["import { Brackets, EntityManager, In, SelectQueryBuilder, WhereExpressionBuilder } from 'typeorm'\n\nimport { Domain, getRepository, Refusal } from '@things-factory/shell'\n\nimport { GrantedRole } from '../service/granted-role/granted-role.js'\nimport { Role } from '../service/role/role.js'\nimport { User } from '../service/user/user.js'\n\n/*\n * The roles a domain can assign - and the one place a person is put into or taken out of them.\n *\n * ── The scope ─────────────────────────────────────────────────────────────\n * Three kinds: the domain's own roles, its parent's (one level, as `userRoles` · `myRoles`), and roles a\n * partner granted to it (`grantedRoles`). `User.roles` answers exactly this scope (cb9a41e040), so the\n * user screen's checkboxes and what can be saved are the same set.\n *\n * ── Why the ids are found again ──────────────────────────────────────────\n * `updateUserRoles` took the client's `selectedRoles` and concatenated them onto the user, and took its\n * `availableRoles` and removed every held role with one of those ids. Neither was looked at. A role id of\n * another tenant was added as sent, and another tenant's role id in `availableRoles` took that role away from\n * the person in the other domain. Both are found here, in this domain's scope, by id. A role to add that is not\n * there is refused by name (ADR-0103 decision 2); a role to remove that is not there is not this domain's to take.\n *\n * The access request grants through this too, so the two ways into a role are one.\n */\n\n/** Restricts `alias` (a Role) to what `domain` can assign. Parameters are named after the alias, so two uses do not collide. */\nexport function whereAssignableBy<T extends WhereExpressionBuilder>(qb: T, alias: string, domain: Domain): T {\n  const domainIds = [domain.id, domain.parentId].filter(Boolean)\n  const own = `${alias}_assignableDomainIds`\n  const grantedTo = `${alias}_assignableGrantedTo`\n\n  qb.andWhere(\n    new Brackets(inner => {\n      inner.where(`${alias}.domain IN (:...${own})`, { [own]: domainIds })\n      inner.orWhere(sub => {\n        const granted = (sub as unknown as SelectQueryBuilder<Role>)\n          .subQuery()\n          .select('GRANTED.role')\n          .from(GrantedRole, 'GRANTED')\n          .where(`GRANTED.domain = :${grantedTo}`, { [grantedTo]: domain.id })\n          .getQuery()\n        return `${alias}.id IN ${granted}`\n      })\n    })\n  )\n  return qb\n}\n\n/** The roles among `ids` that `domain` can assign. */\nexport async function findAssignableRoles(ids: string[], domain: Domain, tx?: EntityManager): Promise<Role[]> {\n  const unique = [...new Set((ids || []).filter(Boolean))]\n  if (unique.length === 0) return []\n\n  const qb = getRepository(Role, tx).createQueryBuilder('ROLE').where({ id: In(unique) })\n  return await whereAssignableBy(qb, 'ROLE', domain).getMany()\n}\n\n/** Refuses with the ids that are not this domain's to assign - a name and values, spoken by `SpeakRefusals`. */\nexport async function requireAssignableRoles(ids: string[], domain: Domain, tx?: EntityManager): Promise<Role[]> {\n  const found = await findAssignableRoles(ids, domain, tx)\n  const foundIds = new Set(found.map(role => role.id))\n  const missing = [...new Set((ids || []).filter(Boolean))].filter(id => !foundIds.has(id))\n\n  if (missing.length > 0) {\n    throw new Refusal(\n      'role-not-assignable-here',\n      { roles: missing.join(', ') },\n      `This domain cannot assign the role(s) ${missing.join(', ')}.`\n    )\n  }\n  return found\n}\n\n/**\n * Puts `user` into `add` and takes them out of `remove` - every id found again in `domain`'s scope first.\n * Roles the user holds outside that scope are not touched, whatever `remove` says.\n *\n * @returns the saved user, and the roles that were added (not already held).\n */\nexport async function assignRoles(\n  user: User,\n  { add = [], remove = [] }: { add?: string[]; remove?: string[] },\n  domain: Domain,\n  tx?: EntityManager\n): Promise<{ user: User; added: Role[] }> {\n  const adding = await requireAssignableRoles(add, domain, tx)\n  /*\n   * `remove` is the caller's scope (\"every role this screen shows\"), not a demand - `user-detail.ts` builds it\n   * from the list it read. Inside this domain's scope it is honoured; an id outside it is a role this domain\n   * does not own, and it stays with the person.\n   */\n  const removing = await findAssignableRoles(remove, domain, tx)\n\n  const addingIds = new Set(adding.map(role => role.id))\n  const removingIds = new Set(removing.map(role => role.id).filter(id => !addingIds.has(id)))\n\n  const held = (user.roles || []).filter(role => !removingIds.has(role.id))\n  const heldIds = new Set(held.map(role => role.id))\n  const added = adding.filter(role => !heldIds.has(role.id))\n\n  user.roles = [...held, ...added]\n  const saved = await getRepository(User, tx).save(user)\n  return { user: saved, added }\n}\n"]}

package/dist-server/utils/check-permission.d.ts

@@ -1,7 +1,34 @@
 import { Domain } from '@things-factory/shell';
 import { PrivilegeObject } from '../service/privilege/privilege.js';
 import { User } from '../service/user/user.js';
-export declare function checkPermission(privilegeObject: PrivilegeObject, user: User, domain: Domain, unsafeIP?: boolean, prohibitedPrivileges?: {
+/**
+ * Why a gate said no - what the person can do about it differs (ADR-0103 decision 1).
+ *
+ *  role       none of their roles holds category:privilege - a role can be given (an access request)
+ *  address    refused from where they are: the domain's protected address list
+ *  license    refused by what this installation is licensed for
+ *  ownership  the declaration opens only to domain or system owners - no role gives it
+ *  unknown    a prohibition that does not say where it came from - the reason is not made up
+ */
+export type RefusalCause = 'role' | 'address' | 'license' | 'ownership' | 'unknown';
+/**
+ * A privilege refused by the request, whatever the person's roles. `by` says who refused it:
+ * the domain's address list (shell domain-middleware) or the installation's license (board-service).
+ */
+export type ProhibitedPrivilege = {
     category: string;
     privilege: string;
-}[]): Promise<boolean>;
+    by?: 'address' | 'license';
+};
+export type PermissionJudgement = {
+    permitted: true;
+} | {
+    permitted: false;
+    because: RefusalCause;
+};
+/**
+ * The gate, with its reason. `checkPermission` answers only the boolean and is what most callers
+ * want; the privilege directive reads this so a refusal can say which of the four it was.
+ */
+export declare function judgePermission(privilegeObject: PrivilegeObject, user: User, domain: Domain, unsafeIP?: boolean, prohibitedPrivileges?: ProhibitedPrivilege[]): Promise<PermissionJudgement>;
+export declare function checkPermission(privilegeObject: PrivilegeObject, user: User, domain: Domain, unsafeIP?: boolean, prohibitedPrivileges?: ProhibitedPrivilege[]): Promise<boolean>;

package/dist-server/utils/check-permission.js

@@ -1,19 +1,51 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.judgePermission = judgePermission;
 exports.checkPermission = checkPermission;
 const user_js_1 = require("../service/user/user.js");
-async function checkPermission(privilegeObject, user, domain, unsafeIP, prohibitedPrivileges) {
+const PERMITTED = { permitted: true };
+function refused(because) {
+    return { permitted: false, because };
+}
+function prohibitionOf(prohibitedPrivileges, category, privilege) {
+    return (prohibitedPrivileges || []).find(pp => pp.category == category && pp.privilege == privilege);
+}
+/**
+ * The gate, with its reason. `checkPermission` answers only the boolean and is what most callers
+ * want; the privilege directive reads this so a refusal can say which of the four it was.
+ */
+async function judgePermission(privilegeObject, user, domain, unsafeIP, prohibitedPrivileges) {
     if (!privilegeObject) {
-        return true;
+        return PERMITTED;
     }
     const { owner: domainOwnerGranted, super: superUserGranted, category, privilege } = privilegeObject;
+    /* Ownership as the gate has always asked it - `process` carries the answer (domain-authenticate-middleware installs it). */
+    const ownershipOpens = async () => !!((domainOwnerGranted && (await process.domainOwnerGranted(domain, user))) ||
+        (superUserGranted && (await process.superUserGranted(domain, user))));
+    /*
+     * From an unsafe address ownership never opened anything and was never asked. It is asked now only on the
+     * way to a refusal, to tell "address" from "role" - and a missing answer is "no", so the gate refuses as it did.
+     */
+    const ownershipWouldHaveOpened = async () => {
+        try {
+            return await ownershipOpens();
+        }
+        catch {
+            return false;
+        }
+    };
     if (unsafeIP) {
         if (privilege && category) {
             // unsafeIP 상황에서는 ownership granted는 적용되지 않는다.
-            if ((prohibitedPrivileges || []).find(pp => pp.category == category && pp.privilege == privilege)) {
-                return false;
+            const prohibition = prohibitionOf(prohibitedPrivileges, category, privilege);
+            if (prohibition) {
+                return refused(prohibition.by ?? 'unknown');
+            }
+            if (await user_js_1.User.hasPrivilege(privilege, category, domain, user)) {
+                return PERMITTED;
             }
-            return await user_js_1.User.hasPrivilege(privilege, category, domain, user);
+            /* An owner without the role would pass from a safe address - what stopped them is where they are. */
+            return refused((await ownershipWouldHaveOpened()) ? 'address' : 'role');
         }
         /*
          * Ownership does not count from an unsafe address, so a declaration that rests on
@@ -25,22 +57,24 @@ async function checkPermission(privilegeObject, user, domain, unsafeIP, prohibit
          * `privilege-directive.ts` now refuses to build a declaration that names nothing, but
          * this function is exported and called directly, so the rule is fixed here too.
          */
-        return false;
+        return refused('address');
     }
     else {
         if (!privilege || !category) {
             // privilege, category가 설정되지 않은 경우에는 ownership granted만을 적용한다.
-            return ((domainOwnerGranted && (await process.domainOwnerGranted(domain, user))) ||
-                (superUserGranted && (await process.superUserGranted(domain, user))));
+            return (await ownershipOpens()) ? PERMITTED : refused('ownership');
         }
-        if ((domainOwnerGranted && (await process.domainOwnerGranted(domain, user))) ||
-            (superUserGranted && (await process.superUserGranted(domain, user)))) {
-            return true;
+        if (await ownershipOpens()) {
+            return PERMITTED;
         }
-        if ((prohibitedPrivileges || []).find(pp => pp.category == category && pp.privilege == privilege)) {
-            return false;
+        const prohibition = prohibitionOf(prohibitedPrivileges, category, privilege);
+        if (prohibition) {
+            return refused(prohibition.by ?? 'unknown');
         }
-        return await user_js_1.User.hasPrivilege(privilege, category, domain, user);
+        return (await user_js_1.User.hasPrivilege(privilege, category, domain, user)) ? PERMITTED : refused('role');
     }
 }
+async function checkPermission(privilegeObject, user, domain, unsafeIP, prohibitedPrivileges) {
+    return (await judgePermission(privilegeObject, user, domain, unsafeIP, prohibitedPrivileges)).permitted;
+}
 //# sourceMappingURL=check-permission.js.map

package/dist-server/utils/check-permission.js.map

@@ -1 +1 @@
-{"version":3,"file":"check-permission.js","sourceRoot":"","sources":["../../server/utils/check-permission.ts"],"names":[],"mappings":";;AAIA,0CAwDC;AA1DD,qDAA8C;AAEvC,KAAK,UAAU,eAAe,CACnC,eAAgC,EAChC,IAAU,EACV,MAAc,EACd,QAAkB,EAClB,oBAAgE;IAEhE,IAAI,CAAC,eAAe,EAAE,CAAC;QACrB,OAAO,IAAI,CAAA;IACb,CAAC;IAED,MAAM,EAAE,KAAK,EAAE,kBAAkB,EAAE,KAAK,EAAE,gBAAgB,EAAE,QAAQ,EAAE,SAAS,EAAE,GAAG,eAAe,CAAA;IAEnG,IAAI,QAAQ,EAAE,CAAC;QACb,IAAI,SAAS,IAAI,QAAQ,EAAE,CAAC;YAC1B,8CAA8C;YAC9C,IAAI,CAAC,oBAAoB,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,QAAQ,IAAI,QAAQ,IAAI,EAAE,CAAC,SAAS,IAAI,SAAS,CAAC,EAAE,CAAC;gBAClG,OAAO,KAAK,CAAA;YACd,CAAC;YAED,OAAO,MAAM,cAAI,CAAC,YAAY,CAAC,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,CAAA;QACnE,CAAC;QAED;;;;;;;;;WASG;QACH,OAAO,KAAK,CAAA;IACd,CAAC;SAAM,CAAC;QACN,IAAI,CAAC,SAAS,IAAI,CAAC,QAAQ,EAAE,CAAC;YAC5B,8DAA8D;YAC9D,OAAO,CACL,CAAC,kBAAkB,IAAI,CAAC,MAAM,OAAO,CAAC,kBAAkB,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC;gBACxE,CAAC,gBAAgB,IAAI,CAAC,MAAM,OAAO,CAAC,gBAAgB,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC,CACrE,CAAA;QACH,CAAC;QAED,IACE,CAAC,kBAAkB,IAAI,CAAC,MAAM,OAAO,CAAC,kBAAkB,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC;YACxE,CAAC,gBAAgB,IAAI,CAAC,MAAM,OAAO,CAAC,gBAAgB,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC,EACpE,CAAC;YACD,OAAO,IAAI,CAAA;QACb,CAAC;QAED,IAAI,CAAC,oBAAoB,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,QAAQ,IAAI,QAAQ,IAAI,EAAE,CAAC,SAAS,IAAI,SAAS,CAAC,EAAE,CAAC;YAClG,OAAO,KAAK,CAAA;QACd,CAAC;QAED,OAAO,MAAM,cAAI,CAAC,YAAY,CAAC,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,CAAA;IACnE,CAAC;AACH,CAAC","sourcesContent":["import { Domain } from '@things-factory/shell'\nimport { PrivilegeObject } from '../service/privilege/privilege.js'\nimport { User } from '../service/user/user.js'\n\nexport async function checkPermission(\n  privilegeObject: PrivilegeObject,\n  user: User,\n  domain: Domain,\n  unsafeIP?: boolean,\n  prohibitedPrivileges?: { category: string; privilege: string }[]\n): Promise<boolean> {\n  if (!privilegeObject) {\n    return true\n  }\n\n  const { owner: domainOwnerGranted, super: superUserGranted, category, privilege } = privilegeObject\n\n  if (unsafeIP) {\n    if (privilege && category) {\n      // unsafeIP 상황에서는 ownership granted는 적용되지 않는다.\n      if ((prohibitedPrivileges || []).find(pp => pp.category == category && pp.privilege == privilege)) {\n        return false\n      }\n\n      return await User.hasPrivilege(privilege, category, domain, user)\n    }\n\n    /*\n     * Ownership does not count from an unsafe address, so a declaration that rests on\n     * ownership alone has nothing left to stand on here and the answer is no.\n     *\n     * This read `!domainOwnerGranted && !superUserGranted` until 2026-09-15, which answered\n     * **yes** for an object that named nothing at all — the same `{}` a safe address\n     * refused. An unsafe address was the more permissive of the two, which is backwards.\n     * `privilege-directive.ts` now refuses to build a declaration that names nothing, but\n     * this function is exported and called directly, so the rule is fixed here too.\n     */\n    return false\n  } else {\n    if (!privilege || !category) {\n      // privilege, category가 설정되지 않은 경우에는 ownership granted만을 적용한다.\n      return (\n        (domainOwnerGranted && (await process.domainOwnerGranted(domain, user))) ||\n        (superUserGranted && (await process.superUserGranted(domain, user)))\n      )\n    }\n\n    if (\n      (domainOwnerGranted && (await process.domainOwnerGranted(domain, user))) ||\n      (superUserGranted && (await process.superUserGranted(domain, user)))\n    ) {\n      return true\n    }\n\n    if ((prohibitedPrivileges || []).find(pp => pp.category == category && pp.privilege == privilege)) {\n      return false\n    }\n\n    return await User.hasPrivilege(privilege, category, domain, user)\n  }\n}\n"]}
+{"version":3,"file":"check-permission.js","sourceRoot":"","sources":["../../server/utils/check-permission.ts"],"names":[],"mappings":"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","sourcesContent":["import { Domain } from '@things-factory/shell'\nimport { PrivilegeObject } from '../service/privilege/privilege.js'\nimport { User } from '../service/user/user.js'\n\n/**\n * Why a gate said no - what the person can do about it differs (ADR-0103 decision 1).\n *\n *  role       none of their roles holds category:privilege - a role can be given (an access request)\n *  address    refused from where they are: the domain's protected address list\n *  license    refused by what this installation is licensed for\n *  ownership  the declaration opens only to domain or system owners - no role gives it\n *  unknown    a prohibition that does not say where it came from - the reason is not made up\n */\nexport type RefusalCause = 'role' | 'address' | 'license' | 'ownership' | 'unknown'\n\n/**\n * A privilege refused by the request, whatever the person's roles. `by` says who refused it:\n * the domain's address list (shell domain-middleware) or the installation's license (board-service).\n */\nexport type ProhibitedPrivilege = { category: string; privilege: string; by?: 'address' | 'license' }\n\nexport type PermissionJudgement = { permitted: true } | { permitted: false; because: RefusalCause }\n\nconst PERMITTED: PermissionJudgement = { permitted: true }\n\nfunction refused(because: RefusalCause): PermissionJudgement {\n  return { permitted: false, because }\n}\n\nfunction prohibitionOf(prohibitedPrivileges: ProhibitedPrivilege[] | undefined, category: string, privilege: string) {\n  return (prohibitedPrivileges || []).find(pp => pp.category == category && pp.privilege == privilege)\n}\n\n/**\n * The gate, with its reason. `checkPermission` answers only the boolean and is what most callers\n * want; the privilege directive reads this so a refusal can say which of the four it was.\n */\nexport async function judgePermission(\n  privilegeObject: PrivilegeObject,\n  user: User,\n  domain: Domain,\n  unsafeIP?: boolean,\n  prohibitedPrivileges?: ProhibitedPrivilege[]\n): Promise<PermissionJudgement> {\n  if (!privilegeObject) {\n    return PERMITTED\n  }\n\n  const { owner: domainOwnerGranted, super: superUserGranted, category, privilege } = privilegeObject\n\n  /* Ownership as the gate has always asked it - `process` carries the answer (domain-authenticate-middleware installs it). */\n  const ownershipOpens = async () =>\n    !!(\n      (domainOwnerGranted && (await (process as any).domainOwnerGranted(domain, user))) ||\n      (superUserGranted && (await (process as any).superUserGranted(domain, user)))\n    )\n\n  /*\n   * From an unsafe address ownership never opened anything and was never asked. It is asked now only on the\n   * way to a refusal, to tell \"address\" from \"role\" - and a missing answer is \"no\", so the gate refuses as it did.\n   */\n  const ownershipWouldHaveOpened = async () => {\n    try {\n      return await ownershipOpens()\n    } catch {\n      return false\n    }\n  }\n\n  if (unsafeIP) {\n    if (privilege && category) {\n      // unsafeIP 상황에서는 ownership granted는 적용되지 않는다.\n      const prohibition = prohibitionOf(prohibitedPrivileges, category, privilege)\n      if (prohibition) {\n        return refused(prohibition.by ?? 'unknown')\n      }\n\n      if (await User.hasPrivilege(privilege, category, domain, user)) {\n        return PERMITTED\n      }\n\n      /* An owner without the role would pass from a safe address - what stopped them is where they are. */\n      return refused((await ownershipWouldHaveOpened()) ? 'address' : 'role')\n    }\n\n    /*\n     * Ownership does not count from an unsafe address, so a declaration that rests on\n     * ownership alone has nothing left to stand on here and the answer is no.\n     *\n     * This read `!domainOwnerGranted && !superUserGranted` until 2026-09-15, which answered\n     * **yes** for an object that named nothing at all — the same `{}` a safe address\n     * refused. An unsafe address was the more permissive of the two, which is backwards.\n     * `privilege-directive.ts` now refuses to build a declaration that names nothing, but\n     * this function is exported and called directly, so the rule is fixed here too.\n     */\n    return refused('address')\n  } else {\n    if (!privilege || !category) {\n      // privilege, category가 설정되지 않은 경우에는 ownership granted만을 적용한다.\n      return (await ownershipOpens()) ? PERMITTED : refused('ownership')\n    }\n\n    if (await ownershipOpens()) {\n      return PERMITTED\n    }\n\n    const prohibition = prohibitionOf(prohibitedPrivileges, category, privilege)\n    if (prohibition) {\n      return refused(prohibition.by ?? 'unknown')\n    }\n\n    return (await User.hasPrivilege(privilege, category, domain, user)) ? PERMITTED : refused('role')\n  }\n}\n\nexport async function checkPermission(\n  privilegeObject: PrivilegeObject,\n  user: User,\n  domain: Domain,\n  unsafeIP?: boolean,\n  prohibitedPrivileges?: ProhibitedPrivilege[]\n): Promise<boolean> {\n  return (await judgePermission(privilegeObject, user, domain, unsafeIP, prohibitedPrivileges)).permitted\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/auth-base",
-  "version": "10.1.79",
+  "version": "10.1.106",
   "main": "dist-server/index.js",
   "browser": "dist-client/index.js",
   "things-factory": true,
@@ -34,9 +34,9 @@
     "@reduxjs/toolkit": "^2.2.5",
     "@simplewebauthn/browser": "^13.0.0",
     "@simplewebauthn/server": "^13.0.0",
-    "@things-factory/email-base": "^10.1.79",
+    "@things-factory/email-base": "^10.1.106",
     "@things-factory/env": "^10.1.20",
-    "@things-factory/shell": "^10.1.79",
+    "@things-factory/shell": "^10.1.106",
     "@things-factory/utils": "^10.1.20",
     "@types/webappsec-credential-management": "^0.6.9",
     "jsonwebtoken": "^9.0.0",
@@ -48,5 +48,5 @@
     "passport-jwt": "^4.0.0",
     "passport-local": "^1.0.0"
   },
-  "gitHead": "94cde9ba17dfdddb0a16139b71e5a7e370977e4a"
+  "gitHead": "8d78c14708420773ec32d18b8dd44c300771c44d"
 }