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

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:

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:

# 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.