@atlasauth/pca-express 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,36 @@
-# Temporary Holding Version
+# @atlasauth/pca-express
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Express middleware for Proof-Carrying Authority: requirePCA() verifies the inbound PCActn and attaches the verdict, or answers 401/403 with a WWW-Authenticate challenge.
+
+## Install
+
+```sh
+npm i @atlasauth/pca-express
+# peer dependency, install alongside:
+npm i express
+```
+
+`express` (v4 or v5) is an optional peer dependency.
+
+## Usage
+
+```ts
+import { pcaExpress } from '@atlasauth/pca-express';
+
+app.post(
+  '/refunds',
+  pcaExpress({
+    audience: 'ins_acme',   // this resource server's / instance id the PCActn must name
+    resolveGrant,           // (ref) => Capability — look up the root grant
+    budgetStore,            // per-holder replay/budget store
+  }),
+  (req, res) => {
+    const { verdict, pcactn } = req.pca!;  // attached on success
+    res.json({ ok: true });
+  },
+);
+```
+
+The client sends the PCActn as `PCA-Action: <base64url>` (see `@atlasauth/pca` `pcaHeaders`) or a JSON body `{ pcactn }` — the default extractor reads both. The middleware verifies and is default-deny (an unenforced required check denies); it is the verifier that decides, not the client's proof.
+
+Part of Proof-Carrying Authority — see `@atlasauth/pca`.

package/dist/index.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Express middleware for Proof-Carrying Authority.
+ *
+ *   app.post('/refunds',
+ *     pcaExpress({ audience: 'ins_acme', resolveGrant, budgetStore, hooks, context }),
+ *     (req, res) => { const { verdict, pcactn } = req.pca!; ... });
+ *
+ * It verifies the inbound PCActn with the framework-agnostic `requirePCA` guard from `@atlasauth/backend`
+ * (default-deny: a required check that is unenforced DENIES) and, on success, attaches the verdict +
+ * PCActn to `req[attachAs]` (default `req.pca`). On failure it answers 401/403 with a WWW-Authenticate
+ * challenge. The client sends the PCActn as `PCA-Action: <base64url>` (see `@atlasauth/pca` `pcaHeaders`)
+ * or a JSON body `{ pcactn }`; that is exactly what the default extractor reads, so no wiring is needed.
+ *
+ * `express` is an OPTIONAL peer dependency and is never imported — the request/response/next shapes are
+ * structural, so this stays compatible across Express 4 and 5.
+ */
+import { requirePCA, defaultExtract, memoryPcaStore } from '@atlasauth/backend';
+import type { PcaGuardResult, RequirePcaOptions, PcaStateStore } from '@atlasauth/backend';
+import type { PCActn } from '@atlasauth/pca';
+/** Structural shim of an Express request (only `headers`/`body` are read; the rest passes through). */
+export interface ExpressRequestLike {
+    headers: Record<string, string | string[] | undefined>;
+    body?: unknown;
+    [k: string]: unknown;
+}
+/** Structural shim of an Express response (the chainable subset the middleware uses). */
+export interface ExpressResponseLike {
+    status(code: number): ExpressResponseLike;
+    set(field: string, value: string): ExpressResponseLike;
+    json(body: unknown): unknown;
+}
+export type ExpressNextLike = (err?: unknown) => void;
+/** The verdict + PCActn attached to the request on success. */
+export interface PcaAttachment {
+    verdict: Extract<PcaGuardResult, {
+        ok: true;
+    }>['verdict'];
+    pcactn: PCActn;
+}
+export interface PcaExpressOptions extends RequirePcaOptions {
+    /** Property on `req` to attach `{ verdict, pcactn }` to (default `pca`). */
+    attachAs?: string;
+    /** Override the 401/403 response (otherwise a JSON error + WWW-Authenticate is sent). */
+    onDeny?: (result: Extract<PcaGuardResult, {
+        ok: false;
+    }>, req: ExpressRequestLike, res: ExpressResponseLike) => void;
+}
+/** Build an Express middleware that requires a valid PCActn on the request. */
+export declare function pcaExpress(options: PcaExpressOptions): (req: ExpressRequestLike, res: ExpressResponseLike, next: ExpressNextLike) => Promise<void>;
+export { requirePCA, defaultExtract, memoryPcaStore };
+export type { PcaGuardResult, RequirePcaOptions, PcaStateStore };

package/dist/index.js

