@stonyx/oauth 0.1.0

package/.github/workflows/ci.yml

@@ -0,0 +1,16 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [dev, main]
+
+concurrency:
+  group: ci-${{ github.head_ref || github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    uses: abofs/stonyx-workflows/.github/workflows/ci.yml@main

package/.github/workflows/publish.yml

@@ -0,0 +1,35 @@
+name: Publish to NPM
+
+on:
+  workflow_dispatch:
+    inputs:
+      version-type:
+        description: 'Version type'
+        required: true
+        type: choice
+        options:
+          - patch
+          - minor
+          - major
+      custom-version:
+        description: 'Custom version (optional, overrides version-type)'
+        required: false
+        type: string
+  pull_request:
+    types: [opened, synchronize, reopened]
+    branches: [main]
+  push:
+    branches: [main]
+
+permissions:
+  contents: write
+  id-token: write
+  pull-requests: write
+
+jobs:
+  publish:
+    uses: abofs/stonyx-workflows/.github/workflows/npm-publish.yml@main
+    with:
+      version-type: ${{ github.event.inputs.version-type }}
+      custom-version: ${{ github.event.inputs.custom-version }}
+    secrets: inherit

package/LICENSE.md

@@ -0,0 +1,203 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [2025] [Stone Costa]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+

package/README.md

@@ -0,0 +1,123 @@
+# @stonyx/oauth
+
+OAuth2 authentication module for the Stonyx framework. Provides a generic OAuth2 Authorization Code flow with a provider pattern — ship with Discord support, extensible to any OAuth2 provider.
+
+## Setup
+
+Add as a devDependency to your Stonyx project:
+
+```bash
+npm install @stonyx/oauth
+```
+
+Requires `@stonyx/rest-server` as a peer dependency.
+
+The module auto-discovers and initializes via the Stonyx module loader — no changes needed in `app.js`.
+
+## Configuration
+
+Add an `oauth` section to your project's `config/environment.js`:
+
+```javascript
+export default {
+  // ... other config
+
+  oauth: {
+    providers: {
+      discord: {
+        clientId: process.env.DISCORD_OAUTH_CLIENT_ID,
+        clientSecret: process.env.DISCORD_OAUTH_CLIENT_SECRET,
+        redirectUri: process.env.DISCORD_OAUTH_REDIRECT_URI || 'http://localhost:4200/auth/callback/discord',
+        scopes: ['identify'],
+      }
+    }
+  }
+};
+```
+
+By default no providers are enabled. Add providers as keys in the `providers` object.
+
+### Config Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `providers` | `{}` | Map of provider name to config |
+| `sessionDuration` | `86400` | Session TTL in seconds (default: 24h) |
+
+## Routes
+
+The module self-registers the following routes on the rest server:
+
+| Method | Route | Description |
+|--------|-------|-------------|
+| `GET` | `/auth` | Validate session — send `session-id` header, returns user or 401 |
+| `GET` | `/auth/login/:provider` | Redirects to provider's OAuth2 authorization page |
+| `GET` | `/auth/callback/:provider` | OAuth2 callback — exchanges code for tokens, creates session |
+| `GET` | `/auth/logout` | Destroys session (send `session-id` header) |
+
+## Officially Supported Providers
+
+### Discord
+
+1. Create a Discord application at https://discord.com/developers/applications
+2. Under OAuth2, add a redirect URL matching your `redirectUri` config
+3. Copy the Client ID and Client Secret to your environment variables
+4. Available scopes: `identify`, `email`, `guilds` (see Discord docs)
+
+## Custom Providers
+
+Create a provider by extending `OAuthFlow`:
+
+```javascript
+import OAuthFlow from '@stonyx/oauth/oauth-flow';
+
+export default class MyProvider extends OAuthFlow {
+  constructor(config) {
+    super({
+      ...config,
+      authorizationUrl: 'https://my-provider.com/oauth/authorize',
+      tokenUrl: 'https://my-provider.com/oauth/token',
+      userInfoUrl: 'https://my-provider.com/api/me',
+    });
+  }
+
+  // Override if the provider uses a different content type for token exchange
+  async exchangeCode(code) { ... }
+
+  // Map provider-specific user data to a standard shape
+  normalizeUser(rawUser) {
+    return {
+      id: rawUser.id,
+      username: rawUser.login,
+      displayName: rawUser.name,
+      avatar: rawUser.avatar_url,
+      email: rawUser.email,
+      raw: rawUser,
+    };
+  }
+}
+```
+
+Place the file at `src/providers/<name>.js` where `<name>` matches the key in your config's `providers` object.
+
+Alternatively, specify a custom module path in the provider config:
+
+```javascript
+providers: {
+  custom: {
+    clientId: '...',
+    clientSecret: '...',
+    module: './lib/my-custom-provider.js',
+  }
+}
+```
+
+## Session Management
+
+Sessions are stored in-memory using a `Map`. Sessions are lost on server restart.
+
+Clients should store the `sessionId` returned from the callback and send it as a `session-id` header on subsequent requests.
+
+## License
+
+Apache-2.0

package/config/environment.js

@@ -0,0 +1,6 @@
+export default {
+  providers: {},
+  sessionDuration: 86400,
+  logColor: 'magenta',
+  logMethod: 'oauth',
+};

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@stonyx/oauth",
+  "keywords": [
+    "stonyx-async",
+    "stonyx-module"
+  ],
+  "version": "0.1.0",
+  "description": "OAuth2 authentication module for the Stonyx framework",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/abofs/stonyx-oauth.git"
+  },
+  "main": "src/main.js",
+  "type": "module",
+  "exports": {
+    ".": "./src/main.js"
+  },
+  "author": "Stone Costa",
+  "license": "Apache-2.0",
+  "contributors": [
+    "Stone Costa <stone.costa@synamicd.com>"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "stonyx": "^0.2.0"
+  },
+  "peerDependencies": {
+    "@stonyx/rest-server": ">=0.2.0"
+  },
+  "devDependencies": {
+    "@stonyx/rest-server": "^0.2.0",
+    "@stonyx/utils": "^0.2.2",
+    "qunit": "^2.24.1",
+    "sinon": "^21.0.0"
+  },
+  "scripts": {
+    "test": "stonyx test"
+  }
+}

