@siglume/direct-request-payment 0.1.0 → 0.3.1

package/docs/security.md

@@ -1,85 +1,110 @@
-# Security Guide
-
-Direct Request Payment is a wallet payment rail. Treat it like payment
-infrastructure, not like a generic API call.
-
-## Do Not Expose Secrets
-
-These values must stay server-side:
-
-- `SIGLUME_DIRECT_PAYMENT_CHALLENGE_SECRET`
-- `SIGLUME_WEBHOOK_SECRET`
-- any merchant administrative credentials
-
-The buyer-facing browser may receive the signed `challenge` string, but never
-the secret that produced it.
-
-## Bind the Order Server-Side
-
-The HMAC challenge covers:
-
-```text
-merchant:amount_minor:currency:nonce
-```
-
-Use a nonce derived from a durable order payment attempt, for example
-`order_123-attempt_1`. The nonce must not contain `:` because the platform
-challenge is encoded as `scheme:nonce:signature`. Store the returned
-`challenge_hash` on the order. When a
-webhook arrives, look up the order by `challenge_hash`.
-
-## Do Not Trust Browser Amounts
-
-The merchant server owns:
-
-- SKU or plan
-- amount in minor units
-- currency
-- nonce
-
-If a browser says the order total is 1200 JPY, treat that as display state only.
-Re-read the order server-side before generating the challenge.
-
-## Webhook Verification
-
-Verify the `Siglume-Signature` header using the raw request body. Do not parse
-and re-stringify JSON before verification.
-
-The SDK expects the Siglume signature format:
-
-```text
-t=<unix timestamp>,v1=<hex hmac sha256>
-```
-
-The signed payload is:
-
-```text
-<timestamp>.<raw body>
-```
-
-The default tolerance is 300 seconds.
-
-## Idempotency
-
-Fulfill exactly once per order. Store at least:
-
-- order id
-- challenge hash
-- Siglume requirement id
-- on-chain receipt id or transaction hash if present
-- fulfillment state
-
-Duplicate webhook deliveries and manual redelivery can occur. A duplicate
-webhook with the same requirement id must not ship the order twice.
-
-## What Direct Request Payment Is Not
-
-Direct Request Payment is not:
-
-- stored value
-- prepaid points
-- escrow
-- a platform balance
-- a card payment fallback
-
-It is a one-request wallet payment gate backed by an on-chain receipt.
+# Security Guide
+
+Direct Request Payment is a wallet payment rail. Treat it like payment
+infrastructure, not like a generic API call.
+
+## Do Not Expose Secrets
+
+These values must stay server-side:
+
+- `SIGLUME_DIRECT_PAYMENT_CHALLENGE_SECRET`
+- `SIGLUME_WEBHOOK_SECRET`
+- any merchant administrative credentials
+
+The buyer-facing browser may receive the signed `challenge` string, but never
+the secret that produced it.
+
+## Keep JWT Roles Separate
+
+Use the merchant's Siglume JWT only for setup actions such as `setupCheckout`,
+challenge secret rotation, billing mandate preparation, and webhook subscription
+creation.
+
+Use the buyer's Siglume JWT only when creating and paying a payment requirement.
+A merchant JWT or Developer Portal `cli_` key must not be used to charge a
+customer wallet.
+
+## Bind the Order Server-Side
+
+The HMAC challenge covers:
+
+```text
+merchant:amount_minor:currency:nonce
+```
+
+Use a nonce derived from a durable order payment attempt, for example
+`order_123-attempt_1`. The nonce must not contain `:` because the platform
+challenge is encoded as `scheme:nonce:signature`. Store the returned
+`challenge_hash` on the order. When a
+webhook arrives, look up the order by `challenge_hash`.
+
+Recurring approvals use a different challenge scheme and HMAC material:
+
+```text
+merchant:amount_minor:currency:cadence:nonce
+```
+
+`cadence="monthly"` is for subscriptions. `cadence="daily"` is the scheduled
+autopay approval tag; it does not itself limit occurrences to once per day.
+Scheduled autopay execution is bounded by the buyer-approved per-run, daily, and
+monthly auto-pay budget.
+
+## Do Not Trust Browser Amounts
+
+The merchant server owns:
+
+- SKU or plan
+- amount in minor units
+- currency
+- nonce
+
+If a browser says the order total is 1200 JPY, treat that as display state only.
+Re-read the order server-side before generating the challenge.
+
+## Webhook Verification
+
+Verify the `Siglume-Signature` header using the raw request body. Do not parse
+and re-stringify JSON before verification.
+
+The SDK expects the Siglume signature format:
+
+```text
+t=<unix timestamp>,v1=<hex hmac sha256>
+```
+
+The signed payload is:
+
+```text
+<timestamp>.<raw body>
+```
+
+The default tolerance is 300 seconds.
+
+Use verified webhook data as the durable completion signal. Browser redirects,
+client-side callbacks, or local transaction responses can improve UX, but they
+should not be the only source used to fulfill an order.
+
+## Idempotency
+
+Fulfill exactly once per order. Store at least:
+
+- order id
+- challenge hash
+- Siglume requirement id
+- on-chain receipt id or transaction hash if present
+- fulfillment state
+
+Duplicate webhook deliveries and manual redelivery can occur. A duplicate
+webhook with the same requirement id must not ship the order twice.
+
+## What Direct Request Payment Is Not
+
+Direct Request Payment is not:
+
+- stored value
+- prepaid points
+- escrow
+- a platform balance
+- a card payment fallback
+
+It is a one-request wallet payment gate backed by an on-chain receipt.

