@aglyn/aglyn 1.0.0-beta.143

package/src/lib/app-utils/host-naming.js

@@ -0,0 +1,188 @@
+/**
+ * @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.
+ */ /**
+ * Host naming guards (AGL-147): one shared subdomain policy for the create
+ * API, the rename/validate API, and the console dialogs — pattern, reserved
+ * + profanity blocklists, a display-name → subdomain generator, and
+ * taken-name suggestions.
+ */ /** 3–30 chars, lowercase alphanumeric + dashes, no leading dash. */ export const SUBDOMAIN_PATTERN = /^[a-z0-9][a-z0-9-]{2,29}$/;
+/** Platform/system names a tenant must not squat. */ export const RESERVED_SUBDOMAINS = new Set([
+    'www',
+    'app',
+    'api',
+    'admin',
+    'console',
+    'mail',
+    'demo',
+    'staging',
+    'dev',
+    'test',
+    'docs',
+    'blog',
+    'help',
+    'support',
+    'status',
+    'cdn',
+    'assets',
+    'static',
+    'ftp',
+    'smtp',
+    'ns1',
+    'ns2',
+    'aglyn',
+    'billing',
+    'account',
+    'login',
+    'signup',
+    'auth'
+]);
+/**
+ * Profanity fragments blocked as substrings in generated or typed
+ * subdomains. Deliberately short: obvious slurs and vulgarity only —
+ * substring matching is aggressive, so entries must be unambiguous.
+ */ const BLOCKED_FRAGMENTS = [
+    'fuck',
+    'shit',
+    'cunt',
+    'nigger',
+    'faggot',
+    'bitch',
+    'porn',
+    'nazi'
+];
+/** True when the subdomain is reserved or contains a blocked fragment. */ export function isBlockedSubdomain(subdomain) {
+    const normalized = subdomain.toLowerCase();
+    if (RESERVED_SUBDOMAINS.has(normalized)) return true;
+    const collapsed = normalized.replace(/[^a-z0-9]/g, '');
+    return BLOCKED_FRAGMENTS.some((fragment)=>collapsed.includes(fragment));
+}
+/**
+ * Best-effort subdomain from a display name: lowercase, spaces/symbols to
+ * dashes, collapsed, trimmed to the pattern's 30-char cap. Returns '' when
+ * nothing usable remains (caller falls back to manual entry).
+ */ export function generateSubdomain(displayName) {
+    const slug = displayName.toLowerCase().normalize('NFKD').replace(/[̀-ͯ]/g, '').replace(/[^a-z0-9]+/g, '-').replace(/-{2,}/g, '-').replace(/^-+|-+$/g, '').slice(0, 30).replace(/-+$/, '');
+    if (!SUBDOMAIN_PATTERN.test(slug) || isBlockedSubdomain(slug)) return '';
+    return slug;
+}
+/**
+ * Alternatives for a taken subdomain: `name-2`, `name-<year>`, `name-site`.
+ * Candidates are truncated to fit the pattern; blocked names are dropped.
+ * Availability is the caller's job (needs a Firestore query).
+ */ export function suggestSubdomains(base, year = new Date().getFullYear()) {
+    const stem = base.toLowerCase().replace(/-+$/, '');
+    const withSuffix = (suffix)=>`${stem.slice(0, 30 - suffix.length - 1)}-${suffix}`.replace(/-{2,}/g, '-');
+    const candidates = [
+        withSuffix('2'),
+        withSuffix(String(year)),
+        withSuffix('site')
+    ];
+    return [
+        ...new Set(candidates.filter((candidate)=>SUBDOMAIN_PATTERN.test(candidate) && !isBlockedSubdomain(candidate)))
+    ];
+}
+/**
+ * The apex tenant sites are served from. Console lives on `app.aglyn.com`.
+ *
+ * CONFIGURABLE, not a literal (AGL-2121). AGL-2022 moved the console's
+ * *display* links onto `NEXT_PUBLIC_TENANT_DOMAIN` and shipped a green spec
+ * for it; this constant — which every OTHER consumer reads — stayed a bare
+ * `'aglyn.app'`. So a self-hoster who set the variable got correct "View live"
+ * links in their own console while the software went on emitting our apex
+ * everywhere that actually reaches the public: `<link rel="canonical">`,
+ * `/api/sitemap`, `/api/robots`, `/api/collections-rss` item links,
+ * `/api/manifest`, `og:image`, and the origin inbox-bound `<img src>` resolves
+ * against. Their customers' sites told Google, every feed reader and every
+ * inbox that they lived at a name the operator does not control and we do not
+ * serve for them.
+ *
+ * Same variable and same default as `tenant-links.ts` — one value, one name
+ * (AGL-733). Dot notation is load-bearing: this module reaches client bundles,
+ * and Next inlines `NEXT_PUBLIC_*` by substituting `process.env.NAME`
+ * textually; the bracket form is never substituted and would read `undefined`
+ * in the browser. Trimmed so a half-finished `.env` line reads as absent
+ * rather than as a whitespace apex.
+ *
+ * The asymmetry with `operator-identity.ts` — which refuses to default at all
+ * — is deliberate. A wrong apex is visible to the operator on the first click
+ * in their own console, so a default they can see and correct is a default. A
+ * wrong contact address fails silently and off-site, which is why that one
+ * refuses to guess.
+ */ export const TENANT_APEX = (process.env.NEXT_PUBLIC_TENANT_DOMAIN || '').trim() || 'aglyn.app';
+/**
+ * The absolute origin a published site is reachable at (AGL-1224).
+ *
+ * A custom domain wins over the platform subdomain, matching what the tenant
+ * renderer already emits as `<link rel="canonical">` — a site on a custom
+ * domain that advertised its `.aglyn.app` origin would be describing itself
+ * by a name its visitors never see.
+ *
+ * Returns undefined rather than a half-built URL when a host has neither, so
+ * a caller that needs an absolute URL can tell it does not have one. Emails
+ * are the sharp case: an image `src` that is site-relative resolves against
+ * nothing in an inbox, so "no origin" has to be answerable.
+ */ export function hostPublicOrigin(host) {
+    if (host == null ? void 0 : host.cname) return `https://${host.cname}`;
+    if (host == null ? void 0 : host.subdomain) return `https://${host.subdomain}.${TENANT_APEX}`;
+    return undefined;
+}
+/** A bare hostname: labels of a-z0-9/dash, at least two of them. */ const CUSTOM_DOMAIN_PATTERN = /^(?!-)[a-z0-9-]{1,63}(\.(?!-)[a-z0-9-]{1,63})+$/;
+/**
+ * The custom domain a host is actually **serving on**, or undefined (AGL-1272).
+ *
+ * Deliberately stricter than `hostPublicOrigin`, which answers "what name does
+ * this site call itself" and is right to prefer `cname` the moment it exists.
+ * This answers a load-bearing question instead — "is it safe to send visitors
+ * away from the platform subdomain and onto this name" — and the cost of
+ * getting it wrong is the whole site, not a wrong URL in an email.
+ *
+ * So every reason to doubt the domain is a refusal:
+ *
+ *  - `cnameAttachmentPending` means the Vercel attach never landed (missing
+ *    env, or a 5xx). The domain is claimed in Firestore and serves nothing:
+ *    no certificate, no routing. This is precisely the "attached but not
+ *    live" state, and redirecting to it strands the site on a dead host.
+ *  - `cnameDetachmentPending` means the customer asked to disconnect and the
+ *    platform release failed. The name may still resolve, but the customer's
+ *    stated intent is to leave it, so we stop advertising it.
+ *  - A name inside `aglyn.app` is refused outright. `{sub}.aglyn.app` is the
+ *    very origin we redirect FROM, and the tenant middleware resolves that
+ *    space by `subdomain` before it ever considers `cname` — so a host whose
+ *    cname pointed back into it would redirect to itself forever.
+ *  - A name that is not hostname-shaped is refused. `/api/domains/attach`
+ *    lowercases and trims what the wizard sends but never pattern-checks it
+ *    (only `/api/domains/verify` does), so a junk value can reach Firestore.
+ *    A junk value reaching a `Location:` header is a different class of
+ *    problem again.
+ *
+ * Note what this CANNOT tell you: DNS was verified once, at connect time, and
+ * nothing re-checks it. A domain whose DNS is later repointed or whose
+ * registration lapses still reads as live here. That residual risk is why the
+ * redirect built on this is temporary and revocable rather than permanent.
+ */ export function liveCustomDomain(host) {
+    var _host_cname;
+    if (!host) return undefined;
+    if (host.cnameAttachmentPending === true) return undefined;
+    if (host.cnameDetachmentPending === true) return undefined;
+    const domain = String((_host_cname = host.cname) != null ? _host_cname : '').trim().toLowerCase();
+    if (!CUSTOM_DOMAIN_PATTERN.test(domain)) return undefined;
+    if (domain === TENANT_APEX || domain.endsWith(`.${TENANT_APEX}`)) {
+        return undefined;
+    }
+    return domain;
+}
+
+//# sourceMappingURL=host-naming.js.map

