relmio 0.3.0 → 0.4.0

package/docs/npm-publish.md

@@ -1,85 +1,84 @@
 # Publish and synchronize the npm package
 
-This guide is for the package maintainer. Run every command on the local
-computer in this repository, not on the VPS.
+This guide is for the package maintainer. Run commands on a clean local
+release worktree, never on the VPS. The repository and its reviewed release
+commit are the source of truth.
 
-The repository is the release source of truth. The initial package is prepared
-in Git, validated by CI, published to npm from that exact commit, and then
-tagged with the same version. Later releases are tagged first and published
-from that exact tag by the trusted workflow. npm does not automatically edit
-`package.json`, `CHANGELOG.md`, or the Git repository after a publish.
-
-The first `relmio` publication is a one-time bootstrap with a narrowly scoped
-local access token because npm requires the package to exist before a trusted
-publisher can be attached. After that bootstrap, releases use the
-repository's `.github/workflows/publish.yml` OIDC workflow and no long-lived
-npm token.
+Relmio is already configured as an npm trusted-publishing package. Every npm
+release must come from the repository's `.github/workflows/publish.yml`
+workflow using GitHub OIDC. Do not create, store, request, or use a local npm
+access token for a Relmio release.
 
 ## Version contract
 
-Every release must use one semantic version in all of these places:
+Every release uses one semantic version in all of these places:
 
 - `package.json`;
 - the top-level and root-package entries in `package-lock.json`;
 - the newest numbered release in `CHANGELOG.md`;
 - the Git tag `v<version>`;
+- the GitHub release;
 - the version published to npm.
 
-Check the local files at any time:
+Check local metadata with:
 
 ```bash
 npm run release:check
 ```
 
-On a tag build, CI also checks that the tag matches the files. The npm badge
-in the README is only an informational, potentially cached view of the
-registry's current `latest` version. The post-publish commands below perform
-the authoritative equality check.
+The README badge can be cached. Post-release registry queries are the
+authoritative publication check.
 
-## One-time npm account setup
+## Trusted publisher contract
 
-1. Sign in at <https://www.npmjs.com/>.
-2. Configure an npm-supported second factor for package publishing. Depending
-   on the account, npm may approve with a passkey/security key or request an
-   authenticator one-time code.
-3. Create one granular access token that can create and publish only the new
-   package. Keep it in the ignored local `NPM_CREATE_ACCESS_TOKEN` environment
-   variable and revoke it after trusted publishing is configured.
+The npm package's **Trusted Publisher** configuration must remain:
 
-Never paste an npm password, passkey recovery material, 2FA code, or access
-token into chat, an issue, a shell-history example, or the repository.
+| Field | Value |
+|---|---|
+| Publisher | GitHub Actions |
+| Organization or user | `Demonbane18` |
+| Repository | `relmio` |
+| Workflow filename | `publish.yml` |
+| Environment name | `npm` |
+| Allowed action | Allow npm publish |
+
+The workflow runs on a GitHub-hosted runner with `id-token: write` and the
+protected `npm` environment. npm exchanges that workload identity for a
+short-lived publishing credential and generates provenance for the public
+package. The workflow contains no long-lived npm secret.
+
+If this trusted-publisher configuration is missing or differs, stop. Repair it
+through npm's package settings and review the repository environment policy
+before attempting a release. Never substitute `npm login`, an `.npmrc` token,
+an environment token, or a personal automation token.
 
 ## Prepare a release
 
-Start from a release branch. Do not retag or reuse an already published
-version.
+Start from an isolated release branch and a clean worktree. Do not retag or
+reuse an already published version.
 
 ### 1. Check the current state
 
 ```bash
 git status --short --branch
-npm view relmio version \
-  --registry=https://registry.npmjs.org
+git tag --sort=-version:refname | head
+npm view relmio version --registry=https://registry.npmjs.org
 ```
 
