chore: public release packaging

Publication packaging: anvil release pipeline, dependabot, SECURITY/CHANGELOG, badges, examples, agent docs. No library code changes.

Author: TheCryptoDonkey

.github/FUNDING.yml

@@ -0,0 +1 @@
+github: TheCryptoDonkey

.github/dependabot.yml

@@ -0,0 +1,47 @@
+version: 2
+
+# Canonical dependabot config for npm/TypeScript repos in forgesworn.
+# Synced from forgesworn/.github/templates/dependabot/dependabot.npm.yml.
+# Edit the template, not individual repos -- run the propagator to sync.
+#
+# Tiering:
+#   patch + minor  -> grouped, auto-merged on green CI
+#   major          -> individual PR, manual review
+#   TS / Node / framework majors -> ignored here, upgraded deliberately
+
+updates:
+  - package-ecosystem: npm
+    directory: "/"
+    schedule:
+      interval: weekly
+      day: monday
+    open-pull-requests-limit: 10
+    commit-message:
+      prefix: chore
+      include: scope
+    groups:
+      production-minor:
+        dependency-type: production
+        update-types: ["patch", "minor"]
+      dev-minor:
+        dependency-type: development
+        update-types: ["patch", "minor"]
+    ignore:
+      - dependency-name: "typescript"
+        update-types: ["version-update:semver-major"]
+      - dependency-name: "@types/node"
+        update-types: ["version-update:semver-major"]
+      - dependency-name: "node"
+        update-types: ["version-update:semver-major"]
+
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: monthly
+    open-pull-requests-limit: 5
+    commit-message:
+      prefix: chore
+      include: scope
+    groups:
+      actions-minor:
+        update-types: ["patch", "minor"]

.github/workflows/auto-release.yml

@@ -0,0 +1,13 @@
+name: auto-release
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write
+  actions: write
+
+jobs:
+  auto-release:
+    uses: forgesworn/anvil/.github/workflows/auto-release.yml@v0

.github/workflows/ci.yml

@@ -1,13 +1,25 @@
 name: CI
-on: [push, pull_request]
+
+on:
+  push:
+    branches: [main, dev, 'feat/**', 'fix/**', 'chore/**']
+  pull_request:
+    branches: [main, dev]
+
+permissions:
+  contents: read
+
 jobs:
   test:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+
+      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
         with:
-          node-version: '22'
+          node-version: 24
+          cache: npm
+
       - run: npm ci
-      - run: npx tsc --noEmit
-      - run: npm test
+      - run: npm run typecheck
+      - run: npm run coverage

.github/workflows/dependabot-auto-merge.yml

@@ -0,0 +1,29 @@
+name: Dependabot auto-merge
+
+# Auto-merges dependabot PRs for patch/minor bumps once required checks pass.
+# Majors are never auto-merged -- they open a normal PR for deliberate review.
+# Security advisories always open their own PR and follow the same gate.
+#
+# Synced from forgesworn/.github/templates/dependabot/dependabot-auto-merge.yml.
+
+on: pull_request
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  auto-merge:
+    if: github.event.pull_request.user.login == 'dependabot[bot]'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Fetch dependabot metadata
+        id: meta
+        uses: dependabot/fetch-metadata@d7267f607e9d3fb96fc2fbe83e0af444713e90b7 # v2.3.0
+
+      - name: Enable auto-merge for patch/minor
+        if: steps.meta.outputs.update-type == 'version-update:semver-patch' || steps.meta.outputs.update-type == 'version-update:semver-minor'
+        env:
+          PR_URL: ${{ github.event.pull_request.html_url }}
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: gh pr merge --auto --squash --delete-branch "$PR_URL"

.github/workflows/release.yml

@@ -0,0 +1,21 @@
+name: release
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: Release tag to publish
+        type: string
+        required: true
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  release:
+    uses: forgesworn/anvil/.github/workflows/release.yml@v0
+    with:
+      tag: ${{ inputs.tag || '' }}

AGENTS.md

