@stonyx/oauth 0.1.1-beta.40 → 0.1.1-beta.42

package/dist/auth-request.d.ts

@@ -0,0 +1,35 @@
+import { Request } from '@stonyx/rest-server';
+interface OAuthInstance {
+    frontendCallbackUrl?: string;
+    getSession(sessionId: string): unknown;
+    getAuthorizationUrl(providerName: string): string;
+    handleCallback(providerName: string, code: string, stateToken: string): Promise<{
+        sessionId: string;
+        expiresAt: number;
+    }>;
+    logout(sessionId: string): void;
+}
+interface RouteRequest {
+    headers: Record<string, string | undefined>;
+    params: Record<string, string>;
+    query: Record<string, string>;
+}
+interface RouteState {
+    redirect?: string;
+}
+export default class AuthRequest extends Request {
+    oauth: OAuthInstance;
+    constructor(oauth: OAuthInstance);
+    handlers: {
+        get: {
+            '/': ({ headers }: RouteRequest) => {};
+            '/login/:provider': (req: RouteRequest, state: RouteState) => 404 | undefined;
+            '/callback/:provider': (req: RouteRequest, state: RouteState) => Promise<{
+                sessionId: string;
+                expiresAt: number;
+            } | 400 | 500 | undefined>;
+            '/logout': ({ headers }: RouteRequest) => void;
+        };
+    };
+}
+export {};

package/dist/auth-request.js

@@ -0,0 +1,68 @@
+import { Request } from '@stonyx/rest-server';
+export default class AuthRequest extends Request {
+    oauth;
+    constructor(oauth) {
+        super();
+        this.oauth = oauth;
+    }
+    handlers = {
+        get: {
+            '/': ({ headers }) => {
+                const sessionId = headers['session-id'];
+                if (!sessionId)
+                    return 401;
+                const user = this.oauth.getSession(sessionId);
+                if (!user)
+                    return 401;
+                return user;
+            },
+            '/login/:provider': (req, state) => {
+                const { provider: providerName } = req.params;
+                try {
+                    const url = this.oauth.getAuthorizationUrl(providerName);
+                    state.redirect = url;
+                }
+                catch {
+                    return 404;
+                }
+            },
+            '/callback/:provider': async (req, state) => {
+                const { provider: providerName } = req.params;
+                const { code, state: stateToken, error } = req.query;
+                if (error) {
+                    if (this.oauth.frontendCallbackUrl) {
+                        state.redirect = `${this.oauth.frontendCallbackUrl}?error=${encodeURIComponent(error)}`;
+                        return;
+                    }
+                    return 400;
+                }
+                if (!code)
+                    return 400;
+                try {
+                    const session = await this.oauth.handleCallback(providerName, code, stateToken);
+                    if (this.oauth.frontendCallbackUrl) {
+                        const params = new URLSearchParams({
+                            sessionId: session.sessionId,
+                            expiresAt: String(session.expiresAt),
+                        });
+                        state.redirect = `${this.oauth.frontendCallbackUrl}?${params}`;
+                        return;
+                    }
+                    return session;
+                }
+                catch {
+                    if (this.oauth.frontendCallbackUrl) {
+                        state.redirect = `${this.oauth.frontendCallbackUrl}?error=auth_failed`;
+                        return;
+                    }
+                    return 500;
+                }
+            },
+            '/logout': ({ headers }) => {
+                const sessionId = headers['session-id'];
+                if (sessionId)
+                    this.oauth.logout(sessionId);
+            },
+        }
+    };
+}

package/dist/main.d.ts

@@ -0,0 +1,22 @@
+import TokenManager from './token-manager.js';
+import SessionManager from './session-manager.js';
+import type OAuthFlow from './oauth-flow.js';
+interface ProviderEntry {
+    flow: OAuthFlow;
+    tokenManager: TokenManager;
+}
+export default class OAuth {
+    static instance: OAuth | null;
+    providers: Map<string, ProviderEntry>;
+    pendingStates: Map<string, number>;
+    sessionManager: SessionManager;
+    frontendCallbackUrl?: string;
+    constructor();
+    init(): Promise<void>;
+    getProvider(name: string): ProviderEntry;
+    getAuthorizationUrl(providerName: string): string;
+    handleCallback(providerName: string, code: string, stateToken: string): Promise<import("./session-manager.js").SessionResult>;
+    getSession(sessionId: string): unknown;
+    logout(sessionId: string): void;
+}
+export {};

