@skrr-ai/auth-core 0.1.2

package/dist/esm/pkce.d.ts

@@ -0,0 +1,62 @@
+/** Currently the only PKCE challenge method we support. See file header. */
+export type PkceChallengeMethod = 'S256';
+/**
+ * Generate a cryptographically random `code_verifier`. Returns a 43-char
+ * base64url string from 32 bytes of CSPRNG output — the RFC 7636 lower
+ * bound and the recommended size for new implementations (256 bits of
+ * entropy).
+ *
+ * The verifier MUST be kept in CLI process memory only — never
+ * persisted, never logged, never sent over the wire until the
+ * token-exchange step. Treat it the same as a private key.
+ */
+export declare function generateVerifier(): string;
+/**
+ * Compute the `code_challenge` for a given verifier using S256 (the only
+ * supported method). Returns `base64url(SHA-256(ASCII(verifier)))`, no
+ * padding.
+ *
+ * Throws RangeError on a verifier that violates RFC 7636 §4.1 (length
+ * or charset). Throws TypeError on non-string input. Throws Error on an
+ * unsupported method. The throw policy is deliberate: misuse here is
+ * always a programmer bug, not a runtime condition the caller should
+ * recover from. Server-side verifier validation in `verifyChallenge()`
+ * has the opposite policy (return false, no oracle).
+ */
+export declare function challenge(verifier: string, method?: PkceChallengeMethod): string;
+/**
+ * Generate a CSRF-style `state` parameter for the auth flow. 32 bytes of
+ * CSPRNG output, base64url-encoded (43 chars). Used to bind the server's
+ * redirect back to the originating CLI process — a callback that doesn't
+ * echo this exact state is rejected by the local server in
+ * `loginLocalhost.ts`.
+ *
+ * Independent of PKCE: state defends against cross-site / replay attacks
+ * on the redirect path; PKCE defends against intercepted auth codes at
+ * the token-exchange step. Both are required.
+ */
+export declare function generateState(): string;
+/**
+ * Constant-time equality check for two PKCE-related strings (state,
+ * code_challenge, computed challenge). Returns false on length mismatch
+ * or non-string input — both signals are public (lengths are not
+ * secret), so the early return does not leak.
+ *
+ * Uses `crypto.timingSafeEqual` over UTF-8 bytes. Wrapped in try/catch
+ * because timingSafeEqual throws on mismatched buffer lengths even after
+ * our length pre-check (defensive — protects against a future caller
+ * passing pre-converted Buffers of different shapes).
+ */
+export declare function safeEqual(a: string, b: string): boolean;
+/**
+ * Server-side: verify a presented `code_verifier` against the stored
+ * `code_challenge` using the declared method. Used at
+ * `/api/auth/cli-token-exchange` to complete the PKCE proof.
+ *
+ * Returns false on ANY input failure (bad method, malformed verifier,
+ * mismatch). Never throws. The server treats a verifier mismatch and a
+ * malformed verifier identically — both surface as a 400 with no
+ * detail — so an attacker probing the endpoint cannot distinguish
+ * "well-formed-but-wrong" from "malformed" and use that as an oracle.
+ */
+export declare function verifyChallenge(verifier: string, storedChallenge: string, method?: PkceChallengeMethod): boolean;

package/dist/esm/pkce.js

