@charter-agreement-protocol/signer 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -3,6 +3,153 @@
 All notable public changes to `@charter-agreement-protocol/signer` are
 documented here.
 
+## [0.3.0] — October 14, 2026
+
+### Breaking
+
+- `signAcceptance` and `signTermination` now take `(claims, keyHandle, chain,
+  opts)`. The verifier derives context from that chain; `revisionText` and
+  `descriptorCompacts` are removed from the signer input. Migration:
+
+  ```ts
+  // Before
+  await signAcceptance(claims, keyHandle, { revisionText, descriptorCompacts, chain }, opts);
+  // Now
+  await signAcceptance(claims, keyHandle, chain, opts);
+  await signTermination(terminationClaims, keyHandle, chain, opts);
+  ```
+
+- The holder's own descriptor key is checked before signing. A wrong kid,
+  public key, or key algorithm returns
+  `{ ok: false, error: "refused", code: "signing_key_mismatch" }`.
+  `signing_key_invalid` maps to `invalid_key_handle`. For otherwise valid
+  descriptor claims, an absent or null successor predecessor, a valid predecessor
+  supplied to a genesis, broken signed lineage, or digest aliases that disagree
+  with the reverified lineage return `invalid_input`/`descriptor_chain_invalid`.
+  A non-object predecessor, both digest aliases absent, or missing, null, empty,
+  or non-string lineage return `invalid_input`/`invalid_type`. Throwing reads also
+  return `invalid_type`. History excluded by a profile or requiring unavailable
+  crypto preserves the profile or substrate code.
+- Context, claims/context mismatches, profile exclusions, and compact size
+  limits reject before the signing callback. Missing or malformed context
+  types return `invalid_input`/`invalid_type`; malformed sets preserve the
+  verifier's code, including `compact_invalid`. `verification_failed` now
+  means only that `finishSigning` rejected what preparation approved.
+- Unavailable crypto returns the top-level
+  `{ ok: false, error: "algorithm_unsupported_on_substrate" }` before signing,
+  including an ML-DSA-65 request on the browser bundle.
+- Rename `invalid_handle` to `invalid_key_handle`. Update error comparisons
+  and exhaustive switches; the result shape is unchanged. Add the new substrate
+  error and refusal code to exhaustive handling.
+- Options must be absent or a plain object containing only `algorithm`,
+  `limits`, `profile`, and (for `signDescriptor`) `predecessor`. Unknown keys,
+  non-plain objects, and unreadable getters return `invalid_input`/`invalid_type`.
+  Malformed limits and profiles preserve `invalid_limits` and `invalid_profile`.
+  Previously, a misspelled option key silently fell back to Ed25519.
+
+### Added
+
+- `signDescriptor` accepts the verifier's `DescriptorPredecessor` as
+  `opts.predecessor`, with retained signed `lineage`, for successor descriptors.
+- All four functions accept verifier `limits` and `profile` options. Limits
+  include the final compact and context artifacts and also apply to the custody
+  guard and completion. Profiles check the new artifact and retained context.
+- `signReceipt` accepts bare revision text as well as a chain view. With a
+  bare revision, the custody guard checks the snapshot key and verifier facts
+  list `signature` in `not_verified`.
+- Export `SigningOptions` and `DescriptorOptions`. Real-key tests cover
+  Ed25519 and ML-DSA-65 successors and pre-sign refusals, with zero signing calls
+  asserted on rejection. The browser bundle test runs the complete workshop flow.
+- Include `SECURITY.md`, `CODE_OF_CONDUCT.md`, and `CONTRIBUTING.md` in the
+  npm package with this package's reporting and contribution practices.
+- Run the shared signer table from `charter_agreement_signer` 0.5.0, copied byte for byte with
+  a SHA-256 check. All 121 rows use real seed keys and compare result shapes,
+  codes, snapshot counts, and custody counts. Twelve Ed25519 successes match
+  exact compacts; five ML-DSA-65 successes pass public verification. The explicit
+  list of unexpressible rows is empty, and the run count is asserted. Eight
+  shared requests or contexts needing ML-DSA-65 refuse before browser custody.
+
+### Changed
+
+- Delegate preparation and completion to verifier 0.7.0's `prepareSigning`
+  and `finishSigning`; remove the signer's context derivation,
+  producer calls, assembly calls, and choice of post-sign verification function.
+- Require `@charter-agreement-protocol/verifier` ^0.7.0. Its signing preparation
+  corpus uses the public input shapes, and signing plans can only be made through
+  `prepareSigning`. The signer already uses that path.
+- Accept signature bytes from any JavaScript realm, including Buffer and plain
+  `Uint8Array`. Ed25519 snapshot keys with noncanonical y coordinates, no curve
+  point, x = 0 with the sign bit set, or small order return `invalid_key_handle`.
+  Invalid descriptor claim keys can fail earlier with `signing_input_invalid`.
+  The verifier checks option values before either key callback. Sparse profile
+  algorithm lists return `invalid_input`/`invalid_profile`; nonfinite or
+  explicitly undefined limit values return `invalid_input`/`invalid_limits`.
+- Copy claims into plain JSON before the first `await`, without array
+  constructor hooks. Read defined context and predecessor members once and
+  retain artifact lists for the verifier. Lineage arrays have no JSON bounds.
+  Claims entry guards use the verifier's maximum JSON bounds. Caller limits and final compact size are
+  checked by `prepareSigning`; oversize claims return `signing_input_invalid`.
+  Predecessor lineage has no signer item limit.
+- Read defined option members once with ordinary property access, including
+  inherited members and accepted class or Map properties. Keep invalid member
+  values opaque for the verifier's checks. Return every verifier option error,
+  including copy errors. Long algorithm lists retain an invalid length without
+  walking their entries.
+- Run all 121 shared rows in Node and the browser bundle with no skips.
+  `ml-successor-ok` and `ml-successor-wrong` now use their table
+  `expected_limited`: `algorithm_unsupported_on_substrate`, one snapshot, and
+  zero custody calls because the browser cannot verify ML-DSA-65 predecessor
+  history. Node retains successor success and
+  `invalid_input`/`descriptor_chain_invalid`, respectively. Removing the duplicate
+  `termination-excluded-context` row
+  reduces the exact Ed25519 success count from 13 to 12 in each lane.
+  Existing row outcomes and the signer API remain unchanged with this build.
+- Resolve limits, then profile, then algorithm, before taking the key snapshot.
+  Absent, `undefined`, and `null` algorithms select Ed25519. Explicit values are
+  `Ed25519` and `ML-DSA-65`; others return `invalid_input`/`algorithm_unsupported`
+  before either callback. The snapshot checks only a non-empty string kid and
+  a string public key; the verifier checks key encoding and shape.
+- Keep version 0.3.0 and the workshop badge. Builds remove stale library output;
+  CI typechecks and builds the workshop on Linux with Node 24.8.0 and Node 24.
+- SECURITY.md uses GitHub private vulnerability reporting. Evidence descriptions
+  name the checks that run; this signer has no telemetry.
+- See the [profile scope](README.md#profile-scope) for the shared ruling.
+
+### Migration from CAP 0.4 to 0.5
+
+- Revisions must name two distinct parties from different descriptor histories.
+  Replace fixtures that use one descriptor for both roles with two real parties.
+  Chain views supply explicit `revisions`, `acceptances`, `descriptors`, and
+  `terminations` arrays, including empty lists.
+
+### Migration from verifier 0.5 to 0.6
+
+- Producer build failures surface as `invalid_input`/`signing_input_invalid`.
+  Termination claims omit `extensions` and other extra members.
+- Digests are canonical base64url SHA-256 values and revision JSON is canonical.
+  Descriptor keys use canonical encodings with the selected algorithm's byte
+  length. Mixed party histories and unknown claims reject.
+- Direct verifier callers pass retained signed `lineage` in predecessor facts
+  to `verifyDescriptor`; `{ digest, claims }` alone is insufficient. Genesis
+  calls omit the predecessor. This signer exposes that predecessor in options.
+- Profiles and limits can reject context as well as the new artifact.
+
+## [0.2.2] — October 6, 2026
+
+### Changed
+
+- Update the build compiler from TypeScript 5.9.3 to 7.0.2 (`^7.0.2`),
+  removing the `~5.9.0` pin; update `@types/node` to 26.6.4 (`^26.6.4`).
+- Reconcile README and workshop documentation with verifier 0.5.0 and signer
+  0.2.2. Make the Node quickstart executable, document development and trusted
+  publisher staging, and clarify the workshop's chain/receipt verification,
+  artifact kinds, refusal ordering, and Node-only ML-DSA support.
+- Observed on October 6, 2026: `npm ci`, `typecheck`, all 18 tests, `build`,
+  `typecheck:web`, `build:site`, and `npm pack --dry-run` pass.
+  `diff -ru` against the TypeScript 5.9.3 baseline reports no differences:
+  all four emitted JavaScript and declaration files are byte-identical.
+  `npm outdated --json` returns `{}`.
+
 ## [0.2.1] — 2026-09-24
 
 Dependency-line release: this package now tracks the published verify
@@ -11,9 +158,8 @@ No API change: verifier 0.5.0 added consumer-side surface only (the
 capability probe, the signature registry identity, the descriptor
 timestamp floor, the 104-case corpus); the producer surface this package
 delegates to is unchanged. Typecheck strict, 18/18 tests against the
-resolved 0.5.0. The producer-side capability alignment (mirrored
-`capabilities()` with refuse-before-mint, declared minting metadata,
-profile-bound signing) is the next feature release on this line.
+resolved 0.5.0. Corrected in 0.3.0: 0.2.2 did not add signer capability metadata,
+profile options, or telemetry.
 
 ## [0.2.0] — 2026-09-17
 

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,87 @@
+<!-- Adapted from the Contributor Covenant version 2.1 (https://www.contributor-covenant.org),
+     the canonical text with the reporting contact substituted for this repository. -->
+
+# 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 the repository maintainer PRIVATELY at palermo777@gmail.com — conduct reports are kept
+confidential; please do not open public issues for conduct reports. 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

package/CONTRIBUTING.md

@@ -0,0 +1,71 @@
+# Contributing
+
+Contributions must preserve the signer's boundaries: the library depends
+only on the public verifier package, key identity comes from one atomic
+snapshot, errors contain no caller values, and test handles do not ship.
+Private keys stay behind the caller's callbacks.
+
+## Toolchain
+
+Use Node 24, at least 24.8.0, and npm. `package-lock.json` pins the build
+tools and verifier version. CI runs on Linux with Node 24.8.0 and the current
+Node 24 line.
+
+## Before a pull request
+
+Install with the frozen lockfile, then run the local checks:
+
+```console
+npm ci
+npm test
+npm run typecheck
+npm run typecheck:web
+npm run build
+npm run build:site
+npm pack --dry-run
+```
+
+The checks after installation run locally without a network connection.
+The suite builds a browser bundle with the workshop's shims and exercises
+real Ed25519 and ML-DSA-65 keys. The library build writes `dist/`; the site
+build writes `site-dist/`.
+
+## Windows
+
+Developer platforms are macOS and Linux. Windows developers use WSL2,
+clone inside its filesystem and follow the Linux commands. CI runs on
+Linux only. Native ML-DSA tests require the supported Node crypto runtime.
+
+## Commits
+
+Use explicit paths when staging or committing. Keep tool directories and
+local process state out of commits. Work on `main` in small commits with
+plain messages unless the maintainer asks otherwise. Do not use `git stash`.
+
+## Tests and checks
+
+- For behavior changes, write the test, observe it fail for the intended
+  reason, then make it pass. Record the observed failure in the commit.
+- New checks must fail under a named temporary mutation. Restore the
+  original code and run the suite again before committing.
+- Use real keys and real signing callbacks. Do not use mocks, fake crypto
+  or handles that return invented signatures.
+- Search for tests of the old contract before changing behavior.
+
+The local suite runs the [shared signer table](test/fixtures/README.md)
+against the TypeScript verifier this checkout installs. It compares recorded
+Elixir outcomes and exact Ed25519 compacts with real seed keys, then checks
+every success through verification. It does not execute Elixir locally.
+Keep the source table byte for byte and report disagreements with both outcomes.
+
+## Protocol dependency changes
+
+Move the verifier requirement and lockfile together. Read its changelog,
+test against the published package and document changes to input rules
+or error codes. Keep signing fixtures canonical.
+
+## Docs
+
+Update documentation with the behavior it describes. Keep error names,
+supported options, package metadata and the workshop's version badge in
+sync. Describe only checks that run and features that ship.