@promptbook/cli 0.112.0-96 → 0.112.0-97

package/apps/agents-server/src/utils/serverRegistry.ts

@@ -1,7 +1,7 @@
 import { createClient, type SupabaseClient } from '@supabase/supabase-js';
 import { spaceTrim } from 'spacetrim';
 import { DatabaseError } from '../../../../src/errors/DatabaseError';
-import { isAgentsServerSqliteMode } from '../database/agentsServerDatabaseMode';
+import { isAgentsServerStandaloneMode } from '../database/agentsServerDatabaseMode';
 
 /**
  * Supported `_Server.environment` values.
@@ -139,7 +139,7 @@ export async function listRegisteredServersUsingServiceRole(options?: {
 }): Promise<Array<ServerRecord>> {
     const environmentServers = listEnvironmentRegisteredServers();
 
-    if (isAgentsServerSqliteMode()) {
+    if (isAgentsServerStandaloneMode()) {
         return environmentServers;
     }
 
@@ -171,13 +171,14 @@ export async function listRegisteredServersUsingServiceRole(options?: {
 /**
  * Loads virtual server records from the comma-separated `SERVERS` environment variable.
  *
- * @returns Server records with deterministic table prefixes derived from normalized domains.
+ * @returns Server records with deterministic table prefixes from the configured server prefix or normalized domains.
  */
 export function listEnvironmentRegisteredServers(): Array<ServerRecord> {
     const rawServers = process.env[SERVERS_ENV_NAME];
     if (!rawServers) {
         return [];
     }
+    const configuredTablePrefix = process.env.SUPABASE_TABLE_PREFIX?.trim() || '';
 
     const normalizedDomains = uniqueStrings(
         rawServers
@@ -191,7 +192,7 @@ export function listEnvironmentRegisteredServers(): Array<ServerRecord> {
         name: domain,
         environment: SERVER_ENVIRONMENT.PRODUCTION,
         domain,
-        tablePrefix: buildEnvironmentServerTablePrefix(domain),
+        tablePrefix: configuredTablePrefix || buildEnvironmentServerTablePrefix(domain),
         createdAt: ENVIRONMENT_SERVER_TIMESTAMP,
         updatedAt: ENVIRONMENT_SERVER_TIMESTAMP,
     }));
