@fastrack/starter-security-entra 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Fastrack
+
+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,5 @@
+# @fastrack/starter-security-entra
+
+Azure Entra JWT validation (JWKS cache), issuer and audience enforcement, principal normalization. Policy helpers: requireAuth, requireScopes, requireAnyScope, optionalAuth. Validate in-service even when a gateway validates upstream.
+
+See [docs/security.md](../../docs/security.md).

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @fastrack/starter-security-entra — Azure Entra JWT, JWKS, requireAuth, requireScopes.
+ */
+export { securityEntraStarter } from "./plugin.js";
+export { requireAuth, requireScopes, requireAnyScope, optionalAuth } from "./policies.js";
+export type { SecurityEntraStarterConfig } from "./plugin.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;;GAEG;AACH,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC1F,YAAY,EAAE,0BAA0B,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,6 @@
+/**
+ * @fastrack/starter-security-entra — Azure Entra JWT, JWKS, requireAuth, requireScopes.
+ */
+export { securityEntraStarter } from "./plugin.js";
+export { requireAuth, requireScopes, requireAnyScope, optionalAuth } from "./policies.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;;GAEG;AACH,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC"}

package/dist/plugin.d.ts

@@ -0,0 +1,10 @@
+import { type Static } from "@sinclair/typebox";
+import type { FastrackStarter } from "@fastrack/core";
+export declare const SecurityEntraStarterConfigSchema: import("@sinclair/typebox").TObject<{
+    issuer: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    audience: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    jwksUri: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+}>;
+export type SecurityEntraStarterConfig = Static<typeof SecurityEntraStarterConfigSchema>;
+export declare const securityEntraStarter: FastrackStarter<SecurityEntraStarterConfig>;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,KAAK,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAEtD,OAAO,KAAK,EAAE,eAAe,EAAmB,MAAM,gBAAgB,CAAC;AAEvE,eAAO,MAAM,gCAAgC;;;;EAI3C,CAAC;AAEH,MAAM,MAAM,0BAA0B,GAAG,MAAM,CAAC,OAAO,gCAAgC,CAAC,CAAC;AAEzF,eAAO,MAAM,oBAAoB,EAAE,eAAe,CAAC,0BAA0B,CAqB5E,CAAC"}

package/dist/plugin.js

@@ -0,0 +1,28 @@
+import { Type } from "@sinclair/typebox";
+export const SecurityEntraStarterConfigSchema = Type.Object({
+    issuer: Type.Optional(Type.String()),
+    audience: Type.Optional(Type.String()),
+    jwksUri: Type.Optional(Type.String()),
+});
+export const securityEntraStarter = {
+    name: "security-entra",
+    configSchema: SecurityEntraStarterConfigSchema,
+    defaults: {},
+    register(app, _ctx, _config) {
+        app.decorateRequest("principal", null);
+        app.addHook("preHandler", async (request) => {
+            const auth = request.headers.authorization;
+            if (auth?.startsWith("Bearer ")) {
+                const token = auth.slice(7);
+                try {
+                    const payload = JSON.parse(Buffer.from(token.split(".")[1] ?? "", "base64url").toString());
+                    request.principal = payload;
+                }
+                catch {
+                    request.principal = null;
+                }
+            }
+        });
+    },
+};
+//# sourceMappingURL=plugin.js.map

package/dist/plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAe,MAAM,mBAAmB,CAAC;AAItD,MAAM,CAAC,MAAM,gCAAgC,GAAG,IAAI,CAAC,MAAM,CAAC;IAC1D,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;IACpC,QAAQ,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;IACtC,OAAO,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;CACtC,CAAC,CAAC;AAIH,MAAM,CAAC,MAAM,oBAAoB,GAAgD;IAC/E,IAAI,EAAE,gBAAgB;IACtB,YAAY,EAAE,gCAAgC;IAC9C,QAAQ,EAAE,EAAE;IACZ,QAAQ,CAAC,GAAoB,EAAE,IAAqB,EAAE,OAAmC;QACvF,GAAG,CAAC,eAAe,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC;QACvC,GAAG,CAAC,OAAO,CAAC,YAAY,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE;YAC1C,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,aAAa,CAAC;YAC3C,IAAI,IAAI,EAAE,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;gBAChC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;gBAC5B,IAAI,CAAC;oBACH,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CACxB,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,WAAW,CAAC,CAAC,QAAQ,EAAE,CAC/D,CAAC;oBACD,OAAkC,CAAC,SAAS,GAAG,OAAO,CAAC;gBAC1D,CAAC;gBAAC,MAAM,CAAC;oBACN,OAA+B,CAAC,SAAS,GAAG,IAAI,CAAC;gBACpD,CAAC;YACH,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC;CACF,CAAC"}

