@wild-framework/auth 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wild Framework contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,28 @@
+# @wild-framework/auth
+
+Authentication guards and authorization policies for [Wild Framework](https://github.com/your-org/wild-framework).
+
+## Install
+
+```bash
+pnpm add @wild-framework/auth
+```
+
+## Usage
+
+```ts
+import { AuthManager, Policy } from "@wild-framework/auth";
+
+auth.setUserResolver(async (req) => verifyToken(req.headers.authorization));
+router.get("/dashboard", auth.authenticate(), action(Dashboard, "index"));
+
+class PostPolicy extends Policy<Post> {
+    update(user: User, post: Post) { return user.id === post.authorId; }
+}
+
+if (!auth.authorize(PostPolicy, "update", post, user)) throw new ForbiddenException();
+```
+
+## License
+
+MIT

package/dist/errors.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Thrown when authentication is required but no valid credentials are provided.
+ */
+export declare class UnauthorizedException extends Error {
+    readonly statusCode = 401;
+    constructor(message?: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAC5C,SAAgB,UAAU,OAAO;gBAErB,OAAO,SAAiB;CAIvC"}

package/dist/errors.js

@@ -0,0 +1,11 @@
+/**
+ * Thrown when authentication is required but no valid credentials are provided.
+ */
+export class UnauthorizedException extends Error {
+    statusCode = 401;
+    constructor(message = "Unauthorized") {
+        super(message);
+        this.name = "UnauthorizedException";
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IAC5B,UAAU,GAAG,GAAG,CAAC;IAEjC,YAAY,OAAO,GAAG,cAAc;QAChC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IACxC,CAAC;CACJ"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { AuthManager } from "./manager.js";
+export type { UserResolver } from "./manager.js";
+export { Policy } from "./manager.js";
+export { AuthProvider } from "./provider.js";
+export { UnauthorizedException } from "./errors.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,YAAY,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,5 @@
+export { AuthManager } from "./manager.js";
+export { Policy } from "./manager.js";
+export { AuthProvider } from "./provider.js";
+export { UnauthorizedException } from "./errors.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAE3C,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC"}

package/dist/manager.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Minimal request interface — compatible with Express but no dependency.
+ */
+interface AuthRequest {
+    headers: Record<string, string | string[] | undefined>;
+    [key: string]: unknown;
+}
+/**
+ * Minimal response interface.
+ */
+interface AuthResponse {
+}
+/**
+ * Express-compatible next function.
+ */
+type NextFunction = (error?: unknown) => void;
+/**
+ * Function that resolves a user from an incoming request.
+ * Return `null` if the request is unauthenticated.
+ */
+export type UserResolver<TUser = unknown> = (req: AuthRequest) => Promise<TUser | null> | TUser | null;
+/**
+ * Base class for authorization policies.
+ *
+ * Subclasses define methods like `view(user, resource)`, `update(user, resource)`
+ * that return `true` if the action is allowed.
+ */
+export declare abstract class Policy<TResource = unknown> {
+}
+/**
+ * Manages authentication and authorization.
+ *
+ * Holds a user resolver (set during boot) and provides middleware
+ * and policy-based authorization.
+ */
+export declare class AuthManager<TUser = unknown> {
+    private resolver;
+    /**
+     * Set the function that resolves a user from a request.
+     * Called during provider boot.
+     */
+    setUserResolver(resolver: UserResolver<TUser>): void;
+    /**
+     * Resolve the current user from a request.
+     * Returns `null` if not authenticated or no resolver is configured.
+     */
+    user(req: AuthRequest): Promise<TUser | null>;
+    /**
+     * Middleware that requires authentication.
+     *
+     * Resolves the user and attaches it to `req`. Throws
+     * `UnauthorizedException` if no user is resolved.
+     *
+     * The resolved user is stored on `(req as any).user`.
+     */
+    authenticate(): (req: AuthRequest, _res: AuthResponse, next: NextFunction) => void;
+    /**
+     * Check if the current user is authorized to perform an action on a resource.
+     *
+     * @param policyClass — a Policy subclass
+     * @param action — the method name to call on the policy
+     * @param resource — the resource being acted upon
+     * @param user — the current user (resolved from request)
+     *
+     * @returns `true` if the policy method returns `true`
+     */
+    authorize<TPolicy extends Policy<TResource>, TResource>(policyClass: new () => TPolicy, action: string & keyof TPolicy, resource: TResource, user: TUser): boolean;
+}
+export {};
+//# sourceMappingURL=manager.d.ts.map

package/dist/manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../src/manager.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,UAAU,WAAW;IACjB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC;IACvD,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CAC1B;AAED;;GAEG;AACH,UAAU,YAAY;CAErB;AAED;;GAEG;AACH,KAAK,YAAY,GAAG,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;AAE9C;;;GAGG;AACH,MAAM,MAAM,YAAY,CAAC,KAAK,GAAG,OAAO,IAAI,CAAC,GAAG,EAAE,WAAW,KAAK,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC,GAAG,KAAK,GAAG,IAAI,CAAC;AAEvG;;;;;GAKG;AACH,8BAAsB,MAAM,CAAC,SAAS,GAAG,OAAO;CAG/C;AAED;;;;;GAKG;AACH,qBAAa,WAAW,CAAC,KAAK,GAAG,OAAO;IACpC,OAAO,CAAC,QAAQ,CAAoC;IAMpD;;;OAGG;IACH,eAAe,CAAC,QAAQ,EAAE,YAAY,CAAC,KAAK,CAAC,GAAG,IAAI;IAQpD;;;OAGG;IACG,IAAI,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC;IASnD;;;;;;;OAOG;IACH,YAAY,IAAI,CAAC,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,YAAY,KAAK,IAAI;IAmBlF;;;;;;;;;OASG;IACH,SAAS,CAAC,OAAO,SAAS,MAAM,CAAC,SAAS,CAAC,EAAE,SAAS,EAClD,WAAW,EAAE,UAAU,OAAO,EAC9B,MAAM,EAAE,MAAM,GAAG,MAAM,OAAO,EAC9B,QAAQ,EAAE,SAAS,EACnB,IAAI,EAAE,KAAK,GACZ,OAAO;CAUb"}

package/dist/manager.js

@@ -0,0 +1,88 @@
+import { UnauthorizedException } from "./errors.js";
+/**
+ * Base class for authorization policies.
+ *
+ * Subclasses define methods like `view(user, resource)`, `update(user, resource)`
+ * that return `true` if the action is allowed.
+ */
+export class Policy {
+}
+/**
+ * Manages authentication and authorization.
+ *
+ * Holds a user resolver (set during boot) and provides middleware
+ * and policy-based authorization.
+ */
+export class AuthManager {
+    resolver = null;
+    // -------------------------------------------------------------------
+    // Configuration
+    // -------------------------------------------------------------------
+    /**
+     * Set the function that resolves a user from a request.
+     * Called during provider boot.
+     */
+    setUserResolver(resolver) {
+        this.resolver = resolver;
+    }
+    // -------------------------------------------------------------------
+    // User resolution
+    // -------------------------------------------------------------------
+    /**
+     * Resolve the current user from a request.
+     * Returns `null` if not authenticated or no resolver is configured.
+     */
+    async user(req) {
+        if (!this.resolver)
+            return null;
+        return this.resolver(req);
+    }
+    // -------------------------------------------------------------------
+    // Middleware
+    // -------------------------------------------------------------------
+    /**
+     * Middleware that requires authentication.
+     *
+     * Resolves the user and attaches it to `req`. Throws
+     * `UnauthorizedException` if no user is resolved.
+     *
+     * The resolved user is stored on `(req as any).user`.
+     */
+    authenticate() {
+        return async (req, _res, next) => {
+            try {
+                const user = await this.user(req);
+                if (!user) {
+                    throw new UnauthorizedException();
+                }
+                req.user = user;
+                next();
+            }
+            catch (error) {
+                next(error);
+            }
+        };
+    }
+    // -------------------------------------------------------------------
+    // Authorization
+    // -------------------------------------------------------------------
+    /**
+     * Check if the current user is authorized to perform an action on a resource.
+     *
+     * @param policyClass — a Policy subclass
+     * @param action — the method name to call on the policy
+     * @param resource — the resource being acted upon
+     * @param user — the current user (resolved from request)
+     *
+     * @returns `true` if the policy method returns `true`
+     */
+    authorize(policyClass, action, resource, user) {
+        const policy = new policyClass();
+        const method = policy[action];
+        if (typeof method !== "function") {
+            throw new Error(`Policy method "${String(action)}" not found on "${policyClass.name}".`);
+        }
+        return method.call(policy, user, resource) === true;
+    }
+}
+//# sourceMappingURL=manager.js.map

package/dist/manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.js","sourceRoot":"","sources":["../src/manager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AA4BpD;;;;;GAKG;AACH,MAAM,OAAgB,MAAM;CAG3B;AAED;;;;;GAKG;AACH,MAAM,OAAO,WAAW;IACZ,QAAQ,GAA+B,IAAI,CAAC;IAEpD,sEAAsE;IACtE,gBAAgB;IAChB,sEAAsE;IAEtE;;;OAGG;IACH,eAAe,CAAC,QAA6B;QACzC,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC7B,CAAC;IAED,sEAAsE;IACtE,kBAAkB;IAClB,sEAAsE;IAEtE;;;OAGG;IACH,KAAK,CAAC,IAAI,CAAC,GAAgB;QACvB,IAAI,CAAC,IAAI,CAAC,QAAQ;YAAE,OAAO,IAAI,CAAC;QAChC,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;IAC9B,CAAC;IAED,sEAAsE;IACtE,aAAa;IACb,sEAAsE;IAEtE;;;;;;;OAOG;IACH,YAAY;QACR,OAAO,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE;YAC7B,IAAI,CAAC;gBACD,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;gBAClC,IAAI,CAAC,IAAI,EAAE,CAAC;oBACR,MAAM,IAAI,qBAAqB,EAAE,CAAC;gBACtC,CAAC;gBACA,GAA+B,CAAC,IAAI,GAAG,IAAI,CAAC;gBAC7C,IAAI,EAAE,CAAC;YACX,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACb,IAAI,CAAC,KAAK,CAAC,CAAC;YAChB,CAAC;QACL,CAAC,CAAC;IACN,CAAC;IAED,sEAAsE;IACtE,gBAAgB;IAChB,sEAAsE;IAEtE;;;;;;;;;OASG;IACH,SAAS,CACL,WAA8B,EAC9B,MAA8B,EAC9B,QAAmB,EACnB,IAAW;QAEX,MAAM,MAAM,GAAG,IAAI,WAAW,EAAE,CAAC;QACjC,MAAM,MAAM,GAAI,MAAkC,CAAC,MAAM,CAAC,CAAC;QAE3D,IAAI,OAAO,MAAM,KAAK,UAAU,EAAE,CAAC;YAC/B,MAAM,IAAI,KAAK,CAAC,kBAAkB,MAAM,CAAC,MAAM,CAAC,mBAAmB,WAAW,CAAC,IAAI,IAAI,CAAC,CAAC;QAC7F,CAAC;QAED,OAAQ,MAAmB,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,EAAE,QAAQ,CAAC,KAAK,IAAI,CAAC;IACtE,CAAC;CACJ"}

package/dist/provider.d.ts

@@ -0,0 +1,11 @@
+import type { Provider, Application } from "@wild-framework/core";
+/**
+ * Registers the auth system with the application.
+ *
+ * Binds `AuthManager` into the container. The user resolver must be
+ * configured by another provider during `boot()`.
+ */
+export declare class AuthProvider implements Provider {
+    register(app: Application): void;
+}
+//# sourceMappingURL=provider.d.ts.map

package/dist/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAIlE;;;;;GAKG;AACH,qBAAa,YAAa,YAAW,QAAQ;IACzC,QAAQ,CAAC,GAAG,EAAE,WAAW,GAAG,IAAI;CAKnC"}

package/dist/provider.js

@@ -0,0 +1,16 @@
+import { Container } from "@wild-framework/container";
+import { AuthManager } from "./manager.js";
+/**
+ * Registers the auth system with the application.
+ *
+ * Binds `AuthManager` into the container. The user resolver must be
+ * configured by another provider during `boot()`.
+ */
+export class AuthProvider {
+    register(app) {
+        const container = app.resolve(Container);
+        const auth = new AuthManager();
+        container.singleton(AuthManager, () => auth);
+    }
+}
+//# sourceMappingURL=provider.js.map

package/dist/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAE3C;;;;;GAKG;AACH,MAAM,OAAO,YAAY;IACrB,QAAQ,CAAC,GAAgB;QACrB,MAAM,SAAS,GAAG,GAAG,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QACzC,MAAM,IAAI,GAAG,IAAI,WAAW,EAAE,CAAC;QAC/B,SAAS,CAAC,SAAS,CAAC,WAAW,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;IACjD,CAAC;CACJ"}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@wild-framework/auth",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "author": "Sphah",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/KhandaSoftware/wild-framework.git"
+  },
+  "description": "Authentication guards and authorization policies for Wild Framework.",
+  "keywords": [
+    "wild",
+    "framework",
+    "auth",
+    "authorization",
+    "policies"
+  ],
+  "dependencies": {
+    "@wild-framework/core": "0.1.0",
+    "@wild-framework/container": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "test": "vitest run"
+  }
+}