@ima-jin/config 1.0.0

package/src/index.ts

@@ -0,0 +1,150 @@
+export { isAllowedOrigin, corsHeaders, corsOptions, withCors, validateOrigin } from "./cors";
+
+export {
+  SERVICES,
+  SERVICE_NAMES,
+  getService,
+  getPort,
+  getServiceUrl,
+  getPublicUrl,
+  buildPublicUrl,
+  servicesByTier,
+  servicesByVisibility,
+  buildServiceUrlMap,
+} from "./services";
+export type {
+  ServiceDefinition,
+  ServiceTier,
+  ServiceVisibility,
+  ServiceCategory,
+} from "./services";
+
+export {
+  SESSION_COOKIE_NAME,
+  getSessionCookieName,
+  getSessionCookieOptions,
+} from "./session";
+
+export { apiFetch, apiUrl } from "./base-path";
+
+export {
+  HANDLE_PATTERN,
+  HANDLE_INPUT_PATTERN,
+  HANDLE_ALLOWED_CHARS,
+  HANDLE_ERROR,
+  RESERVED_HANDLES,
+  isValidHandle,
+  isReservedHandle,
+  normalizeHandleInput,
+} from "./handles";
+
+export {
+  // Event routes
+  eventPath,
+  eventEditPath,
+  eventAdminPath,
+  eventRegisterPath,
+  eventMyTicketsPath,
+  eventCheckoutSuccessPath,
+  eventsDashboardPath,
+  eventsCreatePath,
+  eventsCheckoutSuccessPath,
+  eventsAdminListPath,
+  eventUrl,
+  eventEditUrl,
+  eventRegisterUrl,
+  eventMyTicketsUrl,
+  // Profile routes
+  profilePath,
+  profileEditPath,
+  profileLoginPath,
+  profileRegisterPath,
+  profileUrl,
+  // Auth routes
+  authLoginPath,
+  authRegisterPath,
+  authOnboardPath,
+  authSettingsPath,
+  authSecurityPath,
+  authGroupSettingsPath,
+  authGroupsPath,
+  authNewGroupPath,
+  authAgentsPath,
+  authAppsPath,
+  authAttestationsPath,
+  authAuthorizePath,
+  authDeveloperAppsPath,
+  authDeveloperAppPath,
+  authMembersPath,
+  authNotificationsPath,
+  authStubsPath,
+  authNewStubPath,
+  // Chat routes
+  chatConversationsPath,
+  chatConversationPath,
+  chatPath,
+  // Connections routes
+  connectionsPath,
+  connectionsInvitePath,
+  connectionsPodPath,
+  // Pay routes
+  payPath,
+  payHistoryPath,
+  payPayoutsPath,
+  payTopupPath,
+  payTopupSuccessPath,
+  // Media routes
+  mediaPath,
+  // Learn routes
+  learnCoursePath,
+  learnCourseLessonPath,
+  learnCoursePresentPath,
+  learnDashboardPath,
+  learnCourseDashboardPath,
+  learnCourseStudentsPath,
+  learnHandlePath,
+  // Coffee routes
+  coffeeHandlePath,
+  coffeeDashboardPath,
+  coffeeEditPath,
+  coffeeSuccessPath,
+  // Dykil routes
+  dykilHandlePath,
+  dykilSurveyPath,
+  dykilCreatePath,
+  dykilDashboardPath,
+  dykilResultsPath,
+  dykilEmbedPath,
+  // Links routes
+  linksHandlePath,
+  linksDashboardPath,
+  linksEditPath,
+  // Market routes
+  marketListingPath,
+  marketListingEditPath,
+  marketNewListingPath,
+  marketSellerPath,
+  marketCheckoutSuccessPath,
+  marketDashboardPath,
+  marketSettingsPath,
+  // Articles
+  articlesPath,
+  articleAuthorPath,
+  articlePath,
+  // Kernel / other
+  registryPath,
+  registryDocsPath,
+  buildPath,
+  bumpPath,
+  bugsPath,
+  bugsAdminPath,
+  healthPath,
+  privacyPath,
+  whitepaperPath,
+  subscribePath,
+  developerGuidePath,
+  docsPath,
+  projectPath,
+  notifyPath,
+  notifySettingsPath,
+} from "./routes";

