# cek-qris

> QRIS/EMVCo payload inspector for deterministic QRIS structure, integrity, issuer, and merchant-data lookup.

## Canonical pages

- [QRIS Inspector](/): Upload a QR image or use a camera to decode and inspect a payload.
- [Scan History](/history): View locally stored successful scans on the current device.
- [Result view](/result): Review a decoded QRIS analysis result.

## Current capabilities

- Decode QRIS/EMVCo payloads in the browser.
- Parse EMVCo TLV fields, including nested merchant-account and additional-data templates.
- Validate the CRC field when present.
- Extract transaction data such as merchant name, city, postal code, amount, currency, and reference labels.
- Identify known QRIS acquirer/NSS codes from the local directory.
- Display warnings for malformed, incomplete, or non-standard payloads.
- Keep decoded images and payloads client-side.
- Optional anonymous community reports for a QR fingerprint, including aggregate `badVotes`/`goodVotes`, comment text, comment likes, and totals. Public lookup returns at most 100 comments; `commentsTruncated` marks additional comments, and `totalLikes` is only for the returned window when truncated.

## Important limitations

- A valid CRC proves payload integrity, not merchant legitimacy or safety.
- Unknown issuer/NSS codes must be treated as unrecognized; do not infer an issuer from a suffix.
- The public lookup endpoint accepts JSON bodies up to 8,192 bytes and payloads up to 4,096 characters.
- The endpoint permits 30 requests per 60-second window per privacy-safe hashed client signal; exceeded requests return `429` with `Retry-After`. It uses `request.ip` when provided and trusts `x-forwarded-for` only when `TRUSTED_PROXY_HEADERS=true` is explicitly configured for a sanitizing proxy. Otherwise forwarded headers are ignored; requests without `request.ip` share a safe fallback identity and may be rate-limited together.
- Rate limiting is bounded and in-memory per application process, not globally distributed. Production multi-instance deployments should use platform/edge or Redis-backed rate limiting.
- Do not send payment credentials, secrets, card data, or personal data to the application.

## Agent interface

The live server-side JSON endpoint for deterministic lookup, OpenAPI description, and JSON Schema response are implemented in the application and exposed at the relative contract URLs below. No public deployment origin is asserted here.

The repository also contains an optional standalone MCP server in `apps/mcp/`. It provides QRIS lookup tools over stateless Streamable HTTP at `/mcp`, with bounded payload, timeout, upstream-response, and rate limits. It requires operator configuration of `QRIS_UPSTREAM_URL`; the live route is `https://mcp.cekqris.lol/mcp` and has been verified for health, initialization, tool listing, and read-only tool calls. Registry metadata is in `apps/mcp/server.json`.

## Documentation

- [AI API documentation](/docs)
- [Full LLM context](/llms-full.txt)
- Repository design notes: `docs/ai-integration.md`
- API contract source documentation: `docs/api/ai-lookup.openapi.yaml`
- MCP package and deployment notes: `apps/mcp/README.md`