api-quality-spectral-ruleset 1.7.0 → 1.8.0

package/apq-spectral.yaml

@@ -40,7 +40,7 @@ functions:
   - apq-numeric-invalid-format
   - apq-numeric-missing-format
   - apq-numeric-well-defined-format
-  - apq-string-parameter-integrity
+  - apq-string-parameter-schema-integrity
   - apq-example-schema-types
   - apq-standard-response-schema
   - apq-allowed-http-verbs
@@ -54,6 +54,9 @@ functions:
   - apq-response-content-required
   - apq-tags-consistency
   - apq-forbidden-title-pattern
+  - apq-security-flows-allowed
+  - apq-oauth-url-pattern
+  - apq-security-types-allowed
 rules:
   apiq:OAR001:
     description: "For security reasons and as a REST best practice, the HTTPS protocol is mandatory."
@@ -849,8 +852,8 @@ rules:
     then:
       function: apq-numeric-parameter-integrity
   apiq:OAR075:
-    description: "String parameters should have minLength, maxLength, pattern (regular expression), or enum restriction."
-    message: "OAR075: String parameters should have minLength, maxLength, pattern, or enum restriction."
+    description: "String parameter schemas should have minLength, maxLength, pattern (regular expression), or enum restriction."
+    message: "OAR075: String parameter schemas should have minLength, maxLength, pattern, or enum restriction."
     severity: error
     resolved: false
     given:
@@ -863,7 +866,7 @@ rules:
       - "$.components.parameters[*]"
       - "$.parameters[*]"
     then:
-      function: apq-string-parameter-integrity
+      function: apq-string-parameter-schema-integrity
       functionOptions:
         parameter_integrity: "minLength,maxLength,pattern,enum"
   apiq:OAR076:
@@ -1232,3 +1235,53 @@ rules:
       function: apq-forbidden-title-pattern
       functionOptions:
         forbidden-pattern: "(?!)"
+  apiq:OAR118:
+    description: "OAuth2 security schemes must only declare the flows allowed by the organization (authorizationCode and clientCredentials by default)."
+    message: "{{error}}"
+    documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR118.md"
+    severity: error
+    given: "$"
+    then:
+      function: apq-security-flows-allowed
+      functionOptions:
+        allowed-flows: "authorizationCode,clientCredentials"
+        paths: "/me,/health,/ping,/status"
+        pathValidationStrategy: "/exclude"
+  apiq:OAR119:
+    description: "The authorizationUrl of every OAuth2 flow must match the pattern allowed by the organization (an HTTPS URL on a domain ending in /authorize by default)."
+    message: "{{error}}"
+    documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR119.md"
+    severity: error
+    given: "$"
+    then:
+      function: apq-oauth-url-pattern
+      functionOptions:
+        field: authorizationUrl
+        pattern: '^https://[A-Za-z0-9-]+(\.[A-Za-z0-9-]+)+(:[0-9]+)?(/[^/?#]+)*/authorize$'
+        paths: "/me,/health,/ping,/status"
+        pathValidationStrategy: "/exclude"
+  apiq:OAR120:
+    description: "The tokenUrl of every OAuth2 flow must match the pattern allowed by the organization (an HTTPS URL on a domain ending in /token by default)."
+    message: "{{error}}"
+    documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR120.md"
+    severity: error
+    given: "$"
+    then:
+      function: apq-oauth-url-pattern
+      functionOptions:
+        field: tokenUrl
+        pattern: '^https://[A-Za-z0-9-]+(\.[A-Za-z0-9-]+)+(:[0-9]+)?(/[^/?#]+)*/token$'
+        paths: "/me,/health,/ping,/status"
+        pathValidationStrategy: "/exclude"
+  apiq:OAR121:
+    description: "Security schemes must only use the types allowed by the organization (oauth2 and HTTP bearer by default)."
+    message: "{{error}}"
+    documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR121.md"
+    severity: error
+    given: "$"
+    then:
+      function: apq-security-types-allowed
+      functionOptions:
+        allowed-security-types: "oauth2,bearer"
+        paths: "/me,/health,/ping,/status"
+        pathValidationStrategy: "/exclude"

package/functions/apq-oauth-url-pattern.js

