@algopayoracle/oracle-sdk 1.0.0

package/src/adapters/razorpay.js

@@ -0,0 +1,177 @@
+/**
+ * AlgoPay Oracle SDK — Razorpay Adapter
+ *
+ * Implements the PaymentAdapter interface for Razorpay.
+ * Normalizes Razorpay events into PaymentEvents consumed by AlgoPayClient.
+ */
+
+"use strict";
+
+const crypto = require("crypto");
+const https  = require("https");
+const { ProviderAuthError, ConfigError } = require("../errors");
+
+class RazorpayAdapter {
+  /**
+   * @param {object} opts
+   * @param {string}    opts.keySecret     - Razorpay key secret
+   * @param {string}    [opts.keyId]       - Razorpay key ID (required for createOrder)
+   * @param {object}    [opts.orderStore]  - shared order store (set/get/consume/delete async interface)
+   * @param {string}    [opts.defaultAction]
+   */
+  constructor({ keySecret, keyId, orderStore, defaultAction = "unlock" } = {}) {
+    if (!keySecret) throw new ConfigError("RazorpayAdapter: keySecret is required");
+    this.keySecret     = keySecret;
+    this.keyId         = keyId;
+    this.orderStore    = orderStore || null;
+    this.defaultAction = defaultAction;
+  }
+
+  // ── parseWebhook ───────────────────────────────────────────────────────────
+
+  /**
+   * Parse and verify a Razorpay server-side webhook.
+   * Implements PaymentAdapter.parseWebhook.
+   * Returns null on any failure (invalid sig, wrong event, bad body).
+   *
+   * @param {Buffer|string} rawBody
+   * @param {string}        signature - X-Razorpay-Signature header
+   * @returns {import("../index").PaymentEvent|null}
+   */
+  parseWebhook(rawBody, signature) {
+    if (!signature) return null;
+
+    const expected = crypto.createHmac("sha256", this.keySecret).update(rawBody).digest();
+    const received = Buffer.from(signature, "hex");
+    if (expected.length !== received.length) return null;
+    if (!crypto.timingSafeEqual(expected, received)) return null;
+
+    let body;
+    try { body = JSON.parse(rawBody.toString()); } catch { return null; }
+
+    if (body.event !== "payment.captured") return null;
+
+    const p = body?.payload?.payment?.entity;
+    if (!p?.id || !p?.amount) return null;
+
+    return {
+      payment_id: p.id,
+      amount:     Math.round(p.amount / 100),
+      currency:   (p.currency || "INR").toUpperCase(),
+      action:     this.defaultAction,
+      provider:   "razorpay",
+    };
+  }
+
+  // ── parseClientPayment ────────────────────────────────────────────────────
+
+  /**
+   * Verify a Razorpay client-side payment and return a PaymentEvent.
+   * Amount is resolved from the server-side orderStore — never from the request.
+   *
+   * @param {object} opts
+   * @param {string} opts.razorpay_order_id
+   * @param {string} opts.razorpay_payment_id
+   * @param {string} opts.razorpay_signature
+   * @param {string} [opts.action]
+   * @throws {ProviderAuthError} on invalid signature or missing order
+   * @returns {import("../index").PaymentEvent}
+   */
+  async parseClientPayment({ razorpay_order_id, razorpay_payment_id, razorpay_signature, action }) {
+    if (!razorpay_order_id || !razorpay_payment_id || !razorpay_signature) {
+      throw new ProviderAuthError("razorpay", "missing required payment fields");
+    }
+
+    const expected = crypto
+      .createHmac("sha256", this.keySecret)
+      .update(`${razorpay_order_id}|${razorpay_payment_id}`)
+      .digest();
+    const received = Buffer.from(razorpay_signature, "hex");
+
+    if (expected.length !== received.length || !crypto.timingSafeEqual(expected, received)) {
+      throw new ProviderAuthError("razorpay", "payment signature mismatch");
+    }
+
+    if (!this.orderStore) {
+      throw new ConfigError("RazorpayAdapter: orderStore is required for parseClientPayment — amount cannot be trusted from client");
+    }
+
+    // Amount MUST come from the server-side order record, not the request body
+    // This is a synchronous path so we return a promise that resolves the event
+    // Callers must await this if orderStore.consume is async
+    if (!this.orderStore) {
+      throw new ConfigError("RazorpayAdapter: orderStore is required for parseClientPayment — amount cannot be trusted from client");
+    }
+    const record = await this.orderStore.consume(razorpay_order_id);
+    if (!record) {
+      throw new ProviderAuthError("razorpay", `order "${razorpay_order_id}" not found or already used — call createOrder first`);
+    }
+    return {
+      payment_id: razorpay_payment_id,
+      amount:     record.amount,
+      currency:   record.currency,
+      action:     action || this.defaultAction,
+      provider:   "razorpay",
+    };
+  }
+
+
+  // ── createOrder ───────────────────────────────────────────────────────────
+
+  /**
+   * Create a Razorpay order and store the authoritative amount server-side.
+   *
+   * @param {object}  opts
+   * @param {number}  opts.amount    - integer, in rupees
+   * @param {string}  [opts.currency]
+   * @returns {Promise<{ order_id, amount, currency, key_id }>}
+   */
+  async createOrder({ amount, currency = "INR" }) {
+    if (!this.keyId)                                    throw new ConfigError("RazorpayAdapter: keyId is required for createOrder");
+    if (!Number.isInteger(amount) || amount <= 0)       throw new ConfigError("RazorpayAdapter: amount must be a positive integer");
+
+    const body = JSON.stringify({
+      amount:   amount * 100,
+      currency: currency.toUpperCase(),
+      receipt:  "algopay_" + Date.now(),
+    });
+
+    const auth = Buffer.from(`${this.keyId}:${this.keySecret}`).toString("base64");
+
+    const order = await new Promise((resolve, reject) => {
+      const req = https.request({
+        hostname: "api.razorpay.com",
+        path:     "/v1/orders",
+        method:   "POST",
+        headers:  { "Content-Type": "application/json", Authorization: `Basic ${auth}` },
+      }, res => {
+        let data = "";
+        res.on("data", c => (data += c));
+        res.on("end", () => {
+          try { resolve(JSON.parse(data)); }
+          catch { reject(new ConfigError("RazorpayAdapter: failed to parse order creation response")); }
+        });
+      });
+      req.on("error", err => reject(new ConfigError(`RazorpayAdapter: order request failed — ${err.message}`)));
+      req.write(body);
+      req.end();
+    });
+
+    if (!order.id) {
+      throw new ProviderAuthError("razorpay", `order creation failed: ${JSON.stringify(order)}`);
+    }
+
+    if (this.orderStore) {
+      await this.orderStore.set(order.id, { amount, currency: currency.toUpperCase() });
+    }
+
+    return {
+      order_id: order.id,
+      amount,
+      currency: currency.toUpperCase(),
+      key_id:   this.keyId,
+    };
+  }
+}
+
+module.exports = { RazorpayAdapter };

