@oneunit/auth 2.0.0

package/examples/uwebsockets.ts

@@ -0,0 +1,143 @@
+import { createAuth, uwsAdapter } from "@oneunit/auth";
+import type { UwsHttpRequest, UwsHttpResponse, UwsRequestSnapshot, UserRecord } from "@oneunit/auth";
+
+interface ExampleUwsResponse extends UwsHttpResponse {
+  onAborted(cb: () => void): void;
+  onData(cb: (chunk: ArrayBuffer, isLast: boolean) => void): void;
+}
+
+interface ExampleUwsRequest extends UwsHttpRequest {
+  getParameter?(index: number): string;
+}
+
+interface ExampleUwsApp {
+  post(
+    path: string,
+    handler: (res: ExampleUwsResponse, req: ExampleUwsRequest) => void,
+  ): ExampleUwsApp;
+  get(
+    path: string,
+    handler: (res: ExampleUwsResponse, req: ExampleUwsRequest) => unknown,
+  ): ExampleUwsApp;
+  listen(port: number, cb: (token: unknown) => void): unknown;
+}
+
+// uWebSockets.js is not an npm dependency of this package — the adapter is pure
+// and needs no import, only a server does. Install it from its GitHub package to
+// actually run this example.
+const uWS = {
+  App(): ExampleUwsApp {
+    console.log("Install uWebSockets.js to run this example: npm i uNetworking/uWebSockets.js");
+    console.log("The uwsAdapter is pure and imports nothing; only the server does.");
+    process.exit(0);
+  },
+};
+
+const auth = createAuth({
+  secret: process.env.AUTH_SECRET ?? "change-me-in-production",
+  issuer: "uws-example",
+  rbac: {
+    defaultRole: "user",
+    roles: {
+      user: { permissions: ["me.read"] },
+      admin: { inherits: "user", permissions: ["stats.read"] },
+    },
+  },
+  providers: {
+    google: {
+      clientId: process.env.GOOGLE_CLIENT_ID,
+      clientSecret: process.env.GOOGLE_CLIENT_SECRET,
+      redirectUri: "http://localhost:3000/auth/google/callback",
+    },
+  },
+});
+
+const { authenticate, requirePermission, json } = uwsAdapter(auth);
+
+const port = Number(process.env.PORT ?? 3000);
+
+/**
+ * Stands in for your database lookup. Roles come from the store, never from
+ * the parsed request body, so a caller cannot choose their own grants.
+ */
+async function findUserByEmail(email: string): Promise<UserRecord> {
+  return { id: "user_01", email, name: "Ada", roles: ["user"] };
+}
+
+uWS.App()
+  .post("/auth/login", (res, _req) => {
+    const aborted = { value: false };
+    res.onAborted(() => {
+      aborted.value = true;
+    });
+
+    let buffer = Buffer.alloc(0);
+    res.onData((chunk: ArrayBuffer, isLast: boolean) => {
+      buffer = Buffer.concat([buffer, Buffer.from(chunk)]);
+      if (!isLast) {
+        return;
+      }
+
+      Promise.resolve()
+        .then(async () => {
+          const body = JSON.parse(buffer.toString("utf8") || "{}") as {
+            email?: string;
+          };
+          // Roles come from your store, never from the parsed body. `auth.login()`
+          // signs whatever record it is given and performs no authorization.
+          const user = await findUserByEmail(String(body.email ?? ""));
+          const session = await auth.login(user);
+          if (!aborted.value) {
+            json(res, 200, session);
+          }
+        })
+        .catch((error: { status?: number; code?: string; message: string }) => {
+          if (!aborted.value) {
+            json(res, error.status ?? 400, {
+              error: error.code ?? "AUTH_ERROR",
+              message: error.message,
+            });
+          }
+        });
+    });
+  })
+  .get("/auth/:provider", (res, req) => {
+    const provider = req.getParameter?.(0) ?? "";
+    let aborted = false;
+    res.onAborted(() => {
+      aborted = true;
+    });
+
+    auth.getAuthorizationUrl(provider)
+      .then(({ url }) => {
+        if (aborted) {
+          return;
+        }
+        res.cork?.(() => {
+          res.writeStatus?.("302 Found");
+          res.writeHeader?.("Location", url);
+          res.end?.();
+        });
+      })
+      .catch((error: { status?: number; code?: string; message: string }) => {
+        if (!aborted) {
+          json(res, error.status ?? 400, {
+            error: error.code ?? "AUTH_ERROR",
+            message: error.message,
+          });
+        }
+      });
+  })
+  .get("/me", authenticate()((res, _req, request?: UwsRequestSnapshot) => {
+    json(res, 200, { user: request?.user });
+  }))
+  .get("/stats", authenticate()(requirePermission("stats.read")((res, _req, request?: UwsRequestSnapshot) => {
+    json(res, 200, { ok: true, userId: request?.user?.userId });
+  })))
+  .listen(port, (token: unknown) => {
+    if (token) {
+      console.log(`uWebSockets.js listening on ${port}`);
+    } else {
+      console.error(`Failed to listen on ${port}`);
+    }
+  });

