Countersign validation and audit pack
| Document id | CS-VAL-00 |
| Title | Validation and audit pack: front page |
| Version | 1.0 |
| Applies to | Countersign 1.0.0 |
| Status | Template supplied with the software; to be completed, reviewed and approved by the regulated user |
This folder holds the documents a regulated organisation needs to validate its own installation of Countersign and to answer an auditor's questions about it. They are templates: the facts about the software are filled in and match the source code of version 1.0.0; everything about your installation, your procedures and your people is left blank for you.
Nothing in this pack makes an installation "validated" or "compliant". Validation is something the regulated user does, for a defined intended use, on a configured installation, with approved documents and signed evidence.
1. What is in the pack
| Id | Document | What it is | Who completes it |
|---|---|---|---|
| CS-VAL-01 | Validation plan | Scope, roles, approach, deliverables, acceptance criteria | Validation lead, QA |
| CS-VAL-02 | User requirements | The 15 user requirements, rationale, tailoring, your additions | Process owner |
| CS-VAL-03 | Functional specification | What the software does and where in the code: data model, commands, state machine, audit entry | Supplied; review only |
| CS-VAL-04 | Risk assessment | Functional risk assessment (FMEA style) with technical and procedural controls | Validation lead, system owner, QA |
| CS-VAL-05 | Traceability matrix | UR to FR to test, generated by node scripts/trace.ts from requirements.json |
Generated; do not edit |
| CS-VAL-06 | IQ protocol | Installation qualification of your environment | System administrator, witnessed |
| CS-VAL-07 | OQ protocol | Operational qualification: automated suite, manual cases, database-level negative tests | Testers, reviewed by QA |
| CS-VAL-08 | PQ protocol | Performance qualification with your configuration and business scenarios | Process owner, key users |
| CS-VAL-09 | 21 CFR Part 11 and EU GMP Annex 11 mapping | Clause by clause: what the software supports, what stays with you, known gaps | Supplied; QA assesses |
| CS-VAL-10 | Data integrity and audit trail specification | ALCOA+ mapping, exact hash algorithm, independent verification, anchoring, review checklist | Supplied; QA assesses |
| CS-VAL-11 | SOP templates | Ten short procedures to adapt | Process owner, QA |
| CS-VAL-12 | Supplier assessment | Facts about the open-source project and a questionnaire to file | QA, purchasing or IT |
Related documents outside this folder, referred to throughout: Developer setup,
Configuration, Storage, Authentication,
Deployment, Operations, Architecture, API,
Migration, Security, User guide, and in the repository root
README.md, SECURITY.md and CHANGELOG.md.
2. How to use it
- Copy this folder into your document management system (or print it). The copies become your controlled documents; give them your own document numbers if your quality system requires it.
- Decide the intended use and write it into the validation plan, section 2.
- Tailor the user requirements: strike what does not apply, add your own, approve.
- Write and approve your configuration document (record types, fields, roles): see Configuration.
- Complete the risk assessment for your use; it decides how much of the OQ and PQ you run.
- Install the test environment and execute the IQ, then the OQ, then the PQ. Record actual results, deviations and signatures in the tables provided.
- Adapt and approve the procedures in SOP templates, and train the people named in them.
- Repeat the IQ (and the parts of OQ and PQ your plan requires) on the production environment.
- Write the validation summary report (your own document; the plan lists what it must contain) and release the system.
- Keep the system in its validated state: change control, audit trail review, head-hash anchoring, periodic review.
Blanks to fill are marked ______ or are empty table cells. Text in the "expected result" columns is quoted from the
software; if your installation shows something else, that is a deviation to record, not a typo to correct.
3. Who is responsible for what
| Subject | The software and its project provide | The regulated user must provide |
|---|---|---|
| Design | A rules engine in which every change is a command, every command writes one hash-chained audit entry, and state is the replay of the audit trail; described in the functional specification and Architecture | The decision that this design fits the intended use; the intended use itself |
| Requirements | 15 generic user requirements and 88 functional requirements in requirements.json | Their own approved user requirements, tailored from these |
| Verification of the software | Automated tests named after the requirement they verify; a generated traceability matrix; a test that fails when a requirement has no verification; a script that produces a dated execution report (node scripts/oq-report.ts) |
Execution of those tests on their own infrastructure, the signed report, and the manual and negative tests of the OQ |
| Configuration | A validator for configuration documents; four demo configurations | Their own configuration, reviewed and approved; qualification of that configuration (PQ) |
| Infrastructure | Storage adapters, a reviewable PostgreSQL schema, a health endpoint, a command-line tool | Servers, database, network, TLS, time synchronisation, backup, monitoring, and their qualification (IQ) |
| Identity | Sign-in through OpenID Connect; role mapping from token claims; a recent-sign-in rule for approvals | The identity provider, accounts, passwords and multi-factor rules, joiner/mover/leaver process, periodic access review |
| Procedures and training | Templates (SOP templates), a User guide | Approved procedures, training and training records |
| Records retention | Export of the audit trail, the records and the configuration in open formats | Retention periods, archiving, readability over the retention period, disposal |
| Regulatory assessment | A clause mapping with stated gaps (Part 11 and Annex 11) | The assessment itself and every regulatory decision |
| Supplier assurance | Public source code, licence, changelog, security contact; the facts in the supplier assessment | The supplier assessment decision. There is no vendor to audit, no warranty and no support contract unless you arrange one |
4. Software category (GAMP 5)
GAMP 5 is guidance, not regulation, and the category only steers how much lifecycle effort is appropriate. The categorisation below is a proposal for you to confirm in your validation plan.
| Component | Proposed category | Reasoning |
|---|---|---|
| Operating system, Node.js runtime, PostgreSQL, the identity provider | 1, infrastructure software | Established, commercially or community supported layers; qualified by recording versions and correct installation (IQ) |
| Countersign used as released, with your configuration document | 4, configured product | Record types, fields, hierarchy, roles and permissions are set through a configuration document, without programming; the workflow and audit rules are fixed in the engine and cannot be configured away |
| Your configuration document itself | The configuration of a category 4 product | It defines what the system holds and who may do what; it needs review, approval, version control and testing (PQ) |
| Countersign with source code changes of your own, a storage adapter of your own, or a changed database schema | 5, custom application | Once you change the code you are the developer of that version; the project's tests no longer speak for it without your own review, testing and code control |
Two points an auditor may raise:
- Category 4 normally assumes a supplier whose quality system can be assessed. Countersign is an open-source project without a certified quality system (see supplier assessment). The usual compensation is more verification by the user: run the complete automated suite yourself, review the functional specification against the code for the high-risk functions, and execute the manual and negative tests. This pack is built for that.
- The product is at version 1.0.0 and has no installed base to point to. Treat it as novel in your risk assessment.
5. Reading orders
For an auditor with 30 minutes
| Minutes | Read | To learn |
|---|---|---|
| 0 to 5 | This page, sections 3 and 4 | Who claims what |
| 5 to 12 | Data integrity, sections 2 to 5 | What an audit entry contains, how the hash chain works, how alteration is detected, what is not detected |
| 12 to 20 | Part 11 and Annex 11 mapping, the summary of gaps and the clauses you care about | Where the software helps and where procedures carry the load |
| 20 to 25 | Traceability matrix and the executed OQ report attached to the OQ protocol | That each requirement has a passed test |
| 25 to 30 | Risk assessment, rows with residual risk above low | What the organisation accepted and why |
Then ask the organisation to run countersign verify --expect-entry <n>:<hash> with their last anchor in front of you
(see
Data integrity, section 7) and to show the last audit trail review record.
For a validation lead
- This page.
- Functional specification and Architecture: understand the model before planning.
- Part 11 and Annex 11 mapping: read the gaps first; they shape your procedures.
- Risk assessment: adapt it, then decide the test scope.
- Validation plan and user requirements: write and approve.
- IQ, OQ, PQ: execute in that order.
- SOP templates and supplier assessment: complete in parallel.
- Data integrity: set up anchoring and the review routine before go-live.
6. Keeping the pack current
The pack describes Countersign 1.0.0. When you upgrade, compare CHANGELOG.md, regenerate the traceability matrix
(npm run trace), re-run the automated suite (npm run oq) and review each document here against the new version
under your change control (see the upgrade procedure in SOP templates).