@nugehs/bouncer 0.1.3 → 0.2.0

package/CHANGELOG.md

@@ -5,6 +5,23 @@ All notable changes to `@nugehs/bouncer` are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.0] - 2026-06-16
+
+### Added
+
+- **Nigeria rule packs** — three deterministic packs for a platform operating in
+  Nigeria, validated against a real Next.js front end and a NestJS API:
+  - `ng-ndpc` (10 rules) — Nigeria Data Protection Act 2023 / NDPC: privacy
+    notice, opt-in & granular consent, data-subject rights (access/erasure),
+    encryption at rest, retention/erasure lifecycle, NDPA localization, DPO
+    designation, 72-hour breach plan, and cross-border transfer safeguards.
+  - `ng-fccpc` (5 rules) — consumer protection (FCCPC): blanket "no refund / all
+    sales final" clauses flagged as void (high-precision — a tiered/conditional
+    refund policy does not trip it), refund policy present, no drip pricing,
+    explicit terms acceptance, and terms of service present.
+  - `ng-firs` (4 rules) — tax (FIRS): 7.5% VAT rate, VAT on the platform
+    commission, WHT on organiser payouts, and VAT tax invoices.
+
 ## [0.1.3] - 2026-06-10
 
 ### Added

package/README.md

@@ -10,7 +10,8 @@
 
 bouncer verifies that the controls a
 regulation *requires* actually exist in your code — UK Online Safety Act, ICO
-Children's Code (AADC) — expressed as deterministic **rule packs**. It runs in CI,
+Children's Code (AADC), and Nigeria (NDPC, FCCPC, FIRS) — expressed as
+deterministic **rule packs**. It runs in CI,
 exits non-zero when a required control is missing, and needs **no LLM**.
 
 It checks IDs at the door so non-compliant code doesn't get in.
@@ -106,7 +107,7 @@ not find. Missing surface → honest "can't determine".
 > aliases to file globs (see `src/lib/adapters/next.js`). **Adapter PRs are very
 > welcome** — `nuxt`, `sveltekit`, `remix`, `flutter`, `django` are all natural
 > candidates.
-- `packs` — which rule packs to run. Built-ins: `uk-osa`, `uk-aadc`.
+- `packs` — which rule packs to run. Built-ins: `uk-osa`, `uk-aadc`, `ng-ndpc`, `ng-fccpc`, `ng-firs`.
 - `packDirs` — extra directories of your own `*.json` packs.
 - `ignore` — rule ids to skip.
 - `failOn` — which buckets make `check` exit non-zero (default `["fail"]`).
@@ -145,6 +146,24 @@ or a raw glob. `expect: "absent"` flips the meaning — a match is a *violation*
 
 `any`, `signup`, `auth`, `profile`, `chat`, `livestream`, `ugc`, `governance`.
 
+### Nigeria packs
+
+For a platform operating in Nigeria, three packs ship built-in:
+
+- **`ng-ndpc`** — Nigeria Data Protection Act 2023 (NDPC): privacy notice, opt-in
+  & granular consent, data-subject rights, encryption, retention/erasure, NDPA
+  localization, DPO designation, 72-hour breach plan, cross-border safeguards.
+- **`ng-fccpc`** — consumer protection (FCCPC): blanket "no refund / all sales
+  final" clauses flagged as **void** — and high-precision, so a *tiered* or
+  conditional refund policy doesn't trip it — plus refund-policy present, no drip
+  pricing, explicit terms acceptance, terms of service present.
+- **`ng-firs`** — tax (FIRS): 7.5% VAT rate, VAT on commission, WHT on payouts,
+  VAT tax invoice.
+
+Some obligations are process, not code — NDPC registration, signed cross-border
+DPAs, the WHT remittance itself. Those rules surface as **gaps to track** (add
+them to `ignore` with a note), not things a static scan can prove.
+
 ## MCP
 
 bouncer is also an MCP server (stdio), so an agent can pull the same deterministic

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nugehs/bouncer",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "mcpName": "io.github.nugehs/bouncer",
   "description": "bouncer — static compliance-controls checker. Verifies the controls a regulation requires actually exist in your code (UK Online Safety Act, ICO Children's Code), as deterministic rule packs. No LLM required.",
   "type": "module",