package/src/auth-request.js

@@ -0,0 +1,51 @@
+import { Request } from '@stonyx/rest-server';
+
+export default class AuthRequest extends Request {
+  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) => {
+        const { provider: providerName } = req.params;
+        const { code, state: stateToken } = req.query;
+
+        if (!code) return 400;
+
+        try {
+          return await this.oauth.handleCallback(providerName, code, stateToken);
+        } catch {
+          return 500;
+        }
+      },
+
+      '/logout': ({ headers }) => {
+        const sessionId = headers['session-id'];
+        if (sessionId) this.oauth.logout(sessionId);
+      },
+    }
+  };
+}

package/src/main.js

@@ -0,0 +1,64 @@
+import config from 'stonyx/config';
+import log from 'stonyx/log';
+import { waitForModule } from 'stonyx';
+import RestServer from '@stonyx/rest-server';
+import TokenManager from './token-manager.js';
+import SessionManager from './session-manager.js';
+import AuthRequest from './auth-request.js';
+
+export default class OAuth {
+  providers = new Map();
+
+  constructor() {
+    if (OAuth.instance) return OAuth.instance;
+    OAuth.instance = this;
+  }
+
+  async init() {
+    const { providers, sessionDuration } = config.oauth;
+
+    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();
+    return flow.buildAuthorizationUrl(stateToken);
+  }
+
+  async handleCallback(providerName, code) {
+    const { flow, tokenManager } = this.getProvider(providerName);
+    const tokens = await tokenManager.getTokens(code);
+    const rawUser = await flow.fetchUserInfo(tokens.accessToken);
+    const user = flow.normalizeUser(rawUser);
+    return this.sessionManager.create(user, tokens);
+  }
+
+  getSession(sessionId) {
+    return this.sessionManager.validate(sessionId);
+  }
+
+  logout(sessionId) {
+    this.sessionManager.destroy(sessionId);
+  }
+}

