@pipeline-builder/api-core 4.1.13 → 4.1.14

package/lib/middleware/ecosystem-guard.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The plugin-ecosystem governance gate (docs/runbooks/ecosystem-moderation.md).
+ *
+ * Only the system org manages or approves the ecosystem. A route that exercises
+ * a system-org-only permission (`plugins:moderate`, `publishers:verify`) must
+ * therefore check three things, and {@link requireEcosystemPermission} composes
+ * them so no route can forget one:
+ *
+ *  1. {@link requireSystemOrg} — the caller's ACTIVE org is the system org. A
+ *     token minted in a tenant org is refused even for the same person (and even
+ *     for a superadmin: they switch to the system org to act on the ecosystem,
+ *     so every governance decision is recorded with the system org's id).
+ *  2. the permission itself (`requirePermission`, any-of);
+ *  3. an MFA-grade session (`requireAssurance({ minAssurance: 2 })`), which also
+ *     refuses every machine credential.
+ *
+ * The route-coverage governance check (`findSystemOrgGuardViolations` in
+ * `testing/route-coverage.ts`) fails any route that gates on a system-org-only
+ * permission without 1 and 3, so a hand-rolled chain cannot slip through.
+ */
+import type { NextFunction, Request, RequestHandler, Response } from 'express';
+import { type Permission } from '../types/permissions.js';
+/** Whether the request's ACTIVE org (the token's `organizationId`) is the system
+ *  org. Compared by id only — an org merely NAMED "system" never qualifies. */
+export declare function isSystemOrgRequest(req: Request): boolean;
+/**
+ * Require that the caller's active org is the system org. Compose after
+ * `requireAuth`. Refusals are 403 `SYSTEM_ORG_REQUIRED`, counted
+ * (`system_org_guard_refused_total`) and audited through the shared
+ * `authz.denied` sink (`required: 'system-org'`).
+ */
+export declare const requireSystemOrg: (req: Request, res: Response, next: NextFunction) => void;
+/**
+ * THE gate for an ecosystem-governance route: system org + (any of) the given
+ * system-org-only permission(s) + an MFA-grade human session. Returns the chain
+ * as an array, which Express flattens:
+ *
+ * ```ts
+ * router.post('/requests/:id/approve', requireAuth, requireEcosystemPermission('plugins:moderate'),
+ *   requireStepUp, audited('plugin.request.approve'), handler);
+ * ```
+ *
+ * Throws at route-definition time when handed a permission that is NOT
+ * system-org-only — a tenant permission behind this gate would be unreachable
+ * for every tenant, which is always a wiring mistake.
+ */
+export declare function requireEcosystemPermission(...permissions: Permission[]): RequestHandler[];

package/lib/middleware/ecosystem-guard.js

@@ -0,0 +1,60 @@
+// Copyright 2026 Pipeline Builder Contributors
+// SPDX-License-Identifier: Apache-2.0
+import { isSystemOrgId } from './system-org.js';
+import { recordAuthzDenial, requirePermission } from './permission-gates.js';
+import { requireAssurance } from './assurance.js';
+import { tagRouteGate } from './route-table.js';
+import { HttpStatus } from '../constants/http-status.js';
+import { ErrorCode } from '../types/error-codes.js';
+import { isSystemOrgOnlyPermission } from '../types/permissions.js';
+import { emitCounter } from '../utils/metric-emitter.js';
+import { sendError } from '../utils/response.js';
+/** Whether the request's ACTIVE org (the token's `organizationId`) is the system
+ *  org. Compared by id only — an org merely NAMED "system" never qualifies. */
+export function isSystemOrgRequest(req) {
+    return isSystemOrgId(req.user?.organizationId);
+}
+/**
+ * Require that the caller's active org is the system org. Compose after
+ * `requireAuth`. Refusals are 403 `SYSTEM_ORG_REQUIRED`, counted
+ * (`system_org_guard_refused_total`) and audited through the shared
+ * `authz.denied` sink (`required: 'system-org'`).
+ */
+export const requireSystemOrg = tagRouteGate(function requireSystemOrg(req, res, next) {
+    if (!req.user) {
+        return sendError(res, HttpStatus.UNAUTHORIZED, 'Authentication required', ErrorCode.UNAUTHORIZED);
+    }
+    if (isSystemOrgRequest(req))
+        return next();
+    emitCounter('system_org_guard_refused_total', { principal: req.user.principalType ?? 'unknown' });
+    recordAuthzDenial(req, 'system-org');
+    return sendError(res, HttpStatus.FORBIDDEN, 'This action is reserved for the system organization — switch to it to manage the plugin ecosystem', ErrorCode.SYSTEM_ORG_REQUIRED);
+}, { kind: 'systemOrg' });
+/**
+ * THE gate for an ecosystem-governance route: system org + (any of) the given
+ * system-org-only permission(s) + an MFA-grade human session. Returns the chain
+ * as an array, which Express flattens:
+ *
+ * ```ts
+ * router.post('/requests/:id/approve', requireAuth, requireEcosystemPermission('plugins:moderate'),
+ *   requireStepUp, audited('plugin.request.approve'), handler);
+ * ```
+ *
+ * Throws at route-definition time when handed a permission that is NOT
+ * system-org-only — a tenant permission behind this gate would be unreachable
+ * for every tenant, which is always a wiring mistake.
+ */
+export function requireEcosystemPermission(...permissions) {
+    if (permissions.length === 0)
+        throw new Error('requireEcosystemPermission needs at least one permission');
+    const tenant = permissions.filter((p) => !isSystemOrgOnlyPermission(p));
+    if (tenant.length > 0) {
+        throw new Error(`requireEcosystemPermission only takes system-org-only permissions; got ${tenant.join(', ')}`);
+    }
+    return [
+        requireSystemOrg,
+        requirePermission(...permissions),
+        requireAssurance({ minAssurance: 2 }),
+    ];
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZWNvc3lzdGVtLWd1YXJkLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL21pZGRsZXdhcmUvZWNvc3lzdGVtLWd1YXJkLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLCtDQUErQztBQUMvQyxzQ0FBc0M7QUF3QnRDLE9BQU8sRUFBRSxhQUFhLEVBQUUsTUFBTSxpQkFBaUIsQ0FBQztBQUNoRCxPQUFPLEVBQUUsaUJBQWlCLEVBQUUsaUJBQWlCLEVBQUUsTUFBTSx1QkFBdUIsQ0FBQztBQUM3RSxPQUFPLEVBQUUsZ0JBQWdCLEVBQUUsTUFBTSxnQkFBZ0IsQ0FBQztBQUNsRCxPQUFPLEVBQUUsWUFBWSxFQUFFLE1BQU0sa0JBQWtCLENBQUM7QUFDaEQsT0FBTyxFQUFFLFVBQVUsRUFBRSxNQUFNLDZCQUE2QixDQUFDO0FBQ3pELE9BQU8sRUFBRSxTQUFTLEVBQUUsTUFBTSx5QkFBeUIsQ0FBQztBQUNwRCxPQUFPLEVBQUUseUJBQXlCLEVBQW1CLE1BQU0seUJBQXlCLENBQUM7QUFDckYsT0FBTyxFQUFFLFdBQVcsRUFBRSxNQUFNLDRCQUE0QixDQUFDO0FBQ3pELE9BQU8sRUFBRSxTQUFTLEVBQUUsTUFBTSxzQkFBc0IsQ0FBQztBQUVqRDsrRUFDK0U7QUFDL0UsTUFBTSxVQUFVLGtCQUFrQixDQUFDLEdBQVk7SUFDN0MsT0FBTyxhQUFhLENBQUMsR0FBRyxDQUFDLElBQUksRUFBRSxjQUFjLENBQUMsQ0FBQztBQUNqRCxDQUFDO0FBRUQ7Ozs7O0dBS0c7QUFDSCxNQUFNLENBQUMsTUFBTSxnQkFBZ0IsR0FBRyxZQUFZLENBQUMsU0FBUyxnQkFBZ0IsQ0FBQyxHQUFZLEVBQUUsR0FBYSxFQUFFLElBQWtCO0lBQ3BILElBQUksQ0FBQyxHQUFHLENBQUMsSUFBSSxFQUFFLENBQUM7UUFDZCxPQUFPLFNBQVMsQ0FBQyxHQUFHLEVBQUUsVUFBVSxDQUFDLFlBQVksRUFBRSx5QkFBeUIsRUFBRSxTQUFTLENBQUMsWUFBWSxDQUFDLENBQUM7SUFDcEcsQ0FBQztJQUNELElBQUksa0JBQWtCLENBQUMsR0FBRyxDQUFDO1FBQUUsT0FBTyxJQUFJLEVBQUUsQ0FBQztJQUMzQyxXQUFXLENBQUMsZ0NBQWdDLEVBQUUsRUFBRSxTQUFTLEVBQUUsR0FBRyxDQUFDLElBQUksQ0FBQyxhQUFhLElBQUksU0FBUyxFQUFFLENBQUMsQ0FBQztJQUNsRyxpQkFBaUIsQ0FBQyxHQUFHLEVBQUUsWUFBWSxDQUFDLENBQUM7SUFDckMsT0FBTyxTQUFTLENBQ2QsR0FBRyxFQUFFLFVBQVUsQ0FBQyxTQUFTLEVBQ3pCLG1HQUFtRyxFQUNuRyxTQUFTLENBQUMsbUJBQW1CLENBQzlCLENBQUM7QUFDSixDQUFDLEVBQUUsRUFBRSxJQUFJLEVBQUUsV0FBVyxFQUFFLENBQUMsQ0FBQztBQUUxQjs7Ozs7Ozs7Ozs7OztHQWFHO0FBQ0gsTUFBTSxVQUFVLDBCQUEwQixDQUFDLEdBQUcsV0FBeUI7SUFDckUsSUFBSSxXQUFXLENBQUMsTUFBTSxLQUFLLENBQUM7UUFBRSxNQUFNLElBQUksS0FBSyxDQUFDLDBEQUEwRCxDQUFDLENBQUM7SUFDMUcsTUFBTSxNQUFNLEdBQUcsV0FBVyxDQUFDLE1BQU0sQ0FBQyxDQUFDLENBQUMsRUFBRSxFQUFFLENBQUMsQ0FBQyx5QkFBeUIsQ0FBQyxDQUFDLENBQUMsQ0FBQyxDQUFDO0lBQ3hFLElBQUksTUFBTSxDQUFDLE1BQU0sR0FBRyxDQUFDLEVBQUUsQ0FBQztRQUN0QixNQUFNLElBQUksS0FBSyxDQUFDLDBFQUEwRSxNQUFNLENBQUMsSUFBSSxDQUFDLElBQUksQ0FBQyxFQUFFLENBQUMsQ0FBQztJQUNqSCxDQUFDO0lBQ0QsT0FBTztRQUNMLGdCQUFnQjtRQUNoQixpQkFBaUIsQ0FBQyxHQUFHLFdBQVcsQ0FBQztRQUNqQyxnQkFBZ0IsQ0FBQyxFQUFFLFlBQVksRUFBRSxDQUFDLEVBQUUsQ0FBQztLQUNsQixDQUFDO0FBQ3hCLENBQUMiLCJzb3VyY2VzQ29udGVudCI6WyIvLyBDb3B5cmlnaHQgMjAyNiBQaXBlbGluZSBCdWlsZGVyIENvbnRyaWJ1dG9yc1xuLy8gU1BEWC1MaWNlbnNlLUlkZW50aWZpZXI6IEFwYWNoZS0yLjBcblxuLyoqXG4gKiBUaGUgcGx1Z2luLWVjb3N5c3RlbSBnb3Zlcm5hbmNlIGdhdGUgKGRvY3MvcnVuYm9va3MvZWNvc3lzdGVtLW1vZGVyYXRpb24ubWQpLlxuICpcbiAqIE9ubHkgdGhlIHN5c3RlbSBvcmcgbWFuYWdlcyBvciBhcHByb3ZlcyB0aGUgZWNvc3lzdGVtLiBBIHJvdXRlIHRoYXQgZXhlcmNpc2VzXG4gKiBhIHN5c3RlbS1vcmctb25seSBwZXJtaXNzaW9uIChgcGx1Z2luczptb2RlcmF0ZWAsIGBwdWJsaXNoZXJzOnZlcmlmeWApIG11c3RcbiAqIHRoZXJlZm9yZSBjaGVjayB0aHJlZSB0aGluZ3MsIGFuZCB7QGxpbmsgcmVxdWlyZUVjb3N5c3RlbVBlcm1pc3Npb259IGNvbXBvc2VzXG4gKiB0aGVtIHNvIG5vIHJvdXRlIGNhbiBmb3JnZXQgb25lOlxuICpcbiAqICAxLiB7QGxpbmsgcmVxdWlyZVN5c3RlbU9yZ30g4oCUIHRoZSBjYWxsZXIncyBBQ1RJVkUgb3JnIGlzIHRoZSBzeXN0ZW0gb3JnLiBBXG4gKiAgICAgdG9rZW4gbWludGVkIGluIGEgdGVuYW50IG9yZyBpcyByZWZ1c2VkIGV2ZW4gZm9yIHRoZSBzYW1lIHBlcnNvbiAoYW5kIGV2ZW5cbiAqICAgICBmb3IgYSBzdXBlcmFkbWluOiB0aGV5IHN3aXRjaCB0byB0aGUgc3lzdGVtIG9yZyB0byBhY3Qgb24gdGhlIGVjb3N5c3RlbSxcbiAqICAgICBzbyBldmVyeSBnb3Zlcm5hbmNlIGRlY2lzaW9uIGlzIHJlY29yZGVkIHdpdGggdGhlIHN5c3RlbSBvcmcncyBpZCkuXG4gKiAgMi4gdGhlIHBlcm1pc3Npb24gaXRzZWxmIChgcmVxdWlyZVBlcm1pc3Npb25gLCBhbnktb2YpO1xuICogIDMuIGFuIE1GQS1ncmFkZSBzZXNzaW9uIChgcmVxdWlyZUFzc3VyYW5jZSh7IG1pbkFzc3VyYW5jZTogMiB9KWApLCB3aGljaCBhbHNvXG4gKiAgICAgcmVmdXNlcyBldmVyeSBtYWNoaW5lIGNyZWRlbnRpYWwuXG4gKlxuICogVGhlIHJvdXRlLWNvdmVyYWdlIGdvdmVybmFuY2UgY2hlY2sgKGBmaW5kU3lzdGVtT3JnR3VhcmRWaW9sYXRpb25zYCBpblxuICogYHRlc3Rpbmcvcm91dGUtY292ZXJhZ2UudHNgKSBmYWlscyBhbnkgcm91dGUgdGhhdCBnYXRlcyBvbiBhIHN5c3RlbS1vcmctb25seVxuICogcGVybWlzc2lvbiB3aXRob3V0IDEgYW5kIDMsIHNvIGEgaGFuZC1yb2xsZWQgY2hhaW4gY2Fubm90IHNsaXAgdGhyb3VnaC5cbiAqL1xuXG5pbXBvcnQgdHlwZSB7IE5leHRGdW5jdGlvbiwgUmVxdWVzdCwgUmVxdWVzdEhhbmRsZXIsIFJlc3BvbnNlIH0gZnJvbSAnZXhwcmVzcyc7XG5pbXBvcnQgeyBpc1N5c3RlbU9yZ0lkIH0gZnJvbSAnLi9zeXN0ZW0tb3JnLmpzJztcbmltcG9ydCB7IHJlY29yZEF1dGh6RGVuaWFsLCByZXF1aXJlUGVybWlzc2lvbiB9IGZyb20gJy4vcGVybWlzc2lvbi1nYXRlcy5qcyc7XG5pbXBvcnQgeyByZXF1aXJlQXNzdXJhbmNlIH0gZnJvbSAnLi9hc3N1cmFuY2UuanMnO1xuaW1wb3J0IHsgdGFnUm91dGVHYXRlIH0gZnJvbSAnLi9yb3V0ZS10YWJsZS5qcyc7XG5pbXBvcnQgeyBIdHRwU3RhdHVzIH0gZnJvbSAnLi4vY29uc3RhbnRzL2h0dHAtc3RhdHVzLmpzJztcbmltcG9ydCB7IEVycm9yQ29kZSB9IGZyb20gJy4uL3R5cGVzL2Vycm9yLWNvZGVzLmpzJztcbmltcG9ydCB7IGlzU3lzdGVtT3JnT25seVBlcm1pc3Npb24sIHR5cGUgUGVybWlzc2lvbiB9IGZyb20gJy4uL3R5cGVzL3Blcm1pc3Npb25zLmpzJztcbmltcG9ydCB7IGVtaXRDb3VudGVyIH0gZnJvbSAnLi4vdXRpbHMvbWV0cmljLWVtaXR0ZXIuanMnO1xuaW1wb3J0IHsgc2VuZEVycm9yIH0gZnJvbSAnLi4vdXRpbHMvcmVzcG9uc2UuanMnO1xuXG4vKiogV2hldGhlciB0aGUgcmVxdWVzdCdzIEFDVElWRSBvcmcgKHRoZSB0b2tlbidzIGBvcmdhbml6YXRpb25JZGApIGlzIHRoZSBzeXN0ZW1cbiAqICBvcmcuIENvbXBhcmVkIGJ5IGlkIG9ubHkg4oCUIGFuIG9yZyBtZXJlbHkgTkFNRUQgXCJzeXN0ZW1cIiBuZXZlciBxdWFsaWZpZXMuICovXG5leHBvcnQgZnVuY3Rpb24gaXNTeXN0ZW1PcmdSZXF1ZXN0KHJlcTogUmVxdWVzdCk6IGJvb2xlYW4ge1xuICByZXR1cm4gaXNTeXN0ZW1PcmdJZChyZXEudXNlcj8ub3JnYW5pemF0aW9uSWQpO1xufVxuXG4vKipcbiAqIFJlcXVpcmUgdGhhdCB0aGUgY2FsbGVyJ3MgYWN0aXZlIG9yZyBpcyB0aGUgc3lzdGVtIG9yZy4gQ29tcG9zZSBhZnRlclxuICogYHJlcXVpcmVBdXRoYC4gUmVmdXNhbHMgYXJlIDQwMyBgU1lTVEVNX09SR19SRVFVSVJFRGAsIGNvdW50ZWRcbiAqIChgc3lzdGVtX29yZ19ndWFyZF9yZWZ1c2VkX3RvdGFsYCkgYW5kIGF1ZGl0ZWQgdGhyb3VnaCB0aGUgc2hhcmVkXG4gKiBgYXV0aHouZGVuaWVkYCBzaW5rIChgcmVxdWlyZWQ6ICdzeXN0ZW0tb3JnJ2ApLlxuICovXG5leHBvcnQgY29uc3QgcmVxdWlyZVN5c3RlbU9yZyA9IHRhZ1JvdXRlR2F0ZShmdW5jdGlvbiByZXF1aXJlU3lzdGVtT3JnKHJlcTogUmVxdWVzdCwgcmVzOiBSZXNwb25zZSwgbmV4dDogTmV4dEZ1bmN0aW9uKTogdm9pZCB7XG4gIGlmICghcmVxLnVzZXIpIHtcbiAgICByZXR1cm4gc2VuZEVycm9yKHJlcywgSHR0cFN0YXR1cy5VTkFVVEhPUklaRUQsICdBdXRoZW50aWNhdGlvbiByZXF1aXJlZCcsIEVycm9yQ29kZS5VTkFVVEhPUklaRUQpO1xuICB9XG4gIGlmIChpc1N5c3RlbU9yZ1JlcXVlc3QocmVxKSkgcmV0dXJuIG5leHQoKTtcbiAgZW1pdENvdW50ZXIoJ3N5c3RlbV9vcmdfZ3VhcmRfcmVmdXNlZF90b3RhbCcsIHsgcHJpbmNpcGFsOiByZXEudXNlci5wcmluY2lwYWxUeXBlID8/ICd1bmtub3duJyB9KTtcbiAgcmVjb3JkQXV0aHpEZW5pYWwocmVxLCAnc3lzdGVtLW9yZycpO1xuICByZXR1cm4gc2VuZEVycm9yKFxuICAgIHJlcywgSHR0cFN0YXR1cy5GT1JCSURERU4sXG4gICAgJ1RoaXMgYWN0aW9uIGlzIHJlc2VydmVkIGZvciB0aGUgc3lzdGVtIG9yZ2FuaXphdGlvbiDigJQgc3dpdGNoIHRvIGl0IHRvIG1hbmFnZSB0aGUgcGx1Z2luIGVjb3N5c3RlbScsXG4gICAgRXJyb3JDb2RlLlNZU1RFTV9PUkdfUkVRVUlSRUQsXG4gICk7XG59LCB7IGtpbmQ6ICdzeXN0ZW1PcmcnIH0pO1xuXG4vKipcbiAqIFRIRSBnYXRlIGZvciBhbiBlY29zeXN0ZW0tZ292ZXJuYW5jZSByb3V0ZTogc3lzdGVtIG9yZyArIChhbnkgb2YpIHRoZSBnaXZlblxuICogc3lzdGVtLW9yZy1vbmx5IHBlcm1pc3Npb24ocykgKyBhbiBNRkEtZ3JhZGUgaHVtYW4gc2Vzc2lvbi4gUmV0dXJucyB0aGUgY2hhaW5cbiAqIGFzIGFuIGFycmF5LCB3aGljaCBFeHByZXNzIGZsYXR0ZW5zOlxuICpcbiAqIGBgYHRzXG4gKiByb3V0ZXIucG9zdCgnL3JlcXVlc3RzLzppZC9hcHByb3ZlJywgcmVxdWlyZUF1dGgsIHJlcXVpcmVFY29zeXN0ZW1QZXJtaXNzaW9uKCdwbHVnaW5zOm1vZGVyYXRlJyksXG4gKiAgIHJlcXVpcmVTdGVwVXAsIGF1ZGl0ZWQoJ3BsdWdpbi5yZXF1ZXN0LmFwcHJvdmUnKSwgaGFuZGxlcik7XG4gKiBgYGBcbiAqXG4gKiBUaHJvd3MgYXQgcm91dGUtZGVmaW5pdGlvbiB0aW1lIHdoZW4gaGFuZGVkIGEgcGVybWlzc2lvbiB0aGF0IGlzIE5PVFxuICogc3lzdGVtLW9yZy1vbmx5IOKAlCBhIHRlbmFudCBwZXJtaXNzaW9uIGJlaGluZCB0aGlzIGdhdGUgd291bGQgYmUgdW5yZWFjaGFibGVcbiAqIGZvciBldmVyeSB0ZW5hbnQsIHdoaWNoIGlzIGFsd2F5cyBhIHdpcmluZyBtaXN0YWtlLlxuICovXG5leHBvcnQgZnVuY3Rpb24gcmVxdWlyZUVjb3N5c3RlbVBlcm1pc3Npb24oLi4ucGVybWlzc2lvbnM6IFBlcm1pc3Npb25bXSk6IFJlcXVlc3RIYW5kbGVyW10ge1xuICBpZiAocGVybWlzc2lvbnMubGVuZ3RoID09PSAwKSB0aHJvdyBuZXcgRXJyb3IoJ3JlcXVpcmVFY29zeXN0ZW1QZXJtaXNzaW9uIG5lZWRzIGF0IGxlYXN0IG9uZSBwZXJtaXNzaW9uJyk7XG4gIGNvbnN0IHRlbmFudCA9IHBlcm1pc3Npb25zLmZpbHRlcigocCkgPT4gIWlzU3lzdGVtT3JnT25seVBlcm1pc3Npb24ocCkpO1xuICBpZiAodGVuYW50Lmxlbmd0aCA+IDApIHtcbiAgICB0aHJvdyBuZXcgRXJyb3IoYHJlcXVpcmVFY29zeXN0ZW1QZXJtaXNzaW9uIG9ubHkgdGFrZXMgc3lzdGVtLW9yZy1vbmx5IHBlcm1pc3Npb25zOyBnb3QgJHt0ZW5hbnQuam9pbignLCAnKX1gKTtcbiAgfVxuICByZXR1cm4gW1xuICAgIHJlcXVpcmVTeXN0ZW1PcmcsXG4gICAgcmVxdWlyZVBlcm1pc3Npb24oLi4ucGVybWlzc2lvbnMpLFxuICAgIHJlcXVpcmVBc3N1cmFuY2UoeyBtaW5Bc3N1cmFuY2U6IDIgfSksXG4gIF0gYXMgUmVxdWVzdEhhbmRsZXJbXTtcbn1cbiJdfQ==

package/lib/middleware/index.d.ts

@@ -1,4 +1,11 @@
-export * from './auth.js';
-export * from './mongo-sanitize.js';
-export * from './step-up.js';
-export * from './route-table.js';
+export { verifyUserJwt, verifyBearerToken, hasValidIdentityClaims, } from './jwt-verify.js';
+export { requireAuth, } from './auth.js';
+export { setTokenRevocationStore, isAccessTokenRevoked, } from './revocation.js';
+export { requireAssurance, refuseWeakSession, refuseForOrgAdminAssurance, requireOrgAdminAssurance, type AssuranceOptions, } from './assurance.js';
+export { userHasPermission, setAuthzDenialAuditor, recordAuthzDenial, requirePermission, requireAllPermissions, requirePermissionOrService, requireServicePrincipal, requireInternalService, isSystemAdmin, hasScope, requireSystemAdmin, requireFeature, type AuthzDenialInfo, } from './permission-gates.js';
+export { isSystemOrgId, SYSTEM_ORG_ID, SYSTEM_ORG_SLUG, } from './system-org.js';
+export { serviceNameOf, isServiceTokenDenied, signServiceToken, getServiceAuthHeader, isServicePrincipal, isServiceAccountPrincipal, isServicePrincipalNamed, verifyServicePrincipal, } from './service-tokens.js';
+export { requireSystemOrg, requireEcosystemPermission } from './ecosystem-guard.js';
+export { mongoSanitize, MAX_SANITIZE_DEPTH, } from './mongo-sanitize.js';
+export { requireStepUp, type StepUpMethod, STRONG_STEP_UP_METHODS, } from './step-up.js';
+export { tagRouteGate, getRouteGates, audited, buildRouteTable, isWriteMethod, summarizeRouteTable, type RouteTableEntry, } from './route-table.js';

package/lib/middleware/index.js

@@ -1,7 +1,14 @@
 // Copyright 2026 Pipeline Builder Contributors
 // SPDX-License-Identifier: Apache-2.0
-export * from './auth.js';
-export * from './mongo-sanitize.js';
-export * from './step-up.js';
-export * from './route-table.js';
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvbWlkZGxld2FyZS9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSwrQ0FBK0M7QUFDL0Msc0NBQXNDO0FBRXRDLGNBQWMsV0FBVyxDQUFDO0FBQzFCLGNBQWMscUJBQXFCLENBQUM7QUFDcEMsY0FBYyxjQUFjLENBQUM7QUFDN0IsY0FBYyxrQkFBa0IsQ0FBQyIsInNvdXJjZXNDb250ZW50IjpbIi8vIENvcHlyaWdodCAyMDI2IFBpcGVsaW5lIEJ1aWxkZXIgQ29udHJpYnV0b3JzXG4vLyBTUERYLUxpY2Vuc2UtSWRlbnRpZmllcjogQXBhY2hlLTIuMFxuXG5leHBvcnQgKiBmcm9tICcuL2F1dGguanMnO1xuZXhwb3J0ICogZnJvbSAnLi9tb25nby1zYW5pdGl6ZS5qcyc7XG5leHBvcnQgKiBmcm9tICcuL3N0ZXAtdXAuanMnO1xuZXhwb3J0ICogZnJvbSAnLi9yb3V0ZS10YWJsZS5qcyc7XG4iXX0=
+export { verifyUserJwt, verifyBearerToken, hasValidIdentityClaims, } from './jwt-verify.js';
+export { requireAuth, } from './auth.js';
+export { setTokenRevocationStore, isAccessTokenRevoked, } from './revocation.js';
+export { requireAssurance, refuseWeakSession, refuseForOrgAdminAssurance, requireOrgAdminAssurance, } from './assurance.js';
+export { userHasPermission, setAuthzDenialAuditor, recordAuthzDenial, requirePermission, requireAllPermissions, requirePermissionOrService, requireServicePrincipal, requireInternalService, isSystemAdmin, hasScope, requireSystemAdmin, requireFeature, } from './permission-gates.js';
+export { isSystemOrgId, SYSTEM_ORG_ID, SYSTEM_ORG_SLUG, } from './system-org.js';
+export { serviceNameOf, isServiceTokenDenied, signServiceToken, getServiceAuthHeader, isServicePrincipal, isServiceAccountPrincipal, isServicePrincipalNamed, verifyServicePrincipal, } from './service-tokens.js';
+export { requireSystemOrg, requireEcosystemPermission } from './ecosystem-guard.js';
+export { mongoSanitize, MAX_SANITIZE_DEPTH, } from './mongo-sanitize.js';
+export { requireStepUp, STRONG_STEP_UP_METHODS, } from './step-up.js';
+export { tagRouteGate, getRouteGates, audited, buildRouteTable, isWriteMethod, summarizeRouteTable, } from './route-table.js';
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvbWlkZGxld2FyZS9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSwrQ0FBK0M7QUFDL0Msc0NBQXNDO0FBRXRDLE9BQU8sRUFDTCxhQUFhLEVBQ2IsaUJBQWlCLEVBQ2pCLHNCQUFzQixHQUN2QixNQUFNLGlCQUFpQixDQUFDO0FBQ3pCLE9BQU8sRUFDTCxXQUFXLEdBQ1osTUFBTSxXQUFXLENBQUM7QUFDbkIsT0FBTyxFQUNMLHVCQUF1QixFQUN2QixvQkFBb0IsR0FDckIsTUFBTSxpQkFBaUIsQ0FBQztBQUN6QixPQUFPLEVBQ0wsZ0JBQWdCLEVBQ2hCLGlCQUFpQixFQUNqQiwwQkFBMEIsRUFDMUIsd0JBQXdCLEdBRXpCLE1BQU0sZ0JBQWdCLENBQUM7QUFDeEIsT0FBTyxFQUNMLGlCQUFpQixFQUNqQixxQkFBcUIsRUFDckIsaUJBQWlCLEVBQ2pCLGlCQUFpQixFQUNqQixxQkFBcUIsRUFDckIsMEJBQTBCLEVBQzFCLHVCQUF1QixFQUN2QixzQkFBc0IsRUFDdEIsYUFBYSxFQUNiLFFBQVEsRUFDUixrQkFBa0IsRUFDbEIsY0FBYyxHQUVmLE1BQU0sdUJBQXVCLENBQUM7QUFDL0IsT0FBTyxFQUNMLGFBQWEsRUFDYixhQUFhLEVBQ2IsZUFBZSxHQUNoQixNQUFNLGlCQUFpQixDQUFDO0FBQ3pCLE9BQU8sRUFDTCxhQUFhLEVBQ2Isb0JBQW9CLEVBQ3BCLGdCQUFnQixFQUNoQixvQkFBb0IsRUFDcEIsa0JBQWtCLEVBQ2xCLHlCQUF5QixFQUN6Qix1QkFBdUIsRUFDdkIsc0JBQXNCLEdBQ3ZCLE1BQU0scUJBQXFCLENBQUM7QUFDN0IsT0FBTyxFQUFFLGdCQUFnQixFQUFFLDBCQUEwQixFQUFFLE1BQU0sc0JBQXNCLENBQUM7QUFDcEYsT0FBTyxFQUNMLGFBQWEsRUFDYixrQkFBa0IsR0FDbkIsTUFBTSxxQkFBcUIsQ0FBQztBQUM3QixPQUFPLEVBQ0wsYUFBYSxFQUViLHNCQUFzQixHQUN2QixNQUFNLGNBQWMsQ0FBQztBQUN0QixPQUFPLEVBQ0wsWUFBWSxFQUNaLGFBQWEsRUFDYixPQUFPLEVBQ1AsZUFBZSxFQUNmLGFBQWEsRUFDYixtQkFBbUIsR0FFcEIsTUFBTSxrQkFBa0IsQ0FBQyIsInNvdXJjZXNDb250ZW50IjpbIi8vIENvcHlyaWdodCAyMDI2IFBpcGVsaW5lIEJ1aWxkZXIgQ29udHJpYnV0b3JzXG4vLyBTUERYLUxpY2Vuc2UtSWRlbnRpZmllcjogQXBhY2hlLTIuMFxuXG5leHBvcnQge1xuICB2ZXJpZnlVc2VySnd0LFxuICB2ZXJpZnlCZWFyZXJUb2tlbixcbiAgaGFzVmFsaWRJZGVudGl0eUNsYWltcyxcbn0gZnJvbSAnLi9qd3QtdmVyaWZ5LmpzJztcbmV4cG9ydCB7XG4gIHJlcXVpcmVBdXRoLFxufSBmcm9tICcuL2F1dGguanMnO1xuZXhwb3J0IHtcbiAgc2V0VG9rZW5SZXZvY2F0aW9uU3RvcmUsXG4gIGlzQWNjZXNzVG9rZW5SZXZva2VkLFxufSBmcm9tICcuL3Jldm9jYXRpb24uanMnO1xuZXhwb3J0IHtcbiAgcmVxdWlyZUFzc3VyYW5jZSxcbiAgcmVmdXNlV2Vha1Nlc3Npb24sXG4gIHJlZnVzZUZvck9yZ0FkbWluQXNzdXJhbmNlLFxuICByZXF1aXJlT3JnQWRtaW5Bc3N1cmFuY2UsXG4gIHR5cGUgQXNzdXJhbmNlT3B0aW9ucyxcbn0gZnJvbSAnLi9hc3N1cmFuY2UuanMnO1xuZXhwb3J0IHtcbiAgdXNlckhhc1Blcm1pc3Npb24sXG4gIHNldEF1dGh6RGVuaWFsQXVkaXRvcixcbiAgcmVjb3JkQXV0aHpEZW5pYWwsXG4gIHJlcXVpcmVQZXJtaXNzaW9uLFxuICByZXF1aXJlQWxsUGVybWlzc2lvbnMsXG4gIHJlcXVpcmVQZXJtaXNzaW9uT3JTZXJ2aWNlLFxuICByZXF1aXJlU2VydmljZVByaW5jaXBhbCxcbiAgcmVxdWlyZUludGVybmFsU2VydmljZSxcbiAgaXNTeXN0ZW1BZG1pbixcbiAgaGFzU2NvcGUsXG4gIHJlcXVpcmVTeXN0ZW1BZG1pbixcbiAgcmVxdWlyZUZlYXR1cmUsXG4gIHR5cGUgQXV0aHpEZW5pYWxJbmZvLFxufSBmcm9tICcuL3Blcm1pc3Npb24tZ2F0ZXMuanMnO1xuZXhwb3J0IHtcbiAgaXNTeXN0ZW1PcmdJZCxcbiAgU1lTVEVNX09SR19JRCxcbiAgU1lTVEVNX09SR19TTFVHLFxufSBmcm9tICcuL3N5c3RlbS1vcmcuanMnO1xuZXhwb3J0IHtcbiAgc2VydmljZU5hbWVPZixcbiAgaXNTZXJ2aWNlVG9rZW5EZW5pZWQsXG4gIHNpZ25TZXJ2aWNlVG9rZW4sXG4gIGdldFNlcnZpY2VBdXRoSGVhZGVyLFxuICBpc1NlcnZpY2VQcmluY2lwYWwsXG4gIGlzU2VydmljZUFjY291bnRQcmluY2lwYWwsXG4gIGlzU2VydmljZVByaW5jaXBhbE5hbWVkLFxuICB2ZXJpZnlTZXJ2aWNlUHJpbmNpcGFsLFxufSBmcm9tICcuL3NlcnZpY2UtdG9rZW5zLmpzJztcbmV4cG9ydCB7IHJlcXVpcmVTeXN0ZW1PcmcsIHJlcXVpcmVFY29zeXN0ZW1QZXJtaXNzaW9uIH0gZnJvbSAnLi9lY29zeXN0ZW0tZ3VhcmQuanMnO1xuZXhwb3J0IHtcbiAgbW9uZ29TYW5pdGl6ZSxcbiAgTUFYX1NBTklUSVpFX0RFUFRILFxufSBmcm9tICcuL21vbmdvLXNhbml0aXplLmpzJztcbmV4cG9ydCB7XG4gIHJlcXVpcmVTdGVwVXAsXG4gIHR5cGUgU3RlcFVwTWV0aG9kLFxuICBTVFJPTkdfU1RFUF9VUF9NRVRIT0RTLFxufSBmcm9tICcuL3N0ZXAtdXAuanMnO1xuZXhwb3J0IHtcbiAgdGFnUm91dGVHYXRlLFxuICBnZXRSb3V0ZUdhdGVzLFxuICBhdWRpdGVkLFxuICBidWlsZFJvdXRlVGFibGUsXG4gIGlzV3JpdGVNZXRob2QsXG4gIHN1bW1hcml6ZVJvdXRlVGFibGUsXG4gIHR5cGUgUm91dGVUYWJsZUVudHJ5LFxufSBmcm9tICcuL3JvdXRlLXRhYmxlLmpzJztcbiJdfQ==

package/lib/middleware/jwt-verify.d.ts

@@ -0,0 +1,52 @@
+import { type JwtPayload } from '../types/common.js';
+/** Issuer/audience pinning, when the deployment configures them. Shared by both chains. */
+export declare function issuerAudienceOptions(): {
+    issuer?: string;
+    audience?: string;
+};
+/**
+ * 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.
+ */
+export declare function verifyBearerToken(token: string): Promise<JwtPayload>;
+/**
+ * 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;

package/lib/middleware/jwt-verify.js

@@ -0,0 +1,105 @@
+// Copyright 2026 Pipeline Builder Contributors
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Bearer-token verification: the user chain (ES256 against platform's JWKS) and
+ * the identity-claim shape every gate reasons about.
+ */
+import jwt from 'jsonwebtoken';
+import { platformJwksCache } from '../services/jwks-cache.js';
+import { SERVICE_SUBJECT_PREFIX, isServiceKid, verifyServiceJwt } from '../services/service-keys.js';
+import { AUTH_METHODS, PRINCIPAL_TYPES, TOKEN_USES } from '../types/common.js';
+import { USER_TOKEN_ALGORITHM, decodeJwtHeader } from '../utils/jwk.js';
+import { emitCounter } from '../utils/metric-emitter.js';
+/** Issuer/audience pinning, when the deployment configures them. Shared by both chains. */
+export function issuerAudienceOptions() {
+    return {
+        ...(process.env.JWT_ISSUER ? { issuer: process.env.JWT_ISSUER } : {}),
+        ...(process.env.JWT_AUDIENCE ? { audience: process.env.JWT_AUDIENCE } : {}),
+    };
+}
+/**
+ * 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 async function verifyUserJwt(token) {
+    const header = decodeJwtHeader(token);
+    if (header?.alg !== USER_TOKEN_ALGORITHM || !header.kid) {
+        throw new jwt.JsonWebTokenError(`User tokens must be signed with ${USER_TOKEN_ALGORITHM} and carry a kid`);
+    }
+    const key = await platformJwksCache().getKey(header.kid);
+    return jwt.verify(token, key, { algorithms: [USER_TOKEN_ALGORITHM], ...issuerAudienceOptions() });
+}
+/**
+ * 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.
+ */
+export async function verifyBearerToken(token) {
+    const header = decodeJwtHeader(token);
+    if (!header?.alg)
+        throw new jwt.JsonWebTokenError('Malformed token header');
+    if (header.kid && isServiceKid(header.kid)) {
+        const claims = verifyServiceJwt(token, { kid: header.kid, ...issuerAudienceOptions() });
+        if (claims.principalType !== 'service') {
+            emitCounter('service_key_non_service_token_rejected_total', { alg: header.alg });
+            throw new jwt.JsonWebTokenError('A service signing key may only mint a service principal');
+        }
+        return claims;
+    }
+    const claims = await verifyUserJwt(token);
+    if (claims.principalType === 'service') {
+        throw new jwt.JsonWebTokenError('Service principals may not be signed with the user signing key');
+    }
+    return claims;
+}
+/**
+ * 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 function hasValidIdentityClaims(decoded) {
+    if (!decoded.principalType || !PRINCIPAL_TYPES.includes(decoded.principalType))
+        return false;
+    if (!decoded.token_use || !TOKEN_USES.includes(decoded.token_use))
+        return false;
+    if (decoded.principalType === 'service') {
+        return decoded.token_use === 'access'
+            && typeof decoded.sub === 'string'
+            && decoded.sub.startsWith(SERVICE_SUBJECT_PREFIX)
+            && decoded.sub.length > SERVICE_SUBJECT_PREFIX.length;
+    }
+    return Array.isArray(decoded.amr)
+        && decoded.amr.every((m) => AUTH_METHODS.includes(m))
+        && (decoded.aal === 1 || decoded.aal === 2)
+        && typeof decoded.auth_time === 'number';
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiand0LXZlcmlmeS5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9taWRkbGV3YXJlL2p3dC12ZXJpZnkudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsK0NBQStDO0FBQy9DLHNDQUFzQztBQUV0Qzs7O0dBR0c7QUFFSCxPQUFPLEdBQUcsTUFBTSxjQUFjLENBQUM7QUFDL0IsT0FBTyxFQUFFLGlCQUFpQixFQUFFLE1BQU0sMkJBQTJCLENBQUM7QUFDOUQsT0FBTyxFQUFFLHNCQUFzQixFQUFFLFlBQVksRUFBRSxnQkFBZ0IsRUFBRSxNQUFNLDZCQUE2QixDQUFDO0FBQ3JHLE9BQU8sRUFBRSxZQUFZLEVBQUUsZUFBZSxFQUFFLFVBQVUsRUFBbUIsTUFBTSxvQkFBb0IsQ0FBQztBQUNoRyxPQUFPLEVBQUUsb0JBQW9CLEVBQUUsZUFBZSxFQUFFLE1BQU0saUJBQWlCLENBQUM7QUFDeEUsT0FBTyxFQUFFLFdBQVcsRUFBRSxNQUFNLDRCQUE0QixDQUFDO0FBQ3pELDJGQUEyRjtBQUMzRixNQUFNLFVBQVUscUJBQXFCO0lBQ25DLE9BQU87UUFDTCxHQUFHLENBQUMsT0FBTyxDQUFDLEdBQUcsQ0FBQyxVQUFVLENBQUMsQ0FBQyxDQUFDLEVBQUUsTUFBTSxFQUFFLE9BQU8sQ0FBQyxHQUFHLENBQUMsVUFBVSxFQUFFLENBQUMsQ0FBQyxDQUFDLEVBQUUsQ0FBQztRQUNyRSxHQUFHLENBQUMsT0FBTyxDQUFDLEdBQUcsQ0FBQyxZQUFZLENBQUMsQ0FBQyxDQUFDLEVBQUUsUUFBUSxFQUFFLE9BQU8sQ0FBQyxHQUFHLENBQUMsWUFBWSxFQUFFLENBQUMsQ0FBQyxDQUFDLEVBQUUsQ0FBQztLQUM1RSxDQUFDO0FBQ0osQ0FBQztBQUVEOzs7Ozs7Ozs7Ozs7OztHQWNHO0FBQ0gsTUFBTSxDQUFDLEtBQUssVUFBVSxhQUFhLENBQWlCLEtBQWE7SUFDL0QsTUFBTSxNQUFNLEdBQUcsZUFBZSxDQUFDLEtBQUssQ0FBQyxDQUFDO0lBQ3RD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LEdBQUcsS0FBSyxDQUFDLElBQUksT0FBTyxDQUFDLEdBQUcsS0FBSyxDQUFDLENBQUM7V0FDeEMsT0FBTyxPQUFPLENBQUMsU0FBUyxLQUFLLFFBQVEsQ0FBQztBQUM3QyxDQUFDIiwic291cmNlc0NvbnRlbnQiOlsiLy8gQ29weXJpZ2h0IDIwMjYgUGlwZWxpbmUgQnVpbGRlciBDb250cmlidXRvcnNcbi8vIFNQRFgtTGljZW5zZS1JZGVudGlmaWVyOiBBcGFjaGUtMi4wXG5cbi8qKlxuICogQmVhcmVyLXRva2VuIHZlcmlmaWNhdGlvbjogdGhlIHVzZXIgY2hhaW4gKEVTMjU2IGFnYWluc3QgcGxhdGZvcm0ncyBKV0tTKSBhbmRcbiAqIHRoZSBpZGVudGl0eS1jbGFpbSBzaGFwZSBldmVyeSBnYXRlIHJlYXNvbnMgYWJvdXQuXG4gKi9cblxuaW1wb3J0IGp3dCBmcm9tICdqc29ud2VidG9rZW4nO1xuaW1wb3J0IHsgcGxhdGZvcm1Kd2tzQ2FjaGUgfSBmcm9tICcuLi9zZXJ2aWNlcy9qd2tzLWNhY2hlLmpzJztcbmltcG9ydCB7IFNFUlZJQ0VfU1VCSkVDVF9QUkVGSVgsIGlzU2VydmljZUtpZCwgdmVyaWZ5U2VydmljZUp3dCB9IGZyb20gJy4uL3NlcnZpY2VzL3NlcnZpY2Uta2V5cy5qcyc7XG5pbXBvcnQgeyBBVVRIX01FVEhPRFMsIFBSSU5DSVBBTF9UWVBFUywgVE9LRU5fVVNFUywgdHlwZSBKd3RQYXlsb2FkIH0gZnJvbSAnLi4vdHlwZXMvY29tbW9uLmpzJztcbmltcG9ydCB7IFVTRVJfVE9LRU5fQUxHT1JJVEhNLCBkZWNvZGVKd3RIZWFkZXIgfSBmcm9tICcuLi91dGlscy9qd2suanMnO1xuaW1wb3J0IHsgZW1pdENvdW50ZXIgfSBmcm9tICcuLi91dGlscy9tZXRyaWMtZW1pdHRlci5qcyc7XG4vKiogSXNzdWVyL2F1ZGllbmNlIHBpbm5pbmcsIHdoZW4gdGhlIGRlcGxveW1lbnQgY29uZmlndXJlcyB0aGVtLiBTaGFyZWQgYnkgYm90aCBjaGFpbnMuICovXG5leHBvcnQgZnVuY3Rpb24gaXNzdWVyQXVkaWVuY2VPcHRpb25zKCk6IHsgaXNzdWVyPzogc3RyaW5nOyBhdWRpZW5jZT86IHN0cmluZyB9IHtcbiAgcmV0dXJuIHtcbiAgICAuLi4ocHJvY2Vzcy5lbnYuSldUX0lTU1VFUiA/IHsgaXNzdWVyOiBwcm9jZXNzLmVudi5KV1RfSVNTVUVSIH0gOiB7fSksXG4gICAgLi4uKHByb2Nlc3MuZW52LkpXVF9BVURJRU5DRSA/IHsgYXVkaWVuY2U6IHByb2Nlc3MuZW52LkpXVF9BVURJRU5DRSB9IDoge30pLFxuICB9O1xufVxuXG4vKipcbiAqIFZlcmlmeSBhIHRva2VuIHRoYXQgc3BlYWtzIGZvciBhIFBFUlNPTiDigJQgYWNjZXNzLCBzdGVwLXVwLCBhbmQgdGhlIHRva2VuIGFuXG4gKiBvcGFxdWUgYWNjZXNzIGtleSBpcyBleGNoYW5nZWQgZm9yIOKAlCBhZ2FpbnN0IHBsYXRmb3JtJ3MgcHVibGlzaGVkIHNpZ25pbmdcbiAqIGtleXMuXG4gKlxuICogRVMyNTYgYW5kIGEgYGtpZGAgYXJlIGJvdGggbWFuZGF0b3J5OiBubyBga2lkYCBtZWFucyBubyB3YXkgdG8gcGljayB0aGUgcmlnaHRcbiAqIGtleSBhY3Jvc3MgYSByb3RhdGlvbiwgYW5kIGFueSBvdGhlciBhbGdvcml0aG0gaXMgcmVmdXNlZCBvdXRyaWdodCwgd2hpY2ggaXNcbiAqIHdoYXQgbWFrZXMgXCJubyBzZXJ2aWNlIGFjY2VwdHMgYW4gSFMyNTYgdXNlciB0b2tlblwiIGEgcHJvcGVydHkgb2YgdGhlIGNvZGVcbiAqIHJhdGhlciB0aGFuIGEgY29udmVudGlvbi4gS2V5IGxvb2t1cCBnb2VzIHRocm91Z2ggdGhlIHNoYXJlZCBKV0tTIGNhY2hlXG4gKiAoMTAtbWludXRlIHJlZnJlc2gsIG9uZSByZWZldGNoIG9uIGFuIHVua25vd24gYGtpZGAsIGJyaWVmIG5lZ2F0aXZlIGNhY2hlKS5cbiAqXG4gKiBAdGhyb3dzIHtVbmtub3duS2lkRXJyb3J9IHRoZSBrZXkgc2V0IGlzIGN1cnJlbnQgYW5kIGhhcyBubyBzdWNoIGtleSDihpIgNDAxLlxuICogQHRocm93cyB7Sndrc1VuYXZhaWxhYmxlRXJyb3J9IHRoZSBrZXkgc2V0IGNvdWxkIG5vdCBiZSBvYnRhaW5lZCDihpIgNTAzOyBhblxuICogICAgICAgICB1bnZlcmlmaWFibGUgdG9rZW4gaXMgbmV2ZXIgdHJlYXRlZCBhcyB2YWxpZC5cbiAqL1xuZXhwb3J0IGFzeW5jIGZ1bmN0aW9uIHZlcmlmeVVzZXJKd3Q8VCA9IEp3dFBheWxvYWQ+KHRva2VuOiBzdHJpbmcpOiBQcm9taXNlPFQ+IHtcbiAgY29uc3QgaGVhZGVyID0gZGVjb2RlSnd0SGVhZGVyKHRva2VuKTtcbiAgaWYgKGhlYWRlcj8uYWxnICE9PSBVU0VSX1RPS0VOX0FMR09SSVRITSB8fCAhaGVhZGVyLmtpZCkge1xuICAgIHRocm93IG5ldyBqd3QuSnNvbldlYlRva2VuRXJyb3IoYFVzZXIgdG9rZW5zIG11c3QgYmUgc2lnbmVkIHdpdGggJHtVU0VSX1RPS0VOX0FMR09SSVRITX0gYW5kIGNhcnJ5IGEga2lkYCk7XG4gIH1cbiAgY29uc3Qga2V5ID0gYXdhaXQgcGxhdGZvcm1Kd2tzQ2FjaGUoKS5nZXRLZXkoaGVhZGVyLmtpZCk7XG4gIHJldHVybiBqd3QudmVyaWZ5KHRva2VuLCBrZXksIHsgYWxnb3JpdGhtczogW1VTRVJfVE9LRU5fQUxHT1JJVEhNXSwgLi4uaXNzdWVyQXVkaWVuY2VPcHRpb25zKCkgfSkgYXMgVDtcbn1cblxuLyoqXG4gKiBWZXJpZnkgQU5ZIGJlYXJlciB0b2tlbiBhbmQgcmV0dXJuIGl0cyBjbGFpbXMuXG4gKlxuICogU2luY2UgIzE0IHRoZXJlIGlzIG5vIHNoYXJlZCBzZWNyZXQgbGVmdDogQk9USCBjaGFpbnMgYXJlIEVTMjU2IHdpdGggYSBga2lkYCxcbiAqIHNvIHRoZSBkaXNwYXRjaCBpcyBieSAqKndobyBvd25zIHRoZSBga2lkYCoqIHJhdGhlciB0aGFuIGJ5IGFsZ29yaXRobSDigJQgYW5kXG4gKiBiZWNhdXNlIGEgYGtpZGAgaXMgYW4gUkZDIDc2MzggdGh1bWJwcmludCwgb3duZXJzaGlwIGlzIGEgZmFjdCBhYm91dCB0aGUga2V5LFxuICogbm90IGEgY2xhaW0gdGhlIHRva2VuIG1ha2VzIGFib3V0IGl0c2VsZjpcbiAqXG4gKiAtIGEgYGtpZGAgcHVibGlzaGVkIGluIHRoZSBwZXItc2VydmljZSBrZXkgYnVuZGxlIOKGkiBhbiBJTlRFUk5BTCBTRVJWSUNFIHRva2VuXG4gKiAgICh7QGxpbmsgc2lnblNlcnZpY2VUb2tlbn0pLCB2ZXJpZmllZCB3aXRoIHRoYXQgc2VydmljZSdzIGtleTsgaXRzIGBzdWJgIG11c3RcbiAqICAgbmFtZSB0aGUgc2FtZSBzZXJ2aWNlLCBzbyBvbmUgc2VydmljZSBjYW4gbmV2ZXIgc3BlYWsgZm9yIGFub3RoZXIuXG4gKiAtIGFueXRoaW5nIGVsc2Ug4oaSIGEgcGxhdGZvcm0tc2lnbmVkIFVTRVIgdG9rZW4sIHZlcmlmaWVkIGFnYWluc3QgcGxhdGZvcm0nc1xuICogICBwdWJsaXNoZWQgSldLUy4gQSB0b2tlbiBjbGFpbWluZyBgcHJpbmNpcGFsVHlwZTogJ3NlcnZpY2UnYCBpcyByZWZ1c2VkXG4gKiAgIGhlcmU6IGFuIGludGVybmFsIGlkZW50aXR5IG1heSBub3QgcmlkZSB0aGUgdXNlciBzaWduaW5nIGtleS5cbiAqXG4gKiBBbnl0aGluZyB0aGF0IGlzIG5vdCBFUzI1NiB3aXRoIGEgYGtpZGAgZmFpbHMgaW4gYm90aCBjaGFpbnMsIHdoaWNoIGlzIHdoYXRcbiAqIG1ha2VzIFwibm8gSFMyNTYgdG9rZW4gaXMgYWNjZXB0ZWQgYW55d2hlcmVcIiBhIHByb3BlcnR5IG9mIHRoZSBjb2RlLlxuICovXG5leHBvcnQgYXN5bmMgZnVuY3Rpb24gdmVyaWZ5QmVhcmVyVG9rZW4odG9rZW46IHN0cmluZyk6IFByb21pc2U8Snd0UGF5bG9hZD4ge1xuICBjb25zdCBoZWFkZXIgPSBkZWNvZGVKd3RIZWFkZXIodG9rZW4pO1xuICBpZiAoIWhlYWRlcj8uYWxnKSB0aHJvdyBuZXcgand0Lkpzb25XZWJUb2tlbkVycm9yKCdNYWxmb3JtZWQgdG9rZW4gaGVhZGVyJyk7XG5cbiAgaWYgKGhlYWRlci5raWQgJiYgaXNTZXJ2aWNlS2lkKGhlYWRlci5raWQpKSB7XG4gICAgY29uc3QgY2xhaW1zID0gdmVyaWZ5U2VydmljZUp3dDxKd3RQYXlsb2FkPih0b2tlbiwgeyBraWQ6IGhlYWRlci5raWQsIC4uLmlzc3VlckF1ZGllbmNlT3B0aW9ucygpIH0pO1xuICAgIGlmIChjbGFpbXMucHJpbmNpcGFsVHlwZSAhPT0gJ3NlcnZpY2UnKSB7XG4gICAgICBlbWl0Q291bnRlcignc2VydmljZV9rZXlfbm9uX3NlcnZpY2VfdG9rZW5fcmVqZWN0ZWRfdG90YWwnLCB7IGFsZzogaGVhZGVyLmFsZyB9KTtcbiAgICAgIHRocm93IG5ldyBqd3QuSnNvbldlYlRva2VuRXJyb3IoJ0Egc2VydmljZSBzaWduaW5nIGtleSBtYXkgb25seSBtaW50IGEgc2VydmljZSBwcmluY2lwYWwnKTtcbiAgICB9XG4gICAgcmV0dXJuIGNsYWltcztcbiAgfVxuXG4gIGNvbnN0IGNsYWltcyA9IGF3YWl0IHZlcmlmeVVzZXJKd3QodG9rZW4pO1xuICBpZiAoY2xhaW1zLnByaW5jaXBhbFR5cGUgPT09ICdzZXJ2aWNlJykge1xuICAgIHRocm93IG5ldyBqd3QuSnNvbldlYlRva2VuRXJyb3IoJ1NlcnZpY2UgcHJpbmNpcGFscyBtYXkgbm90IGJlIHNpZ25lZCB3aXRoIHRoZSB1c2VyIHNpZ25pbmcga2V5Jyk7XG4gIH1cbiAgcmV0dXJuIGNsYWltcztcbn1cblxuLyoqXG4gKiBXaGV0aGVyIGEgdmVyaWZpZWQgdG9rZW4gY2FycmllcyBhIHdlbGwtZm9ybWVkIGlkZW50aXR5OiBhIGtub3duXG4gKiBgcHJpbmNpcGFsVHlwZWAgYW5kIGB0b2tlbl91c2VgLCBhbmQgdGhlIGNsYWltcyB0aGF0IGtpbmQgb2YgcHJpbmNpcGFsIG11c3RcbiAqIGhhdmUuIEZhaWxzIGNsb3NlZCDigJQgYSB0b2tlbiBtaW50ZWQgYmVmb3JlIHRoZXNlIGNsYWltcyBleGlzdGVkLCBvciBvbmUgd2l0aCBhXG4gKiBjb250cmFkaWN0b3J5IGNvbWJpbmF0aW9uLCBpcyBub3QgYW4gaWRlbnRpdHkgYW55IGdhdGUgc2hvdWxkIHJlYXNvbiBhYm91dC5cbiAqXG4gKiAtIGBzZXJ2aWNlYDogYHRva2VuX3VzZTogJ2FjY2VzcydgIGFuZCBhIGBzZXJ2aWNlOjxuYW1lPmAgc3ViamVjdCAodGhlIG5hbWVcbiAqICAgZmVlZHMgdGhlIGRlbnlsaXN0IGFuZCBhdWRpdCBhdHRyaWJ1dGlvbikuXG4gKiAtIGB1c2VyYCAvIGBzZXJ2aWNlX2FjY291bnRgOiBgYW1yYCAoa25vd24gbWV0aG9kcyksIGBhYWxgIGFuZCBgYXV0aF90aW1lYC5cbiAqL1xuZXhwb3J0IGZ1bmN0aW9uIGhhc1ZhbGlkSWRlbnRpdHlDbGFpbXMoZGVjb2RlZDogUGFydGlhbDxKd3RQYXlsb2FkPik6IGJvb2xlYW4ge1xuICBpZiAoIWRlY29kZWQucHJpbmNpcGFsVHlwZSB8fCAhUFJJTkNJUEFMX1RZUEVTLmluY2x1ZGVzKGRlY29kZWQucHJpbmNpcGFsVHlwZSkpIHJldHVybiBmYWxzZTtcbiAgaWYgKCFkZWNvZGVkLnRva2VuX3VzZSB8fCAhVE9LRU5fVVNFUy5pbmNsdWRlcyhkZWNvZGVkLnRva2VuX3VzZSkpIHJldHVybiBmYWxzZTtcbiAgaWYgKGRlY29kZWQucHJpbmNpcGFsVHlwZSA9PT0gJ3NlcnZpY2UnKSB7XG4gICAgcmV0dXJuIGRlY29kZWQudG9rZW5fdXNlID09PSAnYWNjZXNzJ1xuICAgICAgJiYgdHlwZW9mIGRlY29kZWQuc3ViID09PSAnc3RyaW5nJ1xuICAgICAgJiYgZGVjb2RlZC5zdWIuc3RhcnRzV2l0aChTRVJWSUNFX1NVQkpFQ1RfUFJFRklYKVxuICAgICAgJiYgZGVjb2RlZC5zdWIubGVuZ3RoID4gU0VSVklDRV9TVUJKRUNUX1BSRUZJWC5sZW5ndGg7XG4gIH1cbiAgcmV0dXJuIEFycmF5LmlzQXJyYXkoZGVjb2RlZC5hbXIpXG4gICAgJiYgZGVjb2RlZC5hbXIuZXZlcnkoKG0pID0+IEFVVEhfTUVUSE9EUy5pbmNsdWRlcyhtKSlcbiAgICAmJiAoZGVjb2RlZC5hYWwgPT09IDEgfHwgZGVjb2RlZC5hYWwgPT09IDIpXG4gICAgJiYgdHlwZW9mIGRlY29kZWQuYXV0aF90aW1lID09PSAnbnVtYmVyJztcbn1cblxuIl19

package/lib/middleware/permission-gates.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Authorization gates — permissions, system admin, features — and the
+ * `authz.denied` audit sink they report refusals to.
+ */
+import type { Request, Response, NextFunction } from 'express';
+import { type Permission } from '../types/permissions.js';
+/**
+ * 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 — 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;
+/**
+ * Check if the request is from a system admin.
+ *
+ * Authority is granted solely by the user-level `isSuperAdmin` flag carried
+ * in the JWT — never by membership in the well-known 'system' org, which would
+ * conflate a Pipeline Builder operator with a customer tenant and let any
+ * write that created a 'system'-named org quietly grant cross-org authority. The `system` org still exists as a *content holder* for shared
+ * sample data; it confers no 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.
+ *  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;