@techelusive/nest-auth 0.0.0-stage → 0.2.0

package/dist/common/crypto/jwt.d.ts

@@ -0,0 +1,89 @@
+import { KeyObject } from 'node:crypto';
+import { type JwtAlgorithm } from '../../constants.js';
+/**
+ * A small, strict JWT implementation using only Node's built-in crypto.
+ *
+ * - We SIGN only with ES256.
+ * - We VERIFY ES256 (our own tokens) and RS256 (Google and Apple ID tokens), and only the
+ *   algorithm the caller allows. This blocks the classic JWT attacks: "alg: none" and
+ *   tricking the server into using the wrong kind of key.
+ */
+/** A JSON Web Key as it appears in a JWKS document. */
+export interface JsonWebKey {
+    kty?: string;
+    kid?: string;
+    alg?: string;
+    use?: string;
+    crv?: string;
+    x?: string;
+    y?: string;
+    d?: string;
+    n?: string;
+    e?: string;
+}
+export type { JwtAlgorithm };
+/**
+ * Turns a private key stored as a JSON Web Key into a Node KeyObject that can sign tokens.
+ *
+ * @param jsonWebKey - The full key, including the private "d" part.
+ * @returns A private KeyObject for `signJwt`.
+ * @throws If the JWK is malformed or is not a private key.
+ */
+export declare function privateKeyFromJwk(jsonWebKey: JsonWebKey): KeyObject;
+/**
+ * Turns a JSON Web Key into a Node public KeyObject for checking signatures.
+ *
+ * Only the public fields are copied (n/e for RSA, crv/x/y for EC), so passing a private JWK
+ * by mistake never leaks the private part into the result.
+ *
+ * @param jsonWebKey - An RSA key (Google, Apple) or an EC key (ours).
+ * @returns A public KeyObject for `verifyJwt`.
+ * @throws If the JWK is malformed.
+ */
+export declare function publicKeyFromJwk(jsonWebKey: JsonWebKey): KeyObject;
+/**
+ * Creates a signed ES256 token.
+ *
+ * @param payload - The claims to put in the token (sub, exp, iss...).
+ * @param signingKey - Our current private key and its id; the id goes into the header as "kid".
+ * @param tokenType - Goes into the header as "typ", e.g. "at+jwt" for access tokens.
+ * @returns The token as "header.payload.signature".
+ * @example
+ * const token = signJwt({ sub: userId, exp }, { keyId, privateKey }, 'at+jwt');
+ */
+export declare function signJwt(payload: object, signingKey: {
+    keyId: string;
+    privateKey: KeyObject;
+}, tokenType: string): string;
+export interface JwtVerificationRules {
+    allowedAlgorithm: JwtAlgorithm;
+    /** Accepted "iss" values. */
+    expectedIssuers: string[];
+    /** Accepted "aud" values; the token must contain at least one. */
+    expectedAudiences: string[];
+    /** Required "typ" header, or undefined to skip the check (provider tokens don't all set it). */
+    expectedTokenType?: string;
+    /** Current time in seconds; only set in tests. */
+    currentTimeSeconds?: number;
+}
+/**
+ * Checks a token and returns its payload if every check passes, otherwise null.
+ *
+ * Checks, in order: the shape, the algorithm, the "typ" header, the signature, the expiry
+ * ("exp", with a little clock-skew tolerance), "iat" not in the future, the issuer and the audience.
+ * Never throws for bad input, so callers can't accidentally leak a stack trace.
+ *
+ * @param token - The raw token string from the client.
+ * @param findPublicKeyById - Looks up the public key named by the token's "kid" header.
+ * @param rules - What the token must look like (algorithm, issuers, audiences, type).
+ * @returns The payload when the token is valid, or null for anything wrong with it.
+ */
+export declare function verifyJwt(token: string, findPublicKeyById: (keyId: string) => KeyObject | undefined, rules: JwtVerificationRules): Record<string, any> | null;
+/**
+ * Reads the "kid" (key id) from a token's header WITHOUT checking anything, so the right public key
+ * can be fetched before calling verifyJwt.
+ *
+ * @param token - Any string that may be a JWT.
+ * @returns The key id, or undefined for anything that isn't a JWT or has no "kid".
+ */
+export declare function readJwtKeyId(token: string): string | undefined;

package/dist/common/crypto/jwt.js

