@pipeline-builder/api-core 4.1.5 → 4.1.7

package/lib/middleware/auth.d.ts

@@ -1,5 +1,7 @@
 import type { Request, Response, NextFunction } from 'express';
+import { type OrgAdminAssuranceMachines } from './route-table.js';
 import { type AssuranceLevel, type JwtPayload } from '../types/common.js';
+import { ErrorCode } from '../types/error-codes.js';
 import { type Permission } from '../types/permissions.js';
 /**
  * Verify a token that speaks for a PERSON — access, step-up, and the token an
@@ -157,6 +159,61 @@ export interface AssuranceOptions {
  * of "is this session MFA-grade" in the codebase.
  */
 export declare function requireAssurance(options: AssuranceOptions): (req: Request, res: Response, next: NextFunction) => void;
+/**
+ * Handler-level twin of {@link requireAssurance}, for a route where only SOME
+ * requests must be MFA-grade — e.g. a policy route on which TIGHTENING a setting
+ * stays open to a single-factor session (so an admin without MFA can adopt it)
+ * but LOOSENING it does not. Same rules and the same three refusals. Returns
+ * true when the request was REFUSED (a response has been sent).
+ */
+export declare function refuseWeakSession(req: Request, res: Response, options: AssuranceOptions): boolean;
+/** What {@link requireOrgAdminAssurance} demands of a route. */
+export interface OrgAdminAssuranceOptions {
+    /** What a machine credential (PAT, service account, machine session) meets on
+     *  this route while the policy is on — see {@link OrgAdminAssuranceMachines}.
+     *  Required, so every route states its decision rather than inheriting one. */
+    machines: OrgAdminAssuranceMachines;
+}
+/** `details.reason` on a refusal by {@link requireOrgAdminAssurance}, so the UI
+ *  can say it is the ORG's policy asking, not the route's own requirement. */
+export declare const ORG_ADMIN_MFA_REASON = "org_admin_policy";
+/**
+ * The refusal {@link requireOrgAdminAssurance} would send for these claims, or
+ * `undefined` when the request may proceed. Exported so a handler whose policy
+ * applies to only PART of a route (e.g. `generate-token`, where opening a new
+ * machine credential is gated but renewing an existing one is not) applies the
+ * exact same rule rather than a copy of it.
+ */
+export declare function orgAdminAssuranceRefusal(claims: JwtPayload | undefined, options: OrgAdminAssuranceOptions): {
+    status: number;
+    code: ErrorCode;
+    message: string;
+    reason: 'machine_principal' | 'weak_session';
+} | undefined;
+/**
+ * Apply {@link orgAdminAssuranceRefusal} and send its refusal. Returns true when
+ * the request was REFUSED (a response has been sent). For handler-level use;
+ * routes use {@link requireOrgAdminAssurance}.
+ */
+export declare function refuseForOrgAdminAssurance(req: Request, res: Response, options: OrgAdminAssuranceOptions): boolean;
+/**
+ * The org policy "administrative actions require MFA" (`adminActionsRequireMfa`).
+ *
+ * Unlike {@link requireAssurance}, the requirement is the ORG's choice, not the
+ * route's: the gate reads the `org_admin_aal` claim, set at token issue from the
+ * active org's policy (strictest across its ancestors), so a service that cannot
+ * read the org document still enforces it. With the policy off the gate is a
+ * no-op; with it on, a single-factor session is refused 401 `MFA_REQUIRED`
+ * (with `details.reason: 'org_admin_policy'`) — the same code the client already
+ * turns into "enrol a factor / sign in with it", never a sign-out.
+ *
+ * `machines` is decided per route (see {@link OrgAdminAssuranceMachines}): the
+ * policy is about how strongly a PERSON's session was opened, so automation that
+ * legitimately drives a route keeps working (`allow`), while a route that mints
+ * a further credential refuses machines outright (`refuse`, 403
+ * `HUMAN_SESSION_REQUIRED` — the same refusal `requireAssurance` gives them).
+ */
+export declare function requireOrgAdminAssurance(options: OrgAdminAssuranceOptions): (req: Request, res: Response, next: NextFunction) => void;
 /**
  * Whether a verified token carries a well-formed identity: a known
  * `principalType` and `token_use`, and the claims that kind of principal must