@@ -0,0 +1,54 @@
+"use strict";
+/**
+ * Express middleware for Proof-Carrying Authority.
+ *
+ *   app.post('/refunds',
+ *     pcaExpress({ audience: 'ins_acme', resolveGrant, budgetStore, hooks, context }),
+ *     (req, res) => { const { verdict, pcactn } = req.pca!; ... });
+ *
+ * It verifies the inbound PCActn with the framework-agnostic `requirePCA` guard from `@atlasauth/backend`
+ * (default-deny: a required check that is unenforced DENIES) and, on success, attaches the verdict +
+ * PCActn to `req[attachAs]` (default `req.pca`). On failure it answers 401/403 with a WWW-Authenticate
+ * challenge. The client sends the PCActn as `PCA-Action: <base64url>` (see `@atlasauth/pca` `pcaHeaders`)
+ * or a JSON body `{ pcactn }`; that is exactly what the default extractor reads, so no wiring is needed.
+ *
+ * `express` is an OPTIONAL peer dependency and is never imported — the request/response/next shapes are
+ * structural, so this stays compatible across Express 4 and 5.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.memoryPcaStore = exports.defaultExtract = exports.requirePCA = void 0;
+exports.pcaExpress = pcaExpress;
+const backend_1 = require("@atlasauth/backend");
+Object.defineProperty(exports, "requirePCA", { enumerable: true, get: function () { return backend_1.requirePCA; } });
+Object.defineProperty(exports, "defaultExtract", { enumerable: true, get: function () { return backend_1.defaultExtract; } });
+Object.defineProperty(exports, "memoryPcaStore", { enumerable: true, get: function () { return backend_1.memoryPcaStore; } });
+/** Build an Express middleware that requires a valid PCActn on the request. */
+function pcaExpress(options) {
+    const attachAs = options.attachAs ?? 'pca';
+    const onDeny = options.onDeny;
+    const guard = (0, backend_1.requirePCA)(options);
+    return async (req, res, next) => {
+        let result;
+        try {
+            result = await guard({ headers: req.headers, body: req.body });
+        }
+        catch (e) {
+            next(e);
+            return;
+        }
+        if (result.ok) {
+            req[attachAs] = { verdict: result.verdict, pcactn: result.pcactn };
+            next();
+            return;
+        }
+        if (onDeny) {
+            onDeny(result, req, res);
+            return;
+        }
+        res.status(result.status);
+        if (result.wwwAuthenticate)
+            res.set('WWW-Authenticate', result.wwwAuthenticate);
+        res.json({ error: result.verdict.reasons?.[0] ?? 'forbidden', verdict: result.verdict });
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;GAeG;;;AAoCH,gCAyBC;AA3DD,gDAAgF;AA6DvE,2FA7DA,oBAAU,OA6DA;AAAE,+FA7DA,wBAAc,OA6DA;AAAE,+FA7DA,wBAAc,OA6DA;AA5BnD,+EAA+E;AAC/E,SAAgB,UAAU,CAAC,OAA0B;IACnD,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,KAAK,CAAC;IAC3C,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAC9B,MAAM,KAAK,GAAG,IAAA,oBAAU,EAAC,OAAO,CAAC,CAAC;IAClC,OAAO,KAAK,EAAE,GAAuB,EAAE,GAAwB,EAAE,IAAqB,EAAiB,EAAE;QACvG,IAAI,MAAsB,CAAC;QAC3B,IAAI,CAAC;YACH,MAAM,GAAG,MAAM,KAAK,CAAC,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAoB,CAAC,CAAC;QACnF,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,IAAI,CAAC,CAAC,CAAC,CAAC;YACR,OAAO;QACT,CAAC;QACD,IAAI,MAAM,CAAC,EAAE,EAAE,CAAC;YACb,GAA+B,CAAC,QAAQ,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC;YAChG,IAAI,EAAE,CAAC;YACP,OAAO;QACT,CAAC;QACD,IAAI,MAAM,EAAE,CAAC;YACX,MAAM,CAAC,MAAM,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;YACzB,OAAO;QACT,CAAC;QACD,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QAC1B,IAAI,MAAM,CAAC,eAAe;YAAE,GAAG,CAAC,GAAG,CAAC,kBAAkB,EAAE,MAAM,CAAC,eAAe,CAAC,CAAC;QAChF,GAAG,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,IAAI,WAAW,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC;IAC3F,CAAC,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@atlasauth/pca-express",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Express middleware for Proof-Carrying Authority: requirePCA() verifies the inbound PCActn and attaches the verdict, or answers 401/403 with a WWW-Authenticate challenge.",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@atlasauth/pca": "0.1.0",
+    "@atlasauth/backend": "0.3.0"
+  },
+  "peerDependencies": {
+    "express": "^4 || ^5"
+  },
+  "peerDependenciesMeta": {
+    "express": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.4"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
 }