@stonyx/oauth 0.1.1-alpha.2 → 0.1.1-alpha.21

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/state-store.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Server-side record for an OAuth flow that is in progress.
+ *
+ * Deliberately holds a *digest* of the binding value rather than the value
+ * itself: a callback is only accepted when the caller presents the plaintext
+ * that hashes to `bindingHash`, so the record on its own unlocks nothing.
+ */
+export interface PendingState {
+    provider: string;
+    bindingHash: string;
+    createdAt: number;
+}
+/**
+ * The five reasons a callback is rejected, as fixed strings.
+ *
+ * Named rather than inlined so that collapsing two of them into one is a
+ * visible edit: distinguishing them in the server log is the whole point of
+ * logging a reason, and an operator telling an expired state from a
+ * cross-provider replay depends on them staying distinct.
+ */
+export declare const STATE_REJECTION: {
+    readonly unknownState: "Invalid or missing state token";
+    readonly expired: "State token has expired";
+    readonly wrongProvider: "State token was not issued for this provider";
+    readonly missingBinding: "Missing state binding value";
+    readonly unboundClient: "State token is not bound to this client";
+};
+/**
+ * A callback rejected by `StateStore.consume`.
+ *
+ * Carries two things the route layer cannot otherwise recover: that the
+ * rejection came from state validation rather than from anything downstream of
+ * it, and whether a pending record was actually consumed.
+ */
+export declare class StateRejection extends Error {
+    /** True when this attempt recognised a pending record and burned it. */
+    consumed: boolean;
+    constructor(reason: string, consumed: boolean);
+}
+export interface IssuedState {
+    /** Sent to the provider as the OAuth2 `state` parameter. */
+    stateToken: string;
+    /** Held by the client that started the flow (a cookie), never by the provider. */
+    bindingValue: string;
+}
+/**
+ * Issues and validates OAuth2 `state` tokens bound to the client that started
+ * the flow (#36).
+ *
+ * Presence-plus-age on a process-global map is replay-window limiting, not the
+ * CSRF binding `state` exists to provide (RFC 6749 section 10.12): any state
+ * issued to any visitor validated for any callback, so an attacker could
+ * harvest their own state and code and deliver them to a victim, logging the
+ * victim in as the attacker. A state is now only accepted when the caller also
+ * presents the matching client-held binding value, and only at the provider it
+ * was issued for.
+ */
+export default class StateStore {
+    pending: Map<string, PendingState>;
+    ttl: number;
+    constructor(ttl?: number);
+    static hash(value: string): string;
+    /** Length-independent, content-constant-time comparison of two digests. */
+    static digestsMatch(a: string, b: string): boolean;
+    issue(provider: string): IssuedState;
+    /**
+     * Validates and consumes a pending state. Throws on every rejection path.
+     *
+     * The record is removed as soon as the state is recognised — before the TTL,
+     * provider and binding checks — so every state gets exactly one attempt
+     * whatever the outcome.
+     *
+     * That uniformity is the justification, not brute-force resistance:
+     * guessing `BINDING_VALUE_BYTES` of CSPRNG output is infeasible whether or
+     * not the record survives. What retaining it would buy an attacker is a
+     * repeatable, unauthenticated oracle on this endpoint for the state's full
+     * lifetime — and the safety of that would then rest entirely on an entropy
+     * constant a future change can lower. One attempt per state is a structural
+     * property; entropy arithmetic is not.
+     *
+     * The trade is real: an attacker who already knows a victim's state can burn
+     * it, and the victim must restart at `/auth/login/:provider`. That vector is
+     * accepted deliberately — it requires the victim's `randomUUID` state, and
+     * it is self-healing on retry. `consumed` on the rejection says whether this
+     * call actually burned a record, so a caller can distinguish "nothing of the
+     * victim's was touched" from "one attempt was spent".
+     *
+     * `bindingValues` is every value the client presented under the binding
+     * cookie's name, not just the first — see `anyCandidateMatches`.
+     */
+    consume(stateToken: string | undefined, provider: string, bindingValues: readonly string[]): void;
+    /**
+     * Whether *any* presented value is the binding value for this record.
+     *
+     * Every candidate is tried, and the callback is accepted if one matches.
+     * Returning on the first value carrying the cookie name instead made a
+     * planted cookie a permanent, unauthenticated denial of login: RFC 6265
+     * section 5.4 orders the `Cookie` header by path length then creation time,
+     * so an attacker with content control on a sibling subdomain sets a
+     * same-named cookie once and every subsequent callback for that victim reads
+     * theirs, fails the binding check, and burns the state on the way out. The
+     * victim cannot recover by retrying.
+     *
+     * Accepting any match gives an attacker nothing: they would have to present
+     * the victim's own binding value, which is the property being checked. The
+     * record is consumed on recognition, so a state still gets exactly one
+     * attempt however many candidates were presented, and the candidate count is
+     * bounded by Node's header size limit rather than by a cap here — a cap
+     * truncates the list from the wrong end and reinstates the denial this method
+     * exists to close. See `constants.ts`.
+     *
+     * The loop does not short-circuit, so the work is a function of how many
+     * values were presented and not of which one matched.
+     */
+    anyCandidateMatches(candidates: readonly string[], record: PendingState): boolean;
+}

