@aglyn/aglyn 1.0.0-beta.143

package/src/lib/app-utils/org-roles.d.ts

@@ -0,0 +1,72 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Org roles (AGL-120): named permission sets assigned to team members,
+ * with per-user overrides an admin can apply on top. Shared between the
+ * console UI and the server permission resolver so both read one table.
+ */
+/** Keys are persisted in custom role docs — add new ones, never rename. */
+export declare const ORG_ROLE_PERMISSION_KEYS: readonly ["createHosts", "editHosts", "editBilling", "publishToMarketplace", "installPlugins", "manageMembers"];
+export type OrgPermissionKey = (typeof ORG_ROLE_PERMISSION_KEYS)[number];
+export type OrgPermissionSet = Record<OrgPermissionKey, boolean>;
+/**
+ * What `resolveRolePermissions` actually returns (AGL-2474): the legacy six
+ * PLUS whatever plugin-declared keys are registered. The six stay named so
+ * `permissions.createHosts` keeps its type; the index signature is what lets
+ * a caller read `permissions.managePos` at all. Consumers that only care
+ * about the built-in keys can keep using `OrgPermissionSet`.
+ */
+export type ResolvedOrgPermissionSet = OrgPermissionSet & Record<string, boolean>;
+export type OrgRoleTier = 'admin' | 'editor' | 'viewer';
+/** Owner-defined role at `orgs/{orgId}/roles/{id}` (AGL-133/243). */
+export interface OrgCustomRole {
+    name: string;
+    /**
+     * Keyed by the legacy six OR any plugin-declared key (AGL-2474) — the
+     * override loops below read both spaces out of this one map.
+     */
+    permissions?: Partial<Record<string, boolean>>;
+}
+/**
+ * Which built-in tier an ORG role resolves onto (AGL-2474).
+ *
+ * `owner` is NOT a tier, so `resolveRolePermissions('owner')` falls through to
+ * the viewer default — correct for an unknown string, catastrophic for the one
+ * role that owns the workspace. The server had its own copy of this table;
+ * sharing it is what lets the console resolve the same plugin-key defaults the
+ * API will enforce, instead of a second table that can drift from it.
+ */
+export declare const ORG_ROLE_TIER: Record<string, OrgRoleTier>;
+/** `ORG_ROLE_TIER` with least-privilege fallback for an unknown role. */
+export declare function orgRoleTier(role: string | null | undefined): OrgRoleTier;
+export declare const ORG_ROLE_TIER_LABELS: Record<OrgRoleTier, string>;
+/** Built-in role permission sets; overrides win key-by-key. */
+export declare const ORG_ROLE_TIER_PERMISSIONS: Record<OrgRoleTier, OrgPermissionSet>;
+/**
+ * Effective permissions: the role's defaults (unknown/missing roles resolve
+ * as `viewer` — least privilege) with per-user overrides applied key-by-key.
+ * Only boolean override values count; anything else keeps the role default.
+ */
+export declare function resolveRolePermissions(role: string | null | undefined, overrides?: Partial<Record<string, unknown>> | null, 
+/**
+ * Custom roles (AGL-133), keyed by role id (`orgs/{orgId}/roles`). A
+ * non-built-in role id resolves against this map — viewer base with the
+ * custom role's permissions applied; unknown ids stay plain viewer.
+ */
+customRoles?: Record<string, OrgCustomRole | undefined> | null): ResolvedOrgPermissionSet;
+/** True for the fixed admin/editor/viewer ids. */
+export declare function isBuiltInRole(role: string | null | undefined): boolean;

package/src/lib/app-utils/org-roles.js

