@atlasauth/pca-ciba 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

@@ -1,46 +1,64 @@
 # @atlasauth/pca-ciba
 
-A CIBA (OpenID Connect Client-Initiated Backchannel Authentication) on-ramp for PCA's FROST step-up: turn a risk-gated step-up into a standard async human-approval flow, interrupting a person only for the actions that actually need it.
+A CIBA (OpenID Connect Client-Initiated Backchannel Authentication) on-ramp for Proof-Carrying Authority (PCA) step-up. It turns a risk-gated step-up into a standard asynchronous human-approval flow, interrupting a person only for the actions that actually need it.
 
-CIBA is the convergent human-in-the-loop primitive every modern IdP ships (Auth0, Descope, Stytch): a backend opens an `auth_req_id`, the human is notified out of band, and the decision comes back by POLL or PING/PUSH. Its `binding_message` carries the human-readable approval context — so the thing approved on the phone is provably the thing the agent is about to do (OpenID CIBA Core).
+In CIBA a backend opens an `auth_req_id`, the human is notified out of band, and the decision comes back by poll or ping/push. The `binding_message` carries the human-readable approval context, so the thing approved on the phone is the thing the agent is about to do ("Approve stripe.refund $480 on charge:ch_1 - because you asked support-bot to 'reconcile October refunds'").
 
-This is a **bridge, not a replacement**. PCA's cryptographic step-up (FROST threshold cosign, in `@atlasauth/pca`) stays the enforcement; CIBA is the human-notification / decision envelope around it. A bare OP yes/no is a trusted single party — a FROST cosign is an unforgeable t-of-n signature — so PCA's step-up is cryptographically stronger; this just gives it the industry-standard async-approval + binding-message on-ramp.
+This is a bridge, not a replacement. PCA's cryptographic step-up (a FROST threshold cosign, in `@atlasauth/pca`) stays the enforcement; CIBA is the notification and decision envelope around it.
 
-**Risk-adaptive gating** is the point: if every action prompts, humans blanket-approve (Anthropic observed 93% blanket-approval under always-prompt). Only a tier-3 step-up (human-required, typically irreversible) is routed through CIBA; tier-2 (guardian auto-cosign) and tier-1 (`auto`) never interrupt a person.
+Gating is risk-adaptive: only a tier-3 step-up (human required, typically irreversible) is routed through CIBA. Tier-2 (guardian auto-cosign) and tier-1 (`auto`) never interrupt a person.
 
 ## Install
 
 ```sh
-npm i @atlasauth/pca-ciba
+npm i @atlasauth/pca-ciba @atlasauth/pca
 ```
 
-Depends on the core `@atlasauth/pca` (installed transitively).
-
 ## Usage
 
 ```ts
-import { reviewAction } from '@atlasauth/pca';
+import { agent, generateKeyPair, reviewAction } from '@atlasauth/pca';
 import { requiresCiba, createCibaBroker, cibaDecisionToCosign } from '@atlasauth/pca-ciba';
 
-const review = reviewAction(agent, 'stripe.refund', 'charge:ch_1', { amount: 480 }, { goal: 'reconcile October refunds' });
+const a = agent({
+  principal: generateKeyPair(),
+  goal: 'reconcile October refunds',
+  permissions: { stripe: ['payout'] },
+  limits: { payout: '$100' },
+  aud: 'rs_demo',
+  riskPolicy: { theta1: 0.3, theta2: 0.6 },
+});
+
+const review = reviewAction(a, 'stripe.payout', 'acct:1', { amount: 80 }, { goal: 'reconcile October refunds' });
 
-if (requiresCiba(review) && review.kind === 'step_up') {
-  const broker = createCibaBroker({ onComplete: (s) => notify(s) }); // PING/PUSH; omit for POLL
+if (review.kind === 'step_up' && requiresCiba(review)) {
+  const broker = createCibaBroker({ onComplete: (session) => console.log(session.status) }); // omit onComplete for POLL
   const ciba = broker.start(review.request, { actsFor: 'support-bot', loginHint: 'owner@acme' });
-  // ciba.binding_message:
-  //   "Approve stripe.refund $480 on charge:ch_1 — because you asked support-bot to 'reconcile October refunds'"
+  // ciba.auth_req_id, ciba.binding_message, ciba.requested_expiry, ...
+
+  broker.poll(ciba.auth_req_id).status; // 'pending' | 'approved' | 'denied' | 'expired'
 
-  // POLL: broker.poll(ciba.auth_req_id).status → 'pending' | 'approved' | 'denied' | 'expired'
-  // The human acts out of band:
+  // The human decides out of band:
   const session = broker.resolve(ciba.auth_req_id, 'approve', 'owner@acme');
 
-  // Fold the decision back into the trust budget (the real cryptographic cosign is FROST, separate):
-  const { budget } = cibaDecisionToCosign(session.status === 'approved' ? 'approve' : 'deny', agent.budget, agent.policy.riskPolicy, Date.now());
+  // Fold the decision back into the trust budget:
+  const { budget, cosigned } = cibaDecisionToCosign(
+    session.status === 'approved' ? 'approve' : 'deny',
+    a.budget,
+    a.policy.riskPolicy,
+    Date.now(),
+  );
 }
 ```
 
-`toCibaAuthRequest(stepUp, opts?)` is the pure mapping (step-up → CIBA request) if you want to drive your own broker or a real OP.
+`toCibaAuthRequest(stepUp, opts?)` is the pure mapping from a step-up to a CIBA request, if you want to drive your own broker or a real OpenID provider.
+
+## Status
+
+The broker is in-memory and models the CIBA lifecycle without any network; a production deployment would swap in a real OpenID provider. The package computes approval envelopes and the derived trust budget and authorises nothing on its own: `cibaDecisionToCosign` is only the budget-level effect. The cryptographic cosign (FROST) is produced and verified separately, and the resource server's verifier remains the authority. Cryptography in PCA is unaudited.
+
+Source and issues: https://github.com/Atlas-Authorization/pca
 
-This computes approval envelopes and the derived trust budget; it authorises nothing on its own. The resource server's verifier and the FROST cosigners remain the authority at run time.
+## License
 
-Part of Proof-Carrying Authority — see `@atlasauth/pca`.
+MIT - see LICENSE

package/package.json

@@ -1,7 +1,27 @@
 {
   "name": "@atlasauth/pca-ciba",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "CIBA (Client-Initiated Backchannel Authentication) bridge for PCA FROST step-up: turn a step-up request into a backchannel human-approval flow with risk-adaptive gating.",
+  "keywords": [
+    "ciba",
+    "backchannel",
+    "human approval",
+    "step-up",
+    "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-ciba"
+  },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
@@ -12,7 +32,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@atlasauth/pca": "0.1.0"
+    "@atlasauth/pca": "0.2.0"
   },
   "devDependencies": {
     "typescript": "^5.6.3",
@@ -20,8 +40,12 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "LICENSE"
   ],
+  "engines": {
+    "node": ">=20"
+  },
   "publishConfig": {
     "access": "public"
   },