Portal SDK npm package readiness¶
This document proposes the npm publication scope for third-party developers building Portal plugins in their own repositories. It inventories the packages and records local packaging checks. It does not announce a release, promise a supported platform matrix, or authorize publishing.
The inventory uses repository baseline a3ee4523 plus the packaging changes in
this branch, with Backstage 1.54.9, Backstage CLI 0.36.5, Yarn 4.12.0,
and RHDH CLI 1.10.8 for the original checks. Native export tooling on this
branch now uses RHDH CLI 2.1.2.
Preview metadata preparation¶
The ten candidates below are prepared together as 0.1.0-alpha.0, with
the private: true guard removed and public access metadata. The intended
distribution tag is next. This makes the reviewed candidates publishable, but does not publish them
or authorize a release. Feature packages retain their existing metadata.
Yarn removes private: false when persisting manifests, so the candidates omit
the field. Release checks accept both public forms and reject private packages.
The original packaging results below describe the earlier 0.1.0 private
candidates. Repeat validation for this preview revision. The release workflow
requires completed CodeQL analyses for the exact merged commit and selected
release branch, a clean dependency audit, archive validation and SBOMs before an
approved publication. Local checks cannot substitute another commit's evidence.
First publication remains subject to an agreed bootstrap procedure with the
@ansible namespace owners and security maintainers. All ten names returned
HTTP 404 from the public registry on 2026-11-19. An authorized owner must also
check whether any name already exists privately. See the
publishing prerequisites and bootstrap procedure.
Preview validation results (2026-11-19)¶
On Node 22.22.3, the prepared preview passes declaration emission, all ten
package builds, archive metadata/content checks and an isolated consumer install.
The consumer passes TypeScript, frontend bundling and backend health/runtime
checks. All ten archives have verified SPDX 2.3 SBOMs generated with Syft 1.57.1.
The 63 validation-tooling tests and immutable repository installation also pass.
The full repository suite passes with 457 suites and 6,917 tests, with one suite
and five tests skipped.
Requiring @backstage/catalog-model@1.10.2 in the affected candidate
dependencies and peer ranges moves that dependency path from Zod 3 to Zod 4.
The repository lockfile also selects patched Zod 4.6.7 for compatible Zod 4
ranges. Existing consumers that require Zod 3 are not forced across a major
version. This change therefore does not eliminate every affected Zod dependency
from the repository.
Earlier local audit counts are omitted because their source commit was replaced by rebasing and their output is not retained as reproducible release evidence. They do not establish the current dependency graph or security status. The SCM dependencies merged in #1054 also require a fresh consumer audit.
To reproduce candidate validation and dependency scanning from a reviewed revision, use a fresh checkout and inspect untracked files before running:
The report's includesUncommittedChanges flag detects tracked changes only.
It does not detect untracked inputs, including extra .d.ts files copied from
the consumer fixture. Remove untracked validation inputs before the run or
commit and review them. Do not associate results with a revision based on this
flag alone. Retain the output directory and run the following subshell. It stops
if validation or changing directory fails without closing an interactive shell:
(
set -e
SDK_VALIDATION_DIR=/absolute/path/to/fresh-sdk-validation yarn validate:sdk-packages
cd /absolute/path/to/fresh-sdk-validation/consumer
if yarn npm audit --recursive --environment production --severity info --no-deprecations --json > yarn-audit.ndjson 2> yarn-audit.stderr.log; then
audit_status=0
else
audit_status=$?
fi
printf '%s\n' "$audit_status" > yarn-audit.exit-code
test "$audit_status" -eq 0
)
Retain yarn-audit.ndjson, yarn-audit.stderr.log, yarn-audit.exit-code, the
consumer's yarn.lock and the validation report.json together. A clean audit
can produce empty stdout; empty output alone does not establish success. The
recorded exit status and stderr distinguish that result from a failed command.
Findings or a failed scan keep the final check nonzero. Check the source SHA,
tracked-change flag and untracked-input inventory before associating results
with a revision. Packed-candidate validation, dependency
auditing and exact-commit CodeQL checks are distinct checks; successful PR
package validation alone is not a clean security report. The publishing
workflow requires security evidence for its exact release revision and branch.
These changes retain the Backstage 1.54.9 and RHDH 2.1 baseline. Hosts
consuming the revised peer ranges must satisfy the catalog-model ^1.10.2
minimum. An unchanged RHDH image is not proven to satisfy that minimum by local
source or packed-consumer checks. Live validation of the changed package set
remains a separate requirement.
Remaining dependency paths require compatible upstream fixes or backports:
- The RHDH global-header package pulls in search backend and TechDocs dependencies
that lead to the GraphQL Tools, basic-ftp and file-type findings. The published
3.3.1manifest still declares those dependency paths. - Backstage integration dependencies lead to the three Octokit advisories.
- Backstage core components lead to the PrismJS finding through refractor, and
some UUID findings through material-table. Published react-syntax-highlighter
15.6.6still depends on refractor3.6.0, which requires PrismJS~1.27.0. - The React Router 6 line remains affected by two advisories whose published
patched versions start at
7.18.0. Do not force Router 7 into a Router 6 host. - UUID also has affected paths through the global-header backend dependencies.
These findings still block publication under the existing all-findings policy. No advisory exclusions, blanket cross-major resolutions or security-policy exceptions are introduced. Recheck the exact merged release revision after upstream remediation. See the Zod advisory and React Router advisory.
The latest main CodeQL analyses for 5b34e298350a0a67a5cc6cdaf4097dbf2a7d9ed9
report zero findings within the boundary computed from these archives. This is
baseline evidence only. The preview metadata changes are not included in that
commit, and the release workflow must obtain analyses for the final merged
revision and selected release branch.
Publication scope¶
Publish the SDK libraries and supporting packages needed to author and host external contributors. Feature plugins from the AAP, APME, content management, and content development workspaces are outside this publication proposal.
Authors install only the libraries their contributor imports. Host packages are installed by the application maintainer. The SDK does not require every author to install a host, an authentication backend, or the existing feature plugins.
SDK and host libraries¶
All five use the coordinated 0.1.0-alpha.0 preview metadata described above.
@ansible/portal-extension-common— shared manifest, contribution, operation, and content-type contracts. No internal runtime package dependencies.@ansible/portal-extension-api— frontend contribution APIs, native blueprints, API references, and registration helpers. Depends onportal-extension-common. Native entry point:/alpha.@ansible/portal-plugin-sdk— reusable React components, hooks, styling, notifications, and presentation utilities. No internal runtime package dependencies. Optional for contributors that do not use its UI helpers.@ansible/portal-plugin-node— backend plugin helpers, identity context, operations, entitlements, audit, and health services. Requiresportal-extension-commonas a peer dependency. Optional for frontend-only contributors.@ansible/portal-extension-host— host rendering, validation, contribution composition, and discovery. Depends onportal-extension-api. Native entry point:/alpha. This is a host-maintainer dependency, not a normal contributor-author dependency. It is grouped with libraries for packaging, but should not be presented as an author prerequisite.
Host and runtime plugins¶
All four use the coordinated 0.1.0-alpha.0 preview metadata. Each is a
supporting package, not a dependency every contributor must declare.
@ansible/portal-core— native frontend host and navigation. Depends onportal-extension-apiandportal-extension-host. Exposes/alphaand/app-navin addition to its root entry point.@ansible/portal-rhdh— RHDH global-header adapter. Depends onportal-extension-hostandportal-plugin-sdk. Exposes/alpha. Its RHDH header dependency remains outside the generic author SDK.@ansible/portal-operations-backend— backend operation dispatch. Depends onportal-extension-commonandportal-plugin-node. Exposes/alpha. Install when the host needs the Portal operation API.@ansible/portal-health-backend— backend health aggregation. Depends onportal-plugin-node, whose common-contract peer must also be available. Install when the host needs the Portal health API.
Optional frontend authentication package¶
@ansible/aap-app-auth uses the same 0.1.0-alpha.0 preview metadata.
It exports rhAapAuthApiRef for consumers needing the user's AAP credentials,
and /alpha supplies the native sign-in and profile contribution module.
It depends on portal-extension-api for the profile contribution.
A consumer importing the auth API reference does not need to directly depend
on the other SDK packages or feature plugins. Its package manager still resolves
the auth package's declared transitive dependencies. The host must provide the
configured frontend AAP auth API, the
@ansible/backstage-plugin-auth-backend-module-rhaap-provider backend module,
and auth.providers.rhaap configuration. Publishing or installing the frontend
package alone does not supply these host prerequisites.
The /api-module entry registers the native AAP API without adding sign-in or
profile UI. Hosts may opt into /sign-in and the /profile factory separately.
The combined /alpha entry keeps its existing API/sign-in/profile declarations
and remains automatically discovered for compatibility. It adds the AAP provider row automatically when native user-settings is installed. Existing
dynamic hosts can disable its AAP sign-in/profile extensions to retain standard
RHDH UI. Do not install combined and separate modules together.
The /settings factory preserves standard provider rows and adds AAP connection
controls. Dynamic hosts receive this through /alpha without a Settings
enablement flag. The user-settings plugin is an optional peer,
required only when using that integration. Settings disconnects the AAP credential
session without triggering full host or OIDC browser logout.
See workspaces/aap/plugins/aap-app-auth/README.md for exact composition,
configuration and backend prerequisites. Validate actual
standard RHDH coexistence and Portal login/logout before release; package tests
and packing alone do not establish live host compatibility.
The API/UI separation was checked against upstream baseline 1ee4427d: auth
package tests, repository TypeScript, package build, clean dynamic export and
packed subpath checks passed. The new auth tarball also installed, compiled and
bundled in the separate consumer project. The combined /alpha entry supplies Settings by default, and the frontend
framework ignores the unattached Settings extension when user-settings is absent.
Live RHDH validation exposed a limitation in RHDH CLI 1.10.8: additional feature
loader metadata did not produce a federated loader export. Settings therefore
uses the existing /alpha entry instead. Inspecting package metadata alone does
not verify that the host can load every declared feature. The older ten-package consumer results
below remain tied to their recorded baseline and must be repeated for release.
The optional Settings integration adds coverage for default-on loading and absent-host handling, preserved standard/custom rows, missing AAP API, account display, provider sign-in, disconnection and error reporting. The auth suite now has 44 passing tests, and source-app composition tests pass. The AAP row was verified in the live source Settings page alongside GitHub and GitLab without disconnecting those sessions. Updated packed Settings entry points compile and bundle in the separate consumer, and the clean dynamic export passes.
Local RHDH 2.1.0 validation on Backstage 1.54.9 used the
automation-portal-local Compose harness and freshly exported dynamic artifacts.
The AAP Settings row appeared automatically alongside the standard RHDH shell.
Manual testing confirmed AAP login and, after enabling the Portal profile
integration, full profile-menu Sign out. Settings Sign out remains a provider
credential disconnect and intentionally leaves the AAP browser SSO session active.
This instance used AAP as its host identity. Preserving an authenticated
non-AAP host session during that disconnect needs a separate live check before
claiming support for that configuration.
The tested AAP authorization endpoint returned
Cross-Origin-Opener-Policy: same-origin, and popup login reported a closed window
after the callback completed. The validation host used Backstage's
enableExperimentalRedirectFlow: true configuration to complete login through
same-tab redirects without changing AAP's security headers. These results cover
this local configuration, not a supported compatibility matrix.
The backend provider is an existing host prerequisite, not part of the initial ten-package packing candidate set. If publishing that backend becomes necessary, its current internal runtime dependency chain is:
@ansible/backstage-plugin-auth-backend-module-rhaap-provider(2.3.1) depends on@ansible/backstage-rhaap-common(2.3.1) and@ansible/aap-common(0.1.0).@ansible/backstage-rhaap-commonalso depends on@ansible/aap-common.- All three currently have
private: true. Their existing versions must not be reset or aligned with SDK preview versions without reviewing release history. - Automatic catalog-user provisioning additionally needs the host's provisioning module and catalog configuration. It is not implied by installing an npm auth library.
Internal dependency map¶
Arrows mean a package declares a runtime dependency, except the labeled peer. This is an npm dependency map, not frontend activation or backend startup order. External Backstage, React, Express, and RHDH dependencies are omitted.
graph TD
api[portal-extension-api] --> common[portal-extension-common]
node[portal-plugin-node] -->|peer| common
host[portal-extension-host] --> api
core[portal-core] --> api
core --> host
rhdh[portal-rhdh] --> host
rhdh --> sdk[portal-plugin-sdk]
operations[portal-operations-backend] --> common
operations --> node
health[portal-health-backend] --> node
auth[aap-app-auth] --> api
The internal dependency closure for these ten candidates contains no feature plugin packages. Publish or otherwise make dependencies available before their dependents, including the common-contract peer required by the backend SDK.
For a frontend contribution, the smallest internal dependency chain is
portal-extension-api and portal-extension-common. Add portal-plugin-sdk
only for its UI helpers. A backend author using portal-plugin-node must also
provide its portal-extension-common peer. Host composition packages are
separate from those author dependencies.
The generic contribution SDK remains usable without AAP authentication. Scaffolder field libraries in content development are not included in the first scope. Include those reusable libraries only if an external author's agreed use case requires them. This does not add the Portal scaffolder feature plugin to npm scope.
Historical packaging findings¶
These results describe the original private 0.1.0 candidates. They are retained
as baseline evidence and do not establish readiness of the new preview revision.
Local checks use freshly emitted TypeScript declarations, package builds, and
yarn workspace <package> pack --out <temporary-path>. These commands create
local tarballs only. They do not publish to npm or a container registry.
Confirmed SDK library checks¶
The five libraries above build and pack locally. Their packed manifests resolve
root entry points, declared export subpaths, and declaration paths to files
present in the archive. Internal runtime and peer dependency ranges become
^0.1.0 rather than retaining workspace: references.
Source manifests pointing to src/ are not by themselves a publication defect.
The installed Backstage prepack hook rewrites entry points to built artifacts,
and postpack restores the source manifests. Inspect the generated archive instead
of rewriting source exports solely because they point to TypeScript.
All ten baseline archives retained private: true, preventing publication, and
kept their existing 0.1.0 versions. Each contains a LICENSE file identical
to the repository Apache-2.0 license. The earlier missing-license finding is
resolved for the candidate packages. This checks the repository license text,
not third-party dependency licenses, required third-party notices, or security
approval.
Supporting plugin checks¶
All five supporting plugins now build and pack with the required metadata:
portal-core,portal-rhdh,portal-operations-backend, andportal-health-backendeach declarebackstage.pluginPackageswith their own package name. No other package in this repository declares the same respective plugin ID.aap-app-authdeclaresbackstage.pluginPackage: '@backstage/plugin-app', matching the nativeappplugin it extends. The module's misleading pluralpluginPackagesentry is removed.
All ten tarballs passed checks that declared main, module, types, export,
and configuration-schema targets exist. Runtime and peer dependencies contain
no workspace:, file:, link:, or portal: references. Each baseline tarball
included its license and retained the private guard. Archive file lists contain no
.env, .git, node_modules, or app-config*.yaml files. These filename checks
are not a secret-content scan or a substitute for security review.
All ten candidate builds and the root TypeScript declaration emission passed on
Node 22.22.3. The separate packed-consumer checks below also passed. Dynamic
exports, dependency vulnerability scanning and dependency-license review are
separate release checks.
Separate packed-consumer checks¶
A fresh consumer project outside this monorepo installed all ten candidate
archives on 2026-11-06, using Yarn 4.12.0 and the Node 22.22.3 runtime. It had
its own manifest and lockfile, with no workspace links or inherited root lockfile.
Internal @ansible dependencies were resolved to the candidate tarballs through
explicit consumer resolutions because these candidates are not yet published.
The declared external peers were installed explicitly. The consumer pinned the
reference host's @backstage/core-app-api@1.20.4 context and used RJSF 5.24.13
peers to satisfy the host package's declared ranges.
The following checks passed:
- TypeScript compilation of a native frontend contributor using the public profile-item blueprint and generic SDK UI components, plus a backend contributor using the backend SDK and health service reference.
- Compilation of host/auth root and subpath imports, including native entry points and the Portal navigation entry point.
- Browser bundles of the frontend contributor and host/auth imports, resolving their dependency graphs from installed archives.
- Runtime import of the backend host features and an SDK health push/read check.
- All ten internal package paths resolve inside the isolated consumer's
node_modules. Browser bundle inputs contain no monorepo source paths.
These checks validate installation, selected public API use, bundling and a
bounded backend runtime path. They do not validate live host discovery, API
identity across independently bundled dynamic plugins, permissions, operation
execution, AAP login/logout, or RHDH installation. Consumer TypeScript compilation
used skipLibCheck: true, so it is not a full third-party declaration audit.
Lifecycle scripts were disabled during the consumer install. Packages requiring native build scripts were not exercised. The install completed with Material UI 4 peer-range warnings against React 18 and its types. Record and review these warnings when choosing the release compatibility matrix; a successful install does not resolve that compatibility question.
RHDH CLI export tooling¶
The root RHDH CLI is pinned to 2.1.2, with its required ts-morph peer declared
explicitly. CLI 2.1 uses native module federation and NFS feature metadata for
frontend exports. Native scripts no longer pass the removed Scalprum generation
flags, and native frontend package file lists no longer advertise dist-scalprum.
Use export-dynamic --clean when switching export toolchains to remove stale
outputs.
The content-management frontend still requires its owners' NFS migration. Its
three CLI-owning workspaces retain an explicit 1.10.8 pin and use their local
CLI binary instead of the root binary. This preserves the legacy content export
path without adding feature plugins to the SDK publication scope. Remove this
exception after the content owners migrate and validate their frontend.
Local checks with CLI 2.1.2 passed for six native frontend exports, the
operations/health/AAP-auth backend exports, and a Node 24 AAP-auth export.
Generated frontend feature declarations matched the federation exposes. The
content frontend also exported successfully with its local CLI 1.10.8, retaining
the legacy Scalprum manifest. The root lockfile installs immutably. Existing
heavy-dependency warnings for core-app-api remain in AAP auth and Portal
scaffolder; these exports did not enable --strict-deps.
The earlier live RHDH login/logout checks used artifacts exported before this CLI upgrade. Repeat live host validation with the selected release artifacts.
Reproducing the candidate packing checks¶
For the automated build, archive audit, and isolated-consumer check, run:
The command uses the explicit candidate list in
scripts/sdk-package-validation/packages.json and writes evidence outside the
checkout. The SDK package validation workflow runs it on Node 22 and 24 for
relevant pull requests. It does not publish packages or establish production
readiness. See scripts/sdk-package-validation/README.md for checks, output, and
limitations. The complete automated command passed locally on 2026-11-10 with
Node 22.22.3 and 24.16.0 for all ten candidates. These runs include the auth
composition and Settings federation fixes on this branch. Existing Material UI
peer warnings remain documented limitations. The commands below are useful for
inspecting individual archives.
Prerequisites¶
- Install repository dependencies with the configured Yarn version.
- Use Node 22 or 24, as declared by the repository.
- Run the commands from the repository root.
Procedure¶
- Emit declarations using the current checkout:
- Build and pack all ten candidates into a temporary directory:
set -e
package_artifacts="$(mktemp -d)"
for package in portal-extension-common portal-extension-api portal-plugin-sdk portal-plugin-node portal-extension-host portal-core portal-rhdh portal-operations-backend portal-health-backend aap-app-auth; do
yarn workspace "@ansible/$package" build
yarn workspace "@ansible/$package" pack --out "$package_artifacts/$package.tgz"
done
Verification¶
Confirm that each command exits successfully. Inspect an archive's published metadata and file list, including any subpath declaration files:
tar -xOf "$package_artifacts/portal-extension-api.tgz" package/package.json
tar -tzf "$package_artifacts/portal-extension-api.tgz"
Resolve every main, module, types, and export target against the archive
contents. Check internal runtime and peer dependency ranges, license files,
notices, and unintended files. Repeat for each archive. A successful local pack
does not authorize publication or validate a real host install.
Release decisions and acceptance gates¶
- Approve the package allowlist. Start with the five libraries, distinguish host-only consumers, and confirm which supporting plugins need npm delivery for the first external integration. Keep feature plugins excluded. Freeze the intended public API before cutting artifacts. The branch includes the merged experience-ID removal, but the historical ten-package consumer results predate it. Repeat packing and consumer checks on the selected merged release revision rather than releasing those baseline artifacts unchanged.
- Review versions and tags. The candidates use
0.1.0-alpha.0with the intendednexttag. Yarn rewrites internal workspace references to matching preview ranges during packing. Dynamic OCI artifacts remain outside this release. If an approved bootstrap publishes this version, prepare a new coordinated version before running the automated publisher. - Finalize publishable metadata and contents. The initial metadata and repository-license gaps are fixed and tarballs pass local checks. Only the ten candidates have their private guards removed. Review required plugin metadata, licenses and notices. Validate root and subpath imports and configuration schemas from the packed files.
- Validate host authentication composition. API-only and opt-in UI entry points are implemented, with the combined entry retained for compatibility. Verify the documented backend prerequisites and test standard RHDH coexistence and Portal login/logout using the release artifacts. A successful package test or pack does not establish live OAuth behavior.
- Complete separate-consumer runtime validation. Packed installation, selected frontend/backend compilation, browser bundling and a backend SDK runtime smoke check have passed outside the monorepo. Next verify live host discovery, shared API identity, permissions, operations and required AAP authentication using the selected release artifacts. The bounded checks above do not prove those host behaviors.
- Agree compatibility. Backstage
1.54.9is the source baseline. Previous local RHDH testing againstnext-2.1is not a supported-version declaration. Record an immutable RHDH image digest and test the actual release candidates. Validate peers rather than widening their ranges based only on a successful monorepo build. - Agree secure publication. Confirm
@ansiblenamespace ownership, authorized maintainers, CI publisher identity, provenance, dependency and license checks, package-content checks, and release approval with the relevant maintainers. These controls are not established by this inventory. - Onboard dynamic plugins separately. The proposed RHDH path uses export overlays for OCI packaging and validation. SDK libraries themselves do not become installable dynamic plugins. Onboarding access and packaging ownership remain to be confirmed before implementing a release workflow.
Related guidance¶
- Plugin author guide
- Native frontend composition
- Out-of-tree plugin obligations
- Yarn workspace dependency publication
- Yarn pack
- Backstage package metadata
- Backstage build and packaging system
The author guide and out-of-tree ADR predate this publication work. Update their in-tree preview restrictions and provisional install instructions together with an accepted external-consumption contract, rather than treating this inventory as an already available npm installation path.
Validation artifact provenance¶
CI generates an SPDX SBOM for each candidate archive with a pinned Syft version.
PR validation remains read-only and uploads diagnostics and SBOMs without
candidate tarballs. Trusted pushes or manual runs on main create Sigstore-backed
build provenance covering archive, SBOM, index, and report digests before uploading
the candidates. Attestation failure blocks candidate upload. Checkout credential
persistence is disabled. These controls identify validation artifact origin and
integrity; they do not approve npm publication or establish production readiness.
SBOMs cover the delivered package contents, with cataloged npm identity and
version checked against the validation report. External consumer dependency
resolution and vulnerability/license review remain separate requirements. See
scripts/sdk-package-validation/README.md for local generation and verification.
The first trusted signing run can be exercised after these workflows reach main.