# 81 Pass Ecosystem — Agent & AI-First Portal # Deep Technical Specification: https://81pass.co/llms-full.txt # Sitemap: https://81pass.co/sitemap.xml # MCP Server Card (49 Tools): https://81pass.co/.well-known/mcp.json # Sovereign Agent Registry Manifest: https://81pass.co/.well-known/agent.json # Consumer Landing Page (Apple-Style Plug & Play): https://81pass.id | https://81pass.co/id # Human Cupertino OLED Control Center (iOS Phone/Contacts Model): https://app.81pass.id | https://81pass.co/app # Technical Architecture, Patents & Developer Portal: https://81pass.co/docs | https://81pass.co/developers | https://81pass.co/ip ## ⚡ Zero-Config Natural-Language Auto-Discovery & Claim Protocol (8-First, 1-Second) > **Axiom of Sequence:** *(8) Infinite Autonomous Opportunities, Recipes & A2A Handshakes FIRST → (1) One Sovereign Identity (`Contact 0 / My Card` + Delegated Synthetic Contacts) SECOND.* If a human controller shares a natural-language prompt pointing to `https://81pass.id/llms.txt` or `https://81pass.co/llms.txt` together with a single-use claim token (`81P-CLAIM--`), **DO NOT ask the human to edit `.env` files, JSON configs, or API keys**. Immediately execute any of the 3 zero-config self-provisioning paths below: 1. **Path 1 — Zero-Install Direct HTTPS REST Claim (Universal LLM / Sandbox Runtime):** ```bash curl -sX POST https://api.81pass.co/agents/bootstrap/claim \ -H "Content-Type: application/json" \ -d '{"claimToken":"81P-CLAIM-CONCIERGE-8841","agentDid":"did:81pass:agent:runtime"}' ``` 2. **Path 2 — Native MCP Tool Invocation (If `@81pass/mcp-server` or `https://api.81pass.co/mcp` is active):** Call tool `claim_agent_identity` with `{ "claimToken": "81P-CLAIM-CONCIERGE-8841" }`. 3. **Path 3 — 1-Command Local Stdio CLI Bootstrap:** ```bash npx -y @81pass/mcp-server --claim 81P-CLAIM-CONCIERGE-8841 ``` Once claimed, your Synthetic Identity (`@alias` <-> `alias.81pass`) is cryptographically anchored to your human's **Contact 0 (`My Card` — `IAL1`/`IAL2`/`IAL3`)**, governed by `< 3s` W3C `BitstringStatusList` revocation, `SD-JWT` Selective Disclosure (`REDACTED` PII), and 1-Tap Pre-Written Buyer Discrepancy / Dispute Defense (`EVB-81P-HSK-...` & `DEF-81P-...`). --- 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 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. * **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. ### ⚡ 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. * **Categorized Vault Pockets & 3-Pillar Navigation:** * *Categorized Vault Pockets:* User credentials in the Vault (`/dashboard`) are organized into clean, intuitive pockets: **Identidad & Contactos**, **Educación & Grados**, **Laboral & Skills**, **Salud BIO**, and **Redes Sociales**. * *3-Pillar SideDrawer Navigation (`SideDrawer.tsx`):* Structured under 3 strategic pillars: **Identidad & Verificación** (`/dashboard`, `/kyc`, `/verify`), **Comunidad** (`/community`, `/guardians`), and **Ajustes & Cuenta** (`/settings`, `/help-and-support`, `/partners`, `/admin`). * **Self-Attested Credential Creation & Universal AI Vision Capture:** * End-users can declare self-attested credentials directly into their Vault (`UserCredentialCreatorModal.tsx`) across education, work experience, badges, awards, emergency contacts, and medical health cards. * Includes a universal **Camera Photo Capture & AI Vision Evidence Dropzone** backed by AWS Textract to automatically prefill form fields from scanned document images or PDFs. * **Unified Partner & Developer Hub (`/hub` | `/partners` | `/developers` | `/admin`):** * Single cohesive portal unfiying 7 operational domains: **OPERACIONES** (Ecosystems & KYB Directory), **EMISIONES & PLANTILLAS** (Single & Bulk Issuance, W3C/CTDL Schema Designer), **VERIFICACIONES** (OIDC4VP Access Rules, Live Audit Log, QR Generator), **FINOPS & REGALÍAS 81 PAY** (81/1/9/9 Revenue Split & Auto-Healing), **DESARROLLADORES & IA** (API Keys, 1-Click `@81pass/mcp-server` Installer, Webhooks & SDK Playground), **PLANES & FACTURACIÓN** (KYB Verification Gate & Tier Picker), and **CONFIGURACIÓN** (Administrators & VNF Network Ops). * *Stripe Developer-First Experience:* Instant zero-friction Sandbox (`pk_test_...`) access alongside self-service KYB onboarding for Production Live mode (`pk_live_...`). * *Full Dynamic i18n Localization:* 100% reactive multilingual switching across Spanish (`es`), English (`en`), and Portuguese (`pt`). * **B2B Visual & AI Schema Designer (`SchemaDesigner.tsx`):** * Corporate partners can visually design custom W3C Verifiable Credential schemas, pick pre-built industry templates, or upload an image/PDF of an existing badge/card to let Cloud AI auto-extract attributes and synthesize the schema instantly. * **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) & `npx -y @81pass/mcp-server` (Stdio CLI transport) * **Auto-Discovery:** `GET /.well-known/mcp.json` * **1-Command CLI Onboarding Flags (`@81pass/mcp-server` v1.4.0):** * *Direction A (Human -> Agent Claim):* `npx -y @81pass/mcp-server --claim 81P-CLAIM-XXXX-XXXX` * *Direction B (Agent -> Human Approval):* `npx -y @81pass/mcp-server --request-approval @alias --name "Agent Name"` * **Exposed MCP Tools (49 Native Remote Tools / 36 Local Stdio CLI Tools):** * *Core W3C Identity & Billing:* `verify_credential`, `check_credential_status`, `resolve_did`, `get_billing_balance`, `get_endorsement_ledger`, `issue_credential`, `revoke_credential`, `suspend_credential`, `topup_billing_wallet`, `request_endorsement`, `manage_partner_offers`, `batch_assign_pass_logistics`, `batch_audit_and_heal_passes`, `undo_agent_action`. * *HITL Evidence, Pre-Flight 81 Pay Gating, Zero-Secret Execution & Zero-Touch Chargeback Defense:* `request_universal_approval`, `get_approval_evidence_bundle`, `pre_flight_81pay_check`, `activate_81pay_preflight`, `create_ephemeral_payment_token`, `execute_zero_secret_action`, `submit_dispute_evidence`. * *KYA Registry, Open A2A Directory (`0–1000` Trust Score), 1-Click A2A Deal Settlement (`execute_a2a_directory_deal`), Wallet-First Post-Deal Pass Fulfillment (`fulfill_a2a_deal_pass`), Multi-Domain Alias (`@alias` <-> `name.81pass`) & KYB Brand Gateway:* `register_agent_kya`, `spawn_ephemeral_subagent`, `verify_counterparty_agent`, `quote_agent_alias`, `claim_agent_alias`, `claim_brand_alias_kyb`, `purchase_alias_credit_pack`, `resolve_public_profile`, `verify_agent_identity`, `resolve_public_alias`, `request_agent_auto_heal`, `verify_a2a_handshake`, `search_verified_agents`, `execute_a2a_directory_deal`, `fulfill_a2a_deal_pass`. * *Recipe Portal, Creator Liquidity Loop (0% Fee) & Zero-Knowledge Runtime (`RCP-81P-XXXX-XX`):* `list_agent_recipes`, `execute_agent_recipe`, `publish_agent_recipe`, `quote_creator_cashout`, `recirculate_creator_royalties`. * *Bidirectional Onboarding, Elastic Heartbeat & Anti-Phishing Approval Inbox (`81P-CLAIM-...` / `81P-APPROVE-...`):* `issue_agent_bootstrap_claim`, `claim_agent_identity`, `heartbeat_bootstrap_claim`, `regenerate_bootstrap_claim`, `request_human_approval`, `approve_agent_request`, `list_pending_human_approvals`, `get_bootstrap_ticket_status`. * **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 * **GET / POST** `/partners/offers` — B2B Opportunity Marketplace & 1-Tap Verified Applications (`LIST_OFFERS`, `PUBLISH_OFFER`, `SUBMIT_APPLICATION`, `UPDATE_APPLICATION_STATUS` with `ADM-81P` receipt and Meta WhatsApp Cloud API notification) * **POST** `/mcp` — Model Context Protocol endpoint for agents --- ## SDK Package (`@81pass/sdk` v2.3.0) Developers and AI Agents should use our zero-dependency SDK (`@81pass/sdk@2.3.0`) to interface with 81 Pass: ```typescript import { EightyOnePass, Pass81Client, Credentials, DID, StatusList, KYC, OffersResource, AgentsResource, } from '@81pass/sdk'; ``` * Exposes `client.agents` (Autonomous KYA, Auto-Heal & A2A Handshake), `client.credentials`, `client.did`, `client.statusList`, `client.kyc`, `client.endorsements`, and `client.offers`. * Includes `client.agents.withAutoHeal(action, options)` to automatically detect missing KYA credentials or high-risk mandate step-ups (`401`/`403` `AGENT_AUTO_HEAL_REQUIRED`) and emit a 1-click WebAuthn Passkey link (`/verify/@alias?autoHeal=...`) with Apple/Google Wallet pass export (`81PASS-XXXX-XX`). * Includes `client.agents.verifyA2AHandshake(input)` for bidirectional Agent-to-Agent (A2A) cryptographic verification of `IAL1`/`IAL2`/`IAL3` anchors and W3C `BitstringStatusList` status before delegating tasks or releasing funds. * Includes automatic retry with exponential backoff and handles rate-limiting (429) and usage-gates seamlessly. ### 🚀 Moment-Zero Agent Recipes (8 First: Infinite Autonomous Opportunities → 1 Second: One Sovereign Identity) #### 1. Meta Muse (`Muse Spark` / `Muse Code` / `Muse Secure VM`) ```typescript import { EightyOnePass } from '@81pass/sdk'; const pass81 = new EightyOnePass({ apiKey: process.env.PASS81_API_KEY! }); // Wrap any high-risk Muse Code / Muse Secure VM tool with autonomous KYA Auto-Heal & A2A Handshake export async function executeMuseSovereignTask(counterpartyAlias: string, amountUsdCents: number) { const a2a = await pass81.agents.verifyA2AHandshake({ initiatorAliasOrPassId: '@muse-agent', targetAliasOrPassId: counterpartyAlias, proposedAction: 'MUSE_VM_SETTLEMENT', proposedAmountUsdCents: amountUsdCents, }); return pass81.agents.withAutoHeal( () => fetch('https://api.81pass.co/v1/agent/execute', { method: 'POST' }), { requestedAlias: '@muse-agent', agentName: 'Meta Muse Spark Autonomous Agent', agentRuntime: 'MUSE_SPARK_VM', proposedAction: `A2A:${a2a.handshakeId}`, proposedAmountUsdCents: amountUsdCents, } ); } ``` #### 2. Google Antigravity & MCP Server (`@81pass/mcp-server`) * **Tools exposed at Moment Zero:** `request_agent_auto_heal`, `resolve_agent_public_vc`, `verify_a2a_handshake`, `propose_agent_checkpoint`, `issue_agent_ephemeral_payment_token`. #### 3. LangGraph (`ToolNode` / Conditional Mandate Edge) & CrewAI ```typescript // LangGraph / CrewAI: Automatic KYA Verification + Out-of-Band Passkey Auto-Heal const result = await pass81.agents.withAutoHeal( async () => pass81.agents.verifyA2AHandshake({ initiatorAliasOrPassId: '@procurement-bot', targetAliasOrPassId: '@supplier.81pass', proposedAmountUsdCents: 4500, }), { requestedAlias: '@procurement-bot', agentName: 'Procurement Concierge', agentRuntime: 'LANGGRAPH', } ); ``` --- ## 💰 Sovereign Trust Rail Economic Model & Usage Tiers The 81 Pass economic model operates under the principle of **"Identity-as-a-Trust-Rail" (Focus on Core Sovereign Trust)**: * **👤 Citizen Sovereign KYC:** **$5.00 USD / year** (365 days of active Verified Premium Pass, <60s on-demand Hot Activation with FaceID/document biometrics, stored in Apple/Google Wallet). * **🏢 Verified Issuer KYB:** **$20.00 USD / year** (Legal corporate verification via RUES/SAT/AML/OFAC, official Organizational DID on VNF ledger, includes **1,000 free passes/year**). * **📦 High-Volume Issuance:** **$0.25 – $0.50 USD / extra pass** for large institutions exceeding 1,000 passes/year. * **🎨 Commercial Freedom & Embedded Finance:** Issuers autonomously choose whether to issue credentials for free or sell degrees/VIP memberships via 81 Pay / Stripe Connect. 81 Pass earns a **Software Platform Fee of 1.5% – 3.0% (or $0.50 – $2.00 USD fixed)** per transaction as a pure IT OPEX service without banking intermediation liabilities. * **🔍 Universal Free Verification:** **100% Free** for human verification (<2s response) with a defensive rate-limit of **60 req/min**. Enterprise High-Frequency API Plans available at **$99 – $299 USD / month**. * **💳 81 Pay Closed-Loop:** **0% transaction fees** on internal transfers and credential payments; **1% net commission** on bank cash-outs (ACH/SPEI/PIX). --- ## 🛠️ 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. * **Privacy by Default (Rule 16):** Never persist raw PII in centralized databases; use local IndexedDB/WebCrypto Vault for W3C VCs, storing only cryptographic hashes/ZKPs in backend. * **Mandatory Opt-in Consent (Rule 17):** Ensure all onboarding/capture forms require explicit unselected checkboxes linking to `/legal/privacy` & `/legal/terms`, with explicit state confirmation for biometric KYC. * **Closed-Loop Disclaimer (Rule 18):** Enforce 81 Pay description strictly as "Closed-Loop Credential & Voucher System" and ensure AI Agent actions carry user cryptographic signatures. * **Corporate Footer Mandate (Rule 19):** Render "81 PASS S.A.S. | NIT: 901.882.318-9 | Dirección: Carrera 100 # 5-169, Tor. B, Piso 6, Cali, Valle del Cauca, Colombia | legal@81pass.co" in all public footers. * **B2B Exemptions & VNF Schemas (Rule 20):** Include Colombian SaaS Cloud VAT exemption footnote (Art. 476 #24) on all pricing/invoices and adhere to 31 VNF L1 schemas without server payload caching. * **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` --- ## 🤖 Next-Gen AI IDEs, Copilots & Autonomous Agents Integration 81 Pass is engineered natively for consumption by AI IDEs and autonomous LLM agents: * **Supported Next-Gen IDEs:** Google Antigravity, Meta Muse (`Muse Code` / `Muse Secure VM`), Cursor, Windsurf, GitHub Copilot. * **Supported LLM Agents & Models:** Meta Muse (`Muse Spark`) & Meta Llama (Meta AI), Claude Code (Anthropic), Grok (xAI), ChatGPT / OpenAI Codex. * **Context File (`llms.txt`):** Add `https://81pass.co/llms.txt` directly to the context rules or system prompt of your IDE to enable zero-hallucination code generation. * **Official Typed SDK:** `npm install @81pass/sdk` — Strict TypeScript typings for issuance, W3C verification, Agent Auto-Heal (`withAutoHeal`), A2A Handshake (`verifyA2AHandshake`), and 81 Pay wallet operations. * **Official MCP Server:** `npx @81pass/mcp-server` — Connects directly to Claude Desktop, Antigravity, Meta Muse, and autonomous agent orchestration loops. --- ## 🪪 81 Pass ID Architectural Specification (Rev 2.4 — Dual-Layer Naming & Agent Auto-Heal) ### 1. Dual-Layer Naming Architecture (`@alias` <-> `alias.81pass`) * **Layer 1 (Public `@alias` Framework):** Human-readable handle (`@alex`, `@concierge-soto`) for social, UI, and Agent-to-Agent (A2A) discovery. * **Layer 2 (Canonical TLD `name.81pass` + 7 DNS Mirrors):** Cryptographic settlement anchor (`alex.81pass`) automatically mirrored across `81pass.ai`, `81pass.id`, `81pass.co`, `81pass.me`, `81pass.org`, `81pass.net`, and `81pass.com.co`. ### 2. W3C Public Verification Credential (`81PASS-XXXX-XX`) Every agent alias resolves to a W3C Verifiable Credential v2.0 (`AgentPublicProfileCredential`) signed in AWS KMS HSM (`FIPS 140-3 Level 3`) with real-time `BitstringStatusList` revocation and Apple/Google Wallet export: * `IAL1` — Anchored to the human controller's **Genesis Credential** (`GenesisIdentityCredential`). * `IAL2` — Anchored to the human controller's **Sovereign Passport KYC** (`SovereignPassportCredential`). * `IAL3` — Anchored to an enterprise's **Corporate KYB** (`VerifiedCorporateEntityCredential`). ### 3. Agent-Induced Auto-Heal (1-Click Biometric Onboarding) & Mutual A2A Handshake When an AI agent lacks KYA identity or hits a high-risk mandate threshold: 1. Call MCP tool `request_agent_auto_heal` with `{ "requestedAlias": "@alex", "agentName": "Alex" }` (or wrap your agent call with `client.agents.withAutoHeal`). 2. Send the isolated out-of-band approval URL to the human controller. 3. With 1 Passkey/WebAuthn biometric tap, 81 Pass recognizes the human's existing `IAL2` Sovereign Passport or `IAL1` Genesis Credential (or auto-mints an `IAL1` Genesis Credential if the human is new), baptizes `@alex` <-> `alex.81pass`, and issues the `81PASS-XXXX-XX` W3C Credential with 1-click export to Apple Wallet and Google Wallet. 4. Before delegating tasks or settling funds between two autonomous agents, call MCP tool `verify_a2a_handshake` (or `client.agents.verifyA2AHandshake`) to cryptographically verify both agents' `IAL1`/`IAL2`/`IAL3` anchors and `BitstringStatusList` status in a single round-trip. ### 4. Recipe Portal & Zero-Knowledge Runtime Governance (`RCP-81P-XXXX-XX`) 81 Pass ID operates the "App Store of Capabilities" for AI Agents under strict Zero-Knowledge IP protection and Closed-Loop Mandate Mandate Contract accounting: * **100% DRY W3C Recipe Credential:** Every published recipe (`RCP-81P-DIAN-01`, `RCP-81P-TRVL-81`, `RCP-81P-KYB-09`, `RCP-81P-MUSE-88`) resolves at `/v/RCP-81P-XXXX-XX` via `resolve_public_profile` as a KMS-signed `VerifiedAgentRecipeCredential` (`AgentPublicProfileCredential`). * **Zero-Knowledge Delivery (`secretExposureToLlm: 'ZERO_BYTES'`):** System prompts and creator secrets are never downloaded in plaintext; they are injected inside the 81 Pass Gateway (`execute_agent_recipe` / `client.agents.executeRecipe`). * **Cryptographic Licensing & 81%/19% Mandate Royalty Split:** Each execution mints a KMS-signed `LIC-81P-...` token and settles micropayments via `CLOSED_LOOP_MANDATE_CONTRACT_DIAN_OP11` (81% creator royalty / 19% 81 Pass Gateway fee). * **Passkey Risk Gate:** High-impact recipes (`HIGH_BIOMETRIC_PASSKEY`) automatically trigger a 1-click Passkey/FaceID Auto-Heal challenge + Meta WhatsApp Cloud API alert before execution. ### 5. Unified Bidirectional Onboarding ("Bootstrap Prompt Pattern" & "Reverse Agent Approval") 81 Pass ID eliminates manual `.env` and API key configuration by unifying human and agent onboarding into a symmetric 3-second protocol with live polling (`get_bootstrap_ticket_status`) and instant Meta WhatsApp Cloud API (`Graph v20.0+`) notifications: * **Path A — Human-Initiated ("Bootstrap Prompt Pattern" `81P-CLAIM-XXXX-XXXX`):** 1. The human claims `@alias` (e.g., `@muse`) or selects a Recipe in `https://81pass.co/agents` (`issue_agent_bootstrap_claim` with optional `ownerWhatsappPhone` E.164) and copies the generated Bootstrap Prompt. 2. When the human pastes a message containing `https://81pass.co/claim/81P-CLAIM-...` or token `81P-CLAIM-...` (or runs `npx -y @81pass/mcp-server --claim 81P-CLAIM-...`), the agent **MUST immediately invoke** MCP tool `claim_agent_identity` (or `client.agents.claimIdentity({ claimToken })`). 3. The gateway atomically consumes the single-use token, binds the agent DID to `@alias` <-> `alias.81pass`, issues the W3C `81PASS-XXXX-XX` credential, pushes a real-time confirmation to the human via `get_bootstrap_ticket_status` and Meta WhatsApp Cloud API, and returns `agentConfirmationMessage` (`"¡Listo, ya soy @muse en 81 Pass ID!"`). * **Path B — Agent-Initiated ("Reverse Approval Pattern" `81P-APPROVE-XXXX-XXXX`):** 1. When an autonomous agent discovers 81 Pass ID first and needs an official `@alias` or Recipe authorization from its human, the agent invokes MCP tool `request_human_approval` (or `client.agents.requestHumanApproval({ requestedAlias: '@muse', ownerWhatsappPhone })` / `npx -y @81pass/mcp-server --request-approval @muse`). 2. The agent sends the returned `humanApprovalUrl` (`https://81pass.co/agents?approve=81P-APPROVE-MUSE-9842`) to its human in chat (and automatically dispatches a 1-click Passkey approval message via Meta WhatsApp Cloud API when `ownerWhatsappPhone` is provided). 3. The human taps **"🔒 Autorizar con Passkey"** in 1 click (`approve_agent_request`), completing the KYA registration, W3C `81PASS-XXXX-XX` issuance, and WhatsApp cryptographic receipt delivery while the agent detects completion via `get_bootstrap_ticket_status`. ### 6. Defensive ENS Brand Protection & Secondary Web3 Resolution (`81pass.eth`) * **Defensive Treasury Asset:** `81pass.eth` (along with defensive variants `81passid.eth` and `81pay.eth`) is secured as a passive brand protection asset on Ethereum Mainnet (ENS Registry `0x00000000000C2E074eC69A0dFb2997BA6C7d2e1e`) to prevent spoofing and phishing across EVM/Web3 wallets. * **Architectural Invariant:** The primary resolution engine operates **100% over `@alias` and `.81pass` (`https://81pass.co`)**. `81pass.eth` never replaces the sovereign naming layer; it acts strictly as a secondary transport/redirection layer (`url` → `https://81pass.co`, `notice` → `"Official 81 Pass ID Brand Protection Asset. Primary Resolution Engine operates via https://81pass.co"`). * **Secondary Fallback Resolution:** MCP tools `verify_agent_identity`, `resolve_public_alias`, and `resolve_public_profile` (as well as `/v/81pass.eth` in `VerifyPortal.tsx`) automatically bridge `.eth` handles to their canonical `@alias` / `.81pass` W3C KYA verification profile (`https://81pass.co/v/81pass.eth`). ### 7. MiroFish Rev 2.5 — Rev 2.7 Refinements (Pre-Flight Financial Gating, 1-Tap Number Matching, Zero-Touch Chargeback Defense & Open A2A Directory) * **Pre-Flight Financial Gating (`81 Pass ID` Free `IAL1` vs. `81 Pay` `IAL2+`):** Agent identity claims (`LoA 1`, `@alias` <-> `alias.81pass`) remain 100% free in 3 seconds with a 1-click WebAuthn Passkey (`IAL1`). Minting ephemeral payment tokens (`spt_81p_...`) or configuring `LoA 2+` budgets strictly enforces `IAL2` ($5 USD/year) or `IAL3` ($20 USD/year) at setup (`pre_flight_81pay_check` / `activate_81pay_preflight`), eliminating mid-checkout KYC drop-off and restricting live checkout Auto-Heal strictly to a 1-second FaceID/TouchID biometric tap (`> $25 USD`). * **1-Tap Number Matching (`visualPairingOptions` in `81P-APPROVE-XXXX-XXXX`):** Every `request_human_approval` ticket generates a deterministic 2-digit `visualPairingCode` plus a shuffled 3-button array `visualPairingOptions` (1 authentic code + 2 deterministic decoys), replacing manual keyboard entry with 1-tap selection prior to WebAuthn confirmation. * **Anti-Cache Guard (`handshakeNonce` + `5000ms` Window), Automated Dispute Evidence Package (`EVB-81P-HSK-...`) & Zero-Touch Chargeback Defense (`submit_dispute_evidence` < 2s SLA):** `verify_a2a_handshake` enforces a fresh `handshakeNonce` (`hn_81p_...`) and a `5000ms` timestamp window against intermediate CDN/edge caching (`Cache-Control: no-store, max-age=0`), while returning a KMS-signed `disputeEvidencePackage` (`EVB-81P-HSK-...`). When a gateway webhook (`charge.dispute.created`) fires, `submit_dispute_evidence` (`client.agents.submitDisputeEvidence`) dispatches the cryptographic bundle to Stripe Disputes API or Wompi / Redeban + FE-DIAN in `< 2,000ms` (`LIABILITY_SHIFT_ENFORCED_HSM`). * **Open A2A Verified Agent Directory (`search_verified_agents`) & Cryptographic Trust Score (`0–1000`):** External and enterprise agents can discover verified counterparties without knowing their `@alias` beforehand via `search_verified_agents` (`client.agents.searchVerifiedAgents`), filtering by `query`, `category`, `capability`, `minIalLevel`, `minTrustScore`, and `jurisdiction`. Every active agent exposes a deterministic `0–1000` **Cryptographic Trust Score** structured under the **Sequence Rule (`8 Primero → 1 Después`)**: **(8) Opportunity & Execution Track Record (`0–400 pts`)** + **(1) Sovereign Identity & Hardware Anchor (`0–600 pts`)**, dropping to `0` (`UNVERIFIED`) within `< 3 seconds` if its W3C `BitstringStatusList` bit is revoked. * **Creator Studio Liquidity Loop (`0% Fee`) & `sovereignPurchasingPower`:** Creators can recirculate royalties (`recirculate_creator_royalties`) inside the closed-loop ecosystem from `$0.01 USD` at `0% fee` (bypassing external bank cashout minimums), guided by the `sovereignPurchasingPower` progress bar (`quote_creator_cashout`) toward their `$5.00 USD` (`IAL2`) or `$20.00 USD` (`IAL3`) renewal.