-The worktree should contain only the changes intended for the release.
-Before the first Relmio publish, npm returns `E404` because the new package
-name has no published version yet. Confirm the exact package name is still
-available, then continue only from the reviewed rebrand commit.
+Inspect the complete diff since the previous published tag. The worktree must
+contain only reviewed release changes.
 
-### 2. Bump the files without creating a tag
+### 2. Update version metadata without creating a tag
 
-For a backward-compatible bug or documentation release:
+For a compatible patch:
 
 ```bash
 npm version patch --no-git-tag-version
 ```
 
-Use `minor` for a backward-compatible feature and `major` for a breaking
-change. The command updates both `package.json` and `package-lock.json`.
-
-Add a matching release heading and user-visible changes to `CHANGELOG.md`.
-Then run:
+For Relmio's pre-1.0 series, use a minor bump for a meaningful new capability
+or workflow. Update the dated `CHANGELOG.md` entry, keep `## Unreleased` above
+it, and run:
 
 ```bash
 npm run release:check
@@ -92,194 +91,115 @@ npm ci --ignore-scripts
 npm run check
 npm audit --audit-level=high
 npm run package:build -- .release
+npm pack --dry-run
 ```
 
-The package builder stages the concise npm README as the tarball's root
-`README.md`; it never changes the full GitHub README or its Mermaid diagrams.
-Review the emitted tarball file list. It must not contain:
-
-- `.env` or local-context files;
-- OAuth files or tokens;
-- SSH keys, passwords, or real VPS details;
-- browser session URLs;
-- test recordings or unredacted screenshots;
-- unrelated local build artifacts.
-
-Documentation images must be sanitized previews. Remember that `docs/**` is
-part of the npm package.
+Review the emitted tarball file list. It must not contain credentials, local
+environment files, SSH material, real infrastructure details, browser session
+URLs, unredacted recordings, or unrelated build artifacts. The package builder
+must stage `npm/README.md` as the tarball's root `README.md` without modifying
+the full GitHub guide.
 
-Before changing a private repository to public, audit the complete Git
-history as well as the current worktree. Deleting a VPS address, email,
-credential, or token from the latest commit does not remove it from earlier
-commits. If history contains sensitive data, keep the repository private and
-perform a reviewed, coordinated history rewrite before the first public
-release.
+When `web/**` changed, also run the web lint, typecheck, tests, production
+Vercel build, and the approved browser QA. When installer or package-manager
+surfaces changed, run their platform-focused tests and artifact checks.
 
-### 4. Commit and run CI
+### 4. Open the release pull request
 
-Stage every intended change, then review the exact staged release:
+Commit only the intended release files and push the release branch. The pull
+request must record:
 
-```bash
-RELEASE_VERSION="$(node -p "require('./package.json').version")"
-git add --all
-git status --short
-git diff --cached --check
-git diff --cached --stat
-git commit -m "release: v${RELEASE_VERSION}"
-git push
-```
+- the previous release tag and intended version;
+- the provider/security boundary for changed behavior;
+- root, web, installer, package, audit, and browser results as applicable;
+- npm, Vercel, Homebrew, WinGet, and installer applicability;
+- every known skip or unresolved risk.
 
-Merge the release commit into the repository's default branch according to
-the project workflow and wait for the default-branch CI run to pass. The
-remaining commands assume that branch is named `main`; substitute the actual
-default branch if it differs.
+Wait for required review, CI, package-manager validation, and Vercel preview
+checks. Do not bypass branch protection. Merge only the reviewed head commit.
 
-## Publish the exact commit
+## Tag and publish the exact merged commit
 
-Check out the CI-approved default branch, update it without a merge commit,
-and record the exact clean commit:
+After the default-branch CI and production deployment are green, resolve the
+exact merged commit:
 
 ```bash
-git switch main
-git pull --ff-only
-test -z "$(git status --porcelain)"
-RELEASE_COMMIT="$(git rev-parse HEAD)"
-npm run release:check
+git fetch origin
+RELEASE_COMMIT="$(git rev-parse origin/main)"
+git show -s --format='%H%n%s' "$RELEASE_COMMIT"
 ```
 