@@ -0,0 +1,205 @@
+const { pathsIncludeExclude } = require('./paths-include-exclude.js');
+
+const DEFAULT_PATTERNS = {
+  authorizationUrl: '^https://[A-Za-z0-9-]+(\\.[A-Za-z0-9-]+)+(:[0-9]+)?(/[^/?#]+)*/authorize$',
+  tokenUrl: '^https://[A-Za-z0-9-]+(\\.[A-Za-z0-9-]+)+(:[0-9]+)?(/[^/?#]+)*/token$',
+};
+const DEFAULT_PATHS = '/me,/health,/ping,/status';
+const INLINE_FLAGS_REGEX = /^\(\?([a-zA-Z]+)\)/;
+const SUPPORTED_INLINE_FLAGS = 'imsu';
+
+const VERBS_V2 = ['get', 'put', 'post', 'delete', 'options', 'head', 'patch'];
+const VERBS_V3 = VERBS_V2.concat(['trace']);
+const VERBS_V32 = VERBS_V3.concat(['query']);
+
+const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const has = (obj, key) => Object.prototype.hasOwnProperty.call(obj, key);
+
+const documentVersion = (root) => {
+  if (has(root, 'swagger')) return 'v2';
+  if (!has(root, 'openapi')) return null;
+  const openapi = String(root.openapi).trim();
+  if (openapi.startsWith('3.2')) return 'v32';
+  if (openapi.startsWith('3.1')) return 'v31';
+  return 'v3';
+};
+
+const buildRegex = (raw) => {
+  if (typeof raw !== 'string' || raw.trim() === '') return null;
+  const text = raw.trim();
+  let source = text;
+  let flags = '';
+  const inline = INLINE_FLAGS_REGEX.exec(source);
+  if (inline) {
+    const requested = inline[1].toLowerCase();
+    if ([...requested].every((flag) => SUPPORTED_INLINE_FLAGS.includes(flag))) {
+      flags = [...new Set(requested)].join('');
+      source = source.slice(inline[0].length);
+    }
+  }
+  if (source === '') return null;
+  try {
+    return { regex: new RegExp(source, flags), text };
+  } catch (err) {
+    return null;
+  }
+};
+
+const pointerTarget = (root, ref) => {
+  let fragment;
+  try {
+    fragment = decodeURIComponent(ref.slice(1));
+  } catch (err) {
+    return undefined;
+  }
+  if (!fragment.startsWith('/')) return undefined;
+  const segments = fragment.slice(1).split('/').map((segment) => segment.replace(/~1/g, '/').replace(/~0/g, '~'));
+  let value = root;
+  for (const segment of segments) {
+    if (!isObject(value) || !has(value, segment)) return undefined;
+    value = value[segment];
+  }
+  return isObject(value) ? { value, segments } : undefined;
+};
+
+const collectOperations = (root, version) => {
+  const verbs = version === 'v32' ? VERBS_V32 : (version === 'v2' ? VERBS_V2 : VERBS_V3);
+  const operations = [];
+  const visitPathItem = (pathItem, pathKey, ancestors) => {
+    if (!isObject(pathItem) || ancestors.has(pathItem)) return;
+    const chain = new Set(ancestors).add(pathItem);
+    const ops = verbs.filter((verb) => has(pathItem, verb)).map((verb) => pathItem[verb]);
+    if (version === 'v32' && isObject(pathItem.additionalOperations)) ops.push(...Object.values(pathItem.additionalOperations));
+    ops.filter(isObject).forEach((op) => {
+      operations.push({ op, pathKey });
+      if (version === 'v2' || !isObject(op.callbacks)) return;
+      Object.values(op.callbacks).filter(isObject).forEach((callback) => {
+        Object.keys(callback)
+          .filter((expression) => !expression.startsWith('x-'))
+          .forEach((expression) => visitPathItem(callback[expression], pathKey, chain));
+      });
+    });
+  };
+  if (isObject(root.paths)) {
+    Object.keys(root.paths)
+      .filter((pathKey) => pathKey.startsWith('/'))
+      .forEach((pathKey) => visitPathItem(root.paths[pathKey], pathKey, new Set()));
+  }
+  if ((version === 'v31' || version === 'v32') && isObject(root.webhooks)) {
+    Object.values(root.webhooks).forEach((pathItem) => visitPathItem(pathItem, null, new Set()));
+  }
+  return operations;
+};
+
+const definitionsBase = (version) => (version === 'v2' ? ['securityDefinitions'] : ['components', 'securitySchemes']);
+
+const lookup = (root, segments) => segments.reduce((value, segment) => (isObject(value) ? value[segment] : undefined), root);
+
+/**
+ * @param {object} root - The resolved document (given: "$")
+ * @param {object} options
+ * @param {string} options.field - "authorizationUrl" or "tokenUrl", the URL of the OAuth2 flows that is checked
+ * @param {string} options.pattern - regular expression the URL must match (unanchored, an optional leading "(?i)" style
+ *   group sets the i, m, s and u flags); blank or invalid falls back to "https://host.domain/.../authorize" for
+ *   authorizationUrl and "https://host.domain/.../token" for tokenUrl
+ * @param {string|string[]} options.paths - comma-separated path patterns matched segment by segment; "*" matches one segment
+ *   and "**" zero or more (default "/me,/health,/ping,/status")
+ * @param {string} options.pathValidationStrategy - "/exclude" (default) skips the security schemes applied only to matching
+ *   paths, "/include" only evaluates the security schemes applied to them; webhooks have no path, so they are only evaluated
+ *   with "/exclude", and callbacks follow the path of their operation
+ * @param {import('@stoplight/spectral-core').RulesetFunctionContext} context
+ * @returns {Array<{message: string, path: Array<string>}>} one result per URL that does not match, on the URL itself
+ */
+module.exports = (root, options, context) => {
+  if (!isObject(root)) return [];
+  const version = documentVersion(root);
+  if (version === null) return [];
+
+  const opts = options || {};
+  const field = opts.field;
+  if (!has(DEFAULT_PATTERNS, field)) return [];
+  const matcher = buildRegex(opts.pattern) || buildRegex(DEFAULT_PATTERNS[field]);
+  const { include, isEvaluatedPath } = pathsIncludeExclude(opts, DEFAULT_PATHS);
+
+  const base = definitionsBase(version);
+  const definitions = lookup(root, base);
+  const rawDefinitions = lookup(context.document && context.document.data, base);
+  const schemes = new Map();
+  if (isObject(definitions)) {
+    Object.keys(definitions).forEach((name) => {
+      const scheme = definitions[name];
+      if (!isObject(scheme)) return;
+      const rawEntry = isObject(rawDefinitions) ? rawDefinitions[name] : undefined;
+      const direct = isObject(rawEntry) && !has(rawEntry, '$ref');
+      const known = schemes.get(scheme);
+      if (!known || (!known.direct && direct)) schemes.set(scheme, { name, path: [...base, name], direct });
+    });
+  }
+
+  const schemeFor = (key) => {
+    if (isObject(definitions) && has(definitions, key)) return isObject(definitions[key]) ? definitions[key] : undefined;
+    if (version !== 'v32') return undefined;
+    const self = typeof root.$self === 'string' ? root.$self.trim() : '';
+    const fragment = self !== '' && key.startsWith(`${self}#`) ? key.slice(self.length) : key;
+    if (!fragment.startsWith('#')) return undefined;
+    const target = pointerTarget(root, fragment);
+    if (!target) return undefined;
+    if (!schemes.has(target.value)) {
+      schemes.set(target.value, { name: target.segments[target.segments.length - 1], path: target.segments, direct: true });
+    }
+    return target.value;
+  };
+
+  const usage = new Map();
+  const rootSecurity = Array.isArray(root.security) ? root.security : [];
+  collectOperations(root, version).forEach(({ op, pathKey }) => {
+    const security = Array.isArray(op.security) ? op.security : rootSecurity;
+    const inScope = pathKey === null ? !include : isEvaluatedPath(pathKey);
+    security.filter(isObject).forEach((requirement) => {
+      Object.keys(requirement).forEach((key) => {
+        const scheme = schemeFor(key);
+        if (scheme) usage.set(scheme, usage.get(scheme) === true || inScope);
+      });
+    });
+  });
+
+  const inventory = context.documentInventory;
+  const isLocatable = (path) => {
+    const item = inventory.findAssociatedItemForPath(path, true);
+    if (!item || !item.document) return true;
+    return item.document.getRangeForJsonPath(item.path, false) !== undefined;
+  };
+  const locatable = (path) => {
+    if (!inventory || typeof inventory.findAssociatedItemForPath !== 'function') return path;
+    for (let length = path.length; length > 0; length -= 1) {
+      if (isLocatable(path.slice(0, length))) return path.slice(0, length);
+    }
+    return path;
+  };
+
+  const ruleCode = context.rule && context.rule.name ? context.rule.name.split(':').pop() : (field === 'tokenUrl' ? 'OAR120' : 'OAR119');
+  const results = [];
+  const check = (url, flow, name, path) => {
+    if (typeof url !== 'string' || matcher.regex.test(url)) return;
+    const flowText = typeof flow === 'string' && flow.trim() !== '' ? ` of flow '${flow}'` : '';
+    results.push({
+      message: `${ruleCode}: ${field} '${url}'${flowText} in security scheme '${name}' does not match the allowed pattern: ${matcher.text}`,
+      path: locatable(path),
+    });
+  };
+
+  schemes.forEach((entry, scheme) => {
+    if (usage.has(scheme) ? !usage.get(scheme) : include) return;
+    if (typeof scheme.type !== 'string' || scheme.type.trim().toLowerCase() !== 'oauth2') return;
+    if (version === 'v2') {
+      if (has(scheme, field)) check(scheme[field], scheme.flow, entry.name, [...entry.path, field]);
+      return;
+    }
+    if (!isObject(scheme.flows)) return;
+    Object.keys(scheme.flows)
+      .filter((flow) => !flow.startsWith('x-') && flow.trim() !== '' && isObject(scheme.flows[flow]) && has(scheme.flows[flow], field))
+      .forEach((flow) => check(scheme.flows[flow][field], flow, entry.name, [...entry.path, 'flows', flow, field]));
+  });
+
+  return results;
+};

