@atlasauth/pca-fetch 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,37 @@
-# Temporary Holding Version
+# @atlasauth/pca-fetch
 
-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.
+Runtime-neutral Web **Fetch** guard for Proof-Carrying Authority — verify an inbound PCActn in any
+`Request → Response` runtime: Cloudflare Workers, Deno, Bun, Vercel Edge, Netlify, a Lambda Function
+URL. Web platform only, no Node APIs.
+
+## Install
+
+```sh
+npm i @atlasauth/pca-fetch
+```
+
+## Usage
+
+```ts
+import { withPCA } from '@atlasauth/pca-fetch';
+
+export default {
+  fetch: withPCA(
+    {
+      audience: 'ins_acme',
+      resolveGrant: async (grantRef) => grants.get(grantRef),   // your grant store
+      context: async () => ({ params: { amount: 20, currency: 'usd' }, budget: { B: 500, tau: 0 }, planAuthorized: true }),
+    },
+    async (req, { pca }) => Response.json({ ok: true, verdict: pca.verdict }),
+  ),
+};
+```
+
+On success your handler runs with `{ pca: { verdict, pcactn } }`; otherwise a `401/403` `Response`
+with a `WWW-Authenticate` challenge is returned. `createPcaFetchGuard(opts)` returns the raw guard
+result if you want to compose it into your own router. The client sends the PCActn as
+`PCA-Action: <base64url>` or a JSON body `{ pcactn }`.
+
+Nothing here authorizes on its own — the resource server's verifier (default-deny) decides.
+
+Part of Proof-Carrying Authority — see [`@atlasauth/pca`](../pca).

package/dist/index.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Runtime-neutral Web Fetch guard for Proof-Carrying Authority.
+ *
+ * Works in any `Request → Response` runtime — Cloudflare Workers, Deno, Bun, Vercel Edge, Netlify, a
+ * Lambda Function URL — using only the web platform (no Node APIs), so the same code protects a
+ * resource server wherever it runs on the internet:
+ *
+ *   export default { fetch: withPCA({ audience, resolveGrant, context }, async (req, { pca }) => {
+ *     return Response.json({ ok: true, verdict: pca.verdict });
+ *   }) };
+ *
+ * It verifies the inbound PCActn with the framework-agnostic `requirePCA` guard from
+ * `@atlasauth/backend` (default-deny) and, on success, calls your handler with the verdict + PCActn;
+ * otherwise it returns a 401/403 `Response` with a WWW-Authenticate challenge. The client sends the
+ * PCActn as `PCA-Action: <base64url>` (see `@atlasauth/pca` `pcaHeaders`) or a JSON body `{ pcactn }`.
+ * Nothing here authorizes on its own — the resource server's verifier decides.
+ */
+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 a guarded handler on success. */
+export interface PcaContextValue {
+    verdict: Extract<PcaGuardResult, {
+        ok: true;
+    }>['verdict'];
+    pcactn: PCActn;
+}
+export interface PcaFetchOptions extends RequirePcaOptions {
+    /** Shape the 401/403 body (default: `{ error, verdict }`). */
+    denyBody?: (result: Extract<PcaGuardResult, {
+        ok: false;
+    }>) => unknown;
+}
+/**
+ * Build a verifier over a web `Request`. Returns the full guard result so you can compose it yourself
+ * (e.g. inside an existing router). Use `withPCA` for the common wrap-a-handler case.
+ */
+export declare function createPcaFetchGuard(options: PcaFetchOptions): (req: Request) => Promise<PcaGuardResult>;
+export type PcaFetchHandler = (req: Request, ctx: {
+    pca: PcaContextValue;
+}) => Response | Promise<Response>;
+/** Wrap a Fetch handler so the inbound PCActn is verified first; on success your handler runs with the verdict. */
+export declare function withPCA(options: PcaFetchOptions, handler: PcaFetchHandler): (req: Request) => Promise<Response>;
+export { requirePCA, defaultExtract, memoryPcaStore };
+export type { PcaGuardResult, RequirePcaOptions, PcaStateStore };

package/dist/index.js

