Package Registry and Catalog

Appearance

Public packages ​

Status: target state, never executed. Publishing to npmjs.com is wired through .github/workflows/release.yml but has never been triggered. The npm publish safety audit (projects/matrix-3/packages/docs/content/security/npm-publish-safety.md) documents the gates that must pass first.

Why public ​

The long-term plan for @open-matrix/* is publication on npmjs.com so that:

  • Anyone with npm can install Matrix packages without configuring a custom registry.
  • Standard npm tooling (npm advisor, npmjs.com, third-party security scanners) works against Matrix packages.
  • Matrix joins the broader ecosystem of npm packages without a private registry detour.

Why not yet ​

npmjs.com is permanent. Every published version is forever; deletion beyond a 72-hour window requires manual npm support intervention. That permanence makes mistakes catastrophic.

The npm publish safety audit identifies four classes of issues that must be fixed before any version reaches npmjs.com:

CRITICAL ​

  1. Build artifact path leakage. 38 matrix-artifact.json files in dist/ contain absolute developer paths and usernames. Publishing these leaks developer identity permanently.
  2. Missing "files" field. 9 packages would publish their entire source tree (tests, fixtures, build scripts) without it. The "files" array is the only allowlist.
  3. Build tools in production dependencies. esbuild and typescript are listed in dependencies (not devDependencies) for two packages. Users would download 50+ MB of unneeded build tooling.

HIGH ​

  1. Hardcoded infrastructure URLs in bundled code. Internal NATS hostnames, Gitea registry URLs, and Docker service references are baked into bundles. Public exposure leaks operational topology.
  2. Mock secret string (apiKey: "matrix-local-mock-secret") baked into bundled code.

MEDIUM ​

  1. SQL interpolation in SqliteRecordStore.
  2. Source maps in dist/ would leak full source on publish.

The audit closes with a pre-publish checklist:

1. Run `npm pack --dry-run` on every package and review file list
2. Grep the tarball for: absolute paths, localhost, secret, password, token
3. Verify no .ts source files, .map files, or test fixtures are included
4. Verify no matrix-artifact.json files with paths are included
5. Verify esbuild/typescript are not in production dependencies
6. Run the build from a clean checkout (not a dev machine with local state)

Each item is a hard block on public publish.

Target flow ​

When the gates pass, public publish is the same npm publish command pointed at https://registry.npmjs.com/:

bash
NPM_CONFIG_REGISTRY=https://registry.npmjs.com/ \
NPM_CONFIG__AUTH_TOKEN=<npm-token> \
npm publish --access public

The CI workflow in .github/workflows/release.yml is structured to run this when manually dispatched, but no run has ever completed.

Coexistence with the private registry ​

Public publish does not retire the Gitea registry. Both can coexist:

  • Public packages on npmjs.com for general consumption.
  • Internal/in-development versions on Gitea, with the option to delete.
  • Pre-release candidates on Gitea (@beta, @next) before promotion to npmjs.com.

The hivecast bundled-package store can pull from either source depending on how the wrapper is built.

Migration risk ​

The first public publish is the highest-risk single operation in the project's history. Once @open-matrix/chat@1.0.0 is on npmjs.com, that exact tarball is permanent. A leaked credential, a build artifact with paths, or a misconfigured .npmignore is a forever-mistake.

The migration path is:

  1. Pass every CRITICAL and HIGH gate in the npm publish safety audit.
  2. Dry-run publish to a test scope on npmjs.com (@open-matrix-staging/* or similar) to validate the flow without committing to the canonical scope.
  3. Audit the resulting tarballs from npmjs.com's perspective (download, extract, grep).
  4. Schedule the real publish during a low-traffic window, with a designated incident commander.
  5. Verify the tarballs post-publish.
  6. Announce.

That path is target state. It will be executed once; it must be right.

See also ​

Source: Workflow at .github/workflows/release.yml. Gates documented in projects/matrix-3/packages/docs/content/security/npm-publish-safety.md.