Guard Uuid

UUID identifier-safety guard. Validates user-supplied UUID strings per RFC 9562 (May 2024 — obsoletes RFC 4122) and refuses non-RFC shapes that downstream parsers routinely misinterpret. KIND="identifier" — the gate consumes ctx.identifier (or ctx.uuid).

Threat catalog: wrong length / shape (canonical 36-char hyphenated, 32-char hyphenless, 38-char braced, or urn:uuid: prefixed — anything else is malformed); wrong character class (non-hex anywhere); invalid version field (RFC 9562 §4.2 defines 1-8; 0 and 9-F are reserved / unassigned and indicate hand-rolled or attacker-shaped IDs); variant bits (RFC 9562 §4.1 — only 10xx is the canonical variant; NCS-reserved 0xxx, Microsoft 110x, future 111x often indicate non-UUID payloads coerced into the slot); nil UUID (§5.9 all zeros — usually "no UUID set", masks missing-key bugs when passed through); max UUID (§5.10 all FF — sentinel with the same semantic risk as nil); urn:uuid: prefix smuggling; Microsoft GUID braces {...} smuggling; BIDI / zero-width / C0-control / null-byte universal-refuse.

Profiles: strict / balanced / permissive. Compliance postures: hipaa / pci-dss / gdpr / soc2.

b.guardUuid.validate(input, opts?) #

{
  profile:                "strict"|"balanced"|"permissive",
  compliancePosture: "hipaa"|"pci-dss"|"gdpr"|"soc2",
  bidiPolicy:             "reject"|"strip"|"audit"|"allow",
  controlPolicy:          "reject"|"strip"|"allow",
  nullBytePolicy:         "reject"|"strip"|"allow",
  zeroWidthPolicy:        "reject"|"strip"|"allow",
  formatPolicy:           "hyphenated"|"hyphenless"|"braced"|"urn"|"hyphenated-only"|"any",
  versionPolicy:          "reject-unassigned"|"audit"|"allow",
  variantPolicy:          "reject-non-rfc"|"audit"|"allow",
  nilPolicy:              "reject"|"audit"|"allow",
  maxPolicy:              "reject"|"audit"|"allow",
  urnPolicy:              "reject"|"audit"|"allow",
  maxBytes:               number,
}

Inspect a UUID string against the resolved profile and return { ok, issues }. Each issue carries kind / severity (critical | high | medium | low) / ruleId / snippet. Non-string input returns a single uuid.bad-input issue rather than throwing — callers that prefer an exception use b.guardUuid.sanitize.

var rv = b.guardUuid.validate("550e8400-e29b-41d4-a716-446655440000",
                              { profile: "strict" });
rv.ok;                                             // → true

var bad = b.guardUuid.validate("00000000-0000-0000-0000-000000000000",
                               { profile: "strict" });
bad.ok;                                            // → false
bad.issues[0].ruleId;                              // → "uuid.nil-uuid"

b.guardUuid.sanitize(input, opts?) #

{
  profile:                "strict"|"balanced"|"permissive",
  compliancePosture: "hipaa"|"pci-dss"|"gdpr"|"soc2",
  ...:                    same shape as b.guardUuid.validate opts,
}

Normalize a UUID to canonical hyphenated lowercase form. Strips Microsoft GUID braces {...} and the urn:uuid: prefix. Throws GuardUuidError when any critical or high issue fires (nil / max sentinel under reject, unassigned version, non-RFC variant). Use validate to inspect issues without throwing.

var safe = b.guardUuid.sanitize("urn:uuid:550E8400-E29B-41D4-A716-446655440000",
                                { profile: "balanced" });
safe;                                              // → "550e8400-e29b-41d4-a716-446655440000"

try {
  b.guardUuid.sanitize("ffffffff-ffff-ffff-ffff-ffffffffffff",
                       { profile: "strict" });
} catch (e) {
  e.code;                                          // → "uuid.max-uuid"
}

