@peac/middleware-core 0.12.5 → 0.12.7

package/README.md

@@ -1,6 +1,6 @@
 # @peac/middleware-core
 
-Framework-agnostic middleware primitives for PEAC receipt issuance.
+Framework-agnostic middleware primitives for PEAC receipt issuance. Provides signing, transport selection, and rate limiting for any HTTP framework.
 
 ## Installation
 
@@ -8,72 +8,81 @@ Framework-agnostic middleware primitives for PEAC receipt issuance.
 pnpm add @peac/middleware-core
 ```
 
-## Quick Start
+## What It Does
+
+`@peac/middleware-core` is a framework-agnostic library for issuing signed PEAC receipts from HTTP servers. It handles receipt creation, transport selection (header, body, or pointer), configuration validation, and rate limiting. Framework-specific packages such as `@peac/middleware-express` build on these primitives.
+
+## How Do I Use It?
+
+### Create a receipt for a request/response pair
 
 ```typescript
 import { createReceipt, validateConfig } from '@peac/middleware-core';
+import type { MiddlewareConfig, RequestContext, ResponseContext } from '@peac/middleware-core';
 
-// Validate configuration at startup
-const config = {
+const config: MiddlewareConfig = {
   issuer: 'https://api.example.com',
   signingKey: privateJwk, // Ed25519 JWK
   keyId: 'prod-2026-02',
 };
 validateConfig(config);
 
-// In a request handler
 const result = await createReceipt(config, requestCtx, responseCtx);
 
-// Add PEAC-Receipt header to response
 for (const [key, value] of Object.entries(result.headers)) {
   res.setHeader(key, value);
 }
 ```
 
-## API
-
-### `createReceipt(config, request, response)`
-
-Create a signed PEAC receipt for a request/response pair. Returns a `ReceiptResult` with the JWS receipt, transport headers, and optional body wrapper.
-
-### `createReceiptWithClaims(config, claims)`
-
-Create a receipt from explicit claims (bypasses request/response context extraction).
-
-### `wrapResponse(data, receipt)`
+### Select transport and wrap responses
 
-Wrap a response body with a PEAC receipt for body transport profile. Returns `{ data, peac_receipt }`.
+```typescript
+import { selectTransport, wrapResponse, buildResponseHeaders } from '@peac/middleware-core';
+
+const transport = selectTransport(receiptJws, config);
+
+if (transport === 'body') {
+  const wrapped = wrapResponse(originalData, receiptJws);
+  res.json(wrapped); // { data, peac_receipt }
+} else {
+  const headers = buildResponseHeaders(receiptJws);
+  for (const [key, value] of Object.entries(headers)) {
+    res.setHeader(key, value);
+  }
+}
+```
 
-### `selectTransport(receipt, config)`
+### Use rate limiting
 
-Determine appropriate transport based on receipt size: `'header'`, `'body'`, or `'pointer'`. Auto-falls back from header to body if receipt exceeds `maxHeaderSize` (default 4096 bytes).
+```typescript
+import { MemoryRateLimitStore } from '@peac/middleware-core';
+import type { RateLimitStore } from '@peac/middleware-core';
 
-### `validateConfig(config)` / `validateConfigAsync(config)`
+const limiter = new MemoryRateLimitStore({
+  maxRequests: 100,
+  windowMs: 60_000,
+});
+```
 
-Validate middleware configuration at startup. Throws `ConfigError` if configuration is invalid.
+## Integrates With
 
-### `buildResponseHeaders(receipt)` / `buildReceiptResult(receipt, transport, body?)`
+- `@peac/kernel` (Layer 0): Types and constants
+- `@peac/schema` (Layer 1): Zod validators for receipt claims
+- `@peac/crypto` (Layer 2): Ed25519 signing
+- `@peac/middleware-express`: Express.js integration built on these primitives
 
-Lower-level utilities for constructing response headers and receipt results.
+## For Agent Developers
 
-## Configuration
+If you are building an AI agent or integration that needs to issue receipts:
 
-```typescript
-interface MiddlewareConfig {
-  issuer: string; // Issuer URL (becomes `iss` claim)
-  signingKey: Ed25519PrivateJwk; // Ed25519 private key (JWK format)
-  keyId: string; // Key ID for JWKS lookup
-  expiresIn?: number; // Receipt expiration in seconds (default: 300)
-  transport?: 'header' | 'body' | 'pointer'; // Transport profile (default: 'header')
-  maxHeaderSize?: number; // Max header size before fallback (default: 4096)
-  pointerUrlGenerator?: (receipt: string) => Promise<string>;
-  claimsGenerator?: (context: RequestContext) => Promise<Partial<ReceiptClaimsInput>>;
-}
-```
+- Use `@peac/middleware-express` for Express.js applications
+- Use `@peac/middleware-core` directly when integrating with other frameworks (Hono, Koa, Fastify)
+- Use `@peac/protocol` for lower-level receipt issuance without HTTP middleware
+- See the [llms.txt](https://github.com/peacprotocol/peac/blob/main/llms.txt) for a concise overview
 
-## Error Handling
+## For Operators
 
-Configuration errors throw `ConfigError` at startup. Receipt generation errors are returned in the result rather than thrown, so receipt failures never break the HTTP response.
+Call `validateConfig()` or `validateConfigAsync()` at application startup to catch configuration errors early. Receipt generation failures are returned in the result rather than thrown, so receipt failures never break HTTP responses. The `MemoryRateLimitStore` is in-process only; for distributed rate limiting, implement the `RateLimitStore` interface with a shared backend.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peac/middleware-core",
-  "version": "0.12.5",
+  "version": "0.12.7",
   "description": "Framework-agnostic middleware primitives for PEAC receipt issuance",
   "main": "dist/index.cjs",
   "types": "dist/index.d.ts",
@@ -15,10 +15,10 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/peacprotocol/peac.git",
+    "url": "git+https://github.com/peacprotocol/peac.git",
     "directory": "packages/middleware-core"
   },
-  "author": "jithinraj <7850727+jithinraj@users.noreply.github.com>",
+  "author": "PEAC Protocol Contributors",
   "license": "Apache-2.0",
   "bugs": {
     "url": "https://github.com/peacprotocol/peac/issues"
@@ -34,9 +34,9 @@
   },
   "dependencies": {
     "uuidv7": "^0.6.3",
-    "@peac/kernel": "0.12.5",
-    "@peac/schema": "0.12.5",
-    "@peac/crypto": "0.12.5"
+    "@peac/schema": "0.12.7",
+    "@peac/crypto": "0.12.7",
+    "@peac/kernel": "0.12.7"
   },
   "devDependencies": {
     "@types/node": "^22.19.11",
@@ -44,6 +44,18 @@
     "vitest": "^4.0.0",
     "tsup": "^8.0.0"
   },
+  "keywords": [
+    "peac",
+    "peacprotocol",
+    "interaction-records",
+    "signed-records",
+    "receipts",
+    "originary",
+    "middleware",
+    "receipt-issuance",
+    "http",
+    "server-side"
+  ],
   "scripts": {
     "prebuild": "rm -rf dist tsconfig.tsbuildinfo",
     "build": "pnpm run build:js && pnpm run build:types",