package/src/packs/ng-fccpc.json

@@ -0,0 +1,97 @@
+{
+  "id": "ng-fccpc",
+  "title": "Nigeria Consumer Protection (FCCPC)",
+  "authority": "Federal Competition & Consumer Protection Commission",
+  "url": "https://fccpc.gov.ng/",
+  "rules": [
+    {
+      "id": "fccpc.no-final-sale-clause",
+      "standard": "Void terms — blanket 'no refund / all sales final' clauses (FCCPA s.130)",
+      "severity": "high",
+      "surface": "any",
+      "intent": "A blanket 'no refund / all sales final / non-refundable' clause that excludes a consumer's statutory rights is void and unenforceable — it must not appear in your terms.",
+      "fix": "Remove blanket no-refund language; state refund eligibility (event cancellation, faulty service, statutory rights) instead.",
+      "assert": {
+        "find": "all sales (are )?final|no refunds?,?\\s+(whatsoever|under any circumstances?|no exceptions|ever\\b)|no refunds? (will be|are) (made|given|issued|provided|offered|accepted)|strictly non[-_ ]?refundable|all (tickets|sales|purchases|fees|payments) are non[-_ ]?refundable|non[-_ ]?refundable and non[-_ ]?(transferable|exchangeable)|no returns,? no refunds",
+        "in": [
+          "**/terms/**/*.{ts,tsx,md,mdx}",
+          "**/*{Terms,Refund,Policy,Disclaimer}*.{ts,tsx}",
+          "lib/compliance/**/*.{ts,tsx}",
+          "legal/**/*.{md,mdx}"
+        ],
+        "expect": "absent"
+      }
+    },
+    {
+      "id": "fccpc.refund-policy-present",
+      "standard": "Right to refund / redress must be disclosed (FCCPA s.120-122)",
+      "severity": "high",
+      "surface": "any",
+      "intent": "A clear refund / cancellation policy must be available to the consumer (e.g. when an event is cancelled or rescheduled).",
+      "fix": "Publish a refund/cancellation policy covering cancellations, reschedules, and faulty-service refunds.",
+      "assert": {
+        "find": "refund[-_ ]?(policy|eligib|process|request)|cancellation policy|refundPolicy|right to (cancel|a refund)|cancel.*refund",
+        "in": [
+          "**/terms/**/*.{ts,tsx,md,mdx}",
+          "**/*{Refund,Cancel,Terms}*.{ts,tsx}",
+          "lib/compliance/**/*.{ts,tsx}",
+          "src/**/*refund*.ts",
+          "{docs,legal}/**/*.{md,mdx}"
+        ],
+        "expect": "present"
+      }
+    },
+    {
+      "id": "fccpc.no-drip-pricing",
+      "standard": "No drip pricing — total price incl. fees shown before payment (FCCPA s.114-115)",
+      "severity": "high",
+      "surface": "any",
+      "intent": "The total price including service/booking fees must be disclosed before the consumer commits — fees revealed only at the final step (drip pricing) is a misleading practice.",
+      "fix": "Compute and display the all-in total (ticket + service/booking fee) on the pricing/checkout surface before payment.",
+      "assert": {
+        "allInFile": ["(service|booking|platform|processing)[_-]?fee", "total"],
+        "in": [
+          "**/*{fee,Fee,checkout,Checkout,pricing,Pricing}*.{ts,tsx}",
+          "**/{checkout,booking,ticket-purchase}/**/*.{ts,tsx}",
+          "lib/*fee*.{ts,tsx}"
+        ],
+        "within": 60,
+        "expect": "present"
+      }
+    },
+    {
+      "id": "fccpc.explicit-terms-acceptance",
+      "standard": "Informed consent to terms — no pre-ticked acceptance (FCCPA s.114)",
+      "severity": "medium",
+      "surface": "any",
+      "intent": "The consumer must actively accept the terms at sign-up/checkout; acceptance must not be pre-ticked or buried.",
+      "fix": "Require an explicit, un-pre-ticked 'I accept the Terms' action at sign-up/checkout.",
+      "assert": {
+        "find": "(accept|agree)[^\\n]{0,30}(terms|conditions)|InlineTermsAcceptance|terms[_-]?accepted|acceptTerms|agreeToTerms",
+        "in": [
+          "**/{signup,sign-up,register,checkout,booking}/**/*.{ts,tsx}",
+          "**/*{Terms,Signup,Register,Checkout,Booking}*.{ts,tsx}",
+          "lib/compliance/**/*.{ts,tsx}"
+        ],
+        "expect": "present"
+      }
+    },
+    {
+      "id": "fccpc.terms-of-service-present",
+      "standard": "Plain, accessible terms of service (FCCPA s.114)",
+      "severity": "low",
+      "surface": "any",
+      "intent": "Clear terms of service / use must be published and accessible to the consumer.",
+      "fix": "Publish a terms-of-service page and link it from the footer and checkout.",
+      "assert": {
+        "find": "terms of (use|service)|TermsOfUse|terms[_-]?(and|&)[_-]?conditions|terms[_-]?of[_-]?use",
+        "in": [
+          "**/terms/**/*.{ts,tsx,md,mdx}",
+          "**/*{Terms}*.{ts,tsx}",
+          "{docs,legal}/**/*.{md,mdx}"
+        ],
+        "expect": "present"
+      }
+    }
+  ]
+}

