wardpass-edge 0.1.0

package/CONSENT.md

@@ -0,0 +1,18 @@
+# Trust Network consent (free hosted tier)
+
+The free WardPass control plane is a **blunt trade**: you get hosting; the bureau gets density.
+
+WardPass’s free hosted control-plane tier requires **Trust Network** membership.
+
+By joining, you agree that WardPass may:
+
+1. Use **aggregated or de-identified** fleet and payment-path signals from your operators/agents to power receiving-side **`POST /v1/screen`** decisions for merchants and facilitators.
+2. Share **aggregated or de-identified** payment-path and screen telemetry with **selected insurance, certification, or underwriting evaluation partners**, solely for risk-model diligence and partnership evaluation — not as a lead list of identifiable operators.
+
+At low participant counts, aggregated signals may still be attributable to specific operators.
+
+You can leave Trust Network at any time. Leaving **stops new contribution**; membership/audit timestamps may be retained. Leaving also ends eligibility for the **free** hosted tier (you may still use this OSS edge against your own DIY settle path without WardPass hosting). Extra agent seats are a later upsell; they are not part of the free TN-backed control plane.
+
+**Trust Network membership is not a trust seal.** `/v1/screen` allow still requires a known agent, valid passport where applicable, and **live** operator oversight. Confidence is never `high` in v0; `insufficient_data` is a first-class outcome, not a silent allow.
+
+This file is product copy for the signup wall. It is not a substitute for a formal DPA or terms of service once the company is incorporated.

package/LICENSE

