@jskit-ai/auth-core 0.2.29 → 0.2.30

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -2,6 +2,7 @@
2
2
 
3
3
  ## Unreleased
4
4
 
5
+ - **Breaking:** dev sign-in, the CSRF cookie's `Secure` and `__Host-` prefix and unknown role grants follow `APP_ENV`, not `NODE_ENV`. `resolveDevAuthPolicy({ enabled, appEnv, secret })` takes the application's `APP_ENV` in place of `nodeEnv` and answers `isDeployed` (staging or production) in place of `isProduction`; a missing or unknown `appEnv` throws. `AUTH_DEV_BYPASS_ENABLED` in staging or production refuses to start with `AUTH_DEV_BYPASS_ENABLED is for development only: remove it from staging and production.` The auth plugin takes `appEnv` in place of `nodeEnv`.
5
6
  - **Breaking:** `./server/passSignIn` is gone. `signPass`, `verifyPass` and `resolvePassSignInFromEnv` moved unchanged to `@jskit-ai/auth-pass/server`, a package that installs no providers, so an application with its own sign-in can check passes without auth-core's runtime. `AUTH_TEXTS` loses the seven `pass*` entries and `locales/en.json` the `auth.pass.*` texts; they are `PASS_TEXTS` and `createPassError` in auth-pass, whose catalog has the same English. Import from `@jskit-ai/auth-pass/server` instead. `AUTH_PATHS.LOGIN_PASS` and the auth service's `signInWithPass({ pass })` stay here.
6
7
  - One-time pass sign-in: `./server/passSignIn` exports `signPass` (for the issuer, which holds an Ed25519 private key), `verifyPass` and `resolvePassSignInFromEnv`. A pass is a compact JWS (`alg` EdDSA, `typ` `pass+jwt`) naming one person (`sub`), one application (`aud`), one resource (`resource`) and its id (`jti`), lasting 60 seconds by default and at most five minutes. `AUTH_PASS_PUBLIC_KEY` (PEM, or base64 DER on one line) turns it on, with `AUTH_PASS_AUDIENCE` and `AUTH_PASS_RESOURCE` required. A refused pass is a 401 coded `auth.pass.malformed`, `auth.pass.badSignature`, `auth.pass.wrongAudience`, `auth.pass.wrongResource`, `auth.pass.expired` or `auth.pass.replayed`, or a 403 `auth.pass.unmapped`, each with an English text in `locales/en.json`. `AUTH_PATHS.LOGIN_PASS` is `/api/login/pass`, and the auth service gains the optional `signInWithPass({ pass })`.
7
8
  - `AUTH_COOKIE_SAME_SITE` sets the CSRF cookie's SameSite: `lax` (the default, unset or blank) or `strict`, as local auth's cookies take it; any other value stops the auth policy's startup with `AUTH_COOKIE_SAME_SITE must be lax or strict, not "<value>".` `./server/utils` exports `resolveAuthCookieSameSite(env)`, which reads it. Applications that leave it unset are unchanged.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@jskit-ai/auth-core",
3
- "version": "0.2.29",
3
+ "version": "0.2.30",
4
4
  "type": "module",
5
5
  "scripts": {
6
6
  "test": "jskit test"
@@ -147,6 +147,6 @@
147
147
  }
148
148
  },
149
149
  "peerDependencies": {
150
- "@jskit-ai/kernel": "0.2.26"
150
+ "@jskit-ai/kernel": "0.2.27"
151
151
  }
152
152
  }
@@ -1,4 +1,5 @@
1
1
  import { hasPermission } from "@jskit-ai/kernel/shared/support/permissions";
2
+ import { appEnvironment } from "@jskit-ai/kernel/shared/support/appEnvironment";
2
3
  import { parseBooleanFlag } from "./booleanFlag.js";
3
4
  import { resolveAuthCookieSameSite } from "./utils.js";
4
5
 
