# Instagram Credential Pool Specification (`INSTAGRAM-CRED-POOL.md`) ## 1. Overview & Agency Context When onboarding agency client profiles ("nodes") to Muse (`muse.ai`), new accounts and certain unconfirmed email accounts encounter the post-OTP Age Verification gate (`/access/verification`). While credit-card verification is not suitable for autonomous multi-tenant operations, **Meta OAuth / Instagram Linking** is the highest-reliability verification route. Currently, the system uses a **Human-in-the-Loop** model: - An operator receives an authorization notification via Tailscale / email. - The operator signs into Instagram via a one-tap link from their mobile device or laptop. This specification details the future architecture for **Automated Instagram Credential Pooling** to remove human intervention entirely while strictly complying with the NetVM Ethics Charter (`https://start.muse-dev.online/ethics.html`). --- ## 2. Architecture & Design Principles ### 2.1 Isolation & Multi-Tenancy (Ethics Charter Compliant) - **1-to-1 Node Mapping**: Each client node (`node == agent == profile == API account`) maintains dedicated browser state, WireGuard netns isolation (`warp-`), and separate credentials. - **Dedicated IG Identities**: Instagram accounts in the pool are provisioned specifically for age-verification linking, never shared concurrently across different active client profiles. - **Encrypted Secret Storage**: Instagram credentials (username, password, 2FA TOTP secret, session cookies) are stored in an encrypted credential vault (e.g., `age`-encrypted `/etc/netvm/meta-credentials/store.age`), never committed in plain text to git or unencrypted markdown. ### 2.2 Pool States & Lifecycle ```mermaid stateDiagram-v2 [*] --> Available : Provisioned & Verified Available --> Assigned : Reserved for Node Onboarding Assigned --> Linking : Navigating Meta OAuth in netns Linking --> Linked : Age Gate Cleared on Muse Linking --> Cooloff : Checkpoint / Rate-limit Hit Cooloff --> Available : Cooldown Elapsed Linked --> InUse : Node Active in Fleet ``` - **`available`**: Account is verified, healthy, and not currently tied to any active Muse profile. - **`assigned`**: Temporarily reserved by `super cred` for onboarding node ``. - **`linking`**: Automated driver navigating the Meta Accounts Center flow inside the isolated namespace. - **`linked`**: Successfully bound to Muse account. - **`cooloff`**: Encountered challenge or cooldown; resting before re-qualification. ### 2.3 Meta Account Center Constraints & Edge Cases - **1-to-1 Linking Constraint**: Meta Accounts Center rejects linking if the target Instagram account is already associated with an existing Meta / Muse profile (`auth_flow=ig_linking` drops to `add_accounts` error page with `token` and `blob` parameters). - **Brand New Account Age Gate Limitation**: - Newly created Instagram accounts without a mature age/identity verification tier or age signal trigger Meta Accounts Center to disable the **"Confirm"** action (`aria-disabled="true"` on `/add_accounts/?flow=HATCH_AGE_VERIFICATION_IG_UPSELL`). - Meta Accounts Center uses Instagram accounts for age verification by checking that the linked Instagram profile itself has established age signals. A freshly minted account created minutes prior lacks this profile history, leaving the age verification unsatisfied. - **Agency Recommendation**: Pre-aged or verified Instagram identities in the pool with established age badges/profiles, or using established client identities, rather than accounts created in the immediate transaction. - **Session Bleed & OIDC Secondary Auth Trip (`auth.meta.com`)**: - When the link is opened in a browser that has existing Meta session cookies (e.g. from Facebook, Oculus, or another Meta account), selecting the new Instagram identity triggers a secondary OpenID Connect reconciliation trip (`https://auth.meta.com/?waterfall_id=...&redirect_uri=auth.meta.com/oidc/...&source_app_id=633385687760560`). - This prompts the user with **"Log in with your Meta account"** because the browser's ambient Meta session does not match the freshly authenticated Instagram identity. - If the user confirms with their cached personal Meta credentials, Meta attempts to merge/link across two disparate account graphs, creating an authorization loop or conflict. - **Resolution**: The link must strictly be opened in an **Incognito / Private window** or a completely clean browser profile with zero cached Meta/Facebook/Instagram cookies. - **In-Namespace Isolation**: Automated pool linking runs in Chromium directly inside `warp-` with an isolated profile, avoiding cross-session cookie collisions entirely. --- ## 3. Automated Driver Mechanics ### 3.1 Fetching Authorization Payload From the node's running browser tab sitting on `/access/verification`: ```javascript const res = await fetch('/api/hatch/age-confirmation/linking-web-auth?account_type=instagram', { headers: { 'Accept': 'application/json' } }).then(r => r.json()); // res.url: https://www.instagram.com/fxcal/auth/login/?app_id=...&next=... ``` ### 3.2 Automated Headless Linking Flow 1. Rather than opening a blocked popup, the driver navigates a dedicated worker tab inside the node's namespace (`warp-`) to `res.url`. 2. Inspects form fields: - Username: `input[name="username"]` - Password: `input[name="password"]` - Submit: `button[type="submit"]` 3. If 2FA prompt appears (`input[name="verificationCode"]` or email security code `auth_platform/codeentry`), handles code entry. 4. Handles Meta Accounts Center confirmation button: `"Confirm"`, `"Allow"`, or `"Continue as "`. 5. Upon redirect back to `https://muse.ai/`, checks for DOM chat markers (`"Connected"`, `"Chats"`, or URL `/`). 6. Updates node status in `ACCOUNTS.md` to `active`. ### 3.3 Singular Email Multi-Client Onboarding via RPA - **The Concept**: For agency onboarding efficiency, an RPA pipeline can provision and link accounts for multiple consenting client nodes backed by sub-addressing / plus-addressing (e.g., `agency+client_node@domain.com`) or a managed singular operator email inbox. - **RPA Capabilities**: - Automatically spins up the Instagram registration flow (submitting username, password, birthdate). - Listens to the incoming email stream via IMAP / Gmail API / maildrop to ingest the Instagram security code / OTP without human roundtrips. - Automatically submits the received code into the waiting Instagram code entry screen (`auth_platform/codeentry`). - Solves any automated challenges/captchas through authorized agency captcha-solving harnesses. - Passes the linked identity to Meta Accounts Center to clear the Muse age gate in seconds per node. --- ## 4. Pool CLI Surface (`super cred pool`) Planned CLI commands to be exposed once implemented: ```bash # Check status of the credential pool super cred pool status # Add a provisioned Instagram credential to the encrypted pool super cred pool add --username --password-file [--totp-secret ] # Trigger automated linking for a node in verification status super cred link-instagram --node --auto # Human-in-the-loop manual fallback (current default) super cred link-instagram --node --human ``` --- ## 5. Security & Risk Mitigations 1. **Anti-Fingerprinting**: All Meta navigation occurs strictly inside the client's assigned `warp-` network namespace to ensure consistent egress IP and prevent cross-node contamination. 2. **Audit Logging**: Every pool acquisition and release event is recorded with timestamps in `job-log.jsonl` with credentials scrubbed/redacted. 3. **Graceful Human Escalation**: If Meta serves an anti-automation challenge (e.g., CAPTCHA, SMS checkpoint), the automated pool driver immediately falls back to the Human-in-the-Loop Tailscale portal notification.