Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 14 additions & 1 deletion .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -4,17 +4,30 @@ on:
push:
branches: [main]
pull_request:
workflow_call:

permissions:
contents: read

jobs:
ci:
runs-on: ubuntu-latest
strategy:
matrix:
node: [24, 26.13.0]
steps:
- uses: actions/checkout@v7.0.1
- uses: actions/setup-node@v7.1.0
with:
node-version: 24
node-version: ${{ matrix.node }}
- run: npm ci
- run: npm run format:check
- run: npm run lint
- run: npm run typecheck
- run: npm test
- run: npm run build
- run: npm run build:lib
- run: npm run build:types
- run: npm pack --dry-run
- run: npm ci && npm run build
working-directory: demo
28 changes: 28 additions & 0 deletions .github/workflows/publish.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
name: Publish
on:
push:
tags: ["v*.*.*"]
permissions:
contents: read
concurrency:
group: publish-${{ github.ref }}
cancel-in-progress: false
jobs:
validate:
uses: ./.github/workflows/ci.yml
publish:
needs: validate
runs-on: ubuntu-latest
permissions:
contents: read
id-token: write
steps:
- uses: actions/checkout@v7.0.1
- uses: actions/setup-node@v7.1.0
with:
node-version: 26.13.0
registry-url: https://registry.npmjs.org
- run: npm ci
- name: Verify release tag
run: node --input-type=module -e 'import fs from "node:fs"; const p = JSON.parse(fs.readFileSync("package.json")); if (process.env.GITHUB_REF_NAME !== `v${p.version}`) throw new Error("Tag must match package version");'
- run: npm publish --access public --provenance
2 changes: 1 addition & 1 deletion .nvmrc
Original file line number Diff line number Diff line change
@@ -1 +1 @@
24
26.13.0
14 changes: 14 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
<!-- coderabbit-ai-generated:v1 -->

# Changelog

## 1.1.0

- Develop, build and release on Node.js 26.13.0 LTS; retain Node 24 support.
- Upgrade development dependencies and patch minimatch via an override. TypeScript stays on 5.9.3 to satisfy typescript-eslint's peer range.
- Update the npm allowScripts list to match installed lifecycle scripts.
- Validate JWT structure, challenge parameters, expiration claims and integer nonces; add scoped redeem-token verification.
- Require a configured secret outside development and bound production JSON request bodies.
- Make the widget form-associated, accessible, cancellable and resettable with automatic token expiry.
- Refresh website styling, install-command copying, keyboard focus, reduced motion and mobile presentation.
- Add tag-triggered npm trusted publishing after CI gates, with provenance and no long-lived npm token.
4 changes: 2 additions & 2 deletions Dockerfile
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
# from a single Node process (server.mjs). Everything is stateless — no
# database or volume is required.

FROM node:24-slim AS build
FROM node:26.13.0-slim AS build
WORKDIR /app

COPY package.json package-lock.json ./
Expand All @@ -18,7 +18,7 @@ COPY . .
# empties it), so the site output is set aside before building the library.
RUN npm run build && cp -r dist site && npm run build:lib

FROM node:24-slim AS runtime
FROM node:26.13.0-slim AS runtime
WORKDIR /app
ENV NODE_ENV=production
ENV PORT=3000
Expand Down
110 changes: 89 additions & 21 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,7 @@
<!-- coderabbit-ai-generated:v1 -->

<!-- coderabbit-ai-generated-section:v1:5f6554f918ee6e482c58ce6f9d4f4d695ce30e254cbe003fdebff0041917f719 -->

# rootcap

A privacy-first, self-hosted captcha alternative powered by proof-of-work.
Expand All @@ -18,9 +22,9 @@ no behavioural surveillance.

## Tech stack

- Node 24
- Node 26.13.0 LTS (also tested on Node 24)
- TypeScript
- Vite 6
- Vite 8
- SCSS (dart-sass)
- Web Workers + Web Crypto API
- HS256 signed JWTs (node:crypto)
Expand Down Expand Up @@ -160,7 +164,7 @@ docker run -d -p 3000:3000 -e ROOTCAP_SECRET=your-secret rootcap
# → open http://localhost:3000
```

Without Docker you can build and serve it on any Node.js 24 host:
Without Docker you can build and serve it on any Node.js 26.13.0 host:

```sh
npm ci
Expand All @@ -172,7 +176,7 @@ ROOTCAP_SECRET=your-secret npm start # serves site/ + API on :3000

## Publishing to npm

