QR Code Ecosystem in Vibe Projects: Scan Login, Channel Codes, and Redemption

Two boundaries first, so this doesn't collide with existing guides on the site: the site's "Account System & Sessions" guide (vibe-project-auth-login-permissions-guide) covers "who the user is and how sessions work" — this article covers only one login method, QR-code login, as a complete engineering implementation. The site's "Share Links" guide (vibe-project-share-links-guide) covers "link permissions and revocation" — this one covers code generation, redemption, and analytics. Login, sharing, redemption — the QR code is three completely different engineering problems across these scenarios.

Many vibe projects use a QR code for the first time by just "drawing one": install an npm package, render it on the frontend, scan it, it opens a link, done. Only after launch do the real problems surface: login tickets get replayed, channel QR analytics don't add up, one coupon gets redeemed eight times, the code won't open inside WeChat. These pitfalls aren't in the "generation" step — they're in everything after it. This guide unpacks the full QR ecosystem in vibe projects: the scan-to-login flow, dynamic share codes and channel codes, redemption codes, generation options, and the WeChat ecosystem — each section with actionable implementation points, plus a genuinely runnable Node/Express scan-login demo at the end.

Four roles of QR codes in vibe projects

The same black-and-white square carries completely different responsibilities per scenario. Sort out which one you're building first:

• Identity credential (scan-to-login): the code holds a one-time ticket; scanning moves "the identity already logged in on the phone" to "the browser in front of the computer." The core is expiry and single-use; the code itself contains no sensitive information.
• Traffic entry (dynamic share codes / channel codes): the code holds a short link; scanning jumps somewhere. The core is parameter tracking and analytics: how many scans, which channel drove them, how conversion looks.
• Benefit voucher (redemption codes): the code is a coupon or a ticket. The core is one-code-one-use, replay protection, and offline redemption when needed.
• Information carrier (display codes): Wi-Fi passwords, contact cards, plain text. The core is error tolerance and aesthetics; generated once, valid long-term.

Security requirements differ wildly across the four: display codes can be generated statically and stay valid forever; redemption codes must be server-verified and single-use. Treating a login code like a display code (e.g., putting a raw userId in it) is the most common post-launch accident source.

The complete scan-to-login flow: six steps, none skippable

Scan-to-login replaces "typing a username and password" with "one scan from the phone." The full flow has six steps:

Step 1: ticket generation (web)

The user opens the login page in a desktop browser; the frontend asks the backend to generate a ticket. The backend does three things: generates a random ticketId (at least 128 bits of entropy — crypto.randomBytes(16) as a starting point); stores a record {ticketId, status: 'pending', createdAt} server-side; returns the ticketId and the scan URL. Note: the QR code contains a URL, never a token. The URL looks like https://yourapp.com/scan?t=<ticketId>; the app opens this page after scanning (or intercepts it into a native scan-result screen).

Ticket lifetime is typically 2 minutes. Shorter and users can't finish scanning; longer and the theft window grows. Expired tickets should transition to expired lazily on any lookup, so they never pile up.

Step 2: code display (web)

The frontend renders the scanUrl with a QR library. While displaying, it starts polling the ticket status. A 2-second interval is the empirical sweet spot: 1 second is too chatty, 5 seconds too slow (users wait after scanning). For production, upgrade to long polling, SSE, or WebSocket to push "scan succeeded" notifications under a second.

Step 3: app scans (phone)

The user scans with the already-logged-in app. The app extracts the ticketId and calls POST /api/qr/scan/:ticketId with the user's identity credentials. The backend verifies the ticket exists, is pending, and hasn't expired, then flips it to scanned. The key insight: scanning and confirming are two separate actions. Scanning only means "this phone claimed this ticket"; the web page now shows "scanned — please confirm on your phone," giving the user a chance to back out — in case the code was scanned under someone else's inducement.

Step 4: app confirms (phone)