package/dist/main.js

@@ -0,0 +1,75 @@
+import config from 'stonyx/config';
+import log from 'stonyx/log';
+import { waitForModule } from 'stonyx';
+import { setup, emit } from '@stonyx/events';
+import RestServer from '@stonyx/rest-server';
+import TokenManager from './token-manager.js';
+import SessionManager from './session-manager.js';
+import AuthRequest from './auth-request.js';
+setup(['authenticate']);
+export default class OAuth {
+    static instance;
+    providers = new Map();
+    pendingStates = new Map();
+    sessionManager;
+    frontendCallbackUrl;
+    constructor() {
+        if (OAuth.instance)
+            return OAuth.instance;
+        OAuth.instance = this;
+    }
+    async init() {
+        const oauthConfig = config.oauth;
+        const { providers, sessionDuration, frontendCallbackUrl } = oauthConfig;
+        this.frontendCallbackUrl = frontendCallbackUrl;
+        for (const [name, providerConfig] of Object.entries(providers)) {
+            const modulePath = providerConfig.module
+                ? `${config.rootPath}/${providerConfig.module}`
+                : `./providers/${name}.js`;
+            const { default: Provider } = await import(modulePath);
+            const flow = new Provider(providerConfig);
+            this.providers.set(name, { flow, tokenManager: new TokenManager(flow) });
+        }
+        this.sessionManager = new SessionManager(sessionDuration);
+        await waitForModule('rest-server');
+        RestServer.instance.mountRoute(AuthRequest, { name: 'auth', options: this });
+        log.oauth?.('OAuth module initialized');
+    }
+    getProvider(name) {
+        const provider = this.providers.get(name);
+        if (!provider)
+            throw new Error(`OAuth provider "${name}" is not configured`);
+        return provider;
+    }
+    getAuthorizationUrl(providerName) {
+        const { flow } = this.getProvider(providerName);
+        const stateToken = crypto.randomUUID();
+        this.pendingStates.set(stateToken, Date.now());
+        return flow.buildAuthorizationUrl(stateToken);
+    }
+    async handleCallback(providerName, code, stateToken) {
+        if (!stateToken || !this.pendingStates.has(stateToken)) {
+            throw new Error('Invalid or missing state token');
+        }
+        const stateCreatedAt = this.pendingStates.get(stateToken);
+        if (stateCreatedAt === undefined)
+            throw new Error('State token not found in pending states');
+        this.pendingStates.delete(stateToken);
+        const TEN_MINUTES = 10 * 60 * 1000;
+        if (Date.now() - stateCreatedAt > TEN_MINUTES) {
+            throw new Error('State token has expired');
+        }
+        const { flow, tokenManager } = this.getProvider(providerName);
+        const tokens = await tokenManager.getTokens(code);
+        const rawUser = await flow.fetchUserInfo(tokens.accessToken);
+        const user = flow.normalizeUser(rawUser);
+        await emit('authenticate', user);
+        return this.sessionManager.create(user, tokens);
+    }
+    getSession(sessionId) {
+        return this.sessionManager.validate(sessionId);
+    }
+    logout(sessionId) {
+        this.sessionManager.destroy(sessionId);
+    }
+}

package/dist/oauth-flow.d.ts

@@ -0,0 +1,30 @@
+export interface OAuthConfig {
+    clientId: string;
+    clientSecret: string;
+    redirectUri: string;
+    scopes?: string[];
+    authorizationUrl: string;
+    tokenUrl: string;
+    userInfoUrl: string;
+}
+export interface TokenResult {
+    accessToken: string;
+    refreshToken: string | null;
+    expiresIn: number;
+}
+export default class OAuthFlow {
+    clientId: string;
+    clientSecret: string;
+    redirectUri: string;
+    scopes: string[];
+    authorizationUrl: string;
+    tokenUrl: string;
+    userInfoUrl: string;
+    constructor({ clientId, clientSecret, redirectUri, scopes, authorizationUrl, tokenUrl, userInfoUrl }: OAuthConfig);
+    buildAuthorizationUrl(stateToken: string): string;
+    exchangeCode(code: string): Promise<TokenResult>;
+    refreshAccessToken(refreshToken: string): Promise<TokenResult>;
+    fetchUserInfo(accessToken: string): Promise<unknown>;
+    normalizeUser(rawUser: unknown): unknown;
+    revokeToken(_accessToken: string): Promise<void>;
+}

