SPARXSTAR™ Helios Trust

SPARXSTAR Helios is the Edge Agreement Engine — a stateless, fail-closed evaluator that decides whether a specific request is allowed to proceed based on the alignment of four signals: Proof, ContextPulse, ResourceSensitivity, and Time.

Helios also provides edge-authenticated login for WordPress Multisite via a Cloudflare Worker gateway. The Worker validates login attempts and issues short-lived signed tokens that the WordPress origin trusts to create sessions. This keeps the login surface off the public internet and allows security controls (rate limiting, bot detection) to run at the edge.

Helios serves frontend users only. WordPress authentication (wp-admin) is for staff. Helios must not create WordPress sessions for frontend users.

The following files provide the full technical specs for the project:

• the full technical specs
• the Platform Integrity Map
• the SPARXSTAR Platform Overview
• the Implementation Tracker

Authentication Flow

Browser
   ↓
POST /custom-login
   ↓
Cloudflare Worker
   ↓  Authorization: Bearer <AUTH_SECRET_KEY>
POST /wp-json/helios/v1/preauth
   ↓
WordPress validates credentials (wp_authenticate)
   ↓
Worker issues short-lived HS256 JWT (5 min, jti, iss, sub)
   ↓  Authorization: Bearer <AUTH_SECRET_KEY>  +  X-Worker-Auth: <jwt>
POST /wp-json/helios/v1/login
   ↓
WordPress verifies JWT (signature, expiry ±30 s skew, jti replay check)
   ↓
wp_set_auth_cookie() — session cookies returned to browser
   ↓
User logged in

Agreement Engine — Two-Zone Rule

Helios operates across two zones. The decision is always exactly one of ALLOW_EDGE | ALLOW_ORIGIN | STEP_UP | DENY. There is no null, no default pass.

Zone A (Edge / Cloudflare Worker)
  L1 resource + all checks pass  → ALLOW_EDGE
  L2/L3 resource + all checks pass → ALLOW_ORIGIN (forward to origin)
  KV unavailable (any level)     → DENY
  Any verification failure       → DENY or STEP_UP

Zone B (Origin / WordPress)
  Issues the final authoritative YES (ALLOW_ORIGIN)
  An edge DENY cannot be overridden here. Ever.

The evaluator checks five steps in order:

1. Proof — ContextPulse present and structurally valid
2. PulseVerifier — 6 checks: HMAC, expiry, clock-skew, device_id, trust_level, trust_score bounds
3. KV revocation — pulse not revoked (KV unavailable = DENY, fail-closed)
4. StepUpPolicy — L3 always requires step-up; L2 requires step-up when trust_score < 0.7
5. Two-Zone routing — L1 → ALLOW_EDGE; L2/L3 → ALLOW_ORIGIN

Security Model

Layer	Control
Cloudflare Worker	Intercepts login; issues short-lived JWT
Shared secret	Authorization: Bearer restricts both REST endpoints to the Worker
JWT token	HS256, 5-minute TTL, iss: helios-worker enforced
Clock-skew tolerance	±30 seconds accepted (exp + CLOCK_SKEW)
Replay protection	One-time jti (UUID v4) tracked in WordPress transients (360 s)
Multisite validation	is_user_member_of_blog() enforced before cookie issuance
Fail-closed config	HELIOS_WORKER_SECRET must be defined; plugin fails at startup if missing/empty

All authentication responses include Cache-Control: no-store.

Important deployment rule: /wp-json/helios/v1/preauth and /wp-json/helios/v1/login must never be exposed directly to the public internet without the Worker in front. Direct calls fail because every request must carry the Worker authentication secret. If you bypass the Worker you also lose edge-layer rate limiting and bot protection.

Threat Model

The Helios architecture defends against:

• Brute-force / credential stuffing — /custom-login sits behind Cloudflare rate limiting; WordPress is never hit directly.
• Token replay — Each JWT carries a single-use jti consumed on first use.
• Clock-drift bypass — A ±30-second skew window is accepted; tokens expired longer than 30 seconds ago are rejected.
• Cross-site session creation (Multisite) — is_user_member_of_blog() ensures a user authenticated on site A cannot obtain cookies for site B.
• Accidental misconfiguration — Bootstrap throws at startup if HELIOS_WORKER_SECRET is undefined, preventing silent insecure deployment.