package/src/lib/app-utils/host-naming.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/host-naming.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\n/**\n * Host naming guards (AGL-147): one shared subdomain policy for the create\n * API, the rename/validate API, and the console dialogs — pattern, reserved\n * + profanity blocklists, a display-name → subdomain generator, and\n * taken-name suggestions.\n */\n\n/** 3–30 chars, lowercase alphanumeric + dashes, no leading dash. */\nexport const SUBDOMAIN_PATTERN = /^[a-z0-9][a-z0-9-]{2,29}$/\n\n/** Platform/system names a tenant must not squat. */\nexport const RESERVED_SUBDOMAINS = new Set([\n  'www',\n  'app',\n  'api',\n  'admin',\n  'console',\n  'mail',\n  'demo',\n  'staging',\n  'dev',\n  'test',\n  'docs',\n  'blog',\n  'help',\n  'support',\n  'status',\n  'cdn',\n  'assets',\n  'static',\n  'ftp',\n  'smtp',\n  'ns1',\n  'ns2',\n  'aglyn',\n  'billing',\n  'account',\n  'login',\n  'signup',\n  'auth',\n])\n\n/**\n * Profanity fragments blocked as substrings in generated or typed\n * subdomains. Deliberately short: obvious slurs and vulgarity only —\n * substring matching is aggressive, so entries must be unambiguous.\n */\nconst BLOCKED_FRAGMENTS = [\n  'fuck',\n  'shit',\n  'cunt',\n  'nigger',\n  'faggot',\n  'bitch',\n  'porn',\n  'nazi',\n]\n\n/** True when the subdomain is reserved or contains a blocked fragment. */\nexport function isBlockedSubdomain(subdomain: string): boolean {\n  const normalized = subdomain.toLowerCase()\n  if (RESERVED_SUBDOMAINS.has(normalized)) return true\n  const collapsed = normalized.replace(/[^a-z0-9]/g, '')\n  return BLOCKED_FRAGMENTS.some((fragment) => collapsed.includes(fragment))\n}\n\n/**\n * Best-effort subdomain from a display name: lowercase, spaces/symbols to\n * dashes, collapsed, trimmed to the pattern's 30-char cap. Returns '' when\n * nothing usable remains (caller falls back to manual entry).\n */\nexport function generateSubdomain(displayName: string): string {\n  const slug = displayName\n    .toLowerCase()\n    .normalize('NFKD')\n    .replace(/[̀-ͯ]/g, '')\n    .replace(/[^a-z0-9]+/g, '-')\n    .replace(/-{2,}/g, '-')\n    .replace(/^-+|-+$/g, '')\n    .slice(0, 30)\n    .replace(/-+$/, '')\n  if (!SUBDOMAIN_PATTERN.test(slug) || isBlockedSubdomain(slug)) return ''\n  return slug\n}\n\n/**\n * Alternatives for a taken subdomain: `name-2`, `name-<year>`, `name-site`.\n * Candidates are truncated to fit the pattern; blocked names are dropped.\n * Availability is the caller's job (needs a Firestore query).\n */\nexport function suggestSubdomains(base: string, year = new Date().getFullYear()): string[] {\n  const stem = base.toLowerCase().replace(/-+$/, '')\n  const withSuffix = (suffix: string) =>\n    `${stem.slice(0, 30 - suffix.length - 1)}-${suffix}`.replace(/-{2,}/g, '-')\n  const candidates = [withSuffix('2'), withSuffix(String(year)), withSuffix('site')]\n  return [\n    ...new Set(\n      candidates.filter(\n        (candidate) =>\n          SUBDOMAIN_PATTERN.test(candidate) && !isBlockedSubdomain(candidate),\n      ),\n    ),\n  ]\n}\n\n/**\n * The apex tenant sites are served from. Console lives on `app.aglyn.com`.\n *\n * CONFIGURABLE, not a literal (AGL-2121). AGL-2022 moved the console's\n * *display* links onto `NEXT_PUBLIC_TENANT_DOMAIN` and shipped a green spec\n * for it; this constant — which every OTHER consumer reads — stayed a bare\n * `'aglyn.app'`. So a self-hoster who set the variable got correct \"View live\"\n * links in their own console while the software went on emitting our apex\n * everywhere that actually reaches the public: `<link rel=\"canonical\">`,\n * `/api/sitemap`, `/api/robots`, `/api/collections-rss` item links,\n * `/api/manifest`, `og:image`, and the origin inbox-bound `<img src>` resolves\n * against. Their customers' sites told Google, every feed reader and every\n * inbox that they lived at a name the operator does not control and we do not\n * serve for them.\n *\n * Same variable and same default as `tenant-links.ts` — one value, one name\n * (AGL-733). Dot notation is load-bearing: this module reaches client bundles,\n * and Next inlines `NEXT_PUBLIC_*` by substituting `process.env.NAME`\n * textually; the bracket form is never substituted and would read `undefined`\n * in the browser. Trimmed so a half-finished `.env` line reads as absent\n * rather than as a whitespace apex.\n *\n * The asymmetry with `operator-identity.ts` — which refuses to default at all\n * — is deliberate. A wrong apex is visible to the operator on the first click\n * in their own console, so a default they can see and correct is a default. A\n * wrong contact address fails silently and off-site, which is why that one\n * refuses to guess.\n */\nexport const TENANT_APEX =\n  (process.env.NEXT_PUBLIC_TENANT_DOMAIN || '').trim() || 'aglyn.app'\n\n/**\n * The absolute origin a published site is reachable at (AGL-1224).\n *\n * A custom domain wins over the platform subdomain, matching what the tenant\n * renderer already emits as `<link rel=\"canonical\">` — a site on a custom\n * domain that advertised its `.aglyn.app` origin would be describing itself\n * by a name its visitors never see.\n *\n * Returns undefined rather than a half-built URL when a host has neither, so\n * a caller that needs an absolute URL can tell it does not have one. Emails\n * are the sharp case: an image `src` that is site-relative resolves against\n * nothing in an inbox, so \"no origin\" has to be answerable.\n */\nexport function hostPublicOrigin(\n  host:\n    | { cname?: string | null; subdomain?: string | null }\n    | null\n    | undefined,\n): string | undefined {\n  if (host?.cname) return `https://${host.cname}`\n  if (host?.subdomain) return `https://${host.subdomain}.${TENANT_APEX}`\n  return undefined\n}\n\n/**\n * The custom-domain lifecycle as it is actually persisted on the host doc.\n *\n * There is no `verifiedAt`, no `status`, no `sslReady` — the console's\n * `/api/domains/*` routes write exactly these three fields, so this is the\n * whole vocabulary anything downstream has to reason from.\n */\nexport interface HostCustomDomainState {\n  cname?: string | null\n  /** Vercel attach failed or was unconfigured — the domain does NOT serve. */\n  cnameAttachmentPending?: boolean | null\n  /** Vercel detach failed — the customer is mid-disconnect. */\n  cnameDetachmentPending?: boolean | null\n  subdomain?: string | null\n}\n\n/** A bare hostname: labels of a-z0-9/dash, at least two of them. */\nconst CUSTOM_DOMAIN_PATTERN = /^(?!-)[a-z0-9-]{1,63}(\\.(?!-)[a-z0-9-]{1,63})+$/\n\n/**\n * The custom domain a host is actually **serving on**, or undefined (AGL-1272).\n *\n * Deliberately stricter than `hostPublicOrigin`, which answers \"what name does\n * this site call itself\" and is right to prefer `cname` the moment it exists.\n * This answers a load-bearing question instead — \"is it safe to send visitors\n * away from the platform subdomain and onto this name\" — and the cost of\n * getting it wrong is the whole site, not a wrong URL in an email.\n *\n * So every reason to doubt the domain is a refusal:\n *\n *  - `cnameAttachmentPending` means the Vercel attach never landed (missing\n *    env, or a 5xx). The domain is claimed in Firestore and serves nothing:\n *    no certificate, no routing. This is precisely the \"attached but not\n *    live\" state, and redirecting to it strands the site on a dead host.\n *  - `cnameDetachmentPending` means the customer asked to disconnect and the\n *    platform release failed. The name may still resolve, but the customer's\n *    stated intent is to leave it, so we stop advertising it.\n *  - A name inside `aglyn.app` is refused outright. `{sub}.aglyn.app` is the\n *    very origin we redirect FROM, and the tenant middleware resolves that\n *    space by `subdomain` before it ever considers `cname` — so a host whose\n *    cname pointed back into it would redirect to itself forever.\n *  - A name that is not hostname-shaped is refused. `/api/domains/attach`\n *    lowercases and trims what the wizard sends but never pattern-checks it\n *    (only `/api/domains/verify` does), so a junk value can reach Firestore.\n *    A junk value reaching a `Location:` header is a different class of\n *    problem again.\n *\n * Note what this CANNOT tell you: DNS was verified once, at connect time, and\n * nothing re-checks it. A domain whose DNS is later repointed or whose\n * registration lapses still reads as live here. That residual risk is why the\n * redirect built on this is temporary and revocable rather than permanent.\n */\nexport function liveCustomDomain(\n  host: HostCustomDomainState | null | undefined,\n): string | undefined {\n  if (!host) return undefined\n  if (host.cnameAttachmentPending === true) return undefined\n  if (host.cnameDetachmentPending === true) return undefined\n  const domain = String(host.cname ?? '')\n    .trim()\n    .toLowerCase()\n  if (!CUSTOM_DOMAIN_PATTERN.test(domain)) return undefined\n  if (domain === TENANT_APEX || domain.endsWith(`.${TENANT_APEX}`)) {\n    return undefined\n  }\n  return domain\n}\n"],"names":["SUBDOMAIN_PATTERN","RESERVED_SUBDOMAINS","Set","BLOCKED_FRAGMENTS","isBlockedSubdomain","subdomain","normalized","toLowerCase","has","collapsed","replace","some","fragment","includes","generateSubdomain","displayName","slug","normalize","slice","test","suggestSubdomains","base","year","Date","getFullYear","stem","withSuffix","suffix","length","candidates","String","filter","candidate","TENANT_APEX","process","env","NEXT_PUBLIC_TENANT_DOMAIN","trim","hostPublicOrigin","host","cname","undefined","CUSTOM_DOMAIN_PATTERN","liveCustomDomain","cnameAttachmentPending","cnameDetachmentPending","domain","endsWith"],"mappings":"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"}