package/src/oauth-flow.js

@@ -0,0 +1,88 @@
+export default class OAuthFlow {
+  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/src/providers/discord.js

@@ -0,0 +1,49 @@
+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/src/session-manager.js

@@ -0,0 +1,38 @@
+import { randomUUID } from 'node:crypto';
+
+export default class SessionManager {
+  sessions = new Map();
+
+  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/src/token-manager.js

@@ -0,0 +1,26 @@
+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;
+  }
+}

package/test/config/environment.js

@@ -0,0 +1,17 @@
+export default {
+  restServer: {
+    dir: './test/sample/requests',
+  },
+  oauth: {
+    providers: {
+      mock: {
+        clientId: 'test-client-id',
+        clientSecret: 'test-client-secret',
+        redirectUri: 'http://localhost:2666/auth/callback/mock',
+        scopes: ['identify'],
+        module: './test/sample/providers/mock.js',
+      }
+    },
+    sessionDuration: 3600,
+  }
+};

package/test/integration/oauth-test.js

@@ -0,0 +1,93 @@
+import QUnit from 'qunit';
+import RestServer from '@stonyx/rest-server';
+import config from 'stonyx/config';
+import { setupIntegrationTests } from 'stonyx/test-helpers';
+
+const { module, test } = QUnit;
+let endpoint;
+
+module('[Integration] OAuth', function(hooks) {
+  setupIntegrationTests(hooks);
+
+  hooks.before(function() {
+    endpoint = `http://localhost:${config.restServer.port}`;
+  });
+
+  hooks.after(function() {
+    RestServer.close();
+  });
+
+  test('GET /auth/login/mock redirects to provider auth URL', async function(assert) {
+    const response = await fetch(`${endpoint}/auth/login/mock`, { redirect: 'manual' });
+
+    assert.equal(response.status, 302);
+
+    const location = response.headers.get('location');
+    assert.ok(location.startsWith('https://mock.provider/oauth/authorize?'));
+    assert.ok(location.includes('client_id=test-client-id'));
+    assert.ok(location.includes('response_type=code'));
+  });
+
+  test('GET /auth/login/nonexistent returns 404', async function(assert) {
+    const response = await fetch(`${endpoint}/auth/login/nonexistent`, { redirect: 'manual' });
+
+    assert.equal(response.status, 404);
+  });
+
+  test('GET /auth/callback/mock exchanges code and returns session', async function(assert) {
+    const response = await fetch(`${endpoint}/auth/callback/mock?code=test-auth-code&state=abc`);
+    const data = await response.json();
+
+    assert.equal(response.status, 200);
+    assert.ok(data.sessionId);
+    assert.ok(data.user);
+    assert.equal(data.user.id, 'mock-user-123');
+    assert.equal(data.user.username, 'mockuser');
+  });
+
+  test('GET /auth with valid session returns user', async function(assert) {
+    // Create a session first
+    const callbackResponse = await fetch(`${endpoint}/auth/callback/mock?code=test-code&state=abc`);
+    const { sessionId } = await callbackResponse.json();
+
+    const response = await fetch(`${endpoint}/auth`, {
+      headers: { 'session-id': sessionId },
+    });
+    const data = await response.json();
+
+    assert.equal(response.status, 200);
+    assert.equal(data.id, 'mock-user-123');
+  });
+
+  test('GET /auth without session returns 401', async function(assert) {
+    const response = await fetch(`${endpoint}/auth`);
+
+    assert.equal(response.status, 401);
+  });
+
+  test('GET /auth with invalid session returns 401', async function(assert) {
+    const response = await fetch(`${endpoint}/auth`, {
+      headers: { 'session-id': 'invalid-session' },
+    });
+
+    assert.equal(response.status, 401);
+  });
+
+  test('GET /auth/logout invalidates session', async function(assert) {
+    // Create a session
+    const callbackResponse = await fetch(`${endpoint}/auth/callback/mock?code=test-code&state=abc`);
+    const { sessionId } = await callbackResponse.json();
+
+    // Logout
+    const logoutResponse = await fetch(`${endpoint}/auth/logout`, {
+      headers: { 'session-id': sessionId },
+    });
+    assert.equal(logoutResponse.status, 200);
+
+    // Verify session is invalid
+    const authResponse = await fetch(`${endpoint}/auth`, {
+      headers: { 'session-id': sessionId },
+    });
+    assert.equal(authResponse.status, 401);
+  });
+});