@@ -0,0 +1,17 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+Copyright 2026 WardPass / splinterone
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,115 @@
+# wardpass-edge
+
+**WardPass** gives builders a hosted policy gateway for agent payments — **free** for one seat:
+
+- Operator account and **1 agent seat**
+- **Policy Passports** for scoped spend
+- **Reserve / settle** through *your* facilitator(s)
+- Oversight heartbeat (“I’m watching”) — a **dead-man’s switch** on new spend
+- **Clearance network**: when you are on the Trust Network *and* oversight is live, receivers can `POST /v1/screen` before irreversible settle
+
+This repo is the thin open-source **phone-home client**. Clone it, point `WARDPASS_URL` at the live staging gateway, and you are on the bureau.
+
+It is **not** a self-hosted gateway. It is **not** the AgentBound monorepo. The control plane, ledger, Trust Network, and `/v1/screen` bureau stay on **WardPass hosted**.
+
+## Why this exists
+
+Receivers take the irreversible-settle risk. Screening only works if enough operators are live, consented, and visible. This client is how you plug in in minutes — densifying the clearance bureau for everyone who screens before they settle.
+
+v0 is honest: `/v1/screen` never returns `confidence: high`. `insufficient_data` is first-class, not a silent allow.
+
+## Quick start
+
+### 1. Install
+
+```bash
+git clone https://github.com/splinterone/wardpass-edge.git
+cd wardpass-edge
+npm install
+npm run build
+```
+
+When published: `npm install wardpass-edge`.
+
+### 2. Configure
+
+```bash
+export WARDPASS_URL=https://wardpass-gateway-staging.fly.dev
+export WARDPASS_KEY=wpk_…                          # operator key (phone-home)
+export WARDPASS_RECEIVER_KEY=abrk_…                # receiver key for /v1/screen
+```
+
+That host is **staging** (`*.fly.dev`), not a production custom domain. `curl "$WARDPASS_URL/health"` should return `{"status":"ok","mode":"gateway"}`. Free tier = one seat; extra seats are a later upsell.
+
+### 3. Phone home (operators)
+
+Use your operator key against the hosted control plane. This package authenticates; it does not reimplement passports, reserve/settle, or the heartbeat.
+
+```js
+import { WardPassClient } from "wardpass-edge";
+
+const wp = new WardPassClient({
+  baseUrl: process.env.WARDPASS_URL || "https://wardpass-gateway-staging.fly.dev",
+  apiKey: process.env.WARDPASS_KEY,
+});
+// Ready: Policy Passports, reserve/settle, and oversight heartbeat
+// are hosted routes. Call them with this client’s credentials — don’t fork a gateway.
+```
+
+### 4. Screen before settle (receivers)
+
+```bash
+node examples/screen-before-settle.mjs
+```
+
+Or in your settle path:
+
+```js
+import { WardPassClient } from "wardpass-edge";
+
+const out = await WardPassClient.screenBeforeSettle({
+  baseUrl: process.env.WARDPASS_URL || "https://wardpass-gateway-staging.fly.dev",
+  receiverApiKey: process.env.WARDPASS_RECEIVER_KEY, // abrk_…
+  body: { agentId, amount, asset, payTo, network },
+});
+
+WardPassClient.assertScreenAllow(out); // throws on review | deny | insufficient_data
+// … then call your facilitator settle …
+```
+
+`allow` still requires a known agent, a valid passport where applicable, and **live** oversight. Trust Network membership is not a trust seal.
+
+## Free tier trade
+
+Free control plane ↔ **mandatory Trust Network** membership. That is the blunt deal: you get hosting; the bureau gets density.
+
+- Aggregated / de-identified signals feed receiving-side **`/v1/screen`**
+- The same class of telemetry may be shared with **selected insurance / certification / underwriting evaluation partners**
+- At low participant counts, aggregated signals may still be attributable to specific operators
+- Leave TN → stop new contribution **and** lose free hosted eligibility
+
+Full text: [CONSENT.md](./CONSENT.md).
+
+## Not a full gateway
+
+| This OSS repo | WardPass hosted (private product) |
+| --- | --- |
+| Thin TypeScript client + screen helper | Control plane, hash-chained ledger, Trust Network, `POST /v1/screen` bureau |
+| Apache-2.0 phone-home | Operator seats, Policy Passports, reserve/settle, oversight heartbeat |
+| Clone and run | **Not** the AgentBound monorepo — that stays private |
+
+You can point this client at your own DIY settle path without WardPass hosting. You just will not get the free control plane.
+
+## Names
+
+| Name | Role |
+| --- | --- |
+| **WardPass** | Company + public product (gateway for operators + `/screen` for receivers) |
+| **AgentBound** | Private engineering monorepo / interim codename |
+| **wardpass-edge** | This public OSS client |
+
+## Status
+
+Staging gateway is live at `https://wardpass-gateway-staging.fly.dev` (Fly.dev hostname, not a production custom domain). Point `WARDPASS_URL` at it. npm publish of this package is still pending — clone and `npm run build` until then.
+
+Apache-2.0. Product backend remains proprietary.

package/dist/index.d.ts

@@ -0,0 +1,47 @@
+/**
+ * wardpass-edge — thin phone-home client for WardPass hosted.
+ * Plug into the free control plane (passports, reserve/settle, oversight, /v1/screen).
+ * Does not implement the full gateway. Not a self-host of AgentBound.
+ */
+export type ScreenDecision = "allow" | "review" | "deny" | "insufficient_data";
+export type ScreenResult = {
+    decision: ScreenDecision;
+    confidence?: string;
+    score?: number;
+    screenId?: string;
+    factors?: Record<string, unknown>;
+    [key: string]: unknown;
+};
+export type WardPassClientOptions = {
+    /** Hosted API base, e.g. https://wardpass-gateway-staging.fly.dev (staging, not production) */
+    baseUrl: string;
+    /** Per-operator API key from free-tier signup (TN consent required). */
+    apiKey: string;
+    /** Optional operator id header. */
+    operatorId?: string;
+    fetch?: typeof fetch;
+};
+export declare class WardPassClient {
+    readonly baseUrl: string;
+    readonly apiKey: string;
+    readonly operatorId?: string;
+    private readonly fetchImpl;
+    constructor(opts: WardPassClientOptions);
+    private headers;
+    /**
+     * Receiver-side helper: call hosted POST /v1/screen before irreversible settle.
+     * Uses a **receiver** API key (abrk_…), not an operator key.
+     */
+    static screenBeforeSettle(opts: {
+        baseUrl: string;
+        receiverApiKey: string;
+        body: Record<string, unknown>;
+        fetch?: typeof fetch;
+    }): Promise<ScreenResult>;
+    /**
+     * Enforce screen decision: allow continues; everything else throws.
+     * insufficient_data is not a silent allow.
+     */
+    static assertScreenAllow(out: ScreenResult): void;
+}
+export declare const TRUST_NETWORK_CONSENT_SUMMARY = "Free WardPass hosting is a blunt trade: Trust Network membership. Aggregated/de-identified signals feed /v1/screen and may go to selected underwriting evaluation partners. At low participant counts, aggregated signals may still be attributable to specific operators. TN is not a trust seal.";

