@nodana/phoenixd-mpp-sdk 0.0.0-stage → 0.1.1

package/dist/server/index.js

@@ -0,0 +1,376 @@
+import {
+  bodyHash,
+  invoiceDetails,
+  paymentHash,
+  satoshis
+} from "../chunk-7BE7G2UI.js";
+import {
+  ChargeError,
+  __export,
+  charge
+} from "../chunk-EQRLZHAJ.js";
+
+// src/server/index.ts
+import { Mppx } from "mppx/server";
+
+// src/server/methods.ts
+var methods_exports = {};
+__export(methods_exports, {
+  charge: () => charge2
+});
+
+// src/server/charge.ts
+import { Challenge, Method, Receipt } from "mppx";
+import { Transport } from "mppx/server";
+
+// src/server/store.ts
+var validId = (id) => typeof id === "string" && /^[A-Za-z0-9_-]{1,128}$/.test(id);
+function assertRecord(value) {
+  if (typeof value !== "object" || value === null)
+    throw new TypeError("Invalid stored challenge");
+  const record = value;
+  if (!validId(record.id) || !/^[0-9a-f]{64}$/.test(record.paymentHash) || !/^[0-9a-f]{64}$/.test(record.bodyHash) || !Number.isSafeInteger(record.amountSat) || record.amountSat < 1 || !Number.isSafeInteger(record.expiresAt) || typeof record.serializedChallenge !== "string" || typeof record.requestUrl !== "string" || typeof record.requestMethod !== "string") {
+    throw new TypeError("Invalid stored challenge");
+  }
+}
+function memoryStore(options = {}) {
+  const maxEntries = options.maxEntries ?? 1e4;
+  if (!Number.isSafeInteger(maxEntries) || maxEntries < 1)
+    throw new TypeError("maxEntries must be positive");
+  const entries = /* @__PURE__ */ new Map();
+  const hashes = /* @__PURE__ */ new Set();
+  const prune = () => {
+    let removed = 0;
+    for (const [id, entry] of entries)
+      if (entry.charge.expiresAt <= Date.now()) {
+        entries.delete(id);
+        hashes.delete(entry.charge.paymentHash);
+        removed++;
+      }
+    return removed;
+  };
+  return {
+    async issue(charge3) {
+      assertRecord(charge3);
+      if (charge3.expiresAt <= Date.now()) throw new Error("Charge has expired");
+      prune();
+      if (entries.size >= maxEntries)
+        throw new Error("Charge store capacity reached");
+      if (entries.has(charge3.id) || hashes.has(charge3.paymentHash))
+        throw new Error("Charge already issued");
+      entries.set(charge3.id, {
+        charge: structuredClone(charge3),
+        consumed: false
+      });
+      hashes.add(charge3.paymentHash);
+    },
+    async get(id) {
+      return entries.has(id) ? structuredClone(entries.get(id).charge) : void 0;
+    },
+    async consume(id) {
+      const entry = entries.get(id);
+      if (!entry || entry.consumed || entry.charge.expiresAt <= Date.now())
+        return false;
+      entry.consumed = true;
+      return true;
+    },
+    async pruneExpired() {
+      return prune();
+    }
+  };
+}
+var issueScript = `
+local time = redis.call('TIME')
+local now = tonumber(time[1]) * 1000 + math.floor(tonumber(time[2]) / 1000)
+local expires = tonumber(ARGV[2])
+if expires <= now then return -1 end
+if redis.call('EXISTS', KEYS[1]) == 1 or redis.call('EXISTS', KEYS[2]) == 1 then return 0 end
+redis.call('HSET', KEYS[1], 'record', ARGV[1], 'expires', ARGV[2], 'consumed', '0')
+redis.call('PEXPIREAT', KEYS[1], ARGV[2])
+redis.call('SET', KEYS[2], ARGV[3])
+redis.call('PEXPIREAT', KEYS[2], ARGV[2])
+return 1
+`;
+var consumeScript = `
+if redis.call('EXISTS', KEYS[1]) == 0 then return 0 end
+local expires = tonumber(redis.call('HGET', KEYS[1], 'expires'))
+local consumed = redis.call('HGET', KEYS[1], 'consumed')
+if not expires or (consumed ~= '0' and consumed ~= '1') then
+  return redis.error_reply('Invalid stored payment challenge')
+end
+local time = redis.call('TIME')
+local now = tonumber(time[1]) * 1000 + math.floor(tonumber(time[2]) / 1000)
+if expires <= now or consumed == '1' then return 0 end
+redis.call('HSET', KEYS[1], 'consumed', '1')
+return 1
+`;
+function redisStore(client, options = {}) {
+  const prefix = options.keyPrefix ?? "phoenixd-mpp";
+  if (!/^[A-Za-z0-9:_-]{1,128}$/.test(prefix))
+    throw new TypeError("Invalid Redis keyPrefix");
+  const root = `{${prefix}}:`;
+  const key = (id) => `${root}challenge:${id}`;
+  return {
+    async issue(charge3) {
+      assertRecord(charge3);
+      const result = await client.sendCommand([
+        "EVAL",
+        issueScript,
+        "2",
+        key(charge3.id),
+        `${root}hash:${charge3.paymentHash}`,
+        JSON.stringify(charge3),
+        String(charge3.expiresAt),
+        charge3.id
+      ]);
+      if (result === -1) throw new Error("Charge has expired");
+      if (result === 0) throw new Error("Charge already issued");
+      if (result !== 1) throw new Error("Unexpected Redis issuance response");
+    },
+    async get(id) {
+      if (!validId(id)) return void 0;
+      const value = await client.sendCommand(["HGET", key(id), "record"]);
+      if (value === null) return void 0;
+      if (typeof value !== "string")
+        throw new TypeError("Invalid Redis record response");
+      const record = JSON.parse(value);
+      assertRecord(record);
+      if (record.id !== id)
+        throw new TypeError("Stored challenge ID does not match");
+      return record;
+    },
+    async consume(id) {
+      if (!validId(id)) return false;
+      const result = await client.sendCommand([
+        "EVAL",
+        consumeScript,
+        "1",
+        key(id)
+      ]);
+      if (result !== 0 && result !== 1)
+        throw new Error("Unexpected Redis consumption response");
+      return result === 1;
+    }
+  };
+}
+
+// src/server/charge.ts
+var defaults = { currency: "sat", methodDetails: { invoice: "" } };
+function charge2(options) {
+  const {
+    client,
+    store = memoryStore(),
+    network,
+    invoiceExpirySeconds = 3600
+  } = options;
+  if (!Number.isSafeInteger(invoiceExpirySeconds) || invoiceExpirySeconds < 1)
+    throw new TypeError("invoiceExpirySeconds must be a positive integer");
+  const byInput = /* @__PURE__ */ new WeakMap();
+  const byCaptured = /* @__PURE__ */ new WeakMap();
+  const http = Transport.http();
+  const transport = {
+    ...http,
+    async respondChallenge(parameters) {
+      const context = byInput.get(parameters.input);
+      if (!context)
+        throw new ChargeError(
+          "invalid_challenge",
+          "An HTTP payment handler is required"
+        );
+      const original = parameters.challenge;
+      const request = charge.schema.request.parse(original.request);
+      const amountSat = satoshis(request.amount);
+      let details;
+      let serialized;
+      try {
+        const invoice = await client.createInvoice({
+          amountSat,
+          description: original.description ?? request.description ?? "",
+          expirySeconds: invoiceExpirySeconds
+        });
+        serialized = invoice.serialized;
+        details = invoiceDetails(
+          await client.decodeInvoice({ invoice: serialized }),
+          request,
+          network
+        );
+        if (invoice.paymentHash !== details.paymentHash || invoice.amountSat !== amountSat)
+          throw new TypeError(
+            "Generated invoice does not match the node response"
+          );
+      } catch {
+        throw new ChargeError(
+          "invalid_invoice",
+          "Phoenixd could not provide a matching, unexpired invoice"
+        );
+      }
+      const requestedExpiry = original.expires === void 0 ? Date.now() + 3e5 : Date.parse(original.expires);
+      const expiresAt = Math.min(requestedExpiry, details.expiresAt);
+      if (!Number.isFinite(expiresAt) || expiresAt <= Date.now())
+        throw new ChargeError(
+          "invoice_expired",
+          "The configured challenge expiry is in the past"
+        );
+      const issuedRequest = {
+        ...request,
+        methodDetails: {
+          invoice: serialized,
+          paymentHash: details.paymentHash,
+          network: details.network
+        }
+      };
+      const issued = Challenge.from({
+        secretKey: context.secretKey,
+        realm: original.realm,
+        method: "lightning",
+        intent: "charge",
+        request: issuedRequest,
+        expires: new Date(expiresAt),
+        ...original.description === void 0 ? {} : { description: original.description },
+        ...original.opaque === void 0 ? {} : { opaque: original.opaque },
+        ...original.digest === void 0 ? {} : { digest: original.digest },
+        ...original.header === void 0 ? {} : { header: original.header }
+      });
+      Object.assign(original.request, issuedRequest);
+      Object.assign(original, issued, { request: original.request });
+      const record = {
+        id: original.id,
+        serializedChallenge: Challenge.serialize(original),
+        paymentHash: details.paymentHash,
+        amountSat,
+        expiresAt,
+        requestUrl: parameters.input.url,
+        requestMethod: parameters.input.method,
+        bodyHash: context.bodyHash
+      };
+      try {
+        await store.issue(record);
+      } catch {
+        throw new ChargeError(
+          "store_unavailable",
+          "Could not persist the payment challenge"
+        );
+      }
+      return http.respondChallenge({
+        ...parameters,
+        error: parameters.error,
+        challenge: original
+      });
+    },
+    respondReceipt(parameters) {
+      const response = http.respondReceipt(parameters);
+      response.headers.set("Cache-Control", "no-store");
+      return response;
+    }
+  };
+  async function validate(parameters) {
+    const { credential, envelope, request } = parameters;
+    const context = envelope === void 0 ? void 0 : byCaptured.get(envelope.capturedRequest);
+    if (!context)
+      throw new ChargeError(
+        "invalid_challenge",
+        "Use the configured HTTP payment handler"
+      );
+    let record;
+    try {
+      record = await store.get(credential.challenge.id);
+    } catch {
+      throw new ChargeError(
+        "store_unavailable",
+        "Could not read the payment challenge"
+      );
+    }
+    if (!record)
+      throw new ChargeError(
+        "unknown_challenge",
+        "The payment challenge is unknown"
+      );
+    if (Date.now() >= record.expiresAt)
+      throw new ChargeError(
+        "invoice_expired",
+        "The payment challenge has expired"
+      );
+    if (record.serializedChallenge !== Challenge.serialize(credential.challenge) || record.amountSat !== satoshis(request.amount) || request.currency !== "sat") {
+      throw new ChargeError(
+        "invalid_challenge",
+        "The credential does not match the issued payment challenge"
+      );
+    }
+    if (record.requestUrl !== context.input.url || record.requestMethod !== context.input.method || record.bodyHash !== context.bodyHash) {
+      throw new ChargeError(
+        "invalid_challenge",
+        "The credential does not match this request"
+      );
+    }
+    let hash;
+    try {
+      hash = paymentHash(credential.payload.preimage);
+    } catch {
+      throw new ChargeError("invalid_preimage", "The payment proof is invalid");
+    }
+    if (hash !== record.paymentHash)
+      throw new ChargeError("invalid_preimage", "The payment proof is invalid");
+    return record;
+  }
+  return Method.toServer(charge, {
+    defaults,
+    transport,
+    async preflight({ capturedRequest, input, secretKey }) {
+      const context = {
+        input,
+        secretKey,
+        bodyHash: await bodyHash(input)
+      };
+      byInput.set(input, context);
+      if (capturedRequest) byCaptured.set(capturedRequest, context);
+      return void 0;
+    },
+    stableBinding: (request) => ({
+      amount: request.amount,
+      currency: request.currency
+    }),
+    async validate(parameters) {
+      await validate(parameters);
+      return {
+        challenge: parameters.credential.challenge,
+        credential: parameters.credential,
+        details: {},
+        intent: "charge",
+        method: "lightning",
+        request: parameters.credential.challenge.request
+      };
+    },
+    async broadcast(parameters) {
+      const record = await validate(parameters);
+      let consumed;
+      try {
+        consumed = await store.consume(record.id);
+      } catch {
+        throw new ChargeError(
+          "store_unavailable",
+          "Could not consume the payment challenge"
+        );
+      }
+      if (!consumed)
+        throw new ChargeError(
+          "already_consumed",
+          "The payment challenge has already been used or expired"
+        );
+      return Receipt.from({
+        method: "lightning",
+        reference: record.paymentHash,
+        status: "success",
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      });
+    }
+  });
+}
+export {
+  ChargeError,
+  Mppx,
+  charge2 as charge,
+  memoryStore,
+  methods_exports as phoenixd,
+  redisStore
+};
+//# sourceMappingURL=index.js.map

