@tensorgrad/oauth 0.1.0

package/README.md

@@ -0,0 +1,154 @@
+# @tensorgrad/oauth
+
+Small OAuth client SDK for integrating tensorGrad SSO into first-party apps.
+
+## What it does
+
+- creates `state` values
+- creates PKCE verifier/challenge pairs
+- builds tensorGrad `/oauth/authorize` URLs
+- exchanges authorization codes at `/oauth/token`
+- fetches canonical identity from `/oauth/userinfo`
+- normalizes tensorGrad user payloads
+- validates granted scopes
+
+## What it does not do
+
+- manage your app sessions or cookies
+- manage roles or permissions inside your app
+- assume a frontend framework
+
+## Runtime
+
+This package targets Web API runtimes such as:
+
+- Cloudflare Workers
+- modern browsers
+- Node runtimes that expose standard Web APIs
+
+## Install
+
+```bash
+npm install @tensorgrad/oauth
+```
+
+## Core constants
+
+```ts
+import { TENSORGRAD_ISSUER } from "@tensorgrad/oauth";
+
+console.log(TENSORGRAD_ISSUER);
+// "https://www.tensorgrad.com"
+```
+
+## Full Cloudflare Worker example
+
+```ts
+import {
+  TENSORGRAD_ISSUER,
+  assertGrantedScopes,
+  createAuthorizationUrl,
+  createPkcePair,
+  createState,
+  exchangeAuthorizationCode,
+  fetchUserInfo,
+  isAdminScopeGranted,
+  normalizeTgUser
+} from "@tensorgrad/oauth";
+
+export interface Env {
+  TENSORGRAD_CLIENT_ID: string;
+  TENSORGRAD_CLIENT_SECRET: string;
+}
+
+function html(body: string, status = 200): Response {
+  return new Response(body, {
+    status,
+    headers: { "Content-Type": "text/html; charset=utf-8" }
+  });
+}
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const url = new URL(request.url);
+
+    if (url.pathname === "/login") {
+      const state = createState();
+      const pkce = await createPkcePair();
+      const redirectUri = `${url.origin}/auth/callback`;
+
+      const authorizeUrl = createAuthorizationUrl(
+        {
+          issuer: TENSORGRAD_ISSUER,
+          clientId: env.TENSORGRAD_CLIENT_ID
+        },
+        {
+          redirectUri,
+          scope: ["openid", "profile", "email"],
+          state,
+          codeChallenge: pkce.codeChallenge,
+          codeChallengeMethod: pkce.codeChallengeMethod
+        }
+      );
+
+      return html(`
+        <p><a href="${authorizeUrl.toString()}">Continue with tensorGrad</a></p>
+        <p>Persist state and codeVerifier in your own storage before redirecting.</p>
+        <pre>${JSON.stringify({ state, codeVerifier: pkce.codeVerifier }, null, 2)}</pre>
+      `);
+    }
+
+    if (url.pathname === "/auth/callback") {
+      const code = url.searchParams.get("code");
+      const state = url.searchParams.get("state");
+
+      if (!code || !state) {
+        return new Response("Missing code or state", { status: 400 });
+      }
+
+      const redirectUri = `${url.origin}/auth/callback`;
+
+      // Replace these with values loaded from your own storage.
+      const expectedState = "<persisted-state>";
+      const codeVerifier = "<persisted-code-verifier>";
+
+      if (state !== expectedState) {
+        return new Response("Invalid state", { status: 400 });
+      }
+
+      const token = await exchangeAuthorizationCode({
+        issuer: TENSORGRAD_ISSUER,
+        clientId: env.TENSORGRAD_CLIENT_ID,
+        clientSecret: env.TENSORGRAD_CLIENT_SECRET,
+        code,
+        redirectUri,
+        codeVerifier
+      });
+
+      assertGrantedScopes(token.scope, ["openid", "profile", "email"]);
+
+      const userFromToken = normalizeTgUser(token.user);
+      const userFromUserInfo = normalizeTgUser(
+        await fetchUserInfo(TENSORGRAD_ISSUER, token.access_token)
+      );
+
+      return Response.json({
+        token,
+        userFromToken,
+        userFromUserInfo,
+        adminGranted: isAdminScopeGranted(token.scope)
+      });
+    }
+
+    return new Response("Not found", { status: 404 });
+  }
+};
+```
+
+## Notes
+
+- `openid` is mandatory and the library enforces that when building authorize URLs.
+- tensorGrad currently uses `https://www.tensorgrad.com` as the OAuth provider.
+- `assertGrantedScopes(token.scope, ["admin"])` is the simplest way to require admin access.
+- `isAdminScopeGranted(token.scope)` is available when you only need a boolean check.
+- app session and logout handling stay in the consuming app.

