api-quality-spectral-ruleset 1.6.1 → 1.8.0

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: {
@@ -22,12 +24,11 @@ const DEFAULT_PAGING_SCHEMA = {
 };
 
 const DEFAULT_PAGING_PROPERTY = 'paging';
-
-const COLLECTION_PROPERTY_NAMES = ['data', 'items', 'results', 'content', 'elements', 'records', 'entries', 'values', 'list', 'rows', 'payload'];
+const DEFAULT_PATHS = '/status,/health,/ping,**/me';
 
 const SUCCESS_CODE_REGEX = /^2(\d\d|XX)$/i;
 const NO_CONTENT_CODE = '204';
-const DETAIL_PATH_REGEX = /\/\{[^}]+\}$/;
+const MEDIA_TYPE_TOKEN = /^[a-z0-9!#$&^_.+-]+$/;
 
 const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
 
@@ -143,15 +144,6 @@ const isArrayView = (view) => view.types.has('array');
 
 const typePath = (view) => (isObject(view.rootSchema) && view.rootSchema.type !== undefined ? [...view.path, 'type'] : view.path);
 
-const findCollectionProperty = (view) => {
-  for (const [name, property] of view.properties) {
-    if (COLLECTION_PROPERTY_NAMES.includes(name.toLowerCase()) && isArrayView(buildView(property.schema, property.path))) {
-      return name;
-    }
-  }
-  return null;
-};
-
 const validateAgainstTemplate = (template, view, label, report) => {
   if (!isObject(template)) return;
   const type = expectedType(template);
@@ -189,56 +181,99 @@ const validateAgainstTemplate = (template, view, label, report) => {
   });
 };
 
