@zhama/tego-plugin-sdk 0.0.0-stage → 1.36.0

package/dist/access.js

@@ -0,0 +1,26 @@
+var At=Object.defineProperty;var r=(t,e)=>At(t,"name",{value:e,configurable:!0});import{RESERVED_PERMISSIONS as v,grantProblem as Z,GLOBAL_DOMAIN as Ot,accessCatalogSchema as Dt}from"./chunk-VMCGDDGP.js";export{AccessCatalogError,BUILTIN_PRINCIPAL_KINDS,DELEGATION_ACTIONS,GLOBAL_DOMAIN,HOST_ADMIN_ROLE,RESERVED_GROUP,RESERVED_PERMISSIONS,accessCatalogFromJson,accessCatalogSchema,defineAccess,grantProblem,validateAccessCatalog}from"./chunk-VMCGDDGP.js";import{expandImplications as E,mergeGrant as Mt,scopeRank as M}from"./chunk-SNUCO2MK.js";export{expandImplications,mergeGrant,scopeRank}from"./chunk-SNUCO2MK.js";import{z as u}from"zod";import{zodToJsonSchema as Ct}from"zod-to-json-schema";function tt(t){return{tenantId:t.tenantId,userId:t.userId,hostRoles:t.roles,...t.avatarId?{agent:{avatarId:t.avatarId,delegation:t.delegation?.actions??[]}}:{}}}r(tt,"subjectFromContext");var et=class{static{r(this,"EffectiveGrants")}constructor(t,e,n,s,i,a,o){this.catalog=t,this.subject=e,this.domain=n,this.held=s,this.withheld=i,this.sources=a,this.assignedDomains=o}catalog;subject;domain;held;withheld;sources;assignedDomains;value(t){return this.held.get(t)?.value}can(t){return this.held.has(t)}scope(t){const e=this.held.get(t)?.value;return typeof e=="string"?e:null}atLeast(t,e){const n=this.catalog.permissions[t],s=this.held.get(t)?.value;if(!n?.scopes||typeof s!="string")return!1;const i=n.scopes.indexOf(e);return i>=0&&n.scopes.indexOf(s)>=i}via(t){return this.held.get(t)?.via??this.withheld.get(t)?.via??[]}denial(t){return this.held.has(t)?null:this.withheld.get(t)?.reason??"not_granted"}permissions(){return Object.fromEntries([...this.held].map(([t,e])=>[t,e.value]))}managesThroughHostRole(){return this.held.get(v.manage)?.via.some(t=>t.source==="hostRole")??!1}decide(t){const e=this.held.get(t);return e?{allowed:!0,permission:t,scope:typeof e.value=="string"?e.value:null,reason:"granted",via:e.via}:{allowed:!1,permission:t,scope:null,reason:this.denial(t),via:this.via(t)}}};async function nt(t,e,n,s){const i=t.decide(e);if(!i.allowed||n===void 0||i.scope===null)return i;const a=t.catalog.permissions[e].scopes;for(let o=a.indexOf(i.scope);o>=0;o--){const d=a[o];if(await s(d))return{...i,matchedScope:d}}return{...i,allowed:!1,reason:"scope_mismatch"}}r(nt,"decideResource");function K(t,e){return t===null||e===null?t===e:t.type===e.type&&t.id===e.id}r(K,"sameDomain");function st(t,e){return t.domain===null||K(t.domain,e)}r(st,"assignmentInDomain");function it(t,e,n){const{principal:s}=t;return s.kind==="user"?s.id===e.userId:n.some(i=>i.kind===s.kind&&(i.id===s.id||s.includeDescendants&&i.ancestors.includes(s.id))&&(s.unitRoles===null||i.role!==void 0&&s.unitRoles.includes(i.role)))}r(it,"assignmentMatches");function I(t,e){const n={};for(const[s,i]of Object.entries(e)){const a=t.permissions[s];a&&Z(a,i)===null&&(n[s]=i)}return n}r(I,"validGrants");function jt(t,e,n){const s=E(t.permissions,I(t,n)),i={};for(const[a,o]of Object.entries(s)){const d=e[a];if(d===void 0)continue;const l=t.permissions[a];i[a]=l.scopes!==null&&M(l,o)>M(l,d)?d:o}return i}r(jt,"narrowInherited");function Lt(t,e){const{[v.manage]:n,...s}=I(t,e);return E(t.permissions,s)}r(Lt,"unassignedGrants");function at(t){const{catalog:e,subject:n,roles:s,domain:i}=t,a=[],o=t.assignments.filter(c=>it(c,n,t.memberships)&&s.has(c.roleId)),d=[];for(const c of o)c.domain&&!d.some(h=>K(h,c.domain))&&d.push(c.domain);const l=o.filter(c=>st(c,i));for(const c of l){const h=s.get(c.roleId);a.push({roleId:h.id,roleKey:h.key,source:"assignment",principal:{kind:c.principal.kind,id:c.principal.id},domain:c.domain})}const m=t.inheritance?.ancestors??[],p=new Map;for(const c of o){if(c.domain===null||!m.some(O=>K(O,c.domain)))continue;const h=s.get(c.roleId),f=E(e.permissions,I(e,h.grants)),_=jt(e,f,t.inheritance.inherit(f));if(Object.keys(_).length===0)continue;const R={roleId:h.id,roleKey:h.key,source:"assignment",principal:{kind:c.principal.kind,id:c.principal.id},domain:c.domain,inherited:!0};a.push(R),p.set(R,_)}const b=new Map;for(const c of s.values())c.builtin&&c.key&&b.set(c.key,c);for(const c of n.hostRoles)for(const h of e.hostRoleBindings[c]??[]){const f=b.get(h);f&&a.push({roleId:f.id,roleKey:f.key,source:"hostRole",hostRole:c})}if(l.length===0&&t.unassignedRoleId){const c=s.get(t.unassignedRoleId);c&&a.push({roleId:c.id,roleKey:c.key,source:"unassigned"})}const w=new Map;for(const c of a){const h=s.get(c.roleId),f=p.get(c)??(c.source==="unassigned"?Lt(e,h.grants):E(e.permissions,I(e,h.grants)));for(const[_,R]of Object.entries(f)){const O=e.permissions[_],D=w.get(_),X=Mt(O,D?.value,R);D?(D.value=X,D.via.push(c)):w.set(_,{value:X,via:[c]})}}const g=new Map;if(n.agent){const c=n.agent.delegation;for(const[h,f]of w){const _=e.permissions[h].agent;_.allowed?_.requires.every(R=>c.includes(R))||g.set(h,{reason:"delegation_missing",via:f.via}):g.set(h,{reason:"agent_forbidden",via:f.via})}for(const h of g.keys())w.delete(h)}return new et(e,n,i,w,g,a,d)}r(at,"resolveGrants");var Ft=/^[a-z_][a-z0-9_]*$/,W=Symbol("tego.access.ident"),ot=Symbol("tego.access.fragment");function C(t){if(!Ft.test(t))throw new Error(`"${t}" is not a plain lower-case SQL identifier (^[a-z_][a-z0-9_]*$)`);return{[W]:t}}r(C,"ident");function Ut(t){return typeof t=="object"&&t!==null&&W in t}r(Ut,"isIdentifier");function Bt(t){return typeof t=="object"&&t!==null&&ot in t}r(Bt,"isFragment");function V(t,e){return{[ot]:!0,strings:t,values:e}}r(V,"fragment");function $(t,...e){const n=[t[0]],s=[],i=r(a=>{n[n.length-1]+=a},"append");return e.forEach((a,o)=>{Ut(a)?i(a[W]):Bt(a)?(i(a.strings[0]),a.values.forEach((d,l)=>{s.push(d),n.push(a.strings[l+1])})):(s.push(a),n.push("")),i(t[o+1])}),V(n,s)}r($,"sql");var k=V(["TRUE"],[]),j=V(["FALSE"],[]);function rt(t){const e=t.filter(s=>s!==j);if(e.includes(k))return k;if(e.length===0)return j;if(e.length===1)return e[0];let n=$`(${e[0]})`;for(const s of e.slice(1))n=$`${n} OR (${s})`;return $`(${n})`}r(rt,"orFragments");function ct(t,e=0){let n=t.strings[0];return t.values.forEach((s,i)=>{n+=`$${e+i+1}${t.strings[i+1]}`}),{text:n,params:[...t.values]}}r(ct,"renderFragment");function Gt(t,e){const n=ct(e,t.length);return{text:n.text,params:[...t,...n.params]}}r(Gt,"bindFragment");function dt(t,e){const n=t.columns?.[e];if(!n)throw new Error(`This scope filters on "${e}": pass it in ref.columns, e.g. { ${e}: 'created_by' }`);return C(n)}r(dt,"refColumn");var lt={matches:r(()=>!0,"matches"),filter:r(()=>k,"filter")},ut={matches:r((t,e)=>e.ownerId===t.userId,"matches"),filter:r((t,e)=>$`${C(e.alias)}.${dt(e,"ownerId")} = ${t.userId}`,"filter")},gt={all:lt,own:ut},ht=class extends Error{static{r(this,"AccessDeniedError")}constructor(t,e){super(e===404?"Not found":`Permission "${t.permission}" is required (${t.reason})`),this.decision=t,this.status=e,this.name="AccessDeniedError"}decision;status},S=class extends Error{static{r(this,"AccessAdminError")}constructor(t,e,n){super(n),this.status=t,this.code=e,this.name="AccessAdminError"}status;code},N=r(t=>t instanceof Date?t.toISOString():new Date(t).toISOString(),"iso");function mt(t,e){return t!==null&&e!==null?{type:t,id:e}:null}r(mt,"domainOf");function L(t){return{id:t.id,key:t.key,builtin:t.builtin,domain:mt(t.domain_type,t.domain_id),name:t.name,description:t.description,grants:t.grants,catalogVersion:t.catalog_version,createdAt:N(t.created_at),updatedAt:N(t.updated_at),updatedBy:t.updated_by}}r(L,"toRole");function F(t){return{id:t.id,roleId:t.role_id,principal:{kind:t.principal_kind,id:t.principal_id,includeDescendants:t.include_descendants,unitRoles:t.unit_roles},domain:mt(t.domain_type,t.domain_id),createdBy:t.created_by,createdAt:N(t.created_at)}}r(F,"toAssignment");var U="id, key, builtin, domain_type, domain_id, name, description, grants, catalog_version, created_at, updated_at, updated_by",B="id, role_id, principal_kind, principal_id, include_descendants, unit_roles, domain_type, domain_id, created_by, created_at";async function pt(t,e){const[n]=await t.query("SELECT unassigned_role_id, version, epoch, updated_at, updated_by FROM tego_access_settings WHERE tenant_id = $1",[e]);return n?{unassignedRoleId:n.unassigned_role_id,version:n.version,epoch:n.epoch,updatedAt:N(n.updated_at),updatedBy:n.updated_by}:null}r(pt,"readSettings");async function ft(t,e){return(await t.query(`SELECT ${U} FROM tego_access_roles WHERE tenant_id = $1 ORDER BY builtin DESC, created_at, id`,[e])).map(L)}r(ft,"listRoles");async function z(t,e,n){const[s]=await t.query(`SELECT ${U} FROM tego_access_roles WHERE tenant_id = $1 AND id = $2`,[e,n]);return s?L(s):null}r(z,"findRole");async function Pt(t,e){return(await t.query("SELECT DISTINCT principal_kind FROM tego_access_assignments WHERE tenant_id = $1",[e])).map(s=>s.principal_kind)}r(Pt,"principalKindsInUse");async function Ht(t,e,n){return n.length===0?[]:(await t.query(`SELECT ${B} FROM tego_access_assignments
+      WHERE tenant_id = $1
+        AND (principal_kind, principal_id) IN (
+          SELECT * FROM unnest($2::text[], $3::text[])
+        )`,[e,n.map(i=>i.kind),n.map(i=>i.id)])).map(F)}r(Ht,"assignmentsFor");async function yt(t,e,n){const s=["tenant_id = $1"],i=[e],a=r(d=>(i.push(d),`$${i.length}`),"param");return n.roleId&&s.push(`role_id = ${a(n.roleId)}`),n.principal&&s.push(`principal_kind = ${a(n.principal.kind)} AND principal_id = ${a(n.principal.id)}`),n.domain===null?s.push("domain_type IS NULL AND domain_id IS NULL"):n.domain&&s.push(`domain_type = ${a(n.domain.type)} AND domain_id = ${a(n.domain.id)}`),(await t.query(`SELECT ${B} FROM tego_access_assignments WHERE ${s.join(" AND ")} ORDER BY created_at, id`,i)).map(F)}r(yt,"listAssignments");async function qt(t,e,n){const[s]=await t.query(`SELECT ${B} FROM tego_access_assignments WHERE tenant_id = $1 AND id = $2`,[e,n]);return s?F(s):null}r(qt,"findAssignment");async function xt(t,e,n){const[s]=await t.query("SELECT count(*)::text AS count FROM tego_access_assignments WHERE tenant_id = $1 AND role_id = $2",[e,n]);return Number(s?.count??0)}r(xt,"countAssignments");async function wt(t,e){const n=await t.query("SELECT role_id, count(*)::text AS count FROM tego_access_assignments WHERE tenant_id = $1 GROUP BY role_id",[e]);return new Map(n.map(s=>[s.role_id,Number(s.count)]))}r(wt,"assignmentCounts");async function _t(t,e,n){const[s]=await t.query(`UPDATE tego_access_settings
+        SET version = version + 1, updated_at = now(), updated_by = $2
+      WHERE tenant_id = $1
+      RETURNING version`,[e,n]);if(!s)throw new Error("Access settings are missing: call access.reconcile(host) from the backend start hook");return s.version}r(_t,"lockAndBump");async function It(t,e,n){const[s]=await t.query(`INSERT INTO tego_access_roles
+       (id, tenant_id, key, builtin, domain_type, domain_id, name, description, grants, catalog_version, updated_by)
+     VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9::jsonb, $10, $11)
+     RETURNING ${U}`,[crypto.randomUUID(),e,n.key,n.builtin,n.domain?.type??null,n.domain?.id??null,n.name,n.description,JSON.stringify(n.grants),n.catalogVersion,n.updatedBy]);return L(s)}r(It,"insertRole");async function bt(t,e,n,s){const[i]=await t.query(`UPDATE tego_access_roles
+        SET name = $3, description = $4, grants = $5::jsonb, catalog_version = $6,
+            updated_by = $7, updated_at = now()
+      WHERE tenant_id = $1 AND id = $2
+      RETURNING ${U}`,[e,n,s.name,s.description,JSON.stringify(s.grants),s.catalogVersion,s.updatedBy]);return L(i)}r(bt,"updateRole");async function Rt(t,e,n){await t.query("DELETE FROM tego_access_roles WHERE tenant_id = $1 AND id = $2",[e,n])}r(Rt,"deleteRole");async function Kt(t,e,n){const[s]=await t.query(`INSERT INTO tego_access_assignments
+       (id, tenant_id, role_id, principal_kind, principal_id, include_descendants, unit_roles, domain_type, domain_id, created_by)
+     VALUES ($1, $2, $3, $4, $5, $6, $7::text[], $8, $9, $10)
+     ON CONFLICT DO NOTHING
+     RETURNING ${B}`,[crypto.randomUUID(),e,n.roleId,n.principal.kind,n.principal.id,n.principal.includeDescendants,n.principal.unitRoles,n.domain?.type??null,n.domain?.id??null,n.createdBy]);return s?F(s):null}r(Kt,"insertAssignment");async function Wt(t,e,n){await t.query("DELETE FROM tego_access_assignments WHERE tenant_id = $1 AND id = $2",[e,n])}r(Wt,"deleteAssignment");async function J(t,e,n){await t.query("UPDATE tego_access_settings SET unassigned_role_id = $2 WHERE tenant_id = $1",[e,n])}r(J,"writeSettings");async function G(t,e,n){await t.query(`INSERT INTO tego_access_audit (id, tenant_id, actor_id, action, target_type, target_id, before, after)
+     VALUES ($1, $2, $3, $4, $5, $6, $7::jsonb, $8::jsonb)`,[crypto.randomUUID(),e,n.actorId,n.action,n.targetType,n.targetId,n.before==null?null:JSON.stringify(n.before),n.after==null?null:JSON.stringify(n.after)])}r(G,"appendAudit");async function Vt(t,e,n){const s=await t.query(`SELECT id, actor_id, action, target_type, target_id, before, after, at
+       FROM tego_access_audit WHERE tenant_id = $1
+      ORDER BY at DESC, id DESC OFFSET $2 LIMIT $3`,[e,n.offset,n.limit+1]);return{items:s.slice(0,n.limit).map(i=>({id:i.id,actorId:i.actor_id,action:i.action,targetType:i.target_type,targetId:i.target_id,before:i.before,after:i.after,at:N(i.at)})),hasMore:s.length>n.limit}}r(Vt,"listAudit");var vt=class{static{r(this,"Lru")}constructor(t){this.max=t}max;map=new Map;get(t){const e=this.map.get(t);return e!==void 0&&(this.map.delete(t),this.map.set(t,e)),e}set(t,e){this.map.delete(t),this.map.set(t,e),this.map.size>this.max&&this.map.delete(this.map.keys().next().value)}},P=r(()=>new Error('Access reads people and units from the host directory: declare "directory.read" in the manifest'),"directoryRequired"),Et={kind:"user",memberships:r(async()=>[],"memberships"),list:r(async(t,e)=>{if(!t.directory)throw P();const n=await t.directory.list({kind:"users",...e});return{items:n.items.map(s=>({id:s.id,displayName:s.displayName,active:s.active})),hasMore:n.hasMore}},"list")},$t={kind:"unit",memberships:r(async(t,e)=>{if(!e.directory)throw P();return(await e.directory.identity(t.userId)).memberships.map(s=>({kind:"unit",id:s.unitId,ancestors:s.ancestors,role:s.role}))},"memberships"),list:r(async(t,e)=>{if(!t.directory)throw P();const n=await t.directory.list({kind:"units",...e});return{items:n.items.map(s=>({id:s.id,displayName:s.displayName,parentId:s.parentId??null,active:s.active})),hasMore:n.hasMore}},"list")};function kt(t){return t?`${t.type}:${t.id}`:""}r(kt,"domainKey");var St=class{static{r(this,"AccessEngine")}catalog;evaluators;principalSources;domainSources;hooks;tenantCache=new vt(32);assignmentCache;constructor(t){this.catalog=t.catalog;const e=new Map(Object.entries({...gt,...t.evaluators}));for(const i of Object.keys(this.catalog.scopes))if(!e.has(i))throw new Error(`Scope "${i}" has no evaluator: pass one in "evaluators"`);this.evaluators=e;const n=new Map([["user",Et],["unit",$t]]);for(const i of t.principals??[])n.set(i.kind,i);for(const i of this.catalog.assignment.principals)if(!n.has(i))throw new Error(`Principal kind "${i}" has no source: pass one in "principals"`);this.principalSources=n;const s=new Map(Object.entries(t.domains??{}));for(const[i,a]of Object.entries(this.catalog.domains)){const o=s.get(i);if(!o)throw new Error(`Domain type "${i}" has no source: pass one in "domains"`);if(a.hierarchical&&(!o.ancestors||!o.inherit))throw new Error(`Domain type "${i}" is hierarchical: its source needs "ancestors" and "inherit"`)}this.domainSources=s,this.hooks=t.hooks??{},this.assignmentCache=new vt(t.cacheSize??2e3)}forRequest(t,e){if(t.tenantId!==e.tenantId)throw new Error("The request names a tenant this install does not serve");return new Y(this,tt(t),e)}forSubject(t,e){if(t.tenantId!==e.tenantId)throw new Error("The subject names a tenant this install does not serve");return new Y(this,t,e)}async subjectFor(t,e){if(!e.directory)throw P();const n=await e.directory.identity(t);return n.active?{tenantId:e.tenantId,userId:t,hostRoles:n.roleNames}:null}async tenantState(t){const e=t.tenantId,n=await pt(t.db,e);if(!n)throw new Error("Access is not set up for this tenant: call access.reconcile(host) from the backend start hook");const s=`${e}:${n.epoch}:${n.version}`,i=this.tenantCache.get(s);if(i)return{...i,settings:n};const[a,o]=await Promise.all([ft(t.db,e),Pt(t.db,e)]),d={settings:n,roles:new Map(a.map(l=>[l.id,l])),kinds:o};return this.tenantCache.set(s,d),d}async assignments(t,e,n){const s=`${t.tenantId}:${e.epoch}:${e.version}:${n.map(o=>`${o.kind}/${o.id}`).sort().join(",")}`,i=this.assignmentCache.get(s);if(i)return i;const a=await Ht(t.db,t.tenantId,n);return this.assignmentCache.set(s,a),a}async reconcile(t){const e=t.tenantId;return t.db.transaction(async n=>{await n.query("SELECT pg_advisory_xact_lock(hashtext($1))",[`tego_access:${e}`]);const i=(await n.query(`INSERT INTO tego_access_settings (tenant_id, unassigned_role_id, version, epoch)
+         VALUES ($1, NULL, 0, $2) ON CONFLICT (tenant_id) DO NOTHING RETURNING tenant_id`,[e,crypto.randomUUID()])).length>0;await n.query("SELECT 1 FROM tego_access_settings WHERE tenant_id = $1 FOR UPDATE",[e]);const a=await ft(n,e),o=await pt(n,e),d=new Map(a.filter(g=>g.builtin).map(g=>[g.key,g])),l={created:[],updated:[],retired:[],staleGrants:[]},m=(()=>{let g=!1;return async()=>{g||(g=!0,await _t(n,e,null))}})(),p=new Map;for(const g of Object.values(this.catalog.roles)){const c=d.get(g.key);if(!c){await m();const h=await It(n,e,{key:g.key,builtin:!0,domain:null,name:g.key,description:"",grants:g.grants,catalogVersion:this.catalog.version,updatedBy:null});p.set(g.key,h.id),l.created.push(g.key),await G(n,e,{actorId:null,action:"role.create",targetType:"role",targetId:h.id,before:null,after:{key:h.key,grants:h.grants}});continue}p.set(g.key,c.id),(c.catalogVersion!==this.catalog.version||!zt(c.grants,g.grants))&&(await m(),await bt(n,e,c.id,{name:g.key,description:"",grants:g.grants,catalogVersion:this.catalog.version,updatedBy:null}),l.updated.push(g.key),await G(n,e,{actorId:null,action:"role.update",targetType:"role",targetId:c.id,before:{grants:c.grants},after:{grants:g.grants}}))}const b=this.catalog.defaults.unassigned?p.get(this.catalog.defaults.unassigned):null;for(const[g,c]of d)this.catalog.roles[g]||(await m(),o.unassignedRoleId===c.id&&await J(n,e,b),await Rt(n,e,c.id),l.retired.push(g),await G(n,e,{actorId:null,action:"role.delete",targetType:"role",targetId:c.id,before:{key:g,grants:c.grants},after:null}),await this.hooks.onChange?.(n,{type:"role.deleted",role:c},{tenantId:e,host:t}));i&&(await m(),await J(n,e,b));for(const g of a)if(!g.builtin)for(const[c,h]of Object.entries(g.grants)){const f=this.catalog.permissions[c];(!f||(f.scopes===null?h!==!0:typeof h!="string"||!f.scopes.includes(h)))&&l.staleGrants.push({roleId:g.id,permission:c})}return l.created.length+l.updated.length+l.retired.length>0&&await this.hooks.onChange?.(n,{type:"catalog.reconciled",report:l},{tenantId:e,host:t}),l.staleGrants.length>0&&t.log.warn("Custom roles hold grants the access catalog no longer has",{staleGrants:l.staleGrants}),l})}};function zt(t,e){const n=Object.keys(t);return n.length===Object.keys(e).length&&n.every(s=>t[s]===e[s])}r(zt,"sameGrants");var Y=class{static{r(this,"AccessSession")}constructor(t,e,n){this.engine=t,this.subject=e,this.host=n}engine;subject;host;state;memberships;grantsByDomain=new Map;tenant(){return this.state??=this.engine.tenantState(this.host),this.state}async loadMemberships(t){return this.memberships??=(async()=>(await Promise.all(t.filter(n=>n!=="user").map(n=>{const s=this.engine.principalSources.get(n);return s?s.memberships(this.subject,this.host):(this.host.log.warn("An assignment names a principal kind with no source",{kind:n}),[])}))).flat())(),this.memberships}async inheritance(t){if(!t||!this.engine.catalog.domains[t.type]?.hierarchical)return null;const e=this.engine.domainSources.get(t.type);return{ancestors:(await e.ancestors(t.id,this.host)).map(s=>({type:t.type,id:s})),inherit:r(s=>e.inherit(s),"inherit")}}grants(t=null){const e=kt(t);let n=this.grantsByDomain.get(e);return n||(n=(async()=>{const s=await this.tenant(),i=await this.loadMemberships(s.kinds),a=[{kind:"user",id:this.subject.userId}];for(const l of i){a.push({kind:l.kind,id:l.id});for(const m of l.ancestors)a.push({kind:l.kind,id:m})}const[o,d]=await Promise.all([this.engine.assignments(this.host,s.settings,a),this.inheritance(t)]);return at({catalog:this.engine.catalog,subject:this.subject,roles:s.roles,assignments:o,memberships:i,unassignedRoleId:s.settings.unassignedRoleId,domain:t,...d?{inheritance:d}:{}})})(),this.grantsByDomain.set(e,n)),n}async can(t,e={}){return(await this.grants(e.domain)).can(t)}async holdsAnywhere(t){const e=await this.grants();if(e.can(t))return!0;for(const n of e.assignedDomains)if((await this.grants(n)).can(t))return!0;return!1}async scope(t,e={}){return(await this.grants(e.domain)).scope(t)}async authorize(t,e,n={}){const s=await this.grants(n.domain);return nt(s,t,e,i=>this.engine.evaluators.get(i).matches(this.subject,e,{host:this.host,permission:t}))}async assert(t,e,n={}){const s=await this.authorize(t,e,n);if(!s.allowed)throw new ht(s,s.reason==="scope_mismatch"&&n.conceal?404:403);return s}async filter(t,e,n={}){C(e.alias);const s=await this.grants(n.domain);if(!s.can(t))return j;const i=s.scope(t);if(i===null)return k;const a=this.engine.catalog.permissions[t].scopes;return rt(a.slice(0,a.indexOf(i)+1).map(o=>this.engine.evaluators.get(o).filter(this.subject,e)))}async snapshot(t={}){const e=await this.grants(t.domain),n=await this.tenant(),s=this.engine.catalog,i=[];for(const o of e.sources){if(i.some(l=>l.id===o.roleId&&l.source===o.source))continue;const d=n.roles.get(o.roleId);i.push({id:d.id,key:d.key,builtin:d.builtin,name:d.name,nameKey:d.key?s.roles[d.key]?.nameKey??null:null,source:o.source,...o.hostRole?{hostRole:o.hostRole}:{}})}const a={};for(const o of e.assignedDomains)(a[o.type]??=[]).push(o.id);return{userId:this.subject.userId,agent:this.subject.agent!==void 0,catalogVersion:s.version,domain:t.domain??null,permissions:e.permissions(),menus:Object.fromEntries(Object.entries(s.menus).map(([o,d])=>[o,d.some(l=>e.can(l))])),roles:i,domains:a}}async manages(t={}){return(await this.grants(t.domain)).can(v.manage)}};function Jt(t){return new St(t)}r(Jt,"createAccess");var T=/^[a-z][a-z0-9_]*$/,Yt=["owner","admin","member","viewer"],H=u.object({type:u.string().regex(T),id:u.string().min(1).max(200)}).strict(),Nt=u.record(u.string(),u.union([u.literal(!0),u.string().regex(T)])),Qt=u.object({name:u.string().trim().min(1).max(80),description:u.string().trim().max(500).default(""),grants:Nt,domain:H.nullable().default(null)}).strict(),Xt=u.object({name:u.string().trim().min(1).max(80).optional(),description:u.string().trim().max(500).optional(),grants:Nt.optional()}).strict(),Zt=u.object({name:u.string().trim().min(1).max(80),domain:H.nullable().optional()}).strict(),te=u.object({roleId:u.string().min(1),principal:u.object({kind:u.string().regex(T),id:u.string().min(1).max(200),includeDescendants:u.boolean().default(!1),unitRoles:u.array(u.enum(Yt)).min(1).nullable().default(null)}).strict(),domain:H.nullable().default(null)}).strict(),ee=u.object({roleId:u.string().min(1).optional(),principalKind:u.string().regex(T).optional(),principalId:u.string().min(1).optional()}).strict(),ne=u.object({kind:u.string().regex(T),search:u.string().max(200).optional(),ids:u.array(u.string().min(1)).min(1).max(100).optional(),offset:u.number().int().min(0).default(0),limit:u.number().int().min(1).max(100).default(50)}).strict(),se=u.object({unassignedRoleId:u.string().min(1).nullable()}).strict(),ie=u.object({offset:u.number().int().min(0).default(0),limit:u.number().int().min(1).max(200).default(50)}).strict(),q=r((t,e)=>new S(403,t,e),"forbidden"),y=r((t,e)=>new S(400,t,e),"badRequest"),A=r((t,e)=>new S(409,t,e),"conflict"),x=r(t=>new S(404,"not_found",`${t} not found`),"notFound");function Q(t,e){return t===null||e===null?t===e:t.type===e.type&&t.id===e.id}r(Q,"sameDomain2");function Tt(t,e,n){const s=E(t.permissions,I(t,n)),i=[];for(const[a,o]of Object.entries(s)){const d=t.permissions[a],l=e.value(a);(l===void 0||d.scopes!==null&&M(d,l)<M(d,o))&&i.push(a)}return i}r(Tt,"uncoveredGrants");var ae=class{static{r(this,"AccessAdmin")}constructor(t){this.session=t}session;get engine(){return this.session.engine}get catalog(){return this.session.engine.catalog}get host(){return this.session.host}get tenantId(){return this.session.subject.tenantId}get actorId(){return this.session.subject.userId}async manager(t){const e=await this.session.grants(t);if(!e.can(v.manage))throw q("permission_required",`Permission "${v.manage}" is required`);return e}assertCovers(t,e){if(t.managesThroughHostRole())return;const n=Tt(this.catalog,t,e);if(n.length>0)throw q("escalation_denied",`You can only grant what you hold yourself. Missing: ${n.join(", ")}`)}async assertDomain(t){if(!t)return;if(!this.catalog.domains[t.type])throw y("unknown_domain",`Unknown domain type "${t.type}"`);if(!(await this.engine.domainSources.get(t.type).describe([t.id],this.host)).has(t.id))throw y("domain_not_found",`${t.type} "${t.id}" does not exist`)}validateGrants(t,e={}){const n=[];for(const[s,i]of Object.entries(t)){const a=this.catalog.permissions[s];if(!a){n.push(`${s}: unknown permission`);continue}a.deprecated&&e[s]===void 0&&n.push(`${s}: deprecated, cannot be newly granted`);const o=Z(a,i);o&&n.push(`${s}: ${o}`)}if(n.length>0)throw y("invalid_grants",n.join("; "));return t}async write(t){return this.host.db.transaction(async e=>(await _t(e,this.tenantId,this.actorId),t(e,n=>this.engine.hooks.onChange?.(e,n,{tenantId:this.tenantId,host:this.host})??Promise.resolve(),n=>G(e,this.tenantId,{actorId:this.actorId,...n}))))}async role(t){const e=await z(this.host.db,this.tenantId,t);if(!e)throw x("Role");return e}view(t,e,n){const s=t.key?this.catalog.roles[t.key]:void 0,i=I(this.catalog,t.grants);return{id:t.id,key:t.key,builtin:t.builtin,domain:t.domain,name:t.name,nameKey:s?.nameKey??null,description:t.description,descriptionKey:s?.descriptionKey??null,grants:i,assignableBy:s?.assignableBy??"access-manager",exemptFromRoleLimit:s?.exemptFromRoleLimit??!1,assignmentCount:e.get(t.id)??0,isDefault:t.id===n,staleGrants:Object.keys(t.grants).filter(a=>!(a in i)),updatedAt:t.updatedAt,updatedBy:t.updatedBy}}async catalogView(t){return await this.manager(t),this.catalog}async listRoles(t){await this.manager(t);const e=await this.session.tenant(),n=await wt(this.host.db,this.tenantId);return[...e.roles.values()].filter(s=>s.domain===null||Q(s.domain,t)).map(s=>this.view(s,n,e.settings.unassignedRoleId))}async createRole(t){const e=await this.manager(t.domain);await this.assertDomain(t.domain);const n=this.validateGrants(t.grants);return this.assertCovers(e,n),this.write(async(s,i,a)=>{await this.assertNameFree(s,t.name,t.domain,null);const o=await It(s,this.tenantId,{key:null,builtin:!1,domain:t.domain,name:t.name,description:t.description,grants:n,catalogVersion:this.catalog.version,updatedBy:this.actorId});return await a({action:"role.create",targetType:"role",targetId:o.id,before:null,after:{name:o.name,domain:o.domain,grants:o.grants}}),await i({type:"role.created",role:o}),this.view(o,new Map,null)})}async assertNameFree(t,e,n,s){if((await t.query(`SELECT id FROM tego_access_roles
+        WHERE tenant_id = $1 AND NOT builtin AND lower(name) = lower($2)
+          AND domain_type IS NOT DISTINCT FROM $3 AND domain_id IS NOT DISTINCT FROM $4
+          AND id IS DISTINCT FROM $5`,[this.tenantId,e,n?.type??null,n?.id??null,s])).length>0)throw A("role_name_taken",`A role named "${e}" already exists`)}async updateRole(t,e){const n=await this.role(t);if(n.builtin)throw y("builtin_locked","Built-in roles follow the plugin catalog; clone one to change it");const s=await this.manager(n.domain),i=e.grants?this.validateGrants(e.grants,n.grants):I(this.catalog,n.grants);return this.assertCovers(s,I(this.catalog,n.grants)),this.assertCovers(s,i),this.write(async(a,o,d)=>{const[l]=await a.query("SELECT unassigned_role_id FROM tego_access_settings WHERE tenant_id = $1",[this.tenantId]);l?.unassigned_role_id===t&&this.assertDefaultMayHold(i);const m=e.name??n.name;e.name&&await this.assertNameFree(a,m,n.domain,t);const p=await bt(a,this.tenantId,t,{name:m,description:e.description??n.description,grants:i,catalogVersion:this.catalog.version,updatedBy:this.actorId});await d({action:"role.update",targetType:"role",targetId:t,before:{name:n.name,description:n.description,grants:n.grants},after:{name:p.name,description:p.description,grants:p.grants}}),await o({type:"role.updated",role:p,before:n});const b=await wt(a,this.tenantId);return this.view(p,b,l?.unassigned_role_id??null)})}async deleteRole(t){const e=await this.role(t);if(e.builtin)throw y("builtin_locked","Built-in roles cannot be deleted");const n=await this.manager(e.domain);this.assertCovers(n,e.grants),await this.write(async(s,i,a)=>{if(await xt(s,this.tenantId,t)>0)throw A("role_in_use","Remove the role from everyone holding it first");const[o]=await s.query("SELECT unassigned_role_id FROM tego_access_settings WHERE tenant_id = $1",[this.tenantId]);if(o?.unassigned_role_id===t)throw A("role_is_default","This role is what unassigned users get; choose another default first");await Rt(s,this.tenantId,t),await a({action:"role.delete",targetType:"role",targetId:t,before:{name:e.name,domain:e.domain,grants:e.grants},after:null}),await i({type:"role.deleted",role:e})})}async cloneRole(t,e){const n=await this.role(t),s=e.domain===void 0?n.domain:e.domain;if(n.domain&&!Q(n.domain,s))throw y("domain_mismatch","A role of one domain can only be cloned within that domain");return this.createRole({name:e.name,description:n.description,grants:I(this.catalog,n.grants),domain:s})}async principalNames(t){const e=new Map;for(const s of t)e.has(s.kind)||e.set(s.kind,new Set),e.get(s.kind).add(s.id);const n=new Map;return await Promise.all([...e].map(async([s,i])=>{const a=this.engine.principalSources.get(s);if(!a)return;const o=[...i];for(let d=0;d<o.length;d+=100){const l=o.slice(d,d+100),m=await a.list(this.host,{ids:l,offset:0,limit:l.length});for(const p of m.items)n.set(`${s}/${p.id}`,p.displayName)}})),n}async domainNames(t){const e=new Map,n=new Map;for(const s of t)n.has(s.type)||n.set(s.type,new Set),n.get(s.type).add(s.id);return await Promise.all([...n].map(async([s,i])=>{const a=this.engine.domainSources.get(s);if(a)for(const[o,d]of await a.describe([...i],this.host))e.set(`${s}:${o}`,d)})),e}async listAssignments(t,e){await this.manager(t);const n=await yt(this.host.db,this.tenantId,{...e.roleId?{roleId:e.roleId}:{},...e.principalKind&&e.principalId?{principal:{kind:e.principalKind,id:e.principalId}}:{},domain:t}),[s,i]=await Promise.all([this.principalNames(n.map(a=>a.principal)),this.domainNames(n.flatMap(a=>a.domain?[a.domain]:[]))]);return n.map(a=>({...a,principalName:s.get(`${a.principal.kind}/${a.principal.id}`)??null,domainName:a.domain?i.get(`${a.domain.type}:${a.domain.id}`)??null:null}))}assertDefaultMayHold(t){if(v.manage in E(this.catalog.permissions,I(this.catalog,t)))throw y("default_role_manages","The default role cannot manage access: every user would")}assertMayAssign(t,e){if((e.key?this.catalog.roles[e.key]:void 0)?.assignableBy==="host-admin"&&!t.managesThroughHostRole())throw q("host_admin_required","Only a host administrator can assign or remove this role");this.assertCovers(t,e.grants)}async createAssignment(t){const e=await this.role(t.roleId),{principal:n,domain:s}=t;if(e.domain&&!Q(e.domain,s))throw y("domain_mismatch","This role belongs to one domain and can only be assigned there");const i=await this.manager(s);if(await this.assertDomain(s),!this.catalog.assignment.principals.includes(n.kind))throw y("principal_kind_not_allowed",`Roles cannot be assigned to "${n.kind}" in this plugin`);if(n.kind==="user"&&(n.includeDescendants||n.unitRoles))throw y("invalid_principal","includeDescendants and unitRoles apply to units and groups only");if(n.kind!=="unit"&&n.unitRoles)throw y("invalid_principal","unitRoles apply to host units only");this.assertMayAssign(i,e);const o=(await this.principalNames([n])).get(`${n.kind}/${n.id}`);if(o===void 0)throw y("principal_not_found",`${n.kind} "${n.id}" does not exist`);const d=e.key?this.catalog.roles[e.key]:void 0,l=this.catalog.assignment.maxRolesPerPrincipal[s?s.type:Ot];return this.write(async(m,p,b)=>{if(n.kind==="user"&&l!==void 0&&!d?.exemptFromRoleLimit){const c=await yt(m,this.tenantId,{principal:{kind:"user",id:n.id},domain:s}),h=await this.session.tenant();if(c.filter(_=>{const R=h.roles.get(_.roleId);return!(R?.key?this.catalog.roles[R.key]:void 0)?.exemptFromRoleLimit}).length>=l)throw A("role_limit_reached",`A user can hold at most ${l} role(s) here; remove the current one first`)}const w=await Kt(m,this.tenantId,{roleId:e.id,principal:n,domain:s,createdBy:this.actorId});if(!w)throw A("already_assigned","This role is already assigned to them here");await b({action:"assignment.create",targetType:"assignment",targetId:w.id,before:null,after:{roleId:e.id,principal:n,domain:s}}),await p({type:"assignment.created",assignment:w});const g=await this.domainNames(s?[s]:[]);return{...w,principalName:o,domainName:s?g.get(`${s.type}:${s.id}`)??null:null}})}async deleteAssignment(t){const e=await qt(this.host.db,this.tenantId,t);if(!e)throw x("Assignment");const n=await this.role(e.roleId),s=await this.manager(e.domain);this.assertMayAssign(s,n),await this.write(async(i,a,o)=>{await Wt(i,this.tenantId,t),await o({action:"assignment.delete",targetType:"assignment",targetId:t,before:{roleId:e.roleId,principal:e.principal,domain:e.domain},after:null}),await a({type:"assignment.deleted",assignment:e})})}async principals(t,e){if(await this.manager(t),!this.catalog.assignment.principals.includes(e.kind))throw y("principal_kind_not_allowed",`Roles cannot be assigned to "${e.kind}" in this plugin`);return this.engine.principalSources.get(e.kind).list(this.host,{...e.search?{search:e.search}:{},...e.ids?{ids:e.ids}:{},offset:e.offset,limit:e.limit})}async explain(t,e){await this.manager(e);const n=await this.engine.subjectFor(t,this.host);if(!n)throw x("Active user");const s=await this.engine.forSubject(n,this.host).grants(e),i=await this.session.tenant();return{userId:t,domain:e,roles:s.sources.map(a=>{const o=i.roles.get(a.roleId);return{...a,name:o.name,nameKey:o.key?this.catalog.roles[o.key]?.nameKey??null:null}}),permissions:Object.keys(this.catalog.permissions).map(a=>{const{allowed:o,scope:d,reason:l,via:m}=s.decide(a);return{permission:a,allowed:o,scope:d,reason:l,via:m}})}}async settings(){await this.manager(null);const{unassignedRoleId:t,version:e,updatedAt:n,updatedBy:s}=(await this.session.tenant()).settings;return{unassignedRoleId:t,version:e,updatedAt:n,updatedBy:s}}async updateSettings(t){const e=await this.manager(null),n=(await this.session.tenant()).settings;if(n.unassignedRoleId!==null){const s=await z(this.host.db,this.tenantId,n.unassignedRoleId);s&&this.assertMayAssign(e,s)}if(t.unassignedRoleId!==null){const s=await this.role(t.unassignedRoleId);if(s.domain)throw y("domain_role","The default role must be a global role");this.assertMayAssign(e,s)}return this.write(async(s,i,a)=>{if(t.unassignedRoleId!==null){const d=await z(s,this.tenantId,t.unassignedRoleId);if(!d)throw x("Role");this.assertDefaultMayHold(d.grants)}await J(s,this.tenantId,t.unassignedRoleId),await a({action:"settings.update",targetType:"settings",targetId:this.tenantId,before:{unassignedRoleId:n.unassignedRoleId},after:{unassignedRoleId:t.unassignedRoleId}}),await i({type:"settings.updated",before:{unassignedRoleId:n.unassignedRoleId},after:{unassignedRoleId:t.unassignedRoleId}});const[o]=await s.query("SELECT version, updated_at, updated_by FROM tego_access_settings WHERE tenant_id = $1",[this.tenantId]);return{unassignedRoleId:t.unassignedRoleId,version:o.version,updatedAt:new Date(o.updated_at).toISOString(),updatedBy:o.updated_by}})}async audit(t){if(!(await this.session.grants(null)).can(v.audit))throw q("permission_required",`Permission "${v.audit}" is required`);const n=await Vt(this.host.db,this.tenantId,t),s=await this.principalNames(n.items.flatMap(i=>i.actorId?[{kind:"user",id:i.actorId}]:[]));return{...n,items:n.items.map(i=>({...i,actorName:i.actorId?s.get(`user/${i.actorId}`)??null:null}))}}};function oe(){return Ct(Dt,{name:"TegoAccessCatalog",$refStrategy:"none"})}r(oe,"accessCatalogJsonSchema");export{ae as AccessAdmin,S as AccessAdminError,ht as AccessDeniedError,St as AccessEngine,Y as AccessSession,gt as BUILTIN_SCOPES,et as EffectiveGrants,j as FALSE_FRAGMENT,k as TRUE_FRAGMENT,oe as accessCatalogJsonSchema,lt as allScope,st as assignmentInDomain,it as assignmentMatches,ee as assignmentQuerySchema,ie as auditQuerySchema,Gt as bindFragment,Zt as cloneRoleInputSchema,Jt as createAccess,te as createAssignmentInputSchema,Qt as createRoleInputSchema,nt as decideResource,H as domainInputSchema,kt as domainKey,C as ident,rt as orFragments,ut as ownScope,ne as principalQuerySchema,dt as refColumn,ct as renderFragment,at as resolveGrants,$ as sql,tt as subjectFromContext,Tt as uncoveredGrants,$t as unitPrincipalSource,Xt as updateRoleInputSchema,se as updateSettingsInputSchema,Et as userPrincipalSource,I as validGrants};