Deployment Requirements

1. WordPress (wp-config.php)

// Login Worker (required)
define( 'HELIOS_WORKER_SECRET', 'your-long-random-secret' );

// Agreement Engine (required when evaluating requests)
define( 'HELIOS_PULSE_SIGNING_KEY',  'your-32-char-minimum-key' );
define( 'HELIOS_CF_ACCOUNT_ID',      'your-cloudflare-account-id' );
define( 'HELIOS_CF_KV_NAMESPACE_ID', 'your-kv-namespace-id' );
define( 'HELIOS_CF_API_TOKEN',       'your-cloudflare-api-token' );

HELIOS_WORKER_SECRET must match AUTH_SECRET_KEY in the Cloudflare Worker. Agreement Engine constants are optional at startup — if absent, the REST controller is not registered and entry points throw \RuntimeException at call time.

2. Cloudflare Worker

Deploy the Helios Login Worker (src/worker/login-worker.js) to Cloudflare and configure two secrets:

wrangler deploy src/worker/login-worker.js --name sparxstar-helios-auth
wrangler secret put AUTH_SECRET_KEY   # same value as HELIOS_WORKER_SECRET
wrangler secret put WORDPRESS_URL     # e.g. https://your-wp-site.com

Secret	Description
AUTH_SECRET_KEY	Shared secret — must equal HELIOS_WORKER_SECRET
WORDPRESS_URL	Base URL of the WordPress origin (no trailing slash)

Full setup instructions (including screenshots of the Cloudflare dashboard and curl-based integration tests) are in docs/CLOUDFLARE_WORKER_SETUP.md.

3. Cloudflare Rate Limiting (recommended)

Create a rate-limiting rule to protect the login endpoint:

Path:   /custom-login
Method: POST
Limit:  5 requests per minute per IP
Action: Block

4. Reverse-proxy cache bypass

If Varnish or another caching layer sits in front of WordPress, ensure Helios endpoints bypass the cache:

if (req.url ~ "^/wp-json/helios/") {
    return (pass);
}

These endpoints must never be cached.

Development Scorecard

Current build state against the Helios Agreement Engine Spec v1.0 and SPARXSTAR Platform Integrity Map v1.0.

Sprint	Module	Status
1	Agreement Engine Core (PHP + TypeScript)	✅ Complete
2	Substrate Import (Ouroboros DTOs/Enums/Exceptions)	⏳ Blocked — awaiting sparxstar-ouroboros-integrity package
3	Sirus Context Integration	🔄 In progress — Sirus PR #30 open
4	Governance / Mehns Integration	⏳ Not started
5	Dheghom Persistence Integration	⏳ Not started

Hard Rules Compliance

Rule	Status
Fail-closed — missing/invalid input = DENY	✅
AgreementResult resolves to exactly one of ALLOW_EDGE|ALLOW_ORIGIN|STEP_UP|DENY	✅
Edge MUST NEVER return ALLOW_EDGE for L2 or L3	✅
Edge DENY cannot be overridden by origin	✅
KV unavailability = DENY for ALL sensitivity levels	✅
Helios MUST NEVER grant Level 3 access at the edge	✅
Audit log is append-only — no UPDATE, no DELETE	✅
Signing keys read from PHP constants only — never DB/WP options	✅
ContextPulse MUST NOT be stored in localStorage	✅
Helios MUST NOT interact with WordPress authentication	⚠️ Worker_Auth_Controller calls wp_authenticate() on behalf of the Cloudflare Login Worker — access is gated behind HELIOS_WORKER_SECRET, so frontend browsers cannot call it directly. Architectural refactoring tracked in Sprint 4.
Helios MUST NOT create WordPress sessions for frontend users	⚠️ Worker_Auth_Controller::handle_login() calls wp_set_auth_cookie() as part of the Worker-mediated login flow. The endpoint is Worker-only (Bearer secret required), but the resulting WP auth cookie constitutes a WordPress session. Architectural refactoring tracked in Sprint 4.
PHP and TypeScript produce identical decisions for identical inputs	✅
Level 3 step-up MUST NOT use email 2FA	⏳ Step-up challenge not yet implemented

See docs/IMPLEMENTATION_TRACKER.md for the full sprint-by-sprint breakdown.

Features

✨ Modern PHP Development

