Functional specification

This document describes what Countersign 1.0.0 does and where in the source code it does it. It is written from the code; where the two differ, the code is right and this document has a defect to report. File paths are relative to the application folder. Requirement identifiers and texts are those of requirements.json; the traceability matrix links each to its test.

Messages in code style inside quotation marks are the exact refusal texts the engine returns. Parts in angle brackets stand for values (a record id, a role name).

1. Structure of the software

lib/ contains no browser or server dependency. The browser (demo path and user interface), the server and the tests run the same engine code. In the demo path there is no server state: the browser keeps the audit trail in localStorage and runs the engine itself; nothing in this document about storage, sign-in or the server applies to it, and it must not hold regulated records.

2. Data model

2.1 Configuration (DomainConfig)

A permission is a record type id, definition, value@<record type id>, value@*, or * (every record type and every option level). In author only, also import and configure; * does not include these two.

2.2 Record (Rec) and version (Version)

A record is { id, type, versions[] }. The id is <prefix>-<number padded to four digits>, numbered per type from a counter that never goes back (nextId). Option definitions are OD-…, option values OV-….

Derived terms (functions in lib/engine.ts):

2.3 Built-in record types

2.4 State (Db)

{ config, configRev, records, counters, audit, people }. It is never stored. It is rebuilt by replay from the audit entries, in the server (Service.sync) and in the browser.

3. Workflow state machine