package/functions/apq-paged-response-check.js

@@ -1,3 +1,5 @@
+const { pathsIncludeExclude } = require('./paths-include-exclude.js');
+
 const DEFAULT_PAGING_SCHEMA = {
   type: 'object',
   properties: {
@@ -189,35 +191,6 @@ const isJsonMediaType = (mediaType) => {
   return subtype.endsWith('+json');
 };
 
-const pathPatterns = (raw) => {
-  let items = [];
-  if (raw === undefined) items = DEFAULT_PATHS.split(',');
-  else if (typeof raw === 'string') items = raw.split(',');
-  else if (Array.isArray(raw)) items = raw;
-  return items
-    .filter((item) => typeof item === 'string')
-    .map((item) => item.trim())
-    .filter(Boolean)
-    .map((pattern) => pattern.split('/'));
-};
-
-const isIncludeStrategy = (value) => typeof value === 'string' && value.trim().replace(/^\//, '').toLowerCase() === 'include';
-
-const matchesPattern = (pattern, segments) => {
-  const match = (patternIndex, segmentIndex) => {
-    if (patternIndex === pattern.length) return segmentIndex === segments.length;
-    if (pattern[patternIndex] === '**') {
-      for (let next = segmentIndex; next <= segments.length; next += 1) {
-        if (match(patternIndex + 1, next)) return true;
-      }
-      return false;
-    }
-    if (segmentIndex === segments.length) return false;
-    return (pattern[patternIndex] === '*' || pattern[patternIndex] === segments[segmentIndex]) && match(patternIndex + 1, segmentIndex + 1);
-  };
-  return match(0, 0);
-};
-
 const isDetailPath = (pathKey) => pathKey.slice(pathKey.lastIndexOf('/') + 1).startsWith('{');
 
 const isUnresolvedRef = (value) => isObject(value) && typeof value.$ref === 'string';
@@ -273,9 +246,7 @@ module.exports = (response, options = {}, context) => {
 
   const pathKey = typeof responsePath[1] === 'string' ? responsePath[1] : '';
   if (isDetailPath(pathKey)) return [];
-  const segments = pathKey.split('/');
-  const isListed = pathPatterns(opts.paths).some((pattern) => matchesPattern(pattern, segments));
-  if (isIncludeStrategy(opts.pathValidationStrategy) ? !isListed : isListed) return [];
+  if (!pathsIncludeExclude(opts, DEFAULT_PATHS).isEvaluatedPath(pathKey)) return [];
 
   const pagingSchema = parsePagingSchema(opts['paging-schema']);
   const pagingPropertyName = typeof pagingSchema.pagingPropertyName === 'string' && pagingSchema.pagingPropertyName.trim() !== ''

package/functions/apq-security-flows-allowed.js

@@ -0,0 +1,194 @@
+const { pathsIncludeExclude } = require('./paths-include-exclude.js');
+
+const DEFAULT_ALLOWED_FLOWS = 'authorizationCode,clientCredentials';
+const DEFAULT_PATHS = '/me,/health,/ping,/status';
+const FLOW_ALIASES = { accesscode: 'authorizationcode', application: 'clientcredentials' };
+
+const VERBS_V2 = ['get', 'put', 'post', 'delete', 'options', 'head', 'patch'];
+const VERBS_V3 = VERBS_V2.concat(['trace']);
+const VERBS_V32 = VERBS_V3.concat(['query']);
+
+const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const has = (obj, key) => Object.prototype.hasOwnProperty.call(obj, key);
+
+const documentVersion = (root) => {
+  if (has(root, 'swagger')) return 'v2';
+  if (!has(root, 'openapi')) return null;
+  const openapi = String(root.openapi).trim();
+  if (openapi.startsWith('3.2')) return 'v32';
+  if (openapi.startsWith('3.1')) return 'v31';
+  return 'v3';
+};
+
+const flowKey = (name) => {
+  const key = name.trim().toLowerCase();
+  return FLOW_ALIASES[key] || key;
+};
+
+const allowedFlows = (raw) => {
+  let items = [];
+  if (typeof raw === 'string') items = raw.split(',');
+  else if (Array.isArray(raw)) items = raw.filter((item) => typeof item === 'string').flatMap((item) => item.split(','));
+  const names = new Map();
+  items.map((item) => item.trim()).filter(Boolean).forEach((item) => {
+    if (!names.has(flowKey(item))) names.set(flowKey(item), item);
+  });
+  return names.size > 0 ? names : allowedFlows(DEFAULT_ALLOWED_FLOWS);
+};
+
+const pointerTarget = (root, ref) => {
+  let fragment;
+  try {
+    fragment = decodeURIComponent(ref.slice(1));
+  } catch (err) {
+    return undefined;
+  }
+  if (!fragment.startsWith('/')) return undefined;
+  const segments = fragment.slice(1).split('/').map((segment) => segment.replace(/~1/g, '/').replace(/~0/g, '~'));
+  let value = root;
+  for (const segment of segments) {
+    if (!isObject(value) || !has(value, segment)) return undefined;
+    value = value[segment];
+  }
+  return isObject(value) ? { value, segments } : undefined;
+};
+
+const collectOperations = (root, version) => {
+  const verbs = version === 'v32' ? VERBS_V32 : (version === 'v2' ? VERBS_V2 : VERBS_V3);
+  const operations = [];
+  const visitPathItem = (pathItem, pathKey, ancestors) => {
+    if (!isObject(pathItem) || ancestors.has(pathItem)) return;
+    const chain = new Set(ancestors).add(pathItem);
+    const ops = verbs.filter((verb) => has(pathItem, verb)).map((verb) => pathItem[verb]);
+    if (version === 'v32' && isObject(pathItem.additionalOperations)) ops.push(...Object.values(pathItem.additionalOperations));
+    ops.filter(isObject).forEach((op) => {
+      operations.push({ op, pathKey });
+      if (version === 'v2' || !isObject(op.callbacks)) return;
+      Object.values(op.callbacks).filter(isObject).forEach((callback) => {
+        Object.keys(callback)
+          .filter((expression) => !expression.startsWith('x-'))
+          .forEach((expression) => visitPathItem(callback[expression], pathKey, chain));
+      });
+    });
+  };
+  if (isObject(root.paths)) {
+    Object.keys(root.paths)
+      .filter((pathKey) => pathKey.startsWith('/'))
+      .forEach((pathKey) => visitPathItem(root.paths[pathKey], pathKey, new Set()));
+  }
+  if ((version === 'v31' || version === 'v32') && isObject(root.webhooks)) {
+    Object.values(root.webhooks).forEach((pathItem) => visitPathItem(pathItem, null, new Set()));
+  }
+  return operations;
+};
+
+const definitionsBase = (version) => (version === 'v2' ? ['securityDefinitions'] : ['components', 'securitySchemes']);
+
+const lookup = (root, segments) => segments.reduce((value, segment) => (isObject(value) ? value[segment] : undefined), root);
+
+/**
+ * @param {object} root - The resolved document (given: "$")
+ * @param {object} options
+ * @param {string|string[]} options['allowed-flows'] - OAuth2 flows allowed in oauth2 security schemes, array or comma-separated,
+ *   case-insensitive; the Swagger 2.0 names are equivalent to the OpenAPI 3 ones (accessCode = authorizationCode,
+ *   application = clientCredentials); blank or unusable falls back to "authorizationCode,clientCredentials"
+ * @param {string|string[]} options.paths - comma-separated path patterns matched segment by segment; "*" matches one segment
+ *   and "**" zero or more (default "/me,/health,/ping,/status")
+ * @param {string} options.pathValidationStrategy - "/exclude" (default) skips the security schemes applied only to matching
+ *   paths, "/include" only evaluates the security schemes applied to them; webhooks have no path, so they are only evaluated
+ *   with "/exclude", and callbacks follow the path of their operation
+ * @param {import('@stoplight/spectral-core').RulesetFunctionContext} context
+ * @returns {Array<{message: string, path: Array<string>}>} one result per disallowed flow, on the scheme definition
+ */
+module.exports = (root, options, context) => {
+  if (!isObject(root)) return [];
+  const version = documentVersion(root);
+  if (version === null) return [];
+
+  const opts = options || {};
+  const allowed = allowedFlows(opts['allowed-flows']);
+  const allowedText = [...allowed.values()].join(', ');
+  const { include, isEvaluatedPath } = pathsIncludeExclude(opts, DEFAULT_PATHS);
+
+  const base = definitionsBase(version);
+  const definitions = lookup(root, base);
+  const rawDefinitions = lookup(context.document && context.document.data, base);
+  const schemes = new Map();
+  if (isObject(definitions)) {
+    Object.keys(definitions).forEach((name) => {
+      const scheme = definitions[name];
+      if (!isObject(scheme)) return;
+      const rawEntry = isObject(rawDefinitions) ? rawDefinitions[name] : undefined;
+      const direct = isObject(rawEntry) && !has(rawEntry, '$ref');
+      const known = schemes.get(scheme);
+      if (!known || (!known.direct && direct)) schemes.set(scheme, { name, path: [...base, name], direct });
+    });
+  }
+
+  const schemeFor = (key) => {
+    if (isObject(definitions) && has(definitions, key)) return isObject(definitions[key]) ? definitions[key] : undefined;
+    if (version !== 'v32') return undefined;
+    const self = typeof root.$self === 'string' ? root.$self.trim() : '';
+    const fragment = self !== '' && key.startsWith(`${self}#`) ? key.slice(self.length) : key;
+    if (!fragment.startsWith('#')) return undefined;
+    const target = pointerTarget(root, fragment);
+    if (!target) return undefined;
+    if (!schemes.has(target.value)) {
+      schemes.set(target.value, { name: target.segments[target.segments.length - 1], path: target.segments, direct: true });
+    }
+    return target.value;
+  };
+
+  const usage = new Map();
+  const rootSecurity = Array.isArray(root.security) ? root.security : [];
+  collectOperations(root, version).forEach(({ op, pathKey }) => {
+    const security = Array.isArray(op.security) ? op.security : rootSecurity;
+    const inScope = pathKey === null ? !include : isEvaluatedPath(pathKey);
+    security.filter(isObject).forEach((requirement) => {
+      Object.keys(requirement).forEach((key) => {
+        const scheme = schemeFor(key);
+        if (scheme) usage.set(scheme, usage.get(scheme) === true || inScope);
+      });
+    });
+  });
+
+  const inventory = context.documentInventory;
+  const isLocatable = (path) => {
+    const item = inventory.findAssociatedItemForPath(path, true);
+    if (!item || !item.document) return true;
+    return item.document.getRangeForJsonPath(item.path, false) !== undefined;
+  };
+  const locatable = (path) => {
+    if (!inventory || typeof inventory.findAssociatedItemForPath !== 'function') return path;
+    for (let length = path.length; length > 0; length -= 1) {
+      if (isLocatable(path.slice(0, length))) return path.slice(0, length);
+    }
+    return path;
+  };
+
+  const ruleCode = context.rule && context.rule.name ? context.rule.name.split(':').pop() : 'OAR118';
+  const results = [];
+  const report = (flow, name, path) => {
+    results.push({
+      message: `${ruleCode}: Flow '${flow}' of security scheme '${name}' is not allowed. Allowed flows: ${allowedText}.`,
+      path: locatable(path),
+    });
+  };
+
+  schemes.forEach((entry, scheme) => {
+    if (usage.has(scheme) ? !usage.get(scheme) : include) return;
+    if (typeof scheme.type !== 'string' || scheme.type.trim().toLowerCase() !== 'oauth2') return;
+    if (version === 'v2') {
+      if (typeof scheme.flow === 'string' && scheme.flow.trim() !== '' && !allowed.has(flowKey(scheme.flow))) {
+        report(scheme.flow, entry.name, [...entry.path, 'flow']);
+      }
+      return;
+    }
+    if (!isObject(scheme.flows)) return;
+    Object.keys(scheme.flows)
+      .filter((flow) => !flow.startsWith('x-') && flow.trim() !== '' && !allowed.has(flowKey(flow)))
+      .forEach((flow) => report(flow, entry.name, [...entry.path, 'flows', flow]));
+  });
+
+  return results;
+};

package/functions/apq-security-types-allowed.js

@@ -0,0 +1,187 @@
+const { pathsIncludeExclude } = require('./paths-include-exclude.js');
+
+const DEFAULT_ALLOWED_TYPES = 'oauth2,bearer';
+const DEFAULT_PATHS = '/me,/health,/ping,/status';
+
+const VERBS_V2 = ['get', 'put', 'post', 'delete', 'options', 'head', 'patch'];
+const VERBS_V3 = VERBS_V2.concat(['trace']);
+const VERBS_V32 = VERBS_V3.concat(['query']);
+
+const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const has = (obj, key) => Object.prototype.hasOwnProperty.call(obj, key);
+const typeKey = (name) => name.trim().toLowerCase();
+
+const documentVersion = (root) => {
+  if (has(root, 'swagger')) return 'v2';
+  if (!has(root, 'openapi')) return null;
+  const openapi = String(root.openapi).trim();
+  if (openapi.startsWith('3.2')) return 'v32';
+  if (openapi.startsWith('3.1')) return 'v31';
+  return 'v3';
+};
+
+const allowedTypes = (raw) => {
+  let items = [];
+  if (typeof raw === 'string') items = raw.split(',');
+  else if (Array.isArray(raw)) items = raw.filter((item) => typeof item === 'string').flatMap((item) => item.split(','));
+  const names = new Map();
+  items.map((item) => item.trim()).filter(Boolean).forEach((item) => {
+    if (!names.has(typeKey(item))) names.set(typeKey(item), item);
+  });
+  return names.size > 0 ? names : allowedTypes(DEFAULT_ALLOWED_TYPES);
+};
+
+const pointerTarget = (root, ref) => {
+  let fragment;
+  try {
+    fragment = decodeURIComponent(ref.slice(1));
+  } catch (err) {
+    return undefined;
+  }
+  if (!fragment.startsWith('/')) return undefined;
+  const segments = fragment.slice(1).split('/').map((segment) => segment.replace(/~1/g, '/').replace(/~0/g, '~'));
+  let value = root;
+  for (const segment of segments) {
+    if (!isObject(value) || !has(value, segment)) return undefined;
+    value = value[segment];
+  }
+  return isObject(value) ? { value, segments } : undefined;
+};
+
+const collectOperations = (root, version) => {
+  const verbs = version === 'v32' ? VERBS_V32 : (version === 'v2' ? VERBS_V2 : VERBS_V3);
+  const operations = [];
+  const visitPathItem = (pathItem, pathKey, ancestors) => {
+    if (!isObject(pathItem) || ancestors.has(pathItem)) return;
+    const chain = new Set(ancestors).add(pathItem);
+    const ops = verbs.filter((verb) => has(pathItem, verb)).map((verb) => pathItem[verb]);
+    if (version === 'v32' && isObject(pathItem.additionalOperations)) ops.push(...Object.values(pathItem.additionalOperations));
+    ops.filter(isObject).forEach((op) => {
+      operations.push({ op, pathKey });
+      if (version === 'v2' || !isObject(op.callbacks)) return;
+      Object.values(op.callbacks).filter(isObject).forEach((callback) => {
+        Object.keys(callback)
+          .filter((expression) => !expression.startsWith('x-'))
+          .forEach((expression) => visitPathItem(callback[expression], pathKey, chain));
+      });
+    });
+  };
+  if (isObject(root.paths)) {
+    Object.keys(root.paths)
+      .filter((pathKey) => pathKey.startsWith('/'))
+      .forEach((pathKey) => visitPathItem(root.paths[pathKey], pathKey, new Set()));
+  }
+  if ((version === 'v31' || version === 'v32') && isObject(root.webhooks)) {
+    Object.values(root.webhooks).forEach((pathItem) => visitPathItem(pathItem, null, new Set()));
+  }
+  return operations;
+};
+
+const definitionsBase = (version) => (version === 'v2' ? ['securityDefinitions'] : ['components', 'securitySchemes']);
+
+const lookup = (root, segments) => segments.reduce((value, segment) => (isObject(value) ? value[segment] : undefined), root);
+
+/**
+ * @param {object} root - The resolved document (given: "$")
+ * @param {object} options
+ * @param {string|string[]} options['allowed-security-types'] - security scheme types allowed, array or comma-separated,
+ *   case-insensitive: apiKey, http, oauth2, openIdConnect, mutualTLS, or an HTTP authentication scheme (basic, bearer,
+ *   digest...) that allows only that scheme of the http type; "http" allows every HTTP scheme and Swagger 2.0 "basic" is
+ *   the HTTP basic scheme; blank or unusable falls back to "oauth2,bearer"
+ * @param {string|string[]} options.paths - comma-separated path patterns matched segment by segment; "*" matches one segment
+ *   and "**" zero or more (default "/me,/health,/ping,/status")
+ * @param {string} options.pathValidationStrategy - "/exclude" (default) skips the security schemes applied only to matching
+ *   paths, "/include" only evaluates the security schemes applied to them; webhooks have no path, so they are only evaluated
+ *   with "/exclude", and callbacks follow the path of their operation
+ * @param {import('@stoplight/spectral-core').RulesetFunctionContext} context
+ * @returns {Array<{message: string, path: Array<string>}>} one result per scheme whose type is not allowed
+ */
+module.exports = (root, options, context) => {
+  if (!isObject(root)) return [];
+  const version = documentVersion(root);
+  if (version === null) return [];
+
+  const opts = options || {};
+  const allowed = allowedTypes(opts['allowed-security-types']);
+  const allowedText = [...allowed.values()].join(', ');
+  const { include, isEvaluatedPath } = pathsIncludeExclude(opts, DEFAULT_PATHS);
+
+  const base = definitionsBase(version);
+  const definitions = lookup(root, base);
+  const rawDefinitions = lookup(context.document && context.document.data, base);
+  const schemes = new Map();
+  if (isObject(definitions)) {
+    Object.keys(definitions).forEach((name) => {
+      const scheme = definitions[name];
+      if (!isObject(scheme)) return;
+      const rawEntry = isObject(rawDefinitions) ? rawDefinitions[name] : undefined;
+      const direct = isObject(rawEntry) && !has(rawEntry, '$ref');
+      const known = schemes.get(scheme);
+      if (!known || (!known.direct && direct)) schemes.set(scheme, { name, path: [...base, name], direct });
+    });
+  }
+
+  const schemeFor = (key) => {
+    if (isObject(definitions) && has(definitions, key)) return isObject(definitions[key]) ? definitions[key] : undefined;
+    if (version !== 'v32') return undefined;
+    const self = typeof root.$self === 'string' ? root.$self.trim() : '';
+    const fragment = self !== '' && key.startsWith(`${self}#`) ? key.slice(self.length) : key;
+    if (!fragment.startsWith('#')) return undefined;
+    const target = pointerTarget(root, fragment);
+    if (!target) return undefined;
+    if (!schemes.has(target.value)) {
+      schemes.set(target.value, { name: target.segments[target.segments.length - 1], path: target.segments, direct: true });
+    }
+    return target.value;
+  };
+
+  const usage = new Map();
+  const rootSecurity = Array.isArray(root.security) ? root.security : [];
+  collectOperations(root, version).forEach(({ op, pathKey }) => {
+    const security = Array.isArray(op.security) ? op.security : rootSecurity;
+    const inScope = pathKey === null ? !include : isEvaluatedPath(pathKey);
+    security.filter(isObject).forEach((requirement) => {
+      Object.keys(requirement).forEach((key) => {
+        const scheme = schemeFor(key);
+        if (scheme) usage.set(scheme, usage.get(scheme) === true || inScope);
+      });
+    });
+  });
+
+  const inventory = context.documentInventory;
+  const isLocatable = (path) => {
+    const item = inventory.findAssociatedItemForPath(path, true);
+    if (!item || !item.document) return true;
+    return item.document.getRangeForJsonPath(item.path, false) !== undefined;
+  };
+  const locatable = (path) => {
+    if (!inventory || typeof inventory.findAssociatedItemForPath !== 'function') return path;
+    for (let length = path.length; length > 0; length -= 1) {
+      if (isLocatable(path.slice(0, length))) return path.slice(0, length);
+    }
+    return path;
+  };
+
+  const ruleCode = context.rule && context.rule.name ? context.rule.name.split(':').pop() : 'OAR121';
+  const results = [];
+
+  schemes.forEach((entry, scheme) => {
+    if (usage.has(scheme) ? !usage.get(scheme) : include) return;
+    if (typeof scheme.type !== 'string' || scheme.type.trim() === '') return;
+    const type = scheme.type.trim();
+    const httpScheme = version !== 'v2' && typeKey(type) === 'http' && typeof scheme.scheme === 'string' && scheme.scheme.trim() !== ''
+      ? scheme.scheme.trim()
+      : null;
+    const labels = [typeKey(type)];
+    if (httpScheme !== null) labels.push(typeKey(httpScheme));
+    if (version === 'v2' && typeKey(type) === 'basic') labels.push('http');
+    if (labels.some((label) => allowed.has(label))) return;
+    const described = httpScheme === null ? `type '${type}'` : `type '${type}' with scheme '${httpScheme}'`;
+    results.push({
+      message: `${ruleCode}: Security scheme '${entry.name}' ${described} is not allowed. Allowed types: ${allowedText}.`,
+      path: locatable([...entry.path, httpScheme === null ? 'type' : 'scheme']),
+    });
+  });
+
+  return results;
+};

package/functions/paths-include-exclude.js

@@ -0,0 +1,42 @@
+const pathPatterns = (raw, defaultPaths) => {
+  let items = [];
+  if (raw === undefined) items = defaultPaths.split(',');
+  else if (typeof raw === 'string') items = raw.split(',');
+  else if (Array.isArray(raw)) items = raw;
+  return items
+    .filter((item) => typeof item === 'string')
+    .map((item) => item.trim())
+    .filter(Boolean)
+    .map((pattern) => pattern.split('/'));
+};
+
+const isIncludeStrategy = (value) => typeof value === 'string' && value.trim().replace(/^\//, '').toLowerCase() === 'include';
+
+const matchesPattern = (pattern, segments) => {
+  const match = (patternIndex, segmentIndex) => {
+    if (patternIndex === pattern.length) return segmentIndex === segments.length;
+    if (pattern[patternIndex] === '**') {
+      for (let next = segmentIndex; next <= segments.length; next += 1) {
+        if (match(patternIndex + 1, next)) return true;
+      }
+      return false;
+    }
+    if (segmentIndex === segments.length) return false;
+    return (pattern[patternIndex] === '*' || pattern[patternIndex] === segments[segmentIndex]) && match(patternIndex + 1, segmentIndex + 1);
+  };
+  return match(0, 0);
+};
+
+const pathsIncludeExclude = (options, defaultPaths) => {
+  const opts = options || {};
+  const include = isIncludeStrategy(opts.pathValidationStrategy);
+  const patterns = pathPatterns(opts.paths, defaultPaths);
+  const isEvaluatedPath = (pathKey) => {
+    const segments = pathKey.split('/');
+    const isListed = patterns.some((pattern) => matchesPattern(pattern, segments));
+    return include ? isListed : !isListed;
+  };
+  return { include, isEvaluatedPath };
+};
+
+module.exports = { pathsIncludeExclude };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "api-quality-spectral-ruleset",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "Spectral ruleset by API Quality",
   "main": "apq-spectral.yaml",
   "files": [