feat(http-utils): add anonymousEndpoints override and drop GET /slack/events from the anonymous auth bypass

[JayKid]

Companion to adobe/spacecat-api-service#3229. Context is in VULN-39365 (Jira) —
deliberately not restated here, as this is a public repository and the fix is not yet
deployed.

Problem

ANONYMOUS_ENDPOINTS in authWrapper is a library-level authentication bypass that every
consumer of this wrapper inherits. It listed both GET and POST /slack/events, so any
service mounting authWrapper gets an unauthenticated /slack/events whether or not it
defends that route by other means.

Changes

1. GET /slack/events removed. Slack only ever POSTs events and interactive payloads,
and a GET carries no body to sign — so that entry could never be backed by a signature check
and existed purely as an unauthenticated entry point.

2. POST /slack/events deliberately stays. Worth being explicit, since the obvious
instinct is to remove both:

• The Slack signature check added in fix(security): verify Slack request signatures on /slack/events spacecat-api-service#3229 (slackSignatureWrapper)
  is mounted outside this wrapper and therefore runs before it.
• Slack presents no SpaceCat credential, so removing the entry would make every legitimate
  Slack request 401.

The security contract is now documented on the constant: an entry here means this library
authenticates nothing, so the consumer MUST authenticate the route by other means.

3. New optional opts.anonymousEndpoints. Lets a consumer override the default list —
[] opts out of the inherited bypass entirely. A service that does not verify Slack
signatures should pass [] rather than silently inheriting a route it is not defending.
Defaults to the existing list, so this is backwards compatible.

Deploy ordering

None required — the two PRs are independent in either order:

• api-service first → GET /slack/events is already gone from its route table (404).
• shared first → api-service's not-yet-removed GET route falls through to the
  authentication manager and 401s, which is strictly safer than today.

Testing

npm test -w packages/spacecat-shared-http-utils: 527 passing, auth-wrapper.js at
100% statements / branches / functions / lines. Lint clean.

New tests cover: POST /slack/events still anonymous; GET /slack/events now reaches the
auth manager and 401s; an anonymousEndpoints: [] override disabling the bypass; an
override naming a different route; and a non-array override falling back to the default.

Change Management

cm-assessment: v1
changeType: standard
impact: unnoticeable
risk: minor
scope: multi-repo
relatedPRs: ["adobe/spacecat-api-service#3229"]
rationale: "Narrows a library-level auth bypass by removing a route that could never be signature-verified, and adds a backwards-compatible opt-out. Only ever restricts access, so it cannot widen exposure. The realistic failure mode is over-rejection of internal Slack bot traffic, which is reversible by pinning the previous package version. No schema, data or breaking API change -- the new option is optional and defaults to current behaviour."
recommendations: "Release before or after adobe/spacecat-api-service#3229 -- no ordering dependency. Consumers of authWrapper that do not verify Slack signatures should adopt anonymousEndpoints: []."
backout: "Revert the commit and release the previous package version; consumers pin the prior @adobe/spacecat-shared-http-utils."

[github-actions]

This PR will trigger a patch release when merged.

[dzehnder]

Hey @JayKid,

Verdict: Request changes - correct, minimal, well-tested library fix; one security-contract doc line overstates what the opt-out actually delivers.
Complexity: MEDIUM - small 2-file diff, but a library-level auth-bypass surface every consumer inherits.
Changes: removes GET /slack/events from authWrapper's default anonymous bypass and adds an optional anonymousEndpoints override (2 files).

Must fix before merge

