PrestaShop Bridge V1

Secure skill pack for operating a PrestaShop 9 Bridge through a stable, signed, asynchronous API contract.

Security Scan

The package appears to be a legitimate PrestaShop Bridge contract, but there are important inconsistencies (missing referenced files, mismatched registry metadata, and a hard-coded HMAC secret in the validator) that you should resolve before trusting or deploying it.

Purpose & Capability

The SKILL.md, README, openapi.yaml, and schemas consistently describe a PrestaShop Bridge that legitimately requires secrets (OAuth client credentials, JWT keys, HMAC secret), Redis and MySQL access. However the registry-level 'Requirements' summary (top of the provided metadata) lists no required environment variables or config paths, which is inconsistent with _meta.json, docs, and the validator that all declare many required runtime variables. This mismatch between published metadata and the package contents is a red flag (either metadata was omitted or the package may be incomplete).

Instruction Scope

The SKILL.md instructions themselves are narrowly scoped to API usage, signing, and polling and explicitly forbid direct DB/filesystem access. That is coherent for a bridge contract. However the included validator script reads local files and expects a .env file and examples.http; the SKILL.md and docs instruct maintainers to run the validator and to verify exact HMAC examples. The validator also embeds a fixed SECRET used to compute example HMACs, which leaks an example signing secret inside the package and increases the chance someone will accidentally reuse it.

Install Mechanism

This is an instruction-only pack with no install spec and no external downloads — low installation risk. The only code files are small validators/eval scripts included for local verification.

Credentials

The package (in _meta.json and docs) declares many sensitive environment variables (OAUTH_CLIENT_SECRET, JWT_PRIVATE_KEY_PATH, HMAC_SECRET_CURRENT/PREVIOUS, DATABASE_URL, REDIS_DSN, etc.), which are proportionate to the stated bridge purpose. The problem is the registry-level requirements shown to the platform were empty; that inconsistency could cause a user to install without providing required secrets. Additionally, validators/validate_examples.py embeds a long hex SECRET constant — this is a hard-coded secret inside the repo (not a platform requirement) and could be mistaken for a runtime secret or misused; it's poor hygiene and may aid attackers if reused.

Persistence & Privilege

The skill does not request permanent platform presence (always:false) and does not request elevated platform privileges. It does not modify other skills. Autonomous invocation remains enabled (normal), but there is no combination of 'always' plus broad credentials here.

What to consider before installing

Do not install or use this pack until you confirm a few things: 1) The registry/manifest shown to the platform should list the same required environment variables declared inside _meta.json and docs—if the platform shows none, ask the publisher why. 2) Verify the package actually includes .env.bridge.example and examples.http referenced by the validator; those files appear to be missing from the provided manifest. 3) Inspect validators/validate_examples.py: it contains a hard-coded SECRET used to compute example HMACs — treat this as an example secret only and ensure you never deploy or reuse it in production. 4) Confirm the package origin and homepage/source (source is unknown here); prefer packages with a verifiable upstream repo or publisher. 5) If you plan to deploy, ensure secrets (oauth client secret, HMAC secrets, JWT private key, DATABASE_URL, REDIS_DSN) are provided through secure secret storage and not committed. 6) Ask the publisher to fix metadata inconsistencies (registry requirements, included example files) and to remove or clearly label any embedded test secrets before trusting automated agents with these credentials.

PrestaShop Bridge V1 is a secure operational contract for AI agents and Python handlers that need to interact with a PrestaShop 9 store through a stable interface. It standardizes OAuth2 authentication, HMAC request signing, rate limiting, asynchronous writes, idempotency, and durable job polling.

Operating model

• Reads are synchronous.
• Writes are asynchronous.
• Redis is used only for Messenger transport and temporary HTTP idempotency cache.
• MySQL is the source of truth for job status, business idempotency, and failed jobs.
• A 202 Accepted response means only that a job was accepted for processing. It never means business success.

Capabilities

get_product

• method: GET
• endpoint: /v1/products/{id}
• sync: true
• scope: bridge:read
• params:
  • id integer, required
• success: 200

get_order

• method: GET
• endpoint: /v1/orders/{id}
• sync: true
• scope: bridge:read
• params:
  • id integer, required
• success: 200

get_job_status

• method: GET
• endpoint: /v1/jobs/{jobId}
• sync: true
• scope: bridge:read
• note: job status is read from MySQL, not from Redis
• success: 200

update_product

• method: POST
• endpoint: /v1/jobs/products/update
• sync: false
• scope: bridge:write
• idempotency: X-Request-ID required
• payload:
  • product_id
  • updates.price_ht
  • updates.stock_delta
  • updates.seo
  • options.skip_reindex
• success: 202

import_products

• method: POST
• endpoint: /v1/jobs/products/import
• sync: false
• scope: bridge:write
• idempotency: request id required and stable batch_id
• payload:
  • batch_id
  • items
  • options
• constraints:
  • maximum 50 items
  • maximum payload size 10MB
• success: 202

update_order_status

• method: POST
• endpoint: /v1/jobs/orders/status
• sync: false
• scope: bridge:write
• idempotency: X-Request-ID required
• payload:
  • order_id
  • new_status
  • notify_customer
  • tracking_number
• success: 202

Security

Required headers on protected routes

• Authorization: Bearer {jwt_rs256_token}
• X-Request-ID: {uuid_v4}
• X-Timestamp: {unix_seconds}
• X-Signature: {hmac_sha256_hex}
• Content-Type: application/json
• Accept: application/json

Compression

• gzip recommended above 1024 bytes
• gzip required above 32768 bytes

OAuth2

• flow: client_credentials
• token endpoint: /oauth/token
• JWT algorithm: RS256
• TTL: 3600
• scopes:
  • bridge:read
  • bridge:write

HMAC

String to sign:

METHOD + "\n" + URI + "\n" + TIMESTAMP + "\n" + REQUEST_ID + "\n" + BODY_SHA256

Exact example:

• method: POST
• uri: /v1/jobs/products/update
• timestamp: 1710950400
• request id: f47ac10b-58cc-4372-a567-0e02b2c3d479
• body sha256: 37abd647733fbd18a3f11fb5a082fe59c62719d9fe833aec96b28ccea36b70ba
• signature: 448e251d1c71078b07a10baf4094fd2686bcebef97761c4729a921f71798554c

Response handling

• 200 OK: synchronous read success or completed idempotent replay.
• 202 Accepted: job accepted only. Always poll /v1/jobs/{jobId}.
• 400 Bad Request: schema validation failed.
• 401 Unauthorized: JWT missing, invalid, or expired.
• 403 Forbidden: invalid HMAC, invalid timestamp window, or insufficient scope.
• 409 Conflict: idempotency conflict or known failed replay.
• 422 Unprocessable Entity: valid JSON but impossible business transition.
• 429 Too Many Requests: wait for Retry-After.
• 500 Internal Server Error: unexpected server failure.
• 503 Service Unavailable: service degraded or Redis unavailable.

Absolute refusal rules

• Never report business success immediately after a 202.
• Never modify TTC price directly. Only HT price may be changed.
• Never delete a product that has associated orders.
• Never access the database or filesystem directly.
• Never send payloads larger than 10MB.
• Never perform heavy writes synchronously.
• Never reuse an X-Request-ID for a different business intention within 24 hours.

Pre-deployment checks

• Verify JWT issuance and validation with RS256 only.
• Verify the exact HMAC example in examples.http.
• Verify schema validation for all request bodies.
• Verify Redis-backed idempotency replay behavior.
• Verify MySQL-backed job polling after Redis restart.
• Verify idempotent handlers under at-least-once delivery.