package/src/lib/app-utils/host-permissions.d.ts

@@ -0,0 +1,76 @@
+/**
+ * @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 type { AglynOrgMember, HostAccessRole, HostPermissionKey, HostUid } from '../foundation';
+import { type AglynOrgCustomRole } from './org-permissions';
+/**
+ * Catalog keys a site collaborator holds PER SITE (AGL-2984), resolved on one
+ * of two axes.
+ *
+ * A plugin that declares a catalog key with `hostRoleDefaults` makes it a
+ * per-site key. For the people whose membership spans the workspace, the key
+ * is an ordinary catalog key: their org role's default, refined by a custom
+ * role and by per-member overrides, the same on every site. A site
+ * collaborator has no org standing to refine — their membership exists only
+ * to carry access to named sites — so for them the key is decided PER SITE,
+ * from the host role they hold there, refined by `hostPermissions[hostId]` on
+ * their member document.
+ *
+ * Which axis applies is `isOrgWideMember`, the predicate the rules projection
+ * and the scope resolver already share. A collaborator asked about a site
+ * they were never granted resolves to nothing, and so does one whose request
+ * names no site at all: there is no host role to read a default from, and
+ * guessing one would let a request reach around the per-site toggle by
+ * omitting the site.
+ */
+/** The catalog keys a collaborator can hold per site, in catalog order. */
+export declare function hostPermissionKeys(): HostPermissionKey[];
+/** What a host role grants for every per-site key, before any toggle. */
+export declare function hostRolePermissionDefaults(role: HostAccessRole): Record<HostPermissionKey, boolean>;
+/**
+ * A collaborator's verdict on ONE site for every per-site key, or null where
+ * they have no access to that site at all. An absent toggle reads as the host
+ * role's default, which is what makes a member document written before
+ * `hostPermissions` existed resolve exactly as it did before.
+ */
+export declare function resolveCollaboratorHostPermissions(member: Partial<AglynOrgMember> | null | undefined, hostId: HostUid | null | undefined): Record<HostPermissionKey, boolean> | null;
+/**
+ * A member's verdict for every per-site key, on whichever axis their
+ * membership is on.
+ *
+ * `customRole` is the member's custom role document when they carry a
+ * `roleId` and the caller has it in hand, and is ignored for a collaborator,
+ * whose org role is a seat-accounting fact rather than a grant. `hostId` is
+ * the site the request is about; an org-wide member resolves the same on
+ * every site and with none named.
+ */
+export declare function resolveMemberHostPermissions(options: {
+    member: Partial<AglynOrgMember> | null | undefined;
+    customRole?: AglynOrgCustomRole | null;
+    hostId?: HostUid | null;
+}): Record<HostPermissionKey, boolean>;
+/**
+ * The `memberPermissions` projection stamped on a host document beside
+ * `memberRoles`: every member who can reach the site, with the verdict for
+ * every per-site key they hold ON it. Org-wide members are resolved against
+ * the custom roles the caller loaded (one read per distinct role, as
+ * `syncOrgAuthProjections` already does for `resolvedPermissions`);
+ * collaborators against their host role. A member who cannot reach the site
+ * has no entry, matching `projectHostMemberRoles`.
+ */
+export declare function projectHostMemberPermissions(members: ReadonlyArray<Partial<AglynOrgMember> & {
+    $id: string;
+}>, hostId: HostUid, customRoles: ReadonlyMap<string, AglynOrgCustomRole | null>): Record<string, Record<HostPermissionKey, boolean>>;

