@atlasauth/pca-dpop 0.1.0 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Atlas Authorization
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,59 @@
+# @atlasauth/pca-dpop
+
+Sender-constrained proof-of-possession for Proof-Carrying Authority. It ties a PCActn to the holder key (or TLS channel) that is allowed to use it, and interoperates with OAuth proof-of-possession:
+
+- RFC 9449 DPoP: a holder-key-signed `dpop+jwt` proof over the HTTP method and target URI.
+- RFC 8705 mutual TLS: the `x5t#S256` certificate-thumbprint confirmation.
+
+A PCActn's bound holder key is the last capability in its chain (`cap_chain[last].holder`, an Ed25519 public key). That key is exactly an OKP/Ed25519 JWK, so a DPoP proof signed by it has a `jkt` thumbprint equal to the PCActn's binding.
+
+## Install
+
+```sh
+npm i @atlasauth/pca-dpop
+```
+
+Depends on `@atlasauth/pca` and `jose`.
+
+## Usage
+
+```ts
+import { createDpopProof, assertPcaDpop, leafHolderJwk } from '@atlasauth/pca-dpop';
+
+// Client: sign a DPoP proof with the same key that holds the PCActn's leaf capability.
+const proof = await createDpopProof({
+  method: 'POST',
+  url: 'https://api.example.com/refunds',
+  privateKey: holderPrivateJwk,          // { kty: 'OKP', crv: 'Ed25519', x, d }
+  publicJwk: leafHolderJwk(pcactn),
+});
+
+// Resource server: confirm the proof is held by the PCActn's bound key and is for this request.
+const seenJti = new Set<string>();       // use a shared store with expiry in production
+const result = await assertPcaDpop(pcactn, proof, {
+  method: 'POST',
+  url: 'https://api.example.com/refunds', // query and fragment are ignored
+  maxAgeSec: 300,                         // default 300
+  seenJti,                                // rejects a repeated jti
+});
+result.jkt;                               // verified key thumbprint
+```
+
+`assertPcaDpop` throws a `DpopVerificationError` (with a `code` such as `typ`, `signature`, `htm`, `htu`, `iat_stale`, `jkt`, `jti_replay`) on any mismatch.
+
+## API
+
+- `createDpopProof`, `verifyDpopProof` (generic RFC 9449 proofs, with optional `expectedJkt`, `seenJti`, `nonce` and `ath`)
+- `bindPcaToDpop(pcactn)` returns `{ jkt }`, the `cnf` binding for the PCActn's holder key
+- `assertPcaDpop(pcactn, proof, opts)` verifies a proof against that binding
+- `leafHolderJwk`, `jwkThumbprint`, `normalizeHtu`, `athFor`
+- `mtlsCnf(certDerOrPem)` returns `{ 'x5t#S256': ... }`
+- `DPOP_ALLOWED_ALGS`: asymmetric algorithms only (`none` and MACs are rejected)
+
+## Status
+
+Experimental. This package checks the proof only; it does not issue DPoP nonces, and replay protection is whatever `seenJti` store you supply. It does not verify the TLS client certificate itself, only computes its thumbprint for comparison. The cryptography is unaudited.
+
+## License
+
+MIT - see LICENSE

package/package.json

@@ -1,7 +1,28 @@
 {
   "name": "@atlasauth/pca-dpop",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Sender-constrained proof-of-possession for PCA: RFC 9449 DPoP proofs and RFC 8705 mTLS cnf binding, tying a PCActn to the holder key/channel for OAuth PoP interop.",
+  "keywords": [
+    "dpop",
+    "rfc 9449",
+    "mtls",
+    "rfc 8705",
+    "proof of possession",
+    "agent authorization",
+    "proof-carrying authority",
+    "pca",
+    "ai agents"
+  ],
+  "license": "MIT",
+  "homepage": "https://github.com/Atlas-Authorization/pca#readme",
+  "bugs": {
+    "url": "https://github.com/Atlas-Authorization/pca/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Atlas-Authorization/pca.git",
+    "directory": "packages/pca-dpop"
+  },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
@@ -13,7 +34,7 @@
   },
   "dependencies": {
     "jose": "^5.9.6",
-    "@atlasauth/pca": "0.1.0"
+    "@atlasauth/pca": "0.2.0"
   },
   "devDependencies": {
     "typescript": "^5.6.3",
@@ -21,8 +42,12 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "LICENSE"
   ],
+  "engines": {
+    "node": ">=20"
+  },
   "publishConfig": {
     "access": "public"
   },