@ima-jin/config 0.7.0 → 0.8.0

package/dist/index.d.ts

@@ -0,0 +1,343 @@
+import { NextRequest, NextResponse } from 'next/server';
+
+/**
+ * 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.
+ */
+declare const ALLOWED_FRAME_ORIGINS = "https://*.imajin.ai https://imajin.ai";
+declare function isAllowedOrigin(origin: string | null): boolean;
+declare function corsHeaders(request: NextRequest): Record<string, string>;
+declare function corsOptions(request: NextRequest): NextResponse;
+declare function withCors(response: NextResponse, request: NextRequest): NextResponse;
+declare function validateOrigin(request: NextRequest): boolean;
+
+type HeaderEntry = {
+    key: string;
+    value: string;
+};
+/**
+ * Tier 1 — hard deny framing.
+ * Use on credential and auth-sensitive pages that must never be embedded.
+ */
+declare function tier1Headers(): HeaderEntry[];
+/**
+ * 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.
+ */
+declare function tier2Headers(): HeaderEntry[];
+/**
+ * Tier 3 — baseline hardening.
+ * Safe to apply on every route in every app.
+ */
+declare function tier3Headers(): HeaderEntry[];
+
+/**
+ * Canonical service manifest — single source of truth for all Imajin services.
+ *
+ * Consumers: registry specs, Caddy config, pm2 ecosystem, docs sync, shared nav.
+ */
+type ServiceTier = "core" | "imajin";
+type ServiceVisibility = "public" | "authenticated" | "creator" | "internal";
+type ServiceCategory = "kernel" | "core" | "creator" | "developer" | "infrastructure" | "meta";
+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;
+}
+declare const SERVICES: readonly ServiceDefinition[];
+/** Get a service definition by name */
+declare function getService(name: string): ServiceDefinition | undefined;
+/** Get the port for a service in a given environment */
+declare function getPort(name: string, env?: "dev" | "prod"): number | undefined;
+/** Get internal URL for a service (server-side calls) */
+declare function getServiceUrl(name: string, env?: "dev" | "prod"): string | 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.
+ */
+declare function getPublicUrl(name: string, options?: {
+    prefix?: string;
+    domain?: string;
+}): string;
+/**
+ * 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
+ */
+declare function buildPublicUrl(name: string, servicePrefix?: string, domain?: string): string;
+/**
+ * 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)
+ */
+declare function buildPublicUrlAbsolute(name: string): string;
+/** All service names */
+declare const SERVICE_NAMES: string[];
+/** Services filtered by tier */
+declare function servicesByTier(tier: ServiceTier): ServiceDefinition[];
+/** Services filtered by visibility */
+declare function servicesByVisibility(visibility: ServiceVisibility): ServiceDefinition[];
+/**
+ * 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`)
+ */
+declare function buildServiceUrlMap(env: Record<string, string | undefined>, mode?: "dev" | "prod"): Record<string, string>;
+
+/**
+ * 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. */
+declare function getSessionCookieName(env?: "dev" | "prod"): string;
+/** Default cookie name — resolves at import time based on environment */
+declare const SESSION_COOKIE_NAME: string;
+/** 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).
+ */
+declare function getSessionCookieOptions(env?: "dev" | "prod"): {
+    name: string;
+    options: {
+        maxAge: number;
+        domain?: string | undefined;
+        httpOnly: boolean;
+        secure: boolean;
+        sameSite: "lax" | "none";
+        path: string;
+    };
+};
+
+/**
+ * basePath-aware utilities for userspace apps running behind Next.js basePath.
+ *
+ * Next.js `basePath` auto-prefixes <Link> and router.push() but NOT:
+ *   - fetch() calls
+ *   - <a href=""> tags
+ *   - globalThis.location assignments
+ *
+ * These utilities read NEXT_PUBLIC_BASE_PATH (set automatically by Next.js
+ * when basePath is configured) and prepend it where needed.
+ *
+ * Usage:
+ *   import { apiFetch, apiUrl } from '@ima-jin/config';
+ *
+ *   // Instead of: fetch('/api/listings')
+ *   apiFetch('/api/listings')
+ *
+ *   // For <a> tags or globalThis.location:
+ *   <a href={apiUrl('/dashboard')}>Dashboard</a>
+ *   globalThis.location.href = apiUrl('/dashboard');
+ */
+/**
+ * Prepend basePath to any root-relative path.
+ *
+ *   apiUrl('/api/listings')  → '/market/api/listings'  (with basePath: '/market')
+ *   apiUrl('/dashboard')     → '/market/dashboard'
+ *   apiUrl('/api/listings')  → '/api/listings'          (standalone, no basePath)
+ */
+declare function apiUrl(path: string): string;
+/**
+ * basePath-aware fetch wrapper. Drop-in replacement for fetch() with
+ * root-relative paths.
+ *
+ *   apiFetch('/api/listings')           → fetch('/market/api/listings')
+ *   apiFetch('/api/listings', { ... })  → fetch('/market/api/listings', { ... })
+ *
+ * Absolute URLs (http://, https://) are passed through unchanged.
+ *
+ * TODO(WO2/correlation): For server-side service-to-service calls, callers should
+ * forward the X-Correlation-Id header so the full request chain shares one ID.
+ * apiFetch is browser-side too, so we can't read headers here automatically —
+ * instead, pass it explicitly via init.headers when calling from a withLogger handler:
+ *
+ *   apiFetch('/api/something', {
+ *     headers: { 'x-correlation-id': correlationId },
+ *   });
+ *
+ * When WO3 instruments services, each withLogger handler receives correlationId in
+ * ctx and should forward it on any outbound apiFetch/fetch calls.
+ */
+declare function apiFetch(path: string, init?: RequestInit): Promise<Response>;
+
+/**
+ * Simple sliding-window in-memory rate limiter.
+ * Safe for single-process Next.js. Per-worker in multi-worker setups (acceptable).
+ */
+declare function rateLimit(key: string, limit: number, windowMs: number): {
+    limited: boolean;
+    retryAfter: number;
+};
+declare function getClientIP(request: Request): string;
+
+/**
+ * Handle validation and normalization.
+ *
+ * Handles are node-scoped today, globally unique via DFOS chain in the future.
+ * Pattern: lowercase alphanumeric + dots, hyphens, underscores. 3-30 chars.
+ * No leading/trailing dots or hyphens. No consecutive dots or hyphens.
+ */
+/** Regex: the full allowed character set, length enforced */
+declare const HANDLE_PATTERN: RegExp;
+/** HTML input pattern attribute (no anchors, no flags) */
+declare const HANDLE_INPUT_PATTERN = "[a-z0-9._\\-]{3,30}";
+/** Characters allowed in handles — use in onChange filters */
+declare const HANDLE_ALLOWED_CHARS: RegExp;
+/** Reserved handles that cannot be claimed */
+declare const RESERVED_HANDLES: Set<string>;
+/** Validate handle format (does NOT check reserved or uniqueness) */
+declare function isValidHandle(handle: string): boolean;
+/** Check if handle is reserved */
+declare function isReservedHandle(handle: string): boolean;
+/** Normalize input: lowercase, strip disallowed chars */
+declare function normalizeHandleInput(value: string): string;
+/** Validation error message */
+declare const HANDLE_ERROR = "Handle must be 3-30 characters: lowercase letters, numbers, dots, hyphens, underscores";
+
+/**
+ * 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]`).
+ */
+declare const eventPath: (eventId: string) => string;
+declare const eventEditPath: (eventId: string) => string;
+declare const eventRegisterPath: (eventId: string, ticketId: string) => string;
+declare const eventMyTicketsPath: (eventId: string) => string;
+declare const eventCheckoutSuccessPath: (eventId: string) => string;
+declare const eventAdminPath: (eventId: string) => string;
+declare const eventsDashboardPath: () => string;
+declare const eventsCreatePath: () => string;
+declare const eventsCheckoutSuccessPath: () => string;
+declare const eventsAdminListPath: () => string;
+declare const eventUrl: (baseUrl: string, eventId: string) => string;
+declare const eventEditUrl: (baseUrl: string, eventId: string) => string;
+declare const eventRegisterUrl: (baseUrl: string, eventId: string, ticketId: string) => string;
+declare const eventMyTicketsUrl: (baseUrl: string, eventId: string) => string;
+declare const profilePath: (handle: string) => string;
+declare const profileEditPath: () => string;
+declare const profileLoginPath: () => string;
+declare const profileRegisterPath: () => string;
+declare const profileUrl: (baseUrl: string, handle: string) => string;
+declare const authLoginPath: () => string;
+declare const authRegisterPath: () => string;
+declare const authOnboardPath: () => string;
+declare const authSettingsPath: () => string;
+declare const authSecurityPath: () => string;
+declare const authGroupSettingsPath: (groupDid: string) => string;
+declare const authGroupsPath: () => string;
+declare const authNewGroupPath: () => string;
+declare const authAgentsPath: () => string;
+declare const authAppsPath: () => string;
+declare const authAttestationsPath: () => string;
+declare const authAuthorizePath: () => string;
+declare const authDeveloperAppsPath: () => string;
+declare const authDeveloperAppPath: (appId: string) => string;
+declare const authMembersPath: () => string;
+declare const authNotificationsPath: () => string;
+declare const authStubsPath: (did: string) => string;
+declare const authNewStubPath: () => string;
+declare const chatConversationsPath: () => string;
+declare const chatConversationPath: (type: string, slug: string) => string;
+declare const chatPath: () => string;
+declare const connectionsPath: () => string;
+declare const connectionsInvitePath: (did: string, code: string) => string;
+declare const connectionsPodPath: (id: string) => string;
+declare const payPath: () => string;
+declare const payHistoryPath: () => string;
+declare const payPayoutsPath: () => string;
+declare const payTopupPath: () => string;
+declare const payTopupSuccessPath: () => string;
+declare const mediaPath: () => string;
+declare const learnCoursePath: (slug: string) => string;
+declare const learnCourseLessonPath: (slug: string, lessonId: string) => string;
+declare const learnCoursePresentPath: (slug: string) => string;
+declare const learnDashboardPath: () => string;
+declare const learnCourseDashboardPath: (slug: string) => string;
+declare const learnCourseStudentsPath: (slug: string) => string;
+declare const learnHandlePath: (handle: string) => string;
+declare const coffeeHandlePath: (handle: string) => string;
+declare const coffeeDashboardPath: () => string;
+declare const coffeeEditPath: () => string;
+declare const coffeeSuccessPath: () => string;
+declare const dykilHandlePath: (handle: string) => string;
+declare const dykilSurveyPath: (handle: string, surveyId: string) => string;
+declare const dykilCreatePath: () => string;
+declare const dykilDashboardPath: () => string;
+declare const dykilResultsPath: (id: string) => string;
+declare const dykilEmbedPath: (surveyId: string) => string;
+declare const linksHandlePath: (handle: string) => string;
+declare const linksDashboardPath: () => string;
+declare const linksEditPath: () => string;
+declare const marketListingPath: (id: string) => string;
+declare const marketListingEditPath: (id: string) => string;
+declare const marketNewListingPath: () => string;
+declare const marketSellerPath: (handle: string) => string;
+declare const marketCheckoutSuccessPath: () => string;
+declare const marketDashboardPath: () => string;
+declare const marketSettingsPath: () => string;
+declare const articlesPath: () => string;
+declare const articleAuthorPath: (handle: string) => string;
+declare const articlePath: (handle: string, slug: string) => string;
+declare const registryPath: () => string;
+declare const registryDocsPath: () => string;
+declare const buildPath: () => string;
+declare const bumpPath: () => string;
+declare const bugsPath: () => string;
+declare const bugsAdminPath: () => string;
+declare const healthPath: () => string;
+declare const privacyPath: () => string;
+declare const whitepaperPath: () => string;
+declare const subscribePath: () => string;
+declare const developerGuidePath: () => string;
+declare const docsPath: () => string;
+declare const projectPath: () => string;
+declare const notifyPath: () => string;
+declare const notifySettingsPath: () => string;
+
+export { ALLOWED_FRAME_ORIGINS, HANDLE_ALLOWED_CHARS, HANDLE_ERROR, HANDLE_INPUT_PATTERN, HANDLE_PATTERN, RESERVED_HANDLES, SERVICES, SERVICE_NAMES, SESSION_COOKIE_NAME, type ServiceCategory, type ServiceDefinition, type ServiceTier, type ServiceVisibility, apiFetch, apiUrl, articleAuthorPath, articlePath, articlesPath, authAgentsPath, authAppsPath, authAttestationsPath, authAuthorizePath, authDeveloperAppPath, authDeveloperAppsPath, authGroupSettingsPath, authGroupsPath, authLoginPath, authMembersPath, authNewGroupPath, authNewStubPath, authNotificationsPath, authOnboardPath, authRegisterPath, authSecurityPath, authSettingsPath, authStubsPath, bugsAdminPath, bugsPath, buildPath, buildPublicUrl, buildPublicUrlAbsolute, buildServiceUrlMap, bumpPath, chatConversationPath, chatConversationsPath, chatPath, coffeeDashboardPath, coffeeEditPath, coffeeHandlePath, coffeeSuccessPath, connectionsInvitePath, connectionsPath, connectionsPodPath, corsHeaders, corsOptions, developerGuidePath, docsPath, dykilCreatePath, dykilDashboardPath, dykilEmbedPath, dykilHandlePath, dykilResultsPath, dykilSurveyPath, eventAdminPath, eventCheckoutSuccessPath, eventEditPath, eventEditUrl, eventMyTicketsPath, eventMyTicketsUrl, eventPath, eventRegisterPath, eventRegisterUrl, eventUrl, eventsAdminListPath, eventsCheckoutSuccessPath, eventsCreatePath, eventsDashboardPath, getClientIP, getPort, getPublicUrl, getService, getServiceUrl, getSessionCookieName, getSessionCookieOptions, healthPath, isAllowedOrigin, isReservedHandle, isValidHandle, learnCourseDashboardPath, learnCourseLessonPath, learnCoursePath, learnCoursePresentPath, learnCourseStudentsPath, learnDashboardPath, learnHandlePath, linksDashboardPath, linksEditPath, linksHandlePath, marketCheckoutSuccessPath, marketDashboardPath, marketListingEditPath, marketListingPath, marketNewListingPath, marketSellerPath, marketSettingsPath, mediaPath, normalizeHandleInput, notifyPath, notifySettingsPath, payHistoryPath, payPath, payPayoutsPath, payTopupPath, payTopupSuccessPath, privacyPath, profileEditPath, profileLoginPath, profilePath, profileRegisterPath, profileUrl, projectPath, rateLimit, registryDocsPath, registryPath, servicesByTier, servicesByVisibility, subscribePath, tier1Headers, tier2Headers, tier3Headers, validateOrigin, whitepaperPath, withCors };