package/examples/express-checkout.ts

@@ -1,105 +1,106 @@
-import express from "express";
-import {
-  createDirectRequestPaymentChallenge,
-  DirectRequestPaymentClient,
-  verifyDirectRequestPaymentWebhook,
-} from "@siglume/direct-request-payment";
-
-const app = express();
-const port = Number(process.env.PORT || 3000);
-
-// Use JSON for normal routes. Use raw body only on the webhook route.
-app.use((req, res, next) => {
-  if (req.path === "/siglume/webhook") {
-    next();
-    return;
-  }
-  express.json()(req, res, next);
-});
-
-const orders = new Map<string, any>();
-
-const asyncRoute =
-  (handler: express.RequestHandler): express.RequestHandler =>
-  (req, res, next) => {
-    Promise.resolve(handler(req, res, next)).catch(next);
-  };
-
-app.post("/checkout/siglume/start", asyncRoute(async (req, res) => {
-  const orderId = String(req.body.order_id || "");
-  const order = orders.get(orderId);
-  if (!order) {
-    res.status(404).json({ error: "order_not_found" });
-    return;
-  }
-
-  order.payment_attempt = Number(order.payment_attempt || 0) + 1;
-  const challenge = await createDirectRequestPaymentChallenge({
-    merchant: "example_merchant",
-    amount_minor: order.amount_minor,
-    currency: order.currency,
-    secret: process.env.SIGLUME_DIRECT_PAYMENT_CHALLENGE_SECRET!,
-    nonce: `${order.id}-attempt_${order.payment_attempt}`,
-  });
-
-  order.siglume_challenge_hash = challenge.challenge_hash;
-  order.siglume_payment_status = "pending";
-
-  res.json({
-    order_id: order.id,
-    amount_minor: order.amount_minor,
-    currency: order.currency,
-    siglume_challenge: challenge.challenge,
-  });
-}));
-
-app.post("/checkout/siglume/pay", asyncRoute(async (req, res) => {
-  const order = orders.get(String(req.body.order_id || ""));
-  if (!order) {
-    res.status(404).json({ error: "order_not_found" });
-    return;
-  }
-
-  // In production, obtain this from the authenticated buyer's Siglume session
-  // or a hosted Siglume payment confirmation flow. Do not use a merchant secret
-  // to charge a customer wallet.
-  const siglume = new DirectRequestPaymentClient({
-    auth_token: String(req.headers.authorization || "").replace(/^Bearer\s+/i, ""),
-  });
-
-  const requirement = await siglume.createPaymentRequirement({
-    merchant: "example_merchant",
-    amount_minor: order.amount_minor,
-    currency: order.currency,
-    challenge: String(req.body.siglume_challenge || ""),
-  });
-
-  res.json({ requirement });
-}));
-
-app.post("/siglume/webhook", express.raw({ type: "application/json" }), asyncRoute(async (req, res) => {
-  const header = String(req.headers["siglume-signature"] || "");
-  const { event } = await verifyDirectRequestPaymentWebhook(
-    process.env.SIGLUME_WEBHOOK_SECRET!,
-    req.body,
-    header,
-  );
-
-  if (event.type === "direct_payment.confirmed") {
-    const challengeHash = String(event.data.challenge_hash || "");
-    const order = [...orders.values()].find((item) => item.siglume_challenge_hash === challengeHash);
-    if (order) {
-      order.siglume_payment_status = "paid";
-      order.siglume_requirement_id = event.data.requirement_id || event.data.direct_payment_requirement_id;
-    }
-  }
-
-  res.status(204).send();
-}));
-
-app.use((error: unknown, _req: express.Request, res: express.Response, _next: express.NextFunction) => {
-  const message = error instanceof Error ? error.message : "internal_error";
-  res.status(500).json({ error: message });
-});
-
-app.listen(port);
+import express from "express";
+import {
+  createDirectRequestPaymentChallenge,
+  DirectRequestPaymentClient,
+  verifyDirectRequestPaymentWebhook,
+} from "@siglume/direct-request-payment";
+
+const app = express();
+const port = Number(process.env.PORT || 3000);
+const merchantKey = process.env.SIGLUME_DIRECT_PAYMENT_MERCHANT || "example_merchant";
+
+// Use JSON for normal routes. Use raw body only on the webhook route.
+app.use((req, res, next) => {
+  if (req.path === "/siglume/webhook") {
+    next();
+    return;
+  }
+  express.json()(req, res, next);
+});
+
+const orders = new Map<string, any>();
+
+const asyncRoute =
+  (handler: express.RequestHandler): express.RequestHandler =>
+  (req, res, next) => {
+    Promise.resolve(handler(req, res, next)).catch(next);
+  };
+
+app.post("/checkout/siglume/start", asyncRoute(async (req, res) => {
+  const orderId = String(req.body.order_id || "");
+  const order = orders.get(orderId);
+  if (!order) {
+    res.status(404).json({ error: "order_not_found" });
+    return;
+  }
+
+  order.payment_attempt = Number(order.payment_attempt || 0) + 1;
+  const challenge = await createDirectRequestPaymentChallenge({
+    merchant: merchantKey,
+    amount_minor: order.amount_minor,
+    currency: order.currency,
+    secret: process.env.SIGLUME_DIRECT_PAYMENT_CHALLENGE_SECRET!,
+    nonce: `${order.id}-attempt_${order.payment_attempt}`,
+  });
+
+  order.siglume_challenge_hash = challenge.challenge_hash;
+  order.siglume_payment_status = "pending";
+
+  res.json({
+    order_id: order.id,
+    amount_minor: order.amount_minor,
+    currency: order.currency,
+    siglume_challenge: challenge.challenge,
+  });
+}));
+
+app.post("/checkout/siglume/pay", asyncRoute(async (req, res) => {
+  const order = orders.get(String(req.body.order_id || ""));
+  if (!order) {
+    res.status(404).json({ error: "order_not_found" });
+    return;
+  }
+
+  // In production, obtain this from the authenticated buyer's Siglume session
+  // or a hosted Siglume payment confirmation flow. Do not use a merchant secret
+  // to charge a customer wallet.
+  const siglume = new DirectRequestPaymentClient({
+    auth_token: String(req.headers.authorization || "").replace(/^Bearer\s+/i, ""),
+  });
+
+  const requirement = await siglume.createPaymentRequirement({
+    merchant: merchantKey,
+    amount_minor: order.amount_minor,
+    currency: order.currency,
+    challenge: String(req.body.siglume_challenge || ""),
+  });
+
+  res.json({ requirement });
+}));
+
+app.post("/siglume/webhook", express.raw({ type: "application/json" }), asyncRoute(async (req, res) => {
+  const header = String(req.headers["siglume-signature"] || "");
+  const { event } = await verifyDirectRequestPaymentWebhook(
+    process.env.SIGLUME_WEBHOOK_SECRET!,
+    req.body,
+    header,
+  );
+
+  if (event.type === "direct_payment.confirmed") {
+    const challengeHash = String(event.data.challenge_hash || "");
+    const order = [...orders.values()].find((item) => item.siglume_challenge_hash === challengeHash);
+    if (order) {
+      order.siglume_payment_status = "paid";
+      order.siglume_requirement_id = event.data.requirement_id || event.data.direct_payment_requirement_id;
+    }
+  }
+
+  res.status(204).send();
+}));
+
+app.use((error: unknown, _req: express.Request, res: express.Response, _next: express.NextFunction) => {
+  const message = error instanceof Error ? error.message : "internal_error";
+  res.status(500).json({ error: message });
+});
+
+app.listen(port);

