specshield 3.5.1 → 3.5.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,11 @@
1
1
  # SpecShield CLI changelog
2
2
 
3
+ ## Unreleased — security regressions in the gate
4
+
5
+ ### Added
6
+
7
+ - `specshield gate --security` (or `gate.security: true`) blocks removed or weakened authentication, dropped OAuth scopes, new endpoints with forgotten auth, and newly exposed credentials or regulated data. Lower-risk changes are reported for review. Off by default. Findings use the existing shadow mode and waivers.
8
+
3
9
  ## Unreleased — proof, not opinion: `specshield prove` and `specshield replay`
4
10
 
5
11
  ### Added
package/README.md CHANGED
@@ -42,7 +42,7 @@ What the CLI does:
42
42
  - [vs. Alternatives](#vs-alternatives) · [Pricing](#pricing)
43
43
 
44
44
  **Commands — local & hosted compare**
45
- - [Local Compare](#local-compare) · [**Who does a change break? (usage-aware compare)**](#who-does-a-change-break--usage-aware-compare) · [**Safe removal: deprecate → drain → remove**](#safe-removal-deprecate--watch-traffic-drain--remove) · [**Break → fix: `specshield fix`**](#break--fix-generate-the-non-breaking-version) · [**CI gate: `specshield gate`**](#a-gate-you-can-leave-blocking-specshield-gate) · [**Proof: `prove` & `replay`**](#proof-not-opinion-specshield-prove-and-specshield-replay) · [Remote Compare](#remote-compare) · [Comparison History](#comparison-history) · [Share a Comparison](#share-a-comparison) · [GitHub App PR Checks](#github-app--pr-checks)
45
+ - [Local Compare](#local-compare) · [**Who does a change break? (usage-aware compare)**](#who-does-a-change-break--usage-aware-compare) · [**Safe removal: deprecate → drain → remove**](#safe-removal-deprecate--watch-traffic-drain--remove) · [**Break → fix: `specshield fix`**](#break--fix-generate-the-non-breaking-version) · [**CI gate: `specshield gate`**](#a-gate-you-can-leave-blocking-specshield-gate) · [**Proof: `prove` & `replay`**](#proof-not-opinion-specshield-prove-and-specshield-replay) · [**Security regressions: `gate --security`**](#security-regressions-in-the-gate-specshield-gate---security) · [Remote Compare](#remote-compare) · [Comparison History](#comparison-history) · [Share a Comparison](#share-a-comparison) · [GitHub App PR Checks](#github-app--pr-checks)
46
46
 
47
47
  **Governance — lint & gate**
48
48
  - [`specshield govern`](#governance--lint-a-spec-and-gate-the-pr)
@@ -578,6 +578,25 @@ In GitHub Actions the gate also writes a job summary and annotations (`--no-summ
578
578
 
579
579
  ---
580
580
 
581
+ ## Security regressions in the gate: `specshield gate --security`
582
+
583
+ The gate also blocks a PR that makes the API less safe. Turn it on with `--security`, or `gate.security: true` in `.specshield.yml`.
584
+
585
+ | Finding (waiver `change`) | Blocks? | Example |
586
+ |---|---|---|
587
+ | `auth-removed` | yes | An operation, or the API-wide `security`, now allows anonymous calls |
588
+ | `auth-scope-reduced` | yes | `[refunds:write, admin]` became `[refunds:write]` |
589
+ | `auth-weakened` | yes | Bearer became basic, an API key moved to the query string, or one required scheme was dropped |
590
+ | `endpoint-added-without-auth` | yes | A new endpoint declares no security while others in the API do |
591
+ | `sensitive-field-exposed` | credentials and regulated data; personal data on public endpoints | New response field `password`, `client_secret`, `cardNumber`, `ssn`; `writeOnly` dropped |
592
+ | `sensitive-field-exposed` | no, reported for review | New `email`, `phone` or token field on an authenticated endpoint |
593
+ | `auth-changed` | no, reported for review | Moved to a different scheme of equal strength |
594
+ | `public-endpoint-added` | no, reported for review | A new endpoint with an explicit `security: []` |
595
+
596
+ A new requirement counts as safe only when every credential that passes it would have passed the old one. Moving a requirement between global and operation level, or adding a scope, reports nothing.
597
+
598
+ Findings work like every other gate finding: `--shadow` reports without failing, and a waiver needs an owner, a reason and an expiry. Usage data never hides them. This reads what the spec declares; it doesn't test what the running service enforces. Sensitive fields are matched by name and `format`, so expect the occasional miss on unusual names.
599
+
581
600
  ## Proof, not opinion: `specshield prove` and `specshield replay`
582
601
 
583
602
  A diff says *"breaking change"*. A reviewer asks *"does it actually break anything?"* — and a gate that can't answer gets overruled. `prove` answers with the exact request that worked before and fails now; `replay` answers with real traffic.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "specshield",
3
- "version": "3.5.1",
3
+ "version": "3.5.2",
4
4
  "description": "Contract compatibility testing for APIs — catch breaking OpenAPI changes before they reach your consumers, with can-i-deploy deploy gating and GitHub PR checks. (a.k.a. bidirectional contract testing.)",
5
5
  "main": "src/cli.js",
6
6
  "homepage": "https://specshield.io",
@@ -27,6 +27,7 @@ const gate = new Command('gate')
27
27
  .option('--no-fetch', 'Never run git fetch, even when the baseline commit is missing from a shallow clone')
28
28
  .option('--usage <file>', 'usage.json from "specshield usage import" — breaking changes no client uses stop blocking')
29
29
  .option('--prove', 'Attach a proof to every breaking change: the request that worked at the baseline and fails now')
30
+ .option('--security', 'Also block security regressions: authentication removed or weakened, scopes dropped, sensitive fields newly exposed')
30
31
  .option('--no-summary', 'Skip the GitHub Actions job summary and annotations')
31
32
  .option('--upload', 'Record this run on your SpecShield dashboard, for the shadow-mode graduation report (Team plan)')
32
33
  .option('--org <key>', 'Org key for --upload (default: gate.org or bdct.org in .specshield.yml)')
@@ -53,6 +54,7 @@ const gate = new Command('gate')
53
54
  ignore: config.ignore || [],
54
55
  usage: usage.usage ? usage : null,
55
56
  prove: Boolean(opts.prove || g.prove),
57
+ security: Boolean(opts.security || g.security),
56
58
  });
57
59
 
58
60
  if (opts.upload || g.upload) r.upload = await upload(r, { ...opts, org: opts.org || g.org });
@@ -151,6 +153,9 @@ function label(c) {
151
153
  return { where, what };
152
154
  }
153
155
 
156
+ const isSecurity = (c) => c.category === 'security';
157
+ const noun = (list) => (list.every(isSecurity) ? 'security regression' : list.some(isSecurity) ? 'blocking change' : 'breaking change');
158
+
154
159
  function render(r) {
155
160
  const lines = [''];
156
161
  lines.push(chalk.bold(` SpecShield™ Gate — ${r.spec}`));
@@ -172,8 +177,8 @@ function render(r) {
172
177
  (r.nonBreaking ? chalk.gray(` · ${plural(r.nonBreaking, 'non-breaking change')}`) : ''));
173
178
  } else {
174
179
  const head = r.verdict === 'would-block'
175
- ? chalk.yellow.bold(` ▲ Shadow mode: would have blocked this change — ${plural(r.blocking.length, 'breaking change')}`)
176
- : chalk.red.bold(` ✖ ${plural(r.blocking.length, 'breaking change')} block${r.blocking.length === 1 ? 's' : ''} this change`);
180
+ ? chalk.yellow.bold(` ▲ Shadow mode: would have blocked this change — ${plural(r.blocking.length, noun(r.blocking))}`)
181
+ : chalk.red.bold(` ✖ ${plural(r.blocking.length, noun(r.blocking))} block${r.blocking.length === 1 ? 's' : ''} this change`);
177
182
  lines.push(head);
178
183
  for (const c of r.blocking) {
179
184
  const { where, what } = label(c);
@@ -188,6 +193,15 @@ function render(r) {
188
193
  }
189
194
  }
190
195
 
196
+ if (r.security && r.security.warnings.length) {
197
+ lines.push('');
198
+ lines.push(chalk.bold(` Security review (${r.security.warnings.length}, not blocking)`));
199
+ for (const c of r.security.warnings) {
200
+ const { where, what } = label(c);
201
+ lines.push(` ${chalk.yellow('▲')} ${what}${where ? chalk.gray(` · ${where}`) : ''}`);
202
+ }
203
+ }
204
+
191
205
  if (r.waived.length) {
192
206
  lines.push('');
193
207
  lines.push(chalk.bold(` Waived (${r.waived.length})`));
@@ -249,7 +263,8 @@ function annotate(r) {
249
263
  const file = `file=${escProp(r.spec)}`;
250
264
  for (const c of r.blocking) {
251
265
  const { where, what } = label(c);
252
- const title = r.verdict === 'would-block' ? 'Breaking API change (shadow mode)' : 'Breaking API change';
266
+ const kind = isSecurity(c) ? 'API security regression' : 'Breaking API change';
267
+ const title = r.verdict === 'would-block' ? `${kind} (shadow mode)` : kind;
253
268
  const extra = c.expiredWaiver ? ` — waiver expired ${c.expiredWaiver.expires}` : '';
254
269
  process.stdout.write(`::${level} ${file},title=${escProp(title)}::${esc(`${what}${where ? ` (${where})` : ''}${extra}`)}\n`);
255
270
  }
@@ -273,8 +288,8 @@ function markdown(r) {
273
288
  else if (r.blocking.length === 0) md.push(`No breaking changes block this change${r.waived.length ? ` (${r.waived.length} waived)` : ''}.`);
274
289
  else {
275
290
  md.push(r.verdict === 'would-block'
276
- ? `**Shadow mode:** would have blocked this change — ${plural(r.blocking.length, 'breaking change')}.`
277
- : `**${plural(r.blocking.length, 'breaking change')}** block this change.`);
291
+ ? `**Shadow mode:** would have blocked this change — ${plural(r.blocking.length, noun(r.blocking))}.`
292
+ : `**${plural(r.blocking.length, noun(r.blocking))}** block this change.`);
278
293
  md.push('');
279
294
  md.push('| Change | Where | |');
280
295
  md.push('|---|---|---|');
@@ -294,6 +309,15 @@ function markdown(r) {
294
309
  md.push('');
295
310
  md.push(`Intended? Add a waiver with an owner, a reason and an expiry: \`${waiveCommand(r.blocking[0], r.waivers.file)}\``);
296
311
  }
312
+ if (r.security && r.security.warnings.length) {
313
+ md.push('');
314
+ md.push(`**Security review (not blocking):**`);
315
+ md.push('');
316
+ for (const c of r.security.warnings) {
317
+ const { where, what } = label(c);
318
+ md.push(`- ${cell(what)}${where ? ` — ${cell(where)}` : ''}`);
319
+ }
320
+ }
297
321
  if (r.waived.length) {
298
322
  md.push('');
299
323
  md.push('<details><summary>Waived</summary>');
@@ -158,7 +158,7 @@ function validateConfig(config, filePath) {
158
158
  throw new Error(`Config error in "${filePath}": gate.${key} must be a string`);
159
159
  }
160
160
  }
161
- for (const key of ['upload', 'prove']) {
161
+ for (const key of ['upload', 'prove', 'security']) {
162
162
  if (g[key] !== undefined && typeof g[key] !== 'boolean') {
163
163
  throw new Error(`Config error in "${filePath}": gate.${key} must be a boolean`);
164
164
  }
@@ -170,6 +170,7 @@ function validateConfig(config, filePath) {
170
170
  maxWaiverDays: g.maxWaiverDays !== undefined ? Number(g.maxWaiverDays) : undefined,
171
171
  upload: g.upload,
172
172
  prove: g.prove,
173
+ security: g.security,
173
174
  org: g.org,
174
175
  };
175
176
  }
@@ -11,6 +11,7 @@ const { resolveBaseline } = require('./baseline');
11
11
  const G = require('./git');
12
12
  const W = require('./waivers');
13
13
  const P = require('../prove');
14
+ const { securityDiff } = require('../security/diff');
14
15
 
15
16
  /**
16
17
  * One gate run: the spec at the merge base vs the spec in the working tree,
@@ -24,7 +25,7 @@ async function runGate(opts) {
24
25
  const {
25
26
  spec, cwd = process.cwd(), base, env = process.env, fetch = true,
26
27
  mode = 'blocking', waiversFile = W.DEFAULT_FILE, maxWaiverDays = W.DEFAULT_MAX_DAYS,
27
- ignore = [], usage = null, now = Date.now(), prove = false,
28
+ ignore = [], usage = null, now = Date.now(), prove = false, security = false,
28
29
  } = opts;
29
30
  if (!['blocking', 'shadow'].includes(mode)) throw new Error(`mode must be "blocking" or "shadow", got "${mode}"`);
30
31
 
@@ -100,6 +101,14 @@ async function runGate(opts) {
100
101
  out.breaking = out.breaking.map((c) => ({ ...c, proof: P.proofFor(c, proofs) }));
101
102
  out.proofs = P.summarize(out.breaking);
102
103
  }
104
+ if (security && docs) {
105
+ // Not subject to usage data: an endpoint nobody calls yet can still be left open.
106
+ const s = securityDiff(docs.baseDoc, docs.headDoc);
107
+ const hit = (c) => ignore.some((p) => (c.description || '').includes(p));
108
+ out.ignored = [...out.ignored, ...s.breaking.filter(hit)];
109
+ out.breaking = [...s.breaking.filter((c) => !hit(c)).map(withKey), ...out.breaking];
110
+ out.security = { warnings: s.warnings.filter((c) => !hit(c)).map(withKey) };
111
+ }
103
112
  const { blocking, waived, used } = W.applyWaivers(out.breaking, headW.waivers, now);
104
113
  out.blocking = blocking;
105
114
  out.waived = waived;
@@ -0,0 +1,304 @@
1
+ 'use strict';
2
+
3
+ /**
4
+ * Security regressions between two specs. Works on the raw documents, because
5
+ * normalizeSpec has no notion of `security`.
6
+ *
7
+ * breaking AUTH_REMOVED, AUTH_SCOPE_REDUCED, AUTH_WEAKENED,
8
+ * ENDPOINT_ADDED_WITHOUT_AUTH, SENSITIVE_FIELD_EXPOSED
9
+ * warnings AUTH_CHANGED, PUBLIC_ENDPOINT_ADDED, SENSITIVE_FIELD_EXPOSED (lower tiers)
10
+ *
11
+ * A requirement is a list of alternatives (OR), each a map of scheme → scopes
12
+ * (AND). The new requirement is at least as strict when every new alternative
13
+ * implies some old one: a credential that passes it would have passed before.
14
+ */
15
+
16
+ const METHODS = ['get', 'post', 'put', 'patch', 'delete', 'head', 'options'];
17
+ const MAX_DEPTH = 12;
18
+
19
+ function securityDiff(baseDoc, headDoc) {
20
+ const base = operations(baseDoc);
21
+ const head = operations(headDoc);
22
+ const found = [];
23
+ for (const [key, h] of head) {
24
+ const b = base.get(key);
25
+ const headReq = requirement(headDoc, h.op);
26
+ if (!b) found.push(...addedEndpoint(h, headReq, headDoc));
27
+ else found.push(...authChange(b, h, requirement(baseDoc, b.op), headReq, baseDoc, headDoc));
28
+ found.push(...exposedFields(b, h, baseDoc, headDoc, headReq));
29
+ }
30
+ const merged = merge(found);
31
+ return {
32
+ breaking: merged.filter((f) => f.severity === 'error'),
33
+ warnings: merged.filter((f) => f.severity !== 'error'),
34
+ };
35
+ }
36
+
37
+ function operations(doc) {
38
+ const ops = new Map();
39
+ for (const [path, item] of Object.entries((doc && doc.paths) || {})) {
40
+ if (!item || typeof item !== 'object') continue;
41
+ for (const method of METHODS) {
42
+ if (!item[method] || typeof item[method] !== 'object') continue;
43
+ // A renamed path parameter is the same operation.
44
+ ops.set(`${method} ${path.replace(/\{[^}]+\}/g, '{}')}`, { path, method, op: item[method] });
45
+ }
46
+ }
47
+ return ops;
48
+ }
49
+
50
+ // ─── authentication ─────────────────────────────────────────────────────────
51
+
52
+ /** An operation's own `security` wins, even when empty; otherwise the document's. */
53
+ function requirement(doc, op) {
54
+ const source = Array.isArray(op.security) ? 'operation' : Array.isArray(doc.security) ? 'global' : 'none';
55
+ const raw = source === 'operation' ? op.security : source === 'global' ? doc.security : [];
56
+ const alts = raw.filter((a) => a && typeof a === 'object').map((a) => {
57
+ const out = {};
58
+ for (const [scheme, scopes] of Object.entries(a)) out[scheme] = Array.isArray(scopes) ? scopes : [];
59
+ return out;
60
+ });
61
+ return { source, alternatives: alts.length ? alts : [{}] };
62
+ }
63
+
64
+ const isAnonymous = (alt) => Object.keys(alt).length === 0;
65
+ const allowsAnonymous = (req) => req.alternatives.some(isAnonymous);
66
+ const subset = (a, b) => a.every((x) => b.includes(x));
67
+
68
+ function schemeOf(doc, name) {
69
+ const all = (doc.components && doc.components.securitySchemes) || doc.securityDefinitions || {};
70
+ let s = all[name];
71
+ if (s && s.$ref) s = all[String(s.$ref).split('/').pop()];
72
+ return s && typeof s === 'object' ? s : null;
73
+ }
74
+
75
+ /** Relative strength of one scheme; null when the spec doesn't define it. */
76
+ function strength(doc, name) {
77
+ const s = schemeOf(doc, name);
78
+ if (!s) return null;
79
+ const type = String(s.type || '').toLowerCase();
80
+ if (type === 'mutualtls') return 4;
81
+ if (type === 'oauth2' || type === 'openidconnect') return 3;
82
+ if (type === 'basic') return 1; // Swagger 2.0
83
+ if (type === 'apikey') return String(s.in).toLowerCase() === 'query' ? 1 : 2; // in a URL it ends up in logs
84
+ if (type === 'http') return String(s.scheme).toLowerCase() === 'basic' ? 1 : 3;
85
+ return null;
86
+ }
87
+
88
+ /** An alternative is as strong as its strongest scheme. */
89
+ function altStrength(doc, alt) {
90
+ const names = Object.keys(alt);
91
+ if (!names.length) return 0;
92
+ const all = names.map((n) => strength(doc, n));
93
+ return all.includes(null) ? null : Math.max(...all);
94
+ }
95
+
96
+ function implies(h, b, headDoc, baseDoc) {
97
+ if (!Object.keys(b).every((s) => s in h && subset(b[s], h[s]))) return false;
98
+ const hs = altStrength(headDoc, h);
99
+ const bs = altStrength(baseDoc, b);
100
+ return hs === null || bs === null || hs >= bs;
101
+ }
102
+
103
+ function authChange(b, h, baseReq, headReq, baseDoc, headDoc) {
104
+ const loose = headReq.alternatives.filter((alt) => !baseReq.alternatives.some((x) => implies(alt, x, headDoc, baseDoc)));
105
+ if (!loose.length) return [];
106
+ const ep = endpoint(h);
107
+ const was = describeReq(baseReq);
108
+ const global = baseReq.source === 'global' && headReq.source !== 'operation';
109
+ const at = global ? 'The API-wide security requirement' : ep;
110
+ const finding = (type, severity, field, description) => ({
111
+ ...change(type, h, severity, field, description),
112
+ ...(global ? { mergeAs: `${type}|${field || ''}|${description}` } : {}),
113
+ });
114
+
115
+ if (loose.some(isAnonymous)) {
116
+ return [finding('AUTH_REMOVED', 'error', null, `Security: ${at} no longer requires authentication (was ${was}) — anyone can call ${global ? 'these endpoints' : 'it'}`)];
117
+ }
118
+ for (const alt of loose) {
119
+ for (const x of baseReq.alternatives) {
120
+ const names = Object.keys(x);
121
+ if (names.length !== Object.keys(alt).length || !names.every((s) => s in alt)) continue;
122
+ const scheme = names.find((s) => !subset(x[s], alt[s]));
123
+ if (scheme && names.every((s) => subset(alt[s], x[s]))) {
124
+ const dropped = x[scheme].filter((s) => !alt[scheme].includes(s));
125
+ return [finding('AUTH_SCOPE_REDUCED', 'error', scheme, `Security: ${at} no longer requires ${dropped.length === 1 ? 'scope' : 'scopes'} ${dropped.join(', ')} on ${scheme}`)];
126
+ }
127
+ }
128
+ }
129
+ const floor = Math.min(...baseReq.alternatives.map((x) => altStrength(baseDoc, x) ?? Infinity));
130
+ for (const alt of loose) {
131
+ const s = altStrength(headDoc, alt);
132
+ const fewer = baseReq.alternatives.some((x) => Object.keys(alt).length < Object.keys(x).length && Object.keys(alt).every((n) => n in x));
133
+ if (fewer || (s !== null && s < floor)) {
134
+ return [finding('AUTH_WEAKENED', 'error', Object.keys(alt).join('+'), `Security: ${at} now accepts weaker authentication: ${describeAlt(alt, headDoc)} (was ${was})`)];
135
+ }
136
+ }
137
+ return [finding('AUTH_CHANGED', 'warning', Object.keys(loose[0]).join('+'), `Security: ${at} now accepts ${describeAlt(loose[0], headDoc)} (was ${was}) — check it grants no more than before`)];
138
+ }
139
+
140
+ /**
141
+ * A new endpoint with no security at all, in an API that protects others, was
142
+ * most likely forgotten; `security: []` was written on purpose, so it's only flagged.
143
+ */
144
+ function addedEndpoint(h, req, doc) {
145
+ if (!allowsAnonymous(req)) return [];
146
+ if (req.source === 'operation') {
147
+ return [change('PUBLIC_ENDPOINT_ADDED', h, 'warning', null, `Security: new endpoint ${endpoint(h)} is public (security: [])`)];
148
+ }
149
+ if (!declaresAuth(doc)) return [];
150
+ return [change('ENDPOINT_ADDED_WITHOUT_AUTH', h, 'error', null, `Security: new endpoint ${endpoint(h)} has no authentication, unlike the rest of this API — add security, or "security: []" if it is meant to be public`)];
151
+ }
152
+
153
+ /** Specs that declare no auth anywhere say nothing about which endpoints are public. */
154
+ function declaresAuth(doc) {
155
+ return [...operations(doc).values()].some((o) => !allowsAnonymous(requirement(doc, o.op)));
156
+ }
157
+
158
+ function describeAlt(alt, doc) {
159
+ return Object.entries(alt).map(([name, scopes]) => {
160
+ const s = schemeOf(doc, name);
161
+ const kind = !s ? '' : s.type === 'apiKey' ? ` (API key in ${s.in})` : s.type === 'http' ? ` (${s.scheme})` : s.type === 'basic' ? ' (basic)' : '';
162
+ return `${name}${kind}${scopes.length ? ` [${scopes.join(', ')}]` : ''}`;
163
+ }).join(' + ') || 'no authentication';
164
+ }
165
+
166
+ function describeReq(req) {
167
+ return req.alternatives.map((a) => (isAnonymous(a) ? 'anonymous' : Object.entries(a).map(([n, s]) => `${n}${s.length ? ` [${s.join(', ')}]` : ''}`).join(' + '))).join(' or ');
168
+ }
169
+
170
+ // ─── sensitive fields in responses ──────────────────────────────────────────
171
+
172
+ const CREDENTIAL = /(^|_)(password|passwd|pwd|passphrase|secret|private_key|api_key|apikey)$/;
173
+ const REGULATED = /(^|_)(ssn|social_security_number|aadhaar|cvv|cvc|card_number|credit_card_number|passport_number|tax_id|bank_account_number)$/;
174
+ const TOKEN = /(^|_)(access_token|refresh_token|id_token|auth_token|session_token|bearer_token|jwt|session_id)$/;
175
+ const PERSONAL = /(^|_)(email|email_address|phone|phone_number|date_of_birth|dob|birthdate|birth_date|home_address)$/;
176
+ // The name has to end in the term: password_changed_at, secret_scanning_status and
177
+ // cvc_check are facts about a secret, not the secret.
178
+ const words = (name) => String(name)
179
+ .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
180
+ .replace(/[^A-Za-z0-9]+/g, '_')
181
+ .toLowerCase();
182
+
183
+ /** credential | regulated | token | personal | null */
184
+ function sensitivity(name, schema) {
185
+ const types = [].concat((schema && schema.type) || 'string');
186
+ if (!types.includes('string')) return null;
187
+ const w = words(name);
188
+ if (schema && schema.format === 'password') return 'credential';
189
+ if (CREDENTIAL.test(w)) return 'credential';
190
+ if (REGULATED.test(w)) return 'regulated';
191
+ if (TOKEN.test(w)) return 'token';
192
+ if (PERSONAL.test(w) || (schema && schema.format === 'email')) return 'personal';
193
+ return null;
194
+ }
195
+
196
+ const LABEL = { credential: 'a credential', regulated: 'regulated personal data', token: 'a token', personal: 'personal data' };
197
+
198
+ function exposedFields(b, h, baseDoc, headDoc, headReq) {
199
+ const before = new Set(b ? sensitiveResponseFields(baseDoc, b.op).map((f) => leaf(f.path)) : []);
200
+ const isPublic = allowsAnonymous(headReq) && (headReq.source === 'operation' || declaresAuth(headDoc));
201
+ const seen = new Set();
202
+ const out = [];
203
+ for (const f of sensitiveResponseFields(headDoc, h.op)) {
204
+ const name = leaf(f.path);
205
+ if (before.has(name) || seen.has(name)) continue;
206
+ seen.add(name);
207
+ const high = f.tier === 'credential' || f.tier === 'regulated' || isPublic;
208
+ const where = isPublic ? 'a public response' : 'a response';
209
+ const via = f.path === name ? '' : ` (at ${f.path})`;
210
+ out.push({
211
+ ...change('SENSITIVE_FIELD_EXPOSED', h, high ? 'error' : 'warning', name, `Security: new field "${name}"${via} in ${where} looks like ${LABEL[f.tier]}`),
212
+ mergeAs: `exposed|${name}|${f.tier}|${isPublic}`,
213
+ });
214
+ }
215
+ return out;
216
+ }
217
+
218
+ const leaf = (p) => p.split('.').pop().replace(/\[\]$/, '');
219
+
220
+ /** Sensitive fields a 2xx response can carry, with their paths. */
221
+ function sensitiveResponseFields(doc, op) {
222
+ const out = [];
223
+ const memo = memoFor(doc);
224
+ for (const [status, raw] of Object.entries(op.responses || {})) {
225
+ if (!/^2/.test(status)) continue;
226
+ const res = deref(doc, raw);
227
+ if (!res) continue;
228
+ const schemas = res.schema ? [res.schema] : Object.entries(res.content || {})
229
+ .filter(([type]) => /json/i.test(type)).map(([, m]) => m && m.schema).filter(Boolean);
230
+ for (const s of schemas) out.push(...walk(doc, s, memo, new Set(), 0));
231
+ }
232
+ return out;
233
+ }
234
+
235
+ const memos = new WeakMap();
236
+ function memoFor(doc) {
237
+ if (!memos.has(doc)) memos.set(doc, new Map());
238
+ return memos.get(doc);
239
+ }
240
+
241
+ function deref(doc, node) {
242
+ let n = node;
243
+ for (let i = 0; n && n.$ref && i < 20; i++) {
244
+ if (typeof n.$ref !== 'string' || !n.$ref.startsWith('#/')) return null;
245
+ n = n.$ref.slice(2).split('/').reduce((o, k) => (o ? o[k.replace(/~1/g, '/').replace(/~0/g, '~')] : undefined), doc);
246
+ }
247
+ return n && typeof n === 'object' ? n : null;
248
+ }
249
+
250
+ /** [{path, tier}] relative to this schema. Named schemas are memoized; cycles are cut. */
251
+ function walk(doc, node, memo, stack, depth) {
252
+ if (!node || depth > MAX_DEPTH) return [];
253
+ if (node.$ref) {
254
+ if (memo.has(node.$ref)) return memo.get(node.$ref);
255
+ if (stack.has(node.$ref)) return [];
256
+ stack.add(node.$ref);
257
+ const r = walk(doc, deref(doc, node), memo, stack, depth + 1);
258
+ stack.delete(node.$ref);
259
+ memo.set(node.$ref, r);
260
+ return r;
261
+ }
262
+ const out = [];
263
+ for (const key of ['allOf', 'oneOf', 'anyOf']) {
264
+ if (Array.isArray(node[key])) for (const s of node[key]) out.push(...walk(doc, s, memo, stack, depth + 1));
265
+ }
266
+ if (node.items) out.push(...walk(doc, node.items, memo, stack, depth + 1).map((f) => ({ ...f, path: `[].${f.path}` })));
267
+ if (node.additionalProperties && typeof node.additionalProperties === 'object') {
268
+ out.push(...walk(doc, node.additionalProperties, memo, stack, depth + 1));
269
+ }
270
+ for (const [name, raw] of Object.entries(node.properties || {})) {
271
+ const prop = deref(doc, raw);
272
+ if (!prop || prop.writeOnly) continue;
273
+ const tier = sensitivity(name, prop);
274
+ if (tier) out.push({ path: name, tier });
275
+ out.push(...walk(doc, raw, memo, stack, depth + 1).map((f) => ({ ...f, path: `${name}.${f.path}` })));
276
+ }
277
+ return out.map((f) => ({ ...f, path: f.path.replace(/^\[\]\./, '') }));
278
+ }
279
+
280
+ // ─── findings ───────────────────────────────────────────────────────────────
281
+
282
+ const endpoint = (h) => `${h.method.toUpperCase()} ${h.path}`;
283
+
284
+ function change(type, h, severity, field, description) {
285
+ return { type, category: 'security', path: h.path, method: h.method, field, severity, description };
286
+ }
287
+
288
+ /** One finding for a cause shared by many endpoints: a global requirement or a shared schema. */
289
+ function merge(found) {
290
+ const out = [];
291
+ const groups = new Map();
292
+ for (const f of found) {
293
+ const { mergeAs, ...c } = f;
294
+ const ep = `${c.method.toUpperCase()} ${c.path}`;
295
+ const g = mergeAs && groups.get(mergeAs);
296
+ if (g) { g.affectedEndpoints.push(ep); continue; }
297
+ const item = { ...c, affectedEndpoints: [ep] };
298
+ if (mergeAs) groups.set(mergeAs, item);
299
+ out.push(item);
300
+ }
301
+ return out;
302
+ }
303
+
304
+ module.exports = { securityDiff, requirement, sensitivity };