@@ -0,0 +1,148 @@
+/**
+ * pkce.ts — RFC 7636 Proof Key for Code Exchange primitives.
+ *
+ * Used by the localhost-callback login flow (Phase H.0,
+ * docs/daemon-auth-roadmap.md) to bind an authorization code to the
+ * originating CLI process. The CLI generates a random `code_verifier`,
+ * sends only its SHA-256 hash (`code_challenge`) to the server in the
+ * auth-init request, then proves possession of the verifier when
+ * redeeming the auth code at `/api/auth/cli-token-exchange`. An attacker
+ * who intercepts the redirect (malicious browser extension, local-host
+ * port race, screen-recorded URL bar) cannot redeem the code without
+ * the verifier — which never leaves the CLI process memory.
+ *
+ * No npm deps — `node:crypto` only. `auth-core` is destined for external
+ * publication (Phase P) and every transitive dep multiplies supply-chain
+ * surface. The PKCE primitives are ~50 lines of pure crypto and we
+ * control them end-to-end with full test coverage including the spec's
+ * known-answer vectors.
+ *
+ * Conformance:
+ *   - RFC 7636 §4.1: code_verifier is 43–128 chars from the unreserved
+ *     character set (RFC 3986 §2.3). We generate the recommended 43-char
+ *     length from 32 bytes of CSPRNG output.
+ *   - RFC 7636 §4.2: code_challenge for S256 is
+ *     base64url(SHA-256(ASCII(verifier))), no padding.
+ *   - RFC 7636 §4.6 verification: server recomputes the challenge from
+ *     the verifier and compares constant-time.
+ *   - RFC 7636 Appendix B known-answer vectors covered in pkce.test.ts.
+ *
+ * Method `'plain'` is intentionally NOT implemented. The spec allows it
+ * for clients that cannot SHA-256, but every viable PKCE client today
+ * can — supporting plain would be a foot-gun for future callers and
+ * complicates the server-side verifier (it would need a second branch).
+ * If a future caller genuinely needs plain, add it explicitly with a
+ * security-review gate.
+ */
+import crypto from 'node:crypto';
+/** RFC 7636 §4.1 lower bound for code_verifier length. */
+const VERIFIER_MIN_LEN = 43;
+/** RFC 7636 §4.1 upper bound for code_verifier length. */
+const VERIFIER_MAX_LEN = 128;
+/**
+ * Char class allowed by RFC 7636 §4.1 — the RFC 3986 unreserved set.
+ * Anchored regex: any character outside this set anywhere in the string
+ * fails. We validate on every challenge() call so a caller that hand-
+ * rolls a verifier (rather than using `generateVerifier()`) cannot
+ * silently feed garbage in.
+ */
+const VERIFIER_CHARSET = /^[A-Za-z0-9\-._~]+$/;
+/**
+ * Generate a cryptographically random `code_verifier`. Returns a 43-char
+ * base64url string from 32 bytes of CSPRNG output — the RFC 7636 lower
+ * bound and the recommended size for new implementations (256 bits of
+ * entropy).
+ *
+ * The verifier MUST be kept in CLI process memory only — never
+ * persisted, never logged, never sent over the wire until the
+ * token-exchange step. Treat it the same as a private key.
+ */
+export function generateVerifier() {
+    // 32 random bytes → base64url (no padding) = 43 chars exactly.
+    return crypto.randomBytes(32).toString('base64url');
+}
+/**
+ * Compute the `code_challenge` for a given verifier using S256 (the only
+ * supported method). Returns `base64url(SHA-256(ASCII(verifier)))`, no
+ * padding.
+ *
+ * Throws RangeError on a verifier that violates RFC 7636 §4.1 (length
+ * or charset). Throws TypeError on non-string input. Throws Error on an
+ * unsupported method. The throw policy is deliberate: misuse here is
+ * always a programmer bug, not a runtime condition the caller should
+ * recover from. Server-side verifier validation in `verifyChallenge()`
+ * has the opposite policy (return false, no oracle).
+ */
+export function challenge(verifier, method = 'S256') {
+    if (method !== 'S256') {
+        throw new Error(`Unsupported PKCE challenge method: ${String(method)} (only 'S256' is allowed)`);
+    }
+    if (typeof verifier !== 'string') {
+        throw new TypeError('verifier must be a string');
+    }
+    if (verifier.length < VERIFIER_MIN_LEN || verifier.length > VERIFIER_MAX_LEN) {
+        throw new RangeError(`verifier length ${verifier.length} outside RFC 7636 §4.1 bounds [${VERIFIER_MIN_LEN}, ${VERIFIER_MAX_LEN}]`);
+    }
+    if (!VERIFIER_CHARSET.test(verifier)) {
+        throw new RangeError('verifier contains characters outside RFC 7636 unreserved set ([A-Za-z0-9-._~])');
+    }
+    const hash = crypto.createHash('sha256').update(verifier, 'ascii').digest();
+    return hash.toString('base64url');
+}
+/**
+ * Generate a CSRF-style `state` parameter for the auth flow. 32 bytes of
+ * CSPRNG output, base64url-encoded (43 chars). Used to bind the server's
+ * redirect back to the originating CLI process — a callback that doesn't
+ * echo this exact state is rejected by the local server in
+ * `loginLocalhost.ts`.
+ *
+ * Independent of PKCE: state defends against cross-site / replay attacks
+ * on the redirect path; PKCE defends against intercepted auth codes at
+ * the token-exchange step. Both are required.
+ */
+export function generateState() {
+    return crypto.randomBytes(32).toString('base64url');
+}
+/**
+ * Constant-time equality check for two PKCE-related strings (state,
+ * code_challenge, computed challenge). Returns false on length mismatch
+ * or non-string input — both signals are public (lengths are not
+ * secret), so the early return does not leak.
+ *
+ * Uses `crypto.timingSafeEqual` over UTF-8 bytes. Wrapped in try/catch
+ * because timingSafeEqual throws on mismatched buffer lengths even after
+ * our length pre-check (defensive — protects against a future caller
+ * passing pre-converted Buffers of different shapes).
+ */
+export function safeEqual(a, b) {
+    if (typeof a !== 'string' || typeof b !== 'string')
+        return false;
+    if (a.length !== b.length)
+        return false;
+    try {
+        return crypto.timingSafeEqual(Buffer.from(a, 'utf8'), Buffer.from(b, 'utf8'));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Server-side: verify a presented `code_verifier` against the stored
+ * `code_challenge` using the declared method. Used at
+ * `/api/auth/cli-token-exchange` to complete the PKCE proof.
+ *
+ * Returns false on ANY input failure (bad method, malformed verifier,
+ * mismatch). Never throws. The server treats a verifier mismatch and a
+ * malformed verifier identically — both surface as a 400 with no
+ * detail — so an attacker probing the endpoint cannot distinguish
+ * "well-formed-but-wrong" from "malformed" and use that as an oracle.
+ */
+export function verifyChallenge(verifier, storedChallenge, method = 'S256') {
+    try {
+        const computed = challenge(verifier, method);
+        return safeEqual(computed, storedChallenge);
+    }
+    catch {
+        return false;
+    }
+}

package/dist/esm/recoveryCode.d.ts

@@ -0,0 +1,61 @@
+/**
+ * recoveryCode.ts — 1Password-style printable account-recovery code format.
+ *
+ * Format: 11 groups × 5 base32 chars = 55 chars, encoding 32 bytes (256 bits).
+ * Example: W7K2J-X9P3M-R6Y4Q-T8N2A-C5VWB-D3FHK-M4LPZ-Q6RSX-Y2JGE-B7NHC-E9KWF
+ *
+ * Properties:
+ *   (a) 11 groups × 5 chars = 55 chars total (encodes 32 bytes exactly,
+ *       padded to 56 base32 chars → 55 significant chars + 1 trailing
+ *       partial group from the 256-bit boundary math)
+ *   (b) H15 — strict alphabet: no confusable-char substitution (0/1/8/9 are
+ *       never in valid output; silent mapping shrinks key space and masks
+ *       brute-force telemetry). Whitespace and dashes stripped; mixed-case
+ *       tolerated. Any character outside A-Z2-7 after normalization is
+ *       rejected with code INVALID_RECOVERY_CODE_ALPHABET.
+ *   (c) No checksum — intentional, matches 1Password/Happy format;
+ *       user discovers a typo immediately on failed redemption
+ *
+ * RFC 4648 base32 alphabet: A–Z, 2–7.
+ * No npm deps — Node.js built-ins only, same philosophy as pkce.ts.
+ */
+/**
+ * Format 32 raw bytes as a printable recovery code.
+ *
+ * @param bytes — exactly 32 bytes of entropy
+ * @returns "AAAAA-BBBBB-CCCCC-...-KKKKK" (55 chars + 10 dashes = 65 chars)
+ * @throws if input is not 32 bytes
+ */
+export declare function formatRecoveryCode(bytes: Buffer | Uint8Array): string;
+/**
+ * Parse a formatted (or loosely-typed) recovery code back to its 32 raw bytes.
+ *
+ * Tolerant of:
+ *   - whitespace (spaces, newlines, tabs)
+ *   - dashes (group separators in the printed format)
+ *   - lowercase
+ *
+ * H15 — strict alphabet: confusable-char substitution (0/1/8/9) is NOT
+ * applied. Any character outside A-Z2-7 after stripping whitespace/dashes
+ * and uppercasing throws with code INVALID_RECOVERY_CODE_ALPHABET.
+ *
+ * M3 — exact-length check: after normalization the cleaned string must be
+ * exactly TOTAL_CHARS (55) characters. Shorter inputs would produce fewer
+ * than 32 meaningful decoded bytes; longer inputs indicate a malformed or
+ * concatenated code. Both are rejected.
+ *
+ * @throws with a descriptive message on invalid characters or wrong length
+ */
+export declare function parseRecoveryCode(formatted: string): Buffer;
+/**
+ * Normalize any input form to the canonical 11-group display format.
+ * Applies the same confusable-char + whitespace tolerance as parseRecoveryCode.
+ *
+ * @throws the same errors as parseRecoveryCode on invalid input
+ */
+export declare function normalizeRecoveryCode(input: string): string;
+/**
+ * Non-throwing validity check.
+ * Returns true iff the input can be successfully parsed as a 32-byte recovery code.
+ */
+export declare function isValidRecoveryCode(input: string): boolean;

package/dist/esm/recoveryCode.js

@@ -0,0 +1,207 @@
+/**
+ * recoveryCode.ts — 1Password-style printable account-recovery code format.
+ *
+ * Format: 11 groups × 5 base32 chars = 55 chars, encoding 32 bytes (256 bits).
+ * Example: W7K2J-X9P3M-R6Y4Q-T8N2A-C5VWB-D3FHK-M4LPZ-Q6RSX-Y2JGE-B7NHC-E9KWF
+ *
+ * Properties:
+ *   (a) 11 groups × 5 chars = 55 chars total (encodes 32 bytes exactly,
+ *       padded to 56 base32 chars → 55 significant chars + 1 trailing
+ *       partial group from the 256-bit boundary math)
+ *   (b) H15 — strict alphabet: no confusable-char substitution (0/1/8/9 are
+ *       never in valid output; silent mapping shrinks key space and masks
+ *       brute-force telemetry). Whitespace and dashes stripped; mixed-case
+ *       tolerated. Any character outside A-Z2-7 after normalization is
+ *       rejected with code INVALID_RECOVERY_CODE_ALPHABET.
+ *   (c) No checksum — intentional, matches 1Password/Happy format;
+ *       user discovers a typo immediately on failed redemption
+ *
+ * RFC 4648 base32 alphabet: A–Z, 2–7.
+ * No npm deps — Node.js built-ins only, same philosophy as pkce.ts.
+ */
+const BASE32_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ234567';
+/** Number of base32 characters needed to encode 32 bytes.
+ *  256 bits / 5 bits-per-char = 51.2 → ceil = 52 significant chars.
+ *  But we split into 11×5=55 groups, so the last group is padded.
+ *  We always produce exactly 55 output chars (some trailing bits zeroed). */
+const TOTAL_CHARS = 55; // 11 groups × 5 chars
+const GROUP_COUNT = 11;
+const GROUP_SIZE = 5;
+const DECODED_BYTE_LENGTH = 32;
+// Build a reverse-lookup table: char → 5-bit value (for fast decode).
+const CHAR_TO_VALUE = new Uint8Array(128).fill(0xff);
+for (let i = 0; i < BASE32_ALPHABET.length; i++) {
+    CHAR_TO_VALUE[BASE32_ALPHABET.charCodeAt(i)] = i;
+}
+/**
+ * Convert raw bytes to a base32 string (no padding chars, no dashes).
+ * Produces exactly TOTAL_CHARS characters for 32-byte input.
+ */
+function bytesToBase32(bytes) {
+    const result = [];
+    let buffer = 0;
+    let bufferBits = 0;
+    for (const byte of bytes) {
+        buffer = (buffer << 8) | byte;
+        bufferBits += 8;
+        while (bufferBits >= 5) {
+            bufferBits -= 5;
+            result.push(BASE32_ALPHABET[(buffer >> bufferBits) & 0x1f]);
+        }
+    }
+    // Flush remaining bits — pad with zero bits on the right.
+    if (bufferBits > 0) {
+        result.push(BASE32_ALPHABET[(buffer << (5 - bufferBits)) & 0x1f]);
+    }
+    // Extend to TOTAL_CHARS by repeating the last char (deterministic, lossless
+    // since parseRecoveryCode only uses the first 32 decoded bytes).
+    while (result.length < TOTAL_CHARS) {
+        result.push(BASE32_ALPHABET[0]); // 'A' = zero padding
+    }
+    return result.slice(0, TOTAL_CHARS).join('');
+}
+/**
+ * Convert a base32 string (stripped of dashes/whitespace) back to bytes.
+ * Returns exactly as many bytes as the bits allow; callers validate length.
+ */
+function base32ToBytes(chars) {
+    const bytes = [];
+    let buffer = 0;
+    let bufferBits = 0;
+    for (let i = 0; i < chars.length; i++) {
+        const code = chars.charCodeAt(i);
+        const value = code < 128 ? CHAR_TO_VALUE[code] : 0xff;
+        if (value === 0xff) {
+            throw new Error(`Invalid base32 character: '${chars[i]}'`);
+        }
+        buffer = (buffer << 5) | value;
+        bufferBits += 5;
+        if (bufferBits >= 8) {
+            bufferBits -= 8;
+            bytes.push((buffer >> bufferBits) & 0xff);
+        }
+    }
+    return Buffer.from(bytes);
+}
+/**
+ * Strip formatting (whitespace + dashes) and uppercase.
+ *
+ * H15 — strict alphabet. The previous confusable-char substitution map
+ * (0→O, 1→I, 8→B, 9→G) is removed. Digits 0/1/8/9 are never emitted by
+ * formatRecoveryCode; accepting them silently shrinks the effective key
+ * space and makes brute-force attempts indistinguishable from alphabet
+ * errors in telemetry. Any character outside A-Z2-7 after normalization
+ * is rejected; callers receive a structured error with code
+ * INVALID_RECOVERY_CODE_ALPHABET so they can surface a clear UX hint
+ * without leaking which validation step failed at the server surface.
+ *
+ * Returns the cleaned, uppercased string (no whitespace, no dashes).
+ * Throws with `code: 'INVALID_RECOVERY_CODE_ALPHABET'` on any illegal char.
+ */
+function normalizeRaw(input) {
+    const upper = input.toUpperCase().replace(/[\s-]/g, '');
+    for (let i = 0; i < upper.length; i++) {
+        const ch = upper[i];
+        const code = ch.charCodeAt(0);
+        if (code >= 128 || CHAR_TO_VALUE[code] === 0xff) {
+            const err = new Error('Recovery codes only contain letters A-Z and digits 2-7. Copy from where you stored it.');
+            err.code = 'INVALID_RECOVERY_CODE_ALPHABET';
+            throw err;
+        }
+    }
+    return upper;
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Format 32 raw bytes as a printable recovery code.
+ *
+ * @param bytes — exactly 32 bytes of entropy
+ * @returns "AAAAA-BBBBB-CCCCC-...-KKKKK" (55 chars + 10 dashes = 65 chars)
+ * @throws if input is not 32 bytes
+ */
+export function formatRecoveryCode(bytes) {
+    if (bytes.length !== DECODED_BYTE_LENGTH) {
+        throw new Error(`formatRecoveryCode: expected ${DECODED_BYTE_LENGTH} bytes, got ${bytes.length}`);
+    }
+    const input = bytes instanceof Buffer ? new Uint8Array(bytes) : bytes;
+    const base32 = bytesToBase32(input);
+    // Split into groups of GROUP_SIZE and join with dashes.
+    const groups = [];
+    for (let i = 0; i < GROUP_COUNT; i++) {
+        groups.push(base32.slice(i * GROUP_SIZE, (i + 1) * GROUP_SIZE));
+    }
+    return groups.join('-');
+}
+/**
+ * Parse a formatted (or loosely-typed) recovery code back to its 32 raw bytes.
+ *
+ * Tolerant of:
+ *   - whitespace (spaces, newlines, tabs)
+ *   - dashes (group separators in the printed format)
+ *   - lowercase
+ *
+ * H15 — strict alphabet: confusable-char substitution (0/1/8/9) is NOT
+ * applied. Any character outside A-Z2-7 after stripping whitespace/dashes
+ * and uppercasing throws with code INVALID_RECOVERY_CODE_ALPHABET.
+ *
+ * M3 — exact-length check: after normalization the cleaned string must be
+ * exactly TOTAL_CHARS (55) characters. Shorter inputs would produce fewer
+ * than 32 meaningful decoded bytes; longer inputs indicate a malformed or
+ * concatenated code. Both are rejected.
+ *
+ * @throws with a descriptive message on invalid characters or wrong length
+ */
+export function parseRecoveryCode(formatted) {
+    if (!formatted || formatted.trim().length === 0) {
+        throw new Error('parseRecoveryCode: input is empty');
+    }
+    // normalizeRaw throws with code INVALID_RECOVERY_CODE_ALPHABET on any
+    // character outside A-Z2-7 (after uppercase + whitespace/dash strip).
+    const cleaned = normalizeRaw(formatted);
+    if (cleaned.length === 0) {
+        throw new Error('parseRecoveryCode: no valid characters found after normalization');
+    }
+    // M3 — reject malformed pad-suffix: require exactly TOTAL_CHARS base32
+    // chars. The canonical format always produces exactly 55 chars (11×5);
+    // any deviation means the input is truncated, extended, or corrupted.
+    if (cleaned.length !== TOTAL_CHARS) {
+        throw new Error(`parseRecoveryCode: expected ${TOTAL_CHARS} base32 chars, got ${cleaned.length} — ` +
+            `input likely has wrong length`);
+    }
+    const decoded = base32ToBytes(cleaned);
+    // 55 base32 chars × 5 bits = 275 bits = 34 bytes + 3 trailing bits.
+    // The format intentionally pads to 55 chars (11×5) for visual grouping;
+    // the last 1–3 bytes are trailing zero-padding from the encoder and must
+    // be dropped. With the exact-length check above, decoded.length is always
+    // ≥ DECODED_BYTE_LENGTH here, but guard defensively.
+    if (decoded.length < DECODED_BYTE_LENGTH) {
+        throw new Error(`parseRecoveryCode: expected ${DECODED_BYTE_LENGTH} decoded bytes, got ${decoded.length} — ` +
+            `input likely has wrong length (got ${cleaned.length} base32 chars, expected ${TOTAL_CHARS})`);
+    }
+    return decoded.slice(0, DECODED_BYTE_LENGTH);
+}
+/**
+ * Normalize any input form to the canonical 11-group display format.
+ * Applies the same confusable-char + whitespace tolerance as parseRecoveryCode.
+ *
+ * @throws the same errors as parseRecoveryCode on invalid input
+ */
+export function normalizeRecoveryCode(input) {
+    const bytes = parseRecoveryCode(input);
+    return formatRecoveryCode(bytes);
+}
+/**
+ * Non-throwing validity check.
+ * Returns true iff the input can be successfully parsed as a 32-byte recovery code.
+ */
+export function isValidRecoveryCode(input) {
+    try {
+        parseRecoveryCode(input);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}