Arvan Cloud Reseller for WordPress

StarCoach 2 Kilo Bananas

This project was built by StarCoach 2 Kilo Bananas for the Vibe-Coding hackathon at StarCoach. Arvan is an independent WordPress reseller plugin for selling Arvan cloud servers, content delivery network services, and cloud storage through a Persian, right-to-left customer experience.

The plugin is designed as a small commerce and provisioning layer between WordPress and Arvan's official APIs. It owns the catalog/quote/order/wallet/ledger state, calls Arvan only through a provider client, provisions or reconciles resources, exposes a customer panel, and gives administrators a control panel for keys, prices, services, finance, audit, and scheduled operations.

Competition context: This repository is a three-day hackathon prototype. It was produced quickly and contains known bugs, incomplete hardening, demo payment behavior, dependency assumptions, and operational edge cases. It is not recommended for production commerce, billing, or cloud provisioning without a security review, payment-gateway review, API-contract verification, backup/restore testing, and a complete operational runbook.

Team

Member	Role and background
Ali Emami	Team lead and full-stack developer; four years of specialized robotics experience and familiar with DevOps.
Mohammad Parsa Hosseini	Bachelor's student in Computer Engineering at Sharif University of Technology.
Parsa Abedi	Bachelor's student in Computer Engineering at the University of Tehran.

Project goal

The project explores how a WordPress site could offer a branded Arvan reseller experience without putting raw cloud credentials or billing logic directly in theme code. It aims to let an administrator:

• configure and test Arvan API credentials for Cloud, CDN, Storage, and Storage S3 operations;
• define licensed branding, margin, tax, and CDN management fees;
• publish product, pricing, legal, and customer-panel pages automatically;
• receive live catalogs and immutable quote snapshots;
• take a wallet-backed order through a demo payment path;
• provision a cloud server, CDN domain, or storage bucket;
• reconcile, suspend, resume, terminate, and meter services;
• track orders, payments, wallet movements, invoices, jobs, usage, restrictions, and audit events.

Products and provider boundaries

Product	Provider boundary	Implemented purpose
Cloud server	Arvan IaaS API under https://napi.arvancloud.ir/ecc/v1	Region, flavor, image, network catalog; quote; server creation; power off/on; existence check; deletion.
CDN	Arvan CDN API under https://napi.arvancloud.ir/cdn/4.0	Plan catalog, domain/DNS service, CDN features, DNS records, cache actions, usage/PAYG concepts, and service lifecycle.
Cloud storage	Arvan Storage API under https://storage.arvanapis.ir	Bucket catalog/snapshot, bucket creation, temporary user creation, S3 policy setup, one-time secret delivery, and bucket deletion.

The provider client uses active, tested, encrypted keys, validates the product/endpoint combination, adds the required authorization header, applies timeouts, maps common HTTP failures, and records response metadata without intentionally storing raw credentials.

What was added during the hackathon

The commit history shows the plugin progressing from a bootstrap into a full reseller prototype:

• Plugin bootstrap: WordPress activation/deactivation hooks, namespaced PHP classes, versioned database install, roles/capabilities, rewrite rules, admin/customer page creation, and a scheduled worker.
• Commerce core: Catalog, quotes, quote hashes, Rial-safe money calculations, margin/tax breakdowns, wallet reservation, demo payment, order state, service creation, provisioning jobs, idempotency keys, settlement/release, and ledger entries.
• Arvan API integration: Cloud, CDN, and Storage request paths, catalogs, quotes, provisioning, reconcile/existence checks, suspend/resume, termination, storage temporary-user flow, and API error normalization.
• Customer experience: Independent Persian/RTL pages, product landing pages, pricing and termination pages, a customer panel, order/payment pages, service list, wallet, one-time secret reveal, and service controls.
• Admin control plane: Setup wizard, keys, orders, services, CDN management, customers, finance, pricing, audit, settings, demo allowance/reset, page recreation, and manual sync actions.
• CDN console: Service snapshot, plan/billing model, DNS records, zone import, BIND export, cache actions, feature flags, security/performance settings, usage metrics, and PAYG demonstration controls.
• Storage safety: Master-key encryption with XChaCha20-Poly1305, encrypted provider keys/secrets, temporary-user cleanup on partial failure, bucket policy application, one-time customer secret reveal, and audit records.
• Debt and restriction policy: A minute scheduler tracks negative wallet balances, stages product-specific restrictions, suspends or terminates when the policy allows it, logs manual-action cases when the provider lacks a supported command, and restores settled services where possible.
• Content layer: Generated product/pricing/legal pages and three evergreen VPS articles, with local assets for the landing, plans, CDN, panel, legal, and blog surfaces.
• Testing and contracts: PHP syntax/unit/static/coding-standard scripts, contract hash verification for official Arvan API specifications, an install smoke test, and Playwright browser tests.

