@ima-jin/config 0.7.0 → 0.8.13

package/src/cors.ts

@@ -4,6 +4,13 @@ import { NextRequest, NextResponse } from "next/server";
 const ORIGIN_PATTERN = /^https:\/\/(dev-)?[a-z-]+\.imajin\.ai$/;
 const LOCAL_PATTERN = /^http:\/\/localhost:\d+$/;
 
+/**
+ * CSP host-source list corresponding to ORIGIN_PATTERN (prod).
+ * Used by security-headers.ts to build frame-ancestors directives.
+ * If the allowed-origin set changes, update ORIGIN_PATTERN and this constant together.
+ */
+export const ALLOWED_FRAME_ORIGINS = 'https://*.imajin.ai https://imajin.ai';
+
 export function isAllowedOrigin(origin: string | null): boolean {
   if (!origin) return false;
   if (ORIGIN_PATTERN.test(origin)) return true;
@@ -18,7 +25,7 @@ export function corsHeaders(request: NextRequest): Record<string, string> {
     "Access-Control-Allow-Origin": allowed ? origin : "",
     "Access-Control-Allow-Credentials": "true",
     "Access-Control-Allow-Methods": "GET, POST, PUT, DELETE, OPTIONS",
-    "Access-Control-Allow-Headers": "Content-Type, Authorization, X-Caller-DID",
+    "Access-Control-Allow-Headers": "Content-Type, Authorization, X-Caller-DID, X-App-DID, X-App-Authorization",
     "Vary": "Origin",
   };
 }

package/src/dashboard-redirect-middleware.ts

@@ -0,0 +1,56 @@
+import { NextRequest, NextResponse } from "next/server";
+import { buildPublicUrlAbsolute } from "./services";
+import { corsHeaders, withCors } from "./cors";
+
+export interface StandaloneDashboardMiddlewareOptions {
+  /** Service name used to build the hub tab URL (`/auth/<service>`). */
+  service: string;
+  /**
+   * Whether to also answer CORS preflight and stamp CORS headers on every
+   * other request — matches the app's pre-existing `/api/:path*` CORS
+   * middleware (#1525). Defaults to `true`; pass `false` for an app (e.g.
+   * dykil) that never had one.
+   */
+  cors?: boolean;
+}
+
+/**
+ * Shared standalone-dashboard-to-hub redirect body (#2332, carved out of
+ * #2275), used by every userspace service app's `middleware.ts` so the
+ * redirect + CORS pass-through logic isn't duplicated six times over.
+ *
+ * Each app still declares its own literal `export const config = { matcher:
+ * [...] }` — Next.js statically extracts `matcher` from the middleware
+ * file's AST at build time (see
+ * `next/dist/build/analysis/extract-const-value.js`: it only understands
+ * literal object/array/string/etc. expressions, not a function call or a
+ * destructured import) — so the matcher itself can't be factored out here
+ * without Next silently falling back to its default, unrestricted matcher.
+ * Only the function *body* is shared.
+ *
+ * The redirect is unconditional: a 308 to `/auth/<service>`, preserving the
+ * query string. The embedded rendering path `<ServiceEmbed>` loads
+ * (`?embed=hub&did=...`, see `apps/kernel/app/auth/lib/service-registry.ts`'s
+ * `buildEmbedSrc`) never reaches this function at all — it's excluded
+ * declaratively by each app's `matcher.missing` clause.
+ */
+export function standaloneDashboardMiddleware(
+  request: NextRequest,
+  { service, cors = true }: StandaloneDashboardMiddlewareOptions,
+): NextResponse {
+  if (request.nextUrl.pathname === "/dashboard") {
+    const hubUrl = new URL(`${buildPublicUrlAbsolute("kernel")}/auth/${service}`);
+    hubUrl.search = request.nextUrl.search;
+    return NextResponse.redirect(hubUrl, 308);
+  }
+
+  if (!cors) {
+    return NextResponse.next();
+  }
+
+  if (request.method === "OPTIONS") {
+    return new NextResponse(null, { status: 204, headers: corsHeaders(request) });
+  }
+
+  return withCors(NextResponse.next(), request);
+}

package/src/forest-config.ts

