@profullstack/x402-gateway 0.5.0 → 0.7.0

package/README.md

@@ -99,9 +99,19 @@ export const GET = robotsRoute(gateway, { disallow: ['/login', '/api/'] });
 | `denyCidrs` | `[]` | IPv4 ranges answered with a tiny `403` before anything else. For a VPS fleet that spoofs a browser: hosting ranges serve no readers. |
 | `chargeSpoofedBrowsers` | `false` | charge a request that claims `Chrome/…` but sends no `Sec-Fetch-Mode`. Every Chromium since 76, headless included, sends it on every request and no script or extension can remove it, so its absence means an HTTP client with a copied string. Firefox and Safari are not judged. |
 | `exempt` | | `(request) => boolean`, never charged: e.g. a request carrying your signed-in cookie |
+| `powerKeys` | Profullstack's | Power Keys honoured as a pass, kid to public key. `false` switches it off. See below. |
+| `revokedKeys` | | Power Key subjects no longer honoured |
 
 Without `coinpay.apiKey` and `payTo` the gateway still answers training crawlers with 402 and the page says payments are off. Nothing is sold, but nothing is given away either.
 
+## One key for every site
+
+A day pass opens one site for a day. A [Power Key](https://profullstack.com/shop) is bought once and opens every Profullstack property for good: no crawler paywall, no allowance, no per-site pass. It is an Ed25519-signed token from [`@profullstack/keys`](https://www.npmjs.com/package/@profullstack/keys), and the gateway verifies it offline with the public key that package ships, so a site honours it with no configuration and no call to anyone.
+
+A client sends it as `Authorization: Bearer pfs_...`, in `x-power-key`, or as `x-api-key`. `passFrom` reads it and `verifyPass` verifies it, so a throttle built on the gateway skips it the same way it skips a day pass. The 402 body carries `powerKey: { shop, header }` and the sales page says where to buy one.
+
+Running the gateway somewhere that is not a Profullstack property? Pass `powerKeys: false`, or your own `{ kid: publicKey }` map to sell keys of your own with `mintKey` from the same package.
+
 ## A free allowance that sells instead of refusing
 
 Named crawlers are one problem. The other is an ordinary client hammering the

package/index.d.ts

@@ -34,6 +34,8 @@ export interface PageContext {
   training: string[];
   retrieval: string[];
   contact: string;
+  /** Where a Power Key is bought and the header it goes in, or null when they are switched off. */
+  powerKey?: { shop: string; header: string } | null;
 }
 
 export interface GatewayOptions {
@@ -82,6 +84,15 @@ export interface GatewayOptions {
   freeQuota?: number | FreeQuotaOptions;
   /** What a pass unlocks, listed on the sales page and in the 402 body. */
   benefits?: string[];
+  /**
+   * Power Keys honoured as a pass: kid -> base64url Ed25519 public key, as
+   * @profullstack/keys ships them. Defaults to Profullstack's keys, so a key
+   * bought at profullstack.com/shop opens this site with no configuration.
+   * `false` switches it off.
+   */
+  powerKeys?: Record<string, string> | false;
+  /** Power Key subjects no longer honoured (refunded, leaked). */
+  revokedKeys?: Iterable<string>;
   fetch?: typeof fetch;
 }
 
@@ -176,10 +187,14 @@ export interface Gateway {
   };
   robotsTxt: (extra?: RobotsOptions) => string;
   page: () => string;
-  /** The pass this request presents, from the gateway's header or a bearer token. */
+  /** The pass this request presents: a day pass from the gateway's header or a bearer token, or a Power Key. */
   passFrom: (request: Request) => string | null;
-  /** Whether that token is a live pass this gateway minted. */
+  /** Whether that token opens the site: a live day pass this gateway minted, or a valid, unrevoked Power Key. */
   verifyPass: (token: string | null) => Promise<boolean>;
+  /** The x402 offer this gateway would make, without answering a request. */
+  offer: (days?: number) => Offer;
+  /** The full 402 body around that offer: the offer plus the pass terms. */
+  receipt: (days?: number, extra?: Record<string, unknown>) => Offer & Record<string, unknown>;
 }
 
 export function createGateway(options: GatewayOptions): Gateway;

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@profullstack/x402-gateway",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "type": "module",
-  "description": "Sell crawl access to AI training crawlers by the day over x402, settled by CoinPay. One middleware: 402 with an offer, a sales page with CLI instructions, signed passes, and a robots.txt that keeps search crawlers welcome.",
+  "description": "Sell crawl access to AI training crawlers by the day over x402, settled by CoinPay. One middleware: 402 with an offer, a sales page with CLI instructions, signed passes, Profullstack Power Keys honoured as a pass, and a robots.txt that keeps search crawlers welcome.",
   "keywords": [
     "x402",
+    "power-key",
     "402",
     "payment-required",
     "crawler",
@@ -69,5 +70,8 @@
   "sideEffects": false,
   "scripts": {
     "test": "node --test"
+  },
+  "dependencies": {
+    "@profullstack/keys": "^0.1.0"
   }
 }

package/src/index.js

@@ -1,3 +1,4 @@
+import { HEADER as POWER_KEY_HEADER, isPowerKey, keyFrom, PROFULLSTACK_KEYS, SHOP_URL, verifyKey } from '@profullstack/keys';
 import { isTrainingAgent, RETRIEVAL_AGENTS, TRAINING_AGENTS } from './agents.js';
 import { clientIp, compileCidrs, inCidrs, isSpoofedBrowser } from './edge.js';
 import { memoryQuotaStore, meters, normaliseQuota, quotaHeaders, spend } from './quota.js';
@@ -22,6 +23,7 @@ export { mintPass, readPass } from './pass.js';
 export { robotsTxt } from './robots.js';
 export { buildOffer, decodePayment, expectedFor, METHODS, verifyAndSettle } from './x402.js';
 export { memoryQuotaStore, normaliseQuota, quotaHeaders, spend } from './quota.js';
+export { isPowerKey, keyFrom, PROFULLSTACK_KEYS, verifyKey } from '@profullstack/keys';
 
 /**
  * A gateway that sells crawl access to training crawlers, by the day, over x402.
@@ -56,6 +58,8 @@ export { memoryQuotaStore, normaliseQuota, quotaHeaders, spend } from './quota.j
  * @param {boolean} [options.chargeSpoofedBrowsers=false]  charge a "Chrome/…" request that lacks the Sec-Fetch-Mode header every Chromium sends
  * @param {(request: Request) => boolean} [options.exempt]  requests never charged, e.g. ones carrying a signed-in cookie
  * @param {string} [options.secret]                pass signing secret; defaults to the CoinPay key
+ * @param {Record<string,string>|false} [options.powerKeys]  kid -> public key of the Power Keys honoured as a pass; defaults to Profullstack's, `false` switches it off
+ * @param {Iterable<string>} [options.revokedKeys]  Power Key subjects no longer honoured
  * @param {(ctx: object) => string} [options.page] custom sales page renderer
  * @param {string} [options.contact]               mailto: or URL for bulk deals
  * @param {(sale: object) => void|Promise<void>} [options.onSale]   accounting hook; awaited before the receipt goes out, and its errors are swallowed
@@ -109,6 +113,13 @@ export function createGateway(options = {}) {
       buy: days > 1 ? `${buyUrl}?days=${days}` : buyUrl,
       buyDays: `${buyUrl}?days=<n>`,
     },
+    /*
+     * The other way in. A Power Key from the shop opens this site and every
+     * other Profullstack property for good, so the 402 says so: a client that
+     * has one but sent it in the wrong place, or that would rather buy once
+     * than pay by the day, learns here where and how.
+     */
+    ...(o.powerKeys ? { powerKey: { shop: SHOP_URL, header: POWER_KEY_HEADER, bearer: true } } : {}),
     ...extra,
   });
 
