@ima-jin/config 0.8.0 → 0.8.15

package/dist/index.cjs

@@ -21,6 +21,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   ALLOWED_FRAME_ORIGINS: () => ALLOWED_FRAME_ORIGINS,
+  APP_DISPLAY_NAME: () => APP_DISPLAY_NAME,
   HANDLE_ALLOWED_CHARS: () => HANDLE_ALLOWED_CHARS,
   HANDLE_ERROR: () => HANDLE_ERROR,
   HANDLE_INPUT_PATTERN: () => HANDLE_INPUT_PATTERN,
@@ -94,12 +95,15 @@ __export(index_exports, {
   eventsCreatePath: () => eventsCreatePath,
   eventsDashboardPath: () => eventsDashboardPath,
   getClientIP: () => getClientIP,
+  getForestScopeConfig: () => getForestScopeConfig,
+  getNodeSelf: () => getNodeSelf,
   getPort: () => getPort,
   getPublicUrl: () => getPublicUrl,
   getService: () => getService,
   getServiceUrl: () => getServiceUrl,
   getSessionCookieName: () => getSessionCookieName,
   getSessionCookieOptions: () => getSessionCookieOptions,
+  hasRegistryServiceUrl: () => hasRegistryServiceUrl,
   healthPath: () => healthPath,
   isAllowedOrigin: () => isAllowedOrigin,
   isReservedHandle: () => isReservedHandle,
@@ -140,8 +144,10 @@ __export(index_exports, {
   rateLimit: () => rateLimit,
   registryDocsPath: () => registryDocsPath,
   registryPath: () => registryPath,
+  registryServiceUrl: () => registryServiceUrl,
   servicesByTier: () => servicesByTier,
   servicesByVisibility: () => servicesByVisibility,
+  standaloneDashboardMiddleware: () => standaloneDashboardMiddleware,
   subscribePath: () => subscribePath,
   tier1Headers: () => tier1Headers,
   tier2Headers: () => tier2Headers,
@@ -153,7 +159,7 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/cors.ts
-var import_server = require("next/server");
+var import_server = require("next/server.js");
 var ORIGIN_PATTERN = /^https:\/\/(dev-)?[a-z-]+\.imajin\.ai$/;
 var LOCAL_PATTERN = /^http:\/\/localhost:\d+$/;
 var ALLOWED_FRAME_ORIGINS = "https://*.imajin.ai https://imajin.ai";
@@ -170,7 +176,7 @@ function corsHeaders(request) {
     "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"
   };
 }
@@ -190,26 +196,8 @@ function validateOrigin(request) {
   return isAllowedOrigin(origin);
 }
 
-// src/security-headers.ts
-function buildFrameAncestors() {
-  const local = process.env.NODE_ENV !== "production" ? " http://localhost:*" : "";
-  return `frame-ancestors 'self' ${ALLOWED_FRAME_ORIGINS}${local}`;
-}
-function tier1Headers() {
-  return [
-    { key: "Content-Security-Policy", value: "frame-ancestors 'none'" },
-    { key: "X-Frame-Options", value: "DENY" }
-  ];
-}
-function tier2Headers() {
-  return [{ key: "Content-Security-Policy", value: buildFrameAncestors() }];
-}
-function tier3Headers() {
-  return [
-    { key: "X-Content-Type-Options", value: "nosniff" },
-    { key: "Referrer-Policy", value: "strict-origin-when-cross-origin" }
-  ];
-}
+// src/dashboard-redirect-middleware.ts
+var import_server2 = require("next/server.js");
 
 // src/services.ts
 var SERVICES = [
@@ -223,6 +211,11 @@ var SERVICES = [
   { name: "media", label: "Media", icon: "\u{1F4C1}", description: "Files, images, and .fair attribution", devPort: 3e3, prodPort: 7e3, schema: "media", tier: "core", visibility: "authenticated", category: "kernel" },
   { name: "registry", label: "Registry", icon: "\u{1F4E1}", description: "Service registry and DFOS relay", devPort: 3e3, prodPort: 7e3, schema: "registry", tier: "core", visibility: "public", category: "kernel" },
   { name: "notify", label: "Notify", icon: "\u{1F514}", description: "Notifications and preferences", devPort: 3e3, prodPort: 7e3, schema: "notify", tier: "core", visibility: "internal", category: "kernel" },
+  { name: "usage", label: "Usage", icon: "\u{1F4CA}", description: "Inference cost ledger \u2014 incurred, billed, drift, signed rollup", devPort: 3e3, prodPort: 7e3, schema: "usage", tier: "core", visibility: "authenticated", category: "kernel" },
+  { name: "calendar", label: "Calendar", icon: "\u{1F4C5}", description: "Temporal entries \u2014 availability, meetings, events, and reminders", devPort: 3e3, prodPort: 7e3, schema: null, tier: "core", visibility: "authenticated", category: "kernel" },
+  { name: "jin", label: "Jin", icon: "\u{1F9ED}", description: "Operator dashboard \u2014 signed approvals, proposals, and usage feed", devPort: 3e3, prodPort: 7e3, schema: "operator", tier: "core", visibility: "internal", category: "kernel" },
+  { name: "google", label: "Google Workspace", icon: "\u{1F4E8}", description: "Gmail/Calendar/Drive/Meet connector \u2014 OAuth2 auth-code, sealed refresh token", devPort: 3e3, prodPort: 7e3, schema: null, tier: "core", visibility: "authenticated", category: "kernel" },
+  { name: "vault", label: "Vault", icon: "\u{1F510}", description: "Sealed secrets, delegation grants, and vault-minted service credentials", devPort: 3e3, prodPort: 7e3, schema: null, tier: "core", visibility: "internal", category: "kernel" },
   // Core apps — separate processes
   { name: "events", label: "Events", icon: "\u{1F3AB}", description: "Event creation, ticketing, and management", devPort: 3006, prodPort: 7006, schema: "events", tier: "core", visibility: "public", category: "core" },
   // Imajin apps
@@ -236,7 +229,8 @@ var SERVICES = [
   { name: "github", label: "GitHub", icon: "\u{1F419}", description: "Source code", devPort: 3e3, prodPort: 7e3, schema: "public", tier: "core", visibility: "public", category: "meta", externalUrl: "https://github.com/ima-jin/imajin-ai" },
   { name: "docs", label: "Docs", icon: "\u{1F4C4}", description: "API documentation", devPort: 3e3, prodPort: 7e3, 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: "\u{1F916}", description: "Telegram broker agent \u2014 conversational surface for social coordination (#1101)", devPort: 0, prodPort: 0, schema: null, tier: "core", visibility: "internal", category: "infrastructure" }
+  { name: "broker-agent", label: "Broker Agent", icon: "\u{1F916}", description: "Telegram broker agent \u2014 conversational surface for social coordination (#1101)", devPort: 0, prodPort: 0, schema: null, tier: "core", visibility: "internal", category: "infrastructure" },
+  { name: "corpus", label: "Corpus", icon: "\u{1F50E}", 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.
 ];
@@ -322,6 +316,46 @@ function buildServiceUrlMap(env, mode = "dev") {
   return map;
 }
 
+// src/dashboard-redirect-middleware.ts
+function standaloneDashboardMiddleware(request, { service, cors = true }) {
+  if (request.nextUrl.pathname === "/dashboard") {
+    const hubUrl = new URL(`${buildPublicUrlAbsolute("kernel")}/auth/${service}`);
+    hubUrl.search = request.nextUrl.search;
+    return import_server2.NextResponse.redirect(hubUrl, 308);
+  }
+  if (!cors) {
+    return import_server2.NextResponse.next();
+  }
+  if (request.method === "OPTIONS") {
+    return new import_server2.NextResponse(null, { status: 204, headers: corsHeaders(request) });
+  }
+  return withCors(import_server2.NextResponse.next(), request);
+}
+
+// src/security-headers.ts
+function buildFrameAncestors() {
+  const local = process.env.NODE_ENV !== "production" ? " http://localhost:*" : "";
+  return `frame-ancestors 'self' ${ALLOWED_FRAME_ORIGINS}${local}`;
+}
+function tier1Headers() {
+  return [
+    { key: "Content-Security-Policy", value: "frame-ancestors 'none'" },
+    { key: "X-Frame-Options", value: "DENY" }
+  ];
+}
+function tier2Headers() {
+  return [{ key: "Content-Security-Policy", value: buildFrameAncestors() }];
+}
+function tier3Headers() {
+  return [
+    { key: "X-Content-Type-Options", value: "nosniff" },
+    { key: "Referrer-Policy", value: "strict-origin-when-cross-origin" }
+  ];
+}
+
+// src/brand.ts
+var APP_DISPLAY_NAME = "imajin (\u03B1)";
+
 // src/session.ts
 function getSessionCookieName(env) {
   const resolved = env ?? (typeof process !== "undefined" && (process.env.IMAJIN_ENV === "dev" || process.env.NODE_ENV === "development") ? "dev" : "prod");
@@ -333,8 +367,13 @@ function isLocalhost() {
   const prefix = process.env.NEXT_PUBLIC_SERVICE_PREFIX ?? "";
   return prefix.includes("localhost");
 }
+function isHostScoped() {
+  if (typeof process === "undefined") return false;
+  return process.env.SESSION_COOKIE_SCOPE === "host";
+}
 function getSessionCookieOptions(env) {
   const local = isLocalhost();
+  const omitDomain = local || isHostScoped();
   return {
     name: getSessionCookieName(env),
     options: {
@@ -342,7 +381,7 @@ function getSessionCookieOptions(env) {
       secure: !local,
       sameSite: local ? "lax" : "none",
       path: "/",
-      ...local ? {} : { domain: ".imajin.ai" },
+      ...omitDomain ? {} : { domain: ".imajin.ai" },
       maxAge: 60 * 60 * 24
       // 24 hours
     }
@@ -401,11 +440,67 @@ function getClientIP(request) {
   return "127.0.0.1";
 }
 
+// src/registry-service-url.ts
+var warnedAboutLegacyRegistryUrl = false;
+function registryServiceUrl() {
+  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 \u2014 set REGISTRY_SERVICE_URL");
+      warnedAboutLegacyRegistryUrl = true;
+    }
+    return process.env.REGISTRY_URL;
+  }
+  return `http://localhost:${process.env.PORT || 3e3}/registry`;
+}
+function hasRegistryServiceUrl() {
+  return Boolean(process.env.REGISTRY_SERVICE_URL || process.env.REGISTRY_URL);
+}
+
+// src/node-self.ts
+async function getNodeSelf() {
+  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} \u2014 check REGISTRY_SERVICE_URL`);
+      return null;
+    }
+    return await res.json();
+  } catch (err) {
+    console.warn(`[config] getNodeSelf: fetch failed for ${url} \u2014 ${err instanceof Error ? err.message : String(err)}`);
+    return null;
+  }
+}
+
+// src/forest-config.ts
+function profileBaseUrl() {
+  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`;
+}
+async function getForestScopeConfig(groupDid) {
+  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();
+    return { scopeFeeBps: typeof data?.scopeFeeBps === "number" ? data.scopeFeeBps : null };
+  } catch (err) {
+    console.warn(`[config] getForestScopeConfig: fetch failed for ${url} \u2014 ${err instanceof Error ? err.message : String(err)}`);
+    return null;
+  }
+}
+
 // src/handles.ts
 var HANDLE_PATTERN = /^[a-z0-9._-]{3,30}$/;
 var HANDLE_EDGE = /^[.-]|[.-]$/;
 var HANDLE_CONSECUTIVE = /[.-]{2}/;
-var HANDLE_INPUT_PATTERN = "[a-z0-9._\\-]{3,30}";
+var HANDLE_INPUT_PATTERN = String.raw`[a-z0-9._\-]{3,30}`;
 var HANDLE_ALLOWED_CHARS = /[^a-z0-9._-]/g;
 var RESERVED_HANDLES = /* @__PURE__ */ new Set([
   "admin",
@@ -551,6 +646,7 @@ var notifySettingsPath = () => `/notify/settings`;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ALLOWED_FRAME_ORIGINS,
+  APP_DISPLAY_NAME,
   HANDLE_ALLOWED_CHARS,
   HANDLE_ERROR,
   HANDLE_INPUT_PATTERN,
@@ -624,12 +720,15 @@ var notifySettingsPath = () => `/notify/settings`;
   eventsCreatePath,
   eventsDashboardPath,
   getClientIP,
+  getForestScopeConfig,
+  getNodeSelf,
   getPort,
   getPublicUrl,
   getService,
   getServiceUrl,
   getSessionCookieName,
   getSessionCookieOptions,
+  hasRegistryServiceUrl,
   healthPath,
   isAllowedOrigin,
   isReservedHandle,
@@ -670,8 +769,10 @@ var notifySettingsPath = () => `/notify/settings`;
   rateLimit,
   registryDocsPath,
   registryPath,
+  registryServiceUrl,
   servicesByTier,
   servicesByVisibility,
+  standaloneDashboardMiddleware,
   subscribePath,
   tier1Headers,
   tier2Headers,

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { NextRequest, NextResponse } from 'next/server';
+import { NextRequest, NextResponse } from 'next/server.js';
 
 /**
  * CSP host-source list corresponding to ORIGIN_PATTERN (prod).
@@ -12,6 +12,39 @@ declare function corsOptions(request: NextRequest): NextResponse;
 declare function withCors(response: NextResponse, request: NextRequest): NextResponse;
 declare function validateOrigin(request: NextRequest): boolean;
 
+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.
+ */
+declare function standaloneDashboardMiddleware(request: NextRequest, { service, cors }: StandaloneDashboardMiddlewareOptions): NextResponse;
+
 type HeaderEntry = {
     key: string;
     value: string;
@@ -35,9 +68,32 @@ declare function tier2Headers(): HeaderEntry[];
 declare function tier3Headers(): HeaderEntry[];
 
 /**
- * Canonical service manifest — single source of truth for all Imajin services.
+ * Human-facing product display name.
+ *
+ * This is the ONLY place the "(α)" (alpha) stage marker lives — flip it here
+ * (e.g. to "(β)" or drop it for GA) and every consumer (BuildInfo, nav bars,
+ * page titles/metadata, auth screens, email templates, etc.) picks it up.
  *
- * Consumers: registry specs, Caddy config, pm2 ecosystem, docs sync, shared nav.
+ * Do NOT use this for DIDs, URLs, package names, event names, localStorage
+ * keys, env vars, or any other code identifier — those stay as literal
+ * 'imajin' strings. This constant is display-text only.
+ */
+declare const APP_DISPLAY_NAME = "imajin (\u03B1)";
+
+/**
+ * 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.
+ *
+ * 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.
  */
 type ServiceTier = "core" | "imajin";
 type ServiceVisibility = "public" | "authenticated" | "creator" | "internal";
@@ -138,6 +194,9 @@ declare const SESSION_COOKIE_NAME: string;
  *
  *  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`.
  */
 declare function getSessionCookieOptions(env?: "dev" | "prod"): {
     name: string;
@@ -189,17 +248,17 @@ declare function apiUrl(path: string): string;
  *
  * 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:
+ * For server-side service-to-service calls, forward the X-Correlation-Id header
+ * so the full request chain shares one ID. apiFetch is browser-side too, so it
+ * can't read headers here automatically — 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.
+ * see: automatic correlationId forwarding on outbound apiFetch/fetch calls from
+ * withLogger handlers is not yet wired up.
  */
 declare function apiFetch(path: string, init?: RequestInit): Promise<Response>;
 
@@ -213,6 +272,89 @@ declare function rateLimit(key: string, limit: number, windowMs: number): {
 };
 declare function getClientIP(request: Request): string;
 
+/**
+ * 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).
+ */
+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).
+ */
+declare function getNodeSelf(): Promise<NodeSelfInfo | null>;
+
+/**
+ * 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.
+ */
+declare function registryServiceUrl(): string;
+/**
+ * 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.
+ */
+declare function hasRegistryServiceUrl(): boolean;
+
+/**
+ * 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.
+ */
+interface ForestScopeConfig {
+    /** Group's configured revenue-share fee, in basis points (0-500). Null if unset. */
+    scopeFeeBps: number | null;
+}
+/**
+ * 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.
+ */
+declare function getForestScopeConfig(groupDid: string): Promise<ForestScopeConfig | null>;
+
 /**
  * Handle validation and normalization.
  *
@@ -223,7 +365,7 @@ declare function getClientIP(request: Request): string;
 /** 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}";
+declare const HANDLE_INPUT_PATTERN: string;
 /** Characters allowed in handles — use in onChange filters */
 declare const HANDLE_ALLOWED_CHARS: RegExp;
 /** Reserved handles that cannot be claimed */
@@ -340,4 +482,4 @@ 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 };
+export { ALLOWED_FRAME_ORIGINS, APP_DISPLAY_NAME, type ForestScopeConfig, HANDLE_ALLOWED_CHARS, HANDLE_ERROR, HANDLE_INPUT_PATTERN, HANDLE_PATTERN, type NodeSelfInfo, RESERVED_HANDLES, SERVICES, SERVICE_NAMES, SESSION_COOKIE_NAME, type ServiceCategory, type ServiceDefinition, type ServiceTier, type ServiceVisibility, type StandaloneDashboardMiddlewareOptions, 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, getForestScopeConfig, getNodeSelf, getPort, getPublicUrl, getService, getServiceUrl, getSessionCookieName, getSessionCookieOptions, hasRegistryServiceUrl, 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, registryServiceUrl, servicesByTier, servicesByVisibility, standaloneDashboardMiddleware, subscribePath, tier1Headers, tier2Headers, tier3Headers, validateOrigin, whitepaperPath, withCors };