package/dist/server/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/server/index.ts","../../src/server/methods.ts","../../src/server/charge.ts","../../src/server/store.ts"],"sourcesContent":["export { Mppx } from \"mppx/server\";\nexport * as phoenixd from \"./methods\";\nexport { charge } from \"./charge\";\nexport type { ChargeOptions, ServerChargeMethod } from \"./charge\";\nexport { redisStore, memoryStore } from \"./store\";\nexport type {\n  ChargeStore,\n  ManagedChargeStore,\n  StoredCharge,\n  RedisClient,\n  RedisStoreOptions,\n} from \"./store\";\nexport { ChargeError } from \"../errors\";\n","export { charge } from \"./charge\";\n","import { Challenge, Method, Receipt } from \"mppx\";\nimport { Transport } from \"mppx/server\";\nimport type { PhoenixdClient } from \"@nodana/phoenixd-ts\";\nimport * as Methods from \"../Methods\";\nimport { ChargeError } from \"../errors\";\nimport { bodyHash, invoiceDetails, paymentHash, satoshis } from \"../shared\";\nimport { memoryStore } from \"./store\";\nimport type { ChargeStore, StoredCharge } from \"./store\";\n\nexport interface ChargeOptions {\n  client: Pick<PhoenixdClient, \"createInvoice\" | \"decodeInvoice\">;\n  /** Use a shared durable store for deployed services. Defaults to process-local memory. */\n  store?: ChargeStore;\n  /** Invoice lifetime in seconds. Defaults to 3600; challenge expiry is capped to it. */\n  invoiceExpirySeconds?: number;\n  network?: Methods.LightningNetwork;\n}\n\nconst defaults = { currency: \"sat\", methodDetails: { invoice: \"\" } } as const;\n\nexport type ServerChargeMethod = Method.Server<\n  typeof Methods.charge,\n  typeof defaults,\n  Transport.Http\n>;\n\ninterface HttpContext {\n  input: Request;\n  secretKey: string;\n  bodyHash: string;\n}\n\nexport function charge(options: ChargeOptions): ServerChargeMethod {\n  const {\n    client,\n    store = memoryStore(),\n    network,\n    invoiceExpirySeconds = 3600,\n  } = options;\n\n  if (!Number.isSafeInteger(invoiceExpirySeconds) || invoiceExpirySeconds < 1)\n    throw new TypeError(\"invoiceExpirySeconds must be a positive integer\");\n\n  const byInput = new WeakMap<Request, HttpContext>();\n  const byCaptured = new WeakMap<Method.CapturedRequest, HttpContext>();\n  const http = Transport.http();\n\n  const transport: Transport.Http = {\n    ...http,\n\n    async respondChallenge(parameters) {\n      const context = byInput.get(parameters.input);\n\n      if (!context)\n        throw new ChargeError(\n          \"invalid_challenge\",\n          \"An HTTP payment handler is required\",\n        );\n\n      const original = parameters.challenge;\n      const request = Methods.charge.schema.request.parse(original.request);\n      const amountSat = satoshis(request.amount);\n      let details: ReturnType<typeof invoiceDetails>;\n      let serialized: string;\n\n      try {\n        const invoice = await client.createInvoice({\n          amountSat,\n          description: original.description ?? request.description ?? \"\",\n          expirySeconds: invoiceExpirySeconds,\n        });\n\n        serialized = invoice.serialized;\n        details = invoiceDetails(\n          await client.decodeInvoice({ invoice: serialized }),\n          request,\n          network,\n        );\n\n        if (\n          invoice.paymentHash !== details.paymentHash ||\n          invoice.amountSat !== amountSat\n        )\n          throw new TypeError(\n            \"Generated invoice does not match the node response\",\n          );\n      } catch {\n        throw new ChargeError(\n          \"invalid_invoice\",\n          \"Phoenixd could not provide a matching, unexpired invoice\",\n        );\n      }\n\n      const requestedExpiry =\n        original.expires === undefined\n          ? Date.now() + 300_000\n          : Date.parse(original.expires);\n      const expiresAt = Math.min(requestedExpiry, details.expiresAt);\n\n      if (!Number.isFinite(expiresAt) || expiresAt <= Date.now())\n        throw new ChargeError(\n          \"invoice_expired\",\n          \"The configured challenge expiry is in the past\",\n        );\n\n      const issuedRequest = {\n        ...request,\n        methodDetails: {\n          invoice: serialized,\n          paymentHash: details.paymentHash,\n          network: details.network,\n        },\n      };\n      const issued = Challenge.from({\n        secretKey: context.secretKey,\n        realm: original.realm,\n        method: \"lightning\",\n        intent: \"charge\",\n        request: issuedRequest,\n        expires: new Date(expiresAt),\n        ...(original.description === undefined\n          ? {}\n          : { description: original.description }),\n        ...(original.opaque === undefined ? {} : { opaque: original.opaque }),\n        ...(original.digest === undefined ? {} : { digest: original.digest }),\n        ...(original.header === undefined ? {} : { header: original.header }),\n      });\n\n      // Enrich the framework's challenge in place so its lifecycle event sees\n      // the same issued ID/request as the HTTP response. No invoice is created\n      // on a successful credential retry; only challenge responses need one.\n      Object.assign(original.request, issuedRequest);\n      Object.assign(original, issued, { request: original.request });\n\n      const record: StoredCharge = {\n        id: original.id,\n        serializedChallenge: Challenge.serialize(original),\n        paymentHash: details.paymentHash,\n        amountSat,\n        expiresAt,\n        requestUrl: parameters.input.url,\n        requestMethod: parameters.input.method,\n        bodyHash: context.bodyHash,\n      };\n\n      try {\n        await store.issue(record);\n      } catch {\n        throw new ChargeError(\n          \"store_unavailable\",\n          \"Could not persist the payment challenge\",\n        );\n      }\n\n      // Rejected credentials always receive a fresh invoice/challenge. Neither\n      // malformed payloads nor a consumed preimage can trigger reuse.\n      return http.respondChallenge({\n        ...parameters,\n        error: parameters.error,\n        challenge: original,\n      });\n    },\n\n    respondReceipt(parameters) {\n      const response = http.respondReceipt(parameters);\n\n      response.headers.set(\"Cache-Control\", \"no-store\");\n\n      return response;\n    },\n  };\n\n  async function validate(\n    parameters: Method.VerifyContext<typeof Methods.charge>,\n  ): Promise<StoredCharge> {\n    const { credential, envelope, request } = parameters;\n    const context =\n      envelope === undefined\n        ? undefined\n        : byCaptured.get(envelope.capturedRequest);\n\n    if (!context)\n      throw new ChargeError(\n        \"invalid_challenge\",\n        \"Use the configured HTTP payment handler\",\n      );\n\n    let record: StoredCharge | undefined;\n\n    try {\n      record = await store.get(credential.challenge.id);\n    } catch {\n      throw new ChargeError(\n        \"store_unavailable\",\n        \"Could not read the payment challenge\",\n      );\n    }\n\n    if (!record)\n      throw new ChargeError(\n        \"unknown_challenge\",\n        \"The payment challenge is unknown\",\n      );\n\n    if (Date.now() >= record.expiresAt)\n      throw new ChargeError(\n        \"invoice_expired\",\n        \"The payment challenge has expired\",\n      );\n\n    if (\n      record.serializedChallenge !==\n        Challenge.serialize(credential.challenge) ||\n      record.amountSat !== satoshis(request.amount) ||\n      request.currency !== \"sat\"\n    ) {\n      throw new ChargeError(\n        \"invalid_challenge\",\n        \"The credential does not match the issued payment challenge\",\n      );\n    }\n\n    if (\n      record.requestUrl !== context.input.url ||\n      record.requestMethod !== context.input.method ||\n      record.bodyHash !== context.bodyHash\n    ) {\n      throw new ChargeError(\n        \"invalid_challenge\",\n        \"The credential does not match this request\",\n      );\n    }\n\n    let hash: string;\n\n    try {\n      hash = paymentHash(credential.payload.preimage);\n    } catch {\n      throw new ChargeError(\"invalid_preimage\", \"The payment proof is invalid\");\n    }\n\n    if (hash !== record.paymentHash)\n      throw new ChargeError(\"invalid_preimage\", \"The payment proof is invalid\");\n\n    return record;\n  }\n\n  return Method.toServer(Methods.charge, {\n    defaults,\n    transport,\n\n    async preflight({ capturedRequest, input, secretKey }) {\n      const context: HttpContext = {\n        input,\n        secretKey,\n        bodyHash: await bodyHash(input),\n      };\n\n      byInput.set(input, context);\n\n      if (capturedRequest) byCaptured.set(capturedRequest, context);\n\n      return undefined;\n    },\n\n    stableBinding: (request) => ({\n      amount: request.amount,\n      currency: request.currency,\n    }),\n\n    async validate(parameters) {\n      await validate(parameters);\n\n      return {\n        challenge: parameters.credential.challenge,\n        credential: parameters.credential,\n        details: {},\n        intent: \"charge\",\n        method: \"lightning\",\n        request: parameters.credential.challenge.request,\n      };\n    },\n\n    async broadcast(parameters) {\n      const record = await validate(parameters);\n      let consumed: boolean;\n\n      try {\n        consumed = await store.consume(record.id);\n      } catch {\n        throw new ChargeError(\n          \"store_unavailable\",\n          \"Could not consume the payment challenge\",\n        );\n      }\n\n      if (!consumed)\n        throw new ChargeError(\n          \"already_consumed\",\n          \"The payment challenge has already been used or expired\",\n        );\n\n      return Receipt.from({\n        method: \"lightning\",\n        reference: record.paymentHash,\n        status: \"success\",\n        timestamp: new Date().toISOString(),\n      });\n    },\n  });\n}\n","/** Stored values contain no payment preimages or node credentials. */\nexport interface StoredCharge {\n  readonly id: string;\n  readonly serializedChallenge: string;\n  readonly paymentHash: string;\n  readonly amountSat: number;\n  readonly expiresAt: number;\n  readonly requestUrl: string;\n  readonly requestMethod: string;\n  readonly bodyHash: string;\n}\n\nexport interface ChargeStore {\n  /** Persist before responding with a challenge. Reject reused IDs/payment hashes. */\n  issue(charge: StoredCharge): Promise<void>;\n  get(id: string): Promise<StoredCharge | undefined>;\n  /** Atomically succeeds once, and only while the stored challenge is unexpired. */\n  consume(id: string): Promise<boolean>;\n}\n\nexport interface ManagedChargeStore extends ChargeStore {\n  pruneExpired(): Promise<number>;\n}\n\nconst validId = (id: string) =>\n  typeof id === \"string\" && /^[A-Za-z0-9_-]{1,128}$/.test(id);\n\nfunction assertRecord(value: unknown): asserts value is StoredCharge {\n  if (typeof value !== \"object\" || value === null)\n    throw new TypeError(\"Invalid stored challenge\");\n\n  const record = value as StoredCharge;\n\n  if (\n    !validId(record.id) ||\n    !/^[0-9a-f]{64}$/.test(record.paymentHash) ||\n    !/^[0-9a-f]{64}$/.test(record.bodyHash) ||\n    !Number.isSafeInteger(record.amountSat) ||\n    record.amountSat < 1 ||\n    !Number.isSafeInteger(record.expiresAt) ||\n    typeof record.serializedChallenge !== \"string\" ||\n    typeof record.requestUrl !== \"string\" ||\n    typeof record.requestMethod !== \"string\"\n  ) {\n    throw new TypeError(\"Invalid stored challenge\");\n  }\n}\n\nexport function memoryStore(\n  options: { maxEntries?: number } = {},\n): ManagedChargeStore {\n  const maxEntries = options.maxEntries ?? 10_000;\n\n  if (!Number.isSafeInteger(maxEntries) || maxEntries < 1)\n    throw new TypeError(\"maxEntries must be positive\");\n\n  const entries = new Map<\n    string,\n    { charge: StoredCharge; consumed: boolean }\n  >();\n  const hashes = new Set<string>();\n\n  const prune = () => {\n    let removed = 0;\n\n    for (const [id, entry] of entries)\n      if (entry.charge.expiresAt <= Date.now()) {\n        entries.delete(id);\n        hashes.delete(entry.charge.paymentHash);\n        removed++;\n      }\n\n    return removed;\n  };\n\n  return {\n    async issue(charge) {\n      assertRecord(charge);\n\n      if (charge.expiresAt <= Date.now()) throw new Error(\"Charge has expired\");\n\n      prune();\n\n      if (entries.size >= maxEntries)\n        throw new Error(\"Charge store capacity reached\");\n\n      if (entries.has(charge.id) || hashes.has(charge.paymentHash))\n        throw new Error(\"Charge already issued\");\n\n      entries.set(charge.id, {\n        charge: structuredClone(charge),\n        consumed: false,\n      });\n      hashes.add(charge.paymentHash);\n    },\n\n    async get(id) {\n      return entries.has(id)\n        ? structuredClone(entries.get(id)!.charge)\n        : undefined;\n    },\n\n    async consume(id) {\n      const entry = entries.get(id);\n\n      if (!entry || entry.consumed || entry.charge.expiresAt <= Date.now())\n        return false;\n\n      entry.consumed = true;\n\n      return true;\n    },\n\n    async pruneExpired() {\n      return prune();\n    },\n  };\n}\n\n/** Compatible with a connected node-redis client using its default reply types. */\nexport interface RedisClient {\n  sendCommand(args: string[]): Promise<unknown>;\n}\n\nexport interface RedisStoreOptions {\n  /** Namespace shared by instances of this service. Defaults to phoenixd-mpp. */\n  keyPrefix?: string;\n}\n\n// Both keys share a hash tag. All checks and writes run in one Redis operation.\nconst issueScript = `\nlocal time = redis.call('TIME')\nlocal now = tonumber(time[1]) * 1000 + math.floor(tonumber(time[2]) / 1000)\nlocal expires = tonumber(ARGV[2])\nif expires <= now then return -1 end\nif redis.call('EXISTS', KEYS[1]) == 1 or redis.call('EXISTS', KEYS[2]) == 1 then return 0 end\nredis.call('HSET', KEYS[1], 'record', ARGV[1], 'expires', ARGV[2], 'consumed', '0')\nredis.call('PEXPIREAT', KEYS[1], ARGV[2])\nredis.call('SET', KEYS[2], ARGV[3])\nredis.call('PEXPIREAT', KEYS[2], ARGV[2])\nreturn 1\n`;\n\nconst consumeScript = `\nif redis.call('EXISTS', KEYS[1]) == 0 then return 0 end\nlocal expires = tonumber(redis.call('HGET', KEYS[1], 'expires'))\nlocal consumed = redis.call('HGET', KEYS[1], 'consumed')\nif not expires or (consumed ~= '0' and consumed ~= '1') then\n  return redis.error_reply('Invalid stored payment challenge')\nend\nlocal time = redis.call('TIME')\nlocal now = tonumber(time[1]) * 1000 + math.floor(tonumber(time[2]) / 1000)\nif expires <= now or consumed == '1' then return 0 end\nredis.call('HSET', KEYS[1], 'consumed', '1')\nreturn 1\n`;\n\n/** Shared payment state; Redis expires records automatically. Does not own the connection. */\nexport function redisStore(\n  client: RedisClient,\n  options: RedisStoreOptions = {},\n): ChargeStore {\n  const prefix = options.keyPrefix ?? \"phoenixd-mpp\";\n\n  if (!/^[A-Za-z0-9:_-]{1,128}$/.test(prefix))\n    throw new TypeError(\"Invalid Redis keyPrefix\");\n\n  const root = `{${prefix}}:`;\n\n  const key = (id: string) => `${root}challenge:${id}`;\n\n  return {\n    async issue(charge) {\n      assertRecord(charge);\n\n      // Serialize before awaiting so caller mutations cannot change issued state.\n      const result = await client.sendCommand([\n        \"EVAL\",\n        issueScript,\n        \"2\",\n        key(charge.id),\n        `${root}hash:${charge.paymentHash}`,\n        JSON.stringify(charge),\n        String(charge.expiresAt),\n        charge.id,\n      ]);\n\n      if (result === -1) throw new Error(\"Charge has expired\");\n\n      if (result === 0) throw new Error(\"Charge already issued\");\n\n      if (result !== 1) throw new Error(\"Unexpected Redis issuance response\");\n    },\n\n    async get(id) {\n      if (!validId(id)) return undefined;\n\n      const value = await client.sendCommand([\"HGET\", key(id), \"record\"]);\n\n      if (value === null) return undefined;\n\n      if (typeof value !== \"string\")\n        throw new TypeError(\"Invalid Redis record response\");\n\n      const record: unknown = JSON.parse(value);\n\n      assertRecord(record);\n\n      if (record.id !== id)\n        throw new TypeError(\"Stored challenge ID does not match\");\n\n      return record;\n    },\n\n    async consume(id) {\n      if (!validId(id)) return false;\n\n      const result = await client.sendCommand([\n        \"EVAL\",\n        consumeScript,\n        \"1\",\n        key(id),\n      ]);\n\n      if (result !== 0 && result !== 1)\n        throw new Error(\"Unexpected Redis consumption response\");\n\n      return result === 1;\n    },\n  };\n}\n"],"mappings":"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","names":["charge","charge","charge"]}