package/dist/oauth-flow.js

@@ -0,0 +1,83 @@
+export default class OAuthFlow {
+    clientId;
+    clientSecret;
+    redirectUri;
+    scopes;
+    authorizationUrl;
+    tokenUrl;
+    userInfoUrl;
+    constructor({ clientId, clientSecret, redirectUri, scopes, authorizationUrl, tokenUrl, userInfoUrl }) {
+        this.clientId = clientId;
+        this.clientSecret = clientSecret;
+        this.redirectUri = redirectUri;
+        this.scopes = scopes || [];
+        this.authorizationUrl = authorizationUrl;
+        this.tokenUrl = tokenUrl;
+        this.userInfoUrl = userInfoUrl;
+    }
+    buildAuthorizationUrl(stateToken) {
+        const params = new URLSearchParams({
+            client_id: this.clientId,
+            redirect_uri: this.redirectUri,
+            response_type: 'code',
+            scope: this.scopes.join(' '),
+            state: stateToken,
+        });
+        return `${this.authorizationUrl}?${params.toString()}`;
+    }
+    async exchangeCode(code) {
+        const response = await fetch(this.tokenUrl, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                client_id: this.clientId,
+                client_secret: this.clientSecret,
+                grant_type: 'authorization_code',
+                code,
+                redirect_uri: this.redirectUri,
+            }),
+        });
+        if (!response.ok)
+            throw new Error(`Token exchange failed: ${response.status}`);
+        const data = await response.json();
+        return {
+            accessToken: data.access_token,
+            refreshToken: data.refresh_token || null,
+            expiresIn: data.expires_in,
+        };
+    }
+    async refreshAccessToken(refreshToken) {
+        const response = await fetch(this.tokenUrl, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                client_id: this.clientId,
+                client_secret: this.clientSecret,
+                grant_type: 'refresh_token',
+                refresh_token: refreshToken,
+            }),
+        });
+        if (!response.ok)
+            throw new Error(`Token refresh failed: ${response.status}`);
+        const data = await response.json();
+        return {
+            accessToken: data.access_token,
+            refreshToken: data.refresh_token || refreshToken,
+            expiresIn: data.expires_in,
+        };
+    }
+    async fetchUserInfo(accessToken) {
+        const response = await fetch(this.userInfoUrl, {
+            headers: { Authorization: `Bearer ${accessToken}` },
+        });
+        if (!response.ok)
+            throw new Error(`User info fetch failed: ${response.status}`);
+        return response.json();
+    }
+    normalizeUser(rawUser) {
+        return { raw: rawUser };
+    }
+    async revokeToken(_accessToken) {
+        // Optional — providers override if supported
+    }
+}

package/dist/providers/discord.d.ts

@@ -0,0 +1,30 @@
+import OAuthFlow from '../oauth-flow.js';
+import type { TokenResult } from '../oauth-flow.js';
+interface DiscordProviderConfig {
+    clientId: string;
+    clientSecret: string;
+    redirectUri: string;
+    scopes?: string[];
+    [key: string]: unknown;
+}
+interface DiscordUser {
+    id: string;
+    username: string;
+    global_name?: string;
+    avatar: string | null;
+    email?: string | null;
+}
+interface NormalizedDiscordUser {
+    id: string;
+    username: string;
+    displayName: string;
+    avatar: string | null;
+    email: string | null;
+    raw: DiscordUser;
+}
+export default class DiscordProvider extends OAuthFlow {
+    constructor(config: DiscordProviderConfig);
+    exchangeCode(code: string): Promise<TokenResult>;
+    normalizeUser(rawUser: DiscordUser): NormalizedDiscordUser;
+}
+export {};

package/dist/providers/discord.js