@@ -0,0 +1,64 @@
+"use strict";
+/**
+ * Runtime-neutral Web Fetch guard for Proof-Carrying Authority.
+ *
+ * Works in any `Request → Response` runtime — Cloudflare Workers, Deno, Bun, Vercel Edge, Netlify, a
+ * Lambda Function URL — using only the web platform (no Node APIs), so the same code protects a
+ * resource server wherever it runs on the internet:
+ *
+ *   export default { fetch: withPCA({ audience, resolveGrant, context }, async (req, { pca }) => {
+ *     return Response.json({ ok: true, verdict: pca.verdict });
+ *   }) };
+ *
+ * It verifies the inbound PCActn with the framework-agnostic `requirePCA` guard from
+ * `@atlasauth/backend` (default-deny) and, on success, calls your handler with the verdict + PCActn;
+ * otherwise it returns a 401/403 `Response` with a WWW-Authenticate challenge. The client sends the
+ * PCActn as `PCA-Action: <base64url>` (see `@atlasauth/pca` `pcaHeaders`) or a JSON body `{ pcactn }`.
+ * Nothing here authorizes on its own — the resource server's verifier decides.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.memoryPcaStore = exports.defaultExtract = exports.requirePCA = void 0;
+exports.createPcaFetchGuard = createPcaFetchGuard;
+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; } });
+/** Adapt a web `Request` to the framework-agnostic `PcaRequestLike` (headers getter + parsed JSON body). */
+async function toPcaRequest(req) {
+    let body;
+    try {
+        // clone so the handler can still read the body; ignore non-JSON bodies.
+        body = await req.clone().json();
+    }
+    catch {
+        body = undefined;
+    }
+    return { headers: { get: (name) => req.headers.get(name) }, body };
+}
+function denyResponse(result, denyBody) {
+    const body = denyBody ? denyBody(result) : { error: result.verdict.reasons?.[0] ?? 'forbidden', verdict: result.verdict };
+    const headers = { 'content-type': 'application/json' };
+    if (result.wwwAuthenticate)
+        headers['WWW-Authenticate'] = result.wwwAuthenticate;
+    return new Response(JSON.stringify(body), { status: result.status, headers });
+}
+/**
+ * Build a verifier over a web `Request`. Returns the full guard result so you can compose it yourself
+ * (e.g. inside an existing router). Use `withPCA` for the common wrap-a-handler case.
+ */
+function createPcaFetchGuard(options) {
+    const guard = (0, backend_1.requirePCA)(options);
+    return async (req) => guard(await toPcaRequest(req));
+}
+/** Wrap a Fetch handler so the inbound PCActn is verified first; on success your handler runs with the verdict. */
+function withPCA(options, handler) {
+    const guard = createPcaFetchGuard(options);
+    return async (req) => {
+        const result = await guard(req);
+        if (result.ok)
+            return handler(req, { pca: { verdict: result.verdict, pcactn: result.pcactn } });
+        return denyResponse(result, options.denyBody);
+    };
+}
+//# 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;;;;;;;;;;;;;;;;GAgBG;;;AAwCH,kDAGC;AAKD,0BAOC;AArDD,gDAAgF;AAuDvE,2FAvDA,oBAAU,OAuDA;AAAE,+FAvDA,wBAAc,OAuDA;AAAE,+FAvDA,wBAAc,OAuDA;AAxCnD,4GAA4G;AAC5G,KAAK,UAAU,YAAY,CAAC,GAAY;IACtC,IAAI,IAAa,CAAC;IAClB,IAAI,CAAC;QACH,wEAAwE;QACxE,IAAI,GAAG,MAAM,GAAG,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,CAAC;IAClC,CAAC;IAAC,MAAM,CAAC;QACP,IAAI,GAAG,SAAS,CAAC;IACnB,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,EAAE,GAAG,EAAE,CAAC,IAAY,EAAE,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,EAAE,CAAC;AAC7E,CAAC;AAED,SAAS,YAAY,CAAC,MAA8C,EAAE,QAAsC;IAC1G,MAAM,IAAI,GAAG,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,IAAI,WAAW,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC;IAC1H,MAAM,OAAO,GAA2B,EAAE,cAAc,EAAE,kBAAkB,EAAE,CAAC;IAC/E,IAAI,MAAM,CAAC,eAAe;QAAE,OAAO,CAAC,kBAAkB,CAAC,GAAG,MAAM,CAAC,eAAe,CAAC;IACjF,OAAO,IAAI,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC;AAChF,CAAC;AAED;;;GAGG;AACH,SAAgB,mBAAmB,CAAC,OAAwB;IAC1D,MAAM,KAAK,GAAG,IAAA,oBAAU,EAAC,OAAO,CAAC,CAAC;IAClC,OAAO,KAAK,EAAE,GAAY,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC;AAChE,CAAC;AAID,mHAAmH;AACnH,SAAgB,OAAO,CAAC,OAAwB,EAAE,OAAwB;IACxE,MAAM,KAAK,GAAG,mBAAmB,CAAC,OAAO,CAAC,CAAC;IAC3C,OAAO,KAAK,EAAE,GAAY,EAAqB,EAAE;QAC/C,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,CAAC;QAChC,IAAI,MAAM,CAAC,EAAE;YAAE,OAAO,OAAO,CAAC,GAAG,EAAE,EAAE,GAAG,EAAE,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QAChG,OAAO,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;IAChD,CAAC,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "@atlasauth/pca-fetch",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Runtime-neutral Web Fetch guard for Proof-Carrying Authority: verify an inbound PCActn in any Request→Response runtime (Cloudflare Workers, Deno, Bun, Vercel Edge, Lambda).",
+  "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"
+  },
+  "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"
+  }
 }