@miiajs/auth 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ruslan Matiushev
+
+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,17 @@
+# @miiajs/auth
+
+Lightweight auth primitives for MiiaJS - `AuthProvider` interface, `AuthGuard` factory, HTTP token extractors, timing-safe equality.
+
+## Installation
+
+```bash
+npm install @miiajs/auth
+```
+
+## Documentation
+
+**[miiajs.com/docs/packages/auth](https://miiajs.com/docs/packages/auth)**
+
+## License
+
+MIT

package/dist/auth.guard.d.ts

@@ -0,0 +1,18 @@
+import type { Constructor, Guard } from '@miiajs/core';
+import type { AuthProvider } from './provider.js';
+/**
+ * Build a guard that authenticates the request using one or more
+ * `AuthProvider` classes. Providers are tried in order - the first one that
+ * resolves without throwing wins, and its result is assigned to `ctx.user`.
+ *
+ * **OR semantics:** if a provider throws an `HttpException`, the guard moves
+ * on to the next provider. Any other error (TypeError, ReferenceError, etc.)
+ * is treated as a programming bug and rethrown immediately so it is not
+ * silently masked by a later provider.
+ *
+ * If every provider throws an `HttpException`, the last error is rethrown.
+ *
+ * For AND semantics, stack guards instead: `@UseGuard(AuthGuard(JwtAuth), Roles('admin'))`.
+ */
+export declare function AuthGuard(first: Constructor<AuthProvider>, ...rest: Constructor<AuthProvider>[]): Guard;
+//# sourceMappingURL=auth.guard.d.ts.map

package/dist/auth.guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.guard.d.ts","sourceRoot":"","sources":["../src/auth.guard.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAe,WAAW,EAAE,KAAK,EAAkB,MAAM,cAAc,CAAA;AACnF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAEjD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,WAAW,CAAC,YAAY,CAAC,EAAE,GAAG,IAAI,EAAE,WAAW,CAAC,YAAY,CAAC,EAAE,GAAG,KAAK,CA8BvG"}

package/dist/auth.guard.js

@@ -0,0 +1,46 @@
+import { GUARD_FACTORY, HttpException, UnauthorizedException, inject } from '@miiajs/core';
+/**
+ * Build a guard that authenticates the request using one or more
+ * `AuthProvider` classes. Providers are tried in order - the first one that
+ * resolves without throwing wins, and its result is assigned to `ctx.user`.
+ *
+ * **OR semantics:** if a provider throws an `HttpException`, the guard moves
+ * on to the next provider. Any other error (TypeError, ReferenceError, etc.)
+ * is treated as a programming bug and rethrown immediately so it is not
+ * silently masked by a later provider.
+ *
+ * If every provider throws an `HttpException`, the last error is rethrown.
+ *
+ * For AND semantics, stack guards instead: `@UseGuard(AuthGuard(JwtAuth), Roles('admin'))`.
+ */
+export function AuthGuard(first, ...rest) {
+    const providerCtors = [first, ...rest];
+    class AuthenticationGuard {
+        // Eagerly resolve providers in the field initializer - this runs during
+        // guard construction, which the framework performs inside an active
+        // container context. `canActivate()` runs later during request handling
+        // and would not have access to the active container.
+        providers = providerCtors.map((P) => inject(P));
+        async canActivate(ctx) {
+            let lastError;
+            for (const provider of this.providers) {
+                try {
+                    ctx.user = await provider.authenticate(ctx);
+                    return true;
+                }
+                catch (error) {
+                    if (error instanceof HttpException) {
+                        lastError = error;
+                        continue;
+                    }
+                    throw error;
+                }
+            }
+            throw lastError ?? new UnauthorizedException('Unauthorized');
+        }
+    }
+    ;
+    AuthenticationGuard[GUARD_FACTORY] = AuthGuard;
+    return AuthenticationGuard;
+}
+//# sourceMappingURL=auth.guard.js.map

package/dist/auth.guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.guard.js","sourceRoot":"","sources":["../src/auth.guard.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AAI1F;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,SAAS,CAAC,KAAgC,EAAE,GAAG,IAAiC;IAC9F,MAAM,aAAa,GAAG,CAAC,KAAK,EAAE,GAAG,IAAI,CAAC,CAAA;IAEtC,MAAM,mBAAmB;QACvB,wEAAwE;QACxE,oEAAoE;QACpE,wEAAwE;QACxE,qDAAqD;QAC7C,SAAS,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAA;QAEvD,KAAK,CAAC,WAAW,CAAC,GAAwC;YACxD,IAAI,SAAoC,CAAA;YACxC,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;gBACtC,IAAI,CAAC;oBACH,GAAG,CAAC,IAAI,GAAG,MAAM,QAAQ,CAAC,YAAY,CAAC,GAAG,CAAC,CAAA;oBAC3C,OAAO,IAAI,CAAA;gBACb,CAAC;gBAAC,OAAO,KAAK,EAAE,CAAC;oBACf,IAAI,KAAK,YAAY,aAAa,EAAE,CAAC;wBACnC,SAAS,GAAG,KAAK,CAAA;wBACjB,SAAQ;oBACV,CAAC;oBACD,MAAM,KAAK,CAAA;gBACb,CAAC;YACH,CAAC;YACD,MAAM,SAAS,IAAI,IAAI,qBAAqB,CAAC,cAAc,CAAC,CAAA;QAC9D,CAAC;KACF;IAED,CAAC;IAAC,mBAA2B,CAAC,aAAa,CAAC,GAAG,SAAS,CAAA;IACxD,OAAO,mBAAmB,CAAA;AAC5B,CAAC"}

package/dist/extractors.d.ts

@@ -0,0 +1,6 @@
+import type { RequestContext } from '@miiajs/core';
+export type TokenExtractor = (ctx: RequestContext) => string | null;
+export declare function fromHeader(header?: string, scheme?: string): TokenExtractor;
+export declare function fromCookie(name: string): TokenExtractor;
+export declare function fromQuery(param: string): TokenExtractor;
+//# sourceMappingURL=extractors.d.ts.map

package/dist/extractors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extractors.d.ts","sourceRoot":"","sources":["../src/extractors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAElD,MAAM,MAAM,cAAc,GAAG,CAAC,GAAG,EAAE,cAAc,KAAK,MAAM,GAAG,IAAI,CAAA;AAEnE,wBAAgB,UAAU,CAAC,MAAM,SAAkB,EAAE,MAAM,SAAW,GAAG,cAAc,CAQtF;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,CAOvD;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,CAEvD"}

package/dist/extractors.js

@@ -0,0 +1,25 @@
+export function fromHeader(header = 'authorization', scheme = 'Bearer') {
+    return (ctx) => {
+        const value = ctx.req.headers.get(header);
+        if (!value)
+            return null;
+        if (!scheme)
+            return value;
+        if (!value.startsWith(scheme + ' '))
+            return null;
+        return value.slice(scheme.length + 1);
+    };
+}
+export function fromCookie(name) {
+    return (ctx) => {
+        const cookie = ctx.req.headers.get('cookie');
+        if (!cookie)
+            return null;
+        const match = cookie.match(new RegExp(`(?:^|;\\s*)${name}=([^;]+)`));
+        return match?.[1] ?? null;
+    };
+}
+export function fromQuery(param) {
+    return (ctx) => ctx.query[param] ?? null;
+}
+//# sourceMappingURL=extractors.js.map

package/dist/extractors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extractors.js","sourceRoot":"","sources":["../src/extractors.ts"],"names":[],"mappings":"AAIA,MAAM,UAAU,UAAU,CAAC,MAAM,GAAG,eAAe,EAAE,MAAM,GAAG,QAAQ;IACpE,OAAO,CAAC,GAAG,EAAE,EAAE;QACb,MAAM,KAAK,GAAG,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;QACzC,IAAI,CAAC,KAAK;YAAE,OAAO,IAAI,CAAA;QACvB,IAAI,CAAC,MAAM;YAAE,OAAO,KAAK,CAAA;QACzB,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,MAAM,GAAG,GAAG,CAAC;YAAE,OAAO,IAAI,CAAA;QAChD,OAAO,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;IACvC,CAAC,CAAA;AACH,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,OAAO,CAAC,GAAG,EAAE,EAAE;QACb,MAAM,MAAM,GAAG,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAA;QAC5C,IAAI,CAAC,MAAM;YAAE,OAAO,IAAI,CAAA;QACxB,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC,cAAc,IAAI,UAAU,CAAC,CAAC,CAAA;QACpE,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,CAAA;IAC3B,CAAC,CAAA;AACH,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,KAAa;IACrC,OAAO,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,IAAI,CAAA;AAC1C,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { AuthGuard } from './auth.guard.js';
+export type { AuthProvider } from './provider.js';
+export { fromHeader, fromCookie, fromQuery } from './extractors.js';
+export type { TokenExtractor } from './extractors.js';
+export { timingSafeEqual } from './timing-safe.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,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAC3C,YAAY,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AACjD,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AACnE,YAAY,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAA"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export { AuthGuard } from './auth.guard.js';
+export { fromHeader, fromCookie, fromQuery } from './extractors.js';
+export { timingSafeEqual } from './timing-safe.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,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAE3C,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAEnE,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAA"}

package/dist/provider.d.ts

@@ -0,0 +1,27 @@
+import type { RequestContext } from '@miiajs/core';
+/**
+ * An authentication provider extracts credentials from a request and returns
+ * the authenticated subject (user, API client, service account, ...) or
+ * throws an `HttpException` on failure.
+ *
+ * Providers are regular `@Injectable()` classes - register them in your
+ * module's `providers` array and pass the class token to `AuthGuard(...)`.
+ *
+ * ```ts
+ * @Injectable()
+ * export class JwtAuth implements AuthProvider {
+ *   private jwt = inject(JwtService)
+ *   private extract = fromHeader()
+ *
+ *   async authenticate(ctx: RequestContext) {
+ *     const token = this.extract(ctx)
+ *     if (!token) throw new UnauthorizedException('Missing token')
+ *     return this.jwt.verify(token)
+ *   }
+ * }
+ * ```
+ */
+export interface AuthProvider {
+    authenticate(ctx: RequestContext): Promise<unknown> | unknown;
+}
+//# 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,cAAc,EAAE,MAAM,cAAc,CAAA;AAElD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,YAAY;IAC3B,YAAY,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAA;CAC9D"}

package/dist/provider.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=provider.js.map

package/dist/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":""}

package/dist/timing-safe.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Constant-time equality check for two strings of the same expected length
+ * (e.g. pre-hashed tokens, HMAC digests, API keys).
+ *
+ * **Not suitable for plaintext password comparison** - use `bcrypt.compare`
+ * or `argon2.verify` instead, which handle salting and proper cost factors.
+ *
+ * Returns `false` immediately (non-constant-time) when lengths differ; callers
+ * should ensure inputs are the same expected length before calling.
+ */
+export declare function timingSafeEqual(a: string, b: string): boolean;
+//# sourceMappingURL=timing-safe.d.ts.map

package/dist/timing-safe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timing-safe.d.ts","sourceRoot":"","sources":["../src/timing-safe.ts"],"names":[],"mappings":"AAIA;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAK7D"}

package/dist/timing-safe.js

@@ -0,0 +1,20 @@
+import { timingSafeEqual as nodeTimingSafeEqual } from 'node:crypto';
+const encoder = new TextEncoder();
+/**
+ * Constant-time equality check for two strings of the same expected length
+ * (e.g. pre-hashed tokens, HMAC digests, API keys).
+ *
+ * **Not suitable for plaintext password comparison** - use `bcrypt.compare`
+ * or `argon2.verify` instead, which handle salting and proper cost factors.
+ *
+ * Returns `false` immediately (non-constant-time) when lengths differ; callers
+ * should ensure inputs are the same expected length before calling.
+ */
+export function timingSafeEqual(a, b) {
+    const bufA = encoder.encode(a);
+    const bufB = encoder.encode(b);
+    if (bufA.length !== bufB.length)
+        return false;
+    return nodeTimingSafeEqual(bufA, bufB);
+}
+//# sourceMappingURL=timing-safe.js.map

package/dist/timing-safe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timing-safe.js","sourceRoot":"","sources":["../src/timing-safe.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,IAAI,mBAAmB,EAAE,MAAM,aAAa,CAAA;AAEpE,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAA;AAEjC;;;;;;;;;GASG;AACH,MAAM,UAAU,eAAe,CAAC,CAAS,EAAE,CAAS;IAClD,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAA;IAC9B,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAA;IAC9B,IAAI,IAAI,CAAC,MAAM,KAAK,IAAI,CAAC,MAAM;QAAE,OAAO,KAAK,CAAA;IAC7C,OAAO,mBAAmB,CAAC,IAAI,EAAE,IAAI,CAAC,CAAA;AACxC,CAAC"}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@miiajs/auth",
+  "version": "0.1.0",
+  "author": "Ruslan Matiushev",
+  "license": "MIT",
+  "description": "Lightweight auth primitives for MiiaJS - AuthProvider interface, AuthGuard factory, HTTP token extractors, timing-safe equality.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/miiajs/miia.git",
+    "directory": "packages/auth"
+  },
+  "homepage": "https://github.com/miiajs/miia/tree/main/packages/auth#readme",
+  "bugs": {
+    "url": "https://github.com/miiajs/miia/issues"
+  },
+  "keywords": [
+    "miiajs",
+    "miia",
+    "auth",
+    "authentication",
+    "authorization",
+    "guard"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22.22.1",
+    "bun": ">=1.3.11",
+    "deno": ">=2.6.1"
+  },
+  "dependencies": {
+    "@miiajs/core": "workspace:*"
+  },
+  "scripts": {
+    "build": "tsc --build",
+    "clean": "tsc --build --clean"
+  }
+}