• PHP 8.2+ with PSR-4 autoloading
• WordPress VIP coding standards
• PHPStan static analysis (Level 5)
• PHPCS with WordPress standards
• Rector for automated refactoring
• PHPUnit for unit testing

🎨 Frontend Tooling

• ESLint for JavaScript linting
• Stylelint for CSS linting
• Terser for JS minification
• clean-css for CSS minification
• Automated build pipeline (src/ → assets/)

🧪 Comprehensive Testing

• PHPUnit for PHP unit tests
• Jest for JavaScript unit tests
• Playwright for E2E testing
• Puppeteer for browser automation
• Accessibility testing with axe-core

🚀 CI/CD & Automation

• GitHub Actions workflows
• Automated releases with version bumping
• Security scanning (CodeQL, dependency audits)
• Accessibility validation
• Code quality checks
• Automated asset building

📦 Release Management

• Automated versioning from Git tags
• Asset minification and optimization
• i18n POT file generation
• Checksum generation (MD5, SHA256)
• Respects .distignore for clean distributions

Quick Start

1. Clone and Install

git clone https://github.com/Starisian-Technologies/sparxstar-helios-trust.git
cd sparxstar-helios-trust
composer install
npm install

2. Build Assets

npm run build

3. Run Tests

composer run test:php
npm test

4. Activate in WordPress

• Copy plugin to WordPress plugins directory
• Activate through WordPress admin

Documentation

• Public API Reference - REST endpoints, PHP classes, filters, and constants for integration
• Cloudflare Worker Setup - Create and configure the Cloudflare Worker
• Implementation Tracker - Spec vs build status and sprint scoreboard
• Build & Development Guide - Detailed build instructions
• Tooling Configuration - Configure all dev tools
• Local Development - Setup local environment
• First Contribution - Contributing guide

Development Commands

PHP

composer run lint:php          # Check PHP code style
composer run fix:php           # Auto-fix PHP issues
composer run analyze:php       # Run PHPStan analysis
composer run test:php          # Run PHPUnit tests
composer run refactor:php      # Preview Rector changes
composer run refactor:php:fix  # Apply Rector refactoring

JavaScript & CSS

npm run lint              # Lint JS & CSS
npm run lint:js          # Lint JavaScript only
npm run lint:css         # Lint CSS only
npm run format           # Format with Prettier
npm test                 # Run Jest tests
npm run test:e2e         # Run Playwright E2E tests

Building

npm run build            # Build all assets
npm run build:js         # Minify JS (src/js → assets/js)
npm run build:css        # Minify CSS (src/css → assets/css)
npm run makepot          # Generate translation file

Project Structure

├── src/
│   ├── helios/
│   │   ├── Agreement/           # Agreement Engine (PHP origin implementation)
│   │   │   ├── DTOs/            # ContextPulse (provisional — owned by Ouroboros)
│   │   │   ├── Enums/           # AgreementResult, ResourceSensitivity, TrustLevel
│   │   │   ├── Exceptions/      # ContextBootException, TokenValidationException
│   │   │   ├── AgreementEvaluator.php
│   │   │   ├── AuditLog.php
│   │   │   ├── EntryPoints.php
│   │   │   ├── KVRevocationClient.php
│   │   │   ├── PulseVerifier.php
│   │   │   └── StepUpPolicy.php
│   │   ├── Admin/               # WordPress admin UI (Security Dashboard, Session Manager)
│   │   ├── Auth/                # Session management, 2FA engine
│   │   ├── Client/              # HeliosClient (implements HeliosClientInterface)
│   │   ├── Contracts/           # HeliosClientInterface, GovernanceTokenInterface, SirusClientInterface
│   │   ├── Gatekeeper/          # Login route interception, frontend forms
│   │   ├── Http/                # REST controllers
│   │   │   ├── Agreement_Controller.php  # POST /helios/v1/agreement/evaluate
│   │   │   ├── Login_Controller.php      # [helios_login] shortcode + AJAX
│   │   │   ├── Session_Controller.php    # POST /helios/v1/admin/revoke-session
│   │   │   ├── TwoFactor_Controller.php  # POST /helios/v1/2fa/*
│   │   │   └── Worker_Auth_Controller.php # POST /helios/v1/preauth + /login
│   │   ├── Identity/            # HeliosIdentityContext value object
│   │   ├── Integrations/        # SirusAdapter (filter-based bridge to Sirus)
│   │   ├── Middleware/          # RequestGatekeeper
│   │   ├── Security/            # Event_Horizon_Bridge, Token_Manager, GovernanceToken
│   │   ├── Trust/               # TrustEngine (sole writer of trust state)
│   │   └── Helios_Bootstrap.php
│   ├── worker/
│   │   ├── src/                 # TypeScript edge implementation
│   │   │   ├── AgreementEvaluator.ts
│   │   │   ├── KVRevocationClient.ts
│   │   │   ├── PulseVerifier.ts
│   │   │   ├── StepUpPolicy.ts
│   │   │   └── types.ts
│   │   ├── index.ts             # Cloudflare Worker entry point
│   │   └── login-worker.js      # Cloudflare login Worker
│   └── includes/
│       └── Autoloader.php       # PSR-4 autoloader (no Composer required)
├── data/
│   └── shared-test-vectors.json # Cross-language test vectors (PROVISIONAL_MIRROR)
├── docs/
│   ├── PUBLIC_API.md            # Public endpoints, classes, filters, and constants
│   ├── IMPLEMENTATION_TRACKER.md
│   └── CLOUDFLARE_WORKER_SETUP.md
├── tests/
│   └── phpunit/helios/          # PHPUnit tests for Agreement Engine
├── wrangler.toml                # Cloudflare Worker deployment config
└── tsconfig.worker.json         # TypeScript config for Worker build

