diff --git a/.credo.exs b/.credo.exs new file mode 100644 index 0000000..09eacfb --- /dev/null +++ b/.credo.exs @@ -0,0 +1,19 @@ +# SPDX-FileCopyrightText: 2026 Sudo Apt Holdings LLC +# SPDX-License-Identifier: Apache-2.0 +# +# Credo's defaults, plus the two security-relevant warnings its defaults leave off, on the code +# that ships (lib/), as in beam_mcp: UnsafeToAtom (atoms from input exhaust the atom table) and +# LeakyEnvironment (a spawned command inheriting the environment, secrets included). +%{ + configs: [ + %{ + name: "default", + checks: %{ + extra: [ + {Credo.Check.Warning.UnsafeToAtom, [files: %{included: ["lib/"]}]}, + {Credo.Check.Warning.LeakyEnvironment, [files: %{included: ["lib/"]}]} + ] + } + } + ] +} diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..9ade0d0 --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,20 @@ +# SPDX-FileCopyrightText: 2026 Sudo Apt Holdings LLC +# SPDX-License-Identifier: Apache-2.0 + +version: 2 +updates: + - package-ecosystem: mix + directory: "/" + schedule: + interval: weekly + open-pull-requests-limit: 5 + commit-message: + prefix: "deps" + + - package-ecosystem: github-actions + directory: "/" + schedule: + interval: weekly + open-pull-requests-limit: 5 + commit-message: + prefix: "ci" diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index e4c2ae5..50333b2 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -2,7 +2,9 @@ # SPDX-License-Identifier: Apache-2.0 # # The same three OTP/Elixir pairs as beam_mcp (floor, pinned, head): format, compile with -# warnings as errors, the suite. Actions pinned by commit SHA with the version beside it. +# warnings as errors, Credo --strict (.credo.exs), the Hex audit (retired packages and OSV +# advisories against mix.lock), the suite; and the DCO sign-off on every commit, as beam_mcp's +# gate workflow checks it. Actions pinned by commit SHA with the version beside it. name: ci on: @@ -36,4 +38,50 @@ jobs: - run: mix deps.get - run: mix format --check-formatted - run: mix compile --warnings-as-errors + - run: mix credo --strict + - run: mix hex.audit - run: mix test + + dco: + name: DCO sign-off + runs-on: ubuntu-24.04 + timeout-minutes: 5 + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + fetch-depth: 0 + - name: every commit in the range carries a Signed-off-by + run: | + set -uo pipefail + before="${{ github.event.before }}" + if [ "${{ github.event_name }}" = "pull_request" ]; then + range="origin/${{ github.base_ref }}..HEAD" + git rev-list --no-merges "$range" > /tmp/commits \ + || { echo "cannot resolve $range"; exit 1; } + elif [ -z "$before" ] \ + || [ "$before" = "0000000000000000000000000000000000000000" ] \ + || ! git rev-parse --verify --quiet "$before^{commit}" >/dev/null; then + # Two cases, one fallback. A branch's first push has no previous state, so + # github.event.before is the all-zeros SHA. A force-push names a real-looking SHA + # that is no longer reachable -- dropping a commit leaves `before` pointing at + # something the fetched history does not contain. Testing the SHA's SHAPE catches + # only the first; asking git whether it RESOLVES catches both. + echo "before is unusable ('$before'): checking every commit reachable from HEAD" + git rev-list --no-merges HEAD > /tmp/commits \ + || { echo "cannot list commits from HEAD"; exit 1; } + else + range="$before..HEAD" + git rev-list --no-merges "$range" > /tmp/commits \ + || { echo "cannot resolve $range"; exit 1; } + fi + echo "commits in scope: $(wc -l < /tmp/commits)" + fail=0 + while read -r sha; do + [ -z "$sha" ] && continue + if git log -1 --format='%B' "$sha" | grep -q '^Signed-off-by: '; then + echo " ok $sha" + else + echo " FAIL $sha carries no Signed-off-by"; fail=1 + fi + done < /tmp/commits + exit $fail diff --git a/CHANGELOG.md b/CHANGELOG.md index f123d97..3016b44 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,19 @@ SPDX-License-Identifier: Apache-2.0 ## [Unreleased] +### Added: the project's pages and checks (no code change) + +- `SECURITY.md` (private reporting, commitments, what a host can rely on, one known limit), + `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md` (Contributor Covenant 2.1, CC-BY-4.0 in + `LICENSES/`), `GOVERNANCE.md`, and `docs/`: architecture, assurance case, roadmap, + verifying a release (the tag-signing key's fingerprint). The pages are in the docs extras. +- CI: `mix credo --strict` (Credo as a dev/test dependency; `.credo.exs` adds `UnsafeToAtom` + and `LeakyEnvironment` on `lib/`), `mix hex.audit`, and a DCO sign-off check on every + commit. Dependabot weekly for Mix and GitHub Actions. +- `tools/release_tarball.sh`, beam_mcp's canonical-tarball script, and `files:` in `mix.exs` + as globs, so a release's bytes are the same on every machine. +- README: the OpenSSF Best Practices badge and links to the pages above. + ## [0.1.1] — 2026-09-19 ### Changed diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..5b9f62b --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,88 @@ + + +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our community include: + +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience +* Focusing on what is best not just for us as individuals, but for the overall community + +Examples of unacceptable behavior include: + +* The use of sexualized language or imagery, and sexual attention or advances of any kind +* Trolling, insulting or derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or email address, without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a professional setting + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at **ayla@scriptkittyos.com**, the maintainer (the address `SECURITY.md` names). A report about the maintainer themselves goes to the same address and is handled under the same guidelines; with one maintainer there is no one else to route it to, and this page says so rather than implying otherwise. All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the reporter of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series of actions. + +**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within the community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1, available at [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1]. + +Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder][Mozilla CoC]. + +For answers to common questions about this code of conduct, see the FAQ at [https://www.contributor-covenant.org/faq][FAQ]. Translations are available at [https://www.contributor-covenant.org/translations][translations]. + +[homepage]: https://www.contributor-covenant.org +[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html +[Mozilla CoC]: https://github.com/mozilla/diversity +[FAQ]: https://www.contributor-covenant.org/faq +[translations]: https://www.contributor-covenant.org/translations diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..6335aed --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,58 @@ + + +# Contributing + +Issues and pull requests are welcome on +[GitHub](https://github.com/ScriptKittyOS/beam_mcp_signer). A pull request is the only way a +change reaches `main`; it is rebased, never merged, so the history stays linear. The +maintainer reviews and decides (`GOVERNANCE.md`). + +## Getting set up + +```sh +git clone https://github.com/ScriptKittyOS/beam_mcp_signer && cd beam_mcp_signer +asdf install # the Erlang/OTP and Elixir versions .tool-versions pins (any manager that reads it works) +mix deps.get +mix test +``` + +Erlang/OTP 27 or newer and Elixir 1.17 or newer, the same floor as `beam_mcp`. CI runs +`mix format --check-formatted`, `mix compile --warnings-as-errors`, `mix credo --strict`, +`mix hex.audit` and `mix test` on three OTP/Elixir pairs; run the same before you push. + +## The rules, all enforced + +1. **Sign off every commit.** `git commit -s` adds the `Signed-off-by` line, certifying the + [Developer Certificate of Origin](https://developercertificate.org/): you wrote the change or + have the right to submit it under this project's licence. CI fails a pull request with a + commit that lacks it. +2. **No tool-attribution trailers.** A commit message says what changed and why it is believed + correct. +3. **CI must be green.** Warnings are errors; there is no baseline to hold. +4. **Tests arrive with behaviour.** Every change that adds or changes behaviour adds tests for + it to the automated suite, in the same pull request. A bug fix carries a regression test + that was seen failing before the fix, and the commit message shows the failure. A change to + how the key is read or returned also keeps the key-source census + (`test/beam_mcp/signer/no_key_source_test.exs`) red when the rule is broken: plant the + break, show it red, restore it. + +## Coding style + +The Elixir community's: the output of `mix format` (this repository's `.formatter.exs`) and +[Credo](https://hexdocs.pm/credo/) in `--strict` mode, which implement the +[Elixir Style Guide](https://github.com/christopheradams/elixir_style_guide), plus the security +warnings `.credo.exs` enables. CI enforces both. `beam_mcp`'s +[`CONVENTIONS.md`](https://github.com/ScriptKittyOS/beam_mcp/blob/main/CONVENTIONS.md) records +the wider rules both packages are developed under. + +## Conduct + +Participation is under the [Code of Conduct](CODE_OF_CONDUCT.md) (the Contributor Covenant, +version 2.1). + +## Reporting a vulnerability + +Not in an issue. See `SECURITY.md`. diff --git a/GOVERNANCE.md b/GOVERNANCE.md new file mode 100644 index 0000000..b615cac --- /dev/null +++ b/GOVERNANCE.md @@ -0,0 +1,44 @@ + + +# Governance + +Who decides, how a change lands, and what happens if the maintainer stops. This package is +governed exactly as [`beam_mcp`](https://github.com/ScriptKittyOS/beam_mcp) is, by the same +person; its [governance page](https://github.com/ScriptKittyOS/beam_mcp/blob/main/docs/governance.md) +and [succession page](https://github.com/ScriptKittyOS/beam_mcp/blob/main/docs/succession.md) +apply here, and this page says what is particular to this repository. + +## Roles + +| role | who | responsibilities | +|---|---|---| +| **Maintainer** | one person: the ScriptKittyOS organization's administrator, the hex.pm owner of `beam_mcp_signer` (account `aylacroft`), and the address in `SECURITY.md` | decides what lands and when; reviews every pull request; keeps CI green; answers security reports on `SECURITY.md`'s commitments; tags (signed) and publishes releases; keeps this page, the roadmap and the CHANGELOG true | +| **Contributor** | anyone | proposes changes by pull request under `CONTRIBUTING.md`: signed off, tested, green; reports bugs and enhancements as issues; reports vulnerabilities privately | + +There is no steering group and no vote. A decision is the maintainer's and is recorded in the +tree (a CHANGELOG entry, a page, a test) or it was not made. The bus factor is one, stated +rather than hidden. + +## How a change lands + +1. A branch and a pull request; nothing is pushed to `main` directly. +2. CI on three OTP/Elixir pairs (the floor, the pinned line, the newest) and the DCO check. +3. The maintainer's review, then a rebase merge. +4. A release is a signed tag and a hex.pm publish by the maintainer, recorded in the + CHANGELOG; `docs/verifying-releases.md` says how to check one. + +## What is particular to this package + +It is the one package of the two that handles key material, so a change to how the key is +read, used or returned is held to the key-source census and to `docs/assurance-case.md`, and +the assurance case changes in the same pull request. + +## If the maintainer stops + +`beam_mcp`'s succession page applies as written: the repository is public and forkable under +the organization, published releases stay on hex.pm, and a successor needs organization +ownership, `mix hex.owner add beam_mcp_signer` from the current owner (or hex.pm's support +process), and nothing else: this package holds no secret of its own. diff --git a/LICENSES/CC-BY-4.0.txt b/LICENSES/CC-BY-4.0.txt new file mode 100644 index 0000000..13ca539 --- /dev/null +++ b/LICENSES/CC-BY-4.0.txt @@ -0,0 +1,156 @@ +Creative Commons Attribution 4.0 International + + Creative Commons Corporation (“Creative Commons”) is not a law firm and does not provide legal services or legal advice. Distribution of Creative Commons public licenses does not create a lawyer-client or other relationship. Creative Commons makes its licenses and related information available on an “as-is” basis. Creative Commons gives no warranties regarding its licenses, any material licensed under their terms and conditions, or any related information. Creative Commons disclaims all liability for damages resulting from their use to the fullest extent possible. + +Using Creative Commons Public Licenses + +Creative Commons public licenses provide a standard set of terms and conditions that creators and other rights holders may use to share original works of authorship and other material subject to copyright and certain other rights specified in the public license below. The following considerations are for informational purposes only, are not exhaustive, and do not form part of our licenses. + +Considerations for licensors: Our public licenses are intended for use by those authorized to give the public permission to use material in ways otherwise restricted by copyright and certain other rights. Our licenses are irrevocable. Licensors should read and understand the terms and conditions of the license they choose before applying it. Licensors should also secure all rights necessary before applying our licenses so that the public can reuse the material as expected. Licensors should clearly mark any material not subject to the license. This includes other CC-licensed material, or material used under an exception or limitation to copyright. More considerations for licensors. + +Considerations for the public: By using one of our public licenses, a licensor grants the public permission to use the licensed material under specified terms and conditions. If the licensor’s permission is not necessary for any reason–for example, because of any applicable exception or limitation to copyright–then that use is not regulated by the license. Our licenses grant only permissions under copyright and certain other rights that a licensor has authority to grant. Use of the licensed material may still be restricted for other reasons, including because others have copyright or other rights in the material. A licensor may make special requests, such as asking that all changes be marked or described. Although not required by our licenses, you are encouraged to respect those requests where reasonable. More considerations for the public. + +Creative Commons Attribution 4.0 International Public License + +By exercising the Licensed Rights (defined below), You accept and agree to be bound by the terms and conditions of this Creative Commons Attribution 4.0 International Public License ("Public License"). To the extent this Public License may be interpreted as a contract, You are granted the Licensed Rights in consideration of Your acceptance of these terms and conditions, and the Licensor grants You such rights in consideration of benefits the Licensor receives from making the Licensed Material available under these terms and conditions. + +Section 1 – Definitions. + + a. Adapted Material means material subject to Copyright and Similar Rights that is derived from or based upon the Licensed Material and in which the Licensed Material is translated, altered, arranged, transformed, or otherwise modified in a manner requiring permission under the Copyright and Similar Rights held by the Licensor. For purposes of this Public License, where the Licensed Material is a musical work, performance, or sound recording, Adapted Material is always produced where the Licensed Material is synched in timed relation with a moving image. + + b. Adapter's License means the license You apply to Your Copyright and Similar Rights in Your contributions to Adapted Material in accordance with the terms and conditions of this Public License. + + c. Copyright and Similar Rights means copyright and/or similar rights closely related to copyright including, without limitation, performance, broadcast, sound recording, and Sui Generis Database Rights, without regard to how the rights are labeled or categorized. For purposes of this Public License, the rights specified in Section 2(b)(1)-(2) are not Copyright and Similar Rights. + + d. Effective Technological Measures means those measures that, in the absence of proper authority, may not be circumvented under laws fulfilling obligations under Article 11 of the WIPO Copyright Treaty adopted on December 20, 1996, and/or similar international agreements. + + e. Exceptions and Limitations means fair use, fair dealing, and/or any other exception or limitation to Copyright and Similar Rights that applies to Your use of the Licensed Material. + + f. Licensed Material means the artistic or literary work, database, or other material to which the Licensor applied this Public License. + + g. Licensed Rights means the rights granted to You subject to the terms and conditions of this Public License, which are limited to all Copyright and Similar Rights that apply to Your use of the Licensed Material and that the Licensor has authority to license. + + h. Licensor means the individual(s) or entity(ies) granting rights under this Public License. + + i. Share means to provide material to the public by any means or process that requires permission under the Licensed Rights, such as reproduction, public display, public performance, distribution, dissemination, communication, or importation, and to make material available to the public including in ways that members of the public may access the material from a place and at a time individually chosen by them. + + j. Sui Generis Database Rights means rights other than copyright resulting from Directive 96/9/EC of the European Parliament and of the Council of 11 March 1996 on the legal protection of databases, as amended and/or succeeded, as well as other essentially equivalent rights anywhere in the world. + + k. You means the individual or entity exercising the Licensed Rights under this Public License. Your has a corresponding meaning. + +Section 2 – Scope. + + a. License grant. + + 1. Subject to the terms and conditions of this Public License, the Licensor hereby grants You a worldwide, royalty-free, non-sublicensable, non-exclusive, irrevocable license to exercise the Licensed Rights in the Licensed Material to: + + A. reproduce and Share the Licensed Material, in whole or in part; and + + B. produce, reproduce, and Share Adapted Material. + + 2. Exceptions and Limitations. For the avoidance of doubt, where Exceptions and Limitations apply to Your use, this Public License does not apply, and You do not need to comply with its terms and conditions. + + 3. Term. The term of this Public License is specified in Section 6(a). + + 4. Media and formats; technical modifications allowed. The Licensor authorizes You to exercise the Licensed Rights in all media and formats whether now known or hereafter created, and to make technical modifications necessary to do so. The Licensor waives and/or agrees not to assert any right or authority to forbid You from making technical modifications necessary to exercise the Licensed Rights, including technical modifications necessary to circumvent Effective Technological Measures. For purposes of this Public License, simply making modifications authorized by this Section 2(a)(4) never produces Adapted Material. + + 5. Downstream recipients. + + A. Offer from the Licensor – Licensed Material. Every recipient of the Licensed Material automatically receives an offer from the Licensor to exercise the Licensed Rights under the terms and conditions of this Public License. + + B. No downstream restrictions. You may not offer or impose any additional or different terms or conditions on, or apply any Effective Technological Measures to, the Licensed Material if doing so restricts exercise of the Licensed Rights by any recipient of the Licensed Material. + + 6. No endorsement. Nothing in this Public License constitutes or may be construed as permission to assert or imply that You are, or that Your use of the Licensed Material is, connected with, or sponsored, endorsed, or granted official status by, the Licensor or others designated to receive attribution as provided in Section 3(a)(1)(A)(i). + +b. Other rights. + + 1. Moral rights, such as the right of integrity, are not licensed under this Public License, nor are publicity, privacy, and/or other similar personality rights; however, to the extent possible, the Licensor waives and/or agrees not to assert any such rights held by the Licensor to the limited extent necessary to allow You to exercise the Licensed Rights, but not otherwise. + + 2. Patent and trademark rights are not licensed under this Public License. + + 3. To the extent possible, the Licensor waives any right to collect royalties from You for the exercise of the Licensed Rights, whether directly or through a collecting society under any voluntary or waivable statutory or compulsory licensing scheme. In all other cases the Licensor expressly reserves any right to collect such royalties. + +Section 3 – License Conditions. + +Your exercise of the Licensed Rights is expressly made subject to the following conditions. + + a. Attribution. + + 1. If You Share the Licensed Material (including in modified form), You must: + + A. retain the following if it is supplied by the Licensor with the Licensed Material: + + i. identification of the creator(s) of the Licensed Material and any others designated to receive attribution, in any reasonable manner requested by the Licensor (including by pseudonym if designated); + + ii. a copyright notice; + + iii. a notice that refers to this Public License; + + iv. a notice that refers to the disclaimer of warranties; + + v. a URI or hyperlink to the Licensed Material to the extent reasonably practicable; + + B. indicate if You modified the Licensed Material and retain an indication of any previous modifications; and + + C. indicate the Licensed Material is licensed under this Public License, and include the text of, or the URI or hyperlink to, this Public License. + + 2. You may satisfy the conditions in Section 3(a)(1) in any reasonable manner based on the medium, means, and context in which You Share the Licensed Material. For example, it may be reasonable to satisfy the conditions by providing a URI or hyperlink to a resource that includes the required information. + + 3. If requested by the Licensor, You must remove any of the information required by Section 3(a)(1)(A) to the extent reasonably practicable. + + 4. If You Share Adapted Material You produce, the Adapter's License You apply must not prevent recipients of the Adapted Material from complying with this Public License. + +Section 4 – Sui Generis Database Rights. + +Where the Licensed Rights include Sui Generis Database Rights that apply to Your use of the Licensed Material: + + a. for the avoidance of doubt, Section 2(a)(1) grants You the right to extract, reuse, reproduce, and Share all or a substantial portion of the contents of the database; + + b. if You include all or a substantial portion of the database contents in a database in which You have Sui Generis Database Rights, then the database in which You have Sui Generis Database Rights (but not its individual contents) is Adapted Material; and + + c. You must comply with the conditions in Section 3(a) if You Share all or a substantial portion of the contents of the database. +For the avoidance of doubt, this Section 4 supplements and does not replace Your obligations under this Public License where the Licensed Rights include other Copyright and Similar Rights. + +Section 5 – Disclaimer of Warranties and Limitation of Liability. + + a. Unless otherwise separately undertaken by the Licensor, to the extent possible, the Licensor offers the Licensed Material as-is and as-available, and makes no representations or warranties of any kind concerning the Licensed Material, whether express, implied, statutory, or other. This includes, without limitation, warranties of title, merchantability, fitness for a particular purpose, non-infringement, absence of latent or other defects, accuracy, or the presence or absence of errors, whether or not known or discoverable. Where disclaimers of warranties are not allowed in full or in part, this disclaimer may not apply to You. + + b. To the extent possible, in no event will the Licensor be liable to You on any legal theory (including, without limitation, negligence) or otherwise for any direct, special, indirect, incidental, consequential, punitive, exemplary, or other losses, costs, expenses, or damages arising out of this Public License or use of the Licensed Material, even if the Licensor has been advised of the possibility of such losses, costs, expenses, or damages. Where a limitation of liability is not allowed in full or in part, this limitation may not apply to You. + + c. The disclaimer of warranties and limitation of liability provided above shall be interpreted in a manner that, to the extent possible, most closely approximates an absolute disclaimer and waiver of all liability. + +Section 6 – Term and Termination. + + a. This Public License applies for the term of the Copyright and Similar Rights licensed here. However, if You fail to comply with this Public License, then Your rights under this Public License terminate automatically. + + b. Where Your right to use the Licensed Material has terminated under Section 6(a), it reinstates: + + 1. automatically as of the date the violation is cured, provided it is cured within 30 days of Your discovery of the violation; or + + 2. upon express reinstatement by the Licensor. + + c. For the avoidance of doubt, this Section 6(b) does not affect any right the Licensor may have to seek remedies for Your violations of this Public License. + + d. For the avoidance of doubt, the Licensor may also offer the Licensed Material under separate terms or conditions or stop distributing the Licensed Material at any time; however, doing so will not terminate this Public License. + + e. Sections 1, 5, 6, 7, and 8 survive termination of this Public License. + +Section 7 – Other Terms and Conditions. + + a. The Licensor shall not be bound by any additional or different terms or conditions communicated by You unless expressly agreed. + + b. Any arrangements, understandings, or agreements regarding the Licensed Material not stated herein are separate from and independent of the terms and conditions of this Public License. + +Section 8 – Interpretation. + + a. For the avoidance of doubt, this Public License does not, and shall not be interpreted to, reduce, limit, restrict, or impose conditions on any use of the Licensed Material that could lawfully be made without permission under this Public License. + + b. To the extent possible, if any provision of this Public License is deemed unenforceable, it shall be automatically reformed to the minimum extent necessary to make it enforceable. If the provision cannot be reformed, it shall be severed from this Public License without affecting the enforceability of the remaining terms and conditions. + + c. No term or condition of this Public License will be waived and no failure to comply consented to unless expressly agreed to by the Licensor. + + d. Nothing in this Public License constitutes or may be interpreted as a limitation upon, or waiver of, any privileges and immunities that apply to the Licensor or You, including from the legal processes of any jurisdiction or authority. + +Creative Commons is not a party to its public licenses. Notwithstanding, Creative Commons may elect to apply one of its public licenses to material it publishes and in those instances will be considered the “Licensor.” Except for the limited purpose of indicating that material is shared under a Creative Commons public license or as otherwise permitted by the Creative Commons policies published at creativecommons.org/policies, Creative Commons does not authorize the use of the trademark “Creative Commons” or any other trademark or logo of Creative Commons without its prior written consent including, without limitation, in connection with any unauthorized modifications to any of its public licenses or any other arrangements, understandings, or agreements concerning use of licensed material. For the avoidance of doubt, this paragraph does not form part of the public licenses. + +Creative Commons may be contacted at creativecommons.org. diff --git a/README.md b/README.md index 61031aa..bc46d5c 100644 --- a/README.md +++ b/README.md @@ -5,6 +5,8 @@ SPDX-License-Identifier: Apache-2.0 # beam_mcp_signer +[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/14775/badge)](https://www.bestpractices.dev/projects/14775) + An Ed25519 signer for [`beam_mcp`](https://github.com/ScriptKittyOS/beam_mcp)'s canonical connectome bytes, through OTP's `:crypto`. One module, `BeamMCP.Signer.Ed25519`, implementing core's `BeamMCP.Signer` behaviour (`sign/2`). @@ -32,3 +34,12 @@ not a dependency of this package in the other direction, and it never will be. A wants signatures adds this package and attaches the module; one that does not, does not. Apache-2.0. Erlang/OTP 27 or newer, Elixir 1.17 or newer -- the same floor as core. + +**The project.** Reference documentation is on [HexDocs](https://hexdocs.pm/beam_mcp_signer). +What a host can rely on, and how to report a vulnerability: [`SECURITY.md`](SECURITY.md). Why +the security requirements hold: [`docs/assurance-case.md`](docs/assurance-case.md), with the +design in [`docs/architecture.md`](docs/architecture.md). Checking a release's signature: +[`docs/verifying-releases.md`](docs/verifying-releases.md). Contributing: +[`CONTRIBUTING.md`](CONTRIBUTING.md), under the [Code of Conduct](CODE_OF_CONDUCT.md). Who +decides, and what comes next: [`GOVERNANCE.md`](GOVERNANCE.md), +[`docs/roadmap.md`](docs/roadmap.md). Bugs and ideas: [issues](https://github.com/ScriptKittyOS/beam_mcp_signer/issues). diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..a913af5 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,82 @@ + + +# Security Policy + +## Reporting a vulnerability + +Report privately through **[GitHub Security Advisories](https://github.com/ScriptKittyOS/beam_mcp_signer/security/advisories/new)**. +Please do not open a public issue for a suspected vulnerability. A report that cannot go +through the form goes to **ayla@scriptkittyos.com**, the maintainer, on the same commitments. + +A report about `beam_mcp` itself (the protocol core, the canonical bytes) belongs to +[its policy](https://github.com/ScriptKittyOS/beam_mcp/blob/main/SECURITY.md); if you are not +sure which package it is, send it to either and it will be routed. + +## What this project commits to + +One person maintains this package, and these are commitments that can be kept: + +- **Acknowledgement within 7 days.** If you hear nothing after 7 days, assume the report did + not arrive and open a public issue saying only that you are waiting on a security response. +- **An assessment within 30 days** of acknowledgement: in scope or not, a rough severity, and + an intended fix window. If it will take longer, you are told so. +- **Credit in the advisory and the changelog**, unless you ask otherwise. + +No paid bounty and no guaranteed fix deadline. + +## What you can expect from this package + +The security requirements a host can rely on, each held by a test in `test/`: + +- **The key is read from one place.** `sign/2` reads the private key from + `opts[:private_key]` on each call and from nowhere else: no environment variable, file, + application config, default key or store. A two-layer census holds it + (`test/beam_mcp/signer/no_key_source_test.exs`). +- **The key does not leave in a result.** Every return value is a signature or a fixed error + term; neither carries the key. **One known limit:** a call that breaks the documented types + (bytes that are not a binary, or options that are not a keyword list, here or at + `beam_mcp`'s `Canonical.signature/3`) raises a `FunctionClauseError`, and Elixir prints that + exception with its arguments, the key among them, wherever it is logged. Pass a keyword + list. Closing it for misuse too is open work, stated in `docs/assurance-case.md`. +- **The signature is standard Ed25519** (RFC 8032, FIPS 186-5) over exactly the canonical bytes + `beam_mcp` produced, computed by Erlang/OTP's `:crypto` (OpenSSL), and verifiable by any + Ed25519 implementation. +- **No randomness is needed or used.** Ed25519 signing is deterministic; the package generates + no key and no nonce. + +What it does **not** do: store, load, rotate or protect the key between calls (the host's +decision, `docs/assurance-case.md` says why), verify signatures, or decide what a signature +authorizes. + +## Severity, in this package's terms + +| level | what it means here | +|---|---| +| **Critical** | On a call with the documented types: the key is read from anywhere but the call's options, or reaches a log, an error, a crash report or a return value; or a signature is produced over bytes other than those given. | +| **High** | A signature that standard Ed25519 verification rejects, or accepts over different bytes. | +| **Medium** | A documented behaviour the package does not match, with a security consequence a host can work around. | +| **Low** | Wrong error terms or documentation that could mislead. | + +## CVEs + +Advisories are published from this repository's GitHub Security Advisories. GitHub is a CVE +Numbering Authority for the repositories it hosts, so a CVE is requested from the advisory +draft when the defect warrants one; Critical and High always do. Published advisories reach +the GitHub Advisory Database and OSV, which `mix hex.audit` reads. + +## Out of scope + +- How and where the host stores the key. +- Defects in Erlang/OTP's `:crypto` or OpenSSL; report those upstream. +- `beam_mcp`'s own code; see its policy, linked above. + +## Supported versions + +| version | supported | +|---|---| +| `0.1.x` | yes | + +Fixes land on the latest release. diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 0000000..581e5aa --- /dev/null +++ b/docs/architecture.md @@ -0,0 +1,52 @@ + + +# Architecture + +One module, one function, one dependency direction. + +```text + host application + | Canonical.signature(graph, BeamMCP.Signer.Ed25519, private_key: key, ...) + v + beam_mcp (BeamMCP.Connectome.Canonical) + | encodes the graph to canonical bytes, then calls the signer through + | the BeamMCP.Signer behaviour: sign(canonical_bytes, opts) + v + beam_mcp_signer (BeamMCP.Signer.Ed25519.sign/2) + | reads opts[:private_key] (32 bytes) and nothing else + v + Erlang/OTP :crypto.sign(:eddsa, :none, canonical_bytes, [key, :ed25519]) (OpenSSL) + | + v + {:ok, 64-byte signature} -> placed beside the bytes by beam_mcp +``` + +## The parts + +- **`BeamMCP.Signer.Ed25519`** (`lib/beam_mcp/signer/ed25519.ex`): implements `beam_mcp`'s + `BeamMCP.Signer` behaviour. `sign/2` takes the canonical bytes and the host's options, reads + the private key from `opts[:private_key]`, checks it is a 32-byte binary, and returns + `{:ok, signature}`, `{:error, :no_private_key}` or `{:error, {:private_key, :not_32_bytes}}`. +- **`beam_mcp`** (a dependency, `~> 0.7`): defines the behaviour and produces the bytes. It + holds no key, calls no signing primitive and does not depend on this package. +- **Erlang/OTP `:crypto`**: performs Ed25519. This package implements no cryptography itself. + +## Properties the arrangement keeps + +- **The key lives with the host.** Nothing is stored between calls: no process, table, + persistent term, application environment or file. A test checks that no state remains after + a call. +- **One way in.** The key has one source, the call's options; a census over both the source + and the compiled module holds that (`test/beam_mcp/signer/no_key_source_test.exs`). +- **Core stays keyless.** Authority (a key, a signature) is kept out of `beam_mcp` by putting + it here, in a package a host chooses to add. + +## Where to read next + +`docs/assurance-case.md` (why the security requirements hold), `SECURITY.md` (what a host can +expect), and `beam_mcp`'s +[`docs/architecture.md`](https://github.com/ScriptKittyOS/beam_mcp/blob/main/docs/architecture.md) +for the bytes being signed. diff --git a/docs/assurance-case.md b/docs/assurance-case.md new file mode 100644 index 0000000..629198f --- /dev/null +++ b/docs/assurance-case.md @@ -0,0 +1,79 @@ + + +# Assurance case + +Why this package's security requirements (`SECURITY.md`, "What you can expect") are met, and +where they stop. + +## The claim + +**Given a 32-byte Ed25519 private key in the call's options, `sign/2` returns a standard +Ed25519 signature over exactly the bytes given, reads the key from nowhere else, keeps no copy +of it, and returns nothing that contains it.** + +## Threat model + +The asset is the host's private key; the goal is that this package adds no way for it to be +read, kept or misused beyond the host's own call. + +| threat | in scope | how it is met | +|---|---|---| +| The key read from a place the host did not choose (environment, file, config) | yes | one source, `opts[:private_key]`; census over source text and compiled calls | +| The key retained after the call (process state, ETS, persistent term, app env) | yes | no state; a test compares all four before and after a call | +| The key returned or placed in an error term | yes | returns are a signature or a fixed atom tuple; tests pin every error term | +| The key printed in an exception when the call breaks the documented types | **yes, not yet met** | see "Open work" below | +| A signature over bytes other than those given, or a non-standard signature | yes | the bytes go to `:crypto.sign/4` unaltered; tests verify with `:crypto.verify/5` and with core's `encode!/2` bytes | +| Weak randomness | yes | none used: Ed25519 is deterministic (RFC 8032), no nonce or key is generated here | +| The host's key storage, the node the host runs, OpenSSL defects | no | the host's and upstream's; stated in `SECURITY.md` | +| Code already running in the same BEAM node | no | the BEAM has no in-node isolation; any process there can read the host's memory | + +## Trust boundaries + +1. **Host to this package.** The host is trusted to supply the key and the options. This + package trusts nothing else: it reads no ambient configuration. +2. **This package to `beam_mcp`.** Core supplies the bytes; this package signs exactly them + and does not interpret them. +3. **This package to OpenSSL** (through OTP `:crypto`). Trusted to implement Ed25519 + correctly; that trust is FIPS 186-5 and RFC 8032's, not this project's. + +## Secure design principles applied + +| principle | here | +|---|---| +| Economy of mechanism | one module, one public function, two remote calls (`:crypto.sign/4`, `Keyword.fetch/2`), pinned by census | +| Fail-safe defaults | no default key; a missing or malformed key is an error, never a signature | +| Complete mediation | the key is checked on every call; nothing is cached | +| Open design | standard Ed25519, verifiable by any implementation; the source is Apache-2.0 | +| Separation of privilege | the key-holding code is a separate package from the keyless core; the host opts in | +| Least privilege | no file, network, environment, OS or application-config access, held by census | +| Least common mechanism | no shared state between calls or callers | +| Psychological acceptability | two named error terms a host can match and act on | + +## Common implementation weaknesses countered + +| weakness | countered by | +|---|---| +| CWE-798 / CWE-321 hard-coded or default key | no default key; census over the source; the history is secret-scanned | +| CWE-522 / CWE-256 insufficiently protected credentials | nothing stored; the key's lifetime is the host's call | +| CWE-338 / CWE-330 weak randomness | no randomness is used | +| CWE-327 / CWE-326 broken algorithm, short key | Ed25519 only, 32-byte seeds only (about 128-bit security, NIST-approved in FIPS 186-5) | +| CWE-347 improper signature verification | not applicable to signing; tests verify every signature with an independent call | +| CWE-209 / CWE-532 key in errors or logs | met for returns; open for exceptions on misuse (below) | + +## Open work + +A call that breaks the documented types (bytes that are not a binary, options that are not a +keyword list) raises `FunctionClauseError`, and Elixir formats that exception with the call's +arguments, so the key can reach a crash log. `beam_mcp`'s `Canonical.signature/3` has the same +shape before it reaches this package. It needs a correctly typed call to be safe today. +Closing it is a contract decision across both packages (answer misuse with an error term that +echoes nothing, or take the key by reference so no exception can carry its bytes) and is on +`docs/roadmap.md`. + +## How the case is kept true + +CI runs the suite, the census and Credo on every push on three OTP/Elixir pairs; a change to how +the key is read or returned changes this page in the same pull request (`GOVERNANCE.md`). diff --git a/docs/roadmap.md b/docs/roadmap.md new file mode 100644 index 0000000..c06cd43 --- /dev/null +++ b/docs/roadmap.md @@ -0,0 +1,38 @@ + + +# Roadmap + +What this package intends to do, and not do, over the next year (to September 2027). Dates +are not promised; the order is. + +## Planned + +1. **Close the misuse path** in `docs/assurance-case.md` ("Open work"), so a key cannot reach + an exception report even on a mistyped call, decided together with `beam_mcp`. +2. **Follow `beam_mcp` to `1.0.0`.** The requirement is `~> 0.7` today; when core ships + `1.0.0`, this package releases with a `~> 1.0` requirement, and then takes its own `1.0.0` + once its surface (one function, three results) has stood a release unchanged. +3. **Release tooling as core has it**: the canonical tarball script (in the tree) used for + every publish, and a build-provenance attestation on each release tag. +4. **Keep current**: security fixes on `SECURITY.md`'s commitments, dependency updates through + Dependabot, and the OTP/Elixir pairs CI tests moved forward with `beam_mcp`'s. + +## Will not do + +- **Store, load, generate or rotate keys.** The host holds the key; this package reads it from + the call's options and nowhere else. That is the package's reason to exist. +- **Implement cryptography.** Ed25519 is OTP's `:crypto`, backed by OpenSSL. +- **Verify signatures or decide what they authorize.** Verification is one standard call any + consumer can make; authority is the consumer's. +- **Make `beam_mcp` depend on it.** The dependency runs one way. + +A second algorithm is not planned; if one is ever needed it would be a separate module +implementing the same behaviour, decided in the open. + +## How it changes + +A change to this page is made in the pull request that changes direction, and recorded in the +CHANGELOG. Proposals are issues on the repository. diff --git a/docs/verifying-releases.md b/docs/verifying-releases.md new file mode 100644 index 0000000..1393526 --- /dev/null +++ b/docs/verifying-releases.md @@ -0,0 +1,41 @@ + + +# Verifying a release + +## The tag's signature + +Every release tag (`v0.1.0` on) is an annotated tag signed with the maintainer's OpenPGP key, +the same key that signs `beam_mcp`'s tags. It is published on the maintainer's GitHub account, +and its fingerprint is: + +```text +24FE 4F05 E3E8 EC26 1462 A0C7 82A6 7035 D628 7F15 +``` + +```sh +curl -fsSL https://github.com/HackTuah.gpg | gpg --import +gpg --fingerprint 24FE4F05E3E8EC261462A0C782A67035D6287F15 # compare with the line above +git clone https://github.com/ScriptKittyOS/beam_mcp_signer && cd beam_mcp_signer +git tag -v v0.1.1 # "Good signature" or it did not verify +``` + +The private key is held on the maintainer's own machine, not on GitHub or hex.pm. If it is +ever replaced, this page and the CHANGELOG say so in the same commit, with the new +fingerprint. + +## The package bytes + +hex.pm serves the package over HTTPS, and `mix` checks each download against the checksum in +`mix.lock`. To rebuild the tarball from a tag and compare: + +```sh +tools/release_tarball.sh "v${v}" "beam_mcp_signer-${v}.tar" # prints the tarball's sha256 +``` + +The script builds from `git archive` of the tag (tracked files only, every file mode 644) so +two machines produce the same bytes. A release published with the script (`--publish`) has +the checksum hex.pm shows; `0.1.0` and `0.1.1` were built from a working tree before the +script existed, and are verified by their signed tags only. diff --git a/mix.exs b/mix.exs index 74bbcce..f6a71f0 100644 --- a/mix.exs +++ b/mix.exs @@ -24,7 +24,18 @@ defmodule BeamMCP.Signer.Ed25519.MixProject do description: "Ed25519 signer for beam_mcp's canonical connectome bytes, through OTP's :crypto; the host hands the key in", source_url: @source_url, - docs: [main: "readme", extras: ["README.md", "CHANGELOG.md"]], + docs: [ + main: "readme", + extras: [ + "README.md", + "CHANGELOG.md", + "SECURITY.md", + "docs/architecture.md", + "docs/assurance-case.md", + "docs/roadmap.md", + "docs/verifying-releases.md" + ] + ], aliases: [check_otp: &check_otp!/1] ] end @@ -40,7 +51,8 @@ defmodule BeamMCP.Signer.Ed25519.MixProject do # stops at 1.0.0, and a host is not held on the previous core minor by this package # (0.1.0's `~> 0.7.0` did exactly that at core's 0.8.0). Nothing else: Ed25519 is OTP's. {:beam_mcp, "~> 0.7"}, - {:ex_doc, "~> 0.34", only: :dev, runtime: false} + {:ex_doc, "~> 0.34", only: :dev, runtime: false}, + {:credo, "~> 1.7", only: [:dev, :test], runtime: false} ] end @@ -49,7 +61,9 @@ defmodule BeamMCP.Signer.Ed25519.MixProject do name: "beam_mcp_signer", licenses: ["Apache-2.0"], links: %{"GitHub" => @source_url, "beam_mcp" => "https://github.com/ScriptKittyOS/beam_mcp"}, - files: ~w(lib mix.exs README.md CHANGELOG.md LICENSE NOTICE) + # Globs, not a directory: a directory in `files:` is walked in readdir order, which differs + # between filesystems, so the tarball would be the machine's (tools/release_tarball.sh). + files: ~w(lib/**/*.ex mix.exs README.md CHANGELOG.md LICENSE NOTICE) ] end diff --git a/mix.lock b/mix.lock index 524ed7e..07bd1ed 100644 --- a/mix.lock +++ b/mix.lock @@ -1,7 +1,10 @@ %{ "beam_mcp": {:hex, :beam_mcp, "0.8.0", "49f2607a92da4137cd1d11fc8669c396e1d93eedf7a3e29aaab1531dd41bd9c2", [:mix], [{:bandit, "~> 1.5", [hex: :bandit, repo: "hexpm", optional: true]}, {:jason, "~> 1.4", [hex: :jason, repo: "hexpm", optional: false]}, {:plug, "~> 1.16", [hex: :plug, repo: "hexpm", optional: true]}, {:telemetry, "~> 1.0", [hex: :telemetry, repo: "hexpm", optional: false]}], "hexpm", "b5a1beba2c936c2c50e164c43240ac31bc8b159a994980083ec0f6562392801e"}, + "bunt": {:hex, :bunt, "1.0.0", "081c2c665f086849e6d57900292b3a161727ab40431219529f13c4ddcf3e7a44", [:mix], [], "hexpm", "dc5f86aa08a5f6fa6b8096f0735c4e76d54ae5c9fa2c143e5a1fc7c1cd9bb6b5"}, + "credo": {:hex, :credo, "1.7.19", "cc52129665fc7c15143d47838fda0f9cd6dac9ceced7bf4da6f85fcbfe64b12a", [:mix], [{:bunt, "~> 0.2.1 or ~> 1.0", [hex: :bunt, repo: "hexpm", optional: false]}, {:file_system, "~> 0.2 or ~> 1.0", [hex: :file_system, repo: "hexpm", optional: false]}, {:jason, "~> 1.0", [hex: :jason, repo: "hexpm", optional: false]}], "hexpm", "2d8bc95d5a7bb99dd2613621d4f08c6a3575c3fd4b62e6a2b48a100352a557b8"}, "earmark_parser": {:hex, :earmark_parser, "1.4.46", "67607a0532e810c6f630a515c548d0b24949643f168cc556303bee4cf96105c7", [:mix], [], "hexpm", "9c44636e8a1c68c62f526b2dcd85d941dbbcee7ab82cf64ba06ce28bef8e89f5"}, "ex_doc": {:hex, :ex_doc, "0.40.4", "66f2e42bf588594d5a8aab31cad87f2ddad09d0da1b1a2f379340ec2c2e497cb", [:mix], [{:earmark_parser, "~> 1.4.46", [hex: :earmark_parser, repo: "hexpm", optional: false]}, {:makeup_c, ">= 0.1.0", [hex: :makeup_c, repo: "hexpm", optional: true]}, {:makeup_elixir, "~> 0.14 or ~> 1.0", [hex: :makeup_elixir, repo: "hexpm", optional: false]}, {:makeup_erlang, "~> 0.1 or ~> 1.0", [hex: :makeup_erlang, repo: "hexpm", optional: false]}, {:makeup_html, ">= 0.1.0", [hex: :makeup_html, repo: "hexpm", optional: true]}], "hexpm", "6222b9e423d76584ee34df2c82a5ed72c2d53dc153f7f483ad28b378694186cc"}, + "file_system": {:hex, :file_system, "1.1.1", "31864f4685b0148f25bd3fbef2b1228457c0c89024ad67f7a81a3ffbc0bbad3a", [:mix], [], "hexpm", "7a15ff97dfe526aeefb090a7a9d3d03aa907e100e262a0f8f7746b78f8f87a5d"}, "jason": {:hex, :jason, "1.4.5", "2e3a008590b0b8d7388c20293e9dcc9cf3e5d642fd2a114e4cbbb52e595d940a", [:mix], [{:decimal, "~> 1.0 or ~> 2.0 or ~> 3.0", [hex: :decimal, repo: "hexpm", optional: true]}], "hexpm", "b0c823996102bcd0239b3c2444eb00409b72f6a140c1950bc8b457d836b30684"}, "makeup": {:hex, :makeup, "1.2.2", "882d46dc0905e9ff7abf2aab61a7e6b3dcc555533977d8a23b06019e6c89ac94", [:mix], [{:nimble_parsec, "~> 1.4", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "9a1a24e5b343b8ae16abea0822c10a6f75da27af7fa802ada5251f7579bfccfa"}, "makeup_elixir": {:hex, :makeup_elixir, "1.0.1", "e928a4f984e795e41e3abd27bfc09f51db16ab8ba1aebdba2b3a575437efafc2", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}, {:nimble_parsec, "~> 1.2.3 or ~> 1.3", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "7284900d412a3e5cfd97fdaed4f5ed389b8f2b4cb49efc0eb3bd10e2febf9507"}, diff --git a/tools/release_tarball.sh b/tools/release_tarball.sh new file mode 100755 index 0000000..c0a2a7a --- /dev/null +++ b/tools/release_tarball.sh @@ -0,0 +1,39 @@ +#!/usr/bin/env bash +# SPDX-FileCopyrightText: 2026 Sudo Apt Holdings LLC +# SPDX-License-Identifier: Apache-2.0 +# +# The release tarball, built the one way that gives the same bytes on every machine. +# +# tools/release_tarball.sh build; print the checksum +# tools/release_tarball.sh --publish the same, then `mix hex.publish` FROM +# THAT TREE, so what is published is +# what was built and attested +# +# WHY A SCRIPT. `mix hex.build` packages the working tree as it lies: each entry carries the +# file's on-disk mode (umask 002 gives 664, umask 022 gives 644 -- two checksums for one commit), +# and a directory named in `files:` is walked in readdir order (fixed by globs in mix.exs). So +# the bytes are made canonical by construction: the tree is `git archive`'d at the ref with +# `tar.umask=022` (every regular file 644, and only tracked files), extracted, the lock's +# dependencies resolved, and built there. The publisher runs it with --publish; anyone runs it +# to reproduce a release's checksum. The same script as beam_mcp's tools/release_tarball.sh, +# where the measurements behind it are recorded (docs/provenance.md there). +# +# What it does not do: pin Hex. Needs bash, git, and sha256sum or shasum. +set -euo pipefail +ref=${1:?ref (a tag or commit)}; out=${2:?output tarball path}; publish=${3:-} +[ -z "$publish" ] || [ "$publish" = "--publish" ] || { echo "third argument is --publish or nothing" >&2; exit 2; } +case "$out" in /*) ;; *) out="$PWD/$out" ;; esac +sha256() { if command -v sha256sum >/dev/null 2>&1; then sha256sum "$1"; else shasum -a 256 "$1"; fi | cut -d' ' -f1; } +root=$(git rev-parse --show-toplevel) +work=$(mktemp -d "${TMPDIR:-/tmp}/beam_mcp_signer-release.XXXXXX"); trap 'rm -rf "$work"' EXIT +git -C "$root" -c tar.umask=022 archive --format=tar "$ref" | tar -xp -C "$work" +cd "$work" +mix deps.get >/dev/null +mix hex.build -o "$out" | tee "$work/build.out" +sha=$(sha256 "$out") +grep -q "Package checksum: ${sha}" "$work/build.out" \ + || { echo "the tarball's sha256 ${sha} is not the checksum hex printed" >&2; exit 1; } +echo "release tarball ${out}: sha256 ${sha} (= hex's package checksum) from ${ref} = $(git -C "$root" rev-parse "${ref}^{commit}")" +if [ "$publish" = "--publish" ]; then + mix hex.publish +fi