The user sees a confirmation screen — "allow login on Chrome (IP/location)?" — and taps confirm. The backend requires the status to be scanned (blocking direct calls to the confirm endpoint that skip scanning), then issues the real login token (JWT or session), flipping the ticket to confirmed. Token issuance reuses your existing session system — scan-to-login is just a new pre-flow for issuing tokens, not a second session mechanism (that's exactly the division of labor with the account-system guide).

Step 5: poll / callback (web)

The web poll hits confirmed; the backend includes the token in the response and immediately destroys the ticket. The frontend stores the token via the normal login flow (httpOnly cookie or memory) and redirects home.

Step 6: expiry and single-use (throughout)

Three iron rules: tickets expire after 2 minutes, dead on expiry; tokens are issued exactly once — the ticket is destroyed on pickup; confirm-endpoint idempotency is enforced by the state machine — calling confirm on a confirmed ticket returns 404/409. Our demo verified this for real: the second poll returned 404, a replayed confirm returned 404. The loop is closed.

The state machine has five states: pending → scanned → confirmed → (destroyed), pending → expired. Any transition not on this diagram is a bug. Draw the state machine before writing the endpoints — it prevents half of all scan-login bugs.

Runnable example: Node/Express ticket + polling demo

A complete, minimal, genuinely runnable implementation (verified end-to-end on Node: generate → poll pending → scan → confirm → one-time token pickup → replay 404). For production, swap the in-memory Map for Redis (multi-instance deploys) and the demo token for your JWT issuance logic.

// Run: npm i express && node qr-login-demo.js
// Open http://localhost:3000/ for the demo page; simulate the app with curl
const express = require('express');
const crypto = require('crypto');
const app = express();
app.use(express.json());

const TICKET_TTL_MS = 2 * 60 * 1000; // code expires in 2 minutes
const tickets = new Map(); // ticketId -> { status, createdAt, token }

function newTicket() {
  const id = crypto.randomBytes(16).toString('hex');
  tickets.set(id, { status: 'pending', createdAt: Date.now(), token: null });
  return id;
}
function getTicket(id) {
  const t = tickets.get(id);
  if (!t) return null;
  if (t.status === 'pending' && Date.now() - t.createdAt > TICKET_TTL_MS) {
    t.status = 'expired'; // lazy expiry: transition on lookup, no sweeper needed
  }
  return t;
}

// 1) Web: generate ticket (the QR code content is this URL)
app.post('/api/qr/ticket', (req, res) => {
  const id = newTicket();
  res.json({ ticketId: id, scanUrl: `https://example.com/scan?t=${id}`,
             expiresIn: TICKET_TTL_MS / 1000 });
});

// 2) Web: poll ticket status
app.get('/api/qr/ticket/:id', (req, res) => {
  const t = getTicket(req.params.id);
  if (!t) return res.status(404).json({ error: 'ticket not found' });
  const out = { status: t.status };
  if (t.status === 'confirmed') {
    out.token = t.token;            // token issued exactly once
    tickets.delete(req.params.id);  // single-use: destroyed on pickup
  }
  res.json(out);
});

// 3) App: scan (pending -> scanned)
app.post('/api/qr/scan/:id', (req, res) => {
  const t = getTicket(req.params.id);
  if (!t) return res.status(404).json({ error: 'ticket not found' });
  if (t.status !== 'pending') return res.status(409).json({ error: `ticket ${t.status}` });
  t.status = 'scanned';
  res.json({ ok: true, status: 'scanned' });
});

// 4) App: confirm login (scanned -> confirmed, token issued)
app.post('/api/qr/confirm/:id', (req, res) => {
  const t = getTicket(req.params.id);
  if (!t) return res.status(404).json({ error: 'ticket not found' });
  if (t.status !== 'scanned') return res.status(409).json({ error: 'must scan first' });
  t.token = 'tok_' + crypto.randomBytes(24).toString('hex'); // production: your JWT
  t.status = 'confirmed';
  res.json({ ok: true });
});

app.listen(3000, () => console.log('demo on http://localhost:3000/'));

The demo page renders the code in-browser with qrcodejs (CDN) and polls every 2 seconds. The verified curl sequence:

# generate ticket
T=$(curl -s -XPOST localhost:3000/api/qr/ticket | python3 -c "import sys,json;print(json.load(sys.stdin)['ticketId'])")
curl -s localhost:3000/api/qr/ticket/$T            # {"status":"pending"}
curl -s -XPOST localhost:3000/api/qr/scan/$T       # {"ok":true,"status":"scanned"}
curl -s -XPOST localhost:3000/api/qr/confirm/$T    # {"ok":true}
curl -s localhost:3000/api/qr/ticket/$T            # {"status":"confirmed","token":"tok_..."}
curl -s -o /dev/null -w "%{http_code}\n" localhost:3000/api/qr/ticket/$T  # 404 (single-use)
curl -s -o /dev/null -w "%{http_code}\n" -XPOST localhost:3000/api/qr/confirm/$T  # 404 (replay-proof)

Demo-to-production checklist: in-memory Map → Redis (with TTL so expiry cleans itself); authenticate the scan/confirm endpoints with the app's login state; show login context (device, IP, approximate location) on the confirm screen against social engineering; replace polling with WebSocket/SSE; everything over HTTPS — with enough ticketId entropy, no extra signing is needed.

Dynamic share codes and channel codes: the code as a traffic ledger

In sharing scenarios, the code always contains a short link, never the final destination URL. Something like https://yourapp.com/s/abc123, with the server 302-redirecting to the real landing page. Why the extra hop? Three reasons. First, replaceable targets — the code is already printed on posters; a landing-page redesign only changes the server-side mapping, no reprint. Second, parameter tracking — the short-link id is tied to a channel (which KOL, which event, which city), and each scan logs UA, IP, and time. Third, kill switch — when the campaign ends, retire the short link and show "campaign ended" instead of landing on a dead 404 page.

Channel "live codes" go one step further: one printed code whose backend target (support contact, group invite, landing page) can be swapped anytime — for expo banners or product packaging where one code stays valid for years while its content changes. Implementation is short links + editable target mapping + scan analytics. On analytics, dedupe: repeated scans from the same device/IP in a short window count as one UV, PV counted separately; and filter obvious test scans (like your own).

Minimum viable data model: a qr_links table (id, target URL, channel tag, status, created_at) and a qr_scans table (link_id, scanned_at, IP hash, UA, city). Early-stage vibe projects don't need BI — these two tables plus a daily GROUP BY query are your channel dashboard.

Redemption codes: coupons and tickets, one-code-one-use is the floor

Redemption codes carry the strictest security requirements. The threat model is concrete: users screenshot a coupon to eight friends, staff scan the same code twice, flaky networks cause duplicate submissions. One-code-one-use is built in three layers:

• Unforgeable code content: the code carries {couponId, nonce} with an HMAC signature from a server-side secret; verify the signature at redemption. Never put state like "already redeemed" inside the code — state always lives server-side.
• Atomic redemption: after signature verification, flip the voucher from unused to used inside a database transaction — only the successful flip counts. When two concurrent requests scan the same code, the atomicity of the state change guarantees exactly one wins. That's the core of replay protection — never "check then update."
• Offline redemption: ticket gates often have no network. The approach is pre-issuance: before the event, the server pushes each gate device a batch of signed, unused voucher ids (or a signed voucher pack); offline, the device verifies signatures against a local redeemed-set, then uploads redemption records for reconciliation once back online. The offline trade-off is that "one voucher used at gate A and gate B simultaneously" can't be blocked in real time — only events that accept this trade-off should go offline; high-value vouchers should require gates to stay online.

An easy trap: redemption codes as bare auto-increment ids with no signature. An attacker enumerating ids can mint valid vouchers at will. Code content must either carry a server-side signature or be a long-enough random string (128 bits) — pick one, never go bare.

Generation options: qrcode.js, segno, or a cloud API

• Frontend instant generation (qrcode.js / qrcodejs): davidshimjs's qrcodejs is the most-used pure-frontend library — dependency-free, one CDN include, ideal for "render the login code live on the page." It's old and lightly maintained, so complex needs (high error correction, custom styling) strain it — but for plain jump codes it's plenty.
• Backend batch generation (segno): Python's segno is currently the best-regarded QR library — clean API, adjustable error-correction levels, SVG/PNG output. The genuinely scannable cover QR of this article was generated with segno. Node backends can use the npm qrcode package for the same job.
• Cloud APIs: for when you'd rather not install graphics libraries server-side, billed per call. Confirm three things when choosing: HTTPS support, generation latency (the login page is a real-time flow — API latency adds directly to user wait), and the provider's data policy (whether code content gets logged).

The beautified-code and logo-embedding pitfalls

The QR standard (ISO/IEC 18004) defines four error-correction levels: L (~7%), M (~15%), Q (~25%), H (~30%). Embedding a logo means deliberately covering part of the code and relying on error correction to cover for it. So the iron rule: logo-bearing codes must use H-level error correction, the logo must cover no more than 15–20% of the code area, and must avoid the three finder patterns. Most "won't scan" beautified codes trace back to default M-level correction plus an oversized logo.

Two more field-tested notes: dark logo on light code is the safe zone; the reverse (light logo over dark code) craters recognition rates. On printed materials, don't go below 2×2 cm — phones can't even focus on smaller codes. After beautifying, test with two or three mainstream scanning apps; don't judge from the design mockup alone.

WeChat ecosystem notes: three constraints, stated as they are

China-market vibe projects can't avoid WeChat. Three constraints, stated honestly — get any of them wrong and launch day breaks:

1. Domains can be blocked anytime; appeals go through official channels. WeChat blocks domains or IPs behind "induced sharing" (share-to-win-red-packets, like-to-claim-coupon copy). Blocked pages show "this page has been stopped." The compliant playbook: use your own ICP-filed domain, keep copy away from induced-sharing phrasing, and give each business line its own domain (don't share one domain between a UGC forum and payments — one block kills both). After a block, appeal through the WeChat Official Accounts Platform. Don't believe any "anti-blocking technique" pitch — that's essentially gray-market talk.

2. In-WeChat H5 navigation is restricted. On iOS WeChat, tapping an app-download link gets intercepted with a "please open in browser" prompt; jumping to external apps must follow the WeChat Open Platform's sanctioned paths. The exact restrictions shift with WeChat versions — treat the WeChat Open Platform's latest documentation as authoritative, and test your redirect chain on real devices (one iOS, one Android) before launch, not just in devtools.

3. WeChat scan-login ≠ generic scan-login. If your app lives inside the WeChat ecosystem (Official Account / Mini Program), prefer the platform's official scan-login capability (website-application WeChat login on the Open Platform) over building your own ticket system inside a WeChat shell — the official flow handles authorization and unionId plumbing. Only the "own app + web" scenario from this article's demo needs a hand-rolled ticket system.

Pre-launch security checklist

• Login codes: 128-bit+ random tickets, 2-minute expiry, single-issue tokens, scan and confirm as two steps, login context shown on the confirm screen.
• Share codes: short links with a kill switch, deduped analytics, server-swappable target URLs.
• Redemption codes: signed content or long random strings, atomic redemption, reconciliation for offline scenarios.
• General: HTTPS end to end; QR content never directly embeds userIds, phone numbers, or other sensitive data; rate-limit generation endpoints (against mass code farming).

A QR code looks like a trivial "draw a picture" task; engineering-wise it's where identity, traffic, and benefits intersect. Get login wrong and it's a security incident; get sharing wrong and it's a data incident; get redemption wrong and it's a financial-loss incident. Follow the flow in this guide step by step, and at minimum you'll guarantee: the code scans, the numbers add up, and each voucher is used exactly once.