package/dist/state-store.js

@@ -0,0 +1,144 @@
+import { createHash, randomBytes, randomUUID } from 'node:crypto';
+import { BINDING_VALUE_BYTES, STATE_TTL_MS } from './constants.js';
+/**
+ * The five reasons a callback is rejected, as fixed strings.
+ *
+ * Named rather than inlined so that collapsing two of them into one is a
+ * visible edit: distinguishing them in the server log is the whole point of
+ * logging a reason, and an operator telling an expired state from a
+ * cross-provider replay depends on them staying distinct.
+ */
+export const STATE_REJECTION = {
+    unknownState: 'Invalid or missing state token',
+    expired: 'State token has expired',
+    wrongProvider: 'State token was not issued for this provider',
+    missingBinding: 'Missing state binding value',
+    unboundClient: 'State token is not bound to this client',
+};
+/**
+ * A callback rejected by `StateStore.consume`.
+ *
+ * Carries two things the route layer cannot otherwise recover: that the
+ * rejection came from state validation rather than from anything downstream of
+ * it, and whether a pending record was actually consumed.
+ */
+export class StateRejection extends Error {
+    /** True when this attempt recognised a pending record and burned it. */
+    consumed;
+    constructor(reason, consumed) {
+        super(reason);
+        this.name = 'StateRejection';
+        this.consumed = consumed;
+    }
+}
+/**
+ * Issues and validates OAuth2 `state` tokens bound to the client that started
+ * the flow (#36).
+ *
+ * Presence-plus-age on a process-global map is replay-window limiting, not the
+ * CSRF binding `state` exists to provide (RFC 6749 section 10.12): any state
+ * issued to any visitor validated for any callback, so an attacker could
+ * harvest their own state and code and deliver them to a victim, logging the
+ * victim in as the attacker. A state is now only accepted when the caller also
+ * presents the matching client-held binding value, and only at the provider it
+ * was issued for.
+ */
+export default class StateStore {
+    pending = new Map();
+    ttl;
+    constructor(ttl = STATE_TTL_MS) {
+        this.ttl = ttl;
+    }
+    static hash(value) {
+        return createHash('sha256').update(value).digest('hex');
+    }
+    /** Length-independent, content-constant-time comparison of two digests. */
+    static digestsMatch(a, b) {
+        if (a.length !== b.length)
+            return false;
+        let difference = 0;
+        for (let index = 0; index < a.length; index++) {
+            difference |= a.charCodeAt(index) ^ b.charCodeAt(index);
+        }
+        return difference === 0;
+    }
+    issue(provider) {
+        const stateToken = randomUUID();
+        const bindingValue = randomBytes(BINDING_VALUE_BYTES).toString('base64url');
+        this.pending.set(stateToken, {
+            provider,
+            bindingHash: StateStore.hash(bindingValue),
+            createdAt: Date.now(),
+        });
+        return { stateToken, bindingValue };
+    }
+    /**
+     * Validates and consumes a pending state. Throws on every rejection path.
+     *
+     * The record is removed as soon as the state is recognised — before the TTL,
+     * provider and binding checks — so every state gets exactly one attempt
+     * whatever the outcome.
+     *
+     * That uniformity is the justification, not brute-force resistance:
+     * guessing `BINDING_VALUE_BYTES` of CSPRNG output is infeasible whether or
+     * not the record survives. What retaining it would buy an attacker is a
+     * repeatable, unauthenticated oracle on this endpoint for the state's full
+     * lifetime — and the safety of that would then rest entirely on an entropy
+     * constant a future change can lower. One attempt per state is a structural
+     * property; entropy arithmetic is not.
+     *
+     * The trade is real: an attacker who already knows a victim's state can burn
+     * it, and the victim must restart at `/auth/login/:provider`. That vector is
+     * accepted deliberately — it requires the victim's `randomUUID` state, and
+     * it is self-healing on retry. `consumed` on the rejection says whether this
+     * call actually burned a record, so a caller can distinguish "nothing of the
+     * victim's was touched" from "one attempt was spent".
+     *
+     * `bindingValues` is every value the client presented under the binding
+     * cookie's name, not just the first — see `anyCandidateMatches`.
+     */
+    consume(stateToken, provider, bindingValues) {
+        if (!stateToken)
+            throw new StateRejection(STATE_REJECTION.unknownState, false);
+        const record = this.pending.get(stateToken);
+        if (!record)
+            throw new StateRejection(STATE_REJECTION.unknownState, false);
+        this.pending.delete(stateToken);
+        if (Date.now() - record.createdAt > this.ttl)
+            throw new StateRejection(STATE_REJECTION.expired, true);
+        if (record.provider !== provider)
+            throw new StateRejection(STATE_REJECTION.wrongProvider, true);
+        const candidates = bindingValues.filter(value => value.length > 0);
+        if (candidates.length === 0)
+            throw new StateRejection(STATE_REJECTION.missingBinding, true);
+        if (!this.anyCandidateMatches(candidates, record)) {
+            throw new StateRejection(STATE_REJECTION.unboundClient, true);
+        }
+    }
+    /**
+     * Whether *any* presented value is the binding value for this record.
+     *
+     * Every candidate is tried, and the callback is accepted if one matches.
+     * Returning on the first value carrying the cookie name instead made a
+     * planted cookie a permanent, unauthenticated denial of login: RFC 6265
+     * section 5.4 orders the `Cookie` header by path length then creation time,
+     * so an attacker with content control on a sibling subdomain sets a
+     * same-named cookie once and every subsequent callback for that victim reads
+     * theirs, fails the binding check, and burns the state on the way out. The
+     * victim cannot recover by retrying.
+     *
+     * Accepting any match gives an attacker nothing: they would have to present
+     * the victim's own binding value, which is the property being checked. The
+     * record is consumed on recognition, so a state still gets exactly one
+     * attempt however many candidates were presented, and the candidate count is
+     * bounded by Node's header size limit rather than by a cap here — a cap
+     * truncates the list from the wrong end and reinstates the denial this method
+     * exists to close. See `constants.ts`.
+     *
+     * The loop does not short-circuit, so the work is a function of how many
+     * values were presented and not of which one matched.
+     */
+    anyCandidateMatches(candidates, record) {
+        return candidates.reduce((matched, candidate) => StateStore.digestsMatch(StateStore.hash(candidate), record.bindingHash) || matched, false);
+    }
+}

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,40 +4,76 @@
     "stonyx-async",
     "stonyx-module"
   ],