Commit-derived milestones

Commit	Observed milestone
18750ad	Created the initial repository.
87db3cf	Bootstrapped the WordPress plugin entry point.
6e07fb4	Added the main plugin architecture, Commerce, Database, ArvanClient, security, scheduler, contracts, tests, and initial README.
81802cd	Expanded admin/frontend surfaces and added hero/card assets for the product experience.
f29c103	Added pricing/legal/panel/blog assets, metadata, templates, and broader admin/client/commerce behavior.
0d39a7d	Added characters, product polish, and additional Cloud/CDN/Storage admin/frontend changes.
5311f20	Added CDN-specific visual sections and extended CDN/admin/client/commerce behavior.
71147f8	Refined frontend, panel, blog styling, and plugin/frontend integration at the time of writing.

Installation and five-step setup

Requirements

• WordPress 6.8 or newer.
• PHP 8.3 through 8.5.
• A database supported by the WordPress installation.
• PHP Sodium, HTTP, multibyte, and internationalization support.
• HTTPS in any environment that handles credentials or customer data.
• An external WordPress cron runner every minute.
• Valid, least-privilege Arvan keys for the products that are enabled.
• A securely configured ARVAN_RESELLER_MASTER_KEY for encryption.

Setup flow

The admin wizard is intentionally gated. Sales should remain disabled until all setup checks pass:

1. Encryption and connectivity: define the master key and test the required Arvan endpoints/keys.
2. License token: verify a high-entropy reseller token against the local password-hash list or a host-provided hash list. The raw token is not stored in the repository.
3. Brand and operator settings: configure the licensed reseller name/branding and operator settings.
4. Pricing policy: set margin and tax as basis points out of 10,000 and set the CDN setup/management fees in Rial.
5. Page and scheduler readiness: create/publish the Cloud, CDN, Storage, Pricing, and Termination pages, enable the product navigation, and verify the scheduled worker.

Generate a 32-byte master key outside the repository:

php -r "echo base64_encode(random_bytes(32)), PHP_EOL;"

Define the resulting base64 value in the host configuration as ARVAN_RESELLER_MASTER_KEY. Never put it in the database, source control, logs, screenshots, or support tickets.

Run WordPress cron from the host rather than relying only on visitor traffic:

* * * * * cd /path/to/wordpress && wp cron event run --due-now --quiet

Customer routes and REST routes

The plugin registers Persian rewrite routes independent of the active theme:

Route	Purpose
/فروش-ابری/	Product landing/entry page.
/پنل-مشتری/	Customer panel.
/پنل-مشتری/<view>/	Customer panel sub-view.
/پرداخت/	Payment flow.

It also registers the following REST routes under /wp-json/arvan-reseller/v1:

• GET /health — admin-capability-protected readiness data.
• GET /catalog/{cloud|cdn|storage} — public catalog lookup with optional region.
• POST /quote/{cloud|cdn|storage} — authenticated quote generation from a product configuration.

Sensitive lifecycle operations remain behind WordPress authentication, capabilities, nonce checks, and customer ownership checks in the admin/frontend handlers.

