@jwilleke/ngdpbase-types 5.30.0 → 5.31.0

package/lib/src/utils/roleGrants.d.ts

@@ -24,12 +24,27 @@ export interface RoleGrants {
     /** Actions a deny policy names for this role. */
     denies: string[];
 }
+/** A grant to one subject, with the policies that give it (#2067). */
+export interface SubjectGrant extends RoleGrant {
+    /** The ids of the allow policies that give it, lowest priority first. */
+    by: string[];
+}
+export interface SubjectGrants {
+    allows: SubjectGrant[];
+    /** Actions a deny policy names for this subject. */
+    denies: string[];
+}
 /**
  * Every role a policy names, with what its policies allow and deny — the one
  * reading of "what a role grants" (#1539): the user forms, the profile, the
  * admin roles page and `PolicyDecisionPoint.rolePermissions` all come from
- * here. Policies are applied lowest priority first, so a deny takes away what
- * a lower-priority allow gave and an allow above it gives it back — the order
- * the evaluator's first-match-by-priority decides in.
+ * here.
  */
 export declare function roleGrants(policies: readonly Policy[]): Record<string, RoleGrants>;
+/**
+ * Every scheduled job a policy names (`{ "type": "job", "value": "<job id>" }`,
+ * #1999), with what its policies allow and deny and which policy gives each
+ * allow — the admin roles page's Jobs part (#2067). A job a policy names acts
+ * as itself and holds only these. Display only, like {@link roleGrants}.
+ */
+export declare function jobGrants(policies: readonly Policy[]): Record<string, SubjectGrants>;

package/lib/src/utils/sessionSecurity.d.ts