package/examples/setup-merchant.ts

@@ -0,0 +1,17 @@
+import { DirectRequestPaymentMerchantClient } from "@siglume/direct-request-payment";
+
+const merchant = new DirectRequestPaymentMerchantClient({
+  auth_token: process.env.SIGLUME_MERCHANT_AUTH_TOKEN,
+});
+
+const setup = await merchant.setupCheckout({
+  merchant: process.env.SIGLUME_DIRECT_PAYMENT_MERCHANT || "example_merchant",
+  display_name: process.env.SIGLUME_DIRECT_PAYMENT_DISPLAY_NAME || "Example Merchant",
+  billing_plan: process.env.SIGLUME_DIRECT_PAYMENT_PLAN || "launch",
+  billing_currency: process.env.SIGLUME_DIRECT_PAYMENT_BILLING_CURRENCY || "JPY",
+  webhook_callback_url: process.env.SIGLUME_DIRECT_PAYMENT_WEBHOOK_URL,
+  max_amount_minor: Number(process.env.SIGLUME_DIRECT_PAYMENT_BILLING_CAP_MINOR || 100000),
+  create_webhook_subscription: Boolean(process.env.SIGLUME_DIRECT_PAYMENT_WEBHOOK_URL),
+});
+
+console.log(JSON.stringify(setup, null, 2));

