@aglyn/aglyn 1.0.0-beta.143

package/src/lib/app-utils/request-ip.js

@@ -0,0 +1,344 @@
+/**
+ * @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.
+ */ /**
+ * The ONE client-address reader (AGL-2014).
+ *
+ * Sits beside `request-geo.ts` and does the same job for a different signal:
+ * read a fact about the caller off the request, vendor-neutrally, and return
+ * nothing rather than a guess when it cannot.
+ *
+ * ## The failure this exists for
+ *
+ * Roughly twenty call sites read `x-forwarded-for` and took element `[0]` as
+ * the visitor's address. That is correct only where the edge OVERWRITES the
+ * header. A default self-host does not overwrite it: nginx's
+ * `$proxy_add_x_forwarded_for` and the usual Traefik/Caddy chains APPEND, so a
+ * caller who sends `X-Forwarded-For: 1.2.3.4` arrives at the app as
+ * `1.2.3.4, <their real address>` and element `[0]` is whatever they typed.
+ *
+ * Every rate limiter in the product keys on that value, so on a default Docker
+ * install it was a rate-limit bypass by header: change one character per
+ * request and every limiter hands out a fresh budget. Nothing errors and
+ * nothing is logged. The same value is stored as clickwrap evidence and shown
+ * to an account owner in a new-device sign-in alert, where a forged address is
+ * durable rather than merely a bypass.
+ *
+ * Binding the containers to loopback in `docker-compose.yml` forces traffic
+ * through the operator's proxy. It does not help here: the proxy appending is
+ * exactly the case that remains.
+ *
+ * ## Which hop is the client
+ *
+ * With N appending proxies in front, the last N entries of `x-forwarded-for`
+ * were written by those proxies and are the only ones a caller cannot forge.
+ * The outermost trusted proxy wrote the address IT saw — the real client — so
+ * the client is the Nth entry counted from the RIGHT, and everything to its
+ * left is caller-supplied text that must be ignored.
+ *
+ * The count is the configuration, because it is the only thing the app cannot
+ * work out for itself. It is deliberately not an index: an operator running
+ * one reverse proxy sets `1`, and never has to reason about which end of the
+ * list they are counting from.
+ *
+ * ## The default, and why it is not the same everywhere
+ *
+ * The two candidate defaults fail in opposite directions. Trusting the
+ * LEFTMOST hop keeps Aglyn's own cloud correct and leaves every self-host
+ * spoofable. Trusting the RIGHTMOST keeps self-hosts correct and would be a
+ * silent behavior change on Aglyn's own production.
+ *
+ * Neither has to be guessed, because the platform can be detected. Vercel sets
+ * `VERCEL` in the runtime environment — the same signal `deployment-shape.ts`
+ * already keys on — and it terminates every request at its own edge. So:
+ *
+ *  - **Platform detected** → platform mode. Read `x-vercel-forwarded-for`
+ *    first: Vercel computes it and strips any inbound copy, so on a Vercel
+ *    request it is the one address value a caller cannot influence. That is
+ *    the same trust `request-geo.ts` already places in `x-vercel-ip-country`
+ *    to run the sanctions gate, so it is not a new assumption. If it is
+ *    absent, fall back to the LEFTMOST `x-forwarded-for` hop, which is
+ *    precisely what every call site did before this module existed — so
+ *    nothing on Aglyn's deployment can read differently than it did.
+ *
+ *  - **No platform detected** (a container, a bare Node process, a developer's
+ *    machine) → one trusted proxy, so the RIGHTMOST hop. That is correct for
+ *    both proxy styles at the depth the shipped `docker-compose.yml` describes:
+ *    an overwriting proxy leaves a single entry, where rightmost and leftmost
+ *    are the same value; an appending proxy leaves the real client last.
+ *
+ * An operator with more than one proxy in front sets the real number. Getting
+ * that number too LOW names an intermediate proxy instead of the visitor,
+ * which over-counts — several visitors share one bucket and the limiter
+ * refuses sooner. Getting it too HIGH is the direction that matters, and it
+ * cannot hand out a forged address here: a chain shorter than the configured
+ * depth is clamped to its leftmost entry, and every entry of such a chain was
+ * still written by a trusted proxy.
+ *
+ * ## What this will not do
+ *
+ * ⛔ It never invents an address. When nothing readable is present the answer
+ * is `null` and the caller decides. Returning a placeholder like `'unknown'`
+ * would put every anonymous caller in one rate-limit bucket, which is a denial
+ * of service the limiter inflicts on itself.
+ *
+ * ⛔ No trusted-CIDR matching. A hop count answers the same question with
+ * configuration an operator can actually get right, and a CIDR list that is
+ * subtly wrong fails open in exactly the way this module exists to prevent.
+ *
+ * ⛔ Not for an edge bundle as written. `AGLYN_TRUSTED_PROXY_COUNT` is read
+ * from `process.env` at call time, so it is a genuine runtime variable an
+ * operator can change without rebuilding — unlike the geo header names, which
+ * `apps/console/middleware.ts` drags into the edge bundle and which therefore
+ * have to be mapped through `next.config.js` and fixed at build. Nothing
+ * reads an address in middleware today. Anything that starts to must map the
+ * variable through both `next.config.js` files first, or the edge will read
+ * `undefined` and silently fall back to the default.
+ */ /** The environment variable naming how many proxies sit in front of the app. */ export const TRUSTED_PROXY_COUNT_VAR = 'AGLYN_TRUSTED_PROXY_COUNT';
+/**
+ * The trusted depth assumed when nothing is configured and no platform edge is
+ * detected: one reverse proxy, which is the shape `docker-compose.yml` and the
+ * self-hosting runbook describe.
+ */ export const DEFAULT_TRUSTED_PROXY_COUNT = 1;
+/**
+ * The key fragment a control uses when it has no address and cannot simply
+ * skip — and the decision every caller of {@link readClientIp} has to make.
+ *
+ * Most address-keyed controls in this codebase SKIP when the address is
+ * `null`. A budget keyed on a placeholder is one budget shared by everybody,
+ * so a deployment whose proxy names no caller would refuse password resets,
+ * sign-ins, org creation and site creation for all of its users at once — a
+ * denial of service the limiter inflicts on itself, and a worse outcome than
+ * the control not running on a deployment that cannot identify anybody. Those
+ * controls each have a second key — a uid, an email address, a site — that
+ * still applies.
+ *
+ * The exception is a control whose job is COST rather than identity: the
+ * unauthenticated beacons and the pre-auth REST budget bound how much
+ * unauthenticated work a stranger can cause, they answer the same way whether
+ * or not the limit bites, and they have no second key. Skipping those would
+ * leave an unauthenticated Firestore writer unbounded on exactly the
+ * misconfigured deployment that produced the missing address. They keep
+ * counting, under this bucket, which costs telemetry rather than service.
+ *
+ * Spelled so it cannot be mistaken for an address, and reached only when NO
+ * source produced one — not merely when `x-forwarded-for` was absent.
+ */ export const NO_CLIENT_ADDRESS_BUCKET = 'no-address';
+/**
+ * An upper bound on a configured depth, so a typo cannot express a chain
+ * nobody runs. Past this the value is treated as unset rather than obeyed.
+ */ const MAX_TRUSTED_PROXIES = 32;
+/**
+ * How many proxies to trust, from configuration or from the runtime.
+ *
+ * Read per call rather than frozen at module scope: this is a runtime
+ * variable, and a module-scope snapshot would make it unchangeable without a
+ * rebuild for no reason (see the edge-bundle note in the module comment).
+ */ export function resolveTrustedProxyCount(env = process.env) {
+    var _env_TRUSTED_PROXY_COUNT_VAR;
+    const raw = String((_env_TRUSTED_PROXY_COUNT_VAR = env[TRUSTED_PROXY_COUNT_VAR]) != null ? _env_TRUSTED_PROXY_COUNT_VAR : '').trim();
+    if (raw) {
+        // Whole, non-negative, and small. A junk value must not silently become a
+        // depth: `NaN` would compare false everywhere and quietly read the
+        // leftmost hop, which is the bypass this module exists to close.
+        const parsed = Number(raw);
+        if (Number.isInteger(parsed) && parsed >= 0 && parsed <= MAX_TRUSTED_PROXIES) {
+            return parsed;
+        }
+    }
+    // The platform's own edge. Detected, not guessed — and detected from the
+    // runtime environment rather than from the presence of a `x-vercel-*`
+    // header, which an operator's proxy could pass through from a caller.
+    if (env['VERCEL']) return null;
+    return DEFAULT_TRUSTED_PROXY_COUNT;
+}
+/**
+ * The address Vercel computed for the caller.
+ *
+ * Vercel sets every `x-vercel-*` header itself and overwrites any inbound
+ * copy, so on a Vercel request this is not caller-supplied. It is read only
+ * in platform mode, so an operator's proxy forwarding a forged
+ * `x-vercel-forwarded-for` reaches nothing.
+ */ const PLATFORM_ADDRESS_HEADER = 'x-vercel-forwarded-for';
+/** Wrap either header shape in the `Headers`-like reader the rest uses. */ function readerFor(headers) {
+    if (typeof (headers == null ? void 0 : headers.get) === 'function') {
+        return headers;
+    }
+    const record = headers != null ? headers : {};
+    const lowered = {};
+    for (const [key, value] of Object.entries(record)){
+        if (value === undefined) continue;
+        // A repeated header arrives as an array in node. Joining with `,` restores
+        // the single-list form `Headers.get` would have produced, so the hop
+        // arithmetic below counts the same entries either way.
+        lowered[key.toLowerCase()] = Array.isArray(value) ? value.join(',') : String(value);
+    }
+    return {
+        get: (name)=>{
+            var _lowered_name_toLowerCase;
+            return (_lowered_name_toLowerCase = lowered[name.toLowerCase()]) != null ? _lowered_name_toLowerCase : null;
+        }
+    };
+}
+/** RFC 7239 says an unresolvable node is `unknown`; squid writes it too. */ const NOT_AN_ADDRESS = new Set([
+    'unknown',
+    'null',
+    'undefined'
+]);
+const IPV4 = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/;
+const IPV6 = /^[0-9a-f:]+$/;
+/**
+ * The one spelling of an address this module ever returns, or `null`.
+ *
+ * Normalization is not cosmetic. A rate-limit key is an exact string, so
+ * `2001:DB8::1` and `2001:db8::1`, or the same address with and without a
+ * source port, would be two budgets for one visitor — the bypass again, in
+ * miniature.
+ *
+ *  - a port is dropped: it changes per connection,
+ *  - `[…]` brackets and an IPv6 zone (`%eth0`) are dropped,
+ *  - an IPv4-mapped IPv6 (`::ffff:1.2.3.4`) collapses to its IPv4 form, so a
+ *    node socket address and a proxy's header value share one bucket,
+ *  - anything that is not an address — `unknown`, RFC 7239's obfuscated
+ *    `_hidden` identifiers, a hostname, a header some proxy passed through
+ *    under this name — is `null` rather than a key.
+ */ export function normalizeClientIp(raw) {
+    var _value_match;
+    let value = String(raw != null ? raw : '').trim().replace(/^"|"$/g, '').trim().toLowerCase();
+    if (!value) return null;
+    // RFC 7239 obfuscated identifiers are deliberately not addresses.
+    if (value.startsWith('_')) return null;
+    if (NOT_AN_ADDRESS.has(value)) return null;
+    if (value.startsWith('[')) {
+        // `[2001:db8::1]:443` — brackets exist precisely to make the port
+        // unambiguous, so this is the only form a port may be stripped from.
+        const close = value.indexOf(']');
+        if (close < 0) return null;
+        value = value.slice(1, close);
+    } else if (((_value_match = value.match(/:/g)) != null ? _value_match : []).length === 1) {
+        // Exactly one colon can only be `host:port`; a bare IPv6 has more.
+        value = value.slice(0, value.indexOf(':'));
+    }
+    // A zone index identifies a local interface, not a caller.
+    const zone = value.indexOf('%');
+    if (zone >= 0) value = value.slice(0, zone);
+    if (!value) return null;
+    const mapped = /^::ffff:(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/.exec(value);
+    if (mapped) value = mapped[1];
+    const v4 = IPV4.exec(value);
+    if (v4) {
+        // `999.1.1.1` matches the shape and is not an address. Leading zeros are
+        // rejected with it: `010.0.0.1` and `10.0.0.1` are the same host to some
+        // resolvers and two different rate-limit keys here.
+        for(let i = 1; i <= 4; i += 1){
+            const octet = v4[i];
+            if (octet.length > 1 && octet.startsWith('0')) return null;
+            if (Number(octet) > 255) return null;
+        }
+        return value;
+    }
+    // Loose on IPv6 by design: the job is to reject text that is not an address,
+    // not to re-implement a parser. It must contain a colon to get here, so a
+    // hostname or a stray token cannot pass.
+    if (value.includes(':') && IPV6.test(value)) return value;
+    return null;
+}
+/** Split a comma-separated forwarding header into its raw entries. */ function entriesOf(value) {
+    return String(value != null ? value : '').split(',').map((entry)=>entry.trim()).filter(Boolean);
+}
+/**
+ * The entry a chain of `length` hops attributes to the client, at `depth`
+ * trusted proxies.
+ *
+ * Clamped when the chain is SHORTER than configured. That happens when an
+ * outer proxy overwrites rather than appends, and every entry of such a chain
+ * was still written by a trusted proxy — so the leftmost is the honest answer
+ * rather than a reason to refuse. It is not clamped at the other end: a chain
+ * LONGER than configured is the attack shape, and the extra entries on the
+ * left are exactly what must be ignored.
+ */ function clientIndex(length, depth) {
+    return Math.max(0, length - depth);
+}
+/**
+ * The `for=` values of an RFC 7239 `Forwarded` header, left to right.
+ *
+ * Comma-splitting is a simplification: a quoted `for=` value may in principle
+ * contain a comma. No proxy in the wild emits one, and the alternative is a
+ * full parameter parser for a header that is the third fallback here.
+ */ function forwardedEntries(value) {
+    const out = [];
+    for (const element of entriesOf(value)){
+        for (const param of element.split(';')){
+            const [name, ...rest] = param.split('=');
+            if (name.trim().toLowerCase() !== 'for') continue;
+            out.push(rest.join('=').trim());
+            break;
+        }
+    }
+    return out;
+}
+/**
+ * The caller's address, or `null` when nothing readable identifies them.
+ *
+ * Sources in order, and the order is the security property: a reading that
+ * depends on the trusted depth always wins, and the single-valued fallbacks
+ * only apply when the chain reading produced nothing at all. A caller cannot
+ * demote the reader to a weaker source, because a proxy that writes
+ * `x-forwarded-for` writes it on every request — the fallbacks are reachable
+ * only on a deployment whose proxy sets something else, or on none.
+ *
+ *  1. the platform edge's own value, in platform mode,
+ *  2. `x-forwarded-for` at the trusted hop,
+ *  3. `x-real-ip`, single-valued and written by the proxy,
+ *  4. `Forwarded` (RFC 7239) at the trusted hop,
+ *  5. the transport peer, when the caller supplied one.
+ */ export function readClientIp(headers, options = {}) {
+    const reader = readerFor(headers);
+    const depth = options.trustedProxyCount !== undefined ? options.trustedProxyCount : resolveTrustedProxyCount(options.env);
+    if (depth === null) {
+        const platform = normalizeClientIp(reader.get(PLATFORM_ADDRESS_HEADER));
+        if (platform) return platform;
+    }
+    // Depth 0 is "nothing is in front of me", so every forwarding header is
+    // caller-supplied and none of them may be read. Skipping straight to the
+    // peer is the whole point of offering the value.
+    if (depth !== 0) {
+        // In platform mode the edge presents one authoritative value, so the
+        // leftmost entry is the client — which is also, exactly, what every call
+        // site read before this module existed.
+        const hops = depth === null ? 1 : depth;
+        const forwardedFor = entriesOf(reader.get('x-forwarded-for'));
+        if (forwardedFor.length) {
+            const index = depth === null ? 0 : clientIndex(forwardedFor.length, hops);
+            // Deliberately does NOT slide to a neighbouring entry when the trusted
+            // hop is unreadable. Letting content choose the position is how a
+            // spoofer would push the reader back onto their own text; falling
+            // through to the next SOURCE cannot be steered that way.
+            const hop = normalizeClientIp(forwardedFor[index]);
+            if (hop) return hop;
+        }
+        const real = normalizeClientIp(reader.get('x-real-ip'));
+        if (real) return real;
+        const forwarded = forwardedEntries(reader.get('forwarded'));
+        if (forwarded.length) {
+            const index = depth === null ? 0 : clientIndex(forwarded.length, hops);
+            const hop = normalizeClientIp(forwarded[index]);
+            if (hop) return hop;
+        }
+    }
+    return normalizeClientIp(options.remoteAddress);
+}
+
+//# sourceMappingURL=request-ip.js.map

package/src/lib/app-utils/request-ip.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/request-ip.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 * The ONE client-address reader (AGL-2014).\n *\n * Sits beside `request-geo.ts` and does the same job for a different signal:\n * read a fact about the caller off the request, vendor-neutrally, and return\n * nothing rather than a guess when it cannot.\n *\n * ## The failure this exists for\n *\n * Roughly twenty call sites read `x-forwarded-for` and took element `[0]` as\n * the visitor's address. That is correct only where the edge OVERWRITES the\n * header. A default self-host does not overwrite it: nginx's\n * `$proxy_add_x_forwarded_for` and the usual Traefik/Caddy chains APPEND, so a\n * caller who sends `X-Forwarded-For: 1.2.3.4` arrives at the app as\n * `1.2.3.4, <their real address>` and element `[0]` is whatever they typed.\n *\n * Every rate limiter in the product keys on that value, so on a default Docker\n * install it was a rate-limit bypass by header: change one character per\n * request and every limiter hands out a fresh budget. Nothing errors and\n * nothing is logged. The same value is stored as clickwrap evidence and shown\n * to an account owner in a new-device sign-in alert, where a forged address is\n * durable rather than merely a bypass.\n *\n * Binding the containers to loopback in `docker-compose.yml` forces traffic\n * through the operator's proxy. It does not help here: the proxy appending is\n * exactly the case that remains.\n *\n * ## Which hop is the client\n *\n * With N appending proxies in front, the last N entries of `x-forwarded-for`\n * were written by those proxies and are the only ones a caller cannot forge.\n * The outermost trusted proxy wrote the address IT saw — the real client — so\n * the client is the Nth entry counted from the RIGHT, and everything to its\n * left is caller-supplied text that must be ignored.\n *\n * The count is the configuration, because it is the only thing the app cannot\n * work out for itself. It is deliberately not an index: an operator running\n * one reverse proxy sets `1`, and never has to reason about which end of the\n * list they are counting from.\n *\n * ## The default, and why it is not the same everywhere\n *\n * The two candidate defaults fail in opposite directions. Trusting the\n * LEFTMOST hop keeps Aglyn's own cloud correct and leaves every self-host\n * spoofable. Trusting the RIGHTMOST keeps self-hosts correct and would be a\n * silent behavior change on Aglyn's own production.\n *\n * Neither has to be guessed, because the platform can be detected. Vercel sets\n * `VERCEL` in the runtime environment — the same signal `deployment-shape.ts`\n * already keys on — and it terminates every request at its own edge. So:\n *\n *  - **Platform detected** → platform mode. Read `x-vercel-forwarded-for`\n *    first: Vercel computes it and strips any inbound copy, so on a Vercel\n *    request it is the one address value a caller cannot influence. That is\n *    the same trust `request-geo.ts` already places in `x-vercel-ip-country`\n *    to run the sanctions gate, so it is not a new assumption. If it is\n *    absent, fall back to the LEFTMOST `x-forwarded-for` hop, which is\n *    precisely what every call site did before this module existed — so\n *    nothing on Aglyn's deployment can read differently than it did.\n *\n *  - **No platform detected** (a container, a bare Node process, a developer's\n *    machine) → one trusted proxy, so the RIGHTMOST hop. That is correct for\n *    both proxy styles at the depth the shipped `docker-compose.yml` describes:\n *    an overwriting proxy leaves a single entry, where rightmost and leftmost\n *    are the same value; an appending proxy leaves the real client last.\n *\n * An operator with more than one proxy in front sets the real number. Getting\n * that number too LOW names an intermediate proxy instead of the visitor,\n * which over-counts — several visitors share one bucket and the limiter\n * refuses sooner. Getting it too HIGH is the direction that matters, and it\n * cannot hand out a forged address here: a chain shorter than the configured\n * depth is clamped to its leftmost entry, and every entry of such a chain was\n * still written by a trusted proxy.\n *\n * ## What this will not do\n *\n * ⛔ It never invents an address. When nothing readable is present the answer\n * is `null` and the caller decides. Returning a placeholder like `'unknown'`\n * would put every anonymous caller in one rate-limit bucket, which is a denial\n * of service the limiter inflicts on itself.\n *\n * ⛔ No trusted-CIDR matching. A hop count answers the same question with\n * configuration an operator can actually get right, and a CIDR list that is\n * subtly wrong fails open in exactly the way this module exists to prevent.\n *\n * ⛔ Not for an edge bundle as written. `AGLYN_TRUSTED_PROXY_COUNT` is read\n * from `process.env` at call time, so it is a genuine runtime variable an\n * operator can change without rebuilding — unlike the geo header names, which\n * `apps/console/middleware.ts` drags into the edge bundle and which therefore\n * have to be mapped through `next.config.js` and fixed at build. Nothing\n * reads an address in middleware today. Anything that starts to must map the\n * variable through both `next.config.js` files first, or the edge will read\n * `undefined` and silently fall back to the default.\n */\n\nimport type { HeaderReader } from './request-geo'\n\n/** The environment variable naming how many proxies sit in front of the app. */\nexport const TRUSTED_PROXY_COUNT_VAR = 'AGLYN_TRUSTED_PROXY_COUNT'\n\n/**\n * The trusted depth assumed when nothing is configured and no platform edge is\n * detected: one reverse proxy, which is the shape `docker-compose.yml` and the\n * self-hosting runbook describe.\n */\nexport const DEFAULT_TRUSTED_PROXY_COUNT = 1\n\n/**\n * `null` means \"a platform edge normalizes the header, trust what it presents\".\n * A number is a literal count of proxies in front, and `0` means none — a\n * process reachable directly from the internet, where every forwarding header\n * is caller-supplied text and only the transport peer is a fact.\n */\nexport type TrustedProxyDepth = number | null\n\n/**\n * The key fragment a control uses when it has no address and cannot simply\n * skip — and the decision every caller of {@link readClientIp} has to make.\n *\n * Most address-keyed controls in this codebase SKIP when the address is\n * `null`. A budget keyed on a placeholder is one budget shared by everybody,\n * so a deployment whose proxy names no caller would refuse password resets,\n * sign-ins, org creation and site creation for all of its users at once — a\n * denial of service the limiter inflicts on itself, and a worse outcome than\n * the control not running on a deployment that cannot identify anybody. Those\n * controls each have a second key — a uid, an email address, a site — that\n * still applies.\n *\n * The exception is a control whose job is COST rather than identity: the\n * unauthenticated beacons and the pre-auth REST budget bound how much\n * unauthenticated work a stranger can cause, they answer the same way whether\n * or not the limit bites, and they have no second key. Skipping those would\n * leave an unauthenticated Firestore writer unbounded on exactly the\n * misconfigured deployment that produced the missing address. They keep\n * counting, under this bucket, which costs telemetry rather than service.\n *\n * Spelled so it cannot be mistaken for an address, and reached only when NO\n * source produced one — not merely when `x-forwarded-for` was absent.\n */\nexport const NO_CLIENT_ADDRESS_BUCKET = 'no-address'\n\n/** Node-style header records alongside a `Headers`-shaped reader. */\nexport type ClientIpHeaders =\n  | HeaderReader\n  | Record<string, string | string[] | undefined>\n\nexport interface ClientIpOptions {\n  /**\n   * Overrides the configured depth. Tests pass this; production code should\n   * not, so an operator's configuration is the only thing that decides.\n   */\n  trustedProxyCount?: TrustedProxyDepth\n  /**\n   * The transport peer — `req.socket.remoteAddress` on a node-style handler.\n   * Consulted last, and only because it is the one address the process knows\n   * first-hand. Behind a proxy that sets no forwarding header at all it is the\n   * proxy's own address, which is a single shared bucket rather than a\n   * visitor; that is a misconfiguration the self-hosting docs name, not a\n   * reading this module can improve on.\n   */\n  remoteAddress?: string | null\n  /** Injectable for tests; defaults to `process.env`. */\n  env?: Record<string, string | undefined>\n}\n\n/**\n * An upper bound on a configured depth, so a typo cannot express a chain\n * nobody runs. Past this the value is treated as unset rather than obeyed.\n */\nconst MAX_TRUSTED_PROXIES = 32\n\n/**\n * How many proxies to trust, from configuration or from the runtime.\n *\n * Read per call rather than frozen at module scope: this is a runtime\n * variable, and a module-scope snapshot would make it unchangeable without a\n * rebuild for no reason (see the edge-bundle note in the module comment).\n */\nexport function resolveTrustedProxyCount(\n  env: Record<string, string | undefined> = process.env,\n): TrustedProxyDepth {\n  const raw = String(env[TRUSTED_PROXY_COUNT_VAR] ?? '').trim()\n  if (raw) {\n    // Whole, non-negative, and small. A junk value must not silently become a\n    // depth: `NaN` would compare false everywhere and quietly read the\n    // leftmost hop, which is the bypass this module exists to close.\n    const parsed = Number(raw)\n    if (Number.isInteger(parsed) && parsed >= 0 && parsed <= MAX_TRUSTED_PROXIES) {\n      return parsed\n    }\n  }\n  // The platform's own edge. Detected, not guessed — and detected from the\n  // runtime environment rather than from the presence of a `x-vercel-*`\n  // header, which an operator's proxy could pass through from a caller.\n  if (env['VERCEL']) return null\n  return DEFAULT_TRUSTED_PROXY_COUNT\n}\n\n/**\n * The address Vercel computed for the caller.\n *\n * Vercel sets every `x-vercel-*` header itself and overwrites any inbound\n * copy, so on a Vercel request this is not caller-supplied. It is read only\n * in platform mode, so an operator's proxy forwarding a forged\n * `x-vercel-forwarded-for` reaches nothing.\n */\nconst PLATFORM_ADDRESS_HEADER = 'x-vercel-forwarded-for'\n\n/** Wrap either header shape in the `Headers`-like reader the rest uses. */\nfunction readerFor(headers: ClientIpHeaders): HeaderReader {\n  if (typeof (headers as HeaderReader)?.get === 'function') {\n    return headers as HeaderReader\n  }\n  const record = (headers ?? {}) as Record<string, string | string[] | undefined>\n  const lowered: Record<string, string> = {}\n  for (const [key, value] of Object.entries(record)) {\n    if (value === undefined) continue\n    // A repeated header arrives as an array in node. Joining with `,` restores\n    // the single-list form `Headers.get` would have produced, so the hop\n    // arithmetic below counts the same entries either way.\n    lowered[key.toLowerCase()] = Array.isArray(value) ? value.join(',') : String(value)\n  }\n  return { get: (name: string) => lowered[name.toLowerCase()] ?? null }\n}\n\n/** RFC 7239 says an unresolvable node is `unknown`; squid writes it too. */\nconst NOT_AN_ADDRESS = new Set(['unknown', 'null', 'undefined'])\n\nconst IPV4 = /^(\\d{1,3})\\.(\\d{1,3})\\.(\\d{1,3})\\.(\\d{1,3})$/\nconst IPV6 = /^[0-9a-f:]+$/\n\n/**\n * The one spelling of an address this module ever returns, or `null`.\n *\n * Normalization is not cosmetic. A rate-limit key is an exact string, so\n * `2001:DB8::1` and `2001:db8::1`, or the same address with and without a\n * source port, would be two budgets for one visitor — the bypass again, in\n * miniature.\n *\n *  - a port is dropped: it changes per connection,\n *  - `[…]` brackets and an IPv6 zone (`%eth0`) are dropped,\n *  - an IPv4-mapped IPv6 (`::ffff:1.2.3.4`) collapses to its IPv4 form, so a\n *    node socket address and a proxy's header value share one bucket,\n *  - anything that is not an address — `unknown`, RFC 7239's obfuscated\n *    `_hidden` identifiers, a hostname, a header some proxy passed through\n *    under this name — is `null` rather than a key.\n */\nexport function normalizeClientIp(raw: string | null | undefined): string | null {\n  let value = String(raw ?? '')\n    .trim()\n    .replace(/^\"|\"$/g, '')\n    .trim()\n    .toLowerCase()\n  if (!value) return null\n  // RFC 7239 obfuscated identifiers are deliberately not addresses.\n  if (value.startsWith('_')) return null\n  if (NOT_AN_ADDRESS.has(value)) return null\n\n  if (value.startsWith('[')) {\n    // `[2001:db8::1]:443` — brackets exist precisely to make the port\n    // unambiguous, so this is the only form a port may be stripped from.\n    const close = value.indexOf(']')\n    if (close < 0) return null\n    value = value.slice(1, close)\n  } else if ((value.match(/:/g) ?? []).length === 1) {\n    // Exactly one colon can only be `host:port`; a bare IPv6 has more.\n    value = value.slice(0, value.indexOf(':'))\n  }\n\n  // A zone index identifies a local interface, not a caller.\n  const zone = value.indexOf('%')\n  if (zone >= 0) value = value.slice(0, zone)\n  if (!value) return null\n\n  const mapped = /^::ffff:(\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}\\.\\d{1,3})$/.exec(value)\n  if (mapped) value = mapped[1]\n\n  const v4 = IPV4.exec(value)\n  if (v4) {\n    // `999.1.1.1` matches the shape and is not an address. Leading zeros are\n    // rejected with it: `010.0.0.1` and `10.0.0.1` are the same host to some\n    // resolvers and two different rate-limit keys here.\n    for (let i = 1; i <= 4; i += 1) {\n      const octet = v4[i]\n      if (octet.length > 1 && octet.startsWith('0')) return null\n      if (Number(octet) > 255) return null\n    }\n    return value\n  }\n  // Loose on IPv6 by design: the job is to reject text that is not an address,\n  // not to re-implement a parser. It must contain a colon to get here, so a\n  // hostname or a stray token cannot pass.\n  if (value.includes(':') && IPV6.test(value)) return value\n  return null\n}\n\n/** Split a comma-separated forwarding header into its raw entries. */\nfunction entriesOf(value: string | null): string[] {\n  return String(value ?? '')\n    .split(',')\n    .map((entry) => entry.trim())\n    .filter(Boolean)\n}\n\n/**\n * The entry a chain of `length` hops attributes to the client, at `depth`\n * trusted proxies.\n *\n * Clamped when the chain is SHORTER than configured. That happens when an\n * outer proxy overwrites rather than appends, and every entry of such a chain\n * was still written by a trusted proxy — so the leftmost is the honest answer\n * rather than a reason to refuse. It is not clamped at the other end: a chain\n * LONGER than configured is the attack shape, and the extra entries on the\n * left are exactly what must be ignored.\n */\nfunction clientIndex(length: number, depth: number): number {\n  return Math.max(0, length - depth)\n}\n\n/**\n * The `for=` values of an RFC 7239 `Forwarded` header, left to right.\n *\n * Comma-splitting is a simplification: a quoted `for=` value may in principle\n * contain a comma. No proxy in the wild emits one, and the alternative is a\n * full parameter parser for a header that is the third fallback here.\n */\nfunction forwardedEntries(value: string | null): string[] {\n  const out: string[] = []\n  for (const element of entriesOf(value)) {\n    for (const param of element.split(';')) {\n      const [name, ...rest] = param.split('=')\n      if (name.trim().toLowerCase() !== 'for') continue\n      out.push(rest.join('=').trim())\n      break\n    }\n  }\n  return out\n}\n\n/**\n * The caller's address, or `null` when nothing readable identifies them.\n *\n * Sources in order, and the order is the security property: a reading that\n * depends on the trusted depth always wins, and the single-valued fallbacks\n * only apply when the chain reading produced nothing at all. A caller cannot\n * demote the reader to a weaker source, because a proxy that writes\n * `x-forwarded-for` writes it on every request — the fallbacks are reachable\n * only on a deployment whose proxy sets something else, or on none.\n *\n *  1. the platform edge's own value, in platform mode,\n *  2. `x-forwarded-for` at the trusted hop,\n *  3. `x-real-ip`, single-valued and written by the proxy,\n *  4. `Forwarded` (RFC 7239) at the trusted hop,\n *  5. the transport peer, when the caller supplied one.\n */\nexport function readClientIp(\n  headers: ClientIpHeaders,\n  options: ClientIpOptions = {},\n): string | null {\n  const reader = readerFor(headers)\n  const depth =\n    options.trustedProxyCount !== undefined\n      ? options.trustedProxyCount\n      : resolveTrustedProxyCount(options.env)\n\n  if (depth === null) {\n    const platform = normalizeClientIp(reader.get(PLATFORM_ADDRESS_HEADER))\n    if (platform) return platform\n  }\n\n  // Depth 0 is \"nothing is in front of me\", so every forwarding header is\n  // caller-supplied and none of them may be read. Skipping straight to the\n  // peer is the whole point of offering the value.\n  if (depth !== 0) {\n    // In platform mode the edge presents one authoritative value, so the\n    // leftmost entry is the client — which is also, exactly, what every call\n    // site read before this module existed.\n    const hops = depth === null ? 1 : depth\n\n    const forwardedFor = entriesOf(reader.get('x-forwarded-for'))\n    if (forwardedFor.length) {\n      const index = depth === null ? 0 : clientIndex(forwardedFor.length, hops)\n      // Deliberately does NOT slide to a neighbouring entry when the trusted\n      // hop is unreadable. Letting content choose the position is how a\n      // spoofer would push the reader back onto their own text; falling\n      // through to the next SOURCE cannot be steered that way.\n      const hop = normalizeClientIp(forwardedFor[index])\n      if (hop) return hop\n    }\n\n    const real = normalizeClientIp(reader.get('x-real-ip'))\n    if (real) return real\n\n    const forwarded = forwardedEntries(reader.get('forwarded'))\n    if (forwarded.length) {\n      const index = depth === null ? 0 : clientIndex(forwarded.length, hops)\n      const hop = normalizeClientIp(forwarded[index])\n      if (hop) return hop\n    }\n  }\n\n  return normalizeClientIp(options.remoteAddress)\n}\n"],"names":["TRUSTED_PROXY_COUNT_VAR","DEFAULT_TRUSTED_PROXY_COUNT","NO_CLIENT_ADDRESS_BUCKET","MAX_TRUSTED_PROXIES","resolveTrustedProxyCount","env","process","raw","String","trim","parsed","Number","isInteger","PLATFORM_ADDRESS_HEADER","readerFor","headers","get","record","lowered","key","value","Object","entries","undefined","toLowerCase","Array","isArray","join","name","NOT_AN_ADDRESS","Set","IPV4","IPV6","normalizeClientIp","replace","startsWith","has","close","indexOf","slice","match","length","zone","mapped","exec","v4","i","octet","includes","test","entriesOf","split","map","entry","filter","Boolean","clientIndex","depth","Math","max","forwardedEntries","out","element","param","rest","push","readClientIp","options","reader","trustedProxyCount","platform","hops","forwardedFor","index","hop","real","forwarded","remoteAddress"],"mappings":"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"}

package/src/lib/app-utils/resolve-named-tokens.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @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 { AglynNodeSchema, NodeId } from '../foundation';
+/**
+ * Named-token substitution (AGL-105): replaces `{{name}}` occurrences in
+ * every node's string props with the provided values — used for
+ * entry-template screens where the tenant injects `entry.title`,
+ * `entry.body`, etc. Only the provided names are touched, so host variable
+ * and function tokens pass through to the regular binding resolver.
+ */
+export declare function resolveNamedTokens<N extends AglynNodeSchema = AglynNodeSchema>(nodes: Record<NodeId, N>, tokens: Record<string, string> | null | undefined): Record<NodeId, N>;
+export default resolveNamedTokens;

package/src/lib/app-utils/resolve-named-tokens.js

@@ -0,0 +1,59 @@
+/**
+ * @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 { _ as _extends } from "@swc/helpers/_/_extends";
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function substitute(value, pattern, tokens) {
+    if (typeof value === 'string') {
+        return value.replace(pattern, (_, name)=>{
+            var _tokens_name;
+            return (_tokens_name = tokens[name]) != null ? _tokens_name : '';
+        });
+    }
+    if (Array.isArray(value)) {
+        return value.map((entry)=>substitute(entry, pattern, tokens));
+    }
+    if (value && typeof value === 'object') {
+        const next = {};
+        for (const [key, entry] of Object.entries(value)){
+            next[key] = substitute(entry, pattern, tokens);
+        }
+        return next;
+    }
+    return value;
+}
+/**
+ * Named-token substitution (AGL-105): replaces `{{name}}` occurrences in
+ * every node's string props with the provided values — used for
+ * entry-template screens where the tenant injects `entry.title`,
+ * `entry.body`, etc. Only the provided names are touched, so host variable
+ * and function tokens pass through to the regular binding resolver.
+ */ export function resolveNamedTokens(nodes, tokens) {
+    const names = Object.keys(tokens != null ? tokens : {});
+    if (!tokens || names.length === 0) return nodes;
+    const pattern = new RegExp(`\\{\\{\\s*(${names.map(escapeRegExp).join('|')})\\s*\\}\\}`, 'g');
+    const next = {};
+    for (const [id, node] of Object.entries(nodes)){
+        next[id] = (node == null ? void 0 : node.props) ? _extends({}, node, {
+            props: substitute(node.props, pattern, tokens)
+        }) : node;
+    }
+    return next;
+}
+export default resolveNamedTokens;
+
+//# sourceMappingURL=resolve-named-tokens.js.map

package/src/lib/app-utils/resolve-named-tokens.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/resolve-named-tokens.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 { AglynNodeSchema, NodeId } from '../foundation'\n\nfunction escapeRegExp(value: string) {\n  return value.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&')\n}\n\nfunction substitute(value: unknown, pattern: RegExp, tokens: Record<string, string>): unknown {\n  if (typeof value === 'string') {\n    return value.replace(pattern, (_, name: string) => tokens[name] ?? '')\n  }\n  if (Array.isArray(value)) {\n    return value.map((entry) => substitute(entry, pattern, tokens))\n  }\n  if (value && typeof value === 'object') {\n    const next: Record<string, unknown> = {}\n    for (const [key, entry] of Object.entries(value)) {\n      next[key] = substitute(entry, pattern, tokens)\n    }\n    return next\n  }\n  return value\n}\n\n/**\n * Named-token substitution (AGL-105): replaces `{{name}}` occurrences in\n * every node's string props with the provided values — used for\n * entry-template screens where the tenant injects `entry.title`,\n * `entry.body`, etc. Only the provided names are touched, so host variable\n * and function tokens pass through to the regular binding resolver.\n */\nexport function resolveNamedTokens<N extends AglynNodeSchema = AglynNodeSchema>(\n  nodes: Record<NodeId, N>,\n  tokens: Record<string, string> | null | undefined,\n): Record<NodeId, N> {\n  const names = Object.keys(tokens ?? {})\n  if (!tokens || names.length === 0) return nodes\n  const pattern = new RegExp(\n    `\\\\{\\\\{\\\\s*(${names.map(escapeRegExp).join('|')})\\\\s*\\\\}\\\\}`,\n    'g',\n  )\n  const next: Record<NodeId, N> = {}\n  for (const [id, node] of Object.entries(nodes)) {\n    next[id] = node?.props\n      ? { ...node, props: substitute(node.props, pattern, tokens) as any }\n      : node\n  }\n  return next\n}\n\nexport default resolveNamedTokens\n"],"names":["escapeRegExp","value","replace","substitute","pattern","tokens","_","name","Array","isArray","map","entry","next","key","Object","entries","resolveNamedTokens","nodes","names","keys","length","RegExp","join","id","node","props"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC;AAID,SAASA,aAAaC,KAAa;IACjC,OAAOA,MAAMC,OAAO,CAAC,uBAAuB;AAC9C;AAEA,SAASC,WAAWF,KAAc,EAAEG,OAAe,EAAEC,MAA8B;IACjF,IAAI,OAAOJ,UAAU,UAAU;QAC7B,OAAOA,MAAMC,OAAO,CAACE,SAAS,CAACE,GAAGC;gBAAiBF;oBAAAA,eAAAA,MAAM,CAACE,KAAK,YAAZF,eAAgB;;IACrE;IACA,IAAIG,MAAMC,OAAO,CAACR,QAAQ;QACxB,OAAOA,MAAMS,GAAG,CAAC,CAACC,QAAUR,WAAWQ,OAAOP,SAASC;IACzD;IACA,IAAIJ,SAAS,OAAOA,UAAU,UAAU;QACtC,MAAMW,OAAgC,CAAC;QACvC,KAAK,MAAM,CAACC,KAAKF,MAAM,IAAIG,OAAOC,OAAO,CAACd,OAAQ;YAChDW,IAAI,CAACC,IAAI,GAAGV,WAAWQ,OAAOP,SAASC;QACzC;QACA,OAAOO;IACT;IACA,OAAOX;AACT;AAEA;;;;;;CAMC,GACD,OAAO,SAASe,mBACdC,KAAwB,EACxBZ,MAAiD;IAEjD,MAAMa,QAAQJ,OAAOK,IAAI,CAACd,iBAAAA,SAAU,CAAC;IACrC,IAAI,CAACA,UAAUa,MAAME,MAAM,KAAK,GAAG,OAAOH;IAC1C,MAAMb,UAAU,IAAIiB,OAClB,CAAC,WAAW,EAAEH,MAAMR,GAAG,CAACV,cAAcsB,IAAI,CAAC,KAAK,WAAW,CAAC,EAC5D;IAEF,MAAMV,OAA0B,CAAC;IACjC,KAAK,MAAM,CAACW,IAAIC,KAAK,IAAIV,OAAOC,OAAO,CAACE,OAAQ;QAC9CL,IAAI,CAACW,GAAG,GAAGC,CAAAA,wBAAAA,KAAMC,KAAK,IAClB,aAAKD;YAAMC,OAAOtB,WAAWqB,KAAKC,KAAK,EAAErB,SAASC;aAClDmB;IACN;IACA,OAAOZ;AACT;AAEA,eAAeI,mBAAkB"}

package/src/lib/app-utils/responsive-typography-sx.d.ts

@@ -0,0 +1,77 @@
+/**
+ * @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.
+ */
+/**
+ * A Styles-panel font size must beat the theme's responsive type ramp.
+ *
+ * `createResponsiveTheme` finishes with MUI's `responsiveFontSizes`, which
+ * bakes a per-breakpoint `fontSize` into each ramped typography VARIANT as
+ * literal `@media (min-width:…px)` keys. Emotion serialises a style object's
+ * plain properties before its at-rules, and the variant is serialised before
+ * the `sx` prop, so the emitted rule for one element reads:
+ *
+ * ```css
+ * .css-x { font-size: 1.5625rem;  ……  font-size: 44px; }   ← variant, then sx
+ * @media (min-width:1536px) { .css-x { font-size: 2.125rem; } }  ← variant ramp
+ * ```
+ *
+ * Both declarations sit on the same class, so the LAST one wins — and the
+ * variant's ramp is last. An author who typed 44 into Font Size at "all
+ * screen sizes" got 34px on a desktop viewport, with nothing in the panel
+ * to explain it. The value was stored correctly and reported correctly; only
+ * the cascade disagreed.
+ *
+ * The canvas never showed the bug, which is why it survived: the besigner
+ * renders through `createDevicePinnedTheme`, which flattens every variant's
+ * media keys at the artboard width before the leaf mounts. So the ramp was
+ * already gone there and the author's value won — the editor and the
+ * published page genuinely disagreed.
+ *
+ * The fix is one line of cascade position, not a new precedence rule: a
+ * scalar `fontSize` is re-expressed as `{ xs: value }`. `xs` is `min-width:0`
+ * and therefore always matches, so the RESOLVED value is unchanged for every
+ * viewport; it simply moves the declaration out of the base block and into an
+ * at-rule that Emotion emits after the variant's, restoring "the author's
+ * explicit choice wins". A `fontSize` the author already scoped per
+ * breakpoint is left exactly as written — those breakpoints are a deliberate
+ * ramp of their own and already sort after the variant.
+ *
+ * Scoped to the sx object's TOP level — the element's own styles, which are
+ * the only ones competing with the element's own variant. A `fontSize` nested
+ * under a descendant selector (`'& .price': { fontSize: 12 }`) is left alone:
+ * it is not in that contest, and rewriting it would grow the stylesheet for
+ * nothing.
+ */
+/**
+ * Typography properties `responsiveFontSizes` ramps, and therefore the ones
+ * whose author value can lose to a variant at-rule.
+ *
+ * `fontSize` alone: MUI's ramp only rewrites `fontSize`, and only aligns
+ * `lineHeight` when `disableAlign` is off AND the variant's line height is a
+ * unitless number — the console theme's ramped variants (h1–h3) all carry
+ * unitless line heights, and the emitted CSS carries no `line-height` inside
+ * the ramp's media queries. Adding properties here that the theme does not
+ * ramp would emit at-rules that change nothing.
+ */
+export declare const RAMPED_TYPOGRAPHY_PROPERTIES: readonly ["fontSize"];
+/**
+ * Pins scalar ramped-typography values into the `xs` slice so they sort
+ * after the theme's variant ramp. Identity-preserving: an sx carrying no
+ * scalar `fontSize` comes back as the very same object, so the hot render
+ * path allocates nothing in the overwhelmingly common case.
+ */
+export declare function pinRampedTypographySx<T>(sx: T): T;
+export default pinRampedTypographySx;