This project is structured as an npm package (v1.0.0). The `lib/` directory
This project is structured as an npm package (v1.1.0). The `lib/` directory
contains the core library and widget; `src/` contains the demo website.

### Build the package
Expand All @@ -184,29 +188,91 @@ npm run build:lib
This compiles the library to `dist/` using Vite library mode, producing ESM
bundles for both the core library and the widget.

### Publish to the npm registry
### Publish with a trusted publisher

Configure the rootcap package on npm → Settings → Trusted Publisher → GitHub Actions:

- Organization or user: `kirasync2748`
- Repository: `rootcap`
- Workflow filename: `publish.yml`
- Environment: leave blank (the workflow does not use an environment).

Keep “Require two-factor authentication and disallow bypass 2fa tokens” enabled.
No npm token secret is needed. See [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/).
This npm account setting must be saved by a package maintainer before the first release.

After merging the release changes into main, create and push the matching tag:

```sh
git tag v1.1.0
git push origin v1.1.0
```

The workflow tests Node 24 and 26.13.0, checks formatting, lint and types,
builds the website, library, declarations and demo, and checks the package.
Only after these checks pass does it verify the tag matches package.json
and publish with OIDC and provenance. A failed check prevents publishing.
The `prepack` hook also builds JavaScript and declarations for local tarballs.

### Security and compatibility

<!-- coderabbit-ai-generated:v1 -->

<!-- coderabbit-ai-generated-section:v1:f42c9c033df101d65fde06f236259e54b5d2cbc1eeaba23ffd4db4841313ef42 -->

Version 1.1.0 retains Node >=24 compatibility.

<!-- /coderabbit-ai-generated:v1 -->
<!-- coderabbit-ai-generated:v1 -->

1. **Log in to npm:**
<!-- coderabbit-ai-generated-section:v1:7faa61aba1cad3d315c8fa584e97f1581a7689474b66578dad0ed85f85fa0eef -->

```sh
npm login
```
<!-- coderabbit-ai-generated:v1 -->

Enter your npm username, password, email, and one-time password.
<!-- coderabbit-ai-generated-section:v1:d16a9ca8bac712d8a922024135824f1b85c168fed9c6a4ca5cc51c912f6238ea -->

2. **Bump the version** (if needed):
Development, Docker and publishing use Node 26.13.0. Challenge counts must be integers from 1–1000.

```sh
npm version 1.0.0
```
<!-- /coderabbit-ai-generated:v1 -->

3. **Build and publish:**
```sh
npm publish
```
The `prepublishOnly` script automatically runs `build:lib` and
`build:types` before publishing, producing the ESM bundles and the
TypeScript declaration files that ship in the package.
<!-- /coderabbit-ai-generated:v1 -->
<!-- coderabbit-ai-generated:v1 -->

<!-- coderabbit-ai-generated-section:v1:2c1838b346bb20c3b03de4cd0d28067f668e5861b69186c571c6e830384f80b9 -->

<!-- coderabbit-ai-generated:v1 -->

<!-- coderabbit-ai-generated-section:v1:8e450556df94384ac5835a4e8155438e06b17789ffedc6368329c9121cff45f0 -->

Difficulty must be an integer from 1–16, and lifetimes must be positive safe integers.

<!-- /coderabbit-ai-generated:v1 -->

Challenges with higher difficulties are rejected, including previously issued
challenges. Generation throws RangeError if the encoded token exceeds 16,384
characters. Invalid options throw RangeError; malformed signed claims fail verification.

<!-- /coderabbit-ai-generated:v1 -->

Production API handlers require ROOTCAP_SECRET (at least 16 characters).
<!-- coderabbit-ai-generated:v1 -->

<!-- coderabbit-ai-generated-section:v1:3bb2a551e2ed53568e7305e69094893c4d8ac11145be2569f4776993fa0e8d50 -->

The development fallback key is used when `NODE_ENV` is `development` and
`ROOTCAP_SECRET` is missing or shorter than 16 characters. Do not set
`NODE_ENV=development` in production.

<!-- /coderabbit-ai-generated:v1 -->

Use `verifyToken(secret, token, { scope: "signup" })` to bind redemption to
an operation. Tokens remain stateless and reusable until expiry: applications
requiring one-time redemption must track consumed tokens server-side. Proof of
work raises the cost of automation; it does not establish a user's identity.
Add application-level rate limits appropriate to your deployment.

The widget participates in native FormData, exposes `reset()`, resets on form
reset and token expiry, and emits `rootcap:verified` and `rootcap:reset` events.
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved

### What gets published