@@ -0,0 +1,29 @@
+# AGENTS.md — private-equality
+
+Instructions in this file apply to the entire repository.
+
+## Project Summary
+
+`@forgesworn/private-equality` decides "do two parties hold the same secret —
+yes/no?" via the Socialist Millionaires' Protocol (OTR variant) over
+Ristretto255, revealing nothing else on mismatch. Pure four-message state
+machine; the consumer supplies the authenticated channel and ferries opaque
+bytes.
+
+## Commands
+
+- Build: `npm run build`
+- Test: `npm test`
+- Coverage gate: `npm run coverage`
+- Typecheck: `npm run typecheck`
+
+## Rules
+
+- British English in all prose. ESM-only; imports use `.js` extensions.
+- Commits: `type: description`. No `Co-Authored-By` lines.
+- Do not modify domain separators, tag bytes, the `sessionBinding` folding,
+  identity-point rejection, or the zero-scalar guard without crypto review —
+  see the "Crypto Safety" section of `CLAUDE.md`.
+- Bump `PRIVATE_EQUALITY_VERSION` (`src/types.ts`) together with
+  `package.json` and add a `CHANGELOG.md` entry for any release.
+- Anvil auto-releases on push to main — work on branches.

CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 0.1.0
+
+Initial public release.
+
+- Socialist Millionaires' Protocol (the OTR SMP variant) over Ristretto255 as a
+  pure four-message state machine — `initiate`/`respond` → `session.next(incoming)`
+  → a single boolean, identical on both sides.
+- Mandatory `sessionBinding` (the consumer's authenticated-channel transcript
+  hash) folded into every Fiat–Shamir challenge — relaying messages across two
+  separate channels aborts with `SmpError`.
+- Wire hardening: identity points are rejected on decode; the ~2^-252
+  zero-secret-scalar edge case is guarded.
+- 32 tests; 100% line coverage on `group`, `zkp`, and `smp`.

CLAUDE.md