package/src/routes.ts

@@ -0,0 +1,151 @@
+/**
+ * Centralized public route paths.
+ * Every service imports from here — change the prefix once, changes everywhere.
+ *
+ * Note: These are the *public-facing* URL paths (after any proxy/basePath
+ * stripping).  Internal Next.js file paths may differ (e.g. kernel profiles
+ * are in `app/profile/p/[handle]` but the public URL is `/p/[handle]`).
+ */
+
+// ─── Event routes (events.imajin.ai) ───────────────────────────────────────
+export const eventPath = (eventId: string) => `/e/${eventId}`;
+export const eventEditPath = (eventId: string) => `/e/${eventId}/edit`;
+export const eventRegisterPath = (eventId: string, ticketId: string) =>
+  `/e/${eventId}/register/${ticketId}`;
+export const eventMyTicketsPath = (eventId: string) => `/e/${eventId}/my-tickets`;
+export const eventCheckoutSuccessPath = (eventId: string) =>
+  `/e/${eventId}#tickets`;
+export const eventAdminPath = (eventId: string) => `/admin/${eventId}`;
+export const eventsDashboardPath = () => `/dashboard`;
+export const eventsCreatePath = () => `/create`;
+export const eventsCheckoutSuccessPath = () => `/checkout/success`;
+export const eventsAdminListPath = () => `/admin`;
+
+// Event full URL builders (for cross-service links, emails, etc.)
+export const eventUrl = (baseUrl: string, eventId: string) =>
+  `${baseUrl}/e/${eventId}`;
+export const eventEditUrl = (baseUrl: string, eventId: string) =>
+  `${baseUrl}/e/${eventId}/edit`;
+export const eventRegisterUrl = (
+  baseUrl: string,
+  eventId: string,
+  ticketId: string
+) => `${baseUrl}/e/${eventId}/register/${ticketId}`;
+export const eventMyTicketsUrl = (baseUrl: string, eventId: string) =>
+  `${baseUrl}/e/${eventId}/my-tickets`;
+
+// ─── Profile routes (profile.imajin.ai) ────────────────────────────────────
+export const profilePath = (handle: string) => `/p/${handle}`;
+export const profileEditPath = () => `/p/edit`;
+export const profileLoginPath = () => `/profile/login`;
+export const profileRegisterPath = () => `/profile/register`;
+
+export const profileUrl = (baseUrl: string, handle: string) =>
+  `${baseUrl}/p/${handle}`;
+
+// ─── Auth routes (auth.imajin.ai) ──────────────────────────────────────────
+export const authLoginPath = () => `/auth/login`;
+export const authRegisterPath = () => `/auth/register`;
+export const authOnboardPath = () => `/auth/onboard`;
+export const authSettingsPath = () => `/auth/settings`;
+export const authSecurityPath = () => `/auth/settings/security`;
+export const authGroupSettingsPath = (groupDid: string) =>
+  `/auth/groups/${groupDid}/settings`;
+export const authGroupsPath = () => `/auth/groups`;
+export const authNewGroupPath = () => `/auth/groups/new`;
+export const authAgentsPath = () => `/auth/agents`;
+export const authAppsPath = () => `/auth/apps`;
+export const authAttestationsPath = () => `/auth/attestations`;
+export const authAuthorizePath = () => `/auth/authorize`;
+export const authDeveloperAppsPath = () => `/auth/developer/apps`;
+export const authDeveloperAppPath = (appId: string) =>
+  `/auth/developer/apps/${appId}`;
+export const authMembersPath = () => `/auth/members`;
+export const authNotificationsPath = () => `/auth/notifications`;
+export const authStubsPath = (did: string) => `/auth/stubs/${did}`;
+export const authNewStubPath = () => `/auth/stubs/new`;
+
+// ─── Chat routes (chat.imajin.ai) ──────────────────────────────────────────
+export const chatConversationsPath = () => `/chat/conversations`;
+export const chatConversationPath = (type: string, slug: string) =>
+  `/chat/conversations/${type}/${slug}`;
+export const chatPath = () => `/chat`;
+
+// ─── Connections routes (connections.imajin.ai) ────────────────────────────
+export const connectionsPath = () => `/connections`;
+export const connectionsInvitePath = (did: string, code: string) =>
+  `/connections/invite/${did}/${code}`;
+export const connectionsPodPath = (id: string) => `/connections/pods/${id}`;
+
+// ─── Pay routes (pay.imajin.ai) ────────────────────────────────────────────
+export const payPath = () => `/pay`;
+export const payHistoryPath = () => `/pay/history`;
+export const payPayoutsPath = () => `/pay/payouts`;
+export const payTopupPath = () => `/pay/topup`;
+export const payTopupSuccessPath = () => `/pay/topup/success`;
+
+// ─── Media routes (media.imajin.ai) ────────────────────────────────────────
+export const mediaPath = () => `/media`;
+
+// ─── Learn routes (learn.imajin.ai) ────────────────────────────────────────
+export const learnCoursePath = (slug: string) => `/course/${slug}`;
+export const learnCourseLessonPath = (slug: string, lessonId: string) =>
+  `/course/${slug}/${lessonId}`;
+export const learnCoursePresentPath = (slug: string) => `/course/${slug}/present`;
+export const learnDashboardPath = () => `/dashboard`;
+export const learnCourseDashboardPath = (slug: string) => `/dashboard/${slug}`;
+export const learnCourseStudentsPath = (slug: string) =>
+  `/dashboard/${slug}/students`;
+export const learnHandlePath = (handle: string) => `/${handle}`;
+
+// ─── Coffee routes (coffee.imajin.ai) ──────────────────────────────────────
+export const coffeeHandlePath = (handle: string) => `/${handle}`;
+export const coffeeDashboardPath = () => `/dashboard`;
+export const coffeeEditPath = () => `/edit`;
+export const coffeeSuccessPath = () => `/success`;
+
+// ─── Dykil routes (dykil.imajin.ai) ────────────────────────────────────────
+export const dykilHandlePath = (handle: string) => `/${handle}`;
+export const dykilSurveyPath = (handle: string, surveyId: string) =>
+  `/${handle}/${surveyId}`;
+export const dykilCreatePath = () => `/create`;
+export const dykilDashboardPath = () => `/dashboard`;
+export const dykilResultsPath = (id: string) => `/survey/${id}/results`;
+export const dykilEmbedPath = (surveyId: string) => `/embed/${surveyId}`;
+
+// ─── Links routes (links.imajin.ai) ────────────────────────────────────────
+export const linksHandlePath = (handle: string) => `/${handle}`;
+export const linksDashboardPath = () => `/dashboard`;
+export const linksEditPath = () => `/edit`;
+
+// ─── Market routes (market.imajin.ai) ──────────────────────────────────────
+export const marketListingPath = (id: string) => `/listings/${id}`;
+export const marketListingEditPath = (id: string) => `/listings/${id}/edit`;
+export const marketNewListingPath = () => `/listings/new`;
+export const marketSellerPath = (handle: string) => `/seller/${handle}`;
+export const marketCheckoutSuccessPath = () => `/checkout/success`;
+export const marketDashboardPath = () => `/dashboard`;
+export const marketSettingsPath = () => `/settings`;
+
+// ─── Kernel / articles ─────────────────────────────────────────────────────
+export const articlesPath = () => `/articles`;
+export const articleAuthorPath = (handle: string) => `/articles/${handle}`;
+export const articlePath = (handle: string, slug: string) =>
+  `/articles/${handle}/${slug}`;
+
+// ─── Kernel / other ────────────────────────────────────────────────────────
+export const registryPath = () => `/registry`;
+export const registryDocsPath = () => `/registry/docs`;
+export const buildPath = () => `/build`;
+export const bumpPath = () => `/bump`;
+export const bugsPath = () => `/bugs`;
+export const bugsAdminPath = () => `/bugs/admin`;
+export const healthPath = () => `/health`;
+export const privacyPath = () => `/privacy`;
+export const whitepaperPath = () => `/whitepaper`;
+export const subscribePath = () => `/subscribe`;
+export const developerGuidePath = () => `/developer-guide`;
+export const docsPath = () => `/docs`;
+export const projectPath = () => `/project`;
+export const notifyPath = () => `/notify`;
+export const notifySettingsPath = () => `/notify/settings`;