package/src/packs/ng-firs.json

@@ -0,0 +1,77 @@
+{
+  "id": "ng-firs",
+  "title": "Nigeria Tax — VAT & WHT (FIRS / NRS)",
+  "authority": "Federal Inland Revenue Service",
+  "url": "https://firs.gov.ng/",
+  "rules": [
+    {
+      "id": "firs.vat-rate-7-5",
+      "standard": "VAT charged at the statutory 7.5% (VAT Act as amended)",
+      "severity": "medium",
+      "surface": "any",
+      "intent": "Where the platform charges VAT, it must use the statutory 7.5% rate, expressed as a single source-of-truth constant rather than a magic number.",
+      "fix": "Define a VAT_RATE = 0.075 constant and apply it consistently; do not hard-code other rates.",
+      "assert": {
+        "find": "VAT_RATE|vat[_-]?rate|0\\.075\\b|7\\.5\\s*%",
+        "in": [
+          "src/**/*{tax,Tax,vat,Vat,fee,Fee,payment,Payment,pricing}*.ts",
+          "**/*{fee,Fee,tax,Tax,vat,Vat,pricing,Pricing}*.{ts,tsx}",
+          "lib/*fee*.{ts,tsx}"
+        ],
+        "expect": "present"
+      }
+    },
+    {
+      "id": "firs.vat-on-commission",
+      "standard": "VAT applied to the platform commission / service fee",
+      "severity": "medium",
+      "surface": "any",
+      "intent": "VAT is due on the platform's commission/service fee — the fee computation should apply VAT to the commission line.",
+      "fix": "Apply VAT to the commission/service-fee line in the fee calculation and surface it on the invoice.",
+      "assert": {
+        "allInFile": ["commission|service[_-]?fee|platform[_-]?fee", "\\bvat\\b|\\btax\\b"],
+        "in": [
+          "src/**/*{fee,Fee,tax,Tax,commission,payment,seller}*.ts",
+          "**/*{fee,Fee,pricing,Pricing,commission}*.{ts,tsx}",
+          "lib/*fee*.{ts,tsx}"
+        ],
+        "within": 40,
+        "expect": "present"
+      }
+    },
+    {
+      "id": "firs.wht-on-payouts",
+      "standard": "Withholding tax handled on organiser payouts",
+      "severity": "medium",
+      "surface": "any",
+      "intent": "Where WHT applies to payouts to organisers/vendors, the payout pipeline should account for and record the withheld amount.",
+      "fix": "Add WHT handling to the payout calculation (compute, withhold, and record the WHT line per payout).",
+      "assert": {
+        "find": "withholding|\\bWHT\\b|wht[_-]?(tax|rate|amount)|tax[_-]?withheld",
+        "in": [
+          "src/{seller,paystack,payment,payment-history}/**/*.ts",
+          "src/**/*{payout,Payout,withholding}*.ts",
+          "**/*{payout,Payout,withholding,WHT}*.{ts,tsx}"
+        ],
+        "expect": "present"
+      }
+    },
+    {
+      "id": "firs.vat-invoice-issued",
+      "standard": "Tax invoice / VAT receipt issued to the buyer",
+      "severity": "low",
+      "surface": "any",
+      "intent": "A compliant tax invoice / VAT receipt should be issued for ticket purchases, showing the VAT charged.",
+      "fix": "Include the VAT line on generated receipts/invoices (PDF or email) and label it as a tax invoice.",
+      "assert": {
+        "find": "tax[_-]?invoice|vat[_-]?invoice|vat[_-]?receipt|invoice[^\\n]{0,30}(vat|tax)|receipt[^\\n]{0,30}vat",
+        "in": [
+          "src/pdf/**/*.ts",
+          "src/**/*{invoice,Invoice,receipt,Receipt,ticket-generator}*.ts",
+          "**/*{Invoice,Receipt}*.{ts,tsx}"
+        ],
+        "expect": "present"
+      }
+    }
+  ]
+}

