@aglyn/aglyn 1.0.0-beta.143

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

@@ -0,0 +1,247 @@
+/**
+ * @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 request-geo reader (AGL-1492/1498).
+ *
+ * Extracted from the console's sanctions module so the tenant's consent-mode
+ * endpoint reads the identical signal the sanctions gate does — two geo
+ * layers would eventually disagree about the same request. The sanctions
+ * POLICY (embargo sets, verdicts, the 451) stays in
+ * `apps/console/constants/sanctions-geo.ts`; this is only the signal.
+ */ /**
+ * The headers carrying the request's country, subdivision and city, named by
+ * configuration with Vercel's own as the default (AGL-2436).
+ *
+ * These were bare `x-vercel-*` literals, under a comment calling them "the
+ * only geo signal this deployment has" — true of Aglyn's cloud and false of
+ * every self-host install, where no edge sets them. Nothing else supplies the
+ * signal, so on a container `readRequestGeo` returned `null` for every request
+ * and the two things built on it were off in production:
+ *
+ *  - the sanctions gate FAILED OPEN on every request, logging it once per
+ *    instance — an embargo control that is silently not running,
+ *  - the tenant's consent-region endpoint had no region to answer with,
+ *  - the new-device sign-in alert reported "Unknown location" to every user,
+ *    and stored that string, so the breach-notification report that reads a
+ *    data subject's country back off it counted nobody.
+ *
+ * An operator's proxy has the signal under its own name: Cloudflare sends
+ * `cf-ipcountry`, and Caddy/nginx/Traefik can set whatever they are told to.
+ * Naming the header is all that was missing.
+ *
+ * ⚠️ Read with DOT notation and mapped through the `env` block of both
+ * `next.config.js` files, because `apps/console/middleware.ts` imports the
+ * sanctions gate and therefore this module into the EDGE bundle. Next inlines
+ * `process.env.NAME` there at build time and never the bracket form (AGL-2037)
+ * — so these are fixed when the image is built, not when it starts, exactly
+ * like `AGLYN_TENANT_HOST_CNAME`.
+ *
+ * Lower-cased because the value is used as a `Vary` header, where it is echoed
+ * verbatim rather than matched case-insensitively.
+ */ export const GEO_COUNTRY_HEADER = (process.env.AGLYN_GEO_COUNTRY_HEADER || 'x-vercel-ip-country').toLowerCase();
+export const GEO_REGION_HEADER = (process.env.AGLYN_GEO_REGION_HEADER || 'x-vercel-ip-country-region').toLowerCase();
+export const GEO_CITY_HEADER = (process.env.AGLYN_GEO_CITY_HEADER || 'x-vercel-ip-city').toLowerCase();
+/**
+ * Normalize a subdivision code to the bare, zero-padded ISO 3166-2 form.
+ *
+ * Providers disagree on `UA-43` vs `43`, and on `9` vs `09` for Luhansk. All
+ * three spellings have to land on the same set member or a sub-country
+ * control silently answers "allowed" for a region it was written to catch.
+ */ function normalizeRegion(raw) {
+    const upper = raw.trim().toUpperCase();
+    const bare = upper.includes('-') ? upper.slice(upper.indexOf('-') + 1) : upper;
+    return /^\d$/.test(bare) ? `0${bare}` : bare;
+}
+/** Reads the edge geo signal off a request's headers. */ /**
+ * The country headers tried after the configured one, in order.
+ *
+ * `GEO_COUNTRY_HEADER` is a single name fixed at BUILD time (see its comment —
+ * Next inlines `process.env.NAME` into the edge bundle), so an operator who
+ * did not set it before building has no way to supply the signal afterwards,
+ * and a deployment that later moves behind a different proxy silently loses
+ * it. Every consumer then reads "no country", which is the strictest consent
+ * posture and a sanctions gate that fails open.
+ *
+ * These are the names the common edges actually send. They are tried only
+ * AFTER the configured header, so an explicit configuration always wins and
+ * nothing here can override a deliberate choice.
+ *
+ * ⛔ Header-only, and deliberately so: no IP-geolocation lookup. Sending a
+ * visitor's address to a third party to decide what to ask them about privacy
+ * would be its own disclosure, and a subprocessor.
+ */ const FALLBACK_COUNTRY_HEADERS = [
+    // Cloudflare.
+    'cf-ipcountry',
+    // Google Cloud: App Engine, and Cloud Run behind a load balancer.
+    'x-appengine-country',
+    'x-client-geo-country',
+    // AWS CloudFront.
+    'cloudfront-viewer-country',
+    // Fastly.
+    'fastly-geo-country',
+    // What a hand-rolled nginx/Caddy/Traefik rule is most often called.
+    'x-geo-country',
+    'x-country-code',
+    'x-country'
+];
+/**
+ * `XX` is Cloudflare's answer for "unknown", and `T1` for a Tor exit node —
+ * neither is a country, and treating them as one would place the visitor in a
+ * region nobody is in. `ZZ` appears from some proxies for the same purpose.
+ */ const NON_COUNTRIES = [
+    'XX',
+    'T1',
+    'ZZ'
+];
+/**
+ * Every header consulted for the country, in order, configured one first.
+ *
+ * Exported because a caller that varies a cached response on the country has
+ * to name ALL of them: a `Vary` that lists only the configured header is
+ * correct on the one platform whose header that is, and on every other one it
+ * lets a CDN serve a US answer to a European visitor from cache. Aglyn is
+ * self-hostable on Docker with the operator's own Firebase and no particular
+ * edge, so "the one platform" is not an assumption this may make.
+ */ export const GEO_COUNTRY_HEADERS = [
+    GEO_COUNTRY_HEADER,
+    ...FALLBACK_COUNTRY_HEADERS
+].filter((name, index, all)=>all.indexOf(name) === index);
+const readCountry = (headers)=>{
+    for (const name of GEO_COUNTRY_HEADERS){
+        var _headers_get;
+        const value = ((_headers_get = headers.get(name)) != null ? _headers_get : '').trim().toUpperCase();
+        // Two letters exactly: a proxy that passes through a city name, a list or
+        // an IP under one of these names must not become a "country".
+        if (!/^[A-Z]{2}$/.test(value)) continue;
+        if (NON_COUNTRIES.indexOf(value) >= 0) continue;
+        return value;
+    }
+    return null;
+};
+/**
+ * The subdivision headers tried after the configured one, in order.
+ *
+ * The sub-country half of the embargo check — Crimea, Donetsk, Luhansk,
+ * Sevastopol — matches on this and on nothing else, so an operator who named
+ * a country header but no region header had the country gate running and the
+ * REGION gate quietly inert: a Donetsk request reads `UA`, which is not
+ * embargoed, and passes. Cloudflare sends no subdivision at all, so a
+ * deployment behind it has no sub-country signal by any name; the rest do.
+ */ const FALLBACK_REGION_HEADERS = [
+    'x-appengine-region',
+    'x-client-geo-region',
+    'cloudfront-viewer-country-region',
+    'x-geo-region',
+    'x-region-code'
+];
+/** Every header consulted for the subdivision, in order, configured one first. */ export const GEO_REGION_HEADERS = [
+    GEO_REGION_HEADER,
+    ...FALLBACK_REGION_HEADERS
+].filter((name, index, all)=>all.indexOf(name) === index);
+const rawRegion = (headers)=>{
+    for (const name of GEO_REGION_HEADERS){
+        var _headers_get;
+        const value = ((_headers_get = headers.get(name)) != null ? _headers_get : '').trim();
+        if (value) return value;
+    }
+    return '';
+};
+export function readRequestGeo(headers) {
+    const region = rawRegion(headers);
+    return {
+        country: readCountry(headers),
+        region: region ? normalizeRegion(region) : null
+    };
+}
+/**
+ * The subdivision as a person should read it, rather than as an embargo set
+ * matches it.
+ *
+ * `readRequestGeo().region` is upper-cased and zero-padded because
+ * `EMBARGOED_UA_REGIONS` is an exact-membership test that every spelling of a
+ * code has to land on. That normalization is wrong for anything a person
+ * reads: a proxy configured to send a subdivision NAME rather than a code
+ * reaches a user's security email shouting `CAPITAL`.
+ *
+ * Same headers, same precedence — only the normalization differs, so the two
+ * readers can never disagree about WHICH subdivision a request came from.
+ */ export function readRequestRegionLabel(headers) {
+    const raw = rawRegion(headers);
+    if (!raw) return null;
+    const bare = raw.includes('-') ? raw.slice(raw.indexOf('-') + 1) : raw;
+    // Commas are the delimiter callers join these parts on; see `readRequestCity`.
+    const label = bare.replace(/,/g, ' ').replace(/\s+/g, ' ').trim();
+    return label || null;
+}
+/**
+ * The city names the common edges send, tried after the configured one.
+ *
+ * Same ordering rule as the country list: the configured header wins, and
+ * these only fill in for an operator who never named one. Cloudflare's
+ * `cf-ipcity` arrives only on plans where the visitor-location transform is
+ * available, so its absence is normal rather than a misconfiguration.
+ */ const FALLBACK_CITY_HEADERS = [
+    'cf-ipcity',
+    'x-appengine-city',
+    'x-client-geo-city',
+    'cloudfront-viewer-city',
+    'x-geo-city',
+    'x-city'
+];
+/** Every header consulted for the city, in order, configured one first. */ export const GEO_CITY_HEADERS = [
+    GEO_CITY_HEADER,
+    ...FALLBACK_CITY_HEADERS
+].filter((name, index, all)=>all.indexOf(name) === index);
+/**
+ * The longest city name treated as a city.
+ *
+ * A proxy that passes something else through one of these names — a header
+ * list, a user agent, a path — would otherwise be rendered to a person as
+ * their sign-in location. 64 characters clears the longest real place names
+ * with room to spare.
+ */ const MAX_CITY_LENGTH = 64;
+/**
+ * The request's city, decoded, or `null` when no edge sent one.
+ *
+ * Percent-decoded because every edge that sends this header sends non-ASCII
+ * names encoded (`S%C3%A3o%20Paulo`), and an undecoded value reaches a person
+ * as mojibake in a security email. A value that is not valid percent-encoding
+ * is kept verbatim rather than dropped — a literal `%` in a name is not a
+ * reason to lose the city.
+ *
+ * Commas become spaces. Callers join city, region and country with `", "`
+ * into one stored string, and `deviceLocationCountry` reads the country back
+ * off the LAST comma-separated token; a comma arriving inside the city half
+ * would add a token to a string that a breach-notification report parses.
+ */ export function readRequestCity(headers) {
+    for (const name of GEO_CITY_HEADERS){
+        var _headers_get;
+        const raw = ((_headers_get = headers.get(name)) != null ? _headers_get : '').trim();
+        if (!raw) continue;
+        let decoded;
+        try {
+            decoded = decodeURIComponent(raw);
+        } catch (unused) {
+            decoded = raw;
+        }
+        const city = decoded.replace(/,/g, ' ').replace(/\s+/g, ' ').trim();
+        if (!city || city.length > MAX_CITY_LENGTH) continue;
+        return city;
+    }
+    return null;
+}
+
+//# sourceMappingURL=request-geo.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/request-geo.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 request-geo reader (AGL-1492/1498).\n *\n * Extracted from the console's sanctions module so the tenant's consent-mode\n * endpoint reads the identical signal the sanctions gate does — two geo\n * layers would eventually disagree about the same request. The sanctions\n * POLICY (embargo sets, verdicts, the 451) stays in\n * `apps/console/constants/sanctions-geo.ts`; this is only the signal.\n */\n\n/**\n * The headers carrying the request's country, subdivision and city, named by\n * configuration with Vercel's own as the default (AGL-2436).\n *\n * These were bare `x-vercel-*` literals, under a comment calling them \"the\n * only geo signal this deployment has\" — true of Aglyn's cloud and false of\n * every self-host install, where no edge sets them. Nothing else supplies the\n * signal, so on a container `readRequestGeo` returned `null` for every request\n * and the two things built on it were off in production:\n *\n *  - the sanctions gate FAILED OPEN on every request, logging it once per\n *    instance — an embargo control that is silently not running,\n *  - the tenant's consent-region endpoint had no region to answer with,\n *  - the new-device sign-in alert reported \"Unknown location\" to every user,\n *    and stored that string, so the breach-notification report that reads a\n *    data subject's country back off it counted nobody.\n *\n * An operator's proxy has the signal under its own name: Cloudflare sends\n * `cf-ipcountry`, and Caddy/nginx/Traefik can set whatever they are told to.\n * Naming the header is all that was missing.\n *\n * ⚠️ Read with DOT notation and mapped through the `env` block of both\n * `next.config.js` files, because `apps/console/middleware.ts` imports the\n * sanctions gate and therefore this module into the EDGE bundle. Next inlines\n * `process.env.NAME` there at build time and never the bracket form (AGL-2037)\n * — so these are fixed when the image is built, not when it starts, exactly\n * like `AGLYN_TENANT_HOST_CNAME`.\n *\n * Lower-cased because the value is used as a `Vary` header, where it is echoed\n * verbatim rather than matched case-insensitively.\n */\nexport const GEO_COUNTRY_HEADER = (\n  process.env.AGLYN_GEO_COUNTRY_HEADER || 'x-vercel-ip-country'\n).toLowerCase()\nexport const GEO_REGION_HEADER = (\n  process.env.AGLYN_GEO_REGION_HEADER || 'x-vercel-ip-country-region'\n).toLowerCase()\nexport const GEO_CITY_HEADER = (\n  process.env.AGLYN_GEO_CITY_HEADER || 'x-vercel-ip-city'\n).toLowerCase()\n\nexport interface RequestGeo {\n  /** ISO 3166-1 alpha-2, uppercased. `null` when the edge sent no signal. */\n  country: string | null\n  /** Bare ISO 3166-2 subdivision code, uppercased. `null` when absent. */\n  region: string | null\n}\n\n/** A minimal `Headers`, so route handlers and middleware share one reader. */\nexport interface HeaderReader {\n  get(name: string): string | null\n}\n\n/**\n * Normalize a subdivision code to the bare, zero-padded ISO 3166-2 form.\n *\n * Providers disagree on `UA-43` vs `43`, and on `9` vs `09` for Luhansk. All\n * three spellings have to land on the same set member or a sub-country\n * control silently answers \"allowed\" for a region it was written to catch.\n */\nfunction normalizeRegion(raw: string): string {\n  const upper = raw.trim().toUpperCase()\n  const bare = upper.includes('-') ? upper.slice(upper.indexOf('-') + 1) : upper\n  return /^\\d$/.test(bare) ? `0${bare}` : bare\n}\n\n/** Reads the edge geo signal off a request's headers. */\n/**\n * The country headers tried after the configured one, in order.\n *\n * `GEO_COUNTRY_HEADER` is a single name fixed at BUILD time (see its comment —\n * Next inlines `process.env.NAME` into the edge bundle), so an operator who\n * did not set it before building has no way to supply the signal afterwards,\n * and a deployment that later moves behind a different proxy silently loses\n * it. Every consumer then reads \"no country\", which is the strictest consent\n * posture and a sanctions gate that fails open.\n *\n * These are the names the common edges actually send. They are tried only\n * AFTER the configured header, so an explicit configuration always wins and\n * nothing here can override a deliberate choice.\n *\n * ⛔ Header-only, and deliberately so: no IP-geolocation lookup. Sending a\n * visitor's address to a third party to decide what to ask them about privacy\n * would be its own disclosure, and a subprocessor.\n */\nconst FALLBACK_COUNTRY_HEADERS = [\n  // Cloudflare.\n  'cf-ipcountry',\n  // Google Cloud: App Engine, and Cloud Run behind a load balancer.\n  'x-appengine-country',\n  'x-client-geo-country',\n  // AWS CloudFront.\n  'cloudfront-viewer-country',\n  // Fastly.\n  'fastly-geo-country',\n  // What a hand-rolled nginx/Caddy/Traefik rule is most often called.\n  'x-geo-country',\n  'x-country-code',\n  'x-country',\n] as const\n\n/**\n * `XX` is Cloudflare's answer for \"unknown\", and `T1` for a Tor exit node —\n * neither is a country, and treating them as one would place the visitor in a\n * region nobody is in. `ZZ` appears from some proxies for the same purpose.\n */\nconst NON_COUNTRIES = ['XX', 'T1', 'ZZ']\n\n/**\n * Every header consulted for the country, in order, configured one first.\n *\n * Exported because a caller that varies a cached response on the country has\n * to name ALL of them: a `Vary` that lists only the configured header is\n * correct on the one platform whose header that is, and on every other one it\n * lets a CDN serve a US answer to a European visitor from cache. Aglyn is\n * self-hostable on Docker with the operator's own Firebase and no particular\n * edge, so \"the one platform\" is not an assumption this may make.\n */\nexport const GEO_COUNTRY_HEADERS: readonly string[] = [\n  GEO_COUNTRY_HEADER,\n  ...FALLBACK_COUNTRY_HEADERS,\n].filter((name, index, all) => all.indexOf(name) === index)\n\nconst readCountry = (headers: HeaderReader): string | null => {\n  for (const name of GEO_COUNTRY_HEADERS) {\n    const value = (headers.get(name) ?? '').trim().toUpperCase()\n    // Two letters exactly: a proxy that passes through a city name, a list or\n    // an IP under one of these names must not become a \"country\".\n    if (!/^[A-Z]{2}$/.test(value)) continue\n    if (NON_COUNTRIES.indexOf(value) >= 0) continue\n    return value\n  }\n  return null\n}\n\n/**\n * The subdivision headers tried after the configured one, in order.\n *\n * The sub-country half of the embargo check — Crimea, Donetsk, Luhansk,\n * Sevastopol — matches on this and on nothing else, so an operator who named\n * a country header but no region header had the country gate running and the\n * REGION gate quietly inert: a Donetsk request reads `UA`, which is not\n * embargoed, and passes. Cloudflare sends no subdivision at all, so a\n * deployment behind it has no sub-country signal by any name; the rest do.\n */\nconst FALLBACK_REGION_HEADERS = [\n  'x-appengine-region',\n  'x-client-geo-region',\n  'cloudfront-viewer-country-region',\n  'x-geo-region',\n  'x-region-code',\n] as const\n\n/** Every header consulted for the subdivision, in order, configured one first. */\nexport const GEO_REGION_HEADERS: readonly string[] = [\n  GEO_REGION_HEADER,\n  ...FALLBACK_REGION_HEADERS,\n].filter((name, index, all) => all.indexOf(name) === index)\n\nconst rawRegion = (headers: HeaderReader): string => {\n  for (const name of GEO_REGION_HEADERS) {\n    const value = (headers.get(name) ?? '').trim()\n    if (value) return value\n  }\n  return ''\n}\n\nexport function readRequestGeo(headers: HeaderReader): RequestGeo {\n  const region = rawRegion(headers)\n  return {\n    country: readCountry(headers),\n    region: region ? normalizeRegion(region) : null,\n  }\n}\n\n/**\n * The subdivision as a person should read it, rather than as an embargo set\n * matches it.\n *\n * `readRequestGeo().region` is upper-cased and zero-padded because\n * `EMBARGOED_UA_REGIONS` is an exact-membership test that every spelling of a\n * code has to land on. That normalization is wrong for anything a person\n * reads: a proxy configured to send a subdivision NAME rather than a code\n * reaches a user's security email shouting `CAPITAL`.\n *\n * Same headers, same precedence — only the normalization differs, so the two\n * readers can never disagree about WHICH subdivision a request came from.\n */\nexport function readRequestRegionLabel(headers: HeaderReader): string | null {\n  const raw = rawRegion(headers)\n  if (!raw) return null\n  const bare = raw.includes('-') ? raw.slice(raw.indexOf('-') + 1) : raw\n  // Commas are the delimiter callers join these parts on; see `readRequestCity`.\n  const label = bare.replace(/,/g, ' ').replace(/\\s+/g, ' ').trim()\n  return label || null\n}\n\n/**\n * The city names the common edges send, tried after the configured one.\n *\n * Same ordering rule as the country list: the configured header wins, and\n * these only fill in for an operator who never named one. Cloudflare's\n * `cf-ipcity` arrives only on plans where the visitor-location transform is\n * available, so its absence is normal rather than a misconfiguration.\n */\nconst FALLBACK_CITY_HEADERS = [\n  'cf-ipcity',\n  'x-appengine-city',\n  'x-client-geo-city',\n  'cloudfront-viewer-city',\n  'x-geo-city',\n  'x-city',\n] as const\n\n/** Every header consulted for the city, in order, configured one first. */\nexport const GEO_CITY_HEADERS: readonly string[] = [\n  GEO_CITY_HEADER,\n  ...FALLBACK_CITY_HEADERS,\n].filter((name, index, all) => all.indexOf(name) === index)\n\n/**\n * The longest city name treated as a city.\n *\n * A proxy that passes something else through one of these names — a header\n * list, a user agent, a path — would otherwise be rendered to a person as\n * their sign-in location. 64 characters clears the longest real place names\n * with room to spare.\n */\nconst MAX_CITY_LENGTH = 64\n\n/**\n * The request's city, decoded, or `null` when no edge sent one.\n *\n * Percent-decoded because every edge that sends this header sends non-ASCII\n * names encoded (`S%C3%A3o%20Paulo`), and an undecoded value reaches a person\n * as mojibake in a security email. A value that is not valid percent-encoding\n * is kept verbatim rather than dropped — a literal `%` in a name is not a\n * reason to lose the city.\n *\n * Commas become spaces. Callers join city, region and country with `\", \"`\n * into one stored string, and `deviceLocationCountry` reads the country back\n * off the LAST comma-separated token; a comma arriving inside the city half\n * would add a token to a string that a breach-notification report parses.\n */\nexport function readRequestCity(headers: HeaderReader): string | null {\n  for (const name of GEO_CITY_HEADERS) {\n    const raw = (headers.get(name) ?? '').trim()\n    if (!raw) continue\n    let decoded: string\n    try {\n      decoded = decodeURIComponent(raw)\n    } catch {\n      decoded = raw\n    }\n    const city = decoded.replace(/,/g, ' ').replace(/\\s+/g, ' ').trim()\n    if (!city || city.length > MAX_CITY_LENGTH) continue\n    return city\n  }\n  return null\n}\n"],"names":["GEO_COUNTRY_HEADER","process","env","AGLYN_GEO_COUNTRY_HEADER","toLowerCase","GEO_REGION_HEADER","AGLYN_GEO_REGION_HEADER","GEO_CITY_HEADER","AGLYN_GEO_CITY_HEADER","normalizeRegion","raw","upper","trim","toUpperCase","bare","includes","slice","indexOf","test","FALLBACK_COUNTRY_HEADERS","NON_COUNTRIES","GEO_COUNTRY_HEADERS","filter","name","index","all","readCountry","headers","value","get","FALLBACK_REGION_HEADERS","GEO_REGION_HEADERS","rawRegion","readRequestGeo","region","country","readRequestRegionLabel","label","replace","FALLBACK_CITY_HEADERS","GEO_CITY_HEADERS","MAX_CITY_LENGTH","readRequestCity","decoded","decodeURIComponent","city","length"],"mappings":"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"}

