skills/docs/security-stack/security/srp/src/errors/errors.md

errors

(no submodules)

Purpose

This module hosts the stable error-code registry and the SrpError class for the @suaveplan/srp package. Every code listed here is thrown by at least one production path under src/ — the audit test in errors.test.ts enforces that contract so dead codes cannot accumulate. Consumers branch on error.code (a literal-typed SrpErrorCode) rather than parsing error.message, which keeps error-handling resilient across releases.

Features

• Frozen SRP_CODES registry via defineCodes("SRP", […]).
• Literal-typed SrpErrorCode union derived from the registry.
• SrpError extends SuaveplanError<SrpErrorCode> carrying the code on the instance.
• srpError(code, message, options) factory that prefixes the code into the message string so log scrapers and expect(...).toThrow(/SRP\./) matchers find a stable substring without inspecting .code.
• Each SrpError instance is instanceof SuaveplanError, so the global error-classification surface (OTel span events, structured logging) sees it without per-package wiring.

Usage: Basic Example

import { SRP_CODES, SrpError, srpError } from "@suaveplan/srp/errors";

throw srpError(SRP_CODES.AUTH_FAILED, "client M1 did not match expected M1");

Usage: Advanced Example

import { SrpError, SRP_CODES } from "@suaveplan/srp/errors";

try {
    runSrpHandshake();
} catch (err) {
    if (err instanceof SrpError && err.code === SRP_CODES.PUBLIC_KEY_INVALID) {
        // RFC 5054 §2.5.4 — abort the session and rotate ephemeral keys.
        return;
    }
    throw err;
}

API Reference

SRP_CODES

Frozen record mapping each reason to "SRP.<REASON>". Six codes:

• SRP.INVALID_PARAMS — malformed SrpParams, oversized PAD input, or other structural validation failure.
• SRP.PUBLIC_KEY_INVALID — A ≡ 0 mod N, B ≡ 0 mod N, or u ≡ 0 mod N.
• SRP.AUTH_FAILED — server rejected the client's M1.
• SRP.MUTUAL_AUTH_FAILED — client rejected the server's M2.
• SRP.GROUP_UNSUPPORTED — group parameters fail structural validation.
• SRP.HASH_UNSUPPORTED — hash algorithm outside {"SHA256", "SHA1"}.

SrpErrorCode

Literal-typed union of every value in SRP_CODES.

class SrpError extends SuaveplanError<SrpErrorCode>

Carries .code: SrpErrorCode. Constructor accepts (code, message, options?). The options.cause field, when an Error, threads through SuaveplanError's cause-chain machinery.

srpError(code, message, options?)

Factory returning an SrpError. Prefixes the message with ${code}: for stable substring matching. options.cause accepts any unknown and is only attached when it is an Error instance.

Implementation Notes

The registry is exhaustively audited at test time: errors.test.ts walks SRP_CODES, scans src/ for a matching throw site for each code, and fails if any code is unreachable. This forces every new code to either ship with a real production path or be removed from the registry. The audit deliberately excludes *.test.ts files so test-only fixtures cannot satisfy the contract.

srpError prefixes the code into the message because SuaveplanError's base constructor uses the messageKey argument for i18n resolution; in this package every code is internal and has a short English-only message, so prefixing keeps the substring stable while preserving the structured .code field. Callers that want a different presentation MAY construct SrpError directly.