wc-licensed-product-client/CLAUDE.md

License-Client for WooCommerce Licensed Product Plugin

Author: Marco Graetsch Author URL: https://src.bundespruefstelle.ch/magdev Author Email: magdev3.0@gmail.com Repository URL: https://src.bundespruefstelle.ch/magdev/wc-licensed-product-client Issues URL: https://src.bundespruefstelle.ch/magdev/wc-licensed-product-client/issues Package-Name: magdev/wc-licensed-product-client

Project Overview

This composer package implements a Client for the WooCommerce Licensed Product Plugin. It uses the REST API as described in tmp/openapi.json to activate, validate and check the status of licenses.

Features

• Easy integration in licensed software packages
• Defines a PHP constant if a licensed is valid or not
• Obfuscate the security critical code parts using plain PHP tools as best as possible

Key Fact: 100% AI-Generated

This project is proudly "vibe-coded" using Claude.AI - the entire codebase was created through AI assistance.

Temporary Roadmap

Note for AI Assistants: Clean this section after the specific features are done or new releases are made. Effective changes are tracked in CHANGELOG.md. Do not add completed versions here - document them in the Session History section at the end of this file.

Known Bugs

No known bugs at the moment

Technical Stack

• Language: PHP 8.3.x
• PHP-Standards: PSR-3, PSR-4, PSR-6, PSR-18
• Coding-Style: Symfony
• HTTP-Client-Library: symfony/http-client
• Dependency Management: Composer
• OpenAPI Description: tmp/openapi.json

---

For AI Assistants:

When starting a new session on this project:

1. Read this CLAUDE.md file first
2. Semantic versioning follows the MAJOR.MINOR.BUGFIX pattern
3. Check git log for recent changes
4. Verify you're on the dev branch before making changes
5. Run composer install if vendor/ is missing
6. Test changes before committing
7. Follow commit message format with Claude Code attribution
8. Update this session history section with learnings
9. Always update the README.md on related changes
10. Keep changes in a single CHANGELOG.md
11. Follow markdown linting rules (see below)

Always refer to this document when starting work on this project.

Markdown Linting Rules

When editing CLAUDE.md or other markdown files, follow these rules to avoid linting errors:

1. MD031 - Blank lines around fenced code blocks: Always add a blank line before and after fenced code blocks, even when they follow list items. Example of correct format:

   • Item label:

     (blank line here) ```php code example ``` (blank line here)

2. MD056 - Table column count: Table separators must have matching column counts and proper spacing. Use consistent dash lengths that match column header widths.

3. MD009 - No trailing spaces: Remove trailing whitespace from lines

4. MD012 - No multiple consecutive blank lines: Use only single blank lines between sections

5. MD040 - Fenced code blocks should have a language specified: Always add a language identifier to code blocks (e.g., txt, bash, php). For shortcode examples, use txt.

6. MD032 - Lists should be surrounded by blank lines: Add a blank line before AND after list blocks, including after bold labels like **Attributes:**.

7. MD034 - Bare URLs: Wrap URLs in angle brackets (e.g., <https://example.com>) or use markdown link syntax [text](url).

8. Author section formatting: Use a heading (### Name) instead of bold (**Name**) for the author name to maintain consistent document structure.

---

Session History

2026-01-22 - Version 0.0.1

Completed:

• Initialized composer project of type library
• Configured package metadata (name, description, license, author)
• Set up PSR-4 autoloading for Magdev\WcLicensedProductClient namespace
• Added symfony/http-client ^7.0 as HTTP client dependency
• Created project structure (src/, tests/)
• Added README.md, CHANGELOG.md, and .gitignore
• Initialized git repository on dev branch
• Pushed initial commit to origin

Learnings:

• OpenAPI spec (tmp/openapi.json) defines 3 POST endpoints: /validate, /status, /activate
• API base path: {baseUrl}/wp-json/wc-licensed-product/v1
• Git remote configured via SSH: ssh://git@src.bundespruefstelle.ch:2022/magdev/wc-licensed-product-client.git

2026-01-22 - Version 0.1.0

Completed:

• Created LicenseClientInterface as public API contract
• Implemented LicenseClient with PSR-3 logging and PSR-6 caching support
• Added DTO classes: LicenseInfo, LicenseStatus, ActivationResult
• Added LicenseState enum for license status values (active, inactive, expired, revoked)
• Created comprehensive exception hierarchy (10 exception classes)
• Added PSR dependencies: psr/log ^3.0, psr/cache ^3.0, psr/http-client ^1.0
• Updated README with usage examples for basic usage, logging, caching, and exception handling
• Merged dev to main branch

Learnings:

• Architecture follows separation: Interface (public API) → Client (implementation) → DTOs (data) → Exceptions (errors)
• Cache keys use SHA256 hashes of license keys to avoid exposing sensitive data
• LicenseClient designed for obfuscation: all sensitive logic contained in single class
• Symfony HttpClient works well with PSR interfaces via symfony/http-client-contracts
• Keep a Changelog format allows duplicate headings per version (MD024 warning can be ignored)

2026-01-22 - Version 0.1.0 (Security Layer)

Completed:

• Added PHPUnit ^11.0 test framework with 66 tests total
• Implemented SecureLicenseClient with response signature verification
• Created ResponseSignature class for HMAC-SHA256 signing/verification
• Created StringEncoder for XOR-based string obfuscation
• Created IntegrityChecker for source file hash verification
• Added SignatureException and IntegrityException for security errors
• Documented server-side implementation in docs/server-implementation.md
• Merged all changes to main branch

Learnings:

• Response signature verification (HMAC) is more secure than code obfuscation alone
• Per-license key derivation prevents cross-license signature reuse
• Timestamp validation (5-minute tolerance) prevents replay attacks
• Server must sign responses with matching algorithm for client verification
• IntegrityChecker normalizes line endings for cross-platform hash consistency
• StringEncoder uses XOR with expanded key for simple obfuscation (not encryption)
• PHPUnit 11 uses PHP 8 attributes (#[Test], #[CoversClass]) instead of annotations