@@ -0,0 +1,144 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.privateKeyFromJwk = privateKeyFromJwk;
+exports.publicKeyFromJwk = publicKeyFromJwk;
+exports.signJwt = signJwt;
+exports.verifyJwt = verifyJwt;
+exports.readJwtKeyId = readJwtKeyId;
+const node_crypto_1 = require("node:crypto");
+const constants_1 = require("../../constants.js");
+const time_1 = require("../time.js");
+/**
+ * Turns a private key stored as a JSON Web Key into a Node KeyObject that can sign tokens.
+ *
+ * @param jsonWebKey - The full key, including the private "d" part.
+ * @returns A private KeyObject for `signJwt`.
+ * @throws If the JWK is malformed or is not a private key.
+ */
+function privateKeyFromJwk(jsonWebKey) {
+    return (0, node_crypto_1.createPrivateKey)({ key: jsonWebKey, format: constants_1.JWK_EXPORT_FORMAT });
+}
+/**
+ * Turns a JSON Web Key into a Node public KeyObject for checking signatures.
+ *
+ * Only the public fields are copied (n/e for RSA, crv/x/y for EC), so passing a private JWK
+ * by mistake never leaks the private part into the result.
+ *
+ * @param jsonWebKey - An RSA key (Google, Apple) or an EC key (ours).
+ * @returns A public KeyObject for `verifyJwt`.
+ * @throws If the JWK is malformed.
+ */
+function publicKeyFromJwk(jsonWebKey) {
+    const publicPart = jsonWebKey.kty === constants_1.JWK_KEY_TYPE.rsa
+        ? { kty: constants_1.JWK_KEY_TYPE.rsa, n: jsonWebKey.n, e: jsonWebKey.e }
+        : { kty: constants_1.JWK_KEY_TYPE.ellipticCurve, crv: jsonWebKey.crv, x: jsonWebKey.x, y: jsonWebKey.y };
+    return (0, node_crypto_1.createPublicKey)({ key: publicPart, format: constants_1.JWK_EXPORT_FORMAT });
+}
+/**
+ * Creates a signed ES256 token.
+ *
+ * @param payload - The claims to put in the token (sub, exp, iss...).
+ * @param signingKey - Our current private key and its id; the id goes into the header as "kid".
+ * @param tokenType - Goes into the header as "typ", e.g. "at+jwt" for access tokens.
+ * @returns The token as "header.payload.signature".
+ * @example
+ * const token = signJwt({ sub: userId, exp }, { keyId, privateKey }, 'at+jwt');
+ */
+function signJwt(payload, signingKey, tokenType) {
+    const header = { alg: constants_1.SIGNING_ALGORITHM, typ: tokenType, kid: signingKey.keyId };
+    const headerAndPayload = [encodeJsonAsBase64Url(header), encodeJsonAsBase64Url(payload)].join(constants_1.JWT_PART_SEPARATOR);
+    const signature = (0, node_crypto_1.sign)(constants_1.HASH_ALGORITHM.sha256, Buffer.from(headerAndPayload), {
+        key: signingKey.privateKey,
+        dsaEncoding: constants_1.ECDSA_SIGNATURE_ENCODING, // JWT uses the raw r||s signature form, not DER
+    });
+    return [headerAndPayload, signature.toString(constants_1.TEXT_ENCODING.base64Url)].join(constants_1.JWT_PART_SEPARATOR);
+}
+/**
+ * Checks a token and returns its payload if every check passes, otherwise null.
+ *
+ * Checks, in order: the shape, the algorithm, the "typ" header, the signature, the expiry
+ * ("exp", with a little clock-skew tolerance), "iat" not in the future, the issuer and the audience.
+ * Never throws for bad input, so callers can't accidentally leak a stack trace.
+ *
+ * @param token - The raw token string from the client.
+ * @param findPublicKeyById - Looks up the public key named by the token's "kid" header.
+ * @param rules - What the token must look like (algorithm, issuers, audiences, type).
+ * @returns The payload when the token is valid, or null for anything wrong with it.
+ */
+function verifyJwt(token, findPublicKeyById, rules) {
+    try {
+        const parts = token.split(constants_1.JWT_PART_SEPARATOR);
+        if (parts.length !== constants_1.JWT_PART_COUNT)
+            return null;
+        const [encodedHeader, encodedPayload, encodedSignature] = parts;
+        const header = decodeBase64UrlJson(encodedHeader);
+        const payload = decodeBase64UrlJson(encodedPayload);
+        if (!header || !payload)
+            return null;
+        if (header.alg !== rules.allowedAlgorithm)
+            return null;
+        if (rules.expectedTokenType !== undefined && header.typ !== rules.expectedTokenType)
+            return null;
+        const publicKey = typeof header.kid === 'string' ? findPublicKeyById(header.kid) : undefined;
+        if (!publicKey)
+            return null;
+        const signedContent = Buffer.from([encodedHeader, encodedPayload].join(constants_1.JWT_PART_SEPARATOR));
+        const signature = Buffer.from(encodedSignature, constants_1.TEXT_ENCODING.base64Url);
+        const signatureIsValid = rules.allowedAlgorithm === constants_1.JWT_ALGORITHM.es256
+            ? (0, node_crypto_1.verify)(constants_1.HASH_ALGORITHM.sha256, signedContent, { key: publicKey, dsaEncoding: constants_1.ECDSA_SIGNATURE_ENCODING }, signature)
+            : (0, node_crypto_1.verify)(constants_1.HASH_ALGORITHM.sha256, signedContent, publicKey, signature);
+        if (!signatureIsValid)
+            return null;
+        const now = rules.currentTimeSeconds ?? (0, time_1.currentUnixTimeSeconds)();
+        const hasExpired = typeof payload.exp !== 'number' || payload.exp + constants_1.CLOCK_SKEW_TOLERANCE_SECONDS <= now;
+        const issuedInFuture = typeof payload.iat === 'number' && payload.iat - constants_1.CLOCK_SKEW_TOLERANCE_SECONDS > now;
+        if (hasExpired || issuedInFuture)
+            return null;
+        if (!rules.expectedIssuers.includes(payload.iss))
+            return null;
+        const tokenAudiences = Array.isArray(payload.aud) ? payload.aud : [payload.aud];
+        if (!tokenAudiences.some((audience) => rules.expectedAudiences.includes(audience)))
+            return null;
+        return payload;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Reads the "kid" (key id) from a token's header WITHOUT checking anything, so the right public key
+ * can be fetched before calling verifyJwt.
+ *
+ * @param token - Any string that may be a JWT.
+ * @returns The key id, or undefined for anything that isn't a JWT or has no "kid".
+ */
+function readJwtKeyId(token) {
+    try {
+        const header = decodeBase64UrlJson(token.split(constants_1.JWT_PART_SEPARATOR)[0]);
+        return typeof header?.kid === 'string' ? header.kid : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Encodes a value as JSON, then base64url (the form used in each part of a JWT).
+ *
+ * @param value - The header or payload object.
+ * @returns The base64url text.
+ */
+function encodeJsonAsBase64Url(value) {
+    return Buffer.from(JSON.stringify(value)).toString(constants_1.TEXT_ENCODING.base64Url);
+}
+/**
+ * Reverses `encodeJsonAsBase64Url`.
+ *
+ * @param encoded - One base64url part of a JWT.
+ * @returns The decoded object, or null when the JSON is not a plain object.
+ * @throws If the text is not valid JSON (callers catch this).
+ */
+function decodeBase64UrlJson(encoded) {
+    const decoded = JSON.parse(Buffer.from(encoded, constants_1.TEXT_ENCODING.base64Url).toString(constants_1.TEXT_ENCODING.utf8));
+    return decoded && typeof decoded === 'object' && !Array.isArray(decoded) ? decoded : null;
+}
+//# sourceMappingURL=jwt.js.map

package/dist/common/crypto/jwt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jwt.js","sourceRoot":"","sources":["../../../src/common/crypto/jwt.ts"],"names":[],"mappings":"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"}

package/dist/common/crypto/random-secrets.d.ts

@@ -0,0 +1,78 @@
+import { TokenPrefix } from '../../constants.js';
+/**
+ * Random secrets we give out, and how we store them.
+ *
+ * Rule: the plain secret is shown to the user exactly once. The database only ever holds a hash,
+ * so even a full database leak gives an attacker nothing they can use.
+ */
+/**
+ * Creates a long random token like "rt_Xy3...".
+ *
+ * @param prefix - Says what the token is for (e.g. "rt" for refresh tokens), which helps when one leaks.
+ * @returns `plainToken` to hand to the user once, and `tokenHash` to store in the database.
+ */
+export declare function createRandomToken(prefix: TokenPrefix): {
+    plainToken: string;
+    tokenHash: string;
+};
+/**
+ * Checks that a value has exactly the shape of a token we created with this prefix.
+ * A cheap check to run before any database lookup.
+ *
+ * @param value - Anything the client sent.
+ * @param prefix - The prefix the token should start with.
+ * @returns True when the value looks like one of our tokens.
+ */
+export declare function hasRandomTokenFormat(value: unknown, prefix: TokenPrefix): value is string;
+/**
+ * Hashes text with SHA-256. Used for long random tokens, which are too random to guess,
+ * so no salt or slow hash is needed.
+ *
+ * @param value - The text to hash.
+ * @returns The hash as 64 hex characters.
+ */
+export declare function sha256Hex(value: string): string;
+/**
+ * Creates a numeric code such as "482915" for email or SMS sign-in.
+ * Uses crypto.randomInt, which has no bias towards particular digits.
+ *
+ * @param numberOfDigits - How long the code should be.
+ * @returns The code as a string (it may start with 0).
+ */
+export declare function createNumericCode(numberOfDigits: number): string;
+/**
+ * Hashes a short code (SMS/email codes, backup codes). A random salt per code means two users
+ * with the same code get different hashes. Short codes are also protected by expiry and attempt limits.
+ *
+ * @param code - The plain code.
+ * @param salt - The code's own salt, from `createSalt`.
+ * @returns The hash to store or compare.
+ */
+export declare function hashShortCode(code: string, salt: string): string;
+/**
+ * Creates a random salt for `hashShortCode`.
+ *
+ * @returns The salt as hex text.
+ */
+export declare function createSalt(): string;
+/**
+ * Creates a backup code like "k7m2x9p4" (shown to users as "k7m2-x9p4").
+ *
+ * @returns The plain backup code.
+ */
+export declare function createBackupCode(): string;
+/**
+ * Removes dashes, spaces and capitals, so "K7M2-X9P4" matches "k7m2x9p4".
+ *
+ * @param typedCode - The backup code as the user typed it.
+ * @returns The code in its stored form.
+ */
+export declare function normalizeBackupCode(typedCode: string): string;
+/**
+ * Compares two strings in constant time, so the time taken does not hint at how many characters matched.
+ *
+ * @param first - One string.
+ * @param second - The other string.
+ * @returns True when both strings are identical.
+ */
+export declare function constantTimeEquals(first: string, second: string): boolean;

package/dist/common/crypto/random-secrets.js

@@ -0,0 +1,113 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRandomToken = createRandomToken;
+exports.hasRandomTokenFormat = hasRandomTokenFormat;
+exports.sha256Hex = sha256Hex;
+exports.createNumericCode = createNumericCode;
+exports.hashShortCode = hashShortCode;
+exports.createSalt = createSalt;
+exports.createBackupCode = createBackupCode;
+exports.normalizeBackupCode = normalizeBackupCode;
+exports.constantTimeEquals = constantTimeEquals;
+const node_crypto_1 = require("node:crypto");
+const constants_1 = require("../../constants.js");
+/**
+ * Random secrets we give out, and how we store them.
+ *
+ * Rule: the plain secret is shown to the user exactly once. The database only ever holds a hash,
+ * so even a full database leak gives an attacker nothing they can use.
+ */
+/**
+ * Creates a long random token like "rt_Xy3...".
+ *
+ * @param prefix - Says what the token is for (e.g. "rt" for refresh tokens), which helps when one leaks.
+ * @returns `plainToken` to hand to the user once, and `tokenHash` to store in the database.
+ */
+function createRandomToken(prefix) {
+    const plainToken = `${prefix}${constants_1.TOKEN_PREFIX_SEPARATOR}${(0, node_crypto_1.randomBytes)(constants_1.RANDOM_TOKEN_BYTES).toString(constants_1.TEXT_ENCODING.base64Url)}`;
+    return { plainToken, tokenHash: sha256Hex(plainToken) };
+}
+/**
+ * Checks that a value has exactly the shape of a token we created with this prefix.
+ * A cheap check to run before any database lookup.
+ *
+ * @param value - Anything the client sent.
+ * @param prefix - The prefix the token should start with.
+ * @returns True when the value looks like one of our tokens.
+ */
+function hasRandomTokenFormat(value, prefix) {
+    const base64UrlLengthOf32Bytes = constants_1.RANDOM_TOKEN_BASE64URL_LENGTH;
+    return (typeof value === 'string' &&
+        value.length === prefix.length + 1 + base64UrlLengthOf32Bytes &&
+        value.startsWith(`${prefix}${constants_1.TOKEN_PREFIX_SEPARATOR}`) &&
+        constants_1.BASE64URL_TEXT_PATTERN.test(value));
+}
+/**
+ * Hashes text with SHA-256. Used for long random tokens, which are too random to guess,
+ * so no salt or slow hash is needed.
+ *
+ * @param value - The text to hash.
+ * @returns The hash as 64 hex characters.
+ */
+function sha256Hex(value) {
+    return (0, node_crypto_1.createHash)(constants_1.HASH_ALGORITHM.sha256).update(value, constants_1.TEXT_ENCODING.utf8).digest(constants_1.TEXT_ENCODING.hex);
+}
+/**
+ * Creates a numeric code such as "482915" for email or SMS sign-in.
+ * Uses crypto.randomInt, which has no bias towards particular digits.
+ *
+ * @param numberOfDigits - How long the code should be.
+ * @returns The code as a string (it may start with 0).
+ */
+function createNumericCode(numberOfDigits) {
+    return Array.from({ length: numberOfDigits }, () => (0, node_crypto_1.randomInt)(0, constants_1.DECIMAL_BASE)).join('');
+}
+/**
+ * Hashes a short code (SMS/email codes, backup codes). A random salt per code means two users
+ * with the same code get different hashes. Short codes are also protected by expiry and attempt limits.
+ *
+ * @param code - The plain code.
+ * @param salt - The code's own salt, from `createSalt`.
+ * @returns The hash to store or compare.
+ */
+function hashShortCode(code, salt) {
+    return sha256Hex(`${salt}${constants_1.SALTED_CODE_SEPARATOR}${code}`);
+}
+/**
+ * Creates a random salt for `hashShortCode`.
+ *
+ * @returns The salt as hex text.
+ */
+function createSalt() {
+    return (0, node_crypto_1.randomBytes)(constants_1.SHORT_CODE_SALT_BYTES).toString(constants_1.TEXT_ENCODING.hex);
+}
+/**
+ * Creates a backup code like "k7m2x9p4" (shown to users as "k7m2-x9p4").
+ *
+ * @returns The plain backup code.
+ */
+function createBackupCode() {
+    return Array.from({ length: constants_1.BACKUP_CODE_LENGTH }, () => constants_1.BACKUP_CODE_ALPHABET[(0, node_crypto_1.randomInt)(0, constants_1.BACKUP_CODE_ALPHABET.length)]).join('');
+}
+/**
+ * Removes dashes, spaces and capitals, so "K7M2-X9P4" matches "k7m2x9p4".
+ *
+ * @param typedCode - The backup code as the user typed it.
+ * @returns The code in its stored form.
+ */
+function normalizeBackupCode(typedCode) {
+    return typedCode.toLowerCase().replace(constants_1.BACKUP_CODE_FORMATTING_CHARACTERS_PATTERN, '');
+}
+/**
+ * Compares two strings in constant time, so the time taken does not hint at how many characters matched.
+ *
+ * @param first - One string.
+ * @param second - The other string.
+ * @returns True when both strings are identical.
+ */
+function constantTimeEquals(first, second) {
+    const firstBytes = Buffer.from(first);
+    const secondBytes = Buffer.from(second);
+    return firstBytes.length === secondBytes.length && (0, node_crypto_1.timingSafeEqual)(firstBytes, secondBytes);
+}
+//# sourceMappingURL=random-secrets.js.map

package/dist/common/crypto/random-secrets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"random-secrets.js","sourceRoot":"","sources":["../../../src/common/crypto/random-secrets.ts"],"names":[],"mappings":";;AA8BA,8CAGC;AAUD,oDAQC;AASD,8BAEC;AASD,8CAEC;AAUD,sCAEC;AAOD,gCAEC;AAOD,4CAEC;AAQD,kDAEC;AASD,gDAIC;AA9HD,6CAAkF;AAClF,2CAcqB;AAErB;;;;;GAKG;AAEH;;;;;GAKG;AACH,SAAgB,iBAAiB,CAAC,MAAmB;IACnD,MAAM,UAAU,GAAG,GAAG,MAAM,GAAG,kCAAsB,GAAG,IAAA,yBAAW,EAAC,8BAAkB,CAAC,CAAC,QAAQ,CAAC,yBAAa,CAAC,SAAS,CAAC,EAAE,CAAC;IAC5H,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,SAAS,CAAC,UAAU,CAAC,EAAE,CAAC;AAC1D,CAAC;AAED;;;;;;;GAOG;AACH,SAAgB,oBAAoB,CAAC,KAAc,EAAE,MAAmB;IACtE,MAAM,wBAAwB,GAAG,yCAA6B,CAAC;IAC/D,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,CAAC,MAAM,KAAK,MAAM,CAAC,MAAM,GAAG,CAAC,GAAG,wBAAwB;QAC7D,KAAK,CAAC,UAAU,CAAC,GAAG,MAAM,GAAG,kCAAsB,EAAE,CAAC;QACtD,kCAAsB,CAAC,IAAI,CAAC,KAAK,CAAC,CACnC,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,SAAS,CAAC,KAAa;IACrC,OAAO,IAAA,wBAAU,EAAC,0BAAc,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,EAAE,yBAAa,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,yBAAa,CAAC,GAAG,CAAC,CAAC;AACvG,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,iBAAiB,CAAC,cAAsB;IACtD,OAAO,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,cAAc,EAAE,EAAE,GAAG,EAAE,CAAC,IAAA,uBAAS,EAAC,CAAC,EAAE,wBAAY,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AAC3F,CAAC;AAED;;;;;;;GAOG;AACH,SAAgB,aAAa,CAAC,IAAY,EAAE,IAAY;IACtD,OAAO,SAAS,CAAC,GAAG,IAAI,GAAG,iCAAqB,GAAG,IAAI,EAAE,CAAC,CAAC;AAC7D,CAAC;AAED;;;;GAIG;AACH,SAAgB,UAAU;IACxB,OAAO,IAAA,yBAAW,EAAC,iCAAqB,CAAC,CAAC,QAAQ,CAAC,yBAAa,CAAC,GAAG,CAAC,CAAC;AACxE,CAAC;AAED;;;;GAIG;AACH,SAAgB,gBAAgB;IAC9B,OAAO,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,8BAAkB,EAAE,EAAE,GAAG,EAAE,CAAC,gCAAoB,CAAC,IAAA,uBAAS,EAAC,CAAC,EAAE,gCAAoB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AACpI,CAAC;AAED;;;;;GAKG;AACH,SAAgB,mBAAmB,CAAC,SAAiB;IACnD,OAAO,SAAS,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,qDAAyC,EAAE,EAAE,CAAC,CAAC;AACxF,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,kBAAkB,CAAC,KAAa,EAAE,MAAc;IAC9D,MAAM,UAAU,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACtC,MAAM,WAAW,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACxC,OAAO,UAAU,CAAC,MAAM,KAAK,WAAW,CAAC,MAAM,IAAI,IAAA,6BAAe,EAAC,UAAU,EAAE,WAAW,CAAC,CAAC;AAC9F,CAAC"}

package/dist/common/crypto/remote-public-keys.d.ts

@@ -0,0 +1,49 @@
+import { KeyObject } from 'node:crypto';
+/**
+ * Downloads and caches a provider's public signing keys (a JWKS URL such as Google's).
+ *
+ * - Keys are cached for hours, because providers change them rarely.
+ * - If a token names a key we don't have, the keys are re-downloaded (providers rotate keys),
+ *   but at most once per UNKNOWN_KEY_REFETCH_WAIT_SECONDS so junk tokens can't make us spam the provider.
+ */
+export declare class RemotePublicKeys {
+    private readonly keysUrl;
+    private keysById;
+    private loadedAt;
+    private lastForcedReloadAt;
+    private loading?;
+    constructor(keysUrl: string);
+    /**
+     * Finds a provider public key by id, downloading the key list first if needed.
+     * Never throws: a download failure just means "unknown key".
+     *
+     * @param keyId - The "kid" from the token header.
+     * @returns The public key, or undefined if the provider doesn't have one with this id.
+     */
+    findKey(keyId: string): Promise<KeyObject | undefined>;
+    /**
+     * Makes sure the key named by `keyId` has been downloaded (if it exists), so it can then be read
+     * synchronously with `findLoadedKey`, e.g. from inside `verifyJwt`'s key lookup.
+     *
+     * @param keyId - The "kid" from the token header, or undefined (then nothing happens).
+     */
+    ensureLoaded(keyId: string | undefined): Promise<void>;
+    /**
+     * Reads a key from the cache without downloading anything. Call `ensureLoaded` first.
+     *
+     * @param keyId - The "kid" from the token header.
+     * @returns The cached public key, or undefined.
+     */
+    findLoadedKey(keyId: string): KeyObject | undefined;
+    /**
+     * Downloads the keys again. If a download is already running, waits for that one instead.
+     *
+     * @returns Resolves when the download has finished (successfully or not).
+     */
+    private reload;
+    /**
+     * Fetches the JWKS URL and replaces the cache with the RSA keys it contains.
+     * On any failure the old keys are kept.
+     */
+    private download;
+}

package/dist/common/crypto/remote-public-keys.js

@@ -0,0 +1,105 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RemotePublicKeys = void 0;
+const constants_1 = require("../../constants.js");
+const jwt_1 = require("./jwt");
+/**
+ * Downloads and caches a provider's public signing keys (a JWKS URL such as Google's).
+ *
+ * - Keys are cached for hours, because providers change them rarely.
+ * - If a token names a key we don't have, the keys are re-downloaded (providers rotate keys),
+ *   but at most once per UNKNOWN_KEY_REFETCH_WAIT_SECONDS so junk tokens can't make us spam the provider.
+ */
+class RemotePublicKeys {
+    keysUrl;
+    keysById = new Map();
+    loadedAt = 0;
+    lastForcedReloadAt = 0;
+    loading;
+    constructor(keysUrl) {
+        this.keysUrl = keysUrl;
+    }
+    /**
+     * Finds a provider public key by id, downloading the key list first if needed.
+     * Never throws: a download failure just means "unknown key".
+     *
+     * @param keyId - The "kid" from the token header.
+     * @returns The public key, or undefined if the provider doesn't have one with this id.
+     */
+    async findKey(keyId) {
+        const cacheIsStale = Date.now() - this.loadedAt > constants_1.SOCIAL_PUBLIC_KEYS_CACHE_SECONDS * constants_1.SECOND_IN_MILLISECONDS;
+        if (cacheIsStale)
+            await this.reload();
+        if (!this.keysById.has(keyId)) {
+            const mayForceReload = Date.now() - this.lastForcedReloadAt > constants_1.UNKNOWN_KEY_REFETCH_WAIT_SECONDS * constants_1.SECOND_IN_MILLISECONDS;
+            if (mayForceReload) {
+                this.lastForcedReloadAt = Date.now();
+                await this.reload();
+            }
+        }
+        return this.keysById.get(keyId);
+    }
+    /**
+     * Makes sure the key named by `keyId` has been downloaded (if it exists), so it can then be read
+     * synchronously with `findLoadedKey`, e.g. from inside `verifyJwt`'s key lookup.
+     *
+     * @param keyId - The "kid" from the token header, or undefined (then nothing happens).
+     */
+    async ensureLoaded(keyId) {
+        if (keyId)
+            await this.findKey(keyId);
+    }
+    /**
+     * Reads a key from the cache without downloading anything. Call `ensureLoaded` first.
+     *
+     * @param keyId - The "kid" from the token header.
+     * @returns The cached public key, or undefined.
+     */
+    findLoadedKey(keyId) {
+        return this.keysById.get(keyId);
+    }
+    /**
+     * Downloads the keys again. If a download is already running, waits for that one instead.
+     *
+     * @returns Resolves when the download has finished (successfully or not).
+     */
+    reload() {
+        // If a download is already running, wait for that one instead of starting another.
+        this.loading ??= this.download().finally(() => (this.loading = undefined));
+        return this.loading;
+    }
+    /**
+     * Fetches the JWKS URL and replaces the cache with the RSA keys it contains.
+     * On any failure the old keys are kept.
+     */
+    async download() {
+        try {
+            const response = await fetch(this.keysUrl, { signal: AbortSignal.timeout(constants_1.SOCIAL_PROVIDER_TIMEOUT_MS) });
+            if (!response.ok)
+                return;
+            const { keys } = (await response.json());
+            if (!Array.isArray(keys))
+                return;
+            const freshKeys = new Map();
+            for (const jsonWebKey of keys) {
+                if (!jsonWebKey.kid || jsonWebKey.kty !== constants_1.JWK_KEY_TYPE.rsa)
+                    continue;
+                try {
+                    freshKeys.set(jsonWebKey.kid, (0, jwt_1.publicKeyFromJwk)(jsonWebKey));
+                }
+                catch {
+                    // Skip a malformed key rather than losing all of them.
+                }
+            }
+            if (freshKeys.size > 0) {
+                this.keysById = freshKeys;
+                this.loadedAt = Date.now();
+            }
+        }
+        catch {
+            // Network problem: keep the keys we had. Tokens signed by unknown keys will fail.
+        }
+    }
+}
+exports.RemotePublicKeys = RemotePublicKeys;
+//# sourceMappingURL=remote-public-keys.js.map

package/dist/common/crypto/remote-public-keys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote-public-keys.js","sourceRoot":"","sources":["../../../src/common/crypto/remote-public-keys.ts"],"names":[],"mappings":"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"}

package/dist/common/crypto/totp.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Time-based one-time passwords (RFC 6238): the 6-digit codes shown by Google Authenticator,
+ * Microsoft Authenticator, 1Password, Authy and others.
+ *
+ * The user's app and our server share a secret. Every 30 seconds both compute
+ * HMAC-SHA1(secret, current 30-second step) and turn it into 6 digits. If they match, the user
+ * has the phone that holds the secret.
+ */
+/**
+ * Creates a new random secret, in the Base32 form authenticator apps expect.
+ *
+ * @returns The secret, e.g. "JBSWY3DPEHPK3PXP...".
+ */
+export declare function createTotpSecret(): string;
+/**
+ * Builds the link inside the QR code the user scans:
+ * otpauth://totp/Issuer:account?secret=...&issuer=Issuer
+ *
+ * @param secret - The Base32 secret from `createTotpSecret`.
+ * @param accountName - Shown in the app under the issuer, usually the user's email.
+ * @param issuerName - Your app's name, shown in the authenticator app.
+ * @returns The otpauth:// URL to turn into a QR code.
+ */
+export declare function buildAuthenticatorAppUrl(secret: string, accountName: string, issuerName: string): string;
+/**
+ * Computes the 6-digit code for one 30-second time step (RFC 6238).
+ *
+ * @param secret - The Base32 secret shared with the authenticator app.
+ * @param timeStep - Which 30-second window, from `timeStepAt`.
+ * @returns The code as a zero-padded string, e.g. "042913".
+ */
+export declare function totpCodeForTimeStep(secret: string, timeStep: number): string;
+/**
+ * Converts a time into its 30-second TOTP window number.
+ *
+ * @param unixTimeSeconds - Seconds since 1970.
+ * @returns The time step that contains this moment.
+ */
+export declare function timeStepAt(unixTimeSeconds: number): number;
+/**
+ * Checks a code the user typed from their authenticator app.
+ *
+ * Codes from one step before or after the current one are also accepted, because phone clocks drift.
+ * `lastAcceptedTimeStep` blocks replay: a code that was already used (or an older one) is refused,
+ * so someone who sees a code over the user's shoulder cannot use it again.
+ *
+ * @param secret - The user's Base32 secret.
+ * @param typedCode - What the user typed; spaces are ignored.
+ * @param lastAcceptedTimeStep - The step of the last code accepted for this user, or null if none.
+ * @param unixTimeSeconds - The current time; only passed in tests.
+ * @returns The matching time step (save it as the new lastAcceptedTimeStep), or null if wrong.
+ */
+export declare function verifyTotpCode(secret: string, typedCode: string, lastAcceptedTimeStep: number | null, unixTimeSeconds?: number): number | null;
+/**
+ * Encodes bytes as Base32 (RFC 4648, no padding), the format authenticator apps use for secrets.
+ *
+ * @param bytes - The raw bytes.
+ * @returns The Base32 text.
+ */
+export declare function encodeBase32(bytes: Buffer): string;
+/**
+ * Decodes Base32 text back into bytes. Lower case and "=" padding are accepted.
+ *
+ * @param text - The Base32 text.
+ * @returns The decoded bytes.
+ * @throws If the text contains a character that is not in the Base32 alphabet.
+ */
+export declare function decodeBase32(text: string): Buffer;