-Review the package from that commit. Immediately before publishing, fail if
-either the commit or worktree changed:
+Confirm that commit contains the reviewed package version and changelog. Create
+an annotated tag on that exact commit, push it, and verify the remote tag
+target before creating the GitHub release:
 
 ```bash
-npm run package:build -- .release
-test "$RELEASE_COMMIT" = "$(git rev-parse HEAD)"
-test -z "$(git status --porcelain)"
+RELEASE_VERSION="$(node -p "require('./package.json').version")"
+git tag -a "v${RELEASE_VERSION}" "$RELEASE_COMMIT" -m "v${RELEASE_VERSION}"
+git push origin "v${RELEASE_VERSION}"
+git ls-remote origin "refs/tags/v${RELEASE_VERSION}^{}"
 ```
 
-For the first `relmio` publication only, place the already-created token in
-the environment without echoing it, write an owner-only temporary npm config,
-and publish the reviewed tarball:
+Create the GitHub release from that tag with curated notes copied from the
+matching changelog entry. Publishing the GitHub release triggers
+`.github/workflows/publish.yml`; that workflow:
 
-```bash
-umask 077
-NPM_CONFIG_USERCONFIG="$(mktemp)"
-trap 'rm -f "$NPM_CONFIG_USERCONFIG"' EXIT
-printf '%s\n' '//registry.npmjs.org/:_authToken=${NPM_CREATE_ACCESS_TOKEN}' \
-  > "$NPM_CONFIG_USERCONFIG"
-export NPM_CONFIG_USERCONFIG NPM_CREATE_ACCESS_TOKEN
-npm whoami --registry=https://registry.npmjs.org
-LOCAL_VERSION="$(node -p "require('./package.json').version")"
-npm publish ".release/relmio-${LOCAL_VERSION}.tgz" \
-  --ignore-scripts \
-  --access public \
-  --registry=https://registry.npmjs.org
-```
+1. checks out the immutable release tag;
+2. runs the full release gate and audit;
+3. builds the reviewed tarball;
+4. skips safely if that immutable version already exists;
+5. otherwise publishes through npm trusted publishing;
+6. builds and attaches verified Windows release artifacts;
+7. generates a Homebrew formula candidate from the published npm tarball.
 
-Do not place the real token value in `.npmrc`, the workflow, a command-line
-argument, or Git. npm may still require its configured publishing second
-factor.
+Never run `npm publish` locally. Never recreate or move a published tag.
 
-Verify the immutable registry result:
+## Verify delivered surfaces
+
+After the workflow succeeds:
 
 ```bash
 LOCAL_VERSION="$(node -p "require('./package.json').version")"
 PUBLISHED_VERSION="$(npm view relmio version \
   --registry=https://registry.npmjs.org)"
 test "$LOCAL_VERSION" = "$PUBLISHED_VERSION"
-npm view "relmio@${LOCAL_VERSION}" dist.integrity \
+npm view "relmio@${LOCAL_VERSION}" \
+  version dist.integrity dist.tarball \
   --registry=https://registry.npmjs.org
 ```
 