package/test/sample/providers/mock.js

@@ -0,0 +1,40 @@
+import OAuthFlow from '../../../src/oauth-flow.js';
+
+export default class MockProvider extends OAuthFlow {
+  constructor(config) {
+    super({
+      ...config,
+      authorizationUrl: 'https://mock.provider/oauth/authorize',
+      tokenUrl: 'https://mock.provider/oauth/token',
+      userInfoUrl: 'https://mock.provider/api/me',
+    });
+  }
+
+  async exchangeCode(_code) {
+    return {
+      accessToken: 'mock-access-token',
+      refreshToken: 'mock-refresh-token',
+      expiresIn: 3600,
+    };
+  }
+
+  async fetchUserInfo(_accessToken) {
+    return {
+      id: 'mock-user-123',
+      username: 'mockuser',
+      displayName: 'Mock User',
+      email: 'mock@test.com',
+    };
+  }
+
+  normalizeUser(rawUser) {
+    return {
+      id: rawUser.id,
+      username: rawUser.username,
+      displayName: rawUser.displayName,
+      avatar: null,
+      email: rawUser.email,
+      raw: rawUser,
+    };
+  }
+}

package/test/unit/oauth-flow-test.js

@@ -0,0 +1,137 @@
+import QUnit from 'qunit';
+import OAuthFlow from '../../src/oauth-flow.js';
+
+const { module, test } = QUnit;
+
+const defaultConfig = {
+  clientId: 'test-client',
+  clientSecret: 'test-secret',
+  redirectUri: 'http://localhost/callback',
+  scopes: ['read', 'write'],
+  authorizationUrl: 'https://provider.com/oauth/authorize',
+  tokenUrl: 'https://provider.com/oauth/token',
+  userInfoUrl: 'https://provider.com/api/me',
+};
+
+module('[Unit] OAuthFlow', function() {
+  module('buildAuthorizationUrl', function() {
+    test('generates a valid authorization URL with all params', function(assert) {
+      const flow = new OAuthFlow(defaultConfig);
+      const url = flow.buildAuthorizationUrl('test-state-123');
+
+      assert.ok(url.startsWith('https://provider.com/oauth/authorize?'));
+      assert.ok(url.includes('client_id=test-client'));
+      assert.ok(url.includes('redirect_uri='));
+      assert.ok(url.includes('response_type=code'));
+      assert.ok(url.includes('scope=read+write'));
+      assert.ok(url.includes('state=test-state-123'));
+    });
+
+    test('handles empty scopes', function(assert) {
+      const flow = new OAuthFlow({ ...defaultConfig, scopes: [] });
+      const url = flow.buildAuthorizationUrl('state');
+
+      assert.ok(url.includes('scope='));
+    });
+  });
+
+  module('exchangeCode', function() {
+    test('makes a POST request to the token URL', async function(assert) {
+      const flow = new OAuthFlow(defaultConfig);
+      const originalFetch = globalThis.fetch;
+
+      globalThis.fetch = async (url, options) => {
+        assert.equal(url, 'https://provider.com/oauth/token');
+        assert.equal(options.method, 'POST');
+        assert.equal(options.headers['Content-Type'], 'application/json');
+
+        const body = JSON.parse(options.body);
+        assert.equal(body.grant_type, 'authorization_code');
+        assert.equal(body.code, 'test-code');
+        assert.equal(body.client_id, 'test-client');
+
+        return {
+          ok: true,
+          json: async () => ({ access_token: 'abc', refresh_token: 'def', expires_in: 3600 }),
+        };
+      };
+
+      const result = await flow.exchangeCode('test-code');
+
+      assert.equal(result.accessToken, 'abc');
+      assert.equal(result.refreshToken, 'def');
+      assert.equal(result.expiresIn, 3600);
+
+      globalThis.fetch = originalFetch;
+    });
+
+    test('throws on failed token exchange', async function(assert) {
+      const flow = new OAuthFlow(defaultConfig);
+      const originalFetch = globalThis.fetch;
+
+      globalThis.fetch = async () => ({ ok: false, status: 400 });
+
+      await assert.rejects(flow.exchangeCode('bad-code'), /Token exchange failed: 400/);
+
+      globalThis.fetch = originalFetch;
+    });
+  });
+
+  module('refreshAccessToken', function() {
+    test('makes a refresh grant request', async function(assert) {
+      const flow = new OAuthFlow(defaultConfig);
+      const originalFetch = globalThis.fetch;
+
+      globalThis.fetch = async (_url, options) => {
+        const body = JSON.parse(options.body);
+        assert.equal(body.grant_type, 'refresh_token');
+        assert.equal(body.refresh_token, 'old-refresh');
+
+        return {
+          ok: true,
+          json: async () => ({ access_token: 'new-access', expires_in: 7200 }),
+        };
+      };
+
+      const result = await flow.refreshAccessToken('old-refresh');
+
+      assert.equal(result.accessToken, 'new-access');
+      assert.equal(result.refreshToken, 'old-refresh', 'falls back to original refresh token');
+      assert.equal(result.expiresIn, 7200);
+
+      globalThis.fetch = originalFetch;
+    });
+  });
+
+  module('fetchUserInfo', function() {
+    test('sends a Bearer token in the Authorization header', async function(assert) {
+      const flow = new OAuthFlow(defaultConfig);
+      const originalFetch = globalThis.fetch;
+
+      globalThis.fetch = async (url, options) => {
+        assert.equal(url, 'https://provider.com/api/me');
+        assert.equal(options.headers.Authorization, 'Bearer my-token');
+
+        return {
+          ok: true,
+          json: async () => ({ id: '1', name: 'Test' }),
+        };
+      };
+
+      const result = await flow.fetchUserInfo('my-token');
+      assert.deepEqual(result, { id: '1', name: 'Test' });
+
+      globalThis.fetch = originalFetch;
+    });
+  });
+
+  module('normalizeUser', function() {
+    test('returns raw user by default', function(assert) {
+      const flow = new OAuthFlow(defaultConfig);
+      const raw = { id: '1', name: 'Test' };
+      const result = flow.normalizeUser(raw);
+
+      assert.deepEqual(result, { raw });
+    });
+  });
+});