@@ -0,0 +1,131 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { listPluginPermissionKeys, pluginPermissionDefaults } from "../plugin-manager/plugin-permissions.js";
+/**
+ * Org roles (AGL-120): named permission sets assigned to team members,
+ * with per-user overrides an admin can apply on top. Shared between the
+ * console UI and the server permission resolver so both read one table.
+ */ /** Keys are persisted in custom role docs — add new ones, never rename. */ export const ORG_ROLE_PERMISSION_KEYS = [
+    'createHosts',
+    'editHosts',
+    'editBilling',
+    'publishToMarketplace',
+    'installPlugins',
+    'manageMembers'
+];
+/**
+ * Which built-in tier an ORG role resolves onto (AGL-2474).
+ *
+ * `owner` is NOT a tier, so `resolveRolePermissions('owner')` falls through to
+ * the viewer default — correct for an unknown string, catastrophic for the one
+ * role that owns the workspace. The server had its own copy of this table;
+ * sharing it is what lets the console resolve the same plugin-key defaults the
+ * API will enforce, instead of a second table that can drift from it.
+ */ export const ORG_ROLE_TIER = {
+    owner: 'admin',
+    admin: 'admin',
+    editor: 'editor',
+    viewer: 'viewer'
+};
+/** `ORG_ROLE_TIER` with least-privilege fallback for an unknown role. */ export function orgRoleTier(role) {
+    var _ORG_ROLE_TIER_;
+    return (_ORG_ROLE_TIER_ = ORG_ROLE_TIER[role != null ? role : '']) != null ? _ORG_ROLE_TIER_ : 'viewer';
+}
+export const ORG_ROLE_TIER_LABELS = {
+    admin: 'Admin',
+    editor: 'Editor',
+    viewer: 'Viewer'
+};
+/** Built-in role permission sets; overrides win key-by-key. */ export const ORG_ROLE_TIER_PERMISSIONS = {
+    admin: {
+        createHosts: true,
+        editHosts: true,
+        editBilling: true,
+        publishToMarketplace: true,
+        installPlugins: true,
+        manageMembers: true
+    },
+    editor: {
+        createHosts: false,
+        editHosts: true,
+        editBilling: false,
+        publishToMarketplace: true,
+        installPlugins: true,
+        manageMembers: false
+    },
+    viewer: {
+        createHosts: false,
+        editHosts: false,
+        editBilling: false,
+        publishToMarketplace: false,
+        installPlugins: false,
+        manageMembers: false
+    }
+};
+/**
+ * Effective permissions: the role's defaults (unknown/missing roles resolve
+ * as `viewer` — least privilege) with per-user overrides applied key-by-key.
+ * Only boolean override values count; anything else keeps the role default.
+ */ export function resolveRolePermissions(role, overrides, /**
+   * Custom roles (AGL-133), keyed by role id (`orgs/{orgId}/roles`). A
+   * non-built-in role id resolves against this map — viewer base with the
+   * custom role's permissions applied; unknown ids stay plain viewer.
+   */ customRoles) {
+    const builtIn = ORG_ROLE_TIER_PERMISSIONS[role != null ? role : ''];
+    // Plugin-declared keys (AGL-435): tier defaults ride under the built-in
+    // set; custom-role overrides below win key-by-key like any other key.
+    const tier = builtIn ? role != null ? role : 'viewer' : 'viewer';
+    let base = _extends({}, pluginPermissionDefaults(tier), builtIn != null ? builtIn : ORG_ROLE_TIER_PERMISSIONS.viewer);
+    // EVERY GRANTABLE KEY, not just the legacy six (AGL-2474). Iterating
+    // `ORG_ROLE_PERMISSION_KEYS` alone is what made every plugin-declared
+    // permission unenforceable: the key materialised into the resolved map from
+    // `pluginPermissionDefaults` above and then no override and no custom role
+    // could move it, so `managePos` could only ever be its tier default. Read
+    // per call — plugins register at module scope and a snapshot taken here
+    // could be empty depending on import order.
+    const grantableKeys = [
+        ...ORG_ROLE_PERMISSION_KEYS,
+        ...listPluginPermissionKeys()
+    ];
+    if (!builtIn) {
+        const custom = customRoles == null ? void 0 : customRoles[role != null ? role : ''];
+        if (custom) {
+            // Plugin tier defaults are re-laid under the viewer base (AGL-2474).
+            // Rebuilding from `ORG_ROLE_TIER_PERMISSIONS.viewer` alone dropped every
+            // plugin key off a custom-role member's map entirely — `managePos` came
+            // back `undefined`, not `false`, which reads as denied but is not the
+            // same thing, and contradicted this function's own docblock.
+            base = _extends({}, pluginPermissionDefaults('viewer'), ORG_ROLE_TIER_PERMISSIONS.viewer);
+            for (const key of grantableKeys){
+                var _custom_permissions;
+                const value = (_custom_permissions = custom.permissions) == null ? void 0 : _custom_permissions[key];
+                if (typeof value === 'boolean') base[key] = value;
+            }
+        }
+    }
+    const permissions = _extends({}, base);
+    for (const key of grantableKeys){
+        const value = overrides == null ? void 0 : overrides[key];
+        if (typeof value === 'boolean') permissions[key] = value;
+    }
+    return permissions;
+}
+/** True for the fixed admin/editor/viewer ids. */ export function isBuiltInRole(role) {
+    return (role != null ? role : '') in ORG_ROLE_TIER_PERMISSIONS;
+}
+
+//# sourceMappingURL=org-roles.js.map

