{"_id":"@cerbi/pino-governance","name":"@cerbi/pino-governance","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@cerbi/pino-governance","version":"0.1.0","description":"Governance evaluator and Pino transport for Cerbi governance rules.","license":"MIT","type":"commonjs","main":"dist/index.js","types":"dist/index.d.ts","scripts":{"build":"tsc -p .","test":"vitest run","lint":"tsc -p . --noEmit"},"repository":{"type":"git","url":"git+https://example.com/cerbi/pino-governance.git"},"engines":{"node":">=20"},"keywords":["pino","governance","cerbi"],"dependencies":{"chokidar":"^4.0.1","pino":"^9.3.2","pino-abstract-transport":"^1.1.0"},"devDependencies":{"@types/node":"^22.7.4","typescript":"^5.6.3","vitest":"^2.1.3"},"gitHead":"d6b3dbf45ecbe33993029834b707d26f61e06b7f","_id":"@cerbi/pino-governance@0.1.0","_nodeVersion":"24.13.0","_npmVersion":"11.12.1","dist":{"integrity":"sha512-h1rki0HQoQAYUg00I8SwR4+Cme/Lg1/yvwHgt3zdLQzOLa7FqsS287oLN6VNEK/IaD81t6/6tObZXrlOTto+Lw==","shasum":"1a835e92f4f1363902714e6f6f430515535b1e93","tarball":"https://registry.npmjs.org/@cerbi/pino-governance/-/pino-governance-0.1.0.tgz","fileCount":30,"unpackedSize":44044,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQC31hcr24ehsPptdKWQ5Nn9Kcvw6iTEK4jov51nI2gGEgIhAKam7r9NQJBXO5l+Qp8ne8V4IaEx1ES4A2/7pSXmtYuB"}]},"_npmUser":{"name":"hellocerbi","email":"hello@cerbi.io"},"directories":{},"maintainers":[{"name":"hellocerbi","email":"hello@cerbi.io"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/pino-governance_0.1.0_1779252130066_0.6311549241864551"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-20T04:42:09.823Z","0.1.0":"2026-05-20T04:42:10.204Z","modified":"2026-05-20T04:42:10.444Z"},"maintainers":[{"name":"hellocerbi","email":"hello@cerbi.io"}],"description":"Governance evaluator and Pino transport for Cerbi governance rules.","keywords":["pino","governance","cerbi"],"repository":{"type":"git","url":"git+https://example.com/cerbi/pino-governance.git"},"license":"MIT","readme":"# @cerbi/pino-governance\r\n\r\nA governance-aware Pino transport and evaluator for Cerbi governance rules. The package can be used as a Pino transport target or as a pure evaluator that annotates events with governance status without blocking log flow.\r\n\r\n## Installation\r\n\r\n```bash\r\nnpm install @cerbi/pino-governance\r\n```\r\n\r\n## Quick start\r\n\r\n### Using as a Pino transport\r\n\r\n```ts\r\nimport pino from 'pino';\r\nimport { createGovernanceTransport } from '@cerbi/pino-governance';\r\n\r\nconst governance = await createGovernanceTransport({\r\n  rulesetPath: './governance.json'\r\n});\r\n\r\nconst logger = pino({\r\n  transport: {\r\n    target: '@cerbi/pino-governance',\r\n    options: { rulesetPath: './governance.json' }\r\n  }\r\n});\r\n\r\nlogger.info({ user: { role: 'admin' } }, 'hello');\r\n```\r\n\r\n`createGovernanceTransport` accepts additional scoring-focused options:\r\n\r\n- `appName` and `environment`: defaults for `AppName` and `Environment` when an event omits them.\r\n- `profileName`: override for the `GovernanceProfileUsed` field (defaults to the ruleset version).\r\n- `stringifyStructuredFields`: JSON-stringifies structured scoring fields (violations) for string-only logging surfaces.\r\n\r\n### Evaluating manually\r\n\r\n```ts\r\nimport { evaluateEvent } from '@cerbi/pino-governance';\r\nimport ruleset from './governance.json';\r\n\r\nconst { event } = evaluateEvent({ level: 30, msg: 'ok', user: { role: 'guest' } }, ruleset);\r\nconsole.log(event.governance);\r\n```\r\n\r\n### Hot reloading a ruleset\r\n\r\n```ts\r\nimport { RulesetLoader } from '@cerbi/pino-governance';\r\n\r\nconst loader = new RulesetLoader('./governance.json', {\r\n  onReload: (ruleset) => console.log('reloaded', ruleset.version),\r\n  onError: (err) => console.error('invalid governance', err.message)\r\n});\r\n\r\nawait loader.start();\r\n```\r\n\r\n## Governance payload\r\n\r\nThe evaluator always preserves `level`, `msg`/`message`, and any structured user fields. It writes a `governance` object alongside the event that includes:\r\n\r\n- `version`: ruleset version string\r\n- `mode`: `enforced`, `relaxed`, or `degraded`\r\n- `status`: `pass`, `fail`, `relaxed`, or `degraded`\r\n- `action`: `allow` or `deny`\r\n- `appliedRule`: rule id or `__default__`\r\n- `tags`: aggregated tags (including standard tags such as `governance:mode:*`)\r\n- `errors`: optional array when the ruleset could not be loaded or validated\r\n\r\nSee [governance-plugin-contract.md](./governance-plugin-contract.md) for the full semantics and the golden fixtures for worked examples.\r\n\r\n## Cerbi scoring payload\r\n\r\nEvery emitted event is enriched with idempotency and scoring fields expected by the CerbiShield scoring worker:\r\n\r\n- `CerbiEventId`: UUID. Generated when absent on the incoming event (override with `idFactory` in tests).\r\n- `CerbiEventTimeUtc`: ISO 8601 UTC timestamp (derived from the same clock used for governance evaluation).\r\n- `AppName` and `Environment`: taken from the event or defaulted from the evaluator/transport options.\r\n- `GovernanceProfileUsed`: profile identifier (ruleset version by default or `profileName` option).\r\n- `GovernanceMode`: mirror of the governance mode (`enforced`, `relaxed`, `degraded`).\r\n- `GovernanceEnforced`: boolean flag for enforcement mode.\r\n- `GovernanceRelaxed`: present and true when the event is evaluated in relaxed mode or explicitly flagged.\r\n- `GovernanceViolations` / `GovernanceViolationsStructured`: arrays describing matching deny decisions (empty arrays for allows/degraded).\r\n- `GovernanceScoreImpact`: numeric weight derived from the violation count.\r\n\r\nFor string-only logging contexts (e.g., Java MDC), enable `stringifyStructuredFields` so structured violations are JSON-encoded.\r\n","readmeFilename":"README.md","_rev":"1-e63a6df9dd215ff642a741349321c85d"}