package/src/services.ts

@@ -0,0 +1,196 @@
+/**
+ * Canonical service manifest — single source of truth for all Imajin services.
+ *
+ * Consumers: registry specs, Caddy config, pm2 ecosystem, docs sync, shared nav.
+ */
+
+export type ServiceTier = "core" | "imajin";
+export type ServiceVisibility = "public" | "authenticated" | "creator" | "internal";
+export type ServiceCategory = "kernel" | "core" | "creator" | "developer" | "infrastructure" | "meta";
+
+export interface ServiceDefinition {
+  /** Subdomain / app directory name */
+  name: string;
+  /** Human-readable label */
+  label: string;
+  /** Description */
+  description: string;
+  /** Emoji icon */
+  icon: string;
+  /** Dev port (3xxx) */
+  devPort: number;
+  /** Prod port (7xxx) */
+  prodPort: number;
+  /** Postgres schema name (null if no DB) */
+  schema: string | null;
+  /** Deployment tier */
+  tier: ServiceTier;
+  /** Visibility in launcher / nav */
+  visibility: ServiceVisibility;
+  /** Grouping category */
+  category: ServiceCategory;
+  /** External URL override (bypasses subdomain convention) */
+  externalUrl?: string;
+  /** Path on www service (env-aware — resolves against www's URL at runtime) */
+  wwwPath?: string;
+}
+
+export const SERVICES: readonly ServiceDefinition[] = [
+  // Kernel services — individually visible, all run on the kernel process (port 3000/7000)
+  { name: "kernel",      label: "Home",        icon: "🏠", description: "Network home — launcher, articles, stats",           devPort: 3000, prodPort: 7000, schema: null,          tier: "core",   visibility: "public",        category: "kernel" },
+  { name: "auth",        label: "Identity",    icon: "🔑", description: "Authentication, keys, and identity management",      devPort: 3000, prodPort: 7000, schema: "auth",        tier: "core",   visibility: "authenticated", category: "kernel" },
+  { name: "profile",     label: "Profile",     icon: "👤", description: "Your profile, settings, and display preferences",    devPort: 3000, prodPort: 7000, schema: "profile",     tier: "core",   visibility: "authenticated", category: "kernel" },
+  { name: "connections", label: "Connections", icon: "🤝", description: "Your network — people you know and trust",           devPort: 3000, prodPort: 7000, schema: "connections", tier: "core",   visibility: "authenticated", category: "kernel" },
+  { name: "chat",        label: "Chat",        icon: "💬", description: "Conversations and group messaging",                  devPort: 3000, prodPort: 7000, schema: "chat",        tier: "core",   visibility: "authenticated", category: "kernel" },
+  { name: "pay",         label: "Wallet",      icon: "💰", description: "Payments, settlements, and MJN balance",             devPort: 3000, prodPort: 7000, schema: "pay",         tier: "core",   visibility: "authenticated", category: "kernel" },
+  { 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" },
+
+  // 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" },
+
+  // Imajin apps
+  { name: "coffee",      label: "Coffee",      icon: "☕", description: "Tipping and creator support pages",                 devPort: 3100, prodPort: 7100, schema: "coffee",      tier: "imajin", visibility: "creator",       category: "creator" },
+  { name: "dykil",       label: "Surveys",     icon: "📋", description: "Surveys and do-you-know-if-I-like polls",           devPort: 3101, prodPort: 7101, schema: "dykil",       tier: "imajin", visibility: "creator",       category: "creator" },
+  { name: "links",       label: "Links",       icon: "🔗", description: "Link-in-bio pages and click tracking",              devPort: 3102, prodPort: 7102, schema: "links",       tier: "imajin", visibility: "creator",       category: "creator" },
+  { name: "learn",       label: "Learn",       icon: "📚", description: "Courses, lessons, and learning progress",           devPort: 3103, prodPort: 7103, schema: "learn",       tier: "imajin", visibility: "public",        category: "core" },
+  { name: "market",      label: "Market",      icon: "🏪", description: "Local commerce — buy and sell with trust",          devPort: 3104, prodPort: 7104, schema: "market",      tier: "imajin", visibility: "public",        category: "core" },
+
+  // Meta — project info and external resources surfaced in the launcher
+  { name: 'project',     label: 'Project',     icon: '📖', description: 'Thesis, whitepaper, essays, RFCs',                  devPort: 3000, prodPort: 7000, schema: "public",      tier: 'core',   visibility: 'public',        category: 'meta', wwwPath: '/project' },
+  { 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' },
+
+  // 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[];
+
+// ── Lookup helpers ──────────────────────────────────────────────────────────
+
+/** Get a service definition by name */
+export function getService(name: string): ServiceDefinition | undefined {
+  return SERVICES.find((s) => s.name === name);
+}
+
+/** 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;
+}
+
+/** Get internal URL for a service (server-side calls) */
+export function getServiceUrl(name: string, env: "dev" | "prod" = "dev"): string | undefined {
+  const port = getPort(name, env);
+  return port ? `http://localhost:${port}` : undefined;
+}
+
+/** Get the public URL for a service.
+ *  Localhost-aware: if domain contains "localhost" or prefix is "http://localhost:",
+ *  returns http://localhost:{devPort} using the canonical port map.
+ */
+export function getPublicUrl(
+  name: string,
+  options?: { prefix?: string; domain?: string }
+): string {
+  const svc = SERVICES.find((s) => s.name === name);
+
+  // External URL takes absolute priority (e.g. GitHub)
+  if (svc?.externalUrl) return svc.externalUrl;
+
+  const domain = options?.domain || "imajin.ai";
+  const prefix = options?.prefix;
+
+  // wwwPath: resolve against www's URL (env-aware)
+  if (svc?.wwwPath) {
+    const wwwUrl = getPublicUrl("www", options);
+    return `${wwwUrl}${svc.wwwPath}`;
+  }
+
+  // Detect localhost dev environment
+  if (domain.includes("localhost") || prefix?.includes("localhost")) {
+    const port = getPort(name, "dev");
+    return port ? `http://localhost:${port}` : `http://localhost:3000`;
+  }
+
+  // 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(".")) {
+    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}`;
+    return `https://${base}/${name}`;
+  }
+
+  const subdomain = prefix ? `${prefix}-${name}` : name;
+  return `https://${subdomain}.${domain}`;
+}
+
+/**
+ * Build the public URL for a service using raw env vars.
+ * Convenience wrapper around getPublicUrl that handles NEXT_PUBLIC_SERVICE_PREFIX
+ * and NEXT_PUBLIC_DOMAIN directly (no need to strip protocol).
+ *
+ * @example
+ *   buildPublicUrl('www')           → uses env vars, localhost-aware
+ *   buildPublicUrl('auth', prefix, domain) → explicit values
+ */
+export function buildPublicUrl(
+  name: string,
+  servicePrefix?: string,
+  domain?: string
+): string {
+  // Check for explicit NEXT_PUBLIC_{NAME}_URL env var first (kernel single-domain mode)
+  if (!servicePrefix && !domain && typeof process !== "undefined") {
+    const envKey = `NEXT_PUBLIC_${name.toUpperCase()}_URL`;
+    const explicit = process.env[envKey];
+    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";
+
+  // Localhost detection
+  if (p.includes("localhost") || d.includes("localhost")) {
+    const port = getPort(name, "dev");
+    return port ? `http://localhost:${port}` : `http://localhost:3000`;
+  }
+
+  // All services live at /{name} on the same domain (single-node architecture).
+  // Subdomain construction is legacy — only used if explicit prefix/domain args
+  // are passed (e.g. generating external links for a different node).
+  if (!servicePrefix && !domain) {
+    return name === "kernel" ? "" : `/${name}`;
+  }
+
+  // Explicit prefix/domain passed — caller wants a full URL (e.g. cross-node links)
+  const match = p.replace(/^https?:\/\//, "").replace(/-$/, "") || undefined;
+  return getPublicUrl(name, { prefix: match, domain: d });
+}
+
+/** All service names */
+export const SERVICE_NAMES = SERVICES.map((s) => s.name);
+
+/** Services filtered by tier */
+export function servicesByTier(tier: ServiceTier): ServiceDefinition[] {
+  return SERVICES.filter((s) => s.tier === tier);
+}
+
+/** Services filtered by visibility */
+export function servicesByVisibility(visibility: ServiceVisibility): ServiceDefinition[] {
+  return SERVICES.filter((s) => s.visibility === visibility);
+}
+
+/**
+ * Build a map of service name → internal URL from env vars with fallback to port convention.
+ * Env var pattern: `{NAME}_SERVICE_URL` (e.g. `AUTH_SERVICE_URL`)
+ */
+export function buildServiceUrlMap(env: Record<string, string | undefined>, mode: "dev" | "prod" = "dev"): Record<string, string> {
+  const map: Record<string, string> = {};
+  for (const svc of SERVICES) {
+    const envKey = `${svc.name.toUpperCase()}_SERVICE_URL`;
+    const port = mode === "prod" ? svc.prodPort : svc.devPort;
+    map[svc.name] = env[envKey] || `http://localhost:${port}`;
+  }
+  return map;
+}

package/src/session.ts

@@ -0,0 +1,50 @@
+/**
+ * Session cookie configuration — single source of truth.
+ *
+ * Every service that reads or writes the session cookie should import from here
+ * instead of hardcoding 'imajin_session'.
+ */
+
+/** The session cookie name. Use a different name per environment to prevent collisions. */
+export function getSessionCookieName(env?: "dev" | "prod"): string {
+  // Auto-detect from common env vars if not specified
+  const resolved =
+    env ??
+    (typeof process !== "undefined" && (process.env.IMAJIN_ENV === "dev" || process.env.NODE_ENV === "development")
+      ? "dev"
+      : "prod");
+
+  return resolved === "dev" ? "imajin_session_dev" : "imajin_session";
+}
+
+/** Default cookie name — resolves at import time based on environment */
+export const SESSION_COOKIE_NAME = getSessionCookieName();
+
+/** Detect if running on localhost (not deployed to *.imajin.ai) */
+function isLocalhost(): boolean {
+  if (typeof process === "undefined") return false;
+  const prefix = process.env.NEXT_PUBLIC_SERVICE_PREFIX ?? "";
+  return prefix.includes("localhost");
+}
+
+/** 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).
+ */
+export function getSessionCookieOptions(env?: "dev" | "prod") {
+  const local = isLocalhost();
+  return {
+    name: getSessionCookieName(env),
+    options: {
+      httpOnly: true,
+      secure: !local,
+      sameSite: local ? ("lax" as const) : ("none" as const),
+      path: "/",
+      ...(local ? {} : { domain: ".imajin.ai" }),
+      maxAge: 60 * 60 * 24, // 24 hours
+    },
+  };
+}