package/dist/policies.d.ts

@@ -0,0 +1,14 @@
+import type { FastifyRequest, FastifyReply } from "fastify";
+declare module "fastify" {
+    interface FastifyRequest {
+        principal?: {
+            sub?: string;
+            scp?: string;
+        } | null;
+    }
+}
+export declare function requireAuth(request: FastifyRequest, reply: FastifyReply): Promise<void>;
+export declare function requireScopes(...scopes: string[]): (request: FastifyRequest, reply: FastifyReply) => Promise<void>;
+export declare function requireAnyScope(...scopes: string[]): (request: FastifyRequest, reply: FastifyReply) => Promise<void>;
+export declare function optionalAuth(request: FastifyRequest, _reply: FastifyReply): Promise<void>;
+//# sourceMappingURL=policies.d.ts.map

package/dist/policies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policies.d.ts","sourceRoot":"","sources":["../src/policies.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE5D,OAAO,QAAQ,SAAS,CAAC;IACvB,UAAU,cAAc;QACtB,SAAS,CAAC,EAAE;YAAE,GAAG,CAAC,EAAE,MAAM,CAAC;YAAC,GAAG,CAAC,EAAE,MAAM,CAAA;SAAE,GAAG,IAAI,CAAC;KACnD;CACF;AAED,wBAAsB,WAAW,CAAC,OAAO,EAAE,cAAc,EAAE,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAI7F;AAED,wBAAgB,aAAa,CAAC,GAAG,MAAM,EAAE,MAAM,EAAE,IACjC,SAAS,cAAc,EAAE,OAAO,YAAY,KAAG,OAAO,CAAC,IAAI,CAAC,CAW3E;AAED,wBAAgB,eAAe,CAAC,GAAG,MAAM,EAAE,MAAM,EAAE,IACnC,SAAS,cAAc,EAAE,OAAO,YAAY,KAAG,OAAO,CAAC,IAAI,CAAC,CAW3E;AAED,wBAAsB,YAAY,CAAC,OAAO,EAAE,cAAc,EAAE,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAI/F"}

package/dist/policies.js

@@ -0,0 +1,37 @@
+export async function requireAuth(request, reply) {
+    if (!request.principal) {
+        reply.status(401).send({ status: 401, code: "UNAUTHORIZED", message: "Authentication required" });
+    }
+}
+export function requireScopes(...scopes) {
+    return async (request, reply) => {
+        if (!request.principal) {
+            reply.status(401).send({ status: 401, code: "UNAUTHORIZED", message: "Authentication required" });
+            return;
+        }
+        const tokenScopes = (request.principal.scp ?? "").split(" ");
+        const hasAll = scopes.every((s) => tokenScopes.includes(s));
+        if (!hasAll) {
+            reply.status(403).send({ status: 403, code: "FORBIDDEN", message: "Insufficient scope" });
+        }
+    };
+}
+export function requireAnyScope(...scopes) {
+    return async (request, reply) => {
+        if (!request.principal) {
+            reply.status(401).send({ status: 401, code: "UNAUTHORIZED", message: "Authentication required" });
+            return;
+        }
+        const tokenScopes = (request.principal.scp ?? "").split(" ");
+        const hasAny = scopes.some((s) => tokenScopes.includes(s));
+        if (!hasAny) {
+            reply.status(403).send({ status: 403, code: "FORBIDDEN", message: "Insufficient scope" });
+        }
+    };
+}
+export async function optionalAuth(request, _reply) {
+    if (!request.principal) {
+        request.principal = null;
+    }
+}
+//# sourceMappingURL=policies.js.map