States of one version, and the commands that move it. "Author" is the version's author; "approver" is a person whose role grants approve for the record's type (for option values: at the value's level).

There is no command that deletes a version or a record, and none that changes an approved version's data.

4. Commands

Every command goes through act(db, actor, command, at, { auth }) in lib/engine.ts. It returns either a new state plus the audit entry, or { error }; on an error nothing is changed and nothing is written (FR-AUD-02).

4.1 Checks common to all commands

4.2 create

4.3 edit

4.4 confirm

4.5 approve (the electronic signature)

4.6 step-back

4.7 retire and remove

4.8 Reference protection (liveChildren, childBlock)

A record cannot be retired or removed, and a pending retire or remove cannot be approved, while a live record of a configured type refers to it through any reference field: "<name> still has <n> active record(s) that refer(s) to it (<ids>). Retire or move them before you retire it."

Option values are not counted as referring records: a record with option values set for it, and an option definition with values, can be retired or removed. Such values stop having any effect because resolution only considers live definitions and live targets (section 6).

4.9 import

4.10 configure

The reviewer is named in the command by the person running the tool. The engine checks only that the reviewer's id differs from the actor's; the reviewer does not sign in. See risk assessment, R-21.

4.11 propose-config, approve-config, reject-config, withdraw-config

The configuration change in two steps, available in the application, over HTTP and from the command-line tool. The state holds at most one waiting proposal (Db.proposal: the document, its hash, the hash of the configuration it was written against, the reason, the proposer, the time and the entry number); it is rebuilt by replay.

All four entries have recordId: "CONFIG", recordType: "config" and v: the revision under discussion.

configImpact(db, next) returns blockers and notices. Blockers (the change is refused): the id of the configuration changes; no role would hold configure; a record type with records that are not removed, or with option values set for its records, is dropped; a prefix changes after records existed; a field's type or reference target changes while the type has records; a field that holds a value in an active record (approved or pending version) is removed; a value in such a record would fail the field's new rules (choices, range, pattern); a field becomes unique while two such records share a value; a parent or group reference becomes required while a record has none; a reference to the own type becomes the parent while records are their own ancestor through it. Notices (accepted): a field becomes required while records have no value (they stay in effect; conformance reports them until completed); the order of inheritance of a type changes; a role is dropped. The complete table with messages is in Configuration.

4.12 Nested records

A parent reference may be optional (a record without it stands at the top level) and may point at its own record type. For such a type validate refuses a record that names itself as parent, or a parent that has the record among its own ancestors, counting the parents in approved and in pending versions (isAbove); the check runs on create, edit, confirm and approve. Revoking an approval (step-back) is refused if the version that would come back into effect puts the record under one of its descendants. chainFor (section 6) follows the records upwards and therefore covers any depth; every walk stops at a record it has seen.

5. Data validation (validate, fieldError, checkValue)

Validation runs on create, on edit, again on confirm and again on approve (FR-VAL-07), and on import.

6. Option resolution (lib/resolve.ts)

resolveFor(db, id) returns, for a record of a configured type whose effective version is active, the value of every live option definition:

1. Build the chain (chainFor): the record itself, then, for each of its reference fields with role parent or group in the order the fields appear in the configuration, the chain of the record that field points at (depth first, each record once). References are read from effective versions only.
2. For each live definition, start with the definition's default, source default.
3. Walk the chain from most specific to least specific. For each option value record set for that definition and that chain member:
   • if it has an open version, report it under pending (level, record, version, state, proposed value);
   • if it has no effective version or is not live, skip it;
   • if its approved value no longer passes checkValue against the definition, report it under invalid and skip it;
   • the first remaining value becomes the result, with source (the level), sourceId (the record it was set for), recordId and v (the option value record and version);
   • every later one is reported under shadowed.

Only approved, active values of live definitions on live targets are ever applied (FR-OPT-04, FR-OPT-05, FR-OPT-07).

7. Audit entry

One entry per accepted command, built in commit (lib/engine.ts).

The exact hash computation, what replay checks and how to verify independently are in Data integrity, sections 3 to 6.

8. Functional requirements by group

8.1 Configuration

checkConfig in lib/config.ts returns every problem of a document in reading order: schema version, slugs, reserved ids (definition, value, config, import, configure), duplicate ids and prefixes, field keys and types, select choices, reference targets, at most one parent and one group reference per type (a group must be required; a parent may be optional, and may point at its own type if it is optional), a name field that is a required text field, valid regular expressions, no cycle in the parent and group graph other than a parent reference of a type to itself, role ids, and known permissions. configure in lib/engine.ts applies the rules of section 4.10. configHash is the SHA-256 of the canonical JSON of the document; it is what countersign status, /api/health and the audit entry show. Without a configuration every other command is refused.

8.2 Workflow and four eyes

Implemented in act (cases edit, confirm, approve, step-back) and create in lib/engine.ts; see sections 3 and 4. The four-eyes rule is the single condition last.author === actor.id || last.confirmedBy === actor.id in the approve case and compares person ids as delivered by the identity provider. The minimum reason length is the constant REASON_MIN (3 characters after trimming).

8.3 Versions

Implemented in the edit case (new version on an approved record) and by effective, openVersion and versionLabel. Revoking an approval (step-back from Approved) makes the previous approved version effective again because effective picks the newest approved version; if there is none, nothing is in effect.

8.4 Data validation

Implemented in validate, fieldError and refError in lib/engine.ts; see section 5.

8.5 Options and inheritance

Definitions and values are validated in validate and checkValue; usageError prevents a definition from changing its type, removing a choice in use or narrowing a range below values in use ("These choices are in use and can't be removed or renamed: …", "These values in use fall outside the new range: …", "<n> value(s) is/are set for this option, so its type can't change."). Resolution is resolveFor in lib/resolve.ts; see section 6.

8.6 Retire and remove

Implemented in the retire/remove case of act, liveChildren and childBlock; see sections 4.7 and 4.8.

8.7 Audit trail

commit is the only place that creates an entry and it is reached only when every check has passed. act refuses a time earlier than the newest entry. The auth object is passed in by the server (App.act to Service.submit) from the session or the proxy headers, never from the request body, and is part of the hashed content.

8.8 Integrity

stable, hashEntry, replay, verifyChain in lib/engine.ts. replay re-runs each stored command as the stored actor at the stored time under the state built so far and requires the resulting entry's hash to equal the stored hash; it stops at the first entry that is unreadable, breaks a rule, or differs. Details in Data integrity.

8.9 Access control

canAuthor, canApprove, hasAdmin and granted in lib/config.ts. A person's permissions are the union of the roles named in their session that the configuration knows; unknown role ids grant nothing. Reading is not restricted by role: App.entries returns the whole trail to any signed-in person.

8.10 Sign-in and signatures

See section 9.

8.11 Storage

See section 10.

8.12 Migration

runMigration in lib/migrate.ts turns each source row into one command. Record types are ordered so that referenced types come first; references are translated from old identifiers to new record ids; cells are converted to the configured field type (number with . or , as decimal separator, dates in five formats, yes/no word lists, value maps). Every row ends as imported, existing (already imported from that system) or failed with the reason. Mode approved issues import commands; mode review issues create and confirm so that approvers sign each record here. The command-line tool always rehearses against a copy of the state first and writes nothing if the rehearsal refuses a row, unless --allow-partial is given; it writes a Markdown report with source file hashes, reconciliation totals and a sign-off table, a JSON report and a cross-reference CSV. parseCsv in lib/csv.ts reads RFC 4180 CSV with comma, semicolon or tab. See Migration.

8.13 Export

auditCsv in lib/present.ts writes one line per entry with the columns seq, at_utc, actor_id, actor_name, actor_roles, action, record_id, record_type, record_name, version, change, reason, signature_meaning, auth_method, auth_time, prev_hash, hash. signature_meaning is filled for approvals. Cells that start with =, +, -, @, tab or carriage return are prefixed with an apostrophe so that a spreadsheet does not run them as formulas. The CSV is a review aid: it summarises the change in words and does not contain the full before, after and command; the complete entries are in the JSON and JSON Lines exports (countersign export --what audit --format json|jsonl), which are the formats to archive and to verify.

8.14 Operation

See sections 9.5, 10 and 11.

8.15 User interface

The interface asks the engine which actions a person may take by running confirm, approve, step back, retire and remove as dry runs (allowedActions in lib/present.ts), so for these what is offered cannot disagree with what is enforced, and the reason shown is the engine's own message. Whether Edit is offered is decided by the same conditions written out a second time in allowedActions (an edit needs data, so it cannot be a dry run); its wording differs slightly from the engine's refusal, and the engine remains the authority when the edit is submitted. These requirements are verified by the end-to-end walkthrough scripts/guide-shots.mjs and by the manual cases of the OQ protocol, part B. See the User guide.

8.16 Documentation site

The documentation the application serves under /docs is rendered from the Markdown files of the repository when the site is built (server/docs.ts). The search index is one static file made from the same rendering, so a result always points at a heading that exists; the matching (lib/docs-search.ts) runs in the browser. Search, the list that follows the reader and the drawing of diagrams need JavaScript; the documents themselves do not.

9. Server behaviour

9.1 Settings (server/settings.ts)

All variables are prefixed COUNTERSIGN_. Without STORAGE the application is the demo.

Read directly by the PostgreSQL adapter (server/storage/postgres.ts): COUNTERSIGN_SKIP_MIGRATE=1 (do not run db/postgres.sql on start), COUNTERSIGN_SCHEMA_FILE (path of that file), COUNTERSIGN_DB_POOL (connections, default 5). Read by the tests only: COUNTERSIGN_TEST_DATABASE_URL.

settingsProblems lists what is missing; while the list is not empty the server answers 503 and serves nothing (FR-OPS-05). The authoritative operator documentation is Deployment.

9.2 Sign-in and session

9.3 Write requests (App.act)

Checks in this order; the first that fails answers.

The actor and the auth evidence are taken from the session or the proxy headers only; an actor in the body is ignored (FR-SIG-08). /auth/login?fresh=1 sends the person to the provider with max_age=0 and prompt=login.

9.4 Read requests

9.5 Service (server/service.ts)

• State: the replayed Db in the memory of each server process. Before every read and write sync asks the store for its head and replays any new entries through replay.
• Time: submit stamps the entry with the server's clock, or with the newest entry's time if the clock is behind it (FR-OPS-04). Clients never supply the time.
• Concurrency: one operation at a time per process; between processes the store accepts only an entry that continues the chain, and the loser re-reads and retries up to six times (FR-STO-05).
• Integrity fault: set when replay rejects an entry, when the store holds fewer entries than already read ("the store holds <n> entries, fewer than the <m> already read: entries were removed"), or when the newest entry's hash changed ("the newest entry in the store is not the one read before: the trail was rewritten"). From then on the process serves the state before the fault for reading and refuses every write with 503 "The audit trail failed its integrity check at entry #<n> (<message>). Changes are refused until it has been investigated." The fault is cleared only by restarting the process against a store that verifies (FR-OPS-02, FR-OPS-03).
• Scope of the running check: entries are verified when they are first read by a process. An entry altered in the store after a process has read it is found at the next start of a server or by countersign verify, not by the running process, unless the alteration changes the number of entries or the newest entry.
• Bootstrap: an empty store gets the configuration named by COUNTERSIGN_CONFIG as entry 1, written by actor system with auth.method system (FR-OPS-01).

10. Storage (server/storage/)

A store keeps audit entries and nothing else (Store interface in types.ts: init, head, read, append, close). append must refuse an entry whose seq is not head + 1 or whose prevHash is not the head's hash.

PostgreSQL schema: columns seq, at, actor, action, record_id, record_type, prev_hash, hash, entry (the entry as JSON text, exactly as hashed), inserted_at (the database's own clock, default now()). The application reads only entry (ordered by seq) and, for the head, seq and hash; the other columns are convenience copies for indexes and queries and are not covered by the hash chain. The view countersign_audit_trail offers one row per entry for reporting tools; it takes every column from the hashed entry text, not from the convenience columns, and adds signature_meaning and inserted_at. Trigger messages: "countersign: the audit trail is append-only (<operation> refused)" and "countersign: entry <seq> does not continue the chain". The server applies the schema on start unless COUNTERSIGN_SKIP_MIGRATE=1. See Storage.

The triggers stop the application's database role and ordinary users. They do not stop the table's owner or a superuser, who can disable or drop them; that is what the hash chain and head-hash anchoring are for.

11. Health and command-line tool

GET /api/health (App.health), no sign-in required:

Command-line tool (scripts/countersign.ts; npm run cli -- <command> in the standalone repository). It uses the same COUNTERSIGN_* variables and the same engine as the server.

Commands that write require --actor-id, --actor-name and --actor-roles. The entry records auth.method cli, the operating-system account and host as auth.issuer, and the time. The identity and roles are stated by the person running the tool and are not verified against the identity provider; control of who can run the tool with write access to the store is therefore a procedural and infrastructure control (risk assessment, R-20).