diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..a20c12b --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,30 @@ +--- +name: Bug report +about: Report a reproducible Constraint Net problem +title: "[Bug]: " +labels: bug +assignees: "" +--- + +## What Happened? + + +## Expected Behavior + + +## Reproduction + +```bash + +``` + +## Safety Surface + +Does this affect consent, signing, replay safety, receipt verification, manifest trust, or CLI behavior? + + +## Environment + +- Node: +- pnpm: +- OS: diff --git a/.github/ISSUE_TEMPLATE/protocol_proposal.md b/.github/ISSUE_TEMPLATE/protocol_proposal.md new file mode 100644 index 0000000..7d509ea --- /dev/null +++ b/.github/ISSUE_TEMPLATE/protocol_proposal.md @@ -0,0 +1,22 @@ +--- +name: Protocol proposal +about: Propose a small, reviewable protocol or developer-experience change +title: "[Protocol]: " +labels: enhancement +assignees: "" +--- + +## Proposal + + +## Why It Matters + + +## Safety Impact + +How does this affect consent, reversibility, idempotency, manifest trust, or receipt verification? + + +## Smallest Shippable Shape + + diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..f336a06 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,15 @@ +## Summary + +- + +## Safety and Consent + +- [ ] Tier 2 side effects still require confirmation. +- [ ] Side-effectful execution remains idempotent and replay safe. +- [ ] Receipt verification still works outside process-local state. +- [ ] No secrets, production private keys, API tokens, or real customer data were added. + +## Verification + +- [ ] `pnpm test` +- [ ] `pnpm typecheck` diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 29507a6..418b55d 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -6,6 +6,9 @@ on: - main pull_request: +env: + FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true + jobs: test: name: Test and typecheck diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..f3ef51d --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,40 @@ +# Contributing + +Constraint Net is a protocol-first alpha. Contributions are most useful when they improve safety, reversibility, consent, verification, or developer clarity without turning the MVP into a broad platform rewrite. + +## Setup + +```bash +pnpm install +pnpm test +pnpm typecheck +``` + +Run the local gateway: + +```bash +pnpm dev +``` + +Open: + +```text +http://127.0.0.1:4173 +``` + +## Development Principles + +- Keep changes small enough to review in one pull request. +- Prefer manifest-declared policy over provider prose. +- Preserve human confirmation for Tier 2 side effects. +- Require idempotency for side-effectful execution. +- Keep receipts verifiable without process-local state. +- Do not introduce production secrets, private keys, API tokens, or real customer data. + +## Pull Request Checklist + +- `pnpm test` +- `pnpm typecheck` +- README or docs updated for public API, CLI, or protocol changes +- new safety behavior covered by tests +- no development key presented as a production key diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..f13472b --- /dev/null +++ b/LICENSE @@ -0,0 +1,183 @@ +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. + +"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. + +"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 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 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. Do not 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 2026 workingclassbuddha + +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. diff --git a/README.md b/README.md index 88e0b13..8c492d0 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,12 @@ Constraint Net is a coherence-first execution layer for AI agents. +## Status: Public Alpha + +Constraint Net is ready for public protocol review, local experiments, and small demo integrations. It is not production key custody, not a hosted network, and not a claim that real-world publishers have opted in. + +The current gateway uses in-memory state, a public development signing key, and mock OpenAPI-backed execution. Those choices keep the alpha easy to run and verify locally; production deployments must replace them with durable storage, publisher-owned keys, real OpenAPI operation resolution, monitoring, and operational controls. + This MVP demonstrates a safe, reversible customer-service workflow: ```text @@ -82,3 +88,12 @@ The executions return signed receipt IDs for intent, consent, and execution. - [Protocol overview](docs/protocol.md) - [Publisher onboarding](docs/publisher-onboarding.md) - [Agent builder guide](docs/agent-builder-guide.md) +- [Public launch checklist](docs/launch-checklist.md) + +## Launch Boundaries + +- Consent first: Tier 2 side effects require confirmation and reversible metadata. +- Replay safe: execution requires idempotency keys and blocks conflicting replays. +- Verifiable: receipts are signed and can be checked outside the running process. +- Alpha only: the committed development issuer key is intentionally public and only supports reproducible examples. +- Local only: manifests, confirmations, executions, and receipts are stored in memory in this gateway. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..c4f9025 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,35 @@ +# Security Policy + +Constraint Net is a public alpha. The current gateway is intended for local development, protocol review, and demo integrations. + +## Supported Scope + +Security review currently applies to the `main` branch and unreleased pull requests. + +Please treat these as alpha boundaries: + +- The committed Ed25519 private key is a public development issuer for reproducible examples and tests. It is not a secret. +- Manifests, confirmations, executions, and receipts are stored in memory. +- Provider execution is mocked and does not yet resolve real OpenAPI operations. +- The local server is not hardened for internet exposure. + +## Reporting + +Use GitHub private vulnerability reporting if it is enabled for this repository. If it is not available, open a minimal issue asking for a secure contact path and avoid posting exploit details publicly. + +Include: + +- affected endpoint, CLI command, or manifest field +- expected impact +- reproduction steps that avoid real user data +- whether the issue affects consent, signing, replay safety, receipt verification, or manifest trust + +## Security Priorities + +Constraint Net changes should preserve: + +- user consent before side effects +- manifest signature, expiry, revocation, and version checks +- idempotent execution and replay protection +- receipt verification outside the running process +- clear separation between development keys and publisher-owned production keys diff --git a/docs/launch-checklist.md b/docs/launch-checklist.md new file mode 100644 index 0000000..cc0c679 --- /dev/null +++ b/docs/launch-checklist.md @@ -0,0 +1,47 @@ +# Public Launch Checklist + +Use this before changing the repository visibility or announcing Constraint Net publicly. + +## Repository + +- `README.md` states Public Alpha status and local-only boundaries. +- `LICENSE`, `SECURITY.md`, and `CONTRIBUTING.md` are present. +- GitHub Actions passes on `main`. +- The package remains `private: true` until an npm release is intentional. +- Issue and pull request templates are available. + +## Safety + +- Tier 2 actions require human confirmation. +- Side-effectful actions require idempotency. +- Manifest validation checks schema version, signature, expiration, revocation, and publisher domain. +- Receipt verification works from receipt payloads alone. +- Demo private keys are clearly labeled as public development issuers. + +## Developer Demo + +```bash +pnpm install +pnpm test +pnpm typecheck +pnpm dev +``` + +Then, in another shell: + +```bash +pnpm cli validate examples/soundmart/actions.json +pnpm cli ingest-url http://127.0.0.1:4173/.well-known/constraint-net/actions.json --server http://127.0.0.1:4173 +pnpm cli plan --goal "Return my headphones from SoundMart and choose the fastest free pickup" --merchant soundmart.example --server http://127.0.0.1:4173 +``` + +## Not Yet Production + +Do not present this alpha as production infrastructure until these are replaced: + +- in-memory store +- public development signing key +- mock OpenAPI-backed execution +- single-process receipt store +- local-only trust and publisher registry +- absence of hosted monitoring, abuse controls, and key rotation diff --git a/package.json b/package.json index 73c6518..b59475e 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,9 @@ { "name": "constraint-net-mvp", + "description": "Public-alpha protocol gateway for agent-safe discovery, planning, consent, execution, and receipt verification.", "version": "0.1.0", "private": true, + "license": "Apache-2.0", "type": "module", "packageManager": "pnpm@10.32.1", "bin": { diff --git a/src/keys.ts b/src/keys.ts index 98d4fcb..d9d2172 100644 --- a/src/keys.ts +++ b/src/keys.ts @@ -1,5 +1,7 @@ export const DEV_KEY_ID = "constraint-net-dev-2026-05"; +// This is a public development issuer for reproducible local examples and tests. +// Do not use this private key for production publishers, hosted gateways, or real receipts. export const DEV_PRIVATE_KEY_PEM = `-----BEGIN PRIVATE KEY----- MC4CAQAwBQYDK2VwBCIEIOC68Bzd/kyQPe54raxib3DBePf6KBXVMGsdsuor1ziR -----END PRIVATE KEY-----`; diff --git a/tests/public-launch.test.ts b/tests/public-launch.test.ts new file mode 100644 index 0000000..c13c69a --- /dev/null +++ b/tests/public-launch.test.ts @@ -0,0 +1,36 @@ +import { existsSync, readFileSync } from "node:fs"; +import { describe, expect, it } from "vitest"; + +function read(path: string): string { + return readFileSync(path, "utf8"); +} + +describe("public launch readiness", () => { + it("includes the public repo files developers expect before adoption", () => { + expect(existsSync("LICENSE")).toBe(true); + expect(existsSync("SECURITY.md")).toBe(true); + expect(existsSync("CONTRIBUTING.md")).toBe(true); + expect(existsSync("docs/launch-checklist.md")).toBe(true); + expect(existsSync(".github/pull_request_template.md")).toBe(true); + }); + + it("states the alpha safety boundary in the package metadata and README", () => { + const pkg = JSON.parse(read("package.json")); + const readme = read("README.md"); + + expect(pkg.license).toBe("Apache-2.0"); + expect(pkg.description).toContain("agent-safe"); + expect(readme).toContain("Public Alpha"); + expect(readme).toContain("not production key custody"); + expect(readme).toContain("mock OpenAPI-backed execution"); + }); + + it("keeps public CI and development signing keys explicit", () => { + const workflow = read(".github/workflows/ci.yml"); + const keys = read("src/keys.ts"); + + expect(workflow).toContain("FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true"); + expect(keys).toContain("public development issuer"); + expect(keys).toContain("Do not use"); + }); +});