@algopayoracle/oracle-sdk 1.0.0

package/src/utils/store.js

@@ -0,0 +1,119 @@
+/**
+ * AlgoPay Oracle — Pluggable Order Store
+ *
+ * Stores server-authoritative payment amounts keyed by gateway order ID.
+ * This is the source of truth for what amount was agreed server-side —
+ * the client cannot override it in the verify-payment path.
+ *
+ * CURRENT IMPLEMENTATION: In-memory (Map with TTL sweep).
+ *   - Fine for single-instance deployments and hackathon demos.
+ *   - Loses state on restart.
+ *   - Breaks in multi-instance / horizontally scaled deployments.
+ *
+ * ROADMAP — swap to a persistent backend by implementing the same interface:
+ *
+ *   class RedisOrderStore {
+ *     async set(id, data, ttlMs)  { await redis.set(id, JSON.stringify(data), "PX", ttlMs); }
+ *     async get(id)               { const v = await redis.get(id); return v ? JSON.parse(v) : null; }
+ *     async delete(id)            { await redis.del(id); }
+ *   }
+ *
+ *   class PostgresOrderStore {
+ *     async set(id, data, ttlMs)  { await db.query("INSERT INTO orders ..."); }
+ *     async get(id)               { const r = await db.query("SELECT ..."); return r.rows[0] ?? null; }
+ *     async delete(id)            { await db.query("DELETE FROM orders WHERE id=$1", [id]); }
+ *   }
+ *
+ * Usage:
+ *   const { createOrderStore } = require("./store");
+ *   const store = createOrderStore();
+ *   await store.set("order_123", { amount: 100, currency: "INR" });
+ *   const record = await store.get("order_123");
+ *   await store.delete("order_123");
+ */
+
+"use strict";
+
+const ORDER_TTL_MS = 30 * 60 * 1000;   // 30 minutes
+
+class InMemoryOrderStore {
+  constructor(ttlMs = ORDER_TTL_MS) {
+    this._map   = new Map();
+    this._ttlMs = ttlMs;
+
+    // Sweep expired entries every 10 minutes
+    this._sweep = setInterval(() => {
+      const now = Date.now();
+      for (const [id, record] of this._map) {
+        if (now - record._createdAt > this._ttlMs) this._map.delete(id);
+      }
+    }, 10 * 60 * 1000);
+
+    // Don't keep the process alive just for sweeping
+    if (this._sweep.unref) this._sweep.unref();
+  }
+
+  /**
+   * Store an order record.
+   * @param {string} id     - gateway order ID
+   * @param {object} data   - { amount, currency, ... }
+   */
+  async set(id, data) {
+    this._map.set(id, { ...data, _createdAt: Date.now() });
+  }
+
+  /**
+   * Retrieve an order record without consuming it.
+   * Returns null if not found or expired.
+   */
+  async get(id) {
+    const record = this._map.get(id);
+    if (!record) return null;
+    if (Date.now() - record._createdAt > this._ttlMs) {
+      this._map.delete(id);
+      return null;
+    }
+    const { _createdAt, ...data } = record;
+    return data;
+  }
+
+  /**
+   * Retrieve and delete an order record (single-use consume).
+   * Returns null if not found or expired.
+   */
+  async consume(id) {
+    const data = await this.get(id);
+    if (data) this._map.delete(id);
+    return data;
+  }
+
+  /**
+   * Delete an order record explicitly.
+   */
+  async delete(id) {
+    this._map.delete(id);
+  }
+
+  /** @returns {number} current number of stored orders */
+  size() { return this._map.size; }
+
+  destroy() { clearInterval(this._sweep); }
+}
+
+/**
+ * Factory — returns the configured store implementation.
+ *
+ * Currently always returns InMemoryOrderStore.
+ * Future: detect REDIS_URL or DATABASE_URL and return the appropriate adapter.
+ *
+ * @returns {InMemoryOrderStore}
+ */
+function createOrderStore(options = {}) {
+  if (process.env.REDIS_URL) {
+    // TODO: return new RedisOrderStore(process.env.REDIS_URL, options);
+    console.warn("[store] REDIS_URL detected but RedisOrderStore is not yet implemented — using in-memory store");
+  }
+  return new InMemoryOrderStore(options.ttlMs);
+}
+
+module.exports = { InMemoryOrderStore, createOrderStore };