package/src/lib/app-utils/host-permissions.js

@@ -0,0 +1,119 @@
+/**
+ * @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 { listPluginOrgPermissions } from "../plugin-manager/plugin-entitlements.js";
+import { hostRoleFor, isOrgWideMember } from "./organizations.js";
+import { resolveOrgPermissions } from "./org-permissions.js";
+/**
+ * Catalog keys a site collaborator holds PER SITE (AGL-2984), resolved on one
+ * of two axes.
+ *
+ * A plugin that declares a catalog key with `hostRoleDefaults` makes it a
+ * per-site key. For the people whose membership spans the workspace, the key
+ * is an ordinary catalog key: their org role's default, refined by a custom
+ * role and by per-member overrides, the same on every site. A site
+ * collaborator has no org standing to refine — their membership exists only
+ * to carry access to named sites — so for them the key is decided PER SITE,
+ * from the host role they hold there, refined by `hostPermissions[hostId]` on
+ * their member document.
+ *
+ * Which axis applies is `isOrgWideMember`, the predicate the rules projection
+ * and the scope resolver already share. A collaborator asked about a site
+ * they were never granted resolves to nothing, and so does one whose request
+ * names no site at all: there is no host role to read a default from, and
+ * guessing one would let a request reach around the per-site toggle by
+ * omitting the site.
+ */ /** The catalog keys a collaborator can hold per site, in catalog order. */ export function hostPermissionKeys() {
+    return listPluginOrgPermissions().filter((permission)=>permission.hostRoleDefaults !== undefined).map((permission)=>permission.key);
+}
+/** What a host role grants for every per-site key, before any toggle. */ export function hostRolePermissionDefaults(role) {
+    const defaults = {};
+    for (const permission of listPluginOrgPermissions()){
+        if (!permission.hostRoleDefaults) continue;
+        defaults[permission.key] = permission.hostRoleDefaults[role] === true;
+    }
+    return defaults;
+}
+/** Every per-site key, refused. */ function noHostPermissions() {
+    return Object.fromEntries(hostPermissionKeys().map((key)=>[
+            key,
+            false
+        ]));
+}
+/**
+ * A collaborator's verdict on ONE site for every per-site key, or null where
+ * they have no access to that site at all. An absent toggle reads as the host
+ * role's default, which is what makes a member document written before
+ * `hostPermissions` existed resolve exactly as it did before.
+ */ export function resolveCollaboratorHostPermissions(member, hostId) {
+    var _member_hostPermissions;
+    if (!member || !hostId) return null;
+    const role = hostRoleFor(member, hostId);
+    if (!role) return null;
+    const merged = hostRolePermissionDefaults(role);
+    const toggles = (_member_hostPermissions = member.hostPermissions) == null ? void 0 : _member_hostPermissions[hostId];
+    if (toggles) {
+        for (const key of Object.keys(merged)){
+            const value = toggles[key];
+            if (typeof value === 'boolean') merged[key] = value;
+        }
+    }
+    return merged;
+}
+/**
+ * A member's verdict for every per-site key, on whichever axis their
+ * membership is on.
+ *
+ * `customRole` is the member's custom role document when they carry a
+ * `roleId` and the caller has it in hand, and is ignored for a collaborator,
+ * whose org role is a seat-accounting fact rather than a grant. `hostId` is
+ * the site the request is about; an org-wide member resolves the same on
+ * every site and with none named.
+ */ export function resolveMemberHostPermissions(options) {
+    var _resolveCollaboratorHostPermissions;
+    const { member, customRole, hostId } = options;
+    if (!member) return noHostPermissions();
+    if (isOrgWideMember(member)) {
+        const granted = resolveOrgPermissions(member, customRole != null ? customRole : null);
+        return Object.fromEntries(hostPermissionKeys().map((key)=>[
+                key,
+                granted[key] === true
+            ]));
+    }
+    return (_resolveCollaboratorHostPermissions = resolveCollaboratorHostPermissions(member, hostId)) != null ? _resolveCollaboratorHostPermissions : noHostPermissions();
+}
+/**
+ * The `memberPermissions` projection stamped on a host document beside
+ * `memberRoles`: every member who can reach the site, with the verdict for
+ * every per-site key they hold ON it. Org-wide members are resolved against
+ * the custom roles the caller loaded (one read per distinct role, as
+ * `syncOrgAuthProjections` already does for `resolvedPermissions`);
+ * collaborators against their host role. A member who cannot reach the site
+ * has no entry, matching `projectHostMemberRoles`.
+ */ export function projectHostMemberPermissions(members, hostId, customRoles) {
+    const projection = {};
+    for (const member of members){
+        var _customRoles_get;
+        if (!hostRoleFor(member, hostId)) continue;
+        projection[member.$id] = resolveMemberHostPermissions({
+            member,
+            customRole: member.roleId ? (_customRoles_get = customRoles.get(member.roleId)) != null ? _customRoles_get : null : null,
+            hostId
+        });
+    }
+    return projection;
+}
+
+//# sourceMappingURL=host-permissions.js.map

