@atlasauth/pca-next 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,36 @@
-# Temporary Holding Version
+# @atlasauth/pca-next
 
-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.
+Next.js helper for Proof-Carrying Authority: wrap a Route Handler so the inbound PCActn is verified before your handler runs, with a 401/403 response otherwise.
+
+## Install
+
+```sh
+npm i @atlasauth/pca-next
+# peer dependency, install alongside:
+npm i next
+```
+
+`next` (v14 or v15) is an optional peer dependency.
+
+## Usage
+
+```ts
+// app/refunds/route.ts
+import { withPCA } from '@atlasauth/pca-next';
+
+export const POST = withPCA(
+  {
+    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
+  },
+  async (req, { pca }) => {
+    const { verdict, pcactn } = pca;   // handler only runs on a valid PCActn
+    return Response.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 wrapper verifies and is default-deny; 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,42 @@
+/**
+ * Next.js App-Router helper for Proof-Carrying Authority.
+ *
+ *   export const POST = withPCA(
+ *     { audience: 'ins_acme', resolveGrant, budgetStore, hooks, context },
+ *     async (req, { pca }) => { const { verdict, pcactn } = pca; return Response.json({ ok: true }); },
+ *   );
+ *
+ * It wraps a Route Handler so the inbound PCActn is verified with the framework-agnostic `requirePCA` guard
+ * from `@atlasauth/backend` (default-deny: a required check that is unenforced DENIES) before your handler
+ * runs. On success it calls your handler with `{ pca: { verdict, pcactn } }`; on failure it returns a 401/403
+ * JSON response 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.
+ *
+ * `next` is an OPTIONAL peer dependency and is never imported — the handler takes the web `Request` and returns
+ * a web `Response`, which is exactly what an App-Router Route Handler is.
+ */
+import { requirePCA, defaultExtract, memoryPcaStore } from '@atlasauth/backend';
+import type { PcaGuardResult, RequirePcaOptions, PcaStateStore } from '@atlasauth/backend';
+import type { PCActn } from '@atlasauth/pca';
+/** The verdict + PCActn handed to the wrapped handler on success. */
+export interface PcaAttachment {
+    verdict: Extract<PcaGuardResult, {
+        ok: true;
+    }>['verdict'];
+    pcactn: PCActn;
+}
+/** A Next.js App-Router Route Handler that receives the verified PCActn in its context. */
+export type PcaRouteHandler = (req: Request, ctx: {
+    pca: PcaAttachment;
+}) => Response | Promise<Response>;
+export interface PcaNextOptions extends RequirePcaOptions {
+    /** Override the 401/403 response (otherwise a JSON error + WWW-Authenticate is returned). */
+    onDeny?: (result: Extract<PcaGuardResult, {
+        ok: false;
+    }>, req: Request) => Response | Promise<Response>;
+}
+/** Wrap an App-Router Route Handler so it only runs for a valid PCActn. */
+export declare function withPCA(options: PcaNextOptions, handler: PcaRouteHandler): (req: Request) => Promise<Response>;
+export { requirePCA, defaultExtract, memoryPcaStore };
+export type { PcaGuardResult, RequirePcaOptions, PcaStateStore };

package/dist/index.js

@@ -0,0 +1,51 @@
+"use strict";
+/**
+ * Next.js App-Router helper for Proof-Carrying Authority.
+ *
+ *   export const POST = withPCA(
+ *     { audience: 'ins_acme', resolveGrant, budgetStore, hooks, context },
+ *     async (req, { pca }) => { const { verdict, pcactn } = pca; return Response.json({ ok: true }); },
+ *   );
+ *
+ * It wraps a Route Handler so the inbound PCActn is verified with the framework-agnostic `requirePCA` guard
+ * from `@atlasauth/backend` (default-deny: a required check that is unenforced DENIES) before your handler
+ * runs. On success it calls your handler with `{ pca: { verdict, pcactn } }`; on failure it returns a 401/403
+ * JSON response 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.
+ *
+ * `next` is an OPTIONAL peer dependency and is never imported — the handler takes the web `Request` and returns
+ * a web `Response`, which is exactly what an App-Router Route Handler is.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.memoryPcaStore = exports.defaultExtract = exports.requirePCA = void 0;
+exports.withPCA = withPCA;
+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; } });
+/** Wrap an App-Router Route Handler so it only runs for a valid PCActn. */
+function withPCA(options, handler) {
+    const onDeny = options.onDeny;
+    const guard = (0, backend_1.requirePCA)(options);
+    return async (req) => {
+        const like = {
+            headers: { get: (n) => req.headers.get(n) },
+            body: await req.clone().json().catch(() => undefined),
+        };
+        const result = await guard(like);
+        if (result.ok) {
+            return handler(req, { pca: { verdict: result.verdict, pcactn: result.pcactn } });
+        }
+        if (onDeny)
+            return onDeny(result, req);
+        return new Response(JSON.stringify({ error: result.verdict.reasons?.[0] ?? 'forbidden', verdict: result.verdict }), {
+            status: result.status,
+            headers: {
+                'content-type': 'application/json',
+                ...(result.wwwAuthenticate ? { 'WWW-Authenticate': result.wwwAuthenticate } : {}),
+            },
+        });
+    };
+}
+//# 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;;;;;;;;;;;;;;;;;GAiBG;;;AAqBH,0BAqBC;AAxCD,gDAAgF;AA0CvE,2FA1CA,oBAAU,OA0CA;AAAE,+FA1CA,wBAAc,OA0CA;AAAE,+FA1CA,wBAAc,OA0CA;AAxBnD,2EAA2E;AAC3E,SAAgB,OAAO,CAAC,OAAuB,EAAE,OAAwB;IACvE,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAC9B,MAAM,KAAK,GAAG,IAAA,oBAAU,EAAC,OAAO,CAAC,CAAC;IAClC,OAAO,KAAK,EAAE,GAAY,EAAqB,EAAE;QAC/C,MAAM,IAAI,GAAmB;YAC3B,OAAO,EAAE,EAAE,GAAG,EAAE,CAAC,CAAS,EAAE,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE;YACnD,IAAI,EAAE,MAAM,GAAG,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC;SACtD,CAAC;QACF,MAAM,MAAM,GAAmB,MAAM,KAAK,CAAC,IAAI,CAAC,CAAC;QACjD,IAAI,MAAM,CAAC,EAAE,EAAE,CAAC;YACd,OAAO,OAAO,CAAC,GAAG,EAAE,EAAE,GAAG,EAAE,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QACnF,CAAC;QACD,IAAI,MAAM;YAAE,OAAO,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QACvC,OAAO,IAAI,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,IAAI,WAAW,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC,EAAE;YAClH,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,OAAO,EAAE;gBACP,cAAc,EAAE,kBAAkB;gBAClC,GAAG,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC,CAAC,EAAE,kBAAkB,EAAE,MAAM,CAAC,eAAe,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAClF;SACF,CAAC,CAAC;IACL,CAAC,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@atlasauth/pca-next",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Next.js helper for Proof-Carrying Authority: wrap a Route Handler so the inbound PCActn is verified before your handler runs, with a 401/403 response otherwise.",
+  "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": {
+    "next": "^14 || ^15"
+  },
+  "peerDependenciesMeta": {
+    "next": {
+      "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"
+  }
 }