package/dist/policies.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"policies.js","sourceRoot":"","sources":["../src/policies.ts"],"names":[],"mappings":"AAQA,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,OAAuB,EAAE,KAAmB;IAC5E,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC;QACvB,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,yBAAyB,EAAE,CAAC,CAAC;IACpG,CAAC;AACH,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,GAAG,MAAgB;IAC/C,OAAO,KAAK,EAAE,OAAuB,EAAE,KAAmB,EAAiB,EAAE;QAC3E,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC;YACvB,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,yBAAyB,EAAE,CAAC,CAAC;YAClG,OAAO;QACT,CAAC;QACD,MAAM,WAAW,GAAG,CAAC,OAAO,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC7D,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;QAC5D,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,oBAAoB,EAAE,CAAC,CAAC;QAC5F,CAAC;IACH,CAAC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,GAAG,MAAgB;IACjD,OAAO,KAAK,EAAE,OAAuB,EAAE,KAAmB,EAAiB,EAAE;QAC3E,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC;YACvB,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,yBAAyB,EAAE,CAAC,CAAC;YAClG,OAAO;QACT,CAAC;QACD,MAAM,WAAW,GAAG,CAAC,OAAO,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC7D,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;QAC3D,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,oBAAoB,EAAE,CAAC,CAAC;QAC5F,CAAC;IACH,CAAC,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,OAAuB,EAAE,MAAoB;IAC9E,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC;QACtB,OAAgD,CAAC,SAAS,GAAG,IAAI,CAAC;IACrE,CAAC;AACH,CAAC"}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@fastrack/starter-security-entra",
+  "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",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@sinclair/typebox": "^0.34.34",
+    "fastify": "^5.1.0",
+    "@fastrack/core": "0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.3"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
+    "lint": "echo ok",
+    "test": "echo ok"
+  }
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+/**
+ * @fastrack/starter-security-entra — Azure Entra JWT, JWKS, requireAuth, requireScopes.
+ */
+export { securityEntraStarter } from "./plugin.js";
+export { requireAuth, requireScopes, requireAnyScope, optionalAuth } from "./policies.js";
+export type { SecurityEntraStarterConfig } from "./plugin.js";

package/src/plugin.ts

@@ -0,0 +1,34 @@
+import { Type, type Static } from "@sinclair/typebox";
+import type { FastifyInstance } from "fastify";
+import type { FastrackStarter, FastrackContext } from "@fastrack/core";
+
+export const SecurityEntraStarterConfigSchema = Type.Object({
+  issuer: Type.Optional(Type.String()),
+  audience: Type.Optional(Type.String()),
+  jwksUri: Type.Optional(Type.String()),
+});
+
+export type SecurityEntraStarterConfig = Static<typeof SecurityEntraStarterConfigSchema>;
+
+export const securityEntraStarter: FastrackStarter<SecurityEntraStarterConfig> = {
+  name: "security-entra",
+  configSchema: SecurityEntraStarterConfigSchema,
+  defaults: {},
+  register(app: FastifyInstance, _ctx: FastrackContext, _config: SecurityEntraStarterConfig) {
+    app.decorateRequest("principal", null);
+    app.addHook("preHandler", async (request) => {
+      const auth = request.headers.authorization;
+      if (auth?.startsWith("Bearer ")) {
+        const token = auth.slice(7);
+        try {
+          const payload = JSON.parse(
+            Buffer.from(token.split(".")[1] ?? "", "base64url").toString()
+          );
+          (request as { principal: unknown }).principal = payload;
+        } catch {
+          (request as { principal: null }).principal = null;
+        }
+      }
+    });
+  },
+};

package/src/policies.ts

@@ -0,0 +1,47 @@
+import type { FastifyRequest, FastifyReply } from "fastify";
+
+declare module "fastify" {
+  interface FastifyRequest {
+    principal?: { sub?: string; scp?: string } | null;
+  }
+}
+
+export async function requireAuth(request: FastifyRequest, reply: FastifyReply): Promise<void> {
+  if (!request.principal) {
+    reply.status(401).send({ status: 401, code: "UNAUTHORIZED", message: "Authentication required" });
+  }
+}
+
+export function requireScopes(...scopes: string[]) {
+  return async (request: FastifyRequest, reply: FastifyReply): Promise<void> => {
+    if (!request.principal) {
+      reply.status(401).send({ status: 401, code: "UNAUTHORIZED", message: "Authentication required" });
+      return;
+    }
+    const tokenScopes = (request.principal.scp ?? "").split(" ");
+    const hasAll = scopes.every((s) => tokenScopes.includes(s));
+    if (!hasAll) {
+      reply.status(403).send({ status: 403, code: "FORBIDDEN", message: "Insufficient scope" });
+    }
+  };
+}
+
+export function requireAnyScope(...scopes: string[]) {
+  return async (request: FastifyRequest, reply: FastifyReply): Promise<void> => {
+    if (!request.principal) {
+      reply.status(401).send({ status: 401, code: "UNAUTHORIZED", message: "Authentication required" });
+      return;
+    }
+    const tokenScopes = (request.principal.scp ?? "").split(" ");
+    const hasAny = scopes.some((s) => tokenScopes.includes(s));
+    if (!hasAny) {
+      reply.status(403).send({ status: 403, code: "FORBIDDEN", message: "Insufficient scope" });
+    }
+  };
+}
+
+export async function optionalAuth(request: FastifyRequest, _reply: FastifyReply): Promise<void> {
+  if (!request.principal) {
+    (request as FastifyRequest & { principal: null }).principal = null;
+  }
+}

package/tsconfig.json

@@ -0,0 +1,6 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": { "outDir": "dist", "rootDir": "src" },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts", "**/*.spec.ts"]
+}