package/src/lib/app-utils/host-permissions.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/host-permissions.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 type {\n  AglynOrgMember,\n  HostAccessRole,\n  HostPermissionKey,\n  HostUid,\n} from '../foundation'\nimport { listPluginOrgPermissions } from '../plugin-manager/plugin-entitlements'\nimport { hostRoleFor, isOrgWideMember } from './organizations'\nimport { resolveOrgPermissions, type AglynOrgCustomRole } from './org-permissions'\n\n/**\n * Catalog keys a site collaborator holds PER SITE (AGL-2984), resolved on one\n * of two axes.\n *\n * A plugin that declares a catalog key with `hostRoleDefaults` makes it a\n * per-site key. For the people whose membership spans the workspace, the key\n * is an ordinary catalog key: their org role's default, refined by a custom\n * role and by per-member overrides, the same on every site. A site\n * collaborator has no org standing to refine — their membership exists only\n * to carry access to named sites — so for them the key is decided PER SITE,\n * from the host role they hold there, refined by `hostPermissions[hostId]` on\n * their member document.\n *\n * Which axis applies is `isOrgWideMember`, the predicate the rules projection\n * and the scope resolver already share. A collaborator asked about a site\n * they were never granted resolves to nothing, and so does one whose request\n * names no site at all: there is no host role to read a default from, and\n * guessing one would let a request reach around the per-site toggle by\n * omitting the site.\n */\n\n/** The catalog keys a collaborator can hold per site, in catalog order. */\nexport function hostPermissionKeys(): HostPermissionKey[] {\n  return listPluginOrgPermissions()\n    .filter((permission) => permission.hostRoleDefaults !== undefined)\n    .map((permission) => permission.key)\n}\n\n/** What a host role grants for every per-site key, before any toggle. */\nexport function hostRolePermissionDefaults(\n  role: HostAccessRole,\n): Record<HostPermissionKey, boolean> {\n  const defaults: Record<HostPermissionKey, boolean> = {}\n  for (const permission of listPluginOrgPermissions()) {\n    if (!permission.hostRoleDefaults) continue\n    defaults[permission.key] = permission.hostRoleDefaults[role] === true\n  }\n  return defaults\n}\n\n/** Every per-site key, refused. */\nfunction noHostPermissions(): Record<HostPermissionKey, boolean> {\n  return Object.fromEntries(hostPermissionKeys().map((key) => [key, false]))\n}\n\n/**\n * A collaborator's verdict on ONE site for every per-site key, or null where\n * they have no access to that site at all. An absent toggle reads as the host\n * role's default, which is what makes a member document written before\n * `hostPermissions` existed resolve exactly as it did before.\n */\nexport function resolveCollaboratorHostPermissions(\n  member: Partial<AglynOrgMember> | null | undefined,\n  hostId: HostUid | null | undefined,\n): Record<HostPermissionKey, boolean> | null {\n  if (!member || !hostId) return null\n  const role = hostRoleFor(member, hostId)\n  if (!role) return null\n  const merged = hostRolePermissionDefaults(role)\n  const toggles = member.hostPermissions?.[hostId]\n  if (toggles) {\n    for (const key of Object.keys(merged)) {\n      const value = toggles[key]\n      if (typeof value === 'boolean') merged[key] = value\n    }\n  }\n  return merged\n}\n\n/**\n * A member's verdict for every per-site key, on whichever axis their\n * membership is on.\n *\n * `customRole` is the member's custom role document when they carry a\n * `roleId` and the caller has it in hand, and is ignored for a collaborator,\n * whose org role is a seat-accounting fact rather than a grant. `hostId` is\n * the site the request is about; an org-wide member resolves the same on\n * every site and with none named.\n */\nexport function resolveMemberHostPermissions(options: {\n  member: Partial<AglynOrgMember> | null | undefined\n  customRole?: AglynOrgCustomRole | null\n  hostId?: HostUid | null\n}): Record<HostPermissionKey, boolean> {\n  const { member, customRole, hostId } = options\n  if (!member) return noHostPermissions()\n  if (isOrgWideMember(member)) {\n    const granted = resolveOrgPermissions(member, customRole ?? null)\n    return Object.fromEntries(\n      hostPermissionKeys().map((key) => [key, granted[key] === true]),\n    )\n  }\n  return resolveCollaboratorHostPermissions(member, hostId) ?? noHostPermissions()\n}\n\n/**\n * The `memberPermissions` projection stamped on a host document beside\n * `memberRoles`: every member who can reach the site, with the verdict for\n * every per-site key they hold ON it. Org-wide members are resolved against\n * the custom roles the caller loaded (one read per distinct role, as\n * `syncOrgAuthProjections` already does for `resolvedPermissions`);\n * collaborators against their host role. A member who cannot reach the site\n * has no entry, matching `projectHostMemberRoles`.\n */\nexport function projectHostMemberPermissions(\n  members: ReadonlyArray<Partial<AglynOrgMember> & { $id: string }>,\n  hostId: HostUid,\n  customRoles: ReadonlyMap<string, AglynOrgCustomRole | null>,\n): Record<string, Record<HostPermissionKey, boolean>> {\n  const projection: Record<string, Record<HostPermissionKey, boolean>> = {}\n  for (const member of members) {\n    if (!hostRoleFor(member, hostId)) continue\n    projection[member.$id] = resolveMemberHostPermissions({\n      member,\n      customRole: member.roleId ? (customRoles.get(member.roleId) ?? null) : null,\n      hostId,\n    })\n  }\n  return projection\n}\n"],"names":["listPluginOrgPermissions","hostRoleFor","isOrgWideMember","resolveOrgPermissions","hostPermissionKeys","filter","permission","hostRoleDefaults","undefined","map","key","hostRolePermissionDefaults","role","defaults","noHostPermissions","Object","fromEntries","resolveCollaboratorHostPermissions","member","hostId","merged","toggles","hostPermissions","keys","value","resolveMemberHostPermissions","options","customRole","granted","projectHostMemberPermissions","members","customRoles","projection","$id","roleId","get"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAQD,SAASA,wBAAwB,QAAQ,2CAAuC;AAChF,SAASC,WAAW,EAAEC,eAAe,QAAQ,qBAAiB;AAC9D,SAASC,qBAAqB,QAAiC,uBAAmB;AAElF;;;;;;;;;;;;;;;;;;;CAmBC,GAED,yEAAyE,GACzE,OAAO,SAASC;IACd,OAAOJ,2BACJK,MAAM,CAAC,CAACC,aAAeA,WAAWC,gBAAgB,KAAKC,WACvDC,GAAG,CAAC,CAACH,aAAeA,WAAWI,GAAG;AACvC;AAEA,uEAAuE,GACvE,OAAO,SAASC,2BACdC,IAAoB;IAEpB,MAAMC,WAA+C,CAAC;IACtD,KAAK,MAAMP,cAAcN,2BAA4B;QACnD,IAAI,CAACM,WAAWC,gBAAgB,EAAE;QAClCM,QAAQ,CAACP,WAAWI,GAAG,CAAC,GAAGJ,WAAWC,gBAAgB,CAACK,KAAK,KAAK;IACnE;IACA,OAAOC;AACT;AAEA,iCAAiC,GACjC,SAASC;IACP,OAAOC,OAAOC,WAAW,CAACZ,qBAAqBK,GAAG,CAAC,CAACC,MAAQ;YAACA;YAAK;SAAM;AAC1E;AAEA;;;;;CAKC,GACD,OAAO,SAASO,mCACdC,MAAkD,EAClDC,MAAkC;QAMlBD;IAJhB,IAAI,CAACA,UAAU,CAACC,QAAQ,OAAO;IAC/B,MAAMP,OAAOX,YAAYiB,QAAQC;IACjC,IAAI,CAACP,MAAM,OAAO;IAClB,MAAMQ,SAAST,2BAA2BC;IAC1C,MAAMS,WAAUH,0BAAAA,OAAOI,eAAe,qBAAtBJ,uBAAwB,CAACC,OAAO;IAChD,IAAIE,SAAS;QACX,KAAK,MAAMX,OAAOK,OAAOQ,IAAI,CAACH,QAAS;YACrC,MAAMI,QAAQH,OAAO,CAACX,IAAI;YAC1B,IAAI,OAAOc,UAAU,WAAWJ,MAAM,CAACV,IAAI,GAAGc;QAChD;IACF;IACA,OAAOJ;AACT;AAEA;;;;;;;;;CASC,GACD,OAAO,SAASK,6BAA6BC,OAI5C;QASQT;IARP,MAAM,EAAEC,MAAM,EAAES,UAAU,EAAER,MAAM,EAAE,GAAGO;IACvC,IAAI,CAACR,QAAQ,OAAOJ;IACpB,IAAIZ,gBAAgBgB,SAAS;QAC3B,MAAMU,UAAUzB,sBAAsBe,QAAQS,qBAAAA,aAAc;QAC5D,OAAOZ,OAAOC,WAAW,CACvBZ,qBAAqBK,GAAG,CAAC,CAACC,MAAQ;gBAACA;gBAAKkB,OAAO,CAAClB,IAAI,KAAK;aAAK;IAElE;IACA,QAAOO,sCAAAA,mCAAmCC,QAAQC,mBAA3CF,sCAAsDH;AAC/D;AAEA;;;;;;;;CAQC,GACD,OAAO,SAASe,6BACdC,OAAiE,EACjEX,MAAe,EACfY,WAA2D;IAE3D,MAAMC,aAAiE,CAAC;IACxE,KAAK,MAAMd,UAAUY,QAAS;YAIGC;QAH/B,IAAI,CAAC9B,YAAYiB,QAAQC,SAAS;QAClCa,UAAU,CAACd,OAAOe,GAAG,CAAC,GAAGR,6BAA6B;YACpDP;YACAS,YAAYT,OAAOgB,MAAM,IAAIH,mBAAAA,YAAYI,GAAG,CAACjB,OAAOgB,MAAM,aAA7BH,mBAAkC,OAAQ;YACvEZ;QACF;IACF;IACA,OAAOa;AACT"}