@@ -0,0 +1,51 @@
+import { getServiceUrl } from './services';
+
+/**
+ * Public forest-group (scope) config exposed by
+ * `GET /api/forest/{groupDid}/config/public` on the profile service. Only
+ * the field relevant to `.fair` fee-split calculation is modeled here — the
+ * rest of the config (enabledServices, landingService, etc.) is a
+ * community-settings concern, not a shared SDK concern.
+ */
+export interface ForestScopeConfig {
+  /** Group's configured revenue-share fee, in basis points (0-500). Null if unset. */
+  scopeFeeBps: number | null;
+}
+
+function profileBaseUrl(): string {
+  // Like every other `*_SERVICE_URL`, this includes the service's path
+  // prefix (`/profile`) — callers append only the endpoint path
+  // (`/api/forest/...`). See #2046 (the equivalent REGISTRY_SERVICE_URL
+  // fix) for why omitting the prefix here is the wrong default.
+  if (process.env.PROFILE_SERVICE_URL) return process.env.PROFILE_SERVICE_URL;
+  const mode = process.env.NODE_ENV === 'production' ? 'prod' : 'dev';
+  const base = getServiceUrl('profile', mode) ?? 'http://localhost:3000';
+  return `${base}/profile`;
+}
+
+/**
+ * Fetch a forest group's public scope-fee config from the profile service
+ * (`GET /api/forest/{groupDid}/config/public`, documented in
+ * `apps/kernel/api-spec/profile.yaml`).
+ *
+ * Replaces raw `profile.forest_config` SQL reads that were duplicated
+ * across coffee, learn, and market (audit item 9 of #1983, #2001). Returns
+ * null on any failure — network error, non-2xx response — so callers can
+ * fall back to the same `scopeFeeBps: null` default they used when the raw
+ * SQL row was missing.
+ */
+export async function getForestScopeConfig(groupDid: string): Promise<ForestScopeConfig | null> {
+  const url = `${profileBaseUrl()}/api/forest/${encodeURIComponent(groupDid)}/config/public`;
+  try {
+    const res = await fetch(url);
+    if (!res.ok) {
+      console.warn(`[config] getForestScopeConfig: profile service returned ${res.status} for ${url}`);
+      return null;
+    }
+    const data = (await res.json()) as { scopeFeeBps?: unknown };
+    return { scopeFeeBps: typeof data?.scopeFeeBps === 'number' ? data.scopeFeeBps : null };
+  } catch (err) {
+    console.warn(`[config] getForestScopeConfig: fetch failed for ${url} — ${err instanceof Error ? err.message : String(err)}`);
+    return null;
+  }
+}

package/src/handles.ts

@@ -10,13 +10,13 @@
 export const HANDLE_PATTERN = /^[a-z0-9._-]{3,30}$/;
 
 /** Regex: disallowed leading/trailing characters */
-const HANDLE_EDGE = /^[.\-]|[.\-]$/;
+const HANDLE_EDGE = /^[.-]|[.-]$/;
 
 /** Regex: consecutive dots or hyphens */
-const HANDLE_CONSECUTIVE = /[.\-]{2}/;
+const HANDLE_CONSECUTIVE = /[.-]{2}/;
 
 /** HTML input pattern attribute (no anchors, no flags) */
-export const HANDLE_INPUT_PATTERN = '[a-z0-9._\\-]{3,30}';
+export const HANDLE_INPUT_PATTERN = String.raw`[a-z0-9._\-]{3,30}`;
 
 /** Characters allowed in handles — use in onChange filters */
 export const HANDLE_ALLOWED_CHARS = /[^a-z0-9._-]/g;

package/src/index.ts

