{"record":{"id":"d5486c661b45e7e4","repo":"ruvnet/ruflo","slug":"unknown-federation-claim-claim","errorCode":null,"errorMessage":"Unknown federation claim: ${claim}","messagePattern":"Unknown federation claim: (.+?)","errorType":"exception","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"v3/@claude-flow/plugin-agent-federation/src/application/claim-checker.ts","lineNumber":51,"sourceCode":" * - observe: calculate and report missing grants without blocking;\n * - enforce: default deny unless the exact claim is configured.\n *\n * ADR-324 policy adapters can supply the `grantedClaims` set after evaluating\n * the request; ownership-changing federation messages remain disabled in the\n * default message policy until the full ingress PEP is composed.\n */\nexport function createFederationClaimChecker(\n  config: FederationClaimCheckerConfig = {},\n): FederationClaimChecker {\n  const mode = config.mode ?? 'legacy';\n  if (mode !== 'legacy' && mode !== 'observe' && mode !== 'enforce') {\n    throw new TypeError(`Unsupported federation authorization mode: ${String(mode)}`);\n  }\n\n  const grantedClaims = new Set<FederationClaimType>();\n  for (const claim of config.grantedClaims ?? []) {\n    if (!FEDERATION_CLAIMS.has(claim as FederationClaimType)) {\n      throw new TypeError(`Unknown federation claim: ${claim}`);\n    }\n    grantedClaims.add(claim as FederationClaimType);\n  }\n\n  return {\n    mode,\n    grantedClaims,\n    checkClaim: (claim) => {\n      const granted = grantedClaims.has(claim);\n      if (mode === 'observe') config.onObservation?.(claim, granted);\n      return mode !== 'enforce' || granted;\n    },\n  };\n}\n","sourceCodeStart":33,"sourceCodeEnd":66,"githubUrl":"https://github.com/ruvnet/ruflo/blob/fa13ee4ad60ac2090b1480656eb233521790d640/v3/@claude-flow/plugin-agent-federation/src/application/claim-checker.ts#L33-L66","documentation":"Every entry in config.grantedClaims must be a member of the package's FEDERATION_CLAIMS vocabulary; unknown strings throw a TypeError during checker construction. The strictness is deliberate: under 'enforce' mode a typo'd claim would silently never match and permanently deny operations, so misconfiguration is surfaced immediately.","triggerScenarios":"Typos in claim strings ('mesage:send' for 'message:send'); claim names invented by the integrator instead of taken from the federation vocabulary; claims valid in a newer/older package version passed across a version skew; an ADR-324 adapter emitting arbitrary strings as claims.","commonSituations":"Grant lists hand-copied from docs of a different version; adapters mapping internal permissions to free-form strings; renamed claims after a package upgrade.","solutions":["Fix the claim string to the exact federation claim type exported by the package","Source grant lists from the package's exported claim vocabulary rather than hand-typed literals","Align adapter and package versions when the claim set changed between releases","Log the exported claim set once at startup so drift is visible in ops output"],"exampleFix":"// before\ncreateFederationClaimChecker({ mode: 'enforce', grantedClaims: ['message:send'] }); // not in vocabulary\n// after\n// use only claims drawn from the package's federation claim vocabulary\ncreateFederationClaimChecker({ mode: 'enforce', grantedClaims: validClaims });","handlingStrategy":"type-guard","validationCode":"// derive grant lists from the exported vocabulary, never hand-type them\nimport { FEDERATION_CLAIMS } from '@claude-flow/plugin-agent-federation'; // if exported\nconst grantedClaims = [...FEDERATION_CLAIMS].filter(c => policy.allows(c));\ncreateFederationClaimChecker({ mode: 'enforce', grantedClaims });","typeGuard":"function isKnownFederationClaim(c: unknown): c is FederationClaimType {\n  return (\n    typeof c === 'string' &&\n    FEDERATION_CLAIMS.has(c as FederationClaimType)\n  );\n}","tryCatchPattern":null,"preventionTips":["Source claims from the package's exported vocabulary","Avoid free-form claim strings in adapters — map to known claim types","Add a startup assertion that every configured claim is known","Re-check claim lists after package upgrades"],"tags":["config","claims","authorization"],"backgroundTag":"unknown-claim-value","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"}