@nya-account/node-sdk 2.0.0

package/dist/index.d.ts

@@ -0,0 +1,307 @@
+import { AccessTokenPayload, IdTokenPayload, getAuth$1 as getAuth } from "./express-yO7hxKKd.js";
+import { NextFunction, Request, Response } from "express";
+
+//#region src/core/types.d.ts
+interface NyaAccountConfig {
+  /** SSO service URL (Issuer URL), can be the service or daemon address */
+  issuer: string;
+  /** OAuth client ID */
+  clientId: string;
+  /** OAuth client secret */
+  clientSecret: string;
+  /** HTTP request timeout in milliseconds (default: 10000) */
+  timeout?: number;
+  /** Discovery document cache TTL in milliseconds (default: 3600000 = 1 hour) */
+  discoveryCacheTtl?: number;
+  /** Explicitly specify endpoint URLs (optional, auto-discovered via OIDC Discovery if omitted) */
+  endpoints?: EndpointConfig;
+}
+interface EndpointConfig {
+  authorization?: string;
+  token?: string;
+  userinfo?: string;
+  revocation?: string;
+  introspection?: string;
+  jwks?: string;
+  endSession?: string;
+}
+interface TokenResponse {
+  accessToken: string;
+  tokenType: string;
+  expiresIn: number;
+  refreshToken: string;
+  scope: string;
+  idToken?: string;
+}
+interface UserInfo {
+  sub: string;
+  name?: string;
+  preferredUsername?: string;
+  email?: string;
+  emailVerified?: boolean;
+  updatedAt?: number;
+}
+interface IntrospectionResponse {
+  active: boolean;
+  scope?: string;
+  clientId?: string;
+  username?: string;
+  tokenType?: string;
+  exp?: number;
+  iat?: number;
+  sub?: string;
+  aud?: string;
+  iss?: string;
+  jti?: string;
+}
+interface DiscoveryDocument {
+  issuer: string;
+  authorizationEndpoint: string;
+  tokenEndpoint: string;
+  userinfoEndpoint?: string;
+  jwksUri: string;
+  revocationEndpoint?: string;
+  introspectionEndpoint?: string;
+  pushedAuthorizationRequestEndpoint?: string;
+  endSessionEndpoint?: string;
+  responseTypesSupported: string[];
+  grantTypesSupported: string[];
+  idTokenSigningAlgValuesSupported: string[];
+  scopesSupported: string[];
+  subjectTypesSupported: string[];
+  tokenEndpointAuthMethodsSupported: string[];
+  codeChallengeMethodsSupported?: string[];
+  claimsSupported?: string[];
+}
+interface CreateAuthorizationUrlOptions {
+  /** Redirect URI, must match the one registered with the OAuth client */
+  redirectUri: string;
+  /** Requested scopes, space-separated (default: 'openid') */
+  scope?: string;
+  /** CSRF protection parameter, auto-generated if not provided */
+  state?: string;
+  /** ID Token replay protection parameter */
+  nonce?: string;
+}
+interface AuthorizationUrlResult {
+  /** Full authorization URL to redirect the user to */
+  url: string;
+  /** PKCE code_verifier, must be stored in session for later token exchange */
+  codeVerifier: string;
+  /** State parameter, must be stored in session for CSRF validation */
+  state: string;
+}
+interface ExchangeCodeOptions {
+  /** Authorization code received in the callback */
+  code: string;
+  /** Redirect URI (must match the one used during authorization) */
+  redirectUri: string;
+  /** PKCE code_verifier saved during the authorization step */
+  codeVerifier: string;
+}
+interface AuthenticateOptions {
+  /** Token verification strategy: 'local' for JWT local verification (default), 'introspection' for remote introspection */
+  strategy?: 'local' | 'introspection';
+}
+interface PkcePair {
+  codeVerifier: string;
+  codeChallenge: string;
+} //#endregion
+//#region src/client.d.ts
+
+/**
+ * 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)
+ * ```
+ */
+declare class NyaAccountClient {
+  private httpClient;
+  private config;
+  private discoveryCache;
+  private discoveryCacheTimestamp;
+  private readonly discoveryCacheTtl;
+  private jwtVerifier;
+  constructor(config: NyaAccountConfig);
+  /**
+   * Fetch the OIDC Discovery document. Results are cached with a configurable TTL.
+   */
+  discover(): Promise<DiscoveryDocument>;
+  /**
+   * Clear the cached Discovery document and JWT verifier, forcing a re-fetch on next use.
+   */
+  clearCache(): void;
+  /**
+   * 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.
+   */
+  createAuthorizationUrl(options: CreateAuthorizationUrlOptions): Promise<AuthorizationUrlResult>;
+  /**
+   * Exchange an authorization code for tokens (Authorization Code Grant).
+   */
+  exchangeCode(options: ExchangeCodeOptions): Promise<TokenResponse>;
+  /**
+   * Refresh an Access Token using a Refresh Token.
+   */
+  refreshToken(refreshToken: string): Promise<TokenResponse>;
+  /**
+   * Revoke a token (RFC 7009).
+   *
+   * Supports revoking Access Tokens or Refresh Tokens.
+   * Revoking a Refresh Token also revokes its entire token family.
+   */
+  revokeToken(token: string): Promise<void>;
+  /**
+   * Token introspection (RFC 7662).
+   *
+   * Query the server for the current state of a token (active status, associated user info, etc.).
+   */
+  introspectToken(token: string): Promise<IntrospectionResponse>;
+  /**
+   * 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
+   */
+  getUserInfo(accessToken: string): Promise<UserInfo>;
+  /**
+   * 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)
+   */
+  verifyAccessToken(token: string, options?: {
+    audience?: string;
+  }): Promise<AccessTokenPayload>;
+  /**
+   * 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)
+   */
+  verifyIdToken(token: string, options?: {
+    audience?: string;
+    nonce?: string;
+  }): Promise<IdTokenPayload>;
+  /**
+   * 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?: AuthenticateOptions): (req: Request, res: Response, next: NextFunction) => void;
+  /**
+   * 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: string[]): (req: Request, res: Response, next: NextFunction) => void;
+  private resolveEndpoint;
+  private getJwtVerifier;
+  private mapTokenResponse;
+  private handleTokenError;
+} //#endregion
+//#region src/core/errors.d.ts
+/**
+ * Base error class for the SDK.
+ */
+declare class NyaAccountError extends Error {
+  readonly code: string;
+  readonly description: string;
+  constructor(code: string, description: string);
+}
+/**
+ * OAuth protocol error (from server error / error_description response).
+ */
+declare class OAuthError extends NyaAccountError {
+  constructor(error: string, errorDescription: string);
+}
+/**
+ * JWT verification error.
+ */
+declare class TokenVerificationError extends NyaAccountError {
+  constructor(description: string);
+}
+/**
+ * OIDC Discovery error.
+ */
+declare class DiscoveryError extends NyaAccountError {
+  constructor(description: string);
+}
+
+//#endregion
+//#region src/utils/pkce.d.ts
+/**
+ * Generate a PKCE code_verifier (43-128 character random string).
+ */
+declare function generateCodeVerifier(): string;
+/**
+ * Generate an S256 code_challenge from a code_verifier.
+ */
+declare function generateCodeChallenge(codeVerifier: string): string;
+/**
+ * Generate a PKCE code_verifier and code_challenge pair.
+ */
+declare function generatePkce(): PkcePair;
+
+//#endregion
+export { AccessTokenPayload, AuthenticateOptions, AuthorizationUrlResult, CreateAuthorizationUrlOptions, DiscoveryDocument, DiscoveryError, EndpointConfig, ExchangeCodeOptions, IdTokenPayload, IntrospectionResponse, NyaAccountClient, NyaAccountConfig, NyaAccountError, OAuthError, PkcePair, TokenResponse, TokenVerificationError, UserInfo, generateCodeChallenge, generateCodeVerifier, generatePkce, getAuth };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/core/types.d.ts","../src/client.d.ts","../src/core/errors.d.ts","../src/utils/pkce.d.ts"],"sourcesContent":null,"mappings":";;;;AAEA,IAAW,mBAAmB,CAAC,IAAG,MAAA,cAAA;AAClC,IAAW,iBAAiB,CAAC,EAAG;AAChC,IAAW,gBAAO,CAAA,EAAA;AAClB,IAAW,WAAW,CAAC,EAAE;AACzB,IAAW,wBAAS,CAAA,EAAA;AACpB,IAAW,oBAAkB,CAAA,EAAA;AAC7B,IAAW,gCAAa,CAAA,EAAA;AACxB,IAAW,yBAAyB,CAAC,EAAG;AACxC,IAAW,sBAAS,CAAA,EAAA;AACpB,IAAW,sBAAsB,CAAC,EAAG;AACrC,IAAW,WAAW,CAAC,EAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AC2B1B,IAAW,mBAAmB;CAAC;CAAG,MAAI;CAAA,MAAA;CAAA,MAAA;CAAA,MAAA;CAAA,MAAA;CAAA,MAAA;CAAA,MAAA;CAAA,MAAA;CAAA,MAAA;CAAA,MAAA;CAAA,MAAA;CAAA,MAAA;CAAA,MAAA;CAAA,MAAA;CAAA,MAAA;CAAA,MAAA;CAAA,MAAA;CAAA,MAAA;CAAA,MAAA;CAAA,MAAA;CAAA,MAAA;CAAA,MAAA;CAAA,MAAA;CAAA,MAAA;CAAA,MAAA;CAAA,MAAA;CAAA,MAAA;AAAA;;;;;;;ACpCtC,IAAW,kBAAkB,CAAC,IAAI,MAAM,KAAM;;;;AAI9C,IAAA,aAAA,CAAA,IAAA,MAAA,eAAA;;;;AAIA,IAAW,yBAAyB,CAAC,IAAI,MAAM,eAAS;;;;AAIxD,IAAW,iBAAc,CAAA,IAAA,MAAA,eAAA;;;;;;;ACXzB,IAAW,uBAAuB,CAAC,EAAG;;;;AAItC,IAAW,wBAAwB,CAAC,EAAG;;;;AAIvC,IAAW,eAAe,CAAC,IAAI,MAAM,QAAS"}