footing 0.3.1

Feature-gated foundations for Rust backend services
Documentation
# Embedded RapiDoc assets

RapiDoc **9.3.8**, enabled by the optional `rapidoc-embedded` feature.
The preset targets this version's native `rapi-doc` attributes.

Source: <https://registry.npmjs.org/rapidoc/-/rapidoc-9.3.8.tgz>

- Tarball SHA-256: `b04086a71c2002169c43e5b0f25d7f694b20eee7a95ddc233b491cf9a54b3ef0`
- Original `package/dist/rapidoc-min.js` SHA-256:
  `affbd173a65e870e18f392cca963113bcdafb6e50e88cd2f6a834a65b22db94d`
- Packaged upstream bundle SHA-256, before the local patches:
  `041fb6ba5d65e5c240dc5039a2883290928882b7ab32542e3d3502cebb3eb73d`
- Distributed bundle SHA-256:
  `2699c3a428d7ba3f47b6c93262b48beb80504d3208a999bf84b781a8538f9cd7`

Packaging changes rename the emitted license-comment link to
`ui.LICENSE.txt` and remove the source-map comment (the map is not shipped).
The local OAuth, path-filter, webhook, navigation and server-selection patches below are the
only JavaScript behavior changes.
The bundle remains a standalone classic script.
Consumers need no npm, Node, build script or build-time network access.

## OAuth security patch

The upstream authorization helpers use one fixed PKCE verifier/challenge and
accept popup messages without checking their origin, source window or state.
The readable section between `footing OAuth security patch start` and
`footing OAuth security patch end` in `rapidoc-min.js` replaces those three
helpers (`RR`, `FR`, `MR`), and the unused fixed verifier/challenge constants
(`ER`, `kR`) are removed. The bundle is the single source of the local patch.
The original source is
<https://github.com/rapi-doc/RapiDoc/blob/v9.3.8/src/templates/security-scheme-template.js>.

The patch generates fresh state, nonce and PKCE verifier values with browser
cryptographic randomness for every popup authorization. Enabling PKCE computes
an S256 challenge from that transaction's verifier. Only a message from the
expected popup, receiver origin and state can complete the expected grant.
Unrelated or malformed messages leave the listener active. Successful callbacks
are consumed once; closed popups, cancellation, replacement and a five-minute
deadline clean up listeners and outstanding requests. Concurrent schemes remain
independent; starting a new attempt for the same scheme cancels its predecessor.
Changing the loaded specification also prevents an old attempt applying a token.
Provider errors are displayed as text and unsuccessful or malformed token
responses never install credentials. Client credentials and password grants
retain their supported form/header client authentication options.