Commerce and money flow

Quote and snapshot

The quote layer validates the selected product configuration, reads the relevant catalog or pricing snapshot, calculates the base price, margin, tax, setup fee, management fee, billing model, and usage policy, and returns a SHA-256 quote hash. CDN prices record a source, sync timestamp, and snapshot hash. Storage pricing uses a stored snapshot and becomes stale-aware; an old or unverified snapshot must not silently become a fresh public price.

Amounts are represented as integer Rial values. Money::breakdown() applies basis-point rates with integer-safe arithmetic. The customer UI may display Toman, but database and ledger amounts remain Rial to avoid floating-point money errors.

Wallet and demo payment

The current payment path is intentionally a test path:

1. An order is created with the quote hash and configuration snapshot.
2. The wallet is locked and checked for available balance (balance_rial - reserved_rial).
3. The order amount is reserved and a ledger entry is written.
4. A demo wallet payment is created with is_demo = 1; it does not charge a real gateway.
5. The order enters provisioning and a unique job/operation key is created.
6. On success, the reservation is settled and the service/order become active.
7. On failure, the reservation is released and the failure is audited.

There is no real payment gateway in this competition build. A real gateway must implement the PaymentGatewayInterface, verify callbacks safely, support idempotency, and be reviewed before any public sale.

Provisioning and one-time secrets

Provisioning is idempotent through service UUIDs, operation keys, job unique keys, and database checks. The Commerce layer calls the provider client and persists external IDs/names, status, configuration, billing model, and metadata. Secrets returned by a provider are encrypted before storage. For storage, a temporary user can be created, a bucket policy can be applied with S3 signing, and partial failures attempt to delete temporary resources.

Customers can reveal a service secret only for a service they own. The encrypted payload is decrypted under a database lock, returned once, then removed and marked with secret_revealed_at. This is a safety measure, not a substitute for a mature secret-management system.

Scheduler, usage, and debt policy

arvan_reseller_tick runs every minute. The worker updates its heartbeat, processes pending jobs, syncs storage when due, prepares restrictions for negative wallets, executes due restrictions, and tries to restore settled services.

The product policy is explicit and product-specific:

Product	Restriction examples in the prototype
Cloud	Network cut after two hours, suspend after 48 hours, terminate after seven days.
CDN	Suspend after 24 hours, DNS disable after 14 days.
Storage	Write cut after 24 hours, read cut after 48 hours, terminate after 14 days.

If the Arvan API does not provide a safe operation for a stage, the scheduler records a manual-action state rather than pretending the restriction succeeded. CDN usage is modeled as metered PAYG/add-on usage; the prototype intentionally does not add an hourly charge to a PAYG CDN service.

Security design

• Provider keys are encrypted with XChaCha20-Poly1305 using the host-provided master key.
• Raw license tokens are verified against hashes; raw tokens should not be stored.
• Admin actions use WordPress capabilities and nonces.
• Customer operations validate logged-in ownership and service/order relationships.
• Request/action rate limiting uses WordPress transients for selected operations.
• Audit metadata redacts fields such as authorization, API keys, secrets, passwords, tokens, and encrypted values.
• Remote IPs in audit logs are HMAC-hashed with the WordPress auth salt.
• Arvan requests use allow-listed product endpoints and map invalid key, permission, timeout, TLS, unavailable, and rate-limit failures.
• Uninstall is conservative by default; data deletion requires the explicit arvan_delete_on_uninstall option.

These controls are useful prototype safeguards but are not a complete security certification.

Database tables

The plugin installs versioned prefixed tables through dbDelta():

Table	Purpose
keys	Encrypted product credentials, endpoints, region, test state, and priority.
prices	Price/snapshot records.
orders	Quote-backed customer orders and lifecycle status.
payments	Demo/payment records and references.
wallets	Balance, reserved balance, and debt timestamps.
ledger	Immutable-ish wallet movements with idempotency keys.
services	Provisioned resource state, external IDs, billing, metadata, and secrets.
operations	Provision/reconcile operation attempts and idempotency.
usage	Metered usage and charge calculation payloads.
invoices	Recurring/management charges.
restrictions	Debt-policy stages and execution states.
jobs	Scheduled/background operations and retry state.
audit	Administrative and lifecycle audit events.