package/src/validate.js

@@ -0,0 +1,105 @@
+/**
+ * AlgoPay Oracle SDK — Input Validation
+ *
+ * Lightweight schema validation for PaymentEvent and proof objects.
+ * No external dependencies — validates manually for zero overhead.
+ *
+ * Usage:
+ *   const { validatePaymentEvent } = require("@algopayoracle/oracle-sdk/validate");
+ *   const event = validatePaymentEvent(req.body);  // throws ConfigError on invalid input
+ */
+
+"use strict";
+
+const { ConfigError, InsufficientAmountError } = require("./errors");
+
+const MIN_AMOUNT       = 100;
+const MAX_PAYMENT_ID   = 256;   // chars
+const MAX_ACTION_LEN   = 64;
+const CURRENCY_RE      = /^[A-Z]{3}$/;   // ISO 4217: 3 uppercase letters
+
+/**
+ * Validate and normalise a PaymentEvent.
+ * Throws a typed error on the first validation failure.
+ *
+ * @param {object} input
+ * @returns {import("./index").PaymentEvent} normalised PaymentEvent
+ * @throws {ConfigError | InsufficientAmountError}
+ */
+function validatePaymentEvent(input) {
+  if (!input || typeof input !== "object") {
+    throw new ConfigError("PaymentEvent must be an object");
+  }
+
+  const { payment_id, amount, currency = "INR", action = "unlock", provider = "unknown" } = input;
+
+  // payment_id
+  if (!payment_id || typeof payment_id !== "string") {
+    throw new ConfigError("PaymentEvent.payment_id must be a non-empty string");
+  }
+  if (payment_id.length > MAX_PAYMENT_ID) {
+    throw new ConfigError(`PaymentEvent.payment_id must be ≤ ${MAX_PAYMENT_ID} characters`);
+  }
+
+  // amount — must be a safe positive integer
+  if (!Number.isSafeInteger(amount) || amount <= 0) {
+    throw new ConfigError("PaymentEvent.amount must be a positive integer");
+  }
+  if (amount < MIN_AMOUNT) {
+    throw new InsufficientAmountError(amount, MIN_AMOUNT);
+  }
+
+  // currency — 3-char ISO 4217 code
+  const normCurrency = String(currency).toUpperCase();
+  if (!CURRENCY_RE.test(normCurrency)) {
+    throw new ConfigError(`PaymentEvent.currency must be a 3-character ISO 4217 code (e.g. INR, USD), got: "${currency}"`);
+  }
+
+  // action
+  if (!action || typeof action !== "string") {
+    throw new ConfigError("PaymentEvent.action must be a non-empty string");
+  }
+  if (action.length > MAX_ACTION_LEN) {
+    throw new ConfigError(`PaymentEvent.action must be ≤ ${MAX_ACTION_LEN} characters`);
+  }
+
+  // timestamp sanity (if provided — internal proofs carry this)
+  if (input.timestamp !== undefined) {
+    const now = Math.floor(Date.now() / 1000);
+    if (!Number.isInteger(input.timestamp)) {
+      throw new ConfigError("PaymentEvent.timestamp must be an integer (unix seconds)");
+    }
+    if (input.timestamp > now + 60) {
+      throw new ConfigError(`PaymentEvent.timestamp is too far in the future: ${input.timestamp}`);
+    }
+  }
+
+  return {
+    payment_id,
+    amount,
+    currency: normCurrency,
+    action,
+    provider: typeof provider === "string" ? provider : "unknown",
+  };
+}
+
+/**
+ * Validate that a proof has all required fields for off-chain verification.
+ * Does not check the signature — use ProofVerifier for that.
+ *
+ * @param {object} proof
+ * @throws {ConfigError}
+ */
+function validateProofFields(proof) {
+  const required = ["payment_id", "canonical_id", "amount", "currency", "action", "timestamp", "app_id", "oracle_address", "signature"];
+  for (const field of required) {
+    if (proof[field] == null) {
+      throw new ConfigError(`Proof is missing required field: ${field}`);
+    }
+  }
+  if (proof.oracle_address.length !== 58) {
+    throw new ConfigError("Proof oracle_address must be a valid Algorand address (58 characters)");
+  }
+}
+
+module.exports = { validatePaymentEvent, validateProofFields, MIN_AMOUNT };