@@ -0,0 +1,116 @@
+/**
+ * resolveSessionSecurity — keep `session.secure` and `trust proxy` consistent (#1046).
+ *
+ * #1043 made the session cookie `secure` actually turn on in production. On
+ * every HTTPS deployment that terminates TLS upstream — Cloudflare, an ingress,
+ * a tunnel — that silently broke login:
+ *
+ *   1. `secure` resolves true, so express-session will only emit `Set-Cookie`
+ *      on a connection it believes is https.
+ *   2. `trust proxy` defaults to false, so Express reads the raw socket and
+ *      believes the connection is plain http. It is not wrong — the hop from
+ *      the proxy really is http; it simply has not been told to read
+ *      X-Forwarded-Proto.
+ *   3. No session cookie ever reaches the browser. Every following request
+ *      builds a fresh session, so `req.session.csrfToken` is missing and the
+ *      CSRF middleware answers `403 Forbidden — invalid CSRF token` — on
+ *      `POST /login` included. Nobody can sign in.
+ *
+ * The two settings are not independent, so they are resolved together here.
+ * Turning on `secure` without `trust proxy` is not a working configuration;
+ * `secure` is the operator's stated intent to be behind TLS, and behind
+ * terminated TLS `trust proxy` is what makes Express able to see it.
+ *
+ * The operator's explicit choice still wins for both keys. The shipped
+ * app-default-config.json pins `ngdpbase.session.secure` and
+ * `ngdpbase.server.trust-proxy` to false, so a plain getProperty() read cannot
+ * tell "operator asked for false" from "nobody has said anything" — hence
+ * reading getCustomProperties() rather than the merged view.
+ *
+ * ## #1160 — native TLS breaks the assumption
+ *
+ * All of the above assumed `secure: true` meant TLS terminated UPSTREAM, so a
+ * proxy existed whose `X-Forwarded-Proto` Express had to be told to read. #1153
+ * made the server able to terminate TLS itself, and then there is no proxy —
+ * and trusting a forwarded header that nothing sets is worse than not trusting
+ * it. With `trust proxy` on and nothing in front, a caller can assert their own
+ * address and scheme, which the login throttle counts by and the audit log
+ * records.
+ *
+ * So the derivation now asks what is actually true rather than inferring from
+ * `secure` alone. The same applies to the misconfiguration warning: `secure`
+ * with `trust-proxy` explicitly false is the CORRECT configuration under native
+ * TLS, and warning about it would train an operator to ignore a warning that is
+ * load-bearing in the upstream case.
+ */
+/** Express's accepted `trust proxy` values: off, hop count, or a subnet list. */
+export type TrustProxyValue = boolean | number | string;
+/** What the resolution needs to know about the transport (#1160). */
+export interface SessionSecurityContext {
+    /**
+     * True when this server terminates TLS itself (#1153).
+     *
+     * Defaults to false so every existing caller keeps its pre-#1160 behaviour
+     * rather than silently changing what it resolves.
+     */
+    nativeTls?: boolean;
+}
+export interface SessionSecurity {
+    /** Value for the session cookie's `secure` flag. */
+    secure: boolean;
+    /** Value for `app.set('trust proxy', …)`. `false` means do not set it. */
+    trustProxy: TrustProxyValue;
+    /** True when `trustProxy` was derived from `secure` rather than configured. */
+    trustProxyDerived: boolean;
+    /**
+     * True when the resolved pair cannot issue a session cookie behind
+     * terminated TLS — `secure` on with `trust proxy` explicitly off. Only
+     * reachable when the operator configured that combination by hand; the
+     * caller is expected to log it loudly rather than silently "fix" a stated
+     * choice.
+     */
+    misconfigured: boolean;
+}
+/**
+ * Resolve the session cookie's `secure` flag and the matching `trust proxy`.
+ *
+ * `secure`: the operator's explicit boolean, else on when NODE_ENV is
+ * production. Inferring it from the request would get the terminated-TLS case
+ * exactly backwards, which is the case that matters.
+ *
+ * `trustProxy`: the operator's explicit value, else `true` whenever `secure`
+ * ends up on. `true` — rather than a hop count — because req.ip must come out
+ * as the end client. Under `1` behind Cloudflare, req.ip would resolve to the
+ * edge address shared by every visitor, and the login throttle's `ip:` bucket
+ * (#1044) would lock out all users at once on ten failures from anyone. An
+ * operator whose instance is also reachable directly should pin a hop count or
+ * a subnet list, since X-Forwarded-For is client-spoofable on that path.
+ *
+ * @param customProperties operator overrides only — NOT the merged config
+ * @param nodeEnv typically process.env.NODE_ENV
+ */
+export declare function resolveSessionSecurity(customProperties: Record<string, unknown> | null | undefined, nodeEnv: string | undefined, context?: SessionSecurityContext): SessionSecurity;
+/**
+ * #2071 — what an administrator and a visitor are told when the session
+ * cookie cannot reach the browser, spelled once: the server log, the admin
+ * dashboard, the CSRF refusal and the login page all say this.
+ */
+export declare const SESSION_COOKIE_WITHHELD_MESSAGE: string;
+/** The two request fields the check reads; express's Request has both. */
+export interface SessionCookieRequest {
+    secure?: boolean;
+    session?: {
+        cookie?: {
+            secure?: unknown;
+        };
+    } | null;
+}
+/**
+ * True when express-session will NOT send the session cookie on this request
+ * (#2071): the cookie is `secure` and the request is not https as Express
+ * sees it, after `trust proxy`. express-session makes exactly this check and
+ * then silently sends nothing, so the browser has no session, every POST
+ * meets a fresh one, and the CSRF middleware refuses it. A boolean read of
+ * two fields, cheap enough for every request.
+ */
+export declare function sessionCookieWithheld(req: SessionCookieRequest): boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jwilleke/ngdpbase-types",
-  "version": "5.30.0",
+  "version": "5.31.0",
   "description": "TypeScript types for ngdpbase add-ons, and a test kit of core's own values. A dev dependency, versioned with ngdpbase.",
   "license": "Apache-2.0",
   "author": "Jim Willeke",