The native OAuth form renderer (`LR`) resolves authorization, token and refresh
URLs against the complete selected server URL, following
[OpenAPI's relative API URL rules](https://spec.openapis.org/oas/v3.1.1.html#relative-references-in-api-urls).
This preserves server path prefixes for relative endpoints and resolves
protocol-relative URLs before starting authorization. Its small URL-resolution
replacement is checked alongside the readable OAuth helper patch.

Footing supplies `oauth-receiver.html` and its external `oauth-receiver.js` beside
the documentation page. The receiver forwards code, implicit-token and error
responses with their state, clears response parameters from browser history,
and targets only its own origin. Missing, duplicate or ambiguous OAuth response
parameters are rejected. A custom `oauth-receiver` must be on the documentation
origin and implement this message format. The embedded preset selects the local
receiver and disables credential persistence unless explicitly enabled.

## Path filter correction

The upstream `match-type=regex` filter tests the pattern against itself instead
of the endpoint. The local correction tests the existing lowercased
`${method} ${path}` value, preserving case-insensitive matching and badge
filtering. A pattern such as `^get /items$` therefore retains `GET /items`.

Filtering now uses the parser's existing HTTP method list so it only examines
operations. Retained paths keep their shared parameters, servers, descriptions,
references and extensions, including null-valued extensions. Previously a
method-specific pattern discarded path-level servers and sent try-it requests
to the document's default server. Paths with no retained operations are removed
even when they contain metadata.

The internal rendering copy also excludes non-path entries in the Paths Object.
[OpenAPI requires path names to start with `/`](https://spec.openapis.org/oas/v3.1.1.html#paths-object),
while `x-*` extensions may hold arbitrary JSON. Previously null extensions broke
loading, and extension objects containing `get` could render as fake endpoints.
The original specification served by `openapi.json` and its download is unchanged.

## Webhook rendering correction

[OpenAPI webhook names](https://spec.openapis.org/oas/v3.1.1.html#openapi-object)
are independent of ordinary path names. The upstream renderer merges both maps,
so a webhook named `/items` silently replaces an ordinary `/items` operation.
The correction renders their entries separately and reads each operation's
parameters and servers from its own Path Item. Webhooks keep their display names
and receive `webhook-` navigation ID prefixes, so identical names and methods
remain independently navigable. Ordinary navigation IDs retain their existing
format. Rendering no longer copies webhooks into paths or adds `_type` markers;
the original served and downloaded specification remains unchanged.

## Navigation collision correction

The upstream ID normalization maps both `/items/{id}` and `/items/-id-` to
`get-/items/-id-`. In focused mode, selecting the latter then shows the former.
The renderer now preserves the first operation's existing ID and assigns later
collisions an `operation-` ID containing the method, webhook distinction and the
hexadecimal code points of the original name. This separate namespace cannot
collide with ordinary method-prefixed IDs, and distinct names remain distinct.
An operation shown under several tags retains one ID across those tags.

IDs are repeatable for the same input order and unaffected by display sorting;
browser navigation and reloading the resulting URL select the same operation.
Removing or reordering colliding entries can change which operation keeps the
original ID. No stability across those specification or filter changes is claimed.
Unambiguous existing deep links retain their original format.

## Operation server precedence

[Operation-level servers override path-level servers](https://spec.openapis.org/oas/v3.1.1.html#operation-object).
The upstream renderer concatenates both lists, selecting the path server first
and sending try-it requests to the wrong endpoint. The correction uses the
operation list when present and inherits the path list when omitted. Explicit
empty lists remain empty so the native request component applies its existing
fallback to the selected document server. Path and webhook operations retain
their independent server choices.

## Patch verification

Verify the distributed patches offline from the repository root:

```sh
node --test tests/rapidoc_security.test.cjs
```

The integrity test checks the entire bundle against the distributed SHA-256
recorded above and checks that the OAuth section markers occur exactly once.
It detects unrecorded bundle changes; it does not reconstruct the upstream bundle
or establish that a recorded change is correct. The upstream archive and bundle
checksums remain available above for reviewing updates against the original.
The same test suite exercises the functions extracted from the distributed bundle
and the actual callback and initialization scripts with browser APIs simulated
in memory. It uses only Node.js built-in modules and never modifies the assets.

Edit the marked OAuth section directly in `rapidoc-min.js`. Review all bundle
changes, update the distributed SHA-256 recorded here, and run the tests above.
No duplicate patch sources, patch generator or build step is required.

## Other embedded behavior

The preset sets `load-fonts=false` before connecting the element, which avoids
RapiDoc's CDN font requests. System fonts are used. Applications own external
references, Markdown images, API servers and any overridden resource URLs.
Disabling the preset restores upstream font-loading behavior.

`LICENSES.txt` preserves the upstream license and complete emitted notices.
It also includes a conservative superset of dependency license texts from the
runtime dependency closure in the upstream v9.3.8 package-lock.json:
<https://github.com/rapi-doc/RapiDoc/blob/v9.3.8/package-lock.json>.
This includes dependencies of the prebundled OpenAPI parser and some packages
that are not used by the browser build; it is not a reconstructed bundle SBOM.
Package tarballs were verified against the lockfile integrity hashes.

The parser package has no standalone license; its author and MIT declaration
from package.json are retained with the MIT terms. The Lit SSR shim license
comes from its release tag. Short Unique ID's copyright and license declaration
come from its packaged README, accompanied by the full Apache 2.0 terms.
Each notice records its source.

When updating, verify archive integrity, refresh notices and hashes, reassess
and reapply the isolated OAuth and path-filter patches, update
`EMBEDDED_RAPIDOC_VERSION`, and check native options, initialization order,
offline loading and CSP behavior against the new bundle.