package/docs/development.md

@@ -0,0 +1,82 @@
+# Development
+
+## Local setup
+
+Use Node.js 22.12 or later. Install dependencies and run the checks:
+
+```sh
+npm install
+npm test
+```
+
+The adapter uses `@nodana/phoenixd-ts` from npm for both development and its public peer dependency. It requires version 0.2.0 or later within the 0.2 series.
+
+The test command checks source and test types, runs the tests, builds all entry points, and checks ESM/CommonJS imports and TypeScript declarations as consumers. The integration test exercises the real Phoenixd HTTP client through an injected fetch implementation, including node authentication, form encoding, a missing payment response, and the MPP client's automatic paid retry. It uses mocked node responses; it does not verify real BOLT11 decoding, Lightning settlement or compatibility with a live daemon. Run a funded regtest integration before a production release.
+
+### Redis integration tests
+
+With `redis-server` and `redis-cli` available on your PATH, run:
+
+```sh
+npm run test:redis
+```
+
+This suite starts a disposable Redis instance on a Unix socket with TCP disabled. It checks concurrent issuance and consumption across independent clients, key expiry, namespace isolation, persistence across actual Redis restarts, and the paid HTTP flow across server instances. It uses a private temporary directory and never connects to an existing Redis service. The regular `npm test` does not require a Redis installation.
+
+## Package roles
+
+`phoenixd-ts` handles the node HTTP API. `mppx` supplies the MPP schemas, signed challenges, credentials, receipts and HTTP handler. This package implements the Lightning charge method between them. Server and payer exports are separate; each accepts a configured client instance.
+
+The Lightning wire schema is adapted from the MIT-licensed Lightspark implementation. Attribution is in `NOTICE`. Node access, request binding, state storage and payment handling are implemented here.
+
+## HTTP lifecycle
+
+The adapter targets mppx 0.13.4's `preflight`, `validate` and `broadcast` hooks. Preflight captures the HTTP request and hashes its body without consuming the application's copy. The adapter supports the HTTP handler lifecycle; standalone credential validation and alternate transports do not supply the required request context and fail closed.
+
+Invoices are created only when returning a challenge. The transport response hook fills the invoice details, caps expiry to the invoice, signs the completed challenge, and persists it before responding. It updates the framework's challenge and request objects in place so lifecycle events report the same signed challenge that went to the client. A successful credential retry does not create another invoice.
+
+Validation compares the entire echoed challenge to its stored form, checks expiry and current price, binds it to the exact URL, HTTP method and body hash, and verifies the SHA-256 preimage proof. Broadcast validates again, then atomically consumes the challenge before returning a receipt. Replayed or invalid credentials receive a fresh challenge and invoice. Payment responses use `Cache-Control: no-store`.
+
+Request bodies are buffered for hashing. Apply the application's normal request size limits before the payment handler. Application headers are not part of the stored request binding; keep authorisation and any header-dependent resource selection in the application's access checks.
+
+The payer checks decoded invoice amount, hash, network and expiry before paying. Concurrent requests for the same invoice within one method instance share a payment promise. It checks outgoing history before sending; a settled payment reuses its verified proof and a pending payment fails closed. On an uncertain payment result, it checks history once and otherwise reports `payment_unknown`. It does not automatically send another payment. This coalescing is process-local; coordinate multiple payer processes separately.
+
+A consumed credential is not a fulfilment record. If application work fails after acceptance, another request requires another payment. For operations needing recoverable fulfilment, record the purchased operation and expose an authenticated recovery endpoint in the application.
+
+## Implement a charge store
+
+Implement the exported `ChargeStore` interface when using a database or a distributed deployment:
+
+- `issue(record)` persists an immutable record before the challenge response, rejecting duplicate IDs and payment hashes among retained records.
+- `get(id)` returns the authoritative record or `undefined` for an unknown ID. Report storage failures by throwing.
+- `consume(id)` atomically returns `true` once, only for an existing, unconsumed, unexpired record. Concurrent callers across processes must have exactly one winner. Throw on storage failure.
+
+Store no payment preimages or node passwords. Enforce atomic uniqueness and consumption in the database itself. Retain records until expiry, including consumed records, so payment credentials cannot be replayed during their lifetime. Keep issuance and consumption reads consistent across instances.
+
+`redisStore(client, { keyPrefix })` accepts the connected `node-redis` client through a structural `RedisClient` interface requiring `sendCommand(args)`. It does not add a Redis runtime dependency, open or close connections, or handle reconnects. The application owns the client's lifecycle. Default replies must be strings/numbers/null, as returned by node-redis without custom reply mappings.
+
+Issuance uses a Lua script to check both challenge ID and payment hash uniqueness, then persist the record and hash reservation together. Consumption uses another script to check expiry and the consumed flag, then mark the challenge used in the same operation. Both scripts use Redis server time. Challenge records and hash reservations expire at the signed challenge's expiry; consuming a record preserves its expiry. No scheduled cleanup is needed.
+
+The namespace is wrapped in a Redis hash tag so all script keys share a slot. Use the same `keyPrefix` for a service's instances and a different prefix for independent services. The client must support raw `EVAL` and `HGET` commands and connect to the primary; the SDK does not implement Redis Cluster routing or an HTTP Redis client. Redis ACLs must permit `EVAL` and the script's `TIME`, `EXISTS`, `HSET`, `HGET`, `SET` and `PEXPIREAT` commands on the namespace.
+
+Use Redis persistence appropriate for payment state, with `noeviction`, sufficient capacity, and clocks synchronised between application hosts and Redis. Connection errors and unexpected replies fail closed. Lost state makes outstanding challenges unusable. Rolling back consumed state can permit reuse; persistence and replication/failover guarantees remain properties of the Redis deployment. Never reset or restore older payment state while its challenges remain valid.
+
+`memoryStore({ maxEntries })` defaults to 10,000 entries. It prunes expired records on issuance and refuses further issuance when full rather than evicting active records. It is limited to one process and loses state at restart.
+
+## Release
+
+Publishing a GitHub Release triggers `.github/workflows/npm-publish.yml`. Pushes to branches or tags, pull requests, draft releases and release-note edits do not trigger publication.
+
+1. Update the version in `package.json` and `package-lock.json`, for example with `npm version patch --no-git-tag-version`.
+2. Commit and push the version change and release code to `main`.
+3. In GitHub, open **Releases → Draft a new release**. Create a tag matching the package version exactly, such as `v0.1.1`, targeting the release commit on `main`.
+4. Add the release title and notes, then click **Publish release**.
+5. Check the **Publish to npm** workflow. It validates the release tag and both manifest versions, installs dependencies, runs the checks, and publishes the tagged code to npm with provenance. Its summary reports whether publication succeeded.
+
+The npm trusted publisher must point to organisation `nodana`, repository `phoenixd-mpp-sdk`, workflow `npm-publish.yml`, with no environment and direct publishing allowed. The source repository must be public for npm provenance. Stable releases publish to the `latest` npm dist-tag; GitHub prereleases publish to `next`.
+
+The workflow checks and builds before publishing, then uses `--ignore-scripts` to avoid running `prepublishOnly` a second time. Manual `npm publish` still runs the full test/build hook. Test results remain in the logs; the Actions summary reports the release outcome.
+
+npm versions cannot be overwritten. If a release fails before publication, fix the cause before retrying. For versions already on npm, create a GitHub Release from the tag matching their original source commit rather than publishing the package again.
+
+When retrying an unpublished version after changing the workflow or code, its tag must include those fixes. Commit and push the fixes first, then replace the failed tag before creating the GitHub Release. Do not move a tag for a version already published to npm.