b.guardUuid.compliancePosture(name) #

Look up a compliance-posture overlay by name (one of "hipaa" / "pci-dss" / "gdpr" / "soc2"). Returns a fresh clone of the posture overlay so the caller may mutate it freely without disturbing the shared table. Throws GuardUuidError with code "uuid.bad-posture" when the name is not one this guard maps. Wired by gateContract.defineGuard through gateContract.lookupCompliancePosture, so the clone semantics and error code are identical across every guard in the family.

var posture = b.guardUuid.compliancePosture("hipaa");
posture;                                             // → overlay clone (mutable)

try {
  b.guardUuid.compliancePosture("not-a-regime");
} catch (e) {
  e.code;                                            // → "uuid.bad-posture"
}

b.guardUuid.buildProfile(opts) #

{
  extends:   string|string[],   // base profile name(s) to compose
  ...:       any guard key,      // inline override of resolved keys
}

Compose a derived profile from one or more named bases plus inline overrides, resolving names through this guard's own PROFILES table. opts.extends is a base profile name ("strict" / "balanced" / "permissive") or an array of names — later entries shadow earlier ones, and inline opts keys win last. Wired by gateContract.defineGuard through gateContract.makeProfileBuilder, so operator-defined profiles stay traceable to a baseline instead of a hand-typed dictionary.

var custom = b.guardUuid.buildProfile({ extends: "strict" });
custom;                                              // → composed profile object

b.guardUuid.loadRulePack(pack) #

Register an operator-supplied rule pack with this guard's rule-pack registry. The pack is identified by pack.id (a non-empty string) and stored for later dispatch by gates that opt in via opts.rulePackId. Returns the pack unchanged on success; throws GuardUuidError with code "uuid.bad-opt" when pack is missing or pack.id is not a non-empty string. Wired by gateContract.defineGuard through gateContract.makeRulePackLoader, so storage shape and validation are identical across the family.

var pack = b.guardUuid.loadRulePack({ id: "tenant-policy", rules: [] });
pack.id;                                             // → "tenant-policy"

b.guardUuid.gate(opts?) #

{
  profile:           string,    // one of PROFILES; default this guard's default
  compliancePosture: string,    // overlay one of hipaa/pci-dss/gdpr/soc2
  mode:              string,    // one of gateContract MODES; default "enforce"
}

Build the guard's request-boundary gate — a contract-shaped object exposing check(ctx) that host primitives call at their byte moment. This is the factory default chain: serve when no issue, audit-only for info / warn issues, and refuse for any high / critical issue, dispatched to the right ctx field by the guard's KIND. Wired by gateContract.defineGuard through gateContract.buildGuardGate; a guard whose gate diverges (a bespoke sanitize-and-reserialize chain, for example) ships its own gate block instead of this template.

var gate = b.guardUuid.gate({ profile: "strict" });
var decision = await gate.check({ bytes: Buffer.from("...") });
decision.action;                                     // → "serve" | "refuse" | …

b.guardUuid.resolveOpts(opts?) #

{
  profile:           string,    // one of PROFILES; default this guard's default
  compliancePosture: string,    // overlay one of hipaa/pci-dss/gdpr/soc2
}

Resolve caller opts against this guard's PROFILES + compliance-posture overlays into the fully-defaulted option set the guard runs on — the same resolution validate / sanitize / gate apply internally. Wired by gateContract.defineGuard from the guard's binding config (profiles / postures / defaults / error class), so a guard's bespoke gate calls resolveOpts instead of re-declaring the per-guard resolver wrapper. Throws GuardUuidError with code "uuid.bad-opt" / "uuid.bad-posture" on an unknown profile or posture name.

var resolved = b.guardUuid.resolveOpts({ profile: "strict" });
resolved.profile;                                    // → "strict"

Last updated 2026-08-08T16:39:49.652Z by seeder.