@learncard/network-brain-service 3.18.0 → 3.19.0

package/src/accesslayer/inbox-credential/refresh.ts

@@ -0,0 +1,221 @@
+import { CredentialRefreshRecordValidator } from 'types/credential-refresh';
+import { randomUUID } from 'node:crypto';
+import { TRPCError } from '@trpc/server';
+import { neogma } from '@instance';
+import type { InboxCredentialType, PublishCredentialRefreshResult } from '@learncard/types';
+import { inflateObject } from '@helpers/objects.helpers';
+
+export const getInboxRefreshIssue = async (
+    issueKey: string
+): Promise<{
+    inbox: InboxCredentialType;
+    requestDigest: string;
+    claimUrl?: string;
+} | null> => {
+    const result = await neogma.queryRunner.run(
+        'MATCH (ic:InboxCredential {refreshIssueKey: $issueKey}) RETURN ic LIMIT 1',
+        { issueKey }
+    );
+    const props = result.records[0]?.get('ic')?.properties;
+    return props
+        ? {
+              inbox: inflateObject(props),
+              requestDigest: props.refreshRequestDigest,
+              claimUrl: props.refreshClaimUrl,
+          }
+        : null;
+};
+
+/** Creates the inbox row and unbound aggregate together; a retry cannot allocate a second root. */
+export const createPendingInboxRefresh = async (params: {
+    inbox: Record<string, unknown>;
+    aggregate: Record<string, unknown>;
+    issueKey: string;
+    requestDigest: string;
+}): Promise<InboxCredentialType> => {
+    const result = await neogma.queryRunner.run(
+        `MATCH (issuer:Profile {profileId: $issuerProfileId})
+         MERGE (ic:InboxCredential {refreshIssueKey: $issueKey})
+         ON CREATE SET ic += $inbox, ic.refreshRequestDigest = $requestDigest
+         WITH issuer, ic WHERE ic.refreshRequestDigest = $requestDigest
+         MERGE (refresh:CredentialRefresh {refreshId: ic.refreshId})
+         ON CREATE SET refresh += $aggregate
+         MERGE (issuer)-[:ISSUED_REFRESH]->(refresh)
+         MERGE (refresh)-[:INBOX]->(ic)
+         MERGE (p:InboxRefreshPublication {refreshVersionKey: ic.refreshId + ':1'})
+         ON CREATE SET p.id = ic.refreshId, p.refreshId = ic.refreshId, p.version = 1,
+                       p.publishedAt = ic.createdAt, p.signingMode = 'signing-authority'
+         RETURN ic`,
+        { ...params, issuerProfileId: params.aggregate.issuerProfileId }
+    );
+    const props = result.records[0]?.get('ic')?.properties;
+    if (!props)
+        throw new TRPCError({
+            code: 'CONFLICT',
+            message: 'This idempotencyKey was used for a different inbox issuance.',
+        });
+    return inflateObject<InboxCredentialType>(props);
+};
+
+/** Metadata only. Pending publication bodies live exclusively in the expiring inbox escrow. */
+export const getPendingInboxPublication = async (
+    refreshId: string,
+    idempotencyKey?: string
+): Promise<PublishCredentialRefreshResult | null> => {
+    if (!idempotencyKey) return null;
+    const result = await neogma.queryRunner.run(
+        `MATCH (p:InboxRefreshPublication {refreshIdempotencyKey: $key}) RETURN p LIMIT 1`,
+        { key: `${refreshId}:${idempotencyKey}` }
+    );
+    const props = result.records[0]?.get('p')?.properties;
+    return props
+        ? {
+              refreshId,
+              version: Number(props.version),
+              publishedAt: props.publishedAt,
+              notification: 'not-applicable',
+          }
+        : null;
+};
+
+/** Publication and claim both lock the inbox row, then compare the version they prepared. */
+export const advancePendingInboxRefresh = async (params: {
+    refreshId: string;
+    expectedVersion: number;
+    credential: string;
+    credentialName?: string;
+    materialDigest: string;
+    idempotencyKey?: string;
+    updateSummary?: string;
+}): Promise<PublishCredentialRefreshResult | null> => {
+    const { refreshId, expectedVersion, idempotencyKey } = params;
+    const replay = await getPendingInboxPublication(refreshId, idempotencyKey);
+    if (replay) return replay;
+    const version = expectedVersion + 1;
+    const publishedAt = new Date().toISOString();
+    const result = await neogma.queryRunner.run(
+        `MATCH (refresh:CredentialRefresh {refreshId: $refreshId})-[:INBOX]->(ic:InboxCredential)
+         SET ic._escrowLock = true REMOVE ic._escrowLock
+         WITH refresh, ic
+         WHERE refresh.state = 'pending_holder' AND refresh.currentVersion = $expectedVersion
+           AND ic.currentStatus = 'PENDING' AND datetime(ic.expiresAt) > datetime()
+           AND ($key IS NULL OR NOT EXISTS { MATCH (:InboxRefreshPublication {refreshIdempotencyKey: $key}) })
+         CREATE (p:InboxRefreshPublication $publication)
+         SET ic.credential = $credential, ic.credentialName = $credentialName,
+             refresh.currentVersion = $version, refresh.materialDigest = $materialDigest,
+             refresh.credentialDisplayName = coalesce($credentialName, refresh.credentialDisplayName),
+             refresh.lastPublishedAt = $publishedAt, refresh.updatedAt = $publishedAt,
+             refresh.updateSummary = $updateSummary
+         RETURN p`,
+        {
+            ...params,
+            version,
+            publishedAt,
+            credentialName: params.credentialName ?? null,
+            updateSummary: params.updateSummary ?? null,
+            key: idempotencyKey ? `${refreshId}:${idempotencyKey}` : null,
+            publication: Object.fromEntries(
+                Object.entries({
+                    id: randomUUID(),
+                    refreshId,
+                    version,
+                    refreshVersionKey: `${refreshId}:${version}`,
+                    publishedAt,
+                    signingMode: 'signing-authority',
+                    updateSummary: params.updateSummary,
+                    refreshIdempotencyKey: idempotencyKey
+                        ? `${refreshId}:${idempotencyKey}`
+                        : undefined,
+                }).filter(([, value]) => value !== undefined)
+            ),
+        }
+    );
+    if (!result.records.length) return getPendingInboxPublication(refreshId, idempotencyKey);
+    return { refreshId, version, publishedAt, notification: 'not-applicable' };
+};
+
+/** Single commit: holder binding, canonical delivery, current version, and escrow erasure. */
+export const bindPendingInboxRefresh = async (params: {
+    inboxId: string;
+    refreshId: string;
+    expectedVersion: number;
+    holderDid: string;
+    holderProfileId?: string;
+    issuerProfileId: string;
+    root: Record<string, unknown>;
+    aggregate: Record<string, unknown>;
+    deliveryCredential: string;
+    deliveryExpiresAt: string;
+    accepted: boolean;
+    boostId?: string;
+}): Promise<boolean> => {
+    const now = new Date().toISOString();
+    const result = await neogma.queryRunner.run(
+        `MATCH (refresh:CredentialRefresh {refreshId: $refreshId})-[:INBOX]->(ic:InboxCredential {id: $inboxId})
+         SET ic._escrowLock = true REMOVE ic._escrowLock
+         WITH refresh, ic
+         WHERE refresh.state = 'pending_holder' AND refresh.currentVersion = $expectedVersion
+           AND ic.currentStatus = 'PENDING' AND datetime(ic.expiresAt) > datetime()
+           AND (ic.guardianStatus IS NULL OR ic.guardianStatus = 'GUARDIAN_APPROVED')
+         MATCH (issuer:Profile {profileId: $issuerProfileId})
+         OPTIONAL MATCH (holder:Profile {profileId: $holderProfileId})
+         OPTIONAL MATCH (boost:Boost {id: $boostId})
+         CREATE (root:Credential $root)
+         CREATE (refresh)-[:ROOT]->(root)
+         CREATE (refresh)-[:HEAD]->(root)
+         CREATE (issuer)-[:CREDENTIAL_SENT {to: $deliveryTarget, date: $now, activityId: ic.activityId, integrationId: ic.integrationId}]->(root)
+         FOREACH (_ IN CASE WHEN holder IS NULL THEN [] ELSE [1] END |
+             CREATE (holder)-[:HELD_REFRESH]->(refresh))
+         FOREACH (_ IN CASE WHEN holder IS NOT NULL AND $accepted THEN [1] ELSE [] END |
+             CREATE (root)-[:CREDENTIAL_RECEIVED {date: $now}]->(holder))
+         FOREACH (_ IN CASE WHEN boost IS NULL THEN [] ELSE [1] END |
+             CREATE (root)-[:INSTANCE_OF]->(boost))
+         SET refresh += $aggregate,
+             refresh.holderDid = $holderDid, refresh.holderProfileId = $holderProfileId,
+             refresh.state = CASE WHEN $accepted THEN 'active' ELSE 'awaiting_claim' END,
+             refresh.updatedAt = $now,
+             ic.currentStatus = 'ISSUED', ic.isAccepted = $accepted, ic.finalizedAt = $now,
+             ic.credential = null, ic.credentialName = null, ic.achievementType = null,
+             ic.deliveryCredential = $deliveryCredential, ic.deliveryRecipientDid = $holderDid,
+             ic.deliveryExpiresAt = $deliveryExpiresAt
+         RETURN root.id AS id`,
+        {
+            ...params,
+            now,
+            holderProfileId: params.holderProfileId ?? null,
+            boostId: params.boostId ?? null,
+            deliveryTarget: params.holderProfileId ?? params.holderDid,
+        }
+    );
+    return result.records.length > 0;
+};
+
+/** A read snapshot under the same inbox lock used by publish/claim, preventing mixed revisions. */
+export const getInboxRefreshSnapshot = async (inboxId: string) => {
+    const result = await neogma.queryRunner.run(
+        `MATCH (refresh:CredentialRefresh)-[:INBOX]->(ic:InboxCredential {id: $inboxId})
+         SET ic._escrowLock = true REMOVE ic._escrowLock
+         RETURN ic, refresh LIMIT 1`,
+        { inboxId }
+    );
+    const row = result.records[0];
+    if (!row) return null;
+    const props = row.get('refresh').properties;
+    return {
+        inbox: inflateObject<InboxCredentialType>(row.get('ic').properties),
+        aggregate: CredentialRefreshRecordValidator.parse({
+            ...props,
+            currentVersion: Number(props.currentVersion),
+        }),
+    };
+};
+
+export const recordInboxRefreshClaimUrl = async (id: string, claimUrl: string): Promise<string> => {
+    const result = await neogma.queryRunner.run(
+        `MATCH (ic:InboxCredential {id: $id})
+         SET ic.refreshClaimUrl = coalesce(ic.refreshClaimUrl, $claimUrl)
+         RETURN ic.refreshClaimUrl AS claimUrl`,
+        { id, claimUrl }
+    );
+    return result.records[0]!.get('claimUrl');
+};

