@character-foundry/character-foundry 0.4.2 → 0.4.3-dev.1766019473

package/dist/federation.d.cts

@@ -41,7 +41,8 @@ declare const CCv3DataSchema: z.ZodObject<{
 				position: z.ZodOptional<z.ZodNullable<z.ZodUnion<[
 					z.ZodEnum<[
 						"before_char",
-						"after_char"
+						"after_char",
+						"in_chat"
 					]>,
 					z.ZodNumber,
 					z.ZodLiteral<"">
@@ -84,7 +85,8 @@ declare const CCv3DataSchema: z.ZodObject<{
 				position: z.ZodOptional<z.ZodNullable<z.ZodUnion<[
 					z.ZodEnum<[
 						"before_char",
-						"after_char"
+						"after_char",
+						"in_chat"
 					]>,
 					z.ZodNumber,
 					z.ZodLiteral<"">
@@ -127,7 +129,8 @@ declare const CCv3DataSchema: z.ZodObject<{
 				position: z.ZodOptional<z.ZodNullable<z.ZodUnion<[
 					z.ZodEnum<[
 						"before_char",
-						"after_char"
+						"after_char",
+						"in_chat"
 					]>,
 					z.ZodNumber,
 					z.ZodLiteral<"">
@@ -172,7 +175,8 @@ declare const CCv3DataSchema: z.ZodObject<{
 				position: z.ZodOptional<z.ZodNullable<z.ZodUnion<[
 					z.ZodEnum<[
 						"before_char",
-						"after_char"
+						"after_char",
+						"in_chat"
 					]>,
 					z.ZodNumber,
 					z.ZodLiteral<"">
@@ -223,7 +227,8 @@ declare const CCv3DataSchema: z.ZodObject<{
 				position: z.ZodOptional<z.ZodNullable<z.ZodUnion<[
 					z.ZodEnum<[
 						"before_char",
-						"after_char"
+						"after_char",
+						"in_chat"
 					]>,
 					z.ZodNumber,
 					z.ZodLiteral<"">
@@ -322,7 +327,8 @@ declare const CCv3DataSchema: z.ZodObject<{
 				position: z.ZodOptional<z.ZodNullable<z.ZodUnion<[
 					z.ZodEnum<[
 						"before_char",
-						"after_char"
+						"after_char",
+						"in_chat"
 					]>,
 					z.ZodNumber,
 					z.ZodLiteral<"">
@@ -397,7 +403,8 @@ declare const CCv3DataSchema: z.ZodObject<{
 				position: z.ZodOptional<z.ZodNullable<z.ZodUnion<[
 					z.ZodEnum<[
 						"before_char",
-						"after_char"
+						"after_char",
+						"in_chat"
 					]>,
 					z.ZodNumber,
 					z.ZodLiteral<"">
@@ -482,7 +489,8 @@ declare const CCv3DataSchema: z.ZodObject<{
 				position: z.ZodOptional<z.ZodNullable<z.ZodUnion<[
 					z.ZodEnum<[
 						"before_char",
-						"after_char"
+						"after_char",
+						"in_chat"
 					]>,
 					z.ZodNumber,
 					z.ZodLiteral<"">
@@ -561,7 +569,8 @@ declare const CCv3DataSchema: z.ZodObject<{
 				position: z.ZodOptional<z.ZodNullable<z.ZodUnion<[
 					z.ZodEnum<[
 						"before_char",
-						"after_char"
+						"after_char",
+						"in_chat"
 					]>,
 					z.ZodNumber,
 					z.ZodLiteral<"">
@@ -619,6 +628,23 @@ declare const CCv3DataSchema: z.ZodObject<{
  * Character Card v3 full structure
  */
 export type CCv3Data = z.infer<typeof CCv3DataSchema>;
+/**
+ * Federation Logger
+ *
+ * Lightweight logger with configurable verbosity and a safe default (warn).
+ * No external dependencies.
+ */
+export type LogLevel = "silent" | "error" | "warn" | "info" | "debug";
+export interface Logger {
+	debug: (...args: unknown[]) => void;
+	info: (...args: unknown[]) => void;
+	warn: (...args: unknown[]) => void;
+	error: (...args: unknown[]) => void;
+}
+export declare function createConsoleLogger(level?: LogLevel): Logger;
+declare function getLogger(): Logger;
+declare function setLogger(logger: Logger): void;
+declare function setLogLevel(level: LogLevel): void;
 /**
  * Federation Types
  *
@@ -978,6 +1004,17 @@ export interface InboxHandlerOptions {
 	strictMode?: boolean;
 	/** Maximum age for signatures in seconds (default 300) */
 	maxAge?: number;
+	/**
+	 * Optional shared network key for internal-only federation.
+	 *
+	 * When set, incoming requests must include a matching network key header.
+	 * In strictMode, the header must also be included in the signed header list.
+	 */
+	networkKey?: string;
+	/**
+	 * Header name for the shared network key (default: X-Foundry-Network-Key)
+	 */
+	networkKeyHeader?: string;
 }
 /**
  * ActivityPub Utilities
@@ -3098,6 +3135,10 @@ export declare class RateLimiter {
  */
 export declare function enableFederation(options?: {
 	skipEnvCheck?: boolean;
+	/** Optional logger override */
+	logger?: Logger;
+	/** Optional log level (used when logger is not provided). Default: warn */
+	logLevel?: LogLevel;
 }): void;
 /**
  * Check if federation is enabled
@@ -3113,6 +3154,9 @@ export declare function isFederationEnabled(): boolean;
 export declare function assertFederationEnabled(feature: string): void;
 
 export {
+	getLogger as getFederationLogger,
+	setLogLevel as setFederationLogLevel,
+	setLogger as setFederationLogger,
 	validateActivitySignature as validateHttpSignature,
 	validateBlockActivity as validateBlockActivityFields,
 	validateFlagActivity as validateFlagActivityFields,

package/dist/federation.d.ts

@@ -41,7 +41,8 @@ declare const CCv3DataSchema: z.ZodObject<{
 				position: z.ZodOptional<z.ZodNullable<z.ZodUnion<[
 					z.ZodEnum<[
 						"before_char",
-						"after_char"
+						"after_char",
+						"in_chat"
 					]>,
 					z.ZodNumber,
 					z.ZodLiteral<"">
@@ -84,7 +85,8 @@ declare const CCv3DataSchema: z.ZodObject<{
 				position: z.ZodOptional<z.ZodNullable<z.ZodUnion<[
 					z.ZodEnum<[
 						"before_char",
-						"after_char"
+						"after_char",
+						"in_chat"
 					]>,
 					z.ZodNumber,
 					z.ZodLiteral<"">
@@ -127,7 +129,8 @@ declare const CCv3DataSchema: z.ZodObject<{
 				position: z.ZodOptional<z.ZodNullable<z.ZodUnion<[
 					z.ZodEnum<[
 						"before_char",
-						"after_char"
+						"after_char",
+						"in_chat"
 					]>,
 					z.ZodNumber,
 					z.ZodLiteral<"">
@@ -172,7 +175,8 @@ declare const CCv3DataSchema: z.ZodObject<{
 				position: z.ZodOptional<z.ZodNullable<z.ZodUnion<[
 					z.ZodEnum<[
 						"before_char",
-						"after_char"
+						"after_char",
+						"in_chat"
 					]>,
 					z.ZodNumber,
 					z.ZodLiteral<"">
@@ -223,7 +227,8 @@ declare const CCv3DataSchema: z.ZodObject<{
 				position: z.ZodOptional<z.ZodNullable<z.ZodUnion<[
 					z.ZodEnum<[
 						"before_char",
-						"after_char"
+						"after_char",
+						"in_chat"
 					]>,
 					z.ZodNumber,
 					z.ZodLiteral<"">
@@ -322,7 +327,8 @@ declare const CCv3DataSchema: z.ZodObject<{
 				position: z.ZodOptional<z.ZodNullable<z.ZodUnion<[
 					z.ZodEnum<[
 						"before_char",
-						"after_char"
+						"after_char",
+						"in_chat"
 					]>,
 					z.ZodNumber,
 					z.ZodLiteral<"">
@@ -397,7 +403,8 @@ declare const CCv3DataSchema: z.ZodObject<{
 				position: z.ZodOptional<z.ZodNullable<z.ZodUnion<[
 					z.ZodEnum<[
 						"before_char",
-						"after_char"
+						"after_char",
+						"in_chat"
 					]>,
 					z.ZodNumber,
 					z.ZodLiteral<"">
@@ -482,7 +489,8 @@ declare const CCv3DataSchema: z.ZodObject<{
 				position: z.ZodOptional<z.ZodNullable<z.ZodUnion<[
 					z.ZodEnum<[
 						"before_char",
-						"after_char"
+						"after_char",
+						"in_chat"
 					]>,
 					z.ZodNumber,
 					z.ZodLiteral<"">
@@ -561,7 +569,8 @@ declare const CCv3DataSchema: z.ZodObject<{
 				position: z.ZodOptional<z.ZodNullable<z.ZodUnion<[
 					z.ZodEnum<[
 						"before_char",
-						"after_char"
+						"after_char",
+						"in_chat"
 					]>,
 					z.ZodNumber,
 					z.ZodLiteral<"">
@@ -619,6 +628,23 @@ declare const CCv3DataSchema: z.ZodObject<{
  * Character Card v3 full structure
  */
 export type CCv3Data = z.infer<typeof CCv3DataSchema>;
+/**
+ * Federation Logger
+ *
+ * Lightweight logger with configurable verbosity and a safe default (warn).
+ * No external dependencies.
+ */
+export type LogLevel = "silent" | "error" | "warn" | "info" | "debug";
+export interface Logger {
+	debug: (...args: unknown[]) => void;
+	info: (...args: unknown[]) => void;
+	warn: (...args: unknown[]) => void;
+	error: (...args: unknown[]) => void;
+}
+export declare function createConsoleLogger(level?: LogLevel): Logger;
+declare function getLogger(): Logger;
+declare function setLogger(logger: Logger): void;
+declare function setLogLevel(level: LogLevel): void;
 /**
  * Federation Types
  *
@@ -978,6 +1004,17 @@ export interface InboxHandlerOptions {
 	strictMode?: boolean;
 	/** Maximum age for signatures in seconds (default 300) */
 	maxAge?: number;
+	/**
+	 * Optional shared network key for internal-only federation.
+	 *
+	 * When set, incoming requests must include a matching network key header.
+	 * In strictMode, the header must also be included in the signed header list.
+	 */
+	networkKey?: string;
+	/**
+	 * Header name for the shared network key (default: X-Foundry-Network-Key)
+	 */
+	networkKeyHeader?: string;
 }
 /**
  * ActivityPub Utilities
@@ -3098,6 +3135,10 @@ export declare class RateLimiter {
  */
 export declare function enableFederation(options?: {
 	skipEnvCheck?: boolean;
+	/** Optional logger override */
+	logger?: Logger;
+	/** Optional log level (used when logger is not provided). Default: warn */
+	logLevel?: LogLevel;
 }): void;
 /**
  * Check if federation is enabled
@@ -3113,6 +3154,9 @@ export declare function isFederationEnabled(): boolean;
 export declare function assertFederationEnabled(feature: string): void;
 
 export {
+	getLogger as getFederationLogger,
+	setLogLevel as setFederationLogLevel,
+	setLogger as setFederationLogger,
 	validateActivitySignature as validateHttpSignature,
 	validateBlockActivity as validateBlockActivityFields,
 	validateFlagActivity as validateFlagActivityFields,

package/dist/federation.js

@@ -44,6 +44,50 @@ function generateUUID() {
 }
 
 // ../federation/dist/index.js
+var LEVELS = {
+  silent: 0,
+  error: 1,
+  warn: 2,
+  info: 3,
+  debug: 4
+};
+var noop = () => {
+};
+function createConsoleLogger(level = "warn") {
+  const severity = LEVELS[level] ?? LEVELS.warn;
+  const hasConsole = typeof console !== "undefined";
+  const c = hasConsole ? console : void 0;
+  const debugImpl = c?.debug ? c.debug.bind(c) : c?.log ? c.log.bind(c) : noop;
+  const infoImpl = c?.info ? c.info.bind(c) : c?.log ? c.log.bind(c) : noop;
+  const warnImpl = c?.warn ? c.warn.bind(c) : c?.log ? c.log.bind(c) : noop;
+  const errorImpl = c?.error ? c.error.bind(c) : c?.log ? c.log.bind(c) : noop;
+  return {
+    debug: severity >= LEVELS.debug ? debugImpl : noop,
+    info: severity >= LEVELS.info ? infoImpl : noop,
+    warn: severity >= LEVELS.warn ? warnImpl : noop,
+    error: severity >= LEVELS.error ? errorImpl : noop
+  };
+}
+var federationLogger = createConsoleLogger("warn");
+function getLogger() {
+  return federationLogger;
+}
+function setLogger(logger) {
+  federationLogger = logger;
+}
+function setLogLevel(level) {
+  federationLogger = createConsoleLogger(level);
+}
+function configureLogger(options) {
+  if (!options) return;
+  if (options.logger) {
+    setLogger(options.logger);
+    return;
+  }
+  if (options.logLevel) {
+    setLogLevel(options.logLevel);
+  }
+}
 var ACTIVITY_CONTEXT = [
   "https://www.w3.org/ns/activitystreams",
   {
@@ -402,7 +446,7 @@ var SyncEngine = class {
         try {
           listener(event);
         } catch (err) {
-          console.error(`Event listener error:`, err);
+          getLogger().error("[federation] Event listener error:", err);
         }
       }
     }
@@ -1531,7 +1575,7 @@ var HttpPlatformAdapter = class extends BasePlatformAdapter {
       const data = await response.json();
       return this.config.transformers?.get ? this.config.transformers.get(data) : data;
     } catch (err) {
-      console.error(`Failed to get card ${localId}:`, err);
+      getLogger().error(`[federation] Failed to get card ${localId}:`, err);
       return null;
     }
   }
@@ -2083,27 +2127,14 @@ function parseSignatureHeader(header) {
   return {
     keyId: params.keyId,
     algorithm: params.algorithm || "rsa-sha256",
-    headers: (params.headers || "(request-target) host date").split(" "),
+    headers: (params.headers || "(request-target) host date").trim().split(/\s+/).filter(Boolean).map((h) => h.toLowerCase()),
     signature: params.signature
   };
 }
 function buildSigningString(method, path, headers, headerNames) {
   const result = buildSigningStringStrict(method, path, headers, headerNames);
   if (!result.success) {
-    console.warn(`[federation] Signature verification may fail: ${result.error}`);
-    const lines = [];
-    for (const name of headerNames) {
-      if (name === "(request-target)") {
-        lines.push(`(request-target): ${method.toLowerCase()} ${path}`);
-      } else if (name === "(created)" || name === "(expires)") {
-      } else {
-        const value = headers.get(name);
-        if (value !== null) {
-          lines.push(`${name.toLowerCase()}: ${value}`);
-        }
-      }
-    }
-    return lines.join("\n");
+    throw new Error(result.error);
   }
   return result.signingString;
 }
@@ -2112,16 +2143,17 @@ function buildSigningStringStrict(method, path, headers, headerNames) {
   const missingHeaders = [];
   const syntheticHeaders = /* @__PURE__ */ new Set(["(request-target)", "(created)", "(expires)"]);
   for (const name of headerNames) {
-    if (name === "(request-target)") {
+    const normalizedName = name.toLowerCase();
+    if (normalizedName === "(request-target)") {
       lines.push(`(request-target): ${method.toLowerCase()} ${path}`);
-    } else if (name === "(created)") {
-    } else if (name === "(expires)") {
+    } else if (normalizedName === "(created)") {
+    } else if (normalizedName === "(expires)") {
     } else {
-      const value = headers.get(name);
+      const value = headers.get(normalizedName);
       if (value !== null) {
-        lines.push(`${name.toLowerCase()}: ${value}`);
-      } else if (!syntheticHeaders.has(name)) {
-        missingHeaders.push(name);
+        lines.push(`${normalizedName}: ${value}`);
+      } else if (!syntheticHeaders.has(normalizedName)) {
+        missingHeaders.push(normalizedName);
       }
     }
   }
@@ -2142,7 +2174,7 @@ async function verifyHttpSignature(parsed, publicKeyPem, method, path, headers,
     if (options.strictHeaders) {
       const strictResult = buildSigningStringStrict(method, path, headers, parsed.headers);
       if (!strictResult.success) {
-        console.warn(`[federation] Strict header verification failed: ${strictResult.error}`);
+        getLogger().warn(`[federation] Strict header verification failed: ${strictResult.error}`);
         return false;
       }
     }
@@ -2162,7 +2194,7 @@ async function verifyHttpSignature(parsed, publicKeyPem, method, path, headers,
       data
     );
   } catch (error) {
-    console.error("Signature verification failed:", error);
+    getLogger().error("[federation] Signature verification failed:", error);
     return false;
   }
 }
@@ -2300,7 +2332,7 @@ async function importPublicKey(pem) {
       ["verify"]
     );
   } catch (error) {
-    console.error("Failed to import public key:", error);
+    getLogger().error("[federation] Failed to import public key:", error);
     return null;
   }
 }
@@ -2316,7 +2348,7 @@ async function importPrivateKey(pem) {
       ["sign"]
     );
   } catch (error) {
-    console.error("Failed to import private key:", error);
+    getLogger().error("[federation] Failed to import private key:", error);
     return null;
   }
 }
@@ -2345,9 +2377,31 @@ function extractHostFromActorId(actorId) {
     return null;
   }
 }
+function timingSafeEqualString(a, b) {
+  let mismatch = a.length === b.length ? 0 : 1;
+  const maxLen = Math.max(a.length, b.length);
+  for (let i = 0; i < maxLen; i++) {
+    const aCode = a.charCodeAt(i) || 0;
+    const bCode = b.charCodeAt(i) || 0;
+    mismatch |= aCode ^ bCode;
+  }
+  return mismatch === 0;
+}
 async function handleInbox(body, headers, options) {
   assertFederationEnabled("handleInbox");
   try {
+    const normalizedHeaders = headers instanceof Headers ? headers : new Headers(headers);
+    const networkKey = typeof options.networkKey === "string" ? options.networkKey : void 0;
+    const networkKeyHeader = options.networkKeyHeader ?? "X-Foundry-Network-Key";
+    if (networkKey && networkKey.length > 0) {
+      const provided = normalizedHeaders.get(networkKeyHeader);
+      if (!provided || !timingSafeEqualString(provided, networkKey)) {
+        return {
+          accepted: false,
+          error: "Unauthorized: invalid or missing network key"
+        };
+      }
+    }
     if (options.moderationStore) {
       const actorId = typeof body === "object" && body !== null && "actor" in body ? String(body.actor) : null;
       if (actorId) {
@@ -2370,7 +2424,7 @@ async function handleInbox(body, headers, options) {
       };
     }
     if (options.strictMode) {
-      const signatureHeader = headers instanceof Headers ? headers.get("signature") : headers["signature"] || headers["Signature"];
+      const signatureHeader = normalizedHeaders.get("signature");
       if (!signatureHeader) {
         return {
           accepted: false,
@@ -2384,6 +2438,15 @@ async function handleInbox(body, headers, options) {
           error: "Invalid Signature header format"
         };
       }
+      if (networkKey && networkKey.length > 0) {
+        const requiredSigned = networkKeyHeader.toLowerCase();
+        if (!parsedSig.headers.includes(requiredSigned)) {
+          return {
+            accepted: false,
+            error: `Strict mode: signature missing required header: ${requiredSigned}`
+          };
+        }
+      }
       const missingSignedHeaders = REQUIRED_SIGNED_HEADERS.filter(
         (h) => !parsedSig.headers.includes(h)
       );
@@ -2393,14 +2456,14 @@ async function handleInbox(body, headers, options) {
           error: `Strict mode: signature missing required headers: ${missingSignedHeaders.join(", ")}`
         };
       }
-      const dateHeader = headers instanceof Headers ? headers.get("date") : headers["date"] || headers["Date"];
+      const dateHeader = normalizedHeaders.get("date");
       if (!dateHeader) {
         return {
           accepted: false,
           error: "Strict mode: Date header required"
         };
       }
-      const hostHeader = headers instanceof Headers ? headers.get("host") : headers["host"] || headers["Host"];
+      const hostHeader = normalizedHeaders.get("host");
       if (!hostHeader) {
         return {
           accepted: false,
@@ -2443,7 +2506,7 @@ async function handleInbox(body, headers, options) {
           error: `Invalid key ID or actor URL`
         };
       }
-      const digestHeader = headers instanceof Headers ? headers.get("digest") : headers["digest"] || headers["Digest"];
+      const digestHeader = normalizedHeaders.get("digest");
       if (digestHeader) {
         if (!options.rawBody) {
           return {
@@ -2474,13 +2537,13 @@ async function handleInbox(body, headers, options) {
       }
       const method = options.method || "POST";
       const path = options.path || "/inbox";
-      const normalizedHeaders = headers instanceof Headers ? headers : new Headers(headers);
       const isValid = await verifyHttpSignature(
         parsedSig,
         actor.publicKey.publicKeyPem,
         method,
         path,
-        normalizedHeaders
+        normalizedHeaders,
+        { strictHeaders: true }
       );
       if (!isValid) {
         return {
@@ -3559,7 +3622,7 @@ var PolicyEngine = class {
     if (!regex) {
       const safetyWarning = checkRegexSafety(rule.pattern);
       if (safetyWarning) {
-        console.warn(`[moderation] Rule "${rule.name}": ${safetyWarning}`);
+        getLogger().warn(`[moderation] Rule "${rule.name}": ${safetyWarning}`);
       }
       try {
         regex = new RegExp(rule.pattern, "i");
@@ -3799,11 +3862,12 @@ function getEnvVar(name) {
   return void 0;
 }
 function enableFederation(options) {
+  configureLogger(options);
   explicitlyEnabled = true;
   envCheckSkipped = options?.skipEnvCheck ?? false;
   const nodeEnv = getEnvVar("NODE_ENV");
   if (nodeEnv === "development" || nodeEnv === "test") {
-    console.warn(
+    getLogger().warn(
       "[character-foundry/federation] Federation enabled. WARNING: Verify HTTP signatures in production. Do NOT use in production with untrusted inputs without signature validation."
     );
   }
@@ -3867,6 +3931,7 @@ export {
   createAnnounceActivity,
   createArchiveAdapter,
   createBlockActivity,
+  createConsoleLogger,
   createCreateActivity,
   createDeleteActivity,
   createFlagActivity,
@@ -3881,6 +3946,7 @@ export {
   enableFederation,
   generateActivityId,
   generateCardId,
+  getLogger as getFederationLogger,
   handleActor,
   handleInbox,
   handleNodeInfo,
@@ -3893,6 +3959,8 @@ export {
   parseForkActivity,
   parseInstallActivity,
   parseSignatureHeader,
+  setLogLevel as setFederationLogLevel,
+  setLogger as setFederationLogger,
   signRequest,
   stCharacterToCCv3,
   validateBlockActivity as validateBlockActivityFields,