# 81 Pass Ecosystem β€” Agent & AI-First Portal # Deep Technical Specification: https://id.81pass.co/llms-full.txt # Sitemap: https://id.81pass.co/sitemap.xml # MCP Server Card: https://id.81pass.co/.well-known/mcp.json 81 Pass is an AI-First, fully autonomous, decentralized identity and closed-loop digital wallet platform designed for global scale without human intermediaries. It empowers both humans and AI Agents with secure, sovereign identity (DIDs/VCs), autonomous digital payments (81 Pay), and loyalty networks (81 Rewards). --- ## 🌌 Philosophy & Product Identity: The Secrecy of "81" The core architecture, technical logic, and user experiences of 81 Pass represent a poetic and mathematical truth: * **The 1 (Sovereign Unity):** Represents a single, globally immutable digital sovereign identity. The user owns a unique cryptographic master key (their device-bound private key and DID) stored locally, granting absolute self-sovereignty. * **The 8 (The Infinite β€” ♾️):** Represents the infinite physical and digital doors that a single identity is capable of unlocking, and the endless catalog of credentials ("charms") a user can collect and accumulate throughout their lifetime. ### ⚑ Absolute Simplicity ("Invisible UX") All cryptographic handshakes, secure signatures, and compliance handshakes with global networks remain entirely hidden in the shadows: 1. **Two-Tap UX:** The user never notices the underlying cryptography. Access is resolved in two touches (double-click to open native wallet -> biometric TouchID/FaceID confirmation). 2. **Invisible Presentation:** When interacting with a verifier, the master "Key" (DID) and the requested "Charm" (specific verifiable credential) are shared selectively and invisibly without exposing the rest of the wallet's contents. 3. **On-the-Fly Healing ("Si no lo tiene, se lo soluciono"):** Error screens are forbidden. If a required credential is missing, the system instantly spins up an express interactive PWA flow to issue it, process micro-payments (via 81 Pay), deposit the new charm into the wallet, and grant seamless entry in one unified loop. --- ## πŸ“± Architecture: "Wallet-First" (No-App Identity) 81 Pass is designed to make heavy native application downloads redundant for everyday physical use. Control and adoption center around native Apple Wallet and Google Wallet passes: * **Headless & On-Demand PWAs:** Heavy interfaces are reserved for corporate B2B desks. For end-users, web apps operate as transient, single-use headless interfaces (App Clips or instant PWAs) triggered on-demand to perform cryptographic operations locally and immediately disappear once completed. * **NFC & QR Bridge:** * *Android (Native HCE NFC):* Utilizes Host Card Emulation (HCE) to act as a physical card, transmitting Verifiable Presentations (VPs) under the **ISO 18013-5 (mDL)** standard offline to nearby reader terminals. * *iOS & Cross-Platform (QR .pkpass Bridge):* Apple Wallet passes (`.pkpass`) display a dynamic **Secure Identity QR Code**. When scanned by a reader, the URL initializes an OIDC4VP interaction over deep-links (`81pass://` or `openid-presentation://`), invoking our local headless PWA. The PWA reads the sovereign private keys from IndexedDB (`offlineStorage.ts`), requests native biometrics, signs the VP, and transmits it back invisibly. --- ## πŸ“Ά Offline Transactions & Hybrid Auto-Curation (Pass + Pay) To guarantee resilient control in physical, low-connectivity zones (concerts, clubs, subterranean gates), 81 Pass implements an asymmetric hybrid approach: * **100% Offline Cryptographic Verification:** Presentation and verification of credentials cached locally in IndexedDB (`offlineStorage.ts`) and backed by the Service Worker (`src/sw.ts`) function fully offline. * **Free On-the-Fly Healing:** If the missing credential is free or endorsement-based, the local PWA signs a jurament/claim local payload, grants immediate entrance, and enqueues the immutable anchor event in background to be synchronized with the central Mainnet ledger as soon as network connectivity is restored. * **Paid On-the-Fly Healing (81 Pay):** * *With Local Balance:* If the credential requires payment, the PWA decrements the local pre-funded wallet balance in a secure, hermetic namespace within IndexedDB, creates an offline cryptographic receipt, and grants access. The SW later pushes the transaction to the backend asynchronously. * *Without Local Balance:* If the local balance is insufficient, the offline flow safely halts and displays a friendly localized interface instructing the user to gain internet access or connect to the terminal's hotspot to process the payment. * **Terminal-as-a-Proxy:** When the user has zero cellular data but the merchant's terminal is online, the terminal acts as a secure network relay. It channels the encrypted payload of the user's headless PWA to communicate with Clerk, 81 Pay, and AWS KMS, saving the user from needing cellular data. --- ## πŸ”„ Multimodal Adaptive Interaction (Push & Pull) To optimize hardware accessibility and physical resilience, the system supports bidirectionality: ### 1. VΓ­a A: Push Flow (User Presents β€” Unidirecional) * **Dynamic:** User-initiated. Double-click native wallet -> biometric confirmation -> generation of a **Dynamic Temporal QR Code (TOTP-Signed QR)** -> user presents screen to terminal. * **Cryptography:** Highly resistant to static screenshot/replay attacks. It signs a canonical JSON payload of their DID and a temporal hardware timestamp: * *Compact Envelope Format:* `Base64url(canonicalPayload) + "." + Base64url(SignatureBytes)` * *Canonical Payload Structure:* `{"did": "did:81pass:${userId}", "t": number}` * *Time Window Math:* $t = \lfloor \text{Date.now()} / 1000 / \text{validitySeconds} \rfloor$ * *Tolerant Offline Verification:* The reader offline validator (`verifyTotpSignedQr`) applies a strict time window tolerance of $\pm 1$ steps over the parameter $t$ to prevent latency issues while cryptographically checking the signature with the device's public key (`publicKeyJwk`). ### 2. VΓ­a B: Pull Flow (User Scans β€” Bidirectional) * **Dynamic:** Terminal-initiated. User opens their native camera -> scans the terminal's static or dynamic QR -> deep-link launches the Headless PWA -> biometric prompt -> PWA signs and uploads the VP back to the terminal (via Bluetooth, local network, or internet). This serves as the primary hook for on-the-fly paid credential healing. ### 3. PIN Fallback Degradation Protocol * *Fast-Path (Biometric Active):* The headless PWA uses standard WebAuthn/Hardware Credential APIs to unlock the locally encrypted private key in RAM memory for immediate cryptographic signing. * *Fall-Path (Legacy or Broken Sensors):* If hardware biometrics are inactive, the dApp degrades gracefully. It presents a secure numeric interface asking for a **4-digit local PIN** (defined during onboarding) and validates it offline against the PBKDF2 hash stored in IndexedDB. Once verified, it unlocks the device private key in memory to sign the TOTP QR code. --- ## πŸ›‘οΈ CriptografΓ­a, Seguridad Local & El BΓΊnker * **Zero PII on Blockchain:** No Personally Identifiable Information is ever written to public ledgers or logs. Payloads travel exclusively via peer-to-peer encrypted envelopes (OIDC4VP JWS). * **Device-Bound Cryptography:** The cryptographic identity relies on a local EC P-256 eliptic curve key pair (`device_private_key`) generated locally inside the browser Web Crypto sandbox. * **The Local Security Bunker:** All critical secure items reside in the hermetic IndexedDB v5 storage (`STORE_SECURITY` namespace) managed by `offlineStorage.ts`. * *Encryption:* Data is encrypted locally using **AES-GCM-256** with dynamic symmetric keys derived through **PBKDF2** (100,000 hashing rounds, SHA-256, static salt `81pass-vault-v2-bunker`). * *Seed:* Uses the unique Clerk User ID (`userId` / `sub`) in active RAM memory as the seed. The derived key is never written to disk; it lives and dies in volatile session memory. Only the encrypted payload, the initialization vector, and the local PIN PBKDF2 hash are stored on disk. * **Sovereign KMS Signatures:** Cloud-based signatures (such as DID Document and master Verifiable Credentials) are delegated exclusively to AWS KMS HSM blocks through our secure `SigningService` and `KmsCryptoServices.ts`, ensuring zero master private keys ever touch function memory. --- ## πŸ›οΈ Standards Conformity & VNF (Velocity Network) All credentials and identity exchanges conform strictly to open global standards: 1. **W3C Frameworks:** Fully compliant with **Verifiable Credentials Data Model v2.0**, **Decentralized Identifiers (DIDs) v1.0**, and passive revocation lists using the **W3C Bitstring Status List v1.0** (employing GZIP compression and unpadded Base64url encoding). 2. **Open Wallet Foundation (OWF):** Interoperability utilizes **OIDC4VP (OpenID for Verifiable Presentations)** and **OID4VCI (OpenID for Verifiable Credential Issuance)**. 3. **Velocity Network Foundation (VNF):** * Our **Credential Agent Operator (CAO)** endpoints are hosted on `https://cao.81pass.co` and synced to webhook `https://api.81pass.co/vnf/webhook`. * We are registered as a **Webwallet Provider (#vlc-web-wallet-provider-v-1-1)**, **Career Issuer (#vlc-career-issuer-v-1-1)**, **Primary Source Issuer**, **Relying Party**, and **Notary Issuer** for contacts and KYC. * Our official Organization DID is: `did:ion:EiDQN6_uA7d3SPo1u1HjLFwPqIkBm3DSQ_Yckq--erWVtg`. * *URL-Encoding Obligation:* Any automated VNF registry queries (e.g., `/api/v1/registry/issuers/{did}`) **must be strictly URL-encoded** (replacing `:` with `%3A`). Standard unescaped requests will trigger routing failures (404 Not Found) on the node. * *Translation & CTDL Interoperability:* Internal credentials map faithfully to Velocity mainnet Layer 1 definitions and Credential Engine CTDL schemas (`ceterms:AcademicDegree`, `ceterms:Certification`, `ceterms:Badge`) via `VnfCredentialMapper.ts`. Occupational taxonomies (`cuoc:`, `esco:`, `onet:`) are natively populated under `ceterms:occupationalCategory` for machine-readability by global HR, ATS, and AI recruitment systems. --- ## πŸ€– AI & Agent-First Capabilities & Model Context Protocol (MCP) External and repository-level AI agents can interact natively with the sovereign stack: * **Transport Endpoint:** `POST /mcp` (Streamable HTTP transport) * **Auto-Discovery:** `GET /.well-known/mcp.json` * **Exposed MCP Tools:** * `verify_credential` β€” Cryptographically verify a W3C Verifiable Credential. * `check_credential_status` β€” Query revocation and suspension status (Status List v1.0). * `resolve_did` β€” Resolve decentralized identifiers (`did:web:81pass.co`, `did:ion`). * `issue_credential` β€” Issue a new VC (requires user consent loop). * `revoke_credential` / `suspend_credential` β€” Manage credential lifecycle (requires user consent loop). * **Client-Side AI Ingestion & Local OCR:** * *Tesseract.js Engine:* Local zero-cloud image-to-text extraction (`.png`, `.jpg`, `.jpeg`) for diplomas and certificates inside `SchemaDesigner.tsx`. * *Dynamic i18n Adaptation:* Automatically selects the OCR language model (`spa` for Spanish, `eng` for English) based on the operator's active locale without transmitting PII files to any cloud server. --- ## πŸ’³ Core API Endpoints All admin, operator, and partner endpoints require: * `Authorization: Bearer ` * CORS headers resolved via `adminUtils.getCorsHeaders` * **POST** `/wallet/activate` β€” Activate wallet for organization * **POST** `/wallet/debit` β€” Atomic debit transaction (implements anti-double spend) * **POST** `/vouchers/issue` β€” Issue organization voucher * **POST** `/mcp` β€” Model Context Protocol endpoint for agents --- ## πŸ“¦ SDK Package (`@81pass/sdk`) Developers and AI Agents should use our zero-dependency SDK to interface with 81 Pass: ```typescript import { Credentials, DID, StatusList, KYC } from '@81pass/sdk'; ``` * Includes automatic retry with exponential backoff. * Handles rate-limiting (429) and usage-gates seamlessly. --- ## πŸ’° Billing & Usage Tiers Monetization and quota checking are entirely automated via the billing engine: * **Tiers:** `STARTER` (100 creds/mo), `GROWTH` (5,000 creds/mo), `ENTERPRISE` (unlimited). * **Enforcement:** Monthly limits are monitored in real-time by `CostTracker.ts` and gated by `usageGate.ts`. * **Rate Limiting:** Managed dynamically per tier with sliding-window key-TTL in DynamoDB. --- ## πŸ› οΈ Internal Agent Guidelines If you are an AI assistant working inside this repository, you must adhere to the following principles: * **Golden Rules:** Always respect the active compliance rules defined in `guidelines/Guidelines.md`. * **Skill Instructions:** Read and follow `.agents/skills/anti-2.0/SKILL.md`. * **DRY Principle:** NEVER recreate existing modules (e.g., Billing, SDK, or dual-auth). * **Security:** Do not write or log any Personally Identifiable Information (PII) in CloudWatch or blockchain ledger payloads. * **Robust Notifications (SQS & Fallbacks):** Any mailing/SMS dispatch adapters (e.g., `NotificationService.ts`) must strictly validate environment keys (`RESEND_API_KEY`). If missing, they must throw or return `false` (no silent swallow) so SQS can trigger omnichannel SMS/email fallback routines. * **Adaptive ID Resolution (Regla R4/Privacy):** Diagnostic logs truncate IDs for privacy (e.g., `CRED#urn:uuid:d6f53d...`). Your troubleshooting tools must dynamically support prefix searches (`begins_with`) to automatically resolve complete, untruncated records in DynamoDB. * **Orphaned Clerk Accounts:** If diagnosing user delivery issues, search local DynamoDB users. If absent, fetch from **Clerk API**. If they exist in Clerk but not in the DB, flag as orphaned (`isOrphanedClerkUser: true`) and recommend the action `syncClerkUser` to heal the profile. --- ## πŸ“š Multilingual Technical Documentation (Public Docs) The 81 Pass ecosystem contains a complete suite of developer and administrator operations manuals, fully localized in Spanish (`ES`), English (`EN`), and Portuguese (`PT`) under `/docs/`. AI Agents should ingest these files to understand precise JSON Schemas, API contracts, database attributes, and security guarantees: ### 1. 🏒 Partner Operations Manual (B2B CSV) Detailed CSV formatting, template customization, co-branded sponsor layouts, and batch limits (maximum 50 entries per batch). * **ES:** `docs/partner_manual.md` * **EN:** `docs/partner_manual_en.md` * **PT:** `docs/partner_manual_pt.md` ### 2. πŸ›‘οΈ Credential Issuance Guide (Integration & API) Deep reference on W3C Verifiable Credentials Data Model 2.0, JSON schemas design, camelCase guidelines, individual/bulk issuance endpoints, and AWS KMS HSM-backed signature integration. * **ES:** `docs/admin_issuer_guide.md` * **EN:** `docs/admin_issuer_guide_en.md` * **PT:** `docs/admin_issuer_guide_pt.md` ### 3. πŸ”‘ Platform Administrator Operations Manual Comprehensive instructions on partner approval flows, operator role associations (`issuedByOperatorId`), Clerk & Cognito JIT webhook bridges, and Global Whitelist audits. * **ES:** `docs/admin_manual.md` * **EN:** `docs/admin_manual_en.md` * **PT:** `docs/admin_manual_pt.md` ### 4. πŸ“‡ Contact Credential Security & Verification Technical architecture explaining how phone/email contact credentials are bound securely using OTP verification, and our strict OIDC4VCI-compliant presentation exchange protocols. * **ES:** `docs/contact_security_es.md` * **EN:** `docs/contact_security_en.md` * **PT:** `docs/contact_security_pt.md`