package/dist/index.js

@@ -0,0 +1,65 @@
+/**
+ * wardpass-edge — thin phone-home client for WardPass hosted.
+ * Plug into the free control plane (passports, reserve/settle, oversight, /v1/screen).
+ * Does not implement the full gateway. Not a self-host of AgentBound.
+ */
+export class WardPassClient {
+    baseUrl;
+    apiKey;
+    operatorId;
+    fetchImpl;
+    constructor(opts) {
+        if (!opts.baseUrl)
+            throw new Error("baseUrl required");
+        if (!opts.apiKey)
+            throw new Error("apiKey required — complete hosted signup + Trust Network consent first");
+        this.baseUrl = opts.baseUrl.replace(/\/$/, "");
+        this.apiKey = opts.apiKey;
+        this.operatorId = opts.operatorId;
+        this.fetchImpl = opts.fetch ?? fetch;
+    }
+    headers(extra) {
+        const h = {
+            authorization: `Bearer ${this.apiKey}`,
+            "content-type": "application/json",
+            ...extra,
+        };
+        if (this.operatorId)
+            h["x-operator-id"] = this.operatorId;
+        return h;
+    }
+    /**
+     * Receiver-side helper: call hosted POST /v1/screen before irreversible settle.
+     * Uses a **receiver** API key (abrk_…), not an operator key.
+     */
+    static async screenBeforeSettle(opts) {
+        const fetchImpl = opts.fetch ?? fetch;
+        const base = opts.baseUrl.replace(/\/$/, "");
+        const res = await fetchImpl(`${base}/v1/screen`, {
+            method: "POST",
+            headers: {
+                authorization: `Bearer ${opts.receiverApiKey}`,
+                "content-type": "application/json",
+            },
+            body: JSON.stringify(opts.body),
+        });
+        const out = (await res.json());
+        if (!res.ok)
+            throw new Error(out.error || `screen_http_${res.status}`);
+        return out;
+    }
+    /**
+     * Enforce screen decision: allow continues; everything else throws.
+     * insufficient_data is not a silent allow.
+     */
+    static assertScreenAllow(out) {
+        if (out.decision === "allow")
+            return;
+        if (out.decision === "review")
+            throw new Error("screen_review");
+        if (out.decision === "deny")
+            throw new Error("screen_deny");
+        throw new Error("screen_insufficient_data");
+    }
+}
+export const TRUST_NETWORK_CONSENT_SUMMARY = "Free WardPass hosting is a blunt trade: Trust Network membership. Aggregated/de-identified signals feed /v1/screen and may go to selected underwriting evaluation partners. At low participant counts, aggregated signals may still be attributable to specific operators. TN is not a trust seal.";

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "wardpass-edge",
+  "version": "0.1.0",
+  "description": "Thin OSS client for WardPass — plug into the free hosted policy gateway, Policy Passports, and pre-settle /v1/screen. Not a full gateway self-host.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CONSENT.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "node --test test/*.test.js",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/splinterone/wardpass-edge.git"
+  },
+  "keywords": [
+    "wardpass",
+    "x402",
+    "agent-payments",
+    "policy-passport",
+    "pre-settle",
+    "clearance",
+    "trust-network",
+    "screen"
+  ],
+  "devDependencies": {
+    "typescript": "^5.6.0"
+  }
+}