@nya-account/node-sdk 2.0.0

package/dist/index.js

@@ -0,0 +1,727 @@
+import { extractBearerToken, getAuth, sendOAuthError, setAuth } from "./express-BHHzodXb.js";
+import axios, { AxiosError } from "axios";
+import { createHash, randomBytes } from "node:crypto";
+import { z } from "zod";
+import { createRemoteJWKSet, errors, jwtVerify } from "jose";
+
+//#region src/core/schemas.ts
+const TokenResponseSchema = z.object({
+	access_token: z.string(),
+	token_type: z.string(),
+	expires_in: z.number(),
+	refresh_token: z.string(),
+	scope: z.string(),
+	id_token: z.string().optional()
+});
+const OAuthErrorSchema = z.object({
+	error: z.string(),
+	error_description: z.string().optional()
+});
+const IntrospectionResponseSchema = z.object({
+	active: z.boolean(),
+	scope: z.string().optional(),
+	client_id: z.string().optional(),
+	username: z.string().optional(),
+	token_type: z.string().optional(),
+	exp: z.number().optional(),
+	iat: z.number().optional(),
+	sub: z.string().optional(),
+	aud: z.string().optional(),
+	iss: z.string().optional(),
+	jti: z.string().optional()
+});
+const UserInfoSchema = z.object({
+	sub: z.string(),
+	name: z.string().optional(),
+	preferred_username: z.string().optional(),
+	email: z.string().optional(),
+	email_verified: z.boolean().optional(),
+	updated_at: z.number().optional()
+});
+const DiscoveryDocumentSchema = z.object({
+	issuer: z.string(),
+	authorization_endpoint: z.string(),
+	token_endpoint: z.string(),
+	userinfo_endpoint: z.string().optional(),
+	jwks_uri: z.string(),
+	revocation_endpoint: z.string().optional(),
+	introspection_endpoint: z.string().optional(),
+	pushed_authorization_request_endpoint: z.string().optional(),
+	end_session_endpoint: z.string().optional(),
+	response_types_supported: z.array(z.string()),
+	grant_types_supported: z.array(z.string()),
+	id_token_signing_alg_values_supported: z.array(z.string()),
+	scopes_supported: z.array(z.string()),
+	subject_types_supported: z.array(z.string()),
+	token_endpoint_auth_methods_supported: z.array(z.string()),
+	code_challenge_methods_supported: z.array(z.string()).optional(),
+	claims_supported: z.array(z.string()).optional(),
+	dpop_signing_alg_values_supported: z.array(z.string()).optional(),
+	request_parameter_supported: z.boolean().optional(),
+	request_uri_parameter_supported: z.boolean().optional()
+});
+const AccessTokenPayloadSchema = z.object({
+	iss: z.string(),
+	sub: z.string(),
+	aud: z.string(),
+	scope: z.string(),
+	ver: z.string(),
+	iat: z.number(),
+	exp: z.number(),
+	jti: z.string(),
+	cnf: z.object({ jkt: z.string() }).optional()
+});
+const IdTokenPayloadSchema = z.object({
+	iss: z.string(),
+	sub: z.string(),
+	aud: z.string(),
+	iat: z.number(),
+	exp: z.number(),
+	nonce: z.string().optional(),
+	name: z.string().optional(),
+	preferred_username: z.string().optional(),
+	email: z.string().optional(),
+	email_verified: z.boolean().optional(),
+	updated_at: z.number().optional()
+});
+
+//#endregion
+//#region src/core/errors.ts
+/**
+
+* Base error class for the SDK.
+
+*/
+var NyaAccountError = class extends Error {
+	constructor(code, description) {
+		super(`[${code}] ${description}`);
+		this.code = void 0;
+		this.description = void 0;
+		this.name = "NyaAccountError";
+		this.code = code;
+		this.description = description;
+	}
+};
+/**
+
+* OAuth protocol error (from server error / error_description response).
+
+*/
+var OAuthError = class extends NyaAccountError {
+	constructor(error, errorDescription) {
+		super(error, errorDescription);
+		this.name = "OAuthError";
+	}
+};
+/**
+
+* JWT verification error.
+
+*/
+var TokenVerificationError = class extends NyaAccountError {
+	constructor(description) {
+		super("token_verification_failed", description);
+		this.name = "TokenVerificationError";
+	}
+};
+/**
+
+* OIDC Discovery error.
+
+*/
+var DiscoveryError = class extends NyaAccountError {
+	constructor(description) {
+		super("discovery_error", description);
+		this.name = "DiscoveryError";
+	}
+};
+
+//#endregion
+//#region src/utils/pkce.ts
+/**
+
+* Generate a PKCE code_verifier (43-128 character random string).
+
+*/
+function generateCodeVerifier() {
+	return randomBytes(32).toString("base64url");
+}
+/**
+
+* Generate an S256 code_challenge from a code_verifier.
+
+*/
+function generateCodeChallenge(codeVerifier) {
+	return createHash("sha256").update(codeVerifier).digest("base64url");
+}
+/**
+
+* Generate a PKCE code_verifier and code_challenge pair.
+
+*/
+function generatePkce() {
+	const codeVerifier = generateCodeVerifier();
+	const codeChallenge = generateCodeChallenge(codeVerifier);
+	return {
+		codeVerifier,
+		codeChallenge
+	};
+}
+
+//#endregion
+//#region src/utils/jwt.ts
+/**
+
+* JWT verifier using remote JWKS for signature verification.
+
+*/
+var JwtVerifier = class {
+	constructor(jwksUri, issuer, defaultAudience) {
+		this.jwks = void 0;
+		this.issuer = void 0;
+		this.defaultAudience = void 0;
+		this.jwks = createRemoteJWKSet(new URL(jwksUri));
+		this.issuer = issuer;
+		this.defaultAudience = defaultAudience;
+	}
+	/**
+	
+	* Verify an OAuth 2.0 Access Token (JWT, RFC 9068).
+	
+	*/
+	async verifyAccessToken(token, audience) {
+		try {
+			const { payload } = await jwtVerify(token, this.jwks, {
+				algorithms: ["RS256"],
+				issuer: this.issuer,
+				audience: audience ?? this.defaultAudience
+			});
+			return AccessTokenPayloadSchema.parse(payload);
+		} catch (error) {
+			throw this.wrapError(error, "Access Token");
+		}
+	}
+	/**
+	
+	* Verify an OIDC ID Token.
+	
+	*/
+	async verifyIdToken(token, options) {
+		try {
+			const { payload } = await jwtVerify(token, this.jwks, {
+				algorithms: ["RS256"],
+				issuer: this.issuer,
+				audience: options?.audience ?? this.defaultAudience
+			});
+			const parsed = IdTokenPayloadSchema.parse(payload);
+			if (options?.nonce !== void 0 && parsed.nonce !== options.nonce) throw new TokenVerificationError("ID Token nonce mismatch");
+			return parsed;
+		} catch (error) {
+			if (error instanceof TokenVerificationError) throw error;
+			throw this.wrapError(error, "ID Token");
+		}
+	}
+	wrapError(error, tokenType) {
+		if (error instanceof TokenVerificationError) return error;
+		if (error instanceof errors.JWTExpired) return new TokenVerificationError(`${tokenType} has expired`);
+		if (error instanceof errors.JWTClaimValidationFailed) return new TokenVerificationError(`${tokenType} claim validation failed: ${error.message}`);
+		if (error instanceof errors.JWSSignatureVerificationFailed) return new TokenVerificationError(`${tokenType} signature verification failed`);
+		const message = error instanceof Error ? error.message : "Unknown error";
+		return new TokenVerificationError(`${tokenType} verification failed: ${message}`);
+	}
+};
+
+//#endregion
+//#region src/client.ts
+const DISCOVERY_ENDPOINT_MAP = {
+	authorization: "authorizationEndpoint",
+	token: "tokenEndpoint",
+	userinfo: "userinfoEndpoint",
+	revocation: "revocationEndpoint",
+	introspection: "introspectionEndpoint",
+	jwks: "jwksUri",
+	endSession: "endSessionEndpoint"
+};
+/** Default discovery cache TTL: 1 hour */
+const DEFAULT_DISCOVERY_CACHE_TTL = 36e5;
+/**
+
+* Nya Account Node.js SDK client.
+
+*
+
+* Provides full OAuth 2.1 / OIDC flow support:
+
+* - Authorization Code + PKCE
+
+* - Token exchange / refresh / revocation / introspection
+
+* - Local JWT verification (via JWKS)
+
+* - OIDC UserInfo
+
+* - OIDC Discovery auto-discovery
+
+* - Express middleware (Bearer Token auth + scope validation)
+
+*
+
+* @example
+
+* ```typescript
+
+* const client = new NyaAccountClient({
+
+*     issuer: 'https://account.example.com',
+
+*     clientId: 'my-app',
+
+*     clientSecret: 'my-secret',
+
+* })
+
+*
+
+* // Create authorization URL (with PKCE)
+
+* const { url, codeVerifier, state } = await client.createAuthorizationUrl({
+
+*     redirectUri: 'https://myapp.com/callback',
+
+*     scope: 'openid profile email',
+
+* })
+
+*
+
+* // Exchange code for tokens
+
+* const tokens = await client.exchangeCode({
+
+*     code: callbackCode,
+
+*     redirectUri: 'https://myapp.com/callback',
+
+*     codeVerifier,
+
+* })
+
+*
+
+* // Get user info
+
+* const userInfo = await client.getUserInfo(tokens.accessToken)
+
+* ```
+
+*/
+var NyaAccountClient = class {
+	constructor(config) {
+		this.httpClient = void 0;
+		this.config = void 0;
+		this.discoveryCache = null;
+		this.discoveryCacheTimestamp = 0;
+		this.discoveryCacheTtl = void 0;
+		this.jwtVerifier = null;
+		this.config = config;
+		this.discoveryCacheTtl = config.discoveryCacheTtl ?? DEFAULT_DISCOVERY_CACHE_TTL;
+		this.httpClient = axios.create({ timeout: config.timeout ?? 1e4 });
+	}
+	/**
+	
+	* Fetch the OIDC Discovery document. Results are cached with a configurable TTL.
+	
+	*/
+	async discover() {
+		if (this.discoveryCache && Date.now() - this.discoveryCacheTimestamp < this.discoveryCacheTtl) return this.discoveryCache;
+		try {
+			const url = `${this.config.issuer}/.well-known/openid-configuration`;
+			const response = await this.httpClient.get(url);
+			const raw = DiscoveryDocumentSchema.parse(response.data);
+			this.discoveryCache = {
+				issuer: raw.issuer,
+				authorizationEndpoint: raw.authorization_endpoint,
+				tokenEndpoint: raw.token_endpoint,
+				userinfoEndpoint: raw.userinfo_endpoint,
+				jwksUri: raw.jwks_uri,
+				revocationEndpoint: raw.revocation_endpoint,
+				introspectionEndpoint: raw.introspection_endpoint,
+				pushedAuthorizationRequestEndpoint: raw.pushed_authorization_request_endpoint,
+				endSessionEndpoint: raw.end_session_endpoint,
+				responseTypesSupported: raw.response_types_supported,
+				grantTypesSupported: raw.grant_types_supported,
+				idTokenSigningAlgValuesSupported: raw.id_token_signing_alg_values_supported,
+				scopesSupported: raw.scopes_supported,
+				subjectTypesSupported: raw.subject_types_supported,
+				tokenEndpointAuthMethodsSupported: raw.token_endpoint_auth_methods_supported,
+				codeChallengeMethodsSupported: raw.code_challenge_methods_supported,
+				claimsSupported: raw.claims_supported
+			};
+			this.discoveryCacheTimestamp = Date.now();
+			return this.discoveryCache;
+		} catch (error) {
+			if (error instanceof DiscoveryError) throw error;
+			const message = error instanceof Error ? error.message : "Unknown error";
+			throw new DiscoveryError(`Failed to fetch OIDC Discovery document: ${message}`);
+		}
+	}
+	/**
+	
+	* Clear the cached Discovery document and JWT verifier, forcing a re-fetch on next use.
+	
+	*/
+	clearCache() {
+		this.discoveryCache = null;
+		this.discoveryCacheTimestamp = 0;
+		this.jwtVerifier = null;
+	}
+	/**
+	
+	* Create an OAuth authorization URL (automatically includes PKCE).
+	
+	*
+	
+	* The returned `codeVerifier` and `state` must be saved to the session
+	
+	* for later use in token exchange and CSRF validation.
+	
+	*/
+	async createAuthorizationUrl(options) {
+		const authorizationEndpoint = await this.resolveEndpoint("authorization");
+		const codeVerifier = generateCodeVerifier();
+		const codeChallenge = generateCodeChallenge(codeVerifier);
+		const state = options.state ?? randomBytes(16).toString("base64url");
+		const params = new URLSearchParams({
+			client_id: this.config.clientId,
+			redirect_uri: options.redirectUri,
+			response_type: "code",
+			scope: options.scope ?? "openid",
+			state,
+			code_challenge: codeChallenge,
+			code_challenge_method: "S256"
+		});
+		if (options.nonce) params.set("nonce", options.nonce);
+		return {
+			url: `${authorizationEndpoint}?${params.toString()}`,
+			codeVerifier,
+			state
+		};
+	}
+	/**
+	
+	* Exchange an authorization code for tokens (Authorization Code Grant).
+	
+	*/
+	async exchangeCode(options) {
+		const tokenEndpoint = await this.resolveEndpoint("token");
+		try {
+			const response = await this.httpClient.post(tokenEndpoint, {
+				grant_type: "authorization_code",
+				code: options.code,
+				redirect_uri: options.redirectUri,
+				client_id: this.config.clientId,
+				client_secret: this.config.clientSecret,
+				code_verifier: options.codeVerifier
+			});
+			return this.mapTokenResponse(response.data);
+		} catch (error) {
+			throw this.handleTokenError(error);
+		}
+	}
+	/**
+	
+	* Refresh an Access Token using a Refresh Token.
+	
+	*/
+	async refreshToken(refreshToken) {
+		const tokenEndpoint = await this.resolveEndpoint("token");
+		try {
+			const response = await this.httpClient.post(tokenEndpoint, {
+				grant_type: "refresh_token",
+				refresh_token: refreshToken,
+				client_id: this.config.clientId,
+				client_secret: this.config.clientSecret
+			});
+			return this.mapTokenResponse(response.data);
+		} catch (error) {
+			throw this.handleTokenError(error);
+		}
+	}
+	/**
+	
+	* Revoke a token (RFC 7009).
+	
+	*
+	
+	* Supports revoking Access Tokens or Refresh Tokens.
+	
+	* Revoking a Refresh Token also revokes its entire token family.
+	
+	*/
+	async revokeToken(token) {
+		const revocationEndpoint = await this.resolveEndpoint("revocation");
+		try {
+			await this.httpClient.post(revocationEndpoint, {
+				token,
+				client_id: this.config.clientId,
+				client_secret: this.config.clientSecret
+			});
+		} catch {}
+	}
+	/**
+	
+	* Token introspection (RFC 7662).
+	
+	*
+	
+	* Query the server for the current state of a token (active status, associated user info, etc.).
+	
+	*/
+	async introspectToken(token) {
+		const introspectionEndpoint = await this.resolveEndpoint("introspection");
+		try {
+			const response = await this.httpClient.post(introspectionEndpoint, {
+				token,
+				client_id: this.config.clientId,
+				client_secret: this.config.clientSecret
+			});
+			const raw = IntrospectionResponseSchema.parse(response.data);
+			return {
+				active: raw.active,
+				scope: raw.scope,
+				clientId: raw.client_id,
+				username: raw.username,
+				tokenType: raw.token_type,
+				exp: raw.exp,
+				iat: raw.iat,
+				sub: raw.sub,
+				aud: raw.aud,
+				iss: raw.iss,
+				jti: raw.jti
+			};
+		} catch (error) {
+			throw this.handleTokenError(error);
+		}
+	}
+	/**
+	
+	* Get user info using an Access Token (OIDC UserInfo Endpoint).
+	
+	*
+	
+	* The returned fields depend on the scopes included in the token:
+	
+	* - `profile`: name, preferredUsername, updatedAt
+	
+	* - `email`: email, emailVerified
+	
+	*/
+	async getUserInfo(accessToken) {
+		const userinfoEndpoint = await this.resolveEndpoint("userinfo");
+		try {
+			const response = await this.httpClient.get(userinfoEndpoint, { headers: { Authorization: `Bearer ${accessToken}` } });
+			const raw = UserInfoSchema.parse(response.data);
+			return {
+				sub: raw.sub,
+				name: raw.name,
+				preferredUsername: raw.preferred_username,
+				email: raw.email,
+				emailVerified: raw.email_verified,
+				updatedAt: raw.updated_at
+			};
+		} catch (error) {
+			throw this.handleTokenError(error);
+		}
+	}
+	/**
+	
+	* Locally verify a JWT Access Token (RFC 9068).
+	
+	*
+	
+	* Uses remote JWKS for signature verification, and validates issuer, audience, expiry, etc.
+	
+	*
+	
+	* @param token JWT Access Token string
+	
+	* @param options.audience Custom audience validation value (defaults to clientId)
+	
+	*/
+	async verifyAccessToken(token, options) {
+		const verifier = await this.getJwtVerifier();
+		return verifier.verifyAccessToken(token, options?.audience);
+	}
+	/**
+	
+	* Locally verify an OIDC ID Token.
+	
+	*
+	
+	* @param token JWT ID Token string
+	
+	* @param options.audience Custom audience validation value (defaults to clientId)
+	
+	* @param options.nonce Validate the nonce claim (required if nonce was sent during authorization)
+	
+	*/
+	async verifyIdToken(token, options) {
+		const verifier = await this.getJwtVerifier();
+		return verifier.verifyIdToken(token, options);
+	}
+	/**
+	
+	* Express middleware: verify the Bearer Token in the request.
+	
+	*
+	
+	* After successful verification, use `getAuth(req)` to retrieve the token payload.
+	
+	*
+	
+	* @param options.strategy Verification strategy: 'local' (default, JWT local verification) or 'introspection' (remote introspection)
+	
+	*
+	
+	* @example
+	
+	* ```typescript
+	
+	* import { getAuth } from '@nya-account/node-sdk/express'
+	
+	*
+	
+	* app.use('/api', client.authenticate())
+	
+	*
+	
+	* app.get('/api/me', (req, res) => {
+	
+	*     const auth = getAuth(req)
+	
+	*     res.json({ userId: auth?.sub })
+	
+	* })
+	
+	* ```
+	
+	*/
+	authenticate(options) {
+		const strategy = options?.strategy ?? "local";
+		return (req, res, next) => {
+			const token = extractBearerToken(req);
+			if (!token) {
+				sendOAuthError(res, 401, "invalid_token", "Missing Bearer token in Authorization header");
+				return;
+			}
+			const handleVerification = async () => {
+				let payload;
+				if (strategy === "introspection") {
+					const introspection = await this.introspectToken(token);
+					if (!introspection.active) {
+						sendOAuthError(res, 401, "invalid_token", "Token is not active");
+						return;
+					}
+					payload = {
+						iss: introspection.iss ?? "",
+						sub: introspection.sub ?? "",
+						aud: introspection.aud ?? "",
+						scope: introspection.scope ?? "",
+						ver: "1",
+						iat: introspection.iat ?? 0,
+						exp: introspection.exp ?? 0,
+						jti: introspection.jti ?? ""
+					};
+				} else payload = await this.verifyAccessToken(token);
+				setAuth(req, payload);
+				next();
+			};
+			handleVerification().catch(() => {
+				sendOAuthError(res, 401, "invalid_token", "Invalid or expired access token");
+			});
+		};
+	}
+	/**
+	
+	* Express middleware: validate that the token in the request contains the specified scopes.
+	
+	*
+	
+	* Must be used after the `authenticate()` middleware.
+	
+	*
+	
+	* @example
+	
+	* ```typescript
+	
+	* app.get('/api/profile',
+	
+	*     client.authenticate(),
+	
+	*     client.requireScopes('profile'),
+	
+	*     (req, res) => { ... }
+	
+	* )
+	
+	* ```
+	
+	*/
+	requireScopes(...scopes) {
+		return (req, res, next) => {
+			const auth = getAuth(req);
+			if (!auth) {
+				sendOAuthError(res, 401, "invalid_token", "Request not authenticated");
+				return;
+			}
+			const tokenScopes = auth.scope.split(" ");
+			const missingScopes = scopes.filter((s) => !tokenScopes.includes(s));
+			if (missingScopes.length > 0) {
+				sendOAuthError(res, 403, "insufficient_scope", `Missing required scopes: ${missingScopes.join(" ")}`);
+				return;
+			}
+			next();
+		};
+	}
+	async resolveEndpoint(name) {
+		const explicit = this.config.endpoints?.[name];
+		if (explicit) return explicit;
+		const discovery = await this.discover();
+		const discoveryKey = DISCOVERY_ENDPOINT_MAP[name];
+		const endpoint = discovery[discoveryKey];
+		if (!endpoint || typeof endpoint !== "string") throw new NyaAccountError("endpoint_not_found", `Endpoint '${name}' not found in Discovery document`);
+		return endpoint;
+	}
+	async getJwtVerifier() {
+		if (this.jwtVerifier) return this.jwtVerifier;
+		const jwksUri = await this.resolveEndpoint("jwks");
+		const discovery = await this.discover();
+		this.jwtVerifier = new JwtVerifier(jwksUri, discovery.issuer, this.config.clientId);
+		return this.jwtVerifier;
+	}
+	mapTokenResponse(data) {
+		const raw = TokenResponseSchema.parse(data);
+		return {
+			accessToken: raw.access_token,
+			tokenType: raw.token_type,
+			expiresIn: raw.expires_in,
+			refreshToken: raw.refresh_token,
+			scope: raw.scope,
+			idToken: raw.id_token
+		};
+	}
+	handleTokenError(error) {
+		if (error instanceof NyaAccountError) return error;
+		if (error instanceof AxiosError && error.response) {
+			const parsed = OAuthErrorSchema.safeParse(error.response.data);
+			if (parsed.success) return new OAuthError(parsed.data.error, parsed.data.error_description ?? "Unknown error");
+		}
+		const message = error instanceof Error ? error.message : "Unknown error";
+		return new NyaAccountError("request_failed", `Request failed: ${message}`);
+	}
+};
+
+//#endregion
+export { DiscoveryError, NyaAccountClient, NyaAccountError, OAuthError, TokenVerificationError, generateCodeChallenge, generateCodeVerifier, generatePkce, getAuth };
+//# sourceMappingURL=index.js.map