Smart Gallery QR

Smart Gallery QR is a WordPress plugin for structured experiences with workspace ownership, private media, password or account access, dynamic QR entry points, and a React-based administration screen.

Current capabilities

• Create workspaces and experiences, and add existing WordPress users to workspaces through the admin. Workspace managers can create group membership and recipient-bound or shared invitation links.
• Add collections, text/items, and encrypted image or PDF media. Editors can choose an accessible color palette and grid or list layout.
• Publish server-rendered experiences with public, unlisted, password, authenticated-user, member, group-policy, or private access. Group policies can combine a named group with a password.
• Generate dynamic QR links and download QR SVG files.
• Collect minimal view and QR-scan events without storing visitor IP addresses. A daily cron task removes events older than 90 days.
• Keep data on deactivation. Uninstall deletes data only when sgqr_delete_on_uninstall is set to 1.

This is an early implementation. The broader product specification in the project request includes full invitation delivery and lifecycle operations, commerce, restaurant, education, proofing, automation, storage drivers, full analytics, ten-language localization, and extensive browser/accessibility tests. Those features are not present yet; this repository is not ready for commercial distribution.

Requirements

• WordPress 6.4 or newer
• PHP 8.1 or newer with Sodium, Fileinfo, and GD
• Composer 2 for PHP dependencies
• Node.js and npm for admin assets

Development setup

composer install
npm ci
npm run build
composer test
composer analyse
npm run typecheck

For private uploads, set a random 32-byte key in wp-config.php or an environment-backed configuration:

define('SGQR_MASTER_KEY', getenv('SGQR_MASTER_KEY'));

The value must be Base64-encoded 32 random bytes. For example, generate one with php -r "echo base64_encode(random_bytes(32)), PHP_EOL;" and store it outside the plugin and database. Back up the key securely: losing it makes encrypted media unreadable. Rotating it requires a migration of existing objects.

Install a release ZIP or copy the plugin folder into wp-content/plugins/smart-gallery-qr, then activate. On activation, the plugin creates site-local sgqr_ tables using the active site's WordPress prefix and registers /sgqr/ routes. The admin screen is under Smart Gallery QR.

Architecture

• src/Infrastructure/Installer.php owns the initial schema and schema version.
• src/Infrastructure/Repository.php contains database access.
• src/Domain/Access.php evaluates access and signs short-lived password sessions. src/Domain/Policy.php validates group, user, password, authentication, membership, and UTC time rules.
• src/Infrastructure/PrivateStorage.php encrypts protected uploads using Sodium secretbox. Raw objects remain ciphertext even if the web server exposes the uploads directory.
• src/Presentation/RestController.php enforces workspace permissions on management routes.
• src/Presentation/PublicController.php resolves QR links, renders experiences, and authorizes media downloads.
• admin/ contains the TypeScript/React admin app; assets/ contains public styles.

The tables are site-local in multisite installations. Network-wide tenancy and cross-site data access are not implemented.

Security and privacy

Uploads are size-limited to 20 MiB and restricted to validated JPEG, PNG, WebP, AVIF, and PDF files. Media is encrypted before being stored under an opaque name. Access is checked for every media request. Password attempts are limited to five per 15 minutes per experience and IP; WordPress transients store only a hash-derived key. The event table stores event type, experience, optional QR, and timestamp. It does not store IP addresses or user agents.

Invitation links carry a random 256-bit token. Only its SHA-256 hash is stored. Managers can create up to 25 recipient-bound invitations at once or one shared link with a maximum use count; acceptance requires a signed-in WordPress user. Recipient-bound links match the account email. A database transaction consumes a use and grants the configured workspace role or group membership. The admin shows raw links only immediately after creation, for manual delivery.

The current media path decrypts whole files into memory, so the 20 MiB limit matters. A streaming encrypted storage format is needed before raising that limit. QR SVG downloads require a signed-in workspace member. Run HTTPS for production use.

Tests and known limits

composer test exercises access policy boundaries, password-session invalidation, encrypted storage tampering, and QR generation. composer analyse runs PHPStan level 3 with WordPress stubs. The isolated WordPress integration fixture exercises REST authorization, schema migration, group access, protected media, and public HTTP password/QR flows. Browser, full accessibility, load, cross-browser, and translation tests have not been run. The repo currently has English source strings and text-domain hooks, without the requested translated catalogs.

License

The repository includes the GNU General Public License version 2 text in LICENSE. The plugin metadata uses GPL-2.0.