package/src/lib/app-utils/host-tokens.d.ts

@@ -0,0 +1,228 @@
+/**
+ * @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.
+ */
+/**
+ * Host variables — publisher templates that fill themselves in (AGL-1022).
+ *
+ * A publisher writing an email template cannot reference the installing site,
+ * so every install begins with the same chore: swap the placeholder logo, fix
+ * the business name, correct the links. Miss one and the site sends an email
+ * carrying someone else's branding.
+ *
+ * `host.*` gives artifacts a way to NAME the host instead of hard-coding it.
+ * The author writes `{{host.businessName}}`; the installing site fills it in,
+ * and it stays filled in when that site rebrands.
+ *
+ * ## The namespace IS the security boundary
+ *
+ * This is publisher-authored content resolving against tenant data, so the
+ * registry is CLOSED and each token reads through a hand-written function
+ * rather than a path into the document. That is the whole design: a token
+ * cannot address `stripeAccountId`, or `memberRoles`, or anything else, because
+ * there is no path syntax to express it — `host.` is followed by a key that
+ * either appears in {@link HOST_TOKENS} or resolves to nothing at all. Adding a
+ * token is a deliberate edit here, reviewable as a diff.
+ *
+ * A path-based registry ("allow `host.seo.title`") would have been shorter and
+ * is the version to refuse: allowlisting prefixes is how a namespace grows a
+ * hole, and the first `host.orgId` would be a data leak with a plausible commit
+ * message.
+ *
+ * ## Resolve LATE
+ *
+ * At render and at send, never at install. Freezing values into the artifact
+ * would make a rebrand stop propagating silently — the site would keep sending
+ * last year's business name from a template nobody remembers is a template.
+ *
+ * ## Every token defines what "empty" does
+ *
+ * A site with no logo must produce something deliberate. Never an empty image,
+ * and never the literal `{{host.logo}}` reaching a visitor — a leaked token is
+ * the most embarrassing possible failure for a feature whose entire purpose is
+ * to stop templates looking unfinished.
+ */
+/**
+ * What a token yields, so a renderer knows how to place it and the authoring
+ * surface can refuse it in the wrong slot.
+ *
+ * `text` is the only type safe to drop into arbitrary copy. The others carry a
+ * shape a slot has to understand — an `image` in a paragraph is a URL sitting
+ * in the middle of a sentence, which is exactly the "fails in a sent email"
+ * outcome this typing exists to move to authoring time.
+ */
+export type HostTokenType = 'text' | 'url' | 'email' | 'image' | 'address';
+/** What a renderer should do when a token resolves to nothing. */
+export type HostTokenEmptyBehaviour = 
+/** Render nothing in its place; the surrounding copy still makes sense. */
+'blank'
+/**
+ * The block holding it should be dropped entirely. An `<img src="">` is a
+ * broken-image icon in every mail client, which is worse than no logo.
+ */
+ | 'omit-block';
+/** The site fields a token may read. A closed, explicit surface. */
+export interface HostTokenSource {
+    displayName?: string;
+    logoUrl?: string;
+    subdomain?: string;
+    cname?: string;
+    /** Contact details a publisher template can reference (AGL-1022). */
+    business?: {
+        supportEmail?: string;
+        address?: string;
+        socialLinks?: Array<{
+            label?: string;
+            url?: string;
+        }>;
+    };
+    seo?: {
+        entity?: {
+            name?: string;
+            logo?: string;
+        };
+    };
+}
+export interface HostTokenDefinition {
+    /** The key after `host.` */
+    key: string;
+    type: HostTokenType;
+    label: string;
+    description: string;
+    /** Reads the value. Hand-written per token — never a path into the document. */
+    resolve: (host: HostTokenSource) => string | undefined;
+    /**
+     * A deliberate second choice when `resolve` finds nothing.
+     *
+     * Not a nicety: "fall back to the business name" is what turns a missing logo
+     * from a hole in the page into a wordmark, which is what a careful designer
+     * would have done by hand.
+     */
+    fallback?: (host: HostTokenSource) => string | undefined;
+    whenEmpty: HostTokenEmptyBehaviour;
+}
+/**
+ * The closed registry.
+ *
+ * Ordered as an author would look for them. Every entry is reachable from a
+ * field a site can actually set — a token that can never resolve is worse than
+ * an absent one, because it teaches people the feature does not work.
+ */
+export declare const HOST_TOKENS: Record<string, HostTokenDefinition>;
+/**
+ * The registry's entry for `key`, or undefined when it declares none.
+ *
+ * An OWN entry only. `HOST_TOKENS` is an object literal, so a bare index also
+ * finds the `Object.prototype` members — `constructor`, `toString`, `valueOf` —
+ * and every one of those names matches {@link HOST_TOKEN_PATTERN}. Read that
+ * way, `{{host.constructor}}` answers the `Object` function where a definition
+ * belongs, and calling its `resolve` throws in the middle of a render. A name
+ * the registry does not declare resolves to nothing, whatever the name is.
+ */
+export declare function hostTokenDefinition(key: string): HostTokenDefinition | undefined;
+/**
+ * `{{host.key}}` — whitespace-tolerant, and deliberately NOT dotted beyond one
+ * segment. `host.a.b` does not match, so there is no path syntax to abuse.
+ */
+export declare const HOST_TOKEN_PATTERN: RegExp;
+/** Every `host.*` token in a string, in order, including unknown ones. */
+export declare function hostTokensIn(text: string): string[];
+/** The resolved value of one token, or undefined when the site has none. */
+export declare function resolveHostToken(key: string, host: HostTokenSource | null | undefined): string | undefined;
+/**
+ * Replaces every `host.*` token with the installing site's value.
+ *
+ * An unresolved token — unknown key, or a site that has not set the field —
+ * renders EMPTY, never the literal. Leaking `{{host.logo}}` into a sent email
+ * is the failure this feature exists to prevent, so it cannot be the fallback
+ * for the feature's own gaps. The authoring-time check
+ * ({@link validateHostTokens}) is where a typo is meant to be caught, while the
+ * writer can still fix it.
+ */
+export declare function resolveHostTokens(text: string, host: HostTokenSource | null | undefined): string;
+export interface HostTokenIssue {
+    key: string;
+    /**
+     * `unknown` — no such token; it will render empty.
+     * `wrong-slot` — the token's type cannot be placed here.
+     */
+    kind: 'unknown' | 'wrong-slot';
+    message: string;
+}
+/**
+ * Authoring-time check: catch a token before it reaches a visitor.
+ *
+ * The two things worth failing on are a typo (which would silently render
+ * nothing) and a type mismatch (an image URL dropped into a sentence). Both are
+ * invisible at authoring time without this and obvious afterwards, which is the
+ * wrong way round for something that ends up in a sent email.
+ *
+ * `allow` names the types this slot can take. Omit it for free text, where only
+ * `text` and the string-ish types make sense.
+ */
+export declare function validateHostTokens(text: string, options?: {
+    allow?: readonly HostTokenType[];
+}): HostTokenIssue[];
+/**
+ * Whether a block containing these tokens should be dropped for this site.
+ *
+ * The other half of "every token needs a defined empty behaviour": a logo block
+ * on a site with no logo should not render an empty image, and the renderer
+ * cannot know that from the resolved string alone — `''` is both "no value" and
+ * "a value that happens to be empty". Asking here keeps the rule with the
+ * token definition rather than spread across the surfaces that render it.
+ */
+export declare function shouldOmitBlock(text: string, host: HostTokenSource | null | undefined): boolean;
+/**
+ * Every token with its resolved value for one site, for an authoring picker
+ * that shows what each will actually produce here.
+ *
+ * A picker listing token names alone makes the author guess; showing the value
+ * this site would render is what turns "is it businessName or business_name"
+ * into a question nobody has to ask.
+ */
+export declare function describeHostTokens(host: HostTokenSource | null | undefined): Array<HostTokenDefinition & {
+    token: string;
+    value?: string;
+    set: boolean;
+}>;
+/**
+ * The `host.*` values as a merge-token map, for surfaces that already have a
+ * token substituter of their own.
+ *
+ * This is how EMAIL gets host variables without the email library depending on
+ * this one: `substituteMergeTokens` already matches `{{a.b}}`, so a caller
+ * spreads this into the merge map it was passing anyway. One registry, two
+ * surfaces, no second substitution engine to drift.
+ *
+ * Every registered token appears, INCLUDING the ones this site has not set —
+ * as `''`. Omitting them would leave `{{host.supportEmail}}` for the generic
+ * catch-all to blank, which works today and works by accident: the moment a
+ * surface without that catch-all uses this map, the literal token ships.
+ */
+export declare function hostTokenMerge(host: HostTokenSource | null | undefined): Record<string, string>;
+/**
+ * Resolves `host.*` tokens across every string prop of a normalized node map.
+ *
+ * Mirrors `resolveNodesBindings` deliberately — same shallow-copy discipline,
+ * same string-props-only rule — so a screen and an email resolve the same token
+ * to the same value. The issue's warning is the reason: two resolvers drift,
+ * and then the same token means different things depending on where an author
+ * typed it.
+ *
+ * Returns the input untouched when the site has nothing to substitute, so a
+ * binding-free tree costs one `Object.entries`.
+ */
+export declare function resolveNodesHostTokens<T extends Record<string, any>>(nodes: T, host: HostTokenSource | null | undefined): T;