@pipeline-builder/api-core 4.1.13 → 4.1.14

package/lib/middleware/auth.d.ts

@@ -1,43 +1,9 @@
-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
- * opaque access key is exchanged for — against platform's published signing
- * keys.
- *
- * ES256 and a `kid` are both mandatory: no `kid` means no way to pick the right
- * key across a rotation, and any other algorithm is refused outright, which is
- * what makes "no service accepts an HS256 user token" a property of the code
- * rather than a convention. Key lookup goes through the shared JWKS cache
- * (10-minute refresh, one refetch on an unknown `kid`, brief negative cache).
- *
- * @throws {UnknownKidError} the key set is current and has no such key → 401.
- * @throws {JwksUnavailableError} the key set could not be obtained → 503; an
- *         unverifiable token is never treated as valid.
- */
-export declare function verifyUserJwt<T = JwtPayload>(token: string): Promise<T>;
 /**
- * Verify ANY bearer token and return its claims.
- *
- * Since #14 there is no shared secret left: BOTH chains are ES256 with a `kid`,
- * so the dispatch is by **who owns the `kid`** rather than by algorithm — and
- * because a `kid` is an RFC 7638 thumbprint, ownership is a fact about the key,
- * not a claim the token makes about itself:
- *
- * - a `kid` published in the per-service key bundle → an INTERNAL SERVICE token
- *   ({@link signServiceToken}), verified with that service's key; its `sub` must
- *   name the same service, so one service can never speak for another.
- * - anything else → a platform-signed USER token, verified against platform's
- *   published JWKS. A token claiming `principalType: 'service'` is refused
- *   here: an internal identity may not ride the user signing key.
- *
- * Anything that is not ES256 with a `kid` fails in both chains, which is what
- * makes "no HS256 token is accepted anywhere" a property of the code.
+ * `requireAuth`: bearer / access-key authentication, the checks every
+ * verified request passes, and the tenant identity it attaches.
  */