Expand All @@ -218,3 +284,5 @@ Users can import from two entry points:
| --------------------------------------------- | --------------------- |
| `import { generateChallenge } from "rootcap"` | Core library |
| `import "rootcap/widget"` | Widget custom element |

<!-- /coderabbit-ai-generated:v1 -->
16 changes: 14 additions & 2 deletions api/challenge.ts
Original file line number Diff line number Diff line change
@@ -1,7 +1,19 @@
import type { IncomingMessage, ServerResponse } from "node:http";
import { handleChallenge } from "../lib/api/handlers.js";

export default async function handler(_req: IncomingMessage, res: ServerResponse) {
export default async function handler(req: IncomingMessage, res: ServerResponse) {
res.setHeader("Content-Type", "application/json");
res.end(JSON.stringify(handleChallenge("demo")));
res.setHeader("Cache-Control", "no-store");
if (req.method !== "GET" && req.method !== "HEAD") {
res.statusCode = 405;
res.setHeader("Allow", "GET, HEAD");
res.end(JSON.stringify({ error: "method_not_allowed" }));
return;
}
try {
res.end(JSON.stringify(handleChallenge("demo")));
} catch {
res.statusCode = 503;
res.end(JSON.stringify({ error: "service_unavailable" }));
}
}
9 changes: 8 additions & 1 deletion api/stats.ts
Original file line number Diff line number Diff line change
@@ -1,7 +1,14 @@
import type { IncomingMessage, ServerResponse } from "node:http";
import { getStats } from "../lib/core/stats.js";

export default async function handler(_req: IncomingMessage, res: ServerResponse) {
export default async function handler(req: IncomingMessage, res: ServerResponse) {
res.setHeader("Content-Type", "application/json");
res.setHeader("Cache-Control", "no-store");
if (req.method !== "GET" && req.method !== "HEAD") {
res.statusCode = 405;
res.setHeader("Allow", "GET, HEAD");
res.end(JSON.stringify({ error: "method_not_allowed" }));
return;
}
res.end(JSON.stringify(getStats()));
}
38 changes: 22 additions & 16 deletions api/verify.ts
Original file line number Diff line number Diff line change
@@ -1,22 +1,28 @@
import type { IncomingMessage, ServerResponse } from "node:http";
import { handleVerify } from "../lib/api/handlers.js";
import { readJson } from "../lib/api/http.js";

export default async function handler(req: IncomingMessage, res: ServerResponse) {
const body = await readJson(req);
res.setHeader("Content-Type", "application/json");
res.end(JSON.stringify(handleVerify(body, "demo")));
}

function readJson(req: IncomingMessage): Promise<unknown> {
return new Promise((resolve) => {
let data = "";
req.on("data", (chunk) => (data += chunk));
req.on("end", () => {
try {
resolve(data ? JSON.parse(data) : {});
} catch {
resolve({});
}
});
});
res.setHeader("Cache-Control", "no-store");
if (req.method !== "POST") {
res.statusCode = 405;
res.setHeader("Allow", "POST");
res.end(JSON.stringify({ error: "method_not_allowed" }));
return;
}
let body: unknown;
try {
body = await readJson(req);
} catch {
res.statusCode = 400;
res.end(JSON.stringify({ success: false, reason: "invalid_body" }));
return;
}
try {
res.end(JSON.stringify(handleVerify(body, "demo")));
} catch {
res.statusCode = 503;
res.end(JSON.stringify({ error: "service_unavailable" }));
}
}
9 changes: 8 additions & 1 deletion demo/README.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,7 @@
<!-- coderabbit-ai-generated:v1 -->

<!-- coderabbit-ai-generated-section:v1:2816bbe9dd48cb93260f6fd213551107704b159ae8386bb9ff594d22f5bcfc3f -->

# rootcap demo

A minimal project showing how to integrate rootcap into your app.
Expand All @@ -8,6 +12,7 @@ Build the rootcap library first (from the repo root):

```sh
npm run build:lib
npm run build:types
```

This compiles `lib/` to `dist/` so the `file:..` dependency resolves.
Expand All @@ -16,7 +21,7 @@ This compiles `lib/` to `dist/` so the `file:..` dependency resolves.

```sh
cd demo
npm install
npm ci
npm run dev # http://localhost:3001
```

Expand Down Expand Up @@ -95,3 +100,5 @@ app.post("/signup", (req, res) => {
<button type="submit">Sign up</button>
</form>
```

<!-- /coderabbit-ai-generated:v1 -->
Loading
Loading