@jskit-ai/auth-core 0.1.114 → 0.1.115

package/package.descriptor.mjs

@@ -1,7 +1,7 @@
 export default Object.freeze({
   "packageVersion": 1,
   "packageId": "@jskit-ai/auth-core",
-  "version": "0.1.114",
+  "version": "0.1.115",
   "kind": "runtime",
   "dependsOn": [
     "@jskit-ai/value-app-config-shared"
@@ -74,7 +74,7 @@ export default Object.freeze({
   "mutations": {
     "dependencies": {
       "runtime": {
-        "@jskit-ai/kernel": "0.1.116",
+        "@jskit-ai/kernel": "0.1.117",
         "@fastify/cookie": "^11.0.2",
         "@fastify/csrf-protection": "^7.1.0",
         "@fastify/rate-limit": "^10.3.0"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/auth-core",
-  "version": "0.1.114",
+  "version": "0.1.115",
   "type": "module",
   "scripts": {
     "test": "node --test"
@@ -14,6 +14,8 @@
     "./server/authPolicyContextResolverRegistry": "./src/server/authPolicyContextResolverRegistry.js",
     "./server/authServiceDecoratorRegistry": "./src/server/authServiceDecoratorRegistry.js",
     "./server/authActor": "./src/server/authActor.js",
+    "./server/booleanFlag": "./src/server/booleanFlag.js",
+    "./server/devAuth": "./src/server/devAuth.js",
     "./server/unsupportedOperation": "./src/server/unsupportedOperation.js",
     "./server/utils": "./src/server/utils.js",
     "./server/validators": "./src/server/validators.js",
@@ -54,7 +56,7 @@
     "./shared/commands/authSessionReadCommand": "./src/shared/commands/authSessionReadCommand.js"
   },
   "dependencies": {
-    "@jskit-ai/kernel": "0.1.116",
+    "@jskit-ai/kernel": "0.1.117",
     "@fastify/cookie": "^11.0.2",
     "@fastify/csrf-protection": "^7.1.0",
     "@fastify/rate-limit": "^10.3.0",

package/src/server/actions/auth.contributor.js

@@ -14,6 +14,7 @@ import {
   authLoginOtpVerifyCommand,
   authLoginOAuthStartCommand,
   authLoginOAuthCompleteCommand,
+  authDevLoginAsCommand,
   authPasswordResetRequestCommand,
   authPasswordRecoveryCompleteCommand,
   authPasswordResetCommand
@@ -157,6 +158,25 @@ const baseAuthActions = Object.freeze([
       return deps.authService.oauthComplete(input);
     }
   },
+  {
+    id: "auth.dev.loginAs",
+    version: 1,
+    kind: "command",
+    channels: ["api", "internal"],
+    surfacesFrom: "enabled",
+    input: authDevLoginAsCommand.operation.body,
+    idempotency: "none",
+    audit: {
+      actionName: "auth.dev.loginAs"
+    },
+    observability: {},
+    async execute(input, context, deps) {
+      return deps.authService.devLoginAs(
+        requireRequestContext(context, "auth.dev.loginAs"),
+        input
+      );
+    }
+  },
   {
     id: "auth.password.reset.request",
     version: 1,

package/src/server/booleanFlag.js

@@ -0,0 +1,15 @@
+function parseBooleanFlag(value, fallback = false) {
+  const normalized = String(value || "").trim().toLowerCase();
+  if (!normalized) {
+    return fallback;
+  }
+  if (["1", "true", "yes", "on"].includes(normalized)) {
+    return true;
+  }
+  if (["0", "false", "no", "off"].includes(normalized)) {
+    return false;
+  }
+  return fallback;
+}
+
+export { parseBooleanFlag };

package/src/server/devAuth.js

@@ -0,0 +1,127 @@
+import { AppError } from "@jskit-ai/kernel/server/runtime/errors";
+import { timingSafeEqual } from "node:crypto";
+import { parseBooleanFlag } from "./booleanFlag.js";
+
+const DEV_AUTH_SECRET_HEADER = "x-jskit-dev-auth-secret";
+
+function normalizeRequestHostname(request) {
+  const hostHeader = String(request?.headers?.host || "").trim();
+  const firstHost = hostHeader.split(",")[0]?.trim();
+  if (!firstHost) {
+    return "";
+  }
+  try {
+    return new URL(`http://${firstHost}`).hostname.trim().toLowerCase();
+  } catch {
+    return firstHost
+      .replace(/^\[/, "")
+      .replace(/\]$/, "")
+      .split(":")[0]
+      .trim()
+      .toLowerCase();
+  }
+}
+
+function normalizeLoopbackIp(value) {
+  return String(value || "")
+    .trim()
+    .toLowerCase()
+    .replace(/^\[|\]$/gu, "")
+    .replace(/^::ffff:/u, "");
+}
+
+function isLoopbackIp(value) {
+  const normalized = normalizeLoopbackIp(value);
+  return normalized === "::1" || normalized === "127.0.0.1" || normalized.startsWith("127.");
+}
+
+function isLoopbackHostname(value) {
+  const normalized = String(value || "")
+    .trim()
+    .toLowerCase()
+    .replace(/^\[|\]$/gu, "");
+  return normalized === "localhost" ||
+    normalized.endsWith(".localhost") ||
+    normalized === "::1" ||
+    normalized === "127.0.0.1";
+}
+
+function isLocalDevAuthRequest(request) {
+  const remoteAddress = String(
+    request?.socket?.remoteAddress || request?.raw?.socket?.remoteAddress || ""
+  ).trim();
+  return isLoopbackIp(remoteAddress) && isLoopbackHostname(normalizeRequestHostname(request));
+}
+
+function resolveDevAuthPolicy({
+  enabled = false,
+  nodeEnv = "development",
+  secret = ""
+} = {}) {
+  return Object.freeze({
+    enabled: parseBooleanFlag(enabled, false),
+    isProduction: String(nodeEnv || "development").trim().toLowerCase() === "production",
+    secret: String(secret || "").trim()
+  });
+}
+
+function resolveDevAuthPolicyFromEnv(env = {}) {
+  return resolveDevAuthPolicy({
+    enabled: env?.AUTH_DEV_BYPASS_ENABLED,
+    nodeEnv: env?.NODE_ENV,
+    secret: env?.AUTH_DEV_BYPASS_SECRET
+  });
+}
+
+function assertDevAuthPolicy(policy = {}) {
+  if (!policy.enabled) {
+    return;
+  }
+  if (policy.isProduction) {
+    throw new Error("AUTH_DEV_BYPASS_ENABLED must not be enabled in production.");
+  }
+  if (!policy.secret) {
+    throw new Error("AUTH_DEV_BYPASS_SECRET is required when AUTH_DEV_BYPASS_ENABLED=true.");
+  }
+}
+
+function ensureDevAuthRuntimeAvailable(policy = {}, request = null) {
+  if (!policy.enabled || policy.isProduction) {
+    throw new AppError(404, "Not found.");
+  }
+  if (!policy.secret) {
+    throw new AppError(500, "AUTH_DEV_BYPASS_SECRET is required when AUTH_DEV_BYPASS_ENABLED=true.");
+  }
+  if (!isLocalDevAuthRequest(request)) {
+    throw new AppError(403, "Dev auth bootstrap is only available from localhost.");
+  }
+}
+
+function requestHeader(request, name = "") {
+  const headers = request?.headers || request?.raw?.headers || {};
+  const value = headers[String(name || "").toLowerCase()] ?? headers[name];
+  return Array.isArray(value) ? value[0] : String(value || "");
+}
+
+function secretMatches(value = "", expected = "") {
+  const actualBuffer = Buffer.from(String(value || ""));
+  const expectedBuffer = Buffer.from(String(expected || ""));
+  return actualBuffer.length === expectedBuffer.length && timingSafeEqual(actualBuffer, expectedBuffer);
+}
+
+function ensureDevAuthExchangeAvailable(policy = {}, request = null) {
+  ensureDevAuthRuntimeAvailable(policy, request);
+  if (!secretMatches(requestHeader(request, DEV_AUTH_SECRET_HEADER), policy.secret)) {
+    throw new AppError(403, "Dev auth exchange is not authorized.");
+  }
+}
+
+export {
+  assertDevAuthPolicy,
+  DEV_AUTH_SECRET_HEADER,
+  ensureDevAuthExchangeAvailable,
+  ensureDevAuthRuntimeAvailable,
+  isLocalDevAuthRequest,
+  resolveDevAuthPolicy,
+  resolveDevAuthPolicyFromEnv
+};

package/src/server/providers/FastifyAuthPolicyServiceProvider.js

@@ -3,24 +3,11 @@ import { registerRouteVisibilityResolver } from "@jskit-ai/kernel/server/http";
 import {
   resolveComposedAuthPolicyContextResolver
 } from "../authPolicyContextResolverRegistry.js";
+import { parseBooleanFlag } from "../booleanFlag.js";
 import { authPolicyPlugin } from "../lib/plugin.js";
 import { createAuthActionContextContributor } from "../lib/actionContextContributor.js";
 import { createAuthRouteVisibilityResolver } from "../lib/routeVisibilityResolver.js";
 
-function parseBoolean(value, fallback = false) {
-  const raw = String(value || "").trim().toLowerCase();
-  if (!raw) {
-    return fallback;
-  }
-  if (["1", "true", "yes", "on"].includes(raw)) {
-    return true;
-  }
-  if (["0", "false", "no", "off"].includes(raw)) {
-    return false;
-  }
-  return fallback;
-}
-
 function parseList(value) {
   return String(value || "")
     .split(",")
@@ -109,7 +96,7 @@ class FastifyAuthPolicyServiceProvider {
         apiPrefix: String(env.AUTH_API_PREFIX || "/api/").trim() || "/api/",
         unsafeMethods: parseList(env.AUTH_CSRF_UNSAFE_METHODS),
         csrfCookieOpts: {
-          secure: parseBoolean(env.AUTH_CSRF_COOKIE_SECURE, false)
+          secure: parseBooleanFlag(env.AUTH_CSRF_COOKIE_SECURE, false)
         }
       }
     );

package/test/authActions.test.js

@@ -80,6 +80,40 @@ test("auth logout action delegates to selected auth provider and notifies sessio
   ]);
 });
 
+test("shared dev login-as action passes the trusted request to the selected auth provider", async () => {
+  const action = buildAuthActions().find((definition) => definition.id === "auth.dev.loginAs");
+  const request = {
+    headers: {
+      "x-jskit-dev-auth-secret": "secret"
+    }
+  };
+  const input = {
+    email: "ada@example.com"
+  };
+  let received = null;
+
+  const result = await action.execute(input, {
+    requestMeta: {
+      request
+    }
+  }, {
+    authService: {
+      async devLoginAs(receivedRequest, receivedInput) {
+        received = {
+          input: receivedInput,
+          request: receivedRequest
+        };
+        return {
+          ok: true
+        };
+      }
+    }
+  });
+
+  assert.deepEqual(result, { ok: true });
+  assert.deepEqual(received, { input, request });
+});
+
 test("AuthActionsServiceProvider registers shared auth actions against auth.provider", async () => {
   const app = createApplication();
   const logoutCalls = [];
@@ -122,7 +156,7 @@ test("AuthActionsServiceProvider registers shared auth actions against auth.prov
   const definitions = actionExecutor.listDefinitions();
   assert.equal(definitions.some((definition) => definition.id === "auth.login.password"), true);
   assert.equal(definitions.some((definition) => definition.id === "auth.register"), true);
-  assert.equal(definitions.some((definition) => definition.id === "auth.dev.loginAs"), false);
+  assert.equal(definitions.some((definition) => definition.id === "auth.dev.loginAs"), true);
   assert.deepEqual(definitions.find((definition) => definition.id === "auth.session.read")?.surfaces, [
     "home",
     "console"

package/test/devAuth.test.js

@@ -0,0 +1,103 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { parseBooleanFlag } from "../src/server/booleanFlag.js";
+import {
+  DEV_AUTH_SECRET_HEADER,
+  assertDevAuthPolicy,
+  ensureDevAuthExchangeAvailable,
+  ensureDevAuthRuntimeAvailable,
+  isLocalDevAuthRequest,
+  resolveDevAuthPolicy
+} from "../src/server/devAuth.js";
+
+const DEV_AUTH_SECRET = "preview-exchange-secret";
+
+function createRequest({
+  headers = {},
+  host = "localhost:4100",
+  remoteAddress = "127.0.0.1"
+} = {}) {
+  return {
+    headers: {
+      host,
+      ...headers
+    },
+    socket: {
+      remoteAddress
+    }
+  };
+}
+
+function enabledPolicy(overrides = {}) {
+  return resolveDevAuthPolicy({
+    enabled: true,
+    nodeEnv: "development",
+    secret: DEV_AUTH_SECRET,
+    ...overrides
+  });
+}
+
+test("parseBooleanFlag normalizes conventional environment flag values", () => {
+  assert.equal(parseBooleanFlag("YES"), true);
+  assert.equal(parseBooleanFlag("off", true), false);
+  assert.equal(parseBooleanFlag("unknown", true), true);
+  assert.equal(parseBooleanFlag("", false), false);
+});
+
+test("dev auth policy rejects production and missing-secret enablement", () => {
+  assert.throws(
+    () => assertDevAuthPolicy(enabledPolicy({ nodeEnv: "production" })),
+    /must not be enabled in production/
+  );
+  assert.throws(
+    () => assertDevAuthPolicy(enabledPolicy({ secret: "" })),
+    /AUTH_DEV_BYPASS_SECRET is required/
+  );
+  assert.doesNotThrow(() => assertDevAuthPolicy(resolveDevAuthPolicy()));
+});
+
+test("dev auth trusts only a direct loopback connection with a loopback Host", () => {
+  assert.equal(isLocalDevAuthRequest(createRequest()), true);
+  assert.equal(isLocalDevAuthRequest(createRequest({ host: "app.localhost:4100" })), true);
+  assert.equal(isLocalDevAuthRequest(createRequest({ host: "example.com" })), false);
+  assert.equal(isLocalDevAuthRequest(createRequest({ remoteAddress: "203.0.113.7" })), false);
+  assert.equal(isLocalDevAuthRequest(createRequest({
+    headers: {
+      "x-forwarded-for": "127.0.0.1",
+      "x-forwarded-host": "localhost"
+    },
+    host: "localhost:4100",
+    remoteAddress: "203.0.113.7"
+  })), false);
+});
+
+test("dev auth runtime accepts native session checks without the exchange header", () => {
+  assert.doesNotThrow(() => ensureDevAuthRuntimeAvailable(enabledPolicy(), createRequest()));
+});
+
+test("dev auth exchange requires the exact fixed-header secret", () => {
+  assert.doesNotThrow(() => ensureDevAuthExchangeAvailable(
+    enabledPolicy(),
+    createRequest({
+      headers: {
+        [DEV_AUTH_SECRET_HEADER]: DEV_AUTH_SECRET
+      }
+    })
+  ));
+  assert.throws(
+    () => ensureDevAuthExchangeAvailable(enabledPolicy(), createRequest()),
+    /not authorized/
+  );
+  assert.throws(
+    () => ensureDevAuthExchangeAvailable(
+      enabledPolicy(),
+      createRequest({
+        headers: {
+          [DEV_AUTH_SECRET_HEADER]: `${DEV_AUTH_SECRET}-wrong`
+        }
+      })
+    ),
+    /not authorized/
+  );
+});