package/src/adapters/stripe.js

@@ -0,0 +1,77 @@
+/**
+ * AlgoPay Oracle SDK — Stripe Adapter
+ *
+ * Bridges Stripe payment events to AlgoPay PaymentEvents.
+ * The credential layer (APC-1 / oracle signing) is provider-agnostic.
+ * This adapter is the provider-specific translation layer for Stripe.
+ *
+ * Requires the 'stripe' npm package:
+ *   npm install stripe
+ *
+ * Usage:
+ *   const adapter = new StripeAdapter({ webhookSecret: process.env.STRIPE_WEBHOOK_SECRET });
+ *   const event   = adapter.parseWebhook(req.rawBody, req.headers["stripe-signature"]);
+ *   if (!event) return res.status(401).end();
+ *   const result  = await client.verifyAndCommit(event);
+ */
+
+const { ProviderAuthError, ConfigError } = require("../errors");
+
+class StripeAdapter {
+  /**
+   * @param {object} opts
+   * @param {string} opts.webhookSecret  - Stripe webhook signing secret (whsec_...)
+   * @param {string} [opts.secretKey]    - Stripe secret key (sk_test_... or sk_live_...)
+   * @param {string} [opts.defaultAction]
+   */
+  constructor({ webhookSecret, secretKey, defaultAction = "unlock" } = {}) {
+    if (!webhookSecret) throw new ConfigError("StripeAdapter: webhookSecret is required");
+    this.webhookSecret = webhookSecret;
+    this.defaultAction = defaultAction;
+
+    // Lazy-load stripe — not a hard SDK dependency
+    try {
+      const Stripe  = require("stripe");
+      this.stripe   = new Stripe(secretKey || process.env.STRIPE_SECRET_KEY || "");
+    } catch {
+      this.stripe = null;
+    }
+  }
+
+  /**
+   * Parse and verify a Stripe webhook event.
+   * Stripe's SDK uses a timing-safe comparison internally.
+   * Returns null on non-payment events, throws ProviderAuthError on bad sig.
+   *
+   * @param {Buffer} rawBody    - raw request body (Buffer, not parsed)
+   * @param {string} signature  - stripe-signature header value
+   * @returns {object|null}     PaymentEvent or null
+   */
+  parseWebhook(rawBody, signature) {
+    if (!this.stripe) throw new ConfigError("StripeAdapter: install 'stripe' npm package");
+
+    let event;
+    try {
+      // Stripe constructEvent uses timing-safe HMAC internally
+      event = this.stripe.webhooks.constructEvent(rawBody, signature, this.webhookSecret);
+    } catch (e) {
+      throw new ProviderAuthError("stripe", e.message);
+    }
+
+    // Only handle successful payment intents
+    if (event.type !== "payment_intent.succeeded") return null;
+
+    const intent = event.data.object;
+    if (!intent?.id || !intent?.amount) return null;
+
+    return {
+      payment_id: intent.id,
+      amount:     Math.round(intent.amount / 100),   // cents → base unit
+      currency:   (intent.currency || "usd").toUpperCase(),
+      action:     this.defaultAction,
+      provider:   "stripe",
+    };
+  }
+}
+
+module.exports = { StripeAdapter };