package/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "@oneunit/auth",
+  "version": "2.0.0",
+  "description": "Framework-agnostic authentication: JWT, generic RBAC, password hashing, and social OAuth. Works standalone or with Express, Fastify, Koa, and uWebSockets.js.",
+  "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",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "examples",
+    "LICENSE",
+    "README.md",
+    "ARCHITECTURE.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "tsc -w -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "tsx --test test/*.test.ts",
+    "prepack": "npm run build",
+    "prepublishOnly": "npm run build && npm test",
+    "pack:check": "npm pack --dry-run",
+    "example": "npm run build && tsx examples/",
+    "example:standalone": "npm run build && tsx examples/standalone.ts",
+    "example:oauth": "npm run build && tsx examples/oauth-social.ts"
+  },
+  "keywords": [
+    "auth",
+    "authentication",
+    "jwt",
+    "jsonwebtoken",
+    "oauth",
+    "oauth2",
+    "oidc",
+    "rbac",
+    "permissions",
+    "roles",
+    "google",
+    "github",
+    "express",
+    "fastify",
+    "koa",
+    "uwebsockets",
+    "typescript",
+    "oneunit"
+  ],
+  "author": "mayank",
+  "license": "MIT",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mayank040902/framework.git",
+    "directory": "packages/auth"
+  },
+  "bugs": {
+    "url": "https://github.com/mayank040902/framework/issues"
+  },
+  "homepage": "https://github.com/mayank040902/framework/tree/main/packages/auth#readme",
+  "dependencies": {
+    "jsonwebtoken": "^9.0.2"
+  },
+  "devDependencies": {
+    "@types/jsonwebtoken": "^9.0.7",
+    "@types/node": "^22.10.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2"
+  }
+}

package/src/adapters.ts