-The equality check must succeed before tagging.
-
-## Switch future releases to trusted publishing
-
-Do this only after the first `relmio` version exists on npm and the
-`publish.yml` workflow is present on the GitHub default branch.
-
-On the npm package's **Trusted Publisher** form, use:
-
-| Field | Value |
-|---|---|
-| Publisher | GitHub Actions |
-| Organization or user | `Demonbane18` |
-| Repository | `relmio` |
-| Workflow filename | `publish.yml` |
-| Environment name | `npm` |
-| Allowed action | Allow npm publish |
-
-The environment must match `environment: npm` in the workflow. Add approval
-rules to the GitHub `npm` environment if a maintainer should explicitly
-approve each registry write.
-
-The workflow uses a GitHub-hosted runner, `id-token: write`, Node.js `22.14.0`,
-and npm `11.13.0`, which is separate from the application's reviewed npm
-`10.9.8` development runtime. npm exchanges the GitHub OIDC identity for a
-short-lived publishing credential and automatically generates provenance for
-public packages.
-
-After one trusted publish is verified:
-
-1. change package publishing access to require 2FA and disallow tokens;
-2. revoke `NPM_CREATE_ACCESS_TOKEN` and any older automation tokens;
-3. keep normal development on npm `10.9.8`;
-4. create future GitHub releases from reviewed `v<version>` tags to trigger
-   the trusted workflow.
-
-The workflow safely skips a version already present on npm. This lets the
-GitHub release for the token-bootstrapped `v0.2.0` tag be created without a
-duplicate publish attempt.
-
-## Tag the published release
-
-For the initial token-bootstrap release, create the tag on the exact published
-commit:
-
-```bash
-RELEASE_VERSION="$(node -p "require('./package.json').version")"
-: "${RELEASE_COMMIT:?Run the publish steps above in this terminal first}"
-test "$RELEASE_COMMIT" = "$(git rev-parse HEAD)"
-git tag -a "v${RELEASE_VERSION}" "$RELEASE_COMMIT" -m "v${RELEASE_VERSION}"
-git push origin "v${RELEASE_VERSION}"
-```
-
-The tag CI run validates that `v<version>` matches the package, lockfile, and
-changelog. For later OIDC releases, push the reviewed tag first and create the
-GitHub release from it; publishing the GitHub release triggers the trusted
-workflow. Copy the matching changelog entry into the release notes.
-
-## Verify as a package user
-
-In a separate terminal, check the version and launch the exact release:
-
-```bash
-npm view relmio version
-npx --yes --ignore-scripts relmio@PUBLISHED_VERSION
-```
+Also verify:
 
-Replace `PUBLISHED_VERSION` with the number just published. Confirm that the
-local wizard opens, then press Control+C before entering real credentials if
-this is only a smoke test.
+- the GitHub release tag targets the reviewed merged commit;
+- npm renders the registry-safe README and the package has provenance;
+- the Vercel production deployment corresponds to the merged commit;
+- hosted `install.sh`, `install.ps1`, and `install.cmd` still byte-match their
+  tested repository sources and invoke `relmio@latest`;
+- Windows assets are attached to the GitHub release;
+- Homebrew points to the exact npm tarball version and SHA-256;
+- WinGet remains described as pending until its upstream catalog is actually
+  updated.
 
-The CLI currently has no `--help` argument parser. Do not use a `--help`
-invocation as a release check; it starts the wizard like any other argument.
+Run the repository's distribution audit for the exact release version and do
+not call the release synchronized while a required surface is red.
 
 ## If something goes wrong
 
-- `ENEEDAUTH`: run `npm login`, complete npm's browser approval, and retry
-  `npm whoami`.
-- `E403`: confirm the intended npm account owns the package and complete the
-  configured publishing second factor.
-- `EPUBLISHCONFLICT`: the version is immutable and already exists. Bump to a
-  new patch version; never delete or overwrite it.
-- Registry version differs from `package.json`: stop before tagging. Determine
-  whether the publish succeeded and prepare a new release if necessary.
-- The Git commit was pushed but npm publish failed: fix npm authentication or
-  policy, rerun the gates on the same clean commit, and publish that version.
-- npm publish succeeded but the tag push failed: do not republish. Push the
-  tag for the exact already-published commit.
-- `npx` cannot see a just-published version: verify the exact registry version
-  and wait briefly for registry/CDN propagation.
-
-Do not publish from the VPS. Never put an npm access token in the GitHub
-Actions workflow; the trusted workflow authenticates only through OIDC.
+- Trusted-publisher or OIDC failure: stop and inspect the GitHub environment,
+  workflow identity, npm trusted-publisher settings, and workflow logs. Do not
+  fall back to a token.
+- `EPUBLISHCONFLICT`: the version is immutable and already exists. Verify
+  whether it is the intended artifact; otherwise prepare a new version.
+- Registry version differs from repository metadata: stop. Do not move the tag
+  or overwrite npm.
+- Tag push failed before the GitHub release: confirm whether the exact tag
+  exists remotely before retrying. Never force-update a release tag.
+- GitHub release exists but publish failed: leave the tag immutable, fix the
+  trusted workflow or policy, rerun the reviewed automation, and preserve the
+  failure evidence.
+- Vercel or package-manager delivery failed: keep the release status explicit
+  and repair only the affected reviewed surface.
+
+Do not publish from the VPS. Do not put an npm token in local config, CI, chat,
+issues, logs, or shell examples. Relmio publishing authenticates only through
+the repository's short-lived GitHub OIDC identity.

