|
| 1 | +// plugins/model-apps/scripts/lib/role-privileges.js |
| 2 | +// PURE: what privileges a persona's security role MUST hold, and whether a deployed role holds them. |
| 3 | +// |
| 4 | +// WHY this exists. `verifySpec`'s role check proved only that a role ROW exists carrying the SDK |
| 5 | +// ownership marker. It never looked at the role's privileges — so a role created with the wrong |
| 6 | +// access, or one whose privilege write silently failed after the row was created, verified clean. |
| 7 | +// That is the cheapest gap in the JTBD-probe design (docs/jtbd-probe-design.md §3b): it needs a |
| 8 | +// metadata read, not a browser. |
| 9 | +// |
| 10 | +// SUBSET, not equality. We assert the role holds AT LEAST every declared privilege at AT LEAST the |
| 11 | +// declared depth. Extra privileges are never a finding, and that is deliberate — three legitimate |
| 12 | +// sources add privileges the spec does not literally list: |
| 13 | +// 1. `appAccess` injects `appmodule` read (see personaRoleSpecFor). |
| 14 | +// 2. Several jobs unioned together escalate a shared entity+access to the MAX declared scope. |
| 15 | +// 3. Distinct entities can share ONE Dataverse privilege, and a role holds one depth per |
| 16 | +// privilege — so the SDK raises that privilege to the highest scope any of them asked for. |
| 17 | +// An equality check would fail on all three while telling us nothing true. |
| 18 | +// |
| 19 | +// Dataverse reference — privilege depth (`Depth` on ReplacePrivilegesRole, `RolePrivilegeDepth`): |
| 20 | +// Basic (user) < Local (business unit) < Deep (parent/child) < Global (organization). |
| 21 | +// https://learn.microsoft.com/en-us/power-apps/developer/data-platform/security-model |
| 22 | +'use strict'; |
| 23 | + |
| 24 | +// App Spec scope -> Dataverse depth name, and its ORDER. The order is what makes this a subset |
| 25 | +// check: a role holding Global satisfies a declared Basic. Mirrors the vendored SDK's own mapping |
| 26 | +// (verified against scripts/vendor/cds-maker-sdk.cjs) so a comparison cannot disagree with the write. |
| 27 | +const SCOPE_DEPTH = { user: 'Basic', businessUnit: 'Local', parentChild: 'Deep', organization: 'Global' }; |
| 28 | +const DEPTH_RANK = { basic: 1, local: 2, deep: 3, global: 4 }; |
| 29 | +// App Spec access token -> Dataverse PrivilegeType, again mirroring the SDK. |
| 30 | +const ACCESS_TYPE = { read: 'Read', create: 'Create', write: 'Write', delete: 'Delete', append: 'Append', appendTo: 'AppendTo', assign: 'Assign', share: 'Share' }; |
| 31 | + |
| 32 | +const rankOf = (depth) => DEPTH_RANK[String(depth == null ? '' : depth).trim().toLowerCase()] || 0; |
| 33 | + |
| 34 | +// Flatten a persona to the (entity, access, scope) triples its role must satisfy, taking the MAX |
| 35 | +// scope per (entity, access) exactly as the builder's union does. `appAccess` is folded in here so |
| 36 | +// the expectation matches what the build actually writes rather than what the author typed. |
| 37 | +function declaredPrivileges(persona) { |
| 38 | + const byKey = new Map(); // "<entity>|<access>" -> { entity, access, scope } |
| 39 | + const addAll = (list) => { |
| 40 | + for (const pr of list || []) { |
| 41 | + if (!pr || !pr.entity) continue; |
| 42 | + const entity = String(pr.entity).trim().toLowerCase(); |
| 43 | + const scope = pr.scope || 'user'; |
| 44 | + for (const a of pr.access || []) { |
| 45 | + const access = String(a).trim(); |
| 46 | + if (!access) continue; |
| 47 | + const key = `${entity}|${access.toLowerCase()}`; |
| 48 | + const prev = byKey.get(key); |
| 49 | + // Max scope wins — the same rule the builder applies when unioning jobs into one role. |
| 50 | + if (!prev || rankOf(SCOPE_DEPTH[scope]) > rankOf(SCOPE_DEPTH[prev.scope])) byKey.set(key, { entity, access, scope }); |
| 51 | + } |
| 52 | + } |
| 53 | + }; |
| 54 | + for (const j of (persona && persona.jobs) || []) addAll(j && j.privileges); |
| 55 | + addAll(persona && persona.additionalPrivileges); |
| 56 | + // Mirrors personaRoleSpecFor: unless the persona opts out, the build grants appmodule read so the |
| 57 | + // app actually opens for them. Verifying it matters — without it the role exists but the app does not. |
| 58 | + if (!persona || persona.appAccess !== false) addAll([{ entity: 'appmodule', access: ['read'], scope: 'organization' }]); |
| 59 | + return [...byKey.values()]; |
| 60 | +} |
| 61 | + |
| 62 | +// Compare declared privileges against what the role actually holds. |
| 63 | +// `entityPrivileges`: Map<entityLogical, [{ Name, PrivilegeId, PrivilegeType }]> — from |
| 64 | +// EntityDefinitions(LogicalName='x')?$select=Privileges, the SAME source the |
| 65 | +// SDK resolves against when it writes. |
| 66 | +// `actualByPrivilegeId`: Map<privilegeId(lowercased), depthName> |
| 67 | +// Returns { ok, missing:[{ entity, access, scope, reason, privilegeName? }] }. |
| 68 | +// An entity whose metadata could not be read is reported as a finding, never skipped — a read |
| 69 | +// failure must not read as "nothing missing" (fail closed). |
| 70 | +function compareRolePrivileges(declared, entityPrivileges, actualByPrivilegeId) { |
| 71 | + const missing = []; |
| 72 | + for (const d of declared) { |
| 73 | + const privs = entityPrivileges.get(d.entity); |
| 74 | + if (!privs) { |
| 75 | + missing.push({ ...d, reason: `could not read privilege metadata for '${d.entity}'` }); |
| 76 | + continue; |
| 77 | + } |
| 78 | + const type = ACCESS_TYPE[d.access.toLowerCase()]; |
| 79 | + const p = type && privs.find((x) => x && x.PrivilegeType === type); |
| 80 | + if (!p) { |
| 81 | + missing.push({ ...d, reason: `'${d.entity}' exposes no '${d.access}' privilege` }); |
| 82 | + continue; |
| 83 | + } |
| 84 | + const held = actualByPrivilegeId.get(String(p.PrivilegeId || '').trim().toLowerCase()); |
| 85 | + if (!held) { |
| 86 | + missing.push({ ...d, privilegeName: p.Name, reason: `role does not hold ${p.Name}` }); |
| 87 | + continue; |
| 88 | + } |
| 89 | + const want = SCOPE_DEPTH[d.scope] || 'Basic'; |
| 90 | + if (rankOf(held) < rankOf(want)) { |
| 91 | + missing.push({ ...d, privilegeName: p.Name, reason: `role holds ${p.Name} at ${held}, below the declared ${want}` }); |
| 92 | + } |
| 93 | + } |
| 94 | + return { ok: missing.length === 0, missing }; |
| 95 | +} |
| 96 | + |
| 97 | +module.exports = { declaredPrivileges, compareRolePrivileges, SCOPE_DEPTH, ACCESS_TYPE, DEPTH_RANK }; |
0 commit comments