package/test/unit/providers/discord-test.js

@@ -0,0 +1,115 @@
+import QUnit from 'qunit';
+import DiscordProvider from '../../../src/providers/discord.js';
+
+const { module, test } = QUnit;
+
+const defaultConfig = {
+  clientId: 'discord-client-id',
+  clientSecret: 'discord-client-secret',
+  redirectUri: 'http://localhost/auth/callback/discord',
+  scopes: ['identify', 'email'],
+};
+
+module('[Unit] DiscordProvider', function() {
+  module('constructor', function() {
+    test('sets correct Discord OAuth2 URLs', function(assert) {
+      const provider = new DiscordProvider(defaultConfig);
+
+      assert.equal(provider.authorizationUrl, 'https://discord.com/oauth2/authorize');
+      assert.equal(provider.tokenUrl, 'https://discord.com/api/oauth2/token');
+      assert.equal(provider.userInfoUrl, 'https://discord.com/api/users/@me');
+    });
+
+    test('preserves client config', function(assert) {
+      const provider = new DiscordProvider(defaultConfig);
+
+      assert.equal(provider.clientId, 'discord-client-id');
+      assert.equal(provider.clientSecret, 'discord-client-secret');
+      assert.deepEqual(provider.scopes, ['identify', 'email']);
+    });
+  });
+
+  module('exchangeCode', function() {
+    test('uses form-encoded body for Discord token exchange', async function(assert) {
+      const provider = new DiscordProvider(defaultConfig);
+      const originalFetch = globalThis.fetch;
+
+      globalThis.fetch = async (url, options) => {
+        assert.equal(url, 'https://discord.com/api/oauth2/token');
+        assert.equal(options.headers['Content-Type'], 'application/x-www-form-urlencoded');
+        assert.ok(options.body instanceof URLSearchParams);
+
+        const params = Object.fromEntries(options.body);
+        assert.equal(params.grant_type, 'authorization_code');
+        assert.equal(params.code, 'discord-auth-code');
+        assert.equal(params.client_id, 'discord-client-id');
+
+        return {
+          ok: true,
+          json: async () => ({ access_token: 'discord-token', refresh_token: 'refresh', expires_in: 604800 }),
+        };
+      };
+
+      const result = await provider.exchangeCode('discord-auth-code');
+
+      assert.equal(result.accessToken, 'discord-token');
+      assert.equal(result.refreshToken, 'refresh');
+      assert.equal(result.expiresIn, 604800);
+
+      globalThis.fetch = originalFetch;
+    });
+  });
+
+  module('normalizeUser', function() {
+    test('maps Discord user fields correctly', function(assert) {
+      const provider = new DiscordProvider(defaultConfig);
+
+      const discordUser = {
+        id: '123456789',
+        username: 'testuser',
+        global_name: 'Test User',
+        avatar: 'abc123',
+        email: 'test@example.com',
+      };
+
+      const result = provider.normalizeUser(discordUser);
+
+      assert.equal(result.id, '123456789');
+      assert.equal(result.username, 'testuser');
+      assert.equal(result.displayName, 'Test User');
+      assert.equal(result.avatar, 'https://cdn.discordapp.com/avatars/123456789/abc123.png');
+      assert.equal(result.email, 'test@example.com');
+      assert.deepEqual(result.raw, discordUser);
+    });
+
+    test('handles missing avatar', function(assert) {
+      const provider = new DiscordProvider(defaultConfig);
+
+      const result = provider.normalizeUser({
+        id: '1', username: 'user', global_name: 'User', avatar: null, email: null,
+      });
+
+      assert.equal(result.avatar, null);
+    });
+
+    test('falls back to username when global_name is missing', function(assert) {
+      const provider = new DiscordProvider(defaultConfig);
+
+      const result = provider.normalizeUser({
+        id: '1', username: 'myuser', avatar: null, email: null,
+      });
+
+      assert.equal(result.displayName, 'myuser');
+    });
+
+    test('handles missing email', function(assert) {
+      const provider = new DiscordProvider(defaultConfig);
+
+      const result = provider.normalizeUser({
+        id: '1', username: 'user', global_name: 'User', avatar: null,
+      });
+
+      assert.equal(result.email, null);
+    });
+  });
+});