package/src/lib/app-utils/org-roles.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/org-roles.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport {\n  listPluginPermissionKeys,\n  pluginPermissionDefaults,\n} from '../plugin-manager/plugin-permissions'\n\n/**\n * Org roles (AGL-120): named permission sets assigned to team members,\n * with per-user overrides an admin can apply on top. Shared between the\n * console UI and the server permission resolver so both read one table.\n */\n\n/** Keys are persisted in custom role docs — add new ones, never rename. */\nexport const ORG_ROLE_PERMISSION_KEYS = [\n  'createHosts',\n  'editHosts',\n  'editBilling',\n  'publishToMarketplace',\n  'installPlugins',\n  'manageMembers',\n] as const\n\nexport type OrgPermissionKey = (typeof ORG_ROLE_PERMISSION_KEYS)[number]\n\nexport type OrgPermissionSet = Record<OrgPermissionKey, boolean>\n\n/**\n * What `resolveRolePermissions` actually returns (AGL-2474): the legacy six\n * PLUS whatever plugin-declared keys are registered. The six stay named so\n * `permissions.createHosts` keeps its type; the index signature is what lets\n * a caller read `permissions.managePos` at all. Consumers that only care\n * about the built-in keys can keep using `OrgPermissionSet`.\n */\nexport type ResolvedOrgPermissionSet = OrgPermissionSet &\n  Record<string, boolean>\n\nexport type OrgRoleTier = 'admin' | 'editor' | 'viewer'\n\n/** Owner-defined role at `orgs/{orgId}/roles/{id}` (AGL-133/243). */\nexport interface OrgCustomRole {\n  name: string\n  /**\n   * Keyed by the legacy six OR any plugin-declared key (AGL-2474) — the\n   * override loops below read both spaces out of this one map.\n   */\n  permissions?: Partial<Record<string, boolean>>\n}\n\n/**\n * Which built-in tier an ORG role resolves onto (AGL-2474).\n *\n * `owner` is NOT a tier, so `resolveRolePermissions('owner')` falls through to\n * the viewer default — correct for an unknown string, catastrophic for the one\n * role that owns the workspace. The server had its own copy of this table;\n * sharing it is what lets the console resolve the same plugin-key defaults the\n * API will enforce, instead of a second table that can drift from it.\n */\nexport const ORG_ROLE_TIER: Record<string, OrgRoleTier> = {\n  owner: 'admin',\n  admin: 'admin',\n  editor: 'editor',\n  viewer: 'viewer',\n}\n\n/** `ORG_ROLE_TIER` with least-privilege fallback for an unknown role. */\nexport function orgRoleTier(role: string | null | undefined): OrgRoleTier {\n  return ORG_ROLE_TIER[role ?? ''] ?? 'viewer'\n}\n\nexport const ORG_ROLE_TIER_LABELS: Record<OrgRoleTier, string> = {\n  admin: 'Admin',\n  editor: 'Editor',\n  viewer: 'Viewer',\n}\n\n/** Built-in role permission sets; overrides win key-by-key. */\nexport const ORG_ROLE_TIER_PERMISSIONS: Record<OrgRoleTier, OrgPermissionSet> =\n  {\n    admin: {\n      createHosts: true,\n      editHosts: true,\n      editBilling: true,\n      publishToMarketplace: true,\n      installPlugins: true,\n      manageMembers: true,\n    },\n    editor: {\n      createHosts: false,\n      editHosts: true,\n      editBilling: false,\n      publishToMarketplace: true,\n      installPlugins: true,\n      manageMembers: false,\n    },\n    viewer: {\n      createHosts: false,\n      editHosts: false,\n      editBilling: false,\n      publishToMarketplace: false,\n      installPlugins: false,\n      manageMembers: false,\n    },\n  }\n\n/**\n * Effective permissions: the role's defaults (unknown/missing roles resolve\n * as `viewer` — least privilege) with per-user overrides applied key-by-key.\n * Only boolean override values count; anything else keeps the role default.\n */\nexport function resolveRolePermissions(\n  role: string | null | undefined,\n  overrides?: Partial<Record<string, unknown>> | null,\n  /**\n   * Custom roles (AGL-133), keyed by role id (`orgs/{orgId}/roles`). A\n   * non-built-in role id resolves against this map — viewer base with the\n   * custom role's permissions applied; unknown ids stay plain viewer.\n   */\n  customRoles?: Record<string, OrgCustomRole | undefined> | null,\n): ResolvedOrgPermissionSet {\n  const builtIn = ORG_ROLE_TIER_PERMISSIONS[(role ?? '') as OrgRoleTier]\n  // Plugin-declared keys (AGL-435): tier defaults ride under the built-in\n  // set; custom-role overrides below win key-by-key like any other key.\n  const tier: OrgRoleTier = builtIn ? ((role ?? 'viewer') as OrgRoleTier) : 'viewer'\n  let base: ResolvedOrgPermissionSet = {\n    ...pluginPermissionDefaults(tier),\n    ...(builtIn ?? ORG_ROLE_TIER_PERMISSIONS.viewer),\n  }\n  // EVERY GRANTABLE KEY, not just the legacy six (AGL-2474). Iterating\n  // `ORG_ROLE_PERMISSION_KEYS` alone is what made every plugin-declared\n  // permission unenforceable: the key materialised into the resolved map from\n  // `pluginPermissionDefaults` above and then no override and no custom role\n  // could move it, so `managePos` could only ever be its tier default. Read\n  // per call — plugins register at module scope and a snapshot taken here\n  // could be empty depending on import order.\n  const grantableKeys: string[] = [\n    ...ORG_ROLE_PERMISSION_KEYS,\n    ...listPluginPermissionKeys(),\n  ]\n  if (!builtIn) {\n    const custom = customRoles?.[role ?? '']\n    if (custom) {\n      // Plugin tier defaults are re-laid under the viewer base (AGL-2474).\n      // Rebuilding from `ORG_ROLE_TIER_PERMISSIONS.viewer` alone dropped every\n      // plugin key off a custom-role member's map entirely — `managePos` came\n      // back `undefined`, not `false`, which reads as denied but is not the\n      // same thing, and contradicted this function's own docblock.\n      base = {\n        ...pluginPermissionDefaults('viewer'),\n        ...ORG_ROLE_TIER_PERMISSIONS.viewer,\n      }\n      for (const key of grantableKeys) {\n        const value = custom.permissions?.[key]\n        if (typeof value === 'boolean') base[key] = value\n      }\n    }\n  }\n  const permissions = { ...base }\n  for (const key of grantableKeys) {\n    const value = overrides?.[key]\n    if (typeof value === 'boolean') permissions[key] = value\n  }\n  return permissions\n}\n\n/** True for the fixed admin/editor/viewer ids. */\nexport function isBuiltInRole(role: string | null | undefined): boolean {\n  return (role ?? '') in ORG_ROLE_TIER_PERMISSIONS\n}\n"],"names":["listPluginPermissionKeys","pluginPermissionDefaults","ORG_ROLE_PERMISSION_KEYS","ORG_ROLE_TIER","owner","admin","editor","viewer","orgRoleTier","role","ORG_ROLE_TIER_LABELS","ORG_ROLE_TIER_PERMISSIONS","createHosts","editHosts","editBilling","publishToMarketplace","installPlugins","manageMembers","resolveRolePermissions","overrides","customRoles","builtIn","tier","base","grantableKeys","custom","key","value","permissions","isBuiltInRole"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED,SACEA,wBAAwB,EACxBC,wBAAwB,QACnB,0CAAsC;AAE7C;;;;CAIC,GAED,yEAAyE,GACzE,OAAO,MAAMC,2BAA2B;IACtC;IACA;IACA;IACA;IACA;IACA;CACD,CAAS;AA4BV;;;;;;;;CAQC,GACD,OAAO,MAAMC,gBAA6C;IACxDC,OAAO;IACPC,OAAO;IACPC,QAAQ;IACRC,QAAQ;AACV,EAAC;AAED,uEAAuE,GACvE,OAAO,SAASC,YAAYC,IAA+B;QAClDN;IAAP,QAAOA,kBAAAA,aAAa,CAACM,eAAAA,OAAQ,GAAG,YAAzBN,kBAA6B;AACtC;AAEA,OAAO,MAAMO,uBAAoD;IAC/DL,OAAO;IACPC,QAAQ;IACRC,QAAQ;AACV,EAAC;AAED,6DAA6D,GAC7D,OAAO,MAAMI,4BACX;IACEN,OAAO;QACLO,aAAa;QACbC,WAAW;QACXC,aAAa;QACbC,sBAAsB;QACtBC,gBAAgB;QAChBC,eAAe;IACjB;IACAX,QAAQ;QACNM,aAAa;QACbC,WAAW;QACXC,aAAa;QACbC,sBAAsB;QACtBC,gBAAgB;QAChBC,eAAe;IACjB;IACAV,QAAQ;QACNK,aAAa;QACbC,WAAW;QACXC,aAAa;QACbC,sBAAsB;QACtBC,gBAAgB;QAChBC,eAAe;IACjB;AACF,EAAC;AAEH;;;;CAIC,GACD,OAAO,SAASC,uBACdT,IAA+B,EAC/BU,SAAmD,EACnD;;;;GAIC,GACDC,WAA8D;IAE9D,MAAMC,UAAUV,yBAAyB,CAAEF,eAAAA,OAAQ,GAAmB;IACtE,wEAAwE;IACxE,sEAAsE;IACtE,MAAMa,OAAoBD,UAAYZ,eAAAA,OAAQ,WAA4B;IAC1E,IAAIc,OAAiC,aAChCtB,yBAAyBqB,OACxBD,kBAAAA,UAAWV,0BAA0BJ,MAAM;IAEjD,qEAAqE;IACrE,sEAAsE;IACtE,4EAA4E;IAC5E,2EAA2E;IAC3E,0EAA0E;IAC1E,wEAAwE;IACxE,4CAA4C;IAC5C,MAAMiB,gBAA0B;WAC3BtB;WACAF;KACJ;IACD,IAAI,CAACqB,SAAS;QACZ,MAAMI,SAASL,+BAAAA,WAAa,CAACX,eAAAA,OAAQ,GAAG;QACxC,IAAIgB,QAAQ;YACV,qEAAqE;YACrE,yEAAyE;YACzE,wEAAwE;YACxE,sEAAsE;YACtE,6DAA6D;YAC7DF,OAAO,aACFtB,yBAAyB,WACzBU,0BAA0BJ,MAAM;YAErC,KAAK,MAAMmB,OAAOF,cAAe;oBACjBC;gBAAd,MAAME,SAAQF,sBAAAA,OAAOG,WAAW,qBAAlBH,mBAAoB,CAACC,IAAI;gBACvC,IAAI,OAAOC,UAAU,WAAWJ,IAAI,CAACG,IAAI,GAAGC;YAC9C;QACF;IACF;IACA,MAAMC,cAAc,aAAKL;IACzB,KAAK,MAAMG,OAAOF,cAAe;QAC/B,MAAMG,QAAQR,6BAAAA,SAAW,CAACO,IAAI;QAC9B,IAAI,OAAOC,UAAU,WAAWC,WAAW,CAACF,IAAI,GAAGC;IACrD;IACA,OAAOC;AACT;AAEA,gDAAgD,GAChD,OAAO,SAASC,cAAcpB,IAA+B;IAC3D,OAAO,CAACA,eAAAA,OAAQ,OAAOE;AACzB"}

package/src/lib/app-utils/organizations.d.ts

@@ -0,0 +1,407 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Organization helpers (AGL-233): slug policy for workspace subdomains
+ * (`{slug}.aglyn.com`) and role math shared by the org APIs, the console
+ * UI, and the Firestore rules' mental model. See
+ * docs/MULTI_TENANT_FIRESTORE.md.
+ */
+import type { AglynOrgMember, HostAccessRole, HostUid, OrgRole, ScopeToken, UserOrgMembership } from '../foundation';
+/** Same lexical policy as host subdomains: 3–30 lowercase/digits/dashes. */
+export declare const ORG_SLUG_PATTERN: RegExp;
+export declare function isBlockedOrgSlug(slug: string): boolean;
+export declare function isValidOrgSlug(slug: string): boolean;
+/** Best-effort slug from an org name; '' when nothing usable remains. */
+export declare function generateOrgSlug(name: string): string;
+export declare const ORG_ROLES: readonly OrgRole[];
+export declare function isOrgRole(value: unknown): value is OrgRole;
+export declare function orgRoleAtLeast(role: OrgRole | null | undefined, minimum: OrgRole): boolean;
+/** Org settings, members, invites, host creation: admin and owner. */
+export declare function canManageOrg(role: OrgRole | null | undefined): boolean;
+/**
+ * The member's effective role on one host, or null for no access.
+ * Owner/admin span every host; editor/viewer resolve through `allHosts`
+ * (mapped to their org role) or the per-host access map.
+ */
+export declare function hostRoleFor(member: Partial<AglynOrgMember> | null | undefined, hostId: HostUid): HostAccessRole | null;
+/**
+ * Host roles that may MUTATE content — the axis `canWriteHostContent()` in
+ * the security rules asks (AGL-2334).
+ *
+ * `author` is here and absent from `HOST_PUBLISH_ROLES` below: that single
+ * difference IS the "edit content but not publish" role. Kept as two named
+ * sets rather than two inline comparisons because they are read in three
+ * places that must not drift — this module, the ~20 server gates, and the
+ * rules — and because a new host role added to the union has to be a
+ * deliberate decision on BOTH lists rather than an omission from one.
+ */
+export declare const HOST_CONTENT_WRITE_ROLES: readonly HostAccessRole[];
+/**
+ * Host roles that may make content LIVE. Everything that registers a route,
+ * moves a live-version pointer, schedules either of those for later, or
+ * flips a collection entry to `published` asks this and not the set above.
+ *
+ * The list is short and it is the whole product decision: `author` is not on
+ * it. If a role is ever added here, the rules' `canPublishHostContent()` and
+ * the publish-surface field freezes below it must be updated in the same
+ * change — they are the enforcement, this is the server-side echo of it.
+ */
+export declare const HOST_PUBLISH_ROLES: readonly HostAccessRole[];
+/**
+ * Whether the member may mutate a host's content — admin, editor **or
+ * author** on it.
+ *
+ * An author is a content editor in every respect this predicate covers; what
+ * it deliberately does NOT cover is publication. Any caller that is really
+ * asking "may this person make something live" must call `canPublishHost`
+ * instead — this one answering `true` for an author is the point of the role,
+ * not a gap in it.
+ */
+export declare function canWriteHost(member: Partial<AglynOrgMember> | null | undefined, hostId: HostUid): boolean;
+/**
+ * Whether the member may PUBLISH on a host — register a route, move a live
+ * version pointer, schedule either for later, or publish a collection entry.
+ *
+ * Strictly narrower than `canWriteHost`: `author` edits and does not publish.
+ * This is the server-side echo of the rules, not the enforcement — publishing
+ * is a set of client-direct Firestore writes across five document shapes, so
+ * `cloud/firebase-firestore.rules` is where it is actually refused. Server
+ * routes that schedule or trigger a publish ask this so the console can say
+ * no with a message instead of surfacing a bare permission-denied.
+ */
+export declare function canPublishHost(member: Partial<AglynOrgMember> | null | undefined, hostId: HostUid): boolean;
+/**
+ * The same question asked of a bare `memberRoles` value rather than a member
+ * document — the shape every Admin-SDK route already has in hand after its
+ * `hosts/{hostId}` read, so it does not have to re-load the org membership.
+ *
+ * `String(role)` at the call sites keeps `undefined` out; an unknown value
+ * is simply not in the set, which fails CLOSED.
+ */
+export declare function hostRoleCanWrite(role: unknown): boolean;
+/** Publish-axis twin of `hostRoleCanWrite`; `author` is excluded. */
+export declare function hostRoleCanPublish(role: unknown): boolean;
+/**
+ * Whether a member's reach is the whole org rather than a list of sites.
+ *
+ * Owner and admin always are; editor/viewer are only when `allHosts` says
+ * so — **or** when the membership predates the flag entirely. A pre-
+ * `allHosts` doc carries neither the flag nor a `hostAccess` map, and
+ * reading that as "scoped, with access to nothing" would lock real members
+ * out of their own workspace. A site collaborator ALWAYS has a non-empty
+ * `hostAccess` (that is what `grantHostAccess` writes), so the absence of
+ * both is the legacy shape, not a scoped one.
+ *
+ * Single source of truth for `resolveOrgPermissions` (the server gate),
+ * `projectMemberScopeTokens` (the rules projection), and the rules'
+ * own `isOrgWideMember()` — three copies of this predicate that disagree
+ * is a privilege bug, not a style problem (AGL-1026, AGL-1038).
+ */
+export declare function isOrgWideMember(member: Partial<AglynOrgMember> | null | undefined): boolean;
+/**
+ * How many of these roster entries consume a **manager** seat (AGL-1113).
+ *
+ * `orgs/{orgId}/members` holds BOTH org managers and site-scoped
+ * collaborators — adding a collaborator to one site writes an org member doc
+ * with `allHosts:false` + `hostAccess`, so a raw `.count()` of the collection
+ * billed every collaborator as a manager. Collaborators are metered
+ * separately, per host, against `membersPerHost` at
+ * `hosts/{hostId}/members` — counting them here charged them twice and
+ * tripped the manager gate for orgs nowhere near their manager limit.
+ *
+ * Reuses `isOrgWideMember` rather than filtering on `allHosts` directly:
+ * owner/admin are managers whatever the flag says, and a pre-`allHosts` doc
+ * is a manager too. A Firestore `where('allHosts','==',true)` count gets both
+ * of those wrong, which is why callers pass entries in and count here.
+ *
+ * Accepts pending INVITES as well as members — an invite carries the same
+ * `role`/`allHosts`/`hostAccess` shape and reserves the seat it will become.
+ */
+export declare function countManagerSeats(entries: ReadonlyArray<Partial<AglynOrgMember> | null | undefined>): number;
+/**
+ * One roster row or pending invite, as the collaborator counter needs to see
+ * it (AGL-2068). Deliberately structural rather than `Partial<AglynOrgMember>`
+ * — an INVITE is not a member document, it is keyed by email and has no uid,
+ * and the whole point of this counter is that the two populations must be
+ * counted together or the cap is enforced against a fraction of itself.
+ */
+export interface CollaboratorSeatEntry {
+    /** Member documents are keyed by uid; invites have none. */
+    uid?: string | null;
+    email?: string | null;
+    role?: unknown;
+    allHosts?: boolean;
+    hostAccess?: Record<string, unknown> | null;
+}
+/**
+ * Every principal consuming a COLLABORATOR seat on one host (AGL-2068).
+ *
+ * ## Why this exists at all
+ *
+ * `membersPerHost` was enforced on one of the four doors that admit a site
+ * collaborator, and that one door counted `hosts/{hostId}/members` — a
+ * DISPLAY roster only `/api/hosts/members` writes. The other three
+ * (`/api/orgs/invites` create, `/api/orgs/invites` accept, and the
+ * `hostAccess` branch of `/api/orgs/members`) land in `orgs/{id}/members` and
+ * the `hosts/{id}.memberRoles` projection, and were invisible to it. So the
+ * cap was both skipped on three paths and under-counted on the fourth, and a
+ * free org — `membersPerHost: 1` — could take on unlimited collaborators,
+ * each with full site access, on a plan that is never invoiced.
+ *
+ * verbatim: **"We need to make sure the free/hobby tier
+ * does hard cap so it always actually stays free."**
+ *
+ * ## What counts
+ *
+ * A SCOPED grant on `hostId`, and nothing else. An org-wide member
+ * (owner/admin, or `allHosts`) reaches every host but consumes a MANAGER
+ * seat — `countManagerSeats` is that side, and charging them here would bill
+ * one person twice and trip a cap they are not on. This is the same split
+ * AGL-1113 drew; it is now drawn from one place instead of three.
+ *
+ * Pending invites count, for the reason the manager gate counts them: an
+ * invite reserves the seat it will become, and a cap that only bites on
+ * acceptance can be walked past by mailing out N invites first.
+ */
+export declare function collaboratorSeatKeys(entries: ReadonlyArray<CollaboratorSeatEntry | null | undefined>, hostId: string): Set<string>;
+/**
+ * How many collaborator seats on `hostId` are spoken for by someone OTHER
+ * than `exclude` (AGL-2068).
+ *
+ * `exclude` is the principal the caller is about to admit, and dropping them
+ * is what makes this composable with `checkSeatQuota(…, used)`, whose
+ * contract is "usage BEFORE the resource being created". Without it the
+ * accept path refuses its own invite: at the moment acceptance is decided the
+ * invitee holds a pending invite AND is about to hold a membership, so they
+ * would be counted once or twice against a cap they are the subject of.
+ *
+ * Both identities are dropped, not whichever one is present. A person can be
+ * on the roster under a uid with no mirrored email and hold an invite under
+ * that address, and the seat is still one seat.
+ *
+ * ## `emails`, not `email` — an account holds several (AGL-2486)
+ *
+ * Since an invitation may be accepted at any CONFIRMED address on the account,
+ * the pending invite the accepter is about to consume can be keyed by an
+ * address that is not their primary. `exclude.email` alone is the primary, so
+ * that invite survived the exclusion and the person was counted against a cap
+ * they are the subject of — the exact double-count the paragraph above says
+ * this function exists to prevent, re-opened by widening the accept match.
+ *
+ * It fails CLOSED (a spurious "out of seats" refusal, never a free seat), and
+ * only for an org sitting exactly on its cap, which is why it survived review.
+ *
+ * `emails` takes every address PROVEN to belong to the principal being
+ * admitted. Passing an address that is not theirs would hand out a free seat,
+ * so callers must pass confirmed addresses for that uid and nothing else.
+ */
+export declare function countCollaboratorSeats(entries: ReadonlyArray<CollaboratorSeatEntry | null | undefined>, hostId: string, exclude?: {
+    uid?: string | null;
+    email?: string | null;
+    /** Further addresses on the SAME account; see above. */
+    emails?: readonly (string | null | undefined)[] | null;
+}): number;
+/**
+ * Every principal consuming a MANAGER seat, as identities rather than rows.
+ *
+ * The org-wide half of `collaboratorSeatKeys`, drawn from the same entries and
+ * split on the same predicate, so the two counters partition one roster
+ * instead of overlapping on it.
+ *
+ * Deduplicating by identity is the difference from {@link countManagerSeats},
+ * and it is what makes this composable with an `exclude`: a person holding a
+ * pending invite AND the membership it became is one seat, and the row-wise
+ * counter reports two because it is handed the two collections separately and
+ * sums them.
+ */
+export declare function managerSeatKeys(entries: ReadonlyArray<CollaboratorSeatEntry | null | undefined>): Set<string>;
+/**
+ * How many manager seats are spoken for by someone OTHER than `exclude`.
+ *
+ * The manager twin of {@link countCollaboratorSeats}, and it exists for the
+ * same reason that one takes an `exclude`: `checkSeatQuota`'s contract is
+ * "usage BEFORE the resource being created", and on the invite-accept path the
+ * accepter holds a pending invite and is about to hold a membership at the
+ * same instant. Counted plainly they are charged once or twice for a seat they
+ * are the subject of, and an org on its last seat refuses its own invitation.
+ *
+ * Both identities are dropped, and `emails` carries the further addresses
+ * proven to belong to that account — an invitation may be accepted at any
+ * confirmed address, so the invite being consumed need not be keyed by the
+ * primary one. Passing an address that is not theirs would hand out a free
+ * seat, so callers must pass confirmed addresses for that uid and nothing
+ * else.
+ *
+ * Kept SEPARATE from {@link countManagerSeats} rather than replacing it: that
+ * one is row-wise and is what the billing and console surfaces count with, and
+ * quietly making it identity-wise would change every one of those totals.
+ */
+export declare function countManagerSeatsExcluding(entries: ReadonlyArray<CollaboratorSeatEntry | null | undefined>, exclude?: {
+    uid?: string | null;
+    email?: string | null;
+    /** Further addresses on the SAME account; see above. */
+    emails?: readonly (string | null | undefined)[] | null;
+}): number;
+/**
+ * What KIND of user a console row represents (AGL-1114) — the distinction
+ * that decides which seat they consume, and the one the Team table could not
+ * express because a manager and a collaborator differ only by fields the
+ * table never showed.
+ *
+ * Deliberately NOT the same axis as `role`. A `role: 'editor'` is a manager
+ * when their reach is the whole org and a collaborator when it is two sites;
+ * reading the role alone is the mistake that let a collaborator look like
+ * team staff (see the org-leak and role-gate work).
+ *
+ * `siteMember` is the third kind and never appears in `orgs/{id}/members` at
+ * all: it is an end-user account on a PUBLISHED site (`siteMembers`), not a
+ * console user. It has no Firebase Auth record of any kind — a site member is
+ * a Firestore document under `hosts/{hostId}/siteMembers` with its own scrypt
+ * hash and its own session cookie — so no surface that lists AUTH accounts,
+ * the staff user directory included, can contain one. The label is here so the
+ * vocabulary is complete, for a surface that lists site accounts and needs a
+ * word for them. Free and uncounted on every plan (AGL-889).
+ */
+export type ConsoleUserType = 'manager' | 'collaborator' | 'siteMember';
+export declare const CONSOLE_USER_TYPE_LABELS: Record<ConsoleUserType, string>;
+/** One line on what each kind is and what it costs — tooltip/legend copy. */
+export declare const CONSOLE_USER_TYPE_HINTS: Record<ConsoleUserType, string>;
+/**
+ * Classify an `orgs/{orgId}/members` entry (or a pending invite, same shape).
+ * Never returns `siteMember` — nothing in that collection is one; the value
+ * exists for surfaces that list published-site accounts and must label them —
+ * never for one that lists both, since the two populations do not share an
+ * identity system.
+ */
+export declare function consoleUserType(member: Partial<AglynOrgMember> | null | undefined): Exclude<ConsoleUserType, 'siteMember'>;
+/**
+ * Whether an account is governed by enterprise SSO (AGL-1128) — it lives in
+ * an org's GCIP tenant pool rather than the project pool, so its identity is
+ * owned by the customer's IdP.
+ *
+ * `tenantId` is the whole signal: Firebase sets it on the user whenever the
+ * account belongs to a tenant, and only SSO accounts do.
+ */
+export declare function isSsoGovernedAccount(user: {
+    tenantId?: string | null;
+} | null | undefined): boolean;
+/**
+ * Whether the account may connect an additional consumer sign-in provider.
+ *
+ * **No, for any SSO-governed account.** The customer's IdP is the single gate
+ * they bought: they revoke there, enforce MFA there, offboard there. A linked
+ * personal Google account is a way in their IdP can never see or revoke —
+ * exactly what SSO is purchased to prevent.
+ *
+ * Deliberately NOT gated on `sso.enforced`. That flag exists so we never
+ * LOCK OUT an existing sign-in method; it is not a licence to hand out new
+ * bypasses meanwhile. Nothing here removes a provider an account already has,
+ * so this can never lock anyone out.
+ *
+ * This is the intent, not the boundary — the boundary is upstream, since a
+ * GCIP tenant only accepts providers enabled on that tenant. Both matter: the
+ * boundary is remote config that could drift, and a UI that offers a
+ * security-regressing action is wrong even when the action would fail.
+ */
+export declare function canLinkSocialProvider(user: {
+    tenantId?: string | null;
+} | null | undefined): boolean;
+/**
+ * The same question as `isOrgWideMember`, asked of the `users/{uid}/orgs`
+ * reverse-index row instead of the member doc (AGL-1032).
+ *
+ * The console navigates from the index — it is what `useOrgScope` loads —
+ * and the index carries a MIRROR of the predicate, not the inputs to it, so
+ * this cannot recompute: `role: 'viewer'` on the index means "viewer",
+ * whether the member reaches every site or one.
+ *
+ * Reads a missing flag as org-wide, for the same reason `isOrgWideMember`
+ * reads a missing `allHosts` that way: rows written before the mirror
+ * existed have no flag, and hiding the workspace from a real member is a
+ * worse failure than showing org chrome to a collaborator whose reads the
+ * rules refuse anyway. Owner/admin are org-wide by role regardless of the
+ * mirror, so a stale row can never lock an admin out.
+ *
+ * Navigation only — never an access decision. AGL-1026 (rules) and the
+ * Admin-SDK scope checks are the boundary.
+ */
+export declare function isOrgWideMembership(membership: Pick<UserOrgMembership, 'role' | 'orgWide'> | null | undefined): boolean;
+/**
+ * The `scopeTokens` projection stamped onto member docs (AGL-1038) so the
+ * rules can intersect a caller's reach with a resource's `visibleTo` —
+ * rules have no `.map()`, so `hostAccess`'s keys cannot be turned into
+ * tokens at evaluation time and have to be denormalized here.
+ *
+ * Org-wide members get `['org']`; they own the org and read everything in
+ * it, scoped or not (the rules short-circuit on them anyway). A scoped
+ * collaborator gets `'org'` plus one token per granted host — `'org'`
+ * because an org-WIDE resource stays readable by any member, which is
+ * today's behavior and not something this project narrows.
+ *
+ * Not capped at `MAX_SCOPE_HOSTS`: the rules' `hasAny` has no 30-value
+ * limit, only the client `array-contains-any` query does, so a member of
+ * more than 30 sites is a listing problem for AGL-1044 to chunk, not a
+ * reason to under-grant here.
+ */
+export declare function projectMemberScopeTokens(member: Partial<AglynOrgMember> | null | undefined): ScopeToken[];
+/**
+ * A member's effective read set: the stored `scopeTokens` projection when it
+ * is there, recomputed from the membership when it is not.
+ *
+ * The fallback is the security-relevant half and it was written out by hand
+ * in four places (`use-scope-tokens`, `erase-scope`, the media sign route,
+ * and by omission in `resolveMediaScope`, which only ever recomputed). Four
+ * copies of "what may this member see" is the shape that eventually
+ * disagrees, and a copy that reads `member.scopeTokens` WITHOUT the
+ * `.length` guard silently grants nothing to a member the AGL-1040 backfill
+ * has not reached — or, written the other way round, grants everything.
+ *
+ * Recomputing is the safe fallback rather than a convenience: it produces
+ * exactly what `grantHostAccess` would have stamped, so an unstamped member
+ * doc behaves as its `hostAccess` says, never as "no access" and never as
+ * org-wide.
+ */
+export declare function memberScopeTokens(member: Partial<AglynOrgMember> | null | undefined): ScopeToken[];
+/**
+ * May this member see a resource carrying `visibleTo`? (AGL-1037/1038)
+ *
+ * The whole client-side/server-side authorization question in one place:
+ * org-wide members read everything they own; everyone else needs their read
+ * set to intersect the resource's scope. Absent/empty `visibleTo` is
+ * org-wide by the same rule the Firestore rules use, so an unbackfilled
+ * resource does not vanish.
+ *
+ * Every Admin-SDK path must call this (or `scopeAllows`, which wraps an
+ * already-resolved scope) — the Admin SDK bypasses rules entirely, so this
+ * IS the enforcement there, not a second opinion about it.
+ *
+ * NOT a membership check, and never a substitute for one: a `null` member
+ * "can see" an org-wide resource here, because the question this answers is
+ * "is this resource in scope for that reach", not "is this person in the
+ * org". Resolve membership first and refuse the caller if there is none —
+ * conflating the two is exactly how AGL-1026 exposed a whole org.
+ */
+export declare function memberCanSee(member: Partial<AglynOrgMember> | null | undefined, visibleTo: readonly string[] | null | undefined): boolean;
+/**
+ * The `memberRoles` projection stamped onto host docs so Firestore rules
+ * authorize host content with the single host-doc read they already do
+ * (docs/MULTI_TENANT_FIRESTORE.md §5). Recomputed by the membership API
+ * whenever a member changes; owner/admin appear on every host.
+ */
+export declare function projectHostMemberRoles(members: ReadonlyArray<Partial<AglynOrgMember> & {
+    $id: string;
+}>, hostId: HostUid): Record<string, HostAccessRole>;