s.plings.io Gateway Service

Created: Tue 29 Jul 2025 06:49:39 CEST
Updated: Wed 06 May 2026 17:14:18 CEST - Phase 1 naming migration: clarified transport-agnosticism (QR / NFC / RFID treated equally); resolved that the Gateway handles the browser path while native apps call the GraphQL API directly; “one way in” clarified as the GraphQL API, not the Gateway
Updated: Mon 15 Jun 2026 - Firewall Function documented as implemented: per-isolate scope of the in-memory rate limiter made explicit; input validation and redirect-destination allowlisting added
Updated: Sun 21 Jun 2026 - added 1D Code128 transport t=c to the transport table; noted that Code128 scans bypass the Gateway entirely (native app → GraphQL API direct).
Document Version: 1.4 - 1D Code128 transport documented
Security Classification: Public Technical Documentation
Target Audience: Frontend Developers, Backend Developers, System Architects
Author: Paul Wisén

Overview

The s.plings.io service is the Plings-Gateway — an intelligent routing service that acts as the entry point for the browser path: any scan where the user does not have (or is not using) a native Plings app. QR codes, NFC tags, and RFID tags all encode the same s.plings.io URL, so the same logic handles every transport on this path. The Gateway provides four critical functions: intelligent routing, centralized logging, security firewall, and future-proof evolution.

Where the Gateway sits

There are two paths from a physical scan to a result:

The unified “one way in” of the Plings system is the GraphQL API at api.plings.io, not the Gateway. The Gateway is one specific client of that API, optimized for the case where there is no native app to do its own resolution.

Transport-Agnosticism (QR · NFC · RFID · Code128)

On the browser path, the Gateway treats all scan transports identically. The URL parameter t (see URL Structure) signals which transport the scan came through, but routing decisions are made on object state and user context — not on transport. Switching from a printed QR sticker to an NFC tag requires no change to the Gateway’s routing logic.

Code128 (1D barcode) scans bypass the Gateway entirely. A 1D Code128 barcode encodes a compact <prefix>-<path> token that is not a URL, so the stock iOS Camera does not follow it as a link. Native apps decode the symbol, parse the token, and call the GraphQL API directly with transport t=c. The Gateway never sees a 1D scan; the transport value c is analytics-only metadata the API records. See URL Structure — 1D Code128 Payload for the full format.

The same URL format is also what native apps parse locally before calling the API for QR and NFC, so transport abstraction holds across all paths.

Why s.plings.io?

Physical identifiers are permanent infrastructure — once printed on millions of stickers (or embedded in NFC tags), they cannot be changed. The Gateway layer provides:

• Intelligent Routing: route scans to different services based on object status
• Evolution Freedom: add new services without reprinting physical identifiers
• Security Layer: protect downstream services from malicious scans
• Analytics Hub: centralized scan tracking across all destinations

The Four Core Functions

1. Routing Function - Intelligent Context-Aware Routing

Routes scans based on:

• Object Status: FOR_SALE → market.plings.io, FOR_RENT → rent.plings.io
• User Context: Owner scans vs. public scans
• Service Availability: Handle outages with fallback routing
• Geographic Location: Route to nearest service endpoint

2. Logger Function - Centralized Analytics & Tracking

Every scan is logged before any redirect:

• Universal Tracking: All scans logged regardless of destination
• Lost & Found Support: GPS location tracking (with consent)
• Privacy Compliant: Anonymous scan logging options
• Cross-Service Analytics: Independent of destination service

3. Firewall Function - Security & Protection Layer

Protects all services with:

• Rate Limiting: 100 scans/minute per IP — answered with HTTP 429 + Retry-After. Current implementation note: the counter is in-memory and therefore per edge isolate, not a global guarantee; it dampens single-source bursts on top of Vercel’s platform-level DDoS protection. A shared store (e.g. Upstash Redis) is the upgrade path for a hard global limit.
• DDoS Protection: Edge-level protection (Vercel platform layer)
• Input Validation: Strict format validation of all scan parameters (see URL Structure); invalid scans redirect to the scan-error page with fixed detail tokens
• Malicious URL Filtering: Backend-provided redirect destinations are allowlisted to HTTPS plings.io / *.plings.io; anything else is discarded and the scan falls back to local routing

4. Freedom to Evolve - Future-Proof Architecture

Enables system evolution:

• New Service Addition: Add services without changing QR codes
• A/B Testing: Experiment with different user flows
• Global Updates: Instant routing logic changes
• Graceful Degradation: Handle service outages intelligently

URL Structure

Incoming Scan URL Format

The same URL format is used for all scan transports (QR / NFC / RFID):

https://s.plings.io?t=<type>&i=<instance>&p=<path>&cp=<class_pointer>

Parameters

Verification Strategy

The Gateway implements a hybrid verification approach using cached manufacturer public keys:

1. Edge Verification: Class pointers verified using cached public keys
2. API Verification: Instance keys verified via backend API
3. Performance: ~70% reduction in backend load
4. Security: Maintains cryptographic verification integrity

For detailed verification flow, see Verification Strategy.

Routing Examples

Object for Sale

Input:  https://s.plings.io?t=q&i=ABC123&p=4.2.3.3.6
Output: https://market.plings.io/item?oid=obj-123&ikey=ABC123&path=4.2.3.3.6&src=scan

Unknown Generic Tag

Input:  https://s.plings.io?t=q&i=XYZ789&p=1.1.1.1.1
Output: https://plings.io/create?ikey=XYZ789&path=1.1.1.1.1&src=scan

Lost Object

Input:  https://s.plings.io?t=q&i=DEF456&p=2.2.2.2.2
Output: https://plings.io/found?oid=obj-456&ikey=DEF456&path=2.2.2.2.2&src=scan

Integration with Services

All Plings services receive enriched parameters from the Gateway:

• oid: Object ID (when known)
• ikey: Original instance key
• path: HD wallet path
• src: Source tracking (always ‘scan’)
• Additional context parameters as needed

Security Considerations

• Rate Limiting: Per IP, per identifier, per user
• Input Validation: Strict parameter validation
• HTTPS Only: All redirects use secure protocols
• Privacy: GPS data only with explicit consent

Performance Requirements

• Response Time: <100ms at 95th percentile
• Global Availability: Edge deployment in all regions
• Uptime: 99.9% availability target
• Throughput: 10,000 scans/second capacity

Related Documentation

• URL Structure & Parameters
• Verification Strategy
• Routing Logic
• Implementation Guide
• Security Model