package/test/unit/session-manager-test.js

@@ -0,0 +1,85 @@
+import QUnit from 'qunit';
+import SessionManager from '../../src/session-manager.js';
+
+const { module, test } = QUnit;
+
+const mockUser = { id: '1', username: 'testuser' };
+const mockTokens = { accessToken: 'abc', expiresAt: Date.now() + 60000 };
+
+module('[Unit] SessionManager', function() {
+  module('create', function() {
+    test('generates a unique session ID and stores session', function(assert) {
+      const manager = new SessionManager(3600);
+      const session1 = manager.create(mockUser, mockTokens);
+      const session2 = manager.create(mockUser, mockTokens);
+
+      assert.ok(session1.sessionId);
+      assert.ok(session2.sessionId);
+      assert.notEqual(session1.sessionId, session2.sessionId);
+      assert.deepEqual(session1.user, mockUser);
+    });
+
+    test('sets expiresAt based on duration', function(assert) {
+      const manager = new SessionManager(3600);
+      const before = Date.now();
+      const session = manager.create(mockUser, mockTokens);
+
+      assert.ok(session.expiresAt >= before + 3600 * 1000);
+    });
+  });
+
+  module('get', function() {
+    test('returns session data for a valid session ID', function(assert) {
+      const manager = new SessionManager(3600);
+      const { sessionId } = manager.create(mockUser, mockTokens);
+      const session = manager.get(sessionId);
+
+      assert.ok(session);
+      assert.deepEqual(session.user, mockUser);
+    });
+
+    test('returns null for unknown session ID', function(assert) {
+      const manager = new SessionManager(3600);
+      const session = manager.get('nonexistent');
+
+      assert.equal(session, null);
+    });
+  });
+
+  module('validate', function() {
+    test('returns user for a valid, non-expired session', function(assert) {
+      const manager = new SessionManager(3600);
+      const { sessionId } = manager.create(mockUser, mockTokens);
+      const user = manager.validate(sessionId);
+
+      assert.deepEqual(user, mockUser);
+    });
+
+    test('returns null for an expired session and cleans it up', function(assert) {
+      const manager = new SessionManager(0);
+      const { sessionId } = manager.create(mockUser, mockTokens);
+      const user = manager.validate(sessionId);
+
+      assert.equal(user, null);
+      assert.equal(manager.get(sessionId), null);
+    });
+
+    test('returns null for nonexistent session', function(assert) {
+      const manager = new SessionManager(3600);
+      const user = manager.validate('missing');
+
+      assert.equal(user, null);
+    });
+  });
+
+  module('destroy', function() {
+    test('removes the session', function(assert) {
+      const manager = new SessionManager(3600);
+      const { sessionId } = manager.create(mockUser, mockTokens);
+
+      manager.destroy(sessionId);
+
+      assert.equal(manager.get(sessionId), null);
+    });
+  });
+});