package/package.json

@@ -1,6 +1,83 @@
 {
   "name": "@nodana/phoenixd-mpp-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Phoenixd Lightning payment methods for the Machine Payments Protocol",
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./server": {
+      "import": {
+        "types": "./dist/server/index.d.ts",
+        "default": "./dist/server/index.js"
+      },
+      "require": {
+        "types": "./dist/server/index.d.cts",
+        "default": "./dist/server/index.cjs"
+      }
+    },
+    "./client": {
+      "import": {
+        "types": "./dist/client/index.d.ts",
+        "default": "./dist/client/index.js"
+      },
+      "require": {
+        "types": "./dist/client/index.d.cts",
+        "default": "./dist/client/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "docs",
+    "NOTICE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.tests.json",
+    "test:unit": "vitest run --reporter=default",
+    "test": "npm run typecheck && npm run test:unit && npm run build && node tests/package-smoke.mjs",
+    "prepublishOnly": "npm test",
+    "test:redis": "vitest run --config vitest.redis.config.ts --reporter=default"
+  },
+  "peerDependencies": {
+    "@nodana/phoenixd-ts": "^0.2.0",
+    "mppx": "^0.13.4"
+  },
+  "devDependencies": {
+    "@nodana/phoenixd-ts": "^0.2.0",
+    "mppx": "^0.13.4",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.9.3",
+    "tsup": "^8.5.0",
+    "vitest": "^4.1.11",
+    "esbuild": "^0.28.2"
+  },
+  "overrides": {
+    "esbuild": "^0.28.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nodana/phoenixd-mpp-sdk.git"
+  },
+  "homepage": "https://github.com/nodana/phoenixd-mpp-sdk#readme",
+  "bugs": {
+    "url": "https://github.com/nodana/phoenixd-mpp-sdk/issues"
+  }
+}