@@ -43,13 +44,13 @@ function createAuthPolicy({ authService, extensions, env }) {
43
44
  hasPermission: defaultHasPermission,
44
45
  resolveContext,
45
46
  options: Object.freeze({
46
- // The plugin resolves both defaults: NODE_ENV not production, and the /api/ prefix.
47
- nodeEnv: env.NODE_ENV,
47
+ // The plugin resolves the /api/ prefix by default; the CSRF cookie follows APP_ENV.
48
+ appEnv: appEnvironment(env),
48
49
  apiPrefix: env.AUTH_API_PREFIX,
49
50
  // Unset AUTH_CSRF_UNSAFE_METHODS keeps the plugin default (POST, PUT, PATCH, DELETE).
50
51
  unsafeMethods: unsafeMethods.length > 0 ? Object.freeze(unsafeMethods) : undefined,
51
52
  // The CSRF cookie's SameSite is the sign-in cookies' (AUTH_COOKIE_SAME_SITE). Unset AUTH_CSRF_COOKIE_SECURE
52
- // follows NODE_ENV (Secure in production).
53
+ // follows APP_ENV (Secure in staging and production).
53
54
  csrfCookieOpts: Object.freeze({
54
55
  sameSite: csrfCookieSameSite,
55
56
  ...(String(env.AUTH_CSRF_COOKIE_SECURE ?? "").trim()
@@ -1,4 +1,4 @@
1
- import { isProductionEnv } from "@jskit-ai/kernel/server/runtime/runtimeMode";
1
+ import { isDeployed } from "@jskit-ai/kernel/shared/support/appEnvironment";
2
2
  import { AppError } from "@jskit-ai/kernel/server/runtime/errors";
3
3
  import { timingSafeEqual } from "node:crypto";
4
4
  import { parseBooleanFlag } from "./booleanFlag.js";
@@ -54,40 +54,42 @@ function isLocalDevAuthRequest(request) {
54
54
  return isLoopbackIp(remoteAddress) && isLoopbackHostname(normalizeRequestHostname(request));
55
55
  }
56
56
 
57
- function resolveDevAuthPolicy({
58
- enabled = false,
59
- nodeEnv = "development",
60
- secret = ""
61
- } = {}) {
57
+ /**
58
+ * Dev sign-in's policy, and whether the application is deployed (staging or production), which every auth provider
59
+ * reads from here to refuse development shortcuts such as cookies without Secure.
60
+ * @param {{ enabled?: unknown, appEnv: string, secret?: string }} settings `appEnv` is the application's APP_ENV;
61
+ * a missing or unknown one throws.
62
+ */
63
+ function resolveDevAuthPolicy({ enabled = false, appEnv, secret = "" }) {
62
64
  return Object.freeze({
63
65
  enabled: parseBooleanFlag(enabled, false),
64
- isProduction: isProductionEnv({ NODE_ENV: nodeEnv }),
66
+ isDeployed: isDeployed({ APP_ENV: appEnv }),
65
67
  secret: String(secret || "").trim()
66
68
  });
67
69
  }
68
70
 
69
- function resolveDevAuthPolicyFromEnv(env = {}) {
71
+ function resolveDevAuthPolicyFromEnv(env) {
70
72
  return resolveDevAuthPolicy({
71
73
  enabled: env.AUTH_DEV_BYPASS_ENABLED,
72
- nodeEnv: env.NODE_ENV,
74
+ appEnv: env.APP_ENV,
73
75
  secret: env.AUTH_DEV_BYPASS_SECRET
74
76
  });
75
77
  }
76
78
 
77
79
  /**
78
- * True when dev sign-in as another user is on: enabled, outside production.
80
+ * True when dev sign-in as another user is on: enabled, in development or test.
79
81
  * @param {ReturnType<typeof resolveDevAuthPolicy>} policy
80
82
  */
81
83
  function isDevAuthBootstrapEnabled(policy) {
82
- return policy.enabled && !policy.isProduction;
84
+ return policy.enabled && !policy.isDeployed;
83
85
  }
84
86
 
85
87
  function assertDevAuthPolicy(policy = {}) {
86
88
  if (!policy.enabled) {
87
89
  return;
88
90
  }
89
- if (policy.isProduction) {
90
- throw new Error("AUTH_DEV_BYPASS_ENABLED must not be enabled in production.");
91
+ if (policy.isDeployed) {
92
+ throw new Error("AUTH_DEV_BYPASS_ENABLED is for development only: remove it from staging and production.");
91
93
  }
92
94
  if (!policy.secret) {
93
95
  throw new Error("AUTH_DEV_BYPASS_SECRET is required when AUTH_DEV_BYPASS_ENABLED=true.");
@@ -95,7 +97,7 @@ function assertDevAuthPolicy(policy = {}) {
95
97
  }
96
98
 
97
99
  function ensureDevAuthRuntimeAvailable(policy = {}, request = null) {
98
- if (!policy.enabled || policy.isProduction) {
100
+ if (!policy.enabled || policy.isDeployed) {
99
101
  throw new AppError(404, "Not found.", { code: "auth.dev.unavailable" });
100
102
  }
101
103
  if (!policy.secret) {
@@ -1,7 +1,7 @@
1
1
  import fastifyCookie from "@fastify/cookie";
2
2
  import fastifyCsrfProtection from "@fastify/csrf-protection";
3
3
  import { safeRequestUrl } from "@jskit-ai/kernel/server/runtime/requestUrl";
4
- import { isProductionEnv } from "@jskit-ai/kernel/server/runtime/runtimeMode";
4
+ import { isDeployed } from "@jskit-ai/kernel/shared/support/appEnvironment";
5
5
  import { SECOND_FACTOR_REQUIRED } from "../../shared/authSecondFactor.js";
6
6
  import { isSecondFactorMet, secondFactorRequiredParams } from "../secondFactor.js";
7
7
  import { hostOnlyCookieName } from "../utils.js";
@@ -81,9 +81,9 @@ function authPolicyPlugin(deps = {}, options = {}) {
81
81
  const { resolveCsrfToken: resolveCsrfTokenFn = resolveCsrfToken, createError = createAuthPolicyError } = options;
82
82
 
83
83
  // CSRF uses tokens checked against a secret cookie, never SameSite alone. In
84
- // production that cookie is host-only (__Host-), so a sibling host cannot plant
84
+ // staging and production (APP_ENV) that cookie is host-only (__Host-), so a sibling host cannot plant
85
85
  // a secret it knows and forge tokens.
86
- const csrfCookieSecure = typeof csrfCookieOpts.secure === "boolean" ? csrfCookieOpts.secure : isProductionEnv({ NODE_ENV: options.nodeEnv });
86
+ const csrfCookieSecure = typeof csrfCookieOpts.secure === "boolean" ? csrfCookieOpts.secure : isDeployed({ APP_ENV: options.appEnv });
87
87
  const csrfCookieOptions = {
88
88
  path: "/",
89
89
  sameSite: "lax",
@@ -39,7 +39,7 @@ const authRegisterBodyValidator = deepFreeze({
39
39
  source: { type: "string", required: false, minLength: 1, maxLength: 120 }
40
40
  })
41
41
  },
42
- // The first account's one-time setup code, which a production server
42
+ // The first account's one-time setup code, which a staging or production server
43
43
  // without accounts asks for (capability features.firstAccountSetupCode).
44
44
  setupCode: { type: "string", required: false, minLength: 1, maxLength: 64 }
45
45
  }),
@@ -27,7 +27,7 @@ async function createApp(t) {
27
27
  }
28
28
  },
29
29
  extensions,
30
- env: { NODE_ENV: "test" }
30
+ env: { APP_ENV: "test" }
31
31
  });
32
32
 
33
33
  const app = Fastify();
@@ -7,8 +7,10 @@ import {
7
7
  assertDevAuthPolicy,
8
8
  ensureDevAuthExchangeAvailable,
9
9
  ensureDevAuthRuntimeAvailable,
10
+ isDevAuthBootstrapEnabled,
10
11
  isLocalDevAuthRequest,
11
- resolveDevAuthPolicy
12
+ resolveDevAuthPolicy,
13
+ resolveDevAuthPolicyFromEnv
12
14
  } from "../src/server/devAuth.js";
13
15
 
14
16
  const DEV_AUTH_SECRET = "preview-exchange-secret";
@@ -32,7 +34,7 @@ function createRequest({
32
34
  function enabledPolicy(overrides = {}) {
33
35
  return resolveDevAuthPolicy({
34
36
  enabled: true,
35
- nodeEnv: "development",
37
+ appEnv: "development",
36
38
  secret: DEV_AUTH_SECRET,
37
39
  ...overrides
38
40
  });
@@ -47,14 +49,32 @@ test("parseBooleanFlag normalizes conventional environment flag values", () => {
47
49
 
48
50
  test("dev auth policy rejects production and missing-secret enablement", () => {
49
51
  assert.throws(
50
- () => assertDevAuthPolicy(enabledPolicy({ nodeEnv: "production" })),
51
- /must not be enabled in production/
52
+ () => assertDevAuthPolicy(enabledPolicy({ appEnv: "staging" })),
53
+ { message: /^AUTH_DEV_BYPASS_ENABLED is for development only: remove it from staging and production\.$/u }
52
54
  );
53
55
  assert.throws(
54
56
  () => assertDevAuthPolicy(enabledPolicy({ secret: "" })),
55
57
  /AUTH_DEV_BYPASS_SECRET is required/
56
58
  );
57
- assert.doesNotThrow(() => assertDevAuthPolicy(resolveDevAuthPolicy()));
59
+ assert.doesNotThrow(() => assertDevAuthPolicy(resolveDevAuthPolicy({ appEnv: "production" })), "off is allowed anywhere");
60
+ assert.throws(() => resolveDevAuthPolicy({ enabled: true }), { message: /^APP_ENV is not set/u }, "never guesses development");
61
+ });
62
+
63
+ test("dev sign-in follows APP_ENV: allowed in development and test, refused in staging and production, whatever NODE_ENV", () => {
64
+ const policyIn = (APP_ENV, NODE_ENV) => resolveDevAuthPolicyFromEnv({
65
+ APP_ENV, NODE_ENV, AUTH_DEV_BYPASS_ENABLED: "true", AUTH_DEV_BYPASS_SECRET: DEV_AUTH_SECRET
66
+ });
67
+ for (const APP_ENV of ["development", "test"]) {
68
+ assert.equal(isDevAuthBootstrapEnabled(policyIn(APP_ENV, "production")), true, APP_ENV);
69
+ assert.doesNotThrow(() => ensureDevAuthRuntimeAvailable(policyIn(APP_ENV, "production"), createRequest()), APP_ENV);
70
+ }
71
+ for (const APP_ENV of ["staging", "production"]) {
72
+ const policy = policyIn(APP_ENV, "production");
73
+ assert.equal(policy.isDeployed, true, APP_ENV);
74
+ assert.equal(isDevAuthBootstrapEnabled(policy), false, APP_ENV);
75
+ assert.throws(() => ensureDevAuthRuntimeAvailable(policy, createRequest()), { code: "auth.dev.unavailable" }, APP_ENV);
76
+ }
77
+ assert.throws(() => resolveDevAuthPolicyFromEnv({}), { message: /^APP_ENV is not set/u });
58
78
  });
59
79
 
60
80
  test("dev auth trusts only a direct loopback connection with a loopback Host", () => {
@@ -111,7 +131,7 @@ test("dev auth refusals carry their own codes", () => {
111
131
  }
112
132
  return null;
113
133
  };
114
- assert.equal(codeOf(() => ensureDevAuthRuntimeAvailable(resolveDevAuthPolicy(), createRequest())), "auth.dev.unavailable");
134
+ assert.equal(codeOf(() => ensureDevAuthRuntimeAvailable(resolveDevAuthPolicy({ appEnv: "development" }), createRequest())), "auth.dev.unavailable");
115
135
  assert.throws(() => ensureDevAuthRuntimeAvailable(enabledPolicy({ secret: "" }), createRequest()), (error) =>
116
136
  error.message === "AUTH_DEV_BYPASS_SECRET is required when AUTH_DEV_BYPASS_ENABLED=true." && error.code === undefined);
117
137
  assert.equal(
@@ -15,7 +15,7 @@ test("auth policy protects real Fastify requests with CSRF", async (t) => {
15
15
  hasPermission() {
16
16
  return false;
17
17
  }
18
- }, { nodeEnv: "test" })(app);
18
+ }, { appEnv: "test" })(app);
19
19
 
20
20
  app.get("/api/csrf", { config: { authPolicy: "public" } }, (_request, reply) => ({
21
21
  token: reply.generateCsrf()
@@ -53,7 +53,7 @@ test("production CSRF secrets live in a host-only __Host- cookie a sibling host
53
53
  hasPermission() {
54
54
  return false;
55
55
  }
56
- }, { nodeEnv: "production" })(app);
56
+ }, { appEnv: "production" })(app);
57
57
  app.get("/api/csrf", { config: { authPolicy: "public" } }, (_request, reply) => ({ token: reply.generateCsrf() }));
58
58
  app.post("/api/write", { config: { authPolicy: "public" } }, () => ({ accepted: true }));
59
59
 
@@ -98,7 +98,7 @@ test("resolves csrf token headers and skips auth for non-api/public routes", asy
98
98
  }
99
99
  },
100
100
  {
101
- nodeEnv: "test"
101
+ appEnv: "test"
102
102
  }
103
103
  );
104
104
 
@@ -145,7 +145,7 @@ test("propagates csrf callback error", async () => {
145
145
  hasPermission() {
146
146
  return true;
147
147
  }
148
- });
148
+ }, { appEnv: "test" });
149
149
 
150
150
  await registerPlugin(fastify);
151
151
  await assert.rejects(
@@ -194,7 +194,7 @@ test("enforces own policy owner checks and invalid policy guard", async () => {
194
194
  onPolicyDenied(event) {
195
195
  denyEvents.push(event);
196
196
  }
197
- });
197
+ }, { appEnv: "test" });
198
198
 
199
199
  await registerPlugin(fastify);
200
200
 
@@ -295,7 +295,7 @@ test("enforces permission checks and resolves workspace context when requested",
295
295
  onPolicyDenied(event) {
296
296
  denyEvents.push(event);
297
297
  }
298
- });
298
+ }, { appEnv: "test" });
299
299
 
300
300
  await registerPlugin(fastify);
301
301
  await assert.rejects(
@@ -330,7 +330,7 @@ test("each policy refusal carries its own code next to the English", async () =>
330
330
  hasPermission() {
331
331
  return false;
332
332
  }
333
- })(fastify);
333
+ }, { appEnv: "test" })(fastify);
334
334
 
335
335
  async function refusal(config, params = {}) {
336
336
  try {
@@ -20,7 +20,7 @@ function createFastify() {
20
20
 
21
21
  function runtimeInputs(fastify) {
22
22
  return {
23
- "runtime.env": { NODE_ENV: "test" },
23
+ "runtime.env": { APP_ENV: "test" },
24
24
  "runtime.fastify": fastify,
25
25
  "runtime.logger": silentLogger
26
26
  };
@@ -157,7 +157,7 @@ async function csrfSecretCookie(t, env) {
157
157
  const app = Fastify();
158
158
  t.after(() => app.close());
159
159
  const runtime = createCapabilityRuntime({
160
- inputs: { ...runtimeInputs(app), "runtime.env": { NODE_ENV: "test", ...env } },
160
+ inputs: { ...runtimeInputs(app), "runtime.env": { APP_ENV: "test", ...env } },
161
161
  providers: [EventProvider, ActionProvider, HttpProvider, AuthExtensionsProvider, AuthFeature, AuthPolicyProvider]
162
162
  });
163
163
  await runtime.start();
@@ -25,7 +25,7 @@ async function startPolicy({ hasPermission = () => true } = {}) {
25
25
  onPolicyDenied(event) {
26
26
  denied.push(event.reason);
27
27
  }
28
- })(fastify);
28
+ }, { appEnv: "test" })(fastify);
29
29
  return {
30
30
  state,
31
31
  denied,