package/package.json

@@ -1,57 +1,71 @@
-{
-  "name": "@siglume/direct-request-payment",
-  "version": "0.1.0",
-  "description": "Merchant SDK for Siglume Direct Request Payment checkout integrations",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/taihei-05/siglume-direct-request-payment.git"
-  },
-  "type": "module",
-  "engines": {
-    "node": ">=18"
-  },
-  "sideEffects": false,
-  "main": "./dist/index.cjs",
-  "module": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": {
-        "types": "./dist/index.d.ts",
-        "default": "./dist/index.js"
-      },
-      "require": {
-        "types": "./dist/index.d.cts",
-        "default": "./dist/index.cjs"
-      }
-    },
-    "./package.json": "./package.json"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "files": [
-    "dist",
-    "docs",
-    "examples",
-    "README.md",
-    "LICENSE"
-  ],
-  "scripts": {
-    "build": "tsup",
-    "lint": "npm run typecheck",
-    "prepack": "npm run build",
-    "prepublishOnly": "npm run build",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "pack:check": "npm pack --json"
-  },
-  "devDependencies": {
-    "@types/node": "^20.16.5",
-    "tsup": "^8.3.0",
-    "typescript": "^5.6.3",
-    "vitest": "^2.1.8"
-  }
-}
+{
+  "name": "@siglume/direct-request-payment",
+  "version": "0.3.1",
+  "description": "Merchant SDK for Siglume Direct Request Payment checkout integrations",
+  "keywords": [
+    "siglume",
+    "payment",
+    "checkout",
+    "external-402",
+    "wallet",
+    "sdk"
+  ],
+  "license": "MIT",
+  "author": "Siglume Contributors",
+  "homepage": "https://github.com/taihei-05/siglume-direct-request-payment#readme",
+  "bugs": {
+    "url": "https://github.com/taihei-05/siglume-direct-request-payment/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/taihei-05/siglume-direct-request-payment.git"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "examples",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "lint": "npm run typecheck",
+    "prepack": "npm run build",
+    "prepublishOnly": "npm run build",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "pack:check": "npm pack --json"
+  },
+  "devDependencies": {
+    "@types/node": "^20.16.5",
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.8"
+  }
+}