@@ -349,10 +350,10 @@ export function isServerEnvironment(value: string): value is ServerEnvironment {
  * @returns Shared untyped Supabase client.
  */
 export function getServerRegistryClient(): SupabaseClient {
-    if (isAgentsServerSqliteMode()) {
+    if (isAgentsServerStandaloneMode()) {
         throw new DatabaseError(
             spaceTrim(`
-                Cannot create a Supabase server-registry client while Agents Server is using SQLite.
+                Cannot create a Supabase server-registry client while Agents Server is using a standalone database backend.
             `),
         );
     }

package/apps/agents-server/src/utils/session.ts

@@ -1,6 +1,8 @@
 import { createHmac } from 'crypto';
 import { cookies, headers } from 'next/headers';
 import { cache } from 'react';
+import { isStandaloneVpsRawIpBootstrapActive } from './standaloneVpsRawIpBootstrap';
+import { writeShibbolethAuthenticationLog } from './shibboleth/writeShibbolethAuthenticationLog';
 
 /**
  * Cookie name used to store the signed user session.
@@ -50,6 +52,10 @@ export type SessionCookieSecurityContext = {
      * Raw forwarded protocol header emitted by the reverse proxy.
      */
     readonly forwardedProto: string | null;
+    /**
+     * Canonical public site URL from `NEXT_PUBLIC_SITE_URL`.
+     */
+    readonly nextPublicSiteUrl: string | null | undefined;
     /**
      * Comma-separated configured domain list from `SERVERS`.
      */
@@ -121,7 +127,13 @@ export function shouldUseSecureSessionCookieForRequest(context: SessionCookieSec
         return false;
     }
 
-    if (parseConfiguredServers(context.configuredServers).length > 0) {
+    if (
+        parseConfiguredServers(context.configuredServers).length > 0 &&
+        !isStandaloneVpsRawIpBootstrapActive({
+            nextPublicSiteUrl: context.nextPublicSiteUrl,
+            publicIpAddress: context.publicIpAddress,
+        })
+    ) {
         return true;
     }
 
@@ -150,9 +162,17 @@ export function shouldUseSecureSessionCookieForRequest(context: SessionCookieSec
  */
 export async function setSession(user: SessionUser) {
     const token = serializeSessionToken(user);
-    const secure = await shouldUseSecureSessionCookie();
+    const headerStore = await headers();
+    const cookieStore = await cookies();
+    const secure = shouldUseSecureSessionCookieForHeaders(headerStore);
 
-    (await cookies()).set(SESSION_COOKIE_NAME, token, {
+    writeShibbolethAuthenticationLog(headerStore, {
+        event: 'session-set',
+        hasSessionCookie: cookieStore.has(SESSION_COOKIE_NAME),
+        isSecureSessionCookie: secure,
+    });
+
+    cookieStore.set(SESSION_COOKIE_NAME, token, {
         httpOnly: true,
         secure,
         path: '/',
@@ -164,9 +184,17 @@ export async function setSession(user: SessionUser) {
  * Clears the current authenticated session cookie.
  */
 export async function clearSession() {
-    (await cookies()).delete(SESSION_COOKIE_NAME);
+    const headerStore = await headers();
+    const cookieStore = await cookies();
+
+    writeShibbolethAuthenticationLog(headerStore, {
+        event: 'session-cleared',
+        hasSessionCookie: cookieStore.has(SESSION_COOKIE_NAME),
+    });
+
+    cookieStore.delete(SESSION_COOKIE_NAME);
     // Also clear legacy adminToken
-    (await cookies()).delete('adminToken');
+    cookieStore.delete('adminToken');
 }
 
 /**
@@ -189,18 +217,18 @@ export async function getSession(): Promise<SessionUser | null> {
 }
 
 /**
- * Resolves the runtime cookie security decision from the current request headers.
+ * Resolves the runtime cookie security decision from one request header snapshot.
  *
+ * @param headerStore - Request headers from the active request.
  * @returns `true` when the session cookie should keep the `Secure` flag.
  */
-async function shouldUseSecureSessionCookie(): Promise<boolean> {
-    const headerStore = await headers();
-
+function shouldUseSecureSessionCookieForHeaders(headerStore: Pick<Headers, 'get'>): boolean {
     return shouldUseSecureSessionCookieForRequest({
         isProduction: process.env.NODE_ENV === 'production',
         host: headerStore.get('host'),
         forwardedHost: headerStore.get('x-forwarded-host'),
         forwardedProto: headerStore.get('x-forwarded-proto'),
+        nextPublicSiteUrl: process.env.NEXT_PUBLIC_SITE_URL,
         configuredServers: process.env.SERVERS,
         publicIpAddress: process.env.PTBK_PUBLIC_IP_ADDRESS,
     });

package/apps/agents-server/src/utils/shibboleth/createShibbolethAuthenticationLogPayload.ts

@@ -0,0 +1,173 @@
+/**
+ * Minimal read-only header accessor shared by middleware, route handlers, and server utilities.
+ *
+ * @private Internal helper of the Shibboleth authentication diagnostics.
+ */
+export type ReadonlyHeadersLike = Pick<Headers, 'get'>;
+
+/**
+ * One resolved Shibboleth-related attribute included in the diagnostic payload.
+ *
+ * @private Internal helper of the Shibboleth authentication diagnostics.
+ */
+export type ShibbolethAuthenticationLogAttribute = {
+    readonly fieldName: string;
+    readonly headerName: string;
+    readonly fingerprint: string;
+    readonly valueLength: number;
+};
+
+/**
+ * Structured, privacy-preserving diagnostic payload for one Shibboleth-related request event.
+ *
+ * @private Internal helper of the Agents Server authentication diagnostics.
+ */
+export type ShibbolethAuthenticationLogPayload = {
+    readonly event: string;
+    readonly pathname?: string;
+    readonly method?: string;
+    readonly hasSessionCookie?: boolean;
+    readonly isSecureSessionCookie?: boolean;
+    readonly headerNames: ReadonlyArray<string>;
+    readonly attributeFields: ReadonlyArray<string>;
+    readonly attributes: ReadonlyArray<ShibbolethAuthenticationLogAttribute>;
+};
+
+/**
+ * Context describing where the Shibboleth diagnostic event happened.
+ *
+ * @private Internal helper of the Shibboleth authentication diagnostics.
+ */
+export type CreateShibbolethAuthenticationLogPayloadOptions = {
+    readonly event: string;
+    readonly pathname?: string;
+    readonly method?: string;
+    readonly hasSessionCookie?: boolean;
+    readonly isSecureSessionCookie?: boolean;
+};
+
+type ShibbolethHeaderDefinition = {
+    readonly fieldName: string;
+    readonly headerNames: ReadonlyArray<string>;
+};
+
+const SHIBBOLETH_HEADER_DEFINITIONS: ReadonlyArray<ShibbolethHeaderDefinition> = [
+    { fieldName: 'sessionId', headerNames: ['shib-session-id', 'x-shib-session-id'] },
+    { fieldName: 'sessionIndex', headerNames: ['shib-session-index', 'x-shib-session-index'] },
+    { fieldName: 'sessionExpires', headerNames: ['shib-session-expires', 'x-shib-session-expires'] },
+    { fieldName: 'applicationId', headerNames: ['shib-application-id', 'x-shib-application-id'] },
+    { fieldName: 'remoteUser', headerNames: ['remote-user', 'x-remote-user'] },
+    { fieldName: 'displayName', headerNames: ['displayname', 'x-displayname'] },
+    { fieldName: 'mail', headerNames: ['mail', 'x-mail'] },
+    { fieldName: 'unstructuredName', headerNames: ['unstructuredname', 'x-unstructuredname'] },
+    {
+        fieldName: 'eduPersonPrincipalName',
+        headerNames: ['edupersonprincipalname', 'eppn', 'x-edupersonprincipalname', 'x-eppn'],
+    },
+    { fieldName: 'persistentId', headerNames: ['persistent-id', 'x-persistent-id'] },
+    { fieldName: 'nameId', headerNames: ['name-id', 'x-name-id'] },
+];
+
+/**
+ * Builds a privacy-preserving Shibboleth diagnostic payload from incoming request headers.
+ *
+ * Only the presence of relevant headers plus short fingerprints of their values are logged,
+ * never the raw personally identifiable header contents.
+ *
+ * @param headers - Request headers or another read-only header accessor.
+ * @param options - Event metadata describing where the diagnostic event originated.
+ * @returns Structured log payload, or `null` when the request does not look Shibboleth-related.
+ *
+ * @private Internal helper of the Agents Server authentication diagnostics.
+ */
+export function createShibbolethAuthenticationLogPayload(
+    headers: ReadonlyHeadersLike,
+    options: CreateShibbolethAuthenticationLogPayloadOptions,
+): ShibbolethAuthenticationLogPayload | null {
+    const attributes = SHIBBOLETH_HEADER_DEFINITIONS.map((definition) => resolveShibbolethHeader(headers, definition)).filter(
+        (attribute): attribute is ShibbolethAuthenticationLogAttribute => attribute !== null,
+    );
+
+    if (attributes.length === 0) {
+        return null;
+    }
+
+    return {
+        event: options.event,
+        pathname: options.pathname,
+        method: options.method,
+        hasSessionCookie: options.hasSessionCookie,
+        isSecureSessionCookie: options.isSecureSessionCookie,
+        headerNames: attributes.map(({ headerName }) => headerName),
+        attributeFields: attributes.map(({ fieldName }) => fieldName),
+        attributes,
+    };
+}
+
+/**
+ * Resolves one Shibboleth attribute from any of its expected header aliases.
+ *
+ * @param headers - Request header accessor.
+ * @param definition - Logical Shibboleth field with supported header aliases.
+ * @returns Sanitized attribute snapshot or `null` when absent.
+ */
+function resolveShibbolethHeader(
+    headers: ReadonlyHeadersLike,
+    definition: ShibbolethHeaderDefinition,
+): ShibbolethAuthenticationLogAttribute | null {
+    for (const headerName of definition.headerNames) {
+        const rawValue = headers.get(headerName);
+        const value = normalizeHeaderValue(rawValue);
+
+        if (!value) {
+            continue;
+        }
+
+        return {
+            fieldName: definition.fieldName,
+            headerName,
+            fingerprint: createHeaderValueFingerprint(value),
+            valueLength: value.length,
+        };
+    }
+
+    return null;
+}
+
+/**
+ * Normalizes one header value before diagnostic processing.
+ *
+ * @param value - Raw header value.
+ * @returns Trimmed non-empty value or `null`.
+ */
+function normalizeHeaderValue(value: string | null): string | null {
+    const normalizedValue = value?.trim() || '';
+    return normalizedValue === '' ? null : normalizedValue;
+}
+
+/**
+ * Creates a short stable fingerprint so logs can correlate the same identity/session
+ * without storing the raw Shibboleth attribute value.
+ *
+ * @param value - Raw Shibboleth header value.
+ * @returns Short deterministic fingerprint.
+ */
+function createHeaderValueFingerprint(value: string): string {
+    let hashPrimary = 0xdeadbeef ^ value.length;
+    let hashSecondary = 0x41c6ce57 ^ value.length;
+
+    for (const character of value) {
+        const codePoint = character.codePointAt(0) || 0;
+        hashPrimary = Math.imul(hashPrimary ^ codePoint, 2654435761);
+        hashSecondary = Math.imul(hashSecondary ^ codePoint, 1597334677);
+    }
+
+    hashPrimary =
+        Math.imul(hashPrimary ^ (hashPrimary >>> 16), 2246822507) ^ Math.imul(hashSecondary ^ (hashSecondary >>> 13), 3266489909);
+    hashSecondary =
+        Math.imul(hashSecondary ^ (hashSecondary >>> 16), 2246822507) ^
+        Math.imul(hashPrimary ^ (hashPrimary >>> 13), 3266489909);
+
+    const combinedHash = 4294967296 * (2097151 & hashSecondary) + (hashPrimary >>> 0);
+    return combinedHash.toString(16).padStart(14, '0').slice(0, 12);
+}

package/apps/agents-server/src/utils/shibboleth/writeShibbolethAuthenticationLog.ts

@@ -0,0 +1,27 @@
+import {
+    createShibbolethAuthenticationLogPayload,
+    type CreateShibbolethAuthenticationLogPayloadOptions,
+    type ReadonlyHeadersLike,
+} from './createShibbolethAuthenticationLogPayload';
+
+/**
+ * Writes one sanitized Shibboleth diagnostic event to the application logs when
+ * the current request carries Shibboleth-related headers.
+ *
+ * @param headers - Request headers or another read-only header accessor.
+ * @param options - Event metadata describing where the diagnostic event originated.
+ *
+ * @private Internal helper of the Agents Server authentication diagnostics.
+ */
+export function writeShibbolethAuthenticationLog(
+    headers: ReadonlyHeadersLike,
+    options: CreateShibbolethAuthenticationLogPayloadOptions,
+): void {
+    const payload = createShibbolethAuthenticationLogPayload(headers, options);
+
+    if (!payload) {
+        return;
+    }
+
+    console.info(`[auth][shibboleth] ${JSON.stringify(payload)}`);
+}

package/apps/agents-server/src/utils/standaloneVpsDnsDiagnostics.ts

@@ -0,0 +1,258 @@
+import { lookup } from 'dns/promises';
+import type {
+    ManagedServerDnsDiagnostic,
+    ManagedServerDnsExpectedRecord,
+    ManagedServerDnsProviderGuide,
+    ManagedServerDnsStatus,
+} from '../app/admin/servers/ServersRegistryDnsTypes';
+
+/**
+ * Resolver signature used for DNS lookups.
+ */
+type ResolveDnsAddresses = (domain: string) => Promise<ReadonlyArray<string>>;
+
+/**
+ * Input used to create one standalone VPS DNS diagnostic.
+ */
+type CreateStandaloneVpsDomainDnsDiagnosticOptions = {
+    /**
+     * Domain currently configured in the standalone VPS server registry.
+     */
+    readonly domain: string;
+
+    /**
+     * Public IP address detected/stored for the VPS runtime.
+     */
+    readonly publicIpAddress: string | null | undefined;
+
+    /**
+     * Optional already-working hostname that subdomains may target via CNAME.
+     */
+    readonly fallbackCnameTargetDomain?: string | null | undefined;
+
+    /**
+     * Optional resolver override used by unit tests.
+     */
+    readonly resolveDnsAddresses?: ResolveDnsAddresses;
+};
+
+/**
+ * Provider guides shown together with DNS record instructions.
+ */
+const DNS_PROVIDER_GUIDES: ReadonlyArray<ManagedServerDnsProviderGuide> = [
+    {
+        label: 'Cloudflare DNS records',
+        href: 'https://developers.cloudflare.com/dns/manage-dns-records/how-to/create-dns-records/',
+    },
+    {
+        label: 'GoDaddy DNS records',
+        href: 'https://www.godaddy.com/help/manage-dns-records-680',
+    },
+    {
+        label: 'Namecheap DNS records',
+        href: 'https://www.namecheap.com/support/knowledgebase/article.aspx/319/2237/how-can-i-set-up-an-a-address-record-for-my-domain/',
+    },
+    {
+        label: 'Squarespace DNS records',
+        href: 'https://support.squarespace.com/hc/en-us/articles/360002101888-Adding-custom-DNS-records-to-your-Squarespace-managed-domain',
+    },
+];
+
+/**
+ * DNS error codes treated as "not resolving yet" during propagation.
+ */
+const DNS_PENDING_ERROR_CODES = new Set(['ENOTFOUND', 'ENODATA', 'EAI_AGAIN', 'ESERVFAIL']);
+
+/**
+ * Creates the browser-safe DNS status for one standalone VPS domain.
+ *
+ * @param options - Domain, VPS IP, and optional resolver override.
+ * @returns DNS diagnostic rendered on `/admin/servers`.
+ */
+export async function createStandaloneVpsDomainDnsDiagnostic(
+    options: CreateStandaloneVpsDomainDnsDiagnosticOptions,
+): Promise<ManagedServerDnsDiagnostic> {
+    const publicIpAddress = normalizePublicIpAddress(options.publicIpAddress);
+    const expectedRecords = createExpectedDnsRecords({
+        domain: options.domain,
+        publicIpAddress,
+        fallbackCnameTargetDomain: options.fallbackCnameTargetDomain,
+    });
+
+    if (!publicIpAddress) {
+        return createDnsDiagnostic({
+            expectedRecords,
+            publicIpAddress: null,
+            resolvedAddresses: [],
+            status: 'unavailable',
+            summary: 'The VPS public IP address is not available yet, so DNS cannot be verified automatically.',
+        });
+    }
+
+    try {
+        const resolvedAddresses = uniqueStrings(
+            await (options.resolveDnsAddresses || resolveDnsAddresses)(options.domain),
+        );
+
+        if (resolvedAddresses.includes(publicIpAddress)) {
+            return createDnsDiagnostic({
+                expectedRecords,
+                publicIpAddress,
+                resolvedAddresses,
+                status: 'verified',
+                summary: `DNS is ready. \`${options.domain}\` resolves to this VPS.`,
+            });
+        }
+
+        if (resolvedAddresses.length === 0) {
+            return createDnsDiagnostic({
+                expectedRecords,
+                publicIpAddress,
+                resolvedAddresses,
+                status: 'pending',
+                summary: `\`${options.domain}\` does not resolve yet. Add the record below and wait for DNS propagation.`,
+            });
+        }
+
+        return createDnsDiagnostic({
+            expectedRecords,
+            publicIpAddress,
+            resolvedAddresses,
+            status: 'misconfigured',
+            summary: `\`${options.domain}\` currently resolves to ${resolvedAddresses.join(', ')}, not to this VPS IP \`${publicIpAddress}\`.`,
+        });
+    } catch (error) {
+        return createDnsDiagnostic({
+            expectedRecords,
+            publicIpAddress,
+            resolvedAddresses: [],
+            status: 'unavailable',
+            summary: `DNS verification failed: ${error instanceof Error ? error.message : 'Unknown DNS lookup error.'}`,
+        });
+    }
+}
+
+/**
+ * Resolves one hostname to all currently known IP addresses.
+ *
+ * @param domain - Domain to resolve.
+ * @returns Unique list of resolved IP addresses.
+ */
+async function resolveDnsAddresses(domain: string): Promise<ReadonlyArray<string>> {
+    try {
+        return (await lookup(domain, { all: true, verbatim: true })).map((record) => record.address);
+    } catch (error) {
+        const code = typeof error === 'object' && error !== null && 'code' in error ? String(error.code) : null;
+
+        if (code && DNS_PENDING_ERROR_CODES.has(code)) {
+            return [];
+        }
+
+        throw error;
+    }
+}
+
+/**
+ * Creates the expected DNS records shown in the admin UI.
+ *
+ * @param options - Record inputs.
+ * @returns DNS records the admin can copy into their provider.
+ */
+function createExpectedDnsRecords(options: {
+    readonly domain: string;
+    readonly publicIpAddress: string | null;
+    readonly fallbackCnameTargetDomain?: string | null | undefined;
+}): ReadonlyArray<ManagedServerDnsExpectedRecord> {
+    const expectedRecords: Array<ManagedServerDnsExpectedRecord> = [];
+
+    if (options.publicIpAddress) {
+        expectedRecords.push({
+            type: isIpv6Address(options.publicIpAddress) ? 'AAAA' : 'A',
+            name: options.domain,
+            value: options.publicIpAddress,
+            note: 'Recommended. Point this hostname directly to the VPS public IP address.',
+        });
+    }
+
+    if (options.fallbackCnameTargetDomain && options.fallbackCnameTargetDomain !== options.domain) {
+        expectedRecords.push({
+            type: 'CNAME',
+            name: options.domain,
+            value: options.fallbackCnameTargetDomain,
+            note: `Optional alternative for subdomains only. Use this only when \`${options.fallbackCnameTargetDomain}\` already works on this VPS.`,
+        });
+    }
+
+    return expectedRecords;
+}
+
+/**
+ * Normalizes the stored VPS public IP address.
+ *
+ * @param value - Raw environment/config value.
+ * @returns Normalized IP address or `null` when unavailable.
+ */
+function normalizePublicIpAddress(value: string | null | undefined): string | null {
+    const normalizedValue = (value || '').trim();
+
+    if (!normalizedValue || normalizedValue === 'localhost') {
+        return null;
+    }
+
+    return normalizedValue;
+}
+
+/**
+ * Creates one consistent browser payload for the DNS diagnostic.
+ *
+ * @param options - Normalized DNS state.
+ * @returns Browser-safe DNS payload.
+ */
+function createDnsDiagnostic(options: {
+    readonly expectedRecords: ReadonlyArray<ManagedServerDnsExpectedRecord>;
+    readonly publicIpAddress: string | null;
+    readonly resolvedAddresses: ReadonlyArray<string>;
+    readonly status: ManagedServerDnsStatus;
+    readonly summary: string;
+}): ManagedServerDnsDiagnostic {
+    return {
+        status: options.status,
+        summary: options.summary,
+        publicIpAddress: options.publicIpAddress,
+        resolvedAddresses: options.resolvedAddresses,
+        expectedRecords: options.expectedRecords,
+        providerGuides: DNS_PROVIDER_GUIDES,
+    };
+}
+
+/**
+ * Detects whether one resolved address is IPv6.
+ *
+ * @param value - Candidate IP address.
+ * @returns `true` when the address looks like IPv6.
+ */
+function isIpv6Address(value: string): boolean {
+    return value.includes(':');
+}
+
+/**
+ * Removes empty values and duplicates while preserving order.
+ *
+ * @param values - Candidate values.
+ * @returns Stable unique list.
+ */
+function uniqueStrings(values: ReadonlyArray<string>): Array<string> {
+    const uniqueValues: Array<string> = [];
+
+    for (const value of values) {
+        const normalizedValue = value.trim();
+
+        if (!normalizedValue || uniqueValues.includes(normalizedValue)) {
+            continue;
+        }
+
+        uniqueValues.push(normalizedValue);
+    }
+
+    return uniqueValues;
+}

package/apps/agents-server/src/utils/standaloneVpsRawIpBootstrap.ts

@@ -0,0 +1,87 @@
+/**
+ * Request-independent context used to decide whether standalone VPS setup should
+ * continue allowing raw-IP bootstrap access.
+ */
+export type StandaloneVpsRawIpBootstrapContext = {
+    /**
+     * Current canonical public site URL stored in the environment.
+     */
+    readonly nextPublicSiteUrl: string | null | undefined;
+
+    /**
+     * Known public IPv4/IPv6 address of the standalone VPS.
+     */
+    readonly publicIpAddress: string | null | undefined;
+};
+
+/**
+ * Returns whether the standalone VPS should keep allowing raw-IP bootstrap access.
+ *
+ * This stays enabled while the canonical public site URL still points to the VPS
+ * raw IP over plain HTTP, which means domain activation has not completed yet.
+ */
+export function isStandaloneVpsRawIpBootstrapActive(context: StandaloneVpsRawIpBootstrapContext): boolean {
+    const parsedPublicSiteUrl = parseAbsoluteHttpUrl(context.nextPublicSiteUrl);
+    if (!parsedPublicSiteUrl || parsedPublicSiteUrl.protocol !== 'http:') {
+        return false;
+    }
+
+    const normalizedSiteHost = normalizeHost(parsedPublicSiteUrl.host);
+    if (!normalizedSiteHost || !isIpAddressHost(normalizedSiteHost)) {
+        return false;
+    }
+
+    const normalizedConfiguredPublicIpAddress = normalizeHost(context.publicIpAddress || '');
+    if (normalizedConfiguredPublicIpAddress && normalizedSiteHost !== normalizedConfiguredPublicIpAddress) {
+        return false;
+    }
+
+    return true;
+}
+
+/**
+ * Parses one absolute HTTP(S) URL from environment configuration.
+ *
+ * @param value - Raw environment value.
+ * @returns Parsed URL or `null` when missing/invalid.
+ */
+function parseAbsoluteHttpUrl(value: string | null | undefined): URL | null {
+    if (!value) {
+        return null;
+    }
+
+    try {
+        const parsedUrl = new URL(value);
+
+        if (parsedUrl.protocol !== 'http:' && parsedUrl.protocol !== 'https:') {
+            return null;
+        }
+
+        return parsedUrl;
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Removes ports and IPv6 brackets from host-like strings.
+ *
+ * @param host - Raw host header value.
+ * @returns Normalized bare hostname or IP address.
+ */
+function normalizeHost(host: string | null | undefined): string {
+    return (host || '')
+        .trim()
+        .replace(/^\[(.+)\](?::\d+)?$/u, '$1')
+        .replace(/:\d+$/u, '');
+}
+
+/**
+ * Checks whether a host string points to a raw IPv4 or IPv6 address.
+ *
+ * @param host - Host header or hostname.
+ * @returns `true` when the host is a raw IP address.
+ */
+function isIpAddressHost(host: string): boolean {
+    return /^\d{1,3}(?:\.\d{1,3}){3}$/u.test(host) || host.includes(':');
+}