package/src/accesslayer/inbox-credential/update.ts

@@ -10,7 +10,7 @@ import {
 
 export const updateInboxCredential = async (
     id: string,
-    updates: Partial<Omit<InboxCredentialType, 'id' | 'createdAt' | 'credential'>>
+    updates: Partial<Omit<InboxCredentialType, 'id' | 'createdAt' | 'credential' | 'refresh'>>
 ): Promise<InboxCredentialType | null> => {
     const result = await new QueryBuilder(new BindParam({ id, updates: flattenObject(updates) }))
         .match({ model: InboxCredential, identifier: 'inboxCredential' })

package/src/cache/atomic-counter.test-helpers.ts

@@ -0,0 +1,27 @@
+import { describe, expect, it } from 'vitest';
+import type { Cache } from './index';
+
+/** Run the same contract against memory in unit tests and Redis 7 in the CI container suite. */
+export const testAtomicCacheCounter = (cache: Cache): void => {
+    describe('atomic cache counter', () => {
+        it('increments atomically and repairs missing expiry', async () => {
+            const key = `atomic-increment-${crypto.randomUUID()}`;
+            try {
+                const counts = await Promise.all(
+                    Array.from({ length: 20 }, () => cache.incr(key, 3600, 5))
+                );
+                expect(counts.slice().sort((a, b) => a! - b!)).toEqual(
+                    Array.from({ length: 20 }, (_, i) => (i + 1) * 5)
+                );
+                expect(await cache.ttl(key)).toBeGreaterThan(3590);
+                // ttl=false deliberately writes without expiry; keepTtl would preserve it.
+                await cache.set(key, 200, false);
+                expect(await cache.ttl(key)).toBe(-1);
+                expect(await cache.incr(key, 3600, 2)).toBe(202);
+                expect(await cache.ttl(key)).toBeGreaterThan(3590);
+            } finally {
+                await cache.delete([key]);
+            }
+        });
+    });
+};

package/src/cache/atomic-counter.test.ts

@@ -0,0 +1,6 @@
+import { vi } from 'vitest';
+vi.mock('@environment', () => ({ environment: {} }));
+import cache from './index';
+import { testAtomicCacheCounter } from './atomic-counter.test-helpers';
+
+testAtomicCacheCounter(cache);

package/src/cache/index.ts

@@ -85,11 +85,11 @@ export type Cache = {
     lrange: (key: RedisKey, start: number, stop: number) => Promise<string[] | undefined>;
 
     /**
-     * Atomically increments a key by 1 and returns the new value.
-     * If the key does not exist it is created with value 1.
-     * When ttl is provided and this is the first increment (result === 1), EXPIRE is set.
+     * Atomically increments a key by amount (default 1) and returns the new value.
+     * If the key does not exist it is created with value amount.
+     * When ttl is provided, increment and missing-expiry repair happen atomically.
      */
-    incr: (key: RedisKey, ttl?: number) => Promise<number | undefined>;
+    incr: (key: RedisKey, ttl?: number, amount?: number) => Promise<number | undefined>;
 };
 
 /** Evict all keys after one hour by default */
@@ -239,19 +239,31 @@ export const getCache = (): Cache => {
 
             return undefined;
         },
-        incr: async (key, ttl) => {
+        incr: async (key, ttl, amount = 1) => {
             try {
                 const redis = cache?.redis ?? cache?.node;
                 if (!redis) return undefined;
 
-                const newVal = await redis.incr(key);
-
-                // Set TTL on first increment so the window auto-expires
-                if (newVal === 1 && ttl) {
-                    await redis.expire(key, ttl);
-                }
-
-                return newVal;
+                if (!Number.isSafeInteger(amount) || amount <= 0) return undefined;
+                // Increment and expiry must be atomic: a crash between commands must not
+                // leave a permanent quota. Also repair counters created without an expiry.
+                if (ttl)
+                    return Number(
+                        await redis.eval(
+                            `
+                    local count = redis.call('INCRBY', KEYS[1], ARGV[1])
+                    if redis.call('TTL', KEYS[1]) < 0 then
+                        redis.call('EXPIRE', KEYS[1], ARGV[2])
+                    end
+                    return count
+                `,
+                            1,
+                            key,
+                            amount,
+                            ttl
+                        )
+                    );
+                return await redis.incrby(key, amount);
             } catch (e) {
                 console.error('Cache incr error', e);
             }

package/src/config/environment.ts

@@ -36,6 +36,9 @@ export const brainServiceEnvironmentShape = {
     OIDC_EXPECTED_AUDIENCE: optionalEnvironmentString,
     AWS_REGION: optionalEnvironmentString,
     NOTIFICATIONS_QUEUE_URL: optionalEnvironmentUrl,
+    INBOX_QUEUE_URL: optionalEnvironmentUrl,
+    INBOX_DEAD_LETTER_QUEUE_URL: optionalEnvironmentUrl,
+    INBOX_QUEUE_ENDPOINT: optionalEnvironmentUrl,
     NOTIFICATIONS_QUEUE_POLL_URL: optionalEnvironmentUrl,
     NOTIFICATIONS_SERVICE_WEBHOOK_URL: optionalEnvironmentUrl.or(z.literal('false')),
     NOTIFICATIONS_SERVICE_PORT: optionalEnvironmentPort,
@@ -80,6 +83,8 @@ export const brainServiceEnvironmentShape = {
     IS_CI: optionalEnvironmentBoolean.default(false),
     IS_E2E_TEST: optionalEnvironmentBoolean.default(false),
     INBOX_DELETE_EXPIRED_RECORDS: optionalEnvironmentBoolean.default(false),
+    INBOX_BATCH_ITEMS_PER_HOUR: optionalEnvironmentString,
+    AWS_LAMBDA_FUNCTION_NAME: optionalEnvironmentString,
     ENABLE_BENCH_ROUTES: optionalEnvironmentBoolean.default(false),
     ENABLE_SEND_CREDENTIAL_TELEMETRY: optionalEnvironmentBoolean.default(false),
     LC_PERF_LOG: optionalEnvironmentBoolean.default(false),
@@ -206,6 +211,27 @@ export const getCredentialRefreshRuntimeEnvironment = (): CredentialRefreshRunti
         examplePath: 'services/learn-card-network/brain-service/.env.example',
     });
 
+const inboxBatchRuntimeEnvironmentSchema = z.object({
+    INBOX_QUEUE_URL: brainServiceEnvironmentShape.INBOX_QUEUE_URL,
+    INBOX_DEAD_LETTER_QUEUE_URL: brainServiceEnvironmentShape.INBOX_DEAD_LETTER_QUEUE_URL,
+    INBOX_QUEUE_ENDPOINT: brainServiceEnvironmentShape.INBOX_QUEUE_ENDPOINT,
+    AWS_REGION: brainServiceEnvironmentShape.AWS_REGION,
+    NODE_ENV: brainServiceEnvironmentShape.NODE_ENV,
+    IS_OFFLINE: brainServiceEnvironmentShape.IS_OFFLINE,
+    AWS_LAMBDA_FUNCTION_NAME: brainServiceEnvironmentShape.AWS_LAMBDA_FUNCTION_NAME,
+    INBOX_BATCH_ITEMS_PER_HOUR: brainServiceEnvironmentShape.INBOX_BATCH_ITEMS_PER_HOUR,
+});
+
+export type InboxBatchRuntimeEnvironment = z.output<typeof inboxBatchRuntimeEnvironmentSchema>;
+
+/** Reads batch settings at call time so local invocations and tests can override them safely. */
+export const getInboxBatchRuntimeEnvironment = (): InboxBatchRuntimeEnvironment =>
+    parseEnvironment(inboxBatchRuntimeEnvironmentSchema, process.env, {
+        project: 'brain-service inbox batch',
+        source: 'process environment',
+        examplePath: 'services/learn-card-network/brain-service/.env.example',
+    });
+
 export type BrainServiceEnvironment = z.output<typeof brainServiceEnvironmentSchema>;
 
 export const parseBrainServiceEnvironment = (

package/src/credential-refresh.ts

@@ -172,7 +172,11 @@ const authenticateRefreshRequest = async (
 
     // Missing aggregates, wrong holders, and awaiting-claim aggregates deliberately
     // share one response so a valid DID cannot use the endpoint as an existence oracle.
-    if (aggregate.holderDid !== auth.holderDid) {
+    if (
+        !aggregate.holderDid ||
+        aggregate.state === 'pending_holder' ||
+        aggregate.holderDid !== auth.holderDid
+    ) {
         logRefreshRequest(refreshId, 'unauthorized', startedAt);
         await reply.status(403).send({ code: 'CREDENTIAL_REFRESH_UNAUTHORIZED' });
         return null;

package/src/docker-entry.ts

@@ -1,3 +1,4 @@
+import { configureInboxBatchBodyLimit } from '@helpers/inbox-batch-http.helpers';
 import { environment } from '@environment';
 import Fastify from 'fastify';
 import fastifyCors from '@fastify/cors';
@@ -15,6 +16,7 @@ import {
 import { neogma } from '@instance';
 import { appRouter, type AppRouter, createContext } from './app';
 import { openApiDocument } from './openapi';
+import { inboxBatchResponseMeta } from './helpers/inbox-batch-http.helpers';
 import { didFastifyPlugin } from './dids';
 import { skillsViewerFastifyPlugin } from './skills-viewer';
 import { statusListsFastifyPlugin } from './status-lists';
@@ -25,6 +27,11 @@ import { maybeAutoSeedSkillFrameworks } from './seed/seedSkillFrameworks';
 
 const server = Fastify({ routerOptions: { maxParamLength: 5000 } });
 
+// Register before either OpenAPI or tRPC registers its wildcard route. The hook raises the
+// parser ceiling for those shared routes, then narrows it back to 4 MiB only for batch issuance.
+// Registering this later would leave the already-created adapter routes at Fastify's 1 MiB limit.
+configureInboxBatchBodyLimit(server);
+
 server.addHook('onRequest', (request, _reply, done) => {
     type RawWithEmitter = typeof request.raw & {
         on?: (...args: unknown[]) => unknown;
@@ -79,6 +86,7 @@ server.register(fastifyTRPCPlugin, {
 });
 
 server.register(fastifyTRPCOpenApiPlugin, {
+    responseMeta: inboxBatchResponseMeta,
     basePath: '/api',
     router: appRouter,
     createContext,

package/src/helpers/activity.helpers.ts

@@ -20,6 +20,7 @@ export const logCredentialActivity = async (
 };
 
 export const logCredentialSent = async (params: {
+    onBehalfOf?: string;
     actorProfileId?: string;
     recipientType: CredentialActivityRecipientType;
     recipientIdentifier: string;
@@ -45,6 +46,7 @@ export const logCredentialSent = async (params: {
 };
 
 export const logCredentialDelivered = async (params: {
+    onBehalfOf?: string;
     activityId: string;
     actorProfileId: string;
     recipientType: CredentialActivityRecipientType;
@@ -64,6 +66,7 @@ export const logCredentialDelivered = async (params: {
 };
 
 export const logCredentialClaimed = async (params: {
+    onBehalfOf?: string;
     activityId?: string;
     actorProfileId: string;
     recipientType: CredentialActivityRecipientType;
@@ -98,6 +101,7 @@ export const logCredentialExpired = async (params: {
 };
 
 export const logCredentialFailed = async (params: {
+    onBehalfOf?: string;
     activityId?: string;
     actorProfileId: string;
     recipientType: CredentialActivityRecipientType;

package/src/helpers/app-counter.helpers.ts

@@ -44,7 +44,7 @@ export const handleIncrementCounterEvent = async (
         // tRPC does not support HTTP 429 natively, so we cast to BAD_REQUEST
         // while keeping the semantic code in the message for clients.
         throw new TRPCError({
-            code: 'TOO_MANY_REQUESTS' as 'BAD_REQUEST',
+            code: 'TOO_MANY_REQUESTS',
             message: 'Rate limit exceeded: max 100 counter writes per user per app per minute',
         });
     }

package/src/helpers/contact-method.helpers.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it, vi } from 'vitest';
+
+const environment = vi.hoisted(() => ({
+    CLIENT_APP_DOMAIN_NAME: undefined as string | undefined,
+    CLIENT_APP_PORT: undefined as number | undefined,
+    PORT: 4000,
+    IS_OFFLINE: true,
+}));
+vi.mock('@environment', () => ({ environment }));
+vi.mock('@cache', () => ({ default: {} }));
+
+import { generateClaimUrl } from './contact-method.helpers';
+
+describe('inbox claim links', () => {
+    it('opens the default frontend instead of the backend port', () => {
+        expect(generateClaimUrl('test-token')).toBe(
+            'http://localhost:3000/interactions/inbox-claim/test-token?iuv=1'
+        );
+    });
+
+    it('uses the configured frontend port locally', () => {
+        environment.CLIENT_APP_PORT = 3100;
+        try {
+            expect(generateClaimUrl('test-token')).toContain('http://localhost:3100/');
+        } finally {
+            environment.CLIENT_APP_PORT = undefined;
+        }
+    });
+
+    it('honors a configured app domain locally and keeps production HTTPS', () => {
+        environment.CLIENT_APP_DOMAIN_NAME = 'app.example.org';
+        try {
+            expect(generateClaimUrl('test-token')).toContain('http://app.example.org/');
+            environment.IS_OFFLINE = false;
+            expect(generateClaimUrl('test-token')).toBe(
+                'https://app.example.org/interactions/inbox-claim/test-token?iuv=1'
+            );
+        } finally {
+            environment.IS_OFFLINE = true;
+            environment.CLIENT_APP_DOMAIN_NAME = undefined;
+        }
+    });
+});

package/src/helpers/contact-method.helpers.ts

@@ -110,10 +110,9 @@ export const markInboxClaimTokenAsUsed = async (token: string): Promise<boolean>
 
 export const generateClaimUrl = (token: string): string => {
     const domainName = environment.CLIENT_APP_DOMAIN_NAME;
-    const domain =
-        !domainName || environment.IS_OFFLINE
-            ? `localhost:${environment.PORT || 3000}`
-            : domainName;
+    // Claim links open the frontend, not the brain-service HTTP port. Honor an
+    // explicitly configured app domain in local development as well.
+    const domain = domainName || `localhost:${environment.CLIENT_APP_PORT || 3000}`;
 
     const protocol = environment.IS_OFFLINE ? 'http' : 'https';