-const responseSchemas = (response, responsePath, isOas2) => {
+const isJsonMediaType = (mediaType) => {
+  const essence = String(mediaType).split(';')[0].trim().toLowerCase();
+  const parts = essence.split('/');
+  if (parts.length !== 2 || parts[0] === '*') return true;
+  const [type, subtype] = parts;
+  if (!MEDIA_TYPE_TOKEN.test(type) || (subtype !== '*' && !MEDIA_TYPE_TOKEN.test(subtype))) return true;
+  if (type === 'application' && (subtype === 'json' || subtype === '*')) return true;
+  return subtype.endsWith('+json');
+};
+
+const isDetailPath = (pathKey) => pathKey.slice(pathKey.lastIndexOf('/') + 1).startsWith('{');
+
+const isUnresolvedRef = (value) => isObject(value) && typeof value.$ref === 'string';
+
+const producedMediaTypes = (document, pathKey) => {
+  const pathItem = isObject(document) && isObject(document.paths) ? document.paths[pathKey] : null;
+  const operation = isObject(pathItem) ? pathItem.get : null;
+  const listed = (value) => (Array.isArray(value) && value.length > 0 ? value : null);
+  return listed(isObject(operation) ? operation.produces : null) || listed(isObject(document) ? document.produces : null);
+};
+
+const evaluatedSchemas = (response, responsePath, document, pathKey, isOas2) => {
+  const schemas = [];
+  const missing = [];
   if (isOas2) {
-    return isObject(response.schema) ? [{ schema: response.schema, path: [...responsePath, 'schema'] }] : [];
+    const produces = producedMediaTypes(document, pathKey);
+    if (produces && !produces.some(isJsonMediaType)) return { schemas, missing };
+    if (isUnresolvedRef(response.schema)) return { schemas, missing };
+    if (isObject(response.schema)) schemas.push({ schema: response.schema, path: [...responsePath, 'schema'] });
+    else missing.push(responsePath);
+    return { schemas, missing };
+  }
+  if (!isObject(response.content) || Object.keys(response.content).length === 0) {
+    missing.push(isObject(response.content) ? [...responsePath, 'content'] : responsePath);
+    return { schemas, missing };
   }
-  if (!isObject(response.content)) return [];
-  return Object.entries(response.content)
-    .filter(([, mediaType]) => isObject(mediaType) && isObject(mediaType.schema))
-    .map(([mediaTypeName, mediaType]) => ({ schema: mediaType.schema, path: [...responsePath, 'content', mediaTypeName, 'schema'] }));
+  Object.entries(response.content)
+    .filter(([mediaTypeName]) => isJsonMediaType(mediaTypeName))
+    .forEach(([mediaTypeName, mediaType]) => {
+      const mediaTypePath = [...responsePath, 'content', mediaTypeName];
+      if (isUnresolvedRef(mediaType) || (isObject(mediaType) && isUnresolvedRef(mediaType.schema))) return;
+      if (isObject(mediaType) && isObject(mediaType.schema)) schemas.push({ schema: mediaType.schema, path: [...mediaTypePath, 'schema'] });
+      else missing.push(mediaTypePath);
+    });
+  return { schemas, missing };
 };
 
 /**
  * @param {object} response - a resolved response of a GET operation
- * @param {object} options - { 'paging-schema': JSON string or object }
+ * @param {object} options
+ * @param {string|object} options['paging-schema'] - JSON string or object with the paging structure and its pagingPropertyName (default "paging")
+ * @param {string|string[]} options.paths - comma-separated path patterns matched segment by segment; "*" matches one segment and "**" zero or more (default "/status,/health,/ping,**\/me")
+ * @param {string} options.pathValidationStrategy - "/exclude" (default) skips the matching paths, "/include" only evaluates them
  * @param {import('@stoplight/spectral-core').RulesetFunctionContext} context
  */
 module.exports = (response, options = {}, context) => {
-  if (!isObject(response)) return [];
+  if (!isObject(response) || isUnresolvedRef(response)) return [];
+  const opts = options || {};
 
   const responsePath = context.path || [];
   const statusCode = String(responsePath[responsePath.length - 1]);
   if (!SUCCESS_CODE_REGEX.test(statusCode) || statusCode === NO_CONTENT_CODE) return [];
 
   const pathKey = typeof responsePath[1] === 'string' ? responsePath[1] : '';
-  const isDetailPath = DETAIL_PATH_REGEX.test(pathKey);
+  if (isDetailPath(pathKey)) return [];
+  if (!pathsIncludeExclude(opts, DEFAULT_PATHS).isEvaluatedPath(pathKey)) return [];
 
-  const pagingSchema = parsePagingSchema((options || {})['paging-schema']);
+  const pagingSchema = parsePagingSchema(opts['paging-schema']);
   const pagingPropertyName = typeof pagingSchema.pagingPropertyName === 'string' && pagingSchema.pagingPropertyName.trim() !== ''
     ? pagingSchema.pagingPropertyName.trim()
     : DEFAULT_PAGING_PROPERTY;
 
-  const document = context.document && context.document.data;
-  const isOas2 = isObject(document) && typeof document.swagger === 'string';
+  const rawDocument = context.document && context.document.data;
+  const resolvedDocument = context.documentInventory && context.documentInventory.resolved;
+  const document = isObject(resolvedDocument) ? resolvedDocument : rawDocument;
+  const isOas2 = isObject(rawDocument) && typeof rawDocument.swagger === 'string';
   const ruleCode = context.rule && context.rule.name ? context.rule.name.split(':').pop() : 'OAR034';
 
   const results = [];
   const report = (message, path) => results.push({ message: `${ruleCode}: ${message}`, path });
 
-  responseSchemas(response, responsePath, isOas2).forEach(({ schema, path }) => {
+  const { schemas, missing } = evaluatedSchemas(response, responsePath, document, pathKey, isOas2);
+  missing.forEach((path) => report(`Collection response must define a schema with a '${pagingPropertyName}' property`, path));
+
+  schemas.forEach(({ schema, path }) => {
     const view = buildView(schema, path);
     const paging = view.properties.get(pagingPropertyName);
 
     if (!paging) {
-      if (isDetailPath) return;
       if (isArrayView(view)) {
         report(`Collection response must be an object with a '${pagingPropertyName}' property, not a top-level array`, view.path);
-        return;
-      }
-      const collectionProperty = findCollectionProperty(view);
-      if (collectionProperty) {
-        report(`Response with collection property '${collectionProperty}' must include '${pagingPropertyName}' property for pagination`, view.path);
+      } else {
+        report(`Collection response must include '${pagingPropertyName}' property for pagination`, view.path);
       }
       return;
     }

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/apq-valid-response-schema.js

@@ -18,9 +18,40 @@ function mergedProperties(schema, visited) {
   return properties;
 }
 
+function parseList(value) {
+  let items = [];
+  if (Array.isArray(value)) {
+    items = value;
+  } else if (typeof value === 'string') {
+    items = value.split(',');
+  }
+  const names = items
+    .filter((item) => typeof item === 'string' || typeof item === 'number')
+    .map((item) => String(item).trim())
+    .filter(Boolean);
+  return [...new Set(names)];
+}
+
+function formatNames(names) {
+  const quoted = names.map((name) => `'${name}'`);
+  if (quoted.length <= 1) {
+    return quoted.join('');
+  }
+  return `${quoted.slice(0, -1).join(', ')} or ${quoted[quoted.length - 1]}`;
+}
+
+function isIncludeStrategy(value) {
+  return typeof value === 'string' && value.trim().replace(/^\//, '').toLowerCase() === 'include';
+}
+
 /**
  * @param {object} given - the 201 response object of a POST operation
  * @param {object} options
+ * @param {string} options['data-property'] - name accepted next to 'error' when allowed-properties is not set (default "data")
+ * @param {string|string[]} options['allowed-properties'] - top-level property names accepted in the schema, array or comma-separated; blank falls back to [data-property, 'error']
+ * @param {string|string[]} options['required-properties'] - top-level property names that must be present, array or comma-separated
+ * @param {string|string[]} options.paths - paths to include/exclude (exact match), array or comma-separated
+ * @param {string} options.pathValidationStrategy - "/include" or "/exclude" (default "/exclude")
  * @param {import('@stoplight/spectral-core').RulesetFunctionContext} context
  */
 module.exports = (given, options, context) => {
@@ -28,17 +59,28 @@ module.exports = (given, options, context) => {
     return [];
   }
 
-  const dataProperty = (options && options['data-property']) || 'data';
-  const VALID_NAMES = [dataProperty, 'error'];
+  const opts = options || {};
+  const basePath = context.path || [];
+
+  const paths = parseList(opts.paths);
+  const isListed = paths.includes(basePath[1]);
+  if (isIncludeStrategy(opts.pathValidationStrategy) ? !isListed : isListed) {
+    return [];
+  }
+
+  const dataProperty = opts['data-property'] || 'data';
+  const configuredNames = parseList(opts['allowed-properties']);
+  const allowedNames = configuredNames.length > 0 ? configuredNames : [...new Set([dataProperty, 'error'])];
+  const requiredNames = parseList(opts['required-properties']);
+  const allowedText = formatNames(allowedNames);
   const doc = context.document?.data ?? {};
   const isOAP2 = typeof doc.swagger === 'string';
-  const basePath = context.path || [];
   const errors = [];
 
   const checkSchema = (schema, schemaPath) => {
     if (!schema || typeof schema !== 'object') {
       errors.push({
-        message: `OAR038: 201 response must define a schema with a '${dataProperty}' or 'error' property.`,
+        message: `OAR038: 201 response must define a schema with a ${allowedText} property.`,
         path: schemaPath,
       });
       return;
@@ -49,16 +91,16 @@ module.exports = (given, options, context) => {
 
     if (propNames.length === 0) {
       errors.push({
-        message: `OAR038: Response schema must have properties named '${dataProperty}' or 'error'.`,
+        message: `OAR038: Response schema must have properties named ${allowedText}.`,
         path: schemaPath,
       });
       return;
     }
 
     for (const propName of propNames) {
-      if (!VALID_NAMES.includes(propName)) {
+      if (!allowedNames.includes(propName)) {
         errors.push({
-          message: `OAR038: Response property must be named '${dataProperty}' or 'error'. Got '${propName}'.`,
+          message: `OAR038: Response property must be named ${allowedText}. Got '${propName}'.`,
           path: [...schemaPath, 'properties', propName],
         });
         continue;
@@ -71,6 +113,15 @@ module.exports = (given, options, context) => {
         });
       }
     }
+
+    for (const requiredName of requiredNames) {
+      if (!Object.prototype.hasOwnProperty.call(properties, requiredName)) {
+        errors.push({
+          message: `OAR038: Response schema must define the required property '${requiredName}'.`,
+          path: schemaPath,
+        });
+      }
+    }
   };
 
   if (isOAP2) {