-  "version": "0.1.1-alpha.2",
+  "version": "0.1.1-alpha.21",
   "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",
   "contributors": [
     "Stone Costa <stone.costa@synamicd.com>"
   ],
+  "files": [
+    "dist",
+    "src",
+    "config",
+    "README.md"
+  ],
   "publishConfig": {
     "access": "public",
     "provenance": true
   },
   "dependencies": {
-    "stonyx": "0.2.3-beta.6",
-    "@stonyx/events": "0.1.1-beta.7"
+    "@stonyx/events": "0.1.1-beta.52",
+    "stonyx": "0.2.3-beta.77"
   },
   "peerDependencies": {
     "@stonyx/rest-server": ">=0.2.1-beta.11"
   },
   "devDependencies": {
-    "@stonyx/rest-server": "0.2.1-beta.16",
-    "@stonyx/utils": "0.2.3-beta.5",
+    "@stonyx/rest-server": "0.2.1-beta.83",
+    "@stonyx/utils": "0.2.3-beta.26",
+    "@stonyx/logs": "1.0.1-beta.19",
+    "@types/qunit": "^2.19.13",
+    "@types/sinon": "^21.0.1",
     "qunit": "^2.24.1",
-    "sinon": "^21.0.0"
+    "sinon": "^21.0.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.8.3"
   },
   "scripts": {
-    "test": "stonyx test"
+    "build": "tsc",
+    "build:test": "tsc -p tsconfig.test.json",
+    "test": "pnpm build && NODE_ENV=test node --import tsx/esm --import ./test/setup.ts node_modules/qunit/bin/qunit.js 'test/**/*-test.ts'"
   }
 }