package/src/packs/ng-ndpc.json

@@ -0,0 +1,189 @@
+{
+  "id": "ng-ndpc",
+  "title": "Nigeria Data Protection Act 2023 (NDPC)",
+  "authority": "Nigeria Data Protection Commission",
+  "url": "https://ndpc.gov.ng/",
+  "rules": [
+    {
+      "id": "ndpc.privacy-notice-present",
+      "standard": "Lawful processing — transparency / privacy notice (NDPA s.27)",
+      "severity": "high",
+      "surface": "privacy",
+      "intent": "A data subject must be given a privacy notice describing what personal data is collected, the legal basis, and their rights.",
+      "fix": "Publish a privacy notice/policy page and link it from sign-up, checkout, and the footer.",
+      "assert": {
+        "find": "privacy[_-]?(policy|notice)|PrivacyPolicy|data[_-]?protection[_-]?(policy|notice)",
+        "in": [
+          "**/privacy/**/*.{ts,tsx,md,mdx}",
+          "**/*{Privacy,privacy}*.{ts,tsx}",
+          "lib/compliance/**/*.{ts,tsx}",
+          "src/gdpr/**/*.ts",
+          "{docs,legal,compliance}/**/*.{md,mdx}"
+        ],
+        "expect": "present"
+      }
+    },
+    {
+      "id": "ndpc.consent-mechanism-optin",
+      "standard": "Consent must be freely given, specific and opt-in (NDPA s.26)",
+      "severity": "high",
+      "surface": "consent",
+      "intent": "Non-essential cookies/trackers and secondary processing need explicit opt-in consent — pre-ticked or implied consent does not meet the bar.",
+      "fix": "Add a consent banner/manager whose non-essential categories default to OFF until the user opts in.",
+      "assert": {
+        "find": "CookieBanner|CMP_STORAGE_KEY|useConsentSettings|consent[_-]?(banner|manager|settings|preferences)|ConsentSettings|update-consent",
+        "in": [
+          "**/{cmp,cookie,cookies,consent}/**/*.{ts,tsx}",
+          "**/*{Cookie,Consent}*.{ts,tsx}",
+          "**/useConsent*.{ts,tsx}",
+          "src/**/*{consent,Consent}*.ts"
+        ],
+        "expect": "present"
+      }
+    },
+    {
+      "id": "ndpc.consent-granular-purposes",
+      "standard": "Specific consent per purpose (NDPA s.26(2))",
+      "severity": "medium",
+      "surface": "consent",
+      "intent": "Consent must be collected per processing purpose (e.g. analytics, marketing) rather than as one blanket toggle.",
+      "fix": "Split consent into granular categories (analytics, marketing/advertising, functional) the user can accept or reject independently.",
+      "assert": {
+        "allInFile": ["consent|cookie", "analytic|marketing|advertis|functional|necessary"],
+        "in": [
+          "**/{cmp,cookie,cookies,consent}/**/*.{ts,tsx}",
+          "**/*{Cookie,Consent}*.{ts,tsx}",
+          "src/**/*{consent,Consent}*.ts"
+        ],
+        "within": 40,
+        "expect": "present"
+      }
+    },
+    {
+      "id": "ndpc.data-subject-rights",
+      "standard": "Data subject rights — access, portability, erasure (NDPA s.34-37)",
+      "severity": "high",
+      "surface": "any",
+      "intent": "Data subjects must be able to access/export their data and request deletion (right to erasure).",
+      "fix": "Expose export-data, data-access-request, and delete-account flows wired to a fulfilment workflow.",
+      "assert": {
+        "find": "export[_-]?(user[_-]?)?data|delete[_-]?account|data[_-]?access[_-]?request|right[_-]?to[_-]?(erasure|access|portability)|DataAccessRequest|GDPRDataManagement",
+        "in": [
+          "src/gdpr/**/*.ts",
+          "**/{gdpr,settings}/**/*.{ts,tsx}",
+          "**/*{GDPR,Gdpr,DataAccess,DeleteAccount,ExportData}*.{ts,tsx}",
+          "lib/compliance/**/*.{ts,tsx}"
+        ],
+        "expect": "present"
+      }
+    },
+    {
+      "id": "ndpc.security-encryption",
+      "standard": "Security of processing — appropriate technical measures (NDPA s.39)",
+      "severity": "medium",
+      "surface": "any",
+      "intent": "Personal data must be protected with appropriate technical measures such as encryption of sensitive fields at rest.",
+      "fix": "Encrypt sensitive personal data (PII, contact details) at rest and hash credentials.",
+      "assert": {
+        "find": "createCipheriv|DataEncryption|encrypt(ion)?[_-]?(service|key|at[_-]?rest)|RecipientPrivacy|bcrypt",
+        "in": [
+          "src/security/**/*.ts",
+          "src/**/*{encryption,Encryption,privacy}*.ts",
+          "**/*{Encryption,DataEncryption}*"
+        ],
+        "expect": "present"
+      }
+    },
+    {
+      "id": "ndpc.retention-and-erasure-lifecycle",
+      "standard": "Storage limitation — retention & deletion (NDPA s.24(1)(e))",
+      "severity": "medium",
+      "surface": "any",
+      "intent": "Personal data must not be kept longer than necessary — a retention/soft-delete + scheduled purge lifecycle should exist.",
+      "fix": "Implement soft-delete with a scheduled hard-purge after the retention window, and document the retention period.",
+      "assert": {
+        "find": "soft[_-]?delete|data[_-]?retention|retention[_-]?(period|policy|window)|purge|scheduled.*(delete|purge)|deleteAfter",
+        "in": [
+          "src/soft-delete/**/*.ts",
+          "src/common/*soft-delete*.ts",
+          "src/scheduled-tasks/**/*.ts",
+          "**/*{soft-delete,softDelete,retention,Retention}*"
+        ],
+        "expect": "present"
+      }
+    },
+    {
+      "id": "ndpc.ndpa-localized",
+      "standard": "Applicable law — Nigeria Data Protection Act 2023, not only foreign regimes",
+      "severity": "high",
+      "surface": "governance",
+      "intent": "A platform processing Nigerian data subjects must apply the NDPA 2023 / NDPC framework — a GDPR-only privacy posture is not sufficient.",
+      "fix": "Reference the NDPA 2023 / NDPC explicitly in the privacy notice and compliance docs, alongside any GDPR text.",
+      "assert": {
+        "find": "\\bNDPA\\b|\\bNDPC\\b|Nigeria[n]? Data Protection|Data Protection Act,?\\s*2023|nigeria[_-]?data[_-]?protection",
+        "in": [
+          "lib/compliance/**/*.{ts,tsx}",
+          "**/privacy/**/*.{ts,tsx,md,mdx}",
+          "**/*{Privacy,privacy}*.{ts,tsx}",
+          "src/gdpr/**/*.ts",
+          "{docs,legal,compliance}/**/*.{md,mdx}"
+        ],
+        "expect": "present"
+      }
+    },
+    {
+      "id": "ndpc.dpo-designated",
+      "standard": "Data Protection Officer — required for a Data Controller of Major Importance (NDPA s.32)",
+      "severity": "high",
+      "surface": "governance",
+      "intent": "A Data Controller of Major Importance must designate a Data Protection Officer and publish a contact route for data-protection queries.",
+      "fix": "Designate a DPO and publish a data-protection contact (e.g. privacy@/dpo@) in the privacy notice.",
+      "assert": {
+        "find": "data[_-]?protection[_-]?officer|\\bDPO\\b|dpo@|privacy@|protection[_-]?officer",
+        "in": [
+          "**/privacy/**/*.{ts,tsx,md,mdx}",
+          "lib/compliance/**/*.{ts,tsx}",
+          "**/*{Privacy,privacy}*.{ts,tsx}",
+          "src/gdpr/**/*.ts",
+          "{docs,legal,compliance}/**/*.{md,mdx}"
+        ],
+        "expect": "present"
+      }
+    },
+    {
+      "id": "ndpc.breach-notification-plan",
+      "standard": "Personal data breach notification within 72 hours (NDPA s.40)",
+      "severity": "medium",
+      "surface": "governance",
+      "intent": "There must be a documented breach-response plan that notifies the NDPC within 72 hours and affected data subjects without undue delay.",
+      "fix": "Add a breach-response runbook documenting the 72-hour NDPC notification and data-subject notification steps.",
+      "assert": {
+        "find": "breach[_-]?(notification|response|plan|runbook)|data breach|72[-_ ]?hour|incident[_-]?response",
+        "in": [
+          "{docs,legal,compliance,governance,security}/**/*.{md,mdx}",
+          "lib/compliance/**/*.{ts,tsx}",
+          "**/*{breach,Breach,incident,Incident}*"
+        ],
+        "expect": "present"
+      }
+    },
+    {
+      "id": "ndpc.cross-border-safeguards",
+      "standard": "Cross-border transfer safeguards & processor agreements (NDPA s.41-43)",
+      "severity": "medium",
+      "surface": "governance",
+      "intent": "Personal data sent to processors abroad (payments, email, analytics) needs an adequacy basis or contractual safeguards (a DPA per processor).",
+      "fix": "Document cross-border transfer bases and sign a Data Processing Agreement with each sub-processor; list sub-processors in the privacy notice.",
+      "assert": {
+        "find": "cross[_-]?border|international (data )?transfer|data[-_ ]processing[-_ ]agreement|\\bDPA\\b|sub[_-]?processor|standard contractual",
+        "in": [
+          "{docs,legal,compliance}/**/*.{md,mdx}",
+          "lib/compliance/**/*.{ts,tsx}",
+          "**/privacy/**/*.{ts,tsx,md,mdx}",
+          "**/*{processor,Processor,transfer,Transfer}*"
+        ],
+        "expect": "present"
+      }
+    }
+  ]
+}