package/src/lib/app-utils/request-ip.d.ts

@@ -0,0 +1,213 @@
+/**
+ * @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.
+ */
+import type { HeaderReader } from './request-geo';
+/** The environment variable naming how many proxies sit in front of the app. */
+export declare 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 declare const DEFAULT_TRUSTED_PROXY_COUNT = 1;
+/**
+ * `null` means "a platform edge normalizes the header, trust what it presents".
+ * A number is a literal count of proxies in front, and `0` means none — a
+ * process reachable directly from the internet, where every forwarding header
+ * is caller-supplied text and only the transport peer is a fact.
+ */
+export type TrustedProxyDepth = number | null;
+/**
+ * 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 declare const NO_CLIENT_ADDRESS_BUCKET = "no-address";
+/** Node-style header records alongside a `Headers`-shaped reader. */
+export type ClientIpHeaders = HeaderReader | Record<string, string | string[] | undefined>;
+export interface ClientIpOptions {
+    /**
+     * Overrides the configured depth. Tests pass this; production code should
+     * not, so an operator's configuration is the only thing that decides.
+     */
+    trustedProxyCount?: TrustedProxyDepth;
+    /**
+     * The transport peer — `req.socket.remoteAddress` on a node-style handler.
+     * Consulted last, and only because it is the one address the process knows
+     * first-hand. Behind a proxy that sets no forwarding header at all it is the
+     * proxy's own address, which is a single shared bucket rather than a
+     * visitor; that is a misconfiguration the self-hosting docs name, not a
+     * reading this module can improve on.
+     */
+    remoteAddress?: string | null;
+    /** Injectable for tests; defaults to `process.env`. */
+    env?: Record<string, string | undefined>;
+}
+/**
+ * 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 declare function resolveTrustedProxyCount(env?: Record<string, string | undefined>): TrustedProxyDepth;
+/**
+ * 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 declare function normalizeClientIp(raw: string | null | undefined): string | null;
+/**
+ * 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 declare function readClientIp(headers: ClientIpHeaders, options?: ClientIpOptions): string | null;