@@ -0,0 +1,43 @@
+import OAuthFlow from '../oauth-flow.js';
+export default class DiscordProvider extends OAuthFlow {
+    constructor(config) {
+        super({
+            ...config,
+            authorizationUrl: 'https://discord.com/oauth2/authorize',
+            tokenUrl: 'https://discord.com/api/oauth2/token',
+            userInfoUrl: 'https://discord.com/api/users/@me',
+        });
+    }
+    async exchangeCode(code) {
+        const response = await fetch(this.tokenUrl, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+            body: new URLSearchParams({
+                client_id: this.clientId,
+                client_secret: this.clientSecret,
+                grant_type: 'authorization_code',
+                code,
+                redirect_uri: this.redirectUri,
+            }),
+        });
+        if (!response.ok)
+            throw new Error(`Token exchange failed: ${response.status}`);
+        const data = await response.json();
+        return {
+            accessToken: data.access_token,
+            refreshToken: data.refresh_token || null,
+            expiresIn: data.expires_in,
+        };
+    }
+    normalizeUser(rawUser) {
+        const { id, username, global_name, avatar, email } = rawUser;
+        return {
+            id,
+            username,
+            displayName: global_name || username,
+            avatar: avatar ? `https://cdn.discordapp.com/avatars/${id}/${avatar}.png` : null,
+            email: email || null,
+            raw: rawUser,
+        };
+    }
+}

package/dist/session-manager.d.ts

@@ -0,0 +1,20 @@
+interface SessionData {
+    user: unknown;
+    tokens: unknown;
+    expiresAt: number;
+}
+export interface SessionResult {
+    sessionId: string;
+    user: unknown;
+    expiresAt: number;
+}
+export default class SessionManager {
+    sessions: Map<string, SessionData>;
+    duration: number;
+    constructor(duration: number);
+    create(user: unknown, tokens: unknown): SessionResult;
+    get(sessionId: string): SessionData | null;
+    destroy(sessionId: string): void;
+    validate(sessionId: string): unknown;
+}
+export {};

package/dist/session-manager.js

@@ -0,0 +1,30 @@
+import { randomUUID } from 'node:crypto';
+export default class SessionManager {
+    sessions = new Map();
+    duration;
+    constructor(duration) {
+        this.duration = duration;
+    }
+    create(user, tokens) {
+        const sessionId = randomUUID();
+        const expiresAt = Date.now() + (this.duration * 1000);
+        this.sessions.set(sessionId, { user, tokens, expiresAt });
+        return { sessionId, user, expiresAt };
+    }
+    get(sessionId) {
+        return this.sessions.get(sessionId) || null;
+    }
+    destroy(sessionId) {
+        this.sessions.delete(sessionId);
+    }
+    validate(sessionId) {
+        const session = this.get(sessionId);
+        if (!session)
+            return null;
+        if (Date.now() >= session.expiresAt) {
+            this.destroy(sessionId);
+            return null;
+        }
+        return session.user;
+    }
+}

package/dist/token-manager.d.ts

@@ -0,0 +1,15 @@
+import type OAuthFlow from './oauth-flow.js';
+import type { TokenResult } from './oauth-flow.js';
+export interface TokenData extends TokenResult {
+    expiresAt: number;
+}
+export default class TokenManager {
+    flow: OAuthFlow;
+    constructor(flow: OAuthFlow);
+    getTokens(code: string): Promise<TokenData>;
+    refresh(refreshToken: string): Promise<TokenData>;
+    revoke(accessToken: string): Promise<void>;
+    isExpired(tokenData: {
+        expiresAt?: number;
+    } | null | undefined): boolean;
+}

package/dist/token-manager.js

@@ -0,0 +1,24 @@
+export default class TokenManager {
+    flow;
+    constructor(flow) {
+        this.flow = flow;
+    }
+    async getTokens(code) {
+        const tokens = await this.flow.exchangeCode(code);
+        tokens.expiresAt = Date.now() + (tokens.expiresIn * 1000);
+        return tokens;
+    }
+    async refresh(refreshToken) {
+        const tokens = await this.flow.refreshAccessToken(refreshToken);
+        tokens.expiresAt = Date.now() + (tokens.expiresIn * 1000);
+        return tokens;
+    }
+    async revoke(accessToken) {
+        return this.flow.revokeToken(accessToken);
+    }
+    isExpired(tokenData) {
+        if (!tokenData?.expiresAt)
+            return true;
+        return Date.now() >= tokenData.expiresAt;
+    }
+}

package/package.json

@@ -4,16 +4,39 @@
     "stonyx-async",
     "stonyx-module"
   ],
-  "version": "0.1.1-beta.40",
+  "version": "0.1.1-beta.42",
   "description": "OAuth2 authentication module for the Stonyx framework",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/abofs/stonyx-oauth.git"
   },