1. [Important] JSDoc claims anonymousEndpoints: [] "disables the bypass entirely" - auth-wrapper.js:46 (details inline). The POST /hooks/site-detection/* prefix and OPTIONS bypasses are separate unconditional clauses the option never touches, so a consumer that passes [] for lockdown still ships two unauthenticated bypasses. Doc-only fix acceptable. Flagged independently by 4 reviewers.

Non-blocking (5): suggestions and nits

• suggestion: add tests pinning that anonymousEndpoints: [] still bypasses OPTIONS and POST /hooks/site-detection/*, and that a non-empty override drops the default POST /slack/events (-> 401) - these are exactly the behaviors the corrected doc most needs to guarantee, and the POST /hooks/site-detection/ true-branch appears unexercised today.
• suggestion: consider feat(http-utils): rather than fix: - this adds a new public option, and this package's changelog precedent (#1693, #1870, #1883) tags new wrapper params feat; semantic-release bumps the version off the type prefix.
• nit: anonymousEndpoints validates array-of-strings but not the 'METHOD /path' uppercase-method shape - a malformed entry like 'post /slack/events' passes validation yet silently never matches (fails closed) - auth-wrapper.js:60.
• nit: src/auth/readme.md and the package README.md version-callout convention were not updated for the new option.
• nit: anonymousEndpoints = opts.anonymousEndpoints retains the caller's array reference; a defensive copy ([...]) after validation removes a mutation footgun.

FYI (verified): among the 4 consumers of this wrapper, only spacecat-api-service serves a /slack/events route, so removing GET from the default is backward-safe; companion adobe/spacecat-api-service#3229 removes that route there. The throw-at-construction validation on bad config is the right call for security-sensitive config.

[dzehnder]

[Important] This line reads "Pass [] to disable the bypass entirely," and the ANONYMOUS_ENDPOINTS contract above says an entry means the library "performs NO authentication for that route." But the runtime guard is:

if (anonymousEndpoints.includes(route)
    || route.startsWith('POST /hooks/site-detection/')
    || method.toUpperCase() === 'OPTIONS') {
  return fn(request, context);

anonymousEndpoints only governs the first clause. A service that passes [] believing it has locked down all anonymous access still exposes POST /hooks/site-detection/* and every OPTIONS request unauthenticated, and neither is reachable through this option.

On a VULN-remediation PR whose value is an accurate mental model of the auth surface, a doc that implies full lockdown is itself a small hazard. Suggest either:

• reword to: "Pass [] to remove the route-based anonymous entries. Note: OPTIONS requests and POST /hooks/site-detection/* bypass authentication unconditionally and are not affected by this option." (and soften the "performs NO authentication" contract to name the full surface), or
• route the hooks-prefix + OPTIONS bypasses through the same override so [] truly means "authenticate everything."

[JayKid]

Thanks @dzehnder — and noted that four reviewers landed on the same doc line independently, which is a fair signal it was actively misleading. Pushed in f6a8ef0 + 85b8010.

Must fix — done (doc route)

You offered two options; I took the reword rather than routing the OPTIONS and hooks bypasses through the override. Reasoning: making [] genuinely mean "authenticate everything" changes runtime behaviour for every consumer of this wrapper, and that doesn't belong in a security fix whose value is a correct mental model rather than a changed auth surface. If we do want [] to mean total lockdown, I'd rather that be its own PR with the blast radius reviewed on its own terms.

The docs now name the full unauthenticated surface in both places — the ANONYMOUS_ENDPOINTS contract block (which previously implied the list was the surface) and the option's JSDoc, using essentially your suggested wording.

Non-blocking — addressed

• Tests pinning the corrected contract: anonymousEndpoints: [] still bypasses OPTIONS and POST /hooks/site-detection/*, and a non-empty override drops the default POST /slack/events → 401. You were right that the hooks true-branch was unexercised — it is now.
• feat: vs fix:: agreed, and retitled. The new public option is the semver-relevant change and the precedent you cited (feat(http-utils): allow s2sAuthWrapper routes to accept multiple capabilities #1693, feat(http-utils): secondary FACS resource param + resolver registry in facsWrapper #1870, feat(http-utils): add composite primary-resource resolver hook to facsWrapper #1883) is consistent. The bot now reports a minor release.
• 'METHOD /path' shape: implemented rather than left as a nit. 'post /slack/events' passing validation while never matching is the same silent-misconfiguration class the throw-on-non-array check exists to prevent — a service would get 401s with no signal why. It now throws and names the offending entries. Covers lower-case methods and missing leading slashes.
• Defensive copy: added, with a test that mutating the caller's array post-construction cannot widen the bypass.
• Readme: src/auth/readme.md now documents the option, including that [] does not mean "authenticate everything" and that malformed config throws.

Thanks also for checking the four consumers and confirming only spacecat-api-service serves a /slack/events route — that was the backward-compatibility question I couldn't answer from inside this repo.

534 passing, 100% statements/branches/functions/lines on auth-wrapper.js; lint clean.

[dzehnder]

Hey @JayKid,

Verdict: Approve - the blocking doc-contract finding is resolved and every non-blocking note was addressed. Re-review over 2 new commits since my last pass.
Complexity: MEDIUM - small auth-bypass surface, unchanged.

Previously flagged, now resolved

• [Important] The anonymousEndpoints: [] "disables the bypass entirely" overstatement is fixed - the ANONYMOUS_ENDPOINTS docblock now carries an explicit IMPORTANT note that OPTIONS and POST /hooks/site-detection/* are unconditional and not overridable, the JSDoc reads "Pass [] to remove the route-based entries... this does NOT authenticate everything," and src/auth/readme.md documents the option with the same two caveats.
• Route-shape validation added (ANONYMOUS_ROUTE_SHAPE) - a lower-case method or a missing leading slash now throws at construction instead of silently failing closed.
• Defensive copy of opts.anonymousEndpoints, so a caller mutating the array afterwards cannot widen the bypass.
• Test coverage added for exactly the behaviors the contract needed pinned: [] still bypasses OPTIONS and POST /hooks/site-detection/*; a non-empty override drops the default POST /slack/events; post-construction mutation cannot widen; and both malformed-shape cases throw.

Non-blocking and optional: the fix: vs feat: commit-type note still stands (this adds a new public option), but that is a changelog-signal preference, not a blocker.

[solaris007]

🎉 This PR is included in version @adobe/spacecat-shared-http-utils-v1.37.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