Files
wc-licensed-product-client/CLAUDE.md

184 lines
7.6 KiB
Markdown
Raw Normal View History

# 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
### Version 0.1.1
No changes at the moment.
### Version 0.2.0
No changes 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
- OpenAPI spec (tmp/openapi.json) updated to v0.3.2 with signature header definitions
### 2026-01-23 - Client Documentation
**Completed:**
- Created comprehensive `docs/client-implementation.md` documentation
- Documented all classes: LicenseClient, SecureLicenseClient, DTOs, Exceptions, Security classes
- Added integration guides for: Basic PHP, WordPress plugins, Laravel, Symfony
- Documented constructor parameters, method signatures, and return types
- Added complete exception hierarchy reference with error codes
- Included best practices section for production use
- Added API reference with endpoints and request/response formats
- Added troubleshooting section for common issues
- Updated README.md with documentation links section
**Learnings:**
- Client documentation complements server documentation for complete integration guide
- Integration examples for major PHP frameworks help adoption
- Error code mapping to exception classes aids programmatic error handling