{"record":{"id":"e108b172f147f9e1","repo":"ruvnet/ruflo","slug":"ruvbotbridgeconfig-proofsigningkey-is-required-whe","errorCode":null,"errorMessage":"RuvBotBridgeConfig.proofSigningKey is required when enableProofChain is true","messagePattern":"RuvBotBridgeConfig\\.proofSigningKey is required when enableProofChain is true","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"v3/@claude-flow/guidance/src/ruvbot-integration.ts","lineNumber":859,"sourceCode":"            `Agent manifest ${validation.admissionDecision}: risk=${validation.riskScore}, errors=${validation.errors.length}`,\n          );\n        }\n      }\n    }\n  }\n\n  /**\n   * Handle `session:create` events: initialize a proof chain for the session.\n   */\n  private async handleSessionCreate(...args: unknown[]): Promise<void> {\n    const data = (args[0] ?? {}) as Record<string, unknown>;\n    const sessionId = String(data['sessionId'] ?? data['id'] ?? `session-${Date.now()}`);\n\n    this.logEvent('session:create', { sessionId });\n\n    if (this.config.enableProofChain) {\n      if (!this.config.proofSigningKey) {\n        throw new Error(\n          'RuvBotBridgeConfig.proofSigningKey is required when enableProofChain is true',\n        );\n      }\n      const { createProofChain } = await import('./proof.js');\n      const chain = createProofChain({ signingKey: this.config.proofSigningKey });\n      this.sessionChains.set(sessionId, chain);\n    }\n  }\n\n  /**\n   * Handle `session:end` events: finalize the proof chain and persist.\n   */\n  private async handleSessionEnd(...args: unknown[]): Promise<void> {\n    const data = (args[0] ?? {}) as Record<string, unknown>;\n    const sessionId = String(data['sessionId'] ?? data['id'] ?? 'unknown');\n\n    this.logEvent('session:end', { sessionId });\n","sourceCodeStart":841,"sourceCodeEnd":877,"githubUrl":"https://github.com/ruvnet/ruflo/blob/fa13ee4ad60ac2090b1480656eb233521790d640/v3/@claude-flow/guidance/src/ruvbot-integration.ts#L841-L877","documentation":"Thrown inside the bridge's private session:create event handler when RuvBotBridgeConfig.enableProofChain is true but config.proofSigningKey is missing. Every proof-chain entry is signed (the chain is created via createProofChain({ signingKey })), so a key is mandatory. The check happens lazily on the first ruvbot 'session:create' event, not at construction, which is why it can surprise you well after startup.","triggerScenarios":"Constructing RuvBotGuidanceBridge(ruvbot, { enableProofChain: true }) without proofSigningKey, then the wrapped ruvbot emits a 'session:create' event; typical when the enable flag and the key come from different config sources and the key source is empty.","commonSituations":"proofSigningKey sourced from an env var (e.g. PROOF_SIGNING_KEY) that is set in production but unset in CI/staging while enableProofChain is hardcoded true; async key loading that has not completed before events start flowing; config objects assembled from partials where the key field is dropped.","solutions":["Provide proofSigningKey in the bridge config whenever enableProofChain is true","Or set enableProofChain: false if signed audit trails are not required in that environment","Validate the pairing (enableProofChain => proofSigningKey present) at startup, before wiring ruvbot events, so it fails fast instead of mid-event"],"exampleFix":"// before\nnew RuvBotGuidanceBridge(ruvbot, { enableProofChain: true }); // no key -> throws on first session:create\n\n// after\nnew RuvBotGuidanceBridge(ruvbot, {\n  enableProofChain: true,\n  proofSigningKey: process.env.PROOF_SIGNING_KEY!,\n});","handlingStrategy":"validation","validationCode":"// Fail fast at startup instead of on the first session:create event\nfunction validateBridgeConfig(cfg: RuvBotBridgeConfig): void {\n  if (cfg.enableProofChain && !cfg.proofSigningKey) {\n    throw new Error(\n      `proofSigningKey required: enableProofChain=true but key is ${cfg.proofSigningKey === '' ? 'empty' : 'unset'}`,\n    );\n  }\n}\nvalidateBridgeConfig(config); // before constructing/wiring the bridge","typeGuard":"type ProofCapableConfig = RuvBotBridgeConfig & { proofSigningKey: string };\nfunction hasProofKey(cfg: RuvBotBridgeConfig): cfg is ProofCapableConfig {\n  return !cfg.enableProofChain || (typeof cfg.proofSigningKey === 'string' && cfg.proofSigningKey.length > 0);\n}","tryCatchPattern":"// handleSessionCreate is an internal event handler; catch at the event boundary\nruvbot.on('error', (e: Error) => {\n  if (e.message.includes('proofSigningKey')) {\n    failStartup('PROOF_SIGNING_KEY missing while enableProofChain=true');\n  }\n});","preventionTips":["Assert required secrets at process start, not lazily on first event","Keep enableProofChain and proofSigningKey sourced from the same config object","Add a config schema check (e.g. zod) for RuvBotBridgeConfig in CI"],"tags":["ruvbot","proof-chain","configuration","signing-key","event-handler"],"backgroundTag":"missing-required-config","analyzedSha":"fa13ee4ad60ac2090b1480656eb233521790d640","analyzedAt":"2026-08-18T21:34:22.708Z","contentChangedAt":"2026-08-18T21:34:22.708Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}