box/INSTAGRAM-CRED-POOL.md

# 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-<node>`), 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 `<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.
- **Dormant / "Ghost" Account Lockout Mode (`/access` Hard Exclusion & Resolution)**:
  - An account that has chronological calendar age (e.g. created ~5 months ago) but has **zero posts, zero regular engagement, and no established social graph** can fail Meta's automated audience eligibility check completely upon Muse onboarding, routing to `https://muse.ai/access` (*"Muse isn't available to all audiences"*).
  - Attempting automated sign-in on these low-reputation identities from datacenter/VPN egress IPs triggers Google reCAPTCHA Enterprise checkpoints.
  - **The "Add Again" Two-Step Handoff Resolution**:
    1. Sign in to `https://accountscenter.meta.com/` using the cached Meta Account session.
    2. Add Account -> complete Instagram sign-on & OTP.
    3. Returning to Meta Accounts Center, click **Add Instagram a second time** (`ADD AGAIN`).
    4. Meta generates the OAuth handoff URL:
       `https://www.instagram.com/fxcal/auth/login/?app_id=633385687760560&etoken=...&next=https%3A%2F%2Faccountscenter.meta.com%2Fadd%2F%3Fauth_flow%3Dig_linking%26background_page%3D%252Fmanage&flow=igcalcomet&entry_point=frl_web_settings&initiator_fbid=...`
    5. Prompt displays: `"[<instagram_handle>] Meta needs to access info from your Instagram account. [Continue] [Not You?]"`.
    6. Clicking **[Continue]** redirects to Accounts Center with query parameters `token` and `blob` (`/add/?auth_flow=ig_linking&token=...&blob=...`).
    7. Clicking **[Confirm]** completes the account merge, prompts Meta's confirmation email (*"Did you just move your profiles into the same Meta Account?"*), and **instantly clears the `/access` block on Muse**, transitioning the session into active chat.
- **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-<node>` 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-<node>`) 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 <username>"`.
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 <user> --password-file <path> [--totp-secret <secret>]

# Trigger automated linking for a node in verification status
super cred link-instagram --node <node> --auto

# Human-in-the-loop manual fallback (current default)
super cred link-instagram --node <node> --human
```

---

## 5. Security & Risk Mitigations

1. **Anti-Fingerprinting**: All Meta navigation occurs strictly inside the client's assigned `warp-<node>` 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.