package/docs/security.md

@@ -1,8 +1,10 @@
 # Security and limitations
 
-This project handles two password-equivalent secrets: a ChatGPT OAuth
-credential and an SSH authentication method. Read this page before offering
-the wizard to another person.
+The VPS/n8n path handles a ChatGPT OAuth credential and an SSH authentication
+method. The local endpoint path can additionally handle an OpenAI Platform API
+key, a Codex/ChatGPT session, and generated local capabilities. Treat every one
+of these values as password-equivalent. Read this page before offering the
+wizard to another person.
 
 ## Trust model
 
@@ -16,6 +18,20 @@ The design assumes:
 
 If any of those assumptions is false, do not use this design.
 
+For a local Docker endpoint, the design additionally assumes:
+
+- the local computer, operating-system account, and Docker Engine are trusted;
+- the app receiving the Relmio capability displayed once by the wizard is
+  trusted and controlled
+  by the same person;
+- a browser origin allowlist is not being used as a substitute for secret
+  storage; and
+- a Codex client is trusted with App Server's broad agent and account surface.
+
+The raw Codex App Server is not a multi-user boundary. It is for a trusted
+native client owned by the same account holder, not a browser, shared service,
+public app, or untrusted plugin.
+
 ## Controls implemented by the wizard
 
 - The web server binds only to `127.0.0.1`.
@@ -42,6 +58,45 @@ If any of those assumptions is false, do not use this design.
 - There is no host `ports` mapping and no reverse-proxy route.
 - The installer verifies the absence of a published port after startup.
 
+### Local endpoint controls
+
+- Generated Compose files publish only literal
+  `127.0.0.1:<selected-port>:<container-port>` mappings.
+- Every OpenAI `/v1` operation that can reach OpenAI and every Codex WebSocket
+  upgrade requires a random Relmio capability displayed once by the wizard;
+  only its SHA-256 verifier is persisted. Exact-origin CORS `OPTIONS` is a
+  non-forwarding metadata exception. The bearer remains valid until an
+  endpoint update rotates it.
+- The Platform API key is accepted only for the OpenAI gateway. A transient,
+  network-disabled helper receives it over stdin and atomically seeds a private,
+  labeled Docker volume that the gateway mounts read-only. No host key file or
+  Compose environment value is created, and the key is never returned to the
+  browser after installation.
+- ChatGPT sign-in is accepted only through the official Codex App Server
+  account flow. Relmio never returns or converts the resulting tokens.
+- Browser requests to the OpenAI gateway require an exact configured `http`
+  or `https` origin. Wildcards and `null` are rejected; requests without an
+  `Origin` remain available to authenticated native clients and backends.
+- Codex receives private named credential and workspace volumes. No host
+  directory, Docker socket, SSH key, browser profile, or home directory is
+  mounted into either local service.
+- Local managed paths use mode `0700`, generated files use owner-only modes,
+  symlinks are rejected, and existing unmanaged directories are not
+  overwritten.
+- The selected Docker context must resolve to a local Unix socket. Every
+  mutating command is pinned to that socket, Docker selector environment
+  overrides are removed, and native Windows is rejected before mutation.
+- Each install uses a random Compose project identity. Containers, networks,
+  and volumes must carry matching Relmio ownership labels before update,
+  restart, recovery, or sign-in actions are allowed.
+- Both long-running endpoint containers run as a non-root user, drop Linux
+  capabilities, set `no-new-privileges`, use a read-only root filesystem, and
+  have bounded temporary storage and resource limits.
+- The one-shot OpenAI credential seed helper is the narrow exception: it has no
+  network, port, or logs; runs with a read-only root filesystem and strict
+  resource limits; and uses root plus only `CHOWN` long enough to atomically
+  make the stdin-seeded volume entry readable by the non-root gateway.
+
 ## What “private” means here
 
 Port `10531` is not reachable from the public internet or VPS host through a