@@ -0,0 +1,86 @@
+# CLAUDE.md — @forgesworn/private-equality
+
+AI agent instructions for working on this codebase.
+
+## Build & Test
+
+```bash
+npm run build      # tsc → dist/
+npm test           # vitest (single run)
+npm run coverage   # vitest with the per-file coverage gate
+npm run typecheck  # tsc --noEmit
+```
+
+Always run `npm test` after changes. Always run `npm run typecheck` before committing.
+
+## Architecture
+
+| File | Purpose |
+|------|---------|
+| `src/group.ts` | Isolates `@noble/curves` ristretto255 — the ONLY file importing it. Point/scalar codecs, `hashToScalar`, `randomScalar`. `Pt` is a structural interface (dodges TS4094 on @noble's anonymous class). |
+| `src/zkp.ts` | Three sigma proofs: PoK of a discrete log, representation (`P = g3^r`, `Q = g1^r · g2^y`), equality of two discrete logs. All Fiat–Shamir with domain separation + per-proof tag byte. |
+| `src/smp.ts` | The four-message OTR-SMP state machine + fixed-layout wire codec. `initiate`/`respond` entry points. |
+| `src/types.ts` | Public types: `Secret`, `SmpResult`, `SmpStep`, `SmpSession`, `SmpError`, `PRIVATE_EQUALITY_VERSION`. |
+| `src/index.ts` | Public API re-exports. |
+
+### Data flow
+
+Pure state machine — no transport. The consumer ferries opaque `Uint8Array`
+messages over an authenticated channel: `initiate(secret, binding)` →
+`{ session, first }`; each side calls `session.next(incoming)` until
+`{ done: true, result: { match } }`. Four messages total.
+
+## Crypto Safety — Do Not Change Without Expert Review
+
+- **Domain separators** (`private-equality/pok-v1`, `private-equality/repr-v1`,
+  `private-equality/eq-v1`, `private-equality/secret-v1`) are protocol
+  constants. Changing them breaks interoperability between versions.
+- **Per-proof tag bytes** separate the distinct proofs within a session. Do not
+  renumber or merge them — two proofs sharing a challenge domain enables proof
+  transplantation.
+- **`sessionBinding` is folded into every Fiat–Shamir challenge.** Never make it
+  optional and never drop it from a challenge — it is the MITM defence.
+- **Identity points are rejected on the wire** (decode-time). Do not relax this —
+  it closes the degenerate `QaQb = identity` case.
+- **The zero secret-scalar guard** in secret derivation is intentional. Do not
+  remove it.
+- **The wire codec is fixed-layout** (32-byte points and scalars, strict length
+  checks). Do not add variable-length fields without redesigning the codec.
+- **`PRIVATE_EQUALITY_VERSION` in `src/types.ts` is pinned by
+  `src/smoke.test.ts` as a literal string.** Anvil bumps `package.json` from
+  commit prefixes; the constant does not update itself. Any releasing change
+  (`feat:`/`fix:`) must update `src/types.ts` and `src/smoke.test.ts` to the
+  new version in the same PR.
+
+## Conventions
+
+- **British English** in all prose (colour, initialise, behaviour, licence).
+- **ESM-only** — all imports use `.js` extensions.
+- **Commit messages**: `type: description` (e.g. `feat: add subpath export`, `fix: reject oversized message`).
+- **No `Co-Authored-By`** lines in commits.
+- **Anvil auto-release on main** — every push to main runs `forgesworn/anvil@v0` and can auto-publish. Work on branches; merge to main only when a logical chunk is complete.
+
+## Release & Versioning
+
+**Automated via [forgesworn/anvil](https://github.com/forgesworn/anvil)** —
+`auto-release.yml` reads conventional commits on push to `main`, bumps the
+version, and creates a GitHub Release; `release.yml` then runs the pre-publish
+gates and publishes to npm via OIDC trusted publishing.
+
+| Type | Version Bump |
+|------|--------------|
+| `fix:` | Patch (0.1.x) |
+| `feat:` | Minor (0.x.0) |
+| `BREAKING CHANGE:` (in commit body) | Major (x.0.0) |
+| `chore:`, `docs:`, `refactor:`, `ci:` | None |
+
+Every release needs a matching `CHANGELOG.md` entry (anvil extracts the release
+body from it) and a synchronised `PRIVATE_EQUALITY_VERSION`.
+
+## Testing
+
+Tests live in `src/*.test.ts`. Vitest with a per-file coverage gate
+(`vitest.config.ts`). Coverage floor: `group`/`zkp` at 100%, `smp` at 100%
+lines / 87% branch. Tests cover the full protocol round-trip, mismatch
+non-leakage, binding mismatch aborts, malformed/replayed messages, and
+tampered proofs. PRs touching `zkp.ts` or `smp.ts` require crypto review.

CONTRIBUTING.md

@@ -0,0 +1,75 @@
+# Contributing
+
+## Setup
+
+```bash
+git clone https://github.com/forgesworn/private-equality.git
+cd private-equality
+npm install
+npm test
+```
+
+## Development Workflow
+
+```bash
+npm run build      # Compile TypeScript → dist/
+npm test           # Run test suite (vitest)
+npm run coverage   # Test suite with the per-file coverage gate
+npm run typecheck  # Type-check without emitting (tsc --noEmit)
+```
+
+Always run `npm run typecheck` and `npm test` before committing.
+
+## Branch Strategy
+
+This repository releases via [forgesworn/anvil](https://github.com/forgesworn/anvil)
+on `main` — pushes to `main` with a releasing commit type automatically publish
+a new npm version.
+
+- **Always work on a branch** (never commit directly to `main`).
+- Merge or squash to `main` only when a logical chunk of work is complete.
+- This produces one clean release instead of many incremental versions.
+
+## Commit Conventions
+
+Commit messages follow the `type: description` format. The type determines the
+version bump:
+
+| Type | Version bump | Example |
+|------|-------------|---------|
+| `feat:` | minor | `feat: add subpath export` |
+| `fix:` | patch | `fix: reject oversized message` |
+| `docs:` | none | `docs: clarify session binding derivation` |
+| `refactor:` | none | `refactor: extract challenge helper` |
+| `test:` | none | `test: add binding mismatch cases` |
+| `chore:` | none | `chore: update dev dependencies` |
+
+Use `BREAKING CHANGE:` in the commit body (or `feat!:` / `fix!:`) for major
+version bumps. Releases also need a `CHANGELOG.md` entry and a synchronised
+`PRIVATE_EQUALITY_VERSION` (see `CLAUDE.md`).
+
+## Crypto Review Policy
+
+**PRs that touch protocol logic require careful review.** This includes:
+
+- Anything in `src/zkp.ts`, `src/smp.ts`, or `src/group.ts`
+- Changes to domain separators, tag bytes, hashing, or scalar arithmetic
+- Changes to `sessionBinding` handling or wire-format validation
+
+If you are unsure whether a change affects cryptographic security, flag it for
+review. The domain separators (`private-equality/pok-v1`, `.../repr-v1`,
+`.../eq-v1`, `.../secret-v1`) are protocol constants — changing them breaks
+interoperability between versions.
+
+## Style
+
+- **British English** in all prose — colour, initialise, behaviour, licence.
+- **ESM-only** — all imports use `.js` extensions.
+- Keep test coverage high. Every new function or code path should have
+  corresponding tests.
+
+## Reporting Issues
+
+Open an issue on GitHub. If the issue involves a potential security
+vulnerability, use GitHub's private vulnerability reporting instead of a
+public issue — see `SECURITY.md`.