-  "main": "src/main.js",
+  "main": "dist/main.js",
   "type": "module",
   "exports": {
-    ".": "./src/main.js"
+    ".": {
+      "types": "./dist/main.d.ts",
+      "default": "./dist/main.js"
+    },
+    "./oauth-flow": {
+      "types": "./dist/oauth-flow.d.ts",
+      "default": "./dist/oauth-flow.js"
+    },
+    "./auth-request": {
+      "types": "./dist/auth-request.d.ts",
+      "default": "./dist/auth-request.js"
+    },
+    "./session-manager": {
+      "types": "./dist/session-manager.d.ts",
+      "default": "./dist/session-manager.js"
+    },
+    "./token-manager": {
+      "types": "./dist/token-manager.d.ts",
+      "default": "./dist/token-manager.js"
+    },
+    "./providers/discord": {
+      "types": "./dist/providers/discord.d.ts",
+      "default": "./dist/providers/discord.js"
+    }
   },
   "author": "Stone Costa",
   "license": "Apache-2.0",
@@ -21,6 +44,7 @@
     "Stone Costa <stone.costa@synamicd.com>"
   ],
   "files": [
+    "dist",
     "src",
     "config",
     "README.md"
@@ -40,9 +64,12 @@
     "@stonyx/rest-server": "0.2.1-beta.30",
     "@stonyx/utils": "0.2.3-beta.7",
     "qunit": "^2.24.1",
-    "sinon": "^21.0.0"
+    "sinon": "^21.0.0",
+    "typescript": "^5.8.3"
   },
   "scripts": {
-    "test": "stonyx test"
+    "build": "tsc",
+    "build:test": "tsc -p tsconfig.test.json",
+    "test": "npm run build && npm run build:test && stonyx test 'dist-test/test/**/*-test.js'"
   }
 }

package/src/{auth-request.js → auth-request.ts}

@@ -1,14 +1,34 @@
 import { Request } from '@stonyx/rest-server';
 