package/src/apc1.js

@@ -0,0 +1,112 @@
+/**
+ * AlgoPay Credential Standard v1 (APC-1)
+ *
+ * APC-1 is the standardized proof format produced by AlgoPay Oracle.
+ * It is provider-agnostic: the same credential format is produced regardless
+ * of whether the payment came from Razorpay, Stripe, UPI, or any other gateway.
+ *
+ * canonical_id is the replay key used on-chain (provider:payment_id).
+ * It must appear in the credential so verifiers can reconstruct the signed message.
+ *
+ * Schema (v1):
+ *   apc            "1"                    — format version
+ *   payment_id     string                 — original provider-issued ID (display only)
+ *   canonical_id   string                 — namespaced replay key: "provider:payment_id"
+ *   amount         integer                — fiat amount in currency base units
+ *   currency       string                 — ISO 4217 (INR, USD, EUR...)
+ *   action         string                 — intended Web3 action
+ *   timestamp      integer                — unix seconds when oracle signed
+ *   oracle_address string                 — Algorand address of signing oracle
+ *   signature      string                 — base64 Ed25519 signature over canonical message
+ *   chain          "algorand"
+ *   network        "localnet"|"testnet"|"mainnet"
+ *   app_id         integer|null           — deployed AlgoPayOracle App ID
+ *   provider       string                 — payment rail label
+ */
+
+"use strict";
+
+const APC_VERSION   = "1";
+const SUPPORTED_APC = new Set(["1"]);
+
+/**
+ * Wrap an internal signed proof as an APC-1 credential.
+ * canonical_id is always included — it is the on-chain replay key.
+ *
+ * @param {object} proof - output of OracleSigner.sign()
+ * @param {object} [meta] - { network, appId, provider }
+ * @returns {object} APC-1 credential
+ */
+function toAPC1(proof, { network = "testnet", appId = null, provider } = {}) {
+  return {
+    apc:            APC_VERSION,
+    payment_id:     proof.payment_id,
+    canonical_id:   proof.canonical_id,   // the signed replay key — MUST be present
+    amount:         proof.amount,
+    currency:       proof.currency,
+    action:         proof.action,
+    timestamp:      proof.timestamp,
+    oracle_address: proof.oracle_address,
+    signature:      proof.signature,
+    chain:          "algorand",
+    network,
+    app_id:         appId ?? null,
+    provider:       provider ?? proof.provider ?? "unknown",
+  };
+}
+
+/**
+ * Validate APC-1 credential structure and field types.
+ * Does NOT verify the cryptographic signature — use ProofVerifier for that.
+ *
+ * @param {object} cred
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+function validateAPC1Structure(cred) {
+  const errors = [];
+
+  if (!SUPPORTED_APC.has(String(cred.apc)))         errors.push(`unsupported apc version: "${cred.apc}" (supported: ${[...SUPPORTED_APC].join(", ")})`);
+  if (!cred.payment_id || typeof cred.payment_id !== "string")
+                                                     errors.push("payment_id must be a non-empty string");
+  if (!cred.canonical_id || typeof cred.canonical_id !== "string")
+                                                     errors.push("canonical_id must be a non-empty string");
+  if (!Number.isInteger(cred.amount) || cred.amount <= 0)
+                                                     errors.push("amount must be a positive integer");
+  if (typeof cred.currency !== "string" || cred.currency.length !== 3)
+                                                     errors.push("currency must be a 3-character ISO code");
+  if (!cred.action || typeof cred.action !== "string")
+                                                     errors.push("action must be a non-empty string");
+  if (!Number.isInteger(cred.timestamp))             errors.push("timestamp must be an integer");
+  if (typeof cred.oracle_address !== "string" || cred.oracle_address.length !== 58)
+                                                     errors.push("oracle_address must be a valid Algorand address (58 chars)");
+  if (!cred.signature || typeof cred.signature !== "string")
+                                                     errors.push("signature must be a base64 string");
+  if (cred.chain !== "algorand")                     errors.push("chain must be 'algorand'");
+  if (!["localnet", "testnet", "mainnet"].includes(cred.network))
+                                                     errors.push("network must be localnet, testnet, or mainnet");
+
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Check if a verifier supports this APC-1 version.
+ * Allows callers to gate on version before attempting verification.
+ *
+ * @param {object} cred
+ * @returns {boolean}
+ */
+function isSupportedVersion(cred) {
+  return SUPPORTED_APC.has(String(cred?.apc));
+}
+
+/**
+ * Check if an APC-1 proof is expired.
+ * @param {object} cred
+ * @param {number} [maxAgeSecs] - default 300 (5 min)
+ */
+function isExpired(cred, maxAgeSecs = 300) {
+  const now = Math.floor(Date.now() / 1000);
+  return now - cred.timestamp > maxAgeSecs;
+}
+
+module.exports = { APC_VERSION, SUPPORTED_APC, toAPC1, validateAPC1Structure, isSupportedVersion, isExpired };

