@peopleware-pt/ciencia-id

Validation of the Ciência ID check digit (ISO/IEC 7064, MOD 17,16). Zero dependencies, Node 18+, TypeScript declarations included (parse returns a union narrowed by status).

Install

npm install @peopleware-pt/ciencia-id

Usage

const { isValid, parse, computeCheckDigit, normalize, format, SOURCES } = require("@peopleware-pt/ciencia-id");
// or: import { isValid, parse } from "@peopleware-pt/ciencia-id";

isValid("EA11-91C2-39D1");                 // true
computeCheckDigit("EA1191C239D");          // "1"  (11 hex digits in, check digit out; null if malformed)
normalize(" https://www.ciencia-id.pt/ea11-91c2-39d1\n"); // "EA1191C239D1"
format("ea1191c239d1");                    // "EA11-91C2-39D1"  (the check digit is not verified)
format("ea1191c239d1", true);              // "ciencia-id.pt/EA11-91C2-39D1"
parse("EA11-91C2-39D1");
// {
//   status: "CIENCIA_ID", reason: null, warnings: [],
//   internalValidation: "EA",
//   source: { code: "1", known: true, name: "Ciência ID", domain: "ciencia-id.pt" },
//   uniqueId: "191C239D", uniqueIdDecimal: 421274525,
//   checkDigit: "1", indicatedDomain: null
// }

Input is trimmed of ASCII whitespace, upper-cased (ASCII only), stripped of an optional http(s)://, www. and ciencia-id.pt/ or estudante-id.pt/ prefix, and stripped of -. Anything else (en dashes, no-break spaces, inner spaces, ligatures) is rejected as FORMAT.

Non-string input (numbers, arrays, Buffer, objects) is treated as invalid (FORMAT), like null.

Statuses

| status | Meaning | | --- | --- | | CIENCIA_ID | Well-formed, check digit correct, known source. | | UNKNOWN_SOURCE | Well-formed, check digit correct, but the source code (3rd digit) is not known to this library. It may be a typo that the check digit happened to miss, or the library may be out of date. | | INVALID | See reason: FORMAT (not 12 hex digits after normalisation) or CHECK_DIGIT (check digit mismatch). All other fields are null. |

CIENCIA_ID does not guarantee that the ID was ever issued, nor does it verify the internal validation digits; it only says the check digit is consistent.

DOMAIN_MISMATCH

warnings contains "DOMAIN_MISMATCH" when the input carried a domain prefix that differs from the domain of the ID's source (for example estudante-id.pt/EA11-91C2-39D1). The warning does not change status or isValid. For an unknown source, any domain prefix counts as a mismatch.

Historical note

The check-digit mechanism was designed for two identifiers: Ciência ID (in use, source 1) and Estudante-ID, which was never implemented, has no source code assigned and will not get one. The library is named after Ciência ID, but the algorithm also supports Estudante-ID, for historical reasons: the estudante-id.pt/ prefix is accepted on input and yields the DOMAIN_MISMATCH warning.

Known limitation

The check digit detects every single-character substitution, but not every adjacent transposition: at each position exactly one of the 120 possible pairs of distinct hex digits can be swapped undetected (about 1 in 120). In particular, swapping the last data digit and the check digit goes undetected when they are 0 and 1, so an ID ending in 01 and the same ID ending in 10 both validate (e.g. 1C11-C5F1-BC01 and 1C11-C5F1-BC10).

License

Apache-2.0. See LICENSE and NOTICE.