package/dist/catalog-CSSbrfEf.d.cts

@@ -0,0 +1,361 @@
+import { z } from 'zod';
+
+/**
+ * The access catalog: everything a plugin declares about its own permissions.
+ *
+ * One JSON document per plugin (`access.json`, referenced from the manifest's
+ * `access.catalog`), read the same way by the TypeScript and the Python
+ * runtime. It is data rather than code so the pack step can validate it for
+ * either runtime, and so a TypeScript plugin importing it still gets its
+ * permission keys as literal types — JSON imports keep property names.
+ *
+ * What lives here is the *vocabulary*: permissions, their scope ladders, the
+ * roles the plugin ships, which host roles map onto them, and who a user is
+ * when nobody assigned them anything. Who holds which custom role is tenant
+ * data and lives in the `tego_access_*` tables.
+ */
+
+/**
+ * The actions a person can delegate to a digital employee.
+ *
+ * Mirrors `PluginUserContext.delegation.actions`; widening that union widens
+ * this one, and the catalog then accepts the new action.
+ */
+declare const DELEGATION_ACTIONS: readonly ["records.read", "work.prepare"];
+type DelegationAction = (typeof DELEGATION_ACTIONS)[number];
+/** Permissions every catalog has, owned by the SDK's admin API. */
+declare const RESERVED_PERMISSIONS: {
+    readonly manage: "access.manage";
+    readonly audit: "access.audit";
+};
+declare const RESERVED_GROUP = "access";
+/**
+ * The host role that must always be able to manage access.
+ *
+ * A tenant's administrators install plugins; a catalog that left them unable
+ * to reach the access settings would leave a tenant with no way back in once
+ * the last plugin-side manager was removed.
+ */
+declare const HOST_ADMIN_ROLE = "admin";
+/** Built-in principal kinds; a catalog may add its own (CRM's departments). */
+declare const BUILTIN_PRINCIPAL_KINDS: readonly ["user", "unit"];
+/** The pseudo domain type naming global assignments in role limits. */
+declare const GLOBAL_DOMAIN = "global";
+declare const accessCatalogSchema: z.ZodObject<{
+    $schema: z.ZodOptional<z.ZodString>;
+    /** Bumped by the plugin when the meaning of the catalog changes. */
+    version: z.ZodNumber;
+    groups: z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        labelKey: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        key: string;
+        labelKey: string;
+    }, {
+        key: string;
+        labelKey: string;
+    }>, "many">;
+    scopes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        labelKey: z.ZodString;
+        descriptionKey: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        labelKey: string;
+        descriptionKey?: string | undefined;
+    }, {
+        labelKey: string;
+        descriptionKey?: string | undefined;
+    }>>>;
+    permissions: z.ZodRecord<z.ZodString, z.ZodObject<{
+        group: z.ZodString;
+        labelKey: z.ZodString;
+        descriptionKey: z.ZodOptional<z.ZodString>;
+        /** Ordered from narrowest to widest; holding one includes those before it. */
+        scopes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        implies: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        /** Absent means a digital employee never holds this permission. */
+        agent: z.ZodOptional<z.ZodUnion<[z.ZodObject<{
+            allowed: z.ZodLiteral<false>;
+        }, "strict", z.ZodTypeAny, {
+            allowed: false;
+        }, {
+            allowed: false;
+        }>, z.ZodObject<{
+            requires: z.ZodArray<z.ZodEnum<["records.read", "work.prepare"]>, "many">;
+        }, "strict", z.ZodTypeAny, {
+            requires: ("records.read" | "work.prepare")[];
+        }, {
+            requires: ("records.read" | "work.prepare")[];
+        }>]>>;
+        /** Still honoured on existing roles; no longer offered for new grants. */
+        deprecated: z.ZodOptional<z.ZodBoolean>;
+    }, "strict", z.ZodTypeAny, {
+        group: string;
+        labelKey: string;
+        descriptionKey?: string | undefined;
+        scopes?: string[] | undefined;
+        implies?: string[] | undefined;
+        agent?: {
+            allowed: false;
+        } | {
+            requires: ("records.read" | "work.prepare")[];
+        } | undefined;
+        deprecated?: boolean | undefined;
+    }, {
+        group: string;
+        labelKey: string;
+        descriptionKey?: string | undefined;
+        scopes?: string[] | undefined;
+        implies?: string[] | undefined;
+        agent?: {
+            allowed: false;
+        } | {
+            requires: ("records.read" | "work.prepare")[];
+        } | undefined;
+        deprecated?: boolean | undefined;
+    }>>;
+    /**
+     * Navigation key → the permission that reveals it, or a list of which any
+     * one does. Unlisted keys are always shown.
+     */
+    menus: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodString, "many">]>>>;
+    roles: z.ZodRecord<z.ZodString, z.ZodObject<{
+        nameKey: z.ZodString;
+        descriptionKey: z.ZodOptional<z.ZodString>;
+        grants: z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodLiteral<true>, z.ZodString]>>;
+        /** `host-admin`: only someone managing access through a host role may assign it. */
+        assignableBy: z.ZodOptional<z.ZodEnum<["access-manager", "host-admin"]>>;
+        /** Not counted against `assignment.maxRolesPerPrincipal`. */
+        exemptFromRoleLimit: z.ZodOptional<z.ZodBoolean>;
+    }, "strict", z.ZodTypeAny, {
+        nameKey: string;
+        grants: Record<string, string | true>;
+        descriptionKey?: string | undefined;
+        assignableBy?: "access-manager" | "host-admin" | undefined;
+        exemptFromRoleLimit?: boolean | undefined;
+    }, {
+        nameKey: string;
+        grants: Record<string, string | true>;
+        descriptionKey?: string | undefined;
+        assignableBy?: "access-manager" | "host-admin" | undefined;
+        exemptFromRoleLimit?: boolean | undefined;
+    }>>;
+    /** Host role name → the built-in roles every holder of it has. */
+    hostRoleBindings: z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString, "many">>;
+    defaults: z.ZodObject<{
+        /** The built-in role of a user nobody assigned anything, or null for none. */
+        unassigned: z.ZodNullable<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        unassigned: string | null;
+    }, {
+        unassigned: string | null;
+    }>;
+    domains: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        labelKey: z.ZodString;
+        hierarchical: z.ZodOptional<z.ZodBoolean>;
+    }, "strict", z.ZodTypeAny, {
+        labelKey: string;
+        hierarchical?: boolean | undefined;
+    }, {
+        labelKey: string;
+        hierarchical?: boolean | undefined;
+    }>>>;
+    assignment: z.ZodObject<{
+        principals: z.ZodArray<z.ZodString, "many">;
+        /** Per domain type (or `global`): direct roles one user may hold there. */
+        maxRolesPerPrincipal: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+    }, "strict", z.ZodTypeAny, {
+        principals: string[];
+        maxRolesPerPrincipal?: Record<string, number> | undefined;
+    }, {
+        principals: string[];
+        maxRolesPerPrincipal?: Record<string, number> | undefined;
+    }>;
+}, "strict", z.ZodTypeAny, {
+    version: number;
+    permissions: Record<string, {
+        group: string;
+        labelKey: string;
+        descriptionKey?: string | undefined;
+        scopes?: string[] | undefined;
+        implies?: string[] | undefined;
+        agent?: {
+            allowed: false;
+        } | {
+            requires: ("records.read" | "work.prepare")[];
+        } | undefined;
+        deprecated?: boolean | undefined;
+    }>;
+    groups: {
+        key: string;
+        labelKey: string;
+    }[];
+    roles: Record<string, {
+        nameKey: string;
+        grants: Record<string, string | true>;
+        descriptionKey?: string | undefined;
+        assignableBy?: "access-manager" | "host-admin" | undefined;
+        exemptFromRoleLimit?: boolean | undefined;
+    }>;
+    hostRoleBindings: Record<string, string[]>;
+    defaults: {
+        unassigned: string | null;
+    };
+    assignment: {
+        principals: string[];
+        maxRolesPerPrincipal?: Record<string, number> | undefined;
+    };
+    scopes?: Record<string, {
+        labelKey: string;
+        descriptionKey?: string | undefined;
+    }> | undefined;
+    $schema?: string | undefined;
+    menus?: Record<string, string | string[]> | undefined;
+    domains?: Record<string, {
+        labelKey: string;
+        hierarchical?: boolean | undefined;
+    }> | undefined;
+}, {
+    version: number;
+    permissions: Record<string, {
+        group: string;
+        labelKey: string;
+        descriptionKey?: string | undefined;
+        scopes?: string[] | undefined;
+        implies?: string[] | undefined;
+        agent?: {
+            allowed: false;
+        } | {
+            requires: ("records.read" | "work.prepare")[];
+        } | undefined;
+        deprecated?: boolean | undefined;
+    }>;
+    groups: {
+        key: string;
+        labelKey: string;
+    }[];
+    roles: Record<string, {
+        nameKey: string;
+        grants: Record<string, string | true>;
+        descriptionKey?: string | undefined;
+        assignableBy?: "access-manager" | "host-admin" | undefined;
+        exemptFromRoleLimit?: boolean | undefined;
+    }>;
+    hostRoleBindings: Record<string, string[]>;
+    defaults: {
+        unassigned: string | null;
+    };
+    assignment: {
+        principals: string[];
+        maxRolesPerPrincipal?: Record<string, number> | undefined;
+    };
+    scopes?: Record<string, {
+        labelKey: string;
+        descriptionKey?: string | undefined;
+    }> | undefined;
+    $schema?: string | undefined;
+    menus?: Record<string, string | string[]> | undefined;
+    domains?: Record<string, {
+        labelKey: string;
+        hierarchical?: boolean | undefined;
+    }> | undefined;
+}>;
+type AccessCatalogInput = z.input<typeof accessCatalogSchema>;
+type GrantValue = true | string;
+type Grants = Record<string, GrantValue>;
+type AgentPolicy = {
+    allowed: false;
+} | {
+    allowed: true;
+    requires: DelegationAction[];
+};
+interface CatalogPermission {
+    key: string;
+    group: string;
+    labelKey: string;
+    descriptionKey?: string;
+    /** Null for a permission without scopes. */
+    scopes: string[] | null;
+    implies: string[];
+    agent: AgentPolicy;
+    deprecated: boolean;
+    /** Owned by the SDK (`access.*`), present in every catalog. */
+    reserved: boolean;
+}
+interface CatalogRole {
+    key: string;
+    nameKey: string;
+    descriptionKey?: string;
+    grants: Grants;
+    assignableBy: 'access-manager' | 'host-admin';
+    exemptFromRoleLimit: boolean;
+}
+/** The validated catalog the engine and the admin API run on. */
+interface AccessCatalog {
+    version: number;
+    groups: {
+        key: string;
+        labelKey: string;
+    }[];
+    scopes: Record<string, {
+        labelKey: string;
+        descriptionKey?: string | undefined;
+    }>;
+    permissions: Record<string, CatalogPermission>;
+    /** Navigation key → the permissions of which any one reveals it. */
+    menus: Record<string, string[]>;
+    roles: Record<string, CatalogRole>;
+    hostRoleBindings: Record<string, string[]>;
+    defaults: {
+        unassigned: string | null;
+    };
+    domains: Record<string, {
+        labelKey: string;
+        hierarchical: boolean;
+    }>;
+    assignment: {
+        principals: string[];
+        maxRolesPerPrincipal: Record<string, number>;
+    };
+}
+/** A catalog whose permission keys are known to the compiler. */
+type TypedAccessCatalog<P extends string> = AccessCatalog & {
+    readonly __permission?: P;
+};
+type PermissionOf<C> = C extends TypedAccessCatalog<infer P> ? P : string;
+interface CatalogIssue {
+    path: string;
+    message: string;
+}
+declare class AccessCatalogError extends Error {
+    readonly issues: CatalogIssue[];
+    constructor(issues: CatalogIssue[]);
+}
+declare function validateAccessCatalog(input: unknown): {
+    ok: true;
+    catalog: AccessCatalog;
+} | {
+    ok: false;
+    issues: CatalogIssue[];
+};
+/**
+ * Validates a catalog and keeps its permission keys as a type.
+ *
+ * Throws {@link AccessCatalogError} listing every problem, so a broken
+ * catalog stops the backend at import rather than at the first request.
+ */
+declare function defineAccess<const I extends AccessCatalogInput>(input: I): TypedAccessCatalog<(keyof I['permissions'] & string) | (typeof RESERVED_PERMISSIONS)[keyof typeof RESERVED_PERMISSIONS]>;
+/**
+ * {@link defineAccess} for the catalog file the manifest names, imported as
+ * JSON.
+ *
+ * A JSON import widens `"allowed": false` to `boolean`, so it cannot satisfy
+ * the input type at compile time; the catalog is validated here at runtime
+ * instead, exactly as pack validated it, and typed by its permission keys.
+ */
+declare function accessCatalogFromJson<const J extends {
+    permissions: Record<string, unknown>;
+}>(json: J): TypedAccessCatalog<(keyof J['permissions'] & string) | (typeof RESERVED_PERMISSIONS)[keyof typeof RESERVED_PERMISSIONS]>;
+/** Why `value` is not a valid grant of `permission`, or null when it is. */
+declare function grantProblem(permission: CatalogPermission, value: GrantValue): string | null;
+
+export { type AccessCatalog as A, BUILTIN_PRINCIPAL_KINDS as B, type CatalogIssue as C, type DelegationAction as D, type Grants as G, HOST_ADMIN_ROLE as H, type PermissionOf as P, RESERVED_GROUP as R, type TypedAccessCatalog as T, type GrantValue as a, AccessCatalogError as b, type AccessCatalogInput as c, type AgentPolicy as d, type CatalogPermission as e, type CatalogRole as f, DELEGATION_ACTIONS as g, GLOBAL_DOMAIN as h, RESERVED_PERMISSIONS as i, accessCatalogFromJson as j, accessCatalogSchema as k, defineAccess as l, grantProblem as m, validateAccessCatalog as v };