package/src/errors.js

@@ -0,0 +1,96 @@
+/**
+ * AlgoPay Oracle SDK — Error Classes
+ *
+ * All SDK errors extend AlgoPayError so callers can catch by base type.
+ *
+ * Usage:
+ *   const { AlgoPayError, ProofExpiredError } = require("@algopayoracle/oracle-sdk/errors");
+ *   try { await client.verifyAndCommit(...) }
+ *   catch (e) {
+ *     if (e instanceof ProofExpiredError) { ... }
+ *     if (e instanceof OracleNotRegisteredError) { ... }
+ *   }
+ */
+
+class AlgoPayError extends Error {
+  constructor(message, code) {
+    super(message);
+    this.name    = "AlgoPayError";
+    this.code    = code || "ALGOPAY_ERROR";
+  }
+}
+
+/** Amount is below the contract's MIN_AMOUNT threshold */
+class InsufficientAmountError extends AlgoPayError {
+  constructor(amount, minAmount) {
+    super(`Amount ${amount} is below minimum ${minAmount}`, "INSUFFICIENT_AMOUNT");
+    this.name      = "InsufficientAmountError";
+    this.amount    = amount;
+    this.minAmount = minAmount;
+  }
+}
+
+/** Proof timestamp is older than PROOF_VALIDITY_SECS */
+class ProofExpiredError extends AlgoPayError {
+  constructor(timestamp, now) {
+    const age = now - timestamp;
+    super(`Proof expired — signed ${age}s ago (max 300s)`, "PROOF_EXPIRED");
+    this.name      = "ProofExpiredError";
+    this.timestamp = timestamp;
+    this.age       = age;
+  }
+}
+
+/** oracle_pubkey is not in the contract's oracle registry */
+class OracleNotRegisteredError extends AlgoPayError {
+  constructor(address) {
+    super(`Oracle ${address} is not registered in the contract`, "ORACLE_NOT_REGISTERED");
+    this.name    = "OracleNotRegisteredError";
+    this.address = address;
+  }
+}
+
+/** payment_id has already been verified (replay attempt) */
+class ReplayError extends AlgoPayError {
+  constructor(paymentId) {
+    super(`payment_id "${paymentId}" has already been processed`, "REPLAY_DETECTED");
+    this.name      = "ReplayError";
+    this.paymentId = paymentId;
+  }
+}
+
+/** Ed25519 signature did not verify */
+class InvalidSignatureError extends AlgoPayError {
+  constructor() {
+    super("Signature verification failed", "INVALID_SIGNATURE");
+    this.name = "InvalidSignatureError";
+  }
+}
+
+/** Configuration is missing or invalid */
+class ConfigError extends AlgoPayError {
+  constructor(message) {
+    super(message, "CONFIG_ERROR");
+    this.name = "ConfigError";
+  }
+}
+
+/** Payment provider (Razorpay/Stripe) signature/HMAC check failed */
+class ProviderAuthError extends AlgoPayError {
+  constructor(provider, reason) {
+    super(`${provider} signature verification failed: ${reason}`, "PROVIDER_AUTH_ERROR");
+    this.name     = "ProviderAuthError";
+    this.provider = provider;
+  }
+}
+
+module.exports = {
+  AlgoPayError,
+  InsufficientAmountError,
+  ProofExpiredError,
+  OracleNotRegisteredError,
+  ReplayError,
+  InvalidSignatureError,
+  ConfigError,
+  ProviderAuthError,
+};