@@ -0,0 +1,333 @@
+import { AuthError, ForbiddenError, UnauthorizedError } from "./errors.js";
+import type { Auth } from "./auth.js";
+import type {
+  ExpressNext,
+  ExpressRequestLike,
+  ExpressResponseLike,
+  ExtractTokenOptions,
+  FastifyLike,
+  FastifyReplyLike,
+  FastifyRequestLike,
+  KoaContextLike,
+  UwsHandler,
+  UwsHttpRequest,
+  UwsHttpResponse,
+  UwsRequestSnapshot,
+} from "./types.js";
+
+function sendError(reply: ExpressResponseLike, error: unknown): void {
+  const err = error as AuthError;
+  const status = err.status ?? 401;
+  const body = {
+    error: err.code ?? "AUTH_ERROR",
+    message: err.message,
+  };
+
+  if (typeof reply.status === "function" && typeof reply.send === "function") {
+    const next = reply.status(status);
+    if (next && typeof next.send === "function") {
+      next.send(body);
+    } else {
+      reply.send(body);
+    }
+    return;
+  }
+  if (typeof reply.code === "function") {
+    const coded = reply.code(status);
+    const send = coded.send ?? reply.send;
+    if (typeof send === "function") {
+      send.call(coded, body);
+      return;
+    }
+  }
+  if (typeof reply.status === "function") {
+    reply.status(status);
+    reply.body = body;
+    return;
+  }
+  throw error;
+}
+
+export function expressAdapter(auth: Auth) {
+  return {
+    initialize() {
+      return (req: ExpressRequestLike, _res: ExpressResponseLike, next?: ExpressNext) => {
+        req.auth = auth;
+        next?.();
+      };
+    },
+
+    authenticate(options: ExtractTokenOptions = {}) {
+      return async (req: ExpressRequestLike, res: ExpressResponseLike, next?: ExpressNext) => {
+        try {
+          req.user = await auth.verifyRequest(req, options);
+          req.token = auth.extractToken(req, options);
+          next?.();
+        } catch (error) {
+          if (options.optional && error instanceof UnauthorizedError) {
+            req.user = null;
+            next?.();
+            return;
+          }
+          if (options.passthrough) {
+            next?.(error);
+            return;
+          }
+          sendError(res, error);
+        }
+      };
+    },
+
+    requirePermission(...permissions: string[]) {
+      return (req: ExpressRequestLike, res: ExpressResponseLike, next?: ExpressNext) => {
+        try {
+          if (!req.user) {
+            throw new UnauthorizedError("Authentication required");
+          }
+          auth.authorize(req.user, permissions);
+          next?.();
+        } catch (error) {
+          sendError(res, error);
+        }
+      };
+    },
+
+    requireRole(...roles: string[]) {
+      return (req: ExpressRequestLike, res: ExpressResponseLike, next?: ExpressNext) => {
+        try {
+          if (!req.user) {
+            throw new UnauthorizedError("Authentication required");
+          }
+          if (!auth.hasRole(req.user, roles)) {
+            throw new ForbiddenError("Insufficient role");
+          }
+          next?.();
+        } catch (error) {
+          sendError(res, error);
+        }
+      };
+    },
+  };
+}
+
+export function fastifyAdapter(auth: Auth) {
+  return async function plugin(fastify: FastifyLike, options: ExtractTokenOptions = {}) {
+    fastify.decorate("auth", auth);
+    fastify.decorateRequest("user", null);
+
+    fastify.decorate("authenticate", (opts: ExtractTokenOptions = {}) => async (request: FastifyRequestLike, reply: FastifyReplyLike) => {
+      // Merge once so the error path sees the same options as the verify path;
+      // reading `opts.optional` alone ignored plugin-level configuration.
+      const settings: ExtractTokenOptions = { ...options, ...opts };
+      try {
+        request.user = await auth.verifyRequest(request, settings);
+      } catch (error) {
+        if (settings.optional && error instanceof UnauthorizedError) {
+          request.user = null;
+          return;
+        }
+        const err = error as AuthError;
+        return reply.code(err.status ?? 401).send({
+          error: err.code ?? "AUTH_ERROR",
+          message: err.message,
+        });
+      }
+    });
+
+    fastify.decorate("requirePermission", (...permissions: string[]) => async (request: FastifyRequestLike, reply: FastifyReplyLike) => {
+      if (!request.user) {
+        return reply.code(401).send({ error: "UNAUTHORIZED", message: "Authentication required" });
+      }
+      if (!auth.can(request.user, permissions)) {
+        return reply.code(403).send({ error: "FORBIDDEN", message: "Missing permission" });
+      }
+    });
+
+    fastify.decorate("requireRole", (...roles: string[]) => async (request: FastifyRequestLike, reply: FastifyReplyLike) => {
+      if (!request.user) {
+        return reply.code(401).send({ error: "UNAUTHORIZED", message: "Authentication required" });
+      }
+      if (!auth.hasRole(request.user, roles)) {
+        return reply.code(403).send({ error: "FORBIDDEN", message: "Insufficient role" });
+      }
+    });
+  };
+}
+
+export function koaAdapter(auth: Auth) {
+  return {
+    authenticate(options: ExtractTokenOptions = {}) {
+      return async (ctx: KoaContextLike, next: () => Promise<void>) => {
+        try {
+          ctx.state.user = await auth.verifyRequest(ctx.request, options);
+          ctx.state.token = auth.extractToken(ctx.request, options);
+        } catch (error) {
+          if (options.optional && error instanceof UnauthorizedError) {
+            ctx.state.user = null;
+            await next();
+            return;
+          }
+          const err = error as AuthError;
+          ctx.status = err.status ?? 401;
+          ctx.body = { error: err.code ?? "AUTH_ERROR", message: err.message };
+          return;
+        }
+        // `next()` stays outside the try so downstream handler errors propagate
+        // to Koa's own error handling instead of being reported as auth failures.
+        await next();
+      };
+    },
+
+    requirePermission(...permissions: string[]) {
+      return async (ctx: KoaContextLike, next: () => Promise<void>) => {
+        if (!ctx.state.user) {
+          ctx.status = 401;
+          ctx.body = { error: "UNAUTHORIZED", message: "Authentication required" };
+          return;
+        }
+        if (!auth.can(ctx.state.user, permissions)) {
+          ctx.status = 403;
+          ctx.body = { error: "FORBIDDEN", message: "Missing permission" };
+          return;
+        }
+        await next();
+      };
+    },
+  };
+}
+
+function jsonResponse(res: UwsHttpResponse, status: number, body: unknown): void {
+  if (typeof res.cork === "function") {
+    res.cork(() => {
+      res.writeStatus?.(String(status));
+      res.writeHeader?.("Content-Type", "application/json; charset=utf-8");
+      res.end?.(JSON.stringify(body));
+    });
+    return;
+  }
+
+  if (typeof res.writeStatus === "function") {
+    res.writeStatus(String(status));
+    res.writeHeader?.("Content-Type", "application/json; charset=utf-8");
+    res.end?.(JSON.stringify(body));
+  }
+}
+
+function attachAbort(res: UwsHttpResponse): () => boolean {
+  let aborted = false;
+  if (typeof res.onAborted === "function") {
+    res.onAborted(() => {
+      aborted = true;
+    });
+  }
+  return () => aborted;
+}
+
+export function snapshotUwsRequest(
+  res: UwsHttpResponse,
+  req: UwsHttpRequest,
+  extra: Partial<UwsRequestSnapshot> = {},
+): UwsRequestSnapshot {
+  const headers: Record<string, string> = {};
+  if (typeof req.forEach === "function") {
+    req.forEach((key, value) => {
+      headers[key] = value;
+    });
+  } else {
+    const authorization = req.getHeader?.("authorization");
+    const cookie = req.getHeader?.("cookie");
+    if (authorization) headers.authorization = authorization;
+    if (cookie) headers.cookie = cookie;
+  }
+
+  return {
+    method: req.getMethod?.() ?? extra.method,
+    url: req.getUrl?.() ?? extra.url,
+    query: req.getQuery?.() ?? extra.query,
+    headers,
+    cookies: extra.cookies,
+    res,
+  };
+}
+
+export function uwsAdapter(auth: Auth) {
+  return {
+    snapshot: snapshotUwsRequest,
+
+    authenticate(options: ExtractTokenOptions = {}) {
+      return (handler: UwsHandler): UwsHandler => async (res, req) => {
+        const aborted = attachAbort(res);
+        const request = snapshotUwsRequest(res, req);
+
+        try {
+          request.user = await auth.verifyRequest(request, options);
+          request.token = auth.extractToken(request, options);
+          if (aborted()) {
+            return;
+          }
+          return await handler(res, req, request);
+        } catch (error) {
+          if (options.optional && error instanceof UnauthorizedError) {
+            request.user = null;
+            if (aborted()) {
+              return;
+            }
+            return await handler(res, req, request);
+          }
+          if (aborted()) {
+            return;
+          }
+          const err = error as AuthError;
+          jsonResponse(res, err.status ?? 401, {
+            error: err.code ?? "AUTH_ERROR",
+            message: err.message,
+          });
+        }
+      };
+    },
+
+    requirePermission(...permissions: string[]) {
+      const requested = permissions.flat();
+      return (handler: UwsHandler): UwsHandler => async (res, req, request) => {
+        const snapshot = request ?? snapshotUwsRequest(res, req);
+        if (!snapshot.user) {
+          jsonResponse(res, 401, { error: "UNAUTHORIZED", message: "Authentication required" });
+          return;
+        }
+        if (!auth.can(snapshot.user, requested)) {
+          jsonResponse(res, 403, { error: "FORBIDDEN", message: "Missing permission" });
+          return;
+        }
+        return await handler(res, req, snapshot);
+      };
+    },
+
+    requireRole(...roles: string[]) {
+      const requested = roles.flat();
+      return (handler: UwsHandler): UwsHandler => async (res, req, request) => {
+        const snapshot = request ?? snapshotUwsRequest(res, req);
+        if (!snapshot.user) {
+          jsonResponse(res, 401, { error: "UNAUTHORIZED", message: "Authentication required" });
+          return;
+        }
+        if (!auth.hasRole(snapshot.user, requested)) {
+          jsonResponse(res, 403, { error: "FORBIDDEN", message: "Insufficient role" });
+          return;
+        }
+        return await handler(res, req, snapshot);
+      };
+    },
+
+    json: jsonResponse,
+  };
+}
+
+export function createAdapters(auth: Auth) {
+  return {
+    express: expressAdapter(auth),
+    fastify: fastifyAdapter(auth),
+    koa: koaAdapter(auth),
+    uws: uwsAdapter(auth),
+    uWebSockets: uwsAdapter(auth),
+  };
+}