@@ -152,14 +163,35 @@ export function createGateway(options = {}) {
     training: o.training,
     retrieval: o.retrieval,
     contact: o.contact,
+    powerKey: o.powerKeys ? { shop: SHOP_URL, header: POWER_KEY_HEADER } : null,
   });
 
-  /** The pass a request presents, from the named header or a bearer token. */
+  /**
+   * The pass a request presents: a day pass from the named header or a bearer
+   * token, or a Power Key wherever @profullstack/keys reads one.
+   */
   const passFrom = (request) => {
     const direct = request.headers.get(o.header);
     if (direct) return direct.trim();
     const m = /^Bearer\s+(cp_[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+)$/i.exec(request.headers.get('authorization') ?? '');
-    return m ? m[1] : null;
+    if (m) return m[1];
+    return o.powerKeys ? keyFrom(request) : null;
+  };
+
+  /**
+   * Whether a token opens the site: a live day pass this gateway minted, or a
+   * Power Key signed by a key in `powerKeys` and not revoked. A Power Key is
+   * bought once at the shop and honoured everywhere, which is the point of it:
+   * the site never asks anyone whether it is good, it checks the signature.
+   */
+  const honours = async (token) => {
+    if (!token) return false;
+    if (isPowerKey(token)) {
+      if (!o.powerKeys) return false;
+      const result = await verifyKey(token, { publicKeys: o.powerKeys, revoked: o.revokedKeys });
+      return result.ok;
+    }
+    return Boolean(await readPass(token, { secret }));
   };
 
   /**
@@ -342,8 +374,7 @@ export function createGateway(options = {}) {
      * were the only reason to refuse and is not now that a quota exists.
      */
     const token = passFrom(request);
-    const paid = Boolean(token && (await readPass(token, { secret })));
-    if (paid) return null;
+    if (await honours(token)) return null;
 
     const pays =
       o.isPaidAgent(request.headers.get('user-agent') ?? '') ||
@@ -387,7 +418,21 @@ export function createGateway(options = {}) {
      * paying crawlers twice.
      */
     passFrom,
-    verifyPass: async (token) => Boolean(token && (await readPass(token, { secret }))),
+    verifyPass: honours,
+    /**
+     * The x402 offer this gateway would make, and the full receipt body around
+     * it, without answering a request.
+     *
+     * A site with its own refusal -- a tiered limiter whose 429 body says which
+     * rung the caller is on and what the next one costs -- wants to keep that
+     * body and add a machine-readable offer to it, so an x402 client can pay
+     * on the spot instead of being told in prose to go and fetch /crawl. The
+     * alternative is every such site rebuilding payTo, price, currency and
+     * network from its own copy of the config, which is how two of them end up
+     * quoting different numbers.
+     */
+    offer,
+    receipt,
     /** robots.txt with this gateway's lists and sales path. */
     robotsTxt: (extra = {}) =>
       robotsTxt({ siteUrl: o.siteUrl, path: o.path, training: o.training, retrieval: o.retrieval, ...extra }),
@@ -466,6 +511,8 @@ function normalise(options) {
     onSale: options.onSale ?? null,
     freeQuota: normaliseQuota(options.freeQuota),
     benefits: Array.isArray(options.benefits) ? options.benefits : null,
+    powerKeys: options.powerKeys === false ? null : (options.powerKeys ?? PROFULLSTACK_KEYS),
+    revokedKeys: options.revokedKeys ?? null,
     fetch: options.fetch ?? globalThis.fetch,
   };
 }

package/src/page.js

@@ -60,6 +60,7 @@ export function renderPage(ctx) {
     maxDays = 30,
     quota = null,
     benefits = null,
+    powerKey = null,
   } = ctx;
 
   /*
@@ -95,6 +96,10 @@ export function renderPage(ctx) {
     benefits && benefits.length
       ? `<h2>What a pass gets you</h2>\n<ul>\n${benefits.map((b) => `  <li>${esc(b)}</li>`).join('\n')}\n</ul>`
       : '';
+  const powerKeyNote = powerKey
+    ? `<h2>Or buy one key for every Profullstack site</h2>
+<p>A <a href="${esc(powerKey.shop)}">Power Key</a> is bought once and opens this site and every other Profullstack property, with no day passes and no limits. Send it as <code>Authorization: Bearer pfs_...</code> or in <code>${esc(powerKey.header)}</code> and this page never answers 402 again.</p>`
+    : '';
   const window =
     minutes === 1440
       ? 'one day'
@@ -134,6 +139,7 @@ ${
 }
 
 ${unlocks}
+${powerKeyNote}
 ${arithmetic}
 
 <h2>How it works</h2>