@pipeline-builder/api-core 0.0.1

package/lib/middleware/auth.d.ts

@@ -0,0 +1,208 @@
+import type { Request, Response, NextFunction } from 'express';
+import { type Permission } from '../types/permissions.js';
+export interface RequireAuthOptions {
+    /**
+     * Allow x-org-id/x-org-name headers to override the JWT's organization fields.
+     *
+     * When enabled, the `x-org-id`/`x-org-name` headers override the caller's org
+     * — but ONLY for a verified SYS-ADMIN (`isSuperAdmin` claim). For any ordinary
+     * authenticated user the headers are ignored, so enabling this can never let a
+     * normal user impersonate another tenant's org. Use for cross-org admin tooling
+     * (e.g. a sysadmin managing a given org's billing). If unsure, leave it disabled.
+     */
+    allowOrgHeaderOverride?: boolean;
+}
+/** 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>;
+}
+/**
+ * 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;
+}): Promise<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;
+/**
+ * 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 (a `service:*` machine token). 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 `service:*`
+ * machine 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 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;
+/** Replace the service-token denylist (service names). Empty ⇒ kill-switch off. */
+export declare function setServiceTokenDenylist(names: Iterable<string>): void;
+/** True when `sub` is `service:<name>` and `<name>` is on the denylist. */
+export declare function isServiceTokenDenied(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.
+ */
+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.sub` was issued by `signServiceToken` (i.e. starts with `service:`). */
+export declare function isServicePrincipal(req: Request): boolean;
+/**
+ * PRE-auth check: cryptographically verify the request carries a valid, signed
+ * SERVICE token (`sub` starts with `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 verification (algorithm pinning + optional
+ * issuer/audience) and returns `false` on any missing/invalid/non-service token.
+ */
+export declare function verifyServicePrincipal(req: Request): boolean;