Code Quality Standards

This template follows:

• PSR-4 autoloading
• PSR-12 coding style (where not conflicting with WordPress)
• WordPress® VIP standards (takes precedence over PSR where conflicts exist)
• WordPress® Coding Standards for WordPress-specific code
• Modern PHP practices (type declarations, readonly properties, etc.)

Linting Scope

Important: Linting and analysis tools only scan:

• Root-level PHP files (e.g., sparxstar-plugin-entry.php)
• src/ directory

Excluded from linting:

• vendor/ - Third-party PHP dependencies
• node_modules/ - Third-party JS dependencies
• assets/ - Generated/minified files
• tests/ - Test files (separate standards)
• data/, examples/, schemas/ - Non-code directories

Workflows

Continuous Integration

Runs on every push/PR:

• PHP linting (PHPCS) and analysis (PHPStan)
• JavaScript/CSS linting
• Unit tests (PHP & JS)
• Asset building verification
• Rector refactoring checks

Release Process

Triggered by pushing a version tag (v*):

1. Updates version in all files
2. Installs production dependencies
3. Builds and minifies assets
4. Generates translation files
5. Creates distribution ZIP
6. Generates checksums
7. Creates GitHub release

To release:

git tag -a v1.2.3 -m "Release 1.2.3"
git push origin v1.2.3

Security Scanning

Weekly and on-demand:

• Dependency audits (Composer & npm)
• CodeQL analysis
• Secret scanning
• Security best practices checks

Accessibility Testing

Automated accessibility validation:

• axe-core integration
• WCAG 2.1 compliance
• HTML validation

Configuration Files

File	Purpose
phpcs.xml.dist	PHP_CodeSniffer configuration
phpstan.neon.dist	PHPStan static analysis
phpunit.xml.dist	PHPUnit testing
rector.php	Rector refactoring rules
eslint.config.js	ESLint JavaScript linting
.stylelintrc.json	Stylelint CSS linting
jest.config.js	Jest testing configuration
playwright.config.js	Playwright E2E testing
.distignore	Files to exclude from releases
composer.json	PHP dependencies & scripts
package.json	Node dependencies & scripts

Requirements

• PHP 8.2 or higher
• WordPress 6.8 or higher
• Node.js 20 or higher
• Composer 2.x

License

Starisian Techologies Proprietary License - see LICENSE.md.

Copyright (c) 2026 Starisian Technologies (Max Barrett).

Credits

Created and maintained by Starisian Technologies™ .

Author: Max Barrett
Email: support@starisian.com

SPARXSTAR™ and Starisian Technologies™ are trademarks of Starisian Technologies. WordPress® is a registered trademark of WordPress Inc. Starisian Technologies is in now way affiliated with WordPress.

Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions
• 📧 Email: support@starisian.com

Contributing

See CONTRIBUTING.md for contribution guidelines and docs/FIRST_CONTRIBUTION.md for first-time contributors.