Technology inventory

Area	Technology or implementation
Platform	WordPress 6.8+, PHP 8.3–8.5, namespaced object-oriented plugin.
Provider APIs	Arvan IaaS, CDN 4.0, Storage APIs, WordPress HTTP API, AWS Signature V4-style S3 signing helper.
Persistence	WordPress $wpdb, custom prefixed tables, dbDelta(), options/transients.
Commerce	Integer Rial money object, basis-point margin/tax, wallet reservation, ledger, invoices, idempotency keys.
Security	Sodium XChaCha20-Poly1305, password-hash license verification, capabilities, nonces, transient rate limit, redacted audit.
Frontend	PHP templates, RTL CSS, vanilla JavaScript, WordPress rewrite/REST hooks, local visual assets.
Scheduling	WordPress Cron with a custom every-minute schedule and external cron recommendation.
Testing	PHPUnit, PHPStan, PHPCS/WPCS, contract hash check, install smoke test, Playwright with axe-core.
Tooling	Composer, npm, official API contract manifest, PHP configuration files.

Repository layout

• arvan.php — plugin metadata, constants, includes, activation/deactivation, and boot hook.
• includes/class-plugin.php — lifecycle, rewrites, REST routes, pages, menus, seeded blog content, and plugin composition.
• includes/class-arvan-client.php — Arvan API boundaries, catalogs, quotes, provisioning, lifecycle, snapshots, and normalization.
• includes/class-commerce.php — orders, payments, wallets, ledger, provisioning, usage, invoices, cancellation, and secrets.
• includes/class-admin.php — setup wizard and admin menus/actions.
• includes/class-frontend.php — customer pages, panels, product views, and public rendering.
• includes/class-database.php — schema/version install.
• includes/class-security.php — encryption, license checks, audit redaction, and rate limiting.
• includes/class-scheduler.php — jobs, sync, restrictions, restoration, and heartbeat.
• templates/ — owned public/blog templates.
• assets/ — CSS, JavaScript, product/panel/blog images, and brand assets.
• contracts/manifest.json — hashes of the official API contracts used for verification.
• tests/ — unit, contract, integration smoke, and browser test entry points.

Tests and local checks

composer install
composer run بررسی-نحو
composer run آزمون-واحد
composer run تحلیل-ایستا
composer run معیار-کدنویسی
composer run آزمون-قرارداد

npm install
npm run آزمون-مرورگر

The Composer script names are Persian because they were authored for the team's Persian WordPress workflow. Live tests require isolated accounts, least-privilege keys, explicit cost limits, and guaranteed cleanup. Never run provisioning tests with a production account.

Known limitations and production warning

This plugin was written in three days. The payment implementation is a demo wallet path and does not collect real money. The license check is local and is not a remote entitlement service. API contracts can change, official pricing can become stale, the scheduler depends on WordPress cron execution, and partial failures may still require manual reconciliation. There is no complete tax, refund, dispute, financial reconciliation, or production-grade secret-management workflow.

Do not install this build on a production WordPress site or connect it to live cloud credentials without an independent review. Use a disposable WordPress instance and non-production Arvan account, rotate keys after testing, verify every API contract, test rollback and cleanup, and add a real payment gateway only after it has been designed and reviewed.

License and ethical use

The team's original hackathon work is covered by the accompanying LICENSE. Using, copying, redistributing, deploying, selling, or publishing the team's code without written permission from the developers is unauthorized and unethical. Please ask the developers for permission before using any part of the repository. Third-party libraries, WordPress, Arvan names/logos, and external API specifications retain their own rights and licenses.

See ABOUT.md for a compact project profile.