feat(snmp): add OID policy enforcement and audit persistence scaffold

[EscDavid]

Motivation

• Enforce OID allow/deny rules before touching the network to block dangerous/sensitive OIDs.
• Add persistent audit scaffolding so SNMP operations can later be recorded for traceability while keeping persistence off by default.
• Introduce typed business errors to map domain failures to coherent HTTP status codes for better client responses and observability.

Description

• Added OidPolicyService with allowlist/denylist prefix rules and wired it into the SNMP flow after OID normalization and before adapter execution (new file src/modules/security/oid-policy.service.ts).
• Added audit repository and service scaffolding that records SNMP events (success/error, latency, target) and a DB pool client; persistence is feature-flagged via AUDIT_PERSISTENCE_ENABLED (new files under src/modules/audit/ and src/shared/database/client.ts).
• Introduced typed domain errors (AppError, OidBlockedError, UnsupportedVendorError) and mapped them to HTTP responses in SNMP route handler (src/shared/errors/app-error.ts, src/app/routes/v1/snmp.routes.ts).
• Updated app routing to register versioned SNMP routes, added env validators and .env.example entries for OID policy and audit flags, and added TypeScript types for net-snmp and a generic SNMP adapter implementation.
• Added unit and integration tests covering OID normalization, OID policy behavior, and the blocked-OID HTTP response (tests/unit/*, tests/integration/*).

Testing

• Ran npm run typecheck (tsc --noEmit) which completed successfully.
• Ran npm test (Vitest) and all tests passed including unit tests for normalizeOid and OidPolicyService and integration tests for health and blocked-OID behavior.
• Ran npm run build (tsc -p tsconfig.json) which completed successfully and produced the build artifacts.

---

Codex Task

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: bfd99cb85b

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Parse audit flag with string-safe boolean semantics

AUDIT_PERSISTENCE_ENABLED is loaded from environment variables as a string, but z.coerce.boolean() uses JavaScript truthiness, so values like 'false' or '0' parse to true. With the shipped .env value AUDIT_PERSISTENCE_ENABLED=false, audit persistence is unintentionally enabled and SNMP requests start writing to Postgres, which can fail requests when DB/audit schema is not available.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Always close SNMP sessions when get() fails

The session is closed only after the awaited promise resolves; any session.get error path (error, empty varbinds, or mapping exception) rejects before reaching session.close(). In repeated timeout/error scenarios this leaks SNMP sessions/sockets and can exhaust resources, so closure should happen in a finally block.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Return 4xx for malformed OID input

The route only converts AppError instances to client-facing status codes; other errors are rethrown and become 500s. Since OID format validation currently throws a plain Error, requests with a valid shape but malformed OID (for example invalid-oid plus a full connection) return Internal Server Error instead of a client error, which breaks the API's invalid-payload behavior.

Useful? React with 👍 / 👎.