Tailscale OAuth Bridge

Standardize the multi-account auth flow on PC for services running on phone, when redirect_uri is hard-locked as loopback (for example http://localhost:1455/auth/callback).

Scope

• In-scope: use Tailscale + SSH local forwarding to handle OAuth loopback callback from PC to Android phone.
• Out-of-scope: general network tunneling outside the OAuth callback bridge problem.

SOP

1. Determine whether the request is within the skill scope.
2. Execute the skill's main workflow/instructions in safe order.
3. Check results, state validation, and next steps.

Indexed sub-skill references (source map)

• @[SKILL.md#L1-L95] Standard frontmatter (name, description).
• @[SKILL.md#L6-L95] Tailscale OAuth Bridge.
• @[SKILL.md#L10-L95] When to use.
• @[SKILL.md#L15-L95] Goals.
• @[SKILL.md#L20-L95] Preconditions.
• @[SKILL.md#L27-L95] Standard commands.
• @[SKILL.md#L48-L95] Standard auth process.
• @[SKILL.md#L55-L95] Quick troubleshooting.
• @[SKILL.md#L69-L95] Hardening.

When to use

• OAuth URL has redirect_uri=http://localhost:<port>/....
• Service actually runs on phone (Android), but login is needed from browser on PC.
• Cannot switch to a custom domain due to invalid_redirect_uri/hard whitelist.

Goals

• Browser on PC can still log in normally.
• localhost callback on PC is safely forwarded to phone via tailnet.
• Do not expose ports to the Internet.

Preconditions

1. PC and phone are both logged into the same Tailscale tailnet.
2. Phone has an SSH server (Termux sshd on port 8022 is recommended).
3. Service on phone is handling the callback flow:
   • callback listener: 127.0.0.1:1455
   • codex callback/backend: 127.0.0.1:8317

Standard commands

On phone (Termux)

pkg update -y && pkg install -y openssh
passwd
sshd
whoami

On PC

tailscale status
ssh -p 8022 -N \
  -L 1455:127.0.0.1:1455 \
  -L 8317:127.0.0.1:8317 \
  <TERMUX_USER>@<PHONE_TAILSCALE_IP>

Keep the SSH tunnel alive during the entire auth process.

Standard auth process

1. Initialize auth flow on phone to generate OAuth URL.
2. Copy URL to PC, open in browser/Google profile that needs adding account.
3. OpenAI redirects to localhost:1455 (PC) -> tunnel forwards to phone.
4. If there is a 302 to http://127.0.0.1:8317/codex/callback, browser can still follow because of tunnel 8317.
5. Verify after each account: call http://127.0.0.1:8317/v1/models and check auth success logs.

Quick troubleshooting

ssh: connect ... port 22: Connection refused

• Phone doesn't have SSH server on 22 yet (normal with Termux).
• Use -p 8022 and ensure sshd is running.

Browser shows 127.0.0.1 refused

• Callback listener on phone is not open at test time.
• Initialize auth flow first, then open URL.

302 -> 127.0.0.1:8317 but fails

• Missing port 8317 forwarding on PC.
• Add -L 8317:127.0.0.1:8317.

Hardening

• Allow only Boss's PC device in tailnet ACL.
• Use SSH key when stable, avoid long-term password auth.
• End auth session: close tunnel immediately.
• Do not use Funnel/public expose for this flow.

Trigger Rules

• Positive: Activate when user request matches tailscale-oauth-bridge by description: Use Tailscale + SSH local forwarding to handle OAuth loopback callback (localhost) from PC to Android phone when authenticating Codex/cli-proxy-api.
• Negative: Do not activate for out-of-scope requests or when this skill's workflow/expertise is not needed.
• Escalation: If there is external action/network write or sensitive operations, add an approval checkpoint before execution.

Error Handling

• If loopback callback still cannot reach PC: verify correct local forward/port map before suspecting OAuth provider.
• If Tailscale IP/route cannot reach phone: split triage into tailnet connectivity and SSH tunnel instead of debugging the whole stack at once.
• If auth flow is complete: remind to close tunnel and clear temporary session to reduce exposure.

Output Contract

• Deliverable: result aligned with tailscale-oauth-bridge objective; clearly state artifact/path/steps performed (if any).
• Validation: report PASS/FAIL status with key checks run.
• Failure mode: when failing, state root cause + proposed remediation.