package/dist/index.d.ts

@@ -0,0 +1,57 @@
+export declare const TENSORGRAD_ISSUER = "https://www.tensorgrad.com";
+export interface tgOAuthConfig {
+    issuer: string;
+    clientId: string;
+    clientSecret?: string;
+}
+export interface PkcePair {
+    codeVerifier: string;
+    codeChallenge: string;
+    codeChallengeMethod: "S256";
+}
+export interface AuthorizationUrlOptions {
+    redirectUri: string;
+    scope: string[] | string;
+    state: string;
+    codeChallenge?: string;
+    codeChallengeMethod?: "S256" | "plain";
+    extraParams?: Record<string, string>;
+}
+export interface TokenExchangeOptions {
+    issuer: string;
+    clientId: string;
+    clientSecret?: string;
+    code: string;
+    redirectUri: string;
+    codeVerifier?: string;
+    fetchImpl?: typeof fetch;
+}
+export interface tgTokenResponse {
+    access_token: string;
+    token_type: string;
+    expires_in: number;
+    scope: string;
+    user: tgUserInfo;
+}
+export interface tgUserInfo {
+    sub: string;
+    email: string;
+    email_verified: boolean;
+    name: string | null;
+    image: string | null;
+}
+export interface normalizedTgUser {
+    id: string;
+    email: string;
+    emailVerified: boolean;
+    name: string | null;
+    image: string | null;
+}
+export declare function createState(length?: number): string;
+export declare function createPkcePair(length?: number): Promise<PkcePair>;
+export declare function createAuthorizationUrl(config: tgOAuthConfig, options: AuthorizationUrlOptions): URL;
+export declare function exchangeAuthorizationCode(options: TokenExchangeOptions): Promise<tgTokenResponse>;
+export declare function fetchUserInfo(issuer: string, accessToken: string, fetchImpl?: typeof fetch): Promise<tgUserInfo>;
+export declare function normalizeTgUser(user: tgUserInfo): normalizedTgUser;
+export declare function assertGrantedScopes(grantedScope: string[] | string, requiredScopes: readonly string[]): void;
+export declare function isAdminScopeGranted(grantedScope: string[] | string): boolean;

package/dist/index.js