-export declare function verifyBearerToken(token: string): Promise<JwtPayload>;
+import type { Request, Response, NextFunction } from 'express';
+import { type AssuranceLevel } from '../types/common.js';
 export interface RequireAuthOptions {
     /**
      * Allow x-org-id/x-org-name headers to override the JWT's organization fields.
@@ -50,7 +16,7 @@ export interface RequireAuthOptions {
      */
     allowOrgHeaderOverride?: boolean;
     /**
-     * Demand that the whole SESSION be at least this assurance level (#8).
+     * Demand that the whole SESSION be at least this assurance level.
      *
      * `minAssurance: 2` means the person authenticated with a second factor — a
      * passkey with user verification, a password plus an authenticator code, or
@@ -82,391 +48,3 @@ export interface RequireAuthOptions {
 /** JWT auth middleware. Use directly or call with options. */
 export declare function requireAuth(req: Request, res: Response, next: NextFunction): void;
 export declare function requireAuth(options?: RequireAuthOptions): (req: Request, res: Response, next: NextFunction) => void;
-/**
- * A source of the CURRENT `tokenVersion` for a user, backed by a store the
- * stateless services can read (in practice a Redis key the platform publishes
- * to on every privilege change). Registered via {@link setTokenRevocationStore}.
- *
- * `getCurrentVersion` returns the user's current version, or `null` when the
- * store has no entry — a miss is treated as "no known revocation" (fail-open):
- * revocation entries are published with a TTL matching the access-token
- * lifetime, so a missing entry means any token old enough to predate it has
- * already expired on its own.
- */
-export interface TokenRevocationStore {
-    getCurrentVersion(userId: string): Promise<number | null>;
-    /**
-     * Whether one IMPERSONATION session (by token `jti`) has been ended early.
-     *
-     * Optional so a store that predates it still links — but a store WITHOUT it
-     * cannot answer, and an impersonation token is then REJECTED. Unlike
-     * `getCurrentVersion`, this is deliberately not fail-open: the platform ends a
-     * session when someone withdraws consent, and a withdrawn consent that keeps
-     * working in every other service is not withdrawn.
-     */
-    getSessionRevocation?(jti: string): Promise<SessionRevocationState>;
-}
-/**
- * `revoked`     — the session was ended; reject.
- * `live`        — no revocation recorded; allow.
- * `unavailable` — the store couldn't be read or can't answer; REJECT. Distinct
- *                 from `live` precisely so an outage can't read as "not revoked".
- */
-export type SessionRevocationState = 'revoked' | 'live' | 'unavailable';
-/**
- * Register (or clear, with `undefined`) the process-wide token-revocation store.
- * When unset (the default), `requireAuth` performs NO revocation check (it relies
- * on the short access-token TTL); services opt in at boot by wiring their Redis
- * client. Platform keeps its own Mongo-backed check and need not register one.
- */
-export declare function setTokenRevocationStore(store: TokenRevocationStore | undefined): void;
-/**
- * Public revocation check for routes that verify a platform JWT OUTSIDE
- * `requireAuth` (e.g. the image-registry `/token` mint path, which resolves
- * identity itself). Returns true when the token's `tokenVersion` is strictly
- * behind the store's current version. Fail-open (never throws) — a store outage
- * or a token/store without a usable version yields false (allow), matching
- * `requireAuth`. Pass the verified JWT claims (`sub`, `tokenVersion`).
- */
-export declare function isAccessTokenRevoked(claims: {
-    sub?: string;
-    tokenVersion?: number;
-    jti?: string;
-    impersonatorId?: string;
-}): Promise<boolean>;
-/**
- * Whether a set of verified claims speaks for a PERSON's own session — the only
- * kind of credential an assurance level can be asserted about.
- *
- * Excludes all three machine shapes: an internal service principal, an org
- * service account, and any exchanged access key (`token_use: 'api_key'`, i.e. a
- * PAT or a service-account key), each of which authenticates a program holding a
- * secret rather than a person presenting factors.
- */
-export declare function isHumanPrincipal(claims: Pick<JwtPayload, 'principalType' | 'token_use'> | undefined): boolean;
-/** What an assurance gate demands. */
-export interface AssuranceOptions {
-    minAssurance: AssuranceLevel;
-    maxAge?: number;
-    /**
-     * A NAMED carve-out for requests that cannot possibly satisfy the level and
-     * must still be served — today only one exists: the bootstrap-administrator
-     * window, where a fresh install's single admin has no factor yet and the setup
-     * calls that create the install's automation credential would otherwise be
-     * unreachable (see platform's `isBootstrapSetupRequest`).
-     *
-     * It is deliberately shaped as `{ reason, when }` rather than a bare predicate:
-     * the reason is counted (`assurance_exempted_total{reason}`) and published on
-     * the route table as `assuranceExempt`, so an exemption cannot be added without
-     * showing up in the generated table a reviewer reads. The gate keeps its
-     * `minAssurance` tag either way — the route still requires MFA-grade for
-     * everyone the carve-out does not name.
-     */
-    exempt?: {
-        reason: string;
-        when: (req: Request) => boolean;
-    };
-}
-/**
- * Standalone assurance gate, for a service whose own `requireAuth` is not
- * api-core's (platform's is its own, because it reads Mongo). Compose it AFTER
- * authentication: `router.get('/x', requireAuth, requireAssurance({ minAssurance: 2 }), h)`.
- *
- * Identical rules and identical refusals to `requireAuth({ minAssurance })` —
- * that option simply calls the same check inline, so there is one implementation
- * 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
- * have. Fails closed — a token minted before these claims existed, or one with a
- * contradictory combination, is not an identity any gate should reason about.
- *
- * - `service`: `token_use: 'access'` and a `service:<name>` subject (the name
- *   feeds the denylist and audit attribution).
- * - `user` / `service_account`: `amr` (known methods), `aal` and `auth_time`.
- */
-export declare function hasValidIdentityClaims(decoded: Partial<JwtPayload>): boolean;
-/**
- * Whether the request's user holds `permission`. Superadmins implicitly hold
- * every permission. Reads the resolved `permissions` claim (set at token issue,
- * or re-derived per request by the platform).
- */
-export declare function userHasPermission(req: Request, permission: Permission): boolean;
-/**
- * Context passed to a registered authorization-denial auditor when a
- * state-changing request is rejected by `requirePermission` /
- * `requireSystemAdmin`.
- */
-export interface AuthzDenialInfo {
-    /** The denied user's id (`sub`), if authenticated. */
-    actorId?: string;
-    actorEmail?: string;
-    /** The user's active org at denial time. */
-    orgId?: string;
-    /** HTTP method + path of the rejected request. */
-    method: string;
-    path: string;
-    /** What was required: the missing permission(s), or 'system-admin'. */
-    required: string;
-}
-/**
- * Register (or clear, with `undefined`) the process-wide authorization-denial
- * auditor. Idempotent; the last registration wins.
- */
-export declare function setAuthzDenialAuditor(fn: ((info: AuthzDenialInfo) => void) | undefined): void;
-/**
- * Emit a denial event, best-effort. Only fires for state-changing (non-GET,
- * non-HEAD/OPTIONS) requests — a rejected GET is low-signal probing noise and
- * would amplify audit volume under a scan. Never throws.
- *
- * The permission gates here call it themselves. Export it for data-driven checks
- * a route makes inline (cross-org access, service-only endpoints), so those 403s
- * reach the same `authz.denied` trail. `required` names what was missing.
- */
-export declare function recordAuthzDenial(req: Request, required: string): void;
-/**
- * Requires that the user hold AT LEAST ONE of the given permissions (or be a
- * superadmin). Use after requireAuth. Mirrors `requireRole`'s any-of semantics;
- * pass a single permission for a specific action, or several when any one of
- * them should grant access.
- */
-export declare function requirePermission(...permissions: Permission[]): (req: Request, res: Response, next: NextFunction) => void;
-/**
- * Requires that the user hold EVERY one of the given permissions (or be a
- * superadmin) — the AND counterpart to `requirePermission`'s any-of. Use for a
- * sensitive action that legitimately demands two distinct capabilities at once
- * (e.g. a cross-surface operation), so the guarantee is explicit rather than
- * approximated by chaining two `requirePermission` gates. Superadmins bypass
- * (they implicitly hold every permission).
- */
-export declare function requireAllPermissions(...permissions: Permission[]): (req: Request, res: Response, next: NextFunction) => void;
-/**
- * Like {@link requirePermission} (any-of) but ALSO admits an internal service
- * principal (`principalType: 'service'`). For READ endpoints that BOTH
- * interactive users — who must hold one of the `:read` capabilities — AND
- * service-to-service callers legitimately hit; service tokens carry no
- * permission claims (they're least-privilege `role:member`), so a plain
- * `requirePermission` would wrongly 403 them. Superadmins pass via
- * `userHasPermission`'s implicit-all. Use only where a service caller is a known,
- * intended consumer of the route (verify the callers); prefer plain
- * `requirePermission` for purely user-facing reads.
- */
-export declare function requirePermissionOrService(...permissions: Permission[]): (req: Request, res: Response, next: NextFunction) => void;
-/**
- * Gate an endpoint to internal service-to-service callers only (a
- * `principalType: 'service'` principal minted via {@link signServiceToken} / `getServiceAuthHeader`).
- * Rejects any user token. For NON-user-facing endpoints — entity-event ingest,
- * auto-subscribe, and similar peer-service hooks — that a browser must never
- * reach. Compose after `requireAuth` so `req.user` is populated.
- */
-export declare function requireServicePrincipal(req: Request, res: Response, next: NextFunction): void;
-/**
- * THE gate for an INTERNAL route (#14) — the one every `/internal/*` path, the
- * quota usage counters, the entity-event ingest and the audit ingest go through.
- *
- * Two rules, both fail-closed:
- *
- *  1. **No user token, ever.** Not a member's, not a superadmin's, not a
- *     service-account key's. An internal route is a peer-service API surface, so
- *     "a sufficiently privileged human" is not an acceptable caller — that
- *     equivalence is exactly how a browser-reachable path becomes a tenant
- *     boundary bug. `requireServicePrincipal` already refused users; this also
- *     closes the `|| isSystemAdmin(req)` escape hatches that had grown around
- *     the individual internal routes.
- *  2. **Only the NAMED callers.** `callers` lists the services that legitimately
- *     call this route, and the name is cryptographically bound to the signing
- *     key (`services/service-keys.ts`), so this is an identity check rather than
- *     a claim check. It is the same allow-list the mesh policy names, at the
- *     layer that also holds in docker compose, where there is no mesh at all —
- *     the Istio `AuthorizationPolicy` is defence in depth on top, never the
- *     enforcement.
- *
- * Compose after `requireAuth` so `req.user` is populated. Refusals are counted
- * (`internal_route_refused_total`) and audited through the shared `authz.denied`
- * sink.
- */
-export declare function requireInternalService(options: {
-    callers: readonly string[];
-}): (req: Request, res: Response, next: NextFunction) => void;
-/**
- * The system tenant's canonical org **id** — a fixed, well-known ObjectId (NOT
- * the string 'system'). This is the single knob every service resolves the
- * system tenant through; override via the `SYSTEM_ORG_ID` env for alternate
- * installs. The system org's human identifier stays the slug/name 'system'
- * (see {@link SYSTEM_ORG_SLUG}); only its `_id` is this ObjectId.
- */
-export declare const SYSTEM_ORG_ID: string;
-/** The system org's well-known slug/name (the human identifier; its `_id` is {@link SYSTEM_ORG_ID}). */
-export declare const SYSTEM_ORG_SLUG = "system";
-/**
- * Check if an orgId or orgName/slug matches the system org. Use this instead of
- * comparing directly: the id is now an ObjectId ({@link SYSTEM_ORG_ID}) while the
- * name/slug is 'system' ({@link SYSTEM_ORG_SLUG}), so the two are compared against
- * their respective canonical values.
- */
-export declare function isSystemOrgId(orgId?: string, orgName?: string): boolean;
-/**
- * Check if the request is from a system admin.
- *
- * Authority is granted solely by the user-level `isSuperAdmin` flag carried
- * in the JWT. The "membership in the well-known 'system' org with role
- * admin/owner" path was removed — it conflated a Pipeline Builder operator
- * with a real customer tenant in the data model, and meant any unintended
- * write that created a 'system'-named org could quietly grant cross-org
- * authority. The `system` org still exists as a *content holder* for shared
- * sample data; it just no longer confers privilege.
- */
-export declare function isSystemAdmin(req: Request): boolean;
-/**
- * Whether the request's token carries a specific capability `scope` (e.g.
- * `'reporting:ingest'`). Used to gate endpoints that accept a narrow machine
- * identity — a normal interactive user token has no `scope` and returns false.
- */
-export declare function hasScope(req: Request, scope: string): boolean;
-/** Requires a system admin — granted solely by the `isSuperAdmin` token claim
- *  (the org-membership path was removed). Use after requireAuth. */
-export declare function requireSystemAdmin(req: Request, res: Response, next: NextFunction): void;
-/**
- * Require a specific feature flag. Use after requireAuth.
- * Checks the `features` array in the JWT payload (set at token issuance).
- * Sysadmins (isSuperAdmin) bypass — they always have every feature.
- */
-export declare function requireFeature(feature: string): (req: Request, res: Response, next: NextFunction) => void;
-/**
- * The calling service's name for a SERVICE principal (`principalType: 'service'`),
- * else `undefined`. A user token never yields a name, whatever its `sub` says.
- */
-export declare function serviceNameOf(claims: {
-    principalType?: string;
-    sub?: string;
-} | undefined): string | undefined;
-/** True when the claims are a service principal whose service is on the denylist. */
-export declare function isServiceTokenDenied(claims: {
-    principalType?: string;
-    sub?: string;
-}): boolean;
-export interface ServiceTokenOptions {
-    /** Calling service identifier (e.g. 'billing', 'platform'). Embedded as `sub: service:<name>`. */
-    serviceName: string;
-    /** Active org context for the call. Use the target tenant's org id, or the
-     *  well-known `SYSTEM_ORG_ID` (an ObjectId) for system-wide ops — NOT the string
-     *  'system', which id-based system-org checks won't recognize. */
-    orgId?: string;
-    /** Active org name. Defaults to orgId. */
-    orgName?: string;
-    /** TTL in seconds (default 300). */
-    ttlSeconds?: number;
-    /**
-     * Role the token carries (required — no implicit default). **Pass the LOWEST
-     * role the call actually needs** (`'member'` for read / data-plane calls) so a
-     * leaked service token can't perform admin actions in the target org.
-     * `isAdmin` is derived from this (admin|owner → true).
-     */
-    role: 'owner' | 'admin' | 'member';
-    /**
-     * Optional fine-grained permission claim. Prefer this + `role: 'member'` over a
-     * high role when a call needs ONE specific capability (e.g. `['plugins:write']`
-     * to push a plugin image) — the token then satisfies that permission gate
-     * WITHOUT carrying `isAdmin`, so a leaked token can't perform admin actions.
-     */
-    permissions?: Permission[];
-}
-/**
- * Mint a JWT identifying the calling service. Used for inter-service HTTP calls.
- * The token satisfies `requireAuth` and (when orgId is present) `requireOrganization`.
- * Scope it with `opts.role` — least privilege keeps a leaked token low-value.
- *
- * `opts.serviceName` must be THIS process's own identity (`SERVICE_NAME`): a
- * service holds only its own signing key, so minting a token that names another
- * service throws rather than producing one every peer would reject. That is the
- * one behaviour change #14 forces on callers — see `services/service-keys.ts`.
- */
-export declare function signServiceToken(opts: ServiceTokenOptions): string;
-/** Convenience: returns a `Bearer <token>` header value for fetch/axios calls. */
-export declare function getServiceAuthHeader(opts: ServiceTokenOptions): string;
-/** True when `req.user` is a service principal (`principalType: 'service'`, minted by `signServiceToken`). */
-export declare function isServicePrincipal(req: Request): boolean;
-/**
- * True when `req.user` is an ORG SERVICE ACCOUNT (`principalType:
- * 'service_account'`) — a non-human principal owned by one org, authenticating
- * with a `pb_sa_…` key exchanged at platform.
- *
- * A service account is NOT an internal service principal: it holds org Roles and
- * is subject to every permission gate a member is. What it can never do is
- * satisfy a HUMAN-presence requirement — step-up (and any later assurance gate)
- * refuses it outright, because there is no person behind it to re-verify.
- */
-export declare function isServiceAccountPrincipal(req: Request): boolean;
-/** True when `req.user` is the named internal service (e.g. `'billing'`). */
-export declare function isServicePrincipalNamed(req: Request, serviceName: string): boolean;
-/**
- * PRE-auth check: cryptographically verify the request carries a valid, signed
- * SERVICE token (`principalType: 'service'`). Unlike {@link isServicePrincipal}
- * (which reads the already-populated `req.user`), this verifies the bearer token
- * itself, so it is safe to call BEFORE `requireAuth` runs — e.g. the global rate
- * limiter's `skip`, which must not trust the spoofable `x-internal-service`
- * header. Mirrors `requireAuth`'s SERVICE chain exactly (the signer's own key,
- * resolved by `kid`, with the `sub`/signer agreement check and the optional
- * issuer/audience) and returns `false` on any missing/invalid/non-service token
- * — including any platform-signed USER token, whose `kid` is not in the service
- * bundle at all. Stays SYNCHRONOUS, which is why the per-service public keys are
- * distributed as a mounted bundle rather than fetched over HTTP.
- */
-export declare function verifyServicePrincipal(req: Request): boolean;