@@ -1,4 +1,8 @@
-export { isAllowedOrigin, corsHeaders, corsOptions, withCors, validateOrigin } from "./cors";
+export { isAllowedOrigin, corsHeaders, corsOptions, withCors, validateOrigin, ALLOWED_FRAME_ORIGINS } from "./cors";
+export { standaloneDashboardMiddleware } from "./dashboard-redirect-middleware";
+export type { StandaloneDashboardMiddlewareOptions } from "./dashboard-redirect-middleware";
+export { tier1Headers, tier2Headers, tier3Headers } from './security-headers';
+export { APP_DISPLAY_NAME } from './brand';
 
 export {
   SERVICES,
@@ -8,6 +12,7 @@ export {
   getServiceUrl,
   getPublicUrl,
   buildPublicUrl,
+  buildPublicUrlAbsolute,
   servicesByTier,
   servicesByVisibility,
   buildServiceUrlMap,
@@ -27,6 +32,16 @@ export {
 
 export { apiFetch, apiUrl } from "./base-path";
 
+export { rateLimit, getClientIP } from "./rate-limit";
+
+export { getNodeSelf } from "./node-self";
+export type { NodeSelfInfo } from "./node-self";
+
+export { registryServiceUrl, hasRegistryServiceUrl } from "./registry-service-url";
+
+export { getForestScopeConfig } from "./forest-config";
+export type { ForestScopeConfig } from "./forest-config";
+
 export {
   HANDLE_PATTERN,
   HANDLE_INPUT_PATTERN,

package/src/node-self.ts

@@ -0,0 +1,45 @@
+import { registryServiceUrl } from './registry-service-url';
+
+/**
+ * Minimal public node metadata returned by GET /registry/api/node/self.
+ * Mirrors the subset of `relay.relay_config` the registry service exposes
+ * publicly — never the private config (profile artifact JWS, etc).
+ */
+export interface NodeSelfInfo {
+  /** This node's own DID (did:imajin:...). */
+  did: string;
+  /** DID of the human/entity operating this node, if configured. */
+  nodeOperatorDid: string | null;
+  /** Node fee, in basis points, applied to .fair settlements on this node. */
+  nodeFeeBps: number | null;
+  /** Buyer credit, in basis points, applied to .fair settlements on this node. */
+  buyerCreditBps: number | null;
+}
+
+/**
+ * Fetch this node's public identity + .fair fee config from the registry
+ * service (`GET /registry/api/node/self`, #2000).
+ *
+ * Replaces raw `relay.relay_config` SQL reads that were duplicated across
+ * coffee, learn, events, and market (audit item 8 of #1983). Returns null on
+ * any failure — network error, non-2xx response (e.g. 503 when the node
+ * identity hasn't been bootstrapped yet) — so callers can fall back to
+ * defaults exactly as they did when the raw SQL row was missing. A non-2xx
+ * response is logged with the URL actually hit (no secrets) so a
+ * misconfigured REGISTRY_SERVICE_URL prefix is visible instead of failing
+ * silently (#2046).
+ */
+export async function getNodeSelf(): Promise<NodeSelfInfo | null> {
+  const url = `${registryServiceUrl()}/api/node/self`;
+  try {
+    const res = await fetch(url);
+    if (!res.ok) {
+      console.warn(`[config] getNodeSelf: registry returned ${res.status} for ${url} — check REGISTRY_SERVICE_URL`);
+      return null;
+    }
+    return (await res.json()) as NodeSelfInfo;
+  } catch (err) {
+    console.warn(`[config] getNodeSelf: fetch failed for ${url} — ${err instanceof Error ? err.message : String(err)}`);
+    return null;
+  }
+}

package/src/rate-limit.ts

@@ -0,0 +1,54 @@
+/**
+ * Simple sliding-window in-memory rate limiter.
+ * Safe for single-process Next.js. Per-worker in multi-worker setups (acceptable).
+ */
+
+interface RateLimitEntry {
+  timestamps: number[];
+  lastSeen: number;
+}
+
+const store = new Map<string, RateLimitEntry>();
+let lastGlobalCleanup = Date.now();
+
+function pruneStore(now: number) {
+  if (now - lastGlobalCleanup < 60_000) return;
+  store.forEach((entry, key) => {
+    if (now - entry.lastSeen > 120_000) {
+      store.delete(key);
+    }
+  });
+  lastGlobalCleanup = now;
+}
+
+export function rateLimit(
+  key: string,
+  limit: number,
+  windowMs: number
+): { limited: boolean; retryAfter: number } {
+  const now = Date.now();
+  pruneStore(now);
+
+  const windowStart = now - windowMs;
+  const entry = store.get(key) ?? { timestamps: [], lastSeen: now };
+
+  entry.timestamps = entry.timestamps.filter((t) => t > windowStart);
+  entry.lastSeen = now;
+
+  if (entry.timestamps.length >= limit) {
+    const oldest = entry.timestamps[0];
+    const retryAfter = Math.ceil((oldest + windowMs - now) / 1000);
+    store.set(key, entry);
+    return { limited: true, retryAfter: Math.max(1, retryAfter) };
+  }
+
+  entry.timestamps.push(now);
+  store.set(key, entry);
+  return { limited: false, retryAfter: 0 };
+}
+
+export function getClientIP(request: Request): string {
+  const forwarded = request.headers.get('x-forwarded-for');
+  if (forwarded) return forwarded.split(',')[0].trim();
+  return '127.0.0.1';
+}

package/src/registry-service-url.ts

@@ -0,0 +1,54 @@
+/**
+ * Single resolver for the registry service's base URL (#2061 — kernel was
+ * the last `REGISTRY_URL` holdout after #2048 established the
+ * `*_SERVICE_URL` convention).
+ *
+ * The returned value always includes the `/registry` path prefix, like
+ * every other `*_SERVICE_URL` (#2046) — callers append only the endpoint
+ * path (e.g. `/api/node/self`, `/relay/operations`).
+ *
+ * Precedence:
+ *   1. `REGISTRY_SERVICE_URL` — the current convention.
+ *   2. `REGISTRY_URL` — deprecated kernel-only legacy name. Used if set,
+ *      but logs a one-time deprecation warning per process.
+ *   3. `http://localhost:${PORT || 3000}/registry` — the mode-aware
+ *      fallback (PORT is 3000 in dev, 7000 in prod) that
+ *      `relay-well-known.ts` already used before this consolidation.
+ */
+
+let warnedAboutLegacyRegistryUrl = false;
+
+export function registryServiceUrl(): string {
+  if (process.env.REGISTRY_SERVICE_URL) return process.env.REGISTRY_SERVICE_URL;
+
+  if (process.env.REGISTRY_URL) {
+    if (!warnedAboutLegacyRegistryUrl) {
+      console.warn('REGISTRY_URL is deprecated — set REGISTRY_SERVICE_URL');
+      warnedAboutLegacyRegistryUrl = true;
+    }
+    return process.env.REGISTRY_URL;
+  }
+
+  return `http://localhost:${process.env.PORT || 3000}/registry`;
+}
+
+/**
+ * True when the registry URL is explicitly configured via either the
+ * current (`REGISTRY_SERVICE_URL`) or deprecated (`REGISTRY_URL`) env var.
+ *
+ * `registryServiceUrl()` always returns a value (it falls back to a
+ * localhost guess), so callers that previously guarded on
+ * `!process.env.REGISTRY_URL` to skip/no-op when the registry isn't
+ * configured should check this instead.
+ */
+export function hasRegistryServiceUrl(): boolean {
+  return Boolean(process.env.REGISTRY_SERVICE_URL || process.env.REGISTRY_URL);
+}
+
+/**
+ * Test-only: resets the one-time deprecation warning latch so each test
+ * can assert the warning fires exactly once for its own scenario.
+ */
+export function __resetRegistryServiceUrlWarningForTests(): void {
+  warnedAboutLegacyRegistryUrl = false;
+}

package/src/security-headers.ts

@@ -0,0 +1,45 @@
+import { ALLOWED_FRAME_ORIGINS } from './cors';
+
+type HeaderEntry = { key: string; value: string };
+
+/**
+ * Build the frame-ancestors directive value.
+ * Mirrors isAllowedOrigin(): includes localhost:* in non-prod so local
+ * hub-iframe development works without disabling frame protection.
+ */
+function buildFrameAncestors(): string {
+  const local = process.env.NODE_ENV !== 'production' ? ' http://localhost:*' : '';
+  return `frame-ancestors 'self' ${ALLOWED_FRAME_ORIGINS}${local}`;
+}
+
+/**
+ * Tier 1 — hard deny framing.
+ * Use on credential and auth-sensitive pages that must never be embedded.
+ */
+export function tier1Headers(): HeaderEntry[] {
+  return [
+    { key: 'Content-Security-Policy', value: "frame-ancestors 'none'" },
+    { key: 'X-Frame-Options', value: 'DENY' },
+  ];
+}
+
+/**
+ * Tier 2 — allow framing by Imajin origins only.
+ * Use on routes embedded by the auth hub (service dashboards, document viewer, surveys).
+ * Does not include X-Frame-Options — it cannot express an allow-list, and SAMEORIGIN
+ * would break cross-subdomain framing. CSP frame-ancestors does the work here.
+ */
+export function tier2Headers(): HeaderEntry[] {
+  return [{ key: 'Content-Security-Policy', value: buildFrameAncestors() }];
+}
+
+/**
+ * Tier 3 — baseline hardening.
+ * Safe to apply on every route in every app.
+ */
+export function tier3Headers(): HeaderEntry[] {
+  return [
+    { key: 'X-Content-Type-Options', value: 'nosniff' },
+    { key: 'Referrer-Policy', value: 'strict-origin-when-cross-origin' },
+  ];
+}

package/src/services.ts

@@ -1,7 +1,17 @@
 /**
- * Canonical service manifest — single source of truth for all Imajin services.
+ * Canonical service manifest — infra/build-time topology for all Imajin
+ * services (dev/prod ports, Postgres schema, deployment tier, Caddy/pm2
+ * routing, docs sync, `/registry/api/specs`). These consumers run without a
+ * live identity/DB context (build scripts, edge config, port-based
+ * routing), so this stays a static, synchronously-importable array.
  *
- * Consumers: registry specs, Caddy config, pm2 ecosystem, docs sync, shared nav.
+ * NOT the nav authority (#2425): which apps an authenticated identity sees
+ * in the kernel hub (auth submenu, launcher, home tiles) is now derived
+ * from `registry.apps` (#1990) via `apps/kernel/src/lib/kernel/app-nav.ts`,
+ * not from this file — a disabled/pruned app disappears from nav by
+ * flipping registry state, independent of whether it still has a row here
+ * for port/Caddy purposes. Consumers: registry specs, Caddy config, pm2
+ * ecosystem, docs sync.
  */
 
 export type ServiceTier = "core" | "imajin";
@@ -46,6 +56,11 @@ export const SERVICES: readonly ServiceDefinition[] = [
   { name: "media",       label: "Media",       icon: "📁", description: "Files, images, and .fair attribution",               devPort: 3000, prodPort: 7000, schema: "media",       tier: "core",   visibility: "authenticated", category: "kernel" },
   { name: "registry",    label: "Registry",    icon: "📡", description: "Service registry and DFOS relay",                    devPort: 3000, prodPort: 7000, schema: "registry",    tier: "core",   visibility: "public",        category: "kernel" },
   { name: "notify",      label: "Notify",      icon: "🔔", description: "Notifications and preferences",                     devPort: 3000, prodPort: 7000, schema: "notify",      tier: "core",   visibility: "internal",      category: "kernel" },
+  { name: "usage",       label: "Usage",       icon: "📊", description: "Inference cost ledger — incurred, billed, drift, signed rollup", devPort: 3000, prodPort: 7000, schema: "usage",       tier: "core",   visibility: "authenticated", category: "kernel" },
+  { name: "calendar",    label: "Calendar",    icon: "📅", description: "Temporal entries — availability, meetings, events, and reminders", devPort: 3000, prodPort: 7000, schema: null,          tier: "core",   visibility: "authenticated", category: "kernel" },
+  { name: "jin",         label: "Jin",         icon: "🧭", description: "Operator dashboard — signed approvals, proposals, and usage feed",  devPort: 3000, prodPort: 7000, schema: "operator",    tier: "core",   visibility: "internal",      category: "kernel" },
+  { name: "google",      label: "Google Workspace", icon: "📨", description: "Gmail/Calendar/Drive/Meet connector — OAuth2 auth-code, sealed refresh token", devPort: 3000, prodPort: 7000, schema: null,          tier: "core",   visibility: "authenticated", category: "kernel" },
+  { name: "vault",       label: "Vault",       icon: "🔐", description: "Sealed secrets, delegation grants, and vault-minted service credentials", devPort: 3000, prodPort: 7000, schema: null,          tier: "core",   visibility: "internal",      category: "kernel" },
 
   // Core apps — separate processes
   { name: "events",      label: "Events",      icon: "🎫", description: "Event creation, ticketing, and management",         devPort: 3006, prodPort: 7006, schema: "events",      tier: "core",   visibility: "public",        category: "core" },
@@ -62,6 +77,10 @@ export const SERVICES: readonly ServiceDefinition[] = [
   { name: 'github',      label: 'GitHub',      icon: '🐙', description: 'Source code',                                       devPort: 3000, prodPort: 7000, schema: "public",      tier: 'core',   visibility: 'public',        category: 'meta', externalUrl: 'https://github.com/ima-jin/imajin-ai' },
   { name: 'docs',        label: 'Docs',        icon: '📄', description: 'API documentation',                                 devPort: 3000, prodPort: 7000, schema: "public",      tier: 'core',   visibility: 'public',        category: 'meta', wwwPath: '/developer-guide' },
 
+  // Daemon processes — not web apps, no HTTP port exposed
+  { name: 'broker-agent', label: 'Broker Agent', icon: '🤖', description: 'Telegram broker agent — conversational surface for social coordination (#1101)', devPort: 0, prodPort: 0, schema: null, tier: 'core', visibility: 'internal', category: 'infrastructure' },
+  { name: 'corpus',       label: 'Corpus',       icon: '🔎', description: 'Per-DID corpus indexing and BM25 search service (#1737)',                    devPort: 8013, prodPort: 8013, schema: null, tier: 'core', visibility: 'internal', category: 'infrastructure' },
+
   // Connected apps (separate repos) will use the plugin architecture (#249).
   // Not included here — they authenticate via delegated sessions, not the monorepo manifest.
 ] as const satisfies readonly ServiceDefinition[];
@@ -76,7 +95,8 @@ export function getService(name: string): ServiceDefinition | undefined {
 /** Get the port for a service in a given environment */
 export function getPort(name: string, env: "dev" | "prod" = "dev"): number | undefined {
   const svc = getService(name);
-  return svc ? (env === "prod" ? svc.prodPort : svc.devPort) : undefined;
+  if (!svc) return undefined;
+  return env === "prod" ? svc.prodPort : svc.devPort;
 }
 
 /** Get internal URL for a service (server-side calls) */
@@ -115,7 +135,7 @@ export function getPublicUrl(
 
   // Single-domain mode: prefix contains dots (e.g. "dev-jin.imajin.ai/")
   // Build https://{prefix}{name} instead of https://{prefix}-{name}.{domain}
-  if (prefix && prefix.includes(".")) {
+  if (prefix?.includes(".")) {
     const base = prefix.endsWith("/") ? prefix.slice(0, -1) : prefix;
     // "www" or "kernel" = root of the node, no suffix
     if (name === "www" || name === "kernel") return `https://${base}`;
@@ -147,8 +167,8 @@ export function buildPublicUrl(
     if (explicit) return explicit;
   }
 
-  const p = servicePrefix ?? (typeof process !== "undefined" ? process.env.NEXT_PUBLIC_SERVICE_PREFIX : undefined) ?? "https://";
-  const d = domain ?? (typeof process !== "undefined" ? process.env.NEXT_PUBLIC_DOMAIN : undefined) ?? "imajin.ai";
+  const p = servicePrefix ?? (typeof process === "undefined"  ? undefined : process.env.NEXT_PUBLIC_SERVICE_PREFIX) ?? "https://";
+  const d = domain ?? (typeof process === "undefined"  ? undefined : process.env.NEXT_PUBLIC_DOMAIN) ?? "imajin.ai";
 
   // Localhost detection
   if (p.includes("localhost") || d.includes("localhost")) {
@@ -168,6 +188,45 @@ export function buildPublicUrl(
   return getPublicUrl(name, { prefix: match, domain: d });
 }
 
+/**
+ * Build an ABSOLUTE public URL for a service — for use OUTSIDE the browser
+ * origin: email links, Stripe/webhook return/success URLs, externally shared
+ * links, and cross-node links. Unlike buildPublicUrl(), this never returns a
+ * relative path.
+ *
+ * Resolution order:
+ *   1. explicit NEXT_PUBLIC_{NAME}_URL env var (only if already absolute)
+ *   2. localhost dev → http://localhost:{devPort} from the canonical port map
+ *   3. otherwise an absolute https URL derived from NEXT_PUBLIC_SERVICE_PREFIX
+ *      + NEXT_PUBLIC_DOMAIN via getPublicUrl()
+ *
+ * @example
+ *   buildPublicUrlAbsolute('chat')   → https://jin.imajin.ai/chat (single-domain)
+ *   buildPublicUrlAbsolute('kernel') → https://jin.imajin.ai (node root)
+ */
+export function buildPublicUrlAbsolute(name: string): string {
+  // 1. Explicit per-service override wins if it is already absolute.
+  if (typeof process !== "undefined") {
+    const explicit = process.env[`NEXT_PUBLIC_${name.toUpperCase()}_URL`];
+    if (explicit && /^https?:\/\//.test(explicit)) return explicit;
+  }
+
+  const prefix =
+    (typeof process === "undefined" ? undefined : process.env.NEXT_PUBLIC_SERVICE_PREFIX) ?? "https://";
+  const domain =
+    (typeof process === "undefined" ? undefined : process.env.NEXT_PUBLIC_DOMAIN) ?? "imajin.ai";
+
+  // 2. Localhost dev → canonical dev port.
+  if (prefix.includes("localhost") || domain.includes("localhost")) {
+    const port = getPort(name, "dev");
+    return port ? `http://localhost:${port}` : "http://localhost:3000";
+  }
+
+  // 3. Force absolute construction (getPublicUrl never returns a relative path).
+  const match = prefix.replace(/^https?:\/\//, "").replace(/-$/, "") || undefined;
+  return getPublicUrl(name, { prefix: match, domain });
+}
+
 /** All service names */
 export const SERVICE_NAMES = SERVICES.map((s) => s.name);
 

package/src/session.ts

@@ -27,15 +27,42 @@ function isLocalhost(): boolean {
   return prefix.includes("localhost");
 }
 
+/**
+ * Cookie domain scope (#1069 Phase 1).
+ *
+ * `SESSION_COOKIE_SCOPE` controls whether the deployed session cookie is a
+ * shared parent-domain cookie or a host-only cookie:
+ *   - unset / "domain" (default): current behavior — `domain: ".imajin.ai"`,
+ *     readable by every `*.imajin.ai` subdomain. Nothing changes unless this
+ *     is explicitly set.
+ *   - "host": omit the `domain` attribute entirely, so the cookie is scoped
+ *     to the exact host that set it and is NOT sent to other subdomains.
+ *     Apps that relied on reading the shared cookie must adopt scoped app
+ *     tokens first (see `requireSessionOrAppToken` in `@ima-jin/auth` and
+ *     `docs/security/cookie-isolation.md`) before this is flipped for real.
+ *
+ * This flag is a primitive for the staged rollout described in
+ * `docs/security/cookie-isolation.md` — flipping it is a separate, later
+ * phase, not part of shipping the primitive itself.
+ */
+function isHostScoped(): boolean {
+  if (typeof process === "undefined") return false;
+  return process.env.SESSION_COOKIE_SCOPE === "host";
+}
+
 /** Cookie options for cross-subdomain sessions.
  *  When called with no argument, auto-detects from IMAJIN_ENV (same logic as getSessionCookieName).
  *  Accepts optional "dev" | "prod" override for explicit control.
  *
  *  Localhost-aware: when SERVICE_PREFIX contains "localhost", uses
  *  settings compatible with HTTP on localhost (no domain, not secure, lax sameSite).
+ *
+ *  See {@link isHostScoped} for the `SESSION_COOKIE_SCOPE=host` opt-in that
+ *  narrows the deployed cookie to host-only instead of `.imajin.ai`.
  */
 export function getSessionCookieOptions(env?: "dev" | "prod") {
   const local = isLocalhost();
+  const omitDomain = local || isHostScoped();
   return {
     name: getSessionCookieName(env),
     options: {
@@ -43,7 +70,7 @@ export function getSessionCookieOptions(env?: "dev" | "prod") {
       secure: !local,
       sameSite: local ? ("lax" as const) : ("none" as const),
       path: "/",
-      ...(local ? {} : { domain: ".imajin.ai" }),
+      ...(omitDomain ? {} : { domain: ".imajin.ai" }),
       maxAge: 60 * 60 * 24, // 24 hours
     },
   };