@@ -0,0 +1,174 @@
+export const TENSORGRAD_ISSUER = "https://www.tensorgrad.com";
+const MIN_STATE_BYTES = 16;
+const MAX_RANDOM_BYTES = 96;
+const MIN_PKCE_RANDOM_BYTES = 32;
+const RESERVED_AUTHORIZATION_PARAMS = new Set([
+    "client_id",
+    "redirect_uri",
+    "response_type",
+    "scope",
+    "state",
+    "code_challenge",
+    "code_challenge_method"
+]);
+function requireNonEmptyString(name, value) {
+    const trimmed = value.trim();
+    if (!trimmed) {
+        throw new Error(`${name} must be a non-empty string`);
+    }
+    return trimmed;
+}
+function assertRandomByteLength(name, length, min, max = MAX_RANDOM_BYTES) {
+    if (!Number.isInteger(length) || length < min || length > max) {
+        throw new Error(`${name} must be an integer between ${min} and ${max}`);
+    }
+}
+function normalizeIssuer(issuer) {
+    const normalized = requireNonEmptyString("issuer", issuer).replace(/\/+$/, "");
+    const parsed = new URL(normalized);
+    if (!parsed.protocol || !parsed.host) {
+        throw new Error("issuer must be an absolute URL");
+    }
+    return parsed.toString().replace(/\/+$/, "");
+}
+function normalizeAbsoluteUrl(name, value) {
+    const normalized = requireNonEmptyString(name, value);
+    return new URL(normalized).toString();
+}
+function parseScopeSet(scope) {
+    return new Set((Array.isArray(scope) ? scope : scope.split(/\s+/))
+        .map((value) => value.trim())
+        .filter(Boolean));
+}
+function normalizeScopeString(scope) {
+    const values = Array.from(parseScopeSet(scope));
+    if (values.length === 0) {
+        throw new Error("scope must contain at least one value");
+    }
+    if (!values.includes("openid")) {
+        throw new Error("scope must include openid");
+    }
+    return values.join(" ");
+}
+function toBase64Url(bytes) {
+    let binary = "";
+    for (const byte of bytes) {
+        binary += String.fromCharCode(byte);
+    }
+    return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
+}
+async function sha256(input) {
+    const encoded = new TextEncoder().encode(input);
+    const digest = await crypto.subtle.digest("SHA-256", encoded);
+    return new Uint8Array(digest);
+}
+export function createState(length = 32) {
+    assertRandomByteLength("state length", length, MIN_STATE_BYTES);
+    const bytes = crypto.getRandomValues(new Uint8Array(length));
+    return toBase64Url(bytes);
+}
+export async function createPkcePair(length = 32) {
+    assertRandomByteLength("PKCE length", length, MIN_PKCE_RANDOM_BYTES);
+    const verifierBytes = crypto.getRandomValues(new Uint8Array(length));
+    const codeVerifier = toBase64Url(verifierBytes);
+    const codeChallenge = toBase64Url(await sha256(codeVerifier));
+    return {
+        codeVerifier,
+        codeChallenge,
+        codeChallengeMethod: "S256"
+    };
+}
+export function createAuthorizationUrl(config, options) {
+    const redirectUri = normalizeAbsoluteUrl("redirectUri", options.redirectUri);
+    const state = requireNonEmptyString("state", options.state);
+    const scope = normalizeScopeString(options.scope);
+    const clientId = requireNonEmptyString("clientId", config.clientId);
+    const url = new URL("/oauth/authorize", normalizeIssuer(config.issuer));
+    url.searchParams.set("client_id", clientId);
+    url.searchParams.set("redirect_uri", redirectUri);
+    url.searchParams.set("response_type", "code");
+    url.searchParams.set("scope", scope);
+    url.searchParams.set("state", state);
+    if (options.codeChallenge) {
+        url.searchParams.set("code_challenge", requireNonEmptyString("codeChallenge", options.codeChallenge));
+        url.searchParams.set("code_challenge_method", options.codeChallengeMethod ?? "S256");
+    }
+    for (const [key, value] of Object.entries(options.extraParams ?? {})) {
+        if (RESERVED_AUTHORIZATION_PARAMS.has(key)) {
+            throw new Error(`extraParams cannot override reserved OAuth parameter: ${key}`);
+        }
+        url.searchParams.set(key, requireNonEmptyString(`extraParams.${key}`, value));
+    }
+    return url;
+}
+async function readJsonOrThrow(response) {
+    const text = await response.text();
+    let payload;
+    try {
+        payload = text ? JSON.parse(text) : {};
+    }
+    catch {
+        throw new Error(`Unexpected non-JSON response: ${text}`);
+    }
+    if (!response.ok) {
+        const message = typeof payload === "object" &&
+            payload !== null &&
+            ("error_description" in payload || "error" in payload)
+            ? String(payload.error_description ??
+                payload.error)
+            : `HTTP ${response.status}`;
+        throw new Error(message);
+    }
+    return payload;
+}
+export async function exchangeAuthorizationCode(options) {
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const url = new URL("/oauth/token", normalizeIssuer(options.issuer));
+    const body = new URLSearchParams();
+    body.set("grant_type", "authorization_code");
+    body.set("client_id", requireNonEmptyString("clientId", options.clientId));
+    body.set("code", requireNonEmptyString("code", options.code));
+    body.set("redirect_uri", normalizeAbsoluteUrl("redirectUri", options.redirectUri));
+    if (options.clientSecret) {
+        body.set("client_secret", options.clientSecret);
+    }
+    if (options.codeVerifier) {
+        body.set("code_verifier", requireNonEmptyString("codeVerifier", options.codeVerifier));
+    }
+    const response = await fetchImpl(url, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/x-www-form-urlencoded"
+        },
+        body
+    });
+    return readJsonOrThrow(response);
+}
+export async function fetchUserInfo(issuer, accessToken, fetchImpl = fetch) {
+    const url = new URL("/oauth/userinfo", normalizeIssuer(issuer));
+    const response = await fetchImpl(url, {
+        headers: {
+            Authorization: `Bearer ${requireNonEmptyString("accessToken", accessToken)}`
+        }
+    });
+    return readJsonOrThrow(response);
+}
+export function normalizeTgUser(user) {
+    return {
+        id: user.sub,
+        email: user.email,
+        emailVerified: user.email_verified,
+        name: user.name,
+        image: user.image
+    };
+}
+export function assertGrantedScopes(grantedScope, requiredScopes) {
+    const granted = parseScopeSet(grantedScope);
+    const missing = requiredScopes.filter((scope) => !granted.has(scope));
+    if (missing.length > 0) {
+        throw new Error(`Missing granted scopes: ${missing.join(", ")}`);
+    }
+}
+export function isAdminScopeGranted(grantedScope) {
+    return parseScopeSet(grantedScope).has("admin");
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@tensorgrad/oauth",
+  "version": "0.1.0",
+  "description": "Small OAuth client SDK for tensorGrad SSO integrations.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "oauth",
+    "pkce",
+    "tensorgrad",
+    "sso"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "typescript": "^5.9.2"
+  }
+}