@@ -67,6 +122,20 @@ expose it.
 - Revoke or refresh the session if the VPS may be compromised.
 - Prefer a dedicated personal VPS with current security updates.
 
+The local capabilities have separate consequences:
+
+- The OpenAI gateway capability can spend through the protected Platform API
+  key, subject to that Platform project's permissions and limits.
+- The Codex capability can invoke broad App Server methods inside the isolated
+  container and use its signed-in ChatGPT/Codex session.
+- An origin allowlist does not make a bearer embedded in browser JavaScript
+  private. Use browser access only for private same-owner local development.
+- Do not expose either endpoint on a LAN, public IP, domain, reverse proxy, or
+  hosted service. Loopback binding and the bearer capability are both required.
+- If a capability is disclosed, update the endpoint to rotate it. If an
+  upstream credential may be exposed, revoke or sign out through the provider
+  as well.
+
 ## Product and policy limitations
 
 - This is not an OpenAI Platform API key.
@@ -79,10 +148,29 @@ expose it.
 - Rate limits and account restrictions still apply.
 - OpenAI can change or discontinue service behavior and can suspend access for
   Terms or usage-policy violations.
+- The local OpenAI-compatible endpoint requires a Platform API key. Its usage
+  is billed or credited to the associated Platform project; a ChatGPT
+  subscription or Codex for Open Source benefit is not substituted for API
+  billing.
+- The local Codex option preserves the official App Server JSON-RPC protocol.
+  It does not provide `/v1/chat/completions`, `/v1/responses`, or any other
+  OpenAI API compatibility route.
+- OpenAI documents App Server WebSocket transport as experimental and
+  unsupported for production. It rejects browser-origin requests and is
+  limited here to trusted native same-owner clients.
+- Acceptance into Codex for Open Source is not treated by Relmio as permission
+  to repurpose credentials, share an account, bypass controls, or broaden the
+  scope of another agreement. Review the current
+  [program terms](https://learn.chatgpt.com/docs/codex-for-oss-terms).
 
 This repository does not claim that every possible use of the bridge is
 permitted. The account owner is responsible for reviewing the current
 [OpenAI Terms](https://openai.com/policies/terms-of-use/) and usage policies.
+The local endpoint design follows the documented
+[OpenAI API authentication](https://developers.openai.com/api/reference/overview#authentication),
+[Codex authentication](https://learn.chatgpt.com/docs/auth), and
+[Codex App Server](https://learn.chatgpt.com/docs/app-server) boundaries. This
+is engineering guidance, not legal advice or an OpenAI approval.
 
 ## Dependency policy
 
@@ -91,6 +179,7 @@ The current release pins:
 - Node.js 22+
 - `ssh2` `1.17.0`
 - `openai-oauth` `2.0.0`
+- `@openai/codex` `0.147.0` in the local Codex image
 
 The POSIX and native Windows PowerShell bootstraps reuse a compatible local
 Node.js runtime or download the matching current official Node.js 22 archive

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "relmio",
-  "version": "0.3.0",
-  "description": "Turn a supported ChatGPT/Codex OAuth sign-in into a private OpenAI-compatible endpoint, starting with self-hosted n8n.",
+  "version": "0.4.0",
+  "description": "Install private local OpenAI API and Codex endpoints with explicit provider credential boundaries, plus the existing isolated n8n sidecar.",
   "keywords": [
     "relmio",
     "gpt-5-6-sol",