+interface OAuthInstance {
+  frontendCallbackUrl?: string;
+  getSession(sessionId: string): unknown;
+  getAuthorizationUrl(providerName: string): string;
+  handleCallback(providerName: string, code: string, stateToken: string): Promise<{ sessionId: string; expiresAt: number }>;
+  logout(sessionId: string): void;
+}
+
+interface RouteRequest {
+  headers: Record<string, string | undefined>;
+  params: Record<string, string>;
+  query: Record<string, string>;
+}
+
+interface RouteState {
+  redirect?: string;
+}
+
 export default class AuthRequest extends Request {
-  constructor(oauth) {
+  oauth: OAuthInstance;
+
+  constructor(oauth: OAuthInstance) {
     super();
     this.oauth = oauth;
   }
 
   handlers = {
     get: {
-      '/': ({ headers }) => {
+      '/': ({ headers }: RouteRequest) => {
         const sessionId = headers['session-id'];
         if (!sessionId) return 401;
 
@@ -18,7 +38,7 @@ export default class AuthRequest extends Request {
         return user;
       },
 
-      '/login/:provider': (req, state) => {
+      '/login/:provider': (req: RouteRequest, state: RouteState) => {
         const { provider: providerName } = req.params;
 
         try {
@@ -29,7 +49,7 @@ export default class AuthRequest extends Request {
         }
       },
 
-      '/callback/:provider': async (req, state) => {
+      '/callback/:provider': async (req: RouteRequest, state: RouteState) => {
         const { provider: providerName } = req.params;
         const { code, state: stateToken, error } = req.query;
 
@@ -49,7 +69,7 @@ export default class AuthRequest extends Request {
           if (this.oauth.frontendCallbackUrl) {
             const params = new URLSearchParams({
               sessionId: session.sessionId,
-              expiresAt: session.expiresAt,
+              expiresAt: String(session.expiresAt),
             });
             state.redirect = `${this.oauth.frontendCallbackUrl}?${params}`;
             return;
@@ -65,7 +85,7 @@ export default class AuthRequest extends Request {
         }
       },
 
-      '/logout': ({ headers }) => {
+      '/logout': ({ headers }: RouteRequest) => {
         const sessionId = headers['session-id'];
         if (sessionId) this.oauth.logout(sessionId);
       },

package/src/{main.js → main.ts}

@@ -6,20 +6,36 @@ import RestServer from '@stonyx/rest-server';
 import TokenManager from './token-manager.js';
 import SessionManager from './session-manager.js';
 import AuthRequest from './auth-request.js';
+import type OAuthFlow from './oauth-flow.js';
 
 setup(['authenticate']);
 
+interface ProviderEntry {
+  flow: OAuthFlow;
+  tokenManager: TokenManager;
+}
+
+interface ProviderConfig {
+  module?: string;
+  [key: string]: unknown;
+}
+
 export default class OAuth {
-  providers = new Map();
-  pendingStates = new Map();
+  static instance: OAuth | null;
+
+  providers = new Map<string, ProviderEntry>();
+  pendingStates = new Map<string, number>();
+  sessionManager!: SessionManager;
+  frontendCallbackUrl?: string;
 
   constructor() {
     if (OAuth.instance) return OAuth.instance;
     OAuth.instance = this;
   }
 
-  async init() {
-    const { providers, sessionDuration, frontendCallbackUrl } = config.oauth;
+  async init(): Promise<void> {
+    const oauthConfig = config.oauth;
+    const { providers, sessionDuration, frontendCallbackUrl } = oauthConfig;
     this.frontendCallbackUrl = frontendCallbackUrl;
 
     for (const [name, providerConfig] of Object.entries(providers)) {
@@ -27,7 +43,7 @@ export default class OAuth {
         ? `${config.rootPath}/${providerConfig.module}`
         : `./providers/${name}.js`;
       const { default: Provider } = await import(modulePath);
-      const flow = new Provider(providerConfig);
+      const flow: OAuthFlow = new Provider(providerConfig);
       this.providers.set(name, { flow, tokenManager: new TokenManager(flow) });
     }
 
@@ -39,25 +55,26 @@ export default class OAuth {
     log.oauth?.('OAuth module initialized');
   }
 
-  getProvider(name) {
+  getProvider(name: string): ProviderEntry {
     const provider = this.providers.get(name);
     if (!provider) throw new Error(`OAuth provider "${name}" is not configured`);
     return provider;
   }
 
-  getAuthorizationUrl(providerName) {
+  getAuthorizationUrl(providerName: string): string {
     const { flow } = this.getProvider(providerName);
     const stateToken = crypto.randomUUID();
     this.pendingStates.set(stateToken, Date.now());
     return flow.buildAuthorizationUrl(stateToken);
   }
 
-  async handleCallback(providerName, code, stateToken) {
+  async handleCallback(providerName: string, code: string, stateToken: string) {
     if (!stateToken || !this.pendingStates.has(stateToken)) {
       throw new Error('Invalid or missing state token');
     }
 
     const stateCreatedAt = this.pendingStates.get(stateToken);
+    if (stateCreatedAt === undefined) throw new Error('State token not found in pending states');
     this.pendingStates.delete(stateToken);
 
     const TEN_MINUTES = 10 * 60 * 1000;
@@ -73,11 +90,11 @@ export default class OAuth {
     return this.sessionManager.create(user, tokens);
   }
 
-  getSession(sessionId) {
+  getSession(sessionId: string) {
     return this.sessionManager.validate(sessionId);
   }
 
-  logout(sessionId) {
+  logout(sessionId: string): void {
     this.sessionManager.destroy(sessionId);
   }
 }

package/src/{oauth-flow.js → oauth-flow.ts}

@@ -1,5 +1,29 @@
+export interface OAuthConfig {
+  clientId: string;
+  clientSecret: string;
+  redirectUri: string;
+  scopes?: string[];
+  authorizationUrl: string;
+  tokenUrl: string;
+  userInfoUrl: string;
+}
+
+export interface TokenResult {
+  accessToken: string;
+  refreshToken: string | null;
+  expiresIn: number;
+}
+
 export default class OAuthFlow {
-  constructor({ clientId, clientSecret, redirectUri, scopes, authorizationUrl, tokenUrl, userInfoUrl }) {
+  clientId: string;
+  clientSecret: string;
+  redirectUri: string;
+  scopes: string[];
+  authorizationUrl: string;
+  tokenUrl: string;
+  userInfoUrl: string;
+
+  constructor({ clientId, clientSecret, redirectUri, scopes, authorizationUrl, tokenUrl, userInfoUrl }: OAuthConfig) {
     this.clientId = clientId;
     this.clientSecret = clientSecret;
     this.redirectUri = redirectUri;
@@ -9,7 +33,7 @@ export default class OAuthFlow {
     this.userInfoUrl = userInfoUrl;
   }
 
-  buildAuthorizationUrl(stateToken) {
+  buildAuthorizationUrl(stateToken: string): string {
     const params = new URLSearchParams({
       client_id: this.clientId,
       redirect_uri: this.redirectUri,
@@ -21,7 +45,7 @@ export default class OAuthFlow {
     return `${this.authorizationUrl}?${params.toString()}`;
   }
 
-  async exchangeCode(code) {
+  async exchangeCode(code: string): Promise<TokenResult> {
     const response = await fetch(this.tokenUrl, {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
@@ -45,7 +69,7 @@ export default class OAuthFlow {
     };
   }
 
-  async refreshAccessToken(refreshToken) {
+  async refreshAccessToken(refreshToken: string): Promise<TokenResult> {
     const response = await fetch(this.tokenUrl, {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
@@ -68,7 +92,7 @@ export default class OAuthFlow {
     };
   }
 
-  async fetchUserInfo(accessToken) {
+  async fetchUserInfo(accessToken: string): Promise<unknown> {
     const response = await fetch(this.userInfoUrl, {
       headers: { Authorization: `Bearer ${accessToken}` },
     });
@@ -78,11 +102,11 @@ export default class OAuthFlow {
     return response.json();
   }
 
-  normalizeUser(rawUser) {
+  normalizeUser(rawUser: unknown): unknown {
     return { raw: rawUser };
   }
 
-  async revokeToken(_accessToken) {
+  async revokeToken(_accessToken: string): Promise<void> {
     // Optional — providers override if supported
   }
 }

package/src/providers/{discord.js → discord.ts}

@@ -1,7 +1,33 @@
 import OAuthFlow from '../oauth-flow.js';
+import type { TokenResult } from '../oauth-flow.js';
+
+interface DiscordProviderConfig {
+  clientId: string;
+  clientSecret: string;
+  redirectUri: string;
+  scopes?: string[];
+  [key: string]: unknown;
+}
+
+interface DiscordUser {
+  id: string;
+  username: string;
+  global_name?: string;
+  avatar: string | null;
+  email?: string | null;
+}
+
+interface NormalizedDiscordUser {
+  id: string;
+  username: string;
+  displayName: string;
+  avatar: string | null;
+  email: string | null;
+  raw: DiscordUser;
+}
 
 export default class DiscordProvider extends OAuthFlow {
-  constructor(config) {
+  constructor(config: DiscordProviderConfig) {
     super({
       ...config,
       authorizationUrl: 'https://discord.com/oauth2/authorize',
@@ -10,7 +36,7 @@ export default class DiscordProvider extends OAuthFlow {
     });
   }
 
-  async exchangeCode(code) {
+  async exchangeCode(code: string): Promise<TokenResult> {
     const response = await fetch(this.tokenUrl, {
       method: 'POST',
       headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
@@ -34,7 +60,7 @@ export default class DiscordProvider extends OAuthFlow {
     };
   }
 
-  normalizeUser(rawUser) {
+  override normalizeUser(rawUser: DiscordUser): NormalizedDiscordUser {
     const { id, username, global_name, avatar, email } = rawUser;
 
     return {

package/src/{session-manager.js → session-manager.ts}

@@ -1,13 +1,26 @@
 import { randomUUID } from 'node:crypto';
 
+interface SessionData {
+  user: unknown;
+  tokens: unknown;
+  expiresAt: number;
+}
+
+export interface SessionResult {
+  sessionId: string;
+  user: unknown;
+  expiresAt: number;
+}
+
 export default class SessionManager {
-  sessions = new Map();
+  sessions = new Map<string, SessionData>();
+  duration: number;
 
-  constructor(duration) {
+  constructor(duration: number) {
     this.duration = duration;
   }
 
-  create(user, tokens) {
+  create(user: unknown, tokens: unknown): SessionResult {
     const sessionId = randomUUID();
     const expiresAt = Date.now() + (this.duration * 1000);
 
@@ -16,15 +29,15 @@ export default class SessionManager {
     return { sessionId, user, expiresAt };
   }
 
-  get(sessionId) {
+  get(sessionId: string): SessionData | null {
     return this.sessions.get(sessionId) || null;
   }
 
-  destroy(sessionId) {
+  destroy(sessionId: string): void {
     this.sessions.delete(sessionId);
   }
 
-  validate(sessionId) {
+  validate(sessionId: string): unknown {
     const session = this.get(sessionId);
     if (!session) return null;
 

package/src/token-manager.ts

@@ -0,0 +1,35 @@
+import type OAuthFlow from './oauth-flow.js';
+import type { TokenResult } from './oauth-flow.js';
+
+export interface TokenData extends TokenResult {
+  expiresAt: number;
+}
+
+export default class TokenManager {
+  flow: OAuthFlow;
+
+  constructor(flow: OAuthFlow) {
+    this.flow = flow;
+  }
+
+  async getTokens(code: string): Promise<TokenData> {
+    const tokens = await this.flow.exchangeCode(code) as TokenData;
+    tokens.expiresAt = Date.now() + (tokens.expiresIn * 1000);
+    return tokens;
+  }
+
+  async refresh(refreshToken: string): Promise<TokenData> {
+    const tokens = await this.flow.refreshAccessToken(refreshToken) as TokenData;
+    tokens.expiresAt = Date.now() + (tokens.expiresIn * 1000);
+    return tokens;
+  }
+
+  async revoke(accessToken: string): Promise<void> {
+    return this.flow.revokeToken(accessToken);
+  }
+
+  isExpired(tokenData: { expiresAt?: number } | null | undefined): boolean {
+    if (!tokenData?.expiresAt) return true;
+    return Date.now() >= tokenData.expiresAt;
+  }
+}

package/src/types/node.d.ts

@@ -0,0 +1,3 @@
+declare module 'node:crypto' {
+  export function randomUUID(): string;
+}

package/src/types/stonyx-events.d.ts

@@ -0,0 +1,4 @@
+declare module '@stonyx/events' {
+  export function setup(events: string[]): void;
+  export function emit(event: string, ...args: unknown[]): Promise<void>;
+}

package/src/types/stonyx-rest-server.d.ts

@@ -0,0 +1,11 @@
+declare module '@stonyx/rest-server' {
+  export class Request {
+    constructor();
+  }
+
+  export default class RestServer {
+    static instance: RestServer;
+    static close(): void;
+    mountRoute(RequestClass: unknown, options: { name: string; options?: unknown }): void;
+  }
+}

package/src/types/stonyx.d.ts

@@ -0,0 +1,30 @@
+declare module 'stonyx/config' {
+  interface OAuthConfig {
+    providers: Record<string, { module?: string; [key: string]: unknown }>;
+    sessionDuration: number;
+    frontendCallbackUrl?: string;
+  }
+  interface Config {
+    oauth: OAuthConfig;
+    rootPath: string;
+    [key: string]: unknown;
+  }
+  const config: Config;
+  export default config;
+}
+
+declare module 'stonyx/log' {
+  const log: Record<string, ((...args: unknown[]) => void) | undefined>;
+  export default log;
+}
+
+declare module 'stonyx' {
+  export function waitForModule(name: string): Promise<void>;
+}
+
+declare module 'stonyx/test-helpers' {
+  export function setupIntegrationTests(hooks: {
+    before(fn: () => void | Promise<void>): void;
+    after(fn: () => void | Promise<void>): void;
+  }): void;
+}

package/src/token-manager.js

@@ -1,26 +0,0 @@
-export default class TokenManager {
-  constructor(flow) {
-    this.flow = flow;
-  }
-
-  async getTokens(code) {
-    const tokens = await this.flow.exchangeCode(code);
-    tokens.expiresAt = Date.now() + (tokens.expiresIn * 1000);
-    return tokens;
-  }
-
-  async refresh(refreshToken) {
-    const tokens = await this.flow.refreshAccessToken(refreshToken);
-    tokens.expiresAt = Date.now() + (tokens.expiresIn * 1000);
-    return tokens;
-  }
-
-  async revoke(accessToken) {
-    return this.flow.revokeToken(accessToken);
-  }
-
-  isExpired(tokenData) {
-    if (!tokenData?.expiresAt) return true;
-    return Date.now() >= tokenData.expiresAt;
-  }
-}