@knitli/openapi-mcp 0.0.0

package/LICENSE-APACHE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/LICENSE-MIT

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Knitli Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,362 @@
+# @knitli/openapi-mcp
+
+Compile OpenAPI documents into immutable, signed SQLite catalogs. The local MCP
+server exposes `search`, `read`, and `action`; it verifies the catalog, request,
+destination, credentials, and any required action authorization before dispatch.
+
+The executable artifact format is **5**, runtime contract **1**, and prepared-call
+format **2**. This package is compiled TypeScript, separate from the Toolshed
+prompt plugins.
+
+## Install and check the runtime
+
+Local serving requires Node `>=24.16.0 <25`. Packed consumers exercise Node 24
+and Bun 1.4 compiler/SQLite imports. Bun HTTP socket-adapter support has not been
+established; use Node for `serve`. `/runtime` and `/conformance` pass an isolated
+WebWorker-only declaration check and browser bundle. This is not evidence of an
+actual Cloudflare D1 deployment or D1 conformance.
+
+The source version is `0.0.0`. Registry publication, trusted publishing, and
+registry provenance verification remain release gates, not claims made by this
+README. For a locally built and tested tarball, install its absolute path from a
+clean consumer directory:
+
+```sh
+npm install --ignore-scripts /absolute/path/to/openapi-mcp.tgz
+node --version
+```
+
+After a real stable version is observed in npm, pin that exact verified version
+with `npm install --save-exact @knitli/openapi-mcp@<verified-version>`. A bootstrap
+`0.0.0` publication, if needed, uses the `bootstrap` dist-tag and is not a stable
+release. The CLI examples below use the consumer's `node_modules/.bin` binary.
+
+## Generate a signing key and compile a release
+
+Use a private operator directory. The generation-state parent must be owned by
+the serving user and mode `0700`; retain that state across upgrades and restarts.
+
+```sh
+mkdir -m 700 operator operator/keys operator/releases operator/state
+./node_modules/.bin/openapi-mcp keygen --out ./operator/keys
+./node_modules/.bin/openapi-mcp compile-release \
+  --spec ./openapi.yaml --source-label widgets-spec --source-revision revision-1 \
+  --catalog widgets --release widgets-1 --generation 1 \
+  --issuer example-operator --key-id signing-1 --policy-id local-policy-1 \
+  --allowed-origin https://api.example.com \
+  --out ./operator/releases --sign-key ./operator/keys/openapi-mcp.key
+```
+
+Replace the spec, provenance, identifiers, and origin with your reviewed inputs.
+`--source-uri <https-uri>` is an alternative to `--source-label`. Compilation
+does not grant permission to call the API. Local references can be bounded with
+`--reference-root` and `--reference-map`; do not treat remote spec fetching as a
+runtime feature. `--permissions` accepts the permissions dataset used by the
+legacy compiler, but permissions annotations are advisory, not authorization.
+
+Keep each v5 SQLite payload beside its matching `.manifest.json` and
+`.manifest.sig` files with the same filename stem. Local executable ingress
+checks bounded, matching sidecars and admits only a complete manifest-last
+bundle. Startup proves every configured release's full record inventory before
+starting its conditional generation admissions. A valid signature alone does
+not admit a release with missing, malformed, or digest-mismatched records.
+
+The command publishes `widgets-1.sqlite`, `widgets-1.manifest.json`, and
+`widgets-1.manifest.sig` under the output directory without replacing an existing
+release. `keygen` refuses to overwrite existing files and writes the private key
+with mode `0600`. Keep the private key out of runtime deployments. Obtain the
+base64url SPKI public key for the config with:
+
+```sh
+node --input-type=module -e 'import {readFileSync} from "node:fs"; import {createPublicKey} from "node:crypto"; console.log(createPublicKey(readFileSync("operator/keys/openapi-mcp.pub")).export({type:"spki",format:"der"}).toString("base64url"))'
+```
+
+## Configure and start the local MCP server
+
+Save this as `operator/config.json`, substituting absolute paths, the public key,
+and the origin present in the signed catalog. Config objects are strict: unknown
+fields, duplicate identifiers, unresolved profile references, and invalid limits
+are rejected. Origins must be HTTPS origins without credentials, paths, or query
+strings. Do not put bearer tokens or API keys in this file; use environment
+variable names. Supply those variables through your process supervisor or secret
+manager before starting the process.
+
+```json
+{
+  "version": 1,
+  "generationStatePath": "/absolute/path/operator/state/generations.json",
+  "catalogs": [{
+    "catalogId": "widgets", "releaseId": "widgets-1",
+    "path": "/absolute/path/operator/releases/widgets-1.sqlite",
+    "profileId": "widgets-user"
+  }],
+  "trust": {
+    "releaseKeys": [{"issuer": "example-operator", "keyId": "signing-1", "publicKey": "REPLACE_WITH_BASE64URL_SPKI"}],
+    "rollbackKeys": []
+  },
+  "allowedOrigins": ["https://api.example.com"],
+  "profiles": [{
+    "profileId": "widgets-user", "revision": 1,
+    "allowedOrigins": ["https://api.example.com"],
+    "auth": {"type": "bearer-env", "env": "WIDGETS_TOKEN"}
+  }]
+}
+```
+
+```sh
+./node_modules/.bin/openapi-mcp serve --config /absolute/path/operator/config.json
+```
+
+This speaks MCP on stdio. Startup errors go to stderr; keep stdout reserved for
+the protocol. A client configuration using the installed Node CLI can be:
+
+```json
+{
+  "mcpServers": {
+    "widgets": {
+      "command": "/absolute/path/to/node",
+      "args": ["/absolute/path/to/node_modules/@knitli/openapi-mcp/dist/cli.js", "serve", "--config", "/absolute/path/operator/config.json"]
+    }
+  }
+}
+```
+
+An API-key profile uses `{"type":"api-key-env","env":"WIDGETS_API_KEY",
+"placement":"header","name":"X-API-Key"}` (query placement is also supported).
+OAuth uses `{"type":"oauth2-pkce","authorizationEndpoint":"https://auth.example.com/authorize",
+"tokenEndpoint":"https://auth.example.com/token","clientId":"public-client-id",
+"scopes":["widgets.read"]}` with optional `resource`. The resource is a fixed
+absolute URI without a fragment, including identifiers such as
+`urn:example:widgets`; it is audience metadata, not a credential destination or
+token-claim validation. Authorization and token endpoints remain HTTPS URLs.
+These endpoints and client
+registration must be configured by the operator. The server uses authorization
+code PKCE with S256 and a temporary `127.0.0.1` callback listener on an ephemeral
+port at `/oauth/callback`; the identity provider must support that redirect.
+The client needs URL elicitation for OAuth and form elicitation for confirmation.
+Open the offered authorization URL, finish login, then follow the client's resume
+flow. Unsupported elicitation fails closed.
+
+## Use the three tools
+
+These are tool names and input objects, not shell commands. Use the opaque
+`operation` returned by search unchanged; it binds the release and manifest.
+
+```json
+{"name":"search","arguments":{"query":"list widgets","limit":5}}
+```
+
+```json
+{"name":"read","arguments":{"operation":"<operation returned by search>","arguments":{"query":{"limit":10}}}}
+```
+
+```json
+{"name":"action","arguments":{"operation":"<action operation returned by search>","arguments":{"path":{"id":"widget-1"},"body":{"label":"Reviewed label"}}}}
+```
+
+Choose arguments from the returned input outline and your API's schema. An API
+namespace can be supplied as `search.api` when advertised by the mounted catalog.
+Read pagination uses the returned opaque `pageToken`; do not construct one.
+Upstream response content is untrusted data and cannot authorize further calls.
+
+Each search shares one candidate, record-proof, store-call, work, and response
+budget across catalogs. It can authenticate and completely prove at most eight
+candidate releases; broad matches or exhausted budgets produce safe omission
+warnings. Narrowing the query or selecting an API can reach later configured
+catalogs, including catalogs sharing an API namespace. Results are a bounded
+ranked sample, not an exhaustive catalog listing. Deprecation demotion and the
+requested result limit apply across the combined candidates.
+
+Successful search results, including the MCP content wrapper, trust text, and
+warnings, obey the configured `limits.maxResponseBytes`. A smaller-than-minimum
+result budget returns a bounded `RESPONSE_LIMIT_EXCEEDED` control error; the
+server does not raise the supplied limit to manufacture a successful result.
+When embedding `createOpenApiMcpServer`, provide its required `searchRuntime`
+port backed by one semantic search context, alongside `routes`, `authorizer`,
+and the same reduction-only `limits`. A single-catalog embedding can pass its
+existing runtime as `searchRuntime`; the CLI assembles shared search itself.
+
+If an action reports `UPSTREAM_OUTCOME_UNKNOWN`, its error includes the exact
+`details.preparedCallDigest` and `retryable: false`. Use that digest to reconcile
+the uncertain outcome; the server has consumed the authorization and does not
+automatically retry the action.
+
+Actions require server-controlled authorization bound to the prepared request,
+credential profile, release, and argument digest. Review the elicited destination,
+operation, effect, and arguments, then explicitly confirm. Rejection, cancellation,
+expiry, a changed request, or a changed credential binding prevents dispatch.
+Destructive operations require the stronger destructive acknowledgment. An operator
+may supply narrowly bound `exactPolicies` for eligible create/update operations;
+they are not broad scopes or a general confirmation bypass. Do not construct policy
+digests from model-supplied values. Policies expire and must match the verified
+manifest, operation, credentials, cardinality, and constrained arguments exactly.
+
+## Rotate credentials, keys, and catalogs
+
+Access and refresh tokens are held in process memory. OAuth refresh is supported;
+closing or restarting the process clears its token state and pending authorization
+flows. Environment credentials are still present if the process supervisor
+injects them again. Process restart is local cleanup, not upstream revocation:
+revoke the credential at the identity provider/API, remove or rotate its source,
+increment the profile revision, then restart the server. The library credential
+provider also exposes local revocation; it does not imply provider-side revocation.
+
+For a signing-key rotation, distribute the new public key through the trusted
+operator config, compile a new immutable release with a higher generation and the
+new key ID, validate it, update the catalog selection, and restart. Remove the old
+trust key when no retained approved release needs it. Keep rollback-authority keys
+separate from routine release keys. Never overwrite a catalog or reset/delete the
+generation state to make an old signature pass.
+
+To disable a catalog, stop the server, remove that catalog from `catalogs`, and
+restart with the remaining valid catalogs. Config requires at least one catalog;
+leave the server stopped if disabling the last one. Removing a file while the
+process is using it is not a reliable disable procedure.
+
+## Recover from a bad release
+
+Before release, record the prior **observed package version**, its tarball digest,
+the prior immutable catalog ID/release ID/generation/manifest digest, and the
+generation-state location. No prior published package version is asserted here.
+After a stable predecessor exists, the downgrade command is
+`npm install --save-exact @knitli/openapi-mcp@<recorded-known-good-version>` from the
+consumer directory. Restart with the retained catalog and state. Package downgrade
+alone does not authorize a signed-data rollback.
+
+The packed Node/Bun exercise compiles generations 1 and 2 with fresh fixture keys.
+A damaged generation-2 signature is rejected while generation 1 still searches
+and its operation record verifies. After valid generation 2 is admitted, generation
+1 is rejected until the separate rollback authority signs the existing v1 rollback
+authorization. Activation retains the highest generation at 2, changes the active
+generation to 1, consumes the authorization ID, and survives reopening the same
+`FileGenerationStore`. This is fixture evidence, not a production rollback.
+
+The stdio config accepts rollback trust keys but does **not** accept an attached
+rollback envelope. An operator can activate a pre-signed authorization through the
+public API while the server is stopped, then restart stdio against the retained
+catalog and the same state. Save the following as `activate-rollback.mjs` inside
+an installed consumer. The input authorization must come from your separate
+rollback authority; this procedure does not generate or weaken its signature.
+
+```js
+import { readFile } from "node:fs/promises";
+import { admitManifest } from "@knitli/openapi-mcp/runtime";
+import { FileGenerationStore, SqliteCatalogStore } from "@knitli/openapi-mcp/sqlite";
+import { parseOpenApiStdioConfig } from "@knitli/openapi-mcp/stdio";
+
+const [configPath, catalogId, authorizationPath] = process.argv.slice(2);
+const config = parseOpenApiStdioConfig(await readFile(configPath, "utf8"));
+const selected = config.catalogs.find((entry) => entry.catalogId === catalogId);
+if (!selected) throw new Error("Catalog is not configured");
+const store = new SqliteCatalogStore(selected.path);
+try {
+  const envelope = await store.getManifest(selected.catalogId, selected.releaseId);
+  if (!envelope) throw new Error("Manifest not found");
+  const rollback = JSON.parse(await readFile(authorizationPath, "utf8"));
+  const admitted = await admitManifest({ ...envelope, rollback }, config.trust,
+    new FileGenerationStore(config.generationStatePath));
+  console.log({ releaseId: admitted.manifest.releaseId, generation: admitted.manifest.generation });
+} finally {
+  store.close();
+}
+```
+
+```sh
+node activate-rollback.mjs /absolute/path/operator/config.json widgets /absolute/path/operator/approved-rollback.json
+```
+
+Select the prior catalog in the config before running this command. The existing
+authorization binds the catalog, issuer, current highest generation, target
+generation and manifest digest, expiry, unique ID, reason, and authorized key ID.
+It is Ed25519 over `knitli.openapi-mcp.rollback-authorization.v1` followed by a NUL
+byte and canonical JSON of the unsigned authorization. The runtime validates that
+contract and replay/state constraints. Use the packed consumer fixture as an
+executable example for a nonproduction signing exercise; never copy its generated
+keys into operator trust.
+
+## Migrate older artifacts
+
+Legacy `compile --spec ... --api ... --out ... [--sign-key ...]` still creates v3
+artifacts; `verify --artifact ... --sig ... --pub ...` verifies the exact SQLite
+file signature. V3 is inventory-only and does not gain executable trust from that
+signature. Recompile the reviewed source with `compile-release` for v5 execution.
+Do not relabel or mutate a v3 database as a v5 release.
+
+Strict historical v4 manifests support their tagless read compatibility contract.
+Do not add v5 tags to a historical v4 signed record or describe historical v4 as
+the current compiler output. V5 signs the manifest and record digests; the legacy
+exact-file `verify` command is not a v5 admission test. Use `admitManifest` and the
+runtime/store checks when validating release trust.
+
+## Troubleshoot and verify a build
+
+`MANIFEST_INVALID` calls for checking the selected release, exact envelope, and
+trusted issuer/key. `MANIFEST_ROLLBACK_REJECTED` requires the recovery procedure,
+not a generation-state reset. A generation-state permission error means its
+parent must be a real, owner-only directory. Generic startup errors are deliberate
+to avoid exposing config secrets; validate with `parseOpenApiStdioConfig` in a
+controlled operator process. Missing environment credentials or OAuth elicitation
+must be resolved before a call can proceed. An action refused for lack of
+confirmation needs an elicitation-capable client or an eligible reviewed exact
+policy. Do not retry a changed action with old approval state.
+
+From the repository, the package checks are:
+
+```sh
+mise exec -- bun run --cwd packages/openapi-mcp build
+mise exec -- bun test packages/openapi-mcp
+mise exec -- bun run --cwd packages/openapi-mcp test:node-transport
+mise exec -- bun run --cwd packages/openapi-mcp test:node-stdio
+mise exec -- bun scripts/generate.mts --check
+mise exec -- bun run validate
+(cd packages/openapi-mcp && mise exec -- bun pm pack --dry-run)
+```
+
+`tests/package-consumers.test.ts` builds/packs once, installs that tarball in fresh
+Node, Bun, and Worker directories outside the repository, executes the fixtures
+there, and prints the artifact path, SHA-256, and evidence directory. Set
+`OPENAPI_MCP_TARBALL` to an absolute tarball path to verify those exact bytes.
+The tarball includes all five public subpaths, declarations, the CLI, README, and
+unmodified MIT and Apache 2.0 licenses. Test specs, credentials, fixture databases,
+and consumer scripts are excluded. The exported conformance fixture module is
+part of the public `/conformance` API and does ship.
+
+Phase 3 must run the exported `runRuntimeConformanceSuite` against actual D1 in
+a Workers test environment and verify the deployed integration. A structural D1
+fake, portable declarations, or a browser bundle does not establish that result.
+The optional large Microsoft Graph corpus check remains skipped when its local
+fixture is absent; no large-corpus performance claim is made here.
+
+## Release gates
+
+Only the protected `npmrelease` GitHub environment may publish this package.
+Steady-state npm trusted publishing must bind exactly `knitli/toolshed`,
+`.github/workflows/release.yml` (publisher workflow name `release.yml`), and
+`npmrelease`, with `id-token: write`. It must not receive `NPM_TOKEN` or
+`NODE_AUTH_TOKEN`. The release adapter tests a Bun-packed artifact and invokes
+npm with that exact tarball from a clean directory under `RUNNER_TEMP`.
+`OPENAPI_MCP_OIDC_READY` is operator-controlled release enablement, not proof of
+publisher configuration or provenance. Set it to `true` only after recording the
+external setup and bootstrap-cleanup gates. Until then, build/test/validation
+still run and publication is explicitly reported as pending. A real build,
+publication, or audit failure continues to fail the job and its dependents.
+
+If the package does not yet exist, bootstrap is a separate exception requiring
+recorded named owner approval and protected-environment approval. It publishes
+only `0.0.0`, with `--access public --tag bootstrap --provenance`; it does not run
+semantic-release or create a Git tag/release. A short-lived granular token may be
+injected only into that protected job, never into local files, logs, commits, or
+artifacts. After bootstrap, configure the exact trusted publisher, remove token
+variables and the GitHub secret, revoke the token, and commit the OIDC-only
+workflow before allowing the first real `latest` release.
+
+For bootstrap and every stable release, retain a fresh public install's
+`npm audit signatures --json --include-attestations` output in the protected job
+artifact, along with its SHA-256. Require successful cryptographic verification
+and verify package identity/integrity, source commit, repository, workflow, and
+CI run against the release being approved. Registry metadata from `npm view`
+alone is insufficient. Record CI and semantic-release completion, registry
+version/dist-tag visibility, the matching stable Git tag/release, protected
+environment and publisher configuration, bootstrap cleanup/revocation when used,
+and the exact-version public consumer result. Any unobserved or failed gate stays
+pending. Local tests and workflow code are not evidence of publication.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};