housekeeping (#20)

* housekeeping

* add encoding tests

* modernize encoding.ts

* improve exmample

* llm typo? wtf

* fix encoding

* upgrade checkout action version

* fix node ver to be >=25 to use native encoding

* fix dep versions

Author: ycmjason

.github/actions/run-pebble/action.yaml

@@ -1,4 +1,5 @@
 name: Run Pebble
+description: Run pabble......
 
 runs:
   using: "composite"

.github/workflows/ci.yaml

@@ -11,7 +11,7 @@ jobs:
     name: "Format & Lint & Type Check"
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v6
       - uses: denoland/setup-deno@v2
         with:
           deno-version: v2.x # Run with latest stable Deno.
@@ -22,7 +22,7 @@ jobs:
     name: "Unit Test (Deno)"
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v6
       - uses: denoland/setup-deno@v2
         with:
           deno-version: v2.x # Run with latest stable Deno.
@@ -31,11 +31,11 @@ jobs:
     name: "Unit Test (Node.js)"
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v6
       - uses: denoland/setup-deno@v2
         with:
           deno-version: v2.x # Run with latest stable Deno.
       - uses: actions/setup-node@v4
         with:
-          node-version: ">=20"
+          node-version: ">=25"
       - run: deno task build:npm:unit

.github/workflows/e2e.yaml

@@ -9,7 +9,7 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - uses: denoland/setup-deno@v2
         with:
           deno-version: v2.x # Run with latest stable Deno.

.github/workflows/integration.yaml

@@ -11,7 +11,7 @@ jobs:
     name: Deno
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - uses: denoland/setup-deno@v2
         with:
@@ -25,15 +25,15 @@ jobs:
     name: Node
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - uses: denoland/setup-deno@v2
         with:
           deno-version: v2.x # Run with latest stable Deno.
 
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v6
         with:
-          node-version: ">=20"
+          node-version: ">=25"
 
       - name: Run Pebble
         uses: ./.github/actions/run-pebble

.github/workflows/publish.yaml

@@ -13,7 +13,7 @@ jobs:
       id-token: write
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Publish package
         run: npx jsr publish
@@ -28,10 +28,10 @@ jobs:
       - uses: denoland/setup-deno@v2
         with:
           deno-version: v2.x # Run with latest stable Deno.
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v6
         with:
           registry-url: "https://registry.npmjs.org"
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - name: Build for NPM
         run: deno task build:npm
       - name: Publish to npm

.vscode/settings.json

@@ -2,6 +2,7 @@
   "prettier.enable": false,
   "deno.enable": true,
   "deno.lint": true,
+  "typescript.validate.enable": false,
   "editor.formatOnSave": true,
   "editor.defaultFormatter": "denoland.vscode-deno",
   "editor.codeActionsOnSave": {

AGENTS.md

@@ -0,0 +1,98 @@
+# AGENTS.md
+
+This file provides guidance to AI Agents when working with code in this
+repository.
+
+## Project Overview
+
+`@fishballpkg/acme` is a zero-dependency, minimalistic, opinionated ACME client
+written in TypeScript. It is designed to be platform-agnostic, running on Deno,
+Node.js, and other modern JavaScript environments that support `WebCrypto` and
+`fetch`.
+
+## Development Commands
+
+This project uses Deno for development.
+
+### Testing
+
+There are multiple tiers of tests in this repository:
+
+- **Unit Tests**: Run purely in-process, mocking external requests where
+  necessary.
+  - Command: `deno task test:unit`
+  - Location: `src/**/*.test.ts`
+
+- **Integration Tests**: Run against a local Pebble instance (Let's Encrypt's
+  ACME test server).
+  - **Prerequisites**: Docker must be running.
+  - **Start Pebble**: `deno task pebble:start` (starts Pebble and `challtestsrv`
+    via Docker Compose)
+  - **Run Integration Tests**: `deno task test:integration`
+  - **Stop Pebble**: `deno task pebble:stop`
+  - Location: `integration/`
+
+- **E2E Tests**:
+  - Command: `deno task test:e2e`
+  - Location: `e2e/`
+
+### Building
+
+The project is natively TypeScript/Deno but builds to NPM for Node.js
+compatibility using `dnt`.
+
+- **Build for NPM**: `deno task build:npm`
+  - This script (`scripts/build-npm.ts`) generates the `dist-npm` directory.
+
+### Linting & Formatting
+
+- **Lint**: Use `deno lint` standard command.
+- **Format**: Use `deno fmt` standard command.
+
+## High-Level Architecture
+
+The codebase follows the hierarchy of the ACME standard (RFC 8555).
+
+### Core Components (`src/`)
+
+- **Entry Point**: `src/mod.ts` exports the public API.
+- **AcmeClient** (`src/AcmeClient.ts`): The main entry point for users.
+  Initializes with a directory URL.
+  - **JWS Signing**: Handles JSON Web Signature (JWS) wrapping for requests
+    using `src/utils/jws.ts` and `src/utils/crypto.ts`.
+  - **Nonce Management**: detailed in `AcmeClient` private methods.
+- **AcmeAccount** (`src/AcmeAccount.ts`): Represents a registered account on the
+  ACME server.
+- **AcmeOrder** (`src/AcmeOrder.ts`): Represents a certificate order. Handles
+  polling for status steps.
+- **AcmeAuthorization** (`src/AcmeAuthorization.ts`): Represents validation for
+  a specific domain.
+- **AcmeChallenge** (`src/AcmeChallenge.ts`): Represents a specific challenge
+  method (e.g., `dns-01`).
+
+### Utilities
+
+- **`src/utils/`**: Internal helpers.
+  - `jws.ts`: JWS signing logic.
+  - `crypto.ts`: WebCrypto wrappers.
+  - `generateCSR.ts`: Logic to generate valid Certificate Signing Requests (CSR)
+    without external dependencies like OpenSSL.
+- **`src/ACME_DIRECTORY_URLS.ts`**: Constants for common ACME directories (Let's
+  Encrypt, etc.).
+
+### Workflows
+
+- **`src/AcmeWorkflows.ts`**: Contains high-level abstraction functions (e.g.,
+  `requestCertificate`) that bundle multiple steps (order creation, challenge
+  solving, polling, finalization) into single calls for convenience.
+
+## Design Principles
+
+1. **Zero Dependencies**: Do not introduce NPM dependencies or external CLIs
+   (like OpenSSL). Everything must be implemented using standard Web APIs
+   (`WebCrypto`, `fetch`) or built from scratch (like the CSR generator).
+2. **Platform Agnostic**: Code must write to Deno standards but be compatible
+   with Node.js via the build script. Avoid Deno-specific namespaces (`Deno.*`)
+   in the `src/` directory unless strictly necessary or valid polyfills exist.
+3. **Opinionated**: Focus on `DNS-01` challenge and `ECDSA P-256` keys. Support
+   for other methods is secondary.

deno.json

@@ -11,14 +11,22 @@
   },
   "tasks": {
     "test:e2e": "deno test --lock -A e2e",
-    "test:unit": "deno test --lock --allow-run=openssl src",
-    "test:integration": "deno test --lock --unsafely-ignore-certificate-errors=localhost --allow-net=\"localhost,127.0.0.1,8.8.8.8,[2001:4860:4860::8888]\" integration",
+    "test:unit": "deno test --lock -P=unit src",
+    "test:integration": "deno test --lock --unsafely-ignore-certificate-errors=localhost -P=integration integration",
     "pebble:start": "docker compose -f integration/docker-compose.yaml up",
     "pebble:stop": "docker compose -f integration/docker-compose.yaml down",
     "build:npm": "deno run --lock -A scripts/build-npm.ts",
     "build:npm:integration": "deno run --lock -A scripts/build-npm-integration.ts",
     "build:npm:unit": "deno run --lock -A scripts/build-npm-unit.ts"
   },
+  "permissions": {
+    "unit": {
+      "run": ["openssl"]
+    },
+    "integration": {
+      "net": ["localhost", "127.0.0.1", "8.8.8.8", "[2001:4860:4860::8888]"]
+    }
+  },
   "compilerOptions": {
     "strict": true,
     "noUncheckedIndexedAccess": true,
@@ -30,6 +38,5 @@
     "exclude": ["**/*.test.ts"]
   },
   "exclude": ["dist*"],
-  "imports": {},
   "license": "MIT"
 }