package/test/unit/token-manager-test.js

@@ -0,0 +1,76 @@
+import QUnit from 'qunit';
+import TokenManager from '../../src/token-manager.js';
+
+const { module, test } = QUnit;
+
+function createMockFlow() {
+  return {
+    exchangeCode: async (code) => ({
+      accessToken: `token-for-${code}`,
+      refreshToken: 'refresh-123',
+      expiresIn: 3600,
+    }),
+    refreshAccessToken: async (refreshToken) => ({
+      accessToken: 'new-access',
+      refreshToken,
+      expiresIn: 7200,
+    }),
+    revokeToken: async () => {},
+  };
+}
+
+module('[Unit] TokenManager', function() {
+  module('getTokens', function() {
+    test('delegates to flow.exchangeCode and sets expiresAt', async function(assert) {
+      const manager = new TokenManager(createMockFlow());
+      const before = Date.now();
+      const result = await manager.getTokens('my-code');
+
+      assert.equal(result.accessToken, 'token-for-my-code');
+      assert.equal(result.refreshToken, 'refresh-123');
+      assert.ok(result.expiresAt >= before + 3600 * 1000);
+    });
+  });
+
+  module('refresh', function() {
+    test('delegates to flow.refreshAccessToken and sets expiresAt', async function(assert) {
+      const manager = new TokenManager(createMockFlow());
+      const result = await manager.refresh('refresh-123');
+
+      assert.equal(result.accessToken, 'new-access');
+      assert.ok(result.expiresAt > Date.now());
+    });
+  });
+
+  module('revoke', function() {
+    test('delegates to flow.revokeToken', async function(assert) {
+      let revoked = false;
+      const flow = { ...createMockFlow(), revokeToken: async () => { revoked = true; } };
+      const manager = new TokenManager(flow);
+
+      await manager.revoke('some-token');
+      assert.ok(revoked);
+    });
+  });
+
+  module('isExpired', function() {
+    test('returns true if expiresAt is in the past', function(assert) {
+      const manager = new TokenManager(createMockFlow());
+
+      assert.true(manager.isExpired({ expiresAt: Date.now() - 1000 }));
+    });
+
+    test('returns false if expiresAt is in the future', function(assert) {
+      const manager = new TokenManager(createMockFlow());
+
+      assert.false(manager.isExpired({ expiresAt: Date.now() + 60000 }));
+    });
+
+    test('returns true if tokenData is null or missing expiresAt', function(assert) {
+      const manager = new TokenManager(createMockFlow());
+
+      assert.true(manager.isExpired(null));
+      assert.true(manager.isExpired({}));
+    });
+  });
+});